@svgrid/grid 3.0.2 → 3.0.4

package/src/chart-summary.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import { chartSummary } from './chart-summary'
+import { CHART_TYPES } from './chart-validate'
+import { sampleChartSpec } from './chart-samples'
+import { pearson } from './chart-stats'
+import type { ChartSpec } from './chart-types'
+
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']
+
+describe('chartSummary', () => {
+  it('reads a rising line with its ends, change, peak and trough', () => {
+    const s = chartSummary({ type: 'line', categories: months, series: [{ label: 'Revenue', values: [100, 180, 90, 140, 160, 150] }] })
+    expect(s).toBe('Revenue rises 50% from 100 at Jan to 150 at Jun, peaking at 180 at Feb, lowest at 90 at Mar.')
+  })
+
+  it('reads a falling series, a flat one, and caps the series it lists', () => {
+    const spec: ChartSpec = {
+      type: 'bar',
+      categories: months,
+      series: [
+        { label: 'Cost', values: [200, 190, 170, 160, 150, 120] },
+        { label: 'Flat', values: [50, 50.2, 49.9, 50.1, 50, 50] },
+        { label: 'A', values: [1, 2, 3, 4, 5, 6] },
+        { label: 'B', values: [1, 2, 3, 4, 5, 6] },
+        { label: 'C', values: [1, 2, 3, 4, 5, 6] },
+      ],
+    }
+    const s = chartSummary(spec)
+    expect(s).toContain('Cost falls 40% from 200 at Jan to 120 at Jun.')
+    expect(s).toContain('Flat holds at about 50 from Jan to Jun.')
+    expect(s).toContain('And 1 more series.')
+    expect(chartSummary(spec, { maxSeries: 2 })).toContain('And 3 more series.')
+    // Hidden series are left out; the formatter is honoured.
+    const hidden = chartSummary({ ...spec, series: [{ ...spec.series[0]!, visible: false }, spec.series[1]!] }, { formatValue: (v) => `$${v}` })
+    expect(hidden).toBe('Flat holds at about $50 from Jan to Jun.')
+  })
+
+  it('shares the top three slices of a pie and a tree map', () => {
+    expect(chartSummary({ type: 'pie', categories: ['A', 'B', 'C', 'D', 'E'], series: [{ label: 'v', values: [50, 25, 15, 6, 4] }] })).toBe(
+      '5 slices totalling 100: A 50%, B 25%, C 15%, 2 more share the rest.',
+    )
+    expect(chartSummary({ type: 'treemap', categories: [], series: [], treemap: { name: 'r', children: [{ name: 'X', value: 3 }, { name: 'Y', children: [{ name: 'y1', value: 1 }] }] } })).toBe(
+      '2 nodes totalling 4: X 75%, Y 25%.',
+    )
+  })
+
+  it('reports the correlation of a scatter, the last close of candles, and the gauge against its target', () => {
+    const pts = Array.from({ length: 20 }, (_, i) => ({ x: i, y: 2 * i + (i % 2) }))
+    expect(chartSummary({ type: 'scatter', categories: [], series: [{ label: 'p', values: [], points: pts }] })).toMatch(/^20 points in 1 series with a strong positive correlation \(r (?:0\.9\d|1\.00)\)/)
+    const anti = pts.map((p) => ({ x: p.x, y: -p.y }))
+    expect(chartSummary({ type: 'scatter', categories: [], series: [{ label: 'p', values: [], points: anti }] })).toContain('strong negative')
+    expect(pearson([1, 2, 3], [1, 1, 1])).toBe(0)
+    const candles = chartSummary({
+      type: 'candlestick',
+      categories: ['d1', 'd2', 'd3'],
+      series: [{ label: 'ACME', values: [10, 11, 12], ohlc: [{ o: 10, h: 12, l: 9, c: 10 }, { o: 10, h: 13, l: 10, c: 11 }, { o: 11, h: 14, l: 11, c: 12.1 }] }],
+    })
+    expect(candles).toBe('ACME: last close 12.1, up 10% on the session, ranging 9 to 14 over 3 bars.')
+    expect(chartSummary({ type: 'gauge', categories: [], series: [], gaugeValue: 72, gaugeMin: 0, gaugeMax: 100, gaugeTarget: 80, gaugeUnit: '%' })).toBe(
+      '72 %, 72% of the way from 0 to 100, below the target of 80.',
+    )
+  })
+
+  it('reads a heat map, a calendar, a funnel, a box plot and a sankey', () => {
+    expect(chartSummary({ type: 'heatmap', categories: ['c1', 'c2'], series: [{ label: 'r1', values: [1, 9] }, { label: 'r2', values: [4, 2] }] })).toBe(
+      '2 rows by 2 columns; the highest cell is 9 at r1 and c2.',
+    )
+    expect(chartSummary({ type: 'calendar', categories: [], series: [], calendarValues: [{ date: '2026-01-01', value: 2 }, { date: '2026-01-02', value: 7 }] })).toBe(
+      '2 days totalling 9; the busiest is 2026-01-02 at 7.',
+    )
+    expect(chartSummary({ type: 'funnel', categories: ['Visit', 'Sign up', 'Pay'], series: [{ label: 'n', values: [1000, 300, 150] }] })).toBe(
+      '15% of 1k at Visit reach Pay; the biggest drop is into Sign up (70% lost).',
+    )
+    expect(chartSummary({ type: 'boxplot', categories: ['a'], series: [{ label: 'X', values: [5], boxes: [{ min: 1, q1: 4, median: 5, q3: 6, max: 9 }] }, { label: 'Y', values: [5], boxes: [{ min: 0, q1: 2, median: 5, q3: 9, max: 12 }] }] })).toBe(
+      '2 distributions over 1 categories; Y has the widest interquartile range at 7.',
+    )
+    expect(chartSummary({ type: 'sankey', categories: [], series: [], sankeyNodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }], sankeyLinks: [{ source: 'a', target: 'b', value: 3 }, { source: 'a', target: 'c', value: 5 }] })).toBe(
+      '2 flows totalling 8; the largest is a to c at 5.',
+    )
+  })
+
+  it('never throws on an empty spec of any type, and describes every sample spec', () => {
+    for (const type of CHART_TYPES) {
+      expect(chartSummary({ type, categories: [], series: [] }), type).toBe('No data.')
+      const s = chartSummary(sampleChartSpec(type))
+      expect(typeof s, type).toBe('string')
+      expect(s.length, type).toBeGreaterThan(8)
+    }
+  })
+})

