@atelic-action/ui 0.1.0 → 0.3.0

package/src/email/text.ts

@@ -0,0 +1,116 @@
+/*
+ * The plain text alternative part, ported one to one from the plain text
+ * section of homebase `runners/lib/email.jq`. Every label and number sits in
+ * its own padded column or on its own line; nothing is ever concatenated,
+ * which is what a mail service's own html to text conversion does to a table.
+ *
+ * jq counts a string's length in Unicode codepoints, so every width here does
+ * too. `.length` on a JavaScript string counts UTF-16 units and would pad an
+ * astral character two columns short.
+ */
+
+function codepoints(value: string): number {
+	return [...value].length;
+}
+
+/** jq's ascii_upcase: ASCII letters only, everything else untouched. */
+export function asciiUpcase(value: string): string {
+	return value.replace(/[a-z]/g, (c) => c.toUpperCase());
+}
+
+/** jq's ascii_downcase: ASCII letters only, everything else untouched. */
+export function asciiDowncase(value: string): string {
+	return value.replace(/[A-Z]/g, (c) => c.toLowerCase());
+}
+
+export function spaces(n: number): string {
+	return " ".repeat(Math.max(n, 0));
+}
+
+/** Pads on the right to a column count. */
+export function rpad(value: string, width: number): string {
+	return value + spaces(width - codepoints(value));
+}
+
+/** Pads on the left to a column count. */
+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 {
+	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 lines[lines.length - 1] = `${last} ${word}`;
+	}
+	return lines.map((line) => `  ${line}`).join("\n");
+}
+
+export const textRule = "=".repeat(64);
+
+export function textSection(title: string): string {
+	return `\n\n${textRule}\n${asciiUpcase(title)}\n${textRule}\n\n`;
+}
+
+export function textRead(text: string): string {
+	return `The Read\n${wrap(text)}\n`;
+}
+
+export function textBar(logged: number, target: number | null): string {
+	if (target === null || target === 0) return "";
+	const filled = Math.min(logged, target);
+	return Array.from({ length: target }, (_, i) => (i < filled ? "#" : ".")).join("");
+}
+
+export type TextTarget = {
+	label: string;
+	logged: number;
+	target: number | null;
+	note: string;
+};
+
+/** One scoreboard line. */
+export function textTarget({ label, logged, target, note }: TextTarget): string {
+	const count = `${logged}${target === null ? "" : ` / ${target}`}`;
+	return `  ${rpad(label, 15)}${rpad(count, 8)}${rpad(textBar(logged, target), 7)}${note}`;
+}
+
+/**
+ * A column table. `right` holds the column indexes that align right. `widths`,
+ * when given, fixes every column's width and keeps every column, so sibling
+ * tables line up; null sizes each column to its content and drops any column
+ * every row leaves empty.
+ */
+export function textTableGrid(
+	cols: string[],
+	rows: string[][],
+	right: number[],
+	widths: number[] | null,
+): string {
+	const keep = cols
+		.map((_, i) => i)
+		.filter((i) => widths !== null || rows.some((row) => (row[i] ?? "") !== ""));
+	const widthOf = keep.map((i) =>
+		widths !== null
+			? widths[i]
+			: Math.max(...[cols[i], ...rows.map((row) => row[i] ?? "")].map(codepoints)),
+	);
+	return [cols, ...rows]
+		.map(
+			(row) =>
+				`  ${keep
+					.map((i, k) =>
+						right.includes(i) ? lpad(row[i] ?? "", widthOf[k]) : rpad(row[i] ?? "", widthOf[k]),
+					)
+					.join("  ")
+					.replace(/ +$/, "")}`,
+		)
+		.join("\n");
+}
+
+export function textTable(cols: string[], rows: string[][], right: number[]): string {
+	return textTableGrid(cols, rows, right, null);
+}

package/src/email/theme.tsx

