nexus-shared 2.0.0 → 3.0.0

package/dist/Components/Forms/Crud.js

@@ -1,11 +1,11 @@
 "use client";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { iconArchive, iconArchiveOff, iconEye, iconFlag, iconFlagOff, iconList, iconLock, iconNotes, iconPencil, iconPin, iconPinnedOff, iconPlus, iconRestore, iconTrash, iconTrashX, InlineIcon, } from "nexus-icons";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconEye, iconFlag, iconFlagOff, iconList, iconLock, iconNotes, iconPencil, iconPin, iconPinnedOff, iconPlus, iconRestore, iconTrash, iconTrashX, InlineIcon, } from "nexus-icons";
 import { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { abortError } from "../../Helpers/ApiFormHelpers.js";
 import { unwrapApiResult } from "../../Helpers/ApiResponses.js";
 import { getCrudBackend } from "../../Helpers/CrudBackend.js";
-import { actionAllowed, availableModes, CRUD_CACHE_LIFETIME, CRUD_MODES, CRUD_ROW_ACTIONS, CrudCache, crudListEndpoint, crudMassActions, crudMessageAction, crudRowActions, crudRowEndpoint, getCrudSettings, leavesList, massActionAllowed, pinRoom, } from "../../Helpers/CrudHelpers.js";
+import { actionAllowed, availableModes, CRUD_CACHE_LIFETIME, CRUD_MODES, CRUD_ROW_ACTIONS, CrudCache, crudCacheMode, crudListEndpoint, crudMassActions, crudMessageAction, crudRowActions, crudRowEndpoint, getCrudSettings, leavesList, massActionAllowed, patchCachedList, pinRoom, } from "../../Helpers/CrudHelpers.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { FormStore } from "../../Helpers/FormStore.js";
 import { pluralize } from "../../Helpers/MessageBuilder.js";
@@ -22,23 +22,22 @@ import { CrudDetails } from "./CrudParts.js";
 import { confirmDiscard, FormButtons } from "./SubmitForm.js";
 /*
  * Crud: a module's records in one component. It takes a controller's endpoints, the table's columns, and the form's
- * inputs, and handles the rest: the lists (all, flagged, archived, trash, deleted) the user may see, the actions they
+ * inputs, and handles the rest: the lists (all, flagged, trash, deleted) the user may see, the actions they
  * may take, the records the user pinned in a section above the list, Add and Edit popups built on ApiForm, a details
  * popup, actions on many rows, a cache of lists while the page is open, and rows updated from each answer instead of
  * reloading.
  */
-const ALL_ACTIONS = ["create", "view", "edit", "flag", "pin", "archive", "restore", "trash", "recover", "delete", "trashFromDelete", "description"];
+const ALL_ACTIONS = ["create", "view", "edit", "flag", "pin", "trash", "recover", "delete", "trashFromDelete", "description"];
 const MODE_INFO = {
     normal: { label: "All", icon: iconList, empty: plural => `No ${plural} yet.` },
     flag: { label: "Flagged", icon: iconFlag, empty: plural => `No flagged ${plural}.` },
-    archive: { label: "Archived", icon: iconArchive, empty: () => "The archive is empty." },
     trash: { label: "Trash", icon: iconTrash, empty: () => "The trash is empty." },
     deleted: { label: "Deleted", icon: iconTrashX, empty: plural => `No deleted ${plural}.` },
 };
-/** Actions that take a record out of reach are asked about first; flags, pins, restore, and recover are undone by a click. */
-const ASKED = new Set(["archive", "trash", "delete", "trashFromDelete"]);
+/** Actions that take a record out of reach are asked about first; flags, pins and recover are undone by a click. */
+const ASKED = new Set(["trash", "delete", "trashFromDelete"]);
 /** Actions that take a record out of the active lists, so it is no longer among the pinned records either. */
-const LEFT_ACTIVE = new Set(["archive", "trash", "delete", "trashFromDelete"]);
+const LEFT_ACTIVE = new Set(["trash", "delete", "trashFromDelete"]);
 /** The words of an action that flags some records and unflags others (a mass toggle of a mixed selection). */
 const TOGGLED_FLAG = { verb: "change the flags of {object}", done: "updated", doing: "Changing the flags of {object}", object: "the records" };
 const capitalize = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
@@ -51,6 +50,21 @@ function endpointSubject(api) {
     const endpoints = [api.create, api.update, api.details, ...Object.values(api.lists ?? {}), ...Object.values(api.pages ?? {})];
     return endpoints.find(endpoint => endpoint?.subject)?.subject;
 }
+/**
+ * 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.
+ */
+function CrudFormBody({ aside, details, children }) {
+    if (!aside)
+        return children;
+    return (_jsxs("div", { className: cx("nx-crud-aside", details && "nx-crud-aside--details"), children: [_jsx("div", { className: "nx-crud-aside__main", children: children }), _jsx("aside", { className: "nx-crud-aside__side", children: aside })] }));
+}
+/** Whether the details endpoint's record says anything the list's row did not. Plain JSON, compared field by field. */
+function addsToRow(row, full) {
+    return Object.entries(full).some(([name, value]) => JSON.stringify(value) !== JSON.stringify(row[name]));
+}
 /**
  * A CRUD page in one component: a data table of a controller's records with its lists, Add and Edit popups, details,
  * and actions on one record or many, each shown only when its endpoint exists and the user may call it.
@@ -89,7 +103,7 @@ export function Crud(props) {
     }, [ready, api, wantedActions, can]);
     const massAllowed = useMemo(() => {
         const map = {};
-        for (const action of ["flag", "pin", "archive", "restore", "trash", "recover", "delete", "trashFromDelete", "description"])
+        for (const action of ["flag", "pin", "trash", "recover", "delete", "trashFromDelete", "description"])
             map[action] = ready && massActionAllowed(action, api, wantedActions, can);
         return map;
     }, [ready, api, wantedActions, can]);
@@ -204,27 +218,46 @@ export function Crud(props) {
             return result;
         });
     }, [mode, api, paging, cache, backend, plural]);
-    /** After a change: the list shown keeps its rows in the cache, the other lists load again when shown. */
-    function afterChange(action, rows) {
+    /** Which list a record belongs in, as this backend reads the record. */
+    const member = (row, of) => backend.listMembership(row, of);
+    /**
+     * The lists kept in the cache, after a change: **every one of them is patched**, from the record the answer
+     * carried. A record flagged joins the flagged list, a record trashed leaves the active list and joins the trash,
+     * and coming back to any of them costs no request. Only a list the record cannot answer for (`changes` empty, or
+     * a backend with no `listMembership`) is dropped, and that one loads when it is shown.
+     *
+     * A server page is not patched when a record joined it or left it: its order, its last row and its counts are the
+     * server's, so that page is dropped and the next one loads. One whose rows only changed is written in place.
+     */
+    function syncCaches(changes) {
         const shown = modeRef.current;
-        if (paging === "client" && shown) {
-            cache.drop(key => key !== shown);
-            cache.update(shown, table.getRows());
-        }
+        if (changes.length)
+            cache.map((key, value) => patchCachedList(value, crudCacheMode(key), changes, row => table.keyOf(row), member));
         else
             cache.clear();
+        // The list on screen is the table's own, every row of it, so it is written back whole rather than patched.
+        if (paging === "client" && shown)
+            cache.update(shown, table.getRows());
+    }
+    function afterChange(action, rows, changes) {
+        syncCaches(changes);
+        const shown = modeRef.current;
         if (shown)
             latest.current.onChange?.({ action, rows, mode: shown });
     }
-    /* Changing rows after an answer */
-    function applyChange(action, rows, result, markOn, values) {
+    function applyChange(action, rows, options = {}) {
+        const { result, mass = false, markOn, values } = options;
         const shown = modeRef.current;
         if (!shown)
             return;
         const answered = rows.length > 1 ? backend.answeredKeys(result, rowKey) : null;
         const done = answered ? rows.filter(row => answered.has(table.keyOf(row))) : rows;
+        const changes = backend.answeredChanges(result, rowKey);
+        // What the answer said about the one record acted on: the record, or the fields that changed - a mark's new
+        // status. It is what lets the other lists be patched rather than thrown away.
+        const one = mass ? null : backend.answeredRow(result);
+        const moved = [];
         if (action === "flag") {
-            const changes = backend.answeredChanges(result, rowKey);
             const leaving = [];
             const updated = [];
             for (const row of done) {
@@ -235,19 +268,21 @@ export function Crud(props) {
                 const change = changes.get(key);
                 if (change)
                     next = { ...next, ...change };
+                if (one)
+                    next = { ...next, ...one };
                 if (leavesList(action, shown, backend.isFlagged(next)))
                     leaving.push(key);
                 else
                     table.upsert(next, { flash: false });
                 updated.push(next);
+                moved.push({ key, row: next, before: current });
             }
             table.remove(leaving);
             patchPins(updated);
-            afterChange(action, updated);
+            afterChange(action, updated, moved);
             return;
         }
         if (action === "pin") {
-            const changes = backend.answeredChanges(result, rowKey);
             const updated = [];
             for (const row of done) {
                 const key = table.keyOf(row);
@@ -257,29 +292,89 @@ export function Crud(props) {
                 const change = changes.get(key);
                 if (change)
                     next = { ...next, ...change };
+                if (one)
+                    next = { ...next, ...one };
                 // A pin changes the section above the list, never the list itself: the record stays where it is, on its page.
                 if (table.getRow(key))
                     table.upsert(next, { flash: false });
                 updated.push(next);
+                moved.push({ key, row: next, before: current });
             }
             applyPins(updated);
-            afterChange(action, updated);
+            afterChange(action, updated, moved);
             return;
         }
         if (action === "description") {
-            const updated = done.map(row => ({ ...(table.getRow(table.keyOf(row)) ?? row), ...values }));
-            for (const row of updated)
-                table.upsert(row);
+            const updated = [];
+            for (const row of done) {
+                const key = table.keyOf(row);
+                const current = table.getRow(key) ?? row;
+                const next = { ...current, ...values };
+                table.upsert(next);
+                updated.push(next);
+                moved.push({ key, row: next, before: current });
+            }
             patchPins(updated);
-            afterChange(action, updated);
+            afterChange(action, updated, moved);
             return;
         }
+        // Trash, recover, delete and the move back to the trash take the record to another band, and only the answer
+        // says which. Every record has to say so for the other lists to be patched; one that does not leaves `moved`
+        // empty, and they load again, which is what they all did before.
         const keys = done.map(row => table.keyOf(row));
+        const updated = [];
+        for (const row of done) {
+            const key = table.keyOf(row);
+            const current = table.getRow(key) ?? row;
+            const change = changes.get(key) ?? one;
+            const next = change ? { ...current, ...change } : current;
+            if (change)
+                moved.push({ key, row: next, before: current });
+            updated.push(next);
+        }
+        if (moved.length !== done.length)
+            moved.length = 0;
         if (leavesList(action, shown))
             table.remove(keys);
         if (LEFT_ACTIVE.has(action))
             dropPins(keys);
-        afterChange(action, done);
+        afterChange(action, updated, moved);
+    }
+    /**
+     * Records a page's own action changed, written exactly where the built-in ones write theirs. The handle's `apply`.
+     */
+    function applyRows(rows, gone = false) {
+        const shown = modeRef.current;
+        if (!shown || rows.length === 0)
+            return;
+        const moved = [];
+        const updated = [];
+        const leaving = [];
+        let pinned = false;
+        for (const given of rows) {
+            const next = { ...(table.getRow(table.keyOf(given)) ?? {}), ...given };
+            const key = table.keyOf(next);
+            if (!key)
+                continue;
+            const before = table.getRow(key);
+            // The record decides whether it is still in the list on screen; a backend that cannot say keeps it there.
+            if (gone || member(next, shown) === false)
+                leaving.push(key);
+            else if (before)
+                table.upsert(next, { flash: false });
+            if (before && backend.isPinned(next) !== backend.isPinned(before))
+                pinned = true;
+            updated.push(next);
+            moved.push({ key, row: next, before, gone });
+        }
+        table.remove(leaving);
+        if (gone)
+            dropPins(leaving);
+        else if (pinned)
+            applyPins(updated);
+        else
+            patchPins(updated);
+        syncCaches(moved);
     }
     /* Row actions */
     async function runRowAction(action, row) {
@@ -295,7 +390,7 @@ export function Crud(props) {
         const options = { params: { id: key, [rowKey]: key }, subject: labelOf(row), action: crudMessageAction(action, markOn) };
         const answer = ASKED.has(action) ? await browserApi.confirm(endpoint, options) : await browserApi.send(endpoint, options);
         if (answer?.ok)
-            applyChange(action, [row], answer.result, markOn);
+            applyChange(action, [row], { result: answer.result, markOn });
     }
     async function runMassAction(action, rows) {
         if (action === "description") {
@@ -332,7 +427,7 @@ export function Crud(props) {
         const answer = ASKED.has(action) ? await browserApi.confirm(endpoint, options) : await browserApi.send(endpoint, options);
         if (!answer?.ok)
             return;
-        applyChange(action, sent, answer.result, markOn);
+        applyChange(action, sent, { result: answer.result, mass: true, markOn });
         table.clearSelection();
         if (over > 0)
             toast.warning(`${sent.length} of ${sent.length + over} ${plural} pinned: you can pin up to ${maxPins}.`);
@@ -384,10 +479,10 @@ export function Crud(props) {
                     form.dropDraft();
                 return discard;
             },
-            content: popup => (_jsx(ApiForm, { form: form, inputs: inputs, buttons: false, defaultValue: (action === "create" ? { ...newValues, ...values } : (row ?? undefined)), loadValue: loadValue, api: endpoint, transform: options.transform ? formValues => options.transform(formValues, { action, row }) : undefined, validate: options.validate, onFieldChange: options.onFieldChange, design: options.design, draftKey: options.draftKey ? `${options.draftKey}:${name}:${action === "create" ? "new" : key}` : undefined, "aria-label": action === "create" ? `Add ${subject}` : `Edit ${label}`, onSuccess: (result, saved) => {
-                    onSaved(action, row, result, saved);
-                    popup.close();
-                } })),
+            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" ? { ...newValues, ...values } : (row ?? undefined)), loadValue: loadValue, api: endpoint, transform: options.transform ? formValues => options.transform(formValues, { action, row }) : undefined, validate: options.validate, onFieldChange: options.onFieldChange, design: options.design, draftKey: options.draftKey ? `${options.draftKey}:${name}:${action === "create" ? "new" : key}` : undefined, "aria-label": action === "create" ? `Add ${subject}` : `Edit ${label}`, onSuccess: (result, saved) => {
+                        onSaved(action, row, result, saved);
+                        popup.close();
+                    } }) })),
             footer: popup => _jsx(FormButtons, { form: form, submitLabel: action === "create" ? `Add ${subject}` : "Save", onCancel: () => popup.close() }),
         });
         if (action === "create") {
@@ -399,23 +494,57 @@ export function Crud(props) {
             });
         }
     }
