nexus-shared 3.1.0 → 3.2.0

package/dist/Components/Inputs/TreeView.js

@@ -1,10 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Icon, iconAlertCircle, iconCheck, iconChevronRight, iconChevronsDown, iconChevronsUp, iconLoader2, iconLock, iconPencil, iconPlus, iconTrash, iconX, InlineIcon, } from "nexus-icons";
-import { isValidElement, useId, useImperativeHandle, useLayoutEffect, useMemo, useReducer, useRef, useState, } from "react";
+import { Icon, iconAlertCircle, iconCheck, iconChevronRight, iconChevronsDown, iconChevronsUp, iconDots, iconLoader2, iconLock, iconPencil, iconPlus, iconTrash, iconX, InlineIcon, } from "nexus-icons";
+import { isValidElement, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useReducer, useRef, useState, } from "react";
 import { afterAnimation } from "../../Helpers/AnimationHelpers.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
-import { TREE_DEFAULT_KEYS, TreeStore, } from "../../Helpers/TreeStore.js";
+import { isPromiseLike, REQUEST_CACHE_LIFETIME } from "../../Helpers/RequestCache.js";
+import { expireTreePages, TREE_DEFAULT_KEYS, 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";
@@ -20,6 +21,9 @@ const OVERSCAN = 12;
 /** Letters typed within this time, in milliseconds, add up to one search for a row. */
 const TYPEAHEAD_DELAY = 600;
 const SKELETON_WIDTHS = ["42%", "58%", "36%", "64%", "48%"];
+/** Children a lazy tree asks for at a time, by default. */
+const CHILD_PAGE_SIZE = 50;
+const NO_ITEMS = [];
 let draftCounter = 0;
 /** A value for an item added in the browser, until a server gives it one. */
 function newTreeValue() {
@@ -38,11 +42,21 @@ const sameItems = (a, b) => a === b || (a.length === b.length && a.every((item,
  * Keys: arrows move and expand, Home and End jump, letters find a row, Space checks, Enter opens, `*` expands the
  * siblings, F2 renames, Delete deletes, Insert adds under the focused row, and Shift+F10 opens the actions menu.
  *
+ * With `loadChildren` the children come from a server, a page at a time, when an item is first expanded: a loading
+ * row while they come, a row that says the page failed with Retry, and Load more with how many are left. Those rows
+ * are rows like the others, reached with the arrows and pressed with Enter or Space. What is loaded stays (collapse
+ * and expand again asks nothing), `cacheKey` shares it with the next tree, and the handle's `refresh` loads again what
+ * is on screen. With `cascade`, an item whose items are not all loaded cannot be checked as a whole: the value can only
+ * hold items that were loaded, so its check would silently leave the rest out.
+ *
  * @example
  * <TreeView label="Permissions" items={permissions} checkable name="actionIds" defaultExpanded={1} isItemDisabled={item => !item.canAssign} />
+ *
+ * <TreeView label="Regions" items={countries} hasChildrenKey="childCount" cacheKey="regions"
+ *   loadChildren={({ parent, skip, take, signal }) => loadRegions(parent, skip, take, signal)} />
  */
 export function TreeView(props) {
-    const { items, 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, 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 generatedId = useId();
     const treeId = id ?? generatedId;
     const labelId = `${treeId}-label`;
@@ -51,7 +65,13 @@ export function TreeView(props) {
     // The store holds the tree outside React. It is built again only when a key or a checking rule changes.
     const disabledRef = useRef(isItemDisabled);
     disabledRef.current = isItemDisabled;
-    const config = [valueKey, parentKey, labelKey, cascade, valueMode].join("
");
+    const items = givenItems ?? NO_ITEMS;
+    const lazy = loadChildren !== undefined;
+    const lazyRoots = lazy && givenItems === undefined;
+    const loadRef = useRef(loadChildren);
+    loadRef.current = loadChildren;
+    // A tree built again (another key or rule) loads its pages again: from the cache when it has a key, so nothing is asked.
+    const config = [valueKey, parentKey, labelKey, cascade, valueMode, lazy, lazyRoots, hasChildrenKey ?? ""].join("
");
     const holderRef = useRef(null);
     // Whether the user (or the handle) changed the checks since the items came, so new items keep them.
     const touchedRef = useRef(false);
@@ -64,6 +84,9 @@ export function TreeView(props) {
             labelKey,
             cascade,
             valueMode,
+            lazy,
+            lazyRoots,
+            hasChildrenKey,
             isItemDisabled: item => (disabledRef.current ? disabledRef.current(item) : read(item, "disabled") === true || read(item, "isDisabled") === true),
         }, value ?? (previous && touchedRef.current ? previous.value() : defaultValue));
         if (previous)
@@ -103,6 +126,14 @@ export function TreeView(props) {
     const [busyKeys, setBusyKeys] = useState(() => new Set());
     const [message, setMessage] = useState(null);
     const [contextKey, setContextKey] = useState(undefined);
+    // What a screen reader hears about pages of children: on their way, in, or failed.
+    const [announcement, setAnnouncement] = useState("");
+    // The focused row as the answers to requests see it: they come after the render that sent them.
+    const focusKeyRef = useRef(focusKey);
+    focusKeyRef.current = focusKey;
+    const mountedRef = useRef(true);
+    // Requests made without a cache are aborted when the tree goes; kept ones are not, since the next tree wants them.
+    const abortRef = useRef(null);
     const panelRef = useRef(null);
     const viewportRef = useRef(null);
     const motionRef = useRef(null);
@@ -118,6 +149,7 @@ 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" });
     // 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) {
@@ -129,15 +161,20 @@ export function TreeView(props) {
     // The value for a form, read again only when something could have changed it.
     const formValues = useMemo(() => (name ? store.value() : []), [name, store, version, items, value]);
     function rowElement(key) {
-        const node = key === null ? undefined : store.get(key);
+        const node = key === null ? undefined : store.find(key);
         return node ? (viewportRef.current?.querySelector(`[data-uid="${node.uid}"]`) ?? null) : null;
     }
+    /** The row an event happened in: an item's, or a status row (loading, failed, Load more). */
     function nodeOfTarget(target) {
-        const row = target instanceof Element ? target.closest(".nx-tree__row[data-key]") : null;
-        return row?.dataset.key === undefined ? undefined : store.get(row.dataset.key);
+        const row = target instanceof Element ? target.closest(".nx-tree__row[data-key], .nx-tree__row[data-status-of]") : null;
+        if (!row)
+            return undefined;
+        if (row.dataset.key !== undefined)
+            return store.get(row.dataset.key);
+        return row.dataset.statusOf === undefined ? undefined : store.find(treeStatusKey(row.dataset.statusOf || null));
     }
     function focusedNode() {
-        const node = focusKey === null ? undefined : store.get(focusKey);
+        const node = focusKey === null ? undefined : store.find(focusKey);
         return node && store.isVisible(node) ? node : undefined;
     }
     // Scrolling and focus
@@ -152,9 +189,33 @@ export function TreeView(props) {
         const next = { start: Math.max(0, first - OVERSCAN), end: last + OVERSCAN };
         if (next.start === current.start && next.end === current.end)
             return;
+        releaseFocusLeaving(viewport, next);
         rangeRef.current = next;
         setRange(next);
     }
+    /**
+     * A focused row that the new window leaves out hands focus to the viewport now, in the event that moves the window,
+     * rather than being taken out of the page still focused in the middle of React's commit. Chrome lays the page out
+     * inside the removal of a focused element, after blur and focusout - and so does any focusout listener that measures -
+     * at a moment when React has taken the leaving rows out but not yet put the new ones in or moved the padding: the list
+     * looked short and the scroll position was clamped, or scroll anchoring moved it to keep a row in place (nexus.web,
+     * 2026-10-09: a jump to the end came back 160-1,120px after a client-side navigation). A name box being edited in
+     * the row lets go too, without saving, as it did when its row unmounted: it comes back focused with its row.
+     */
+    function releaseFocusLeaving(viewport, next) {
+        const active = document.activeElement;
+        if (!(active instanceof HTMLElement) || active === viewport || !viewport.contains(active))
+            return;
+        const node = nodeOfTarget(active);
+        if (!node)
+            return;
+        const index = store.indexOf(node);
+        if (index >= next.start && index < next.end)
+            return;
+        restoringRef.current = true;
+        viewport.focus({ preventScroll: true });
+        restoringRef.current = false;
+    }
     function scrollToIndex(index) {
         const viewport = viewportRef.current;
         if (!viewport || index < 0)
@@ -230,6 +291,7 @@ export function TreeView(props) {
         noteRowRef.current = null;
         readOnlyNotice.hide();
         lockedNotice.hide();
+        partialNotice.hide();
     });
     // An open or close ends when its animation does, or at once when none runs (reduced motion).
     useLayoutEffect(() => {
@@ -242,6 +304,44 @@ export function TreeView(props) {
         }
         return afterAnimation(group, motion.type === "open" ? "nx-tree-open" : "nx-tree-close", () => setMotion(null));
     }, [motion]);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            const controller = abortRef.current;
+            // React's development double run sets the tree up again at once: abort only when it stays gone.
+            queueMicrotask(() => {
+                if (mountedRef.current)
+                    return;
+                controller?.abort();
+                if (abortRef.current === controller)
+                    abortRef.current = null;
+            });
+        };
+    }, []);
+    // 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.
+    useLayoutEffect(() => {
+        if (!lazy)
+            return;
+        const wanted = new Set();
+        if (store.rootPages)
+            wanted.add(null);
+        for (const row of store.rows.slice(Math.min(range.start, store.rows.length), Math.min(range.end, store.rows.length))) {
+            for (let parent = row.parent; parent; parent = parent.parent)
+                wanted.add(parent);
+        }
+        for (const parent of wanted) {
+            const pages = store.pagesOf(parent);
+            if (!pages || pages.status === "loading" || pages.status === "failed" || (parent && !parent.expanded))
+                continue;
+            if (pages.stale)
+                reloadPages(parent);
+            else if (pages.status === "idle")
+                loadNext(parent);
+        }
+    });
     function onPanelFocus() {
         hadFocusRef.current = true;
     }
@@ -253,6 +353,7 @@ export function TreeView(props) {
             hadFocusRef.current = false;
             readOnlyNotice.hide();
             lockedNotice.hide();
+            partialNotice.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.
@@ -329,6 +430,11 @@ export function TreeView(props) {
             showNote(lockedNotice, target);
             return;
         }
+        // Its items are not all loaded: a check would stand for items the value cannot hold.
+        if (cascade && node.partial) {
+            showNote(partialNotice, target);
+            return;
+        }
         if (store.toggle(node))
             afterCheck();
     }
@@ -339,17 +445,20 @@ export function TreeView(props) {
             afterCheck();
     }
     function toggleExpand(node) {
-        if (node.children.length === 0)
+        if (!store.canExpand(node))
             return;
         const edit = editingRef.current;
         if (edit && node.expanded && isInside(store.get(edit.key), node)) {
             void runAfterEdit(() => toggleExpand(node));
             return;
         }
+        // Asked before it opens, so a page the cache has at once opens with its rows in one move.
+        if (!node.expanded)
+            ensureLoaded(node);
         const change = node.expanded ? store.collapse(node) : store.expand(node);
         setMotion(change ? (node.expanded ? openMotion(change) : closeMotion(change)) : null);
         // Focus inside a collapsed item moves up to it.
-        const focused = focusKey === null ? undefined : store.get(focusKey);
+        const focused = focusKey === null ? undefined : store.find(focusKey);
         if (focused && !store.isVisible(focused) && hadFocusRef.current)
             focusNode(node);
         bump();
@@ -372,13 +481,176 @@ export function TreeView(props) {
         }
         bump();
     }
+    // Children from a server (loadChildren)
+    /** The parent an answer is for, found again by its key, since the tree may have been built again meanwhile; `undefined` when it is gone. */
+    function parentByKey(parentKey) {
+        return parentKey === null ? null : store.get(parentKey);
+    }
+    function underName(parent) {
+        return parent ? ` under ${parent.label || "(no name)"}` : "";
+    }
+    function pageSize() {
+        return Math.max(1, Math.floor(childPageSize) || CHILD_PAGE_SIZE);
+    }
+    /** One page: a fresh one the cache keeps (at once), the same request already on its way, or a new one from the loader. */
+    function fetchPage(parent, skip, take) {
+        const load = loadRef.current;
+        const ask = (signal) => load({ parent: parent ? parent.item : null, parentValue: parent ? parent.value : null, skip, take, signal });
+        if (cacheKey) {
+            const key = treePageKey(cacheKey, parent ? parent.value : null, skip, take);
+            return treePages.get(key, ask, cacheLifetime);
+        }
+        abortRef.current ??= new AbortController();
+        return ask(abortRef.current.signal);
+    }
+    /** Asks for a parent's next page (`null`: the top level): the first when nothing is loaded, else the one after the last. */
+    function loadNext(parent) {
+        const pages = store.pagesOf(parent);
+        if (!loadRef.current || !pages || pages.status === "loading" || (pages.status === "ready" && !pages.hasMore))
+            return;
+        const parentKey = parent ? parent.key : null;
+        const skip = pages.loaded;
+        const take = pageSize();
+        const first = skip === 0;
+        const request = store.beginLoad(parent);
+        const where = underName(parent);
+        const done = (page) => {
+            if (!mountedRef.current)
+                return;
+            const current = parentByKey(parentKey);
+            if (current === undefined)
+                return;
+            const result = store.receivePage(current, request, page ?? { items: [] }, take);
+            if (!result)
+                return;
+            if (result.change)
+                setMotion(openMotion(result.change));
+            followStatusFocus(current, result.added);
+            const now = store.pagesOf(current);
+            const count = result.added.length;
+            const of = now?.total !== undefined ? ` (${now.loaded.toLocaleString()} of ${now.total.toLocaleString()})` : "";
+            setAnnouncement(count === 0 && first ? `No items${where}.` : `${count.toLocaleString()} ${count === 1 ? "item" : "items"} loaded${where}${of}.`);
+            bump();
+        };
+        const fail = () => {
+            if (!mountedRef.current)
+                return;
+            const current = parentByKey(parentKey);
+            if (current === undefined || !store.failLoad(current, request))
+                return;
+            setAnnouncement(`Could not load ${first ? "the" : "more"} items${where}.`);
+            bump();
+        };
+        let answer;
+        try {
+            answer = fetchPage(parent, skip, take);
+        }
+        catch {
+            fail();
+            return;
+        }
+        if (!isPromiseLike(answer)) {
+            done(answer);
+            return;
+        }
+        setAnnouncement(`Loading ${first ? "the" : "more"} items${where}…`);
+        bump();
+        answer.then(done, fail);
+    }
+    /** Loads again, after a refresh, the pages a parent had (`null`: the top level), and puts them in place of the old ones. */
+    function reloadPages(parent) {
+        const pages = store.pagesOf(parent);
+        if (!loadRef.current || !pages || pages.status === "loading")
+            return;
+        const parentKey = parent ? parent.key : null;
+        const take = pageSize();
+        const count = Math.max(1, Math.ceil(pages.loaded / take));
+        const request = store.beginLoad(parent);
+        const where = underName(parent);
+        const done = (answers) => {
+            if (!mountedRef.current)
+                return;
+            const current = parentByKey(parentKey);
+            if (current === undefined || !store.replacePages(current, request, answers, take))
+                return;
+            setMotion(null);
+            followStatusFocus(current, []);
+            setAnnouncement(`Items loaded again${where}.`);
+            bump();
+        };
+        const fail = () => {
+            if (!mountedRef.current)
+                return;
+            const current = parentByKey(parentKey);
+            if (current === undefined || !store.failLoad(current, request))
+                return;
+            setAnnouncement(`Could not load the items${where}.`);
+            bump();
+        };
+        let answers;
+        try {
+            answers = Array.from({ length: count }, (_, index) => fetchPage(parent, index * take, take));
+        }
+        catch {
+            fail();
+            return;
+        }
+        if (!answers.some(answer => isPromiseLike(answer))) {
+            done(answers);
+            return;
+        }
+        bump();
+        Promise.all(answers).then(done, fail);
+    }
+    /** What an open parent needs from the loader: its first page, a first page that failed asked again, or its pages again after a refresh. */
+    function ensureLoaded(parent) {
+        const pages = store.pagesOf(parent);
+        if (!pages || pages.status === "loading")
+            return;
+        if (pages.stale)
+            reloadPages(parent);
+        else if (pages.status === "idle" || (pages.status === "failed" && pages.loaded === 0))
+            loadNext(parent);
+    }
+    /** Enter, Space, or a click on a status row: Load more asks for the next page, and a failed row asks again. */
+    function pressStatus(row) {
+        if (disabled)
+            return;
+        const parent = row.parent;
+        const pages = store.pagesOf(parent);
+        if (row.status === "more")
+            loadNext(parent);
+        else if (row.status === "error") {
+            if (pages?.stale)
+                reloadPages(parent);
+            else
+                loadNext(parent);
+        }
+    }
+    /**
+     * Focus on a parent's status row (Load more, Retry, or loading) when its page came moves to the first item it brought,
+     * or back to the parent when nothing came and the row is gone. Focus anywhere else stays where it is.
+     */
+    function followStatusFocus(parent, added) {
+        const key = treeStatusKey(parent ? parent.key : null);
+        if (focusKeyRef.current !== key)
+            return;
+        const status = store.find(key);
+        const next = added[0] ?? (status && store.isVisible(status) ? undefined : (parent ?? store.rows[store.rows.length - 1]));
+        if (!next)
+            return;
+        if (hadFocusRef.current)
+            focusNode(next);
+        else
+            setFocusKey(next.key);
+    }
     // Adding, renaming, deleting
     function allowed(action, node) {
         if (blocked)
             return false;
         if ((action === "create" && !creatable) || (action === "update" && !editable) || (action === "delete" && !deletable))
             return false;
-        if (node && (node.disabledPath || node.draft))
+        if (node && (node.disabledPath || node.draft || node.status))
             return false;
         return canChange ? canChange(action, node ? node.item : null) : true;
     }
@@ -424,6 +696,9 @@ export function TreeView(props) {
             const before = store.rows;
             const draft = { [valueKey]: newTreeValue(), [parentKey]: parent ? parent.value : null, [labelKey]: "" };
             const node = store.insert(parent, draft, { draft: true });
+            // A lazy parent opened by the new item shows its own children too, after it.
+            if (parent && lazy)
+                ensureLoaded(parent);
             const index = store.indexOf(node);
             setMotion(openMotion(wasOpen ? { at: index, count: 1 } : { at: parentIndex + 1, count: store.rows.length - before.length }));
             openEditor({ key: node.key, mode: "create" }, "");
@@ -480,6 +755,9 @@ export function TreeView(props) {
         const edit = editingRef.current;
         if (!edit)
             return true;
+        // The row scrolled out of the window: the box keeps its text, and comes back focused with its row.
+        if (via === "blur" && restoringRef.current)
+            return false;
         if (savingRef.current)
             return false;
         const node = store.get(edit.key);
@@ -603,9 +881,9 @@ export function TreeView(props) {
     }
     // Pointer and keys
     function onViewportPointerDown(event) {
-        // The context menu opens on the row that was pressed, or at the top level on empty space.
+        // 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.key : null);
+        setContextKey(node && !node.status ? node.key : null);
     }
     function onViewportClick(event) {
         const target = event.target;
@@ -617,6 +895,10 @@ export function TreeView(props) {
         setFocusKey(node.key);
         if (disabled)
             return;
+        if (node.status) {
+            pressStatus(node);
+            return;
+        }
         if (target.closest(".nx-tree__toggle")) {
             toggleExpand(node);
             return;
@@ -632,7 +914,7 @@ export function TreeView(props) {
             else
                 onItemClick(node.item);
         }
-        else if (node.children.length > 0) {
+        else if (store.canExpand(node)) {
             toggleExpand(node);
         }
     }
@@ -644,6 +926,7 @@ export function TreeView(props) {
             noteRowRef.current = null;
             readOnlyNotice.hide();
             lockedNotice.hide();
+            partialNotice.hide();
             event.preventDefault();
             return;
         }
@@ -654,6 +937,12 @@ export function TreeView(props) {
         const target = rowElement(node.key) ?? event.currentTarget;
         const page = Math.max(1, Math.floor((viewportRef.current?.clientHeight ?? rowHeight) / rowHeight) - 1);
         const { key, ctrlKey, metaKey, altKey } = event;
+        // A status row is a button: Enter or Space presses Load more or Retry.
+        if (node.status && (key === "Enter" || (key === " " && !ctrlKey && !metaKey))) {
+            pressStatus(node);
+            event.preventDefault();
+            return;
+        }
         let handled = true;
         if (key === "ArrowDown")
             moveTo(index + 1);
@@ -668,7 +957,7 @@ export function TreeView(props) {
         else if (key === "PageUp")
             moveTo(index - page);
         else if (key === "ArrowRight") {
-            if (node.children.length === 0)
+            if (!store.canExpand(node))
                 handled = false;
             else if (!node.expanded)
                 toggleExpand(node);
@@ -690,7 +979,7 @@ export function TreeView(props) {
         else if (key === "Enter") {
             if (onItemClick && !checkable && !node.disabledPath)
                 onItemClick(node.item);
-            else if (node.children.length > 0)
+            else if (store.canExpand(node))
                 toggleExpand(node);
             else if (checkable)
                 toggleCheck(node, target);
@@ -772,6 +1061,8 @@ export function TreeView(props) {
             if (!node)
                 return;
             store.reveal(node);
+            if (!node.expanded)
+                ensureLoaded(node);
             store.expand(node);
             setMotion(null);
             bump();
@@ -823,15 +1114,63 @@ export function TreeView(props) {
             if (node)
                 focusNode(node);
         },
+        refresh: refreshValue => {
+            if (!lazy)
+                return;
+            const node = refreshValue === undefined ? null : store.get(refreshValue);
+            if (refreshValue !== undefined && !node)
+                return;
+            if (cacheKey)
+                expireTreePages(cacheKey, node ? store.subtree(node).map(each => each.value) : undefined);
+            store.markStale(node);
+            setMotion(null);
+            bump();
+        },
     }));
     // Rendering
     const showCounts = checkable && cascade && counts;
     const tabbable = focusedNode() ?? rows[0];
     const rendered = new Set();
+    /** How many siblings a row has: all of them on the server when the loader said, loaded or not. */
+    function setSize(node) {
+        const loaded = node.parent ? node.parent.children.length : store.roots.length;
+        const total = store.pagesOf(node.parent)?.total;
+        return total === undefined ? loaded : Math.max(total, loaded);
+    }
+    /** A row that is not an item: a parent's page on its way, a page that failed (Retry), or Load more. The whole row is the button. */
+    function renderStatusRow(row, ghost) {
+        if (!ghost)
+            rendered.add(row.key);
+        const parent = row.parent;
+        const pages = store.pagesOf(parent);
+        const first = !pages || pages.loaded === 0;
+        const where = underName(parent);
+        const left = row.status === "more" && pages?.total !== undefined ? Math.max(0, pages.total - pages.loaded) : undefined;
+        const leftText = left === undefined ? null : `${left.toLocaleString()} left`;
+        let text;
+        let name;
+        if (row.status === "loading") {
+            text = first ? "Loading…" : "Loading more…";
+            name = `Loading ${first ? "the" : "more"} items${where}`;
+        }
+        else if (row.status === "error") {
+            text = first ? "Could not load the items." : "Could not load more items.";
+            name = `Could not load ${first ? "the" : "more"} items${where}. Retry`;
+        }
+        else {
+            text = "Load more";
+            name = `Load more${where}${leftText ? `, ${leftText}` : ""}`;
+        }
+        return (_jsxs("div", { role: ghost ? undefined : "treeitem", className: cx("nx-tree__row nx-tree__row--status", row.status === "loading" && "nx-tree__row--loading", row.status === "error" && "nx-tree__row--error", row.status === "more" && "nx-tree__row--more"), style: { "--nx-tree-depth": row.depth }, "data-status-of": ghost ? undefined : parent ? parent.key : "", "data-uid": ghost ? undefined : row.uid, tabIndex: ghost ? undefined : !disabled && tabbable === row ? 0 : -1, "aria-level": ghost ? undefined : row.depth + 1, "aria-busy": ghost ? undefined : row.status === "loading" || undefined, "aria-label": ghost ? undefined : name, children: [_jsx("span", { className: "nx-tree__toggle", "aria-hidden": "true" }), _jsx(InlineIcon, { icon: row.status === "loading" ? iconLoader2 : row.status === "error" ? iconAlertCircle : iconDots, className: cx("nx-tree__status-icon", row.status === "loading" && "nx-spin"), "aria-hidden": "true" }), _jsxs("span", { className: "nx-tree__text", "aria-hidden": "true", children: [_jsx("span", { className: "nx-tree__status-text", children: text }), leftText && _jsx("span", { className: "nx-tree__description", children: leftText })] }), row.status === "error" && (_jsx("span", { className: "nx-btn nx-btn--secondary nx-btn--sm nx-tree__retry", "aria-hidden": "true", children: _jsx("span", { className: "nx-btn__label", children: "Retry" }) }))] }, row.uid));
+    }
     function renderRow(node, ghost = false) {
+        if (node.status)
+            return renderStatusRow(node, ghost);
         if (!ghost)
             rendered.add(node.key);
         const hasChildren = node.children.length > 0;
+        const expandable = hasChildren || store.canExpand(node);
+        const childrenLoading = node.pages?.status === "loading";
         const state = checkable ? store.state(node) : null;
         const edit = !ghost && editing?.key === node.key ? editing : null;
         const busy = busyKeys.has(node.key);
@@ -853,10 +1192,10 @@ export function TreeView(props) {
                 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"));
             }
         }
-        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 : (node.parent ? node.parent.children.length : store.roots.length), "aria-posinset": ghost ? undefined : node.position + 1, "aria-expanded": ghost || !hasChildren ? undefined : node.expanded, "aria-checked": ghost || !state ? undefined : state === "mixed" ? "mixed" : state === "checked", "aria-disabled": ghost ? undefined : locked || undefined, "aria-busy": busy || 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: hasChildren && _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"), 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 => {
                             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()] })), 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));
+                        } }) })), 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));
     }
     const end = Math.min(range.end, total);
     const start = Math.min(range.start, end);
@@ -889,15 +1228,25 @@ export function TreeView(props) {
     }
     const allState = checkable ? store.allState() : null;
     const tally = store.counts();
-    const hasParents = store.roots.some(root => root.children.length > 0);
+    const hasParents = store.roots.some(root => root.children.length > 0 || root.expanded);
     const hasLabel = hasContent(label);
     const shownMessage = message ?? (hasContent(error) ? error : null);
-    const empty = total === 0;
-    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 && _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin", "aria-hidden": "true" }), loading && empty
+    // A lazy top level on its way shows the same placeholder rows as `loading`; one that failed shows its row with Retry.
+    const rootPages = store.rootPages;
+    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
                                         ? "Loading…"
                                         : checkable
                                             ? `${tally.checked.toLocaleString()} of ${tally.total.toLocaleString()} selected`
-                                            : `${store.size.toLocaleString()} ${store.size === 1 ? "item" : "items"}`, !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 ? (loading ? (_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": loading || undefined, style: { 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))), readOnlyNotice.notice, lockedNotice.notice] }));
+                                            : `${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, 
+                                // 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] }));
 }
 /** 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 }) {