@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,255 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One change record inside a release: which kind it is, the line that says what
+ * changed, and the sentence under it.
+ *
+ * `kind` is a closed set of five and it is the taxonomy rather than a severity
+ * ladder: a record says what kind of change it is and not how bad it was, because
+ * how bad it was is a property of a reader's exposure and not of the record. The
+ * words beside the mark are the caller's, and the mark itself is the Block's.
+ */
+export type ChangelogPageRecord = {
+    /** The record's stable key within its release. */
+    id: string;
+    /** Which of the five kinds this record is. */
+    kind: 'added' | 'changed' | 'fixed' | 'removed' | 'security';
+    /** The one line that says what changed. */
+    title: string;
+    /**
+     * The detail under the line: why it changed, what it affects, what to do about
+     * it. A node, so a caller may pass a paragraph, a list of migration steps, or a
+     * code block showing the old call beside the new one.
+     */
+    body?: ReactNode;
+    /** Where the full record lives. Its presence makes the entry carry a link. */
+    href?: string;
+    /** The words on the link. Required whenever `href` is, and enforced by the Block. */
+    hrefLabel?: string;
+};
+/**
+ * One release: what it is called, when it was, one line about it, and its records.
+ *
+ * **`version` and `at` are two different facts and both are required by different
+ * readers, which is why neither is derived from the other.** A product that cuts
+ * a nightly build has a moment and no meaningful version, and a product that ships
+ * once a month has a version a reader can compare against their own lockfile and
+ * almost no use for the hour. The Page prints what it was handed and invents
+ * neither: it holds no calendar, no semver parser and no opinion about which of
+ * the two identifies a release, because every product in this repository has
+ * answered that differently and the one answer that would fit all of them is the
+ * string the caller already had.
+ */
+export type ChangelogPageRelease = {
+    /**
+     * The release's stable key, and the fragment a consumer's own changelog links
+     * to.
+     *
+     * A key and not the version, because a fragment has to be a legal anchor and
+     * `1.4.0` and `Q3 2026` are not the same shape of string. The Page puts it on
+     * the element that wraps the release's own heading, so a link to it lands on the
+     * release rather than above it.
+     */
+    id: string;
+    /** The version, or the date, or whatever identifies this group of records. */
+    version: string;
+    /** The moment, already written the way a reader should see it. */
+    at?: string;
+    /** One line about the release as a whole, for a reader deciding whether to read on. */
+    summary?: ReactNode;
+    /**
+     * The records, in the order the product published them.
+     *
+     * Order is the caller's and this Page never touches it. A changelog is a record
+     * rather than a document, and the order in a record is the order things happened
+     * in, which is a publication decision with a long tail of exceptions: a security
+     * fix belongs beside the change that made it necessary far more often than it
+     * belongs at the top of the list. Sorting by the version string would reorder
+     * `1.10.0` before `1.9.0` for every consumer whose versions happen to be
+     * strings, and sorting by the date would move a release whose records were
+     * written in a different order into one that was not.
+     */
+    entries: readonly ChangelogPageRecord[];
+};
+/**
+ * One kind the reader can ask for, and whether they have.
+ *
+ * `state` is a state and not a control: it is what the caller has decided, and the
+ * Page draws it. The control that changes it is the caller's, in `filters`,
+ * because narrowing a changelog means holding state and a server Page holds none.
+ */
+export type ChangelogPageFilter = {
+    /** A stable key for the filter. */
+    id: string;
+    /** The words on the filter, in the product's own language. */
+    label: string;
+    /** Whether the caller has this kind turned on. */
+    state: 'on' | 'off';
+};
+/**
+ * The band that asks a reader to stop reading and start receiving.
+ *
+ * `cta` is a node rather than a label and a destination because the thing a reader
+ * subscribes to is a control: an email field, a feed link, a form the consumer
+ * wrote. Prism supplies the heading and the measure and the caller supplies the
+ * control, which is the same seam every other slot in this package is.
+ */
+export type ChangelogPageSubscribe = {
+    /** The band's heading. */
+    title: ReactNode;
+    /** One or two sentences under the heading. */
+    description?: ReactNode;
+    /** The control that subscribes the reader, composed by the caller. */
+    cta: ReactNode;
+};
+/**
+ * The props a ChangelogPage takes.
+ *
+ * Every string, every version and every record is a prop and the Page ships none
+ * of them. A changelog is the highest risk of hardcoded copy in this package,
+ * because the vocabulary of change is the most tempting kind of copy to write: five
+ * words, a fixed order, and every product apparently needs them. Five words in one
+ * language is five words every consumer of this Page inherits, and the corpus
+ * publishes them as this design system's own.
+ */
+export type ChangelogPageProps = {
+    /** Optional label above the page's own heading. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /**
+     * The page's heading.
+     *
+     * Required, and the Page draws it itself rather than handing it to the first
+     * release. See the Page's JSDoc for the state that decided it.
+     */
+    title: ReactNode;
+    /** One or two sentences under the heading. */
+    description?: ReactNode;
+    /**
+     * The releases, newest first unless the product says otherwise.
+     *
+     * The Page does not sort them and does not filter them. Order is a publication
+     * decision, and which releases are shown at all is a decision about the reader.
+     */
+    releases: readonly ChangelogPageRelease[];
+    /**
+     * The kinds the reader can ask for, and which of them they have.
+     *
+     * Drawn as a legend rather than as a row of controls, because a control that
+     * does nothing is worse than no control: this Page is a server Component, it
+     * holds no state, and a button on it would be a button a reader presses and
+     * nothing happens.
+     */
+    kinds?: readonly ChangelogPageFilter[];
+    /**
+     * The filter control itself: a `TagGroup`, a set of `Button`s wired to a query
+     * the caller fetches, or a set of links under a query parameter.
+     *
+     * A slot because a filter is a control and this Page ships no behaviour. The
+     * narrowed set comes back through `releases`, which is why the Page never has to
+     * know what the control did.
+     */
+    filters?: ReactNode;
+    /**
+     * The caller's own way of reaching the releases that are not on this page: a
+     * load-more control, a pager, a link to an archive route.
+     *
+     * A slot for the same reason `filters` is one, and for one more: pagination is
+     * a routing decision. Whether the next page is a query parameter, a path
+     * segment or a second fetch is a fact about the consumer's own router, and a
+     * Page that drew a pager would have drawn a router.
+     */
+    older?: ReactNode;
+    /** The closing band asking the reader to subscribe. Omit it and the page ends at `older`. */
+    subscribe?: ChangelogPageSubscribe;
+    /**
+     * What the page shows instead of the releases when there are none.
+     *
+     * Required, and for the same reason the empty state is required on a careers
+     * page: a product that has not shipped yet still has a changelog route, and a
+     * route that draws nothing is a route a reader cannot tell from a broken one.
+     */
+    empty: ReactNode;
+    /**
+     * The heading level for the page's own heading, and one step below it for every
+     * band and for every release heading inside those bands.
+     *
+     * 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 record screen: what changed, in the order it changed, with the
+ * reader's own way of narrowing it and the product's own way of reaching the rest
+ * of it.
+ *
+ * **It composes one `Changelog01` per release, and that is the first thing a Block
+ * cannot do for itself.** A changelog is a record rather than a document, and the
+ * difference is not a matter of taste: a document has one reading order that a
+ * reader follows from the top, and a record has an order that is a claim about
+ * what happened, which is why the Block takes the order it is given and refuses to
+ * sort. A page that passed the whole set to one Block would have every release
+ * inside a single section, and the cost of that is the second thing this Page
+ * exists for. Composing one per release gives each release its own band and its
+ * own anchor, and the alternative was a `Section` per release written here, which
+ * would have meant re-deriving the container and the rhythm that `Section` owns.
+ *
+ * **Each release is linkable, and the release's own heading is what the link
+ * lands on.** This is the page a product points at when it says "since last time":
+ * an email, a status dashboard, a support answer and a customer's own release
+ * notes all want to send a reader to one release rather than to the top of a list
+ * they then have to scroll. So the caller's `id` goes on the element that wraps
+ * each release, the release's heading is the first thing in it, and a fragment link
+ * to that id lands on the release rather than a band above it. The Page uses the
+ * release's key rather than its version for the anchor, because a fragment has to
+ * be legal in a URL and `1.4.0` and `Q3 2026` are not the same shape of string;
+ * the cost is that a consumer writing a link by hand has to use the key, which is
+ * why the key is a required field and not derived from the version.
+ *
+ * **The filters and the older-entries slot are the caller's, and the reason is that
+ * both are facts about the reader.** A changelog is usually longer than anyone will
+ * read, and a reader who wants only the security records and the reader who wants
+ * only the ones since their last deploy are asking two different questions of the
+ * same page, so the control that asks it belongs to whoever knows the answer.
+ * Filtering also means holding state, and a server Page holds none, which is why
+ * `filters` is a node the caller fills with a control they wired themselves and
+ * `kinds` is a legend this Page draws from the state they reported: a row of
+ * pressed-looking marks with no way to press them would be a row of lies, and the
+ * legend is the honest form of the same information. `older` is a slot for the
+ * same reason plus one more, which is that pagination is a routing decision:
+ * whether the next page is a query parameter, a path segment or a second fetch is
+ * a fact about the consumer's router, and a Page that drew a pager would have drawn
+ * a router.
+ *
+ * **The page draws its own `h1`, and the state that decided it is the empty one.**
+ * The alternative was handing the caller's title to the first `Changelog01`, which
+ * is what the about page and the careers page do with their first band, and it was
+ * rejected because `Changelog01` returns nothing at all when it is given no
+ * releases. A product that has not shipped yet, or a product whose first release
+ * is being written right now, still has a changelog route, and on that route the
+ * heading would have been inside the one element that does not render, so the
+ * screen would have had no `h1`, no title, and a sentence about there being no
+ * releases floating under nothing. The Page therefore holds the heading itself, in
+ * a band of its own, and every release below it is composed at one level deeper
+ * with no title, which is also why a release's heading is a child of the page
+ * rather than a sibling of it.
+ *
+ * **`empty` is required and it is not the same prop as the one a Block would want.**
+ * The honest sentence for a changelog with nothing in it is a fact about the
+ * product and not about a changelog: "no releases yet" and "your filter matched
+ * nothing" want different words, and only the caller knows which one they are
+ * showing. So the Page takes the node and draws it in the release band's place, in
+ * a band of its own so the reader is told the record is empty rather than being
+ * shown a gap where it should be.
+ *
+ * It is a server Component. It fetches nothing, it holds no state, it takes no
+ * function prop and it imports no router, so a consumer renders it from their own
+ * changelog route and hands it the releases their release pipeline published.
+ */
+export declare function ChangelogPage({ eyebrow, title, description, releases, kinds, filters, older, subscribe, empty, headingLevel, className, }: ChangelogPageProps): import("react").JSX.Element;
+export default ChangelogPage;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/changelog-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGpG;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAA;IACV,8CAA8C;IAC9C,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAA;IAC5D,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;;;;;OAQG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,uFAAuF;IACvF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAA;CACxC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,KAAK,EAAE,IAAI,GAAG,KAAK,CAAA;CACpB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,0BAA0B;IAC1B,KAAK,EAAE,SAAS,CAAA;IAChB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,sEAAsE;IACtE,GAAG,EAAE,SAAS,CAAA;CACf,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;OAKG;IACH,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACzC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAA;IACtC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,sBAAsB,CAAA;IAClC;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,KAAK,EACL,OAAO,EACP,KAAK,EACL,SAAS,EACT,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,kBAAkB,+BA2EpB;AAED,eAAe,aAAa,CAAA"}

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

@@ -0,0 +1,86 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Changelog01 } from '../../blocks/changelog-01/index.js';
+import { Badge } from '../../components/ui/badge.js';
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A complete record screen: what changed, in the order it changed, with the
+ * reader's own way of narrowing it and the product's own way of reaching the rest
+ * of it.
+ *
+ * **It composes one `Changelog01` per release, and that is the first thing a Block
+ * cannot do for itself.** A changelog is a record rather than a document, and the
+ * difference is not a matter of taste: a document has one reading order that a
+ * reader follows from the top, and a record has an order that is a claim about
+ * what happened, which is why the Block takes the order it is given and refuses to
+ * sort. A page that passed the whole set to one Block would have every release
+ * inside a single section, and the cost of that is the second thing this Page
+ * exists for. Composing one per release gives each release its own band and its
+ * own anchor, and the alternative was a `Section` per release written here, which
+ * would have meant re-deriving the container and the rhythm that `Section` owns.
+ *
+ * **Each release is linkable, and the release's own heading is what the link
+ * lands on.** This is the page a product points at when it says "since last time":
+ * an email, a status dashboard, a support answer and a customer's own release
+ * notes all want to send a reader to one release rather than to the top of a list
+ * they then have to scroll. So the caller's `id` goes on the element that wraps
+ * each release, the release's heading is the first thing in it, and a fragment link
+ * to that id lands on the release rather than a band above it. The Page uses the
+ * release's key rather than its version for the anchor, because a fragment has to
+ * be legal in a URL and `1.4.0` and `Q3 2026` are not the same shape of string;
+ * the cost is that a consumer writing a link by hand has to use the key, which is
+ * why the key is a required field and not derived from the version.
+ *
+ * **The filters and the older-entries slot are the caller's, and the reason is that
+ * both are facts about the reader.** A changelog is usually longer than anyone will
+ * read, and a reader who wants only the security records and the reader who wants
+ * only the ones since their last deploy are asking two different questions of the
+ * same page, so the control that asks it belongs to whoever knows the answer.
+ * Filtering also means holding state, and a server Page holds none, which is why
+ * `filters` is a node the caller fills with a control they wired themselves and
+ * `kinds` is a legend this Page draws from the state they reported: a row of
+ * pressed-looking marks with no way to press them would be a row of lies, and the
+ * legend is the honest form of the same information. `older` is a slot for the
+ * same reason plus one more, which is that pagination is a routing decision:
+ * whether the next page is a query parameter, a path segment or a second fetch is
+ * a fact about the consumer's router, and a Page that drew a pager would have drawn
+ * a router.
+ *
+ * **The page draws its own `h1`, and the state that decided it is the empty one.**
+ * The alternative was handing the caller's title to the first `Changelog01`, which
+ * is what the about page and the careers page do with their first band, and it was
+ * rejected because `Changelog01` returns nothing at all when it is given no
+ * releases. A product that has not shipped yet, or a product whose first release
+ * is being written right now, still has a changelog route, and on that route the
+ * heading would have been inside the one element that does not render, so the
+ * screen would have had no `h1`, no title, and a sentence about there being no
+ * releases floating under nothing. The Page therefore holds the heading itself, in
+ * a band of its own, and every release below it is composed at one level deeper
+ * with no title, which is also why a release's heading is a child of the page
+ * rather than a sibling of it.
+ *
+ * **`empty` is required and it is not the same prop as the one a Block would want.**
+ * The honest sentence for a changelog with nothing in it is a fact about the
+ * product and not about a changelog: "no releases yet" and "your filter matched
+ * nothing" want different words, and only the caller knows which one they are
+ * showing. So the Page takes the node and draws it in the release band's place, in
+ * a band of its own so the reader is told the record is empty rather than being
+ * shown a gap where it should be.
+ *
+ * It is a server Component. It fetches nothing, it holds no state, it takes no
+ * function prop and it imports no router, so a consumer renders it from their own
+ * changelog route and hands it the releases their release pipeline published.
+ */
+export function ChangelogPage({ eyebrow, title, description, releases, kinds, filters, older, subscribe, empty, headingLevel = 'h1', className, }) {
+    const band = childLevel(headingLevel);
+    return (_jsxs("div", { "data-slot": "changelog-page", className: cn(className), children: [_jsx(Section, { "data-slot": "changelog-page-heading", children: _jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }) }), kinds === undefined && filters === undefined ? null : (_jsx(Section, { "data-slot": "changelog-page-filters", children: _jsxs("div", { className: "flex flex-col items-start gap-4", children: [kinds === undefined || kinds.length === 0 ? null : (_jsx("ul", { "data-slot": "changelog-page-kinds", className: "flex flex-wrap items-center gap-2", children: kinds.map((kind) => (_jsx("li", { children: _jsx(Badge, { variant: kind.state === 'on' ? 'secondary' : 'outline', "data-state": kind.state, children: kind.label }) }, kind.id))) })), filters] }) })), releases.length === 0 ? (_jsx(Section, { "data-slot": "changelog-page-empty", children: _jsx("div", { "data-slot": "changelog-page-empty-body", className: "text-muted-foreground text-pretty text-sm", children: empty }) })) : (releases.map((release) => (_jsx("div", { id: release.id, "data-slot": "changelog-page-release", children: _jsx(Changelog01, { headingLevel: band, releases: [
+                        {
+                            id: release.id,
+                            version: release.version,
+                            at: release.at,
+                            summary: release.summary,
+                            entries: release.entries.map((entry) => ({ ...entry })),
+                        },
+                    ] }) }, release.id)))), older === undefined ? null : _jsx(Section, { "data-slot": "changelog-page-older", children: older }), subscribe === undefined ? null : (_jsxs(Section, { "data-slot": "changelog-page-subscribe", children: [_jsx(SectionHeading, { as: band, align: "left", title: subscribe.title, description: subscribe.description, className: "mb-8" }), subscribe.cta] }))] }));
+}
+export default ChangelogPage;

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

