@svgrid/grid 3.0.1 → 3.0.2

package/src/chart.ts

@@ -8,10 +8,37 @@
  * (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'
+
+/** Every mark this engine can draw. `bar`, `line` and `area` compose (a series
+ *  can override the spec's type for a combo chart); the rest are whole-chart
+ *  types that ignore per-series overrides. */
 export type ChartType =
   | 'bar' | 'line' | 'area' | 'pie' | 'scatter'
   | 'heatmap' | 'waterfall' | 'funnel' | 'radar'
   | 'calendar' | 'gauge' | 'treemap' | 'sankey'
+  | 'candlestick' | 'ohlc' | 'boxplot'
+
+/** One open / high / low / close bar. */
+export type OhlcBar = { o: number; h: number; l: number; c: number }
+
+/** A five-number summary: one box, its whiskers, and anything past them.
+ *  `min` / `max` are the WHISKER ENDS, not the extremes of the sample - with
+ *  the usual 1.5 IQR rule those differ, and the points beyond go in
+ *  `outliers` so they can be drawn individually. */
+export type BoxStats = {
+  min: number
+  q1: number
+  median: number
+  q3: number
+  max: number
+  /** Values outside the whiskers, drawn as individual points. */
+  outliers?: number[]
+}
 
 /** A clicked bar / point / slice - the payload of `SvGridChart`'s `onSelect`.
  *  `rowIds` is populated when the spec was built from grid rows (via
@@ -43,7 +70,40 @@ export type ChartSeries = {
   values: number[]
   color?: string
   /** Per-series chart type, for combo charts. Defaults to the spec `type`. */
-  type?: 'bar' | 'line' | 'area'
+  type?: 'bar' | 'line' | 'area' | 'candlestick' | 'ohlc' | 'boxplot'
+  /**
+   * Open / high / low / close per category, parallel to `categories`. `null`
+   * is a gap (a day with no session) and draws nothing.
+   *
+   * Set `values` to the CLOSING prices alongside this. Everything that reads a
+   * series generically reads `values` - the tooltip rows, the CSV export, the
+   * screen-reader table, and `overlay` - so filling it in is what lets a
+   * candlestick series carry a moving average (`overlay: 'sma:20'`) or export
+   * to CSV without a single line of candle-specific code.
+   */
+  ohlc?: Array<OhlcBar | null>
+  /**
+   * Five-number summaries per category, parallel to `categories`. `null` is a
+   * gap and draws nothing.
+   *
+   * Set `values` to the MEDIANS alongside this, for exactly the reason `ohlc`
+   * sets them to the closes: everything that reads a series generically reads
+   * `values`, so the tooltip rows, the CSV export, the screen-reader table and
+   * `overlay` all keep working with no box-specific code.
+   *
+   * `boxStats()` turns a raw sample into one of these.
+   */
+  boxes?: Array<BoxStats | null>
+  /**
+   * Symmetric or asymmetric error bars, parallel to `values`. A number is a
+   * symmetric +/- margin; a pair is an explicit low/high; `null` draws nothing.
+   *
+   * These are an ANNOTATION on an existing mark rather than a mark of their
+   * own, so they compose: a bar, line, area or scatter series can carry them
+   * without changing its type. That is the whole reason they are not a
+   * `ChartType` - "bar chart with error bars" should not be a different chart.
+   */
+  errors?: Array<number | { lo: number; hi: number } | null>
   /** Plot against the left (default) or right Y axis. */
   axis?: 'left' | 'right'
   /** Scatter / bubble points (used when `type === 'scatter'`). */
@@ -116,6 +176,16 @@ export type ChartSpec = {
   /** Number format for the value axis, tooltips, data labels and reference
    *  lines. Unset = the default compact `1.2k` / `1.2M` style. */
   valueFormat?: ChartValueFormat
+  /** BCP-47 locale for value formatting. Setting this (or `currency`) switches
+   *  formatting to `Intl.NumberFormat`, so thousands separators, the decimal
+   *  mark and the compact suffixes follow the locale rather than the built-in
+   *  English `1.2k` / `1.2M`. Unset = the locale-free default, which is why the
+   *  default output has never changed under anyone's feet. */
+  locale?: string | ReadonlyArray<string>;
+  /** ISO 4217 code for `valueFormat: 'currency'` (`'EUR'`, `'JPY'`, ...). Unset
+   *  means the axis reads `$`, which is wrong everywhere outside the dollar
+   *  zone and was the only currency this chart could draw for a long time. */
+  currency?: string
   /** Grouped (nested) category axis: a parent tier spanning consecutive leaf
    *  categories (spans must sum to `categories.length`). Vertical category
    *  charts only (ignored for time / horizontal / pie). */
@@ -134,8 +204,18 @@ export type ChartSpec = {
   innerRadius?: number
   /** Horizontal target / goal / average lines. */
   referenceLines?: ChartReferenceLine[]
-  /** Treat `categories` as dates -> time-scaled x positions + date ticks. */
-  xType?: 'category' | 'time'
+  /**
+   * How to read `categories` along the x axis.
+   *
+   * - `'category'` (default): evenly spaced labels, taken literally.
+   * - `'time'`: parsed as dates and positioned by ACTUAL elapsed time, so an
+   *   irregular gap renders as a proportional gap.
+   * - `'ordinal-time'`: parsed as dates but spaced EVENLY, with date-derived
+   *   ticks. This is what a series of trading sessions or business days needs:
+   *   on a true time axis every weekend opens a hole a third as wide as the
+   *   working week, which is noise rather than information.
+   */
+  xType?: 'category' | 'time' | 'ordinal-time'
   /** Axis titles (reserve gutter space + render). */
   yAxisTitle?: string
   y2AxisTitle?: string
@@ -186,6 +266,10 @@ export type ChartSpec = {
   /** Waterfall: explicit colors for positive/negative/total bars. The
    *  series color is ignored when this is set. */
   waterfallColors?: { positive?: string; negative?: string; total?: string }
+  /** Candlestick / OHLC colors. Direction beats series identity here, the same
+   *  way `waterfallColors` overrides the series color. Defaults to the green /
+   *  red pair from the palette's own vocabulary. */
+  candleColors?: { up?: string; down?: string }
   /** Heatmap color scale. `'sequential'` maps min->max through one hue,
    *  `'diverging'` runs cold->neutral->warm around 0. A custom array
    *  (>=2 hex colors) defines an arbitrary gradient. Default `'sequential'`. */
@@ -331,6 +415,168 @@ export type ChartHeatmapCell = {
   colLabel: string
 }
 
+/**
+ * One candlestick / OHLC bar in SVG coordinates.
+ *
+ * Kept apart from {@link ChartBar} rather than folded into it: bars pick up
+ * series pattern fills, data labels and the brush mini-map, and all three are
+ * wrong for a candle. A separate array means every existing loop over `bars`
+ * keeps working untouched, which is the point of this flat geometry.
+ */
+export type ChartCandle = {
+  /** Body rect left edge and width. In OHLC mode, the span of the two ticks. */
+  x: number
+  w: number
+  /** Wick line, and the OHLC bar's vertical. */
+  xCenter: number
+  yOpen: number
+  yClose: number
+  yHigh: number
+  yLow: number
+  /** Body rect, pre-ordered so the renderer does no min/max of its own. */
+  bodyY: number
+  bodyH: number
+  /** Close at or above open. Drives colour and hollow-vs-filled. */
+  up: boolean
+  color: string
+  label: string
+  series: string
+  o: number
+  h: number
+  l: number
+  c: number
+}
+
+/**
+ * A laid-out box plot, in SVG coordinates. Its own array for the same reason
+ * candles have one: `bars` carries pattern fills, data labels and the brush
+ * mini-map, none of which mean anything for a box.
+ */
+export type ChartBox = {
+  /** Box rect left edge and width. */
+  x: number
+  w: number
+  /** Whisker line and the caps, centred on the slot. */
+  xCenter: number
+  yMin: number
+  yQ1: number
+  yMedian: number
+  yQ3: number
+  yMax: number
+  /** Box rect, pre-ordered so the renderer does no min/max of its own. */
+  boxY: number
+  boxH: number
+  /** Points beyond the whiskers, already positioned. */
+  outliers: Array<{ y: number; value: number }>
+  color: string
+  label: string
+  series: string
+  min: number
+  q1: number
+  median: number
+  q3: number
+  max: number
+}
+
+/** One positioned error bar: a vertical span with caps, centred on its mark. */
+export type ChartErrorBar = {
+  xCenter: number
+  yLo: number
+  yHi: number
+  /** Cap half-width, so the renderer draws the same T at both ends. */
+  cap: number
+  color: string
+  label: string
+  series: string
+  lo: number
+  hi: number
+}
+
+/**
+ * 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: ReadonlyArray<number>, whisker = 1.5): BoxStats | null {
+  const v = sample.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b)
+  if (!v.length) return null
+  const q = (p: number) => {
+    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: string[],
+  xCenter: (i: number) => number,
+  slot: number,
+  rotated: boolean,
+): ChartCategoryTick[] {
+  // 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: ChartCategoryTick[] = []
+  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: number | { lo: number; hi: number } | null | undefined,
+  value: number,
+): { lo: number; hi: number } | null {
+  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) }
+}
+
 /** A computed bar rectangle in SVG coordinates. Output of {@link buildChart}, not an input. */
 export type ChartBar = {
   x: number
@@ -407,7 +653,33 @@ export type ChartGeometry = {
   width: number
   height: number
   plot: { x: number; y: number; w: number; h: number }
+  /**
+   * The value domain each axis was actually drawn against, and the slot width
+   * of the category axis. Plain data, deliberately: the geometry stays a
+   * serialisable value object, and `chartScales(geo)` turns this into the
+   * `xOf` / `yOf` functions a custom mark needs.
+   *
+   * Null on the types with no cartesian axes (pie, gauge, treemap, sankey,
+   * calendar, radar, funnel), which is also how a caller can tell whether
+   * drawing into plot coordinates means anything.
+   */
+  axes: {
+    y: { min: number; max: number; log: boolean }
+    /** The right axis, when a series is plotted against one. */
+    y2: { min: number; max: number; log: boolean } | null
+    /** Horizontal room per category, in px. */
+    slot: number
+    /** Number of categories the axis was laid out for. */
+    count: number
+  } | null
   bars: ChartBar[]
+  /** Candlestick / OHLC bars. Empty for every other chart type. */
+  candles: ChartCandle[]
+  /** Box plots. Empty for every other chart type. */
+  boxes: ChartBox[]
+  /** Error bars, from any series carrying `errors`. Empty when none do - they
+   *  annotate whatever mark the series already draws. */
+  errorBars: ChartErrorBar[]
   lines: ChartLine[]
   slices: ChartPieSlice[]
   yTicks: ChartAxisTick[]
@@ -593,6 +865,62 @@ function project(value: number, min: number, max: number, isLog: boolean): numbe
   return (value - min) / (max - min)
 }
 
+/** The scale functions for a laid-out cartesian chart. See {@link chartScales}. */
+export type ChartScales = {
+  /** Pixel x at the centre of category `i`. Fractional indices interpolate,
+   *  so `xOf(2.5)` is the midpoint between the third and fourth categories. */
+  xOf: (index: number) => number
+  /** Pixel y for a value on the left axis (or the right, when asked). Returns
+   *  NaN for a value the axis cannot express, e.g. zero on a log scale. */
+  yOf: (value: number, axis?: 'left' | 'right') => number
+  /** The inverse of `xOf`: which category a pixel x falls on. Clamped. */
+  xInvert: (px: number) => number
+  /** The inverse of `yOf`. */
+  yInvert: (px: number, axis?: 'left' | 'right') => number
+}
+
+/**
+ * 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: ChartGeometry): ChartScales | null {
+  const a = geo.axes
+  if (!a) return null
+  const { x: px, y: py, w: pw, h: ph } = geo.plot
+  const yFor = (dom: { min: number; max: number; log: boolean }) => (value: number) => {
+    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: { min: number; max: number; log: boolean }) => (y: number) => {
+    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
@@ -766,14 +1094,46 @@ function fmtTick(n: number): string {
 /** Value-axis / tooltip / label number format. */
 export type ChartValueFormat = 'number' | 'currency' | 'percent' | 'compact'
 
+/** Locale-aware formatting options, a structural subset of `ChartSpec` so a
+ *  caller inside the engine can pass the spec straight through. */
+export type ChartFormatLocale = { locale?: string | ReadonlyArray<string>; currency?: string }
+
 /**
  * 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: number, format?: ChartValueFormat): string {
+export function formatChartValue(
+  n: number,
+  format?: ChartValueFormat,
+  opts?: ChartFormatLocale,
+): string {
   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: Intl.NumberFormatOptions = { 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') {
     const p = n * 100
@@ -793,6 +1153,53 @@ function dateTicks(tMin: number, tMax: number): number[] {
   if (!ticks.length) 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: number[], target = 6): number[] {
+  if (times.length <= 1) return times.length ? [0] : []
+  const keyOf: Record<string, (d: Date) => number | string> = {
+    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: number[] | null = null
+  for (const unit of ['day', 'week', 'month', 'year'] as const) {
+    const at: number[] = []
+    let prev: number | string | null = 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: number, span: number): string {
   const d = new Date(t)
   if (span <= 70 * DAY) return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
@@ -802,10 +1209,26 @@ function fmtDate(t: number, span: number): string {
 
 type ResolvedSeries = ChartSeries & {
   color: string
-  kind: 'bar' | 'line' | 'area'
+  kind: 'bar' | 'line' | 'area' | 'candle' | 'box'
   axis: 'left' | 'right'
 }
 
+/**
+ * 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: ChartSeries, specType: ChartType): ResolvedSeries['kind'] {
+  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. */
@@ -843,6 +1266,43 @@ function axisDomain(
     for (const s of stackable) for (const v of s.values) note(v)
   }
   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
@@ -870,10 +1330,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
   const series: ResolvedSeries[] = 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)) as
-      | 'bar'
-      | 'line'
-      | 'area',
+    kind: kindOf(s, spec.type),
     axis: s.axis ?? 'left',
   }))
   const legend: ChartLegendItem[] = series.map((s) => ({ label: s.label, color: s.color }))
