@atelic-action/ui 0.4.0 → 0.5.0

package/README.md

@@ -149,18 +149,30 @@ const html = renderEmail({
 
 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).
+`RecordStack` takes `records`, each a `RecordStackItem` (`title`, `url`, `meta`, `note`, `badge`, `callout`), and renders one table row per record: the title on its own line at 15px, bold and wrapping freely, linked when `url` is set; a mono meta line beneath it with the items joined by middle dots (empty items drop); an optional note beneath that; a hairline between records and none after the last. No cell carries a width, so a name of any length wraps at 320 pixels instead of squashing. An optional `badge` (a stage word such as `"Contacted"`) sits on the title line in a small mono uppercase pill on a `line` hairline, in its own right aligned unbroken cell, so the title keeps wrapping beside it and the badge stays on the title's first line. An optional `callout` (`{ eyebrow, text }`) sets a short task under the meta and the note in the accented `Note` idiom: the eyebrow in the accent, the text at 13px, and a 2px accent rule down its left edge. A record with neither renders exactly as it did before. `recordStackText(records)` is its plain text twin: each title on its own line under a two space indent with any badge after it in square brackets (`Blue Heron Plumbing [Contacted]`), the meta and the note wrapped under a four space indent, any callout as its eyebrow in upper case over its text under that same indent, a blank line between records, and no line past `textWidth` (68 columns, indent included).
 
-`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.
+`StatStrip` lays its stats out as inline block cells with an 88 pixel floor inside one centered cell, so six or seven stats flow onto a second row on a phone rather than shrinking. Each stat takes an optional `delta` (`"+3 (12%)"`), set small under its label and colored by its sign: one that opens on `+` wears the palette's `up`, one that opens on `-` its `down`, and anything else stays muted.
+
+`Masthead` takes an optional `meta` (`"Week 39 · 09/21 to 09/27"`) set in the eyebrow style at the right end of the row, so the title card no longer carries the week. It is a right aligned, unbroken block floated after the wordmark and title: on the same line while the row has room, and dropped under the title on its own line, still right aligned, when it does not (checked at 320 pixels). `Eyebrow` takes `strong`, which sets the label at 15px and weight 700 in ink rather than faint, with a slightly tighter tracking, so a section such as `MQL · 15` reads as a heading on a phone.
 
 ```tsx
 const records = [
-	{ title: "Pinewood Cabinetry", url: "https://example.test", meta: ["Lead", "Longmont", "fit 14"], note: "Answered the audit inside a day." },
+	{
+		title: "Pinewood Cabinetry",
+		url: "https://example.test",
+		meta: ["Lead", "Longmont", "fit 14"],
+		note: "Answered the audit inside a day.",
+		badge: "Contacted",
+		callout: { eyebrow: "Next", text: "Walk the Business Profile findings Thursday." },
+	},
 ];
 
+<Masthead title="Pipeline" meta="Week 39 · 09/21 to 09/27" />;
+<Eyebrow text="MQL · 15" strong />;
+
 <Card>
 	<Row last={false}>
-		<StatStrip stats={[{ n: 6, label: "Lead", delta: "+3 · +12%" }, { n: 2, label: "MQL" }]} />
+		<StatStrip stats={[{ n: 6, label: "Lead", delta: "+3 (12%)" }, { n: 2, label: "MQL", delta: "-1 (4%)" }]} />
 	</Row>
 	<Row last>
 		<RecordStack records={records} />
@@ -178,7 +190,7 @@ Where the jq takes a pre rendered html string (`$rows`, `$body_html`, `$cells_ht
 
 | jq Function | Component | Props |
 |---|---|---|
-| `eyebrow` | `Eyebrow` | `text` |
+| `eyebrow` | `Eyebrow` | `text`, `strong` (added 0.5.0, no jq counterpart) |
 | `card` | `Card` | `children` |
 | `fold` | `Fold` | `summary`, `children` |
 | `big_fold` | `BigFold` | `summary`, `count` (a `ReactNode`, absent for the jq's `""`), `children` |
@@ -203,10 +215,10 @@ 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`, 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) |
+| `stat_strip` | `StatStrip` | `stats`, each with an optional `delta` colored by its sign (the component wraps where the jq does not) |
+| none | `RecordStack` | `records`, each with an optional `badge` and `callout` (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`) |
+| `masthead` | `Masthead` | `title`, `wordmark` (defaults to `atelic`), `meta` (added 0.5.0, no jq counterpart) |
 | `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` |
@@ -220,6 +232,8 @@ The plain text alternative part ports as plain functions with no React anywhere
 
 `@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.
 
+The palette carries two 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. Both 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. Neither maps to a site token.
+
 ## 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.4.0",
+	"version": "0.5.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/atoms.tsx

@@ -10,16 +10,27 @@ import { eyebrowStyle, tableReset, useEmailTheme } from "./theme";
  * is a plain string and React does the escaping.
  */
 
-export type EyebrowProps = { text: string };
+export type EyebrowProps = {
+	text: string;
+	/** Reads as a heading on a phone: larger, bold, in ink rather than faint. */
+	strong?: boolean;
+};
 
 /** A section label between cards. */
-export function Eyebrow({ text }: EyebrowProps) {
+export function Eyebrow({ text, strong = false }: EyebrowProps) {
 	const { palette, fonts } = useEmailTheme();
+	const look = strong
+		? {
+				...eyebrowStyle(fonts),
+				fontSize: "15px",
+				fontWeight: "700",
+				letterSpacing: "0.06em",
+				color: palette.ink,
+			}
+		: { ...eyebrowStyle(fonts), color: palette.faint };
 	return (
 		<tr>
-			<td style={{ padding: "36px 8px 12px", ...eyebrowStyle(fonts), color: palette.faint }}>
-				{text}
-			</td>
+			<td style={{ padding: "36px 8px 12px", ...look }}>{text}</td>
 		</tr>
 	);
 }

package/src/email/frame.tsx

@@ -14,62 +14,88 @@ export type MastheadProps = {
 	title: string;
 	/** The wordmark at the top left. */
 	wordmark?: string;
+	/**
+	 * A quiet fact at the right end of the row, such as the week. It sits on
+	 * the title's line while it fits and drops under it, still right aligned,
+	 * when the row runs out of room.
+	 */
+	meta?: string;
 };
 
 /**
  * The wordmark and one orange rule at the top left, the email's title beside
- * them: the runner's name, not the week.
+ * them: the runner's name, not the week. A `meta` rides at the right end of
+ * the row in its own right aligned, unbroken block, floated after the brand so
+ * that on a narrow screen it drops under the title instead of squashing it.
  */
-export function Masthead({ title, wordmark = "atelic" }: MastheadProps) {
+export function Masthead({ title, wordmark = "atelic", meta }: MastheadProps) {
 	const { palette, fonts } = useEmailTheme();
+	const brand = (
+		<table {...tableReset}>
+			<tbody>
+				<tr>
+					<td
+						style={{
+							fontSize: "20px",
+							fontWeight: "600",
+							letterSpacing: "-0.045em",
+							color: palette.ink,
+							paddingRight: "8px",
+							lineHeight: "1",
+						}}
+					>
+						{wordmark}
+					</td>
+					<td width="34" style={{ width: "34px", verticalAlign: "middle", paddingRight: "12px" }}>
+						<div
+							style={{
+								width: "34px",
+								height: "2px",
+								fontSize: "0",
+								lineHeight: "0",
+								backgroundColor: palette.accent,
+								background: `linear-gradient(90deg,${palette.accent},${fadeStop(palette.accent)})`,
+							}}
+						>
+							{"\u00a0"}
+						</div>
+					</td>
+					<td
+						style={{
+							...eyebrowStyle(fonts),
+							color: palette.faint,
+							verticalAlign: "middle",
+							lineHeight: "1",
+						}}
+					>
+						{title}
+					</td>
+				</tr>
+			</tbody>
+		</table>
+	);
 	return (
 		<tr>
 			<td style={{ padding: "8px 8px 22px", fontFamily: fonts.sans }}>
-				<table {...tableReset}>
-					<tbody>
-						<tr>
-							<td
-								style={{
-									fontSize: "20px",
-									fontWeight: "600",
-									letterSpacing: "-0.045em",
-									color: palette.ink,
-									paddingRight: "8px",
-									lineHeight: "1",
-								}}
-							>
-								{wordmark}
-							</td>
-							<td
-								width="34"
-								style={{ width: "34px", verticalAlign: "middle", paddingRight: "12px" }}
-							>
-								<div
-									style={{
-										width: "34px",
-										height: "2px",
-										fontSize: "0",
-										lineHeight: "0",
-										backgroundColor: palette.accent,
-										background: `linear-gradient(90deg,${palette.accent},${fadeStop(palette.accent)})`,
-									}}
-								>
-									{"\u00a0"}
-								</div>
-							</td>
-							<td
-								style={{
-									...eyebrowStyle(fonts),
-									color: palette.faint,
-									verticalAlign: "middle",
-									lineHeight: "1",
-								}}
-							>
-								{title}
-							</td>
-						</tr>
-					</tbody>
-				</table>
+				{meta ? (
+					<>
+						<div style={{ display: "inline-block", verticalAlign: "middle" }}>{brand}</div>
+						<div
+							style={{
+								float: "right",
+								textAlign: "right",
+								whiteSpace: "nowrap",
+								...eyebrowStyle(fonts),
+								lineHeight: "20px",
+								color: palette.faint,
+							}}
+						>
+							{meta}
+						</div>
+					</>
+				) : (
+					brand
+				)}
 			</td>
 		</tr>
 	);

package/src/email/scoreboard.tsx

@@ -1,4 +1,5 @@
-import { Fragment, type ReactNode } from "react";
+import { type CSSProperties, Fragment, type ReactNode } from "react";
+import { atelicPalette, type Palette } from "../tokens";
 import type { RecordStackItem } from "./text";
 import { eyebrowStyle, tableReset, useEmailTheme } from "./theme";
 
@@ -327,9 +328,22 @@ export function DayStrip({ days, last }: DayStripProps) {
 export type StatStripEntry = {
 	n: string | number;
 	label: string;
-	/** A change beside the number, small and muted under the label: "+3 · +12%". */
+	/**
+	 * A change beside the number, small under the label: "+3 (12%)". One that
+	 * opens on "+" wears the palette's `up`, one that opens on "-" its `down`,
+	 * anything else stays muted.
+	 */
 	delta?: string;
 };
+
+/** The color a delta wears, read off its sign. */
+export function deltaColor(delta: string, palette: Palette): string {
+	if (delta.startsWith("+")) return palette.up ?? atelicPalette.up ?? palette.faint;
+	if (delta.startsWith("-") || delta.startsWith("\u2212")) {
+		return palette.down ?? atelicPalette.down ?? palette.faint;
+	}
+	return palette.faint;
+}
 export type StatStripProps = { stats: StatStripEntry[] };
 
 /**
@@ -377,7 +391,11 @@ export function StatStrip({ stats }: StatStripProps) {
 									<>
 										<br />
 										<span
-											style={{ fontFamily: fonts.mono, fontSize: "11px", color: palette.faint }}
+											style={{
+												fontFamily: fonts.mono,
+												fontSize: "11px",
+												color: deltaColor(entry.delta, palette),
+											}}
 										>
 											{entry.delta}
 										</span>
@@ -392,6 +410,35 @@ export function StatStrip({ stats }: StatStripProps) {
 	);
 }
 
+type RecordBadgeProps = { text: string };
+
+/**
+ * A word in a small mono pill on a hairline, the Badge idiom sized for a stage
+ * such as "Contacted". Only RecordStack wears it.
+ */
+function RecordBadge({ text }: RecordBadgeProps) {
+	const { palette, fonts } = useEmailTheme();
+	return (
+		<span
+			style={{
+				display: "inline-block",
+				fontFamily: fonts.mono,
+				fontSize: "10px",
+				lineHeight: "14px",
+				letterSpacing: "0.08em",
+				textTransform: "uppercase",
+				padding: "0 6px",
+				border: `1px solid ${palette.line}`,
+				borderRadius: "3px",
+				color: palette.dim,
+				whiteSpace: "nowrap",
+			}}
+		>
+			{text}
+		</span>
+	);
+}
+
 export type { RecordStackItem };
 export type RecordStackProps = { records: RecordStackItem[] };
 
@@ -403,12 +450,33 @@ export type RecordStackProps = { records: RecordStackItem[] };
  */
 export function RecordStack({ records }: RecordStackProps) {
 	const { palette, fonts } = useEmailTheme();
+	const titleStyle: CSSProperties = {
+		fontSize: "15px",
+		fontWeight: "600",
+		lineHeight: "1.35",
+		color: palette.ink,
+		wordBreak: "break-word",
+	};
 	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 !== "");
+					const title = record.url ? (
+						<a
+							href={record.url}
+							style={{
+								color: palette.ink,
+								textDecoration: "none",
+								borderBottom: `1px solid ${palette.accent}`,
+							}}
+						>
+							{record.title}
+						</a>
+					) : (
+						record.title
+					);
 					return (
 						// biome-ignore lint/suspicious/noArrayIndexKey: a record's position is its identity
 						<tr key={i}>
@@ -419,30 +487,29 @@ export function RecordStack({ records }: RecordStackProps) {
 									...(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>
+								{record.badge ? (
+									<table {...tableReset} width="100%">
+										<tbody>
+											<tr>
+												<td style={{ ...titleStyle, verticalAlign: "top" }}>{title}</td>
+												<td
+													align="right"
+													style={{
+														textAlign: "right",
+														whiteSpace: "nowrap",
+														verticalAlign: "top",
+														paddingLeft: "12px",
+														paddingTop: "2px",
+													}}
+												>
+													<RecordBadge text={record.badge} />
+												</td>
+											</tr>
+										</tbody>
+									</table>
+								) : (
+									<div style={titleStyle}>{title}</div>
+								)}
 								{meta.length > 0 ? (
 									<div
 										style={{
@@ -468,6 +535,25 @@ export function RecordStack({ records }: RecordStackProps) {
 										{record.note}
 									</div>
 								) : null}
+								{record.callout ? (
+									<div
+										style={{
+											marginTop: "10px",
+											paddingLeft: "10px",
+											borderLeft: `2px solid ${palette.accent}`,
+											fontFamily: fonts.sans,
+											fontSize: "13px",
+											lineHeight: "1.5",
+											color: palette.ink,
+										}}
+									>
+										<span style={{ ...eyebrowStyle(fonts), color: palette.accent }}>
+											{record.callout.eyebrow}
+										</span>
+										<br />
+										{record.callout.text}
+									</div>
+								) : null}
 							</td>
 						</tr>
 					);

package/src/email/text.ts

@@ -135,21 +135,32 @@ export type RecordStackItem = {
 	/** Facts joined by a middle dot on the line under the title; empty items drop. */
 	meta: string[];
 	note?: string;
+	/** A stage word on the title line, right aligned in a pill; "[Contacted]" in the text twin. */
+	badge?: string;
+	/** A short task under the record, an orange eyebrow over a line of text. */
+	callout?: { eyebrow: string; text: 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`.
+ * two space indent with any badge after it in square brackets, the meta joined
+ * by middle dots and the note beneath it, both wrapped under a four space
+ * indent, then any callout as its eyebrow in upper case over its text under
+ * the same 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 title = record.badge ? `${record.title} [${record.badge}]` : record.title;
+			const lines = [wrapIndented(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));
+			if (record.callout) {
+				lines.push(wrapIndented(asciiUpcase(record.callout.eyebrow), 4));
+				lines.push(wrapIndented(record.callout.text, 4));
+			}
 			return lines.join("\n");
 		})
 		.join("\n\n");

package/src/tokens/palettes.ts

@@ -24,6 +24,14 @@ export type Palette = {
 	line: string;
 	/** The lighter rule inside a card. */
 	hair: string;
+	/**
+	 * A change for the better, such as a positive delta under a stat. Optional
+	 * so a palette written before 0.5.0 still compiles; a palette without it
+	 * borrows the Atelic value.
+	 */
+	up?: string;
+	/** A change for the worse, the negative delta's color. Optional the same way. */
+	down?: string;
 };
 
 export const atelicPalette: Palette = {
@@ -35,6 +43,8 @@ export const atelicPalette: Palette = {
 	accent: "#FC4A1A",
 	line: "#E6DFD2",
 	hair: "#F0EAE0",
+	up: "#2F7A4B",
+	down: "#B23A2E",
 };
 
 /**