nexus-shared 1.1.21 → 3.0.0

package/dist/Components/Forms/Form.js

@@ -0,0 +1,323 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { iconAlertCircle, iconHistory, iconX, InlineIcon } from "nexus-icons";
+import { memo, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.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 { formatTime } from "../../Helpers/TimeHelpers.js";
+import { Button } from "../Documents/Button.js";
+import { hasContent } from "../Inputs/Field.js";
+import { isFirstInvalid } from "../Inputs/InputField.js";
+import { renderInput } from "../Inputs/InputRenderer.js";
+import { firstFocusable } from "../Inputs/RowsInput.js";
+/*
+ * Form: a list of input params on a 12-column grid, with the values in a FormStore. Typing renders only the input
+ * typed in; an input renders again when a message it shows changes or code sets its value. The form checks nothing on
+ * 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"]);
+/** Inputs taller than one line, for the placeholders shown while the values load. */
+const TALL_TYPES = new Set(["textarea", "markdown", "rich-text", "tree", "tabular", "group", "checkbox-group", "radio-group"]);
+/** 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";
+/* Hooks */
+/**
+ * A form store for the page to hold: pass it to a form as `form`, then read, watch, set, and submit through it.
+ *
+ * @example
+ * const form = useForm<Employee>();
+ * const country = useFormValue<string>(form, "country");
+ * <SubmitForm form={form} inputs={inputs} onSubmit={save} />
+ */
+export function useForm() {
+    const [store] = useState(() => new FormStore());
+    return store;
+}
+/** One value of a form; the component renders again only when it changes. */
+export function useFormValue(form, name) {
+    const store = form;
+    const read = () => store.get(name);
+    return useSyncExternalStore(store.subscribeValue, read, read);
+}
+/** Every value of a form; the component renders again on every change, so keep it to small forms or summaries. */
+export function useFormValues(form) {
+    const read = () => form.getValue();
+    return useSyncExternalStore(form.subscribeValue, read, read);
+}
+/** What the form's frame shows: changed, submitting, problems, the form's message, drafts. */
+export function useFormStatus(form) {
+    const store = form;
+    return useSyncExternalStore(store.subscribeStatus, store.getStatus, store.getStatus);
+}
+/** The form's own store, or the one given. */
+export function useFormStore(given) {
+    const [own] = useState(() => (given ? null : new FormStore()));
+    return given ?? own;
+}
+/* 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);
+}
+/** 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 };
+}
+/** Names in a sentence: "A", "A and B", "A, B, and C", "A, B, C, and 3 more". */
+export function listInSentence(names, most = 3) {
+    const { shown, more } = namesToShow(names, most);
+    if (more)
+        return `${shown.join(", ")}, and ${more} more`;
+    if (shown.length <= 1)
+        return shown[0] ?? "";
+    if (shown.length === 2)
+        return `${shown[0]} and ${shown[1]}`;
+    return `${shown.slice(0, -1).join(", ")}, and ${shown[shown.length - 1]}`;
+}
+/** A moment in the user's time format, with the date in their calendar when it was not today. */
+export function formatFormTime(ms, preferences) {
+    const date = new Date(ms);
+    const script = usesDevanagari(preferences.calendar, preferences.script) ? "devanagari" : "latin";
+    const time = formatTime(date, { format: preferences.timeFormat, script });
+    if (toIsoDate(date) === toIsoDate(new Date()))
+        return time;
+    return `${formatDate(date, preferences)}, ${time}`;
+}
+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";
+/** 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 }) {
+    const [initial] = useState(() => store.get(params.name));
+    const onValueChange = useCallback((value) => store.input(params.name, value, stamp), [store, params.name, stamp]);
+    const own = params;
+    const overrides = {
+        id: `${context.idPrefix}-${params.name}`,
+        defaultValue: initial,
+        onValueChange,
+        size: own.size ?? context.size,
+        readOnly: context.readOnly,
+        disabled: context.disabled,
+    };
+    if (context.design && !own.design)
+        overrides.design = context.design;
+    if (context.scopeNames && params.type === "radio-group")
+        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);
+}
+/** 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;
+    const subscribe = useCallback((listener) => store.subscribeField(name, listener), [store, name]);
+    const version = () => store.fieldVersion(name);
+    useSyncExternalStore(subscribe, version, version);
+    const stamp = store.stamp(name);
+    const span = spanOf(params);
+    // An input that follows others is asked whether it shows each time it draws: it comes and goes with their values.
+    if (params.dependsOn?.length && params.hidden)
+        return null;
+    // Leaving the input shows the form's own rule message on it, such as "Passwords do not match".
+    function onBlur(event) {
+        if (event.relatedTarget instanceof Node && event.currentTarget.contains(event.relatedTarget))
+            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, context.design) || undefined, "data-nx-field": name, onBlur: onBlur, children: _jsx(FieldInput, { store: store, params: params, stamp: stamp, error: store.shownError(name), context: context }, stamp) }));
+});
+/** A placeholder in an input's shape while the values load. */
+function SkeletonCell({ params, design }) {
+    const span = spanOf(params);
+    const choice = CHOICE_TYPES.has(params.type);
+    const ownDesign = params.design ?? design ?? "standard";
+    return (_jsxs("div", { className: cx("nx-form__cell", "nx-form__skeleton", choice && "nx-form__cell--choice"), style: { "--nx-span": span }, "data-span": span, "data-beside": besideBoxes(params, span, design) || undefined, children: [!choice && ownDesign === "standard" && hasContent(params.label) && _jsx("span", { className: "nx-form__skeleton-label" }), _jsx("span", { className: cx("nx-form__skeleton-box", TALL_TYPES.has(params.type) && "nx-form__skeleton-box--tall", choice && "nx-form__skeleton-box--choice") })] }));
+}
+/** The note over a form whose unsaved changes came back from a draft. */
+function DraftNotice({ store, restored, inputs, preferences }) {
+    const label = (name) => formInputLabel(inputs.find(params => params.name === name), name);
+    const conflicts = restored.conflicts.map(label);
+    return (_jsxs("div", { className: "nx-form__notice", role: "status", children: [_jsx(InlineIcon, { icon: iconHistory }), _jsxs("p", { className: "nx-form__notice-text", children: ["Restored your unsaved changes from ", formatFormTime(restored.savedAt, preferences), ": ", listInSentence(restored.names.map(label)), ".", conflicts.length > 0 && (_jsxs("strong", { children: [" ", listInSentence(conflicts), " also changed on the server since; check ", conflicts.length === 1 ? "it" : "them", " before you save."] }))] }), _jsx(Button, { size: "sm", variant: "ghost", hoverTone: "danger", onClick: () => store.discardDraft(), children: "Discard" }), _jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconX }), "aria-label": "Keep the changes and close this note", title: "Close", onClick: () => store.dismissDraft() })] }));
+}
+/* Form */
+/**
+ * Renders a list of input params on a 12-column grid (`span` in each input's params), with the values in a store outside
+ * React, so a form of any size types as fast as one input. The same params describe every input, so a CRUD page or a
+ * server can build a form from plain objects; a tabular or group input is one entry that holds rows.
+ *
+ * On its own it suits filters and settings that save as they change (`onValueChange`). `SubmitForm` adds checks on
+ * submit and the buttons; `ApiForm` sends the values to a server. Inside a plain `<form>`, each input sends its value
+ * under its name, and the form's own rule blocks the submit while it fails.
+ *
+ * @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 },
+ *   ]}
+ *   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 store = useFormStore(props.form);
+    const anyStore = store;
+    const preferences = useDatePreferences();
+    const idPrefix = useId();
+    const rootRef = useRef(null);
+    const proxyRef = useRef(null);
+    const latest = useRef(props);
+    latest.current = props;
+    const locked = readOnly || disabled;
+    const options = { inputs, validate: props.validate, onFieldChange: props.onFieldChange, context: { preferences }, locked, draftKey };
+    // The first render loads the values quietly, so the inputs mount with them; the page hears of it once mounted. A store
+    // that already has values (from `useForm`, a form shown again) keeps them.
+    if (!store.started) {
+        store.configure(options, false);
+        store.load(props.defaultValue ?? {}, { draft: !loading, quiet: true });
+    }
+    useLayoutEffect(() => store.announce(), [store]);
+    // Inputs or settings that change what is valid check every value again; callbacks only swap.
+    const rulesKey = [inputs, preferences, locked, draftKey];
+    const rulesRef = useRef(null);
+    useLayoutEffect(() => {
+        const previous = rulesRef.current;
+        rulesRef.current = rulesKey;
+        store.configure(options, !previous || rulesKey.some((item, index) => !Object.is(item, previous[index])));
+    });
+    useLayoutEffect(() => store.setLoading(loading), [store, loading]);
+    useImperativeHandle(ref, () => store, [store]);
+    // Radio groups need names of their own when no <form> keeps them apart.
+    const [inForm, setInForm] = useState(true);
+    useLayoutEffect(() => setInForm(Boolean(rootRef.current?.closest("form"))), []);
+    const status = useFormStatus(store);
+    /** The inputs on the page that report a problem, and those the values fail, in form order. Fires no events. */
+    function findProblems() {
+        const root = rootRef.current;
+        const invalid = new Map();
+        if (root) {
+            for (const cell of root.querySelectorAll(":scope > .nx-form__grid > [data-nx-field]")) {
+                const controls = cell.querySelectorAll(INVALID_CONTROLS);
+                if (controls.length)
+                    invalid.set(cell.dataset.nxField ?? "", [...controls]);
+            }
+        }
+        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);
+        return { names, invalid, fromValues };
+    }
+    function focusInput(name) {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const cell = root.querySelector(`:scope > .nx-form__grid > [data-nx-field${name === undefined ? "" : `="${CSS.escape(name)}"`}]`);
+        if (!cell)
+            return;
+        const target = cell.querySelector(TYPING_TARGETS) ?? firstFocusable(cell);
+        target?.focus();
+    }
+    const view = {
+        validate() {
+            const { names, invalid, fromValues } = findProblems();
+            // A problem the values have and the input on the page does not show: the form shows its message on the input.
+            const forced = [...fromValues].filter(name => !invalid.has(name) && store.ruleError(name));
+            store.reveal(names, forced);
+            // Every input shows its own message, and the first in the form takes focus.
+            for (const controls of invalid.values())
+                for (const control of controls)
+                    control.checkValidity();
+            const first = names[0];
+            // After the inputs' own focus, which a list of rows moves in the next frame.
+            if (first && !invalid.has(first))
+                requestAnimationFrame(() => focusInput(first));
+            return names;
+        },
+        focus: focusInput,
+    };
+    useLayoutEffect(() => {
+        store.view = view;
+        return () => {
+            if (store.view === view)
+                store.view = null;
+        };
+    });
+    // Page-level listeners: the page's `onValueChange`, the problem list after a submit, and the proxy's validity.
+    useEffect(() => {
+        let frame = 0;
+        const syncProxy = () => {
+            const proxy = proxyRef.current;
+            if (!proxy)
+                return;
+            const first = latest.current.inputs.find(params => !params.hidden && store.formRuleError(params.name));
+            proxy.setCustomValidity((first ? store.formRuleError(first.name) : store.formRuleMessage) ?? "");
+        };
+        const recount = () => {
+            frame = 0;
+            if (store.getStatus().showAll)
+                store.setAttention(findProblems().names);
+        };
+        syncProxy();
+        const unsubscribe = store.subscribeValue((values, name) => {
+            syncProxy();
+            if (store.getStatus().showAll && !frame)
+                frame = requestAnimationFrame(recount);
+            latest.current.onValueChange?.(values, name);
+        });
+        return () => {
+            unsubscribe();
+            cancelAnimationFrame(frame);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store]);
+    // Inside a <form>: a reset brings back the values the form opened with.
+    useEffect(() => {
+        const form = rootRef.current?.closest("form");
+        if (!form)
+            return;
+        const onReset = () => store.reset();
+        form.addEventListener("reset", onReset);
+        return () => form.removeEventListener("reset", onReset);
+    }, [store]);
+    // A draft is written when the page hides or the form leaves, so a change typed just before is kept too.
+    useEffect(() => {
+        if (!draftKey)
+            return;
+        const flush = () => store.flushDraft();
+        const onVisibility = () => {
+            if (document.visibilityState === "hidden")
+                flush();
+        };
+        window.addEventListener("pagehide", flush);
+        document.addEventListener("visibilitychange", onVisibility);
+        return () => {
+            window.removeEventListener("pagehide", flush);
+            document.removeEventListener("visibilitychange", onVisibility);
+            flush();
+        };
+    }, [store, draftKey]);
+    /** A native submit of the <form> around found the form's own rule failing. */
+    function onProxyInvalid(event) {
+        event.preventDefault();
+        const { names } = findProblems();
+        store.reveal(names);
+        const first = names.find(name => store.formRuleError(name));
+        if (first && isFirstInvalid(event.currentTarget))
+            focusInput(first);
+    }
+    const context = useMemo(() => ({ idPrefix, size, design, readOnly, disabled, scopeNames: !inForm }), [idPrefix, size, design, readOnly, disabled, inForm]);
+    // 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 }), loading ? _jsx(SkeletonCell, { params: params, design: design }) : _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/SubmitForm.d.ts

@@ -0,0 +1,65 @@
+import { type ReactNode } from "react";
+import type { AnyFormStore, FormStore } from "../../Helpers/FormStore.ts";
+import type { FormValues, SubmitFormProps } from "../../Interfaces/FormInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export interface FormButtonsProps<TValues extends FormValues = FormValues> {
+    /** The form's store: the one given to the form as `form`. */
+    form: FormStore<TValues>;
+    /** Default "Save". */
+    submitLabel?: ReactNode;
+    /** Default: a floppy disk. `null` shows none. */
+    submitIcon?: ReactNode | null;
+    /** Shows a Cancel button. */
+    onCancel?: () => void;
+    /** Cancel asks before it drops changed values. Default true. */
+    confirmCancel?: boolean;
+    /** Default "Cancel". */
+    cancelLabel?: ReactNode;
+    /** Shows a Reset button. */
+    resettable?: boolean;
+    /** Default "Reset". */
+    resetLabel?: ReactNode;
+    /** `end` (default): the status line, then the buttons at the end. `start`: the buttons first. */
+    align?: "start" | "end";
+    /** Size of the buttons. Default `md`. */
+    size?: Size;
+    /** Nothing to save: only Cancel shows. */
+    readOnly?: boolean;
+    className?: string;
+}
+/**
+ * Asks "Discard your changes?" when the form has changes. Resolves `true` to go on (nothing changed, or the user chose
+ * Discard), `false` to keep editing. Cancel buttons and popups that close a form ask it.
+ */
+export declare function confirmDiscard(form: AnyFormStore): Promise<boolean>;
+/**
+ * A form's bar: its status line (loading, saving, what needs attention, unsaved changes, saved), Reset, Cancel, and Save.
+ * `SubmitForm` renders one; render your own with `buttons={false}` to put the bar elsewhere, such as a popup's footer.
+ * Its Save button submits the form from anywhere on the page.
+ *
+ * @example
+ * const form = useForm();
+ * <Popup footer={<FormButtons form={form} onCancel={close} />}>
+ *   <ApiForm form={form} buttons={false} inputs={inputs} api={api} />
+ * </Popup>
+ */
+export declare function FormButtons<TValues extends FormValues = FormValues>({ form, submitLabel, submitIcon, onCancel, confirmCancel, cancelLabel, resettable, resetLabel, align, size, readOnly, className, }: FormButtonsProps<TValues>): import("react").JSX.Element;
+/**
+ * A `Form` that submits: every value is checked on Save (the inputs' own rules, the form's `validate`, rows not on the
+ * page), each message shows, and the first problem takes focus; then `onSubmit` gets the values, and while it runs Save
+ * waits with a spinner and nothing submits twice. A save makes the values the form's own, so "Unsaved changes" clears;
+ * `{ ok: false, errors }` shows messages on their inputs. Cancel asks before it drops changes, the page asks before it
+ * closes with unsaved ones, and Ctrl+S or Ctrl+Enter saves from any input.
+ *
+ * @example
+ * <SubmitForm
+ *   inputs={EMPLOYEE_INPUTS}
+ *   defaultValue={employee}
+ *   onSubmit={async values => {
+ *     const answer = await api.save(values);
+ *     if (!answer.ok) return { ok: false, errors: answer.errors };
+ *   }}
+ *   onCancel={close}
+ * />
+ */
+export declare function SubmitForm<TValues extends FormValues = FormValues>(props: SubmitFormProps<TValues>): import("react").JSX.Element;

