@jarenjs/charts 0.34.0

package/src/component/index.js

@@ -0,0 +1,125 @@
+//@ts-check
+/**
+ * @file The charts VISUAL COMPONENT — the only app-aware file in the
+ * package (the two-layer rule the mermaid component established). The
+ * engine neither knows nor needs any of it.
+ *
+ * `createChartComponent()` returns a memoized `view()` projection for
+ * `@jarenjs/app` viewModels: the same `(config, data)` pair yields a
+ * reference-equal vnode, so an unchanged chart patches in O(1). The
+ * memo is a WeakMap keyed on the DATA object's identity (streaming
+ * snapshots are fresh objects, so every tick re-renders; static data is
+ * stable, so navigation is free), with an inner cache keyed on the
+ * config's structural identity. That identity is the whole serialized
+ * config, not a fingerprint of it: the memo hands back the vnode, so a
+ * hash collision would draw one chart's config under another's.
+ */
+
+import { createSemanticCache } from '@jarenjs/core/cache';
+import { compileChart } from '../core/chart.js';
+import { createChartSession } from '../core/session.js';
+
+/** Distinct configs memoized per data object before the oldest is
+ * dropped — one chart is redrawn from a handful of configs at most, so
+ * the bound only stops an unbounded churn of generated configs. */
+const CONFIG_MEMO_LIMIT = 64;
+
+/**
+ * @typedef {object} ChartComponentOptions
+ * @property {any} [theme] theme name or override object
+ * @property {import('../core/marks.js').ChartTooltipSpec} [tooltip] pointer
+ *  bindings emitted from every value mark, for a floating-tooltip host
+ *  (see {@link tooltipView}); absent leaves charts on their native
+ *  `<title>` hover only
+ */
+/**
+ * @typedef {object} ChartComponent
+ * @property {(config: any, data?: any) => import('../core/chart.js').CompiledChart} compile
+ * @property {(config: any, data?: any) => any} view memoized vnode projection
+ * @property {(config: any, source: import('../core/session.js').ChartSessionSource)
+ *   => import('../core/session.js').ChartSession} createSession incremental
+ *   session bound to this component's theme
+ * @property {Record<string, (props: any, dispatch: any) => any>} effects
+ */
+
+/**
+ * Create the charts component.
+ *
+ * @example
+ * const charts = createChartComponent({ theme: 'host' });
+ * createApp(appDoc, {
+ *   viewModel: (state) => ({ ...state, chart: charts.view(state.config, state.data) }),
+ * });
+ *
+ * @param {ChartComponentOptions} [options]
+ * @returns {ChartComponent}
+ */
+export function createChartComponent(options = {}) {
+  const compileOptions = { theme: options.theme, tooltip: options.tooltip };
+
+  /** Data-identity memo; inner caches key on the config's identity. */
+  /** @type {WeakMap<object, import('@jarenjs/core/cache').SemanticCache<any>>} */
+  const byData = new WeakMap();
+
+  const compile = (config, data = config) => compileChart(config, data, compileOptions);
+
+  return {
+    compile,
+
+    createSession(config, source) {
+      return createChartSession(config, source, compileOptions);
+    },
+
+    view(config, data = config) {
+      if (config === null || config === undefined) return null;
+      if (data === null || typeof data !== 'object') {
+        return compile(config, data).toVnode();
+      }
+      let byConfig = byData.get(data);
+      if (byConfig === undefined) {
+        byConfig = createSemanticCache(CONFIG_MEMO_LIMIT);
+        byData.set(data, byConfig);
+      }
+      // structural identity, not a fingerprint: this memo RETURNS the
+      // vnode, so a collision would draw one chart's config as another
+      return byConfig.getOrCreate(config, () => compile(config, data).toVnode());
+    },
+
+    // No app effects yet: rendering is synchronous and pure. Streaming
+    // wiring (timers, sockets) belongs to the host boundary, not here.
+    effects: {},
+  };
+}
+
+/**
+ * The floating-tooltip host: the vnode for the box a `tooltip` binding
+ * asks for. The mark dispatches `{ text, … }` plus the pointer's
+ * `clientX`/`clientY`; an action stores that slice in the state and the
+ * viewModel projects it through here.
+ *
+ * Positioned `fixed` at the viewport coordinates the event carried, so
+ * it needs no measurement and no layout read — the stylesheet's
+ * `translate` lifts it clear of the pointer. `null` (the leave action's
+ * state) renders nothing.
+ *
+ * @example
+ * // viewModel: (state) => ({ ...state, tip: tooltipView(state.tip) })
+ * // action:    { "tip": { "text": "$payload.text",
+ * //                       "x": "$event.clientX", "y": "$event.clientY" } }
+ *
+ * @param {{text?: string, x?: number, y?: number}|null|undefined} tip
+ * @returns {any} a `<div class="chart-tooltip">` vnode, or null
+ */
+export function tooltipView(tip) {
+  if (tip === null || typeof tip !== 'object') return null;
+  const text = tip.text;
+  if (typeof text !== 'string' || text === '') return null;
+  return ['div', {
+    class: 'chart-tooltip',
+    role: 'status',
+    style: {
+      left: `${Number.isFinite(tip.x) ? tip.x : 0}px`,
+      top: `${Number.isFinite(tip.y) ? tip.y : 0}px`,
+    },
+  }, text];
+}