@@ -883,7 +1340,11 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     width,
     height,
     plot: { x: 0, y: 0, w: width, h: height },
+    axes: null,
     bars: [],
+    candles: [],
+    boxes: [],
+    errorBars: [],
     lines: [],
     slices: [],
     yTicks: [],
@@ -1003,7 +1464,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
       x: round(padL + slotW * i + slotW / 2),
     }))
     const yTicks: ChartAxisTick[] = 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,
@@ -1190,7 +1651,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = '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,
@@ -1226,8 +1687,13 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = '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: ChartGaugeLayout['target'] = null
@@ -1257,23 +1723,42 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = '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: number, ang: number) => `${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: string | null = null
-    for (const band of spec.gaugeRanges ?? []) {
-      if (value >= band.from && value <= band.to) valueColor = band.color
+    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 ?? '',
@@ -1544,7 +2029,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = '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,
@@ -1665,7 +2150,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     }
     const referenceLines: ChartRefLineGeo[] = (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,
     }))
@@ -1674,7 +2159,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = '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) })),
     }
   }
@@ -1761,7 +2246,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     }
 
     const valueTicks: ChartCategoryTick[] = 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: ChartAxisTick[] = spec.categories.map((label, i) => ({
@@ -1771,7 +2256,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     }))
     const referenceLinesV: ChartRefLineGeoV[] = (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,
     }))