package/src/chart-summary.ts

@@ -0,0 +1,197 @@
+/**
+ * A chart in a sentence or two. `chartSummary` reads a spec the way a
+ * colleague would read the picture: which way each series goes and by how
+ * much, where it peaks, what the biggest slices are, whether two measures
+ * move together, how the last session closed. `SvChart` puts the result in
+ * the SVG's `aria-description`, the context menu copies it, and the AI
+ * "explain this chart" prompt is grounded on it, so the words a screen
+ * reader hears and the words a model reasons from are the same words.
+ *
+ * Pure and dependency-light (two small leaves: the number formatter and the
+ * trend primitives, kept apart from the engine's modules so the chunk a
+ * bundler shares between this lazy module and the base stays tiny), so it
+ * runs on the server and in a test, and the renderer loads it lazily.
+ */
+import type { ChartSpec, ChartSeries } from './chart-types'
+import { formatChartValue } from './chart-format'
+import { linearTrend, pearson } from './chart-trend'
+
+/** What {@link chartSummary} takes. */
+export type ChartSummaryOptions = {
+  /** How numbers are written. Default: the spec's `valueFormat` / `locale` / `currency`. */
+  formatValue?: (v: number) => string
+  /** How many series a cartesian chart describes before it says "and N more". Default 4. */
+  maxSeries?: number
+}
+
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)
+
+/** First and last finite value of a series with their indices, or null. */
+function ends(values: ReadonlyArray<number>): { i0: number; v0: number; i1: number; v1: number } | null {
+  let i0 = -1
+  let i1 = -1
+  for (let i = 0; i < values.length; i += 1) if (finite(values[i])) { if (i0 < 0) i0 = i; i1 = i }
+  if (i0 < 0) return null
+  return { i0, v0: values[i0]!, i1, v1: values[i1]! }
+}
+
+function extremes(values: ReadonlyArray<number>): { max: number; iMax: number; min: number; iMin: number } | null {
+  let max = -Infinity, min = Infinity, iMax = -1, iMin = -1
+  values.forEach((v, i) => {
+    if (!finite(v)) return
+    if (v > max) { max = v; iMax = i }
+    if (v < min) { min = v; iMin = i }
+  })
+  return iMax < 0 ? null : { max, iMax, min, iMin }
+}
+
+const pct = (from: number, to: number): string => {
+  if (from === 0) return ''
+  const p = Math.abs(((to - from) / Math.abs(from)) * 100)
+  return `${p >= 10 ? Math.round(p) : Math.round(p * 10) / 10}%`
+}
+
+function describeSeries(s: ChartSeries, categories: ReadonlyArray<string>, fmt: (v: number) => string): string {
+  const values = s.ohlc ? s.ohlc.map((b) => (b ? b.c : Number.NaN)) : s.values
+  const e = ends(values)
+  if (!e) return `${s.label} has no values.`
+  const at = (i: number) => categories[i] ?? `#${i + 1}`
+  if (e.i0 === e.i1) return `${s.label} is ${fmt(e.v0)} at ${at(e.i0)}.`
+  const slope = linearTrend(values)
+  const rise = slope[slope.length - 1]! - slope[0]!
+  const span = Math.abs(e.v1 - e.v0)
+  const scale = Math.max(Math.abs(e.v0), Math.abs(e.v1), 1e-9)
+  const flat = span / scale < 0.02 && Math.abs(rise) / scale < 0.05
+  const dir = flat ? 'holds at about' : e.v1 > e.v0 ? 'rises' : 'falls'
+  const change = pct(e.v0, e.v1)
+  let out = flat
+    ? `${s.label} holds at about ${fmt(e.v1)} from ${at(e.i0)} to ${at(e.i1)}`
+    : `${s.label} ${dir}${change ? ` ${change}` : ''} from ${fmt(e.v0)} at ${at(e.i0)} to ${fmt(e.v1)} at ${at(e.i1)}`
+  const x = extremes(values)
+  if (x && !flat) {
+    const peakInside = x.iMax !== e.i0 && x.iMax !== e.i1
+    const troughInside = x.iMin !== e.i0 && x.iMin !== e.i1
+    if (peakInside) out += `, peaking at ${fmt(x.max)} at ${at(x.iMax)}`
+    if (troughInside) out += `, lowest at ${fmt(x.min)} at ${at(x.iMin)}`
+  }
+  return out + '.'
+}
+
+function shares(labels: ReadonlyArray<string>, values: ReadonlyArray<number>, fmt: (v: number) => string, noun: string): string {
+  const total = values.reduce((a, v) => a + (finite(v) ? Math.abs(v) : 0), 0)
+  if (!total) return `No ${noun} has a value.`
+  const ranked = labels.map((l, i) => ({ l, v: finite(values[i]) ? Math.abs(values[i]!) : 0 })).sort((a, b) => b.v - a.v)
+  const top = ranked.slice(0, 3).map((r) => `${r.l} ${Math.round((r.v / total) * 100)}%`)
+  const rest = ranked.length > 3 ? `, ${ranked.length - 3} more share the rest` : ''
+  return `${labels.length} ${noun}s totalling ${fmt(total)}: ${top.join(', ')}${rest}.`
+}
+
+/**
+ * Describe a spec in plain words. Never throws: an empty spec of any type
+ * comes back as "No data." so a live region always has something to say.
+ */
+export function chartSummary(spec: ChartSpec, opts: ChartSummaryOptions = {}): string {
+  const fmt = opts.formatValue ?? ((v: number) => formatChartValue(v, spec.valueFormat, spec))
+  const max = opts.maxSeries ?? 4
+  const cats = spec.categories ?? []
+  const series = (spec.series ?? []).filter((s) => s.visible !== false)
+  const type = spec.type
+  try {
+    if (type === 'pie' || type === 'radial-bar' || type === 'nightingale') {
+      const s = series[0]
+      if (!s || !s.values.some(finite)) return 'No data.'
+      return shares(cats, s.values, fmt, 'slice')
+    }
+    if (type === 'treemap' || type === 'sunburst') {
+      const root = spec.treemap ?? spec.tree
+      const kids = root?.children ?? []
+      if (!kids.length) return 'No data.'
+      const total = (n: { value?: number; children?: Array<{ value?: number; children?: unknown[] }> }): number =>
+        n.value ?? (n.children ?? []).reduce((a, c) => a + total(c as never), 0)
+      return shares(kids.map((k) => k.name), kids.map((k) => total(k)), fmt, 'node')
+    }
+    if (type === 'gauge') {
+      if (!finite(spec.gaugeValue)) return 'No data.'
+      const lo = spec.gaugeMin ?? 0
+      const hi = spec.gaugeMax ?? 100
+      const share = hi > lo ? Math.round(((spec.gaugeValue - lo) / (hi - lo)) * 100) : 0
+      const target = finite(spec.gaugeTarget) ? `, ${spec.gaugeValue >= spec.gaugeTarget ? 'above' : 'below'} the target of ${fmt(spec.gaugeTarget)}` : ''
+      return `${fmt(spec.gaugeValue)}${spec.gaugeUnit ? ' ' + spec.gaugeUnit : ''}, ${share}% of the way from ${fmt(lo)} to ${fmt(hi)}${target}.`
+    }
+    if (type === 'scatter') {
+      const pts = series.flatMap((s) => s.points ?? []).filter((p) => finite(p.x) && finite(p.y))
+      if (!pts.length) return 'No data.'
+      const r = pearson(pts.map((p) => p.x), pts.map((p) => p.y))
+      const strength = Math.abs(r) >= 0.7 ? 'strong' : Math.abs(r) >= 0.4 ? 'moderate' : Math.abs(r) >= 0.2 ? 'weak' : 'no'
+      const sign = r > 0 ? 'positive' : 'negative'
+      const rel = strength === 'no' ? 'no clear correlation' : `a ${strength} ${sign} correlation (r ${r.toFixed(2)})`
+      return `${pts.length} points in ${series.length} series with ${rel} between x and y.`
+    }
+    if (type === 'candlestick' || type === 'ohlc') {
+      const s = series.find((x) => x.ohlc) ?? series[0]
+      const bars = (s?.ohlc ?? []).filter((b): b is NonNullable<typeof b> => !!b)
+      if (!s || !bars.length) return 'No data.'
+      const last = bars[bars.length - 1]!
+      const prev = bars.length > 1 ? bars[bars.length - 2]! : null
+      const hi = Math.max(...bars.map((b) => b.h))
+      const lo = Math.min(...bars.map((b) => b.l))
+      const move = prev ? `, ${last.c >= prev.c ? 'up' : 'down'} ${pct(prev.c, last.c)} on the session` : ''
+      return `${s.label}: last close ${fmt(last.c)}${move}, ranging ${fmt(lo)} to ${fmt(hi)} over ${bars.length} bars.`
+    }
+    if (type === 'heatmap') {
+      let best: { v: number; row: string; col: string } | null = null
+      for (const s of series) s.values.forEach((v, i) => { if (finite(v) && (!best || v > best.v)) best = { v, row: s.label, col: cats[i] ?? String(i) } })
+      if (!best) return 'No data.'
+      const b = best as { v: number; row: string; col: string }
+      return `${series.length} rows by ${cats.length} columns; the highest cell is ${fmt(b.v)} at ${b.row} and ${b.col}.`
+    }
+    if (type === 'calendar') {
+      const days = (spec.calendarValues ?? []).filter((d) => finite(d.value))
+      if (!days.length) return 'No data.'
+      const top = days.reduce((a, d) => (d.value > a.value ? d : a), days[0]!)
+      const total = days.reduce((a, d) => a + d.value, 0)
+      return `${days.length} days totalling ${fmt(total)}; the busiest is ${top.date} at ${fmt(top.value)}.`
+    }
+    if (type === 'funnel') {
+      const s = series[0]
+      const vals = (s?.values ?? []).filter(finite)
+      if (!s || vals.length < 2) return s && vals.length === 1 ? `${cats[0] ?? s.label}: ${fmt(vals[0]!)}.` : 'No data.'
+      const first = vals[0]!
+      const last = vals[vals.length - 1]!
+      const conv = first ? Math.round((last / first) * 100) : 0
+      let worstDrop = 0
+      let worstAt = ''
+      for (let i = 1; i < vals.length; i += 1) {
+        const drop = vals[i - 1]! ? 1 - vals[i]! / vals[i - 1]! : 0
+        if (drop > worstDrop) { worstDrop = drop; worstAt = cats[i] ?? `step ${i + 1}` }
+      }
+      return `${conv}% of ${fmt(first)} at ${cats[0] ?? 'the top'} reach ${cats[vals.length - 1] ?? 'the bottom'}${worstAt ? `; the biggest drop is into ${worstAt} (${Math.round(worstDrop * 100)}% lost)` : ''}.`
+    }
+    if (type === 'boxplot') {
+      let widest: { label: string; spread: number } | null = null
+      for (const s of series) for (const b of s.boxes ?? []) {
+        if (!b) continue
+        const spread = b.q3 - b.q1
+        if (!widest || spread > widest.spread) widest = { label: s.label, spread }
+      }
+      if (!widest) return 'No data.'
+      return `${series.length} distributions over ${cats.length} categories; ${widest.label} has the widest interquartile range at ${fmt(widest.spread)}.`
+    }
+    if (type === 'sankey' || type === 'chord') {
+      const links = spec.sankeyLinks ?? []
+      if (!links.length) return 'No data.'
+      const total = links.reduce((a, l) => a + (finite(l.value) ? l.value : 0), 0)
+      const top = [...links].sort((a, b) => b.value - a.value)[0]!
+      return `${links.length} flows totalling ${fmt(total)}; the largest is ${top.source} to ${top.target} at ${fmt(top.value)}.`
+    }
+    // Cartesian families: one sentence per series, up to the cap.
+    const usable = series.filter((s) => s.values.some(finite) || s.ohlc)
+    if (!usable.length) return 'No data.'
+    const shown = usable.slice(0, max)
+    const parts = shown.map((s) => describeSeries(s, cats, fmt))
+    const more = usable.length > shown.length ? ` And ${usable.length - shown.length} more series.` : ''
+    return `${parts.join(' ')}${more}`
+  } catch {
+    return 'No data.'
+  }
+}

