@svgrid/grid 3.0.0 → 3.0.2

package/dist/chart.js

@@ -1,3 +1,97 @@
+/**
+ * Integrated chart geometry. Pure functions that turn categories + numeric
+ * series into SVG primitives - the "chart from a grid range" enterprise
+ * feature without bundling a charting library. The `<SvGridChart>` component
+ * paints the result; this module has no DOM so it is unit-testable.
+ *
+ * Supports: grouped + stacked bars, line, area, pie/donut, combo charts
+ * (per-series type), a secondary (right) Y axis, signed Y domains (negative
+ * values drop below a zero baseline), and nice auto-scaled ticks.
+ */
+// The one import this module has. `Intl.NumberFormat` is expensive enough to
+// construct that a chart with 8 axis ticks and 200 data labels would rebuild it
+// 200 times a frame, and the grid already solved that for cells - so reuse that
+// cache rather than starting a second one. Still DOM-free: it is plain TS.
+import { getNumberFormatter } from './cell-formatting.js';
+/**
+ * Five-number summary of a raw sample, with the 1.5 IQR whisker rule.
+ *
+ * Whiskers stop at the last observation INSIDE the fence rather than at the
+ * fence itself, which is what makes them read as real data; anything past them
+ * comes back in `outliers`. Quartiles use linear interpolation between the two
+ * neighbouring order statistics.
+ *
+ * Returns `null` for an empty sample, so a category with no observations is a
+ * gap rather than a box drawn at zero.
+ */
+export function boxStats(sample, whisker = 1.5) {
+    const v = sample.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b);
+    if (!v.length)
+        return null;
+    const q = (p) => {
+        const pos = (v.length - 1) * p;
+        const lo = Math.floor(pos);
+        const hi = Math.ceil(pos);
+        return lo === hi ? v[lo] : v[lo] + (v[hi] - v[lo]) * (pos - lo);
+    };
+    const q1 = q(0.25);
+    const median = q(0.5);
+    const q3 = q(0.75);
+    const fenceLo = q1 - whisker * (q3 - q1);
+    const fenceHi = q3 + whisker * (q3 - q1);
+    const inside = v.filter((n) => n >= fenceLo && n <= fenceHi);
+    const outliers = v.filter((n) => n < fenceLo || n > fenceHi);
+    return {
+        // `inside` can only be empty if every point is an outlier, which the fence
+        // rule makes impossible (q1 and q3 are always within it) - but a degenerate
+        // sample should still produce a box rather than `undefined` coordinates.
+        min: inside.length ? inside[0] : v[0],
+        q1,
+        median,
+        q3,
+        max: inside.length ? inside[inside.length - 1] : v[v.length - 1],
+        ...(outliers.length ? { outliers } : {}),
+    };
+}
+/**
+ * Category-axis labels, thinned so they do not overlap.
+ *
+ * A category axis used to emit one tick per category however many there were.
+ * At 5000 categories that is 5000 `<text>` nodes stacked into an unreadable
+ * grey band - the labels were the single biggest thing the renderer had to put
+ * in the DOM, and none of them could be read. The time and ordinal-time axes
+ * already thinned themselves (`dateTicks` / `ordinalDateTicks`); this brings
+ * the plain category axis in line.
+ *
+ * The first category always gets a label, so a thinned axis still starts where
+ * the data does.
+ */
+function thinCategoryTicks(categories, xCenter, slot, rotated) {
+    // Rotated labels run diagonally and pack far tighter than upright ones. 18px
+    // is deliberately just under the spacing a 40-category chart at 800px already
+    // had, so charts that read fine before are untouched and only genuinely
+    // overlapping axes get thinned.
+    const minPx = rotated ? 18 : 60;
+    const step = Math.max(1, Math.ceil(minPx / Math.max(slot, 0.001)));
+    const out = [];
+    for (let i = 0; i < categories.length; i += step)
+        out.push({ label: categories[i], x: xCenter(i) });
+    return out;
+}
+/** Normalize one `errors` entry to an absolute low/high pair around `value`. */
+function errorSpan(e, value) {
+    if (e == null)
+        return null;
+    if (typeof e === 'number') {
+        if (!Number.isFinite(e))
+            return null;
+        const m = Math.abs(e);
+        return { lo: value - m, hi: value + m };
+    }
+    if (!Number.isFinite(e.lo) || !Number.isFinite(e.hi))
+        return null;
+    return { lo: Math.min(e.lo, e.hi), hi: Math.max(e.lo, e.hi) };
+}
 /** Series colours used when a {@link ChartSeries} sets none, in order. */
 export const DEFAULT_PALETTE = [
     '#2563eb',
@@ -112,6 +206,48 @@ function project(value, min, max, isLog) {
     }
     return (value - min) / (max - min);
 }