package/dist/Components/Forms/SubmitForm.js

@@ -0,0 +1,198 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconAlertCircle, iconCircleCheck, iconDeviceFloppy, iconLoader2, iconRefresh, InlineIcon } from "nexus-icons";
+import { useEffect, useId, useLayoutEffect, useRef } from "react";
+import { errorMessage, isAbortError } from "../../Helpers/ApiResponses.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { Button } from "../Documents/Button.js";
+import { messageBox } from "../Layouts/MessageBox.js";
+import { Form, formatFormTime, formInputLabel, namesToShow, useFormStatus, useFormStore } from "./Form.js";
+/** The problems after a submit, each a button that goes to its input: "2 fields need attention: Email, Phone." */
+function ProblemList({ form, names }) {
+    const { shown, more } = namesToShow(names);
+    return (_jsxs(_Fragment, { children: [names.length === 1 ? "1 field needs attention: " : `${names.length} fields need attention: `, shown.map((name, index) => (_jsxs("span", { children: [index > 0 && (index === shown.length - 1 && !more ? (shown.length > 2 ? ", and " : " and ") : ", "), _jsx("button", { type: "button", className: "nx-form-status__jump", onClick: () => form.focus(name), children: formInputLabel(form.inputs.find(params => params.name === name), name) })] }, name))), more > 0 && `, and ${more} more`, "."] }));
+}
+/** One line of what the form is doing: loading, saving, what needs attention, unsaved changes, or when it saved. */
+function FormStatusLine({ form, status }) {
+    const preferences = useDatePreferences();
+    let tone = "muted";
+    let content = null;
+    if (status.loading) {
+        content = (_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), _jsx("span", { children: "Loading\u2026" })] }));
+    }
+    else if (status.submitting) {
+        content = _jsx("span", { children: "Saving\u2026" });
+    }
+    else if (status.message || status.problems.length) {
+        tone = "error";
+        content = (_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsxs("span", { children: [status.message, status.message && status.problems.length > 0 && " ", status.problems.length > 0 && _jsx(ProblemList, { form: form, names: status.problems })] })] }));
+    }
+    else if (status.changed) {
+        content = _jsx("span", { children: status.draftSavedAt ? "Unsaved changes, kept on this device." : "Unsaved changes." });
+    }
+    else if (status.savedAt) {
+        tone = "success";
+        content = (_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconCircleCheck }), _jsxs("span", { children: ["Saved at ", formatFormTime(status.savedAt, preferences), "."] })] }));
+    }
+    return (_jsx("p", { className: cx("nx-form-status", `nx-form-status--${tone}`), "aria-live": "polite", children: content }));
+}
+/**
+ * Asks "Discard your changes?" when the form has changes. Resolves `true` to go on (nothing changed, or the user chose
+ * Discard), `false` to keep editing. Cancel buttons and popups that close a form ask it.
+ */
+export async function confirmDiscard(form) {
+    if (!form.isChanged())
+        return true;
+    return messageBox.confirm({
+        title: "Discard your changes?",
+        message: "What you changed in this form will be lost.",
+        tone: "warning",
+        confirmLabel: "Discard",
+        cancelLabel: "Keep editing",
+    });
+}
+/**
+ * A form's bar: its status line (loading, saving, what needs attention, unsaved changes, saved), Reset, Cancel, and Save.
+ * `SubmitForm` renders one; render your own with `buttons={false}` to put the bar elsewhere, such as a popup's footer.
+ * Its Save button submits the form from anywhere on the page.
+ *
+ * @example
+ * const form = useForm();
+ * <Popup footer={<FormButtons form={form} onCancel={close} />}>
+ *   <ApiForm form={form} buttons={false} inputs={inputs} api={api} />
+ * </Popup>
+ */
+export function FormButtons({ form, submitLabel = "Save", submitIcon, onCancel, confirmCancel = true, cancelLabel = "Cancel", resettable = false, resetLabel = "Reset", align = "end", size = "md", readOnly = false, className, }) {
+    const store = form;
+    const status = useFormStatus(store);
+    useEffect(() => store.addButtons(), [store]);
+    async function cancel() {
+        if (confirmCancel && !(await confirmDiscard(store)))
+            return;
+        store.dropDraft();
+        onCancel?.();
+    }
+    const buttonSize = size === "lg" ? "lg" : size === "sm" ? "sm" : "md";
+    const actions = [
+        resettable && !readOnly && (_jsx(Button, { size: buttonSize, variant: "ghost", icon: _jsx(InlineIcon, { icon: iconRefresh }), disabled: !status.changed || status.submitting || status.loading, onClick: () => store.reset(), children: resetLabel }, "reset")),
+        onCancel && (_jsx(Button, { size: buttonSize, onClick: () => void cancel(), children: cancelLabel }, "cancel")),
+        !readOnly && (_jsx(Button, { type: "submit", form: status.formId ?? undefined, size: buttonSize, variant: "primary", loading: status.submitting, disabled: status.loading, icon: submitIcon === undefined ? _jsx(InlineIcon, { icon: iconDeviceFloppy }) : (submitIcon ?? undefined), children: submitLabel }, "submit")),
+    ].filter(Boolean);
+    if (align === "start")
+        actions.reverse();
+    const line = _jsx(FormStatusLine, { form: store, status: status }, "status");
+    const bar = actions.length ? (_jsx("div", { className: "nx-form-buttons__actions", children: actions }, "actions")) : null;
+    return _jsx("div", { className: cx("nx-form-buttons", `nx-form-buttons--${align}`, className), children: align === "start" ? [bar, line] : [line, bar] });
+}
+/**
+ * A `Form` that submits: every value is checked on Save (the inputs' own rules, the form's `validate`, rows not on the
+ * page), each message shows, and the first problem takes focus; then `onSubmit` gets the values, and while it runs Save
+ * waits with a spinner and nothing submits twice. A save makes the values the form's own, so "Unsaved changes" clears;
+ * `{ ok: false, errors }` shows messages on their inputs. Cancel asks before it drops changes, the page asks before it
+ * closes with unsaved ones, and Ctrl+S or Ctrl+Enter saves from any input.
+ *
+ * @example
+ * <SubmitForm
+ *   inputs={EMPLOYEE_INPUTS}
+ *   defaultValue={employee}
+ *   onSubmit={async values => {
+ *     const answer = await api.save(values);
+ *     if (!answer.ok) return { ok: false, errors: answer.errors };
+ *   }}
+ *   onCancel={close}
+ * />
+ */
+export function SubmitForm(props) {
+    const { onSubmit: _onSubmit, onSaved: _onSaved, onCancel, confirmCancel, submitLabel, submitIcon, cancelLabel, resettable, resetLabel, resetOnSuccess: _resetOnSuccess, buttons = "end", confirmLeave, id, className, style, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...formProps } = props;
+    const store = useFormStore(props.form);
+    const formRef = useRef(null);
+    const generatedId = useId();
+    const formId = id ?? `${generatedId}form`;
+    const controllerRef = useRef(null);
+    const latest = useRef(props);
+    latest.current = props;
+    const locked = Boolean(props.readOnly || props.disabled);
+    useLayoutEffect(() => {
+        const submitter = () => formRef.current?.requestSubmit();
+        store.submitter = submitter;
+        store.setFormId(formId);
+        return () => {
+            if (store.submitter === submitter)
+                store.submitter = null;
+            store.setFormId(null);
+        };
+    }, [store, formId]);
+    // A submit still running when the form leaves stops.
+    useEffect(() => () => controllerRef.current?.abort(), []);
+    // Closing or reloading the page with unsaved changes asks first, unless a draft keeps them.
+    const guardLeave = confirmLeave ?? !props.draftKey;
+    useEffect(() => {
+        if (!guardLeave)
+            return;
+        const onBeforeUnload = (event) => {
+            if (!store.isChanged() || locked)
+                return;
+            event.preventDefault();
+            // Older browsers show the prompt only when this is set.
+            event.returnValue = "";
+        };
+        window.addEventListener("beforeunload", onBeforeUnload);
+        return () => window.removeEventListener("beforeunload", onBeforeUnload);
+    }, [store, guardLeave, locked]);
+    async function submit() {
+        const status = store.getStatus();
+        if (status.submitting || status.loading || locked)
+            return;
+        if (!store.validate())
+            return;
+        const controller = new AbortController();
+        controllerRef.current = controller;
+        const values = store.getValue();
+        const context = { changes: store.getChanges(), initial: store.getInitial(), form: store, signal: controller.signal };
+        store.beginSubmit();
+        let result;
+        try {
+            result = await latest.current.onSubmit(values, context);
+        }
+        catch (error) {
+            result = isAbortError(error) ? false : { ok: false, message: errorMessage(error) };
+        }
+        if (controllerRef.current === controller)
+            controllerRef.current = null;
+        if (controller.signal.aborted || result === false) {
+            store.endSubmit();
+            return;
+        }
+        if (result && typeof result === "object" && result.ok === false) {
+            store.endSubmit();
+            store.setErrors(result.errors ?? {}, result.message ?? null);
+            const first = store.getStatus().problems[0];
+            if (first)
+                store.focus(first);
+            return;
+        }
+        // Saved.
+        if (latest.current.resetOnSuccess) {
+            store.reset();
+            store.markSaved();
+            requestAnimationFrame(() => store.focus());
+        }
+        else {
+            store.commit(values, result && typeof result === "object" && result.ok ? result.values : undefined);
+        }
+        latest.current.onSaved?.(store.getValue(), store);
+    }
+    function onKeyDown(event) {
+        if (event.defaultPrevented || !(event.ctrlKey || event.metaKey) || event.altKey || event.shiftKey)
+            return;
+        if (event.key.toLowerCase() === "s" || event.key === "Enter") {
+            event.preventDefault();
+            formRef.current?.requestSubmit();
+        }
+    }
+    return (_jsxs("form", { ref: formRef, id: formId, className: cx("nx-submit-form", className), style: style, noValidate: true, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, onSubmit: event => {
+            event.preventDefault();
+            void submit();
+        }, onKeyDown: onKeyDown, children: [_jsx(Form, { ...formProps, form: store }), buttons !== false && (_jsx(FormButtons, { form: store, align: buttons, submitLabel: submitLabel, submitIcon: submitIcon, onCancel: onCancel, confirmCancel: confirmCancel, cancelLabel: cancelLabel, resettable: resettable, resetLabel: resetLabel, size: formProps.size, readOnly: locked }))] }));
+}

