@atelic-action/ui 0.1.0 → 0.2.0

package/README.md

@@ -40,6 +40,9 @@ Both package sheets sit inside `@layer atelic-ui`, so any rule a site writes out
 | Import | Exports |
 |---|---|
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
+| `@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` |
 | `@atelic-action/ui/hooks` | `useScrollSpy` and its `PageStop` type |
 | `@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` |
@@ -66,6 +69,96 @@ import { Footer, SiteHeader, SkipLink, StickyCTABar } from "@atelic-action/ui/ch
 
 The menu is a native `<dialog>` opened with `showModal()`, so Escape, focus containment, and focus return come from the browser.
 
+## Email
+
+`@atelic-action/ui/email` is the runner email design as React components, ported one to one from the jq library the runners compose their mail from (homebase `runners/lib/email.jq`). The components are born inline: every layout is a table, every style is an inline style object, and there is no CSS file and no `className`, because Gmail strips a style block and ignores media queries on some accounts. The same components therefore mount on a web page as happily as they render into a mail client.
+
+Colors and fonts come from context, so a client branded email passes its own palette:
+
+```tsx
+import { Card, Eyebrow, Footer, Item, Masthead, TitleCard } from "@atelic-action/ui/email";
+import { renderEmail } from "@atelic-action/ui/email/render";
+import { atelicPalette } from "@atelic-action/ui/tokens";
+
+const html = renderEmail({
+	title: "Week 40 Recruiter",
+	preheader: "Three roles cleared every filter.",
+	palette: { ...atelicPalette, accent: "#0B6E4F" },
+	children: (
+		<>
+			<Masthead title="Recruiter" />
+			<TitleCard
+				eyebrowText="Week 40"
+				headlineLines={["Three cleared", "every filter."]}
+				lede="Two of them are remote."
+			/>
+			<Eyebrow text="Shortlist" />
+			<Card>
+				<Item
+					name="Pinewood Cabinetry"
+					right="4.5"
+					subparts={["Staff engineer", "Remote"]}
+					body="They answered inside a day."
+					linkText="Posting"
+					url="https://example.test/posting"
+					last
+				/>
+			</Card>
+			<Footer meta="Run 2026-10-05" />
+		</>
+	),
+});
+```
+
+`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
+
+Where the jq takes a pre rendered html string (`$rows`, `$body_html`, `$cells_html`, a records cell's `html`, a stat's caption), the React prop is `children` or a `ReactNode`. Where the jq escapes a string argument, the prop is a plain string and React does the escaping.
+
+| jq Function | Component | Props |
+|---|---|---|
+| `eyebrow` | `Eyebrow` | `text` |
+| `card` | `Card` | `children` |
+| `fold` | `Fold` | `summary`, `children` |
+| `big_fold` | `BigFold` | `summary`, `count` (a `ReactNode`, absent for the jq's `""`), `children` |
+| `title_line` | `TitleLine` | `name`, `right` |
+| `item` | `Item` | `name`, `right`, `subparts`, `body`, `foldLabel`, `foldBody`, `linkText`, `url`, `last` |
+| `note` | `Note` | `eyebrowText`, `text`, `accented`, `last` |
+| `empty_row` | `EmptyRow` | `text` |
+| `stat` | `Stat` | `n`, `caption` (a `ReactNode`: the jq takes raw html here) |
+| `stats_row` | `StatsRow` | `children`, the `Stat` cells |
+| `list` | `List` | `fontSize`, `children` |
+| `list_row` | `ListRow` | `children` |
+| `lead_row` | `LeadRow` | `lead`, `rest` |
+| `row` | `Row` | `last`, `children` |
+| `fold_row` | `FoldRow` | `last`, `children` |
+| `mono_table` | `MonoTable` | `headers`, `rows` |
+| `bar` | `Bar` | `logged`, `target` |
+| `group_row` | `GroupRow` | `text`, `first` |
+| `target_row` | `TargetRow` | `text`, `logged`, `target` (null is a count with nothing to measure it against), `note`, `last` |
+| `scoreboard` | `Scoreboard` | `children`, the `GroupRow` and `TargetRow` rows |
+| `what_moved` | `WhatMoved` | `items`, `note` |
+| `read_block` | `ReadBlock` | `text`, `divider` |
+| `sub_eyebrow` | `SubEyebrow` | `text` |
+| `badge` | `Badge` | `letter` |
+| `day_strip` | `DayStrip` | `days`, `last` |
+| `stat_strip` | `StatStrip` | `stats` |
+| `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`) |
+| `footer` | `Footer` | `meta` |
+| `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.
+
+`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.
+
+### Tokens
+
+`@atelic-action/ui/tokens` carries the palette and the font stacks with no React import, so a build script or a plain text renderer can read them. `toThemeCSS(palette)` writes the palette out as the site token declarations (`--surface`, `--surface-dark`, `--card`, `--ink`, `--primary`), and `themeTokenMap` exposes which palette key each token takes.
+
 ## 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.
@@ -76,4 +169,4 @@ The menu is a native `<dialog>` opened with `showModal()`, so Escape, focus cont
    git push origin v0.1.1
    ```
 
