fix(modal, popover): Add disableFocusTrap property to toggle focus …

…trapping. (#5965)

fix(modal, popover): Add `disableFocusTrap` property to toggle focus
trapping.

src/components/modal/modal.tsx

@@ -28,7 +28,8 @@ import {
   FocusTrap,
   connectFocusTrap,
   activateFocusTrap,
-  deactivateFocusTrap
+  deactivateFocusTrap,
+  focusFirstTabbable
 } from "../../utils/focusTrapComponent";
 import {
   setUpLoadableComponent,
@@ -83,6 +84,20 @@ export class Modal
   /** When `true`, disables the component's close button. */
   @Prop({ reflect: true }) disableCloseButton = false;
 
+  /**
+   * When `true`, prevents focus trapping.
+   */
+  @Prop({ reflect: true }) disableFocusTrap = false;
+
+  @Watch("disableFocusTrap")
+  handleDisableFocusTrap(disableFocusTrap: boolean): void {
+    if (!this.open) {
+      return;
+    }
+
+    disableFocusTrap ? deactivateFocusTrap(this) : activateFocusTrap(this);
+  }
+
   /** When `true`, disables the closing of the component when clicked outside. */
   @Prop({ reflect: true }) disableOutsideClose = false;
 
@@ -363,7 +378,7 @@ export class Modal
       return focusElement(closeButtonEl);
     }
 
-    activateFocusTrap(this);
+    focusFirstTabbable(this);
   }
 
   /**
@@ -404,6 +419,7 @@ export class Modal
   onOpen(): void {
     this.transitionEl.classList.remove(CSS.openingIdle, CSS.openingActive);
     this.calciteModalOpen.emit();
+    activateFocusTrap(this);
   }
 
   onBeforeClose(): void {

src/components/popover/popover.tsx

@@ -32,7 +32,8 @@ import {
   FocusTrap,
   connectFocusTrap,
   activateFocusTrap,
-  deactivateFocusTrap
+  deactivateFocusTrap,
+  focusFirstTabbable
 } from "../../utils/focusTrapComponent";
 
 import { guid } from "../../utils/guid";
@@ -91,6 +92,15 @@ export class Popover
    */
   @Prop({ reflect: true }) disableFocusTrap = false;
 
+  @Watch("disableFocusTrap")
+  handleDisableFocusTrap(disableFocusTrap: boolean): void {
+    if (!this.open) {
+      return;
+    }
+
+    disableFocusTrap ? deactivateFocusTrap(this) : activateFocusTrap(this);
+  }
+
   /**
    * When `true`, removes the caret pointer.
    */
@@ -350,7 +360,7 @@ export class Popover
       return;
     }
 
-    activateFocusTrap(this);
+    focusFirstTabbable(this);
   }
 
   /**
@@ -467,9 +477,7 @@ export class Popover
 
   onOpen(): void {
     this.calcitePopoverOpen.emit();
-    if (!this.disableFocusTrap) {
-      activateFocusTrap(this);
-    }
+    activateFocusTrap(this);
   }
 
   onBeforeClose(): void {

src/utils/focusTrapComponent.ts

@@ -1,12 +1,27 @@
-import { FocusTrap as _FocusTrap, Options as FocusTrapOptions, createFocusTrap } from "focus-trap";
+import {
+  FocusTrap as _FocusTrap,
+  Options as FocusTrapOptions,
+  createFocusTrap,
+  FocusTrapTabbableOptions
+} from "focus-trap";
 import { FocusableElement, focusElement } from "./dom";
+import { tabbable } from "tabbable";
+
+const tabbableOptions: FocusTrapTabbableOptions = {
+  getShadowRoot: true
+};
 
 const trapStack: _FocusTrap[] = [];
 
 /**
  * Defines interface for components with a focus trap.
  */
 export interface FocusTrapComponent {
+  /**
+   * When `true`, prevents focus trapping.
+   */
+  disableFocusTrap: boolean;
+
   /**
    * The focus trap instance.
    */
@@ -21,9 +36,9 @@ export interface FocusTrapComponent {
 export type FocusTrap = _FocusTrap;
 
 /**
- * Helper to set up focus trap component.
+ * Helper to set up the FocusTrap component.
  *
- * @param component
+ * @param {FocusTrapComponent} component The FocusTrap component.
  */
 export function connectFocusTrap(component: FocusTrapComponent): void {
   const { focusTrapEl } = component;
@@ -46,29 +61,38 @@ export function connectFocusTrap(component: FocusTrapComponent): void {
       focusElement(el as FocusableElement);
       return false;
     },
-    tabbableOptions: {
-      getShadowRoot: true
-    },
+    tabbableOptions,
     trapStack
   };
 
   component.focusTrap = createFocusTrap(focusTrapEl, focusTrapOptions);
 }
 
 /**
- * Helper to activate focus trap component.
+ * Helper to activate the FocusTrap component.
  *
- * @param component
+ * @param {FocusTrapComponent} component The FocusTrap component.
  */
 export function activateFocusTrap(component: FocusTrapComponent): void {
-  component.focusTrap?.activate();
+  if (!component.disableFocusTrap) {
+    component.focusTrap?.activate();
+  }
 }
 
 /**
- * Helper to tear deactivate focus trap component.
+ * Helper to deactivate the FocusTrap component.
  *
- * @param component
+ * @param {FocusTrapComponent} component The FocusTrap component.
  */
 export function deactivateFocusTrap(component: FocusTrapComponent): void {
   component.focusTrap?.deactivate();
 }
+
+/**
+ * Helper to focus the first tabbable element within the FocusTrap component.
+ *
+ * @param {FocusTrapComponent} component The FocusTrap component.
+ */
+export function focusFirstTabbable(component: FocusTrapComponent): void {
+  tabbable(component.focusTrapEl, tabbableOptions)[0]?.focus();
+}