package/src/chart-sync.svelte.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared hover and zoom between charts in the same `syncGroup`.
+ *
+ * A registry of groups whose entries are `$state`, so every chart that reads
+ * its group's entry re-renders when another chart in the group writes to it. Each write
+ * carries the writer's token so a chart can ignore its own echoes.
+ */
+import type { ChartZoomWindow } from './chart-types'
+
+/** What one chart publishes for the others: the hovered category (its label,
+ *  index and, when the category parses as a date, its time) and the window. */
+export type ChartSyncState = {
+  hover: { label: string; index: number; time: number | null; from: symbol } | null
+  zoom: { window: ChartZoomWindow | null; count: number; from: symbol; labels: [string, string] | null } | null
+}
+
+// A plain map of reactive entries: looking a group up (which a chart does
+// inside a $derived) must not itself be a state mutation, so the map is not
+// reactive and each entry is.
+const groups = new Map<string, ChartSyncState>()
+
+/** The live entry for a group, created on first use. */
+export function syncGroupState(name: string): ChartSyncState {
+  const existing = groups.get(name)
+  if (existing) return existing
+  const fresh = $state<ChartSyncState>({ hover: null, zoom: null })
+  groups.set(name, fresh)
+  return fresh
+}
+
+/** Publish a hover (or clear it with null). */
+export function publishSyncHover(name: string, hover: ChartSyncState['hover']): void {
+  syncGroupState(name).hover = hover
+}
+
+/** Publish a zoom window (null = the whole axis) with the axis length it
+ *  was made against and the category labels at its two ends, so a chart with
+ *  a different axis can map it by date. */
+export function publishSyncZoom(name: string, window: ChartZoomWindow | null, count: number, from: symbol, labels: [string, string] | null = null): void {
+  syncGroupState(name).zoom = { window, count, from, labels }
+}

