@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Prose } from '../../components/ui/prose';
-import { Heading, Text } from '../../components/ui/typography';
-import { cn } from '../../lib/utils';
+import { Prose } from '../../components/ui/prose.js';
+import { Heading, Text } from '../../components/ui/typography.js';
+import { cn } from '../../lib/utils.js';
 /**
  * A documentation screen: a navigation rail, the document, a contents rail and
  * the pager to the neighbouring pages.
@@ -31,8 +31,19 @@ import { cn } from '../../lib/utils';
  * consumer sites all write `url: node.index?.url ?? ''` in their own adapter
  * today, which is the same fact spelled as an empty string, and two of the three
  * then carry a stylesheet rule that styles the resulting anchor-with-no-href
- * back into a label. Naming the case in the type makes those two rules dead
- * rather than load-bearing, and the type is the only place that had to change.
+ * back into a label. So the Page reads an empty or blank `href` as the absence on
+ * this arm, and the two stylesheet rules are dead rather than load-bearing. It
+ * takes one function rather than only a type, because an optional field the
+ * caller spells as `''` is not an optional field the type can see.
+ *
+ * **An entry with no words is a label too, and a page with no address is
+ * refused.** Both halves of "what makes this a destination" are answered in one
+ * function, `destinationOf`, and both the rail and the pager ask it. An entry
+ * that is a label on the rail is not a page the pager reaches either, so one
+ * malformed row cannot become two surfaces' worth of broken link. A page whose
+ * address is empty or blank has no such reading: there is nothing to render in
+ * place of the link, so the Page throws, naming the entry, before any of the tree
+ * renders.
  *
  * **The pager is derived from the navigation rather than passed.** The rail
  * already knows every page and the order a reader meets them in, and deriving the
@@ -56,6 +67,14 @@ import { cn } from '../../lib/utils';
  * twenty-seven-page tree are both a full screen and neither is a page-long
  * sidebar.
  *
+ * **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 with both rails hidden, which is the arrangement
+ * a phone gets.
+ *
  * 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
  * it the page tree, the outline and the current address. A Block would be the
@@ -68,16 +87,89 @@ import { cn } from '../../lib/utils';
  * and hands it the document their pipeline produced.
  */
 export function DocsShell({ title, description, nav, toc, currentHref, navLabel, tocLabel, pagerLabel, pagerLabels, header, footer, className, children, }) {
+    readTree(nav, 'nav');
+    readTree(toc, 'toc');
     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] }));
