focus-trap 8.0.1 → 8.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 8.2.0
+
+### Minor Changes
+
+- 567dbe1: Add new `delayReturnFocus` option (default true) to control whether return focus and onPostDeactivate are deferred by one frame (#1689).
+
+### Patch Changes
+
+- b70e8d9: Fix bug where removing the ancestor of a focused node within a trap would result in focus landing on the body instead of remaining in the trap (#1660).
+
+## 8.1.0
+
+### Minor Changes
+
+- 642f7f2: Update lifecycle hooks to include the associated focus trap as a parameter.
+
 ## 8.0.1
 
 ### Patch Changes

package/README.md

@@ -94,7 +94,7 @@ Returns a new focus trap on `element` (one or more "containers" of tabbable node
 ##### onActivate
 
 ```typescript
-() => void
+(params: LifecycleParameters) => void
 ```
 
 A function that will be called **before** sending focus to the target element upon activation.
@@ -102,7 +102,7 @@ A function that will be called **before** sending focus to the target element up
 ##### onPostActivate
 
 ```typescript
-() => void
+(params: LifecycleParameters) => void
 ```
 
 A function that will be called **after** sending focus to the target element upon activation **unless** initial focus is delayed because the  [delayInitialFocus](#delayinitialfocus) is true (default).
@@ -110,7 +110,7 @@ A function that will be called **after** sending focus to the target element upo
 ##### onPause
 
 ```typescript
-() => void
+(params: LifecycleParameters) => void
 ```
 
 A function that will be called immediately after the trap's state is updated to be paused.
@@ -118,7 +118,7 @@ A function that will be called immediately after the trap's state is updated to
 ##### onPostPause
 
 ```typescript
-() => void
+(params: LifecycleParameters) => void
 ```
 
 A function that will be called after the trap has been completely paused and is no longer managing/trapping focus.
@@ -126,7 +126,7 @@ A function that will be called after the trap has been completely paused and is
 ##### onUnpause
 
 ```typescript
-() => void
+(params: LifecycleParameters) => void
 ```
 
 A function that will be called immediately after the trap's state is updated to be active again, but prior to updating its knowledge of what nodes are tabbable within its containers, and prior to actively managing/trapping focus.
@@ -134,7 +134,7 @@ A function that will be called immediately after the trap's state is updated to
 ##### onPostUnpause
 
 ```typescript
-() => void
+(params: LifecycleParameters) => void
 ```
 
 A function that will be called after the trap has been completely unpaused and is once again managing/trapping focus.
@@ -150,11 +150,12 @@ Note that if [delayInitialFocus](#delayinitialfocus) is true, this handler will
 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).
 
 🔺 It does not matter whether the Promise resolves or rejects, only that it settles. A rejected Promise will not result in cancellation of trap activation.
+🔺 This controls **when activation may proceed**. The separate [delayInitialFocus](#delayinitialfocus) option controls whether there is an additional one-frame delay before focus is sent once activation can proceed.
 
 ##### onDeactivate
 
 ```typescript
-() => void
+(params: LifecycleParameters) => 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.
@@ -162,11 +163,13 @@ A function that will be called **before** returning focus to the node that had f
 ##### onPostDeactivate
 
 ```typescript
-() => void
+(params: LifecycleParameters) => 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.
 
+By default, this callback is delayed by one frame along with return-focus timing; set [delayReturnFocus](#delayreturnfocus) to `false` to remove that extra delay.
+
 ##### checkCanReturnFocus
 
 ```typescript
@@ -175,6 +178,8 @@ A function that will be called after the trap is deactivated, after `onDeactivat
 
 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).
 
+🔺 If [delayReturnFocus](#delayreturnfocus) is `true` (default), there is still an additional one-frame delay after this Promise settles before focus is returned and `onPostDeactivate` is called.
+
 ##### initialFocus
 
 ```typescript
@@ -272,6 +277,19 @@ 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.
 
 🔺 Note that when this option is `true` (default), it means the initial element to be focused will not be focused until **after** [onPostActivate](#onpostactivate) or [onPostUnpause](#onpostunpause) are called.
+🔺 This option controls the extra frame delay on activation. Use [checkCanFocusTrap](#checkcanfocustrap) to gate activation readiness, and [delayReturnFocus](#delayreturnfocus) plus [checkCanReturnFocus](#checkcanreturnfocus) for the equivalent deactivation timing controls.
+
+##### delayReturnFocus
+
+```typescript
+boolean
+```
+
+Default: `true`. Delays return-focus to the next execution frame when the focus trap is deactivated.
+
+- This same delay also applies to [onPostDeactivate](#onpostdeactivate).
+- Set to `false` to skip the extra frame delay.
+- If [checkCanReturnFocus](#checkcanreturnfocus) is configured, that Promise must still settle first.
 
 ##### isolateSubtrees
 
@@ -389,8 +407,8 @@ Returns the `trap`.
 
 These options are used to override the focus trap's default behavior for this particular activation.
 
-- **onActivate** `{() => void}`: Default: whatever you chose for `createOptions.onActivate`. `null` or `false` are the equivalent of a `noop`.
-- **onPostActivate** `{() => void}`: Default: whatever you chose for `createOptions.onPostActivate`. `null` or `false` are the equivalent of a `noop`.
+- **onActivate** `{(params: LifecycleParameters) => void}`: Default: whatever you chose for `createOptions.onActivate`. `null` or `false` are the equivalent of a `noop`.
+- **onPostActivate** `{(params: LifecycleParameters) => void}`: Default: whatever you chose for `createOptions.onPostActivate`. `null` or `false` are the equivalent of a `noop`.
 - **checkCanFocusTrap** `{(containers: Array<HTMLElement | SVGElement>) => Promise<unknown>}`: Default: whatever you chose for `createOptions.checkCanFocusTrap`.
 
 ### trap.deactivate()
@@ -408,9 +426,9 @@ Returns the `trap`.
 These options are used to override the focus trap's default behavior for this particular deactivation.
 
 - **returnFocus** `{boolean}`: Default: whatever you set 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 set for `createOptions.onDeactivate`. `null` or `false` are the equivalent of a `noop`.
-- **onPostDeactivate** `{() => void}`: Default: whatever you set for `createOptions.onPostDeactivate`. `null` or `false` are the equivalent of a `noop`.
-- **checkCanReturnFocus** `{(trigger: HTMLElement | SVGElement) => Promise<void>}`: Default: whatever you set 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.
+- **onDeactivate** `{(params: LifecycleParameters) => void}`: Default: whatever you set for `createOptions.onDeactivate`. `null` or `false` are the equivalent of a `noop`.
+- **onPostDeactivate** `{(params: LifecycleParameters) => void}`: Default: whatever you set for `createOptions.onPostDeactivate`. `null` or `false` are the equivalent of a `noop`.
+- **checkCanReturnFocus** `{(trigger: HTMLElement | SVGElement) => Promise<void>}`: Default: whatever you set 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. After this Promise settles, `createOptions.delayReturnFocus` determines whether return-focus and `onPostDeactivate` are immediate (`false`) or delayed by one frame (`true`, default).
 
 ### trap.pause()
 
@@ -436,8 +454,8 @@ This is useful in various cases, one of which is when you want one focus trap wi
 
 These options are used to override the focus trap's default behavior for this particular pausing.
 
-- **onPause** `{() => void}`: Default: whatever you chose for `createOptions.onPause`. `null` or `false` are the equivalent of a `noop`.
-- **onPostPause** `{() => void}`: Default: whatever you chose for `createOptions.onPostPause`. `null` or `false` are the equivalent of a `noop`.
+- **onPause** `{(params: LifecycleParameters) => void}`: Default: whatever you chose for `createOptions.onPause`. `null` or `false` are the equivalent of a `noop`.
+- **onPostPause** `{(params: LifecycleParameters) => void}`: Default: whatever you chose for `createOptions.onPostPause`. `null` or `false` are the equivalent of a `noop`.
 
 ### trap.unpause()
 
@@ -461,8 +479,8 @@ Returns the `trap`.
 
 These options are used to override the focus trap's default behavior for this particular unpausing.
 
-- **onUnpause** `{() => void}`: Default: whatever you chose for `createOptions.onUnpause`. `null` or `false` are the equivalent of a `noop`.
-- **onPostUnpause** `{() => void}`: Default: whatever you chose for `createOptions.onPostUnpause`. `null` or `false` are the equivalent of a `noop`.
+- **onUnpause** `{(params: LifecycleParameters) => void}`: Default: whatever you chose for `createOptions.onUnpause`. `null` or `false` are the equivalent of a `noop`.
+- **onPostUnpause** `{(params: LifecycleParameters) => void}`: Default: whatever you chose for `createOptions.onPostUnpause`. `null` or `false` are the equivalent of a `noop`.
 
 ### trap.updateContainerElements()
 

package/dist/focus-trap.esm.js

@@ -1,8 +1,8 @@
 /*!
-* focus-trap 8.0.1
+* focus-trap 8.2.0
 * @license MIT, https://github.com/focus-trap/focus-trap/blob/master/LICENSE
 */
-import { isFocusable, tabbable, focusable, isTabbable, getTabIndex } from 'tabbable';
+import { tabbable, focusable, isTabbable, getTabIndex, isFocusable } from 'tabbable';
 
 function _arrayLikeToArray(r, a) {
   (null == a || a > r.length) && (a = r.length);
@@ -356,6 +356,7 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
     returnFocusOnDeactivate: true,
     escapeDeactivates: true,
     delayInitialFocus: true,
+    delayReturnFocus: true,
     isolateSubtrees: false,
     isKeyForward: isKeyForward,
     isKeyBackward: isKeyBackward
@@ -1102,17 +1103,27 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
   //
 
   var checkDomRemoval = function checkDomRemoval(mutations) {
+    var focusedNode = state.mostRecentlyFocusedNode;
+    if (!focusedNode) {
+      return;
+    }
     var isFocusedNodeRemoved = mutations.some(function (mutation) {
       var removedNodes = Array.from(mutation.removedNodes);
       return removedNodes.some(function (node) {
-        return node === state.mostRecentlyFocusedNode;
+        return node === focusedNode || typeof node.contains === 'function' && node.contains(focusedNode);
       });
     });
 
-    // If the currently focused is removed then browsers will move focus to the
+    // If the currently focused node is removed then browsers will move focus to the
     // <body> element. If this happens, try to move focus back into the trap.
-    if (isFocusedNodeRemoved) {
-      _tryFocus(getInitialFocusNode());
+    if (isFocusedNodeRemoved && state.containers.some(function (container) {
+      return container === null || container === void 0 ? void 0 : container.isConnected;
+    })) {
+      // Refresh tabbable state before resolving initial focus because
+      // getInitialFocusNode() may fall back to the first tabbable node in the trap.
+      updateTabbableNodes();
+      var initialFocusNode = getInitialFocusNode();
+      _tryFocus(initialFocusNode);
     }
   };
 
@@ -1172,7 +1183,9 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
         state.active = true;
         state.paused = false;
         state.nodeFocusedBeforeActivation = _getActiveElement(doc);
-        onActivate === null || onActivate === void 0 || onActivate();
+        onActivate === null || onActivate === void 0 || onActivate({
+          trap: trap
+        });
         var finishActivation = /*#__PURE__*/function () {
           var _ref6 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
             return _regenerator().w(function (_context) {
@@ -1192,7 +1205,9 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
                 case 1:
                   trap._setSubtreeIsolation(true);
                   updateObservedNodes();
-                  onPostActivate === null || onPostActivate === void 0 || onPostActivate();
+                  onPostActivate === null || onPostActivate === void 0 || onPostActivate({
+                    trap: trap
+                  });
                 case 2:
                   return _context.a(2);
               }
@@ -1249,16 +1264,26 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
       var onDeactivate = getOption(options, 'onDeactivate');
       var onPostDeactivate = getOption(options, 'onPostDeactivate');
       var checkCanReturnFocus = getOption(options, 'checkCanReturnFocus');
+      var delayReturnFocus = getOption(options, 'delayReturnFocus');
       var returnFocus = getOption(options, 'returnFocus', 'returnFocusOnDeactivate');
-      onDeactivate === null || onDeactivate === void 0 || onDeactivate();
-      var finishDeactivation = function finishDeactivation() {
-        delay(function () {
-          if (returnFocus) {
-            _tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
-          }
-          onPostDeactivate === null || onPostDeactivate === void 0 || onPostDeactivate();
+      onDeactivate === null || onDeactivate === void 0 || onDeactivate({
+        trap: trap
+      });
+      var completeDeactivation = function completeDeactivation() {
+        if (returnFocus) {
+          _tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
+        }
+        onPostDeactivate === null || onPostDeactivate === void 0 || onPostDeactivate({
+          trap: trap
         });
       };
+      var finishDeactivation = function finishDeactivation() {
+        if (delayReturnFocus && returnFocus) {
+          delay(completeDeactivation);
+        } else {
+          completeDeactivation();
+        }
+      };
       if (returnFocus && checkCanReturnFocus) {
         checkCanReturnFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation)).then(finishDeactivation, finishDeactivation);
         return this;
@@ -1316,15 +1341,21 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
         if (paused) {
           var onPause = getOption(options, 'onPause');
           var onPostPause = getOption(options, 'onPostPause');
-          onPause === null || onPause === void 0 || onPause();
+          onPause === null || onPause === void 0 || onPause({
+            trap: trap
+          });
           removeListeners();
           trap._setSubtreeIsolation(false);
           updateObservedNodes();
-          onPostPause === null || onPostPause === void 0 || onPostPause();
+          onPostPause === null || onPostPause === void 0 || onPostPause({
+            trap: trap
+          });
         } else {
           var onUnpause = getOption(options, 'onUnpause');
           var onPostUnpause = getOption(options, 'onPostUnpause');
-          onUnpause === null || onUnpause === void 0 || onUnpause();
+          onUnpause === null || onUnpause === void 0 || onUnpause({
+            trap: trap
+          });
           var finishUnpause = /*#__PURE__*/function () {
             var _ref7 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
               return _regenerator().w(function (_context2) {
@@ -1342,7 +1373,9 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
                   case 1:
                     trap._setSubtreeIsolation(true);
                     updateObservedNodes();
-                    onPostUnpause === null || onPostUnpause === void 0 || onPostUnpause();
+                    onPostUnpause === null || onPostUnpause === void 0 || onPostUnpause({
+                      trap: trap
+                    });
                   case 2:
                     return _context2.a(2);
                 }