focus-trap 6.2.0 → 6.3.0

package/dist/focus-trap.umd.js

@@ -1,5 +1,5 @@
 /*!
-* focus-trap 6.2.0
+* focus-trap 6.3.0
 * @license MIT, https://github.com/focus-trap/focus-trap/blob/master/LICENSE
 */
 (function (global, factory) {
@@ -100,7 +100,54 @@
     };
   }();
 
-  function createFocusTrap(elements, userOptions) {
+  var isSelectableInput = function isSelectableInput(node) {
+    return node.tagName && node.tagName.toLowerCase() === 'input' && typeof node.select === 'function';
+  };
+
+  var isEscapeEvent = function isEscapeEvent(e) {
+    return e.key === 'Escape' || e.key === 'Esc' || e.keyCode === 27;
+  };
+
+  var isTabEvent = function isTabEvent(e) {
+    return e.key === 'Tab' || e.keyCode === 9;
+  };
+
+  var delay = function delay(fn) {
+    return setTimeout(fn, 0);
+  }; // Array.find/findIndex() are not supported on IE; this replicates enough
+  //  of Array.findIndex() for our needs
+
+
+  var findIndex = function findIndex(arr, fn) {
+    var idx = -1;
+    arr.every(function (value, i) {
+      if (fn(value)) {
+        idx = i;
+        return false; // break
+      }
+
+      return true; // next
+    });
+    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.
+   */
+
+
+  var valueOrHandler = function valueOrHandler(value) {
+    for (var _len = arguments.length, params = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+      params[_key - 1] = arguments[_key];
+    }
+
+    return typeof value === 'function' ? value.apply(void 0, params) : value;
+  };
+
+  var createFocusTrap = function createFocusTrap(elements, userOptions) {
     var doc = document;
 
     var config = _objectSpread2({
@@ -112,143 +159,41 @@
     var state = {
       // @type {Array<HTMLElement>}
       containers: [],
-      // @type {{ firstTabbableNode: HTMLElement, lastTabbableNode: HTMLElement }}
+      // list of objects identifying the first and last tabbable nodes in all containers/groups in
+      //  the trap
+      // NOTE: it's possible that a group has no tabbable nodes if nodes get removed while the trap
+      //  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 }>}
       tabbableGroups: [],
       nodeFocusedBeforeActivation: null,
       mostRecentlyFocusedNode: null,
       active: false,
       paused: false
     };
-    var trap = {
-      activate: activate,
-      deactivate: deactivate,
-      pause: pause,
-      unpause: unpause,
-      updateContainerElements: updateContainerElements
-    };
-    updateContainerElements(elements);
-    return trap;
-
-    function updateContainerElements(containerElements) {
-      var elementsAsArray = [].concat(containerElements).filter(Boolean);
-      state.containers = elementsAsArray.map(function (element) {
-        return typeof element === 'string' ? doc.querySelector(element) : element;
-      });
-
-      if (state.active) {
-        updateTabbableNodes();
-      }
-
-      return trap;
-    }
-
-    function activate(activateOptions) {
-      if (state.active) return;
-      updateTabbableNodes();
-      state.active = true;
-      state.paused = false;
-      state.nodeFocusedBeforeActivation = doc.activeElement;
-      var onActivate = activateOptions && activateOptions.onActivate ? activateOptions.onActivate : config.onActivate;
-
-      if (onActivate) {
-        onActivate();
-      }
-
-      addListeners();
-      return trap;
-    }
+    var 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
 
-    function deactivate(deactivateOptions) {
-      if (!state.active) return;
-      clearTimeout(activeFocusDelay);
-      removeListeners();
-      state.active = false;
-      state.paused = false;
-      activeFocusTraps.deactivateTrap(trap);
-      var onDeactivate = deactivateOptions && deactivateOptions.onDeactivate !== undefined ? deactivateOptions.onDeactivate : config.onDeactivate;
-
-      if (onDeactivate) {
-        onDeactivate();
-      }
-
-      var returnFocus = deactivateOptions && deactivateOptions.returnFocus !== undefined ? deactivateOptions.returnFocus : config.returnFocusOnDeactivate;
-
-      if (returnFocus) {
-        delay(function () {
-          tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
-        });
-      }
-
-      return trap;
-    }
-
-    function pause() {
-      if (state.paused || !state.active) return trap;
-      state.paused = true;
-      removeListeners();
-      return trap;
-    }
-
-    function unpause() {
-      if (!state.paused || !state.active) return trap;
-      state.paused = false;
-      updateTabbableNodes();
-      addListeners();
-      return trap;
-    }
-
-    function addListeners() {
-      if (!state.active) return; // There can be only one listening focus trap at a time
-
-      activeFocusTraps.activateTrap(trap); // Delay ensures that the focused element doesn't capture the event
-      // that caused the focus trap activation.
-
-      activeFocusDelay = config.delayInitialFocus ? delay(function () {
-        tryFocus(getInitialFocusNode());
-      }) : tryFocus(getInitialFocusNode());
-      doc.addEventListener('focusin', checkFocusIn, true);
-      doc.addEventListener('mousedown', checkPointerDown, {
-        capture: true,
-        passive: false
-      });
-      doc.addEventListener('touchstart', checkPointerDown, {
-        capture: true,
-        passive: false
-      });
-      doc.addEventListener('click', checkClick, {
-        capture: true,
-        passive: false
-      });
-      doc.addEventListener('keydown', checkKey, {
-        capture: true,
-        passive: false
+    var containersContain = function containersContain(element) {
+      return state.containers.some(function (container) {
+        return container.contains(element);
       });
-      return trap;
-    }
-
-    function removeListeners() {
-      if (!state.active) return;
-      doc.removeEventListener('focusin', checkFocusIn, true);
-      doc.removeEventListener('mousedown', checkPointerDown, true);
-      doc.removeEventListener('touchstart', checkPointerDown, true);
-      doc.removeEventListener('click', checkClick, true);
-      doc.removeEventListener('keydown', checkKey, true);
-      return trap;
-    }
+    };
 
-    function getNodeForOption(optionName) {
+    var getNodeForOption = function getNodeForOption(optionName) {
       var optionValue = config[optionName];
-      var node = optionValue;
 
       if (!optionValue) {
         return null;
       }
 
+      var node = optionValue;
+
       if (typeof optionValue === 'string') {
         node = doc.querySelector(optionValue);
 
         if (!node) {
-          throw new Error('`' + optionName + '` refers to no known node');
+          throw new Error("`".concat(optionName, "` refers to no known node"));
         }
       }
 
@@ -256,14 +201,14 @@
         node = optionValue();
 
         if (!node) {
-          throw new Error('`' + optionName + '` did not return a node');
+          throw new Error("`".concat(optionName, "` did not return a node"));
         }
       }
 
       return node;
-    }
+    };
 
-    function getInitialFocusNode() {
+    var getInitialFocusNode = function getInitialFocusNode() {
       var node;
 
       if (getNodeForOption('initialFocus') !== null) {
@@ -281,24 +226,67 @@
       }
 
       return node;
-    }
+    };
+
+    var updateTabbableNodes = function updateTabbableNodes() {
+      state.tabbableGroups = state.containers.map(function (container) {
+        var tabbableNodes = tabbable.tabbable(container);
 
-    function getReturnFocusNode(previousActiveElement) {
+        if (tabbableNodes.length > 0) {
+          return {
+            container: container,
+            firstTabbableNode: tabbableNodes[0],
+            lastTabbableNode: tabbableNodes[tabbableNodes.length - 1]
+          };
+        }
+
+        return undefined;
+      }).filter(function (group) {
+        return !!group;
+      }); // remove groups with no tabbable nodes
+      // throw if no groups have tabbable nodes and we don't have a fallback focus node either
+
+      if (state.tabbableGroups.length <= 0 && !getNodeForOption('fallbackFocus')) {
+        throw new Error('Your focus-trap must have at least one container with at least one tabbable node in it at all times');
+      }
+    };
+
+    var tryFocus = function tryFocus(node) {
+      if (node === doc.activeElement) {
+        return;
+      }
+
+      if (!node || !node.focus) {
+        tryFocus(getInitialFocusNode());
+        return;
+      }
+
+      node.focus({
+        preventScroll: !!config.preventScroll
+      });
+      state.mostRecentlyFocusedNode = node;
+
+      if (isSelectableInput(node)) {
+        node.select();
+      }
+    };
+
+    var getReturnFocusNode = function getReturnFocusNode(previousActiveElement) {
       var node = getNodeForOption('setReturnFocus');
       return node ? node : previousActiveElement;
-    } // This needs to be done on mousedown and touchstart instead of click
+    }; // This needs to be done on mousedown and touchstart instead of click
     // so that it precedes the focus event.
 
 
-    function checkPointerDown(e) {
+    var checkPointerDown = function checkPointerDown(e) {
       if (containersContain(e.target)) {
         // allow the click since it ocurred inside the trap
         return;
       }
 
-      if (config.clickOutsideDeactivates) {
+      if (valueOrHandler(config.clickOutsideDeactivates, e)) {
         // immediately deactivate the trap
-        deactivate({
+        trap.deactivate({
           // if, on deactivation, we should return focus to the node originally-focused
           //  when the trap was activated (or the configured `setReturnFocus` node),
           //  then assume it's also OK to return focus to the outside node that was
@@ -318,140 +306,253 @@
       // 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;
       } // otherwise, prevent the click
 
 
       e.preventDefault();
-    } // In case focus escapes the trap for some strange reason, pull it back in.
+    }; // In case focus escapes the trap for some strange reason, pull it back in.
 
 
-    function checkFocusIn(e) {
-      // In Firefox when you Tab out of an iframe the Document is briefly focused.
-      if (containersContain(e.target) || e.target instanceof Document) {
-        return;
-      }
+    var checkFocusIn = function checkFocusIn(e) {
+      var targetContained = containersContain(e.target); // In Firefox when you Tab out of an iframe the Document is briefly focused.
 
-      e.stopImmediatePropagation();
-      tryFocus(state.mostRecentlyFocusedNode || getInitialFocusNode());
-    }
-
-    function checkKey(e) {
-      if (config.escapeDeactivates !== false && isEscapeEvent(e)) {
-        e.preventDefault();
-        deactivate();
-        return;
-      }
-
-      if (isTabEvent(e)) {
-        checkTab(e);
-        return;
+      if (targetContained || e.target instanceof Document) {
+        if (targetContained) {
+          state.mostRecentlyFocusedNode = e.target;
+        }
+      } else {
+        // escaped! pull it back in to where it just left
+        e.stopImmediatePropagation();
+        tryFocus(state.mostRecentlyFocusedNode || getInitialFocusNode());
       }
-    } // Hijack Tab events on the first and last focusable nodes of the trap,
+    }; // Hijack Tab events on the first and last focusable nodes of the trap,
     // in order to prevent focus from escaping. If it escapes for even a
     // moment it can end up scrolling the page and causing confusion so we
     // kind of need to capture the action at the keydown phase.
 
 
-    function checkTab(e) {
+    var checkTab = function checkTab(e) {
       updateTabbableNodes();
       var destinationNode = null;
 
-      if (e.shiftKey) {
-        var startOfGroupIndex = state.tabbableGroups.findIndex(function (_ref) {
-          var firstTabbableNode = _ref.firstTabbableNode;
-          return e.target === firstTabbableNode;
+      if (state.tabbableGroups.length > 0) {
+        // make sure the target is actually contained in a group
+        var containerIndex = findIndex(state.tabbableGroups, function (_ref) {
+          var container = _ref.container;
+          return container.contains(e.target);
         });
 
-        if (startOfGroupIndex >= 0) {
-          var destinationGroupIndex = startOfGroupIndex === 0 ? state.tabbableGroups.length - 1 : startOfGroupIndex - 1;
-          var destinationGroup = state.tabbableGroups[destinationGroupIndex];
-          destinationNode = destinationGroup.lastTabbableNode;
-        }
-      } else {
-        var lastOfGroupIndex = state.tabbableGroups.findIndex(function (_ref2) {
-          var lastTabbableNode = _ref2.lastTabbableNode;
-          return e.target === lastTabbableNode;
-        });
+        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
+          var startOfGroupIndex = findIndex(state.tabbableGroups, function (_ref2) {
+            var firstTabbableNode = _ref2.firstTabbableNode;
+            return e.target === firstTabbableNode;
+          });
+
+          if (startOfGroupIndex >= 0) {
+            var destinationGroupIndex = startOfGroupIndex === 0 ? state.tabbableGroups.length - 1 : startOfGroupIndex - 1;
+            var destinationGroup = state.tabbableGroups[destinationGroupIndex];
+            destinationNode = destinationGroup.lastTabbableNode;
+          }
+        } else {
+          // FORWARD
+          var lastOfGroupIndex = findIndex(state.tabbableGroups, function (_ref3) {
+            var lastTabbableNode = _ref3.lastTabbableNode;
+            return e.target === lastTabbableNode;
+          });
 
-        if (lastOfGroupIndex >= 0) {
-          var _destinationGroupIndex = lastOfGroupIndex === state.tabbableGroups.length - 1 ? 0 : lastOfGroupIndex + 1;
+          if (lastOfGroupIndex >= 0) {
+            var _destinationGroupIndex = lastOfGroupIndex === state.tabbableGroups.length - 1 ? 0 : lastOfGroupIndex + 1;
 
-          var _destinationGroup = state.tabbableGroups[_destinationGroupIndex];
-          destinationNode = _destinationGroup.firstTabbableNode;
+            var _destinationGroup = state.tabbableGroups[_destinationGroupIndex];
+            destinationNode = _destinationGroup.firstTabbableNode;
+          }
         }
+      } else {
+        destinationNode = getNodeForOption('fallbackFocus');
       }
 
       if (destinationNode) {
         e.preventDefault();
         tryFocus(destinationNode);
       }
-    }
+    };
 
-    function checkClick(e) {
-      if (config.clickOutsideDeactivates) return;
-      if (containersContain(e.target)) return;
+    var checkKey = function checkKey(e) {
+      if (config.escapeDeactivates !== false && isEscapeEvent(e)) {
+        e.preventDefault();
+        trap.deactivate();
+        return;
+      }
 
-      if (config.allowOutsideClick && (typeof config.allowOutsideClick === 'boolean' ? config.allowOutsideClick : config.allowOutsideClick(e))) {
+      if (isTabEvent(e)) {
+        checkTab(e);
+        return;
+      }
+    };
+
+    var checkClick = function checkClick(e) {
+      if (valueOrHandler(config.clickOutsideDeactivates, e)) {
+        return;
+      }
+
+      if (containersContain(e.target)) {
+        return;
+      }
+
+      if (valueOrHandler(config.allowOutsideClick, e)) {
         return;
       }
 
       e.preventDefault();
       e.stopImmediatePropagation();
-    }
+    }; //
+    // EVENT LISTENERS
+    //
 
-    function updateTabbableNodes() {
-      state.tabbableGroups = state.containers.map(function (container) {
-        var tabbableNodes = tabbable.tabbable(container);
-        return {
-          firstTabbableNode: tabbableNodes[0],
-          lastTabbableNode: tabbableNodes[tabbableNodes.length - 1]
-        };
-      });
-    }
 
-    function tryFocus(node) {
-      if (node === doc.activeElement) return;
+    var addListeners = function addListeners() {
+      if (!state.active) {
+        return;
+      } // There can be only one listening focus trap at a time
 
-      if (!node || !node.focus) {
+
+      activeFocusTraps.activateTrap(trap); // Delay ensures that the focused element doesn't capture the event
+      // that caused the focus trap activation.
+
+      activeFocusDelay = config.delayInitialFocus ? delay(function () {
         tryFocus(getInitialFocusNode());
+      }) : tryFocus(getInitialFocusNode());
+      doc.addEventListener('focusin', checkFocusIn, true);
+      doc.addEventListener('mousedown', checkPointerDown, {
+        capture: true,
+        passive: false
+      });
+      doc.addEventListener('touchstart', checkPointerDown, {
+        capture: true,
+        passive: false
+      });
+      doc.addEventListener('click', checkClick, {
+        capture: true,
+        passive: false
+      });
+      doc.addEventListener('keydown', checkKey, {
+        capture: true,
+        passive: false
+      });
+      return trap;
+    };
+
+    var removeListeners = function removeListeners() {
+      if (!state.active) {
         return;
       }
 
-      node.focus({
-        preventScroll: !!config.preventScroll
-      });
-      state.mostRecentlyFocusedNode = node;
+      doc.removeEventListener('focusin', checkFocusIn, true);
+      doc.removeEventListener('mousedown', checkPointerDown, true);
+      doc.removeEventListener('touchstart', checkPointerDown, true);
+      doc.removeEventListener('click', checkClick, true);
+      doc.removeEventListener('keydown', checkKey, true);
+      return trap;
+    }; //
+    // TRAP DEFINITION
+    //
 
-      if (isSelectableInput(node)) {
-        node.select();
-      }
-    }
 
-    function containersContain(element) {
-      return state.containers.some(function (container) {
-        return container.contains(element);
-      });
-    }
-  }
+    trap = {
+      activate: function activate(activateOptions) {
+        if (state.active) {
+          return this;
+        }
 
-  function isSelectableInput(node) {
-    return node.tagName && node.tagName.toLowerCase() === 'input' && typeof node.select === 'function';
-  }
+        updateTabbableNodes();
+        state.active = true;
+        state.paused = false;
+        state.nodeFocusedBeforeActivation = doc.activeElement;
+        var onActivate = activateOptions && activateOptions.onActivate ? activateOptions.onActivate : config.onActivate;
 
-  function isEscapeEvent(e) {
-    return e.key === 'Escape' || e.key === 'Esc' || e.keyCode === 27;
-  }
+        if (onActivate) {
+          onActivate();
+        }
 
-  function isTabEvent(e) {
-    return e.key === 'Tab' || e.keyCode === 9;
-  }
+        addListeners();
+        return this;
+      },
+      deactivate: function deactivate(deactivateOptions) {
+        if (!state.active) {
+          return this;
+        }
 
-  function delay(fn) {
-    return setTimeout(fn, 0);
-  }
+        clearTimeout(activeFocusDelay);
+        removeListeners();
+        state.active = false;
+        state.paused = false;
+        activeFocusTraps.deactivateTrap(trap);
+        var onDeactivate = deactivateOptions && deactivateOptions.onDeactivate !== undefined ? deactivateOptions.onDeactivate : config.onDeactivate;
+
+        if (onDeactivate) {
+          onDeactivate();
+        }
+
+        var returnFocus = deactivateOptions && deactivateOptions.returnFocus !== undefined ? deactivateOptions.returnFocus : config.returnFocusOnDeactivate;
+
+        if (returnFocus) {
+          delay(function () {
+            tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
+          });
+        }
+
+        return this;
+      },
+      pause: function pause() {
+        if (state.paused || !state.active) {
+          return this;
+        }
+
+        state.paused = true;
+        removeListeners();
+        return this;
+      },
+      unpause: function unpause() {
+        if (!state.paused || !state.active) {
+          return this;
+        }
+
+        state.paused = false;
+        updateTabbableNodes();
+        addListeners();
+        return this;
+      },
+      updateContainerElements: function updateContainerElements(containerElements) {
+        var elementsAsArray = [].concat(containerElements).filter(Boolean);
+        state.containers = elementsAsArray.map(function (element) {
+          return typeof element === 'string' ? doc.querySelector(element) : element;
+        });
+
+        if (state.active) {
+          updateTabbableNodes();
+        }
+
+        return this;
+      }
+    }; // initialize container elements
+
+    trap.updateContainerElements(elements);
+    return trap;
+  };
 
   exports.createFocusTrap = createFocusTrap;