@lovett/ui 0.0.11 → 0.2.0

package/src/bar-chart.tsx

@@ -0,0 +1,1214 @@
+/**
+ * BarChart — vertical or horizontal bars, monochrome by default.
+ *
+ * Promoted in ADR-146 D5 (chart layer).
+ *
+ * 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).
+ *   TODAY (0 — gate NOT MET). Nothing in product code renders it. The admin
+ *   analytics tab plots its trend with `AreaChart` and its usage mix with
+ *   `RankedBars`; neither is this primitive.
+ *   PLANNED: a keywords volume-by-term panel (`lenses/keywords/detail/`) and
+ *   an admin volume-by-period panel. `design-system/spec/shell-charts.tsx`'s
+ *   ranked-bar, split-bar and column specimens retire onto it under ADR-146
+ *   D13 (`promote-spec-charts.md`), but those are specimens, not consumers.
+ *   Tracked in `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * THE ONE IDEA THIS PRIMITIVE EXISTS TO HOLD (ADR-146 D7)
+ * -------------------------------------------------------
+ * **The default is monochrome.** Every bar renders in
+ * `rgb(var(--accent) / 0.14)` and exactly ONE bar — the selected one, the
+ * peak, or the current period — renders at full `rgb(var(--accent))`. No
+ * series token is involved, and no palette is needed. That is "the accent
+ * earns impact from scarcity" applied to data, and it is why most of our
+ * charts need no series colour at all.
+ *
+ * A palette enters only when the chart genuinely encodes **more than one
+ * entity** — that is what `series` means, and it is the only thing that turns
+ * this chart polychrome. Colouring nominal bars by their own value is
+ * forbidden: it spends the identity channel re-encoding what bar length
+ * already shows. There is deliberately no prop for it.
+ *
+ * Colour follows the ENTITY, never its rank (D7): `BarChartSeries.slot` is
+ * required rather than derived from array position, so filtering a series out
+ * cannot repaint the survivors.
+ *
+ * GEOMETRY (Metoric spec §6.1 — extracted measurements, not eyeballed)
+ * --------------------------------------------------------------------
+ *   bar radius   `--radius-sm` (8px) on all four corners — a rounded BAR.
+ *                Not a pill (`--radius-full`) and not a circle.
+ *   bar gap      `--space-4` (16px) at full size, scaling down with the
+ *                count: the gap is capped at a share of the step, so 4 bars
+ *                get 16px and 30 bars get a hairline rather than fusing.
+ *   stack seam   a 2px gap between adjacent stacked segments, painted in the
+ *                panel colour so they read as separate marks.
+ *
+ * THE EDGE CASES, EACH A NAMED TEST (ADR-146 acceptance criterion 8)
+ * ------------------------------------------------------------------
+ *   • **no data**        → the frame's `empty` state. So does data whose
+ *                          every value is ABSENT: nothing was measured, and
+ *                          "every value is zero" would be a different claim.
+ *   • **an absent value**→ a datum with no `value` (or `undefined` / `NaN`)
+ *                          was never measured, which is NOT the same fact as
+ *                          a measured zero. It draws no bar at all, reads
+ *                          `—` in the readout, the accessible name and the
+ *                          table, is excluded from the domain, and can never
+ *                          win the `peak` emphasis. A zero-length bar on the
+ *                          baseline would be indistinguishable from a real
+ *                          zero, which is the `LineChart` gap defect (its
+ *                          `NO_VALUE`) in bar form.
+ *   • **one bar**        → a legal chart; the single band takes the full
+ *                          width less its padding.
+ *   • **all zero**       → the baseline and gridlines stay (unlabelled — a
+ *                          single nice tick at zero would be drawn at
+ *                          mid-height, which is a lie), the gutter keeps its
+ *                          width so the plot does not resize, and an in-plot
+ *                          message says so. Invisible bars on a blank panel
+ *                          look like a broken chart, not like zero. Because
+ *                          the rules stay live under it, that message is a
+ *                          `PlotNotice` — opaque-backed, so a gridline cannot
+ *                          run through the sentence. Same for "too dense".
+ *   • **negative values**→ bars descend from the y=0 baseline, and a darker
+ *                          `--chart-axis` zero rule is drawn where the
+ *                          baseline actually is. They are NOT clamped to
+ *                          zero: a clamp is a chart that lies. The ONE
+ *                          exception is `mode="stacked"`, where a running sum
+ *                          has no honest negative — those are clamped, and
+ *                          the primitive warns rather than doing it quietly.
+ *   • **very many bars** → below a legible bar width we say "too dense" and
+ *                          `console.warn` once, rather than painting mush.
+ *                          The table view stays reachable.
+ *
+ * INTERACTION (D9) — part of the primitive, not the caller's problem
+ * ------------------------------------------------------------------
+ * The hit target is the whole **band column** (bar + gap, full plot depth),
+ * so it is always at least as large as the bar it selects — which is what
+ * makes a 4px bar usable. Hover or focus lifts a `--chart-band` column behind
+ * the marks and opens `ChartTooltip`; grouped and stacked charts read out
+ * every series at that category in one card. Bars grow with `--dur-base` /
+ * `--ease-out` (never `--ease-spring` on a data change), and
+ * `prefers-reduced-motion` jumps to the final state.
+ *
+ * Token discipline: every colour is `rgb(var(--token))` — no literal, no
+ * constructed name. Series hues resolve through the frozen `SERIES` lookup in
+ * `lib/series.ts` (D8). `--chart-grid` / `--chart-axis` / `--chart-band`
+ * carry their own alpha and are consumed as `rgb(var(--chart-grid))`, NEVER
+ * with a second one. Every spacing and radius is a token; the only bare
+ * numbers are pixel geometry (a gap cap, a hairline, a legibility floor),
+ * which cannot read a custom property — each names its token equivalent.
+ */
+
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react'
+
+import { cn } from './lib/utils'
+import {
+  bandScale,
+  estimateTextWidth,
+  fitTickCount,
+  fitTicks,
+  linearScale,
+  normalizeToMax,
+  stackTotals,
+} from './lib/chart'
+import { slotColor, type ChartSlot, type SeriesPalette } from './lib/series'
+import {
+  ChartFrame,
+  X_LABEL_FONT_PX,
+  Y_TICK_MIN_SPACING_PX,
+  type ChartFrameProps,
+  type ChartFrameState,
+  type ChartTableData,
+  type ChartTableRow,
+} from './chart-frame'
+import { ChartLegend, type ChartLegendItem } from './chart-legend'
+import { ChartTooltip, type ChartTooltipRow } from './chart-tooltip'
+import { formatNumber } from './format'
+
+/* ── public types ────────────────────────────────────────────────────── */
+
+/** One category — one band on the categorical axis. */
+export interface BarChartDatum {
+  /**
+   * Stable identity key. The React key, the `onSelect` payload, and what
+   * `selectedKey` matches. Never the array index: colour and emphasis follow
+   * the entity, not its rank (ADR-146 D7).
+   */
+  key: string
+  /** The category's axis label. */
+  label: string
+  /**
+   * The bar's value in monochrome mode. Ignored when `series` is set.
+   *
+   * Omitted, `undefined` or `NaN` means **not measured**, which is a
+   * different fact from a measured `0`: no bar is drawn, and every readout
+   * of it says `—`. Pass `0` for a real zero.
+   */
+  value?: number
+  /**
+   * Grouped / stacked mode: one value per entry in `series`, in the SAME
+   * order.
+   *
+   * A missing or short entry is **absent, not zero** — no segment is drawn
+   * and it reads `—` in the readout, the accessible name and the table, the
+   * same as `value`. In `stacked` mode an absent segment contributes nothing
+   * to the running total (arithmetically what a zero would, but it is not
+   * REPORTED as a zero anywhere); the stack simply carries one fewer
+   * segment.
+   */
+  values?: readonly number[]
+}
+
+/** One entity — the only thing that makes this chart polychrome (D7). */
+export interface BarChartSeries {
+  /** Stable entity key. The React key and the legend's identity. */
+  key: string
+  /** The entity's name. Always rendered in the legend and the readout. */
+  label: string
+  /**
+   * Palette slot, or `'other'` for the folded remainder.
+   *
+   * **Required, and assigned from the stable entity key** — never from the
+   * array index after a filter, which would repaint every survivor when one
+   * series is removed (ADR-146 D7).
+   */
+  slot: ChartSlot
+}
+
+/** Bars up the value axis, or along it. */
+export type BarChartOrientation = 'vertical' | 'horizontal'
+
+/** How multiple series share a category band. */
+export type BarChartMode = 'grouped' | 'stacked'
+
+/**
+ * Which single bar wears the full accent in monochrome mode (D7).
+ * `selectedKey` overrides this when it names a datum.
+ */
+export type BarChartEmphasis = 'peak' | 'last' | 'none'
+
+export interface BarChartProps {
+  /** The categories, in draw order. */
+  data: readonly BarChartDatum[]
+  /**
+   * The entities. Omit for the monochrome default — which is the right
+   * answer for almost every bar chart we draw. Supplying this is a claim
+   * that the chart encodes more than one entity.
+   */
+  series?: readonly BarChartSeries[]
+  /** How `series` share a band. Default `'grouped'`. Ignored without `series`. */
+  mode?: BarChartMode
+  /** Bars up, or bars along. Default `'vertical'`. */
+  orientation?: BarChartOrientation
+  /** Which palette `slot` indexes into. Default `'default'`. */
+  palette?: SeriesPalette
+  /** Which bar wears the full accent. Default `'peak'`. Monochrome only. */
+  emphasis?: BarChartEmphasis
+  /**
+   * The selected datum's `key`. Overrides `emphasis` when it matches a datum;
+   * a key that matches nothing simply emphasizes nothing (it does not fall
+   * back to the peak, which would make a failed lookup invisible).
+   */
+  selectedKey?: string | null
+  /** Makes each band a button, called with the datum's `key`. */
+  onSelect?: (key: string) => void
+  /**
+   * Draw the value axis — gridlines and tick labels. Default `true`.
+   * `false` is the kit's own bare `Data Plot`: bars normalised to the peak,
+   * no axis at all.
+   */
+  showAxis?: boolean
+  /**
+   * Target tick count for the value axis. Default `5`.
+   *
+   * A TARGET, and a ceiling — never a promise. The ladder is fitted to the
+   * plot that is actually on screen (`fitTicks`), so a short or narrow panel
+   * gets fewer ticks rather than a stack of overlapping labels, and no axis
+   * draws more than six however many are asked for.
+   */
+  tickCount?: number
+  /**
+   * Formats a value for the axis, the readout and the table. Default
+   * `formatNumber`. **`formatPercent` takes percent units, not a 0-1
+   * fraction** (ADR-146 D11) — convert at the call site.
+   */
+  formatValue?: (value: number) => string
+  /** Chart title. With no `series` this also names the single series (D10.2). */
+  title?: string
+  /** 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 data resolves to `'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
+  /**
+   * Plot width ÷ height. Default `16 / 5` vertical, `16 / 9` horizontal. A
+   * horizontal chart with many categories wants a taller ratio — pass one.
+   */
+  aspectRatio?: number
+  /**
+   * Header for the table's category column, and the accessible name of the
+   * categorical axis. Default `'Category'`.
+   */
+  categoryLabel?: string
+  /**
+   * Header for the table's measure column in monochrome mode. Default
+   * `'Value'`. Ignored when `series` is set — each series names its own.
+   */
+  valueLabel?: string
+  /**
+   * Width of the category-label gutter in horizontal orientation. A
+   * PROPORTION by default (`'30%'`) rather than a fixed length, so labels
+   * stay legible at every panel width; pass a token-derived length
+   * (`'var(--space-12)'`) for a fixed gutter.
+   */
+  categoryGutter?: string
+  /**
+   * Below this bar width (px) the chart says "too dense" instead of drawing.
+   * Default `4`. Bars thinner than this are mush, and mush that renders is
+   * worse than a chart that admits it cannot.
+   */
+  minBarSize?: number
+  /** Optional className on the frame panel. */
+  className?: string
+}
+
+/* ── geometry constants ──────────────────────────────────────────────── */
+/* Pixel arithmetic cannot read a CSS custom property, so these are numbers.
+   Each names the token it mirrors. */
+
+/** `--space-4` (16px): the gap between bars at full size (Metoric §6.1). */
+const GAP_FULL_PX = 16
+
+/** Floor, so a dense strip separates into bars instead of fusing into a block. */
+const GAP_MIN_PX = 2
+
+/** Cap the gap at this share of the step, which is what makes it scale down. */
+const GAP_MAX_RATIO = 0.35
+
+/** Gap between the bars WITHIN one group, as a share of the group's band. */
+const GROUP_GAP_RATIO = 0.12
+
+/**
+ * The seam between adjacent stacked segments — a hairline in the panel
+ * colour, the same family of value as the 1px gridline, doubled so it stays
+ * visible against two saturated fills.
+ */
+const STACK_SEAM = '2px'
+
+/** Height reserved for the horizontal chart's value-tick strip. */
+const TICK_STRIP_HEIGHT = 'var(--space-5)'
+
+/** Clear air between two labels on the horizontal value-tick strip. */
+const TICK_LABEL_GAP_PX = 12
+
+/** Monochrome: every bar. `--accent` is a bare triple, so this alpha is legal. */
+const BAR_REST = 'rgb(var(--accent) / 0.14)'
+
+/** Monochrome: the ONE emphasized bar. The whole point of D7. */
+const BAR_EMPHASIS = 'rgb(var(--accent))'
+
+/**
+ * What an absent value reads as, everywhere a number would go.
+ *
+ * The same em dash `LineChart` uses for a gap, for the same reason: a datum
+ * that was never measured is not a measurement of none, and printing "0" for
+ * it makes the two indistinguishable.
+ */
+const NO_VALUE = '—'
+
+/* ── density guard ───────────────────────────────────────────────────── */
+
+const WARNED = new Set<string>()
+
+/**
+ * Warn once per `key`, process-wide.
+ *
+ * The key is deliberately NOT the message: a chart re-renders on every hover
+ * and re-measures on every resize, and a message that carries a measured
+ * pixel value would defeat a message-keyed cache the first time the panel
+ * changed width.
+ */
+function warnOnce(key: string, message: string): void {
+  if (WARNED.has(key)) return
+  WARNED.add(key)
+  console.warn(message)
+}
+
+/* ── internals ───────────────────────────────────────────────────────── */
+
+/**
+ * Read a datum as a finite number, or `null` for "there is no measurement
+ * here" — `undefined`, `NaN` and `±Infinity` all mean absent.
+ *
+ * It used to fold all three onto `0`, which drew a zero-length bar and
+ * printed "0" in the tooltip, the accessible name and the table: a missing
+ * measurement reported as a measured zero.
+ */
+function num(value: number | undefined): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+/** Format a value, or the em dash when there is nothing to format. */
+function read(value: number | null | undefined, format: (v: number) => string): string {
+  return value === null || value === undefined ? NO_VALUE : format(value)
+}
+
+/** One drawn rectangle: a span along the value axis, in percent of the plot. */
+interface Span {
+  /** The edge nearer the value-axis origin (bottom, or left). */
+  readonly start: number
+  /** The far edge. */
+  readonly end: number
+}
+
+interface PlotMetrics {
+  /** Plot box size — what `ChartTooltip` clamps against. */
+  readonly plotWidth: number
+  readonly plotHeight: number
+  /** The bar region's box, relative to the plot box. */
+  readonly regionLeft: number
+  readonly regionTop: number
+  readonly regionWidth: number
+  readonly regionHeight: number
+}
+
+const UNMEASURED: PlotMetrics = {
+  plotWidth: 0,
+  plotHeight: 0,
+  regionLeft: 0,
+  regionTop: 0,
+  regionWidth: 0,
+  regionHeight: 0,
+}
+
+function sameMetrics(a: PlotMetrics, b: PlotMetrics): boolean {
+  return (
+    a.plotWidth === b.plotWidth &&
+    a.plotHeight === b.plotHeight &&
+    a.regionLeft === b.regionLeft &&
+    a.regionTop === b.regionTop &&
+    a.regionWidth === b.regionWidth &&
+    a.regionHeight === b.regionHeight
+  )
+}
+
+/**
+ * A message drawn INSIDE the plot box while the axis chrome is still live.
+ *
+ * The all-zero and too-dense states deliberately keep the gridlines and the
+ * baseline (that is the point — the axis proves the chart is not broken), so
+ * the message lands on top of live rules. Measured on the all-zero demo before
+ * this existed: the message box spanned y 241-260 while a 608px-wide
+ * `rgb(var(--chart-grid))` rule sat at y=250 — dead centre through the
+ * sentence — because both the text and its wrapper computed to a transparent
+ * background.
+ *
+ * So the text gets an OPAQUE knock-out on the panel surface. `--surface-card`
+ * is correct and not a guess: `ChartFrame` paints its `<figure>` with exactly
+ * `rgb(var(--surface-card))` (`chart-frame.tsx`), and every BarChart renders
+ * inside one. The backing therefore matches its ground exactly — it is
+ * invisible as a shape and visible only as the gap it cuts in the gridlines,
+ * which is what makes it read as a label sitting ON the plot.
+ *
+ * It stays centred, and the rules keep running behind it on both sides.
+ */
+function PlotNotice({ children }: { children: string }) {
+  return (
+    <div
+      className="pointer-events-none absolute inset-0 flex items-center justify-center text-center"
+      style={{ padding: 'var(--space-4)' }}
+    >
+      <span
+        className="text-[13px]"
+        style={{
+          color: 'rgb(var(--text-tertiary))',
+          background: 'rgb(var(--surface-card))',
+          paddingBlock: 'var(--space-1)',
+          paddingInline: 'var(--space-3)',
+          borderRadius: 'var(--radius-sm)',
+        }}
+      >
+        {children}
+      </span>
+    </div>
+  )
+}
+
+export function BarChart({
+  data,
+  series,
+  mode = 'grouped',
+  orientation = 'vertical',
+  palette = 'default',
+  emphasis = 'peak',
+  selectedKey,
+  onSelect,
+  showAxis = true,
+  tickCount = 5,
+  formatValue = formatNumber,
+  title,
+  subtitle,
+  action,
+  state = 'loaded',
+  emptyMessage,
+  errorMessage,
+  onRetry,
+  aspectRatio,
+  categoryLabel = 'Category',
+  valueLabel = 'Value',
+  categoryGutter = '30%',
+  minBarSize = 4,
+  className,
+}: BarChartProps) {
+  // CALLBACK refs, not `useRef`. `ChartFrame` renders `children` only in the
+  // `loaded` state and swaps the plot out for the table view, so both boxes
+  // unmount and remount. A `useRef` + fixed-dep effect binds once and never
+  // rebinds, which leaves a chart that first painted in `loading`/`empty` —
+  // the normal async path — with all-zero metrics for the rest of its life:
+  // the tooltip would anchor at the plot's top-left instead of the hovered
+  // bar, and the density guard would never fire.
+  const [plotNode, setPlotNode] = useState<HTMLDivElement | null>(null)
+  const [regionNode, setRegionNode] = useState<HTMLDivElement | null>(null)
+  const [metrics, setMetrics] = useState<PlotMetrics>(UNMEASURED)
+  const [hovered, setHovered] = useState<number | null>(null)
+  const [lastHovered, setLastHovered] = useState<number>(0)
+
+  const vertical = orientation === 'vertical'
+  const count = data.length
+  // Stable identity when `series` is omitted, so the memos below actually
+  // memo instead of recomputing on every hover.
+  const seriesList = useMemo(() => series ?? [], [series])
+  const multi = seriesList.length > 0
+  const stacked = multi && mode === 'stacked'
+
+  /* — the value matrix: one row per datum, one entry per series —
+       `null` is ABSENT, and stays distinguishable from `0` all the way to
+       the mark, the readout, the accessible name and the table. */
+  const matrix = useMemo<(number | null)[][]>(
+    () =>
+      data.map((datum) =>
+        multi
+          ? seriesList.map((_, si) => num(datum.values?.[si]))
+          : [num(datum.value)],
+      ),
+    // `data` and `series` are fresh arrays on every parent render; keying on
+    // them directly is correct here because the map is cheap and the result
+    // is only ever read synchronously in this render.
+    [data, seriesList, multi],
+  )
+
+  const hasNegative = matrix.some((row) => row.some((v) => v !== null && v < 0))
+  /** Whether anything at all was measured. All-absent is `empty`, not zero. */
+  const hasValue = matrix.some((row) => row.some((v) => v !== null))
+  /** Whether anything is missing — which narrows what the all-zero message
+   *  is allowed to claim. */
+  const hasAbsent = matrix.some((row) => row.some((v) => v === null))
+
+  // A stack is a running sum, so a negative segment would have to eat into
+  // the one below it — there is no honest picture of that, and every charting
+  // library that tries produces a different one. We clamp to zero, which is
+  // exactly the "chart that lies" this primitive refuses everywhere else, so
+  // it is not allowed to be SILENT. Grouped mode has no such limitation and
+  // draws negatives properly.
+  useEffect(() => {
+    if (!stacked || !hasNegative) return
+    warnOnce(
+      'bar-chart:stacked-negative',
+      '[@lovett/ui] BarChart: a stacked chart cannot draw a negative value, ' +
+        'so negative segments are clamped to zero and the total under-reads. ' +
+        'Use mode="grouped", or split the negative measure into its own ' +
+        'chart — see ADR-146 D5.',
+    )
+  }, [stacked, hasNegative])
+
+  /* — the value domain, with zero always inside it — */
+  // A bar is read as a length from zero, so zero is in the domain whether or
+  // not the data reaches it. This is also what makes an all-equal series
+  // draw full-height bars rather than collapsing to a flat line.
+  const columnTotals = useMemo(
+    () =>
+      stacked
+        ? stackTotals(
+            seriesList.map((_, si) => matrix.map((row) => row[si] ?? 0)),
+          )
+        : [],
+    [stacked, seriesList, matrix],
+  )
+
+  let dataMin = 0
+  let dataMax = 0
+  if (stacked) {
+    for (const total of columnTotals) {
+      if (total > dataMax) dataMax = total
+    }
+  } else {
+    for (const row of matrix) {
+      for (const v of row) {
+        // An absent value is not a datum, so it does not get a vote on the
+        // domain. (Zero is already in the domain by construction, so this
+        // changes no axis today — it is here so the invariant holds if that
+        // ever stops being true.)
+        if (v === null) continue
+        if (v < dataMin) dataMin = v
+        if (v > dataMax) dataMax = v
+      }
+    }
+  }
+
+  const axisTickCount = Math.max(2, Math.min(12, Math.floor(tickCount) || 5))
+
+  /**
+   * How far apart two value-axis labels have to be before they read as two
+   * labels — and it is a different question in each orientation.
+   *
+   * Standing bars put the value axis in the frame's vertical gutter, where
+   * labels sit above each other and the constraint is two line boxes. Lying
+   * bars put it along the bottom, where they sit beside each other and the
+   * constraint is the widest label's own WIDTH plus a gap. The widest is
+   * estimated from the domain's endpoints, which is where the longest number
+   * on a nice-number ladder lives.
+   */
+  const axisSpacingPx = vertical
+    ? Y_TICK_MIN_SPACING_PX
+    : Math.max(
+        estimateTextWidth(formatValue(dataMin), X_LABEL_FONT_PX),
+        estimateTextWidth(formatValue(dataMax), X_LABEL_FONT_PX),
+      ) + TICK_LABEL_GAP_PX
+  // The value axis is drawn along the plot's height when bars stand up and
+  // along its width when they lie down, so the fit measures whichever one
+  // the labels actually run along. Both are `0` until the ResizeObserver
+  // lands, which `fitTicks` reads as "unmeasured" and leaves alone.
+  const axisLengthPx = vertical ? metrics.regionHeight : metrics.regionWidth
+  const ticks = showAxis
+    ? fitTicks(dataMin, dataMax, axisLengthPx, axisSpacingPx, axisTickCount)
+    : []
+  const lo = showAxis ? (ticks[0] ?? dataMin) : dataMin
+  const hi = showAxis ? (ticks[ticks.length - 1] ?? dataMax) : dataMax
+
+  // `hi === lo` can only happen when every MEASURED value is zero, because
+  // zero is already inside the domain. `hasValue` is what separates that from
+  // "nothing was measured", which collapses the domain the same way but is a
+  // different fact and gets the frame's empty state instead.
+  const allZero = count > 0 && hasValue && hi === lo
+
+  const toPct = linearScale([lo, hi], [0, 100])
+  const zeroPct = allZero ? 0 : toPct(0)
+
+  /**
+   * The no-axis monochrome strip is `normalizeToMax`'s exact job — heights as
+   * a fraction of the peak, no domain and no ticks. It clamps negatives to
+   * zero, so it is used ONLY when there are none: a negative bar has to
+   * descend from the baseline, not vanish.
+   */
+  const peakFractions =
+    !showAxis && !multi && !hasNegative
+      ? normalizeToMax(matrix.map((row) => row[0] ?? 0))
+      : null
+
+  /* — spans, one per drawn rectangle. `null` = nothing to draw here — */
+  const spans = useMemo<(Span | null)[][]>(() => {
+    if (allZero) {
+      return matrix.map((row) =>
+        row.map((value) => (value === null ? null : { start: 0, end: 0 })),
+      )
+    }
+    return matrix.map((row, di) => {
+      if (peakFractions !== null) {
+        const value = row[0] ?? null
+        return [value === null ? null : { start: 0, end: (peakFractions[di] ?? 0) * 100 }]
+      }
+      if (stacked) {
+        let cursor = 0
+        return row.map((value) => {
+          // Absent: no segment, and the cursor does not move. The stack
+          // carries one fewer band rather than a seam around nothing.
+          if (value === null) return null
+          const v = value > 0 ? value : 0
+          const span = { start: toPct(cursor), end: toPct(cursor + v) }
+          cursor += v
+          return span
+        })
+      }
+      return row.map((value) => {
+        if (value === null) return null
+        const end = toPct(value)
+        return value < 0
+          ? { start: end, end: zeroPct }
+          : { start: zeroPct, end }
+      })
+    })
+    // `toPct` is rebuilt every render; the domain values it closes over are
+    // the real dependencies.
+  }, [matrix, allZero, peakFractions, stacked, lo, hi, zeroPct]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  /* — band geometry — */
+  // The band axis is the plot's width when bars stand up, its height when
+  // they lie down. Both come off the same measurement.
+  const bandAxisPx = vertical ? metrics.regionWidth : metrics.regionHeight
+  const stepPx = count > 0 && bandAxisPx > 0 ? bandAxisPx / count : 0
+  const gapPx =
+    stepPx > 0
+      ? Math.min(GAP_FULL_PX, Math.max(GAP_MIN_PX, stepPx * GAP_MAX_RATIO))
+      : 0
+  // Unmeasured, fall back to the ratio: percentages are already correct, so
+  // the first paint is a real chart and the measurement only refines the gap.
+  const paddingRatio = stepPx > 0 ? Math.min(1, gapPx / stepPx) : GAP_MAX_RATIO
+
+  // Percent units: `bandScale` over a width of 100 hands back percentages,
+  // which is what lets the bars lay out before anything is measured.
+  const bands = bandScale(count, 100, paddingRatio)
+  const groups = bandScale(
+    multi && !stacked ? seriesList.length : 1,
+    bands.band,
+    multi && !stacked ? GROUP_GAP_RATIO : 0,
+  )
+
+  const drawnBandPct = multi && !stacked ? groups.band : bands.band
+  const drawnBandPx = (drawnBandPct / 100) * bandAxisPx
+  const tooDense = bandAxisPx > 0 && count > 0 && drawnBandPx < minBarSize
+
+  useEffect(() => {
+    if (!tooDense) return
+    warnOnce(
+      `bar-chart:too-dense:${count}`,
+      `[@lovett/ui] BarChart: ${count} bars leave ${drawnBandPx.toFixed(1)}px ` +
+        `per bar, below the ${minBarSize}px legibility floor. Aggregate, page, ` +
+        `or use the table view — see ADR-146 D5.`,
+    )
+  }, [tooDense, count, drawnBandPx, minBarSize])
+
+  /* — measurement: the tooltip's clamp bounds and the density check — */
+  useLayoutEffect(() => {
+    const plot = plotNode
+    const region = regionNode
+    if (plot === null || region === null) return
+
+    const read = () => {
+      const next: PlotMetrics = {
+        plotWidth: plot.offsetWidth,
+        plotHeight: plot.offsetHeight,
+        regionLeft: region.offsetLeft,
+        regionTop: region.offsetTop,
+        regionWidth: region.offsetWidth,
+        regionHeight: region.offsetHeight,
+      }
+      setMetrics((prev) => (sameMetrics(prev, next) ? prev : next))
+    }
+
+    read()
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(read)
+    observer.observe(plot)
+    observer.observe(region)
+    return () => observer.disconnect()
+  }, [plotNode, regionNode, orientation, categoryGutter, count])
+
+  /* — emphasis: exactly one bar, and only in monochrome (D7) — */
+  let emphasized: number | null = null
+  if (!multi && !allZero && count > 0) {
+    if (selectedKey !== null && selectedKey !== undefined) {
+      const found = data.findIndex((datum) => datum.key === selectedKey)
+      emphasized = found >= 0 ? found : null
+    } else if (emphasis === 'peak') {
+      // Only MEASURED values compete. Folding absent onto zero let a missing
+      // reading win the accent outright on an all-negative series — the
+      // emphasis landing on a bar that is not drawn at all.
+      let best: number | null = null
+      let bestValue = Number.NEGATIVE_INFINITY
+      for (let i = 0; i < matrix.length; i++) {
+        const value = matrix[i]?.[0] ?? null
+        if (value === null || value <= bestValue) continue
+        best = i
+        bestValue = value
+      }
+      emphasized = best
+    } else if (emphasis === 'last') {
+      // The last CATEGORY, not the last measurement — but an unmeasured one
+      // draws no bar, so emphasizing it would emphasize nothing visible.
+      emphasized = (matrix[count - 1]?.[0] ?? null) === null ? null : count - 1
+    }
+  }
+
+  /* — frame chrome — */
+  // Categories with nothing measured in any of them are EMPTY, not zero.
+  // "Every value in this range is zero" is a claim about measurements, and
+  // there are none to make it about.
+  const frameState: ChartFrameState =
+    state === 'loaded' && (count === 0 || !hasValue) ? 'empty' : state
+
+  const tickLabels = ticks.map((tick) => formatValue(tick))
+  // ChartFrame's y-gutter is a VALUE axis. It carries the ticks when bars
+  // stand up; when they lie down the value axis is horizontal, so the frame
+  // draws no gutter and no gridlines and this chart draws its own.
+  const yLabels: string[] = !vertical || !showAxis
+    ? []
+    : allZero
+      ? // All-zero keeps the axis STRUCTURE — the gutter's reserved width and
+        // its gridlines — so the plot does not change width between a range
+        // with data and one without (D9, reserved space). It carries no
+        // NUMBERS: `niceTicks(0, 0)` is a single tick, which the frame would
+        // centre at mid-height, drawing a zero line floating above the
+        // baseline. Blank labels keep the structure and drop the lie.
+        // Fitted like any other ladder, so the blank gutter reserves the
+        // same number of rows a measured one would.
+        Array.from(
+          { length: fitTickCount(axisLengthPx, axisSpacingPx, axisTickCount) },
+          () => '',
+        )
+      : [...tickLabels].reverse()
+  // A chart that has declined to draw its bars must not print 400 crushed
+  // labels underneath the refusal.
+  const xLabels: string[] =
+    vertical && !tooDense ? data.map((datum) => datum.label) : []
+  /**
+   * Where each category label belongs: the CENTRE OF ITS BAND, as a fraction
+   * of the plot — the same `bands.center` the bar itself is drawn on.
+   *
+   * Without it the frame can only spread the labels evenly, which is not the
+   * band scale: measured in Chromium at 1440, that put "Paid search" 25px
+   * from its bar on the 5-category demo and 65px on the 3-category one.
+   */
+  const xLabelFractions: number[] = xLabels.map(
+    (_, index) => bands.center(index) / 100,
+  )
+
+  const table = useMemo<ChartTableData>(() => {
+    const columns = multi
+      ? [categoryLabel, ...seriesList.map((entry) => entry.label)]
+      : [categoryLabel, valueLabel]
+    const rows: ChartTableRow[] = data.map((datum, di) => ({
+      key: datum.key,
+      cells: [
+        datum.label,
+        ...(matrix[di] ?? []).map((value) => read(value, formatValue)),
+      ],
+    }))
+    return { columns, rows, caption: `${title ?? 'Chart'} data table` }
+  }, [data, matrix, multi, seriesList, categoryLabel, valueLabel, formatValue, title])
+
+  const legendItems: ChartLegendItem[] = seriesList.map((entry) => ({
+    key: entry.key,
+    label: entry.label,
+    slot: entry.slot,
+  }))
+
+  /* — the readout — */
+  const readoutIndex = hovered ?? lastHovered
+  const readoutDatum = data[readoutIndex]
+  const tooltipRows: ChartTooltipRow[] = multi
+    ? seriesList.map((entry, si) => ({
+        key: entry.key,
+        label: entry.label,
+        value: read(matrix[readoutIndex]?.[si], formatValue),
+        slot: entry.slot,
+      }))
+    : [
+        {
+          key: readoutDatum?.key ?? 'value',
+          label: valueLabel,
+          value: read(matrix[readoutIndex]?.[0], formatValue),
+        },
+      ]
+
+  const readoutSpans = spans[readoutIndex] ?? []
+  const readoutFar = readoutSpans.reduce(
+    (far, span) => (span === null ? far : Math.max(far, span.end)),
+    zeroPct,
+  )
+  const anchorX = vertical
+    ? metrics.regionLeft + (bands.center(readoutIndex) / 100) * metrics.regionWidth
+    : metrics.regionLeft + (readoutFar / 100) * metrics.regionWidth
+  const anchorY = vertical
+    ? metrics.regionTop + ((100 - readoutFar) / 100) * metrics.regionHeight
+    : metrics.regionTop + (bands.center(readoutIndex) / 100) * metrics.regionHeight
+
+  function activate(index: number | null): void {
+    setHovered(index)
+    if (index !== null) setLastHovered(index)
+  }
+
+  /* — the region box: bars, gridlines and the zero rule live here — */
+  // The horizontal chart draws its own value-tick strip along the bottom
+  // (the frame's tick row belongs to a vertical value axis), so the region
+  // gives that strip its height — and gives it back when there is no axis.
+  const tickStrip = !vertical && showAxis ? TICK_STRIP_HEIGHT : 0
+
+  const regionStyle: CSSProperties = vertical
+    ? { left: 0, right: 0, top: 0, bottom: 0 }
+    : { left: categoryGutter, right: 0, top: 0, bottom: tickStrip }
+
+  // The hit layer shares the region's depth but spans the full width, so in
+  // horizontal orientation hovering the category label works too.
+  const hitBoxStyle: CSSProperties = vertical
+    ? { left: 0, right: 0, top: 0, bottom: 0 }
+    : { left: 0, right: 0, top: 0, bottom: tickStrip }
+
+  const showMarks = frameState === 'loaded' && count > 0 && !tooDense && !allZero
+
+  const frameProps: ChartFrameProps = {
+    state: frameState,
+    aspectRatio: aspectRatio ?? (vertical ? 16 / 5 : 16 / 9),
+    yLabels,
+    xLabels,
+    xLabelFractions,
+    table,
+    ...(title !== undefined && { title }),
+    ...(subtitle !== undefined && { subtitle }),
+    ...(action !== undefined && { action }),
+    ...(emptyMessage !== undefined && { emptyMessage }),
+    ...(errorMessage !== undefined && { errorMessage }),
+    ...(onRetry !== undefined && { onRetry }),
+    ...(className !== undefined && { className }),
+    ...(legendItems.length >= 2 && {
+      legend: (
+        <ChartLegend
+          items={legendItems}
+          palette={palette}
+          label={`${title ?? 'Chart'} series`}
+        />
+      ),
+    }),
+  }
+
+  return (
+    <ChartFrame {...frameProps}>
+      <div ref={setPlotNode} className="absolute inset-0">
+        {/* Horizontal: the category-label gutter. Vertical charts get their
+            labels from the frame's x-label row instead. */}
+        {!vertical && frameState === 'loaded' && (
+          <div
+            aria-hidden="true"
+            className="absolute"
+            style={{
+              left: 0,
+              top: 0,
+              width: categoryGutter,
+              bottom: tickStrip,
+            }}
+          >
+            {data.map((datum, di) => (
+              <span
+                key={datum.key}
+                className="absolute block truncate text-[14px]"
+                style={{
+                  // The gap between the label and the bar it names lives HERE,
+                  // not as padding on the gutter: an absolutely-positioned
+                  // child resolves its offsets against its ancestor's PADDING
+                  // box, so padding on the gutter would be dead style and the
+                  // labels would sit flush against the bars.
+                  right: 'var(--space-2)',
+                  top: `${bands.center(di)}%`,
+                  maxWidth: 'calc(100% - var(--space-2))',
+                  transform: 'translateY(-50%)',
+                  color: 'rgb(var(--text-tertiary))',
+                }}
+              >
+                {datum.label}
+              </span>
+            ))}
+          </div>
+        )}
+
+        {/* The bar region. Measured, so the readout can be positioned. */}
+        <div ref={setRegionNode} className="absolute" style={regionStyle}>
+          {/* Horizontal gets its own gridlines: the frame's are horizontal
+              rules for a vertical value axis, which is the wrong axis here. */}
+          {!vertical &&
+            showAxis &&
+            frameState === 'loaded' &&
+            !allZero &&
+            ticks.map((tick, ti) => (
+              <div
+                key={`grid-${ti}`}
+                aria-hidden="true"
+                className="pointer-events-none absolute top-0 bottom-0"
+                style={{
+                  left: `${toPct(tick)}%`,
+                  width: '1px',
+                  background: 'rgb(var(--chart-grid))',
+                }}
+              />
+            ))}
+
+          {/* The zero rule. Only drawn where zero is NOT the frame's own
+              baseline — a negative-spanning vertical chart, or any
+              horizontal one, where the value axis runs the other way. */}
+          {frameState === 'loaded' && !allZero && (hasNegative || !vertical) && (
+            <div
+              aria-hidden="true"
+              className="pointer-events-none absolute"
+              style={
+                vertical
+                  ? {
+                      left: 0,
+                      right: 0,
+                      bottom: `${zeroPct}%`,
+                      height: '1px',
+                      background: 'rgb(var(--chart-axis))',
+                    }
+                  : {
+                      top: 0,
+                      bottom: 0,
+                      left: `${zeroPct}%`,
+                      width: '1px',
+                      background: 'rgb(var(--chart-axis))',
+                    }
+              }
+            />
+          )}
+
+          {/* The hover column, behind the marks. */}
+          {showMarks && hovered !== null && (
+            <div
+              aria-hidden="true"
+              className="pointer-events-none absolute"
+              style={{
+                ...(vertical
+                  ? {
+                      left: `${hovered * bands.step}%`,
+                      width: `${bands.step}%`,
+                      top: 0,
+                      bottom: 0,
+                    }
+                  : {
+                      top: `${hovered * bands.step}%`,
+                      height: `${bands.step}%`,
+                      left: 0,
+                      right: 0,
+                    }),
+                background: 'rgb(var(--chart-band))',
+                borderRadius: 'var(--radius-sm)',
+              }}
+            />
+          )}
+
+          {/* The marks. */}
+          {showMarks &&
+            data.map((datum, di) => {
+              const rowSpans = spans[di] ?? []
+              return rowSpans.map((span, si) => {
+                // Absent: no mark. A zero-length bar on the baseline would
+                // read as a measured zero, which is the whole defect.
+                if (span === null) return null
+                const entry = seriesList[si]
+                const bandStart =
+                  multi && !stacked
+                    ? bands.at(di) + groups.at(si)
+                    : bands.at(di)
+                const bandSize = multi && !stacked ? groups.band : bands.band
+                const length = Math.abs(span.end - span.start)
+                const near = Math.min(span.start, span.end)
+                const fill = multi
+                  ? slotColor(entry?.slot ?? 'other', palette)
+                  : di === emphasized
+                    ? BAR_EMPHASIS
+                    : BAR_REST
+                // The seam between stacked segments: a hairline painted in
+                // the panel colour so two fills read as two marks. The top
+                // DRAWN segment has nothing above it, so it gets none —
+                // absent segments above it do not count, or the topmost bar
+                // would wear a seam against empty space.
+                const seam =
+                  stacked && rowSpans.slice(si + 1).some((next) => next !== null)
+                    ? `${STACK_SEAM} solid rgb(var(--surface-card))`
+                    : undefined
+                return (
+                  <div
+                    key={`${datum.key}-${entry?.key ?? 'value'}`}
+                    aria-hidden="true"
+                    className={cn(
+                      'pointer-events-none absolute',
+                      // Named properties, never `transition-all`: `all` would
+                      // also tween the seam's border-width and every inherited
+                      // property, and it makes what is animating unreadable.
+                      // The list is static, so Tailwind can scan it.
+                      'motion-safe:transition-[left,top,right,bottom,width,height,background-color]',
+                    )}
+                    style={{
+                      ...(vertical
+                        ? {
+                            left: `${bandStart}%`,
+                            width: `${bandSize}%`,
+                            bottom: `${near}%`,
+                            height: `${length}%`,
+                            ...(seam !== undefined && { borderTop: seam }),
+                          }
+                        : {
+                            top: `${bandStart}%`,
+                            height: `${bandSize}%`,
+                            left: `${near}%`,
+                            width: `${length}%`,
+                            ...(seam !== undefined && { borderRight: seam }),
+                          }),
+                      boxSizing: 'border-box',
+                      background: fill,
+                      borderRadius: 'var(--radius-sm)',
+                      // Data changes tween with ease-out. Never ease-spring:
+                      // overshoot on a measured length reads as imprecise.
+                      transitionDuration: 'var(--dur-base)',
+                      transitionTimingFunction: 'var(--ease-out)',
+                    }}
+                  />
+                )
+              })
+            })}
+
+          {/* All-zero: the axis stays, and we say so. Invisible bars on a
+              blank panel read as a broken chart, not as zero. */}
+          {frameState === 'loaded' && allZero && (
+            <PlotNotice>
+              {hasAbsent
+                ? 'Every value measured in this range is zero.'
+                : 'Every value in this range is zero.'}
+            </PlotNotice>
+          )}
+
+          {/* Too dense to draw. The frame's table toggle is still there. */}
+          {frameState === 'loaded' && tooDense && (
+            <PlotNotice>
+              {`Too many categories to chart legibly (${count}). Narrow the range or open the table.`}
+            </PlotNotice>
+          )}
+        </div>
+
+        {/* Horizontal: the value-tick strip, aligned to the gridlines. */}
+        {!vertical && showAxis && frameState === 'loaded' && !allZero && (
+          <div
+            aria-hidden="true"
+            className="absolute"
+            style={{
+              left: categoryGutter,
+              right: 0,
+              bottom: 0,
+              height: TICK_STRIP_HEIGHT,
+            }}
+          >
+            {ticks.map((tick, ti) => {
+              const pct = toPct(tick)
+              const shift =
+                ti === 0
+                  ? 'translateX(0)'
+                  : ti === ticks.length - 1
+                    ? 'translateX(-100%)'
+                    : 'translateX(-50%)'
+              return (
+                <span
+                  key={`tick-${ti}`}
+                  className="absolute top-0 text-[14px] tabular-nums tracking-[-0.5px] whitespace-nowrap"
+                  style={{
+                    left: `${pct}%`,
+                    transform: shift,
+                    color: 'rgb(var(--text-tertiary))',
+                  }}
+                >
+                  {tickLabels[ti]}
+                </span>
+              )
+            })}
+          </div>
+        )}
+
+        {/* The hit layer. One target per category, spanning the full band
+            (bar + gap) and the full plot depth — always at least as large as
+            the bar it selects, which is what makes a 4px bar usable. */}
+        {frameState === 'loaded' && count > 0 && !tooDense && (
+          <div className="absolute" style={hitBoxStyle}>
+            {data.map((datum, di) => {
+              const summary = multi
+                ? seriesList
+                    .map(
+                      (entry, si) =>
+                        `${entry.label} ${read(matrix[di]?.[si], formatValue)}`,
+                    )
+                    .join(', ')
+                : read(matrix[di]?.[0], formatValue)
+              const name = `${datum.label}: ${summary}`
+              const position: CSSProperties = vertical
+                ? {
+                    left: `${di * bands.step}%`,
+                    width: `${bands.step}%`,
+                    top: 0,
+                    bottom: 0,
+                  }
+                : {
+                    top: `${di * bands.step}%`,
+                    height: `${bands.step}%`,
+                    left: 0,
+                    right: 0,
+                  }
+              const shared = {
+                className: cn(
+                  'absolute bg-transparent',
+                  'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                ),
+                style: { ...position, borderRadius: 'var(--radius-sm)' },
+                onMouseEnter: () => activate(di),
+                onMouseLeave: () => activate(null),
+                onFocus: () => activate(di),
+                onBlur: () => activate(null),
+              }
+              return onSelect !== undefined ? (
+                <button
+                  key={datum.key}
+                  {...shared}
+                  type="button"
+                  aria-label={name}
+                  // Only a chart that models selection is a toggle. A bare
+                  // drill-down button announcing "not pressed" on every band
+                  // is noise, so the attribute appears only when the caller
+                  // passes `selectedKey` at all.
+                  {...(selectedKey !== undefined && {
+                    'aria-pressed': selectedKey === datum.key,
+                  })}
+                  className={cn(shared.className, 'cursor-pointer')}
+                  onClick={() => onSelect(datum.key)}
+                />
+              ) : (
+                // Not a button: clicking does nothing, and a control that
+                // advertises an action it does not have is worse than none.
+                // It stays focusable because focus is what reveals the
+                // readout for a keyboard user; the accessible name carries
+                // the datum either way, and ChartFrame's table view is the
+                // full accessible representation (D10.5).
+                <div
+                  key={datum.key}
+                  {...shared}
+                  role="img"
+                  tabIndex={0}
+                  aria-label={name}
+                />
+              )
+            })}
+          </div>
+        )}
+
+        {readoutDatum !== undefined && count > 0 && !tooDense && !allZero && (
+          <ChartTooltip
+            x={anchorX}
+            y={anchorY}
+            plotWidth={metrics.plotWidth}
+            plotHeight={metrics.plotHeight}
+            title={readoutDatum.label}
+            rows={tooltipRows}
+            palette={palette}
+            visible={hovered !== null}
+          />
+        )}
+      </div>
+    </ChartFrame>
+  )
+}