package/src/core/axis.js

@@ -0,0 +1,221 @@
+//@ts-check
+/**
+ * @file Tick generators. Linear ticks snap to a nice-number step
+ * (1/2/5 × 10^k) so an axis never shows values like `12.75`; log ticks
+ * are decade powers (the shape benchmark-ratio charts need, where one
+ * axis spans two orders of magnitude); ordinal ticks center on their
+ * band. Tick *positions* are the caller's job via the matching scale —
+ * these functions return domain values only.
+ */
+
+import { Float64, niceStep } from '@jarenjs/core/math';
+import {
+  partsFromEpoch,
+  epochOfRFC3339Parts,
+  startOfParts,
+  addToParts,
+  compileDateFormat,
+} from '@jarenjs/core/dates';
+
+// The 1/2/5 ladder is generic numeric math, so it lives in the kernel; it is
+// re-exported here because it is part of this module's tick vocabulary.
+export { niceStep };
+
+/**
+ * Linear ticks: multiples of a nice step inside `[min, max]`.
+ * Degenerate domains yield a single tick.
+ * @param {number} min - Domain minimum
+ * @param {number} max - Domain maximum
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]}
+ */
+export function axisTicksLinear(min, max, count = 5) {
+  if (!Number.isFinite(min) || !Number.isFinite(max))
+    return [];
+  if (min === max)
+    return [min];
+  if (min > max)
+    return axisTicksLinear(max, min, count);
+  const step = niceStep(max - min, count);
+  const decimals = Math.max(0, -Math.floor(Math.log10(step)));
+  const ticks = [];
+  const first = Math.ceil(min / step);
+  const last = Math.floor(max / step);
+  for (let i = first; i <= last; ++i)
+    ticks.push(Number((i * step).toFixed(decimals)));
+  return ticks;
+}
+
+/**
+ * Log ticks: the decade powers (… 0.1, 1, 10, 100 …) inside
+ * `[min, max]`. When the domain sits within a single decade the
+ * endpoints are returned so the axis is never empty.
+ * @param {number} min - Domain minimum (> 0)
+ * @param {number} max - Domain maximum (> 0)
+ * @returns {number[]}
+ */
+export function axisTicksLog(min, max) {
+  if (!(min > 0) || !(max > 0))
+    throw new RangeError(`axisTicksLog domain must be positive, got [${min}, ${max}]`);
+  if (min > max)
+    return axisTicksLog(max, min);
+  const ticks = [];
+  const first = Math.ceil(Math.log10(min) - 1e-12);
+  const last = Math.floor(Math.log10(max) + 1e-12);
+  for (let k = first; k <= last; ++k)
+    ticks.push(Math.pow(10, k));
+  return ticks.length !== 0 ? ticks : [min, max];
+}
+
+/**
+ * Ordinal ticks: every category, centered on its band.
+ * @param {readonly string[]} categories - Domain, in display order
+ * @returns {{label: string, pos: number}[]} positions in [0,1]
+ */
+export function axisTicksOrdinal(categories) {
+  const n = categories.length;
+  return categories.map((label, i) => ({ label, pos: (i + 0.5) / n }));
+}
+
+/**
+ * A compact tick label: `1.5k`, `2M`, `1G` for large magnitudes,
+ * 3-significant-digit decimals otherwise.
+ * @param {number} v - Tick value
+ * @returns {string}
+ */
+export function formatTickValue(v) {
+  if (v === 0) return '0';
+  const abs = Math.abs(v);
+  if (abs >= 1e9) return trim(v / 1e9) + 'G';
+  if (abs >= 1e6) return trim(v / 1e6) + 'M';
+  if (abs >= 1e3) return trim(v / 1e3) + 'k';
+  return trim(v);
+}
+
+// The steps a clock and a calendar actually have. The 1/2/5 ladder is
+// right for quantities and wrong for time: it puts ticks 50 seconds or
+// 8.64 days apart, which no reader converts back into a date. Each entry
+// is [unit, amount]; the unit names are the kernel's.
+const TIME_STEPS = Object.freeze([
+  ['second', 1], ['second', 5], ['second', 15], ['second', 30],
+  ['minute', 1], ['minute', 5], ['minute', 15], ['minute', 30],
+  ['hour', 1], ['hour', 3], ['hour', 6], ['hour', 12],
+  ['day', 1], ['day', 2], ['week', 1], ['week', 2],
+  ['month', 1], ['month', 3], ['month', 6],
+  ['year', 1],
+]);
+
+// approximate widths, used only to pick a step near the target count
+const STEP_MS = Object.freeze({
+  second: 1000, minute: 60000, hour: 3600000, day: 86400000,
+  week: 604800000, month: 2629800000, year: 31557600000,
+});
+
+/**
+ * Choose the calendar step closest to covering `span` in `count` ticks.
+ * @param {number} span - Domain width in milliseconds
+ * @param {number} count - Desired tick count
+ * @returns {[string, number]} a [unit, amount] pair
+ */
+export function niceTimeStep(span, count) {
+  const target = span / Math.max(1, count);
+  let best = TIME_STEPS[0];
+  let bestErr = Infinity;
+  for (let i = 0; i < TIME_STEPS.length; i++) {
+    const [unit, amount] = TIME_STEPS[i];
+    const err = Math.abs(Math.log(STEP_MS[unit] * amount / target));
+    if (err < bestErr) {
+      bestErr = err;
+      best = TIME_STEPS[i];
+    }
+  }
+  return best;
+}
+
+/**
+ * Time ticks on calendar boundaries: the first tick is the start of a
+ * `[unit, amount]` step at or after `min`, and each following one is a
+ * whole step later. Month and year steps land on the first of the
+ * month, so a multi-year axis reads `2024 2025 2026` rather than
+ * arbitrary instants.
+ * @param {number} min - Domain minimum, epoch milliseconds
+ * @param {number} max - Domain maximum, epoch milliseconds
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]} tick values in epoch milliseconds
+ */
+export function axisTicksTime(min, max, count = 4) {
+  if (!Number.isFinite(min) || !Number.isFinite(max))
+    return [];
+  if (min === max)
+    return [min];
+  if (min > max)
+    return axisTicksTime(max, min, count);
+  const span = max - min;
+  // below a second the calendar has nothing to say; the numeric ladder does
+  if (span < 1000 * count)
+    return axisTicksLinear(min, max, count);
+  const [unit, amount] = niceTimeStep(span, count);
+  // snap to the step's own boundary, then advance whole steps
+  let parts = startOfParts(partsFromEpoch(min), unit === 'week' ? 'week' : unit);
+  if (unit === 'month' && amount > 1) {
+    // quarters and half-years start on month 1, 4, 7, 10 (or 1, 7)
+    const aligned = Math.floor((parts.month - 1) / amount) * amount + 1;
+    parts = { ...parts, month: aligned };
+  }
+  const ticks = [];
+  let ms = epochOfRFC3339Parts(parts);
+  if (ms < min) {
+    parts = addToParts(parts, amount, unit);
+    ms = epochOfRFC3339Parts(parts);
+  }
+  // the step is never zero, so this terminates; the cap is a guard
+  // against a pathological domain rather than an expected path
+  for (let i = 0; ms <= max && i < 1000; i++) {
+    ticks.push(ms);
+    parts = addToParts(parts, amount, unit);
+    ms = epochOfRFC3339Parts(parts);
+  }
+  return ticks;
+}
+
+// label patterns by how coarse the step is, compiled once
+const LABEL_SECOND = compileDateFormat('HH:mm:ss');
+const LABEL_MINUTE = compileDateFormat('HH:mm');
+const LABEL_DAY = compileDateFormat('yyyy-MM-dd');
+const LABEL_MONTH = compileDateFormat('yyyy-MM');
+const LABEL_YEAR = compileDateFormat('yyyy');
+
+/**
+ * A time-axis tick label in UTC (deterministic across machines).
+ *
+ * With a `step` the label matches the step's granularity — clock time
+ * for intraday ticks, a date for daily ones, a month or year above that
+ * — so an axis never repeats the same string on every tick. Without one
+ * it keeps the historical behaviour: `HH:MM:SS`, or the date when the
+ * value sits exactly on a day boundary.
+ *
+ * @param {number|Date} v - Epoch milliseconds or a Date
+ * @param {[string, number]} [step] - The [unit, amount] the axis stepped by
+ * @returns {string}
+ */
+export function formatTimeTick(v, step = undefined) {
+  const ms = typeof v === 'number' ? v : v.getTime();
+  const parts = partsFromEpoch(ms);
+  if (step === undefined) {
+    return parts.hours === 0 && parts.minutes === 0 && parts.seconds === 0
+      ? LABEL_DAY(parts)
+      : LABEL_SECOND(parts);
+  }
+  const unit = step[0];
+  if (unit === 'second')
+    return LABEL_SECOND(parts);
+  if (unit === 'minute' || unit === 'hour')
+    return LABEL_MINUTE(parts);
+  if (unit === 'day' || unit === 'week')
+    return LABEL_DAY(parts);
+  return unit === 'month' ? LABEL_MONTH(parts) : LABEL_YEAR(parts);
+}
+
+function trim(x) {
+  return String(Float64.roundToPrecision(x, 3));
+}

