feat(dialog): add focusTrapDisabled property for non-modal dialogs (#11362)

**Related Issue:** #10685

## Summary
Add `focusTrapDisabled` attribute to for non-`modal` `dialog`s.

Author: Elijbet

packages/calcite-components/src/components/dialog/dialog.e2e.ts

@@ -1,6 +1,6 @@
 // @ts-strict-ignore
 import { newE2EPage, E2EPage } from "@arcgis/lumina-compiler/puppeteerTesting";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   accessible,
   defaults,
@@ -1160,4 +1160,126 @@ describe("calcite-dialog", () => {
       expect(await dialog.getProperty("open")).toBe(true);
     });
   });
+
+  describe("focusTrap behavior for modal dialogs", () => {
+    let page: E2EPage;
+
+    beforeEach(async () => {
+      page = await newE2EPage();
+      await page.setContent(html`
+        <calcite-dialog modal width-scale="s" open closable><button id="insideEl">inside</button></calcite-dialog>
+        <button id="outsideEl">outside</button>
+      `);
+
+      await skipAnimations(page);
+      await page.waitForChanges();
+    });
+
+    it("cannot tab out of dialog when modal=true and focusTrapDisabled=true", async () => {
+      const dialog = await page.find("calcite-dialog");
+      const insideEl = await page.find("#insideEl");
+
+      dialog.setProperty("focusTrapDisabled", true);
+
+      await page.waitForChanges();
+
+      expect(await dialog.isVisible()).toBe(true);
+
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+
+      const activeElementId = await page.evaluate(() => document.activeElement.id);
+      expect(activeElementId).toBe(await insideEl.getProperty("id"));
+    });
+
+    it("cannot tab out of dialog when modal=true and focusTrapDisabled=false", async () => {
+      const dialog = await page.find("calcite-dialog");
+      const action = await page.find("calcite-dialog >>> calcite-action");
+      const insideEl = await page.find("#insideEl");
+
+      dialog.setProperty("focusTrapDisabled", false);
+
+      await page.waitForChanges();
+
+      expect(await dialog.isVisible()).toBe(true);
+
+      await action.callMethod("setFocus");
+      await page.waitForChanges();
+
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+
+      const activeElementId = await page.evaluate(() => document.activeElement.id);
+      expect(activeElementId).toBe(await insideEl.getProperty("id"));
+    });
+  });
+
+  describe("focusTrap behavior for non-modal dialogs", () => {
+    let page: E2EPage;
+
+    beforeEach(async () => {
+      page = await newE2EPage();
+      await page.setContent(html`
+        <calcite-dialog width-scale="s" open closable><button id="insideEl">inside</button></calcite-dialog>
+        <button id="outsideEl">outside</button>
+      `);
+
+      await skipAnimations(page);
+      await page.waitForChanges();
+    });
+
+    it("can tab out of non-modal dialog when focusTrapDisabled=true", async () => {
+      const dialog = await page.find("calcite-dialog");
+      const action = await page.find("calcite-dialog >>> calcite-action");
+      const outsideEl = await page.find("#outsideEl");
+
+      dialog.setProperty("focusTrapDisabled", true);
+
+      await page.waitForChanges();
+
+      expect(await dialog.isVisible()).toBe(true);
+
+      await action.callMethod("setFocus");
+      await page.waitForChanges();
+
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+
+      const activeElementId = await page.evaluate(() => document.activeElement.id);
+      expect(activeElementId).toBe(await outsideEl.getProperty("id"));
+    });
+
+    it("cannot tab out of non-modal dialog when focusTrapDisabled=false", async () => {
+      const dialog = await page.find("calcite-dialog");
+      const action = await page.find("calcite-dialog >>> calcite-action");
+      const insideEl = await page.find("#insideEl");
+
+      dialog.setProperty("focusTrapDisabled", false);
+
+      await page.waitForChanges();
+
+      expect(await dialog.isVisible()).toBe(true);
+
+      await action.callMethod("setFocus");
+      await page.waitForChanges();
+
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+      await page.keyboard.press("Tab");
+      await page.waitForChanges();
+
+      const activeElementId = await page.evaluate(() => document.activeElement.id);
+      expect(activeElementId).toBe(await insideEl.getProperty("id"));
+    });
+  });
 });

packages/calcite-components/src/components/dialog/dialog.tsx

@@ -192,6 +192,9 @@ export class Dialog extends LitElement implements OpenCloseComponent, LoadableCo
   /** When `true`, displays a scrim blocking interaction underneath the component. */
   @property({ reflect: true }) modal = false;
 
