focus-trap 6.5.0 → 6.7.0

package/index.js

@@ -1,7 +1,5 @@
 import { tabbable, isFocusable } from 'tabbable';
 
-let activeFocusDelay;
-
 const activeFocusTraps = (function () {
   const trapQueue = [];
   return {
@@ -84,8 +82,21 @@ const valueOrHandler = function (value, ...params) {
   return typeof value === 'function' ? value(...params) : value;
 };
 
+const getActualTarget = function (event) {
+  // NOTE: If the trap is _inside_ a shadow DOM, event.target will always be the
+  //  shadow host. However, event.target.composedPath() will be an array of
+  //  nodes "clicked" from inner-most (the actual element inside the shadow) to
+  //  outer-most (the host HTML document). If we have access to composedPath(),
+  //  then use its first element; otherwise, fall back to event.target (and
+  //  this only works for an _open_ shadow DOM; otherwise,
+  //  composedPath()[0] === event.target always).
+  return event.target.shadowRoot && typeof event.composedPath === 'function'
+    ? event.composedPath()[0]
+    : event.target;
+};
+
 const createFocusTrap = function (elements, userOptions) {
-  const doc = document;
+  const doc = userOptions.document || document;
 
   const config = {
     returnFocusOnDeactivate: true,
@@ -111,6 +122,10 @@ const createFocusTrap = function (elements, userOptions) {
     mostRecentlyFocusedNode: null,
     active: false,
     paused: false,
+
+    // timer ID for when delayInitialFocus is true and initial focus in this trap
+    //  has been delayed during activation
+    delayInitialFocusTimer: undefined,
   };
 
   let trap; // eslint-disable-line prefer-const -- some private functions reference it, and its methods reference private functions, so we must declare here and define later
@@ -123,28 +138,51 @@ const createFocusTrap = function (elements, userOptions) {
   };
 
   const containersContain = function (element) {
-    return state.containers.some((container) => container.contains(element));
+    return !!(
+      element &&
+      state.containers.some((container) => container.contains(element))
+    );
   };
 
-  const getNodeForOption = function (optionName) {
-    const optionValue = config[optionName];
-    if (!optionValue) {
-      return null;
-    }
+  /**
+   * Gets the node for the given option, which is expected to be an option that
+   *  can be either a DOM node, a string that is a selector to get a node, `false`
+   *  (if a node is explicitly NOT given), or a function that returns any of these
+   *  values.
+   * @param {string} optionName
+   * @returns {undefined | false | HTMLElement | SVGElement} Returns
+   *  `undefined` if the option is not specified; `false` if the option
+   *  resolved to `false` (node explicitly not given); otherwise, the resolved
+   *  DOM node.
+   * @throws {Error} If the option is set, not `false`, and is not, or does not
+   *  resolve to a node.
+   */
+  const getNodeForOption = function (optionName, ...params) {
+    let optionValue = config[optionName];
 
-    let node = optionValue;
+    if (typeof optionValue === 'function') {
+      optionValue = optionValue(...params);
+    }
 
-    if (typeof optionValue === 'string') {
-      node = doc.querySelector(optionValue);
-      if (!node) {
-        throw new Error(`\`${optionName}\` refers to no known node`);
+    if (!optionValue) {
+      if (optionValue === undefined || optionValue === false) {
+        return optionValue;
       }
+      // else, empty string (invalid), null (invalid), 0 (invalid)
+
+      throw new Error(
+        `\`${optionName}\` was specified but was not a node, or did not return a node`
+      );
     }
 
-    if (typeof optionValue === 'function') {
-      node = optionValue();
+    let node = optionValue; // could be HTMLElement, SVGElement, or non-empty string at this point
+
+    if (typeof optionValue === 'string') {
+      node = doc.querySelector(optionValue); // resolve to node, or null if fails
       if (!node) {
-        throw new Error(`\`${optionName}\` did not return a node`);
+        throw new Error(
+          `\`${optionName}\` as selector refers to no known node`
+        );
       }
     }
 
@@ -152,17 +190,25 @@ const createFocusTrap = function (elements, userOptions) {
   };
 
   const getInitialFocusNode = function () {
-    let node;
+    let node = getNodeForOption('initialFocus');
 
-    if (getNodeForOption('initialFocus') !== null) {
-      node = getNodeForOption('initialFocus');
-    } else if (containersContain(doc.activeElement)) {
-      node = doc.activeElement;
-    } else {
-      const firstTabbableGroup = state.tabbableGroups[0];
-      const firstTabbableNode =
-        firstTabbableGroup && firstTabbableGroup.firstTabbableNode;
-      node = firstTabbableNode || getNodeForOption('fallbackFocus');
+    // false explicitly indicates we want no initialFocus at all
+    if (node === false) {
+      return false;
+    }
+
+    if (node === undefined) {
+      // option not specified: use fallback options
+      if (containersContain(doc.activeElement)) {
+        node = doc.activeElement;
+      } else {
+        const firstTabbableGroup = state.tabbableGroups[0];
+        const firstTabbableNode =
+          firstTabbableGroup && firstTabbableGroup.firstTabbableNode;
+
+        // NOTE: `fallbackFocus` option function cannot return `false` (not supported)
+        node = firstTabbableNode || getNodeForOption('fallbackFocus');
+      }
     }
 
     if (!node) {
@@ -194,7 +240,7 @@ const createFocusTrap = function (elements, userOptions) {
     // throw if no groups have tabbable nodes and we don't have a fallback focus node either
     if (
       state.tabbableGroups.length <= 0 &&
-      !getNodeForOption('fallbackFocus')
+      !getNodeForOption('fallbackFocus') // returning false not supported for this option
     ) {
       throw new Error(
         'Your focus-trap must have at least one container with at least one tabbable node in it at all times'
@@ -203,9 +249,14 @@ const createFocusTrap = function (elements, userOptions) {
   };
 
   const tryFocus = function (node) {
+    if (node === false) {
+      return;
+    }
+
     if (node === doc.activeElement) {
       return;
     }
+
     if (!node || !node.focus) {
       tryFocus(getInitialFocusNode());
       return;
@@ -220,15 +271,16 @@ const createFocusTrap = function (elements, userOptions) {
   };
 
   const getReturnFocusNode = function (previousActiveElement) {
-    const node = getNodeForOption('setReturnFocus');
-
-    return node ? node : previousActiveElement;
+    const node = getNodeForOption('setReturnFocus', previousActiveElement);
+    return node ? node : node === false ? false : previousActiveElement;
   };
 
   // This needs to be done on mousedown and touchstart instead of click
   // so that it precedes the focus event.
   const checkPointerDown = function (e) {
-    if (containersContain(e.target)) {
+    const target = getActualTarget(e);
+
+    if (containersContain(target)) {
       // allow the click since it ocurred inside the trap
       return;
     }
@@ -247,7 +299,7 @@ const createFocusTrap = function (elements, userOptions) {
         //  that was clicked, whether it's focusable or not; by setting
         //  `returnFocus: true`, we'll attempt to re-focus the node originally-focused
         //  on activation (or the configured `setReturnFocus` node)
-        returnFocus: config.returnFocusOnDeactivate && !isFocusable(e.target),
+        returnFocus: config.returnFocusOnDeactivate && !isFocusable(target),
       });
       return;
     }
@@ -266,11 +318,13 @@ const createFocusTrap = function (elements, userOptions) {
 
   // In case focus escapes the trap for some strange reason, pull it back in.
   const checkFocusIn = function (e) {
-    const targetContained = containersContain(e.target);
+    const target = getActualTarget(e);
+    const targetContained = containersContain(target);
+
     // In Firefox when you Tab out of an iframe the Document is briefly focused.
-    if (targetContained || e.target instanceof Document) {
+    if (targetContained || target instanceof Document) {
       if (targetContained) {
-        state.mostRecentlyFocusedNode = e.target;
+        state.mostRecentlyFocusedNode = target;
       }
     } else {
       // escaped! pull it back in to where it just left
@@ -284,6 +338,7 @@ const createFocusTrap = function (elements, userOptions) {
   // moment it can end up scrolling the page and causing confusion so we
   // kind of need to capture the action at the keydown phase.
   const checkTab = function (e) {
+    const target = getActualTarget(e);
     updateTabbableNodes();
 
     let destinationNode = null;
@@ -293,7 +348,7 @@ const createFocusTrap = function (elements, userOptions) {
       // NOTE: the target may also be the container itself if it's tabbable
       //  with tabIndex='-1' and was given initial focus
       const containerIndex = findIndex(state.tabbableGroups, ({ container }) =>
-        container.contains(e.target)
+        container.contains(target)
       );
 
       if (containerIndex < 0) {
@@ -314,12 +369,12 @@ const createFocusTrap = function (elements, userOptions) {
         // is the target the first tabbable node in a group?
         let startOfGroupIndex = findIndex(
           state.tabbableGroups,
-          ({ firstTabbableNode }) => e.target === firstTabbableNode
+          ({ firstTabbableNode }) => target === firstTabbableNode
         );
 
         if (
           startOfGroupIndex < 0 &&
-          state.tabbableGroups[containerIndex].container === e.target
+          state.tabbableGroups[containerIndex].container === target
         ) {
           // an exception case where the target is the container itself, in which
           //  case, we should handle shift+tab as if focus were on the container's
@@ -345,12 +400,12 @@ const createFocusTrap = function (elements, userOptions) {
         // is the target the last tabbable node in a group?
         let lastOfGroupIndex = findIndex(
           state.tabbableGroups,
-          ({ lastTabbableNode }) => e.target === lastTabbableNode
+          ({ lastTabbableNode }) => target === lastTabbableNode
         );
 
         if (
           lastOfGroupIndex < 0 &&
-          state.tabbableGroups[containerIndex].container === e.target
+          state.tabbableGroups[containerIndex].container === target
         ) {
           // an exception case where the target is the container itself, in which
           //  case, we should handle tab as if focus were on the container's
@@ -372,6 +427,7 @@ const createFocusTrap = function (elements, userOptions) {
         }
       }
     } else {
+      // NOTE: the fallbackFocus option does not support returning false to opt-out
       destinationNode = getNodeForOption('fallbackFocus');
     }
 
@@ -383,7 +439,10 @@ const createFocusTrap = function (elements, userOptions) {
   };
 
   const checkKey = function (e) {
-    if (config.escapeDeactivates !== false && isEscapeEvent(e)) {
+    if (
+      isEscapeEvent(e) &&
+      valueOrHandler(config.escapeDeactivates, e) !== false
+    ) {
       e.preventDefault();
       trap.deactivate();
       return;
@@ -400,7 +459,9 @@ const createFocusTrap = function (elements, userOptions) {
       return;
     }
 
-    if (containersContain(e.target)) {
+    const target = getActualTarget(e);
+
+    if (containersContain(target)) {
       return;
     }
 
@@ -426,7 +487,7 @@ const createFocusTrap = function (elements, userOptions) {
 
     // Delay ensures that the focused element doesn't capture the event
     // that caused the focus trap activation.
-    activeFocusDelay = config.delayInitialFocus
+    state.delayInitialFocusTimer = config.delayInitialFocus
       ? delay(function () {
           tryFocus(getInitialFocusNode());
         })
@@ -520,7 +581,8 @@ const createFocusTrap = function (elements, userOptions) {
         return this;
       }
 
-      clearTimeout(activeFocusDelay);
+      clearTimeout(state.delayInitialFocusTimer); // noop if undefined
+      state.delayInitialFocusTimer = undefined;
 
       removeListeners();
       state.active = false;
@@ -546,14 +608,14 @@ const createFocusTrap = function (elements, userOptions) {
       );
 
       const finishDeactivation = () => {
-        if (returnFocus) {
-          delay(() => {
+        delay(() => {
+          if (returnFocus) {
             tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
-            if (onPostDeactivate) {
-              onPostDeactivate();
-            }
-          });
-        }
+          }
+          if (onPostDeactivate) {
+            onPostDeactivate();
+          }
+        });
       };
 
       if (returnFocus && checkCanReturnFocus) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focus-trap",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "description": "Trap focus within a DOM node.",
   "main": "dist/focus-trap.js",
   "module": "dist/focus-trap.esm.js",
@@ -17,22 +17,24 @@
     "dist"
   ],
   "scripts": {
-    "demo-bundle": "browserify demo/js/index.js -o demo/demo-bundle.js",
-    "format": "prettier --write \"{*,src/**/*,test/**/*,demo/js/**/*,.github/workflows/*,cypress/**/*}.+(js|yml)\"",
-    "format:check": "prettier --check \"{*,src/**/*,test/**/*,demo/js/**/*,.github/workflows/*,cypress/**/*}.+(js|yml)\"",
-    "format:watch": "onchange \"{*,src/**/*,test/**/*,demo/js/**/*,.github/workflows/*,cypress/**/*}.+(js|yml)\" -- prettier --write {{changed}}",
-    "lint": "eslint \"*.js\" \"demo/**/*.js\" \"cypress/**/*.js\"",
+    "demo-bundle": "yarn compile:demo",
+    "format": "prettier --write \"{*,src/**/*,test/**/*,docs/js/**/*,.github/workflows/*,cypress/**/*}.+(js|yml)\"",
+    "format:check": "prettier --check \"{*,src/**/*,test/**/*,docs/js/**/*,.github/workflows/*,cypress/**/*}.+(js|yml)\"",
+    "format:watch": "onchange \"{*,src/**/*,test/**/*,docs/js/**/*,.github/workflows/*,cypress/**/*}.+(js|yml)\" -- prettier --write {{changed}}",
+    "lint": "eslint \"*.js\" \"docs/js/**/*.js\" \"cypress/**/*.js\"",
     "clean": "rm -rf ./dist",
     "compile:esm": "cross-env BUILD_ENV=esm BABEL_ENV=esm rollup -c",
     "compile:cjs": "cross-env BUILD_ENV=cjs BABEL_ENV=es5 rollup -c",
     "compile:umd": "cross-env BUILD_ENV=umd BABEL_ENV=es5 rollup -c",
+    "compile:demo": "cross-env BUILD_ENV=demo BABEL_ENV=es5 rollup -c",
     "compile": "yarn compile:esm && yarn compile:cjs && yarn compile:umd",
     "build": "yarn clean && yarn compile",
-    "start": "yarn compile:cjs && budo demo/js/index.js:demo-bundle.js --dir demo --live -- -t babelify",
+    "start": "yarn compile:demo --watch --environment SERVE,RELOAD,IS_CYPRESS_ENV:''",
+    "start:cypress": "yarn compile:demo --environment SERVE,IS_CYPRESS_ENV:\"$CYPRESS_BROWSER\"",
     "test:types": "tsc index.d.ts",
     "test:unit": "echo \"No unit tests to run!\"",
-    "test:cypress": "start-server-and-test start 9966 'cypress open'",
-    "test:cypress:ci": "start-server-and-test start 9966 'cypress run --browser $CYPRESS_BROWSER --headless'",
+    "test:cypress": "CYPRESS_BROWSER=ANY start-server-and-test start:cypress 9966 'cypress open'",
+    "test:cypress:ci": "start-server-and-test start:cypress 9966 'cypress run --browser $CYPRESS_BROWSER --headless'",
     "test:chrome": "CYPRESS_BROWSER=chrome yarn test:cypress:ci",
     "test": "yarn format:check && yarn lint && yarn test:unit && yarn test:types && CYPRESS_BROWSER=chrome yarn test:cypress:ci",
     "prepare": "yarn build",
@@ -60,36 +62,36 @@
   },
   "homepage": "https://github.com/focus-trap/focus-trap#readme",
   "dependencies": {
-    "tabbable": "^5.2.0"
+    "tabbable": "^5.2.1"
   },
   "devDependencies": {
-    "@babel/cli": "^7.14.3",
-    "@babel/core": "^7.14.3",
-    "@babel/preset-env": "^7.14.4",
-    "@changesets/cli": "^2.16.0",
+    "@babel/cli": "^7.15.7",
+    "@babel/core": "^7.15.5",
+    "@babel/preset-env": "^7.15.6",
+    "@changesets/cli": "^2.17.0",
     "@rollup/plugin-babel": "^5.3.0",
-    "@rollup/plugin-commonjs": "^19.0.0",
-    "@rollup/plugin-node-resolve": "^13.0.0",
-    "@testing-library/cypress": "^7.0.6",
-    "@types/jquery": "^3.5.5",
+    "@rollup/plugin-commonjs": "^20.0.0",
+    "@rollup/plugin-node-resolve": "^13.0.5",
+    "@testing-library/cypress": "^8.0.1",
+    "@types/jquery": "^3.5.6",
     "all-contributors-cli": "^6.20.0",
     "babel-eslint": "^10.1.0",
     "babel-loader": "^8.2.2",
-    "babelify": "^10.0.0",
-    "browserify": "^17.0.0",
-    "budo": "^11.6.4",
     "cross-env": "^7.0.3",
-    "cypress": "^7.4.0",
+    "cypress": "^8.4.1",
     "cypress-plugin-tab": "^1.0.5",
-    "eslint": "^7.27.0",
+    "eslint": "^7.32.0",
     "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-cypress": "^2.11.3",
+    "eslint-plugin-cypress": "^2.12.1",
     "onchange": "^7.1.0",
-    "prettier": "^2.3.0",
-    "rollup": "^2.50.5",
+    "prettier": "^2.4.1",
+    "rollup": "^2.57.0",
+    "rollup-plugin-inject-process-env": "^1.3.1",
+    "rollup-plugin-livereload": "^2.0.5",
+    "rollup-plugin-serve": "^1.1.0",
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-terser": "^7.0.1",
-    "start-server-and-test": "^1.12.3",
-    "typescript": "^4.3.2"
+    "start-server-and-test": "^1.14.0",
+    "typescript": "^4.4.3"
   }
 }