Guia

Conceitos

As ideias que se aplicam a todo tipo de gráfico — como os dados são estruturados, como os eixos escalam, como tematizar, o sistema de eventos, exportação, responsividade, acessibilidade e animação.

Formatos de dados

Array de números — cada valor é um y; x auto-incrementa de 0 (ou pointStart).

series: [{ data: [10, 20, 30, 40, 50] }]
// points: (0,10), (1,20), (2,30), (3,40), (4,50)

Tuplas — [x, y], ou [x, y, z] para bolhas (z = raio), ou [name, y] para pizza/dados de categoria.

data: [[0, 10], [5, 20], [12, 35]]          // [x, y]
data: [[0, 10, 50], [5, 20, 120]]          // [x, y, z] bubble
data: [['Apples', 5], ['Oranges', 3]]      // [name, y]

Objeto (PointOptions) — o mais flexível; cada ponto carrega propriedades nomeadas.

data: [{
  x: 0, y: 10, name: 'First', color: '#d62728', id: 'point-0',
  drilldown: 'details-0',
  marker: { symbol: 'diamond', radius: 6 },
  dataLabels: { enabled: true, format: '{y} units' },
  custom: { department: 'Sales', quarter: 'Q1' }
}]

Nulls quebram a linha por padrão; connectNulls: true preenche lacunas. pointStart / pointInterval mapeiam um array flat em um eixo-x (ótimo para datetime). keys remapeia colunas de tupla.

{ data: [10, 20, null, 40], connectNulls: true }
{ data: [29.9, 71.5, 106.4], pointStart: Date.UTC(2024,0,1), pointInterval: 86400000 }
{ keys: ['x', 'y', 'color'], data: [[0, 10, '#d62728'], [1, 25, '#2ca02c']] }

Formatos especiais por tipo

Tipo	Formato
`pie`	{ name, y }
`candlestick / ohlc`	{ x, open, high, low, close }
`boxplot`	{ low, q1, median, q3, high }
`sankey`	{ from, to, weight }
`heatmap`	{ x, y, value }
`treemap / sunburst`	{ id, parent, name, value }
`networkgraph`	[nodeA, nodeB] pairs
`gauge`	[{ y: value }]

Sistema de eixos

Cada eixo usa um de quatro tipos de escala; o tipo é inferido dos dados ou definido via xAxis.type/yAxis.type.

Tipo	Descrição
`linear`	Escala numérica contínua.
`logarithmic`	Log-base-10 para intervalos exponenciais.
`datetime`	Escala de tempo com formatação automática inteligente de ticks de data.
`category`	Banda discreta por rótulo de categoria.

Definir xAxis.categories faz automaticamente o eixo uma categoria.

Cálculo do domínio (aplicado em ordem)

minPadding / maxPadding — espaço em branco proporcional nas bordas (0.01 linear, 0 categoria).
softMin / softMax — estende apenas se os dados ainda não alcançarem.
floor / ceiling — limites rígidos que o domínio não pode cruzar (mas pode ser menor).
min / max — substituições rígidas explícitas.
startOnTick / endOnTick — arredonda para fora para o tick mais próximo.

Múltiplos eixos

yAxis: [
  { title: { text: 'Temperature (°C)' } },
  { title: { text: 'Rainfall (mm)' }, opposite: true }
],
series: [
  { name: 'Temperature', type: 'line',   yAxis: 0, data: [7,12,18,24] },
  { name: 'Rainfall',    type: 'column', yAxis: 1, data: [49,71,106,129] }
]

Estilo e tematização

Cores de série vêm de uma paleta — defina globalmente com setOptions({ colors }) ou por gráfico. 20 paletas vêm integradas (veja API).