+  /** When `true` and `modal` is `false`, prevents focus trapping. */
+  @property({ reflect: true }) focusTrapDisabled = false;
+
   /** When `true`, displays and positions the component. */
   @property({ reflect: true })
   get open(): boolean {
@@ -275,6 +278,11 @@ export class Dialog extends LitElement implements OpenCloseComponent, LoadableCo
     this.focusTrap.updateContainerElements();
   }
 
+  /** When defined, provides a condition to disable focus trapping. When `true`, prevents focus trapping. */
+  focusTrapDisabledOverride(): boolean {
+    return !this.modal && this.focusTrapDisabled;
+  }
+
   // #endregion
 
   // #region Events
@@ -352,6 +360,7 @@ export class Dialog extends LitElement implements OpenCloseComponent, LoadableCo
   // #endregion
 
   // #region Private Methods
+
   private updateAssistiveText(): void {
     const { messages } = this;
     this.assistiveText =

packages/calcite-components/src/controllers/useFocusTrap.ts

@@ -43,14 +43,26 @@ interface UseFocusTrapOptions<T extends LitElement = LitElement> {
   focusTrapOptions?: FocusTrapOptions;
 }
 
+interface FocusTrapComponent extends LitElement {
+  /**
+   * When `true` prevents focus trapping.
+   */
+  focusTrapDisabled?: boolean;
+
+  /**
+   * When defined, provides a condition to disable focus trapping. When `true`, prevents focus trapping.
+   */
+  focusTrapDisabledOverride?: () => boolean;
+}
+
 /**
  * A controller for managing focus traps.
  *
  * Note: traps will be deactivated automatically when the component is disconnected.
  *
  * @param options
  */
-export const useFocusTrap = <T extends LitElement>(
+export const useFocusTrap = <T extends FocusTrapComponent>(
   options: UseFocusTrapOptions<T>,
 ): ReturnType<typeof makeGenericController<UseFocusTrap, T>> => {
   return makeGenericController<UseFocusTrap, T>((component, controller) => {
@@ -77,7 +89,13 @@ export const useFocusTrap = <T extends LitElement>(
           focusTrap = createFocusTrap(targetEl, createFocusTrapOptions(targetEl, focusTrapOptions));
         }
 
-        focusTrap.activate(options);
+        if (
+          typeof component.focusTrapDisabledOverride === "function"
+            ? !component.focusTrapDisabledOverride()
+            : !component.focusTrapDisabled
+        ) {
+          focusTrap.activate(options);
+        }
       },
       deactivate: (options?: Parameters<FocusTrap["deactivate"]>[0]) => focusTrap?.deactivate(options),
       overrideFocusTrapEl: (el: HTMLElement) => {

packages/calcite-components/src/utils/focusTrapComponent.spec.ts

@@ -112,4 +112,33 @@ describe("focusTrapComponent", () => {
       expect(customFocusTrapStack).toHaveLength(1);
     });
   });
+  describe("focusTrapDisabledOverride", () => {
+    const fakeComponent = {} as FocusTrapComponent;
+    let activateSpy: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      fakeComponent.el = document.createElement("div");
+
+      connectFocusTrap(fakeComponent);
+
+      activateSpy = vi.fn();
+      fakeComponent.focusTrap.activate = activateSpy;
+    });
+
+    it("should activate focus trap when focusTrapDisabledOverride returns false", () => {
+      fakeComponent.focusTrapDisabledOverride = () => false;
+
+      activateFocusTrap(fakeComponent);
+
+      expect(activateSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not activate focus trap when focusTrapDisabledOverride returns true", () => {
+      fakeComponent.focusTrapDisabledOverride = () => true;
+
+      activateFocusTrap(fakeComponent);
+
+      expect(activateSpy).toHaveBeenCalledTimes(0);
+    });
+  });
 });

packages/calcite-components/src/utils/focusTrapComponent.ts

@@ -10,6 +10,9 @@ export interface FocusTrapComponent {
   /** When `true`, prevents focus trapping. */
   focusTrapDisabled?: boolean;
 
+  /** When defined, provides a condition to disable focus trapping. When `true`, prevents focus trapping. */
+  focusTrapDisabledOverride?: () => boolean;
+
   /** The focus trap instance. */
   focusTrap: FocusTrap;
 
@@ -83,7 +86,7 @@ export function activateFocusTrap(
   component: FocusTrapComponent,
   options?: Parameters<_FocusTrap["activate"]>[0],
 ): void {
-  if (!component.focusTrapDisabled) {
+  if (component.focusTrapDisabledOverride ? !component.focusTrapDisabledOverride() : !component.focusTrapDisabled) {
     component.focusTrap?.activate(options);
   }
 }