@react-hive/honey-utils 3.21.0 → 3.23.0

package/dist/index.dev.cjs

@@ -2118,7 +2118,7 @@ __webpack_require__.r(__webpack_exports__);
  * - Temporary UI keys (e.g. React lists, animations)
  * - In-memory references scoped to a single runtime
  *
- * @returns An ephemeral identifier string.
+ * @returns An ephemeral string identifier.
  */
 const generateEphemeralId = () => {
     const timestampPart = Math.floor(performance.now() * 1000).toString(36);
@@ -2793,6 +2793,315 @@ __webpack_require__.r(__webpack_exports__);
 const toKebabCase = (input) => input.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 
 
+/***/ }),
+
+/***/ "./src/tree/flatten-tree.ts":
+/*!**********************************!*\
+  !*** ./src/tree/flatten-tree.ts ***!
+  \**********************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   flattenTree: () => (/* binding */ flattenTree)
+/* harmony export */ });
+/**
+ * Flattens a hierarchical tree into a single preorder array.
+ *
+ * Each node in the returned list is stripped of its nested children property
+ * (`childrenKey`) and enriched with hierarchy metadata:
+ *
+ * - `parentId` — identifier of the parent node (`undefined` for roots)
+ * - `depthLevel` — nesting depth starting at `0`
+ * - `childCount` — number of direct child nodes
+ *
+ * The flattening order is **preorder**, meaning parents always appear before
+ * their descendants. This representation is especially useful for rendering
+ * tree-based UIs such as TreeSelect components, nested menus, and folder pickers.
+ *
+ * @template OriginItem - Original node shape of the hierarchical structure.
+ *
+ * @param items - Root-level nodes to flatten. If undefined, an empty array is returned.
+ * @param nodeIdKey - Key that uniquely identifies each node.
+ * @param childrenKey - Key containing the nested child node array.
+ *
+ * @param flatTree - Internal accumulator used during recursion.
+ * @param parentId - Parent identifier for the current recursion level.
+ * @param depthLevel - Current depth level, where `0` represents the root.
+ *
+ * @returns A flat preorder list of tree nodes with hierarchy metadata attached,
+ *          excluding the original children property.
+ *
+ * @example
+ * ```ts
+ * const tree = [
+ *   {
+ *     id: 1,
+ *     name: 'Root',
+ *     children: [{ id: 2, name: 'Child', children: [] }],
+ *   },
+ * ];
+ *
+ * const flatTree = flattenTree(tree, 'id', 'children');
+ *
+ * // [
+ * //   { id: 1, name: 'Root', parentId: undefined, depthLevel: 0, childCount: 1 },
+ * //   { id: 2, name: 'Child', parentId: 1, depthLevel: 1, childCount: 0 }
+ * // ]
+ * ```
+ */
+const flattenTree = (items, nodeIdKey, childrenKey, 
+///
+flatTree = [], parentId = undefined, depthLevel = 0) => {
+    items?.forEach(item => {
+        const { [childrenKey]: _, ...nodeData } = item;
+        const children = item[childrenKey];
+        const hasChildrenArray = Array.isArray(children);
+        flatTree.push({
+            ...nodeData,
+            parentId,
+            depthLevel,
+            childCount: hasChildrenArray ? children.length : 0,
+        });
+        if (hasChildrenArray) {
+            const parentId = item[nodeIdKey];
+            flattenTree(children, nodeIdKey, childrenKey, flatTree, parentId, depthLevel + 1);
+        }
+    });
+    return flatTree;
+};
+
+
+/***/ }),
+
+/***/ "./src/tree/get-tree-children.ts":
+/*!***************************************!*\
+  !*** ./src/tree/get-tree-children.ts ***!
+  \***************************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   getTreeChildren: () => (/* binding */ getTreeChildren)
+/* harmony export */ });
+/**
+ * Returns the direct children of a given parent node from a flattened tree.
+ *
+ * This helper filters a flat tree representation (`HoneyTreeFlatNode`) and
+ * selects only nodes whose `parentId` matches the provided identifier.
+ *
+ * ⚠️ Only direct children are returned - descendants at deeper levels are not included.
+ *
+ * An optional predicate may be provided to further narrow the result set
+ * (e.g. filtering by depth, type, or custom node flags).
+ *
+ * @template OriginItem - Original node shape of the hierarchical structure.
+ * @template ChildrenKey - Key of the removed nested children property.
+ *
+ * @param flatTree - Flat preorder list of tree nodes containing hierarchy metadata.
+ * @param parentId - Identifier of the parent node whose direct children should be returned.
+ * @param predicate - Optional additional filter applied to each matched child node.
+ *
+ * @returns An array of nodes that are direct children of the specified parent.
+ *
+ * @example
+ * ```ts
+ * const children = getTreeChildren(flatTree, 1);
+ *
+ * // Returns all nodes where parentId === 1
+ * ```
+ *
+ * @example
+ * ```ts
+ * const shallowChildren = getTreeChildren(
+ *   flatTree,
+ *   1,
+ *   node => node.depthLevel <= 2,
+ * );
+ *
+ * // Returns only children of node 1 that satisfy the predicate.
+ * ```
+ */
+const getTreeChildren = (flatTree, parentId, predicate) => flatTree.filter(node => node.parentId === parentId && (!predicate || predicate(node)));
+
+
+/***/ }),
+
+/***/ "./src/tree/index.ts":
+/*!***************************!*\
+  !*** ./src/tree/index.ts ***!
+  \***************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   flattenTree: () => (/* reexport safe */ _flatten_tree__WEBPACK_IMPORTED_MODULE_1__.flattenTree),
+/* harmony export */   getTreeChildren: () => (/* reexport safe */ _get_tree_children__WEBPACK_IMPORTED_MODULE_2__.getTreeChildren),
+/* harmony export */   searchTree: () => (/* reexport safe */ _search_tree__WEBPACK_IMPORTED_MODULE_3__.searchTree)
+/* harmony export */ });
+/* harmony import */ var _tree_types__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./tree.types */ "./src/tree/tree.types.ts");
+/* harmony import */ var _flatten_tree__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./flatten-tree */ "./src/tree/flatten-tree.ts");
+/* harmony import */ var _get_tree_children__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(/*! ./get-tree-children */ "./src/tree/get-tree-children.ts");
+/* harmony import */ var _search_tree__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(/*! ./search-tree */ "./src/tree/search-tree.ts");
+
+
+
+
+
+
+/***/ }),
+
+/***/ "./src/tree/search-tree.ts":
+/*!*********************************!*\
+  !*** ./src/tree/search-tree.ts ***!
+  \*********************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   searchTree: () => (/* binding */ searchTree)
+/* harmony export */ });
+/* harmony import */ var _guards__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/guards */ "./src/guards.ts");
+/* harmony import */ var _string__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ~/string */ "./src/string/index.ts");
+
+
+/**
+ * Performs a context-aware search over a flattened tree.
+ *
+ * Matching is applied to the provided string field (`nodeValueKey`) using
+ * **case-insensitive, word-prefix comparison**:
+ *
+ * - The query is split into words
+ * - Each query word must match the start of at least one word in the node value
+ *
+ * Unlike a simple filter, this function preserves hierarchical context:
+ *
+ * - When a nested node matches, all of its ancestor nodes are included, so the
+ *   result remains navigable.
+ * - When a root node matches, its full descendant subtree is included so the
+ *   hierarchy stays intact.
+ *
+ * This makes the utility ideal for searchable tree-based UIs such as
+ * TreeSelect components, folder pickers, nested menus, and grouped lists.
+ *
+ * @template OriginItem - Original node shape of the hierarchical structure.
+ * @template ChildrenKey - Key of the removed nested children property.
+ *
+ * @param flatTree - Flat preorder list of tree nodes containing hierarchy metadata.
+ * @param nodeIdKey - Key that uniquely identifies each node.
+ * @param nodeValueKey - Key containing the searchable string value (e.g. `"name"`).
+ * @param searchQuery - User input query. Split into words and matched by prefix.
+ *
+ * @returns A filtered flat list containing:
+ * - all matching nodes
+ * - their ancestor chain (for nested matches)
+ * - full descendant subtrees (for root-level matches)
+ *
+ * @example
+ * ```ts
+ * const results = searchTree(flatTree, 'id', 'label', 'kit che');
+ *
+ * // Matches nodes where words start with "kit" and "che"
+ * // (e.g. "Kitchen Chair"), including their parents.
+ * ```
+ *
+ * @example
+ * ```ts
+ * // If a deep child matches, ancestors are included:
+ * //
+ * // Root
+ * // └─ Category
+ * //    └─ Item ← matches
+ * //
+ * // Result includes: Root, Category, Item
+ * ```
+ */
+const searchTree = (flatTree, nodeIdKey, nodeValueKey, searchQuery) => {
+    const searchWords = (0,_string__WEBPACK_IMPORTED_MODULE_1__.splitStringIntoWords)(searchQuery.toLowerCase());
+    if (!searchWords.length) {
+        return flatTree;
+    }
+    const nodeIdToIndexMap = flatTree.reduce((result, node, nodeIndex) => {
+        // Map node id → index for fast ancestor lookup.
+        result[node[nodeIdKey]] = nodeIndex;
+        return result;
+    }, {});
+    return flatTree.reduce((matchedNodes, node) => {
+        const nodeValue = node[nodeValueKey];
+        // If the item value is null, undefined or empty string
+        if (!nodeValue) {
+            return matchedNodes;
+        }
+        if (matchedNodes.some(matchedNode => matchedNode[nodeIdKey] === node[nodeIdKey])) {
+            return matchedNodes;
+        }
+        const nodeValueWords = (0,_string__WEBPACK_IMPORTED_MODULE_1__.splitStringIntoWords)(nodeValue.toLowerCase());
+        const isNodeMatched = searchWords.every(searchWord => nodeValueWords.some(word => word.startsWith(searchWord)));
+        if (isNodeMatched) {
+            if ((0,_guards__WEBPACK_IMPORTED_MODULE_0__.isUndefined)(node.parentId)) {
+                matchedNodes.push(node);
+                const insertNestedItems = (targetNode) => {
+                    if (!targetNode.childCount) {
+                        return;
+                    }
+                    flatTree.forEach(node => {
+                        if (node.parentId === targetNode[nodeIdKey]) {
+                            matchedNodes.push(node);
+                            insertNestedItems(node);
+                        }
+                    });
+                };
+                insertNestedItems(node);
+            }
+            else {
+                const insertParentNodes = (targetNode) => {
+                    const parentNodeIndex = nodeIdToIndexMap[targetNode.parentId];
+                    const parentNode = flatTree[parentNodeIndex];
+                    if (!(0,_guards__WEBPACK_IMPORTED_MODULE_0__.isUndefined)(parentNode.parentId)) {
+                        insertParentNodes(parentNode);
+                    }
+                    const prevNodeParentId = matchedNodes.length
+                        ? matchedNodes[matchedNodes.length - 1].parentId
+                        : null;
+                    const shouldInsertParentNode = (0,_guards__WEBPACK_IMPORTED_MODULE_0__.isNull)(prevNodeParentId) || prevNodeParentId !== targetNode.parentId;
+                    if (shouldInsertParentNode) {
+                        (0,_guards__WEBPACK_IMPORTED_MODULE_0__.assert)(parentNode, '[@react-hive/honey-utils]: Parent node was not found.');
+                        matchedNodes.push(parentNode);
+                    }
+                };
+                insertParentNodes(node);
+                matchedNodes.push(node);
+            }
+        }
+        return matchedNodes;
+    }, []);
+};
+
+
+/***/ }),
+
+/***/ "./src/tree/tree.types.ts":
+/*!********************************!*\
+  !*** ./src/tree/tree.types.ts ***!
+  \********************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+
+
+
+/***/ }),
+
+/***/ "./src/types.ts":
+/*!**********************!*\
+  !*** ./src/types.ts ***!
+  \**********************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+
+
+
 /***/ })
 
 /******/ 	});
