@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/pages/docs-shell/docs-shell.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from '../../components/ui/prose.js';
+import { headingSizeClass } from '../../components/ui/section.js';
 import { Heading, Text } from '../../components/ui/typography.js';
 import { cn } from '../../lib/utils.js';
 /**
@@ -59,13 +60,85 @@ import { cn } from '../../lib/utils.js';
  * author filed it. A Page that sorted its rail would flatten the one thing the
  * three sites disagree about and cannot both be right about.
  *
- * **The rail is bounded in height.** Atlas files nineteen pages and AlphaLens
- * files twenty-seven, so the taller tree is half again as long, and an unbounded
- * rail on a tall tree is a rail that pushes the document below the fold before
- * the reader has read a line of it. The rail and the contents rail are each
- * capped against the viewport and scroll inside it, so a nineteen-page tree and a
- * twenty-seven-page tree are both a full screen and neither is a page-long
- * sidebar.
+ * **The rail is bounded in height, and the bound is what the reader has to be
+ * able to see.** Atlas files nineteen pages and AlphaLens files twenty-seven, so
+ * the taller tree is half again as long, and an unbounded rail on a tall tree is
+ * a rail that pushes the document below the fold before the reader has read a
+ * line of it. The rail and the contents rail are each capped against the viewport
+ * and scroll inside it, so a nineteen-page tree and a twenty-seven-page tree are
+ * both a full screen and neither is a page-long sidebar.
+ *
+ * **A cap the reader cannot see is a defect, and this one was invisible for 344
+ * and 750 pixels.** Measured in two consumers' built exports at 1280 by 680, the
+ * rail's content stood at 912 and 1318 pixels against a 568 pixel box, so more
+ * than half of one site's documentation navigation sat below the fold with
+ * `mask-image: none`, no scrollbar Chrome would draw until the reader scrolled,
+ * no fade and no count. Chrome's overlay scrollbars are the reason this is not
+ * caught by looking: they appear on scroll, so the first render of a rail that
+ * hides half its content is indistinguishable from a rail that has all of it, and
+ * the last visible row was cut mid-word above dead space, which reads as a
+ * rendering fault rather than as a scroll region.
+ *
+ * **The affordance is a fade across the foot of the scroll region, with the space
+ * it covers reserved rather than borrowed.** Three answers were available and the
+ * other two were rejected for stated reasons. A persistent themed scrollbar is
+ * truthful at both ends and costs nothing to legibility, and it is still here in
+ * the sense that the region is a real scroll region rather than a clipped box,
+ * but it is a single hairline whose length says "there is more" without saying
+ * which way, it needs `scrollbar-gutter` reserved in a 15rem rail to stop the
+ * content shifting when a short tree becomes a tall one, and in Chrome it is the
+ * least reliable of the three to reason about because the property that makes it
+ * persistent is the same one whose default is an overlay. A collapse control needs
+ * a disclosure whose state a server Component cannot hold. An "N more" control is
+ * copy this Page does not ship and it needs the count the Page cannot compute
+ * without measuring, which is the one thing a server Component cannot do.
+ *
+ * So the fade, and it is painted on a wrapper that does not scroll rather than on
+ * the scroll region itself: a mask or a gradient inside the scrollport moves with
+ * the content and marks nothing. The wrapper carries the sticky offset, the
+ * scroll region keeps the cap and the scrolling, and the gradient is pinned to
+ * the wrapper's foot. The region carries `padding-bottom` of the same height, and
+ * that is the half that makes it honest: at rest the gradient falls on reserved
+ * space and the last row is fully legible, and only while there is more below
+ * does it fall on content. Without the padding the same gradient washes the last
+ * row permanently, which is the usual cost of this answer and the reason the
+ * padding is not optional.
+ *
+ * **The fade is paint, and it is on the accessibility tree's terms.** It is an
+ * empty element with `aria-hidden` and `pointer-events-none`, inside the `<nav>`
+ * and outside the `<ul>`, so it is not a list item, it is not announced, it never
+ * takes a press and it never reaches a Tab stop. A keyboard reader scrolls the
+ * region with the arrow keys exactly as before and reaches every entry, and a
+ * screen-reader user is told nothing at all, which is the right answer: the cut is
+ * a fact about ink, and announcing it would put a sentence in the middle of a
+ * list of a consumer's own pages.
+ *
+ * **Below `lg` there was no navigation at all, and the fix is a native
+ * disclosure.** At 768 and at 1024 both rails were `hidden` and the only
+ * navigation left inside `<main>` was the two-item pager at the foot of the
+ * article, so a reader on a thirty-one document reference at tablet width had no
+ * contents, no on-this-page and no way to a sibling page except Previous and
+ * Next. The disclosure is `<details>` and `<summary>`, which is the one
+ * disclosure widget that needs no runtime at all: it is expanded and collapsed by
+ * the platform, it is a real control in the Tab order with a real expanded state,
+ * and adding a client boundary to a server Component to reinvent it would put
+ * bytes on every documentation page in the family to save a reader one click.
+ *
+ * The tree is rendered twice, once in each arrangement, and only one of them is
+ * in the document at any width: the rail is `hidden lg:block` and the disclosure
+ * is `lg:hidden`, so the other one is `display: none` and is out of the
+ * accessibility tree and out of the tab order rather than a second copy a reader
+ * meets. The summary carries `navLabel` or `tocLabel`, which is the caller's own
+ * word for that navigation and therefore the one word on the control that cannot
+ * be wrong in a language the consumer did not write in.
+ *
+ * **The frame is three columns from `lg`, and the third is the consumer's to
+ * fill.** The rail is 15rem, the document takes the rest, and the contents rail
+ * is 13rem. The third track exists only when `toc` is passed, because the
+ * document takes the second track by auto-placement and a template that named a
+ * track no child occupies would leave the document in the 15rem one. Below `lg`
+ * the frame is a single column: the document fills it and the two navigations sit
+ * above it behind their disclosures.
  *
  * It is a Page rather than a Block because it is a whole screen and it is the
  * screen a content pipeline targets: a route that reads one document and hands
@@ -76,7 +149,10 @@ import { cn } from '../../lib/utils.js';
  *
  * It is a server Component. It fetches nothing, it holds no state and it imports
  * no router, so a consumer renders it from whichever route their framework names
- * and hands it the document their pipeline produced.
+ * and hands it the document their pipeline produced. The sub-`lg` disclosure is
+ * the reason that stays true under pressure: it is the one feature on this Page
+ * that a hand would be tempted to write as a client Component, and it is written
+ * as markup instead.
  */
 export function DocsShell({ title, description, nav, toc, currentHref, navLabel, tocLabel, pagerLabel, pagerLabels, header, footer, className, children, }) {
     readTree(nav, 'nav');
@@ -84,13 +160,86 @@ export function DocsShell({ title, description, nav, toc, currentHref, navLabel,
     const rail = nav && nav.length > 0 ? nav : undefined;
     const contents = toc && toc.length > 0 ? toc : undefined;
     const neighbours = currentHref === undefined ? undefined : deriveNeighbours(nav ?? [], currentHref);
-    return (_jsxs("div", { "data-slot": "docs-shell", className: cn('mx-auto w-full max-w-6xl px-6 py-10 lg:px-8', className), children: [header, _jsxs("div", { "data-slot": "docs-shell-frame", className: cn('flex flex-col gap-8 lg:flex-row lg:gap-10', 
-                // One column for the document, and a third for whichever rails are
-                // present. The frame is sized by what the consumer passed rather than
-                // by a fixed three-column grid, so a tree with no contents rail leaves
-                // the document the width the two remaining columns divide between
-                // them.
-                contents ? 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)] xl:grid-cols-[15rem_minmax(0,1fr)_13rem]' : 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)]'), children: [rail ? (_jsx("aside", { "data-slot": "docs-rail", className: "hidden lg:col-start-1 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": navLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto lg:pe-4", children: _jsx(NavList, { entries: rail, currentHref: currentHref, depth: 0 }) }) })) : null, _jsxs("article", { "data-slot": "docs-article", className: "flex min-w-0 flex-col gap-8", children: [title ? (_jsxs("header", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h1", size: "3xl", children: title }), description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null] })) : description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null, _jsx(Prose, { fullWidth: true, children: children }), neighbours ? (_jsx(Pager, { previous: neighbours.previous, next: neighbours.next, label: pagerLabel, labels: pagerLabels })) : null] }), contents ? (_jsx("aside", { "data-slot": "docs-contents", className: "hidden lg:col-start-3 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": tocLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto", children: _jsx(NavList, { entries: contents, currentHref: currentHref, depth: 0 }) }) })) : null] }), footer] }));
+    const unnamedNav = unnamedIn(nav);
+    const unnamedToc = unnamedIn(toc);
+    return (_jsxs("div", { "data-slot": "docs-shell", className: cn('mx-auto w-full max-w-page px-6 py-10 lg:px-8', className), children: [header, _jsxs("div", { "data-slot": "docs-shell-frame", className: cn('flex flex-col gap-8 lg:flex-row lg:gap-10', 
+                // One track for the rail, one for the document, and a third for the
+                // contents rail when there is one. The template names exactly the
+                // tracks the children occupy rather than a fixed three-column grid,
+                // because the document takes the second track by auto-placement: a
+                // tree with no contents rail has two children, so a three-track
+                // template would leave the document in the 15rem first track.
+                //
+                // The third track is at the same width as the two-column frame, and
+                // that is a fact about the token package rather than a preference: the
+                // emitted theme closes `xl` with `initial`, so a third track written
+                // against a wider screen compiled to no media query at all, and the
+                // contents rail landed in an implicit `auto` track rather than the
+                // 13rem one. `check-breakpoint-variants.mjs` is the gate that says so
+                // to the next class written against a screen the theme does not emit.
+                contents ? 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)_13rem]' : 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)]'), children: [rail || contents ? (_jsxs("div", { "data-slot": "docs-nav-compact", className: "flex flex-col gap-4 lg:hidden", children: [rail ? (_jsx(Disclosure, { label: navLabel, unnamed: unnamedNav, children: _jsx(NavList, { entries: rail, currentHref: currentHref, depth: 0 }) })) : null, contents ? (_jsx(Disclosure, { label: tocLabel, unnamed: unnamedToc, children: _jsx(NavList, { entries: contents, currentHref: currentHref, depth: 0 }) })) : null] })) : null, rail ? (_jsx("aside", { "data-slot": "docs-rail", className: "hidden lg:col-start-1 lg:row-start-1 lg:block", children: _jsx(Rail, { label: navLabel, entries: rail, currentHref: currentHref, unnamed: unnamedNav }) })) : null, _jsxs("article", { "data-slot": "docs-article", className: "flex min-w-0 flex-col gap-8", children: [title ? (_jsxs("header", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h1", className: headingSizeClass('h1'), children: title }), description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null] })) : description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null, _jsx(Prose, { fullWidth: true, children: children }), neighbours ? (_jsx(Pager, { previous: neighbours.previous, next: neighbours.next, label: pagerLabel, labels: pagerLabels })) : null] }), contents ? (_jsx("aside", { "data-slot": "docs-contents", className: "hidden lg:col-start-3 lg:row-start-1 lg:block", children: _jsx(Rail, { label: tocLabel, entries: contents, currentHref: currentHref, unnamed: unnamedToc }) })) : null] }), footer] }));
+}
+/* ------------------------------------------------------------------ *
+ * The two rails at lg
+ * ------------------------------------------------------------------ */
+/**
+ * One rail: a region that scrolls inside a bound against the viewport, with the
+ * cut at its foot marked so the rows below it are discoverable.
+ *
+ * **The sticky offset is on this wrapper and not on the scroll region, and the
+ * reason is the fade.** The fade has to be pinned to the foot of the region while
+ * the region scrolls, and nothing inside a scroll container stays put while that
+ * container scrolls: a gradient or a mask written into the scrollport travels with
+ * the content and so marks nothing once the reader has scrolled. The wrapper is
+ * the element that travels, so the fade is absolutely positioned against it and
+ * the `<nav>` inside is free to be nothing but the scroll region.
+ *
+ * The cap is `100svh` less the sticky offset plus the gap under it, and `svh` is
+ * the smallest viewport height rather than the largest, which is the direction that
+ * matters here. `dvh` would grow to the full height the moment a mobile browser's
+ * URL bar retracted, and a sticky region measured against a viewport taller than
+ * the one on screen is a region whose foot is below the bottom of the screen
+ * while it is pinned, which is the one state the bound exists to prevent. `svh`
+ * is never taller than what is visible, so `top` plus `max-h` is always inside the
+ * viewport and the rail's foot always clears it. `top-20` is 5rem and the cap is
+ * the viewport less 7rem, so the foot sits 2rem above the bottom edge at every
+ * window height; a short window makes the rail shorter and does not make it
+ * taller than the space it is pinned in.
+ *
+ * `padding-bottom` is the same height as the fade, and it is what makes the fade
+ * honest. The gradient falls on the last 2rem of whatever the scrollport is
+ * showing, so with the padding reserved it falls on empty space once the reader
+ * has reached the end and on content only while there is more below. Without it
+ * the same gradient permanently washes the bottom of the last row, which is the
+ * usual cost of a fade and the reason the padding is part of the answer rather
+ * than a detail.
+ *
+ * `unnamed` is carried on the `<nav>` rather than logged, for the reason
+ * `unnamedIn` gives.
+ */
+function Rail({ label, entries, currentHref, unnamed, }) {
+    return (_jsxs("div", { className: "relative lg:sticky lg:top-20", children: [_jsx("nav", { "aria-label": label, "data-unnamed-entries": unnamed, className: "lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto lg:pe-4 lg:pb-8", children: _jsx(NavList, { entries: entries, currentHref: currentHref, depth: 0 }) }), _jsx("div", { "aria-hidden": "true", "data-slot": "docs-rail-fade", className: "from-background pointer-events-none absolute inset-x-0 bottom-0 h-8 bg-gradient-to-t to-transparent" })] }));
+}
+/**
+ * One tree behind a native disclosure, for the widths where there is no rail.
+ *
+ * `<details>` rather than a Component, and the whole argument is that it needs no
+ * runtime: the platform holds the expanded state, the control is in the Tab order
+ * with a real expanded state, and the Page stays a server Component. A Page that
+ * shipped a client disclosure for this would put JavaScript on every documentation
+ * page in the family to replace a browser feature that has been in the platform
+ * since 2018.
+ *
+ * **The summary's word is the caller's.** `navLabel` and `tocLabel` are already
+ * required props and already name these two navigations for a screen reader, so
+ * the control that opens one says the same thing the region inside it is called
+ * and the Page ships no word of its own. Nothing suppresses the browser's own
+ * disclosure marker or its own focus ring: the marker is the cheapest honest
+ * signal that the row is a disclosure, and `py-3` puts the target at 44 pixels for
+ * a coarse pointer without a variant.
+ */
+function Disclosure({ label, unnamed, children, }) {
+    return (_jsxs("details", { "data-slot": "docs-nav-disclosure", children: [_jsx("summary", { className: "text-foreground cursor-pointer py-3 text-sm font-medium", children: label }), _jsx("nav", { "aria-label": label, "data-unnamed-entries": unnamed, className: "pb-4", children: children })] }));
 }
 /* ------------------------------------------------------------------ *
  * The tree
@@ -107,6 +256,21 @@ export function DocsShell({ title, description, nav, toc, currentHref, navLabel,
 function addressOf(href) {
     return href !== undefined && href.trim() !== '' ? href : undefined;
 }
+/**
+ * Whether an entry has words to be called by.
+ *
+ * Blank counts as none, for the same reason `addressOf` counts it: all three
+ * consumer adapters build a title out of whatever their content pipeline produced,
+ * and one of them maps a heading whose title arrives as a React element to the
+ * empty string. A row is rendered from a string, and a string of spaces is not a
+ * name. It is read here rather than at each use because `destinationOf` decides
+ * between a link and a label, the renderer decides between a row and nothing, and
+ * the counter decides how many rows went missing, and three answers to one
+ * question is how a fourth grows.
+ */
+function named(entry) {
+    return entry.title.trim() !== '';
+}
 /**
  * The address an entry is reachable at, or `undefined` when it is not a
  * destination at all.
@@ -119,7 +283,35 @@ function addressOf(href) {
  * `Next` link under it.
  */
 function destinationOf(entry) {
-    return entry.title === '' ? undefined : addressOf(entry.href);
+    return named(entry) ? addressOf(entry.href) : undefined;
+}
+/**
+ * How many entries in a tree the Page cannot name, and therefore did not draw.
+ *
+ * **It is counted rather than swallowed, and the place it is counted on is the
+ * rail itself.** `Diagram` answers a dropped relation the same way, with
+ * `data-unresolved-relations` on the drawing, and the argument is the same one: a
+ * row that did not draw is a fact about the caller's data, and a fact that leaves
+ * no trace is a defect the next reader has to rediscover from a screenshot. The
+ * number is on the element rather than in a console because a caller reads the
+ * element and does not read the console.
+ *
+ * Three things are counted, because three things go missing rather than two:
+ * a page with no words, which is dropped whole; a group with no words, whose
+ * label is not rendered while its pages still are; and a group with neither words
+ * nor children, which has nothing left to draw and is dropped whole.
+ */
+function unnamedIn(entries) {
+    let count = 0;
+    for (const entry of entries ?? []) {
+        if (entry.type === 'divider')
+            continue;
+        if (!named(entry))
+            count += 1;
+        if (entry.type === 'group')
+            count += unnamedIn(entry.items);
+    }
+    return count;
 }
 /**
  * Reads a tree before any of it renders, and refuses the one shape it cannot
@@ -188,15 +380,23 @@ function NavNode({ entry, currentHref, depth, }) {
     }
     const href = destinationOf(entry);
     if (entry.type === 'group') {
-        return (_jsx("li", { "data-slot": "docs-nav-group", children: _jsxs("div", { className: "flex flex-col gap-1", children: [href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(entry, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-heading", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })), entry.items.length > 0 ? (_jsx(NavList, { entries: entry.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
+        // A group with no words and no pages has nothing left to draw, and a `<li>`
+        // holding an empty `<div>` is the same empty row the page arm used to render.
+        // Dropping it costs nothing, because there was nothing in it.
+        if (!named(entry) && entry.items.length === 0)
+            return null;
+        return (_jsx("li", { "data-slot": "docs-nav-group", children: _jsxs("div", { className: "flex flex-col gap-1", children: [!named(entry) ? null : href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(entry, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-heading", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })), entry.items.length > 0 ? (_jsx(NavList, { entries: entry.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
     }
-    // The page arm. `href` is never empty here: `readTree` refused that above and
-    // named the entry, so what is left to decide is the words. A nameless page is
-    // the same rule as a group with no index, rendered as a label, because a link
-    // with no accessible name is announced as "link" and nothing else.
-    return (_jsx("li", { "data-slot": "docs-nav-page", children: href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: "-ms-px block border-l-2 border-transparent py-1 ps-3 text-sm text-muted-foreground", children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-link", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === href
+    // The page arm, and there is one shape of it left. `readTree` refused a page
+    // with no address above and named the entry, so every page that reaches here has
+    // one, and a page with no words is not rendered at all rather than rendered as
+    // a label: a link with no accessible name is announced as "link" and nothing
+    // else, and a blank row is not a label either because a label is words.
+    if (!named(entry))
+        return null;
+    return (_jsx("li", { "data-slot": "docs-nav-page", children: _jsx("a", { "data-slot": "docs-nav-link", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === href
                 ? 'text-foreground border-primary font-medium'
-                : 'text-muted-foreground hover:text-foreground border-transparent'), children: entry.title })) }));
+                : 'text-muted-foreground hover:text-foreground border-transparent'), children: entry.title }) }));
 }
 /**
  * Every page the tree holds, in the order a reader meets them.
@@ -208,11 +408,12 @@ function NavNode({ entry, currentHref, depth, }) {
  * the pager to reach either. A divider contributes nothing at all.
  *
  * The row a reader can click and the row the pager can reach are decided by the
- * SAME function, `destinationOf`. A nameless entry is a label on the rail and is
- * dropped here, so one malformed row cannot be published twice: a nameless anchor
- * in the rail, and a `Next` link under it carrying the text of whichever entry
- * happened to follow, is what deriving without asking produced. The two surfaces
- * do not each get their own opinion about a row that is not a page.
+ * SAME function, `destinationOf`, and a row with no words is now dropped from the
+ * rail as well, so the two surfaces agree twice over rather than once by accident.
+ * The defect this replaced was a nameless anchor in the rail and a `Next` link
+ * under it carrying the text of whichever entry happened to follow, published
+ * from one malformed row. Deriving without asking produced the first and a
+ * separate opinion produced the second; asking once produces neither.
  */
 function flatten(entries, into = []) {
     for (const entry of entries) {

package/dist/pages/error-page/index.d.ts

@@ -0,0 +1,188 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One way out of a failed screen, and the words for it.
+ *
+ * Identical to `NotFoundLink`, and it is a second declaration rather than an import
+ * because a Page's props are the surface a consumer reads and this Page is shipped
+ * from its own subpath: a consumer reading the corpus for a retry screen should not
+ * have to know that a not-found screen also exists. The duplication is four fields
+ * and a key, and the alternative is a shared type in one Page's module that the
+ * other Page's documentation would then be about.
+ */
+export type ErrorPageLink = {
+    /** The words of the link. */
+    label: string;
+    /** Where it goes. */
+    href: string;
+    /**
+     * Opens the destination in a new browsing context, which defaults the link
+     * relationship to `noopener noreferrer`. Almost never right on a failed screen: a
+     * reader who has just been shown a failure and is sent to a new tab has to find
+     * their way back and cannot tell whether the thing they were doing is still there.
+     */
+    newTab?: boolean;
+};
+/**
+ * Every field of an ErrorPage except whether it shows a support reference.
+ *
+ * Not exported, because the two arms below are what a caller writes and this is
+ * only the half they share. The union is what makes `referenceLabel` required
+ * wherever `reference` is set, and a flat pair of optional props could not: a
+ * reference with no label is a value on the page that nothing names, and a label
+ * with no reference is a word heading nothing.
+ */
+type ErrorPageFields = {
+    /**
+     * The status code, drawn as the page's own `h1`.
+     *
+     * Required, and a string rather than a number because it is displayed, not
+     * computed: a Page never decides what code it is answering, and a code a product
+     * derives from its own exception class is a code this Page would then be
+     * asserting about the consumer's deployment.
+     */
+    code: string;
+    /**
+     * The headline under the code: the sentence that says what happened.
+     *
+     * A `string` because it is one sentence and it is the part a reader actually
+     * reads, and it is the caller's because every product says it differently.
+     */
+    title: string;
+    /** One or two sentences, for anything a reader should know before they press anything. */
+    description?: string;
+    /**
+     * The control that tries the failed request again.
+     *
+     * A node and not a label and a handler, and that is the decision this Page is
+     * shaped around. See the JSDoc on the Page: a slot is what keeps this screen a
+     * server Component while the retry is still the first thing on it.
+     */
+    retry?: ReactNode;
+    /**
+     * The ways out, in the order a reader should see them. Put the destination most
+     * likely to help first.
+     */
+    links: readonly ErrorPageLink[];
+    /**
+     * The accessible name of the row of ways out.
+     *
+     * Required, because it is a word a reader hears and a Page that ships no copy
+     * ships no reader-facing copy either. The Page's own phrasing is "where to next";
+     * a site that files its destinations differently names the same landmark
+     * differently.
+     */
+    linksLabel: string;
+    /** A slot for anything else the site wants to say here: a status page, a chat route. */
+    children?: ReactNode;
+    /**
+     * The level of the code, and one step below it for the headline.
+     *
+     * Defaults to `h1`, because a Page owns the top of the document outline and the
+     * code is this screen's one string that is the same for every failure of its kind.
+     */
+    headingLevel?: HeadingLevel;
+    /** Layout only, exactly as on every Item. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * The props an ErrorPage takes.
+ *
+ * Every string and every destination is a prop and the Page ships none. There is no
+ * "something went wrong", no "please try again" and no product name, for the same
+ * reason `NotFoundPage` gives: the failure screens are the ones every reader and no
+ * crawler sees, so a sentence written here would be a claim about a product this
+ * package knows nothing about, in the exact place where being wrong is worst.
+ */
+export type ErrorPageProps = ErrorPageFields & ({
+    /**
+     * The support reference a reader quotes to a person: the request id, the
+     * incident, the case number.
+     *
+     * A `string` because it is a machine value a reader copies rather than
+     * reads, which is why it is drawn in the mono face and why the label beside
+     * it is the caller's word.
+     */
+    reference: string;
+    /**
+     * The word naming that value.
+     *
+     * Required here and forbidden on the other arm. "Reference", "Incident"
+     * and "Case" are three words for three products, and a reference a reader
+     * has to guess the name of is a reference they cannot quote.
+     */
+    referenceLabel: string;
+} | {
+    /** No reference on this screen. */
+    reference?: never;
+    /** No word is needed, because there is no value to name. */
+    referenceLabel?: never;
+});
+/**
+ * A complete failure screen: the code, what happened, the retry, and the ways out.
+ *
+ * **This is the third of the three Pages that `DESIGN.md` records under Known Open
+ * Items as deferred to v1.1**, so it discharges that row rather than adding to the
+ * tail. The other two are `PricingPage` and `OnboardingPage`.
+ *
+ * **It is the sibling of `NotFoundPage` and the two fail for opposite reasons, which
+ * is the reason they are two items rather than one with a prop.** A not-found is a
+ * request that will never succeed: the address is wrong, the page was never there,
+ * and no amount of asking again produces it, so a retry on a 404 is a lie told by a
+ * button, and a reader who believes it waits, and then believes the next one too. A
+ * server error is a request that may well succeed on a second try: the database was
+ * briefly unreachable, a deploy was halfway, a queue was full. So on this screen the
+ * retry is not one control among several, it is the most important thing on the page,
+ * and it goes first, above the links and above the sentence that names the failure.
+ * A design system that treated the two as one item, with a `retry` prop on the shared
+ * screen and a flag deciding whether to draw it, would be wrong twice: it would teach
+ * a 404 reader to press a button that cannot work, and it would teach an error
+ * reader that the product agrees with them. Two screens with one shape between them
+ * is the honest arrangement, and the cost is that a consumer with an error boundary
+ * renders two components and holds two sets of words, which is a sentence in their
+ * own copy rather than a fork.
+ *
+ * **Everything else is deliberately identical to its sibling**, and the shape of
+ * that sameness is the argument. The code is the `h1` and the headline is one step
+ * below it, for the reason `NotFoundPage` gives: the code is the one string on the
+ * screen that is the same for every failure of its kind, so it is what anything
+ * reading the outline indexes. The code is set in the mono face because it is a
+ * machine value and that is the face this package annotates machine values with. The
+ * links are native anchors with real destinations, for the reason its sibling gives
+ * and for the same doubled reason: a reader who has just followed one link to a
+ * failure is the reader on this site who most wants to see where the next one goes.
+ *
+ * **`retry` is a slot and that is what keeps this screen a server Component, and the
+ * argument is about the boundary rather than about the control.** The rejected shape
+ * was `retry: { label, onRetry }`: a handler is a function, a function is a piece of
+ * state, and state is a client module, so that shape would have put the entire
+ * failure screen, including every link and the code, on the client because one button
+ * wanted an `onClick`. Passing the control in as a node inverts it: the caller writes
+ * their own button in their own client component, this Page renders the node, and a
+ * consumer whose retry is a router refresh, a mutation retry or a plain reload all
+ * pass their own thing and get it drawn first. The cost is that Prism cannot check
+ * that the slot is a control at all, and can neither label it nor disable it while a
+ * retry is in flight, so a caller whose retry needs a busy state holds that state in
+ * the component they wrote. That is the right home for it: the in-flight state is a
+ * fact about the consumer's request and not about a screen.
+ *
+ * **The reference is a `dl`, and the label is a prop, because the word is the
+ * consumer's.** "Reference", "Incident" and "Case" are three words for three
+ * products and a reader has to be able to quote the word their support process asks
+ * for. The value itself is a machine string a reader copies rather than reads, so it
+ * is drawn in the mono face, and the pair is a definition list so a screen reader
+ * announces the label with the value rather than reading a bare string.
+ *
+ * The Page carries no `noindex` and no `robots` directive, for the reason its
+ * sibling gives: what a failure response is indexed as is the consumer's server's
+ * decision, and a component that declared it would be making a claim about a
+ * deployment it cannot see.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports no
+ * router, so a consumer renders it from whichever route their framework names for
+ * the status, and nothing on the screen costs client JavaScript until the caller's
+ * own retry control does.
+ */
+export declare function ErrorPage({ code, title, description, retry, links, linksLabel, reference, referenceLabel, children, headingLevel, className, }: ErrorPageProps): import("react").JSX.Element;
+export default ErrorPage;
+//# sourceMappingURL=index.d.ts.map

package/dist/pages/error-page/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/error-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAItG;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,KAAK,eAAe,GAAG;IACrB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IAC/B;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAC1C,CACI;IACE;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB,GACD;IACE,mCAAmC;IACnC,SAAS,CAAC,EAAE,KAAK,CAAA;IACjB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,KAAK,CAAA;CACvB,CACJ,CAAA;AAqBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,YAAmB,EACnB,SAAS,GACV,EAAE,cAAc,+BAqEhB;AAED,eAAe,SAAS,CAAA"}

package/dist/pages/error-page/index.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Prose } from '../../components/ui/prose.js';
+import { Section, childLevel, headingSizeClass } from '../../components/ui/section.js';
+import { Heading, Text } from '../../components/ui/typography.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The one check the union cannot make, run before anything is drawn.
+ *
+ * It is here for the JavaScript caller and for a value that came out of a database
+ * with the type's guarantee already gone, for the reason `Help01`, `Team01` and
+ * `Onboarding01` each keep their own: a defect that is invisible in a screenshot is
+ * not a defect a design system can afford to ship quietly.
+ */
+function assertReference(reference, referenceLabel) {
+    if (reference === undefined)
+        return;
+    if (referenceLabel === undefined || referenceLabel.trim() === '') {
+        throw new Error('ErrorPage: a reference is shown with no referenceLabel, so the value would sit on the page with nothing ' +
+            'naming it and a reader would have no way to know what it is for. Pass the word your support process ' +
+            'asks readers to quote, or drop the reference.');
+    }
+}
+/**
+ * A complete failure screen: the code, what happened, the retry, and the ways out.
+ *
+ * **This is the third of the three Pages that `DESIGN.md` records under Known Open
+ * Items as deferred to v1.1**, so it discharges that row rather than adding to the
+ * tail. The other two are `PricingPage` and `OnboardingPage`.
+ *
+ * **It is the sibling of `NotFoundPage` and the two fail for opposite reasons, which
+ * is the reason they are two items rather than one with a prop.** A not-found is a
+ * request that will never succeed: the address is wrong, the page was never there,
+ * and no amount of asking again produces it, so a retry on a 404 is a lie told by a
+ * button, and a reader who believes it waits, and then believes the next one too. A
+ * server error is a request that may well succeed on a second try: the database was
+ * briefly unreachable, a deploy was halfway, a queue was full. So on this screen the
+ * retry is not one control among several, it is the most important thing on the page,
+ * and it goes first, above the links and above the sentence that names the failure.
+ * A design system that treated the two as one item, with a `retry` prop on the shared
+ * screen and a flag deciding whether to draw it, would be wrong twice: it would teach
+ * a 404 reader to press a button that cannot work, and it would teach an error
+ * reader that the product agrees with them. Two screens with one shape between them
+ * is the honest arrangement, and the cost is that a consumer with an error boundary
+ * renders two components and holds two sets of words, which is a sentence in their
+ * own copy rather than a fork.
+ *
+ * **Everything else is deliberately identical to its sibling**, and the shape of
+ * that sameness is the argument. The code is the `h1` and the headline is one step
+ * below it, for the reason `NotFoundPage` gives: the code is the one string on the
+ * screen that is the same for every failure of its kind, so it is what anything
+ * reading the outline indexes. The code is set in the mono face because it is a
+ * machine value and that is the face this package annotates machine values with. The
+ * links are native anchors with real destinations, for the reason its sibling gives
+ * and for the same doubled reason: a reader who has just followed one link to a
+ * failure is the reader on this site who most wants to see where the next one goes.
+ *
+ * **`retry` is a slot and that is what keeps this screen a server Component, and the
+ * argument is about the boundary rather than about the control.** The rejected shape
+ * was `retry: { label, onRetry }`: a handler is a function, a function is a piece of
+ * state, and state is a client module, so that shape would have put the entire
+ * failure screen, including every link and the code, on the client because one button
+ * wanted an `onClick`. Passing the control in as a node inverts it: the caller writes
+ * their own button in their own client component, this Page renders the node, and a
+ * consumer whose retry is a router refresh, a mutation retry or a plain reload all
+ * pass their own thing and get it drawn first. The cost is that Prism cannot check
+ * that the slot is a control at all, and can neither label it nor disable it while a
+ * retry is in flight, so a caller whose retry needs a busy state holds that state in
+ * the component they wrote. That is the right home for it: the in-flight state is a
+ * fact about the consumer's request and not about a screen.
+ *
+ * **The reference is a `dl`, and the label is a prop, because the word is the
+ * consumer's.** "Reference", "Incident" and "Case" are three words for three
+ * products and a reader has to be able to quote the word their support process asks
+ * for. The value itself is a machine string a reader copies rather than reads, so it
+ * is drawn in the mono face, and the pair is a definition list so a screen reader
+ * announces the label with the value rather than reading a bare string.
+ *
+ * The Page carries no `noindex` and no `robots` directive, for the reason its
+ * sibling gives: what a failure response is indexed as is the consumer's server's
+ * decision, and a component that declared it would be making a claim about a
+ * deployment it cannot see.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports no
+ * router, so a consumer renders it from whichever route their framework names for
+ * the status, and nothing on the screen costs client JavaScript until the caller's
+ * own retry control does.
+ */
+export function ErrorPage({ code, title, description, retry, links, linksLabel, reference, referenceLabel, children, headingLevel = 'h1', className, }) {
+    assertReference(reference, referenceLabel);
+    /*
+      The headline sits one step below the code, which is the same derivation every
+      Block uses and the reason a hardcoded `h2` would be right exactly once. The
+      size is asked of the same table rather than passed to `Heading`'s `size`, which
+      is a step of the scale and not a rung of the ladder, so the code and the
+      headline were drawn at fixed sizes that the ladder's ceiling has since left
+      behind.
+    */
+    const TitleHeading = childLevel(headingLevel);
+    return (_jsx(Section, { "data-slot": "error-page", className: cn(className), children: _jsxs("div", { "data-slot": "error-page-body", className: "flex flex-col items-start gap-6", children: [_jsx(Heading, { as: headingLevel, className: cn('text-muted-foreground font-mono', headingSizeClass(headingLevel)), children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: TitleHeading, className: headingSizeClass(TitleHeading), children: title }), description ? _jsx(Text, { size: "lg", children: description }) : null] }), retry === undefined ? null : (_jsx("div", { "data-slot": "error-page-retry", children: retry })), links.length > 0 ? (_jsx("nav", { "aria-label": linksLabel, className: "flex flex-wrap items-center gap-3", children: links.map((link, index) => (_jsx(CtaLink, { href: link.href, newTab: link.newTab, variant: index === 0 ? 'default' : 'outline', children: link.label }, link.href))) })) : null, reference === undefined ? null : (_jsxs("dl", { "data-slot": "error-page-reference", className: "flex flex-col items-start gap-1", children: [_jsx("dt", { className: "text-muted-foreground text-xs", children: referenceLabel }), _jsx("dd", { className: "font-mono text-sm", children: reference })] })), children ? _jsx(Prose, { className: "mt-2", children: children }) : null] }) }));
+}
+export default ErrorPage;