package/src/chart-table.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { chartSpecToTable } from './chart-table'
+import type { ChartSpec } from './chart-types'
+
+describe('chartSpecToTable', () => {
+  it('lays a category chart out as one row per category and a column per series, in the chart format', () => {
+    const t = chartSpecToTable({
+      type: 'bar',
+      categories: ['Q1', 'Q2', 'Q1', 'Q2'],
+      categoryGroups: [{ label: '2025', span: 2 }, { label: '2026', span: 2 }],
+      series: [{ label: 'Americas', values: [1, 2, 3, Number.NaN] }, { label: 'EMEA', values: [4, 5, 6, 7] }],
+      valueFormat: 'currency',
+      currency: 'EUR',
+    })
+    expect(t.columns.map((c) => c.header)).toEqual(['Group', 'Category', 'Americas', 'EMEA'])
+    expect(t.columns[2]).toMatchObject({ cellDataType: 'number', format: { type: 'currency', currency: 'EUR' } })
+    expect(t.rows).toEqual([
+      { group: '2025', category: 'Q1', s0: 1, s1: 4 },
+      { group: '2025', category: 'Q2', s0: 2, s1: 5 },
+      { group: '2026', category: 'Q1', s0: 3, s1: 6 },
+      { group: '2026', category: 'Q2', s0: null, s1: 7 },
+    ])
+  })
+
+  it('reads a date axis as a date column named after the axis, and a right-axis series in that axis format', () => {
+    const t = chartSpecToTable({
+      type: 'bar',
+      xType: 'time',
+      categories: ['2026-01-01', '2026-02-01'],
+      series: [{ label: 'Revenue', values: [2.1, 2.3] }, { label: 'Margin', values: [0.29, 0.31], type: 'line', axis: 'right' }],
+      valueFormat: 'currency',
+      y2Axis: { format: 'percent' },
+      xAxisTitle: 'Month',
+    })
+    expect(t.columns[0]).toEqual({ field: 'category', header: 'Month', cellDataType: 'date' })
+    expect(t.columns[1]!.format).toEqual({ type: 'currency', currency: 'USD' })
+    expect(t.columns[2]!.format).toEqual({ type: 'percent' })
+    expect(chartSpecToTable({ type: 'gauge', categories: [], series: [], gaugeValue: 1, gaugeUnit: 'ms' }).columns[1]!.header).toBe('Value (ms)')
+  })
+
+  it('expands the numbers a series carries: ranges, targets, error bars, candles, boxes, bins', () => {
+    const range = chartSpecToTable({ type: 'range-bar', categories: ['a'], series: [{ label: 'Band', values: [9], lowValues: [4] }] })
+    expect(range.columns.map((c) => c.header)).toEqual(['Category', 'Band Low', 'Band High'])
+    expect(range.rows[0]).toEqual({ category: 'a', s0lo: 4, s0hi: 9 })
+    const bullet = chartSpecToTable({ type: 'bullet', categories: ['a'], series: [{ label: 'Actual', values: [82], targets: [90] }] })
+    expect(bullet.rows[0]).toEqual({ category: 'a', s0: 82, s0t: 90 })
+    const err = chartSpecToTable({ type: 'bar', categories: ['a', 'b'], series: [{ label: 'Mean', values: [10, 20], errors: [2, { lo: 15, hi: 30 }] }] })
+    expect(err.rows).toEqual([{ category: 'a', s0: 10, s0lo: 8, s0hi: 12 }, { category: 'b', s0: 20, s0lo: 15, s0hi: 30 }])
+    const candles = chartSpecToTable({ type: 'candlestick', categories: ['d1'], series: [{ label: 'ACME', values: [3], ohlc: [{ o: 1, h: 4, l: 0.5, c: 3 }], volumes: [100] }] })
+    expect(candles.columns.map((c) => c.header)).toEqual(['Category', 'ACME Open', 'ACME High', 'ACME Low', 'ACME Close', 'ACME Volume'])
+    expect(candles.rows[0]).toEqual({ category: 'd1', s0o: 1, s0h: 4, s0l: 0.5, s0c: 3, s0v: 100 })
+    const boxes = chartSpecToTable({ type: 'boxplot', categories: ['a'], series: [{ label: 'ms', values: [5], boxes: [{ min: 1, q1: 3, median: 5, q3: 7, max: 9, outliers: [20, 30] }] }] })
+    expect(boxes.rows[0]).toEqual({ category: 'a', s0min: 1, s0q1: 3, s0med: 5, s0q3: 7, s0max: 9, s0out: '20 30' })
+    const bins = chartSpecToTable({ type: 'histogram', categories: ['5', '15'], series: [{ label: 'n', values: [2, 3] }], binEdges: [0, 10, 20] })
+    expect(bins.columns.map((c) => c.header)).toEqual(['From', 'To', 'n'])
+    expect(bins.rows).toEqual([{ from: 0, to: 10, s0: 2 }, { from: 10, to: 20, s0: 3 }])
+  })
+
+  it('tabulates the shapes the category grid cannot: points, links, leaves, days, a gauge', () => {
+    const scatter = chartSpecToTable({ type: 'scatter', categories: [], series: [{ label: 'S', values: [], points: [{ x: 1, y: 2, r: 3, label: 'p' }] }] })
+    expect(scatter.columns.map((c) => c.header)).toEqual(['Series', 'X', 'Y', 'Size', 'Label'])
+    expect(scatter.rows).toEqual([{ series: 'S', x: 1, y: 2, size: 3, label: 'p' }])
+    const flow = chartSpecToTable({ type: 'sankey', categories: [], series: [], sankeyNodes: [{ id: 'a', label: 'Wind' }, { id: 'b' }], sankeyLinks: [{ source: 'a', target: 'b', value: 27 }] })
+    expect(flow.rows).toEqual([{ source: 'Wind', target: 'b', value: 27 }])
+    const tree: ChartSpec = { type: 'sunburst', categories: [], series: [], tree: { name: 'All', children: [{ name: 'Blink', children: [{ name: 'Chrome', value: 6 }] }, { name: 'Gecko', value: 3 }] } }
+    const leaves = chartSpecToTable(tree)
+    expect(leaves.columns.map((c) => c.header)).toEqual(['Level 1', 'Level 2', 'Value'])
+    expect(leaves.rows).toEqual([{ level1: 'Blink', level2: 'Chrome', value: 6 }, { level1: 'Gecko', value: 3 }])
+    const days = chartSpecToTable({ type: 'calendar', categories: [], series: [], calendarValues: [{ date: '2026-01-05', value: 4 }] })
+    expect(days.columns[0]).toMatchObject({ header: 'Date', cellDataType: 'date' })
+    expect(days.rows).toEqual([{ date: '2026-01-05', value: 4 }])
+    const gauge = chartSpecToTable({ type: 'gauge', categories: [], series: [], title: 'Uptime', gaugeValue: 99.2, gaugeMin: 99, gaugeMax: 100, gaugeTarget: 99.9 })
+    expect(gauge.rows).toEqual([{ metric: 'Uptime', value: 99.2, min: 99, max: 100, target: 99.9 }])
+    expect(chartSpecToTable({ type: 'bar', categories: [], series: [] })).toEqual({ columns: [], rows: [] })
+  })
+})

