@nanisoft/prism-ui 0.13.0 → 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/image-list-field.d.ts

@@ -0,0 +1,232 @@
+import { type ReactNode } from 'react';
+/**
+ * One image the field holds, and the three things the field knows about it.
+ *
+ * A reference and not a file. A `File` object is a browser fact that does not
+ * survive a page reload and says nothing about where the bytes are, and a
+ * design system that took one would be a Component whose value is only meaningful
+ * on the machine that produced it. What a form field actually holds is a handle:
+ * an id the caller's own store recognises, and a name a reader recognises. The
+ * caller resolves that handle into a URL, a signed path or a thumbnail component,
+ * and passes the result as `preview`, because how an image is fetched, cached and
+ * cropped is the caller's transport decision and Prism ships no client.
+ */
+export type ImageListFieldImage = {
+    /**
+     * The caller's own identity for the image, and what the remove control reports.
+     *
+     * Required, and required as a string rather than as the file name, for the
+     * reason `FileUpload` states in full: a reader who adds the same photograph
+     * twice has two rows with the same name, and two remove controls that announce
+     * identically are two controls nobody can tell apart.
+     */
+    id: string;
+    /**
+     * The name a reader recognises the image by.
+     *
+     * A word and not a sentence. It is drawn truncated in the middle and it is what
+     * `removeLabel` is given, so it is the one string in the row that a caller
+     * should keep short enough to finish reading.
+     */
+    name: string;
+    /**
+     * The caller's own picture for the row, clipped to a fixed square.
+     *
+     * A `ReactNode` and not a URL. A URL here would be a claim that the image lives
+     * at an address the browser can fetch, which is false for a blob, a signed
+     * path that expires, a data URI and anything behind an authenticated route, and
+     * a Component that rendered an `<img>` would then be drawing a broken image and
+     * an alt text it invented. Pass an `img` with the caller's own `alt`, or a
+     * placeholder mark; both are the caller's to choose.
+     */
+    preview?: ReactNode;
+};
+/**
+ * The props the Image list field accepts.
+ *
+ * A declared interface rather than a forwarded native one, which is the opposite
+ * of what most of this package does and is right here: every prop on this
+ * Component is a fact about the caller's value or a sentence the caller owns, and
+ * there is no native attribute left to forward once those are spent.
+ */
+export interface ImageListFieldProps {
+    /**
+     * The images, in the order the reader added them.
+     *
+     * Required, and order is the caller's because it is a claim about importance.
+     * The list is an `ol`, so the position is in the accessibility tree and a
+     * reader who removes the third of six hears the five that remain renumbered
+     * rather than having to count them again.
+     */
+    images: ImageListFieldImage[];
+    /**
+     * The most images this field will hold.
+     *
+     * Required, and a number rather than a boolean, because "at most one" and "at
+     * most twelve" are the same shape of rule and only one of them is a decision
+     * about a product. A caller that does not have a cap does not use this
+     * Component: a list with no ceiling is a `FileUpload` with a receipt's worth of
+     * rows, and the Component that already draws that is one call away.
+     */
+    cap: number;
+    /**
+     * The visible label of the add affordance, in the product's own words.
+     *
+     * Required and never defaulted. "Add photograph", "Add another floor plan" and
+     * "Subir imagen" are three products' answers, and the affordance is the one
+     * place on the field where a reader decides whether the rule is one they accept.
+     */
+    addLabel: ReactNode;
+    /**
+     * Called when the reader asks for another image.
+     *
+     * Required, and it is a callback rather than a composed `Dropzone` on purpose.
+     * This Component cannot know what an image is on the caller's side: it may be a
+     * browser `File` on its way to an upload, a URL already in the caller's store,
+     * or a picked frame from a camera roll the browser has no input for. Enforcing
+     * the cap means owning the affordance, and owning the affordance means Prism
+     * draws the control while the caller keeps the picker: compose `Dropzone` in
+     * your own layout, or a `Button` over a hidden `input`, and open it here. The
+     * alternative, Prism rendering a `Dropzone` and being handed `File` objects,
+     * would make a field about images a field about uploads, and every caller whose
+     * images are already stored would have to fake a `File` to use it.
+     */
+    onAdd: () => void;
+    /**
+     * Called with an image's `id` when the reader takes it off the list.
+     *
+     * Required rather than optional, unlike `FileUpload`'s. A `FileUpload` is
+     * sometimes a receipt, and offering to remove an attachment from a receipt is a
+     * promise the product cannot keep. A field is not a receipt: the images on it
+     * are the ones the reader is still choosing between, so a field where a chosen
+     * image cannot be unchosen is a form with a mistake in it and no way back.
+     */
+    onRemove: (id: string) => void;
+    /**
+     * The accessible name of one row's remove control, given that row's image name.
+     *
+     * Required, and a function because the name has to name the image and the
+     * image's name is the caller's string rather than this package's sentence. A
+     * nameless remove control is announced as "button", and a screen reader user
+     * holding a list of six is left to work out which row it belongs to.
+     */
+    removeLabel: (name: string) => string;
+    /**
+     * What stands in for the list while it is empty.
+     *
+     * Required, and it is a label rather than a placeholder row. A row with no
+     * image in it is a row a reader tries to remove, and a row whose preview is
+     * still loading is a row that looks like a broken image. The absence is either
+     * the caller's own sentence or, here, nothing at all: a caller who would rather
+     * the field showed nothing until the first image passes an empty string and
+     * gets nothing drawn, because the check is on the value's length and not on
+     * this prop being present.
+     */
+    empty: ReactNode;
+    /**
+     * What the reader is told when the cap is reached.
+     *
+     * Optional, and it exists because the affordance going unavailable is a
+     * question the reader will ask. A dimmed add button answers "can I not" and not
+     * "why not", and a form whose only feedback is a dimmed control is the dead end
+     * the disabled-state rule exists to prevent. Written with the limit and the way
+     * past it: "Six is the most a listing takes. Remove one to swap it." The
+     * affordance points at it with `aria-describedby` while it is shown, so the
+     * reason is announced with the control rather than sitting beside it as a line
+     * a reader has to find.
+     */
+    capLabel?: ReactNode;
+    /**
+     * The list's own name, drawn above it and used as its accessible name.
+     *
+     * Optional rather than required, and the omission is deliberate rather than an
+     * oversight: this is the one place in the package where a region is allowed to
+     * arrive anonymous, and `ListPanel` says why at length. A list called "Images"
+     * is a claim that is wrong in every consumer's product, and a screen reader
+     * user hearing a generic name learns less than hearing none, because a name is
+     * a promise that something follows it. Omit it and the list is honestly absent
+     * from the landmark list; pass one when the field sits among several.
+     */
+    label?: ReactNode;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * An ordered list of images with a cap, a per-item remove, and an add affordance
+ * that stops offering a seventh before the reader has chosen one.
+ *
+ * **It is not a `FileUpload`, and the difference is the cap.** `FileUpload` is the
+ * receipt half of an upload: it renders whatever array it is handed, with no
+ * ceiling and no way in, because a receipt names what was sent and a limit on
+ * what may be sent belongs to the control that sends. This is the other half. It
+ * has a ceiling, and the ceiling is a rule about the caller's product, so the
+ * Component that can enforce it is the one that owns the affordance. A caller who
+ * wants a capped list today writes a button, a length test and a disabled branch,
+ * and the branch is the interesting one, because a cap enforced anywhere else
+ * produces one of two lies: a value holding six images rendered as four, or six
+ * rows where the fifth and sixth are drawn in a way that says they are not
+ * welcome. Neither is a fact about the reader's field. The one thing that is a
+ * fact is the affordance, and this is the Component that draws it.
+ *
+ * **The cap is enforced at the affordance and nowhere else, and that placement is
+ * the design.** The moment the cap is reached, the add control is still there, in
+ * the tab order, and marked `aria-disabled`; it is not removed and it is not
+ * natively disabled, because a control that vanishes leaves a keyboard reader
+ * with a gap and no announcement, and a natively disabled one is gone from the tab
+ * order for the same reason. `Dropzone` states the whole argument and this
+ * Component inherits it. The reader learns the cap before they spend a pick, and
+ * the value is never silently truncated.
+ *
+ * **Removing a middle row moves focus, and that is the part no prop can express.**
+ * The naive `onRemove` hands the reader back to the document: the button they
+ * pressed is unmounted with the row, focus falls to `body`, and the next Tab
+ * starts from the top of the page, so a reader removing the third of six
+ * photographs is returned to the top of a form to find the two they still meant
+ * to change. The correct destination is a neighbour, and which neighbour is a
+ * fact about the index the caller does not know this Component holds: the row
+ * that moved up into the removed row's place, or the one above it when the
+ * removed row was last. Prism knows the index because it drew the row, so Prism
+ * moves the focus. When the last image goes, the focus lands on the add control,
+ * because that is the only operable thing left in the field and dropping a reader
+ * on nothing is the same defect one level up.
+ *
+ * **The row is a reference and the list is an `ol`, so position is in the
+ * accessibility tree.** The Component does not draw an ordinal and does not
+ * renumber anything by hand: an `ol` reports "3 of 6" for free, and the
+ * renumbering the reader needs after a removal is the list doing its job rather
+ * than a number this Component recomputed and could get wrong. The remove control
+ * is named by the caller's own sentence so the two do not have to agree.
+ *
+ * **It draws its own row and does not compose `FileUpload`, and the reason is the
+ * number of bytes.** `FileUpload`'s row is a name, a size in bytes, an optional
+ * transfer meter and an optional per-file error, and a field of references has
+ * none of those: a stored image has no size until the caller fetches it, and
+ * drawing a byte count for an image that has not been downloaded is a
+ * measurement of nothing. The two would also disagree about focus, because
+ * `FileUpload` owns its own remove control and there is no way to tell it where
+ * the reader's focus should land afterwards without reaching into its markup. The
+ * composition Prism does make is outward: `onAdd` is the seam where a `Dropzone`
+ * or a hidden `input` is composed, and `Button` draws the affordance rather than
+ * this Component re-deriving a control's metrics.
+ *
+ * **It is a client Component**, because the focus handoff and the cap's arrival
+ * both happen after the reader acts, and neither can be known at a server render.
+ * What that costs is the price of every client field: a form with images on it
+ * carries a hydration boundary, and a caller whose form is otherwise static pays
+ * for this one. The value is still the caller's, so a server Component may render
+ * the whole field once with the list already in place; what it may not do is offer
+ * a capped, removable list whose focus behaves, because that part is a client
+ * fact.
+ *
+ * **Two upstream spellings are this one job, and the catalogue holds one of
+ * them.** An image list and a gallery upload differ in whether the frame around
+ * the images is decorative, and in nothing else: both are an ordered list of
+ * image references, both cap, both remove. Publishing both would put two Items in
+ * the list whose only difference is a wrapper one of them drew, and a list
+ * nobody can search is what the naming law exists to prevent. A caller who wants
+ * a gallery frames the list themselves, which is layout and therefore already
+ * theirs.
+ */
+declare function ImageListField({ images, cap, addLabel, onAdd, onRemove, removeLabel, empty, capLabel, label, className, }: ImageListFieldProps): import("react").JSX.Element;
+export { ImageListField };
+//# sourceMappingURL=image-list-field.d.ts.map

package/dist/components/ui/image-list-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-list-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/image-list-field.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAKhE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;;;OAOG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,MAAM,EAAE,mBAAmB,EAAE,CAAA;IAC7B;;;;;;;;OAQG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB;;;;;;;;OAQG;IACH,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC;;;;;;;;;;OAUG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,iBAAS,cAAc,CAAC,EACtB,MAAM,EACN,GAAG,EACH,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,WAAW,EACX,KAAK,EACL,QAAQ,EACR,KAAK,EACL,SAAS,GACV,EAAE,mBAAmB,+BA8JrB;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}