@lovett/ui 0.0.11 → 0.2.0

package/src/chart-frame.tsx

@@ -0,0 +1,960 @@
+/**
+ * ChartFrame — the shared chrome every chart primitive composes.
+ *
+ * Promoted in ADR-146 D5 (chart layer). It exists so the title row, legend
+ * slot, y-gutter, gridlines, baseline, x-labels, the four states and the
+ * table view are written once rather than once per chart.
+ *
+ * CONSUMERS — measured 2026-09-06.
+ *   TODAY, inside `@lovett/ui` (2): `line-chart.tsx` (`LineChart` /
+ *   `AreaChart`) and `bar-chart.tsx` (`BarChart`).
+ *   `DonutChart` and `RankedBars` do NOT compose it — a donut has no axes and
+ *   ranked bars are their own rows — so the earlier claim that this is "every
+ *   chart in the set" was simply wrong.
+ *   TODAY, in product code (0): no file under `apps/workspace/src` imports
+ *   `ChartFrame`. It reaches the product only through the two charts above.
+ *   Tracked in `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * ANATOMY (Metoric spec §6.2, mapped onto our tokens — real measurements,
+ * not eyeballed)
+ * -----------------------------------------------------------------------
+ *   frame      opaque panel, `--surface-card`, `--radius-md`, pad `--space-4`
+ *   y-labels   left column, `--text-tertiary`, 14px, ls -0.5, tabular-nums,
+ *              each centred on its own gridline. HOW MANY is decided by the
+ *              plot's own height, not by a fixed number: a tick needs about
+ *              two line boxes of room, so a short panel gets a shorter ladder
+ *              rather than five labels stacked into 40px of gutter.
+ *   gridlines  `rgb(var(--chart-grid))`, one per tick, count from `fitTicks`
+ *   baseline   `rgb(var(--chart-axis))` — **deliberately a darker rule than
+ *              the gridlines.** Every chart in the kit does this, and it is
+ *              one line of CSS that does more for legibility than any colour
+ *              decision. It is the detail that makes a chart read as a chart.
+ *   x-labels   a row that MIRRORS the plot row — same reserved gutter, same
+ *              gap — so its track is exactly the plot's width. Each label is
+ *              absolutely positioned at its own `xLabelFractions` fraction
+ *              and centred there, so it sits under the point or band it
+ *              names; the first and last anchor to the plot edges instead of
+ *              overhanging them.
+ *
+ * The frame is a plain `Card`-style panel with **no tray** (ADR-146 D1): a
+ * tray appears only when a widget holds more than one internal panel, which
+ * is what stops every chart growing a redundant 4px frame.
+ *
+ * THE FOUR STATES, ALL IN RESERVED SPACE (D10.7)
+ * ----------------------------------------------
+ * `loaded` / `loading` / `empty` / `error`. The plot box carries an
+ * `aspect-ratio`, so its height is fixed by its width and **async data cannot
+ * shift the page** — no white gap, no spinner in a collapsed box. `loading`
+ * is a correctly-sized skeleton occupying the same box the plot will.
+ *
+ * THE TABLE VIEW (D10.5)
+ * ----------------------
+ * Every chart that composes `ChartFrame` gets an accessible `<table>` of the
+ * same data for free. Pass `table`; the toggle appears and swaps the plot for
+ * the table. Omit it and no toggle renders — a control that leads nowhere is
+ * worse than no control. The table is the chart's accessible representation:
+ * a hand-rolled SVG plot is not readable by assistive tech, and this is how
+ * the contract is met rather than asserted.
+ *
+ * Token discipline: every colour is `rgb(var(--token))`; every spacing,
+ * radius and control height is a token. `--chart-grid` / `--chart-axis` carry
+ * their own alpha, so they are consumed as `rgb(var(--chart-grid))` and
+ * **never** given a second one — `rgb(var(--chart-grid) / 0.5)` expands to
+ * `rgb(0 0 0 / 0.08 / 0.5)`, which is invalid and silently discarded.
+ * `--muted` is used only for the skeleton well and the table header strip —
+ * flat opaque greys INSIDE an opaque panel, which is required structure, not
+ * a panel surface (CLAUDE.md §2 data-display recipe).
+ */
+
+import {
+  useLayoutEffect,
+  useState,
+  type ReactNode,
+} from 'react'
+import { ChartLine, Inbox, Table2, TriangleAlert } from 'lucide-react'
+
+import { cn } from './lib/utils'
+import {
+  estimateTextWidth,
+  fitLabelCount,
+  fitTicks,
+  strideIndices,
+} from './lib/chart'
+
+/**
+ * The room an x label needs beside its neighbour — the `--space-2` gutter the
+ * slot already subtracts, kept here so the capacity fit and the paint agree.
+ * The type size itself is `X_LABEL_FONT_PX`, declared with the other axis
+ * metrics below.
+ */
+const X_LABEL_GUTTER_PX = 8
+
+/**
+ * Y-axis metrics. The font size is what the tick row renders (`text-[14px]`);
+ * `SPACE_BASE_PX` is the 4px base of the `--space` scale, so a derived gutter
+ * still snaps to a rung; `Y_GUTTER_MIN_PX` is `var(--space-10)`, the width the
+ * gutter had when it was fixed — kept as a FLOOR so short-label axes do not
+ * tighten up now that the width adapts.
+ */
+const Y_TICK_FONT_PX = 14
+const SPACE_BASE_PX = 4
+const Y_GUTTER_MIN_PX = 40
+
+/** Which of the four states the frame is rendering. */
+export type ChartFrameState = 'loaded' | 'loading' | 'empty' | 'error'
+
+/** Chart or table. The table is the accessible representation (D10.5). */
+export type ChartFrameView = 'chart' | 'table'
+
+export interface ChartTableRow {
+  /** Stable identity key — the React key, never the array index. */
+  key: string
+  /**
+   * One pre-formatted string per column, in `columns` order. Formatting is
+   * the chart's job (`@lovett/ui/format`); the table only sets numbers in
+   * `tabular-nums`.
+   */
+  cells: readonly string[]
+}
+
+export interface ChartTableData {
+  /** Header cells. The first is the category column, the rest are measures. */
+  columns: readonly string[]
+  /** Body rows. */
+  rows: readonly ChartTableRow[]
+  /**
+   * Screen-reader caption describing the table. Defaults to the frame's
+   * `title`. Visually hidden — the figure caption already shows the title.
+   */
+  caption?: string
+}
+
+export interface ChartFrameProps {
+  /** Chart title. With a single series this also names it, so no legend
+   *  box is needed (D10.2). */
+  title?: string
+  /** Optional supporting line under the title. */
+  subtitle?: string
+  /** Trailing slot in the title row — a range picker, a menu. Sits before
+   *  the table toggle. */
+  action?: ReactNode
+  /**
+   * Legend node, rendered under the title row. Pass a `<ChartLegend>`.
+   * Two or more series always render one (D10.1); a single series does not
+   * (D10.2).
+   */
+  legend?: ReactNode
+  /** Which state to render. Default `'loaded'`. */
+  state?: ChartFrameState
+  /** Message for `state="empty"`. Default `'No data for this range.'` */
+  emptyMessage?: string
+  /** Message for `state="error"`. Default `'This chart could not load.'` */
+  errorMessage?: string
+  /** Adds a retry button to the error state. Omit for a non-retryable error. */
+  onRetry?: () => void
+  /**
+   * Explicit y-axis tick labels, **top to bottom** (max first). Takes
+   * precedence over `yDomain`. Use when the axis is categorical or already
+   * formatted upstream.
+   */
+  yLabels?: readonly string[]
+  /**
+   * `[min, max]` for a generated axis. Ticks come from `niceTicks` — the
+   * nice-number generator that replaces the literal `[0.25, 0.5, 0.75]`
+   * fraction list this repo used to inline. Ignored when `yLabels` is set.
+   */
+  yDomain?: readonly [number, number]
+  /** Target tick count for `yDomain`. Default `5`. */
+  yTickCount?: number
+  /**
+   * Formats a generated tick. Default `String`. **`formatPercent` takes
+   * percent units, not a 0-1 fraction** (ADR-146 D11) — convert at the call
+   * site.
+   */
+  formatYTick?: (value: number) => string
+  /** x-axis labels, left to right. */
+  xLabels?: readonly string[]
+  /**
+   * Where each `xLabels` entry actually SITS, as a fraction `0..1` of the
+   * plot's width. Same length as `xLabels`.
+   *
+   * Without this the row can only spread its labels evenly, which is a
+   * different axis from the one the marks are drawn on: a band scale centres
+   * its first category half a band in, and a thinned point axis keeps
+   * positions 0, 2, 4 … — neither is an even spread. Evenly spreading them
+   * put "Paid search" 25px, and the 3-category case 65px, away from the bar
+   * it names (measured in Chromium at 1440, 2026-09-06).
+   *
+   * Omit it and the labels fall back to an even point spread
+   * (`i / (n - 1)`), which is right for an unthinned line axis and wrong for
+   * everything else — so charts pass it.
+   */
+  xLabelFractions?: readonly number[]
+  /**
+   * Plot width ÷ height. The plot reserves its height from this, so async
+   * data cannot reflow the page. Default `16 / 5`, the kit's 459×108 plot.
+   * Pass `1` for a donut.
+   */
+  aspectRatio?: number
+  /**
+   * Reserved width of the y-label gutter, and the x-label row's left pad.
+   *
+   * Omit it and the gutter is DERIVED from the widest tick actually drawn,
+   * snapped up to the `--space` scale with `var(--space-10)` (40px) as the
+   * floor. That is the default because a fixed gutter cannot hold a label it
+   * has never seen: the labels are `right-0` and `whitespace-nowrap`, so a
+   * `$60,000` in a 40px box does not wrap or clip — it overflows LEFTWARD out
+   * of the gutter and through the panel's padding, and the axis ends up 2px
+   * from the panel edge while a `350` on the next chart sits 31px in.
+   *
+   * Pass a token-derived length to override it, and own the fit yourself.
+   */
+  yGutterWidth?: string
+  /** The same data as an accessible table. Omit to hide the view toggle. */
+  table?: ChartTableData
+  /** Controlled view. Omit for uncontrolled (starts on `'chart'`). */
+  view?: ChartFrameView
+  /** Called when the toggle changes the view. */
+  onViewChange?: (view: ChartFrameView) => void
+  /** The plot itself — an SVG, positioned absolutely inside the plot box.
+   *  The box is `position: relative`, which is what `ChartTooltip` needs. */
+  children?: ReactNode
+  /** Optional className on the outer panel. */
+  className?: string
+}
+
+/** Gap between the y-gutter and the plot, and the x-label row's extra pad. */
+const GUTTER_GAP = 'var(--space-3)'
+
+/**
+ * Line box of one y-tick label, in pixels.
+ *
+ * The gutter labels are `text-[14px]` against the frame's inherited 1.5 line
+ * height, and Chromium reports exactly `21px` for every one of them
+ * (`getBoundingClientRect().height`, measured off the shipped gallery
+ * 2026-09-06, light and dark, 390/900/1440). Pixel arithmetic cannot read a
+ * CSS custom property, so this is a number that names what it mirrors — the
+ * same contract as `bar-chart.tsx`'s `GAP_FULL_PX`.
+ *
+ * Not exported on its own: what the charts need is the SPACING below, and
+ * two different line-height numbers in two files is a chart whose axis
+ * disagrees with its own gutter.
+ */
+const Y_TICK_LINE_PX = 21
+
+/**
+ * The room two adjacent y ticks need between them: two line boxes.
+ *
+ * One line box apart is two labels touching; two is a ladder that reads as a
+ * ladder. Every y axis in the set — this frame's generated one, LineChart's
+ * and BarChart's — fits against THIS number, so the gutter and the scale can
+ * never disagree about how many ticks there are.
+ */
+export const Y_TICK_MIN_SPACING_PX = 2 * Y_TICK_LINE_PX
+
+/**
+ * Font size of an x-axis label, in pixels — `text-[14px]` on the row below.
+ * Charts estimate label widths against it when deciding how many to keep.
+ */
+export const X_LABEL_FONT_PX = 14
+
+/**
+ * Measure a box's height, and keep measuring it. `null` means NOT MEASURED —
+ * which is a different fact from "measured, and it is zero", and the
+ * difference is load-bearing.
+ *
+ * A zero-height plot is real: at a 390 viewport the design-system gallery's
+ * own shell collapses its content column, and the plot box measures 0 x 0.
+ * An axis in a 0px box has room for nothing, so its NUMBERS come off — but
+ * only when we actually know the box is zero. Reading an unmeasured box as
+ * zero would strip the numbers off every chart's first paint and then put
+ * them back, which is a worse defect than the one being fixed.
+ *
+ * The ONLY reading trusted is one a `ResizeObserver` delivered. That is the
+ * discriminator: jsdom ships a no-op observer stub whose callback never
+ * fires, so `clientHeight` there — always `0` — is never mistaken for a
+ * measurement, while a real browser's observer fires on `observe()` before
+ * the first paint and hands over the true size, zero or not.
+ *
+ * Only armed when the caller needs it (`enabled`), so a frame with no axis
+ * does not observe anything.
+ */
+function usePlotBox(
+  node: HTMLDivElement | null,
+  enabled: boolean,
+): { width: number; height: number } | null {
+  const [box, setBox] = useState<{ width: number; height: number } | null>(null)
+
+  useLayoutEffect(() => {
+    if (node === null || !enabled || typeof ResizeObserver === 'undefined') {
+      return
+    }
+
+    const observer = new ResizeObserver(() => {
+      const width = node.clientWidth
+      const height = node.clientHeight
+      setBox((prev) =>
+        prev !== null && prev.width === width && prev.height === height
+          ? prev
+          : { width, height },
+      )
+    })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [node, enabled])
+
+  return box
+}
+
+/**
+ * Where label `index` sits along the x axis, as a fraction `0..1`.
+ *
+ * The fallback when no `xLabelFractions` is given: an even POINT spread, so
+ * the first label sits on the plot's left edge and the last on its right.
+ */
+function xFraction(
+  fractions: readonly number[] | undefined,
+  index: number,
+  count: number,
+): number {
+  const given = fractions?.[index]
+  if (given !== undefined && Number.isFinite(given)) {
+    return Math.max(0, Math.min(1, given))
+  }
+  if (count <= 1) return 0.5
+  return index / (count - 1)
+}
+
+/**
+ * Vertical position of tick `index` of `count`, as a percentage from the top.
+ *
+ * A single tick sits at the **middle**, not the top or bottom: `niceTicks`
+ * returns one tick for a flat series, and `linearScale` maps a flat series to
+ * the middle of the range — so the label has to agree with where the line
+ * actually draws, or the axis lies.
+ */
+function tickPercent(index: number, count: number): number {
+  if (count <= 1) return 50
+  return (index / (count - 1)) * 100
+}
+
+export function ChartFrame({
+  title,
+  subtitle,
+  action,
+  legend,
+  state = 'loaded',
+  emptyMessage = 'No data for this range.',
+  errorMessage = 'This chart could not load.',
+  onRetry,
+  yLabels,
+  yDomain,
+  yTickCount = 5,
+  formatYTick = String,
+  xLabels,
+  xLabelFractions,
+  aspectRatio = 16 / 5,
+  yGutterWidth,
+  table,
+  view,
+  onViewChange,
+  children,
+  className,
+}: ChartFrameProps) {
+  const [uncontrolledView, setUncontrolledView] = useState<ChartFrameView>('chart')
+  const activeView = view ?? uncontrolledView
+
+  function changeView(next: ChartFrameView) {
+    if (view === undefined) setUncontrolledView(next)
+    onViewChange?.(next)
+  }
+
+  // A generated axis has to FIT the plot it is drawn in, so the plot box is
+  // measured. Only when this frame is the one generating the ladder: a chart
+  // that passes `yLabels` has already fitted them against the same
+  // `Y_TICK_MIN_SPACING_PX`, and observing the box again would be a second
+  // ResizeObserver measuring the same thing to no effect.
+  // A CALLBACK ref, not `useRef`. The plot box unmounts and remounts — the
+  // table view swaps the whole plot row out, and `children` only render in the
+  // `loaded` state, so a chart that starts in `loading` or `empty` (the normal
+  // async path) paints its plot for the first time on a LATER render. A
+  // `useRef` + `[ref]` effect cannot see any of that: the ref object is stable
+  // for the component's life, so the observer binds once, to whatever node
+  // existed then, and never rebinds. The fit would then silently fall back to
+  // nominal sizes — which is the exact label overlap the measured fit exists
+  // to prevent. Node state re-fires the effect on every remount.
+  const [plotNode, setPlotNode] = useState<HTMLDivElement | null>(null)
+  const hasAxis = yLabels !== undefined || yDomain !== undefined
+  // The x-label row needs the plot's WIDTH for the same reason the y ladder
+  // needs its height, so the box is observed whenever either axis exists.
+  const plotBox = usePlotBox(plotNode, hasAxis || xLabels !== undefined)
+  const plotHeight = plotBox?.height ?? null
+
+  // Ticks are top-to-bottom (max first). `fitTicks` is ascending, so a
+  // generated axis is reversed for display.
+  const ticks: string[] =
+    yLabels !== undefined
+      ? [...yLabels]
+      : yDomain !== undefined
+        ? fitTicks(
+            yDomain[0],
+            yDomain[1],
+            // `null` (unmeasured) reads as 0, which `fitTicks` already
+            // treats as "leave the requested count alone".
+            plotHeight ?? 0,
+            Y_TICK_MIN_SPACING_PX,
+            yTickCount,
+          )
+            .map((value) => formatYTick(value))
+            .reverse()
+        : []
+
+  /**
+   * Below one line box of plot, two labels at the two extremes overlap
+   * whatever the tick count is — the floor of two ticks cannot go lower.
+   * Measured: an 8px plot painted "$50,000" over "$0" by 12.9px, and a
+   * 0px one (the gallery shell's collapsed column at a 390 viewport) painted
+   * every pair of a three-rung ladder on top of each other.
+   *
+   * So under that floor the axis keeps its STRUCTURE — the gutter's reserved
+   * width and the gridlines, which are what make the plot readable as a plot
+   * — and drops the NUMBERS, which at that size are not readable as numbers.
+   * It is the same "keep the structure, drop the lie" move `BarChart` already
+   * makes for an all-zero range, and it is strictly better than two figures
+   * printed on top of each other.
+   *
+   * An UNMEASURED plot (`null`) keeps its numbers: not knowing the height is
+   * not the same as knowing it is too small.
+   */
+  const tickNumbersFit = plotHeight === null || plotHeight >= Y_TICK_LINE_PX
+
+  /**
+   * The gutter has to hold the LONGEST label it will actually draw, or the
+   * axis crowds the panel edge — `$60,000` measured 2px from it while `350`
+   * on a neighbouring chart sat 31px in, because a fixed box right-aligns its
+   * contents and lets the overflow escape leftward.
+   *
+   * Snapped UP to the 4px `--space` base so an adaptive width still lands on
+   * the scale, and floored at `--space-10` so a short-label axis keeps the
+   * same generous gutter it has today rather than tightening.
+   */
+  const derivedGutterPx = (() => {
+    if (ticks.length === 0) return 0
+    const widest = ticks.reduce(
+      (max, label) => Math.max(max, estimateTextWidth(label, Y_TICK_FONT_PX)),
+      0,
+    )
+    return Math.max(
+      Y_GUTTER_MIN_PX,
+      Math.ceil(widest / SPACE_BASE_PX) * SPACE_BASE_PX,
+    )
+  })()
+
+  const hasGutter = ticks.length > 0
+  const gutterWidth = hasGutter
+    ? (yGutterWidth ?? `${derivedGutterPx}px`)
+    : '0px'
+  const showPlotChrome = state === 'loaded' || state === 'loading'
+  const showTable = table !== undefined && activeView === 'table'
+
+  const captionText = table?.caption ?? title ?? 'Chart data'
+
+  /**
+   * The narrowest gap between two adjacent x labels, as a percentage of the
+   * plot. It is what each label may occupy before it starts eating its
+   * neighbour's room — with a `--space-2` gutter subtracted at the call site
+   * so two full-width labels never touch.
+   *
+   * Derived from the fractions rather than from the count, because a band
+   * axis and a thinned point axis do not have the same spacing.
+   */
+  /**
+   * Which x labels actually get drawn.
+   *
+   * Constraining each label to its own slot stops neighbours overlapping, but
+   * on a narrow plot every slot is a few pixels wide and the whole axis
+   * truncates to nothing — measured on this component's own demo at a 382px
+   * panel: twelve "Wk n" labels at 5px each, the first and last at 0. An axis
+   * of empty slots is worse than a sparser one, so the row thins by a uniform
+   * STRIDE (`strideIndices`, which always keeps the first and the last) to
+   * the count the measured width can actually hold.
+   *
+   * `LineChart` already thins before it calls in; this is the same rule
+   * applied one level down, so a frame used directly gets it too and the two
+   * paths cannot disagree.
+   */
+  const keptXIndices = (() => {
+    const count = xLabels?.length ?? 0
+    if (count === 0) return []
+    const width = plotBox?.width ?? 0
+    if (!(width > 0)) return Array.from({ length: count }, (_, i) => i)
+    const widest = xLabels!.reduce(
+      (max, label) => Math.max(max, estimateTextWidth(label, X_LABEL_FONT_PX)),
+      0,
+    )
+    // The EDGE labels are the binding constraint, not the middle ones. A
+    // middle label is centred, so it spends half its width on each side of
+    // its tick and a full slot holds it. An edge label is anchored to the
+    // plot edge and spends its whole width on one side, so it only has the
+    // room up to its neighbour's near edge — half a slot plus half the
+    // gutter. Fitting against the middle case alone is what let "Wk 1" and
+    // "Wk 12" truncate at 20px on a 608px axis while every middle label sat
+    // comfortably in 47px.
+    //
+    // Inverting `widest <= slot / 2 + gutter / 2` gives the extent below.
+    const extent = Math.max(
+      widest + X_LABEL_GUTTER_PX,
+      2 * widest - X_LABEL_GUTTER_PX,
+    )
+    const capacity = fitLabelCount(width, extent, count)
+    return strideIndices(count, capacity)
+  })()
+
+  const keptXSet = new Set(keptXIndices)
+
+  /**
+   * The narrowest gap between two adjacent DRAWN x labels, as a percentage of
+   * the plot. It is what each label may occupy before it starts eating its
+   * neighbour's room — with a `--space-2` gutter subtracted at the call site
+   * so two full-width labels never touch.
+   *
+   * Derived from the fractions rather than from the count, because a band
+   * axis and a thinned point axis do not have the same spacing — and from the
+   * KEPT labels, because thinning is what widens the slot.
+   */
+  const slotPercent = (() => {
+    const count = xLabels?.length ?? 0
+    if (count <= 1 || keptXIndices.length <= 1) return 100
+    let narrowest = Number.POSITIVE_INFINITY
+    for (let i = 1; i < keptXIndices.length; i++) {
+      const gap =
+        xFraction(xLabelFractions, keptXIndices[i]!, count) -
+        xFraction(xLabelFractions, keptXIndices[i - 1]!, count)
+      if (gap < narrowest) narrowest = gap
+    }
+    if (!Number.isFinite(narrowest) || narrowest <= 0) {
+      return 100 / keptXIndices.length
+    }
+    return narrowest * 100
+  })()
+
+  return (
+    <figure
+      className={cn('flex flex-col', className)}
+      style={{
+        margin: 0,
+        gap: 'var(--space-3)',
+        background: 'rgb(var(--surface-card))',
+        border: '1px solid rgb(var(--border))',
+        borderRadius: 'var(--radius-md)',
+        padding: 'var(--space-4)',
+      }}
+    >
+      {(title !== undefined || subtitle !== undefined || action !== undefined ||
+        table !== undefined) && (
+        <figcaption className="flex items-start justify-between gap-3">
+          <div className="min-w-0">
+            {title !== undefined && (
+              <div
+                className="truncate text-[14px] font-semibold"
+                style={{ color: 'rgb(var(--foreground))' }}
+              >
+                {title}
+              </div>
+            )}
+            {subtitle !== undefined && (
+              <div
+                className="truncate text-[12px]"
+                style={{
+                  marginTop: 'var(--space-1)',
+                  color: 'rgb(var(--text-tertiary))',
+                }}
+              >
+                {subtitle}
+              </div>
+            )}
+          </div>
+          <div className="flex shrink-0 items-center gap-2">
+            {action}
+            {table !== undefined && (
+              <button
+                type="button"
+                onClick={() => changeView(showTable ? 'chart' : 'table')}
+                aria-label={showTable ? 'Chart view' : 'Table view'}
+                className={cn(
+                  'inline-flex cursor-pointer items-center gap-2 text-[12px] font-medium',
+                  'motion-safe:transition-colors hover:border-[rgb(var(--border-strong))]',
+                  'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                )}
+                style={{
+                  height: 'var(--ctrl-sm)',
+                  paddingInline: 'var(--space-3)',
+                  // A bordered secondary control, never a ghost button: a
+                  // lesser action still has to read as a button (CLAUDE.md §2).
+                  background: 'rgb(var(--surface-overlay))',
+                  border: '1px solid rgb(var(--border))',
+                  borderRadius: 'var(--radius-xs)',
+                  color: 'rgb(var(--text-secondary))',
+                }}
+              >
+                {showTable ? (
+                  <ChartLine aria-hidden="true" className="h-4 w-4" />
+                ) : (
+                  <Table2 aria-hidden="true" className="h-4 w-4" />
+                )}
+                {showTable ? 'Chart' : 'Table'}
+              </button>
+            )}
+          </div>
+        </figcaption>
+      )}
+
+      {legend}
+
+      {showTable ? (
+        <ChartDataTable data={table} caption={captionText} />
+      ) : (
+        <>
+          <div className="flex items-stretch" style={{ gap: GUTTER_GAP }}>
+            {/* y-gutter. Always reserved, even in empty/error, so the plot
+                does not change width between states. */}
+            <div
+              className="relative shrink-0"
+              style={{ width: gutterWidth }}
+              aria-hidden="true"
+            >
+              {state === 'loaded' &&
+                ticks.map((label, index) => (
+                  <span
+                    key={`${index}-${label}`}
+                    className="absolute right-0 text-[14px] tabular-nums tracking-[-0.5px] whitespace-nowrap"
+                    style={{
+                      top: `${tickPercent(index, ticks.length)}%`,
+                      transform: 'translateY(-50%)',
+                      color: 'rgb(var(--text-tertiary))',
+                    }}
+                  >
+                    {tickNumbersFit ? label : ''}
+                  </span>
+                ))}
+            </div>
+
+            {/* Plot box. `relative` is load-bearing: ChartTooltip and every
+                gridline position against it, and `aspect-ratio` is what
+                reserves the height. */}
+            <div
+              ref={setPlotNode}
+              className="relative min-w-0 flex-1"
+              style={{ aspectRatio: String(aspectRatio) }}
+            >
+              {showPlotChrome && (
+                <>
+                  {ticks.map((label, index) => {
+                    const pct = tickPercent(index, ticks.length)
+                    // The bottom tick IS the baseline, which is drawn below
+                    // in the darker --chart-axis. Drawing both would stack a
+                    // light rule on a dark one.
+                    if (pct >= 100) return null
+                    return (
+                      <div
+                        key={`grid-${index}-${label}`}
+                        aria-hidden="true"
+                        className="pointer-events-none absolute right-0 left-0"
+                        style={{
+                          top: `${pct}%`,
+                          height: '1px',
+                          background: 'rgb(var(--chart-grid))',
+                        }}
+                      />
+                    )
+                  })}
+                  {/* The baseline: a DARKER rule than the gridlines. */}
+                  <div
+                    aria-hidden="true"
+                    className="pointer-events-none absolute right-0 bottom-0 left-0"
+                    style={{
+                      height: '1px',
+                      background: 'rgb(var(--chart-axis))',
+                    }}
+                  />
+                </>
+              )}
+
+              {state === 'loaded' && children}
+
+              {state === 'loading' && (
+                <div
+                  role="status"
+                  aria-label="Loading chart"
+                  className="absolute inset-0 motion-safe:animate-pulse"
+                  style={{
+                    background: 'rgb(var(--muted))',
+                    borderRadius: 'var(--radius-sm)',
+                  }}
+                />
+              )}
+
+              {state === 'empty' && (
+                <ChartFrameMessage
+                  icon={
+                    <Inbox
+                      aria-hidden="true"
+                      className="h-5 w-5"
+                      style={{ color: 'rgb(var(--text-muted))' }}
+                    />
+                  }
+                  message={emptyMessage}
+                />
+              )}
+
+              {state === 'error' && (
+                <ChartFrameMessage
+                  role="alert"
+                  icon={
+                    <TriangleAlert
+                      aria-hidden="true"
+                      className="h-5 w-5"
+                      style={{ color: 'rgb(var(--destructive))' }}
+                    />
+                  }
+                  message={errorMessage}
+                  action={
+                    onRetry !== undefined ? (
+                      <button
+                        type="button"
+                        onClick={onRetry}
+                        className={cn(
+                          'cursor-pointer text-[12px] font-medium',
+                          'motion-safe:transition-colors hover:border-[rgb(var(--border-strong))]',
+                          'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                        )}
+                        style={{
+                          height: 'var(--ctrl-sm)',
+                          paddingInline: 'var(--space-3)',
+                          background: 'rgb(var(--surface-overlay))',
+                          border: '1px solid rgb(var(--border))',
+                          borderRadius: 'var(--radius-xs)',
+                          color: 'rgb(var(--foreground))',
+                        }}
+                      >
+                        Try again
+                      </button>
+                    ) : undefined
+                  }
+                />
+              )}
+            </div>
+          </div>
+
+          {/* x-labels.
+              The row MIRRORS the plot row above it — the same reserved
+              gutter, the same gap — so the label track is exactly as wide as
+              the plot and a fraction of it means the same thing in both. It
+              used to be one padded flex row with `justify-between`, which
+              spreads labels EVENLY whatever their real x: measured in
+              Chromium at 1440, that put BarChart's "Paid search" 25px from
+              its bar and, on the 3-category demo, 65px. Every label now sits
+              at its own fraction and is centred there; the first and last
+              anchor to the plot edges instead of overhanging them.
+              The row keeps its height in every state so a load does not
+              shift the panel. */}
+          <div
+            className="flex items-stretch"
+            style={{ minHeight: 'var(--space-5)', gap: GUTTER_GAP }}
+            aria-hidden="true"
+          >
+            <div className="shrink-0" style={{ width: gutterWidth }} />
+            <div className="relative min-w-0 flex-1">
+              {state === 'loaded' &&
+                xLabels?.map((label, index) => {
+                  const count = xLabels.length
+                  // Thinned out at this width — see `keptXIndices`. The row
+                  // keeps its height either way, so dropping a label never
+                  // moves the plot.
+                  if (!keptXSet.has(index)) return null
+                  const fraction = xFraction(xLabelFractions, index, count)
+                  // Edge labels anchor to the edge they sit on. Centring them
+                  // would hang half a label outside the plot; this is the
+                  // same start / middle / end rule the direct value labels
+                  // inside the plot already use.
+                  const anchor =
+                    fraction <= 0 ? 'start' : fraction >= 1 ? 'end' : 'middle'
+                  return (
+                    <span
+                      key={`${index}-${label}`}
+                      className="absolute top-0 truncate text-[14px] tabular-nums tracking-[-0.5px]"
+                      style={{
+                        left: `${fraction * 100}%`,
+                        transform:
+                          anchor === 'start'
+                            ? undefined
+                            : anchor === 'end'
+                              ? 'translateX(-100%)'
+                              : 'translateX(-50%)',
+                        // The label may claim its own share of the axis and
+                        // no more, so `truncate` still has something to
+                        // truncate against now that the row is not a flex
+                        // track. `slotPercent` is the narrowest gap between
+                        // two labels; two CENTRED neighbours each spend half
+                        // a slot on the side that faces the other, so a full
+                        // slot is exactly their non-overlap bound. An
+                        // ANCHORED edge label spends its whole width on one
+                        // side, so it gets half — measured: two edge labels
+                        // at a full slot each overlapped by 10px on a 26px
+                        // axis.
+                        // A middle label is centred, so a full slot less the
+                        // gutter is exactly its non-overlap bound. An edge
+                        // label is anchored and spends its whole width on one
+                        // side, so its bound is the distance to its
+                        // neighbour's near edge: half a slot, plus back the
+                        // half-gutter the neighbour's own box already gave
+                        // up. Subtracting a WHOLE gutter here instead was the
+                        // 20px truncation.
+                        maxWidth:
+                          anchor === 'middle'
+                            ? `calc(${slotPercent}% - var(--space-2))`
+                            : `calc(${slotPercent / 2}% + (var(--space-2) / 2))`,
+                        textAlign:
+                          anchor === 'start'
+                            ? 'left'
+                            : anchor === 'end'
+                              ? 'right'
+                              : 'center',
+                        color: 'rgb(var(--text-tertiary))',
+                      }}
+                    >
+                      {label}
+                    </span>
+                  )
+                })}
+            </div>
+          </div>
+        </>
+      )}
+    </figure>
+  )
+}
+
+interface ChartFrameMessageProps {
+  icon: ReactNode
+  message: string
+  action?: ReactNode
+  role?: 'alert'
+}
+
+/** Centred state message, inside the plot box's already-reserved space. */
+function ChartFrameMessage({
+  icon,
+  message,
+  action,
+  role,
+}: ChartFrameMessageProps) {
+  return (
+    <div
+      role={role}
+      className="absolute inset-0 flex flex-col items-center justify-center text-center"
+      style={{ gap: 'var(--space-2)', padding: 'var(--space-4)' }}
+    >
+      {icon}
+      <span
+        className="text-[13px]"
+        style={{ color: 'rgb(var(--text-tertiary))' }}
+      >
+        {message}
+      </span>
+      {action}
+    </div>
+  )
+}
+
+interface ChartDataTableProps {
+  data: ChartTableData
+  caption: string
+}
+
+/**
+ * The accessible table view.
+ *
+ * Built to the data-display surface recipe (CLAUDE.md §2): an opaque panel,
+ * with the grey STRUCTURE inside it — a solid `--muted` header strip and
+ * `--border` row rules. Stripping those is the "flat / floating" defect, and
+ * it is exactly as wrong as using a translucent tint for the surface.
+ *
+ * Column 0 is the category and left-aligns; every other column is a measure
+ * and right-aligns in `tabular-nums`, so figures line up digit for digit.
+ */
+function ChartDataTable({ data, caption }: ChartDataTableProps) {
+  return (
+    <div
+      className="overflow-x-auto"
+      style={{
+        border: '1px solid rgb(var(--border))',
+        borderRadius: 'var(--radius-sm)',
+      }}
+    >
+      <table className="w-full border-collapse text-left">
+        <caption className="sr-only">{caption}</caption>
+        <thead>
+          <tr style={{ background: 'rgb(var(--muted))' }}>
+            {data.columns.map((column, index) => (
+              <th
+                key={column}
+                scope="col"
+                className={cn(
+                  'text-[12px] font-semibold whitespace-nowrap',
+                  index === 0 ? 'text-left' : 'text-right',
+                )}
+                style={{
+                  padding: 'var(--space-2) var(--space-3)',
+                  borderBottom: '1px solid rgb(var(--border))',
+                  color: 'rgb(var(--text-secondary))',
+                }}
+              >
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {data.rows.map((row, rowIndex) => (
+            <tr key={row.key}>
+              {row.cells.map((cell, cellIndex) => {
+                const isCategory = cellIndex === 0
+                const style = {
+                  padding: 'var(--space-2) var(--space-3)',
+                  borderTop:
+                    rowIndex > 0 ? '1px solid rgb(var(--border))' : undefined,
+                  color: isCategory
+                    ? 'rgb(var(--foreground))'
+                    : 'rgb(var(--text-secondary))',
+                }
+                const className = cn(
+                  'text-[13px] whitespace-nowrap',
+                  isCategory ? 'text-left font-medium' : 'text-right tabular-nums',
+                )
+                return isCategory ? (
+                  <th
+                    key={`${row.key}-${cellIndex}`}
+                    scope="row"
+                    className={className}
+                    style={style}
+                  >
+                    {cell}
+                  </th>
+                ) : (
+                  <td
+                    key={`${row.key}-${cellIndex}`}
+                    className={className}
+                    style={style}
+                  >
+                    {cell}
+                  </td>
+                )
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}