@svgrid/grid 3.0.2 → 3.0.4

package/src/chart-validate.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import { CHART_TYPES, KNOWN_SERIES_KEYS, KNOWN_SPEC_KEYS, nearestKey, validateChartSpec } from './chart-validate'
+import { sampleChartSpec, sampleChartThumb } from './chart-samples'
+import { PER_CATEGORY_SERIES_KEYS } from './chart-decimate'
+import type { ChartSpec } from './chart-types'
+
+const base = (): ChartSpec => ({
+  type: 'bar',
+  categories: ['a', 'b', 'c'],
+  series: [{ label: 's', values: [1, 2, 3] }],
+})
+const codes = (spec: unknown) => validateChartSpec(spec).map((d) => d.code)
+
+describe('validateChartSpec', () => {
+  it('passes every sample spec of every type, full size and thumbnail', () => {
+    for (const type of CHART_TYPES) {
+      expect(validateChartSpec(sampleChartSpec(type)), type).toEqual([])
+      expect(validateChartSpec(sampleChartThumb(type)), `${type} thumb`).toEqual([])
+    }
+    expect(validateChartSpec(base())).toEqual([])
+  })
+
+  it('names an unknown top-level key with the nearest known one', () => {
+    const d = validateChartSpec({ ...base(), serie: [] } as unknown)
+    expect(d).toHaveLength(1)
+    expect(d[0]).toMatchObject({ code: 'chart/unknown-key', path: 'serie', severity: 'warning' })
+    expect(d[0]!.message).toContain('"series"')
+    expect(validateChartSpec({ ...base(), zzzz: 1 } as unknown)[0]!.message).toContain('is ignored')
+    expect(nearestKey('valeus', KNOWN_SERIES_KEYS)).toBe('values')
+    expect(nearestKey('completely-different', KNOWN_SPEC_KEYS)).toBeNull()
+  })
+
+  it('rejects an unknown chart type and suggests the closest', () => {
+    const d = validateChartSpec({ ...base(), type: 'lines' })
+    expect(d[0]).toMatchObject({ code: 'chart/unknown-type', path: 'type', severity: 'error' })
+    expect(d[0]!.message).toContain('"line"')
+    expect(codes({ categories: [], series: [] })).toContain('chart/unknown-type')
+    expect(codes(null)).toEqual(['chart/not-an-object'])
+    expect(codes('bar')).toEqual(['chart/not-an-object'])
+  })
+
+  it('checks series length against the categories, and every parallel array', () => {
+    expect(codes({ ...base(), series: [{ label: 's', values: [1, 2] }] })).toEqual(['chart/series-length'])
+    for (const key of PER_CATEGORY_SERIES_KEYS) {
+      if (key === 'values') continue
+      const spec = { ...base(), series: [{ label: 's', values: [1, 2, 3], [key]: [null] }] }
+      expect(codes(spec), key).toContain('chart/series-length')
+    }
+    // Families that do not index values by category are left alone.
+    expect(codes({ type: 'scatter', categories: [], series: [{ label: 'p', values: [], points: [{ x: 1, y: 2 }] }] })).toEqual([])
+    expect(codes({ type: 'gauge', categories: [], series: [], gaugeValue: 3 })).toEqual([])
+  })
+
+  it('checks series keys, type, axis, stack, overlay and the point shapes', () => {
+    expect(validateChartSpec({ ...base(), series: [{ label: 's', valeus: [1, 2, 3], values: [1, 2, 3] }] })[0]).toMatchObject({ code: 'chart/unknown-series-key', path: 'series[0].valeus' })
+    expect(codes({ ...base(), series: [{ label: 's', values: [1, 2, 3], type: 'column' }] })).toEqual(['chart/series-type'])
+    expect(codes({ ...base(), series: [{ label: 's', values: [1, 2, 3], axis: 'top' }] })).toEqual(['chart/series-axis'])
+    expect(codes({ ...base(), type: 'line', series: [{ label: 's', values: [1, 2, 3], stack: 'x' }] })).toEqual(['chart/stack-kind'])
+    expect(codes({ ...base(), series: [{ label: 's', values: [1, 2, 3], stack: 'x' }] })).toEqual([])
+    expect(codes({ ...base(), series: [{ label: 's', values: [1, 2, 3], overlay: 'sma20' }] })).toEqual(['chart/overlay'])
+    for (const ok of ['linear', 'sma:20', 'ema:7', 'wma:5', 'bb:20:2', 'bb:20:2.5', 'vwap', 'poly:3', 'exp', 'log', 'power']) {
+      expect(codes({ ...base(), series: [{ label: 's', values: [1, 2, 3], overlay: ok }] }), ok).toEqual([])
+    }
+    expect(codes({ ...base(), type: 'candlestick', series: [{ label: 's', values: [1, 2, 3], ohlc: [{ o: 1, h: 2, l: 3, c: 2 }, null, { o: 1 }] }] })).toEqual(['chart/ohlc-range', 'chart/ohlc-shape'])
+    expect(codes({ ...base(), type: 'boxplot', series: [{ label: 's', values: [1, 2, 3], boxes: [{ min: 0, q1: 5, median: 2, q3: 6, max: 9 }, null, null] }] })).toEqual(['chart/box-order'])
+    expect(codes({ type: 'scatter', categories: [], series: [{ label: 'p', values: [], points: [{ x: 'a', y: 2 }] }] })).toEqual(['chart/point-shape'])
+  })
+
+  it('checks the axis config', () => {
+    expect(codes({ ...base(), yAxis: { min: 10, max: 5 } })).toEqual(['chart/axis-range'])
+    expect(codes({ ...base(), yAxis: { scale: 'log', min: 0 } })).toEqual(['chart/axis-log-min'])
+    expect(codes({ ...base(), xAxis: { type: 'category', scale: 'log' } })).toEqual(['chart/axis-log-x'])
+    expect(codes({ ...base(), xAxis: { type: 'number', scale: 'log' } })).toEqual([])
+    expect(codes({ ...base(), y2Axis: { tickCount: 0 } })).toEqual(['chart/axis-ticks'])
+    expect(codes({ ...base(), xAxis: { labelRotation: 'tilted' } })).toEqual(['chart/axis-rotation'])
+    expect(codes({ ...base(), yAxis: { scale: 'sqrt' } })).toEqual(['chart/axis-scale'])
+    expect(codes({ ...base(), yAxis: 'log' })).toEqual(['chart/axis-shape'])
+  })
+
+  it('checks the spec-level shapes: stacked100, innerRadius, groups, bins, waterfall flags, responsive rules', () => {
+    expect(codes({ ...base(), type: 'pie', stacked100: true })).toEqual(['chart/stacked100-kind'])
+    expect(codes({ ...base(), innerRadius: 1.5 })).toEqual(['chart/inner-radius'])
+    expect(codes({ ...base(), categoryGroups: [{ label: 'g', span: 2 }] })).toEqual(['chart/category-groups'])
+    expect(codes({ ...base(), type: 'histogram', binEdges: [0, 1] })).toEqual(['chart/bin-edges'])
+    expect(codes({ ...base(), type: 'waterfall', waterfallTotals: [true] })).toEqual(['chart/waterfall-totals'])
+    expect(codes({ ...base(), responsive: [{ spec: { title: 'x' } }] })).toEqual(['chart/responsive-size'])
+    expect(codes({ ...base(), responsive: [{ maxWidth: 400, spec: { width: 10 } }] })).toEqual(['chart/responsive-size-key'])
+    expect(codes({ ...base(), responsive: ['narrow'] })).toEqual(['chart/responsive-shape'])
+  })
+
+  it('warns about x anchors that name no category, and not on a time or number axis', () => {
+    expect(codes({ ...base(), referenceLines: [{ axis: 'x', value: 'd' }] })).toEqual(['chart/unknown-category'])
+    expect(codes({ ...base(), annotations: [{ at: { category: 'zz' }, label: 'n' }] })).toEqual(['chart/unknown-category'])
+    expect(codes({ ...base(), drawings: [{ id: 'd1', kind: 'trend', points: [{ x: 'a', y: 1 }, { x: 'q', y: 2 }] }] })).toEqual(['chart/unknown-category'])
+    expect(codes({ ...base(), categories: ['1', '2', '3'], xType: 'number', referenceLines: [{ axis: 'x', value: '2.5' }] })).toEqual([])
+    // The drawing tools write a timestamp for every pointer position on a time axis.
+    expect(codes({ ...base(), categories: ['2026-01-01', '2026-02-01', '2026-03-01'], xType: 'time', drawings: [{ id: 'd1', kind: 'trend', points: [{ x: '2026-01-12T10:00:00.000Z', y: 1 }, { x: '2026-02-20T08:30:00.000Z', y: 2 }] }] })).toEqual([])
+    expect(codes({ ...base(), annotations: [{ at: { category: 'b' }, label: 'n' }] })).toEqual([])
+  })
+})

