refactor!: configure full window overlay globally to address exit animation issues (#125)

BREAKING CHANGE: Removes individual `fullWindowOverlay` config from
`magicModal.show`. Introduces `magicModal.enableFullWindowOverlay()` and
`magicModal.disableFullWindowOverlay()` in order to control overlay
behavior globally. This fixes exit animations on iOS.

Author: GSTJ

README.md

@@ -227,9 +227,9 @@ If your use-case is a scrollable bottom-sheet, I recommend going with Gorhom's r
 **Q:** Modals are appearing on top of native modal screens, such as the image picker. How can I fix this?
 
 **A:**
-This behavior can be disabled by passing `fullWindowOverlay: false` to the `magicModal.show` function.
+This behavior can be disabled by calling `magicModal.disableFullWindowOverlay()` before showing the modal. This will prevent the modal from appearing on top of native modal screens.
 
-This will prevent the modal from appearing on top of native modal screens.
+You can also call `magicModal.enableFullWindowOverlay()` to re-enable it.
 
 ## Contributors
 

examples/kitchen-sink/src/app/index.tsx

@@ -84,9 +84,9 @@ const showZoomInModal = async () => {
 };
 
 const showNoFullWindowOverlayModal = async () => {
-  magicModal.show(() => <ExampleModal />, {
-    fullWindowOverlay: false,
-  });
+  magicModal.disableFullWindowOverlay();
+  await magicModal.show(() => <ExampleModal />).promise;
+  magicModal.enableFullWindowOverlay();
 };
 
 export default () => {

packages/modal/src/components/MagicModal.tsx

@@ -1,11 +1,5 @@
 import React, { memo, useMemo } from "react";
-import {
-  Platform,
-  Pressable,
-  StyleSheet,
-  useWindowDimensions,
-  View,
-} from "react-native";
+import { Pressable, StyleSheet, useWindowDimensions, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import Animated, {
   Extrapolation,
@@ -25,8 +19,6 @@ import Animated, {
   useSharedValue,
   withSpring,
 } from "react-native-reanimated";
-/** Do not import FullWindowOverlay from react-native-screens directly, as it screws up code splitting */
-import FullWindowOverlay from "react-native-screens/src/components/FullWindowOverlay";
 
 import { defaultDirection } from "../constants/defaultConfig";
 import {
@@ -69,11 +61,6 @@ export const MagicModal = memo(
     const prevTranslationX = useSharedValue(0);
     const prevTranslationY = useSharedValue(0);
 
-    const Overlay =
-      config.fullWindowOverlay && Platform.OS === "ios"
-        ? FullWindowOverlay
-        : React.Fragment;
-
     /**
      * Necessary to skip exit animation when swipe is complete.
      * This is a problem on web, where the exit animation does not
@@ -228,74 +215,64 @@ export const MagicModal = memo(
     const isBackdropVisible = !config.hideBackdrop;
 
     return (
-      <Overlay>
-        <View style={[StyleSheet.absoluteFill, styles.pointerEventsBoxNone]}>
-          <Animated.View
-            pointerEvents={isBackdropVisible ? "auto" : "none"}
-            entering={FadeIn.duration(config.animationInTiming)}
-            exiting={FadeOut.duration(config.animationOutTiming)}
-            style={styles.backdropContainer}
-          >
-            <AnimatedPressable
-              testID="magic-modal-backdrop"
-              style={[
-                styles.backdrop,
-                animatedBackdropStyles,
-                {
-                  backgroundColor: isBackdropVisible
-                    ? config.backdropColor
-                    : "transparent",
-                },
-              ]}
-              onPress={onBackdropPress}
-            />
-          </Animated.View>
-          <Animated.View
+      <View style={[StyleSheet.absoluteFill, styles.pointerEventsBoxNone]}>
+        <Animated.View
+          pointerEvents={isBackdropVisible ? "auto" : "none"}
+          entering={FadeIn.duration(config.animationInTiming)}
+          exiting={FadeOut.duration(config.animationOutTiming)}
+          style={styles.backdropContainer}
+        >
+          <AnimatedPressable
+            testID="magic-modal-backdrop"
             style={[
-              styles.overlay,
-              styles.pointerEventsBoxNone,
-              animatedStyles,
+              styles.backdrop,
+              animatedBackdropStyles,
+              {
+                backgroundColor: isBackdropVisible
+                  ? config.backdropColor
+                  : "transparent",
+              },
             ]}
+            onPress={onBackdropPress}
+          />
+        </Animated.View>
+        <Animated.View
+          style={[styles.overlay, styles.pointerEventsBoxNone, animatedStyles]}
+        >
+          <Animated.View
+            style={[styles.overlay, styles.pointerEventsBoxNone, config.style]}
+            entering={
+              !isSwipeComplete
+                ? (config.entering ??
+                  defaultAnimationInMap[
+                    config.swipeDirection ?? defaultDirection
+                  ].duration(config.animationInTiming))
+                : undefined
+            }
+            exiting={
+              !isSwipeComplete
+                ? (config.exiting ??
+                  defaultAnimationOutMap[
+                    config.swipeDirection ?? defaultDirection
+                  ].duration(config.animationOutTiming))
+                : undefined
+            }
           >
-            <Animated.View
-              style={[
-                styles.overlay,
-                styles.pointerEventsBoxNone,
-                config.style,
-              ]}
-              entering={
-                !isSwipeComplete
-                  ? (config.entering ??
-                    defaultAnimationInMap[
-                      config.swipeDirection ?? defaultDirection
-                    ].duration(config.animationInTiming))
-                  : undefined
-              }
-              exiting={
-                !isSwipeComplete
-                  ? (config.exiting ??
-                    defaultAnimationOutMap[
-                      config.swipeDirection ?? defaultDirection
-                    ].duration(config.animationOutTiming))
-                  : undefined
-              }
-            >
-              <GestureDetector gesture={pan}>
-                <View
-                  collapsable={false}
-                  style={[
-                    styles.childrenWrapper,
-                    styles.pointerEventsBoxNone,
-                    config.style,
-                  ]}
-                >
-                  <Children />
-                </View>
-              </GestureDetector>
-            </Animated.View>
+            <GestureDetector gesture={pan}>
+              <View
+                collapsable={false}
+                style={[
+                  styles.childrenWrapper,
+                  styles.pointerEventsBoxNone,
+                  config.style,
+                ]}
+              >
+                <Children />
+              </View>
+            </GestureDetector>
           </Animated.View>
-        </View>
-      </Overlay>
+        </Animated.View>
+      </View>
     );
   },
 );

packages/modal/src/components/MagicModalPortal/MagicModalPortal.tsx

@@ -5,7 +5,9 @@ import React, {
   useImperativeHandle,
   useMemo,
 } from "react";
-import { BackHandler, StyleSheet, View } from "react-native";
+import { BackHandler, Platform, StyleSheet, View } from "react-native";
+/** Do not import FullWindowOverlay from react-native-screens directly, as it screws up code splitting */
+import FullWindowOverlay from "react-native-screens/src/components/FullWindowOverlay";
 
 import { defaultConfig } from "../../constants/defaultConfig";
 import {
@@ -47,6 +49,16 @@ type ModalStackItem = {
  */
 export const MagicModalPortal: React.FC = memo(() => {
   const [modals, setModals] = React.useState<ModalStackItem[]>([]);
+  const [fullWindowOverlayEnabled, setFullWindowOverlayEnabled] =
+    React.useState(true);
+
+  const disableFullWindowOverlay = useCallback(() => {
+    setFullWindowOverlayEnabled(false);
+  }, []);
+
+  const enableFullWindowOverlay = useCallback(() => {
+    setFullWindowOverlayEnabled(true);
+  }, []);
 
   const _hide = useCallback<GlobalHideFunction>(
     async (props, { modalID } = {}) => {
@@ -162,6 +174,8 @@ export const MagicModalPortal: React.FC = memo(() => {
     show,
     hide,
     hideAll,
+    disableFullWindowOverlay,
+    enableFullWindowOverlay,
   }));
 
   const modalList = useMemo(() => {
@@ -174,11 +188,22 @@ export const MagicModalPortal: React.FC = memo(() => {
     });
   }, [modals]);
 
+  const Overlay =
+    fullWindowOverlayEnabled && Platform.OS === "ios"
+      ? FullWindowOverlay
+      : React.Fragment;
+
   /* This needs to always be rendered, if we make it conditionally render based on ModalContent too,
      the modal will have zIndex issues on react-navigation modals. */
   return (
-    <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
-      {modalList}
-    </View>
+    <Overlay>
+      <View style={[StyleSheet.absoluteFill, styles.wrapper]}>{modalList}</View>
+    </Overlay>
   );
 });
+
+const styles = StyleSheet.create({
+  wrapper: {
+    pointerEvents: "box-none",
+  },
+});

packages/modal/src/constants/defaultConfig.ts

@@ -13,6 +13,5 @@ export const defaultConfig: ModalProps = {
   swipeVelocityThreshold: 500,
   onBackButtonPress: undefined,
   onBackdropPress: undefined,
-  fullWindowOverlay: true,
   style: {},
 } satisfies ModalProps;

packages/modal/src/constants/types.ts

@@ -39,13 +39,6 @@ export type ModalProps = {
    */
   backdropColor: string;
 
-  /**
-   * If true, the modal will be displayed as a full window overlay on top of native iOS modal screens.
-   * @default true
-   * @platform ios
-   */
-  fullWindowOverlay: boolean;
-
   /**
    * Function to be called when the back button is pressed.
    * You can override it to prevent the modal from closing on back button press.
@@ -102,6 +95,10 @@ export type GlobalHideFunction = <T>(
 
 export type GlobalHideAllFunction = () => void;
 
+export type EnableFullWindowOverlayFunction = () => void;
+
+export type DisableFullWindowOverlayFunction = () => void;
+
 export type HookHideFunction = <T>(props: HideReturn<T>) => void;
 
 export type NewConfigProps = Partial<ModalProps>;

packages/modal/src/utils/magicModalHandler.ts

@@ -1,6 +1,8 @@
 import React from "react";
 
 import {
+  DisableFullWindowOverlayFunction,
+  EnableFullWindowOverlayFunction,
   GlobalHideAllFunction,
   GlobalHideFunction,
   GlobalShowFunction,
@@ -28,6 +30,14 @@ const hide: GlobalHideFunction = (props, { modalID } = {}) => {
   return getMagicModal().hide(props, { modalID });
 };
 
+const enableFullWindowOverlay: EnableFullWindowOverlayFunction = () => {
+  return getMagicModal().enableFullWindowOverlay();
+};
+
+const disableFullWindowOverlay: DisableFullWindowOverlayFunction = () => {
+  return getMagicModal().disableFullWindowOverlay();
+};
+
 const hideAll: GlobalHideAllFunction = () => {
   // We recommend using this method in jest, and having throw because the ref was not found isn't useful there.
   // Not all tests are necessarily using the provider.
@@ -37,6 +47,8 @@ export interface IModal {
   show: typeof show;
   hide: typeof hide;
   hideAll: typeof hideAll;
+  enableFullWindowOverlay: typeof enableFullWindowOverlay;
+  disableFullWindowOverlay: typeof disableFullWindowOverlay;
 }
 
 /**
@@ -76,4 +88,26 @@ export const magicModal = {
    * However, this function can be useful in edge cases. It's also useful for test suites, such as calling hideAll in Jest's beforeEach function as a cleanup step.
    */
   hideAll,
+  /**
+   * @description Enables the full window overlay globally. This is useful for modals that need to be displayed on top of native iOS modal screens. The function is no-op on non-iOS platforms.
+   * @example
+   * ```js
+   * magicModal.disableFullWindowOverlay();
+   * await magicModal.show(() => <ExampleModal />).promise;
+   * magicModal.enableFullWindowOverlay();
+   * ```
+   * @platform ios
+   */
+  enableFullWindowOverlay,
+  /**
+   * @description Disables the full window overlay globally. This is useful for modals that do not need to be displayed on top of native iOS modal screens. The function is no-op on non-iOS platforms.
+   * @example
+   * ```js
+   * magicModal.disableFullWindowOverlay();
+   * await magicModal.show(() => <ExampleModal />).promise;
+   * magicModal.enableFullWindowOverlay();
+   * ```
+   * @platform ios
+   */
+  disableFullWindowOverlay,
 };