@accelint/design-toolkit 9.9.2 → 9.11.0

package/dist/hooks/use-tree/actions/cache.d.ts

@@ -14,81 +14,470 @@ import { TreeNode } from "../types.js";
 import { Key } from "@react-types/shared";
 
 //#region src/hooks/use-tree/actions/cache.d.ts
+/**
+ * Internal cache representation of a tree node.
+ *
+ * Differs from TreeNode by storing only child keys (not full child objects)
+ * for efficient cache lookups and memory usage.
+ *
+ * @template T - The type of data stored in the node.
+ */
 type CacheTreeNode<T> = Omit<TreeNode<T>, 'children'> & {
   children?: Key[];
 };
 /**
- * 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.
+ *
+ * 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');
  *
- * This will initialize once on load with data, then
- * updated with each tree operation.
+ * // Update selection
+ * cache.cascadeSelection('node-1', true);
+ *
+ * // Rebuild tree structure
+ * const tree = cache.toTree();
+ * ```
  */
 declare class Cache<T> {
   protected cache: {
     lookup: Map<Key, CacheTreeNode<T>>;
     roots: Key[];
   };
+  /**
+   * 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?: TreeNode<T>[]);
   /**
-   * 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: TreeNode<T>[], lookup?: Map<Key, CacheTreeNode<T>>, parentKey?: Key | null): {
     lookup: Map<Key, CacheTreeNode<T>>;
     roots: Key[];
   };
+  /**
+   * 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.
+   */
   protected get(key: Key): CacheTreeNode<T>;
+  /**
+   * Updates a cache node by key.
+   *
+   * @param key - The node key to update.
+   * @param node - The cache node data to store.
+   */
   protected set(key: Key, node: CacheTreeNode<T>): void;
+  /**
+   * Removes a node from the cache lookup.
+   *
+   * @param key - The node key to remove.
+   */
   protected delete(key: Key): void;
+  /**
+   * 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.
+   */
   protected addToParent(parentKey: Key, childKey: Key, idx: number): void;
+  /**
+   * 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.
+   */
   protected addToRoot(key: Key, idx: number): void;
+  /**
+   * Removes a child key from a parent's children array.
+   *
+   * @param parentKey - The parent node key.
+   * @param childKey - The child node key to remove.
+   */
   protected removeFromParent(parentKey: Key, childKey: Key): void;
+  /**
+   * Removes a node key from the roots array.
+   *
+   * @param key - The node key to remove from roots.
+   */
   protected removeFromRoot(key: Key): void;
+  /**
+   * 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.
+   */
   protected parentOrSibling(target: Key | null, position: 'before' | 'after'): {
     parentKey: Key | null;
     index: number;
   };
+  /**
+   * Recursively updates computed visibility for a node and all descendants.
+   *
+   * @param key - The node key to traverse from.
+   */
   protected traverse(key: Key): void;
+  /**
+   * 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.
+   */
   protected calculateVisibility(key: Key): boolean;
+  /**
+   * Recomputes visibility for all nodes in the tree.
+   */
   protected deriveVisibility(): void[];
   /**
-   * 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.
    */
   protected buildNode(key: Key): TreeNode<T>;
   /**
-   * Builds a tree structure from cache
+   * Rebuilds the tree structure from the flattened cache.
    *
-   * TODO: optimization - rebuild only from change to root
-   * Rebuild only from the changed node up the tree to avoid
-   * rebuilding the entire tree
+   * Converts the internal flat lookup map back into hierarchical TreeNode objects.
+   * Optionally recomputes visibility state based on ancestor expansion before building.
    *
-   * @param deriveVisible boolean - if true, will recompute visibility for nodes based on ancestry
+   * @param deriveVisible - If true, recomputes visibility for all nodes based on ancestry before building.
+   * @returns Array of root TreeNode objects with nested children.
+   *
+   * @example
+   * ```typescript
+   * // Build tree with current visibility
+   * const tree = cache.toTree();
+   *
+   * // Build tree and recompute visibility
+   * const tree = cache.toTree(true);
+   * ```
    */
   toTree(deriveVisible?: boolean): TreeNode<T>[];
   /**
    * 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: Key): TreeNode<T>;
+  /**
+   * 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(): MapIterator<Key>;
+  /**
+   * 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(): MapIterator<CacheTreeNode<T>>;
+  /**
+   * 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: Key | null, position: 'before' | 'after'): Key | null;
+  /**
+   * 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: Key, node: TreeNode<T>): void;
+  /**
+   * 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
   }: Partial<TreeNode<T>>): void;
+  /**
+   * 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: Key): void;
+  /**
+   * 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: Key | null, nodes: TreeNode<T>[], position: 'before' | 'after'): void;
+  /**
+   * 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: Key | null, node: TreeNode<T>, idx: number): void;
+  /**
+   * 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: Key | null, nodes: Set<Key>, position: 'before' | 'after'): void;
+  /**
+   * 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 | null, key: Key, idx: number): void;
+  /**
+   * 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: Key, selected: boolean): void;
+  /**
+   * 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: Key): void;
+  /**
+   * 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.
+   */
+  private computeSelectionState;
+  /**
+   * 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: Set<Key>, newParent: Key | null): void;
 }
 //#endregion
-export { Cache };
+export { Cache, CacheTreeNode };
 //# sourceMappingURL=cache.d.ts.map