@atelic-action/ui 0.7.2 → 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` |
@@ -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.2",
+	"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>
+	);
+}

package/src/components/ThresholdScale.tsx

@@ -0,0 +1,89 @@
+import type { Tone } from "./tone";
+
+export interface ThresholdZone {
+	label: string;
+	/** Where the zone ends, in the reading's unit; the last zone runs to `max`. */
+	upTo?: number;
+	tone: Tone;
+}
+
+export interface ThresholdReading {
+	label: string;
+	value: number;
+	/** The figure as printed, e.g. "5.9 s". */
+	display: string;
+	tone: Tone;
+}
+
+export interface ThresholdScaleProps {
+	/** The far end of the scale, in the reading's unit. */
+	max: number;
+	/** Zones in order, e.g. good, slow, poor. */
+	zones: ThresholdZone[];
+	/** The lines between zones, labeled, e.g. "2.5 s" at 2.5. */
+	ticks?: Array<{ at: number; label: string }>;
+	/** One line a reading, each a pin on the scale. */
+	readings: ThresholdReading[];
+	className?: string;
+}
+
+/**
+ * A scale with zones and one line a reading: where a number sits against
+ * the lines that decide good, slow, and poor.
+ */
+export function ThresholdScale({ max, zones, ticks, readings, className }: ThresholdScaleProps) {
+	let from = 0;
+	const sized = zones.map((zone) => {
+		const to = zone.upTo ?? max;
+		const width = ((to - from) / max) * 100;
+		from = to;
+		return { ...zone, width };
+	});
+	return (
+		<div className={["threshold-scale", className].filter(Boolean).join(" ")}>
+			{readings.map((reading) => (
+				<div className="threshold-scale-row" key={reading.label}>
+					<span className="threshold-scale-label">{reading.label}</span>
+					<span
+						className="threshold-scale-track"
+						role="img"
+						aria-label={`${reading.label}: ${reading.display}`}
+					>
+						{sized.map((zone) => (
+							<span
+								className="threshold-scale-zone"
+								key={zone.label}
+								data-tone={zone.tone}
+								style={{ width: `${zone.width}%` }}
+							/>
+						))}
+						<span
+							className="threshold-scale-pin"
+							data-tone={reading.tone}
+							style={{ left: `${Math.min(reading.value / max, 1) * 100}%` }}
+						/>
+					</span>
+					<b className="threshold-scale-value" data-tone={reading.tone}>
+						{reading.display}
+					</b>
+				</div>
+			))}
+			<div className="threshold-scale-row is-axis" aria-hidden="true">
+				<span className="threshold-scale-label" />
+				<span className="threshold-scale-axis">
+					{sized.map((zone) => (
+						<span key={zone.label} data-tone={zone.tone} style={{ width: `${zone.width}%` }}>
+							{zone.label}
+						</span>
+					))}
+					{ticks?.map((tick) => (
+						<i key={tick.label} style={{ left: `${(tick.at / max) * 100}%` }}>
+							{tick.label}
+						</i>
+					))}
+				</span>
+				<span className="threshold-scale-value" />
+			</div>
+		</div>
+	);
+}

package/src/components/index.ts

@@ -1 +1,34 @@
+export { Callout, type CalloutProps } from "./Callout";
+export { Checklist, type ChecklistItem, type ChecklistProps } from "./Checklist";
+export { Collapsible, type CollapsibleProps } from "./Collapsible";
+export {
+	ColumnChart,
+	type ColumnChartBar,
+	type ColumnChartGroup,
+	type ColumnChartProps,
+} from "./ColumnChart";
+export {
+	DataTable,
+	type DataTableCell,
+	type DataTableColumn,
+	type DataTableProps,
+	type DataTableRow,
+	type DataTableValueCell,
+	type SortDirection,
+} from "./DataTable";
 export { NotFound, type NotFoundProps } from "./NotFound";
+export { StackedBar, type StackedBarProps, type StackedBarSegment } from "./StackedBar";
+export {
+	type StatDelta,
+	type StatDirection,
+	type StatItem,
+	StatRow,
+	type StatRowProps,
+} from "./StatRow";
+export {
+	type ThresholdReading,
+	ThresholdScale,
+	type ThresholdScaleProps,
+	type ThresholdZone,
+} from "./ThresholdScale";
+export type { Tone } from "./tone";

package/src/components/tone.ts

@@ -0,0 +1,7 @@
+/**
+ * How a figure, a mark, or a bar reads: good, a warning, broken, plain
+ * information, or quiet. A component sets it as `data-tone`, and
+ * `styles/components.css` turns it into `--tone`, `--tone-fill`, and
+ * `--tone-bg` for whatever sits inside.
+ */
+export type Tone = "good" | "warn" | "bad" | "info" | "muted";

package/src/styles/components.css

@@ -17,4 +17,589 @@
 	.mkt .not-found-closing .cta-row {
 		margin-top: 22px;
 	}
+
+	/* ---- Tones: the one palette this package carries, because good, a
+	   warning, and broken read green, amber, and red whatever the brand is.
+	   A site's theme may restate any of these on .mkt. A component sets
+	   data-tone, and --tone, --tone-fill, and --tone-bg follow. ---- */
+	.mkt {
+		--tone-good: #1b7f3b;
+		--tone-good-fill: #37a35c;
+		--tone-good-bg: #eaf6ee;
+		--tone-warn: #a84500;
+		--tone-warn-fill: #e8a317;
+		--tone-warn-bg: #fff3df;
+		--tone-bad: #b3261e;
+		--tone-bad-fill: #d9483f;
+		--tone-bad-bg: #fdecea;
+	}
+	.mkt [data-tone="good"] {
+		--tone: var(--tone-good);
+		--tone-fill: var(--tone-good-fill);
+		--tone-bg: var(--tone-good-bg);
+	}
+	.mkt [data-tone="warn"] {
+		--tone: var(--tone-warn);
+		--tone-fill: var(--tone-warn-fill);
+		--tone-bg: var(--tone-warn-bg);
+	}
+	.mkt [data-tone="bad"] {
+		--tone: var(--tone-bad);
+		--tone-fill: var(--tone-bad-fill);
+		--tone-bg: var(--tone-bad-bg);
+	}
+	.mkt [data-tone="info"] {
+		--tone: var(--primary);
+		--tone-fill: var(--primary-bright);
+		--tone-bg: var(--primary-tint);
+	}
+	.mkt [data-tone="muted"] {
+		--tone: var(--neutral-500);
+		--tone-fill: var(--neutral-200);
+		--tone-bg: var(--surface-alt);
+	}
+
+	/* ---- StatRow: large figures, each over what it counts, its period,
+	   and its comparisons ---- */
+	.mkt .stat-row {
+		display: grid;
+		gap: 24px;
+		grid-template-columns: repeat(2, minmax(0, 1fr));
+	}
+	@media (min-width: 760px) {
+		.mkt .stat-row {
+			grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+		}
+	}
+	.mkt .stat-row.is-center .stat {
+		text-align: center;
+	}
+	.mkt .stat .num {
+		display: flex;
+		align-items: center;
+		gap: 0.12em;
+		font-size: clamp(2.2rem, 5vw, 3rem);
+		font-weight: 800;
+		letter-spacing: -0.03em;
+		color: var(--tone, var(--primary));
+		line-height: 1;
+		font-variant-numeric: tabular-nums;
+	}
+	.mkt .stat-row.is-center .stat .num {
+		justify-content: center;
+	}
+	.mkt .stat-trend {
+		width: 0.8em;
+		height: 0.8em;
+		flex: none;
+	}
+	.mkt .stat .lbl {
+		font-size: 0.95rem;
+		font-weight: 650;
+		color: var(--ink);
+		margin-top: 8px;
+	}
+	.mkt .stat-period {
+		margin-left: 0.5em;
+		font-weight: 400;
+		color: var(--neutral-500);
+	}
+	.mkt .stat-delta {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: baseline;
+		gap: 2px 6px;
+		margin-top: 4px;
+		font-size: 0.82rem;
+		line-height: 1.35;
+		color: var(--neutral-500);
+		font-variant-numeric: tabular-nums;
+	}
+	.mkt .stat-delta-change {
+		display: inline-flex;
+		align-items: center;
+		gap: 2px;
+		font-weight: 700;
+		color: var(--tone);
+	}
+	.mkt .stat-delta-change svg {
+		align-self: center;
+	}
+	.mkt .stat-delta-basis {
+		text-decoration: none;
+	}
+	.mkt .stat .note {
+		font-size: 0.8rem;
+		color: var(--neutral-500);
+		margin-top: 4px;
+	}
+
+	/* ---- Collapsible: a labeled line that opens to the detail behind it ---- */
+	.mkt .collapsible > summary {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 14px;
+		cursor: pointer;
+		list-style: none;
+	}
+	.mkt .collapsible > summary::-webkit-details-marker {
+		display: none;
+	}
+	.mkt .collapsible-text {
+		display: flex;
+		flex-direction: column;
+		gap: 2px;
+		min-width: 0;
+	}
+	.mkt .collapsible-label {
+		font-weight: 650;
+		color: var(--ink);
+	}
+	.mkt .collapsible-summary {
+		color: var(--ink-soft);
+		text-wrap: pretty;
+	}
+	.mkt .collapsible > summary:hover .collapsible-label {
+		color: var(--primary);
+	}
+	.mkt .collapsible-chevron {
+		flex: none;
+		color: var(--neutral-500);
+		transition: transform 0.15s;
+	}
+	.mkt .collapsible[open] > summary .collapsible-chevron {
+		transform: rotate(180deg);
+	}
+	.mkt .collapsible-body {
+		margin-top: 12px;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.mkt .collapsible-chevron {
+			transition: none;
+		}
+	}
+	/* Paper cannot be clicked, so a printed collapsible is open. */
+	@media print {
+		.mkt .collapsible::details-content {
+			content-visibility: visible;
+			display: block;
+		}
+		.mkt .collapsible-chevron {
+			display: none;
+		}
+	}
+
+	/* ---- Callout: an icon in its tone beside the title, the explainer
+	   under it; boxed, it sits apart on a tinted ground ---- */
+	.mkt .callout {
+		display: grid;
+		grid-template-columns: auto minmax(0, 1fr);
+		gap: 10px;
+		align-items: start;
+	}
+	.mkt .callout-icon {
+		margin-top: 0.15em;
+		color: var(--tone);
+		flex: none;
+	}
+	.mkt .callout-title {
+		font-weight: 650;
+		color: var(--ink);
+		text-wrap: pretty;
+	}
+	.mkt .callout-body {
+		margin-top: 2px;
+		color: var(--ink-soft);
+		text-wrap: pretty;
+	}
+	.mkt .callout.is-box {
+		padding: 14px 16px;
+		border-radius: var(--radius-sm);
+		background: var(--tone-bg);
+		border: 1px solid color-mix(in srgb, var(--tone-fill) 45%, transparent);
+	}
+
+	/* ---- Checklist: checks passed or failed, two columns when there is room ---- */
+	.mkt .checklist {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: grid;
+		grid-template-columns: minmax(0, 1fr);
+		gap: 12px 28px;
+	}
+	@media print, (min-width: 721px) {
+		.mkt .checklist {
+			grid-template-columns: repeat(2, minmax(0, 1fr));
+		}
+	}
+	.mkt .checklist li {
+		display: grid;
+		grid-template-columns: auto minmax(0, 1fr);
+		gap: 10px;
+		align-items: start;
+		line-height: 1.4;
+	}
+	.mkt .checklist li > svg {
+		margin-top: 0.1em;
+		color: var(--tone);
+	}
+	.mkt .checklist-label {
+		display: block;
+		font-weight: 600;
+		color: var(--ink);
+	}
+	.mkt .checklist li[data-tone="bad"] .checklist-label {
+		color: var(--tone);
+	}
+	.mkt .checklist-detail {
+		display: block;
+		color: var(--ink-soft);
+	}
+
+	/* ---- The charts' shared key: a swatch, a figure, a label ---- */
+	.mkt .chart-key {
+		list-style: none;
+		margin: 10px 0 0;
+		padding: 0;
+		display: flex;
+		flex-wrap: wrap;
+		gap: 5px 20px;
+		font-size: 0.82rem;
+		color: var(--ink-soft);
+	}
+	.mkt .chart-key li {
+		display: inline-flex;
+		align-items: baseline;
+		gap: 7px;
+	}
+	.mkt .chart-key b {
+		font-weight: 650;
+		color: var(--ink);
+		font-variant-numeric: tabular-nums;
+	}
+	.mkt .chart-swatch {
+		width: 10px;
+		height: 10px;
+		border-radius: 3px;
+		background: var(--tone-fill);
+		align-self: center;
+		flex: none;
+	}
+
+	/* ---- StackedBar: one bar, the parts of a whole ---- */
+	.mkt .stacked-bar-track {
+		display: flex;
+		gap: 2px;
+		height: 16px;
+		border-radius: 999px;
+		overflow: hidden;
+	}
+	.mkt .stacked-bar-track span {
+		background: var(--tone-fill);
+		min-width: 4px;
+	}
+
+	/* ---- ColumnChart: a bar a period, the periods in labeled groups ---- */
+	.mkt .column-chart-plot {
+		display: flex;
+		align-items: flex-end;
+		gap: 12px;
+		min-width: 0;
+	}
+	.mkt .column-chart-group {
+		flex: 1 1 0;
+		min-width: 0;
+	}
+	.mkt .column-chart-bars {
+		display: flex;
+		align-items: flex-end;
+		gap: 3px;
+	}
+	.mkt .column-chart-col {
+		flex: 1 1 0;
+		min-width: 0;
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 3px;
+	}
+	.mkt .column-chart-value {
+		font-size: 0.64rem;
+		font-variant-numeric: tabular-nums;
+		color: var(--ink-soft);
+		white-space: nowrap;
+	}
+	.mkt .column-chart-bar {
+		width: 100%;
+		max-width: 48px;
+		border-radius: 4px 4px 0 0;
+		background: var(--tone-fill);
+	}
+	.mkt .column-chart-label {
+		font-size: 0.66rem;
+		color: var(--ink-soft);
+		white-space: nowrap;
+	}
+	.mkt .column-chart-group-label {
+		display: flex;
+		flex-wrap: wrap;
+		justify-content: center;
+		gap: 0 6px;
+		margin-top: 6px;
+		padding-top: 5px;
+		border-top: 1px solid var(--neutral-200);
+		font-family: var(--font-mono);
+		font-size: 0.66rem;
+		letter-spacing: 0.04em;
+		color: var(--neutral-500);
+		white-space: nowrap;
+	}
+	.mkt .column-chart-group-label b {
+		font-family: var(--font-sans);
+		font-size: 0.8rem;
+		letter-spacing: 0;
+		font-weight: 650;
+		color: var(--ink);
+		font-variant-numeric: tabular-nums;
+	}
+
+	/* ---- ThresholdScale: zones, and a pin a reading ---- */
+	.mkt .threshold-scale {
+		display: flex;
+		flex-direction: column;
+		gap: 10px;
+	}
+	.mkt .threshold-scale-row {
+		display: grid;
+		grid-template-columns: 4.4em minmax(0, 1fr) 3.4em;
+		gap: 10px;
+		align-items: center;
+	}
+	.mkt .threshold-scale-label {
+		color: var(--ink-soft);
+	}
+	.mkt .threshold-scale-track {
+		position: relative;
+		display: flex;
+		gap: 2px;
+		height: 12px;
+	}
+	.mkt .threshold-scale-zone {
+		background: var(--tone-fill);
+		opacity: 0.32;
+	}
+	.mkt .threshold-scale-zone:first-child {
+		border-radius: 999px 0 0 999px;
+	}
+	.mkt .threshold-scale-zone:nth-last-child(2) {
+		border-radius: 0 999px 999px 0;
+	}
+	.mkt .threshold-scale-pin {
+		position: absolute;
+		top: 50%;
+		width: 18px;
+		height: 18px;
+		margin: -9px 0 0 -9px;
+		border-radius: 50%;
+		background: var(--tone-fill);
+		border: 3px solid var(--card);
+		box-shadow: 0 0 0 1.5px var(--tone-fill);
+	}
+	.mkt .threshold-scale-value {
+		font-weight: 700;
+		font-variant-numeric: tabular-nums;
+		color: var(--tone);
+		text-align: right;
+	}
+	.mkt .threshold-scale-axis {
+		position: relative;
+		display: flex;
+		gap: 2px;
+		height: 2.3em;
+		font-size: 0.8rem;
+	}
+	.mkt .threshold-scale-axis > span {
+		color: var(--tone);
+		font-weight: 600;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+	.mkt .threshold-scale-axis > i {
+		position: absolute;
+		top: 1.25em;
+		transform: translateX(-50%);
+		font-style: normal;
+		font-family: var(--font-mono);
+		font-size: 0.72rem;
+		color: var(--neutral-500);
+		white-space: nowrap;
+	}
+
+	/* ---- DataTable: on a phone each row stacks, its facts wearing their
+	   column's label, and a dropdown sorts; wide, it is a table whose
+	   headings sort ---- */
+	.mkt .data-table table,
+	.mkt .data-table tbody {
+		display: block;
+		width: 100%;
+	}
+	.mkt .data-table thead {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+	}
+	.mkt .data-table-sort {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		margin-bottom: 8px;
+		font-size: 0.85rem;
+		color: var(--ink-soft);
+	}
+	.mkt .data-table-sort select {
+		font: inherit;
+		color: var(--ink);
+		background: var(--card);
+		border: 1px solid var(--neutral-200);
+		border-radius: var(--radius-sm);
+		padding: 5px 8px;
+		max-width: 100%;
+	}
+	.mkt .data-table tbody tr {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: 4px 18px;
+		padding: 9px 0;
+		border-bottom: 1px solid var(--neutral-100);
+		line-height: 1.35;
+	}
+	.mkt .data-table tbody tr:first-child {
+		border-top: 1.5px solid var(--ink);
+	}
+	.mkt .data-table tbody tr:last-child {
+		border-bottom: 0;
+		padding-bottom: 0;
+	}
+	.mkt .data-table tbody th {
+		width: 100%;
+		text-align: left;
+		font-weight: 400;
+	}
+	.mkt .data-table td {
+		display: inline-flex;
+		align-items: center;
+		gap: 6px;
+		font-variant-numeric: tabular-nums;
+	}
+	.mkt .data-table td::before {
+		content: attr(data-label);
+		font-family: var(--font-mono);
+		font-size: 0.7rem;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+		color: var(--neutral-500);
+	}
+	@media print, (min-width: 721px) {
+		.mkt .data-table-sort {
+			display: none;
+		}
+		.mkt .data-table table {
+			display: table;
+			border-collapse: collapse;
+		}
+		.mkt .data-table tbody {
+			display: table-row-group;
+		}
+		.mkt .data-table thead {
+			position: static;
+			width: auto;
+			height: auto;
+			overflow: visible;
+			clip: auto;
+		}
+		.mkt .data-table tbody tr {
+			display: table-row;
+			padding: 0;
+			border: 0;
+		}
+		.mkt .data-table tbody tr:first-child {
+			border-top: 0;
+		}
+		.mkt .data-table th,
+		.mkt .data-table td {
+			display: table-cell;
+			padding: 7px 14px 7px 0;
+			border-bottom: 1px solid var(--neutral-100);
+			text-align: left;
+			vertical-align: middle;
+			font-weight: 400;
+		}
+		.mkt .data-table tbody th {
+			width: auto;
+		}
+		.mkt .data-table td::before {
+			content: none;
+		}
+		.mkt .data-table th:last-child,
+		.mkt .data-table td:last-child {
+			padding-right: 0;
+		}
+		.mkt .data-table [data-align="center"] {
+			text-align: center;
+		}
+		.mkt .data-table [data-align="right"] {
+			text-align: right;
+		}
+		.mkt .data-table thead th {
+			padding-top: 0;
+			padding-bottom: 8px;
+			border-bottom: 1.5px solid var(--ink);
+			font-family: var(--font-mono);
+			font-size: 0.72rem;
+			letter-spacing: 0.08em;
+			text-transform: uppercase;
+			color: var(--ink-soft);
+			white-space: nowrap;
+			vertical-align: bottom;
+		}
+		.mkt .data-table thead th button {
+			display: inline-flex;
+			align-items: center;
+			gap: 4px;
+			padding: 0;
+			border: 0;
+			background: none;
+			font: inherit;
+			letter-spacing: inherit;
+			text-transform: inherit;
+			color: inherit;
+			cursor: pointer;
+		}
+		.mkt .data-table thead th button:hover,
+		.mkt .data-table thead th button[data-active] {
+			color: var(--primary);
+		}
+		.mkt .data-table thead th button svg {
+			opacity: 0.55;
+		}
+		.mkt .data-table thead th button[data-active] svg {
+			opacity: 1;
+		}
+		.mkt .data-table tbody tr:last-child th,
+		.mkt .data-table tbody tr:last-child td {
+			border-bottom: 0;
+		}
+	}
+	@media print {
+		.mkt .data-table thead th button svg {
+			display: none;
+		}
+	}
 }