@itwin/tree-widget-react 3.0.0-dev.6 → 3.0.1

package/README.md

@@ -12,9 +12,9 @@ The new `3.0` version of the package contains a few notable changes, compared to
 
 - 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.
+- 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. As a result, we're seeing 30-40% performance improvement for loading nodes in the Models tree when using a web backend and orders of magnitude improvement when using a local backend (desktop & mobile case).
 
-  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.
+  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. This also adds an `@itwin/ecschema-metadata` peer dependency on version `^4.0.0`.
 
   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.
 
@@ -24,11 +24,16 @@ The new `3.0` version of the package contains a few notable changes, compared to
   | ----------------------------------------------- | ----------------------------------------------- |
   | ![Tree widget 2.x](./media/tree-widget-2.x.png) | ![Tree widget 3.0](./media/tree-widget-3.0.png) |
 
+  This change introduces an `@itwin/itwinui-react` peer dependency on version `^3.11.0`.
+
 - 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.
 
+- Behavior of header buttons like "Show all", "Hide all", etc. has been changed in filtered hierarchies' case. Previously they applied the visibility change on everything, no matter if the hierarchy is filtered or not. Now, when a hierarchy is filtered, only the nodes in the filtered hierarchy are affected.
+
 - 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.
+  - In addition to the two filtering-related improvements above, we now allow displaying a subset of the tree by providing a `getFilteredPaths` function. See [Displaying a subset of the tree](#displaying-a-subset-of-the-tree) section for more details.
   - 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
@@ -37,50 +42,56 @@ Typically, the package is used with an [AppUI](https://github.com/iTwin/appui/tr
 
 In any case, **before** using any APIs or components delivered with the package, it needs to be initialized:
 
-```ts
-import { IModelApp } from "@itwin/core-frontend";
+<!-- [[include: [TreeWidget.TreeWidgetInitializeImports, TreeWidget.TreeWidgetInitialize], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
+```tsx
 import { TreeWidget } from "@itwin/tree-widget-react";
+import { IModelApp } from "@itwin/core-frontend";
 
 await TreeWidget.initialize(IModelApp.localization);
 ```
 
+<!-- END EXTRACTION -->
+
 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
+<!-- [[include: [TreeWidget.RegisterExampleImports, TreeWidget.RegisterExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
+```tsx
 import { UiItemsManager } from "@itwin/appui-react";
 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.</>,
-        },
-      ],
-    }),
-  ],
+  getWidgets: () =>
+    [
+      createTreeWidget({
+        trees: [
+          // add a custom component
+          { id: "my-tree-id", startIcon: <svg />, getLabel: () => "My Custom Tree", render: () => <>This is my custom tree.</> },
+          // add the Models tree component delivered with the package
+          {
+            id: ModelsTreeComponent.id,
+            getLabel: () => ModelsTreeComponent.getLabel(),
+            render: (props) => (
+              <ModelsTreeComponent
+                // see "Creating schema context" section for example implementation
+                getSchemaContext={getSchemaContext}
+                // see "Creating unified selection storage" section for example implementation
+                selectionStorage={unifiedSelectionStorage}
+              />
+            ),
+          },
+        ],
+      }),
+    ] as readonly Widget[],
 });
 ```
 
+<!-- END EXTRACTION -->
+
 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
@@ -99,44 +110,30 @@ The component renders a tree that tries to replicate how a typical "Models" tree
 
 Typical usage:
 
+<!-- [[include: [TreeWidget.ModelsTreeExampleImports, TreeWidget.ModelsTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```tsx
-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
+      // see "Creating schema context" section for example implementation
       getSchemaContext={getSchemaContext}
-      selectionStorage={getUnifiedSelectionStorage()}
+      // see "Creating unified selection storage" section for example implementation
+      selectionStorage={unifiedSelectionStorage}
       headerButtons={[
-        (props) => <ModelsTreeComponent.ShowAllButton {...props} />,
-        (props) => <ModelsTreeComponent.HideAllButton {...props} />,
-        (props) => <MyCustomButton />,
+        (props) => <ModelsTreeComponent.ShowAllButton {...props} key={"ShowAllButton"} />,
+        (props) => <ModelsTreeComponent.HideAllButton {...props} key={"HideAllButton"} />,
       ]}