package/src/chart-table.ts

@@ -0,0 +1,178 @@
+/**
+ * Chart spec -> grid table.
+ *
+ * The rows and columns a `ChartSpec` amounts to, in the shape `SvGrid` takes:
+ * one row per category with a column per series for the category types, one
+ * row per point for a scatter, per link for a sankey or chord, per leaf for
+ * a tree map or sunburst, per day for a calendar, and one row for a gauge.
+ * Number columns carry `cellDataType: 'number'` and the chart's value format,
+ * so a grid of the chart reads its numbers the way the chart does.
+ *
+ * This is the grid-shaped sibling of `chartSpecToCsv`: the CSV keeps its
+ * header contract byte for byte, this one adds types and formats and covers
+ * the shapes the CSV leaves out. A "Chart | Grid" switch on a chart is this
+ * function behind an `SvGrid`.
+ */
+import type { CellFormatConfig } from './core'
+import type { ChartSpec, TreeNode } from './chart-types'
+
+/** One column of a chart's table: what `SvGrid` needs to draw it. */
+export type ChartTableColumn = {
+  field: string
+  header: string
+  cellDataType?: 'number' | 'text' | 'date'
+  format?: CellFormatConfig
+  width?: number
+}
+
+/** A chart's data as a table: grid columns and plain row objects. */
+export type ChartTable = {
+  columns: ChartTableColumn[]
+  rows: Array<Record<string, unknown>>
+}
+
+/** A finite number as itself, anything else as an empty cell. */
+const num = (v: unknown): number | null => (typeof v === 'number' && Number.isFinite(v) ? v : null)
+
+/** The cell format a chart value format maps to, for the number columns. */
+function formatOf(format: ChartSpec['valueFormat'], spec: ChartSpec): CellFormatConfig | undefined {
+  const locales: string | string[] | undefined = typeof spec.locale === 'string' ? spec.locale : spec.locale ? [...spec.locale] : undefined
+  if (format === 'currency') return { type: 'currency', currency: spec.currency ?? 'USD', ...(locales ? { locales } : {}) }
+  if (format === 'percent') return { type: 'percent', ...(locales ? { locales } : {}) }
+  if (format === 'number' || format === 'compact') return { type: 'number', ...(locales ? { locales } : {}) }
+  return undefined
+}
+
+/**
+ * The rows and columns a chart spec amounts to. Never throws: a spec with
+ * nothing to tabulate comes back with no rows and no columns.
+ */
+export function chartSpecToTable(spec: ChartSpec): ChartTable {
+  const fmt = formatOf(spec.valueFormat, spec)
+  // A series on the right axis reads in that axis's format: a margin of 0.29
+  // beside a revenue in dollars is "29%", not "$0.29".
+  const fmt2 = formatOf(spec.y2Axis?.format, spec)
+  const numCol = (field: string, header: string, right = false): ChartTableColumn => {
+    const f = right ? fmt2 : fmt
+    return { field, header, cellDataType: 'number', ...(f ? { format: f } : {}) }
+  }
+  const textCol = (field: string, header: string): ChartTableColumn => ({ field, header })
+  const series = spec.series ?? []
+
+  // Scatter and bubble: one row per point.
+  if (series.some((s) => s.points?.length)) {
+    const rows: Array<Record<string, unknown>> = []
+    for (const s of series) for (const p of s.points ?? []) rows.push({ series: s.label, x: num(p.x), y: num(p.y), size: num(p.r), label: p.label ?? '' })
+    return { columns: [textCol('series', 'Series'), numCol('x', 'X'), numCol('y', 'Y'), numCol('size', 'Size'), textCol('label', 'Label')], rows }
+  }
+  // Sankey and chord: one row per link.
+  if (spec.sankeyLinks?.length) {
+    const names = new Map((spec.sankeyNodes ?? []).map((n) => [n.id, n.label ?? n.id]))
+    const rows = spec.sankeyLinks.map((l) => ({ source: names.get(l.source) ?? l.source, target: names.get(l.target) ?? l.target, value: num(l.value) }))
+    return { columns: [textCol('source', 'Source'), textCol('target', 'Target'), numCol('value', 'Value')], rows }
+  }
+  // Tree map and sunburst: one row per leaf, a column per level.
+  const tree = spec.tree ?? spec.treemap
+  if (tree && (spec.type === 'treemap' || spec.type === 'sunburst' || !spec.categories?.length)) {
+    const rows: Array<Record<string, unknown>> = []
+    let depth = 0
+    const walk = (n: TreeNode, path: string[]) => {
+      if (n.children?.length) {
+        for (const c of n.children) walk(c, [...path, c.name])
+        return
+      }
+      depth = Math.max(depth, path.length)
+      const row: Record<string, unknown> = { value: num(n.value) }
+      path.forEach((seg, i) => (row[`level${i + 1}`] = seg))
+      rows.push(row)
+    }
+    walk(tree, [])
+    const columns: ChartTableColumn[] = []
+    for (let i = 1; i <= depth; i += 1) columns.push(textCol(`level${i}`, depth === 1 ? 'Name' : `Level ${i}`))
+    columns.push(numCol('value', 'Value'))
+    return { columns, rows }
+  }
+  // Calendar: one row per day.
+  if (spec.calendarValues?.length) {
+    return {
+      columns: [{ field: 'date', header: 'Date', cellDataType: 'date' }, numCol('value', 'Value')],
+      rows: spec.calendarValues.map((d) => ({ date: d.date, value: num(d.value) })),
+    }
+  }
+  // Gauge: the one reading and its scale.
+  if (spec.type === 'gauge') {
+    return {
+      columns: [textCol('metric', 'Metric'), numCol('value', spec.gaugeUnit ? `Value (${spec.gaugeUnit})` : 'Value'), numCol('min', 'Min'), numCol('max', 'Max'), numCol('target', 'Target')],
+      rows: [{ metric: spec.title ?? spec.series[0]?.label ?? 'Value', value: num(spec.gaugeValue), min: num(spec.gaugeMin ?? 0), max: num(spec.gaugeMax ?? 100), target: num(spec.gaugeTarget) }],
+    }
+  }
+
+  // Everything else reads categories x series: one row per category, one
+  // column per number a series carries.
+  const cats = spec.categories ?? []
+  if (!cats.length || !series.length) return { columns: [], rows: [] }
+  const columns: ChartTableColumn[] = []
+  const groups = spec.categoryGroups
+  if (groups?.length) columns.push(textCol('group', 'Group'))
+  const edges = spec.binEdges
+  const xType = spec.xAxis?.type ?? spec.xType
+  const dated = xType === 'time' || xType === 'ordinal-time'
+  const catHeader = spec.xAxis?.title ?? spec.xAxisTitle ?? (dated ? 'Date' : 'Category')
+  if (edges && edges.length === cats.length + 1) columns.push(numCol('from', 'From'), numCol('to', 'To'))
+  else columns.push(dated ? { field: 'category', header: catHeader, cellDataType: 'date' } : textCol('category', catHeader))
+  const fields: Array<{ field: string; pick: (i: number) => unknown }> = []
+  series.forEach((s, si) => {
+    const key = (suffix: string) => `s${si}${suffix}`
+    const add = (suffix: string, header: string, pick: (i: number) => unknown) => {
+      columns.push(numCol(key(suffix), header, s.axis === 'right'))
+      fields.push({ field: key(suffix), pick })
+    }
+    if (s.ohlc) {
+      add('o', `${s.label} Open`, (i) => num(s.ohlc![i]?.o))
+      add('h', `${s.label} High`, (i) => num(s.ohlc![i]?.h))
+      add('l', `${s.label} Low`, (i) => num(s.ohlc![i]?.l))
+      add('c', `${s.label} Close`, (i) => num(s.ohlc![i]?.c))
+      if (s.volumes) add('v', `${s.label} Volume`, (i) => num(s.volumes![i]))
+    } else if (s.boxes) {
+      add('min', `${s.label} Min`, (i) => num(s.boxes![i]?.min))
+      add('q1', `${s.label} Q1`, (i) => num(s.boxes![i]?.q1))
+      add('med', `${s.label} Median`, (i) => num(s.boxes![i]?.median))
+      add('q3', `${s.label} Q3`, (i) => num(s.boxes![i]?.q3))
+      add('max', `${s.label} Max`, (i) => num(s.boxes![i]?.max))
+      columns.push(textCol(key('out'), `${s.label} Outliers`))
+      fields.push({ field: key('out'), pick: (i) => s.boxes![i]?.outliers?.join(' ') ?? '' })
+    } else if (s.errors) {
+      add('', s.label, (i) => num(s.values[i]))
+      add('lo', `${s.label} Low`, (i) => {
+        const v = s.values[i], e = s.errors![i]
+        return e == null || !Number.isFinite(v) ? null : typeof e === 'number' ? (v as number) - Math.abs(e) : Math.min(e.lo, e.hi)
+      })
+      add('hi', `${s.label} High`, (i) => {
+        const v = s.values[i], e = s.errors![i]
+        return e == null || !Number.isFinite(v) ? null : typeof e === 'number' ? (v as number) + Math.abs(e) : Math.max(e.lo, e.hi)
+      })
+    } else if (s.lowValues) {
+      add('lo', `${s.label} Low`, (i) => num(s.lowValues![i]))
+      add('hi', `${s.label} High`, (i) => num(s.values[i]))
+    } else if (s.targets) {
+      add('', s.label, (i) => num(s.values[i]))
+      add('t', `${s.label} Target`, (i) => num(s.targets![i]))
+    } else {
+      add('', s.label, (i) => num(s.values[i]))
+    }
+  })
+  // A category's group, from the spans.
+  const groupOf: string[] = []
+  if (groups?.length) for (const g of groups) for (let k = 0; k < g.span; k += 1) groupOf.push(g.label)
+  const rows = cats.map((cat, i) => {
+    const row: Record<string, unknown> = {}
+    if (groups?.length) row.group = groupOf[i] ?? ''
+    if (edges && edges.length === cats.length + 1) {
+      row.from = num(edges[i])
+      row.to = num(edges[i + 1])
+    } else row.category = cat
+    for (const f of fields) row[f.field] = f.pick(i)
+    return row
+  })
+  return { columns, rows }
+}

