@itwin/presentation-hierarchies-react 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @itwin/presentation-hierarchies-react
 
+## 0.8.0
+
+### Minor Changes
+
+- [#708](https://github.com/iTwin/presentation/pull/708): **BREAKING:** A new attribute - `imodelKey` - has been added to `imodelAccess` prop of "use tree" hooks. For the most common case when a hierarchy is built from an `IModelConnection`, it's recommended to use `key` attribute of the connection as this value.
+
+  Example:
+
+  ```ts
+  function createHierarchyProvider(imodel: IModelConnection) {
+    return createIModelHierarchyProvider({
+      imodelAccess: {
+        imodelKey: imodel.key, // set the newly introduced `imodelKey` attribute
+        // ... other iModel access props
+      },
+      // ... other provider props
+    });
+  }
+  ```
+
+  See "Basic example" section in README learning page for the full example.
+
+- [#717](https://github.com/iTwin/presentation/pull/717): **BREAKING:** Add support for non-iModel-driven trees.
+
+  - `useTree` and `useUnifiedSelectionTree` hooks have been changed to support non-iModel-driven trees. The hooks take a `getHierarchyProvider` prop, which returns a `HierarchyProvider`. The provider can return data from any data source.
+  - New `useIModelTree` and `useIModelUnifiedSelectionTree` hooks have been added to cover the most common case, where a tree is created from a iModel's data. The API of these hooks is exactly the same as of the old `useTree` and `useUnifiedSelectionTree` hooks.
+
+  Reacting to this breaking change is as simple as renaming the calls to `useTree` and `useUnifiedSelectionTree` to `useIModelTree` and `useIModelUnifiedSelectionTree`, respectively.
+
+- [#717](https://github.com/iTwin/presentation/pull/717): **BREAKING:** The `reloadTree` function attribute returned by "use tree" hooks has been changed to **not** accept a `dataSourceChanged` parameter.
+
+  The parameter was used to notify the tree component that the underlying data source has changed and the tree should be reloaded. For example, something like this was necessary:
+
+  ```tsx
+  const { reloadTree } = useIModelUnifiedSelectionTree({
+    // ...
+  });
+
+  useEffect(() => {
+    if (!imodel.isBriefcaseConnection()) {
+      return;
+    }
+
+    return registerTxnListeners(imodel.txns, () => {
+      reloadTree({ dataSourceChanged: true });
+    });
+  }, [imodel, reloadTree]);
+  ```
+
+  Now, the `HierarchyProvider` notifies the hook about hierarchy changes.
+
+  Note that iModel-based hierarchy providers require an `imodelChanged` event object to be provided and raised when the underlying iModel changes:
+
+  ```tsx
+  const [imodelChanged] = useState(new BeEvent<() => void>());
+  useEffect(() => {
+    if (imodel.isBriefcaseConnection()) {
+      return registerTxnListeners(imodel.txns, () => imodelChanged.raiseEvent());
+    }
+    return undefined;
+  }, [imodel, imodelChanged]);
+
+  const { ... } = useIModelUnifiedSelectionTree({
+    imodelChanged,
+    ...,
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies:
+  - @itwin/presentation-hierarchies@0.7.0
+
+## 0.7.2
+
+### Patch Changes
+
+- [#699](https://github.com/iTwin/presentation/pull/699): Fixed warnings related to passing `ref` to the component that is not wrapped in `forwardRef` function.
+- Updated dependencies:
+  - @itwin/presentation-hierarchies@0.5.1
+  - @itwin/presentation-shared@0.5.0
+  - @itwin/unified-selection@0.5.1
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -6,11 +6,55 @@ The `@itwin/presentation-hierarchies-react` package provides APIs for building a
 
 ## Headless UI
 
-### `useTree`
+### Tree state hooks
 
-This is a React hook that creates state for a tree component.
+The package provides different flavors of the same hook for creating and managing state of a tree component:
 
-It takes 2 required properties:
+| Feature \ Hook                                                                                       | `useTree` | `useIModelTree` | `useUnifiedSelectionTree` | `useIModelUnifiedSelectionTree` |
+| ---------------------------------------------------------------------------------------------------- | --------- | --------------- | ------------------------- | ------------------------------- |
+| Supported data source                                                                                | any       | iModel          | any                       | iModel                          |
+| Integration with [Unified Selection](https://www.itwinjs.org/presentation/unified-selection/) system | ❌        | ❌              | ✔️                        | ✔️                              |
+
+All these hooks return the same state object, which contains properties and functions to manage the tree component:
+
+- `isLoading` is a boolean indicating whether the root tree nodes are being loaded. Set to `true` on initial load and on reload (e.g. when iModel data changes).
+
+- `rootNodes` is an array of root tree nodes and is what the component should render. There are several types of nodes:
+
+  - A `PresentationHierarchyNode` is the primary type of node, created based on the hierarchy definition. The `isPresentationHierarchyNode` type guard utility may be used to check if a node is of this type.
+  - A `PresentationInfoNode` is a non-expandable, non-selectable informational type of node, generally created when for some reason we don't have any real nodes to show. There may be different reasons like filtered-out nodes, too large result set, a network error, etc. The `type` attribute of the node indicates that.
+
+- `expandNode` function to expand or collapse a node.
+
+- `isNodeSelected` and `selectNodes` function to inspect and change tree selection.
+
+- `getHierarchyLevelDetails` function to access details of a specific hierarchy level. The returned object provides access to:
+
+  - hierarchy level size limit,
+  - hierarchy level instance filter,
+  - instance keys of the nodes in the hierarchy level.
+
+- `reloadTree` function to reload part of the tree, optionally keeping its state.
+
+- `setFormatter` function to set active node label formatter.
+
+#### `useTree` props
+
+The hook takes a single required prop:
+
+- `getHierarchyProvider` is a factory function that creates a hierarchy provider, returning the hierarchy the tree component will render. The `@itwin/presentation-hierarchies` package describes the concept of hierarchy provider [in more detail](https://github.com/iTwin/presentation/blob/master/packages/hierarchies/README.md#hierarchy-providers).
+
+#### `useUnifiedSelectionTree` props
+
+In addition to [props required by `useTree`](#usetree-props), the hook additionally requires:
+
+- `sourceName` - a string that distinguishes selection changes being made by different components. The value should be unique for each component.
+
+The hook also relies on unified selection storage being provided to it through a React context. See [Providing unified selection context](#providing-unified-selection-context) example below for more details.
+
+#### `useIModelTree` props
+
+The hook takes 2 required properties:
 
 - `imodelAccess` provides access to iModel's data and metadata, required to build the hierarchy. Generally, `@itwin/presentation-core-interop` and `@itwin/presentation-shared` packages are used to create this object:
 
@@ -43,6 +87,7 @@ It takes 2 required properties:
   function createIModelAccess(imodel: IModelConnection) {
     const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
     return {
+      imodelKey: imodel.key,
       ...schemaProvider,
       // while caching for hierarchy inspector is not mandatory, it's recommended to use it to improve performance
       ...createCachingECClassHierarchyInspector({ schemaProvider, cacheSize: 100 }),
@@ -55,66 +100,25 @@ It takes 2 required properties:
 
   <!-- END EXTRACTION -->
 
-- `getHierarchyDefinition` is a factory function that creates a hierarchy definition, describing the hierarchy the tree component will render. The `@itwin/presentation-hierarchies` package describes the concept of hierarchy definitions [in more detail](https://github.com/iTwin/presentation/blob/master/packages/hierarchies/README.md#hierarchy-definition).
+- `getHierarchyDefinition` is a factory function that creates a hierarchy definition, describing the hierarchy the tree component will render. The `@itwin/presentation-hierarchies` package describes the concept of hierarchy definitions [in more detail](https://github.com/iTwin/presentation/blob/master/packages/hierarchies/learning/imodel/HierarchyDefinition.md).
 
-The resulting state object contains the following properties:
+#### `useIModelUnifiedSelectionTree` props
 
-- `isLoading` is a boolean indicating whether the root tree nodes are being loaded. Set to `true` on initial load and on reload (e.g. when iModel data changes).
+In addition to [props required by `useIModelTree`](#useimodeltree-props), the hook additionally requires:
 
-- `rootNodes` is an array of root tree nodes and is what the component should render. There are several types of nodes:
+- `sourceName` - a string that distinguishes selection changes being made by different components. The value should be unique for each component.
 
-  - A `PresentationHierarchyNode` is the primary type of node, created based on the hierarchy definition. The `isPresentationHierarchyNode` type guard utility may be used to check if a node is of this type.
-  - A `PresentationInfoNode` is a non-expandable, non-selectable informational type of node, generally created when for some reason we don't have any real nodes to show. There may be different reasons like filtered-out nodes, too large result set, a network error, etc. The `type` attribute of the node indicates that.
-
-- `expandNode` function to expand or collapse a node.
-
-- `isNodeSelected` and `selectNodes` function to inspect and change tree selection.
+The hook also relies on unified selection storage being provided to it through a React context. See [Providing unified selection context](#providing-unified-selection-context) example below for more details.
 
-- `getHierarchyLevelDetails` function to access details of a specific hierarchy level. The returned object provides access to:
+#### Providing unified selection context
 
-  - hierarchy level size limit,
-  - hierarchy level instance filter,
-  - instance keys of the nodes in the hierarchy level.
-
-- `reloadTree` function to reload the tree, optionally keeping its state, after an iModel data change.
-
-- `setFormatter` function to set active node label formatter.
-
-### `useSelectionHandler`
-
-This is a React hook that helps implement different selection modes in a tree, whose state is managed through the `useTree` or `useUnifiedSelectionTree` hooks.
-
-It takes 3 required properties:
-
-- `rootNodes` and `selectNodes` are the corresponding properties from the tree state object, created using `useTree` or `useUnifiedSelectionTree` hook.
-
-- `selectionMode` is a string that defines the selection mode. It can be one of the following values:
-  - `none` - no selection is allowed,
-  - `single` - only one node can be selected at a time,
-  - `extended` - multiple nodes can be selected using shift and ctrl keys,
-  - `multiple` - multiple nodes can be selected without using shift or ctrl keys.
-
-The returned object contains 2 functions, that should be called by the node renderer: `onNodeClick` and `onNodeKeyDown`.
-
-Our [tree renderer implementation](#treerenderer) calls this hook and passes the callbacks to the [node renderer](#treenoderenderer), so there's no need to use it unless implementing a custom tree renderer.
-
-### `useUnifiedSelectionTree` & `UnifiedSelectionProvider`
-
-The package delivers a variation of [`useTree`](#usetree), that automatically hooks tree selection into the [Unified Selection](https://www.itwinjs.org/learning/unified-selection/) system. It takes the same properties as [`useTree`](#usetree), plus a couple of additional ones:
-
-- `imodelKey` is a string that uniquely identifies the iModel the tree is associated with. It's used to distinguish selection changes between different iModels. Generally, the value is obtained using `IModelConnection.key` getter.
-
-- `sourceName` is a string that distinguishes selection changes being made by different components. It's used to avoid conflicts between different components that use the same iModel and the same selection storage. The value should be unique for each component.
-
-The returned result is identical to the one from [`useTree`](#usetree).
-
-The hook also relies on unified selection storage being provided to it through a React context. For that, the package delivers the `UnifiedSelectionProvider` component, that should wrap the tree component, using the `useUnifiedSelectionTree` hook:
+The flavor of tree state hooks, that support unified selection integration, relies on unified selection storage being provided to it through a React context. For that, the package delivers the `UnifiedSelectionProvider` component, that should wrap the tree component, using the `useUnifiedSelectionTree` hook:
 
 <!-- [[include: [Presentation.HierarchiesReact.SelectionStorage.Imports, Presentation.HierarchiesReact.SelectionStorage], tsx]] -->
 <!-- BEGIN EXTRACTION -->
 
 ```tsx
-import { TreeRenderer, UnifiedSelectionProvider, useUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
+import { TreeRenderer, UnifiedSelectionProvider, useIModelUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
 import { createStorage } from "@itwin/unified-selection";
 import { useEffect, useState } from "react";
 
@@ -134,7 +138,7 @@ function MyTreeComponent({ imodel }: { imodel: IModelConnection }) {
 
   return (
     <UnifiedSelectionProvider storage={selectionStorage}>
-      <MyTreeComponentInternal imodelKey={imodel.key} imodelAccess={imodelAccess} />
+      <MyTreeComponentInternal imodelAccess={imodelAccess} />
     </UnifiedSelectionProvider>
   );
 }
@@ -142,18 +146,16 @@ function MyTreeComponent({ imodel }: { imodel: IModelConnection }) {
 
 <!-- END EXTRACTION -->
 
-After providing the unified selection storage through the context, the `useUnifiedSelectionTree` hook can be used inside the component as follows:
+After providing the unified selection storage through the context, the `useUnifiedSelectionTree` and `useIModelUnifiedSelectionTree` hooks can be used inside the component as follows:
 
 <!-- [[include: Presentation.HierarchiesReact.UseUnifiedSelectionTree, tsx]] -->
 <!-- BEGIN EXTRACTION -->
 
 ```tsx
-function MyTreeComponentInternal({ imodelAccess, imodelKey }: { imodelAccess: IModelAccess; imodelKey: string }) {
-  const { rootNodes, ...state } = useUnifiedSelectionTree({
+function MyTreeComponentInternal({ imodelAccess }: { imodelAccess: IModelAccess }) {
+  const { rootNodes, ...state } = useIModelUnifiedSelectionTree({
     // the source name is used to distinguish selection changes being made by different components
     sourceName: "MyTreeComponent",
-    // the iModel key is required for unified selection system to distinguish selection changes between different iModels
-    imodelKey,
     // iModel access is used to build the hierarchy
     imodelAccess,
     // the hierarchy definition describes the hierarchy using ECSQL queries
@@ -168,13 +170,31 @@ function MyTreeComponentInternal({ imodelAccess, imodelKey }: { imodelAccess: IM
 
 <!-- END EXTRACTION -->
 
+### `useSelectionHandler` hook
+
+This is a React hook that helps implement different selection modes in a tree, whose state is managed through one of the [tree state hooks](#tree-state-hooks).
+
+It takes 3 required properties:
+
+- `rootNodes` and `selectNodes` are the corresponding properties from the tree state object, created using one of the [tree state hooks](#tree-state-hooks).
+
+- `selectionMode` is a string that defines the selection mode. It can be one of the following values:
+  - `none` - no selection is allowed,
+  - `single` - only one node can be selected at a time,
+  - `extended` - multiple nodes can be selected using shift and ctrl keys,
+  - `multiple` - multiple nodes can be selected without using shift or ctrl keys.
+
+The returned object contains 2 functions, that should be called by the node renderer: `onNodeClick` and `onNodeKeyDown`.
+
+Our [tree renderer implementation](#treerenderer) calls this hook and passes the callbacks to the [node renderer](#treenoderenderer), so there's no need to use it unless implementing a custom tree renderer.
+
 ## iTwinUI components
 
 While the package provides a headless UI, it also delivers a set of [iTwinUI](https://itwinui.bentley.com/)-based components for rendering the tree, which should cover majority of use cases. Consumers using the below components are required to provide a compatible `@itwin/itwinui-react` package, which is an optional peer dependency to this package.
 
 ### `TreeRenderer`
 
-The component is based on [iTwinUI Tree component](https://itwinui.bentley.com/docs/tree) and uses our [`TreeNodeRenderer`](#treenoderenderer) to render the nodes. In addition, it makes use of the [`useSelectionHandler` hook](#useselectionhandler) to add selection modes' support.
+The component is based on [iTwinUI Tree component](https://itwinui.bentley.com/docs/tree) and uses our [`TreeNodeRenderer`](#treenoderenderer) to render the nodes. In addition, it makes use of the [`useSelectionHandler` hook](#useselectionhandler-hook) to add selection modes' support.
 
 The iTwinUI Tree component requires a `getNode` function that maps nodes to `NodeData<TNode>` objects. Our `TreeRenderer` uses `createRenderedTreeNodeData` function for this purpose, and it's available for consumers as well, in case a custom iTwinUI Tree component implementation is being written.
 
@@ -183,7 +203,7 @@ The iTwinUI Tree component requires a `getNode` function that maps nodes to `Nod
 The component is based on `TreeNode` component from iTwinUI library and supports the following features:
 
 - Rendering informational type of nodes (e.g. "No filter matches", "Too many nodes in a hierarchy level", etc.).
-- Reporting click and key down events for use with [`useSelectionHandler` hook](#useselectionhandler).
+- Reporting click and key down events for use with [`useSelectionHandler` hook](#useselectionhandler-hook).
 - Icons, selection, expand / collapse.
 - Action buttons to clear / set hierarchy level instance filter.
 
@@ -199,7 +219,7 @@ import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
 import { createECSchemaProvider, createECSqlQueryExecutor } from "@itwin/presentation-core-interop";
 import { createLimitingECSqlQueryExecutor, createNodesQueryClauseFactory, HierarchyDefinition } from "@itwin/presentation-hierarchies";
 
-import { TreeRenderer, UnifiedSelectionProvider, useUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
+import { TreeRenderer, UnifiedSelectionProvider, useIModelUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
 import { createStorage } from "@itwin/unified-selection";
 import { useEffect, useState } from "react";
 
@@ -224,6 +244,7 @@ function getIModelSchemaContext(imodel: IModelConnection) {
 function createIModelAccess(imodel: IModelConnection) {
   const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
   return {
+    imodelKey: imodel.key,
     ...schemaProvider,
     // while caching for hierarchy inspector is not mandatory, it's recommended to use it to improve performance
     ...createCachingECClassHierarchyInspector({ schemaProvider, cacheSize: 100 }),
@@ -249,19 +270,19 @@ function MyTreeComponent({ imodel }: { imodel: IModelConnection }) {
 
   return (
     <UnifiedSelectionProvider storage={selectionStorage}>
-      <MyTreeComponentInternal imodelKey={imodel.key} imodelAccess={imodelAccess} />
+      <MyTreeComponentInternal imodelAccess={imodelAccess} />
     </UnifiedSelectionProvider>
   );
 }
 
-type IModelAccess = Parameters<typeof useUnifiedSelectionTree>[0]["imodelAccess"];
+type IModelAccess = Parameters<typeof useIModelUnifiedSelectionTree>[0]["imodelAccess"];
 
 // The hierarchy definition describes the hierarchy using ECSQL queries; here it just returns all `BisCore.PhysicalModel` instances
 function getHierarchyDefinition({ imodelAccess }: { imodelAccess: IModelAccess }): HierarchyDefinition {
-  // Create a factory for building nodes SELECT query clauses in a format understood by the provider
-  const nodesQueryFactory = createNodesQueryClauseFactory({ imodelAccess });
   // 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 });
   return {
     defineHierarchyLevel: async () => [
       {
@@ -286,12 +307,10 @@ function getHierarchyDefinition({ imodelAccess }: { imodelAccess: IModelAccess }
 }
 
 /** Internal component that creates and renders tree state. */
-function MyTreeComponentInternal({ imodelAccess, imodelKey }: { imodelAccess: IModelAccess; imodelKey: string }) {
-  const { rootNodes, setFormatter, isLoading, ...state } = useUnifiedSelectionTree({
+function MyTreeComponentInternal({ imodelAccess }: { imodelAccess: IModelAccess }) {
+  const { rootNodes, setFormatter, isLoading, ...state } = useIModelUnifiedSelectionTree({
     // the source name is used to distinguish selection changes being made by different components
     sourceName: "MyTreeComponent",
-    // the iModel key is required for unified selection system to distinguish selection changes between different iModels
-    imodelKey,
     // iModel access is used to build the hierarchy
     imodelAccess,
     // supply the hierarchy definition
@@ -308,7 +327,7 @@ function MyTreeComponentInternal({ imodelAccess, imodelKey }: { imodelAccess: IM
 
 ## Localization
 
-Localization can be enabled for `TreeRenderer` component and `useTree` and `useUnifiedSelectionTree` hooks by providing an object with localized strings that will be used instead of the default English ones.
+Localization can be enabled for `TreeRenderer` component and [tree state hooks](#tree-state-hooks) by providing an object with localized strings that will be used instead of the default English ones.
 
 Example:
 
@@ -316,12 +335,12 @@ Example:
 <!-- BEGIN EXTRACTION -->
 
 ```tsx
-import { useUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
+import { useIModelUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
 
-type IModelAccess = Parameters<typeof useUnifiedSelectionTree>[0]["imodelAccess"];
+type IModelAccess = Parameters<typeof useIModelUnifiedSelectionTree>[0]["imodelAccess"];
 
 const localizedStrings = {
-  // strings for the `useUnifiedSelectionTree` hook
+  // strings for the `useIModelUnifiedSelectionTree` hook
   unspecified: "Unspecified",
   other: "Other",
 
@@ -336,10 +355,9 @@ const localizedStrings = {
   increaseHierarchyLimitWithFiltering: "Or, <link>increase the hierarchy level size limit to {{limit}}.</link>",
 };
 
-function MyTreeComponent({ imodelAccess, imodelKey }: { imodelAccess: IModelAccess; imodelKey: string }) {
-  const { rootNodes, ...state } = useUnifiedSelectionTree({
+function MyTreeComponent({ imodelAccess }: { imodelAccess: IModelAccess }) {
+  const { rootNodes, expandNode } = useIModelUnifiedSelectionTree({
     sourceName: "MyTreeComponent",
-    imodelKey,
     imodelAccess,
     localizedStrings,
     getHierarchyDefinition,
@@ -347,7 +365,7 @@ function MyTreeComponent({ imodelAccess, imodelKey }: { imodelAccess: IModelAcce
   if (!rootNodes) {
     return localizedStrings.loading;
   }
-  return <TreeRenderer {...state} rootNodes={rootNodes} localizedStrings={localizedStrings} onFilterClick={() => {}} />;
+  return <TreeRenderer rootNodes={rootNodes} expandNode={expandNode} localizedStrings={localizedStrings} onFilterClick={() => {}} />;
 }
 ```
 

package/lib/cjs/presentation-hierarchies-react/UseIModelTree.d.ts

@@ -0,0 +1,53 @@
+import { createIModelHierarchyProvider, HierarchyDefinition, HierarchyFilteringPath } from "@itwin/presentation-hierarchies";
+import { UseUnifiedTreeSelectionProps } from "./internal/UseUnifiedSelection";
+import { UseTreeProps, UseTreeResult } from "./UseTree";
+/** @beta */
+type IModelHierarchyProviderProps = Parameters<typeof createIModelHierarchyProvider>[0];
+/** @beta */
+type IModelAccess = IModelHierarchyProviderProps["imodelAccess"];
+/**
+ * Props for `useIModelTree` and `useIModelUnifiedSelectionTree` hooks.
+ * @beta
+ */
+type UseIModelTreeProps = Omit<UseTreeProps, "getHierarchyProvider" | "getFilteredPaths"> & Pick<IModelHierarchyProviderProps, "localizedStrings" | "imodelAccess" | "imodelChanged"> & {
+    /** Provides the hierarchy definition for the tree. */
+    getHierarchyDefinition: (props: {
+        imodelAccess: IModelAccess;
+    }) => HierarchyDefinition;
+    /** Provides paths to filtered nodes. */
+    getFilteredPaths?: (props: {
+        /** Object that provides access to the iModel schema and can run queries against the iModel. */
+        imodelAccess: IModelAccess;
+    }) => Promise<HierarchyFilteringPath[] | undefined>;
+};
+/**
+ * A React hook that creates state for a tree component whose displayed hierarchy is based on
+ * iModel data.
+ *
+ * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a
+ * component-agnostic result which may be used to render the hierarchy using any UI framework.
+ *
+ * See `README.md` for an example
+ *
+ * @see `useTree`
+ * @see `useIModelUnifiedSelectionTree`
+ * @beta
+ */
+export declare function useIModelTree(props: UseIModelTreeProps): UseTreeResult;
+/**
+ * A React hook that creates state for a tree component whose displayed hierarchy is based on
+ * iModel data and that is integrated with unified selection through context provided by `UnifiedSelectionProvider`.
+ *
+ * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a
+ * component-agnostic result which may be used to render the hierarchy using any UI framework.
+ *
+ * See `README.md` for an example
+ *
+ * @see `useIModelTree`
+ * @see `useUnifiedSelectionTree`
+ * @see `UnifiedSelectionProvider`
+ * @beta
+ */
+export declare function useIModelUnifiedSelectionTree(props: UseIModelTreeProps & UseUnifiedTreeSelectionProps): UseTreeResult;
+export {};
+//# sourceMappingURL=UseIModelTree.d.ts.map

package/lib/cjs/presentation-hierarchies-react/UseIModelTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseIModelTree.d.ts","sourceRoot":"","sources":["../../../src/presentation-hierarchies-react/UseIModelTree.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC7H,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAW,YAAY,EAAE,aAAa,EAA2B,MAAM,WAAW,CAAC;AAE1F,YAAY;AACZ,KAAK,4BAA4B,GAAG,UAAU,CAAC,OAAO,6BAA6B,CAAC,CAAC,CAAC,CAAC,CAAC;AAExF,YAAY;AACZ,KAAK,YAAY,GAAG,4BAA4B,CAAC,cAAc,CAAC,CAAC;AAEjE;;;GAGG;AACH,KAAK,kBAAkB,GAAG,IAAI,CAAC,YAAY,EAAE,sBAAsB,GAAG,kBAAkB,CAAC,GACvF,IAAI,CAAC,4BAA4B,EAAE,kBAAkB,GAAG,cAAc,GAAG,eAAe,CAAC,GAAG;IAC1F,sDAAsD;IACtD,sBAAsB,EAAE,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,YAAY,CAAA;KAAE,KAAK,mBAAmB,CAAC;IAEvF,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE;QACzB,+FAA+F;QAC/F,YAAY,EAAE,YAAY,CAAC;KAC5B,KAAK,OAAO,CAAC,sBAAsB,EAAE,GAAG,SAAS,CAAC,CAAC;CACrD,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAMtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,kBAAkB,GAAG,4BAA4B,GAAG,aAAa,CAMrH"}

package/lib/cjs/presentation-hierarchies-react/UseIModelTree.js

@@ -0,0 +1,65 @@
+"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.useIModelTree = useIModelTree;
+exports.useIModelUnifiedSelectionTree = useIModelUnifiedSelectionTree;
+const react_1 = require("react");
+const presentation_hierarchies_1 = require("@itwin/presentation-hierarchies");
+const UseTree_1 = require("./UseTree");
+/**
+ * A React hook that creates state for a tree component whose displayed hierarchy is based on
+ * iModel data.
+ *
+ * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a
+ * component-agnostic result which may be used to render the hierarchy using any UI framework.
+ *
+ * See `README.md` for an example
+ *
+ * @see `useTree`
+ * @see `useIModelUnifiedSelectionTree`
+ * @beta
+ */
+function useIModelTree(props) {
+    const { imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings, ...rest } = props;
+    return (0, UseTree_1.useTree)({
+        ...rest,
+        ...useIModelTreeProps({ imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings }),
+    });
+}
+/**
+ * A React hook that creates state for a tree component whose displayed hierarchy is based on
+ * iModel data and that is integrated with unified selection through context provided by `UnifiedSelectionProvider`.
+ *
+ * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a
+ * component-agnostic result which may be used to render the hierarchy using any UI framework.
+ *
+ * See `README.md` for an example
+ *
+ * @see `useIModelTree`
+ * @see `useUnifiedSelectionTree`
+ * @see `UnifiedSelectionProvider`
+ * @beta
+ */
+function useIModelUnifiedSelectionTree(props) {
+    const { imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings, ...rest } = props;
+    return (0, UseTree_1.useUnifiedSelectionTree)({
+        ...rest,
+        ...useIModelTreeProps({ imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings }),
+    });
+}
+function useIModelTreeProps(props) {
+    const { imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings } = props;
+    return {
+        getHierarchyProvider: (0, react_1.useCallback)(() => (0, presentation_hierarchies_1.createIModelHierarchyProvider)({
+            imodelAccess,
+            imodelChanged,
+            hierarchyDefinition: getHierarchyDefinition({ imodelAccess }),
+            localizedStrings,
+        }), [imodelAccess, imodelChanged, getHierarchyDefinition, localizedStrings]),
+        getFilteredPaths: (0, react_1.useCallback)(async () => getFilteredPaths?.({ imodelAccess }), [imodelAccess, getFilteredPaths]),
+    };
+}
+//# sourceMappingURL=UseIModelTree.js.map

package/lib/cjs/presentation-hierarchies-react/UseIModelTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseIModelTree.js","sourceRoot":"","sources":["../../../src/presentation-hierarchies-react/UseIModelTree.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;AA0ChG,sCAMC;AAgBD,sEAMC;AApED,iCAAoC;AACpC,8EAA6H;AAE7H,uCAA0F;AAwB1F;;;;;;;;;;;;GAYG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACrD,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IACnH,OAAO,IAAA,iBAAO,EAAC;QACb,GAAG,IAAI;QACP,GAAG,kBAAkB,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;KACnH,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,6BAA6B,CAAC,KAAwD;IACpG,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IACnH,OAAO,IAAA,iCAAuB,EAAC;QAC7B,GAAG,IAAI;QACP,GAAG,kBAAkB,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;KACnH,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CACzB,KAAsI;IAEtI,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IAC1G,OAAO;QACL,oBAAoB,EAAE,IAAA,mBAAW,EAC/B,GAAG,EAAE,CACH,IAAA,wDAA6B,EAAC;YAC5B,YAAY;YACZ,aAAa;YACb,mBAAmB,EAAE,sBAAsB,CAAC,EAAE,YAAY,EAAE,CAAC;YAC7D,gBAAgB;SACjB,CAAC,EACJ,CAAC,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,CAAC,CACxE;QACD,gBAAgB,EAAE,IAAA,mBAAW,EAAC,KAAK,IAAI,EAAE,CAAC,gBAAgB,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;KAClH,CAAC;AACJ,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 { useCallback } from \"react\";\nimport { createIModelHierarchyProvider, HierarchyDefinition, HierarchyFilteringPath } from \"@itwin/presentation-hierarchies\";\nimport { UseUnifiedTreeSelectionProps } from \"./internal/UseUnifiedSelection\";\nimport { useTree, UseTreeProps, UseTreeResult, useUnifiedSelectionTree } from \"./UseTree\";\n\n/** @beta */\ntype IModelHierarchyProviderProps = Parameters<typeof createIModelHierarchyProvider>[0];\n\n/** @beta */\ntype IModelAccess = IModelHierarchyProviderProps[\"imodelAccess\"];\n\n/**\n * Props for `useIModelTree` and `useIModelUnifiedSelectionTree` hooks.\n * @beta\n */\ntype UseIModelTreeProps = Omit<UseTreeProps, \"getHierarchyProvider\" | \"getFilteredPaths\"> &\n  Pick<IModelHierarchyProviderProps, \"localizedStrings\" | \"imodelAccess\" | \"imodelChanged\"> & {\n    /** Provides the hierarchy definition for the tree. */\n    getHierarchyDefinition: (props: { imodelAccess: IModelAccess }) => HierarchyDefinition;\n\n    /** Provides paths to filtered nodes. */\n    getFilteredPaths?: (props: {\n      /** Object that provides access to the iModel schema and can run queries against the iModel. */\n      imodelAccess: IModelAccess;\n    }) => Promise<HierarchyFilteringPath[] | undefined>;\n  };\n\n/**\n * A React hook that creates state for a tree component whose displayed hierarchy is based on\n * iModel data.\n *\n * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a\n * component-agnostic result which may be used to render the hierarchy using any UI framework.\n *\n * See `README.md` for an example\n *\n * @see `useTree`\n * @see `useIModelUnifiedSelectionTree`\n * @beta\n */\nexport function useIModelTree(props: UseIModelTreeProps): UseTreeResult {\n  const { imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings, ...rest } = props;\n  return useTree({\n    ...rest,\n    ...useIModelTreeProps({ imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings }),\n  });\n}\n\n/**\n * A React hook that creates state for a tree component whose displayed hierarchy is based on\n * iModel data and that is integrated with unified selection through context provided by `UnifiedSelectionProvider`.\n *\n * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a\n * component-agnostic result which may be used to render the hierarchy using any UI framework.\n *\n * See `README.md` for an example\n *\n * @see `useIModelTree`\n * @see `useUnifiedSelectionTree`\n * @see `UnifiedSelectionProvider`\n * @beta\n */\nexport function useIModelUnifiedSelectionTree(props: UseIModelTreeProps & UseUnifiedTreeSelectionProps): UseTreeResult {\n  const { imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings, ...rest } = props;\n  return useUnifiedSelectionTree({\n    ...rest,\n    ...useIModelTreeProps({ imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings }),\n  });\n}\n\nfunction useIModelTreeProps(\n  props: Pick<UseIModelTreeProps, \"imodelAccess\" | \"imodelChanged\" | \"getHierarchyDefinition\" | \"getFilteredPaths\" | \"localizedStrings\">,\n): Pick<UseTreeProps, \"getHierarchyProvider\" | \"getFilteredPaths\"> {\n  const { imodelAccess, imodelChanged, getHierarchyDefinition, getFilteredPaths, localizedStrings } = props;\n  return {\n    getHierarchyProvider: useCallback(\n      () =>\n        createIModelHierarchyProvider({\n          imodelAccess,\n          imodelChanged,\n          hierarchyDefinition: getHierarchyDefinition({ imodelAccess }),\n          localizedStrings,\n        }),\n      [imodelAccess, imodelChanged, getHierarchyDefinition, localizedStrings],\n    ),\n    getFilteredPaths: useCallback(async () => getFilteredPaths?.({ imodelAccess }), [imodelAccess, getFilteredPaths]),\n  };\n}\n"]}

package/lib/cjs/presentation-hierarchies-react/UseTree.d.ts

@@ -1,5 +1,5 @@
-import { createHierarchyProvider, GenericInstanceFilter, HierarchyDefinition, HierarchyNode, LimitingECSqlQueryExecutor } from "@itwin/presentation-hierarchies";
-import { ECClassHierarchyInspector, ECSchemaProvider, InstanceKey, IPrimitiveValueFormatter } from "@itwin/presentation-shared";
+import { GenericInstanceFilter, HierarchyFilteringPath, HierarchyNode, HierarchyProvider } from "@itwin/presentation-hierarchies";
+import { InstanceKey, IPrimitiveValueFormatter } from "@itwin/presentation-shared";
 import { UseUnifiedTreeSelectionProps } from "./internal/UseUnifiedSelection";
 import { PresentationTreeNode } from "./TreeNode";
 import { SelectionChangeType } from "./UseSelectionHandler";
@@ -33,6 +33,7 @@ export interface HierarchyLevelDetails {
  * See `README.md` for an example
  *
  * @see `useUnifiedSelectionTree`
+ * @see `useIModelTree`
  * @beta
  */
 export declare function useTree(props: UseTreeProps): UseTreeResult;
@@ -46,31 +47,17 @@ export declare function useTree(props: UseTreeProps): UseTreeResult;
  * See `README.md` for an example
  *
  * @see `useTree`
+ * @see `useIModelUnifiedSelectionTree`
  * @see `UnifiedSelectionProvider`
  * @beta
  */
-export declare function useUnifiedSelectionTree({ imodelKey, sourceName, ...props }: UseTreeProps & UseUnifiedTreeSelectionProps): UseTreeResult;
+export declare function useUnifiedSelectionTree({ sourceName, ...props }: UseTreeProps & UseUnifiedTreeSelectionProps): UseTreeResult;
 /** @beta */
-type IModelAccess = ECSchemaProvider & LimitingECSqlQueryExecutor & ECClassHierarchyInspector;
-/** @beta */
-interface GetFilteredPathsProps {
-    /** Object that provides access to the iModel schema and can run queries against the iModel. */
-    imodelAccess: IModelAccess;
-}
-/** @beta */
-type HierarchyProviderProps = Parameters<typeof createHierarchyProvider>[0];
-/** @beta */
-type HierarchyFilteringPaths = NonNullable<NonNullable<HierarchyProviderProps["filtering"]>["paths"]>;
-/** @beta */
-interface UseTreeProps extends Pick<HierarchyProviderProps, "localizedStrings"> {
-    /** Object that provides access to the iModel schema and can run queries against the iModel. */
-    imodelAccess: ECSchemaProvider & LimitingECSqlQueryExecutor & ECClassHierarchyInspector;
-    /** Provides the hierarchy definition for the tree. */
-    getHierarchyDefinition: (props: {
-        imodelAccess: IModelAccess;
-    }) => HierarchyDefinition;
+export interface UseTreeProps {
+    /** Provides the hierarchy provider for the tree. */
+    getHierarchyProvider: () => HierarchyProvider;
     /** Provides paths to filtered nodes. */
-    getFilteredPaths?: (props: GetFilteredPathsProps) => Promise<HierarchyFilteringPaths | undefined>;
+    getFilteredPaths?: () => Promise<HierarchyFilteringPath[] | undefined>;
     /**
      * Callback that is called just after a certain action is finished.
      * Can be used for performance tracking.
@@ -88,8 +75,13 @@ interface UseTreeProps extends Pick<HierarchyProviderProps, "localizedStrings">
         type: "timeout" | "unknown";
     }) => void;
 }
-/** @beta */
-interface ReloadTreeCommonOptions {
+/**
+ * Options for doing either full or a sub tree reload.
+ * @beta
+ */
+interface ReloadTreeOptions {
+    /** Specifies parent node under which sub tree should be reloaded. */
+    parentNodeId: string | undefined;
     /**
      * Specifies how current tree state should be handled:
      * - `keep` - try to keep current tree state (expanded/collapsed nodes, instance filters, etc.).
@@ -100,29 +92,8 @@ interface ReloadTreeCommonOptions {
      */
     state?: "keep" | "discard" | "reset";
 }
-/**
- * Options for full tree reload.
- * @beta
- */
-type FullTreeReloadOptions = {
-    /** Specifies that data source changed and caches should be cleared before reloading tree. */
-    dataSourceChanged?: true;
-} & ReloadTreeCommonOptions;
-/**
- * Options for subtree reload.
- * @beta
- */
-type SubtreeReloadOptions = {
-    /** Specifies parent node under which sub tree should be reloaded. */
-    parentNodeId: string;
-} & ReloadTreeCommonOptions;
-/**
- * Options for doing either full or a sub tree reload.
- * @beta
- */
-type ReloadTreeOptions = FullTreeReloadOptions | SubtreeReloadOptions;
 /** @beta */
-interface UseTreeResult {
+export interface UseTreeResult {
     /**
      * Array containing root tree nodes. It is `undefined` on initial render until any nodes are loaded.
      */