@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/components/ui/filter-panel.d.ts

@@ -0,0 +1,164 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** The props a `FilterPanelHeader` takes. */
+export interface FilterPanelHeaderProps extends Omit<ComponentProps<'div'>, 'title'> {
+    /**
+     * The id the panel's `aria-labelledby` points at.
+     *
+     * Supplied by `FilterPanel`, which generates it and puts it on the title
+     * element. A caller rendering a header inside their own `section` passes their
+     * own and sets `aria-labelledby` themselves, which is the arrangement the
+     * `title` prop exists to make unnecessary.
+     */
+    titleId: string;
+    /** The one line that names the panel. */
+    title?: ReactNode;
+    /**
+     * The caller's own account of what is currently applied.
+     *
+     * A node because the sentence is the consumer's: "3 filters" is true in one
+     * language and false in another, and so is "Showing archived runs". A panel
+     * that assembled the sentence would have assembled it in English, into a
+     * product that may not be in English.
+     */
+    summary?: ReactNode;
+    /** Layout only. */
+    className?: string;
+}
+/** The props a `FilterPanelFooter` takes. */
+export interface FilterPanelFooterProps extends ComponentProps<'div'> {
+    /**
+     * The apply and clear controls, as a slot.
+     *
+     * A slot and not a pair of props for two buttons, because the two are the
+     * consumer's decisions together: which one is primary, whether clear comes
+     * first, whether clear is even offered, and what each one says in the
+     * consumer's own words. A panel that drew them would be drawing all four.
+     */
+    children?: ReactNode;
+    /** Layout only. */
+    className?: string;
+}
+/** The props a `FilterPanel` takes. */
+export interface FilterPanelProps extends Omit<ComponentProps<'section'>, 'children' | 'title'> {
+    /**
+     * The one line that names the panel, and the accessible name of the region.
+     *
+     * A `ReactNode` rather than a string, because the panel's visible title is
+     * content. The accessible name is derived from this element by
+     * `aria-labelledby` rather than set separately, so the name a reader hears and
+     * the name a sighted reader reads are the same text by construction.
+     */
+    title?: ReactNode;
+    /**
+     * The caller's account of what is applied, shown in the header beside the
+     * title.
+     *
+     * In the header rather than the footer because it is a statement, not an
+     * instruction. A reader who has scrolled to the bottom of a tall filter column
+     * is looking for the button, and the statement about the state they are in has
+     * to be where they already were, at the top, or it is a thing they have to go
+     * looking for.
+     */
+    summary?: ReactNode;
+    /**
+     * The footer's slot, where apply and clear go.
+     *
+     * Rendered only when the caller passes it, because a footer band with nothing
+     * in it is a gap the reader looks through and a panel with no apply control is
+     * a panel whose filters apply themselves, which is the one thing this Component
+     * refuses to decide.
+     */
+    actions?: ReactNode;
+    /**
+     * The panel's accessible name, used only when there is no `title` to take it
+     * from.
+     *
+     * A `string` because this one is written into `aria-label`. With neither a
+     * title nor a name the region renders anonymous, which is the honest state
+     * rather than a name this package invented.
+     */
+    label?: string;
+    /** The filter controls, in the order a reader should meet them. */
+    children?: ReactNode;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * A titled panel holding filter controls, with a summary above and a footer below.
+ *
+ * **The panel does not own apply and clear, and that is the whole reason it is a
+ * Component rather than a form.** The obvious version of this is a panel that
+ * applies on every change, and it is wrong for a reason that has nothing to do
+ * with performance: applying on change makes a decision about the consumer's data
+ * layer. It means a filter cannot be set before the next one is, that a request
+ * goes out per keystroke and per toggle, that the list behind the panel is
+ * rewritten while the reader is still choosing, and that a consumer with a large
+ * result set has to add debouncing to a Component they installed. The alternative
+ * is a panel that applies on a button, and that one has to know when the draft is
+ * complete: which filters are dependent on which others, whether a half-chosen
+ * range is valid, whether a pending change is a change. That is the consumer's
+ * fact about their own data, and it is not knowable from inside a layout panel.
+ * So the panel draws the frame, the summary slot and the footer slot, and the
+ * consumer supplies the two controls and owns every decision behind them. The
+ * cost is real and worth naming: a caller who wants the panel to own apply has to
+ * write four lines around it, and a caller who forgets gets filters that do
+ * nothing at all, which is a state the panel could have prevented by owning them
+ * and chose not to.
+ *
+ * **It is the same decision `list-panel` makes about its region, made once.**
+ * Both are a `section` named by its own title through `aria-labelledby`, both
+ * generate the title's id, and both fall back to `aria-label` only when the caller
+ * passes one and render anonymous otherwise. Two panels that named themselves
+ * differently would mean a reader meeting a named region in one place and an
+ * anonymous one in the next, from the same library, and the inconsistency would
+ * read as one of the two being wrong. So the rule is stated once here and
+ * `list-panel` states the same rule for its own frame: a `div` is not a landmark,
+ * a landmark a screen reader cannot name is a landmark they walk past twice, and
+ * a region Prism named for the caller is a claim about somebody else's product.
+ *
+ * **The summary is the caller's, and it is a slot rather than a count.** A panel
+ * that said "3 filters active" would be true in one language and false in another,
+ * and it would be wrong in this one the moment a filter has a range in it rather
+ * than a value. What is active is a fact about the consumer's state, and the
+ * sentence that states it is theirs.
+ *
+ * **The controls are the caller's own elements and the panel adds no wrapper per
+ * control.** A panel that wrapped each filter in its own row would assume the
+ * filters are single-line, which is false of a date range, a multi-select and
+ * anything with a hint under it. The panel is a column; the column's contents are
+ * the caller's, composed out of `Field`, `Checkbox`, `Switch` and `NativeSelect`,
+ * which is where the spacing and the naming of an individual control live.
+ *
+ * It is a server Component. It holds no state, reads no context and attaches no
+ * handler, so a filter column costs no JavaScript from this; the draft state, the
+ * apply handler and the clear handler are all the consumer's, which is the same
+ * argument as the rest of this Component's design and the reason the panel can be
+ * a plain `section` at all.
+ */
+declare function FilterPanel({ title, summary, actions, label, children, className, ...props }: FilterPanelProps): import("react").JSX.Element;
+/**
+ * The head of a filter panel: its title, and the caller's account of what is
+ * applied.
+ *
+ * Rendered by `FilterPanel` when either slot is present, and not at all when
+ * neither is, so a panel whose caller has not given it a title does not get a
+ * bordered band with nothing in it. The title element is a `span` carrying the
+ * id the panel points `aria-labelledby` at, rather than a heading: a filter
+ * column in a sidebar is not the heading of the region it sits in, and a heading
+ * here would put an entry in the page outline for a control cluster. A caller who
+ * wants a heading passes an element as `title` and keeps the name.
+ */
+declare function FilterPanelHeader({ titleId, title, summary, className, ...props }: FilterPanelHeaderProps): import("react").JSX.Element;
+/**
+ * The foot of a filter panel, where the apply and clear controls sit.
+ *
+ * On the muted surface and above a rule, for the reason a `ListPanel`'s footer is:
+ * it is the one band that does not scroll with the controls above it, and a
+ * reader who has set five filters has to be able to reach the control that commits
+ * them without scrolling back to a row they have already set. A caller who wants
+ * the pair in the other order, or a third control beside them, passes one slot and
+ * composes what it needs.
+ */
+declare function FilterPanelFooter({ className, ...props }: FilterPanelFooterProps): import("react").JSX.Element;
+export { FilterPanel, FilterPanelHeader, FilterPanelFooter };
+//# sourceMappingURL=filter-panel.d.ts.map

package/dist/components/ui/filter-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-panel.d.ts","sourceRoot":"","sources":["../../../src/components/ui/filter-panel.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIlE,6CAA6C;AAC7C,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAClF;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAuB,SAAQ,cAAc,CAAC,KAAK,CAAC;IACnE;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC7F;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAK,EACL,OAAO,EACP,OAAO,EACP,KAAK,EACL,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAoClB;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,iBAAiB,CAAC,EACzB,OAAO,EACP,KAAK,EACL,OAAO,EACP,SAAS,EACT,GAAG,KAAK,EACT,EAAE,sBAAsB,+BAmBxB;AAED;;;;;;;;;GASG;AACH,iBAAS,iBAAiB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,sBAAsB,+BAQzE;AAED,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/components/ui/filter-panel.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * A titled panel holding filter controls, with a summary above and a footer below.
+ *
+ * **The panel does not own apply and clear, and that is the whole reason it is a
+ * Component rather than a form.** The obvious version of this is a panel that
+ * applies on every change, and it is wrong for a reason that has nothing to do
+ * with performance: applying on change makes a decision about the consumer's data
+ * layer. It means a filter cannot be set before the next one is, that a request
+ * goes out per keystroke and per toggle, that the list behind the panel is
+ * rewritten while the reader is still choosing, and that a consumer with a large
+ * result set has to add debouncing to a Component they installed. The alternative
+ * is a panel that applies on a button, and that one has to know when the draft is
+ * complete: which filters are dependent on which others, whether a half-chosen
+ * range is valid, whether a pending change is a change. That is the consumer's
+ * fact about their own data, and it is not knowable from inside a layout panel.
+ * So the panel draws the frame, the summary slot and the footer slot, and the
+ * consumer supplies the two controls and owns every decision behind them. The
+ * cost is real and worth naming: a caller who wants the panel to own apply has to
+ * write four lines around it, and a caller who forgets gets filters that do
+ * nothing at all, which is a state the panel could have prevented by owning them
+ * and chose not to.
+ *
+ * **It is the same decision `list-panel` makes about its region, made once.**
+ * Both are a `section` named by its own title through `aria-labelledby`, both
+ * generate the title's id, and both fall back to `aria-label` only when the caller
+ * passes one and render anonymous otherwise. Two panels that named themselves
+ * differently would mean a reader meeting a named region in one place and an
+ * anonymous one in the next, from the same library, and the inconsistency would
+ * read as one of the two being wrong. So the rule is stated once here and
+ * `list-panel` states the same rule for its own frame: a `div` is not a landmark,
+ * a landmark a screen reader cannot name is a landmark they walk past twice, and
+ * a region Prism named for the caller is a claim about somebody else's product.
+ *
+ * **The summary is the caller's, and it is a slot rather than a count.** A panel
+ * that said "3 filters active" would be true in one language and false in another,
+ * and it would be wrong in this one the moment a filter has a range in it rather
+ * than a value. What is active is a fact about the consumer's state, and the
+ * sentence that states it is theirs.
+ *
+ * **The controls are the caller's own elements and the panel adds no wrapper per
+ * control.** A panel that wrapped each filter in its own row would assume the
+ * filters are single-line, which is false of a date range, a multi-select and
+ * anything with a hint under it. The panel is a column; the column's contents are
+ * the caller's, composed out of `Field`, `Checkbox`, `Switch` and `NativeSelect`,
+ * which is where the spacing and the naming of an individual control live.
+ *
+ * It is a server Component. It holds no state, reads no context and attaches no
+ * handler, so a filter column costs no JavaScript from this; the draft state, the
+ * apply handler and the clear handler are all the consumer's, which is the same
+ * argument as the rest of this Component's design and the reason the panel can be
+ * a plain `section` at all.
+ */
+function FilterPanel({ title, summary, actions, label, children, className, ...props }) {
+    const titleId = useId();
+    const named = title !== undefined;
+    const hasHeader = named || summary !== undefined;
+    const hasFooter = actions !== undefined && actions !== null && actions !== false;
+    return (_jsxs("section", { "data-slot": "filter-panel", "aria-labelledby": named ? titleId : undefined, "aria-label": named ? undefined : label, className: cn('bg-card text-card-foreground flex flex-col overflow-hidden rounded-lg border', className), ...props, children: [hasHeader ? (_jsx(FilterPanelHeader, { titleId: titleId, title: title, summary: summary })) : null, _jsx("div", { "data-slot": "filter-panel-body", className: "flex min-w-0 flex-1 flex-col p-4", children: children }), hasFooter ? _jsx(FilterPanelFooter, { children: actions }) : null] }));
+}
+/**
+ * The head of a filter panel: its title, and the caller's account of what is
+ * applied.
+ *
+ * Rendered by `FilterPanel` when either slot is present, and not at all when
+ * neither is, so a panel whose caller has not given it a title does not get a
+ * bordered band with nothing in it. The title element is a `span` carrying the
+ * id the panel points `aria-labelledby` at, rather than a heading: a filter
+ * column in a sidebar is not the heading of the region it sits in, and a heading
+ * here would put an entry in the page outline for a control cluster. A caller who
+ * wants a heading passes an element as `title` and keeps the name.
+ */
+function FilterPanelHeader({ titleId, title, summary, className, ...props }) {
+    return (_jsxs("div", { "data-slot": "filter-panel-header", className: cn('flex flex-col gap-1 border-b px-4 py-3', className), ...props, children: [title === undefined ? null : (_jsx("span", { id: titleId, "data-slot": "filter-panel-title", className: "text-sm font-medium", children: title })), summary === undefined ? null : (_jsx("span", { "data-slot": "filter-panel-summary", className: "text-muted-foreground text-xs", children: summary }))] }));
+}
+/**
+ * The foot of a filter panel, where the apply and clear controls sit.
+ *
+ * On the muted surface and above a rule, for the reason a `ListPanel`'s footer is:
+ * it is the one band that does not scroll with the controls above it, and a
+ * reader who has set five filters has to be able to reach the control that commits
+ * them without scrolling back to a row they have already set. A caller who wants
+ * the pair in the other order, or a third control beside them, passes one slot and
+ * composes what it needs.
+ */
+function FilterPanelFooter({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "filter-panel-footer", className: cn('bg-muted/50 flex items-center gap-3 border-t px-4 py-3', className), ...props }));
+}
+export { FilterPanel, FilterPanelHeader, FilterPanelFooter };

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