-      selectionMode={"extended"}
-      hierarchyConfig={{
-        elementClassGrouping: "enable",
-      }}
     />
   );
 }
 ```
 
+<!-- END EXTRACTION -->
+
 Available header buttons:
 
 - `ModelsTreeComponent.ShowAllButton` makes everything in the iModel displayed.
@@ -161,13 +158,48 @@ This package provides building blocks for custom models tree:
 
 Example:
 
+<!-- [[include: [TreeWidget.CustomModelsTreeExampleImports, TreeWidget.CustomModelsTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```tsx
+import { TreeWithHeader, useModelsTree, useModelsTreeButtonProps, VisibilityTree, VisibilityTreeRenderer } from "@itwin/tree-widget-react";
+import type { SelectionStorage } from "@itwin/unified-selection";
+import type { IModelConnection, Viewport } from "@itwin/core-frontend";
+import type { SchemaContext } from "@itwin/ecschema-metadata";
+import type { ComponentPropsWithoutRef } from "react";
+
+type VisibilityTreeRendererProps = ComponentPropsWithoutRef<typeof VisibilityTreeRenderer>;
+type CustomModelsTreeRendererProps = Parameters<ComponentPropsWithoutRef<typeof VisibilityTree>["treeRenderer"]>[0];
+function CustomModelsTreeRenderer(props: CustomModelsTreeRendererProps) {
+  const getLabel = props.getLabel;
+  const getLabelCallback = useCallback<Required<VisibilityTreeRendererProps>["getLabel"]>(
+    (node) => {
+      const originalLabel = getLabel(node);
+      return <>Custom node - {originalLabel}</>;
+    },
+    [getLabel],
+  );
+  return <VisibilityTreeRenderer {...props} getLabel={getLabelCallback} getSublabel={getSublabel} />;
+}
+
+interface CustomModelsTreeProps {
+  imodel: IModelConnection;
+  viewport: Viewport;
+  getSchemaContext: (imodel: IModelConnection) => SchemaContext;
+  selectionStorage: SelectionStorage;
+}
+
 function CustomModelsTreeComponent({ imodel, viewport, getSchemaContext, selectionStorage }: CustomModelsTreeProps) {
-  const buttonProps = useModelsTreeButtonProps({ imodel, viewport });
+  const { buttonProps } = useModelsTreeButtonProps({ imodel, viewport });
   const { modelsTreeProps, rendererProps } = useModelsTree({ activeView: viewport });
 
   return (
-    <TreeWithHeader buttons={[<ModelsTreeComponent.ShowAllButton {...buttonProps} />, <ModelsTreeComponent.HideAllButton {...buttonProps} />]}>
+    <TreeWithHeader
+      buttons={[
+        <ModelsTreeComponent.ShowAllButton {...buttonProps} key={"ShowAllButton"} />,
+        <ModelsTreeComponent.HideAllButton {...buttonProps} key={"HideAllButton"} />,
+      ]}
+    >
       <VisibilityTree
         {...modelsTreeProps}
         getSchemaContext={getSchemaContext}
@@ -178,49 +210,54 @@ function CustomModelsTreeComponent({ imodel, viewport, getSchemaContext, selecti
     </TreeWithHeader>
   );
 }
-
-type VisibilityTreeRendererProps = ComponentPropsWithoutRef<typeof VisibilityTreeRenderer>;
-type CustomModelsTreeRendererProps = Parameters<ComponentPropsWithoutRef<typeof VisibilityTree>["treeRenderer"]>[0];
-
-function CustomModelsTreeRenderer(props: CustomModelsTreeRendererProps) {
-  const getLabel = useCallback<Required<VisibilityTreeRendererProps>["getLabel"]>(
-    (node) => {
-      const originalLabel = props.getLabel(node);
-      return <>Custom node - {originalLabel}</>;
-    },
-    [props.getLabel],
-  );
-  return <VisibilityTreeRenderer {...props} getLabel={getLabel} getSublabel={getSublabel} />;
-}
 ```
 
+<!-- END EXTRACTION -->
+
 #### Displaying a subset of the tree
 
 Models tree allows displaying a subset of all nodes by providing a `getFilteredPaths` function, which receives a `createInstanceKeyPaths` function for creating hierarchy node paths from instance keys or an instance label and returns a list of hierarchy node paths targeting some nodes. When these paths are provided, the displayed hierarchy consists only of the targeted nodes, their ancestors, and their children. Example implementation of `getFilteredPaths`:
 
+<!-- [[include: [TreeWidget.GetFilteredPathsComponentExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```tsx
-const getFilteredPaths = async ({ createInstanceKeyPaths }) => {
-  return createInstanceKeyPaths({
-    // list of instance keys representing nodes that should be displayed in the hierarchy
-    keys: myInstanceKeys,
-    // instead of providing instance keys, a label can be provided to display all nodes that contain it
-    // label: "MyLabel"
-  });
-};
-```
+type UseModelsTreeProps = Parameters<typeof useModelsTree>[0];
+type GetFilteredPathsType = Exclude<UseModelsTreeProps["getFilteredPaths"], undefined>;
+interface CustomModelsTreeProps {
+  viewport: Viewport;
+  selectionStorage: SelectionStorage;
+  imodel: IModelConnection;
+  targetItems: InstanceKey[];
+}
 
-The `ModelsTree` component displays a message when too many matches are found while filtering the tree; for this reason, it is recommended to throw `FilterLimitExceededError` that is provided by this package when the displayed subset is too large. Typically, this error is thrown when there are more than 100 matches. The error is cleared when a new reference for `getFilteredPaths` is provided.
+function CustomModelsTreeComponent({ viewport, selectionStorage, imodel, targetItems }: CustomModelsTreeProps) {
+  const getFilteredPaths = useCallback<GetFilteredPathsType>(
+    async ({ createInstanceKeyPaths }) => {
+      return createInstanceKeyPaths({
+        // list of instance keys representing nodes that should be displayed in the hierarchy
+        targetItems,
+      });
+    },
+    [targetItems],
+  );
 
-When a filter is provided or instance focus mode is used, the hierarchy automatically expands to show the targeted nodes. This might not be desirable when displaying a subset of the hierarchy and can be disabled by adding the `autoExpand: false` option to each path returned by `getFilteredPaths`:
+  const { modelsTreeProps, rendererProps } = useModelsTree({ activeView: viewport, getFilteredPaths });
 
-```tsx
-const getFilteredPaths = async ({ createInstanceKeyPaths }) => {
-  const paths = await createInstanceKeyPaths({ keys: myInstanceKeys });
-  // disable auto-expansion
-  return paths.map((path) => ({ path, options: { autoExpand: false } }));
-};
+  return (
+    <VisibilityTree
+      {...modelsTreeProps}
+      getSchemaContext={getSchemaContext}
+      selectionStorage={selectionStorage}
+      imodel={imodel}
+      treeRenderer={(props) => <VisibilityTreeRenderer {...props} {...rendererProps} />}
+    />
+  );
+}
 ```
 
+<!-- END EXTRACTION -->
+
 ### Categories tree
 
 The component, based on the active view, renders a hierarchy of either spatial (3d) or drawing (2d) categories. The hierarchy consists of two levels - the category (spatial or drawing) and its sub-categories. There's also a header that renders categories search box and various visibility control buttons.
@@ -229,40 +266,27 @@ The component, based on the active view, renders a hierarchy of either spatial (
 
 Typical usage:
 
-```tsx
-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
-}
+<!-- [[include: [TreeWidget.CategoriesTreeExampleImports, TreeWidget.CategoriesTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
 
-// 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
-}
+```tsx
+import { CategoriesTreeComponent } from "@itwin/tree-widget-react";
 
 function MyWidget() {
   return (
     <CategoriesTreeComponent
+      // see "Creating schema context" section for example implementation
       getSchemaContext={getSchemaContext}
-      selectionStorage={getUnifiedSelectionStorage()}
-      headerButtons={[
-        (props) => <CategoriesTreeComponent.ShowAllButton {...props} />,
-        (props) => <CategoriesTreeComponent.HideAllButton {...props} />,
-        (props) => <MyCustomButton />,
-      ]}
+      // see "Creating unified selection storage" section for example implementation
+      selectionStorage={unifiedSelectionStorage}
+      headerButtons={[(props) => <CategoriesTreeComponent.ShowAllButton {...props} />, (props) => <CategoriesTreeComponent.HideAllButton {...props} />]}
     />
   );
 }
 ```
 
+<!-- END EXTRACTION -->
+
 Available header buttons:
 
 - `ModelsTreeComponent.ShowAllButton` makes all categories and their subcategories displayed.
@@ -278,44 +302,68 @@ This package provides building blocks for custom categories tree:
 
 Example:
 
-```tsx
-function CustomCategoriesTreeComponent({ imodel, viewport, getSchemaContext, selectionStorage }: CustomCategoriesTreeProps) {
-  const buttonProps = useCategoriesTreeButtonProps({ imodel, viewport });
-  const { categoriesTreeProps, rendererProps } = useCategoriesTree({ activeView: viewport });
+<!-- [[include: [TreeWidget.CustomCategoriesTreeExampleImports, TreeWidget.CustomCategoriesTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
 
-  return (
-    <TreeWithHeader buttons={[<CategoriesTreeComponent.ShowAllButton {...buttonProps} />, <CategoriesTreeComponent.HideAllButton {...buttonProps} />]}>
-      <VisibilityTree
-        {...categoriesTreeProps}
-        getSchemaContext={getSchemaContext}
-        selectionStorage={selectionStorage}
-        imodel={imodel}
-        treeRenderer={(props) => <CustomCategoriesTreeRenderer {...props} {...rendererProps} />}
-      />
-    </TreeWithHeader>
-  );
-}
+```tsx
+import { TreeWithHeader, useCategoriesTree, useCategoriesTreeButtonProps, VisibilityTree, VisibilityTreeRenderer } from "@itwin/tree-widget-react";
+import type { IModelConnection, Viewport } from "@itwin/core-frontend";
+import type { SelectionStorage } from "@itwin/unified-selection";
+import type { SchemaContext } from "@itwin/ecschema-metadata";
+import type { ComponentPropsWithoutRef } from "react";
 
 type VisibilityTreeRendererProps = ComponentPropsWithoutRef<typeof VisibilityTreeRenderer>;
 type CustomCategoriesTreeRendererProps = Parameters<ComponentPropsWithoutRef<typeof VisibilityTree>["treeRenderer"]>[0];
 
 function CustomCategoriesTreeRenderer(props: CustomCategoriesTreeRendererProps) {
-  const getLabel = useCallback<Required<VisibilityTreeRendererProps>["getLabel"]>(
+  const getLabel = props.getLabel;
+  const getLabelCallback = useCallback<Required<VisibilityTreeRendererProps>["getLabel"]>(
     (node) => {
-      const originalLabel = props.getLabel(node);
+      const originalLabel = getLabel(node);
       return <>Custom node - {originalLabel}</>;
     },
-    [props.getLabel],
+    [getLabel],
   );
 
   const getSublabel = useCallback<Required<VisibilityTreeRendererProps>["getSublabel"]>(() => {
     return <>Custom sub label</>;
   }, []);
 
-  return <VisibilityTreeRenderer {...props} getLabel={getLabel} getSublabel={getSublabel} />;
+  return <VisibilityTreeRenderer {...props} getLabel={getLabelCallback} getSublabel={getSublabel} />;
+}
+
+interface CustomCategoriesTreeProps {
+  imodel: IModelConnection;
+  viewport: Viewport;
+  getSchemaContext: (imodel: IModelConnection) => SchemaContext;
+  selectionStorage: SelectionStorage;
+}
+
+function CustomCategoriesTreeComponent({ imodel, viewport, getSchemaContext, selectionStorage }: CustomCategoriesTreeProps) {
+  const { buttonProps } = useCategoriesTreeButtonProps({ viewport });
+  const { categoriesTreeProps, rendererProps } = useCategoriesTree({ activeView: viewport, filter: "" });
+
+  return (
+    <TreeWithHeader
+      buttons={[
+        <CategoriesTreeComponent.ShowAllButton {...buttonProps} key={"ShowAllButton"} />,
+        <CategoriesTreeComponent.HideAllButton {...buttonProps} key={"HideAllButton"} />,
+      ]}
+    >
+      <VisibilityTree
+        {...categoriesTreeProps}
+        getSchemaContext={getSchemaContext}
+        selectionStorage={selectionStorage}
+        imodel={imodel}
+        treeRenderer={(props) => <CustomCategoriesTreeRenderer {...props} {...rendererProps} />}
+      />
+    </TreeWithHeader>
+  );
 }
 ```
 
+<!-- END EXTRACTION -->
+
 ### iModel content tree
 
 The component renders a similar hierarchy to [Models tree](#models-tree), but with the following changes:
@@ -331,35 +379,26 @@ In general, the component is expected to be used by advanced users to inspect co
 
 Typical usage:
 
+<!-- [[include: [TreeWidget.ImodelContentTreeExampleImports, TreeWidget.ImodelContentTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```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
+      // see "Creating schema context" section for example implementation
       getSchemaContext={getSchemaContext}
-      selectionStorage={getUnifiedSelectionStorage()}
+      // see "Creating unified selection storage" section for example implementation
+      selectionStorage={unifiedSelectionStorage}
     />
   );
 }
 ```
 
+<!-- END EXTRACTION -->
+
 ### Custom trees
 
 The package delivers a set of building blocks for creating trees that look and feel similar to the tree components provided by this package.
@@ -373,40 +412,69 @@ A "basic" tree is a tree that renders the hierarchy without visibility control -
 
 Example:
 
+<!-- [[include: [TreeWidget.CustomTreeExampleImports, TreeWidget.CustomTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```tsx
-import { ComponentPropsWithoutRef } from "react";
-import { IModelConnection } from "@itwin/core-frontend";
-import { SchemaContext } from "@itwin/ecschema-metadata";
-import { SelectionStorage } from "@itwin/unified-selection";
+import type { ComponentPropsWithoutRef } from "react";
+import type { IModelConnection } from "@itwin/core-frontend";
 import { Tree, TreeRenderer } from "@itwin/tree-widget-react";
-
-
-function getUnifiedSelectionStorage(): SelectionStorage {
-  // see "Creating unified selection storage" section for example implementation
-}
-
-function getSchemaContext(imodel: IModelConnection): SchemaContext {
-  // see "Creating schema context" section for example implementation
-}
+import { createClassBasedHierarchyDefinition, createNodesQueryClauseFactory } from "@itwin/presentation-hierarchies";
+import { createBisInstanceLabelSelectClauseFactory } from "@itwin/presentation-shared";
 
 type TreeProps = ComponentPropsWithoutRef<typeof Tree>;
 const getHierarchyDefinition: TreeProps["getHierarchyDefinition"] = ({ imodelAccess }) => {
   // create a hierarchy definition that defines what should be shown in the tree
   // see https://github.com/iTwin/presentation/blob/master/packages/hierarchies/README.md#hierarchy-definition
+  const nodesQueryFactory = createNodesQueryClauseFactory({ imodelAccess });
+  const labelsQueryFactory = createBisInstanceLabelSelectClauseFactory({ classHierarchyInspector: imodelAccess });
+  return createClassBasedHierarchyDefinition({
+    classHierarchyInspector: imodelAccess,
+    hierarchy: {
+      // For root nodes, select all BisCore.GeometricModel3d instances
+      rootNodes: async () => [
+        {
+          fullClassName: "BisCore.GeometricModel3d",
+          query: {
+            ecsql: `
+              SELECT
+                ${await nodesQueryFactory.createSelectClause({
+                  ecClassId: { selector: "this.ECClassId" },
+                  ecInstanceId: { selector: "this.ECInstanceId" },
+                  nodeLabel: {
+                    selector: await labelsQueryFactory.createSelectClause({ classAlias: "this", className: "BisCore.GeometricModel3d" }),
+                  },
+                })}
+              FROM BisCore.GeometricModel3d this
+            `,
+          },
+        },
+      ],
+      childNodes: [],
+    },
+  });
+};
+
+interface MyTreeProps {
+  imodel: IModelConnection;
 }
 
 function MyTree({ imodel }: MyTreeProps) {
-  return <Tree
-    treeName="MyTree"
-    imodel={imodel}
-    selectionStorage={getUnifiedSelectionStorage()}
-    getSchemaContext={getSchemaContext}
-    getHierarchyDefinition={getHierarchyDefinition}
-    treeRenderer={(props) => <TreeRenderer {...props} />}
-  />;
+  return (
+    <Tree
+      treeName="MyTree"
+      imodel={imodel}
+      selectionStorage={unifiedSelectionStorage}
+      getSchemaContext={getSchemaContext}
+      getHierarchyDefinition={getHierarchyDefinition}
+      treeRenderer={(props) => <TreeRenderer {...props} />}
+    />
+  );
 }
 ```
 
+<!-- END EXTRACTION -->
+
 #### Custom visibility tree
 
 A visibility tree is a tree that renders the hierarchy and allows controlling visibility control through the use of "eye" checkboxes - see [Models](#models-tree) and [Categories](#categories-tree) trees. Core components:
@@ -416,34 +484,56 @@ A visibility tree is a tree that renders the hierarchy and allows controlling vi
 
 Example:
 
+<!-- [[include: [TreeWidget.CustomVisibilityTreeExampleImports, TreeWidget.CustomVisibilityTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```tsx
-import { ComponentPropsWithoutRef } from "react";
 import { BeEvent } from "@itwin/core-bentley";
-import { IModelConnection } from "@itwin/core-frontend";
-import { SchemaContext } from "@itwin/ecschema-metadata";
-import { SelectionStorage } from "@itwin/unified-selection";
 import { VisibilityTree, VisibilityTreeRenderer } from "@itwin/tree-widget-react";
-
-
-function getUnifiedSelectionStorage(): SelectionStorage {
-  // see "Creating unified selection storage" section for example implementation
-}
-
-function getSchemaContext(imodel: IModelConnection): SchemaContext {
-  // see "Creating schema context" section for example implementation
-}
+import { createClassBasedHierarchyDefinition, createNodesQueryClauseFactory } from "@itwin/presentation-hierarchies";
+import { createBisInstanceLabelSelectClauseFactory } from "@itwin/presentation-shared";
+import type { ComponentPropsWithoutRef } from "react";
+import type { IModelConnection } from "@itwin/core-frontend";
 
 type VisibilityTreeProps = ComponentPropsWithoutRef<typeof VisibilityTree>;
 const getHierarchyDefinition: VisibilityTreeProps["getHierarchyDefinition"] = ({ imodelAccess }) => {
   // create a hierarchy definition that defines what should be shown in the tree
   // see https://github.com/iTwin/presentation/blob/master/packages/hierarchies/README.md#hierarchy-definition
-}
+  const nodesQueryFactory = createNodesQueryClauseFactory({ imodelAccess });
+  const labelsQueryFactory = createBisInstanceLabelSelectClauseFactory({ classHierarchyInspector: imodelAccess });
+  return createClassBasedHierarchyDefinition({
+    classHierarchyInspector: imodelAccess,
+    hierarchy: {
+      // For root nodes, select all BisCore.GeometricModel3d instances
+      rootNodes: async () => [
+        {
+          fullClassName: "BisCore.GeometricModel3d",
+          query: {
+            ecsql: `
+              SELECT
+                ${await nodesQueryFactory.createSelectClause({
+                  ecClassId: { selector: "this.ECClassId" },
+                  ecInstanceId: { selector: "this.ECInstanceId" },
+                  nodeLabel: {
+                    selector: await labelsQueryFactory.createSelectClause({ classAlias: "this", className: "BisCore.GeometricModel3d" }),
+                  },
+                })}
+              FROM BisCore.GeometricModel3d this
+            `,
+          },
+        },
+      ],
+      childNodes: [],
+    },
+  });
+};
 