package/dist/Components/Inputs/Calendar.d.ts

@@ -0,0 +1,69 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { CalendarDay, CalendarType, DateInput, DateRange, DateScript } from "../../Interfaces/DateInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export type { DateRange } from "../../Interfaces/DateInterfaces.ts";
+export interface CalendarProps {
+    /** Picks one day (default) or a start and an end. */
+    mode?: "single" | "range";
+    /** The chosen day, as an ISO date. With `value`, the calendar is controlled. */
+    value?: DateInput;
+    defaultValue?: DateInput;
+    /** After a day is chosen or cleared, with the ISO date or `null`. */
+    onValueChange?: (value: string | null) => void;
+    /** Range mode: the chosen range. With `range`, the calendar is controlled. */
+    range?: DateRange;
+    defaultRange?: DateRange;
+    /** Range mode: after the start is chosen (end `null`), after the end is chosen, and after a clear. */
+    onRangeChange?: (range: [string | null, string | null]) => void;
+    /** After a pick is complete: a day, or the end of a range. A popover closes on this. */
+    onSelect?: (value: string) => void;
+    /** The calendar shown: `ad` or `bs`. Default: the user's setting. Values are ISO dates in either case. */
+    calendar?: CalendarType;
+    /** Digits and names of Nepali dates. Default: the user's setting. */
+    script?: DateScript;
+    /** Earliest day that can be picked. */
+    min?: DateInput;
+    /** Latest day that can be picked. */
+    max?: DateInput;
+    /** Days that cannot be picked, such as booked nights. */
+    isDateDisabled?: (iso: string) => boolean;
+    /** The month shown, as any day in it. With `month`, moving between months goes through `onMonthChange`. */
+    month?: DateInput;
+    defaultMonth?: DateInput;
+    /** After the shown month changes, with its first day. */
+    onMonthChange?: (firstDay: string) => void;
+    /** Months shown side by side, from the one in `month`: 1 (default) or 2, for ranges. With more than one, outside days are not drawn. */
+    months?: number;
+    /** First column of the week: 0 Sunday (default), 1 Monday, 6 Saturday. */
+    weekStart?: number;
+    /** Weekdays drawn as holidays (0 Sunday to 6 Saturday). Default: Saturday in the Nepali calendar, none otherwise. */
+    weekendDays?: readonly number[];
+    /** Shows the days of the months before and after that fill the first and last rows. Default true. */
+    showOutsideDays?: boolean;
+    /** Draws the inside of a day, e.g. the number with event markers under it. Default: the day number. */
+    renderDay?: (day: CalendarDay) => ReactNode;
+    /** Today and Clear buttons under the grid. Default true. */
+    footer?: boolean;
+    /** The day marked and picked as today, as an ISO date. Default: today where the browser is; a date and time picker showing another time zone passes that zone's day. */
+    today?: DateInput;
+    /** Default `md`. */
+    size?: Size;
+    readOnly?: boolean;
+    disabled?: boolean;
+    /** Focuses the calendar's current day when it mounts. */
+    autoFocus?: boolean;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+/**
+ * A month of days to pick from, in the English (AD) or Nepali (BS) calendar, with month and year menus, arrow-key
+ * navigation, a range mode with a live preview, two months side by side with `months`, and a `renderDay` slot for
+ * event markers. Values are ISO dates in the Gregorian calendar whatever calendar is shown. It is the panel of
+ * `DatePicker` and `DateRangePicker`, and works on its own in a page.
+ *
+ * @example <Calendar value={date} onValueChange={setDate} min={todayIsoDate()} />
+ */
+export declare function Calendar(props: CalendarProps): import("react").JSX.Element;