npm - @accelint/design-toolkit - Versions diffs - 9.9.2 → 9.11.0 - Mend

@accelint/design-toolkit 9.9.2 → 9.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (719) hide show

package/dist/hooks/use-tree/actions/cache.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cache.js","names":["index: number","parentKey: Key \| null","key"],"sources":["../../../../src/hooks/use-tree/actions/cache.ts"],"sourcesContent":["// __private-exports\n/\n Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n /\n\nimport type { Key } from '@react-types/shared';\nimport type { TreeNode } from '../types';\n\ntype CacheTreeNode<T> = Omit<TreeNode<T>, 'children'> & {\n children?: Key[];\n};\n\n/\n This is a cache created only for performance reasons and is considered\n * to be only a temporary mirror of the data. The data is always correct\n * cache should be updated according to the data, only. If the data and\n * the cache do not match, the cache is invalidated and rebuilt.\n \n This will initialize once on load with data, then\n * updated with each tree operation.\n /\nexport class Cache<T> {\n protected cache: { lookup: Map<Key, CacheTreeNode<T>>; roots: Key[] } = {\n lookup: new Map(),\n roots: [],\n };\n\n constructor(nodes: TreeNode<T>[] = []) {\n this.rebuild(nodes);\n }\n\n /\n Recursively creates the cache object from tree data\n /\n rebuild(\n nodes: TreeNode<T>[],\n lookup: Map<Key, CacheTreeNode<T>> = new Map(),\n parentKey: Key \| null = null,\n ) {\n nodes.forEach((node) => {\n const { children, ...rest } = node;\n\n lookup.set(node.key, {\n isDisabled: false,\n isExpanded: false,\n isSelected: false,\n isVisible: false,\n isVisibleComputed: false,\n ...rest,\n parentKey,\n ...(children ? { children: children.map((child) => child.key) } : {}),\n });\n\n if (node.children) {\n this.rebuild(node.children, lookup, node.key);\n }\n });\n\n const cache = { lookup, roots: nodes.map((node) => node.key) };\n\n if (!parentKey) {\n this.cache = cache;\n }\n\n this.deriveVisibility();\n return cache;\n }\n\n protected get(key: Key) {\n const node = this.cache.lookup.get(key);\n\n if (node === undefined) {\n throw new Error(`Key of ${key} does not exist in tree`);\n }\n\n return node;\n }\n\n protected set(key: Key, node: CacheTreeNode<T>) {\n this.cache.lookup.set(key, node);\n }\n\n protected delete(key: Key) {\n this.cache.lookup.delete(key);\n }\n\n protected addToParent(parentKey: Key, childKey: Key, idx: number) {\n const parent = this.get(parentKey);\n const child = this.get(childKey);\n const index = Math.max(0, idx);\n\n this.set(childKey, {\n ...child,\n parentKey,\n });\n\n const children = (parent.children ?? []).slice(0);\n\n children.splice(index, 0, childKey);\n\n this.set(parentKey, {\n ...parent,\n children,\n });\n }\n\n protected addToRoot(key: Key, idx: number) {\n const node = this.get(key);\n const index = Math.max(0, idx);\n\n this.set(key, {\n ...node,\n parentKey: null,\n });\n\n this.cache.roots.splice(index, 0, key);\n }\n\n protected removeFromParent(parentKey: Key, childKey: Key) {\n const parent = this.get(parentKey);\n const child = this.get(childKey);\n\n this.set(childKey, {\n ...child,\n parentKey: null,\n });\n\n this.cache.lookup.set(parentKey, {\n ...parent,\n children: parent.children?.filter((key) => key !== childKey),\n });\n }\n\n protected removeFromRoot(key: Key) {\n const node = this.get(key);\n const idx = this.cache.roots.indexOf(key);\n\n if (idx >= 0) {\n this.set(key, {\n ...node,\n parentKey: null,\n });\n\n this.cache.roots.splice(idx, 1);\n }\n }\n\n protected parentOrSibling(target: Key \| null, position: 'before' \| 'after') {\n let index: number;\n let parentKey: Key \| null = null;\n\n if (target === null) {\n index = position === 'before' ? 0 : this.cache.roots.length;\n } else {\n const targetNode = this.get(target);\n\n if (targetNode.parentKey) {\n const parent = this.get(targetNode.parentKey);\n\n parentKey = parent.key;\n index = parent.children?.indexOf(target) ?? 0;\n } else {\n index = this.cache.roots.indexOf(target);\n }\n }\n\n return { parentKey, index };\n }\n\n protected traverse(key: Key) {\n const node = this.get(key);\n\n this.cache.lookup.set(key, {\n ...node,\n isVisibleComputed: this.calculateVisibility(key),\n });\n\n node.children?.map((child) => this.traverse(child));\n }\n\n protected calculateVisibility(key: Key) {\n let current = this.get(key);\n const ancestry = [current];\n\n while (current.parentKey) {\n const parent = this.get(current.parentKey);\n if (parent) {\n ancestry.push(parent);\n }\n current = parent;\n }\n\n return ancestry.every((n) => n.isVisible);\n }\n\n protected deriveVisibility() {\n return this.cache.roots.map((key) => this.traverse(key));\n }\n /\n Recursively builds a TreeNode from a key\n \n @param key\n /\n protected buildNode(key: Key): TreeNode<T> {\n const node = this.get(key);\n\n const children = (node.children ?? []).reduce(\n (acc: TreeNode<T>[], child) => {\n const childNode = this.cache.lookup.get(child);\n\n if (childNode && childNode.parentKey === key) {\n acc.push(this.buildNode(child));\n }\n\n return acc;\n },\n [],\n );\n\n return {\n ...node,\n children,\n };\n }\n\n /\n Builds a tree structure from cache\n \n TODO: optimization - rebuild only from change to root\n * Rebuild only from the changed node up the tree to avoid\n * rebuilding the entire tree\n \n @param deriveVisible boolean - if true, will recompute visibility for nodes based on ancestry\n /\n toTree(deriveVisible?: boolean): TreeNode<T>[] {\n if (deriveVisible) {\n this.deriveVisibility();\n }\n return this.cache.roots.map((key) => this.buildNode(key));\n }\n\n /\n CACHE FUNCTIONS\n * These manage cache operations. No cache operations should ever be done\n * outside this file.\n **/\n getNode(key: Key): TreeNode<T> {\n const node = this.get(key);\n\n return {\n ...node,\n children: node.children?.map((key) => this.buildNode(key)),\n };\n }\n\n getAllKeys() {\n return this.cache.lookup.keys();\n }\n\n getAllNodes() {\n return this.cache.lookup.values();\n }\n\n setNode(key: Key, node: TreeNode<T>) {\n this.set(key, {\n ...node,\n children: (node.children ?? []).map((child) => child.key),\n });\n }\n\n setAllNodes({ parentKey, children, ...rest }: Partial<TreeNode<T>>) {\n for (const node of this.cache.lookup.values()) {\n this.set(node.key, {\n ...node,\n ...rest,\n });\n }\n }\n\n deleteNode(key: Key) {\n const node = this.cache.lookup.get(key);\n\n if (!node) {\n return;\n }\n\n // remove children\n node.children?.map((key) => this.deleteNode(key));\n\n // remove node from previous parent or root\n node.parentKey\n ? this.removeFromParent(node.parentKey, key)\n : this.removeFromRoot(key);\n\n // remove the actual node\n this.delete(key);\n }\n\n addNodes(\n target: Key \| null,\n nodes: TreeNode<T>[],\n position: 'before' \| 'after',\n ) {\n const { parentKey, index } = this.parentOrSibling(target, position);\n const idx = index + (position === 'before' ? 0 : 1);\n\n nodes.map((node, i) => this.insertNode(parentKey, node, idx + i));\n }\n\n insertNode(parentKey: Key \| null, node: TreeNode<T>, idx: number) {\n const { children, ...rest } = node;\n\n this.set(node.key, {\n isDisabled: false,\n isExpanded: false,\n isSelected: false,\n isVisible: false,\n isVisibleComputed: false,\n ...rest,\n parentKey,\n ...(children ? { children: children.map((child) => child.key) } : {}),\n });\n\n node.children?.map((child, i) => this.insertNode(node.key, child, i));\n\n parentKey === null\n ? this.addToRoot(node.key, idx)\n : this.addToParent(parentKey, node.key, idx);\n }\n\n moveNodes(target: Key \| null, nodes: Set<Key>, position: 'before' \| 'after') {\n const { parentKey, index } = this.parentOrSibling(target, position);\n const idx = index + (position === 'before' ? 0 : 1);\n\n Array.from(nodes).map((key, i) => this.moveNode(parentKey, key, idx + i));\n }\n\n moveNode(parentKey: Key \| null, key: Key, idx: number) {\n const node = this.get(key);\n\n // remove from previous parent\n node.parentKey\n ? this.removeFromParent(node.parentKey, key)\n : this.removeFromRoot(key);\n\n // add as child to new parent or root at position\n parentKey\n ? this.addToParent(parentKey, key, idx)\n : this.addToRoot(key, idx);\n }\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"cache.js","names":["index: number","parentKey: Key \| null","key"],"sources":["../../../../src/hooks/use-tree/actions/cache.ts"],"sourcesContent":["// __private-exports\n/\n Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n /\n\nimport type { Key } from '@react-types/shared';\nimport type { TreeNode } from '../types';\n\n/\n Internal cache representation of a tree node.\n \n Differs from TreeNode by storing only child keys (not full child objects)\n * for efficient cache lookups and memory usage.\n \n @template T - The type of data stored in the node.\n /\nexport type CacheTreeNode<T> = Omit<TreeNode<T>, 'children'> & {\n children?: Key[];\n};\n\n/\n Performance-optimized cache for tree node operations.\n \n Maintains a flat lookup map and roots array for O(1) node access. The cache\n * is a temporary mirror of tree data and must stay synchronized with the source\n * tree structure. If inconsistencies occur, the cache is invalidated and rebuilt.\n \n Initializes once on construction with tree data, then updates incrementally\n * with each tree operation (add, move, delete, select).\n \n @template T - The type of data stored in tree nodes.\n \n @example\n * ```typescript\n * const cache = new Cache<UserData>(initialNodes);\n \n // Get a node\n * const node = cache.getNode('node-1');\n \n // Update selection\n * cache.cascadeSelection('node-1', true);\n \n // Rebuild tree structure\n * const tree = cache.toTree();\n * ```\n /\nexport class Cache<T> {\n protected cache: { lookup: Map<Key, CacheTreeNode<T>>; roots: Key[] } = {\n lookup: new Map(),\n roots: [],\n };\n\n /\n Creates a new cache instance and populates it with tree nodes.\n \n @param nodes - Initial tree nodes to cache (defaults to empty array).\n \n @example\n * ```typescript\n * const cache = new Cache(treeData);\n * ```\n /\n constructor(nodes: TreeNode<T>[] = []) {\n this.rebuild(nodes);\n }\n\n /\n Rebuilds the entire cache from tree nodes.\n \n Recursively flattens the tree structure into a lookup map and roots array.\n * Initializes all node properties with defaults (isDisabled: false, isExpanded: false, etc.)\n * and converts nested children to key references. After rebuilding, recomputes visibility\n * for all nodes based on ancestor state.\n \n Called automatically in the constructor and whenever external tree state changes.\n * This is an expensive operation - prefer incremental cache updates when possible.\n \n @param nodes - Tree nodes to build cache from.\n * @param lookup - Internal lookup map (used for recursion, typically omitted).\n * @param parentKey - Parent key for current recursion level (used for recursion, typically omitted).\n \n @example\n * ```typescript\n * // Rebuild cache from new tree data\n * cache.rebuild(newTreeNodes);\n * ```\n /\n rebuild(\n nodes: TreeNode<T>[],\n lookup: Map<Key, CacheTreeNode<T>> = new Map(),\n parentKey: Key \| null = null,\n ) {\n nodes.forEach((node) => {\n const { children, ...rest } = node;\n\n lookup.set(node.key, {\n isDisabled: false,\n isExpanded: false,\n isSelected: false,\n isVisible: false,\n isVisibleComputed: false,\n isIndeterminate: false,\n ...rest,\n parentKey,\n ...(children ? { children: children.map((child) => child.key) } : {}),\n });\n\n if (node.children) {\n this.rebuild(node.children, lookup, node.key);\n }\n });\n\n const cache = { lookup, roots: nodes.map((node) => node.key) };\n\n if (!parentKey) {\n this.cache = cache;\n }\n\n this.deriveVisibility();\n return cache;\n }\n\n /\n Retrieves a cache node by key.\n \n @param key - The node key to retrieve.\n * @returns The cached node.\n * @throws {Error} If key is null/undefined or doesn't exist in cache.\n /\n protected get(key: Key) {\n if (key == null) {\n throw new Error(`Key is ${key} (null/undefined) - this is invalid`);\n }\n\n const node = this.cache.lookup.get(key);\n\n if (node === undefined) {\n throw new Error(`Key of ${key} does not exist in tree`);\n }\n\n return node;\n }\n\n /\n Updates a cache node by key.\n \n @param key - The node key to update.\n * @param node - The cache node data to store.\n /\n protected set(key: Key, node: CacheTreeNode<T>) {\n this.cache.lookup.set(key, node);\n }\n\n /\n Removes a node from the cache lookup.\n \n @param key - The node key to remove.\n /\n protected delete(key: Key) {\n this.cache.lookup.delete(key);\n }\n\n /\n Adds a child key to a parent's children array at a specific index.\n \n @param parentKey - The parent node key.\n * @param childKey - The child node key to add.\n * @param idx - The index position within parent's children.\n /\n protected addToParent(parentKey: Key, childKey: Key, idx: number) {\n const parent = this.get(parentKey);\n const child = this.get(childKey);\n const index = Math.max(0, idx);\n\n this.set(childKey, {\n ...child,\n parentKey,\n });\n\n const children = (parent.children ?? []).slice(0);\n\n children.splice(index, 0, childKey);\n\n this.set(parentKey, {\n ...parent,\n children,\n });\n }\n\n /\n Adds a node key to the roots array at a specific index.\n \n @param key - The node key to add to roots.\n * @param idx - The index position within roots array.\n /\n protected addToRoot(key: Key, idx: number) {\n const node = this.get(key);\n const index = Math.max(0, idx);\n\n this.set(key, {\n ...node,\n parentKey: null,\n });\n\n this.cache.roots.splice(index, 0, key);\n }\n\n /\n Removes a child key from a parent's children array.\n \n @param parentKey - The parent node key.\n * @param childKey - The child node key to remove.\n /\n protected removeFromParent(parentKey: Key, childKey: Key) {\n const parent = this.get(parentKey);\n const child = this.get(childKey);\n\n this.set(childKey, {\n ...child,\n parentKey: null,\n });\n\n this.cache.lookup.set(parentKey, {\n ...parent,\n children: parent.children?.filter((key) => key !== childKey),\n });\n }\n\n /\n Removes a node key from the roots array.\n \n @param key - The node key to remove from roots.\n /\n protected removeFromRoot(key: Key) {\n const node = this.get(key);\n const idx = this.cache.roots.indexOf(key);\n\n if (idx >= 0) {\n this.set(key, {\n ...node,\n parentKey: null,\n });\n\n this.cache.roots.splice(idx, 1);\n }\n }\n\n /\n Calculates parent key and index for positioning relative to a target.\n \n @param target - The target node key, or null for root level.\n * @param position - Whether positioning before or after target.\n * @returns Object with parentKey and index for insertion.\n /\n protected parentOrSibling(target: Key \| null, position: 'before' \| 'after') {\n let index: number;\n let parentKey: Key \| null = null;\n\n if (target === null) {\n index = position === 'before' ? 0 : this.cache.roots.length;\n } else {\n const targetNode = this.get(target);\n\n if (targetNode.parentKey) {\n const parent = this.get(targetNode.parentKey);\n\n parentKey = parent.key;\n index = parent.children?.indexOf(target) ?? 0;\n } else {\n index = this.cache.roots.indexOf(target);\n }\n }\n\n return { parentKey, index };\n }\n\n /\n Recursively updates computed visibility for a node and all descendants.\n \n @param key - The node key to traverse from.\n /\n protected traverse(key: Key) {\n const node = this.get(key);\n\n this.cache.lookup.set(key, {\n ...node,\n isVisibleComputed: this.calculateVisibility(key),\n });\n\n node.children?.map((child) => this.traverse(child));\n }\n\n /\n Calculates if a node is actually visible based on all ancestors' visibility.\n \n @param key - The node key to calculate visibility for.\n * @returns True if node and all ancestors have isVisible: true.\n /\n protected calculateVisibility(key: Key) {\n let current = this.get(key);\n const ancestry = [current];\n\n while (current.parentKey) {\n const parent = this.get(current.parentKey);\n if (parent) {\n ancestry.push(parent);\n }\n current = parent;\n }\n\n return ancestry.every((n) => n.isVisible);\n }\n\n /\n Recomputes visibility for all nodes in the tree.\n /\n protected deriveVisibility() {\n return this.cache.roots.map((key) => this.traverse(key));\n }\n\n /\n Recursively builds a TreeNode from a cache key.\n \n Converts the flat cache representation back into nested TreeNode structure\n * by recursively building child nodes from child keys.\n \n @param key - The node key to build from.\n * @returns Complete TreeNode with nested children.\n /\n protected buildNode(key: Key): TreeNode<T> {\n const node = this.get(key);\n\n const children = (node.children ?? []).reduce(\n (acc: TreeNode<T>[], child) => {\n const childNode = this.cache.lookup.get(child);\n\n if (childNode && childNode.parentKey === key) {\n acc.push(this.buildNode(child));\n }\n\n return acc;\n },\n [],\n );\n\n return {\n ...node,\n children,\n };\n }\n\n /\n Rebuilds the tree structure from the flattened cache.\n \n Converts the internal flat lookup map back into hierarchical TreeNode objects.\n * Optionally recomputes visibility state based on ancestor expansion before building.\n \n @param deriveVisible - If true, recomputes visibility for all nodes based on ancestry before building.\n * @returns Array of root TreeNode objects with nested children.\n \n @example\n * ```typescript\n * // Build tree with current visibility\n * const tree = cache.toTree();\n \n // Build tree and recompute visibility\n * const tree = cache.toTree(true);\n * ```\n /\n toTree(deriveVisible?: boolean): TreeNode<T>[] {\n if (deriveVisible) {\n this.deriveVisibility();\n }\n return this.cache.roots.map((key) => this.buildNode(key));\n }\n\n /\n CACHE FUNCTIONS\n * These are the public functions to manage cache operations. No cache operations should ever be done\n * outside this file since it risks corruption of the data.\n /\n\n /\n * Retrieves a node from cache and builds its full TreeNode representation.\n \n Differs from internal `get()` by recursively building child nodes into\n * full TreeNode objects instead of returning just child keys.\n \n @param key - The unique key of the node to retrieve.\n * @returns The full TreeNode with nested children.\n * @throws {Error} If key doesn't exist in cache.\n \n @example\n * ```typescript\n * const node = cache.getNode('node-1');\n * console.log(node.children); // Full TreeNode objects, not keys\n * ```\n /\n getNode(key: Key): TreeNode<T> {\n const node = this.get(key);\n\n return {\n ...node,\n children: node.children?.map((key) => this.buildNode(key)),\n };\n }\n\n /\n Returns an iterator of all node keys in the cache.\n \n @returns Iterator over all cached node keys.\n \n @example\n * ```typescript\n * for (const key of cache.getAllKeys()) {\n * console.log(key);\n * }\n * ```\n /\n getAllKeys() {\n return this.cache.lookup.keys();\n }\n\n /\n Returns an iterator of all cached nodes.\n \n Note: Returns CacheTreeNode objects (with child keys, not full children objects).\n \n @returns Iterator over all cached nodes.\n \n @example\n * ```typescript\n * for (const node of cache.getAllNodes()) {\n * if (node.isSelected) {\n * console.log(node.key);\n * }\n * }\n * ```\n /\n getAllNodes() {\n return this.cache.lookup.values();\n }\n\n /\n Determines the parent key for inserting a node at a position relative to a target.\n \n Used to calculate where a new node should be inserted when positioned\n * 'before' or 'after' a target node.\n \n @param target - The target node key to position relative to, or null for root level.\n * @param position - Whether to position before or after the target.\n * @returns The parent key where insertion should occur, or null for root level.\n \n @example\n * ```typescript\n * // Find parent for inserting before node-2\n * const parent = cache.getParentForPosition('node-2', 'before');\n * ```\n /\n getParentForPosition(\n target: Key \| null,\n position: 'before' \| 'after',\n ): Key \| null {\n const { parentKey } = this.parentOrSibling(target, position);\n return parentKey;\n }\n\n /\n Updates a node in the cache.\n \n Accepts a TreeNode<T>. Automatically converts TreeNode children to keys for\n * internal cache storage.\n \n @param key - The unique key of the node to update.\n * @param node - The node data to store.\n \n @example\n * ```typescript\n * // Update with TreeNode\n * cache.setNode('node-1', { key: 'node-1', isSelected: true, children: [...] });\n \n // Update with CacheTreeNode (child keys)\n * cache.setNode('node-1', { key: 'node-1', isSelected: true, children: ['child-1', 'child-2'] });\n * ```\n /\n setNode(key: Key, node: TreeNode<T>) {\n this.set(key, {\n ...node,\n children: (node.children ?? []).map((child) => child.key),\n });\n }\n\n /\n Updates all nodes in the cache with shared properties.\n \n Applies partial updates to every cached node. Useful for bulk operations\n * like clearing all selections or resetting visibility states.\n \n Note: `parentKey` and `children` properties are ignored (not applied to nodes).\n \n @param props - Partial node properties to apply to all nodes.\n \n @example\n * ```typescript\n * // Clear all selections\n * cache.setAllNodes({ isSelected: false, isIndeterminate: false });\n \n // Reset visibility\n * cache.setAllNodes({ isVisible: false });\n * ```\n /\n setAllNodes({ parentKey, children, ...rest }: Partial<TreeNode<T>>) {\n for (const node of this.cache.lookup.values()) {\n this.set(node.key, {\n ...node,\n ...rest,\n });\n }\n }\n\n /\n Removes a node and all its descendants from the cache.\n \n Recursively deletes the node and all child nodes, then removes\n * the node from its parent's children array (or roots array if top-level).\n * Silently returns if the node doesn't exist.\n \n @param key - The unique key of the node to delete.\n \n @example\n * ```typescript\n * // Delete node and all its children\n * cache.deleteNode('node-1');\n * ```\n /\n deleteNode(key: Key) {\n const node = this.cache.lookup.get(key);\n\n if (!node) {\n return;\n }\n\n // remove children\n node.children?.map((key) => this.deleteNode(key));\n\n // remove node from previous parent or root\n node.parentKey\n ? this.removeFromParent(node.parentKey, key)\n : this.removeFromRoot(key);\n\n // remove the actual node\n this.delete(key);\n }\n\n /\n Inserts multiple nodes at a position relative to a target node.\n \n Nodes are inserted in array order at the calculated position. If target is null,\n * nodes are inserted at root level.\n \n @param target - The target node key to position relative to, or null for root level.\n * @param nodes - Array of TreeNode objects to insert.\n * @param position - Whether to insert before or after the target.\n \n @example\n * ```typescript\n * // Insert nodes before node-2\n * cache.addNodes('node-2', [newNode1, newNode2], 'before');\n \n // Insert nodes at end of root level\n * cache.addNodes(null, [newNode], 'after');\n * ```\n /\n addNodes(\n target: Key \| null,\n nodes: TreeNode<T>[],\n position: 'before' \| 'after',\n ) {\n const { parentKey, index } = this.parentOrSibling(target, position);\n const idx = index + (position === 'before' ? 0 : 1);\n\n nodes.map((node, i) => this.insertNode(parentKey, node, idx + i));\n }\n\n /\n Inserts a node and its descendants into the cache at a specific index.\n \n Initializes node with default property values (isDisabled: false, isSelected: false, etc.)\n * and recursively inserts all child nodes. Children are converted to key references\n * for internal cache storage.\n \n @param parentKey - The parent node key, or null to insert at root level.\n * @param node - The TreeNode to insert (with nested children).\n * @param idx - The index position to insert at within the parent's children.\n \n @example\n * ```typescript\n * // Insert as first child of parent-1\n * cache.insertNode('parent-1', newNode, 0);\n \n // Insert at root level\n * cache.insertNode(null, newNode, 0);\n * ```\n /\n insertNode(parentKey: Key \| null, node: TreeNode<T>, idx: number) {\n const { children, ...rest } = node;\n\n this.set(node.key, {\n isDisabled: false,\n isExpanded: false,\n isSelected: false,\n isVisible: false,\n isVisibleComputed: false,\n isIndeterminate: false,\n ...rest,\n parentKey,\n ...(children\n ? {\n children: children.map((child) => child.key),\n }\n : {}),\n });\n\n node.children?.map((child, i) => this.insertNode(node.key, child, i));\n\n parentKey === null\n ? this.addToRoot(node.key, idx)\n : this.addToParent(parentKey, node.key, idx);\n }\n\n /\n Moves multiple nodes to a position relative to a target node.\n \n Nodes are moved in Set iteration order to the calculated position.\n * Each node is removed from its current parent and added to the new parent.\n \n @param target - The target node key to position relative to, or null for root level.\n * @param nodes - Set of node keys to move.\n * @param position - Whether to position before or after the target.\n \n @example\n * ```typescript\n * // Move nodes before node-5\n * cache.moveNodes('node-5', new Set(['node-1', 'node-2']), 'before');\n \n // Move to end of root level\n * cache.moveNodes(null, new Set(['node-3']), 'after');\n * ```\n /\n moveNodes(target: Key \| null, nodes: Set<Key>, position: 'before' \| 'after') {\n const { parentKey, index } = this.parentOrSibling(target, position);\n const idx = index + (position === 'before' ? 0 : 1);\n\n Array.from(nodes).map((key, i) => this.moveNode(parentKey, key, idx + i));\n }\n\n /\n Moves a single node to a new parent and position.\n \n First removes the node from its current parent (or roots), then inserts\n * it at the specified index under the new parent. The node's parentKey is updated.\n \n @param parentKey - The new parent node key, or null to move to root level.\n * @param key - The node key to move.\n * @param idx - The index position within the new parent's children.\n \n @example\n * ```typescript\n * // Move node-1 to be first child of parent-2\n * cache.moveNode('parent-2', 'node-1', 0);\n \n // Move node-1 to root level\n * cache.moveNode(null, 'node-1', 0);\n * ```\n /\n moveNode(parentKey: Key \| null, key: Key, idx: number) {\n const node = this.get(key);\n\n // remove from previous parent\n node.parentKey\n ? this.removeFromParent(node.parentKey, key)\n : this.removeFromRoot(key);\n\n // add as child to new parent or root at position\n parentKey\n ? this.addToParent(parentKey, key, idx)\n : this.addToRoot(key, idx);\n }\n\n /\n Recursively applies selection state to a node and all its descendants.\n \n Disabled nodes are skipped (their selection state is not changed).\n * Indeterminate state is cleared when selection is applied.\n \n @param key - The node key to cascade selection from.\n * @param selected - Whether to select (true) or deselect (false).\n \n @example\n * ```typescript\n * // Select node and all children\n * cache.cascadeSelection('node-1', true);\n \n // Deselect node and all children\n * cache.cascadeSelection('node-1', false);\n * ```\n /\n cascadeSelection(key: Key, selected: boolean): void {\n try {\n const node = this.get(key);\n\n // Update this node (skip if disabled)\n if (!node.isDisabled) {\n this.set(key, {\n ...node,\n isSelected: selected,\n isIndeterminate: false,\n });\n }\n\n // Recurse to children\n if (node.children) {\n for (const childKey of node.children) {\n if (childKey != null) {\n this.cascadeSelection(childKey, selected);\n }\n }\n }\n } catch {\n // Key doesn't exist, skip\n return;\n }\n }\n\n /\n Propagates selection state changes up through all ancestor nodes.\n \n Starting from a node, walks up the ancestor chain and recomputes each\n * parent's selection state based on its children (all selected → selected,\n * some selected → indeterminate, none selected → deselected).\n \n Includes early termination: stops walking up when a parent's state doesn't\n * change, since ancestors won't be affected.\n \n @param key - The node key to bubble selection from.\n \n @example\n * ```typescript\n * // After updating a child's selection, update parents\n * cache.setNode('child-1', { ...node, isSelected: true });\n * cache.bubbleUpSelection('child-1');\n * ```\n /\n bubbleUpSelection(key: Key): void {\n try {\n let current = this.get(key);\n\n while (current.parentKey) {\n const parent = this.get(current.parentKey);\n const newState = this.computeSelectionState(parent);\n\n // Early termination: if parent state unchanged, ancestors won't change\n if (\n parent.isSelected === newState.isSelected &&\n parent.isIndeterminate === newState.isIndeterminate\n ) {\n break;\n }\n\n this.set(parent.key, {\n ...parent,\n isSelected: newState.isSelected,\n isIndeterminate: newState.isIndeterminate,\n });\n\n current = parent;\n }\n } catch {\n // Key doesn't exist, skip\n return;\n }\n }\n\n /\n Computes selection state for a node based on its children's states.\n \n Returns selected if all selectable children are selected, indeterminate if some\n * are selected, and deselected if none are selected. Disabled children are excluded\n * from computation. Leaf nodes use their own selection state.\n \n @param node - The node to compute state for.\n * @returns Object with isSelected and isIndeterminate flags.\n /\n private computeSelectionState(node: CacheTreeNode<T>): {\n isSelected: boolean;\n isIndeterminate: boolean;\n } {\n // Leaf nodes: use their own state\n if (!node.children \|\| node.children.length === 0) {\n return {\n isSelected: node.isSelected ?? false,\n isIndeterminate: false,\n };\n }\n\n // Get selectable children (exclude disabled)\n const selectableChildren = node.children\n .filter((k) => {\n try {\n const child = this.get(k);\n return !child.isDisabled;\n } catch {\n return false;\n }\n })\n .map((k) => this.get(k));\n\n // If all children disabled, treat as leaf\n if (selectableChildren.length === 0) {\n return {\n isSelected: node.isSelected ?? false,\n isIndeterminate: false,\n };\n }\n\n // Check if all/none/some selected\n const selectedCount = selectableChildren.filter((c) => c.isSelected).length;\n const indeterminateCount = selectableChildren.filter(\n (c) => c.isIndeterminate,\n ).length;\n\n // If any child is indeterminate, parent is indeterminate\n if (indeterminateCount > 0) {\n return {\n isSelected: false,\n isIndeterminate: true,\n };\n }\n\n // All children selected\n if (selectedCount === selectableChildren.length) {\n return {\n isSelected: true,\n isIndeterminate: false,\n };\n }\n\n // No children selected\n if (selectedCount === 0) {\n return {\n isSelected: false,\n isIndeterminate: false,\n };\n }\n\n // Some children selected (indeterminate)\n return {\n isSelected: false,\n isIndeterminate: true,\n };\n }\n\n /\n Updates selection state for all affected parents after moving nodes.\n \n When nodes are moved, both old parents (lost children) and new parent (gained children)\n * may have their selection state invalidated. This method recomputes selection state\n * for all affected parents and bubbles changes up the ancestor chain.\n \n @param oldParents - Set of parent keys that lost children during the move.\n * @param newParent - The parent key that gained children, or null if moved to root.\n \n @example\n * ```typescript\n * // After moving nodes from parent-1 to parent-2\n * cache.syncParentsAfterMove(new Set(['parent-1']), 'parent-2');\n \n // After moving nodes to root level\n * cache.syncParentsAfterMove(new Set(['parent-1']), null);\n * ```\n */\n syncParentsAfterMove(oldParents: Set<Key>, newParent: Key \| null): void {\n // Update old parents (lost children)\n for (const parentKey of oldParents) {\n try {\n const parent = this.get(parentKey);\n const newState = this.computeSelectionState(parent);\n\n this.set(parentKey, {\n ...parent,\n isSelected: newState.isSelected,\n isIndeterminate: newState.isIndeterminate,\n });\n\n // Bubble up to ancestors\n if (parent.parentKey) {\n this.bubbleUpSelection(parentKey);\n }\n } catch {\n // Parent doesn't exist, skip\n }\n }\n\n // Update new parent (gained children)\n if (newParent) {\n try {\n const parent = this.get(newParent);\n const newState = this.computeSelectionState(parent);\n\n this.set(newParent, {\n ...parent,\n isSelected: newState.isSelected,\n isIndeterminate: newState.isIndeterminate,\n });\n\n // Bubble up to ancestors\n if (parent.parentKey) {\n this.bubbleUpSelection(newParent);\n }\n } catch {\n // Parent doesn't exist, skip\n }\n }\n }\n}\n"],"mappings":"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"}