-const visibilityHandlerFactory: VisibilityTreeProps["visibilityHandlerFactory"] = ({ imodelAccess }) => {
+const visibilityHandlerFactory: VisibilityTreeProps["visibilityHandlerFactory"] = () => {
   return {
     // event that can be used to notify tree when visibility of instances represented by tree nodes changes from outside.
     onVisibilityChange: new BeEvent(),
     async getVisibilityStatus(node: HierarchyNode): Promise<VisibilityStatus> {
+      return { state: "visible" };
       // determine visibility status of the instance represented by tree node.
     },
     async changeVisibility(node: HierarchyNode, on: boolean): Promise<void> {
@@ -453,21 +543,29 @@ const visibilityHandlerFactory: VisibilityTreeProps["visibilityHandlerFactory"]
       // if necessary, do some clean up before new visibility handler is created or component is unmounted.
     },
   };
+};
+
+interface MyVisibilityTreeProps {
+  imodel: IModelConnection;
 }
 
 function MyVisibilityTree({ imodel }: MyVisibilityTreeProps) {
-  return <VisibilityTree
-    treeName="MyVisibilityTree"
-    imodel={imodel}
-    selectionStorage={getUnifiedSelectionStorage()}
-    getSchemaContext={getSchemaContext}
-    getHierarchyDefinition={getHierarchyDefinition}
-    visibilityHandlerFactory={visibilityFactory}
-    treeRenderer={(props) => <VisibilityTreeRenderer {...props} />}
-  />;
+  return (
+    <VisibilityTree
+      treeName="MyVisibilityTree"
+      imodel={imodel}
+      selectionStorage={unifiedSelectionStorage}
+      getSchemaContext={getSchemaContext}
+      getHierarchyDefinition={getHierarchyDefinition}
+      visibilityHandlerFactory={visibilityHandlerFactory}
+      treeRenderer={(props) => <VisibilityTreeRenderer {...props} />}
+    />
+  );
 }
 ```
 
+<!-- END EXTRACTION -->
+
 ### Hierarchy level size limiting
 
 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.
@@ -488,9 +586,13 @@ Tree components that support selection synchronization, require a unified select
 
 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
+<!-- [[include: [TreeWidget.SelectionStorageExampleImports, TreeWidget.SelectionStorageExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
+```tsx
 import { IModelConnection } from "@itwin/core-frontend";
-import { createStorage, SelectionStorage } from "@itwin/unified-selection";
+import { createStorage } from "@itwin/unified-selection";
+import type { SelectionStorage } from "@itwin/unified-selection";
 
 let unifiedSelectionStorage: SelectionStorage | undefined;
 function getUnifiedSelectionStorage(): SelectionStorage {
@@ -504,28 +606,34 @@ function getUnifiedSelectionStorage(): SelectionStorage {
 }
 ```
 
-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.:
+<!-- END EXTRACTION -->
+
+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 [`initialize`](https://www.itwinjs.org/reference/presentation-frontend/core/presentation/initializestatic/) function, e.g.:
 
-```ts
+<!-- [[include: [TreeWidget.SelectionStorageInitializeExampleImports, TreeWidget.SelectionStorageInitializeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
+```tsx
 import { Presentation } from "@itwin/presentation-frontend";
 
-Presentation.initialize({
-  selection: {
-    selectionStorage: getUnifiedSelectionStorage(),
-  },
-});
+await Presentation.initialize({ selection: { selectionStorage: getUnifiedSelectionStorage() } });
 ```
 
+<!-- END EXTRACTION -->
+
 ### 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";
+<!-- [[include: [TreeWidget.GetSchemaContextExampleImports, TreeWidget.GetSchemaContextExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
+```tsx
 import { SchemaContext } from "@itwin/ecschema-metadata";
 import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
+import type { IModelConnection } from "@itwin/core-frontend";
 
 const schemaContextCache = new Map<string, SchemaContext>();
 function getSchemaContext(imodel: IModelConnection) {
@@ -542,13 +650,15 @@ function getSchemaContext(imodel: IModelConnection) {
 }
 ```
 
+<!-- END EXTRACTION -->
+
 ## 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:
+This can be achieved by passing `onPerformanceMeasured` function to `CategoriesTreeComponent`, `ModelsTreeComponent`, `IModelContentTreeComponent`. 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.
@@ -560,7 +670,7 @@ Where `{tree}` specifies which tree component the feature is of.
 
 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:
+This can be achieved by passing `onFeatureUsed` function to `CategoriesTreeComponent`, `ModelsTreeComponent`, `IModelContentTreeComponent`. 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. This includes any kind of interaction with nodes, including them being expanded/collapsed, selected, filtered, their visibility change, etc.
@@ -585,62 +695,70 @@ Where `{tree}` specifies which tree component the feature is of.
 
 ### Example
 
-```ts
-import { UiItemsManager } from "@itwin/appui-react";
-import { TreeWidgetUiItemsProvider } from "@itwin/tree-widget-react";
-
-UiItemsManager.register(
-  new TreeWidgetUiItemsProvider({
-    onPerformanceMeasured={(feature, elapsedTime) => {
-      telemetryClient.log(`TreeWidget [${feature}] took ${elapsedTime} ms`);
-    }},
-    onFeatureUsed={(feature) => {
-      telemetryClient.log(`TreeWidget [${feature}] used`);
-    }},
-  })
-);
-```
-
 For individual tree components the callbacks should be supplied through props:
 
+<!-- [[include: [TreeWidget.TelemetryTreeComponentExampleImports, TreeWidget.TelemetryTreeComponentExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```tsx
-import { ModelsTreeComponent } from "@itwin/tree-widget-react";
+import { IModelContentTreeComponent } from "@itwin/tree-widget-react";
 
 function MyWidget() {
   return (
-    <ModelsTreeComponent
-      {...otherProps}
+    <IModelContentTreeComponent
       onPerformanceMeasured={(feature, elapsedTime) => {
-        console.log(`TreeWidget [${feature}] took ${elapsedTime} ms`)
+        console.log(`TreeWidget [${feature}] took ${elapsedTime} ms`);
       }}
       onFeatureUsed={(feature) => {
-        console.log(`TreeWidget [${feature}] used`)
+        console.log(`TreeWidget [${feature}] used`);
       }}
+      getSchemaContext={getSchemaContext}
+      selectionStorage={unifiedSelectionStorage}
     />
   );
 }
 ```
 
+<!-- END EXTRACTION -->
+
 For custom tree components `TelemetryContextProvider` should be used:
 
+<!-- [[include: [TreeWidget.TelemetryCustomTreeExampleImports, TreeWidget.TelemetryCustomTreeExample], tsx]] -->
+<!-- BEGIN EXTRACTION -->
+
 ```tsx
-import { TelemetryContextProvider } from "@itwin/tree-widget-react";
+import { TelemetryContextProvider, useCategoriesTree, VisibilityTree, VisibilityTreeRenderer } from "@itwin/tree-widget-react";
 
 function MyWidget() {
-  return <TelemetryContextProvider
-    componentIdentifier="MyTree"
-    onPerformanceMeasured={(feature, elapsedTime) => {
-      console.log(`TreeWidget [${feature}] took ${elapsedTime} ms`)
-    }}
-    onFeatureUsed={(feature) => {
-      console.log(`TreeWidget [${feature}] used`)
-    }}
-  >
-    <MyTree />
-  </TelemetryContextProvider>;
+  return (
+    <TelemetryContextProvider
+      componentIdentifier="MyTree"
+      onPerformanceMeasured={(feature, elapsedTime) => {
+        console.log(`TreeWidget [${feature}] took ${elapsedTime} ms`);
+      }}
+      onFeatureUsed={(feature) => {
+        console.log(`TreeWidget [${feature}] used`);
+      }}
+    >
+      <MyTree />
+    </TelemetryContextProvider>
+  );
 }
 
 function MyTree() {
-  // see "Custom trees" section for example implementation
+  const { categoriesTreeProps, rendererProps } = useCategoriesTree({ activeView: viewport, filter: "" });
+  return (
+    // VisibilityTree will use provided telemetry context to report used features and their performance
+    <VisibilityTree
+      {...categoriesTreeProps}
+      getSchemaContext={getSchemaContext}
+      selectionStorage={unifiedSelectionStorage}
+      imodel={imodel}
+      treeRenderer={(props) => <VisibilityTreeRenderer {...props} {...rendererProps} />}
+    />
+  );
+  // see "Custom trees" section for more example implementations
 }
 ```
+
+<!-- END EXTRACTION -->