@atelic-action/ui 0.7.1 → 0.8.0

package/README.md

@@ -41,7 +41,7 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | Import | Exports |
 |---|---|
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
-| `@atelic-action/ui/components` | `NotFound` and its prop types (see [The Not Found Page](#the-not-found-page)) |
+| `@atelic-action/ui/components` | `NotFound` and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
 | `@atelic-action/ui/email` | The email components, the theme provider, the plain text helpers, and their prop types (see [Email](#email)) |
 | `@atelic-action/ui/email/render` | `renderEmail` and `renderFailureEmail`, the only entry that imports `react-dom/server` |
 | `@atelic-action/ui/tokens` | `Palette`, `atelicPalette`, `Fonts`, `atelicFonts`, `toThemeCSS`, `themeTokenMap` |
@@ -162,7 +162,7 @@ Runner emails are mobile first. A layout that squashes on a phone is fixed here,
 
 `RecordStack` takes `records`, each a `RecordStackItem` (`title`, `url`, `meta`, `note`, `badge`, `callout`), and renders one table row per record: the title on its own line at 15px, bold and wrapping freely, linked when `url` is set; a mono meta line beneath it with the items joined by middle dots (empty items drop); an optional note beneath that; a hairline between records and none after the last. No cell carries a width, so a name of any length wraps at 320 pixels instead of squashing. An optional `badge` (a stage word such as `"Contacted"`) sits on the title line in a small mono uppercase pill on a `line` hairline, in its own right aligned unbroken cell, so the title keeps wrapping beside it and the badge stays on the title's first line. An optional `callout` (`{ eyebrow, text }`) sets a short task under the meta and the note in the accented `Note` idiom: the eyebrow in the accent, the text at 13px, and a 2px accent rule down its left edge. A record with neither renders exactly as it did before. `recordStackText(records)` is its plain text twin: each title on its own line under a two space indent with any badge after it in square brackets (`Blue Heron Plumbing [Contacted]`), the meta and the note wrapped under a four space indent, any callout as its eyebrow in upper case over its text under that same indent, a blank line between records, and no line past `textWidth` (68 columns, indent included).
 
-The Company Cards additions (0.7.0, from the `Company Cards IA` design, 2026-09-29) ride on the same item and change nothing for a record without them. `badges` is a list of further pills after `badge`, each with a `tone`: `faint` is the quiet stage word, `ink` a bold pill in ink on a 1.5px border (the next touch), `accent` the same in the accent (New). `timeline` (`{ days, touches, opens }`, each day count back from today) draws the record's recent days between the title and the meta line as one table cell per marked day and one per run of empty days between them (seven cells for three marks, never thirty, since Gmail clips a message past about 100 KB), an 8px ink square on each send day and a 5px accent dot on each known open day, the two stacked when they share a day, all standing on a `line` hairline with a 1.5px ink tick at today's edge; nothing is positioned, so it survives Gmail. `RecordTimelineStrip` renders one on its own and `RecordTimelineLegend` names the marks once above a list. `aside` (`{ text, strong, tone }`) sets a fact right on the meta line with its number in bold and colored by tone: `up` fresh, `warm` cooling, `accent` cold. In the text twin every pill follows the title in brackets, the timeline is one character per day (`10d [#······@·o|]`: `#` a send, `o` an open, `@` both, `·` nothing, `|` today), and the aside ends the meta line; `recordTimelineText` and `recordBadges` are the helpers it uses.
+The Company Cards additions (0.7.0, from the `Company Cards IA` design, 2026-09-29) ride on the same item and change nothing for a record without them. `badges` is a list of further pills after `badge`, each with a `tone`: `faint` is the quiet stage word, `ink` a bold pill in ink on a 1.5px border (the next touch), `accent` the same in the accent (New). `timeline` (`{ days, touches, opens }`, each day count back from today) draws the record's recent days between the title and the meta line as one table cell per marked day and one per run of empty days between them (seven cells for three marks, never thirty, since Gmail clips a message past about 100 KB), an 8px ink square on each send day and a 5px accent dot on each known open day, the two stacked when they share a day, all standing on a `line` hairline with a 1.5px ink tick at today's edge and an axis row beneath (`30d` on the left, `today` on the right); nothing is positioned, so it survives Gmail. `RecordTimelineStrip` renders one on its own and `RecordTimelineLegend` names the marks once above a list. `aside` (`{ text, strong, tone }`) sets a fact right on the meta line with its number in bold and colored by tone: `up` fresh, `warm` cooling, `accent` cold. In the text twin every pill follows the title in brackets, the timeline is one character per day (`10d [#······@·o|]`: `#` a send, `o` an open, `@` both, `·` nothing, `|` today), and the aside ends the meta line; `recordTimelineText` and `recordBadges` are the helpers it uses.
 
 `StatStrip` lays its stats out as inline block cells with an 88 pixel floor inside one centered cell, so six or seven stats flow onto a second row on a phone rather than shrinking. Each stat takes an optional `delta` (`"+3 (12%)"`), set small under its label and colored by its sign: one that opens on `+` wears the palette's `up`, one that opens on `-` its `down`, and anything else stays muted.
 
@@ -247,6 +247,23 @@ The plain text alternative part ports as plain functions with no React anywhere
 
 The palette carries three optional keys beyond the jq's eight: `up` (`#2F7A4B`, a calm green) and `down` (`#B23A2E`, a calm red, kept well apart from the orange accent), the colors a `StatStrip` delta wears by its sign, and `warm` (`#B7791F`, an amber between `up` and the accent) for a record's aside that is cooling but not cold. All three read on the cream card. They are optional so a client palette written before 0.5.0 still compiles, and a palette without them borrows the Atelic values. None maps to a site token.
 
+## Page Components
+
+The blocks a page composes, each styled in `styles/components.css` inside the `atelic-ui` layer, so a site's own unlayered rule resizes or recolors any of them. They were cut from the SkySpec baseline writeup on 2026-10-02 (ATE-600), which is the worked example of all eight on one page.
+
+| Component | What it is | Notes |
+|---|---|---|
+| `Checklist` | A short list of checks, each passed or failed | Two columns when there is room, one on a phone. `passLabel` and `failLabel` name the icons for a screen reader |
+| `DataTable` | A table whose first column names each row, sortable by any column marked `sortable` | A click on a heading sorts on a wide screen. On a phone each row stacks, every fact wearing its column's label, and a dropdown sorts. A cell is a node, or `{ display, sort }` when what it shows is not what it sorts by; a formatted number in a string (`"$12,047"`, `"0.24%"`) sorts as a number. It renders in `defaultSort` on the server |
+| `StatRow` | A row of large figures, each over what it counts and its `period` | `trend` draws an arrow before a figure that is itself a change. `deltas` list comparisons beneath: an arrow, how far, against what (`basis`), and the earlier figure (`was`), each in its own tone, since a spend falling and a cost falling read differently |
+| `Callout` | One finding: an icon in its tone beside the title, the explainer under it | `variant="box"` sets it apart on a tinted ground, for something missing or owed |
+| `Collapsible` | A labeled line the reader opens for the detail behind it | A native `details`, so it works before any script loads and find in page opens it. `summary` carries the point, so the detail needs no explaining once open. It prints open |
+| `StackedBar` | One bar split into the parts of a whole, with a key | A part of zero is keyed and not drawn |
+| `ColumnChart` | A bar a period, the periods in groups that carry a label and a total | Months in quarters is the case it was cut for: a quarter reads against the one before it and the same one a year earlier |
+| `ThresholdScale` | Zones on a scale and a pin for each reading | For a number judged against lines, like a load time against good and poor |
+
+**Tones.** `good`, `warn`, `bad`, `info`, and `muted` are the one palette the package carries, because good, a warning, and broken read green, amber, and red whatever the brand is. A component sets `data-tone`, and `--tone`, `--tone-fill`, and `--tone-bg` follow for whatever sits inside. A site's theme may restate `--tone-good` and the rest on `.mkt`; `info` and `muted` come from the theme's own primary and neutral tokens.
+
 ## Releasing
 
 1. Bump `version` in `package.json` and merge it to `main`: patch for a fix, minor for a new component or prop, major for a breaking prop or class rename.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.7.1",
+	"version": "0.8.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, and the component library they install",
 	"type": "module",
 	"license": "UNLICENSED",

package/src/components/Callout.tsx

@@ -0,0 +1,60 @@
+import { CircleAlert, CircleCheck, CircleX, Info } from "lucide-react";
+import type { ReactNode } from "react";
+import type { Tone } from "./tone";
+
+export interface CalloutProps {
+	/** How it reads; picks the icon and the color. Defaults to a warning. */
+	tone?: Tone;
+	/** The point, in a sentence. The icon sits beside it. */
+	title: ReactNode;
+	/** What the icon means, for a screen reader, e.g. "Needs work". */
+	toneLabel?: string;
+	/** `box` sets it apart on a tinted ground, for something missing or owed. */
+	variant?: "plain" | "box";
+	className?: string;
+	/** The one explainer under the title. */
+	children?: ReactNode;
+}
+
+const icons = {
+	good: CircleCheck,
+	warn: CircleAlert,
+	bad: CircleX,
+	info: Info,
+	muted: Info,
+} as const;
+const labels = {
+	good: "Working",
+	warn: "Needs work",
+	bad: "Broken",
+	info: "Note",
+	muted: "Note",
+} as const;
+
+/**
+ * One finding: an icon in its tone beside the title, and the explainer
+ * under it. Plain, it sits in a list of findings; boxed, it is a callout
+ * for something a reader must not miss.
+ */
+export function Callout({
+	tone = "warn",
+	title,
+	toneLabel,
+	variant = "plain",
+	className,
+	children,
+}: CalloutProps) {
+	const Icon = icons[tone];
+	return (
+		<div
+			className={["callout", variant === "box" && "is-box", className].filter(Boolean).join(" ")}
+			data-tone={tone}
+		>
+			<Icon className="callout-icon" size={18} role="img" aria-label={toneLabel ?? labels[tone]} />
+			<div className="callout-text">
+				<div className="callout-title">{title}</div>
+				{children && <div className="callout-body">{children}</div>}
+			</div>
+		</div>
+	);
+}

package/src/components/Checklist.tsx

@@ -0,0 +1,43 @@
+import { CircleCheck, CircleX } from "lucide-react";
+import type { ReactNode } from "react";
+
+export interface ChecklistItem {
+	label: ReactNode;
+	/** One line on what was checked or what failed. */
+	detail?: ReactNode;
+	pass: boolean;
+}
+
+export interface ChecklistProps {
+	items: ChecklistItem[];
+	/** What a screen reader calls a pass and a fail. */
+	passLabel?: string;
+	failLabel?: string;
+	className?: string;
+}
+
+/** A short list of checks, each passed or failed, in two columns when there is room. */
+export function Checklist({
+	items,
+	passLabel = "Passes",
+	failLabel = "Fails",
+	className,
+}: ChecklistProps) {
+	return (
+		<ul className={["checklist", className].filter(Boolean).join(" ")}>
+			{items.map((item, i) => {
+				const Icon = item.pass ? CircleCheck : CircleX;
+				return (
+					// biome-ignore lint/suspicious/noArrayIndexKey: checks are static content in a fixed order
+					<li key={i} data-tone={item.pass ? "good" : "bad"}>
+						<Icon size={18} role="img" aria-label={item.pass ? passLabel : failLabel} />
+						<span>
+							<span className="checklist-label">{item.label}</span>
+							{item.detail && <span className="checklist-detail">{item.detail}</span>}
+						</span>
+					</li>
+				);
+			})}
+		</ul>
+	);
+}

package/src/components/Collapsible.tsx

@@ -0,0 +1,43 @@
+import { ChevronDown } from "lucide-react";
+import type { ReactNode } from "react";
+
+export interface CollapsibleProps {
+	/** What is inside, e.g. "Your Main Pages". Always visible. */
+	label: ReactNode;
+	/**
+	 * What the detail shows, in a sentence, so a reader who never opens it
+	 * still has the point and the detail needs no explaining once open.
+	 */
+	summary?: ReactNode;
+	/** Open on first render; closed by default. */
+	defaultOpen?: boolean;
+	className?: string;
+	children: ReactNode;
+}
+
+/**
+ * A labeled line the reader opens to see the detail behind it. It is a
+ * native details element, so it opens with a click, a tap, Enter, or Space,
+ * works before any script loads, and a browser's find in page opens it. It
+ * prints open.
+ */
+export function Collapsible({
+	label,
+	summary,
+	defaultOpen,
+	className,
+	children,
+}: CollapsibleProps) {
+	return (
+		<details className={["collapsible", className].filter(Boolean).join(" ")} open={defaultOpen}>
+			<summary>
+				<span className="collapsible-text">
+					<span className="collapsible-label">{label}</span>
+					{summary && <span className="collapsible-summary">{summary}</span>}
+				</span>
+				<ChevronDown className="collapsible-chevron" size={18} aria-hidden="true" />
+			</summary>
+			<div className="collapsible-body">{children}</div>
+		</details>
+	);
+}

package/src/components/ColumnChart.tsx

@@ -0,0 +1,97 @@
+import type { Tone } from "./tone";
+
+export interface ColumnChartBar {
+	/** Under the bar, e.g. "Jul". */
+	label: string;
+	value: number;
+	/** Over the bar, e.g. "1.7k"; defaults to the value with separators. */
+	display?: string;
+	tone?: Tone;
+}
+
+export interface ColumnChartGroup {
+	/** Under the group, e.g. "2026 Q3". */
+	label?: string;
+	/** The group's own figure beside its label, e.g. "3,948". */
+	total?: string;
+	/** Colors every bar in the group that sets no tone of its own. */
+	tone?: Tone;
+	bars: ColumnChartBar[];
+}
+
+export interface ColumnChartProps {
+	/** Bars in groups, e.g. months in quarters. One group draws a plain chart. */
+	groups: ColumnChartGroup[];
+	/** What each tone means, e.g. "The same quarter, a year apart". */
+	legend?: Array<{ label: string; tone: Tone }>;
+	/** The tallest a bar draws, in pixels. */
+	height?: number;
+	className?: string;
+}
+
+/**
+ * A column chart: one bar a period, the periods in groups that each carry
+ * their own label and total, so a reader compares a quarter with the one
+ * before it and with the same quarter a year earlier in one picture.
+ */
+export function ColumnChart({ groups, legend, height = 120, className }: ColumnChartProps) {
+	const all = groups.flatMap((group) => group.bars);
+	const max = Math.max(...all.map((bar) => bar.value), 1);
+	const figure = (bar: ColumnChartBar) => bar.display ?? bar.value.toLocaleString("en-US");
+	const summary = groups
+		.map(
+			(group) =>
+				`${group.label ? `${group.label}${group.total ? `, ${group.total}` : ""}: ` : ""}${group.bars
+					.map((bar) => `${bar.label} ${bar.value.toLocaleString("en-US")}`)
+					.join(", ")}`,
+		)
+		.join("; ");
+	return (
+		<div className={["column-chart", className].filter(Boolean).join(" ")}>
+			<div className="column-chart-plot" role="img" aria-label={summary}>
+				{groups.map((group, g) => (
+					<div
+						className="column-chart-group"
+						// biome-ignore lint/suspicious/noArrayIndexKey: groups are static content in time order
+						key={g}
+						style={{ flexGrow: group.bars.length }}
+					>
+						<div className="column-chart-bars">
+							{group.bars.map((bar, b) => (
+								<div
+									className="column-chart-col"
+									// biome-ignore lint/suspicious/noArrayIndexKey: bars are static content in time order
+									key={b}
+									data-tone={bar.tone ?? group.tone ?? "muted"}
+								>
+									<span className="column-chart-value">{figure(bar)}</span>
+									<span
+										className="column-chart-bar"
+										style={{ height: `${Math.round((bar.value / max) * height)}px` }}
+									/>
+									<span className="column-chart-label">{bar.label}</span>
+								</div>
+							))}
+						</div>
+						{(group.label || group.total) && (
+							<div className="column-chart-group-label">
+								{group.label && <span>{group.label}</span>}
+								{group.total && <b>{group.total}</b>}
+							</div>
+						)}
+					</div>
+				))}
+			</div>
+			{legend && (
+				<ul className="chart-key">
+					{legend.map((entry) => (
+						<li key={entry.label} data-tone={entry.tone}>
+							<span className="chart-swatch" aria-hidden="true" />
+							<span>{entry.label}</span>
+						</li>
+					))}
+				</ul>
+			)}
+		</div>
+	);
+}

package/src/components/DataTable.tsx

@@ -0,0 +1,194 @@
+import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
+import { type ReactNode, useId, useMemo, useState } from "react";
+
+export type SortDirection = "asc" | "desc";
+
+export interface DataTableColumn {
+	label: string;
+	align?: "left" | "center" | "right";
+	/**
+	 * Lets a reader sort by this column. Needs every cell in it to carry a
+	 * sort value, or to be a plain string or number.
+	 */
+	sortable?: boolean;
+	/** The direction a first click sorts in; numbers usually read best largest first. */
+	firstSort?: SortDirection;
+}
+
+/** A cell whose display is not what it sorts by, e.g. an icon over a number. */
+export interface DataTableValueCell {
+	display: ReactNode;
+	sort: number | string;
+}
+
+export type DataTableCell = ReactNode | DataTableValueCell;
+
+export interface DataTableRow {
+	/** One cell per column; the first names the row. */
+	cells: DataTableCell[];
+	/** How the row reads, e.g. "bad"; set as data-tone for the site to color. */
+	tone?: string;
+}
+
+export interface DataTableProps {
+	columns: DataTableColumn[];
+	rows: DataTableRow[];
+	/** The sort the table opens in. */
+	defaultSort?: { column: number; direction: SortDirection };
+	/** The label on the phone's sort control. */
+	sortLabel?: string;
+	className?: string;
+}
+
+function isValueCell(cell: DataTableCell): cell is DataTableValueCell {
+	return typeof cell === "object" && cell !== null && "sort" in cell && "display" in cell;
+}
+
+function sortValue(cell: DataTableCell): number | string {
+	if (isValueCell(cell)) return cell.sort;
+	if (typeof cell === "number") return cell;
+	if (typeof cell === "string") {
+		const number = Number(cell.replace(/[$,%\s]/g, ""));
+		return cell.trim() !== "" && Number.isFinite(number) ? number : cell.toLowerCase();
+	}
+	return "";
+}
+
+function compare(a: number | string, b: number | string): number {
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	return String(a).localeCompare(String(b), "en", { numeric: true });
+}
+
+/**
+ * A table whose first column names each row. A reader sorts it by any
+ * sortable column: a click on the heading on a wide screen, a dropdown on a
+ * phone, where each row stacks and every fact wears its column's label so
+ * nothing scrolls sideways. It renders sorted by `defaultSort` on the server
+ * and sorts in place once the page is live.
+ */
+export function DataTable({
+	columns,
+	rows,
+	defaultSort,
+	sortLabel = "Sort by",
+	className,
+}: DataTableProps) {
+	const [sort, setSort] = useState(defaultSort ?? null);
+	const selectId = useId();
+	const anySortable = columns.some((column) => column.sortable);
+
+	const sorted = useMemo(() => {
+		// Each row keeps its place in the source, which is its key: a sort moves
+		// a row's elements rather than rewriting every row in place.
+		const indexed = rows.map((row, index) => ({ row, index }));
+		if (!sort) return indexed;
+		const direction = sort.direction === "asc" ? 1 : -1;
+		return indexed.sort((a, b) => {
+			const order = compare(
+				sortValue(a.row.cells[sort.column]),
+				sortValue(b.row.cells[sort.column]),
+			);
+			return order === 0 ? a.index - b.index : order * direction;
+		});
+	}, [rows, sort]);
+
+	const sortBy = (column: number) => {
+		setSort((current) => {
+			if (current && current.column === column) {
+				return { column, direction: current.direction === "asc" ? "desc" : "asc" };
+			}
+			return { column, direction: columns[column]?.firstSort ?? "asc" };
+		});
+	};
+
+	return (
+		<div className={["data-table", className].filter(Boolean).join(" ")}>
+			{anySortable && (
+				<div className="data-table-sort">
+					<label htmlFor={selectId}>{sortLabel}</label>
+					<select
+						id={selectId}
+						value={sort ? `${sort.column}:${sort.direction}` : ""}
+						onChange={(event) => {
+							const [column, direction] = event.target.value.split(":");
+							if (column === undefined || column === "") return;
+							setSort({ column: Number(column), direction: direction as SortDirection });
+						}}
+					>
+						{!sort && <option value="">As listed</option>}
+						{columns.flatMap((column, index) =>
+							column.sortable
+								? (["desc", "asc"] as const).map((direction) => (
+										// biome-ignore lint/suspicious/noArrayIndexKey: columns are fixed, and the index is the option's value
+										<option key={`${index}:${direction}`} value={`${index}:${direction}`}>
+											{`${column.label}, ${direction === "desc" ? "high to low" : "low to high"}`}
+										</option>
+									))
+								: [],
+						)}
+					</select>
+				</div>
+			)}
+			<table>
+				<thead>
+					<tr>
+						{columns.map((column, index) => {
+							const active = sort?.column === index;
+							const Icon = !active ? ArrowUpDown : sort?.direction === "asc" ? ArrowUp : ArrowDown;
+							return (
+								<th
+									scope="col"
+									key={column.label}
+									data-align={column.align ?? "left"}
+									aria-sort={
+										column.sortable
+											? active
+												? sort?.direction === "asc"
+													? "ascending"
+													: "descending"
+												: "none"
+											: undefined
+									}
+								>
+									{column.sortable ? (
+										<button
+											type="button"
+											onClick={() => sortBy(index)}
+											data-active={active || undefined}
+										>
+											{column.label}
+											<Icon size={12} aria-hidden="true" />
+										</button>
+									) : (
+										column.label
+									)}
+								</th>
+							);
+						})}
+					</tr>
+				</thead>
+				<tbody>
+					{sorted.map(({ row, index }) => (
+						<tr key={index} data-tone={row.tone}>
+							{row.cells.map((cell, c) => {
+								const align = columns[c]?.align ?? "left";
+								const body = isValueCell(cell) ? cell.display : cell;
+								return c === 0 ? (
+									// biome-ignore lint/suspicious/noArrayIndexKey: cells sit in column order
+									<th scope="row" key={c} data-align={align}>
+										{body}
+									</th>
+								) : (
+									// biome-ignore lint/suspicious/noArrayIndexKey: cells sit in column order
+									<td key={c} data-align={align} data-label={columns[c]?.label}>
+										{body}
+									</td>
+								);
+							})}
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	);
+}

package/src/components/StackedBar.tsx

@@ -0,0 +1,46 @@
+import type { Tone } from "./tone";
+
+export interface StackedBarSegment {
+	label: string;
+	value: number;
+	/** The figure as printed, e.g. "1,158"; defaults to the value with separators. */
+	display?: string;
+	tone: Tone;
+}
+
+export interface StackedBarProps {
+	segments: StackedBarSegment[];
+	className?: string;
+}
+
+/** One bar split into the parts of a whole, with a key naming each part and its figure. */
+export function StackedBar({ segments, className }: StackedBarProps) {
+	const total = segments.reduce((sum, segment) => sum + segment.value, 0) || 1;
+	const figure = (segment: StackedBarSegment) =>
+		segment.display ?? segment.value.toLocaleString("en-US");
+	const summary = segments.map((segment) => `${segment.label}: ${figure(segment)}`).join(", ");
+	return (
+		<div className={["stacked-bar", className].filter(Boolean).join(" ")}>
+			<div className="stacked-bar-track" role="img" aria-label={summary}>
+				{segments
+					.filter((segment) => segment.value > 0)
+					.map((segment) => (
+						<span
+							key={segment.label}
+							data-tone={segment.tone}
+							style={{ flexGrow: segment.value / total }}
+						/>
+					))}
+			</div>
+			<ul className="chart-key">
+				{segments.map((segment) => (
+					<li key={segment.label} data-tone={segment.tone}>
+						<span className="chart-swatch" aria-hidden="true" />
+						<b>{figure(segment)}</b>
+						<span>{segment.label}</span>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}

package/src/components/StatRow.tsx

@@ -0,0 +1,96 @@
+import { ArrowDown, ArrowRight, ArrowUp } from "lucide-react";
+import type { ReactNode } from "react";
+import type { Tone } from "./tone";
+
+export type StatDirection = "up" | "down" | "flat";
+
+/** One comparison under a figure: which way it moved, by how much, against what. */
+export interface StatDelta {
+	direction: StatDirection;
+	/** How far it moved, e.g. "23%". */
+	change: string;
+	/** What it is measured against, short, e.g. "YoY". */
+	basis: string;
+	/** The basis spelled out, e.g. "year over year"; read aloud and shown on hover. */
+	basisTitle?: string;
+	/** The earlier figure, e.g. "5,157". It leads the line, small, under the current one. */
+	was?: string;
+	/** Whether the move is good or bad news; a spend falling and a cost falling read differently. */
+	tone?: Tone;
+}
+
+export interface StatItem {
+	/** The big figure, e.g. "$199", "3,948", "23%"; may embed an inline glyph. */
+	value: ReactNode;
+	/** An arrow before the figure, when the figure is itself a change. */
+	trend?: StatDirection;
+	/** What the figure counts. */
+	label: ReactNode;
+	/** The period the figure covers, e.g. "2026 Q3". */
+	period?: ReactNode;
+	/** Comparisons under the figure, each an arrow, a change, and what it is against. */
+	deltas?: StatDelta[];
+	/** A small dimmed qualifier at the foot (the source, a caveat). */
+	note?: ReactNode;
+	/** How the figure itself reads; set as data-tone. */
+	tone?: Tone;
+}
+
+export interface StatRowProps {
+	stats: StatItem[];
+	className?: string;
+}
+
+const arrow = { up: ArrowUp, down: ArrowDown, flat: ArrowRight } as const;
+const spoken = { up: "Up", down: "Down", flat: "Unchanged" } as const;
+
+/**
+ * A row of large figures. Under each sit its comparisons, one a line: what
+ * the figure was, an arrow, how far it moved, and against what. The label
+ * closes the stat, with the period it covers. The row wraps to as many
+ * columns as fit, and arrows are read aloud as up or down.
+ */
+export function StatRow({ stats, className }: StatRowProps) {
+	return (
+		<div className={["stat-row", className].filter(Boolean).join(" ")}>
+			{stats.map((stat, i) => {
+				const Trend = stat.trend ? arrow[stat.trend] : null;
+				return (
+					// biome-ignore lint/suspicious/noArrayIndexKey: stats are static content in a fixed order
+					<div className="stat" key={i} data-tone={stat.tone}>
+						<div className="num">
+							{Trend && stat.trend && (
+								<Trend className="stat-trend" role="img" aria-label={spoken[stat.trend]} />
+							)}
+							{stat.value}
+						</div>
+						{stat.deltas?.map((delta) => {
+							const Icon = arrow[delta.direction];
+							return (
+								<div className="stat-delta" key={delta.basis}>
+									{delta.was && <span className="stat-delta-was">{delta.was}</span>}
+									<span className="stat-delta-change" data-tone={delta.tone ?? "muted"}>
+										<Icon size={14} role="img" aria-label={spoken[delta.direction]} />
+										{delta.change}
+									</span>
+									{delta.basisTitle ? (
+										<abbr className="stat-delta-basis" title={delta.basisTitle}>
+											{delta.basis}
+										</abbr>
+									) : (
+										<span className="stat-delta-basis">{delta.basis}</span>
+									)}
+								</div>
+							);
+						})}
+						<div className="lbl">
+							{stat.label}
+							{stat.period && <span className="stat-period">{stat.period}</span>}
+						</div>
+						{stat.note && <div className="note">{stat.note}</div>}
+					</div>
+				);
+			})}
+		</div>
+	);
+}