@atelic-action/ui 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @atelic-action/ui
 
-Shared UI for the Atelic templates: the site chrome (header, menu, footer, sticky CTA bar, and credit band), the scroll spy hook, and the one base stylesheet. The marketing and artifact templates install it instead of carrying their own copies, so a chrome fix lands once and every site picks it up with `bun update`.
+Shared UI for the Atelic templates: the site chrome (header, menu, footer, sticky CTA bar, and credit band), the not found page and the routing that keeps it alive, the scroll spy hook, and the one base stylesheet. The marketing and artifact templates install it instead of carrying their own copies, so a chrome fix lands once and every site picks it up with `bun update`.
 
 The package ships source, not a build. Its TSX and CSS arrive as written and compile inside each site's own Vite.
 
@@ -30,22 +30,26 @@ Import the stylesheets in this order, from the root route or the site's base she
 1. The site's fonts (`fonts.css`)
 2. `@atelic-action/ui/styles/base.css`
 3. `@atelic-action/ui/styles/chrome.css`
-4. The site's own CSS
-5. The site's `theme.css`, last
+4. `@atelic-action/ui/styles/components.css`
+5. The site's own CSS
+6. The site's `theme.css`, last
 
-Both package sheets sit inside `@layer atelic-ui`, so any rule a site writes outside a layer wins over them whatever its specificity. The package reads the theme tokens (`--ink`, `--surface`, `--primary`, `--nav-height`, and the rest) and defines none, so `theme.css` stays the one file a site edits to rebrand. The chrome's buttons wear the site's own `.btn` classes.
+The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outside a layer wins over them whatever its specificity. The package reads the theme tokens (`--ink`, `--surface`, `--primary`, `--nav-height`, and the rest) and defines none, so `theme.css` stays the one file a site edits to rebrand. The chrome's buttons wear the site's own `.btn` classes.
 
 ## What Is Inside
 
 | Import | Exports |
 |---|---|
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
+| `@atelic-action/ui/components` | `NotFound` and its prop types (see [The Not Found Page](#the-not-found-page)) |
 | `@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/routing` | `staticNotFoundRouting`, the router options behind the not found page |
 | `@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` |
+| `@atelic-action/ui/styles/components.css` | Layout defaults for everything under `components` |
 
 Every component renders from props alone. None reads a config file or a router, so a site maps its own config onto the props in its shell:
 
@@ -69,6 +73,37 @@ 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.
 
+## The Not Found Page
+
+`NotFound` is the page an unknown path renders: a headline, a row of popular pages, and the closing call to action. It renders the body only, so a site wraps it in its own shell, and it wears the site's own classes (`.page-hero`, `.eyebrow`, `.lead`, `.final-cta`, `.btn`).
+
+On a statically prerendered TanStack Start site the markup is the easy part. The host serves the `/404` prerender for every miss, and the page survives hydration only with three pieces in the site:
+
+1. **A catch all route**, `src/routes/$.tsx`, rendering the site's page (noindexed). Never a dedicated `/404` route: an unknown path then matches only the root, TanStack's hydrate throws, and the page goes blank.
+2. **The router options:** `createRouter({ routeTree, ...staticNotFoundRouting(NotFoundPage) })`. A miss hydrates through its pending state first, so pending has to render the same page or React reports a mismatch.
+3. **The build:** a `{ path: "/404", prerender: { enabled: true }, sitemap: { exclude: true } }` entry in the Vite `pages` list, and a copy of `dist/client/404/index.html` to `dist/client/404.html`.
+
+```tsx
+// src/shared/components/NotFoundPage.tsx
+import { NotFound } from "@atelic-action/ui/components";
+
+export function NotFoundPage() {
+	return (
+		<SiteShell site={site}>
+			<NotFound
+				title="This page wandered off."
+				lead="The link may be old, or the page may have moved."
+				links={site.nav.filter((item) => item.to !== "/").map(({ label, to }) => ({ label, href: to }))}
+				closing={{ eyebrow: "Back on Track", title: "Let's get you where you were headed." }}
+				primaryCTA={site.cta}
+			/>
+		</SiteShell>
+	);
+}
+```
+
+`staticNotFoundRouting` is for prerendered sites only. On a live app the pending state is a real loading moment and the page would flash through every slow load, so an app sets `defaultNotFoundComponent` alone. A browser test is the only proof any of this works; template-marketing's `e2e/not-found.spec.ts` is the one to copy.
+
 ## 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/package.json

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

package/src/components/NotFound.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react";
+import { newTabProps } from "../lib/newTabProps";
+import type { CallToAction, NavLink } from "../types";
+
+export interface NotFoundProps {
+	/** The kicker above the headline. Defaults to "404". */
+	eyebrow?: string;
+	title: ReactNode;
+	lead?: ReactNode;
+	/** A short list of pages worth landing on, usually the nav without Home. */
+	links?: NavLink[];
+	/** The heading and accessible name of the links row. Defaults to "Popular Pages". */
+	linksLabel?: string;
+	/** The closing section's kicker and headline. */
+	closing: { eyebrow?: string; title: ReactNode };
+	/** The site's primary conversion action, rendered first. */
+	primaryCTA: CallToAction;
+	/** The ghost action beside it. Defaults to "Back to Home" at "/". */
+	secondary?: NavLink;
+}
+
+/**
+ * The page a missing path renders: a headline, a row of popular pages, and
+ * the closing call to action. It renders the page body only; a site wraps it
+ * in its own shell, as it does every page. The markup wears the site's own
+ * classes (.page-hero, .eyebrow, .lead, .final-cta, .btn), so a site that
+ * styles them gets its own look, and components.css covers the layout where
+ * it does not.
+ *
+ * Keeping it alive through hydration takes routing as well as markup; see
+ * staticNotFoundRouting in the routing entry.
+ */
+export function NotFound({
+	eyebrow = "404",
+	title,
+	lead,
+	links = [],
+	linksLabel = "Popular Pages",
+	closing,
+	primaryCTA,
+	secondary = { label: "Back to Home", href: "/" },
+}: NotFoundProps) {
+	return (
+		<>
+			<section className="page-hero not-found-hero">
+				<div className="wrap">
+					<span className="eyebrow">{eyebrow}</span>
+					<h1>{title}</h1>
+					{lead && <p className="lead">{lead}</p>}
+				</div>
+			</section>
+			{links.length > 0 && (
+				<section className="section not-found-links">
+					<div className="wrap center">
+						<span className="eyebrow center">{linksLabel}</span>
+						<nav aria-label={linksLabel} className="cta-row center">
+							{links.map((link) => (
+								<a key={link.href} className="btn btn-ghost" href={link.href}>
+									{link.label}
+								</a>
+							))}
+						</nav>
+					</div>
+				</section>
+			)}
+			<section className="section final-cta surface-alt not-found-closing">
+				<div className="wrap center">
+					{closing.eyebrow && <span className="eyebrow center">{closing.eyebrow}</span>}
+					<h2>{closing.title}</h2>
+					<div className="cta-row center">
+						<a
+							className="btn btn-primary btn-lg"
+							href={primaryCTA.href}
+							{...newTabProps(primaryCTA.href, primaryCTA.external)}
+						>
+							{primaryCTA.label}
+							<span className="arrow">{"→"}</span>
+						</a>
+						<a className="btn btn-ghost btn-lg" href={secondary.href}>
+							{secondary.label}
+						</a>
+					</div>
+				</div>
+			</section>
+		</>
+	);
+}

package/src/components/index.ts

@@ -0,0 +1 @@
+export { NotFound, type NotFoundProps } from "./NotFound";

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;
+	}
+}