+/**
+ * Turn a laid-out chart's axes into functions, so a caller can draw its own
+ * marks in the same coordinates the built-in ones use.
+ *
+ * This is the custom-series seam. Rather than a registry of mark types, the
+ * chart hands over its geometry and its scales and lets the caller render
+ * whatever SVG it likes into the plot - which is the Svelte-shaped answer, and
+ * means a custom mark is ordinary markup rather than a plugin.
+ *
+ * Deriving the scale from `geo.axes` matters: the domain a chart drew against
+ * is the NICE-ROUNDED one, stretched to include zero for bar charts and any
+ * reference lines. Recomputing it from the data outside would land custom marks
+ * a few pixels off the built-in ones, in a way that looks like a rendering bug.
+ *
+ * Returns `null` for a chart with no cartesian axes (pie, gauge, treemap,
+ * sankey, calendar, radar, funnel), where plot coordinates mean nothing.
+ */
+export function chartScales(geo) {
+    const a = geo.axes;
+    if (!a)
+        return null;
+    const { x: px, y: py, w: pw, h: ph } = geo.plot;
+    const yFor = (dom) => (value) => {
+        const t = project(value, dom.min, dom.max, dom.log);
+        return t === null ? Number.NaN : py + ph - t * ph;
+    };
+    const left = yFor(a.y);
+    const right = a.y2 ? yFor(a.y2) : left;
+    const invFor = (dom) => (y) => {
+        const t = ph === 0 ? 0 : (py + ph - y) / ph;
+        if (!dom.log)
+            return dom.min + t * (dom.max - dom.min);
+        const lo = Math.log10(dom.min);
+        return 10 ** (lo + t * (Math.log10(dom.max) - lo));
+    };
+    return {
+        xOf: (i) => px + a.slot * i + a.slot / 2,
+        yOf: (value, axis) => (axis === 'right' ? right(value) : left(value)),
+        xInvert: (x) => Math.max(0, Math.min(a.count - 1, Math.floor((x - px) / (a.slot || 1)))),
+        yInvert: (y, axis) => (axis === 'right' && a.y2 ? invFor(a.y2)(y) : invFor(a.y)(y)),
+    };
+}
 // ---- Overlay math: trendline + moving averages -----------------------
 /** Build an SVG path from a list of (x,y) pairs, optionally smoothed via
  *  monotone cubic interpolation (preserves local extrema - no overshoots).
@@ -314,13 +450,38 @@ function fmtTick(n) {
 }
 /**
  * Format a numeric value for display, honouring an optional `valueFormat`.
- * Builds on the compact `1.2k` / `1.2M` base: currency prefixes `$` (sign
- * outside), percent multiplies by 100 and suffixes `%`. Unset / `'number'` /
- * `'compact'` = the plain compact form.
+ *
+ * Two modes, on purpose. With no `locale` and no `currency` this is the original
+ * locale-free output: the compact `1.2k` / `1.2M` base, currency prefixed with
+ * `$` (sign outside), percent multiplied by 100 and suffixed `%`. Set either one
+ * and it switches to `Intl.NumberFormat`, so separators, the decimal mark and the
+ * compact suffixes all follow the locale.
+ *
+ * Keeping the old path as the default is deliberate rather than lazy. `Intl`'s
+ * compact notation is not the same string even for `en-US` (`1.2K`, capital),
+ * so formatting everything through it would silently restyle every axis in every
+ * existing chart. Opting in is the only version of this that is not a surprise.
  */
