@itwin/presentation-hierarchies 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @itwin/presentation-hierarchies
 
+## 0.7.0
+
+### 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:
+      - `StandardHierarchyNodeKey` renamed to `IModelHierarchyNodeKey`.
+      - `HierarchyNodeKey.isStandard` renamed to `HierarchyNodeKey.isIModelNodeKey`.
+      - `HierarchyNode.isStandard` renamed to `HierarchyNode.isIModelNode`.
+    - "Custom" nodes were renamed to "generic":
+      - `key` of custom nodes was a `string`. Now, `HierarchyProvider` returns these nodes with key of type `GenericNodeKey` (`HierarchyDefinition` still returns the `key` as `string` like before). This affects how generic nodes are identified through `HierarchyNodeIdentifier` when specifying hierarchy filter paths (was a `string`, now `GenericNodeKey`).
+      - `DefineCustomNodeChildHierarchyLevelProps` renamed to `DefineGenericNodeChildHierarchyLevelProps`.
+      - `HierarchyNodeKey.isCustom` renamed to `HierarchyNodeKey.isGeneric`.
+      - `HierarchyNode.isCustom` renamed to `HierarchyNode.isGeneric`.
+      - `HierarchyNodeIdentifier.isCustomNodeIdentifier` renamed to `HierarchyNodeIdentifier.isGenericNodeIdentifier`.
+      - `HierarchyNodesDefinition.isCustomNode` renamed to `HierarchyNodesDefinition.isGenericNode`.
+    - `ParsedHierarchyNode` was renamed to `SourceHierarchyNode`.
+    - Type guards in `HierarchyNode` namespace no longer narrow the type of the input node to `ProcessedHierarchyNode` subtypes. Instead, a `ProcessedHierarchyNode` namespace was added with a number of type guards to do that.
+  - Changes to `HierarchyProvider` interface:
+    - Removed `notifyDataSourceChanged` method. Each provider implementation should decide how it gets notified about data source changes.
+    - Added `setHierarchyFilter` method to allow setting or removing the filter without creating a new provider.
+  - Renamed `createHierarchyProvider` to `createIModelHierarchyProvider` to signify that the created provider creates nodes based on specific iModel. In addition, the function received the following changes:
+    - The `imodelAccess` object now requires an additional `imodelKey` attribute. See README for how to create the `imodelAccess` object.
+    - All nodes returned by the provider are now associated with the iModel this provider is using:
+      - Instances-based hierarchy nodes' instance keys have an `imodelKey` attribute.
+      - Generic nodes' keys have a `source` attribute set to imodel access' `imodelKey`.
+    - Added an optional `imodelChanged` prop of `Event` type. The created provider listens to this event and updates the hierarchy when the event is raised (previously this was done by calling `notifyDataSourceChanged` method on the provider).
+    - 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.
+
+    Migration:
+
+    ```ts
+    // before
+    const definition = createClassBasedHierarchyDefinition({
+      classHierarchyInspector,
+      hierarchy: {
+        rootNodes: async () => [...],
+        childNodes: [
+          {
+            parentNodeClassName: "MySchema.MyClass",
+            definitions: async () => [...],
+          },
+          {
+            customParentNodeKey: "my-custom-node",
+            definitions: async () => [...],
+          },
+        ],
+      },
+    });
+
+    // after
+    const definition = createPredicateBasedHierarchyDefinition({
+      classHierarchyInspector,
+      hierarchy: {
+        rootNodes: async () => [...],
+        childNodes: [
+          {
+            parentInstancesNodePredicate: "MySchema.MyClass",
+            /* alternative:
+            parentInstancesNodePredicate: async (parentKey) =>
+              Promise.all(
+                parentKey.instanceKeys.map(async (instanceKey) =>
+                  classHierarchyInspector.classDerivesFrom(instanceKey.className, "MySchema.MyClass"),
+                ),
+              ),
+            */
+            definitions: async () => [...],
+          },
+          {
+            parentGenericNodePredicate: async (parentKey) => parentKey.id === "my-custom-node",
+            definitions: async () => [...],
+          },
+        ],
+      },
+    });
+    ```
+
+- [#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.
+    - `normalize` takes `HierarchyFilteringPath`, which may be either a pure path or an object with a path and options, and returns normalized version of it - an object with `path` and `options` attributes.
+
+- [#717](https://github.com/iTwin/presentation/pull/717): **BREAKING:** Added a required `HierarchyProvider.hierarchyChanged` attribute.
+
+  The attribute is of type `Event` and should be raised by the provider whenever the underlying data source changes in a way that affects the resulting hierarchy. This moves the responsibility of data source change tracking from the consumers using the provider to the provider itself. All provider implementations delivered by this package have been updated to raise this event when necessary.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -2,9 +2,9 @@
 
 Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.
 
-The `@itwin/presentation-hierarchies` package provides APIs for creating hierarchical data structures based on data in an [iTwin.js iModel](https://www.itwinjs.org/learning/imodels/#imodel-overview).
+The `@itwin/presentation-hierarchies` package provides APIs for creating hierarchical data structures. While most of the delivered APIs are intended for the use case we anticipate the most - hierarchies based on data in an [iTwin.js iModel](https://www.itwinjs.org/learning/imodels/#imodel-overview), the package also supports generic hierarchies that are not based on any specific data source.
 
-The package doesn't depend on any backend, frontend or UI specific packages. As such, it can be used in both backend and frontend applications, and in case of the latter, it can be used with any UI framework. For React-based frontend applications, please see the `@itwin/presentation-hierarchies-react` package.
+The package doesn't depend on any backend, frontend or UI specific packages. As such, it can be used in both backend and frontend applications, and in case of the latter, it can be used with any UI framework. For React-based frontend applications, please see the [`@itwin/presentation-hierarchies-react`](../hierarchies-react/README.md) package.
 
 ## Concepts
 
@@ -18,14 +18,14 @@ Here are definitions of some basic hierarchy-related concepts based on the above
 - A hierarchy level is a group of hierarchy nodes that are at the same level in the hierarchy. In the above example the root level contains `Node 0`, `Node 1` and `Node 2`. Child level of `Node 2` contains `Node 2-0`, `Node 2-1`.
 - A hierarchy branch is a sub-hierarchy under specific parent node, including the parent itself. In the above example, the branch of `Node 2` contains `Node 2`, `Node 2-0`, `Node 2-1` and `Node 2-1-0`.
 
-In the context of `@itwin/presentation-hierarchies` package, a hierarchy is built by requesting hierarchy levels from a [hierarchy provider](#hierarchy-provider). The provider knows how to create hierarchy levels based on the data in an iModel and a [hierarchy definition](#hierarchy-definition).
+In the context of `@itwin/presentation-hierarchies` package, a hierarchy is built by requesting hierarchy levels from a [hierarchy provider](#hierarchy-providers). A couple of built-in hierarchy provider implementations are delivered with the package - see [hierarchy providers](#hierarchy-providers) section for more information.
 
 ### Hierarchy nodes
 
-A `HierarchyNode` interface in the package represents a single node in a hierarchy. It contains information about what the node represents in the iModel (through it's `key` property), label and other properties. There are multiple types of nodes:
+A `HierarchyNode` data structure in the package represents a single node in a hierarchy. It contains information about what the node represents (through it's `key` property), label and other properties. There are multiple types of nodes:
 
-- A custom node is not based on any iModel data and is created by the application. Its `key` is a string.
-- An instances node is based on one or more ECInstance(s) in the iModel. Its `key` is an `InstancesNodeKey` and contains identifiers of those ECInstances.
+- A generic node is not based on any iModel data. Its `key` is a `GenericNodeKey` and has a consumer-supplied identifier with an optional `source` attribute identifying the hierarchy provider that created the node.
+- An instances node is based on one or more ECInstance(s) in an iModel. Its `key` is an `InstancesNodeKey` and contains identifiers of those ECInstances, in addition to `imodelKey` attribute that identifies the source iModel.
 - A grouping node groups one or more instances nodes. Its `key` is a `GroupingNodeKey` and contains the grouping criteria, which depends on the type of grouping:
   - Label grouping node keys have a label.
   - Class grouping nodes have a full class name.
@@ -33,27 +33,13 @@ A `HierarchyNode` interface in the package represents a single node in a hierarc
 
 `HierarchyNode` and `HierarchyNodeKey` namespaces contain type guards and utility functions for working with hierarchy nodes and their keys.
 
-A `HierarchyNode` goes through several stages throughout its lifetime:
+### Hierarchy providers
 
-1. A node starts its life as a `ParsedHierarchyNode` when it's initially parsed from ECSQL query results or returned by a [hierarchy definition](#hierarchy-definition) as a custom node. This variation has no information about its ancestors (position in the hierarchy) and may have unformatted label. Parsed nodes may only be custom or instances nodes.
+`HierarchyProvider` is the core concept of the library, which consumers use directly to build hierarchies. While that is an interface that consumers are free to implement, the package delivers a couple of built-in implementations:
 
-2. A node becomes a `ProcessedHierarchyNode` as soon as it starts being processed by a [hierarchy provider](#hierarchy-provider). During the processing, provider assigns a formatted label, handles node hiding, grouping, sorting and other operations. A [hierarchy definition](#hierarchy-definition) gets a chance to step into the process as well. In case of grouping, new grouping nodes may be created.
+- A provider that builds hierarchies based on data in an [iTwin.js iModel](https://www.itwinjs.org/learning/imodels/#imodel-overview). The `createIModelHierarchyProvider` function is used to create such a provider. See [iModel-based hierarchies](./learning/imodel/HierarchyProvider.md) learning page for more information.
 
-3. Finally, all the processing-related information is cleaned up from `ProcessedHierarchyNode` and it becomes a `HierarchyNode`, which is what consumers get from a [hierarchy provider](#hierarchy-provider).
-
-### Hierarchy definition
-
-A hierarchy definition is what describes the hierarchy by defining what child nodes to return for a given parent node. In this package that is achieved though the `HierarchyDefinition` interface, which has one required method - `defineHierarchyLevel`. The method's responsibility is to create a `HierarchyLevelDefinition` for a given parent node. A `HierarchyLevelDefinition` is actually just a set of `HierarchyNodesDefinition` objects, which either describe a single custom node, or an ECSQL query that returns a number of ECInstance nodes. When `HierarchyLevelDefinition` consists of more than 1 `HierarchyNodesDefinition`, the hierarchy level is combined from multiple sets of nodes.
-
-In case of ECSQL queries for creating the hierarchy level, the definition may want to select some extra information and assign it to the nodes. For that purpose, there's an optional `HierarchyDefinition.parseNode` method, which lets the definition parse the query results handle those extra columns.
-
-Finally, the library also allows hierarchy definitions to step into nodes processing chain through the optional `preProcessNode` and `postProcessNode` methods. These methods are called before and after the node is processed by a [hierarchy provider](#hierarchy-provider) respectively and allow hiding and customizing nodes.
-
-In iTwin.js, the most common way to create hierarchies is based on EC data (schemas, classes, relationships) in iModels. To make consumers' life easier, the package provides an utility called `createClassBasedHierarchyDefinition`, which lets consumers define hierarchy levels based on parent nodes' class.
-
-### Hierarchy provider
-
-`HierarchyProvider` the core concept of the library - it's responsibility is to glue everything together, including evaluating hierarchy definition, running the queries, processing nodes and, finally, returning them to consumers. The package delivers the `createHierarchyProvider` function to create an instance of `HierarchyProvider`.
+- A merged provider that combines multiple providers into a single one. This is useful when you want to combine multiple hierarchies, possibly built from different data sources, into a single one. See [Merged hierarchies](./learning/MergedHierarchies.md) learning page for more information.
 
 ## Learning
 
@@ -61,24 +47,28 @@ Are you migrating from Presentation Rules? Check out our [Migrating from Present
 
 Below is a list of learning material related to building hierarchies:
 
-- [Hierarchy processing](./learning/HierarchyProcessing.md)
-- [Hierarchy definitions](./learning/HierarchyDefinitions.md)
-- [Hierarchy filtering](./learning/HierarchyFiltering.md)
-- [Hierarchy level filtering](./learning/HierarchyLevelFiltering.md)
-- [Hierarchy node labels](./learning/NodeLabels.md)
-- [Grouping](./learning/Grouping.md)
-- [Formatting](./learning/Formatting.md)
-- [Localization](./learning/Localization.md)
-- [Logging](./learning/Logging.md)
-- [Performance tuning](./learning/PerformanceTuning.md)
+- General topics:
+  - [Formatting](./learning/Formatting.md)
+  - [Logging](./learning/Logging.md)
+  - [Hierarchy filtering](./learning/HierarchyFiltering.md)
+  - [Merged hierarchies](./learning/MergedHierarchies.md)
+- iModel-based hierarchies:
+  - [Hierarchy provider](./learning/imodel/HierarchyProvider.md)
+  - [Hierarchy definition](./learning/imodel/HierarchyDefinition.md)
+  - [Hierarchy node labels](./learning/imodel/HierarchyNodeLabels.md)
+  - [Hierarchy filtering](./learning/imodel/HierarchyFiltering.md)
+  - [Hierarchy level filtering](./learning/imodel/HierarchyLevelFiltering.md)
+  - [Grouping](./learning/imodel/Grouping.md)
+  - [Localization](./learning/imodel/Localization.md)
+  - [Performance tuning](./learning/imodel/PerformanceTuning.md)
 
 Do you think something is missing in the above list? Let us know by [creating an issue](https://github.com/iTwin/presentation/issues/new?assignees=&labels=documentation%2C+presentation&projects=&template=learning-material-request.md&title=).
 
 ## Basic example
 
-Here's a simple example of how to create a hierarchy provider and build a hierarchy of Models and their Elements, with the latter grouped by class:
+Here's a simple example of how to create a hierarchy provider and build a hierarchy of iModels' Models and Elements, with the latter grouped by class:
 
-<!-- [[include: Presentation.Hierarchies.Readme.BasicExample, ts]] -->
+<!-- [[include: [Presentation.Hierarchies.IModelAccessImports, Presentation.Hierarchies.ReadmeExampleImports, Presentation.Hierarchies.IModelAccess, Presentation.Hierarchies.ReadmeExample], ts]] -->
 <!-- BEGIN EXTRACTION -->
 
 ```ts
@@ -86,16 +76,18 @@ import { IModelConnection } from "@itwin/core-frontend";
 import { SchemaContext } from "@itwin/ecschema-metadata";
 import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
 import { createECSchemaProvider, createECSqlQueryExecutor } from "@itwin/presentation-core-interop";
+import { createLimitingECSqlQueryExecutor } from "@itwin/presentation-hierarchies";
+import { createCachingECClassHierarchyInspector } from "@itwin/presentation-shared";
+
 import {
-  createClassBasedHierarchyDefinition,
-  createHierarchyProvider,
-  createLimitingECSqlQueryExecutor,
+  createIModelHierarchyProvider,
   createNodesQueryClauseFactory,
+  createPredicateBasedHierarchyDefinition,
   DefineInstanceNodeChildHierarchyLevelProps,
   HierarchyNode,
   HierarchyProvider,
 } from "@itwin/presentation-hierarchies";
-import { createBisInstanceLabelSelectClauseFactory, createCachingECClassHierarchyInspector, ECSqlBinding } from "@itwin/presentation-shared";
+import { createBisInstanceLabelSelectClauseFactory, ECSqlBinding } from "@itwin/presentation-shared";
 
 // Not really part of the package, but we need SchemaContext to create a hierarchy provider. It's
 // recommended to cache the schema context and reuse it across different application's components to
@@ -112,10 +104,12 @@ function getIModelSchemaContext(imodel: IModelConnection) {
   return context;
 }
 
-function createProvider(imodel: IModelConnection): HierarchyProvider {
-  // First, set up access to the iModel
+function createIModelAccess(imodel: IModelConnection) {
   const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
-  const imodelAccess = {
+  return {
+    // The key of the iModel we're accessing
+    imodelKey: imodel.key,
+    // Schema provider provides access to EC information (metadata)
     ...schemaProvider,
     // While caching for hierarchy inspector is not mandatory, it's recommended to use it to improve performance
     ...createCachingECClassHierarchyInspector({ schemaProvider, cacheSize: 100 }),
@@ -123,14 +117,17 @@ function createProvider(imodel: IModelConnection): HierarchyProvider {
     // avoid creating hierarchy levels of insane size (expensive to us and useless to users)
     ...createLimitingECSqlQueryExecutor(createECSqlQueryExecutor(imodel), 1000),
   };
+}
 
+function createProvider(imodelAccess: Parameters<typeof createIModelHierarchyProvider>[0]["imodelAccess"]): HierarchyProvider {
   // Create a factory for building labels SELECT query clauses according to BIS conventions
   const labelsQueryFactory = createBisInstanceLabelSelectClauseFactory({ classHierarchyInspector: imodelAccess });
+
   // Create a factory for building nodes SELECT query clauses in a format understood by the provider
   const nodesQueryFactory = createNodesQueryClauseFactory({ imodelAccess, instanceLabelSelectClauseFactory: labelsQueryFactory });
 
   // Then, define the hierarchy
-  const hierarchyDefinition = createClassBasedHierarchyDefinition({
+  const hierarchyDefinition = createPredicateBasedHierarchyDefinition({
     classHierarchyInspector: imodelAccess,
     hierarchy: {
       // For root nodes, select all BisCore.GeometricModel3d instances
@@ -155,7 +152,7 @@ function createProvider(imodel: IModelConnection): HierarchyProvider {
       childNodes: [
         {
           // For BisCore.Model parent nodes, select all BisCore.Element instances contained in corresponding model
-          parentNodeClassName: "BisCore.Model",
+          parentInstancesNodePredicate: "BisCore.Model",
           definitions: async ({ parentNodeInstanceIds }: DefineInstanceNodeChildHierarchyLevelProps) => [
             {
               fullClassName: "BisCore.Element",
@@ -185,11 +182,11 @@ function createProvider(imodel: IModelConnection): HierarchyProvider {
   });
 
   // Finally, create the provider
-  return createHierarchyProvider({ imodelAccess, hierarchyDefinition });
+  return createIModelHierarchyProvider({ imodelAccess, hierarchyDefinition });
 }
 
 async function main() {
-  const provider = createProvider(await getIModelConnection());
+  const provider = createProvider(createIModelAccess(await getIModelConnection()));
   async function loadBranch(parentNode: HierarchyNode | undefined, indent: number = 0) {
     for await (const node of provider.getNodes({ parentNode })) {
       console.log(`${new Array(indent * 2 + 1).join(" ")}${node.label}`);

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

@@ -0,0 +1,64 @@
+import { NonGroupingHierarchyNode } from "./HierarchyNode";
+import { HierarchyNodeIdentifiersPath } from "./HierarchyNodeIdentifier";
+import { GroupingNodeKey } from "./HierarchyNodeKey";
+/** @beta */
+export interface FilterTargetGroupingNodeInfo {
+    /** Key of the grouping node. */
+    key: GroupingNodeKey;
+    /**
+     * Depth of the grouping node in the hierarchy.
+     * Generally, it can be retrieved from `parentKeys.length`.
+     */
+    depth: number;
+}
+/** @beta */
+export interface HierarchyFilteringPathOptions {
+    /**
+     * This option specifies the way `autoExpand` flag should be assigned to nodes in the filtered hierarchy.
+     * - If it's `false` or `undefined`, nodes have no 'autoExpand' flag.
+     * - If it's `true`, then all nodes up to the filter target will have `autoExpand` flag.
+     * - If it's an instance of `FilterTargetGroupingNodeInfo`, then all nodes up to the grouping node that matches this property,
+     * will have `autoExpand` flag.
+     */
+    autoExpand?: boolean | FilterTargetGroupingNodeInfo;
+}
+/**
+ * A path of hierarchy node identifiers for filtering the hierarchy with additional options.
+ * @beta
+ */
+export type HierarchyFilteringPath = HierarchyNodeIdentifiersPath | {
+    path: HierarchyNodeIdentifiersPath;
+    options?: HierarchyFilteringPathOptions;
+};
+/** @beta */
+export declare namespace HierarchyFilteringPath {
+    /**
+     * Normalizes the hierarchy filtering path to the object form.
+     * @beta
+     */
+    function normalize(source: HierarchyFilteringPath): Exclude<HierarchyFilteringPath, HierarchyNodeIdentifiersPath>;
+    /**
+     * Merges two given `HierarchyFilteringPathOptions` objects.
+     * - if both inputs are `undefined`, `undefined` is returned,
+     * - else if one of the inputs is `undefined`, the other one is returned.
+     * - else, merge each option individually.
+     *
+     * For the `autoExpand` attribute, the merge chooses to auto-expand as deep as the deepest input:
+     * - if one of the inputs is `true`, return `true`,
+     * - else if both inputs are objects, return the one with the greater `depth` attribute.
+     * - else, return `false` or `undefined`.
+     *
+     * @beta
+     */
+    function mergeOptions(lhs: HierarchyFilteringPathOptions | undefined, rhs: HierarchyFilteringPathOptions | undefined): HierarchyFilteringPathOptions | undefined;
+}
+/**
+ * An utility that extracts filtering properties from given root level filtering props or
+ * the parent node. Returns `undefined` if filtering props are not present.
+ * @beta
+ */
+export declare function extractFilteringProps(rootLevelFilteringProps: HierarchyFilteringPath[], parentNode: Pick<NonGroupingHierarchyNode, "filtering"> | undefined): {
+    filteredNodePaths: HierarchyFilteringPath[];
+    hasFilterTargetAncestor: boolean;
+} | undefined;
+//# sourceMappingURL=HierarchyFiltering.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyFiltering.d.ts","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyFiltering.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,YAAY;AACZ,MAAM,WAAW,4BAA4B;IAC3C,gCAAgC;IAChC,GAAG,EAAE,eAAe,CAAC;IAErB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,YAAY;AACZ,MAAM,WAAW,6BAA6B;IAC5C;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,4BAA4B,CAAC;CACrD;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,GAAG;IAAE,IAAI,EAAE,4BAA4B,CAAC;IAAC,OAAO,CAAC,EAAE,6BAA6B,CAAA;CAAE,CAAC;AACpJ,YAAY;AAEZ,yBAAiB,sBAAsB,CAAC;IACtC;;;OAGG;IACH,SAAgB,SAAS,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,EAAE,4BAA4B,CAAC,CAKvH;IAED;;;;;;;;;;;;OAYG;IACH,SAAgB,YAAY,CAC1B,GAAG,EAAE,6BAA6B,GAAG,SAAS,EAC9C,GAAG,EAAE,6BAA6B,GAAG,SAAS,GAC7C,6BAA6B,GAAG,SAAS,CAwB3C;CACF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,uBAAuB,EAAE,sBAAsB,EAAE,EACjD,UAAU,EAAE,IAAI,CAAC,wBAAwB,EAAE,WAAW,CAAC,GAAG,SAAS,GAEjE;IACE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;IAC5C,uBAAuB,EAAE,OAAO,CAAC;CAClC,GACD,SAAS,CAUZ"}

package/lib/cjs/hierarchies/HierarchyFiltering.js

@@ -0,0 +1,80 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HierarchyFilteringPath = void 0;
+exports.extractFilteringProps = extractFilteringProps;
+/** @beta */
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+var HierarchyFilteringPath;
+(function (HierarchyFilteringPath) {
+    /**
+     * Normalizes the hierarchy filtering path to the object form.
+     * @beta
+     */
+    function normalize(source) {
+        if (Array.isArray(source)) {
+            return { path: source, options: undefined };
+        }
+        return source;
+    }
+    HierarchyFilteringPath.normalize = normalize;
+    /**
+     * Merges two given `HierarchyFilteringPathOptions` objects.
+     * - if both inputs are `undefined`, `undefined` is returned,
+     * - else if one of the inputs is `undefined`, the other one is returned.
+     * - else, merge each option individually.
+     *
+     * For the `autoExpand` attribute, the merge chooses to auto-expand as deep as the deepest input:
+     * - if one of the inputs is `true`, return `true`,
+     * - else if both inputs are objects, return the one with the greater `depth` attribute.
+     * - else, return `false` or `undefined`.
+     *
+     * @beta
+     */
+    function mergeOptions(lhs, rhs) {
+        // istanbul ignore next
+        if (!lhs && !rhs) {
+            return undefined;
+        }
+        // istanbul ignore next
+        if (!lhs) {
+            return rhs;
+        }
+        // istanbul ignore next
+        if (!rhs) {
+            return lhs;
+        }
+        return {
+            autoExpand: (() => {
+                if (rhs.autoExpand === true) {
+                    return rhs.autoExpand;
+                }
+                if (typeof lhs.autoExpand === "object" && typeof rhs.autoExpand === "object" && rhs.autoExpand.depth > lhs.autoExpand.depth) {
+                    return rhs.autoExpand;
+                }
+                return lhs.autoExpand;
+            })(),
+        };
+    }
+    HierarchyFilteringPath.mergeOptions = mergeOptions;
+})(HierarchyFilteringPath || (exports.HierarchyFilteringPath = HierarchyFilteringPath = {}));
+/**
+ * An utility that extracts filtering properties from given root level filtering props or
+ * the parent node. Returns `undefined` if filtering props are not present.
+ * @beta
+ */
+function extractFilteringProps(rootLevelFilteringProps, parentNode) {
+    if (!parentNode) {
+        return { filteredNodePaths: rootLevelFilteringProps, hasFilterTargetAncestor: false };
+    }
+    return parentNode.filtering?.filteredChildrenIdentifierPaths
+        ? {
+            filteredNodePaths: parentNode.filtering.filteredChildrenIdentifierPaths,
+            hasFilterTargetAncestor: !!parentNode.filtering.hasFilterTargetAncestor || !!parentNode.filtering.isFilterTarget,
+        }
+        : undefined;
+}
+//# sourceMappingURL=HierarchyFiltering.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyFiltering.js","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyFiltering.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAiGhG,sDAkBC;AAhFD,YAAY;AACZ,2DAA2D;AAC3D,IAAiB,sBAAsB,CAqDtC;AArDD,WAAiB,sBAAsB;IACrC;;;OAGG;IACH,SAAgB,SAAS,CAAC,MAA8B;QACtD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QAC9C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IALe,gCAAS,YAKxB,CAAA;IAED;;;;;;;;;;;;OAYG;IACH,SAAgB,YAAY,CAC1B,GAA8C,EAC9C,GAA8C;QAE9C,uBAAuB;QACvB,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACjB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,uBAAuB;QACvB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,GAAG,CAAC;QACb,CAAC;QACD,uBAAuB;QACvB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO;YACL,UAAU,EAAE,CAAC,GAAgD,EAAE;gBAC7D,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;oBAC5B,OAAO,GAAG,CAAC,UAAU,CAAC;gBACxB,CAAC;gBACD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;oBAC5H,OAAO,GAAG,CAAC,UAAU,CAAC;gBACxB,CAAC;gBACD,OAAO,GAAG,CAAC,UAAU,CAAC;YACxB,CAAC,CAAC,EAAE;SACL,CAAC;IACJ,CAAC;IA3Be,mCAAY,eA2B3B,CAAA;AACH,CAAC,EArDgB,sBAAsB,sCAAtB,sBAAsB,QAqDtC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CACnC,uBAAiD,EACjD,UAAmE;IAOnE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,KAAK,EAAE,CAAC;IACxF,CAAC;IACD,OAAO,UAAU,CAAC,SAAS,EAAE,+BAA+B;QAC1D,CAAC,CAAC;YACE,iBAAiB,EAAE,UAAU,CAAC,SAAS,CAAC,+BAA+B;YACvE,uBAAuB,EAAE,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,uBAAuB,IAAI,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,cAAc;SACjH;QACH,CAAC,CAAC,SAAS,CAAC;AAChB,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 { NonGroupingHierarchyNode } from \"./HierarchyNode\";\nimport { HierarchyNodeIdentifiersPath } from \"./HierarchyNodeIdentifier\";\nimport { GroupingNodeKey } from \"./HierarchyNodeKey\";\n\n/** @beta */\nexport interface FilterTargetGroupingNodeInfo {\n  /** Key of the grouping node. */\n  key: GroupingNodeKey;\n\n  /**\n   * Depth of the grouping node in the hierarchy.\n   * Generally, it can be retrieved from `parentKeys.length`.\n   */\n  depth: number;\n}\n\n/** @beta */\nexport interface HierarchyFilteringPathOptions {\n  /**\n   * This option specifies the way `autoExpand` flag should be assigned to nodes in the filtered hierarchy.\n   * - If it's `false` or `undefined`, nodes have no 'autoExpand' flag.\n   * - If it's `true`, then all nodes up to the filter target will have `autoExpand` flag.\n   * - If it's an instance of `FilterTargetGroupingNodeInfo`, then all nodes up to the grouping node that matches this property,\n   * will have `autoExpand` flag.\n   */\n  autoExpand?: boolean | FilterTargetGroupingNodeInfo;\n}\n\n/**\n * A path of hierarchy node identifiers for filtering the hierarchy with additional options.\n * @beta\n */\nexport type HierarchyFilteringPath = HierarchyNodeIdentifiersPath | { path: HierarchyNodeIdentifiersPath; options?: HierarchyFilteringPathOptions };\n/** @beta */\n// eslint-disable-next-line @typescript-eslint/no-redeclare\nexport namespace HierarchyFilteringPath {\n  /**\n   * Normalizes the hierarchy filtering path to the object form.\n   * @beta\n   */\n  export function normalize(source: HierarchyFilteringPath): Exclude<HierarchyFilteringPath, HierarchyNodeIdentifiersPath> {\n    if (Array.isArray(source)) {\n      return { path: source, options: undefined };\n    }\n    return source;\n  }\n\n  /**\n   * Merges two given `HierarchyFilteringPathOptions` objects.\n   * - if both inputs are `undefined`, `undefined` is returned,\n   * - else if one of the inputs is `undefined`, the other one is returned.\n   * - else, merge each option individually.\n   *\n   * For the `autoExpand` attribute, the merge chooses to auto-expand as deep as the deepest input:\n   * - if one of the inputs is `true`, return `true`,\n   * - else if both inputs are objects, return the one with the greater `depth` attribute.\n   * - else, return `false` or `undefined`.\n   *\n   * @beta\n   */\n  export function mergeOptions(\n    lhs: HierarchyFilteringPathOptions | undefined,\n    rhs: HierarchyFilteringPathOptions | undefined,\n  ): HierarchyFilteringPathOptions | undefined {\n    // istanbul ignore next\n    if (!lhs && !rhs) {\n      return undefined;\n    }\n    // istanbul ignore next\n    if (!lhs) {\n      return rhs;\n    }\n    // istanbul ignore next\n    if (!rhs) {\n      return lhs;\n    }\n    return {\n      autoExpand: ((): HierarchyFilteringPathOptions[\"autoExpand\"] => {\n        if (rhs.autoExpand === true) {\n          return rhs.autoExpand;\n        }\n        if (typeof lhs.autoExpand === \"object\" && typeof rhs.autoExpand === \"object\" && rhs.autoExpand.depth > lhs.autoExpand.depth) {\n          return rhs.autoExpand;\n        }\n        return lhs.autoExpand;\n      })(),\n    };\n  }\n}\n\n/**\n * An utility that extracts filtering properties from given root level filtering props or\n * the parent node. Returns `undefined` if filtering props are not present.\n * @beta\n */\nexport function extractFilteringProps(\n  rootLevelFilteringProps: HierarchyFilteringPath[],\n  parentNode: Pick<NonGroupingHierarchyNode, \"filtering\"> | undefined,\n):\n  | {\n      filteredNodePaths: HierarchyFilteringPath[];\n      hasFilterTargetAncestor: boolean;\n    }\n  | undefined {\n  if (!parentNode) {\n    return { filteredNodePaths: rootLevelFilteringProps, hasFilterTargetAncestor: false };\n  }\n  return parentNode.filtering?.filteredChildrenIdentifierPaths\n    ? {\n        filteredNodePaths: parentNode.filtering.filteredChildrenIdentifierPaths,\n        hasFilterTargetAncestor: !!parentNode.filtering.hasFilterTargetAncestor || !!parentNode.filtering.isFilterTarget,\n      }\n    : undefined;\n}\n"]}