@atelic-action/ui 0.7.2 → 0.9.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`, `StarRating`), 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` |
@@ -50,6 +50,7 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | `@atelic-action/ui/styles/base.css` | Resets, the `.mkt` canvas, typography, and layout helpers |
 | `@atelic-action/ui/styles/chrome.css` | Styles for everything under `chrome` |
 | `@atelic-action/ui/styles/components.css` | Layout defaults for everything under `components` |
+| `@atelic-action/ui/styles/star-rating.css` | `StarRating`'s styles alone, for an app that wears none of the site chrome; `components.css` already imports it |
 
 Every component renders from props alone. None reads a config file or a router, so a site maps its own config onto the props in its shell:
 
@@ -247,6 +248,37 @@ 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 |
+| `StarRating` | A row of stars showing a rating in half star steps, and taking one when given `onChange` | Each star is two hit targets; picking the current rating clears it. Editable, it is one slider to a keyboard and a screen reader; read only, a picture named by the rating. `fillColor` and `outlineColor` take any CSS color, `size` and `max` set the star and the scale |
+
+**StarRating outside a site.** It is the one component that does not sit under `.mkt` or read a theme token: its styles are in `styles/star-rating.css`, and its two colors are the `--star-fill` and `--star-outline` custom properties, falling back to the text color and a faint tint of it. An app that installs the package for this component alone imports that one sheet, not `components.css`.
+
+**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.
+
+## The Gallery
+
+`gallery/` is one static page, The Components, that shows every page component on its own with made up data for a fictional bakery, wearing the practice's own palette and type. It lives at [ui.atelic.me](https://ui.atelic.me), noindexed and disallowed in its `robots.txt`, since it is for the people building with the package and never search inventory. It imports the components and stylesheets from `src/` by relative path rather than from npm, so it always shows the code in the repo, and it reads the package name and version from `package.json` at build time. It sits outside `src/`, so it is never published.
+
+```bash
+bun run gallery:dev    # a dev server on the repo's own source
+bun run gallery:build  # the static page, written to gallery/dist
+```
+
+`vercel.json` builds it the same way and serves `gallery/dist`. Typecheck and lint cover it, and CI builds it, so a component change that breaks the gallery fails CI. **A new page component gets a gallery section in the same change**, with each of its meaningfully different forms shown.
+
 ## 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.9.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, and the component library they install",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -28,13 +28,16 @@
 		"./styles/base.css": "./src/styles/base.css",
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./styles/components.css": "./src/styles/components.css",
+		"./styles/star-rating.css": "./src/styles/star-rating.css",
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"lint": "biome check .",
 		"lint:fix": "biome check . --write",
-		"typecheck": "tsc --noEmit",
-		"test:run": "vitest run"
+		"typecheck": "tsc --noEmit && tsc --noEmit -p gallery",
+		"test:run": "vitest run",
+		"gallery:dev": "vite gallery",
+		"gallery:build": "vite build gallery"
 	},
 	"peerDependencies": {
 		"lucide-react": "^1.23.0",
@@ -47,11 +50,13 @@
 		"@testing-library/react": "^16.0.1",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
+		"@vitejs/plugin-react": "^6.1.1",
 		"jsdom": "^25.0.1",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"typescript": "^5.6.3",
+		"vite": "^8.3.2",
 		"vitest": "^4.0.0"
 	},
 	"trustedDependencies": [

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>
+	);
+}