@atelic-action/ui 0.3.0 → 0.4.0

package/README.md

@@ -145,6 +145,31 @@ const html = renderEmail({
 });
 ```
 
+### Mobile First
+
+Runner emails are mobile first. A layout that squashes on a phone is fixed here, in the components every runner shares, never in a report page. A fixed column table is for numbers alone and never carries a name; names go in a `RecordStack`.
+
+`RecordStack` takes `records`, each a `RecordStackItem` (`title`, `url`, `meta`, `note`), 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. `recordStackText(records)` is its plain text twin: each title on its own line under a two space indent, the meta and the note wrapped under a four space indent, a blank line between records, and no line past `textWidth` (68 columns, indent included).
+
+`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 and muted under its label.
+
+```tsx
+const records = [
+	{ title: "Pinewood Cabinetry", url: "https://example.test", meta: ["Lead", "Longmont", "fit 14"], note: "Answered the audit inside a day." },
+];
+
+<Card>
+	<Row last={false}>
+		<StatStrip stats={[{ n: 6, label: "Lead", delta: "+3 · +12%" }, { n: 2, label: "MQL" }]} />
+	</Row>
+	<Row last>
+		<RecordStack records={records} />
+	</Row>
+</Card>;
+
+const text = recordStackText(records);
+```
+
 `renderEmail` builds the document shell itself and puts only the rows through React, because React emits no doctype, React 19 hoists and reorders head tags, and it would escape the `>` in `details>summary`. `renderFailureEmail` is the same shell around `FailurePage`. Both live at `@atelic-action/ui/email/render`, apart from the components, so a site that mounts a component on a page never pulls React's server renderer into its browser bundle.
 
 ### The Mapping
