focus-trap-react 8.9.2 → 8.11.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 8.11.1
+
+### Patch Changes
+
+- 040813a: Bumps focus-trap to v6.9.1 to pick-up a fix to tabbable in v5.3.2 regarding the `displayCheck=full` (default) option behavior that caused issues with detached nodes.
+
+## 8.11.0
+
+### Minor Changes
+
+- 7495680: Bump focus-trap to v6.9.0 to get bug fixes and new features to help fix some bugs.
+
+### Patch Changes
+
+- 7495680: Fix onDeactivate, onPostDeactivate, and checkCanReturnFocus options not being called consistently on deactivation.
+- 7495680: Fix focus not being allowed to remain on outside node post-deactivation when `clickOutsideDeactivates` is true or returns true.
+
+## 8.10.0
+
+### Minor Changes
+
+- 659d44e: Bumps focus-trap to v6.8.1. The big new feature is opt-in Shadow DOM support in focus-trap (in tabbable), and new tabbable options exposed in a new `focusTrapOptions.tabbableOptions` configuration option.
+  - ⚠️ This will likely break your tests **if you're using JSDom** (e.g. with Jest). See [testing in JSDom](./README.md#testing-in-jsdom) for more info.
+
 ## 8.9.2
 
 ### Patch Changes

package/README.md

@@ -68,7 +68,8 @@ Here's one more simple example:
 
 ```js
 const React = require('react');
-const ReactDOM = require('react-dom');
+const ReactDOM = require('react-dom'); // React 16-17
+const { createRoot } = require('react-dom/client'); // React 18
 const FocusTrap = require('focus-trap-react');
 
 class Demo extends React.Component {
@@ -132,7 +133,8 @@ class Demo extends React.Component {
   }
 }
 
-ReactDOM.render(<Demo />, document.getElementById('root'));
+ReactDOM.render(<Demo />, document.getElementById('root')); // React 16-17
+createRoot(document.getElementById('root')).render(<Demo />); // React 18
 ```
 
 ### Props
@@ -141,7 +143,9 @@ ReactDOM.render(<Demo />, document.getElementById('root'));
 
 Type: `Object`, optional
 
