@svgrid/grid 3.0.1 → 3.0.3

package/src/chart.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { buildChart, rowsToChartSpec, niceScale } from './chart'
+import { buildChart, rowsToChartSpec, niceScale, sliceChartWindow, specToTreemap, specToCalendar, specToSankey, rowsToScatterSpec, rowsToGaugeSpec, boxStats, rowsToBoxSpec, chartScales } from './chart'
+import type { ChartSpec } from './chart'
 
 describe('niceScale', () => {
   it('rounds a positive domain to nice ticks including 0', () => {
@@ -158,6 +159,18 @@ describe('buildChart', () => {
     expect(g.bars.map((b) => b.value).sort()).toEqual([1, 3])
   })
 
+  it('stacked100 labels the axis as a percentage, not as the measure', () => {
+    // The axis is a share of the total there, so a currency format would give
+    // an axis reading 0 to 100 in currency for what are percentages.
+    const g = buildChart({
+      type: 'bar', stacked100: true, valueFormat: 'currency',
+      categories: ['A'],
+      series: [{ label: 'x', values: [1] }, { label: 'y', values: [3] }],
+    })
+    expect(g.yTicks.map((t) => t.label)).toContain('100%')
+    expect(g.yTicks.every((t) => !t.label.includes('$'))).toBe(true)
+  })
+
   it('stacked100 area: the top series reaches the 100% line, not the raw total', () => {
     const g = buildChart({
       type: 'area',
@@ -309,3 +322,819 @@ describe('rowsToChartSpec', () => {
     expect(spec.stacked100).toBe(true)
   })
 })
+
+describe('sliceChartWindow (the zoom / brush window)', () => {
+  const banded = (): ChartSpec => ({
+    type: 'line',
+    categories: ['a', 'b', 'c', 'd', 'e'],
+    series: [
+      {
+        label: 'forecast',
+        values: [1, 2, 3, 4, 5],
+        upperValues: [2, 3, 4, 5, 6],
+        lowerValues: [0, 1, 2, 3, 4],
+        rowIds: [['r1'], ['r2'], ['r3'], ['r4'], ['r5']],
+      },
+    ],
+  })
+
+  it('keeps every category-parallel array the same length', () => {
+    const w = sliceChartWindow(banded(), 1, 3)
+    const s = w.series[0]!
+    expect(w.categories).toEqual(['b', 'c', 'd'])
+    expect(s.values).toEqual([2, 3, 4])
+    expect(s.upperValues).toEqual([3, 4, 5])
+    expect(s.lowerValues).toEqual([1, 2, 3])
+    expect(s.rowIds).toEqual([['r2'], ['r3'], ['r4']])
+  })
+
+  it('still draws the confidence band after zooming', () => {
+    // The regression this function exists for. The window used to slice
+    // `values` but not the envelopes, so their lengths stopped matching and
+    // buildChart's equality guard dropped the band without a word.
+    const full = buildChart(banded())
+    expect(full.lines[0]!.bandPath).not.toBe('')
+
+    const zoomed = buildChart(sliceChartWindow(banded(), 1, 3))
+    expect(zoomed.lines[0]!.bandPath, 'band vanished inside the zoom window').not.toBe('')
+  })
+
+  it('slices ohlc, boxes and errors with the window', () => {
+    // Same defect class as the band above, and the reason to assert every
+    // per-category array rather than the one that broke last time: a missed
+    // array does not throw, it silently draws against the wrong categories.
+    const spec: ChartSpec = {
+      type: 'candlestick',
+      categories: ['a', 'b', 'c', 'd'],
+      series: [
+        {
+          label: 'px',
+          values: [1, 2, 3, 4],
+          ohlc: [
+            { o: 1, h: 2, l: 0, c: 1 },
+            { o: 2, h: 3, l: 1, c: 2 },
+            { o: 3, h: 4, l: 2, c: 3 },
+            { o: 4, h: 5, l: 3, c: 4 },
+          ],
+          boxes: [
+            { min: 0, q1: 1, median: 2, q3: 3, max: 4 },
+            { min: 1, q1: 2, median: 3, q3: 4, max: 5 },
+            { min: 2, q1: 3, median: 4, q3: 5, max: 6 },
+            { min: 3, q1: 4, median: 5, q3: 6, max: 7 },
+          ],
+          errors: [0.1, 0.2, 0.3, 0.4],
+        },
+      ],
+    }
+    const s = sliceChartWindow(spec, 1, 2).series[0]!
+    expect(s.values).toEqual([2, 3])
+    expect(s.ohlc).toHaveLength(2)
+    expect(s.ohlc![0]!.c).toBe(2)
+    expect(s.boxes).toHaveLength(2)
+    expect(s.boxes![0]!.median).toBe(3)
+    expect(s.errors).toEqual([0.2, 0.3])
+  })
+
+  it('draws a zoomed candlestick against the right categories', () => {
+    // Before the slice covered `ohlc`, the geometry walked the full-length
+    // array against three categories, so candles landed off the plot.
+    const spec: ChartSpec = {
+      type: 'candlestick',
+      categories: ['a', 'b', 'c', 'd', 'e'],
+      series: [
+        {
+          label: 'px',
+          values: [1, 2, 3, 4, 5],
+          ohlc: [
+            { o: 1, h: 2, l: 0, c: 1 },
+            { o: 2, h: 3, l: 1, c: 2 },
+            { o: 3, h: 4, l: 2, c: 3 },
+            { o: 4, h: 5, l: 3, c: 4 },
+            { o: 5, h: 6, l: 4, c: 5 },
+          ],
+        },
+      ],
+      width: 400,
+      height: 300,
+    }
+    const zoomed = buildChart(sliceChartWindow(spec, 1, 3))
+    expect(zoomed.candles).toHaveLength(3)
+    expect(zoomed.candles.map((c) => c.label)).toEqual(['b', 'c', 'd'])
+    for (const c of zoomed.candles) {
+      expect(c.xCenter).toBeGreaterThanOrEqual(zoomed.plot.x)
+      expect(c.xCenter).toBeLessThanOrEqual(zoomed.plot.x + zoomed.plot.w)
+    }
+  })
+
+  it('carries waterfall totals with the window', () => {
+    const w = sliceChartWindow(
+      { type: 'waterfall', categories: ['a', 'b', 'c'], series: [{ label: 's', values: [1, 2, 3] }], waterfallTotals: [false, false, true] },
+      1,
+      2,
+    )
+    expect(w.waterfallTotals).toEqual([false, true])
+  })
+
+  it('clamps a window that runs past either end', () => {
+    const w = sliceChartWindow(banded(), -5, 99)
+    expect(w.categories).toHaveLength(5)
+    expect(w.series[0]!.values).toHaveLength(5)
+  })
+
+  it('leaves a series without envelopes undisturbed', () => {
+    const w = sliceChartWindow(
+      { type: 'bar', categories: ['a', 'b'], series: [{ label: 's', values: [1, 2] }] },
+      0,
+      1,
+    )
+    expect(w.series[0]!.upperValues).toBeUndefined()
+    expect(w.series[0]!.rowIds).toBeUndefined()
+  })
+})
+
+describe('buildChart: candlestick / OHLC', () => {
+  const bars = [
+    { o: 100, h: 110, l: 95, c: 105 },
+    { o: 105, h: 108, l: 99, c: 101 },
+    { o: 101, h: 120, l: 100, c: 118 },
+  ]
+  const priced = (extra: Partial<ChartSpec> = {}): ChartSpec => ({
+    type: 'candlestick',
+    categories: ['2026-03-02', '2026-03-03', '2026-03-04'],
+    series: [{ label: 'ACME', values: bars.map((b) => b.c), ohlc: bars }],
+    ...extra,
+  })
+
+  it('draws one candle per bar, body spanning open to close', () => {
+    const g = buildChart(priced())
+    expect(g.candles).toHaveLength(3)
+    const first = g.candles[0]!
+    // SVG y grows downward, so a rising candle opens BELOW its close on screen.
+    expect(first.up).toBe(true)
+    expect(first.bodyY).toBe(Math.min(first.yOpen, first.yClose))
+    expect(first.bodyH).toBeCloseTo(Math.abs(first.yClose - first.yOpen), 5)
+    // Wick brackets the body.
+    expect(first.yHigh).toBeLessThanOrEqual(first.bodyY)
+    expect(first.yLow).toBeGreaterThanOrEqual(first.bodyY + first.bodyH)
+  })
+
+  it('colours by direction, not by series', () => {
+    const g = buildChart(priced({ candleColors: { up: '#00f', down: '#f00' } }))
+    expect(g.candles.map((k) => k.color)).toEqual(['#00f', '#f00', '#00f'])
+  })
+
+  it('does not drag the price axis down to zero', () => {
+    // Candles are not stackable, so the bar chart's "always include 0" rule
+    // must not fire. A 95..120 price series pinned to a zero baseline wastes
+    // four fifths of the plot and is the whole reason `kind` is its own value.
+    const g = buildChart(priced())
+    expect(g.yTicks[0]!.value).toBeGreaterThan(0)
+  })
+
+  it('does not also draw the closes as a line over the candles', () => {
+    // `values` carries the closes so tooltips, CSV and overlays keep working.
+    // That is only safe while the line loop skips candle series.
+    const g = buildChart(priced())
+    expect(g.lines).toEqual([])
+  })
+
+  it('still draws a moving-average overlay from those same closes', () => {
+    const withMa = priced()
+    withMa.series[0]!.overlay = 'sma:2'
+    const g = buildChart(withMa)
+    expect(g.overlays.length).toBe(1)
+    expect(g.lines).toEqual([])
+  })
+
+  it('ohlc renders the same geometry as candlestick', () => {
+    const a = buildChart(priced())
+    const b = buildChart(priced({ type: 'ohlc' }))
+    expect(b.candles).toEqual(a.candles)
+  })
+
+  it('skips a null bar without shifting the rest', () => {
+    const withGap = priced()
+    withGap.series[0]!.ohlc = [bars[0]!, null, bars[2]!]
+    const g = buildChart(withGap)
+    expect(g.candles).toHaveLength(2)
+    expect(g.candles.map((k) => k.label)).toEqual(['2026-03-02', '2026-03-04'])
+  })
+
+  it('keeps a doji visible', () => {
+    const flat = priced()
+    flat.series[0]!.ohlc = [{ o: 100, h: 104, l: 96, c: 100 }]
+    flat.categories = ['2026-03-02']
+    flat.series[0]!.values = [100]
+    expect(buildChart(flat).candles[0]!.bodyH).toBeGreaterThanOrEqual(1)
+  })
+
+  it('returns empty geometry when no series carries ohlc', () => {
+    const g = buildChart({ type: 'candlestick', categories: ['a'], series: [{ label: 's', values: [1] }] })
+    expect(g.candles).toEqual([])
+  })
+
+  it('carries a volume series on the right axis alongside the prices', () => {
+    const g = buildChart(
+      priced({
+        series: [
+          { label: 'ACME', values: bars.map((b) => b.c), ohlc: bars },
+          { label: 'Volume', values: [12, 30, 21], type: 'bar', axis: 'right' },
+        ],
+      }),
+    )
+    expect(g.candles).toHaveLength(3)
+    expect(g.bars).toHaveLength(3)
+    expect(g.hasRightAxis).toBe(true)
+  })
+
+  it('drops a non-positive price on a log axis instead of emitting NaN', () => {
+    const bad = priced({ yScale: 'log' })
+    bad.series[0]!.ohlc = [{ o: 0, h: 10, l: -5, c: 8 }, bars[1]!, bars[2]!]
+    const g = buildChart(bad)
+    expect(g.candles).toHaveLength(2)
+    for (const k of g.candles) {
+      for (const v of [k.yOpen, k.yClose, k.yHigh, k.yLow]) expect(Number.isFinite(v)).toBe(true)
+    }
+  })
+})
+
+describe("xType: 'ordinal-time'", () => {
+  // Fri, Mon, Tue: a real weekend sits between the first two.
+  const sessions = ['2026-03-06', '2026-03-09', '2026-03-10']
+  const spec = (xType: ChartSpec['xType']): ChartSpec => ({
+    type: 'line',
+    categories: sessions,
+    series: [{ label: 'p', values: [1, 2, 3] }],
+    xType,
+  })
+
+  it('spaces sessions evenly across a weekend', () => {
+    const g = buildChart(spec('ordinal-time'))
+    const xs = g.lines[0]!.points.map((p) => p.x)
+    expect(xs[1]! - xs[0]!).toBeCloseTo(xs[2]! - xs[1]!, 5)
+  })
+
+  it("differs from 'time', which leaves the weekend as a gap", () => {
+    const g = buildChart(spec('time'))
+    const xs = g.lines[0]!.points.map((p) => p.x)
+    // Three calendar days versus one, so the first gap is the wider one.
+    expect(xs[1]! - xs[0]!).toBeGreaterThan(xs[2]! - xs[1]!)
+  })
+
+  it('labels ticks from the dates and puts them on real points', () => {
+    const g = buildChart(spec('ordinal-time'))
+    expect(g.xTicks.length).toBeGreaterThan(0)
+    const pointXs = g.lines[0]!.points.map((p) => p.x)
+    for (const t of g.xTicks) {
+      expect(t.label).not.toBe('')
+      expect(pointXs).toContain(t.x)
+    }
+  })
+
+  it('falls back to the raw labels when nothing parses as a date', () => {
+    const g = buildChart({
+      type: 'line',
+      categories: ['north', 'south'],
+      series: [{ label: 'p', values: [1, 2] }],
+      xType: 'ordinal-time',
+    })
+    expect(g.xTicks.map((t) => t.label)).toEqual(['north', 'south'])
+  })
+})
+
+describe('shape adapters (the types the panel could not reach)', () => {
+  const rows = [
+    { region: 'EMEA', channel: 'web', date: '2026-03-02', revenue: 100, deals: 4, id: 'r1' },
+    { region: 'EMEA', channel: 'shop', date: '2026-03-03', revenue: 50, deals: 2, id: 'r2' },
+    { region: 'APAC', channel: 'web', date: '2026-03-04', revenue: 70, deals: 9, id: 'r3' },
+  ]
+
+  it('specToTreemap: one level from a single series', () => {
+    const t = specToTreemap(rowsToChartSpec(rows, { type: 'treemap', category: 'region', value: 'revenue' }))
+    expect(t.children!.map((c) => c.name).sort()).toEqual(['APAC', 'EMEA'])
+    expect(t.children!.find((c) => c.name === 'EMEA')!.value).toBe(150)
+  })
+
+  it('specToTreemap: two levels when a split-by produced several series', () => {
+    const t = specToTreemap(
+      rowsToChartSpec(rows, { type: 'treemap', category: 'region', value: 'revenue', series: 'channel' }),
+    )
+    const emea = t.children!.find((c) => c.name === 'EMEA')!
+    expect(emea.children!.map((c) => c.name).sort()).toEqual(['shop', 'web'])
+  })
+
+  it('specToTreemap: drops non-positive leaves, which have no area', () => {
+    const t = specToTreemap({ type: 'treemap', categories: ['a', 'b'], series: [{ label: 's', values: [5, -3] }] })
+    expect(t.children!.map((c) => c.name)).toEqual(['a'])
+  })
+
+  it('specToCalendar: normalises categories to YYYY-MM-DD', () => {
+    const c = specToCalendar(rowsToChartSpec(rows, { type: 'calendar', category: 'date', value: 'deals' }))
+    expect(c).toEqual([
+      { date: '2026-03-02', value: 4 },
+      { date: '2026-03-03', value: 2 },
+      { date: '2026-03-04', value: 9 },
+    ])
+  })
+
+  it('specToCalendar: drops a category that is not a date rather than placing it at epoch 0', () => {
+    const c = specToCalendar({ type: 'calendar', categories: ['north', '2026-03-02'], series: [{ label: 's', values: [1, 2] }] })
+    expect(c).toEqual([{ date: '2026-03-02', value: 2 }])
+  })
+
+  it('specToSankey: a pivot becomes an edge list', () => {
+    const { nodes, links } = specToSankey(
+      rowsToChartSpec(rows, { type: 'sankey', category: 'region', value: 'revenue', series: 'channel' }),
+    )
+    expect(links).toHaveLength(3)
+    expect(links.every((l) => l.value > 0)).toBe(true)
+    // Sources and targets are namespaced, so a name on both sides is two nodes
+    // rather than one node with a loop through it.
+    expect(nodes.every((n) => n.id.startsWith('from:') || n.id.startsWith('to:'))).toBe(true)
+    expect(new Set(nodes.map((n) => n.id)).size).toBe(nodes.length)
+  })
+
+  it('rowsToScatterSpec: one point per row, grouped into series', () => {
+    const s = rowsToScatterSpec(rows, { x: 'revenue', y: 'deals', series: 'channel' })
+    expect(s.type).toBe('scatter')
+    expect(s.series.map((x) => x.label).sort()).toEqual(['shop', 'web'])
+    expect(s.series.find((x) => x.label === 'web')!.points).toHaveLength(2)
+    expect(buildChart(s).scatterPoints).toHaveLength(3)
+  })
+
+  it('rowsToScatterSpec: skips rows whose x or y is not numeric', () => {
+    const s = rowsToScatterSpec([{ a: 1, b: 2 }, { a: 'x', b: 3 }], { x: 'a', y: 'b' })
+    expect(s.series[0]!.points).toHaveLength(1)
+  })
+
+  it('rowsToGaugeSpec: reduces to one number and rounds the dial end up', () => {
+    const g = rowsToGaugeSpec(rows, { value: 'revenue' })
+    expect(g.gaugeValue).toBe(220)
+    // The needle must not sit pinned at the very end of the arc.
+    expect(g.gaugeMax!).toBeGreaterThanOrEqual(220)
+    expect(buildChart(g).gauge).not.toBeNull()
+  })
+
+  it('rowsToGaugeSpec: honours avg and count', () => {
+    expect(rowsToGaugeSpec(rows, { value: 'deals', reduce: 'count' }).gaugeValue).toBe(3)
+    expect(rowsToGaugeSpec(rows, { value: 'deals', reduce: 'avg' }).gaugeValue).toBeCloseTo(5, 5)
+  })
+
+  it('every adapter survives an empty row set', () => {
+    const empty = rowsToChartSpec([] as Array<{ a: string; b: number }>, { type: 'bar', category: 'a', value: 'b' })
+    expect(specToTreemap(empty).children).toEqual([])
+    expect(specToCalendar(empty)).toEqual([])
+    expect(specToSankey(empty).links).toEqual([])
+    expect(rowsToScatterSpec([] as Array<{ a: number; b: number }>, { x: 'a', y: 'b' }).series).toEqual([])
+    expect(rowsToGaugeSpec([] as Array<{ a: number }>, { value: 'a' }).gaugeValue).toBe(0)
+  })
+})
+
+describe('gauge bands', () => {
+  // Bands normally share endpoints, so which side of a boundary a value falls
+  // on decides its colour. Half-open [from, to), first match wins.
+  const bands = [
+    { from: 0, to: 0.3, color: 'green' },
+    { from: 0.3, to: 0.45, color: 'amber' },
+    { from: 0.45, to: 5, color: 'red' },
+  ]
+  const dial = (gaugeValue: number): ChartSpec => ({
+    type: 'gauge',
+    categories: [],
+    series: [],
+    gaugeValue,
+    gaugeMin: 0,
+    gaugeMax: 5,
+    gaugeRanges: bands,
+  })
+
+  it('a value inside a band takes that band', () => {
+    expect(buildChart(dial(0.4)).gauge!.valueColor).toBe('amber')
+    expect(buildChart(dial(0.1)).gauge!.valueColor).toBe('green')
+    expect(buildChart(dial(3)).gauge!.valueColor).toBe('red')
+  })
+
+  it('a value exactly on a boundary belongs to the band it opens', () => {
+    // This is the one that was wrong: an inclusive `to` plus last-match-wins
+    // gave 0.45 the colour of the band ABOVE it.
+    expect(buildChart(dial(0.3)).gauge!.valueColor).toBe('amber')
+    expect(buildChart(dial(0.45)).gauge!.valueColor).toBe('red')
+  })
+
+  it('the top of the scale still lands in the last band', () => {
+    expect(buildChart(dial(5)).gauge!.valueColor).toBe('red')
+  })
+
+  it('keeps the bands clear of the value arc', () => {
+    // Bands are context on their own inner ring; the value arc is the reading.
+    // Drawn at the same radius, a band spanning most of the scale swamps it.
+    const g = buildChart(dial(0.45)).gauge!
+    const bandR = Number(/A([\d.]+),/.exec(g.rangePaths[0]!.path)![1])
+    expect(bandR).toBeLessThan(g.r - 8)
+  })
+})
+
+describe('boxStats (the five-number summary)', () => {
+  it('computes quartiles and stops the whiskers at real observations', () => {
+    // Whiskers land on the last point INSIDE the 1.5 IQR fence, not on the
+    // fence itself, which is what makes them read as data rather than as a
+    // calculated boundary.
+    const b = boxStats([1, 2, 3, 4, 5, 6, 7, 8, 9])!
+    expect(b.median).toBe(5)
+    expect(b.q1).toBe(3)
+    expect(b.q3).toBe(7)
+    expect(b.min).toBe(1)
+    expect(b.max).toBe(9)
+    expect(b.outliers).toBeUndefined()
+  })
+
+  it('splits points beyond the fence into outliers', () => {
+    const b = boxStats([10, 11, 12, 13, 14, 15, 90])!
+    expect(b.outliers).toEqual([90])
+    // The whisker stops at the largest value still inside the fence.
+    expect(b.max).toBe(15)
+  })
+
+  it('interpolates quartiles between order statistics', () => {
+    // 4 points: q1 sits between the 1st and 2nd.
+    const b = boxStats([1, 2, 3, 4])!
+    expect(b.q1).toBeCloseTo(1.75, 5)
+    expect(b.median).toBeCloseTo(2.5, 5)
+    expect(b.q3).toBeCloseTo(3.25, 5)
+  })
+
+  it('returns null for an empty sample, so the category is a gap', () => {
+    expect(boxStats([])).toBeNull()
+    expect(boxStats([Number.NaN, Number.POSITIVE_INFINITY])).toBeNull()
+  })
+
+  it('handles a single observation and a zero-spread sample', () => {
+    const one = boxStats([7])!
+    expect(one).toMatchObject({ min: 7, q1: 7, median: 7, q3: 7, max: 7 })
+    const flat = boxStats([3, 3, 3, 3])!
+    expect(flat.q1).toBe(3)
+    expect(flat.outliers).toBeUndefined()
+  })
+})
+
+describe('buildChart: box plots', () => {
+  const spec = (): ChartSpec => ({
+    type: 'boxplot',
+    categories: ['a', 'b'],
+    series: [
+      {
+        label: 'latency',
+        // `values` holds the medians, the way `ohlc` sets closes.
+        values: [20, 30],
+        boxes: [
+          { min: 10, q1: 15, median: 20, q3: 25, max: 30, outliers: [45] },
+          { min: 20, q1: 25, median: 30, q3: 35, max: 40 },
+        ],
+      },
+    ],
+    width: 400,
+    height: 300,
+  })
+
+  it('lays out a box per category, ordered and inside the plot', () => {
+    const geo = buildChart(spec())
+    expect(geo.boxes).toHaveLength(2)
+    const b = geo.boxes[0]!
+    // SVG y grows downward, so the max whisker is the SMALLEST y.
+    expect(b.yMax).toBeLessThan(b.yQ3)
+    expect(b.yQ3).toBeLessThan(b.yMedian)
+    expect(b.yMedian).toBeLessThan(b.yQ1)
+    expect(b.yQ1).toBeLessThan(b.yMin)
+    expect(b.boxY).toBe(Math.min(b.yQ1, b.yQ3))
+    expect(b.boxH).toBeGreaterThan(0)
+    expect(b.label).toBe('a')
+  })
+
+  it('positions outliers and carries the raw numbers for the tooltip', () => {
+    const geo = buildChart(spec())
+    const b = geo.boxes[0]!
+    expect(b.outliers).toHaveLength(1)
+    expect(b.outliers[0]!.value).toBe(45)
+    // The outlier is above the upper whisker, so a smaller y.
+    expect(b.outliers[0]!.y).toBeLessThan(b.yMax)
+    expect(b).toMatchObject({ min: 10, q1: 15, median: 20, q3: 25, max: 30 })
+  })
+
+  it('scales the axis to the whiskers and outliers, not the medians', () => {
+    // `values` are 20 and 30; a domain built from those would clip every box.
+    const geo = buildChart(spec())
+    const top = geo.yTicks[geo.yTicks.length - 1]!.value
+    expect(top).toBeGreaterThanOrEqual(45)
+    expect(geo.yTicks[0]!.value).toBeLessThanOrEqual(10)
+  })
+
+  it('never also draws the medians as a line', () => {
+    // The candlestick bug: `values` exists for tooltips / CSV / overlays, and
+    // was drawn a second time as a dotted line straight over the marks.
+    const geo = buildChart(spec())
+    expect(geo.lines).toHaveLength(0)
+    expect(geo.bars).toHaveLength(0)
+  })
+
+  it('treats a null box as a gap and returns empty geometry for no data', () => {
+    const withGap = spec()
+    withGap.series[0]!.boxes = [null, { min: 1, q1: 2, median: 3, q3: 4, max: 5 }]
+    expect(buildChart(withGap).boxes).toHaveLength(1)
+    expect(buildChart({ type: 'boxplot', categories: [], series: [] }).boxes).toEqual([])
+  })
+
+  it('shares the slot between two box series, like grouped bars', () => {
+    const two = spec()
+    two.series.push({
+      label: 'p99',
+      values: [40, 50],
+      boxes: [
+        { min: 30, q1: 35, median: 40, q3: 45, max: 50 },
+        { min: 40, q1: 45, median: 50, q3: 55, max: 60 },
+      ],
+    })
+    const geo = buildChart(two)
+    expect(geo.boxes).toHaveLength(4)
+    const first = geo.boxes.filter((b) => b.label === 'a')
+    expect(first).toHaveLength(2)
+    expect(first[0]!.x).not.toBe(first[1]!.x)
+  })
+})
+
+describe('buildChart: error bars', () => {
+  const spec = (errors: ChartSpec['series'][number]['errors']): ChartSpec => ({
+    type: 'bar',
+    categories: ['a', 'b'],
+    series: [{ label: 'mean', values: [10, 20], errors }],
+    width: 400,
+    height: 300,
+  })
+
+  it('draws a symmetric margin around the value', () => {
+    const geo = buildChart(spec([2, 3]))
+    expect(geo.errorBars).toHaveLength(2)
+    expect(geo.errorBars[0]).toMatchObject({ lo: 8, hi: 12 })
+    expect(geo.errorBars[1]).toMatchObject({ lo: 17, hi: 23 })
+    // Higher value, smaller y.
+    expect(geo.errorBars[0]!.yHi).toBeLessThan(geo.errorBars[0]!.yLo)
+  })
+
+  it('accepts an explicit asymmetric pair and normalizes the order', () => {
+    const geo = buildChart(spec([{ lo: 9, hi: 14 }, { hi: 18, lo: 25 }]))
+    expect(geo.errorBars[0]).toMatchObject({ lo: 9, hi: 14 })
+    expect(geo.errorBars[1]).toMatchObject({ lo: 18, hi: 25 })
+  })
+
+  it('extends the axis domain past the mark, so a whisker cannot clip', () => {
+    const withBars = buildChart(spec([0, 40]))
+    const top = withBars.yTicks[withBars.yTicks.length - 1]!.value
+    expect(top).toBeGreaterThanOrEqual(60)
+  })
+
+  it('skips a null entry and still draws the bar it annotates', () => {
+    const geo = buildChart(spec([null, 3]))
+    expect(geo.errorBars).toHaveLength(1)
+    expect(geo.errorBars[0]!.label).toBe('b')
+    expect(geo.bars).toHaveLength(2)
+  })
+
+  it('annotates a line series too, without changing its type', () => {
+    const geo = buildChart({
+      type: 'line',
+      categories: ['a', 'b'],
+      series: [{ label: 'm', values: [10, 20], errors: [1, 1] }],
+      width: 400,
+      height: 300,
+    })
+    expect(geo.lines).toHaveLength(1)
+    expect(geo.errorBars).toHaveLength(2)
+  })
+})
+
+describe('rowsToBoxSpec (the panel path)', () => {
+  const rows = [
+    { team: 'A', ms: 10 }, { team: 'A', ms: 12 }, { team: 'A', ms: 14 }, { team: 'A', ms: 90 },
+    { team: 'B', ms: 20 }, { team: 'B', ms: 22 }, { team: 'B', ms: 24 },
+  ]
+
+  it('groups rows into one box per category', () => {
+    const spec = rowsToBoxSpec(rows, { category: 'team', value: 'ms' })
+    expect(spec.type).toBe('boxplot')
+    expect(spec.categories).toEqual(['A', 'B'])
+    const boxes = spec.series[0]!.boxes!
+    expect(boxes).toHaveLength(2)
+    expect(boxes[0]!.outliers).toEqual([90])
+    expect(boxes[1]!.median).toBe(22)
+  })
+
+  it('sets values to the medians so tooltips and CSV keep working', () => {
+    const spec = rowsToBoxSpec(rows, { category: 'team', value: 'ms' })
+    expect(spec.series[0]!.values).toEqual([13, 22])
+  })
+
+  it('splits into side-by-side series on a second field', () => {
+    const split = [
+      { team: 'A', env: 'prod', ms: 10 }, { team: 'A', env: 'prod', ms: 12 },
+      { team: 'A', env: 'dev', ms: 30 }, { team: 'A', env: 'dev', ms: 32 },
+    ]
+    const spec = rowsToBoxSpec(split, { category: 'team', value: 'ms', series: 'env' })
+    expect(spec.series.map((s) => s.label)).toEqual(['prod', 'dev'])
+    expect(spec.series[1]!.boxes![0]!.median).toBe(31)
+    expect(buildChart({ ...spec, width: 400, height: 300 }).boxes).toHaveLength(2)
+  })
+
+  it('leaves a category with no numeric sample as a gap, not a zero', () => {
+    const spec = rowsToBoxSpec(
+      [{ team: 'A', ms: 5 }, { team: 'B', ms: null as unknown as number }],
+      { category: 'team', value: 'ms' },
+    )
+    expect(spec.series[0]!.boxes![1]).toBeNull()
+    expect(Number.isNaN(spec.series[0]!.values[1]!)).toBe(true)
+    expect(buildChart({ ...spec, width: 400, height: 300 }).boxes).toHaveLength(1)
+  })
+})
+
+describe('category axis label thinning', () => {
+  const line = (n: number, width = 800): ChartSpec => ({
+    type: 'line',
+    categories: Array.from({ length: n }, (_, i) => `c${i}`),
+    series: [{ label: 's', values: Array.from({ length: n }, (_, i) => i % 50) }],
+    width,
+    height: 400,
+  })
+
+  it('labels every category while they fit', () => {
+    // The threshold is set just under the spacing a 40-category chart at 800px
+    // already had, so charts that read fine before are untouched.
+    expect(buildChart(line(2)).xTicks).toHaveLength(2)
+    expect(buildChart(line(12)).xTicks).toHaveLength(12)
+    expect(buildChart(line(40)).xTicks).toHaveLength(40)
+  })
+
+  it('thins once labels would overlap, and never grows without bound', () => {
+    const many = buildChart(line(5000)).xTicks
+    expect(many.length).toBeLessThan(60)
+    expect(many.length).toBeGreaterThan(10)
+    // 5000 labels were 5000 <text> nodes stacked into an unreadable band, and
+    // the single biggest thing the renderer had to put in the DOM.
+    expect(buildChart(line(500)).xTicks.length).toBeLessThan(60)
+  })
+
+  it('keeps the first category labelled, so the axis starts where the data does', () => {
+    expect(buildChart(line(5000)).xTicks[0]!.label).toBe('c0')
+  })
+
+  it('thins by available width, not by count alone', () => {
+    const narrow = buildChart(line(200, 400)).xTicks.length
+    const wide = buildChart(line(200, 1600)).xTicks.length
+    expect(wide).toBeGreaterThan(narrow)
+  })
+
+  it('leaves ticks in ascending x order after thinning', () => {
+    const ticks = buildChart(line(1000)).xTicks
+    for (let i = 1; i < ticks.length; i += 1) expect(ticks[i]!.x).toBeGreaterThan(ticks[i - 1]!.x)
+  })
+})
+
+describe('chartScales (the custom-series seam)', () => {
+  const spec = (over: Partial<ChartSpec> = {}): ChartSpec => ({
+    type: 'bar',
+    categories: ['a', 'b', 'c', 'd'],
+    series: [{ label: 's', values: [10, 20, 30, 40] }],
+    width: 500,
+    height: 300,
+    ...over,
+  })
+
+  it('lands a custom mark exactly where the built-in one is', () => {
+    // The whole point. A caller recomputing the scale from the raw data would
+    // miss the nice-scale rounding and the "always include zero" rule, and its
+    // marks would sit a few pixels off in a way that reads as a rendering bug.
+    const geo = buildChart(spec())
+    const sc = chartScales(geo)!
+    // The category tick is the authoritative x - that is where the axis label
+    // sits - and `xOf` matches it exactly.
+    geo.xTicks.forEach((t, i) => expect(sc.xOf(i)).toBeCloseTo(t.x, 6))
+    geo.bars.forEach((bar, i) => {
+      // A bar's own centre can be a half pixel off its slot: the bar width is
+      // rounded before it is centred. Within a pixel of the tick, which is what
+      // the eye compares it against.
+      expect(Math.abs(sc.xOf(i) - (bar.x + bar.w / 2))).toBeLessThanOrEqual(1)
+      expect(sc.yOf(bar.value)).toBeCloseTo(bar.y, 0)
+    })
+  })
+
+  it('agrees with the axis ticks it was drawn from', () => {
+    const geo = buildChart(spec({ type: 'line' }))
+    const sc = chartScales(geo)!
+    for (const t of geo.yTicks) expect(sc.yOf(t.value)).toBeCloseTo(t.y, 0)
+  })
+
+  it('maps the right axis separately when there is one', () => {
+    const geo = buildChart(spec({
+      series: [
+        { label: 'left', values: [10, 20, 30, 40], axis: 'left' },
+        { label: 'right', values: [0.1, 0.2, 0.3, 0.9], type: 'line', axis: 'right' },
+      ],
+    }))
+    const sc = chartScales(geo)!
+    expect(geo.axes!.y2).not.toBeNull()
+    // Same number, different axis, different pixel - or the second axis is a lie.
+    expect(sc.yOf(0.5, 'right')).not.toBeCloseTo(sc.yOf(0.5, 'left'), 0)
+    for (const t of geo.y2Ticks) expect(sc.yOf(t.value, 'right')).toBeCloseTo(t.y, 0)
+  })
+
+  it('inverts back to the value and the category it came from', () => {
+    const geo = buildChart(spec())
+    const sc = chartScales(geo)!
+    expect(sc.yInvert(sc.yOf(25))).toBeCloseTo(25, 4)
+    for (let i = 0; i < 4; i += 1) expect(sc.xInvert(sc.xOf(i))).toBe(i)
+    // Clamped rather than off the end.
+    expect(sc.xInvert(-500)).toBe(0)
+    expect(sc.xInvert(99_999)).toBe(3)
+  })
+
+  it('round-trips on a log axis too', () => {
+    const geo = buildChart(spec({ yScale: 'log', series: [{ label: 's', values: [1, 10, 100, 1000] }] }))
+    const sc = chartScales(geo)!
+    expect(sc.yInvert(sc.yOf(50))).toBeCloseTo(50, 3)
+    // A value the axis cannot express is NaN, not a silently wrong pixel.
+    expect(Number.isNaN(sc.yOf(0))).toBe(true)
+  })
+
+  it('is null for the types where plot coordinates mean nothing', () => {
+    for (const type of ['pie', 'gauge', 'treemap', 'sankey', 'radar', 'funnel', 'calendar'] as const) {
+      const geo = buildChart({ ...spec(), type })
+      expect(chartScales(geo), `${type} should have no cartesian scale`).toBeNull()
+      expect(geo.axes).toBeNull()
+    }
+  })
+
+  it('reports the axes a candlestick and a box plot were drawn against', () => {
+    // Both keep out of the zero-baseline rule, so their domain is not something
+    // a caller could guess from the data.
+    const px = buildChart({
+      type: 'candlestick',
+      categories: ['a', 'b'],
+      series: [{ label: 'p', values: [190, 192], ohlc: [{ o: 189, h: 195, l: 188, c: 190 }, { o: 190, h: 196, l: 189, c: 192 }] }],
+      width: 400, height: 300,
+    })
+    expect(px.axes!.y.min).toBeGreaterThan(0)
+    const sc = chartScales(px)!
+    expect(sc.yOf(195)).toBeLessThan(sc.yOf(188)) // higher price, smaller y
+  })
+})
+
+describe('gauge needle', () => {
+  const dial = (value: number, max = 100) =>
+    buildChart({ type: 'gauge', categories: [], series: [], gaugeValue: value, gaugeMin: 0, gaugeMax: max, width: 360, height: 240 })
+
+  /** The needle's four vertices, as distances from the hub. */
+  const spokes = (g: ReturnType<typeof dial>) => {
+    const { cx, cy } = g.gauge!
+    return g.gauge!.needle.path
+      .match(/-?[\d.]+,-?[\d.]+/g)!
+      .map((p) => p.split(',').map(Number) as [number, number])
+      .map(([x, y]) => Math.hypot(x - cx, y - cy))
+  }
+
+  it('keeps the counterweight inside the hub, so it cannot read as an arrowhead', () => {
+    // The tail used to stick out past the hub. At a horizontal angle that
+    // little solid triangle is visually denser than the 130px taper opposite
+    // it, so a near-full dial read as an arrow pointing at the MINIMUM.
+    const g = dial(99.82)
+    const hubR = g.gauge!.needle.hubR
+    const dists = spokes(g).sort((a, b) => a - b)
+    const [tail, s1, s2, tip] = [dists[0]!, dists[1]!, dists[2]!, dists[3]!]
+    expect(tail).toBeLessThanOrEqual(hubR)
+    // ...and the shoulders OUTSIDE it, or the hub hides the needle's base and
+    // all that is left is a hairline.
+    expect(s1).toBeGreaterThan(hubR)
+    expect(s2).toBeGreaterThan(hubR)
+    // The tip is the far end, by a wide margin.
+    expect(tip).toBeGreaterThan(s2 * 5)
+  })
+
+  it('points at the value: the tip is the vertex nearest the value angle', () => {
+    const { cx, cy, r } = dial(25).gauge!
+    const g = dial(25)
+    const pts = g.gauge!.needle.path
+      .match(/-?[\d.]+,-?[\d.]+/g)!
+      .map((p) => p.split(',').map(Number) as [number, number])
+    const far = pts.reduce((a, b) => (Math.hypot(b[0] - cx, b[1] - cy) > Math.hypot(a[0] - cx, a[1] - cy) ? b : a))
+    // 25 of 100 on a semicircle sweeping left -> right is up and to the left.
+    expect(far[0]).toBeLessThan(cx)
+    expect(far[1]).toBeLessThan(cy)
+    // And it stops inside the track rather than poking through it.
+    expect(Math.hypot(far[0] - cx, far[1] - cy)).toBeLessThan(r)
+  })
+
+  it('swings to the other side for a high value', () => {
+    const { cx } = dial(75).gauge!
+    const pts = dial(75).gauge!.needle.path
+      .match(/-?[\d.]+,-?[\d.]+/g)!
+      .map((p) => p.split(',').map(Number) as [number, number])
+    const far = pts.reduce((a, b) => (Math.abs(b[0] - cx) > Math.abs(a[0] - cx) ? b : a))
+    expect(far[0]).toBeGreaterThan(cx)
+  })
+})