nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Forms/CrudTree.js

@@ -0,0 +1,363 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { unwrapApiResult } from "../../Helpers/ApiResponses.js";
+import { getCrudBackend } from "../../Helpers/CrudBackend.js";
+import { actionAllowed, crudJoinedNames, crudJoinsMissing, crudRowActions, crudSavedCount, crudSavedRecord, crudTreeChanges } from "../../Helpers/CrudHelpers.js";
+import { pluralize } from "../../Helpers/MessageBuilder.js";
+import { getPermissions, permissionsVersion, subscribePermissions } from "../../Helpers/Permissions.js";
+import { columnValue, formatCellText, namingColumn, readPath } from "../../Helpers/TableHelpers.js";
+import { tableJoins } from "../../Helpers/TableJoins.js";
+import { TREE_DEFAULT_KEYS, writeTreeChanges } from "../../Helpers/TreeStore.js";
+import { api as browserApi } from "../../Services/BrowserApi.js";
+import { expireLookups, joinSource } from "../../Services/JoinSources.js";
+import { Button } from "../Documents/Button.js";
+import { TreeView } from "../Inputs/TreeView.js";
+import { CRUD_ACTION_WORDS, crudActionEntry, crudSubject, openCrudForm, sendCrudRowAction } from "./CrudActions.js";
+import { openAuditHistory } from "./CrudHistory.js";
+import { CrudDetails } from "./CrudParts.js";
+/*
+ * CrudTree: a controller's records as a tree whose levels load from the server when they are opened (TreeView
+ * `loadChildren`), changed where they are shown - Add New under an item, Edit, the trash and back, the history - through
+ * the very form and calls the data table's Crud uses. Every change is written into the tree and into the pages it keeps
+ * (`writeTreeChanges`), and nothing is read again for it: a record added goes under its parent, one edited is written in
+ * place or moves, one sent to the trash leaves with its parent counting one fewer.
+ */
+/** The built-in actions a tree of records offers, by default. Flags, pins and favourites stay on the table. */
+const TREE_ACTIONS = ["create", "edit", "history", "trash", "recover", "delete", "trashFromDelete"];
+/** The panel's buttons, in their order: what a record's list offers, the history last. */
+const PANEL_ORDER = ["edit", "recover", "trashFromDelete", "trash", "delete", "history"];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const capitalize = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
+/**
+ * A controller's records as a tree, with Add New, Edit, Move to trash, Recover, Delete and History where they are shown:
+ * an icon button on each row for Add New under it, Edit and Move to trash (Insert, F2 and Delete on a focused row, all
+ * three in its context menu), Add New in the tree's toolbar, and every action of the picked record on the panel beside
+ * the tree. The forms and the calls are the data table's; a change is written into the tree and its kept pages, so no
+ * level is read again for it.
+ *
+ * A click or Enter on a row selects it - marked in the tree, and staying so while focus, the keys and the chevrons move
+ * on - and a record's row shows that record in the panel; a row that is not a record (a country above its regions)
+ * empties the panel and opens.
+ *
+ * With `place.placeKeys` the tree fixes where a record sits: every Add goes inside a row - the toolbar's inside the
+ * selected row, the one the panel shows, and saying why it cannot until there is one - and the Add and Edit forms show
+ * those fields read-only, saying why.
+ *
+ * @example
+ * <AdminSplit>
+ *   <CrudTree api={REGIONS} inputs={REGION_INPUTS} columns={REGION_COLUMNS} place={REGION_TREE} form={REGION_FORM}
+ *     tree={{ loadChildren, fill: true, "aria-label": "Regions" }}
+ *     details={({ row, body, actions }) => <AdminPanel title={row?.name ?? "Details"} action={actions}>{body}</AdminPanel>} />
+ * </AdminSplit>
+ */
+export function CrudTree(props) {
+    const { api, place, columns, rowKey = "id", tree: treeProps, ref } = props;
+    const latest = useRef(props);
+    latest.current = props;
+    const subject = props.subject ?? crudSubject(api) ?? "record";
+    const name = props.name ?? subject;
+    const backend = props.backend ?? getCrudBackend();
+    const valueKey = place.rules.valueKey ?? TREE_DEFAULT_KEYS.value;
+    const labelKey = treeProps.labelKey ?? TREE_DEFAULT_KEYS.label;
+    // The fields that say where a record sits: fixed in every form the tree opens, when the placement names them.
+    const placeKeys = place.placeKeys;
+    // Permissions: each action asks, again whenever the user's rights change.
+    const permissionsStamp = useSyncExternalStore(subscribePermissions, permissionsVersion, permissionsVersion);
+    const permissions = getPermissions();
+    const wanted = props.actions ?? TREE_ACTIONS;
+    const allowed = useMemo(() => {
+        const map = {};
+        for (const action of TREE_ACTIONS)
+            map[action] = permissions.ready && actionAllowed(action, api, wanted, endpoint => permissions.can(endpoint));
+        return map;
+    }, [permissions, permissionsStamp, api, wanted]); // eslint-disable-line react-hooks/exhaustive-deps
+    // A controller without a trash deletes from the tree; a trash the user may not use never becomes Delete.
+    const trashless = !api.trash || !wanted.includes("trash");
+    const treeRef = useRef(null);
+    const actionsRef = useRef(null);
+    // The record the panel shows, and the selected row - its row, or one that is no record (a country): where the
+    // toolbar's Add New adds, with `placeKeys`. Focus, the keys and the chevrons move neither.
+    const [picked, setPicked] = useState(null);
+    const [selected, setSelected] = useState(null);
+    // Draws the panel's fields again for the same record once it changed.
+    const [stamp, setStamp] = useState(0);
+    const [busy, setBusy] = useState(false);
+    // An action pressed on the panel took its own button away: focus goes to the panel's first button once it is drawn.
+    const refocusRef = useRef(false);
+    const keyOf = (row) => String(readPath(row, rowKey) ?? "");
+    const valueOf = (row) => place.itemOf(row)[valueKey];
+    const itemLabel = (item) => String(item[labelKey] ?? "");
+    function labelOf(row) {
+        const custom = latest.current.rowLabel;
+        if (custom)
+            return custom(row);
+        const first = namingColumn(latest.current.columns);
+        const text = first ? formatCellText(first, columnValue(first, row), {}, row) : "";
+        return text || `${capitalize(subject)} ${keyOf(row)}`;
+    }
+    /** The list a record is in now: the active one, unless its status puts it in the trash or among the deleted. */
+    const modeOf = (row) => (backend.listMembership(row, "deleted") ? "deleted" : backend.listMembership(row, "trash") ? "trash" : "normal");
+    /** Whether the tree shows a record: an active one, or one whose status does not say. */
+    const inTree = (row) => backend.listMembership(row, "normal") !== false;
+    /** Shows a record in the panel and selects its row (or the row of an item that is no record, with an empty panel). */
+    function show(row, item = row ? place.itemOf(row) : null) {
+        setPicked(row);
+        setSelected(item);
+        setStamp(count => count + 1);
+    }
+    /** Writes changes into the tree and its kept pages, marks the lookups of these records old, and tells the page. */
+    function changed(change, treeChanges = crudTreeChanges(change, place, backend)) {
+        writeTreeChanges(place.cacheKey, treeChanges, place.rules);
+        expireLookups(api);
+        latest.current.onChange?.(change);
+    }
+    /**
+     * Shows a record where it went, its parents opened and its row scrolled into view - where the tree placed it. Under a
+     * parent never opened it was only counted, and opening that parent would read its page: it stays closed, with its new
+     * count, and the panel shows the record.
+     */
+    function revealInTree(row) {
+        const tree = treeRef.current;
+        const value = valueOf(row);
+        if (tree && inTree(row) && tree.getItem(value) !== undefined)
+            tree.reveal(value, false);
+    }
+    /** The record of the item a form names as the parent: kept for the pickers that look these records up, so none asks. */
+    function rememberParent(parent) {
+        if (!api.findListing || parent === null)
+            return;
+        const item = treeRef.current?.getItem(parent);
+        const record = item ? place.recordOf(item) : null;
+        if (record)
+            tableJoins.remember(joinSource(api.findListing, backend), [record]);
+    }
+    /**
+     * The row the toolbar's Add New adds inside, with `placeKeys`: the selected one, as the tree holds it now - unless it is
+     * a record out of the tree (moved to the trash, deleted), which nothing can be added inside. `null` while there is none.
+     */
+    function addTarget() {
+        if (!selected)
+            return null;
+        const value = selected[valueKey];
+        const item = treeRef.current?.getItem(value) ?? selected;
+        const record = place.recordOf(item);
+        return record && !inTree(record) ? null : item;
+    }
+    /**
+     * Opens the Add form under an item. With `placeKeys` every Add goes inside one - without one given, inside the selected
+     * row, and nothing opens while there is none - and the fields that say where are fixed to it: what `childValues` gives,
+     * and empty for a field it leaves out.
+     */
+    function create(parent, values) {
+        if (!allowed.create)
+            return;
+        const inside = placeKeys && !parent ? addTarget() : parent;
+        if (placeKeys && !inside)
+            return;
+        if (inside)
+            rememberParent(inside[valueKey]);
+        const under = inside && place.childValues ? place.childValues(inside) : {};
+        const fixed = {};
+        const locked = {};
+        for (const key of placeKeys ?? []) {
+            fixed[key] = under[key] ?? null;
+            locked[key] = `Added inside ${itemLabel(inside)}: pick another row in the tree to add elsewhere.`;
+        }
+        void openCrudForm({
+            api,
+            action: "create",
+            row: null,
+            values: { ...under, ...values, ...fixed },
+            locked: placeKeys ? locked : undefined,
+            inputs: latest.current.inputs,
+            form: latest.current.form,
+            subject,
+            name,
+            rowKey,
+            // Says where, in the title bar and on the dock: two Adds minimized inside two rows read apart.
+            label: inside ? `Inside ${itemLabel(inside)}` : undefined,
+            onSaved: (result, sent, joined) => void afterSave(null, result, sent, joined),
+        });
+    }
+    /** Opens a record's Edit form; with `placeKeys` its place stays as it is, fixed, and moves only where it is offered. */
+    function edit(row) {
+        if (!allowed.edit)
+            return;
+        rememberParent(place.parentOf(row));
+        void openCrudForm({
+            api,
+            action: "edit",
+            row,
+            locked: placeKeys ? Object.fromEntries(placeKeys.map(key => [key, "Its place cannot be changed in the tree."])) : undefined,
+            inputs: latest.current.inputs,
+            form: latest.current.form,
+            subject,
+            name,
+            rowKey,
+            key: keyOf(row),
+            label: labelOf(row),
+            onSaved: (result, sent, joined) => void afterSave(row, result, sent, joined),
+        });
+    }
+    /**
+     * A record saved through the form, finished with no call and written in where it now belongs, shown in the panel and
+     * in the tree: the fields only the server keeps as the backend writes them (`savedRow`), the names the database joins
+     * from the records the form picked, the page holds, or the tree holds - the parent it sits under - and the record as
+     * the tree counts it (`crudSavedCount`: a new one has no children, an edited one the count the tree keeps now). An
+     * edited record is finished from the row as the tree holds it now, not as the form opened it.
+     */
+    async function afterSave(row, result, sent, joined) {
+        const action = row ? "edit" : "create";
+        const answered = backend.answeredRow(result);
+        let record = crudSavedRecord(row, sent, answered);
+        if (!answered && !readPath(record, rowKey)) {
+            const given = backend.answeredKey(result);
+            if (given !== null && !rowKey.includes("."))
+                record[rowKey] = given;
+        }
+        if (!keyOf(record))
+            return;
+        const heldItem = row ? treeRef.current?.getItem(valueOf(row)) : undefined;
+        const held = row ? ((heldItem ? place.recordOf(heldItem) : null) ?? row) : undefined;
+        record = backend.savedRow(action, record, held);
+        const parentValue = place.parentOf(record);
+        const parentItem = parentValue === null ? undefined : treeRef.current?.getItem(parentValue);
+        const parent = parentItem ? place.recordOf(parentItem) : null;
+        record = crudJoinedNames(record, held, latest.current.columns, (from, key) => joined(from, key, parent ? [parent] : []));
+        record = crudSavedCount(record, held, place);
+        changed({ action, rows: [record], mode: "normal", before: [held] });
+        show(record);
+        revealInTree(record);
+        // Read back only what nothing here can finish: a list unknown (never the Nexus backend's: `savedRow`), or a name.
+        if (api.details && (backend.listMembership(record, "normal") === undefined || crudJoinsMissing(record, held, latest.current.columns)))
+            await fill(record);
+    }
+    /** Reads one record back, and writes it in place: into the tree, its kept pages, and the panel if it shows it. */
+    async function fill(record) {
+        if (!api.details)
+            return;
+        const id = readPath(record, rowKey);
+        const answer = await browserApi.get(api.details, { params: { id, [rowKey]: id }, toast: false });
+        const full = unwrapApiResult(answer);
+        if (!isRecord(full))
+            return;
+        const next = { ...record, ...full };
+        writeTreeChanges(place.cacheKey, crudTreeChanges({ action: "edit", rows: [next], mode: "normal", before: [record] }, place, backend), place.rules);
+        setPicked(current => (current && keyOf(current) === keyOf(next) ? next : current));
+        setStamp(count => count + 1);
+    }
+    /** Moves a record to the trash or back, or deletes it: the call the table makes, then the tree and the panel follow. */
+    async function run(action, row) {
+        const fromPanel = Boolean(actionsRef.current?.contains(document.activeElement));
+        setBusy(true);
+        try {
+            const answer = await sendCrudRowAction(api, action, row, { rowKey, label: labelOf(row), backend });
+            if (!answer?.ok)
+                return;
+            const one = backend.answeredRow(answer.result);
+            const next = (one ? { ...row, ...one } : row);
+            // An answer that does not say where the record went: where the action takes it.
+            const wasIn = inTree(row);
+            const nowIn = backend.listMembership(next, "normal") ?? action === "recover";
+            const treeChanges = [];
+            if (wasIn && !nowIn)
+                treeChanges.push({ type: "remove", value: valueOf(row), parent: place.parentOf(row) });
+            else if (!wasIn && nowIn)
+                treeChanges.push({ type: "put", item: place.itemOf(next), parent: place.parentOf(next), before: false });
+            changed({ action, rows: [next], mode: modeOf(row), before: [row] }, treeChanges);
+            refocusRef.current = fromPanel;
+            show(next);
+            if (!wasIn && nowIn)
+                revealInTree(next);
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    function openHistory(row) {
+        if (!api.audit)
+            return;
+        openAuditHistory({ endpoint: api.audit, id: readPath(row, rowKey), subject, subjectPlural: props.subjectPlural ?? pluralize(subject), label: labelOf(row), backend });
+    }
+    /** A click or Enter on an item selects it: a record shows in the panel, anything else empties it and opens. */
+    function pick(item) {
+        const record = place.recordOf(item);
+        if (!record) {
+            show(null, item);
+            treeRef.current?.expand(item[valueKey]);
+            return;
+        }
+        show(record, item);
+        // A record whose list cannot be told - written by a backend whose saves leave no status, never the Nexus backend's - is read once.
+        if (api.details && backend.listMembership(record, "normal") === undefined)
+            void fill(record);
+    }
+    /** The actions on a row of the tree: Add New under it, and on an active record Edit and Move to trash. */
+    function rowActions(item) {
+        const list = [];
+        if (allowed.create)
+            list.push({ id: "create", ...crudActionEntry("create"), inline: true, shortcut: "Insert", onSelect: () => create(item) });
+        const record = place.recordOf(item);
+        if (!record || modeOf(record) !== "normal")
+            return list;
+        if (allowed.edit)
+            list.push({ id: "edit", ...crudActionEntry("edit"), inline: true, shortcut: "F2", onSelect: () => edit(record) });
+        const out = trashless ? "delete" : "trash";
+        if (allowed[out])
+            list.push({ id: out, ...crudActionEntry(out), inline: true, shortcut: "Delete", onSelect: () => run(out, record) });
+        return list;
+    }
+    // The panel's first button takes focus after an action pressed there took its own away (Move to trash became Recover).
+    useLayoutEffect(() => {
+        if (!refocusRef.current)
+            return;
+        refocusRef.current = false;
+        actionsRef.current?.querySelector("button:not(:disabled)")?.focus();
+    }, [stamp, busy]);
+    useImperativeHandle(ref, () => ({
+        get tree() {
+            return treeRef.current;
+        },
+        create: (parent, values) => create(parent ?? null, values),
+        edit,
+        pick: show,
+    }));
+    let body = null;
+    let actions = null;
+    if (picked) {
+        const mode = modeOf(picked);
+        const offered = crudRowActions(mode, action => Boolean(allowed[action]), trashless);
+        const ids = [];
+        if (mode === "normal" && allowed.create)
+            ids.push("create");
+        for (const action of PANEL_ORDER)
+            if (offered.includes(action))
+                ids.push(action);
+        const record = picked;
+        const label = labelOf(record);
+        body = _jsx(CrudDetails, { row: record, columns: columns }, `${keyOf(record)}:${stamp}`);
+        actions =
+            ids.length > 0 ? (_jsx("div", { ref: actionsRef, className: "nx-crud-tree__actions", role: "group", "aria-label": `${capitalize(subject)}: ${label}`, children: ids.map(id => {
+                    const entry = crudActionEntry(id);
+                    const onClick = id === "create"
+                        ? () => create(place.itemOf(record))
+                        : id === "edit"
+                            ? () => edit(record)
+                            : id === "history"
+                                ? () => openHistory(record)
+                                : () => void run(id, record);
+                    return (_jsx(Button, { size: "sm", icon: entry.icon, hoverTone: entry.tone, disabled: busy, "data-action": id, title: id === "create" ? `${entry.label}: inside ${label}` : undefined, onClick: onClick, children: entry.label }, id));
+                }) })) : null;
+    }
+    // The toolbar's Add New: at the top level, or - with place keys - inside the selected row, and saying why not without one.
+    let add;
+    if (allowed.create && !placeKeys)
+        add = { label: CRUD_ACTION_WORDS.create.label, onClick: () => create(null) };
+    else if (allowed.create) {
+        const target = addTarget();
+        const description = target ? `Adds a new ${subject} inside ${itemLabel(target)}.` : `Select a row in the tree to add a new ${subject} inside it.`;
+        add = { label: CRUD_ACTION_WORDS.create.label, onClick: () => create(null), disabled: !target, description };
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(TreeView, { ...treeProps, ref: treeRef, valueKey: valueKey, hasChildrenKey: place.rules.hasChildrenKey, cacheKey: place.cacheKey, rowActions: rowActions, add: add, selectedValue: selected ? selected[valueKey] : null, onItemClick: pick }), props.details?.({ row: picked, body, actions })] }));
+}

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

