@accelint/design-toolkit 9.9.2 → 9.11.0

package/dist/hooks/use-tree/actions/cache.js

@@ -13,24 +13,69 @@
 
 //#region src/hooks/use-tree/actions/cache.ts
 /**
-* This is a cache created only for performance reasons and is considered
-* to be only a temporary mirror of the data. The data is *always* correct
-* cache should be updated according to the data, only. If the data and
-* the cache do not match, the cache is invalidated and rebuilt.
+* Performance-optimized cache for tree node operations.
 *
-* This will initialize once on load with data, then
-* updated with each tree operation.
+* Maintains a flat lookup map and roots array for O(1) node access. The cache
+* is a temporary mirror of tree data and must stay synchronized with the source
+* tree structure. If inconsistencies occur, the cache is invalidated and rebuilt.
+*
+* Initializes once on construction with tree data, then updates incrementally
+* with each tree operation (add, move, delete, select).
+*
+* @template T - The type of data stored in tree nodes.
+*
+* @example
+* ```typescript
+* const cache = new Cache<UserData>(initialNodes);
+*
+* // Get a node
+* const node = cache.getNode('node-1');
+*
+* // Update selection
+* cache.cascadeSelection('node-1', true);
+*
+* // Rebuild tree structure
+* const tree = cache.toTree();
+* ```
 */
 var Cache = class {
 	cache = {
 		lookup: /* @__PURE__ */ new Map(),
 		roots: []
 	};
+	/**
+	* Creates a new cache instance and populates it with tree nodes.
+	*
+	* @param nodes - Initial tree nodes to cache (defaults to empty array).
+	*
+	* @example
+	* ```typescript
+	* const cache = new Cache(treeData);
+	* ```
+	*/
 	constructor(nodes = []) {
 		this.rebuild(nodes);
 	}
 	/**
-	* Recursively creates the cache object from tree data
+	* Rebuilds the entire cache from tree nodes.
+	*
+	* Recursively flattens the tree structure into a lookup map and roots array.
+	* Initializes all node properties with defaults (isDisabled: false, isExpanded: false, etc.)
+	* and converts nested children to key references. After rebuilding, recomputes visibility
+	* for all nodes based on ancestor state.
+	*
+	* Called automatically in the constructor and whenever external tree state changes.
+	* This is an expensive operation - prefer incremental cache updates when possible.
+	*
+	* @param nodes - Tree nodes to build cache from.
+	* @param lookup - Internal lookup map (used for recursion, typically omitted).
+	* @param parentKey - Parent key for current recursion level (used for recursion, typically omitted).
+	*
+	* @example
+	* ```typescript
+	* // Rebuild cache from new tree data
+	* cache.rebuild(newTreeNodes);
+	* ```
 	*/
 	rebuild(nodes, lookup = /* @__PURE__ */ new Map(), parentKey = null) {
 		nodes.forEach((node) => {
@@ -41,6 +86,7 @@ var Cache = class {
 				isSelected: false,
 				isVisible: false,
 				isVisibleComputed: false,
+				isIndeterminate: false,
 				...rest,
 				parentKey,
 				...children ? { children: children.map((child) => child.key) } : {}
@@ -55,17 +101,43 @@ var Cache = class {
 		this.deriveVisibility();
 		return cache;
 	}
+	/**
+	* Retrieves a cache node by key.
+	*
+	* @param key - The node key to retrieve.
+	* @returns The cached node.
+	* @throws {Error} If key is null/undefined or doesn't exist in cache.
+	*/
 	get(key) {
+		if (key == null) throw new Error(`Key is ${key} (null/undefined) - this is invalid`);
 		const node = this.cache.lookup.get(key);
 		if (node === void 0) throw new Error(`Key of ${key} does not exist in tree`);
 		return node;
 	}
+	/**
+	* Updates a cache node by key.
+	*
+	* @param key - The node key to update.
+	* @param node - The cache node data to store.
+	*/
 	set(key, node) {
 		this.cache.lookup.set(key, node);
 	}
+	/**
+	* Removes a node from the cache lookup.
+	*
+	* @param key - The node key to remove.
+	*/
 	delete(key) {
 		this.cache.lookup.delete(key);
 	}
+	/**
+	* Adds a child key to a parent's children array at a specific index.
+	*
+	* @param parentKey - The parent node key.
+	* @param childKey - The child node key to add.
+	* @param idx - The index position within parent's children.
+	*/
 	addToParent(parentKey, childKey, idx) {
 		const parent = this.get(parentKey);
 		const child = this.get(childKey);
@@ -81,6 +153,12 @@ var Cache = class {
 			children
 		});
 	}
+	/**
+	* Adds a node key to the roots array at a specific index.
+	*
+	* @param key - The node key to add to roots.
+	* @param idx - The index position within roots array.
+	*/
 	addToRoot(key, idx) {
 		const node = this.get(key);
 		const index = Math.max(0, idx);
@@ -90,6 +168,12 @@ var Cache = class {
 		});
 		this.cache.roots.splice(index, 0, key);
 	}
+	/**
+	* Removes a child key from a parent's children array.
+	*
+	* @param parentKey - The parent node key.
+	* @param childKey - The child node key to remove.
+	*/
 	removeFromParent(parentKey, childKey) {
 		const parent = this.get(parentKey);
 		const child = this.get(childKey);
@@ -102,6 +186,11 @@ var Cache = class {
 			children: parent.children?.filter((key) => key !== childKey)
 		});
 	}
+	/**
+	* Removes a node key from the roots array.
+	*
+	* @param key - The node key to remove from roots.
+	*/
 	removeFromRoot(key) {
 		const node = this.get(key);
 		const idx = this.cache.roots.indexOf(key);
@@ -113,6 +202,13 @@ var Cache = class {
 			this.cache.roots.splice(idx, 1);
 		}
 	}
+	/**
+	* Calculates parent key and index for positioning relative to a target.
+	*
+	* @param target - The target node key, or null for root level.
+	* @param position - Whether positioning before or after target.
+	* @returns Object with parentKey and index for insertion.
+	*/
 	parentOrSibling(target, position) {
 		let index;
 		let parentKey = null;
@@ -130,6 +226,11 @@ var Cache = class {
 			index
 		};
 	}
+	/**
+	* Recursively updates computed visibility for a node and all descendants.
+	*
+	* @param key - The node key to traverse from.
+	*/
 	traverse(key) {
 		const node = this.get(key);
 		this.cache.lookup.set(key, {
@@ -138,6 +239,12 @@ var Cache = class {
 		});
 		node.children?.map((child) => this.traverse(child));
 	}
+	/**
+	* Calculates if a node is actually visible based on all ancestors' visibility.
+	*
+	* @param key - The node key to calculate visibility for.
+	* @returns True if node and all ancestors have isVisible: true.
+	*/
 	calculateVisibility(key) {
 		let current = this.get(key);
 		const ancestry = [current];
@@ -148,13 +255,20 @@ var Cache = class {
 		}
 		return ancestry.every((n) => n.isVisible);
 	}
+	/**
+	* Recomputes visibility for all nodes in the tree.
+	*/
 	deriveVisibility() {
 		return this.cache.roots.map((key) => this.traverse(key));
 	}
 	/**
-	* Recursively builds a TreeNode from a key
+	* Recursively builds a TreeNode from a cache key.
+	*
+	* Converts the flat cache representation back into nested TreeNode structure
+	* by recursively building child nodes from child keys.
 	*
-	* @param key
+	* @param key - The node key to build from.
+	* @returns Complete TreeNode with nested children.
 	*/
 	buildNode(key) {
 		const node = this.get(key);
@@ -169,13 +283,22 @@ var Cache = class {
 		};
 	}
 	/**
-	* Builds a tree structure from cache
+	* Rebuilds the tree structure from the flattened cache.
+	*
+	* Converts the internal flat lookup map back into hierarchical TreeNode objects.
+	* Optionally recomputes visibility state based on ancestor expansion before building.
+	*
+	* @param deriveVisible - If true, recomputes visibility for all nodes based on ancestry before building.
+	* @returns Array of root TreeNode objects with nested children.
 	*
-	* TODO: optimization - rebuild only from change to root
-	* Rebuild only from the changed node up the tree to avoid
-	* rebuilding the entire tree
+	* @example
+	* ```typescript
+	* // Build tree with current visibility
+	* const tree = cache.toTree();
 	*
-	* @param deriveVisible boolean - if true, will recompute visibility for nodes based on ancestry
+	* // Build tree and recompute visibility
+	* const tree = cache.toTree(true);
+	* ```
 	*/
 	toTree(deriveVisible) {
 		if (deriveVisible) this.deriveVisibility();
@@ -183,9 +306,25 @@ var Cache = class {
 	}
 	/**
 	* CACHE FUNCTIONS
-	* These manage cache operations. No cache operations should ever be done
-	* outside this file.
+	* These are the public functions to manage cache operations. No cache operations should ever be done
+	* outside this file since it risks corruption of the data.
 	**/
+	/**
+	* Retrieves a node from cache and builds its full TreeNode representation.
+	*
+	* Differs from internal `get()` by recursively building child nodes into
+	* full TreeNode objects instead of returning just child keys.
+	*
+	* @param key - The unique key of the node to retrieve.
+	* @returns The full TreeNode with nested children.
+	* @throws {Error} If key doesn't exist in cache.
+	*
+	* @example
+	* ```typescript
+	* const node = cache.getNode('node-1');
+	* console.log(node.children); // Full TreeNode objects, not keys
+	* ```
+	*/
 	getNode(key) {
 		const node = this.get(key);
 		return {
@@ -193,24 +332,124 @@ var Cache = class {
 			children: node.children?.map((key$1) => this.buildNode(key$1))
 		};
 	}
+	/**
+	* Returns an iterator of all node keys in the cache.
+	*
+	* @returns Iterator over all cached node keys.
+	*
+	* @example
+	* ```typescript
+	* for (const key of cache.getAllKeys()) {
+	*   console.log(key);
+	* }
+	* ```
+	*/
 	getAllKeys() {
 		return this.cache.lookup.keys();
 	}
+	/**
+	* Returns an iterator of all cached nodes.
+	*
+	* Note: Returns CacheTreeNode objects (with child keys, not full children objects).
+	*
+	* @returns Iterator over all cached nodes.
+	*
+	* @example
+	* ```typescript
+	* for (const node of cache.getAllNodes()) {
+	*   if (node.isSelected) {
+	*     console.log(node.key);
+	*   }
+	* }
+	* ```
+	*/
 	getAllNodes() {
 		return this.cache.lookup.values();
 	}
+	/**
+	* Determines the parent key for inserting a node at a position relative to a target.
+	*
+	* Used to calculate where a new node should be inserted when positioned
+	* 'before' or 'after' a target node.
+	*
+	* @param target - The target node key to position relative to, or null for root level.
+	* @param position - Whether to position before or after the target.
+	* @returns The parent key where insertion should occur, or null for root level.
+	*
+	* @example
+	* ```typescript
+	* // Find parent for inserting before node-2
+	* const parent = cache.getParentForPosition('node-2', 'before');
+	* ```
+	*/
+	getParentForPosition(target, position) {
+		const { parentKey } = this.parentOrSibling(target, position);
+		return parentKey;
+	}
+	/**
+	* Updates a node in the cache.
+	*
+	* Accepts a TreeNode<T>. Automatically converts TreeNode children to keys for
+	* internal cache storage.
+	*
+	* @param key - The unique key of the node to update.
+	* @param node - The node data to store.
+	*
+	* @example
+	* ```typescript
+	* // Update with TreeNode
+	* cache.setNode('node-1', { key: 'node-1', isSelected: true, children: [...] });
+	*
+	* // Update with CacheTreeNode (child keys)
+	* cache.setNode('node-1', { key: 'node-1', isSelected: true, children: ['child-1', 'child-2'] });
+	* ```
+	*/
 	setNode(key, node) {
 		this.set(key, {
 			...node,
 			children: (node.children ?? []).map((child) => child.key)
 		});
 	}
+	/**
+	* Updates all nodes in the cache with shared properties.
+	*
+	* Applies partial updates to every cached node. Useful for bulk operations
+	* like clearing all selections or resetting visibility states.
+	*
+	* Note: `parentKey` and `children` properties are ignored (not applied to nodes).
+	*
+	* @param props - Partial node properties to apply to all nodes.
+	*
+	* @example
+	* ```typescript
+	* // Clear all selections
+	* cache.setAllNodes({ isSelected: false, isIndeterminate: false });
+	*
+	* // Reset visibility
+	* cache.setAllNodes({ isVisible: false });
+	* ```
+	*/
 	setAllNodes({ parentKey, children, ...rest }) {
 		for (const node of this.cache.lookup.values()) this.set(node.key, {
 			...node,
 			...rest
 		});
 	}
+	/**
+	* Removes a node and all its descendants from the cache.
+	*
+	* Recursively deletes the node and all child nodes, then removes
+	* the node from its parent's children array (or roots array if top-level).
+	* Silently returns if the node doesn't exist.
+	*
+	* @param key - The unique key of the node to delete.
+	*
+	* @example
+	* ```typescript
+	* // Delete node and all its children
+	* cache.deleteNode('node-1');
+	* ```
+	*/
 	deleteNode(key) {
 		const node = this.cache.lookup.get(key);
 		if (!node) return;
@@ -218,11 +457,50 @@ var Cache = class {
 		node.parentKey ? this.removeFromParent(node.parentKey, key) : this.removeFromRoot(key);
 		this.delete(key);
 	}
+	/**
+	* Inserts multiple nodes at a position relative to a target node.
+	*
+	* Nodes are inserted in array order at the calculated position. If target is null,
+	* nodes are inserted at root level.
+	*
+	* @param target - The target node key to position relative to, or null for root level.
+	* @param nodes - Array of TreeNode objects to insert.
+	* @param position - Whether to insert before or after the target.
+	*
+	* @example
+	* ```typescript
+	* // Insert nodes before node-2
+	* cache.addNodes('node-2', [newNode1, newNode2], 'before');
+	*
+	* // Insert nodes at end of root level
+	* cache.addNodes(null, [newNode], 'after');
+	* ```
+	*/
 	addNodes(target, nodes, position) {
 		const { parentKey, index } = this.parentOrSibling(target, position);
 		const idx = index + (position === "before" ? 0 : 1);
 		nodes.map((node, i) => this.insertNode(parentKey, node, idx + i));
 	}
+	/**
+	* Inserts a node and its descendants into the cache at a specific index.
+	*
+	* Initializes node with default property values (isDisabled: false, isSelected: false, etc.)
+	* and recursively inserts all child nodes. Children are converted to key references
+	* for internal cache storage.
+	*
+	* @param parentKey - The parent node key, or null to insert at root level.
+	* @param node - The TreeNode to insert (with nested children).
+	* @param idx - The index position to insert at within the parent's children.
+	*
+	* @example
+	* ```typescript
+	* // Insert as first child of parent-1
+	* cache.insertNode('parent-1', newNode, 0);
+	*
+	* // Insert at root level
+	* cache.insertNode(null, newNode, 0);
+	* ```
+	*/
 	insertNode(parentKey, node, idx) {
 		const { children, ...rest } = node;
 		this.set(node.key, {
@@ -231,6 +509,7 @@ var Cache = class {
 			isSelected: false,
 			isVisible: false,
 			isVisibleComputed: false,
+			isIndeterminate: false,
 			...rest,
 			parentKey,
 			...children ? { children: children.map((child) => child.key) } : {}
@@ -238,16 +517,209 @@ var Cache = class {
 		node.children?.map((child, i) => this.insertNode(node.key, child, i));
 		parentKey === null ? this.addToRoot(node.key, idx) : this.addToParent(parentKey, node.key, idx);
 	}
+	/**
+	* Moves multiple nodes to a position relative to a target node.
+	*
+	* Nodes are moved in Set iteration order to the calculated position.
+	* Each node is removed from its current parent and added to the new parent.
+	*
+	* @param target - The target node key to position relative to, or null for root level.
+	* @param nodes - Set of node keys to move.
+	* @param position - Whether to position before or after the target.
+	*
+	* @example
+	* ```typescript
+	* // Move nodes before node-5
+	* cache.moveNodes('node-5', new Set(['node-1', 'node-2']), 'before');
+	*
+	* // Move to end of root level
+	* cache.moveNodes(null, new Set(['node-3']), 'after');
+	* ```
+	*/
 	moveNodes(target, nodes, position) {
 		const { parentKey, index } = this.parentOrSibling(target, position);
 		const idx = index + (position === "before" ? 0 : 1);
 		Array.from(nodes).map((key, i) => this.moveNode(parentKey, key, idx + i));
 	}
+	/**
+	* Moves a single node to a new parent and position.
+	*
+	* First removes the node from its current parent (or roots), then inserts
+	* it at the specified index under the new parent. The node's parentKey is updated.
+	*
+	* @param parentKey - The new parent node key, or null to move to root level.
+	* @param key - The node key to move.
+	* @param idx - The index position within the new parent's children.
+	*
+	* @example
+	* ```typescript
+	* // Move node-1 to be first child of parent-2
+	* cache.moveNode('parent-2', 'node-1', 0);
+	*
+	* // Move node-1 to root level
+	* cache.moveNode(null, 'node-1', 0);
+	* ```
+	*/
 	moveNode(parentKey, key, idx) {
 		const node = this.get(key);
 		node.parentKey ? this.removeFromParent(node.parentKey, key) : this.removeFromRoot(key);
 		parentKey ? this.addToParent(parentKey, key, idx) : this.addToRoot(key, idx);
 	}
+	/**
+	* Recursively applies selection state to a node and all its descendants.
+	*
+	* Disabled nodes are skipped (their selection state is not changed).
+	* Indeterminate state is cleared when selection is applied.
+	*
+	* @param key - The node key to cascade selection from.
+	* @param selected - Whether to select (true) or deselect (false).
+	*
+	* @example
+	* ```typescript
+	* // Select node and all children
+	* cache.cascadeSelection('node-1', true);
+	*
+	* // Deselect node and all children
+	* cache.cascadeSelection('node-1', false);
+	* ```
+	*/
+	cascadeSelection(key, selected) {
+		try {
+			const node = this.get(key);
+			if (!node.isDisabled) this.set(key, {
+				...node,
+				isSelected: selected,
+				isIndeterminate: false
+			});
+			if (node.children) {
+				for (const childKey of node.children) if (childKey != null) this.cascadeSelection(childKey, selected);
+			}
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Propagates selection state changes up through all ancestor nodes.
+	*
+	* Starting from a node, walks up the ancestor chain and recomputes each
+	* parent's selection state based on its children (all selected → selected,
+	* some selected → indeterminate, none selected → deselected).
+	*
+	* Includes early termination: stops walking up when a parent's state doesn't
+	* change, since ancestors won't be affected.
+	*
+	* @param key - The node key to bubble selection from.
+	*
+	* @example
+	* ```typescript
+	* // After updating a child's selection, update parents
+	* cache.setNode('child-1', { ...node, isSelected: true });
+	* cache.bubbleUpSelection('child-1');
+	* ```
+	*/
+	bubbleUpSelection(key) {
+		try {
+			let current = this.get(key);
+			while (current.parentKey) {
+				const parent = this.get(current.parentKey);
+				const newState = this.computeSelectionState(parent);
+				if (parent.isSelected === newState.isSelected && parent.isIndeterminate === newState.isIndeterminate) break;
+				this.set(parent.key, {
+					...parent,
+					isSelected: newState.isSelected,
+					isIndeterminate: newState.isIndeterminate
+				});
+				current = parent;
+			}
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Computes selection state for a node based on its children's states.
+	*
+	* Returns selected if all selectable children are selected, indeterminate if some
+	* are selected, and deselected if none are selected. Disabled children are excluded
+	* from computation. Leaf nodes use their own selection state.
+	*
+	* @param node - The node to compute state for.
+	* @returns Object with isSelected and isIndeterminate flags.
+	*/
+	computeSelectionState(node) {
+		if (!node.children || node.children.length === 0) return {
+			isSelected: node.isSelected ?? false,
+			isIndeterminate: false
+		};
+		const selectableChildren = node.children.filter((k) => {
+			try {
+				return !this.get(k).isDisabled;
+			} catch {
+				return false;
+			}
+		}).map((k) => this.get(k));
+		if (selectableChildren.length === 0) return {
+			isSelected: node.isSelected ?? false,
+			isIndeterminate: false
+		};
+		const selectedCount = selectableChildren.filter((c) => c.isSelected).length;
+		if (selectableChildren.filter((c) => c.isIndeterminate).length > 0) return {
+			isSelected: false,
+			isIndeterminate: true
+		};
+		if (selectedCount === selectableChildren.length) return {
+			isSelected: true,
+			isIndeterminate: false
+		};
+		if (selectedCount === 0) return {
+			isSelected: false,
+			isIndeterminate: false
+		};
+		return {
+			isSelected: false,
+			isIndeterminate: true
+		};
+	}
+	/**
+	* Updates selection state for all affected parents after moving nodes.
+	*
+	* When nodes are moved, both old parents (lost children) and new parent (gained children)
+	* may have their selection state invalidated. This method recomputes selection state
+	* for all affected parents and bubbles changes up the ancestor chain.
+	*
+	* @param oldParents - Set of parent keys that lost children during the move.
+	* @param newParent - The parent key that gained children, or null if moved to root.
+	*
+	* @example
+	* ```typescript
+	* // After moving nodes from parent-1 to parent-2
+	* cache.syncParentsAfterMove(new Set(['parent-1']), 'parent-2');
+	*
+	* // After moving nodes to root level
+	* cache.syncParentsAfterMove(new Set(['parent-1']), null);
+	* ```
+	*/
+	syncParentsAfterMove(oldParents, newParent) {
+		for (const parentKey of oldParents) try {
+			const parent = this.get(parentKey);
+			const newState = this.computeSelectionState(parent);
+			this.set(parentKey, {
+				...parent,
+				isSelected: newState.isSelected,
+				isIndeterminate: newState.isIndeterminate
+			});
+			if (parent.parentKey) this.bubbleUpSelection(parentKey);
+		} catch {}
+		if (newParent) try {
+			const parent = this.get(newParent);
+			const newState = this.computeSelectionState(parent);
+			this.set(newParent, {
+				...parent,
+				isSelected: newState.isSelected,
+				isIndeterminate: newState.isIndeterminate
+			});
+			if (parent.parentKey) this.bubbleUpSelection(newParent);
+		} catch {}
+	}
 };
 
 //#endregion