@@ -0,0 +1,257 @@
+import { type ReactNode } from 'react';
+/**
+ * Where a form dialog's submission is.
+ *
+ * A closed set of four and not a boolean plus a message, and the reason is the same
+ * one `LifecycleButton` gives: four states do not fit into two answers, and the
+ * two that cannot be expressed are the two that cost the most. `invalid` is a
+ * submission that never left the browser and `failed` is one that did, and a reader
+ * who has been told the two are the same state has been told their work was
+ * rejected by a server when in fact a field was empty.
+ */
+export type FormDialogPhase = 'idle' | 'invalid' | 'submitting' | 'failed';
+/**
+ * One thing wrong with the form, in the caller's own words.
+ *
+ * `field` is the `id` of the control the message belongs to, and the id rather
+ * than the `name` because the summary's entries are anchors to it: a summary entry
+ * that cannot take the reader to the control that caused it is a list they have to
+ * match by eye against a form they then have to read a second time.
+ */
+export type FormDialogIssue = {
+    /** The `id` of the control this message belongs to. */
+    field: string;
+    /** The message, in the product's own words. */
+    message: string;
+};
+/**
+ * The props a FormDialog accepts.
+ *
+ * Two halves, and the split is the argument. The *modal* half is `Dialog`, and
+ * nothing here redraws it. The *submission* half is this Component's own, and it
+ * exists because a validating submit is a state machine with an accessibility
+ * contract attached to it, and neither `Dialog` nor `AlertDialog` nor `Popover`
+ * carries one. The three shapes upstream ships for this are the three ways of
+ * getting that contract wrong, and the refusals are on `FormDialog`: a `Popover`
+ * dismisses on an outside press, so a half-answered form loses its answers; an
+ * `AlertDialog` cannot be dismissed at all, so a long form traps a reader in it;
+ * and a bare `Dialog` with a submit button gives a caller nowhere to put the
+ * running state, so every consumer re-derives one.
+ */
+export interface FormDialogProps {
+    /**
+     * The modal's open state.
+     *
+     * Controlled and required rather than defaulted, because the caller's answer to
+     * "is my form showing" is the fact that decides what happens to a submission in
+     * flight, and a Component that could open itself would be a Component deciding
+     * when a reader's answers are discarded.
+     */
+    open: boolean;
+    /** Called when the open state changes, including on Escape, the close control and an outside press. */
+    onOpenChange: (open: boolean) => void;
+    /**
+     * The content of the control that opens the dialog.
+     *
+     * Required and a node rather than a `ReactElement` to clone, because the trigger
+     * is Prism's `DialogTrigger` and what a caller composes into it is a label or a
+     * label with an icon. The cost is that a caller cannot pass their own `Button`
+     * here without it becoming a button inside a button, and the answer to that is
+     * that they compose `DialogTrigger` themselves in their own layout and use this
+     * Component for the panel.
+     */
+    trigger: ReactNode;
+    /**
+     * Where the submission is.
+     *
+     * Required and controlled, for the same reason `LifecycleButton` is: the caller
+     * owns the request, so the caller owns where the request is. Prism draws the
+     * label, the refusal, the summary and the focus move that a position implies, and
+     * moves nothing itself.
+     */
+    phase: FormDialogPhase;
+    /**
+     * Called when the reader asks to submit, given the form's own element.
+     *
+     * Required, and called only from `idle`. A control that accepted presses while a
+     * submission was running would let a reader queue a second one without knowing
+     * whether the first had landed, which is the double submission
+     * `LifecycleButton` refuses.
+     *
+     * The form element rather than a record of values, because the caller owns the
+     * shape of the form. This Component does not know which controls there are, what
+     * they are called or what a value means, so a values record would be a second
+     * description of the form that could disagree with it.
+     */
+    onSubmit: (form: HTMLFormElement) => void;
+    /**
+     * Called with the form's own values when the reader asks to submit, before
+     * `onSubmit` is reached.
+     *
+     * Optional rather than required, and the omission is the decision: a form with no
+     * rules of its own is the ordinary case, and a required callback would make every
+     * caller write `() => []`. It returns rather than throws, because validation
+     * produces a *list* and a thrown error carries one. An empty array is the ordinary
+     * result and the submission goes ahead; a non-empty one is drawn as the refusal
+     * and `onSubmit` is never called, which is the whole difference between a form
+     * that checks itself and one that asks a network whether it is allowed to try.
+     */
+    validate?: (values: FormData, form: HTMLFormElement) => readonly FormDialogIssue[];
+    /**
+     * The issues to draw in the refusal, given whatever the caller has.
+     *
+     * The second route to the same list as `validate`, and what makes a *server*
+     * refusal drawable: a request that came back with errors has already happened, so
+     * this Component never called `validate`, and a form whose summary can only come
+     * from a local check cannot show what the server said. The two are unioned by
+     * position and never merged, because drawing the local result over the server's
+     * would hide the one the reader needs, which is the sentence saying why the
+     * *server* refused.
+     */
+    issues?: readonly FormDialogIssue[];
+    /** The dialog's heading, and the name every reader hears for it. */
+    title: ReactNode;
+    /** One line under the heading saying what submitting this will do. */
+    description?: ReactNode;
+    /**
+     * The label of the submit control while nothing has been attempted.
+     *
+     * Required and never defaulted: "Create workspace", "Save changes" and "Guardar
+     * cambios" are three products' answers to the same control.
+     */
+    idleLabel: ReactNode;
+    /**
+     * The label of the submit control while the form stands refused.
+     *
+     * Required, and it is the action again rather than a description of the problem,
+     * because the control is still a control the reader can press once they have
+     * fixed what is wrong, and a label that has become an error message is a control
+     * that no longer says what it does.
+     */
+    invalidLabel: ReactNode;
+    /** The label of the submit control while the submission is running. */
+    submittingLabel: ReactNode;
+    /** The label of the submit control after the submission was refused by something. */
+    failedLabel: ReactNode;
+    /**
+     * The heading above the error summary.
+     *
+     * Required, and a heading rather than a sentence because the summary is a focus
+     * target and a reader who lands on it has to know what they have landed on before
+     * they read the list. "There is a problem" and "Two fields need attention" are a
+     * product's two, and only the second one carries the count.
+     */
+    errorSummaryLabel: ReactNode;
+    /**
+     * The words naming one field, given its id.
+     *
+     * Required, and a function of the id rather than of the message for the reason
+     * every readable string here is one. It is also what lets a summary entry name
+     * the *control* rather than repeat the message beside it, so the reader is taken
+     * somewhere and told what it is on the way.
+     */
+    fieldLabel: (field: string) => string;
+    /**
+     * The words of the control that leaves the dialog without submitting.
+     *
+     * Required, and there is always one. A modal whose only way out is its submit
+     * control is a trap a keyboard reader cannot leave, and a reader who opened the
+     * wrong form deserves one keypress back out.
+     */
+    cancelLabel: ReactNode;
+    /**
+     * The accessible name of the built-in close control.
+     *
+     * A prop and not a fixed word, for the reason `Dialog` states: a consumer that
+     * localises its dialog cannot otherwise localise the one control that dismisses
+     * it.
+     */
+    closeLabel?: string;
+    /** The form's own controls, which the caller's `Field` and `Input` compose. */
+    children?: ReactNode;
+    /**
+     * The controls beside cancel and submit.
+     *
+     * Rendered as a slot rather than replacing the two, because a caller who has to
+     * re-derive a refused submit control to add a third button is a caller who gets
+     * the refusal wrong. What belongs here is the *extra* control: a save-as-draft
+     * beside cancel, a destructive delete beside submit.
+     */
+    extraActions?: ReactNode;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * 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.
+ */
+declare function FormDialog({ open, onOpenChange, trigger, phase, onSubmit, validate, issues, title, description, idleLabel, invalidLabel, submittingLabel, failedLabel, errorSummaryLabel, fieldLabel, cancelLabel, closeLabel, children, extraActions, className, }: FormDialogProps): import("react").JSX.Element;
+export { FormDialog };
+//# sourceMappingURL=form-dialog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"form-dialog.d.ts","sourceRoot":"","sources":["../../../src/components/ui/form-dialog.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAsD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAgB1F;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAA;AAE1E;;;;;;;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;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,IAAI,EAAE,OAAO,CAAA;IACb,uGAAuG;IACvG,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC;;;;;;;;;OASG;IACH,OAAO,EAAE,SAAS,CAAA;IAClB;;;;;;;OAOG;IACH,KAAK,EAAE,eAAe,CAAA;IACtB;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACzC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,KAAK,SAAS,eAAe,EAAE,CAAA;IAClF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IACnC,oEAAoE;IACpE,KAAK,EAAE,SAAS,CAAA;IAChB,sEAAsE;IACtE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;OAKG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,CAAA;IACvB,uEAAuE;IACvE,eAAe,EAAE,SAAS,CAAA;IAC1B,qFAAqF;IACrF,WAAW,EAAE,SAAS,CAAA;IACtB;;;;;;;OAOG;IACH,iBAAiB,EAAE,SAAS,CAAA;IAC5B;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC;;;;;;OAMG;IACH,WAAW,EAAE,SAAS,CAAA;IACtB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,SAAS,CAAA;IACxB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,iBAAS,UAAU,CAAC,EAClB,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,KAAK,EACL,WAAW,EACX,SAAS,EACT,YAAY,EACZ,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,SAAS,GACV,EAAE,eAAe,+BAoNjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}