focus-trap 6.6.1 → 6.7.3

package/index.js

@@ -1,4 +1,4 @@
-import { tabbable, isFocusable } from 'tabbable';
+import { tabbable, focusable, isFocusable, isTabbable } from 'tabbable';
 
 const activeFocusTraps = (function () {
   const trapQueue = [];
@@ -82,8 +82,23 @@ 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;
+  // SSR: a live trap shouldn't be created in this type of environment so this
+  //  should be safe code to execute if the `document` option isn't specified
+  const doc = userOptions?.document || document;
 
   const config = {
     returnFocusOnDeactivate: true,
@@ -102,7 +117,12 @@ const createFocusTrap = function (elements, userOptions) {
     //  is active, but the trap should never get to a state where there isn't at least one group
     //  with at least one tabbable node in it (that would lead to an error condition that would
     //  result in an error being thrown)
-    // @type {Array<{ container: HTMLElement, firstTabbableNode: HTMLElement|null, lastTabbableNode: HTMLElement|null }>}
+    // @type {Array<{
+    //   container: HTMLElement,
+    //   firstTabbableNode: HTMLElement|null,
+    //   lastTabbableNode: HTMLElement|null,
+    //   nextTabbableNode: (node: HTMLElement, forward: boolean) => HTMLElement|undefined
+    // }>}
     tabbableGroups: [],
 
     nodeFocusedBeforeActivation: null,
@@ -125,28 +145,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`
+        );
       }
     }
 
@@ -154,22 +197,25 @@ const createFocusTrap = function (elements, userOptions) {
   };
 
   const getInitialFocusNode = function () {
-    let node;
+    let node = getNodeForOption('initialFocus');
 
-    // false indicates we want no initialFocus at all
-    if (getOption({}, 'initialFocus') === false) {
+    // false explicitly indicates we want no initialFocus at all
+    if (node === false) {
       return false;
     }
 
-    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');
+    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) {
@@ -186,11 +232,46 @@ const createFocusTrap = function (elements, userOptions) {
       .map((container) => {
         const tabbableNodes = tabbable(container);
 
+        // NOTE: if we have tabbable nodes, we must have focusable nodes; focusable nodes
+        //  are a superset of tabbable nodes
+        const focusableNodes = focusable(container);
+
         if (tabbableNodes.length > 0) {
           return {
             container,
             firstTabbableNode: tabbableNodes[0],
             lastTabbableNode: tabbableNodes[tabbableNodes.length - 1],
+
+            /**
+             * Finds the __tabbable__ node that follows the given node in the specified direction,
+             *  in this container, if any.
+             * @param {HTMLElement} node
+             * @param {boolean} [forward] True if going in forward tab order; false if going
+             *  in reverse.
+             * @returns {HTMLElement|undefined} The next tabbable node, if any.
+             */
+            nextTabbableNode(node, forward = true) {
+              // NOTE: If tabindex is positive (in order to manipulate the tab order separate
+              //  from the DOM order), this __will not work__ because the list of focusableNodes,
+              //  while it contains tabbable nodes, does not sort its nodes in any order other
+              //  than DOM order, because it can't: Where would you place focusable (but not
+              //  tabbable) nodes in that order? They have no order, because they aren't tabbale...
+              // Support for positive tabindex is already broken and hard to manage (possibly
+              //  not supportable, TBD), so this isn't going to make things worse than they
+              //  already are, and at least makes things better for the majority of cases where
+              //  tabindex is either 0/unset or negative.
+              // FYI, positive tabindex issue: https://github.com/focus-trap/focus-trap/issues/375
+              const nodeIdx = focusableNodes.findIndex((n) => n === node);
+              if (forward) {
+                return focusableNodes
+                  .slice(nodeIdx + 1)
+                  .find((n) => isTabbable(n));
+              }
+              return focusableNodes
+                .slice(0, nodeIdx)
+                .reverse()
+                .find((n) => isTabbable(n));
+            },
           };
         }
 
@@ -201,7 +282,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'
@@ -232,15 +313,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;
     }
@@ -259,7 +341,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;
     }
@@ -278,11 +360,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
@@ -296,17 +380,20 @@ 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;
 
     if (state.tabbableGroups.length > 0) {
       // make sure the target is actually contained in a group
-      // NOTE: the target may also be the container itself if it's tabbable
+      // NOTE: the target may also be the container itself if it's focusable
       //  with tabIndex='-1' and was given initial focus
       const containerIndex = findIndex(state.tabbableGroups, ({ container }) =>
-        container.contains(e.target)
+        container.contains(target)
       );
+      const containerGroup =
+        containerIndex >= 0 ? state.tabbableGroups[containerIndex] : undefined;
 
       if (containerIndex < 0) {
         // target not found in any group: quite possible focus has escaped the trap,
@@ -326,14 +413,20 @@ 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
+          (containerGroup.container === target ||
+            (isFocusable(target) &&
+              !isTabbable(target) &&
+              !containerGroup.nextTabbableNode(target, false)))
         ) {
-          // an exception case where the target is the container itself, in which
+          // an exception case where the target is either the container itself, or
+          //  a non-tabbable node that was given focus (i.e. tabindex is negative
+          //  and user clicked on it or node was programmatically given focus)
+          //  and is not followed by any other tabbable node, in which
           //  case, we should handle shift+tab as if focus were on the container's
           //  first tabbable node, and go to the last tabbable node of the LAST group
           startOfGroupIndex = containerIndex;
@@ -357,14 +450,20 @@ 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
+          (containerGroup.container === target ||
+            (isFocusable(target) &&
+              !isTabbable(target) &&
+              !containerGroup.nextTabbableNode(target)))
         ) {
-          // an exception case where the target is the container itself, in which
+          // an exception case where the target is the container itself, or
+          //  a non-tabbable node that was given focus (i.e. tabindex is negative
+          //  and user clicked on it or node was programmatically given focus)
+          //  and is not followed by any other tabbable node, in which
           //  case, we should handle tab as if focus were on the container's
           //  last tabbable node, and go to the first tabbable node of the FIRST group
           lastOfGroupIndex = containerIndex;
@@ -384,6 +483,7 @@ const createFocusTrap = function (elements, userOptions) {
         }
       }
     } else {
+      // NOTE: the fallbackFocus option does not support returning false to opt-out
       destinationNode = getNodeForOption('fallbackFocus');
     }
 
@@ -397,7 +497,7 @@ const createFocusTrap = function (elements, userOptions) {
   const checkKey = function (e) {
     if (
       isEscapeEvent(e) &&
-      valueOrHandler(config.escapeDeactivates) !== false
+      valueOrHandler(config.escapeDeactivates, e) !== false
     ) {
       e.preventDefault();
       trap.deactivate();
@@ -415,7 +515,9 @@ const createFocusTrap = function (elements, userOptions) {
       return;
     }
 
-    if (containersContain(e.target)) {
+    const target = getActualTarget(e);
+
+    if (containersContain(target)) {
       return;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focus-trap",
-  "version": "6.6.1",
+  "version": "6.7.3",
   "description": "Trap focus within a DOM node.",
   "main": "dist/focus-trap.js",
   "module": "dist/focus-trap.esm.js",
@@ -17,7 +17,7 @@
     "dist"
   ],
   "scripts": {
-    "demo-bundle": "browserify docs/js/index.js -o docs/demo-bundle.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}}",
@@ -26,13 +26,15 @@
     "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 docs/js/index.js:demo-bundle.js --dir docs --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",
@@ -63,33 +65,33 @@
     "tabbable": "^5.2.1"
   },
   "devDependencies": {
-    "@babel/cli": "^7.14.8",
-    "@babel/core": "^7.15.0",
-    "@babel/preset-env": "^7.15.0",
-    "@changesets/cli": "^2.16.0",
+    "@babel/cli": "^7.17.0",
+    "@babel/core": "^7.17.2",
+    "@babel/eslint-parser": "^7.17.0",
+    "@babel/preset-env": "^7.16.11",
+    "@changesets/cli": "^2.20.0",
     "@rollup/plugin-babel": "^5.3.0",
-    "@rollup/plugin-commonjs": "^20.0.0",
-    "@rollup/plugin-node-resolve": "^13.0.4",
-    "@testing-library/cypress": "^8.0.0",
-    "@types/jquery": "^3.5.6",
+    "@rollup/plugin-commonjs": "^21.0.1",
+    "@rollup/plugin-node-resolve": "^13.1.3",
+    "@testing-library/cypress": "^8.0.2",
+    "@types/jquery": "^3.5.13",
     "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",
+    "babel-loader": "^8.2.3",
     "cross-env": "^7.0.3",
-    "cypress": "^8.2.0",
+    "cypress": "^9.4.1",
     "cypress-plugin-tab": "^1.0.5",
-    "eslint": "^7.32.0",
+    "eslint": "^8.8.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.2",
-    "rollup": "^2.56.2",
+    "prettier": "^2.5.1",
+    "rollup": "^2.67.1",
+    "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.13.1",
-    "typescript": "^4.3.5"
+    "start-server-and-test": "^1.14.0",
+    "typescript": "^4.5.5"
   }
 }