@@ -1843,21 +2328,31 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
 
   // 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: number) =>
-    timeOk && Number.isFinite(timeVals![i])
+    timeScaled && Number.isFinite(timeVals![i])
       ? round(padL + ((timeVals![i]! - tMin) / tSpan) * plotW)
       : round(padL + slot * i + slot / 2)
-  const xTicks: ChartCategoryTick[] = timeOk
+  const xTicks: ChartCategoryTick[] = 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: ChartGeometry['categoryGroupTicks'] = []
@@ -1952,6 +2447,128 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = '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: ChartCandle[] = []
+  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: ChartBox[] = []
+  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: ChartErrorBar[] = []
+  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: ChartLine[] = []
   const areaCum: Record<'left' | 'right', number[]> = {
@@ -1975,7 +2592,12 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     }
   }
   for (const s of series) {
-    if (s.kind === 'bar') continue
+    // 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)
     const yA = (v: number) => yOf(dom, v, log)
@@ -2072,8 +2694,17 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     lines.push({ path, areaPath, color: s.color, label: s.label, points: pts, bandPath })
   }
 
+  // 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: NiceScale, log: boolean): ChartAxisTick[] =>
-    dom.ticks.map((value) => ({ value, y: yOf(dom, value, log), label: formatChartValue(value, spec.valueFormat) }))
+    dom.ticks.map((value) => ({
+      value,
+      y: yOf(dom, value, log),
+      label: spec.stacked100 ? `${round(value)}%` : formatChartValue(value, spec.valueFormat, spec),
+    }))
 
   const referenceLines: ChartRefLineGeo[] = (spec.referenceLines ?? []).map((ref) => {
     const onRight = ref.axis === 'right'
@@ -2081,7 +2712,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     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,
     }
@@ -2156,7 +2787,20 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = '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) : [],
@@ -2170,6 +2814,53 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
   }
 }
 
