nexus-shared 3.2.0 → 4.0.0

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

@@ -0,0 +1,136 @@
+import { type IconNode } from "nexus-icons";
+import type { ReactNode } from "react";
+import type { CrudBackend } from "../../Helpers/CrudBackend.ts";
+import { type CrudJoinedRecord } from "../../Helpers/CrudHelpers.ts";
+import type { ApiResult } from "../../Interfaces/ApiInterfaces.ts";
+import type { CrudEndpoints, CrudFormOptions, CrudInputs, CrudMassActionName, CrudRowActionName } from "../../Interfaces/CrudInterfaces.ts";
+import { type FormValues, type InputParams } from "../../Interfaces/FormInterfaces.ts";
+/** The subject the endpoints were given: `apiController(module, "Guest", "guest")` → "guest". */
+export declare function crudSubject(api: CrudEndpoints): string | undefined;
+/** How the built-in actions on one record read wherever they are offered: a table's row, a tree's row, a panel's buttons. */
+export declare const CRUD_ACTION_WORDS: {
+    readonly create: {
+        readonly label: "Add New";
+        readonly icon: IconNode;
+    };
+    readonly edit: {
+        readonly label: "Edit";
+        readonly icon: IconNode;
+    };
+    readonly history: {
+        readonly label: "History";
+        readonly icon: IconNode;
+    };
+    readonly trash: {
+        readonly label: "Move to trash";
+        readonly icon: IconNode;
+        readonly tone: "danger";
+    };
+    readonly recover: {
+        readonly label: "Recover";
+        readonly description: "Back to the active list";
+        readonly icon: IconNode;
+    };
+    readonly delete: {
+        readonly label: "Delete permanently";
+        readonly icon: IconNode;
+        readonly tone: "danger";
+    };
+    readonly trashFromDelete: {
+        readonly label: "Move back to trash";
+        readonly icon: IconNode;
+    };
+};
+/** An action's words as a menu entry or a button takes them: the label, the icon drawn, and its tone and second line. */
+export declare function crudActionEntry(action: keyof typeof CRUD_ACTION_WORDS): {
+    label: string;
+    icon: ReactNode;
+    tone?: "danger";
+    description?: string;
+};
+/** Actions that move a record between the lists are asked about first; flags and pins are undone by a click. */
+export declare const CRUD_ASKED: ReadonlySet<CrudRowActionName | CrudMassActionName>;
+/**
+ * The body of an Add, Edit or details popup. Without an `aside` it is the form (or the details) and nothing else, so
+ * a popup that wants no panel carries no wrapper at all. With one, the two become columns that scroll on their own,
+ * and the form is first in the DOM — which is also the order they stack in when there is no room for two. A details
+ * popup is marked, because there the panel is what the popup is for and takes the larger share.
+ */
+export declare function CrudFormBody({ aside, details, below, children }: {
+    aside: ReactNode;
+    details?: boolean;
+    below?: boolean;
+    children: ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+/** The inputs of the Add or the Edit form, from one list, a list each, or a function of the action and the record. */
+export declare function crudInputsFor<TRow extends FormValues>(inputs: CrudInputs<TRow>, action: "create" | "edit", row: TRow | null): Promise<readonly InputParams[]>;
+/** What the Add or Edit popup is opened with. */
+export interface CrudFormRequest<TRow extends FormValues = FormValues> {
+    api: CrudEndpoints;
+    action: "create" | "edit";
+    /** The record edited; `null` for a new one. */
+    row: TRow | null;
+    /** Values over the new record's (`form.newValues`): the parent it is added under. */
+    values?: Partial<TRow>;
+    /**
+     * Inputs fixed for this opening, by name, each with why: read-only with the lock and the reason as its note, their
+     * values (from `values`, or the edited record) kept and sent (`lockInputs`), and never rewritten by the form's own
+     * `onFieldChange`. An Add with fixed inputs is a popup and a draft of its own per set of fixed values (`crudFormPlace`),
+     * so an Add started inside one parent never comes back inside another; an Edit stays one popup per record, its draft
+     * per set of fixed values.
+     */
+    locked?: Readonly<Record<string, string>>;
+    /**
+     * Records the caller holds for the values it fixes - the row picked in another list that a new record is added for: a
+     * fixed dropdown names its value from them, with no lookup (`lockInputs`).
+     */
+    known?: readonly FormValues[];
+    inputs: CrudInputs<TRow>;
+    form?: CrudFormOptions<TRow>;
+    /** What one record is: "region". */
+    subject: string;
+    /** Tells the popups of one controller apart from another's. */
+    name: string;
+    /** The field that tells records apart. Default `id`. */
+    rowKey?: string;
+    /** The record's key as text, for the Edit popup's key and its draft. */
+    key?: string;
+    /** Beside the title, and under it on the dock while minimized: the record an Edit is of, where an Add adds ("Inside Bagmati"). */
+    label?: string;
+    /**
+     * After the save: the answer, the values sent, and what the form's dropdowns know of the records their keys name
+     * (`joined`), so the record's joined names are written with no call. The popup closes itself.
+     */
+    onSaved: (result: unknown, saved: TRow, joined: CrudJoinedLookup) => void;
+}
+/**
+ * The record behind a key of a form's dropdown (`name`), as a save names its joins (`crudJoinedNames`): the item the
+ * user picked for that key, else one of the dropdown's `selectedOptions` (given for a saved or a fixed value), else one
+ * the page holds (the dropdown's `peekOption`), else one of `held` (records the caller holds: a tree's parent, a narrowed
+ * list's picked record), else one the page held once and has marked old (`peekOption(key, true)`: an old name beats
+ * none). Its name is the dropdown's `labelKey` field, its status the record's `recordStatus`. `null` when none is known:
+ * nothing is asked for it.
+ */
+export type CrudJoinedLookup = (name: string, key: string, held?: readonly FormValues[]) => CrudJoinedRecord | null;
+/**
+ * Opens the Add or the Edit popup of a controller's record: its inputs in an `ApiForm` that calls `create` or `update`,
+ * a discard question before changes are lost, and `onSaved` with the answer.
+ *
+ * - An Add form with changes comes back as it was - the one of the same place, when inputs are fixed (`locked`). Asking
+ *   for one replaces every untouched Add of the controller, so the dock keeps only forms with work in them.
+ * - A record has one Edit popup wherever it was opened from. Asked for again with the same inputs fixed, it comes back;
+ *   with others (a tree's fixed form, a data table's free one), an untouched one is replaced, and one with changes comes
+ *   back as it is, saying why: an older form's save would undo what the newer one saved.
+ */
+export declare function openCrudForm<TRow extends FormValues>(request: CrudFormRequest<TRow>): Promise<void>;
+/**
+ * Calls the endpoint of a built-in action on one record - asking first for those that move it between the lists - with
+ * the record's key in the path and its name in the messages. A flag carries the way it goes (`markOn`). `null` when the
+ * controller has no such endpoint or the question was answered No.
+ */
+export declare function sendCrudRowAction<TRow extends FormValues>(api: CrudEndpoints, action: CrudRowActionName, row: TRow, options: {
+    rowKey?: string;
+    label?: string;
+    backend: CrudBackend;
+    markOn?: boolean;
+}): Promise<ApiResult | null>;

package/dist/Components/Forms/CrudActions.js

@@ -0,0 +1,184 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconArrowBackUp, iconHistory, iconPencil, iconPlus, iconTrash, iconTrashX, InlineIcon } from "nexus-icons";
+import { unwrapApiResult } from "../../Helpers/ApiResponses.js";
+import { crudFormPlace, crudMessageAction, crudRowEndpoint } from "../../Helpers/CrudHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { FormStore } from "../../Helpers/FormStore.js";
+import { lockedFieldChange, lockInputs } from "../../Helpers/InputParamsHelpers.js";
+import { readPath } from "../../Helpers/TableHelpers.js";
+import { EInputTypes } from "../../Interfaces/FormInterfaces.js";
+import { api as browserApi } from "../../Services/BrowserApi.js";
+import { openPopup } from "../Layouts/PopupHost.js";
+import { popupRuleFor } from "../Layouts/PopupRules.js";
+import { toast } from "../Layouts/Toaster.js";
+import { ApiForm } from "./ApiForm.js";
+import { confirmDiscard, FormButtons } from "./SubmitForm.js";
+/*
+ * What every view of a controller's records does the same way - the data table (`Crud`) and the tree (`CrudTree`): the
+ * Add and Edit popups, the call behind an action on one record, and the words and icons each action shows. One copy, so
+ * a record added from a tree is added through exactly the form the table opens.
+ */
+/** The subject the endpoints were given: `apiController(module, "Guest", "guest")` → "guest". */
+export function crudSubject(api) {
+    const endpoints = [api.create, api.update, api.details, ...Object.values(api.lists ?? {}), ...Object.values(api.pages ?? {})];
+    return endpoints.find(endpoint => endpoint?.subject)?.subject;
+}
+/** How the built-in actions on one record read wherever they are offered: a table's row, a tree's row, a panel's buttons. */
+export const CRUD_ACTION_WORDS = {
+    // One fixed label on every CRUD, whatever its subject (the owner, 2026-10-10); the form it opens says "Add <subject>".
+    create: { label: "Add New", icon: iconPlus },
+    edit: { label: "Edit", icon: iconPencil },
+    history: { label: "History", icon: iconHistory },
+    trash: { label: "Move to trash", icon: iconTrash, tone: "danger" },
+    recover: { label: "Recover", description: "Back to the active list", icon: iconArrowBackUp },
+    delete: { label: "Delete permanently", icon: iconTrashX, tone: "danger" },
+    trashFromDelete: { label: "Move back to trash", icon: iconArrowBackUp },
+};
+/** An action's words as a menu entry or a button takes them: the label, the icon drawn, and its tone and second line. */
+export function crudActionEntry(action) {
+    const words = CRUD_ACTION_WORDS[action];
+    return { label: words.label, icon: _jsx(InlineIcon, { icon: words.icon }), tone: words.tone, description: words.description };
+}
+/** Actions that move a record between the lists are asked about first; flags and pins are undone by a click. */
+export const CRUD_ASKED = new Set(["trash", "recover", "delete", "trashFromDelete"]);
+/**
+ * The body of an Add, Edit or details popup. Without an `aside` it is the form (or the details) and nothing else, so
+ * a popup that wants no panel carries no wrapper at all. With one, the two become columns that scroll on their own,
+ * and the form is first in the DOM — which is also the order they stack in when there is no room for two. A details
+ * popup is marked, because there the panel is what the popup is for and takes the larger share.
+ */
+export function CrudFormBody({ aside, details, below, children }) {
+    if (!aside)
+        return children;
+    return (_jsxs("div", { className: cx("nx-crud-aside", details && "nx-crud-aside--details", below && "nx-crud-aside--below"), children: [_jsx("div", { className: "nx-crud-aside__main", children: children }), _jsx("aside", { className: "nx-crud-aside__side", children: aside })] }));
+}
+/** The inputs of the Add or the Edit form, from one list, a list each, or a function of the action and the record. */
+export async function crudInputsFor(inputs, action, row) {
+    if (typeof inputs === "function")
+        return inputs(action, row);
+    if (Array.isArray(inputs))
+        return inputs;
+    const split = inputs;
+    return (action === "create" ? (split.create ?? split.edit) : (split.edit ?? split.create)) ?? [];
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const capitalize = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
+/** `CrudJoinedLookup` over a form's inputs and its store. */
+function joinedLookup(inputs, form) {
+    return (name, key, held = []) => {
+        const params = inputs.find(input => input.name === name);
+        if (!params || params.type !== EInputTypes.Dropdown || params.multiple)
+            return null;
+        const valueKey = params.valueKey ?? "value";
+        const labelKey = params.labelKey ?? "label";
+        const matches = (item) => isRecord(item) && String(item[valueKey]) === key;
+        // The form's own first: what the user picked, then the records the input was given for its saved value.
+        const record = [form.pickedItem(name), ...(params.selectedOptions ?? []), params.peekOption?.(key), ...held].find(matches) ?? [params.peekOption?.(key, true)].find(matches);
+        return record ? { name: record[labelKey], status: record.recordStatus } : null;
+    };
+}
+/** The Add and Edit popups open now, by popup key: the controller's name, the action, the form, and the place it was opened for. */
+const openForms = new Map();
+/** Brings a popup back from the dock; one on screen is left as it is. */
+function bringBack(handle) {
+    if (handle.windowState === "minimized")
+        handle.restore();
+}
+/**
+ * Opens the Add or the Edit popup of a controller's record: its inputs in an `ApiForm` that calls `create` or `update`,
+ * a discard question before changes are lost, and `onSaved` with the answer.
+ *
+ * - An Add form with changes comes back as it was - the one of the same place, when inputs are fixed (`locked`). Asking
+ *   for one replaces every untouched Add of the controller, so the dock keeps only forms with work in them.
+ * - A record has one Edit popup wherever it was opened from. Asked for again with the same inputs fixed, it comes back;
+ *   with others (a tree's fixed form, a data table's free one), an untouched one is replaced, and one with changes comes
+ *   back as it is, saying why: an older form's save would undo what the newer one saved.
+ */
+export async function openCrudForm(request) {
+    const { api, action, row, values, locked, subject, name, rowKey = "id", key = "", label, onSaved } = request;
+    const endpoint = action === "create" ? api.create : api.update;
+    if (!endpoint)
+        return;
+    const options = request.form ?? {};
+    const newValues = typeof options.newValues === "function" ? options.newValues() : options.newValues;
+    // What the form opens with: a new record's values, or the record edited.
+    const opening = (action === "create" ? { ...newValues, ...values } : (row ?? {}));
+    // Fixed inputs make it the form of one place: an Add's popup and every draft carry the values fixed.
+    const place = locked ? crudFormPlace(Object.fromEntries(Object.keys(locked).map(field => [field, opening[field]]))) : "";
+    const popupKey = action === "create" ? `${name}-new${place}` : `${name}-edit-${key}`;
+    const open = openForms.get(popupKey);
+    if (open && (open.form.isChanged() || (action === "edit" && open.place === place))) {
+        bringBack(open.handle);
+        if (open.place !== place)
+            toast.info(`${label ?? capitalize(subject)} is already being edited`, "Its form is open with changes: save or discard them first.");
+        return;
+    }
+    if (action === "create") {
+        for (const [other, entry] of openForms)
+            if (other !== popupKey && entry.name === name && entry.action === "create" && !entry.form.isChanged())
+                entry.handle.close("replaced");
+    }
+    const given = await crudInputsFor(request.inputs, action, row);
+    const inputs = locked ? lockInputs(given, locked, opening, request.known) : given;
+    // The inputs lockInputs fixed - a copy each - are out of reach of the form's own rules too.
+    const onFieldChange = lockedFieldChange(options.onFieldChange, inputs.filter((params, index) => params !== given[index]).map(params => params.name));
+    const form = new FormStore();
+    const loader = options.load;
+    const id = row ? readPath(row, rowKey) : undefined;
+    const loadValue = action === "edit" && row && loader && loader !== "row"
+        ? loader === "details"
+            ? api.details
+                ? (signal) => browserApi.get(api.details, { params: { id, [rowKey]: id }, signal, toast: false }).then(answer => ({ ...row, ...unwrapApiResult(answer) }))
+                : undefined
+            : (signal) => loader(row, signal).then(full => ({ ...row, ...full }))
+        : undefined;
+    const handle = openPopup({
+        key: popupKey,
+        // One still open under this key was untouched, or opened for another place: a fresh form takes its place.
+        reopen: "replace",
+        title: action === "create" ? `Add ${subject}` : `Edit ${subject}`,
+        description: label,
+        icon: _jsx(InlineIcon, { icon: action === "create" ? iconPlus : iconPencil }),
+        size: options.size ?? (inputs.length > 8 ? "lg" : "md"),
+        closeOnBackdrop: false,
+        // A CRUD page's Add and Edit are the popups that can be put aside on the dock; a page's rule for the key may say no.
+        minimizable: popupRuleFor(popupKey)?.minimizable ?? true,
+        beforeClose: async () => {
+            const discard = await confirmDiscard(form);
+            if (discard)
+                form.dropDraft();
+            return discard;
+        },
+        content: popup => (_jsx(CrudFormBody, { aside: typeof options.aside === "function" ? options.aside({ form, action, row }) : options.aside, children: _jsx(ApiForm, { form: form, inputs: inputs, buttons: false, defaultValue: (action === "create" ? opening : (row ?? undefined)), loadValue: loadValue, api: endpoint, transform: options.transform ? formValues => options.transform(formValues, { action, row }) : undefined, confirm: options.confirm, validate: options.validate, onFieldChange: onFieldChange, design: options.design, draftKey: options.draftKey ? `${options.draftKey}:${name}:${action === "create" ? "new" : key}${place}` : undefined, "aria-label": action === "create" ? `Add ${subject}` : `Edit ${label}`, onSuccess: (result, saved) => {
+                    onSaved(result, saved, joinedLookup(inputs, form));
+                    popup.close();
+                } }) })),
+        footer: popup => _jsx(FormButtons, { form: form, submitLabel: action === "create" ? `Add ${subject}` : "Save", onCancel: () => popup.close() }),
+    });
+    const entry = { name, action, handle, form: form, place };
+    openForms.set(popupKey, entry);
+    void handle.closed.then(() => {
+        if (openForms.get(popupKey) === entry)
+            openForms.delete(popupKey);
+    });
+}
+/**
+ * Calls the endpoint of a built-in action on one record - asking first for those that move it between the lists - with
+ * the record's key in the path and its name in the messages. A flag carries the way it goes (`markOn`). `null` when the
+ * controller has no such endpoint or the question was answered No.
+ */
+export async function sendCrudRowAction(api, action, row, options) {
+    const endpoint = crudRowEndpoint(api, action);
+    if (!endpoint)
+        return null;
+    const rowKey = options.rowKey ?? "id";
+    const key = readPath(row, rowKey);
+    const call = {
+        params: { id: key, [rowKey]: key },
+        subject: options.label,
+        action: crudMessageAction(action, options.markOn),
+        ...(options.markOn !== undefined ? options.backend.flagRequest(options.markOn) : {}),
+    };
+    return CRUD_ASKED.has(action) ? browserApi.confirm(endpoint, call) : browserApi.send(endpoint, call);
+}

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

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import type { CrudNarrow, CrudNarrowPicker } from "../../Interfaces/CrudInterfaces.ts";
+/** What a narrowed list says while nothing is picked, and on its Add: the box's reason, read with it. */
+export interface CrudNarrowPickerWords {
+    empty: string;
+    add: string;
+}
+/** The narrowing a `narrowPicker` gives its CRUD, the parts it draws, and what the CRUD's Add and list do with it. */
+export interface CrudNarrowPickerParts {
+    /** The CRUD's `narrow`, the picked record in it; nothing without a `narrowPicker`. */
+    narrow: CrudNarrow | undefined;
+    /** The box, for the toolbar. */
+    box: ReactNode;
+    /** The list's button to the box, for its empty message while the box asks for a pick; null otherwise. */
+    pickButton: ReactNode;
+    /** The box is settling as the page opens (a kept pick looked up, its records counted for a lone one): the list waits. */
+    waiting: boolean;
+    /** Nothing is picked and the box has settled: it asks for a pick. */
+    wanted: boolean;
+    /**
+     * Add pressed with nothing picked: the cursor goes to the box, the box is nudged (still, with reduced motion) and a
+     * screen reader hears Add's reason with it. False while the box cannot take it (settling, or not drawn).
+     */
+    askForAdd: () => boolean;
+}
+/**
+ * The narrowing a `narrowPicker` gives its CRUD, and the box it draws in the toolbar. Without one: nothing, and the
+ * CRUD's own `narrow` stands. `words` are the list's: the box's reason while it asks for a pick, and Add's after a press
+ * (default: the box's own words for "records").
+ */
+export declare function useCrudNarrowPicker(options: CrudNarrowPicker | undefined, words?: CrudNarrowPickerWords): CrudNarrowPickerParts;

package/dist/Components/Forms/CrudNarrowPicker.js

@@ -0,0 +1,180 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconArrowUp, InlineIcon } from "nexus-icons";
+import { useEffect, useId, useRef, useState } from "react";
+import { flushSync } from "react-dom";
+import { narrowBoxTakesCursor, narrowPickerPlaceholder, narrowPickerStorageKey, narrowPickWords, readNarrowPick, startNarrowPick, writeNarrowPick } from "../../Helpers/CrudNarrowPick.js";
+import { Button } from "../Documents/Button.js";
+import { Dropdown } from "../Inputs/Dropdown.js";
+/** This browser's local storage, or nothing where it cannot be reached (a server draw, storage switched off). */
+function browserStorage() {
+    try {
+        return typeof window === "undefined" ? null : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a popup (a dialog) or a panel (a menu, a list) is open over the page: a toast or a field's note is not one. */
+function somethingOpen() {
+    if (document.querySelector("dialog[open]"))
+        return true;
+    try {
+        return Boolean(document.querySelector(":popover-open:not(.nx-toast, .nx-field-notice)"));
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether the whole of the box is on screen, so a cursor sent there scrolls nothing. */
+function wholeOnScreen(box) {
+    const rect = box.getBoundingClientRect();
+    return rect.width > 0 && rect.top >= 0 && rect.left >= 0 && rect.bottom <= window.innerHeight && rect.right <= window.innerWidth;
+}
+/** A touch screen with no mouse, where a cursor in a text box raises the on-screen keyboard. */
+function touchOnly() {
+    return typeof window.matchMedia === "function" && window.matchMedia("(hover: none) and (pointer: coarse)").matches;
+}
+/** Nudges the box (`.nx-field__box[data-nudge]`), again on every call. The stylesheet stills it with reduced motion. */
+function nudge(input) {
+    const box = input.closest(".nx-field__box");
+    if (!(box instanceof HTMLElement))
+        return;
+    box.removeAttribute("data-nudge");
+    void box.offsetWidth;
+    box.setAttribute("data-nudge", "");
+    box.addEventListener("animationend", () => box.removeAttribute("data-nudge"), { once: true });
+}
+/**
+ * The narrowing a `narrowPicker` gives its CRUD, and the box it draws in the toolbar. Without one: nothing, and the
+ * CRUD's own `narrow` stands. `words` are the list's: the box's reason while it asks for a pick, and Add's after a press
+ * (default: the box's own words for "records").
+ */
+export function useCrudNarrowPicker(options, words = narrowPickWords(options?.label, "record", "records")) {
+    const [picked, setPicked] = useState(null);
+    // Which opening has settled (`storage|valueKey`): until the one asked for now has, the list waits.
+    const [settledFor, setSettledFor] = useState(null);
+    // Add was pressed with nothing picked: the box's reason is Add's until a pick.
+    const [asked, setAsked] = useState(false);
+    const latest = useRef(options);
+    latest.current = options;
+    // A pick made before the box settled is the person's: settling never replaces it.
+    const touched = useRef(false);
+    // Pressed a key or a pointer since the page opened: the box then does not take the cursor.
+    const used = useRef(false);
+    // The moment the page opened has been judged: the box takes the cursor then or never.
+    const judged = useRef(false);
+    const inputRef = useRef(null);
+    const reasonId = `${useId()}-reason`;
+    const active = Boolean(options);
+    const storage = options?.remember ? narrowPickerStorageKey(options.remember) : null;
+    const valueKey = options ? (options.valueKey ?? options.picker.valueKey ?? "id") : "id";
+    const labelKey = options ? (options.labelKey ?? options.picker.labelKey) : undefined;
+    const opening = `${storage ?? ""}|${valueKey}`;
+    const waiting = active && settledFor !== opening && picked === null;
+    const wanted = active && !waiting && picked === null;
+    // The box opens on the remembered pick while it still offers it, as it offers it now (asked for by its key alone), else
+    // on the one record it offers, else it asks for a pick.
+    useEffect(() => {
+        if (!active)
+            return;
+        const controller = new AbortController();
+        const kept = browserStorage();
+        const saved = storage && kept ? readNarrowPick(kept, storage) : null;
+        void startNarrowPick(latest.current.picker, saved, valueKey, controller.signal).then(start => {
+            if (controller.signal.aborted)
+                return;
+            if (!touched.current) {
+                // Kept again as the key alone (a pick kept by an older build held its name too), forgotten when the box no longer
+                // offers it, or the lone record kept as a person's pick is.
+                if (storage && kept && start.keep !== undefined)
+                    writeNarrowPick(kept, storage, start.keep);
+                if (start.picked) {
+                    setPicked(start.picked);
+                    latest.current?.onPick?.(start.picked);
+                }
+            }
+            setSettledFor(opening);
+        });
+        return () => controller.abort();
+    }, [active, storage, valueKey, opening]);
+    // Until the page's opening is judged, a key or a pointer pressed anywhere counts as the person at work; no longer after.
+    const stopWatching = useRef(null);
+    useEffect(() => {
+        if (!active || judged.current)
+            return;
+        const mark = () => {
+            used.current = true;
+        };
+        document.addEventListener("pointerdown", mark, true);
+        document.addEventListener("keydown", mark, true);
+        const stop = () => {
+            document.removeEventListener("pointerdown", mark, true);
+            document.removeEventListener("keydown", mark, true);
+            stopWatching.current = null;
+        };
+        stopWatching.current = stop;
+        return stop;
+    }, [active]);
+    // Settled with nothing picked as the page opens: the box takes the cursor, unless the person is at work elsewhere, a
+    // popup is open, the box is off screen, or a cursor would raise a phone's keyboard over the list.
+    useEffect(() => {
+        if (!active || waiting || judged.current)
+            return;
+        judged.current = true;
+        stopWatching.current?.();
+        const input = inputRef.current;
+        if (picked || !input || input.disabled || input.readOnly)
+            return;
+        const focused = document.activeElement;
+        const takes = narrowBoxTakesCursor({
+            used: used.current,
+            focusElsewhere: focused !== null && focused !== document.body && focused !== document.documentElement,
+            popupOpen: somethingOpen(),
+            touchOnly: touchOnly(),
+            inView: wholeOnScreen(input.closest(".nx-field__box") ?? input),
+        });
+        if (takes)
+            input.focus({ preventScroll: true });
+    }, [active, waiting, picked]);
+    if (!options)
+        return { narrow: undefined, box: null, pickButton: null, waiting: false, wanted: false, askForAdd: () => false };
+    const { picker, label, placeholder, remember: _remember, onPick: _onPick, ...narrowing } = options;
+    const boxPlaceholder = placeholder ?? narrowPickerPlaceholder(label);
+    function pick(value, item) {
+        touched.current = true;
+        // The box names the record it picked; one it only holds by key is looked up in what it has loaded.
+        const row = value === null ? null : (item ?? picker.peekOption?.(String(value)) ?? { [valueKey]: value });
+        setPicked(row);
+        setAsked(false);
+        const kept = browserStorage();
+        if (storage && kept)
+            writeNarrowPick(kept, storage, row ? String(row[valueKey]) : null);
+        latest.current?.onPick?.(row);
+    }
+    function askForAdd() {
+        const input = inputRef.current;
+        if (!wanted || !input || input.disabled || input.readOnly)
+            return false;
+        // The reason is Add's before the cursor lands, so a screen reader reads it with the box.
+        flushSync(() => setAsked(true));
+        input.focus();
+        nudge(input);
+        return true;
+    }
+    // The list's button: the cursor to the box and its list open, as a click on the box opens it.
+    function openBox() {
+        const input = inputRef.current;
+        if (!input)
+            return;
+        input.focus();
+        input.click();
+    }
+    const value = picked ? picked[valueKey] : null;
+    const box = (_jsxs(_Fragment, { children: [_jsx(Dropdown, { ...picker, ref: inputRef, "aria-label": label, "aria-describedby": wanted ? reasonId : undefined, size: "sm", placeholder: boxPlaceholder, multiple: false, value: value, selectedOptions: picked ? [picked] : [], 
+                // The list needs a pick: required always, drawn as a field that must be set while it has none. Its reason is the
+                // list's, read with the box, never a message line under it in the toolbar.
+                required: true, validateOn: "submit", invalid: wanted, loading: waiting, onValueChange: (next, item) => pick(next, item) }), wanted && (_jsx("span", { id: reasonId, hidden: true, children: asked ? words.add : words.empty }))] }));
+    const pickButton = wanted ? (_jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconArrowUp }), onClick: openBox, children: boxPlaceholder })) : null;
+    return { narrow: { ...narrowing, valueKey, ...(labelKey && { labelKey }), picked }, box, pickButton, waiting, wanted, askForAdd };
+}

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

@@ -14,6 +14,34 @@ export interface CrudDetailsProps<TRow extends FormValues = FormValues> {
     load?: (signal: AbortSignal) => Promise<Partial<TRow> | null | undefined>;
     /** Draws the details instead of the list of fields. */
     render?: (row: TRow) => ReactNode;
+    /** The currency of a `money` field without its own, as the table writes it (`DataTableProps.currency`). */
+    currency?: string | null;
 }
-/** A record's fields as label and value, two to a line where there is room, in the formats of the table's columns. */
-export declare function CrudDetails<TRow extends FormValues = FormValues>({ row, columns, load, render }: CrudDetailsProps<TRow>): import("react").JSX.Element;
+/**
+ * A record's fields as label and value, two to a line where there is room, in the formats of the table's columns. Where
+ * columns name a `group` (a table's band), each run of neighbouring columns with one group is a section under that
+ * heading; columns with no group draw as before, without one.
+ */
+export declare function CrudDetails<TRow extends FormValues = FormValues>({ row, columns, load, render, currency }: CrudDetailsProps<TRow>): import("react").JSX.Element;
+export interface CrudTabFooterProps {
+    /** Its words first (a `<p>`: what saving does), then the buttons (`FormButtons`, or `Button`s). */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * The footer of a tab in a record's workspace (`CrudDetailsOptions.tabs`): one bar, its words at the start and its
+ * buttons at the end, put last in the tab. While the tab scrolls it stays at the bottom of the workspace's panel, so a
+ * long form's Save never falls below the window; at the end of the tab it sits in its place. It is drawn on the panel's
+ * own surface under a hairline, across the panel's whole width, with the popup footer's room, and on a phone its words
+ * and its buttons wrap as whole groups. Outside a workspace it is a plain bar where it stands.
+ *
+ * A field the keyboard moves to is scrolled into view above it, never under it.
+ *
+ * @example
+ * <ApiForm form={form} buttons={false} api={STAYS.create} inputs={STAY_INPUTS} />
+ * <CrudTabFooter>
+ *   <p role="status" aria-live="polite">3 nights in a double room · To pay Rs. 10,500.00</p>
+ *   <FormButtons form={form} submitLabel="Save" />
+ * </CrudTabFooter>
+ */
+export declare function CrudTabFooter({ children, className }: CrudTabFooterProps): import("react").JSX.Element;