@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,176 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from 'react';
+import { Button } from './button.js';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, } from './dialog.js';
+import { Field } from './field.js';
+import { LiveRegion } from './live-region.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The error summary's own frame.
+ *
+ * A tinted destructive surface rather than a filled one, so a form with one wrong
+ * field is not interrupted by a block of red, and destructive ink because the
+ * summary is only ever rendered when something is wrong. It sets its own fill and
+ * therefore its own ink, for the reason the Stated Ink Rule gives: an ink left to
+ * be inherited is whatever surface the element happens to be sitting on.
+ */
+const SUMMARY = 'border-destructive/40 bg-destructive/5 text-destructive rounded-md border p-3';
+/**
+ * The summary's focus target, drawn once.
+ *
+ * `tabIndex={-1}` at the call site and not `tabIndex={0}`, and the difference is
+ * the whole keyboard model: a focus target that is a tab stop adds a permanent stop
+ * to every reader's journey for a region that exists only after a refusal, while
+ * `-1` makes it focusable by script and by nothing else. The outline is suppressed
+ * because the ring replaces it, and the ring is `ring-ring` at full strength on
+ * `focus-visible` for the reason every ring in this package is: the token is the
+ * one measured to clear 3:1 against every surface, and a destructive ring on a
+ * panel whose own ink is already destructive reads as a second error rather than
+ * as an indicator.
+ */
+const SUMMARY_FOCUS = 'rounded-sm outline-none focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * A modal that owns a validating submit: it runs the caller's rules before the
+ * submission, draws what is wrong where it can be acted on, and keeps the reader
+ * where they were when a submission is refused.
+ *
+ * **It is the accessibility centrepiece of the three modal shapes, and what makes
+ * it one is a focus move rather than a drawing.** A form dialog has four things a
+ * reader must be able to do from a keyboard: submit it, be told what is wrong, get
+ * to whatever is wrong, and get back to where they were. The first three are
+ * ordinary and the fourth is where a hand-rolled version fails. A refusal tends to
+ * re-render the form's content, and a re-render that replaces the control the
+ * reader was on leaves focus on `body`: a reader in a six-field form is now at the
+ * top of the document with no idea which field they were in. So on a refusal the
+ * summary takes focus and nothing else does.
+ *
+ * **The move is to the summary and not to the first invalid field, because a
+ * summary is a list and a first field is one of its entries.** A reader with one
+ * mistake out of six needs the count and the whole list, since they have to decide
+ * whether to fix everything or abandon the form; landing them in the first field
+ * gives them neither and makes them Tab through the rest to assemble what they were
+ * just told. The summary takes focus and is deliberately *not* a `role="alert"`: an
+ * alert in the same commit as a focus move is one refusal announced twice in two
+ * voices, which is the arrangement `LifecycleButton` explicitly avoids.
+ *
+ * **Validation runs before the submission and its result is unioned with the
+ * server's by position, never merged.** `validate` is a local check over the form's
+ * own values, so a field left empty is caught before a request goes out and the
+ * reader is not made to wait for a round trip to be told what the form already
+ * knew. `issues` is the other route, for a request that came back refused, and both
+ * reach one summary because a form that can show local errors and not server errors
+ * is a form whose worst errors are the ones it hides. Merging was rejected: a local
+ * result arriving after the server's would overwrite the sentence that says why
+ * the *server* said no.
+ *
+ * **A refusal with nothing to draw is the caller's own transitional state, and this
+ * Component says nothing rather than inventing a sentence.** A caller who sets
+ * `phase` to `invalid` on the way to a server response and passes `issues` as
+ * undefined is between two states, and the honest drawing is no summary, no
+ * announcement and no focus move until there is something to read. The cost is
+ * named rather than hidden: a caller in that state has a submit control labelled as
+ * a refusal with no explanation on the page, which is why `invalidLabel` is required
+ * and why the documentation says to set the phase when the issues arrive.
+ *
+ * **The submit control refuses a second press while one is running and says so
+ * rather than vanishing.** `aria-disabled` and not the native attribute, for the
+ * reason `Dropzone` and `LifecycleButton` both give: 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. Here the control keeps its
+ * place, keeps its ring, and announces itself as busy. The price is a tab stop that
+ * does nothing, which is what every disabled control costs and is why this package
+ * draws them rather than removing them.
+ *
+ * **The modal is `Dialog` and only `Dialog`, and the two refusals are the argument
+ * rather than a preference.** A `Popover` closes on an outside press, so for a form
+ * it means a reader who clicks the page behind has silently lost six fields of
+ * typing with no warning and no route back. An `AlertDialog` refuses dismissal
+ * outright, so for a form it is a trap: a twelve-field dialog with no outside press
+ * and no Escape is a surface a reader cannot leave once they are in it. `Dialog` is
+ * the only one of the three that can be dismissed and does not dismiss itself, and
+ * that is the property a form needs. The backdrop, the portal, the focus trap, the
+ * scroll lock and Escape are composed rather than reimplemented, for the reason
+ * every composition here is one: two implementations of a focus trap disagree
+ * within a release and a consumer cannot tell which they got.
+ *
+ * **It is a client Component**, because validation and submission happen after the
+ * reader acts, because the summary's focus move is script, 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 this panel once with the form's values in
+ * place, and what it may not do is check them.
+ */
+function FormDialog({ open, onOpenChange, trigger, phase, onSubmit, validate, issues, title, description, idleLabel, invalidLabel, submittingLabel, failedLabel, errorSummaryLabel, fieldLabel, cancelLabel, closeLabel, children, extraActions, className, }) {
+    const generated = useId();
+    const headingId = `${generated}-errors`;
+    const formRef = useRef(null);
+    const summaryRef = useRef(null);
+    // The local check's result, held so the refusal can be drawn from a check this
+    // Component ran itself. Cleared the moment a submission is allowed through, so a
+    // later refusal never shows a stale message from an earlier attempt.
+    const [local, setLocal] = useState([]);
+    // The phase the last focus move was made from. The move happens on the
+    // transition into a refusal and not on every render while the reader is sitting
+    // on the summary, which is what stops a reader who tabs away and back from being
+    // dragged onto it again.
+    const movedFor = useRef('idle');
+    const refused = phase === 'invalid';
+    const shown = refused ? (issues ?? local) : [];
+    const running = phase === 'submitting';
+    useEffect(() => {
+        if (!open) {
+            movedFor.current = 'idle';
+            return;
+        }
+        if (!refused) {
+            movedFor.current = 'idle';
+            return;
+        }
+        if (movedFor.current === 'invalid')
+            return;
+        movedFor.current = 'invalid';
+        // Only when there is something to read. A refusal with no issues drawn is the
+        // caller's own transitional state, and moving focus onto a region with no
+        // content is a reader being told there is a problem and then finding none.
+        if (shown.length > 0)
+            summaryRef.current?.focus();
+    }, [open, refused, shown.length]);
+    const submit = (event) => {
+        event.preventDefault();
+        if (running)
+            return;
+        const form = formRef.current;
+        if (form === null)
+            return;
+        if (validate === undefined) {
+            setLocal([]);
+            onSubmit(form);
+            return;
+        }
+        const found = validate(new FormData(form), form);
+        setLocal(found);
+        // A refusal never reaches `onSubmit`, which is the whole distinction between a
+        // form that checks itself and one that asks a network whether it is allowed to
+        // try.
+        if (found.length > 0)
+            return;
+        onSubmit(form);
+    };
+    const label = running
+        ? submittingLabel
+        : phase === 'failed'
+            ? failedLabel
+            : refused
+                ? invalidLabel
+                : idleLabel;
+    return (_jsxs(Dialog, { open: open, onOpenChange: onOpenChange, children: [_jsx(DialogTrigger, { "data-slot": "form-dialog-trigger", children: trigger }), _jsxs(DialogContent, { closeLabel: closeLabel, className: cn('max-w-overlay-form', className), children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: title }), description === undefined ? null : _jsx(DialogDescription, { children: description })] }), _jsxs("form", { ref: formRef, "data-slot": "form-dialog-form", 
+                        // The browser's own bubbles are off because this Component reports
+                        // validity in one place, and a bubble over a styled message is two
+                        // reports of one problem in two voices.
+                        noValidate: true, onSubmit: submit, className: "flex flex-col gap-4", children: [children, shown.length === 0 ? null : (_jsxs(Field, { ref: summaryRef, "data-slot": "form-dialog-error-summary", "aria-labelledby": headingId, tabIndex: -1, className: cn(SUMMARY, SUMMARY_FOCUS), children: [_jsx("h2", { id: headingId, "data-slot": "form-dialog-error-summary-heading", className: "text-sm font-semibold", children: errorSummaryLabel }), _jsx("ul", { "data-slot": "form-dialog-issues", className: "mt-1 flex list-none flex-col gap-2", children: shown.map((issue) => (_jsxs("li", { "data-slot": "form-dialog-issue", children: [_jsx("a", { href: `#${issue.field}`, "data-slot": "form-dialog-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: fieldLabel(issue.field) }), _jsx("p", { "data-slot": "form-dialog-issue-message", className: "text-sm", children: issue.message })] }, `${issue.field}:${issue.message}`))) })] })), _jsx(DialogFooter, { className: "mt-2", children: _jsxs("div", { "data-slot": "form-dialog-actions", className: "flex flex-wrap items-center gap-2", children: [extraActions, _jsx(Button, { "data-slot": "form-dialog-cancel", type: "button", variant: "outline", onClick: () => onOpenChange(false), children: cancelLabel }), _jsx(Button, { "data-slot": "form-dialog-submit", type: "submit", "aria-disabled": running || undefined, onClick: (event) => {
+                                                if (running)
+                                                    event.preventDefault();
+                                            }, children: label })] }) })] }), _jsx(LiveRegion, { "data-slot": "form-dialog-status", className: "sr-only", politeness: phase === 'failed' ? 'assertive' : 'polite', children: phase === 'failed' ? failedLabel : running ? submittingLabel : '' })] })] }));
+}
+export { FormDialog };

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 };