@itwin/presentation-hierarchies 2.0.0-alpha.2 → 2.0.0-alpha.20

package/lib/{esm/hierarchies → hierarchies}/HierarchyProvider.d.ts

@@ -1,8 +1,7 @@
-import "./internal/DisposePolyfill.js";
-import { GenericInstanceFilter } from "@itwin/core-common";
-import { Event, InstanceKey, IPrimitiveValueFormatter, Props } from "@itwin/presentation-shared";
-import { HierarchyFilteringPath } from "./HierarchyFiltering.js";
-import { HierarchyNode, ParentHierarchyNode } from "./HierarchyNode.js";
+import type { GenericInstanceFilter } from "@itwin/core-common";
+import type { Event, EventListener, InstanceKey, IPrimitiveValueFormatter, Props, RaisableEvent } from "@itwin/presentation-shared";
+import type { HierarchyNode, ParentHierarchyNode } from "./HierarchyNode.js";
+import type { HierarchySearchTree } from "./HierarchySearch.js";
 /**
  * Props for the `HierarchyProvider.getNodes` call.
  * @public
@@ -32,9 +31,9 @@ interface HierarchyChangedEventArgs {
     formatterChange?: {
         newFormatter: IPrimitiveValueFormatter | undefined;
     };
-    /** Set when the hierarchy change was caused by a hierarchy filter change. */
-    filterChange?: {
-        newFilter: Props<HierarchyProvider["setHierarchyFilter"]>;
+    /** Set when the hierarchy change was caused by a hierarchy search change. */
+    searchChange?: {
+        newSearch: Props<HierarchyProvider["setHierarchySearch"]>;
     };
 }
 /**
@@ -43,14 +42,13 @@ interface HierarchyChangedEventArgs {
  */
 export interface HierarchyProvider {
     /**
-     * An event that provider raises due to a hierarchy change, that requires a reload. Provider may
-     * set additional event arguments to provide extra information about what caused the change.
+     * An event that provider raises due to a hierarchy change that requires a reload.
      *
      * Consumers are expected to subscribe to this event and reload the hierarchy when it's raised.
-     * Implementations may provide additional details on what caused the change through the optional
+     * Implementations may provide additional details on what caused the change through the
      * event arguments.
      */
-    readonly hierarchyChanged: Event<(args?: HierarchyChangedEventArgs) => void>;
+    readonly hierarchyChanged: Event<(args: HierarchyChangedEventArgs) => void>;
     /**
      * Gets nodes for the specified parent node. This is **the method to implement**, otherwise
      * the provider doesn't return any nodes.
@@ -74,36 +72,63 @@ export interface HierarchyProvider {
      */
     setFormatter(formatter: IPrimitiveValueFormatter | undefined): void;
     /**
-     * Sets the hierarchy filter used by this hierarchy provider. Setting to `undefined`
-     * removes the filter.
+     * Sets the hierarchy search used by this hierarchy provider. Setting to `undefined`
+     * removes the search.
      *
-     * @note There's a difference between `undefined` filter and filter with empty paths list. The
-     * former means no filter is applied, while the latter means the filter is applied and it filters-out
+     * @note There's a difference between `undefined` search and search with empty paths list. The
+     * former means no search is applied, while the latter means the search is applied and it filters-out
      * all hierarchy.
      *
-     * @note Changing filter is expected to trigger the `hierarchyChanged` event with `filterChange` arg.
+     * @note Changing search is expected to trigger the `hierarchyChanged` event with `searchChange` arg.
      */
-    setHierarchyFilter(props: {
-        /** A list of node identifiers from root to target node. */
-        paths: HierarchyFilteringPath[];
+    setHierarchySearch(props: {
+        /** A list of search trees that define paths from root to search target nodes. */
+        paths: HierarchySearchTree[];
     } | undefined): void;
 }
 /**
- * Props for `mergeProviders` function.
+ * An utility to create a `HierarchyProvider` from a partial implementation.
+ *
+ * Creating a `HierarchyProvider` directly requires implementing all its methods:
+ * ```ts
+ * {
+ *   hierarchyChanged: new BeEvent(),
+ *   async *getNodes({ parentNode }) {
+ *     // yield nodes...
+ *   },
+ *   async *getNodeInstanceKeys() {},
+ *   setFormatter() {},
+ *   setHierarchySearch() {},
+ * }
+ * ```
+ *
+ * However, in many cases you may only need to implement the `getNodes` method and
+ * can rely on default implementations for other methods.
+ *
+ * With this utility you can implement only part of it, e.g. just the `getNodes` method:
+ * ```ts
+ * // provide implementation as a javascript object
+ * createHierarchyProvider(({ hierarchyChanged }) => ({
+ *   async *getNodes({ parentNode }) {
+ *     // yield nodes...
+ *   },
+ * }));
+ *
+ * // or, provide implementation as a class instance:
+ * createHierarchyProvider(
+ *   ({ hierarchyChanged }) =>
+ *     new (class implements Pick<HierarchyProvider, "getNodes"> {
+ *       public async *getNodes({ parentNode }): ReturnType<HierarchyProvider["getNodes"]> {
+ *         // yield nodes...
+ *       }
+ *     })(),
+ * );
+ * ```
+ *
  * @public
  */
-interface MergeHierarchyProvidersProps {
-    /** List of providers to merge. */
-    providers: HierarchyProvider[];
-}
-/**
- * Creates a single, merged, hierarchy provider from multiple given providers.
- * @public
- */
-export declare function mergeProviders({ providers }: MergeHierarchyProvidersProps): HierarchyProvider & {
-    /** @deprecated in 1.4. Use `[Symbol.dispose]` instead. */
-    dispose: () => void;
-    [Symbol.dispose]: () => void;
-};
+export declare function createHierarchyProvider<TPartialProvider extends Partial<Omit<HierarchyProvider, "hierarchyChanged">> & Pick<HierarchyProvider, "getNodes">>(partialFactory: (props: {
+    hierarchyChanged: RaisableEvent<EventListener<HierarchyProvider["hierarchyChanged"]>>;
+}) => TPartialProvider): TPartialProvider & HierarchyProvider;
 export {};
 //# sourceMappingURL=HierarchyProvider.d.ts.map

package/lib/hierarchies/HierarchyProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyProvider.d.ts","sourceRoot":"","sources":["../../src/hierarchies/HierarchyProvider.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EACb,WAAW,EACX,wBAAwB,EACxB,KAAK,EACL,aAAa,EACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,UAAU,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAE5C,0FAA0F;IAC1F,cAAc,CAAC,EAAE,qBAAqB,CAAC;IAEvC;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAE/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,UAAU,yBAAyB;IACjC,sEAAsE;IACtE,eAAe,CAAC,EAAE;QAAE,YAAY,EAAE,wBAAwB,GAAG,SAAS,CAAA;KAAE,CAAC;IAEzE,6EAA6E;IAC7E,YAAY,CAAC,EAAE;QAAE,SAAS,EAAE,KAAK,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,CAAC,CAAA;KAAE,CAAC;CAC9E;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,yBAAyB,KAAK,IAAI,CAAC,CAAC;IAE5E;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,qBAAqB,CAAC,aAAa,CAAC,CAAC;IAE9E;;;;;;OAMG;IACH,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,CAAC,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAE5G;;;;;;;OAOG;IACH,YAAY,CAAC,SAAS,EAAE,wBAAwB,GAAG,SAAS,GAAG,IAAI,CAAC;IAEpE;;;;;;;;;OASG;IACH,kBAAkB,CAChB,KAAK,EACD;QACE,iFAAiF;QACjF,KAAK,EAAE,mBAAmB,EAAE,CAAC;KAC9B,GACD,SAAS,GACZ,IAAI,CAAC;CACT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,SAAS,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAAC,GAAG,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,EAEnH,cAAc,EAAE,CAAC,KAAK,EAAE;IACtB,gBAAgB,EAAE,aAAa,CAAC,aAAa,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;CACvF,KAAK,gBAAgB,GACrB,gBAAgB,GAAG,iBAAiB,CAatC"}

package/lib/hierarchies/HierarchyProvider.js

@@ -0,0 +1,61 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import { BeEvent } from "@itwin/core-bentley";
+/**
+ * An utility to create a `HierarchyProvider` from a partial implementation.
+ *
+ * Creating a `HierarchyProvider` directly requires implementing all its methods:
+ * ```ts
+ * {
+ *   hierarchyChanged: new BeEvent(),
+ *   async *getNodes({ parentNode }) {
+ *     // yield nodes...
+ *   },
+ *   async *getNodeInstanceKeys() {},
+ *   setFormatter() {},
+ *   setHierarchySearch() {},
+ * }
+ * ```
+ *
+ * However, in many cases you may only need to implement the `getNodes` method and
+ * can rely on default implementations for other methods.
+ *
+ * With this utility you can implement only part of it, e.g. just the `getNodes` method:
+ * ```ts
+ * // provide implementation as a javascript object
+ * createHierarchyProvider(({ hierarchyChanged }) => ({
+ *   async *getNodes({ parentNode }) {
+ *     // yield nodes...
+ *   },
+ * }));
+ *
+ * // or, provide implementation as a class instance:
+ * createHierarchyProvider(
+ *   ({ hierarchyChanged }) =>
+ *     new (class implements Pick<HierarchyProvider, "getNodes"> {
+ *       public async *getNodes({ parentNode }): ReturnType<HierarchyProvider["getNodes"]> {
+ *         // yield nodes...
+ *       }
+ *     })(),
+ * );
+ * ```
+ *
+ * @public
+ */
+export function createHierarchyProvider(partialFactory) {
+    const hierarchyChanged = new BeEvent();
+    const impl = partialFactory({ hierarchyChanged });
+    return Object.assign(impl, {
+        hierarchyChanged,
+        ...(impl.getNodeInstanceKeys
+            ? { getNodeInstanceKeys: impl.getNodeInstanceKeys }
+            : /* v8 ignore next */ { async *getNodeInstanceKeys() { } }),
+        ...(impl.setFormatter ? { setFormatter: impl.setFormatter } : /* v8 ignore next */ { setFormatter() { } }),
+        ...(impl.setHierarchySearch
+            ? { setHierarchySearch: impl.setHierarchySearch }
+            : /* v8 ignore next */ { setHierarchySearch() { } }),
+    });
+}
+//# sourceMappingURL=HierarchyProvider.js.map

package/lib/hierarchies/HierarchyProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyProvider.js","sourceRoot":"","sources":["../../src/hierarchies/HierarchyProvider.ts"],"names":[],"mappings":"AAAA;;;gGAGgG;AAEhG,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AA6G9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,uBAAuB,CAGrC,cAEsB;IAEtB,MAAM,gBAAgB,GAAqD,IAAI,OAAO,EAAE,CAAC;IACzF,MAAM,IAAI,GAAG,cAAc,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;QACzB,gBAAgB;QAChB,GAAG,CAAC,IAAI,CAAC,mBAAmB;YAC1B,CAAC,CAAC,EAAE,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,EAAE;YACnD,CAAC,CAAC,oBAAoB,CAAC,EAAE,KAAK,CAAC,CAAC,mBAAmB,KAAI,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC,EAAE,YAAY,KAAI,CAAC,EAAE,CAAC;QACzG,GAAG,CAAC,IAAI,CAAC,kBAAkB;YACzB,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,EAAE;YACjD,CAAC,CAAC,oBAAoB,CAAC,EAAE,kBAAkB,KAAI,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC;AACL,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n * Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n * See LICENSE.md in the project root for license terms and full copyright notice.\n *--------------------------------------------------------------------------------------------*/\n\nimport { BeEvent } from \"@itwin/core-bentley\";\n\nimport type { GenericInstanceFilter } from \"@itwin/core-common\";\nimport type {\n  Event,\n  EventListener,\n  InstanceKey,\n  IPrimitiveValueFormatter,\n  Props,\n  RaisableEvent,\n} from \"@itwin/presentation-shared\";\nimport type { HierarchyNode, ParentHierarchyNode } from \"./HierarchyNode.js\";\nimport type { HierarchySearchTree } from \"./HierarchySearch.js\";\n\n/**\n * Props for the `HierarchyProvider.getNodes` call.\n * @public\n */\nexport interface GetHierarchyNodesProps {\n  /** Parent node to get children for. Pass `undefined` to get root nodes. */\n  parentNode: ParentHierarchyNode | undefined;\n\n  /** Optional hierarchy level filter. Has no effect if `parentNode` is a `GroupingNode`. */\n  instanceFilter?: GenericInstanceFilter;\n\n  /**\n   * Optional hierarchy level size limit override. This value is passed to `LimitingECSqlQueryExecutor` used\n   * by this provider to override query rows limit per hierarchy level. If not provided, defaults to whatever\n   * is used by the limiting query executor.\n   *\n   * Has no effect if `parentNode` is a `GroupingNode`.\n   */\n  hierarchyLevelSizeLimit?: number | \"unbounded\";\n\n  /** When set to `true` ignores the cache and fetches the nodes again. */\n  ignoreCache?: boolean;\n}\n\n/**\n * Event arguments for `HierarchyProvider.hierarchyChanged` event.\n * @public\n */\ninterface HierarchyChangedEventArgs {\n  /** Set when the hierarchy change was caused by a formatter change. */\n  formatterChange?: { newFormatter: IPrimitiveValueFormatter | undefined };\n\n  /** Set when the hierarchy change was caused by a hierarchy search change. */\n  searchChange?: { newSearch: Props<HierarchyProvider[\"setHierarchySearch\"]> };\n}\n\n/**\n * An interface for a hierarchy provider that knows how to create child nodes for a given parent node.\n * @public\n */\nexport interface HierarchyProvider {\n  /**\n   * An event that provider raises due to a hierarchy change that requires a reload.\n   *\n   * Consumers are expected to subscribe to this event and reload the hierarchy when it's raised.\n   * Implementations may provide additional details on what caused the change through the\n   * event arguments.\n   */\n  readonly hierarchyChanged: Event<(args: HierarchyChangedEventArgs) => void>;\n\n  /**\n   * Gets nodes for the specified parent node. This is **the method to implement**, otherwise\n   * the provider doesn't return any nodes.\n   */\n  getNodes(props: GetHierarchyNodesProps): AsyncIterableIterator<HierarchyNode>;\n\n  /**\n   * Gets instance keys for the specified parent node.\n   *\n   * The result of this method may be used to determine instances whose nodes would be displayed as children\n   * of the specified parent node. For such use cases calling this method should be more efficient compared\n   * to calling `getNodes`.\n   */\n  getNodeInstanceKeys(props: Omit<GetHierarchyNodesProps, \"ignoreCache\">): AsyncIterableIterator<InstanceKey>;\n\n  /**\n   * Overrides the property value formatter used by the hierarchy provider. Setting to `undefined`\n   * resets the formatter, but what that means depends on the provider implementation - it could just\n   * use unformatted values, or use some default formatter, e.g. the on created by `createDefaultValueFormatter`\n   * from `@itwin/presentation-shared` package.\n   *\n   * @note Changing formatter is expected to trigger the `hierarchyChanged` event with `formatterChange` arg.\n   */\n  setFormatter(formatter: IPrimitiveValueFormatter | undefined): void;\n\n  /**\n   * Sets the hierarchy search used by this hierarchy provider. Setting to `undefined`\n   * removes the search.\n   *\n   * @note There's a difference between `undefined` search and search with empty paths list. The\n   * former means no search is applied, while the latter means the search is applied and it filters-out\n   * all hierarchy.\n   *\n   * @note Changing search is expected to trigger the `hierarchyChanged` event with `searchChange` arg.\n   */\n  setHierarchySearch(\n    props:\n      | {\n          /** A list of search trees that define paths from root to search target nodes. */\n          paths: HierarchySearchTree[];\n        }\n      | undefined,\n  ): void;\n}\n\n/**\n * An utility to create a `HierarchyProvider` from a partial implementation.\n *\n * Creating a `HierarchyProvider` directly requires implementing all its methods:\n * ```ts\n * {\n *   hierarchyChanged: new BeEvent(),\n *   async *getNodes({ parentNode }) {\n *     // yield nodes...\n *   },\n *   async *getNodeInstanceKeys() {},\n *   setFormatter() {},\n *   setHierarchySearch() {},\n * }\n * ```\n *\n * However, in many cases you may only need to implement the `getNodes` method and\n * can rely on default implementations for other methods.\n *\n * With this utility you can implement only part of it, e.g. just the `getNodes` method:\n * ```ts\n * // provide implementation as a javascript object\n * createHierarchyProvider(({ hierarchyChanged }) => ({\n *   async *getNodes({ parentNode }) {\n *     // yield nodes...\n *   },\n * }));\n *\n * // or, provide implementation as a class instance:\n * createHierarchyProvider(\n *   ({ hierarchyChanged }) =>\n *     new (class implements Pick<HierarchyProvider, \"getNodes\"> {\n *       public async *getNodes({ parentNode }): ReturnType<HierarchyProvider[\"getNodes\"]> {\n *         // yield nodes...\n *       }\n *     })(),\n * );\n * ```\n *\n * @public\n */\nexport function createHierarchyProvider<\n  TPartialProvider extends Partial<Omit<HierarchyProvider, \"hierarchyChanged\">> & Pick<HierarchyProvider, \"getNodes\">,\n>(\n  partialFactory: (props: {\n    hierarchyChanged: RaisableEvent<EventListener<HierarchyProvider[\"hierarchyChanged\"]>>;\n  }) => TPartialProvider,\n): TPartialProvider & HierarchyProvider {\n  const hierarchyChanged: Props<typeof partialFactory>[\"hierarchyChanged\"] = new BeEvent();\n  const impl = partialFactory({ hierarchyChanged });\n  return Object.assign(impl, {\n    hierarchyChanged,\n    ...(impl.getNodeInstanceKeys\n      ? { getNodeInstanceKeys: impl.getNodeInstanceKeys }\n      : /* v8 ignore next */ { async *getNodeInstanceKeys() {} }),\n    ...(impl.setFormatter ? { setFormatter: impl.setFormatter } : /* v8 ignore next */ { setFormatter() {} }),\n    ...(impl.setHierarchySearch\n      ? { setHierarchySearch: impl.setHierarchySearch }\n      : /* v8 ignore next */ { setHierarchySearch() {} }),\n  });\n}\n"]}