package/src/core/cartesian.js

@@ -0,0 +1,192 @@
+//@ts-check
+/**
+ * @file The shared cartesian chrome: plot frame, axes, grid, legend and
+ * title, rendered from an AST's tick lists. Chart types append their
+ * marks inside the returned plot rect. All positions arrive in unit
+ * space (`pos`/`u`/`v` in [0,1], `v = 0` at the domain minimum, drawn
+ * at the plot bottom); pixel mapping happens only here and in the
+ * callers' mark loops.
+ */
+
+import { line as svgLine, textAt, textWidth, num } from '@jarenjs/view/helpers';
+import { seriesColor } from './palette.js';
+
+export const FS_TICK = 11;
+export const FS_LABEL = 12;
+export const FS_TITLE = 15;
+
+/**
+ * Resolve a mark color: semantic tone first, series palette otherwise.
+ * @param {{tokens: Record<string,string>}} theme
+ * @param {'win'|'loss'|null|undefined} tone
+ * @param {number} i series index
+ * @param {readonly string[]} [palette]
+ * @returns {string}
+ */
+export function toneColor(theme, tone, i, palette) {
+  if (tone === 'win') return theme.tokens.win;
+  if (tone === 'loss') return theme.tokens.loss;
+  return seriesColor(i, palette);
+}
+
+/**
+ * Truncate a label so it fits `maxWidth` at `fontSize`, appending an
+ * ellipsis when anything was cut.
+ * @param {string} label
+ * @param {number} maxWidth
+ * @param {number} fontSize
+ * @returns {string}
+ */
+export function fitLabel(label, maxWidth, fontSize) {
+  if (textWidth(label, fontSize) <= maxWidth) return label;
+  let end = label.length;
+  while (end > 1 && textWidth(label.slice(0, end) + '…', fontSize) > maxWidth)
+    end--;
+  return label.slice(0, end) + '…';
+}
+
+/**
+ * The chart title `<text>`: bold, centred on `x`, carrying the
+ * `chart-title` class the chart stylesheet hooks. Every chart type places
+ * its own title — the anchor point and size are part of each type's
+ * layout — so those stay the caller's, and only the styling is shared.
+ * @param {number} x anchor (the title centres on it)
+ * @param {number} y baseline
+ * @param {string} text
+ * @param {number} fontSize
+ * @param {Record<string,string>} tokens the resolved theme tokens
+ * @returns {any}
+ */
+export function chartTitle(x, y, text, fontSize, tokens) {
+  return textAt(x, y, text, fontSize,
+    { 'font-weight': 'bold', 'text-anchor': 'middle', fill: tokens.text, class: 'chart-title' });
+}
+
+/**
+ * @typedef {{name: string, swatch?: number, tone?: 'win'|'loss'|null}} LegendEntry
+ */
+
+/**
+ * The legend swatch row, laid out right-to-left from `right` so the last
+ * entry ends at the plot's right edge. Returns the vnodes rather than
+ * drawing, so a chart with no cartesian frame at all (the map) can place
+ * the same row itself.
+ * @param {LegendEntry[]} legend
+ * @param {number} right the x the row ends at
+ * @param {number} y the swatches' top edge
+ * @param {{tokens: Record<string,string>}} theme
+ * @param {readonly string[]} [palette]
+ * @returns {any[]}
+ */
+export function legendRow(legend, right, y, theme, palette) {
+  let x = right;
+  const entries = [];
+  for (let i = legend.length - 1; i >= 0; i--) {
+    const entry = legend[i];
+    const label = entry.name;
+    const w = Math.ceil(textWidth(label, FS_TICK));
+    x -= w + 4;
+    entries.push(textAt(x + 14, y + 9, label, FS_TICK, { fill: theme.tokens.muted, class: 'chart-tick' }));
+    x -= 14;
+    entries.push(['rect', {
+      x: num(x), y: num(y), width: 10, height: 10,
+      fill: toneColor(theme, entry.tone, entry.swatch ?? i, palette),
+      class: 'chart-swatch',
+    }]);
+    x -= 14;
+  }
+  return entries;
+}
+
+/**
+ * @typedef {{ticks: {pos: number, label: string}[], label?: string|null}} AxisAST
+ */
+
+/**
+ * Compute the plot frame and render the chart chrome.
+ * @param {object} params
+ * @param {string|null} [params.title]
+ * @param {{name: string, swatch?: number, tone?: 'win'|'loss'|null}[]|null} [params.legend]
+ * @param {AxisAST} [params.xAxis] ticks along the bottom edge
+ * @param {AxisAST} [params.yAxis] ticks along the left edge
+ * @param {'x'|'y'|'xy'|'none'} [params.grid] which tick sets draw grid lines
+ * @param {number} [params.width]
+ * @param {number} [params.plotHeight]
+ * @param {readonly string[]} [params.palette]
+ * @param {{tokens: Record<string,string>}} params.theme
+ * @returns {{width: number, height: number, plot: {x:number,y:number,w:number,h:number}, children: any[]}}
+ */
+export function cartesianFrame(params) {
+  const t = params.theme.tokens;
+  const width = params.width ?? 560;
+  const xAxis = params.xAxis ?? { ticks: [] };
+  const yAxis = params.yAxis ?? { ticks: [] };
+  const grid = params.grid ?? 'y';
+  const legend = params.legend ?? null;
+  const yTickW = Math.max(0, ...yAxis.ticks.map((tk) => textWidth(tk.label, FS_TICK)));
+  const left = Math.ceil(Math.max(30, Math.min(230, yTickW) + 14)) + (yAxis.label ? 18 : 0);
+  const top = (params.title ? 34 : 14) + (legend !== null && legend.length !== 0 ? 22 : 0);
+  const right = 16;
+  const bottom = 32 + (xAxis.label ? 18 : 0);
+  const plotH = params.plotHeight ?? 220;
+  const height = top + plotH + bottom;
+  const plot = { x: left, y: top, w: width - left - right, h: plotH };
+  const children = [];
+
+  if (params.title) {
+    children.push(chartTitle(width / 2, 22, params.title, FS_TITLE, t));
+  }
+
+  if (legend !== null && legend.length !== 0) {
+    children.push(...legendRow(legend, plot.x + plot.w, plot.y - 10, params.theme, params.palette));
+  }
+
+  for (const tick of yAxis.ticks) {
+    const y = plot.y + (1 - tick.pos) * plot.h;
+    if (grid === 'y' || grid === 'xy')
+      children.push(svgLine(plot.x, y, plot.x + plot.w, y, { stroke: t.grid, 'stroke-width': 1, class: 'chart-grid' }));
+    children.push(textAt(plot.x - 6, y + 4, fitLabel(tick.label, 230, FS_TICK), FS_TICK,
+      { 'text-anchor': 'end', fill: t.muted, class: 'chart-tick' }));
+  }
+  for (const tick of xAxis.ticks) {
+    const x = plot.x + tick.pos * plot.w;
+    if (grid === 'x' || grid === 'xy')
+      children.push(svgLine(x, plot.y, x, plot.y + plot.h, { stroke: t.grid, 'stroke-width': 1, class: 'chart-grid' }));
+    children.push(textAt(x, plot.y + plot.h + 16,
+      fitLabel(tick.label, Math.max(40, plot.w / Math.max(1, xAxis.ticks.length) - 8), FS_TICK), FS_TICK,
+      { 'text-anchor': 'middle', fill: t.muted, class: 'chart-tick' }));
+  }
+
+  children.push(svgLine(plot.x, plot.y, plot.x, plot.y + plot.h, { stroke: t.axis, 'stroke-width': 1, class: 'chart-axis' }));
+  children.push(svgLine(plot.x, plot.y + plot.h, plot.x + plot.w, plot.y + plot.h, { stroke: t.axis, 'stroke-width': 1, class: 'chart-axis' }));
+
+  if (xAxis.label) {
+    children.push(textAt(plot.x + plot.w / 2, height - 8, xAxis.label, FS_LABEL,
+      { 'text-anchor': 'middle', fill: t.muted, class: 'chart-axis-label' }));
+  }
+  if (yAxis.label) {
+    children.push(['text', {
+      x: 0, y: 0, 'font-size': FS_LABEL, fill: t.muted, 'text-anchor': 'middle',
+      transform: `rotate(-90) translate(${num(-(plot.y + plot.h / 2))} 12)`,
+      class: 'chart-axis-label',
+    }, String(yAxis.label)]);
+  }
+
+  return { width, height, plot, children };
+}
+
+/**
+ * Stamp accessibility onto a finished chart svg vnode: an `aria-label`
+ * (the title) and a leading `<title>` child for hover text. `svgRoot`
+ * already sets `role="img"`.
+ * @param {any} svg the `['svg', props, …]` vnode (mutated in place)
+ * @param {string|null|undefined} label
+ * @returns {any} the same vnode
+ */
+export function annotateChart(svg, label) {
+  if (label) {
+    svg[1]['aria-label'] = String(label);
+    svg.splice(2, 0, ['title', {}, String(label)]);
+  }
+  return svg;
+}

