@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/components/chart/Chart.test.tsx

@@ -0,0 +1,187 @@
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { Chart, estimateTickWidth, valueAxisLayout, type ChartFigure } from './Chart'
+import { niceTicks } from './chartMath'
+import { toPlot } from './plot'
+
+const line: ChartFigure = {
+  form: 'trend',
+  heading: 'Cases by stage',
+  reading: 'Stages 3 and 4 add up to 37 of 94 cases.',
+  across: { field: 'x', caption: 'Year' },
+  up: { caption: 'Cases', unit: 'cases' },
+  layers: [{ field: 'Stage 3' }, { field: 'Stage 4', projected: true, tone: 'categorical-4' }],
+  records: [
+    { x: '2022', 'Stage 3': 4, 'Stage 4': 1 },
+    { x: '2023', 'Stage 3': 9, 'Stage 4': 6 },
+    { x: '2024', 'Stage 3': 14, 'Stage 4': 12 },
+    { x: '2025', 'Stage 3': 20, 'Stage 4': 17 },
+  ],
+}
+
+describe('Chart', () => {
+  it('names the figure by the title and draws one legend entry per series and one mark per datum', () => {
+    const { container } = render(<Chart figure={line} />)
+    const figure = screen.getByRole('figure', { name: 'Cases by stage' })
+    expect(within(figure).getAllByRole('listitem')).toHaveLength(2)
+    for (const name of ['Stage 3', 'Stage 4']) {
+      expect(container.querySelectorAll(`g[data-series="${name}"] .ty-chart__mark`)).toHaveLength(4)
+    }
+    expect(screen.getByText(line.reading!)).toBeInTheDocument()
+    expect(container.querySelector('.ty-chart__legend-item[data-dashed]')).not.toBeNull()
+  })
+
+  it('draws histogram bins without gaps', () => {
+    const { container } = render(
+      <Chart figure={{ ...line, form: 'bins', layers: [{ field: 'Stage 3' }] }} />,
+    )
+    const bins = [...container.querySelectorAll('rect.ty-chart__bar')]
+    expect(bins).toHaveLength(4)
+    for (let i = 1; i < bins.length; i++) {
+      const prev = bins[i - 1]!
+      const end = Number(prev.getAttribute('x')) + Number(prev.getAttribute('width'))
+      expect(Number(bins[i]!.getAttribute('x'))).toBeCloseTo(end, 6)
+    }
+  })
+
+  it('draws grouped bars with a gap between groups', () => {
+    const { container } = render(<Chart figure={{ ...line, form: 'columns' }} />)
+    const first = container.querySelectorAll('g[data-series="Stage 4"] rect')[0]!
+    const next = container.querySelectorAll('g[data-series="Stage 3"] rect')[1]!
+    expect(Number(next.getAttribute('x'))).toBeGreaterThan(Number(first.getAttribute('x')) + Number(first.getAttribute('width')))
+  })
+
+  it('announces the third category after two presses of Right', async () => {
+    render(<Chart figure={line} />)
+    const plot = screen.getByRole('group', { name: 'Cases by stage' })
+    await userEvent.tab()
+    await userEvent.tab()
+    await userEvent.tab()
+    plot.focus()
+    expect(plot).toHaveFocus()
+    await userEvent.keyboard('{ArrowRight}{ArrowRight}')
+    expect(screen.getByRole('status')).toHaveTextContent('2024, Stage 3: 14 cases')
+    await userEvent.keyboard('{ArrowDown}')
+    expect(screen.getByRole('status')).toHaveTextContent('2024, Stage 4: 12 cases')
+    await userEvent.keyboard('{End}')
+    expect(screen.getByRole('status')).toHaveTextContent('2025')
+    await userEvent.keyboard('{Escape}')
+    expect(screen.getByRole('status')).toHaveTextContent('')
+  })
+
+  it('shows a readout when a point is tapped', () => {
+    const { container } = render(<Chart figure={line} />)
+    const svg = container.querySelector('svg.ty-chart__svg')!
+    svg.getBoundingClientRect = () => ({ left: 0, top: 0, width: 640, height: 360, right: 640, bottom: 360, x: 0, y: 0, toJSON() {} })
+    fireEvent.pointerDown(svg, { clientX: 60, clientY: 200 })
+    expect(container.querySelector('.ty-chart__readout')).toHaveTextContent('2022')
+  })
+
+  it('switches to a table with one column per series and one row per datum', async () => {
+    render(<Chart figure={line} />)
+    await userEvent.click(screen.getByRole('radio', { name: 'Table' }))
+    const table = screen.getByRole('table')
+    expect(within(table).getAllByRole('columnheader')).toHaveLength(3)
+    expect(within(table).getAllByRole('row')).toHaveLength(5)
+  })
+
+  it('shows an empty message and no axes without data', () => {
+    const { container } = render(<Chart figure={{ ...line, records: [] }} />)
+    expect(screen.getByText('No data to plot')).toBeInTheDocument()
+    expect(container.querySelector('svg.ty-chart__svg')).toBeNull()
+  })
+
+  it('treats "n/a" as a missing value: a gap in the line, no mark', () => {
+    const figure: ChartFigure = { ...line, layers: [{ field: 'Stage 3' }], records: line.records.map((r, i) => (i === 1 ? { ...r, 'Stage 3': 'n/a' } : r)) }
+    const { container } = render(<Chart figure={figure} />)
+    expect(container.querySelectorAll('.ty-chart__mark')).toHaveLength(3)
+    expect(container.querySelectorAll('.ty-chart__line')).toHaveLength(2)
+  })
+
+  it('places an annotation only at an existing category', () => {
+    const { container } = render(
+      <Chart figure={{ ...line, notes: [{ at: '2024', text: 'Rule v2' }, { at: '1999', text: 'Nowhere' }] }} />,
+    )
+    const marks = container.querySelectorAll('.ty-chart__annotation')
+    expect(marks).toHaveLength(1)
+    expect(marks[0]).toHaveAttribute('data-category', '2024')
+    expect(marks[0]).toHaveTextContent('Rule v2')
+  })
+
+  it('is one image when not interactive', () => {
+    render(<Chart figure={line} interactive={false} />)
+    expect(screen.getByRole('img', { name: 'Cases by stage' })).toBeInTheDocument()
+  })
+
+  it('computes domains and ticks', () => {
+    expect(toPlot({ ...line, up: { bounds: [0, 50] } }).span).toEqual([0, 50])
+    expect(toPlot({ ...line, records: [] }).span).toEqual([0, 1])
+    const flat = toPlot({ ...line, layers: [{ field: 'a' }], records: [{ x: 1, a: 5 }, { x: 2, a: 5 }] }).span
+    expect(5 - flat[0]).toBeCloseTo(flat[1] - 5)
+    expect(niceTicks([0, 100], 5)).toEqual([0, 25, 50, 75, 100])
+  })
+
+  it('uses system colours and no animation', () => {
+    const css = cssOf('components/chart/Chart.css')
+    expect(mediaBlock(css, /\(forced-colors:\s*active\)/)).toMatch(/CanvasText/)
+    expect(mediaBlock(css, /\(prefers-reduced-motion:\s*reduce\)/)).toMatch(/animation:\s*none/)
+  })
+
+  it('has no axe violations in chart and table views, light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((s) => (
+          <ThemeScope key={s} scheme={s}>
+            <Chart figure={line} />
+            <Chart figure={{ ...line, form: 'columns', heading: 'Bars' }} defaultFace="table" />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('Chart value axis with a long unit', () => {
+  /** Left edge of the plot, read from the baseline (LTR). */
+  const plotStart = (container: HTMLElement) => Number(container.querySelector('.ty-chart__baseline')!.getAttribute('x1'))
+  const ticks = (container: HTMLElement) => Array.from(container.querySelectorAll('.ty-chart__axes > g > text.ty-chart__tick'), (t) => t.textContent ?? '')
+
+  it('widens the gutter so every tick label with its unit fits beside the axis', () => {
+    const short = render(<Chart figure={line} />)
+    const narrow = plotStart(short.container)
+    short.unmount()
+    const { container } = render(<Chart figure={{ ...line, up: { caption: 'Cases', unit: 'thousand people' } }} />)
+    const wide = plotStart(container)
+    expect(wide).toBeGreaterThan(narrow)
+    // Tick labels end 8 units before the plot and must start inside the drawing.
+    for (const label of ticks(container)) {
+      expect(label).toContain('thousand people')
+      expect(wide - 8 - estimateTickWidth(label)).toBeGreaterThanOrEqual(0)
+    }
+  })
+
+  it('moves a unit too long for the gutter to one caption above the axis, never clipped', () => {
+    const unit = 'registered public-service conversations per thousand residents'
+    const { container } = render(<Chart figure={{ ...line, up: { caption: 'Cases', unit } }} />)
+    const caption = container.querySelector('.ty-chart__unit')
+    expect(caption?.textContent).toBe(unit)
+    for (const label of ticks(container)) {
+      expect(label).not.toContain(unit)
+      expect(plotStart(container) - 8 - estimateTickWidth(label)).toBeGreaterThanOrEqual(0)
+    }
+    // The table view still carries the unit with each value.
+    fireEvent.click(screen.getByRole('radio', { name: /table/i }))
+    expect(screen.getAllByText(new RegExp(unit)).length).toBeGreaterThan(1)
+  })
+
+  it('keeps the default gutter for short labels', () => {
+    const layout = valueAxisLayout([0, 10, 20], { withUnit: (v) => `${v} cases`, bare: String }, true)
+    expect(layout).toMatchObject({ gutter: Math.max(52, estimateTickWidth('20 cases') + 14), unitCaption: false })
+    expect(valueAxisLayout([0, 5], { withUnit: String, bare: String }, false).gutter).toBe(52)
+  })
+})

package/src/components/chart/Chart.tsx

@@ -0,0 +1,502 @@
+import {
+  useId,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type PointerEvent as ReactPointerEvent,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { useLocale } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import type { ChartsGeoMessages } from '../../internal/messages/charts-geo'
+import { useMessages } from '../../internal/provider'
+import { DataTable } from '../data-table/DataTable'
+import { EmptyState } from '../empty-state/EmptyState'
+import { SegmentedControl } from '../segmented-control/SegmentedControl'
+import { linear, niceTicks, segments, visibleLabelIndices } from './chartMath'
+import { toPlot } from './plot'
+import type { ChartFace, ChartFigure, Glyph, Plot, Track } from './types'
+
+export type { ChartFace, ChartFigure, ChartForm, ChartLayer, ChartNote, ChartRecord } from './types'
+
+export interface ChartProps {
+  figure: ChartFigure
+  face?: ChartFace
+  defaultFace?: ChartFace
+  onFaceChange?: (face: ChartFace) => void
+  /** Width-to-height ratio of the plot; the chart always fills its container width. */
+  aspect?: number
+  /** Keyboard and pointer reading of points (default true). Static charts are one image. */
+  interactive?: boolean
+  /** Hide the chart/table switch (the table stays reachable through `face`). */
+  hideViewSwitch?: boolean
+  className?: string
+}
+
+/* ---------------------------------------------------------------- frame -- */
+
+/** viewBox width and the gutters around the plot, in viewBox units. */
+const CANVAS = 640
+const GUTTER = { head: 16, foot: 36, axisSide: 52, farSide: 20 }
+/** Tick label size (CSS 12px = 12 viewBox units) and the room kept beside it. */
+const TICK_EM = 12
+const TICK_GAP = 14
+/** Widest value gutter; a unit that would need more moves to a caption above the axis. */
+const AXIS_MAX = 176
+/** Extra head room for that caption. */
+const UNIT_CAPTION = 18
+
+/**
+ * Estimated advance of a tick label in viewBox units: about 0.6 em per
+ * grapheme, a full em for wide (CJK, fullwidth) ones. Deliberately generous,
+ * so a label is never cut at the edge of the drawing.
+ */
+export function estimateTickWidth(text: string): number {
+  const segmenter = typeof Intl.Segmenter === 'function' ? new Intl.Segmenter(undefined, { granularity: 'grapheme' }) : null
+  const parts = segmenter ? Array.from(segmenter.segment(text), (s) => s.segment) : Array.from(text)
+  return Math.ceil(parts.reduce((w, g) => w + ((g.codePointAt(0) ?? 0) >= 0x2e80 ? 1 : 0.62) * TICK_EM, 0))
+}
+
+/** Tick labels with and without the unit, for the gutter decision. */
+export interface TickText {
+  withUnit: (v: number) => string
+  bare: (v: number) => string
+}
+
+/**
+ * Value-axis layout: the gutter grows with the widest tick label. When the
+ * unit would push it past AXIS_MAX, ticks show numbers only and the unit is
+ * written once above the axis (never clipped).
+ */
+export function valueAxisLayout(ticks: number[], text: TickText, hasUnit: boolean) {
+  const widest = (say: (v: number) => string) => Math.max(0, ...ticks.map((t) => estimateTickWidth(say(t))))
+  const inline = widest(text.withUnit) + TICK_GAP
+  if (!hasUnit || inline <= AXIS_MAX) return { gutter: Math.max(GUTTER.axisSide, inline), unitCaption: false, label: text.withUnit }
+  return { gutter: Math.max(GUTTER.axisSide, Math.min(AXIS_MAX, widest(text.bare) + TICK_GAP)), unitCaption: true, label: text.bare }
+}
+
+interface Frame {
+  rtl: boolean
+  tall: number
+  /** Plot box in viewBox units (x0 always the physical left edge). */
+  x0: number
+  x1: number
+  y0: number
+  y1: number
+  slotWidth: number
+  slotX: (slot: number) => number
+  valueY: (reading: number) => number
+  floorY: number
+  ticks: number[]
+  /** Tick label text (with the unit unless it moved to the caption). */
+  tickLabel: (v: number) => string
+  /** The unit is written once above the value axis. */
+  unitCaption: boolean
+}
+
+function frameFor(plot: Plot, aspect: number, rtl: boolean, text: TickText): Frame {
+  const tall = Math.round(CANVAS / aspect)
+  const ticks = niceTicks(plot.span, 5)
+  const axis = valueAxisLayout(ticks, text, !!plot.unit)
+  // The value axis sits on the inline start, so its wide gutter changes side in RTL.
+  const x0 = rtl ? GUTTER.farSide : axis.gutter
+  const x1 = CANVAS - (rtl ? axis.gutter : GUTTER.farSide)
+  const y0 = GUTTER.head + (axis.unitCaption ? UNIT_CAPTION : 0)
+  const y1 = tall - GUTTER.foot
+  const slotWidth = (x1 - x0) / Math.max(plot.stops.length, 1)
+  const valueY = linear(plot.span, [y1, y0])
+  const [low, high] = plot.span
+  return {
+    rtl,
+    tall,
+    x0,
+    x1,
+    y0,
+    y1,
+    slotWidth,
+    slotX: (slot) => (rtl ? x1 - slotWidth * (slot + 0.5) : x0 + slotWidth * (slot + 0.5)),
+    valueY,
+    floorY: valueY(Math.min(Math.max(0, low), high)),
+    ticks,
+    tickLabel: axis.label,
+    unitCaption: axis.unitCaption,
+  }
+}
+
+/* --------------------------------------------------------------- cursor -- */
+
+/** Focused reading: slot (category) and lane (series), or none. */
+type Cursor = { slot: number; lane: number } | null
+
+type CursorEvent = { type: 'key'; key: string; rtl: boolean; slots: number; lanes: number } | { type: 'set'; to: Cursor }
+
+function steer(cursor: Cursor, event: CursorEvent): Cursor {
+  if (event.type === 'set') return event.to
+  const at = cursor ?? { slot: 0, lane: 0 }
+  const lastSlot = event.slots - 1
+  const clampSlot = (s: number) => Math.min(lastSlot, Math.max(0, s))
+  const forward = event.rtl ? 'ArrowLeft' : 'ArrowRight'
+  const back = event.rtl ? 'ArrowRight' : 'ArrowLeft'
+  switch (event.key) {
+    case forward:
+      return { ...at, slot: clampSlot(at.slot + 1) }
+    case back:
+      return { ...at, slot: clampSlot(at.slot - 1) }
+    case 'ArrowDown':
+      return { ...at, lane: Math.min(event.lanes - 1, at.lane + 1) }
+    case 'ArrowUp':
+      return { ...at, lane: Math.max(0, at.lane - 1) }
+    case 'Home':
+      return { ...at, slot: 0 }
+    case 'End':
+      return { ...at, slot: lastSlot }
+    case 'Escape':
+      return null
+    default:
+      return cursor
+  }
+}
+
+const STEERING_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'Escape'])
+
+/* --------------------------------------------------------------- glyphs -- */
+
+type GlyphDraw = (x: number, y: number, r: number, attrs: Record<string, unknown>) => ReactElement
+
+const GLYPHS: Record<Glyph, GlyphDraw> = {
+  dot: (x, y, r, attrs) => <circle {...attrs} cx={x} cy={y} r={r} />,
+  box: (x, y, r, attrs) => <rect {...attrs} x={x - r} y={y - r} width={r * 2} height={r * 2} />,
+  wedge: (x, y, r, attrs) => <polygon {...attrs} points={`${x},${y - r * 1.2} ${x + r * 1.1},${y + r * 0.9} ${x - r * 1.1},${y + r * 0.9}`} />,
+  rhomb: (x, y, r, attrs) => <polygon {...attrs} points={`${x},${y - r * 1.3} ${x + r * 1.3},${y} ${x},${y + r * 1.3} ${x - r * 1.3},${y}`} />,
+}
+
+/* --------------------------------------------------------------- layers -- */
+
+interface LayerProps {
+  plot: Plot
+  frame: Frame
+  cursor: Cursor
+  say: (reading: number) => string
+}
+
+function GridLayer({ plot, frame }: LayerProps) {
+  const shown = visibleLabelIndices(plot.stops.length, frame.x1 - frame.x0)
+  const tickX = frame.rtl ? frame.x1 + 8 : frame.x0 - 8
+  return (
+    <g className="ty-chart__axes" aria-hidden="true">
+      {frame.ticks.map((t) => (
+        <g key={t}>
+          <line className="ty-chart__grid" x1={frame.x0} x2={frame.x1} y1={frame.valueY(t)} y2={frame.valueY(t)} />
+          <text className="ty-chart__tick" x={tickX} y={frame.valueY(t)} textAnchor="end" dominantBaseline="middle">
+            {frame.tickLabel(t)}
+          </text>
+        </g>
+      ))}
+      {frame.unitCaption && plot.unit ? (
+        <text
+          className="ty-chart__tick ty-chart__unit"
+          x={frame.rtl ? CANVAS - GUTTER.farSide : GUTTER.farSide}
+          y={GUTTER.head}
+          textAnchor={frame.rtl ? 'end' : 'start'}
+          dominantBaseline="middle"
+        >
+          {plot.unit}
+        </text>
+      ) : null}
+      <line className="ty-chart__baseline" x1={frame.x0} x2={frame.x1} y1={frame.y1} y2={frame.y1} />
+      {shown.map((slot) => (
+        <text key={slot} className="ty-chart__tick" x={frame.slotX(slot)} y={frame.y1 + 20} textAnchor="middle">
+          {plot.stops[slot]}
+        </text>
+      ))}
+    </g>
+  )
+}
+
+function PinLayer({ plot, frame }: LayerProps) {
+  const nudge = frame.rtl ? -4 : 4
+  return (
+    <g className="ty-chart__annotations">
+      {plot.pins.map((pin) => {
+        const x = frame.slotX(pin.slot)
+        return (
+          <g key={`${pin.slot}:${pin.text}`} className="ty-chart__annotation" data-category={plot.stops[pin.slot]}>
+            <line x1={x} x2={x} y1={frame.y0} y2={frame.y1} />
+            <text x={x + nudge} y={frame.y0 + 10}>
+              {pin.text}
+            </text>
+          </g>
+        )
+      })}
+    </g>
+  )
+}
+
+function blockTrack(track: Track, lane: number, { plot, frame, cursor }: LayerProps) {
+  const flush = plot.stroke.mode === 'block' && plot.stroke.flush
+  const lanes = plot.tracks.length
+  const group = flush ? frame.slotWidth : frame.slotWidth * 0.78
+  const width = flush ? frame.slotWidth : group / lanes
+  const leftOf = (slot: number) => {
+    const middle = frame.slotX(slot)
+    if (flush) return middle - frame.slotWidth / 2
+    return frame.rtl ? middle + group / 2 - width * (lane + 1) : middle - group / 2 + width * lane
+  }
+  return track.readings.map((reading, slot) =>
+    reading === null ? null : (
+      <rect
+        key={slot}
+        className="ty-chart__mark ty-chart__bar"
+        data-active={(cursor?.slot === slot && cursor.lane === lane) || undefined}
+        data-overlap={flush && lanes > 1 ? '' : undefined}
+        x={leftOf(slot)}
+        y={Math.min(frame.valueY(reading), frame.floorY)}
+        width={width}
+        height={Math.max(Math.abs(frame.floorY - frame.valueY(reading)), 0.5)}
+      />
+    ),
+  )
+}
+
+function pathTrack(track: Track, lane: number, { plot, frame, cursor }: LayerProps) {
+  const runs = segments(track.readings.map((reading, slot) => (reading === null ? null : { x: frame.slotX(slot), y: frame.valueY(reading), slot })))
+  const fill = plot.stroke.mode === 'path' && plot.stroke.fill
+  const draw = GLYPHS[track.glyph]
+  const trace = (run: (typeof runs)[number]) => run.map((p, k) => `${k ? 'L' : 'M'}${p.x},${p.y}`).join(' ')
+  return (
+    <>
+      {fill
+        ? runs.map((run, k) => (
+            <path key={`fill${k}`} className="ty-chart__area" d={`M${run[0]!.x},${frame.floorY} ${trace(run).replace(/^M/, 'L')} L${run.at(-1)!.x},${frame.floorY} Z`} />
+          ))
+        : null}
+      {runs.map((run, k) => (
+        <path key={`stroke${k}`} className="ty-chart__line" strokeDasharray={track.dash} d={trace(run)} />
+      ))}
+      {runs.flat().map((p) => {
+        const lit = cursor?.slot === p.slot && cursor.lane === lane
+        return <g key={p.slot}>{draw(p.x, p.y, lit ? 5.6 : 3.5, { className: 'ty-chart__mark', 'data-active': lit || undefined })}</g>
+      })}
+    </>
+  )
+}
+
+function TrackLayer(props: LayerProps) {
+  const drawTrack = props.plot.stroke.mode === 'block' ? blockTrack : pathTrack
+  return (
+    <g className="ty-chart__marks">
+      {props.plot.tracks.map((track, lane) => (
+        <g key={track.label} data-series={track.label} data-index={lane} data-kind={props.plot.kind} style={{ color: track.hue }}>
+          {drawTrack(track, lane, props)}
+        </g>
+      ))}
+    </g>
+  )
+}
+
+/** Drawing order: grid under pins under marks. */
+const LAYERS = [GridLayer, PinLayer, TrackLayer]
+
+function Key({ plot, name }: { plot: Plot; name: string }) {
+  return (
+    <ul className="ty-chart__legend" aria-label={name}>
+      {plot.tracks.map((track) => (
+        <li key={track.label} className="ty-chart__legend-item" style={{ color: track.hue }} data-dashed={track.dash ? '' : undefined}>
+          <svg className="ty-chart__swatch" viewBox="0 0 24 12" aria-hidden="true" focusable="false">
+            <line x1="1" x2="23" y1="6" y2="6" strokeDasharray={track.dash ? '4 3' : undefined} />
+          </svg>
+          <span className="ty-chart__legend-name">{track.label}</span>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+function TableView({ plot, caption, say, copy }: { plot: Plot; caption: string; say: (v: number) => string; copy: ChartsGeoMessages['chart'] }) {
+  const columnOf = (lane: number) => `lane-${lane}`
+  return (
+    <DataTable
+      caption={caption}
+      columns={[
+        { id: 'stop', header: plot.stopsHeader ?? copy.categoryColumn },
+        ...plot.tracks.map((track, lane) => ({ id: columnOf(lane), header: track.label, numeric: true, align: 'end' as const })),
+      ]}
+      rows={plot.stops.map((stop, slot) => ({
+        id: String(slot),
+        cells: Object.fromEntries([
+          ['stop', stop],
+          ...plot.tracks.map((track, lane) => {
+            const reading = track.readings[slot] ?? null
+            return [columnOf(lane), reading === null ? <span className="ty-chart__missing">{copy.missing}</span> : say(reading)]
+          }),
+        ]) as Record<string, ReactNode>,
+      }))}
+    />
+  )
+}
+
+/* ------------------------------------------------------------ component -- */
+
+/** Accessible figure for a declarative chart, with a complete table view (spec: wave-2/chart.md). */
+export function Chart(props: ChartProps) {
+  const copy = useMessages().chart
+  const { locale, direction } = useLocale()
+  const rtl = direction === 'rtl'
+  const base = useId()
+  const live = props.interactive ?? true
+  const plot = useMemo(() => toPlot(props.figure), [props.figure])
+  const [ownFace, setOwnFace] = useState<ChartFace>(props.defaultFace ?? 'drawing')
+  const view = props.face ?? ownFace
+  const [cursor, dispatch] = useReducer(steer, null)
+  const canvas = useRef<SVGSVGElement>(null)
+
+  const say = useMemo(() => {
+    const digits = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 })
+    const joiner = new Intl.ListFormat(locale, { type: 'unit', style: 'narrow' })
+    const unit = plot.unit
+    return (v: number) => (unit ? joiner.format([digits.format(v), unit]) : digits.format(v))
+  }, [locale, plot.unit])
+  const frame = useMemo(() => {
+    const digits = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 })
+    return frameFor(plot, props.aspect ?? 16 / 9, rtl, { withUnit: say, bare: (v) => digits.format(v) })
+  }, [plot, props.aspect, rtl, say, locale])
+
+  const blank = plot.stops.length === 0 || plot.tracks.length === 0
+  const ids = { title: `${base}-title`, hint: `${base}-hint` }
+
+  const readoutText = (() => {
+    if (!cursor) return ''
+    const track = plot.tracks[cursor.lane]
+    const stop = plot.stops[cursor.slot]
+    if (!track || stop === undefined) return ''
+    const reading = track.readings[cursor.slot] ?? null
+    return copy.readout(stop, track.label, reading === null ? copy.missing : say(reading))
+  })()
+
+  const chooseView = (next: string) => {
+    if (props.face === undefined) setOwnFace(next as ChartFace)
+    props.onFaceChange?.(next as ChartFace)
+  }
+
+  const onKey = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!STEERING_KEYS.has(event.key)) return
+    event.preventDefault()
+    dispatch({ type: 'key', key: event.key, rtl, slots: plot.stops.length, lanes: plot.tracks.length })
+  }
+
+  const aim = (event: ReactPointerEvent<SVGSVGElement>) => {
+    const box = canvas.current?.getBoundingClientRect()
+    if (!box?.width) return
+    const vx = ((event.clientX - box.left) / box.width) * CANVAS
+    const vy = ((event.clientY - box.top) / box.height) * frame.tall
+    const along = rtl ? frame.x1 - vx : vx - frame.x0
+    const slot = Math.max(0, Math.min(plot.stops.length - 1, Math.floor(along / frame.slotWidth)))
+    const nearest = plot.tracks
+      .map((track, lane) => ({ lane, reading: track.readings[slot] ?? null }))
+      .filter((c): c is { lane: number; reading: number } => c.reading !== null)
+      .sort((a, b) => Math.abs(frame.valueY(a.reading) - vy) - Math.abs(frame.valueY(b.reading) - vy))[0]
+    dispatch({ type: 'set', to: { slot, lane: nearest?.lane ?? 0 } })
+  }
+
+  const layerProps: LayerProps = { plot, frame, cursor, say }
+
+  const plotArea = (): ReactNode => {
+    const drawing = (
+      <svg
+        ref={canvas}
+        className="ty-chart__svg"
+        viewBox={`0 0 ${CANVAS} ${frame.tall}`}
+        preserveAspectRatio="xMidYMid meet"
+        direction={rtl ? 'rtl' : 'ltr'}
+        role={live ? undefined : 'img'}
+        aria-label={live ? undefined : props.figure.heading}
+        aria-hidden={live ? true : undefined}
+        focusable="false"
+        {...(live ? { onPointerMove: aim, onPointerDown: aim, onPointerLeave: () => dispatch({ type: 'set', to: null }) } : {})}
+      >
+        {LAYERS.map((Layer, depth) => (
+          <Layer key={depth} {...layerProps} />
+        ))}
+      </svg>
+    )
+    if (!live) {
+      return (
+        <div className="ty-chart__plot" data-kind={plot.kind}>
+          {drawing}
+        </div>
+      )
+    }
+    const bubbleAt = cursor ? (rtl ? CANVAS - frame.slotX(cursor.slot) : frame.slotX(cursor.slot)) / CANVAS : 0
+    return (
+      <div
+        className="ty-chart__plot"
+        role="group"
+        tabIndex={0}
+        aria-labelledby={ids.title}
+        aria-describedby={ids.hint}
+        onKeyDown={onKey}
+        onFocus={() => dispatch({ type: 'set', to: cursor ?? { slot: 0, lane: 0 } })}
+        onBlur={() => dispatch({ type: 'set', to: null })}
+        data-kind={plot.kind}
+      >
+        {drawing}
+        {cursor && readoutText ? (
+          <div
+            className="ty-chart__readout"
+            aria-hidden="true"
+            style={{ insetInlineStart: `${bubbleAt * 100}%` }}
+            data-edge={cursor.slot > plot.stops.length / 2 ? 'end' : 'start'}
+          >
+            {readoutText}
+          </div>
+        ) : null}
+        <span id={ids.hint} className="ty-visually-hidden">
+          {copy.plotHint(props.figure.heading)}
+        </span>
+      </div>
+    )
+  }
+
+  const body: ReactNode = blank ? (
+    <EmptyState reason="custom" framing="inline" title={copy.noData} description={copy.noDataHint} headingLevel={4} />
+  ) : view === 'table' ? (
+    <TableView plot={plot} caption={props.figure.heading} say={say} copy={copy} />
+  ) : (
+    plotArea()
+  )
+
+  const { heading: title, aside: subtitle, reading: finding } = props.figure
+  return (
+    <figure className={cx('ty-chart', props.className)} aria-labelledby={ids.title} data-view={view} data-kind={plot.kind} data-direction={direction}>
+      <figcaption className="ty-chart__caption">
+        <span id={ids.title} className="ty-chart__title">
+          {title}
+        </span>
+        {subtitle ? <span className="ty-chart__subtitle">{subtitle}</span> : null}
+        {finding ? <span className="ty-chart__finding">{finding}</span> : null}
+      </figcaption>
+      {blank || props.hideViewSwitch ? null : (
+        <div className="ty-chart__tools">
+          <SegmentedControl
+            size="compact"
+            label={copy.viewSwitch}
+            options={[
+              { value: 'drawing', label: copy.chartView },
+              { value: 'table', label: copy.tableView },
+            ]}
+            value={view}
+            onChange={chooseView}
+          />
+        </div>
+      )}
+      {!blank && view === 'drawing' ? <Key plot={plot} name={copy.legend} /> : null}
+      {body}
+      <div className="ty-visually-hidden" role="status" aria-live="polite" aria-atomic="true">
+        {readoutText}
+      </div>
+    </figure>
+  )
+}