@aeriz/chart 1.1.0 → 2.0.0

package/dist/index.d.ts

@@ -1,647 +1,323 @@
 /**
- * @aeriz/chart — visualization, light as air.
+ * @aeriz/chart 2.0 — visualization, light as air.
  *
- * 21 canvas chart types, one module each (import only what you use),
- * zero dependencies. Framework adapters: `@aeriz/chart/react`, `/vue`,
- * `/svelte`, `/jquery`.
+ * 21 canvas chart types with one way to do each thing:
+ * `new XChart(target, options)` → `update(patch)` · `setState(state)` · `render()` · `destroy()`.
+ * Every chart takes its data as `data`. Framework adapters: `@aeriz/chart/react`,
+ * `/vue`, `/svelte`, `/jquery`.
  *
  * @packageDocumentation
  */
 
-// ──────────────────────────────────────────────────────────────────
-// Common types
-// ──────────────────────────────────────────────────────────────────
+// ─── Shared types ────────────────────────────────────────────────
 
 /** A CSS selector or a DOM element to mount the chart into. */
-export type ChartContainer = string | HTMLElement;
+export type Target = string | HTMLElement;
 
-/** Color value — anything CSS accepts. */
+/** Any CSS color. */
 export type Color = string;
 
-/** Tick formatter used on numeric axes. Receives the raw tick value. */
-export type TickFormatter = (value: number) => string;
-
-/** Categorical tick formatter — receives the raw category label. */
-export type CategoryTickFormatter = (label: string, index: number) => string;
-
-/** Axis scale type. `time` interprets numeric values as ms since epoch. */
-export type ScaleType = 'linear' | 'log' | 'time';
-
-/** Click handler signature shared by all chart types. */
-export type ClickHandler<H = unknown> = (
-  hit: H | null,
-  point: { x: number; y: number },
-  chart: Chart<any>,
-) => void;
-
-/**
- * Label/value data in any of these shapes:
- * `[{ label, value }]` · `[3, 7, 4]` · `{ Jan: 3, Feb: 7 }` · `[['Jan', 3], ['Feb', 7]]`
- */
-export type Rows<T> = T[] | number[] | Record<string, number> | Array<[string, number]>;
-
 /**
- * Number format for tooltips and value axes: a function, or
- * `Intl.NumberFormat` options such as `{ style: 'currency', currency: 'KRW' }`.
+ * Number format for tooltips and the value axis: `Intl.NumberFormat` options
+ * such as `{ style: 'currency', currency: 'KRW' }`, or a function.
+ * Without it, numbers follow the browser locale.
  */
