focus-trap 6.5.0 → 6.7.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 6.7.0
+
+### Minor Changes
+
+- 893dd2c: Add `document` option to support focus traps inside `<iframe>` elements (#97)
+- 244f0c1: Extend the `setReturnFocus` option to receive a reference to the element that had focus prior to the trap being activated when a function is specified. Additionally, the function can now return `false` to leave focus where it is at the time of deactivation. (#485)
+
+### Patch Changes
+
+- 60162eb: Fix bug where `KeyboardEvent` was not being passed to `escapeDeactivates` option when it's a function (#498)
+- 7b6abfa: Fix how focus-trap determines the event's target, which was preventing traps inside open shadow DOMs from working properly (#496)
+- 14b0ee8: Fix `initialFocus` option not supporting function returning `false` as documented (#490)
+
+## 6.6.1
+
+### Patch Changes
+
+- 24063d7: Update tabbable to v5.2.1 to get bug fix for disabled fieldsets.
+
+## 6.6.0
+
+### Minor Changes
+
+- 281e66c: Add option to allow no initial focus when trap activates via `initialFocus: false`
+
+  There may be cases where we don't want to focus the first tabbable element when a focus trap activates.
+
+  Examples use-cases:
+
+  - Modals/dialogs
+  - On mobile devices where "tabbing" doesn't make sense without a connected Bluetooth keyboard
+
+  In addition, this change ensures that any element inside the trap manually focused outside of `focus-trap` code will be brought back in focus if focus is somehow found outside of the trap.
+
+  Example usage:
+
+  When the trap activates, there will be no initially focused element inside the new trap.
+
+  ```js
+  const focusTrap = createFocusTrap('#some-container', {
+    initialFocus: false,
+  });
+  ```
+
+- 75be463: `escapeDeactivates` can now be either a boolean (as before) or a function that takes an event and returns a boolean.
+
+### Patch Changes
+
+- e2294f0: Fix race condition when activating a second trap where initial focus in the second trap may be thwarted because pausing of first trap clears the `delayInitialFocus` timer created for the second trap before during its activation sequence.
+
+## 6.5.1
+
+### Patch Changes
+
+- c38bf3f: onPostDeactivate should always be called even if returnFocus/OnDeactivate is disabled.
+
 ## 6.5.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
 # focus-trap [![CI](https://github.com/focus-trap/focus-trap/workflows/CI/badge.svg?branch=master&event=push)](https://github.com/focus-trap/focus-trap/actions?query=workflow:CI+branch:master) [![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-15-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-19-orange.svg?style=flat-square)](#contributors)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 Trap focus within a DOM node.
@@ -28,7 +28,7 @@ When the focus trap is deactivated, this is what should happen:
 - Focus is passed to *whichever element had focus when the trap was activated* (e.g. the button that opened the modal or menu).
 - Tabbing and clicking behave normally everywhere.
 
-[Check out the demos.](http://focus-trap.github.io/focus-trap/demo/)
+[Check out the demos.](http://focus-trap.github.io/focus-trap/)
 
 For more advanced usage (e.g. focus traps within focus traps), you can also pause a focus trap's behavior without deactivating it entirely, then unpause at will.
 
@@ -86,19 +86,33 @@ Returns a new focus trap on `element` (one or more "containers" of tabbable node
 - **onPostActivate** `{() => void}`: A function that will be called **after** sending focus to the target element upon activation.
 - **checkCanFocusTrap** `{(containers: Array<HTMLElement | SVGElement>) => Promise<void>}`: Animated dialogs have a small delay between when `onActivate` is called and when the focus trap is focusable. `checkCanFocusTrap` expects a promise to be returned. When that promise settles (resolves or rejects), focus will be sent to the first tabbable node (in tab order) in the focus trap (or the node configured in the `initialFocus` option). Due to the lack of Promise support, `checkCanFocusTrap` is not supported in IE unless you provide a Promise polyfill.
 - **onDeactivate** `{() => void}`: A function that will be called **before** returning focus to the node that had focus prior to activation (or configured with the `setReturnFocus` option) upon deactivation.
-- **onPostDeactivate** `{() => void}`: A function that will be called **after** returning focus to the node that had focus prior to activation (or configured with the `setReturnFocus` option) upon deactivation.
+- **onPostDeactivate** `{() => void}`: A function that will be called after the trap is deactivated, after `onDeactivate`. If the `returnFocus` deactivation option was set, it will be called **after** returning focus to the node that had focus prior to activation (or configured with the `setReturnFocus` option) upon deactivation; otherwise, it will be called after deactivation completes.
 - **checkCanReturnFocus** `{(trigger: HTMLElement | SVGElement) => Promise<void>}`: An animated trigger button will have a small delay between when `onDeactivate` is called and when the focus is able to be sent back to the trigger. `checkCanReturnFocus` expects a promise to be returned. When that promise settles (resolves or rejects), focus will be sent to to the node that had focus prior to the activation of the trap (or the node configured in the `setReturnFocus` option). Due to the lack of Promise support, `checkCanReturnFocus` is not supported in IE unless you provide a Promise polyfill.
-- **initialFocus** `{HTMLElement | SVGElement | string | () => HTMLElement | SVGElement}`: 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 specify a different element to receive that initial focus. Can be a DOM node, or a selector string (which will be passed to `document.querySelector()` to find the DOM node), or a function that returns a DOM node.
+- **initialFocus** `{HTMLElement | SVGElement | string | false | (() => HTMLElement | SVGElement | false)}`: 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 specify a different element to receive that initial focus. Can be a DOM node, or a selector string (which will be passed to `document.querySelector()` to find the DOM node), or a function that returns a DOM node. You can also set this option to `false` (or to a function that returns `false`) to prevent any initial focus at all when the trap activates.
+    - 💬 Setting this option to `false` (or a function that returns `false`) will prevent the `fallbackFocus` option from being used.
+    - ⚠️ See warning below about **Shadow DOM** and selector strings.
 - **fallbackFocus** `{HTMLElement | SVGElement | string | () => HTMLElement | SVGElement}`: By default, an error will be thrown if the focus trap contains no elements in its tab order. With this option you can specify a fallback element to programmatically receive focus if no other tabbable elements are found. For example, you may want a popover's `<div>` to receive focus if the popover's content includes no tabbable elements. *Make sure the fallback element has a negative `tabindex` so it can be programmatically focused.* The option value can be a DOM node, a selector string (which will be passed to `document.querySelector()` to find the DOM node), or a function that returns a DOM node.
-- **escapeDeactivates** `{boolean}`: Default: `true`. If `false`, the `Escape` key will not trigger deactivation of the focus trap. This can be useful if you want to force the user to make a decision instead of allowing an easy way out.
+    - 💬 If `initialFocus` is `false` (or a function that returns `false`), this function will not be called when the trap is activated, and no element will be initially focused. This function may still be called while the trap is active if things change such that there are no longer any tabbable nodes in the trap.
+    - ⚠️ See warning below about **Shadow DOM** and selector strings.
+- **escapeDeactivates** `{boolean} | (e: KeyboardEvent) => boolean)`: Default: `true`. If `false` or returns `false`, the `Escape` key will not trigger deactivation of the focus trap. This can be useful if you want to force the user to make a decision instead of allowing an easy way out. Note that if a function is given, it's only called if the ESC key was pressed.
 - **clickOutsideDeactivates** `{boolean | (e: MouseEvent | TouchEvent) => boolean}`: 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`. Default: `false`.
   - ⚠️ If you're using a password manager such as 1Password, where the app adds a clickable icon to all fillable fields, you should avoid using this option, and instead use the `allowOutsideClick` option to better control exactly when the focus trap can be deactivated. The clickable icons are usually positioned absolutely, floating on top of the fields, and therefore _not_ part of the container the trap is managing. When using the `clickOutsideDeactivates` option, clicking on a field's 1Password icon will likely cause the trap to be unintentionally deactivated.
 - **allowOutsideClick** `{boolean | (e: MouseEvent | TouchEvent) => boolean}`: 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`. Default: `false`.
   - ⚠️ If this is a function, it will be called **twice** on every click: First on `mousedown` (or `touchstart` on mobile), and then on the actual `click` if the function returned `true` on the first event. Be sure to check the event type if the double call is an issue in your code.
 - **returnFocusOnDeactivate** `{boolean}`: Default: `true`. If `false`, when the trap is deactivated, focus will *not* return to the element that had focus before activation.
-- **setReturnFocus** `{HTMLElement | SVGElement | string | () => HTMLElement | SVGElement}`: By default, focus trap on deactivation will return to the element that was focused before activation. With this option you can specify another element to programmatically receive focus after deactivation. Can be a DOM node, or a selector string (which will be passed to `document.querySelector()` to find the DOM node), or a function that returns a DOM node.
+- **setReturnFocus** `{HTMLElement | SVGElement | string | (previousActiveElement: HTMLElement | SVGElement) => HTMLElement | SVGElement | false}`: By default, on **deactivation**, if `returnFocusOnDeactivate=true` (or if `returnFocus=true` in the [deactivation options](#trapdeactivatedeactivateoptions)), focus will be returned to the element that was focused just before activation. With this option, you can specify another element to programmatically receive focus after deactivation. It can be a DOM node, a selector string (which will be passed to `document.querySelector()` to find the DOM node **upon deactivation**), or a function that returns a DOM node to call **upon deactivation** (i.e. the selector and function options are only executed at the time the trap is deactivated), or `false` to leave focus where it is at the time of deactivation.
+    - 💬 Using the selector or function options is a good way to return focus to a DOM node that may not even exist at the time the trap is activated.
+    - ⚠️ See warning below about **Shadow DOM** and selector strings.
 - **preventScroll** `{boolean}`: By default, focus() will scroll to the element if not in viewport. It can produce unintended effects like scrolling back to the top of a modal. If set to `true`, no scroll will happen.
 - **delayInitialFocus** `{boolean}`: Default: `true`. Delays the autofocus to the next execution frame when the focus trap is activated. This prevents elements within the focusable element from capturing the event that triggered the focus trap activation.
+- **document** {Document}: Default: `window.document`. Document where the focus trap will be active. This allows to use FocusTrap in an iFrame context.
+
+#### Shadow DOM and selector strings
+
+⚠️ Beware that putting a focus-trap **inside** an open Shadow DOM means you must either:
+
+- **Not use selector strings** for options that support these (because nodes inside Shadow DOMs, even open shadows, are not visible via `document.querySelector()`); OR
+- You must **use the `document` option** to configure the focus trap to use your *shadow host* element as its document. The downside of this option is that, while selector queries on nodes inside your trap will now work, the trap will not prevent focus from being set on nodes outside your Shadow DOM, which is the same drawback as putting a focus trap <a href="https://focus-trap.github.io/focus-trap/#demo-in-iframe">inside an iframe</a>.
 
 ### trap.activate([activateOptions])
 
@@ -132,7 +146,7 @@ Returns the `trap`.
 
 These options are used to override the focus trap's default behavior for this particular deactivation.
 
-- **returnFocus** `{boolean}`: Default: whatever you chose for `createOptions.returnFocusOnDeactivate`.
+- **returnFocus** `{boolean}`: Default: whatever you chose for `createOptions.returnFocusOnDeactivate`. If `true`, then the `setReturnFocus` option (specified when the trap was created) is used to determine where focus will be returned.
 - **onDeactivate** `{() => void}`: Default: whatever you chose for `createOptions.onDeactivate`. `null` or `false` are the equivalent of a `noop`.
 - **onPostDeactivate** `{() => void}`: Default: whatever you chose for `createOptions.onPostDeactivate`. `null` or `false` are the equivalent of a `noop`.
 - **checkCanReturnFocus** `{(trigger: HTMLElement | SVGElement) => Promise<void>}`: Default: whatever you chose for `createOptions.checkCanReturnFocus`. Not called if the `returnFocus` option is falsy. `trigger` is either the originally focused node prior to activation, or the result of the `setReturnFocus` configuration option.
@@ -171,12 +185,12 @@ Returns the `trap`.
 
 ## Examples
 
-Read code in `demo/` and [see how it works](http://focus-trap.github.io/focus-trap/demo/).
+Read code in `docs/` and [see how it works](http://focus-trap.github.io/focus-trap/).
 
-Here's what happens in `default.js` (the "default behavior" demo):
+Here's generally what happens in `default.js` (the "default behavior" demo):
 
 ```js
-const { createFocusTrap } = require('../../dist/focus-trap');
+const { createFocusTrap } = require('../../index');
 
 const container = document.getElementById('default');
 
@@ -232,24 +246,28 @@ In alphabetical order:
 <!-- markdownlint-disable -->
 <table>
   <tr>
+    <td align="center"><a href="https://github.com/andersthorsen"><img src="https://avatars.githubusercontent.com/u/190081?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Anders Thorsen</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/issues?q=author%3Aandersthorsen" title="Bug reports">🐛</a></td>
     <td align="center"><a href="https://github.com/bparish628"><img src="https://avatars1.githubusercontent.com/u/8492971?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Benjamin Parish</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/issues?q=author%3Abparish628" title="Bug reports">🐛</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/commits?author=cgood92" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=cgood92" title="Documentation">📖</a> <a href="#example-cgood92" title="Examples">💡</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=cgood92" 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/commits?author=Dan503" title="Documentation">📖</a> <a href="#tool-Dan503" title="Tools">🔧</a> <a href="#a11y-Dan503" title="Accessibility">️️️️♿️</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=Dan503" title="Code">💻</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/commits?author=davidtheclark" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/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/commits?author=davidtheclark" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap/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="https://github.com/michael-ar"><img src="https://avatars3.githubusercontent.com/u/18557997?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Michael Reynolds</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/issues?q=author%3Amichael-ar" title="Bug reports">🐛</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/commits?author=liunate" title="Tests">⚠️</a></td>
   </tr>
   <tr>
+    <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/commits?author=liunate" title="Tests">⚠️</a></td>
+    <td align="center"><a href="https://github.com/far-fetched"><img src="https://avatars.githubusercontent.com/u/11621383?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Piotr Panek</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/issues?q=author%3Afar-fetched" title="Bug reports">🐛</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=far-fetched" title="Documentation">📖</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=far-fetched" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=far-fetched" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://github.com/randypuro"><img src="https://avatars2.githubusercontent.com/u/2579?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Randy Puro</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/issues?q=author%3Arandypuro" title="Bug reports">🐛</a></td>
     <td align="center"><a href="https://github.com/sadick254"><img src="https://avatars2.githubusercontent.com/u/5238135?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sadick</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/commits?author=sadick254" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=sadick254" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=sadick254" title="Documentation">📖</a></td>
     <td align="center"><a href="https://scottblinch.me/"><img src="https://avatars2.githubusercontent.com/u/4682114?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Scott Blinch</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/commits?author=scottblinch" title="Documentation">📖</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/commits?author=SeanMcP" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=SeanMcP" title="Documentation">📖</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/issues?q=author%3ASlapbox" title="Bug reports">🐛</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/commits?author=stefcameron" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/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/commits?author=stefcameron" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap/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="#tool-thawkin3" title="Tools">🔧</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=thawkin3" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=thawkin3" title="Documentation">📖</a></td>
   </tr>
   <tr>
+    <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/commits?author=stefcameron" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/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/commits?author=stefcameron" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap/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="#tool-thawkin3" title="Tools">🔧</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=thawkin3" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=thawkin3" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/wandroll"><img src="https://avatars.githubusercontent.com/u/4492317?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Wandrille Verlut</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/commits?author=wandroll" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=wandroll" title="Tests">⚠️</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=wandroll" title="Documentation">📖</a> <a href="#tool-wandroll" title="Tools">🔧</a></td>
+    <td align="center"><a href="http://willmruzek.com/"><img src="https://avatars.githubusercontent.com/u/108522?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Will Mruzek</b></sub></a><br /><a href="https://github.com/focus-trap/focus-trap/commits?author=mruzekw" title="Code">💻</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=mruzekw" title="Documentation">📖</a> <a href="#example-mruzekw" title="Examples">💡</a> <a href="https://github.com/focus-trap/focus-trap/commits?author=mruzekw" title="Tests">⚠️</a> <a href="#question-mruzekw" title="Answering Questions">💬</a></td>
     <td align="center"><a href="https://github.com/zioth"><img src="https://avatars3.githubusercontent.com/u/945603?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Zioth</b></sub></a><br /><a href="#ideas-zioth" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/focus-trap/focus-trap/issues?q=author%3Azioth" title="Bug reports">🐛</a></td>
   </tr>
 </table>

package/dist/focus-trap.esm.js

@@ -1,5 +1,5 @@
 /*!
-* focus-trap 6.5.0
+* focus-trap 6.7.0
 * @license MIT, https://github.com/focus-trap/focus-trap/blob/master/LICENSE
 */
 import { tabbable, isFocusable } from 'tabbable';
@@ -57,8 +57,6 @@ function _defineProperty(obj, key, value) {
   return obj;
 }
 
-var activeFocusDelay;
-
 var activeFocusTraps = function () {
   var trapQueue = [];
   return {
@@ -142,8 +140,19 @@ var valueOrHandler = function valueOrHandler(value) {
   return typeof value === 'function' ? value.apply(void 0, params) : value;
 };
 
+var getActualTarget = function getActualTarget(event) {
+  // NOTE: If the trap is _inside_ a shadow DOM, event.target will always be the
+  //  shadow host. However, event.target.composedPath() will be an array of
+  //  nodes "clicked" from inner-most (the actual element inside the shadow) to
+  //  outer-most (the host HTML document). If we have access to composedPath(),
+  //  then use its first element; otherwise, fall back to event.target (and
+  //  this only works for an _open_ shadow DOM; otherwise,
+  //  composedPath()[0] === event.target always).
+  return event.target.shadowRoot && typeof event.composedPath === 'function' ? event.composedPath()[0] : event.target;
+};
+
 var createFocusTrap = function createFocusTrap(elements, userOptions) {
-  var doc = document;
+  var doc = userOptions.document || document;
 
   var config = _objectSpread2({
     returnFocusOnDeactivate: true,
@@ -165,7 +174,10 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
     nodeFocusedBeforeActivation: null,
     mostRecentlyFocusedNode: null,
     active: false,
-    paused: false
+    paused: false,
+    // timer ID for when delayInitialFocus is true and initial focus in this trap
+    //  has been delayed during activation
+    delayInitialFocusTimer: undefined
   };
   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
 
@@ -174,33 +186,52 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
   };
 
   var containersContain = function containersContain(element) {
-    return state.containers.some(function (container) {
+    return !!(element && state.containers.some(function (container) {
       return container.contains(element);
-    });
+    }));
   };
+  /**
+   * Gets the node for the given option, which is expected to be an option that
+   *  can be either a DOM node, a string that is a selector to get a node, `false`
+   *  (if a node is explicitly NOT given), or a function that returns any of these
+   *  values.
+   * @param {string} optionName
+   * @returns {undefined | false | HTMLElement | SVGElement} Returns
+   *  `undefined` if the option is not specified; `false` if the option
+   *  resolved to `false` (node explicitly not given); otherwise, the resolved
+   *  DOM node.
+   * @throws {Error} If the option is set, not `false`, and is not, or does not
+   *  resolve to a node.
+   */
+
 
   var getNodeForOption = function getNodeForOption(optionName) {
     var optionValue = config[optionName];
 
-    if (!optionValue) {
-      return null;
+    if (typeof optionValue === 'function') {
+      for (var _len2 = arguments.length, params = new Array(_len2 > 1 ? _len2 - 1 : 0), _key2 = 1; _key2 < _len2; _key2++) {
+        params[_key2 - 1] = arguments[_key2];
+      }
+
+      optionValue = optionValue.apply(void 0, params);
     }
 
-    var node = optionValue;
+    if (!optionValue) {
+      if (optionValue === undefined || optionValue === false) {
+        return optionValue;
+      } // else, empty string (invalid), null (invalid), 0 (invalid)
 
-    if (typeof optionValue === 'string') {
-      node = doc.querySelector(optionValue);
 
-      if (!node) {
-        throw new Error("`".concat(optionName, "` refers to no known node"));
-      }
+      throw new Error("`".concat(optionName, "` was specified but was not a node, or did not return a node"));
     }
 
-    if (typeof optionValue === 'function') {
-      node = optionValue();
+    var node = optionValue; // could be HTMLElement, SVGElement, or non-empty string at this point
+
+    if (typeof optionValue === 'string') {
+      node = doc.querySelector(optionValue); // resolve to node, or null if fails
 
       if (!node) {
-        throw new Error("`".concat(optionName, "` did not return a node"));
+        throw new Error("`".concat(optionName, "` as selector refers to no known node"));
       }
     }
 
@@ -208,16 +239,22 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
   };
 
   var getInitialFocusNode = function getInitialFocusNode() {
-    var node;
+    var node = getNodeForOption('initialFocus'); // false explicitly indicates we want no initialFocus at all
 
-    if (getNodeForOption('initialFocus') !== null) {
-      node = getNodeForOption('initialFocus');
-    } else if (containersContain(doc.activeElement)) {
-      node = doc.activeElement;
-    } else {
-      var firstTabbableGroup = state.tabbableGroups[0];
-      var firstTabbableNode = firstTabbableGroup && firstTabbableGroup.firstTabbableNode;
-      node = firstTabbableNode || getNodeForOption('fallbackFocus');
+    if (node === false) {
+      return false;
+    }
+
+    if (node === undefined) {
+      // option not specified: use fallback options
+      if (containersContain(doc.activeElement)) {
+        node = doc.activeElement;
+      } else {
+        var firstTabbableGroup = state.tabbableGroups[0];
+        var firstTabbableNode = firstTabbableGroup && firstTabbableGroup.firstTabbableNode; // NOTE: `fallbackFocus` option function cannot return `false` (not supported)
+
+        node = firstTabbableNode || getNodeForOption('fallbackFocus');
+      }
     }
 
     if (!node) {
@@ -245,12 +282,17 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
     }); // 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')) {
+    if (state.tabbableGroups.length <= 0 && !getNodeForOption('fallbackFocus') // returning false not supported for this option
+    ) {
       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 === false) {
+      return;
+    }
+
     if (node === doc.activeElement) {
       return;
     }
@@ -271,14 +313,16 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
   };
 
   var getReturnFocusNode = function getReturnFocusNode(previousActiveElement) {
-    var node = getNodeForOption('setReturnFocus');
-    return node ? node : previousActiveElement;
+    var node = getNodeForOption('setReturnFocus', previousActiveElement);
+    return node ? node : node === false ? false : previousActiveElement;
   }; // This needs to be done on mousedown and touchstart instead of click
   // so that it precedes the focus event.
 
 
   var checkPointerDown = function checkPointerDown(e) {
-    if (containersContain(e.target)) {
+    var target = getActualTarget(e);
+
+    if (containersContain(target)) {
       // allow the click since it ocurred inside the trap
       return;
     }
@@ -297,7 +341,7 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
         //  that was clicked, whether it's focusable or not; by setting
         //  `returnFocus: true`, we'll attempt to re-focus the node originally-focused
         //  on activation (or the configured `setReturnFocus` node)
-        returnFocus: config.returnFocusOnDeactivate && !isFocusable(e.target)
+        returnFocus: config.returnFocusOnDeactivate && !isFocusable(target)
       });
       return;
     } // This is needed for mobile devices.
@@ -316,11 +360,12 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
 
 
   var checkFocusIn = function checkFocusIn(e) {
-    var targetContained = containersContain(e.target); // In Firefox when you Tab out of an iframe the Document is briefly focused.
+    var target = getActualTarget(e);
+    var targetContained = containersContain(target); // In Firefox when you Tab out of an iframe the Document is briefly focused.
 
-    if (targetContained || e.target instanceof Document) {
+    if (targetContained || target instanceof Document) {
       if (targetContained) {
-        state.mostRecentlyFocusedNode = e.target;
+        state.mostRecentlyFocusedNode = target;
       }
     } else {
       // escaped! pull it back in to where it just left
@@ -334,6 +379,7 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
 
 
   var checkTab = function checkTab(e) {
+    var target = getActualTarget(e);
     updateTabbableNodes();
     var destinationNode = null;
 
@@ -343,7 +389,7 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
       //  with tabIndex='-1' and was given initial focus
       var containerIndex = findIndex(state.tabbableGroups, function (_ref) {
         var container = _ref.container;
-        return container.contains(e.target);
+        return container.contains(target);
       });
 
       if (containerIndex < 0) {
@@ -361,10 +407,10 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
         // is the target the first tabbable node in a group?
         var startOfGroupIndex = findIndex(state.tabbableGroups, function (_ref2) {
           var firstTabbableNode = _ref2.firstTabbableNode;
-          return e.target === firstTabbableNode;
+          return target === firstTabbableNode;
         });
 
-        if (startOfGroupIndex < 0 && state.tabbableGroups[containerIndex].container === e.target) {
+        if (startOfGroupIndex < 0 && state.tabbableGroups[containerIndex].container === 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
@@ -384,10 +430,10 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
         // is the target the last tabbable node in a group?
         var lastOfGroupIndex = findIndex(state.tabbableGroups, function (_ref3) {
           var lastTabbableNode = _ref3.lastTabbableNode;
-          return e.target === lastTabbableNode;
+          return target === lastTabbableNode;
         });
 
-        if (lastOfGroupIndex < 0 && state.tabbableGroups[containerIndex].container === e.target) {
+        if (lastOfGroupIndex < 0 && state.tabbableGroups[containerIndex].container === 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
@@ -405,6 +451,7 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
         }
       }
     } else {
+      // NOTE: the fallbackFocus option does not support returning false to opt-out
       destinationNode = getNodeForOption('fallbackFocus');
     }
 
@@ -416,7 +463,7 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
   };
 
   var checkKey = function checkKey(e) {
-    if (config.escapeDeactivates !== false && isEscapeEvent(e)) {
+    if (isEscapeEvent(e) && valueOrHandler(config.escapeDeactivates, e) !== false) {
       e.preventDefault();
       trap.deactivate();
       return;
@@ -433,7 +480,9 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
       return;
     }
 
-    if (containersContain(e.target)) {
+    var target = getActualTarget(e);
+
+    if (containersContain(target)) {
       return;
     }
 
@@ -457,7 +506,7 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
     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 () {
+    state.delayInitialFocusTimer = config.delayInitialFocus ? delay(function () {
       tryFocus(getInitialFocusNode());
     }) : tryFocus(getInitialFocusNode());
     doc.addEventListener('focusin', checkFocusIn, true);
@@ -543,7 +592,9 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
         return this;
       }
 
-      clearTimeout(activeFocusDelay);
+      clearTimeout(state.delayInitialFocusTimer); // noop if undefined
+
+      state.delayInitialFocusTimer = undefined;
       removeListeners();
       state.active = false;
       state.paused = false;
@@ -559,15 +610,15 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
       var returnFocus = getOption(deactivateOptions, 'returnFocus', 'returnFocusOnDeactivate');
 
       var finishDeactivation = function finishDeactivation() {
-        if (returnFocus) {
-          delay(function () {
+        delay(function () {
+          if (returnFocus) {
             tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
+          }
 
-            if (onPostDeactivate) {
-              onPostDeactivate();
-            }
-          });
-        }
+          if (onPostDeactivate) {
+            onPostDeactivate();
+          }
+        });
       };
 
       if (returnFocus && checkCanReturnFocus) {