+/**
+ * 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: ChartSpec, lo: number, hi: number): ChartSpec {
+  const from = Math.max(0, lo)
+  const to = Math.min(spec.categories.length - 1, hi)
+  const cut = <T,>(arr: T[] | undefined): T[] | undefined =>
+    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:
@@ -2319,3 +3010,333 @@ export function rowsToChartSpec<T extends Record<string, unknown>>(
     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: ChartSpec, rootName = 'Total'): TreeNode {
+  const positive = (v: unknown) => (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: ChartSpec): Array<{ date: string; value: number }> {
+  const s = spec.series[0]
+  const out: Array<{ date: string; value: number }> = []
+  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: ChartSpec): {
+  nodes: Array<{ id: string; label?: string }>
+  links: Array<{ source: string; target: string; value: number }>
+} {
+  const links: Array<{ source: string; target: string; value: number }> = []
+  const ids = new Set<string>()
+  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<T extends Record<string, unknown>>(
+  type: ChartType,
+  rows: ReadonlyArray<T>,
+  opts: {
+    category?: string
+    /** The measure. For scatter this is X. */
+    value?: string
+    /** Scatter's Y measure. */
+    value2?: string
+    series?: string
+    reduce?: 'sum' | 'avg' | 'count'
+    palette?: string[]
+  },
+): ChartSpec | null {
+  const cat = opts.category as (keyof T & string) | undefined
+  const val = opts.value as (keyof T & string) | undefined
+  const ser = opts.series as (keyof T & string) | undefined
+  if (type === 'scatter') {
+    const y = opts.value2 as (keyof T & string) | undefined
+    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<T extends Record<string, unknown>>(
+  rows: ReadonlyArray<T>,
+  opts: {
+    category: keyof T & string
+    value: keyof T & string
+    /** One box series per distinct value of this field, side by side. */
+    series?: keyof T & string
+    seriesLabel?: string
+    /** Whisker length in IQRs. Default 1.5. */
+    whisker?: number
+    width?: number
+    height?: number
+  },
+): ChartSpec {
+  const cats: string[] = []
+  const seen = new Set<string>()
+  for (const r of rows) {
+    const c = String(r[opts.category] ?? '')
+    if (!seen.has(c)) {
+      seen.add(c)
+      cats.push(c)
+    }
+  }
+  const groupNames: string[] = []
+  const groupSeen = new Set<string>()
+  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: ChartSeries[] = groupNames.map((g) => {
+    const boxes: Array<BoxStats | null> = cats.map((c) => {
+      const sample: number[] = []
+      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<T extends Record<string, unknown>>(
+  rows: ReadonlyArray<T>,
+  opts: {
+    x: keyof T & string
+    y: keyof T & string
+    /** Bubble radius field. Omit for a plain scatter. */
+    r?: keyof T & string
+    /** Group points into one series per distinct value. */
+    series?: keyof T & string
+    /** Per-point label, shown in the tooltip. */
+    label?: keyof T & string
+    palette?: string[]
+    width?: number
+    height?: number
+  },
+): ChartSpec {
+  const bySeries = new Map<string, ScatterPoint[]>()
+  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 as string)
+    const pt: ScatterPoint = { 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<T extends Record<string, unknown>>(
+  rows: ReadonlyArray<T>,
+  opts: {
+    value: keyof T & string
+    reduce?: 'sum' | 'avg' | 'count'
+    min?: number
+    max?: number
+    unit?: string
+    target?: number
+    width?: number
+    height?: number
+  },
+): ChartSpec {
+  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,
+  }
+}