package/lib/hierarchies/HierarchySearch.d.ts

@@ -0,0 +1,297 @@
+import { HierarchyNodeIdentifier } from "./HierarchyNodeIdentifier.js";
+import type { NonGroupingHierarchyNode } from "./HierarchyNode.js";
+import type { HierarchyNodeIdentifiersPath } from "./HierarchyNodeIdentifier.js";
+import type { GenericNodeKey, InstancesNodeKey } from "./HierarchyNodeKey.js";
+/** @public */
+export interface HierarchySearchPathOptions {
+    /**
+     * This option specifies the way `autoExpand` flag should be assigned to nodes in the searched hierarchy.
+     * - If it's `false` or `undefined`, nodes have no 'autoExpand' flag.
+     * - If it's `true`, then all nodes up to the search target will have `autoExpand` flag.
+     * - If it's a object with `groupingLevel` then `groupingLevel` determines the number of grouping levels to expand for
+     * the search target.
+     */
+    reveal?: boolean | {
+        /**
+         * Index of the node in search path should be revealed in hierarchy by auto-expanding its ancestors.
+         *
+         * Use when you want to expand up to specific instance node and don't care about grouping nodes.
+         *
+         * **Use case example:**
+         *
+         * All nodes up to `Element1` should be expanded in the following hierarchy:
+         * - Node1
+         *   - GroupingNode1
+         *     - GroupingNode2
+         *       - Element1
+         *       - Element2
+         *
+         * Provide `{ path: [Node1, Element1], reveal: { depthInPath: 1 } }`
+         *
+         * **NOTE**: All nodes that are up to `depthInPath` will be expanded **except** search targets.
+         */
+        depthInPath: number;
+    } | {
+        /**
+         * The number of grouping levels to expand for the search target. For example, if `groupingLevel` is set to `2`, then all grouping nodes up to the second level
+         * will have the `autoExpand` flag.
+         *
+         * **Note:** if search target has less grouping levels than specified by this attribute, then all grouping nodes up to the search target will have
+         * the `autoExpand` flag, but the search target itself won't have the `autoExpand` flag.
+         */
+        groupingLevel: number;
+    };
+    /**
+     * This option specifies whether or not search target should be expanded.
+     * - If it's `false` or `undefined`, search target won't have 'autoExpand' flag.
+     * - If it's `true`, search target will have `autoExpand` flag.
+     *
+     * **Note:** this attribute does not set `autoExpand` flag on nodes up to the search target. For that use `reveal`.
+     */
+    autoExpand?: boolean;
+}
+/**
+ * A path of hierarchy node identifiers for search the hierarchy with additional options.
+ * @public
+ */
+export type HierarchySearchPath = HierarchyNodeIdentifiersPath | {
+    path: HierarchyNodeIdentifiersPath;
+    options?: HierarchySearchPathOptions;
+};
+/** @public */
+export declare namespace HierarchySearchPath {
+    /**
+     * Normalizes the hierarchy search path to the object form.
+     * @public
+     */
+    function normalize(source: HierarchySearchPath): Exclude<HierarchySearchPath, HierarchyNodeIdentifiersPath>;
+    /**
+     * Merges two given `HierarchySearchPathOptions` objects.
+     *
+     * For the `reveal` attribute, the merge chooses to `reveal` as deep as the deepest input:
+     * - if any one of the inputs is `true`, return `true`,
+     * - 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 `groupingLevel` set, return that one,
+     *    - else compare by matching reveal type (`groupingLevel` or `depthInPath`) and return the deeper one.
+     *
+     * @public
+     */
+    function mergeOptions(lhs: HierarchySearchPathOptions | undefined, rhs: HierarchySearchPathOptions | undefined): HierarchySearchPathOptions | undefined;
+}
+/**
+ * A tree structure representing hierarchy search paths. Each node in the tree corresponds
+ * to a hierarchy node identifier and may have children that represent deeper levels in the
+ * hierarchy.
+ *
+ * The `HierarchySearchTree.createBuilder` or `HierarchySearchTree.createFromPathsList` are
+ * typically used create this tree from a flat list of search paths.
+ *
+ * @public
+ */
+export interface HierarchySearchTree {
+    /** Identifier of the hierarchy node this tree entry represents. */
+    identifier: HierarchyNodeIdentifier;
+    /**
+     * When `true`, indicates that this node is a search target.
+     *
+     * Note: A `HierarchySearchTree` node is considered a search target if it has no children, even if `isTarget` is not explicitly set to `true`. This
+     * is because a node with no children represents the end of a search path.
+     */
+    isTarget?: boolean;
+    /** Provides options for handling this search tree entry, such as auto-expansion behavior. */
+    options?: {
+        /**
+         * - `true` to expand the node and its grouping nodes,
+         * - `{ groupingLevel: number }` to expand ancestor grouping nodes, e.g. for the following hierarchy:
+         *   ```
+         *   - Grouping node A
+         *     - Instance node A
+         *       - Grouping node B1
+         *         - Grouping node B2
+         *           - ...
+         *             - Grouping node Bn
+         *               - Instance node B
+         *   ```
+         *
+         *   For "Instance node B" search tree entry:
+         *   - `{ groupingLevel: 1 }` expands its first grouping node "Grouping node B1",
+         *   - `{ groupingLevel: 2 }` expands two levels to "Grouping node B2".
+         *   - `{ groupingLevel: Number.MAX_SAFE_INTEGER }` expands all grouping nodes of that instance node.
+         *
+         *   Note that there's a slight difference between `HierarchySearchTree.options.autoExpand` and
+         *   `HierarchySearchPath.options.reveal`. The latter option reveals the search target node by expanding its ancestors,
+         *   while the `HierarchySearchTree.options.autoExpand` also expands the target node itself.
+         */
+        autoExpand?: boolean | {
+            groupingLevel: number;
+        };
+    };
+    /** Child search tree entries representing the next level(s) in the hierarchy search paths. */
+    children?: HierarchySearchTree[];
+}
+/** @public */
+export declare namespace HierarchySearchTree {
+    /** @public */
+    type HierarchySearchTreeBuilderAcceptHandlerTreeEntry<TExtras extends Record<string, unknown>> = Readonly<Pick<HierarchySearchTree, "identifier" | "options"> & {
+        extras: TExtras;
+    }> & Pick<HierarchySearchTree, "isTarget">;
+    /** @public */
+    type HierarchySearchTreeBuilderAcceptHandlerTreeInput = Readonly<Pick<HierarchySearchTree, "identifier" | "isTarget" | "options"> & {
+        hasChildren: boolean;
+    }>;
+    /** @public */
+    interface HierarchySearchTreeBuilderAcceptHandler<TExtras extends Record<string, unknown>> {
+        /**
+         * Called when a new entry is added to the tree. Return `true` to accept the entry, `false` to reject it and all its children, if any.
+         */
+        onNewEntry?: (props: {
+            /** The parent entries of the new entry being added, from root to immediate parent. It's allowed to mutate these entries. */
+            parentEntries: Array<HierarchySearchTreeBuilderAcceptHandlerTreeEntry<TExtras>>;
+            /** The new entry being added to the tree. */
+            inputEntry: HierarchySearchTreeBuilderAcceptHandlerTreeInput;
+        }) => boolean;
+        /**
+         * Called when a new entry is added to the tree and accepted (either it's a new entry or it merges with an existing entry). This can be used to perform
+         * side effects such as assigning extra information to the tree entry.
+         */
+        onEntryHandled?: (props: {
+            /** The parent entries of the new entry being added, from root to immediate parent. It's allowed to mutate these entries. */
+            parentEntries: Array<HierarchySearchTreeBuilderAcceptHandlerTreeEntry<TExtras>>;
+            /** The tree entry that has been handled. It's allowed to mutate this entry. */
+            treeEntry: HierarchySearchTreeBuilderAcceptHandlerTreeEntry<TExtras>;
+            /** The input entry being added to the tree. */
+            inputEntry: HierarchySearchTreeBuilderAcceptHandlerTreeInput;
+        }) => void;
+    }
+    /**
+     * Props supplied to HierarchySearchTreeBuilder.accept() method for accepting a hierarchy search path or tree with an optional handler for customizing
+     * the behavior of the builder when accepting new entries.
+     * @public
+     */
+    type HierarchySearchTreeBuilderAcceptProps<TAcceptHandlerExtras extends Record<string, unknown>> = ({
+        path: HierarchySearchPath;
+    } | {
+        tree: HierarchySearchTree;
+    }) & {
+        /** An optional handler for customizing the behavior of the builder when accepting new entries. */
+        handler?: HierarchySearchTreeBuilderAcceptHandler<TAcceptHandlerExtras>;
+    };
+    /**
+     * Props supplied to HierarchySearchTreeBuilder.getTree() method for customizing the resulting tree entries, e.g. by omitting some of them or
+     * assigning extra information to them.
+     * @public
+     */
+    interface HierarchySearchTreeBuilderFinalizeTreeProps<TAcceptHandlerExtras extends Record<string, unknown>> {
+        /**
+         * A function that can be used to process each tree entry before it's added to the final tree.
+         *
+         * Return `undefined` to omit the entry and its entire branch from the resulting tree.
+         */
+        processEntry?: (props: {
+            treeEntry: HierarchySearchTreeBuilderAcceptHandlerTreeEntry<TAcceptHandlerExtras>;
+            parentEntries: Array<HierarchySearchTreeBuilderAcceptHandlerTreeEntry<TAcceptHandlerExtras>>;
+        }) => (Omit<HierarchySearchTree, "children"> & {
+            extras: TAcceptHandlerExtras;
+        }) | undefined;
+    }
+    /**
+     * An utility that accepts hierarchy search paths or search trees one by one and builds a `HierarchySearchTree` structure based on them.
+     * @public
+     */
+    interface HierarchySearchTreeBuilder<TAcceptHandlerExtras extends Record<string, unknown>> {
+        /**
+         * Accepts a hierarchy search path or paths' tree and adds it to the builder's internal tree structure. Use `getTree()` to create
+         * a `HierarchySearchTree[]` from the added paths.
+         */
+        accept(props: HierarchySearchTreeBuilderAcceptProps<TAcceptHandlerExtras>): HierarchySearchTreeBuilder<TAcceptHandlerExtras>;
+        /**
+         * Create `HierarchySearchTree[]` from currently added search paths.
+         */
+        getTree(props?: HierarchySearchTreeBuilderFinalizeTreeProps<TAcceptHandlerExtras>): 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
+     */
+    export function createBuilder<TAcceptHandlerExtras extends Record<string, unknown> = Record<string, unknown>>(): HierarchySearchTreeBuilder<TAcceptHandlerExtras>;
+    /**
+     * 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
+     */
+    export function createFromPathsList(paths: Iterable<HierarchySearchPath>): Promise<HierarchySearchTree[]>;
+    /**
+     * 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
+     */
+    export function mergeOptions(lhs: HierarchySearchTree["options"] | undefined, rhs: HierarchySearchTree["options"] | undefined): HierarchySearchTree["options"] | undefined;
+    export {};
+}
+/**
+ * Creates a set of utilities for making it easier to search the given hierarchy
+ * level.
+ *
+ * @public
+ */
+export declare function createHierarchySearchHelper(rootLevelSearchProps: HierarchySearchTree[] | undefined, parentNode: Pick<NonGroupingHierarchyNode, "search"> | undefined): {
+    /** Returns a flag indicating if the hierarchy level is filtered. */
+    hasSearch: boolean;
+    /**
+     * Returns a flag indicating whether this hierarchy level has an ancestor node
+     * that is a search target. That generally means that this and all downstream hierarchy
+     * levels should be displayed without search being applied to them, even if search paths
+     * say otherwise.
+     */
+    hasSearchTargetAncestor: boolean;
+    /**
+     * Returns a list of hierarchy node identifiers that apply specifically for this
+     * hierarchy level. Returns `undefined` if search is not applied to this level.
+     */
+    getChildNodeSearchIdentifiers: () => HierarchyNodeIdentifier[] | undefined;
+    /**
+     * When a hierarchy node is created for a filtered hierarchy level, it needs some attributes (e.g. `search`
+     * and `autoExpand`) to be set based on the search paths and search options. This function calculates
+     * these props for a child node based on its key or path matcher.
+     *
+     * When using `pathMatcher` or `asyncPathMatcher` prop, callers have more flexibility to decide whether the given `HierarchyNodeIdentifier` applies
+     * to their node. For example, only some parts of the identifier can be checked for improved performance. Otherwise, the
+     * `nodeKey` prop can be used to check the whole identifier.
+     *
+     * There are multiple overloads of `createChildNodeProps`: depending on props type it returns different values:
+     * - `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: {
+        (props: {
+            nodeKey: InstancesNodeKey | GenericNodeKey;
+        }): Pick<NonGroupingHierarchyNode, "search" | "autoExpand"> | undefined;
+        (props: {
+            nodeKey: InstancesNodeKey | GenericNodeKey;
+            pathMatcher: (identifier: HierarchyNodeIdentifier) => boolean;
+        }): Pick<NonGroupingHierarchyNode, "search" | "autoExpand"> | undefined;
+        (props: {
+            nodeKey: InstancesNodeKey | GenericNodeKey;
+            asyncPathMatcher: (identifier: HierarchyNodeIdentifier) => boolean | Promise<boolean>;
+        }): Promise<Pick<NonGroupingHierarchyNode, "search" | "autoExpand"> | undefined> | Pick<NonGroupingHierarchyNode, "search" | "autoExpand"> | undefined;
+    };
+};
+//# sourceMappingURL=HierarchySearch.d.ts.map

package/lib/hierarchies/HierarchySearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchySearch.d.ts","sourceRoot":"","sources":["../../src/hierarchies/HierarchySearch.ts"],"names":[],"mappings":"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"}