@atelic-action/ui 0.12.1 → 0.13.0

package/README.md

@@ -41,11 +41,12 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | Import | Exports |
 |---|---|
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
-| `@atelic-action/ui/components` | `NotFound` and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`, `StarRating`, `Disclosure`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
+| `@atelic-action/ui/components` | `NotFound`, the access gate's `GateLogin` and `Watermark` (with `readCookie`), and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`, `StarRating`, `Disclosure`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
 | `@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/gate.css` | Styles for `GateLogin` and `Watermark` |
 | `@atelic-action/ui/gate` | `signToken`, `verifyToken`, `safeNext`, `needsSession`, and the token types |
 | `@atelic-action/ui/gate/request-link` | `POST`, the handler that emails a sign in link, and `createRequestLink` |
 | `@atelic-action/ui/gate/verify` | `GET`, the handler that turns a link into a session |
@@ -173,6 +174,30 @@ What it does not do, by having no store: a link can be used more than once until
 
 This is the one corner of the package that ships compiled. Vercel runs a function's and a middleware's package imports as shipped and compiles nothing inside `node_modules`, so `bun run build` emits `src/gate/` to `dist/gate/`, and `prepack` runs it before every publish.
 
+### The Screen and the Watermark
+
+The two pieces a reader sees are ordinary components, in `@atelic-action/ui/components`, styled by `@atelic-action/ui/styles/gate.css` (import it after `components.css`):
+
+```tsx
+// src/routes/login.tsx: the screen alone inside the site's scope, no header
+<div className="mkt">
+	<GateLogin
+		brandName={site.recipient.name}
+		eyebrow={site.gate?.eyebrow}
+		headline={site.gate?.headline}
+		lead={site.gate?.lead}
+		builtBy={site.sender.name}
+		contactEmail={site.sender.email}
+	/>
+</div>;
+
+// the site's shell, once, inside its `.mkt` wrapper, so every page behind
+// the gate wears it (the styles are scoped there, like every sheet's)
+<Watermark />;
+```
+
+`GateLogin` posts to `/api/auth/request-link`; a site served under a base path passes its own `endpoint`. Its button wears the site's `.btn` classes, as the chrome's do. `Watermark` reads the `gate_email` cookie and draws nothing without one. `readCookie`, exported beside them, is the reader `Watermark` uses and a site's own code can: empty during prerender, for a missing cookie, and for one that will not decode. `GateLogin` says so when an address is not an email, holds a second submit while the first is in flight, and announces each outcome to a screen reader.
+
 ## 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.

package/dist/gate/wall.d.ts

@@ -11,7 +11,8 @@
  * the favicon in its head, and the brand marks the header draws, which every
  * prerendered page preloads because the router's pending page carries the
  * header (each site's e2e/wall.spec.ts fails when the login page asks for
- * anything else); plus the two sign in functions under /api/auth/, the login page itself,
+ * anything else); plus everything under /api/auth/, where the two sign in functions
+ * live and a host adds nothing private, the login page itself,
  * robots.txt, and the uptime monitor's health.json. /assets/doc/ is the one
  * part of /assets/ held back: the build writes every chunk carrying a
  * private content module there (the private chunks build plugin), so a document's

package/dist/gate/wall.js

