@itwin/tree-widget-react 2.3.2 → 3.0.0-dev.1

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # Change Log - @itwin/tree-widget-react
 
-This log was last generated on Mon, 10 Jun 2024 12:47:40 GMT and should not be manually modified.
+This log was last generated on Mon, 10 Jun 2024 12:47:48 GMT and should not be manually modified.
 
 <!-- Start content -->
 
 ## 2.3.2
 
-Mon, 10 Jun 2024 12:47:40 GMT
+Mon, 10 Jun 2024 12:47:48 GMT
 
 ### Patches
 

package/README.md

@@ -6,6 +6,31 @@ The `@itwin/tree-widget-react` package provides React components to build a widg
 
 ![Widget example](./media/widget.png)
 
+## 3.0 highlights
+
+The new `3.0` version of the package contains a few notable changes, compared to the previous `2.x` generation.
+
+- To allow easier customization of widget placement, the package now delivers a `createTreeWidget()` function that creates a tree widget definition, instead of a full `UiItemsProvider` implementation. See [Usage](#usage) section for details on how to use the new function.
+
+- The underlying engine for building hierarchies has been changed from `@itwin/presentation-components` to `@itwin/presentation-hierarchies-react`. This is a significant change as the new library runs plain ECSQL queries and handles hierarchy creation on the frontend, as opposed to the previous version that relied on the backend to provide hierarchy data. This change allows this package to use more optimal queries and to be more flexible in terms of hierarchy creation.
+
+  This change adds a requirement for all tree components in this package to access iModels' metadata, which is achieved through a required `getSchemaContext` prop. See [Creating schema context](#creating-schema-context) section for an example implementation of this function.
+
+  In addition, the new tree components don't rely on the global selection manager provided by `@itwin/presentation-frontend` package. Instead, they require a unified selection storage object created using `createStorage()` function from `@itwin/unified-selection` package. See sections of individual tree components for how to supply it to them, and [Creating unified selection storage](#creating-unified-selection-storage) section for an example for how to create the storage.
+
+- The tree components delivered with the package have been updated to use the [`Tree` component from `@itwin/itwinui-react` package](https://itwinui.bentley.com/docs/tree) instead of [`ControlledTree` from `@itwin/components-react`](https://www.itwinjs.org/reference/components-react/tree/controlledtree/). The new component is a little less dense, provides better accessibility and customization options.
+
+  | 2.x                                             | 3.0                                             |
+  | ----------------------------------------------- | ----------------------------------------------- |
+  | ![Tree widget 2.x](./media/tree-widget-2.x.png) | ![Tree widget 3.0](./media/tree-widget-3.0.png) |
+
+- The tree components now have hierarchy level size limiting and filtering features always turned on. The features were already available in `2.x` versions, but were not enabled by default. See [Hierarchy level size limiting](#hierarchy-level-size-limiting) and [Hierarchy level filtering](#hierarchy-level-filtering) sections for more details.
+
+- Models tree:
+  - The label filtering feature has been expanded to filter not only up to Models, but the whole hierarchy. This allows filtering the hierarchy to additionally find Category or Element nodes.
+  - [Focus mode](#focus-mode) feature has been added to allow automatic hierarchy filtering as the application selection changes.
+  - Display states' control has been modified to be hierarchy based. This means that changing display state of something deep in the hierarchy affects checkbox state of all its ancestors. And vice versa - changing display state of an ancestor affects all its descendants.
+
 ## Usage
 
 Typically, the package is used with an [AppUI](https://github.com/iTwin/appui/tree/master/ui/appui-react) based application, but the building blocks may as well be used with any other iTwin.js React app.
@@ -15,66 +40,56 @@ In any case, **before** using any APIs or components delivered with the package,
 ```ts
 import { IModelApp } from "@itwin/core-frontend";
 import { TreeWidget } from "@itwin/tree-widget-react";
-...
-await TreeWidget.initialize(IModelApp.localization);
-```
-
-In [AppUI](https://github.com/iTwin/appui/tree/master/ui/appui-react) based applications widgets are typically provided using `UiItemsProvider` implementations. The `@itwin/tree-widget-react` package delivers `TreeWidgetUiItemsProvider` that can be used to add the tree widget to UI:
 
-```ts
-import { UiItemsManager } from "@itwin/appui-react";
-import { TreeWidgetUiItemsProvider } from "@itwin/tree-widget-react";
-...
-UiItemsManager.register(
-  new TreeWidgetUiItemsProvider()
-);
+await TreeWidget.initialize(IModelApp.localization);
 ```
 
-The above example uses default widget parameters and results in a component similar to the one visible at the top of this README. Customization is also possible:
+In [AppUI](https://github.com/iTwin/appui/tree/master/ui/appui-react) based applications widgets are typically provided using `UiItemsProvider` implementations. The `@itwin/tree-widget-react` package delivers `createTreeWidget` function that can be used to add the tree widget to UI through a `UiItemsProvider`:
 
 ```ts
 import { UiItemsManager } from "@itwin/appui-react";
-import { TreeWidgetUiItemsProvider, ModelsTreeComponent } from "@itwin/tree-widget-react";
-...
-UiItemsManager.register(
-  new TreeWidgetUiItemsProvider({
-    // defaults to `StagePanelLocation.Right`
-    defaultPanelLocation: StagePanelLocation.Left,
-    // defaults to `StagePanelSection.Start`
-    defaultPanelSection: StagePanelSection.End,
-    // defaults to whatever the default `Widget.priority` in AppUI is
-    defaultTreeWidgetPriority: 1000,
-    // defaults to `ModelsTreeComponent` and `CategoriesTreeComponent`
-    trees: [{
-        id: ModelsTreeComponent.id,
-        getLabel: ModelsTreeComponent.getLabel,
-        render: () => <ModelsTreeComponent />,
-    }, {
-        id: "my-tree-id",
-        getLabel: "My Custom Tree",
-        render: () => <>This is my custom tree.</>,
-    }];
-  })
-);
+import { createTreeWidget, ModelsTreeComponent } from "@itwin/tree-widget-react";
+
+UiItemsManager.register({
+  id: "tree-widget-provider",
+  getWidgets: () => [
+    createTreeWidget({
+      trees: [
+        // add the Models tree component delivered with the package
+        {
+          id: ModelsTreeComponent.id,
+          getLabel: () => ModelsTreeComponent.getLabel(),
+          render: (props) => (
+            <ModelsTreeComponent
+              // see "Models tree" section for details regarding `getSchemaContext` and `selectionStorage` props
+              getSchemaContext={getSchemaContext}
+              selectionStorage={unifiedSelectionStorage}
+              selectionMode={"extended"}
+            />
+          ),
+        },
+        // add a custom component
+        {
+          id: "my-tree-id",
+          startIcon: <MyTreeIcon />,
+          getLabel: () => "My Custom Tree",
+          render: () => <>This is my custom tree.</>,
+        },
+      ],
+    }),
+  ],
+});
 ```
 
-As seen in the above code snippet, `TreeWidgetUiItemsProvider` takes a list of trees that are displayed in the widget. This package delivers a number of tree components for everyone's use (see below), but providing custom trees is also an option.
+As seen in the above code snippet, `createTreeWidget` takes a list of trees that are displayed in the widget. This package delivers a number of tree components for everyone's use (see below), but providing custom trees is also an option.
 
 ## Components
 
-While we expect this package to be mostly used with [AppUI](https://github.com/iTwin/appui/tree/master/ui/appui-react) and widget created through `TreeWidgetUiItemsProvider`, the package delivers components used within the widget to meet other use cases:
+While we expect this package to be mostly used with [AppUI](https://github.com/iTwin/appui/tree/master/ui/appui-react) and widget created through `createTreeWidget`, the package delivers components used within the widget to meet other use cases.
 
-- `SelectableTree` renders a tree selector and selected tree (based on the `trees` prop).
+### Selectable tree
 
-- Visibility tree components help you build trees that look and feel like [Models](#models-tree) and [Categories](#categories-tree) trees, letting you control display of elements in the hierarchy.
-
-  - `createVisibilityTreeRenderer` returns a tree renderer that renders nodes with "eye" checkboxes. Its building blocks:
-    - `createVisibilityTreeNodeRenderer`
-    - `VisibilityTreeNodeCheckbox`
-  - `useVisibilityTreeState` is used to create and manage tree state.
-  - `VisibilityTreeNoFilteredData` is used to render a "no results" when filtering.
-  - `VisibilityTreeEventHandler` is an extension of [UnifiedSelectionTreeEventHandler](https://www.itwinjs.org/reference/presentation-components/tree/unifiedselectiontreeeventhandler/), that additionally handles checkbox events and calls provided `IVisibilityHandler` to get/set display of the elements in the hierarchy.
-  - `useTreeTransientState` is used to persist tree scroll position when tree is used in [AppUI](https://github.com/iTwin/appui/tree/master/ui/appui-react) widget.
+`SelectableTree` renders a tree selector and selected tree, based on the `trees` prop. Each tree definition contains a label, an optional icon and a render function that renders the component.
 
 ### Models tree
 
@@ -85,20 +100,37 @@ The component renders a tree that tries to replicate how a typical "Models" tree
 Typical usage:
 
 ```tsx
-import { ModelsTreeComponent, ClassGroupingOption } from "@itwin/tree-widget-react";
-import { SelectionMode } from "@itwin/components-react";
-...
+import { IModelConnection } from "@itwin/core-frontend";
+import { SchemaContext } from "@itwin/ecschema-metadata";
+import { SelectionStorage } from "@itwin/unified-selection";
+import { ModelsTreeComponent } from "@itwin/tree-widget-react";
+
+// The Models tree requires a unified selection storage to support selection synchronization with the
+// application. The storage should be created once per application and shared across multiple selection-enabled
+// components.
+function getUnifiedSelectionStorage(): SelectionStorage {
+  // see "Creating unified selection storage" section for example implementation
+}
+
+// Schema context is used by Models tree to access iModels metadata. Similar to selection storage, it should be
+// created once per application and shared across multiple components.
+function getSchemaContext(imodel: IModelConnection): SchemaContext {
+  // see "Creating schema context" section for example implementation
+}
+
 function MyWidget() {
   return (
     <ModelsTreeComponent
+      getSchemaContext={getSchemaContext}
+      selectionStorage={getUnifiedSelectionStorage()}
       headerButtons={[
         (props) => <ModelsTreeComponent.ShowAllButton {...props} />,
         (props) => <ModelsTreeComponent.HideAllButton {...props} />,
         (props) => <MyCustomButton />,
       ]}
-      selectionMode={SelectionMode.Extended}
+      selectionMode={"extended"}
       hierarchyConfig={{
-        enableElementsClassGrouping: ClassGroupingOption.Yes,
+        elementClassGrouping: "enable",
       }}
     />
   );
@@ -113,10 +145,11 @@ Available header buttons:
 - `ModelsTreeComponent.View2DButton` toggles plan projection models' display.
 - `ModelsTreeComponent.View3DButton` toggles non-plan projection models' display.
 
-`ModelsTreeComponent` building blocks:
+#### Focus mode
 
-- `ModelsTree` renders the tree without the header.
-- `ModelsVisibilityHandler` knows how to get and control display of various concepts displayed in the Models tree: Subjects, Models, Categories, Elements.
+The Models tree can be used in a "focus mode" where the tree is automatically filtered to show only elements that are selected in the application. The mode can be controlled through a toggle button in the component's header. Since the feature is mutually exclusive with the "search" feature, enabling it automatically disables the search functionality.
+
+![Models tree focus mode demo](./media/models-tree-focus-mode.gif)
 
 ### Categories tree
 
@@ -127,11 +160,29 @@ The component, based on the active view, renders a hierarchy of either spatial (
 Typical usage:
 
 ```tsx
-import { CategoriesTreeComponent } from "@itwin/tree-widget-react";
-...
+import { IModelConnection } from "@itwin/core-frontend";
+import { SchemaContext } from "@itwin/ecschema-metadata";
+import { SelectionStorage } from "@itwin/unified-selection";
+import { CategoriesTreeComponent, CategoriesTreeComponent } from "@itwin/tree-widget-react";
+
+// The Categories tree requires a unified selection storage to support selection synchronization with the
+// application. The storage should be created once per application and shared across multiple selection-enabled
+// components.
+function getUnifiedSelectionStorage(): SelectionStorage {
+  // see "Creating unified selection storage" section for example implementation
+}
+
+// Schema context is used by Categories tree to access iModels metadata. Similar to selection storage, it should be
+// created once per application and shared across multiple components.
+function getSchemaContext(imodel: IModelConnection): SchemaContext {
+  // see "Creating schema context" section for example implementation
+}
+
 function MyWidget() {
   return (
     <CategoriesTreeComponent
+      getSchemaContext={getSchemaContext}
+      selectionStorage={getUnifiedSelectionStorage()}
       headerButtons={[
         (props) => <CategoriesTreeComponent.ShowAllButton {...props} />,
         (props) => <CategoriesTreeComponent.HideAllButton {...props} />,
@@ -148,19 +199,14 @@ Available header buttons:
 - `ModelsTreeComponent.HideAllButton` makes all categories hidden.
 - `ModelsTreeComponent.InvertButton` inverts display of all categories.
 
-`CategoriesTreeComponent` building blocks:
-
-- `CategoryTree` renders the tree without the header.
-- `CategoryVisibilityHandler` knows how to get and control display of Categories and SubCategories.
-
-### IModel content tree
+### iModel content tree
 
 The component renders a similar hierarchy to [Models tree](#models-tree), but with the following changes:
 
 - Only the hierarchy, without a header is rendered.
 - Visibility control is not allowed.
 - There's less hiding of `Subject` and `Model` nodes.
-- Show not only geometric, but all Models.
+- Show not only geometric, but all Models and Elements.
 
 In general, the component is expected to be used by advanced users to inspect contents of the iModel.
 
@@ -169,142 +215,181 @@ In general, the component is expected to be used by advanced users to inspect co
 Typical usage:
 
 ```tsx
+import { IModelConnection } from "@itwin/core-frontend";
+import { SchemaContext } from "@itwin/ecschema-metadata";
+import { SelectionStorage } from "@itwin/unified-selection";
 import { IModelContentTreeComponent } from "@itwin/tree-widget-react";
-...
+
+// The iModel content tree requires a unified selection storage to support selection synchronization with the
+// application. The storage should be created once per application and shared across multiple selection-enabled
+// components.
+function getUnifiedSelectionStorage(): SelectionStorage {
+  // see "Creating unified selection storage" section for example implementation
+}
+
+// Schema context is used by iModel content tree to access iModels metadata. Similar to selection storage, it should be
+// created once per application and shared across multiple components.
+function getSchemaContext(imodel: IModelConnection): SchemaContext {
+  // see "Creating schema context" section for example implementation
+}
+
 function MyWidget() {
   return (
-    <IModelContentTreeComponent />
+    <IModelContentTreeComponent
+      getSchemaContext={getSchemaContext}
+      selectionStorage={getUnifiedSelectionStorage()}
+    />
   );
 }
 ```
 
-## Performance tracking
+### Hierarchy level size limiting
 
-Components from this package allows consumers to track performance of specific features.
+All tree components in this package enforce a hierarchy level size limit. This means that when a node is expanded, only a certain number of child nodes are loaded. The limit is enforced to prevent loading too many nodes at once and to keep the performance of the tree components at an acceptable level.
 
-This can be achieved by passing `onPerformanceMeasured` function to `CategoriesTreeComponent`, `ModelsTreeComponent`, `IModelContentTreeComponent` or `TreeWidgetUiItemsProvider`. The function is invoked with feature id and time elapsed as the component is being used. List of tracked features:
+By default, the limit is set to `1000` nodes and components allow users to increase it to `10,000` for each hierarchy level individually:
 
-- `"{tree}-initial-load"` - time it takes to load initial nodes after the tree is created.
-- `"{tree}-hierarchy-level-load"` - time it takes to load children nodes when a node is expanded.
+![Hierarchy level size limit override example](./media/hierarchy-level-size-limit-override-example.gif)
 
-Where `{tree}` specifies which tree component the feature is of.
+### Hierarchy level filtering
+
+All tree components in this package allow users to filter nodes at each hierarchy level. The filter is applied to a single hierarchy level, which allows users to reduce amount of nodes being loaded - this is especially useful when a [hierarchy level size limit](#hierarchy-level-size-limiting) is hit:
 
-Example:
+![Hierarchy level filtering example](./media/hierarchy-level-filtering-example.gif)
+
+### Creating unified selection storage
+
+Tree components that support selection synchronization, require a unified selection storage object created using `createStorage()` function from `@itwin/unified-selection` package.
+
+Typically, we want one unified selection storage per application - this makes sure that selection in all application's components is synchronized. Below is an example implementation of `getUnifiedSelectionStorage` function that creates the storage and clears it when an iModel is closed:
 
 ```ts
-import { UiItemsManager } from "@itwin/appui-react";
-import { TreeWidgetUiItemsProvider, ModelsTreeComponent } from "@itwin/tree-widget-react";
-...
-UiItemsManager.register(
-  new TreeWidgetUiItemsProvider({
-    defaultPanelLocation: StagePanelLocation.Left,
-    defaultPanelSection: StagePanelSection.End,
-    defaultTreeWidgetPriority: 1000,
-    onPerformanceMeasured={(feature, elapsedTime) => {
-      telemetryClient.log(`TreeWidget [${feature}] took ${elapsedTime} ms`);
-    }},
-    trees: [{
-      id: ModelsTreeComponent.id,
-      getLabel: ModelsTreeComponent.getLabel,
-      render: (props) => <ModelsTreeComponent { ...props } />,
-    }];
-  })
-);
+import { IModelConnection } from "@itwin/core-frontend";
+import { createStorage, SelectionStorage } from "@itwin/unified-selection";
+
+let unifiedSelectionStorage: SelectionStorage | undefined;
+function getUnifiedSelectionStorage(): SelectionStorage {
+  if (!unifiedSelectionStorage) {
+    unifiedSelectionStorage = createStorage();
+    IModelConnection.onClose.addListener((imodel) => {
+      unifiedSelectionStorage!.clearStorage({ imodelKey: imodel.key });
+    });
+  }
+  return unifiedSelectionStorage;
+}
 ```
 
-For individual tree components the `onPerformanceMeasured` callback should be supplied through props:
+In case the application is also using components driven by APIs from `@itwin/presentation-frontend` package, which has its own selection manager, the single unified selection storage object should be passed to [`Presentation.initialize`](https://www.itwinjs.org/reference/presentation-frontend/core/presentation/initializestatic/) function, e.g.:
 
 ```ts
-return (
-  <ModelsTreeComponent
-    onPerformanceMeasured={(feature, elapsedTime) => {
-      console.log(`TreeWidget [${feature}] took ${elapsedTime} ms`)
-    }}
-  />
-);
+import { Presentation } from "@itwin/presentation-frontend";
+
+Presentation.initialize({
+  selection: {
+    selectionStorage: getUnifiedSelectionStorage(),
+  },
+});
+```
+
+### Creating schema context
+
+All tree components delivered with the package require a [`SchemaContext`](https://www.itwinjs.org/reference/ecschema-metadata/context/schemacontext/) to be able to access iModels metadata.
+
+Typically, we want one schema context per iModel per application - this allows schema information to be shared across components, saving memory and time required to access the metadata. Below is an example implementation of `getSchemaContext` function, required by tree components:
+
+```ts
+import { IModelConnection } from "@itwin/core-frontend";
+import { SchemaContext } from "@itwin/ecschema-metadata";
+import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
+
+const schemaContextCache = new Map<string, SchemaContext>();
+function getSchemaContext(imodel: IModelConnection) {
+  const key = imodel.getRpcProps().key;
+  let schemaContext = schemaContextCache.get(key);
+  if (!schemaContext) {
+    const schemaLocater = new ECSchemaRpcLocater(imodel.getRpcProps());
+    schemaContext = new SchemaContext();
+    schemaContext.addLocater(schemaLocater);
+    schemaContextCache.set(key, schemaContext);
+    imodel.onClose.addOnce(() => schemaContextCache.delete(key));
+  }
+  return schemaContext;
+}
 ```
 
-## Usage tracking
+## Telemetry
+
+### Performance tracking
+
+Components from this package allows consumers to track performance of specific features.
+
+This can be achieved by passing `onPerformanceMeasured` function to `CategoriesTreeComponent`, `ModelsTreeComponent`, `IModelContentTreeComponent` or `TreeWidgetUiItemsProvider`. The function is invoked with feature id and time elapsed as the component is being used. List of tracked features:
+
+- `"{tree}-initial-load"` - time it takes to load initial nodes after the tree is created.
+- `"{tree}-hierarchy-level-load"` - time it takes to load child nodes when a node is expanded.
+- `"{tree}-reload"` - time it takes to reload the tree after data in the iModel changes or it's being reloaded due to filtering.
+
+Where `{tree}` specifies which tree component the feature is of.
+
+### Usage tracking
 
 Components from this package allows consumers to track the usage of specific features.
 
 This can be achieved by passing `onFeatureUsed` function to `CategoriesTreeComponent`, `ModelsTreeComponent`, `IModelContentTreeComponent` or `TreeWidgetUiItemsProvider`. The function is invoked with feature id as the component is being used. List of tracked features:
 
 - `"choose-{tree}"` - when a tree is selected in the tree selector.
-- `"use-{tree}"` - when an interaction with a tree hierarchy happens.
+- `"use-{tree}"` - when an interaction with a tree hierarchy happens. This includes any kind of interaction with nodes, including them being expanded/collapsed, selected, filtered, their visibility change, etc.
 - `"{tree}-visibility-change"` - when visibility is toggled using an "eye" button.
 - `"models-tree-showall"` - when "Show All" button is used in `ModelsTreeComponent`.
 - `"models-tree-hideall"` - when "Hide All" button is used in `ModelsTreeComponent`.
 - `"models-tree-invert"` - when "Invert" button is used in `ModelsTreeComponent`.
 - `"models-tree-view2d"` - when "Toggle 2D Views" button is used in `ModelsTreeComponent`.
 - `"models-tree-view3d"` - when "Toggle 3D Views" button is used in `ModelsTreeComponent`.
+- `"models-tree-instancesfocus"` - when "Instances focus mode" toggle button is used in `ModelsTreeComponent`.
 - `"models-tree-zoom-to-node"` - when node is zoomed to in `ModelsTree`.
 - `"models-tree-filtering"` - when a filter is applied in `ModelsTree`.
-- `"models-tree-hierarchy-level-filtering"` - when a hierarchy level filter is applied in `ModelsTree`.
-- `"models-tree-hierarchy-level-size-limit-hit"` - when hierarchy limit is exceeded while loading nodes in `ModelsTree`.
+- `"models-tree-hierarchy-level-filtering"` - when a hierarchy level filter is applied in the `ModelsTree`.
+- `"models-tree-hierarchy-level-size-limit-hit"` - when hierarchy level size limit is exceeded while loading nodes in the `ModelsTree`.
 - `"categories-tree-showall"` - when "Show All" button is used in `CategoriesTreeComponent`.
 - `"categories-tree-hideall"` - when "Hide All" button is used in `CategoriesTreeComponent`.
 - `"categories-tree-invert"` - when "Invert" button is used in `CategoriesTreeComponent`.
 
 Where `{tree}` specifies which tree component the feature is of.
 
-Example:
+### Example
 
 ```ts
 import { UiItemsManager } from "@itwin/appui-react";
-import { TreeWidgetUiItemsProvider, ModelsTreeComponent } from "@itwin/tree-widget-react";
-...
+import { TreeWidgetUiItemsProvider } from "@itwin/tree-widget-react";
+
 UiItemsManager.register(
   new TreeWidgetUiItemsProvider({
-    defaultPanelLocation: StagePanelLocation.Left,
-    defaultPanelSection: StagePanelSection.End,
-    defaultTreeWidgetPriority: 1000,
+    onPerformanceMeasured={(feature, elapsedTime) => {
+      telemetryClient.log(`TreeWidget [${feature}] took ${elapsedTime} ms`);
+    }},
     onFeatureUsed={(feature) => {
       telemetryClient.log(`TreeWidget [${feature}] used`);
     }},
-    trees: [{
-      id: ModelsTreeComponent.id,
-      getLabel: ModelsTreeComponent.getLabel,
-      render: (props) => <ModelsTreeComponent { ...props } />,
-    }];
   })
 );
 ```
 
-For individual tree components the `onFeatureUsed` callback should be supplied through props:
+For individual tree components the callbacks should be supplied through props:
 
 ```ts
-return (
-  <ModelsTreeComponent
-    onFeatureUsed={(feature) => {
-      console.log(`TreeWidget [${feature}] used`)
-    }}
-  />
-);
-```
-
-## Tree selector icons
-
-Provided trees to `TreeWidgetUiItemsProvider` can define a `startIcon` property that will be shown next to the tree label in tree selector.
+import { ModelsTreeComponent } from "@itwin/tree-widget-react";
 
-Example:
-
-```ts
-import { UiItemsManager } from "@itwin/appui-react";
-import { TreeWidgetUiItemsProvider, ModelsTreeComponent } from "@itwin/tree-widget-react";
-import { SvgTechnicalPreviewMiniBw } from "@itwin/itwinui-icons-react";
-...
-UiItemsManager.register(
-  new TreeWidgetUiItemsProvider({
-    defaultPanelLocation: StagePanelLocation.Left,
-    defaultPanelSection: StagePanelSection.End,
-    defaultTreeWidgetPriority: 1000,
-    trees: [{
-      id: ModelsTreeComponent.id,
-      getLabel: ModelsTreeComponent.getLabel,
-      render: (props) => <ModelsTreeComponent { ...props } />,
-      startIcon: <SvgTechnicalPreviewMiniBw />,
-    }];
-  })
-);
+function MyWidget() {
+  return (
+    <ModelsTreeComponent
+      {...otherProps}
+      onPerformanceMeasured={(feature, elapsedTime) => {
+        console.log(`TreeWidget [${feature}] took ${elapsedTime} ms`)
+      }}
+      onFeatureUsed={(feature) => {
+        console.log(`TreeWidget [${feature}] used`)
+      }}
+    />
+  );
+}
 ```

package/lib/cjs/TreeWidget.d.ts

@@ -1,5 +1,4 @@
-import type { Localization } from "@itwin/core-common";
-import type { LocalizationOptions } from "@itwin/core-i18n";
+import type { Localization, TranslationOptions } from "@itwin/core-common";
 /**
  * Entry point for static initialization required by various components used in the package.
  * @public
@@ -7,7 +6,6 @@ import type { LocalizationOptions } from "@itwin/core-i18n";
 export declare class TreeWidget {
     private static _i18n?;
     private static _initialized?;
-    private static _dispose?;
     /**
      * Called by IModelApp to initialize the Tree Widget
      * @param i18n - The internationalization service created by the IModelApp.
@@ -21,6 +19,6 @@ export declare class TreeWidget {
     static get i18nNamespace(): string;
     /** Calls i18n.translateWithNamespace with the "TreeWidget" namespace. Do NOT include the namespace in the key.
      */
-    static translate(key: string | string[], options?: LocalizationOptions): string;
+    static translate(key: string | string[], options?: TranslationOptions): string;
 }
 //# sourceMappingURL=TreeWidget.d.ts.map

package/lib/cjs/TreeWidget.js

@@ -7,7 +7,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TreeWidget = void 0;
 const core_common_1 = require("@itwin/core-common");
 const core_frontend_1 = require("@itwin/core-frontend");
-const Utils_1 = require("./components/trees/common/Utils");
 /**
  * Entry point for static initialization required by various components used in the package.
  * @public
@@ -23,7 +22,6 @@ class TreeWidget {
         }
         TreeWidget._initialized = true;
         TreeWidget._i18n = i18n ?? core_frontend_1.IModelApp.localization;
-        TreeWidget._dispose = (0, Utils_1.registerRenderers)();
         return TreeWidget._i18n.registerNamespace(TreeWidget.i18nNamespace);
     }
     /** Unregisters the TreeWidget internationalization service namespace */
@@ -32,10 +30,6 @@ class TreeWidget {
             TreeWidget._i18n.unregisterNamespace(TreeWidget.i18nNamespace);
             TreeWidget._i18n = undefined;
         }
-        if (TreeWidget._dispose) {
-            TreeWidget._dispose();
-            TreeWidget._dispose = undefined;
-        }
         TreeWidget._initialized = false;
     }
     /** The internationalization service created by the IModelApp. */

package/lib/cjs/TreeWidget.js.map

@@ -1 +1 @@
-{"version":3,"file":"TreeWidget.js","sourceRoot":"","sources":["../../src/TreeWidget.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAGhG,oDAAiE;AACjE,wDAAiD;AACjD,2DAAoE;AAIpE;;;GAGG;AACH,MAAa,UAAU;IAKrB;;;OAGG;IACI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAmB;QAChD,IAAI,IAAI,CAAC,YAAY,EAAE;YACrB,OAAO;SACR;QAED,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC;QAC/B,UAAU,CAAC,KAAK,GAAG,IAAI,IAAI,yBAAS,CAAC,YAAY,CAAC;QAClD,UAAU,CAAC,QAAQ,GAAG,IAAA,yBAAiB,GAAE,CAAC;QAC1C,OAAO,UAAU,CAAC,KAAK,CAAC,iBAAiB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACtE,CAAC;IAED,wEAAwE;IACjE,MAAM,CAAC,SAAS;QACrB,IAAI,UAAU,CAAC,KAAK,EAAE;YACpB,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAC/D,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;SAC9B;QAED,IAAI,UAAU,CAAC,QAAQ,EAAE;YACvB,UAAU,CAAC,QAAQ,EAAE,CAAC;YACtB,UAAU,CAAC,QAAQ,GAAG,SAAS,CAAC;SACjC;QAED,UAAU,CAAC,YAAY,GAAG,KAAK,CAAC;IAClC,CAAC;IAED,iEAAiE;IAC1D,MAAM,KAAK,IAAI;QACpB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;YACrB,MAAM,IAAI,0BAAY,CAAC,2BAAa,CAAC,KAAK,EAAE,4BAA4B,CAAC,CAAC;SAC3E;QACD,OAAO,UAAU,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,kDAAkD;IAC3C,MAAM,KAAK,aAAa;QAC7B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED;OACG;IACI,MAAM,CAAC,SAAS,CAAC,GAAsB,EAAE,OAA6B;QAC3E,MAAM,SAAS,GAAG,GAAG,UAAU,CAAC,aAAa,IAAI,GAAG,EAAE,CAAC;QACvD,OAAO,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC;CACF;AAtDD,gCAsDC","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 type { Localization } from \"@itwin/core-common\";\nimport { BentleyError, BentleyStatus } from \"@itwin/core-common\";\nimport { IModelApp } from \"@itwin/core-frontend\";\nimport { registerRenderers } from \"./components/trees/common/Utils\";\n\nimport type { LocalizationOptions } from \"@itwin/core-i18n\";\n\n/**\n * Entry point for static initialization required by various components used in the package.\n * @public\n */\nexport class TreeWidget {\n  private static _i18n?: Localization;\n  private static _initialized?: boolean;\n  private static _dispose?: () => void;\n\n  /**\n   * Called by IModelApp to initialize the Tree Widget\n   * @param i18n - The internationalization service created by the IModelApp.\n   */\n  public static async initialize(i18n?: Localization): Promise<void> {\n    if (this._initialized) {\n      return;\n    }\n\n    TreeWidget._initialized = true;\n    TreeWidget._i18n = i18n ?? IModelApp.localization;\n    TreeWidget._dispose = registerRenderers();\n    return TreeWidget._i18n.registerNamespace(TreeWidget.i18nNamespace);\n  }\n\n  /** Unregisters the TreeWidget internationalization service namespace */\n  public static terminate() {\n    if (TreeWidget._i18n) {\n      TreeWidget._i18n.unregisterNamespace(TreeWidget.i18nNamespace);\n      TreeWidget._i18n = undefined;\n    }\n\n    if (TreeWidget._dispose) {\n      TreeWidget._dispose();\n      TreeWidget._dispose = undefined;\n    }\n\n    TreeWidget._initialized = false;\n  }\n\n  /** The internationalization service created by the IModelApp. */\n  public static get i18n(): Localization {\n    if (!TreeWidget._i18n) {\n      throw new BentleyError(BentleyStatus.ERROR, \"TreeWidget not initialized\");\n    }\n    return TreeWidget._i18n;\n  }\n\n  /** The internationalization service namespace. */\n  public static get i18nNamespace(): string {\n    return \"TreeWidget\";\n  }\n\n  /** Calls i18n.translateWithNamespace with the \"TreeWidget\" namespace. Do NOT include the namespace in the key.\n   */\n  public static translate(key: string | string[], options?: LocalizationOptions): string {\n    const stringKey = `${TreeWidget.i18nNamespace}:${key}`;\n    return TreeWidget.i18n.getLocalizedString(stringKey, options);\n  }\n}\n"]}
+{"version":3,"file":"TreeWidget.js","sourceRoot":"","sources":["../../src/TreeWidget.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAEhG,oDAAiE;AACjE,wDAAiD;AAIjD;;;GAGG;AACH,MAAa,UAAU;IAIrB;;;OAGG;IACI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAmB;QAChD,IAAI,IAAI,CAAC,YAAY,EAAE;YACrB,OAAO;SACR;QAED,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC;QAC/B,UAAU,CAAC,KAAK,GAAG,IAAI,IAAI,yBAAS,CAAC,YAAY,CAAC;QAClD,OAAO,UAAU,CAAC,KAAK,CAAC,iBAAiB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACtE,CAAC;IAED,wEAAwE;IACjE,MAAM,CAAC,SAAS;QACrB,IAAI,UAAU,CAAC,KAAK,EAAE;YACpB,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAC/D,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;SAC9B;QAED,UAAU,CAAC,YAAY,GAAG,KAAK,CAAC;IAClC,CAAC;IAED,iEAAiE;IAC1D,MAAM,KAAK,IAAI;QACpB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;YACrB,MAAM,IAAI,0BAAY,CAAC,2BAAa,CAAC,KAAK,EAAE,4BAA4B,CAAC,CAAC;SAC3E;QACD,OAAO,UAAU,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,kDAAkD;IAC3C,MAAM,KAAK,aAAa;QAC7B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED;OACG;IACI,MAAM,CAAC,SAAS,CAAC,GAAsB,EAAE,OAA4B;QAC1E,MAAM,SAAS,GAAG,GAAG,UAAU,CAAC,aAAa,IAAI,GAAG,EAAE,CAAC;QACvD,OAAO,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC;CACF;AA/CD,gCA+CC","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 { BentleyError, BentleyStatus } from \"@itwin/core-common\";\nimport { IModelApp } from \"@itwin/core-frontend\";\n\nimport type { Localization, TranslationOptions } from \"@itwin/core-common\";\n\n/**\n * Entry point for static initialization required by various components used in the package.\n * @public\n */\nexport class TreeWidget {\n  private static _i18n?: Localization;\n  private static _initialized?: boolean;\n\n  /**\n   * Called by IModelApp to initialize the Tree Widget\n   * @param i18n - The internationalization service created by the IModelApp.\n   */\n  public static async initialize(i18n?: Localization): Promise<void> {\n    if (this._initialized) {\n      return;\n    }\n\n    TreeWidget._initialized = true;\n    TreeWidget._i18n = i18n ?? IModelApp.localization;\n    return TreeWidget._i18n.registerNamespace(TreeWidget.i18nNamespace);\n  }\n\n  /** Unregisters the TreeWidget internationalization service namespace */\n  public static terminate() {\n    if (TreeWidget._i18n) {\n      TreeWidget._i18n.unregisterNamespace(TreeWidget.i18nNamespace);\n      TreeWidget._i18n = undefined;\n    }\n\n    TreeWidget._initialized = false;\n  }\n\n  /** The internationalization service created by the IModelApp. */\n  public static get i18n(): Localization {\n    if (!TreeWidget._i18n) {\n      throw new BentleyError(BentleyStatus.ERROR, \"TreeWidget not initialized\");\n    }\n    return TreeWidget._i18n;\n  }\n\n  /** The internationalization service namespace. */\n  public static get i18nNamespace(): string {\n    return \"TreeWidget\";\n  }\n\n  /** Calls i18n.translateWithNamespace with the \"TreeWidget\" namespace. Do NOT include the namespace in the key.\n   */\n  public static translate(key: string | string[], options?: TranslationOptions): string {\n    const stringKey = `${TreeWidget.i18nNamespace}:${key}`;\n    return TreeWidget.i18n.getLocalizedString(stringKey, options);\n  }\n}\n"]}

package/lib/cjs/components/SelectableTree.d.ts

@@ -1,17 +1,14 @@
 /// <reference types="react" />
 import "./SelectableTree.scss";
 import type { IModelConnection } from "@itwin/core-frontend";
-/**
- * Props for rendering trees
- * @public
- */
+/** Props for rendering trees */
 export interface TreeRenderProps {
     density?: "enlarged" | "default";
     onPerformanceMeasured?: (featureId: string, elapsedTime: number) => void;
     onFeatureUsed?: (feature: string) => void;
 }
 /**
- * Definition of a tree component displayed in [[SelectableTree]]
+ * Definition of a tree component displayed in `SelectableTree`.
  * @public
  */
 export interface TreeDefinition {
@@ -29,10 +26,7 @@ export interface TreeDefinition {
     /** Icon to render before tree label in tree selector */
     startIcon?: React.ReactNode;
 }
-/**
- * Props for [[SelectableTree]]
- * @public
- */
+/** Props for `SelectableTree` */
 export interface SelectableTreeProps {
     trees: TreeDefinition[];
     density?: "enlarged" | "default";

package/lib/cjs/components/SelectableTree.js

@@ -81,7 +81,7 @@ function getTreeSelectorProps(trees) {
                 {
                     id: "no-trees",
                     label: "",
-                    render: () => (0, jsx_runtime_1.jsx)(core_react_1.FillCentered, { children: TreeWidget_1.TreeWidget.translate("noTrees") }),
+                    render: () => (0, jsx_runtime_1.jsx)(core_react_1.FillCentered, { children: TreeWidget_1.TreeWidget.translate("selectableTree.noTrees") }),
                 },
             ],
         };