focus-trap 6.3.0 → 6.6.0

package/index.js

@@ -1,7 +1,5 @@
 import { tabbable, isFocusable } from 'tabbable';
 
-let activeFocusDelay;
-
 const activeFocusTraps = (function () {
   const trapQueue = [];
   return {
@@ -111,10 +109,21 @@ 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
 
+  const getOption = (configOverrideOptions, optionName, configOptionName) => {
+    return configOverrideOptions &&
+      configOverrideOptions[optionName] !== undefined
+      ? configOverrideOptions[optionName]
+      : config[configOptionName || optionName];
+  };
+
   const containersContain = function (element) {
     return state.containers.some((container) => container.contains(element));
   };
@@ -147,6 +156,11 @@ const createFocusTrap = function (elements, userOptions) {
   const getInitialFocusNode = function () {
     let node;
 
+    // false indicates we want no initialFocus at all
+    if (getOption({}, 'initialFocus') === false) {
+      return false;
+    }
+
     if (getNodeForOption('initialFocus') !== null) {
       node = getNodeForOption('initialFocus');
     } else if (containersContain(doc.activeElement)) {
@@ -196,9 +210,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;
@@ -283,6 +302,8 @@ const createFocusTrap = function (elements, userOptions) {
 
     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
+      //  with tabIndex='-1' and was given initial focus
       const containerIndex = findIndex(state.tabbableGroups, ({ container }) =>
         container.contains(e.target)
       );
@@ -301,12 +322,27 @@ const createFocusTrap = function (elements, userOptions) {
         }
       } else if (e.shiftKey) {
         // REVERSE
-        const startOfGroupIndex = findIndex(
+
+        // is the target the first tabbable node in a group?
+        let startOfGroupIndex = findIndex(
           state.tabbableGroups,
           ({ firstTabbableNode }) => e.target === firstTabbableNode
         );
 
+        if (
+          startOfGroupIndex < 0 &&
+          state.tabbableGroups[containerIndex].container === e.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
+          //  first tabbable node, and go to the last tabbable node of the LAST group
+          startOfGroupIndex = containerIndex;
+        }
+
         if (startOfGroupIndex >= 0) {
+          // YES: then shift+tab should go to the last tabbable node in the
+          //  previous group (and wrap around to the last tabbable node of
+          //  the LAST group if it's the first tabbable node of the FIRST group)
           const destinationGroupIndex =
             startOfGroupIndex === 0
               ? state.tabbableGroups.length - 1
@@ -317,12 +353,27 @@ const createFocusTrap = function (elements, userOptions) {
         }
       } else {
         // FORWARD
-        const lastOfGroupIndex = findIndex(
+
+        // is the target the last tabbable node in a group?
+        let lastOfGroupIndex = findIndex(
           state.tabbableGroups,
           ({ lastTabbableNode }) => e.target === lastTabbableNode
         );
 
+        if (
+          lastOfGroupIndex < 0 &&
+          state.tabbableGroups[containerIndex].container === e.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
+          //  last tabbable node, and go to the first tabbable node of the FIRST group
+          lastOfGroupIndex = containerIndex;
+        }
+
         if (lastOfGroupIndex >= 0) {
+          // YES: then tab should go to the first tabbable node in the next
+          //  group (and wrap around to the first tabbable node of the FIRST
+          //  group if it's the last tabbable node of the LAST group)
           const destinationGroupIndex =
             lastOfGroupIndex === state.tabbableGroups.length - 1
               ? 0
@@ -340,10 +391,14 @@ const createFocusTrap = function (elements, userOptions) {
       e.preventDefault();
       tryFocus(destinationNode);
     }
+    // else, let the browser take care of [shift+]tab and move the focus
   };
 
   const checkKey = function (e) {
-    if (config.escapeDeactivates !== false && isEscapeEvent(e)) {
+    if (
+      isEscapeEvent(e) &&
+      valueOrHandler(config.escapeDeactivates) !== false
+    ) {
       e.preventDefault();
       trap.deactivate();
       return;
@@ -386,7 +441,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());
         })
@@ -437,21 +492,41 @@ const createFocusTrap = function (elements, userOptions) {
         return this;
       }
 
-      updateTabbableNodes();
+      const onActivate = getOption(activateOptions, 'onActivate');
+      const onPostActivate = getOption(activateOptions, 'onPostActivate');
+      const checkCanFocusTrap = getOption(activateOptions, 'checkCanFocusTrap');
+
+      if (!checkCanFocusTrap) {
+        updateTabbableNodes();
+      }
 
       state.active = true;
       state.paused = false;
       state.nodeFocusedBeforeActivation = doc.activeElement;
 
-      const onActivate =
-        activateOptions && activateOptions.onActivate
-          ? activateOptions.onActivate
-          : config.onActivate;
       if (onActivate) {
         onActivate();
       }
 
-      addListeners();
+      const finishActivation = () => {
+        if (checkCanFocusTrap) {
+          updateTabbableNodes();
+        }
+        addListeners();
+        if (onPostActivate) {
+          onPostActivate();
+        }
+      };
+
+      if (checkCanFocusTrap) {
+        checkCanFocusTrap(state.containers.concat()).then(
+          finishActivation,
+          finishActivation
+        );
+        return this;
+      }
+
+      finishActivation();
       return this;
     },
 
@@ -460,7 +535,8 @@ const createFocusTrap = function (elements, userOptions) {
         return this;
       }
 
-      clearTimeout(activeFocusDelay);
+      clearTimeout(state.delayInitialFocusTimer); // noop if undefined
+      state.delayInitialFocusTimer = undefined;
 
       removeListeners();
       state.active = false;
@@ -468,25 +544,42 @@ const createFocusTrap = function (elements, userOptions) {
 
       activeFocusTraps.deactivateTrap(trap);
 
-      const onDeactivate =
-        deactivateOptions && deactivateOptions.onDeactivate !== undefined
-          ? deactivateOptions.onDeactivate
-          : config.onDeactivate;
+      const onDeactivate = getOption(deactivateOptions, 'onDeactivate');
+      const onPostDeactivate = getOption(deactivateOptions, 'onPostDeactivate');
+      const checkCanReturnFocus = getOption(
+        deactivateOptions,
+        'checkCanReturnFocus'
+      );
+
       if (onDeactivate) {
         onDeactivate();
       }
 
-      const returnFocus =
-        deactivateOptions && deactivateOptions.returnFocus !== undefined
-          ? deactivateOptions.returnFocus
-          : config.returnFocusOnDeactivate;
+      const returnFocus = getOption(
+        deactivateOptions,
+        'returnFocus',
+        'returnFocusOnDeactivate'
+      );
 
-      if (returnFocus) {
-        delay(function () {
-          tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
+      const finishDeactivation = () => {
+        delay(() => {
+          if (returnFocus) {
+            tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
+          }
+          if (onPostDeactivate) {
+            onPostDeactivate();
+          }
         });
+      };
+
+      if (returnFocus && checkCanReturnFocus) {
+        checkCanReturnFocus(
+          getReturnFocusNode(state.nodeFocusedBeforeActivation)
+        ).then(finishDeactivation, finishDeactivation);
+        return this;
       }
 
+      finishDeactivation();
       return this;
     },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focus-trap",
-  "version": "6.3.0",
+  "version": "6.6.0",
   "description": "Trap focus within a DOM node.",
   "main": "dist/focus-trap.js",
   "module": "dist/focus-trap.esm.js",
@@ -17,23 +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": "browserify docs/js/index.js -o docs/demo-bundle.js",
+    "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": "BUILD_ENV=esm BABEL_ENV=esm rollup -c",
-    "compile:cjs": "BUILD_ENV=cjs BABEL_ENV=es5 rollup -c",
-    "compile:umd": "BUILD_ENV=umd BABEL_ENV=es5 rollup -c",
+    "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": "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:cjs && budo docs/js/index.js:demo-bundle.js --dir docs --live -- -t babelify",
     "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": "yarn format:check && yarn lint && yarn test:unit && yarn test:types && CYPRESS_BROWSER=chrome yarn test:cypress-ci",
+    "test:cypress:ci": "start-server-and-test start 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",
     "release": "yarn build && changeset publish"
   },
@@ -59,35 +60,36 @@
   },
   "homepage": "https://github.com/focus-trap/focus-trap#readme",
   "dependencies": {
-    "tabbable": "^5.1.5"
+    "tabbable": "^5.2.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.12.10",
-    "@babel/core": "^7.12.10",
-    "@babel/preset-env": "^7.12.11",
-    "@changesets/cli": "^2.12.0",
-    "@rollup/plugin-babel": "^5.2.2",
-    "@rollup/plugin-commonjs": "^17.0.0",
-    "@rollup/plugin-node-resolve": "^11.0.1",
-    "@testing-library/cypress": "^7.0.3",
+    "@babel/cli": "^7.14.5",
+    "@babel/core": "^7.14.6",
+    "@babel/preset-env": "^7.14.7",
+    "@changesets/cli": "^2.16.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",
-    "all-contributors-cli": "^6.19.0",
+    "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",
-    "cypress": "^6.2.1",
+    "cross-env": "^7.0.3",
+    "cypress": "^7.6.0",
     "cypress-plugin-tab": "^1.0.5",
-    "eslint": "^7.17.0",
-    "eslint-config-prettier": "^7.1.0",
-    "eslint-plugin-cypress": "^2.11.2",
+    "eslint": "^7.29.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-cypress": "^2.11.3",
     "onchange": "^7.1.0",
-    "prettier": "^2.2.1",
-    "rollup": "^2.36.1",
+    "prettier": "^2.3.2",
+    "rollup": "^2.52.4",
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-terser": "^7.0.1",
-    "start-server-and-test": "^1.11.7",
-    "typescript": "^4.1.3"
+    "start-server-and-test": "^1.12.5",
+    "typescript": "^4.3.4"
   }
 }