Add advancedUsage to standard layout of ToolbarItem

.changeset/afraid-signs-rush.md

@@ -0,0 +1,20 @@
+---
+"@itwin/appui-react": minor
+---
+
+Added `ToolbarAdvancedUsage` non-exhaustive string literal union type used in `advancedUsage` property of `StandardLayoutToolbarItem` interface.
+This property takes precedence over enum based `usage` property and allows specifying advanced toolbar item usage scenarios.
+When set to `"view-settings"` it positions the toolbar item at the bottom-right of the content area in the default standard layout configuration.
+
+```tsx
+ToolbarItemUtilities.createActionItem({
+  id: "action",
+  layouts: {
+    standard: {
+      usage: ToolbarUsage.ViewNavigation,
+      advancedUsage: "view-settings",
+      orientation: ToolbarOrientation.Horizontal,
+    },
+  },
+});
+```

common/api/appui-react.api.md

@@ -1804,6 +1804,7 @@ export interface ExpandableSectionProps extends CommonProps {
 // @public @deprecated
 export interface ExtensibleToolbarProps {
     activeItemIds?: string[];
+    advancedUsage?: ToolbarAdvancedUsage;
     items: ToolbarItem[];
     orientation: ToolbarOrientation;
     usage: ToolbarUsage;
@@ -3412,6 +3413,8 @@ export interface NavigationWidgetComposerProps extends CommonProps {
     hideNavigationAid?: boolean;
     horizontalToolbar?: React_2.ReactNode;
     navigationAidHost?: React_2.ReactNode;
+    secondaryHorizontalToolbar?: React_2.ReactNode;
+    secondaryVerticalToolbar?: React_2.ReactNode;
     verticalToolbar?: React_2.ReactNode;
 }
 
@@ -4326,6 +4329,7 @@ export function StandardLayout(props: StandardLayoutProps): React_2.JSX.Element;
 
 // @public
 export interface StandardLayoutToolbarItem {
+    readonly advancedUsage?: ToolbarAdvancedUsage;
     readonly orientation: ToolbarOrientation;
     readonly usage: ToolbarUsage;
 }
@@ -4755,6 +4759,9 @@ export interface ToolbarActionItem extends CommonToolbarItem {
     readonly parentGroupItemId?: string;
 }
 
+// @public
+export type ToolbarAdvancedUsage = "view-settings" | (string & {});
+
 // @public
 export class ToolbarButtonHelper {
     static getAppButton(): HTMLButtonElement | null;

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

@@ -681,6 +681,7 @@ public;interface;ToolAssistanceFieldProps
 beta;function;Toolbar
 public;const;TOOLBAR_OPACITY_DEFAULT
 public;interface;ToolbarActionItem
+public;type;ToolbarAdvancedUsage
 public;class;ToolbarButtonHelper
 public;function;ToolbarComposer
 public;interface;ToolbarCustomItem

docs/storybook/src/Utils.tsx

@@ -2,6 +2,7 @@
  * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
+import { action } from "storybook/actions";
 import type { ArgTypes } from "@storybook/react-vite";
 import {
   ContentProps,
@@ -12,6 +13,11 @@ import {
   StageUsage,
   StandardContentLayouts,
   StandardFrontstageProps,
+  ToolbarActionItem,
+  ToolbarGroupItem,
+  ToolbarItemUtilities,
+  ToolbarOrientation,
+  ToolbarUsage,
   Widget,
 } from "@itwin/appui-react";
 import { SvgPlaceholder } from "@itwin/itwinui-icons-react";
@@ -110,3 +116,44 @@ export function createWidget(id: number, overrides?: Partial<Widget>): Widget {
     ...overrides,
   };
 }
+
+export function createToolbarItemFactory() {
+  let i = 0;
+  function createActionItem(
+    overrides?: Omit<Partial<ToolbarActionItem>, "icon">
+  ) {
+    const id = `item${++i}`;
+    const label = `Item ${i}`;
+    return ToolbarItemUtilities.createActionItem({
+      id,
+      label,
+      icon: <SvgPlaceholder />,
+      execute: () => action(label)(),
+      layouts: {
+        standard: {
+          usage: ToolbarUsage.ContentManipulation,
+          orientation: ToolbarOrientation.Horizontal,
+        },
+      },
+      ...overrides,
+    });
+  }
+
+  function createGroupItem(
+    overrides?: Omit<Partial<ToolbarGroupItem>, "icon">
+  ) {
+    const id = `group${++i}`;
+    const label = `Group ${i}`;
+    return ToolbarItemUtilities.createGroupItem({
+      id,
+      label,
+      icon: <SvgPlaceholder />,
+      ...overrides,
+    });
+  }
+
+  return {
+    createActionItem,
+    createGroupItem,
+  };
+}

docs/storybook/src/components/ToolbarComposer.stories.tsx

@@ -11,8 +11,6 @@ import {
 import {
   CommandItemDef,
   ToolItemDef,
-  ToolbarActionItem,
-  ToolbarGroupItem,
   ToolbarHelper,
   ToolbarItemUtilities,
   ToolbarOrientation,
@@ -36,7 +34,10 @@ import placeholderIcon from "@bentley/icons-generic/icons/placeholder.svg";
 import { AppUiDecorator, InitializerDecorator } from "../Decorators";
 import { withResizer } from "../../.storybook/addons/Resizer";
 import { createBumpEvent } from "../createBumpEvent";
-import { enumArgType } from "../Utils";
+import {
+  enumArgType,
+  createToolbarItemFactory as createItemFactory,
+} from "../Utils";
 import { ToolbarComposerStory } from "./ToolbarComposer";
 
 const meta = {
@@ -573,41 +574,6 @@ function createAbstractConditionalIcon() {
   };
 }
 
-function createItemFactory() {
-  let i = 0;
-  function createActionItem(
-    overrides?: Omit<Partial<ToolbarActionItem>, "icon">
-  ) {
-    const id = `item${++i}`;
-    const label = `Item ${i}`;
-    return ToolbarItemUtilities.createActionItem({
-      id,
-      label,
-      icon: <SvgPlaceholder />,
-      execute: () => action(label)(),
-      ...overrides,
-    });
-  }
-
-  function createGroupItem(
-    overrides?: Omit<Partial<ToolbarGroupItem>, "icon">
-  ) {
-    const id = `group${++i}`;
-    const label = `Group ${i}`;
-    return ToolbarItemUtilities.createGroupItem({
-      id,
-      label,
-      icon: <SvgPlaceholder />,
-      ...overrides,
-    });
-  }
-
-  return {
-    createActionItem,
-    createGroupItem,
-  };
-}
-
 function createItems() {
   const action1 = ToolbarItemUtilities.createActionItem(
     "item1",