@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -0,0 +1,357 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The five controls a provisioning run can ask a reader to fill in.
+ *
+ * A closed set, and the closure is the point, for the reason `ContactField`
+ * gives at full length: the controls are this Block's, so the field declaration is
+ * data and Prism supplies none of it. A run that is committed in three steps and
+ * four that is committed in one want the same Component, and a provisioning
+ * question that needs a date picker or a file, or a set of radio buttons whose
+ * options each carry their own description, is a caller's own surface composed
+ * beside this one rather than a sixth arm here. The cost is named rather than
+ * hidden: a consumer whose step needs a control Prism does not draw cannot reach
+ * it through this type, and the answer is a step with no fields plus the control
+ * the caller composes into `actions`.
+ */
+export type ProvisioningFieldType = 'text' | 'email' | 'number' | 'select' | 'textarea';
+/**
+ * One choice in a `select` field, and nothing else.
+ *
+ * A native `<option>` holds text and nothing more, which is the whole reason a
+ * provisioning step'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 this Block does not pretend otherwise.
+ */
+export type ProvisioningOption = {
+    /** What the run records 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 provisioning 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 `required?: boolean` leaves a caller who passed nothing unable to say which
+ * of the two they meant.
+ *
+ * The field's value is not here. A run collects what the reader typed and hands
+ * the whole record over at the commit, so there is nothing for a caller to hold
+ * between two steps: a step is mounted, filled and unmounted, and the values
+ * travel in the Block's own state, which is why this is a client Component.
+ */
+type ProvisioningFieldBase = {
+    /** 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 commit the run 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 run, 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 run's fields are the caller's
+ * declaration and 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 and looks
+ * answered only because the control is there and focusable. A `options?: string[]`
+ * on one type would typecheck the defect and leave only a diagnostic at run time
+ * to 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 building 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 ProvisioningField = (ProvisioningFieldBase & {
+    type: 'select';
+    /** The choices, in the order the reader should meet them. */
+    options: readonly ProvisioningOption[];
+}) | (ProvisioningFieldBase & {
+    type: 'text' | 'email' | 'number' | 'textarea';
+    /** A select with no options is a question nobody can answer, so it is not one here. */
+    options?: never;
+});
+/**
+ * One step of a run: what it is called, what happens there, and what the reader is
+ * asked for while they are on it.
+ *
+ * `fields` may be empty, and that is a real shape rather than a gap. The last step
+ * of a checkout has no fields on it: it is the review, and what it carries is the
+ * caller's own confirmation under `description` plus the control that commits. An
+ * empty list is that step, so this Block draws a step with a name, a description
+ * and a control rather than an empty form, which is a form a reader cannot fill
+ * and a page that looks broken.
+ */
+export type ProvisioningStep = {
+    /** A stable key for the step, and what `onNext` and `onBack` report. */
+    id: string;
+    /** What the step is called, in the caller's own words. */
+    name: string;
+    /**
+     * The line under the step's name, for whatever the caller wants said about it.
+     *
+     * A node, because the honest line on a review step is the summary of everything
+     * the reader just entered, with a link in it, and a `string` would force a
+     * flattening that loses whichever of those it could not hold.
+     */
+    description?: ReactNode;
+    /**
+     * What the reader is asked for on this step, in the order they should meet it.
+     *
+     * A list and not a fixed set, for the reason `Contact01` states in full: a
+     * provisioning run with a fixed set of fields is a run that decides what a reader
+     * may be asked, and the decision is invisible in a review because the rendered
+     * form looks complete.
+     */
+    fields: readonly ProvisioningField[];
+};
+/**
+ * Everything the reader typed, keyed by the caller's own field ids.
+ *
+ * A record and not a fixed shape, and the reason is that the keys are facts about
+ * the caller's run rather than about what a provisioning form is made of. The
+ * value type is `string` because the five control types here all submit strings,
+ * and a run that collects a file or a set of nodes is a different surface, which
+ * is what `Bundle01` is for.
+ */
+export type ProvisioningValue = 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 form Block in
+ * this package states: a success sentence this package wrote would be inherited
+ * verbatim by every consumer, and a provisioning run has more outcomes than any
+ * other form here, from a run that is queued to a run that is refused because the
+ * estate is full, a run that failed on one node of forty, and a run that is still
+ * rolling out an hour later.
+ */
+export type Provisioning01Status = {
+    /** Which of the four the run is in. Read by the Block for three things only. */
+    state: 'idle' | 'working' | 'done' | 'error';
+    /** The words for that state, in the product's own voice. */
+    message: ReactNode;
+};
+/** The props a Provisioning01 takes. Every string in this Block is one of them. */
+export type Provisioning01Props = {
+    /** The short line above the title, usually what the product is. */
+    eyebrow?: ReactNode;
+    /** The heading. Required, because a run 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;
+    /**
+     * The steps of the run, in the order they happen.
+     *
+     * Order is the caller's and it is a claim: this is a route through a run, and a
+     * list in an order the run does not have is a wrong diagram rather than a layout
+     * problem. The rail above the form says "steps" to every reader and to every
+     * crawler, so the order is the strongest claim this Block makes.
+     */
+    steps: readonly ProvisioningStep[];
+    /**
+     * Which step the reader opens on, zero based.
+     *
+     * Optional and clamped, and both halves of that matter. Clamped because a caller
+     * whose run is resumed at step two after a reload passes a number that can be off
+     * by one when the run grew a step, and a form that renders nothing at all because
+     * the index is past the end is a form the reader cannot get out of. Optional
+     * because a run that has not started opens on its first step, and the first step
+     * is the only answer a Block can give without knowing the run.
+     *
+     * It is read once, on mount. A later change to `initial` does not move the
+     * reader, and that is stated rather than hidden: a multi-step form that follows a
+     * changing prop is a form that moves under a reader who is typing in it, and the
+     * caller who wants to move the reader has the back and next controls for it.
+     */
+    initial?: number;
+    /**
+     * Called with the step being left and the step being entered, when the reader
+     * presses next.
+     *
+     * Optional, and a notification rather than a gate. The reader advances whatever
+     * this function says, because a run whose next control can be refused by a
+     * handler is a run whose step list is not the route: the caller validates, and
+     * the honest response to a field the caller will not accept is the caller's own
+     * `status`, which puts a sentence under the control the reader can act on.
+     */
+    onNext?: (from: string, to: string) => void;
+    /**
+     * Called with the step being left and the step being entered, when the reader
+     * presses back.
+     *
+     * Optional, and optional for a different reason than `onNext`: going back is
+     * always allowed, so a caller rarely has anything to say about it. A caller whose
+     * product discards a step's answers on the way back passes a handler here that
+     * does its own clearing, and the values it clears are the Block's own state.
+     */
+    onBack?: (from: string, to: string) => void;
+    /** The words on the control that returns to the previous step. */
+    backLabel: string;
+    /**
+     * The words on the control that moves to the next step.
+     *
+     * Required, and a `string` because it is one name a reader sees once per step
+     * rather than a sentence about the step. "Continue", "Next" and "Review order"
+     * are three products' decisions and the cell has room for whichever one is yours.
+     */
+    nextLabel: string;
+    /**
+     * The words on the control that commits the run, drawn on the last step.
+     *
+     * Required rather than derived from `nextLabel`, because the last step is not a
+     * continuation: it is the one press that starts something irreversible on a
+     * reader's estate. A reader who sees "Continue" on the control that provisions
+     * four nodes has been told the wrong thing about the only button on the page
+     * that matters, so the words are the caller's and they are required.
+     */
+    confirmLabel: string;
+    /**
+     * Called with everything the reader typed, when they commit.
+     *
+     * **Required, and the requirement is the design.** `onConfirm` is the only thing
+     * this Block does with what it collected, and there is no arm of this component
+     * in which a run is filled in 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 gathers a reader's configuration for four consumers and then
+     * discards it without telling anyone. This Block also sends nothing: what the run
+     * does with the record is the caller's product, and a consumer who already has a
+     * transport passes it straight in.
+     */
+    onConfirm: (value: ProvisioningValue) => void;
+    /**
+     * What the reader is told happens to what they typed.
+     *
+     * Optional here, and the difference from `Waitlist01` is the fact rather than an
+     * inconsistency. A waitlist holds an address, and a jurisdiction may require the
+     * disclosure to be there; a provisioning run holds a configuration that becomes
+     * infrastructure, so what the caller usually needs to say is narrower and
+     * specific: what will be created, that it bills, and that it can be removed. That
+     * sentence belongs on the last step, beside the control that commits, which is
+     * where `terms` is drawn. A caller whose counsel asks for one passes it.
+     */
+    terms?: ReactNode;
+    /**
+     * The outcome of the caller's own request, drawn in a live region and announced.
+     *
+     * A prop and never an internal state Prism writes, and it is also where a caller
+     * puts the sentence that says a step will not be accepted, which is the honest
+     * answer to a `onNext` that has decided the reader may not move on.
+     */
+    status?: Provisioning01Status;
+    /** 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 multi-step run that commits something: a rail, the current step's fields, a
+ * back and a next control, and a confirmation the caller supplies.
+ *
+ * **This is a checkout, and the pattern is identical, so the translation is
+ * stated rather than implied.** A checkout is a sequence of steps, each with its
+ * own fields, a back, a next, and a commit at the end. A provisioning run is that
+ * same sequence with the same controls, and the only thing that changes is what is
+ * committed at the end: a checkout commits a payment, and this commits a
+ * configuration onto an estate. A storefront catalogue sells parcels and this one
+ * does not, so nothing on this page is a parcel, a basket or a shopper, and the
+ * four consumer products that install this Block each have their own nouns for
+ * what is being set up. The frame is the storefront's because the frame is right:
+ * a sequence of steps with a commit at the end is the shape of both, and the
+ * alternative, a Block that invented its own arrangement, would be a worse
+ * version of a form a reader already knows how to use.
+ *
+ * **The step state is derived from the current index, and `onSelect` is not a
+ * prop, and that is the one decision a checkout Block has to get right.** A
+ * multi-step form whose reader can jump to step four is a form that can submit an
+ * unvalidated step: the reader lands on the commit step with three required fields
+ * behind them they never saw, and the run is committed with three values this
+ * Block never asked for. Every stage of that failure is invisible in a review,
+ * because the form renders correctly in every state; it is visible only in use, on
+ * the screen where a reader has pressed the control that provisions four nodes and
+ * a required field they were never shown is blank. The obvious fix is a rail the
+ * reader can click, and it is refused here for the reason `Steps` states at
+ * length: a rail that is also a control is a control containing the state that
+ * says where the reader is, and a caller who wants to reach a step the reader has
+ * not earned passes `initial`, which is a number and not an affordance. The
+ * rejected alternative of letting a caller override a step's state is refused for
+ * the same reason, and `onSelect` is the better of the two refusals because it is
+ * the one that cannot be reintroduced by a prop.
+ *
+ * **`initial` is a number and it is clamped, and both halves are load-bearing.**
+ * A number rather than a step id, because a run is a sequence and a sequence is
+ * indexed, and a caller whose step ids change between deployments would otherwise
+ * arrive with a string this Block cannot place. Clamped, because a caller who
+ * resumes a run at step two after a reload holds a number that can be off by one
+ * when the run grew a step, and a form that renders nothing because the index is
+ * past the end is a form the reader cannot get out of. It is read once on mount, and
+ * that is stated rather than hidden: a multi-step form that follows a changing prop
+ * moves under a reader who is typing in it.
+ *
+ * **A step with no fields renders a confirmation and a control, not an empty
+ * form.** The last step of a checkout has no fields on it: it is the review, and
+ * what it carries is the caller's own `description` plus the control that commits.
+ * A fieldless step that drew an empty form would be a form a reader cannot fill and
+ * a page that looks broken, and the reader who sees it concludes the product is
+ * broken rather than that the step is a review. So the fields area is omitted
+ * entirely, the step's `description` is the body of the step, and `terms` is drawn
+ * beside the control that commits, which is the one place a reader is about to
+ * make something irreversible and the one place a disclosure belongs.
+ *
+ * **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 has to be right on every
+ * field, and a Block that drew a bespoke row per type would have five places to get
+ * it wrong. What `field.tsx` offers and this Block does not draw is `FieldError`,
+ * and the omission is a decision: 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, because the browser writes it, so the `required` and `type` attributes
+ * this Block forwards are the error path, and a caller with validation rules of
+ * its own validates in `onConfirm` and puts the message in `status`, which is one
+ * sentence about the run rather than one per field.
+ *
+ * **Nothing here validates anything.** There is no address format check, no
+ * minimum count, no cross-field rule, and no refusal to advance. Each of those is
+ * a decision about the caller's product, 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 `working` both controls are disabled, because a
+ * second press while the first run is in flight is a second set of nodes on an
+ * estate that may already have the first. That is the whole of Prism's reading of
+ * the state, and it is stated because the alternative is a Block that has begun to
+ * have opinions about the run.
+ *
+ * It is a client Component, and there are two reasons rather than one, and both
+ * are load-bearing. The handlers are the first: `onConfirm`, `onNext` and
+ * `onBack` are functions, a function is a piece of state, and state is a client
+ * module, so a server Component cannot hand an event handler down to a `<form>`. The
+ * second is the values themselves: a run holds what the reader typed across steps
+ * that are not all mounted at once, so the record that arrives at `onConfirm` has
+ * to survive a step boundary, and a server render has nowhere to keep it. That
+ * second reason is the one that decides the shape, because it is why the values
+ * live here and not in the caller's state: the caller gets the whole record at the
+ * commit and is not asked to thread a controlled value through five fields it does
+ * not own.
+ */
+export declare function Provisioning01({ eyebrow, title, description, steps, initial, onNext, onBack, backLabel, nextLabel, confirmLabel, onConfirm, terms, status, headingLevel, className, }: Provisioning01Props): import("react").JSX.Element;
+export default Provisioning01;
+//# sourceMappingURL=provisioning.d.ts.map

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

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

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

@@ -0,0 +1,230 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useState } from 'react';
+import { Button } from '../../components/ui/button.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, childLevel, } from '../../components/ui/section.js';
+import { Steps } from '../../components/ui/steps.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 a question that looks answered because the control is there and
+ * focusable is worse than one that is visibly missing.
+ */
+function blankList(value) {
+    return value === undefined || value.length === 0;
+}
+/**
+ * The two ways a caller's field declaration can be a form nobody can fill, and
+ * the two ways a caller's step list can be a run nobody can finish, 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.
+ *
+ * A nameless control is announced as "text field", which is the one name every
+ * other field on the run shares. A select with nothing in it is a question with no
+ * answer. A run with no steps is a frame with no route, which is the one this
+ * package refuses to draw rather than answering: a reader who arrives at a
+ * provisioning form with no steps has been shown a promise with no content behind
+ * it. Each message reaches a developer in a console and never a reader, which is
+ * what makes it a refusal rather than copy.
+ */
+function assertRun(steps, backLabel, nextLabel, confirmLabel) {
+    if (steps.length === 0) {
+        throw new Error('Provisioning01: steps is empty, so the rail would be a row of nothing above a form with no route ' +
+            'through it, and the control at the bottom would commit a run of no steps. Pass the steps the run ' +
+            'actually has.');
+    }
+    for (const step of steps) {
+        for (const field of step.fields) {
+            if (blank(field.label)) {
+                throw new Error(`Provisioning01: the field "${field.id}" on the step "${step.id}" declares no label, so the ` +
+                    'control would be announced with no name and two fields on this run would be announced ' +
+                    'identically. Every control this Block draws is named by its label, so there is no fallback.');
+            }
+            if (field.type === 'select' && blankList(field.options)) {
+                throw new Error(`Provisioning01: the field "${field.id}" on the step "${step.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. Pass the choices, or declare the field as a text field and check the answer in your ' +
+                    'own handler.');
+            }
+        }
+    }
+    if (blank(backLabel) || blank(nextLabel) || blank(confirmLabel)) {
+        throw new Error('Provisioning01: one of backLabel, nextLabel and confirmLabel is empty, so a control on this run ' +
+            'would be drawn with no words on it, and a button with no name is announced as "button" whatever ' +
+            'it does. Pass the words your readers use for all three.');
+    }
+}
+/**
+ * The step the rail is on, and the reason the derivation is a clamp rather than a
+ * lookup.
+ *
+ * There is exactly one current step in a run, and it is the one the reader is on,
+ * so the index is the whole of the position. `Steps` clamps as well, and the clamp
+ * is here as well, and the duplication is deliberate: `Steps` throws when the
+ * resolved states are not exactly one current, and it can only be reached through
+ * an index this Block has already resolved, so a run that opened on step five of
+ * three is corrected before the rail is asked to draw rather than throwing a
+ * diagnostic about a value the caller never passed.
+ */
+function stepAt(steps, wanted) {
+    if (steps.length === 0)
+        return 0;
+    if (!Number.isFinite(wanted))
+        return 0;
+    return Math.min(Math.max(Math.trunc(wanted), 0), steps.length - 1);
+}
+/**
+ * A multi-step run that commits something: a rail, the current step's fields, a
+ * back and a next control, and a confirmation the caller supplies.
+ *
+ * **This is a checkout, and the pattern is identical, so the translation is
+ * stated rather than implied.** A checkout is a sequence of steps, each with its
+ * own fields, a back, a next, and a commit at the end. A provisioning run is that
+ * same sequence with the same controls, and the only thing that changes is what is
+ * committed at the end: a checkout commits a payment, and this commits a
+ * configuration onto an estate. A storefront catalogue sells parcels and this one
+ * does not, so nothing on this page is a parcel, a basket or a shopper, and the
+ * four consumer products that install this Block each have their own nouns for
+ * what is being set up. The frame is the storefront's because the frame is right:
+ * a sequence of steps with a commit at the end is the shape of both, and the
+ * alternative, a Block that invented its own arrangement, would be a worse
+ * version of a form a reader already knows how to use.
+ *
+ * **The step state is derived from the current index, and `onSelect` is not a
+ * prop, and that is the one decision a checkout Block has to get right.** A
+ * multi-step form whose reader can jump to step four is a form that can submit an
+ * unvalidated step: the reader lands on the commit step with three required fields
+ * behind them they never saw, and the run is committed with three values this
+ * Block never asked for. Every stage of that failure is invisible in a review,
+ * because the form renders correctly in every state; it is visible only in use, on
+ * the screen where a reader has pressed the control that provisions four nodes and
+ * a required field they were never shown is blank. The obvious fix is a rail the
+ * reader can click, and it is refused here for the reason `Steps` states at
+ * length: a rail that is also a control is a control containing the state that
+ * says where the reader is, and a caller who wants to reach a step the reader has
+ * not earned passes `initial`, which is a number and not an affordance. The
+ * rejected alternative of letting a caller override a step's state is refused for
+ * the same reason, and `onSelect` is the better of the two refusals because it is
+ * the one that cannot be reintroduced by a prop.
+ *
+ * **`initial` is a number and it is clamped, and both halves are load-bearing.**
+ * A number rather than a step id, because a run is a sequence and a sequence is
+ * indexed, and a caller whose step ids change between deployments would otherwise
+ * arrive with a string this Block cannot place. Clamped, because a caller who
+ * resumes a run at step two after a reload holds a number that can be off by one
+ * when the run grew a step, and a form that renders nothing because the index is
+ * past the end is a form the reader cannot get out of. It is read once on mount, and
+ * that is stated rather than hidden: a multi-step form that follows a changing prop
+ * moves under a reader who is typing in it.
+ *
+ * **A step with no fields renders a confirmation and a control, not an empty
+ * form.** The last step of a checkout has no fields on it: it is the review, and
+ * what it carries is the caller's own `description` plus the control that commits.
+ * A fieldless step that drew an empty form would be a form a reader cannot fill and
+ * a page that looks broken, and the reader who sees it concludes the product is
+ * broken rather than that the step is a review. So the fields area is omitted
+ * entirely, the step's `description` is the body of the step, and `terms` is drawn
+ * beside the control that commits, which is the one place a reader is about to
+ * make something irreversible and the one place a disclosure belongs.
+ *
+ * **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 has to be right on every
+ * field, and a Block that drew a bespoke row per type would have five places to get
+ * it wrong. What `field.tsx` offers and this Block does not draw is `FieldError`,
+ * and the omission is a decision: 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, because the browser writes it, so the `required` and `type` attributes
+ * this Block forwards are the error path, and a caller with validation rules of
+ * its own validates in `onConfirm` and puts the message in `status`, which is one
+ * sentence about the run rather than one per field.
+ *
+ * **Nothing here validates anything.** There is no address format check, no
+ * minimum count, no cross-field rule, and no refusal to advance. Each of those is
+ * a decision about the caller's product, 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 `working` both controls are disabled, because a
+ * second press while the first run is in flight is a second set of nodes on an
+ * estate that may already have the first. That is the whole of Prism's reading of
+ * the state, and it is stated because the alternative is a Block that has begun to
+ * have opinions about the run.
+ *
+ * It is a client Component, and there are two reasons rather than one, and both
+ * are load-bearing. The handlers are the first: `onConfirm`, `onNext` and
+ * `onBack` are functions, a function is a piece of state, and state is a client
+ * module, so a server Component cannot hand an event handler down to a `<form>`. The
+ * second is the values themselves: a run holds what the reader typed across steps
+ * that are not all mounted at once, so the record that arrives at `onConfirm` has
+ * to survive a step boundary, and a server render has nowhere to keep it. That
+ * second reason is the one that decides the shape, because it is why the values
+ * live here and not in the caller's state: the caller gets the whole record at the
+ * commit and is not asked to thread a controlled value through five fields it does
+ * not own.
+ */
+export function Provisioning01({ eyebrow, title, description, steps, initial = 0, onNext, onBack, backLabel, nextLabel, confirmLabel, onConfirm, terms, status, headingLevel = 'h2', className, }) {
+    const generated = useId();
+    const [at, setAt] = useState(() => stepAt(steps, initial));
+    const [values, setValues] = useState({});
+    assertRun(steps, backLabel, nextLabel, confirmLabel);
+    // Read once, on mount, so a caller whose steps change mid-run is not moved under
+    // a reader who is typing. See `initial` for the argument.
+    const index = stepAt(steps, at);
+    const step = steps[index];
+    const last = index === steps.length - 1;
+    const working = status?.state === 'working';
+    const done = status?.state === 'done';
+    const move = (next, from, to, notify) => {
+        setAt(stepAt(steps, next));
+        notify?.(from, to);
+    };
+    const rail = steps.map((one) => ({ label: one.name }));
+    /*
+      The step's own heading, and the level is derived rather than chosen. A step is
+      a part of this section and not a section of its own, so it nests one level
+      below the heading that introduces the run, and a run composed under an `h3` on
+      a page whose sections are `h3` carries its step headings to `h4` with it. A
+      literal `h3` would be right exactly once, at the nesting depth it was written
+      for, and every Block that draws a titled part of itself has the same property.
+    */
+    const StepHeading = childLevel(headingLevel);
+    return (_jsx(Section, { "data-slot": "provisioning-01", className: cn(className), children: _jsxs("div", { "data-slot": "provisioning-01-body", className: "flex flex-col gap-8", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx("div", { "data-slot": "provisioning-01-rail", className: "border-border border-b pb-8", children: _jsx(Steps, { steps: rail, current: index }) }), _jsxs("form", { "data-slot": "provisioning-01-form", className: "flex w-full max-w-measure flex-col gap-6", onSubmit: (event) => {
+                        event.preventDefault();
+                        onConfirm(values);
+                    }, children: [_jsx(StepHeading, { "data-slot": "provisioning-01-step", className: "text-lg font-semibold tracking-tight", children: step.name }), step.description === undefined ? null : (_jsx("div", { "data-slot": "provisioning-01-step-description", className: "text-muted-foreground text-pretty text-sm", children: step.description })), step.fields.length === 0 ? null : (_jsx("div", { "data-slot": "provisioning-01-fields", className: "flex flex-col gap-4", children: step.fields.map((field) => {
+                                const controlId = `${generated}-${field.id}`;
+                                const descriptionId = `${controlId}-description`;
+                                return (_jsxs(Field, { "data-slot": "provisioning-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, value: values[field.id] ?? '', onChange: (event) => setValues((held) => ({ ...held, [field.id]: event.target.value })), "aria-describedby": field.description === undefined ? undefined : descriptionId })) : field.type === 'select' ? (_jsx(NativeSelect, { id: controlId, name: field.id, required: field.required, value: values[field.id] ?? '', onChange: (event) => setValues((held) => ({ ...held, [field.id]: event.target.value })), "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, value: values[field.id] ?? '', onChange: (event) => setValues((held) => ({ ...held, [field.id]: event.target.value })), "aria-describedby": field.description === undefined ? undefined : descriptionId })), field.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: field.description }))] }, field.id));
+                            }) })), terms === undefined || !last ? null : (_jsx("p", { "data-slot": "provisioning-01-terms", className: "text-muted-foreground text-pretty text-sm", children: terms })), _jsxs("div", { "data-slot": "provisioning-01-controls", className: "flex flex-col gap-3 sm:flex-row-reverse sm:items-center sm:justify-start", children: [last ? (_jsx(Button, { "data-slot": "provisioning-01-confirm", type: "submit", disabled: working || done, className: "sm:order-2", children: confirmLabel })) : (_jsx(Button, { "data-slot": "provisioning-01-next", type: "button", disabled: working, className: "sm:order-2", onClick: () => {
+                                        const to = steps[index + 1];
+                                        if (to === undefined)
+                                            return;
+                                        move(index + 1, step.id, to.id, onNext);
+                                    }, children: nextLabel })), index === 0 ? null : (_jsx(Button, { "data-slot": "provisioning-01-back", type: "button", variant: "outline", disabled: working, className: "sm:order-1", onClick: () => {
+                                        const to = steps[index - 1];
+                                        if (to === undefined)
+                                            return;
+                                        move(index - 1, step.id, to.id, onBack);
+                                    }, children: backLabel }))] }), _jsx(LiveRegion, { politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: working, className: "text-sm", children: status?.message })] })] }) }));
+}
+export default Provisioning01;

package/dist/blocks/quick-view-01/index.d.ts

@@ -0,0 +1,3 @@
+export { QuickView01, default } from './quick-view.js';
+export type { QuickView01Fact, QuickView01Props, QuickView01Size } from './quick-view.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/quick-view-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/quick-view-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAInD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA"}

package/dist/blocks/quick-view-01/index.js

@@ -0,0 +1 @@
+export { QuickView01, default } from './quick-view.js';