@@ -178,7 +203,8 @@ Where the jq takes a pre rendered html string (`$rows`, `$body_html`, `$cells_ht
 | `sub_eyebrow` | `SubEyebrow` | `text` |
 | `badge` | `Badge` | `letter` |
 | `day_strip` | `DayStrip` | `days`, `last` |
-| `stat_strip` | `StatStrip` | `stats` |
+| `stat_strip` | `StatStrip` | `stats`, each with an optional `delta` (the component wraps where the jq does not) |
+| none | `RecordStack` | `records` (born here on 2026-09-24, with no jq counterpart) |
 | `records` | `Records` | `columns`, `rows`; a cell's `html` is a `ReactNode` |
 | `masthead` | `Masthead` | `title`, `wordmark` (defaults to `atelic`) |
 | `title_card` | `TitleCard` | `eyebrowText`, `headlineLines`, `lede`, `stats` (the rows under the lede, in place of the jq's `$stats_html`) |
@@ -186,7 +212,7 @@ Where the jq takes a pre rendered html string (`$rows`, `$body_html`, `$cells_ht
 | `page` | `renderEmail` | `title`, `preheader`, `children`, `palette`, `fonts` |
 | `failure_page` | `renderFailureEmail`, or `FailurePage` as body rows | `runnerTitle`, `eyebrowText`, `reason`, `logTail` |
 
-The plain text alternative part ports as plain functions with no React anywhere in them: `spaces`, `rpad`, `lpad`, `wrap`, `textRule`, `textSection`, `textRead`, `textBar`, `textTarget`, `textTableGrid`, `textTable`, plus `asciiUpcase` and `asciiDowncase`. Every width counts Unicode codepoints, the way jq's `length` does.
+The plain text alternative part ports as plain functions with no React anywhere in them: `spaces`, `rpad`, `lpad`, `wrap`, `textRule`, `textSection`, `textRead`, `textBar`, `textTarget`, `textTableGrid`, `textTable`, `recordStackText`, `textWidth`, plus `asciiUpcase` and `asciiDowncase`. Every width counts Unicode codepoints, the way jq's `length` does.
 
 `tst/email/expected/` holds frozen goldens generated from the jq library, and the component tests compare the rendered DOM against them. See that folder's README before touching one.
 

package/package.json

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

package/src/email/index.ts

@@ -56,6 +56,8 @@ export {
 	type GroupRowProps,
 	ReadBlock,
 	type ReadBlockProps,
+	RecordStack,
+	type RecordStackProps,
 	Records,
 	type RecordsCell,
 	type RecordsColumn,
@@ -77,6 +79,8 @@ export {
 	asciiDowncase,
 	asciiUpcase,
 	lpad,
+	type RecordStackItem,
+	recordStackText,
 	rpad,
 	spaces,
 	type TextTarget,
@@ -87,6 +91,7 @@ export {
 	textTable,
 	textTableGrid,
 	textTarget,
+	textWidth,
 	wrap,
 } from "./text";
 export {

package/src/email/scoreboard.tsx

@@ -1,4 +1,5 @@
 import { Fragment, type ReactNode } from "react";
+import type { RecordStackItem } from "./text";
 import { eyebrowStyle, tableReset, useEmailTheme } from "./theme";
 
 /*
@@ -323,50 +324,159 @@ export function DayStrip({ days, last }: DayStripProps) {
 	);
 }
 
-export type StatStripEntry = { n: string | number; label: string };
+export type StatStripEntry = {
+	n: string | number;
+	label: string;
+	/** A change beside the number, small and muted under the label: "+3 · +12%". */
+	delta?: string;
+};
 export type StatStripProps = { stats: StatStripEntry[] };
 
-/** A row of big numbers over eyebrow labels. */
+/**
+ * A strip of big numbers over eyebrow labels. Each stat is an inline block
+ * cell with a floor on its width inside one centered cell, so six or seven
+ * stats flow onto a second row on a phone instead of shrinking to nothing.
+ */
 export function StatStrip({ stats }: StatStripProps) {
 	const { palette, fonts } = useEmailTheme();
-	const width = `${Math.floor(100 / stats.length)}%`;
+	const share = `${Math.floor(100 / Math.max(stats.length, 1))}%`;
 	return (
 		<table {...tableReset} width="100%">
 			<tbody>
 				<tr>
-					{stats.map((entry, i) => (
-						<td
-							// biome-ignore lint/suspicious/noArrayIndexKey: a stat's position is its identity
-							key={i}
-							width={width}
-							style={{
-								padding: "12px 6px 10px",
-								borderTop: `2px solid ${palette.ink}`,
-								textAlign: "center",
-								verticalAlign: "top",
-							}}
-						>
-							<span
+					<td align="center" style={{ textAlign: "center" }}>
+						{stats.map((entry, i) => (
+							<div
+								// biome-ignore lint/suspicious/noArrayIndexKey: a stat's position is its identity
+								key={i}
 								style={{
-									fontFamily: fonts.sans,
-									fontSize: "22px",
-									fontWeight: "600",
-									letterSpacing: "-0.02em",
-									color: palette.ink,
+									display: "inline-block",
+									width: share,
+									minWidth: "88px",
+									boxSizing: "border-box",
+									verticalAlign: "top",
+									padding: "12px 6px 10px",
+									borderTop: `2px solid ${palette.ink}`,
+									textAlign: "center",
 								}}
 							>
-								{String(entry.n)}
-							</span>
-							<br />
-							<span style={{ ...eyebrowStyle(fonts), color: palette.faint }}>{entry.label}</span>
-						</td>
-					))}
+								<span
+									style={{
+										fontFamily: fonts.sans,
+										fontSize: "22px",
+										fontWeight: "600",
+										letterSpacing: "-0.02em",
+										color: palette.ink,
+									}}
+								>
+									{String(entry.n)}
+								</span>
+								<br />
+								<span style={{ ...eyebrowStyle(fonts), color: palette.faint }}>{entry.label}</span>
+								{entry.delta ? (
+									<>
+										<br />
+										<span
+											style={{ fontFamily: fonts.mono, fontSize: "11px", color: palette.faint }}
+										>
+											{entry.delta}
+										</span>
+									</>
+								) : null}
+							</div>
+						))}
+					</td>
 				</tr>
 			</tbody>
 		</table>
 	);
 }
 
+export type { RecordStackItem };
+export type RecordStackProps = { records: RecordStackItem[] };
+
+/**
+ * One record per row, stacked: the title on its own line, a mono meta line
+ * under it, an optional note under that. No column cells and no fixed widths,
+ * so a name of any length wraps instead of squashing on a phone. A fixed
+ * column table is for numbers alone; names go here.
+ */
+export function RecordStack({ records }: RecordStackProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<table {...tableReset} width="100%" style={{ fontFamily: fonts.sans, color: palette.ink }}>
+			<tbody>
+				{records.map((record, i) => {
+					const last = i === records.length - 1;
+					const meta = record.meta.filter((m) => m !== "");
+					return (
+						// biome-ignore lint/suspicious/noArrayIndexKey: a record's position is its identity
+						<tr key={i}>
+							<td
+								style={{
+									padding: `${i === 0 ? "0" : "12px"} 0 ${last ? "0" : "12px"}`,
+									verticalAlign: "top",
+									...(last ? {} : { borderBottom: `1px solid ${palette.line}` }),
+								}}
+							>
+								<div
+									style={{
+										fontSize: "15px",
+										fontWeight: "600",
+										lineHeight: "1.35",
+										color: palette.ink,
+										wordBreak: "break-word",
+									}}
+								>
+									{record.url ? (
+										<a
+											href={record.url}
+											style={{
+												color: palette.ink,
+												textDecoration: "none",
+												borderBottom: `1px solid ${palette.accent}`,
+											}}
+										>
+											{record.title}
+										</a>
+									) : (
+										record.title
+									)}
+								</div>
+								{meta.length > 0 ? (
+									<div
+										style={{
+											fontFamily: fonts.mono,
+											fontSize: "12px",
+											lineHeight: "1.5",
+											color: palette.faint,
+											marginTop: "4px",
+										}}
+									>
+										{meta.join(" · ")}
+									</div>
+								) : null}
+								{record.note ? (
+									<div
+										style={{
+											fontSize: "13px",
+											lineHeight: "1.5",
+											color: palette.dim,
+											marginTop: "6px",
+										}}
+									>
+										{record.note}
+									</div>
+								) : null}
+							</td>
+						</tr>
+					);
+				})}
+			</tbody>
+		</table>
+	);
+}
+
 export type RecordsColumn = {
 	label: string;
 	/** Aligns the column right and keeps its cells on one line. */

package/src/email/text.ts

@@ -37,16 +37,25 @@ export function lpad(value: string, width: number): string {
 	return spaces(width - codepoints(value)) + value;
 }
 
-/** Prose wrapped at 66 columns under a two space indent. */
-export function wrap(text: string): string {
+/** The widest a plain text line runs, indent included: two spaces and 66 columns of prose. */
+export const textWidth = 68;
+
+/** Prose broken into lines of at most `columns` codepoints, each under `indent`. */
+function wrapIndented(text: string, indent: number): string {
+	const columns = textWidth - indent;
 	const lines = [""];
 	for (const word of text.split(" ")) {
 		const last = lines[lines.length - 1];
 		if (codepoints(last) === 0) lines[lines.length - 1] = word;
-		else if (codepoints(last) + 1 + codepoints(word) > 66) lines.push(word);
+		else if (codepoints(last) + 1 + codepoints(word) > columns) lines.push(word);
 		else lines[lines.length - 1] = `${last} ${word}`;
 	}
-	return lines.map((line) => `  ${line}`).join("\n");
+	return lines.map((line) => `${spaces(indent)}${line}`).join("\n");
+}
+
+/** Prose wrapped at 66 columns under a two space indent. */
+export function wrap(text: string): string {
+	return wrapIndented(text, 2);
 }
 
 export const textRule = "=".repeat(64);
@@ -114,3 +123,34 @@ export function textTableGrid(
 export function textTable(cols: string[], rows: string[][], right: number[]): string {
 	return textTableGrid(cols, rows, right, null);
 }
+
+/**
+ * One record in a stack: what `RecordStack` renders and `recordStackText`
+ * writes. It lives here, with no React, so a plain text renderer can import it.
+ */
+export type RecordStackItem = {
+	title: string;
+	/** Links the title when set; the plain text twin leaves it out. */
+	url?: string | null;
+	/** Facts joined by a middle dot on the line under the title; empty items drop. */
+	meta: string[];
+	note?: string;
+};
+
+/**
+ * The plain text twin of `RecordStack`: each title on its own line under a
+ * two space indent, the meta joined by middle dots and the note beneath it,
+ * both wrapped under a four space indent, a blank line between records. No
+ * line runs past `textWidth`.
+ */
+export function recordStackText(records: RecordStackItem[]): string {
+	return records
+		.map((record) => {
+			const lines = [wrapIndented(record.title, 2)];
+			const meta = record.meta.filter((m) => m !== "");
+			if (meta.length > 0) lines.push(wrapIndented(meta.join(" · "), 4));
+			if (record.note) lines.push(wrapIndented(record.note, 4));
+			return lines.join("\n");
+		})
+		.join("\n\n");
+}