focus-trap 6.2.3 → 6.5.1

package/index.d.ts

@@ -4,19 +4,65 @@ declare module 'focus-trap' {
    * `document.querySelector()` to find the DOM node), or a function that
    * returns a DOM node.
    */
-  export type FocusTarget = HTMLElement | string | { (): HTMLElement };
+  export type FocusTarget = HTMLElement | SVGElement | string | { (): HTMLElement | SVGElement };
 
-  type MouseEventToBoolean = (event: MouseEvent) => boolean
+  type MouseEventToBoolean = (event: MouseEvent | TouchEvent) => boolean
 
   export interface Options {
     /**
-     * A function that will be called when the focus trap activates.
+     * A function that will be called **before** sending focus to the
+     * target element upon activation.
      */
     onActivate?: () => void;
+
+    /**
+     * A function that will be called **after** focus has been sent to the
+     * target element upon activation.
+     */
+    onPostActivate?: () => void
+
+    /**
+     * A function for determining if it is safe to send focus to the focus trap
+     * or not.
+     *
+     * It should return a promise that only resolves once all the listed `containers`
+     * are able to receive focus.
+     *
+     * The purpose of this is to prevent early focus-trap activation on animated
+     * dialogs that fade in and out. When a dialog fades in, there is a brief delay
+     * between the activation of the trap and the trap element being focusable.
+     */
+    checkCanFocusTrap?: (containers: Array<HTMLElement | SVGElement>) => Promise<void>
+
     /**
-     * A function that will be called when the focus trap deactivates.
+     * A function that will be called **before** sending focus to the
+     * trigger element upon deactivation.
      */
     onDeactivate?: () => void;
+
+    /**
+     * A function that will be called after the trap is deactivated, after `onDeactivate`.
+     * If `returnFocus` was set, it will be called **after** focus has been sent to the trigger
+     * element upon deactivation; otherwise, it will be called after deactivation completes.
+     */
+    onPostDeactivate?: () => void
+    /**
+     * A function for determining if it is safe to send focus back to the `trigger` element.
+     *
+     * It should return a promise that only resolves once `trigger` is focusable.
+     *
+     * The purpose of this is to prevent the focus being sent to an animated trigger element too early.
+     * If a trigger element fades in upon trap deactivation, there is a brief delay between the deactivation
+     * of the trap and when the trigger element is focusable.
+     *
+     * `trigger` will be either the node that had focus prior to the trap being activated,
+     * or the result of the `setReturnFocus` option, if configured.
+     *
+     * This handler is **not** called if the `returnFocusOnDeactivate` configuration option
+     * (or the `returnFocus` deactivation option) is falsy.
+     */
+    checkCanReturnFocus?: (trigger: HTMLElement | SVGElement) => Promise<void>
+
     /**
      * By default, when a focus trap is activated the first element in the
      * focus trap's tab order will receive focus. With this option you can
@@ -51,19 +97,20 @@ declare module 'focus-trap' {
      */
     escapeDeactivates?: boolean;
     /**
-     * Default: `false`. If `true`, a click outside the focus trap will
-     * deactivate the focus trap and allow the click event to do its thing.
-     * This option **takes precedence** over `allowOutsideClick` when it's set
-     * to `true`.
+     * If `true` or returns `true`, a click outside the focus trap will
+     * deactivate the focus trap and allow the click event to do its thing (i.e.
+     * to pass-through to the element that was clicked). This option **takes
+     * precedence** over `allowOutsideClick` when it's set to `true`, causing
+     * that option to be ignored. Default: `false`.
      */
-    clickOutsideDeactivates?: boolean;
+    clickOutsideDeactivates?: boolean | MouseEventToBoolean;
     /**
      * If set and is or returns `true`, a click outside the focus trap will not
      * be prevented, even when `clickOutsideDeactivates` is `false`. When
      * `clickOutsideDeactivates` is `true`, this option is **ignored** (i.e.
      * if it's a function, it will not be called). Use this option to control
      * if (and even which) clicks are allowed outside the trap in conjunction
-     * with `clickOutsideDeactivates: false`.
+     * with `clickOutsideDeactivates: false`. Default: `false`.
      */
     allowOutsideClick?: boolean | MouseEventToBoolean;
     /**
@@ -80,9 +127,9 @@ declare module 'focus-trap' {
     delayInitialFocus?: boolean;
   }
 
-  type ActivateOptions = Pick<Options, 'onActivate'>;
+  type ActivateOptions = Pick<Options, 'onActivate' | 'onPostActivate' | 'checkCanFocusTrap'>;
 
-  interface DeactivateOptions extends Pick<Options, 'onDeactivate'> {
+  interface DeactivateOptions extends Pick<Options, 'onDeactivate' | 'onPostDeactivate' | 'checkCanReturnFocus'> {
     returnFocus?: boolean;
   }
 
@@ -91,7 +138,7 @@ declare module 'focus-trap' {
     deactivate(deactivateOptions?: DeactivateOptions): FocusTrap;
     pause(): FocusTrap;
     unpause(): FocusTrap;
-    updateContainerElements(containerElements: HTMLElement | string | Array<HTMLElement | string>): FocusTrap;
+    updateContainerElements(containerElements: HTMLElement | SVGElement | string | Array<HTMLElement | SVGElement | string>): FocusTrap;
   }
 
   /**
@@ -102,7 +149,7 @@ declare module 'focus-trap' {
    *  find the element.
    */
   export function createFocusTrap(
-    element: HTMLElement | string | Array<HTMLElement | string>,
+    element: HTMLElement | SVGElement | string | Array<HTMLElement | SVGElement | string>,
     userOptions?: Options
   ): FocusTrap;
 }

