Add promptAtContent to ToolAssistanceField components (#1211)

* Update docs * Add story * Group status bar fields * Use ConfigurableUiContent * Add indefinite cursorPromptTimeout * Fix an issue with CursorPopup where a fading popup is not re-opened. * Refactor cursor prompt. * Close the prompt if toggled off (after toggle on tool still needs to be activated). * Add promptAtContent prop. * Add promptAtContent story * rush change * Extract API * NextVersion * Mark componentDidUpdate as internal to fix docs CI issue
iTwin · Feb 12, 2025 · 0d6dc0b · 0d6dc0b
1 parent 6ffcbf0
commit 0d6dc0b
Show file tree

Hide file tree

Showing 14 changed files with 419 additions and 238 deletions.
diff --git a/common/api/appui-react.api.md b/common/api/appui-react.api.md
@@ -1451,6 +1451,7 @@ export class CursorPopupManager {
     // @internal (undocumented)
     static readonly onCursorPopupFadeOutEvent: BeUiEvent<{
         id: string;
+        show?: CursorPopupShow;
     }>;
     // @internal (undocumented)
     static readonly onCursorPopupsChangedEvent: BeUiEvent<object>;
@@ -2069,7 +2070,7 @@ export interface FrameworkKeyboardShortcuts {
 export const FrameworkReducer: Reducer_2<    {
 configurableUiState: ConfigurableUiState;
 sessionState: DeepReadonlyObject_2<SessionState>;
-}, SessionStateActionsUnion_2 | ConfigurableUiActionsUnion_2, Partial<{
+}, ConfigurableUiActionsUnion_2 | SessionStateActionsUnion_2, Partial<{
 configurableUiState: never;
 sessionState: never;
 }>>;
@@ -3838,7 +3839,7 @@ export const SessionStateActions: {
     setNumItemsSelected: (numSelected: number) => ActionWithPayload_2<SessionStateActionId.SetNumItemsSelected, number>;
     setIModelConnection: (iModelConnection: any) => ActionWithPayload_2<SessionStateActionId.SetIModelConnection, any>;
     setSelectionScope: (activeSelectionScope: string) => ActionWithPayload_2<SessionStateActionId.SetSelectionScope, string>;
-    updateCursorMenu: (cursorMenuData: CursorMenuData | CursorMenuPayload) => ActionWithPayload_2<SessionStateActionId.UpdateCursorMenu, DeepReadonlyObject_2<CursorMenuPayload> | DeepReadonlyObject_2<CursorMenuData>>;
+    updateCursorMenu: (cursorMenuData: CursorMenuData | CursorMenuPayload) => ActionWithPayload_2<SessionStateActionId.UpdateCursorMenu, DeepReadonlyObject_2<CursorMenuData> | DeepReadonlyObject_2<CursorMenuPayload>>;
 };
 
 // @beta @deprecated
@@ -3876,7 +3877,7 @@ export const sessionStateMapDispatchToProps: {
     setNumItemsSelected: (numSelected: number) => ActionWithPayload_2<SessionStateActionId.SetNumItemsSelected, number>;
     setIModelConnection: (iModelConnection: any) => ActionWithPayload_2<SessionStateActionId.SetIModelConnection, any>;
     setSelectionScope: (activeSelectionScope: string) => ActionWithPayload_2<SessionStateActionId.SetSelectionScope, string>;
-    updateCursorMenu: (cursorMenuData: CursorMenuData | CursorMenuPayload) => ActionWithPayload_2<SessionStateActionId.UpdateCursorMenu, DeepReadonlyObject_2<CursorMenuPayload> | DeepReadonlyObject_2<CursorMenuData>>;
+    updateCursorMenu: (cursorMenuData: CursorMenuData | CursorMenuPayload) => ActionWithPayload_2<SessionStateActionId.UpdateCursorMenu, DeepReadonlyObject_2<CursorMenuData> | DeepReadonlyObject_2<CursorMenuPayload>>;
 };
 
 // @public @deprecated
@@ -4654,6 +4655,8 @@ export class ToolAssistanceField extends React_2.Component<ToolAssistanceFieldPr
     constructor(p: ToolAssistanceFieldProps);
     // (undocumented)
     componentDidMount(): Promise<void>;
+    // @internal (undocumented)
+    componentDidUpdate(): void;
     // (undocumented)
     componentWillUnmount(): void;
     // @internal (undocumented)
@@ -4674,6 +4677,7 @@ export interface ToolAssistanceFieldProps extends CommonProps {
     defaultPromptAtCursor: boolean;
     fadeOutCursorPrompt: boolean;
     includePromptAtCursor: boolean;
+    promptAtContent?: boolean;
     uiStateStorage?: UiStateStorage;
 }
 

diff --git a/common/changes/@itwin/appui-react/issue-1201_2025-02-10-11-01.json b/common/changes/@itwin/appui-react/issue-1201_2025-02-10-11-01.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/appui-react",
+      "comment": "Add `promptAtContent` prop to `ToolAssistanceField` component.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/appui-react"
+}
diff --git a/docs/changehistory/NextVersion.md b/docs/changehistory/NextVersion.md
@@ -1,7 +1,16 @@
 # NextVersion <!-- omit from toc -->
 
+- [@itwin/appui-react](#itwinappui-react)
+  - [Additions](#additions)
+  - [Changes](#changes)
+
 ## @itwin/appui-react
 
 ### Additions
 
 - Added `useSavedState` property to `Widget` interface. By default widgets with `defaultState=Hidden` are always hidden when the layout is restored (i.e. page is reloaded). When `useSavedState` is set to `true` it will override the default behavior and force the widget to use its saved layout state instead. This is useful for widgets that are hidden by default but should be shown when the layout is restored. [#1210](https://github.com/iTwin/appui/pull/1210)
+- Added `promptAtContent` prop to `ToolAssistanceField` component. When set to `true` the prompt will be displayed only when the content area (i.e. viewport) is hovered. [#1211](https://github.com/iTwin/appui/pull/1211)
+
+### Changes
+
+- Updated `cursorPromptTimeout` prop of `ToolAssistanceField` component to handle `Number.POSITIVE_INFINITY`, which when enabled will display the cursor prompt indefinitely. [#1211](https://github.com/iTwin/appui/pull/1211)
diff --git a/docs/storybook/src/components/MessageCenterField.stories.tsx b/docs/storybook/src/components/MessageCenterField.stories.tsx
@@ -30,7 +30,7 @@ const AlignComponent: Decorator = (Story) => {
 };
 
 const meta = {
-  title: "Components/MessageCenterField",
+  title: "Components/Status fields/MessageCenterField",
   component: MessageCenterField,
   tags: ["autodocs"],
   decorators: [AlignComponent, InitializerDecorator, AppUiDecorator],

diff --git a/docs/storybook/src/components/ToolAssistanceField.stories.tsx b/docs/storybook/src/components/ToolAssistanceField.stories.tsx
@@ -0,0 +1,128 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from "react";
+import type { Decorator, Meta, StoryObj } from "@storybook/react";
+import {
+  MessageManager,
+  StatusBarItemUtilities,
+  ToolAssistanceField,
+  UiFramework,
+} from "@itwin/appui-react";
+import {
+  Tool,
+  ToolAssistance,
+  ToolAssistanceImage,
+} from "@itwin/core-frontend";
+import { AppUiStory } from "src/AppUiStory";
+import { createFrontstage } from "src/Utils";
+
+const StoryDecorator: Decorator = (Story) => {
+  return (
+    <AppUiStory
+      frontstages={[
+        createFrontstage({
+          hideStatusBar: false,
+        }),
+      ]}
+      itemProviders={[
+        {
+          id: "provider-1",
+          getStatusBarItems: () => [
+            StatusBarItemUtilities.createCustomItem({
+              id: "tool-assistance",
+              content: (
+                <>
+                  <Story />
+                  <Setup />
+                </>
+              ),
+            }),
+          ],
+        },
+      ]}
+    />
+  );
+};
+
+function Setup() {
+  React.useEffect(() => {
+    const mainInstruction = ToolAssistance.createInstruction(
+      ToolAssistanceImage.CursorClick,
+      "Main instruction of a tool"
+    );
+
+    const cursorSection = ToolAssistance.createSection(
+      [
+        ToolAssistance.createInstruction(
+          ToolAssistanceImage.LeftClick,
+          "Left click to select a point"
+        ),
+        ToolAssistance.createInstruction(
+          ToolAssistanceImage.RightClick,
+          "Right click to cancel"
+        ),
+      ],
+      ToolAssistance.inputsLabel
+    );
+
+    const touchSection = ToolAssistance.createSection(
+      [
+        ToolAssistance.createInstruction(
+          ToolAssistanceImage.OneTouchTap,
+          "Touch to select a point"
+        ),
+      ],
+      ToolAssistance.inputsLabel
+    );
+
+    const instructions = ToolAssistance.createInstructions(mainInstruction, [
+      cursorSection,
+      touchSection,
+    ]);
+    // Tool assistance information
+    MessageManager.setToolAssistance(instructions);
+
+    // Icon for the tool assistance
+    UiFramework.frontstages.setActiveTool(
+      new (class extends Tool {
+        get iconSpec(): string {
+          return "icon-placeholder";
+        }
+      })()
+    );
+  }, []);
+  return null;
+}
+
+const meta = {
+  title: "Components/Status fields/ToolAssistanceField",
+  component: ToolAssistanceField,
+  tags: ["autodocs"],
+  decorators: [StoryDecorator],
+  args: {
+    includePromptAtCursor: true,
+    cursorPromptTimeout: 5000,
+    fadeOutCursorPrompt: true,
+    defaultPromptAtCursor: true,
+  },
+} satisfies Meta<typeof ToolAssistanceField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const AlwaysVisible: Story = {
+  args: {
+    cursorPromptTimeout: Number.POSITIVE_INFINITY,
+  },
+};
+
+export const PromptAtContent: Story = {
+  args: {
+    cursorPromptTimeout: Number.POSITIVE_INFINITY,
+    promptAtContent: true,
+  },
+};
diff --git a/ui/appui-react/src/appui-react/configurableui/ConfigurableUiContent.tsx b/ui/appui-react/src/appui-react/configurableui/ConfigurableUiContent.tsx
@@ -11,7 +11,10 @@ import * as React from "react";
 import type { CommonProps } from "@itwin/core-react";
 import { Point } from "@itwin/core-react/internal";
 import { ThemeProvider } from "@itwin/itwinui-react";
-import { CursorInformation } from "../cursor/CursorInformation.js";
+import {
+  CursorInformation,
+  useCursorInformationStore,
+} from "../cursor/CursorInformation.js";
 import { CursorPopupMenu } from "../cursor/cursormenu/CursorMenu.js";
 import { CursorPopupRenderer } from "../cursor/cursorpopup/CursorPopupManager.js";
 import { ModalDialogRenderer } from "../dialog/ModalDialogManager.js";
@@ -46,7 +49,9 @@ export const ConfigurableUiContext = React.createContext<
     | "animateToolSettings"
     | "toolAsToolSettingsLabel"
     | "childWindow"
-  >
+  > & {
+    contentElementRef?: React.RefObject<HTMLElement>;
+  }
 >({});
 
 /** Properties for [[ConfigurableUiContent]]
@@ -94,6 +99,8 @@ export const WrapperContext = React.createContext<HTMLElement>(document.body);
  */
 // eslint-disable-next-line @typescript-eslint/no-deprecated
 export function ConfigurableUiContent(props: ConfigurableUiContentProps) {
+  const contentElementRef = React.useRef<HTMLElement>(null);
+
   useWidgetOpacity(props.widgetOpacity);
   useToolbarOpacity(props.toolbarOpacity);
   const [mainElement, setMainElement] = React.useState<HTMLElement>();
@@ -112,11 +119,9 @@ export function ConfigurableUiContent(props: ConfigurableUiContentProps) {
     };
   }, [props.idleTimeout, props.intervalTimeout]);
 
-  const handleMouseMove = React.useCallback((e: React.MouseEvent) => {
-    const point = new Point(e.pageX, e.pageY);
-    CursorInformation.handleMouseMove(point);
-  }, []);
-
+  const setContentHovered = useCursorInformationStore(
+    (state) => state.setContentHovered
+  );
   return (
     <ConfigurableUiContext.Provider
       value={{
@@ -128,14 +133,25 @@ export function ConfigurableUiContent(props: ConfigurableUiContentProps) {
         animateToolSettings: props.animateToolSettings,
         toolAsToolSettingsLabel: props.toolAsToolSettingsLabel,
         childWindow: props.childWindow,
+        contentElementRef,
       }}
     >
       <main
         role="main"
         id="uifw-configurableui-wrapper"
         className={props.className}
         style={props.style}
-        onMouseMove={handleMouseMove}
+        onMouseMove={(e) => {
+          const point = new Point(e.pageX, e.pageY);
+          CursorInformation.handleMouseMove(point);
+
+          if (!(e.target instanceof Node)) return;
+          const contentHovered = contentElementRef.current?.contains(e.target);
+          setContentHovered(contentHovered ?? false);
+        }}
+        onMouseLeave={() => {
+          setContentHovered(false);
+        }}
         ref={(el) => setMainElement(el ?? undefined)}
       >
         <WrapperContext.Provider value={mainElement ?? document.body}>

diff --git a/ui/appui-react/src/appui-react/cursor/CursorInformation.ts b/ui/appui-react/src/appui-react/cursor/CursorInformation.ts
@@ -6,6 +6,8 @@
  * @module Cursor
  */
 
+import { create } from "zustand";
+import { produce } from "immer";
 import type { XAndY } from "@itwin/core-geometry";
 import { RelativePosition, UiEvent } from "@itwin/appui-abstract";
 import { Point } from "@itwin/core-react/internal";
@@ -195,3 +197,20 @@ export class CursorInformation {
     this._cursorDirections.length = 0;
   }
 }
+
+/** Returns additional information about cursor.
+ * @internal
+ */
+export const useCursorInformationStore = create<{
+  contentHovered: boolean;
+  setContentHovered: (hovered: boolean) => void;
+}>((set) => ({
+  contentHovered: false,
+  setContentHovered: (hovered: boolean) => {
+    set((state) =>
+      produce(state, (draft) => {
+        draft.contentHovered = hovered;
+      })
+    );
+  },
+}));
diff --git a/ui/appui-react/src/appui-react/cursor/cursorpopup/CursorPopup.tsx b/ui/appui-react/src/appui-react/cursor/cursorpopup/CursorPopup.tsx
@@ -96,7 +96,7 @@ export class CursorPopup extends React.Component<
   > = (args) => {
     if (this.props.id === args.id) {
       if (this._isMounted)
-        this.setState({ showPopup: CursorPopupShow.FadeOut });
+        this.setState({ showPopup: args.show ?? CursorPopupShow.FadeOut });
     }
   };