@react-navigation/stack 8.0.0-alpha.2 → 8.0.0-alpha.21

package/src/types.tsx

@@ -1,9 +1,9 @@
 import type {
-  HeaderBackButton,
   HeaderBackButtonDisplayMode,
   HeaderBackButtonProps,
   HeaderOptions,
   HeaderTitleProps,
+  Icon,
 } from '@react-navigation/elements';
 import type {
   DefaultNavigatorOptions,
@@ -138,12 +138,12 @@ export type SceneProgress = {
    * Progress value for the screen after this one in the stack.
    * This can be `undefined` in case the screen animating is the last one.
    */
-  next?: Animated.AnimatedInterpolation<number>;
+  next?: Animated.AnimatedInterpolation<number> | undefined;
   /**
    * Progress value for the screen before this one in the stack.
    * This can be `undefined` in case the screen animating is the first one.
    */
-  previous?: Animated.AnimatedInterpolation<number>;
+  previous?: Animated.AnimatedInterpolation<number> | undefined;
 };
 
 export type StackHeaderMode = 'float' | 'screen';
@@ -187,14 +187,14 @@ export type StackHeaderOptions = Omit<
    * Defaults to the previous screen's title, or "Back" if there's not enough space.
    * Use `headerBackButtonDisplayMode` to customize the behavior.
    */
-  headerBackTitle?: string;
+  headerBackTitle?: string | undefined;
   /**
    * Title string used by the back button when `headerBackTitle` doesn't fit on the screen.
    * Use `headerBackButtonDisplayMode` to customize the behavior.
    *
    * Defaults to "Back".
    */
-  headerBackTruncatedTitle?: string;
+  headerBackTruncatedTitle?: string | undefined;
   /**
    * How the back button displays icon and title.
    *
@@ -211,27 +211,47 @@ export type StackHeaderOptions = Omit<
    */
   headerBackTitleStyle?: StyleProp<TextStyle>;
   /**
-   * Function which returns a React Element to display custom image in header's back button.
-   * It receives the `tintColor` in in the options object as an argument. object.
-   * Defaults to Image component with a the default back icon image for the platform (a chevron on iOS and an arrow on Android).
-   */
-  headerBackImage?: React.ComponentProps<typeof HeaderBackButton>['backImage'];
+   * Icon to display in the header in the back button.
+   *
+   * Supported types:
+   * - image: custom image source
+   * - sfSymbol: SF Symbol icon (iOS only)
+   * - materialSymbol: material symbol icon (Android only)
+   * - React Node: function that returns a React Element
+   *
+   * Defaults to back icon image for the platform
+   * - A chevron on iOS
+   * - An arrow on Android
+   *
+   * @example
+   * ```js
+   * headerBackIcon: {
+   *   type: 'image',
+   *   source: require('./back-icon.png'),
+   * }
+   * ```
+   */
+  headerBackIcon?:
+    | Icon
+    | ((props: { tintColor: ColorValue | undefined }) => React.ReactNode);
 };
 
 export type StackHeaderProps = {
   /**
    * Options for the back button.
    */
-  back?: {
-    /**
-     * Title of the previous screen.
-     */
-    title: string | undefined;
-    /**
-     * The `href` to use for the anchor tag on web
-     */
-    href: string | undefined;
-  };
+  back?:
+    | {
+        /**
+         * Title of the previous screen.
+         */
+        title: string | undefined;
+        /**
+         * The `href` to use for the anchor tag on web
+         */
+        href: string | undefined;
+      }
+    | undefined;
   /**
    * Animated nodes representing the progress of the animation.
    */
@@ -258,26 +278,26 @@ export type StackHeaderRightProps = {
   /**
    * Tint color for the header button.
    */
-  tintColor?: ColorValue;
+  tintColor?: ColorValue | undefined;
   /**
    * Color for material ripple (Android >= 5.0 only).
    */
-  pressColor?: ColorValue;
+  pressColor?: ColorValue | undefined;
   /**
    * Opacity when the button is pressed, used when ripple is not supported.
    */
-  pressOpacity?: number;
+  pressOpacity?: number | undefined;
   /**
    * Whether it's possible to navigate back in stack.
    */
-  canGoBack?: boolean;
+  canGoBack?: boolean | undefined;
 };
 
 export type StackHeaderLeftProps = HeaderBackButtonProps & {
   /**
    * Whether it's possible to navigate back in stack.
    */
-  canGoBack?: boolean;
+  canGoBack?: boolean | undefined;
 };
 
 export type StackDescriptor = Descriptor<
@@ -330,9 +350,6 @@ export type StackNavigationOptions = StackHeaderOptions &
      * You can also specify `{ backgroundColor: 'transparent' }` to make the previous screen visible underneath.
      * This is useful to implement things like modal dialogs.
      *
-     * You should also specify `detachPreviousScreen: false` in options when using a transparent background
-     * so that the previous screen isn't detached and stays below the current screen.
-     *
      * You might also need to change the animation of the screen using `cardStyleInterpolator`
      * so that the previous screen isn't transformed or invisible.
      */
@@ -348,7 +365,6 @@ export type StackNavigationOptions = StackHeaderOptions &
      * - `transparentModal`: Similar to `modal`. This changes following things:
      *   - Sets `headerMode` to `screen` for the screen unless specified otherwise.
      *   - Sets background color of the screen to transparent, so previous screen is visible
-     *   - Adjusts the `detachPreviousScreen` option so that the previous screen stays rendered.
      *   - Prevents the previous screen from animating from its last position.
      *   - Changes the screen animation to a vertical slide animation.
      *
@@ -390,43 +406,29 @@ export type StackNavigationOptions = StackHeaderOptions &
      * Not supported on Web.
      */
     gestureVelocityImpact?: number;
-    /**
-     * Whether to detach the previous screen from the view hierarchy to save memory.
-     * Set it to `false` if you need the previous screen to be seen through the active screen.
-     * Only applicable if `detachInactiveScreens` isn't set to `false`.
-     * Defaults to `false` for the last screen for modals, otherwise `true`.
-     */
-    detachPreviousScreen?: boolean;
     /**
      * If `false`, the keyboard will NOT automatically dismiss when navigating to a new screen from this screen.
      * Defaults to `true`.
      */
     keyboardHandlingEnabled?: boolean;
+
     /**
-     * Whether inactive screens should be suspended from re-rendering. Defaults to `false`.
-     * Defaults to `true` when `enableFreeze()` is run at the top of the application.
-     * Requires `react-native-screens` version >=3.16.0.
+     * What should happen when screens become inactive.
+     * - `pause`: Effects are cleaned up
+     * - `unmount`: Screen is unmounted
+     * - `none`: Screen renders normally
      *
-     * Only supported on iOS and Android.
-     */
-    freezeOnBlur?: boolean;
-    /**
-     * Whether the home indicator should prefer to stay hidden on this screen. Defaults to `false`.
+     * Defaults to `pause`.
+     *
+     * Preloaded screens won't be paused until after navigated to.
+     * This makes sure that effects are run to initialize the screen.
      *
-     * @platform ios
+     * Screens with nested navigators and last 2 screens won't be unmounted.
      */
-    autoHideHomeIndicator?: boolean;
+    inactiveBehavior?: 'pause' | 'unmount' | 'none' | undefined;
   };
 