@@ -11,7 +11,8 @@
  * the favicon in its head, and the brand marks the header draws, which every
  * prerendered page preloads because the router's pending page carries the
  * header (each site's e2e/wall.spec.ts fails when the login page asks for
- * anything else); plus the two sign in functions under /api/auth/, the login page itself,
+ * anything else); plus everything under /api/auth/, where the two sign in functions
+ * live and a host adds nothing private, the login page itself,
  * robots.txt, and the uptime monitor's health.json. /assets/doc/ is the one
  * part of /assets/ held back: the build writes every chunk carrying a
  * private content module there (the private chunks build plugin), so a document's

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.12.1",
+	"version": "0.13.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, and the access gate they install",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -29,6 +29,7 @@
 		"./styles/base.css": "./src/styles/base.css",
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./styles/components.css": "./src/styles/components.css",
+		"./styles/gate.css": "./src/styles/gate.css",
 		"./styles/star-rating.css": "./src/styles/star-rating.css",
 		"./gate": {
 			"types": "./dist/gate/index.d.ts",

package/src/components/GateLogin.tsx

@@ -0,0 +1,190 @@
+import { type FormEvent, useEffect, useId, useRef, useState } from "react";
+
+type Status = "idle" | "sending" | "sent" | "failed";
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export interface GateLoginProps {
+	/** Who the page behind the gate is for, set at the top of the screen. */
+	brandName: string;
+	/** The small line over the headline; with it the brand wears a "Preview" tag. */
+	eyebrow?: string;
+	headline?: string;
+	lead?: string;
+	/** Who built what is behind the gate, in the fine print. */
+	builtBy?: string;
+	/** A reply address, in the fine print. */
+	contactEmail?: string;
+	/**
+	 * Where the form posts. A site served under a base path passes its own
+	 * path to the function.
+	 */
+	endpoint?: string;
+}
+
+/**
+ * The access gate's sign in screen. Collects an email and posts it to the
+ * request link function, which emails a sign in link only to allowlisted
+ * addresses. The response is the same either way, so this screen always
+ * shows the same "check your inbox" confirmation.
+ *
+ * It renders the screen only: a site wraps it in its `.mkt` scope with no
+ * header, since a header would only point at pages the visitor cannot open
+ * yet. The button wears the site's own `.btn` classes, as the chrome's do.
+ */
+export function GateLogin({
+	brandName,
+	eyebrow,
+	headline = "A first look, by invitation.",
+	lead = "Enter your email and we will send a private link to the document.",
+	builtBy,
+	contactEmail,
+	endpoint = "/api/auth/request-link",
+}: GateLoginProps) {
+	const [status, setStatus] = useState<Status>("idle");
+	const [sentTo, setSentTo] = useState("");
+	const [expired, setExpired] = useState(false);
+	const [invalid, setInvalid] = useState(false);
+	const input = useRef<HTMLInputElement>(null);
+	const confirmation = useRef<HTMLHeadingElement>(null);
+	// A ref, since two submits can land before React renders the first one's state.
+	const inFlight = useRef(false);
+	const errorId = useId();
+
+	useEffect(() => {
+		const params = new URLSearchParams(window.location.search);
+		if (params.get("e") === "expired") setExpired(true);
+	}, []);
+
+	// The form leaves the page when the confirmation arrives, and focus would
+	// fall to the body with it. Moving it to the heading is also what tells a
+	// screen reader the request went through.
+	useEffect(() => {
+		if (status === "sent") confirmation.current?.focus();
+	}, [status]);
+
+	async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+		event.preventDefault();
+		const form = event.currentTarget;
+		// A second submit while the first is in flight would post twice, and a
+		// late failure would then pull the confirmation back to the form.
+		if (inFlight.current) return;
+		const email = String(new FormData(form).get("email") ?? "").trim();
+		if (!EMAIL_PATTERN.test(email)) {
+			// Nothing was sent, so an earlier failure no longer describes anything.
+			setStatus("idle");
+			setInvalid(true);
+			input.current?.focus();
+			return;
+		}
+		setInvalid(false);
+
+		const next = new URLSearchParams(window.location.search).get("next") ?? "/";
+		inFlight.current = true;
+		setStatus("sending");
+		try {
+			const response = await fetch(endpoint, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ email, next }),
+			});
+			if (!response.ok) throw new Error(`status ${response.status}`);
+			setSentTo(email);
+			setStatus("sent");
+			setExpired(false);
+		} catch {
+			setStatus("failed");
+		} finally {
+			inFlight.current = false;
+		}
+	}
+
+	// "Start over" swaps the confirmation for the form, and the button that
+	// held focus goes with it, so focus is handed to the field it leads to.
+	function startOver() {
+		setStatus("idle");
+		requestAnimationFrame(() => input.current?.focus());
+	}
+
+	return (
+		<div className="gate-screen">
+			<div className="gate-brand">
+				<span className="gate-brand-name">{brandName}</span>
+				{eyebrow && <span className="gate-brand-sub">Preview</span>}
+			</div>
+
+			<div className="gate-body">
+				{eyebrow && <p className="gate-eyebrow">{eyebrow}</p>}
+
+				{status === "sent" ? (
+					<>
+						<h1 className="gate-headline" ref={confirmation} tabIndex={-1}>
+							Check your inbox.
+						</h1>
+						<div className="gate-sent">
+							If <strong>{sentTo}</strong> is on the list, a sign in link is on its way. The link
+							expires shortly if unused, and once you are in, you stay signed in for a while.
+						</div>
+						<p className="gate-fine">
+							Wrong address?{" "}
+							<button type="button" className="gate-link-button" onClick={startOver}>
+								Start over
+							</button>
+						</p>
+					</>
+				) : (
+					<>
+						<h1 className="gate-headline">{headline}</h1>
+						{expired && (
+							<p className="gate-error" role="alert">
+								That link has expired. Enter your email and we will send a fresh one.
+							</p>
+						)}
+						<p className="gate-lead">{lead}</p>
+						<form className="gate-form" onSubmit={handleSubmit} noValidate>
+							<input
+								className="gate-input"
+								type="email"
+								name="email"
+								placeholder="you@company.com"
+								autoComplete="email"
+								aria-label="Your email"
+								aria-invalid={invalid || undefined}
+								aria-describedby={invalid ? errorId : undefined}
+								ref={input}
+								required
+							/>
+							<button
+								type="submit"
+								className="btn btn-primary btn-lg"
+								disabled={status === "sending"}
+							>
+								{status === "sending" ? "Sending…" : "Email me my link"}
+								<span className="arrow" aria-hidden="true">
+									→
+								</span>
+							</button>
+						</form>
+						{invalid && (
+							<p className="gate-error gate-error-after" id={errorId} role="alert">
+								That does not look like an email address. Check it and try again.
+							</p>
+						)}
+						{status === "failed" && (
+							<p className="gate-error gate-error-after" role="alert">
+								Something went wrong. Please try again in a moment.
+							</p>
+						)}
+						{(builtBy || contactEmail) && (
+							<p className="gate-fine">
+								{builtBy && `Built by ${builtBy}`}
+								{builtBy && contactEmail && " · "}
+								{contactEmail && <a href={`mailto:${contactEmail}`}>{contactEmail}</a>}
+							</p>
+						)}
+					</>
+				)}
+			</div>
+		</div>
+	);
+}

