feat: support focusOptions, fixes #162

Author: theKashey

interfaces.d.ts

@@ -14,6 +14,19 @@ export interface ReactFocusLockProps<ChildrenType = React.ReactNode, LockProps=R
    */
   returnFocus?: boolean | FocusOptions | ((returnTo: Element)=> boolean | FocusOptions);
 
+  /**
+   * used to control behavior or "returning focus back to the lock"
+   *
+   * @deprecated Can lead to a wrong user experience. Use this option only if you known what you are doing
+   * @see {@link https://github.com/theKashey/react-focus-lock/issues/162}
+   * @example
+   * prevent scroll example
+   * ```tsx
+   * <FocusLock focusOptions={{preventScroll: true}} />
+   * ```
+   */
+  focusOptions?: FocusOptions;
+
   /**
    * @deprecated Use persistentFocus=false instead
    * enables(or disables) text selection. This also allows not to have ANY focus.

src/Lock.js

@@ -34,6 +34,7 @@ const FocusLock = React.forwardRef(function FocusLockUI(props, parentRef) {
     sideCar: SideCar,
 
     returnFocus: shouldReturnFocus,
+    focusOptions,
 
     onActivation: onActivationCallback,
     onDeactivation: onDeactivationCallback,
@@ -73,15 +74,15 @@ const FocusLock = React.forwardRef(function FocusLockUI(props, parentRef) {
     if (returnFocusTo && returnFocusTo.focus) {
       const howToReturnFocus = typeof shouldReturnFocus === 'function' ? shouldReturnFocus(returnFocusTo) : shouldReturnFocus;
       if (Boolean(howToReturnFocus)) {
-        const focusOptions = typeof howToReturnFocus === 'object' ? howToReturnFocus : undefined;
+        const returnFocusOptions = typeof howToReturnFocus === 'object' ? howToReturnFocus : undefined;
         originalFocusedElement.current = null;
 
         if (allowDefer) {
           // React might return focus after update
           // it's safer to defer the action
-          Promise.resolve().then(() => returnFocusTo.focus(focusOptions));
+          Promise.resolve().then(() => returnFocusTo.focus(returnFocusOptions));
         } else {
-          returnFocusTo.focus(focusOptions);
+          returnFocusTo.focus(returnFocusOptions);
         }
       }
     }
@@ -152,6 +153,7 @@ const FocusLock = React.forwardRef(function FocusLockUI(props, parentRef) {
           onActivation={onActivation}
           onDeactivation={onDeactivation}
           returnFocus={returnFocus}
+          focusOptions={focusOptions}
         />
       )}
       <Container
@@ -174,7 +176,8 @@ const FocusLock = React.forwardRef(function FocusLockUI(props, parentRef) {
 FocusLock.propTypes = {
   children: node,
   disabled: bool,
-  returnFocus: oneOfType([bool, object]),
+  returnFocus: oneOfType([bool, object, func]),
+  focusOptions: object,
   noFocusGuards: bool,
 
   allowTextSelection: bool,
@@ -201,6 +204,7 @@ FocusLock.defaultProps = {
   children: undefined,
   disabled: false,
   returnFocus: false,
+  focusOptions: undefined,
   noFocusGuards: false,
   autoFocus: true,
   persistentFocus: false,

src/Trap.js

@@ -71,7 +71,7 @@ const activateTrap = () => {
   let result = false;
   if (lastActiveTrap) {
     const {
-      observed, persistentFocus, autoFocus, shards, crossFrame,
+      observed, persistentFocus, autoFocus, shards, crossFrame, focusOptions,
     } = lastActiveTrap;
     const workingNode = observed || (lastPortaledElement && lastPortaledElement.portaledElement);
     const activeElement = document && document.activeElement;
@@ -101,7 +101,7 @@ const activateTrap = () => {
               }
               document.body.focus();
             } else {
-              result = moveFocusInside(workingArea, lastActiveFocus);
+              result = moveFocusInside(workingArea, lastActiveFocus, {focusOptions});
               lastPortaledElement = {};
             }
           }