nexus-shared 2.0.0 → 3.1.0

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

@@ -6,7 +6,11 @@ export interface CrudDetailsProps<TRow extends FormValues = FormValues> {
     row: TRow;
     /** The fields, as the table's columns describe them; hidden columns included. */
     columns: readonly TableColumn<TRow>[];
-    /** Loads the full record (fields the list leaves out); its values replace the row's when they come. */
+    /**
+     * Loads the full record (fields the list leaves out); its values replace the row's when they come. Meanwhile a field
+     * the row lacks keeps its line blank, and reads "Not loaded" if the load fails; the details say nothing else about
+     * the load (`aria-busy` while it runs), so the popup around them never changes size for it.
+     */
     load?: (signal: AbortSignal) => Promise<Partial<TRow> | null | undefined>;
     /** Draws the details instead of the list of fields. */
     render?: (row: TRow) => ReactNode;

package/dist/Components/Forms/CrudParts.js

@@ -1,18 +1,30 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { iconInfoCircle, iconLoader2, InlineIcon } from "nexus-icons";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { motionAllowed } from "../../Helpers/AnimationHelpers.js";
 import { isAbortError } from "../../Helpers/ApiResponses.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { readPath } from "../../Helpers/TableHelpers.js";
+import { useNumberLocale } from "../../Helpers/UserPreferences.js";
 import { TableCellValue } from "../Viewers/DataTableParts.js";
+/**
+ * An element's height as its `height` would set it: unrounded, unlike `offsetHeight`, so an unroll between two of
+ * them starts and ends exactly where the details are and the popup never steps by a fraction of a pixel. NaN while
+ * not drawn.
+ */
+const usedHeight = (element) => parseFloat(getComputedStyle(element).height);
 /** 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 function CrudDetails({ row, columns, load, render }) {
     const [record, setRecord] = useState(row);
     const [state, setState] = useState(load ? "loading" : "done");
+    const rootRef = useRef(null);
+    // The details' height just before the full record went in, kept only when the change may be animated.
+    const grownFrom = useRef(null);
     const preferences = useDatePreferences();
     const timeZone = useBrowserTimeZone();
-    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined }), [preferences, timeZone]);
+    const locale = useNumberLocale();
+    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined, locale }), [preferences, timeZone, locale]);
     useEffect(() => {
         if (!load)
             return;
@@ -20,8 +32,11 @@ export function CrudDetails({ row, columns, load, render }) {
         load(controller.signal).then(full => {
             if (controller.signal.aborted)
                 return;
-            if (full)
+            if (full) {
+                if (motionAllowed() && rootRef.current)
+                    grownFrom.current = usedHeight(rootRef.current);
                 setRecord(current => ({ ...current, ...full }));
+            }
             setState("done");
         }, error => {
             if (controller.signal.aborted || isAbortError(error))
@@ -32,5 +47,22 @@ export function CrudDetails({ row, columns, load, render }) {
         // The record loads once per popup.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
-    return (_jsxs("div", { className: "nx-crud-details", "aria-busy": state === "loading" || undefined, children: [state === "loading" && (_jsxs("p", { className: "nx-crud-details__note", role: "status", children: [_jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), "Loading the full record\u2026"] })), state === "failed" && (_jsxs("p", { className: "nx-crud-details__note", role: "status", children: [_jsx(InlineIcon, { icon: iconInfoCircle }), "The full record could not be loaded; these are the values from the list."] })), render ? (render(record)) : (_jsx("dl", { className: "nx-crud-details__list", children: columns.map(column => (_jsxs("div", { className: cx("nx-crud-details__item", column.wrap && "nx-crud-details__item--wide"), children: [_jsx("dt", { className: "nx-crud-details__label", children: column.label }), _jsx("dd", { className: "nx-crud-details__value", children: _jsx(TableCellValue, { column: column, row: record, options: options }) })] }, column.key))) }))] }));
+    // A record that makes the details taller (a long note the list did not have) unrolls to its height when motion is
+    // allowed, as maximize does; without motion it changes at once. Nothing waits on it.
+    useLayoutEffect(() => {
+        const from = grownFrom.current;
+        grownFrom.current = null;
+        const root = rootRef.current;
+        if (!from || !root || typeof root.animate !== "function")
+            return;
+        const to = usedHeight(root);
+        if (!to || Math.abs(to - from) < 1)
+            return;
+        const animation = root.animate([{ height: `${from}px`, overflow: "clip" }, { height: `${to}px`, overflow: "clip" }], { duration: 200, easing: "cubic-bezier(0.2, 0, 0, 1)" });
+        return () => animation.cancel();
+    }, [record]);
+    // A field the list's row does not carry can only be filled by the full record. Columns that draw or work out their
+    // own value (`render`, `value`) draw as always, because only they know what they read.
+    const awaited = (column) => state !== "done" && !column.render && !column.value && readPath(record, column.key) === undefined;
+    return (_jsx("div", { ref: rootRef, className: "nx-crud-details", "aria-busy": state === "loading" || undefined, children: render ? (render(record)) : (_jsx("dl", { className: "nx-crud-details__list", children: columns.map(column => (_jsxs("div", { className: cx("nx-crud-details__item", column.wrap && "nx-crud-details__item--wide"), children: [_jsx("dt", { className: "nx-crud-details__label", children: column.label }), _jsx("dd", { className: "nx-crud-details__value", children: !awaited(column) ? _jsx(TableCellValue, { column: column, row: record, options: options }) : state === "failed" ? _jsx("span", { className: "nx-crud-details__missing", children: "Not loaded" }) : null })] }, column.key))) })) }));
 }

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

@@ -0,0 +1,58 @@
+import { type ReactNode, type Ref } from "react";
+import type { ExcelEndpoints, ExcelImportAnswer } from "../../Interfaces/ExcelInterfaces.ts";
+import { type ExcelCallOptions } from "../../Services/ExcelApi.ts";
+import { type PopupHandle } from "../Layouts/PopupHost.tsx";
+/** What an import panel needs. */
+export interface ExcelImportProps {
+    /** The model's spreadsheet endpoints: `excelEndpoints(CITIES)`, or the app's own four. */
+    endpoints: ExcelEndpoints;
+    /** What one row is: "city". Default: what the settings say. */
+    subject?: string;
+    /** Path values the calls need, such as a parent id. */
+    params?: ExcelCallOptions["params"];
+    /** After an import wrote something, to reload the list behind the panel. */
+    onImported?: (answer: ExcelImportAnswer) => void;
+    /** The Close button, and what it does. Without it, none shows (a popup has its own). */
+    onClose?: () => void;
+    /** No template download is offered, for a model whose file comes from somewhere else. */
+    templateDownload?: false;
+    /** The tallest each editor grows before its rows scroll. Default 320. */
+    maxHeight?: number;
+    /**
+     * `"file"` (the default): a filled template is sent to be checked, and its rows come back to be gone over.
+     * `"bulk"`: no file - the rows are typed here, from one empty row, and imported with the same checks. A sheet with a
+     * required list cannot be typed in (its key is picked in the spreadsheet), and the panel says so.
+     */
+    mode?: "file" | "bulk";
+    /** What closing the panel would lose, so a window can ask first: `openExcelImport` passes one. */
+    ref?: Ref<ExcelImportHandle>;
+    className?: string;
+}
+/** What `ref` gives on an import panel. */
+export interface ExcelImportHandle {
+    /** The rows only this screen has - typed here, or a sheet's row edited here - which closing the panel loses. */
+    unsavedRows: () => number;
+}
+/**
+ * The three steps of an import in one panel: the template, the file, and the review - or, for a bulk insert, the rows
+ * typed in and the import.
+ *
+ * @example
+ * <ExcelImport endpoints={CITY_SHEET} subject="city" onImported={() => table.reload()} />
+ * <ExcelImport endpoints={REGION_SHEET} subject="region" mode="bulk" onImported={() => table.reload()} />
+ */
+export declare function ExcelImport({ endpoints, subject: given, params, onImported, onClose, templateDownload, maxHeight, mode, ref, className }: ExcelImportProps): import("react").JSX.Element;
+/** Options of the import popup: the panel's, plus what the window looks like. */
+export interface OpenExcelImportOptions extends Omit<ExcelImportProps, "onClose" | "ref"> {
+    /** The window's title. Default: "Import <subjects> from a spreadsheet", or "Bulk insert <subjects>". */
+    title?: ReactNode;
+    /** One popup per key. Default: the import endpoint's path and the mode, so one model opens one of each. */
+    popupKey?: string;
+}
+/**
+ * Opens the import panel as a window. This is the one line a data table's Import entry needs - and, with
+ * `mode: "bulk"`, its Bulk insert entry.
+ *
+ * @example onImport={() => openExcelImport({ endpoints: CITY_SHEET, subject: "city", onImported: reload })}
+ */
+export declare function openExcelImport({ title, popupKey, ...props }: OpenExcelImportOptions): PopupHandle;

package/dist/Components/Forms/ExcelImport.js

@@ -0,0 +1,319 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconAlertTriangle, iconChevronDown, iconCircleCheck, iconCopy, iconDownload, iconFile, iconFileImport, iconRefresh, iconTable, iconUpload, InlineIcon } from "nexus-icons";
+import { createRef, useEffect, useId, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { EXCEL_FILE_ACCEPT, EXCEL_ROW_NUMBER, excelColumnInputs, excelCount, excelEditorRows, excelPlural, excelProblemPlace, excelProblems, excelRowNumber, excelRowsOfKind, excelSheetRows, excelText, excelWritableRows, hasExcelValues, isExcelRowTyped, } from "../../Helpers/ExcelHelpers.js";
+import { ExcelRowKind } from "../../Interfaces/ExcelInterfaces.js";
+import { downloadExcelTemplate, excelSettings, importExcelRows, verifyExcelFile } from "../../Services/ExcelApi.js";
+import { toast } from "../Layouts/Toaster.js";
+import { messageBox } from "../Layouts/MessageBox.js";
+import { openPopup } from "../Layouts/PopupHost.js";
+import { Button } from "../Documents/Button.js";
+import { Dropdown } from "../Inputs/Dropdown.js";
+import { TabularForm } from "../Inputs/TabularForm.js";
+const DEFAULT_MAX_HEIGHT = 320;
+/** A bulk insert starts from one empty row: the editor gives each column its own empty value. */
+const BULK_ROWS = [{}];
+/**
+ * The three steps of an import in one panel: the template, the file, and the review - or, for a bulk insert, the rows
+ * typed in and the import.
+ *
+ * @example
+ * <ExcelImport endpoints={CITY_SHEET} subject="city" onImported={() => table.reload()} />
+ * <ExcelImport endpoints={REGION_SHEET} subject="region" mode="bulk" onImported={() => table.reload()} />
+ */
+export function ExcelImport({ endpoints, subject: given, params, onImported, onClose, templateDownload, maxHeight = DEFAULT_MAX_HEIGHT, mode = "file", ref, className }) {
+    const id = useId();
+    const bulk = mode === "bulk";
+    const fileRef = useRef(null);
+    const newRef = useRef(null);
+    const sameRef = useRef(null);
+    const [settings, setSettings] = useState(null);
+    const [file, setFile] = useState(null);
+    const [verify, setVerify] = useState(null);
+    const [imported, setImported] = useState(null);
+    /** The rows already there when the import was sent: skipped, and named in its report. */
+    const [skipped, setSkipped] = useState([]);
+    const [failure, setFailure] = useState(null);
+    /** What an import that wrote nothing refused, row by row: listed under the rows, which stay to be fixed. */
+    const [refused, setRefused] = useState(null);
+    /** The status the person picked for the new records; until they pick, the backend's default. */
+    const [pickedStatus, setPickedStatus] = useState(null);
+    const [busy, setBusy] = useState("settings");
+    /** Bumped on every answer: the editors take their rows again instead of being told to change them. */
+    const [generation, setGeneration] = useState(0);
+    /** The new rows' editor as the person changes it: its rows, and those an import would send. Null: as it started. */
+    const [editorRows, setEditorRows] = useState(null);
+    const [sendableRows, setSendableRows] = useState(null);
+    // A page may well write its endpoints and its params as literals, which are a new object every render. What they
+    // say is what matters, so the settings are asked for again only when that changes.
+    const sheetKey = `${String(endpoints.settings.module)}|${endpoints.settings.path}|${JSON.stringify(params ?? null)}`;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const callOptions = useMemo(() => ({ params }), [sheetKey]);
+    useEffect(() => {
+        let left = false;
+        void (async () => {
+            const answer = await excelSettings(endpoints, callOptions);
+            if (left)
+                return;
+            if (answer.ok && answer.result)
+                setSettings(answer.result);
+            // A file brings its own columns, but rows typed here have nothing else to be drawn from.
+            else if (bulk)
+                setFailure(answer.message ?? excelText("bulkUnavailable"));
+            setBusy(null);
+        })();
+        return () => {
+            left = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [sheetKey]);
+    const subject = given ?? verify?.subject ?? settings?.subject ?? "row";
+    const statuses = settings?.recordStatuses ?? [];
+    const recordStatus = statuses.length ? (pickedStatus ?? settings?.defaultRecordStatus ?? statuses[0].value) : undefined;
+    const statusLabel = statuses.find(status => status.value === recordStatus)?.label;
+    const columns = verify?.columns ?? settings?.columns ?? [];
+    const inputs = useMemo(() => excelColumnInputs(columns), [columns]);
+    const fresh = useMemo(() => (verify ? excelWritableRows(verify.rows) : []), [verify]);
+    const same = useMemo(() => (verify ? excelRowsOfKind(verify.rows, ExcelRowKind.Duplicate) : []), [verify]);
+    const freshRows = useMemo(() => excelEditorRows(fresh, columns), [fresh, columns]);
+    const sameRows = useMemo(() => excelEditorRows(same, columns), [same, columns]);
+    /**
+     * The columns a row typed here can never fill: a required list is picked in the spreadsheet, under a key made for the
+     * person who downloaded it, which no browser can make. A sheet with one is imported from a file only, and its review
+     * takes no rows but the file's.
+     */
+    const requiredLists = useMemo(() => columns.filter(column => column.isReference && column.isRequired), [columns]);
+    const startRows = bulk ? BULK_ROWS : freshRows;
+    const rowCount = editorRows ?? startRows.length;
+    const sendable = sendableRows ?? (bulk ? 0 : freshRows.length);
+    const typing = bulk && requiredLists.length === 0;
+    /** The rows only this screen has - typed here, or a sheet's row edited here - which closing or starting over loses. */
+    const unsavedRows = () => (newRef.current?.getValue() ?? []).filter(row => isExcelRowTyped(row, columns)).length;
+    useImperativeHandle(ref, () => ({ unsavedRows }), [columns]);
+    /** As the person changes the rows: a sheet's row is sent as it is, and a row added here only with something in it. */
+    function onRowsChange(rows) {
+        setEditorRows(rows.length);
+        setSendableRows(rows.filter(row => excelRowNumber(row) > 0 || hasExcelValues(row, columns)).length);
+    }
+    function startEditor() {
+        setEditorRows(null);
+        setSendableRows(null);
+        setRefused(null);
+        setGeneration(value => value + 1);
+    }
+    /** Starting over clears what was typed here too, so it asks first, as closing the window does. */
+    async function onStartOver() {
+        if (await confirmDiscardRows(unsavedRows()))
+            reset();
+    }
+    function reset() {
+        setFile(null);
+        setVerify(null);
+        setImported(null);
+        setSkipped([]);
+        setPickedStatus(null);
+        setFailure(null);
+        startEditor();
+        if (fileRef.current)
+            fileRef.current.value = "";
+    }
+    async function onTemplate() {
+        setBusy("template");
+        await downloadExcelTemplate(endpoints, callOptions);
+        setBusy(null);
+    }
+    async function onPicked(picked) {
+        if (!picked)
+            return;
+        setFile(picked);
+        setVerify(null);
+        setImported(null);
+        setFailure(null);
+        setBusy("checking");
+        const answer = await verifyExcelFile(endpoints, picked, callOptions);
+        setBusy(null);
+        // Clearing the input is what lets the same file be picked again after a fix in the spreadsheet.
+        if (fileRef.current)
+            fileRef.current.value = "";
+        if (!answer.ok || !answer.result) {
+            setFailure(answer.message ?? excelText("verifyFailed"));
+            return;
+        }
+        setVerify(answer.result);
+        startEditor();
+    }
+    async function onImport() {
+        const editor = newRef.current;
+        if (!editor || (!verify && !bulk))
+            return;
+        // A row added here and left empty is not a row - Enter on the last one makes one - so it is dropped, not refused.
+        const before = editor.getValue();
+        for (let index = before.length - 1; index >= 0; index--) {
+            const row = before[index];
+            if (excelRowNumber(row) === 0 && !hasExcelValues(row, columns))
+                editor.remove(index, { undo: false });
+        }
+        const newValues = editor.getValue();
+        if (newValues.length && !editor.validate())
+            return;
+        // A row already there is never updated and cannot be edited here, so only the new rows are sent. A row added here
+        // goes after every row the file had - those already there and those taken out of the review too - so none takes a
+        // number the file uses; a bulk insert has no file, and numbers its rows from 1.
+        const lastRow = verify ? verify.rows.reduce((last, row) => Math.max(last, row.number), 0) : 0;
+        const rows = excelSheetRows(newValues, columns, lastRow);
+        if (!rows.length) {
+            setFailure(excelText("importNothing"));
+            return;
+        }
+        setBusy("importing");
+        const answer = await importExcelRows(endpoints, rows, { ...callOptions, recordStatus });
+        setBusy(null);
+        // An import that wrote nothing - and a call that never answered - leaves the rows where they are, to be fixed and
+        // sent again: the panel says why, and lists under them each row the backend refused, when it sent its report.
+        if (!answer.ok) {
+            setFailure(answer.message ?? excelText("importedNone"));
+            if (answer.result?.refused?.length)
+                setRefused(byRowNumber(answer.result.refused));
+            return;
+        }
+        const written = answer.result;
+        if (!written)
+            return;
+        // Anything else ends the import: the panel shows what was written, what was not and why, and what was skipped.
+        // Another file, or another batch, is a Start over.
+        setFailure(null);
+        setSkipped(same);
+        setImported(written);
+        if (written.created > 0) {
+            toast.success(`${excelCount(written.created, subject)} imported`, { message: written.note });
+            onImported?.(written);
+        }
+    }
+    /**
+     * A problem names a row: clicking it brings that row into view, wherever it has moved to, and puts the caret in it.
+     * A typed row has no sheet row; the import numbered it by its place in the editor.
+     */
+    const goTo = (editor) => (problem) => {
+        const rows = editor.current?.getValue() ?? [];
+        let index = rows.findIndex(row => excelRowNumber(row) === problem.row);
+        if (index < 0 && bulk)
+            index = problem.row - 1;
+        if (index >= 0 && index < rows.length)
+            editor.current?.focusRow(index, problem.field);
+    };
+    const checking = busy === "checking";
+    const importing = busy === "importing";
+    const reviewing = !imported && (bulk ? settings !== null : verify !== null);
+    const canImport = !busy && sendable > 0 && (bulk ? typing : Boolean(verify));
+    const note = bulk
+        ? typing
+            ? `Type one ${subject} per row, up to ${(settings?.maxImportRows ?? 0).toLocaleString("en-US")}. Nothing is written until you import.`
+            : `${requiredLists.map(column => column.header).join(", ")} can only be picked in the spreadsheet, so ${excelPlural(subject)} are imported from one: use Import from a spreadsheet.`
+        : verify?.note;
+    /** What the new rows' line says needs doing: what the import refused, or what the file's check found. */
+    const toFix = refused
+        ? `${excelCount(refused.length, "row")} not written: fix or remove ${refused.length === 1 ? "it" : "them"}, and import again.`
+        : verify && verify.invalid > 0
+            ? `${excelCount(verify.invalid, "row")} to fix before anything is written.`
+            : undefined;
+    return (_jsxs("section", { className: cx("nx-excel", className), "aria-label": bulk ? `Bulk insert ${excelPlural(subject)}` : `Import ${excelPlural(subject)} from a spreadsheet`, "data-nx-excel": "", children: [!bulk && !file && (_jsxs("ol", { className: "nx-excel__steps", children: [_jsxs("li", { children: ["Download the template", templateDownload === false ? "" : " below", ": every list in it is a dropdown, and the ids beside a choice fill themselves."] }), _jsxs("li", { children: ["Fill in one row per ", subject, ". Leave the locked columns alone."] }), _jsx("li", { children: "Send it here to be checked. Nothing is written until you import." })] })), !bulk && (_jsxs("div", { className: "nx-excel__pick", children: [!file && templateDownload !== false && (_jsx(Button, { icon: _jsx(InlineIcon, { icon: iconDownload }), loading: busy === "template", onClick: onTemplate, children: excelText("template") })), _jsx("input", { ref: fileRef, id: `${id}-file`, className: "nx-visually-hidden", type: "file", accept: EXCEL_FILE_ACCEPT, onChange: event => void onPicked(event.currentTarget.files?.[0]) }), !file && (_jsx(Button, { variant: "primary", icon: _jsx(InlineIcon, { icon: iconFileImport }), onClick: () => fileRef.current?.click(), children: excelText("choose") })), _jsx("p", { className: "nx-excel__file", "data-nx-excel-file": "", children: checking ? (_jsxs(_Fragment, { children: [excelText("checking"), " ", _jsx("strong", { children: file?.name }), String.fromCharCode(8230)] })) : file ? (_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconFile, "aria-hidden": "true" }), _jsx("strong", { children: file.name })] })) : (_jsx("span", { className: "nx-excel__muted", children: excelText("nothingPicked") })) }), settings && (_jsxs("p", { className: "nx-excel__limits", children: [excelCount(settings.maxImportRows, "row"), " at most per file"] }))] })), failure && (_jsxs("p", { className: "nx-excel__failure", role: "alert", "data-nx-excel-failure": "", children: [_jsx(InlineIcon, { icon: iconAlertTriangle, "aria-hidden": "true" }), _jsx("span", { children: failure })] })), imported && _jsx(ImportedReport, { answer: imported, subject: subject, skipped: skipped, status: statusLabel, byRow: bulk }), reviewing && (_jsxs("div", { className: "nx-excel__review", "data-nx-excel-review": "", inert: importing, children: [_jsx("p", { className: "nx-excel__note", children: note }), statuses.length > 0 && (bulk ? typing : fresh.length > 0) && (_jsx("div", { className: "nx-excel__status", children: _jsx(Dropdown, { name: `${id}-status`, label: "New records start as", size: "sm", options: statuses, 
+                            // Always one: there is no record without a status, so nothing to clear.
+                            clearable: false, value: recordStatus, onValueChange: (value) => setPickedStatus(value), hint: "Change it later on each record." }) })), (bulk ? typing : fresh.length > 0) && (_jsx(ReviewSection, { id: `${id}-new`, title: excelText("newRows"), tone: toFix ? "warning" : "neutral", count: rowCount, hint: toFix, rows: refused ?? fresh, byRow: bulk, onGo: goTo(newRef), 
+                        // What the person types is in this editor only, and folding the section away would take it with it.
+                        fixed: true, children: _jsx(TabularForm, { ref: newRef, "aria-label": excelText("newRows"), inputs: inputs, itemLabel: subject, defaultValue: startRows, 
+                            // A sheet's row is the row's id: a copy leaves it behind, so it is never sent as that row of the file.
+                            rowKey: EXCEL_ROW_NUMBER, 
+                            // A row added here could never fill a required list, so such a sheet's review takes the file's rows only.
+                            addable: requiredLists.length === 0, max: settings?.maxImportRows, sortable: false, actionsAt: "end", lockable: true, maxHeight: maxHeight, size: "sm", onValueChange: onRowsChange }, `new-${generation}`) })), same.length > 0 && (_jsx(ReviewSection, { id: `${id}-same`, title: excelText("duplicates"), tone: "muted", count: same.length, hint: excelText("duplicateHint"), rows: same, onGo: goTo(sameRef), children: _jsx(TabularForm, { ref: sameRef, "aria-label": excelText("duplicates"), inputs: inputs, itemLabel: subject, defaultValue: sameRows, readOnly: true, readOnlyMessage: excelText("duplicateHint"), maxHeight: maxHeight, size: "sm" }, `same-${generation}`) }))] })), _jsxs("footer", { className: "nx-excel__actions", children: [imported ? (_jsx("p", { className: "nx-excel__sending", children: excelText(bulk ? "addAgain" : "importAgain") })) : (reviewing &&
+                        (bulk ? typing : rowCount > 0 || same.length > 0) && (_jsxs("p", { className: "nx-excel__sending", "data-nx-excel-sending": "", children: [sendable > 0 ? `${excelCount(sendable, subject)} to send.` : "Nothing to send.", same.length > 0 ? ` ${excelCount(same.length, subject)} already there ${same.length === 1 ? "is" : "are"} skipped.` : ""] }))), _jsxs("div", { className: "nx-excel__buttons", children: [!busy && (file || (bulk && imported)) && (_jsx(Button, { variant: "secondary", icon: _jsx(InlineIcon, { icon: iconRefresh }), onClick: () => void onStartOver(), children: excelText("startOver") })), onClose && (_jsx(Button, { variant: "secondary", onClick: onClose, children: excelText("close") })), !imported && (_jsx(Button, { variant: "primary", icon: _jsx(InlineIcon, { icon: iconUpload }), loading: importing, disabled: !canImport, onClick: () => void onImport(), children: excelText("importLabel") }))] })] })] }));
+}
+/**
+ * One half of the review: a line that says what these rows are and how many, and the editor under it. The duplicates
+ * fold away, because a person with twenty of them and three new rows is looking at the three; the new rows do not, as
+ * folding them would take what the person typed with them.
+ */
+function ReviewSection({ id, title, count, tone, hint, rows, onGo, byRow = false, open: openByDefault = false, fixed = false, children }) {
+    const [opened, setOpened] = useState(openByDefault);
+    const open = fixed || opened;
+    const problems = useMemo(() => excelProblems(rows), [rows]);
+    const duplicates = useMemo(() => rows.filter(row => row.duplicate), [rows]);
+    const head = (_jsxs(_Fragment, { children: [!fixed && _jsx(InlineIcon, { icon: iconChevronDown, className: "nx-excel__chevron", "aria-hidden": "true" }), _jsx("span", { className: "nx-excel__title", children: title }), _jsx("span", { className: "nx-excel__tag", children: count.toLocaleString("en-US") }), hint && _jsx("span", { className: "nx-excel__hint", children: hint })] }));
+    return (_jsxs("section", { className: "nx-excel__section", "data-open": open || undefined, "data-tone": tone, "data-nx-excel-section": title, children: [_jsx("h3", { className: "nx-excel__section-head", children: fixed ? (_jsx("span", { className: "nx-excel__toggle", "data-fixed": "", children: head })) : (_jsx("button", { type: "button", className: "nx-excel__toggle", "aria-expanded": open, "aria-controls": open ? id : undefined, onClick: () => setOpened(!open), children: head })) }), open && (_jsxs("div", { className: "nx-excel__section-body", id: id, children: [children, problems.length > 0 && _jsx(ProblemList, { problems: problems, onGo: onGo, byRow: byRow }), duplicates.length > 0 && (_jsxs("div", { className: "nx-excel__problems nx-excel__problems--same", "data-nx-excel-duplicates": "", children: [_jsxs("p", { className: "nx-excel__problems-head", children: [_jsx(InlineIcon, { icon: iconCopy, "aria-hidden": "true" }), _jsx("span", { children: excelText("whyDuplicate") })] }), _jsx("ul", { children: duplicates.map(row => (_jsxs("li", { children: [_jsxs("span", { className: "nx-excel__place", children: ["Row ", row.number] }), _jsx("span", { children: row.duplicate })] }, row.number))) })] }))] }))] }));
+}
+/** What the server found wrong, each naming the cell the person reads - or, for rows typed here, the row - and taking them to it. */
+function ProblemList({ problems, onGo, byRow = false }) {
+    return (_jsxs("div", { className: "nx-excel__problems", "data-nx-excel-problems": "", children: [_jsxs("p", { className: "nx-excel__problems-head", children: [_jsx(InlineIcon, { icon: iconAlertTriangle, "aria-hidden": "true" }), _jsx("span", { children: excelText("toFix") })] }), _jsx("ul", { children: problems.map(problem => (_jsxs("li", { children: [onGo ? (_jsx("button", { type: "button", className: "nx-excel__place nx-excel__go", onClick: () => onGo(problem), children: excelProblemPlace(problem, byRow) })) : (_jsx("span", { className: "nx-excel__place", children: excelProblemPlace(problem, byRow) })), _jsx("span", { children: problem.message })] }, `${problem.row}:${problem.column}:${problem.message}`))) })] }));
+}
+/**
+ * What the import did, in three parts side by side rather than inside one another: what was written, in the backend's
+ * own words; what was not, and why, problem by problem; and what was skipped because it is already a record. Rows
+ * typed here have no sheet, so `byRow` names a problem by its row rather than by a spreadsheet's cell.
+ */
+function ImportedReport({ answer, subject, skipped, status, byRow }) {
+    const wrote = answer.created > 0;
+    const refused = byRowNumber(answer.refused ?? []);
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: cx("nx-excel__result", wrote ? "nx-excel__result--ok" : "nx-excel__result--none"), role: "status", "data-nx-excel-result": "", children: [_jsxs("p", { className: "nx-excel__result-head", children: [_jsx(InlineIcon, { icon: wrote ? iconCircleCheck : iconAlertTriangle, "aria-hidden": "true" }), _jsx("strong", { children: wrote ? `${excelCount(answer.created, subject)} added${status ? ` as ${status}` : ""}` : excelText("importedNone") })] }), _jsx("p", { className: "nx-excel__result-note", children: answer.note })] }), refused.length > 0 && (_jsxs("div", { className: "nx-excel__problems", children: [_jsxs("p", { className: "nx-excel__problems-head", children: [_jsx(InlineIcon, { icon: iconAlertTriangle, "aria-hidden": "true" }), _jsxs("span", { children: [excelText("failedHead"), " (", refused.length.toLocaleString("en-US"), ")"] })] }), _jsx("ul", { children: refused.flatMap(row => row.problems?.length
+                            ? row.problems.map(problem => (_jsxs("li", { children: [_jsx("span", { className: "nx-excel__place", children: excelProblemPlace(problem, byRow) }), _jsx("span", { children: problem.message })] }, `${row.number}:${problem.column}:${problem.message}`)))
+                            : [
+                                _jsxs("li", { children: [_jsxs("span", { className: "nx-excel__place", children: ["Row ", row.number] }), _jsx("span", { children: row.duplicate ?? excelText("refused") })] }, row.number),
+                            ]) })] })), skipped.length > 0 && (_jsxs("div", { className: "nx-excel__problems nx-excel__problems--same", children: [_jsxs("p", { className: "nx-excel__problems-head", children: [_jsx(InlineIcon, { icon: iconCopy, "aria-hidden": "true" }), _jsxs("span", { children: [excelText("skippedHead"), " (", skipped.length.toLocaleString("en-US"), ")"] })] }), _jsx("ul", { children: skipped.map(row => (_jsxs("li", { children: [_jsxs("span", { className: "nx-excel__place", children: ["Row ", row.number] }), _jsx("span", { children: row.duplicate ?? excelText("duplicateHint") })] }, row.number))) })] }))] }));
+}
+/** Rows in the order the person reads them: by their row, whatever order the backend listed them in. */
+function byRowNumber(rows) {
+    return [...rows].sort((a, b) => a.number - b.number);
+}
+/** The import windows open now, by popup key, so a second opening can see what the first one holds. */
+const openPanels = new Map();
+/**
+ * Opens the import panel as a window. This is the one line a data table's Import entry needs - and, with
+ * `mode: "bulk"`, its Bulk insert entry.
+ *
+ * @example onImport={() => openExcelImport({ endpoints: CITY_SHEET, subject: "city", onImported: reload })}
+ */
+export function openExcelImport({ title, popupKey, ...props }) {
+    const subject = props.subject ?? "row";
+    const bulk = props.mode === "bulk";
+    // A key of its own for a bulk insert, so opening one never closes an import whose review is half gone over.
+    const key = popupKey ?? `${bulk ? "nx-excel-bulk" : "nx-excel"}:${String(props.endpoints.import.module)}:${props.endpoints.import.path}`;
+    // Picked again while its window is still open - minimized, say - a window holding rows typed or changed in it comes
+    // back as it was, as a CRUD's Add form with changes does; an untouched one, or one showing an import's report, is
+    // replaced by a fresh panel.
+    const open = openPanels.get(key);
+    if (open && (open.panel.current?.unsavedRows() ?? 0) > 0) {
+        open.handle.restore();
+        return open.handle;
+    }
+    const panel = createRef();
+    const handle = openPopup({
+        key,
+        title: title ?? (bulk ? `Bulk insert ${excelPlural(subject)}` : `Import ${excelPlural(subject)} from a spreadsheet`),
+        icon: _jsx(InlineIcon, { icon: iconTable }),
+        size: "xl",
+        closeOnBackdrop: false,
+        // What was typed or changed here is in no file: closing over it asks first, as a form with changes does.
+        beforeClose: () => confirmDiscardRows(panel.current?.unsavedRows() ?? 0),
+        // No Close of its own: the window's title bar already has one, and two ways out of one panel is one too many.
+        content: _jsx(ExcelImport, { ...props, ref: panel }),
+    });
+    const entry = { handle, panel };
+    openPanels.set(key, entry);
+    void handle.closed.then(() => {
+        if (openPanels.get(key) === entry)
+            openPanels.delete(key);
+    });
+    return handle;
+}
+/** Asks before rows only this screen has are thrown away. With nothing to lose, nothing is asked. */
+function confirmDiscardRows(rows) {
+    if (rows === 0)
+        return true;
+    return messageBox.confirm({
+        title: excelText("discardTitle"),
+        message: `${excelCount(rows, "row")} you typed or changed here will be lost.`,
+        tone: "warning",
+        confirmLabel: excelText("discardLabel"),
+        cancelLabel: excelText("keepEditing"),
+    });
+}

