@react-navigation/native-stack 7.0.0-alpha.9 → 7.0.0-rc.1

package/src/navigators/createNativeStackNavigator.tsx

@@ -1,12 +1,15 @@
 import {
   createNavigatorFactory,
   type EventArg,
+  type NavigatorTypeBagBase,
   type ParamListBase,
   type StackActionHelpers,
   StackActions,
   type StackNavigationState,
   StackRouter,
   type StackRouterOptions,
+  type StaticConfig,
+  type TypedNavigator,
   useNavigationBuilder,
 } from '@react-navigation/native';
 import * as React from 'react';
@@ -14,6 +17,7 @@ import * as React from 'react';
 import type {
   NativeStackNavigationEventMap,
   NativeStackNavigationOptions,
+  NativeStackNavigationProp,
   NativeStackNavigatorProps,
 } from '../types';
 import { NativeStackView } from '../views/NativeStackView';
@@ -26,6 +30,7 @@ function NativeStackNavigator({
   screenListeners,
   screenOptions,
   screenLayout,
+  UNSTABLE_getStateForRouteNamesChange,
   ...rest
 }: NativeStackNavigatorProps) {
   const { state, descriptors, navigation, NavigationContent } =
@@ -43,6 +48,7 @@ function NativeStackNavigator({
       screenListeners,
       screenOptions,
       screenLayout,
+      UNSTABLE_getStateForRouteNamesChange,
     });
 
   React.useEffect(
@@ -83,9 +89,27 @@ function NativeStackNavigator({
   );
 }
 
-export const createNativeStackNavigator = createNavigatorFactory<
-  StackNavigationState<ParamListBase>,
-  NativeStackNavigationOptions,
-  NativeStackNavigationEventMap,
-  typeof NativeStackNavigator
->(NativeStackNavigator);
+export function createNativeStackNavigator<
+  ParamList extends ParamListBase,
+  NavigatorID extends string | undefined = undefined,
+  TypeBag extends NavigatorTypeBagBase = {
+    ParamList: ParamList;
+    NavigatorID: NavigatorID;
+    State: StackNavigationState<ParamList>;
+    ScreenOptions: NativeStackNavigationOptions;
+    EventMap: NativeStackNavigationEventMap;
+    NavigationList: {
+      [RouteName in keyof ParamList]: NativeStackNavigationProp<
+        ParamList,
+        RouteName,
+        NavigatorID
+      >;
+    };
+    Navigator: typeof NativeStackNavigator;
+  },
+  Config extends StaticConfig<TypeBag> | undefined =
+    | StaticConfig<TypeBag>
+    | undefined,
+>(config?: Config): TypedNavigator<TypeBag, Config> {
+  return createNavigatorFactory(NativeStackNavigator)(config);
+}

package/src/types.tsx

@@ -9,6 +9,7 @@ import type {
   StackActionHelpers,
   StackNavigationState,
   StackRouterOptions,
+  Theme,
 } from '@react-navigation/native';
 import type {
   ImageSourcePropType,
@@ -61,6 +62,14 @@ export type NativeStackScreenProps<
   route: RouteProp<ParamList, RouteName>;
 };
 
+export type NativeStackOptionsArgs<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = keyof ParamList,
+  NavigatorID extends string | undefined = undefined,
+> = NativeStackScreenProps<ParamList, RouteName, NavigatorID> & {
+  theme: Theme;
+};
+
 export type NativeStackNavigationHelpers = NavigationHelpers<
   ParamListBase,
   NativeStackNavigationEventMap
@@ -114,6 +123,10 @@ export type NativeStackHeaderLeftProps = NativeStackHeaderRightProps & {
    * By default, this is only shown on iOS.
    */
   label?: string;
+  /**
+   * The `href` to use for the anchor tag on web
+   */
+  href?: string;
 };
 
 export type NativeStackNavigationOptions = {
@@ -319,7 +332,7 @@ export type NativeStackNavigationOptions = {
    *
    * Only supported on iOS and Android.
    */
-  headerSearchBarOptions?: SearchBarProps;
+  headerSearchBarOptions?: Omit<SearchBarProps, 'ref'>;
   /**
    * Boolean indicating whether to show the menu on longPress of iOS >= 14 back button. Defaults to `true`.
    * Requires `react-native-screens` version >=3.3.0.
@@ -347,6 +360,12 @@ export type NativeStackNavigationOptions = {
    * @platform android
    */
   navigationBarColor?: string;
+  /**
+   * Boolean indicating whether the content should be visible behind the navigation bar. Defaults to `false`.
+   *
+   * @platform android
+   */
+  navigationBarTranslucent?: boolean;
   /**
    * Sets the visibility of the navigation bar. Defaults to `false`.
    *
@@ -571,9 +590,11 @@ export type NativeStackNavigationOptions = {
 
 export type NativeStackNavigatorProps = DefaultNavigatorOptions<
   ParamListBase,
+  string | undefined,
   StackNavigationState<ParamListBase>,
   NativeStackNavigationOptions,
-  NativeStackNavigationEventMap
+  NativeStackNavigationEventMap,
+  NativeStackNavigationProp<ParamListBase>
 > &
   StackRouterOptions &
   NativeStackNavigationConfig;

package/src/utils/debounce.tsx

@@ -0,0 +1,14 @@
+export function debounce<T extends (...args: any[]) => void>(
+  func: T,
+  duration: number
+): T {
+  let timeout: NodeJS.Timeout;
+
+  return function (this: unknown, ...args) {
+    clearTimeout(timeout);
+
+    timeout = setTimeout(() => {
+      func.apply(this, args);
+    }, duration);
+  } as T;
+}

package/src/utils/getModalRoutesKeys.ts

@@ -0,0 +1,21 @@
+import type { Route } from '@react-navigation/native';
+
+import type { NativeStackDescriptorMap } from '../types';
+
+export const getModalRouteKeys = (
+  routes: Route<string>[],
+  descriptors: NativeStackDescriptorMap
+) =>
+  routes.reduce<string[]>((acc, route) => {
+    const { presentation } = descriptors[route.key]?.options ?? {};
+
+    if (
+      (acc.length && !presentation) ||
+      presentation === 'modal' ||
+      presentation === 'transparentModal'
+    ) {
+      acc.push(route.key);
+    }
+
+    return acc;
+  }, []);

package/src/utils/useAnimatedHeaderHeight.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import type { Animated } from 'react-native';
 
 export const AnimatedHeaderHeightContext = React.createContext<
-  Animated.Value | undefined
+  Animated.AnimatedInterpolation<number> | undefined
 >(undefined);
 
 export function useAnimatedHeaderHeight() {

package/src/views/HeaderConfig.tsx

@@ -58,16 +58,16 @@ export function HeaderConfig({
     headerTintColor ?? (Platform.OS === 'ios' ? colors.primary : colors.text);
 
   const headerBackTitleStyleFlattened =
-    StyleSheet.flatten([headerBackTitleStyle, fonts.regular]) || {};
+    StyleSheet.flatten([fonts.regular, headerBackTitleStyle]) || {};
   const headerLargeTitleStyleFlattened =
     StyleSheet.flatten([
-      headerLargeTitleStyle,
       Platform.select({ ios: fonts.heavy, default: fonts.medium }),
+      headerLargeTitleStyle,
     ]) || {};
   const headerTitleStyleFlattened =
     StyleSheet.flatten([
-      headerTitleStyle,
       Platform.select({ ios: fonts.bold, default: fonts.medium }),
+      headerTitleStyle,
     ]) || {};
   const headerStyleFlattened = StyleSheet.flatten(headerStyle) || {};
   const headerLargeStyleFlattened = StyleSheet.flatten(headerLargeStyle) || {};
@@ -130,6 +130,8 @@ export function HeaderConfig({
     tintColor,
     canGoBack,
     label: headerBackTitle,
+    // `href` is only applicable to web
+    href: undefined,
   });
   const headerRightElement = headerRight?.({
     tintColor,
@@ -179,7 +181,12 @@ export function HeaderConfig({
     <ScreenStackHeaderConfig
       backButtonInCustomView={backButtonInCustomView}
       backgroundColor={headerBackgroundColor}
-      backTitle={headerBackTitleVisible ? headerBackTitle : ' '}
+      backTitle={
+        headerBackTitleVisible
+          ? headerBackTitle
+          : ' ' /* For backward compatibility with react-native-screens versions <3.21.0, where `backTitleVisible` is not available */
+      }
+      backTitleVisible={headerBackTitleVisible}
       backTitleFontFamily={backTitleFontFamily}
       backTitleFontSize={backTitleFontSize}
       blurEffect={headerBlurEffect}
@@ -204,7 +211,7 @@ export function HeaderConfig({
       titleColor={titleColor}
       titleFontFamily={titleFontFamily}
       titleFontSize={titleFontSize}
-      titleFontWeight={titleFontWeight}
+      titleFontWeight={String(titleFontWeight)}
       topInsetEnabled={headerTopInsetEnabled}
       translucent={
         // This defaults to `true`, so we can't pass `undefined`

package/src/views/NativeStackView.native.tsx

@@ -20,6 +20,7 @@ import * as React from 'react';
 import {
   Animated,
   Platform,
+  StatusBar,
   StyleSheet,
   useAnimatedValue,
   View,
@@ -42,6 +43,8 @@ import type {
   NativeStackNavigationHelpers,
   NativeStackNavigationOptions,
 } from '../types';
+import { debounce } from '../utils/debounce';
+import { getModalRouteKeys } from '../utils/getModalRoutesKeys';
 import { AnimatedHeaderHeightContext } from '../utils/useAnimatedHeaderHeight';
 import { useDismissedRouteError } from '../utils/useDismissedRouteError';
 import { useInvalidPreventRemoveError } from '../utils/useInvalidPreventRemoveError';
@@ -132,6 +135,7 @@ type SceneViewProps = {
   descriptor: NativeStackDescriptor;
   previousDescriptor?: NativeStackDescriptor;
   nextDescriptor?: NativeStackDescriptor;
+  isPresentationModal?: boolean;
   onWillDisappear: () => void;
   onWillAppear: () => void;
   onAppear: () => void;
@@ -148,6 +152,7 @@ const SceneView = ({
   descriptor,
   previousDescriptor,
   nextDescriptor,
+  isPresentationModal,
   onWillDisappear,
   onWillAppear,
   onAppear,
@@ -162,8 +167,8 @@ const SceneView = ({
   let {
     animation,
     animationMatchesGesture,
+    presentation = isPresentationModal ? 'modal' : 'card',
     fullScreenGestureEnabled,
-    presentation = 'card',
   } = options;
 
   const {
@@ -180,6 +185,7 @@ const SceneView = ({
     autoHideHomeIndicator,
     keyboardHandlingEnabled,
     navigationBarColor,
+    navigationBarTranslucent,
     navigationBarHidden,
     orientation,
     sheetAllowedDetents = 'large',
@@ -249,15 +255,57 @@ const SceneView = ({
 
   const { preventedRoutes } = usePreventRemoveContext();
 
-  const defaultHeaderHeight = getDefaultHeaderHeight(frame, isModal, topInset);
+  const defaultHeaderHeight = Platform.select({
+    // FIXME: Currently screens isn't using Material 3
+    // So our `getDefaultHeaderHeight` doesn't return the correct value
+    // So we hardcode the value here for now until screens is updated
+    android: 56 + topInset,
+    default: getDefaultHeaderHeight(frame, isModal, topInset),
+  });
+
+  const [headerHeight, setHeaderHeight] = React.useState(defaultHeaderHeight);
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const setHeaderHeightDebounced = React.useCallback(
+    // Debounce the header height updates to avoid excessive re-renders
+    debounce(setHeaderHeight, 100),
+    []
+  );
+
+  const hasCustomHeader = header !== undefined;
+
+  let headerHeightCorrectionOffset = 0;
+
+  if (isAndroid && !hasCustomHeader) {
+    const statusBarHeight = StatusBar.currentHeight ?? 0;
 
-  const [customHeaderHeight, setCustomHeaderHeight] =
-    React.useState(defaultHeaderHeight);
+    // FIXME: On Android, the native header height is not correctly calculated
+    // It includes status bar height even if statusbar is not translucent
+    // And the statusbar value itself doesn't match the actual status bar height
+    // So we subtract the bogus status bar height and add the actual top inset
+    headerHeightCorrectionOffset = -statusBarHeight + topInset;
+  }
 
-  const animatedHeaderHeight = useAnimatedValue(defaultHeaderHeight);
+  const rawAnimatedHeaderHeight = useAnimatedValue(defaultHeaderHeight);
+  const animatedHeaderHeight = React.useMemo(
+    () =>
+      Animated.add<number>(
+        rawAnimatedHeaderHeight,
+        headerHeightCorrectionOffset
+      ),
+    [headerHeightCorrectionOffset, rawAnimatedHeaderHeight]
+  );
 
-  const headerTopInsetEnabled = topInset !== 0;
-  const headerHeight = header ? customHeaderHeight : defaultHeaderHeight;
+  // During the very first render topInset is > 0 when running
+  // in non edge-to-edge mode on Android, while on every consecutive render
+  // topInset === 0, causing header content to jump, as we add padding on the first frame,
+  // just to remove it in next one. To prevent this, when statusBarTranslucent is set,
+  // we apply additional padding in header only if its true.
+  // For more details see: https://github.com/react-navigation/react-navigation/pull/12014
+  const headerTopInsetEnabled =
+    typeof statusBarTranslucent === 'boolean'
+      ? statusBarTranslucent
+      : topInset !== 0;
 
   const backTitle = previousDescriptor
     ? getHeaderTitle(previousDescriptor.options, previousDescriptor.route.name)
@@ -293,6 +341,8 @@ const SceneView = ({
       homeIndicatorHidden={autoHideHomeIndicator}
       hideKeyboardOnSwipe={keyboardHandlingEnabled}
       navigationBarColor={navigationBarColor}
+      // @ts-expect-error prop supported from react-native-screens 3.32.0 onwards
+      navigationBarTranslucent={navigationBarTranslucent}
       navigationBarHidden={navigationBarHidden}
       replaceAnimation={animationTypeForReplace}
       stackPresentation={presentation === 'card' ? 'push' : presentation}
@@ -329,11 +379,36 @@ const SceneView = ({
         [
           {
             nativeEvent: {
-              headerHeight: animatedHeaderHeight,
+              headerHeight: rawAnimatedHeaderHeight,
             },
           },
         ],
-        { useNativeDriver: true }
+        {
+          useNativeDriver: true,
+          listener: (e) => {
+            if (
+              e.nativeEvent &&
+              typeof e.nativeEvent === 'object' &&
+              'headerHeight' in e.nativeEvent &&
+              typeof e.nativeEvent.headerHeight === 'number'
+            ) {
+              const headerHeight =
+                e.nativeEvent.headerHeight + headerHeightCorrectionOffset;
+
+              // Only debounce if header has large title or search bar
+              // As it's the only case where the header height can change frequently
+              const doesHeaderAnimate =
+                Platform.OS === 'ios' &&
+                (options.headerLargeTitle || options.headerSearchBarOptions);
+
+              if (doesHeaderAnimate) {
+                setHeaderHeightDebounced(headerHeight);
+              } else {
+                setHeaderHeight(headerHeight);
+              }
+            }
+          },
+        }
       )}
       // this prop is available since rn-screens 3.16
       freezeOnBlur={freezeOnBlur}
@@ -385,7 +460,10 @@ const SceneView = ({
                   {header !== undefined && headerShown !== false ? (
                     <View
                       onLayout={(e) => {
-                        setCustomHeaderHeight(e.nativeEvent.layout.height);
+                        const headerHeight = e.nativeEvent.layout.height;
+
+                        setHeaderHeight(headerHeight);
+                        rawAnimatedHeaderHeight.setValue(headerHeight);
                       }}
                       style={headerTransparent ? styles.absolute : null}
                     >
@@ -442,99 +520,100 @@ type Props = {
   descriptors: NativeStackDescriptorMap;
 };
 
-function NativeStackViewInner({ state, navigation, descriptors }: Props) {
+export function NativeStackView({ state, navigation, descriptors }: Props) {
   const { setNextDismissedKey } = useDismissedRouteError(state);
 
+  const { colors } = useTheme();
+
   useInvalidPreventRemoveError(descriptors);
 
-  return (
-    <ScreenStack style={styles.container}>
-      {state.routes.map((route, index) => {
-        const descriptor = descriptors[route.key];
-        const isFocused = state.index === index;
-        const previousKey = state.routes[index - 1]?.key;
-        const nextKey = state.routes[index + 1]?.key;
-        const previousDescriptor = previousKey
-          ? descriptors[previousKey]
-          : undefined;
-        const nextDescriptor = nextKey ? descriptors[nextKey] : undefined;
-
-        return (
-          <SceneView
-            key={route.key}
-            index={index}
-            focused={isFocused}
-            descriptor={descriptor}
-            previousDescriptor={previousDescriptor}
-            nextDescriptor={nextDescriptor}
-            onWillDisappear={() => {
-              navigation.emit({
-                type: 'transitionStart',
-                data: { closing: true },
-                target: route.key,
-              });
-            }}
-            onWillAppear={() => {
-              navigation.emit({
-                type: 'transitionStart',
-                data: { closing: false },
-                target: route.key,
-              });
-            }}
-            onAppear={() => {
-              navigation.emit({
-                type: 'transitionEnd',
-                data: { closing: false },
-                target: route.key,
-              });
-            }}
-            onDisappear={() => {
-              navigation.emit({
-                type: 'transitionEnd',
-                data: { closing: true },
-                target: route.key,
-              });
-            }}
-            onDismissed={(event) => {
-              navigation.dispatch({
-                ...StackActions.pop(event.nativeEvent.dismissCount),
-                source: route.key,
-                target: state.key,
-              });
-
-              setNextDismissedKey(route.key);
-            }}
-            onHeaderBackButtonClicked={() => {
-              navigation.dispatch({
-                ...StackActions.pop(),
-                source: route.key,
-                target: state.key,
-              });
-            }}
-            onNativeDismissCancelled={(event) => {
-              navigation.dispatch({
-                ...StackActions.pop(event.nativeEvent.dismissCount),
-                source: route.key,
-                target: state.key,
-              });
-            }}
-            onGestureCancel={() => {
-              navigation.emit({
-                type: 'gestureCancel',
-                target: route.key,
-              });
-            }}
-          />
-        );
-      })}
-    </ScreenStack>
-  );
-}
+  const modalRouteKeys = getModalRouteKeys(state.routes, descriptors);
 
-export function NativeStackView(props: Props) {
   return (
-    <SafeAreaProviderCompat>
-      <NativeStackViewInner {...props} />
+    <SafeAreaProviderCompat style={{ backgroundColor: colors.background }}>
+      <ScreenStack style={styles.container}>
+        {state.routes.map((route, index) => {
+          const descriptor = descriptors[route.key];
+          const isFocused = state.index === index;
+          const previousKey = state.routes[index - 1]?.key;
+          const nextKey = state.routes[index + 1]?.key;
+          const previousDescriptor = previousKey
+            ? descriptors[previousKey]
+            : undefined;
+          const nextDescriptor = nextKey ? descriptors[nextKey] : undefined;
+
+          const isModal = modalRouteKeys.includes(route.key);
+
+          return (
+            <SceneView
+              key={route.key}
+              index={index}
+              focused={isFocused}
+              descriptor={descriptor}
+              previousDescriptor={previousDescriptor}
+              nextDescriptor={nextDescriptor}
+              isPresentationModal={isModal}
+              onWillDisappear={() => {
+                navigation.emit({
+                  type: 'transitionStart',
+                  data: { closing: true },
+                  target: route.key,
+                });
+              }}
+              onWillAppear={() => {
+                navigation.emit({
+                  type: 'transitionStart',
+                  data: { closing: false },
+                  target: route.key,
+                });
+              }}
+              onAppear={() => {
+                navigation.emit({
+                  type: 'transitionEnd',
+                  data: { closing: false },
+                  target: route.key,
+                });
+              }}
+              onDisappear={() => {
+                navigation.emit({
+                  type: 'transitionEnd',
+                  data: { closing: true },
+                  target: route.key,
+                });
+              }}
+              onDismissed={(event) => {
+                navigation.dispatch({
+                  ...StackActions.pop(event.nativeEvent.dismissCount),
+                  source: route.key,
+                  target: state.key,
+                });
+
+                setNextDismissedKey(route.key);
+              }}
+              onHeaderBackButtonClicked={() => {
+                navigation.dispatch({
+                  ...StackActions.pop(),
+                  source: route.key,
+                  target: state.key,
+                });
+              }}
+              onNativeDismissCancelled={(event) => {
+                navigation.dispatch({
+                  ...StackActions.pop(event.nativeEvent.dismissCount),
+                  source: route.key,
+                  target: state.key,
+                });
+              }}
+              onGestureCancel={() => {
+                navigation.emit({
+                  type: 'gestureCancel',
+                  target: route.key,
+                });
+              }}
+            />
+          );
+        })}
+      </ScreenStack>
     </SafeAreaProviderCompat>
   );
 }
@@ -550,14 +629,14 @@ const styles = StyleSheet.create({
   absolute: {
     position: 'absolute',
     top: 0,
-    left: 0,
-    right: 0,
+    start: 0,
+    end: 0,
   },
   translucent: {
     position: 'absolute',
     top: 0,
-    left: 0,
-    right: 0,
+    start: 0,
+    end: 0,
     zIndex: 1,
     elevation: 1,
   },