nexus-shared 1.1.20 → 2.0.0

package/dist/Components/Forms/Crud.js

@@ -0,0 +1,556 @@
+"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 { 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 { cx } from "../../Helpers/ClassHelpers.js";
+import { FormStore } from "../../Helpers/FormStore.js";
+import { pluralize } from "../../Helpers/MessageBuilder.js";
+import { getPermissions, permissionsVersion, subscribePermissions } from "../../Helpers/Permissions.js";
+import { columnValue, formatCellText, readPath } from "../../Helpers/TableHelpers.js";
+import { api as browserApi } from "../../Services/BrowserApi.js";
+import { Button } from "../Documents/Button.js";
+import { TabButtons } from "../Documents/TabButtons.js";
+import { openPopup } from "../Layouts/PopupHost.js";
+import { toast } from "../Layouts/Toaster.js";
+import { DataTable, useTable } from "../Viewers/DataTable.js";
+import { ApiForm } from "./ApiForm.js";
+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
+ * 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 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 the active lists, so it is no longer among the pinned records either. */
+const LEFT_ACTIVE = new Set(["archive", "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);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isInputList(inputs) {
+    return Array.isArray(inputs);
+}
+/** The subject the endpoints were given: `apiController(module, "Guest", "guest")` → "guest". */
+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;
+}
+/**
+ * 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.
+ *
+ * @example
+ * const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "guest");
+ *
+ * <Crud<Guest>
+ *   api={GUESTS}
+ *   columns={[{ key: "fullName", label: "Name" }, { key: "email", label: "Email" }, { key: "visits", label: "Visits", format: "number" }]}
+ *   inputs={GUEST_INPUTS}
+ *   paging="server"
+ * />
+ */
+export function Crud(props) {
+    const { api, columns, rowKey = "id", paging = "client", table: tableOptions, id, className, style, ref } = props;
+    const latest = useRef(props);
+    latest.current = props;
+    const subject = props.subject ?? endpointSubject(api) ?? "record";
+    const plural = props.subjectPlural ?? pluralize(subject);
+    const name = props.name ?? subject;
+    const backend = getCrudBackend();
+    // Permissions: every list and action asks, again whenever the user's rights change.
+    const permissionsStamp = useSyncExternalStore(subscribePermissions, permissionsVersion, permissionsVersion);
+    const permissions = getPermissions();
+    const ready = permissions.ready;
+    const wantedModes = props.modes ?? CRUD_MODES;
+    const wantedActions = props.actions ?? ALL_ACTIONS;
+    const can = useCallback((endpoint) => permissions.can(endpoint), [permissions, permissionsStamp]); // eslint-disable-line react-hooks/exhaustive-deps
+    const modes = useMemo(() => (ready ? availableModes(api, paging, wantedModes, can) : []), [ready, api, paging, wantedModes, can]);
+    const allowed = useMemo(() => {
+        const map = {};
+        for (const action of ALL_ACTIONS)
+            map[action] = ready && actionAllowed(action, api, wantedActions, can);
+        return map;
+    }, [ready, api, wantedActions, can]);
+    const massAllowed = useMemo(() => {
+        const map = {};
+        for (const action of ["flag", "pin", "archive", "restore", "trash", "recover", "delete", "trashFromDelete", "description"])
+            map[action] = ready && massActionAllowed(action, api, wantedActions, can);
+        return map;
+    }, [ready, api, wantedActions, can]);
+    // A controller without a trash deletes from its lists; a trash the user may not use never becomes Delete.
+    const trashless = !api.trash || !wantedActions.includes("trash");
+    const massTrashless = !api.mass?.trash || !wantedActions.includes("trash");
+    const [chosenMode, setChosenMode] = useState(props.defaultMode ?? null);
+    const mode = chosenMode && modes.includes(chosenMode) ? chosenMode : modes[0];
+    const modeRef = useRef(mode);
+    modeRef.current = mode;
+    const table = useTable();
+    const lifetime = props.cache === false ? 0 : (props.cache?.lifetime ?? CRUD_CACHE_LIFETIME);
+    const [cache] = useState(() => new CrudCache(lifetime));
+    // The cache lives while the page is open, as the old CRUD's did.
+    useEffect(() => () => cache.clear(), [cache]);
+    const rawKey = (row) => readPath(row, rowKey);
+    const labelOf = useCallback((row) => {
+        const custom = latest.current.rowLabel;
+        if (custom)
+            return custom(row);
+        const first = latest.current.columns[0];
+        const text = first ? formatCellText(first, columnValue(first, row)) : "";
+        return text || `${capitalize(subject)} ${table.keyOf(row)}`;
+    }, [subject, table]);
+    /* The records the user pinned: their own endpoint, a section above the list, and a limit every CRUD shares */
+    const maxPins = getCrudSettings().maxPins;
+    const pinsEndpoint = api.pins;
+    const pinsOn = ready && Boolean(pinsEndpoint) && wantedActions.includes("pin") && can(pinsEndpoint);
+    const [pinned, setPinned] = useState(null);
+    const [pinsLoading, setPinsLoading] = useState(false);
+    const [pinsStamp, setPinsStamp] = useState(0);
+    useEffect(() => {
+        if (!pinsOn || !pinsEndpoint) {
+            setPinned(null);
+            return;
+        }
+        const controller = new AbortController();
+        setPinsLoading(true);
+        const done = (rows) => {
+            if (controller.signal.aborted)
+                return;
+            if (rows)
+                setPinned(rows);
+            setPinsLoading(false);
+        };
+        void browserApi.send(pinsEndpoint, { signal: controller.signal, toast: false, subject: plural }).then(answer => {
+            if (answer.aborted)
+                return;
+            // The rows come from the pinned list, so they are pinned whatever the backend sends on each one.
+            done(answer.ok ? backend.readList(answer.result).map(row => backend.withPin(row, true)) : []);
+        }, 
+        // The section is a shortcut to records the list holds as well, so a failed load leaves it out quietly.
+        () => done([]));
+        return () => controller.abort();
+    }, [pinsOn, pinsEndpoint, backend, plural, pinsStamp]);
+    const reloadPins = useCallback(() => setPinsStamp(stamp => stamp + 1), []);
+    /** The section after a pin or an unpin: records just pinned go on top, unpinned ones go. */
+    function applyPins(rows) {
+        setPinned(current => {
+            if (!current)
+                return current;
+            const changed = new Map(rows.map(row => [table.keyOf(row), row]));
+            const kept = current.map(row => changed.get(table.keyOf(row)) ?? row).filter(row => backend.isPinned(row));
+            const keys = new Set(kept.map(row => table.keyOf(row)));
+            return [...rows.filter(row => backend.isPinned(row) && !keys.has(table.keyOf(row))), ...kept];
+        });
+    }
+    /** A pinned record's copy in the section, after a change that was not a pin: a flag, a description, a save. */
+    function patchPins(rows) {
+        setPinned(current => {
+            if (!current)
+                return current;
+            const changed = new Map(rows.map(row => [table.keyOf(row), row]));
+            if (!current.some(row => changed.has(table.keyOf(row))))
+                return current;
+            // The record is still pinned: only its other values changed, and a list may not send the pin at all.
+            return current.map(row => {
+                const next = changed.get(table.keyOf(row));
+                return next ? backend.withPin(next, true) : row;
+            });
+        });
+    }
+    /** Records that left the active lists are no longer among the pinned ones. */
+    function dropPins(keys) {
+        if (!keys.length)
+            return;
+        const gone = new Set(keys);
+        setPinned(current => (current && current.some(row => gone.has(table.keyOf(row))) ? current.filter(row => !gone.has(table.keyOf(row))) : current));
+    }
+    /** Nothing can be pinned while the limit is reached: lowering the limit never unpins, it only waits to be met. */
+    const pinsFull = () => `You can pin up to ${maxPins} ${plural}. Unpin one to pin another.`;
+    /* Loading */
+    const load = useCallback((query, signal) => {
+        if (!mode)
+            return new Promise(() => undefined);
+        const endpoint = crudListEndpoint(api, mode, paging);
+        const sortColumn = query.sort ? latest.current.columns.find(column => column.key === query.sort.key) : undefined;
+        const key = paging === "server" ? `${mode}|${query.search}|${query.sort ? `${query.sort.key}:${query.sort.direction}` : ""}|${query.page}|${query.pageSize}` : mode;
+        const kept = cache.get(key);
+        if (kept)
+            return kept;
+        const options = { signal, toast: false, subject: plural };
+        if (paging === "server")
+            options.body = backend.pageRequest(query, sortColumn?.sortKey ?? sortColumn?.key);
+        return browserApi.send(endpoint, options).then(answer => {
+            if (answer.aborted)
+                throw abortError();
+            if (!answer.ok)
+                throw new Error(answer.message ?? `Could not load the ${plural}.`);
+            const result = paging === "server" ? backend.readPage(answer.result) : backend.readList(answer.result);
+            cache.set(key, result);
+            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) {
+        const shown = modeRef.current;
+        if (paging === "client" && shown) {
+            cache.drop(key => key !== shown);
+            cache.update(shown, table.getRows());
+        }
+        else
+            cache.clear();
+        if (shown)
+            latest.current.onChange?.({ action, rows, mode: shown });
+    }
+    /* Changing rows after an answer */
+    function applyChange(action, rows, result, markOn, values) {
+        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;
+        if (action === "flag") {
+            const changes = backend.answeredChanges(result, rowKey);
+            const leaving = [];
+            const updated = [];
+            for (const row of done) {
+                const key = table.keyOf(row);
+                const current = table.getRow(key) ?? row;
+                const on = markOn ?? !backend.isFlagged(current);
+                let next = backend.withFlag(current, on);
+                const change = changes.get(key);
+                if (change)
+                    next = { ...next, ...change };
+                if (leavesList(action, shown, backend.isFlagged(next)))
+                    leaving.push(key);
+                else
+                    table.upsert(next, { flash: false });
+                updated.push(next);
+            }
+            table.remove(leaving);
+            patchPins(updated);
+            afterChange(action, updated);
+            return;
+        }
+        if (action === "pin") {
+            const changes = backend.answeredChanges(result, rowKey);
+            const updated = [];
+            for (const row of done) {
+                const key = table.keyOf(row);
+                const current = table.getRow(key) ?? row;
+                const on = markOn ?? !backend.isPinned(current);
+                let next = backend.withPin(current, on);
+                const change = changes.get(key);
+                if (change)
+                    next = { ...next, ...change };
+                // 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);
+            }
+            applyPins(updated);
+            afterChange(action, updated);
+            return;
+        }
+        if (action === "description") {
+            const updated = done.map(row => ({ ...(table.getRow(table.keyOf(row)) ?? row), ...values }));
+            for (const row of updated)
+                table.upsert(row);
+            patchPins(updated);
+            afterChange(action, updated);
+            return;
+        }
+        const keys = done.map(row => table.keyOf(row));
+        if (leavesList(action, shown))
+            table.remove(keys);
+        if (LEFT_ACTIVE.has(action))
+            dropPins(keys);
+        afterChange(action, done);
+    }
+    /* Row actions */
+    async function runRowAction(action, row) {
+        const endpoint = crudRowEndpoint(api, action);
+        if (!endpoint)
+            return;
+        const key = rawKey(row);
+        const markOn = action === "flag" ? !backend.isFlagged(row) : action === "pin" ? !backend.isPinned(row) : undefined;
+        if (action === "pin" && markOn && pinRoom(pinned?.length) < 1) {
+            toast.warning(pinsFull());
+            return;
+        }
+        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);
+    }
+    async function runMassAction(action, rows) {
+        if (action === "description") {
+            openDescription(rows);
+            return;
+        }
+        const endpoint = api.mass?.[action];
+        if (!endpoint)
+            return;
+        let markOn;
+        let sent = rows;
+        let over = 0;
+        if (action === "flag") {
+            const on = rows.filter(row => backend.isFlagged(row)).length;
+            markOn = on === 0 ? true : on === rows.length ? false : undefined;
+        }
+        if (action === "pin") {
+            // Every selected record pinned means Unpin; otherwise the ones that are not pinned yet are pinned, as many as
+            // the limit leaves room for, in the order the user picked them. The rest stay as they are.
+            const adding = rows.filter(row => !backend.isPinned(row));
+            markOn = adding.length > 0;
+            if (markOn) {
+                const room = pinRoom(pinned?.length);
+                if (room < 1) {
+                    toast.warning(pinsFull());
+                    return;
+                }
+                sent = adding.slice(0, room);
+                over = adding.length - sent.length;
+            }
+        }
+        const messageAction = action === "flag" && markOn === undefined ? TOGGLED_FLAG : crudMessageAction(action, markOn);
+        const options = { body: backend.massRequest(action, sent.map(rawKey)), subject, plural: props.subjectPlural, count: sent.length, action: messageAction };
+        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);
+        table.clearSelection();
+        if (over > 0)
+            toast.warning(`${sent.length} of ${sent.length + over} ${plural} pinned: you can pin up to ${maxPins}.`);
+    }
+    /* Popups */
+    const addPopup = useRef(null);
+    async function inputsFor(action, row) {
+        const given = latest.current.inputs;
+        if (typeof given === "function")
+            return given(action, row);
+        if (isInputList(given))
+            return given;
+        return (action === "create" ? (given.create ?? given.edit) : (given.edit ?? given.create)) ?? [];
+    }
+    async function openForm(action, row, values) {
+        const endpoint = action === "create" ? api.create : api.update;
+        if (!endpoint)
+            return;
+        // An Add form with changes comes back as it was; an untouched one is replaced by a fresh form.
+        if (action === "create" && addPopup.current?.form.isChanged()) {
+            addPopup.current.handle.restore();
+            return;
+        }
+        const inputs = await inputsFor(action, row);
+        const options = latest.current.form ?? {};
+        const form = new FormStore();
+        const key = row ? table.keyOf(row) : "";
+        const label = row ? labelOf(row) : undefined;
+        const newValues = typeof options.newValues === "function" ? options.newValues() : options.newValues;
+        const loader = options.load;
+        const loadValue = action === "edit" && row && loader && loader !== "row"
+            ? loader === "details"
+                ? api.details
+                    ? (signal) => browserApi.get(api.details, { params: { id: rawKey(row), [rowKey]: rawKey(row) }, signal, toast: false }).then(answer => ({ ...row, ...unwrapApiResult(answer) }))
+                    : undefined
+                : (signal) => loader(row, signal).then(full => ({ ...row, ...full }))
+            : undefined;
+        const handle = openPopup({
+            key: action === "create" ? `${name}-new` : `${name}-edit-${key}`,
+            reopen: action === "create" ? "replace" : "restore",
+            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,
+            beforeClose: async () => {
+                const discard = await confirmDiscard(form);
+                if (discard)
+                    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();
+                } })),
+            footer: popup => _jsx(FormButtons, { form: form, submitLabel: action === "create" ? `Add ${subject}` : "Save", onCancel: () => popup.close() }),
+        });
+        if (action === "create") {
+            const entry = { handle, form };
+            addPopup.current = entry;
+            void handle.closed.then(() => {
+                if (addPopup.current === entry)
+                    addPopup.current = null;
+            });
+        }
+    }
+    function onSaved(action, row, result, values) {
+        const record = { ...row, ...values, ...(isRecord(result) ? result : {}) };
+        const shown = modeRef.current;
+        if (action === "edit") {
+            table.upsert(record);
+            patchPins([record]);
+            afterChange("edit", [record]);
+            return;
+        }
+        // A new record belongs to the list of every record; without its key from the server, the list loads again.
+        if (shown === "normal") {
+            if (table.keyOf(record))
+                table.upsert(record);
+            else
+                void table.reload({ quiet: true });
+        }
+        afterChange("create", [record]);
+    }
+    function openDetails(row) {
+        const details = latest.current.details;
+        if (details === false)
+            return;
+        const key = table.keyOf(row);
+        const canEdit = allowed.edit && modeRef.current !== undefined && CRUD_ROW_ACTIONS[modeRef.current].includes("edit");
+        const endpoint = api.details;
+        openPopup({
+            key: `${name}-view-${key}`,
+            reopen: "restore",
+            title: `${capitalize(subject)} 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 })),
+            footer: popup => (_jsxs(_Fragment, { children: [canEdit && (_jsx(Button, { icon: _jsx(InlineIcon, { icon: iconPencil }), onClick: () => {
+                            popup.close();
+                            void openForm("edit", table.getRow(key) ?? row);
+                        }, children: "Edit" })), _jsx(Button, { variant: "primary", onClick: () => popup.close(), children: "Close" })] })),
+        });
+    }
+    function openDescription(rows) {
+        const endpoint = api.mass?.description;
+        if (!endpoint)
+            return;
+        const form = new FormStore();
+        const count = rows.length;
+        openPopup({
+            key: `${name}-description`,
+            title: "Description",
+            description: `${count} ${count === 1 ? subject : plural}`,
+            icon: _jsx(InlineIcon, { icon: iconNotes }),
+            size: "sm",
+            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);
+                    table.clearSelection();
+                    popup.close();
+                } })),
+            footer: popup => _jsx(FormButtons, { form: form, submitLabel: "Save", onCancel: () => popup.close() }),
+        });
+    }
+    // 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 };
+    /* The table's callbacks */
+    const rowActions = useCallback((row) => {
+        if (!mode)
+            return [];
+        const list = [];
+        const primary = mode === "normal" || mode === "flag";
+        const flagged = backend.isFlagged(row);
+        const isPinned = backend.isPinned(row);
+        const info = {
+            view: { label: "View 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" },
+            trashFromDelete: { label: "Move back to trash", icon: _jsx(InlineIcon, { icon: iconRestore }), inline: true },
+        };
+        for (const action of crudRowActions(mode, candidate => allowed[candidate], trashless)) {
+            if (action === "view" && latest.current.details === false)
+                continue;
+            const onSelect = action === "view" ? () => run.current.openDetails(row) : action === "edit" ? () => void run.current.openForm("edit", row) : () => run.current.runRowAction(action, row);
+            const entry = info[action];
+            list.push({ ...entry, id: action, inline: entry.inline && (primary ? action === "edit" : true), onSelect });
+        }
+        const extra = latest.current.rowActions?.(row, mode) ?? [];
+        return [...list, ...extra];
+    }, [mode, allowed, backend, trashless]);
+    const massActionsFor = useCallback((rows) => {
+        if (!mode)
+            return [];
+        const list = [];
+        const flagged = rows.filter(row => backend.isFlagged(row)).length;
+        const unpinned = rows.filter(row => !backend.isPinned(row)).length;
+        for (const action of crudMassActions(mode, candidate => massAllowed[candidate], massTrashless)) {
+            const onSelect = (selected) => run.current.runMassAction(action, selected);
+            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" },
+                trashFromDelete: { label: "Move back to trash", icon: _jsx(InlineIcon, { icon: iconRestore }) },
+                description: { label: "Description", icon: _jsx(InlineIcon, { icon: iconNotes }) },
+            };
+            list.push({ ...info[action], id: action, onSelect });
+        }
+        const extra = latest.current.massActions ? latest.current.massActions(rows, mode) : [];
+        return [...list, ...extra];
+    }, [mode, massAllowed, backend, massTrashless]);
+    const onRowOpen = useCallback((row) => {
+        if (allowed.view && latest.current.details !== false)
+            run.current.openDetails(row);
+        else if (allowed.edit && mode && CRUD_ROW_ACTIONS[mode].includes("edit"))
+            void run.current.openForm("edit", row);
+    }, [allowed, mode]);
+    useImperativeHandle(ref, () => ({
+        table,
+        get mode() {
+            return modeRef.current ?? "normal";
+        },
+        setMode: next => setChosenMode(next),
+        reload: () => {
+            cache.clear();
+            reloadPins();
+            return table.reload({ quiet: true });
+        },
+        create: values => void run.current.openForm("create", null, values),
+        edit: row => void run.current.openForm("edit", row),
+        view: row => run.current.openDetails(row),
+    }), [table, cache, reloadPins]);
+    const tableLabel = props["aria-label"] ?? (props["aria-labelledby"] ? undefined : capitalize(plural));
+    const configured = CRUD_MODES.some(value => wantedModes.includes(value) && crudListEndpoint(api, value, paging));
+    if (!configured) {
+        return (_jsx("div", { id: id, className: cx("nx-crud", "nx-crud--denied", className), style: style, role: "alert", children: _jsxs("p", { className: "nx-crud__denied-title", children: ["Nothing to show: no ", paging === "server" ? "`pages`" : "`lists`", " endpoint for the ", plural, "."] }) }));
+    }
+    if (ready && !mode) {
+        return (_jsxs("div", { id: id, className: cx("nx-crud", "nx-crud--denied", className), style: style, role: "status", children: [_jsx(InlineIcon, { icon: iconLock, className: "nx-crud__denied-icon" }), _jsxs("p", { className: "nx-crud__denied-title", children: ["You do not have permission to see ", plural, "."] }), _jsx("p", { className: "nx-crud__denied-detail", children: "Ask an administrator for access." })] }));
+    }
+    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: () => {
+                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 }) }));
+}

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

@@ -0,0 +1,15 @@
+import { type ReactNode } from "react";
+import type { FormValues } from "../../Interfaces/FormInterfaces.ts";
+import type { TableColumn } from "../../Interfaces/TableInterfaces.ts";
+export interface CrudDetailsProps<TRow extends FormValues = FormValues> {
+    /** The record as the list has it, shown at once. */
+    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. */
+    load?: (signal: AbortSignal) => Promise<Partial<TRow> | null | undefined>;
+    /** Draws the details instead of the list of fields. */
+    render?: (row: TRow) => ReactNode;
+}
+/** 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;

package/dist/Components/Forms/CrudParts.js

@@ -0,0 +1,36 @@
+"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 { isAbortError } from "../../Helpers/ApiResponses.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { TableCellValue } from "../Viewers/DataTableParts.js";
+/** 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 preferences = useDatePreferences();
+    const timeZone = useBrowserTimeZone();
+    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined }), [preferences, timeZone]);
+    useEffect(() => {
+        if (!load)
+            return;
+        const controller = new AbortController();
+        load(controller.signal).then(full => {
+            if (controller.signal.aborted)
+                return;
+            if (full)
+                setRecord(current => ({ ...current, ...full }));
+            setState("done");
+        }, error => {
+            if (controller.signal.aborted || isAbortError(error))
+                return;
+            setState("failed");
+        });
+        return () => controller.abort();
+        // 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))) }))] }));
+}