+    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 ? (_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] }));
+}
+/* ------------------------------------------------------------------ *
+ * The tree
+ * ------------------------------------------------------------------ */
+/**
+ * The address an entry has, or `undefined` when it has none.
+ *
+ * Blank counts as none, which is not pedantry. All three consumer adapters write
+ * `url: node.index?.url ?? ''` for a folder holding no index, so the empty string
+ * is how they spell "this group is not a route", and a guard that read only
+ * `=== undefined` let that same spelling through to the renderer on the arm where
+ * it means something else entirely.
+ */
+function addressOf(href) {
+    return href !== undefined && href.trim() !== '' ? href : undefined;
+}
+/**
+ * The address an entry is reachable at, or `undefined` when it is not a
+ * destination at all.
+ *
+ * An entry is a destination only when it has an address AND words, and both
+ * halves live here so that one rule answers for both surfaces that read a tree.
+ * The rail asks it to decide between an anchor and a label; the pager asks it to
+ * decide between a neighbour and nothing. Two places deciding that separately is
+ * how one malformed row becomes a nameless anchor in the rail and a nameless
+ * `Next` link under it.
+ */
+function destinationOf(entry) {
+    return entry.title === '' ? undefined : addressOf(entry.href);
+}
+/**
+ * Reads a tree before any of it renders, and refuses the one shape it cannot
+ * render honestly.
+ *
+ * A page entry whose address is empty or blank is an entry whose whole content is
+ * a route the consumer does not have. There is no honest rendering of it: a label
+ * in its place would hide a page the tree is missing rather than report it, and an
+ * anchor would be a control a reader can focus and cannot operate. So the Page
+ * throws, naming the entry, which is the opposite of copy and reaches a developer
+ * rather than a reader.
+ *
+ * Two things are deliberate here. The pass is in the component and not in a
+ * renderer, so it runs once for both trees and cannot be reached only on the path
+ * that happens to draw the bad row. And a GROUP is not refused: no address is a
+ * documented state for a group and the empty string is how all three consumers
+ * already spell it, so it renders as a label. Only the arm where an address is
+ * the entire entry is a fault.
+ */
+function readTree(entries, source) {
+    for (const entry of entries ?? []) {
+        if (entry.type === 'divider')
+            continue;
+        if (entry.type === 'group') {
+            readTree(entry.items, source);
+            continue;
+        }
+        if (addressOf(entry.href) === undefined) {
+            throw new Error(`docs-shell: a page entry in the ${source} has no address, and an anchor with no address is a ` +
+                'control a reader can focus and cannot follow. Give the entry the address its page is read at, or ' +
+                `remove it from the tree. Its title is ${JSON.stringify(entry.title)}.`);
+        }
+    }
 }
 /* ------------------------------------------------------------------ *
  * The rail
@@ -111,12 +203,17 @@ function NavNode({ entry, currentHref, depth, }) {
         // above the hairline rather than a word a reader has to interpret.
         return (_jsx("li", { "data-slot": "docs-nav-divider", className: "border-border mt-2 border-t pt-2 first:mt-0 first:border-t-0 first:pt-0", children: entry.title ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: entry.title })) : null }));
     }
+    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: [entry.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: entry.href, "aria-current": currentHref === entry.href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(entry.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] }) }));
+        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] }) }));
     }
-    return (_jsx("li", { "data-slot": "docs-nav-page", children: _jsx("a", { "data-slot": "docs-nav-link", href: entry.href, "aria-current": currentHref === entry.href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === entry.href
+    // 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
                 ? '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.
@@ -126,18 +223,23 @@ function NavNode({ entry, currentHref, depth, }) {
  * contributes its children and nothing else, which is the second thing that
  * makes an absent `href` a label rather than a route: there is no page there for
  * 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.
  */
 function flatten(entries, into = []) {
     for (const entry of entries) {
-        if (entry.type === 'page') {
-            into.push({ title: entry.title, href: entry.href });
+        if (entry.type === 'divider')
             continue;
-        }
-        if (entry.type === 'group') {
-            if (entry.href !== undefined)
-                into.push({ title: entry.title, href: entry.href });
+        const href = destinationOf(entry);
+        if (href !== undefined)
+            into.push({ title: entry.title, href });
+        if (entry.type === 'group')
             flatten(entry.items, into);
-        }
     }
     return into;
 }
