Update ActiveSelectionScope relative documentation

common/api/appui-react.api.md

@@ -3708,7 +3708,7 @@ export enum SelectionScope {
 }
 
 // @public
-export const SelectionScopeField: ConnectedComponent<typeof SelectionScopeFieldComponent, Omit_3<SelectionScopeFieldProps, "availableSelectionScopes" | "activeSelectionScope">>;
+export const SelectionScopeField: ConnectedComponent<typeof SelectionScopeFieldComponent, CommonProps>;
 
 // @public
 export interface SessionState {
@@ -4802,9 +4802,7 @@ export class UiFramework {
     static getAccudrawSnapMode(): SnapMode;
     // (undocumented)
     static getActiveIModelId(): string;
-    // (undocumented)
     static getActiveSelectionScope(): string;
-    // (undocumented)
     static getAvailableSelectionScopes(): PresentationSelectionScope[];
     // (undocumented)
     static getColorTheme(): ThemeId;
@@ -4851,7 +4849,6 @@ export class UiFramework {
     static setAccudrawSnapMode(snapMode: SnapMode): void;
     // (undocumented)
     static setActiveIModelId(iModelId: string): void;
-    // (undocumented)
     static setActiveSelectionScope(selectionScopeId: string): void;
     // (undocumented)
     static setAnimateToolSettings(value: boolean): void;

common/changes/@itwin/appui-react/raplemie-selectionScopesDoc_2023-10-30-16-28.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/appui-react",
+      "comment": "Update active selection scope related documentation.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/appui-react"
+}

ui/appui-react/src/appui-react/UiFramework.ts

@@ -464,12 +464,22 @@ export class UiFramework {
       : /* istanbul ignore next */ SnapMode.NearestKeypoint;
   }
 
+  /**
+   * Returns the stored active selection scope id.
+   */
   public static getActiveSelectionScope(): string {
     return UiFramework.frameworkState
       ? UiFramework.frameworkState.sessionState.activeSelectionScope
       : /* istanbul ignore next */ "element";
   }
 
+  /**
+   * This method stores the active selection scope to the supplied scope id, and triggers
+   * a `SessionStateActionId.SetSelectionScope` event in the `SyncUiEventDispatcher`.
+   * Note: As of 4.0, this method *does not change* the active selection scope in the `Presentation.selection.scopes.activeScope` property.
+   * This event should be listened to and the change should typically be applied to
+   * `Presentation.selection.scopes.activeScope` property from the `@itwin/presentation-frontend` package.
+   */
   public static setActiveSelectionScope(selectionScopeId: string): void {
     // istanbul ignore else
     if (UiFramework.frameworkState) {
@@ -654,7 +664,12 @@ export class UiFramework {
       : /* istanbul ignore next */ undefined;
   }
 
-  /** @public */
+  /**
+   * Returns the stored list of available selection scopes. This list should be set by the application
+   * by dispatching the `setAvailableSelectionScopes` action.
+   * The value for this action typically come from `Presentation.selection.scopes.getSelectionScopes()`
+   * method found in the `@itwin/presentation-frontend` package.
+   * @public */
   public static getAvailableSelectionScopes(): PresentationSelectionScope[] {
     return UiFramework.frameworkState
       ? UiFramework.frameworkState.sessionState.availableSelectionScopes

ui/appui-react/src/appui-react/statusfields/SelectionScope.tsx

@@ -9,6 +9,7 @@
 import "./SelectionScope.scss";
 import classnames from "classnames";
 import * as React from "react";
+import type { ConnectedComponent } from "react-redux";
 import { connect } from "react-redux";
 import { FooterIndicator } from "@itwin/appui-layout-react";
 import { Select } from "@itwin/itwinui-react";
@@ -26,11 +27,6 @@ interface SelectionScopeFieldProps extends CommonProps {
 
 /**
  * Status Field React component. This component is designed to be specified in a status bar definition.
- * It is used to display the number of selected items based on the Presentation Rules Selection Manager.
- * The IModelApp should call either UiFramework.setIModelConnection or SyncUiEventDispatcher.initializeConnectionEvents
- * with the active iModelConnection each time a new iModel is opened so the selection scope data is properly updated
- * in the Redux state.
- * @public
  */
 function SelectionScopeFieldComponent(props: SelectionScopeFieldProps) {
   const label = UiFramework.translate("selectionScopeField.label");
@@ -86,13 +82,14 @@ function mapStateToProps(state: any) {
   };
 }
 
-// we declare the variable and export that rather than using export default.
 /**
  * SelectionScopeField React component. This component is designed to be specified in a status bar definition. It will
- * display the active selection scope that is used by the PresentationManager to determine what elements are added to the selection nap mode.
+ * display the active selection scope from `UiFramework.getActiveSelectionScope()`, and display the stored list of scopes from
+ * `UiFramework.getAvailableSelectionScopes()` to allow the user to change the active selection scope, using `UiFramework.setActiveSelectionScope()`.
  * This React component is Redux connected.
  * @public
  */
-export const SelectionScopeField = connect(mapStateToProps)(
-  SelectionScopeFieldComponent
-);
+export const SelectionScopeField: ConnectedComponent<
+  typeof SelectionScopeFieldComponent,
+  CommonProps
+> = connect(mapStateToProps)(SelectionScopeFieldComponent);