@@ -0,0 +1,73 @@
+import { type ReactNode } from "react";
+import { type CrudRecordRead } from "../../Helpers/CrudDetailsTabs.ts";
+import type { FormStore } from "../../Helpers/FormStore.ts";
+import type { CrudDetailsOptions, CrudDetailsProfile } from "../../Interfaces/CrudInterfaces.ts";
+import type { FormValues } from "../../Interfaces/FormInterfaces.ts";
+import type { TableColumn } from "../../Interfaces/TableInterfaces.ts";
+import type { PopupHandle } from "../Layouts/PopupHost.tsx";
+import { type FormLeaveGuard } from "./FormLeaveGuard.ts";
+export interface CrudWorkspaceProps<TRow extends FormValues = FormValues> {
+    /** The page's details options: `tabs`, `profile`, `remember`. */
+    options: CrudDetailsOptions<TRow>;
+    /** The record: the row at once, then the details endpoint's record, then each refresh's. */
+    form: FormStore<TRow>;
+    /** The row as the list has it now. */
+    current: () => TRow;
+    popup: PopupHandle;
+    /** The details' fields (`columns`, else the table's): what a string in the profile's `fields` names. */
+    columns: readonly TableColumn<TRow>[];
+    /** The currency of a `money` field without its own, as the table writes it. */
+    currency?: string | null;
+    /**
+     * The built-in details: the fields, with the `aside` beside them, less the fields the profile shows (`fields`), given
+     * the workspace's `refresh` (a section's own Edit reads the record again with it once saved).
+     */
+    details: (without: readonly (TableColumn<TRow> | string)[] | undefined, refresh: () => Promise<TRow | null>) => ReactNode;
+    /** Starts reading the record from the details endpoint, once: called when the workspace is first drawn. */
+    load?: () => void;
+    /**
+     * How that read is coming along (the footer's own state): a profile field the row lacks is held while it is read and
+     * says "Not loaded" when it failed. Without it the record counts as read.
+     */
+    read?: {
+        get: () => CrudRecordRead;
+        subscribe: (listener: () => void) => () => void;
+    };
+    refresh: () => Promise<TRow | null>;
+    /** What the tabs are named for screen readers: "Guest". */
+    subject: string;
+    /**
+     * The forms the tabs draw (every `SubmitForm` and `ApiForm` joins it): a switch to another tab, and the popup's
+     * closing, ask "Discard your changes?" while one has changes.
+     */
+    guard: FormLeaveGuard;
+    /**
+     * Told the chosen tab when the workspace opens and on every switch: the Crud shows the popup's footer (View history,
+     * Edit, Close) only while the built-in Details tab is chosen.
+     */
+    onTab?: (tab: string) => void;
+}
+/**
+ * Asks "Discard your changes?" when a form in a place that is about to go away (a `FormLeaveGuard`: a tab of a record's
+ * workspace, its popup) has changes. Resolves `true` to go on - nothing changed, or the user chose Discard, which drops
+ * the form's draft - and `false` to stay.
+ */
+export declare function confirmLeaving(guard: FormLeaveGuard): Promise<boolean>;
+/**
+ * A record's picture where it is shown large (a workspace's profile, a record page's hero): by its Drive params, a button
+ * that opens the pictures window, the record's initials standing in; or what the page draws in its place. `size` is a
+ * CSS length. Read-only shows the pictures with no way to change them. `round` draws it as a circle whatever the
+ * picture's own shape (a workspace's profile); the pictures window keeps the picture's shape and aspect.
+ */
+export declare function ProfilePicture({ picture, title, size, readOnly, round }: {
+    picture: CrudDetailsProfile["picture"];
+    title: ReactNode;
+    size: string;
+    readOnly?: boolean;
+    round?: boolean;
+}): ReactNode;
+/**
+ * The workspace: profile and tabs on the left, the chosen tab on the right. Only the chosen tab is drawn; a switch
+ * keeps the focus on the tabs, or puts it on the chosen tab when the panel that held it went away.
+ */
+export declare function CrudWorkspace<TRow extends FormValues>({ options, form, current, popup, columns, currency, details, load, read, refresh, subject, guard, onTab }: CrudWorkspaceProps<TRow>): import("react").JSX.Element;

