@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/blocks/contact-01/contact.d.ts

@@ -0,0 +1,319 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One choice in a `select` field, and nothing else.
+ *
+ * A native `<option>` holds text and nothing more, which is the whole reason a
+ * contact form's select is a `NativeSelect` rather than the Base UI one. The two
+ * values are a string and its label, so 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` does not pretend otherwise: it names
+ * `NativeSelect`'s own argument in its JSDoc and stops there.
+ */
+export type Contact01Option = {
+    /** 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;
+};
+/**
+ * What every contact field carries, whichever control it draws.
+ *
+ * `required` is a boolean rather than an optional prop because there is no third
+ * state worth having: a field is one the reader must fill or one they may leave,
+ * and a `required?: boolean` leaves a caller who passed nothing unable to say which
+ * of the two they meant. A field is a data declaration and nothing else, and the
+ * two arms below differ only in which control is drawn and in the one property
+ * that control needs and the other has no use for.
+ */
+type ContactFieldBase = {
+    /** 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;
+    /** Whether the reader may submit the form without filling it. */
+    required: boolean;
+    /**
+     * A line under the control, announced with it.
+     *
+     * A node, because the honest line is sometimes not one sentence: a caller's
+     * hint, a link to the thing being asked about, a piece of the page's own copy.
+     * It is wired to the control through `aria-describedby` rather than drawn as a
+     * footnote, so a screen reader hears what this field is for as they reach it.
+     */
+    description?: ReactNode;
+    /** What the control shows while it is empty. A hint, not a name. */
+    placeholder?: string;
+    /** The platform's own autofill hint for this field. */
+    autoComplete?: string;
+};
+/**
+ * One field of the caller's form, and the control it draws.
+ *
+ * **A union and not one type with an optional `options`, and that is the shape of
+ * the whole argument in this Block.** A contact form's fields are the caller's
+ * declaration, not this package's opinion about what a reader may be asked, and
+ * the one place that shows is the select: a select with no options is a control
+ * with nothing in it, which is a question no reader can answer, so `options` is
+ * required inside the select arm and forbidden beside the other four. A
+ * `options?: string[]` on one type would typecheck the defect and only the
+ * diagnostic at run time would catch it, which is one gate too late. The union is
+ * the same mechanism `HeroAction` uses for the same reason: the shape that
+ * requires something declares it, and the shape that forbids it says so in the
+ * type rather than in prose.
+ *
+ * The cost of the union is that a caller who wants to build a field list
+ * generically, from data, has to narrow before it can type the result, and the
+ * answer to that is a narrowing function in the caller's own code rather than a
+ * looser type here.
+ */
+export type ContactField = (ContactFieldBase & {
+    type: 'select';
+    /** The choices, in the order the reader should meet them. */
+    options: Contact01Option[];
+}) | (ContactFieldBase & {
+    type: 'text' | 'email' | 'tel' | 'textarea';
+    /** A select with no options is a question nobody can answer, so it is not one here. */
+    options?: never;
+});
+/**
+ * Where a reader can reach a person, and the one address this Block links.
+ *
+ * **The `email` and `emailLabel` arms are a union, and the reason is the sentence
+ * a screen reader would otherwise read.** A mailto link whose accessible name is
+ * the address itself is announced as `mailto` and a run of characters read out
+ * one at a time, which is the one link on the page no reader can follow and the
+ * one a mouse reader cannot copy either. So a link is never drawn from a bare
+ * address: `emailLabel` is the sentence that says what activating it does, and it
+ * is required inside the arm where `email` is. The alternative was an optional
+ * `emailLabel` beside an optional `email` and a fallback, and the fallback would
+ * have been the address, which is the defect.
+ */
+export type Contact01Address = {
+    /** The postal lines, one per entry, in the order a reader reads them. */
+    lines: string[];
+    /**
+     * What a reader is told about the hours, if the caller has hours to state.
+     *
+     * A node rather than a string, because the honest content is a table on three of
+     * the four consumer sites rather than a sentence, and a Block that accepted a
+     * string would force the caller to flatten it.
+     */
+    hours?: ReactNode;
+} & ({
+    /** The address the mailto link points at. */
+    email: string;
+    /** The words on the link, which is its accessible name. */
+    emailLabel: string;
+} | {
+    /** No link, so no accessible name to owe. */
+    email?: never;
+    emailLabel?: never;
+});
+/**
+ * Everything the caller declared, keyed by the caller's own `id`.
+ *
+ * A record and not a fixed shape, and the reason is the same one that makes
+ * `fields` a list: the keys are facts about the caller's product, so a named type
+ * would be a claim about what a contact form is made of. The value type is `string`
+ * because the five control types here all submit strings, and a contact form that
+ * collects a file is a different Block.
+ */
+export type ContactValue = Record<string, string>;
+/**
+ * The outcome of the caller's own request, as the Block draws it.
+ *
+ * A prop and never a state this Block writes, for the reason every Block in this
+ * wave states: a success sentence this package wrote would be inherited verbatim
+ * by every consumer, and a contact request has more outcomes than any other form
+ * here, from a delivered message to a spam folder to a rate limit to an address
+ * that was never deliverable.
+ */
+export type Contact01Status = {
+    /** Which of the four the request is in. Read by the Block for two things only. */
+    state: 'idle' | 'sending' | 'sent' | 'error';
+    /** The words for that state, in the product's own voice. */
+    message: ReactNode;
+};
+/** The props a Contact01 takes. Every string in this Block is one of them. */
+export type Contact01Props = {
+    /** The short line above the title, usually what the desk is called. */
+    eyebrow?: ReactNode;
+    /** The heading. Required, because a form with no heading is a form in a page. */
+    title: ReactNode;
+    /** One supporting line under the heading, for the part the title cannot carry. */
+    description?: ReactNode;
+    /**
+     * Called with the declared fields' values when the reader submits.
+     *
+     * **Required, and the requirement is the design.** `onSubmit` is the only thing
+     * this Block does with what it collected, and there is no arm of this component
+     * in which a message is gathered and then nowhere to go. The obvious
+     * alternative is an optional handler with a form that renders and does nothing,
+     * which is a component that collects a personal datum, displays it back to the
+     * reader and then discards it without telling anyone.
+     */
+    onSubmit: (value: ContactValue) => void;
+    /**
+     * The fields, in the order the reader should meet them.
+     *
+     * **Required, and this list is the whole design rather than a convenience.** A
+     * contact form Component with a fixed set of fields is a Component that decides
+     * what a reader may say, and the decision is invisible in a review because the
+     * rendered form looks complete. It is also the decision that loses the message
+     * a contact form was given: a form that cannot ask for an order number has to
+     * be abandoned and retried through a support channel, a form that cannot ask for
+     * a company size sends a one-line hello to a sales team that then spends a week
+     * on discovery calls, and a form that cannot ask for a budget guarantees the
+     * reply nobody wanted. So Prism names the five control types it can draw and
+     * supplies no fields: a contact desk that asks for a tax number, a preferred
+     * contact window and three product interests is three fields of the caller's own
+     * vocabulary and a select, and Prism composes all of them. The cost is stated
+     * rather than hidden: a consumer that wants a second column for a subset of its
+     * fields composes two `Contact01`s or reaches for a `Page`, because this Block
+     * draws one column in the order the list gives.
+     */
+    fields: ContactField[];
+    /** The label on the one control that submits. */
+    submitLabel: string;
+    /**
+     * What the reader is told happens to what they type.
+     *
+     * Optional here, and the difference from `Newsletter01` is the fact rather than
+     * an inconsistency: a newsletter's consent line is about a marketing list and a
+     * jurisdiction may require it to be there, while a contact form's disclosure is
+     * about a reply, and most jurisdictions are satisfied by the caller's own footer
+     * and by this Block's status sentence. A caller whose counsel asks for one
+     * passes it, and it is drawn under the fields where the reader is about to press
+     * the control rather than in a page they have already scrolled past.
+     */
+    consent?: ReactNode;
+    /** Where a reader can reach a person, drawn beside the form in the split layout. */
+    address?: Contact01Address;
+    /**
+     * Whether the address sits beside the form or under it.
+     *
+     * `split` is right where the address is a real destination rather than a
+     * decoration, which is most of the time, and `stacked` is right on a narrow
+     * page and wherever a reader on a phone would otherwise have to scroll past four
+     * postal lines before reaching the field they came for. There is no third
+     * arrangement that changes Prism's drawing rather than this Block's spacing,
+     * because `className` is layout only.
+     */
+    variant?: 'split' | 'stacked';
+    /**
+     * The outcome of the caller's request, drawn in a live region and announced.
+     *
+     * A prop and never an internal state Prism writes, for the reason the type
+     * states: a success sentence this package wrote would be inherited by every
+     * consumer and would be the one sentence on the page most certainly wrong.
+     */
+    status?: Contact01Status;
+    /** Heading level for the section heading. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * A contact form whose fields the caller declares, beside the address a reader can
+ * reach a person at.
+ *
+ * **The declared field list is the whole design, and the reason is that a contact
+ * form is a form about the message.** A contact form Component with a fixed set of
+ * fields is a Component that decides what a reader may say, and the decision is
+ * invisible in a review because the rendered form looks complete: four labelled
+ * controls and a submit button read as a finished surface in a screenshot. What it
+ * is is a claim about what enquiries are, and it is a claim that loses the message
+ * the form was given. A form that cannot ask for an order number is a form a
+ * reader abandons and retried through a support channel. A form that cannot ask for
+ * a company size sends a one-line hello to a sales team that then spends a week on
+ * discovery calls. A form that cannot ask for a budget guarantees the reply nobody
+ * wanted, because the reader has already told the sender what they can afford and
+ * the send has nowhere to put it. So `fields` is a prop list of the caller's own,
+ * Prism names the five control types it can draw and supplies no fields at all, and
+ * a contact desk that asks for a tax number, a preferred contact window and three
+ * product interests is three fields and a select. The honest cost is the mirror of
+ * the argument: one column in the order the list gives, so a consumer that wants a
+ * two-column form for a subset of its fields composes two of these or reaches for
+ * a Page, and no single field here can be described by a caller's own validation
+ * message, which is the second cost and is stated below.
+ *
+ * **`onSubmit` is required and the Block sends nothing, which is what makes it
+ * installable.** The alternative shape, the one this Block is shaped to refuse, is a
+ * component that collects a name, an address and a message and posts them to a route
+ * it guessed at: four consumers with four back ends then either patch it or rewrite
+ * it, and in the meantime the message has been handled, stored, retried, threaded
+ * and forgotten by a piece of code that was installed to draw a form. Every one of
+ * those five is a decision about the caller's product and its data, and a frame that
+ * takes one of them is a frame that has to be replaced rather than configured. A
+ * consumer who wants a transport writes one, and a consumer who already has one
+ * passes it straight in.
+ *
+ * **There is no success message anywhere in this file, and that is the other half
+ * of the same argument.** A form that owns its own outcome sentence puts that
+ * sentence into every product that installs the Block, the corpus publishes it as
+ * this design system's own voice, and it is the single line on the page most
+ * certainly to be wrong: 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 `status` is a prop with a caller-written message, this file
+ * holds no `sent` flag and no `error` flag, and a consumer who installs this Block
+ * owns the promise it makes.
+ *
+ * **The run throws on a field with no label and on a select with no options, and
+ * both refusals are about a control that cannot be used.** A nameless control is
+ * announced as "text field", which is the one name every other field on the page
+ * shares, so two fields in this same form become indistinguishable to a screen
+ * reader and the form is unusable for exactly the readers the label exists for. A
+ * select with nothing in it is a question no reader can answer that looks answered
+ * only because the control is there and focusable. The type catches the second
+ * one for a TypeScript caller through the union above, and the check is here for
+ * the JavaScript caller and for the value that came out of a database with the
+ * type's guarantee already gone. Each message names the field rather than the
+ * index, because a caller with nine fields needs to know which one.
+ *
+ * **`emailLabel` is required wherever there is an email, because a mailto link
+ * whose accessible name is the address is unreadable as a sentence.** The link
+ * would be announced as the word mailto and then a run of characters read out one
+ * at a time, which is the one link on the page no reader can follow and the one a
+ * mouse reader cannot copy either, because the words a reader selects are the ones
+ * on the control rather than the ones in the address bar. So the visible text is
+ * the caller's sentence about what the link does, and the address itself is in the
+ * `href` where it belongs. The union on `Contact01Address` is what holds it: an
+ * optional `emailLabel` beside an optional `email` would need a fallback, and the
+ * only fallback available is the address.
+ *
+ * **Every field goes through `Field`, so its label, its description and the control
+ * that announces them are Prism's wiring rather than a caller's.** That is the
+ * second reason the field list is data: the wiring is the part that has to be right
+ * on every field, and a Block that drew a bespoke row per type would have six
+ * places to get it wrong. What `field.tsx` offers and this Block does not draw is
+ * `FieldError`, and the omission is a decision rather than an oversight: the
+ * sentence saying what is wrong with a value is the one sentence a native control
+ * already gets right in the reader's own language for free, because the browser
+ * writes it, so the `required` and `type` attributes this Block forwards are the
+ * error path and a per-field message from the caller is composed beside `Field`
+ * rather than inside this Block. The cost is named: a consumer whose validation
+ * rules are its own rather than the platform's has no seam here, and the answer is
+ * that it validates in its handler and puts the message in `status`, which is one
+ * sentence about all the fields rather than one per field.
+ *
+ * **Nothing here validates anything.** There is no address format check, no message
+ * length, no required consent and no spam rule. Each of those is a decision about
+ * the caller's product and its data, and a Block that guessed one would refuse a
+ * reader on the caller's behalf. What Prism does with `status` is refuse a second
+ * press: while the state reads `sending` the submit control is disabled, because a
+ * second press while the first request is in flight is a duplicate enquiry a
+ * support inbox cannot merge. That is the whole of Prism's reading of the state,
+ * and it is stated here because the alternative is a Block that has begun to have
+ * opinions about the request.
+ *
+ * It is a client Component, and the reason is the handler rather than the state.
+ * `onSubmit` is a function, a function is a piece of state, and state is a client
+ * module: a server component cannot hand an event handler down to a `<form>`, so a
+ * caller rendering this from a server component gets a form that submits and calls
+ * nothing. The rest of the rendering is a section and five controls, which is the
+ * price of the argument above and not a claim about what else this Block might do.
+ */
+export declare function Contact01({ eyebrow, title, description, onSubmit, fields, submitLabel, consent, address, variant, status, headingLevel, className, }: Contact01Props): import("react").JSX.Element;
+export default Contact01;
+//# sourceMappingURL=contact.d.ts.map

package/dist/blocks/contact-01/contact.d.ts.map

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

package/dist/blocks/contact-01/contact.js

@@ -0,0 +1,211 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Button } from '../../components/ui/button.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Field, FieldDescription, FieldLabel } from '../../components/ui/field.js';
+import { Input } from '../../components/ui/input.js';
+import { LiveRegion } from '../../components/ui/live-region.js';
+import { NativeSelect } from '../../components/ui/native-select.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Textarea } from '../../components/ui/textarea.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Whether a caller-supplied string never arrived, arrived empty, or arrived as
+ * nothing but space.
+ *
+ * Read as `string | undefined` rather than as the declared `string`, because the
+ * check is about the value that turned up rather than about what the type
+ * promised. A JavaScript caller and a value out of a database both arrive with
+ * the type's guarantee already gone, and the diagnostic below is the last place
+ * that can still say what was wrong.
+ */
+function blank(value) {
+    return value === undefined || value.trim() === '';
+}
+/**
+ * Whether a caller passed a list that is not there, or is there and empty.
+ *
+ * The same argument as `blank` above, and the reason a select with no options is
+ * caught rather than drawn: a control with nothing in it is a question no reader
+ * can answer, and it is a question that looks answered because the control is
+ * there and focusable.
+ */
+function blankList(value) {
+    return value === undefined || value.length === 0;
+}
+/**
+ * The two ways a caller's field declaration can be a form that cannot be filled,
+ * checked before anything is drawn so the run fails once with the name of the
+ * field rather than once per field with a nameless control on the page.
+ *
+ * Both reach a developer in a console rather than a reader, which is what makes
+ * them refusals rather than copy: the message says what was passed and what to
+ * pass instead, and neither of those sentences is ever shown to a reader.
+ */
+function assertField(field) {
+    if (blank(field.label)) {
+        throw new Error(`Contact01: the field "${field.id}" declares no label, so the control would be announced with no name and ` +
+            'two fields on this page would be announced identically. Every control this Block draws is named by its ' +
+            'label, so there is no fallback to fall back to.');
+    }
+    if (field.type === 'select' && blankList(field.options)) {
+        throw new Error(`Contact01: the field "${field.id}" is a select and passes no options, so it would render a control with ` +
+            'nothing in it, which is a question no reader can answer and looks answered only because the control is ' +
+            'there and focusable. Pass the choices, or declare the field as a text field and check the answer in your ' +
+            'own handler.');
+    }
+}
+/**
+ * A contact form whose fields the caller declares, beside the address a reader can
+ * reach a person at.
+ *
+ * **The declared field list is the whole design, and the reason is that a contact
+ * form is a form about the message.** A contact form Component with a fixed set of
+ * fields is a Component that decides what a reader may say, and the decision is
+ * invisible in a review because the rendered form looks complete: four labelled
+ * controls and a submit button read as a finished surface in a screenshot. What it
+ * is is a claim about what enquiries are, and it is a claim that loses the message
+ * the form was given. A form that cannot ask for an order number is a form a
+ * reader abandons and retried through a support channel. A form that cannot ask for
+ * a company size sends a one-line hello to a sales team that then spends a week on
+ * discovery calls. A form that cannot ask for a budget guarantees the reply nobody
+ * wanted, because the reader has already told the sender what they can afford and
+ * the send has nowhere to put it. So `fields` is a prop list of the caller's own,
+ * Prism names the five control types it can draw and supplies no fields at all, and
+ * a contact desk that asks for a tax number, a preferred contact window and three
+ * product interests is three fields and a select. The honest cost is the mirror of
+ * the argument: one column in the order the list gives, so a consumer that wants a
+ * two-column form for a subset of its fields composes two of these or reaches for
+ * a Page, and no single field here can be described by a caller's own validation
+ * message, which is the second cost and is stated below.
+ *
+ * **`onSubmit` is required and the Block sends nothing, which is what makes it
+ * installable.** The alternative shape, the one this Block is shaped to refuse, is a
+ * component that collects a name, an address and a message and posts them to a route
+ * it guessed at: four consumers with four back ends then either patch it or rewrite
+ * it, and in the meantime the message has been handled, stored, retried, threaded
+ * and forgotten by a piece of code that was installed to draw a form. Every one of
+ * those five is a decision about the caller's product and its data, and a frame that
+ * takes one of them is a frame that has to be replaced rather than configured. A
+ * consumer who wants a transport writes one, and a consumer who already has one
+ * passes it straight in.
+ *
+ * **There is no success message anywhere in this file, and that is the other half
+ * of the same argument.** A form that owns its own outcome sentence puts that
+ * sentence into every product that installs the Block, the corpus publishes it as
+ * this design system's own voice, and it is the single line on the page most
+ * certainly to be wrong: 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 `status` is a prop with a caller-written message, this file
+ * holds no `sent` flag and no `error` flag, and a consumer who installs this Block
+ * owns the promise it makes.
+ *
+ * **The run throws on a field with no label and on a select with no options, and
+ * both refusals are about a control that cannot be used.** A nameless control is
+ * announced as "text field", which is the one name every other field on the page
+ * shares, so two fields in this same form become indistinguishable to a screen
+ * reader and the form is unusable for exactly the readers the label exists for. A
+ * select with nothing in it is a question no reader can answer that looks answered
+ * only because the control is there and focusable. The type catches the second
+ * one for a TypeScript caller through the union above, and the check is here for
+ * the JavaScript caller and for the value that came out of a database with the
+ * type's guarantee already gone. Each message names the field rather than the
+ * index, because a caller with nine fields needs to know which one.
+ *
+ * **`emailLabel` is required wherever there is an email, because a mailto link
+ * whose accessible name is the address is unreadable as a sentence.** The link
+ * would be announced as the word mailto and then a run of characters read out one
+ * at a time, which is the one link on the page no reader can follow and the one a
+ * mouse reader cannot copy either, because the words a reader selects are the ones
+ * on the control rather than the ones in the address bar. So the visible text is
+ * the caller's sentence about what the link does, and the address itself is in the
+ * `href` where it belongs. The union on `Contact01Address` is what holds it: an
+ * optional `emailLabel` beside an optional `email` would need a fallback, and the
+ * only fallback available is the address.
+ *
+ * **Every field goes through `Field`, so its label, its description and the control
+ * that announces them are Prism's wiring rather than a caller's.** That is the
+ * second reason the field list is data: the wiring is the part that has to be right
+ * on every field, and a Block that drew a bespoke row per type would have six
+ * places to get it wrong. What `field.tsx` offers and this Block does not draw is
+ * `FieldError`, and the omission is a decision rather than an oversight: the
+ * sentence saying what is wrong with a value is the one sentence a native control
+ * already gets right in the reader's own language for free, because the browser
+ * writes it, so the `required` and `type` attributes this Block forwards are the
+ * error path and a per-field message from the caller is composed beside `Field`
+ * rather than inside this Block. The cost is named: a consumer whose validation
+ * rules are its own rather than the platform's has no seam here, and the answer is
+ * that it validates in its handler and puts the message in `status`, which is one
+ * sentence about all the fields rather than one per field.
+ *
+ * **Nothing here validates anything.** There is no address format check, no message
+ * length, no required consent and no spam rule. Each of those is a decision about
+ * the caller's product and its data, and a Block that guessed one would refuse a
+ * reader on the caller's behalf. What Prism does with `status` is refuse a second
+ * press: while the state reads `sending` the submit control is disabled, because a
+ * second press while the first request is in flight is a duplicate enquiry a
+ * support inbox cannot merge. That is the whole of Prism's reading of the state,
+ * and it is stated here because the alternative is a Block that has begun to have
+ * opinions about the request.
+ *
+ * It is a client Component, and the reason is the handler rather than the state.
+ * `onSubmit` is a function, a function is a piece of state, and state is a client
+ * module: a server component cannot hand an event handler down to a `<form>`, so a
+ * caller rendering this from a server component gets a form that submits and calls
+ * nothing. The rest of the rendering is a section and five controls, which is the
+ * price of the argument above and not a claim about what else this Block might do.
+ */
+export function Contact01({ eyebrow, title, description, onSubmit, fields, submitLabel, consent, address, variant = 'split', status, headingLevel = 'h2', className, }) {
+    const generated = useId();
+    const sending = status?.state === 'sending';
+    for (const field of fields)
+        assertField(field);
+    /*
+     * The values are read out of the form rather than out of any prop, because a
+     * contact form is uncontrolled by nature: there are as many fields as the caller
+     * declared and no state to hold them in. The keys are the caller's own `id`s, so
+     * the record that arrives is shaped like the declaration that produced it, and a
+     * caller that renames a field in one place renames it in one place.
+     */
+    const handleSubmit = (event) => {
+        event.preventDefault();
+        const read = new FormData(event.currentTarget);
+        const next = {};
+        for (const field of fields) {
+            const one = read.get(field.id);
+            if (typeof one === 'string')
+                next[field.id] = one;
+        }
+        onSubmit(next);
+    };
+    return (_jsx(Section, { "data-slot": "contact-01", className: cn(className), children: _jsxs("div", { "data-slot": "contact-01-body", className: "flex flex-col gap-8", children: [_jsx(SectionHeading, { eyebrow: eyebrow, title: title, description: description, align: "left", as: headingLevel }), _jsxs("div", { "data-slot": "contact-01-columns", "data-variant": variant, className: cn('grid items-start gap-10', variant === 'split' ? 'lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)] lg:gap-14' : null), children: [_jsxs("form", { "data-slot": "contact-01-form", onSubmit: handleSubmit, className: "flex w-full max-w-measure flex-col gap-4", children: [fields.map((field) => {
+                                    const controlId = `${generated}-${field.id}`;
+                                    const descriptionId = `${controlId}-description`;
+                                    return (_jsxs(Field, { "data-slot": "contact-01-field", "data-field": field.type, children: [_jsx(FieldLabel, { htmlFor: controlId, children: field.label }), field.type === 'textarea' ? (_jsx(Textarea, { id: controlId, name: field.id, rows: 4, placeholder: field.placeholder, required: field.required, "aria-describedby": field.description === undefined ? undefined : descriptionId })) : field.type === 'select' ? (_jsx(NativeSelect, { id: controlId, name: field.id, required: field.required, "aria-describedby": field.description === undefined ? undefined : descriptionId, children: field.options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value))) })) : (_jsx(Input, { id: controlId, name: field.id, type: field.type, placeholder: field.placeholder, autoComplete: field.autoComplete, required: field.required, "aria-describedby": field.description === undefined ? undefined : descriptionId })), field.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: field.description }))] }, field.id));
+                                }), consent === undefined ? null : (_jsx("p", { "data-slot": "contact-01-consent", className: "text-muted-foreground text-sm", children: consent })), _jsxs("div", { "data-slot": "contact-01-actions", className: "flex flex-col gap-3", children: [_jsx(Button, { "data-slot": "contact-01-submit", type: "submit", disabled: sending, className: "self-start", children: submitLabel }), _jsx(LiveRegion, { politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: sending, className: "text-sm", children: status?.message })] })] }), address === undefined ? null : (
+                        /*
+                         * An `address` element, because that is what this is: contact
+                         * information for the organisation, which is what the element names and
+                         * which a `<div>` does not. The platform renders it in italics and no
+                         * token in this stylesheet resets that, so the one display utility
+                         * restores the reading type. It is here rather than in a token
+                         * because an italic address is a platform default rather than a design
+                         * decision, and because the reset belongs on every element that draws
+                         * postal lines: this one and `contact-page`'s office rows, which is why
+                         * it is written out twice rather than pushed into the base layer, since
+                         * a base reset for one element a package happens to draw is a decision
+                         * about the platform default made in a place no reader looks.
+                         */
+                        _jsxs("address", { "data-slot": "contact-01-address", className: "text-muted-foreground flex w-full max-w-measure-narrow flex-col gap-4 not-italic", children: [address.lines.map((line) => (_jsx("span", { "data-slot": "contact-01-address-line", className: "block", children: line }, line))), address.email === undefined ? null : (
+                                /*
+                                 * A `CtaLink` and not a bare anchor, so the link carries the focus
+                                 * ring, the hover state and the announced role of one, and so the
+                                 * address is in the `href` where a reader can copy it rather than
+                                 * being the only words on the control. The words are the caller's,
+                                 * and the union on `Contact01Address` is what refuses to draw this
+                                 * one at all without them.
+                                 */
+                                _jsx(CtaLink, { "data-slot": "contact-01-email", href: `mailto:${address.email}`, variant: "ghost", size: "sm", className: "self-start", children: address.emailLabel })), address.hours === undefined ? null : (_jsx("div", { "data-slot": "contact-01-hours", className: "flex flex-col gap-2 text-sm", children: address.hours }))] }))] })] }) }));
+}
+export default Contact01;

package/dist/blocks/contact-01/index.d.ts

@@ -0,0 +1,3 @@
+export { Contact01, default } from './contact.js';
+export type { Contact01Address, Contact01Option, Contact01Props, Contact01Status, ContactField, ContactValue, } from './contact.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/contact-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/contact-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAM9C,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,WAAW,CAAA"}

package/dist/blocks/contact-01/index.js

@@ -0,0 +1 @@
+export { Contact01, default } from './contact.js';