@@ -0,0 +1,77 @@
+import { type CSSProperties, createContext, type ReactNode, useContext } from "react";
+import { atelicFonts, atelicPalette, type Fonts, type Palette } from "../tokens";
+
+export type EmailTheme = {
+	palette: Palette;
+	fonts: Fonts;
+};
+
+const EmailThemeContext = createContext<EmailTheme>({
+	palette: atelicPalette,
+	fonts: atelicFonts,
+});
+
+export type EmailThemeProviderProps = {
+	palette?: Palette;
+	fonts?: Fonts;
+	children?: ReactNode;
+};
+
+/**
+ * Wraps a tree of email rows in a palette and a font pair. A client branded
+ * email passes its own; everything defaults to Atelic.
+ */
+export function EmailThemeProvider({
+	palette = atelicPalette,
+	fonts = atelicFonts,
+	children,
+}: EmailThemeProviderProps) {
+	return (
+		<EmailThemeContext.Provider value={{ palette, fonts }}>{children}</EmailThemeContext.Provider>
+	);
+}
+
+export function useEmailTheme(): EmailTheme {
+	return useContext(EmailThemeContext);
+}
+
+/**
+ * The shared eyebrow: monospace, small, wide, uppercase. The caller adds the
+ * color, because which color an eyebrow wears is what it says.
+ */
+export function eyebrowStyle(fonts: Fonts): CSSProperties {
+	return {
+		fontFamily: fonts.mono,
+		fontSize: "11px",
+		letterSpacing: "0.12em",
+		textTransform: "uppercase",
+	};
+}
+
+/** The props every layout table in an email carries. */
+export const tableReset = {
+	role: "presentation" as const,
+	cellPadding: "0",
+	cellSpacing: "0",
+	border: 0,
+};
+
+/**
+ * `#FC4A1A` to `rgba(252,74,26,0)`, the masthead rule's fade out stop. An accent
+ * that is not a three or six digit hex fades to `transparent` rather than to NaN.
+ */
+export function fadeStop(hex: string): string {
+	if (!/^#?(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(hex)) return "transparent";
+	const digits = hex.replace("#", "");
+	const full =
+		digits.length === 3
+			? digits
+					.split("")
+					.map((c) => c + c)
+					.join("")
+			: digits;
+	const r = Number.parseInt(full.slice(0, 2), 16);
+	const g = Number.parseInt(full.slice(2, 4), 16);
+	const b = Number.parseInt(full.slice(4, 6), 16);
+	return `rgba(${r},${g},${b},0)`;
+}

package/src/routing/index.ts

@@ -0,0 +1,31 @@
+/**
+ * The router options that keep a not found page alive on a statically
+ * prerendered TanStack Start site. Spread them into createRouter:
+ *
+ *   createRouter({ routeTree, ...staticNotFoundRouting(NotFoundPage) })
+ *
+ * The static host serves the /404 prerender for every unknown path, and it
+ * takes a catch all route (src/routes/$.tsx rendering the same page) plus
+ * these two options to survive hydration:
+ *
+ * - The splat gives the client a match below the root. With a dedicated
+ *   /404 route instead, an unknown path matches only the root, hydrate takes
+ *   its SPA branch, throws, and the page goes blank.
+ * - The splat's match id still carries the path, so it differs from the
+ *   dehydrated /404 match and hydrate renders the pending state first.
+ *   Pending as the page itself keeps that first render identical to the
+ *   server HTML; the default null is a hydration mismatch.
+ *
+ * Static sites only. On a live app the pending state is a real loading
+ * moment, and this would flash the not found page through every slow load;
+ * an app sets defaultNotFoundComponent alone.
+ *
+ * Generic over the page so the router checks it against its own component
+ * type; the package stays free of any router import.
+ */
+export function staticNotFoundRouting<Page>(page: Page) {
+	return {
+		defaultNotFoundComponent: page,
+		defaultPendingComponent: page,
+	};
+}

package/src/styles/components.css

@@ -0,0 +1,20 @@
+/* Layout defaults for the components under src/components. A site's own
+   classes (.page-hero, .eyebrow, .lead, .btn) arrive unlayered and win, so
+   these only fill in where a site does not style them. */
+@layer atelic-ui {
+	.mkt .not-found-hero {
+		padding-top: calc(var(--nav-height, 72px) + clamp(40px, 7vw, 86px));
+		padding-bottom: clamp(28px, 5vw, 60px);
+	}
+	.mkt .not-found-hero h1 {
+		margin: 16px 0 0;
+	}
+	.mkt .not-found-hero .lead {
+		margin-top: 22px;
+		max-width: 56ch;
+	}
+	.mkt .not-found-links .cta-row,
+	.mkt .not-found-closing .cta-row {
+		margin-top: 22px;
+	}
+}

package/src/tokens/css.ts

@@ -0,0 +1,27 @@
+import type { Palette } from "./palettes";
+
+/**
+ * Which site token each email palette key answers to, so an email palette can
+ * dress a web page and a page's theme can dress an email. The names are the
+ * ones in a site's `theme.css`; only the keys with a clear counterpart are
+ * mapped, which is why the neutral ramp, the radii, and the shadows are
+ * absent. `--ink` and `--surface-dark` both take the ink, exactly as the site
+ * defines them.
+ */
+export const themeTokenMap: Record<string, keyof Palette> = {
+	"--surface": "ground",
+	"--surface-dark": "ink",
+	"--card": "paper",
+	"--ink": "ink",
+	"--primary": "accent",
+};
+
+/**
+ * The palette as CSS custom property declarations, one per line, ready to drop
+ * inside a selector block.
+ */
+export function toThemeCSS(palette: Palette): string {
+	return Object.entries(themeTokenMap)
+		.map(([token, key]) => `${token}: ${palette[key]};`)
+		.join("\n");
+}

package/src/tokens/index.ts

@@ -0,0 +1,2 @@
+export { themeTokenMap, toThemeCSS } from "./css";
+export { atelicFonts, atelicPalette, type Fonts, type Palette } from "./palettes";

package/src/tokens/palettes.ts

@@ -0,0 +1,54 @@
+/**
+ * The palette the runner emails are painted in, ported one to one from
+ * homebase `runners/lib/email.jq` (the tokens section). Cream ground, paper
+ * cards on a hairline, near black ink, the orange reserved for the one number
+ * that matters on a row.
+ *
+ * A client branded email passes its own Palette to EmailThemeProvider; the
+ * values below are the default.
+ */
+export type Palette = {
+	/** The page behind the cards. */
+	ground: string;
+	/** A card's own fill. */
+	paper: string;
+	/** Headings and anything read closely. */
+	ink: string;
+	/** Secondary prose. */
+	dim: string;
+	/** Eyebrows, captions, and anything deliberately quiet. */
+	faint: string;
+	/** The single accent. */
+	accent: string;
+	/** A card's border and the heavier rule. */
+	line: string;
+	/** The lighter rule inside a card. */
+	hair: string;
+};
+
+export const atelicPalette: Palette = {
+	ground: "#F6F1E7",
+	paper: "#FDFBF6",
+	ink: "#151515",
+	dim: "#55503f",
+	faint: "#8a8272",
+	accent: "#FC4A1A",
+	line: "#E6DFD2",
+	hair: "#F0EAE0",
+};
+
+/**
+ * Font family values, not whole declarations: the components compose them
+ * into a `fontFamily` style property.
+ */
+export type Fonts = {
+	/** Eyebrows, numbers, and anything the reader copies rather than reads. */
+	mono: string;
+	/** Everything read. */
+	sans: string;
+};
+
+export const atelicFonts: Fonts = {
+	mono: "'Courier New',monospace",
+	sans: "'Helvetica Neue',Helvetica,Arial,sans-serif",
+};