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

package/CHANGELOG.md

@@ -1,5 +1,226 @@
 # @itwin/presentation-hierarchies
 
+## 2.0.0-alpha.14
+
+### Minor Changes
+
+- [#1264](https://github.com/iTwin/presentation/pull/1264): Enhance `HierarchySearchTree.createBuilder()` by allowing it to process resulting hierarchy.
+
+  Example:
+
+  ```ts
+  const builder = HierarchySearchTree.createBuilder<{ heat?: number }>();
+  builder.accept({
+    tree: subTree,
+    handler: {
+      onEntryHandled: ({ treeEntry, parentEntries }) => {
+        // Assign some extra information to the entry and its ancestors. This will allow us to test
+        // that we can use that information in `getTree` method to filter out entries.
+        [...parentEntries, treeEntry].forEach((entry) => {
+          entry.extras.heat ? entry.extras.heat++ : (entry.extras.heat = 1);
+        });
+      },
+    },
+  });
+  const tree = builder.getTree({
+    // Only include branches with heat > 5
+    processEntry: ({ treeEntry }) =>
+      (treeEntry.extras.heat ?? 0) > 5 ? treeEntry : undefined,
+  });
+  ```
+
+### Patch Changes
+
+- [#1256](https://github.com/iTwin/presentation/pull/1256): Fix `alpha` dependencies being specified with a range (`^`), allowing package manager to use higher versions, possibly with breaking changes.
+
+## 2.0.0-alpha.13
+
+### Major Changes
+
+- [#1250](https://github.com/iTwin/presentation/pull/1250): Use type-safe full class names.
+
+  The full class names used in this package were defined as `string`, although we always expect them to be in specific format - either `Schema:Class` or `Schema.Class`. In many cases we rely on this format when parsing the name for compare or other purposes, so type safety for the format is highly beneficial. This change makes full class names type-safe(ier) through [TypeScript's template literal types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html), so that we can be sure that they are always in correct format.
+
+  ## Breaking changes
+
+  - `ClassGroupingNodeKey.className` is now of type `EC.FullClassName` instead of `string`.
+  - `NodesQueryClauseFactory.createSelectClause` prop `grouping.byBaseClasses.fullClassNames` is now of type `EC.FullClassName[]` instead of `string[]`.
+  - `NodesQueryClauseFactory.createSelectClause` prop `grouping.byProperties.propertiesClassName` is now of type `EC.FullClassName` instead of `string`.
+  - `HierarchyNodesDefinition.fullClassName` is now of type `EC.FullClassName` instead of `string`.
+  - `createPredicateBasedHierarchyDefinition` prop `hierarchies.childNodes[number].parentInstancesNodePredicate` now accepts `EC.FullClassName` instead of `string`.
+  - `NodesQueryClauseFactory.createFilterClauses` prop `contentClass.fullName` is now of type `EC.FullClassName` instead of `string`.
+  - `PropertyOtherValuesGroupingNodeKey.properties[number].className` is now of type `EC.FullClassName` instead of `string`.
+  - `PropertyValueGroupingNodeKey.propertyClassName` is now of type `EC.FullClassName` instead of `string`.
+  - `PropertyValueRangeGroupingNodeKey.propertyClassName` is now of type `EC.FullClassName` instead of `string`.
+
+  In many cases migration will be seamless, as long as the input string matches the expected format. In some cases (e.g. when assigning a string variable to one of the affected properties), you may need to use `normalizeFullClassName` from `@itwin/presentation-shared` to ensure the value is of the correct type:
+
+  ```ts
+  const myClassName: string = "MySchema.MyClass";
+
+  // before
+  const myClassGroupingNodeKey: ClassGroupingNodeKey = {
+    type: "class-grouping",
+    className: myClassName,
+  };
+
+  // after
+  const myClassGroupingNodeKey: ClassGroupingNodeKey = {
+    type: "class-grouping",
+    // assigning `MySchema.MyClass` directly wouldn't require using `normalizeFullClassName` as the type would be correctly inferred, but if the class name is stored in a variable of type `string`, you need to use `normalizeFullClassName` to ensure it's of the correct type
+    className: normalizeFullClassName(myClassName),
+  };
+  ```
+
+- [#1236](https://github.com/iTwin/presentation/pull/1236): Start using tree structure for defining hierarchy search paths.
+
+  **Additions:**
+
+  - `HierarchySearchTree` type that represents a tree structure of hierarchy search paths and is now used for hierarchy search implementation in `HierarchyProvider`.
+
+    In addition to the type, there's also a namespace with the same name, providing utility functions for working with the tree structure:
+
+    - `HierarchySearchTree.createBuilder` function to create a builder for hierarchy search trees, which can be used to create a tree from individual paths or to merge multiple trees together:
+
+      ```ts
+      const builder = HierarchySearchTree.createBuilder();
+      builder.accept({ path: searchPath1 });
+      builder.accept({ path: searchPath2 });
+      builder.accept({ tree: partialSearchTree });
+      const tree: HierarchySearchTree[] = builder.getTree();
+      ```
+
+      This is the preferred way to create a `HierarchySearchTree`, as it allows to create a tree without having to create an array first, as opposed to `HierarchySearchTree.createFromPathsList` function described below.
+
+    - `HierarchySearchTree.createFromPathsList` function to create a hierarchy search tree from a list of hierarchy search paths. This is a quick & easy way to migrate from the old `HierarchySearchPath[]` structure to `HierarchySearchTree[]`, but it's' less efficient than using the builder if you need to create a tree from a large number of paths, as it needs to create an intermediate array.
+
+      The recommended way to handle multiple search paths is to use the builder and call `accept` for each path, as it allows to create a tree without having to create an array first:
+
+      ```ts
+      // Instead of doing this:
+      const searchPaths: HierarchySearchPath[] = [];
+      for (const item of items) {
+        searchPaths.push(createSearchPathForItem(item));
+      }
+      const tree: HierarchySearchTree[] =
+        await HierarchySearchTree.createFromPathsList(searchPaths);
+
+      // Do this:
+      const builder = HierarchySearchTree.createBuilder();
+      for (const item of items) {
+        builder.accept({ path: createSearchPathForItem(item) });
+      }
+      const tree: HierarchySearchTree[] = builder.getTree();
+      ```
+
+    - `HierarchySearchTree.mergeOptions` function to merge options of two hierarchy search trees. Used internally to merge options of the same nodes when creating a tree from a list of paths.
+
+  - `HierarchyNode.getGroupingNodeLevel` utility function to get the level of a grouping node in the hierarchy. Convenient for specifying the `groupingLevel` prop in `HierarchySearchPath.options.reveal` and `HierarchySearchTree.options.autoExpand`.
+
+  - `HierarchyNodeIdentifier.compare` static function to compare two `HierarchyNodeIdentifier` objects. Useful when using `HierarchyNodeIdentifier` as a key in a dictionary sorted set.
+
+  **Breaking changes:**
+
+  - `HierarchySearchPathOptions.reveal` type `{ depthInHierarchy: number }` was replaced with `{ groupingLevel: number }`.
+
+    The `depthInHierarchy` option was only useful when revealing grouping nodes, the rename makes the intent more explicit. In addition, the `groupingLevel` option is only handled in the scope of one specific `InstancesNode` node that the options are supplied for, so handling this option is more efficient - we only need to handle it for grouping nodes, and look only as deep as the next grouped `InstancesNode` node.
+
+    Migration:
+
+    ```ts
+    const groupingNode = getMyGroupingNode();
+    const searchPath: HierarchySearchPath = {
+      // ...
+      options: {
+        // before
+        reveal: { depthInHierarchy: groupingNode.parentKeys.length },
+
+        // after
+        reveal: {
+          groupingLevel: HierarchyNode.getGroupingNodeLevel(groupingNode),
+        },
+      },
+    };
+    ```
+
+  - `HierarchyProvider.setHierarchySearch` now takes `{ paths: HierarchySearchTree[] }` instead of `{ paths: HierarchySearchPath[] }`.
+
+    Migration:
+
+    ```ts
+    const provider: HierarchyProvider = getMyHierarchyProvider();
+    const searchPaths: HierarchySearchPath[] = getMySearchPaths();
+    provider.setHierarchySearch({
+      // before
+      paths: searchPaths,
+
+      // after
+      // - see `HierarchySearchTree.createFromPathsList` description above for more efficient way to do this
+      // - quick migration:
+      paths: await HierarchySearchTree.createFromPathsList(searchPaths),
+    });
+    ```
+
+  - `createIModelHierarchyProvider` and `createMergedIModelHierarchyProvider` functions' `search` prop now takes `{ paths: HierarchySearchTree[] }` instead of `{ paths: HierarchySearchPath[] }`. Use `HierarchySearchTree.createFromPathsList` to do the conversion.
+
+    Migration:
+
+    ```ts
+    const searchPaths: HierarchySearchPath[] = getMySearchPaths();
+    const provider = createIModelHierarchyProvider({
+      // ...
+      search: {
+        // before
+        paths: searchPaths,
+
+        // after
+        // - see `HierarchySearchTree.createFromPathsList` description above for more efficient way to do this
+        // - quick migration:
+        paths: await HierarchySearchTree.createFromPathsList(searchPaths),
+      },
+    });
+    ```
+
+  - `HierarchyNode.search` changes:
+
+    - Type of `childrenTargetPaths` has been changed from `HierarchySearchPath[]` to `HierarchySearchTree[]`.
+    - `searchTargetOptions` was replaced with `options`, which is available not only for nodes with `isSearchTarget: true`, but all of them.
+
+    The changes of this attribute are taken care of by the `createHierarchySearchHelper` changes described below.
+
+  - `createHierarchySearchHelper` changes:
+
+    - The first argument is now `HierarchySearchTree[]` instead of `HierarchySearchPath[]`.
+    - The `createChildNodeProps` function of returned result no longer requires the `parentKeys` prop, but instead always requires the `nodeKey` prop.
+
+    Migration:
+
+    ```ts
+    // Somewhere in `HierarchyProvider.getNodes` implementation...
+
+    // Type of the first argument has changed, but it also changed on `HierarchyProvider`, so likely no changes are needed here. If the
+    // type of `rootSearch.paths` is still `HierarchySearchPath[]` - use `HierarchySearchTree.createFromPathsList` to do the conversion.
+    const helper = createHierarchySearchHelper(rootSearch?.paths, parentNode);
+    for (const book of books) {
+      const nodeKey: GenericNodeKey = { type: "generic", id: `book:${book.key}` };
+      yield {
+        key: nodeKey,
+        label: book.title,
+        children: false,
+        parentKeys: [...parentNode.parentKeys, parentNode.key],
+        // before
+        ...searchHelper?.createChildNodeProps({ nodeKey, parentKeys }),
+        // after
+        ...searchHelper?.createChildNodeProps({ nodeKey }),
+      };
+    }
+    ```
+
+### Patch Changes
+
+- Updated dependencies:
+  - @itwin/presentation-shared@2.0.0-alpha.9
+
 ## 2.0.0-alpha.12
 
 ### Patch Changes
@@ -91,15 +312,21 @@
   // or, provide implementation as a class instance:
   const afterAsClassObject = createHierarchyProvider(
     ({ hierarchyChanged }) =>
-      new (class implements Pick<HierarchyProvider, "getNodes" | "setFormatter"> {
-        public async *getNodes({ parentNode }): ReturnType<HierarchyProvider["getNodes"]> {
+      new (class
+        implements Pick<HierarchyProvider, "getNodes" | "setFormatter">
+      {
+        public async *getNodes({
+          parentNode,
+        }): ReturnType<HierarchyProvider["getNodes"]> {
           // yield nodes...
         }
         public setFormatter(formatter: IPrimitiveValueFormatter | undefined) {
           // set formatter...
-          hierarchyChanged.raiseEvent({ formatterChange: { newFormatter: formatter } });
+          hierarchyChanged.raiseEvent({
+            formatterChange: { newFormatter: formatter },
+          });
         }
-      })(),
+      })()
   );
   ```
 
@@ -126,6 +353,7 @@
   the `createNodesQueryClauseFactory` function should be called with `imodelAccess` that is passed to `HierarchyDefinition.defineHierarchyLevel`.
 
   **Breaking changes:**
+
   - `DefineHierarchyLevelProps.imodelKey` was replaced with `imodelAccess`. If needed, the key can be accessed using `imodelAccess.imodelKey`. This affects the following APIs:
     - `HierarchyDefinition.defineHierarchyLevel` (function that uses these props),
     - `DefineRootHierarchyLevelProps` (extends the props type),
@@ -138,6 +366,7 @@
 - [#1137](https://github.com/iTwin/presentation/pull/1137): Fix hierarchy search only handling a single (latest) iModel results when searching multi-iModel hierarchies.
 
   Notable API changes:
+
   - **BREAKING:** `NodeParser` (type of `HierarchyDefinition.parseNode` function) now gets a single props argument instead of multiple arguments. In addition, the props object now also contains an imodel key argument.
 
     ```ts
@@ -172,6 +401,7 @@
   Properties and APIs were renamed accordingly to clarify the distinction and avoid confusion between hierarchy‑wide search and per-hierarchy‑level filtering.
 
   **Breaking changes:**
+
   - Removed deprecated `extractFilteringProps`.
   - Removed deprecated `HierarchyNodeFilteringProps.create`.
   - Renamed `createHierarchyFilteringHelper` to `createHierarchySearchHelper`. It's return type was also adjusted for the rename:
@@ -196,6 +426,7 @@
 - 6a00754233e6d1b8956a5fc7680829562156d659: Fixed a bug causing `HierarchyNode.autoExpand` flag to be set on non-grouping nodes, when `HierarchyFilteringPathOptions.autoExpand.depthInHierarchy` points to a grouping node whose child non-grouping node is not a filter target.
 
   **Breaking changes:**
+
   - `GroupingHierarchyNode` no longer contains `filtering` attribute. This was always the case, but now the types have been updated to match it.
   - Changed return type of `createHierarchyFilteringHelper`:
     - Removed `createChildNodePropsAsync` - it became an overload of `createChildNodeProps`, whose path matching is done through `asyncPathMatcher` callback.
@@ -258,6 +489,7 @@
 ### Major Changes
 
 - [#954](https://github.com/iTwin/presentation/pull/954): Add additional requirements for types in `EC` metadata namespace, whose objects are returned by `ECSchemaProvider`.
+
   - `EC.Schema`, `EC.Class` and `EC.Property` now all have an async `getCustomAttributes()` method that returns an `EC.CustomAttributeSet`, allowing consumers to access custom attributes of these schema items.
   - `EC.Class` now additionally has these members:
     - `baseClass: Promise<Class | undefined>`
@@ -276,6 +508,14 @@
 - Updated dependencies:
   - @itwin/presentation-shared@2.0.0-alpha.0
 
+## 1.7.11
+
+### Patch Changes
+
+- [#1242](https://github.com/iTwin/presentation/pull/1242): Bump dependencies.
+- Updated dependencies:
+  - @itwin/presentation-shared@1.2.10
+
 ## 1.7.10
 
 ### Patch Changes
@@ -356,6 +596,7 @@
 ### Minor Changes
 
 - 8f7d200926b93e862276e1f978f6c891691e0dae: Refactored specifying the depth / level to which filtering path should be auto-expanded.
+
   - Deprecated `FilteringPathAutoExpandOption` and `FilterTargetGroupingNodeInfo`.
   - Added `FilteringPathAutoExpandDepthInPath` and `FilteringPathAutoExpandDepthInHierarchy` which should be used instead.
 
@@ -420,7 +661,10 @@
   **Before:**
 
   ```ts
-  const childNodeProps = await createHierarchyFilteringHelper(undefined, undefined).createChildNodePropsAsync({
+  const childNodeProps = await createHierarchyFilteringHelper(
+    undefined,
+    undefined
+  ).createChildNodePropsAsync({
     pathMatcher: (identifier): boolean | Promise<boolean> => {
       return false;
     },
@@ -428,6 +672,7 @@
   ```
 
   **After:**
+
   - **Option A:** check if it's a Promise before awaiting:
 
     Use this when you want to get slightly better performance by avoiding unnecessary `await`.
@@ -446,7 +691,10 @@
     Use this if pathMatcher always returns a Promise or you prefer a simpler pattern.
 
     ```ts
-    const childNodeProps = await createHierarchyFilteringHelper(undefined, undefined).createChildNodePropsAsync({
+    const childNodeProps = await createHierarchyFilteringHelper(
+      undefined,
+      undefined
+    ).createChildNodePropsAsync({
       pathMatcher: async (identifier): Promise<boolean> => {
         return false;
       },
@@ -512,6 +760,7 @@
 - [#783](https://github.com/iTwin/presentation/pull/783): Added hierarchy filtering helper to make hierarchy filtering easier to implement.
 
   The helper can be created using the `createHierarchyFilteringHelper` function and supplying it the root level filtering paths and parent node. From there, filtering information for specific hierarchy level is determined and an object with the following attributes is returned:
+
   - `hasFilter` tells if the hierarchy level has a filter applied.
   - `hasFilterTargetAncestor` tells if there's a filter target ancestor node up in the hierarchy.
   - `getChildNodeFilteringIdentifiers()` returns an array of hierarchy node identifiers that apply specifically for this hierarchy level.
@@ -520,6 +769,7 @@
   See the [Implementing hierarchy filtering support](./learning/CustomHierarchyProviders.md#implementing-hierarchy-filtering-support) learning page for a usage example.
 
   In addition, deprecated a few APIs that are replaced by filtering helper:
+
   - `extractFilteringProps` function,
   - `HierarchyNodeFilteringProps.create` function.
 
@@ -565,6 +815,7 @@
   | 50k             | not tested        | 13.45 s          |
 
   In addition, changed `NodeParser` (return type of `HierarchyDefinition.parseNode`):
+
   - It now can return a promise, so instead of just `SourceInstanceHierarchyNode` it can now also return `Promise<SourceInstanceHierarchyNode>`.
   - Additionally, it now accepts an optional `parentNode` argument of `HierarchyDefinitionParentNode` type.
 
@@ -596,6 +847,7 @@
 ### Minor Changes
 
 - [#708](https://github.com/iTwin/presentation/pull/708): **BREAKING:** Added support for creating hierarchies from multiple data sources.
+
   - `InstancesNodeKey.instanceKeys` array items now have an optional `imodelKey` attribute to allow for the identification of the iModel that the instance belongs to. This is useful when working with sets of instance keys representing instances from different iModels. In addition, the same `imodelKey` attribute is also available on `HierarchyNodeIdentifier` to allow for filtering nodes based on the iModel they belong to.
   - `HierarchyNode` terminology and related changes:
     - "Standard" nodes were renamed to "IModel" nodes to signify the fact that they're based on iModel data:
@@ -623,6 +875,7 @@
     - The returned provider now has a `dispose` method to clean up resources - make sure to call it when the provider is no longer needed.
   - Added `mergeProviders` function, which, given a number of hierarchy providers, creates a new provider that merges the hierarchies of the input providers. The returned provider has a `dispose` method that needs to be called when the provider is no longer needed.
   - Renamed `createClassBasedHierarchyDefinition` to `createPredicateBasedHierarchyDefinition` to signify its props changes:
+
     - When specifying `childNodes` definition for instances parent node, the `parentNodeClassName` attribute was changed to `parentInstancesNodePredicate`. In addition to accepting a full class name, identifying the class of parent instances to return children for, it now also accepts an async function predicate.
     - When specifying `childNodes` definition for generic parent node, the `customParentNodeKey` attribute was changed to `parentGenericNodePredicate`. The type changed from `string`, identifying the key of the parent node, to an async function predicate.
 
@@ -675,6 +928,7 @@
     ```
 
 - [#708](https://github.com/iTwin/presentation/pull/708): Added utilities for custom hierarchy filtering handling:
+
   - `extractFilteringProps` function, given root level hierarchy filtering paths and a parent node, returns props required to filter particular hierarchy level.
   - `HierarchyFilteringPath` interface is now public and there's also a similarly-named namespace with the following utilities:
     - `mergeOptions` merges filtering options of two paths. This is useful for cases when there are multiple paths targeting the same node, but with different options.
@@ -703,7 +957,9 @@
   ```ts
   const selectQueryFactory = createNodesQueryClauseFactory({
     imodelAccess,
-    instanceLabelSelectClauseFactory: createBisInstanceLabelSelectClauseFactory({ classHierarchyInspector: imodelAccess }),
+    instanceLabelSelectClauseFactory: createBisInstanceLabelSelectClauseFactory(
+      { classHierarchyInspector: imodelAccess }
+    ),
   });
   ```
 
@@ -726,7 +982,12 @@
           // Path to the element "C"
           path: [elementKeys.a, elementKeys.b, elementKeys.c],
           // Supply grouping node attributes with the path to the "C" element.
-          options: { autoExpand: { key: groupingNode.key, depth: groupingNode.parentKeys.length } },
+          options: {
+            autoExpand: {
+              key: groupingNode.key,
+              depth: groupingNode.parentKeys.length,
+            },
+          },
         },
       ],
     },
@@ -765,7 +1026,12 @@
   const hierarchyProvider = createHierarchyProvider({
     imodelAccess,
     hierarchyDefinition: createHierarchyDefinition(imodelAccess),
-    filtering: { paths: filterPaths.map((path) => ({ path, options: { autoExpand: true } })) },
+    filtering: {
+      paths: filterPaths.map((path) => ({
+        path,
+        options: { autoExpand: true },
+      })),
+    },
   });
   ```
 
@@ -807,12 +1073,18 @@
       childNodes: [
         {
           parentNodeClassName: "BisCore.PhysicalElement",
-          definitions: async ({ parentNode }) => getPhysicalElementChildren(parentNode),
+          definitions: async ({ parentNode }) =>
+            getPhysicalElementChildren(parentNode),
         },
         {
           parentNodeClassName: "BisCore.SpatialElement",
           definitions: async ({ parentNode, parentNodeClassName }) => {
-            if (await inspector.classDerivesFrom(parentNodeClassName, "BisCore.PhysicalElement")) {
+            if (
+              await inspector.classDerivesFrom(
+                parentNodeClassName,
+                "BisCore.PhysicalElement"
+              )
+            ) {
               return [];
             }
 
@@ -822,11 +1094,21 @@
         {
           parentNodeClassName: "BisCore.GeometricElement3d",
           definitions: async ({ parentNode, parentNodeClassName }) => {
-            if (await inspector.classDerivesFrom(parentNodeClassName, "BisCore.PhysicalElement")) {
+            if (
+              await inspector.classDerivesFrom(
+                parentNodeClassName,
+                "BisCore.PhysicalElement"
+              )
+            ) {
               return [];
             }
 
-            if (await inspector.classDerivesFrom(parentNodeClassName, "BisCore.SpatialElement")) {
+            if (
+              await inspector.classDerivesFrom(
+                parentNodeClassName,
+                "BisCore.SpatialElement"
+              )
+            ) {
               return [];
             }
 
@@ -847,17 +1129,20 @@
       childNodes: [
         {
           parentNodeClassName: "BisCore.PhysicalElement",
-          definitions: async ({ parentNode }) => getPhysicalElementChildren(parentNode),
+          definitions: async ({ parentNode }) =>
+            getPhysicalElementChildren(parentNode),
         },
         {
           parentNodeClassName: "BisCore.SpatialElement",
           onlyIfNotHandled: true,
-          definitions: async ({ parentNode }) => getSpatialElementChildren(parentNode),
+          definitions: async ({ parentNode }) =>
+            getSpatialElementChildren(parentNode),
         },
         {
           parentNodeClassName: "BisCore.GeometricElement3d",
           onlyIfNotHandled: true,
-          definitions: async ({ parentNode }) => getGeometricElement3dChildren(parentNode),
+          definitions: async ({ parentNode }) =>
+            getGeometricElement3dChildren(parentNode),
         },
       ],
     },

package/README.md

@@ -76,7 +76,7 @@ Here's a simple example of how to create a hierarchy provider and build a hierar
 ```ts
 import { IModelConnection } from "@itwin/core-frontend";
 import { createECSchemaProvider, createECSqlQueryExecutor, createIModelKey } from "@itwin/presentation-core-interop";
-import { createLimitingECSqlQueryExecutor } from "@itwin/presentation-hierarchies";
+import { createLimitingECSqlQueryExecutor, HierarchyLevelDefinition } from "@itwin/presentation-hierarchies";
 import { createCachingECClassHierarchyInspector, Props } from "@itwin/presentation-shared";
 
 import {
@@ -138,7 +138,7 @@ function createProvider(imodelAccess: Props<typeof createIModelHierarchyProvider
         {
           // For BisCore.Model parent nodes, select all BisCore.Element instances contained in corresponding model
           parentInstancesNodePredicate: "BisCore.Model",
-          definitions: async ({ parentNodeInstanceIds }: DefineInstanceNodeChildHierarchyLevelProps) => [
+          definitions: async ({ parentNodeInstanceIds }: DefineInstanceNodeChildHierarchyLevelProps): Promise<HierarchyLevelDefinition> => [
             {
               fullClassName: "BisCore.Element",
               query: {

package/lib/cjs/hierarchies/HierarchyNode.d.ts

@@ -1,22 +1,18 @@
 import { HierarchyNodeKey } from "./HierarchyNodeKey.js";
 import type { OmitOverUnion } from "@itwin/presentation-shared";
 import type { ClassGroupingNodeKey, GenericNodeKey, GroupingNodeKey, IModelHierarchyNodeKey, IModelInstanceKey, InstancesNodeKey, LabelGroupingNodeKey, PropertyGroupingNodeKey, PropertyOtherValuesGroupingNodeKey, PropertyValueGroupingNodeKey, PropertyValueRangeGroupingNodeKey } from "./HierarchyNodeKey.js";
-import type { HierarchySearchPath, HierarchySearchPathOptions } from "./HierarchySearch.js";
+import type { HierarchySearchTree } from "./HierarchySearch.js";
 /** @public */
-export type HierarchyNodeSearchProps = {
+export interface HierarchyNodeSearchProps {
     /** If set to true, then one of the ancestor nodes in the hierarchy is the search target. */
     hasSearchTargetAncestor?: boolean;
     /** Paths to node's children that are search targets. */
-    childrenTargetPaths?: HierarchySearchPath[];
-} & ({
+    childrenTargetPaths?: HierarchySearchTree[];
     /** Whether or not this node is a search target. */
-    isSearchTarget?: false;
-} | {
-    /** Whether or not this node is a search target. */
-    isSearchTarget: true;
-    /** Options that were used to search the node. */
-    searchTargetOptions?: HierarchySearchPathOptions;
-});
+    isSearchTarget?: boolean;
+    /** Options assigned to this node through search. */
+    options?: HierarchySearchTree["options"];
+}
 /**
  * A data structure that defines attributes that are common to all types of hierarchy nodes.
  * @public
@@ -136,6 +132,12 @@ export declare namespace HierarchyNode {
         key: PropertyGroupingNodeKey;
         supportsFiltering?: undefined;
     } & GroupingHierarchyNode;
+    /**
+     * Gets the grouping level of the given grouping node.
+     *
+     * May be useful when setting `groupingLevel` for `HierarchySearchTree.options.autoExpand` or `HierarchySearchPathOptions.reveal`.
+     */
+    function getGroupingNodeLevel(groupingNode: Pick<GroupingHierarchyNode, "key" | "parentKeys">): number;
 }
 /**
  * A type of `HierarchyNode` that doesn't know about its children and is an input when requesting

package/lib/cjs/hierarchies/HierarchyNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HierarchyNode.d.ts","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyNode.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,kCAAkC,EAClC,4BAA4B,EAC5B,iCAAiC,EAClC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAE5F,cAAc;AACd,MAAM,MAAM,wBAAwB,GAAG;IACrC,4FAA4F;IAC5F,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,wDAAwD;IACxD,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC7C,GAAG,CACA;IACE,mDAAmD;IACnD,cAAc,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACE,mDAAmD;IACnD,cAAc,EAAE,IAAI,CAAC;IACrB,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;CAClD,CACJ,CAAC;AAEF;;;GAGG;AACH,UAAU,iBAAiB;IACzB,0FAA0F;IAC1F,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yDAAyD;IACzD,YAAY,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,iEAAiE;IACjE,GAAG,EAAE,cAAc,GAAG,gBAAgB,CAAC;IACvC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uEAAuE;IACvE,MAAM,CAAC,EAAE,wBAAwB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,2EAA2E;IAC3E,GAAG,EAAE,eAAe,CAAC;IAErB;;;OAGG;IACH,mBAAmB,EAAE,iBAAiB,EAAE,CAAC;IAEzC,+HAA+H;IAC/H,mBAAmB,CAAC,EAAE,mBAAmB,CAAC,wBAAwB,CAAC,CAAC;CACrE;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,wBAAwB,GAAG,qBAAqB,CAAC;AAE7E,cAAc;AAEd,yBAAiB,aAAa,CAAC;IAC7B,sDAAsD;IACtD,SAAgB,SAAS,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,wBAAwB,GAAG;QAAE,GAAG,EAAE,cAAc,CAAA;KAAE,CAElJ;IACD,8EAA8E;IAC9E,SAAgB,YAAY,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,sBAAsB,CAAA;KAAE,CAElI;IACD,iEAAiE;IACjE,SAAgB,eAAe,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,wBAAwB,GAAG;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,CAE1J;IACD,uDAAuD;IACvD,SAAgB,cAAc,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,qBAAqB,CAE1H;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACzE,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,oBAAoB,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEtG;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACzE,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,oBAAoB,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEtG;IACD,gFAAgF;IAChF,SAAgB,iCAAiC,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACvF,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,kCAAkC,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEpH;IACD,sEAAsE;IACtE,SAAgB,2BAA2B,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACjF,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,4BAA4B,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAE9G;IACD,4EAA4E;IAC5E,SAAgB,gCAAgC,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACtF,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,iCAAiC,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEnH;IACD,gEAAgE;IAChE,SAAgB,sBAAsB,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAC5E,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,uBAAuB,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEzG;CACF;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,KAAK,GAAG,aAAa,IAAI,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC"}
+{"version":3,"file":"HierarchyNode.d.ts","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyNode.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,kCAAkC,EAClC,4BAA4B,EAC5B,iCAAiC,EAClC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,cAAc;AACd,MAAM,WAAW,wBAAwB;IACvC,4FAA4F;IAC5F,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,wDAAwD;IACxD,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC5C,mDAAmD;IACnD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oDAAoD;IACpD,OAAO,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,UAAU,iBAAiB;IACzB,0FAA0F;IAC1F,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yDAAyD;IACzD,YAAY,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,iEAAiE;IACjE,GAAG,EAAE,cAAc,GAAG,gBAAgB,CAAC;IACvC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uEAAuE;IACvE,MAAM,CAAC,EAAE,wBAAwB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,2EAA2E;IAC3E,GAAG,EAAE,eAAe,CAAC;IAErB;;;OAGG;IACH,mBAAmB,EAAE,iBAAiB,EAAE,CAAC;IAEzC,+HAA+H;IAC/H,mBAAmB,CAAC,EAAE,mBAAmB,CAAC,wBAAwB,CAAC,CAAC;CACrE;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,wBAAwB,GAAG,qBAAqB,CAAC;AAE7E,cAAc;AAEd,yBAAiB,aAAa,CAAC;IAC7B,sDAAsD;IACtD,SAAgB,SAAS,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,wBAAwB,GAAG;QAAE,GAAG,EAAE,cAAc,CAAA;KAAE,CAElJ;IACD,8EAA8E;IAC9E,SAAgB,YAAY,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,sBAAsB,CAAA;KAAE,CAElI;IACD,iEAAiE;IACjE,SAAgB,eAAe,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,wBAAwB,GAAG;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,CAE1J;IACD,uDAAuD;IACvD,SAAgB,cAAc,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,qBAAqB,CAE1H;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACzE,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,oBAAoB,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEtG;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACzE,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,oBAAoB,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEtG;IACD,gFAAgF;IAChF,SAAgB,iCAAiC,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACvF,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,kCAAkC,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEpH;IACD,sEAAsE;IACtE,SAAgB,2BAA2B,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACjF,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,4BAA4B,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAE9G;IACD,4EAA4E;IAC5E,SAAgB,gCAAgC,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EACtF,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,iCAAiC,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEnH;IACD,gEAAgE;IAChE,SAAgB,sBAAsB,CAAC,KAAK,SAAS;QAAE,GAAG,EAAE,gBAAgB,CAAA;KAAE,EAC5E,IAAI,EAAE,KAAK,GACV,IAAI,IAAI,KAAK,GAAG;QAAE,GAAG,EAAE,uBAAuB,CAAC;QAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,qBAAqB,CAEzG;IAED;;;;OAIG;IACH,SAAgB,oBAAoB,CAAC,YAAY,EAAE,IAAI,CAAC,qBAAqB,EAAE,KAAK,GAAG,YAAY,CAAC,GAAG,MAAM,CAU5G;CACF;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,KAAK,GAAG,aAAa,IAAI,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC"}

package/lib/cjs/hierarchies/HierarchyNode.js

@@ -60,5 +60,23 @@ var HierarchyNode;
         return HierarchyNodeKey_js_1.HierarchyNodeKey.isPropertyGrouping(node.key);
     }
     HierarchyNode.isPropertyGroupingNode = isPropertyGroupingNode;
+    /**
+     * Gets the grouping level of the given grouping node.
+     *
+     * May be useful when setting `groupingLevel` for `HierarchySearchTree.options.autoExpand` or `HierarchySearchPathOptions.reveal`.
+     */
+    function getGroupingNodeLevel(groupingNode) {
+        let level = 1;
+        for (let i = groupingNode.parentKeys.length - 1; i >= 0; i--) {
+            if (HierarchyNodeKey_js_1.HierarchyNodeKey.isGrouping(groupingNode.parentKeys[i])) {
+                level++;
+            }
+            else {
+                break;
+            }
+        }
+        return level;
+    }
+    HierarchyNode.getGroupingNodeLevel = getGroupingNodeLevel;
 })(HierarchyNode || (exports.HierarchyNode = HierarchyNode = {}));
 //# sourceMappingURL=HierarchyNode.js.map

package/lib/cjs/hierarchies/HierarchyNode.js.map

@@ -1 +1 @@
-{"version":3,"file":"HierarchyNode.js","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyNode.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAEhG,+DAAyD;AA8FzD,cAAc;AACd,2DAA2D;AAC3D,IAAiB,aAAa,CAqD7B;AArDD,WAAiB,aAAa;IAC5B,sDAAsD;IACtD,SAAgB,SAAS,CAA0C,IAAW;QAC5E,OAAO,sCAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IAFe,uBAAS,YAExB,CAAA;IACD,8EAA8E;IAC9E,SAAgB,YAAY,CAA0C,IAAW;QAC/E,OAAO,sCAAgB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAFe,0BAAY,eAE3B,CAAA;IACD,iEAAiE;IACjE,SAAgB,eAAe,CAA0C,IAAW;QAClF,OAAO,sCAAgB,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAFe,6BAAe,kBAE9B,CAAA;IACD,uDAAuD;IACvD,SAAgB,cAAc,CAA0C,IAAW;QACjF,OAAO,sCAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAFe,4BAAc,iBAE7B,CAAA;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CACjC,IAAW;QAEX,OAAO,sCAAgB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAJe,iCAAmB,sBAIlC,CAAA;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CACjC,IAAW;QAEX,OAAO,sCAAgB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAJe,iCAAmB,sBAIlC,CAAA;IACD,gFAAgF;IAChF,SAAgB,iCAAiC,CAC/C,IAAW;QAEX,OAAO,sCAAgB,CAAC,6BAA6B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAJe,+CAAiC,oCAIhD,CAAA;IACD,sEAAsE;IACtE,SAAgB,2BAA2B,CACzC,IAAW;QAEX,OAAO,sCAAgB,CAAC,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5D,CAAC;IAJe,yCAA2B,8BAI1C,CAAA;IACD,4EAA4E;IAC5E,SAAgB,gCAAgC,CAC9C,IAAW;QAEX,OAAO,sCAAgB,CAAC,4BAA4B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;IAJe,8CAAgC,mCAI/C,CAAA;IACD,gEAAgE;IAChE,SAAgB,sBAAsB,CACpC,IAAW;QAEX,OAAO,sCAAgB,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IAJe,oCAAsB,yBAIrC,CAAA;AACH,CAAC,EArDgB,aAAa,6BAAb,aAAa,QAqD7B","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 { HierarchyNodeKey } from \"./HierarchyNodeKey.js\";\n\nimport type { OmitOverUnion } from \"@itwin/presentation-shared\";\nimport type {\n  ClassGroupingNodeKey,\n  GenericNodeKey,\n  GroupingNodeKey,\n  IModelHierarchyNodeKey,\n  IModelInstanceKey,\n  InstancesNodeKey,\n  LabelGroupingNodeKey,\n  PropertyGroupingNodeKey,\n  PropertyOtherValuesGroupingNodeKey,\n  PropertyValueGroupingNodeKey,\n  PropertyValueRangeGroupingNodeKey,\n} from \"./HierarchyNodeKey.js\";\nimport type { HierarchySearchPath, HierarchySearchPathOptions } from \"./HierarchySearch.js\";\n\n/** @public */\nexport type HierarchyNodeSearchProps = {\n  /** If set to true, then one of the ancestor nodes in the hierarchy is the search target. */\n  hasSearchTargetAncestor?: boolean;\n  /** Paths to node's children that are search targets. */\n  childrenTargetPaths?: HierarchySearchPath[];\n} & (\n  | {\n      /** Whether or not this node is a search target. */\n      isSearchTarget?: false;\n    }\n  | {\n      /** Whether or not this node is a search target. */\n      isSearchTarget: true;\n      /** Options that were used to search the node. */\n      searchTargetOptions?: HierarchySearchPathOptions;\n    }\n);\n\n/**\n * A data structure that defines attributes that are common to all types of hierarchy nodes.\n * @public\n */\ninterface BaseHierarchyNode {\n  /** Identifiers of all node ancestors. Can be used to identify a node in the hierarchy. */\n  parentKeys: HierarchyNodeKey[];\n  /** Node's display label. */\n  label: string;\n  /** A flag indicating whether the node has children or not. */\n  children: boolean;\n  /** A flag indicating whether this node should be auto-expanded in the UI. */\n  autoExpand?: boolean;\n  /** Additional data that may be assigned to this node. */\n  extendedData?: { [key: string]: any };\n}\n\n/**\n * A data structure that represents a single non-grouping hierarchy node.\n * @public\n */\nexport interface NonGroupingHierarchyNode extends BaseHierarchyNode {\n  /** An identifier to identify the node in its hierarchy level. */\n  key: GenericNodeKey | InstancesNodeKey;\n  /**\n   * Identifies whether the hierarchy level below this node supports filtering. If not, supplying an instance\n   * filter when requesting child hierarchy level will have no effect.\n   */\n  supportsFiltering?: boolean;\n  /** Data that is assigned to the node if hierarchy search is enabled */\n  search?: HierarchyNodeSearchProps;\n}\n\n/**\n * A data structure that represents a grouping node that groups other nodes.\n * @public\n */\nexport interface GroupingHierarchyNode extends BaseHierarchyNode {\n  /** An identifier to identify this grouping node in its hierarchy level. */\n  key: GroupingNodeKey;\n\n  /**\n   * Keys of all instances grouped by this node, including deeply nested under\n   * other grouping nodes.\n   */\n  groupedInstanceKeys: IModelInstanceKey[];\n\n  /** The closest ancestor node that is not a grouping node. May be `undefined` if the grouping node grouped root level nodes. */\n  nonGroupingAncestor?: ParentHierarchyNode<NonGroupingHierarchyNode>;\n}\n\n/**\n * A data structure that represents a single hierarchy node.\n * @public\n */\nexport type HierarchyNode = NonGroupingHierarchyNode | GroupingHierarchyNode;\n\n/** @public */\n// eslint-disable-next-line @typescript-eslint/no-redeclare\nexport namespace HierarchyNode {\n  /** Checks whether the given node is a generic node */\n  export function isGeneric<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & NonGroupingHierarchyNode & { key: GenericNodeKey } {\n    return HierarchyNodeKey.isGeneric(node.key);\n  }\n  /** Checks whether the given node is a standard (iModel content based) node */\n  export function isIModelNode<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & { key: IModelHierarchyNodeKey } {\n    return HierarchyNodeKey.isIModelNodeKey(node.key);\n  }\n  /** Checks whether the given node is an ECInstances-based node */\n  export function isInstancesNode<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & NonGroupingHierarchyNode & { key: InstancesNodeKey } {\n    return HierarchyNodeKey.isInstances(node.key);\n  }\n  /** Checks whether the given node is a grouping node */\n  export function isGroupingNode<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & GroupingHierarchyNode {\n    return HierarchyNodeKey.isGrouping(node.key);\n  }\n  /** Checks whether the given node is a class grouping node */\n  export function isClassGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: ClassGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isClassGrouping(node.key);\n  }\n  /** Checks whether the given node is a label grouping node */\n  export function isLabelGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: LabelGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isLabelGrouping(node.key);\n  }\n  /** Checks whether the given node is property grouping node for other values  */\n  export function isPropertyOtherValuesGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyOtherValuesGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyOtherValuesGrouping(node.key);\n  }\n  /** Checks whether the given node is a property value grouping node */\n  export function isPropertyValueGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyValueGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyValueGrouping(node.key);\n  }\n  /** Checks whether the given node is a property value range grouping node */\n  export function isPropertyValueRangeGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyValueRangeGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyValueRangeGrouping(node.key);\n  }\n  /** Checks whether the given node is a property grouping node */\n  export function isPropertyGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyGrouping(node.key);\n  }\n}\n\n/**\n * A type of `HierarchyNode` that doesn't know about its children and is an input when requesting\n * them using `HierarchyProvider.getNodes`.\n * @public\n */\nexport type ParentHierarchyNode<TBase = HierarchyNode> = OmitOverUnion<TBase, \"children\">;\n"]}
+{"version":3,"file":"HierarchyNode.js","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyNode.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAEhG,+DAAyD;AAuFzD,cAAc;AACd,2DAA2D;AAC3D,IAAiB,aAAa,CAsE7B;AAtED,WAAiB,aAAa;IAC5B,sDAAsD;IACtD,SAAgB,SAAS,CAA0C,IAAW;QAC5E,OAAO,sCAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IAFe,uBAAS,YAExB,CAAA;IACD,8EAA8E;IAC9E,SAAgB,YAAY,CAA0C,IAAW;QAC/E,OAAO,sCAAgB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAFe,0BAAY,eAE3B,CAAA;IACD,iEAAiE;IACjE,SAAgB,eAAe,CAA0C,IAAW;QAClF,OAAO,sCAAgB,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAFe,6BAAe,kBAE9B,CAAA;IACD,uDAAuD;IACvD,SAAgB,cAAc,CAA0C,IAAW;QACjF,OAAO,sCAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAFe,4BAAc,iBAE7B,CAAA;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CACjC,IAAW;QAEX,OAAO,sCAAgB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAJe,iCAAmB,sBAIlC,CAAA;IACD,6DAA6D;IAC7D,SAAgB,mBAAmB,CACjC,IAAW;QAEX,OAAO,sCAAgB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAJe,iCAAmB,sBAIlC,CAAA;IACD,gFAAgF;IAChF,SAAgB,iCAAiC,CAC/C,IAAW;QAEX,OAAO,sCAAgB,CAAC,6BAA6B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAJe,+CAAiC,oCAIhD,CAAA;IACD,sEAAsE;IACtE,SAAgB,2BAA2B,CACzC,IAAW;QAEX,OAAO,sCAAgB,CAAC,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5D,CAAC;IAJe,yCAA2B,8BAI1C,CAAA;IACD,4EAA4E;IAC5E,SAAgB,gCAAgC,CAC9C,IAAW;QAEX,OAAO,sCAAgB,CAAC,4BAA4B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;IAJe,8CAAgC,mCAI/C,CAAA;IACD,gEAAgE;IAChE,SAAgB,sBAAsB,CACpC,IAAW;QAEX,OAAO,sCAAgB,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IAJe,oCAAsB,yBAIrC,CAAA;IAED;;;;OAIG;IACH,SAAgB,oBAAoB,CAAC,YAA+D;QAClG,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7D,IAAI,sCAAgB,CAAC,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5D,KAAK,EAAE,CAAC;YACV,CAAC;iBAAM,CAAC;gBACN,MAAM;YACR,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAVe,kCAAoB,uBAUnC,CAAA;AACH,CAAC,EAtEgB,aAAa,6BAAb,aAAa,QAsE7B","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 { HierarchyNodeKey } from \"./HierarchyNodeKey.js\";\n\nimport type { OmitOverUnion } from \"@itwin/presentation-shared\";\nimport type {\n  ClassGroupingNodeKey,\n  GenericNodeKey,\n  GroupingNodeKey,\n  IModelHierarchyNodeKey,\n  IModelInstanceKey,\n  InstancesNodeKey,\n  LabelGroupingNodeKey,\n  PropertyGroupingNodeKey,\n  PropertyOtherValuesGroupingNodeKey,\n  PropertyValueGroupingNodeKey,\n  PropertyValueRangeGroupingNodeKey,\n} from \"./HierarchyNodeKey.js\";\nimport type { HierarchySearchTree } from \"./HierarchySearch.js\";\n\n/** @public */\nexport interface HierarchyNodeSearchProps {\n  /** If set to true, then one of the ancestor nodes in the hierarchy is the search target. */\n  hasSearchTargetAncestor?: boolean;\n  /** Paths to node's children that are search targets. */\n  childrenTargetPaths?: HierarchySearchTree[];\n  /** Whether or not this node is a search target. */\n  isSearchTarget?: boolean;\n  /** Options assigned to this node through search. */\n  options?: HierarchySearchTree[\"options\"];\n}\n\n/**\n * A data structure that defines attributes that are common to all types of hierarchy nodes.\n * @public\n */\ninterface BaseHierarchyNode {\n  /** Identifiers of all node ancestors. Can be used to identify a node in the hierarchy. */\n  parentKeys: HierarchyNodeKey[];\n  /** Node's display label. */\n  label: string;\n  /** A flag indicating whether the node has children or not. */\n  children: boolean;\n  /** A flag indicating whether this node should be auto-expanded in the UI. */\n  autoExpand?: boolean;\n  /** Additional data that may be assigned to this node. */\n  extendedData?: { [key: string]: any };\n}\n\n/**\n * A data structure that represents a single non-grouping hierarchy node.\n * @public\n */\nexport interface NonGroupingHierarchyNode extends BaseHierarchyNode {\n  /** An identifier to identify the node in its hierarchy level. */\n  key: GenericNodeKey | InstancesNodeKey;\n  /**\n   * Identifies whether the hierarchy level below this node supports filtering. If not, supplying an instance\n   * filter when requesting child hierarchy level will have no effect.\n   */\n  supportsFiltering?: boolean;\n  /** Data that is assigned to the node if hierarchy search is enabled */\n  search?: HierarchyNodeSearchProps;\n}\n\n/**\n * A data structure that represents a grouping node that groups other nodes.\n * @public\n */\nexport interface GroupingHierarchyNode extends BaseHierarchyNode {\n  /** An identifier to identify this grouping node in its hierarchy level. */\n  key: GroupingNodeKey;\n\n  /**\n   * Keys of all instances grouped by this node, including deeply nested under\n   * other grouping nodes.\n   */\n  groupedInstanceKeys: IModelInstanceKey[];\n\n  /** The closest ancestor node that is not a grouping node. May be `undefined` if the grouping node grouped root level nodes. */\n  nonGroupingAncestor?: ParentHierarchyNode<NonGroupingHierarchyNode>;\n}\n\n/**\n * A data structure that represents a single hierarchy node.\n * @public\n */\nexport type HierarchyNode = NonGroupingHierarchyNode | GroupingHierarchyNode;\n\n/** @public */\n// eslint-disable-next-line @typescript-eslint/no-redeclare\nexport namespace HierarchyNode {\n  /** Checks whether the given node is a generic node */\n  export function isGeneric<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & NonGroupingHierarchyNode & { key: GenericNodeKey } {\n    return HierarchyNodeKey.isGeneric(node.key);\n  }\n  /** Checks whether the given node is a standard (iModel content based) node */\n  export function isIModelNode<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & { key: IModelHierarchyNodeKey } {\n    return HierarchyNodeKey.isIModelNodeKey(node.key);\n  }\n  /** Checks whether the given node is an ECInstances-based node */\n  export function isInstancesNode<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & NonGroupingHierarchyNode & { key: InstancesNodeKey } {\n    return HierarchyNodeKey.isInstances(node.key);\n  }\n  /** Checks whether the given node is a grouping node */\n  export function isGroupingNode<TNode extends { key: HierarchyNodeKey }>(node: TNode): node is TNode & GroupingHierarchyNode {\n    return HierarchyNodeKey.isGrouping(node.key);\n  }\n  /** Checks whether the given node is a class grouping node */\n  export function isClassGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: ClassGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isClassGrouping(node.key);\n  }\n  /** Checks whether the given node is a label grouping node */\n  export function isLabelGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: LabelGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isLabelGrouping(node.key);\n  }\n  /** Checks whether the given node is property grouping node for other values  */\n  export function isPropertyOtherValuesGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyOtherValuesGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyOtherValuesGrouping(node.key);\n  }\n  /** Checks whether the given node is a property value grouping node */\n  export function isPropertyValueGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyValueGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyValueGrouping(node.key);\n  }\n  /** Checks whether the given node is a property value range grouping node */\n  export function isPropertyValueRangeGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyValueRangeGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyValueRangeGrouping(node.key);\n  }\n  /** Checks whether the given node is a property grouping node */\n  export function isPropertyGroupingNode<TNode extends { key: HierarchyNodeKey }>(\n    node: TNode,\n  ): node is TNode & { key: PropertyGroupingNodeKey; supportsFiltering?: undefined } & GroupingHierarchyNode {\n    return HierarchyNodeKey.isPropertyGrouping(node.key);\n  }\n\n  /**\n   * Gets the grouping level of the given grouping node.\n   *\n   * May be useful when setting `groupingLevel` for `HierarchySearchTree.options.autoExpand` or `HierarchySearchPathOptions.reveal`.\n   */\n  export function getGroupingNodeLevel(groupingNode: Pick<GroupingHierarchyNode, \"key\" | \"parentKeys\">): number {\n    let level = 1;\n    for (let i = groupingNode.parentKeys.length - 1; i >= 0; i--) {\n      if (HierarchyNodeKey.isGrouping(groupingNode.parentKeys[i])) {\n        level++;\n      } else {\n        break;\n      }\n    }\n    return level;\n  }\n}\n\n/**\n * A type of `HierarchyNode` that doesn't know about its children and is an input when requesting\n * them using `HierarchyProvider.getNodes`.\n * @public\n */\nexport type ParentHierarchyNode<TBase = HierarchyNode> = OmitOverUnion<TBase, \"children\">;\n"]}

package/lib/cjs/hierarchies/HierarchyNodeIdentifier.d.ts

@@ -18,6 +18,8 @@ export declare namespace HierarchyNodeIdentifier {
     function isGenericNodeIdentifier(id: HierarchyNodeIdentifier): id is GenericNodeKey;
     /** Checks two identifiers for equality */
     function equal(lhs: HierarchyNodeIdentifier, rhs: HierarchyNodeIdentifier): boolean;
+    /** Compares two identifiers */
+    function compare(lhs: HierarchyNodeIdentifier, rhs: HierarchyNodeIdentifier): number;
 }
 /**
  * A path of hierarchy node identifiers, typically used to describe a path from root down