Property widget: Selection storage support

apps/learning-snippets/src/test/property-grid/Usage.test.tsx

@@ -8,6 +8,7 @@ import { expect } from "chai";
 import sinon from "sinon";
 import { StagePanelLocation, StagePanelSection, StageUsage } from "@itwin/appui-react";
 import { PresentationPropertyDataProvider } from "@itwin/presentation-components";
+import { createStorage } from "@itwin/unified-selection";
 // __PUBLISH_EXTRACT_START__ PropertyGrid.RegisterPropertyGridWidgetImports
 import { createPropertyGrid } from "@itwin/property-grid-react";
 import { UiItemsManager } from "@itwin/appui-react";
@@ -50,6 +51,9 @@ describe("Property grid", () => {
       it("registers customizable property grid", async function () {
         const MY_CUSTOM_RULESET = undefined;
 
+        const selectionStorage = createStorage();
+        const getGlobalSelectionStorage = () => selectionStorage;
+
         // __PUBLISH_EXTRACT_START__ PropertyGrid.RegisterCustomPropertyGridWidget
         UiItemsManager.register({
           id: "property-grid-provider",
@@ -82,6 +86,10 @@ describe("Property grid", () => {
                 // supply an optional custom storage for user preferences, e.g. the show/hide null values used above
                 preferencesStorage: new IModelAppUserPreferencesStorage("my-favorites-namespace"),
 
+                // supply the global selection storage that the widget will use to listen to selection
+                // changes (more details: https://github.com/iTwin/presentation/blob/master/packages/unified-selection/README.md)
+                selectionStorage: getGlobalSelectionStorage(),
+
                 // supply an optional data provider factory method to create a custom property data provider
                 createDataProvider: (imodel: IModelConnection) => new PresentationPropertyDataProvider({ imodel, ruleset: MY_CUSTOM_RULESET }),
 

apps/test-viewer/src/UiProvidersConfig.tsx

@@ -217,6 +217,7 @@ const configuredUiItems = new Map<string, UiItem>([
                 onFeatureUsed: (feature) => {
                   console.log(`PropertyGrid [${feature}] used`);
                 },
+                selectionStorage: unifiedSelectionStorage,
               }),
             ];
           },

change/@itwin-property-grid-react-6b27dcfe-db3d-4eed-8287-9f057945cbf1.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Added optional `selectionStorage` prop to `createPropertyGrid` function and `MultiElementPropertyGrid` component. This allows using `@itwin/unified-selection` to manage selection state, rather than relying on soon-to-be deprecated unified selection API from `@itwin/presentation-frontend`. The prop will be made required in next major release.",
+  "packageName": "@itwin/property-grid-react",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/itwin/property-grid/README.md

@@ -87,6 +87,10 @@ UiItemsManager.register({
         // supply an optional custom storage for user preferences, e.g. the show/hide null values used above
         preferencesStorage: new IModelAppUserPreferencesStorage("my-favorites-namespace"),
 
+        // supply the global selection storage that the widget will use to listen to selection
+        // changes (more details: https://github.com/iTwin/presentation/blob/master/packages/unified-selection/README.md)
+        selectionStorage: getGlobalSelectionStorage(),
+
         // supply an optional data provider factory method to create a custom property data provider
         createDataProvider: (imodel: IModelConnection) => new PresentationPropertyDataProvider({ imodel, ruleset: MY_CUSTOM_RULESET }),
 
@@ -99,7 +103,19 @@ UiItemsManager.register({
 
 <!-- END EXTRACTION -->
 
-As seen in the above code snippet, `createPropertyGrid` takes a number of props that allow customizing not only how the widget behaves, but also how it looks. The package delivers commonly used building blocks:
+As seen in the above code snippet, `createPropertyGrid` takes a number of props that allow customizing not only how the widget behaves, but also how it looks.
+
+### Hooking into unified selection
+
+The widget and its components rely on [unified selection](https://github.com/iTwin/presentation/blob/master/packages/unified-selection/README.md#basic-concepts) system to tell them which element(s) are currently selected and when the selection changes. As of version `1.16`, there are two ways to hook into unified selection:
+
+- Supply the `selectionStorage` prop to components that use the unified selection system. See [Basic usage](https://github.com/iTwin/presentation/blob/master/packages/unified-selection/README.md#basic-usage) example for how to set up the storage. At the moment the prop is optional and will only be made required in version `2.0`; the components fall back to the legacy system described below if it's not provided.
+
+- The legacy `SelectionManager` from `@itwin/presentation-frontend` package, accessed through `Presentation.selection` API.
+
+### Building blocks
+
+The package delivers commonly used building blocks:
 
 - context and setting menu items
 - ancestor navigation controls

packages/itwin/property-grid/api/property-grid-react.api.md

@@ -13,14 +13,16 @@ import type { IModelConnection } from '@itwin/core-frontend';
 import type { InstanceKey } from '@itwin/presentation-common';
 import type { IPresentationPropertyDataProvider } from '@itwin/presentation-components';
 import type { IPropertyDataFilterer } from '@itwin/components-react';
-import type { KeySet } from '@itwin/presentation-common';
+import { KeySet } from '@itwin/presentation-common';
 import type { Localization } from '@itwin/core-common';
 import type { PropertyCategory } from '@itwin/components-react';
 import type { PropertyRecord } from '@itwin/appui-abstract';
 import type { PropertyUpdatedArgs } from '@itwin/components-react';
 import type { PropsWithChildren } from 'react';
 import type { ReactNode } from 'react';
 import { Ref } from 'react';
+import { Selectables } from '@itwin/unified-selection';
+import type { SelectionStorage as SelectionStorage_2 } from '@itwin/unified-selection';
 import { StagePanelLocation } from '@itwin/appui-react';
 import { StagePanelSection } from '@itwin/appui-react';
 import type { TranslationOptions } from '@itwin/core-common';
@@ -97,6 +99,7 @@ export function MultiElementPropertyGrid({ ancestorsNavigationControls, ...props
 // @public
 export interface MultiElementPropertyGridProps extends Omit<PropertyGridProps, "headerControls" | "onBackButton"> {
     ancestorsNavigationControls?: (props: AncestorsNavigationControlsProps) => ReactNode;
+    selectionStorage?: SelectionStorage;
 }
 
 // @public
@@ -207,9 +210,13 @@ export interface PropertyGridUiItemsProviderProps {
 export const PropertyGridWidgetId = "vcr:PropertyGridComponent";
 
 // @public
-export interface PropertyGridWidgetProps extends PropertyGridComponentProps {
+export type PropertyGridWidgetProps = PropertyGridComponentProps & ({
     shouldShow?: (selection: Readonly<KeySet>) => boolean;
-}
+    selectionStorage?: never;
+} | {
+    shouldShow?: (selection: Selectables) => Promise<boolean>;
+    selectionStorage: SelectionStorage;
+});
 
 // @public
 export function RemoveFavoritePropertyContextMenuItem({ field, imodel, scope, onSelect }: FavoritePropertiesContextMenuItemProps): JSX.Element | null;

packages/itwin/property-grid/api/property-grid-react.exports.csv

@@ -34,7 +34,7 @@ deprecated;class;PropertyGridUiItemsProvider
 public;interface;PropertyGridUiItemsProviderProps
 deprecated;interface;PropertyGridUiItemsProviderProps
 public;const;PropertyGridWidgetId
-public;interface;PropertyGridWidgetProps
+public;type;PropertyGridWidgetProps
 public;function;RemoveFavoritePropertyContextMenuItem
 public;interface;SettingsMenuItemProps
 public;interface;SettingsMenuProps

packages/itwin/property-grid/package.json

@@ -39,7 +39,7 @@
     "copy:cjs": "cpx \"./src/**/*.scss\" ./lib/cjs",
     "copy:esm": "cpx \"./src/**/*.scss\" ./lib/esm",
     "cover": "c8 npm run test",
-    "extract-api": "betools extract-api --entry=property-grid-react --apiReportFolder=./api --apiReportTempFolder=./api/temp --apiSummaryFolder=./api",
+    "extract-api": "betools extract-api --entry=lib/esm/property-grid-react --apiReportFolder=./api --apiReportTempFolder=./api/temp --apiSummaryFolder=./api",
     "check-internal": "node ../../../scripts/checkInternal.js --apiSummary ./api/property-grid-react.api.md",
     "lint": "npm run lint:eslint && npm run lint:stylelint",
     "lint:eslint": "eslint -f visualstudio \"./src/**/*.{ts,tsx}\" 1>&2",
@@ -73,6 +73,9 @@
     "@itwin/itwinui-icons-react": "^2.8.0",
     "@itwin/itwinui-illustrations-react": "^2.1.0",
     "@itwin/itwinui-react": "^3.16.5",
+    "@itwin/presentation-core-interop": "^1.3.0",
+    "@itwin/presentation-shared": "^1.2.0",
+    "@itwin/unified-selection": "^1.3.0",
     "classnames": "^2.5.1",
     "react-error-boundary": "^4.0.10"
   },
@@ -106,7 +109,7 @@
     "@types/chai": "^4.3.16",
     "@types/jsdom": "^21.1.6",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^18.18.10",
+    "@types/node": "^22.13.1",
     "@types/react": "^18.0.34",
     "@types/react-dom": "^18.0.11",
     "@types/sinon": "^17.0.3",