@@ -0,0 +1,261 @@
+import type { ReactNode } from 'react';
+import { type Contact01Status, type ContactValue } from '../../blocks/contact-01/index.js';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One choice in a select field.
+ *
+ * A `value` that is a key and a `label` that is a sentence, because that is what a
+ * native `<option>` holds and nothing else. A caller who needs a description beside
+ * an option, a count or anything nested is reaching for a control the platform
+ * cannot render, and `Contact01` names that rather than pretending otherwise.
+ */
+export type ContactPageOption = {
+    /** What the form submits for this choice, which is a key and not a sentence. */
+    value: string;
+    /** The words the reader sees, in the product's own language. */
+    label: string;
+};
+/**
+ * One declared field of the contact form.
+ *
+ * **Flat, on purpose, where `ContactField` is a union.** A consumer's form data is
+ * flat: a record read out of a content type, a CMS entry or a JSON file has one
+ * shape with an optional `options` key, and a caller that had to narrow their own
+ * record before they could hand it to a page would be doing the Block's type work
+ * at every call site. So the union is built once, inside this module, and the one
+ * shape it cannot build is refused here with a message that names the Page's own
+ * prop. That is `AboutPage`'s arrangement for the same pair of link fields, and the
+ * cost is the same: a caller who wants the compile error rather than the thrown one
+ * types their fields against `ContactField` and passes the result here, which
+ * works because the two are structurally the same.
+ */
+export type ContactPageField = {
+    /** The caller's key for this field, and the key the value arrives under. */
+    id: string;
+    /** The field's visible name, and the accessible name its control announces. */
+    label: string;
+    /** The control the field draws. Five, and they are the five `Contact01` draws. */
+    type: 'text' | 'email' | 'tel' | 'textarea' | 'select';
+    /** Whether the reader may submit the form without filling it. */
+    required: boolean;
+    /** A line under the control, announced with it. */
+    description?: ReactNode;
+    /** What the control shows while it is empty. A hint, not a name. */
+    placeholder?: string;
+    /** The choices of a `select` field, and forbidden on the other four. */
+    options?: readonly ContactPageOption[];
+    /** The platform's own autofill hint for this field. */
+    autoComplete?: string;
+};
+/**
+ * Every field of an office but whether it carries a map link.
+ *
+ * Not exported, because the two arms below are what a caller writes and this is
+ * only the half they share.
+ */
+type ContactPageOfficeFacts = {
+    /** A stable key for the office, carried on the markup as `data-office`. */
+    id: string;
+    /**
+     * The name of the place: the city, the region, the desk.
+     *
+     * Required, because a card of postal lines with nothing naming which place they
+     * are is a set of addresses a reader has to guess between.
+     */
+    name: string;
+    /** The postal lines, one per entry, in the order a reader reads them. */
+    lines: readonly string[];
+    /** Whatever else is true of this place: the hours, the languages, the nearest station. */
+    detail?: ReactNode;
+};
+/**
+ * One place a reader can reach a person, and the one link it may carry.
+ *
+ * **`mapLabel` is required wherever `mapHref` is, and declared forbidden where it is
+ * not**, for the reason every other link in this package carries the same union: a
+ * control whose only words are a coordinate or a route is a control a screen reader
+ * announces as punctuation, and it is also the one control on a card whose words a
+ * mouse reader cannot select, because the words they select are the ones on the
+ * control rather than the ones in the address bar.
+ */
+export type ContactPageOffice = (ContactPageOfficeFacts & {
+    /** Where a map of this place is, as a native anchor's `href`. */
+    mapHref: string;
+    /** The words on that link. Required here, and forbidden on the other arm. */
+    mapLabel: string;
+}) | (ContactPageOfficeFacts & {
+    /** No map link on this card, so no destination to name. */
+    mapHref?: never;
+    /** No accessible name owed, because there is no link to name. */
+    mapLabel?: never;
+});
+/**
+ * The props a ContactPage takes.
+ *
+ * Every string, every destination and the outcome of the request are props, and the
+ * Page ships none of them. A contact screen is where a design system's copy is most
+ * tempting and most expensive, because it is the screen a product writes its own
+ * apology into, and a sentence written here would be inherited by every consumer.
+ */
+export type ContactPageProps = {
+    /** Optional label above the page's own heading. See the No-Default-Eyebrow Rule. */
+    eyebrow?: ReactNode;
+    /**
+     * The page's heading, and this screen's `h1`.
+     *
+     * Required, and drawn by the Page rather than handed to the form band. See the
+     * Page's JSDoc for why the screen needs two headings and why they are not the
+     * same sentence twice.
+     */
+    title: ReactNode;
+    /** One or two sentences under the heading, for what to expect from a reply. */
+    description?: ReactNode;
+    /**
+     * The name of the form band, which sits one step below the page heading.
+     *
+     * Required rather than optional, and the reason is `Contact01`'s own: that Block
+     * requires a title, because a form with no heading is a form in a page. A screen
+     * that drew a page heading and gave the form band nothing would have a page whose
+     * title was the title of one of its own regions, and a reader navigating by
+     * heading would meet the form and not the page.
+     */
+    form: {
+        /** The band's heading. */
+        title: ReactNode;
+        /** One supporting line under it, for the part the heading cannot carry. */
+        description?: ReactNode;
+    };
+    /**
+     * The fields, in the order the reader should meet them.
+     *
+     * `readonly` because the normal way a consumer writes a field list is an `as
+     * const` fixture or a record read out of a build step, and a prop typed as a
+     * mutable array rejects both at the moment they are most useful.
+     */
+    fields: readonly ContactPageField[];
+    /**
+     * Called with the declared fields' values when the reader submits.
+     *
+     * Required, for the reason `Contact01` gives: it is the only thing this Page does
+     * with what the form collected, and there is no arm of this screen in which a
+     * message is gathered and then nowhere to go.
+     */
+    onSubmit: (value: ContactValue) => void;
+    /** The label on the one control that submits. */
+    submitLabel: string;
+    /**
+     * What the reader is told happens to what they type, drawn under the fields where
+     * the reader is about to press the control.
+     */
+    consent?: ReactNode;
+    /**
+     * The outcome of the caller's own request, drawn in a live region and announced.
+     *
+     * `Contact01`'s status, taken unchanged rather than restated. Its four states are
+     * read for two things only: `sending` disables the submit control, because a
+     * second press while the first request is in flight is a duplicate enquiry a
+     * support inbox cannot merge, and `error` makes the announcement assertive. A Page
+     * that named the same state `working` would have to translate it at the boundary,
+     * which buys a vaguer word and a table to keep in step.
+     */
+    status?: Contact01Status;
+    /**
+     * The closing band: a `Faq01` for the questions nobody should have to ask to find
+     * this screen, a `Newsletter01`, or a legal line.
+     *
+     * Named for the band most consumers put here, and it holds any of the three,
+     * because a contact screen is the band, the places, and the questions, and the
+     * last of those is content rather than a footer.
+     */
+    footer?: ReactNode;
+    /**
+     * The level of the page's own heading, and one step below it for the band
+     * headings, and two below for an office's name.
+     *
+     * Defaults to `h1`, because a Page owns the top of the document outline.
+     */
+    headingLevel?: HeadingLevel;
+    /** Layout only, exactly as on every Item. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+} & ({
+    /**
+     * The places a reader can reach a person, in the order a reader should meet
+     * them. At least one, and the band is only there when there are.
+     */
+    offices: readonly ContactPageOffice[];
+    /**
+     * The accessible name and the visible heading of that band.
+     *
+     * Required here and forbidden on the other arm. "Offices", "Where we are"
+     * and "Locations" are three products' words, and a row of addresses with
+     * nothing above it is the region every contact screen forgets to name.
+     */
+    officesLabel: string;
+} | {
+    /** No places on this screen, so there is no band to name. */
+    offices?: never;
+    /** No word is needed, because there is no band to name. */
+    officesLabel?: never;
+});
+/**
+ * A complete contact screen: the page heading, the form the caller declares, the
+ * places a reader can reach a person, and the questions they should not have to ask
+ * to find this screen.
+ *
+ * **The offices are the part that makes this a Page rather than a `Contact01`, and
+ * it is worth saying what that Block cannot do.** A contact Block is a band: one
+ * form, in one column, with the caller's fields. A contact screen is the band, the
+ * places, and the questions, and the two extras are what a reader actually arrives
+ * with, because a reader who wants to write has a fallback and a reader who has run
+ * out of patience has a map. `Contact01` has an `address` arm and this Page does not
+ * use it, for three reasons that all point the same way: that arm holds exactly one
+ * postal address where a business has as many as it has regions; it has no field for
+ * a name for the place, so three cities are three unlabelled blocks of lines; and
+ * its link arm is a `mailto`, which is the wrong link for a place that is not
+ * reachable by post. A consumer whose only address is one postal address beside one
+ * form should compose `Contact01` with that arm, which is the better arrangement
+ * for one address, and the cost here is the other thing: the offices are a band
+ * under the form rather than a column beside it, because a Block that draws its own
+ * `Section` cannot be dropped into a grid column without the page's vertical rhythm
+ * doubling, which is the same reason `dashboard-page` stacks its bands rather than
+ * setting two of them side by side.
+ *
+ * **The offices are facts and not controls, and the type is what holds that.** A
+ * postal line is a string a reader copies. `detail` is a node, because the honest
+ * thing under a place is sometimes a sentence and sometimes a small table of
+ * opening hours, and a string would force one of those to be flattened. The only
+ * link a card may carry is the caller's own map link, and it carries words, and the
+ * union is what makes those words required. A screen that turned its regions into
+ * navigation would be telling a reader that a place is a topic they can read about,
+ * and the only topic any of them has is how to get there.
+ *
+ * **The page heading and the form band are two headings and not one sentence twice.**
+ * The rejected alternative was handing `title` to the form and letting the Block's
+ * section heading be the page's `h1`, which is what `onboarding-page` does and what
+ * it can do because its first band is the whole screen. Here the first band is a
+ * form with a name of its own, and a screen whose page heading was "Talk to us" and
+ * whose form heading was also "Talk to us" would be a page with one heading drawn
+ * twice and a reader navigating by heading who met the form rather than the page.
+ *
+ * **The status is `Contact01`'s, and the refusal to invent one is the whole of this
+ * Page's copy law.** There is no success sentence anywhere in this file, no `sent`
+ * flag written by this package, and no "we will reply within a day". A contact
+ * request can be delivered, held by a filter, filed by a bot, refused as a duplicate
+ * and answered, and one sentence cannot be true of all five, so the caller owns the
+ * promise and writes the words. The cost is that a consumer who installs this screen
+ * has to write a sentence they will get wrong once.
+ *
+ * **It is a client Component, and the reason is `onSubmit`.** 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 server Page that took one would hand
+ * a caller a form that gathers a person's name, an address and a message and then
+ * calls nothing. `Contact01` is a client module for the same reason and the Page
+ * cannot be a server module in front of it. The cost is stated rather than hidden:
+ * every datum on this screen is serialised across the boundary to reach a band three
+ * elements down, and the rejected alternative was a form slot, which would have
+ * been a Page that owns a heading, a row of addresses and nothing a reader could
+ * submit.
+ */
+export declare function ContactPage({ eyebrow, title, description, form, fields, onSubmit, submitLabel, consent, status, offices, officesLabel, footer, headingLevel, className, }: ContactPageProps): import("react").JSX.Element;
+export default ContactPage;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/contact-page/index.tsx"],"names":[],"mappings":"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"}