focus-trap 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 8.1.0
+
+### Minor Changes
+
+- 642f7f2: Update lifecycle hooks to include the associated focus trap as a parameter.
+
+## 8.0.1
+
+### Patch Changes
+
+- 7d5010e: Loosen checkCanFocusTrap Promise resolution type to `unknown` to make it easier to use `Promise.all()` or `Promise.allSettled()` as the returned Promise (`Promise<void>` was causing issues because those Promise APIs do not resolve with a `void` value).
+
 ## 8.0.0
 
 ### Major 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.
@@ -144,15 +144,17 @@ Note that if [delayInitialFocus](#delayinitialfocus) is true, this handler will
 ##### checkCanFocusTrap
 
 ```typescript
-(containers: Array<HTMLElement | SVGElement>) => Promise<void>
+(containers: Array<HTMLElement | SVGElement>) => Promise<unknown>
 ```
 
 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.
+
 ##### 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.
@@ -160,7 +162,7 @@ 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.
@@ -387,9 +389,9 @@ 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`.
-- **checkCanFocusTrap** `{(containers: Array<HTMLElement | SVGElement>) => Promise<void>}`: Default: whatever you chose for `createOptions.checkCanFocusTrap`.
+- **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()
 
@@ -406,8 +408,8 @@ 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`.
+- **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.
 
 ### trap.pause()
@@ -434,8 +436,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()
 
@@ -459,8 +461,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,5 +1,5 @@
 /*!
-* focus-trap 8.0.0
+* focus-trap 8.1.0
 * @license MIT, https://github.com/focus-trap/focus-trap/blob/master/LICENSE
 */
 import { isFocusable, tabbable, focusable, isTabbable, getTabIndex } from 'tabbable';
@@ -1172,7 +1172,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 +1194,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);
               }
@@ -1250,13 +1254,17 @@ var createFocusTrap = function createFocusTrap(elements, userOptions) {
       var onPostDeactivate = getOption(options, 'onPostDeactivate');
       var checkCanReturnFocus = getOption(options, 'checkCanReturnFocus');
       var returnFocus = getOption(options, 'returnFocus', 'returnFocusOnDeactivate');
-      onDeactivate === null || onDeactivate === void 0 || onDeactivate();
+      onDeactivate === null || onDeactivate === void 0 || onDeactivate({
+        trap: trap
+      });
       var finishDeactivation = function finishDeactivation() {
         delay(function () {
           if (returnFocus) {
             _tryFocus(getReturnFocusNode(state.nodeFocusedBeforeActivation));
           }
-          onPostDeactivate === null || onPostDeactivate === void 0 || onPostDeactivate();
+          onPostDeactivate === null || onPostDeactivate === void 0 || onPostDeactivate({
+            trap: trap
+          });
         });
       };
       if (returnFocus && checkCanReturnFocus) {
@@ -1316,15 +1324,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 +1356,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);
                 }