nexus-shared 3.2.0 → 4.0.0

package/dist/Components/Inputs/TreeView.js

@@ -5,7 +5,7 @@ import { isValidElement, useEffect, useId, useImperativeHandle, useLayoutEffect,
 import { afterAnimation } from "../../Helpers/AnimationHelpers.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { isPromiseLike, REQUEST_CACHE_LIFETIME } from "../../Helpers/RequestCache.js";
-import { expireTreePages, TREE_DEFAULT_KEYS, treePageKey, treePages, TreeStore, treeStatusKey, } from "../../Helpers/TreeStore.js";
+import { expireTreePages, subscribeTreeChanges, TREE_DEFAULT_KEYS, treeKey, treePageKey, treePages, TreeStore, treeStatusKey, } from "../../Helpers/TreeStore.js";
 import { Button } from "../Documents/Button.js";
 import { ContextMenu } from "../Documents/Menu.js";
 import { messageBox } from "../Layouts/MessageBox.js";
@@ -56,7 +56,7 @@ const sameItems = (a, b) => a === b || (a.length === b.length && a.every((item,
  *   loadChildren={({ parent, skip, take, signal }) => loadRegions(parent, skip, take, signal)} />
  */
 export function TreeView(props) {
-    const { items: givenItems, loadChildren, childPageSize = CHILD_PAGE_SIZE, hasChildrenKey, cacheKey, cacheLifetime = REQUEST_CACHE_LIFETIME, partialMessage = "Its items are not all loaded: open it and load them all to check it as a whole.", valueKey = TREE_DEFAULT_KEYS.value, parentKey = TREE_DEFAULT_KEYS.parent, labelKey = TREE_DEFAULT_KEYS.label, descriptionKey = "description", iconKey = "icon", isItemDisabled, lockedMessage = "You do not have permission to change this item.", label, hint, error, size = "md", checkable = false, cascade = true, valueMode = "leaves", value, defaultValue, onValueChange, name, form, counts = true, defaultExpanded, creatable = false, editable = false, deletable = false, canChange, onCreate, onUpdate, onDelete, onItemsChange, confirmDelete = true, maxLabelLength = 100, onItemClick, loading = false, emptyMessage = "No items", toolbar = true, height, maxHeight = 420, readOnly = false, readOnlyMessage = "Read-only: this tree cannot be changed.", disabled = false, id, className, style, "aria-label": ariaLabel, ref, } = props;
+    const { items: givenItems, loadChildren, childPageSize = CHILD_PAGE_SIZE, hasChildrenKey, cacheKey, cacheLifetime = REQUEST_CACHE_LIFETIME, partialMessage = "Its items are not all loaded: open it and load them all to check it as a whole.", valueKey = TREE_DEFAULT_KEYS.value, parentKey = TREE_DEFAULT_KEYS.parent, labelKey = TREE_DEFAULT_KEYS.label, descriptionKey = "description", iconKey = "icon", isItemDisabled, lockedMessage = "You do not have permission to change this item.", label, hint, error, size = "md", checkable = false, cascade = true, valueMode = "leaves", value, defaultValue, onValueChange, name, form, counts = true, defaultExpanded, creatable = false, editable = false, deletable = false, canChange, onCreate, onUpdate, onDelete, onItemsChange, confirmDelete = true, rowActions, add, selectedValue, maxLabelLength = 100, onItemClick, loading = false, emptyMessage = "No items", toolbar = true, height, maxHeight = 420, fill = false, readOnly = false, readOnlyMessage = "Read-only: this tree cannot be changed.", disabled = false, id, className, style, "aria-label": ariaLabel, ref, } = props;
     const generatedId = useId();
     const treeId = id ?? generatedId;
     const labelId = `${treeId}-label`;
@@ -142,6 +142,8 @@ export function TreeView(props) {
     const pendingScrollRef = useRef(null);
     const pendingFocusRef = useRef(null);
     const typeaheadRef = useRef({ text: "", at: 0 });
+    // An item the handle was asked to reveal before it was loaded: revealed when the page that brings it comes.
+    const pendingRevealRef = useRef(null);
     const blocked = readOnly || disabled;
     const noticeAnchor = (target) => {
         const row = target.closest(".nx-tree__row");
@@ -150,6 +152,10 @@ export function TreeView(props) {
     const readOnlyNotice = useReadOnlyNotice(readOnly && !disabled, viewportRef, readOnlyMessage, { anchor: noticeAnchor, typing: false, lock: "label" });
     const lockedNotice = useReadOnlyNotice(!blocked, viewportRef, lockedMessage, { anchor: noticeAnchor, typing: false, lock: "label" });
     const partialNotice = useReadOnlyNotice(!blocked && lazy && checkable && cascade, viewportRef, partialMessage, { anchor: noticeAnchor, typing: false, lock: "label" });
+    // Why the toolbar's own button cannot be pressed yet, under it, on a press.
+    const addNotice = useReadOnlyNotice(Boolean(add?.disabled && add.description), viewportRef, add?.description, { anchor: target => target.closest(".nx-btn"), align: "end", typing: false, lock: "label" });
+    // The row shown as selected, as a node key.
+    const selectedKey = checkable ? null : treeKey(selectedValue);
     // The row a note points at: when it leaves the page (scrolled out of the window), the note goes too.
     const noteRowRef = useRef(null);
     function showNote(notice, target) {
@@ -319,6 +325,13 @@ export function TreeView(props) {
             });
         };
     }, []);
+    // Changes to the source written elsewhere (`writeTreeChanges`) are written into this tree too.
+    const applyRef = useRef(() => undefined);
+    useEffect(() => {
+        if (!lazy || !cacheKey)
+            return;
+        return subscribeTreeChanges(cacheKey, (changes, rules) => applyRef.current(changes, rules));
+    }, [lazy, cacheKey]);
     // Open parents with rows in view that need pages: the top level at first, a parent a refresh made stale, one whose
     // request a refresh forgot. A stale parent out of view waits until it scrolls in, and a closed one until it opens; a
     // failed one waits for Retry, so a server that is down is not asked again and again.
@@ -345,6 +358,88 @@ export function TreeView(props) {
     function onPanelFocus() {
         hadFocusRef.current = true;
     }
+    /**
+     * Changes made elsewhere, written in (the handle's `apply`). The focused row keeps focus; when it leaves the page or
+     * moves in it, focus goes to the viewport first, while the DOM is whole, and comes back to it - or, when the item
+     * left, to the row now in its place - in the layout effect, as when the window moves (see `releaseFocusLeaving`).
+     */
+    function applyChanges(changes, rules = {}) {
+        if (changes.length === 0)
+            return;
+        const viewport = viewportRef.current;
+        const active = document.activeElement;
+        const held = viewport && active instanceof HTMLElement && active !== viewport && viewport.contains(active) ? nodeOfTarget(active) : undefined;
+        const heldIndex = held ? store.indexOf(held) : -1;
+        const focused = focusKeyRef.current === null ? undefined : store.find(focusKeyRef.current);
+        const focusedIndex = focused ? store.indexOf(focused) : -1;
+        const valueBefore = valueSignature();
+        for (const change of changes) {
+            if (change.type === "put")
+                store.placeItem(change.item, change.parent, { before: change.before, compare: rules.compare });
+            else
+                store.removeItem(change.value, change.parent);
+        }
+        setMotion(null);
+        const stillThere = (node, index) => {
+            const found = store.find(node.key);
+            if (found && store.isVisible(found))
+                return found;
+            return store.rows.length > 0 ? store.rows[Math.max(0, Math.min(index, store.rows.length - 1))] : undefined;
+        };
+        if (held && viewport) {
+            const next = stillThere(held, heldIndex);
+            if (next !== held || store.indexOf(held) !== heldIndex) {
+                restoringRef.current = true;
+                viewport.focus({ preventScroll: true });
+                restoringRef.current = false;
+                if (next)
+                    focusNode(next);
+            }
+        }
+        else if (focused && !(store.find(focused.key) === focused && store.isVisible(focused))) {
+            setFocusKey(stillThere(focused, focusedIndex)?.key ?? null);
+        }
+        emitValueIfChanged(valueBefore);
+        bump();
+    }
+    applyRef.current = applyChanges;
+    /** An item revealed before it was loaded, revealed now if the answer just in brought it. */
+    function revealPending() {
+        const pending = pendingRevealRef.current;
+        const node = pending ? store.get(pending.key) : undefined;
+        if (!pending || !node)
+            return;
+        pendingRevealRef.current = null;
+        if (pending.focus) {
+            focusNode(node);
+            return;
+        }
+        if (store.reveal(node))
+            setMotion(null);
+        pendingScrollRef.current = store.indexOf(node);
+    }
+    /** The page's own actions on a row, where they may be offered. */
+    function rowActionsOf(node) {
+        if (!rowActions || blocked || node.status || node.draft || node.disabledPath)
+            return [];
+        return rowActions(node.item);
+    }
+    /** Runs one of them. The row is busy, its actions waiting, while a promise the action returns runs. */
+    function runRowAction(node, action) {
+        if (blocked || action.disabled || busyKeys.has(node.key))
+            return;
+        pendingRevealRef.current = null;
+        const result = action.onSelect(node.item);
+        if (!isPromiseLike(result))
+            return;
+        const key = node.key;
+        setBusy(key, true);
+        const done = () => {
+            if (mountedRef.current)
+                setBusy(key, false);
+        };
+        result.then(done, done);
+    }
     function onPanelBlur(event) {
         const next = event.relatedTarget;
         if (next instanceof Node && panelRef.current?.contains(next))
@@ -354,6 +449,7 @@ export function TreeView(props) {
             readOnlyNotice.hide();
             lockedNotice.hide();
             partialNotice.hide();
+            addNotice.hide();
             return;
         }
         // Focus went nowhere: a click on the page, or a focused row that left the DOM. The first is settled after this frame.
@@ -526,6 +622,7 @@ export function TreeView(props) {
             if (result.change)
                 setMotion(openMotion(result.change));
             followStatusFocus(current, result.added);
+            revealPending();
             const now = store.pagesOf(current);
             const count = result.added.length;
             const of = now?.total !== undefined ? ` (${now.loaded.toLocaleString()} of ${now.total.toLocaleString()})` : "";
@@ -575,6 +672,7 @@ export function TreeView(props) {
                 return;
             setMotion(null);
             followStatusFocus(current, []);
+            revealPending();
             setAnnouncement(`Items loaded again${where}.`);
             bump();
         };
@@ -881,6 +979,8 @@ export function TreeView(props) {
     }
     // Pointer and keys
     function onViewportPointerDown(event) {
+        // The user moves on: an item waiting to be revealed is not brought into view under them later.
+        pendingRevealRef.current = null;
         // The context menu opens on the row that was pressed, or at the top level on empty space or a status row.
         const node = nodeOfTarget(event.target);
         setContextKey(node && !node.status ? node.key : null);
@@ -922,6 +1022,7 @@ export function TreeView(props) {
         if (event.defaultPrevented || event.target.closest(".nx-tree__edit"))
             return;
         setContextKey(undefined);
+        pendingRevealRef.current = null;
         if (event.key === "Escape" && noteRowRef.current) {
             noteRowRef.current = null;
             readOnlyNotice.hide();
@@ -990,12 +1091,18 @@ export function TreeView(props) {
             setMotion(null);
             bump();
         }
-        else if (key === "F2")
-            startRename(node);
-        else if (key === "Delete")
-            void requestDelete(node);
-        else if (key === "Insert")
-            startCreate(node);
+        else if (key === "F2" || key === "Delete" || key === "Insert") {
+            // The page's own action for the key, where it gave one; else the tree's own editing.
+            const own = rowActionsOf(node).find(action => action.shortcut === key && !action.disabled);
+            if (own)
+                runRowAction(node, own);
+            else if (key === "F2")
+                startRename(node);
+            else if (key === "Delete")
+                void requestDelete(node);
+            else
+                startCreate(node);
+        }
         else if (key.length === 1 && !ctrlKey && !metaKey && !altKey && key !== " ") {
             const now = performance.now();
             const typed = typeaheadRef.current;
@@ -1041,7 +1148,20 @@ export function TreeView(props) {
             contextItems.push({ value: "delete", label: "Delete", icon: _jsx(InlineIcon, { icon: iconTrash }), shortcut: "Delete", tone: "danger", disabled: !allowed("delete", contextNode) });
         }
     }
+    // The page's own actions on the row, after the tree's.
+    const ownActions = contextNode ? rowActionsOf(contextNode) : [];
+    if (ownActions.length > 0 && contextItems.length > 0)
+        contextItems.push({ separator: true });
+    for (const action of ownActions) {
+        contextItems.push({ value: `row:${action.id}`, label: action.label, description: action.description, icon: action.icon, shortcut: action.shortcut, tone: action.tone, disabled: action.disabled });
+    }
     function onContextSelect(action) {
+        if (action.startsWith("row:")) {
+            const own = ownActions.find(each => `row:${each.id}` === action);
+            if (own && contextNode)
+                runRowAction(contextNode, own);
+            return;
+        }
         if (action === "create")
             startCreate(contextNode ?? null);
         else if (action === "update" && contextNode)
@@ -1076,8 +1196,12 @@ export function TreeView(props) {
         },
         reveal: (revealValue, focus = true) => {
             const node = store.get(revealValue);
-            if (!node)
+            if (!node) {
+                const key = treeKey(revealValue);
+                pendingRevealRef.current = key === null ? null : { key, focus };
                 return;
+            }
+            pendingRevealRef.current = null;
             if (focus) {
                 focusNode(node);
                 return;
@@ -1099,6 +1223,10 @@ export function TreeView(props) {
                 afterCheck();
         },
         getItems: () => store.items(),
+        getItem: itemValue => {
+            const node = store.get(itemValue);
+            return node && !node.draft ? node.item : undefined;
+        },
         startCreate: parentValue => startCreate(parentValue === null ? null : (store.get(parentValue) ?? null)),
         startRename: renameValue => {
             const node = store.get(renameValue);
@@ -1126,6 +1254,7 @@ export function TreeView(props) {
             setMotion(null);
             bump();
         },
+        apply: (changes, rules) => applyChanges(changes, rules),
     }));
     // Rendering
     const showCounts = checkable && cascade && counts;
@@ -1191,8 +1320,13 @@ export function TreeView(props) {
             if (allowed("delete", node)) {
                 actions.push(_jsx(Button, { variant: "ghost", size: "sm", hoverTone: "danger", className: "nx-tree__action", icon: _jsx(InlineIcon, { icon: iconTrash }), "aria-label": `Delete ${node.label}`, title: "Delete (Delete)", tabIndex: -1, onMouseDown: keepEditorFocus, onClick: () => void requestDelete(node) }, "delete"));
             }
+            for (const action of rowActionsOf(node)) {
+                if (!action.inline)
+                    continue;
+                actions.push(_jsx(Button, { variant: "ghost", size: "sm", hoverTone: action.tone, className: "nx-tree__action", icon: action.icon, "aria-label": `${action.label}: ${node.label}`, title: action.shortcut ? `${action.label} (${action.shortcut})` : action.label, tabIndex: -1, disabled: action.disabled, "data-action": action.id, onMouseDown: keepEditorFocus, onClick: () => runRowAction(node, action) }, `row:${action.id}`));
+            }
         }
-        return (_jsxs("div", { role: ghost ? undefined : "treeitem", className: cx("nx-tree__row", locked && "nx-tree__row--locked", edit && "nx-tree__row--editing"), style: { "--nx-tree-depth": node.depth }, "data-key": ghost ? undefined : node.key, "data-uid": ghost ? undefined : node.uid, "data-readonly": locked || undefined, tabIndex: ghost ? undefined : !disabled && tabbable === node ? 0 : -1, "aria-level": ghost ? undefined : node.depth + 1, "aria-setsize": ghost ? undefined : setSize(node), "aria-posinset": ghost ? undefined : node.position + 1, "aria-expanded": ghost || !expandable ? undefined : node.expanded, "aria-checked": ghost || !state ? undefined : state === "mixed" ? "mixed" : state === "checked", "aria-disabled": ghost ? undefined : locked || undefined, "aria-busy": busy || childrenLoading || undefined, "aria-labelledby": ghost || edit ? undefined : labelElementId, "aria-label": edit ? (edit.mode === "create" ? "New item" : `Renaming ${node.label}`) : undefined, "aria-describedby": ghost || edit ? undefined : descriptionElementId, children: [_jsx("span", { className: "nx-tree__toggle", "aria-hidden": "true", children: expandable && _jsx(InlineIcon, { icon: iconChevronRight }) }), checkable && (_jsx("span", { className: cx("nx-tree__check nx-choice", `nx-choice--${size}`), "aria-hidden": "true", children: _jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", tabIndex: -1, checked: state === "checked", disabled: disabled, readOnly: true, ref: input => {
+        return (_jsxs("div", { role: ghost ? undefined : "treeitem", className: cx("nx-tree__row", locked && "nx-tree__row--locked", edit && "nx-tree__row--editing", node.key === selectedKey && "nx-tree__row--selected"), style: { "--nx-tree-depth": node.depth }, "data-key": ghost ? undefined : node.key, "data-uid": ghost ? undefined : node.uid, "data-readonly": locked || undefined, tabIndex: ghost ? undefined : !disabled && tabbable === node ? 0 : -1, "aria-level": ghost ? undefined : node.depth + 1, "aria-setsize": ghost ? undefined : setSize(node), "aria-posinset": ghost ? undefined : node.position + 1, "aria-expanded": ghost || !expandable ? undefined : node.expanded, "aria-checked": ghost || !state ? undefined : state === "mixed" ? "mixed" : state === "checked", "aria-selected": !ghost && node.key === selectedKey ? true : undefined, "aria-disabled": ghost ? undefined : locked || undefined, "aria-busy": busy || childrenLoading || undefined, "aria-labelledby": ghost || edit ? undefined : labelElementId, "aria-label": edit ? (edit.mode === "create" ? "New item" : `Renaming ${node.label}`) : undefined, "aria-describedby": ghost || edit ? undefined : descriptionElementId, children: [_jsx("span", { className: "nx-tree__toggle", "aria-hidden": "true", children: expandable && _jsx(InlineIcon, { icon: iconChevronRight }) }), checkable && (_jsx("span", { className: cx("nx-tree__check nx-choice", `nx-choice--${size}`), "aria-hidden": "true", children: _jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", tabIndex: -1, checked: state === "checked", disabled: disabled, readOnly: true, ref: input => {
                             if (input)
                                 input.indeterminate = state === "mixed";
                         } }) })), icon && (_jsx("span", { className: "nx-tree__icon", "aria-hidden": "true", children: icon })), edit ? (_jsx(TreeEditor, { initial: editTextRef.current, select: edit.mode === "update", maxLength: maxLabelLength, saving: saving, label: edit.mode === "create" ? "Name of the new item" : `New name for ${node.label}`, invalid: message !== null, describedBy: message !== null ? messageId : undefined, onText: text => (editTextRef.current = text), onCommit: via => void commitEdit(via), onCancel: cancelEdit }, node.uid)) : (_jsxs("span", { className: "nx-tree__text", children: [_jsx("span", { id: ghost ? undefined : labelElementId, className: "nx-tree__label", title: node.label, children: node.label || "(no name)" }), hasDescription && (_jsx("span", { id: ghost ? undefined : descriptionElementId, className: "nx-tree__description", children: String(description) }))] })), showCounts && hasChildren && !edit && (_jsxs("span", { className: "nx-tree__count", "aria-hidden": "true", children: [node.checkedLeaves.toLocaleString(), "/", node.leaves.toLocaleString(), node.partial && "+"] })), busy && !edit && _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin nx-tree__busy", "aria-hidden": "true" }), locked && !edit && (_jsx("span", { className: "nx-tree__lock", title: lockedMessage, "aria-hidden": "true", children: _jsx(InlineIcon, { icon: iconLock }) })), actions.length > 0 && _jsx("span", { className: "nx-tree__actions", children: actions })] }, node.uid));
@@ -1236,17 +1370,17 @@ export function TreeView(props) {
     const rootWaiting = store.size === 0 && rootPages !== null && (rootPages.status === "idle" || rootPages.status === "loading");
     const waiting = loading || rootWaiting;
     const empty = total === 0 || rootWaiting;
-    return (_jsxs("div", { className: cx("nx-field nx-field--standard", `nx-field--${size}`, "nx-tree-field", className), style: style, "data-invalid": shownMessage ? true : undefined, "data-readonly": readOnly || undefined, "data-disabled": disabled || undefined, children: [hasLabel && (_jsxs("span", { id: labelId, className: "nx-field__label", children: [label, readOnlyNotice.lock] })), _jsxs("div", { ref: panelRef, className: cx("nx-tree", `nx-tree--${size}`), onFocus: onPanelFocus, onBlur: onPanelBlur, children: [toolbar && (_jsxs("div", { className: "nx-tree__toolbar", children: [checkable && (_jsx(CheckBox, { size: "sm", className: "nx-tree__all", label: "Select all", checked: allState === "checked", indeterminate: allState === "mixed", disabled: disabled || allState === null || empty, readOnly: readOnly, readOnlyMessage: readOnlyMessage, onValueChange: toggleAll })), _jsxs("span", { className: "nx-tree__summary", "aria-live": "polite", children: [(loading || rootPages?.status === "loading") && _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin", "aria-hidden": "true" }), waiting && empty
+    return (_jsxs("div", { className: cx("nx-field nx-field--standard", `nx-field--${size}`, "nx-tree-field", fill && "nx-tree-field--fill", className), style: style, "data-invalid": shownMessage ? true : undefined, "data-readonly": readOnly || undefined, "data-disabled": disabled || undefined, children: [hasLabel && (_jsxs("span", { id: labelId, className: "nx-field__label", children: [label, readOnlyNotice.lock] })), _jsxs("div", { ref: panelRef, className: cx("nx-tree", `nx-tree--${size}`), onFocus: onPanelFocus, onBlur: onPanelBlur, children: [toolbar && (_jsxs("div", { className: "nx-tree__toolbar", children: [checkable && (_jsx(CheckBox, { size: "sm", className: "nx-tree__all", label: "Select all", checked: allState === "checked", indeterminate: allState === "mixed", disabled: disabled || allState === null || empty, readOnly: readOnly, readOnlyMessage: readOnlyMessage, onValueChange: toggleAll })), _jsxs("span", { className: "nx-tree__summary", "aria-live": "polite", children: [(loading || rootPages?.status === "loading") && _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin", "aria-hidden": "true" }), waiting && empty
                                         ? "Loading…"
                                         : checkable
                                             ? `${tally.checked.toLocaleString()} of ${tally.total.toLocaleString()} selected`
-                                            : `${store.size.toLocaleString()} ${store.size === 1 ? "item" : "items"}${lazy ? " loaded" : ""}`, !hasLabel && readOnlyNotice.lock] }), _jsxs("span", { className: "nx-tree__tools", children: [_jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconChevronsDown }), "aria-label": "Expand all", title: "Expand all", disabled: !hasParents, onClick: expandAll }), _jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconChevronsUp }), "aria-label": "Collapse all", title: "Collapse all", disabled: !hasParents, onClick: collapseAll }), creatable && !blocked && (!canChange || canChange("create", null)) && (_jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconPlus }), onMouseDown: keepEditorFocus, onClick: () => startCreate(null), children: "Add" }))] })] })), _jsx(ContextMenu, { items: contextItems, onSelect: onContextSelect, disabled: contextItems.length === 0, "aria-label": "Item actions", children: _jsx("div", { ref: viewportRef, className: "nx-tree__viewport", style: { height, maxHeight: height === undefined ? maxHeight : undefined }, tabIndex: !disabled && !empty && !(tabbable && rendered.has(tabbable.key)) ? 0 : -1, onScroll: event => syncRange(event.currentTarget), onFocus: onViewportFocus, onPointerDown: onViewportPointerDown, onClick: onViewportClick, onKeyDown: onViewportKeyDown, children: empty ? (waiting ? (_jsx("div", { className: "nx-tree__list", "aria-hidden": "true", children: SKELETON_WIDTHS.map((width, index) => (_jsxs("div", { className: "nx-tree__row nx-tree__row--skeleton", style: { "--nx-tree-depth": index % 3 === 0 ? 0 : 1 }, children: [_jsx("span", { className: "nx-tree__toggle" }), _jsx("span", { className: "nx-tree__skeleton", style: { width } })] }, index))) })) : (_jsx("p", { className: "nx-tree__empty", children: emptyMessage }))) : (_jsx("div", { role: "tree", className: "nx-tree__list", "aria-labelledby": hasLabel ? labelId : undefined, "aria-label": hasLabel ? undefined : (ariaLabel ?? "Tree"), "aria-describedby": shownMessage || hasContent(hint) ? messageId : undefined, "aria-disabled": disabled || undefined, "aria-readonly": readOnly || undefined, "aria-busy": waiting || undefined, 
+                                            : `${store.size.toLocaleString()} ${store.size === 1 ? "item" : "items"}${lazy ? " loaded" : ""}`, !hasLabel && readOnlyNotice.lock] }), _jsxs("span", { className: "nx-tree__tools", children: [_jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconChevronsDown }), "aria-label": "Expand all", title: "Expand all", disabled: !hasParents, onClick: expandAll }), _jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconChevronsUp }), "aria-label": "Collapse all", title: "Collapse all", disabled: !hasParents, onClick: collapseAll }), creatable && !blocked && (!canChange || canChange("create", null)) && (_jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconPlus }), onMouseDown: keepEditorFocus, onClick: () => startCreate(null), children: "Add" })), add && !blocked && (_jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconPlus }), "aria-disabled": add.disabled || undefined, title: add.description, onMouseDown: keepEditorFocus, onKeyDown: addNotice.onKeyDown, onClick: event => (add.disabled ? addNotice.show(event.currentTarget) : add.onClick()), children: add.label }))] })] })), _jsx(ContextMenu, { items: contextItems, onSelect: onContextSelect, disabled: contextItems.length === 0, "aria-label": "Item actions", children: _jsx("div", { ref: viewportRef, className: "nx-tree__viewport", style: fill ? undefined : { height, maxHeight: height === undefined ? maxHeight : undefined }, tabIndex: !disabled && !empty && !(tabbable && rendered.has(tabbable.key)) ? 0 : -1, onScroll: event => syncRange(event.currentTarget), onFocus: onViewportFocus, onPointerDown: onViewportPointerDown, onClick: onViewportClick, onKeyDown: onViewportKeyDown, children: empty ? (waiting ? (_jsx("div", { className: "nx-tree__list", "aria-hidden": "true", children: SKELETON_WIDTHS.map((width, index) => (_jsxs("div", { className: "nx-tree__row nx-tree__row--skeleton", style: { "--nx-tree-depth": index % 3 === 0 ? 0 : 1 }, children: [_jsx("span", { className: "nx-tree__toggle" }), _jsx("span", { className: "nx-tree__skeleton", style: { width } })] }, index))) })) : (_jsx("p", { className: "nx-tree__empty", children: emptyMessage }))) : (_jsx("div", { role: "tree", className: "nx-tree__list", "aria-labelledby": hasLabel ? labelId : undefined, "aria-label": hasLabel ? undefined : (ariaLabel ?? "Tree"), "aria-describedby": shownMessage || hasContent(hint) ? messageId : undefined, "aria-disabled": disabled || undefined, "aria-readonly": readOnly || undefined, "aria-busy": waiting || undefined, 
                                 // As tall as all of its rows at every moment of a commit, not only once it has finished. A scroll that
                                 // moves the window makes React take the rows that leave it out before it puts the new ones in and sets
                                 // this padding, and a layout in between - Chrome lays the page out inside the removal of a focused row,
                                 // and so may any focusout listener that measures - would find the list short of the scroll position and
                                 // clamp it: a jump to the end came back up to 1,120px (nexus.web, 2026-10-09).
-                                style: { boxSizing: "border-box", minHeight: 2 * PAD + total * rowHeight, paddingTop: PAD + start * rowHeight, paddingBottom: PAD + bottom }, children: body })) }) })] }), (shownMessage || hasContent(hint)) && (_jsx("div", { className: "nx-field__footer", children: _jsxs("p", { id: messageId, className: cx("nx-field__message", shownMessage && "nx-field__message--error"), role: message ? "alert" : undefined, children: [shownMessage && _jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: shownMessage ?? hint })] }) })), name && formValues.map(item => _jsx("input", { type: "hidden", name: name, form: form, disabled: disabled, value: String(item) }, String(item))), lazy && (_jsx("span", { className: "nx-visually-hidden", role: "status", "aria-live": "polite", children: announcement })), readOnlyNotice.notice, lockedNotice.notice, partialNotice.notice] }));
+                                style: { boxSizing: "border-box", minHeight: 2 * PAD + total * rowHeight, paddingTop: PAD + start * rowHeight, paddingBottom: PAD + bottom }, children: body })) }) })] }), (shownMessage || hasContent(hint)) && (_jsx("div", { className: "nx-field__footer", children: _jsxs("p", { id: messageId, className: cx("nx-field__message", shownMessage && "nx-field__message--error"), role: message ? "alert" : undefined, children: [shownMessage && _jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: shownMessage ?? hint })] }) })), name && formValues.map(item => _jsx("input", { type: "hidden", name: name, form: form, disabled: disabled, value: String(item) }, String(item))), lazy && (_jsx("span", { className: "nx-visually-hidden", role: "status", "aria-live": "polite", children: announcement })), readOnlyNotice.notice, lockedNotice.notice, partialNotice.notice, addNotice.notice] }));
 }
 /** The name box of a row being added or renamed. Enter saves, Esc cancels, and leaving it saves. */
 function TreeEditor({ initial, select, maxLength, saving, label, invalid, describedBy, onText, onCommit, onCancel }) {

package/dist/Components/Layouts/MessageBox.d.ts

@@ -5,16 +5,29 @@ import type { PopupSize } from "./Popup.tsx";
 export type MessageTone = "neutral" | "info" | "success" | "warning" | "danger" | "question";
 export interface MessageBoxOptions {
     title: ReactNode;
-    /** Text under the title. */
+    /** Text under the title, in the box's muted text. */
     message?: ReactNode;
+    /**
+     * What the question is about, in full, after the message and in the normal text colour: a record's details
+     * (`<CrudDetails row columns />`), a list. It scrolls with the box's body while the buttons stay in view; give the box a
+     * width that suits it (`size: "lg"` or `"xl"`).
+     */
+    details?: ReactNode;
     /** Colors the icon: `info`, `success`, `warning`, `danger`, `question`. `neutral` shows no icon. */
     tone?: MessageTone;
     /** Replaces the tone's icon; `null` shows none. */
     icon?: ReactNode | null;
     /** Default `sm`. */
     size?: PopupSize;
-    /** The close button, Esc, and a click outside dismiss the box. Default true. */
+    /** The close button and Esc dismiss the box. Default true. */
     closable?: boolean;
+    /**
+     * A click outside dismisses the box. Default: as `closable`. `false` keeps a box with much to read (a question with its
+     * `details`) open through a stray click, while Esc and the close button still dismiss it.
+     */
+    closeOnBackdrop?: boolean;
+    /** Dismisses the box when it aborts, as Esc would: the form or the page that asked has gone. */
+    signal?: AbortSignal;
 }
 export interface MessageBoxButton<T extends string = string> {
     value: T;

package/dist/Components/Layouts/MessageBox.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { iconAlertCircle, iconAlertTriangle, iconCircleCheck, iconHelpCircle, iconInfoCircle, InlineIcon } from "nexus-icons";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { Button } from "../Documents/Button.js";
@@ -14,40 +14,85 @@ const TONE_ICONS = {
     question: iconHelpCircle,
 };
 let promptCounter = 0;
+let messageCounter = 0;
+/*
+ * A held Enter, or one pressed again at once (a double press), never answers a box. The Enter that opened a question (in
+ * a form's box) would otherwise press the Confirm it gave the focus to - by the key's repeat, or by the second tap of a
+ * double press - before anything in the box was read. Any Enter within this long of the one before it is held.
+ */
+const HASTY_ENTER_MS = 300;
+let lastEnterAt = Number.NEGATIVE_INFINITY;
+function holdHastyEnter(event) {
+    if (event.key !== "Enter")
+        return;
+    const gap = event.timeStamp - lastEnterAt;
+    lastEnterAt = event.timeStamp;
+    if (!(event.target instanceof Element) || !event.target.closest(".nx-popup--message"))
+        return;
+    if (event.repeat || gap < HASTY_ENTER_MS)
+        event.preventDefault();
+}
+// Listening from the start: the Enter that opens a box comes before the box.
+if (typeof window !== "undefined")
+    window.addEventListener("keydown", holdHastyEnter, true);
 function toneIcon(tone, icon) {
     if (icon !== undefined)
         return icon;
     const data = TONE_ICONS[tone];
     return data ? _jsx(InlineIcon, { icon: data }) : null;
 }
+/** The muted message, then the details in the normal text colour; each with an id the box is described by. */
+function messageBody(message, details, id) {
+    return (_jsxs(_Fragment, { children: [message && (_jsx("div", { id: `${id}-text`, className: "nx-message__text", children: message })), details && (_jsx("div", { id: `${id}-details`, className: "nx-message__details", children: details }))] }));
+}
+/**
+ * What describes a box to a screen reader: its message and its details, read with the title as the focus enters it, so
+ * a question's Confirm is never reached before what it confirms was heard.
+ */
+function describedBy(message, details, id) {
+    return cx(message ? `${id}-text` : undefined, details ? `${id}-details` : undefined) || undefined;
+}
+/** Dismisses an open box when the signal aborts; nothing is left listening once it has closed. */
+function closeOnAbort(popup, signal) {
+    if (!signal)
+        return;
+    const dismiss = () => popup.close();
+    signal.addEventListener("abort", dismiss, { once: true });
+    void popup.closed.then(() => signal.removeEventListener("abort", dismiss));
+}
 /**
  * A message box with the given buttons. Resolves with the clicked button's value, or `null` when the box was
  * dismissed with the close button, Esc, or a click outside.
  */
 export function showMessageBox(options) {
-    const { title, message, tone = "neutral", icon, size = "sm", closable = true, buttons } = options;
+    const { title, message, details, tone = "neutral", icon, size = "sm", closable = true, closeOnBackdrop = closable, signal, buttons } = options;
+    if (signal?.aborted)
+        return Promise.resolve(null);
     const cautious = tone === "danger" || tone === "warning";
     const explicit = buttons.findIndex(button => button.autoFocus);
     const focusIndex = explicit >= 0 ? explicit : cautious ? 0 : buttons.length - 1;
     let result = null;
+    const id = `nx-message-${++messageCounter}`;
     const popup = openPopup({
         title,
         icon: toneIcon(tone, icon),
         size,
         closable,
-        closeOnBackdrop: closable,
+        closeOnBackdrop,
         closeOnEscape: closable,
         variant: "dialog",
         minimizable: false,
         maximizable: false,
         className: cx("nx-popup--message", `nx-popup--tone-${tone}`),
         initialFocus: "[data-nx-focus]",
-        content: message ? _jsx("div", { className: "nx-message__text", children: message }) : null,
+        "aria-describedby": describedBy(message, details, id),
+        content: message || details ? messageBody(message, details, id) : null,
         footer: handle => buttons.map((button, index) => (_jsx(Button, { variant: button.variant ?? (index === buttons.length - 1 ? (tone === "danger" ? "danger" : "primary") : "secondary"), "data-nx-focus": index === focusIndex || undefined, onClick: () => {
                 result = button.value;
                 handle.close();
             }, children: button.label }, button.value))),
     });
+    closeOnAbort(popup, signal);
     return popup.closed.then(() => result);
 }
 function options(input) {
@@ -72,7 +117,9 @@ function confirm(input) {
 }
 /** A text box with Cancel and OK. Resolves with the text, or `null` when cancelled. */
 function prompt(input) {
-    const { title, message, tone = "neutral", icon, size = "sm", closable = true, label, defaultValue, placeholder, required = true, inputType = "text", confirmLabel, cancelLabel } = options(input);
+    const { title, message, details, tone = "neutral", icon, size = "sm", closable = true, closeOnBackdrop = closable, signal, label, defaultValue, placeholder, required = true, inputType = "text", confirmLabel, cancelLabel } = options(input);
+    if (signal?.aborted)
+        return Promise.resolve(null);
     const formId = `nx-prompt-${++promptCounter}`;
     let result = null;
     const popup = openPopup({
@@ -80,20 +127,22 @@ function prompt(input) {
         icon: toneIcon(tone, icon),
         size,
         closable,
-        closeOnBackdrop: closable,
+        closeOnBackdrop,
         closeOnEscape: closable,
         variant: "dialog",
         minimizable: false,
         maximizable: false,
         className: cx("nx-popup--message", `nx-popup--tone-${tone}`),
         initialFocus: `#${formId} input`,
+        "aria-describedby": describedBy(message, details, formId),
         content: handle => (_jsxs("form", { id: formId, className: "nx-message__form", onSubmit: (event) => {
                 event.preventDefault();
                 result = String(new FormData(event.currentTarget).get("value") ?? "");
                 handle.close();
-            }, children: [message && _jsx("div", { className: "nx-message__text", children: message }), _jsx(TextBox, { name: "value", label: label, type: inputType, defaultValue: defaultValue, placeholder: placeholder, required: required })] })),
+            }, children: [messageBody(message, details, formId), _jsx(TextBox, { name: "value", label: label, type: inputType, defaultValue: defaultValue, placeholder: placeholder, required: required })] })),
         footer: handle => (_jsxs(_Fragment, { children: [_jsx(Button, { onClick: () => handle.close(), children: cancelLabel ?? "Cancel" }), _jsx(Button, { type: "submit", form: formId, variant: "primary", children: confirmLabel ?? "OK" })] })),
     });
+    closeOnAbort(popup, signal);
     return popup.closed.then(() => result);
 }
 /**

package/dist/Components/Layouts/Popup.d.ts

@@ -50,8 +50,9 @@ export interface PopupProps {
     closeOnBackdrop?: boolean;
     /**
      * The minimize button: the popup steps aside to a bar at the bottom right, keeping everything typed in it, and the
-     * page can be used again. Default: when `closable`, since a popup that must be answered cannot be put aside.
-     * Needs `<PopupHost />`, which shows the bars.
+     * page can be used again. Default false: only a popup that asks has it. A CRUD page's Add and Edit forms and its row
+     * forms ask (a form put aside while the list behind it is read); message boxes, viewers, galleries, histories and
+     * the rest do not. Needs `<PopupHost />`, which shows the bars.
      */
     minimizable?: boolean;
     /** The maximize button, and a double-click on the title bar: the popup fills the window. Default true. */