@@ -2884,12 +3193,14 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   filterSequential: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.filterSequential),
 /* harmony export */   findAsync: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.findAsync),
 /* harmony export */   findCharIndices: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_13__.findCharIndices),
+/* harmony export */   flattenTree: () => (/* reexport safe */ _tree__WEBPACK_IMPORTED_MODULE_14__.flattenTree),
 /* harmony export */   forEachChar: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_13__.forEachChar),
 /* harmony export */   generateEphemeralId: () => (/* reexport safe */ _id__WEBPACK_IMPORTED_MODULE_9__.generateEphemeralId),
 /* harmony export */   getDOMRectIntersectionRatio: () => (/* reexport safe */ _intersection__WEBPACK_IMPORTED_MODULE_10__.getDOMRectIntersectionRatio),
 /* harmony export */   getElementOffsetRect: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_3__.getElementOffsetRect),
 /* harmony export */   getFocusableHtmlElements: () => (/* reexport safe */ _a11y__WEBPACK_IMPORTED_MODULE_0__.getFocusableHtmlElements),
 /* harmony export */   getLocalStorageCapabilities: () => (/* reexport safe */ _env__WEBPACK_IMPORTED_MODULE_4__.getLocalStorageCapabilities),
+/* harmony export */   getTreeChildren: () => (/* reexport safe */ _tree__WEBPACK_IMPORTED_MODULE_14__.getTreeChildren),
 /* harmony export */   getWordsInitials: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_13__.getWordsInitials),
 /* harmony export */   getXOverflowWidth: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_3__.getXOverflowWidth),
 /* harmony export */   getYOverflowHeight: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_3__.getYOverflowHeight),
@@ -2942,6 +3253,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   retry: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.retry),
 /* harmony export */   runParallel: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.runParallel),
 /* harmony export */   runSequential: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.runSequential),
+/* harmony export */   searchTree: () => (/* reexport safe */ _tree__WEBPACK_IMPORTED_MODULE_14__.searchTree),
 /* harmony export */   someAsync: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.someAsync),
 /* harmony export */   splitStringIntoWords: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_13__.splitStringIntoWords),
 /* harmony export */   timeout: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.timeout),
@@ -2963,6 +3275,10 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _math__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(/*! ./math */ "./src/math/index.ts");
 /* harmony import */ var _object__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(/*! ./object */ "./src/object.ts");
 /* harmony import */ var _string__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(/*! ./string */ "./src/string/index.ts");
+/* harmony import */ var _tree__WEBPACK_IMPORTED_MODULE_14__ = __webpack_require__(/*! ./tree */ "./src/tree/index.ts");
+/* harmony import */ var _types__WEBPACK_IMPORTED_MODULE_15__ = __webpack_require__(/*! ./types */ "./src/types.ts");
+
+