-Pass any of the options available in [`focus-trap`'s `createOptions`](https://github.com/focus-trap/focus-trap#focustrap--createfocustrapelement-createoptions).
+Pass any of the options available in focus-trap's [createOptions](https://github.com/focus-trap/focus-trap#createoptions).
+
+> ⚠️ See notes about __[testing in JSDom](#testing-in-jsdom)__ (e.g. using Jest) if that's what you currently use.
 
 #### active
 
@@ -169,6 +173,20 @@ If `containerElements` is subsequently updated (i.e. after the trap has been cre
 
 Using `containerElements` does require the use of React refs which, by nature, will require at least one state update in order to get the resolved elements into the prop, resulting in at least one additional render. In the normal case, this is likely more than acceptable, but if you really want to optimize things, then you could consider [using focus-trap directly](https://codesandbox.io/s/focus-trapreact-containerelements-demos-v5ydi) (see `Trap2.js`).
 
+## Help
+
+### Testing in JSDom
+
+> ⚠️ JSDom is not officially supported. Your mileage may vary, and tests may break from one release to the next (even a patch or minor release).
+>
+> This topic is just here to help with what we know may affect your tests.
+
+In general, a focus trap is best tested in a full browser environment such as Cypress, Playwright, or Nightwatch where a full DOM is available.
+
+Sometimes, that's not entirely desirable, and depending on what you're testing, you may be able to get away with using JSDom (e.g. via Jest), but you'll have to configure your traps using the `focusTrapOptions.tabbableOptions.displayCheck: 'none'` option.
+
+See [Testing focus-trap in JSDom](https://github.com/focus-trap/focus-trap#testing-in-jsdom) for more details.
+
 ## Contributing
 
 See [CONTRIBUTING](CONTRIBUTING.md).

package/dist/focus-trap-react.js

@@ -29,7 +29,10 @@ var ReactDOM = require('react-dom');
 var PropTypes = require('prop-types');
 
 var _require = require('focus-trap'),
-    createFocusTrap = _require.createFocusTrap; // TODO: These issues are related to older React features which we'll likely need
+    createFocusTrap = _require.createFocusTrap;
+
+var _require2 = require('tabbable'),
+    isFocusable = _require2.isFocusable; // TODO: These issues are related to older React features which we'll likely need
 //  to fix in order to move the code forward to the next major version of React.
 //  @see https://github.com/davidtheclark/focus-trap-react/issues/77
 
@@ -46,18 +49,43 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
 
     _classCallCheck(this, FocusTrap);
 
-    _this = _super.call(this, props); // We need to hijack the returnFocusOnDeactivate option,
-    // because React can move focus into the element before we arrived at
-    // this lifecycle hook (e.g. with autoFocus inputs). So the component
-    // captures the previouslyFocusedElement in componentWillMount,
-    // then (optionally) returns focus to it in componentWillUnmount.
-
-    _this.tailoredFocusTrapOptions = {
-      returnFocusOnDeactivate: false
-    }; // because of the above, we maintain our own flag for this option, and
-    //  default it to `true` because that's focus-trap's default
-
-    _this.returnFocusOnDeactivate = true;
+    _this = _super.call(this, props);
+    _this.handleDeactivate = _this.handleDeactivate.bind(_assertThisInitialized(_this));
+    _this.handlePostDeactivate = _this.handlePostDeactivate.bind(_assertThisInitialized(_this));
+    _this.handleClickOutsideDeactivates = _this.handleClickOutsideDeactivates.bind(_assertThisInitialized(_this)); // focus-trap options used internally when creating the trap
+
+    _this.internalOptions = {
+      // We need to hijack the returnFocusOnDeactivate option,
+      // because React can move focus into the element before we arrived at
+      // this lifecycle hook (e.g. with autoFocus inputs). So the component
+      // captures the previouslyFocusedElement in componentWillMount,
+      // then (optionally) returns focus to it in componentWillUnmount.
+      returnFocusOnDeactivate: false,
+      // the rest of these are also related to deactivation of the trap, and we
+      //  need to use them and control them as well
+      checkCanReturnFocus: null,
+      onDeactivate: _this.handleDeactivate,
+      onPostDeactivate: _this.handlePostDeactivate,
+      // we need to special-case this setting as well so that we can know if we should
+      //  NOT return focus if the trap gets auto-deactivated as the result of an
+      //  outside click (otherwise, we'll always think we should return focus because
+      //  of how we manage that flag internally here)
+      clickOutsideDeactivates: _this.handleClickOutsideDeactivates
+    }; // original options provided by the consumer
+
+    _this.originalOptions = {
+      // because of the above `tailoredFocusTrapOptions`, we maintain our own flag for
+      //  this option, and default it to `true` because that's focus-trap's default
+      returnFocusOnDeactivate: true,
+      // because of the above `tailoredFocusTrapOptions`, we keep these separate since
+      //  they're part of the deactivation process which we configure (internally) to
+      //  be shared between focus-trap and focus-trap-react
+      onDeactivate: null,
+      onPostDeactivate: null,
+      checkCanReturnFocus: null,
+      // the user's setting, defaulted to false since focus-trap defaults this to false
+      clickOutsideDeactivates: false
+    };
     var focusTrapOptions = props.focusTrapOptions;
 
     for (var optionName in focusTrapOptions) {
@@ -65,22 +93,22 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
         continue;
       }
 
-      if (optionName === 'returnFocusOnDeactivate') {
-        _this.returnFocusOnDeactivate = !!focusTrapOptions[optionName];
-        continue;
+      if (optionName === 'returnFocusOnDeactivate' || optionName === 'onDeactivate' || optionName === 'onPostDeactivate' || optionName === 'checkCanReturnFocus' || optionName === 'clickOutsideDeactivates') {
+        _this.originalOptions[optionName] = focusTrapOptions[optionName];
+        continue; // exclude from tailoredFocusTrapOptions
       }
 
-      if (optionName === 'onPostDeactivate') {
-        _this.onPostDeactivate = focusTrapOptions[optionName];
-        continue;
-      }
+      _this.internalOptions[optionName] = focusTrapOptions[optionName];
+    } // if set, `{ target: Node, allowDeactivation: boolean }` where `target` is the outside
+    //  node that was clicked, and `allowDeactivation` is the result of the consumer's
+    //  option (stored in `this.originalOptions.clickOutsideDeactivates`, which may be a
+    //  function) whether to allow or deny auto-deactivation on click on this outside node
+
 
-      _this.tailoredFocusTrapOptions[optionName] = focusTrapOptions[optionName];
-    } // elements from which to create the focus trap on mount; if a child is used
+    _this.outsideClick = null; // elements from which to create the focus trap on mount; if a child is used
     //  instead of the `containerElements` prop, we'll get the child's related
     //  element when the trap renders and then is declared 'mounted'
 
-
     _this.focusTrapElements = props.containerElements || []; // now we remember what the currently focused element is, not relying on focus-trap
 
     _this.updatePreviousElement();
@@ -105,7 +133,7 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
   }, {
     key: "getNodeForOption",
     value: function getNodeForOption(optionName) {
-      var optionValue = this.tailoredFocusTrapOptions[optionName];
+      var optionValue = this.internalOptions[optionName];
 
       if (!optionValue) {
         return null;
@@ -153,40 +181,97 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
   }, {
     key: "deactivateTrap",
     value: function deactivateTrap() {
-      var _this2 = this;
-
-      var _this$tailoredFocusTr = this.tailoredFocusTrapOptions,
-          checkCanReturnFocus = _this$tailoredFocusTr.checkCanReturnFocus,
-          _this$tailoredFocusTr2 = _this$tailoredFocusTr.preventScroll,
-          preventScroll = _this$tailoredFocusTr2 === void 0 ? false : _this$tailoredFocusTr2;
+      // NOTE: it's possible the focus trap has already been deactivated without our knowing it,
+      //  especially if the user set the `clickOutsideDeactivates: true` option on the trap,
+      //  and the mouse was clicked on some element outside the trap; at that point, focus-trap
+      //  will initiate its auto-deactivation process, which will call our own
+      //  handleDeactivate(), which will call into this method
+      if (!this.focusTrap || !this.focusTrap.active) {
+        return;
+      }
 
-      if (this.focusTrap) {
+      this.focusTrap.deactivate({
         // NOTE: we never let the trap return the focus since we do that ourselves
-        this.focusTrap.deactivate({
-          returnFocus: false
-        });
+        returnFocus: false,
+        // we'll call this in our own post deactivate handler so make sure the trap doesn't
+        //  do it prematurely
+        checkCanReturnFocus: null,
+        // let it call the user's original deactivate handler, if any, instead of
+        //  our own which calls back into this function
+        onDeactivate: this.originalOptions.onDeactivate // NOTE: for post deactivate, don't specify anything so that it calls the
+        //  onPostDeactivate handler specified on `this.internalOptions`
+        //  which will always be our own `handlePostDeactivate()` handler, which
+        //  will finish things off by calling the user's provided onPostDeactivate
+        //  handler, if any, at the right time
+        // onPostDeactivate: NOTHING
+
+      });
+    }
+  }, {
+    key: "handleClickOutsideDeactivates",
+    value: function handleClickOutsideDeactivates(event) {
+      // use consumer's option (or call their handler) as the permission or denial
+      var allowDeactivation = typeof this.originalOptions.clickOutsideDeactivates === 'function' ? this.originalOptions.clickOutsideDeactivates.call(null, event) // call out of context
+      : this.originalOptions.clickOutsideDeactivates; // boolean
+
+      if (allowDeactivation) {
+        // capture the outside target that was clicked so we can use it in the deactivation
+        //  process since the consumer allowed it to cause auto-deactivation
+        this.outsideClick = {
+          target: event.target,
+          allowDeactivation: allowDeactivation
+        };
+      }
+
+      return allowDeactivation;
+    }
+  }, {
+    key: "handleDeactivate",
+    value: function handleDeactivate() {
+      if (this.originalOptions.onDeactivate) {
+        this.originalOptions.onDeactivate.call(null); // call user's handler out of context
       }
 
+      this.deactivateTrap();
+    }
+  }, {
+    key: "handlePostDeactivate",
+    value: function handlePostDeactivate() {
+      var _this2 = this;
+
       var finishDeactivation = function finishDeactivation() {
         var returnFocusNode = _this2.getReturnFocusNode();
 
-        var canReturnFocus = (returnFocusNode === null || returnFocusNode === void 0 ? void 0 : returnFocusNode.focus) && _this2.returnFocusOnDeactivate;
+        var canReturnFocus = !!( // did the consumer allow it?
+        _this2.originalOptions.returnFocusOnDeactivate && // can we actually focus the node?
+        returnFocusNode !== null && returnFocusNode !== void 0 && returnFocusNode.focus && ( // was there an outside click that allowed deactivation?
+        !_this2.outsideClick || // did the consumer allow deactivation when the outside node was clicked?
+        _this2.outsideClick.allowDeactivation && // is the outside node NOT focusable (implying that it did NOT receive focus
+        //  as a result of the click-through) -- in which case do NOT restore focus
+        //  to `returnFocusNode` because focus should remain on the outside node
+        !isFocusable(_this2.outsideClick.target, _this2.internalOptions.tabbableOptions)) // if no, the restore focus to `returnFocusNode` at this point
+        );
+        var _this2$internalOption = _this2.internalOptions.preventScroll,
+            preventScroll = _this2$internalOption === void 0 ? false : _this2$internalOption;
 
         if (canReturnFocus) {
-          /** Returns focus to the element that had focus when the trap was activated. */
+          // return focus to the element that had focus when the trap was activated
           returnFocusNode.focus({
             preventScroll: preventScroll
           });
         }
 
-        if (_this2.onPostDeactivate) {
-          _this2.onPostDeactivate.call(null); // don't call it in context of "this"
+        if (_this2.originalOptions.onPostDeactivate) {
+          _this2.originalOptions.onPostDeactivate.call(null); // don't call it in context of "this"
 
         }
+
+        _this2.outsideClick = null; // reset: no longer needed
       };
 
-      if (checkCanReturnFocus) {
-        checkCanReturnFocus(this.getReturnFocusNode()).then(finishDeactivation, finishDeactivation);
+      if (this.originalOptions.checkCanReturnFocus) {
+        this.originalOptions.checkCanReturnFocus.call(null, this.getReturnFocusNode()) // call out of context
+        .then(finishDeactivation, finishDeactivation);
       } else {
         finishDeactivation();
       }
@@ -203,7 +288,7 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
 
         if (nodesExist) {
           // eslint-disable-next-line react/prop-types -- _createFocusTrap is an internal prop
-          this.focusTrap = this.props._createFocusTrap(focusTrapElementDOMNodes, this.tailoredFocusTrapOptions);
+          this.focusTrap = this.props._createFocusTrap(focusTrapElementDOMNodes, this.internalOptions);
 
           if (this.props.active) {
             this.focusTrap.activate();
@@ -339,7 +424,11 @@ FocusTrap.propTypes = {
     returnFocusOnDeactivate: PropTypes.bool,
     setReturnFocus: PropTypes.oneOfType([PropTypes.instanceOf(ElementType), PropTypes.string, PropTypes.func]),
     allowOutsideClick: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
-    preventScroll: PropTypes.bool
+    preventScroll: PropTypes.bool,
+    tabbableOptions: PropTypes.shape({
+      displayCheck: PropTypes.oneOf(['full', 'non-zero-area', 'none']),
+      getShadowRoot: PropTypes.oneOfType([PropTypes.bool, PropTypes.func])
+    })
   }),
   containerElements: PropTypes.arrayOf(PropTypes.instanceOf(ElementType)),
   children: PropTypes.oneOfType([PropTypes.element, // React element

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focus-trap-react",
-  "version": "8.9.2",
+  "version": "8.11.1",
   "description": "A React component that traps focus.",
   "main": "dist/focus-trap-react.js",
   "types": "index.d.ts",
@@ -26,8 +26,10 @@
     "test:coverage": "jest --coverage",
     "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: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",
+    "prepublishOnly": "yarn test && yarn build",
     "release": "yarn build && changeset publish"
   },
   "repository": {
@@ -55,43 +57,45 @@
   },
   "homepage": "https://github.com/focus-trap/focus-trap-react#readme",
   "devDependencies": {
-    "@babel/cli": "^7.17.0",
-    "@babel/core": "^7.17.2",
+    "@babel/cli": "^7.17.10",
+    "@babel/core": "^7.17.10",
     "@babel/eslint-parser": "^7.17.0",
     "@babel/plugin-proposal-class-properties": "^7.16.5",
-    "@babel/preset-env": "^7.16.11",
+    "@babel/preset-env": "^7.17.10",
     "@babel/preset-react": "^7.16.7",
-    "@changesets/cli": "^2.20.0",
+    "@changesets/cli": "^2.22.0",
     "@testing-library/cypress": "^8.0.2",
-    "@testing-library/dom": "^8.11.3",
-    "@testing-library/jest-dom": "^5.16.2",
-    "@testing-library/react": "^12.1.2",
-    "@testing-library/user-event": "^13.5.0",
-    "@types/jquery": "^3.5.13",
+    "@testing-library/dom": "^8.13.0",
+    "@testing-library/jest-dom": "^5.16.4",
+    "@testing-library/react": "^13.2.0",
+    "@testing-library/user-event": "^14.1.1",
+    "@types/jquery": "^3.5.14",
     "all-contributors-cli": "^6.20.0",
-    "babel-jest": "^27.5.1",
+    "babel-jest": "^28.0.3",
     "babelify": "^10.0.0",
     "browserify": "^17.0.0",
-    "budo": "^11.6.4",
-    "cypress": "^9.4.1",
+    "budo": "^11.7.0",
+    "cypress": "^9.6.0",
     "cypress-plugin-tab": "^1.0.5",
-    "eslint": "^8.8.0",
-    "eslint-config-prettier": "^8.3.0",
+    "eslint": "^8.14.0",
+    "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-cypress": "^2.12.1",
-    "eslint-plugin-react": "^7.28.0",
-    "jest": "^27.5.1",
-    "jest-watch-typeahead": "^1.0.0",
+    "eslint-plugin-jest": "^26.1.5",
+    "eslint-plugin-react": "^7.29.4",
+    "jest": "^28.0.3",
+    "jest-environment-jsdom": "^28.0.2",
+    "jest-watch-typeahead": "^1.1.0",
     "onchange": "^7.1.0",
-    "prettier": "^2.5.1",
+    "prettier": "^2.6.2",
     "prop-types": "^15.8.1",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2",
+    "react": "^18.1.0",
+    "react-dom": "^18.1.0",
     "regenerator-runtime": "^0.13.9",
     "start-server-and-test": "^1.14.0",
-    "typescript": "^4.5.5"
+    "typescript": "^4.6.4"
   },
   "dependencies": {
-    "focus-trap": "^6.7.3"
+    "focus-trap": "^6.9.1"
   },
   "peerDependencies": {
     "prop-types": "^15.8.1",

package/src/focus-trap-react.js

@@ -2,6 +2,7 @@ const React = require('react');
 const ReactDOM = require('react-dom');
 const PropTypes = require('prop-types');
 const { createFocusTrap } = require('focus-trap');
+const { isFocusable } = require('tabbable');
 
 // TODO: These issues are related to older React features which we'll likely need
 //  to fix in order to move the code forward to the next major version of React.
@@ -12,18 +13,49 @@ class FocusTrap extends React.Component {
   constructor(props) {
     super(props);
 
-    // We need to hijack the returnFocusOnDeactivate option,
-    // because React can move focus into the element before we arrived at
-    // this lifecycle hook (e.g. with autoFocus inputs). So the component
-    // captures the previouslyFocusedElement in componentWillMount,
-    // then (optionally) returns focus to it in componentWillUnmount.
-    this.tailoredFocusTrapOptions = {
+    this.handleDeactivate = this.handleDeactivate.bind(this);
+    this.handlePostDeactivate = this.handlePostDeactivate.bind(this);
+    this.handleClickOutsideDeactivates =
+      this.handleClickOutsideDeactivates.bind(this);
+
+    // focus-trap options used internally when creating the trap
+    this.internalOptions = {
+      // We need to hijack the returnFocusOnDeactivate option,
+      // because React can move focus into the element before we arrived at
+      // this lifecycle hook (e.g. with autoFocus inputs). So the component
+      // captures the previouslyFocusedElement in componentWillMount,
+      // then (optionally) returns focus to it in componentWillUnmount.
       returnFocusOnDeactivate: false,
+
+      // the rest of these are also related to deactivation of the trap, and we
+      //  need to use them and control them as well
+      checkCanReturnFocus: null,
+      onDeactivate: this.handleDeactivate,
+      onPostDeactivate: this.handlePostDeactivate,
+
+      // we need to special-case this setting as well so that we can know if we should
+      //  NOT return focus if the trap gets auto-deactivated as the result of an
+      //  outside click (otherwise, we'll always think we should return focus because
+      //  of how we manage that flag internally here)
+      clickOutsideDeactivates: this.handleClickOutsideDeactivates,
     };
 
-    // because of the above, we maintain our own flag for this option, and
-    //  default it to `true` because that's focus-trap's default
-    this.returnFocusOnDeactivate = true;
+    // original options provided by the consumer
+    this.originalOptions = {
+      // because of the above `tailoredFocusTrapOptions`, we maintain our own flag for
+      //  this option, and default it to `true` because that's focus-trap's default
+      returnFocusOnDeactivate: true,
+
+      // because of the above `tailoredFocusTrapOptions`, we keep these separate since
+      //  they're part of the deactivation process which we configure (internally) to
+      //  be shared between focus-trap and focus-trap-react
+      onDeactivate: null,
+      onPostDeactivate: null,
+      checkCanReturnFocus: null,
+
+      // the user's setting, defaulted to false since focus-trap defaults this to false
+      clickOutsideDeactivates: false,
+    };
 
     const { focusTrapOptions } = props;
     for (const optionName in focusTrapOptions) {
@@ -31,19 +63,26 @@ class FocusTrap extends React.Component {
         continue;
       }
 
-      if (optionName === 'returnFocusOnDeactivate') {
-        this.returnFocusOnDeactivate = !!focusTrapOptions[optionName];
-        continue;
-      }
-
-      if (optionName === 'onPostDeactivate') {
-        this.onPostDeactivate = focusTrapOptions[optionName];
-        continue;
+      if (
+        optionName === 'returnFocusOnDeactivate' ||
+        optionName === 'onDeactivate' ||
+        optionName === 'onPostDeactivate' ||
+        optionName === 'checkCanReturnFocus' ||
+        optionName === 'clickOutsideDeactivates'
+      ) {
+        this.originalOptions[optionName] = focusTrapOptions[optionName];
+        continue; // exclude from tailoredFocusTrapOptions
       }
 
-      this.tailoredFocusTrapOptions[optionName] = focusTrapOptions[optionName];
+      this.internalOptions[optionName] = focusTrapOptions[optionName];
     }
 
+    // if set, `{ target: Node, allowDeactivation: boolean }` where `target` is the outside
+    //  node that was clicked, and `allowDeactivation` is the result of the consumer's
+    //  option (stored in `this.originalOptions.clickOutsideDeactivates`, which may be a
+    //  function) whether to allow or deny auto-deactivation on click on this outside node
+    this.outsideClick = null;
+
     // elements from which to create the focus trap on mount; if a child is used
     //  instead of the `containerElements` prop, we'll get the child's related
     //  element when the trap renders and then is declared 'mounted'
@@ -69,7 +108,7 @@ class FocusTrap extends React.Component {
 
   // TODO: Need more test coverage for this function
   getNodeForOption(optionName) {
-    const optionValue = this.tailoredFocusTrapOptions[optionName];
+    const optionValue = this.internalOptions[optionName];
     if (!optionValue) {
       return null;
     }
@@ -108,36 +147,102 @@ class FocusTrap extends React.Component {
   }
 
   deactivateTrap() {
-    const { checkCanReturnFocus, preventScroll = false } =
-      this.tailoredFocusTrapOptions;
+    // NOTE: it's possible the focus trap has already been deactivated without our knowing it,
+    //  especially if the user set the `clickOutsideDeactivates: true` option on the trap,
+    //  and the mouse was clicked on some element outside the trap; at that point, focus-trap
+    //  will initiate its auto-deactivation process, which will call our own
+    //  handleDeactivate(), which will call into this method
+    if (!this.focusTrap || !this.focusTrap.active) {
+      return;
+    }
 
-    if (this.focusTrap) {
+    this.focusTrap.deactivate({
       // NOTE: we never let the trap return the focus since we do that ourselves
-      this.focusTrap.deactivate({ returnFocus: false });
+      returnFocus: false,
+      // we'll call this in our own post deactivate handler so make sure the trap doesn't
+      //  do it prematurely
+      checkCanReturnFocus: null,
+      // let it call the user's original deactivate handler, if any, instead of
+      //  our own which calls back into this function
+      onDeactivate: this.originalOptions.onDeactivate,
+      // NOTE: for post deactivate, don't specify anything so that it calls the
+      //  onPostDeactivate handler specified on `this.internalOptions`
+      //  which will always be our own `handlePostDeactivate()` handler, which
+      //  will finish things off by calling the user's provided onPostDeactivate
+      //  handler, if any, at the right time
+      // onPostDeactivate: NOTHING
+    });
+  }
+
+  handleClickOutsideDeactivates(event) {
+    // use consumer's option (or call their handler) as the permission or denial
+    const allowDeactivation =
+      typeof this.originalOptions.clickOutsideDeactivates === 'function'
+        ? this.originalOptions.clickOutsideDeactivates.call(null, event) // call out of context
+        : this.originalOptions.clickOutsideDeactivates; // boolean
+
+    if (allowDeactivation) {
+      // capture the outside target that was clicked so we can use it in the deactivation
+      //  process since the consumer allowed it to cause auto-deactivation
+      this.outsideClick = {
+        target: event.target,
+        allowDeactivation,
+      };
+    }
+
+    return allowDeactivation;
+  }
+
+  handleDeactivate() {
+    if (this.originalOptions.onDeactivate) {
+      this.originalOptions.onDeactivate.call(null); // call user's handler out of context
     }
+    this.deactivateTrap();
+  }
 
+  handlePostDeactivate() {
     const finishDeactivation = () => {
       const returnFocusNode = this.getReturnFocusNode();
-      const canReturnFocus =
-        returnFocusNode?.focus && this.returnFocusOnDeactivate;
+      const canReturnFocus = !!(
+        // did the consumer allow it?
+        (
+          this.originalOptions.returnFocusOnDeactivate &&
+          // can we actually focus the node?
+          returnFocusNode?.focus &&
+          // was there an outside click that allowed deactivation?
+          (!this.outsideClick ||
+            // did the consumer allow deactivation when the outside node was clicked?
+            (this.outsideClick.allowDeactivation &&
+              // is the outside node NOT focusable (implying that it did NOT receive focus
+              //  as a result of the click-through) -- in which case do NOT restore focus
+              //  to `returnFocusNode` because focus should remain on the outside node
+              !isFocusable(
+                this.outsideClick.target,
+                this.internalOptions.tabbableOptions
+              )))
+        )
+        // if no, the restore focus to `returnFocusNode` at this point
+      );
+      const { preventScroll = false } = this.internalOptions;
 
       if (canReturnFocus) {
-        /** Returns focus to the element that had focus when the trap was activated. */
+        // return focus to the element that had focus when the trap was activated
         returnFocusNode.focus({
           preventScroll,
         });
       }
 
-      if (this.onPostDeactivate) {
-        this.onPostDeactivate.call(null); // don't call it in context of "this"
+      if (this.originalOptions.onPostDeactivate) {
+        this.originalOptions.onPostDeactivate.call(null); // don't call it in context of "this"
       }
+
+      this.outsideClick = null; // reset: no longer needed
     };
 
-    if (checkCanReturnFocus) {
-      checkCanReturnFocus(this.getReturnFocusNode()).then(
-        finishDeactivation,
-        finishDeactivation
-      );
+    if (this.originalOptions.checkCanReturnFocus) {
+      this.originalOptions.checkCanReturnFocus
+        .call(null, this.getReturnFocusNode()) // call out of context
+        .then(finishDeactivation, finishDeactivation);
     } else {
       finishDeactivation();
     }
@@ -157,7 +262,7 @@ class FocusTrap extends React.Component {
         // eslint-disable-next-line react/prop-types -- _createFocusTrap is an internal prop
         this.focusTrap = this.props._createFocusTrap(
           focusTrapElementDOMNodes,
-          this.tailoredFocusTrapOptions
+          this.internalOptions
         );
 
         if (this.props.active) {
@@ -311,6 +416,10 @@ FocusTrap.propTypes = {
     ]),
     allowOutsideClick: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
     preventScroll: PropTypes.bool,
+    tabbableOptions: PropTypes.shape({
+      displayCheck: PropTypes.oneOf(['full', 'non-zero-area', 'none']),
+      getShadowRoot: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
+    }),
   }),
   containerElements: PropTypes.arrayOf(PropTypes.instanceOf(ElementType)),
   children: PropTypes.oneOfType([