nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/TreeStore.js

@@ -0,0 +1,577 @@
+/*
+ * The model behind TreeView: nodes built from a flat list of items, checked counts kept up to date as boxes change,
+ * locks, and the list of visible rows. It has no React in it, so a tree of 100,000 items is plain objects and
+ * arrays, and every operation is tested without a browser (scripts/test-tree-store.mts).
+ *
+ * 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.
+ */
+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;
+const defaultChecked = (item) => read(item, "checked") === true || read(item, "isChecked") === true;
+/** The text key of a value, or `null` for no value. */
+export function treeKey(value) {
+    if (value === null || value === undefined || 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.
+ */
+export class TreeStore {
+    valueKey;
+    parentKey;
+    labelKey;
+    cascade;
+    valueMode;
+    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. */
+    rows = [];
+    byKey = new Map();
+    /** Without `cascade`: checked nodes, nodes that are not locked, and the checked ones among them. */
+    checkedNodes = 0;
+    openNodes = 0;
+    openCheckedNodes = 0;
+    indexCache = null;
+    constructor(items = [], options = {}, value) {
+        this.valueKey = options.valueKey ?? TREE_DEFAULT_KEYS.value;
+        this.parentKey = options.parentKey ?? TREE_DEFAULT_KEYS.parent;
+        this.labelKey = options.labelKey ?? TREE_DEFAULT_KEYS.label;
+        this.cascade = options.cascade ?? true;
+        this.valueMode = options.valueMode ?? "leaves";
+        this.isDisabled = options.isItemDisabled ?? defaultDisabled;
+        this.isChecked = options.isItemChecked ?? defaultChecked;
+        this.setItems(items, value);
+    }
+    /** Items in the tree, drafts included. */
+    get size() {
+        return this.byKey.size;
+    }
+    /** The node of a value. */
+    get(value) {
+        const key = treeKey(value);
+        return key === null ? undefined : this.byKey.get(key);
+    }
+    /**
+     * Replaces the items. Expanded items stay expanded. The checked items come from `value` when given, otherwise from
+     * the items' own flags.
+     */
+    setItems(items, value) {
+        const previous = this.byKey;
+        const byKey = new Map();
+        const ordered = [];
+        for (const item of items) {
+            const key = treeKey(read(item, this.valueKey));
+            if (key === null || byKey.has(key))
+                continue;
+            const node = this.createNode(item, key);
+            node.expanded = previous.get(key)?.expanded ?? false;
+            byKey.set(key, node);
+            ordered.push(node);
+        }
+        const roots = [];
+        for (const node of ordered) {
+            const parentKey = treeKey(read(node.item, this.parentKey));
+            const parent = parentKey === null ? undefined : byKey.get(parentKey);
+            if (parent && parent !== node) {
+                node.parent = parent;
+                parent.children.push(node);
+            }
+            else {
+                roots.push(node);
+            }
+        }
+        // Items in a loop of parents are reached from no top-level item: cut each loop at its first item in the list.
+        const reached = new Set(preOrder(roots));
+        if (reached.size < ordered.length) {
+            const position = new Map(ordered.map((node, index) => [node, index]));
+            for (const node of ordered) {
+                if (reached.has(node))
+                    continue;
+                const parent = node.parent;
+                parent.children.splice(parent.children.indexOf(node), 1);
+                node.parent = null;
+                const at = roots.findIndex(root => position.get(root) > position.get(node));
+                roots.splice(at < 0 ? roots.length : at, 0, node);
+                for (const cut of preOrder([node]))
+                    reached.add(cut);
+            }
+        }
+        this.byKey = byKey;
+        this.roots = roots;
+        const checked = value ? this.keysOf(value) : null;
+        const all = preOrder(roots);
+        for (const node of all) {
+            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.recount(all);
+        this.rows = visibleRows(roots);
+    }
+    /** Every item in tree order, without drafts. */
+    items() {
+        return preOrder(this.roots)
+            .filter(node => !node.draft)
+            .map(node => node.item);
+    }
+    /** A node and everything under it, in tree order. */
+    subtree(node) {
+        return preOrder([node]);
+    }
+    /** The node's parents, the top-level one first. */
+    path(node) {
+        const list = [];
+        for (let parent = node.parent; parent; parent = parent.parent)
+            list.unshift(parent);
+        return list;
+    }
+    // Checking
+    /** The state of a node's box. */
+    state(node) {
+        if (!this.cascade || node.children.length === 0)
+            return node.checked ? "checked" : "unchecked";
+        if (node.checkedLeaves === 0)
+            return "unchecked";
+        return node.checkedLeaves === node.leaves ? "checked" : "mixed";
+    }
+    /** Checked boxes and all boxes: leaves with `cascade`, every item without it. Drafts count. */
+    counts() {
+        if (!this.cascade)
+            return { checked: this.checkedNodes, total: this.byKey.size };
+        let checked = 0;
+        let total = 0;
+        for (const root of this.roots) {
+            checked += root.checkedLeaves;
+            total += root.leaves;
+        }
+        return { checked, total };
+    }
+    /** The checked values, in tree order, following `valueMode`. */
+    value() {
+        return this.checkedInOrder().map(node => node.value);
+    }
+    /** The items of the value, in the same order. */
+    valueItems() {
+        return this.checkedInOrder().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. */
+    setValue(values) {
+        const keys = this.keysOf(values);
+        let changed = false;
+        const all = preOrder(this.roots);
+        for (const node of all) {
+            if (this.cascade && node.children.length > 0)
+                continue;
+            const checked = keys.has(node.key) || this.checkedByParent(node, keys);
+            if (node.checked !== checked) {
+                node.checked = checked;
+                changed = true;
+            }
+        }
+        if (changed)
+            this.recount(all);
+        return changed;
+    }
+    /**
+     * 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.
+     */
+    toggle(node) {
+        if (node.locked)
+            return false;
+        if (!this.cascade)
+            return this.setNodeChecked(node, !node.checked);
+        return this.setLeaves(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)
+            return false;
+        return this.cascade ? this.setLeaves(node, checked) : this.setNodeChecked(node, checked);
+    }
+    /** The state of a "select all" box, over the items that are not locked; `null` when every item is locked. */
+    allState() {
+        let open = this.openNodes;
+        let checked = this.openCheckedNodes;
+        if (this.cascade) {
+            open = 0;
+            checked = 0;
+            for (const root of this.roots) {
+                open += root.openLeaves;
+                checked += root.openChecked;
+            }
+        }
+        if (open === 0)
+            return null;
+        return checked === 0 ? "unchecked" : checked === open ? "checked" : "mixed";
+    }
+    /** 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() {
+        const state = this.allState();
+        return state !== null && this.checkAll(state !== "checked");
+    }
+    /** Checks or unchecks every item that is not locked. Returns whether anything changed. */
+    checkAll(checked) {
+        let changed = false;
+        if (this.cascade) {
+            for (const root of this.roots)
+                changed = this.setChecked(root, checked) || changed;
+        }
+        else {
+            for (const node of preOrder(this.roots))
+                changed = (!node.locked && this.setNodeChecked(node, checked)) || changed;
+        }
+        return changed;
+    }
+    // Expanding
+    /** Whether every parent of the node is expanded, so the node is a row. */
+    isVisible(node) {
+        for (let parent = node.parent; parent; parent = parent.parent)
+            if (!parent.expanded)
+                return false;
+        return this.byKey.get(node.key) === node;
+    }
+    /** The node's row index, or -1 when it is not a row. */
+    indexOf(node) {
+        if (this.indexCache?.rows !== this.rows) {
+            const map = new Map();
+            this.rows.forEach((row, index) => map.set(row, index));
+            this.indexCache = { rows: this.rows, map };
+        }
+        return this.indexCache.map.get(node) ?? -1;
+    }
+    /** Expands a node. Returns the rows it added, or `null` when no rows changed. */
+    expand(node) {
+        if (node.expanded || node.children.length === 0)
+            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 before = this.rows;
+        this.rows = before.slice(0, index + 1).concat(added, before.slice(index + 1));
+        return { at: index + 1, count: added.length, before };
+    }
+    /** Collapses a node. Returns the rows it removed, or `null` when no rows changed. */
+    collapse(node) {
+        if (!node.expanded)
+            return null;
+        node.expanded = false;
+        const index = this.isVisible(node) ? this.indexOf(node) : -1;
+        if (index < 0)
+            return null;
+        const before = this.rows;
+        let end = index + 1;
+        while (end < before.length && before[end].depth > node.depth)
+            end++;
+        if (end === index + 1)
+            return null;
+        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). */
+    expandAll(levels = Infinity) {
+        for (const node of this.byKey.values())
+            node.expanded = node.children.length > 0 && node.depth < levels;
+        this.rows = visibleRows(this.roots);
+    }
+    collapseAll() {
+        for (const node of this.byKey.values())
+            node.expanded = false;
+        this.rows = visibleRows(this.roots);
+    }
+    /** Expands these items and their parents, so the items and their children show. */
+    expandValues(values) {
+        for (const key of this.keysOf(values)) {
+            const node = this.byKey.get(key);
+            if (!node)
+                continue;
+            if (node.children.length > 0)
+                node.expanded = true;
+            for (const parent of this.path(node))
+                parent.expanded = true;
+        }
+        this.rows = visibleRows(this.roots);
+    }
+    /** The values of the expanded items, in tree order. */
+    expandedValues() {
+        return preOrder(this.roots)
+            .filter(node => node.expanded && node.children.length > 0)
+            .map(node => node.value);
+    }
+    /** Expands the parents of a node so it becomes a row. Returns whether rows changed. */
+    reveal(node) {
+        const closed = this.path(node).filter(parent => !parent.expanded);
+        if (closed.length === 0)
+            return false;
+        for (const parent of closed)
+            parent.expanded = true;
+        this.rows = visibleRows(this.roots);
+        return true;
+    }
+    // Changing items
+    /**
+     * 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.
+     */
+    insert(parent, item, options = {}) {
+        const key = treeKey(read(item, this.valueKey));
+        if (key === null)
+            throw new Error("TreeStore.insert: the item has no value.");
+        if (this.byKey.has(key))
+            throw new Error(`TreeStore.insert: the value "${key}" is in use.`);
+        const node = this.createNode(item, key);
+        node.draft = options.draft ?? false;
+        node.parent = parent;
+        node.depth = parent ? parent.depth + 1 : 0;
+        // 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;
+        siblings.splice(Math.max(0, Math.min(options.index ?? siblings.length, siblings.length)), 0, node);
+        this.byKey.set(key, node);
+        if (parent)
+            parent.expanded = true;
+        this.recount(preOrder(this.roots));
+        this.rows = visibleRows(this.roots);
+        return node;
+    }
+    /**
+     * 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.
+     */
+    update(node, item, options = {}) {
+        const key = treeKey(read(item, this.valueKey));
+        if (key === null)
+            throw new Error("TreeStore.update: the item has no value.");
+        const other = this.byKey.get(key);
+        if (other && other !== node)
+            throw new Error(`TreeStore.update: the value "${key}" is in use.`);
+        this.byKey.delete(node.key);
+        node.key = key;
+        node.value = read(item, this.valueKey);
+        node.item = item;
+        node.label = labelOf(item, this.labelKey);
+        node.draft = options.draft ?? false;
+        this.byKey.set(key, node);
+        const disabled = this.isDisabled(item);
+        if (disabled !== node.disabled) {
+            node.disabled = disabled;
+            this.recount(preOrder(this.roots));
+        }
+    }
+    /** Removes a node and everything under it. Returns the removed nodes in tree order. */
+    remove(node) {
+        const parent = node.parent;
+        const siblings = parent ? parent.children : this.roots;
+        const index = siblings.indexOf(node);
+        if (index < 0)
+            return [];
+        const removed = preOrder([node]);
+        // A parent that loses its last child becomes a leaf, checked when all of its items were.
+        if (parent && this.cascade && siblings.length === 1)
+            parent.checked = this.state(parent) === "checked";
+        siblings.splice(index, 1);
+        if (parent && parent.children.length === 0)
+            parent.expanded = false;
+        for (const item of removed)
+            this.byKey.delete(item.key);
+        node.parent = null;
+        this.recount(preOrder(this.roots));
+        this.rows = visibleRows(this.roots);
+        return removed;
+    }
+    // Internals
+    createNode(item, key) {
+        return {
+            uid: nextUid++,
+            key,
+            value: read(item, this.valueKey),
+            item,
+            label: labelOf(item, this.labelKey),
+            parent: null,
+            children: [],
+            depth: 0,
+            position: 0,
+            disabled: this.isDisabled(item),
+            disabledPath: false,
+            locked: false,
+            expanded: false,
+            checked: false,
+            leaves: 1,
+            checkedLeaves: 0,
+            openLeaves: 0,
+            openChecked: 0,
+            draft: false,
+        };
+    }
+    keysOf(values) {
+        const keys = new Set();
+        for (const value of values) {
+            const key = treeKey(value);
+            if (key !== null)
+                keys.add(key);
+        }
+        return keys;
+    }
+    /** With `valueMode: "checked"`, a parent in the value stands for all of its items. */
+    checkedByParent(node, keys) {
+        if (!this.cascade || this.valueMode !== "checked")
+            return false;
+        for (let parent = node.parent; parent; parent = parent.parent)
+            if (keys.has(parent.key))
+                return true;
+        return false;
+    }
+    /** Locks and counts for every node, given in tree order: parents pass locks down, children pass counts up. */
+    recount(ordered) {
+        this.roots.forEach((root, index) => (root.position = index));
+        for (const node of ordered) {
+            node.children.forEach((child, index) => (child.position = index));
+            node.disabledPath = node.disabled || Boolean(node.parent?.disabledPath);
+            node.locked = node.disabledPath;
+        }
+        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++;
+            }
+        }
+        this.checkedNodes = checkedNodes;
+        this.openNodes = openNodes;
+        this.openCheckedNodes = openCheckedNodes;
+    }
+    /** 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) {
+        let changed = false;
+        const stack = [node];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            // A subtree that is locked, or already all checked or all unchecked, has nothing to change.
+            if (current.locked || current.openChecked === (checked ? current.openLeaves : 0))
+                continue;
+            if (current.children.length > 0) {
+                for (const child of current.children)
+                    stack.push(child);
+                continue;
+            }
+            current.checked = checked;
+            const step = checked ? 1 : -1;
+            for (let path = current; path; path = path.parent) {
+                path.checkedLeaves += step;
+                path.openChecked += step;
+            }
+            changed = true;
+        }
+        return changed;
+    }
+    setNodeChecked(node, checked) {
+        if (node.checked === checked)
+            return false;
+        node.checked = checked;
+        const step = checked ? 1 : -1;
+        this.checkedNodes += step;
+        if (!node.locked)
+            this.openCheckedNodes += step;
+        if (node.children.length === 0) {
+            for (let path = node; path; path = path.parent) {
+                path.checkedLeaves += step;
+                if (!node.locked)
+                    path.openChecked += step;
+            }
+        }
+        return true;
+    }
+    checkedInOrder() {
+        const list = [];
+        const mode = this.cascade ? this.valueMode : null;
+        const stack = [...this.roots].reverse();
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (node.draft)
+                continue;
+            if (mode === null) {
+                if (node.checked)
+                    list.push(node);
+            }
+            else {
+                // 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))
+                    list.push(node);
+            }
+            for (let index = node.children.length - 1; index >= 0; index--)
+                stack.push(node.children[index]);
+        }
+        return list;
+    }
+}
+/** 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 = [];
+    const stack = [...nodes].reverse();
+    while (stack.length > 0) {
+        const node = stack.pop();
+        list.push(node);
+        for (let index = node.children.length - 1; index >= 0; index--)
+            stack.push(node.children[index]);
+    }
+    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);
+}