fix(modal): resolve focus trap issue (#20157)

makafsal · riddhybansal · ariellalgilmore · web-flow · commit bb9cf284c524 · 2025-10-24T14:48:57.000Z
* fix(modal): resolve focus trap issue

* fix(modal): implement a prop to disable focus trap

* refactor(modal): remove disableFocusTrap property

---------

Co-authored-by: Riddhi Bansal &lt;41935566+riddhybansal@users.noreply.github.com&gt;
Co-authored-by: Ariella Gilmore &lt;ariellalgilmore@gmail.com&gt;
diff --git a/packages/web-components/src/components/modal/modal-body.ts b/packages/web-components/src/components/modal/modal-body.ts
@@ -17,8 +17,31 @@ import { carbonElement as customElement } from '../../globals/decorators/carbon-
  */
 @customElement(`${prefix}-modal-body`)
 class CDSModalBody extends LitElement {
+  private userDefinedTabindex: string | null = null;
+
+  connectedCallback() {
+    super.connectedCallback?.();
+    // Store the tabindex if user set it initially
+    if (this.hasAttribute('tabindex')) {
+      this.userDefinedTabindex = this.getAttribute('tabindex');
+    }
+  }
+
+  checkScroll() {
+    const hasScroll = this.scrollHeight > this.clientHeight;
+
+    // Respect user-defined tabindex
+    if (this.userDefinedTabindex !== null) return;
+
+    if (hasScroll) {
+      this.setAttribute('tabindex', '0');
+    } else {
+      this.removeAttribute('tabindex');
+    }
+  }
+
   render() {
-    return html` <slot></slot> `;
+    return html` <slot @slotchange=${this.checkScroll}></slot> `;
   }
 
   static styles = styles;
diff --git a/packages/web-components/src/components/modal/modal.stories.ts b/packages/web-components/src/components/modal/modal.stories.ts
@@ -337,8 +337,8 @@ export const WithAILabel = {
   render: () => html`
 <cds-modal open has-scrolling-content>
       <cds-modal-header>
-        <cds-ai-label alignment="bottom-left"> ${content}${actions}</cds-ai-label>
         <cds-modal-close-button></cds-modal-close-button>
+        <cds-ai-label alignment="bottom-left"> ${content}${actions}</cds-ai-label>
         <cds-modal-label>Account resources</cds-modal-label>
         <cds-modal-heading>Add a custom domain</cds-modal-heading>
       </cds-modal-header>
diff --git a/packages/web-components/src/components/modal/modal.ts b/packages/web-components/src/components/modal/modal.ts
@@ -7,7 +7,7 @@
 
 import { classMap } from 'lit/directives/class-map.js';
 import { LitElement, html } from 'lit';
-import { property, query } from 'lit/decorators.js';
+import { property } from 'lit/decorators.js';
 import { prefix } from '../../globals/settings';
 import HostListener from '../../globals/decorators/host-listener';
 import HostListenerMixin from '../../globals/mixins/host-listener';
@@ -18,42 +18,6 @@ import { carbonElement as customElement } from '../../globals/decorators/carbon-
 
 export { MODAL_SIZE };
 
-const PRECEDING =
-  Node.DOCUMENT_POSITION_PRECEDING | Node.DOCUMENT_POSITION_CONTAINS;
-
-const FOLLOWING =
-  Node.DOCUMENT_POSITION_FOLLOWING | Node.DOCUMENT_POSITION_CONTAINED_BY;
-
-/**
- * Tries to focus on the given elements and bails out if one of them is successful.
- *
- * @param elems The elements.
- * @param reverse `true` to go through the list in reverse order.
- * @returns `true` if one of the attempts is successful, `false` otherwise.
- */
-function tryFocusElems(elems: NodeListOf<HTMLElement>, reverse = false) {
-  if (!reverse) {
-    for (let i = 0; i < elems.length; ++i) {
-      const elem = elems[i];
-      elem.focus();
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- https://github.com/carbon-design-system/carbon/issues/20452
-      if (elem.ownerDocument!.activeElement === elem) {
-        return true;
-      }
-    }
-  } else {
-    for (let i = elems.length - 1; i >= 0; --i) {
-      const elem = elems[i];
-      elem.focus();
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- https://github.com/carbon-design-system/carbon/issues/20452
-      if (elem.ownerDocument!.activeElement === elem) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
 /**
  * Modal.
  *
@@ -71,18 +35,6 @@ class CDSModal extends HostListenerMixin(LitElement) {
    */
   private _launcher: Element | null = null;
 
-  /**
-   * Node to track focus going outside of modal content.
-   */
-  @query('#start-sentinel')
-  private _startSentinelNode!: HTMLAnchorElement;
-
-  /**
-   * Node to track focus going outside of modal content.
-   */
-  @query('#end-sentinel')
-  private _endSentinelNode!: HTMLAnchorElement;
-
   /**
    * Handles `click` event on this element.
    *
@@ -102,92 +54,28 @@ class CDSModal extends HostListenerMixin(LitElement) {
   };
 
   /**
-   * Handles `blur` event on this element.
+   * Handle the keydown event.
+   * Trap the focus inside the side-panel by tracking keydown.key == `Tab`
    *
-   * @param event The event.
-   * @param event.target The event target.
-   * @param event.relatedTarget The event relatedTarget.
+   * @param {KeyboardEvent} event The keyboard event object.
    */
-  @HostListener('shadowRoot:focusout')
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- https://github.com/carbon-design-system/carbon/issues/20452
-  // @ts-ignore: The decorator refers to this method but TS thinks this method is not referred to
-  private _handleBlur = async ({ target, relatedTarget }: FocusEvent) => {
-    const {
-      open,
-      _startSentinelNode: startSentinelNode,
-      _endSentinelNode: endSentinelNode,
-    } = this;
-    const oldContains = target !== this && this.contains(target as Node);
-    const currentContains =
-      relatedTarget !== this &&
-      (this.contains(relatedTarget as Node) ||
-        (this.shadowRoot?.contains(relatedTarget as Node) &&
-          relatedTarget !== (endSentinelNode as Node)));
-
-    // Performs focus wrapping if _all_ of the following is met:
-    // * This modal is open
-    // * The viewport still has focus
-    // * Modal body used to have focus but no longer has focus
-    const { selectorTabbable: selectorTabbableForModal } = this
-      .constructor as typeof CDSModal;
-    if (open && relatedTarget && oldContains && !currentContains) {
-      const comparisonResult = (target as Node).compareDocumentPosition(
-        relatedTarget as Node
-      );
+  @HostListener('keydown')
+  protected _handleHostKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Tab') {
+      const { first: _firstElement, last: _lastElement } = this.getFocusable();
 
-      if (relatedTarget === startSentinelNode || comparisonResult & PRECEDING) {
-        await (this.constructor as typeof CDSModal)._delay();
-        if (
-          !tryFocusElems(
-            this.querySelectorAll(selectorTabbableForModal),
-            true
-          ) &&
-          relatedTarget !== this
-        ) {
-          this.focus();
-        }
-      } else if (
-        relatedTarget === endSentinelNode ||
-        comparisonResult & FOLLOWING
+      if (
+        event.shiftKey &&
+        (this.shadowRoot?.activeElement === _firstElement ||
+          document.activeElement === _firstElement)
       ) {
-        await (this.constructor as typeof CDSModal)._delay();
-        if (!tryFocusElems(this.querySelectorAll(selectorTabbableForModal))) {
-          this.focus();
-        }
-      }
-    }
+        event.preventDefault();
 
-    // Adjust scroll if needed so that element with focus is not obscured by gradient
-    const modal = document.querySelector(`${prefix}-modal`);
-    const modalContent = document.querySelector(`${prefix}-modal-body`);
-    if (
-      !modal ||
-      !modal.hasAttribute('has-scrolling-content') ||
-      !modalContent ||
-      !relatedTarget ||
-      !modalContent.contains(relatedTarget as Node)
-    ) {
-      return;
-    }
+        _lastElement?.focus();
+      } else if (!event.shiftKey && document.activeElement === _lastElement) {
+        event.preventDefault();
 
-    const lastContent = modalContent.children[modalContent.children.length - 1];
-    const gradientSpacing =
-      modalContent.scrollHeight -
-      (lastContent as HTMLElement).offsetTop -
-      (lastContent as HTMLElement).clientHeight;
-
-    for (const elem of modalContent.children) {
-      if (elem.contains(relatedTarget as Node)) {
-        const spaceBelow =
-          modalContent.clientHeight -
-          (elem as HTMLElement).offsetTop +
-          modalContent.scrollTop -
-          (elem as HTMLElement).clientHeight;
-        if (spaceBelow < gradientSpacing) {
-          modalContent.scrollTop =
-            modalContent.scrollTop + (gradientSpacing - spaceBelow);
-        }
-        break;
+        _firstElement?.focus();
       }
     }
   };
@@ -201,6 +89,38 @@ class CDSModal extends HostListenerMixin(LitElement) {
     }
   };
 
+  /**
+   * Get focusable elements.
+   *
+   * Querying all tabbable items.
+   *
+   * @returns {{first: HTMLElement, last: HTMLElement, all: HTMLElement[]}} Returns an object with various elements.
+   */
+  private getFocusable(): {
+    first: HTMLElement | undefined;
+    last: HTMLElement | undefined;
+    all: HTMLElement[];
+  } {
+    const elements: HTMLElement[] = [];
+
+    // Add tabbable elements inside light DOM
+    const tabbableItems = this.querySelectorAll<HTMLElement>(selectorTabbable);
+    if (tabbableItems?.length) {
+      elements.push(...tabbableItems);
+    }
+
+    // Flatten NodeList arrays and filter for focusable items
+    const all = elements?.filter(
+      (el): el is HTMLElement => typeof el?.focus === 'function'
+    );
+
+    return {
+      first: all[0],
+      last: all[all.length - 1],
+      all,
+    };
+  }
+
   /**
    * Handles `click` event on the modal container.
    *
@@ -345,11 +265,6 @@ class CDSModal extends HostListenerMixin(LitElement) {
       ...containerClass,
     });
     return html`
-      <a
-        id="start-sentinel"
-        class="${prefix}--visually-hidden"
-        href="javascript:void 0"
-        role="navigation"></a>
       <div
         aria-label=${ariaLabel}
         part="dialog"
@@ -362,11 +277,6 @@ class CDSModal extends HostListenerMixin(LitElement) {
           ? html` <div class="cds--modal-content--overflow-indicator"></div> `
           : ``}
       </div>
-      <a
-        id="end-sentinel"
-        class="${prefix}--visually-hidden"
-        href="javascript:void 0"
-        role="navigation"></a>
     `;
   }
 
@@ -383,15 +293,10 @@ class CDSModal extends HostListenerMixin(LitElement) {
           // For cases where a `carbon-web-components` component (e.g. `<cds-button>`) being `primaryFocusNode`,
           // where its first update/render cycle that makes it focusable happens after `<cds-modal>`'s first update/render cycle
           (primaryFocusNode as HTMLElement).focus();
-        } else if (
-          !tryFocusElems(
-            this.querySelectorAll(
-              (this.constructor as typeof CDSModal).selectorTabbable
-            ),
-            true
-          )
-        ) {
-          this.focus();
+        } else {
+          const { first } = this.getFocusable();
+
+          first?.focus();
         }
       } else if (
         this._launcher &&
diff --git a/packages/web-components/src/globals/settings.ts b/packages/web-components/src/globals/settings.ts
@@ -18,6 +18,7 @@ const selectorTabbable = `
   iframe, object, embed, *[tabindex]:not([tabindex='-1']), *[contenteditable=true],
   ${prefix}-accordion-item,
   ${prefix}-actionable-notification-button,
+  ${prefix}-ai-label,
   ${prefix}-button,
   ${prefix}-breadcrumb-link,
   ${prefix}-checkbox,
@@ -36,6 +37,7 @@ const selectorTabbable = `
   ${prefix}-number-input,
   ${prefix}-modal,
   ${prefix}-modal-close-button,
+  ${prefix}-modal-footer-button,
   ${prefix}-multi-select,
   ${prefix}-inline-notification,
   ${prefix}-toast-notification,
