focus-trap-react 8.4.2 → 8.7.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 8.7.0
+
+### Minor Changes
+
+- 7fbe8ca: Update to support new features in `focus-trap@6.6.0` including `initialFocus` which can now be false to prevent initial focus, and `escapeDeactivates` which can now alternately be a function that returns a boolean instead of a straight boolean.
+
+## 8.6.0
+
+### Minor Changes
+
+- 5292ae8:
+  - Adding support for new focus-trap options from focus-trap v6.5.0: `checkCanFocusTrap()`, `onPostActivate()`, `checkCanReturnFocus()`, and `onPostDeactivate()`.
+  - Adding support (bug fix) for existing focus-trap `setReturnFocus` option that had thus far been ignored, with focus-trap-react always returning focus to the previously-focused element prior to activation regardless of the use of the `setReturnFocus` option. The option is now respected the same as it is when using focus-trap directly.
+
+### Patch Changes
+
+- 24704c7: Bump focus-trap dependency to 6.5.1 for bug fix to onPostDeactivate.
+
+## 8.5.1
+
+### Patch Changes
+
+- b8d7071: Bump focus-trap dependency to 6.5.0 to get new features
+
+## 8.5.0
+
+### Minor Changes
+
+- 6ee37fb: Bump focus-trap from 6.3.0 to 6.4.0. There should be no changes in behavior as a result of this upgrade.
+
 ## 8.4.2
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,7 @@
 # focus-trap-react [![CI](https://github.com/focus-trap/focus-trap-react/workflows/CI/badge.svg?branch=master&event=push)](https://github.com/focus-trap/focus-trap-react/actions?query=workflow:CI+branch:master) [![Codecov](https://img.shields.io/codecov/c/github/focus-trap/focus-trap-react)](https://codecov.io/gh/focus-trap/focus-trap-react) [![license](https://badgen.now.sh/badge/license/MIT)](./LICENSE)
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-17-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-18-orange.svg?style=flat-square)](#contributors)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 A React component that traps focus.
@@ -186,20 +186,21 @@ In alphabetical order:
     <td align="center"><a href="https://ofcr.se/"><img src="https://avatars1.githubusercontent.com/u/813865?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Benjamin Tan</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=bnjmnt4n" title="Documentation">📖</a></td>
     <td align="center"><a href="https://clintgoodman.com"><img src="https://avatars3.githubusercontent.com/u/5473697?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Clint Goodman</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=cgood92" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=cgood92" title="Documentation">📖</a> <a href="#example-cgood92" title="Examples">💡</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=cgood92" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://github.com/DSil"><img src="https://avatars1.githubusercontent.com/u/6265045?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Daniel</b></sub></a><br /><a href="#maintenance-DSil" title="Maintenance">🚧</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=DSil" title="Tests">⚠️</a></td>
+    <td align="center"><a href="https://github.com/Dan503"><img src="https://avatars.githubusercontent.com/u/10610368?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Daniel Tonon</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=Dan503" title="Documentation">📖</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=Dan503" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=Dan503" title="Tests">⚠️</a></td>
     <td align="center"><a href="http://davidtheclark.com/"><img src="https://avatars2.githubusercontent.com/u/628431?v=4?s=100" width="100px;" alt=""/><br /><sub><b>David Clark</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=davidtheclark" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap-react/issues?q=author%3Adavidtheclark" title="Bug reports">🐛</a> <a href="#infra-davidtheclark" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=davidtheclark" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=davidtheclark" title="Documentation">📖</a> <a href="#maintenance-davidtheclark" title="Maintenance">🚧</a></td>
     <td align="center"><a href="https://github.com/features/security"><img src="https://avatars1.githubusercontent.com/u/27347476?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Dependabot</b></sub></a><br /><a href="#maintenance-dependabot" title="Maintenance">🚧</a></td>
-    <td align="center"><a href="http://josuzuki.me"><img src="https://avatars1.githubusercontent.com/u/9583920?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jonathan Suzuki</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/issues?q=author%3AJoSuzuki" title="Bug reports">🐛</a></td>
   </tr>
   <tr>
+    <td align="center"><a href="http://josuzuki.me"><img src="https://avatars1.githubusercontent.com/u/9583920?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jonathan Suzuki</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/issues?q=author%3AJoSuzuki" title="Bug reports">🐛</a></td>
     <td align="center"><a href="http://kathleenmcmahon.dev/"><img src="https://avatars1.githubusercontent.com/u/11621935?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Kathleen McMahon</b></sub></a><br /><a href="#maintenance-resource11" title="Maintenance">🚧</a></td>
     <td align="center"><a href="https://marais.io/"><img src="https://avatars2.githubusercontent.com/u/599459?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Marais Rossouw</b></sub></a><br /><a href="#infra-maraisr" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
     <td align="center"><a href="https://github.com/liunate"><img src="https://avatars2.githubusercontent.com/u/38996291?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nate Liu</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=liunate" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://www.linkedin.com/in/rivajunior/"><img src="https://avatars1.githubusercontent.com/u/11370172?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rivaldo Junior</b></sub></a><br /><a href="#maintenance-rivajunior" title="Maintenance">🚧</a></td>
     <td align="center"><a href="https://scottrippey.github.io/"><img src="https://avatars3.githubusercontent.com/u/430608?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Scott Rippey</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=scottrippey" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap-react/issues?q=author%3Ascottrippey" title="Bug reports">🐛</a></td>
     <td align="center"><a href="https://seanmcp.com/"><img src="https://avatars1.githubusercontent.com/u/6360367?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sean McPherson</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=SeanMcP" title="Code">💻</a></td>
-    <td align="center"><a href="https://recollectr.io"><img src="https://avatars2.githubusercontent.com/u/6835891?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Slapbox</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=Slapbox" title="Documentation">📖</a></td>
   </tr>
   <tr>
+    <td align="center"><a href="https://recollectr.io"><img src="https://avatars2.githubusercontent.com/u/6835891?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Slapbox</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=Slapbox" title="Documentation">📖</a></td>
     <td align="center"><a href="https://stefancameron.com/"><img src="https://avatars3.githubusercontent.com/u/2855350?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Stefan Cameron</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=stefcameron" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap-react/issues?q=author%3Astefcameron" title="Bug reports">🐛</a> <a href="#infra-stefcameron" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=stefcameron" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=stefcameron" title="Documentation">📖</a> <a href="#maintenance-stefcameron" title="Maintenance">🚧</a></td>
     <td align="center"><a href="http://tylerhawkins.info/201R/"><img src="https://avatars0.githubusercontent.com/u/13806458?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tyler Hawkins</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/commits?author=thawkin3" title="Documentation">📖</a> <a href="#example-thawkin3" title="Examples">💡</a> <a href="https://github.com/focus-trap/focus-trap-react/commits?author=thawkin3" title="Tests">⚠️</a> <a href="#tool-thawkin3" title="Tools">🔧</a></td>
     <td align="center"><a href="https://github.com/krikienoid"><img src="https://avatars3.githubusercontent.com/u/8528227?v=4?s=100" width="100px;" alt=""/><br /><sub><b>krikienoid</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap-react/issues?q=author%3Akrikienoid" title="Bug reports">🐛</a></td>

package/dist/focus-trap-react.js

@@ -18,7 +18,7 @@ function _possibleConstructorReturn(self, call) { if (call && (_typeof(call) ===
 
 function _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return self; }
 
-function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === "function") return true; try { Date.prototype.toString.call(Reflect.construct(Date, [], function () {})); return true; } catch (e) { return false; } }
+function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === "function") return true; try { Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); return true; } catch (e) { return false; } }
 
 function _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }
 