package/index.js

@@ -73,6 +73,17 @@ const findIndex = function (arr, fn) {
   return idx;
 };
 
+/**
+ * Get an option's value when it could be a plain value, or a handler that provides
+ *  the value.
+ * @param {*} value Option's value to check.
+ * @param {...*} [params] Any parameters to pass to the handler, if `value` is a function.
+ * @returns {*} The `value`, or the handler's returned value.
+ */
+const valueOrHandler = function (value, ...params) {
+  return typeof value === 'function' ? value(...params) : value;
+};
+
 const createFocusTrap = function (elements, userOptions) {
   const doc = document;
 
@@ -93,7 +104,7 @@ 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<{ firstTabbableNode: HTMLElement|null, lastTabbableNode: HTMLElement|null }>}
+    // @type {Array<{ container: HTMLElement, firstTabbableNode: HTMLElement|null, lastTabbableNode: HTMLElement|null }>}
     tabbableGroups: [],
 
     nodeFocusedBeforeActivation: null,
@@ -104,6 +115,13 @@ const createFocusTrap = function (elements, userOptions) {
 
   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));
   };
@@ -163,6 +181,7 @@ const createFocusTrap = function (elements, userOptions) {
 
         if (tabbableNodes.length > 0) {
           return {
+            container,
             firstTabbableNode: tabbableNodes[0],
             lastTabbableNode: tabbableNodes[tabbableNodes.length - 1],
           };
@@ -214,7 +233,7 @@ const createFocusTrap = function (elements, userOptions) {
       return;
     }
 
-    if (config.clickOutsideDeactivates) {
+    if (valueOrHandler(config.clickOutsideDeactivates, e)) {
       // immediately deactivate the trap
       trap.deactivate({
         // if, on deactivation, we should return focus to the node originally-focused
@@ -236,12 +255,7 @@ const createFocusTrap = function (elements, userOptions) {
     // This is needed for mobile devices.
     // (If we'll only let `click` events through,
     // then on mobile they will be blocked anyways if `touchstart` is blocked.)
-    if (
-      config.allowOutsideClick &&
-      (typeof config.allowOutsideClick === 'boolean'
-        ? config.allowOutsideClick
-        : config.allowOutsideClick(e))
-    ) {
+    if (valueOrHandler(config.allowOutsideClick, e)) {
       // allow the click outside the trap to take place
       return;
     }
@@ -275,13 +289,48 @@ const createFocusTrap = function (elements, userOptions) {
     let destinationNode = null;
 
     if (state.tabbableGroups.length > 0) {
-      if (e.shiftKey) {
-        const startOfGroupIndex = findIndex(
+      // 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)
+      );
+
+      if (containerIndex < 0) {
+        // target not found in any group: quite possible focus has escaped the trap,
+        //  so bring it back in to...
+        if (e.shiftKey) {
+          // ...the last node in the last group
+          destinationNode =
+            state.tabbableGroups[state.tabbableGroups.length - 1]
+              .lastTabbableNode;
+        } else {
+          // ...the first node in the first group
+          destinationNode = state.tabbableGroups[0].firstTabbableNode;
+        }
+      } else if (e.shiftKey) {
+        // REVERSE
+
+        // 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
@@ -291,12 +340,28 @@ const createFocusTrap = function (elements, userOptions) {
           destinationNode = destinationGroup.lastTabbableNode;
         }
       } else {
-        const lastOfGroupIndex = findIndex(
+        // FORWARD
+
+        // 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
@@ -314,6 +379,7 @@ 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) {
@@ -330,7 +396,7 @@ const createFocusTrap = function (elements, userOptions) {
   };
 
   const checkClick = function (e) {
-    if (config.clickOutsideDeactivates) {
+    if (valueOrHandler(config.clickOutsideDeactivates, e)) {
       return;
     }
 
@@ -338,12 +404,7 @@ const createFocusTrap = function (elements, userOptions) {
       return;
     }
 
-    if (
-      config.allowOutsideClick &&
-      (typeof config.allowOutsideClick === 'boolean'
-        ? config.allowOutsideClick
-        : config.allowOutsideClick(e))
-    ) {
+    if (valueOrHandler(config.allowOutsideClick, e)) {
       return;
     }
 
@@ -416,21 +477,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;
     },
 
@@ -447,25 +528,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.2.3",
+  "version": "6.5.1",
   "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)\"",
-    "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"
   },
@@ -58,34 +60,36 @@
   },
   "homepage": "https://github.com/focus-trap/focus-trap#readme",
   "dependencies": {
-    "tabbable": "^5.1.4"
+    "tabbable": "^5.2.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.12.8",
-    "@babel/core": "^7.12.9",
-    "@babel/preset-env": "^7.12.7",
-    "@changesets/cli": "^2.12.0",
-    "@rollup/plugin-babel": "^5.2.2",
-    "@rollup/plugin-commonjs": "^17.0.0",
-    "@rollup/plugin-node-resolve": "^11.0.0",
-    "@testing-library/cypress": "^7.0.2",
+    "@babel/cli": "^7.14.5",
+    "@babel/core": "^7.14.6",
+    "@babel/preset-env": "^7.14.5",
+    "@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.1.0",
+    "cross-env": "^7.0.3",
+    "cypress": "^7.5.0",
     "cypress-plugin-tab": "^1.0.5",
-    "eslint": "^7.15.0",
-    "eslint-config-prettier": "^7.0.0",
-    "eslint-plugin-cypress": "^2.11.2",
-    "prettier": "^2.2.1",
-    "rollup": "^2.34.2",
+    "eslint": "^7.28.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-cypress": "^2.11.3",
+    "onchange": "^7.1.0",
+    "prettier": "^2.3.1",
+    "rollup": "^2.51.2",
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-terser": "^7.0.1",
-    "start-server-and-test": "^1.11.6",
-    "typescript": "^4.1.2"
+    "start-server-and-test": "^1.12.5",
+    "typescript": "^4.3.2"
   }
 }