@atelic-action/ui 0.14.0 → 0.15.0

package/src/artifact/ErrorFallback.tsx

@@ -0,0 +1,70 @@
+/// <reference types="vite/client" />
+
+interface ErrorFallbackProps {
+	error: unknown;
+	resetError: () => void;
+}
+
+/**
+ * Fallback UI displayed when the error boundary catches a render error.
+ * Deliberately dependency-free (inline styles, no component library) so it
+ * renders even when the styling pipeline is part of what broke.
+ */
+export function ErrorFallback({ error, resetError }: ErrorFallbackProps) {
+	const errorMessage = error instanceof Error ? error.message : "Unknown error";
+
+	return (
+		<div
+			style={{
+				minHeight: "100vh",
+				display: "flex",
+				alignItems: "center",
+				justifyContent: "center",
+				padding: 24,
+				fontFamily: "system-ui, sans-serif",
+				textAlign: "center",
+			}}
+		>
+			<div style={{ maxWidth: 420 }}>
+				<h1 style={{ fontSize: 24, fontWeight: 600, margin: 0 }}>Something went wrong</h1>
+				<p style={{ marginTop: 8, fontSize: 14, color: "#666" }}>
+					An unexpected error occurred. Please try again.
+				</p>
+				{import.meta.env.DEV && (
+					<pre
+						style={{
+							marginTop: 16,
+							maxHeight: 160,
+							overflow: "auto",
+							borderRadius: 8,
+							background: "#f4f4f4",
+							padding: 12,
+							textAlign: "left",
+							fontSize: 12,
+							color: "#666",
+						}}
+					>
+						{errorMessage}
+					</pre>
+				)}
+				<button
+					type="button"
+					onClick={resetError}
+					style={{
+						marginTop: 24,
+						padding: "10px 22px",
+						borderRadius: 999,
+						border: "none",
+						background: "#222",
+						color: "#fff",
+						fontSize: 14,
+						fontWeight: 600,
+						cursor: "pointer",
+					}}
+				>
+					Try Again
+				</button>
+			</div>
+		</div>
+	);
+}

package/src/artifact/Gate.tsx