package/dist/hooks/use-tree/actions/index.d.ts CHANGED Viewed

@@ -16,39 +16,53 @@ import "client-only";
 //#region src/hooks/use-tree/actions/index.d.ts
 /**
- * Stateless hook that transforms tree data according to actions
- * it takes in nodes and returns a new version of the tree.
+ * Stateless hook that provides tree transformation operations without managing state.
  *
- * Note: each operation returns the whole tree. Future iterations
- * might want to return only the changed portion of the tree.
+ * Returns pure functions that accept tree nodes and return new transformed tree nodes.
+ * Does not modify the input tree - all operations are immutable transformations.
+ * Each operation returns the complete updated tree structure. Use this hook when you
+ * want to manage tree state yourself, or when integrating with external state management.
+ * For complete state management, use {@link useTreeState} instead.
  *
- * @param options - {@link UseTreeActionsOptions}
- * @param options.nodes - Current tree nodes to operate on.
- * @returns {@link TreeActions} Object containing all tree manipulation functions.
+ * Note: Each operation returns the whole tree. Future iterations might return only
+ * the changed portion of the tree for performance optimization.
+ *
+ * @template T - The type of custom values stored in tree nodes (accessed via `node.values`).
+ *
+ * @param options - Configuration options for tree actions.
+ * @param options.nodes - Current tree nodes to operate on. Used to build internal cache for operations.
+ * @param options.selectionCascade - Enable cascade selection mode. When true, selection operations
+ *   automatically propagate to descendants and update parent indeterminate states. Default: false.
+ * @returns Object containing all tree manipulation functions (insert, move, remove, select, expand, etc.).
  *
  * @example
  * ```tsx
- * const treeActions = useTreeActions({
- *   nodes: [
- *     {
- *       key: 'root',
- *       label: 'Root',
- *       children: [
- *         { key: 'child1', label: 'Child 1' },
- *         { key: 'child2', label: 'Child 2' }
- *       ]
- *     }
- *   ]
- * });
+ * // Basic usage with custom state management
+ * const [tree, setTree] = useState(initialTree);
+ * const actions = useTreeActions({ nodes: tree });
  *
- * // Use tree actions
- * const updatedTree = treeActions.insertAfter('child1', [
+ * // Insert a new node
+ * const updatedTree = actions.insertAfter('child1', [
  *   { key: 'newChild', label: 'New Child' }
  * ]);
+ * setTree(updatedTree);
+ *
+ * // Move nodes
+ * const movedTree = actions.moveInto('parent', new Set(['child1', 'child2']));
+ * setTree(movedTree);
+ *
+ * // Cascade selection
+ * const actionsWithCascade = useTreeActions({
+ *   nodes: tree,
+ *   selectionCascade: true
+ * });
+ * const selectedTree = actionsWithCascade.onSelectionChange(new Set(['parent']));
+ * // All descendants of 'parent' are now selected too
  * ```
  */
 declare function useTreeActions<T>({
-  nodes
+  nodes,
+  selectionCascade
 }: UseTreeActionsOptions<T>): TreeActions<T>;
 //#endregion
 export { useTreeActions };