package/src/chart-validate.ts

@@ -0,0 +1,247 @@
+/**
+ * Chart spec diagnostics. A `ChartSpec` is plain data, and plain data gets
+ * typos: a `serie` key, a `values` array one short of the categories, a log
+ * axis pinned at zero. The engine draws what it can and stays quiet, which
+ * is right for production and wrong for the developer who wonders why a bar
+ * is missing. `validateChartSpec` says what is off, with the path of the
+ * field and a severity: `error` for what will not draw as intended,
+ * `warning` for what is ignored or looks like a slip.
+ *
+ * Pure and dependency-free (types only), so the same rules run in `SvChart`
+ * in development, in the MCP server's code check and in a test. The key and
+ * type lists are exported for the JSON schema's drift guard.
+ */
+import type { ChartSeries, ChartSpec, ChartType } from './chart-types'
+
+/** One finding of {@link validateChartSpec}. */
+export type ChartDiagnostic = {
+  /** A stable rule id, `chart/<rule>`. */
+  code: string
+  /** The field's path in the spec, like `series[1].values` or `yAxis.min`. */
+  path: string
+  message: string
+  /** `error`: will not draw as intended. `warning`: ignored, or a likely slip. */
+  severity: 'error' | 'warning'
+}
+
+/** Every `ChartType` the engine draws. */
+export const CHART_TYPES: ReadonlyArray<ChartType> = [
+  'bar', 'line', 'area', 'pie', 'scatter', 'heatmap', 'waterfall', 'funnel', 'radar', 'calendar', 'gauge',
+  'treemap', 'sankey', 'candlestick', 'ohlc', 'boxplot', 'histogram', 'range-bar', 'range-area', 'lollipop',
+  'dumbbell', 'pareto', 'stream', 'sunburst', 'radial-bar', 'radial-column', 'nightingale', 'chord', 'bullet',
+]
+
+/** Every top-level key a `ChartSpec` may carry. */
+export const KNOWN_SPEC_KEYS: ReadonlyArray<keyof ChartSpec> = [
+  'type', 'categories', 'series', 'width', 'height', 'palette', 'categoryColors', 'valueFormat', 'locale',
+  'currency', 'categoryGroups', 'stacked', 'stacked100', 'orientation', 'innerRadius', 'referenceLines',
+  'xType', 'yAxisTitle', 'y2AxisTitle', 'xAxisTitle', 'yScale', 'y2Scale', 'xAxis', 'yAxis', 'y2Axis',
+  'title', 'subtitle', 'caption', 'referenceBands', 'nullAs', 'decimate', 'dataLabels', 'annotations',
+  'seriesLabels', 'responsive', 'style', 'drawings', 'lastPriceLine', 'patternFallback', 'calendarValues',
+  'calendarStart', 'calendarEnd', 'gaugeValue', 'gaugeMin', 'gaugeMax', 'gaugeTarget', 'gaugeRanges',
+  'gaugeUnit', 'treemap', 'sankeyNodes', 'sankeyLinks', 'waterfallTotals', 'waterfallColors', 'candleColors',
+  'candleStyle', 'funnelShape', 'stackOffset', 'binEdges', 'tree', 'bulletRanges', 'colorScale',
+]
+
+/** Every key a `ChartSeries` may carry. */
+export const KNOWN_SERIES_KEYS: ReadonlyArray<keyof ChartSeries> = [
+  'label', 'values', 'color', 'type', 'ohlc', 'volumes', 'boxes', 'errors', 'axis', 'points', 'rowIds',
+  'overlay', 'overlayColor', 'pattern', 'smooth', 'upperValues', 'lowerValues', 'marker', 'markers', 'colors',
+  'stack', 'strokeWidth', 'dash', 'opacity', 'visible', 'gradient', 'step', 'connectNulls', 'nullAs',
+  'lowValues', 'targets',
+]
+
+const SERIES_TYPES = new Set(['bar', 'line', 'area', 'scatter', 'candlestick', 'ohlc', 'boxplot', 'range-bar', 'range-area', 'lollipop', 'dumbbell'])
+/** The series arrays that must run parallel to `categories`. */
+const PER_CATEGORY = ['values', 'rowIds', 'upperValues', 'lowerValues', 'ohlc', 'boxes', 'errors', 'markers', 'colors', 'lowValues', 'targets', 'volumes'] as const
+/** Families whose `series[].values` are not indexed by `categories`. */
+const FREE_LENGTH_TYPES = new Set<string>(['scatter', 'gauge', 'treemap', 'sankey', 'calendar', 'sunburst', 'chord', 'histogram'])
+const OVERLAY_RE = /^(linear|exp|log|power|vwap|sma:\d+|ema:\d+|wma:\d+|bb:\d+:\d+(?:\.\d+)?|poly:\d+)$/
+
+/** Levenshtein distance, for a "did you mean" on a misspelt key. */
+function distance(a: string, b: string): number {
+  const dp: number[] = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 1; i <= a.length; i += 1) {
+    let prev = dp[0]!
+    dp[0] = i
+    for (let j = 1; j <= b.length; j += 1) {
+      const tmp = dp[j]!
+      dp[j] = Math.min(dp[j]! + 1, dp[j - 1]! + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+      prev = tmp
+    }
+  }
+  return dp[b.length]!
+}
+
+/** The known key closest to `key`, when it is close enough to be a typo. */
+export function nearestKey(key: string, known: ReadonlyArray<string>): string | null {
+  let best: string | null = null
+  let bestD = Infinity
+  for (const k of known) {
+    const d = distance(key.toLowerCase(), k.toLowerCase())
+    if (d < bestD) { bestD = d; best = k }
+  }
+  return best !== null && bestD <= Math.max(1, Math.floor(key.length / 3)) ? best : null
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+const isNum = (v: unknown): v is number => typeof v === 'number'
+
+const warnedSpecs = new WeakSet<object>()
+
+/**
+ * Log every finding of a spec once per spec object, the way `SvChart` does in
+ * development, and return them. A spec already reported (by any chart) is
+ * skipped, so a spec shared by ten charts warns once.
+ */
+export function warnChartSpec(spec: unknown, log: (line: string) => void = (line) => console.warn(line)): ChartDiagnostic[] {
+  if (typeof spec !== 'object' || spec === null || warnedSpecs.has(spec)) return []
+  warnedSpecs.add(spec)
+  const out = validateChartSpec(spec)
+  for (const d of out) log(`[SvChart] ${d.path ? d.path + ': ' : ''}${d.message}`)
+  return out
+}
+
+/**
+ * Check a spec and return every finding, an empty array for a clean one. Never
+ * throws: a spec that is not even an object comes back as one error.
+ */
+export function validateChartSpec(spec: unknown): ChartDiagnostic[] {
+  const out: ChartDiagnostic[] = []
+  const err = (code: string, path: string, message: string) => out.push({ code: `chart/${code}`, path, message, severity: 'error' })
+  const warn = (code: string, path: string, message: string) => out.push({ code: `chart/${code}`, path, message, severity: 'warning' })
+  if (!isObj(spec)) {
+    err('not-an-object', '', 'a ChartSpec is an object with type, categories and series')
+    return out
+  }
+  const s = spec as Record<string, unknown>
+
+  // ---- Keys and type -------------------------------------------------------
+  for (const k of Object.keys(s)) {
+    if ((KNOWN_SPEC_KEYS as ReadonlyArray<string>).includes(k)) continue
+    const near = nearestKey(k, KNOWN_SPEC_KEYS)
+    warn('unknown-key', k, near ? `unknown field "${k}"; did you mean "${near}"?` : `unknown field "${k}" is ignored`)
+  }
+  const type = s.type
+  if (typeof type !== 'string' || !(CHART_TYPES as ReadonlyArray<string>).includes(type)) {
+    const near = typeof type === 'string' ? nearestKey(type, CHART_TYPES) : null
+    err('unknown-type', 'type', near ? `unknown chart type "${String(type)}"; did you mean "${near}"?` : `unknown chart type "${String(type)}"`)
+  }
+  const categories = Array.isArray(s.categories) ? (s.categories as unknown[]) : null
+  if (!categories) err('categories', 'categories', 'categories must be an array of labels')
+  const n = categories?.length ?? 0
+  const series = Array.isArray(s.series) ? (s.series as unknown[]) : null
+  if (!series) err('series', 'series', 'series must be an array')
+
+  // ---- Series ----------------------------------------------------------------
+  const fixedLength = typeof type === 'string' && !FREE_LENGTH_TYPES.has(type)
+  series?.forEach((sr, i) => {
+    const p = `series[${i}]`
+    if (!isObj(sr)) { err('series-shape', p, 'a series is an object with label and values'); return }
+    for (const k of Object.keys(sr)) {
+      if ((KNOWN_SERIES_KEYS as ReadonlyArray<string>).includes(k)) continue
+      const near = nearestKey(k, KNOWN_SERIES_KEYS)
+      warn('unknown-series-key', `${p}.${k}`, near ? `unknown series field "${k}"; did you mean "${near}"?` : `unknown series field "${k}" is ignored`)
+    }
+    if (typeof sr.label !== 'string') warn('series-label', `${p}.label`, 'a series wants a string label; the legend and tooltip name it')
+    if (!Array.isArray(sr.values)) { err('series-values', `${p}.values`, 'values must be an array of numbers'); return }
+    const values = sr.values as unknown[]
+    if (fixedLength && categories && values.length !== n && !(sr.points && values.length === 0)) {
+      err('series-length', `${p}.values`, `${values.length} values for ${n} categories; they run in parallel`)
+    }
+    for (const key of PER_CATEGORY) {
+      if (key === 'values') continue
+      const arr = sr[key]
+      if (arr === undefined) continue
+      if (!Array.isArray(arr)) { err('series-array', `${p}.${key}`, `${key} must be an array parallel to values`); continue }
+      if (fixedLength && arr.length !== values.length) err('series-length', `${p}.${key}`, `${key} has ${arr.length} entries for ${values.length} values; they run in parallel`)
+    }
+    if (sr.type !== undefined && (typeof sr.type !== 'string' || !SERIES_TYPES.has(sr.type))) err('series-type', `${p}.type`, `unknown series type "${String(sr.type)}"`)
+    if (sr.axis !== undefined && sr.axis !== 'left' && sr.axis !== 'right') err('series-axis', `${p}.axis`, `axis is 'left' or 'right', not "${String(sr.axis)}"`)
+    if (sr.stack !== undefined) {
+      const kind = (sr.type as string | undefined) ?? type
+      if (kind !== 'bar' && kind !== 'area') warn('stack-kind', `${p}.stack`, 'stack groups apply to bar and area series; ignored here')
+    }
+    if (sr.overlay !== undefined && (typeof sr.overlay !== 'string' || !OVERLAY_RE.test(sr.overlay))) err('overlay', `${p}.overlay`, `unknown overlay "${String(sr.overlay)}"; expected linear, poly:N, exp, log, power, sma:N, ema:N, wma:N, bb:N:K or vwap`)
+    if (Array.isArray(sr.ohlc)) {
+      ;(sr.ohlc as unknown[]).forEach((b, j) => {
+        if (b === null || b === undefined) return
+        if (!isObj(b) || !isNum(b.o) || !isNum(b.h) || !isNum(b.l) || !isNum(b.c)) err('ohlc-shape', `${p}.ohlc[${j}]`, 'an OHLC bar is { o, h, l, c } or null')
+        else if (b.l > b.h) err('ohlc-range', `${p}.ohlc[${j}]`, `low ${b.l} is above high ${b.h}`)
+      })
+    }
+    if (Array.isArray(sr.boxes)) {
+      ;(sr.boxes as unknown[]).forEach((b, j) => {
+        if (b === null || b === undefined) return
+        if (!isObj(b) || !isNum(b.min) || !isNum(b.q1) || !isNum(b.median) || !isNum(b.q3) || !isNum(b.max)) err('box-shape', `${p}.boxes[${j}]`, 'a box is { min, q1, median, q3, max } or null')
+        else if (b.q1 > b.median || b.median > b.q3) err('box-order', `${p}.boxes[${j}]`, 'a box wants q1 <= median <= q3')
+      })
+    }
+    if (Array.isArray(sr.points)) {
+      ;(sr.points as unknown[]).forEach((pt, j) => {
+        if (!isObj(pt) || !isNum(pt.x) || !isNum(pt.y)) err('point-shape', `${p}.points[${j}]`, 'a scatter point is { x, y, r?, label? }')
+      })
+    }
+  })
+
+  // ---- Axes ----------------------------------------------------------------
+  for (const key of ['xAxis', 'yAxis', 'y2Axis'] as const) {
+    const ax = s[key]
+    if (ax === undefined) continue
+    if (!isObj(ax)) { err('axis-shape', key, `${key} must be an object`); continue }
+    if (isNum(ax.min) && isNum(ax.max) && ax.min >= ax.max) err('axis-range', `${key}.min`, `min ${ax.min} is not below max ${ax.max}`)
+    if (ax.scale === 'log' && isNum(ax.min) && ax.min <= 0) err('axis-log-min', `${key}.min`, 'a log axis cannot start at or below zero')
+    if (ax.scale === 'log' && key === 'xAxis' && ax.type !== undefined && ax.type !== 'number') warn('axis-log-x', `${key}.scale`, "a log x axis needs type: 'number'")
+    if (ax.tickCount !== undefined && (!isNum(ax.tickCount) || ax.tickCount <= 0)) err('axis-ticks', `${key}.tickCount`, 'tickCount must be a positive number')
+    if (ax.labelRotation !== undefined && ax.labelRotation !== 'auto' && !isNum(ax.labelRotation)) err('axis-rotation', `${key}.labelRotation`, "labelRotation is a number of degrees or 'auto'")
+    if (ax.scale !== undefined && ax.scale !== 'linear' && ax.scale !== 'log') err('axis-scale', `${key}.scale`, `scale is 'linear' or 'log', not "${String(ax.scale)}"`)
+  }
+
+  // ---- Spec-level shapes -----------------------------------------------------
+  if (s.stacked100 && typeof type === 'string' && type !== 'bar' && type !== 'area') warn('stacked100-kind', 'stacked100', 'stacked100 applies to bar and area charts; ignored here')
+  if (s.innerRadius !== undefined && (!isNum(s.innerRadius) || s.innerRadius < 0 || s.innerRadius > 1)) err('inner-radius', 'innerRadius', 'innerRadius is a fraction 0..1 of the pie radius')
+  if (Array.isArray(s.categoryGroups) && categories) {
+    const span = (s.categoryGroups as Array<{ span?: unknown }>).reduce((a, g) => a + (isObj(g) && isNum(g.span) ? g.span : 0), 0)
+    if (span !== n) err('category-groups', 'categoryGroups', `the group spans add up to ${span}, not the ${n} categories`)
+  }
+  if (Array.isArray(s.binEdges) && categories && (s.binEdges as unknown[]).length !== n + 1) err('bin-edges', 'binEdges', `binEdges wants ${n + 1} edges for ${n} bins`)
+  if (Array.isArray(s.waterfallTotals) && categories && (s.waterfallTotals as unknown[]).length !== n) err('waterfall-totals', 'waterfallTotals', `waterfallTotals has ${(s.waterfallTotals as unknown[]).length} flags for ${n} categories`)
+  if (Array.isArray(s.responsive)) {
+    ;(s.responsive as unknown[]).forEach((r, i) => {
+      const p = `responsive[${i}]`
+      if (!isObj(r)) { err('responsive-shape', p, 'a rule is { maxWidth?, minWidth?, maxHeight?, spec?, legend? }'); return }
+      if (!isNum(r.maxWidth) && !isNum(r.minWidth) && !isNum(r.maxHeight)) warn('responsive-size', p, 'a rule with no maxWidth, minWidth or maxHeight always applies')
+      if (isObj(r.spec)) {
+        for (const k of ['width', 'height', 'responsive']) if (k in r.spec) warn('responsive-size-key', `${p}.spec.${k}`, `${k} in a responsive rule is ignored; a rule cannot change the size`)
+      }
+    })
+  }
+  // Anchors on the category axis that name no category.
+  if (categories && typeof type === 'string' && !FREE_LENGTH_TYPES.has(type)) {
+    const known = new Set(categories.map(String))
+    const isTimeOrNumber = (s.xType ?? (isObj(s.xAxis) ? s.xAxis.type : undefined)) as string | undefined
+    const anchored = isTimeOrNumber === 'time' || isTimeOrNumber === 'number'
+    const check = (list: unknown, path: string, valueOf: (item: Record<string, unknown>) => unknown) => {
+      if (!Array.isArray(list) || anchored) return
+      list.forEach((item, i) => {
+        if (!isObj(item)) return
+        const v = valueOf(item)
+        if (typeof v === 'string' && !known.has(v)) warn('unknown-category', `${path}[${i}]`, `"${v}" is not one of the categories, so it has no place on the axis`)
+      })
+    }
+    check(s.annotations, 'annotations', (a) => (isObj(a.at) ? a.at.category : undefined))
+    check(Array.isArray(s.referenceLines) ? (s.referenceLines as unknown[]).filter((r) => isObj(r) && r.axis === 'x') : [], 'referenceLines', (r) => r.value)
+    // On a time or number axis a drawing's x is a timestamp or a number the
+    // axis places itself; the tools write one for every pointer position, so
+    // matching those against the category list warned on every drawing.
+    if (Array.isArray(s.drawings) && !anchored) {
+      ;(s.drawings as unknown[]).forEach((d, i) => {
+        if (!isObj(d) || !Array.isArray(d.points)) return
+        ;(d.points as unknown[]).forEach((pt, j) => {
+          if (isObj(pt) && typeof pt.x === 'string' && !known.has(pt.x)) warn('unknown-category', `drawings[${i}].points[${j}].x`, `"${pt.x}" is not one of the categories`)
+        })
+      })
+    }
+  }
+  return out
+}

package/src/chart-zoom.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest'
+import { nearestIndexByTime, panWindow, pinchWindow, presetWindow, wheelWindow } from './chart-zoom'
+import { drillTree, pathTo } from './chart-hierarchy'
+import { interpolateGeometry } from './chart-motion'
+import { buildChart, type ChartSpec } from './chart'
+
+describe('wheelWindow', () => {
+  it('zooms in around the anchor and keeps its relative position', () => {
+    const n = 100
+    const w = wheelWindow(null, n, 50, 0.5)!
+    expect(w.i1 - w.i0 + 1).toBe(50)
+    // The anchor was at the middle of the full axis, so it stays at the middle.
+    expect((50 - w.i0) / (w.i1 - w.i0)).toBeCloseTo(0.5, 1)
+    const edge = wheelWindow(null, n, 0, 0.5)!
+    expect(edge.i0).toBe(0)
+    expect(edge.i1).toBe(49)
+  })
+  it('zooms out until the whole axis, which is null', () => {
+    const w = wheelWindow({ i0: 40, i1: 59 }, 100, 50, 2)!
+    expect(w.i1 - w.i0 + 1).toBe(40)
+    expect(wheelWindow({ i0: 10, i1: 89 }, 100, 50, 2)).toBeNull()
+  })
+  it('never goes below two categories', () => {
+    expect(wheelWindow({ i0: 10, i1: 11 }, 100, 10, 0.5)).toEqual({ i0: 10, i1: 11 })
+  })
+})
+
+describe('panWindow', () => {
+  it('slides the window and clamps at both ends', () => {
+    expect(panWindow({ i0: 10, i1: 19 }, 100, 5)).toEqual({ i0: 15, i1: 24 })
+    expect(panWindow({ i0: 10, i1: 19 }, 100, -50)).toEqual({ i0: 0, i1: 9 })
+    expect(panWindow({ i0: 85, i1: 94 }, 100, 50)).toEqual({ i0: 90, i1: 99 })
+    expect(panWindow(null, 100, 5)).toBeNull()
+  })
+})
+
+describe('pinchWindow', () => {
+  it('spreading the fingers zooms in', () => {
+    const w = pinchWindow(null, 100, 50, 2)!
+    expect(w.i1 - w.i0 + 1).toBe(50)
+  })
+})
+
+describe('presetWindow', () => {
+  const days = Array.from({ length: 730 }, (_, i) => new Date(Date.UTC(2025, 0, 1) + i * 86_400_000).toISOString().slice(0, 10))
+  it('picks the last month, three months and year to date up to the latest category', () => {
+    const m = presetWindow(days, '1M')!
+    expect(m.i1).toBe(729)
+    expect(m.i1 - m.i0).toBeGreaterThanOrEqual(28)
+    expect(m.i1 - m.i0).toBeLessThanOrEqual(31)
+    const q = presetWindow(days, '3M')!
+    expect(q.i1 - q.i0).toBeGreaterThanOrEqual(89)
+    const ytd = presetWindow(days, 'YTD')!
+    expect(days[ytd.i0]).toBe('2026-01-01')
+    expect(ytd.i1).toBe(729)
+    expect(presetWindow(days, '1W')!.i1 - presetWindow(days, '1W')!.i0).toBe(7)
+  })
+  it('All and unparseable categories give the whole axis', () => {
+    expect(presetWindow(days, 'All')).toBeNull()
+    expect(presetWindow(['a', 'b', 'c'], '1M')).toBeNull()
+  })
+  it('takes explicit from / to and day counts', () => {
+    const w = presetWindow(days, { label: 'Q1', from: '2026-01-01', to: '2026-03-31' })!
+    expect(days[w.i0]).toBe('2026-01-01')
+    expect(days[w.i1]).toBe('2026-03-31')
+    const d = presetWindow(days, { label: '10d', days: 10 })!
+    expect(d.i1 - d.i0).toBe(10)
+  })
+  it('honours an explicit now', () => {
+    const w = presetWindow(days, '1M', Date.UTC(2025, 5, 30))!
+    expect(days[w.i1]).toBe('2025-06-30')
+  })
+})
+
+describe('nearestIndexByTime', () => {
+  it('finds the closest date and skips non-dates', () => {
+    expect(nearestIndexByTime(['2026-01-01', 'x', '2026-01-10', '2026-01-20'], Date.parse('2026-01-12'))).toBe(2)
+    expect(nearestIndexByTime(['a', 'b'], 0)).toBe(-1)
+  })
+})
+
+describe('drillTree / pathTo', () => {
+  const tree = { name: 'root', children: [{ name: 'A', children: [{ name: 'A1', value: 1 }] }, { name: 'B', value: 2 }] }
+  it('descends by names and reports the path to a node', () => {
+    expect(drillTree(tree, [])).toBe(tree)
+    expect(drillTree(tree, ['A'])!.name).toBe('A')
+    expect(drillTree(tree, ['A', 'A1'])!.value).toBe(1)
+    expect(drillTree(tree, ['Z'])).toBeNull()
+    expect(pathTo(tree, 'A1')).toEqual(['A', 'A1'])
+    expect(pathTo(tree, 'nope')).toBeNull()
+  })
+})
+
+describe('interpolateGeometry', () => {
+  const spec = (values: number[], categories = ['a', 'b', 'c']): ChartSpec => ({
+    type: 'bar', categories, series: [{ label: 's', values }, { label: 'l', values: values.map((v) => v / 2), type: 'line' }], width: 400, height: 200,
+  })
+  it('is the source at 0 and the target at 1, and halfway between in between', () => {
+    const a = buildChart(spec([10, 20, 30]))
+    const b = buildChart(spec([30, 20, 10]))
+    expect(interpolateGeometry(a, b, 0)).toBe(a)
+    expect(interpolateGeometry(a, b, 1)).toBe(b)
+    const mid = interpolateGeometry(a, b, 0.5)
+    expect(mid.bars[0]!.h).toBeCloseTo((a.bars[0]!.h + b.bars[0]!.h) / 2, 1)
+    expect(mid.lines[0]!.points[0]!.y).toBeCloseTo((a.lines[0]!.points[0]!.y + b.lines[0]!.points[0]!.y) / 2, 1)
+    expect(mid.lines[0]!.path).not.toBe(a.lines[0]!.path)
+  })
+  it('grows a new bar from the baseline and shrinks a removed one', () => {
+    const a = buildChart(spec([10, 20], ['a', 'b']))
+    const b = buildChart(spec([10, 20, 30]))
+    const mid = interpolateGeometry(a, b, 0.5)
+    const c = mid.bars.find((x) => x.label === 'c')!
+    expect(c.h).toBeCloseTo(b.bars[2]!.h / 2, 1)
+    const back = interpolateGeometry(b, a, 0.5)
+    const gone = back.bars.find((x) => x.label === 'c')!
+    expect(gone.h).toBeCloseTo(b.bars[2]!.h / 2, 1)
+    expect(interpolateGeometry(b, a, 1).bars.find((x) => x.label === 'c')).toBeUndefined()
+  })
+  it('tweens pie slices and arcs by angle', () => {
+    const pie = (v: number[]): ChartSpec => ({ type: 'pie', categories: ['x', 'y'], series: [{ label: 's', values: v }], width: 300, height: 200 })
+    const a = buildChart(pie([1, 1]))
+    const b = buildChart(pie([3, 1]))
+    const mid = interpolateGeometry(a, b, 0.5)
+    expect(mid.slices[0]!.arc!.a1).toBeCloseTo((a.slices[0]!.arc!.a1 + b.slices[0]!.arc!.a1) / 2, 6)
+    expect(mid.slices[0]!.path).not.toBe(a.slices[0]!.path)
+    const rb = (v: number[]): ChartSpec => ({ type: 'radial-bar', categories: ['x', 'y'], series: [{ label: 's', values: v }], width: 300, height: 200 })
+    const ra = buildChart(rb([50, 100]))
+    const rbz = buildChart(rb([100, 100]))
+    const rm = interpolateGeometry(ra, rbz, 0.5)
+    expect(rm.arcs[0]!.a1).toBeCloseTo((ra.arcs[0]!.a1 + rbz.arcs[0]!.a1) / 2, 6)
+  })
+  it('snaps when the chart type changes', () => {
+    const a = buildChart(spec([1, 2, 3]))
+    const b = buildChart({ ...spec([1, 2, 3]), type: 'pie' })
+    expect(interpolateGeometry(a, b, 0.5)).toBe(b)
+  })
+})

package/src/chart-zoom.ts

@@ -0,0 +1,124 @@
+/**
+ * Zoom-window arithmetic for the chart: the category window a wheel, a pinch,
+ * a pan or a range preset produces. Pure functions over indices and dates, so
+ * the renderer's gestures are thin and the maths is unit-tested.
+ */
+import type { ChartZoomWindow } from './chart-types'
+
+/** Clamp a window to [0, n-1] with at least one category in it. */
+function clampWindow(i0: number, i1: number, n: number): ChartZoomWindow | null {
+  if (n <= 0) return null
+  let a = Math.max(0, Math.min(n - 1, Math.round(i0)))
+  let b = Math.max(0, Math.min(n - 1, Math.round(i1)))
+  if (b < a) [a, b] = [b, a]
+  if (a === 0 && b === n - 1) return null
+  return { i0: a, i1: b }
+}
+
+/**
+ * Zoom the window in or out around an anchor category, keeping the anchor at
+ * the same relative position. `factor < 1` zooms in, `> 1` out; a null window
+ * means the whole axis. Never narrower than 2 categories.
+ */
+export function wheelWindow(win: ChartZoomWindow | null, n: number, anchor: number, factor: number): ChartZoomWindow | null {
+  if (n <= 2) return null
+  const i0 = win ? win.i0 : 0
+  const i1 = win ? win.i1 : n - 1
+  const span = i1 - i0 + 1
+  const next = Math.max(2, Math.min(n, Math.round(span * factor)))
+  if (next === span) return win
+  // Where the anchor sits inside the window, 0..1, so it stays put.
+  const rel = span > 1 ? (Math.max(i0, Math.min(i1, anchor)) - i0) / (span - 1) : 0.5
+  let a = Math.round(anchor - rel * (next - 1))
+  a = Math.max(0, Math.min(n - next, a))
+  return clampWindow(a, a + next - 1, n)
+}
+
+/** Slide the window by `delta` categories, clamped to the axis. */
+export function panWindow(win: ChartZoomWindow | null, n: number, delta: number): ChartZoomWindow | null {
+  if (!win || !delta) return win
+  const span = win.i1 - win.i0
+  let a = win.i0 + Math.round(delta)
+  a = Math.max(0, Math.min(n - 1 - span, a))
+  return clampWindow(a, a + span, n)
+}
+
+/**
+ * Resize the window by a pinch: `scale > 1` spreads the fingers (zoom in),
+ * around the category under the pinch midpoint.
+ */
+export function pinchWindow(win: ChartZoomWindow | null, n: number, midpoint: number, scale: number): ChartZoomWindow | null {
+  if (!Number.isFinite(scale) || scale <= 0) return win
+  return wheelWindow(win, n, midpoint, 1 / scale)
+}
+
+/** The range presets a time axis offers. */
+export type ChartRangePreset = '1W' | '1M' | '3M' | '6M' | 'YTD' | '1Y' | 'All' | { label: string; days?: number; from?: string; to?: string }
+
+/**
+ * The window a preset selects on a time / ordinal-time axis whose categories
+ * parse as dates: the last N days up to the latest category, the year to
+ * date, or an explicit from / to. `'All'` (and a preset nothing matches)
+ * returns null, the whole axis. `now` defaults to the last category, which is
+ * what "1M" means on a chart that stops last quarter.
+ */
+export function presetWindow(categories: ReadonlyArray<string>, preset: ChartRangePreset, now?: number): ChartZoomWindow | null {
+  const n = categories.length
+  if (!n) return null
+  const times = categories.map((c) => Date.parse(c))
+  const last = [...times].reverse().find(Number.isFinite)
+  if (last == null) return null
+  const end = now ?? last
+  const DAY = 86_400_000
+  let from: number
+  let to = end
+  if (typeof preset === 'object') {
+    if (preset.from) from = Date.parse(preset.from)
+    else if (preset.days) from = end - preset.days * DAY
+    else return null
+    if (preset.to) to = Date.parse(preset.to)
+  } else {
+    switch (preset) {
+      case '1W': from = end - 7 * DAY; break
+      case '1M': from = shiftMonths(end, -1); break
+      case '3M': from = shiftMonths(end, -3); break
+      case '6M': from = shiftMonths(end, -6); break
+      case '1Y': from = shiftMonths(end, -12); break
+      case 'YTD': { const d = new Date(end); from = Date.UTC(d.getUTCFullYear(), 0, 1); break }
+      default: return null
+    }
+  }
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return null
+  let i0 = -1
+  let i1 = -1
+  for (let i = 0; i < n; i += 1) {
+    const t = times[i]!
+    if (!Number.isFinite(t)) continue
+    if (t >= from && i0 < 0) i0 = i
+    if (t <= to) i1 = i
+  }
+  if (i0 < 0 || i1 < 0 || i1 < i0) return null
+  return clampWindow(i0, i1, n)
+}
+
+function shiftMonths(t: number, months: number): number {
+  const d = new Date(t)
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + months, d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes())
+}
+
+/**
+ * The category whose date is nearest to `t`, for syncing a hover between two
+ * charts whose categories differ. Categories that do not parse are skipped;
+ * returns -1 when none do.
+ */
+export function nearestIndexByTime(categories: ReadonlyArray<string>, t: number): number {
+  let best = -1
+  let bestD = Infinity
+  for (let i = 0; i < categories.length; i += 1) {
+    const ct = Date.parse(categories[i]!)
+    if (!Number.isFinite(ct)) continue
+    const d = Math.abs(ct - t)
+    if (d < bestD) { bestD = d; best = i }
+  }
+  return best
+}