@lovett/ui 0.0.11 → 0.2.0

package/src/donut-chart.tsx

@@ -0,0 +1,988 @@
+/**
+ * DonutChart — arc segments plus a divided legend list.
+ *
+ * Promoted in ADR-146 D5 (chart layer). It consumes `arcSegments` from
+ * `lib/chart.ts` rather than writing a fourth copy of the cumulative
+ * dasharray accumulator that `spec/shell-charts.tsx:63-91` and
+ * `completion-ring.tsx:58-64` already write (ADR-146 D6).
+ *
+ * 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).
+ *   PLANNED: an admin usage-mix panel (`components/ui/admin/analytics.tsx`
+ *   renders that share as `RankedBars` today) and a discovery traffic-source
+ *   panel. Neither is written. Tracked in
+ *   `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * ANATOMY (Metoric spec §6.3, real measurements)
+ * ----------------------------------------------
+ *   plot        square, 150-160px, stroke-based arcs on ONE centreline circle
+ *   gap         2px of the SURFACE colour between adjacent segments, so the
+ *               ring reads as separate marks rather than one continuous band
+ *   centre      optional: value large and **set solid** (line-height 1 — the
+ *               kit's own rule, and what stops a metric looking loose), a
+ *               muted caption below it, both `tabular-nums`
+ *   legend      swatch + label + value, 1px dividers between rows,
+ *               `--space-4` vertical padding, and the **percentage inside the
+ *               label string** ("Website (50%)") rather than in a third
+ *               column. That is the kit's choice and it is the right one: a
+ *               third column makes the row scan as a table, not a key.
+ *
+ * WHAT THIS PRIMITIVE DELIBERATELY DOES NOT DO
+ * --------------------------------------------
+ * It does **not** compose `ChartFrame`. A donut has no axis, no gridlines and
+ * no baseline, and `ChartFrame` always draws its darker `--chart-axis`
+ * baseline under the plot box — correct for every other chart in the set and
+ * wrong under a ring. Its plot box is also a single full-width column, which
+ * cannot hold the kit's plot-beside-legend layout. So `DonutChart` renders
+ * the plot and its legend only, and a caller who wants a titled panel with a
+ * table view wraps it in a `Card`. (`chart-frame.tsx`'s header currently
+ * lists `DonutChart` among its consumers; that line is stale — logged as a
+ * follow-up rather than edited here, since another phase owns that file.)
+ *
+ * THE SERIES CAP (ADR-146 D2) — WHY THE FOLD IS A FUNCTION
+ * --------------------------------------------------------
+ * Beyond eight entities the remainder folds into ONE "Other" segment in a
+ * neutral grey. We never generate a ninth hue: two entities drawn in one
+ * colour is a wrong chart that no gate can see. The fold is `foldDonutData`,
+ * exported and pure, so the folded count is available to a caller ("and 4
+ * more") without re-deriving it, and so the cap is unit-testable without a
+ * DOM. It is also visible in the legend, as a `meta` line under the "Other"
+ * row — a silent fold would be a data loss the reader cannot detect.
+ *
+ * Colour follows the ENTITY, never its rank (D7). Slot defaults to the
+ * datum's position in `data`, and a datum may pin its own `slot` so a filter
+ * that removes a series cannot repaint the survivors.
+ *
+ * EDGE CASES, ALL DELIBERATE
+ * --------------------------
+ * - **One category** → a single complete ring, and no separators. A lone cut
+ *   in a full ring reads as a rendering fault.
+ * - **All values zero (or empty `data`)** → the track ring paints in `--muted`
+ *   and the legend is replaced by `emptyMessage`. `arcSegments` returns
+ *   fractions of `0` here rather than dividing by zero, and it does not
+ *   split the ring evenly, which would invent data that is not there.
+ * - **A slice under 1%** → it still gets a **minimum visible arc**
+ *   (`minSliceFraction`, default `0.012` ≈ 4.3°). Without this a 0.3% slice
+ *   is a sub-pixel dash: present in the legend, invisible in the ring, which
+ *   reads as a bug. The lift is taken proportionally out of the slices that
+ *   are above the floor, so the ring still closes exactly. **The legend
+ *   percentage is always the TRUE fraction** — the lift is a drawing
+ *   correction and must never leak into a number the reader compares.
+ *
+ * TWO NARROW-WIDTH DEFECTS, FOUND BY MEASURING A BROWSER (fixed 2026-09-06)
+ * -------------------------------------------------------------------------
+ * Both were measured at a 390px viewport in BOTH themes, and neither is
+ * visible to a jsdom test — the source read correctly in both cases.
+ *
+ * 1. **The legend labels collapsed to zero width.** The plot is `shrink-0`,
+ *    so on a 164px-wide root it kept all 160px and the `flex-1` legend beside
+ *    it got 0. Every label rendered at `width: 0` (`scrollWidth` 73-124),
+ *    leaving swatch + value and five series told apart by hue alone. The row
+ *    now wraps (`flex-wrap` + `LEGEND_BASIS`): below ~372px the legend moves
+ *    UNDER the plot at full width instead of being starved.
+ *
+ * 2. **The centre readout overflowed the hole and painted on the arcs.** It
+ *    was `inset-0` on the whole 160px plot box, so "$116,120" spanned x
+ *    96-212 across a hole of x 100-208 — the "$" on one arc, the trailing "0"
+ *    on another. It is now sized to the hole (inner diameter at the RAISED
+ *    stroke, less `--space-1`), and its type is scaled once, from a measured
+ *    gauge, against the WIDEST string the slot can ever hold — the resting
+ *    total and every value a hover can swap in. That is what makes the slot
+ *    genuinely reserved: hovering changes the string, never the size.
+ *
+ * Token discipline: every colour is `rgb(var(--token))`. Series hues resolve
+ * through `slotColor` and the frozen `SERIES` lookup in `lib/series.ts` (D8 —
+ * never a constructed `--series-${i}`), which is also what makes the arc and
+ * its legend swatch the same colour by construction. The "Other" fold takes
+ * that module's shared `OTHER_SLOT_COLOR` neutral for the same reason. Every
+ * spacing, radius, duration and easing is a token. The only bare numbers are
+ * SVG geometry — a viewBox cannot read a CSS custom property — and each one
+ * is named.
+ */
+
+import { useEffect, useRef, useState } from 'react'
+
+import { ChartLegend, type ChartLegendItem } from './chart-legend'
+import { ChartTooltip } from './chart-tooltip'
+import { formatNumber, formatPercent } from './format'
+import { arcGeometry, arcSegments } from './lib/chart'
+import {
+  SERIES_SLOT_COUNT,
+  isSeriesSlot,
+  slotColor,
+  type ChartSlot,
+  type SeriesPalette,
+  type SeriesSlot,
+} from './lib/series'
+import { cn } from './lib/utils'
+
+/* ── geometry constants ──────────────────────────────────────────────────
+ * Pixel arithmetic in the SVG's own coordinate space. These cannot be
+ * tokens: a `viewBox` is unitless and cannot resolve `var()`.
+ */
+
+/** Extra stroke a hovered/focused segment gains, in viewBox units. */
+const HOVER_BUMP = 4
+/** Extra stroke the focus halo gains over the base stroke. */
+const FOCUS_HALO = 8
+/**
+ * Half the widest extra stroke, reserved inside the square so a raised or
+ * focused segment cannot paint outside the plot box. This is the layout-
+ * stability rule applied to a ring: the box never grows, the mark does.
+ */
+const EDGE_RESERVE = FOCUS_HALO / 2
+/** Stroke width of the surface-coloured cut drawn between adjacent segments. */
+const SEGMENT_GAP = 2
+/** Opacity of a non-active segment while another one is active. Matches
+ *  `ChartLegend`'s row dim, so plot and legend fade together. */
+const DIM_OPACITY = 0.55
+
+/**
+ * Base type size of the centre value, in px, before the fit scale below is
+ * applied. On the type ramp (24 / 18 / 16 / 14 / 12); it is a number rather
+ * than a `text-[24px]` class because the fit multiplies it.
+ */
+const CENTER_VALUE_FONT_PX = 24
+/**
+ * Floor for the centre fit. Below this the readout would be smaller than the
+ * caption under it and the hierarchy would invert; no plausible formatted
+ * value reaches it (at 12px a tabular string clears a 94px hole up to ~15
+ * characters).
+ */
+const CENTER_MIN_SCALE = 0.5
+/** Base type size of the centre caption, in px, before its own fit scale. */
+const CENTER_CAPTION_FONT_PX = 12
+/**
+ * Floor for the caption fit. A caption is prose and may ellipsis as a last
+ * resort; it must not shrink past legibility to avoid one.
+ */
+const CAPTION_MIN_SCALE = 0.8
+
+/**
+ * Flex basis of the legend column in the `row` layout. Below this the legend
+ * WRAPS under the plot instead of being starved.
+ *
+ * Measured 2026-09-06, light and dark, 390px viewport: the plot is
+ * `shrink-0` at `size` px, so on a 164px-wide root it kept all 160px and the
+ * `flex-1` legend beside it was allotted 0 — every label rendered at
+ * `width: 0` against a `scrollWidth` of 73-124px, leaving five series
+ * identified by colour alone (ADR-146 D10.1). `flex-wrap` plus this basis is
+ * what makes the row reflow instead.
+ *
+ * Token-derived, and sized from the legend row it has to hold: swatch
+ * (`--space-3`) + two `--space-3` gaps + a readable label + the reserved
+ * value column (`--space-12`).
+ */
+const LEGEND_BASIS = 'calc(var(--space-12) * 4)'
+
+/** The synthetic key of the folded "Other" slice. */
+export const DONUT_OTHER_KEY = 'donut:other'
+
+/** Which surface the inter-segment gap is cut in. */
+export type DonutGapSurface = 'card' | 'frame' | 'none'
+
+/**
+ * Frozen literal lookup, the same shape as `metric-card.tsx`'s `TONE_COLOR`.
+ * The gap has to be painted in whatever surface the donut actually sits on,
+ * and a caller cannot be trusted with a raw colour — so it picks a surface by
+ * name and the token is resolved here.
+ */
+const GAP_COLOR: Record<Exclude<DonutGapSurface, 'none'>, string> = {
+  card: 'rgb(var(--surface-card))',
+  frame: 'rgb(var(--surface-frame))',
+}
+
+export interface DonutChartDatum {
+  /**
+   * Stable identity key. Also the React key, the `onSelect` payload, and —
+   * per ADR-146 D7 — what colour follows. Keep it stable across filters.
+   */
+  key: string
+  /** Category name. Rendered in the legend and the segment's accessible
+   *  name; identity is never colour alone (D10.1). */
+  label: string
+  /** The measure. Negative and non-finite values read as `0` — an arc
+   *  cannot sweep backwards, and a share chart with negative shares is a
+   *  different chart. */
+  value: number
+  /**
+   * Pin this entity's palette slot. Omit and the slot is the datum's
+   * position in `data`. Pass it when the same entity must keep its hue
+   * across a filter that changes its position (D7 — colour follows the
+   * entity, never its rank).
+   */
+  slot?: SeriesSlot
+  /** Optional muted second line under the legend label. */
+  meta?: string
+}
+
+/** One rendered slice: a datum, or the folded "Other" remainder. */
+export interface DonutSlice {
+  readonly key: string
+  readonly label: string
+  readonly value: number
+  readonly slot: ChartSlot
+  readonly meta: string | undefined
+  /** `0` for a real entity; the number of categories folded in for "Other". */
+  readonly foldedCount: number
+}
+
+/** The result of applying the ADR-146 D2 series cap. */
+export interface DonutFold {
+  /** Slices to draw, in order. At most `maxSlices` long. */
+  readonly slices: readonly DonutSlice[]
+  /** How many categories were folded into "Other". `0` when nothing folded. */
+  readonly foldedCount: number
+}
+
+/**
+ * Apply the series cap: keep the first `maxSlices - 1` categories and fold
+ * every remaining one into a single neutral "Other" slice (ADR-146 D2).
+ *
+ * Exported and pure so a caller can read `foldedCount` without a DOM, and so
+ * the cap is testable on its own. `maxSlices` is clamped into
+ * `1..SERIES_SLOT_COUNT`: a cap above eight would ask the palette for a hue
+ * it does not have, and a cap below one has no meaning.
+ *
+ * Input order is preserved, and a datum's own `slot` always wins over its
+ * position.
+ */
+export function foldDonutData(
+  data: readonly DonutChartDatum[],
+  maxSlices: number = SERIES_SLOT_COUNT,
+  otherLabel = 'Other',
+): DonutFold {
+  const cap = Number.isFinite(maxSlices)
+    ? Math.max(1, Math.min(Math.floor(maxSlices), SERIES_SLOT_COUNT))
+    : SERIES_SLOT_COUNT
+
+  const toSlice = (datum: DonutChartDatum, index: number): DonutSlice => ({
+    key: datum.key,
+    label: datum.label,
+    value: datum.value,
+    slot: datum.slot ?? (isSeriesSlot(index) ? index : 'other'),
+    meta: datum.meta,
+    foldedCount: 0,
+  })
+
+  if (data.length <= cap) {
+    return { slices: data.map(toSlice), foldedCount: 0 }
+  }
+
+  const kept = data.slice(0, cap - 1).map(toSlice)
+  const folded = data.slice(cap - 1)
+  let total = 0
+  for (const datum of folded) {
+    // Same clamp `arcSegments` applies, so the "Other" arc and the "Other"
+    // value can never disagree.
+    if (Number.isFinite(datum.value) && datum.value > 0) total += datum.value
+  }
+
+  return {
+    slices: [
+      ...kept,
+      {
+        key: DONUT_OTHER_KEY,
+        label: otherLabel,
+        value: total,
+        slot: 'other',
+        meta: undefined,
+        foldedCount: folded.length,
+      },
+    ],
+    foldedCount: folded.length,
+  }
+}
+
+/**
+ * Lift every non-zero fraction to at least `minFraction`, taking the lift
+ * proportionally out of the slices that sit above the floor so the total
+ * stays exactly `1` and the ring still closes.
+ *
+ * Exported for tests: "a 0.3% slice is still visible AND the ring is still
+ * full" is the contract, and it is far easier to assert as arithmetic than as
+ * a rendered dasharray.
+ *
+ * The floor is itself capped at `1 / n`, so a chart of many tiny slices
+ * degrades to an even split rather than demanding more ring than exists.
+ */
+export function withMinimumArc(
+  fractions: readonly number[],
+  minFraction: number,
+): number[] {
+  const positives = fractions.filter((f) => f > 0).length
+  if (positives === 0) return fractions.map(() => 0)
+  if (!Number.isFinite(minFraction) || minFraction <= 0) return [...fractions]
+
+  const floor = Math.min(minFraction, 1 / positives)
+  const lifted = fractions.map((f) => (f > 0 && f < floor ? floor : f))
+
+  let total = 0
+  for (const f of lifted) total += f
+  const deficit = total - 1
+  if (deficit <= 0) return lifted
+
+  let surplus = 0
+  for (const f of lifted) if (f > floor) surplus += f - floor
+  if (surplus <= 0) return lifted.map((f) => (total > 0 ? f / total : 0))
+
+  const ratio = Math.min(1, deficit / surplus)
+  return lifted.map((f) => (f > floor ? f - (f - floor) * ratio : f))
+}
+
+export interface DonutChartProps {
+  /** The categories, in draw order (twelve o'clock, clockwise). */
+  data: readonly DonutChartDatum[]
+  /**
+   * Coloured slices before the "Other" fold. Clamped to `1..8`; default `8`
+   * (ADR-146 D2 — the palette has eight slots and never generates a ninth).
+   */
+  maxSlices?: number
+  /** Label for the folded slice. Default `'Other'`. */
+  otherLabel?: string
+  /**
+   * Meta line under the "Other" legend row, so the fold is visible rather
+   * than silent. Receives the folded count. Default
+   * `` (n) => `${n} smaller categories` ``.
+   */
+  otherMeta?: (foldedCount: number) => string
+  /** Plot edge in px. Default `160` — the kit's donut is 150-160. */
+  size?: number
+  /** Ring stroke in px. Default `size / 6`, floored at 6. */
+  thickness?: number
+  /**
+   * The smallest fraction of the ring any non-zero slice may occupy, so a
+   * sub-1% category is still a visible mark. Default `0.012` (≈4.3°). Set
+   * `0` to draw true fractions only. Never affects the legend percentage.
+   */
+  minSliceFraction?: number
+  /** Which palette the slots index into. Default `'default'`. */
+  palette?: SeriesPalette
+  /**
+   * Surface the 2px inter-segment gap is cut in — it has to match whatever
+   * the donut sits on. Default `'card'`; `'none'` draws one continuous ring.
+   */
+  gapSurface?: DonutGapSurface
+  /**
+   * Formats a value for the legend, the tooltip and the centre. Default
+   * `formatNumber`. Format through `@lovett/ui/format`.
+   */
+  formatValue?: (value: number) => string
+  /** Decimal places on the legend/tooltip percentage. Default `0`. */
+  percentDecimals?: number
+  /**
+   * Centre value when nothing is hovered — usually the total. Omit for a
+   * plain ring. While a segment is active the centre shows THAT segment
+   * instead, which is the whole reason the slot is reserved rather than
+   * conditionally rendered.
+   */
+  centerValue?: string
+  /** Muted caption under the centre value. Often the measure's name. */
+  centerCaption?: string
+  /** Renders the legend. Default `true`. */
+  showLegend?: boolean
+  /** Legend beside the plot (`'row'`, default) or under it (`'column'`). */
+  orientation?: 'row' | 'column'
+  /** Reserved width of the legend's value column. Default `var(--space-12)`. */
+  legendValueMinWidth?: string
+  /**
+   * Controlled active (hovered/focused) key. Omit for uncontrolled. `null`
+   * means nothing is active.
+   */
+  activeKey?: string | null
+  /** Fires whenever the active segment changes, controlled or not. */
+  onActiveChange?: (key: string | null) => void
+  /**
+   * Makes segments and legend rows activatable. Receives the slice key —
+   * `DONUT_OTHER_KEY` for the fold. Omit for a read-only chart: an inert
+   * mark must not advertise an interaction it does not have.
+   */
+  onSelect?: (key: string) => void
+  /** Shown in place of the legend when nothing has a positive value. */
+  emptyMessage?: string
+  /** Accessible name for the plot. Default `'Donut chart'`. */
+  label?: string
+  /** Optional className on the outer container. */
+  className?: string
+}
+
+export function DonutChart({
+  data,
+  maxSlices = SERIES_SLOT_COUNT,
+  otherLabel = 'Other',
+  otherMeta = (count) => `${count} smaller categories`,
+  size = 160,
+  thickness,
+  minSliceFraction = 0.012,
+  palette = 'default',
+  gapSurface = 'card',
+  formatValue = (value) => formatNumber(value),
+  percentDecimals = 0,
+  centerValue,
+  centerCaption,
+  showLegend = true,
+  orientation = 'row',
+  legendValueMinWidth = 'var(--space-12)',
+  activeKey,
+  onActiveChange,
+  onSelect,
+  emptyMessage = 'No data to chart.',
+  label = 'Donut chart',
+  className,
+}: DonutChartProps) {
+  const [internalActive, setInternalActive] = useState<string | null>(null)
+  const controlled = activeKey !== undefined
+  const active = controlled ? activeKey : internalActive
+
+  function setActive(next: string | null) {
+    if (!controlled) setInternalActive(next)
+    onActiveChange?.(next)
+  }
+
+  /* ── geometry ─────────────────────────────────────────────────────── */
+
+  const box = Math.max(0, size)
+  const stroke = Math.max(6, thickness ?? Math.round(box / 6))
+  // The raised/focused stroke has to fit, so the ring is inset by half the
+  // widest extra stroke. The box never changes size; the mark does.
+  const outerRadius = Math.max(0, box / 2 - EDGE_RESERVE)
+  const { radius } = arcGeometry(outerRadius, stroke)
+  const center = box / 2
+
+  const { slices, foldedCount } = foldDonutData(data, maxSlices, otherLabel)
+
+  // TRUE fractions — what the legend and the tooltip report. `arcSegments`
+  // clamps negatives to 0 and returns 0 for every slice when the total is 0,
+  // so there is no divide-by-zero to guard here.
+  const trueSegments = arcSegments(
+    slices.map((slice) => slice.value),
+    outerRadius,
+    stroke,
+  )
+  const positiveCount = trueSegments.filter((seg) => seg.fraction > 0).length
+  const isEmpty = positiveCount === 0
+
+  // DISPLAY fractions — the same shares with a minimum visible arc applied.
+  // Drawn geometry only; never reported as a number.
+  const drawnSegments = arcSegments(
+    withMinimumArc(
+      trueSegments.map((seg) => seg.fraction),
+      minSliceFraction,
+    ),
+    outerRadius,
+    stroke,
+  )
+
+  /* ── the plot's rendered width, for tooltip anchoring ─────────────── */
+
+  const plotRef = useRef<HTMLDivElement>(null)
+  const [plotPx, setPlotPx] = useState(box)
+
+  useEffect(() => {
+    const el = plotRef.current
+    if (el === null) return
+
+    function measure() {
+      if (el === null) return
+      const width = el.getBoundingClientRect().width
+      setPlotPx(width > 0 ? width : box)
+    }
+
+    measure()
+    // jsdom ships no ResizeObserver (the suite stubs a no-op one), and a
+    // fixed-size donut never resizes — the measurement is only here so the
+    // tooltip still lands on its segment when the plot shrinks under
+    // `max-width: 100%` on a narrow viewport.
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [box])
+
+  const scale = box > 0 ? plotPx / box : 1
+
+  /* ── the hole, and the centre readout that has to fit inside it ─────── */
+
+  // The hole is the ring's INNER diameter, and it is measured against the
+  // RAISED stroke, not the resting one: a hovered segment grows inward by
+  // HOVER_BUMP / 2, so a reserve computed from the resting ring would let the
+  // centre collide with an arc at exactly the moment a value is being read
+  // off it. Using the raised figure makes the reserve constant in every
+  // state, which is the point of reserving it at all.
+  //
+  // Measured 2026-09-06 at 390px, before this: the plot spanned x 74-234 with
+  // a hole of x 100-208, while "$116,120" spanned x 96-212 — the leading "$"
+  // sat on the violet arc and the trailing "0" on the blue one, because the
+  // readout was sized `inset-0` against the whole 160px plot box.
+  const holePx = Math.max(0, 2 * radius - stroke - HOVER_BUMP) * scale
+
+  /* ── derived text ─────────────────────────────────────────────────── */
+
+  // formatPercent takes PERCENT UNITS, not a 0-1 fraction (ADR-146 D11).
+  const zeroPercent = formatPercent(0, { decimals: percentDecimals })
+  const percentOf = (fraction: number) => {
+    const pct = fraction * 100
+    const text = formatPercent(pct, { decimals: percentDecimals })
+    // A slice that is DRAWN — it cleared `minSliceFraction`, so the reader can
+    // see it — but whose share rounds to "0%" reads as a rendering fault: a
+    // visible arc labelled as nothing. Report the true share as "<1%" (or
+    // "<0.1%" at one decimal) instead. Still true, never rounded UP into a
+    // share the slice does not have, and it is the number the reader compares.
+    if (pct > 0 && text === zeroPercent) {
+      const smallest = 10 ** -percentDecimals
+      return `<${formatPercent(smallest, { decimals: percentDecimals })}`
+    }
+    return text
+  }
+
+  const activeIndex = active === null
+    ? -1
+    : slices.findIndex((slice) => slice.key === active)
+  const activeSlice = activeIndex >= 0 ? slices[activeIndex] : undefined
+  const activeFraction = trueSegments[activeIndex]?.fraction ?? 0
+  // A controlled `activeKey` can outlive the datum it names — a filter drops
+  // the series while it is hovered. Resolve emphasis through the slice we
+  // actually found, so a stale key dims nothing rather than dimming the whole
+  // chart and its legend with no segment raised to explain why.
+  const resolvedActive = activeSlice !== undefined ? active : null
+
+  const legendItems: ChartLegendItem[] = slices.map((slice, index) => {
+    const fraction = trueSegments[index]?.fraction ?? 0
+    const meta =
+      slice.foldedCount > 0 ? otherMeta(slice.foldedCount) : slice.meta
+    return {
+      key: slice.key,
+      label: `${slice.label} (${percentOf(fraction)})`,
+      slot: slice.slot,
+      value: formatValue(slice.value),
+      ...(meta !== undefined ? { meta } : {}),
+    }
+  })
+
+  const showCenter = centerValue !== undefined || activeSlice !== undefined
+  const centerMain =
+    activeSlice !== undefined ? formatValue(activeSlice.value) : centerValue
+  const centerSub =
+    activeSlice !== undefined ? activeSlice.label : centerCaption
+
+  /* ── centre fit ───────────────────────────────────────────────────────
+   * Every string the centre slot can EVER show: the resting value plus the
+   * value of every slice a hover can swap in. The type size is chosen from
+   * the widest of them and then never changes, which is what makes the slot
+   * genuinely reserved — hovering swaps the string, never the size.
+   */
+
+  const valueSet = new Set<string>()
+  if (centerValue !== undefined && centerValue !== '') valueSet.add(centerValue)
+  for (const slice of slices) {
+    const text = formatValue(slice.value)
+    if (text !== '') valueSet.add(text)
+  }
+
+  const captionSet = new Set<string>()
+  if (centerCaption !== undefined && centerCaption !== '') {
+    captionSet.add(centerCaption)
+  }
+  for (const slice of slices) {
+    if (slice.label !== '') captionSet.add(slice.label)
+  }
+
+  // The candidates travel into the effect as ONE string rather than an array:
+  // an array literal is a new identity on every render and would re-run the
+  // effect forever, and a \u0000-joined key is both the dependency and the
+  // payload. (No formatter can emit a NUL, so the split is lossless.)
+  const valueKey = [...valueSet].join('\u0000')
+  const captionKey = [...captionSet].join('\u0000')
+
+  const fitRef = useRef<HTMLDivElement>(null)
+  const valueGaugeRef = useRef<HTMLSpanElement>(null)
+  const captionGaugeRef = useRef<HTMLSpanElement>(null)
+  const [centerScale, setCenterScale] = useState(1)
+  const [captionScale, setCaptionScale] = useState(1)
+
+  useEffect(() => {
+    const fit = fitRef.current
+    if (fit === null) return
+
+    // The gauges are rendered EMPTY and filled one candidate at a time here,
+    // rather than rendering every candidate as its own hidden node. Hidden
+    // duplicates of the value would put the same string in the DOM twice,
+    // which is a trap for anything that reads the tree by text — a test, a
+    // find-in-page, a scraper — for no benefit.
+    function widestOf(gauge: HTMLSpanElement | null, key: string): number {
+      if (gauge === null || key === '') return 0
+      let widest = 0
+      for (const candidate of key.split('\u0000')) {
+        gauge.textContent = candidate
+        widest = Math.max(widest, gauge.getBoundingClientRect().width)
+      }
+      gauge.textContent = ''
+      return widest
+    }
+
+    function recompute() {
+      if (fit === null) return
+      const available = fit.getBoundingClientRect().width
+      const valueWidest = widestOf(valueGaugeRef.current, valueKey)
+      const captionWidest = widestOf(captionGaugeRef.current, captionKey)
+
+      // jsdom reports 0 for every box; leaving the scales at 1 there is
+      // correct — there is nothing to fit to.
+      const fit1 =
+        available > 0 && valueWidest > 0
+          ? Math.max(CENTER_MIN_SCALE, Math.min(1, available / valueWidest))
+          : 1
+      const fit2 =
+        available > 0 && captionWidest > 0
+          ? Math.max(CAPTION_MIN_SCALE, Math.min(1, available / captionWidest))
+          : 1
+
+      // Quantized so sub-pixel resize noise cannot chase its own tail — and
+      // quantized DOWNWARD, never to nearest. Rounding 0.7465 up to 0.75 put
+      // "$116,120" at 86.4px inside an 86px slot: no overflow, no failing
+      // `scrollWidth` check, and a visible "$116,1…" in the screenshot. A
+      // number that ellipsises is a number the reader cannot trust.
+      const nextValue = Math.floor(fit1 * 100) / 100
+      const nextCaption = Math.floor(fit2 * 100) / 100
+      setCenterScale((prev) => (Math.abs(prev - nextValue) < 0.005 ? prev : nextValue))
+      setCaptionScale((prev) =>
+        Math.abs(prev - nextCaption) < 0.005 ? prev : nextCaption,
+      )
+    }
+
+    recompute()
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(recompute)
+    observer.observe(fit)
+    return () => observer.disconnect()
+    // `showCenter` is load-bearing, not decoration: on a donut with no
+    // `centerValue` the whole readout is unmounted at rest and only appears
+    // when a segment becomes active. Without this dep the effect would have
+    // run once against a null ref and never again, and that donut's value
+    // would render unscaled at the base size — measured, before this: a 120px
+    // donut showed "48,250" at 24px, ellipsised inside a 60px slot.
+  }, [valueKey, captionKey, holePx, showCenter])
+
+  /* ── tooltip anchor ───────────────────────────────────────────────── */
+
+  const anchorFraction =
+    activeIndex >= 0
+      ? (drawnSegments[activeIndex]?.startFraction ?? 0) +
+        (drawnSegments[activeIndex]?.fraction ?? 0) / 2
+      : 0
+  const anchorAngle = anchorFraction * Math.PI * 2 - Math.PI / 2
+  const anchorX = (center + radius * Math.cos(anchorAngle)) * scale
+  const anchorY = (center + radius * Math.sin(anchorAngle)) * scale
+
+  /* ── render ───────────────────────────────────────────────────────── */
+
+  const interactive = onSelect !== undefined
+  const gapColor = gapSurface === 'none' ? null : GAP_COLOR[gapSurface]
+
+  return (
+    <div
+      className={cn(
+        'flex',
+        // `flex-wrap` in the row layout is what stops the legend being
+        // starved: the plot cannot shrink (it is `shrink-0`), so on a narrow
+        // root the legend either wraps under it or gets nothing. See
+        // LEGEND_BASIS for the measurement.
+        orientation === 'row' ? 'flex-row flex-wrap items-center' : 'flex-col',
+        className,
+      )}
+      style={{ gap: 'var(--space-5)' }}
+    >
+      <div
+        ref={plotRef}
+        className="relative shrink-0"
+        // Geometry, not spacing: the plot is a square of `size` px that may
+        // shrink on a narrow viewport. `aspect-ratio` is what reserves its
+        // height so async data cannot reflow the page (ADR-146 D9).
+        style={{ width: box, maxWidth: '100%', aspectRatio: '1' }}
+      >
+        <svg
+          viewBox={`0 0 ${box} ${box}`}
+          className="h-full w-full"
+          role="group"
+          aria-label={label}
+        >
+          {/* Track. Always painted, so an all-zero chart still reads as a
+              ring rather than as a missing element. */}
+          <circle
+            aria-hidden="true"
+            cx={center}
+            cy={center}
+            r={radius}
+            fill="none"
+            stroke="rgb(var(--muted))"
+            strokeWidth={stroke}
+          />
+
+          {/* Segments. Rotated -90° so slice one starts at twelve o'clock —
+              the same convention both hand-rolled accumulators used. */}
+          <g transform={`rotate(-90 ${center} ${center})`}>
+            {!isEmpty &&
+              drawnSegments.map((segment, index) => {
+                const slice = slices[index]
+                if (slice === undefined || segment.fraction <= 0) return null
+
+                const trueFraction = trueSegments[index]?.fraction ?? 0
+                const raised = active === slice.key
+                const color = slotColor(slice.slot, palette)
+                const name = [
+                  slice.label,
+                  formatValue(slice.value),
+                  percentOf(trueFraction),
+                  slice.foldedCount > 0 ? otherMeta(slice.foldedCount) : null,
+                ]
+                  .filter((part) => part !== null)
+                  .join(', ')
+
+                return (
+                  <g
+                    key={slice.key}
+                    // No `focus-visible:[box-shadow:var(--ring-focus)]` here:
+                    // `box-shadow` does not paint on an SVG element — it has
+                    // no CSS box — so the class would be an inert claim to a
+                    // focus ring with every gate green. The visible ring is
+                    // the halo <circle> below, which has the added virtue of
+                    // tracing THIS arc rather than boxing the whole plot.
+                    className={cn(
+                      'group cursor-default outline-none',
+                      interactive && 'cursor-pointer',
+                    )}
+                    tabIndex={0}
+                    role={interactive ? 'button' : 'img'}
+                    aria-label={name}
+                    onMouseEnter={() => setActive(slice.key)}
+                    onMouseLeave={() => setActive(null)}
+                    onFocus={() => setActive(slice.key)}
+                    onBlur={() => setActive(null)}
+                    onClick={
+                      onSelect !== undefined
+                        ? () => onSelect(slice.key)
+                        : undefined
+                    }
+                    onKeyDown={
+                      onSelect !== undefined
+                        ? (event) => {
+                            if (event.key !== 'Enter' && event.key !== ' ') {
+                              return
+                            }
+                            event.preventDefault()
+                            onSelect(slice.key)
+                          }
+                        : undefined
+                    }
+                  >
+                    {/* Focus halo. Same radius and same dash as the arc, so
+                        it traces exactly this segment and not the whole
+                        ring. Painted first, therefore behind. Kept in the
+                        DOM at zero opacity so focusing costs no layout. */}
+                    <circle
+                      aria-hidden="true"
+                      className="opacity-0 group-focus-visible:opacity-100"
+                      cx={center}
+                      cy={center}
+                      r={radius}
+                      fill="none"
+                      stroke="rgb(var(--ring))"
+                      strokeWidth={stroke + FOCUS_HALO}
+                      strokeDasharray={segment.dasharray}
+                      strokeDashoffset={segment.dashoffset}
+                    />
+                    <circle
+                      className="motion-safe:transition-[stroke-width,opacity]"
+                      cx={center}
+                      cy={center}
+                      r={radius}
+                      fill="none"
+                      stroke={color}
+                      // The "raise": the stroke grows around the SAME
+                      // centreline, so the dash geometry stays valid and the
+                      // segment thickens on both edges instead of moving.
+                      strokeWidth={raised ? stroke + HOVER_BUMP : stroke}
+                      strokeDasharray={segment.dasharray}
+                      strokeDashoffset={segment.dashoffset}
+                      opacity={
+                        activeSlice === undefined || raised ? 1 : DIM_OPACITY
+                      }
+                      style={{
+                        transitionDuration: 'var(--dur-fast)',
+                        // Data and hover changes tween with ease-out. Never
+                        // ease-spring: overshoot reads as imprecise.
+                        transitionTimingFunction: 'var(--ease-out)',
+                      }}
+                    />
+                  </g>
+                )
+              })}
+
+            {/* The 2px surface-coloured cuts between adjacent segments. Drawn
+                last so they sit above every arc, and skipped entirely for a
+                single slice — one cut in a full ring reads as a fault. */}
+            {gapColor !== null &&
+              positiveCount > 1 &&
+              drawnSegments.map((segment, index) => {
+                const slice = slices[index]
+                if (slice === undefined || segment.fraction <= 0) return null
+                const angle = segment.startFraction * Math.PI * 2
+                // Reach past the RAISED stroke, not just the resting one. A
+                // hovered/focused segment grows by HOVER_BUMP around the same
+                // centreline, so a cut sized for the base stroke leaves a
+                // coloured nub at each radial end of it the moment the reader
+                // hovers. The overshoot paints surface colour onto surface
+                // colour, so covering the widest case costs nothing.
+                const reach = stroke / 2 + HOVER_BUMP / 2 + 1
+                const inner = radius - reach
+                const outer = radius + reach
+                const cos = Math.cos(angle)
+                const sin = Math.sin(angle)
+                return (
+                  <line
+                    key={`gap-${slice.key}`}
+                    aria-hidden="true"
+                    x1={center + inner * cos}
+                    y1={center + inner * sin}
+                    x2={center + outer * cos}
+                    y2={center + outer * sin}
+                    stroke={gapColor}
+                    strokeWidth={SEGMENT_GAP}
+                  />
+                )
+              })}
+          </g>
+        </svg>
+
+        {/* Centre readout. Absolutely positioned and pointer-events-none so
+            it can never steal a hover from a segment underneath it, and both
+            lines always occupy their slot so swapping total ↔ hovered
+            segment does not resize anything.
+
+            The reserve is the HOLE, not the plot box: the readout is sized to
+            `holePx` (inner diameter at the raised stroke) less the inline
+            padding, and the value's type is scaled once to the widest string
+            the slot can ever hold. */}
+        {showCenter && (
+          <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+            <div
+              className="flex flex-col items-center text-center"
+              style={{
+                width: holePx,
+                maxWidth: '100%',
+                // --space-1, not --space-2: the reserve already uses the
+                // RAISED hole, which is 2px tighter on each side than the
+                // resting one, so 4px here is 6px of real clearance from the
+                // arc as drawn at rest — and it buys the value line enough
+                // width to stay near its full type size.
+                paddingInline: 'var(--space-1)',
+                boxSizing: 'border-box',
+              }}
+            >
+              {/* `fitRef` measures the available content width; the gauges
+                  below render every candidate at the BASE size, off-flow and
+                  invisible, so the fit is measured rather than estimated. */}
+              <div ref={fitRef} className="relative w-full">
+                <span
+                  ref={valueGaugeRef}
+                  aria-hidden="true"
+                  className="absolute top-0 left-0 block leading-none font-semibold tabular-nums whitespace-nowrap opacity-0"
+                  style={{ fontSize: `${CENTER_VALUE_FONT_PX}px` }}
+                />
+                <span
+                  ref={captionGaugeRef}
+                  aria-hidden="true"
+                  className="absolute top-0 left-0 block leading-tight whitespace-nowrap opacity-0"
+                  style={{ fontSize: `${CENTER_CAPTION_FONT_PX}px` }}
+                />
+                <span
+                  className="block truncate leading-none font-semibold tabular-nums"
+                  style={{
+                    color: 'rgb(var(--foreground))',
+                    maxWidth: '100%',
+                    fontSize: `${CENTER_VALUE_FONT_PX * centerScale}px`,
+                  }}
+                >
+                  {centerMain}
+                </span>
+                <span
+                  className="block truncate leading-tight"
+                  style={{
+                    marginTop: 'var(--space-1)',
+                    // Reserved even when empty, so the value never jumps.
+                    minHeight: 'var(--space-4)',
+                    maxWidth: '100%',
+                    color: 'rgb(var(--text-tertiary))',
+                    fontSize: `${CENTER_CAPTION_FONT_PX * captionScale}px`,
+                    visibility: centerSub === undefined ? 'hidden' : 'visible',
+                  }}
+                >
+                  {centerSub ?? ''}
+                </span>
+              </div>
+            </div>
+          </div>
+        )}
+
+        {activeSlice !== undefined && (
+          <ChartTooltip
+            x={anchorX}
+            y={anchorY}
+            plotWidth={plotPx}
+            plotHeight={plotPx}
+            title={activeSlice.label}
+            palette={palette}
+            rows={[
+              {
+                key: activeSlice.key,
+                label: percentOf(activeFraction),
+                value: formatValue(activeSlice.value),
+                slot: activeSlice.slot,
+              },
+            ]}
+          />
+        )}
+      </div>
+
+      {showLegend && (
+        <div
+          className="min-w-0"
+          style={
+            orientation === 'row'
+              ? { flex: `1 1 ${LEGEND_BASIS}` }
+              : { flex: '1 1 auto' }
+          }
+        >
+          {isEmpty ? (
+            <p
+              className="text-[14px]"
+              style={{ color: 'rgb(var(--text-tertiary))' }}
+            >
+              {emptyMessage}
+            </p>
+          ) : (
+            <ChartLegend
+              items={legendItems}
+              orientation="vertical"
+              palette={palette}
+              activeKey={resolvedActive}
+              valueMinWidth={legendValueMinWidth}
+              label={`${label} legend`}
+              {...(onSelect !== undefined ? { onSelect } : {})}
+            />
+          )}
+        </div>
+      )}
+
+      {/* The fold has to be readable, not just visible: a screen reader hears
+          this even though the legend's "Other" row already shows it. */}
+      {foldedCount > 0 && !isEmpty && (
+        <span className="sr-only">
+          {`${foldedCount} smaller categories are grouped as ${otherLabel}.`}
+        </span>
+      )}
+    </div>
+  )
+}