package/src/components/Watermark.tsx

@@ -0,0 +1,55 @@
+import { useEffect, useState } from "react";
+import { readCookie } from "../lib/readCookie";
+
+/**
+ * The confidential watermark stamped on every page behind the access gate.
+ * Reads the signed in viewer's email from the readable `gate_email` cookie
+ * (set when a sign in link is verified) and paints a corner pill, plus a
+ * faint tiled overlay when the gate runs in "tiled" mode. Renders nothing
+ * when there is no session, so it is inert on a public site and during
+ * prerender. The email travels into any screenshot. Mount it inside the
+ * site's `.mkt` (or `.atelic-ui`) wrapper, where its styles are scoped.
+ *
+ * It deters and attributes; it does not enforce. The cookies it reads are
+ * unsigned and it is drawn in the reader's own browser.
+ */
+export function Watermark() {
+	const [email, setEmail] = useState("");
+	const [mode, setMode] = useState("pill");
+
+	useEffect(() => {
+		setEmail(readCookie("gate_email"));
+		setMode(readCookie("gate_wm") || "pill");
+	}, []);
+
+	if (!email) return null;
+
+	return (
+		<>
+			{mode === "tiled" && (
+				<div className="gate-wm-tile-layer" aria-hidden="true">
+					{Array.from({ length: 32 }).map((_, index) => {
+						const row = Math.floor(index / 4);
+						const col = index % 4;
+						return (
+							<span
+								// biome-ignore lint/suspicious/noArrayIndexKey: fixed static grid, order is stable
+								key={index}
+								className="gate-wm-tile"
+								style={{ top: `${row * 13 + 2}%`, left: `${col * 27 - 6 + (row % 2 ? 13 : 0)}%` }}
+							>
+								confidential · {email}
+							</span>
+						);
+					})}
+				</div>
+			)}
+			<div className="gate-wm" aria-hidden="true">
+				<span className="gate-wm-dot" />
+				<span className="gate-wm-text">
+					Confidential preview · <b>{email}</b>
+				</span>
+			</div>
+		</>
+	);
+}

package/src/components/index.ts

@@ -1,3 +1,4 @@
+export { readCookie } from "../lib/readCookie";
 export { Callout, type CalloutProps } from "./Callout";
 export { Checklist, type ChecklistItem, type ChecklistProps } from "./Checklist";
 export { Collapsible, type CollapsibleProps } from "./Collapsible";
@@ -17,6 +18,7 @@ export {
 	type SortDirection,
 } from "./DataTable";
 export { Disclosure, type DisclosureProps } from "./Disclosure";
+export { GateLogin, type GateLoginProps } from "./GateLogin";
 export { NotFound, type NotFoundProps } from "./NotFound";
 export { StackedBar, type StackedBarProps, type StackedBarSegment } from "./StackedBar";
 export { describeStarRating, StarRating, type StarRatingProps } from "./StarRating";