+    /**
+     * The record a `Create` answered only the key of, read back on its own: the row goes in at once with what the form
+     * sent, and the fields the server owns - its status, its times, anything it worked out - land a moment later. One
+     * small request, where loading the list again was a request for every record on it.
+     */
+    async function fillSaved(key, record) {
+        const endpoint = api.details;
+        if (!endpoint)
+            return;
+        const id = readPath(record, rowKey);
+        const answer = await browserApi.get(endpoint, { params: { id, [rowKey]: id }, toast: false });
+        const full = unwrapApiResult(answer);
+        if (!isRecord(full))
+            return;
+        const before = table.getRow(key);
+        const next = { ...(before ?? record), ...full };
+        if (before)
+            table.upsert(next, { flash: false });
+        syncCaches([{ key, row: next, before }]);
+    }
     function onSaved(action, row, result, values) {
-        const record = { ...row, ...values, ...(isRecord(result) ? result : {}) };
+        // The record as the server now has it: what was sent, over the row it came from, with whatever the answer added.
+        // A backend that answers the record it wrote leaves nothing to load at all.
+        const answered = backend.answeredRow(result);
+        const record = { ...row, ...values, ...answered };
         const shown = modeRef.current;
         if (action === "edit") {
+            const key = table.keyOf(record);
+            const before = table.getRow(key);
             table.upsert(record);
             patchPins([record]);
-            afterChange("edit", [record]);
+            afterChange("edit", [record], key ? [{ key, row: record, before }] : []);
             return;
         }
-        // A new record belongs to the list of every record; without its key from the server, the list loads again.
+        // A new record belongs to the list of every record. An answer that is only the new key still gives it one, so
+        // the row goes in and the record is read back on its own; without even a key the list has to load again.
+        if (!answered && !readPath(record, rowKey)) {
+            const given = backend.answeredKey(result);
+            if (given !== null && !rowKey.includes("."))
+                record[rowKey] = given;
+        }
+        const key = table.keyOf(record);
         if (shown === "normal") {
-            if (table.keyOf(record))
+            if (key)
                 table.upsert(record);
             else
                 void table.reload({ quiet: true });
         }
-        afterChange("create", [record]);
+        afterChange("create", [record], key ? [{ key, row: record, before: undefined }] : []);
+        if (key && !answered && api.details)
+            void fillSaved(key, record);
     }
     function openDetails(row) {
         const details = latest.current.details;
@@ -424,14 +553,32 @@ export function Crud(props) {
         const key = table.keyOf(row);
         const canEdit = allowed.edit && modeRef.current !== undefined && CRUD_ROW_ACTIONS[modeRef.current].includes("edit");
         const endpoint = api.details;
+        // The panel's record: the row at once, so it has something to show while the full one loads, and that one after.
+        const shown = typeof details?.aside === "function" ? new FormStore() : null;
+        shown?.load(row, { draft: false });
+        const aside = typeof details?.aside === "function" ? details.aside({ form: shown, row }) : details?.aside;
         openPopup({
             key: `${name}-view-${key}`,
             reopen: "restore",
-            title: `${capitalize(subject)} details`,
+            title: `${capitalize(subject)} ${details?.label ?? "details"}`,
             description: labelOf(row),
             icon: _jsx(InlineIcon, { icon: iconEye }),
             size: details?.size ?? "md",
-            content: (_jsx(CrudDetails, { row: row, columns: details?.columns ?? latest.current.columns, render: details?.render, load: endpoint ? signal => browserApi.get(endpoint, { params: { id: rawKey(row), [rowKey]: rawKey(row) }, signal, toast: false }).then(unwrapApiResult) : undefined })),
+            // Focus goes where it goes without a panel, the footer, rather than to the first button the panel happens to
+            // draw: a panel that renders at once (a Copy button) would otherwise take it, and one that loads would not.
+            initialFocus: aside ? ".nx-popup__foot button" : undefined,
+            content: (_jsx(CrudFormBody, { aside: aside, details: true, children: _jsx(CrudDetails, { row: row, columns: details?.columns ?? latest.current.columns, render: details?.render, load: endpoint
+                        ? signal => browserApi
+                            .get(endpoint, { params: { id: rawKey(row), [rowKey]: rawKey(row) }, signal, toast: false })
+                            .then(unwrapApiResult)
+                            .then(full => {
+                            // Only when it adds something: a panel that renders from the record would otherwise ask again
+                            // for exactly what it is already showing.
+                            if (shown && isRecord(full) && addsToRow(row, full))
+                                shown.load({ ...row, ...full }, { draft: false });
+                            return full;
+                        })
+                        : undefined }) })),
             footer: popup => (_jsxs(_Fragment, { children: [canEdit && (_jsx(Button, { icon: _jsx(InlineIcon, { icon: iconPencil }), onClick: () => {
                             popup.close();
                             void openForm("edit", table.getRow(key) ?? row);
@@ -453,7 +600,7 @@ export function Crud(props) {
             closeOnBackdrop: false,
             beforeClose: () => confirmDiscard(form),
             content: popup => (_jsx(ApiForm, { form: form, buttons: false, inputs: [{ type: "textarea", name: "description", label: "Description", maxLength: 500, rows: 4, showCount: true }], api: endpoint, transform: values => backend.massRequest("description", rows.map(rawKey), values), "aria-label": `Description of ${count} ${count === 1 ? subject : plural}`, onSuccess: (result, values) => {
-                    applyChange("description", rows, result, undefined, values);
+                    applyChange("description", rows, { result, mass: true, values });
                     table.clearSelection();
                     popup.close();
                 } })),
@@ -461,8 +608,8 @@ export function Crud(props) {
         });
     }
     // Row actions and the handle call these through a ref, so the table's callbacks stay the same between renders.
-    const run = useRef({ runRowAction, runMassAction, openForm, openDetails });
-    run.current = { runRowAction, runMassAction, openForm, openDetails };
+    const run = useRef({ runRowAction, runMassAction, openForm, openDetails, applyRows });
+    run.current = { runRowAction, runMassAction, openForm, openDetails, applyRows };
     /* The table's callbacks */
     const rowActions = useCallback((row) => {
         if (!mode)
@@ -472,12 +619,10 @@ export function Crud(props) {
         const flagged = backend.isFlagged(row);
         const isPinned = backend.isPinned(row);
         const info = {
-            view: { label: "View details", icon: _jsx(InlineIcon, { icon: iconEye }) },
+            view: { label: `View ${(latest.current.details || undefined)?.label ?? "details"}`, icon: _jsx(InlineIcon, { icon: iconEye }) },
             edit: { label: "Edit", icon: _jsx(InlineIcon, { icon: iconPencil }), inline: true },
             flag: flagged ? { label: "Unflag", icon: _jsx(InlineIcon, { icon: iconFlagOff }) } : { label: "Flag", icon: _jsx(InlineIcon, { icon: iconFlag }) },
             pin: isPinned ? { label: "Unpin", icon: _jsx(InlineIcon, { icon: iconPinnedOff }) } : { label: "Pin", icon: _jsx(InlineIcon, { icon: iconPin }) },
-            archive: { label: "Archive", icon: _jsx(InlineIcon, { icon: iconArchive }) },
-            restore: { label: "Restore", description: "Back to the active list", icon: _jsx(InlineIcon, { icon: iconArchiveOff }), inline: true },
             trash: { label: "Move to trash", icon: _jsx(InlineIcon, { icon: iconTrash }), tone: "danger" },
             recover: { label: "Recover", description: "Back to the active list", icon: _jsx(InlineIcon, { icon: iconRestore }), inline: true },
             delete: { label: "Delete permanently", icon: _jsx(InlineIcon, { icon: iconTrashX }), tone: "danger" },
@@ -504,8 +649,6 @@ export function Crud(props) {
             const info = {
                 flag: flagged === rows.length ? { label: "Unflag", icon: _jsx(InlineIcon, { icon: iconFlagOff }) } : { label: flagged ? "Flag / unflag" : "Flag", icon: _jsx(InlineIcon, { icon: iconFlag }) },
                 pin: unpinned === 0 ? { label: "Unpin", icon: _jsx(InlineIcon, { icon: iconPinnedOff }) } : { label: "Pin", icon: _jsx(InlineIcon, { icon: iconPin }) },
-                archive: { label: "Archive", icon: _jsx(InlineIcon, { icon: iconArchive }) },
-                restore: { label: "Restore", icon: _jsx(InlineIcon, { icon: iconArchiveOff }) },
                 trash: { label: "Move to trash", icon: _jsx(InlineIcon, { icon: iconTrash }), tone: "danger" },
                 recover: { label: "Recover", icon: _jsx(InlineIcon, { icon: iconRestore }) },
                 delete: { label: "Delete permanently", icon: _jsx(InlineIcon, { icon: iconTrashX }), tone: "danger" },
@@ -534,6 +677,7 @@ export function Crud(props) {
             reloadPins();
             return table.reload({ quiet: true });
         },
+        apply: (rows, options) => run.current.applyRows(rows, options?.gone ?? false),
         create: values => void run.current.openForm("create", null, values),
         edit: row => void run.current.openForm("edit", row),
         view: row => run.current.openDetails(row),
@@ -549,8 +693,16 @@ export function Crud(props) {
     const modeOptions = modes.map(value => ({ value, label: MODE_INFO[value].label, icon: _jsx(InlineIcon, { icon: MODE_INFO[value].icon }) }));
     const addButton = allowed.create ? (_jsxs(Button, { variant: "primary", size: "sm", icon: _jsx(InlineIcon, { icon: iconPlus }), onClick: () => void run.current.openForm("create", null), children: ["Add ", subject] })) : null;
     const selectable = props.massActions !== false && Boolean(mode) && (crudMassActions(mode, action => massAllowed[action], massTrashless).length > 0 || Boolean(props.massActions));
-    return (_jsx("div", { id: id, className: cx("nx-crud", className), style: style, "data-mode": mode, children: _jsx(DataTable, { table: table, columns: columns, load: load, loadKey: mode ?? "waiting", paging: paging, rowKey: rowKey, rowLabel: labelOf, "aria-label": tableLabel, "aria-labelledby": props["aria-labelledby"], toolbar: modes.length > 1 && mode ? (_jsx(TabButtons, { size: "sm", labels: "selected", options: modeOptions, value: mode, onChange: setChosenMode, "aria-label": `${capitalize(plural)}: lists` })) : undefined, actions: _jsxs(_Fragment, { children: [props.toolbar, addButton] }), selectable: selectable, massActions: massActionsFor, rowActions: rowActions, pinnedRows: mode === "normal" && pinsOn ? (pinned ?? undefined) : undefined, pinnedLoading: pinsLoading, pinnedLabel: `Pinned ${plural}`, pinnedMax: maxPins, onRowOpen: onRowOpen, onReload: () => {
+    return (_jsx("div", { id: id, className: cx("nx-crud", className), style: style, "data-mode": mode, children: _jsx(DataTable, { table: table, columns: columns, load: load, loadKey: mode ?? "waiting", paging: paging, rowKey: rowKey, rowLabel: labelOf, "aria-label": tableLabel, "aria-labelledby": props["aria-labelledby"], toolbar: modes.length > 1 && mode ? (_jsx(TabButtons, { size: "sm", labels: "selected", options: modeOptions, value: mode, onChange: setChosenMode, "aria-label": `${capitalize(plural)}: lists` })) : undefined, actions: _jsxs(_Fragment, { children: [props.toolbar, addButton] }), selectable: selectable, massActions: massActionsFor, rowActions: rowActions, pinnedRows: mode === "normal" && pinsOn ? (pinned ?? undefined) : undefined, pinnedLoading: pinsLoading, pinnedLabel: `Pinned ${plural}`, pinnedMax: maxPins, onRowOpen: onRowOpen, openOnClick: tableOptions?.openOnClick, onReload: () => {
                 cache.clear();
                 reloadPins();
-            }, emptyMessage: tableOptions?.emptyMessage ?? (mode ? MODE_INFO[mode].empty(plural) : undefined), emptyAction: mode === "normal" ? addButton : undefined, searchPlaceholder: tableOptions?.searchPlaceholder ?? `Search ${plural}…`, stateKey: tableOptions?.stateKey ?? `crud:${name}`, pageSize: tableOptions?.pageSize, pageSizes: tableOptions?.pageSizes, defaultSort: tableOptions?.defaultSort, numbered: tableOptions?.numbered, maxHeight: tableOptions?.maxHeight, size: tableOptions?.size, maxSelection: tableOptions?.maxSelection, columnsMenu: tableOptions?.columnsMenu, searchDelay: tableOptions?.searchDelay, reorderable: tableOptions?.reorderable, resizable: tableOptions?.resizable, pinnable: tableOptions?.pinnable, moreActions: tableOptions?.moreActions, exportable: tableOptions?.exportable, printable: tableOptions?.printable, exportName: tableOptions?.exportName, onImport: tableOptions?.onImport }) }));
+            }, emptyMessage: tableOptions?.emptyMessage ?? (mode ? MODE_INFO[mode].empty(plural) : undefined), emptyAction: mode === "normal" ? addButton : undefined, searchPlaceholder: tableOptions?.searchPlaceholder ?? `Search ${plural}…`, stateKey: tableOptions?.stateKey ?? `crud:${name}`, pageSize: tableOptions?.pageSize, pageSizes: tableOptions?.pageSizes, defaultSort: tableOptions?.defaultSort, numbered: tableOptions?.numbered, maxHeight: tableOptions?.maxHeight, fill: tableOptions?.fill, size: tableOptions?.size, maxSelection: tableOptions?.maxSelection, columnsMenu: tableOptions?.columnsMenu, searchDelay: tableOptions?.searchDelay, reorderable: tableOptions?.reorderable, resizable: tableOptions?.resizable, pinnable: tableOptions?.pinnable, moreActions: tableOptions?.moreActions, exportable: tableOptions?.exportable, printable: tableOptions?.printable, exportName: tableOptions?.exportName, onImport: tableOptions?.onImport, excel: tableOptions?.excel && {
+                ...tableOptions.excel,
+                // A spreadsheet wrote records straight into the database: every list this CRUD kept is out of date.
+                onImported: () => {
+                    cache.clear();
+                    reloadPins();
+                    tableOptions.excel?.onImported?.();
+                },
+            } }) }));
 }

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

@@ -0,0 +1,42 @@
+import { type ReactNode } 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;
+    className?: string;
+}
+/**
+ * The three steps of an import in one panel: the template, the file, and the review.
+ *
+ * @example
+ * <ExcelImport endpoints={CITY_SHEET} subject="city" onImported={() => table.reload()} />
+ */
+export declare function ExcelImport({ endpoints, subject: given, params, onImported, onClose, templateDownload, maxHeight, 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"> {
+    /** The window's title. Default: "Import <subjects> from a spreadsheet". */
+    title?: ReactNode;
+    /** One popup per key. Default: the import endpoint's path, so one model opens one. */
+    popupKey?: string;
+}
+/**
+ * Opens the import panel as a window. This is the one line a data table's Import entry needs.
+ *
+ * @example onImport={() => openExcelImport({ endpoints: CITY_SHEET, subject: "city", onImported: reload })}
+ */
+export declare function openExcelImport({ title, popupKey, ...props }: OpenExcelImportOptions): PopupHandle;