@react-navigation/native-stack 7.0.0-rc.27 → 7.0.0-rc.29

package/src/views/NativeStackView.native.tsx

@@ -10,7 +10,7 @@ import {
   NavigationContext,
   NavigationRouteContext,
   type ParamListBase,
-  type Route,
+  type RouteProp,
   StackActions,
   type StackNavigationState,
   usePreventRemoveContext,
@@ -29,107 +29,24 @@ import {
   useSafeAreaFrame,
   useSafeAreaInsets,
 } from 'react-native-safe-area-context';
-import {
-  Screen,
-  type ScreenProps,
-  ScreenStack,
-  type StackPresentationTypes,
-} from 'react-native-screens';
-import warnOnce from 'warn-once';
+import { type ScreenProps, ScreenStack } from 'react-native-screens';
 
 import type {
   NativeStackDescriptor,
   NativeStackDescriptorMap,
   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';
-import { DebugContainer } from './DebugContainer';
-import { HeaderConfig } from './HeaderConfig';
+import { FooterComponent } from './FooterComponent';
+import { ScreenStackContent } from './ScreenStackContent';
+import { useHeaderConfigProps } from './useHeaderConfigProps';
 
 const ANDROID_DEFAULT_HEADER_HEIGHT = 56;
 
-const MaybeNestedStack = ({
-  options,
-  route,
-  presentation,
-  headerHeight,
-  headerTopInsetEnabled,
-  children,
-}: {
-  options: NativeStackNavigationOptions;
-  route: Route<string>;
-  presentation: Exclude<StackPresentationTypes, 'push'> | 'card';
-  headerHeight: number;
-  headerTopInsetEnabled: boolean;
-  children: React.ReactNode;
-}) => {
-  const { colors } = useTheme();
-  const { header, headerShown = true, contentStyle } = options;
-
-  const isHeaderInModal =
-    Platform.OS === 'android'
-      ? false
-      : presentation !== 'card' && headerShown === true && header === undefined;
-
-  const headerShownPreviousRef = React.useRef(headerShown);
-
-  React.useEffect(() => {
-    warnOnce(
-      Platform.OS !== 'android' &&
-        presentation !== 'card' &&
-        headerShownPreviousRef.current !== headerShown,
-      `Dynamically changing 'headerShown' in modals will result in remounting the screen and losing all local state. See options for the screen '${route.name}'.`
-    );
-
-    headerShownPreviousRef.current = headerShown;
-  }, [headerShown, presentation, route.name]);
-
-  const content = (
-    <DebugContainer
-      style={[
-        styles.container,
-        presentation !== 'transparentModal' &&
-          presentation !== 'containedTransparentModal' && {
-            backgroundColor: colors.background,
-          },
-        contentStyle,
-      ]}
-      stackPresentation={presentation === 'card' ? 'push' : presentation}
-    >
-      {children}
-    </DebugContainer>
-  );
-
-  if (isHeaderInModal) {
-    return (
-      <ScreenStack style={styles.container}>
-        <Screen
-          enabled
-          isNativeStack
-          hasLargeHeader={options.headerLargeTitle ?? false}
-          style={StyleSheet.absoluteFill}
-        >
-          {content}
-          <HeaderConfig
-            {...options}
-            route={route}
-            headerHeight={headerHeight}
-            headerTopInsetEnabled={headerTopInsetEnabled}
-            canGoBack
-          />
-        </Screen>
-      </ScreenStack>
-    );
-  }
-
-  return content;
-};
-
 type SceneViewProps = {
   index: number;
   focused: boolean;
@@ -137,6 +54,7 @@ type SceneViewProps = {
   previousDescriptor?: NativeStackDescriptor;
   nextDescriptor?: NativeStackDescriptor;
   isPresentationModal?: boolean;
+  isPreloaded?: boolean;
   onWillDisappear: () => void;
   onWillAppear: () => void;
   onAppear: () => void;
@@ -145,6 +63,7 @@ type SceneViewProps = {
   onHeaderBackButtonClicked: ScreenProps['onHeaderBackButtonClicked'];
   onNativeDismissCancelled: ScreenProps['onDismissed'];
   onGestureCancel: ScreenProps['onGestureCancel'];
+  onSheetDetentChanged: ScreenProps['onSheetDetentChanged'];
 };
 
 const SceneView = ({
@@ -154,6 +73,7 @@ const SceneView = ({
   previousDescriptor,
   nextDescriptor,
   isPresentationModal,
+  isPreloaded,
   onWillDisappear,
   onWillAppear,
   onAppear,
@@ -162,6 +82,7 @@ const SceneView = ({
   onHeaderBackButtonClicked,
   onNativeDismissCancelled,
   onGestureCancel,
+  onSheetDetentChanged,
 }: SceneViewProps) => {
   const { route, navigation, options, render } = descriptor;
 
@@ -170,6 +91,7 @@ const SceneView = ({
     animationMatchesGesture,
     presentation = isPresentationModal ? 'modal' : 'card',
     fullScreenGestureEnabled,
+    unstable_screenStyle = null,
   } = options;
 
   const {
@@ -190,19 +112,31 @@ const SceneView = ({
     navigationBarTranslucent,
     navigationBarHidden,
     orientation,
-    sheetAllowedDetents = 'large',
-    sheetLargestUndimmedDetent = 'all',
+    sheetAllowedDetents = [1.0],
+    sheetLargestUndimmedDetentIndex = -1,
     sheetGrabberVisible = false,
     sheetCornerRadius = -1.0,
+    sheetElevation = 24,
     sheetExpandsWhenScrolledToEdge = true,
+    sheetInitialDetentIndex = 0,
     statusBarAnimation,
     statusBarHidden,
     statusBarStyle,
     statusBarTranslucent,
     statusBarBackgroundColor,
+    unstable_sheetFooter = null,
     freezeOnBlur,
+    contentStyle,
   } = options;
 
+  // We want to allow only backgroundColor setting for now.
+  // This allows to workaround one issue with truncated
+  // content with formSheet presentation.
+  unstable_screenStyle =
+    unstable_screenStyle && presentation === 'formSheet'
+      ? { backgroundColor: unstable_screenStyle.backgroundColor }
+      : null;
+
   if (gestureDirection === 'vertical' && Platform.OS === 'ios') {
     // for `vertical` direction to work, we need to set `fullScreenGestureEnabled` to `true`
     // so the screen can be dismissed from any point on screen.
@@ -234,6 +168,7 @@ const SceneView = ({
     presentation = 'card';
   }
 
+  const { colors } = useTheme();
   const insets = useSafeAreaInsets();
   const frame = useSafeAreaFrame();
 
@@ -309,32 +244,52 @@ const SceneView = ({
       ? statusBarTranslucent
       : topInset !== 0;
 
+  const canGoBack = previousDescriptor != null || parentHeaderBack != null;
   const backTitle = previousDescriptor
     ? getHeaderTitle(previousDescriptor.options, previousDescriptor.route.name)
     : parentHeaderBack?.title;
 
-  const headerBack = React.useMemo(
-    () => ({
-      // No href needed for native
-      href: undefined,
-      title: backTitle,
-    }),
-    [backTitle]
-  );
+  const headerBack = React.useMemo(() => {
+    if (canGoBack) {
+      return {
+        href: undefined, // No href needed for native
+        title: backTitle,
+      };
+    }
+
+    return undefined;
+  }, [canGoBack, backTitle]);
 
   const isRemovePrevented = preventedRoutes[route.key]?.preventRemove;
 
+  const headerConfig = useHeaderConfigProps({
+    ...options,
+    route,
+    canGoBack,
+    headerBackButtonMenuEnabled:
+      isRemovePrevented !== undefined
+        ? !isRemovePrevented
+        : headerBackButtonMenuEnabled,
+    headerBackTitle:
+      options.headerBackTitle !== undefined
+        ? options.headerBackTitle
+        : undefined,
+    headerHeight,
+    headerShown: header !== undefined ? false : headerShown,
+    headerTopInsetEnabled,
+  });
+
   return (
-    <Screen
+    <ScreenStackContent
       key={route.key}
-      enabled
-      isNativeStack
+      activityState={isPreloaded ? 0 : 2}
+      style={[StyleSheet.absoluteFill, unstable_screenStyle]}
       accessibilityElementsHidden={!focused}
       importantForAccessibility={focused ? 'auto' : 'no-hide-descendants'}
-      style={StyleSheet.absoluteFill}
-      hasLargeHeader={options.headerLargeTitle ?? false}
       customAnimationOnSwipe={animationMatchesGesture}
       fullScreenSwipeEnabled={fullScreenGestureEnabled}
+      fullScreenSwipeShadowEnabled={fullScreenGestureShadowEnabled}
+      freezeOnBlur={freezeOnBlur}
       gestureEnabled={
         Platform.OS === 'android'
           ? // This prop enables handling of system back gestures on Android
@@ -352,9 +307,11 @@ const SceneView = ({
       stackAnimation={animation}
       screenOrientation={orientation}
       sheetAllowedDetents={sheetAllowedDetents}
-      sheetLargestUndimmedDetent={sheetLargestUndimmedDetent}
+      sheetLargestUndimmedDetentIndex={sheetLargestUndimmedDetentIndex}
       sheetGrabberVisible={sheetGrabberVisible}
+      sheetInitialDetentIndex={sheetInitialDetentIndex}
       sheetCornerRadius={sheetCornerRadius}
+      sheetElevation={sheetElevation}
       sheetExpandsWhenScrolledToEdge={sheetExpandsWhenScrolledToEdge}
       statusBarAnimation={statusBarAnimation}
       statusBarHidden={statusBarHidden}
@@ -369,6 +326,7 @@ const SceneView = ({
       onDisappear={onDisappear}
       onDismissed={onDismissed}
       onGestureCancel={onGestureCancel}
+      onSheetDetentChanged={onSheetDetentChanged}
       gestureResponseDistance={gestureResponseDistance}
       nativeBackButtonDismissalEnabled={false} // on Android
       onHeaderBackButtonClicked={onHeaderBackButtonClicked}
@@ -423,12 +381,17 @@ const SceneView = ({
           },
         }
       )}
-      freezeOnBlur={freezeOnBlur}
+      contentStyle={[
+        presentation !== 'transparentModal' &&
+          presentation !== 'containedTransparentModal' && {
+            backgroundColor: colors.background,
+          },
+        contentStyle,
+      ]}
+      headerConfig={headerConfig}
       // When ts-expect-error is added, it affects all the props below it
       // So we keep any props that need it at the end
       // Otherwise invalid props may not be caught by TypeScript
-      // @ts-expect-error Props available in newer versions of `react-native-screens`
-      fullScreenSwipeShadowEnabled={fullScreenGestureShadowEnabled} // 3.33.0 onwards
     >
       <NavigationContext.Provider value={navigation}>
         <NavigationRouteContext.Provider value={route}>
@@ -477,52 +440,18 @@ const SceneView = ({
               <HeaderShownContext.Provider
                 value={isParentHeaderShown || headerShown !== false}
               >
-                <MaybeNestedStack
-                  options={options}
-                  route={route}
-                  presentation={presentation}
-                  headerHeight={headerHeight}
-                  headerTopInsetEnabled={headerTopInsetEnabled}
-                >
-                  <HeaderBackContext.Provider value={headerBack}>
-                    {render()}
-                  </HeaderBackContext.Provider>
-                </MaybeNestedStack>
+                <HeaderBackContext.Provider value={headerBack}>
+                  {render()}
+                </HeaderBackContext.Provider>
               </HeaderShownContext.Provider>
-              {/**
-               * `HeaderConfig` needs to be the direct child of `Screen` without any intermediate `View`
-               * We don't render it conditionally to make it possible to dynamically render a custom `header`
-               * Otherwise dynamically rendering a custom `header` leaves the native header visible
-               *
-               * https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md#screenstackheaderconfig
-               *
-               * HeaderConfig must not be first child of a Screen.
-               * See https://github.com/software-mansion/react-native-screens/pull/1825
-               * for detailed explanation
-               */}
-              <HeaderConfig
-                {...options}
-                route={route}
-                headerBackButtonMenuEnabled={
-                  isRemovePrevented !== undefined
-                    ? !isRemovePrevented
-                    : headerBackButtonMenuEnabled
-                }
-                headerShown={header !== undefined ? false : headerShown}
-                headerHeight={headerHeight}
-                headerBackTitle={
-                  options.headerBackTitle !== undefined
-                    ? options.headerBackTitle
-                    : undefined
-                }
-                headerTopInsetEnabled={headerTopInsetEnabled}
-                canGoBack={headerBack !== undefined}
-              />
+              {presentation === 'formSheet' && unstable_sheetFooter && (
+                <FooterComponent>{unstable_sheetFooter()}</FooterComponent>
+              )}
             </HeaderHeightContext.Provider>
           </AnimatedHeaderHeightContext.Provider>
         </NavigationRouteContext.Provider>
       </NavigationContext.Provider>
-    </Screen>
+    </ScreenStackContent>
   );
 };
 
@@ -530,9 +459,18 @@ type Props = {
   state: StackNavigationState<ParamListBase>;
   navigation: NativeStackNavigationHelpers;
   descriptors: NativeStackDescriptorMap;
+  describe: (
+    route: RouteProp<ParamListBase>,
+    placeholder: boolean
+  ) => NativeStackDescriptor;
 };
 
-export function NativeStackView({ state, navigation, descriptors }: Props) {
+export function NativeStackView({
+  state,
+  navigation,
+  descriptors,
+  describe,
+}: Props) {
   const { setNextDismissedKey } = useDismissedRouteError(state);
 
   const { colors } = useTheme();
@@ -541,11 +479,18 @@ export function NativeStackView({ state, navigation, descriptors }: Props) {
 
   const modalRouteKeys = getModalRouteKeys(state.routes, descriptors);
 
+  const preloadedDescriptors =
+    state.preloadedRoutes.reduce<NativeStackDescriptorMap>((acc, route) => {
+      acc[route.key] = acc[route.key] || describe(route, true);
+      return acc;
+    }, {});
+
   return (
     <SafeAreaProviderCompat style={{ backgroundColor: colors.background }}>
       <ScreenStack style={styles.container}>
-        {state.routes.map((route, index) => {
-          const descriptor = descriptors[route.key];
+        {state.routes.concat(state.preloadedRoutes).map((route, index) => {
+          const descriptor =
+            descriptors[route.key] ?? preloadedDescriptors[route.key];
           const isFocused = state.index === index;
           const previousKey = state.routes[index - 1]?.key;
           const nextKey = state.routes[index + 1]?.key;
@@ -556,6 +501,10 @@ export function NativeStackView({ state, navigation, descriptors }: Props) {
 
           const isModal = modalRouteKeys.includes(route.key);
 
+          const isPreloaded =
+            preloadedDescriptors[route.key] !== undefined &&
+            descriptors[route.key] === undefined;
+
           return (
             <SceneView
               key={route.key}
@@ -565,6 +514,7 @@ export function NativeStackView({ state, navigation, descriptors }: Props) {
               previousDescriptor={previousDescriptor}
               nextDescriptor={nextDescriptor}
               isPresentationModal={isModal}
+              isPreloaded={isPreloaded}
               onWillDisappear={() => {
                 navigation.emit({
                   type: 'transitionStart',
@@ -622,6 +572,16 @@ export function NativeStackView({ state, navigation, descriptors }: Props) {
                   target: route.key,
                 });
               }}
+              onSheetDetentChanged={(event) => {
+                navigation.emit({
+                  type: 'sheetDetentChange',
+                  target: route.key,
+                  data: {
+                    index: event.nativeEvent.index,
+                    stable: event.nativeEvent.isStable,
+                  },
+                });
+              }}
             />
           );
         })}

package/src/views/NativeStackView.tsx

@@ -9,6 +9,7 @@ import {
 } from '@react-navigation/elements';
 import {
   type ParamListBase,
+  type RouteProp,
   type StackNavigationState,
   useLinkBuilder,
   useTheme,
@@ -17,6 +18,7 @@ import * as React from 'react';
 import { Animated, Image, StyleSheet, View } from 'react-native';
 
 import type {
+  NativeStackDescriptor,
   NativeStackDescriptorMap,
   NativeStackNavigationHelpers,
 } from '../types';
@@ -27,6 +29,10 @@ type Props = {
   // This is used for the native implementation of the stack.
   navigation: NativeStackNavigationHelpers;
   descriptors: NativeStackDescriptorMap;
+  describe: (
+    route: RouteProp<ParamListBase>,
+    placeholder: boolean
+  ) => NativeStackDescriptor;
 };
 
 const TRANSPARENT_PRESENTATIONS = [
@@ -34,20 +40,20 @@ const TRANSPARENT_PRESENTATIONS = [
   'containedTransparentModal',
 ];
 
-export function NativeStackView({ state, descriptors }: Props) {
+export function NativeStackView({ state, descriptors, describe }: Props) {
   const parentHeaderBack = React.useContext(HeaderBackContext);
   const { buildHref } = useLinkBuilder();
   const { colors } = useTheme();
 
-  if (state.preloadedRoutes.length !== 0) {
-    throw new Error(
-      'Preloading routes is not supported in the NativeStackNavigator navigator.'
-    );
-  }
+  const preloadedDescriptors =
+    state.preloadedRoutes.reduce<NativeStackDescriptorMap>((acc, route) => {
+      acc[route.key] = acc[route.key] || describe(route, true);
+      return acc;
+    }, {});
 
   return (
     <SafeAreaProviderCompat style={{ backgroundColor: colors.background }}>
-      {state.routes.map((route, i) => {
+      {state.routes.concat(state.preloadedRoutes).map((route, i) => {
         const isFocused = state.index === i;
         const previousKey = state.routes[i - 1]?.key;
         const nextKey = state.routes[i + 1]?.key;
@@ -55,7 +61,8 @@ export function NativeStackView({ state, descriptors }: Props) {
           ? descriptors[previousKey]
           : undefined;
         const nextDescriptor = nextKey ? descriptors[nextKey] : undefined;
-        const { options, navigation, render } = descriptors[route.key];
+        const { options, navigation, render } =
+          descriptors[route.key] ?? preloadedDescriptors[route.key];
 
         const headerBack = previousDescriptor
           ? {
@@ -70,7 +77,7 @@ export function NativeStackView({ state, descriptors }: Props) {
             }
           : parentHeaderBack;
 
-        const canGoBack = headerBack !== undefined;
+        const canGoBack = headerBack != null;
 
         const {
           header,
@@ -86,6 +93,10 @@ export function NativeStackView({ state, descriptors }: Props) {
 
         const nextPresentation = nextDescriptor?.options.presentation;
 
+        const isPreloaded =
+          preloadedDescriptors[route.key] !== undefined &&
+          descriptors[route.key] === undefined;
+
         return (
           <Screen
             key={route.key}
@@ -146,9 +157,10 @@ export function NativeStackView({ state, descriptors }: Props) {
               StyleSheet.absoluteFill,
               {
                 display:
-                  isFocused ||
-                  (nextPresentation != null &&
-                    TRANSPARENT_PRESENTATIONS.includes(nextPresentation))
+                  (isFocused ||
+                    (nextPresentation != null &&
+                      TRANSPARENT_PRESENTATIONS.includes(nextPresentation))) &&
+                  !isPreloaded
                     ? 'flex'
                     : 'none',
               },

package/src/views/ScreenStackContent.tsx

@@ -0,0 +1,121 @@
+import * as React from 'react';
+import {
+  Platform,
+  type StyleProp,
+  StyleSheet,
+  type ViewStyle,
+} from 'react-native';
+import {
+  Screen,
+  type ScreenProps,
+  ScreenStack,
+  ScreenStackHeaderConfig,
+  type ScreenStackHeaderConfigProps,
+} from 'react-native-screens';
+import warnOnce from 'warn-once';
+
+import { DebugContainer } from './DebugContainer';
+
+type Props = Omit<
+  ScreenProps,
+  'enabled' | 'isNativeStack' | 'hasLargeHeader'
+> & {
+  headerConfig?: ScreenStackHeaderConfigProps;
+  contentStyle?: StyleProp<ViewStyle>;
+};
+
+export function ScreenStackContent({
+  children,
+  headerConfig,
+  activityState,
+  stackPresentation,
+  contentStyle,
+  ...rest
+}: Props) {
+  const isHeaderInModal =
+    Platform.OS === 'android'
+      ? false
+      : stackPresentation !== 'push' && headerConfig?.hidden === false;
+
+  const headerHiddenPreviousRef = React.useRef(headerConfig?.hidden);
+
+  React.useEffect(() => {
+    warnOnce(
+      Platform.OS !== 'android' &&
+        stackPresentation !== 'push' &&
+        headerHiddenPreviousRef.current !== headerConfig?.hidden,
+      `Dynamically changing header's visibility in modals will result in remounting the screen and losing all local state.`
+    );
+
+    headerHiddenPreviousRef.current = headerConfig?.hidden;
+  }, [headerConfig?.hidden, stackPresentation]);
+
+  const content = (
+    <>
+      <DebugContainer
+        style={[
+          stackPresentation === 'formSheet'
+            ? Platform.OS === 'ios'
+              ? styles.absolute
+              : null
+            : styles.container,
+          contentStyle,
+        ]}
+        stackPresentation={stackPresentation ?? 'push'}
+      >
+        {children}
+      </DebugContainer>
+      {/**
+       * `HeaderConfig` needs to be the direct child of `Screen` without any intermediate `View`
+       * We don't render it conditionally based on visibility to make it possible to dynamically render a custom `header`
+       * Otherwise dynamically rendering a custom `header` leaves the native header visible
+       *
+       * https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md#screenstackheaderconfig
+       *
+       * HeaderConfig must not be first child of a Screen.
+       * See https://github.com/software-mansion/react-native-screens/pull/1825
+       * for detailed explanation.
+       */}
+      <ScreenStackHeaderConfig {...headerConfig} />
+    </>
+  );
+
+  return (
+    <Screen
+      enabled
+      isNativeStack
+      activityState={activityState}
+      stackPresentation={stackPresentation}
+      hasLargeHeader={headerConfig?.largeTitle ?? false}
+      {...rest}
+    >
+      {isHeaderInModal ? (
+        <ScreenStack style={styles.container}>
+          <Screen
+            enabled
+            isNativeStack
+            activityState={activityState}
+            hasLargeHeader={headerConfig?.largeTitle ?? false}
+            style={StyleSheet.absoluteFill}
+          >
+            {content}
+          </Screen>
+        </ScreenStack>
+      ) : (
+        content
+      )}
+    </Screen>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  absolute: {
+    position: 'absolute',
+    top: 0,
+    start: 0,
+    end: 0,
+  },
+});