@react-navigation/native-stack 7.0.0-alpha.2 → 7.0.0-alpha.20

package/src/types.tsx

@@ -9,6 +9,7 @@ import type {
   StackActionHelpers,
   StackNavigationState,
   StackRouterOptions,
+  Theme,
 } from '@react-navigation/native';
 import type {
   ImageSourcePropType,
@@ -20,6 +21,7 @@ import type {
   ScreenProps,
   ScreenStackHeaderConfigProps,
   SearchBarProps,
+  SheetDetentTypes,
 } from 'react-native-screens';
 
 export type NativeStackNavigationEventMap = {
@@ -31,12 +33,16 @@ export type NativeStackNavigationEventMap = {
    * Event which fires when a transition animation ends.
    */
   transitionEnd: { data: { closing: boolean } };
+  /**
+   * Event which fires when a swipe back is canceled on iOS.
+   */
+  gestureCancel: { data: undefined };
 };
 
 export type NativeStackNavigationProp<
   ParamList extends ParamListBase,
   RouteName extends keyof ParamList = string,
-  NavigatorID extends string | undefined = undefined
+  NavigatorID extends string | undefined = undefined,
 > = NavigationProp<
   ParamList,
   RouteName,
@@ -50,12 +56,20 @@ export type NativeStackNavigationProp<
 export type NativeStackScreenProps<
   ParamList extends ParamListBase,
   RouteName extends keyof ParamList = string,
-  NavigatorID extends string | undefined = undefined
+  NavigatorID extends string | undefined = undefined,
 > = {
   navigation: NativeStackNavigationProp<ParamList, RouteName, NavigatorID>;
   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
@@ -72,7 +86,11 @@ export type NativeStackHeaderProps = {
     /**
      * Title of the previous screen.
      */
-    title: string;
+    title: string | undefined;
+    /**
+     * The `href` to use for the anchor tag on web
+     */
+    href: string | undefined;
   };
   /**
    * Options for the current screen.
@@ -88,7 +106,7 @@ export type NativeStackHeaderProps = {
   navigation: NativeStackNavigationProp<ParamListBase>;
 };
 
-export type HeaderButtonProps = {
+export type NativeStackHeaderRightProps = {
   /**
    * Tint color for the header.
    */
@@ -99,12 +117,16 @@ export type HeaderButtonProps = {
   canGoBack: boolean;
 };
 
-export type HeaderBackButtonProps = HeaderButtonProps & {
+export type NativeStackHeaderLeftProps = NativeStackHeaderRightProps & {
   /**
    * Label text for the button. Usually the title of the previous screen.
    * 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 = {
@@ -258,11 +280,11 @@ export type NativeStackNavigationOptions = {
    * Function which returns a React Element to display on the left side of the header.
    * This replaces the back button. See `headerBackVisible` to show the back button along side left element.
    */
-  headerLeft?: (props: HeaderBackButtonProps) => React.ReactNode;
+  headerLeft?: (props: NativeStackHeaderLeftProps) => React.ReactNode;
   /**
    * Function which returns a React Element to display on the right side of the header.
    */
-  headerRight?: (props: HeaderButtonProps) => React.ReactNode;
+  headerRight?: (props: NativeStackHeaderRightProps) => React.ReactNode;
   /**
    * String or a function that returns a React Element to be used by the header.
    * Defaults to screen `title` or route name.
@@ -326,6 +348,12 @@ export type NativeStackNavigationOptions = {
    * @platform ios
    */
   autoHideHomeIndicator?: boolean;
+  /**
+   * Whether the keyboard should hide when swiping to the previous screen. Defaults to `false`.
+   *
+   * @platform ios
+   */
+  keyboardHandlingEnabled?: boolean;
   /**
    * Sets the navigation bar color. Defaults to initial navigation bar color.
    *
@@ -352,7 +380,7 @@ export type NativeStackNavigationOptions = {
    *
    * @platform android
    */
-  statusBarColor?: string;
+  statusBarBackgroundColor?: string;
   /**
    * Whether the status bar should be hidden on this screen.
    * Requires setting `View controller-based status bar appearance -> YES` in your Info.plist file.
@@ -379,7 +407,7 @@ export type NativeStackNavigationOptions = {
   statusBarTranslucent?: boolean;
   /**
    * Sets the direction in which you should swipe to dismiss the screen.
-   * When using `vertical` option, options `fullScreenGestureEnabled: true`, `customAnimationOnGesture: true` and `animation: 'slide_from_bottom'` are set by default.
+   * When using `vertical` option, options `fullScreenGestureEnabled: true`, `animationMatchesGesture: true` and `animation: 'slide_from_bottom'` are set by default.
    *
    * Supported values:
    * - `vertical` – dismiss screen vertically
@@ -399,10 +427,10 @@ export type NativeStackNavigationOptions = {
    *
    * @platform ios
    */
-  customAnimationOnGesture?: boolean;
+  animationMatchesGesture?: boolean;
   /**
    * Whether the gesture to dismiss should work on the whole screen. Using gesture to dismiss with this option results in the same
-   * transition animation as `simple_push`. This behavior can be changed by setting `customAnimationOnGesture` prop. Achieving the
+   * transition animation as `simple_push`. This behavior can be changed by setting `animationMatchesGesture` prop. Achieving the
    * default iOS animation isn't possible due to platform limitations. Defaults to `false`.
    *
    * Doesn't affect the behavior of screens presented modally.
@@ -418,6 +446,12 @@ export type NativeStackNavigationOptions = {
    * @platform ios
    */
   gestureEnabled?: boolean;
+  /**
+   * Use it to restrict the distance from the edges of screen in which the gesture should be recognized. To be used alongside `fullScreenGestureEnabled`.
+   *
+   * @platform ios
+   */
+  gestureResponseDistance?: ScreenProps['gestureResponseDistance'];
   /**
    * The type of animation to use when this screen replaces another screen. Defaults to `pop`.
    *
@@ -466,6 +500,62 @@ export type NativeStackNavigationOptions = {
    * Only supported on iOS and Android.
    */
   presentation?: Exclude<ScreenProps['stackPresentation'], 'push'> | 'card';
+  /**
+   * Describes heights where a sheet can rest.
+   * Works only when `presentation` is set to `formSheet`.
+   * Defaults to `large`.
+   *
+   * Available values:
+   *
+   * - `large` - only large detent level will be allowed
+   * - `medium` - only medium detent level will be allowed
+   * - `all` - all detent levels will be allowed
+   *
+   * @platform ios
+   */
+  sheetAllowedDetents?: SheetDetentTypes;
+  /**
+   * Whether the sheet should expand to larger detent when scrolling.
+   * Works only when `presentation` is set to `formSheet`.
+   * Defaults to `true`.
+   *
+   * @platform ios
+   */
+  sheetExpandsWhenScrolledToEdge?: boolean;
+  /**
+   * The corner radius that the sheet will try to render with.
+   * Works only when `presentation` is set to `formSheet`.
+   *
+   * If set to non-negative value it will try to render sheet with provided radius, else it will apply system default.
+   *
+   * If left unset system default is used.
+   *
+   * @platform ios
+   */
+  sheetCornerRadius?: number;
+  /**
+   * Boolean indicating whether the sheet shows a grabber at the top.
+   * Works only when `presentation` is set to `formSheet`.
+   * Defaults to `false`.
+   *
+   * @platform ios
+   */
+  sheetGrabberVisible?: boolean;
+  /**
+   * The largest sheet detent for which a view underneath won't be dimmed.
+   * Works only when `presentation` is se tto `formSheet`.
+   *
+   * If this prop is set to:
+   *
+   * - `large` - the view underneath won't be dimmed at any detent level
+   * - `medium` - the view underneath will be dimmed only when detent level is `large`
+   * - `all` - the view underneath will be dimmed for any detent level
+   *
+   * Defaults to `all`.
+   *
+   * @platform ios
+   */
+  sheetLargestUndimmedDetent?: SheetDetentTypes;
   /**
    * The display orientation to use for the screen.
    *
@@ -494,9 +584,11 @@ export type NativeStackNavigationOptions = {
 
 export type NativeStackNavigatorProps = DefaultNavigatorOptions<
   ParamListBase,
+  string | undefined,
   StackNavigationState<ParamListBase>,
   NativeStackNavigationOptions,
-  NativeStackNavigationEventMap
+  NativeStackNavigationEventMap,
+  NativeStackNavigationProp<ParamListBase>
 > &
   StackRouterOptions &
   NativeStackNavigationConfig;

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

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { Animated } from 'react-native';
+
+export const AnimatedHeaderHeightContext = React.createContext<
+  Animated.Value | undefined
+>(undefined);
+
+export function useAnimatedHeaderHeight() {
+  const animatedValue = React.useContext(AnimatedHeaderHeightContext);
+
+  if (animatedValue === undefined) {
+    throw new Error(
+      "Couldn't find the header height. Are you inside a screen in a native stack navigator?"
+    );
+  }
+
+  return animatedValue;
+}

package/src/views/DebugContainer.native.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { Platform, View, ViewProps } from 'react-native';
-// @ts-ignore Getting private component
+import { Platform, View, type ViewProps } from 'react-native';
+// @ts-expect-error Getting private component
 import AppContainer from 'react-native/Libraries/ReactNative/AppContainer';
 import type { StackPresentationTypes } from 'react-native-screens';
 
@@ -9,8 +9,14 @@ type ContainerProps = ViewProps & {
   children: React.ReactNode;
 };
 
-export let DebugContainer =
-  View as unknown as React.ComponentType<ContainerProps>;
+/**
+ * This view must *not* be flattened.
+ * See https://github.com/software-mansion/react-native-screens/pull/1825
+ * for detailed explanation.
+ */
+export let DebugContainer = (props: ContainerProps) => {
+  return <View {...props} collapsable={false} />;
+};
 
 if (process.env.NODE_ENV !== 'production') {
   DebugContainer = (props: ContainerProps) => {
@@ -20,11 +26,11 @@ if (process.env.NODE_ENV !== 'production') {
       // This is necessary for LogBox
       return (
         <AppContainer>
-          <View {...rest} />
+          <View {...rest} collapsable={false} />
         </AppContainer>
       );
     }
 
-    return <View {...rest} />;
+    return <View {...rest} collapsable={false} />;
   };
 }

package/src/views/DebugContainer.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { View, ViewProps } from 'react-native';
+import { View, type ViewProps } from 'react-native';
 import type { StackPresentationTypes } from 'react-native-screens';
 
 type ContainerProps = ViewProps & {

package/src/views/FontProcessor.native.tsx

@@ -1,10 +1,9 @@
-// @ts-ignore: No declaration available
+// @ts-expect-error importing private module
 import ReactNativeStyleAttributes from 'react-native/Libraries/Components/View/ReactNativeStyleAttributes';
 
 export function processFonts(
   fontFamilies: (string | undefined)[]
 ): (string | undefined)[] {
-  // @ts-ignore: React Native types are incorrect here and don't consider fontFamily a style value
   const fontFamilyProcessor = ReactNativeStyleAttributes.fontFamily?.process;
   if (typeof fontFamilyProcessor === 'function') {
     return fontFamilies.map(fontFamilyProcessor);

package/src/views/HeaderConfig.tsx

@@ -1,13 +1,7 @@
 import { getHeaderTitle, HeaderTitle } from '@react-navigation/elements';
-import { Route, useTheme } from '@react-navigation/native';
+import { type Route, useLocale, useTheme } from '@react-navigation/native';
 import * as React from 'react';
-import {
-  I18nManager,
-  Platform,
-  StyleSheet,
-  TextStyle,
-  View,
-} from 'react-native';
+import { Platform, StyleSheet, type TextStyle, View } from 'react-native';
 import {
   isSearchBarAvailableForCurrentPlatform,
   ScreenStackHeaderBackButtonImage,
@@ -30,7 +24,6 @@ type Props = NativeStackNavigationOptions & {
 };
 
 export function HeaderConfig({
-  headerHeight,
   headerBackImageSource,
   headerBackButtonMenuEnabled,
   headerBackTitle,
@@ -59,21 +52,22 @@ export function HeaderConfig({
   title,
   canGoBack,
 }: Props): JSX.Element {
+  const { direction } = useLocale();
   const { colors, fonts } = useTheme();
   const tintColor =
     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) || {};
@@ -136,6 +130,8 @@ export function HeaderConfig({
     tintColor,
     canGoBack,
     label: headerBackTitle,
+    // `href` is only applicable to web
+    href: undefined,
   });
   const headerRightElement = headerRight?.({
     tintColor,
@@ -182,118 +178,105 @@ export function HeaderConfig({
       headerTransparent !== false);
 
   return (
-    <>
-      {headerBackground != null ? (
-        <View
-          style={[
-            styles.background,
-            headerTransparent ? styles.translucent : null,
-            { height: headerHeight },
-          ]}
-        >
-          {headerBackground()}
-        </View>
-      ) : null}
-      <ScreenStackHeaderConfig
-        backButtonInCustomView={backButtonInCustomView}
-        backgroundColor={headerBackgroundColor}
-        backTitle={headerBackTitleVisible ? headerBackTitle : ' '}
-        backTitleFontFamily={backTitleFontFamily}
-        backTitleFontSize={backTitleFontSize}
-        blurEffect={headerBlurEffect}
-        color={tintColor}
-        direction={I18nManager.getConstants().isRTL ? 'rtl' : 'ltr'}
-        disableBackButtonMenu={headerBackButtonMenuEnabled === false}
-        hidden={headerShown === false}
-        hideBackButton={headerBackVisible === false}
-        hideShadow={
-          headerShadowVisible === false ||
-          headerBackground != null ||
-          (headerTransparent && headerShadowVisible !== true)
-        }
-        largeTitle={headerLargeTitle}
-        largeTitleBackgroundColor={largeTitleBackgroundColor}
-        largeTitleColor={largeTitleColor}
-        largeTitleFontFamily={largeTitleFontFamily}
-        largeTitleFontSize={largeTitleFontSize}
-        largeTitleFontWeight={largeTitleFontWeight}
-        largeTitleHideShadow={headerLargeTitleShadowVisible === false}
-        title={titleText}
-        titleColor={titleColor}
-        titleFontFamily={titleFontFamily}
-        titleFontSize={titleFontSize}
-        titleFontWeight={titleFontWeight}
-        topInsetEnabled={headerTopInsetEnabled}
-        translucent={
-          // This defaults to `true`, so we can't pass `undefined`
-          translucent === true
-        }
-      >
-        {Platform.OS === 'ios' ? (
-          <>
-            {headerLeftElement != null ? (
-              <ScreenStackHeaderLeftView>
+    <ScreenStackHeaderConfig
+      backButtonInCustomView={backButtonInCustomView}
+      backgroundColor={headerBackgroundColor}
+      backTitle={headerBackTitleVisible ? headerBackTitle : ' '}
+      backTitleFontFamily={backTitleFontFamily}
+      backTitleFontSize={backTitleFontSize}
+      blurEffect={headerBlurEffect}
+      color={tintColor}
+      direction={direction}
+      disableBackButtonMenu={headerBackButtonMenuEnabled === false}
+      hidden={headerShown === false}
+      hideBackButton={headerBackVisible === false}
+      hideShadow={
+        headerShadowVisible === false ||
+        headerBackground != null ||
+        (headerTransparent && headerShadowVisible !== true)
+      }
+      largeTitle={headerLargeTitle}
+      largeTitleBackgroundColor={largeTitleBackgroundColor}
+      largeTitleColor={largeTitleColor}
+      largeTitleFontFamily={largeTitleFontFamily}
+      largeTitleFontSize={largeTitleFontSize}
+      largeTitleFontWeight={largeTitleFontWeight}
+      largeTitleHideShadow={headerLargeTitleShadowVisible === false}
+      title={titleText}
+      titleColor={titleColor}
+      titleFontFamily={titleFontFamily}
+      titleFontSize={titleFontSize}
+      titleFontWeight={titleFontWeight}
+      topInsetEnabled={headerTopInsetEnabled}
+      translucent={
+        // This defaults to `true`, so we can't pass `undefined`
+        translucent === true
+      }
+    >
+      {Platform.OS === 'ios' ? (
+        <>
+          {headerLeftElement != null ? (
+            <ScreenStackHeaderLeftView>
+              {headerLeftElement}
+            </ScreenStackHeaderLeftView>
+          ) : null}
+          {headerTitleElement != null ? (
+            <ScreenStackHeaderCenterView>
+              {headerTitleElement}
+            </ScreenStackHeaderCenterView>
+          ) : null}
+        </>
+      ) : (
+        <>
+          {headerLeftElement != null || typeof headerTitle === 'function' ? (
+            <ScreenStackHeaderLeftView>
+              <View style={styles.row}>
                 {headerLeftElement}
-              </ScreenStackHeaderLeftView>
-            ) : null}
-            {headerTitleElement != null ? (
-              <ScreenStackHeaderCenterView>
-                {headerTitleElement}
-              </ScreenStackHeaderCenterView>
-            ) : null}
-          </>
-        ) : (
-          <>
-            {headerLeftElement != null || typeof headerTitle === 'function' ? (
-              <ScreenStackHeaderLeftView>
-                <View style={styles.row}>
-                  {headerLeftElement}
-                  {headerTitleAlign !== 'center' ? (
-                    typeof headerTitle === 'function' ? (
-                      headerTitleElement
-                    ) : (
-                      <HeaderTitle
-                        tintColor={tintColor}
-                        style={headerTitleStyleSupported}
-                      >
-                        {titleText}
-                      </HeaderTitle>
-                    )
-                  ) : null}
-                </View>
-              </ScreenStackHeaderLeftView>
-            ) : null}
-            {headerTitleAlign === 'center' ? (
-              <ScreenStackHeaderCenterView>
-                {typeof headerTitle === 'function' ? (
-                  headerTitleElement
-                ) : (
-                  <HeaderTitle
-                    tintColor={tintColor}
-                    style={headerTitleStyleSupported}
-                  >
-                    {titleText}
-                  </HeaderTitle>
-                )}
-              </ScreenStackHeaderCenterView>
-            ) : null}
-          </>
-        )}
-        {headerBackImageSource !== undefined ? (
-          <ScreenStackHeaderBackButtonImage source={headerBackImageSource} />
-        ) : null}
-        {headerRightElement != null ? (
-          <ScreenStackHeaderRightView>
-            {headerRightElement}
-          </ScreenStackHeaderRightView>
-        ) : null}
-        {hasHeaderSearchBar ? (
-          <ScreenStackHeaderSearchBarView>
-            <SearchBar {...headerSearchBarOptions} />
-          </ScreenStackHeaderSearchBarView>
-        ) : null}
-      </ScreenStackHeaderConfig>
-    </>
+                {headerTitleAlign !== 'center' ? (
+                  typeof headerTitle === 'function' ? (
+                    headerTitleElement
+                  ) : (
+                    <HeaderTitle
+                      tintColor={tintColor}
+                      style={headerTitleStyleSupported}
+                    >
+                      {titleText}
+                    </HeaderTitle>
+                  )
+                ) : null}
+              </View>
+            </ScreenStackHeaderLeftView>
+          ) : null}
+          {headerTitleAlign === 'center' ? (
+            <ScreenStackHeaderCenterView>
+              {typeof headerTitle === 'function' ? (
+                headerTitleElement
+              ) : (
+                <HeaderTitle
+                  tintColor={tintColor}
+                  style={headerTitleStyleSupported}
+                >
+                  {titleText}
+                </HeaderTitle>
+              )}
+            </ScreenStackHeaderCenterView>
+          ) : null}
+        </>
+      )}
+      {headerBackImageSource !== undefined ? (
+        <ScreenStackHeaderBackButtonImage source={headerBackImageSource} />
+      ) : null}
+      {headerRightElement != null ? (
+        <ScreenStackHeaderRightView>
+          {headerRightElement}
+        </ScreenStackHeaderRightView>
+      ) : null}
+      {hasHeaderSearchBar ? (
+        <ScreenStackHeaderSearchBarView>
+          <SearchBar {...headerSearchBarOptions} />
+        </ScreenStackHeaderSearchBarView>
+      ) : null}
+    </ScreenStackHeaderConfig>
   );
 }
 
@@ -302,15 +285,4 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     alignItems: 'center',
   },
-  translucent: {
-    position: 'absolute',
-    top: 0,
-    left: 0,
-    right: 0,
-    zIndex: 1,
-    elevation: 1,
-  },
-  background: {
-    overflow: 'hidden',
-  },
 });