-3. The Publish workflow checks that the tag matches the version, runs the gates, and publishes to npm with provenance. It needs the `NPM_TOKEN` repository secret and the `@atelic` npm organization.
+3. The Publish workflow checks that the tag matches the version, runs the gates, and publishes to npm with provenance. It authenticates through npm trusted publishing (the package's Trusted Publisher names this repo and `publish.yml`, and its allowed actions must permit direct `npm publish`, since a configuration created after 2026-09-03 allows only `npm stage publish` by default), so no token is stored, and it needs npm 11.5.1 or later, which Node 24 ships.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, and the component library they install",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -19,7 +19,10 @@
 	],
 	"exports": {
 		"./chrome": "./src/chrome/index.ts",
+		"./email": "./src/email/index.ts",
+		"./email/render": "./src/email/render.tsx",
 		"./hooks": "./src/hooks/index.ts",
+		"./tokens": "./src/tokens/index.ts",
 		"./styles/base.css": "./src/styles/base.css",
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./package.json": "./package.json"

package/src/email/atoms.tsx

@@ -0,0 +1,465 @@
+import type { ReactNode } from "react";
+import { eyebrowStyle, tableReset, useEmailTheme } from "./theme";
+
+/*
+ * The atoms of the runner email, ported one to one from the atoms section of
+ * homebase `runners/lib/email.jq`. Every layout is a table and every style is
+ * inline, because Gmail strips a style block and ignores media queries on some
+ * accounts. Where the jq takes a pre rendered html string the React prop is
+ * `children` or a ReactNode; where the jq escapes a string argument the prop
+ * is a plain string and React does the escaping.
+ */
+
+export type EyebrowProps = { text: string };
+
+/** A section label between cards. */
+export function Eyebrow({ text }: EyebrowProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<tr>
+			<td style={{ padding: "36px 8px 12px", ...eyebrowStyle(fonts), color: palette.faint }}>
+				{text}
+			</td>
+		</tr>
+	);
+}
+
+export type CardProps = { children?: ReactNode };
+
+/** A card: paper on a hairline, rows inside. */
+export function Card({ children }: CardProps) {
+	const { palette } = useEmailTheme();
+	return (
+		<tr>
+			<td
+				style={{
+					background: palette.paper,
+					border: `1px solid ${palette.line}`,
+					borderRadius: "14px",
+					padding: "0",
+				}}
+			>
+				<table {...tableReset} width="100%">
+					<tbody>{children}</tbody>
+				</table>
+			</td>
+		</tr>
+	);
+}
+
+export type FoldProps = { summary: string; children?: ReactNode };
+
+/** A small disclosure inside a row: "+ what they do". */
+export function Fold({ summary, children }: FoldProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<details style={{ marginTop: "12px" }}>
+			<summary
+				style={{
+					fontFamily: fonts.mono,
+					fontSize: "12px",
+					color: palette.faint,
+					cursor: "pointer",
+				}}
+			>
+				{"+ "}
+				{summary}
+			</summary>
+			<div
+				style={{
+					fontSize: "14px",
+					lineHeight: "1.55",
+					color: palette.dim,
+					marginTop: "8px",
+				}}
+			>
+				{children}
+			</div>
+		</details>
+	);
+}
+
+export type BigFoldProps = { summary: string; count?: ReactNode; children?: ReactNode };
+
+/** A card level disclosure: a bold summary with an optional faint count beside it. */
+export function BigFold({ summary, count, children }: BigFoldProps) {
+	const { palette, fonts } = useEmailTheme();
+	const hasCount = count !== undefined && count !== null && count !== "";
+	return (
+		<details>
+			<summary
+				style={{
+					fontSize: "15px",
+					fontWeight: "600",
+					color: palette.ink,
+					cursor: "pointer",
+				}}
+			>
+				<span style={{ fontFamily: fonts.mono, color: palette.faint }}>+</span> {summary}
+				{hasCount ? (
+					<>
+						{" "}
+						<span
+							style={{
+								fontFamily: fonts.mono,
+								fontSize: "12px",
+								fontWeight: "400",
+								color: palette.faint,
+							}}
+						>
+							{count}
+						</span>
+					</>
+				) : null}
+			</summary>
+			{children}
+		</details>
+	);
+}
+
+export type TitleLineProps = { name: string; right: string };
+
+/** A name on the left and the one value that matters on the right, in the accent. */
+export function TitleLine({ name, right }: TitleLineProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<table {...tableReset} width="100%">
+			<tbody>
+				<tr>
+					<td
+						style={{
+							fontSize: "17px",
+							fontWeight: "600",
+							letterSpacing: "-0.02em",
+							color: palette.ink,
+							lineHeight: "1.2",
+						}}
+					>
+						{name}
+					</td>
+					<td
+						align="right"
+						style={{
+							fontFamily: fonts.mono,
+							fontSize: "12px",
+							color: palette.accent,
+							whiteSpace: "nowrap",
+							paddingLeft: "12px",
+						}}
+					>
+						{right}
+					</td>
+				</tr>
+			</tbody>
+		</table>
+	);
+}
+
+export type ItemProps = {
+	name: string;
+	right: string;
+	/** Facts joined by a middle dot. Null and empty parts drop, an empty list still renders the row. */
+	subparts: (string | null)[];
+	body?: string;
+	foldLabel?: string;
+	foldBody?: string;
+	linkText?: string;
+	url?: string;
+	/** Drops the bottom hairline so the card closes clean. */
+	last: boolean;
+};
+
+/**
+ * The workhorse row: title line, a dim subline of facts joined by middots, a
+ * body sentence or two, an optional fold, an optional link.
+ */
+export function Item({
+	name,
+	right,
+	subparts,
+	body,
+	foldLabel,
+	foldBody,
+	linkText,
+	url,
+	last,
+}: ItemProps) {
+	const { palette, fonts } = useEmailTheme();
+	const parts = subparts.filter((p) => p !== null && p !== "");
+	return (
+		<tr>
+			<td
+				style={{
+					padding: `22px 24px ${last ? "22px" : "20px"}`,
+					fontFamily: fonts.sans,
+					...(last ? {} : { borderBottom: `1px solid ${palette.line}` }),
+				}}
+			>
+				<TitleLine name={name} right={right} />
+				{subparts.length > 0 ? (
+					<div style={{ fontSize: "14px", color: palette.dim, marginTop: "3px" }}>
+						{parts.join(" · ")}
+					</div>
+				) : null}
+				{body ? (
+					<div
+						style={{
+							fontSize: "14px",
+							lineHeight: "1.55",
+							color: palette.ink,
+							marginTop: "12px",
+						}}
+					>
+						{body}
+					</div>
+				) : null}
+				{foldBody ? <Fold summary={foldLabel ?? ""}>{foldBody}</Fold> : null}
+				{url ? (
+					<div style={{ marginTop: "14px" }}>
+						<a
+							href={url}
+							style={{
+								fontSize: "14px",
+								fontWeight: "500",
+								color: palette.ink,
+								textDecoration: "none",
+								borderBottom: `1px solid ${palette.accent}`,
+							}}
+						>
+							{linkText ?? ""}
+							{" →"}
+						</a>
+					</div>
+				) : null}
+			</td>
+		</tr>
+	);
+}
+
+export type NoteProps = { eyebrowText: string; text: string; accented: boolean; last: boolean };
+
+/** A short note inside a card under a small eyebrow; accented puts the eyebrow in orange. */
+export function Note({ eyebrowText, text, accented, last }: NoteProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<tr>
+			<td
+				style={{
+					padding: `18px 24px ${last ? "20px" : "4px"}`,
+					fontFamily: fonts.sans,
+					fontSize: "14px",
+					lineHeight: "1.55",
+					color: accented ? palette.ink : palette.dim,
+				}}
+			>
+				<span style={{ ...eyebrowStyle(fonts), color: accented ? palette.accent : palette.faint }}>
+					{eyebrowText}
+				</span>
+				<br />
+				{text}
+			</td>
+		</tr>
+	);
+}
+
+export type EmptyRowProps = { text: string };
+
+/** One line of dim text filling a card row: the empty state. */
+export function EmptyRow({ text }: EmptyRowProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<tr>
+			<td
+				style={{
+					padding: "22px 24px",
+					fontFamily: fonts.sans,
+					fontSize: "14px",
+					color: palette.dim,
+				}}
+			>
+				{text}
+			</td>
+		</tr>
+	);
+}
+
+export type StatProps = { n: string | number; caption?: ReactNode };
+
+/** A big number over a small caption; three of these sit in a title card. */
+export function Stat({ n, caption }: StatProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<td style={{ padding: "10px 0", borderTop: `1px solid ${palette.line}` }}>
+			<span
+				style={{
+					fontFamily: fonts.sans,
+					fontSize: "22px",
+					fontWeight: "600",
+					letterSpacing: "-0.02em",
+					color: palette.ink,
+				}}
+			>
+				{String(n)}
+			</span>
+			<br />
+			{caption}
+		</td>
+	);
+}
+
+export type StatsRowProps = { children?: ReactNode };
+
+/** The row of Stat cells inside a title card. */
+export function StatsRow({ children }: StatsRowProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<tr>
+			<td style={{ padding: "20px 26px 24px" }}>
+				<table
+					{...tableReset}
+					width="100%"
+					style={{ fontFamily: fonts.mono, fontSize: "12px", color: palette.faint }}
+				>
+					<tbody>
+						<tr>{children}</tr>
+					</tbody>
+				</table>
+			</td>
+		</tr>
+	);
+}
+
+export type ListProps = { fontSize: string; children?: ReactNode };
+
+/** A hairline list inside a fold: one ListRow per line. */
+export function List({ fontSize, children }: ListProps) {
+	const { palette } = useEmailTheme();
+	return (
+		<table
+			{...tableReset}
+			width="100%"
+			style={{
+				marginTop: "12px",
+				fontSize,
+				lineHeight: "1.5",
+				color: palette.dim,
+			}}
+		>
+			<tbody>{children}</tbody>
+		</table>
+	);
+}
+
+export type ListRowProps = { children?: ReactNode };
+
+export function ListRow({ children }: ListRowProps) {
+	const { palette } = useEmailTheme();
+	return (
+		<tr>
+			<td style={{ padding: "6px 0", borderTop: `1px solid ${palette.hair}` }}>{children}</td>
+		</tr>
+	);
+}
+
+export type LeadRowProps = { lead: string; rest: string };
+
+/** A list row that opens on a bolded lead. */
+export function LeadRow({ lead, rest }: LeadRowProps) {
+	const { palette } = useEmailTheme();
+	return (
+		<ListRow>
+			<b style={{ color: palette.ink, fontWeight: "500" }}>{lead}</b> {rest}
+		</ListRow>
+	);
+}
+
+export type RowProps = { last: boolean; children?: ReactNode };
+
+/** A card row holding any block the pieces above built, with the card's own padding and hairline. */
+export function Row({ last, children }: RowProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<tr>
+			<td
+				style={{
+					padding: `18px 24px ${last ? "22px" : "18px"}`,
+					fontFamily: fonts.sans,
+					...(last ? {} : { borderBottom: `1px solid ${palette.line}` }),
+				}}
+			>
+				{children}
+			</td>
+		</tr>
+	);
+}
+
+export type FoldRowProps = { last: boolean; children?: ReactNode };
+
+/** A card row that holds a card level fold. */
+export function FoldRow({ last, children }: FoldRowProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<tr>
+			<td
+				style={{
+					padding: last ? "18px 24px 20px" : "18px 24px",
+					fontFamily: fonts.sans,
+					...(last ? {} : { borderBottom: `1px solid ${palette.line}` }),
+				}}
+			>
+				{children}
+			</td>
+		</tr>
+	);
+}
+
+export type MonoTableProps = { headers: string[]; rows: string[][] };
+
+/**
+ * A compact monospace table for data the reader copies rather than reads.
+ */
+export function MonoTable({ headers, rows }: MonoTableProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<table
+			{...tableReset}
+			width="100%"
+			style={{
+				marginTop: "12px",
+				fontFamily: fonts.mono,
+				fontSize: "11px",
+				lineHeight: "1.5",
+				color: palette.dim,
+			}}
+		>
+			<tbody>
+				<tr>
+					{headers.map((label, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: a header's position is its identity
+						<td key={i} style={{ padding: "4px 6px", color: palette.faint }}>
+							{label}
+						</td>
+					))}
+				</tr>
+				{rows.map((cells, r) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: a row's position is its identity
+					<tr key={r}>
+						{cells.map((cell, c) => (
+							<td
+								// biome-ignore lint/suspicious/noArrayIndexKey: a cell's position is its identity
+								key={c}
+								style={{
+									padding: "4px 6px",
+									borderTop: `1px solid ${palette.hair}`,
+									verticalAlign: "top",
+								}}
+							>
+								{cell}
+							</td>
+						))}
+					</tr>
+				))}
+			</tbody>
+		</table>
+	);
+}