@jarenjs/charts 0.34.0

package/README.md

@@ -0,0 +1,293 @@
+# @jarenjs/charts
+
+**Headless charts** for the jaren suite: a chart definition plus its
+data compiled to a **geometry-free AST** and rendered as **pure-vnode
+SVG** through [`@jarenjs/view`](../../packages/view) — no `innerHTML`,
+no browser, no third-party chart library. Thirteen types: `pie` (with a
+donut variant), `bar` (grouped/stacked, vertical/horizontal,
+linear/log), `line` (linear/time/log, the streaming-critical type),
+`scatter` (log axes, win/loss tones, reference line), `candlestick`
+(OHLC on a time axis), `radar`, `gauge`, `boxplot` (raw samples or
+five-number summaries, Tukey whiskers), `heatmap` (sequential blue
+ramp, linear or log), `treemap` (squarified), `streamgraph`
+(silhouette baseline), `sankey` (layered flows, cycle-safe) and `map`
+(GeoJSON in Web Mercator, shaded by a feature property). Like
+[`@jarenjs/mermaid`](../mermaid), it ships in **two layers**: a pure
+engine (definition + data ⇄ AST ⇄ vnode) that knows only the vnode
+shape, and a visual component that packages it for an `@jarenjs/app`
+host.
+
+## A chart in one glance
+
+```js
+import { compileChart } from '@jarenjs/charts';
+
+const compiled = compileChart({
+  type: 'pie',
+  title: 'Pets',
+  slices: [
+    { label: 'Dogs', value: 40 },
+    { label: 'Cats', value: 25 },
+    { label: 'Birds', value: 10 },
+  ],
+});
+
+compiled.ast;           // geometry-free: fractions and angles, no pixels
+compiled.toVnode();     // ['svg', { viewBox, … }, …] — a pure-vnode SVG
+compiled.toSvgString(); // standalone SVG text (SSR), colors baked in
+```
+
+`config` carries the type and presentation fields; the data fields
+(`slices`, …) default to the same object, so one self-contained
+definition document works — while streaming callers pass live data as a
+separate second argument: `compileChart(config, adapter.getData())`.
+
+## The component (for `@jarenjs/app` hosts)
+
+```js
+import { createChartComponent } from '@jarenjs/charts/component';
+
+const charts = createChartComponent({ theme: 'host' });
+createApp(appDoc, {
+  viewModel: (state) => ({ ...state, chart: charts.view(state.config, state.data) }),
+});
+```
+
+`view()` memoizes on the **data object's identity** (a WeakMap): the
+same `(config, data)` pair returns a reference-equal vnode, so an
+unchanged chart patches in O(1); a fresh streaming snapshot re-renders.
+
+## The definition shapes
+
+Every type reads its data from the definition document (or the
+separate `data` argument). The type-specific fields, briefly:
+
+| type | data fields |
+|---|---|
+| `pie` | `slices: [{label, value}]`; `donut: true` or a hole fraction in (0, 1) |
+| `bar` | `categories`, `series: [{name, values}]`; `stacked`, `log`, `orient` |
+| `line` | `series: [{name, points: [{x, y}]}]`; `x: 'time'`, `log`, `markers` |
+| `scatter` | `points: [{x, y, tone?}]`; `xLog`/`yLog`, `refY`/`refLabel` |
+| `candlestick` | `candles: [{t, open, high, low, close}]` |
+
+**Time axes.** An `x: 'time'` axis (and every `candlestick`) accepts epoch milliseconds, a `Date`, or an **RFC 3339 string** — a date in a JSON document plots without being pre-converted, and a bare `2026-07-27` reads as UTC midnight. A *numeric* string still does not coerce: accepting `"5"` where the config asked for a number is a type confusion, not a date.
+
+Ticks land on calendar boundaries rather than on the 1/2/5 ladder, because a quantity axis and a clock have different nice numbers — the ladder puts ticks 50 seconds or 8.64 days apart, which no reader converts back into a time. Steps come from a clock/calendar ladder (1/5/15/30 seconds and minutes, 1/3/6/12 hours, 1/2 days, 1/2 weeks, 1/3/6 months, years), and the label granularity follows the step, so an axis never repeats one string on every tick:
+
+```javascript
+axisTicksTime(Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));  // → 2024, 2025, 2026, 2027
+axisTicksTime(Date.UTC(2026, 6, 27, 0), Date.UTC(2026, 6, 27, 6));  // → 00:00 … 06:00
+```
+| `radar` | `axes: string[]`, `series: [{name, values}]`; `max` pins the domain, `labelEvery` the spoke-label stride |
+| `gauge` | `value`; `min`/`max` (0..100 default), `unit`, `tone` |
+| `boxplot` | `boxes: [{label, values}]` raw, or `{label, min, q1, med, q3, max, outliers?}` |
+| `heatmap` | `xLabels`, `yLabels`, `values[yi][xi]` (row-major from the top); `log` |
+| `treemap` | `items: [{label, value}]` or `[{label, children: [{label, value}]}]`; `aspect` (default 1.6) |
+| `streamgraph` | `series: [{name, values}]`, optional numeric `xs` |
+| `sankey` | `links: [{source, target, value}]` by name or index; `nodes` optional |
+
+The full contract is `schemas/chart-definition.schema.json`.
+
+## Hover text and tooltips
+
+Every value-carrying mark — slice, bar, dot, candle, cell, tile,
+ribbon, band, series — renders a `<title>` child naming it and its
+exact value. That is native hover text: it works in a static
+`toSvgString()` document with no script, no CSS and no app, so it is
+always on. Marks report the datum, not the axis's rounded tick scale,
+which is the only way to read a value back off a log axis.
+
+For a positioned, styled tooltip instead, ask for **bindings**:
+
+```js
+const compiled = compileChart(config, data, {
+  tooltip: { action: 'chartHover', leaveAction: 'chartLeave' },
+});
+```
+
+Each mark then carries an `on` binding (VIEW-FORMAT §4) naming that
+action, with the mark's descriptor as the payload and the pointer's
+`clientX`/`clientY` requested as `$event` fields. Bindings are plain
+JSON built at render time — the engine names an action, it never calls
+one — and `renderToString` drops `on`, so the SSR bytes do not change.
+The `@jarenjs/app` half is three lines and a projection:
+
+```js
+const charts = createChartComponent({ theme: 'host', tooltip: { action: 'chartHover', leaveAction: 'chartLeave' } });
+// action chartHover: { "tip": { "text": "$payload.text", "x": "$event.clientX", "y": "$event.clientY" } }
+// action chartLeave: { "tip": null }
+// viewModel:         (state) => ({ ...state, tip: tooltipView(state.tip) })
+```
+
+`tooltipView` (from `@jarenjs/charts/component`) returns the floating
+box positioned at those viewport coordinates; `styles/charts.css`
+carries its `.chart-tooltip` rules.
+
+## Scales, axes, palette
+
+The core primitives are exported for reuse; scales are pure
+`domain -> (value) => [0,1]` closures and axes generate nice-number
+ticks (`1/2/5 × 10^k`) or log decades:
+
+```js
+import {
+  scaleLinear, scaleLog, scaleBand, scaleTime,
+  axisTicksLinear, axisTicksLog, CATEGORICAL, SEQUENTIAL,
+} from '@jarenjs/charts';
+```
+
+The categorical palette is a concrete constant in the suite's anchor
+order (blue first, amber second, teal third — no pink, no purple, per
+the repo's docs/DESIGN.md), and `SEQUENTIAL` is its magnitude counterpart:
+a single-hue blue ramp, light→dark, sampled continuously by
+`sequentialColor(t)` (the heatmap's cell fill). The semantic tokens
+(text/grid/axis, win/loss) resolve through the shared `resolveTheme`
+kernel and can be host-linked with `theme: 'host'`, so charts follow
+the site's light/dark flip live without a re-render.
+
+## Streaming (the adapter)
+
+`@jarenjs/charts/stream-adapter` turns the unified reader events of
+[`@jarenjs/josl`](../../packages/josl)'s streaming readers into chart
+data — it consumes **events, never a reader**, so this package has no
+parser dependency and any event source with the same `pair` shape
+works:
+
+```js
+import { createJsonxStreamReader } from '@jarenjs/josl/jsonx-stream';
+import { createStreamAdapter } from '@jarenjs/charts/stream-adapter';
+import { compileChart } from '@jarenjs/charts';
+
+const adapter = createStreamAdapter('line', {
+  recordPath: ['run'],          // records live at {"run": [...]} / [[run]]
+  xField: 'i', yField: 'ops', seriesField: 'suite',
+  maxPoints: 200,               // ring-buffer eviction
+});
+const reader = createJsonxStreamReader({ mode: 'json', onEvent: adapter.onEvent });
+
+for await (const chunk of feed) {          // chunks may split ANY token
+  reader.feed(chunk);
+  render(compileChart({ type: 'line' }, adapter.getData()).toVnode());
+}
+reader.end();
+adapter.endDocument();
+```
+
+Two record boundaries cover the two streaming shapes: `'path'` (one
+large document arriving in chunks — records close when the event path
+leaves them) and `'document'` (many small complete documents, e.g. one
+WebSocket message each — `endDocument()` closes the record;
+`abortDocument()` discards a malformed one). Six accumulators:
+
+| type | what a record contributes | fields |
+|---|---|---|
+| `line` | a point on a series, ring-buffer evicted | `xField`, `yField`, `seriesField` |
+| `bar` | +1 (or `+yField`) on a category | `xField`, `yField?` |
+| `heatmap` | the same, under two grouping keys | `xField` (column), `seriesField` (row), `yField?` |
+| `gauge` | the latest reading; nothing is kept | `yField` |
+| `candlestick` | a candle keyed by open time; a re-delivered key replaces it (exchange kline semantics) | `xField`, `openField`… |
+| `map` | a whole GeoJSON Feature, projected and simplified on arrival | `labelField?`, `valueField?`, `simplify?`, `aspect?` |
+
+A heatmap cell nobody measured stays `null` rather than `0` — the
+surface shows through, which is the honest rendering of "no
+measurement" — and a gauge with no reading yet is `null`, not zero.
+
+The `map` accumulator is the odd one out: its record is not flat pair
+fields but a complete Feature, consumed from the reader's `object-end`
+events at `recordPath + [index]` (default `['features']`) — pair the
+reader with `detach: ['features', '*']` so the document root retains
+nothing and the accumulator's reduced set is the only retention. Each
+feature's geometry is simplified **on arrival** to the vertices a
+drawing of the current extent could distinguish, so memory is bounded
+by the drawn detail rather than the source detail. The projection
+cannot be fitted before the last feature has been seen, so the design
+is refit-on-growth: the running bbox sets the tolerance, and when it
+grows enough to double it, the kept features are coarsened once against
+the new extent (never re-read — early features can only be finer than
+needed, not wrong). `simplify: false` keeps every vertex, which unbounds
+memory again; `test/charts/map-stream.test.js` pins the reduction, the
+refit and the change-feed replay.
+
+## Incremental sessions (O(1) ticks)
+
+A snapshot re-render is O(n): every point is re-projected because a
+unit-space AST stores positions as *fractions of the domain*, so a
+tick that moves the scales legitimately changes every mark. Declare a
+**domain policy** and most ticks stop moving them — then
+`createChartSession` patches only what changed:
+
+```js
+const adapter = createStreamAdapter('line', { …, changes: true });
+const session = createChartSession({
+  type: 'line',
+  domain: { y: 'step', x: { window: 60_000, slide: 15_000 } },
+}, adapter);
+
+reader.feed(chunk);
+const { vnode, mode } = session.tick();  // 'incremental' | 'rebuilt' | 'unchanged'
+```
+
+`{ changes: true }` makes the adapter buffer its mutations as RFC 6902
+ops (`takeChanges()`); the session applies them to the previous AST and
+rebuilds only the touched series — every other child stays
+**reference-equal**, so the patcher skips it in O(1). Domain policies:
+
+| policy | effect |
+|---|---|
+| `x: { window, slide }` | sliding window whose end is quantized to `slide` — the domain moves once per quantum, not per sample |
+| `y: { min, max }` | pinned bounds; out-of-range samples clamp to the plot edge |
+| `y: 'step'` | bounds snap outward to nice-number steps (decades under `log`) |
+
+**The fallback is the design, not a failure mode.** When the domain
+*does* move — or a new series appears, or the source resets — the
+session rebuilds wholesale, because that is the correct rendering of a
+frame whose scales moved. `mode` reports which path ran. The
+correctness contract is byte equality: every tick's vnode serializes
+identically to a wholesale `compileChart()` of the same data, which is
+property-tested over thousands of random frames rather than assumed.
+
+Measured (`npm run benchmark:charts`, one appended point):
+
+| points × series | session tick | wholesale tick |
+|---|---|---|
+| 100 × 5 | ~8 µs | ~319 µs |
+| 1 000 × 5 | ~4.6 µs | ~1.03 ms |
+| 10 000 × 5 | ~4.2 µs | ~11.3 ms |
+
+The session tick is *flat* in n (10 000 points cost no more than 100)
+while the wholesale tick grows 35×. Supported types: `line` (appends
+and ring-buffer evictions), `bar` (live counts and sums) and
+`candlestick` (keyed kline upserts — one candle group re-renders). The
+website's Binance demo runs on it.
+
+A bar chart's stillness test is the nice-number top rather than a
+declared policy: a count below it repaints one rect, a count that
+pushes the axis higher rebuilds. A new category rebuilds too — every
+band width and position moves with it — and so does a stacked chart,
+where one value shifts every bar above it in its category.
+
+| categories | session tick | wholesale tick |
+|---|---|---|
+| 20 | ~5.7 µs | ~33 µs |
+| 200 | ~11 µs | ~137 µs |
+
+Only the *vnode* work is O(1) there — one rect re-emitted instead of
+all of them. The stillness test still rescans every category (a count
+that drops can retire the tallest bar, so extremes cannot be extended)
+and the adapter rebuilds its snapshot arrays, so the bar session's tick
+does grow with the category count. It grows about 2× where the
+wholesale render grows about 4×; the line session's flatness is the
+stronger claim, and this is deliberately the weaker one.
+
+## Mermaid interop
+
+`@jarenjs/mermaid` delegates its `pie` diagrams here (the arrow is
+mermaid → charts, never the reverse); the
+`@jarenjs/charts/transforms/mermaid-adapter` transform maps a mermaid
+pie AST onto `compileChart` inputs.
+
+## Validation
+
+`schemas/chart-definition.schema.json` describes the definition
+document; validate untrusted definitions with `@jarenjs/validate`
+before compiling.

package/dist/types/component/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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.
+ */
+export type ChartComponentOptions = {
+    /**
+     * theme name or override object
+     */
+    theme?: any;
+    /**
+     * pointer
+     * bindings emitted from every value mark, for a floating-tooltip host
+     * (see {@link tooltipView}); absent leaves charts on their native
+     * `<title>` hover only
+     */
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+};
+export type ChartComponent = {
+    compile: (config: any, data?: any) => import('../core/chart.js').CompiledChart;
+    /**
+     * memoized vnode projection
+     */
+    view: (config: any, data?: any) => any;
+    /**
+     * incremental
+     * session bound to this component's theme
+     */
+    createSession: (config: any, source: import('../core/session.js').ChartSessionSource) => import('../core/session.js').ChartSession;
+    effects: Record<string, (props: any, dispatch: any) => any>;
+};
+/**
+ * @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 declare function createChartComponent(options?: ChartComponentOptions): ChartComponent;
+/**
+ * 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 declare function tooltipView(tip: {
+    text?: string;
+    x?: number;
+    y?: number;
+} | null | undefined): any;

package/dist/types/core/axis.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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 { niceStep } from '@jarenjs/core/math';
+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 declare function axisTicksLinear(min: number, max: number, count?: number): number[];
+/**
+ * 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 declare function axisTicksLog(min: number, max: number): number[];
+/**
+ * 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 declare function axisTicksOrdinal(categories: readonly string[]): {
+    label: string;
+    pos: number;
+}[];
+/**
+ * A compact tick label: `1.5k`, `2M`, `1G` for large magnitudes,
+ * 3-significant-digit decimals otherwise.
+ * @param {number} v - Tick value
+ * @returns {string}
+ */
+export declare function formatTickValue(v: number): string;
+/**
+ * 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 declare function niceTimeStep(span: number, count: number): [string, number];
+/**
+ * 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 declare function axisTicksTime(min: number, max: number, count?: number): number[];
+/**
+ * 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 declare function formatTimeTick(v: number | Date, step?: [string, number]): string;

package/dist/types/core/cartesian.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @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.
+ */
+export declare const FS_TICK = 11;
+export declare const FS_LABEL = 12;
+export declare 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 declare function toneColor(theme: {
+    tokens: Record<string, string>;
+}, tone: 'win' | 'loss' | null | undefined, i: number, palette?: readonly string[]): string;
+/**
+ * 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 declare function fitLabel(label: string, maxWidth: number, fontSize: number): string;
+/**
+ * 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 declare function chartTitle(x: number, y: number, text: string, fontSize: number, tokens: Record<string, string>): any;
+export type LegendEntry = {
+    name: string;
+    swatch?: number;
+    tone?: 'win' | 'loss' | null;
+};
+/**
+ * @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 declare function legendRow(legend: LegendEntry[], right: number, y: number, theme: {
+    tokens: Record<string, string>;
+}, palette?: readonly string[]): any[];
+export type AxisAST = {
+    ticks: {
+        pos: number;
+        label: string;
+    }[];
+    label?: string | null;
+};
+/**
+ * @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 declare function cartesianFrame(params: {
+    title?: string | null;
+    legend?: {
+        name: string;
+        swatch?: number;
+        tone?: 'win' | 'loss' | null;
+    }[] | null;
+    xAxis?: AxisAST;
+    yAxis?: AxisAST;
+    grid?: 'x' | 'y' | 'xy' | 'none';
+    width?: number;
+    plotHeight?: number;
+    palette?: readonly string[];
+    theme: {
+        tokens: Record<string, string>;
+    };
+}): {
+    width: number;
+    height: number;
+    plot: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    children: any[];
+};
+/**
+ * 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 declare function annotateChart(svg: any, label: string | null | undefined): any;

package/dist/types/core/chart.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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.
+ */
+/**
+ * The chart types the dispatcher knows.
+ * @returns {string[]}
+ */
+export declare function chartTypes(): string[];
+export type CompiledChart = {
+    /**
+     * the geometry-free AST
+     */
+    ast: any;
+    /**
+     * cached pure-vnode SVG
+     */
+    toVnode: () => any;
+    /**
+     * cached standalone SVG string (SSR)
+     */
+    toSvgString: () => string;
+};
+/**
+ * @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 declare function compileChart(config: {
+    type: string;
+    title?: string;
+    [k: string]: any;
+}, data?: any, options?: {
+    theme?: any;
+    tooltip?: import('./marks.js').ChartTooltipSpec;
+}): CompiledChart;