@@ -0,0 +1,328 @@
+import { type FormEvent, useEffect, useRef, useState } from "react";
+import { Button } from "../primitives/Button";
+
+/**
+ * PBKDF2 work factor and hash. Mirrored by scripts/build-gate-payload.mjs;
+ * the two must agree exactly or every sealed payload stops opening.
+ */
+const PBKDF2_ITERATIONS = 200000;
+const PBKDF2_HASH = "SHA-256";
+
+declare global {
+	interface Window {
+		/** HubSpot tracking queue; the loader drains anything pushed before it loads. */
+		_hsq?: unknown[];
+	}
+}
+
+export interface GatePerson {
+	/** Stable handle for the reader, used in the payload and in `onUnlock`. */
+	id: string;
+	/**
+	 * The reader's email address: the secret their key derives from, and,
+	 * when it matches `identifyDomain`, the identity pushed to HubSpot.
+	 */
+	email: string;
+	/** Base64: this reader's PBKDF2 salt, GCM nonce, and wrapped content key. */
+	salt: string;
+	iv: string;
+	wrapped: string;
+}
+
+export interface GatePayload {
+	/** Base64: the document's GCM nonce and ciphertext. */
+	civ: string;
+	ct: string;
+	people: GatePerson[];
+}
+
+export interface GateProps {
+	/** Built by scripts/build-gate-payload.mjs. Carries no plaintext. */
+	payload: GatePayload;
+	/** localStorage key holding the reader's email, so a return visit walks straight in. */
+	storageKey?: string;
+	/**
+	 * Query parameter a sent link may carry the reader's email in, so the
+	 * link opens the document in one click. Checked once on mount and
+	 * stripped from the address bar either way.
+	 */
+	queryParam?: string;
+	/**
+	 * When set, a reader whose email ends with this domain is pushed to
+	 * HubSpot on unlock, so the open lands on their contact timeline.
+	 * Readers on another domain identify nobody. Leave it unset and the
+	 * gate tracks no one.
+	 */
+	identifyDomain?: string;
+	/** Gate copy. Defaults are neutral; a client document overrides what it needs. */
+	kicker?: string;
+	heading?: string;
+	sub?: string;
+	placeholder?: string;
+	inputLabel?: string;
+	errorText?: string;
+	/** Fired once, after a successful unlock. */
+	onUnlock?: (person: GatePerson) => void;
+}
+
+/**
+ * An email is its letters and digits, uppercased, so "Dana@Example.com",
+ * "dana@example.com" and even a stray space all open the same document.
+ * Mirrored in the build script.
+ */
+export function normalizeEmail(email: string): string {
+	return email.toUpperCase().replace(/[^A-Z0-9]/g, "");
+}
+
+function fromBase64(value: string): Uint8Array {
+	const binary = atob(value);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+
+interface Opened {
+	person: GatePerson;
+	html: string;
+}
+
+/**
+ * Try the entered email against every reader in the payload. An email that
+ * matches nobody fails the GCM tag check on each attempt and returns null,
+ * which is the only signal the gate ever gives: it never reveals who is on
+ * the list or how close a guess came.
+ */
+async function openDocument(payload: GatePayload, rawEmail: string): Promise<Opened | null> {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) return null;
+	const normalized = normalizeEmail(rawEmail);
+	if (!normalized) return null;
+
+	const material = await subtle.importKey(
+		"raw",
+		new TextEncoder().encode(normalized),
+		"PBKDF2",
+		false,
+		["deriveKey"],
+	);
+
+	for (const person of payload.people) {
+		try {
+			const wrapper = await subtle.deriveKey(
+				{
+					name: "PBKDF2",
+					salt: fromBase64(person.salt) as BufferSource,
+					iterations: PBKDF2_ITERATIONS,
+					hash: PBKDF2_HASH,
+				},
+				material,
+				{ name: "AES-GCM", length: 256 },
+				false,
+				["decrypt"],
+			);
+			const contentKeyBytes = await subtle.decrypt(
+				{ name: "AES-GCM", iv: fromBase64(person.iv) as BufferSource },
+				wrapper,
+				fromBase64(person.wrapped) as BufferSource,
+			);
+			const contentKey = await subtle.importKey(
+				"raw",
+				contentKeyBytes,
+				{ name: "AES-GCM" },
+				false,
+				["decrypt"],
+			);
+			const plain = await subtle.decrypt(
+				{ name: "AES-GCM", iv: fromBase64(payload.civ) as BufferSource },
+				contentKey,
+				fromBase64(payload.ct) as BufferSource,
+			);
+			return { person, html: new TextDecoder().decode(plain) };
+		} catch {
+			// Wrong email for this reader. Try the next one; say nothing.
+		}
+	}
+	return null;
+}
+
+function identifyReader(person: GatePerson, domain: string | undefined) {
+	if (!domain || !person.email) return;
+	if (!person.email.toLowerCase().endsWith(`@${domain.toLowerCase()}`)) return;
+	window._hsq = window._hsq || [];
+	window._hsq.push(["identify", { email: person.email }]);
+	window._hsq.push(["setPath", window.location.pathname]);
+	window._hsq.push(["trackPageView"]);
+}
+
+function readStored(key: string): string {
+	try {
+		return globalThis.localStorage?.getItem(key) ?? "";
+	} catch {
+		return ""; // Storage blocked (private mode); the reader just retypes their email.
+	}
+}
+
+function writeStored(key: string, value: string) {
+	try {
+		globalThis.localStorage?.setItem(key, value);
+	} catch {
+		// Same: persistence is a courtesy, never a requirement.
+	}
+}
+
+/** Read and strip the gate's query parameter in one motion. */
+function takeQueryParam(name: string): string {
+	try {
+		const url = new URL(window.location.href);
+		const value = url.searchParams.get(name) ?? "";
+		if (value) {
+			url.searchParams.delete(name);
+			window.history.replaceState(window.history.state, "", url.toString());
+		}
+		return value;
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * The gate: an email field standing in front of a sealed document.
+ *
+ * The document ships as ciphertext inside the page, so there is no server to
+ * ask and nothing to gate at the edge. The reader's own email address derives
+ * the key that unwraps the content key, the document decrypts in the browser,
+ * and the gate replaces itself with it. Wrong emails get one line of copy and
+ * no hint. A sent link can carry the email in a query parameter (`?email=`)
+ * to open the document in one click.
+ *
+ * Sized for a document sent to named people: the reader types the one thing
+ * they always know, no sign in, no inbox round trip. The access gate
+ * (ACCESS-GATE.md, GateLogin in this folder) is the other shape, for a whole
+ * site preview behind an email tied session with inbox verified identity.
+ */
+export function Gate({
+	payload,
+	storageKey = "gate-email",
+	queryParam = "email",
+	identifyDomain,
+	kicker = "Private Document",
+	heading = "Enter Your Email",
+	sub = "This document opens with the email address it was sent to.",
+	placeholder = "you@company.com",
+	inputLabel = "Your email",
+	errorText = "That email does not open this document. Use the address it was sent to.",
+	onUnlock,
+}: GateProps) {
+	const [html, setHtml] = useState<string | null>(null);
+	const [failed, setFailed] = useState(false);
+	const [busy, setBusy] = useState(false);
+	const [value, setValue] = useState("");
+
+	// Held in a ref so a caller passing an inline function cannot re-run the
+	// auto unlock effect on every render.
+	const onUnlockRef = useRef(onUnlock);
+	onUnlockRef.current = onUnlock;
+
+	// Silent auto unlock, in order: a sent link's query parameter first, then
+	// the stored email of a reader who has been here before. A value that no
+	// longer opens anything (the payload was rebuilt) fails quietly; a failed
+	// query value pre fills the field and surfaces the error, since the
+	// reader arrived expecting the door to open.
+	useEffect(() => {
+		let cancelled = false;
+
+		async function attempt() {
+			const fromQuery = takeQueryParam(queryParam);
+			if (fromQuery) {
+				const opened = await openDocument(payload, fromQuery);
+				if (cancelled) return;
+				if (opened) {
+					writeStored(storageKey, fromQuery);
+					identifyReader(opened.person, identifyDomain);
+					setHtml(opened.html);
+					onUnlockRef.current?.(opened.person);
+					return;
+				}
+				setValue(fromQuery);
+				setFailed(true);
+				return;
+			}
+
+			const stored = readStored(storageKey);
+			if (!stored) return;
+			const opened = await openDocument(payload, stored);
+			if (cancelled || !opened) return;
+			identifyReader(opened.person, identifyDomain);
+			setHtml(opened.html);
+			onUnlockRef.current?.(opened.person);
+		}
+
+		attempt();
+		return () => {
+			cancelled = true;
+		};
+	}, [payload, storageKey, identifyDomain, queryParam]);
+
+	async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+		event.preventDefault();
+		if (busy) return;
+		setBusy(true);
+		setFailed(false);
+		const opened = await openDocument(payload, value);
+		setBusy(false);
+		if (!opened) {
+			setFailed(true);
+			return;
+		}
+		writeStored(storageKey, value);
+		identifyReader(opened.person, identifyDomain);
+		setHtml(opened.html);
+		onUnlockRef.current?.(opened.person);
+	}
+
+	if (html !== null) {
+		return (
+			<div className="gate-doc">
+				<div className="wrap">
+					{/* biome-ignore lint/security/noDangerouslySetInnerHtml: the document is the practice's own HTML, sealed at build time and decrypted here. Injecting it is the whole point of the component. */}
+					<div className="gate-content" dangerouslySetInnerHTML={{ __html: html }} />
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="gate-hall">
+			<div className="wrap">
+				<div className="gate-card">
+					{kicker && <p className="gate-eyebrow">{kicker}</p>}
+					<h1 className="gate-headline">{heading}</h1>
+					{sub && <p className="gate-lead">{sub}</p>}
+					<form className="gate-form" onSubmit={handleSubmit} noValidate>
+						<input
+							className="gate-input"
+							type="email"
+							inputMode="email"
+							name="email"
+							value={value}
+							onChange={(event) => setValue(event.target.value)}
+							placeholder={placeholder}
+							aria-label={inputLabel}
+							autoComplete="email"
+							autoCapitalize="none"
+							spellCheck={false}
+						/>
+						<Button type="submit" size="lg">
+							{busy ? "Opening…" : "Open Document"}
+						</Button>
+					</form>
+					{failed && (
+						<p className="gate-error" role="alert">
+							{errorText}
+						</p>
+					)}
+				</div>
+			</div>
+		</div>
+	);
+}

package/src/artifact/GradeChip.tsx

@@ -0,0 +1,29 @@
+/**
+ * The grade a section carries: A, B, C, or D, green, yellow, orange, red, so
+ * an owner reads it at a glance. The scale and the rule behind every letter
+ * are the practice's FOOTPRINT.md, never restated here; D is for something
+ * truly broken, and only where a section's rule names it. The monthly page
+ * wears the same letters, so a later writeup and every month after read
+ * against the first.
+ */
+export type WriteupGrade = "a" | "b" | "c" | "d";
+
+export const gradeLabel: Record<WriteupGrade, string> = {
+	a: "A",
+	b: "B",
+	c: "C",
+	d: "D",
+};
+
+/**
+ * The letter as a chip in its grade's color. The writeup and the monthly page
+ * both wear it, so its styles live in the base sheet chain
+ * (styles/artifact.css), never in either component's stylesheet.
+ */
+export function GradeChip({ grade }: { grade: WriteupGrade }) {
+	return (
+		<span className="op-grade" data-grade={grade}>
+			{gradeLabel[grade]}
+		</span>
+	);
+}

package/src/artifact/Report.tsx

@@ -0,0 +1,131 @@
+import type { ReactNode } from "react";
+import { GradeChip, type WriteupGrade } from "./GradeChip";
+import { SignOff, type WriteupPerson } from "./SignOff";
+
+/**
+ * The monthly page: what an Operate client gets each month, as one printed
+ * letter sheet and its hosted twin. Its shape is the practice's
+ * FOOTPRINT.md, under What the Owner Gets: the title and the period, then
+ * the leads block answering the four questions the Statement of Work
+ * promises, in that order, each a figure and one plain sentence; then the
+ * seven grades with what moved since last month and since the baseline; then
+ * the sign off. It wears the writeup's grade chip and sign off, and the
+ * artifact shell's header on screen; print drops the header and the credit
+ * band, so the sheet is the document alone.
+ */
+
+export interface ReportLead {
+	/** The figure, e.g. "31 leads" or "$1,240". */
+	figure: ReactNode;
+	/** One plain sentence on what the figure means to the owner. */
+	sentence: ReactNode;
+}
+
+/** The four questions, answered in this order on every monthly page. */
+export interface ReportLeads {
+	cameIn: ReportLead;
+	fromWhere: ReportLead;
+	cost: ReportLead;
+	closed: ReportLead;
+}
+
+export interface ReportGradeRow {
+	/** The tier, e.g. "Health". */
+	tier: string;
+	/** The section's trade name, e.g. "Local SEO". */
+	section: string;
+	/** The grade this month: the one judgement, in full color. */
+	now: WriteupGrade;
+	/** The grade last month; omit on the first month. */
+	lastMonth?: WriteupGrade;
+	/** The grade in the baseline snapshot, the first taken on private sources. */
+	baseline?: WriteupGrade;
+	/** One line on what moved, in the owner's words. */
+	moved: string;
+}
+
+export interface ReportProps {
+	title: string;
+	/** The period as printed, e.g. "September 2026". */
+	period: string;
+	leads: ReportLeads;
+	/** The seven sections, in the footprint's order. */
+	grades: ReportGradeRow[];
+	/** The sign off, the same lockup the writeup closes on. */
+	close: { signOff: string; person: WriteupPerson };
+}
+
+/**
+ * The questions are the monthly page's contract with the Statement of Work,
+ * the same on every client's page, so they live here rather than in content.
+ */
+const QUESTIONS: { key: keyof ReportLeads; label: string }[] = [
+	{ key: "cameIn", label: "What Came In" },
+	{ key: "fromWhere", label: "From Where" },
+	{ key: "cost", label: "What It Cost" },
+	{ key: "closed", label: "What It Closed" },
+];
+
+function Earlier({ grade, label }: { grade?: WriteupGrade; label: string }) {
+	return (
+		<td className="rp-earlier" data-label={label}>
+			{grade && <GradeChip grade={grade} />}
+		</td>
+	);
+}
+
+export function Report({ title, period, leads, grades, close }: ReportProps) {
+	let lastTier = "";
+	return (
+		<div className="rp">
+			<article className="rp-sheet">
+				<header className="rp-head">
+					<div className="rp-period">{period}</div>
+					<h1>{title}</h1>
+				</header>
+				<div className="rp-leads">
+					{QUESTIONS.map(({ key, label }) => (
+						<section className="rp-lead" key={key}>
+							<h2 className="rp-q">{label}</h2>
+							<div className="rp-figure">{leads[key].figure}</div>
+							<p>{leads[key].sentence}</p>
+						</section>
+					))}
+				</div>
+				<table className="rp-grades">
+					<thead>
+						<tr>
+							<th scope="col">Tier</th>
+							<th scope="col">Section</th>
+							<th scope="col">Now</th>
+							<th scope="col">Last Month</th>
+							<th scope="col">Baseline</th>
+							<th scope="col">What Moved</th>
+						</tr>
+					</thead>
+					<tbody>
+						{grades.map((row) => {
+							const tier = row.tier === lastTier ? "" : row.tier;
+							lastTier = row.tier;
+							return (
+								<tr key={row.section} className={tier ? "is-tier-start" : undefined}>
+									<td className="rp-tier">{tier}</td>
+									<td className="rp-section">{row.section}</td>
+									<td className="rp-now" data-label="Now">
+										<GradeChip grade={row.now} />
+									</td>
+									<Earlier grade={row.lastMonth} label="Last Month" />
+									<Earlier grade={row.baseline} label="Baseline" />
+									<td className="rp-moved">{row.moved}</td>
+								</tr>
+							);
+						})}
+					</tbody>
+				</table>
+				<footer className="rp-close">
+					<SignOff signOff={close.signOff} person={close.person} />
+				</footer>
+			</article>
+		</div>
+	);
+}

package/src/artifact/SignOff.tsx

@@ -0,0 +1,37 @@
+import { Mail } from "lucide-react";
+import type { ReactNode } from "react";
+
+export interface WriteupPerson {
+	photoSrc: string;
+	photoAlt: string;
+	name: string;
+	/** The line under the name, e.g. <>Founder, <a href="https://atelic.me">Atelic</a></>. */
+	role: ReactNode;
+	mailHref: string;
+	/** The address as printed, e.g. "matt@atelic.me". */
+	mailLabel: string;
+}
+
+/**
+ * The sign off a printed artifact closes on: the script line, then the person
+ * lockup, the photo beside the name, the role, and the address
+ * (Brand/voice.md, Pitch Surfaces 9). The writeup and the monthly page both
+ * wear it, so its styles live in the base sheet chain
+ * (styles/artifact.css); its container sets the type size and the color.
+ */
+export function SignOff({ signOff, person }: { signOff: string; person: WriteupPerson }) {
+	return (
+		<div className="op-who">
+			<img src={person.photoSrc} alt={person.photoAlt} />
+			<div>
+				<div className="op-sign">{signOff}</div>
+				<b>{person.name}</b>
+				<br />
+				{person.role} ·{" "}
+				<a href={person.mailHref}>
+					<Mail size={11} aria-hidden="true" /> {person.mailLabel}
+				</a>
+			</div>
+		</div>
+	);
+}