Tree widget: Expose focused instances context provider (#1175)

* Expose `FocusedInstancesContextProvider` and `useFocusedInstancesContext`

* change

Author: grigasp

change/@itwin-tree-widget-react-5a06d142-8cab-416d-b641-b7478a50e8f1.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Expose `FocusedInstancesContextProvider` and `useFocusedInstancesContext` to allow using `ModelsTreeComponent.ToggleInstancesFocusButton` from outside of `ModelsTreeComponent` and accesing the context from other React components.",
+  "packageName": "@itwin/tree-widget-react",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/itwin/tree-widget/api/tree-widget-react.api.md

@@ -156,6 +156,19 @@ export class FilterLimitExceededError extends Error {
     readonly limit: number;
 }
 
+// @public (undocumented)
+interface FocusedInstancesContext {
+    enabled: boolean;
+    loadFocusedItems?: () => AsyncIterableIterator<InstanceKey | GroupingHierarchyNode>;
+    toggle: () => void;
+}
+
+// @public
+export function FocusedInstancesContextProvider({ selectionStorage, imodelKey, children, }: PropsWithChildren<{
+    selectionStorage: SelectionStorage;
+    imodelKey: string;
+}>): JSX.Element;
+
 // @beta (undocumented)
 type FunctionProps<THook extends (props: any) => any> = Parameters<THook>[0];
 
@@ -485,6 +498,9 @@ interface UseCategoriesTreeResult {
     rendererProps: Required<Pick<VisibilityTreeRendererProps, "getIcon" | "getSublabel">>;
 }
 
+// @public
+export function useFocusedInstancesContext(): FocusedInstancesContext;
+
 // @beta
 export function useModelsTree({ activeView, filter, hierarchyConfig, visibilityHandlerOverrides, getFilteredPaths, onModelsFiltered, selectionPredicate: nodeTypeSelectionPredicate, }: UseModelsTreeProps): UseModelsTreeResult;
 

packages/itwin/tree-widget/api/tree-widget-react.exports.csv

@@ -4,6 +4,7 @@ public;const;CategoriesTreeComponent
 public;function;createTreeWidget
 beta;const;ExternalSourcesTreeComponent
 beta;class;FilterLimitExceededError
+public;function;FocusedInstancesContextProvider
 beta;interface;HierarchyVisibilityHandler
 beta;const;IModelContentTreeComponent
 public;const;ModelsTreeComponent
@@ -18,6 +19,7 @@ public;function;TreeWidgetComponent
 beta;function;TreeWithHeader
 beta;function;useCategoriesTree
 public;function;useCategoriesTreeButtonProps
+public;function;useFocusedInstancesContext
 beta;function;useModelsTree
 public;function;useModelsTreeButtonProps
 beta;interface;VisibilityStatus

packages/itwin/tree-widget/package.json

@@ -38,7 +38,7 @@
     "copy:cjs": "cpx \"./src/**/*.{scss,json}\" ./lib/cjs",
     "copy:esm": "cpx \"./src/**/*.{scss,json}\" ./lib/esm",
     "cover": "c8 npm run test",
-    "extract-api": "betools extract-api --entry=tree-widget-react --apiReportFolder=./api --apiReportTempFolder=./api/temp --apiSummaryFolder=./api --includeUnexportedApis",
+    "extract-api": "betools extract-api --entry=lib/esm/tree-widget-react --apiReportFolder=./api --apiReportTempFolder=./api/temp --apiSummaryFolder=./api --includeUnexportedApis",
     "check-internal": "node ../../../scripts/checkInternal.js --apiSummary ./api/tree-widget-react.api.md",
     "lint": "npm run lint:eslint && npm run lint:stylelint",
     "lint:eslint": "eslint -f visualstudio \"./src/**/*.{ts,tsx}\" 1>&2",

packages/itwin/tree-widget/src/test/trees/common/FocusedInstancesContext.test.tsx

@@ -5,8 +5,7 @@
 
 import { expect } from "chai";
 import { createStorage } from "@itwin/unified-selection";
-import { useFocusedInstancesContext } from "../../../tree-widget-react/components/trees/common/FocusedInstancesContext.js";
-import { FocusedInstancesContextProvider } from "../../../tree-widget-react/components/trees/common/FocusedInstancesContextProvider.js";
+import { FocusedInstancesContextProvider, useFocusedInstancesContext } from "../../../tree-widget-react/components/trees/common/FocusedInstancesContext.js";
 import { act, createAsyncIterator, renderHook, waitFor } from "../../TestUtils.js";
 
 import type { GroupingHierarchyNode } from "@itwin/presentation-hierarchies";

packages/itwin/tree-widget/src/tree-widget-react/components/trees/common/FocusedInstancesContext.ts

@@ -3,17 +3,48 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 
-import { useEffect, useState } from "react";
+import { createContext, useContext, useEffect, useState } from "react";
 import { HierarchyNode } from "@itwin/presentation-hierarchies-react";
 import { Selectable, Selectables } from "@itwin/unified-selection";
-import { focusedInstancesContext } from "./FocusedInstancesContext.js";
 
-import type { SelectionStorage } from "@itwin/presentation-hierarchies-react";
 import type { PropsWithChildren } from "react";
-import type { InstanceKey } from "@itwin/presentation-common";
-import type { FocusedInstancesContext } from "./FocusedInstancesContext.js";
 import type { GroupingHierarchyNode } from "@itwin/presentation-hierarchies";
+import type { SelectionStorage } from "@itwin/presentation-hierarchies-react";
+import type { InstanceKey } from "@itwin/presentation-shared";
+
+/** @public */
+interface FocusedInstancesContext {
+  /**
+   * A function, returning an async iterator of items that should be focused. The function is not set
+   * when instances focus mode is disabled or selection is empty.
+   */
+  loadFocusedItems?: () => AsyncIterableIterator<InstanceKey | GroupingHierarchyNode>;
+
+  /** A flag indicating whether instances focus mode is enabled. */
+  enabled: boolean;
+
+  /** Toggle enable or disable instances focus mode. */
+  toggle: () => void;
+}
+
+const focusedInstancesContext = createContext<FocusedInstancesContext>({ enabled: false, toggle: () => {} });
+
+/**
+ * A React hook for getting focused instances context. The context must be provided
+ * using `FocusedInstancesContextProvider`.
+ *
+ * @public
+ */
+export function useFocusedInstancesContext(): FocusedInstancesContext {
+  return useContext(focusedInstancesContext);
+}
 
+/**
+ * A React context provider for setting up focused instances context, which can then be acquired
+ * using `useFocusedInstancesContext` hook.
+ *
+ * @public
+ */
 export function FocusedInstancesContextProvider({
   selectionStorage,
   imodelKey,

packages/itwin/tree-widget/src/tree-widget-react/components/trees/common/FocusedInstancesContextProvider.tsx renamed to packages/itwin/tree-widget/src/tree-widget-react/components/trees/common/FocusedInstancesContext.tsx

@@ -14,6 +14,8 @@ export { useCategoriesTree } from "./categories-tree/UseCategoriesTree.js";
 export { useModelsTreeButtonProps } from "./models-tree/ModelsTreeButtons.js";
 export { useCategoriesTreeButtonProps } from "./categories-tree/CategoriesTreeButtons.js";
 
+export { FocusedInstancesContextProvider, useFocusedInstancesContext } from "./common/FocusedInstancesContext.js";
+
 export { Tree } from "./common/components/Tree.js";
 export { VisibilityTree } from "./common/components/VisibilityTree.js";
 export { TreeRenderer } from "./common/components/TreeRenderer.js";

packages/itwin/tree-widget/src/tree-widget-react/components/trees/index.ts

@@ -7,8 +7,7 @@ import { Fragment, useEffect } from "react";
 import { useActiveIModelConnection } from "@itwin/appui-react";
 import { TreeWidget } from "../../../TreeWidget.js";
 import { TreeWithHeader } from "../../tree-header/TreeWithHeader.js";
-import { useFocusedInstancesContext } from "../common/FocusedInstancesContext.js";
-import { FocusedInstancesContextProvider } from "../common/FocusedInstancesContextProvider.js";
+import { FocusedInstancesContextProvider, useFocusedInstancesContext } from "../common/FocusedInstancesContext.js";
 import { useActiveViewport } from "../common/UseActiveViewport.js";
 import { useFiltering } from "../common/UseFiltering.js";
 import { TelemetryContextProvider } from "../common/UseTelemetryContext.js";
@@ -106,7 +105,12 @@ ModelsTreeComponent.View2DButton = View2DButton as ModelsTreeHeaderButtonType;
 ModelsTreeComponent.View3DButton = View3DButton as ModelsTreeHeaderButtonType;
 
 /**
- * Renders a "Enable/Disable instances focus" button that enables/disables instances focusing mode.
+ * Renders an "Instance focus" toggle button that enables/disables instances focusing mode.
+ *
+ * Requires instances focus context to be provided using `FocusedInstancesContextProvider`. The context
+ * is provided automatically, when using `ModelsTreeComponent`, but needs to be provided by consumers
+ * when rendering `ToggleInstancesFocusButton` outside of `ModelsTreeComponent`.
+ *
  * @public
  */
 ModelsTreeComponent.ToggleInstancesFocusButton = ToggleInstancesFocusButton as ModelsTreeHeaderButtonType;