package/src/chart-trend.ts

@@ -0,0 +1,47 @@
+/**
+ * The two trend primitives a chart is read with: the least-squares line
+ * through a series and Pearson's correlation of two samples.
+ *
+ * A leaf of its own, and deliberately small, for the same reason as
+ * chart-format.ts: the engine and the lazily loaded summary
+ * (chart-summary.ts) share these two functions, a bundler hoists what the
+ * base chunk and a lazy chunk share into a third chunk, and hoisting all of
+ * chart-stats.ts for two functions cost the base bundle gzip locality for no
+ * new code. chart-stats.ts re-exports both.
+ */
+
+/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
+ *  Returns the fitted value at each x index, or NaN where the source value
+ *  was non-finite. */
+export function linearTrend(values: number[]): number[] {
+  let n = 0, sumX = 0, sumY = 0, sumXX = 0, sumXY = 0
+  for (let i = 0; i < values.length; i += 1) {
+    const y = values[i]!
+    if (!Number.isFinite(y)) continue
+    n += 1; sumX += i; sumY += y; sumXX += i * i; sumXY += i * y
+  }
+  if (n < 2) return values.map(() => NaN)
+  const denom = n * sumXX - sumX * sumX
+  if (denom === 0) return values.map(() => sumY / n)
+  const slope = (n * sumXY - sumX * sumY) / denom
+  const intercept = (sumY - slope * sumX) / n
+  return values.map((_, i) => slope * i + intercept)
+}
+
+/** Pearson's correlation coefficient of two equal-length samples, skipping
+ *  pairs where either side is non-finite; 0 when fewer than two pairs remain
+ *  or either side has no variance. */
+export function pearson(xs: ReadonlyArray<number>, ys: ReadonlyArray<number>): number {
+  let n = 0, sx = 0, sy = 0
+  const len = Math.min(xs.length, ys.length)
+  for (let i = 0; i < len; i += 1) if (Number.isFinite(xs[i]) && Number.isFinite(ys[i])) { n += 1; sx += xs[i]!; sy += ys[i]! }
+  if (n < 2) return 0
+  const mx = sx / n, my = sy / n
+  let sxy = 0, sxx = 0, syy = 0
+  for (let i = 0; i < len; i += 1) {
+    if (!Number.isFinite(xs[i]) || !Number.isFinite(ys[i])) continue
+    const dx = xs[i]! - mx, dy = ys[i]! - my
+    sxy += dx * dy; sxx += dx * dx; syy += dy * dy
+  }
+  return sxx === 0 || syy === 0 ? 0 : sxy / Math.sqrt(sxx * syy)
+}