focus-trap 8.1.0 → 8.2.1

package/index.js

@@ -128,6 +128,7 @@ const createFocusTrap = function (elements, userOptions) {
     returnFocusOnDeactivate: true,
     escapeDeactivates: true,
     delayInitialFocus: true,
+    delayReturnFocus: true,
     isolateSubtrees: false,
     isKeyForward,
     isKeyBackward,
@@ -300,6 +301,31 @@ const createFocusTrap = function (elements, userOptions) {
     return node;
   };
 
+  /**
+   * Gets the current activeElement. If it's a web-component and has open shadow-root
+   * it will recursively search inside shadow roots for the "true" activeElement.
+   *
+   * @param {Document | ShadowRoot} el
+   *
+   * @returns {HTMLElement|null} The element that currently has the focus. `null` if a focused element isn't found.
+   **/
+  const getActiveElement = function (el) {
+    const activeElement = el.activeElement;
+
+    if (!activeElement) {
+      return null;
+    }
+
+    if (
+      activeElement.shadowRoot &&
+      activeElement.shadowRoot.activeElement !== null
+    ) {
+      return getActiveElement(activeElement.shadowRoot);
+    }
+
+    return activeElement;
+  };
+
   const getInitialFocusNode = function () {
     let node = getNodeForOption('initialFocus', { hasFallback: true });
 
@@ -312,9 +338,11 @@ const createFocusTrap = function (elements, userOptions) {
       node === undefined ||
       (node && !isFocusable(node, config.tabbableOptions))
     ) {
+      const activeElement = getActiveElement(doc);
+
       // option not specified nor focusable: use fallback options
-      if (findContainerIndex(doc.activeElement) >= 0) {
-        node = doc.activeElement;
+      if (findContainerIndex(activeElement) >= 0) {
+        node = activeElement;
       } else {
         const firstTabbableGroup = state.tabbableGroups[0];
         const firstTabbableNode =
@@ -456,31 +484,6 @@ const createFocusTrap = function (elements, userOptions) {
     }
   };
 
-  /**
-   * Gets the current activeElement. If it's a web-component and has open shadow-root
-   * it will recursively search inside shadow roots for the "true" activeElement.
-   *
-   * @param {Document | ShadowRoot} el
-   *
-   * @returns {HTMLElement} The element that currently has the focus
-   **/
-  const getActiveElement = function (el) {
-    const activeElement = el.activeElement;
-
-    if (!activeElement) {
-      return;
-    }
-
-    if (
-      activeElement.shadowRoot &&
-      activeElement.shadowRoot.activeElement !== null
-    ) {
-      return getActiveElement(activeElement.shadowRoot);
-    }
-
-    return activeElement;
-  };
-
   const tryFocus = function (node) {
     if (node === false) {
       return;
@@ -850,12 +853,13 @@ const createFocusTrap = function (elements, userOptions) {
   /**
    * Adds listeners to the document necessary for trapping focus and attempts to set focus
    *  to the configured initial focus node. Does nothing if the trap isn't active.
-   * @returns {Promise<void>} Resolved (always) once the initial focus node has been focused.
-   *  Also resolved if the trap isn't active.
+   * @returns {Promise<void> | undefined} A promise resolved once the initial focus node has
+   *  been focused when `delayInitialFocus=true`; `undefined` when focus is set synchronously
+   *  or the trap isn't active.
    */
   const addListeners = function () {
     if (!state.active) {
-      return Promise.resolve();
+      return;
     }
 
     // There can be only one listening focus trap at a time
@@ -863,7 +867,7 @@ const createFocusTrap = function (elements, userOptions) {
 
     // Delay ensures that the focused element doesn't capture the event
     // that caused the focus trap activation.
-    /** @type {Promise<void>} */
+    /** @type {Promise<void> | undefined} */
     let promise;
     if (config.delayInitialFocus) {
       // NOTE: Promise constructor callback is called synchronously, which is what we want
@@ -875,7 +879,6 @@ const createFocusTrap = function (elements, userOptions) {
         });
       });
     } else {
-      promise = Promise.resolve();
       tryFocus(getInitialFocusNode());
     }
 
@@ -979,17 +982,33 @@ const createFocusTrap = function (elements, userOptions) {
   //
 
   const checkDomRemoval = function (mutations) {
+    const focusedNode = state.mostRecentlyFocusedNode;
+    if (!focusedNode) {
+      return;
+    }
     const isFocusedNodeRemoved = mutations.some(function (mutation) {
       const removedNodes = Array.from(mutation.removedNodes);
       return removedNodes.some(function (node) {
-        return node === state.mostRecentlyFocusedNode;
+        return (
+          node === focusedNode ||
+          (typeof node.contains === 'function' && node.contains(focusedNode))
+        );
       });
     });
 
-    // If the currently focused is removed then browsers will move focus to the
+    // If the currently focused node is removed then browsers will move focus to the
     // <body> element. If this happens, try to move focus back into the trap.
-    if (isFocusedNodeRemoved) {
-      tryFocus(getInitialFocusNode());
+    if (
+      isFocusedNodeRemoved &&
+      state.containers.some(function (container) {
+        return container?.isConnected;
+      })
+    ) {
+      // Refresh tabbable state before resolving initial focus because
+      // getInitialFocusNode() may fall back to the first tabbable node in the trap.
+      updateTabbableNodes();
+      const initialFocusNode = getInitialFocusNode();
+      tryFocus(initialFocusNode);
     }
   };
 
@@ -1061,21 +1080,28 @@ const createFocusTrap = function (elements, userOptions) {
 
         onActivate?.({ trap });
 
-        const finishActivation = async () => {
+        const finishActivation = () => {
           if (checkCanFocusTrap) {
             updateTabbableNodes();
           }
 
-          // NOTE: wait for initial focus node to get focused before we potentially isolate
-          //  the subtrees with aria-hidden while focus is still in some other subtree and
-          //  not yet in the trap, resulting in some browsers (e.g. Chrome) logging to the
-          //  console that they, "Blocked aria-hidden on an element because its descendant
-          //  retained focus..."
-          await addListeners();
+          const afterListeners = () => {
+            trap._setSubtreeIsolation(true);
+            updateObservedNodes();
+            onPostActivate?.({ trap });
+          };
 
-          trap._setSubtreeIsolation(true);
-          updateObservedNodes();
-          onPostActivate?.({ trap });
+          // NOTE: wait for initial focus node to get focused (whether activation is fully,
+          //  partially, or not asynchronous) before we potentially isolate the subtrees
+          //  with aria-hidden while focus is still in some other subtree and not yet in
+          //  the trap, resulting in some browsers (e.g. Chrome) logging to the console that
+          //  they, "Blocked aria-hidden on an element because its descendant retained focus..."
+          const listenersPromise = addListeners();
+          if (listenersPromise) {
+            listenersPromise.then(afterListeners);
+          } else {
+            afterListeners();
+          }
         };
 
         if (checkCanFocusTrap) {
@@ -1137,6 +1163,7 @@ const createFocusTrap = function (elements, userOptions) {
       const onDeactivate = getOption(options, 'onDeactivate');
       const onPostDeactivate = getOption(options, 'onPostDeactivate');
       const checkCanReturnFocus = getOption(options, 'checkCanReturnFocus');
+      const delayReturnFocus = getOption(options, 'delayReturnFocus');
       const returnFocus = getOption(
         options,
         'returnFocus',
@@ -1144,14 +1171,19 @@ const createFocusTrap = function (elements, userOptions) {
       );
 
       onDeactivate?.({ trap });
+      const completeDeactivation = () => {
+        if (returnFocus) {
+          tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
+        }
+        onPostDeactivate?.({ trap });
+      };
 
       const finishDeactivation = () => {
-        delay(() => {
-          if (returnFocus) {
-            tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
-          }
-          onPostDeactivate?.({ trap });
-        });
+        if (delayReturnFocus && returnFocus) {
+          delay(completeDeactivation);
+        } else {
+          completeDeactivation();
+        }
       };
 
       if (returnFocus && checkCanReturnFocus) {
@@ -1244,19 +1276,26 @@ const createFocusTrap = function (elements, userOptions) {
 
           onUnpause?.({ trap });
 
-          const finishUnpause = async () => {
+          const finishUnpause = () => {
             updateTabbableNodes();
 
-            // NOTE: wait for initial focus node to get focused before we potentially isolate
-            //  the subtrees with aria-hidden while focus is still in some other subtree and
-            //  not yet in the trap, resulting in some browsers (e.g. Chrome) logging to the
-            //  console that they, "Blocked aria-hidden on an element because its descendant
-            //  retained focus..."
-            await addListeners();
-
-            trap._setSubtreeIsolation(true);
-            updateObservedNodes();
-            onPostUnpause?.({ trap });
+            const afterListeners = () => {
+              trap._setSubtreeIsolation(true);
+              updateObservedNodes();
+              onPostUnpause?.({ trap });
+            };
+
+            // NOTE: wait for initial focus node to get focused (whether activation is fully,
+            //  partially, or not asynchronous) before we potentially isolate the subtrees
+            //  with aria-hidden while focus is still in some other subtree and not yet in
+            //  the trap, resulting in some browsers (e.g. Chrome) logging to the console that
+            //  they, "Blocked aria-hidden on an element because its descendant retained focus..."
+            const listenersPromise = addListeners();
+            if (listenersPromise) {
+              listenersPromise.then(afterListeners);
+            } else {
+              afterListeners();
+            }
           };
 
           finishUnpause();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focus-trap",
-  "version": "8.1.0",
+  "version": "8.2.1",
   "description": "Trap focus within a DOM node.",
   "main": "dist/focus-trap.js",
   "module": "dist/focus-trap.esm.js",
@@ -72,7 +72,7 @@
     "@babel/core": "^7.29.0",
     "@babel/eslint-parser": "^7.28.6",
     "@babel/eslint-plugin": "^7.27.1",
-    "@babel/preset-env": "^7.29.2",
+    "@babel/preset-env": "^7.29.5",
     "@changesets/cli": "^2.31.0",
     "@eslint/js": "^9.39.2",
     "@rollup/plugin-babel": "^7.0.0",
@@ -80,40 +80,40 @@
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-terser": "^1.0.0",
-    "@testing-library/cypress": "^10.1.0",
+    "@testing-library/cypress": "^10.1.3",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/user-event": "^14.6.1",
     "@types/jest": "^30.0.0",
     "@types/jquery": "^4.0.0",
-    "@types/node": "^25.6.0",
-    "@typescript-eslint/eslint-plugin": "^8.59.0",
-    "@typescript-eslint/parser": "^8.58.2",
+    "@types/node": "^25.7.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.3",
     "all-contributors-cli": "^6.26.1",
-    "babel-jest": "^30.3.0",
+    "babel-jest": "^30.4.1",
     "babel-loader": "^10.1.1",
     "cross-env": "^10.1.0",
-    "cypress": "^15.14.1",
+    "cypress": "^15.15.0",
     "cypress-plugin-tab": "^1.0.5",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-node": "^0.3.10",
     "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-cypress": "^6.3.1",
+    "eslint-plugin-cypress": "^6.4.1",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-jest": "^29.15.2",
     "eslint-plugin-jest-dom": "^5.5.0",
     "eslint-plugin-testing-library": "^7.16.2",
-    "globals": "^17.5.0",
-    "jest": "^30.3.0",
-    "jest-environment-jsdom": "^30.3.0",
+    "globals": "^17.6.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
     "jest-watch-typeahead": "^3.0.1",
     "onchange": "^7.1.0",
     "prettier": "^3.8.3",
-    "rollup": "^4.60.2",
+    "rollup": "^4.60.3",
     "rollup-plugin-livereload": "^2.0.5",
     "rollup-plugin-serve": "^3.0.0",
-    "start-server-and-test": "^3.0.2",
+    "start-server-and-test": "^3.0.4",
     "typescript": "^6.0.3"
   }
 }