@@ -70,6 +70,11 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
         continue;
       }
 
+      if (optionName === 'onPostDeactivate') {
+        _this.onPostDeactivate = focusTrapOptions[optionName];
+        continue;
+      }
+
       _this.tailoredFocusTrapOptions[optionName] = focusTrapOptions[optionName];
     } // 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
@@ -81,24 +86,87 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
     _this.updatePreviousElement();
 
     return _this;
-  }
-  /** Update the previously focused element with the currently focused element. */
+  } // TODO: Need more test coverage for this function
 
 
   _createClass(FocusTrap, [{
+    key: "getNodeForOption",
+    value: function getNodeForOption(optionName) {
+      var optionValue = this.tailoredFocusTrapOptions[optionName];
+
+      if (!optionValue) {
+        return null;
+      }
+
+      var node = optionValue;
+
+      if (typeof optionValue === 'string') {
+        node = document.querySelector(optionValue);
+
+        if (!node) {
+          throw new Error("`".concat(optionName, "` refers to no known node"));
+        }
+      }
+
+      if (typeof optionValue === 'function') {
+        node = optionValue();
+
+        if (!node) {
+          throw new Error("`".concat(optionName, "` did not return a node"));
+        }
+      }
+
+      return node;
+    }
+  }, {
+    key: "getReturnFocusNode",
+    value: function getReturnFocusNode() {
+      var node = this.getNodeForOption('setReturnFocus');
+      return node ? node : this.previouslyFocusedElement;
+    }
+    /** Update the previously focused element with the currently focused element. */
+
+  }, {
     key: "updatePreviousElement",
     value: function updatePreviousElement() {
       if (typeof document !== 'undefined') {
         this.previouslyFocusedElement = document.activeElement;
       }
     }
-    /** Returns focus to the element that had focus when the trap was activated. */
-
   }, {
-    key: "returnFocus",
-    value: function returnFocus() {
-      if (this.previouslyFocusedElement && this.previouslyFocusedElement.focus) {
-        this.previouslyFocusedElement.focus();
+    key: "deactivateTrap",
+    value: function deactivateTrap() {
+      var _this2 = this;
+
+      var checkCanReturnFocus = this.tailoredFocusTrapOptions.checkCanReturnFocus;
+
+      if (this.focusTrap) {
+        // NOTE: we never let the trap return the focus since we do that ourselves
+        this.focusTrap.deactivate({
+          returnFocus: false
+        });
+      }
+
+      var finishDeactivation = function finishDeactivation() {
+        var returnFocusNode = _this2.getReturnFocusNode();
+
+        var canReturnFocus = (returnFocusNode === null || returnFocusNode === void 0 ? void 0 : returnFocusNode.focus) && _this2.returnFocusOnDeactivate;
+
+        if (canReturnFocus) {
+          /** Returns focus to the element that had focus when the trap was activated. */
+          returnFocusNode.focus();
+        }
+
+        if (_this2.onPostDeactivate) {
+          _this2.onPostDeactivate.call(null); // don't call it in context of "this"
+
+        }
+      };
+
+      if (checkCanReturnFocus) {
+        checkCanReturnFocus(this.getReturnFocusNode()).then(finishDeactivation, finishDeactivation);
+      } else {
+        finishDeactivation();
       }
     }
   }, {
@@ -138,28 +206,27 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
           this.focusTrap.updateContainerElements(this.props.containerElements);
         }
 
-        if (prevProps.active && !this.props.active) {
-          // NOTE: we never let the trap return the focus since we do that ourselves
-          this.focusTrap.deactivate({
-            returnFocus: false
-          });
+        var hasActivated = !prevProps.active && this.props.active;
+        var hasDeactivated = prevProps.active && !this.props.active;
+        var hasPaused = !prevProps.paused && this.props.paused;
+        var hasUnpaused = prevProps.paused && !this.props.paused;
 
-          if (this.returnFocusOnDeactivate) {
-            this.returnFocus();
-          }
+        if (hasActivated) {
+          this.updatePreviousElement();
+          this.focusTrap.activate();
+        }
 
+        if (hasDeactivated) {
+          this.deactivateTrap();
           return; // un/pause does nothing on an inactive trap
         }
 
-        if (!prevProps.active && this.props.active) {
-          this.updatePreviousElement();
-          this.focusTrap.activate();
+        if (hasPaused) {
+          this.focusTrap.pause();
         }
 
-        if (prevProps.paused && !this.props.paused) {
+        if (hasUnpaused) {
           this.focusTrap.unpause();
-        } else if (!prevProps.paused && this.props.paused) {
-          this.focusTrap.pause();
         }
       } else if (prevProps.containerElements !== this.props.containerElements) {
         this.focusTrapElements = this.props.containerElements;
@@ -169,21 +236,12 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
   }, {
     key: "componentWillUnmount",
     value: function componentWillUnmount() {
-      if (this.focusTrap) {
-        // NOTE: we never let the trap return the focus since we do that ourselves
-        this.focusTrap.deactivate({
-          returnFocus: false
-        });
-      }
-
-      if (this.returnFocusOnDeactivate) {
-        this.returnFocus();
-      }
+      this.deactivateTrap();
     }
   }, {
     key: "render",
     value: function render() {
-      var _this2 = this;
+      var _this3 = this;
 
       var child = this.props.children ? React.Children.only(this.props.children) : undefined;
 
@@ -193,7 +251,7 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
         }
 
         var composedRefCallback = function composedRefCallback(element) {
-          var containerElements = _this2.props.containerElements;
+          var containerElements = _this3.props.containerElements;
 
           if (child) {
             if (typeof child.ref === 'function') {
@@ -203,7 +261,7 @@ var FocusTrap = /*#__PURE__*/function (_React$Component) {
             }
           }
 
-          _this2.focusTrapElements = containerElements ? containerElements : [element];
+          _this3.focusTrapElements = containerElements ? containerElements : [element];
         };
 
         var childWithRef = React.cloneElement(child, {
@@ -226,10 +284,14 @@ FocusTrap.propTypes = {
   paused: PropTypes.bool,
   focusTrapOptions: PropTypes.shape({
     onActivate: PropTypes.func,
+    onPostActivate: PropTypes.func,
+    checkCanFocusTrap: PropTypes.func,
     onDeactivate: PropTypes.func,
-    initialFocus: PropTypes.oneOfType([PropTypes.instanceOf(ElementType), PropTypes.string, PropTypes.func]),
+    onPostDeactivate: PropTypes.func,
+    checkCanReturnFocus: PropTypes.func,
+    initialFocus: PropTypes.oneOfType([PropTypes.instanceOf(ElementType), PropTypes.string, PropTypes.func, PropTypes.bool]),
     fallbackFocus: PropTypes.oneOfType([PropTypes.instanceOf(ElementType), PropTypes.string, PropTypes.func]),
-    escapeDeactivates: PropTypes.bool,
+    escapeDeactivates: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
     clickOutsideDeactivates: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
     returnFocusOnDeactivate: PropTypes.bool,
     setReturnFocus: PropTypes.oneOfType([PropTypes.instanceOf(ElementType), PropTypes.string, PropTypes.func]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focus-trap-react",
-  "version": "8.4.2",
+  "version": "8.7.0",
   "description": "A React component that traps focus.",
   "main": "dist/focus-trap-react.js",
   "types": "index.d.ts",
@@ -24,7 +24,6 @@
     "test:types": "tsc index.d.ts",
     "test:unit": "jest",
     "test:coverage": "jest --coverage",
-    "test:coverage:ci": "yarn test:coverage && codecov",
     "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",
@@ -56,44 +55,43 @@
   },
   "homepage": "https://github.com/focus-trap/focus-trap-react#readme",
   "devDependencies": {
-    "@babel/cli": "^7.12.13",
-    "@babel/core": "^7.12.13",
+    "@babel/cli": "^7.14.5",
+    "@babel/core": "^7.14.6",
     "@babel/plugin-proposal-class-properties": "^7.12.13",
-    "@babel/preset-env": "^7.12.13",
-    "@babel/preset-react": "^7.12.13",
-    "@changesets/cli": "^2.14.0",
-    "@testing-library/cypress": "^7.0.3",
-    "@testing-library/dom": "^7.29.4",
-    "@testing-library/jest-dom": "^5.11.9",
-    "@testing-library/react": "^11.2.5",
-    "@testing-library/user-event": "^12.6.3",
+    "@babel/preset-env": "^7.14.7",
+    "@babel/preset-react": "^7.14.5",
+    "@changesets/cli": "^2.16.0",
+    "@testing-library/cypress": "^7.0.6",
+    "@testing-library/dom": "^8.0.0",
+    "@testing-library/jest-dom": "^5.14.1",
+    "@testing-library/react": "^12.0.0",
+    "@testing-library/user-event": "^13.1.9",
     "@types/jquery": "^3.5.5",
-    "all-contributors-cli": "^6.19.0",
+    "all-contributors-cli": "^6.20.0",
     "babel-eslint": "^10.1.0",
-    "babel-jest": "^26.6.3",
+    "babel-jest": "^27.0.6",
     "babelify": "^10.0.0",
     "browserify": "^17.0.0",
     "budo": "^11.6.4",
-    "codecov": "^3.8.1",
-    "cypress": "^6.4.0",
+    "cypress": "^7.6.0",
     "cypress-plugin-tab": "^1.0.5",
-    "eslint": "^7.19.0",
-    "eslint-config-prettier": "^7.2.0",
-    "eslint-plugin-cypress": "^2.11.2",
-    "eslint-plugin-react": "^7.22.0",
-    "jest": "^26.6.3",
-    "jest-watch-typeahead": "^0.6.1",
+    "eslint": "^7.29.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-cypress": "^2.11.3",
+    "eslint-plugin-react": "^7.24.0",
+    "jest": "^27.0.6",
+    "jest-watch-typeahead": "^0.6.4",
     "onchange": "^7.1.0",
-    "prettier": "^2.2.1",
+    "prettier": "^2.3.2",
     "prop-types": "^15.7.2",
-    "react": "^17.0.1",
-    "react-dom": "^17.0.1",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
     "regenerator-runtime": "^0.13.7",
-    "start-server-and-test": "^1.12.0",
-    "typescript": "^4.1.3"
+    "start-server-and-test": "^1.12.5",
+    "typescript": "^4.3.4"
   },
   "dependencies": {
-    "focus-trap": "^6.3.0"
+    "focus-trap": "^6.6.0"
   },
   "peerDependencies": {
     "prop-types": "^15.7.2",

package/src/focus-trap-react.js

@@ -36,6 +36,11 @@ class FocusTrap extends React.Component {
         continue;
       }
 
+      if (optionName === 'onPostDeactivate') {
+        this.onPostDeactivate = focusTrapOptions[optionName];
+        continue;
+      }
+
       this.tailoredFocusTrapOptions[optionName] = focusTrapOptions[optionName];
     }
 
@@ -48,6 +53,38 @@ class FocusTrap extends React.Component {
     this.updatePreviousElement();
   }
 
+  // TODO: Need more test coverage for this function
+  getNodeForOption(optionName) {
+    const optionValue = this.tailoredFocusTrapOptions[optionName];
+    if (!optionValue) {
+      return null;
+    }
+
+    let node = optionValue;
+
+    if (typeof optionValue === 'string') {
+      node = document.querySelector(optionValue);
+      if (!node) {
+        throw new Error(`\`${optionName}\` refers to no known node`);
+      }
+    }
+
+    if (typeof optionValue === 'function') {
+      node = optionValue();
+      if (!node) {
+        throw new Error(`\`${optionName}\` did not return a node`);
+      }
+    }
+
+    return node;
+  }
+
+  getReturnFocusNode() {
+    const node = this.getNodeForOption('setReturnFocus');
+
+    return node ? node : this.previouslyFocusedElement;
+  }
+
   /** Update the previously focused element with the currently focused element. */
   updatePreviousElement() {
     if (typeof document !== 'undefined') {
@@ -55,10 +92,36 @@ class FocusTrap extends React.Component {
     }
   }
 
-  /** Returns focus to the element that had focus when the trap was activated. */
-  returnFocus() {
-    if (this.previouslyFocusedElement && this.previouslyFocusedElement.focus) {
-      this.previouslyFocusedElement.focus();
+  deactivateTrap() {
+    const { checkCanReturnFocus } = this.tailoredFocusTrapOptions;
+
+    if (this.focusTrap) {
+      // NOTE: we never let the trap return the focus since we do that ourselves
+      this.focusTrap.deactivate({ returnFocus: false });
+    }
+
+    const finishDeactivation = () => {
+      const returnFocusNode = this.getReturnFocusNode();
+      const canReturnFocus =
+        returnFocusNode?.focus && this.returnFocusOnDeactivate;
+
+      if (canReturnFocus) {
+        /** Returns focus to the element that had focus when the trap was activated. */
+        returnFocusNode.focus();
+      }
+
+      if (this.onPostDeactivate) {
+        this.onPostDeactivate.call(null); // don't call it in context of "this"
+      }
+    };
+
+    if (checkCanReturnFocus) {
+      checkCanReturnFocus(this.getReturnFocusNode()).then(
+        finishDeactivation,
+        finishDeactivation
+      );
+    } else {
+      finishDeactivation();
     }
   }
 
@@ -100,25 +163,28 @@ class FocusTrap extends React.Component {
         this.focusTrap.updateContainerElements(this.props.containerElements);
       }
 
-      if (prevProps.active && !this.props.active) {
-        // NOTE: we never let the trap return the focus since we do that ourselves
-        this.focusTrap.deactivate({ returnFocus: false });
-        if (this.returnFocusOnDeactivate) {
-          this.returnFocus();
-        }
-        return; // un/pause does nothing on an inactive trap
-      }
+      const hasActivated = !prevProps.active && this.props.active;
+      const hasDeactivated = prevProps.active && !this.props.active;
+      const hasPaused = !prevProps.paused && this.props.paused;
+      const hasUnpaused = prevProps.paused && !this.props.paused;
 
-      if (!prevProps.active && this.props.active) {
+      if (hasActivated) {
         this.updatePreviousElement();
         this.focusTrap.activate();
       }
 
-      if (prevProps.paused && !this.props.paused) {
-        this.focusTrap.unpause();
-      } else if (!prevProps.paused && this.props.paused) {
+      if (hasDeactivated) {
+        this.deactivateTrap();
+        return; // un/pause does nothing on an inactive trap
+      }
+
+      if (hasPaused) {
         this.focusTrap.pause();
       }
+
+      if (hasUnpaused) {
+        this.focusTrap.unpause();
+      }
     } else if (prevProps.containerElements !== this.props.containerElements) {
       this.focusTrapElements = this.props.containerElements;
       this.setupFocusTrap();
@@ -126,14 +192,7 @@ class FocusTrap extends React.Component {
   }
 
   componentWillUnmount() {
-    if (this.focusTrap) {
-      // NOTE: we never let the trap return the focus since we do that ourselves
-      this.focusTrap.deactivate({ returnFocus: false });
-    }
-
-    if (this.returnFocusOnDeactivate) {
-      this.returnFocus();
-    }
+    this.deactivateTrap();
   }
 
   render() {
@@ -183,18 +242,23 @@ FocusTrap.propTypes = {
   paused: PropTypes.bool,
   focusTrapOptions: PropTypes.shape({
     onActivate: PropTypes.func,
+    onPostActivate: PropTypes.func,
+    checkCanFocusTrap: PropTypes.func,
     onDeactivate: PropTypes.func,
+    onPostDeactivate: PropTypes.func,
+    checkCanReturnFocus: PropTypes.func,
     initialFocus: PropTypes.oneOfType([
       PropTypes.instanceOf(ElementType),
       PropTypes.string,
       PropTypes.func,
+      PropTypes.bool,
     ]),
     fallbackFocus: PropTypes.oneOfType([
       PropTypes.instanceOf(ElementType),
       PropTypes.string,
       PropTypes.func,
     ]),
-    escapeDeactivates: PropTypes.bool,
+    escapeDeactivates: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
     clickOutsideDeactivates: PropTypes.oneOfType([
       PropTypes.bool,
       PropTypes.func,