package/src/core/chart.js

@@ -0,0 +1,101 @@
+//@ts-check
+/**
+ * @file `compileChart` — the type dispatcher. Compiles a chart
+ * definition plus its data into a bundle of cached projections
+ * (the `compileMermaid` shape): the geometry-free AST, a pure-vnode
+ * SVG, and a standalone SVG string.
+ *
+ * Memoization strategy (deliberate, see the component layer): identity
+ * of the *data object* is the cache key, held in a WeakMap by
+ * `createChartComponent` — never a hash of the object itself, which
+ * would stringify every object to `"[object Object]"` and collide
+ * universally. `contentKey` (the memo-grade stable-stringify hash from
+ * `@jarenjs/core/object`) derives the root vnode key from the config.
+ */
+
+import { renderToString } from '@jarenjs/view';
+import { contentKey } from '@jarenjs/core/object';
+
+import { createTheme } from './palette.js';
+import { buildPieAST, renderPieAST } from '../types/pie.js';
+import { buildBarAST, renderBarAST } from '../types/bar.js';
+import { buildLineAST, renderLineAST } from '../types/line.js';
+import { buildScatterAST, renderScatterAST } from '../types/scatter.js';
+import { buildCandlestickAST, renderCandlestickAST } from '../types/candlestick.js';
+import { buildRadarAST, renderRadarAST } from '../types/radar.js';
+import { buildGaugeAST, renderGaugeAST } from '../types/gauge.js';
+import { buildBoxplotAST, renderBoxplotAST } from '../types/boxplot.js';
+import { buildHeatmapAST, renderHeatmapAST } from '../types/heatmap.js';
+import { buildTreemapAST, renderTreemapAST } from '../types/treemap.js';
+import { buildStreamgraphAST, renderStreamgraphAST } from '../types/streamgraph.js';
+import { buildSankeyAST, renderSankeyAST } from '../types/sankey.js';
+import { buildMapAST, renderMapAST } from '../types/map.js';
+
+/** @type {Record<string, {build: (data: any, config: any) => any, render: (ast: any, theme: any, hash: string, options?: any) => any}>} */
+const TYPES = {
+  pie: { build: buildPieAST, render: renderPieAST },
+  bar: { build: buildBarAST, render: renderBarAST },
+  line: { build: buildLineAST, render: renderLineAST },
+  scatter: { build: buildScatterAST, render: renderScatterAST },
+  candlestick: { build: buildCandlestickAST, render: renderCandlestickAST },
+  radar: { build: buildRadarAST, render: renderRadarAST },
+  gauge: { build: buildGaugeAST, render: renderGaugeAST },
+  boxplot: { build: buildBoxplotAST, render: renderBoxplotAST },
+  heatmap: { build: buildHeatmapAST, render: renderHeatmapAST },
+  treemap: { build: buildTreemapAST, render: renderTreemapAST },
+  streamgraph: { build: buildStreamgraphAST, render: renderStreamgraphAST },
+  sankey: { build: buildSankeyAST, render: renderSankeyAST },
+  map: { build: buildMapAST, render: renderMapAST },
+};
+
+/**
+ * The chart types the dispatcher knows.
+ * @returns {string[]}
+ */
+export function chartTypes() {
+  return Object.keys(TYPES);
+}
+
+/**
+ * @typedef {object} CompiledChart
+ * @property {any} ast the geometry-free AST
+ * @property {() => any} toVnode cached pure-vnode SVG
+ * @property {() => string} toSvgString cached standalone SVG string (SSR)
+ */
+
+/**
+ * Compile a chart definition. `config` carries the type and
+ * presentation fields; `data` carries the series/slices and defaults to
+ * the config object itself, so a single self-contained definition
+ * document works while streaming callers pass live data separately.
+ *
+ * @param {{type: string, title?: string, [k: string]: any}} config
+ * @param {any} [data]
+ * @param {{theme?: any, tooltip?: import('./marks.js').ChartTooltipSpec}} [options]
+ * @returns {CompiledChart}
+ * @throws {TypeError} On an unknown chart type
+ */
+export function compileChart(config, data = config, options = {}) {
+  const def = TYPES[config?.type];
+  if (def === undefined)
+    throw new TypeError(`unknown chart type '${config?.type}'`);
+  const ast = def.build(data, config);
+  const theme = createTheme(options.theme);
+  const hash = contentKey(config);
+  // Only the render half takes options; passing the object through
+  // whole would let a `theme` member reach a type's palette options.
+  const renderOptions = options.tooltip === undefined ? undefined : { tooltip: options.tooltip };
+  let vnode;
+  let svg;
+  return {
+    ast,
+    toVnode() {
+      if (vnode === undefined) vnode = def.render(ast, theme, hash, renderOptions);
+      return vnode;
+    },
+    toSvgString() {
+      if (svg === undefined) svg = renderToString(this.toVnode());
+      return svg;
+    },
+  };
+}