package/dist/hooks/use-tree/actions/index.js CHANGED Viewed

@@ -16,46 +16,84 @@
 import { Cache } from "./cache.js";
 import "client-only";
 import { useRef } from "react";
-import { useUpdateEffect } from "@react-aria/utils";
 //#region src/hooks/use-tree/actions/index.ts
 /**
-* Stateless hook that transforms tree data according to actions
-* it takes in nodes and returns a new version of the tree.
+* Stateless hook that provides tree transformation operations without managing state.
 *
-* Note: each operation returns the whole tree. Future iterations
-* might want to return only the changed portion of the tree.
+* Returns pure functions that accept tree nodes and return new transformed tree nodes.
+* Does not modify the input tree - all operations are immutable transformations.
+* Each operation returns the complete updated tree structure. Use this hook when you
+* want to manage tree state yourself, or when integrating with external state management.
+* For complete state management, use {@link useTreeState} instead.
 *
-* @param options - {@link UseTreeActionsOptions}
-* @param options.nodes - Current tree nodes to operate on.
-* @returns {@link TreeActions} Object containing all tree manipulation functions.
+* Note: Each operation returns the whole tree. Future iterations might return only
+* the changed portion of the tree for performance optimization.
+*
+* @template T - The type of custom values stored in tree nodes (accessed via `node.values`).
+*
+* @param options - Configuration options for tree actions.
+* @param options.nodes - Current tree nodes to operate on. Used to build internal cache for operations.
+* @param options.selectionCascade - Enable cascade selection mode. When true, selection operations
+*   automatically propagate to descendants and update parent indeterminate states. Default: false.
+* @returns Object containing all tree manipulation functions (insert, move, remove, select, expand, etc.).
 *
 * @example
 * ```tsx
-* const treeActions = useTreeActions({
-*   nodes: [
-*     {
-*       key: 'root',
-*       label: 'Root',
-*       children: [
-*         { key: 'child1', label: 'Child 1' },
-*         { key: 'child2', label: 'Child 2' }
-*       ]
-*     }
-*   ]
-* });
+* // Basic usage with custom state management
+* const [tree, setTree] = useState(initialTree);
+* const actions = useTreeActions({ nodes: tree });
 *
-* // Use tree actions
-* const updatedTree = treeActions.insertAfter('child1', [
+* // Insert a new node
+* const updatedTree = actions.insertAfter('child1', [
 *   { key: 'newChild', label: 'New Child' }
 * ]);
+* setTree(updatedTree);
+*
+* // Move nodes
+* const movedTree = actions.moveInto('parent', new Set(['child1', 'child2']));
+* setTree(movedTree);
+*
+* // Cascade selection
+* const actionsWithCascade = useTreeActions({
+*   nodes: tree,
+*   selectionCascade: true
+* });
+* const selectedTree = actionsWithCascade.onSelectionChange(new Set(['parent']));
+* // All descendants of 'parent' are now selected too
 * ```
 */
