@itwin/presentation-hierarchies-react 2.0.0-alpha.6 → 2.0.0-alpha.60

package/README.md

@@ -2,7 +2,16 @@
 
 Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.
 
-The `@itwin/presentation-hierarchies-react` package provides APIs for building a headless UI for rendering tree components based on data in an [iTwin.js iModel](https://www.itwinjs.org/learning/imodels/#imodel-overview). In addition, it delivers a set of [iTwinUI](https://itwinui.bentley.com/)-based components for rendering the tree.
+The `@itwin/presentation-hierarchies-react` package provides APIs for building a headless UI for rendering tree components based on data in an [iTwin.js iModel](https://www.itwinjs.org/learning/imodels/#imodel-overview). In addition, it delivers a set of [StrataKit](https://www.npmjs.com/package/@stratakit/bricks)-based components for rendering the tree.
+
+## Entry points
+
+Because StrataKit packages are optional peer dependencies, the package exposes two entry points:
+
+| Entry point                                       | Requires StrataKit peer dependencies | Description                                                                                                       |
+| ------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `@itwin/presentation-hierarchies-react`           | ❌                                   | Core API - headless hooks and utilities, including localization helpers.                                          |
+| `@itwin/presentation-hierarchies-react/stratakit` | ✔️                                   | StrataKit-based components and actions (`StrataKitTreeRenderer`, `TreeNodeFilterAction`, `TreeNodeRenameAction`). |
 
 ## Headless UI
 
@@ -15,30 +24,22 @@ The package provides different flavors of the same hook for creating and managin
 | 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.
+All these hooks return a `UseTreeResult` object with top-level properties and two optional renderer prop bags:
 
-- `getNode` function to get node by its id.
+- `isReloading` is a boolean that is `true` while the tree is being reloaded (does not apply to the initial load).
 
-- `getHierarchyLevelDetails` function to access details of a specific hierarchy level. The returned object provides access to:
+- `getNode` function to get a tree node by its id.
 
-  - hierarchy level size limit,
-  - hierarchy level instance filter,
-  - instance keys of the nodes in the hierarchy level.
+- `setFormatter` function to set the active node label formatter.
 
-- `reloadTree` function to reload part of the tree, optionally keeping its state.
+- `rootErrorRendererProps` is defined (and `treeRendererProps` is `undefined`) when root nodes fail to load. Pass it directly to `StrataKitRootErrorRenderer` or use it to build a custom error UI.
 
-- `setFormatter` function to set active node label formatter.
+- `treeRendererProps` is defined once root nodes have loaded successfully. It is `undefined` during the initial load. Pass it directly to `StrataKitTreeRenderer` or use it to build a custom tree renderer. It contains:
+  - `rootNodes` — array of `TreeNode` items to render.
+  - `expandNode` — function to expand or collapse a node.
+  - `isNodeSelected` and `selectNodes` — functions to inspect and change tree selection.
+  - `getHierarchyLevelDetails` — function to get details of a specific hierarchy level (size limit, instance filter, instance key iterator).
+  - `reloadTree` — function to reload part of the tree, optionally keeping its state.
 
 #### `useTree` props
 
@@ -61,31 +62,16 @@ The hook takes 2 required properties:
 
   ```tsx
   import { IModelConnection } from "@itwin/core-frontend";
-  import { SchemaContext } from "@itwin/ecschema-metadata";
-  import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
   import { createCachingECClassHierarchyInspector } from "@itwin/presentation-shared";
   import { createECSchemaProvider, createECSqlQueryExecutor, createIModelKey } from "@itwin/presentation-core-interop";
-  import { createLimitingECSqlQueryExecutor, createNodesQueryClauseFactory, HierarchyDefinition } from "@itwin/presentation-hierarchies";
-
-  // Not really part of the package, but we need SchemaContext to create the tree state. It's
-  // recommended to cache the schema context and reuse it across different application's components to
-  // avoid loading and storing same schemas multiple times.
-  const imodelSchemaContextsCache = new Map<string, SchemaContext>();
-
-  function getIModelSchemaContext(imodel: IModelConnection) {
-    const imodelKey = createIModelKey(imodel);
-    let context = imodelSchemaContextsCache.get(imodelKey);
-    if (!context) {
-      context = new SchemaContext();
-      context.addLocater(new ECSchemaRpcLocater(imodel.getRpcProps()));
-      imodelSchemaContextsCache.set(imodelKey, context);
-      imodel.onClose.addListener(() => imodelSchemaContextsCache.delete(imodelKey));
-    }
-    return context;
-  }
+  import {
+    createLimitingECSqlQueryExecutor,
+    createNodesQueryClauseFactory,
+    HierarchyDefinition,
+  } from "@itwin/presentation-hierarchies";
 
   function createIModelAccess(imodel: IModelConnection) {
-    const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
+    const schemaProvider = createECSchemaProvider(imodel.schemaContext);
     return {
       imodelKey: createIModelKey(imodel),
       ...schemaProvider,
@@ -107,78 +93,35 @@ In addition to [props required by `useIModelTree`](#useimodeltree-props), the ho
 - `selectionStorage` - unified selection storage used across different app's components, allowing them all to share selection state.
 - `sourceName` - a string that distinguishes selection changes being made by different components. The value should be unique for each component.
 
-### `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.
+## StrataKit components
 
-## iTwinUI components
+While the package provides a headless UI, it also delivers a set of [StrataKit](https://www.npmjs.com/package/@stratakit/bricks)-based components for rendering the tree, which should cover majority of use cases. Consumers using the below components are required to provide compatible `@stratakit/bricks`/`@stratakit/icons`/`@stratakit/foundations` packages, which are optional peer dependencies to this package.
 
-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.
+### `StrataKitTreeRenderer`
 
-### `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-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.
-
-### `TreeNodeRenderer`
-
-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-hook).
-- Icons, selection, expand / collapse.
-- Action buttons to clear / set hierarchy level instance filter.
+The component renders a virtualized tree using the `Tree` component from `@stratakit/structures`. It handles node selection modes, error display, and virtualized scrolling. It accepts a required `treeLabel` prop (used for accessibility) and spreads `treeRendererProps` returned by the tree state hooks.
 
 ## Full example
 
 ```tsx
 import { IModelConnection } from "@itwin/core-frontend";
-import { SchemaContext } from "@itwin/ecschema-metadata";
-import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
 import { createCachingECClassHierarchyInspector } from "@itwin/presentation-shared";
 import { createECSchemaProvider, createECSqlQueryExecutor, createIModelKey } from "@itwin/presentation-core-interop";
-import { createLimitingECSqlQueryExecutor, createNodesQueryClauseFactory, HierarchyDefinition } from "@itwin/presentation-hierarchies";
+import {
+  createLimitingECSqlQueryExecutor,
+  createNodesQueryClauseFactory,
+  HierarchyDefinition,
+} from "@itwin/presentation-hierarchies";
 
 import { createBisInstanceLabelSelectClauseFactory, Props } from "@itwin/presentation-shared";
 
-import { TreeRenderer, useIModelUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
+import { useIModelUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
+import { StrataKitTreeRenderer, StrataKitRootErrorRenderer } from "@itwin/presentation-hierarchies-react/stratakit";
 import { createStorage, SelectionStorage } from "@itwin/unified-selection";
 import { useEffect, useState } from "react";
 
-// Not really part of the package, but we need SchemaContext to create the tree state. It's
-// recommended to cache the schema context and reuse it across different application's components to
-// avoid loading and storing same schemas multiple times.
-const imodelSchemaContextsCache = new Map<string, SchemaContext>();
-
-function getIModelSchemaContext(imodel: IModelConnection) {
-  const imodelKey = createIModelKey(imodel);
-  let context = imodelSchemaContextsCache.get(imodelKey);
-  if (!context) {
-    context = new SchemaContext();
-    context.addLocater(new ECSchemaRpcLocater(imodel.getRpcProps()));
-    imodelSchemaContextsCache.set(imodelKey, context);
-    imodel.onClose.addListener(() => imodelSchemaContextsCache.delete(imodelKey));
-  }
-  return context;
-}
-
 function createIModelAccess(imodel: IModelConnection) {
-  const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
+  const schemaProvider = createECSchemaProvider(imodel.schemaContext);
   return {
     imodelKey: createIModelKey(imodel),
     ...schemaProvider,
@@ -214,7 +157,10 @@ function getHierarchyDefinition({ imodelAccess }: { imodelAccess: 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 });
+  const nodesQueryFactory = createNodesQueryClauseFactory({
+    imodelAccess,
+    instanceLabelSelectClauseFactory: labelsQueryFactory,
+  });
   return {
     defineHierarchyLevel: async () => [
       {
@@ -226,7 +172,10 @@ function getHierarchyDefinition({ imodelAccess }: { imodelAccess: IModelAccess }
                 ecClassId: { selector: "this.ECClassId" },
                 ecInstanceId: { selector: "this.ECInstanceId" },
                 nodeLabel: {
-                  selector: await labelsQueryFactory.createSelectClause({ classAlias: "this", className: "BisCore.PhysicalModel" }),
+                  selector: await labelsQueryFactory.createSelectClause({
+                    classAlias: "this",
+                    className: "BisCore.PhysicalModel",
+                  }),
                 },
                 hasChildren: false,
               })}
@@ -239,8 +188,14 @@ function getHierarchyDefinition({ imodelAccess }: { imodelAccess: IModelAccess }
 }
 
 /** Internal component that creates and renders tree state. */
-function MyTreeComponentInternal({ imodelAccess, selectionStorage }: { imodelAccess: IModelAccess; selectionStorage: SelectionStorage }) {
-  const { rootNodes, setFormatter, isLoading, ...state } = useIModelUnifiedSelectionTree({
+function MyTreeComponentInternal({
+  imodelAccess,
+  selectionStorage,
+}: {
+  imodelAccess: IModelAccess;
+  selectionStorage: SelectionStorage;
+}) {
+  const treeProps = useIModelUnifiedSelectionTree({
     // the unified selection storage used by all app components let them share selection state
     selectionStorage,
     // the source name is used to distinguish selection changes being made by different components
@@ -250,85 +205,63 @@ function MyTreeComponentInternal({ imodelAccess, selectionStorage }: { imodelAcc
     // supply the hierarchy definition
     getHierarchyDefinition,
   });
-  if (!rootNodes) {
+
+  if (treeProps.rootErrorRendererProps) {
+    // render error component if tree fails to load
+    return <StrataKitRootErrorRenderer {...treeProps.rootErrorRendererProps} />;
+  }
+
+  if (treeProps.isReloading || treeProps.treeRendererProps === undefined) {
     return "Loading...";
   }
-  return <TreeRenderer {...state} rootNodes={rootNodes} />;
+
+  return <StrataKitTreeRenderer {...treeProps.treeRendererProps} treeLabel="My Tree" />;
 }
 ```
 
 ## Localization
 
-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:
+This package delivers a locale JSON file with English strings that follows the [`i18next JSON format`](https://www.i18next.com/misc/json-format). To enable localization, register `LOCALIZATION_NAMESPACES` during initialization and wrap components in `LocalizationContextProvider`:
 
 ```tsx
-import { Props } from "@itwin/presentation-shared";
-
-import { useIModelUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
+import {
+  LocalizationContextProvider,
+  LOCALIZATION_NAMESPACES,
+  useIModelUnifiedSelectionTree,
+} from "@itwin/presentation-hierarchies-react";
+import { StrataKitTreeRenderer } from "@itwin/presentation-hierarchies-react/stratakit";
 
-type IModelAccess = Props<typeof useIModelUnifiedSelectionTree>["imodelAccess"];
+// Register localization namespaces with `i18next` based localization provider.
+for (const namespace of LOCALIZATION_NAMESPACES) {
+  await localization.registerNamespace(namespace);
+}
 
-const localizedStrings = {
-  // strings for the `useIModelUnifiedSelectionTree` hook
-  unspecified: "Unspecified",
-  other: "Other",
-
-  // strings for `TreeRenderer` and `TreeNodeRenderPresentation.HierarchiesReact.iModelAccesser`
-  loading: "Loading...",
-  filterHierarchyLevel: "Apply hierarchy filter",
-  clearHierarchyLevelFilter: "Clear active filter",
-  noFilteredChildren: "No child nodes match current filter",
-  resultLimitExceeded: "There are more items than allowed limit of {{limit}}.",
-  resultLimitExceededWithFiltering: "Please provide <link>additional filtering</link> - there are more items than allowed limit of {{limit}}.",
-  increaseHierarchyLimit: "<link>Increase the hierarchy level size limit to {{limit}}.</link>",
-  increaseHierarchyLimitWithFiltering: "Or, <link>increase the hierarchy level size limit to {{limit}}.</link>",
-};
+// Wrap components with LocalizationContextProvider
+function Tree() {
+  return (
+    <LocalizationContextProvider localization={localization}>
+      <MyTreeComponent imodelAccess={imodelAccess} />
+    </LocalizationContextProvider>
+  );
+}
 
 function MyTreeComponent({ imodelAccess }: { imodelAccess: IModelAccess }) {
-  const { rootNodes, expandNode } = useIModelUnifiedSelectionTree({
+  const treeProps = useIModelUnifiedSelectionTree({
     sourceName: "MyTreeComponent",
     imodelAccess,
-    localizedStrings,
     getHierarchyDefinition,
   });
-  if (!rootNodes) {
-    return localizedStrings.loading;
-  }
-  return <TreeRenderer rootNodes={rootNodes} expandNode={expandNode} localizedStrings={localizedStrings} onFilterClick={() => {}} />;
-}
-```
-
-In case the `TreeNodeRenderer` component is used within a custom tree renderer, the tree component should supply localized strings through `LocalizationContextProvider`:
-
-```tsx
-import { Props } from "@itwin/presentation-shared";
-
-import { ComponentPropsWithoutRef, useCallback } from "react";
-import { Tree } from "@itwin/itwinui-react";
-import {
-  createRenderedTreeNodeData,
-  LocalizationContextProvider,
-  RenderedTreeNode,
-  TreeNodeRenderer,
-  TreeRenderer,
-} from "@itwin/presentation-hierarchies-react";
 
-type TreeProps = ComponentPropsWithoutRef<typeof Tree<RenderedTreeNode>>;
-type TreeRendererProps = Props<typeof TreeRenderer>;
-
-function MyTreeRenderer({ rootNodes }: TreeRendererProps) {
-  const nodeRenderer = useCallback<TreeProps["nodeRenderer"]>((nodeProps) => {
-    return <TreeNodeRenderer {...nodeProps} onFilterClick={() => {}} expandNode={() => {}} />;
-  }, []);
+  if (treeProps.rootErrorRendererProps) {
+    return <div>Error</div>;
+  }
 
-  const getNode = useCallback<TreeProps["getNode"]>((node) => createRenderedTreeNodeData(node, () => false), []);
+  if (treeProps.isReloading || treeProps.treeRendererProps === undefined) {
+    return <div>Loading...</div>;
+  }
 
-  return (
-    <LocalizationContextProvider localizedStrings={localizedStrings}>
-      <Tree<RenderedTreeNode> data={rootNodes} nodeRenderer={nodeRenderer} getNode={getNode} enableVirtualization={true} />
-    </LocalizationContextProvider>
-  );
+  return <StrataKitTreeRenderer {...treeProps.treeRendererProps} treeLabel="My Tree" />;
 }
 ```
+
+`LocalizationContextProvider` accepts a `localization` prop — an object with a `getLocalizedString(key: string): string` method. It is designed to work with the `Localization` interface from `@itwin/core-common`, but a custom implementation can be used as well by providing an object with a custom `getLocalizedString` function. The provider uses it internally to resolve translation keys prefixed with localization namespace.

package/lib/presentation-hierarchies-react/FlatTreeNode.d.ts

@@ -0,0 +1,49 @@
+import { TreeNode } from "./TreeNode.js";
+
+//#region src/presentation-hierarchies-react/FlatTreeNode.d.ts
+/**
+ * Placeholder item that is added to hierarchy as a child for a parent item while its child items are loading.
+ *
+ * @alpha
+ */
+interface FlatPlaceholderItem {
+  id: string;
+  level: number;
+  placeholder: true;
+}
+/**
+ * An item containing `TreeNode` node with properties needed for a flat tree structure.
+ *
+ * @alpha
+ */
+interface FlatTreeNodeItem {
+  id: string;
+  level: number;
+  levelSize: number;
+  posInLevel: number;
+  node: TreeNode;
+}
+/**
+ * An Item describing single tree item position and its content inside tree.
+ * Returned by `useFlatTreeNodeList` hook.
+ *
+ *  @alpha
+ */
+type FlatTreeItem = FlatTreeNodeItem | FlatPlaceholderItem;
+/**
+ * Used to get a list of `FlatTreeItem` objects for the given list of `TreeNode` objects that represent
+ * a hierarchical structure. The resulting items can be used to render the hierarchy in a flat manner, e.g. using a
+ * virtualized list.
+ *
+ * @alpha
+ */
+declare function useFlatTreeItems(rootNodes: TreeNode[]): FlatTreeItem[];
+/**
+ * Finds and returns all nodes containing errors in a given hierarchy.
+ *
+ * @alpha
+ */
+declare function useErrorNodes(rootNodes: TreeNode[]): Array<TreeNode & Pick<Required<TreeNode>, "error">>;
+//#endregion
+export { FlatTreeItem, useErrorNodes, useFlatTreeItems };
+//# sourceMappingURL=FlatTreeNode.d.ts.map

package/lib/presentation-hierarchies-react/FlatTreeNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlatTreeNode.d.ts","names":[],"sources":["../../src/presentation-hierarchies-react/FlatTreeNode.ts"],"mappings":";;;;;AAO8C;;;UAOpC,mBAAA;EACR,EAAA;EACA,KAAA;EACA,WAAA;AAAA;;AAQF;;;;UAAiB,gBAAA;EACf,EAAA;EACA,KAAA;EACA,SAAA;EACA,UAAA;EACA,IAAA,EAAM,QAAA;AAAA;;AASR;;;;;KAAY,YAAA,GAAe,gBAAA,GAAmB,mBAAA;;;;;;;AAkD9C;iBApCgB,gBAAA,CAAiB,SAAA,EAAW,QAAA,KAAU,YAAA;;;;;;iBAoCtC,aAAA,CAAc,SAAA,EAAW,QAAA,KAAa,KAAA,CAAM,QAAA,GAAW,IAAA,CAAK,QAAA,CAAS,QAAA"}

package/lib/presentation-hierarchies-react/FlatTreeNode.js

@@ -0,0 +1,93 @@
+import { c } from "react-compiler-runtime";
+//#region src/presentation-hierarchies-react/FlatTreeNode.ts
+/** @alpha */
+function isPlaceholderItem(item) {
+	return "placeholder" in item;
+}
+/**
+* Used to get a list of `FlatTreeItem` objects for the given list of `TreeNode` objects that represent
+* a hierarchical structure. The resulting items can be used to render the hierarchy in a flat manner, e.g. using a
+* virtualized list.
+*
+* @alpha
+*/
+function useFlatTreeItems(rootNodes) {
+	const $ = c(2);
+	let t0;
+	if ($[0] !== rootNodes) {
+		t0 = getFlatItems(rootNodes, 1);
+		$[0] = rootNodes;
+		$[1] = t0;
+	} else t0 = $[1];
+	return t0;
+}
+function getFlatItems(nodes, level) {
+	const flatItems = [];
+	nodes.forEach((node, index) => {
+		flatItems.push({
+			node,
+			id: node.id,
+			level,
+			levelSize: nodes.length,
+			posInLevel: index + 1
+		});
+		if (!node.isExpanded) return;
+		if (node.error && (node.error.type !== "Unknown" || !node.error.isNodeExpandable)) return;
+		if (node.children !== true) {
+			const childNodes = getFlatItems(node.children, level + 1);
+			flatItems.push(...childNodes);
+			return;
+		}
+		flatItems.push({
+			id: `${node.id}-children-placeholder`,
+			level: level + 1,
+			placeholder: true
+		});
+	});
+	return flatItems;
+}
+/**
+* Finds and returns all nodes containing errors in a given hierarchy.
+*
+* @alpha
+*/
+function useErrorNodes(rootNodes) {
+	const $ = c(2);
+	let t0;
+	if ($[0] !== rootNodes) {
+		t0 = rootNodes.flatMap(_temp);
+		$[0] = rootNodes;
+		$[1] = t0;
+	} else t0 = $[1];
+	return t0;
+}
+function _temp(rootNode) {
+	const errors = isErrorNode(rootNode) ? [rootNode] : [];
+	if (rootNode.children === true) return errors;
+	if (errors.length === 1 && (rootNode.error?.type !== "Unknown" || !rootNode.error.isNodeExpandable)) return errors;
+	errors.push(...getErrorNodes(rootNode));
+	return errors;
+}
+function getErrorNodes(parent) {
+	const errorList = [];
+	if (parent.children === true) return [];
+	parent.children.forEach((node) => {
+		if (isErrorNode(node)) {
+			errorList.push(node);
+			if (node.error.type !== "Unknown" || !node.error.isNodeExpandable) return;
+		}
+		if (node.children !== true) {
+			const childErrorList = getErrorNodes(node);
+			errorList.push(...childErrorList);
+			return;
+		}
+	});
+	return errorList;
+}
+function isErrorNode(node) {
+	return node.error !== void 0;
+}
+//#endregion
+export { isPlaceholderItem, useErrorNodes, useFlatTreeItems };
+
+//# sourceMappingURL=FlatTreeNode.js.map

package/lib/presentation-hierarchies-react/FlatTreeNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlatTreeNode.js","names":["useMemo","TreeNode","FlatPlaceholderItem","id","level","placeholder","FlatTreeNodeItem","levelSize","posInLevel","node","FlatTreeItem","isPlaceholderItem","item","useFlatTreeItems","rootNodes","$","_c","t0","getFlatItems","nodes","flatItems","forEach","index","push","length","isExpanded","error","type","isNodeExpandable","children","childNodes","useErrorNodes","flatMap","_temp","rootNode","errors","isErrorNode","getErrorNodes","parent","errorList","ReturnType","childErrorList","Pick","Required","undefined"],"sources":["../../src/presentation-hierarchies-react/FlatTreeNode.ts"],"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 { useMemo } from \"react\";\n\nimport type { TreeNode } from \"./TreeNode.js\";\n\n/**\n * Placeholder item that is added to hierarchy as a child for a parent item while its child items are loading.\n *\n * @alpha\n */\ninterface FlatPlaceholderItem {\n  id: string;\n  level: number;\n  placeholder: true;\n}\n\n/**\n * An item containing `TreeNode` node with properties needed for a flat tree structure.\n *\n * @alpha\n */\nexport interface FlatTreeNodeItem {\n  id: string;\n  level: number;\n  levelSize: number;\n  posInLevel: number;\n  node: TreeNode;\n}\n\n/**\n * An Item describing single tree item position and its content inside tree.\n * Returned by `useFlatTreeNodeList` hook.\n *\n *  @alpha\n */\nexport type FlatTreeItem = FlatTreeNodeItem | FlatPlaceholderItem;\n\n/** @alpha */\nexport function isPlaceholderItem(item: FlatTreeItem): item is FlatPlaceholderItem {\n  return \"placeholder\" in item;\n}\n\n/**\n * Used to get a list of `FlatTreeItem` objects for the given list of `TreeNode` objects that represent\n * a hierarchical structure. The resulting items can be used to render the hierarchy in a flat manner, e.g. using a\n * virtualized list.\n *\n * @alpha\n */\nexport function useFlatTreeItems(rootNodes: TreeNode[]) {\n  return useMemo(() => getFlatItems(rootNodes, 1), [rootNodes]);\n}\n\nfunction getFlatItems(nodes: TreeNode[], level: number) {\n  const flatItems: FlatTreeItem[] = [];\n  nodes.forEach((node, index) => {\n    flatItems.push({ node, id: node.id, level, levelSize: nodes.length, posInLevel: index + 1 });\n    if (!node.isExpanded) {\n      return;\n    }\n\n    if (node.error && (node.error.type !== \"Unknown\" || !node.error.isNodeExpandable)) {\n      return;\n    }\n\n    if (node.children !== true) {\n      const childNodes = getFlatItems(node.children, level + 1);\n      flatItems.push(...childNodes);\n      return;\n    }\n\n    flatItems.push({\n      id: `${node.id}-children-placeholder`,\n      level: level + 1,\n      placeholder: true,\n    } satisfies FlatPlaceholderItem);\n  });\n  return flatItems;\n}\n\n/**\n * Finds and returns all nodes containing errors in a given hierarchy.\n *\n * @alpha\n */\nexport function useErrorNodes(rootNodes: TreeNode[]): Array<TreeNode & Pick<Required<TreeNode>, \"error\">> {\n  return useMemo(\n    () =>\n      rootNodes.flatMap((rootNode) => {\n        const errors = isErrorNode(rootNode) ? [rootNode] : [];\n        if (rootNode.children === true) {\n          return errors;\n        }\n\n        if (errors.length === 1 && (rootNode.error?.type !== \"Unknown\" || !rootNode.error.isNodeExpandable)) {\n          return errors;\n        }\n        errors.push(...getErrorNodes(rootNode));\n        return errors;\n      }),\n    [rootNodes],\n  );\n}\n\nfunction getErrorNodes(parent: TreeNode) {\n  const errorList: ReturnType<typeof useErrorNodes> = [];\n\n  if (parent.children === true) {\n    return [];\n  }\n\n  parent.children.forEach((node) => {\n    if (isErrorNode(node)) {\n      errorList.push(node);\n      if (node.error.type !== \"Unknown\" || !node.error.isNodeExpandable) {\n        return;\n      }\n    }\n\n    if (node.children !== true) {\n      const childErrorList = getErrorNodes(node);\n      errorList.push(...childErrorList);\n      return;\n    }\n  });\n  return errorList;\n}\n\nfunction isErrorNode(node: TreeNode): node is TreeNode & Pick<Required<TreeNode>, \"error\"> {\n  return node.error !== undefined;\n}\n"],"mappings":";;;AA0CA,SAAgBW,kBAAkBC,MAAiD;AACjF,QAAO,iBAAiBA;;;;;;;;;AAU1B,SAAOC,iBAAAC,WAAA;CAAA,MAAAC,IAAAC,EAAA,EAAA;CAAA,IAAAC;AAAA,KAAAF,EAAA,OAAAD,WAAA;AACgBG,OAAAC,aAAaJ,WAAW,EAAE;AAAAC,IAAA,KAAAD;AAAAC,IAAA,KAAAE;OAAAA,MAAAF,EAAA;AAAA,QAA1BE;;AAGvB,SAASC,aAAaC,OAAmBf,OAAe;CACtD,MAAMgB,YAA4B,EAAE;AACpCD,OAAME,SAASZ,MAAMa,UAAU;AAC7BF,YAAUG,KAAK;GAAEd;GAAMN,IAAIM,KAAKN;GAAIC;GAAOG,WAAWY,MAAMK;GAAQhB,YAAYc,QAAQ;GAAG,CAAC;AAC5F,MAAI,CAACb,KAAKgB,WACR;AAGF,MAAIhB,KAAKiB,UAAUjB,KAAKiB,MAAMC,SAAS,aAAa,CAAClB,KAAKiB,MAAME,kBAC9D;AAGF,MAAInB,KAAKoB,aAAa,MAAM;GAC1B,MAAMC,aAAaZ,aAAaT,KAAKoB,UAAUzB,QAAQ,EAAE;AACzDgB,aAAUG,KAAK,GAAGO,WAAW;AAC7B;;AAGFV,YAAUG,KAAK;GACbpB,IAAI,GAAGM,KAAKN,GAAE;GACdC,OAAOA,QAAQ;GACfC,aAAa;GACd,CAA+B;GAChC;AACF,QAAOe;;;;;;;AAQT,SAAOW,cAAAjB,WAAA;CAAA,MAAAC,IAAAC,EAAA,EAAA;CAAA,IAAAC;AAAA,KAAAF,EAAA,OAAAD,WAAA;AAGDG,OAAAH,UAASkB,QAASC,MAWhB;AAAAlB,IAAA,KAAAD;AAAAC,IAAA,KAAAE;OAAAA,MAAAF,EAAA;AAAA,QAXFE;;AAHC,SAAAgB,MAAAC,UAAA;CAIC,MAAAC,SAAeC,YAAYF,SAA2B,GAAvC,CAAyBA,SAAc,GAAvC,EAAuC;AACtD,KAAIA,SAAQL,aAAc,KAAI,QACrBM;AAGT,KAAIA,OAAMX,WAAY,MAAMU,SAAQR,OAAYC,SAAK,aAAzB,CAAuCO,SAAQR,MAAME,kBAAkB,QAC1FO;AAETA,QAAMZ,KAAK,GAAIc,cAAcH,SAAS,CAAC;AAAA,QAChCC;;AAMf,SAASE,cAAcC,QAAkB;CACvC,MAAMC,YAA8C,EAAE;AAEtD,KAAID,OAAOT,aAAa,KACtB,QAAO,EAAE;AAGXS,QAAOT,SAASR,SAASZ,SAAS;AAChC,MAAI2B,YAAY3B,KAAK,EAAE;AACrB8B,aAAUhB,KAAKd,KAAK;AACpB,OAAIA,KAAKiB,MAAMC,SAAS,aAAa,CAAClB,KAAKiB,MAAME,iBAC/C;;AAIJ,MAAInB,KAAKoB,aAAa,MAAM;GAC1B,MAAMY,iBAAiBJ,cAAc5B,KAAK;AAC1C8B,aAAUhB,KAAK,GAAGkB,eAAe;AACjC;;GAEF;AACF,QAAOF;;AAGT,SAASH,YAAY3B,MAAsE;AACzF,QAAOA,KAAKiB,UAAUkB,KAAAA"}

package/lib/presentation-hierarchies-react/LocalizationContext.d.ts

@@ -0,0 +1,24 @@
+import { JSX, PropsWithChildren } from "react";
+
+//#region src/presentation-hierarchies-react/LocalizationContext.d.ts
+/**
+ * Properties for `LocalizationContextProvider`.
+ * @public
+ */
+interface LocalizationContextProviderProps {
+  /** Localization object compatible with `@itwin/core-common` */
+  localization: {
+    getLocalizedString: (key: string) => string;
+  };
+}
+/**
+ * Context provider for localizing components.
+ * @public
+ */
+declare function LocalizationContextProvider({
+  localization,
+  children
+}: PropsWithChildren<LocalizationContextProviderProps>): JSX.Element;
+//#endregion
+export { LocalizationContextProvider };
+//# sourceMappingURL=LocalizationContext.d.ts.map

package/lib/presentation-hierarchies-react/LocalizationContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalizationContext.d.ts","names":[],"sources":["../../src/presentation-hierarchies-react/LocalizationContext.tsx"],"mappings":";;;AAW0C;;;;AAAA,UAQhC,gCAAA;EAEQ;EAAhB,YAAA;IAAgB,kBAAA,GAAqB,GAAA;EAAA;AAAA;;;;;iBAOvB,2BAAA,CAAA;EACd,YAAA;EACA;AAAA,GACC,iBAAA,CAAkB,gCAAA,IAAoC,GAAA,CAAI,OAAA"}

package/lib/presentation-hierarchies-react/LocalizationContext.js

@@ -0,0 +1,40 @@
+import { LOCALIZATION_NAMESPACE } from "./internal/LocalizedStrings.js";
+import { c } from "react-compiler-runtime";
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/presentation-hierarchies-react/LocalizationContext.tsx
+const localizationContext = createContext((key) => key);
+/**
+* Context provider for localizing components.
+* @public
+*/
+function LocalizationContextProvider(t0) {
+	const $ = c(5);
+	const { localization, children } = t0;
+	let t1;
+	if ($[0] !== localization) {
+		t1 = (key) => localization.getLocalizedString(`${LOCALIZATION_NAMESPACE}:${key}`);
+		$[0] = localization;
+		$[1] = t1;
+	} else t1 = $[1];
+	const translate = t1;
+	let t2;
+	if ($[2] !== children || $[3] !== translate) {
+		t2 = /* @__PURE__ */ jsx(localizationContext.Provider, {
+			value: translate,
+			children
+		});
+		$[2] = children;
+		$[3] = translate;
+		$[4] = t2;
+	} else t2 = $[4];
+	return t2;
+}
+/** @internal */
+function useTranslation() {
+	return useContext(localizationContext);
+}
+//#endregion
+export { LocalizationContextProvider, useTranslation };
+
+//# sourceMappingURL=LocalizationContext.js.map

package/lib/presentation-hierarchies-react/LocalizationContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalizationContext.js","names":["createContext","useContext","useMemo","LOCALIZATION_NAMESPACE","JSX","PropsWithChildren","LocalizationKey","TranslateFunc","key","localizationContext","LocalizationContextProviderProps","localization","getLocalizedString","LocalizationContextProvider","t0","$","_c","children","t1","translate","t2","useTranslation"],"sources":["../../src/presentation-hierarchies-react/LocalizationContext.tsx"],"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 { createContext, useContext, useMemo } from \"react\";\nimport { LOCALIZATION_NAMESPACE } from \"./internal/LocalizedStrings.js\";\n\nimport type { JSX, PropsWithChildren } from \"react\";\nimport type { LocalizationKey } from \"./internal/LocalizedStrings.js\";\n\ntype TranslateFunc = (key: LocalizationKey) => string;\n\nconst localizationContext = createContext<TranslateFunc>((key) => key);\n\n/**\n * Properties for `LocalizationContextProvider`.\n * @public\n */\ninterface LocalizationContextProviderProps {\n  /** Localization object compatible with `@itwin/core-common` */\n  localization: { getLocalizedString: (key: string) => string };\n}\n\n/**\n * Context provider for localizing components.\n * @public\n */\nexport function LocalizationContextProvider({\n  localization,\n  children,\n}: PropsWithChildren<LocalizationContextProviderProps>): JSX.Element {\n  const translate = useMemo<TranslateFunc>(() => {\n    return (key: LocalizationKey) => localization.getLocalizedString(`${LOCALIZATION_NAMESPACE}:${key}`);\n  }, [localization]);\n  return <localizationContext.Provider value={translate}>{children}</localizationContext.Provider>;\n}\n\n/** @internal */\nexport function useTranslation() {\n  return useContext(localizationContext);\n}\n"],"mappings":";;;;;AAaA,MAAMS,sBAAsBT,eAA8BQ,QAAQA,IAAI;;;;;AAetE,SAAOK,4BAAAC,IAAA;CAAA,MAAAC,IAAAC,EAAA,EAAA;CAAqC,MAAA,EAAAL,cAAAM,aAAAH;CAGU,IAAAI;AAAA,KAAAH,EAAA,OAAAJ,cAAA;AAE3CO,QAAAV,QAA0BG,aAAYC,mBAAoB,GAAGT,uBAAsB,GAAIK,MAAM;AAAAO,IAAA,KAAAJ;AAAAI,IAAA,KAAAG;OAAAA,MAAAH,EAAA;CADtG,MAAAI,YACED;CACiB,IAAAE;AAAA,KAAAL,EAAA,OAAAE,YAAAF,EAAA,OAAAI,WAAA;AACZC,OAAA,oBAAA,oBAAA,UAAA;GAAqCD,OAAAA;GAAYF;GAAwC,CAAA;AAAAF,IAAA,KAAAE;AAAAF,IAAA,KAAAI;AAAAJ,IAAA,KAAAK;OAAAA,MAAAL,EAAA;AAAA,QAAzFK;;;AAIT,SAAOC,iBAAA;AAAA,QACEpB,WAAWQ,oBAAoB"}