KatuCharts.setOptions({ colors: ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728'] });
KatuCharts.chart(container, { colors: ['#264653', '#2a9d8f', '#e9c46a'], series: [/* … */] });

Estilos de traço

dashStyle	stroke-dasharray
`Solid`	none
`Dash`	8,6
`Dot`	2,6
`DashDot`	8,6,2,6
`ShortDash / ShortDot`	6,2 / 2,2
`ShortDashDot / ShortDashDotDot`	6,2,2,2 / 6,2,2,2,2,2
`LongDash / LongDashDot / LongDashDotDot`	16,6 / 16,6,2,6 / 16,6,2,6,2,6

Hooks de classe CSS

Cada elemento recebe uma classe previsível para estilo externo — ex: .katucharts-background, .katucharts-title, .katucharts-axis, .katucharts-grid-line, .katucharts-series, .katucharts-point, .katucharts-legend-item, .katucharts-tooltip, .katucharts-data-label, .katucharts-crosshair, .katucharts-credits, .katucharts-export-button.

Interatividade

chart: {
  zoomType: 'xy',                       // 'x' | 'y' | 'xy'
  panning: { enabled: true, type: 'xy' },
  panKey: 'shift',
  zooming: {
    mouseWheel: { enabled: true, sensitivity: 1.1 },
    resetButton: { position: { align: 'right', y: 10 } }
  }
}

Drilldown — clique um ponto com um id drilldown para descer em uma sub-série; um botão Voltar aparece. Os níveis podem se aninhar.
Crosshair — xAxis.crosshair: { width, color, dashStyle, snap } rastreia o ponteiro.
Seleção de ponto — allowPointSelect: true com um estilo states.select e point.events.select/unselect.
Hover — linha/marcador crescem, opacidade, halo via states.hover; séries não pairadas escurecem via states.inactive.

Sistema de eventos

Handlers anexam no nível de gráfico, série, ponto e eixo. Dentro de um handler this é o objeto relevante.

chart: { events: { load() {}, redraw() {}, render() {}, click(e) {},
  selection(e) {}, drilldown(e) {}, drillup(e) {} } },
plotOptions: { series: { events: {
  click(e) {}, mouseOver() {}, mouseOut() {}, legendItemClick() { return true; },
  show() {}, hide() {}, afterAnimate() {}
}, point: { events: {
  click() {}, select() {}, unselect() {}, update(e) {}, remove() {}
} } } },
xAxis: { events: { afterSetExtremes(e) { /* e.min, e.max, e.trigger */ } } }

EventBus interno

const chart = KatuCharts.chart(container, options);
const unsub = chart.events.on('point:click', d => console.log(d.point, d.series));
chart.events.on('zoom:changed', d => console.log(d.xMin, d.xMax));
unsub();

Evento	Payload
`chart:load / redraw / render`	Instância de gráfico
`chart:click`	{ x, y, originalEvent }
`chart:addSeries`	{ series, options }
`point:mouseover / mouseout / click`	{ point, series, originalEvent }
`series:mouseenter / mouseleave`	{ series, originalEvent }
`series:visibilityChanged / legend:itemClick`	{ series, visible }
`navigator:brushed`	{ min, max }
`rangeSelector:selected / dateRange`	{ index, text } / { min, max }
`zoom:changed`	{ xMin, xMax, yMin, yMax, trigger }
`drilldown:drilldown / drillup`	{ point, seriesOptions } / { seriesOptions }

Exportação e acesso a dados

chart.exportChart({ type: 'image/png', filename: 'my-chart' });
// 'image/svg+xml' · 'image/jpeg' · 'application/pdf' (needs jspdf)

const svg  = chart.getSVG();
const csv  = chart.getCSV();
const html = chart.getTable();
const rows = chart.getDataRows();       // header row first

// the export menu can also offer CSV and XLS downloads:
// exporting: { buttons: { contextButton: { menuItems: [
//   'downloadPNG', 'downloadJPEG', 'downloadSVG', 'downloadPDF', 'downloadCSV', 'downloadXLS'
// ] } } }

import { ExportModule } from 'katucharts.js';
ExportModule.exportPNG(chart.getSVG(), 'my-chart', 2);   // svg string, filename, scale
ExportModule.exportPDF(chart.getSVG(), 'my-chart');      // needs jspdf

Gráficos de estoque

Gráficos financeiros do bundle principal ganham seletor de intervalo e navegador (rangeSelector.enabled, navigator.enabled), renderização OHLC/candlestick e agrupamento de dados.

import KatuCharts from 'katucharts.js';

KatuCharts.chart(container, {
  rangeSelector: { enabled: true, selected: 1, buttons: [
    { type: 'month', count: 1, text: '1m' },
    { type: 'year',  count: 1, text: '1y' },
    { type: 'all', text: 'All' }
  ] },
  navigator: { enabled: true },
  series: [{
    type: 'candlestick', name: 'AAPL', data: ohlc,
    dataGrouping: { units: [['week', [1]], ['month', [1, 3, 6]]] }
  }]
});

Aproximações de agrupamento de dados

Aproximação	Descrição
`average / sum`	Média / soma do grupo.
`open / close`	Primeiro / último valor no grupo.
`high / low`	Máximo / mínimo valor no grupo.
`ohlc`	Combina open, high, low, close em um ponto OHLC.

Design responsivo

Um ResizeObserver auto-chama reflow() no redimensionamento do container — gráficos se encaixam em layouts flex/grid sem trabalho manual. Adicione responsive.rules para substituições condicionais.

Altura automática — deixe chart.height sem definir (null) e o gráfico cresce para caber no conteúdo em vez de colapsar; o crescimento é limitado em viewports móveis curtos. Combine com chart.scrollablePlotArea para manter gráficos densos legíveis em telas pequenas.

responsive: {
  rules: [
    { condition: { maxWidth: 500 },
      chartOptions: { legend: { enabled: false }, credits: { enabled: false } } },
    { condition: { callback: () => matchMedia('(max-width: 600px)').matches },
      chartOptions: { chart: { spacing: [5, 5, 5, 5] } } }
  ]
}

ARIA — container recebe role="img" + aria-label descritivo.
Descrição — um bloco de texto oculto resume os dados para leitores de tela.
Teclado — Tab através de séries/pontos, Enter para selecionar, Escape para sair.
Regiões live — atualizações dinâmicas anunciadas via aria-live.
Gerenciamento de foco e alto contraste — indicadores de foco e diferenciação baseada em forma.

accessibility: {
  enabled: true,
  description: 'Line chart of monthly revenue, Jan–Jun 2024.',
  keyboardNavigation: { enabled: true, focusBorder: { style: { color: '#00f', lineWidth: 2 } } },
  point: { descriptionFormatter: p => p.series.name + ': ' + p.y + ' at ' + p.category },
  announceNewData: { enabled: true, minAnnounceInterval: 5000 }
}

Animação

KatuCharts.setOptions({ chart: { animation: { duration: 800, easing: 'easeOutCubic' } } });
// per-series
series: [{ data: [10,20,30], animation: { duration: 1200, easing: 'easeInOutQuart' } },
         { data: [8,15,22], animation: false }]
// animated update
chart.series[0].setData([50,60,70,80], false);
chart.animatedRedraw(600);

Animações de entrada por tipo

Tipo	Estilo	Duração
`line / spline`	Stroke draw (path reveal)	1000ms
`area`	Stroke draw + fill fade-in	1000ms
`column / bar`	Grow from baseline + stagger	800ms + 80ms/bar
`scatter / bubble`	Stagger fade-in / scale-in	600ms + 20–40ms/pt
`pie`	Rotate sweep	600ms
`heatmap / waterfall`	Fade / grow + stagger	600–800ms + per-cell/bar

Animações escalonadas são limitadas a 500 pontos; além disso, todos os pontos animam de uma vez por desempenho.