-function useTreeActions({ nodes }) {
+function useTreeActions({ nodes, selectionCascade = false }) {
 	const cache = useRef(new Cache(nodes)).current;
-	useUpdateEffect(() => {
-		cache.rebuild(nodes);
-	}, [nodes]);
+	/**
+	* Collects parent keys for a set of nodes before a move operation
+	*/
+	function getParents(keys) {
+		const prevParents = /* @__PURE__ */ new Set();
+		for (const key of keys) {
+			const node = cache.getNode(key);
+			if (node.parentKey) prevParents.add(node.parentKey);
+		}
+		return prevParents;
+	}
+	/** CASCADE SELECTION **/
+	/**
+	* Selection change with cascade logic
+	*/
+	function onSelectionChangeCascade(keys) {
+		const previouslySelected = /* @__PURE__ */ new Set();
+		for (const k of cache.getAllKeys()) try {
+			if (cache.getNode(k).isSelected) previouslySelected.add(k);
+		} catch {}
+		const validKeys = [...keys].filter((k) => k != null);
+		const added = validKeys.filter((k) => !previouslySelected.has(k));
+		const removed = [...previouslySelected].filter((k) => !validKeys.includes(k));
+		for (const key of added) cache.cascadeSelection(key, true);
+		for (const key of removed) cache.cascadeSelection(key, false);
+		const affectedKeys = new Set([...added, ...removed]);
+		for (const key of affectedKeys) cache.bubbleUpSelection(key);
+		return cache.toTree();
+	}
 	/** GET NODE **/
 	function getNode(key) {
 		return cache.getNode(key);
@@ -75,15 +113,35 @@ function useTreeActions({ nodes }) {
 	}
 	/** MOVE NODES **/
 	function moveAfter(target, keys) {
+		if (!selectionCascade) {
+			cache.moveNodes(target, keys, "after");
+			return cache.toTree();
+		}
+		const prevParents = getParents(keys);
+		const newParent = cache.getParentForPosition(target, "after");
 		cache.moveNodes(target, keys, "after");
+		cache.syncParentsAfterMove(prevParents, newParent);
 		return cache.toTree();
 	}
 	function moveBefore(target, keys) {
+		if (!selectionCascade) {
+			cache.moveNodes(target, keys, "before");
+			return cache.toTree();
+		}
+		const prevParents = getParents(keys);
+		const newParent = cache.getParentForPosition(target, "before");
 		cache.moveNodes(target, keys, "before");
+		cache.syncParentsAfterMove(prevParents, newParent);
 		return cache.toTree();
 	}
 	function moveInto(target, keys) {
+		if (!selectionCascade) {
+			for (const key of keys) cache.moveNode(target, key, 0);
+			return cache.toTree();
+		}
+		const prevParents = getParents(keys);
 		for (const key of keys) cache.moveNode(target, key, 0);
+		cache.syncParentsAfterMove(prevParents, target);
 		return cache.toTree();
 	}
 	/** UPDATE NODES **/
@@ -99,22 +157,31 @@ function useTreeActions({ nodes }) {
 	}
 	/** SELECTION **/
 	function onSelectionChange(keys) {
-		unselectAll();
-		for (const key of keys) {
-			const node = cache.getNode(key);
-			cache.setNode(node.key, {
-				...node,
-				isSelected: true
-			});
+		if (!selectionCascade) {
+			unselectAll();
+			for (const key of keys) {
+				const node = cache.getNode(key);
+				cache.setNode(node.key, {
+					...node,
+					isSelected: true
+				});
+			}
+			return cache.toTree();
 		}
-		return cache.toTree();
+		return onSelectionChangeCascade(keys);
 	}
 	function selectAll() {
-		cache.setAllNodes({ isSelected: true });
+		cache.setAllNodes({
+			isSelected: true,
+			isIndeterminate: false
+		});
 		return cache.toTree();
 	}
 	function unselectAll() {
-		cache.setAllNodes({ isSelected: false });
+		cache.setAllNodes({
+			isSelected: false,
+			isIndeterminate: false
+		});
 		return cache.toTree();
 	}
 	/** EXPANSION **/

package/dist/hooks/use-tree/actions/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","names":["nodes"],"sources":["../../../../src/hooks/use-tree/actions/index.ts"],"sourcesContent":["/\n Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n /\n'use client';\n\nimport 'client-only';\nimport { useUpdateEffect } from '@react-aria/utils';\nimport { useRef } from 'react';\nimport { Cache } from './cache';\nimport type { Key } from '@react-types/shared';\nimport type {\n TreeActions,\n TreeData,\n TreeNode,\n TreeNodeBase,\n UseTreeActionsOptions,\n} from '../types';\n\n/\n Stateless hook that transforms tree data according to actions\n * it takes in nodes and returns a new version of the tree.\n \n Note: each operation returns the whole tree. Future iterations\n * might want to return only the changed portion of the tree.\n \n @param options - {@link UseTreeActionsOptions}\n * @param options.nodes - Current tree nodes to operate on.\n * @returns {@link TreeActions} Object containing all tree manipulation functions.\n \n @example\n * ```tsx\n * const treeActions = useTreeActions({\n * nodes: [\n * {\n * key: 'root',\n * label: 'Root',\n * children: [\n * { key: 'child1', label: 'Child 1' },\n * { key: 'child2', label: 'Child 2' }\n * ]\n * }\n * ]\n * });\n \n // Use tree actions\n * const updatedTree = treeActions.insertAfter('child1', [\n * { key: 'newChild', label: 'New Child' }\n * ]);\n * ```\n /\nexport function useTreeActions<T>({\n nodes,\n}: UseTreeActionsOptions<T>): TreeActions<T> {\n const cache = useRef(new Cache<T>(nodes)).current;\n\n useUpdateEffect(() => {\n cache.rebuild(nodes);\n }, [nodes]);\n\n /* GET NODE /\n function getNode(key: Key) {\n return cache.getNode(key);\n }\n\n / INSERT NODES /\n function insertAfter(\n target: Key \| null,\n nodes: TreeNode<T>[],\n ): TreeNode<T>[] {\n cache.addNodes(target, nodes, 'after');\n\n return cache.toTree(true);\n }\n\n function insertBefore(\n target: Key \| null,\n nodes: TreeNode<T>[],\n ): TreeNode<T>[] {\n cache.addNodes(target, nodes, 'before');\n\n return cache.toTree(true);\n }\n\n function insertInto(target: Key \| null, nodes: TreeNode<T>[]): TreeNode<T>[] {\n for (const node of nodes) {\n cache.insertNode(target, node, 0);\n }\n\n return cache.toTree(true);\n }\n\n / MOVE NODES /\n function moveAfter(target: Key \| null, keys: Set<Key>): TreeNode<T>[] {\n cache.moveNodes(target, keys, 'after');\n\n return cache.toTree();\n }\n\n function moveBefore(target: Key \| null, keys: Set<Key>): TreeNode<T>[] {\n cache.moveNodes(target, keys, 'before');\n\n return cache.toTree();\n }\n\n function moveInto(target: Key \| null, keys: Set<Key>): TreeNode<T>[] {\n for (const key of keys) {\n cache.moveNode(target, key, 0);\n }\n\n return cache.toTree();\n }\n\n / UPDATE NODES /\n function updateNode(\n key: Key,\n callback: (node: TreeNodeBase<T>) => TreeNodeBase<T>,\n ): TreeNode<T>[] {\n const node = cache.getNode(key);\n\n cache.setNode(key, callback(node));\n\n return cache.toTree(true);\n }\n\n / REMOVE NODES /\n function remove(keys: Set<Key>): TreeNode<T>[] {\n for (const key of keys.values()) {\n cache.deleteNode(key);\n }\n\n return cache.toTree(true);\n }\n\n / SELECTION /\n function onSelectionChange(keys: Set<Key>): TreeNode<T>[] {\n unselectAll();\n\n for (const key of keys) {\n const node = cache.getNode(key);\n\n cache.setNode(node.key, {\n ...node,\n isSelected: true,\n });\n }\n\n return cache.toTree();\n }\n\n function selectAll(): TreeNode<T>[] {\n cache.setAllNodes({ isSelected: true });\n\n return cache.toTree();\n }\n\n function unselectAll(): TreeNode<T>[] {\n cache.setAllNodes({ isSelected: false });\n\n return cache.toTree();\n }\n\n / EXPANSION /\n function onExpandedChange(keys: Set<Key>): TreeNode<T>[] {\n collapseAll();\n\n for (const key of keys) {\n const node = cache.getNode(key);\n\n cache.setNode(node.key, {\n ...node,\n isExpanded: true,\n });\n }\n\n return cache.toTree();\n }\n\n function expandAll(): TreeNode<T>[] {\n cache.setAllNodes({ isExpanded: true });\n\n return cache.toTree();\n }\n\n function collapseAll(): TreeNode<T>[] {\n cache.setAllNodes({ isExpanded: false });\n\n return cache.toTree();\n }\n\n / VISIBILITY **/\n function onVisibilityChange(keys: Set<Key>): TreeData<T> {\n hideAll();\n\n for (const key of keys) {\n const node = cache.getNode(key);\n cache.setNode(node.key, {\n ...node,\n isVisible: true,\n });\n }\n return cache.toTree(true);\n }\n\n function revealAll(): TreeNode<T>[] {\n cache.setAllNodes({ isVisible: true });\n\n return cache.toTree(true);\n }\n\n function hideAll(): TreeNode<T>[] {\n cache.setAllNodes({ isVisible: false });\n\n return cache.toTree(true);\n }\n\n return {\n getNode,\n insertAfter,\n insertBefore,\n insertInto,\n moveAfter,\n moveBefore,\n moveInto,\n remove,\n updateNode,\n\n // Expansion\n collapseAll,\n expandAll,\n onExpandedChange,\n\n // Selection\n selectAll,\n unselectAll,\n onSelectionChange,\n\n // Visibility\n hideAll,\n revealAll,\n onVisibilityChange,\n };\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"index.js","names":["nodes"],"sources":["../../../../src/hooks/use-tree/actions/index.ts"],"sourcesContent":["/\n Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n /\n'use client';\n\nimport 'client-only';\nimport { useRef } from 'react';\nimport { Cache } from './cache';\nimport type { Key } from '@react-types/shared';\nimport type {\n TreeActions,\n TreeData,\n TreeNode,\n TreeNodeBase,\n UseTreeActionsOptions,\n} from '../types';\n\n/\n Stateless hook that provides tree transformation operations without managing state.\n \n Returns pure functions that accept tree nodes and return new transformed tree nodes.\n * Does not modify the input tree - all operations are immutable transformations.\n * Each operation returns the complete updated tree structure. Use this hook when you\n * want to manage tree state yourself, or when integrating with external state management.\n * For complete state management, use {@link useTreeState} instead.\n \n Note: Each operation returns the whole tree. Future iterations might return only\n * the changed portion of the tree for performance optimization.\n \n @template T - The type of custom values stored in tree nodes (accessed via `node.values`).\n \n @param options - Configuration options for tree actions.\n * @param options.nodes - Current tree nodes to operate on. Used to build internal cache for operations.\n * @param options.selectionCascade - Enable cascade selection mode. When true, selection operations\n * automatically propagate to descendants and update parent indeterminate states. Default: false.\n * @returns Object containing all tree manipulation functions (insert, move, remove, select, expand, etc.).\n \n @example\n * ```tsx\n * // Basic usage with custom state management\n * const [tree, setTree] = useState(initialTree);\n * const actions = useTreeActions({ nodes: tree });\n \n // Insert a new node\n * const updatedTree = actions.insertAfter('child1', [\n * { key: 'newChild', label: 'New Child' }\n * ]);\n * setTree(updatedTree);\n \n // Move nodes\n * const movedTree = actions.moveInto('parent', new Set(['child1', 'child2']));\n * setTree(movedTree);\n \n // Cascade selection\n * const actionsWithCascade = useTreeActions({\n * nodes: tree,\n * selectionCascade: true\n * });\n * const selectedTree = actionsWithCascade.onSelectionChange(new Set(['parent']));\n * // All descendants of 'parent' are now selected too\n * ```\n /\nexport function useTreeActions<T>({\n nodes,\n selectionCascade = false,\n}: UseTreeActionsOptions<T>): TreeActions<T> {\n const cache = useRef(new Cache<T>(nodes)).current;\n\n /\n Collects parent keys for a set of nodes before a move operation\n /\n function getParents(keys: Set<Key>): Set<Key> {\n const prevParents = new Set<Key>();\n for (const key of keys) {\n const node = cache.getNode(key);\n if (node.parentKey) {\n prevParents.add(node.parentKey);\n }\n }\n return prevParents;\n }\n\n /* CASCADE SELECTION /\n\n /\n * Selection change with cascade logic\n /\n function onSelectionChangeCascade(keys: Set<Key>): TreeNode<T>[] {\n // Detect changes\n const previouslySelected = new Set<Key>();\n for (const k of cache.getAllKeys()) {\n try {\n const node = cache.getNode(k);\n if (node.isSelected) {\n previouslySelected.add(k);\n }\n } catch {\n // Skip invalid keys\n }\n }\n\n const validKeys = [...keys].filter((k) => k != null);\n const added = validKeys.filter((k) => !previouslySelected.has(k));\n const removed = [...previouslySelected].filter(\n (k) => !validKeys.includes(k),\n );\n\n // Cascade down\n for (const key of added) {\n cache.cascadeSelection(key, true);\n }\n\n for (const key of removed) {\n cache.cascadeSelection(key, false);\n }\n\n // Bubble up\n const affectedKeys = new Set([...added, ...removed]);\n for (const key of affectedKeys) {\n cache.bubbleUpSelection(key);\n }\n\n return cache.toTree();\n }\n\n /* GET NODE /\n function getNode(key: Key) {\n return cache.getNode(key);\n }\n\n / INSERT NODES /\n function insertAfter(\n target: Key \| null,\n nodes: TreeNode<T>[],\n ): TreeNode<T>[] {\n cache.addNodes(target, nodes, 'after');\n\n return cache.toTree(true);\n }\n\n function insertBefore(\n target: Key \| null,\n nodes: TreeNode<T>[],\n ): TreeNode<T>[] {\n cache.addNodes(target, nodes, 'before');\n\n return cache.toTree(true);\n }\n\n function insertInto(target: Key \| null, nodes: TreeNode<T>[]): TreeNode<T>[] {\n for (const node of nodes) {\n cache.insertNode(target, node, 0);\n }\n\n return cache.toTree(true);\n }\n\n / MOVE NODES /\n function moveAfter(target: Key \| null, keys: Set<Key>): TreeNode<T>[] {\n if (!selectionCascade) {\n cache.moveNodes(target, keys, 'after');\n return cache.toTree();\n }\n\n // Collect old parents before move\n const prevParents = getParents(keys);\n\n // Get new parent before move\n const newParent = cache.getParentForPosition(target, 'after');\n\n // Perform move\n cache.moveNodes(target, keys, 'after');\n\n // Sync cascade state\n cache.syncParentsAfterMove(prevParents, newParent);\n\n return cache.toTree();\n }\n\n function moveBefore(target: Key \| null, keys: Set<Key>): TreeNode<T>[] {\n if (!selectionCascade) {\n cache.moveNodes(target, keys, 'before');\n return cache.toTree();\n }\n\n // Collect old parents before move\n const prevParents = getParents(keys);\n\n // Get new parent before move\n const newParent = cache.getParentForPosition(target, 'before');\n\n // Perform move\n cache.moveNodes(target, keys, 'before');\n\n // Sync cascade state\n cache.syncParentsAfterMove(prevParents, newParent);\n\n return cache.toTree();\n }\n\n function moveInto(target: Key \| null, keys: Set<Key>): TreeNode<T>[] {\n if (!selectionCascade) {\n for (const key of keys) {\n cache.moveNode(target, key, 0);\n }\n return cache.toTree();\n }\n\n // Collect old parents before move\n const prevParents = getParents(keys);\n\n // Perform move\n for (const key of keys) {\n cache.moveNode(target, key, 0);\n }\n\n // Sync cascade state (target IS the new parent for moveInto)\n cache.syncParentsAfterMove(prevParents, target);\n\n return cache.toTree();\n }\n\n / UPDATE NODES /\n function updateNode(\n key: Key,\n callback: (node: TreeNodeBase<T>) => TreeNodeBase<T>,\n ): TreeNode<T>[] {\n const node = cache.getNode(key);\n\n cache.setNode(key, callback(node));\n\n return cache.toTree(true);\n }\n\n / REMOVE NODES /\n function remove(keys: Set<Key>): TreeNode<T>[] {\n for (const key of keys.values()) {\n cache.deleteNode(key);\n }\n\n return cache.toTree(true);\n }\n\n / SELECTION /\n function onSelectionChange(keys: Set<Key>): TreeNode<T>[] {\n if (!selectionCascade) {\n // Current behavior (no cascade)\n unselectAll();\n\n for (const key of keys) {\n const node = cache.getNode(key);\n\n cache.setNode(node.key, {\n ...node,\n isSelected: true,\n });\n }\n\n return cache.toTree();\n }\n\n // Cascade behavior\n return onSelectionChangeCascade(keys);\n }\n\n function selectAll(): TreeNode<T>[] {\n cache.setAllNodes({ isSelected: true, isIndeterminate: false });\n\n return cache.toTree();\n }\n\n function unselectAll(): TreeNode<T>[] {\n cache.setAllNodes({ isSelected: false, isIndeterminate: false });\n\n return cache.toTree();\n }\n\n / EXPANSION /\n function onExpandedChange(keys: Set<Key>): TreeNode<T>[] {\n collapseAll();\n\n for (const key of keys) {\n const node = cache.getNode(key);\n\n cache.setNode(node.key, {\n ...node,\n isExpanded: true,\n });\n }\n\n return cache.toTree();\n }\n\n function expandAll(): TreeNode<T>[] {\n cache.setAllNodes({ isExpanded: true });\n\n return cache.toTree();\n }\n\n function collapseAll(): TreeNode<T>[] {\n cache.setAllNodes({ isExpanded: false });\n\n return cache.toTree();\n }\n\n / VISIBILITY **/\n function onVisibilityChange(keys: Set<Key>): TreeData<T> {\n hideAll();\n\n for (const key of keys) {\n const node = cache.getNode(key);\n cache.setNode(node.key, {\n ...node,\n isVisible: true,\n });\n }\n return cache.toTree(true);\n }\n\n function revealAll(): TreeNode<T>[] {\n cache.setAllNodes({ isVisible: true });\n\n return cache.toTree(true);\n }\n\n function hideAll(): TreeNode<T>[] {\n cache.setAllNodes({ isVisible: false });\n\n return cache.toTree(true);\n }\n\n return {\n getNode,\n insertAfter,\n insertBefore,\n insertInto,\n moveAfter,\n moveBefore,\n moveInto,\n remove,\n updateNode,\n\n // Expansion\n collapseAll,\n expandAll,\n onExpandedChange,\n\n // Selection\n selectAll,\n unselectAll,\n onSelectionChange,\n\n // Visibility\n hideAll,\n revealAll,\n onVisibilityChange,\n };\n}\n"],"mappings":"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"}

package/dist/hooks/use-tree/state/index.d.ts CHANGED Viewed

@@ -14,15 +14,38 @@ import { UseTreeState, UseTreeStateOptions } from "../types.js";
 import "client-only";
 //#region src/hooks/use-tree/state/index.d.ts
 /**
- * Stateful tree manager with drag-and-drop, selection, expansion, and visibility controls
+ * Stateful tree manager with drag-and-drop, selection, expansion, and visibility controls.
+ *
+ * Manages tree state internally using React hooks. Returns tree nodes, manipulation actions,
+ * and drag-and-drop configuration. Use this hook when you need a complete tree solution with
+ * built-in state management. For stateless transformations, use {@link useTreeActions} instead.
  *
  * @param options - {@link UseTreeStateOptions}
  * @param options.items - Initial tree node items.
+ * @param options.selectionCascade - Enable cascade selection mode. When true, selecting a parent
+ *   automatically selects all descendants, and parent checkboxes show indeterminate state when
+ *   partially selected. Default: false.
  * @returns {@link UseTreeState} Tree state, actions, and drag-and-drop configuration.
+ *
+ * @example
+ * ```tsx
+ * // Basic tree without cascade
+ * const { nodes, actions } = useTreeState({
+ *   items: myTree,
+ * });
+ *
+ * // Tree with cascade selection (file system-like behavior)
+ * const { nodes, actions } = useTreeState({
+ *   items: fileSystemTree,
+ *   selectionCascade: true,
+ * });
+ * ```
  */
 declare function useTreeState<T>({
-  items
+  items,
+  selectionCascade
 }: UseTreeStateOptions<T>): UseTreeState<T>;
 //#endregion
 export { useTreeState };

package/dist/hooks/use-tree/state/index.js CHANGED Viewed

@@ -20,15 +20,39 @@ import { useState } from "react";
 //#region src/hooks/use-tree/state/index.ts
 /**
-* Stateful tree manager with drag-and-drop, selection, expansion, and visibility controls
+* Stateful tree manager with drag-and-drop, selection, expansion, and visibility controls.
+*
+* Manages tree state internally using React hooks. Returns tree nodes, manipulation actions,
+* and drag-and-drop configuration. Use this hook when you need a complete tree solution with
+* built-in state management. For stateless transformations, use {@link useTreeActions} instead.
 *
 * @param options - {@link UseTreeStateOptions}
 * @param options.items - Initial tree node items.
+* @param options.selectionCascade - Enable cascade selection mode. When true, selecting a parent
+*   automatically selects all descendants, and parent checkboxes show indeterminate state when
+*   partially selected. Default: false.
 * @returns {@link UseTreeState} Tree state, actions, and drag-and-drop configuration.
+*
+* @example
+* ```tsx
+* // Basic tree without cascade
+* const { nodes, actions } = useTreeState({
+*   items: myTree,
+* });
+*
+* // Tree with cascade selection (file system-like behavior)
+* const { nodes, actions } = useTreeState({
+*   items: fileSystemTree,
+*   selectionCascade: true,
+* });
+* ```
 */
-function useTreeState({ items }) {
+function useTreeState({ items, selectionCascade = false }) {
 	const [nodes, setNodes] = useState(items);
-	const actions = useTreeActions({ nodes });
+	const actions = useTreeActions({
+		nodes,
+		selectionCascade
+	});
 	const dragAndDropConfig = {
 		getItems: (keys) => [...keys].map((key) => {
 			const node = actions.getNode(key);

package/dist/hooks/use-tree/state/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","names":["dragAndDropConfig: DragAndDropConfig","items"],"sources":["../../../../src/hooks/use-tree/state/index.ts"],"sourcesContent":["/\n Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n /\n'use client';\n\nimport 'client-only';\nimport { useState } from 'react';\nimport { useTreeActions } from '../actions';\nimport { processDroppedItems } from './utils';\nimport type {\n DragItem,\n DroppableCollectionInsertDropEvent,\n DroppableCollectionRootDropEvent,\n Key,\n Selection,\n} from '@react-types/shared';\nimport type {\n DragAndDropConfig,\n UseTreeState,\n UseTreeStateOptions,\n} from '../types';\n\n/\n Stateful tree manager with drag-and-drop, selection, expansion, and visibility controls\n \n @param options - {@link UseTreeStateOptions}\n * @param options.items - Initial tree node items.\n * @returns {@link UseTreeState} Tree state, actions, and drag-and-drop configuration.\n */\nexport function useTreeState<T>({\n items,\n}: UseTreeStateOptions<T>): UseTreeState<T> {\n const [nodes, setNodes] = useState(items);\n const actions = useTreeActions<T>({ nodes });\n\n const dragAndDropConfig: DragAndDropConfig = {\n getItems: (keys: Set<Key>): DragItem[] =>\n [...keys].map((key) => {\n const node = actions.getNode(key);\n\n return {\n key: `${key}`,\n 'text/plain': JSON.stringify(node),\n };\n }),\n onInsert: ({ items, target }: DroppableCollectionInsertDropEvent) => {\n (async () => {\n const processedItems = await processDroppedItems(\n items,\n dragAndDropConfig.acceptedDragTypes ?? [],\n );\n\n setNodes(\n actions.remove(new Set(processedItems.map((item) => item.id))),\n );\n\n if (target.dropPosition === 'before') {\n setNodes(actions.insertBefore(target.key, processedItems));\n } else if (target.dropPosition === 'after') {\n setNodes(actions.insertAfter(target.key, processedItems));\n }\n })();\n },\n onRootDrop: ({ items }: DroppableCollectionRootDropEvent) => {\n (async () => {\n const processedItems = await processDroppedItems(\n items,\n dragAndDropConfig.acceptedDragTypes ?? [],\n );\n\n setNodes(\n actions.remove(new Set(processedItems.map((item) => item.key))),\n );\n setNodes(actions.insertAfter(null, processedItems));\n })();\n },\n onMove: (e) => {\n if (e.target.dropPosition === 'before') {\n setNodes(actions.moveBefore(e.target.key, e.keys));\n } else if (e.target.dropPosition === 'after') {\n setNodes(actions.moveAfter(e.target.key, e.keys));\n } else if (e.target.dropPosition === 'on') {\n const targetNode = actions.getNode(e.target.key);\n if (targetNode) {\n setNodes(actions.moveInto(e.target.key, e.keys));\n }\n }\n },\n };\n\n function collapseAll() {\n setNodes(actions.collapseAll());\n }\n\n function expandAll() {\n setNodes(actions.expandAll());\n }\n\n function onExpandedChange(keys: Set<Key>) {\n setNodes(actions.onExpandedChange(keys));\n }\n\n function selectAll() {\n setNodes(actions.selectAll());\n }\n\n function unselectAll() {\n setNodes(actions.unselectAll());\n }\n\n function onSelectionChange(keys: Selection) {\n if (keys === 'all') {\n return selectAll();\n }\n\n setNodes(actions.onSelectionChange(keys));\n }\n\n function hideAll() {\n setNodes(actions.hideAll());\n }\n\n function revealAll() {\n setNodes(actions.revealAll());\n }\n\n function onVisibilityChange(keys: Set<Key>) {\n setNodes(actions.onVisibilityChange(keys));\n }\n\n return {\n nodes,\n actions: {\n // Expansion\n collapseAll,\n expandAll,\n onExpandedChange,\n\n // Selection\n selectAll,\n unselectAll,\n onSelectionChange,\n\n // Visibility\n hideAll,\n revealAll,\n onVisibilityChange,\n },\n dragAndDropConfig,\n };\n}\n"],"mappings":"~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA~~,SAAgB,aAAgB,EAC9B,~~SAC0C~~;CAC1C,MAAM,CAAC,OAAO,YAAY,SAAS,MAAM;CACzC,MAAM,UAAU,eAAkB,EAAE,~~OAAO,~~CAAC;~~CAE5C~~,MAAMA,oBAAuC;EAC3C,WAAW,SACT,CAAC,GAAG,KAAK,CAAC,KAAK,QAAQ;GACrB,MAAM,OAAO,QAAQ,QAAQ,IAAI;AAEjC,UAAO;IACL,KAAK,GAAG;IACR,cAAc,KAAK,UAAU,KAAK;IACnC;IACD;EACJ,WAAW,EAAE,gBAAO,aAAiD;AACnE,IAAC,YAAY;IACX,MAAM,iBAAiB,MAAM,oBAC3BC,SACA,kBAAkB,qBAAqB,EAAE,CAC1C;AAED,aACE,QAAQ,OAAO,IAAI,IAAI,eAAe,KAAK,SAAS,KAAK,GAAG,CAAC,CAAC,CAC/D;AAED,QAAI,OAAO,iBAAiB,SAC1B,UAAS,QAAQ,aAAa,OAAO,KAAK,eAAe,CAAC;aACjD,OAAO,iBAAiB,QACjC,UAAS,QAAQ,YAAY,OAAO,KAAK,eAAe,CAAC;OAEzD;;EAEN,aAAa,EAAE,qBAA8C;AAC3D,IAAC,YAAY;IACX,MAAM,iBAAiB,MAAM,oBAC3BA,SACA,kBAAkB,qBAAqB,EAAE,CAC1C;AAED,aACE,QAAQ,OAAO,IAAI,IAAI,eAAe,KAAK,SAAS,KAAK,IAAI,CAAC,CAAC,CAChE;AACD,aAAS,QAAQ,YAAY,MAAM,eAAe,CAAC;OACjD;;EAEN,SAAS,MAAM;AACb,OAAI,EAAE,OAAO,iBAAiB,SAC5B,UAAS,QAAQ,WAAW,EAAE,OAAO,KAAK,EAAE,KAAK,CAAC;YACzC,EAAE,OAAO,iBAAiB,QACnC,UAAS,QAAQ,UAAU,EAAE,OAAO,KAAK,EAAE,KAAK,CAAC;YACxC,EAAE,OAAO,iBAAiB,MAEnC;QADmB,QAAQ,QAAQ,EAAE,OAAO,IAAI,CAE9C,UAAS,QAAQ,SAAS,EAAE,OAAO,KAAK,EAAE,KAAK,CAAC;;;EAIvD;CAED,SAAS,cAAc;AACrB,WAAS,QAAQ,aAAa,CAAC;;CAGjC,SAAS,YAAY;AACnB,WAAS,QAAQ,WAAW,CAAC;;CAG/B,SAAS,iBAAiB,MAAgB;AACxC,WAAS,QAAQ,iBAAiB,KAAK,CAAC;;CAG1C,SAAS,YAAY;AACnB,WAAS,QAAQ,WAAW,CAAC;;CAG/B,SAAS,cAAc;AACrB,WAAS,QAAQ,aAAa,CAAC;;CAGjC,SAAS,kBAAkB,MAAiB;AAC1C,MAAI,SAAS,MACX,QAAO,WAAW;AAGpB,WAAS,QAAQ,kBAAkB,KAAK,CAAC;;CAG3C,SAAS,UAAU;AACjB,WAAS,QAAQ,SAAS,CAAC;;CAG7B,SAAS,YAAY;AACnB,WAAS,QAAQ,WAAW,CAAC;;CAG/B,SAAS,mBAAmB,MAAgB;AAC1C,WAAS,QAAQ,mBAAmB,KAAK,CAAC;;AAG5C,QAAO;EACL;EACA,SAAS;GAEP;GACA;GACA;GAGA;GACA;GACA;GAGA;GACA;GACA;GACD;EACD;EACD"}
1	+ {"version":3,"file":"index.js","names":["dragAndDropConfig: DragAndDropConfig","items"],"sources":["../../../../src/hooks/use-tree/state/index.ts"],"sourcesContent":["/\n Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n /\n'use client';\n\nimport 'client-only';\nimport { useState } from 'react';\nimport { useTreeActions } from '../actions';\nimport { processDroppedItems } from './utils';\nimport type {\n DragItem,\n DroppableCollectionInsertDropEvent,\n DroppableCollectionRootDropEvent,\n Key,\n Selection,\n} from '@react-types/shared';\nimport type {\n DragAndDropConfig,\n UseTreeState,\n UseTreeStateOptions,\n} from '../types';\n\n/\n Stateful tree manager with drag-and-drop, selection, expansion, and visibility controls.\n \n Manages tree state internally using React hooks. Returns tree nodes, manipulation actions,\n * and drag-and-drop configuration. Use this hook when you need a complete tree solution with\n * built-in state management. For stateless transformations, use {@link useTreeActions} instead.\n \n @param options - {@link UseTreeStateOptions}\n * @param options.items - Initial tree node items.\n * @param options.selectionCascade - Enable cascade selection mode. When true, selecting a parent\n * automatically selects all descendants, and parent checkboxes show indeterminate state when\n * partially selected. Default: false.\n * @returns {@link UseTreeState} Tree state, actions, and drag-and-drop configuration.\n \n @example\n * ```tsx\n * // Basic tree without cascade\n * const { nodes, actions } = useTreeState({\n * items: myTree,\n * });\n \n // Tree with cascade selection (file system-like behavior)\n * const { nodes, actions } = useTreeState({\n * items: fileSystemTree,\n * selectionCascade: true,\n * });\n * ```\n */\nexport function useTreeState<T>({\n items,\n selectionCascade = false,\n}: UseTreeStateOptions<T>): UseTreeState<T> {\n const [nodes, setNodes] = useState(items);\n const actions = useTreeActions<T>({ nodes, selectionCascade });\n\n const dragAndDropConfig: DragAndDropConfig = {\n getItems: (keys: Set<Key>): DragItem[] =>\n [...keys].map((key) => {\n const node = actions.getNode(key);\n\n return {\n key: `${key}`,\n 'text/plain': JSON.stringify(node),\n };\n }),\n onInsert: ({ items, target }: DroppableCollectionInsertDropEvent) => {\n (async () => {\n const processedItems = await processDroppedItems(\n items,\n dragAndDropConfig.acceptedDragTypes ?? [],\n );\n\n setNodes(\n actions.remove(new Set(processedItems.map((item) => item.id))),\n );\n\n if (target.dropPosition === 'before') {\n setNodes(actions.insertBefore(target.key, processedItems));\n } else if (target.dropPosition === 'after') {\n setNodes(actions.insertAfter(target.key, processedItems));\n }\n })();\n },\n onRootDrop: ({ items }: DroppableCollectionRootDropEvent) => {\n (async () => {\n const processedItems = await processDroppedItems(\n items,\n dragAndDropConfig.acceptedDragTypes ?? [],\n );\n\n setNodes(\n actions.remove(new Set(processedItems.map((item) => item.key))),\n );\n setNodes(actions.insertAfter(null, processedItems));\n })();\n },\n onMove: (e) => {\n if (e.target.dropPosition === 'before') {\n setNodes(actions.moveBefore(e.target.key, e.keys));\n } else if (e.target.dropPosition === 'after') {\n setNodes(actions.moveAfter(e.target.key, e.keys));\n } else if (e.target.dropPosition === 'on') {\n const targetNode = actions.getNode(e.target.key);\n if (targetNode) {\n setNodes(actions.moveInto(e.target.key, e.keys));\n }\n }\n },\n };\n\n function collapseAll() {\n setNodes(actions.collapseAll());\n }\n\n function expandAll() {\n setNodes(actions.expandAll());\n }\n\n function onExpandedChange(keys: Set<Key>) {\n setNodes(actions.onExpandedChange(keys));\n }\n\n function selectAll() {\n setNodes(actions.selectAll());\n }\n\n function unselectAll() {\n setNodes(actions.unselectAll());\n }\n\n function onSelectionChange(keys: Selection) {\n if (keys === 'all') {\n return selectAll();\n }\n\n setNodes(actions.onSelectionChange(keys));\n }\n\n function hideAll() {\n setNodes(actions.hideAll());\n }\n\n function revealAll() {\n setNodes(actions.revealAll());\n }\n\n function onVisibilityChange(keys: Set<Key>) {\n setNodes(actions.onVisibilityChange(keys));\n }\n\n return {\n nodes,\n actions: {\n // Expansion\n collapseAll,\n expandAll,\n onExpandedChange,\n\n // Selection\n selectAll,\n unselectAll,\n onSelectionChange,\n\n // Visibility\n hideAll,\n revealAll,\n onVisibilityChange,\n },\n dragAndDropConfig,\n };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,SAAgB,aAAgB,EAC9B,OACA,mBAAmB,SACuB;CAC1C,MAAM,CAAC,OAAO,YAAY,SAAS,MAAM;CACzC,MAAM,UAAU,eAAkB;EAAE;EAAO;EAAkB,CAAC;CAE9D,MAAMA,oBAAuC;EAC3C,WAAW,SACT,CAAC,GAAG,KAAK,CAAC,KAAK,QAAQ;GACrB,MAAM,OAAO,QAAQ,QAAQ,IAAI;AAEjC,UAAO;IACL,KAAK,GAAG;IACR,cAAc,KAAK,UAAU,KAAK;IACnC;IACD;EACJ,WAAW,EAAE,gBAAO,aAAiD;AACnE,IAAC,YAAY;IACX,MAAM,iBAAiB,MAAM,oBAC3BC,SACA,kBAAkB,qBAAqB,EAAE,CAC1C;AAED,aACE,QAAQ,OAAO,IAAI,IAAI,eAAe,KAAK,SAAS,KAAK,GAAG,CAAC,CAAC,CAC/D;AAED,QAAI,OAAO,iBAAiB,SAC1B,UAAS,QAAQ,aAAa,OAAO,KAAK,eAAe,CAAC;aACjD,OAAO,iBAAiB,QACjC,UAAS,QAAQ,YAAY,OAAO,KAAK,eAAe,CAAC;OAEzD;;EAEN,aAAa,EAAE,qBAA8C;AAC3D,IAAC,YAAY;IACX,MAAM,iBAAiB,MAAM,oBAC3BA,SACA,kBAAkB,qBAAqB,EAAE,CAC1C;AAED,aACE,QAAQ,OAAO,IAAI,IAAI,eAAe,KAAK,SAAS,KAAK,IAAI,CAAC,CAAC,CAChE;AACD,aAAS,QAAQ,YAAY,MAAM,eAAe,CAAC;OACjD;;EAEN,SAAS,MAAM;AACb,OAAI,EAAE,OAAO,iBAAiB,SAC5B,UAAS,QAAQ,WAAW,EAAE,OAAO,KAAK,EAAE,KAAK,CAAC;YACzC,EAAE,OAAO,iBAAiB,QACnC,UAAS,QAAQ,UAAU,EAAE,OAAO,KAAK,EAAE,KAAK,CAAC;YACxC,EAAE,OAAO,iBAAiB,MAEnC;QADmB,QAAQ,QAAQ,EAAE,OAAO,IAAI,CAE9C,UAAS,QAAQ,SAAS,EAAE,OAAO,KAAK,EAAE,KAAK,CAAC;;;EAIvD;CAED,SAAS,cAAc;AACrB,WAAS,QAAQ,aAAa,CAAC;;CAGjC,SAAS,YAAY;AACnB,WAAS,QAAQ,WAAW,CAAC;;CAG/B,SAAS,iBAAiB,MAAgB;AACxC,WAAS,QAAQ,iBAAiB,KAAK,CAAC;;CAG1C,SAAS,YAAY;AACnB,WAAS,QAAQ,WAAW,CAAC;;CAG/B,SAAS,cAAc;AACrB,WAAS,QAAQ,aAAa,CAAC;;CAGjC,SAAS,kBAAkB,MAAiB;AAC1C,MAAI,SAAS,MACX,QAAO,WAAW;AAGpB,WAAS,QAAQ,kBAAkB,KAAK,CAAC;;CAG3C,SAAS,UAAU;AACjB,WAAS,QAAQ,SAAS,CAAC;;CAG7B,SAAS,YAAY;AACnB,WAAS,QAAQ,WAAW,CAAC;;CAG/B,SAAS,mBAAmB,MAAgB;AAC1C,WAAS,QAAQ,mBAAmB,KAAK,CAAC;;AAG5C,QAAO;EACL;EACA,SAAS;GAEP;GACA;GACA;GAGA;GACA;GACA;GAGA;GACA;GACA;GACD;EACD;EACD"}

package/dist/hooks/use-tree/state/utils.d.ts CHANGED Viewed

@@ -13,8 +13,36 @@
 import { DropItem, TextDropItem } from "@react-types/shared";
 //#region src/hooks/use-tree/state/utils.d.ts
+/**
+ * Filters and processes an array of drop items into parsed tree node data.
+ *
+ * Filters to text items only, then processes each using supported drag types.
+ *
+ * @param items - Drop items from a drag-and-drop event.
+ * @param acceptedDragTypes - MIME types to accept when reading item payloads.
+ * @returns Array of parsed node objects from the dropped items.
+ */
 declare function processDroppedItems(items: DropItem[], acceptedDragTypes: string[]): Promise<any[]>;
+/**
+ * Processes a single text drop item into parsed tree node data.
+ *
+ * @param item - A text drop item from a drag-and-drop event.
+ * @param acceptedDragTypes - MIME types to attempt reading from the item.
+ * @returns Parsed node object from the first matching drag type payload.
+ * @throws {Error} When no payload matching any accepted drag type is found.
+ */
 declare function processDroppedItem(item: TextDropItem, acceptedDragTypes: string[]): Promise<any>;
+/**
+ * Reads the text payload from a drop item for the first matching drag type.
+ *
+ * Uses `Promise.any` — returns the payload from whichever accepted drag type
+ * resolves first.
+ *
+ * @param item - A text drop item from a drag-and-drop event.
+ * @param acceptedDragTypes - MIME types to attempt reading in order.
+ * @returns The raw text payload string for the first matching drag type.
+ * @throws {AggregateError} When no accepted drag type has a payload.
+ */
 declare function getDroppedItemPayload(item: TextDropItem, acceptedDragTypes: string[]): Promise<string>;
 //#endregion
 export { getDroppedItemPayload, processDroppedItem, processDroppedItems };