@itwin/presentation-hierarchies 2.0.0-alpha.12 → 2.0.0-alpha.14

package/lib/esm/hierarchies/HierarchySearch.js

@@ -2,38 +2,11 @@
  * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
+import { firstValueFrom, from, map, reduce } from "rxjs";
+import { Dictionary } from "@itwin/core-bentley";
 import { HierarchyNodeIdentifier } from "./HierarchyNodeIdentifier.js";
 import { HierarchyNodeKey } from "./HierarchyNodeKey.js";
-var HierarchySearchPathOptions;
-(function (HierarchySearchPathOptions) {
-    function mergeRevealOptions(lhs, rhs) {
-        if (rhs === true || lhs === true) {
-            return true;
-        }
-        if (!rhs || !lhs) {
-            return !!rhs ? rhs : lhs;
-        }
-        const lhsDepth = "depthInPath" in lhs ? lhs.depthInPath : lhs.depthInHierarchy;
-        const rhsDepth = "depthInPath" in rhs ? rhs.depthInPath : rhs.depthInHierarchy;
-        const isLhsDepthBasedOnPath = "depthInPath" in lhs;
-        const isRhsDepthBasedOnPath = "depthInPath" in rhs;
-        if (isLhsDepthBasedOnPath) {
-            if (isRhsDepthBasedOnPath) {
-                return lhsDepth > rhsDepth ? lhs : rhs;
-            }
-            return lhs;
-        }
-        if (isRhsDepthBasedOnPath) {
-            return rhs;
-        }
-        return lhsDepth > rhsDepth ? lhs : rhs;
-    }
-    HierarchySearchPathOptions.mergeRevealOptions = mergeRevealOptions;
-    function mergeAutoExpandOption(lhs, rhs) {
-        return lhs || rhs ? true : undefined;
-    }
-    HierarchySearchPathOptions.mergeAutoExpandOption = mergeAutoExpandOption;
-})(HierarchySearchPathOptions || (HierarchySearchPathOptions = {}));
+import { releaseMainThreadOnItemsCount } from "./internal/operators/ReleaseMainThread.js";
 /** @public */
 // eslint-disable-next-line @typescript-eslint/no-redeclare
 export var HierarchySearchPath;
@@ -57,14 +30,14 @@ export var HierarchySearchPath;
      * - else if only one of the inputs is an object, return it,
      * - else if both inputs are falsy, return `false` or `undefined`,
      * - else:
-     *    - if only one of the inputs has `depthInHierarchy` set, return the other one,
-     *    - else return the one with greater `depthInPath` or `depthInHierarchy`.
+     *    - if only one of the inputs has `groupingLevel` set, return that one,
+     *    - else compare by matching reveal type (`groupingLevel` or `depthInPath`) and return the deeper one.
      *
      * @public
      */
     function mergeOptions(lhs, rhs) {
-        const reveal = HierarchySearchPathOptions.mergeRevealOptions(lhs?.reveal, rhs?.reveal);
-        const autoExpand = HierarchySearchPathOptions.mergeAutoExpandOption(lhs?.autoExpand, rhs?.autoExpand);
+        const reveal = mergeRevealOptions(lhs?.reveal, rhs?.reveal);
+        const autoExpand = mergeAutoExpandOption(lhs?.autoExpand, rhs?.autoExpand);
         return reveal || autoExpand
             ? {
                 ...(reveal !== undefined ? { reveal } : undefined),
@@ -73,7 +46,264 @@ export var HierarchySearchPath;
             : undefined;
     }
     HierarchySearchPath.mergeOptions = mergeOptions;
+    function mergeRevealOptions(lhs, rhs) {
+        if (rhs === true || lhs === true) {
+            return true;
+        }
+        if (!rhs || !lhs) {
+            return !!rhs ? rhs : lhs;
+        }
+        if ("groupingLevel" in lhs) {
+            if ("groupingLevel" in rhs) {
+                return lhs.groupingLevel > rhs.groupingLevel ? lhs : rhs;
+            }
+            return lhs;
+        }
+        else if ("groupingLevel" in rhs) {
+            return rhs;
+        }
+        return lhs.depthInPath > rhs.depthInPath ? lhs : rhs;
+    }
+    function mergeAutoExpandOption(lhs, rhs) {
+        return lhs || rhs ? true : undefined;
+    }
 })(HierarchySearchPath || (HierarchySearchPath = {}));