@@ -34,3 +36,4 @@ export {
 	type ThresholdZone,
 } from "./ThresholdScale";
 export type { Tone } from "./tone";
+export { Watermark } from "./Watermark";

package/src/gate/wall.ts

@@ -11,7 +11,8 @@
  * the favicon in its head, and the brand marks the header draws, which every
  * prerendered page preloads because the router's pending page carries the
  * header (each site's e2e/wall.spec.ts fails when the login page asks for
- * anything else); plus the two sign in functions under /api/auth/, the login page itself,
+ * anything else); plus everything under /api/auth/, where the two sign in functions
+ * live and a host adds nothing private, the login page itself,
  * robots.txt, and the uptime monitor's health.json. /assets/doc/ is the one
  * part of /assets/ held back: the build writes every chunk carrying a
  * private content module there (the private chunks build plugin), so a document's

package/src/lib/readCookie.ts

@@ -0,0 +1,20 @@
+/**
+ * Read one cookie the page is allowed to see. Returns "" during prerender,
+ * when the cookie is not set, and when its value is not valid percent
+ * encoding, so a caller can treat all three as absent. The name is matched
+ * as written, never as a pattern, so one holding a dot or a bracket reads
+ * its own cookie and nothing else.
+ */
+export function readCookie(name: string): string {
+	if (typeof document === "undefined" || !name) return "";
+	for (const pair of document.cookie.split(";")) {
+		const split = pair.indexOf("=");
+		if (split === -1 || pair.slice(0, split).trim() !== name) continue;
+		try {
+			return decodeURIComponent(pair.slice(split + 1).trim());
+		} catch {
+			return "";
+		}
+	}
+	return "";
+}

package/src/styles/gate.css

