feat(action-bar, action-pad, block, flow-item, panel): add overlayPositioning prop for built-in menus (#8633)

**Related Issue:** #8620

## Summary

This allows users to specify `overlayPositioning` to help escape
scrolling containers for underlying menus.

**Note**: this adds a new helper
(`delegatesToFloatingUiOwningComponent`) to shallowly test if a
component has a floating-ui-owning component wired up.

Author: jcfranco

packages/calcite-components/src/components.d.ts

@@ -9,8 +9,8 @@ import { Alignment, Appearance, Columns, FlipContext, Kind, Layout, LogicalFlowP
 import { RequestedItem } from "./components/accordion/interfaces";
 import { RequestedItem as RequestedItem1 } from "./components/accordion-item/interfaces";
 import { ActionMessages } from "./components/action/assets/action/t9n";
-import { ActionBarMessages } from "./components/action-bar/assets/action-bar/t9n";
 import { EffectivePlacement, LogicalPlacement, MenuPlacement, OverlayPositioning, ReferenceElement } from "./utils/floating-ui";
+import { ActionBarMessages } from "./components/action-bar/assets/action-bar/t9n";
 import { ActionGroupMessages } from "./components/action-group/assets/action-group/t9n";
 import { ActionPadMessages } from "./components/action-pad/assets/action-pad/t9n";
 import { AlertDuration, Sync } from "./components/alert/interfaces";
@@ -95,8 +95,8 @@ export { Alignment, Appearance, Columns, FlipContext, Kind, Layout, LogicalFlowP
 export { RequestedItem } from "./components/accordion/interfaces";
 export { RequestedItem as RequestedItem1 } from "./components/accordion-item/interfaces";
 export { ActionMessages } from "./components/action/assets/action/t9n";
-export { ActionBarMessages } from "./components/action-bar/assets/action-bar/t9n";
 export { EffectivePlacement, LogicalPlacement, MenuPlacement, OverlayPositioning, ReferenceElement } from "./utils/floating-ui";
+export { ActionBarMessages } from "./components/action-bar/assets/action-bar/t9n";
 export { ActionGroupMessages } from "./components/action-group/assets/action-group/t9n";
 export { ActionPadMessages } from "./components/action-pad/assets/action-pad/t9n";
 export { AlertDuration, Sync } from "./components/alert/interfaces";
@@ -344,6 +344,10 @@ export namespace Components {
           * Disables automatically overflowing `calcite-action`s that won't fit into menus.
          */
         "overflowActionsDisabled": boolean;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning": OverlayPositioning;
         /**
           * Arranges the component depending on the element's `dir` property.
          */
@@ -463,6 +467,10 @@ export namespace Components {
           * Made into a prop for testing purposes only
          */
         "messages": ActionPadMessages;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning": OverlayPositioning;
         /**
           * Arranges the component depending on the element's `dir` property.
          */
@@ -604,6 +612,10 @@ export namespace Components {
           * When `true`, expands the component and its contents.
          */
         "open": boolean;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning": OverlayPositioning;
         /**
           * Sets focus on the component's first tabbable element.
          */
@@ -1724,6 +1736,10 @@ export namespace Components {
           * Made into a prop for testing purposes only
          */
         "messages": FlowItemMessages;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning": OverlayPositioning;
         /**
           * Scrolls the component's content to a specified set of coordinates.
           * @example myCalciteFlowItem.scrollContentTo({   left: 0, // Specifies the number of pixels along the X axis to scroll the window or element.   top: 0, // Specifies the number of pixels along the Y axis to scroll the window or element   behavior: "auto" // Specifies whether the scrolling should animate smoothly (smooth), or happen instantly in a single jump (auto, the default value). });
@@ -3433,6 +3449,10 @@ export namespace Components {
           * Made into a prop for testing purposes only
          */
         "messages": PanelMessages;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning": OverlayPositioning;
         /**
           * Scrolls the component's content to a specified set of coordinates.
           * @example myCalciteFlowItem.scrollContentTo({   left: 0, // Specifies the number of pixels along the X axis to scroll the window or element.   top: 0, // Specifies the number of pixels along the Y axis to scroll the window or element   behavior: "auto" // Specifies whether the scrolling should animate smoothly (smooth), or happen instantly in a single jump (auto, the default value). });
@@ -7567,6 +7587,10 @@ declare namespace LocalJSX {
           * Disables automatically overflowing `calcite-action`s that won't fit into menus.
          */
         "overflowActionsDisabled"?: boolean;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning"?: OverlayPositioning;
         /**
           * Arranges the component depending on the element's `dir` property.
          */
@@ -7682,6 +7706,10 @@ declare namespace LocalJSX {
           * Fires when the `expanded` property is toggled.
          */
         "onCalciteActionPadToggle"?: (event: CalciteActionPadCustomEvent<void>) => void;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning"?: OverlayPositioning;
         /**
           * Arranges the component depending on the element's `dir` property.
          */
@@ -7860,6 +7888,10 @@ declare namespace LocalJSX {
           * When `true`, expands the component and its contents.
          */
         "open"?: boolean;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning"?: OverlayPositioning;
         /**
           * Displays a status-related indicator icon.
          */
@@ -9053,6 +9085,10 @@ declare namespace LocalJSX {
           * Fires when the collapse button is clicked.
          */
         "onCalciteFlowItemToggle"?: (event: CalciteFlowItemCustomEvent<void>) => void;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning"?: OverlayPositioning;
         /**
           * When `true`, displays a back button in the component's header.
          */
@@ -10863,6 +10899,10 @@ declare namespace LocalJSX {
           * Fires when the collapse button is clicked.
          */
         "onCalcitePanelToggle"?: (event: CalcitePanelCustomEvent<void>) => void;
+        /**
+          * Determines the type of positioning to use for the overlaid content.  Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.  `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+         */
+        "overlayPositioning"?: OverlayPositioning;
     }
     /**
      * @deprecated Use the `list` component instead.

packages/calcite-components/src/components/action-bar/action-bar.e2e.ts

@@ -1,6 +1,16 @@
 import { newE2EPage } from "@stencil/core/testing";
 import { html } from "../../../support/formatting";
-import { accessible, defaults, focusable, hidden, reflects, renders, slots, t9n } from "../../tests/commonTests";
+import {
+  accessible,
+  defaults,
+  delegatesToFloatingUiOwningComponent,
+  focusable,
+  hidden,
+  reflects,
+  renders,
+  slots,
+  t9n,
+} from "../../tests/commonTests";
 import { CSS, SLOTS } from "./resources";
 import { overflowActionsDebounceInMs } from "./utils";
 import { getFocusedElementProp } from "../../tests/utils";
@@ -32,6 +42,10 @@ describe("calcite-action-bar", () => {
         propertyName: "layout",
         defaultValue: "vertical",
       },
+      {
+        propertyName: "overlayPositioning",
+        defaultValue: "absolute",
+      },
     ]);
   });
 
@@ -45,9 +59,22 @@ describe("calcite-action-bar", () => {
         propertyName: "expanded",
         value: true,
       },
+      {
+        propertyName: "overlayPositioning",
+        value: "fixed",
+      },
     ]);
   });
 
+  describe("delegates to floating-ui-owner component", () => {
+    delegatesToFloatingUiOwningComponent(
+      html`<calcite-action-bar>
+        <calcite-action id="plus" slot="menu-actions" text="Add" icon="plus"></calcite-action>
+      </calcite-action-bar>`,
+      "calcite-action-group",
+    );
+  });
+
   describe("expand functionality", () => {
     it("should not modify actions within an action-menu", async () => {
       const page = await newE2EPage({

packages/calcite-components/src/components/action-bar/action-bar.tsx

@@ -48,6 +48,7 @@ import {
   overflowActionsDebounceInMs,
   queryActions,
 } from "./utils";
+import { OverlayPositioning } from "../../utils/floating-ui";
 
 /**
  * @slot - A slot for adding `calcite-action`s that will appear at the top of the component.
@@ -123,6 +124,16 @@ export class ActionBar
     this.overflowActions();
   }
 
+  /**
+   * Determines the type of positioning to use for the overlaid content.
+   *
+   * Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.
+   *
+   * `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+   *
+   */
+  @Prop({ reflect: true }) overlayPositioning: OverlayPositioning = "absolute";
+
   /**
    * Arranges the component depending on the element's `dir` property.
    */
@@ -391,6 +402,7 @@ export class ActionBar
       layout,
       messages,
       actionsEndGroupLabel,
+      overlayPositioning,
     } = this;
 
     const expandToggleNode = !expandDisabled ? (
@@ -414,6 +426,7 @@ export class ActionBar
         hidden={this.expandDisabled && !(this.hasActionsEnd || this.hasBottomActions)}
         label={actionsEndGroupLabel}
         layout={layout}
+        overlayPositioning={overlayPositioning}
         scale={scale}
       >
         <slot name={SLOTS.actionsEnd} onSlotchange={this.handleActionsEndSlotChange} />

packages/calcite-components/src/components/action-menu/action-menu.e2e.ts

@@ -1,6 +1,15 @@
 import { newE2EPage } from "@stencil/core/testing";
 import { html } from "../../../support/formatting";
-import { accessible, defaults, focusable, hidden, reflects, renders, slots } from "../../tests/commonTests";
+import {
+  accessible,
+  defaults,
+  delegatesToFloatingUiOwningComponent,
+  focusable,
+  hidden,
+  reflects,
+  renders,
+  slots,
+} from "../../tests/commonTests";
 import { TOOLTIP_OPEN_DELAY_MS } from "../tooltip/resources";
 import { CSS, SLOTS, activeAttr } from "./resources";
 
@@ -84,6 +93,15 @@ describe("calcite-action-menu", () => {
     ]);
   });
 
+  describe("delegates to floating-ui-owner component", () => {
+    delegatesToFloatingUiOwningComponent(
+      html`<calcite-action-menu>
+        <calcite-action text="Plus" icon="plus" text-enabled></calcite-action>
+      </calcite-action-menu>`,
+      "calcite-popover",
+    );
+  });
+
   it("should emit 'calciteActionMenuOpen' event", async () => {
     const page = await newE2EPage({
       html: `<calcite-action-menu>

packages/calcite-components/src/components/action-pad/action-pad.e2e.ts

@@ -1,5 +1,15 @@
 import { newE2EPage } from "@stencil/core/testing";
-import { accessible, defaults, focusable, hidden, reflects, renders, slots, t9n } from "../../tests/commonTests";
+import {
+  accessible,
+  defaults,
+  delegatesToFloatingUiOwningComponent,
+  focusable,
+  hidden,
+  reflects,
+  renders,
+  slots,
+  t9n,
+} from "../../tests/commonTests";
 import { CSS, SLOTS } from "./resources";
 import { html } from "../../../support/formatting";
 
@@ -26,6 +36,10 @@ describe("calcite-action-pad", () => {
         propertyName: "layout",
         defaultValue: "vertical",
       },
+      {
+        propertyName: "overlayPositioning",
+        defaultValue: "absolute",
+      },
       {
         propertyName: "scale",
         defaultValue: undefined,
@@ -47,9 +61,22 @@ describe("calcite-action-pad", () => {
         propertyName: "layout",
         value: "horizontal",
       },
+      {
+        propertyName: "overlayPositioning",
+        value: "fixed",
+      },
     ]);
   });
 
+  describe("delegates to floating-ui-owner component", () => {
+    delegatesToFloatingUiOwningComponent(
+      html`<calcite-action-pad>
+        <calcite-action id="plus" slot="menu-actions" text="Add" icon="plus"></calcite-action>
+      </calcite-action-pad>`,
+      "calcite-action-group",
+    );
+  });
+
   describe("expand functionality", () => {
     it("should be expandable by default", async () => {
       const page = await newE2EPage();

packages/calcite-components/src/components/action-pad/action-pad.tsx

@@ -36,6 +36,7 @@ import { Layout, Position, Scale } from "../interfaces";
 import { ActionPadMessages } from "./assets/action-pad/t9n";
 import { CSS, SLOTS } from "./resources";
 import { createObserver } from "../../utils/observers";
+import { OverlayPositioning } from "../../utils/floating-ui";
 
 /**
  * @slot - A slot for adding `calcite-action`s to the component.
@@ -117,6 +118,16 @@ export class ActionPad
     /* wired up by t9n util */
   }
 
+  /**
+   * Determines the type of positioning to use for the overlaid content.
+   *
+   * Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.
+   *
+   * `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
+   *
+   */
+  @Prop({ reflect: true }) overlayPositioning: OverlayPositioning = "absolute";
+
   // --------------------------------------------------------------------------
   //
   //  Events
@@ -265,6 +276,7 @@ export class ActionPad
       scale,
       layout,
       actionsEndGroupLabel,
+      overlayPositioning,
     } = this;
 
     const expandToggleNode = !expandDisabled ? (
@@ -287,6 +299,7 @@ export class ActionPad
         class={CSS.actionGroupEnd}
         label={actionsEndGroupLabel}
         layout={layout}
+        overlayPositioning={overlayPositioning}
         scale={scale}
       >
         <slot name={SLOTS.expandTooltip} onSlotchange={this.handleTooltipSlotChange} />