-export type StackNavigationConfig = {
-  /**
-   * Whether inactive screens should be detached from the view hierarchy to save memory.
-   * This will have no effect if you disable `react-native-screens`.
-   *
-   * Defaults to `true`.
-   */
-  detachInactiveScreens?: boolean;
-};
+export type StackNavigationConfig = {};
 
 export type TransitionSpec =
   | {
@@ -458,12 +460,14 @@ export type StackCardInterpolationProps = {
    * Values for the screen after this one in the stack.
    * This can be `undefined` in case the screen animating is the last one.
    */
-  next?: {
-    /**
-     * Animated node representing the progress value of the next screen.
-     */
-    progress: Animated.AnimatedInterpolation<number>;
-  };
+  next?:
+    | {
+        /**
+         * Animated node representing the progress value of the next screen.
+         */
+        progress: Animated.AnimatedInterpolation<number>;
+      }
+    | undefined;
   /**
    * The index of the card with this interpolation in the stack.
    */
@@ -537,12 +541,14 @@ export type StackHeaderInterpolationProps = {
    * Values for the screen after this one in the stack.
    * This can be `undefined` in case the screen animating is the last one.
    */
-  next?: {
-    /**
-     * Animated node representing the progress value of the next screen.
-     */
-    progress: Animated.AnimatedInterpolation<number>;
-  };
+  next?:
+    | {
+        /**
+         * Animated node representing the progress value of the next screen.
+         */
+        progress: Animated.AnimatedInterpolation<number>;
+      }
+    | undefined;
   /**
    * Writing direction of the layout.
    */

package/src/utils/gestureActivationCriteria.tsx

@@ -17,7 +17,7 @@ export const gestureActivationCriteria = ({
 }: {
   direction: LocaleDirection;
   gestureDirection: GestureDirection;
-  gestureResponseDistance?: number;
+  gestureResponseDistance?: number | undefined;
   layout: Layout;
 }) => {
   const enableTrackpadTwoFingerGesture = true;

package/src/utils/useCardAnimation.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 import { CardAnimationContext } from './CardAnimationContext';
 
 export function useCardAnimation() {
-  const animation = React.useContext(CardAnimationContext);
+  const animation = React.use(CardAnimationContext);
 
   if (animation === undefined) {
     throw new Error(

package/src/utils/useGestureHandlerRef.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 import { GestureHandlerRefContext } from './GestureHandlerRefContext';
 
 export function useGestureHandlerRef() {
-  const ref = React.useContext(GestureHandlerRefContext);
+  const ref = React.use(GestureHandlerRefContext);
 
   if (ref === undefined) {
     throw new Error(

package/src/utils/useKeyboardManager.tsx

@@ -1,12 +1,20 @@
 import * as React from 'react';
 import { type HostInstance, Keyboard, TextInput } from 'react-native';
 
-export function useKeyboardManager(isEnabled: () => boolean) {
+export function useKeyboardManager({
+  enabled,
+  focused,
+}: {
+  enabled: boolean;
+  focused: boolean;
+}) {
   // Numeric id of the previously focused text input
   // When a gesture didn't change the tab, we can restore the focused input with this
   const previouslyFocusedTextInputRef = React.useRef<HostInstance>(undefined);
   const startTimestampRef = React.useRef<number>(0);
-  const keyboardTimeoutRef = React.useRef<NodeJS.Timeout>(undefined);
+  const keyboardTimeoutRef =
+    React.useRef<ReturnType<typeof setTimeout>>(undefined);
+  const enabledRef = React.useRef(enabled);
 
   const clearKeyboardTimeout = React.useCallback(() => {
     if (keyboardTimeoutRef.current !== undefined) {
@@ -16,7 +24,7 @@ export function useKeyboardManager(isEnabled: () => boolean) {
   }, []);
 
   const onPageChangeStart = React.useCallback(() => {
-    if (!isEnabled()) {
+    if (!enabledRef.current) {
       return;
     }
 
@@ -32,37 +40,10 @@ export function useKeyboardManager(isEnabled: () => boolean) {
 
     // Store timestamp for touch start
     startTimestampRef.current = Date.now();
-  }, [clearKeyboardTimeout, isEnabled]);
-
-  const onPageChangeConfirm = React.useCallback(
-    (force: boolean) => {
-      if (!isEnabled()) {
-        return;
-      }
-
-      clearKeyboardTimeout();
-
-      if (force) {
-        // Always dismiss input, even if we don't have a ref to it
-        // We might not have the ref if onPageChangeStart was never called
-        // This can happen if page change was not from a gesture
-        Keyboard.dismiss();
-      } else {
-        const input = previouslyFocusedTextInputRef.current;
-
-        // Dismiss the keyboard only if an input was a focused before
-        // This makes sure we don't dismiss input on going back and focusing an input
-        input?.blur();
-      }
-
-      // Cleanup the ID on successful page change
-      previouslyFocusedTextInputRef.current = undefined;
-    },
-    [clearKeyboardTimeout, isEnabled]
-  );
+  }, [clearKeyboardTimeout]);
 
   const onPageChangeCancel = React.useCallback(() => {
-    if (!isEnabled()) {
+    if (!enabledRef.current) {
       return;
     }
 
@@ -89,7 +70,60 @@ export function useKeyboardManager(isEnabled: () => boolean) {
         previouslyFocusedTextInputRef.current = undefined;
       }
     }
-  }, [clearKeyboardTimeout, isEnabled]);
+  }, [clearKeyboardTimeout]);
+
+  const onPageChangeConfirm = React.useCallback(
+    ({
+      gesture,
+      active,
+      closing,
+    }: {
+      gesture: boolean;
+      active: boolean;
+      closing: boolean;
+    }) => {
+      if (!enabledRef.current) {
+        return;
+      }
+
+      if (!closing) {
+        onPageChangeCancel();
+        return;
+      }
+
+      clearKeyboardTimeout();
+
+      if (!gesture) {
+        // Always dismiss input, even if we don't have a ref to it
+        // We might not have the ref if onPageChangeStart was never called
+        // This can happen if page change was not from a gesture
+        Keyboard.dismiss();
+      } else if (active) {
+        const input = previouslyFocusedTextInputRef.current;
+
+        // Dismiss the keyboard only if an input was a focused before
+        // This makes sure we don't dismiss input on going back and focusing an input
+        input?.blur();
+      }
+
+      // Cleanup the ID on successful page change
+      previouslyFocusedTextInputRef.current = undefined;
+    },
+    [clearKeyboardTimeout, onPageChangeCancel]
+  );
+
+  // Dismiss keyboard when screen loses focus (e.g. when pushing a new screen).
+  // This handles the "navigate forward" case so we don't dismiss the new screen's
+  // auto-focused input from handleTransition.
+  React.useLayoutEffect(() => {
+    if (enabledRef.current && !focused) {
+      Keyboard.dismiss();
+    }
+  }, [focused]);
+
+  React.useLayoutEffect(() => {
+    enabledRef.current = enabled;
+  });
 
   React.useEffect(() => {
     return () => clearKeyboardTimeout();

package/src/views/Header/Header.tsx

@@ -41,8 +41,8 @@ export const Header = React.memo(function Header({
     [navigation, route.key]
   );
 
-  const isModal = React.useContext(ModalPresentationContext);
-  const isParentHeaderShown = React.useContext(HeaderShownContext);
+  const isModal = React.use(ModalPresentationContext);
+  const isParentHeaderShown = React.use(HeaderShownContext);
 
   const statusBarHeight =
     options.headerStatusBarHeight !== undefined

package/src/views/Header/HeaderContainer.tsx

@@ -1,4 +1,5 @@
 import { getHeaderTitle, HeaderBackContext } from '@react-navigation/elements';
+import { ActivityView } from '@react-navigation/elements/internal';
 import {
   NavigationProvider,
   type ParamListBase,
@@ -43,7 +44,7 @@ export function HeaderContainer({
   style,
 }: Props) {
   const focusedRoute = getFocusedRoute();
-  const parentHeaderBack = React.useContext(HeaderBackContext);
+  const parentHeaderBack = React.use(HeaderBackContext);
   const { buildHref } = useLinkBuilder();
 
   return (
@@ -156,7 +157,6 @@ export function HeaderContainer({
                     }
                   : undefined
               }
-              aria-hidden={!isFocused}
               style={[
                 // Avoid positioning the focused header absolutely
                 // Otherwise accessibility tools don't seem to be able to find it
@@ -168,7 +168,12 @@ export function HeaderContainer({
                 },
               ]}
             >
-              {header !== undefined ? header(props) : <Header {...props} />}
+              <ActivityView
+                mode={isFocused ? 'normal' : 'inert'}
+                visible={true}
+              >
+                {header !== undefined ? header(props) : <Header {...props} />}
+              </ActivityView>
             </View>
           </NavigationProvider>
         );

package/src/views/Header/HeaderSegment.tsx

@@ -20,8 +20,8 @@ type Props = Omit<StackHeaderOptions, 'headerStatusBarHeight'> & {
   headerStatusBarHeight: number;
   title: string;
   modal: boolean;
-  onGoBack?: () => void;
-  backHref?: string;
+  onGoBack?: (() => void) | undefined;
+  backHref?: string | undefined;
   progress: SceneProgress;
   styleInterpolator: StackHeaderStyleInterpolator;
 };
@@ -40,7 +40,7 @@ export function HeaderSegment(props: Props) {
       ? (props: HeaderBackButtonProps) => <HeaderBackButton {...props} />
       : undefined,
     headerRight: right,
-    headerBackImage,
+    headerBackIcon,
     headerBackTitle,
     headerBackButtonDisplayMode,
     headerBackTruncatedTitle,
@@ -93,7 +93,7 @@ export function HeaderSegment(props: Props) {
         left({
           ...props,
           href: backHref,
-          backImage: headerBackImage,
+          icon: headerBackIcon,
           accessibilityLabel: headerBackAccessibilityLabel,
           testID: headerBackTestID,
           allowFontScaling: headerBackAllowFontScaling,

package/src/views/Stack/Card.tsx

@@ -58,7 +58,7 @@ type Props = {
   overlayEnabled: boolean;
   shadowEnabled: boolean | undefined;
   gestureEnabled: boolean;
-  gestureResponseDistance?: number;
+  gestureResponseDistance?: number | undefined;
   gestureVelocityImpact: number | undefined;
   transitionSpec: {
     open: TransitionSpec;
@@ -66,8 +66,8 @@ type Props = {
   };
   preloaded: boolean;
   styleInterpolator: StackCardStyleInterpolator;
-  containerStyle?: StyleProp<ViewStyle>;
-  contentStyle?: StyleProp<ViewStyle>;
+  containerStyle?: StyleProp<ViewStyle> | undefined;
+  contentStyle?: StyleProp<ViewStyle> | undefined;
 };
 
 const GESTURE_VELOCITY_IMPACT = 0.3;
@@ -151,14 +151,14 @@ function Card({
   containerStyle: customContainerStyle,
   contentStyle,
 }: Props) {
-  const [, forceUpdate] = React.useReducer((x) => x + 1, 0);
-
   const didInitiallyAnimate = React.useRef(false);
   const lastToValueRef = React.useRef<number | undefined>(undefined);
 
   const animationHandleRef = React.useRef<number | undefined>(undefined);
   const pendingGestureCallbackRef =
     React.useRef<ReturnType<typeof setTimeout>>(undefined);
+  const pendingOnCloseCallbackRef =
+    React.useRef<ReturnType<typeof setTimeout>>(undefined);
 
   const [isClosing] = React.useState(() => new Animated.Value(FALSE));
 
@@ -218,10 +218,8 @@ function Card({
         }
 
         animationHandleRef.current = requestAnimationFrame(() => {
-          if (didInitiallyAnimate.current) {
-            // Make sure to re-open screen if it wasn't removed
-            forceUpdate();
-          }
+          // Make sure to re-open screen if it wasn't removed
+          maybeAnimate();
         });
       };
 
@@ -249,6 +247,8 @@ function Card({
     ({ nativeEvent }: PanGestureHandlerGestureEvent) => {
       switch (nativeEvent.state) {
         case GestureState.ACTIVE:
+          clearTimeout(pendingGestureCallbackRef.current);
+          clearTimeout(pendingOnCloseCallbackRef.current);
           isSwiping.setValue(TRUE);
           onGestureBegin?.();
           break;
@@ -305,10 +305,13 @@ function Card({
             pendingGestureCallbackRef.current = setTimeout(() => {
               onClose();
 
-              // Trigger an update after we dispatch the action to remove the screen
-              // This will make sure that we check if the screen didn't get removed so we can cancel the animation
-              forceUpdate();
-            }, 32);
+              // Check if the screen is still closing with a delay
+              // So state update from onClose has a chance to go through
+              // If route wasn't removed after onClose, re-open it
+              pendingOnCloseCallbackRef.current = setTimeout(() => {
+                maybeAnimate();
+              }, 32);
+            }, 16);
           }
 
           onGestureEnd?.();
@@ -350,17 +353,15 @@ function Card({
       }
 
       clearTimeout(pendingGestureCallbackRef.current);
+      clearTimeout(pendingOnCloseCallbackRef.current);
     };
-
-    // We only want to clean up the animation on unmount
   }, []);
 
-  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout>>(undefined);
 
-  React.useEffect(() => {
-    if (preloaded) {
-      return;
-    }
+  const maybeAnimate = useLatestCallback(() => {
+    clearTimeout(pendingGestureCallbackRef.current);
+    clearTimeout(pendingOnCloseCallbackRef.current);
 
     if (!didInitiallyAnimate.current) {
       // Animate the card in on initial mount
@@ -368,9 +369,8 @@ function Card({
       // rending of the screen is done. This is especially important
       // in the new architecture
       // cf., https://github.com/react-navigation/react-navigation/issues/12401
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-      }
+      clearTimeout(timeoutRef.current);
+
       timeoutRef.current = setTimeout(() => {
         didInitiallyAnimate.current = true;
         animate({ closing });
@@ -410,6 +410,14 @@ function Card({
         animate({ closing });
       }
     }
+  });
+
+  React.useEffect(() => {
+    if (preloaded) {
+      return;
+    }
+
+    maybeAnimate();
 
     previousPropsRef.current = {
       opening,
@@ -428,6 +436,7 @@ function Card({
     layout,
     opening,
     preloaded,
+    maybeAnimate,
   ]);
 
   const interpolationProps = React.useMemo(

package/src/views/Stack/CardA11yWrapper.tsx

@@ -6,7 +6,6 @@ type Props = {
   active: boolean;
   animated: boolean;
   isNextScreenTransparent: boolean;
-  detachCurrentScreen: boolean;
   children: React.ReactNode;
 };
 
@@ -14,14 +13,7 @@ export type CardA11yWrapperRef = { setInert: (value: boolean) => void };
 
 export const CardA11yWrapper = React.forwardRef(
   (
-    {
-      focused,
-      active,
-      animated,
-      isNextScreenTransparent,
-      detachCurrentScreen,
-      children,
-    }: Props,
+    { focused, active, animated, isNextScreenTransparent, children }: Props,
     ref: React.Ref<CardA11yWrapperRef>
   ) => {
     // Manage this in separate component to avoid re-rendering card during gestures
@@ -30,11 +22,7 @@ export const CardA11yWrapper = React.forwardRef(
 
     React.useImperativeHandle(ref, () => ({ setInert }), []);
 
-    const isHidden =
-      !animated &&
-      isNextScreenTransparent === false &&
-      detachCurrentScreen !== false &&
-      !focused;
+    const isHidden = !animated && isNextScreenTransparent === false && !focused;
 
     return (
       <View