@react-navigation/stack 8.0.0-alpha.3 → 8.0.0-alpha.31

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<
@@ -326,15 +346,6 @@ export type StackNavigationOptions = StackHeaderOptions &
     /**
      * Style object for the card in stack.
      * You can provide a custom background color to use instead of the default background here.
-     *
-     * 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.
      */
     cardStyle?: StyleProp<ViewStyle>;
     /**
@@ -348,7 +359,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 +400,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`.
      *
-     * @platform ios
+     * Preloaded screens won't be paused until after navigated to.
+     * This makes sure that effects are run to initialize the screen.
+     *
+     * 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 +454,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 +535,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,
@@ -6,7 +7,13 @@ import {
   useLinkBuilder,
 } from '@react-navigation/native';
 import * as React from 'react';
-import { type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native';
+import {
+  type LayoutChangeEvent,
+  type StyleProp,
+  StyleSheet,
+  View,
+  type ViewStyle,
+} from 'react-native';
 
 import {
   forNoAnimation,
@@ -22,12 +29,18 @@ import type {
 } from '../../types';
 import { Header } from './Header';
 
+export type HeaderHeight = {
+  measured: boolean;
+  value: number;
+};
+
 export type Props = {
   mode: StackHeaderMode;
   scenes: (Scene | undefined)[];
   getPreviousScene: (props: { route: Route<string> }) => Scene | undefined;
   getFocusedRoute: () => Route<string>;
-  onContentHeightChange?: (props: {
+  contentHeight: HeaderHeight | undefined;
+  onContentHeightChange: (props: {
     route: Route<string>;
     height: number;
   }) => void;
@@ -39,11 +52,12 @@ export function HeaderContainer({
   scenes,
   getPreviousScene,
   getFocusedRoute,
+  contentHeight,
   onContentHeightChange,
   style,
 }: Props) {
   const focusedRoute = getFocusedRoute();
-  const parentHeaderBack = React.useContext(HeaderBackContext);
+  const parentHeaderBack = React.use(HeaderBackContext);
   const { buildHref } = useLinkBuilder();
 
   return (
@@ -96,6 +110,9 @@ export function HeaderContainer({
           headerMode: previousHeaderMode,
         } = previousDescriptor?.options || {};
 
+        const { headerTransparent: nextHeaderTransparent } =
+          nextDescriptor?.options || {};
+
         // If any of the next screens don't have a header or header is part of the screen
         // Then we need to move this header offscreen so that it doesn't cover it
         const nextHeaderlessScene = self.slice(i + 1).find((scene) => {
@@ -115,6 +132,9 @@ export function HeaderContainer({
             // We still need to animate when coming back from next scene
             // A hacky way to check this is if the next scene exists
             !nextDescriptor) ||
+          // If next header is tranparent, we want to treat this header as static
+          // Otherwise it may show through the next header
+          nextHeaderTransparent ||
           nextHeaderlessScene;
 
         const props: StackHeaderProps = {
@@ -137,6 +157,26 @@ export function HeaderContainer({
               : forNoAnimation,
         };
 
+        const onRef = (node: View | null) => {
+          node?.measure((_x, _y, _width, height) => {
+            if (height && !contentHeight?.measured) {
+              onContentHeightChange({
+                route: scene.descriptor.route,
+                height,
+              });
+            }
+          });
+        };
+
+        const onLayout = (e: LayoutChangeEvent) => {
+          const { height } = e.nativeEvent.layout;
+
+          onContentHeightChange({
+            route: scene.descriptor.route,
+            height,
+          });
+        };
+
         return (
           <NavigationProvider
             key={scene.descriptor.route.key}
@@ -144,31 +184,37 @@ export function HeaderContainer({
             route={scene.descriptor.route}
           >
             <View
-              onLayout={
-                onContentHeightChange
-                  ? (e) => {
-                      const { height } = e.nativeEvent.layout;
-
-                      onContentHeightChange({
-                        route: scene.descriptor.route,
-                        height,
-                      });
-                    }
-                  : undefined
-              }
-              aria-hidden={!isFocused}
               style={[
-                // Avoid positioning the focused header absolutely
+                // Avoid absolutely positioning the focused header unnecessarily
                 // Otherwise accessibility tools don't seem to be able to find it
                 (mode === 'float' && !isFocused) || headerTransparent
-                  ? styles.header
+                  ? [
+                      styles.absolute,
+                      mode === 'screen'
+                        ? // For transparent headers, specify a min height
+                          // This is needed for screen readers, and testing tools on Android
+                          // For float header, it's handled in CardStack
+                          { minHeight: contentHeight?.value }
+                        : null,
+                    ]
                   : null,
                 {
                   pointerEvents: isFocused ? 'box-none' : 'none',
                 },
               ]}
             >
-              {header !== undefined ? header(props) : <Header {...props} />}
+              <View
+                ref={onRef}
+                onLayout={onLayout}
+                style={{ pointerEvents: 'box-none' }}
+              >
+                <ActivityView
+                  mode={isFocused ? 'normal' : 'inert'}
+                  visible={true}
+                >
+                  {header !== undefined ? header(props) : <Header {...props} />}
+                </ActivityView>
+              </View>
             </View>
           </NavigationProvider>
         );
@@ -181,7 +227,7 @@ const styles = StyleSheet.create({
   container: {
     pointerEvents: 'box-none',
   },
-  header: {
+  absolute: {
     position: 'absolute',
     top: 0,
     start: 0,

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,