@@ -0,0 +1,207 @@
+/* The access gate's two faces: the sign in screen (GateLogin) and the
+   confidential watermark (Watermark). Every value is a theme token, so the
+   gate recolors with the rest of a site. Scoped under `.mkt` or
+   `.atelic-ui`, which also lifts each rule over the base heading and
+   paragraph rules inside this layer. */
+@layer atelic-ui {
+	:is(.mkt, .atelic-ui) .gate-screen {
+		min-height: 100vh;
+		display: flex;
+		flex-direction: column;
+		background: var(--surface);
+		color: var(--ink);
+	}
+
+	:is(.mkt, .atelic-ui) .gate-brand {
+		display: flex;
+		align-items: baseline;
+		gap: 10px;
+		padding: 22px 32px;
+		border-bottom: 1px solid var(--neutral-100);
+	}
+	:is(.mkt, .atelic-ui) .gate-brand-name {
+		font-family: var(--font-serif);
+		font-style: italic;
+		font-size: 24px;
+		color: var(--ui-primary, var(--primary));
+	}
+	:is(.mkt, .atelic-ui) .gate-brand-sub {
+		font-family: var(--font-mono);
+		font-size: 11px;
+		letter-spacing: 0.22em;
+		text-transform: uppercase;
+		color: var(--ink-soft);
+	}
+
+	:is(.mkt, .atelic-ui) .gate-body {
+		flex: 1;
+		display: flex;
+		flex-direction: column;
+		justify-content: center;
+		align-items: center;
+		text-align: center;
+		padding: 52px 24px 44px;
+	}
+	:is(.mkt, .atelic-ui) .gate-eyebrow {
+		font-family: var(--font-mono);
+		font-size: 12px;
+		letter-spacing: 0.18em;
+		text-transform: uppercase;
+		color: var(--ui-primary, var(--primary));
+		margin: 0 0 16px;
+	}
+	:is(.mkt, .atelic-ui) .gate-headline {
+		font-family: var(--font-serif);
+		font-size: clamp(2rem, 4.4vw, 2.7rem);
+		line-height: 1.08;
+		margin: 0 0 16px;
+		max-width: 16ch;
+		text-wrap: balance;
+		color: var(--ink);
+	}
+	:is(.mkt, .atelic-ui) .gate-lead {
+		font-size: 1.05rem;
+		color: var(--ink-soft);
+		max-width: 46ch;
+		margin: 0 0 30px;
+		text-wrap: pretty;
+	}
+
+	:is(.mkt, .atelic-ui) .gate-form {
+		display: flex;
+		gap: 10px;
+		width: 100%;
+		max-width: 440px;
+		flex-wrap: wrap;
+		justify-content: center;
+	}
+	:is(.mkt, .atelic-ui) .gate-input {
+		flex: 1;
+		min-width: 220px;
+		font-family: var(--font-sans);
+		font-size: 15px;
+		/* The pill, matching the primary Button, so the pair reads as one
+		   control set (Forni's review of the SkySpec gate, 2026-08-25). */
+		padding: 15px 22px;
+		border-radius: var(--radius-pill);
+		border: 1px solid var(--neutral-200);
+		background: var(--ui-card, var(--card));
+		color: var(--ink);
+		outline: none;
+	}
+	:is(.mkt, .atelic-ui) .gate-input:focus-visible {
+		border-color: var(--ui-primary, var(--primary));
+		box-shadow: 0 0 0 3px var(--primary-focus-ring);
+	}
+	:is(.mkt, .atelic-ui) .gate-input::placeholder {
+		color: var(--neutral-500);
+	}
+
+	:is(.mkt, .atelic-ui) .gate-fine {
+		margin: 26px 0 0;
+		font-family: var(--font-mono);
+		font-size: 11.5px;
+		color: var(--neutral-500);
+	}
+	:is(.mkt, .atelic-ui) .gate-fine a {
+		color: var(--ui-primary, var(--primary));
+		text-decoration: none;
+	}
+	:is(.mkt, .atelic-ui) .gate-fine a:hover {
+		text-decoration: underline;
+	}
+
+	:is(.mkt, .atelic-ui) .gate-sent {
+		margin: 4px auto 0;
+		max-width: 440px;
+		border: 1px solid var(--neutral-100);
+		border-radius: var(--radius-sm);
+		background: var(--primary-tint);
+		padding: 18px 20px;
+		text-align: left;
+		color: var(--ink-soft);
+	}
+	:is(.mkt, .atelic-ui) .gate-sent strong {
+		color: var(--ink);
+	}
+	:is(.mkt, .atelic-ui) .gate-error {
+		margin: 0 0 22px;
+		max-width: 44ch;
+		font-size: 0.95rem;
+		color: var(--ink);
+		background: var(--surface-alt);
+		border: 1px solid var(--neutral-200);
+		border-radius: var(--radius-sm);
+		padding: 11px 16px;
+	}
+
+	/* The "Start over" control reads as a link in the fine print. */
+	:is(.mkt, .atelic-ui) .gate-link-button {
+		background: none;
+		border: none;
+		color: var(--ui-primary, var(--primary));
+		cursor: pointer;
+		font: inherit;
+		padding: 0;
+	}
+	/* The failure line under the form, where the default bottom margin is spare. */
+	:is(.mkt, .atelic-ui) .gate-error.gate-error-after {
+		margin-top: 22px;
+		margin-bottom: 0;
+	}
+
+	/* ---- Watermark ---- */
+	:is(.mkt, .atelic-ui) .gate-wm {
+		position: fixed;
+		right: 16px;
+		bottom: 16px;
+		z-index: 2147483000;
+		display: flex;
+		align-items: center;
+		gap: 9px;
+		max-width: calc(100vw - 32px);
+		padding: 8px 13px;
+		border-radius: 999px;
+		font-family: var(--font-mono);
+		font-size: 11px;
+		letter-spacing: 0.03em;
+		background: var(--surface-dark);
+		color: var(--surface);
+		box-shadow: var(--shadow-md, 0 8px 24px -10px rgba(0, 0, 0, 0.5));
+		pointer-events: none;
+	}
+	:is(.mkt, .atelic-ui) .gate-wm b {
+		color: #fff;
+		font-weight: 600;
+	}
+	:is(.mkt, .atelic-ui) .gate-wm-dot {
+		width: 7px;
+		height: 7px;
+		border-radius: 50%;
+		background: var(--primary-bright);
+		flex-shrink: 0;
+	}
+	:is(.mkt, .atelic-ui) .gate-wm-text {
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	:is(.mkt, .atelic-ui) .gate-wm-tile-layer {
+		position: fixed;
+		inset: 0;
+		z-index: 2147482000;
+		pointer-events: none;
+		overflow: hidden;
+		opacity: 0.5;
+	}
+	:is(.mkt, .atelic-ui) .gate-wm-tile {
+		position: absolute;
+		font-family: var(--font-mono);
+		font-size: 12px;
+		color: var(--ui-primary, var(--primary));
+		opacity: 0.12;
+		white-space: nowrap;
+		transform: rotate(-30deg);
+	}
+}