-export type NumberFormat = ((value: number) => string) | Intl.NumberFormatOptions;
-
-/** What `onClick` receives — the hovered element, or `null`. */
-export interface Hit {
-  /** Index of the data row / category. */
-  index?: number;
-  /** Series index (multi-series charts). */
-  series?: number;
+export type NumberFormat = Intl.NumberFormatOptions | ((value: number) => string);
+
+/** Formats category / time labels on the x axis and in tooltips. Time labels are ms timestamps. */
+export type LabelFormat = (label: any) => string;
+
+/** What `onClick` receives: the clicked item. */
+export interface Hit<Row = unknown> {
+  /** Index of the row / category (heatmap: column). */
+  index: number;
+  /** Its label (category, row label, or point label). */
+  label: any;
+  /** Its value, when the item has one. */
   value?: number;
-  /** The original data row, when there is one. */
-  data?: unknown;
-  tooltip?: string | { title?: string; rows: Array<{ name?: string; value?: string; color?: Color }> };
+  /** Series index in multi-series charts (heatmap: row). */
+  series?: number;
+  /** The original data item: your row, point or series object. */
+  row?: Row;
 }
 
-/** A single named series of numeric values, used by category-axis charts. */
-export interface Series {
-  name: string;
-  values: number[];
-  color?: Color;
-  hidden?: boolean;
+/** `chart.setState()` overlays. `null` removes the overlay. */
+export type State = 'loading' | 'empty' | 'error' | null;
+
+/** Options every chart takes. */
+export interface CommonOptions<D, Row = unknown> {
+  /** The data. Its shape depends on the chart — see each chart's `data`. */
+  data?: D;
+  /** Accessible name for screen readers (gauge also shows it as a caption). */
+  title?: string;
+  /** Series / item colors, in order. Defaults to `--aeriz-color-1…12`, then the built-in palette. */
+  colors?: Color[];
+  /** Number format for tooltips and the value axis. */
+  format?: NumberFormat;
+  /** Show the legend (multi-series charts and pie). Default `true`. */
+  legend?: boolean;
+  /** Animate drawing and updates. Default `true` (off with prefers-reduced-motion). */
+  animate?: boolean;
+  /** Text shown when there is no data. Default `'No data'`. */
+  emptyText?: string;
+  /** Called when an item is clicked (or Enter is pressed on it). */
+  onClick?: (hit: Hit<Row>, chart: Chart) => void;
+  /** Called when a legend item is toggled. */
+  onLegend?: (index: number, visible: boolean, chart: Chart) => void;
 }
 
-/** A single radar-axis series — same shape as a regular Series. */
-export type RadarSeries = Series;
+/** Value axis range (charts with axes). */
+export interface AxisOptions {
+  /** Formats x-axis labels and tooltip titles. */
+  labelFormat?: LabelFormat;
+  /** Lowest value on the value axis (default: from the data, starting at 0). */
+  min?: number;
+  /** Highest value on the value axis (default: from the data). */
+  max?: number;
+}
 
-// ──────────────────────────────────────────────────────────────────
-// Per-chart datum shapes
-// ──────────────────────────────────────────────────────────────────
+// ─── Data shapes ─────────────────────────────────────────────────
 
-export interface BarDatum {
-  label: string;
+/** A `{ label, value }` row. Extra fields are allowed (use `label` / `value` accessors to read others). */
+export interface Row {
+  label: string | number;
   value: number;
+  /** Per-item color. */
   color?: Color;
 }
 
-export interface ScatterDatum {
-  x: number;
-  y: number;
-  group?: number | string;
-  color?: Color;
-}
+/**
+ * Single-series data, three ways that mean the same:
+ * `[64, 42, 78]` · `{ Jan: 64, Feb: 42 }` · `[{ label: 'Jan', value: 64 }]`
+ * (or your own objects with `label` / `value` accessors).
+ */
+export type Rows<R = Row> = number[] | Float64Array | Float32Array | Record<string, number> | R[];
 
-export interface BubbleDatum extends ScatterDatum {
-  z: number;
+/** Single-series options: read other fields with accessors. */
+export interface RowOptions<R> {
+  /** Reads a row's label, e.g. `(row) => row.month`. */
+  label?: (row: R, index: number) => string | number;
+  /** Reads a row's value, e.g. `(row) => row.sales`. */
+  value?: (row: R, index: number) => number;
 }
 
-export interface PieDatum {
-  label: string;
-  value: number;
+export interface Series {
+  name: string;
+  values: ArrayLike<number | null>;
   color?: Color;
 }
 
-export interface PolarDatum {
-  label: string;
-  value: number;
-  color?: Color;
+/** Multi-series data. Every series has one value per category. */
+export interface SeriesData<S extends Series = Series> {
+  categories: ArrayLike<string | number>;
+  series: S[];
 }
 
-export interface HeatmapDatum {
+export interface Point {
   x: number;
   y: number;
-  value: number;
+  /** Scatter: radius in px. Bubble: a value, drawn as the bubble's area. */
+  size?: number;
+  /** Colors points by series index. */
+  group?: number;
+  label?: string;
+  color?: Color;
 }
 
-export interface BoxplotDatum {
-  label: string;
-  min: number;
-  q1: number;
-  median: number;
-  q3: number;
-  max: number;
-  outliers?: number[];
-}
+// ─── Base class ──────────────────────────────────────────────────
 
-export interface FunnelDatum {
-  label: string;
-  value: number;
-  color?: Color;
+export interface ChartMeta {
+  id: string;
+  name: string;
+  aria: string;
+  data: 'rows' | 'series' | 'stream' | 'points' | 'matrix' | 'boxes' | 'steps' | 'number';
+  options: string[];
 }
 
-export interface TreemapDatum {
-  label: string;
-  value: number;
-  color?: Color;
+export declare class Chart<O = CommonOptions<unknown>> {
+  constructor(target: Target, options?: O);
+  static readonly meta: ChartMeta | null;
+  readonly container: HTMLElement;
+  readonly canvas: HTMLCanvasElement;
+  readonly options: O;
+  /** Change any options, data included. Changed values animate in. */
+  update(patch: Partial<O>): this;
+  /** Show a loading / empty / error overlay (with optional text), or remove it with `null`. */
+  setState(state: State, text?: string): this;
+  /** Re-read CSS variables and draw the final frame now — also off-screen (print, export). */
+  render(): this;
+  /** Remove the chart and undo every change to the container. */
+  destroy(): void;
 }
 
-export interface WaterfallDatum {
-  label: string;
-  value: number;
-  /** Anchor bar — drawn at absolute height instead of as a delta. */
-  isTotal?: boolean;
-  color?: Color;
-}
+/** The default color palette. */
+export declare const PALETTE: readonly Color[];
 
-/** A layer in a `CompositeChart`. */
-export type CompositeLayer =
-  | {
-      type: 'bar' | 'line' | 'area';
-      name: string;
-      values: number[];
-      color?: Color;
-      /** Which y-axis the layer maps to. Default `'left'`. */
-      axis?: 'left' | 'right';
-    }
-  | {
-      type: 'scatter';
-      name: string;
-      values: Array<{ x: number; y: number }>;
-      color?: Color;
-      axis?: 'left' | 'right';
-    };
-
-// ──────────────────────────────────────────────────────────────────
-// Per-chart option types
-// ──────────────────────────────────────────────────────────────────
-
-/** Options shared by every chart. */
-export interface BaseChartOptions {
-  /** Override the auto-resolved palette. */
-  palette?: Color[];
-  /** Show value labels on bars (BarChart). A function formats each label. */
-  dataLabels?: boolean | ((datum: any, index: number) => string);
-  /** Click handler — `hit` is the element under the pointer, or `null`. Enter key also fires it. */
-  onClick?: ClickHandler<Hit>;
-  /** Number format for tooltips and value axes (axes switch to compact 12K / 3.4M above 10,000). */
-  format?: NumberFormat;
-  /** `false` hides the legend on multi-series charts. */
-  legend?: boolean;
-  /** Called when a legend item is toggled. */
-  onLegend?: (index: number, visible: boolean, chart: Chart<any>) => void;
-  /** `false` draws without the entry/update animation. Reduced-motion users never get one. */
-  animate?: boolean;
-  /** Accessible name for the chart canvas (defaults to `title`, then the chart type). */
-  ariaLabel?: string;
-  title?: string;
-  /** Text of the automatic empty state. Default `'No data'`. */
-  emptyText?: string;
-}
+// ─── Charts ──────────────────────────────────────────────────────
 
-export interface BarChartOptions extends BaseChartOptions {
-  data: Rows<BarDatum>;
-  /** Read the label from a custom row shape. */
-  label?: (d: any, i: number) => string | number;
-  /** Read the value from a custom row shape. */
-  value?: (d: any, i: number) => number;
-  /** One color for every bar / the line (instead of the palette). */
-  color?: Color;
-  yTickFormat?: TickFormatter;
-  xTickFormat?: CategoryTickFormatter;
-}
+type Curve = 'smooth' | 'linear' | 'step';
 
-export interface HBarChartOptions extends BaseChartOptions {
-  data: Rows<BarDatum>;
-  /** Read the label from a custom row shape. */
-  label?: (d: any, i: number) => string | number;
-  /** Read the value from a custom row shape. */
-  value?: (d: any, i: number) => number;
-  /** One color for every bar / the line (instead of the palette). */
-  color?: Color;
-  xTickFormat?: TickFormatter;
-  yTickFormat?: CategoryTickFormatter;
+export interface BarOptions<R = Row> extends CommonOptions<Rows<R>, R>, AxisOptions, RowOptions<R> {
+  /** Value labels on the bars: `true`, or a function for the text. */
+  dataLabels?: boolean | ((value: number, row: R, index: number) => string);
 }
+export declare class BarChart<R = Row> extends Chart<BarOptions<R>> {}
 
-export interface LineChartOptions extends BaseChartOptions {
-  data: Rows<BarDatum>;
-  /** Read the label from a custom row shape. */
-  label?: (d: any, i: number) => string | number;
-  /** Read the value from a custom row shape. */
-  value?: (d: any, i: number) => number;
-  /** One color for every bar / the line (instead of the palette). */
-  color?: Color;
-  /** Path interpolation. Default `'smooth'`. */
-  interpolation?: 'smooth' | 'linear' | 'step' | 'step-after' | 'step-middle';
-  /** Area under the line. Default `true`. */
+export interface HBarOptions<R = Row> extends CommonOptions<Rows<R>, R>, AxisOptions, RowOptions<R> {}
+export declare class HBarChart<R = Row> extends Chart<HBarOptions<R>> {}
+
+export interface LineOptions<R = Row> extends CommonOptions<Rows<R>, R>, AxisOptions, RowOptions<R> {
+  /** Default `'smooth'`. */
+  curve?: Curve;
+  /** Gradient fill under the line. Default `true`. */
   fill?: boolean;
-  /** Dots on each point (≤ 50 points). Default `true`. */
+  /** Point markers (up to 50 points). Default `true`. */
   points?: boolean;
-  /** Highlight the last data point with a dot. */
-  lastDot?: boolean;
-  xScale?: ScaleType;
-  yScale?: ScaleType;
-  yTickFormat?: TickFormatter;
-  xTickFormat?: CategoryTickFormatter;
+  /** `'time'`: labels are ms timestamps on a local-time axis. Default `'category'`. */
+  xScale?: 'category' | 'time';
+  /** Default `'linear'`. */
+  yScale?: 'linear' | 'log';
 }
+export declare class LineChart<R = Row> extends Chart<LineOptions<R>> {}
 
-export interface AreaChartOptions extends BaseChartOptions {
-  categories: string[];
-  series: Series[];
-  /** Stack all series. Default `false`. */
+export interface AreaOptions extends CommonOptions<SeriesData, Series>, AxisOptions {
+  /** Stack the series. */
   stacked?: boolean;
-  yTickFormat?: TickFormatter;
-  xTickFormat?: CategoryTickFormatter;
 }
+export declare class AreaChart extends Chart<AreaOptions> {}
 
-export interface StackedBarChartOptions extends BaseChartOptions {
-  categories: string[];
-  series: Series[];
-  yTickFormat?: TickFormatter;
-}
+export interface StackedBarOptions extends CommonOptions<SeriesData, Series>, AxisOptions {}
+export declare class StackedBarChart extends Chart<StackedBarOptions> {}
 
-export interface GroupedBarChartOptions extends BaseChartOptions {
-  categories: string[];
-  series: Series[];
-  yTickFormat?: TickFormatter;
-}
+export interface GroupedBarOptions extends CommonOptions<SeriesData, Series>, AxisOptions {}
+export declare class GroupedBarChart extends Chart<GroupedBarOptions> {}
 
-export interface MultiLineChartOptions extends BaseChartOptions {
-  categories: Array<string | number>;
-  series: Series[];
-  interpolation?: 'smooth' | 'linear' | 'step' | 'step-after' | 'step-middle';
-  /** `'time'`: categories are timestamps (ms). */
-  xScale?: ScaleType;
-  yTickFormat?: TickFormatter;
+export interface MultiLineOptions extends CommonOptions<SeriesData, Series>, AxisOptions {
+  curve?: Curve;
+  xScale?: 'category' | 'time';
 }
+export declare class MultiLineChart extends Chart<MultiLineOptions> {}
 
-export interface ScatterChartOptions extends BaseChartOptions {
-  data: ScatterDatum[];
-  xScale?: ScaleType;
-  yScale?: ScaleType;
-  xTickFormat?: TickFormatter;
-  yTickFormat?: TickFormatter;
-}
+export interface ScatterOptions extends CommonOptions<Point[], Point>, AxisOptions {}
+export declare class ScatterChart extends Chart<ScatterOptions> {}
 
-export interface BubbleChartOptions extends BaseChartOptions {
-  data: BubbleDatum[];
-  /** Largest bubble radius in px. Default `32`. */
-  maxRadius?: number;
-  /** Smallest bubble radius in px. Default `4`. */
-  minRadius?: number;
-  xScale?: ScaleType;
-  yScale?: ScaleType;
-  xTickFormat?: TickFormatter;
-  yTickFormat?: TickFormatter;
+export interface BubbleOptions extends CommonOptions<Point[], Point>, AxisOptions {
+  /** Bubble radius range in px for the smallest and largest `size`. Default `[4, 32]`. */
+  radius?: [number, number];
 }
+export declare class BubbleChart extends Chart<BubbleOptions> {}
 
-export interface PieChartOptions extends BaseChartOptions {
-  data: Rows<PieDatum>;
-  label?: (d: any, i: number) => string | number;
-  value?: (d: any, i: number) => number;
-  /**
-   * Donut hole: a ratio of the radius (`0.6`), pixels (`80`), `'auto'`
-   * (0.55), or omit for a solid pie.
-   */
-  innerRadius?: number | 'auto';
-  /** Text in the donut center when nothing is hovered (default: the total). */
-  totalLabel?: string;
-  /** `false` hides the donut center text. */
-  centerLabel?: boolean;
+export interface PieOptions<R = Row> extends CommonOptions<Rows<R>, R>, RowOptions<R> {
+  /** Donut hole as a share of the radius, 0–0.9. Default `0` (pie). */
+  innerRadius?: number;
+  /** Donut center text. Default: the formatted total. `false` hides it. */
+  center?: string | false;
 }
+export declare class PieChart<R = Row> extends Chart<PieOptions<R>> {}
 
-export interface RadarChartOptions extends BaseChartOptions {
-  axes: string[];
-  series: RadarSeries[];
+export interface RadarOptions extends CommonOptions<SeriesData, Series> {
+  labelFormat?: LabelFormat;
+  /** Value at the outer ring (default: from the data). */
+  max?: number;
 }
+export declare class RadarChart extends Chart<RadarOptions> {}
 
-export interface PolarChartOptions extends BaseChartOptions {
-  data: Rows<PolarDatum>;
-  label?: (d: any, i: number) => string | number;
-  value?: (d: any, i: number) => number;
-  /** `'sqrt'` (default) keeps wedge *area* proportional to value; `'linear'` maps radius. */
+export interface PolarOptions<R = Row> extends CommonOptions<Rows<R>, R>, RowOptions<R> {
+  /** `'sqrt'` keeps areas true to the values. Default `'sqrt'`. */
   scale?: 'sqrt' | 'linear';
 }
+export declare class PolarChart<R = Row> extends Chart<PolarOptions<R>> {}
 
-export interface GaugeChartOptions extends BaseChartOptions {
-  value: number;
-  /** Minimum scale value. Default `0`. */
+export interface GaugeOptions extends CommonOptions<number> {
+  /** Default `0`. */
   min?: number;
-  /** Maximum scale value. Default `100`. */
+  /** Default `100`. */
   max?: number;
-  /** Arc color. Default: first palette color. */
-  color?: Color;
-  /** Label drawn under the gauge. */
-  label?: string;
-  /** Suffix appended to the displayed value, e.g. `'%'`. */
+  /** Text after the number, e.g. `'%'`. */
   unit?: string;
 }
+export declare class GaugeChart extends Chart<GaugeOptions> {}
 
-export interface HeatmapChartOptions extends BaseChartOptions {
-  xLabels: string[];
-  yLabels: string[];
-  data: HeatmapDatum[];
-  /** Color of the lowest cell value. */
-  colorLow?: Color;
-  /** Color of the highest cell value. */
-  colorHigh?: Color;
+export interface HeatmapData {
+  x: ArrayLike<string | number>;
+  y: ArrayLike<string | number>;
+  /** `values[y][x]`; `null` leaves a cell empty. */
+  values: Array<ArrayLike<number | null>>;
+}
+export interface HeatmapOptions extends Omit<CommonOptions<HeatmapData, { x: unknown; y: unknown; value: number }>, 'colors'> {
+  labelFormat?: LabelFormat;
+  /** Colors for the lowest and highest values. */
+  colors?: { low?: Color; high?: Color };
 }
+export declare class HeatmapChart extends Chart<HeatmapOptions> {}
 
-export interface BoxplotChartOptions extends BaseChartOptions {
-  data: BoxplotDatum[];
-  yTickFormat?: TickFormatter;
+export interface Box {
+  label: string | number;
+  min: number;
+  q1: number;
+  median: number;
+  q3: number;
+  max: number;
+  outliers?: number[];
+  color?: Color;
 }
+export interface BoxplotOptions extends CommonOptions<Box[], Box>, AxisOptions {}
+export declare class BoxplotChart extends Chart<BoxplotOptions> {}
 
-export interface FunnelChartOptions extends BaseChartOptions {
-  data: Rows<FunnelDatum>;
-  label?: (d: any, i: number) => string | number;
-  value?: (d: any, i: number) => number;
-  /** Text color inside segments. Default `#fff`. */
+export interface FunnelOptions<R = Row> extends CommonOptions<Rows<R>, R>, RowOptions<R> {
+  /** Color of labels drawn inside the segments. Default `'#fff'`. */
   labelColor?: Color;
 }
+export declare class FunnelChart<R = Row> extends Chart<FunnelOptions<R>> {}
 
-export interface TreemapChartOptions extends BaseChartOptions {
-  data: Rows<TreemapDatum>;
-  label?: (d: any, i: number) => string | number;
-  value?: (d: any, i: number) => number;
-  /** Text color inside tiles. Default `#fff`. */
+export interface TreemapOptions<R = Row> extends CommonOptions<Rows<R>, R>, RowOptions<R> {
+  /** Color of labels drawn inside the tiles. Default `'#fff'`. */
   labelColor?: Color;
 }
+export declare class TreemapChart<R = Row> extends Chart<TreemapOptions<R>> {}
 
-export interface SparklineOptions extends BaseChartOptions {
-  /** Numbers (or `{ value }` rows) — sparklines have no axes. */
-  data: number[] | Array<{ value: number }>;
-  value?: (d: any, i: number) => number;
-  color?: Color;
+export interface SparklineOptions<R = Row> extends CommonOptions<Rows<R>, R>, RowOptions<R> {
+  min?: number;
+  max?: number;
+  /** Default `true`. */
   fill?: boolean;
+  /** Dot on the last value. Default `true`. */
   lastDot?: boolean;
 }
+export declare class SparklineChart<R = Row> extends Chart<SparklineOptions<R>> {}
 
-export interface RealtimeChartOptions extends BaseChartOptions {
-  /** Series definitions; values are pushed in over time via `push()`. */
-  series: Array<{ name: string; color?: Color }>;
-  /** Number of samples to keep on screen. Default `200`. */
-  windowSize?: number;
-  yTickFormat?: TickFormatter;
-  /** Fix the y range instead of fitting the visible window. */
-  yMin?: number;
-  yMax?: number;
-  /** Text shown before the first sample. Default `'streaming…'`. */
-  waitingText?: string;
-}
-
-export interface WaterfallChartOptions extends BaseChartOptions {
-  data: WaterfallDatum[] | Record<string, number>;
-  yTickFormat?: TickFormatter;
-  /** Color for positive deltas. */
-  colorUp?: Color;
-  /** Color for negative deltas. */
-  colorDown?: Color;
-  /** Color for total / anchor bars. */
-  colorTotal?: Color;
-}
-
-export interface CompositeChartOptions extends BaseChartOptions {
-  categories: string[];
-  layers: CompositeLayer[];
-  xScale?: ScaleType;
-  /** Left axis format (`yTickFormat` works too). */
-  yLeftTickFormat?: TickFormatter;
-  yRightTickFormat?: TickFormatter;
-  yTickFormat?: TickFormatter;
-  xTickFormat?: (value: number) => string;
-}
-
-// ──────────────────────────────────────────────────────────────────
-// Base Chart class
-// ──────────────────────────────────────────────────────────────────
-
-/**
- * Common base class for every chart.
- *
- * `O` is the concrete options shape for the subclass. Most users will
- * interact only through the typed subclasses (e.g. `BarChart`); this base
- * is exposed for advanced extension scenarios.
- */
-export class Chart<O extends BaseChartOptions = BaseChartOptions> {
-  constructor(container: ChartContainer, options: O);
-
-  readonly container: HTMLElement;
-  options: O;
-
-  /** Re-resolve theme + palette from CSS variables and redraw. */
-  invalidate(): void;
-
-  /**
-   * Merge new options — any of them, including `data`, `series`,
-   * `categories` — and animate to the new state. Returns `this`.
-   */
-  update(options: Partial<O>): this;
-
-  /** Replace `options.data` and animate to the new state. Returns `this`. */
-  setData(data: O extends { data: infer D } ? D : unknown): this;
-
-  /** Show a loading overlay. Returns `this`. */
-  setLoading(message?: string): this;
-  /** Show an empty-state overlay. Returns `this`. */
-  setEmpty(message?: string): this;
-  /** Show an error overlay. Returns `this`. */
-  setError(message?: string): this;
-  /** Clear any active overlay state and resume rendering. Returns `this`. */
-  clearState(): this;
-
-  /** Tear down listeners, observers, and remove the canvas. */
-  destroy(): void;
-}
-
-// ──────────────────────────────────────────────────────────────────
-// Concrete chart classes
-// ──────────────────────────────────────────────────────────────────
-
-export class BarChart extends Chart<BarChartOptions> {
-  constructor(container: ChartContainer, options: BarChartOptions);
-}
-export class HBarChart extends Chart<HBarChartOptions> {
-  constructor(container: ChartContainer, options: HBarChartOptions);
-}
-export class LineChart extends Chart<LineChartOptions> {
-  constructor(container: ChartContainer, options: LineChartOptions);
-}
-export class AreaChart extends Chart<AreaChartOptions> {
-  constructor(container: ChartContainer, options: AreaChartOptions);
-}
-export class StackedBarChart extends Chart<StackedBarChartOptions> {
-  constructor(container: ChartContainer, options: StackedBarChartOptions);
-}
-export class GroupedBarChart extends Chart<GroupedBarChartOptions> {
-  constructor(container: ChartContainer, options: GroupedBarChartOptions);
-}
-export class MultiLineChart extends Chart<MultiLineChartOptions> {
-  constructor(container: ChartContainer, options: MultiLineChartOptions);
-}
-export class ScatterChart extends Chart<ScatterChartOptions> {
-  constructor(container: ChartContainer, options: ScatterChartOptions);
-}
-export class BubbleChart extends Chart<BubbleChartOptions> {
-  constructor(container: ChartContainer, options: BubbleChartOptions);
-}
-export class PieChart extends Chart<PieChartOptions> {
-  constructor(container: ChartContainer, options: PieChartOptions);
-}
-export class RadarChart extends Chart<RadarChartOptions> {
-  constructor(container: ChartContainer, options: RadarChartOptions);
-}
-export class PolarChart extends Chart<PolarChartOptions> {
-  constructor(container: ChartContainer, options: PolarChartOptions);
-}
-
-export class GaugeChart extends Chart<GaugeChartOptions> {
-  constructor(container: ChartContainer, options: GaugeChartOptions);
-  /** Animate the needle to a new value. */
-  setValue(value: number): this;
-}
-
-export class HeatmapChart extends Chart<HeatmapChartOptions> {
-  constructor(container: ChartContainer, options: HeatmapChartOptions);
-}
-export class BoxplotChart extends Chart<BoxplotChartOptions> {
-  constructor(container: ChartContainer, options: BoxplotChartOptions);
-}
-export class FunnelChart extends Chart<FunnelChartOptions> {
-  constructor(container: ChartContainer, options: FunnelChartOptions);
-}
-export class TreemapChart extends Chart<TreemapChartOptions> {
-  constructor(container: ChartContainer, options: TreemapChartOptions);
-}
-export class Sparkline extends Chart<SparklineOptions> {
-  constructor(container: ChartContainer, options: SparklineOptions);
+export interface RealtimeOptions extends CommonOptions<{ series: Array<{ name: string; color?: Color }> }> {
+  min?: number;
+  max?: number;
+  /** How many samples stay visible. Default `200`. */
+  window?: number;
 }
-
-export class RealtimeChart extends Chart<RealtimeChartOptions> {
-  constructor(container: ChartContainer, options: RealtimeChartOptions);
-  /**
-   * Append one sample. Pass a single number for one-series charts, or an
-   * array aligned with `options.series` for multi-series charts.
-   */
-  push(values: number | number[]): this;
-  /** Drop all buffered samples. */
+export declare class RealtimeChart extends Chart<RealtimeOptions> {
+  /** Add one sample: one value per series (a number for a single series). */
+  push(values: number | Array<number | null>): this;
+  /** Remove every sample. */
   clear(): this;
 }
 
-export class WaterfallChart extends Chart<WaterfallChartOptions> {
-  constructor(container: ChartContainer, options: WaterfallChartOptions);
-}
-
-export class CompositeChart extends Chart<CompositeChartOptions> {
-  constructor(container: ChartContainer, options: CompositeChartOptions);
+export interface Step {
+  label: string | number;
+  value: number;
+  /** Draw this bar from zero to its value (a subtotal or the end result). */
+  total?: boolean;
 }
-
-// ──────────────────────────────────────────────────────────────────
-// Engine + scheduler (advanced / extension API)
-// ──────────────────────────────────────────────────────────────────
-
-/**
- * Low-level canvas drawing primitives shared by every chart. Most users
- * will not touch this directly — extend `Chart` and use `this.engine`.
- */
-export class Engine {
-  constructor(canvas: HTMLCanvasElement);
-  readonly canvas: HTMLCanvasElement;
-  readonly ctx: CanvasRenderingContext2D;
-  /** Logical width in CSS pixels (set by `resize()`). */
-  readonly w: number;
-  /** Logical height in CSS pixels (set by `resize()`). */
-  readonly h: number;
-  /** Device pixel ratio used for the backing buffer. */
-  readonly dpr: number;
-  resize(w: number, h: number): void;
-  clear(color?: Color): void;
+export interface WaterfallOptions extends Omit<CommonOptions<Step[], Step>, 'colors'>, AxisOptions {
+  colors?: { up?: Color; down?: Color; total?: Color };
 }
+export declare class WaterfallChart extends Chart<WaterfallOptions> {}
 
-/** Normalize label/value data shortcuts to `{ label, value }` rows. */
-export function toRows<T = BarDatum>(data: Rows<T> | null | undefined): T[];
-
-/** Geometry returned by `drawCartesian()`. */
-export interface CartesianFrame {
-  px: number; py: number; pw: number; ph: number;
-  yToPx(v: number): number;
-  yRToPx: ((v: number) => number) | null;
-  xToPx(v: number): number;
-  yTicks: number[];
-  xTicks: number[];
-  yMin: number;
-  yMax: number;
+export interface CompositeSeries extends Series {
+  type: 'bar' | 'line' | 'area' | 'scatter';
+  /** Put this series on the right axis. */
+  axis?: 'left' | 'right';
+  /** Number format for this series (tooltip and its axis). */
+  format?: NumberFormat;
 }
-
-/** Draw grid + axes for a custom chart (extension API). */
-export function drawCartesian(chart: Chart<any>, spec: {
-  yMin?: number; yMax: number; yScale?: 'linear' | 'log'; yTickFormat?: TickFormatter;
-  xLabels?: Array<string | number>; xTime?: { min: number; max: number }; xLinear?: { min: number; max: number };
-  xTickFormat?: (value: number, index: number) => string;
-  right?: { yMin: number; yMax: number; yTickFormat?: TickFormatter };
-  pad?: { l?: number; r?: number; t?: number; b?: number };
-}): CartesianFrame;
-
-/**
- * Global render scheduler. Charts register themselves and are ticked on
- * `requestAnimationFrame` only when dirty.
- */
-export const scheduler: {
-  schedule(chart: Chart<any>): void;
-  fps(): number;
-  count(): number;
-};
-
-/** Current render frame rate, averaged over the last ~500 ms. */
-export function getFPS(): number;
-
-/** Number of charts currently mounted. */
-export function getActiveCount(): number;
-
-// ──────────────────────────────────────────────────────────────────
-// Math helpers
-// ──────────────────────────────────────────────────────────────────
-
-/**
- * Default qualitative palette — 8 colors, brand accent first.
- *
- * Re-exported at the top level because every chart accepts a `palette`
- * option and most users only ever need this one math symbol directly.
- */
-export const PALETTE: Color[];
-
-/**
- * Pure helpers (scales, ticks, smoothing, color ops). Use as
- * `import { math } from 'aeriz'` and then `math.clamp(...)` etc.
- */
-export const math: {
-  readonly TAU: number;
-  clamp(v: number, lo: number, hi: number): number;
-  lerp(a: number, b: number, t: number): number;
-  extent<T>(arr: T[], fn?: (x: T, i: number) => number): [number, number];
-  niceTicks(min: number, max: number, count?: number): number[];
-  niceDomain(min: number, max: number, count?: number): [number, number];
-  timeNiceTicks(minMs: number, maxMs: number, count?: number): number[];
-  timeFormat(stepMs: number): (timestampMs: number) => string;
-  minMaxDecimate<T>(
-    data: T[],
-    targetCount: number,
-    fn?: (d: T, i: number) => number,
-  ): T[];
-  /** Indices of the points min-max decimation keeps. */
-  minMaxDecimateIdx(n: number, targetCount: number, valueAt: (i: number) => number): number[];
-  shouldDecimate(n: number, pxWidth: number): boolean;
-  /** Format a number like the charts do (see `NumberFormat`). `axis` enables compact notation. */
-  formatNumber(value: number, format?: NumberFormat | null, axis?: boolean): string;
-  bezierControlPoints(
-    pts: Array<{ x: number; y: number }>,
-    tension?: number,
-  ): Array<{ c1x: number; c1y: number; c2x: number; c2y: number }>;
-  springStep(
-    v: number,
-    target: number,
-    velocity: number,
-    cfg?: { stiffness?: number; damping?: number },
-  ): { value: number; velocity: number; done: boolean };
-  colorParse(c: Color): [number, number, number, number];
-  colorAlpha(c: Color, a: number): string;
-  colorMix(a: Color, b: Color, t: number): string;
-  readonly PALETTE: Color[];
-};
-
-// ──────────────────────────────────────────────────────────────────
-// Browser global (for the IIFE / CDN bundle)
-// ──────────────────────────────────────────────────────────────────
-
-declare global {
-  interface Window {
-    Aeriz?: typeof import('./index.js') & {
-      /** Install the jQuery plugin on a jQuery that loaded after this script. */
-      jquery(jq: unknown): unknown;
-    };
-  }
+export interface CompositeOptions extends CommonOptions<SeriesData<CompositeSeries>, CompositeSeries>, AxisOptions {
+  xScale?: 'category' | 'time';
 }
+export declare class CompositeChart extends Chart<CompositeOptions> {}