@itwin/presentation-hierarchies-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @itwin/presentation-hierarchies-react
+
+## 0.1.0
+
+### Minor Changes
+
+- [#587](https://github.com/iTwin/presentation/pull/587): Initial release.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @itwin/presentation-shared@0.2.0
+  - @itwin/unified-selection@0.4.2
+  - @itwin/presentation-hierarchies@0.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright © 2017-2024 Bentley Systems, Incorporated. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# @itwin/presentation-hierarchies-react
+
+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.
+
+## Headless UI
+
+### `useTree`
+
+This is a React hook that creates state for a tree component.
+
+It takes 2 required properties:
+
+- `imodelAccess` provides access to iModel's data and metadata, required to build the hierarchy. Generally, `@itwin/presentation-core-interop` and `@itwin/presentation-shared` packages are used to create this object:
+
+  ```tsx
+  import { IModelConnection } from "@itwin/core-frontend";
+  import { createECSchemaProvider, createECSqlQueryExecutor } from "@itwin/presentation-core-interop";
+  import { createLimitingECSqlQueryExecutor } from "@itwin/presentation-hierarchies";
+  import { createCachingECClassHierarchyInspector } from "@itwin/presentation-shared";
+
+  function createIModelAccess(imodel: IModelConnection) {
+    const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
+    return {
+      ...schemaProvider,
+      // while caching for hierarchy inspector is not mandatory, it's recommended to use it to improve performance
+      ...createCachingECClassHierarchyInspector({ schemaProvider, cacheSize: 100 }),
+      // the second argument is the maximum number of rows the executor will return - this allows us to
+      // avoid creating hierarchy levels of insane size (expensive to us and useless to users)
+      ...createLimitingECSqlQueryExecutor(createECSqlQueryExecutor(imodel), 1000),
+    };
+  }
+  ```
+
+- `getHierarchyDefinition` is a factory function that creates a hierarchy definition, describing the hierarchy the tree component will render. The `@itwin/presentation-hierarchies` package describes the concept of hierarchy definitions [in more detail](https://github.com/iTwin/presentation/blob/master/packages/hierarchies/README.md#hierarchy-definition).
+
+The resulting state object contains the following properties:
+
+- `isLoading` is a boolean indicating whether the root tree nodes are being loaded. Set to `true` on initial load and on reload (e.g. when iModel data changes).
+
+- `rootNodes` is an array of root tree nodes and is what the component should render. There are several types of nodes:
+
+  - A `PresentationHierarchyNode` is the primary type of node, created based on the hierarchy definition. The `isPresentationHierarchyNode` type guard utility may be used to check if a node is of this type.
+  - A `PresentationInfoNode` is a non-expandable, non-selectable informational type of node, generally created when for some reason we don't have any real nodes to show. There may be different reasons like filtered-out nodes, too large result set, a network error, etc. The `type` attribute of the node indicates that.
+
+- `expandNode` function to expand or collapse a node.
+
+- `isNodeSelected` and `selectNodes` function to inspect and change tree selection.
+
+- `getHierarchyLevelDetails` function to access details of a specific hierarchy level. The returned object provides access to:
+
+  - hierarchy level size limit,
+  - hierarchy level instance filter,
+  - instance keys of the nodes in the hierarchy level.
+
+- `reloadTree` function to reload the tree, optionally keeping its state, after an iModel data change.
+
+- `setFormatter` function to set active node label formatter.
+
+### `useSelectionHandler`
+
+This is React hook that helps implement different selection modes in tree, whose state is managed through the `useTree` or `useUnifiedSelectionTree` hooks.
+
+It takes 3 required properties:
+
+- `rootNodes` and `selectNodes` are the corresponding properties from the tree state object, created using `useTree` or `useUnifiedSelectionTree` hook.
+
+- `selectionMode` is a string that defines the selection mode. It can be one of the following values:
+  - `none` - no selection is allowed,
+  - `single` - only one node can be selected at a time,
+  - `extended` - multiple nodes can be selected using shift and ctrl keys,
+  - `multiple` - multiple nodes can be selected without using shift or ctrl keys.
+
+The returned object contains 2 functions, that should be called by the node renderer: `onNodeClick` and `onNodeKeyDown`.
+
+Our [tree renderer implementation](#treerenderer) calls this hook and passes the callbacks to the [node renderer](#treenoderenderer), so there's no need to use it unless implementing a custom tree renderer.
+
+### `useUnifiedSelectionTree` & `UnifiedSelectionProvider`
+
+The package delivers a variation of [`useTree`](#usetree), that automatically hooks tree selection into the [Unified Selection](https://www.itwinjs.org/learning/unified-selection/) system. It takes the same properties as [`useTree`](#usetree), plus a couple of additional ones:
+
+- `imodelKey` is a string that uniquely identifies the iModel the tree is associated with. It's used to distinguish selection changes between different iModels. Generally, the value is obtained using `IModelConnection.key` getter.
+
+- `sourceName` is a string that distinguishes selection changes being made by different components. It's used to avoid conflicts between different components that use the same iModel and the same selection storage. The value should be unique for each component.
+
+The returned result is identical to the one from [`useTree`](#usetree).
+
+The hook also relies on unified selection storage being provided to it through a React context. For that, the package delivers the `UnifiedSelectionProvider` component, that should wrap the tree component, using the `useUnifiedSelectionTree` hook:
+
+```tsx
+import { UnifiedSelectionProvider, useUnifiedSelectionTree } from "@itwin/presentation-hierarchies-react";
+import { createStorage } from "@itwin/unified-selection";
+
+// Unified selection storage should be created once per application and reused across components.
+const selectionStorage = createStorage();
+
+/** The top-level application component sets up the unified selection context. */
+function MyApplication(props: MyApplicationProps) {
+  return (
+    <UnifiedSelectionProvider storage={selectionStorage}>
+      <MyTreeComponent {...props} />
+    </UnifiedSelectionProvider>
+  );
+}
+
+/** The tree component calls `useUnifiedSelectionTree` that uses unified selection context. */
+function MyTreeComponent(props: MyTreeComponentProps) {
+  const state = useUnifiedSelectionTree(props);
+  return <MyTreeRenderer {...state} />;
+}
+```
+
+## iTwinUI components
+
+While the package provides a headless UI, it also delivers a set of [iTwinUI](https://itwinui.bentley.com/)-based components for rendering the tree, which should cover majority of use cases. Consumers using the below components are required to provide a compatible `@itwin/itwinui-react` package, which is an optional peer dependency to this package.
+
+### `TreeRenderer`
+
+The component is based on [iTwinUI Tree component](https://itwinui.bentley.com/docs/tree) and uses our [`TreeNodeRenderer`](#treenoderenderer) to render the nodes. In addition, it makes use of the [`useSelectionHandler` hook](#useselectionhandler) to add selection modes' support.
+
+The 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).
+- Icons, selection, expand / collapse.
+- Action buttons to clear / set hierarchy level instance filter.
+
+## Full example
+
+```tsx
+import { useEffect, useState } from "react";
+import { IModelConnection } from "@itwin/core-frontend";
+import { SchemaContext } from "@itwin/ecschema-metadata";
+import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
+import { createECSchemaProvider, createECSqlQueryExecutor } from "@itwin/presentation-core-interop";
+import { createLimitingECSqlQueryExecutor, createNodesQueryClauseFactory } from "@itwin/presentation-hierarchies";
+import {
+  isPresentationHierarchyNode,
+  PresentationTreeNode,
+  UnifiedSelectionProvider,
+  useUnifiedSelectionTree,
+  TreeRenderer,
+} from "@itwin/presentation-hierarchies-react";
+import { createBisInstanceLabelSelectClauseFactory, createCachingECClassHierarchyInspector } from "@itwin/presentation-shared";
+import { createStorage } from "@itwin/unified-selection";
+
+// 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) {
+  let context = imodelSchemaContextsCache.get(imodel.key);
+  if (!context) {
+    context = new SchemaContext();
+    context.addLocater(new ECSchemaRpcLocater(imodel.getRpcProps()));
+    imodelSchemaContextsCache.set(imodel.key, context);
+    imodel.onClose.addListener(() => imodelSchemaContextsCache.delete(imodel.key));
+  }
+  return context;
+}
+
+// Not part of the package - this should be created once and reused across different components of the application.
+const selectionStorage = createStorage();
+
+/** The top level component sets up access to the iModel and unified selection. */
+export function MyTreeComponent({ imodel }: { imodel: IModelConnection }) {
+  const [imodelAccess, setIModelAccess] = useState<IModelAccess>();
+  useEffect(() => {
+    const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
+    setIModelAccess({
+      ...schemaProvider,
+      // while caching for hierarchy inspector is not mandatory, it's recommended to use it to improve performance
+      ...createCachingECClassHierarchyInspector({ schemaProvider, cacheSize: 100 }),
+      // the second argument is the maximum number of rows the executor will return - this allows us to
+      // avoid creating hierarchy levels of insane size (expensive to us and useless to users)
+      ...createLimitingECSqlQueryExecutor(createECSqlQueryExecutor(imodel), 1000),
+    });
+  }, [imodel]);
+
+  if (!imodelAccess) {
+    return null;
+  }
+
+  return (
+    <UnifiedSelectionProvider storage={selectionStorage}>
+      <MyTreeComponentInternal imodelKey={imodel.key} imodelAccess={imodelAccess} />
+    </UnifiedSelectionProvider>
+  );
+}
+type IModelAccess = Parameters<typeof useUnifiedSelectionTree>[0]["imodelAccess"];
+
+/** Internal component that defines the hierarchy and creates tree state. */
+function MyTreeComponentInternal({ imodelAccess, imodelKey }: { imodelAccess: IModelAccess; imodelKey: string }) {
+  // Create a factory for building nodes SELECT query clauses in a format understood by the provider
+  const [nodesQueryFactory] = useState(createNodesQueryClauseFactory({ imodelAccess }));
+  // Create a factory for building labels SELECT query clauses according to BIS conventions
+  const [labelsQueryFactory] = useState(createBisInstanceLabelSelectClauseFactory({ classHierarchyInspector: imodelAccess }));
+
+  const { rootNodes, ...state } = useUnifiedSelectionTree({
+    // the source name is used to distinguish selection changes being made by different components
+    sourceName: "MyTreeComponent",
+    // the iModel key is required for unified selection system to distinguish selection changes between different iModels
+    imodelKey,
+    // iModel access is used to build the hierarchy
+    imodelAccess,
+    // the hierarchy definition describes the hierarchy using ECSQL queries; here it just returns all bis.Model instances
+    // grouped by class
+    getHierarchyDefinition: () => ({
+      defineHierarchyLevel: async () => [
+        {
+          fullClassName: "BisCore.Model",
+          query: {
+            ecsql: `
+              SELECT
+                ${await nodesQueryFactory.createSelectClause({
+                  ecClassId: { selector: "this.ECClassId" },
+                  ecInstanceId: { selector: "this.ECInstanceId" },
+                  nodeLabel: {
+                    selector: await labelsQueryFactory.createSelectClause({ classAlias: "this", className: "BisCore.Model" }),
+                  },
+                  grouping: {
+                    byClass: true,
+                  },
+                  hasChildren: false,
+                })}
+              FROM BisCore.Model this
+              WHERE this.ParentModel IS NULL
+            `,
+          },
+        },
+      ],
+    }),
+  });
+  if (!rootNodes) {
+    return "Loading...";
+  }
+  return <TreeRenderer rootNodes={rootNodes} {...state} />;
+}
+```
+
+## Localization
+
+Localization can be enabled for `TreeRenderer` component and `useTree` and `useUnifiedSelectionTree` hooks by providing an object with localized strings that will be used instead of the default English ones.
+
+Example:
+
+```tsx
+const localizedStrings = {
+  // strings for the `useUnifiedSelectionTree` hook
+  unspecified: "Unspecified",
+  other: "Other",
+
+  // strings for `TreeRenderer` and `TreeNodeRenderer`
+  loading: "Loading...",
+  filterHierarchyLevel: "Apply 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>",
+};
+
+function MyTreeComponent({ imodelAccess, imodelKey }: { imodelAccess: IModelAccess; imodelKey: string }) {
+  const { rootNodes, ...state } = useUnifiedSelectionTree({
+    sourceName: "MyTreeComponent",
+    imodelKey,
+    imodelAccess,
+    localizedStrings,
+    getHierarchyDefinition: () => ({
+      defineHierarchyLevel: async () => [],
+    }),
+  });
+  if (!rootNodes) {
+    return localizedStrings.loading;
+  }
+  return <TreeRenderer rootNodes={rootNodes} localizedStrings={localizedStrings} {...state} />;
+}
+```
+
+In case the `TreeNodeRenderer` component is used within a custom tree renderer, the tree component should supply localized strings through `LocalizationContextProvider`:
+
+```tsx
+export function MyTreeRenderer(props: MyTreeRendererProps) {
+  const nodeRenderer = useCallback(
+    (nodeProps) => {
+      return <TreeNodeRenderer {...nodeProps} {...props} />;
+    },
+    [props],
+  );
+
+  return (
+    <LocalizationContextProvider localizedStrings={localizedStrings}>
+      <Tree<RenderedTreeNode> {...props} />
+    </LocalizationContextProvider>
+  );
+}
+```

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

@@ -0,0 +1,75 @@
+import { HierarchyNode } from "@itwin/presentation-hierarchies";
+/**
+ * A type that defines an actual expandable node in a UI tree component, built with `useTree` hook.
+ * @beta
+ */
+export interface PresentationHierarchyNode {
+    id: string;
+    label: string;
+    children: true | Array<PresentationTreeNode>;
+    isExpanded: boolean;
+    isLoading: boolean;
+    isFilterable: boolean;
+    isFiltered: boolean;
+    /** UI-agnostic source of this node object. */
+    nodeData: HierarchyNode;
+    /** Additional data that may be assigned to this node. */
+    extendedData?: {
+        [key: string]: any;
+    };
+}
+/**
+ * A type of `PresentationInfoNode` that is returned as the single child of a filtered parent node,
+ * when none of the child nodes match the filter.
+ *
+ * @beta
+ */
+export interface PresentationNoFilterMatchesInfoNode {
+    id: string;
+    parentNodeId: string | undefined;
+    type: "NoFilterMatches";
+}
+/**
+ * A type of `PresentationInfoNode` that is returned as the single child of a parent node, when the
+ * number of child nodes exceeds the limit set on the tree nodes loader. The limit is also included
+ * on this node as `resultSetSizeLimit` attribute.
+ *
+ * @beta
+ */
+export interface PresentationResultSetTooLargeInfoNode {
+    id: string;
+    parentNodeId: string | undefined;
+    type: "ResultSetTooLarge";
+    resultSetSizeLimit: number;
+}
+/**
+ * A type of `PresentationInfoNode` that contains a user-friendly message to be displayed in the UI.
+ * Generally, this is the only child of a parent node, created in cases like an error loading children. The
+ * renderer may offer users to re-load the children or the whole component in such cases.
+ *
+ * @beta
+ */
+export interface PresentationGenericInfoNode {
+    id: string;
+    parentNodeId: string | undefined;
+    type: "Unknown";
+    message: string;
+}
+/**
+ * A type that defines a non-expandable, non-selectable informational node in a UI tree component, built
+ * with `useTree` hook.
+ *
+ * @beta
+ */
+export type PresentationInfoNode = PresentationGenericInfoNode | PresentationResultSetTooLargeInfoNode | PresentationNoFilterMatchesInfoNode;
+/**
+ * A type that defines a node in a UI tree component, built with `useTree` hook.
+ * @beta
+ */
+export type PresentationTreeNode = PresentationHierarchyNode | PresentationInfoNode;
+/**
+ * An utility function to check if a node is a `PresentationHierarchyNode`.
+ * @beta
+ */
+export declare function isPresentationHierarchyNode(node: PresentationTreeNode): node is PresentationHierarchyNode;
+//# sourceMappingURL=TreeNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TreeNode.d.ts","sourceRoot":"","sources":["../../../src/presentation-hierarchies-react/TreeNode.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,IAAI,GAAG,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,YAAY,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mCAAmC;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qCAAqC;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,GAAG,qCAAqC,GAAG,mCAAmC,CAAC;AAE7I;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,yBAAyB,GAAG,oBAAoB,CAAC;AAEpF;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,IAAI,yBAAyB,CAEzG"}

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

@@ -0,0 +1,16 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPresentationHierarchyNode = void 0;
+/**
+ * An utility function to check if a node is a `PresentationHierarchyNode`.
+ * @beta
+ */
+function isPresentationHierarchyNode(node) {
+    return "children" in node;
+}
+exports.isPresentationHierarchyNode = isPresentationHierarchyNode;
+//# sourceMappingURL=TreeNode.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TreeNode.js","sourceRoot":"","sources":["../../../src/presentation-hierarchies-react/TreeNode.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AA4EhG;;;GAGG;AACH,SAAgB,2BAA2B,CAAC,IAA0B;IACpE,OAAO,UAAU,IAAI,IAAI,CAAC;AAC5B,CAAC;AAFD,kEAEC","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 { HierarchyNode } from \"@itwin/presentation-hierarchies\";\n\n/**\n * A type that defines an actual expandable node in a UI tree component, built with `useTree` hook.\n * @beta\n */\nexport interface PresentationHierarchyNode {\n  id: string;\n  label: string;\n  children: true | Array<PresentationTreeNode>;\n  isExpanded: boolean;\n  isLoading: boolean;\n  isFilterable: boolean;\n  isFiltered: boolean;\n  /** UI-agnostic source of this node object. */\n  nodeData: HierarchyNode;\n  /** Additional data that may be assigned to this node. */\n  extendedData?: { [key: string]: any };\n}\n\n/**\n * A type of `PresentationInfoNode` that is returned as the single child of a filtered parent node,\n * when none of the child nodes match the filter.\n *\n * @beta\n */\nexport interface PresentationNoFilterMatchesInfoNode {\n  id: string;\n  parentNodeId: string | undefined;\n  type: \"NoFilterMatches\";\n}\n\n/**\n * A type of `PresentationInfoNode` that is returned as the single child of a parent node, when the\n * number of child nodes exceeds the limit set on the tree nodes loader. The limit is also included\n * on this node as `resultSetSizeLimit` attribute.\n *\n * @beta\n */\nexport interface PresentationResultSetTooLargeInfoNode {\n  id: string;\n  parentNodeId: string | undefined;\n  type: \"ResultSetTooLarge\";\n  resultSetSizeLimit: number;\n}\n\n/**\n * A type of `PresentationInfoNode` that contains a user-friendly message to be displayed in the UI.\n * Generally, this is the only child of a parent node, created in cases like an error loading children. The\n * renderer may offer users to re-load the children or the whole component in such cases.\n *\n * @beta\n */\nexport interface PresentationGenericInfoNode {\n  id: string;\n  parentNodeId: string | undefined;\n  type: \"Unknown\";\n  message: string;\n}\n\n/**\n * A type that defines a non-expandable, non-selectable informational node in a UI tree component, built\n * with `useTree` hook.\n *\n * @beta\n */\nexport type PresentationInfoNode = PresentationGenericInfoNode | PresentationResultSetTooLargeInfoNode | PresentationNoFilterMatchesInfoNode;\n\n/**\n * A type that defines a node in a UI tree component, built with `useTree` hook.\n * @beta\n */\nexport type PresentationTreeNode = PresentationHierarchyNode | PresentationInfoNode;\n\n/**\n * An utility function to check if a node is a `PresentationHierarchyNode`.\n * @beta\n */\nexport function isPresentationHierarchyNode(node: PresentationTreeNode): node is PresentationHierarchyNode {\n  return \"children\" in node;\n}\n"]}

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

@@ -0,0 +1,18 @@
+import { PropsWithChildren } from "react";
+import { SelectionStorage } from "@itwin/unified-selection";
+interface Props {
+    storage: SelectionStorage;
+}
+/**
+ * A React context provider that makes given selection storage available to all child components. This
+ * is a requirement for `useUnifiedSelectionTree` to work with unified selection.
+ *
+ * See `README.md` for a usage example.
+ *
+ * @beta
+ */
+export declare function UnifiedSelectionProvider({ storage, children }: PropsWithChildren<Props>): import("react/jsx-runtime").JSX.Element;
+/** @internal */
+export declare function useUnifiedSelectionContext(): SelectionStorage | undefined;
+export {};
+//# sourceMappingURL=UnifiedSelectionContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UnifiedSelectionContext.d.ts","sourceRoot":"","sources":["../../../src/presentation-hierarchies-react/UnifiedSelectionContext.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAiB,iBAAiB,EAAc,MAAM,OAAO,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAI5D,UAAU,KAAK;IACb,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC,KAAK,CAAC,2CAEvF;AAED,gBAAgB;AAChB,wBAAgB,0BAA0B,iCAEzC"}

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

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUnifiedSelectionContext = exports.UnifiedSelectionProvider = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+const react_1 = require("react");
+const unifiedSelectionContext = (0, react_1.createContext)(undefined);
+/**
+ * A React context provider that makes given selection storage available to all child components. This
+ * is a requirement for `useUnifiedSelectionTree` to work with unified selection.
+ *
+ * See `README.md` for a usage example.
+ *
+ * @beta
+ */
+function UnifiedSelectionProvider({ storage, children }) {
+    return (0, jsx_runtime_1.jsx)(unifiedSelectionContext.Provider, { value: storage, children: children });
+}
+exports.UnifiedSelectionProvider = UnifiedSelectionProvider;
+/** @internal */
+function useUnifiedSelectionContext() {
+    return (0, react_1.useContext)(unifiedSelectionContext);
+}
+exports.useUnifiedSelectionContext = useUnifiedSelectionContext;
+//# sourceMappingURL=UnifiedSelectionContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UnifiedSelectionContext.js","sourceRoot":"","sources":["../../../src/presentation-hierarchies-react/UnifiedSelectionContext.tsx"],"names":[],"mappings":";;;;AAAA;;;gGAGgG;AAEhG,iCAAqE;AAGrE,MAAM,uBAAuB,GAAG,IAAA,qBAAa,EAA+B,SAAS,CAAC,CAAC;AAMvF;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAA4B;IACtF,OAAO,uBAAC,uBAAuB,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,YAAG,QAAQ,GAAoC,CAAC;AACzG,CAAC;AAFD,4DAEC;AAED,gBAAgB;AAChB,SAAgB,0BAA0B;IACxC,OAAO,IAAA,kBAAU,EAAC,uBAAuB,CAAC,CAAC;AAC7C,CAAC;AAFD,gEAEC","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, PropsWithChildren, useContext } from \"react\";\nimport { SelectionStorage } from \"@itwin/unified-selection\";\n\nconst unifiedSelectionContext = createContext<SelectionStorage | undefined>(undefined);\n\ninterface Props {\n  storage: SelectionStorage;\n}\n\n/**\n * A React context provider that makes given selection storage available to all child components. This\n * is a requirement for `useUnifiedSelectionTree` to work with unified selection.\n *\n * See `README.md` for a usage example.\n *\n * @beta\n */\nexport function UnifiedSelectionProvider({ storage, children }: PropsWithChildren<Props>) {\n  return <unifiedSelectionContext.Provider value={storage}>{children}</unifiedSelectionContext.Provider>;\n}\n\n/** @internal */\nexport function useUnifiedSelectionContext() {\n  return useContext(unifiedSelectionContext);\n}\n"]}

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

@@ -0,0 +1,33 @@
+/// <reference types="react" />
+import { useTree } from "./UseTree";
+/**
+ * A union of different supported selection modes in a tree component:
+ * - `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.
+ *
+ * @internal
+ */
+export type SelectionMode = "none" | "single" | "extended" | "multiple";
+/** @internal */
+export type SelectionChangeType = "add" | "replace" | "remove";
+/** Props for `useSelectionHandler` hook. */
+type UseSelectionHandlerProps = Pick<ReturnType<typeof useTree>, "rootNodes" | "selectNodes"> & {
+    /** Selection mode that the component is working in. */
+    selectionMode: SelectionMode;
+};
+/** Result of `useSelectionHandler` hook. */
+interface UseSelectionHandlerResult {
+    /** Should be called by node renderer when a node component is clicked. */
+    onNodeClick: (nodeId: string, isSelected: boolean, event: React.MouseEvent<HTMLElement, MouseEvent>) => void;
+    /** Should be called by node renderer when a keyboard event happens on a node. */
+    onNodeKeyDown: (nodeId: string, isSelected: boolean, event: React.KeyboardEvent<HTMLElement>) => void;
+}
+/**
+ * A react hook that helps implement different selection modes in a tree component created using `useTree` hook.
+ * @beta
+ */
+export declare function useSelectionHandler(props: UseSelectionHandlerProps): UseSelectionHandlerResult;
+export {};
+//# sourceMappingURL=UseSelectionHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UseSelectionHandler.d.ts","sourceRoot":"","sources":["../../../src/presentation-hierarchies-react/UseSelectionHandler.ts"],"names":[],"mappings":";AAOA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAExE,gBAAgB;AAChB,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE/D,4CAA4C;AAC5C,KAAK,wBAAwB,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,GAAG;IAC9F,uDAAuD;IACvD,aAAa,EAAE,aAAa,CAAC;CAC9B,CAAC;AAEF,4CAA4C;AAC5C,UAAU,yBAAyB;IACjC,0EAA0E;IAC1E,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,KAAK,IAAI,CAAC;IAC7G,iFAAiF;IACjF,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACvG;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CAwD9F"}

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

@@ -0,0 +1,102 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSelectionHandler = void 0;
+const react_1 = require("react");
+const TreeNode_1 = require("./TreeNode");
+/**
+ * A react hook that helps implement different selection modes in a tree component created using `useTree` hook.
+ * @beta
+ */
+function useSelectionHandler(props) {
+    const { rootNodes, selectionMode, selectNodes } = props;
+    const previousSelectionRef = (0, react_1.useRef)(undefined);
+    const state = (0, react_1.useRef)({
+        flatNodeList: [],
+        nodeIdToIndexMap: new Map(),
+    });
+    (0, react_1.useEffect)(() => {
+        if (!rootNodes) {
+            return;
+        }
+        state.current = computeFlatNodeList(rootNodes);
+    }, [rootNodes]);
+    const getNodeRange = (firstId, secondId) => {
+        const getIndex = (nodeId) => {
+            return nodeId ? state.current.nodeIdToIndexMap.get(nodeId) : 0;
+        };
+        const firstIndex = getIndex(firstId);
+        const secondIndex = getIndex(secondId);
+        if (firstIndex === undefined || secondIndex === undefined) {
+            return [];
+        }
+        const startingIndex = Math.min(firstIndex, secondIndex);
+        const endIndex = Math.max(firstIndex, secondIndex);
+        return state.current.flatNodeList.slice(startingIndex, endIndex + 1);
+    };
+    const onNodeSelect = (nodeId, isSelected, shiftDown, ctrlDown) => {
+        const selection = getSelectionAction(selectionMode, isSelected, shiftDown, ctrlDown);
+        if (selection.type === "disabled") {
+            return;
+        }
+        const nodes = selection.select === "range" ? getNodeRange(previousSelectionRef.current, nodeId) : [nodeId];
+        if (!nodes.length) {
+            return;
+        }
+        selection.select !== "range" && (previousSelectionRef.current = nodeId);
+        selectNodes(nodes, selection.type);
+    };
+    const onNodeClick = (nodeId, isSelected, event) => {
+        return onNodeSelect(nodeId, isSelected, event.shiftKey, event.ctrlKey);
+    };
+    const onNodeKeyDown = (nodeId, isSelected, event) => {
+        if (event.key === " " || event.key === "Spacebar" || event.key === "Enter") {
+            return onNodeSelect(nodeId, isSelected, event.shiftKey, event.ctrlKey);
+        }
+    };
+    return { onNodeClick, onNodeKeyDown };
+}
+exports.useSelectionHandler = useSelectionHandler;
+function getSelectionAction(selectionMode, isSelected, shiftDown, ctrlDown) {
+    switch (selectionMode) {
+        case "none":
+            return { select: "node", type: "disabled" };
+        case "single":
+            return { select: "node", type: isSelected ? "replace" : "remove" };
+        case "multiple":
+            return { select: "node", type: isSelected ? "add" : "remove" };
+        case "extended":
+            return getExtendedSelectionAction(isSelected, shiftDown, ctrlDown);
+    }
+}
+function getExtendedSelectionAction(isSelected, shiftDown, ctrlDown) {
+    if (shiftDown) {
+        return { select: "range", type: "replace" };
+    }
+    if (!isSelected) {
+        return { select: "node", type: "remove" };
+    }
+    return { select: "node", type: ctrlDown ? "add" : "replace" };
+}
+function computeFlatNodeList(rootNodes) {
+    const flatNodeList = [];
+    const nodeIdToIndexMap = new Map();
+    const flattenNodeRecursively = (nodes) => {
+        nodes.forEach((node) => {
+            if (!(0, TreeNode_1.isPresentationHierarchyNode)(node)) {
+                return;
+            }
+            nodeIdToIndexMap.set(node.id, flatNodeList.length);
+            flatNodeList.push(node.id);
+            if (node.isExpanded && typeof node.children !== "boolean") {
+                flattenNodeRecursively(node.children);
+            }
+        });
+    };
+    flattenNodeRecursively(rootNodes);
+    return { flatNodeList, nodeIdToIndexMap };
+}
+//# sourceMappingURL=UseSelectionHandler.js.map