@@ -76,17 +77,23 @@ export interface PopupProps {
     initialFocus?: string;
     /** Name for screen readers when there is no title. */
     "aria-label"?: string;
+    /**
+     * Ids of elements inside the popup that describe it to screen readers, after its `description`: a message box names
+     * its message and its details, so they are read with the title as the focus enters.
+     */
+    "aria-describedby"?: string;
     className?: string;
     children?: ReactNode;
 }
 /**
- * A modal window on the native <dialog>, with the buttons of a desktop window: minimize, maximize, and close. It sits
- * in the top layer above everything, dims and locks the page behind it, traps Tab, closes with Esc or a click outside,
- * and returns focus to where it came from. The title bar moves it; a double-click there maximizes it. Minimized, it
+ * A modal window on the native <dialog>, with the buttons of a desktop window: maximize and close, and minimize when
+ * it asks (`minimizable`: a CRUD page's Add and Edit). It sits in the top layer above everything, dims and locks the
+ * page behind it, traps Tab, closes with Esc or a click outside, and returns focus to where it came from. The title
+ * bar moves it; a double-click there maximizes it. Minimized, it
  * waits as a bar at the bottom right with its content kept, while the page can be used. The body scrolls while the
  * title and the footer stay. The content mounts while the popup is open, so a form inside starts fresh every time.
  *
  * @example
  * <Popup open={open} onClose={() => setOpen(false)} title="Edit booking" footer={<Button variant="primary">Save</Button>}>…</Popup>
  */
-export declare function Popup({ open, onClose, onClosed, title, description, icon, variant, size, footer, closable, closeOnEscape, closeOnBackdrop, minimizable, maximizable, movable, reopen, windowState: windowStateProp, defaultWindowState, onWindowStateChange, flush, initialFocus, "aria-label": ariaLabel, className, children, }: PopupProps): import("react").JSX.Element;
+export declare function Popup({ open, onClose, onClosed, title, description, icon, variant, size, footer, closable, closeOnEscape, closeOnBackdrop, minimizable, maximizable, movable, reopen, windowState: windowStateProp, defaultWindowState, onWindowStateChange, flush, initialFocus, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, className, children, }: PopupProps): import("react").JSX.Element;