focus-trap-react 9.0.2 → 10.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 10.0.0
+
+### Major Changes
+
+- af69c14: 🚨 **Breaking:** Underlying `tabbable` dependency has been updated to v6.0.0 and contains a breaking change related to detached nodes with its default `displayCheck` setting. See tabbable's [changelog](https://github.com/focus-trap/tabbable/blob/master/CHANGELOG.md#600) for more information.
+  - The `focus-trap` dependency has also be updated to v7.0.0 but only contains the underlying `tabbable` changes.
+  - The `tabbableOptions.displayCheck` prop type has been updated to include the new "legacy-full" option.
+- 018732c: 🚨 **Breaking:** Dropped support of IE browsers, all versions.
+  - IE11 was [officially retired](https://blogs.windows.com/windowsexperience/2022/06/15/internet-explorer-11-has-retired-and-is-officially-out-of-support-what-you-need-to-know/) on June 15, 2022 (6 weeks ago). There are no longer any versions of IE that are still maintained or even supported by Microsoft.
+- 018732c: Revised and clarified official browser support (still as broad and deep as _reasonably_ possible).
+
+### Patch Changes
+
+- b0bbbd4: Update README with a note about the `children` prop stating that the trap requires a single child, and that if a component is used, it must be a **functional** component that forwards refs.
+
 ## 9.0.2
 
 ### Patch Changes

package/README.md

@@ -33,13 +33,21 @@ npm install focus-trap-react
 
 ### React dependency
 
-React `>= 16.0.0`.
+React `>= 16.3.0`
 
 ## Browser Support
 
-Basically IE9+.
+As old and as broad as _reasonably_ possible, excluding browsers that are out of support or have nearly no user base.
 
-Why? Because this module's core functionality comes from focus-trap, which uses [a couple of IE9+ functions](https://github.com/davidtheclark/tabbable#browser-support).
+Focused on desktop browsers, particularly Chrome, Edge, FireFox, Safari, and Opera.
+
+Focus-trap-react is not officially tested on any mobile browsers or devices.
+
+> ⚠️ Microsoft [no longer supports](https://blogs.windows.com/windowsexperience/2022/06/15/internet-explorer-11-has-retired-and-is-officially-out-of-support-what-you-need-to-know/) any version of IE, so IE is no longer supported by this library.
+
+> 💬 Focus-trap-react relies on focus-trap so its browser support is at least [what focus-trap supports](https://github.com/focus-trap/focus-trap#browser-support).
+
+> 💬 Keep in mind that performance optimization and old browser support are often at odds, so tabbable may not always be able to use the most optimal (typically modern) APIs in all cases.
 
 ## Usage
 
@@ -66,7 +74,7 @@ You can read further code examples in `demo/` (it's very simple), and [see how i
 
 Here's one more simple example:
 
-```js
+```jsx
 const React = require('react');
 const ReactDOM = require('react-dom'); // React 16-17
 const { createRoot } = require('react-dom/client'); // React 18
@@ -139,6 +147,96 @@ createRoot(document.getElementById('root')).render(<Demo />); // React 18
 
 ### Props
 
+#### children
+
+> ⚠️ The `<FocusTrap>` component requires a __single__ child, and this child must __forward refs__ onto the element which will ultimately be considered the trap's container. Since React does not provide for a way to forward refs to class-based components, this means the child must be a __functional__ component that uses the `React.forwardRef()` API.
+>
+> If you must use a __class__-based component as the trap's container, then you will need to get your own ref to it upon render, and use the `containerElements` prop (initially set to an empty array `[]`) in order to provide the ref's element to it once updated by React (hint: use a [callback ref](https://reactjs.org/docs/refs-and-the-dom.html#callback-refs)).
+
+> 💬 The child is ignored (but still rendered) if the `containerElements` prop is used to imperatively provide trap container elements.
+
+Example:
+
+```jsx
+const React = require('react');
+const { createRoot } = require('react-dom/client');
+const propTypes = require('prop-types');
+const FocusTrap = require('../../dist/focus-trap-react');
+
+const container = document.getElementById('demo-function-child');
+
+const TrapChild = React.forwardRef(function ({ onDeactivate }, ref) {
+  return (
+    <div ref={ref}>
+      <p>
+        Here is a focus trap <a href="#">with</a> <a href="#">some</a>{' '}
+        <a href="#">focusable</a> parts.
+      </p>
+      <p>
+        <button
+          onClick={onDeactivate}
+          aria-describedby="class-child-heading"
+        >
+          deactivate trap
+        </button>
+      </p>
+    </div>
+  );
+});
+
+TrapChild.displayName = 'TrapChild';
+TrapChild.propTypes = {
+  onDeactivate: propTypes.func,
+};
+
+class DemoFunctionChild extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.state = {
+      activeTrap: false,
+    };
+
+    this.mountTrap = this.mountTrap.bind(this);
+    this.unmountTrap = this.unmountTrap.bind(this);
+  }
+
+  mountTrap() {
+    this.setState({ activeTrap: true });
+  }
+
+  unmountTrap() {
+    this.setState({ activeTrap: false });
+  }
+
+  render() {
+    const trap = this.state.activeTrap && (
+      <FocusTrap
+        focusTrapOptions={{
+          onDeactivate: this.unmountTrap,
+        }}
+      >
+        <TrapChild />
+      </FocusTrap>
+    );
+
+    return (
+      <div>
+        <p>
+          <button onClick={this.mountTrap} aria-describedby="function-child-heading">
+            activate trap
+          </button>
+        </p>
+        {trap}
+      </div>
+    );
+  }
+}
+
+const root = createRoot(container);
+root.render(<DemoFunctionChild />);
+```
+
 #### focusTrapOptions
 
 Type: `Object`, optional
@@ -165,9 +263,11 @@ If you would like to pause or unpause the focus trap (see [`focus-trap`'s docume
 
 Type: `Array of HTMLElement`, optional
 
-If passed in, these elements will be used as the boundaries for the focus-trap, __instead of the child__.  These get passed as arguments to `focus-trap`'s `updateContainerElements()` method.
+If specified, these elements will be used as the boundaries for the focus-trap, __instead of the child__.  These get passed as arguments to `focus-trap`'s `updateContainerElements()` method.
 
-> Note that when you use `containerElements`, the need for a child is eliminated as the child is __always__ ignored when the prop is specified, even if the prop is `[]` (an empty array). Also note that if the refs you're putting into the array like `containerElements={[ref1.current, ref2.current]}` and one or both refs aren't resolved yet, resulting in `[null, null]` for example, the trap will not get created. The array must contain at least one `HTMLElement` in order for the trap to get updated.
+> 💬 Note that when you use `containerElements`, the need for a child is eliminated as the child is __always__ ignored (though still rendered) when the prop is specified, even if this prop is `[]` (an empty array).
+>
+> Also note that if the refs you're putting into the array, like `containerElements={[ref1.current, ref2.current]}`, aren't resolved yet, resulting in `[null, null]` for example, the trap will not get created. The array must contain at least one valid `HTMLElement` in order for the trap to get created/updated.
 
 If `containerElements` is subsequently updated (i.e. after the trap has been created) to an empty array (or an array of falsy values like `[null, null]`), the trap will still be active, but the TAB key will do nothing because the trap will not contain any tabbable groups of nodes. At this point, the trap can either be deactivated manually or by unmounting, or an updated set of elements can be given to `containerElements` to resume use of the TAB key.
 

package/dist/focus-trap-react.js

@@ -464,7 +464,7 @@ FocusTrap.propTypes = {
     allowOutsideClick: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
     preventScroll: PropTypes.bool,
     tabbableOptions: PropTypes.shape({
-      displayCheck: PropTypes.oneOf(['full', 'non-zero-area', 'none']),
+      displayCheck: PropTypes.oneOf(['full', 'legacy-full', 'non-zero-area', 'none']),
       getShadowRoot: PropTypes.oneOfType([PropTypes.bool, PropTypes.func])
     })
   }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focus-trap-react",
-  "version": "9.0.2",
+  "version": "10.0.0",
   "description": "A React component that traps focus.",
   "main": "dist/focus-trap-react.js",
   "types": "index.d.ts",
@@ -57,46 +57,46 @@
   },
   "homepage": "https://github.com/focus-trap/focus-trap-react#readme",
   "devDependencies": {
-    "@babel/cli": "^7.17.10",
-    "@babel/core": "^7.18.5",
-    "@babel/eslint-parser": "^7.18.2",
-    "@babel/plugin-proposal-class-properties": "^7.17.12",
-    "@babel/preset-env": "^7.18.2",
-    "@babel/preset-react": "^7.17.12",
-    "@changesets/cli": "^2.23.0",
+    "@babel/cli": "^7.18.10",
+    "@babel/core": "^7.18.13",
+    "@babel/eslint-parser": "^7.18.9",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/preset-env": "^7.18.10",
+    "@babel/preset-react": "^7.18.6",
+    "@changesets/cli": "^2.24.3",
     "@testing-library/cypress": "^8.0.3",
-    "@testing-library/dom": "^8.13.0",
-    "@testing-library/jest-dom": "^5.16.4",
+    "@testing-library/dom": "^8.17.1",
+    "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^13.3.0",
-    "@testing-library/user-event": "^14.2.0",
+    "@testing-library/user-event": "^14.4.3",
     "@types/jquery": "^3.5.14",
     "all-contributors-cli": "^6.20.0",
-    "babel-jest": "^28.1.1",
+    "babel-jest": "^28.1.3",
     "babelify": "^10.0.0",
     "browserify": "^17.0.0",
     "budo": "^11.7.0",
-    "cypress": "^10.1.0",
+    "cypress": "^10.6.0",
     "cypress-plugin-tab": "^1.0.5",
-    "eslint": "^8.17.0",
+    "eslint": "^8.22.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-cypress": "^2.12.1",
-    "eslint-plugin-jest": "^26.5.3",
-    "eslint-plugin-react": "^7.30.0",
-    "jest": "^28.1.1",
-    "jest-environment-jsdom": "^28.1.1",
-    "jest-watch-typeahead": "^1.1.0",
+    "eslint-plugin-jest": "^26.8.7",
+    "eslint-plugin-react": "^7.30.1",
+    "jest": "^28.1.3",
+    "jest-environment-jsdom": "^28.1.3",
+    "jest-watch-typeahead": "^2.0.0",
     "onchange": "^7.1.0",
-    "prettier": "^2.7.0",
+    "prettier": "^2.7.1",
     "prop-types": "^15.8.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "regenerator-runtime": "^0.13.9",
     "start-server-and-test": "^1.14.0",
-    "typescript": "^4.7.3"
+    "typescript": "^4.7.4"
   },
   "dependencies": {
-    "focus-trap": "^6.9.4",
-    "tabbable": "^5.3.3"
+    "focus-trap": "^7.0.0",
+    "tabbable": "^6.0.0"
   },
   "peerDependencies": {
     "prop-types": "^15.8.1",

package/src/focus-trap-react.js

@@ -453,7 +453,12 @@ FocusTrap.propTypes = {
     allowOutsideClick: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
     preventScroll: PropTypes.bool,
     tabbableOptions: PropTypes.shape({
-      displayCheck: PropTypes.oneOf(['full', 'non-zero-area', 'none']),
+      displayCheck: PropTypes.oneOf([
+        'full',
+        'legacy-full',
+        'non-zero-area',
+        'none',
+      ]),
       getShadowRoot: PropTypes.oneOfType([PropTypes.bool, PropTypes.func]),
     }),
   }),