+/** @public */
+export var HierarchySearchTree;
+(function (HierarchySearchTree) {
+    /**
+     * Create a `HierarchySearchTree` builder utility that accepts hierarchy search paths or search trees one by one and builds
+     * a `HierarchySearchTree` structure based on them.
+     *
+     * Usage example:
+     *
+     * ```ts
+     * const builder = HierarchySearchTree.createBuilder();
+     * for (const path of searchPaths) {
+     *   builder.accept({ path });
+     * }
+     * const searchTree = builder.getTree();
+     * ```
+     *
+     * @public
+     */
+    function createBuilder() {
+        var _a;
+        return new (class Impl {
+            #rootsDictionary = new Dictionary(HierarchyNodeIdentifier.compare);
+            static #mapDictionaryToTree(dictionary, parentEntries, props) {
+                const list = [];
+                for (const { children, ...entry } of dictionary.values()) {
+                    let processedEntry = entry;
+                    if (props?.processEntry) {
+                        processedEntry = props.processEntry({ treeEntry: entry, parentEntries });
+                    }
+                    if (!processedEntry) {
+                        continue;
+                    }
+                    const { extras: _, ...entryWithoutExtras } = processedEntry;
+                    parentEntries.push(processedEntry);
+                    list.push({ ...entryWithoutExtras, ...(children ? { children: Impl.#mapDictionaryToTree(children, parentEntries, props) } : undefined) });
+                    parentEntries.pop();
+                }
+                return list;
+            }
+            static #assignAutoExpandOptionsBasedOnReveal(treePath, revealOption) {
+                if (revealOption === true) {
+                    Impl.#assignOptionsOnTreePath({
+                        treePath,
+                        targetEntryIndex: treePath.length - 1,
+                        getEntryOptions: (index, targetEntryIndex) => {
+                            if (index === targetEntryIndex) {
+                                // auto-expand all grouping nodes of the revealed node
+                                return { autoExpand: { groupingLevel: Number.MAX_SAFE_INTEGER } };
+                            }
+                            // auto-expand all parent nodes
+                            return { autoExpand: true };
+                        },
+                    });
+                }
+                else if (revealOption && "groupingLevel" in revealOption) {
+                    Impl.#assignOptionsOnTreePath({
+                        treePath,
+                        targetEntryIndex: treePath.length - 1,
+                        getEntryOptions: (index, targetEntryIndex) => {
+                            if (index === targetEntryIndex) {
+                                // the last entry should have `autoExpand` with `groupingLevel` set to the value based on `reveal.groupingLevel`
+                                return { autoExpand: { groupingLevel: Math.max(revealOption.groupingLevel - 1, 0) } };
+                            }
+                            // auto-expand all parent nodes
+                            return { autoExpand: true };
+                        },
+                    });
+                }
+                else if (revealOption && "depthInPath" in revealOption) {
+                    Impl.#assignOptionsOnTreePath({
+                        treePath,
+                        targetEntryIndex: Math.min(revealOption.depthInPath, treePath.length - 1),
+                        getEntryOptions: (index, targetEntryIndex) => {
+                            if (index === targetEntryIndex) {
+                                // auto-expand all grouping nodes of the revealed node
+                                return { autoExpand: { groupingLevel: Number.MAX_SAFE_INTEGER } };
+                            }
+                            // auto-expand all parent nodes
+                            return { autoExpand: true };
+                        },
+                    });
+                }
+            }
+            static #assignOptionsOnTreePath({ treePath, targetEntryIndex, getEntryOptions, }) {
+                // set all parent entries to auto-expand
+                for (let i = 0; i <= targetEntryIndex; i++) {
+                    const options = mergeOptions(treePath[i].options, getEntryOptions(i, targetEntryIndex));
+                    if (options) {
+                        treePath[i].options = options;
+                    }
+                }
+            }
+            #acceptNode({ parentEntries, level, node, handler, }) {
+                let entry = level.get(node.identifier);
+                if (!entry) {
+                    if (handler?.onNewEntry && !handler.onNewEntry({ parentEntries, inputEntry: node })) {
+                        return undefined;
+                    }
+                    entry = {
+                        identifier: node.identifier,
+                        children: node.hasChildren ? new Dictionary(HierarchyNodeIdentifier.compare) : undefined,
+                        extras: {},
+                    };
+                    level.set(node.identifier, entry);
+                }
+                const isNodeSearchTarget = node.isTarget || !node.hasChildren;
+                if (isNodeSearchTarget && entry.children) {
+                    entry.isTarget = true;
+                }
+                if (!entry.children && node.hasChildren) {
+                    // Existing leaf nodes are implied targets. Preserve that status when adding children.
+                    entry.isTarget = true;
+                    entry.children = new Dictionary(HierarchyNodeIdentifier.compare);
+                }
+                handler?.onEntryHandled?.({ parentEntries, treeEntry: entry, inputEntry: node });
+                return entry;
+            }
+            #acceptPath({ path, handler }) {
+                const normalized = HierarchySearchPath.normalize(path);
+                const treePath = [];
+                let currentLevel = this.#rootsDictionary;
+                for (let i = 0; i < normalized.path.length; i++) {
+                    const identifier = normalized.path[i];
+                    const acceptedNode = this.#acceptNode({
+                        parentEntries: treePath,
+                        node: { identifier, hasChildren: i < normalized.path.length - 1 },
+                        level: currentLevel,
+                        handler,
+                    });
+                    if (!acceptedNode) {
+                        break;
+                    }
+                    treePath.push(acceptedNode);
+                    if (!acceptedNode.children) {
+                        break;
+                    }
+                    currentLevel = acceptedNode.children;
+                }
+                if (treePath.length === 0) {
+                    return;
+                }
+                // handle auto-expand
+                const lastNode = treePath[treePath.length - 1];
+                if (normalized.options?.autoExpand) {
+                    (lastNode.options ??= {}).autoExpand = true;
+                }
+                // handle auto-reveal
+                Impl.#assignAutoExpandOptionsBasedOnReveal(treePath, normalized.options?.reveal);
+            }
+            #acceptTree({ tree, handler }) {
+                const acceptTreeNode = (parentEntries, parentInputs, level, node) => {
+                    const acceptedNode = this.#acceptNode({
+                        parentEntries,
+                        node: { ...node, hasChildren: node.children !== undefined },
+                        level,
+                        handler,
+                    });
+                    if (!acceptedNode) {
+                        // It was decided to reject this node and its children, if any
+                        return;
+                    }
+                    const treePath = [...parentEntries, acceptedNode];
+                    const inputsPath = [...parentInputs, node];
+                    if (!node.children || node.isTarget) {
+                        // Found an effective search target - merge options from its path
+                        Impl.#assignOptionsOnTreePath({
+                            treePath,
+                            targetEntryIndex: treePath.length - 1,
+                            getEntryOptions: (index) => inputsPath[index].options,
+                        });
+                    }
+                    const currentLevel = acceptedNode.children;
+                    if (currentLevel) {
+                        node.children?.forEach((child) => acceptTreeNode(treePath, inputsPath, currentLevel, child));
+                    }
+                };
+                acceptTreeNode([], [], this.#rootsDictionary, tree);
+            }
+            accept(props) {
+                if ("path" in props) {
+                    this.#acceptPath(props);
+                }
+                else {
+                    this.#acceptTree(props);
+                }
+                return this;
+            }
+            getTree(props) {
+                return Impl.#mapDictionaryToTree(this.#rootsDictionary, [], props);
+            }
+        })();
+    }
+    HierarchySearchTree.createBuilder = createBuilder;
+    /**
+     * Builds a list of `HierarchySearchTree` nodes from an iterable of search paths. Shared
+     * path prefixes are merged so that each unique hierarchy node identifier appears only once
+     * per level. The resulting trees carry `isTarget`, `options`, and `children` attributes
+     * derived from the paths and their options (`autoExpand`, `reveal`).
+     *
+     * @public
+     */
+    async function createFromPathsList(paths) {
+        return firstValueFrom(from(paths).pipe(releaseMainThreadOnItemsCount(1000), reduce((builder, path) => builder.accept({ path }), createBuilder()), map((builder) => builder.getTree())));
+    }
+    HierarchySearchTree.createFromPathsList = createFromPathsList;
+    /**
+     * Merges two `HierarchySearchTree` option objects. For the `autoExpand` attribute,
+     * `true` takes precedence over `{ groupingLevel }`, and when both sides are
+     * `{ groupingLevel }` objects the larger value wins.
+     * @public
+     */
+    function mergeOptions(lhs, rhs) {
+        if (!lhs) {
+            return rhs;
+        }
+        if (!rhs) {
+            return lhs;
+        }
+        const autoExpand = mergeSearchTreeAutoExpandOption(lhs.autoExpand, rhs.autoExpand);
+        const options = {
+            ...(autoExpand ? { autoExpand } : undefined),
+        };
+        return Object.keys(options).length > 0 ? options : undefined;
+    }
+    HierarchySearchTree.mergeOptions = mergeOptions;
+    function mergeSearchTreeAutoExpandOption(lhs, rhs) {
+        if (!lhs) {
+            return rhs;
+        }
+        if (!rhs) {
+            return lhs;
+        }
+        return lhs === true || rhs === true ? true : { groupingLevel: Math.max(lhs.groupingLevel, rhs.groupingLevel) };
+    }
+})(HierarchySearchTree || (HierarchySearchTree = {}));
 function extractSearchPropsInternal(rootLevelSearchProps, parentNode) {
     if (!parentNode) {
         return rootLevelSearchProps ? { childrenTargetPaths: rootLevelSearchProps, hasSearchTargetAncestor: false } : undefined;
@@ -94,41 +324,37 @@ export function createHierarchySearchHelper(rootLevelSearchProps, parentNode) {
     const searchProps = extractSearchPropsInternal(rootLevelSearchProps, parentNode);
     const hasSearch = !!searchProps;
     function saveSearchPropsFromPathsIntoReducer(extractionProps) {
-        // Passes down matching normalized paths to the reducer.
-        // It uses `nodeKey`, `pathMatcher` or `asyncPathMatcher` to check if `HierarchyNodeIdentifier` at the first position in search path matches the node
+        // Passes down matching hierarchy search trees to the reducer.
+        // It uses `nodeKey`, `pathMatcher` or `asyncPathMatcher` to check if `HierarchyNodeIdentifier` in the search tree item's identifier matches the node
         // and if it does, the path is passed down to the reducer.
-        // This function returns a promise only if asyncPathMatcher returns a promise.
+        // This function returns a promise only if `asyncPathMatcher` returns a promise.
         if (!searchProps?.childrenTargetPaths) {
             return;
         }
-        const matchedPathPromises = new Array();
-        for (const childrenTargetPaths of searchProps.childrenTargetPaths) {
-            const normalizedPath = HierarchySearchPath.normalize(childrenTargetPaths);
-            /* c8 ignore next 3 */
-            if (normalizedPath.path.length === 0) {
-                continue;
-            }
-            if ("nodeKey" in extractionProps) {
-                if ((HierarchyNodeKey.isGeneric(extractionProps.nodeKey) && HierarchyNodeIdentifier.equal(normalizedPath.path[0], extractionProps.nodeKey)) ||
-                    (HierarchyNodeKey.isInstances(extractionProps.nodeKey) &&
-                        extractionProps.nodeKey.instanceKeys.some((ik) => HierarchyNodeIdentifier.equal(normalizedPath.path[0], ik)))) {
-                    extractionProps.pathsReducer.accept(normalizedPath);
+        const matchedTreePromises = new Array();
+        for (const childrenSearchTree of searchProps.childrenTargetPaths) {
+            if ("asyncPathMatcher" in extractionProps) {
+                const matchesPossiblyPromise = extractionProps.asyncPathMatcher(childrenSearchTree.identifier);
+                if (matchesPossiblyPromise instanceof Promise) {
+                    matchedTreePromises.push(matchesPossiblyPromise.then((matches) => (matches ? childrenSearchTree : undefined)));
+                }
+                else if (matchesPossiblyPromise) {
+                    extractionProps.pathsReducer.accept(childrenSearchTree);
                 }
-                continue;
-            }
-            const matchesPossiblyPromise = "pathMatcher" in extractionProps ? extractionProps.pathMatcher(normalizedPath.path[0]) : extractionProps.asyncPathMatcher(normalizedPath.path[0]);
-            if (matchesPossiblyPromise instanceof Promise) {
-                matchedPathPromises.push(matchesPossiblyPromise.then((matches) => (matches ? normalizedPath : undefined)));
-                continue;
             }
-            if (matchesPossiblyPromise) {
-                extractionProps.pathsReducer.accept(normalizedPath);
+            else {
+                const matches = "pathMatcher" in extractionProps
+                    ? extractionProps.pathMatcher(childrenSearchTree.identifier)
+                    : nodeKeyMatchesIdentifier(extractionProps.nodeKey, childrenSearchTree.identifier);
+                if (matches) {
+                    extractionProps.pathsReducer.accept(childrenSearchTree);
+                }
             }
         }
-        if (matchedPathPromises.length === 0) {
+        if (matchedTreePromises.length === 0) {
             return;
         }
-        return Promise.all(matchedPathPromises).then((matchedPath) => matchedPath.forEach((normalizedPath) => normalizedPath && extractionProps.pathsReducer.accept(normalizedPath)));
+        return Promise.all(matchedTreePromises).then((matchedTrees) => matchedTrees.forEach((matchedTree) => matchedTree && extractionProps.pathsReducer.accept(matchedTree)));
     }
     function createChildNodeProps(props) {
         if (!hasSearch) {
@@ -136,15 +362,15 @@ export function createHierarchySearchHelper(rootLevelSearchProps, parentNode) {
         }
         const reducer = new MatchingSearchPathsReducer(searchProps.hasSearchTargetAncestor);
         if ("asyncPathMatcher" in props) {
-            const extractResult = saveSearchPropsFromPathsIntoReducer({ pathsReducer: reducer, asyncPathMatcher: props.asyncPathMatcher });
+            const extractResult = saveSearchPropsFromPathsIntoReducer({ pathsReducer: reducer, nodeKey: props.nodeKey, asyncPathMatcher: props.asyncPathMatcher });
             if (extractResult instanceof Promise) {
-                return extractResult.then(() => reducer.getNodeProps(props.parentKeys));
+                return extractResult.then(() => reducer.aggregatedOptions);
             }
         }
         else {
-            saveSearchPropsFromPathsIntoReducer({ ...props, pathsReducer: reducer });
+            saveSearchPropsFromPathsIntoReducer({ pathsReducer: reducer, ...props });
         }
-        return reducer.getNodeProps(props.parentKeys);
+        return reducer.aggregatedOptions;
     }
     return {
         /** Returns a flag indicating if the hierarchy level is filtered. */
@@ -164,10 +390,7 @@ export function createHierarchySearchHelper(rootLevelSearchProps, parentNode) {
             if (!searchProps?.childrenTargetPaths) {
                 return undefined;
             }
-            return searchProps.childrenTargetPaths
-                .map(HierarchySearchPath.normalize)
-                .filter(({ path }) => path.length > 0)
-                .map(({ path }) => path[0]);
+            return searchProps.childrenTargetPaths.map(({ identifier }) => identifier);
         },
         /**
          * When a hierarchy node is created for a filtered hierarchy level, it needs some attributes (e.g. `search`
@@ -179,13 +402,16 @@ export function createHierarchySearchHelper(rootLevelSearchProps, parentNode) {
          * `nodeKey` prop can be used to check the whole identifier.
          *
          * There are multiple overloads of `createChildNodeProps`: depending on props type it returns different values:
-         * - `parentKeys` is defined and `pathMatcher` or `nodeKey` is provided - returns undefined **or** `search` and `autoExpand` prop from `HierarchyNode`;
-         * - `parentKeys` is undefined - does not return `HierarchyNode.autoExpand` option;
-         * - props have `asyncPathMatcher` - returns either Promise or the regular return value based on whether or not `asyncPathMatcher` returns a promise.
+         * - `asyncPathMatcher` is provided - returns either Promise or the regular return value based on whether or not `asyncPathMatcher` returns a `Promise`.
+         * - `pathMatcher` or only `nodeKey` is provided - returns undefined **or** `search` and `autoExpand` prop from `HierarchyNode`;
          */
         createChildNodeProps,
     };
 }
+function nodeKeyMatchesIdentifier(nodeKey, identifier) {
+    return ((HierarchyNodeKey.isGeneric(nodeKey) && HierarchyNodeIdentifier.equal(identifier, nodeKey)) ||
+        (HierarchyNodeKey.isInstances(nodeKey) && nodeKey.instanceKeys.some((ik) => HierarchyNodeIdentifier.equal(identifier, ik))));
+}
 /**
  * Extracts information from search paths and later returns `search` and `autoExpand` values from `HierarchyNode`.
  *
@@ -199,56 +425,33 @@ class MatchingSearchPathsReducer {
     _hasSearchTargetAncestor;
     _childrenTargetPaths = new Array();
     _isSearchTarget = false;
-    _searchTargetOptions = undefined;
-    _revealOption = false;
+    _options = undefined;
     constructor(_hasSearchTargetAncestor) {
         this._hasSearchTargetAncestor = _hasSearchTargetAncestor;
     }
-    accept(normalizedPath) {
-        const { path, options } = normalizedPath;
-        if (path.length === 1) {
+    accept(tree) {
+        if (tree.isTarget || tree.children === undefined) {
             this._isSearchTarget = true;
-            this._searchTargetOptions = HierarchySearchPath.mergeOptions(this._searchTargetOptions, options);
         }
-        else if (path.length > 1) {
-            this._childrenTargetPaths.push({ path: path.slice(1), options });
-            this._revealOption = HierarchySearchPathOptions.mergeRevealOptions(options?.reveal, this._revealOption);
+        if (tree.children && tree.children.length > 0) {
+            this._childrenTargetPaths.push(...tree.children);
         }
+        this._options = HierarchySearchTree.mergeOptions(this._options, tree.options);
     }
-    getNodeProps(parentKeys) {
+    get aggregatedOptions() {
+        const search = this._hasSearchTargetAncestor || this._isSearchTarget || this._childrenTargetPaths.length > 0 || this._options
+            ? {
+                ...(this._hasSearchTargetAncestor ? { hasSearchTargetAncestor: true } : undefined),
+                ...(this._isSearchTarget ? { isSearchTarget: true } : undefined),
+                ...(this._childrenTargetPaths.length > 0 ? { childrenTargetPaths: this._childrenTargetPaths } : undefined),
+                ...(this._options ? { options: this._options } : undefined),
+            }
+            : undefined;
+        const autoExpand = this._options?.autoExpand === true;
         return {
-            ...(this._hasSearchTargetAncestor || this._isSearchTarget || this._childrenTargetPaths.length > 0
-                ? {
-                    search: {
-                        ...(this._hasSearchTargetAncestor ? { hasSearchTargetAncestor: true } : undefined),
-                        ...(this._isSearchTarget ? { isSearchTarget: true, searchTargetOptions: this._searchTargetOptions } : undefined),
-                        ...(this._childrenTargetPaths.length > 0 ? { childrenTargetPaths: this._childrenTargetPaths } : undefined),
-                    },
-                }
-                : undefined),
-            ...(parentKeys &&
-                (shouldAutoExpandBasedOnReveal({
-                    reveal: this._revealOption,
-                    nodePositionInHierarchy: parentKeys.length,
-                    nodePositionInPath: parentKeys.filter((key) => !HierarchyNodeKey.isGrouping(key)).length,
-                }) ||
-                    !!this._searchTargetOptions?.autoExpand)
-                ? { autoExpand: true }
-                : undefined),
+            ...(search ? { search } : undefined),
+            ...(autoExpand ? { autoExpand } : undefined),
         };
     }
 }
-/** @internal */
-export function shouldAutoExpandBasedOnReveal({ reveal, nodePositionInPath, nodePositionInHierarchy, }) {
-    if (!reveal) {
-        return false;
-    }
-    if (reveal === true) {
-        return true;
-    }
-    if ("depthInHierarchy" in reveal) {
-        return nodePositionInHierarchy < reveal.depthInHierarchy;
-    }
-    return nodePositionInPath < reveal.depthInPath;
-}
 //# sourceMappingURL=HierarchySearch.js.map