nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Forms/Form.d.ts

@@ -1,6 +1,7 @@
 import { FormStore, type AnyFormStore, type FormStatus } from "../../Helpers/FormStore.ts";
 import type { DatePreferences } from "../../Interfaces/DateInterfaces.ts";
-import type { FormProps, FormValues, InputParams } from "../../Interfaces/FormInterfaces.ts";
+import { type FormProps, type FormValues } from "../../Interfaces/FormInterfaces.ts";
+import { formInputLabel } from "../Inputs/ComputedInput.tsx";
 /**
  * A form store for the page to hold: pass it to a form as `form`, then read, watch, set, and submit through it.
  *
@@ -19,7 +20,7 @@ export declare function useFormStatus(form: AnyFormStore): FormStatus;
 /** The form's own store, or the one given. */
 export declare function useFormStore<TValues extends FormValues>(given: FormStore<TValues> | undefined): FormStore<TValues>;
 /** An input's name in the form's messages: its `fieldName`, its label when it is text, or its name. */
-export declare function formInputLabel(params: InputParams | undefined, name?: string): string;
+export { formInputLabel };
 /** The names a list shows: all of them up to one more than `most` ("and 1 more" says less than the name), else the first `most`. */
 export declare function namesToShow<T>(names: readonly T[], most?: number): {
     shown: readonly T[];
@@ -41,9 +42,9 @@ export declare function formatFormTime(ms: number, preferences: DatePreferences)
  * @example
  * <Form
  *   inputs={[
- *     { type: "text", name: "fullName", label: "Full name", required: true, span: 6 },
- *     { type: "email", name: "email", label: "Email", span: 6 },
- *     { type: "dropdown", name: "role", label: "Role", options: roles, span: 4 },
+ *     { type: EInputTypes.Text, name: "fullName", label: "Full name", required: true, span: 6 },
+ *     { type: EInputTypes.Email, name: "email", label: "Email", span: 6 },
+ *     { type: EInputTypes.Dropdown, name: "role", label: "Role", options: roles, span: 4 },
  *   ]}
  *   defaultValue={employee}
  *   onValueChange={values => saveFilters(values)}

package/dist/Components/Forms/Form.js

@@ -8,9 +8,13 @@ import { useInputDesign } from "../../Helpers/UserPreferences.js";
 import { formatDate, toIsoDate, usesDevanagari } from "../../Helpers/DateHelpers.js";
 import { useDatePreferences } from "../../Helpers/DatePreferences.js";
 import { FormStore } from "../../Helpers/FormStore.js";
-import { inputFieldName } from "../../Helpers/InputParamsHelpers.js";
+import { withInputConditions } from "../../Helpers/InputConditions.js";
+import { formNarrowingNames, narrowInputParamsBy } from "../../Helpers/InputNarrowing.js";
+import { isBooleanInput, isRowsInput } from "../../Helpers/InputParamsHelpers.js";
 import { formatTime } from "../../Helpers/TimeHelpers.js";
+import { EInputTypes } from "../../Interfaces/FormInterfaces.js";
 import { Button } from "../Documents/Button.js";
+import { ComputedInput, formInputLabel } from "../Inputs/ComputedInput.js";
 import { isFirstInvalid } from "../Inputs/InputField.js";
 import { renderInput } from "../Inputs/InputRenderer.js";
 import { firstFocusable } from "../Inputs/RowsInput.js";
@@ -20,11 +24,21 @@ import { firstFocusable } from "../Inputs/RowsInput.js";
  * its own: SubmitForm checks on submit, and a plain <form> around a Form blocks its submit while any input, or the form's
  * own rule, has a problem.
  */
-/** Inputs without a box: they line up with the boxes beside them. */
-const CHOICE_TYPES = new Set(["checkbox", "switch", "radio"]);
 /** What takes focus in an input's cell: a control to type in or pick, before any button of its toolbar. */
 const TYPING_TARGETS = 'input:not([type="hidden"]):not(.nx-visually-hidden):not(:disabled), textarea:not(.nx-visually-hidden):not(:disabled), select:not(:disabled), [contenteditable="true"]';
 const INVALID_CONTROLS = ":is(input, textarea, select):invalid";
+const NO_INPUTS = [];
+const NO_SUBSCRIBE = () => () => { };
+const NO_VERSION = () => 0;
+/** This browser's local storage, or nothing where it cannot be reached (storage switched off). */
+function browserStorage() {
+    try {
+        return window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
 /* Hooks */
 /**
  * A form store for the page to hold: pass it to a form as `form`, then read, watch, set, and submit through it.
@@ -61,11 +75,7 @@ export function useFormStore(given) {
 }
 /* Text */
 /** An input's name in the form's messages: its `fieldName`, its label when it is text, or its name. */
-export function formInputLabel(params, name = "") {
-    if (!params)
-        return name;
-    return inputFieldName(params) ?? (typeof params.label === "string" ? params.label : params.name);
-}
+export { formInputLabel };
 /** The names a list shows: all of them up to one more than `most` ("and 1 more" says less than the name), else the first `most`. */
 export function namesToShow(names, most = 3) {
     return names.length <= most + 1 ? { shown: names, more: 0 } : { shown: names.slice(0, most), more: names.length - most };
@@ -90,13 +100,48 @@ export function formatFormTime(ms, preferences) {
         return time;
     return `${formatDate(date, preferences)}, ${time}`;
 }
+/* Cells */
+/**
+ * What the page passed as the form's `computeWith`, for the inputs worked out from it (`compute`): one object for the
+ * form's life, so the cells' context stays the same and only the worked-out inputs draw again when it changes.
+ */
+class ComputeSource {
+    listeners = new Set();
+    version = 0;
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    set(value) {
+        if (Object.is(value, this.value))
+            return;
+        this.value = value;
+        this.version++;
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    getVersion = () => this.version;
+}
 const spanOf = (params) => Math.max(1, Math.min(12, Math.round(params.span ?? 12)));
 /** A checkbox, switch, or radio that shares a row with labeled boxes: it lines up with their boxes, below their labels. */
-const besideBoxes = (params, span, design) => CHOICE_TYPES.has(params.type) && span < 12 && (design ?? "standard") === "standard";
+const besideBoxes = (params, span, design) => isBooleanInput(params) && span < 12 && (design ?? "standard") === "standard";
 /** The input. It starts from the store's value and reports each change; a new stamp mounts it again with a new value. */
-function FieldInput({ store, params, stamp, error, context }) {
+function FieldInput({ store, params, stamp, error, context, cell, heldFocus }) {
     const [initial] = useState(() => store.get(params.name));
-    const onValueChange = useCallback((value) => store.input(params.name, value, stamp), [store, params.name, stamp]);
+    // Runs before the input leaves the page (a new stamp: a value from code, a load, a remembered value a picker gave
+    // late): a focus inside it is noted, or it would fall to the page with nothing said.
+    useLayoutEffect(() => () => {
+        const active = typeof document === "undefined" ? null : document.activeElement;
+        if (active && cell.current?.contains(active))
+            heldFocus.current = true;
+    }, [cell, heldFocus]);
+    const onValueChange = useCallback((value, item) => store.input(params.name, value, stamp, item), [store, params.name, stamp]);
     const own = params;
     const overrides = {
         id: `${context.idPrefix}-${params.name}`,
@@ -108,13 +153,51 @@ function FieldInput({ store, params, stamp, error, context }) {
     };
     if (context.design && !own.design)
         overrides.design = context.design;
-    if (context.scopeNames && params.type === "radio-group")
+    if (context.scopeNames && params.type === EInputTypes.RadioGroup)
         overrides.name = `${context.idPrefix}:${params.name}`;
     // Only a message from the form replaces the input's own.
     if (error !== undefined)
         overrides.error = error;
-    return renderInput(params, overrides);
+    // A picker asked whether it still offers the remembered value (`remember`): its spinner shows until it answers.
+    if (store.isRemembering(params.name))
+        overrides.loading = true;
+    // Options another input narrows (`narrowedBy`): read with its value as it is now; the cell draws again when it changes.
+    // Copied afresh on every draw, never kept: the copy reads the params' getters, and one that `dependsOn` follows
+    // (readOnly, hint, label, options; span is read by the cell) must answer for the values of this draw. The box keeps its loaded pages by `loadKey`.
+    const shown = params.narrowedBy ? narrowInputParamsBy(params, narrowing => ({ value: store.get(narrowing.name), label: store.inputParams(narrowing.name)?.label })) : params;
+    // Rows whose inputs follow this form's values (`narrowedBy` `from: "form"`): handed them as they are now; the rows input
+    // draws again when one changes (it follows them as `dependsOn` would).
+    const rowInputs = isRowsInput(params) ? (params.inputs ?? []) : NO_INPUTS;
+    if (rowInputs.length) {
+        const names = formNarrowingNames(rowInputs);
+        if (names.length)
+            overrides.formValues = Object.fromEntries(names.map(name => [name, { value: store.get(name), label: store.inputParams(name)?.label }]));
+    }
+    // Rows with inputs worked out from others (`compute`) get the form's `computeWith`, unless their params name their own;
+    // the rows input draws again when the page passes a new one.
+    const handsCompute = rowInputs.some(input => input.compute) && !("computeWith" in params);
+    const source = context.computeWith;
+    useSyncExternalStore(handsCompute ? source.subscribe : NO_SUBSCRIBE, handsCompute ? source.getVersion : NO_VERSION, handsCompute ? source.getVersion : NO_VERSION);
+    if (handsCompute)
+        overrides.computeWith = source.value;
+    return renderInput(shown, overrides);
 }
+/**
+ * An input worked out from others (`compute`) in a form: `ComputedInput` reading the form's values and its `computeWith`
+ * (it alone draws again when the page passes a new one), and writing a typed-in figure's answer as the person's change.
+ */
+function ComputedField({ store, params, context }) {
+    const source = context.computeWith;
+    useSyncExternalStore(source.subscribe, source.getVersion, source.getVersion);
+    const { idPrefix } = context;
+    const read = useCallback(() => store.getValue(), [store]);
+    const write = useCallback((values) => void store.setFromPerson(values), [store]);
+    const inputParams = useCallback((name) => store.inputParams(name), [store]);
+    const sourceId = useCallback((name) => `${idPrefix}-${name}`, [idPrefix]);
+    return (_jsx(ComputedInput, { params: params, id: `${idPrefix}-${params.name}`, read: read, withValue: source.value, write: write, inputParams: inputParams, sourceId: sourceId, size: context.size, design: context.design, loading: context.loading, readOnly: context.readOnly, disabled: context.disabled }));
+}
+/** The control an input mounted again takes the focus back in: its box, a list's combobox, a choice, an editor. */
+const REFOCUSABLE = '[role="combobox"]:not([disabled]), input:not([type="hidden"]):not([disabled]):not([tabindex="-1"]), textarea:not([disabled]), select:not([disabled]), [contenteditable="true"], button:not([disabled]):not([tabindex="-1"])';
 /** One input's place on the grid. It renders again only when its input must: a message from the form, or a value from code. */
 const FormCell = memo(function FormCell({ store, params, context }) {
     const { name } = params;
@@ -122,6 +205,23 @@ const FormCell = memo(function FormCell({ store, params, context }) {
     const version = () => store.fieldVersion(name);
     useSyncExternalStore(subscribe, version, version);
     const stamp = store.stamp(name);
+    const cellRef = useRef(null);
+    const heldFocus = useRef(false);
+    // An input mounted again while it had the focus gets it back in its new control (the checked choice of a group
+    // first): a person in the box stays there, and a screen reader says the box again with the value it now holds.
+    useLayoutEffect(() => {
+        if (!heldFocus.current)
+            return;
+        heldFocus.current = false;
+        const cell = cellRef.current;
+        const active = document.activeElement;
+        if (!cell || (active && active !== document.body && cell.contains(active)))
+            return;
+        const target = cell.querySelector("input:checked:not([disabled])") ?? cell.querySelector(REFOCUSABLE);
+        target?.focus({ preventScroll: true });
+    }, [stamp]);
+    // Read on every draw: a `span` getter, or `spanWhen`, answers for the values as they are now. The input below keeps
+    // its key, so a new width never mounts it again: what is typed, the caret and the focus stay.
     const span = spanOf(params);
     // The design the inputs draw in, the person's choice included: choice boxes sit beside others only in `standard`.
     const design = useInputDesign(context.design);
@@ -134,7 +234,7 @@ const FormCell = memo(function FormCell({ store, params, context }) {
             return;
         store.touch(name);
     }
-    return (_jsx("div", { className: cx("nx-form__cell", CHOICE_TYPES.has(params.type) && "nx-form__cell--choice"), style: { "--nx-span": span }, "data-span": span, "data-beside": besideBoxes(params, span, design) || undefined, "data-nx-field": name, onBlur: onBlur, children: _jsx(FieldInput, { store: store, params: params, stamp: stamp, error: store.shownError(name), context: context }, stamp) }));
+    return (_jsx("div", { className: cx("nx-form__cell", isBooleanInput(params) && "nx-form__cell--choice"), style: { "--nx-span": span }, "data-span": span, "data-beside": besideBoxes(params, span, design) || undefined, "data-nx-field": name, onBlur: onBlur, ref: cellRef, children: params.compute ? (_jsx(ComputedField, { store: store, params: params, context: context })) : (_jsx(FieldInput, { store: store, params: params, stamp: stamp, error: store.shownError(name), context: context, cell: cellRef, heldFocus: heldFocus }, stamp)) }));
 });
 /** The note over a form whose unsaved changes came back from a draft. */
 function DraftNotice({ store, restored, inputs, preferences }) {
@@ -155,18 +255,24 @@ function DraftNotice({ store, restored, inputs, preferences }) {
  * @example
  * <Form
  *   inputs={[
- *     { type: "text", name: "fullName", label: "Full name", required: true, span: 6 },
- *     { type: "email", name: "email", label: "Email", span: 6 },
- *     { type: "dropdown", name: "role", label: "Role", options: roles, span: 4 },
+ *     { type: EInputTypes.Text, name: "fullName", label: "Full name", required: true, span: 6 },
+ *     { type: EInputTypes.Email, name: "email", label: "Email", span: 6 },
+ *     { type: EInputTypes.Dropdown, name: "role", label: "Role", options: roles, span: 4 },
  *   ]}
  *   defaultValue={employee}
  *   onValueChange={values => saveFilters(values)}
  * />
  */
 export function Form(props) {
-    const { inputs, design, size = "md", readOnly = false, disabled = false, loading = false, draftKey, id, className, style, ref } = props;
+    const { design, size = "md", readOnly = false, disabled = false, loading = false, draftKey, id, className, style, ref } = props;
     const store = useFormStore(props.form);
     const anyStore = store;
+    // What the page passes for the worked-out inputs (`compute`): they alone draw again when it changes.
+    const [computeWith] = useState(() => new ComputeSource(props.computeWith));
+    useLayoutEffect(() => computeWith.set(props.computeWith), [computeWith, props.computeWith]);
+    // An input with `showWhen` gets a live `hidden`, one with `readOnlyWhen` a live `readOnly`, that reads this store; it
+    // follows the inputs they name (`dependsOn`).
+    const inputs = useMemo(() => withInputConditions(props.inputs, name => anyStore.get(name)), [props.inputs, anyStore]);
     const preferences = useDatePreferences();
     const idPrefix = useId();
     const rootRef = useRef(null);
@@ -190,6 +296,13 @@ export function Form(props) {
         rulesRef.current = rulesKey;
         store.configure(options, !previous || rulesKey.some((item, index) => !Object.is(item, previous[index])));
     });
+    // Remembered inputs (`remember`) read and keep their values in this browser: given once drawn - after the store has
+    // these inputs (a store a CRUD loaded first takes them in the effect above) - so the first draw is the same on a
+    // server and in the browser, and they open on what is kept before the first paint.
+    useLayoutEffect(() => {
+        if (inputs.some(params => params.remember))
+            store.attachMemory(browserStorage());
+    }, [store, inputs]);
     useLayoutEffect(() => store.setLoading(loading), [store, loading]);
     useImperativeHandle(ref, () => store, [store]);
     // Radio groups need names of their own when no <form> keeps them apart.
@@ -208,7 +321,7 @@ export function Form(props) {
             }
         }
         const fromValues = new Set(store.problems());
-        const names = latest.current.inputs.filter(params => !params.hidden && (invalid.has(params.name) || fromValues.has(params.name))).map(params => params.name);
+        const names = anyStore.inputs.filter(params => !params.hidden && (invalid.has(params.name) || fromValues.has(params.name))).map(params => params.name);
         return { names, invalid, fromValues };
     }
     function focusInput(name) {
@@ -253,7 +366,7 @@ export function Form(props) {
             const proxy = proxyRef.current;
             if (!proxy)
                 return;
-            const first = latest.current.inputs.find(params => !params.hidden && store.formRuleError(params.name));
+            const first = anyStore.inputs.find(params => !params.hidden && store.formRuleError(params.name));
             proxy.setCustomValidity((first ? store.formRuleError(first.name) : store.formRuleMessage) ?? "");
         };
         const recount = () => {
@@ -311,7 +424,7 @@ export function Form(props) {
     }
     // While the values load, the real inputs show, disabled: the form has its final shape from the first frame, so a
     // popup around it never jumps when the record lands. The store refuses anything typed until then.
-    const context = useMemo(() => ({ idPrefix, size, design, readOnly, disabled: disabled || loading, scopeNames: !inForm }), [idPrefix, size, design, readOnly, disabled, loading, inForm]);
+    const context = useMemo(() => ({ idPrefix, size, design, readOnly, disabled: disabled || loading, loading, scopeNames: !inForm, computeWith }), [idPrefix, size, design, readOnly, disabled, loading, inForm, computeWith]);
     // With FormButtons on the page, the form's message is in their status line.
     const ownMessage = status.buttons === 0 ? status.message : null;
     return (_jsxs("div", { ref: rootRef, id: id, className: cx("nx-form", `nx-form--${size}`, className), style: style, "data-nx-form": "", "aria-busy": loading || undefined, children: [status.restored && !loading && _jsx(DraftNotice, { store: anyStore, restored: status.restored, inputs: inputs, preferences: preferences }), _jsx("div", { className: "nx-form__grid", children: inputs.filter(params => params.dependsOn?.length || !params.hidden).map((params, index, visible) => (_jsxs(Fragment, { children: [params.section && (index === 0 || visible[index - 1]?.section !== params.section) && _jsx("h3", { className: "nx-form__section", children: params.section }), _jsx(FormCell, { store: anyStore, params: params, context: context })] }, params.name))) }), loading && (_jsx("p", { className: "nx-visually-hidden", role: "status", children: "Loading\u2026" })), _jsx("input", { ref: proxyRef, className: "nx-visually-hidden", tabIndex: -1, "aria-hidden": "true", disabled: locked, onInvalid: onProxyInvalid }), ownMessage && (_jsxs("p", { className: "nx-form__message nx-field__message nx-field__message--error", role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: ownMessage })] }))] }));

package/dist/Components/Forms/FormLeaveGuard.d.ts

@@ -0,0 +1,44 @@
+import type { AnyFormStore } from "../../Helpers/FormStore.ts";
+/** One form a guard watches: its store, and whether it has changes that leaving would lose now. */
+export interface GuardedForm {
+    form: AnyFormStore;
+    changed: () => boolean;
+}
+/** The forms in a place, as they come and go. */
+export declare class FormLeaveGuard {
+    private readonly forms;
+    /** Watches a form until the function it answers is called (the form leaves). */
+    watch(entry: GuardedForm): () => void;
+    /** The first form with changes that leaving would lose, or `undefined`. */
+    changed(): AnyFormStore | undefined;
+}
+/** The guard of the place a form is drawn in; `null` outside one. */
+export declare const FormLeaveGuardContext: import("react").Context<FormLeaveGuard | null>;
+/**
+ * The page's own forms: the ones a navigation inside the app takes away with the page. A `SubmitForm` (and so an
+ * `ApiForm`) that asks before the page closes joins it too, unless it is drawn in a `PopupHost` popup, which stays open
+ * through a navigation. A link inside the app and `confirmPageLeave()` ask "Discard your changes?" while one has changes.
+ */
+export declare class PageLeaveGuard extends FormLeaveGuard {
+    private allowedUntil;
+    private unloading;
+    /** Lets the page's forms go without asking for a moment: a navigation the person confirmed, until it has started. */
+    allow(ms?: number): void;
+    /**
+     * Lets every form go, the page's and the popups', until the page itself goes (`pagehide`): a full-page move the person
+     * confirmed (a sign-out, `location.assign`), however long its own call takes first. `end()` takes it back.
+     */
+    allowUnload(): void;
+    /** Asks again: a confirmed move that did not happen (its call failed, the page stays). */
+    end(): void;
+    /** Whether a confirmed navigation is under way, so neither a link nor a page form's close question asks again. */
+    get allowed(): boolean;
+    /** Whether a confirmed full-page move is under way: only then a popup form's close question is not asked either. */
+    get unloadAllowed(): boolean;
+}
+/** The one page guard of this browser tab. */
+export declare const pageLeaveGuard: PageLeaveGuard;
+/** Every form a full-page load takes away: the page's and the ones in popups (`confirmPageLeave({ unload: true })`). */
+export declare const unloadLeaveGuard: FormLeaveGuard;
+/** The page guard a form joins: the tab's, or `null` inside a place that outlives a navigation (a `PopupHost` popup). */
+export declare const PageLeaveGuardContext: import("react").Context<PageLeaveGuard | null>;

package/dist/Components/Forms/FormLeaveGuard.js

@@ -0,0 +1,65 @@
+"use client";
+import { createContext } from "react";
+/** The forms in a place, as they come and go. */
+export class FormLeaveGuard {
+    forms = new Set();
+    /** Watches a form until the function it answers is called (the form leaves). */
+    watch(entry) {
+        this.forms.add(entry);
+        return () => {
+            this.forms.delete(entry);
+        };
+    }
+    /** The first form with changes that leaving would lose, or `undefined`. */
+    changed() {
+        for (const entry of this.forms)
+            if (entry.changed())
+                return entry.form;
+        return undefined;
+    }
+}
+/** The guard of the place a form is drawn in; `null` outside one. */
+export const FormLeaveGuardContext = createContext(null);
+/**
+ * The page's own forms: the ones a navigation inside the app takes away with the page. A `SubmitForm` (and so an
+ * `ApiForm`) that asks before the page closes joins it too, unless it is drawn in a `PopupHost` popup, which stays open
+ * through a navigation. A link inside the app and `confirmPageLeave()` ask "Discard your changes?" while one has changes.
+ */
+export class PageLeaveGuard extends FormLeaveGuard {
+    allowedUntil = 0;
+    unloading = false;
+    /** Lets the page's forms go without asking for a moment: a navigation the person confirmed, until it has started. */
+    allow(ms = 1500) {
+        this.allowedUntil = Date.now() + ms;
+    }
+    /**
+     * Lets every form go, the page's and the popups', until the page itself goes (`pagehide`): a full-page move the person
+     * confirmed (a sign-out, `location.assign`), however long its own call takes first. `end()` takes it back.
+     */
+    allowUnload() {
+        if (this.unloading)
+            return;
+        this.unloading = true;
+        if (typeof window !== "undefined")
+            window.addEventListener("pagehide", () => this.end(), { once: true });
+    }
+    /** Asks again: a confirmed move that did not happen (its call failed, the page stays). */
+    end() {
+        this.unloading = false;
+        this.allowedUntil = 0;
+    }
+    /** Whether a confirmed navigation is under way, so neither a link nor a page form's close question asks again. */
+    get allowed() {
+        return this.unloading || Date.now() < this.allowedUntil;
+    }
+    /** Whether a confirmed full-page move is under way: only then a popup form's close question is not asked either. */
+    get unloadAllowed() {
+        return this.unloading;
+    }
+}
+/** The one page guard of this browser tab. */
+export const pageLeaveGuard = new PageLeaveGuard();
+/** Every form a full-page load takes away: the page's and the ones in popups (`confirmPageLeave({ unload: true })`). */
+export const unloadLeaveGuard = new FormLeaveGuard();
+/** The page guard a form joins: the tab's, or `null` inside a place that outlives a navigation (a `PopupHost` popup). */
+export const PageLeaveGuardContext = createContext(pageLeaveGuard);

package/dist/Components/Forms/FormQuestion.d.ts

@@ -0,0 +1,6 @@
+import type { FormConfirmQuestion } from "../../Helpers/FormConfirm.ts";
+/**
+ * Asks a settled question (`formConfirmQuestion`): a question box with what will be saved drawn as a record's details,
+ * Confirm holding the focus, a press outside it changing nothing. Resolves whether to go on; an abort answers no.
+ */
+export declare function askFormQuestion(question: FormConfirmQuestion, signal?: AbortSignal): Promise<boolean>;

package/dist/Components/Forms/FormQuestion.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { messageBox } from "../Layouts/MessageBox.js";
+import { CrudDetails } from "./CrudParts.js";
+/*
+ * The question asked before a save, drawn once for every place that asks it: a form's `confirm` (SubmitForm) and a row
+ * form's, including a row action that is its question alone (CrudRowForms.tsx). Not exported from the package: a page
+ * asks through those params.
+ */
+/**
+ * Asks a settled question (`formConfirmQuestion`): a question box with what will be saved drawn as a record's details,
+ * Confirm holding the focus, a press outside it changing nothing. Resolves whether to go on; an abort answers no.
+ */
+export function askFormQuestion(question, signal) {
+    const details = question.details;
+    return messageBox.confirm({
+        tone: "question",
+        closable: true,
+        closeOnBackdrop: false,
+        signal,
+        size: question.size,
+        title: question.title,
+        message: question.message,
+        details: details ? _jsx(CrudDetails, { row: details.row, columns: details.columns, currency: details.currency }) : null,
+        confirmLabel: question.confirmLabel,
+        cancelLabel: question.cancelLabel,
+    });
+}

package/dist/Components/Forms/RecordFlows.d.ts

@@ -0,0 +1,50 @@
+import { type ReactNode } from "react";
+import { type RecordWriteRequest } from "../../Helpers/RecordCards.ts";
+import type { ApiResult, ApiTarget } from "../../Interfaces/ApiInterfaces.ts";
+import type { ApiRequest, InputParams } from "../../Interfaces/FormInterfaces.ts";
+import type { RecordConfirmParams, RecordContext, RecordFlowParams } from "../../Interfaces/RecordInterfaces.ts";
+import { type PopupHandle } from "../Layouts/PopupHost.tsx";
+/** What a popup works with: the card's data as held now, and the page's ways to write it and to end the session. */
+export interface RecordFlowHost<TData = any, TItem = any> {
+    /** The card's data and the item, as held now. */
+    context: () => RecordContext<TData, TItem>;
+    /** Draws the popup again when the page's data changes. */
+    subscribe: (listener: () => void) => () => void;
+    snapshot: () => unknown;
+    /** Writes an answer into the card's data, as `writes` says. */
+    write: (request: Pick<RecordWriteRequest, "writes" | "result" | "values" | "fallback">) => Promise<void>;
+    /** A refusal that ended the session: the page shows its words and closes its popups. Answers whether it was one. */
+    ended: (answer: ApiResult) => boolean;
+    /** Keeps the popup, so an ended session closes it, and the focus comes home after it. */
+    track: (popup: PopupHandle) => void;
+}
+export interface RecordFlowRequest<TData = any, TItem = any> {
+    flow: RecordFlowParams<TData, TItem>;
+    host: RecordFlowHost<TData, TItem>;
+    /** One popup per key: opened again, it comes back as it was. */
+    key: string;
+    /** The popup's title and line when the flow names neither. */
+    title: ReactNode;
+    description?: ReactNode;
+    /**
+     * `edit`: a card's Edit - its inputs when the flow names none, opened on the data, its values merged over the data as
+     * held now when sent and written back when the answer is no record. `add`: the values alone. `item`: opened on the item,
+     * its values merged over it.
+     */
+    kind: "edit" | "add" | "item";
+    inputs?: readonly InputParams[];
+}
+/** Where a change goes, sent through the app's `api` without its toasts: an endpoint, a URL (POST), a request, or a function. */
+export declare function sendRecordCall(submit: ApiTarget | ApiRequest | ((body: unknown) => Promise<unknown>), body: unknown): Promise<ApiResult>;
+/**
+ * Opens a record page's popup: one per key, brought back as it was when it is open. Each step is a form (none of its
+ * inputs is required: a step can be its sentence and its button); its answer is written into the card's data, then the
+ * step's `next` shows, or the popup closes and `done` runs. Closing with changes asks first, unless the step says there
+ * is nothing worth keeping.
+ */
+export declare function openRecordFlow<TData, TItem>(request: RecordFlowRequest<TData, TItem>): PopupHandle;
+/**
+ * A change that needs no form: the question first ("Remove ram@example.com?"), then the call, its answer written into
+ * the card's data. `busy` marks the item while it runs. A refusal is said in a toast, in the server's words.
+ */
+export declare function runRecordConfirm<TData, TItem>(confirm: RecordConfirmParams<TData, TItem>, host: RecordFlowHost<TData, TItem>, busy: (on: boolean) => void): Promise<void>;