nexus-shared 3.0.0 → 3.2.0

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,79 @@ 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;
+}
+/** 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;
+/** 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 +130,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 +170,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 +205,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 +260,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 +327,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.
@@ -174,11 +343,56 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
     /** Removes a node and everything under it. Returns the removed nodes in tree order. */
     remove(node: TreeNode<TItem>): TreeNode<TItem>[];
     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;