package/dist/Components/Forms/Form.js

@@ -1,5 +1,6 @@
 "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";
@@ -9,7 +10,6 @@ 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";
@@ -21,8 +21,6 @@ import { firstFocusable } from "../Inputs/RowsInput.js";
  */
 /** 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";
@@ -124,6 +122,9 @@ const FormCell = memo(function FormCell({ store, params, context }) {
     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))
@@ -132,13 +133,6 @@ const FormCell = memo(function FormCell({ store, params, context }) {
     }
     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);
@@ -182,7 +176,7 @@ export function Form(props) {
     // 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 });
+        store.load(props.defaultValue ?? {}, { draft: !loading, quiet: true, loading });
     }
     useLayoutEffect(() => store.announce(), [store]);
     // Inputs or settings that change what is valid check every value again; callbacks only swap.
@@ -312,8 +306,10 @@ export function Form(props) {
         if (first && isFirstInvalid(event.currentTarget))
             focusInput(first);
     }
-    const context = useMemo(() => ({ idPrefix, size, design, readOnly, disabled, scopeNames: !inForm }), [idPrefix, size, design, readOnly, disabled, inForm]);
+    // 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]);
     // 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.map(params => params.hidden ? null : loading ? (_jsx(SkeletonCell, { params: params, design: design }, params.name)) : (_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 })] }))] }));
+    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/SubmitForm.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
 import type { AnyFormStore, FormStore } from "../../Helpers/FormStore.ts";
-import type { FormValues, SubmitFormProps } from "../../Interfaces/FormInterfaces.ts";
+import type { FormStatusLineMode, 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`. */
@@ -25,6 +25,15 @@ export interface FormButtonsProps<TValues extends FormValues = FormValues> {
     size?: Size;
     /** Nothing to save: only Cancel shows. */
     readOnly?: boolean;
+    /** What the status line reports. Default `full`; `errors` for a short form that keeps nothing, such as a sign-in or a search. */
+    statusLine?: FormStatusLineMode;
+    /** The buttons share the bar's whole width, such as a sign-in's one button across its card. */
+    block?: boolean;
+    /**
+     * With `statusLine="errors"` the line keeps quiet, so while the form loads the submit button says it instead: a
+     * spinner and this. Default "Loading…".
+     */
+    loadingLabel?: ReactNode;
     className?: string;
 }
 /**
@@ -43,7 +52,7 @@ export declare function confirmDiscard(form: AnyFormStore): Promise<boolean>;
  *   <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;
+export declare function FormButtons<TValues extends FormValues = FormValues>({ form, submitLabel, submitIcon, onCancel, confirmCancel, cancelLabel, resettable, resetLabel, align, size, readOnly, statusLine, block, loadingLabel, 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