@nanisoft/prism-ui 0.13.0 → 0.15.0

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

@@ -0,0 +1,194 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One legal document: what it is called, where it lives, and optionally the line
+ * a reader needs to decide whether to open it.
+ *
+ * `selected` is the caller's decision and not a state this Page infers. A Page
+ * cannot know which document its `body` holds, because the body is an opaque node
+ * the caller composed, so the caller marks the one that is showing. The Page draws
+ * the mark and refuses to derive it, and the reason is the same one
+ * `Team01` gives for `highlight`: a border or a weight that follows a position
+ * moves to a different document after a reorder, and a mark that says "you are
+ * here" is a claim about where the reader is.
+ */
+export type LegalPageDocument = {
+    /** A stable key for the row, and not the document's title. */
+    id: string;
+    /** The document's own name, as the document is titled. */
+    title: string;
+    /** Where the document lives on its own route. Omit it for the one being shown here. */
+    href?: string;
+    /** The line under the name, for a reader choosing between six documents. */
+    summary?: ReactNode;
+    /**
+     * Marks this document as the one in the body.
+     *
+     * At most one should be marked. Two marked documents say the reader is in two
+     * places, which is the one state `aria-current` cannot represent.
+     */
+    selected?: boolean;
+};
+/**
+ * The props a LegalPage takes.
+ *
+ * Every string is a prop and the Page ships none. A legal screen is the screen
+ * where a sentence is a promise, and this package is not entitled to write one: a
+ * Page that hardcoded a "last updated" line or a list of document names would put
+ * one company's legal position into every product that installs it, and a legal
+ * page is the last page on a site where a wrong sentence is a real problem.
+ */
+export type LegalPageProps = {
+    /**
+     * The page's heading.
+     *
+     * Required, and the Page draws it itself. A legal screen whose heading were
+     * inside the body would lose its `h1` in every state where the body is not
+     * passed, and a route whose heading is a sentence in the middle of a document is
+     * a route a search engine and a screen reader both handle badly.
+     */
+    title: ReactNode;
+    /**
+     * When the selected document last changed, already written the way a reader
+     * should see it.
+     *
+     * A string, because Prism formats no date and a `Date` here would push the
+     * locale and the calendar onto every consumer. A bare date under a page heading
+     * reads as the date the page was published, which is a different fact, so it is
+     * never drawn without `updatedLabel`.
+     */
+    updatedAt?: string;
+    /**
+     * The words that say what the date is.
+     *
+     * Required whenever `updatedAt` is, and enforced rather than documented: a bare
+     * date under a legal heading is read as the date the document was published
+     * rather than the date it was last changed, and those two are the pair a reader
+     * is checking.
+     */
+    updatedLabel?: string;
+    /**
+     * The documents, in the order a reader should meet them.
+     *
+     * Order is the caller's because it is a claim about which document the reader
+     * is most likely to want, and this Page does not reorder a legal set.
+     */
+    documents: readonly LegalPageDocument[];
+    /**
+     * The accessible name of the table of documents.
+     *
+     * Required, because the table is a navigation landmark and a landmark with no
+     * name is announced as "navigation", which on a site with a header above it is
+     * two regions called the same thing. The words are the caller's: "Legal
+     * documents" and "Policies and terms" are two filings and only the site knows
+     * which one it has.
+     */
+    documentsLabel: string;
+    /**
+     * The selected document's body, at the reading measure.
+     *
+     * Required, and an opaque node on purpose. See the Page's JSDoc for why this
+     * Page does not parse it and what the cost of that decision is.
+     */
+    body: ReactNode;
+    /**
+     * The accessible name of the region the body sits in.
+     *
+     * Optional, and the reason it is optional is the element rather than the
+     * prop: a `<section>` with no accessible name is not a landmark at all, so
+     * passing this turns the band into a named region and omitting it leaves it as
+     * a plain division of the page. A caller with one document on the route has
+     * nothing to name and nothing is lost.
+     */
+    bodyLabel?: string;
+    /**
+     * A slot for what comes after the document: a related set, a contact address, a
+     * second form.
+     *
+     * A slot rather than a prop because everything that could go here is a Block, and
+     * a Page that took a Block per prop would be a Page whose interface lists the
+     * whole catalogue.
+     */
+    footer?: ReactNode;
+    /**
+     * The heading level for the page's own heading, and one level deeper for the
+     * document's own headings, which the caller writes inside `body`.
+     *
+     * Defaults to `h1`, because a page owns the top of the document outline.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A complete legal screen: what this set of documents is, which one is selected,
+ * and that one at the reading measure.
+ *
+ * **The decision this Page makes is that it does not own the text and does not
+ * parse it, and the decision is the reason the screen exists at all.** A legal
+ * document is prose a lawyer wrote, it has a structure a design system knows
+ * nothing about, and a Page that imposed a section grammar on it would be
+ * rewriting the document it exists to publish. The rejected alternatives are both
+ * reasonable-looking and both refusals. A `sections` prop of typed blocks would
+ * have made a legal document a `ContentGrid01` entry per clause, which means this
+ * package would decide what a clause is and what an amendment is, and a consumer's
+ * counsel would then be reviewing a layout rather than reading their own words. A
+ * Markdown string with `dangerouslySetInnerHTML` would have been worse and quieter:
+ * a legal document is the one place on a site where a rendering bug is a
+ * compliance problem rather than a visual one. So `body` is a node, authored
+ * wherever it is authored, and Prism supplies the measure, the rhythm and the
+ * block treatments and nothing else. The cost is real and it is the honest
+ * counterweight: Prism cannot check that a consumer's document has a version in
+ * it, cannot find the headings, and cannot put a table of contents in step with
+ * the text, so a consumer who needs a synced contents list builds it themselves.
+  *
+ * **The document list is a `nav` of the caller's own rows and not a Block, and the
+ * reason is the current item.** A legal screen has to mark the document in the
+ * body, because a reader who has lost their place in a set of six is the whole
+ * problem this screen exists to solve, and that mark is `aria-current="page"`
+ * because a current item is a position and not a hue. `ContentGrid01` is the
+ * nearest Block and it is the wrong one twice over: it is a grid of dated entries
+ * and a legal document has no date, and it carries no current mark, so composing
+ * it would have meant either losing the position or reaching around it with a
+ * colour. The Page draws the list itself, as a `nav` with the caller's name on it,
+ * and the only Prism-owned thing in it is the focus behaviour every anchor in this
+ * package already has.
+ *
+ * **The selected item is marked three ways, and only one of them is a colour.** The
+ * `aria-current` is what a screen reader announces. The weight is what a reader
+ * scanning the left edge sees. The colour is there and it is the weakest of the
+ * three, which is the whole doctrine: a design system that marked the current item
+ * in the accent hue alone would be unreadable for a reader who cannot separate
+ * that hue from the page ground, and every rule in this package that draws a
+ * current item draws it the same way. The mark is also never given a hover state
+ * that looks like it, because a row that changes colour under the pointer is a row
+ * that lies about where the reader is. The surface moves on hover; the position
+ * does not.
+ *
+ * **The date needs its words, and the Page throws without them.** A bare date
+ * under a legal heading is read as the date the page was published, and a
+ * reader checking a document's currency is checking the difference between the two.
+ * So `updatedAt` is never drawn on its own: the caller's `updatedLabel` says what
+ * the date is, and the check runs before anything is drawn, because a page that
+ * rendered the date anyway would look correct in a screenshot and be wrong on the
+ * page.
+ *
+ * **The body is a `Prose`, so the measure and the rhythm are tokens rather than a
+ * guess.** A legal document is the longest run of prose on almost every site, and
+ * the alternative was a `max-w-*` utility written in this file, which would have
+ * been a second source of truth for the measure and a number that goes stale when
+ * the token changes. The cost of handing the measure to `Prose` is that the caller
+ * cannot put a table or a wide figure beside the text, and the answer is that
+ * `className` is layout only and a legal document that needs a full-bleed
+ * attachment is a page the consumer composes themselves.
+ *
+ * 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 a legal document and hands it the body their own content pipeline produced.
+ */
+export declare function LegalPage({ title, updatedAt, updatedLabel, documents, documentsLabel, body, bodyLabel, footer, headingLevel, className, }: LegalPageProps): import("react").JSX.Element;
+export default LegalPage;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/legal-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIxF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAA;IACV,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAA;IACb,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACvC;;;;;;;;OAQG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,IAAI,EAAE,SAAS,CAAA;IACf;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,SAAS,EACT,YAAY,EACZ,SAAS,EACT,cAAc,EACd,IAAI,EACJ,SAAS,EACT,MAAM,EACN,YAAmB,EACnB,SAAS,GACV,EAAE,cAAc,+BAgFhB;AAuBD,eAAe,SAAS,CAAA"}

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

@@ -0,0 +1,99 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Prose } from '../../components/ui/prose.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Text } from '../../components/ui/typography.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A complete legal screen: what this set of documents is, which one is selected,
+ * and that one at the reading measure.
+ *
+ * **The decision this Page makes is that it does not own the text and does not
+ * parse it, and the decision is the reason the screen exists at all.** A legal
+ * document is prose a lawyer wrote, it has a structure a design system knows
+ * nothing about, and a Page that imposed a section grammar on it would be
+ * rewriting the document it exists to publish. The rejected alternatives are both
+ * reasonable-looking and both refusals. A `sections` prop of typed blocks would
+ * have made a legal document a `ContentGrid01` entry per clause, which means this
+ * package would decide what a clause is and what an amendment is, and a consumer's
+ * counsel would then be reviewing a layout rather than reading their own words. A
+ * Markdown string with `dangerouslySetInnerHTML` would have been worse and quieter:
+ * a legal document is the one place on a site where a rendering bug is a
+ * compliance problem rather than a visual one. So `body` is a node, authored
+ * wherever it is authored, and Prism supplies the measure, the rhythm and the
+ * block treatments and nothing else. The cost is real and it is the honest
+ * counterweight: Prism cannot check that a consumer's document has a version in
+ * it, cannot find the headings, and cannot put a table of contents in step with
+ * the text, so a consumer who needs a synced contents list builds it themselves.
+  *
+ * **The document list is a `nav` of the caller's own rows and not a Block, and the
+ * reason is the current item.** A legal screen has to mark the document in the
+ * body, because a reader who has lost their place in a set of six is the whole
+ * problem this screen exists to solve, and that mark is `aria-current="page"`
+ * because a current item is a position and not a hue. `ContentGrid01` is the
+ * nearest Block and it is the wrong one twice over: it is a grid of dated entries
+ * and a legal document has no date, and it carries no current mark, so composing
+ * it would have meant either losing the position or reaching around it with a
+ * colour. The Page draws the list itself, as a `nav` with the caller's name on it,
+ * and the only Prism-owned thing in it is the focus behaviour every anchor in this
+ * package already has.
+ *
+ * **The selected item is marked three ways, and only one of them is a colour.** The
+ * `aria-current` is what a screen reader announces. The weight is what a reader
+ * scanning the left edge sees. The colour is there and it is the weakest of the
+ * three, which is the whole doctrine: a design system that marked the current item
+ * in the accent hue alone would be unreadable for a reader who cannot separate
+ * that hue from the page ground, and every rule in this package that draws a
+ * current item draws it the same way. The mark is also never given a hover state
+ * that looks like it, because a row that changes colour under the pointer is a row
+ * that lies about where the reader is. The surface moves on hover; the position
+ * does not.
+ *
+ * **The date needs its words, and the Page throws without them.** A bare date
+ * under a legal heading is read as the date the page was published, and a
+ * reader checking a document's currency is checking the difference between the two.
+ * So `updatedAt` is never drawn on its own: the caller's `updatedLabel` says what
+ * the date is, and the check runs before anything is drawn, because a page that
+ * rendered the date anyway would look correct in a screenshot and be wrong on the
+ * page.
+ *
+ * **The body is a `Prose`, so the measure and the rhythm are tokens rather than a
+ * guess.** A legal document is the longest run of prose on almost every site, and
+ * the alternative was a `max-w-*` utility written in this file, which would have
+ * been a second source of truth for the measure and a number that goes stale when
+ * the token changes. The cost of handing the measure to `Prose` is that the caller
+ * cannot put a table or a wide figure beside the text, and the answer is that
+ * `className` is layout only and a legal document that needs a full-bleed
+ * attachment is a page the consumer composes themselves.
+ *
+ * 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 a legal document and hands it the body their own content pipeline produced.
+ */
+export function LegalPage({ title, updatedAt, updatedLabel, documents, documentsLabel, body, bodyLabel, footer, headingLevel = 'h1', className, }) {
+    assertUpdatedLabel(updatedAt, updatedLabel);
+    return (_jsxs("div", { "data-slot": "legal-page", className: cn(className), children: [_jsx(Section, { "data-slot": "legal-page-heading", children: _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", title: title }), updatedAt === undefined ? null : (_jsxs(Text, { "data-slot": "legal-page-updated", size: "sm", tone: "muted", children: [_jsx("span", { children: updatedLabel }), " ", _jsx("span", { children: updatedAt })] }))] }) }), _jsx(Section, { "data-slot": "legal-page-documents", children: _jsx("nav", { "aria-label": documentsLabel, "data-slot": "legal-page-documents-nav", children: _jsx("ul", { className: "flex flex-col gap-1", children: documents.map((document) => {
+                            const current = document.selected === true;
+                            const row = (_jsxs(_Fragment, { children: [_jsx("span", { "data-slot": "legal-page-document-title", className: cn('text-sm', current ? 'text-foreground font-semibold' : 'text-muted-foreground'), children: document.title }), document.summary === undefined ? null : (_jsx("span", { "data-slot": "legal-page-document-summary", className: "text-muted-foreground text-pretty text-sm", children: document.summary }))] }));
+                            return (_jsx("li", { "data-slot": "legal-page-document", "data-current": current ? 'true' : undefined, children: document.href === undefined ? (_jsx("span", { "data-slot": "legal-page-document-link", "aria-current": current ? 'page' : undefined, className: "flex flex-col gap-1 rounded-sm", children: row })) : (_jsx("a", { "data-slot": "legal-page-document-link", href: document.href, "aria-current": current ? 'page' : undefined, className: "hover:bg-accent/50 flex flex-col gap-1 rounded-sm transition-colors duration-fast ease-out", children: row })) }, document.id));
+                        }) }) }) }), _jsx(Section, { "data-slot": "legal-page-body", "aria-label": bodyLabel, children: _jsx(Prose, { size: "lg", children: body }) }), footer === undefined ? null : _jsx(Section, { "data-slot": "legal-page-footer", children: footer })] }));
+}
+/**
+ * The date's own check, run before anything is drawn.
+ *
+ * A bare date under a legal heading is read as the date the page was published,
+ * and a reader checking a document's currency is checking the difference between
+ * that and the date it last changed. The cost of throwing rather than degrading is
+ * that a caller with a data file that has drifted finds out at render rather than
+ * in review, which is the trade every refusal in this package makes.
+ */
+function assertUpdatedLabel(updatedAt, updatedLabel) {
+    if (updatedAt === undefined)
+        return;
+    if (updatedLabel !== undefined && updatedLabel.trim() !== '')
+        return;
+    throw new Error('LegalPage: updatedAt was passed with no updatedLabel, so the date would be drawn on its own under the page ' +
+        'heading, where a reader reads it as the date the page was published rather than the date the document last ' +
+        'changed. Those are two different facts and the second is the one a reader checking a document is here for. ' +
+        'Pass the words that say what the date is, or drop the date.');
+}
+export default LegalPage;

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