-export function formatChartValue(n, format) {
+export function formatChartValue(n, format, opts) {
     if (!Number.isFinite(n))
         return '';
+    const localized = opts && (opts.locale || opts.currency);
+    if (localized) {
+        // Compact notation because these are axis ticks and data labels, where a
+        // full-precision number is what makes an axis unreadable.
+        const style = format === 'currency' ? 'currency' : format === 'percent' ? 'percent' : 'decimal';
+        const o = { notation: 'compact', maximumFractionDigits: 1 };
+        if (style === 'currency') {
+            o.style = 'currency';
+            // `style: 'currency'` throws without a code, so fall back to the symbol
+            // this used to hard-code rather than refusing to draw the chart.
+            o.currency = opts.currency || 'USD';
+        }
+        else if (style === 'percent') {
+            o.style = 'percent';
+        }
+        return getNumberFormatter(opts.locale, o).format(n);
+    }
     if (format === 'currency')
         return `${n < 0 ? '-' : ''}$${fmtTick(Math.abs(n))}`;
     if (format === 'percent') {
@@ -341,6 +502,56 @@ function dateTicks(tMin, tMax) {
         ticks.push(tMin, tMax);
     return ticks;
 }
+/**
+ * Tick positions for an ordinal (evenly spaced) date axis, as INDICES into
+ * `times`.
+ *
+ * A time axis can put a tick anywhere, because x is a function of the
+ * timestamp. An ordinal axis cannot: x is a function of the index, so a tick
+ * has to land on a point that exists. This picks the first point of each
+ * calendar unit - day, week, month, year, whichever gets closest to `target`
+ * ticks without going over - so labels sit on real sessions and a weekend or a
+ * holiday never stretches the spacing.
+ */
+export function ordinalDateTicks(times, target = 6) {
+    if (times.length <= 1)
+        return times.length ? [0] : [];
+    const keyOf = {
+        day: (d) => `${d.getUTCFullYear()}-${d.getUTCMonth()}-${d.getUTCDate()}`,
+        week: (d) => Math.floor((Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / DAY + 4) / 7),
+        month: (d) => `${d.getUTCFullYear()}-${d.getUTCMonth()}`,
+        year: (d) => d.getUTCFullYear(),
+    };
+    let chosen = null;
+    for (const unit of ['day', 'week', 'month', 'year']) {
+        const at = [];
+        let prev = null;
+        for (let i = 0; i < times.length; i += 1) {
+            const t = times[i];
+            if (!Number.isFinite(t))
+                continue;
+            const k = keyOf[unit](new Date(t));
+            if (k !== prev)
+                at.push(i);
+            prev = k;
+        }
+        chosen = at;
+        if (at.length <= target * 2)
+            break;
+    }
+    let out = chosen ?? [];
+    // Even the coarsest unit can be too dense (a decade of yearly points), and a
+    // single trading day yields one boundary. Thin, or fall back to plain strides.
+    if (out.length > target) {
+        const stride = Math.ceil(out.length / target);
+        out = out.filter((_, i) => i % stride === 0);
+    }
+    if (out.length < 2) {
+        const stride = Math.max(1, Math.ceil(times.length / target));
+        out = times.map((_, i) => i).filter((i) => i % stride === 0);
+    }
+    return out;
+}
 function fmtDate(t, span) {
     const d = new Date(t);
     if (span <= 70 * DAY)
@@ -349,6 +560,24 @@ function fmtDate(t, span) {
         return d.toLocaleDateString(undefined, { month: 'short', year: '2-digit' });
     return String(d.getFullYear());
 }
+/**
+ * Which mark a series draws.
+ *
+ * A series counts as a candle when it says so OR when it carries `ohlc` data,
+ * so a spec typed `'candlestick'` can still hold a plain volume bar series
+ * beside the prices. Boxes work the same way. Anything unrecognised falls back
+ * to `'bar'`, which is what pie and scatter have always relied on.
+ */
+function kindOf(s, specType) {
+    const t = s.type ?? specType;
+    if (t === 'candlestick' || t === 'ohlc' || s.ohlc)
+        return 'candle';
+    if (t === 'boxplot' || s.boxes)
+        return 'box';
+    if (t === 'line' || t === 'area')
+        return t;
+    return 'bar';
+}
 /** Data domain for one axis, honoring stacking of its bar/area series.
  *  When `isLog` is true, non-positive values are discarded (log undefined)
  *  and the domain is rounded to decade boundaries instead of nice steps. */
@@ -392,6 +621,50 @@ function axisDomain(list, categories, stacked, extra = [], isLog = false) {
     for (const s of lines)
         for (const v of s.values)
             note(v);
+    // Candles: note the HIGH and the LOW, not `values` (the closes), or every
+    // wick clips at the body. Note also that candles are deliberately absent
+    // from `stackable`, so the zero-baseline rule below does not fire for them:
+    // a price series running 180 to 195 keeps a readable domain instead of being
+    // flattened against zero.
+    for (const s of list) {
+        if (s.kind !== 'candle')
+            continue;
+        for (const k of s.ohlc ?? []) {
+            if (!k)
+                continue;
+            note(k.h);
+            note(k.l);
+        }
+    }
+    // Boxes: the whisker ends and any outlier, for the same reason - `values`
+    // holds the medians, so a domain built from those alone would clip half of
+    // every box. Boxes are also absent from `stackable`, so a sample that never
+    // goes near zero keeps a readable domain.
+    for (const s of list) {
+        if (s.kind !== 'box')
+            continue;
+        for (const b of s.boxes ?? []) {
+            if (!b)
+                continue;
+            note(b.min);
+            note(b.max);
+            for (const o of b.outliers ?? [])
+                note(o);
+        }
+    }
+    // Error bars extend past their own mark, so a whisker that leaves the plot is
+    // the same defect as a clipped candle wick.
+    for (const s of list) {
+        if (!s.errors)
+            continue;
+        s.errors.forEach((e, i) => {
+            const span = errorSpan(e, s.values[i] ?? 0);
+            if (!span)
+                return;
+            note(span.lo);
+            note(span.hi);
+        });
+    }
     if (dMin === Infinity) {
         dMin = isLog ? 1 : 0;
         dMax = isLog ? 10 : 1;
@@ -417,7 +690,7 @@ export function buildChart(spec, theme = 'light') {
     const series = spec.series.map((s, i) => ({
         ...s,
         color: s.color ?? palette[i % palette.length],
-        kind: (s.type ?? (spec.type === 'pie' || spec.type === 'scatter' ? 'bar' : spec.type)),
+        kind: kindOf(s, spec.type),
         axis: s.axis ?? 'left',
     }));
     const legend = series.map((s) => ({ label: s.label, color: s.color }));
@@ -426,7 +699,11 @@ export function buildChart(spec, theme = 'light') {
         width,
         height,
         plot: { x: 0, y: 0, w: width, h: height },
+        axes: null,
         bars: [],
+        candles: [],
+        boxes: [],
+        errorBars: [],
         lines: [],
         slices: [],
         yTicks: [],
@@ -548,7 +825,7 @@ export function buildChart(spec, theme = 'light') {
             x: round(padL + slotW * i + slotW / 2),
         }));
         const yTicks = dom.ticks.map((value) => ({
-            value, y: yOfW(value), label: formatChartValue(value, spec.valueFormat),
+            value, y: yOfW(value), label: formatChartValue(value, spec.valueFormat, spec),
         }));
         return {
             ...empty,
@@ -744,7 +1021,7 @@ export function buildChart(spec, theme = 'light') {
         const legend = Array.from({ length: 5 }, (_, i) => {
             const t = i / 4;
             const value = vMin + (vMax - vMin) * t;
-            return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat) };
+            return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat, spec) };
         });
         return {
             ...empty,
@@ -779,8 +1056,13 @@ export function buildChart(spec, theme = 'light') {
         };
         const trackPath = arc(A0, A1, r);
         const valuePath = arc(A0, angleAt(value), r);
+        // Bands sit on their own inner ring, well clear of the value arc's 16px
+        // stroke at `r`. They are context, not the reading: a band covering most
+        // of the scale (an error-rate dial where anything above 0.45 is red) used
+        // to out-shout the value arc completely, so the dial looked pegged at
+        // maximum when the actual value was 9 percent.
         const rangePaths = (spec.gaugeRanges ?? []).map((band) => ({
-            path: arc(angleAt(band.from), angleAt(band.to), r - 9),
+            path: arc(angleAt(band.from), angleAt(band.to), r - 16),
             color: band.color, from: band.from, to: band.to,
         }));
         let targetPx = null;
@@ -810,23 +1092,46 @@ export function buildChart(spec, theme = 'light') {
         }
         // Pointer needle: a kite (long tip toward the value, short counterweight
         // tail) pivoting on a center hub.
+        //
+        // The proportions matter more than they look, and the counterweight was the
+        // whole problem. A tail sticking out past the hub is a short, solid triangle;
+        // the pointer is a 130px taper that thins to nothing. The compact shape wins
+        // the eye, so on a near-full dial the needle read as an arrow pointing at the
+        // MINIMUM. Keeping the tail inside the hub radius removes the competing
+        // point without giving up the pivot, and the shoulders sit outside the hub so
+        // the needle actually has a visible base to taper from.
         const aV = angleAt(value);
-        const tipR = r - 16, tailR = 18, baseR = 6;
+        const tipR = r - 14, tailR = 5, baseR = 9;
         const aPerp = aV + Math.PI / 2;
         const pt = (rad, ang) => `${round(cx + rad * Math.cos(ang))},${round(cy + rad * Math.sin(ang))}`;
         const needlePath = `M${pt(baseR, aPerp)} L${pt(tipR, aV)} L${pt(baseR, aPerp + Math.PI)} L${pt(tailR, aV + Math.PI)} Z`;
         // Color the value arc by the band the value currently sits in.
+        // First match wins, and bands are half-open [from, to). Bands normally
+        // share endpoints - green 0..0.3, amber 0.3..0.45, red 0.45..5 - and with
+        // an inclusive `to` plus last-match-wins, a value sitting exactly ON a
+        // boundary took the colour of the band ABOVE it. An error rate of 0.45
+        // against a 0.45 amber ceiling read as red.
         let valueColor = null;
-        for (const band of spec.gaugeRanges ?? []) {
-            if (value >= band.from && value <= band.to)
+        const bands = spec.gaugeRanges ?? [];
+        for (const band of bands) {
+            if (value >= band.from && value < band.to) {
                 valueColor = band.color;
+                break;
+            }
+        }
+        // The very top of the scale belongs to the last band that reaches it,
+        // which the half-open test above would otherwise exclude.
+        if (valueColor == null) {
+            for (const band of bands)
+                if (value >= band.from && value <= band.to)
+                    valueColor = band.color;
         }
         return {
             ...empty,
             plot: { x: 0, y: 0, w: width, h: height },
             gauge: {
                 cx, cy, r, trackPath, valuePath, rangePaths, target: targetPx,
-                ticks, needle: { path: needlePath, hubR: 7 }, valueColor,
+                ticks, needle: { path: needlePath, hubR: 6 }, valueColor,
                 minLabel: { x: cx - r, y: cy + 20 },
                 maxLabel: { x: cx + r, y: cy + 20 },
                 value, min, max, unit: spec.gaugeUnit ?? '',
@@ -1131,7 +1436,7 @@ export function buildChart(spec, theme = 'light') {
         const heatmapLegend = Array.from({ length: 5 }, (_, i) => {
             const t = i / 4;
             const value = vMin + (vMax - vMin) * t;
-            return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat) };
+            return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat, spec) };
         });
         return {
             ...empty,
@@ -1261,7 +1566,7 @@ export function buildChart(spec, theme = 'light') {
         }
         const referenceLines = (spec.referenceLines ?? []).map((ref) => ({
             y: yOf(ref.value),
-            label: ref.label ?? formatChartValue(ref.value, spec.valueFormat),
+            label: ref.label ?? formatChartValue(ref.value, spec.valueFormat, spec),
             color: ref.color ?? '#ef4444',
             dashed: ref.dashed !== false,
         }));
@@ -1270,7 +1575,7 @@ export function buildChart(spec, theme = 'light') {
             plot,
             scatterPoints,
             referenceLines,
-            yTicks: yDom.ticks.map((value) => ({ value, y: yOf(value), label: formatChartValue(value, spec.valueFormat) })),
+            yTicks: yDom.ticks.map((value) => ({ value, y: yOf(value), label: formatChartValue(value, spec.valueFormat, spec) })),
             xTicks: xDom.ticks.map((value) => ({ label: fmtTick(value), x: xOf(value) })),
         };
     }
@@ -1353,7 +1658,7 @@ export function buildChart(spec, theme = 'light') {
             });
         }
         const valueTicks = dom.ticks.map((value) => ({
-            label: spec.stacked100 ? `${fmtTick(value)}%` : formatChartValue(value, spec.valueFormat),
+            label: spec.stacked100 ? `${fmtTick(value)}%` : formatChartValue(value, spec.valueFormat, spec),
             x: xOf(value),
         }));
         const catTicks = spec.categories.map((label, i) => ({
@@ -1363,7 +1668,7 @@ export function buildChart(spec, theme = 'light') {
         }));
         const referenceLinesV = (spec.referenceLines ?? []).map((ref) => ({
             x: xOf(ref.value),
-            label: ref.label ?? formatChartValue(ref.value, spec.valueFormat),
+            label: ref.label ?? formatChartValue(ref.value, spec.valueFormat, spec),
             color: ref.color ?? '#ef4444',
             dashed: ref.dashed !== false,
         }));
@@ -1428,19 +1733,30 @@ export function buildChart(spec, theme = 'light') {
     const slot = plotW / Math.max(1, n);
     // X positions. A time axis spaces points by actual time (irregular gaps);
     // a category axis is uniform. (Bars stay uniform either way.)
-    const timeVals = spec.xType === 'time' ? spec.categories.map((c) => Date.parse(c)) : null;
+    // Two date modes, and the difference is only where the marks go: `'time'`
+    // positions by the timestamp, `'ordinal-time'` positions by the index and
+    // uses the dates for labels alone. Both parse; only one scales.
+    const isDateAxis = spec.xType === 'time' || spec.xType === 'ordinal-time';
+    const timeVals = isDateAxis ? spec.categories.map((c) => Date.parse(c)) : null;
     const timeOk = !!timeVals && timeVals.some((t) => Number.isFinite(t));
+    const timeScaled = timeOk && spec.xType === 'time';
     const tMin = timeOk ? Math.min(...timeVals.filter(Number.isFinite)) : 0;
     const tSpan = timeOk ? Math.max(...timeVals.filter(Number.isFinite)) - tMin || 1 : 1;
-    const xCenter = (i) => timeOk && Number.isFinite(timeVals[i])
+    const xCenter = (i) => timeScaled && Number.isFinite(timeVals[i])
         ? round(padL + ((timeVals[i] - tMin) / tSpan) * plotW)
         : round(padL + slot * i + slot / 2);
-    const xTicks = timeOk
+    const xTicks = timeScaled
         ? dateTicks(tMin, tMin + tSpan).map((t) => ({
             label: fmtDate(t, tSpan),
             x: round(padL + ((t - tMin) / tSpan) * plotW),
         }))
-        : spec.categories.map((label, i) => ({ label, x: xCenter(i) }));
+        : timeOk
+            ? // Ordinal: ticks land on points that exist, labelled from their dates.
+                ordinalDateTicks(timeVals).map((i) => ({
+                    label: fmtDate(timeVals[i], tSpan),
+                    x: xCenter(i),
+                }))
+            : thinCategoryTicks(spec.categories, xCenter, slot, xLabelRotated);
     // Parent-tier ticks for a grouped category axis: each spans its leaves.
     const categoryGroupTicks = [];
     if (validGroups && !timeOk) {
@@ -1532,6 +1848,135 @@ export function buildChart(spec, theme = 'light') {
             });
         }
     }
+    // Candlesticks / OHLC bars. Laid out once; the two marks differ only in how
+    // the renderer paints them, so there is no second geometry pass.
+    const candleSeries = series.filter((s) => s.kind === 'candle');
+    const candles = [];
+    if (candleSeries.length) {
+        const upColor = spec.candleColors?.up ?? '#16a34a';
+        const downColor = spec.candleColors?.down ?? '#ef4444';
+        // Share the slot when two instruments are charted together, the same way
+        // grouped bars do.
+        const bodyW = Math.max(1, (slot * 0.7) / candleSeries.length);
+        candleSeries.forEach((s, si) => {
+            const dom = domOf(s);
+            const log = isLogOf(s);
+            (s.ohlc ?? []).forEach((k, i) => {
+                if (!k)
+                    return;
+                if (![k.o, k.h, k.l, k.c].every(Number.isFinite))
+                    return;
+                // A log price axis is genuinely used for long histories, and a
+                // non-positive price has no place on one.
+                if (log && (k.o <= 0 || k.h <= 0 || k.l <= 0 || k.c <= 0))
+                    return;
+                const centre = padL + slot * i + slot / 2;
+                const x = centre - (bodyW * candleSeries.length) / 2 + bodyW * si;
+                const yOpen = yOf(dom, k.o, log);
+                const yClose = yOf(dom, k.c, log);
+                const up = k.c >= k.o;
+                candles.push({
+                    x: round(x),
+                    w: round(bodyW),
+                    xCenter: round(x + bodyW / 2),
+                    yOpen,
+                    yClose,
+                    yHigh: yOf(dom, k.h, log),
+                    yLow: yOf(dom, k.l, log),
+                    bodyY: Math.min(yOpen, yClose),
+                    // A doji closes where it opened; keep it visible as a 1px line
+                    // rather than a zero-height rect that paints nothing.
+                    bodyH: Math.max(1, Math.abs(yClose - yOpen)),
+                    up,
+                    color: up ? upColor : downColor,
+                    label: spec.categories[i] ?? String(i),
+                    series: s.label,
+                    o: k.o,
+                    h: k.h,
+                    l: k.l,
+                    c: k.c,
+                });
+            });
+        });
+    }
+    // Box plots. Same slot-sharing as grouped bars and candles, so several
+    // samples can sit side by side under one category.
+    const boxSeries = series.filter((s) => s.kind === 'box');
+    const boxes = [];
+    if (boxSeries.length) {
+        const boxW = Math.max(1, (slot * 0.6) / boxSeries.length);
+        boxSeries.forEach((s, si) => {
+            const dom = domOf(s);
+            const log = isLogOf(s);
+            (s.boxes ?? []).forEach((b, i) => {
+                if (!b)
+                    return;
+                if (![b.min, b.q1, b.median, b.q3, b.max].every(Number.isFinite))
+                    return;
+                if (log && b.min <= 0)
+                    return;
+                const centre = padL + slot * i + slot / 2;
+                const x = centre - (boxW * boxSeries.length) / 2 + boxW * si;
+                const yQ1 = yOf(dom, b.q1, log);
+                const yQ3 = yOf(dom, b.q3, log);
+                boxes.push({
+                    x: round(x),
+                    w: round(boxW),
+                    xCenter: round(x + boxW / 2),
+                    yMin: yOf(dom, b.min, log),
+                    yQ1,
+                    yMedian: yOf(dom, b.median, log),
+                    yQ3,
+                    yMax: yOf(dom, b.max, log),
+                    boxY: Math.min(yQ1, yQ3),
+                    // A sample with no spread would otherwise paint nothing at all.
+                    boxH: Math.max(1, Math.abs(yQ1 - yQ3)),
+                    outliers: (b.outliers ?? [])
+                        .filter((o) => Number.isFinite(o) && (!log || o > 0))
+                        .map((o) => ({ y: yOf(dom, o, log), value: o })),
+                    color: s.color,
+                    label: spec.categories[i] ?? String(i),
+                    series: s.label,
+                    min: b.min,
+                    q1: b.q1,
+                    median: b.median,
+                    q3: b.q3,
+                    max: b.max,
+                });
+            });
+        });
+    }
+    // Error bars. Not a mark of their own: they annotate whatever the series
+    // already draws, so this runs over every series carrying `errors` regardless
+    // of kind, and the geometry sits in its own array so no existing loop changes.
+    const errorBars = [];
+    for (const s of series) {
+        if (!s.errors)
+            continue;
+        const dom = domOf(s);
+        const log = isLogOf(s);
+        s.errors.forEach((e, i) => {
+            const v = s.values[i];
+            if (!Number.isFinite(v))
+                return;
+            const span = errorSpan(e, v);
+            if (!span)
+                return;
+            if (log && span.lo <= 0)
+                return;
+            errorBars.push({
+                xCenter: round(padL + slot * i + slot / 2),
+                yLo: yOf(dom, span.lo, log),
+                yHi: yOf(dom, span.hi, log),
+                cap: round(Math.min(6, slot * 0.15)),
+                color: s.color,
+                label: spec.categories[i] ?? String(i),
+                series: s.label,
+                lo: span.lo,
+                hi: span.hi,
+            });
+        });
+    }
     // Lines / areas. Stacked areas accumulate per axis; others fill to baseline.
     const lines = [];
     const areaCum = {
@@ -1549,7 +1994,12 @@ export function buildChart(spec, theme = 'light') {
         }
     }
     for (const s of series) {
-        if (s.kind === 'bar')
+        // Bars, candles and boxes draw their own marks. Candles and boxes
+        // especially: `values` holds their closes / medians so that tooltips, CSV
+        // and overlays work, and without this guard that same array was ALSO drawn
+        // as a line, laying a dotted close-line straight over every candle. Boxes
+        // would do exactly the same thing through the median.
+        if (s.kind === 'bar' || s.kind === 'candle' || s.kind === 'box')
             continue;
         const dom = domOf(s);
         const log = isLogOf(s);
@@ -1649,14 +2099,23 @@ export function buildChart(spec, theme = 'light') {
         }
         lines.push({ path, areaPath, color: s.color, label: s.label, points: pts, bandPath });
     }
-    const tickFor = (dom, log) => dom.ticks.map((value) => ({ value, y: yOf(dom, value, log), label: formatChartValue(value, spec.valueFormat) }));
+    // Under `stacked100` the axis is a share of the total, not the measure, so
+    // it is labelled as a percentage whatever `valueFormat` says. Formatting it
+    // as currency gives an axis reading "$0 .. $100" for what are percentages -
+    // which is what it did, unnoticed, while `stacked100` was reachable only
+    // from config.
+    const tickFor = (dom, log) => dom.ticks.map((value) => ({
+        value,
+        y: yOf(dom, value, log),
+        label: spec.stacked100 ? `${round(value)}%` : formatChartValue(value, spec.valueFormat, spec),
+    }));
     const referenceLines = (spec.referenceLines ?? []).map((ref) => {
         const onRight = ref.axis === 'right';
         const dom = onRight ? (rightDom ?? leftDom) : leftDom;
         const log = onRight ? rightLog : leftLog;
         return {
             y: yOf(dom, ref.value, log),
-            label: ref.label ?? formatChartValue(ref.value, spec.valueFormat),
+            label: ref.label ?? formatChartValue(ref.value, spec.valueFormat, spec),
             color: ref.color ?? '#ef4444',
             dashed: ref.dashed !== false,
         };
@@ -1735,7 +2194,20 @@ export function buildChart(spec, theme = 'light') {
     return {
         ...empty,
         plot,
+        // What a caller needs to put its own marks in this chart's coordinates.
+        // Reported rather than recomputed, so a custom mark lands on exactly the
+        // scale the built-in ones did - including the nice-scale rounding and the
+        // "always include zero" rule, which are impossible to guess from outside.
+        axes: {
+            y: { min: leftDom.min, max: leftDom.max, log: leftLog },
+            y2: rightDom ? { min: rightDom.min, max: rightDom.max, log: rightLog } : null,
+            slot,
+            count: spec.categories.length,
+        },
         bars,
+        candles,
+        boxes,
+        errorBars,
         lines,
         yTicks: tickFor(leftDom, leftLog),
         y2Ticks: rightDom ? tickFor(rightDom, rightLog) : [],
@@ -1748,6 +2220,51 @@ export function buildChart(spec, theme = 'light') {
         annotations,
     };
 }
+/**
+ * Narrow a spec to the category window `[lo, hi]`, keeping every
+ * category-parallel array in step.
+ *
+ * This is the zoom / brush slice. It lives here rather than in the renderer
+ * because getting it wrong is a MODEL bug, not a paint bug, and it was wrong:
+ * the component used to slice `categories`, `values` and `rowIds` by hand and
+ * spread the rest of the series through untouched. `upperValues` and
+ * `lowerValues` therefore kept their full length, the equality guard on the
+ * confidence band (see `buildChart`) stopped matching, and the band silently
+ * disappeared the moment anyone zoomed.
+ *
+ * The lesson generalises: every array here is indexed by category, so each one
+ * added in future has to be sliced too. Keeping them in one function is what
+ * makes that a single place to remember rather than a scattered convention.
+ */
+export function sliceChartWindow(spec, lo, hi) {
+    const from = Math.max(0, lo);
+    const to = Math.min(spec.categories.length - 1, hi);
+    const cut = (arr) => arr ? arr.slice(from, to + 1) : undefined;
+    return {
+        ...spec,
+        categories: spec.categories.slice(from, to + 1),
+        // EVERY per-category array on a series has to be cut here, not just the
+        // ones that existed when this function was written. A missed one does not
+        // throw: the geometry keeps indexing the full-length array against the
+        // sliced categories, so marks land at the wrong x or off the plot entirely.
+        // `upperValues` / `lowerValues` were missed once and silently dropped the
+        // confidence band on zoom; `ohlc` was missed the same way and drew a
+        // zoomed candlestick chart against the wrong categories.
+        series: spec.series.map((s) => ({
+            ...s,
+            values: s.values.slice(from, to + 1),
+            rowIds: cut(s.rowIds),
+            upperValues: cut(s.upperValues),
+            lowerValues: cut(s.lowerValues),
+            ohlc: cut(s.ohlc),
+            boxes: cut(s.boxes),
+            errors: cut(s.errors),
+        })),
+        // Per-category, so it has to travel with the window or the waterfall's
+        // running total resets on the wrong bars.
+        waterfallTotals: cut(spec.waterfallTotals),
+    };
+}
 /**
  * Aggregate flat rows into a chart spec. Group by a category field, reduce a
  * value field per group. Three multi-series shapes:
@@ -1866,3 +2383,286 @@ export function rowsToChartSpec(rows, opts) {
         palette: opts.palette,
     };
 }
+// ---------------------------------------------------------------------------
+// Shape adapters.
+//
+// Nine of the thirteen chart types were unreachable from the chart panel
+// because they do not read a `categories x series` grid: a treemap wants a
+// hierarchy, a sankey wants an edge list, a gauge wants one number. Rather
+// than give each its own aggregation path, these take the spec
+// `rowsToChartSpec` already produced and reshape it, so grouping, `reduce`,
+// `sort`, `topN` and the "Other" bucket keep working for all of them.
+// ---------------------------------------------------------------------------
+/**
+ * Reshape an aggregated spec into a tree-map hierarchy.
+ *
+ * One series gives a flat set of leaves. Several (a split-by) give two levels,
+ * category above series, which is the shape people expect from "sales by
+ * region, split by channel".
+ */
+export function specToTreemap(spec, rootName = 'Total') {
+    const positive = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+    if (spec.series.length <= 1) {
+        const s = spec.series[0];
+        return {
+            name: rootName,
+            children: spec.categories
+                .map((name, i) => ({ name, value: positive(s?.values[i]) }))
+                .filter((n) => n.value > 0),
+        };
+    }
+    return {
+        name: rootName,
+        children: spec.categories
+            .map((name, i) => ({
+            name,
+            children: spec.series
+                .map((s) => ({ name: s.label, value: positive(s.values[i]) }))
+                .filter((n) => n.value > 0),
+        }))
+            .filter((n) => n.children.length > 0),
+    };
+}
+/**
+ * Reshape an aggregated spec into calendar samples.
+ *
+ * Categories that do not parse as a date are dropped rather than rendered at
+ * epoch zero, which would put a stray cell in 1970 and rescale the whole year.
+ */
+export function specToCalendar(spec) {
+    const s = spec.series[0];
+    const out = [];
+    spec.categories.forEach((c, i) => {
+        const t = Date.parse(c);
+        if (!Number.isFinite(t))
+            return;
+        const v = s?.values[i];
+        if (typeof v !== 'number' || !Number.isFinite(v))
+            return;
+        out.push({ date: new Date(t).toISOString().slice(0, 10), value: v });
+    });
+    return out;
+}
+/**
+ * Reshape a pivoted spec into sankey nodes and links.
+ *
+ * The pivot `rowsToChartSpec` already performs is exactly an edge list read
+ * sideways: categories are sources, series are targets, and each cell is the
+ * flow between them. Zero cells and self-edges are dropped, the first because
+ * a zero-width ribbon is not a flow and the second because the layout has no
+ * meaningful place to put one.
+ */
+export function specToSankey(spec) {
+    const links = [];
+    const ids = new Set();
+    spec.categories.forEach((from, i) => {
+        for (const s of spec.series) {
+            const v = s.values[i];
+            if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0)
+                continue;
+            // Sources and targets share a namespace, so a value appearing on both
+            // sides would otherwise become one node with a cycle through it.
+            const source = `from:${from}`;
+            const target = `to:${s.label}`;
+            if (source === target)
+                continue;
+            ids.add(source);
+            ids.add(target);
+            links.push({ source, target, value: v });
+        }
+    });
+    return {
+        nodes: [...ids].map((id) => ({ id, label: id.slice(id.indexOf(':') + 1) })),
+        links,
+    };
+}
+/**
+ * The chart types that read ROWS directly instead of a grouped grid, behind one
+ * call. Returns `null` for every other type, which then goes through
+ * `rowsToChartSpec` and its reduce / sort / topN / "Other" pipeline.
+ *
+ * One entry point rather than a branch per type in the caller, because the
+ * caller is the grid controller and the controller is in the BASE bundle: every
+ * type named there is bytes paid by grids that never chart. Here it is in the
+ * lazy chart chunk, next to the builders it dispatches to, and adding a fourth
+ * direct type costs a grid nothing.
+ */
+export function rowsToDirectSpec(type, rows, opts) {
+    const cat = opts.category;
+    const val = opts.value;
+    const ser = opts.series;
+    if (type === 'scatter') {
+        const y = opts.value2;
+        if (!val || !y)
+            return null;
+        return rowsToScatterSpec(rows, {
+            x: val,
+            y,
+            ...(ser ? { series: ser } : {}),
+            ...(opts.palette ? { palette: opts.palette } : {}),
+        });
+    }
+    if (type === 'gauge') {
+        if (!val)
+            return null;
+        return rowsToGaugeSpec(rows, { value: val, ...(opts.reduce ? { reduce: opts.reduce } : {}) });
+    }
+    if (type === 'boxplot') {
+        if (!cat || !val)
+            return null;
+        const spec = rowsToBoxSpec(rows, {
+            category: cat,
+            value: val,
+            ...(ser ? { series: ser } : {}),
+        });
+        if (opts.palette)
+            spec.palette = opts.palette;
+        return spec;
+    }
+    return null;
+}
+/**
+ * Build a box plot spec straight from rows: group by a category, then reduce
+ * each group to a five-number summary.
+ *
+ * This is the one aggregate the panel's `sum | avg | count` cannot express, and
+ * that is the point of it. Every other chart answers "how much"; a box plot
+ * answers "how spread out", which needs the whole sample per group rather than
+ * one number, so it cannot go through `rowsToChartSpec`.
+ *
+ * `values` comes out as the medians, so tooltips, CSV and overlays work with no
+ * box-specific code - the same contract `ohlc` follows.
+ */
+export function rowsToBoxSpec(rows, opts) {
+    const cats = [];
+    const seen = new Set();
+    for (const r of rows) {
+        const c = String(r[opts.category] ?? '');
+        if (!seen.has(c)) {
+            seen.add(c);
+            cats.push(c);
+        }
+    }
+    const groupNames = [];
+    const groupSeen = new Set();
+    if (opts.series) {
+        for (const r of rows) {
+            const g = String(r[opts.series] ?? '');
+            if (!groupSeen.has(g)) {
+                groupSeen.add(g);
+                groupNames.push(g);
+            }
+        }
+    }
+    else {
+        groupNames.push(opts.seriesLabel ?? String(opts.value));
+    }
+    const series = groupNames.map((g) => {
+        const boxes = cats.map((c) => {
+            const sample = [];
+            for (const r of rows) {
+                if (String(r[opts.category] ?? '') !== c)
+                    continue;
+                if (opts.series && String(r[opts.series] ?? '') !== g)
+                    continue;
+                // `Number(null)` and `Number('')` are both 0, so coercing first would
+                // fold every empty cell into the sample as a zero and drag the whole
+                // box down. An absent observation is absent, not zero.
+                const raw = r[opts.value];
+                if (raw == null || raw === '')
+                    continue;
+                const n = Number(raw);
+                if (Number.isFinite(n))
+                    sample.push(n);
+            }
+            return boxStats(sample, opts.whisker);
+        });
+        return {
+            label: g,
+            // Medians, so a gap stays a gap rather than plotting as zero.
+            values: boxes.map((b) => (b ? b.median : Number.NaN)),
+            boxes,
+        };
+    });
+    return {
+        type: 'boxplot',
+        categories: cats,
+        series,
+        ...(opts.width ? { width: opts.width } : {}),
+        ...(opts.height ? { height: opts.height } : {}),
+    };
+}
+/**
+ * Build a scatter / bubble spec straight from rows.
+ *
+ * Unlike the adapters above this cannot reuse `rowsToChartSpec`: a scatter
+ * point is one row, not one group, so there is nothing to reduce. `series`
+ * colours the points by a categorical field.
+ */
+export function rowsToScatterSpec(rows, opts) {
+    const bySeries = new Map();
+    for (const row of rows) {
+        const x = Number(row[opts.x]);
+        const y = Number(row[opts.y]);
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            continue;
+        const key = opts.series ? String(row[opts.series] ?? '') : opts.y;
+        const pt = { x, y };
+        if (opts.r) {
+            const r = Number(row[opts.r]);
+            if (Number.isFinite(r))
+                pt.r = r;
+        }
+        if (opts.label)
+            pt.label = String(row[opts.label] ?? '');
+        const list = bySeries.get(key);
+        if (list)
+            list.push(pt);
+        else
+            bySeries.set(key, [pt]);
+    }
+    return {
+        type: 'scatter',
+        categories: [],
+        series: [...bySeries].map(([label, points]) => ({ label, values: [], points })),
+        palette: opts.palette,
+        width: opts.width,
+        height: opts.height,
+        xAxisTitle: opts.x,
+        yAxisTitle: opts.y,
+    };
+}
+/**
+ * Reduce rows to the single number a gauge shows.
+ *
+ * There is no category axis here, which is why this cannot go through
+ * `rowsToChartSpec`. The dial ends on a nice round number rather than exactly
+ * the value, so the needle never sits pinned at the far end of the arc.
+ */
+export function rowsToGaugeSpec(rows, opts) {
+    const reduce = opts.reduce ?? 'sum';
+    let sum = 0;
+    let count = 0;
+    for (const row of rows) {
+        const v = Number(row[opts.value]);
+        if (!Number.isFinite(v))
+            continue;
+        sum += v;
+        count += 1;
+    }
+    const value = reduce === 'count' ? count : reduce === 'avg' ? (count ? sum / count : 0) : sum;
+    const min = opts.min ?? Math.min(0, value);
+    const max = opts.max ?? (value > min ? niceScale(min, value).max : min + 1);
+    return {
+        type: 'gauge',
+        categories: [],
+        series: [],
+        gaugeValue: value,
+        gaugeMin: min,
+        gaugeMax: max,
+        gaugeTarget: opts.target,
+        gaugeUnit: opts.unit,
+        width: opts.width,
+        height: opts.height,
+    };
+}