@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/form-wizard.d.ts

@@ -0,0 +1,251 @@
+import { type ReactNode } from 'react';
+/**
+ * One thing wrong with a step, in the caller's own words.
+ *
+ * `field` is the `id` of the control the message belongs to and it is what makes a
+ * step's refusal actionable in the same way `FormDialog`'s summary is: an entry a
+ * reader cannot take to the control is a sentence they have to match by eye against
+ * a form they then have to read a second time.
+ */
+export type FormWizardIssue = {
+    /** The `id` of the control this message belongs to. */
+    field: string;
+    /** The message, in the product's own words. */
+    message: string;
+};
+/**
+ * One step of a sequence a reader passes through in order.
+ *
+ * `id` is required because a step's record is what a caller keys their own per-step
+ * state on, and because a sequence whose entries have no identity is a sequence
+ * whose saved answers have nowhere to live.
+ */
+export type FormWizardStep = {
+    /** A stable key for the step. */
+    id: string;
+    /**
+     * The step's name, in the words a reader would use about it in conversation.
+     *
+     * A `string` and not a node, and the reason is the rail: the same word is drawn
+     * in `Steps` at a width a step gets in a six-step row, and `Steps` states that a
+     * label has to survive that width. So one word serves the rail and the heading,
+     * which is also the right way round, because a rail saying "Billing details" and a
+     * heading saying `<strong>Billing</strong> details` is two names for one step.
+     */
+    label: string;
+    /** One line under the name saying what this step asks for, in plain words. */
+    description?: string;
+    /** The step's own controls. */
+    children?: ReactNode;
+    /**
+     * Called when the reader tries to leave this step forwards, given the step's own
+     * element.
+     *
+     * Optional per step rather than a rule on the whole sequence, and the reason is
+     * that a step which asks for nothing has nothing to refuse. A checkout's payment
+     * step validates and its review step does not, and one `validate` on the Component
+     * would have the caller write a branch per step to express what the absence of one
+     * already says.
+     *
+     * Returning issues refuses the move and nothing else. The caller is expected to
+     * set the step's own error state from the same source that produced them, because
+     * this Component cannot see the caller's controls and cannot mark them invalid.
+     */
+    validate?: (form: HTMLFormElement) => readonly FormWizardIssue[];
+};
+/**
+ * The props a FormWizard accepts.
+ *
+ * Two halves, and the split is the argument. The *progress rail* is `Steps`, and it
+ * is composed rather than redrawn: it is an ordered indicator of position, it
+ * derives three marks from one number, and it throws when the marks disagree, which
+ * is a stronger guarantee than any arrangement drawn here. The *gate* is this
+ * Component's own, and it exists because a rail that shows progress and a sequence
+ * that gates it are different jobs, and upstream ships the second as the first with
+ * the decision left out.
+ */
+export interface FormWizardProps {
+    /**
+     * The steps, in order.
+     *
+     * Required, and the order is the claim: a reader told these are steps is told
+     * there is a route through them, so a list passed in an order the process does not
+     * have is a wrong diagram rather than a layout problem. The same constraint
+     * `Steps` states, for the same reason.
+     */
+    steps: readonly FormWizardStep[];
+    /**
+     * The step the reader is on, counting from zero.
+     *
+     * Controlled and clamped, and clamped rather than optional for the reason
+     * `Steps` gives: a sequence with no position is a list and a list is a different
+     * Component. The clamp makes an off-by-one harmless, where the alternative was a
+     * throw on a value that is only wrong by one.
+     */
+    current: number;
+    /**
+     * Called when the reader moves, given the step's index and which way they asked.
+     *
+     * Required, and the second argument is there because forward and back are not the
+     * same move and a caller whose rules differ by direction has to be able to tell
+     * them apart without reading the index. A refused forward press arrives here as
+     * nothing at all, so a caller who wants to know their validation ran hears it from
+     * the refusal list rather than from this callback.
+     */
+    onStepChange: (index: number, direction: 'forward' | 'back') => void;
+    /**
+     * The sequence's own rules, given the step the reader is on.
+     *
+     * Required and separate from each step's own `validate`, because there are two
+     * questions and one of them is not about a step. A step's rules ask whether *this*
+     * step is complete. This asks whether the sequence as a whole may be submitted,
+     * which is a check no individual step can make: a review step has nothing to
+     * validate locally and the whole sequence may still be un-submittable because the
+     * terms were not accepted three steps ago.
+     */
+    validate?: (index: number, form: HTMLFormElement) => readonly FormWizardIssue[];
+    /**
+     * The label of the control that goes back.
+     *
+     * Required and never defaulted, and the one label on this Component that is shown
+     * at every step: see the JSDoc for why back is the one direction a gate never
+     * closes.
+     */
+    backLabel: ReactNode;
+    /**
+     * The label of the control that goes forward, on every step but the last.
+     *
+     * Required, and separate from the last step's label because "Next" and "Finish"
+     * are two different claims about what the press does, and a sequence whose last
+     * control says "Next" has not told the reader it is the end.
+     */
+    nextLabel: ReactNode;
+    /**
+     * The label of the control on the last step, which submits rather than advances.
+     *
+     * Required, and a separate prop rather than a computed one because both labels are
+     * a product's two words and this package knows neither of them.
+     */
+    finishLabel: ReactNode;
+    /**
+     * The heading above the refusal.
+     *
+     * Required, and a heading rather than a sentence because the refusal list is a
+     * focus target and a reader who lands on it needs to know what they have landed on
+     * before they read the list.
+     */
+    blockedLabel: ReactNode;
+    /**
+     * The accessible name of the progress rail.
+     *
+     * Required, and the sequence's noun rather than this Component's: a page with a
+     * checkout and an onboarding wizard on it has two rails, and a reader moving
+     * between them is told nothing about which they are in.
+     */
+    progressLabel: string;
+    /**
+     * The accessible name of one control in the refusal list, given the field the
+     * issue belongs to.
+     *
+     * Required, and a function of the field rather than of the message for the reason
+     * every readable string here is one. It is also what lets an entry name the
+     * *control* rather than repeat the sentence beside it.
+     */
+    issueLabel: (field: string) => string;
+    /**
+     * The words for this sequence's keyboard model, read once when the reader lands on
+     * the step's region.
+     *
+     * Required, because a gated sequence is a place a reader can get stuck and the one
+     * thing they need while stuck is that going back is always allowed. One sentence
+     * for the whole sequence, since it is the same sentence at every step.
+     */
+    instructionsLabel: string;
+    /** The reader's own slot, for anything above or below the step's controls. */
+    children?: ReactNode;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * A sequence of steps where each one gates the way forward and none of them gates
+ * the way back.
+ *
+ * **This is not `Steps`, and the difference is a check rather than a drawing.**
+ * `Steps` is an ordered indicator of where a reader is: it derives three marks from
+ * one number, it marks the current step with `aria-current`, and it throws when the
+ * marks disagree, which is a stronger guarantee than any arrangement drawn here. It
+ * has no opinion at all about whether a reader may move, because showing a reader
+ * their position and deciding whether they may leave it are different jobs, and
+ * upstream ships the second as the first with the decision left out. A caller who
+ * wants a rail composes `Steps`; a caller who reaches for `Tabs` has picked the wrong
+ * Component, because a tab list is peer views of one subject and a wizard's steps are
+ * a route through it.
+ *
+ * **Back is always allowed, and that asymmetry is the whole Component.** Forward is
+ * gated, and the gate is the point: a wizard exists to stop a reader submitting a
+ * sequence with a hole in it, and a step's rules are how it knows there is one. Back
+ * is not, for a reason that is about the reader rather than about the data. A gated
+ * back control traps a reader in the very step they opened the wizard to escape:
+ * they have opened step two, found it asks for something they do not have, and
+ * pressing back does nothing either. No arrangement of the data makes that
+ * acceptable and the fix is not a better error message, it is that going back is
+ * always available. So the back control is drawn, named and operable at every step
+ * including the first, where it is inert rather than absent: a control that appears
+ * and disappears moves the row a reader is aiming at, and its absence on step one
+ * would be a claim that there is nothing before here, which is true and not worth a
+ * layout shift to say. On the first step it is `aria-disabled` rather than natively
+ * `disabled`, for the reason `LifecycleButton` gives: a natively disabled control
+ * leaves the tab order, so a reader tabs onto where it was, presses Enter and nothing
+ * happens with no announcement to explain it.
+ *
+ * **A refused forward move takes focus to the refusal and announces nothing else.**
+ * The same reasoning as `FormDialog`, and the two are kept consistent on purpose: a
+ * refusal is announced once, by a focus target the reader lands on and can read
+ * from, rather than by an alert *and* a focus move, which is one refusal heard twice
+ * in two voices. The list is a list of anchors, each carrying the field's own name
+ * with the message beneath it. Focus moves once per refusal rather than on every
+ * render, so a reader who tabs away and comes back is not dragged onto it again, and
+ * the Component holds no live region at all for the same reason: a permanently
+ * mounted one would announce the refusal a second time when the move commits.
+ *
+ * **The gate is the caller's and the drawing is Prism's.** Each step's own
+ * `validate` decides whether its step may be left forwards, and this Component
+ * refuses the move and draws what came back. It never marks a control invalid and
+ * never shows a message under one, because it cannot see the caller's form: the
+ * caller's fields are their own `Field`s and their own `Input`s, and reaching into
+ * them would be the override path this package refuses everywhere else. The cost is
+ * named rather than hidden: a caller has to render each message under its control as
+ * well as in the refusal list, and a caller who does only the first has a list a
+ * reader can follow and controls that do not say why. That is two renderings of one
+ * sentence, and it is the price of the caller owning the form.
+ *
+ * **Forward is gated twice over and the order matters.** The step's own rules run
+ * first, because they are about the reader's answers, and the sequence's own rules
+ * second, because they are about the submission. A step that fails its own rules
+ * never reaches the sequence's, which is what stops a reader being told their card
+ * was declined when the field they left empty was the problem.
+ *
+ * **The last step's control is a different prop and not a computed label.** `next`
+ * and `finish` are two claims about what the press does, and a sequence whose last
+ * control says "Next" has not told the reader it is the end, while one that says
+ * "Finish" and then opens step four has lied about something a reader will act on.
+ * Both are required and neither has a default, because this package does not know
+ * whether the product's word is "Continue", "Weiter" or "Siguiente".
+ *
+ * **`Steps` is composed at the position the rail belongs rather than inside a
+ * wrapper.** The reader sees the rail above the step, the step's own controls in the
+ * middle and the two directions below, and a wizard whose rail is somewhere else is a
+ * wizard whose progress is somewhere else in the reader's eye. The rail reads the
+ * same index the navigation moves, so the two cannot disagree about which step is
+ * current.
+ *
+ * **It is a client Component**, because a gate is a decision taken after the reader
+ * acts and the decision has to be able to refuse, and because every one of its value
+ * props is a function the caller hands it, which is a client-to-client boundary
+ * wherever it is written. What that costs is the price of every client control: a
+ * server Component may render one step's controls once, and what it may not do is let
+ * the reader move between them.
+ */
+declare function FormWizard({ steps, current, onStepChange, validate, backLabel, nextLabel, finishLabel, blockedLabel, progressLabel, issueLabel, instructionsLabel, children, className, }: FormWizardProps): import("react").JSX.Element;
+export { FormWizard };
+//# sourceMappingURL=form-wizard.d.ts.map

package/dist/components/ui/form-wizard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-wizard.d.ts","sourceRoot":"","sources":["../../../src/components/ui/form-wizard.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAM1E;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,SAAS,eAAe,EAAE,CAAA;CACjE,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,cAAc,EAAE,CAAA;IAChC;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;OAQG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,KAAK,IAAI,CAAA;IACpE;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,KAAK,SAAS,eAAe,EAAE,CAAA;IAC/E;;;;;;OAMG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB;;;;;;OAMG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB;;;;;OAKG;IACH,WAAW,EAAE,SAAS,CAAA;IACtB;;;;;;OAMG;IACH,YAAY,EAAE,SAAS,CAAA;IACvB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC;;;;;;;OAOG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,iBAAS,UAAU,CAAC,EAClB,KAAK,EACL,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,SAAS,GACV,EAAE,eAAe,+BA+NjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/form-wizard.js

@@ -0,0 +1,151 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { useEffect, useId, useRef, useState } from 'react';
+import { Button } from './button.js';
+import { Steps } from './steps.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A sequence of steps where each one gates the way forward and none of them gates
+ * the way back.
+ *
+ * **This is not `Steps`, and the difference is a check rather than a drawing.**
+ * `Steps` is an ordered indicator of where a reader is: it derives three marks from
+ * one number, it marks the current step with `aria-current`, and it throws when the
+ * marks disagree, which is a stronger guarantee than any arrangement drawn here. It
+ * has no opinion at all about whether a reader may move, because showing a reader
+ * their position and deciding whether they may leave it are different jobs, and
+ * upstream ships the second as the first with the decision left out. A caller who
+ * wants a rail composes `Steps`; a caller who reaches for `Tabs` has picked the wrong
+ * Component, because a tab list is peer views of one subject and a wizard's steps are
+ * a route through it.
+ *
+ * **Back is always allowed, and that asymmetry is the whole Component.** Forward is
+ * gated, and the gate is the point: a wizard exists to stop a reader submitting a
+ * sequence with a hole in it, and a step's rules are how it knows there is one. Back
+ * is not, for a reason that is about the reader rather than about the data. A gated
+ * back control traps a reader in the very step they opened the wizard to escape:
+ * they have opened step two, found it asks for something they do not have, and
+ * pressing back does nothing either. No arrangement of the data makes that
+ * acceptable and the fix is not a better error message, it is that going back is
+ * always available. So the back control is drawn, named and operable at every step
+ * including the first, where it is inert rather than absent: a control that appears
+ * and disappears moves the row a reader is aiming at, and its absence on step one
+ * would be a claim that there is nothing before here, which is true and not worth a
+ * layout shift to say. On the first step it is `aria-disabled` rather than natively
+ * `disabled`, for the reason `LifecycleButton` gives: a natively disabled control
+ * leaves the tab order, so a reader tabs onto where it was, presses Enter and nothing
+ * happens with no announcement to explain it.
+ *
+ * **A refused forward move takes focus to the refusal and announces nothing else.**
+ * The same reasoning as `FormDialog`, and the two are kept consistent on purpose: a
+ * refusal is announced once, by a focus target the reader lands on and can read
+ * from, rather than by an alert *and* a focus move, which is one refusal heard twice
+ * in two voices. The list is a list of anchors, each carrying the field's own name
+ * with the message beneath it. Focus moves once per refusal rather than on every
+ * render, so a reader who tabs away and comes back is not dragged onto it again, and
+ * the Component holds no live region at all for the same reason: a permanently
+ * mounted one would announce the refusal a second time when the move commits.
+ *
+ * **The gate is the caller's and the drawing is Prism's.** Each step's own
+ * `validate` decides whether its step may be left forwards, and this Component
+ * refuses the move and draws what came back. It never marks a control invalid and
+ * never shows a message under one, because it cannot see the caller's form: the
+ * caller's fields are their own `Field`s and their own `Input`s, and reaching into
+ * them would be the override path this package refuses everywhere else. The cost is
+ * named rather than hidden: a caller has to render each message under its control as
+ * well as in the refusal list, and a caller who does only the first has a list a
+ * reader can follow and controls that do not say why. That is two renderings of one
+ * sentence, and it is the price of the caller owning the form.
+ *
+ * **Forward is gated twice over and the order matters.** The step's own rules run
+ * first, because they are about the reader's answers, and the sequence's own rules
+ * second, because they are about the submission. A step that fails its own rules
+ * never reaches the sequence's, which is what stops a reader being told their card
+ * was declined when the field they left empty was the problem.
+ *
+ * **The last step's control is a different prop and not a computed label.** `next`
+ * and `finish` are two claims about what the press does, and a sequence whose last
+ * control says "Next" has not told the reader it is the end, while one that says
+ * "Finish" and then opens step four has lied about something a reader will act on.
+ * Both are required and neither has a default, because this package does not know
+ * whether the product's word is "Continue", "Weiter" or "Siguiente".
+ *
+ * **`Steps` is composed at the position the rail belongs rather than inside a
+ * wrapper.** The reader sees the rail above the step, the step's own controls in the
+ * middle and the two directions below, and a wizard whose rail is somewhere else is a
+ * wizard whose progress is somewhere else in the reader's eye. The rail reads the
+ * same index the navigation moves, so the two cannot disagree about which step is
+ * current.
+ *
+ * **It is a client Component**, because a gate is a decision taken after the reader
+ * acts and the decision has to be able to refuse, and because every one of its value
+ * props is a function the caller hands it, which is a client-to-client boundary
+ * wherever it is written. What that costs is the price of every client control: a
+ * server Component may render one step's controls once, and what it may not do is let
+ * the reader move between them.
+ */
+function FormWizard({ steps, current, onStepChange, validate, backLabel, nextLabel, finishLabel, blockedLabel, progressLabel, issueLabel, instructionsLabel, children, className, }) {
+    const generated = useId();
+    const instructionsId = `${generated}-instructions`;
+    const labelId = `${generated}-label`;
+    const blockedId = `${generated}-blocked`;
+    const formRef = useRef(null);
+    const refusedRef = useRef(null);
+    const [refused, setRefused] = useState([]);
+    const total = steps.length;
+    const at = total === 0 ? 0 : Math.min(Math.max(Math.trunc(current), 0), total - 1);
+    const step = steps[at];
+    const last = at === total - 1;
+    const leave = (direction) => {
+        const form = formRef.current;
+        if (form === null)
+            return;
+        if (direction === 'back') {
+            // The asymmetry, in one branch. Nothing is checked, nothing is refused, and
+            // the callback fires whatever this step's rules would have said, because a
+            // reader who has opened the wrong step has to be able to get out of it. The
+            // refusal is cleared rather than left standing, because a message about step
+            // two shown while the reader reads step one is a message about a form they
+            // are no longer in.
+            setRefused([]);
+            if (at > 0)
+                onStepChange(at - 1, 'back');
+            return;
+        }
+        // Forward, gated twice, and the order is the argument. The step's own rules ask
+        // whether this step is complete; the sequence's ask whether the whole thing may
+        // be submitted. A step that fails its own rules never reaches the sequence's,
+        // which is what stops a reader being told their card was declined when the
+        // field they left empty was the problem.
+        const own = step.validate === undefined ? [] : step.validate(form);
+        if (own.length > 0) {
+            setRefused(own);
+            return;
+        }
+        const whole = validate === undefined ? [] : validate(at, form);
+        if (whole.length > 0) {
+            setRefused(whole);
+            return;
+        }
+        setRefused([]);
+        onStepChange(last ? at : at + 1, 'forward');
+    };
+    // The focus move, once per refusal. The dependency is the length rather than the
+    // array itself, because the caller builds a fresh array on every check and
+    // depending on its identity would move the reader's focus on every render.
+    useEffect(() => {
+        if (refused.length === 0)
+            return;
+        refusedRef.current?.focus();
+    }, [refused.length]);
+    return (_jsxs("div", { "data-slot": "form-wizard", className: cn('flex w-full flex-col gap-6', className), children: [_jsx(Steps, { steps: steps, current: at, label: progressLabel }), _jsx("span", { id: instructionsId, "data-slot": "form-wizard-instructions", className: "sr-only", children: instructionsLabel }), _jsxs("form", { ref: formRef, "data-slot": "form-wizard-form", noValidate: true, role: "group", "aria-labelledby": labelId, "aria-describedby": instructionsId, onSubmit: (event) => {
+                    event.preventDefault();
+                    leave('forward');
+                }, className: "flex flex-col gap-4", children: [_jsxs("div", { "data-slot": "form-wizard-heading", className: "flex flex-col gap-1", children: [_jsx("h2", { id: labelId, "data-slot": "form-wizard-step-label", className: "text-lg font-semibold tracking-tight", children: step.label }), step.description === undefined ? null : (_jsx("p", { "data-slot": "form-wizard-step-description", className: "text-muted-foreground text-sm", children: step.description }))] }), refused.length === 0 ? null : (_jsxs("div", { ref: refusedRef, "data-slot": "form-wizard-refusal", role: "group", "aria-labelledby": blockedId, tabIndex: -1, className: cn('border-destructive/40 bg-destructive/5 text-destructive', 'focus-visible:ring-ring', 'rounded-md border p-3 outline-none', 'focus-visible:ring-[3px]'), children: [_jsx("h3", { id: blockedId, "data-slot": "form-wizard-refusal-label", className: "text-sm font-semibold", children: blockedLabel }), _jsx("ul", { "data-slot": "form-wizard-issues", className: "mt-1 flex list-none flex-col gap-2", children: refused.map((issue) => (_jsxs("li", { "data-slot": "form-wizard-issue", children: [_jsx("a", { href: `#${issue.field}`, "data-slot": "form-wizard-issue-link", className: cn('hover:underline', 'focus-visible:ring-ring', 'rounded-sm text-sm font-medium', 'underline underline-offset-2 outline-none', 'focus-visible:ring-[3px]'), children: issueLabel(issue.field) }), _jsx("p", { "data-slot": "form-wizard-issue-message", className: "text-sm", children: issue.message })] }, `${issue.field}:${issue.message}`))) })] })), _jsx("div", { "data-slot": "form-wizard-step", className: "flex flex-col gap-4", children: step.children }), children, _jsxs("div", { "data-slot": "form-wizard-navigation", className: "flex items-center gap-2", children: [_jsxs(Button, { "data-slot": "form-wizard-back", type: "button", variant: "ghost", "aria-disabled": at === 0 || undefined, onClick: () => {
+                                    if (at === 0)
+                                        return;
+                                    leave('back');
+                                }, children: [_jsx(ChevronLeftIcon, { "aria-hidden": "true" }), backLabel] }), _jsxs(Button, { "data-slot": "form-wizard-forward", type: "submit", variant: "default", className: "ms-auto", children: [last ? finishLabel : nextLabel, last ? null : _jsx(ChevronRightIcon, { "aria-hidden": "true" })] })] })] })] }));
+}
+export { FormWizard };

package/dist/components/ui/form.d.ts

@@ -0,0 +1,151 @@
+import type { ComponentProps } from 'react';
+/** The props the Form accepts. */
+export interface FormProps extends Omit<ComponentProps<'form'>, 'onSubmit'> {
+    /**
+     * The errors the server returned, keyed by field name.
+     *
+     * This is the whole point of the binding. A submission fails and comes back with
+     * a record of what was wrong with it, and a form that cannot take that record has
+     * to either drop it or turn it into a banner above the form that the reader has to
+     * match to a field themselves. Passed here, each `FormField` named after the key
+     * renders it under the control that caused it, and the control is marked invalid.
+     * Pass an empty record to clear them: the errors are cleared as data, not by
+     * reloading the page. A key with no error is an absent key rather than a key
+     * holding nothing, because a record that says "this field is wrong" and does not
+     * say how is not one this can draw.
+     */
+    errors?: Record<string, string | string[]>;
+    /**
+     * Called with the field values when the form submits.
+     *
+     * The native submit event is prevented, so this is where a server action goes.
+     * Nothing is submitted to the browser and no navigation happens unless the caller
+     * does it.
+     */
+    onSubmit?: (values: Record<string, unknown>) => void;
+    /**
+     * Whether the browser's own validation bubbles are off. @defaultValue true
+     *
+     * On by default, because the binding reports validity on the field and a form
+     * that shows the browser's bubble and a styled message is two reports of one
+     * problem, in two places, in two voices.
+     */
+    noValidate?: boolean;
+}
+/** The props the Form field accepts. */
+export interface FormFieldProps extends ComponentProps<'div'> {
+    /**
+     * The name of the field, and the key its error arrives under.
+     *
+     * Required, and it is the join between the control's `name`, the key in the
+     * server's `errors` and the field the error is drawn under. A field that is not
+     * named cannot receive an error, so this is the one prop that makes the rest of
+     * the binding work.
+     */
+    name: string;
+    /**
+     * The rule the field is checked against, returning the message to show.
+     *
+     * The message is the caller's, because it is a sentence about their product's
+     * rules. Returning nothing means the value is valid.
+     */
+    validate?: (value: unknown) => string | string[] | null | void;
+    /** Whether the field is invalid, for a value a library of the caller's owns. */
+    invalid?: boolean;
+    /** Whether the field ignores interaction. */
+    disabled?: boolean;
+}
+/** The props the Form label accepts. */
+export interface FormLabelProps extends ComponentProps<'label'> {
+}
+/** The props the Form description accepts. */
+export interface FormDescriptionProps extends ComponentProps<'p'> {
+}
+/**
+ * The props the Form control accepts.
+ *
+ * Declared here rather than as `ComponentProps<typeof FieldPrimitive.Control>`,
+ * for the same reason `Progress` declares its own props rather than re-exporting
+ * Base UI's (ticket 07 section 6): an upstream type in the signature reaches the
+ * emitted declaration, and the surface gate fails a declaration file that names
+ * an upstream module. A consumer would then need Base UI resolvable to typecheck a
+ * Prism import, which is the seam the rule exists to keep closed.
+ *
+ * It is `ComponentProps<'input'>` because that is the element the control renders
+ * by default, and naming the element is more honest than naming a `div` and being
+ * wrong about every attribute. A caller who swaps the element for a select or a
+ * textarea passes that element's own attributes and the runtime does the rest; the
+ * type here is the default case, not a limit on what may be rendered.
+ */
+export interface FormControlProps extends ComponentProps<'input'> {
+}
+/** The props the Form error accepts. */
+export interface FormErrorProps extends ComponentProps<'div'> {
+    /**
+     * What the reader can do about the error, drawn after the message.
+     *
+     * The message and the way out are one unit. "That address is already registered"
+     * with nothing after it is a dead end, and the reader is left to guess whether
+     * they should sign in instead, change the address or ask somebody. So this
+     * Component renders both in the same live region: the recovery is announced with
+     * the problem rather than being something the reader has to find.
+     */
+    action?: React.ReactNode;
+}
+/**
+ * The form binding: a form, its fields, and the errors that came back from it.
+ *
+ * **`Field` is the layout; this is the wiring.** `Field` is presentational and says
+ * so: nothing in it generates an `id`, so the consumer owns the control's id and
+ * wires it to the label's `htmlFor` and to the description or error's `id` through
+ * `aria-describedby`. That is the right default for a layout, and it is a lot of
+ * hand-written ids in a form with eleven fields, none of which a reader can see
+ * and all of which a screen reader depends on. This module is the part that
+ * generates them: `FormField` owns the name, `FormControl` registers itself with
+ * the field, and `FormLabel` and `FormDescription` find the control and point at
+ * it. Nothing here changes how `Field` looks.
+ *
+ * **A server error arrives as data and lands under the control that caused it.**
+ * `errors` is a record keyed by field name and `FormField` is keyed by the same
+ * name, so the message a submission came back with is drawn under the control the
+ * reader has to fix, the control is marked invalid, and the message is added to the
+ * control's description so it is read out when the reader reaches the field. The
+ * errors clear when the record clears: a field that fixed itself still shows the
+ * server's complaint until the caller stops passing it, which is exactly as
+ * honest as it sounds.
+ *
+ * **The error and the way out are rendered together, in one live region.** The
+ * recovery is the half of an error that is usually missing. A `FormError` renders
+ * the message and then the caller's `action`, and the region is in the document
+ * before either of them is, because a live region inserted at the same moment as
+ * its content is not announced by every screen reader. The region is therefore
+ * present and empty while the field is valid, which is the cost of the reliable
+ * half.
+ *
+ * **Use a `FormControl` inside a `FormField`.** The control is the part that
+ * registers itself, which is what makes the label's `for` resolve and what puts the
+ * description and the error into the control's accessible description. A plain
+ * `Input` renders and submits perfectly well inside a `FormField` and is not
+ * registered, so its label points at an id that is on nothing and its error is
+ * never announced with it. That is the one rule this module asks for, and it is
+ * the rule `Field` deliberately leaves to the caller.
+ */
+declare function Form({ errors, onSubmit, noValidate, className, ...props }: FormProps): import("react").JSX.Element;
+/** One field's name, its rule and the control that answers to it. */
+declare function FormField({ name, validate, invalid, disabled, className, ...props }: FormFieldProps): import("react").JSX.Element;
+/** The control's accessible name, associated with it rather than placed near it. */
+declare function FormLabel({ className, ...props }: FormLabelProps): import("react").JSX.Element;
+/** The control itself, registered with the field so the label and errors find it. */
+declare function FormControl({ className, ...props }: FormControlProps): import("react").JSX.Element;
+/** A short helper line under the control, announced with the control itself. */
+declare function FormDescription({ className, ...props }: FormDescriptionProps): import("react").JSX.Element;
+/**
+ * The field's error and what to do about it, in one announced region.
+ *
+ * The region is always in the document and the message is not, because a live
+ * region that arrives with its content is missed by some screen readers. It is
+ * empty while the field is valid.
+ */
+declare function FormError({ className, action, ...props }: FormErrorProps): import("react").JSX.Element;
+export { Form, FormControl, FormDescription, FormError, FormField, FormLabel };
+//# sourceMappingURL=form.d.ts.map

package/dist/components/ui/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../../src/components/ui/form.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C,kCAAkC;AAClC,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IACzE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACpD;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAe,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC3D;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;IAC9D,gFAAgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAe,SAAQ,cAAc,CAAC,OAAO,CAAC;CAAG;AAElE,8CAA8C;AAC9C,MAAM,WAAW,oBAAqB,SAAQ,cAAc,CAAC,GAAG,CAAC;CAAG;AAEpE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc,CAAC,OAAO,CAAC;CAAG;AAEpE,wCAAwC;AACxC,MAAM,WAAW,cAAe,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC3D;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAiB,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,+BAUpF;AAED,qEAAqE;AACrE,iBAAS,SAAS,CAAC,EACjB,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,+BAYhB;AAED,oFAAoF;AACpF,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,+BAQzD;AAED,qFAAqF;AACrF,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAc7D;AAED,gFAAgF;AAChF,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,oBAAoB,+BAQrE;AAED;;;;;;GAMG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,+BAyBjE;AAED,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/ui/form.js

@@ -0,0 +1,73 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Field as FieldPrimitive } from '@base-ui/react/field';
+import { Form as FormPrimitive } from '@base-ui/react/form';
+import { cn } from '../../lib/utils.js';
+/**
+ * The form binding: a form, its fields, and the errors that came back from it.
+ *
+ * **`Field` is the layout; this is the wiring.** `Field` is presentational and says
+ * so: nothing in it generates an `id`, so the consumer owns the control's id and
+ * wires it to the label's `htmlFor` and to the description or error's `id` through
+ * `aria-describedby`. That is the right default for a layout, and it is a lot of
+ * hand-written ids in a form with eleven fields, none of which a reader can see
+ * and all of which a screen reader depends on. This module is the part that
+ * generates them: `FormField` owns the name, `FormControl` registers itself with
+ * the field, and `FormLabel` and `FormDescription` find the control and point at
+ * it. Nothing here changes how `Field` looks.
+ *
+ * **A server error arrives as data and lands under the control that caused it.**
+ * `errors` is a record keyed by field name and `FormField` is keyed by the same
+ * name, so the message a submission came back with is drawn under the control the
+ * reader has to fix, the control is marked invalid, and the message is added to the
+ * control's description so it is read out when the reader reaches the field. The
+ * errors clear when the record clears: a field that fixed itself still shows the
+ * server's complaint until the caller stops passing it, which is exactly as
+ * honest as it sounds.
+ *
+ * **The error and the way out are rendered together, in one live region.** The
+ * recovery is the half of an error that is usually missing. A `FormError` renders
+ * the message and then the caller's `action`, and the region is in the document
+ * before either of them is, because a live region inserted at the same moment as
+ * its content is not announced by every screen reader. The region is therefore
+ * present and empty while the field is valid, which is the cost of the reliable
+ * half.
+ *
+ * **Use a `FormControl` inside a `FormField`.** The control is the part that
+ * registers itself, which is what makes the label's `for` resolve and what puts the
+ * description and the error into the control's accessible description. A plain
+ * `Input` renders and submits perfectly well inside a `FormField` and is not
+ * registered, so its label points at an id that is on nothing and its error is
+ * never announced with it. That is the one rule this module asks for, and it is
+ * the rule `Field` deliberately leaves to the caller.
+ */
+function Form({ errors, onSubmit, noValidate = true, className, ...props }) {
+    return (_jsx(FormPrimitive, { className: cn('flex w-full flex-col gap-6', className), noValidate: noValidate, ...(errors === undefined ? null : { errors }), onFormSubmit: (values) => onSubmit?.(values), ...props }));
+}
+/** One field's name, its rule and the control that answers to it. */
+function FormField({ name, validate, invalid, disabled, className, ...props }) {
+    return (_jsx(FieldPrimitive.Root, { "data-slot": "form-field", name: name, className: cn('flex w-full flex-col gap-1.5', className), ...(validate === undefined ? null : { validate }), ...(invalid === undefined ? null : { invalid }), ...(disabled === undefined ? null : { disabled }), ...props }));
+}
+/** The control's accessible name, associated with it rather than placed near it. */
+function FormLabel({ className, ...props }) {
+    return (_jsx(FieldPrimitive.Label, { "data-slot": "form-label", className: cn('text-foreground text-sm leading-none font-medium', className), ...props }));
+}
+/** The control itself, registered with the field so the label and errors find it. */
+function FormControl({ className, ...props }) {
+    return (_jsx(FieldPrimitive.Control, { "data-slot": "form-control", className: cn('border-input bg-background text-foreground placeholder:text-muted-foreground flex h-9 w-full min-w-0 rounded-md border px-3 py-1 text-base shadow-xs transition-[color,box-shadow] duration-fast ease-out outline-none md:text-sm', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'aria-invalid:border-destructive aria-invalid:ring-destructive/20', 'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50', className), ...props }));
+}
+/** A short helper line under the control, announced with the control itself. */
+function FormDescription({ className, ...props }) {
+    return (_jsx(FieldPrimitive.Description, { "data-slot": "form-description", className: cn('text-muted-foreground text-sm', className), ...props }));
+}
+/**
+ * The field's error and what to do about it, in one announced region.
+ *
+ * The region is always in the document and the message is not, because a live
+ * region that arrives with its content is missed by some screen readers. It is
+ * empty while the field is valid.
+ */
+function FormError({ className, action, ...props }) {
+    return (_jsxs("div", { "data-slot": "form-error", role: "alert", className: cn('flex flex-col items-start gap-1', className), ...props, children: [_jsx(FieldPrimitive.Error, { "data-slot": "form-error-message", className: "text-destructive text-sm font-medium" }), action === undefined ? null : (_jsx(FieldPrimitive.Validity, { children: (state) => (state.validity.valid === false ? action : null) }))] }));
+}
+export { Form, FormControl, FormDescription, FormError, FormField, FormLabel };