@@ -0,0 +1,199 @@
+import type { ReactNode } from 'react';
+import type { HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One thing the reader has to do, or has done, or is stuck on.
+ *
+ * The same seven fields as `Onboarding01`'s own step, declared here rather than
+ * imported so that this Page's published interface does not change when the Block
+ * gains a field, and so a consumer reading the corpus sees one vocabulary for the
+ * screen rather than two.
+ *
+ * `stateLabel` and `hrefLabel` are optional in the type and required in practice:
+ * `Onboarding01` refuses both at run time, by the same argument it makes for every
+ * mark and every link in this package. A mark with no sentence beside it is a shape
+ * a reader can only see, and a link announced by its address is punctuation rather
+ * than a name.
+ */
+export type OnboardingPageStep = {
+    /** A stable key for the step, and the key a `stateLabel` and an action are found by. */
+    id: string;
+    /** What the step is, in the words a reader would use in conversation. */
+    name: string;
+    /** A line or two about what this step involves, for a reader who has arrived at it. */
+    description?: ReactNode;
+    /**
+     * Where the step stands.
+     *
+     * `blocked` is a fact about this run rather than a position in the order, and it
+     * is here because a checklist that can only say done and not done and next will
+     * read as broken to a reader who is genuinely stuck.
+     */
+    state: 'done' | 'current' | 'upcoming' | 'blocked';
+    /** The words for that state, in the product's own voice. Required whenever `state` is set. */
+    stateLabel?: string;
+    /** The control that acts on this step, beside it: a connect, a retry, a skip. */
+    action?: ReactNode;
+    /** Where the step goes, rendered as a native anchor so the destination is real. */
+    href?: string;
+    /** The words on that link. Required whenever `href` is. */
+    hrefLabel?: string;
+};
+/**
+ * The props an OnboardingPage takes.
+ *
+ * Every string and every count is a prop and the Page ships none of them. The one
+ * place that is hardest is the progress sentence, which is a function rather than a
+ * template, because it has a plural and changes shape past one and every language
+ * words it differently.
+ */
+export type OnboardingPageProps = {
+    /**
+     * Optional label above the page's own heading. See the No-Default-Eyebrow Rule.
+     *
+     * A `string` and not a node, because the checklist's `eyebrow` is a `string`: the
+     * label is one short line that the Block sets in small caps, and a node there
+     * would be markup inside a run of text that is already an eyebrow.
+     */
+    eyebrow?: string;
+    /**
+     * The page's heading, and this screen's `h1`.
+     *
+     * Required, and it is handed to the checklist rather than drawn above it. See
+     * the Page's JSDoc for why that is the right home for the `h1` rather than a
+     * title the Page draws separately.
+     */
+    title: ReactNode;
+    /** One or two sentences under the heading, for the part the heading cannot carry. */
+    description?: ReactNode;
+    /**
+     * The steps, in the order the reader should do them.
+     *
+     * `readonly` because the normal way a consumer writes a step list is an `as
+     * const` fixture, and a prop typed as a mutable array rejects that fixture at the
+     * moment it is most useful. The list is handed to `Onboarding01` as a fresh array
+     * because that Block declares a mutable one.
+     */
+    steps: readonly OnboardingPageStep[];
+    /**
+     * The sentence the progress figure is named by, given the two counts.
+     *
+     * Required, and a function rather than a string for the reason `Onboarding01`
+     * gives: the phrase has a plural, it changes shape past one, and every language
+     * words it differently. A Page that composed it would compose the English one and
+     * ship it into every consumer's product.
+     */
+    progressLabel: (done: number, total: number) => string;
+    /**
+     * The note under the progress figure: what happens when the last step is done,
+     * what a blocked step needs, where to read more.
+     */
+    completion?: ReactNode;
+    /**
+     * What the checklist draws in place of the steps when there are none.
+     *
+     * Required, and it is `Onboarding01`'s own requirement forwarded rather than
+     * softened. A setup with no steps is either a product that has nothing to set up
+     * or a caller's query that returned nothing, and those are opposite claims: the
+     * first is good news and the second is a fault in the consumer's data, and this
+     * Page cannot tell them apart, so the sentence is the caller's.
+     */
+    empty: ReactNode;
+    /**
+     * The way out of a setup that is going wrong, beside the checklist.
+     *
+     * A `Help01` goes here and it is the reason this is a Page rather than a Block.
+     * See the JSDoc on the Page: a checklist with no escape is a dead end a reader
+     * has to close the tab to leave.
+     */
+    help?: ReactNode;
+    /**
+     * The closing band: a `Contact01`, a `Newsletter01`, or whatever else a reader
+     * who has run out of road should be given next.
+     */
+    footer?: ReactNode;
+    /**
+     * How the screen is arranged.
+     *
+     * `centred` is the default and it sets the whole screen in one reading measure,
+     * which is the screen a first run is: there is one thing to do and nothing else
+     * competing for the reader. `split` puts the checklist and the help in two
+     * columns from the large breakpoint up, which is the screen a return visit is,
+     * where the reader has done the setup once and is now reading for the answer
+     * rather than for the route. With no `help`, `split` leaves the checklist the
+     * full width of both columns, so the arrangement is total rather than conditional.
+     */
+    layout?: 'centred' | 'split';
+    /**
+     * The level of the page's own heading, which the checklist draws.
+     *
+     * Defaults to `h1`, because a Page owns the top of the document outline. A
+     * consumer embedding this screen under a heading it already owns passes one level
+     * deeper and the outline follows.
+     */
+    headingLevel?: HeadingLevel;
+    /** Layout only, exactly as on every Item. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * A complete setup screen: the heading, the checklist, and the way out of a setup
+ * that is going wrong.
+ *
+ * **This is the second 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 `ErrorPage`.
+ *
+ * **The distinction from `onboarding-01` is the whole argument for this Page
+ * existing, so it is worth being blunt about it. The Block is the checklist. This
+ * is the screen.** A checklist is a list with a figure above it, and a list is a
+ * thing a reader arrives at. A screen is a heading, a list, and a way out of the
+ * situation the list describes, and a reader who is stuck does not go looking for
+ * the checklist: they arrive at the screen, because the screen is the only address
+ * they were ever given. A reader three days into a setup with one step left open and
+ * no permission yet granted has a question, and the question is not "which step is
+ * next", it is "is this broken", and the answer to that cannot live in a list of
+ * rows. So the Page composes the checklist with a way to ask, and `help` is why it
+ * is a Page and not a Block: a checklist with no escape is a dead end a reader has
+ * to close the tab to leave, and closing the tab is the worst outcome a setup
+ * screen can have, because the reader does not come back.
+ *
+ * **The `h1` is the checklist's own section heading, and handing it over is the
+ * decision.** The rejected alternative was a title this Page drew above the
+ * checklist, and it failed twice. The first failure is duplication: the checklist
+ * opens with a heading, so a title above it is the same words twice on one screen.
+ * The second is rhythm: a Page that draws its own heading band has to decide where
+ * the content starts below it, and the answer is always a second `Section` of
+ * vertical padding between the heading and the thing the heading is about, which on
+ * a screen whose whole job is one list reads as an empty band. Passing `title` to
+ * the Block puts the page heading where the page's subject is, gives the screen
+ * exactly one `h1` without this Page having to police it, and lets `Onboarding01`
+ * hold the heading left, which is the alignment `SectionHeading` requires of
+ * anything with content under it.
+ *
+ * **`layout` is the only layout decision the Page makes, and both of its forms are
+ * the same screen read by a different reader.** `centred` puts one reading measure
+ * on the page, which is the first run, where the only question is which step comes
+ * next. `split` gives the checklist three fifths and the help two, which is the
+ * return visit, where the route is already known and the missing paragraph is not.
+ * The rejected third form was a single full-width column for both, which is `centred`
+ * and costs nothing to say, so it was not named.
+ *
+ * **The Page checks nothing, and that is a boundary rather than an omission.**
+ * `Onboarding01` already refuses a step with no `stateLabel`, a step with an `href`
+ * and no `hrefLabel`, and a rail with two current steps, and it names the step by
+ * its `id`. This Page hands the list over in the same shape, so those messages
+ * already name the key the caller passed here, and repeating them would only print
+ * the same sentence twice.
+ *
+ * **It is a client Component, and the reason is `progressLabel` rather than any
+ * state of the Page's own.** A handler is a function, a function is a piece of
+ * state, and a function cannot cross from a server Component to a client Component,
+ * so a Page that took one and rendered it into a client Block would have to be a
+ * client module itself. The rejected alternative was a formatted count, which is a
+ * Page that ships an English phrase and its plural rule into every consumer's
+ * product. The cost is that this screen's data is serialised across the boundary to
+ * reach a Block two elements down, and the answer is that a setup screen is a client
+ * screen anyway: the consumer's own retry handler is a client handler.
+ */
+export declare function OnboardingPage({ eyebrow, title, description, steps, progressLabel, completion, empty, help, footer, layout, headingLevel, className, }: OnboardingPageProps): import("react").JSX.Element;
+export default OnboardingPage;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/onboarding-page/index.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAG/D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAA;IACV,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,uFAAuF;IACvF,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAA;IAClD,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iFAAiF;IACjF,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,qFAAqF;IACrF,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACpC;;;;;;;OAOG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtD;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,IAAI,EACJ,MAAM,EACN,MAAkB,EAClB,YAAmB,EACnB,SAAS,GACV,EAAE,mBAAmB,+BA+CrB;AAED,eAAe,cAAc,CAAA"}

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

@@ -0,0 +1,71 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Onboarding01 } from '../../blocks/onboarding-01/index.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A complete setup screen: the heading, the checklist, and the way out of a setup
+ * that is going wrong.
+ *
+ * **This is the second 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 `ErrorPage`.
+ *
+ * **The distinction from `onboarding-01` is the whole argument for this Page
+ * existing, so it is worth being blunt about it. The Block is the checklist. This
+ * is the screen.** A checklist is a list with a figure above it, and a list is a
+ * thing a reader arrives at. A screen is a heading, a list, and a way out of the
+ * situation the list describes, and a reader who is stuck does not go looking for
+ * the checklist: they arrive at the screen, because the screen is the only address
+ * they were ever given. A reader three days into a setup with one step left open and
+ * no permission yet granted has a question, and the question is not "which step is
+ * next", it is "is this broken", and the answer to that cannot live in a list of
+ * rows. So the Page composes the checklist with a way to ask, and `help` is why it
+ * is a Page and not a Block: a checklist with no escape is a dead end a reader has
+ * to close the tab to leave, and closing the tab is the worst outcome a setup
+ * screen can have, because the reader does not come back.
+ *
+ * **The `h1` is the checklist's own section heading, and handing it over is the
+ * decision.** The rejected alternative was a title this Page drew above the
+ * checklist, and it failed twice. The first failure is duplication: the checklist
+ * opens with a heading, so a title above it is the same words twice on one screen.
+ * The second is rhythm: a Page that draws its own heading band has to decide where
+ * the content starts below it, and the answer is always a second `Section` of
+ * vertical padding between the heading and the thing the heading is about, which on
+ * a screen whose whole job is one list reads as an empty band. Passing `title` to
+ * the Block puts the page heading where the page's subject is, gives the screen
+ * exactly one `h1` without this Page having to police it, and lets `Onboarding01`
+ * hold the heading left, which is the alignment `SectionHeading` requires of
+ * anything with content under it.
+ *
+ * **`layout` is the only layout decision the Page makes, and both of its forms are
+ * the same screen read by a different reader.** `centred` puts one reading measure
+ * on the page, which is the first run, where the only question is which step comes
+ * next. `split` gives the checklist three fifths and the help two, which is the
+ * return visit, where the route is already known and the missing paragraph is not.
+ * The rejected third form was a single full-width column for both, which is `centred`
+ * and costs nothing to say, so it was not named.
+ *
+ * **The Page checks nothing, and that is a boundary rather than an omission.**
+ * `Onboarding01` already refuses a step with no `stateLabel`, a step with an `href`
+ * and no `hrefLabel`, and a rail with two current steps, and it names the step by
+ * its `id`. This Page hands the list over in the same shape, so those messages
+ * already name the key the caller passed here, and repeating them would only print
+ * the same sentence twice.
+ *
+ * **It is a client Component, and the reason is `progressLabel` rather than any
+ * state of the Page's own.** A handler is a function, a function is a piece of
+ * state, and a function cannot cross from a server Component to a client Component,
+ * so a Page that took one and rendered it into a client Block would have to be a
+ * client module itself. The rejected alternative was a formatted count, which is a
+ * Page that ships an English phrase and its plural rule into every consumer's
+ * product. The cost is that this screen's data is serialised across the boundary to
+ * reach a Block two elements down, and the answer is that a setup screen is a client
+ * screen anyway: the consumer's own retry handler is a client handler.
+ */
+export function OnboardingPage({ eyebrow, title, description, steps, progressLabel, completion, empty, help, footer, layout = 'centred', headingLevel = 'h1', className, }) {
+    const split = layout === 'split';
+    return (_jsxs("div", { "data-slot": "onboarding-page", className: cn(className), children: [_jsxs("div", { "data-slot": "onboarding-page-body", "data-layout": layout, className: cn('w-full gap-10', split
+                    ? 'grid items-start lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)]'
+                    : 'mx-auto flex max-w-measure-narrow flex-col'), children: [_jsx("div", { "data-slot": "onboarding-page-checklist", className: cn(split && help === undefined && 'lg:col-span-2'), children: _jsx(Onboarding01, { eyebrow: eyebrow, title: title, description: description, steps: [...steps], progressLabel: progressLabel, completion: completion, empty: empty, headingLevel: headingLevel }) }), help === undefined ? null : (_jsx("div", { "data-slot": "onboarding-page-help", children: help }))] }), footer === undefined ? null : (_jsx("div", { "data-slot": "onboarding-page-footer", children: footer }))] }));
+}
+export default OnboardingPage;