@@ -182,9 +284,15 @@ function under(href, currentHref) {
  * A group with a route answers for that route and everything under it. A group
  * without one has no route to answer with, so it asks its children, which is the
  * only way a label can still show a reader that they are inside it.
+ *
+ * The group's own address is read through `addressOf`, like every other read of
+ * it. A group whose `href` is the empty string is a label, and a blank string
+ * handed to `under` as though it were a route matches every absolute address on
+ * the site, which is every label-only section claiming to be the current one at
+ * once.
  */
 function containsHref(group, currentHref) {
-    if (under(group.href, currentHref))
+    if (under(addressOf(group.href), currentHref))
         return true;
     return group.items.some((entry) => {
         if (entry.type === 'page')

package/dist/pages/docs-shell/index.d.ts

@@ -1,3 +1,3 @@
-export { DocsShell, default } from './docs-shell';
-export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell';
+export { DocsShell, default } from './docs-shell.js';
+export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-export { DocsShell, default } from './docs-shell';
+export { DocsShell, default } from './docs-shell.js';

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,EAAuB,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIpF;;;;;;;;;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,+BAkEhB;AAED,eAAe,SAAS,CAAA"}

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

@@ -0,0 +1,98 @@
+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 } 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.
+    */
+    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, size: "4xl", className: "text-muted-foreground font-mono", children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: TitleHeading, size: "2xl", 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;

package/dist/pages/index.d.ts

@@ -11,18 +11,28 @@
  * A published name cannot be cheaply changed and there is no redirect lane for
  * item routes.
  */
-export { MarketingPage } from './marketing-page';
-export type { MarketingPageProps } from './marketing-page';
-export { DashboardPage } from './dashboard-page';
-export type { DashboardPageProps } from './dashboard-page';
-export { SettingsPage } from './settings-page';
-export type { SettingsPageProps, SettingsPageTab } from './settings-page';
-export { AuthPage } from './auth-page';
-export type { AuthPageProps, AuthPageAside } from './auth-page';
-export { NotFoundPage } from './not-found-page';
-export type { NotFoundPageProps, NotFoundLink } from './not-found-page';
-export { BlogPostPage } from './blog-post-page';
-export type { BlogPostPageProps, BlogPostTag, BlogPostNeighbour, BlogPostTrailLabels } from './blog-post-page';
-export { DocsShell } from './docs-shell';
-export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell';
+export { MarketingPage } from './marketing-page/index.js';
+export type { MarketingPageProps } from './marketing-page/index.js';
+export { DashboardPage } from './dashboard-page/index.js';
+export type { DashboardPageProps } from './dashboard-page/index.js';
+export { SettingsPage } from './settings-page/index.js';
+export type { SettingsPageProps, SettingsPageTab } from './settings-page/index.js';
+export { AuthPage } from './auth-page/index.js';
+export type { AuthPageProps, AuthPageAside } from './auth-page/index.js';
+export { NotFoundPage } from './not-found-page/index.js';
+export type { NotFoundPageProps, NotFoundLink } from './not-found-page/index.js';
+export { BlogPostPage } from './blog-post-page/index.js';
+export type { BlogPostPageProps, BlogPostTag, BlogPostNeighbour, BlogPostTrailLabels } from './blog-post-page/index.js';
+export { DocsShell } from './docs-shell/index.js';
+export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell/index.js';
+export { AboutPage } from './about-page/index.js';
+export { CareersPage } from './careers-page/index.js';
+export { ChangelogPage } from './changelog-page/index.js';
+export { ContactPage } from './contact-page/index.js';
+export { ErrorPage } from './error-page/index.js';
+export { LegalPage } from './legal-page/index.js';
+export { OnboardingPage } from './onboarding-page/index.js';
+export { PricingPage } from './pricing-page/index.js';
+export { SearchPage } from './search-page/index.js';
+export { StatusPage } from './status-page/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/pages/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC9G,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC9G,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,cAAc,CAAA;AAOrB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA"}

package/dist/pages/index.js

@@ -11,10 +11,24 @@
  * A published name cannot be cheaply changed and there is no redirect lane for
  * item routes.
  */
-export { MarketingPage } from './marketing-page';
-export { DashboardPage } from './dashboard-page';
-export { SettingsPage } from './settings-page';
-export { AuthPage } from './auth-page';
-export { NotFoundPage } from './not-found-page';
-export { BlogPostPage } from './blog-post-page';
-export { DocsShell } from './docs-shell';
+export { MarketingPage } from './marketing-page/index.js';
+export { DashboardPage } from './dashboard-page/index.js';
+export { SettingsPage } from './settings-page/index.js';
+export { AuthPage } from './auth-page/index.js';
+export { NotFoundPage } from './not-found-page/index.js';
+export { BlogPostPage } from './blog-post-page/index.js';
+export { DocsShell } from './docs-shell/index.js';
+/*
+ * the ten screens the 2026-09 expansion added.
+ * Derived by the maintainer rather than authored: each entry is read out of the Item own
+ * index module, so an Item and its barrel line cannot come apart. */
+export { AboutPage } from './about-page/index.js';
+export { CareersPage } from './careers-page/index.js';
+export { ChangelogPage } from './changelog-page/index.js';
+export { ContactPage } from './contact-page/index.js';
+export { ErrorPage } from './error-page/index.js';
+export { LegalPage } from './legal-page/index.js';
+export { OnboardingPage } from './onboarding-page/index.js';
+export { PricingPage } from './pricing-page/index.js';
+export { SearchPage } from './search-page/index.js';
+export { StatusPage } from './status-page/index.js';