Guía

Conceptos

Las ideas que aplican a todos los tipos de gráficos — cómo se estructuran los datos, cómo se escalan los ejes, cómo aplicar temas, el sistema de eventos, exportación, capacidad de respuesta, accesibilidad y animación.

Formatos de datos

Array de números — cada valor es un y; x se auto-incrementa desde 0 (o pointStart).

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

Tuplas — [x, y], o [x, y, z] para burbujas (z = radio), o [name, y] para datos circulares/categoría.

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) — el más flexible; cada punto lleva propiedades nombradas.

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' }
}]

Nulos rompen la línea por defecto; connectNulls: true cubre las brechas. pointStart / pointInterval mapean un array plano a un eje x (excelente para datetime). keys remapea columnas de tuplas.

{ 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 especiales 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 ejes

Cada eje usa uno de cuatro tipos de escala; el tipo se infiere de los datos o se establece a través de xAxis.type/yAxis.type.

Tipo	Descripción
`linear`	Escala numérica continua.
`logarithmic`	Log base 10 para rangos exponenciales.
`datetime`	Escala de tiempo con formato de tick de fecha inteligente.
`category`	Banda discreta por etiqueta de categoría.

Establecer xAxis.categories convierte automáticamente el eje en un eje de categoría.

Cálculo de dominio (aplicado en orden)

minPadding / maxPadding — espacio en blanco proporcional en los bordes (0.01 lineal, 0 categoría).
softMin / softMax — extiende solo si los datos no alcanzan ya estos valores.
floor / ceiling — límites duros que el dominio no puede cruzar (pero puede ser más pequeño).
min / max — sobrescrituras duras explícitas.
startOnTick / endOnTick — redondea hacia afuera al tick más cercano.

Múltiples ejes

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] }
]

Estilos y temas

Los colores de las series provienen de una paleta — establécelos globalmente con setOptions({ colors }) o por gráfico. 20 paletas se distribuyen integradas (consulta API).

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

Estilos de guiones

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 clase CSS

Cada elemento obtiene una clase predecible para estilos externos — por ejemplo, .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.

Interactividad

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 } }
  }
}

Perforación — haz clic en un punto con un id drilldown para descender a una sub-serie; aparece un botón Atrás. Los niveles pueden anidarse.
Retícula — xAxis.crosshair: { width, color, dashStyle, snap } rastrea el puntero.
Selección de puntos — allowPointSelect: true con un estilo states.select y point.events.select/unselect.
Desplazamiento — línea/marcador crece, opacidad, halo a través de states.hover; series no desplazadas se atenúan a través de states.inactive.

Sistema de eventos

Los handlers se adjuntan a nivel de gráfico, serie, punto y eje. Dentro de un handler this es el 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	Carga
`chart:load / redraw / render`	Instancia 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 }

Exportación y acceso a datos

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 bursátiles

Los gráficos financieros del bundle principal incluyen selector de rango y navegador (rangeSelector.enabled, navigator.enabled), renderización OHLC/velas y agrupación de datos.

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]]] }
  }]
});

Aproximaciones de agrupación de datos

Aproximación	Descripción
`average / sum`	Media / suma del grupo.
`open / close`	Primer / último valor del grupo.
`high / low`	Valor máximo / mínimo del grupo.
`ohlc`	Combina apertura, máximo, mínimo, cierre en un punto OHLC.

Diseño responsivo

Un ResizeObserver llama automáticamente a reflow() al cambiar el tamaño del contenedor — los gráficos se ajustan a diseños flex/grid sin trabajo manual. Añade responsive.rules para sobrescrituras condicionales.

Altura automática — deja chart.height sin definir (null) y el gráfico crece para ajustarse a su contenido en lugar de colapsar; el crecimiento se limita en viewports móviles cortos. Combínalo con chart.scrollablePlotArea para mantener legibles los gráficos densos en pantallas pequeñas.

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 — el contenedor obtiene role="img" + descriptivo aria-label.
Descripción — un bloque de texto oculto resume los datos para lectores de pantalla.
Teclado — Presiona Tab para atravesar series/puntos, Enter para seleccionar, Escape para salir.
Regiones en vivo — actualizaciones dinámicas anunciadas a través de aria-live.
Gestión de foco y alto contraste — indicadores de foco y diferenciación basada en formas.

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 }
}

Animación

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);

Animaciones de entrada por tipo

Tipo	Estilo	Duración
`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

Las animaciones escalonadas tienen un límite de 500 puntos; más allá de eso, todos los puntos se animan a la vez por rendimiento.