nexus-shared 3.1.0 → 3.2.0

package/dist/Helpers/TreeStore.js

@@ -5,7 +5,55 @@
  *
  * Checking a box, the frequent change, updates counts along one path. Adding, renaming, and removing items count
  * the whole tree again, which takes a few milliseconds at 100,000 items.
+ *
+ * With `lazy`, children come later, a page at a time, from whoever loads them (TreeView's `loadChildren`): a node with
+ * none loaded yet can still be expanded, a page joins its parent with counts updated along one path, and `rows` holds
+ * a status row under a parent whose page is on its way, failed, or has more to come. The store never loads anything
+ * itself: the view asks, and tells the store what came back (`beginLoad`, `receivePage`, `failLoad`).
+ */
+import { RequestCache } from "./RequestCache.js";
+/** Children's pages kept for every lazy tree on the page that names a `cacheKey`, for 5 minutes: see `RequestCache`. */
+export const treePages = new RequestCache();
+/** The start of every key a tree keeps its pages under, or one parent's pages (`null`: the top level). */
+export function treePagesKey(cacheKey, parent) {
+    if (parent === undefined)
+        return `${cacheKey}\u0000`;
+    return `${cacheKey}\u0000${treeKey(parent) ?? ""}\u0000`;
+}
+/** The key one page is kept under. */
+export function treePageKey(cacheKey, parent, skip, take) {
+    return `${treePagesKey(cacheKey, parent)}${skip}\u0000${take}`;
+}
+/**
+ * Drops the kept pages of a tree's source - all of them, one parent's (`null`: the top level), or several parents' -
+ * after the records behind them changed elsewhere. Returns how many were dropped. A tree on screen keeps what it shows:
+ * its `refresh()` loads that again.
  */
+export function expireTreePages(cacheKey, parent) {
+    if (!Array.isArray(parent))
+        return treePages.drop(treePagesKey(cacheKey, parent));
+    const base = treePagesKey(cacheKey);
+    const parents = new Set(parent.map(value => treeKey(value) ?? ""));
+    return treePages.drop(key => key.startsWith(base) && parents.has(key.slice(base.length, key.indexOf("\u0000", base.length))));
+}
+/** A has-children field read as the tree reads it: a boolean, or a count above 0; `undefined` when it says nothing. */
+export function treeHasChildren(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value > 0 : undefined;
+    if (typeof value === "string" && value.trim() !== "") {
+        const count = Number(value);
+        return Number.isFinite(count) ? count > 0 : undefined;
+    }
+    return undefined;
+}
+/** The key of a status row: never an item's, since a value's key is never empty and never starts with NUL. */
+const STATUS_KEY = "\u0000";
+/** The key of the status row under a parent (`null`: the top level), as `TreeNode.key` holds it. */
+export function treeStatusKey(parentKey) {
+    return STATUS_KEY + (parentKey ?? "");
+}
 export const TREE_DEFAULT_KEYS = { value: "id", parent: "parentId", label: "label" };
 const read = (item, key) => item[key];
 const defaultDisabled = (item) => read(item, "disabled") === true || read(item, "isDisabled") === true;
@@ -16,7 +64,6 @@ export function treeKey(value) {
         return null;
     return typeof value === "string" || typeof value === "number" ? String(value) : null;
 }
-let nextUid = 1;
 /**
  * A tree built from a flat list. Items whose parent is missing become top-level items, and a loop of parents is
  * broken at the first item of the loop. Siblings keep the order of the list; a repeated value keeps its first item.
@@ -27,12 +74,31 @@ export class TreeStore {
     labelKey;
     cascade;
     valueMode;
+    /** Children come a page at a time from a loader. */
+    lazy;
+    hasChildrenKey;
     isDisabled;
     isChecked;
     roots = [];
-    /** The visible rows in order: top-level items, and the children of every expanded item whose parents are expanded. A new array after each change. */
+    /**
+     * The visible rows in order: top-level items, and the children of every expanded item whose parents are expanded,
+     * with a lazy parent's status row after its children. A new array after each change.
+     */
     rows = [];
+    /** With `lazyRoots`: where the top level's pages stand. `null` when the top level comes from the items. */
+    rootPages = null;
     byKey = new Map();
+    /** The status row of each lazy parent that has had one, by the parent's key ("" for the top level). */
+    statusRows = new Map();
+    /**
+     * With `lazy`: checked values whose items are not loaded yet, or not settled (see `settle`). They stay in the value,
+     * and check their items when the items come, so a saved value is never lost to a page not opened yet.
+     */
+    pending = new Map();
+    /** Whether the checks came from a value rather than from the items' own flags; items that come later follow the same rule. */
+    valueGiven = false;
+    requests = 0;
+    nextUid = 1;
     /** Without `cascade`: checked nodes, nodes that are not locked, and the checked ones among them. */
     checkedNodes = 0;
     openNodes = 0;
@@ -44,8 +110,12 @@ export class TreeStore {
         this.labelKey = options.labelKey ?? TREE_DEFAULT_KEYS.label;
         this.cascade = options.cascade ?? true;
         this.valueMode = options.valueMode ?? "leaves";
+        this.lazy = options.lazy ?? false;
+        this.hasChildrenKey = options.hasChildrenKey;
         this.isDisabled = options.isItemDisabled ?? defaultDisabled;
         this.isChecked = options.isItemChecked ?? defaultChecked;
+        if (this.lazy && options.lazyRoots)
+            this.rootPages = idlePages();
         this.setItems(items, value);
     }
     /** Items in the tree, drafts included. */
@@ -57,9 +127,24 @@ export class TreeStore {
         const key = treeKey(value);
         return key === null ? undefined : this.byKey.get(key);
     }
+    /** The node or status row whose `key` this is: what a view keeps for its focused row. */
+    find(key) {
+        const node = this.byKey.get(key);
+        if (node)
+            return node;
+        if (!key.startsWith(STATUS_KEY))
+            return undefined;
+        const row = this.statusRows.get(key.slice(STATUS_KEY.length));
+        return row && (row.parent === null || this.byKey.get(row.parent.key) === row.parent) ? row : undefined;
+    }
+    /** Where a lazy parent's children stand (`null`: the top level); `undefined` when they do not come from a loader. */
+    pagesOf(parent) {
+        return parent ? parent.pages : (this.rootPages ?? undefined);
+    }
     /**
      * Replaces the items. Expanded items stay expanded. The checked items come from `value` when given, otherwise from
-     * the items' own flags.
+     * the items' own flags. In a lazy tree, an item whose children were loaded keeps them, unless the items now give it
+     * children of their own.
      */
     setItems(items, value) {
         const previous = this.byKey;
@@ -102,6 +187,18 @@ export class TreeStore {
                     reached.add(cut);
             }
         }
+        if (this.lazy) {
+            for (const node of ordered) {
+                // Children given in the items are all of them.
+                if (node.children.length > 0) {
+                    node.pages = loadedPages();
+                    continue;
+                }
+                const before = previous.get(node.key);
+                if (before?.pages)
+                    this.adoptChildren(node, before, byKey);
+            }
+        }
         this.byKey = byKey;
         this.roots = roots;
         const checked = value ? this.keysOf(value) : null;
@@ -110,8 +207,25 @@ export class TreeStore {
             node.depth = node.parent ? node.parent.depth + 1 : 0;
             node.checked = checked ? checked.has(node.key) || this.checkedByParent(node, checked) : this.isChecked(node.item);
         }
+        this.valueGiven = value !== undefined;
+        this.pending = this.lazy && value ? valueMap(value) : new Map();
         this.recount(all);
-        this.rows = visibleRows(roots);
+        this.settleAll();
+        this.rows = this.visibleRows(roots, null);
+    }
+    /** Moves the loaded children (and pages) of a node that is being built again onto its new node. */
+    adoptChildren(node, before, byKey) {
+        node.pages = before.pages;
+        for (const child of before.children) {
+            const moved = preOrder([child]);
+            // A child whose value an item now uses stays behind, with everything under it.
+            if (moved.some(each => byKey.has(each.key)))
+                continue;
+            child.parent = node;
+            node.children.push(child);
+            for (const each of moved)
+                byKey.set(each.key, each);
+        }
     }
     /** Every item in tree order, without drafts. */
     items() {
@@ -131,10 +245,15 @@ export class TreeStore {
         return list;
     }
     // Checking
-    /** The state of a node's box. */
+    /**
+     * The state of a node's box. With `cascade`, a lazy parent whose items are not all loaded is never `checked` - its
+     * unloaded items are not in the value - unless the value names it (`valueMode: "checked"`, where it stands for all).
+     */
     state(node) {
         if (!this.cascade || node.children.length === 0)
             return node.checked ? "checked" : "unchecked";
+        if (node.partial)
+            return this.pending.has(node.key) ? "checked" : node.checkedLeaves > 0 ? "mixed" : "unchecked";
         if (node.checkedLeaves === 0)
             return "unchecked";
         return node.checkedLeaves === node.leaves ? "checked" : "mixed";
@@ -151,15 +270,37 @@ export class TreeStore {
         }
         return { checked, total };
     }
-    /** The checked values, in tree order, following `valueMode`. */
+    /**
+     * The checked values, in tree order, following `valueMode`. In a lazy tree, values whose items are not loaded yet
+     * (or not settled) follow the others, so a saved value survives until its items come.
+     */
     value() {
-        return this.checkedInOrder().map(node => node.value);
+        const list = this.checkedInOrder().map(node => node.value);
+        if (this.pending.size === 0)
+            return list;
+        const listed = new Set(list.map(String));
+        for (const [key, value] of this.pending)
+            if (!listed.has(key))
+                list.push(value);
+        return list;
     }
-    /** The items of the value, in the same order. */
+    /** The items of the value, in the same order. In a lazy tree it holds only the items loaded, so it can be shorter than `value()`. */
     valueItems() {
-        return this.checkedInOrder().map(node => node.item);
+        const nodes = this.checkedInOrder();
+        if (this.pending.size === 0)
+            return nodes.map(node => node.item);
+        const listed = new Set(nodes.map(node => node.key));
+        for (const key of this.pending.keys()) {
+            const node = this.byKey.get(key);
+            if (node && !listed.has(key))
+                nodes.push(node);
+        }
+        return nodes.map(node => node.item);
     }
-    /** Checks exactly these values. Locks do not apply: this is the saved state, not a user's change. Returns whether anything changed. */
+    /**
+     * Checks exactly these values. Locks do not apply: this is the saved state, not a user's change. In a lazy tree a
+     * value whose item is not loaded is kept, and checks the item when it comes. Returns whether anything changed.
+     */
     setValue(values) {
         const keys = this.keysOf(values);
         let changed = false;
@@ -173,26 +314,44 @@ export class TreeStore {
                 changed = true;
             }
         }
+        this.valueGiven = true;
         if (changed)
             this.recount(all);
-        return changed;
+        if (!this.lazy)
+            return changed;
+        const before = [...this.pending.keys()].join(STATUS_KEY);
+        this.pending = valueMap(values);
+        this.settleAll();
+        return changed || [...this.pending.keys()].join(STATUS_KEY) !== before;
     }
     /**
      * What a click on the node's box does. With `cascade` it checks every item under the node that is not locked, or
      * unchecks them when they are all checked already. Returns whether anything changed; nothing does on a locked node.
+     *
+     * In a lazy tree with `cascade`, a node whose items are not all loaded (`partial`) does not change either: a check
+     * stands for everything under it, and the value can only hold the items that were loaded, so checking it would
+     * silently leave the rest out. The items under it whose own items are all loaded can still be checked one by one.
      */
     toggle(node) {
-        if (node.locked)
+        if (node.locked || node.status)
             return false;
         if (!this.cascade)
             return this.setNodeChecked(node, !node.checked);
-        return this.setLeaves(node, node.openChecked < node.openLeaves);
+        return this.setChecked(node, node.openChecked < node.openLeaves);
     }
     /** Checks or unchecks a node; with `cascade`, every item under it that is not locked. Returns whether anything changed. */
     setChecked(node, checked) {
-        if (node.locked)
+        if (node.locked || node.status)
             return false;
-        return this.cascade ? this.setLeaves(node, checked) : this.setNodeChecked(node, checked);
+        if (!this.cascade)
+            return this.setNodeChecked(node, checked);
+        if (node.partial)
+            return false;
+        const changed = this.setLeaves(node, checked);
+        // A parent whose value stood for everything under it ("checked" mode) no longer does once something under it is unchecked.
+        if (changed && !checked)
+            this.dropClaimsAbove(node);
+        return changed;
     }
     /** The state of a "select all" box, over the items that are not locked; `null` when every item is locked. */
     allState() {
@@ -215,12 +374,16 @@ export class TreeStore {
         const state = this.allState();
         return state !== null && this.checkAll(state !== "checked");
     }
-    /** Checks or unchecks every item that is not locked. Returns whether anything changed. */
+    /**
+     * Checks or unchecks every item that is not locked. Returns whether anything changed. In a lazy tree with `cascade`,
+     * a node whose items are not all loaded is passed over and the loaded parts under it are changed; values whose
+     * items are not loaded stay as they are.
+     */
     checkAll(checked) {
         let changed = false;
         if (this.cascade) {
-            for (const root of this.roots)
-                changed = this.setChecked(root, checked) || changed;
+            for (const top of this.settledTops())
+                changed = this.setChecked(top, checked) || changed;
         }
         else {
             for (const node of preOrder(this.roots))
@@ -231,11 +394,22 @@ export class TreeStore {
     // Expanding
     /** Whether every parent of the node is expanded, so the node is a row. */
     isVisible(node) {
+        if (node.status)
+            return this.indexOf(node) >= 0;
         for (let parent = node.parent; parent; parent = parent.parent)
             if (!parent.expanded)
                 return false;
         return this.byKey.get(node.key) === node;
     }
+    /** Whether the node can be expanded: it has children, or (lazy) it may have some not loaded yet. */
+    canExpand(node) {
+        if (node.status)
+            return false;
+        if (node.children.length > 0)
+            return true;
+        const pages = node.pages;
+        return pages !== undefined && (pages.status !== "ready" || pages.hasMore);
+    }
     /** The node's row index, or -1 when it is not a row. */
     indexOf(node) {
         if (this.indexCache?.rows !== this.rows) {
@@ -245,15 +419,15 @@ export class TreeStore {
         }
         return this.indexCache.map.get(node) ?? -1;
     }
-    /** Expands a node. Returns the rows it added, or `null` when no rows changed. */
+    /** Expands a node. Returns the rows it added (a lazy node's status row too), or `null` when no rows changed. */
     expand(node) {
-        if (node.expanded || node.children.length === 0)
+        if (node.expanded || !this.canExpand(node))
             return null;
         node.expanded = true;
         const index = this.isVisible(node) ? this.indexOf(node) : -1;
         if (index < 0)
             return null;
-        const added = visibleRows(node.children);
+        const added = this.visibleRows(node.children, node);
         const before = this.rows;
         this.rows = before.slice(0, index + 1).concat(added, before.slice(index + 1));
         return { at: index + 1, count: added.length, before };
@@ -275,18 +449,22 @@ export class TreeStore {
         this.rows = before.slice(0, index + 1).concat(before.slice(end));
         return { at: index + 1, count: end - index - 1, before };
     }
-    /** Expands every item, or only the first `levels` levels (1 expands the top-level items). */
+    /**
+     * Expands every item, or only the first `levels` levels (1 expands the top-level items). In a lazy tree it opens the
+     * items whose children are loaded, and asks for nothing: a node open on a page still on its way stays open.
+     */
     expandAll(levels = Infinity) {
-        for (const node of this.byKey.values())
-            node.expanded = node.children.length > 0 && node.depth < levels;
-        this.rows = visibleRows(this.roots);
+        for (const node of this.byKey.values()) {
+            node.expanded = node.depth < levels && (node.children.length > 0 || (node.expanded && this.canExpand(node)));
+        }
+        this.rows = this.visibleRows(this.roots, null);
     }
     collapseAll() {
         for (const node of this.byKey.values())
             node.expanded = false;
-        this.rows = visibleRows(this.roots);
+        this.rows = this.visibleRows(this.roots, null);
     }
-    /** Expands these items and their parents, so the items and their children show. */
+    /** Expands these items and their parents, so the items and their children show. In a lazy tree, only items whose children are loaded. */
     expandValues(values) {
         for (const key of this.keysOf(values)) {
             const node = this.byKey.get(key);
@@ -297,7 +475,7 @@ export class TreeStore {
             for (const parent of this.path(node))
                 parent.expanded = true;
         }
-        this.rows = visibleRows(this.roots);
+        this.rows = this.visibleRows(this.roots, null);
     }
     /** The values of the expanded items, in tree order. */
     expandedValues() {
@@ -312,9 +490,122 @@ export class TreeStore {
             return false;
         for (const parent of closed)
             parent.expanded = true;
-        this.rows = visibleRows(this.roots);
+        this.rows = this.visibleRows(this.roots, null);
+        return true;
+    }
+    // Loading children (lazy)
+    /**
+     * Marks a parent's next page as on its way (`null`: the top level) and returns the request's number, which the
+     * answer is given back with. An earlier request still out is forgotten. Returns 0 when the parent has no pages.
+     */
+    beginLoad(parent) {
+        const pages = this.pagesOf(parent);
+        if (!pages || !this.owns(parent))
+            return 0;
+        pages.status = "loading";
+        pages.request = ++this.requests;
+        this.changedPages(parent);
+        return pages.request;
+    }
+    /**
+     * Adds a page of children that `request` asked for, after the ones loaded, and works out what follows: `hasMore`
+     * when the page says, else whether `total` is reached, else whether the page was full (`take` items). Their parent
+     * field is not read: they go under `parent`. A value already in the tree is passed over, so a page that overlaps
+     * the last one adds no row twice. Returns the nodes added and the rows they added (for an animation), or `null` when
+     * the answer is to an older request or the parent is gone.
+     */
+    receivePage(parent, request, page, take) {
+        const pages = this.pagesOf(parent);
+        if (!pages || pages.request !== request || pages.status !== "loading" || !this.owns(parent))
+            return null;
+        const items = Array.isArray(page?.items) ? page.items : [];
+        // A first page leaves nothing old behind it.
+        if (pages.loaded === 0)
+            pages.stale = false;
+        pages.loaded += items.length;
+        if (typeof page.total === "number" && Number.isFinite(page.total))
+            pages.total = page.total;
+        pages.hasMore = morePages(pages, page, items.length, take);
+        pages.status = "ready";
+        const before = this.rows;
+        const added = this.addNodes(parent, items);
+        this.settleAround(parent, added);
+        // A parent that turned out to have no children closes: its chevron goes with its status row.
+        if (parent && parent.children.length === 0 && !this.canExpand(parent))
+            this.collapse(parent);
+        else
+            this.refreshBlock(parent);
+        const at = added.length > 0 && this.rows !== before ? this.indexOf(added[0]) : -1;
+        return { added, change: at >= 0 ? { at, count: added.length, before } : null };
+    }
+    /** The page `request` asked for failed: the parent shows a failed row with Retry. Returns false for an older request. */
+    failLoad(parent, request) {
+        const pages = this.pagesOf(parent);
+        if (!pages || pages.request !== request || pages.status !== "loading" || !this.owns(parent))
+            return false;
+        pages.status = "failed";
+        this.changedPages(parent);
         return true;
     }
+    /**
+     * Replaces a parent's children with fresh pages after a refresh (`request` from `beginLoad`): an item still there
+     * keeps its node - what is expanded and loaded under it - and takes the fresh item; one no longer there goes, and a
+     * value it held waits in the value for its item to come back. Returns false for an older request.
+     */
+    replacePages(parent, request, answers, take) {
+        const pages = this.pagesOf(parent);
+        if (!pages || pages.request !== request || pages.status !== "loading" || !this.owns(parent))
+            return false;
+        const items = answers.flatMap(page => (Array.isArray(page?.items) ? [...page.items] : []));
+        const last = answers[answers.length - 1] ?? { items: [] };
+        pages.loaded = items.length;
+        pages.total = undefined;
+        for (const page of answers)
+            if (typeof page.total === "number" && Number.isFinite(page.total))
+                pages.total = page.total;
+        pages.hasMore = morePages(pages, last, Array.isArray(last.items) ? last.items.length : 0, take);
+        pages.status = "ready";
+        pages.stale = false;
+        const valueBefore = this.value();
+        this.reconcile(parent, items);
+        this.recount(preOrder(this.roots));
+        const valueAfter = new Set(this.value().map(String));
+        for (const value of valueBefore)
+            if (!valueAfter.has(String(value)))
+                this.pending.set(String(value), value);
+        this.settleAll();
+        this.rows = this.visibleRows(this.roots, null);
+        return true;
+    }
+    /**
+     * Marks loaded pages old, for a refresh: every lazy parent (`null`), or a node and everything under it. The view
+     * loads again the ones on screen, and the rest load when next expanded; a page on its way is forgotten, and a node
+     * that had answered with no children may have some now.
+     */
+    markStale(node = null) {
+        if (!this.lazy)
+            return;
+        if (node === null && this.rootPages)
+            this.rootPages = this.stalePages(this.rootPages, null);
+        for (const each of node ? preOrder([node]) : preOrder(this.roots))
+            if (each.pages)
+                each.pages = this.stalePages(each.pages, each);
+        this.recount(preOrder(this.roots));
+        this.rows = this.visibleRows(this.roots, null);
+    }
+    stalePages(pages, owner) {
+        if (pages.status === "loading") {
+            pages.request = ++this.requests;
+            pages.status = pages.loaded > 0 ? "ready" : "idle";
+        }
+        if (pages.status === "idle")
+            return pages;
+        // Nothing loaded under it: it starts again from what its item says.
+        if (owner && owner.children.length === 0)
+            return this.newPages(owner.item);
+        pages.stale = true;
+        return pages;
+    }
     // Changing items
     /**
      * Adds an item under `parent` (at the top level for `null`), as its last child unless `index` is given, and expands
@@ -330,6 +621,9 @@ export class TreeStore {
         node.draft = options.draft ?? false;
         node.parent = parent;
         node.depth = parent ? parent.depth + 1 : 0;
+        // A new item has no children anywhere yet, so a lazy tree has nothing to ask about it.
+        if (this.lazy)
+            node.pages = loadedPages();
         // An item added under a checked leaf starts checked, so its parent stays checked.
         node.checked = Boolean(this.cascade && parent && parent.children.length === 0 && parent.checked);
         const siblings = parent ? parent.children : this.roots;
@@ -338,9 +632,22 @@ export class TreeStore {
         if (parent)
             parent.expanded = true;
         this.recount(preOrder(this.roots));
-        this.rows = visibleRows(this.roots);
+        this.rows = this.visibleRows(this.roots, null);
         return node;
     }
+    /**
+     * Adds many items under `parent` (at the top level for `null`) after its children, in one pass: counts are updated
+     * along one path, not over the whole tree, so a page of 50 joins a tree of 100,000 in well under a millisecond. A
+     * value already in the tree is passed over. The parent is not expanded. Returns the nodes added.
+     */
+    insertMany(parent, items) {
+        if (parent && this.byKey.get(parent.key) !== parent)
+            return [];
+        const added = this.addNodes(parent, items);
+        this.settleAround(parent, added);
+        this.refreshBlock(parent);
+        return added;
+    }
     /**
      * Replaces a node's item, e.g. after a rename, or once a draft is saved and the server gave it an id. The value can
      * change; the parent cannot. Throws on a value another item uses.
@@ -377,19 +684,23 @@ export class TreeStore {
         if (parent && this.cascade && siblings.length === 1)
             parent.checked = this.state(parent) === "checked";
         siblings.splice(index, 1);
-        if (parent && parent.children.length === 0)
+        if (parent && parent.children.length === 0 && !this.canExpand(parent))
             parent.expanded = false;
-        for (const item of removed)
+        for (const item of removed) {
             this.byKey.delete(item.key);
+            this.statusRows.delete(item.key);
+            // A deleted item's value goes with it.
+            this.pending.delete(item.key);
+        }
         node.parent = null;
         this.recount(preOrder(this.roots));
-        this.rows = visibleRows(this.roots);
+        this.rows = this.visibleRows(this.roots, null);
         return removed;
     }
     // Internals
     createNode(item, key) {
         return {
-            uid: nextUid++,
+            uid: this.nextUid++,
             key,
             value: read(item, this.valueKey),
             item,
@@ -408,8 +719,266 @@ export class TreeStore {
             openLeaves: 0,
             openChecked: 0,
             draft: false,
+            pages: this.lazy ? this.newPages(item) : undefined,
+            partial: false,
         };
     }
+    /** A lazy node's pages before anything is asked: none to ask for when its item says it has no children. */
+    newPages(item) {
+        const known = this.hasChildrenKey === undefined ? undefined : treeHasChildren(read(item, this.hasChildrenKey));
+        return known === false ? loadedPages() : idlePages();
+    }
+    /** Whether a parent (`null`: the top level) is still in the tree, so an answer for it applies. */
+    owns(parent) {
+        return parent === null || this.byKey.get(parent.key) === parent;
+    }
+    /** After a parent's pages changed state: its `partial` and counts along its path, and its rows. */
+    changedPages(parent) {
+        if (parent) {
+            const path = this.path(parent).concat(parent);
+            this.count(path, -1);
+            for (let index = path.length - 1; index >= 0; index--)
+                this.aggregate(path[index]);
+            this.count(path, 1);
+        }
+        this.refreshBlock(parent);
+    }
+    /**
+     * Creates nodes for items under a parent, after its children, and updates counts along the parent's path only. A
+     * value already in the tree is passed over.
+     */
+    addNodes(parent, items) {
+        const path = parent ? this.path(parent).concat(parent) : [];
+        this.count(path, -1);
+        const siblings = parent ? parent.children : this.roots;
+        const added = [];
+        for (const item of items) {
+            const key = treeKey(read(item, this.valueKey));
+            if (key === null || this.byKey.has(key))
+                continue;
+            const node = this.createNode(item, key);
+            node.parent = parent;
+            node.depth = parent ? parent.depth + 1 : 0;
+            node.position = siblings.length;
+            node.disabledPath = node.disabled || Boolean(parent?.disabledPath);
+            node.checked = this.arrivalChecked(node);
+            siblings.push(node);
+            this.byKey.set(key, node);
+            this.aggregate(node);
+            added.push(node);
+        }
+        for (let index = path.length - 1; index >= 0; index--)
+            this.aggregate(path[index]);
+        this.count(path, 1);
+        this.count(added, 1);
+        return added;
+    }
+    /** Adds (1) or takes away (-1) nodes' share of the counts kept for a tree without `cascade`. */
+    count(nodes, step) {
+        for (const node of nodes) {
+            if (node.checked)
+                this.checkedNodes += step;
+            if (node.locked)
+                continue;
+            this.openNodes += step;
+            if (node.checked)
+                this.openCheckedNodes += step;
+        }
+    }
+    /** Whether an item that has just come starts checked: its value is waiting, a parent's value stands for it, or its own flag. */
+    arrivalChecked(node) {
+        if (this.pending.has(node.key))
+            return true;
+        if (this.cascade && this.valueMode === "checked" && this.pending.size > 0) {
+            for (let parent = node.parent; parent; parent = parent.parent)
+                if (this.pending.has(parent.key))
+                    return true;
+        }
+        return !this.valueGiven && this.isChecked(node.item);
+    }
+    /**
+     * Whether a waiting value is settled now that its item is here, so the tree's own checks say it all:
+     * - without `cascade`, at once - the item is its own value, and came checked;
+     * - with `cascade`, a parent named in a value of leaves (or of every parent with a checked item) means nothing, as in
+     *   a tree loaded whole;
+     * - with `cascade`, any other waits until everything under its item is loaded: an unloaded item, or a "checked"-mode
+     *   parent that stands for all of its items, loaded or not.
+     */
+    settle(node) {
+        if (!this.pending.has(node.key))
+            return;
+        if (!this.cascade || (node.children.length > 0 && this.valueMode !== "checked") || !node.partial)
+            this.pending.delete(node.key);
+    }
+    settleAll() {
+        if (this.pending.size === 0)
+            return;
+        for (const key of [...this.pending.keys()]) {
+            const node = this.byKey.get(key);
+            if (node)
+                this.settle(node);
+        }
+    }
+    settleAround(parent, added) {
+        if (this.pending.size === 0)
+            return;
+        for (const node of added)
+            this.settle(node);
+        for (let node = parent; node; node = node.parent)
+            this.settle(node);
+    }
+    dropClaimsAbove(node) {
+        if (this.pending.size === 0)
+            return;
+        for (let parent = node.parent; parent; parent = parent.parent)
+            this.pending.delete(parent.key);
+    }
+    /** With `cascade`: the highest nodes whose items are all loaded - the roots, or below a partial node its loaded parts. */
+    settledTops() {
+        const list = [];
+        const stack = [...this.roots].reverse();
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (!node.partial)
+                list.push(node);
+            else
+                for (let index = node.children.length - 1; index >= 0; index--)
+                    stack.push(node.children[index]);
+        }
+        return list;
+    }
+    /**
+     * Fresh items in place of a parent's children: a node whose value is still there is kept (with what is expanded and
+     * loaded under it) and takes the fresh item; one not there goes, unless it is a draft being named.
+     */
+    reconcile(parent, items) {
+        const siblings = parent ? parent.children : this.roots;
+        const old = new Map(siblings.map(node => [node.key, node]));
+        const next = [];
+        for (const item of items) {
+            const key = treeKey(read(item, this.valueKey));
+            if (key === null)
+                continue;
+            const kept = old.get(key);
+            if (kept) {
+                old.delete(key);
+                kept.item = item;
+                kept.value = read(item, this.valueKey);
+                kept.label = labelOf(item, this.labelKey);
+                kept.disabled = this.isDisabled(item);
+                // Nothing loaded under it: what the fresh item says about its children counts.
+                if (kept.children.length === 0 && kept.pages && kept.pages.status !== "loading")
+                    kept.pages = this.newPages(item);
+                next.push(kept);
+            }
+            else if (!this.byKey.has(key)) {
+                const node = this.createNode(item, key);
+                node.parent = parent;
+                node.depth = parent ? parent.depth + 1 : 0;
+                node.checked = this.arrivalChecked(node);
+                this.byKey.set(key, node);
+                next.push(node);
+            }
+        }
+        for (const gone of old.values()) {
+            if (gone.draft) {
+                next.push(gone);
+                continue;
+            }
+            for (const each of preOrder([gone])) {
+                this.byKey.delete(each.key);
+                this.statusRows.delete(each.key);
+            }
+            gone.parent = null;
+        }
+        siblings.splice(0, siblings.length, ...next);
+    }
+    /** Rows again for a parent's block (`null`: every row), when it is expanded and a row: its children's rows and its status row. */
+    refreshBlock(parent) {
+        const before = this.rows;
+        let start = 0;
+        let end = before.length;
+        if (parent) {
+            if (!parent.expanded)
+                return;
+            const index = this.isVisible(parent) ? this.indexOf(parent) : -1;
+            if (index < 0)
+                return;
+            start = index + 1;
+            end = start;
+            while (end < before.length && before[end].depth > parent.depth)
+                end++;
+        }
+        this.rows = before.slice(0, start).concat(this.visibleRows(parent ? parent.children : this.roots, parent), before.slice(end));
+    }
+    /** The rows these nodes show - each node, then the rows of its children when it is expanded - and, in a lazy tree, each expanded parent's status row after its children. `parent` owns `nodes`, for its own status row. */
+    visibleRows(nodes, parent) {
+        const list = [];
+        const stack = [];
+        const own = this.statusRowOf(parent);
+        if (own)
+            stack.push(own);
+        for (let index = nodes.length - 1; index >= 0; index--)
+            stack.push(nodes[index]);
+        while (stack.length > 0) {
+            const node = stack.pop();
+            list.push(node);
+            if (!node.expanded)
+                continue;
+            if (this.lazy) {
+                const status = this.statusRowOf(node);
+                if (status)
+                    stack.push(status);
+            }
+            for (let index = node.children.length - 1; index >= 0; index--)
+                stack.push(node.children[index]);
+        }
+        return list;
+    }
+    /** The status row an expanded parent (`null`: the top level) shows after its children, if its pages need one. */
+    statusRowOf(parent) {
+        if (!this.lazy)
+            return undefined;
+        const pages = this.pagesOf(parent);
+        if (!pages)
+            return undefined;
+        // An open parent not asked yet is about to be: it shows as loading.
+        const kind = pages.status === "loading" || pages.status === "idle" ? "loading" : pages.status === "failed" ? "error" : pages.hasMore ? "more" : null;
+        if (kind === null)
+            return undefined;
+        const parentKey = parent ? parent.key : "";
+        let row = this.statusRows.get(parentKey);
+        if (!row || row.parent !== parent) {
+            // Not built by createNode: the item callbacks (isItemDisabled) are never handed an empty object.
+            row = {
+                uid: this.nextUid++,
+                key: STATUS_KEY + parentKey,
+                value: "",
+                item: EMPTY_ITEM,
+                label: "",
+                parent,
+                children: [],
+                depth: 0,
+                position: 0,
+                disabled: false,
+                disabledPath: false,
+                locked: false,
+                expanded: false,
+                checked: false,
+                leaves: 0,
+                checkedLeaves: 0,
+                openLeaves: 0,
+                openChecked: 0,
+                draft: false,
+                partial: false,
+            };
+            this.statusRows.set(parentKey, row);
+        }
+        row.status = kind;
+        row.depth = parent ? parent.depth + 1 : 0;
+        row.disabledPath = Boolean(parent?.disabledPath);
+        return row;
+    }
     keysOf(values) {
         const keys = new Set();
         for (const value of values) {
@@ -434,51 +1003,53 @@ export class TreeStore {
         for (const node of ordered) {
             node.children.forEach((child, index) => (child.position = index));
             node.disabledPath = node.disabled || Boolean(node.parent?.disabledPath);
+        }
+        for (let index = ordered.length - 1; index >= 0; index--)
+            this.aggregate(ordered[index]);
+        this.checkedNodes = 0;
+        this.openNodes = 0;
+        this.openCheckedNodes = 0;
+        this.count(ordered, 1);
+    }
+    /**
+     * A node's lock, `partial`, and counts, from its own flags and its children's (already worked out): what `recount`
+     * does for every node, and what a page of children does for each node on its parent's path.
+     */
+    aggregate(node) {
+        const pages = node.pages;
+        const own = pages !== undefined && (pages.status !== "ready" || pages.hasMore);
+        if (node.children.length === 0) {
+            node.partial = own;
             node.locked = node.disabledPath;
+            // A lazy node not loaded yet is a leaf whose box cannot be changed with cascade: it shows what the value says.
+            const fixed = node.locked || (this.cascade && own);
+            node.leaves = 1;
+            node.checkedLeaves = node.checked ? 1 : 0;
+            node.openLeaves = fixed ? 0 : 1;
+            node.openChecked = fixed ? 0 : node.checkedLeaves;
+            return;
         }
-        let checkedNodes = 0;
-        let openNodes = 0;
-        let openCheckedNodes = 0;
-        for (let index = ordered.length - 1; index >= 0; index--) {
-            const node = ordered[index];
-            if (node.children.length === 0) {
-                node.leaves = 1;
-                node.checkedLeaves = node.checked ? 1 : 0;
-                node.openLeaves = node.locked ? 0 : 1;
-                node.openChecked = node.locked ? 0 : node.checkedLeaves;
-            }
-            else {
-                let leaves = 0;
-                let checked = 0;
-                let openLeaves = 0;
-                let openChecked = 0;
-                let allLocked = true;
-                for (const child of node.children) {
-                    leaves += child.leaves;
-                    checked += child.checkedLeaves;
-                    openLeaves += child.openLeaves;
-                    openChecked += child.openChecked;
-                    allLocked &&= child.locked;
-                }
-                node.leaves = leaves;
-                node.checkedLeaves = checked;
-                node.openLeaves = openLeaves;
-                node.openChecked = openChecked;
-                // A parent's box follows its items only with cascade; without it, a parent stays free.
-                if (this.cascade)
-                    node.locked ||= allLocked;
-            }
-            if (node.checked)
-                checkedNodes++;
-            if (!node.locked) {
-                openNodes++;
-                if (node.checked)
-                    openCheckedNodes++;
-            }
+        let leaves = 0;
+        let checked = 0;
+        let openLeaves = 0;
+        let openChecked = 0;
+        let allLocked = true;
+        let partial = own;
+        for (const child of node.children) {
+            leaves += child.leaves;
+            checked += child.checkedLeaves;
+            openLeaves += child.openLeaves;
+            openChecked += child.openChecked;
+            allLocked &&= child.locked;
+            partial ||= child.partial;
         }
-        this.checkedNodes = checkedNodes;
-        this.openNodes = openNodes;
-        this.openCheckedNodes = openCheckedNodes;
+        node.leaves = leaves;
+        node.checkedLeaves = checked;
+        node.openLeaves = openLeaves;
+        node.openChecked = openChecked;
+        node.partial = partial;
+        // A parent's box follows its items only with cascade; without it, a parent stays free.
+        node.locked = node.disabledPath || (this.cascade && allLocked);
     }
     /** Sets every open leaf under a node (the node itself for a leaf), updating counts up the path of each leaf that changes. */
     setLeaves(node, checked) {
@@ -537,8 +1108,15 @@ export class TreeStore {
                 // A subtree without a checked leaf adds nothing.
                 if (node.checkedLeaves === 0)
                     continue;
-                if (node.children.length === 0 || mode === "any" || (mode === "checked" && node.checkedLeaves === node.leaves))
+                if (node.partial) {
+                    // Not everything under it is loaded: it is in the value only when the value names it (see `value`), except
+                    // as a parent with a checked item in "any" mode, which it is.
+                    if (mode === "any" && node.children.length > 0)
+                        list.push(node);
+                }
+                else if (node.children.length === 0 || mode === "any" || (mode === "checked" && node.checkedLeaves === node.leaves)) {
                     list.push(node);
+                }
             }
             for (let index = node.children.length - 1; index >= 0; index--)
                 stack.push(node.children[index]);
@@ -546,6 +1124,34 @@ export class TreeStore {
         return list;
     }
 }
+/** Placeholder item of a status row. */
+const EMPTY_ITEM = Object.freeze({});
+function idlePages() {
+    return { status: "idle", loaded: 0, hasMore: true, stale: false, request: 0 };
+}
+/** Pages of a node whose children are all known: given in the items, created here, or none at all. */
+function loadedPages() {
+    return { status: "ready", loaded: 0, hasMore: false, stale: false, request: 0 };
+}
+/** Whether another page follows the one that came with `count` items. A page with nothing in it ends the list, whatever it says. */
+function morePages(pages, page, count, take) {
+    if (count === 0)
+        return false;
+    if (typeof page.hasMore === "boolean")
+        return page.hasMore;
+    if (pages.total !== undefined)
+        return pages.loaded < pages.total;
+    return count >= take;
+}
+function valueMap(values) {
+    const map = new Map();
+    for (const value of values) {
+        const key = treeKey(value);
+        if (key !== null && !map.has(key))
+            map.set(key, value);
+    }
+    return map;
+}
 /** Nodes in tree order: each node, then its children. No recursion, so even a chain 100,000 levels deep works. */
 export function preOrder(nodes) {
     const list = [];
@@ -558,19 +1164,6 @@ export function preOrder(nodes) {
     }
     return list;
 }
-/** The rows these nodes show: each node, then the rows of its children when it is expanded. */
-function visibleRows(nodes) {
-    const list = [];
-    const stack = [...nodes].reverse();
-    while (stack.length > 0) {
-        const node = stack.pop();
-        list.push(node);
-        if (node.expanded)
-            for (let index = node.children.length - 1; index >= 0; index--)
-                stack.push(node.children[index]);
-    }
-    return list;
-}
 function labelOf(item, key) {
     const label = read(item, key);
     return label === null || label === undefined ? "" : String(label);