feat: Add bottom toolbar positions to ToolbarUsage and render them in the standard layout

.changeset/bottom-toolbar-positions.md

@@ -0,0 +1,5 @@
+---
+"@itwin/appui-react": minor
+---
+
+Added `BottomContentManipulation` and `BottomViewNavigation` values to the `ToolbarUsage` enum. The standard layout now automatically renders bottom toolbar positions when a `UiItemsProvider` returns items with these usages — no custom overlay component is needed.

common/api/appui-react.api.md

@@ -655,6 +655,21 @@ export interface BasicToolWidgetProps {
     showCategoryAndModelsContextTools?: boolean;
 }
 
+// @public
+export function BottomContentToolWidgetComposer(): React_2.JSX.Element;
+
+// @public
+export function BottomToolWidgetComposer(props: BottomToolWidgetComposerProps): React_2.JSX.Element | null;
+
+// @public
+export interface BottomToolWidgetComposerProps {
+    horizontalToolbar?: React_2.ReactNode;
+    verticalToolbar?: React_2.ReactNode;
+}
+
+// @public
+export function BottomViewToolWidgetComposer(): React_2.JSX.Element;
+
 // @alpha
 export class BumpToolSetting extends Tool {
     // (undocumented)
@@ -2276,7 +2291,9 @@ export interface FrontstageActivatedEventArgs {
 
 // @public @deprecated
 export interface FrontstageConfig extends CommonProps {
+    readonly bottomContentManipulation?: WidgetConfig;
     readonly bottomPanel?: StagePanelConfig;
+    readonly bottomViewNavigation?: WidgetConfig;
     readonly contentGroup: ContentGroup | ContentGroupProvider;
     readonly contentManipulation?: WidgetConfig;
     readonly defaultTool?: string;
@@ -2317,7 +2334,11 @@ export class FrontstageDef {
     // @internal
     batch(fn: () => void): void;
     // (undocumented)
+    get bottomContentManipulation(): WidgetDef | undefined;
+    // (undocumented)
     get bottomPanel(): StagePanelDef | undefined;
+    // (undocumented)
+    get bottomViewNavigation(): WidgetDef | undefined;
     // @deprecated
     get contentControls(): ContentControl[];
     // (undocumented)
@@ -4958,6 +4979,8 @@ export interface ToolbarProps extends CommonProps, NoChildrenProps {
 
 // @public
 export enum ToolbarUsage {
+    BottomContentManipulation = 2,
+    BottomViewNavigation = 3,
     ContentManipulation = 0,
     ViewNavigation = 1
 }
@@ -5427,7 +5450,7 @@ export function useUiStateStorageHandler(): UiStateStorage;
 // @public
 export function useWidget(): {
     state: WidgetState;
-    widgetLocation: "popout" | "docked" | "floating";
+    widgetLocation: "docked" | "floating" | "popout";
     setState: (widgetState: Omit<WidgetState, WidgetState.Floating>) => void;
 };
 

common/api/summary/appui-react.exports.csv

@@ -96,6 +96,10 @@ deprecated;interface;BasicNavigationWidgetProps
 public;function;BasicToolWidget
 public;interface;BasicToolWidgetProps
 deprecated;interface;BasicToolWidgetProps
+public;function;BottomContentToolWidgetComposer
+public;function;BottomToolWidgetComposer
+public;interface;BottomToolWidgetComposerProps
+public;function;BottomViewToolWidgetComposer
 alpha;class;BumpToolSetting
 public;class;Calculator
 public;class;CalculatorPopup

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

@@ -812,6 +812,12 @@ export {
   ContentToolWidgetComposer,
   ContentToolWidgetComposerProps,
 } from "./appui-react/widgets/ContentToolWidgetComposer.js";
+export { BottomContentToolWidgetComposer } from "./appui-react/widgets/BottomContentToolWidgetComposer.js";
+export {
+  BottomToolWidgetComposer,
+  BottomToolWidgetComposerProps,
+} from "./appui-react/widgets/BottomToolWidgetComposer.js";
+export { BottomViewToolWidgetComposer } from "./appui-react/widgets/BottomViewToolWidgetComposer.js";
 export {
   NavigationAidHost,
   NavigationWidgetComposer,

ui/appui-react/src/appui-react/frontstage/FrontstageConfig.ts

@@ -50,6 +50,10 @@ export interface FrontstageConfig extends CommonProps {
   };
   /** The top-right corner that shows view navigation tools. */
   readonly viewNavigation?: WidgetConfig;
+  /** The bottom-left corner that shows tools typically used to query and modify content. */
+  readonly bottomContentManipulation?: WidgetConfig;
+  /** The bottom-right corner that shows view navigation tools. */
+  readonly bottomViewNavigation?: WidgetConfig;
   /** The status bar of the application. */
   readonly statusBar?: WidgetConfig;
 

ui/appui-react/src/appui-react/frontstage/FrontstageDef.tsx

@@ -80,6 +80,8 @@ export class FrontstageDef {
   private _statusBar?: WidgetDef;
   private _contentManipulation?: WidgetDef;
   private _viewNavigation?: WidgetDef;
+  private _bottomContentManipulation?: WidgetDef;
+  private _bottomViewNavigation?: WidgetDef;
   private _topPanel?: StagePanelDef;
   private _leftPanel?: StagePanelDef;
   private _rightPanel?: StagePanelDef;
@@ -130,6 +132,12 @@ export class FrontstageDef {
   public get viewNavigation(): WidgetDef | undefined {
     return this._viewNavigation;
   }
+  public get bottomContentManipulation(): WidgetDef | undefined {
+    return this._bottomContentManipulation;
+  }
+  public get bottomViewNavigation(): WidgetDef | undefined {
+    return this._bottomViewNavigation;
+  }
 
   public get topPanel(): StagePanelDef | undefined {
     return this._topPanel;
@@ -600,6 +608,14 @@ export class FrontstageDef {
       config.viewNavigation,
       WidgetType.Navigation
     );
+    this._bottomContentManipulation = createWidgetDef(
+      config.bottomContentManipulation,
+      WidgetType.Tool
+    );
+    this._bottomViewNavigation = createWidgetDef(
+      config.bottomViewNavigation,
+      WidgetType.Navigation
+    );
     this._topPanel = createStagePanelDef(config, StagePanelLocation.Top);
     this._leftPanel = createStagePanelDef(config, StagePanelLocation.Left);
     this._rightPanel = createStagePanelDef(config, StagePanelLocation.Right);

ui/appui-react/src/appui-react/toolbar/ToolbarComposer.tsx

@@ -257,10 +257,20 @@ export function ToolbarComposer(props: ExtensibleToolbarProps) {
 
 function toExpandsTo(orientation: ToolbarOrientation, usage: ToolbarUsage) {
   if (orientation === ToolbarOrientation.Vertical) {
-    if (usage === ToolbarUsage.ViewNavigation) return Direction.Left;
+    if (
+      usage === ToolbarUsage.ViewNavigation ||
+      usage === ToolbarUsage.BottomViewNavigation
+    )
+      return Direction.Left;
     return Direction.Right;
   }
 
+  if (
+    usage === ToolbarUsage.BottomContentManipulation ||
+    usage === ToolbarUsage.BottomViewNavigation
+  )
+    return Direction.Top;
+
   return Direction.Bottom;
 }
 
@@ -270,7 +280,8 @@ function toPanelAlignment(
 ) {
   if (
     orientation === ToolbarOrientation.Horizontal &&
-    usage === ToolbarUsage.ViewNavigation
+    (usage === ToolbarUsage.ViewNavigation ||
+      usage === ToolbarUsage.BottomViewNavigation)
   )
     return ToolbarPanelAlignment.End;
 

ui/appui-react/src/appui-react/toolbar/ToolbarItem.ts

@@ -22,6 +22,10 @@ export enum ToolbarUsage {
   ContentManipulation = 0,
   /** Manipulate view/camera - in AppUI this is in top right of content area. */
   ViewNavigation = 1,
+  /** Contains tools to Create Update and Delete content - rendered in bottom left of content area. */
+  BottomContentManipulation = 2,
+  /** Manipulate view/camera - rendered in bottom right of content area. */
+  BottomViewNavigation = 3,
 }
 
 /** Used to specify the orientation of the toolbar.

ui/appui-react/src/appui-react/widget-panels/Toolbars.scss

@@ -11,12 +11,59 @@
   ); // TODO: Change this to an AppUI global CSS variable.
   box-sizing: border-box;
   grid-template-columns: 1fr 1fr;
+  grid-template-rows: auto 1fr auto;
 
   .nz-tools-widget {
     grid-column: 1;
+    grid-row: 1;
 
     &.nz-widget-navigationArea {
       grid-column: 2;
+      grid-row: 1;
+    }
+  }
+
+  .uifw-widgetPanels-bottomToolbars {
+    grid-column: 1 / -1;
+    grid-row: 3;
+    display: flex;
+    justify-content: space-between;
+    align-items: flex-end;
+    pointer-events: none;
+
+    > * {
+      pointer-events: auto;
+    }
+  }
+
+  .uifw-bottom-toolArea {
+    display: grid;
+    grid-gap: 6px;
+    grid-template-areas:
+      "vtools ."
+      "vtools htools";
+    grid-template-columns: auto 1fr;
+    grid-template-rows: 1fr auto;
+    align-items: end;
+    justify-items: start;
+  }
+
+  .uifw-bottom-toolArea_vertical {
+    grid-area: vtools;
+    display: inline-flex;
+    flex-direction: column;
+  }
+
+  .uifw-bottom-toolArea_horizontal {
+    grid-area: htools;
+    min-width: 0;
+  }
+
+  .uifw-bottom-toolArea_right {
+    margin-left: auto;
+
+    .uifw-bottom-toolArea {
+      justify-items: end;
     }
   }
 }

ui/appui-react/src/appui-react/widget-panels/Toolbars.tsx

@@ -16,10 +16,22 @@ export function WidgetPanelsToolbars() {
   const frontstageDef = useActiveFrontstageDef();
   const tools = frontstageDef?.contentManipulation?.reactNode;
   const navigation = frontstageDef?.viewNavigation?.reactNode;
+  const bottomTools = frontstageDef?.bottomContentManipulation?.reactNode;
+  const bottomNavigation = frontstageDef?.bottomViewNavigation?.reactNode;
   return (
     <div className="uifw-widgetPanels-toolbars">
       {tools}
       <NavigationWidget>{navigation}</NavigationWidget>
+      {(bottomTools || bottomNavigation) && (
+        <div className="uifw-widgetPanels-bottomToolbars">
+          {bottomTools}
+          {bottomNavigation && (
+            <div className="uifw-bottom-toolArea_right">
+              {bottomNavigation}
+            </div>
+          )}
+        </div>
+      )}
     </div>
   );
 }

ui/appui-react/src/appui-react/widgets/BottomContentToolWidgetComposer.tsx

@@ -0,0 +1,39 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Widget
+ */
+
+import * as React from "react";
+import { ToolbarComposer } from "../toolbar/ToolbarComposer.js";
+import { BottomToolWidgetComposer } from "./BottomToolWidgetComposer.js";
+import { ToolbarOrientation, ToolbarUsage } from "../toolbar/ToolbarItem.js";
+
+/**
+ * BottomContentToolWidgetComposer composes a bottom-left Tool Widget with no tools defined by default.
+ * UiItemsProviders are used to populate the toolbars by providing items with
+ * `ToolbarUsage.BottomContentManipulation`.
+ * @public
+ */
+export function BottomContentToolWidgetComposer() {
+  return (
+    <BottomToolWidgetComposer
+      horizontalToolbar={
+        <ToolbarComposer
+          items={[]}
+          usage={ToolbarUsage.BottomContentManipulation}
+          orientation={ToolbarOrientation.Horizontal}
+        />
+      }
+      verticalToolbar={
+        <ToolbarComposer
+          items={[]}
+          usage={ToolbarUsage.BottomContentManipulation}
+          orientation={ToolbarOrientation.Vertical}
+        />
+      }
+    />
+  );
+}

ui/appui-react/src/appui-react/widgets/BottomToolWidgetComposer.tsx

@@ -0,0 +1,86 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Widget
+ */
+
+import "../widget-panels/Toolbars.scss";
+import * as React from "react";
+import {
+  useProximityToMouse,
+  WidgetElementSet,
+  WidgetOpacityContext,
+} from "@itwin/core-react/internal";
+import { UiFramework } from "../UiFramework.js";
+import { useUiVisibility } from "../hooks/useUiVisibility.js";
+
+/** Properties for {@link BottomToolWidgetComposer}.
+ * @public
+ */
+export interface BottomToolWidgetComposerProps {
+  /** Optional Horizontal Toolbar */
+  horizontalToolbar?: React.ReactNode;
+  /** Optional Vertical Toolbar */
+  verticalToolbar?: React.ReactNode;
+}
+
+/**
+ * BottomToolWidgetComposer renders an L-shaped toolbar area anchored to the bottom of the content area.
+ * The vertical toolbar grows upward and the horizontal toolbar is positioned at the bottom,
+ * offset by the vertical toolbar's width.
+ * @public
+ */
+export function BottomToolWidgetComposer(
+  props: BottomToolWidgetComposerProps
+) {
+  const { horizontalToolbar, verticalToolbar } = props;
+  const [elementSet] = React.useState(new WidgetElementSet());
+  const proximityScale = useProximityToMouse(
+    elementSet,
+    UiFramework.visibility.snapWidgetOpacity
+  );
+  const uiIsVisible = useUiVisibility();
+
+  const addRef = React.useCallback<
+    React.ContextType<typeof WidgetOpacityContext>["addRef"]
+  >(
+    (ref) => {
+      elementSet.add(ref);
+    },
+    [elementSet]
+  );
+  const removeRef = React.useCallback<
+    React.ContextType<typeof WidgetOpacityContext>["removeRef"]
+  >(
+    (ref) => {
+      elementSet.delete(ref);
+    },
+    [elementSet]
+  );
+
+  if (!uiIsVisible) return null;
+
+  return (
+    <WidgetOpacityContext.Provider
+      value={{
+        addRef,
+        removeRef,
+        proximityScale,
+      }}
+    >
+      <div
+        className="uifw-bottom-toolArea"
+        onMouseEnter={UiFramework.visibility.handleWidgetMouseEnter}
+      >
+        <div className="uifw-bottom-toolArea_vertical">
+          {verticalToolbar}
+        </div>
+        <div className="uifw-bottom-toolArea_horizontal">
+          {horizontalToolbar}
+        </div>
+      </div>
+    </WidgetOpacityContext.Provider>
+  );
+}