package/dist/Components/Forms/CrudWorkspace.js

@@ -0,0 +1,177 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconInfoCircle, InlineIcon } from "nexus-icons";
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { CRUD_DETAILS_TAB, crudProfileFields, crudTabStorageKey, isAwaitedCrudField, isCrudPicture, isCrudProfile, offeredCrudTabs, openingCrudTab, readCrudTab, writeCrudTab } from "../../Helpers/CrudDetailsTabs.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { getPermissions, permissionsVersion, subscribePermissions } from "../../Helpers/Permissions.js";
+import { useNumberLocale } from "../../Helpers/UserPreferences.js";
+import { TabPanel, Tabs } from "../Documents/Tabs.js";
+import { TableCellValue } from "../Viewers/DataTableParts.js";
+import { openPictureGallery, OwnerPicture } from "../Viewers/OwnerFiles.js";
+import { FormLeaveGuardContext } from "./FormLeaveGuard.js";
+import { confirmDiscard } from "./SubmitForm.js";
+/*
+ * A record's workspace in its details popup (`CrudDetailsOptions.tabs` and `profile`): who the record is and its tabs
+ * in a column on the left, the chosen tab on the right. The Crud owns the record (the FormStore), its loading and the
+ * lists a `refresh()` writes into; this draws them and keeps which tab is chosen.
+ */
+const subscribeNothing = () => () => { };
+const readDone = () => "done";
+/** This browser's local storage, or nothing where it cannot be reached (a server draw, storage switched off). */
+function browserStorage() {
+    try {
+        return typeof window === "undefined" ? null : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Asks "Discard your changes?" when a form in a place that is about to go away (a `FormLeaveGuard`: a tab of a record's
+ * workspace, its popup) has changes. Resolves `true` to go on - nothing changed, or the user chose Discard, which drops
+ * the form's draft - and `false` to stay.
+ */
+export async function confirmLeaving(guard) {
+    const form = guard.changed();
+    if (!form)
+        return true;
+    if (!(await confirmDiscard(form)))
+        return false;
+    form.dropDraft();
+    return true;
+}
+/**
+ * A record's picture where it is shown large (a workspace's profile, a record page's hero): by its Drive params, a button
+ * that opens the pictures window, the record's initials standing in; or what the page draws in its place. `size` is a
+ * CSS length. Read-only shows the pictures with no way to change them. `round` draws it as a circle whatever the
+ * picture's own shape (a workspace's profile); the pictures window keeps the picture's shape and aspect.
+ */
+export function ProfilePicture({ picture, title, size, readOnly = false, round = false }) {
+    if (!isCrudPicture(picture))
+        return picture ?? null;
+    const named = typeof title === "string" ? title : undefined;
+    const { name, module, category, ownerId, aspect, shape, ...gallery } = picture;
+    const owner = { module, category, ownerId };
+    return (_jsx(OwnerPicture, { owner: owner, size: size, aspect: round ? 1 : aspect, shape: round ? "circle" : shape, name: name ?? named ?? null, label: named ? `${named}: pictures` : "Pictures", onClick: () => openPictureGallery({ ...gallery, ...owner, aspect, shape, title: gallery.title ?? named, readOnly: gallery.readOnly || readOnly }) }));
+}
+/**
+ * A few of the record's fields under the profile's tags (`profile.fields`): label and value, the value drawn as the
+ * table and the details draw it (the person's date and number formats, an option's tone, the column's tag after it).
+ */
+function CrudProfileFields({ fields, row, currency, read }) {
+    const preferences = useDatePreferences();
+    const timeZone = useBrowserTimeZone();
+    const locale = useNumberLocale();
+    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined, locale, currency }), [preferences, timeZone, locale, currency]);
+    const awaiting = fields.some(column => isAwaitedCrudField(column, row, read));
+    return (_jsx("dl", { className: "nx-crud-profile__fields", "aria-busy": (awaiting && read === "loading") || undefined, children: fields.map(column => (_jsxs("div", { className: "nx-crud-profile__field", children: [_jsx("dt", { className: "nx-crud-profile__label", children: column.label }), " ", _jsx("dd", { className: "nx-crud-profile__value", children: !isAwaitedCrudField(column, row, read) ? (_jsx(TableCellValue, { column: column, row: row, options: options })) : read === "failed" ? (_jsx("span", { className: "nx-crud-details__missing", children: "Not loaded" })) : (_jsx("span", { className: "nx-table__bone nx-record__bone nx-crud-profile__bone", "aria-hidden": "true" })) })] }, column.key))) }));
+}
+/**
+ * The profile at the top of the column: the picture in a circle (a button that opens the pictures), the name, a line,
+ * tags, and a few of the record's fields. A profile of a picture and a name alone is those two, in the middle.
+ */
+function CrudProfile({ profile, row, columns, currency, read }) {
+    const { picture, title, subtitle, tags } = profile;
+    const fields = crudProfileFields(profile.fields, columns, row, read);
+    return (_jsxs("div", { className: "nx-crud-profile", children: [picture !== undefined && picture !== null && picture !== false && (_jsx("div", { className: "nx-crud-profile__picture", children: _jsx(ProfilePicture, { picture: picture, title: title, size: "var(--nx-crud-profile-picture)", round: true }) })), _jsxs("div", { className: "nx-crud-profile__text", children: [_jsx("p", { className: "nx-crud-profile__title", children: title }), subtitle !== undefined && subtitle !== null && subtitle !== "" && _jsx("p", { className: "nx-crud-profile__subtitle", children: subtitle }), tags && tags.length > 0 && (_jsx("p", { className: "nx-crud-profile__tags", children: tags.map((tag, index) => (_jsx("span", { className: "nx-table__tag", "data-tone": tag.tone, children: tag.label }, index))) })), fields.length > 0 && _jsx(CrudProfileFields, { fields: fields, row: row, currency: currency, read: read })] })] }));
+}
+/**
+ * The workspace: profile and tabs on the left, the chosen tab on the right. Only the chosen tab is drawn; a switch
+ * keeps the focus on the tabs, or puts it on the chosen tab when the panel that held it went away.
+ */
+export function CrudWorkspace({ options, form, current, popup, columns, currency, details, load, read, refresh, subject, guard, onTab }) {
+    const id = useId();
+    const recordRead = useSyncExternalStore(read?.subscribe ?? subscribeNothing, read?.get ?? readDone, read?.get ?? readDone);
+    // The record as it is now: the profile and the tabs' rules follow it.
+    const record = useSyncExternalStore(form.subscribeValue, () => form.getValue(), () => form.getValue());
+    useSyncExternalStore(subscribePermissions, permissionsVersion, permissionsVersion);
+    const permissions = getPermissions();
+    const can = permissions.ready ? permissions.can.bind(permissions) : () => false;
+    const offered = options.tabs ? offeredCrudTabs(options.tabs, record, can) : [];
+    const storage = useMemo(() => crudTabStorageKey(options.remember), [options.remember?.key, options.remember?.viewer]); // eslint-disable-line react-hooks/exhaustive-deps
+    const [asked, setAsked] = useState(() => readCrudTab(browserStorage(), storage));
+    const chosen = openingCrudTab(offered, asked) ?? CRUD_DETAILS_TAB;
+    // Bumped by each refresh, so the built-in details are drawn again from the record read again (in place: what has the
+    // focus keeps it).
+    const [, setVersion] = useState(0);
+    const rootRef = useRef(null);
+    // Set when a switch took the panel that held the focus: the chosen tab takes it once drawn.
+    const refocus = useRef(false);
+    // A switch takes the chosen tab away: a form in it with changes asks first. One question at a time.
+    const asking = useRef(false);
+    async function select(tab) {
+        if (!offered.some(one => one.id === tab) || tab === chosen || asking.current)
+            return;
+        if (guard.changed()) {
+            asking.current = true;
+            const leave = await confirmLeaving(guard).finally(() => (asking.current = false));
+            if (!leave)
+                return;
+        }
+        const active = document.activeElement;
+        const panel = rootRef.current?.querySelector(".nx-crud-workspace__panel");
+        // The focus in the panel, or in the popup's footer, which only the Details tab has: the chosen tab takes it.
+        refocus.current = !active || active === document.body || Boolean(panel?.contains(active)) || Boolean(active.closest(".nx-popup__foot"));
+        setAsked(tab);
+        writeCrudTab(browserStorage(), storage, tab);
+    }
+    // Before the paint, so the footer of a tab that does not have one is never drawn.
+    useLayoutEffect(() => {
+        onTab?.(chosen);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [chosen]);
+    useLayoutEffect(() => {
+        if (!refocus.current)
+            return;
+        refocus.current = false;
+        rootRef.current?.querySelector('[role="tab"][aria-selected="true"]')?.focus();
+    }, [chosen]);
+    useEffect(() => {
+        load?.();
+        // The record is read once per popup.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // A panel that went away under the focus (a tab hidden by a refresh) leaves it on the chosen tab, never on the page.
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const onOut = (event) => {
+            if (event.relatedTarget)
+                return;
+            window.requestAnimationFrame(() => {
+                if (document.activeElement === document.body && root.isConnected)
+                    root.querySelector('[role="tab"][aria-selected="true"], .nx-crud-workspace__panel')?.focus();
+            });
+        };
+        root.addEventListener("focusout", onOut);
+        return () => root.removeEventListener("focusout", onOut);
+    }, []);
+    async function refreshed() {
+        const next = await refresh();
+        setVersion(stamp => stamp + 1);
+        return next;
+    }
+    const given = options.profile?.(record);
+    let profile;
+    // The fields the profile shows: the Details tab leaves them out.
+    let profileFields;
+    if (isCrudProfile(given)) {
+        profile = _jsx(CrudProfile, { profile: given, row: record, columns: columns, currency: currency, read: recordRead });
+        profileFields = given.fields;
+    }
+    else
+        profile = given;
+    const tab = offered.find(one => one.id === chosen);
+    const row = current();
+    let body;
+    if (!tab || tab.builtIn)
+        body = _jsx("div", { children: details(profileFields, refreshed) });
+    else
+        body = tab.render?.({ row, form, popup, tab: tab.id, select: next => void select(next), refresh: refreshed });
+    const shownProfile = profile !== undefined && profile !== null && profile !== false;
+    const tabbed = offered.length > 1;
+    return (_jsx(FormLeaveGuardContext, { value: guard, children: _jsx("div", { ref: rootRef, className: "nx-crud-workspace", children: _jsxs("div", { className: cx("nx-crud-workspace__frame", !shownProfile && !tabbed && "nx-crud-workspace__frame--alone"), children: [(shownProfile || tabbed) && (_jsxs("div", { className: "nx-crud-workspace__side", children: [shownProfile && _jsx("div", { className: "nx-crud-workspace__profile", children: profile }), tabbed && (_jsx("div", { className: "nx-crud-workspace__nav", children: _jsx(Tabs, { id: id, design: "auto", "aria-label": `${subject} tabs`, value: chosen, onChange: next => void select(next), options: offered.map(one => ({ value: one.id, label: one.label, icon: one.icon ?? (one.builtIn ? _jsx(InlineIcon, { icon: iconInfoCircle }) : undefined), badge: typeof one.badge === "function" ? one.badge(row) : one.badge })) }) }))] })), tabbed ? (_jsx(TabPanel, { tabs: id, value: chosen, className: "nx-crud-workspace__panel", children: body })) : (_jsx("div", { className: "nx-crud-workspace__panel", children: body }))] }) }) }));
+}

package/dist/Components/Forms/ExcelImport.js

@@ -277,9 +277,9 @@ export function openExcelImport({ title, popupKey, ...props }) {
     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.
+    // Picked again while its window is still open - minimized by a page's rule (it has no minimize button of its own), or
+    // from code - 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();