@lovett/ui 0.0.11 → 0.2.0

package/src/line-chart.tsx

@@ -0,0 +1,1176 @@
+/**
+ * LineChart / AreaChart — the time-series plot, and the same plot with a
+ * filled region under it.
+ *
+ * Promoted in ADR-146 D5 (chart layer). One file, shared internals: an area
+ * chart IS a line chart plus a gradient fill, and forking them is how the two
+ * drift apart on stroke width, marker treatment and hover behaviour. Both
+ * compose `ChartFrame` for every piece of chrome (panel, title, legend,
+ * y-gutter, gridlines, baseline, x-labels, the four states, the table view),
+ * so this file owns exactly one thing: the marks and the interaction.
+ *
+ * CONSUMERS — measured 2026-09-06 (real `from '@lovett/ui'` imports under
+ * `apps/workspace/src`; the design-system gallery is a demo harness and does
+ * NOT count toward the ADR-008 D3 gate — the earlier version of this comment
+ * counted it, which is what made the claim false).
+ *   `AreaChart` TODAY (1 — gate NOT MET):
+ *     • `components/ui/admin/analytics.tsx` — the weekly tool-run trend
+ *   `LineChart` TODAY (0): no product consumer at all.
+ *   PLANNED: a Discovery report trend panel (`lenses/discovery/report-sections/`).
+ *   `AreaChart` also supersedes the `Trend Line` specimen in
+ *   `design-system/spec/shell-charts.tsx` (retirement tracked in
+ *   `promote-spec-charts.md`), but that is gallery code and is not a consumer.
+ *   Tracked in `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * MARK SPEC (Metoric anatomy §6.2 — real measurements, not eyeballed)
+ * -------------------------------------------------------------------
+ *   line      2px stroke in `rgb(var(--series-N))`, round cap + round join,
+ *             plus a very subtle drop shadow. The shadow is what lifts the
+ *             series off the gridlines; the kit ships it on every chart.
+ *   area      a vertical gradient from the series hue at 0.18 alpha down to
+ *             fully transparent, closing on the ZERO line rather than the
+ *             floor of the plot. Never a flat fill — a flat fill competes
+ *             with the line for the same ink.
+ *   point     a FILLED dot with a 2px ring in the panel surface colour, 8-10px
+ *             across, so it stays legible wherever it lands including on top
+ *             of the area fill. (The small `Sparkline` inverts this — hollow
+ *             at small size, filled at large.)
+ *   hover     a BAND, not a 1px crosshair (ADR-146 D9): a full-plot-height
+ *             column of `rgb(var(--chart-band))`, about one x-step wide,
+ *             `--radius-xs`, snapping to the nearest x. A far larger hit
+ *             target, and it reads deliberate rather than technical.
+ *
+ * WHY EVERY GRADIENT GETS A `useId()` SUFFIX
+ * ------------------------------------------
+ * `design-system/spec/shell-charts.tsx` names its gradients `fill-<index>`.
+ * SVG ids are document-global, so two charts on one page define the same id
+ * twice and every url() reference in the document resolves to whichever one
+ * the browser saw first. Both charts then paint the FIRST chart's colours —
+ * with typecheck, lint, build and the token gate all green, because the
+ * source is syntactically perfect. Every id here is suffixed with `useId()`
+ * (colons stripped: they are legal in an id but hostile inside a URL
+ * fragment) and keyed by series INDEX rather than the caller's key, which may
+ * contain characters an id may not.
+ *
+ * WHY THE SERIES SLOT IS REQUIRED AND NOT DEFAULTED
+ * -------------------------------------------------
+ * ADR-146 D7: colour follows the ENTITY, never its rank — a filter that
+ * removes a series must not repaint the survivors. The only default this
+ * primitive could pick is the array index, which is precisely the forbidden
+ * behaviour, so `slot` is a required field and the caller derives it from its
+ * own stable key. Colour then resolves through the frozen `SERIES` lookup in
+ * `lib/series.ts` (D8) — no primitive here ever composes a token NAME.
+ *
+ * EDGE CASES, EACH DELIBERATE (ADR-146 acceptance criterion 8)
+ * ------------------------------------------------------------
+ *   • **One point** — `linePath` emits a zero-length segment which, with
+ *     `stroke-linecap: round`, paints as a dot. The marker draws on top. No
+ *     line, no empty plot.
+ *   • **Two points** — an ordinary segment; nothing special is needed.
+ *   • **All-zero series** — the domain collapses to `[0, 0]`, `niceTicks`
+ *     returns the single tick `[0]`, `linearScale` maps everything to the
+ *     MIDDLE of the range, and `ChartFrame` puts a lone tick label at 50%.
+ *     Axis and data agree, and nothing divides by zero.
+ *   • **Negative values** — the baseline is then NOT the bottom of the plot.
+ *     The domain spans the data, a zero rule is drawn at `y(0)` in
+ *     `--chart-axis`, and the line goes below it. The AREA fill closes on
+ *     that zero line too: closing it on the plot floor instead would paint a
+ *     tall block of ink for a small negative number.
+ *   • **Gaps / nulls** — the line BREAKS. A gap splits the series into
+ *     separate path segments rather than being interpolated across, because a
+ *     line drawn through missing data is a chart that lies.
+ *   • **No finite data at all** — the frame's `empty` state, in reserved
+ *     space. Never a white gap.
+ *
+ * Token discipline: every colour is `rgb(var(--token))`, resolved from the
+ * frozen series lookup or a text/structure token; there is no colour literal
+ * in this file, and no colour is ever built by string surgery. `--chart-band`
+ * and `--chart-axis` carry their own alpha, so they are consumed as
+ * `rgb(var(--chart-band))` and never given a second one. Every spacing,
+ * radius and duration is a token. The bare numbers that remain are SVG
+ * geometry in user units — path arithmetic cannot read a custom property —
+ * and each is a named constant recording the measurement it came from.
+ * Motion runs through `motion-safe:` utilities so `prefers-reduced-motion`
+ * jumps to the final state, and every transition is `--ease-out`: overshoot
+ * on a data change reads as imprecise (D9).
+ */
+
+import {
+  useCallback,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type PointerEvent,
+  type ReactNode,
+} from 'react'
+
+import { cn } from './lib/utils'
+import { formatNumber } from './format'
+import {
+  areaPath,
+  estimateTextWidth,
+  fitLabelCount,
+  fitTicks,
+  linePath,
+  linearScale,
+  strideIndices,
+  type NumericInput,
+  type Point,
+} from './lib/chart'
+import { slotColor, type ChartSlot, type SeriesPalette } from './lib/series'
+import {
+  ChartFrame,
+  X_LABEL_FONT_PX,
+  Y_TICK_MIN_SPACING_PX,
+  type ChartFrameState,
+  type ChartTableData,
+  type ChartTableRow,
+} from './chart-frame'
+import { ChartLegend, type ChartLegendItem } from './chart-legend'
+import { ChartTooltip, type ChartTooltipRow } from './chart-tooltip'
+
+/* ── geometry constants ──────────────────────────────────────────────────
+ * SVG user units. These cannot be tokens: they feed path and attribute
+ * arithmetic, and a custom property is not readable at the point the
+ * geometry is built. Each records the measurement it came from. */
+
+/** Line stroke. Metoric §6.2 measures the line at `2-3px`. */
+const STROKE = 2
+/** Marker radius. §6.2 measures the point at `10 x 10`, so r = 5. */
+const MARKER_RADIUS = 5
+/** The ring around a marker, in the panel surface colour. §6.2 `stroke:2`. */
+const MARKER_RING = 2
+/** Gap between a direct label's baseline and the marker it labels. */
+const LABEL_GAP = 2
+/** Marker radius + its ring + the gap: how far a label clears its dot. */
+const LABEL_OFFSET = MARKER_RADIUS + MARKER_RING + LABEL_GAP
+/**
+ * Approximate cap height of the 12px direct label, in user units.
+ *
+ * SVG `<text>` has no layout box to measure, and the peak point sits at or
+ * near `y = 0` whenever `niceTicks` rounds the domain tight to the data — so
+ * without this the label's glyphs paint ABOVE the plot, on top of the legend,
+ * because the plot SVG is deliberately `overflow: visible` (so markers at the
+ * edge are not clipped). It is the threshold for flipping a label below its
+ * marker instead.
+ */
+const LABEL_CAP = 9
+/** Nominal plot width for the first paint, before measurement lands. */
+const NOMINAL_WIDTH = 459
+/** Narrowest hover band, ≈ `--space-2`. Below this it stops being a target. */
+const MIN_BAND = 8
+/** Band width as a share of one x-step — the kit's 44 across a ~55 step. */
+const BAND_STEP_RATIO = 0.8
+/** Above this many x positions, `markers="auto"` stops drawing every point. */
+const AUTO_MARKER_LIMIT = 12
+/**
+ * Most x labels the axis ROW will render, however wide the plot gets.
+ *
+ * The row is a fixed-width track: hand it a 90-day series and it draws 90
+ * labels a few pixels apart — an unreadable mush, with every gate green.
+ * Beyond this cap the axis thins by a uniform STRIDE (`strideIndices`), first
+ * and last always kept, which is what the eye reads anyway.
+ *
+ * The cap is the CEILING, not the answer: the actual count is fitted against
+ * the measured plot width and the widest label (`fitLabelCount`), so a 234px
+ * panel does not get the same eight labels a 608px one does.
+ *
+ * This thinning is the ONLY truncation in this file, it applies to LABELS
+ * and never to data, and it is reversible in one click: the plot draws every
+ * position, and the table view carries one row per position — including
+ * positions the caller gave no label for (see `count`).
+ */
+const MAX_X_LABELS = 8
+
+/** Smallest gap between two x labels before they read as one word. */
+const X_LABEL_GAP_PX = 12
+
+/**
+ * Font size and weight of a direct value label — `text-[12px] font-semibold`
+ * on the `<text>` below. Chromium measures its line box at exactly 15px
+ * (`getBoundingClientRect().height`, gallery, 2026-09-06), which is what the
+ * collision pass uses for a label's vertical extent.
+ */
+const VALUE_LABEL_FONT_PX = 12
+const VALUE_LABEL_BOX_PX = 15
+/** Clear air required between two value labels before they count as apart. */
+const VALUE_LABEL_PAD_PX = 3
+/** What a gap reads as in the tooltip and the table. Not a zero: a missing
+ *  datum is not a measurement of none. */
+const NO_VALUE = '—'
+
+/** One series of the plot. */
+export interface LineChartSeries {
+  /**
+   * Stable entity key — the React key, the tooltip row key and the legend
+   * key. Never an array index.
+   */
+  key: string
+  /** Series name. Shown in the legend, the tooltip and the table header. */
+  label: string
+  /**
+   * One value per x position, aligned to `xLabels` by index. `null` /
+   * `undefined` / `NaN` is a GAP: the line breaks rather than interpolating
+   * across it.
+   *
+   * A series LONGER than `xLabels` is plotted in full — the surplus
+   * positions simply carry no axis label. Values are never discarded to fit
+   * the label count.
+   */
+  values: readonly NumericInput[]
+  /**
+   * Palette slot, or `'other'` for the folded remainder.
+   *
+   * Required on purpose (ADR-146 D7): the only default available here is the
+   * array index, and defaulting to it would repaint every surviving series
+   * the moment a caller filters one out. Derive it from `key`.
+   */
+  slot: ChartSlot
+}
+
+export interface LineChartProps {
+  /** The series, in draw order. */
+  series: readonly LineChartSeries[]
+  /**
+   * x-axis labels, left to right.
+   *
+   * It does NOT cap the number of x positions: the plot has as many
+   * positions as the longest of this list and every series. A short label
+   * list leaves the surplus positions unlabelled; it never truncates data.
+   */
+  xLabels: readonly string[]
+  /** Chart title. With a single series this also names it, so no legend box
+   *  renders (ADR-146 D10.2). */
+  title?: string
+  /** Optional supporting line under the title. */
+  subtitle?: string
+  /** Trailing slot in the title row — a range picker, a menu. */
+  action?: ReactNode
+  /** Frame state. `'loaded'` with no finite datum renders `'empty'`. */
+  state?: ChartFrameState
+  /** Message for the empty state. */
+  emptyMessage?: string
+  /** Message for the error state. */
+  errorMessage?: string
+  /** Adds a retry button to the error state. */
+  onRetry?: () => void
+  /**
+   * Force the y domain. Ticks are still nice-numbered from it, so the drawn
+   * domain may round outward. Omit to derive it from the data.
+   */
+  yDomain?: readonly [number, number]
+  /** Target y tick count. Default `5`. */
+  yTickCount?: number
+  /**
+   * Whether the y domain must contain zero. `LineChart` defaults to `false`
+   * (a 100-105 series should not be flattened against a phantom zero);
+   * `AreaChart` defaults to `true`, because a filled region measured from a
+   * non-zero baseline overstates its own magnitude.
+   */
+  includeZero?: boolean
+  /**
+   * Formats a data value for the tooltip, the direct labels and the table.
+   * Default: thousand-separated, with decimals only where the value has any.
+   *
+   * `formatPercent` takes PERCENT UNITS, not a 0-1 fraction (ADR-146 D11) —
+   * convert at the call site.
+   */
+  formatValue?: (value: number) => string
+  /** Formats a y-axis tick. Defaults to `formatValue`. */
+  formatYTick?: (value: number) => string
+  /** Plot width ÷ height. Default `16 / 5`, the kit's 459×108 plot. */
+  aspectRatio?: number
+  /** Reserved width of the y-label gutter. Default `var(--space-10)`. */
+  yGutterWidth?: string
+  /** Fill the region under each line. `AreaChart` sets this. */
+  area?: boolean
+  /** Which palette the slots index into. Default `'default'`. */
+  palette?: SeriesPalette
+  /**
+   * Point markers. `'auto'` (default) draws every point up to 12 x positions
+   * and only the meaningful ones (first, last, peak, hovered) beyond that — a
+   * dot per point on a 90-day series is noise, not information.
+   */
+  markers?: 'auto' | 'all' | 'none'
+  /**
+   * Selective value labels at each series' first, last and peak point
+   * (ADR-146 D10.3 — never a number on every point). Defaults to on for four
+   * or fewer series, off above that, where they would collide.
+   */
+  directLabels?: boolean
+  /**
+   * Render the legend. Defaults to on for two or more series and off for one
+   * (D10.1 / D10.2 — the title names a single series).
+   */
+  legend?: boolean
+  /** Header for the table view's category column. Default `'Point'`. */
+  categoryLabel?: string
+  /** Accessible name for the plot. Defaults to `title`. */
+  ariaLabel?: string
+  /** Notified when the hovered / focused x index changes. `null` on leave. */
+  onHoverChange?: (index: number | null) => void
+  /** Optional className on the frame. */
+  className?: string
+}
+
+/** `AreaChart` is `LineChart` with the fill on — the prop is not re-exposed. */
+export type AreaChartProps = Omit<LineChartProps, 'area'>
+
+interface Size {
+  readonly width: number
+  readonly height: number
+}
+
+const UNMEASURED: Size = { width: 0, height: 0 }
+
+/** Read a datum as a finite number, or `null` for "there is no datum here". */
+function datum(input: NumericInput): number | null {
+  return typeof input === 'number' && Number.isFinite(input) ? input : null
+}
+
+/**
+ * Thousand-separated, with decimals only where the value has any and only as
+ * many as its own magnitude needs (capped at 6).
+ *
+ * `formatNumber` alone defaults to zero decimals, which would render the tick
+ * ladder 0, 0.25, 0.5, 0.75, 1 as "0, 0, 1, 1, 1" — five labels, three lies.
+ */
+function defaultFormat(input: number): string {
+  if (!Number.isFinite(input)) return formatNumber(Number.NaN)
+  if (Number.isInteger(input)) return formatNumber(input)
+  const magnitude = Math.floor(Math.log10(Math.abs(input)))
+  return formatNumber(input, { decimals: Math.min(6, Math.max(1, 1 - magnitude)) })
+}
+
+/**
+ * One decimal precision for the WHOLE tick ladder.
+ *
+ * Formatting each tick on its own magnitude renders the 0..1 ladder as
+ * "1 / 0.75 / 0.5 / 0.25 / 0" — four different shapes in one column, which is
+ * exactly what `tabular-nums` exists to prevent. The ladder shares a step, so
+ * it shares a precision.
+ */
+function tickFormatter(ticks: readonly number[]): (value: number) => string {
+  let decimals = 0
+  for (const tick of ticks) {
+    // Exponential forms ("1e-7") carry no '.' and are left at 0 rather than
+    // being mis-read as a 7-place decimal.
+    const text = String(Math.abs(tick))
+    const dot = text.indexOf('.')
+    if (dot >= 0) {
+      decimals = Math.max(decimals, Math.min(6, text.length - dot - 1))
+    }
+  }
+  return (value: number): string => formatNumber(value, { decimals })
+}
+
+/**
+ * The widest label in the row, estimated, plus the gap it needs from its
+ * neighbour — the per-label extent `fitLabelCount` divides the plot by.
+ */
+function xLabelExtent(labels: readonly string[]): number {
+  let widest = 0
+  for (const label of labels) {
+    const width = estimateTextWidth(label, X_LABEL_FONT_PX)
+    if (width > widest) widest = width
+  }
+  return widest + X_LABEL_GAP_PX
+}
+
+/** A direct value label competing for room, before collisions are resolved. */
+interface LabelCandidate {
+  readonly key: string
+  readonly seriesKey: string
+  readonly index: number
+  readonly text: string
+  readonly x: number
+  readonly y: number
+  readonly anchor: 'start' | 'middle' | 'end'
+  /** peak 3 > last 2 > first 1. The survivor of a collision. */
+  readonly priority: number
+  readonly left: number
+  readonly right: number
+  readonly top: number
+  readonly bottom: number
+}
+
+/**
+ * Drop the direct value labels that would overlap another one, lowest
+ * priority first.
+ *
+ * ADR-146 D10.3 makes direct labels SELECTIVE by design — first, last and
+ * peak, never every point — so dropping a colliding one is the contract
+ * working, not a compromise. What is NOT acceptable is what shipped: two
+ * labels painted over each other. Measured in Chromium on AreaChart's
+ * "Spend, filled" demo, "$17,460" and "$17,120" overlapped by 19.6 x 11.8px
+ * and rendered as "$17,46O$17,120".
+ *
+ * Priority is peak > last > first: the peak is the only one of the three that
+ * says something the axis cannot, and the last is the value a reader looks
+ * for next. Ties break on input order, so the result is deterministic and the
+ * same series wins twice rather than flickering between renders.
+ *
+ * Boxes are estimated, not measured — see `estimateTextWidth` for why, and
+ * why the estimate rounds up.
+ */
+function resolveLabelCollisions(
+  candidates: readonly LabelCandidate[],
+): Set<string> {
+  const ranked = [...candidates].sort((a, b) => b.priority - a.priority)
+  const kept: LabelCandidate[] = []
+  const keys = new Set<string>()
+
+  for (const candidate of ranked) {
+    let clear = true
+    for (const other of kept) {
+      const overlapX =
+        Math.min(candidate.right, other.right) -
+        Math.max(candidate.left, other.left)
+      const overlapY =
+        Math.min(candidate.bottom, other.bottom) -
+        Math.max(candidate.top, other.top)
+      if (overlapX > 0 && overlapY > 0) {
+        clear = false
+        break
+      }
+    }
+    if (clear) {
+      kept.push(candidate)
+      keys.add(candidate.key)
+    }
+  }
+  return keys
+}
+
+/**
+ * Measure a box, and keep measuring it. Returns `0 × 0` until the first
+ * measurement lands (and in any environment without `ResizeObserver`, jsdom
+ * included) — callers then fall back to the nominal plot size, whose aspect
+ * ratio matches the box, so the first paint is right and the second is exact.
+ */
+function usePlotSize(node: HTMLDivElement | null): Size {
+  const [size, setSize] = useState<Size>(UNMEASURED)
+
+  useLayoutEffect(() => {
+    if (node === null) return
+
+    const measure = () => {
+      const next: Size = { width: node.clientWidth, height: node.clientHeight }
+      setSize((prev) =>
+        prev.width === next.width && prev.height === next.height ? prev : next,
+      )
+    }
+
+    measure()
+    if (typeof ResizeObserver === 'undefined') return
+
+    const observer = new ResizeObserver(measure)
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [node])
+
+  return size
+}
+
+/**
+ * Split a series into the runs of consecutive plottable points, so a gap
+ * breaks the line instead of being interpolated across.
+ *
+ * A run of one point is kept: `linePath` renders it as a zero-length segment,
+ * which with a round cap paints as a dot. Dropping it would make a lone datum
+ * between two gaps silently invisible.
+ */
+function segmentsOf(
+  values: readonly NumericInput[],
+  count: number,
+  xAt: (index: number) => number,
+  yAt: (value: number) => number,
+): Point[][] {
+  const segments: Point[][] = []
+  let run: Point[] = []
+
+  for (let i = 0; i < count; i++) {
+    const value = datum(values[i])
+    if (value === null) {
+      if (run.length > 0) segments.push(run)
+      run = []
+      continue
+    }
+    run.push({ x: xAt(i), y: yAt(value) })
+  }
+  if (run.length > 0) segments.push(run)
+
+  return segments
+}
+
+export function LineChart({
+  series,
+  xLabels,
+  title,
+  subtitle,
+  action,
+  state = 'loaded',
+  emptyMessage,
+  errorMessage,
+  onRetry,
+  yDomain,
+  yTickCount = 5,
+  includeZero = false,
+  formatValue = defaultFormat,
+  formatYTick,
+  aspectRatio = 16 / 5,
+  yGutterWidth,
+  area = false,
+  palette = 'default',
+  markers = 'auto',
+  directLabels,
+  legend,
+  categoryLabel = 'Point',
+  ariaLabel,
+  onHoverChange,
+  className,
+}: LineChartProps) {
+  // A CALLBACK ref: ChartFrame renders `children` only in the `loaded` state
+  // and swaps the plot out for the table view, so this box unmounts and
+  // remounts. A `useRef` + `[ref]` effect binds once and never rebinds, which
+  // would leave a chart that started in `loading` (the normal async path)
+  // permanently unmeasured and falling back to the nominal size.
+  const [plotNode, setPlotNode] = useState<HTMLDivElement | null>(null)
+  const measured = usePlotSize(plotNode)
+  // Document-global ids. Without this suffix, two charts on one page share a
+  // gradient id and both paint the first chart's colours.
+  const uid = useId().replace(/:/g, '')
+
+  const hoveredRef = useRef<number | null>(null)
+  const [hovered, setHovered] = useState<number | null>(null)
+
+  /**
+   * How many x POSITIONS the plot has: the longest of the label row and
+   * every series.
+   *
+   * Deriving this from `xLabels.length` alone silently discarded every value
+   * past the last label — it never entered the y domain, never drew a mark,
+   * and never reached the table view either, so a 30-day series arriving
+   * with 7 labels lost 23 points with typecheck, lint and every test green.
+   * The label list describes the axis; it does not define the data.
+   */
+  const count = useMemo(() => {
+    let longest = xLabels.length
+    for (const entry of series) {
+      if (entry.values.length > longest) longest = entry.values.length
+    }
+    return longest
+  }, [xLabels, series])
+
+  /**
+   * One label per POSITION, so index i of this list always names position i.
+   *
+   * A position past the caller's labels gets `''` rather than being dropped:
+   * dropping it would slide every later label onto the wrong point, which is
+   * the same lie in a quieter form.
+   */
+  const positionLabels = useMemo(
+    () => Array.from({ length: count }, (_, index) => xLabels[index] ?? ''),
+    [count, xLabels],
+  )
+
+  const ratio = aspectRatio > 0 ? aspectRatio : 1
+  const width = measured.width > 0 ? measured.width : NOMINAL_WIDTH
+  const height = measured.height > 0 ? measured.height : NOMINAL_WIDTH / ratio
+
+  const geometry = useMemo(() => {
+    let min = Number.POSITIVE_INFINITY
+    let max = Number.NEGATIVE_INFINITY
+    let finiteCount = 0
+
+    for (const entry of series) {
+      for (let i = 0; i < count; i++) {
+        const value = datum(entry.values[i])
+        if (value === null) continue
+        finiteCount++
+        if (value < min) min = value
+        if (value > max) max = value
+      }
+    }
+
+    if (finiteCount === 0) {
+      min = 0
+      max = 0
+    }
+    if (includeZero) {
+      min = Math.min(min, 0)
+      max = Math.max(max, 0)
+    }
+
+    const extent: readonly [number, number] = yDomain ?? [min, max]
+    // The DRAWN domain is the rounded-out tick range, not the raw extent, so
+    // the gridlines land on round numbers and the axis labels are the truth.
+    //
+    // The count is FITTED to the plot's measured height, not taken as given:
+    // `niceTicks` is allowed to overshoot its target (it rounds the domain
+    // outward), and a fixed five-tick ladder in a short panel stacks its
+    // labels on top of each other — measured at 390, every adjacent pair of
+    // "$50,000 / $40,000 / …" overlapped. A short plot gets a shorter ladder.
+    const ticks = fitTicks(
+      extent[0],
+      extent[1],
+      height,
+      Y_TICK_MIN_SPACING_PX,
+      yTickCount,
+    )
+    const lo = ticks[0] ?? 0
+    const hi = ticks[ticks.length - 1] ?? 0
+
+    // A flat domain maps every value to the middle of the range, which is
+    // exactly where ChartFrame puts a lone tick label. Axis and data agree.
+    const yAt = linearScale([lo, hi], [height, 0])
+    const step = count > 1 ? width / (count - 1) : width
+    const xAt = (index: number): number => (count > 1 ? index * step : width / 2)
+
+    return { finiteCount, lo, hi, ticks, yAt, xAt, step }
+  }, [series, count, includeZero, yDomain, yTickCount, width, height])
+
+  const { finiteCount, lo, hi, ticks, yAt, xAt, step } = geometry
+
+  // A caller's own tick formatter wins; so does a caller's value formatter.
+  // The uniform ladder applies only to the built-in default, which formats
+  // per value and therefore ragged.
+  const formatTick =
+    formatYTick ?? (formatValue === defaultFormat ? tickFormatter(ticks) : formatValue)
+
+  const effectiveState: ChartFrameState =
+    state === 'loaded' && (count === 0 || finiteCount === 0) ? 'empty' : state
+
+  /**
+   * The hover index, clamped to the CURRENT data. New data can be shorter
+   * than the old — a range switch from 30 days to 7 — and a stale index would
+   * otherwise read past the end of every series and paint a readout of
+   * nothing while the band sat outside the plot.
+   */
+  const active = hovered !== null && hovered >= 0 && hovered < count ? hovered : null
+
+  const showLegend = legend ?? series.length >= 2
+  const showDirectLabels = directLabels ?? series.length <= 4
+  const drawEveryMarker =
+    markers === 'all' || (markers === 'auto' && count <= AUTO_MARKER_LIMIT)
+
+  /** Zero rule position, when zero sits strictly inside the drawn domain. */
+  const zeroY = lo < 0 && hi > 0 ? yAt(0) : null
+
+  /**
+   * Where an area's fill CLOSES TO — zero, not the floor of the plot.
+   *
+   * `AreaChart` already forces zero into the domain because "a filled region
+   * measured from a non-zero baseline overstates its own magnitude". With
+   * negative data that reasoning cuts the other way and the plot floor is no
+   * longer zero: closing a −10 point down to a −40 floor paints a tall block
+   * of ink for a small negative number, which is the same lie in the opposite
+   * direction. Clamped into the plot, so an all-positive domain still closes
+   * on the floor (`yAt(0) === height`) and an all-negative one closes on the
+   * ceiling — in both cases exactly where the zero line is.
+   */
+  const areaBaseline = Math.max(0, Math.min(height, yAt(0)))
+
+  const setHoverIndex = useCallback(
+    (next: number | null) => {
+      // The ref, not the state, is the comparison: this runs from a pointer
+      // handler on every mouse move, and a side effect inside a state updater
+      // would fire twice under StrictMode.
+      if (hoveredRef.current === next) return
+      hoveredRef.current = next
+      setHovered(next)
+      onHoverChange?.(next)
+    },
+    [onHoverChange],
+  )
+
+  const handlePointerMove = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (count === 0) return
+      const box = event.currentTarget.getBoundingClientRect()
+      if (box.width <= 0) return
+      const position = ((event.clientX - box.left) / box.width) * Math.max(1, count - 1)
+      setHoverIndex(Math.max(0, Math.min(count - 1, Math.round(position))))
+    },
+    [count, setHoverIndex],
+  )
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (count === 0) return
+      // Arrowing into an unhovered chart lands on the current index rather
+      // than stepping past it, so the first keypress always reveals a point.
+      const current = active ?? 0
+      const stepped = (delta: number): number =>
+        active === null ? current : Math.max(0, Math.min(count - 1, current + delta))
+
+      if (event.key === 'ArrowRight') setHoverIndex(stepped(1))
+      else if (event.key === 'ArrowLeft') setHoverIndex(stepped(-1))
+      else if (event.key === 'Home') setHoverIndex(0)
+      else if (event.key === 'End') setHoverIndex(count - 1)
+      else if (event.key === 'Escape') setHoverIndex(null)
+      else return
+
+      event.preventDefault()
+    },
+    [count, active, setHoverIndex],
+  )
+
+  /** Per-series draw data. One pass, reused by every layer below. */
+  const drawn = series.map((entry, index) => {
+    const points: (Point | null)[] = []
+    let firstIndex: number | null = null
+    let lastIndex: number | null = null
+    let peakIndex: number | null = null
+    let peak = Number.NEGATIVE_INFINITY
+
+    for (let i = 0; i < count; i++) {
+      const value = datum(entry.values[i])
+      if (value === null) {
+        points.push(null)
+        continue
+      }
+      points.push({ x: xAt(i), y: yAt(value) })
+      if (firstIndex === null) firstIndex = i
+      lastIndex = i
+      if (value > peak) {
+        peak = value
+        peakIndex = i
+      }
+    }
+
+    return {
+      series: entry,
+      color: slotColor(entry.slot, palette),
+      gradientId: `lovett-chart-area-${uid}-${index}`,
+      segments: segmentsOf(entry.values, count, xAt, yAt),
+      points,
+      firstIndex,
+      lastIndex,
+      peakIndex,
+    }
+  })
+
+  /**
+   * The direct value labels, as boxes, BEFORE any of them is drawn.
+   *
+   * They have to be resolved together rather than per series: the overlap
+   * that shipped was between two different series' labels, so a per-series
+   * pass cannot see it. Anchoring matches the `<text>` below exactly — a box
+   * computed from a different anchor than the one that renders is a
+   * collision check of something that is not on screen.
+   */
+  const valueLabels: LabelCandidate[] = !showDirectLabels
+    ? []
+    : drawn.flatMap((entry): LabelCandidate[] => {
+        // Peak first, so a point that is BOTH the peak and the last is
+        // ranked as the peak. De-duplicated by index, as before.
+        const marks: readonly { index: number | null; priority: number }[] = [
+          { index: entry.peakIndex, priority: 3 },
+          { index: entry.lastIndex, priority: 2 },
+          { index: entry.firstIndex, priority: 1 },
+        ]
+        const seen = new Set<number>()
+        const out: LabelCandidate[] = []
+
+        for (const mark of marks) {
+          const index = mark.index
+          if (index === null || seen.has(index)) continue
+          seen.add(index)
+
+          const point = entry.points[index]
+          const value = datum(entry.series.values[index])
+          if (point === null || point === undefined || value === null) continue
+
+          const text = formatValue(value)
+          // Above the marker by default, BELOW it when the glyphs would not
+          // fit. A peak lands at y = 0 whenever the tick ladder rounds tight
+          // to the data, and the plot SVG is overflow: visible, so an
+          // unflipped label paints outside the plot and over the legend.
+          const above = point.y - LABEL_OFFSET
+          const y =
+            above - LABEL_CAP >= 0 ? above : point.y + LABEL_OFFSET + LABEL_CAP
+          const anchor: LabelCandidate['anchor'] =
+            index === 0 ? 'start' : index === count - 1 ? 'end' : 'middle'
+
+          const textWidth = estimateTextWidth(text, VALUE_LABEL_FONT_PX)
+          const boxLeft =
+            anchor === 'start'
+              ? point.x
+              : anchor === 'end'
+                ? point.x - textWidth
+                : point.x - textWidth / 2
+
+          out.push({
+            key: `${entry.series.key}-label-${index}`,
+            seriesKey: entry.series.key,
+            index,
+            text,
+            x: point.x,
+            y,
+            anchor,
+            priority: mark.priority,
+            // `y` is the BASELINE, so the box runs up from it. Padded on
+            // every side, because two labels a hairline apart still read as
+            // one word.
+            left: boxLeft - VALUE_LABEL_PAD_PX,
+            right: boxLeft + textWidth + VALUE_LABEL_PAD_PX,
+            top: y - VALUE_LABEL_BOX_PX,
+            bottom: y + VALUE_LABEL_PAD_PX,
+          })
+        }
+        return out
+      })
+
+  const drawnValueLabels = resolveLabelCollisions(valueLabels)
+
+  const legendItems: ChartLegendItem[] = series.map((entry) => ({
+    key: entry.key,
+    label: entry.label,
+    slot: entry.slot,
+  }))
+
+  const tooltipRows: ChartTooltipRow[] = series.map((entry) => {
+    const value = active === null ? null : datum(entry.values[active])
+    return {
+      key: entry.key,
+      label: entry.label,
+      value: value === null ? NO_VALUE : formatValue(value),
+      // A swatch on a single-series readout is noise — the title names it.
+      ...(series.length > 1 ? { slot: entry.slot } : {}),
+    }
+  })
+
+  const hoverX = active === null ? 0 : xAt(active)
+  const hoverYs =
+    active === null
+      ? []
+      : drawn.flatMap((entry) => {
+          const point = entry.points[active]
+          return point === null || point === undefined ? [] : [point.y]
+        })
+  const hoverY =
+    hoverYs.length > 0
+      ? hoverYs.reduce((total, y) => total + y, 0) / hoverYs.length
+      : height / 2
+
+  const bandWidth = Math.max(MIN_BAND, step * BAND_STEP_RATIO)
+  const bandLeft = Math.max(
+    0,
+    Math.min(hoverX - bandWidth / 2, Math.max(0, width - bandWidth)),
+  )
+
+  /**
+   * MEMOISED, and the memo is load-bearing rather than tidy. This formats
+   * every datum of every series — 2,007 `formatValue` calls for a 1,000-point
+   * 2-series chart — and `hovered` is component state, so without the memo a
+   * single pointermove re-formatted the entire dataset. Measured before the
+   * memo: 26.8ms per render at 1,000 points, 315ms at 10,000, of which ~96%
+   * was the formatter (the same chart with `formatValue={String}` renders in
+   * 1.2ms). That is under 60fps from one chart, on hover, for a table that is
+   * usually not even on screen. `BarChart` already memoised its equivalent;
+   * the asymmetry was an oversight, not a design.
+   */
+  const table: ChartTableData = useMemo(
+    () => ({
+      columns: [categoryLabel, ...series.map((entry) => entry.label)],
+      // One row per POSITION, not per label: the table is the chart's
+      // accessible representation, so a value the plot draws must be readable
+      // here even where the caller supplied no label for it.
+      rows: positionLabels.map((label, index): ChartTableRow => {
+        const cells = series.map((entry) => {
+          const value = datum(entry.values[index])
+          return value === null ? NO_VALUE : formatValue(value)
+        })
+        return { key: `${index}-${label}`, cells: [label, ...cells] }
+      }),
+      ...(title !== undefined ? { caption: title } : {}),
+    }),
+    [categoryLabel, series, positionLabels, formatValue, title],
+  )
+
+  /**
+   * What the axis ROW shows, and WHERE each of those labels sits.
+   *
+   * Two decisions, both measured rather than fixed:
+   *   • how many — the plot's width divided by the widest label, capped at
+   *     `MAX_X_LABELS`;
+   *   • which — a uniform stride (`strideIndices`), so the gaps are equal.
+   *     The predecessor rounded a fraction and produced 0, 2, 3, 5, 6, 8, 9,
+   *     11 over 12 weeks: an axis that reads as irregular data.
+   *
+   * The fraction is the label's real position on the plot, which is what
+   * `ChartFrame` centres it on. The table below still carries every position.
+   */
+  const xCapacity = fitLabelCount(
+    width,
+    xLabelExtent(positionLabels),
+    MAX_X_LABELS,
+    // 0, so "not even two fit" is answerable instead of being clamped away.
+    0,
+  )
+  // A plot 26px wide holds no 32px label, and two of them overlapped by 10px.
+  // Below two, the row draws NOTHING and keeps its reserved height — the
+  // panel does not resize, and the table view still carries every position.
+  const axisIndices =
+    count > 1 && xCapacity < 2
+      ? []
+      : strideIndices(count, Math.max(2, xCapacity))
+  const axisLabels = axisIndices.map((index) => positionLabels[index] ?? '')
+  const axisFractions = axisIndices.map((index) =>
+    count > 1 ? index / (count - 1) : 0.5,
+  )
+
+  // An unlabelled position has no title to show, so the readout carries the
+  // values alone rather than a card with an empty heading.
+  const labelAt = active === null ? '' : (positionLabels[active] ?? '')
+  const hoveredLabel = labelAt === '' ? undefined : labelAt
+  const liveText =
+    active === null
+      ? ''
+      : `${hoveredLabel ?? ''}: ${tooltipRows
+          .map((row) => `${row.label} ${row.value}`)
+          .join(', ')}`
+
+  return (
+    <ChartFrame
+      state={effectiveState}
+      action={action}
+      legend={
+        showLegend ? (
+          <ChartLegend
+            items={legendItems}
+            palette={palette}
+            activeKey={null}
+            label={title === undefined ? 'Chart legend' : `${title} legend`}
+          />
+        ) : undefined
+      }
+      yLabels={[...ticks].reverse().map((tick) => formatTick(tick))}
+      xLabels={axisLabels}
+      xLabelFractions={axisFractions}
+      aspectRatio={aspectRatio}
+      table={table}
+      {...(title !== undefined ? { title } : {})}
+      {...(subtitle !== undefined ? { subtitle } : {})}
+      {...(emptyMessage !== undefined ? { emptyMessage } : {})}
+      {...(errorMessage !== undefined ? { errorMessage } : {})}
+      {...(onRetry !== undefined ? { onRetry } : {})}
+      {...(yGutterWidth !== undefined ? { yGutterWidth } : {})}
+      {...(className !== undefined ? { className } : {})}
+    >
+      <div
+        ref={setPlotNode}
+        role="group"
+        tabIndex={0}
+        aria-label={ariaLabel ?? title ?? 'Chart'}
+        onPointerMove={handlePointerMove}
+        onPointerLeave={() => setHoverIndex(null)}
+        onBlur={() => setHoverIndex(null)}
+        onKeyDown={handleKeyDown}
+        className={cn(
+          'absolute inset-0 cursor-crosshair',
+          'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+        )}
+      >
+        {/* The hover BAND (ADR-146 D9), not a 1px crosshair: full plot height,
+            about one x-step wide, snapped to the nearest x, behind the marks.
+            --chart-band already carries its alpha; a second one would be
+            invalid CSS that the browser silently discards. It stays mounted
+            and toggles visibility, so showing it costs no layout. */}
+        <div
+          aria-hidden="true"
+          className={cn(
+            'pointer-events-none absolute top-0 bottom-0 left-0',
+            'motion-safe:transition-transform motion-safe:duration-[var(--dur-fast)]',
+            'motion-safe:ease-[var(--ease-out)]',
+          )}
+          style={{
+            width: bandWidth,
+            transform: `translate3d(${bandLeft}px, 0, 0)`,
+            background: 'rgb(var(--chart-band))',
+            borderRadius: 'var(--radius-xs)',
+            visibility: active === null ? 'hidden' : 'visible',
+          }}
+        />
+
+        <svg
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 h-full w-full"
+          viewBox={`0 0 ${width} ${height}`}
+          style={{ overflow: 'visible' }}
+        >
+          {area && (
+            <defs>
+              {drawn.map((entry) => (
+                <linearGradient
+                  key={entry.gradientId}
+                  id={entry.gradientId}
+                  x1="0"
+                  y1="0"
+                  x2="0"
+                  y2="1"
+                >
+                  {/* stop-opacity multiplies the stop colour's own alpha, so
+                      0.18 → 0 is the specified ramp without doing string
+                      surgery on a token expression to inject an alpha. */}
+                  <stop offset="0%" stopColor={entry.color} stopOpacity={0.18} />
+                  <stop offset="100%" stopColor={entry.color} stopOpacity={0} />
+                </linearGradient>
+              ))}
+            </defs>
+          )}
+
+          {area &&
+            drawn.map((entry) =>
+              entry.segments.map((segment, segmentIndex) => {
+                const d = areaPath(segment, areaBaseline)
+                // A one-point run has no area; its dot still draws below.
+                if (d === '') return null
+                return (
+                  <path
+                    key={`${entry.series.key}-area-${segmentIndex}`}
+                    d={d}
+                    className="motion-safe:transition-[d] motion-safe:duration-[var(--dur-base)] motion-safe:ease-[var(--ease-out)]"
+                    style={{ fill: `url(#${entry.gradientId})` }}
+                  />
+                )
+              }),
+            )}
+
+          {/* The zero rule. Drawn only when zero sits strictly inside the
+              domain — otherwise the frame's bottom baseline already is it,
+              and two dark rules would stack. It sits ABOVE the area fill and
+              below the lines: an axis rule painted under a translucent fill
+              is dimmed by it, and the fill is what it delimits. */}
+          {zeroY !== null && (
+            <line
+              x1={0}
+              x2={width}
+              y1={zeroY}
+              y2={zeroY}
+              strokeWidth={1}
+              style={{ stroke: 'rgb(var(--chart-axis))' }}
+            />
+          )}
+
+          {drawn.map((entry) =>
+            entry.segments.map((segment, segmentIndex) => (
+              <path
+                key={`${entry.series.key}-line-${segmentIndex}`}
+                d={linePath(segment)}
+                fill="none"
+                strokeWidth={STROKE}
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="motion-safe:transition-[d] motion-safe:duration-[var(--dur-base)] motion-safe:ease-[var(--ease-out)]"
+                style={{
+                  stroke: entry.color,
+                  // Very subtle — enough to lift the series off the
+                  // gridlines, not enough to read as a glow. It is the
+                  // SHADOW token, not the axis token: --chart-axis is
+                  // `255 255 255 / 0.22` in the dark theme, so using it here
+                  // painted a white halo under every line on a dark card —
+                  // the opposite of a shadow, in the one theme where nobody
+                  // would have caught it from the source. --shadow-sm is a
+                  // whole `<x> <y> <blur> <color>` value, which is exactly
+                  // drop-shadow()'s grammar, and it is dark in both themes.
+                  filter: 'drop-shadow(var(--shadow-sm))',
+                }}
+              />
+            )),
+          )}
+
+          {markers !== 'none' &&
+            drawn.map((entry) =>
+              entry.points.map((point, index) => {
+                if (point === null) return null
+                const isHovered = active === index
+                const isEdge =
+                  index === entry.firstIndex || index === entry.lastIndex
+                const isPeak = index === entry.peakIndex
+                // Beyond the auto limit only the meaningful points are drawn:
+                // a dot on every one of 90 days is noise, not information.
+                if (!drawEveryMarker && !isHovered && !isEdge && !isPeak) {
+                  return null
+                }
+
+                return (
+                  <circle
+                    key={`${entry.series.key}-dot-${index}`}
+                    cx={point.x}
+                    cy={point.y}
+                    r={MARKER_RADIUS}
+                    strokeWidth={MARKER_RING}
+                    className="motion-safe:transition-[cx,cy] motion-safe:duration-[var(--dur-base)] motion-safe:ease-[var(--ease-out)]"
+                    style={{
+                      fill: entry.color,
+                      // The ring is the PANEL surface, which is what keeps a
+                      // filled dot legible on top of the area fill.
+                      stroke: 'rgb(var(--surface-card))',
+                    }}
+                  />
+                )
+              }),
+            )}
+
+          {/* Direct value labels. Selective by contract (D10.3): first,
+              last and peak only, de-duplicated, and then only the ones that
+              do not land on top of another — across ALL series, since that
+              is where the overlap that shipped came from. The hovered point
+              is covered by the tooltip, so it gets no second label competing
+              with it. */}
+          {valueLabels
+            .filter((label) => drawnValueLabels.has(label.key))
+            .map((label) => (
+              <text
+                key={label.key}
+                x={label.x}
+                y={label.y}
+                textAnchor={label.anchor}
+                className="text-[12px] font-semibold tabular-nums"
+                // Text wears text tokens, never the series colour (D10.4).
+                // The marker below it carries the identity.
+                style={{ fill: 'rgb(var(--text-secondary))' }}
+              >
+                {label.text}
+              </text>
+            ))}
+        </svg>
+
+        {active !== null && (
+          <ChartTooltip
+            x={hoverX}
+            y={hoverY}
+            plotWidth={width}
+            plotHeight={height}
+            rows={tooltipRows}
+            palette={palette}
+            {...(hoveredLabel !== undefined ? { title: hoveredLabel } : {})}
+          />
+        )}
+
+        {/* The keyboard reader's channel. The SVG is aria-hidden and the
+            table view is the chart's accessible representation, so this is
+            what announces where the arrow keys just landed. */}
+        <span aria-live="polite" className="sr-only">
+          {liveText}
+        </span>
+      </div>
+    </ChartFrame>
+  )
+}
+
+/**
+ * `AreaChart` — `LineChart` with the gradient region filled in.
+ *
+ * The only behavioural difference beyond the fill is `includeZero`, which
+ * defaults to `true` here: a filled area measured from a non-zero baseline
+ * overstates its own magnitude, which is the classic area-chart lie.
+ */
+export function AreaChart({ includeZero = true, ...props }: AreaChartProps) {
+  return <LineChart {...props} includeZero={includeZero} area />
+}