@ultimat3/ui 23.0.0 → 25.0.0

package/src/components/app-shell-view.ts

@@ -1,6 +1,6 @@
-// AppShell's two rules, kept away from the markup: the id the skip link points at is derived
-// from the same place the <main> gets it, and which landmarks the frame emits in which order.
-// Both are silent failures when wrong — a skip link to nowhere, or two <main> elements.
+// AppShell's rules, kept away from the markup: the ids the skip link and the menu button point at
+// are derived from the same place the <main> and the <nav> get them, and which landmarks the frame
+// emits in which order. All are silent failures when wrong — a skip link or a menu to nowhere.
 
 export type ShellLandmark = 'banner' | 'navigation' | 'main' | 'contentinfo';
 
@@ -8,6 +8,8 @@ export interface ShellIds {
   readonly mainId: string;
   /** Always `#` + `mainId`. One derivation, so the link and the target cannot drift. */
   readonly skipHref: string;
+  /** The sidebar `<nav>`, which the menu button's `popovertarget` names below `md`. */
+  readonly navId: string;
 }
 
 export interface ShellSlots {
@@ -18,7 +20,7 @@ export interface ShellSlots {
 
 export function shellIds(base: string): ShellIds {
   const mainId = `${base}-main`;
-  return { mainId, skipHref: `#${mainId}` };
+  return { mainId, skipHref: `#${mainId}`, navId: `${base}-nav` };
 }
 
 /**

package/src/components/bar-chart-view.ts

@@ -20,11 +20,12 @@ export interface BarRect {
 }
 
 /**
- * 600 × 128 at a 5:1-ish ratio, not 3:1: at dashboard width a taller box pushed the table — the
- * thing people came for — below the fold. `plot` is where bars live; the strip under it belongs
- * to the axis labels, which drawn ON the first and last bars were unreadable there.
+ * 600 × 108, nearly 6:1, not 3:1: at dashboard width a taller box pushed the table — the thing
+ * people came for — below the fold. `plot` is where bars live; `top` and the matching strip under
+ * it only keep the outer grid hairlines off the edge. The axis labels are HTML OUTSIDE the svg
+ * (issue 494) — inside a viewBox they scaled with it — so the box spends no strip on them.
  */
-export const BAR_CHART = { width: 600, top: 12, plot: 104, height: 128, gap: 3 } as const;
+export const BAR_CHART = { width: 600, top: 2, plot: 104, height: 108, gap: 3 } as const;
 
 /** Quarter lines. Four is what a reader can use to judge a bar's height without a y-axis. */
 export const GRID_STEPS = [0.25, 0.5, 0.75, 1] as const;
@@ -50,13 +51,17 @@ export function gridY(step: number): number {
 /** One rect per point, oldest first. At least 2px tall so a zero still draws a visible bar. */
 export function barRects(points: readonly ChartPoint[]): readonly BarRect[] {
   const count = Math.max(points.length, 1);
-  const width = (BAR_CHART.width - BAR_CHART.gap * (count - 1)) / count;
+  // The gap gives way before the bars do: at most half of each bar's slot, so past the 201 points
+  // where 3px gaps alone fill the width, every bar is still a positive rect and the row still ends
+  // at the right edge.
+  const gap = Math.min(BAR_CHART.gap, BAR_CHART.width / count / 2);
+  const width = (BAR_CHART.width - gap * (count - 1)) / count;
   const max = maxOf(points);
   return points.map((point, index) => {
     const value = Number.isFinite(point.value) ? Math.max(0, point.value) : 0;
     const height = Math.max(2, (value / max) * BAR_CHART.plot);
     return {
-      x: index * (width + BAR_CHART.gap),
+      x: index * (width + gap),
       y: BAR_CHART.top + BAR_CHART.plot - height,
       width,
       height,

package/src/components/chart-frame-view.ts

@@ -0,0 +1,219 @@
+// What every chart shares apart from its geometry: which colour slot, dash and marker a series
+// gets (so no series is told apart by colour alone), the data table a screen reader and a
+// no-colour reader get instead of the picture, and how a number becomes text — always in a locale
+// the caller passed, never the runtime's default.
+
+/** The chart colour roles, `chart-1` … `chart-8` (`--color-chart-N`). */
+export const CHART_SERIES_SLOTS = 8;
+
+export type MarkerShape =
+  | 'circle'
+  | 'square'
+  | 'triangle'
+  | 'diamond'
+  | 'plus'
+  | 'triangle-down'
+  | 'cross'
+  | 'star';
+
+const MARKERS: readonly MarkerShape[] = [
+  'circle',
+  'square',
+  'triangle',
+  'diamond',
+  'plus',
+  'triangle-down',
+  'cross',
+  'star',
+];
+
+/**
+ * Five dash patterns against eight slots and markers: 5 and 8 share no factor, so the whole look
+ * of a series (slot, dash, marker) first repeats at the 41st — a ninth series reuses a colour,
+ * never a line. Units are screen px: every chart stroke is `non-scaling-stroke`.
+ */
+const DASHES: readonly (string | undefined)[] = [undefined, '6 4', '2 3', '10 3 2 3', '1 4'];
+
+export interface SeriesStyle {
+  /** 1-based: the `N` of `--color-chart-N`, and the `data-series` a sheet keys the colour on. */
+  readonly slot: number;
+  /** `stroke-dasharray`; `undefined` is a solid line. */
+  readonly dash: string | undefined;
+  readonly marker: MarkerShape;
+}
+
+const indexOf = (index: number): number =>
+  Number.isFinite(index) && index > 0 ? Math.floor(index) : 0;
+
+/** The look of the `index`th series (0-based). */
+export function seriesStyle(index: number): SeriesStyle {
+  const i = indexOf(index);
+  return {
+    slot: (i % CHART_SERIES_SLOTS) + 1,
+    dash: DASHES[i % DASHES.length],
+    marker: MARKERS[i % MARKERS.length] ?? 'circle',
+  };
+}
+
+/** A coordinate as SVG text: two decimals at most, no trailing zeros, never `-0`. */
+export function svgNumber(value: number): string {
+  const text = value.toFixed(2).replace(/\.?0+$/, '');
+  return text === '-0' ? '0' : text;
+}
+
+/** A closed polygon through `points` (unit offsets scaled by `r` around `x, y`). */
+function polygon(x: number, y: number, r: number, points: readonly (readonly [number, number])[]) {
+  const [head, ...rest] = points.map(
+    ([dx, dy]) => `${svgNumber(x + dx * r)},${svgNumber(y + dy * r)}`,
+  );
+  return `M${head} ${rest.map((p) => `L${p}`).join(' ')} Z`;
+}
+
+const ring = (count: number, radius: number, phase = 0): [number, number][] =>
+  Array.from({ length: count }, (_, i) => {
+    const angle = phase + (i * 2 * Math.PI) / count;
+    return [Math.sin(angle) * radius, -Math.cos(angle) * radius];
+  });
+
+/** Polygons only, so a marker is one path a sheet fills — a 12-gon IS a circle at 4px. */
+const SHAPES: Record<MarkerShape, readonly (readonly [number, number])[]> = {
+  circle: ring(12, 1),
+  square: [
+    [-0.85, -0.85],
+    [0.85, -0.85],
+    [0.85, 0.85],
+    [-0.85, 0.85],
+  ],
+  triangle: [
+    [0, -1],
+    [1, 0.85],
+    [-1, 0.85],
+  ],
+  diamond: [
+    [0, -1],
+    [1, 0],
+    [0, 1],
+    [-1, 0],
+  ],
+  plus: [
+    [-0.33, -1],
+    [0.33, -1],
+    [0.33, -0.33],
+    [1, -0.33],
+    [1, 0.33],
+    [0.33, 0.33],
+    [0.33, 1],
+    [-0.33, 1],
+    [-0.33, 0.33],
+    [-1, 0.33],
+    [-1, -0.33],
+    [-0.33, -0.33],
+  ],
+  'triangle-down': [
+    [-1, -0.85],
+    [1, -0.85],
+    [0, 1],
+  ],
+  cross: [
+    [-1, -0.6],
+    [-0.6, -1],
+    [0, -0.4],
+    [0.6, -1],
+    [1, -0.6],
+    [0.4, 0],
+    [1, 0.6],
+    [0.6, 1],
+    [0, 0.4],
+    [-0.6, 1],
+    [-1, 0.6],
+    [-0.4, 0],
+  ],
+  star: ring(10, 1).map(([dx, dy], i) => (i % 2 === 0 ? [dx, dy] : [dx * 0.45, dy * 0.45])),
+};
+
+/** The `d` of a marker of `shape` centred on `x, y`, inside a box of half-width `r`. */
+export function markerPath(shape: MarkerShape, x: number, y: number, r: number): string {
+  return polygon(x, y, r, SHAPES[shape]);
+}
+
+/** A value a chart can place, or `null` for a gap: missing, NaN and ±∞ are never drawn as 0. */
+export function finiteOrNull(value: number | null | undefined): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export interface ChartSeries {
+  /** The series' name, already translated: the legend entry and the table's column head. */
+  readonly label: string;
+  /** One value per key, in key order; `null` is a gap in the line and an empty table cell. */
+  readonly values: readonly (number | null)[];
+}
+
+export interface ChartTableRow {
+  readonly key: string;
+  readonly cells: readonly string[];
+}
+
+export interface ChartTable {
+  readonly caption: string;
+  /** The corner cell (the key column's head, `''` when unnamed), then one head per series. */
+  readonly head: readonly string[];
+  readonly rows: readonly ChartTableRow[];
+}
+
+export interface ChartTableInput {
+  readonly caption: string;
+  readonly keyLabel: string | undefined;
+  readonly keys: readonly string[];
+  readonly series: readonly ChartSeries[];
+  readonly format: (value: number) => string;
+}
+
+/** The same numbers the picture draws, as rows a screen reader walks cell by cell. */
+export function chartTable(input: ChartTableInput): ChartTable {
+  return {
+    caption: input.caption,
+    head: [input.keyLabel ?? '', ...input.series.map((series) => series.label)],
+    rows: input.keys.map((key, index) => ({
+      key,
+      cells: input.series.map((series) => {
+        const value = finiteOrNull(series.values[index]);
+        return value === null ? '' : input.format(value);
+      }),
+    })),
+  };
+}
+
+/** `Intl.NumberFormat` in the locale passed — the page's, read by the component from `useUi()`. */
+export function chartNumberFormat(
+  locale: string,
+  maxFractionDigits = 2,
+): (value: number) => string {
+  const format = new Intl.NumberFormat(locale, { maximumFractionDigits: maxFractionDigits });
+  return (value) => format.format(value);
+}
+
+/** A point's accessible name: key, series (when there is more than one thing to name), value. */
+export function pointLabel(key: string, series: string | undefined, value: string): string {
+  return series === undefined ? `${key}: ${value}` : `${key}, ${series}: ${value}`;
+}
+
+/** `part` of `whole` as a CSS percentage for a `--x`/`--y` custom property, clamped to the box. */
+export function cssPercent(part: number, whole: number): string {
+  if (!(whole > 0) || !Number.isFinite(part)) return '0%';
+  const share = Math.min(1, Math.max(0, part / whole));
+  return `${svgNumber(share * 100)}%`;
+}
+
+/** A share (0..1) as a percentage in the locale passed: a donut's legend, a gauge's readout. */
+export function chartPercentFormat(locale: string): (share: number) => string {
+  const format = new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 });
+  return (share) => format.format(share);
+}
+
+/** Which way a point's readout opens: inward from the outer fifth of the plot, centred elsewhere. */
+export function hitEdge(x: number, width: number): 'start' | 'middle' | 'end' {
+  const share = width > 0 ? x / width : 0.5;
+  if (share < 0.2) return 'start';
+  if (share > 0.8) return 'end';
+  return 'middle';
+}

package/src/components/chart-ticks-view.ts

@@ -0,0 +1,173 @@
+// Axis arithmetic shared by every chart with a value axis: a "nice" scale (steps of 1, 2 or 5 ×
+// 10ⁿ, the only steps a reader can count in their head) and which category keys get a label.
+// Pure, so the server render and an island draw the same axis, and testable with no renderer.
+
+export interface NiceScale {
+  /** The axis' lowest tick — at or below the data's minimum. */
+  readonly min: number;
+  /** The axis' highest tick — at or above the data's maximum. */
+  readonly max: number;
+  readonly step: number;
+  /** `min`, `min + step`, … `max`, as exact decimals. */
+  readonly ticks: readonly number[];
+}
+
+const MANTISSAS = [1, 2, 5] as const;
+
+/** Rounds away binary noise: `0.1 + 0.2` is drawn as `0.3`, never `0.30000000000000004`. */
+const exact = (value: number): number => Number(value.toPrecision(12));
+
+/** The largest step of the 1-2-5 ladder at or below `raw`; 1 for a raw step that is not one. */
+export function niceStep(raw: number): number {
+  if (!Number.isFinite(raw) || raw <= 0) return 1;
+  const exp = Math.floor(Math.log10(raw));
+  const power = 10 ** exp;
+  const fraction = raw / power;
+  let mantissa = 1;
+  for (const candidate of MANTISSAS) if (candidate <= fraction * (1 + 1e-9)) mantissa = candidate;
+  return exact(mantissa * power);
+}
+
+/** The next rung of the ladder above `step`: 1 → 2 → 5 → 10 → 20. */
+function nextStep(step: number): number {
+  const exp = Math.floor(Math.log10(step));
+  const mantissa = Math.round(step / 10 ** exp);
+  if (mantissa === 1) return exact(2 * 10 ** exp);
+  if (mantissa === 2) return exact(5 * 10 ** exp);
+  return exact(10 ** (exp + 1));
+}
+
+/** Fraction digits a tick at `step` needs: 0 for 5 or 500, 1 for 0.5, 2 for 0.02. */
+export function tickDecimals(step: number): number {
+  if (!Number.isFinite(step) || step <= 0) return 0;
+  return Math.max(0, -Math.floor(Math.log10(step) + 1e-9));
+}
+
+/** A flat range has no height to divide: open it by a tenth of its size (or by 1 at zero). */
+function bounds(lo: number, hi: number): readonly [number, number] {
+  const a = Number.isFinite(lo) ? lo : 0;
+  const b = Number.isFinite(hi) ? hi : a;
+  const [low, high] = a <= b ? [a, b] : [b, a];
+  if (high > low) return [low, high];
+  if (low === 0) return [0, 1];
+  const open = Math.abs(low) * 0.1;
+  // Clamped, because a flat range at ±MAX_VALUE opens past float64 into ±Infinity.
+  return [Math.max(-Number.MAX_VALUE, low - open), Math.min(Number.MAX_VALUE, high + open)];
+}
+
+export interface NiceTicksOptions {
+  /**
+   * The data is whole numbers — a count. Steps are then at least 1, so no tick falls between two
+   * values the data can take: "0.4 signups" labels nothing, and it pushed the max off the labels.
+   */
+  readonly integer?: boolean | undefined;
+}
+
+/**
+ * The densest 1-2-5 labelling of `lo..hi` with at most `maxTicks` ticks (read as at least 2):
+ * start at the step that would fit exactly and climb the ladder until the count fits.
+ */
+export function niceTicks(
+  lo: number,
+  hi: number,
+  maxTicks = 6,
+  options: NiceTicksOptions = {},
+): NiceScale {
+  const cap = Math.max(2, Math.floor(maxTicks));
+  const [low, high] = bounds(lo, hi);
+  const fitted = niceStep((high - low) / (cap - 1));
+  // Every rung of the ladder from 1 up is a whole number, so flooring the START at 1 is enough.
+  let step = options.integer === true ? Math.max(1, fitted) : fitted;
+  for (let rung = 0; rung < MAX_RUNGS; rung += 1) {
+    const min = exact(Math.floor(low / step + 1e-9) * step);
+    const max = exact(Math.ceil(high / step - 1e-9) * step);
+    const count = Math.round((max - min) / step) + 1;
+    // Past float64's edge the ladder stops being one: `ceil(hi / step) * step` overflows, the
+    // next rung IS `Infinity`, and `NaN <= cap` is false forever — a LineChart SSR that never
+    // returned. An underflowing step collapses the range to one tick instead. Either way the
+    // data's own two ends are the only honest axis left.
+    if (!(step > 0 && Number.isFinite(step) && Number.isFinite(min) && Number.isFinite(max))) break;
+    if (count < 2) break;
+    if (count <= cap) {
+      const ticks = Array.from({ length: count }, (_, i) => exact(min + i * step));
+      return { min, max, step, ticks };
+    }
+    step = nextStep(step);
+  }
+  return edgeScale(low, high);
+}
+
+/**
+ * Rungs from the smallest subnormal step to the largest finite one: ~632 decades × 3. The loop
+ * already exits at the first non-finite rung; the bound makes termination a fact, not an argument.
+ */
+const MAX_RUNGS = 2_048;
+
+/** The fallback axis: just the data's two ends, which `bounds` has already made finite. */
+function edgeScale(low: number, high: number): NiceScale {
+  const span = high - low;
+  return {
+    min: low,
+    max: high,
+    step: Number.isFinite(span) && span > 0 ? span : Number.MAX_VALUE,
+    ticks: [low, high],
+  };
+}
+
+/**
+ * Which of `count` category keys carry a label, at most `max` of them: an even stride counted
+ * back from the NEWEST key, which is always labelled — on a time axis it is the one people read.
+ * The stride is at least `(count - 1) / (max - 1)` keys, which is what lets a label be capped at
+ * a fixed share of the axis and never touch its neighbour.
+ */
+export function axisLabelIndices(count: number, max: number): readonly number[] {
+  if (count <= 0) return [];
+  const cap = Math.max(2, Math.floor(max));
+  if (count <= cap) return Array.from({ length: count }, (_, i) => i);
+  const stride = Math.ceil((count - 1) / (cap - 1));
+  const out: number[] = [];
+  for (let index = count - 1; index >= 0; index -= stride) out.unshift(index);
+  return out;
+}
+
+/** Category labels a chart under its container breakpoint shows — a 390px phone. */
+export const NARROW_LABELS = 3;
+/** And at or above it. Each label is capped at ⅔ of the narrowest stride, so neither overlaps. */
+export const WIDE_LABELS = 6;
+
+export type LabelEdge = 'start' | 'middle' | 'end';
+
+export interface CategoryLabel {
+  readonly index: number;
+  /** Shown below the container breakpoint (`data-narrow`). */
+  readonly narrow: boolean;
+  /** Shown at or above it (`data-wide`). */
+  readonly wide: boolean;
+  /** The oldest key aligns to the start edge, the newest to the end, so neither leaves the box. */
+  readonly edge: LabelEdge;
+}
+
+/**
+ * Every key that either width labels, oldest first, each flagged with the width that shows it.
+ * The sheet hides by flag, so one server render serves the phone and the desktop with no JS.
+ */
+export function categoryLabels(count: number): readonly CategoryLabel[] {
+  const narrow = new Set(axisLabelIndices(count, NARROW_LABELS));
+  const wide = new Set(axisLabelIndices(count, WIDE_LABELS));
+  const indices = [...new Set([...narrow, ...wide])].sort((a, b) => a - b);
+  return indices.map((index) => ({
+    index,
+    narrow: narrow.has(index),
+    wide: wide.has(index),
+    edge: count === 1 ? 'middle' : index === 0 ? 'start' : index === count - 1 ? 'end' : 'middle',
+  }));
+}
+
+/**
+ * Which of `count` value-axis labels a narrow chart hides: every other one counted down from the
+ * TOP, once there are more than three — the highest tick is the one that bounds the data, so it is
+ * never the one dropped. Hidden labels keep their grid line; only the text goes.
+ */
+export function minorTicks(count: number): readonly boolean[] {
+  return Array.from({ length: count }, (_, i) => count > 3 && (count - 1 - i) % 2 === 1);
+}

package/src/components/data-table-view.ts

@@ -0,0 +1,68 @@
+// Where each DataTable value is visible, by the table's own width. A column's `priority` hides its
+// cell in a narrow table; the row's "more" disclosure shows the same value for exactly the widths
+// the cell is gone, so no value is ever on screen twice and none is ever nowhere.
+
+import { invalidValueError } from '../errors';
+
+/**
+ * The roles every DataTable element re-declares. Redundant on a table laid out as a table, and
+ * deliberately so: below `sm` the card view changes `display` on the table, its row groups, rows
+ * and cells, and WebKit drops the implicit table semantics of an element whose `display` changed —
+ * a screen reader then meets loose text with no row, no column and no header. The explicit role is
+ * the documented remedy, and ONE constant is the one place the redundancy is argued, rather than a
+ * lint suppression on every element.
+ */
+export const TABLE_ROLES = {
+  rowgroup: 'rowgroup',
+  row: 'row',
+  columnheader: 'columnheader',
+  cell: 'cell',
+} as const;
+
+/** 1 is always a cell; 2 is a cell from `md` up; 3 from `lg` up. Widths are the TABLE's. */
+export const COLUMN_PRIORITIES = [1, 2, 3] as const;
+export type ColumnPriority = (typeof COLUMN_PRIORITIES)[number];
+
+/**
+ * The `data-priority` / `data-more` values the stylesheet's width rules select on. Attributes, not
+ * classes: they are state the markup carries, and a test can read them where a CSS-module class
+ * resolves to nothing under `bun test`.
+ */
+export type PriorityAttr = '2' | '3';
+/** The rung the disclosure shows below — the widest range any of its columns is hidden over. */
+export type MoreUntil = 'md' | 'lg';
+
+/**
+ * The priority a column declared, refused when it is not one: the type stops a TypeScript caller,
+ * and nothing stops a column list parsed from config — a `priority: 4` used to be a column shown
+ * at every width with no word that it was not what was asked for.
+ */
+export function columnPriority(priority: unknown): ColumnPriority {
+  if (priority === undefined) return 1;
+  if (priority === 1 || priority === 2 || priority === 3) return priority;
+  throw invalidValueError('DataTable', priority, 'a column priority of 1, 2 or 3');
+}
+
+/** What a cell (and its header) carries; priority 1 carries nothing and is never hidden. */
+export function priorityAttr(priority: ColumnPriority): PriorityAttr | undefined {
+  return priority === 1 ? undefined : `${priority}`;
+}
+
+export interface MoreColumn<C> {
+  /** The columns whose values the disclosure may hold, in declaration order. */
+  readonly columns: readonly C[];
+  readonly until: MoreUntil;
+}
+
+/**
+ * The trailing "more" column, or `undefined` when every column is priority 1 — a table that
+ * hides nothing gets no extra column, no extra header and no extra bytes.
+ */
+export function moreColumn<C extends { readonly priority?: unknown }>(
+  columns: readonly C[],
+): MoreColumn<C> | undefined {
+  const hidden = columns.filter((column) => columnPriority(column.priority) > 1);
+  if (hidden.length === 0) return undefined;
+  const widest = Math.max(...hidden.map((column) => columnPriority(column.priority)));
+  return { columns: hidden, until: widest === 3 ? 'lg' : 'md' };
+}

package/src/components/donut-chart-view.ts

@@ -0,0 +1,120 @@
+// The arc maths of a DonutChart (and a Gauge's track): where each segment starts and ends, the
+// annular-sector path that draws it, and where its marker sits. Angles are radians from twelve
+// o'clock, clockwise — the way a reader goes round a clock face. Pure, so two renders agree.
+
+import { svgNumber } from './chart-frame-view';
+
+/** A 200 × 200 box; the ring is 32 units wide, which leaves room for a centre label inside. */
+export const DONUT = { size: 200, centre: 100, outer: 96, inner: 64, marker: 6 } as const;
+
+const TURN = Math.PI * 2;
+/** The gap between two neighbours, so a segment boundary reads without relying on colour. */
+const GAP = 0.03;
+/** The least sweep a non-zero segment is drawn with: a 0.1% share is still a visible sliver. */
+const MIN_SWEEP = 0.012;
+
+export interface CirclePoint {
+  readonly x: number;
+  readonly y: number;
+}
+
+export function pointOnCircle(cx: number, cy: number, r: number, angle: number): CirclePoint {
+  return { x: cx + r * Math.sin(angle), y: cy - r * Math.cos(angle) };
+}
+
+const at = (p: CirclePoint): string => `${svgNumber(p.x)},${svgNumber(p.y)}`;
+
+function sector(cx: number, cy: number, outer: number, inner: number, a0: number, a1: number) {
+  const large = a1 - a0 > Math.PI ? 1 : 0;
+  const o0 = pointOnCircle(cx, cy, outer, a0);
+  const o1 = pointOnCircle(cx, cy, outer, a1);
+  const i1 = pointOnCircle(cx, cy, inner, a1);
+  const i0 = pointOnCircle(cx, cy, inner, a0);
+  return (
+    `M${at(o0)} A${outer},${outer} 0 ${large} 1 ${at(o1)} ` +
+    `L${at(i1)} A${inner},${inner} 0 ${large} 0 ${at(i0)} Z`
+  );
+}
+
+/**
+ * The ring between radii `inner` and `outer` from angle `a0` to `a1`. A sweep of a whole turn is
+ * drawn as two halves: an SVG arc from a point back to itself has no direction and draws nothing.
+ */
+export function annularSector(
+  cx: number,
+  cy: number,
+  outer: number,
+  inner: number,
+  a0: number,
+  a1: number,
+): string {
+  if (!(a1 > a0)) return '';
+  if (a1 - a0 >= TURN - 1e-9) {
+    const half = a0 + Math.PI;
+    return `${sector(cx, cy, outer, inner, a0, half)} ${sector(cx, cy, outer, inner, half, a0 + TURN)}`;
+  }
+  return sector(cx, cy, outer, inner, a0, a1);
+}
+
+export interface DonutArc {
+  /** This value's part of the positive total; 0 for a value that is not drawn. */
+  readonly share: number;
+  /** The segment's slot on the ring, before the gap is taken off. */
+  readonly start: number;
+  readonly end: number;
+  /** What is actually drawn: the slot less half a gap at each end. */
+  readonly drawnStart: number;
+  readonly drawnEnd: number;
+  readonly path: string;
+  /** Mid-ring, mid-segment: where a focusable segment's hit sits. `null` for a share of 0. */
+  readonly anchor: CirclePoint | null;
+  /** The anchor again, or `null` where the segment is too narrow to hold a marker. */
+  readonly marker: CirclePoint | null;
+}
+
+const positive = (value: number): number => (Number.isFinite(value) && value > 0 ? value : 0);
+
+/** One arc per value, in order from twelve o'clock; a non-positive value is listed, not drawn. */
+export function donutArcs(values: readonly number[]): readonly DonutArc[] {
+  const { centre, outer, inner, marker } = DONUT;
+  const total = values.reduce((sum, value) => sum + positive(value), 0);
+  const drawn = values.filter((value) => positive(value) > 0).length;
+  const gap = drawn > 1 ? GAP : 0;
+  const mid = (outer + inner) / 2;
+  let cursor = 0;
+  return values.map((value): DonutArc => {
+    const share = total > 0 ? positive(value) / total : 0;
+    const start = cursor;
+    const end = cursor + share * TURN;
+    cursor = end;
+    if (share === 0) {
+      return {
+        share,
+        start,
+        end,
+        drawnStart: start,
+        drawnEnd: start,
+        path: '',
+        anchor: null,
+        marker: null,
+      };
+    }
+    const centreAngle = (start + end) / 2;
+    const sweep = Math.max(MIN_SWEEP, end - start - gap);
+    const drawnStart = gap === 0 ? start : centreAngle - sweep / 2;
+    const drawnEnd = gap === 0 ? end : centreAngle + sweep / 2;
+    // A marker needs about three of its own widths of arc, or it spills onto the neighbours.
+    const fits = sweep * mid >= marker * 3;
+    const anchor = pointOnCircle(centre, centre, mid, centreAngle);
+    return {
+      share,
+      start,
+      end,
+      drawnStart,
+      drawnEnd,
+      path: annularSector(centre, centre, outer, inner, drawnStart, drawnEnd),
+      anchor,
+      marker: fits ? anchor : null,
+    };
+  });
+}