nexus-shared 3.1.0 → 4.0.0

package/dist/Helpers/TableStore.js

@@ -19,6 +19,7 @@ function initialState(pageSize) {
         matches: 0,
         query: { search: "", sort: null, page: 1, pageSize },
         selected: EMPTY_MAP,
+        picked: null,
         busy: EMPTY_SET,
         flashed: EMPTY_SET,
         hidden: EMPTY_SET,
@@ -103,13 +104,18 @@ export class TableStore {
         if (changes.selected && changes.selected !== previous.selected)
             this.options.onSelectionChange?.(this.getSelected());
     }
-    /** Puts back what was saved on this device (page size, sort, columns), before the first load. Tells nobody. */
-    restore(saved) {
+    /**
+     * Puts back what was saved on this device (page size, sort, columns): before the first load, telling nobody, or, with
+     * `notify`, over a table already shown (another key's settings), its rows shown again in them on the first page.
+     */
+    restore(saved, options = {}) {
         const query = { ...this.state.query };
         if (saved.pageSize && saved.pageSize > 0)
             query.pageSize = saved.pageSize;
         if (saved.sort !== undefined)
             query.sort = saved.sort;
+        if (options.notify)
+            query.page = 1;
         this.state = {
             ...this.state,
             query,
@@ -118,6 +124,8 @@ export class TableStore {
             widths: saved.widths ?? this.state.widths,
             pinned: saved.pinned ?? this.state.pinned,
         };
+        if (options.notify)
+            this.view();
     }
     /* Rows given by the page */
     /** Shows these rows: every row there is. The table searches, sorts, and pages them. */
@@ -127,7 +135,9 @@ export class TableStore {
         this.given = rows;
         this.all = [...rows];
         this.dropMissingSelection();
-        this.view({ status: "ready", error: null, refreshing: false });
+        const picked = this.state.picked;
+        this.view({ status: "ready", error: null, refreshing: false, picked: this.followPicked(this.all, true) });
+        this.pickedChanged(picked);
     }
     /* Loading */
     /**
@@ -151,6 +161,9 @@ export class TableStore {
             this.state = { ...this.state, query: { ...this.state.query, search: "", page: 1 } };
             if (this.state.selected.size)
                 this.set({ selected: EMPTY_MAP });
+            // Another list: the row picked in the one before is not in it.
+            if (this.state.picked)
+                this.pick(null);
         }
         const keepRows = quiet ?? (this.state.status === "ready" && !reset);
         const query = this.state.query;
@@ -197,6 +210,7 @@ export class TableStore {
                 void this.reload({ quiet: true });
                 return;
             }
+            const picked = this.state.picked;
             this.set({
                 status: "ready",
                 refreshing: false,
@@ -207,13 +221,17 @@ export class TableStore {
                 offset: (query.page - 1) * query.pageSize,
                 query,
                 selected: this.refreshSelected(page.rows),
+                picked: this.followPicked(page.rows, false),
             });
+            this.pickedChanged(picked);
             return;
         }
         this.all = page.rows;
         this.given = null;
         this.dropMissingSelection();
-        this.view({ status: "ready", refreshing: false, error: null });
+        const picked = this.state.picked;
+        this.view({ status: "ready", refreshing: false, error: null, picked: this.followPicked(this.all, true) });
+        this.pickedChanged(picked);
     }
     fail(error, seq) {
         if (seq !== this.seq)
@@ -239,6 +257,15 @@ export class TableStore {
             query: page === query.page ? query : { ...query, page },
         });
     }
+    /**
+     * Some columns' values changed while the rows did not: the names a `join` column reads came in. A client table reads
+     * its search text again and searches, filters, sorts and pages anew; a server table draws again. Nothing loads.
+     */
+    refreshValues() {
+        this.texts = new WeakMap();
+        if (this.state.status === "ready")
+            this.view();
+    }
     /** Changes the query: a client table shows it at once, a server table loads it. */
     query(changes) {
         const query = { ...this.state.query, ...changes };
@@ -292,6 +319,9 @@ export class TableStore {
      */
     upsert(row, { at = "start", flash = true } = {}) {
         const key = this.keyOf(row);
+        // The picked record's new copy is the one picked now.
+        const before = this.state.picked;
+        const picked = before && key && this.keyOf(before) === key ? row : before;
         if (this.options.paging === "server") {
             const index = this.state.rows.findIndex(candidate => this.keyOf(candidate) === key);
             const rows = [...this.state.rows];
@@ -306,7 +336,7 @@ export class TableStore {
                 total++;
                 matches++;
             }
-            this.set({ rows, total, matches, selected: this.replaceSelected(key, row), status: "ready" });
+            this.set({ rows, total, matches, selected: this.replaceSelected(key, row), picked, status: "ready" });
         }
         else {
             const index = this.all.findIndex(candidate => this.keyOf(candidate) === key);
@@ -317,8 +347,9 @@ export class TableStore {
             else
                 this.all.push(row);
             this.all = [...this.all];
-            this.view({ selected: this.replaceSelected(key, row), status: "ready" });
+            this.view({ selected: this.replaceSelected(key, row), picked, status: "ready" });
         }
+        this.pickedChanged(before);
         if (flash && key)
             this.flash([key]);
     }
@@ -346,6 +377,9 @@ export class TableStore {
         for (const key of gone)
             selected.delete(key);
         const busy = new Set([...this.state.busy].filter(key => !gone.has(key)));
+        // A picked record that left the list is no longer picked.
+        const before = this.state.picked;
+        const picked = before && gone.has(this.keyOf(before)) ? null : before;
         if (this.options.paging === "server") {
             const rows = this.state.rows.filter(row => !gone.has(this.keyOf(row)));
             const removed = this.state.rows.length - rows.length;
@@ -354,15 +388,18 @@ export class TableStore {
                 total: Math.max(0, this.state.total - removed),
                 matches: Math.max(0, this.state.matches - removed),
                 selected: selected.size === this.state.selected.size ? this.state.selected : selected,
+                picked,
                 busy,
             });
+            this.pickedChanged(before);
             // A short wait lets several removals (a mass action's rows) share one load.
             clearTimeout(this.reloadTimer);
             this.reloadTimer = setTimeout(() => void this.reload({ quiet: true }), 60);
             return;
         }
         this.all = this.all.filter(row => !gone.has(this.keyOf(row)));
-        this.view({ selected: selected.size === this.state.selected.size ? this.state.selected : selected, busy });
+        this.view({ selected: selected.size === this.state.selected.size ? this.state.selected : selected, picked, busy });
+        this.pickedChanged(before);
     }
     /* Selection */
     /** Selects or unselects rows, up to `maxSelection`. Returns how many rows it could not select. */
@@ -431,6 +468,35 @@ export class TableStore {
         this.state = { ...this.state, selected: selected.size ? selected : EMPTY_MAP };
         this.options.onSelectionChange?.(this.getSelected());
     }
+    /* The picked row */
+    /**
+     * Picks a row (`DataTable` `onPick`), or none: the one row whose own records the page shows beside the table. It
+     * follows the record from then on - its newest copy after an upsert, none once it is removed or gone after a load -
+     * and every change is told to `onPickChange`.
+     */
+    pick(row) {
+        const next = row !== null && this.keyOf(row) !== "" ? row : null;
+        if (next === this.state.picked)
+            return;
+        this.set({ picked: next });
+        this.options.onPickChange?.(next);
+    }
+    /**
+     * The picked row as these rows hold it: its newest copy, or none when they are every row there is (`whole`, a client
+     * table) and it is not among them. A server page without it keeps it, since it may be on another page.
+     */
+    followPicked(rows, whole) {
+        const picked = this.state.picked;
+        if (!picked)
+            return null;
+        const key = this.keyOf(picked);
+        return rows.find(row => this.keyOf(row) === key) ?? (whole ? null : picked);
+    }
+    /** Tells the page when a change left another copy of the picked row, or none. */
+    pickedChanged(before) {
+        if (this.state.picked !== before)
+            this.options.onPickChange?.(this.state.picked);
+    }
     /* Rows with an action running, and rows to highlight */
     setBusy(keys, on) {
         const busy = new Set(this.state.busy);

package/dist/Helpers/TreeStore.d.ts

@@ -1,3 +1,4 @@
+import { RequestCache } from "./RequestCache.ts";
 export type TreeValue = string | number;
 /** An item of a tree: any object with a value, a parent value, and a label under the keys the tree is given. */
 export type TreeItem = object;
@@ -25,9 +26,131 @@ export interface TreeStoreOptions<TItem extends TreeItem = TreeItem> {
     cascade?: boolean;
     /** Default `leaves`. Ignored without `cascade`, where the value is every checked item. */
     valueMode?: TreeValueMode;
+    /**
+     * Children come later, a page at a time: a node with none loaded yet can be expanded, and `rows` shows its loading,
+     * failed, or Load more state. A node whose children come in the items counts as loaded. Default false.
+     */
+    lazy?: boolean;
+    /** With `lazy`: the top level comes from the loader too, and the items given (if any) are only a start. Default false. */
+    lazyRoots?: boolean;
+    /**
+     * With `lazy`: the item field saying whether it has children before they are loaded - a boolean, or a count (more
+     * than 0). Without it, or when the field is empty, a node counts as having children until its first page answers.
+     */
+    hasChildrenKey?: string;
+}
+/** A row that is not an item, under a parent of a lazy tree: its page is on its way, failed (Retry), or more can be loaded. */
+export type TreeStatusKind = "loading" | "error" | "more";
+/** Where a lazy parent's children stand: what was asked of the loader, and what it said. */
+export interface TreeChildPages {
+    /** `idle`: nothing asked yet; `loading`: a page is on its way; `failed`: the last page failed; `ready`: answered. */
+    status: "idle" | "loading" | "failed" | "ready";
+    /** Children the loader gave so far, as it counted them: the next page skips this many. */
+    loaded: number;
+    /** All of the parent's children on the server, when the loader said. */
+    total?: number;
+    /** Whether another page follows. */
+    hasMore: boolean;
+    /** A refresh made the pages old: they are drawn until fresh ones replace them. */
+    stale: boolean;
+    /** The request now current; an answer to an older one is ignored. */
+    request: number;
+}
+/** What a lazy tree's loader is asked for: one page of a parent's children. */
+export interface TreeChildrenRequest<TItem extends TreeItem = TreeItem> {
+    /** The item whose children to load, or `null` for the top level. */
+    parent: TItem | null;
+    /** Its value, or `null` for the top level. */
+    parentValue: TreeValue | null;
+    /** Children already loaded: the page starts after them (an API's skip count). */
+    skip: number;
+    /** The most to return: the page size (an API's max count). */
+    take: number;
+    /** Aborted when the tree unmounts before the answer, unless a `cacheKey` keeps the answer for the next tree. */
+    signal: AbortSignal;
+}
+/** One page of children, as the loader answers it. */
+export interface TreeChildrenPage<TItem extends TreeItem = TreeItem> {
+    /** The children, in order. Their parent field is not read: they go under the parent that was asked for. */
+    items: readonly TItem[];
+    /** All of the parent's children on the server: Load more says how many are left. */
+    total?: number;
+    /** Whether another page follows. Default: `total` says so, or the page was full. */
+    hasMore?: boolean;
+}
+/**
+ * A change to one item of a tree's source made somewhere else - a form saved, a record moved to the trash - written into
+ * the pages kept for the tree (`writeTreeChanges`) and into every tree on screen that shows them, so nothing is read
+ * from the server again for it.
+ */
+export type TreeItemChange<TItem extends TreeItem = TreeItem> = {
+    /** Added, changed, or moved: the item as it is now, under the item whose value is `parent` (`null`: the top level). */
+    type: "put";
+    item: TItem;
+    parent: TreeValue | null;
+    /**
+     * Where it was: its parent's value (`null`: the top level), or `false` when it was not in the tree at all - just
+     * added, or back from the trash. Left out when not known: a tree that holds the item knows, and the kept pages are
+     * searched; an item found nowhere then changes no count.
+     */
+    before?: TreeValue | null | false;
+} | {
+    /** Out of the tree - moved to the trash, deleted: the item's value, and its parent's when known. */
+    type: "remove";
+    value: TreeValue;
+    parent?: TreeValue | null;
+};
+/** How a tree reads its items, for changes written from outside it: the same keys the tree is given. */
+export interface TreeChangeRules<TItem extends TreeItem = TreeItem> {
+    /** The item field that holds its value: the tree's `valueKey`. Default `id`. */
+    valueKey?: string;
+    /** The tree's `hasChildrenKey`: a parent's count there goes up and down with its children, and its chevron with it. */
+    hasChildrenKey?: string;
+    /**
+     * The order of siblings, as the server sorts them, so an item added or changed goes where a fresh read would put it.
+     * Without it an added item goes after the children loaded, and a changed one stays where it was.
+     */
+    compare?: (a: TItem, b: TItem) => number;
 }
+/** Children's pages kept for every lazy tree on the page that names a `cacheKey`, for 5 minutes: see `RequestCache`. */
+export declare const treePages: RequestCache<TreeChildrenPage<object>>;
+/** The start of every key a tree keeps its pages under, or one parent's pages (`null`: the top level). */
+export declare function treePagesKey(cacheKey: string, parent?: TreeValue | null): string;
+/** The key one page is kept under. */
+export declare function treePageKey(cacheKey: string, parent: TreeValue | null, skip: number, take: number): string;
+/**
+ * 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 declare function expireTreePages(cacheKey: string, parent?: TreeValue | null | readonly (TreeValue | null)[]): number;
+/**
+ * Writes changes made elsewhere into the pages kept for a tree's source, and into every tree on screen that keeps its
+ * pages under `cacheKey` - so a record saved in a form, moved, or sent to the trash shows in the tree at once, and
+ * leaving the page and coming back reads nothing again for it. Items go where the parent's children are known (see
+ * `TreeStore.placeItem`); a parent whose children were never loaded only counts one more or one fewer, and its first page
+ * comes from the server when it is opened, as it would have anyway.
+ */
+export declare function writeTreeChanges<TItem extends TreeItem>(cacheKey: string, changes: readonly TreeItemChange<TItem>[], rules?: TreeChangeRules<TItem>): void;
+type TreeChangeListener = (changes: readonly TreeItemChange[], rules: TreeChangeRules) => void;
+/** Hears the changes written for `cacheKey`: what a tree on screen does to write them into itself. Returns the way out. */
+export declare function subscribeTreeChanges(cacheKey: string, listener: TreeChangeListener): () => void;
+/**
+ * The kept pages under `cacheKey` with the changes written in (what `writeTreeChanges` does to `treePages`). A parent's
+ * pages are read as one list from its first child, the changes applied to it, and the list written back in pages of the
+ * same size, each with the parent's total - so a tree reading them again, page by page, asks the server for exactly the
+ * children it does not have. A page still on its way for a changed parent is dropped: its answer may predate the change.
+ */
+export declare function patchTreePages<TItem extends TreeItem>(cache: RequestCache<TreeChildrenPage>, cacheKey: string, changes: readonly TreeItemChange<TItem>[], rules?: TreeChangeRules<TItem>): void;
+/** A has-children field read as the tree reads it: a boolean, or a count above 0; `undefined` when it says nothing. */
+export declare function treeHasChildren(value: unknown): boolean | undefined;
+/** The key of the status row under a parent (`null`: the top level), as `TreeNode.key` holds it. */
+export declare function treeStatusKey(parentKey: string | null): string;
 export interface TreeNode<TItem extends TreeItem = TreeItem> {
-    /** A number unique to this node for its whole life, for React keys and element ids. */
+    /**
+     * A number unique to this node in its store for its whole life, for React keys and element ids. Counted per store,
+     * so a tree rendered on the server numbers its rows as the browser does.
+     */
     readonly uid: number;
     /** The value as text: the key in maps, so `7` and `"7"` are the same item. */
     key: string;
@@ -59,6 +182,19 @@ export interface TreeNode<TItem extends TreeItem = TreeItem> {
     openChecked: number;
     /** Being created and not saved yet: not part of the value or the items. */
     draft: boolean;
+    /** With `lazy`: where its children's pages stand. */
+    pages?: TreeChildPages;
+    /**
+     * With `lazy`: not everything under it is loaded yet - its own pages, or a node's under it. With `cascade` such a node
+     * cannot be checked or unchecked as a whole (see `TreeStore.toggle`), and never shows checked unless the value names it.
+     */
+    partial: boolean;
+    /**
+     * Set only on a status row, a row that is not an item: under its `parent` (`null`: the top level) a page is on its
+     * way, failed, or more can be loaded. A status row is in `rows` only - never in `children`, the value, or the items -
+     * and its `item` is an empty object.
+     */
+    status?: TreeStatusKind;
 }
 /** What expanding or collapsing did to the visible rows, for an animation. */
 export interface TreeRowsChange<TItem extends TreeItem = TreeItem> {
@@ -86,12 +222,31 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
     readonly labelKey: string;
     readonly cascade: boolean;
     readonly valueMode: TreeValueMode;
+    /** Children come a page at a time from a loader. */
+    readonly lazy: boolean;
+    private readonly hasChildrenKey;
     private readonly isDisabled;
     private readonly isChecked;
     roots: TreeNode<TItem>[];
-    /** 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: readonly TreeNode<TItem>[];
+    /** With `lazyRoots`: where the top level's pages stand. `null` when the top level comes from the items. */
+    rootPages: TreeChildPages | null;
     private byKey;
+    /** The status row of each lazy parent that has had one, by the parent's key ("" for the top level). */
+    private statusRows;
+    /**
+     * 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.
+     */
+    private pending;
+    /** Whether the checks came from a value rather than from the items' own flags; items that come later follow the same rule. */
+    private valueGiven;
+    private requests;
+    private nextUid;
     /** Without `cascade`: checked nodes, nodes that are not locked, and the checked ones among them. */
     private checkedNodes;
     private openNodes;
@@ -102,33 +257,53 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
     get size(): number;
     /** The node of a value. */
     get(value: TreeValue | null | undefined): TreeNode<TItem> | undefined;
+    /** The node or status row whose `key` this is: what a view keeps for its focused row. */
+    find(key: string): TreeNode<TItem> | undefined;
+    /** Where a lazy parent's children stand (`null`: the top level); `undefined` when they do not come from a loader. */
+    pagesOf(parent: TreeNode<TItem> | null): TreeChildPages | 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: readonly TItem[], value?: readonly TreeValue[]): void;
+    /** Moves the loaded children (and pages) of a node that is being built again onto its new node. */
+    private adoptChildren;
     /** Every item in tree order, without drafts. */
     items(): TItem[];
     /** A node and everything under it, in tree order. */
     subtree(node: TreeNode<TItem>): TreeNode<TItem>[];
     /** The node's parents, the top-level one first. */
     path(node: TreeNode<TItem>): TreeNode<TItem>[];
-    /** 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: TreeNode<TItem>): TreeCheckState;
     /** Checked boxes and all boxes: leaves with `cascade`, every item without it. Drafts count. */
     counts(): {
         checked: number;
         total: number;
     };
-    /** 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(): TreeValue[];
-    /** 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(): TItem[];
-    /** 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: readonly TreeValue[]): boolean;
     /**
      * 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: TreeNode<TItem>): boolean;
     /** Checks or unchecks a node; with `cascade`, every item under it that is not locked. Returns whether anything changed. */
@@ -137,25 +312,65 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
     allState(): TreeCheckState | null;
     /** What a click on a "select all" box does: checks every item that is not locked, or unchecks them all when all are checked. */
     toggleAll(): boolean;
-    /** 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: boolean): boolean;
     /** Whether every parent of the node is expanded, so the node is a row. */
     isVisible(node: TreeNode<TItem>): boolean;
+    /** Whether the node can be expanded: it has children, or (lazy) it may have some not loaded yet. */
+    canExpand(node: TreeNode<TItem>): boolean;
     /** The node's row index, or -1 when it is not a row. */
     indexOf(node: TreeNode<TItem>): number;
-    /** 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: TreeNode<TItem>): TreeRowsChange<TItem> | null;
     /** Collapses a node. Returns the rows it removed, or `null` when no rows changed. */
     collapse(node: TreeNode<TItem>): TreeRowsChange<TItem> | null;
-    /** 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?: number): void;
     collapseAll(): void;
-    /** 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: readonly TreeValue[]): void;
     /** The values of the expanded items, in tree order. */
     expandedValues(): TreeValue[];
     /** Expands the parents of a node so it becomes a row. Returns whether rows changed. */
     reveal(node: TreeNode<TItem>): boolean;
+    /**
+     * 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: TreeNode<TItem> | null): number;
+    /**
+     * 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: TreeNode<TItem> | null, request: number, page: TreeChildrenPage<TItem>, take: number): {
+        added: TreeNode<TItem>[];
+        change: TreeRowsChange<TItem> | null;
+    } | null;
+    /** The page `request` asked for failed: the parent shows a failed row with Retry. Returns false for an older request. */
+    failLoad(parent: TreeNode<TItem> | null, request: number): boolean;
+    /**
+     * 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: TreeNode<TItem> | null, request: number, answers: readonly TreeChildrenPage<TItem>[], take: number): boolean;
+    /**
+     * 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?: TreeNode<TItem> | null): void;
+    private stalePages;
     /**
      * Adds an item under `parent` (at the top level for `null`), as its last child unless `index` is given, and expands
      * the parent. A `draft` is not part of the value or the items until `update` saves it. Throws on a value in use.
@@ -164,6 +379,12 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
         index?: number;
         draft?: boolean;
     }): TreeNode<TItem>;
+    /**
+     * 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: TreeNode<TItem> | null, items: readonly TItem[]): TreeNode<TItem>[];
     /**
      * 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.
@@ -173,12 +394,85 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
     }): void;
     /** Removes a node and everything under it. Returns the removed nodes in tree order. */
     remove(node: TreeNode<TItem>): TreeNode<TItem>[];
+    /**
+     * Writes an item where a change made elsewhere left it (see `TreeItemChange`): in place under the same parent (moved
+     * among its siblings by `compare`), under its new parent when it moved - with what is loaded under it - and in for the
+     * first time when it is new or back. Only where the parent's children are known: given, loaded, or known to be none.
+     * Under a parent never opened it waits for that parent's first page, and one that sorts after the loaded children while
+     * more are to come waits for its page. A lazy parent's `loaded` and `total` follow, so its next page skips the right
+     * number, and so does the count in `hasChildrenKey` on the parent's own item, which its chevron goes by. Returns the
+     * item's node where it is now, or `undefined` when this tree does not show it.
+     */
+    placeItem(item: TItem, parentValue: TreeValue | null, options?: {
+        before?: TreeValue | null | false;
+        compare?: (a: TItem, b: TItem) => number;
+    }): TreeNode<TItem> | undefined;
+    /**
+     * Takes out an item a change made elsewhere took out of the tree - moved to the trash, deleted - with everything under
+     * it. Its parent counts one fewer (its pages' `loaded` and `total`, the count on its item) and loses its chevron when
+     * none are left. An item not loaded here still lowers its parent's counts when `parentValue` names the parent.
+     * Returns the nodes taken out.
+     */
+    removeItem(value: TreeValue, parentValue?: TreeValue | null): TreeNode<TItem>[];
+    /** Whether a parent's children are known here: given in the items, loaded (all or the first pages), or known to be none. */
+    private listsChildren;
+    /**
+     * One child more or fewer under a parent (`null`: the top level): its pages' total, and the count its own item
+     * carries in `hasChildrenKey` - a new copy of the item. A parent never opened reads its children from the new count,
+     * so one that has none left loses its chevron; one whose children were loaded knows already.
+     */
+    private countChild;
     private createNode;
+    /** A lazy node's pages before anything is asked: none to ask for when its item says it has no children. */
+    private newPages;
+    /** Whether a parent (`null`: the top level) is still in the tree, so an answer for it applies. */
+    private owns;
+    /** After a parent's pages changed state: its `partial` and counts along its path, and its rows. */
+    private changedPages;
+    /**
+     * 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.
+     */
+    private addNodes;
+    /** Adds (1) or takes away (-1) nodes' share of the counts kept for a tree without `cascade`. */
+    private count;
+    /** Whether an item that has just come starts checked: its value is waiting, a parent's value stands for it, or its own flag. */
+    private arrivalChecked;
+    /**
+     * 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.
+     */
+    private settle;
+    private settleAll;
+    private settleAround;
+    private dropClaimsAbove;
+    /** With `cascade`: the highest nodes whose items are all loaded - the roots, or below a partial node its loaded parts. */
+    private settledTops;
+    /**
+     * 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.
+     */
+    private reconcile;
+    /** 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. */
+    private refreshBlock;
+    /** 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. */
+    private visibleRows;
+    /** The status row an expanded parent (`null`: the top level) shows after its children, if its pages need one. */
+    private statusRowOf;
     private keysOf;
     /** With `valueMode: "checked"`, a parent in the value stands for all of its items. */
     private checkedByParent;
     /** Locks and counts for every node, given in tree order: parents pass locks down, children pass counts up. */
     private recount;
+    /**
+     * 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.
+     */
+    private aggregate;
     /** Sets every open leaf under a node (the node itself for a leaf), updating counts up the path of each leaf that changes. */
     private setLeaves;
     private setNodeChecked;
@@ -186,3 +480,4 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
 }
 /** Nodes in tree order: each node, then its children. No recursion, so even a chain 100,000 levels deep works. */
 export declare function preOrder<TItem extends TreeItem>(nodes: readonly TreeNode<TItem>[]): TreeNode<TItem>[];
+export {};