@react-navigation/stack 8.0.0-alpha.6 → 8.0.0-alpha.60

package/src/types.tsx

@@ -1,14 +1,13 @@
 import type {
-  HeaderBackButton,
   HeaderBackButtonDisplayMode,
   HeaderBackButtonProps,
   HeaderOptions,
   HeaderTitleProps,
+  Icon,
 } from '@react-navigation/elements';
 import type {
   DefaultNavigatorOptions,
   Descriptor,
-  LocaleDirection,
   NavigationHelpers,
   NavigationProp,
   ParamListBase,
@@ -53,6 +52,7 @@ export type StackNavigationEventMap = {
 
 export type StackNavigationHelpers = NavigationHelpers<
   ParamListBase,
+  StackNavigationState<ParamListBase>,
   StackNavigationEventMap
 > &
   StackActionHelpers<ParamListBase>;
@@ -97,6 +97,9 @@ export type StackAnimationName =
   | 'fade'
   | 'fade_from_bottom'
   | 'fade_from_right'
+  | 'flip'
+  | 'ios_from_left'
+  | 'ios_from_right'
   | 'none'
   | 'reveal_from_bottom'
   | 'scale_from_center'
@@ -107,7 +110,8 @@ export type StackAnimationName =
 type SceneOptionsDefaults = TransitionPreset & {
   animation: StackAnimationName;
   gestureEnabled: boolean;
-  cardOverlayEnabled: boolean;
+  cardOverlayEnabled: boolean | undefined;
+  cardShadowEnabled: boolean | undefined;
   headerMode: StackHeaderMode;
 };
 
@@ -127,6 +131,10 @@ export type Scene = {
    * Animated nodes representing the progress of the animation.
    */
   progress: SceneProgress;
+  /**
+   * Animated node representing whether the screen is closing.
+   */
+  closing: Animated.Value;
 };
 
 export type SceneProgress = {
@@ -138,18 +146,16 @@ 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';
 
-export type StackPresentationMode = 'card' | 'modal';
-
 export type StackHeaderOptions = Omit<
   HeaderOptions,
   'headerLeft' | 'headerTitle' | 'headerRight'
@@ -161,40 +167,43 @@ export type StackHeaderOptions = Omit<
    * It receives `allowFontScaling`, `tintColor`, `style` and `children` in the options object as an argument.
    * The title string is passed in `children`.
    */
-  headerTitle?: string | ((props: HeaderTitleProps) => React.ReactNode);
+  headerTitle?:
+    | string
+    | ((props: HeaderTitleProps) => React.ReactNode)
+    | undefined;
   /**
    * Function which returns a React Element to display on the left side of the header.
    */
-  headerLeft?: (props: StackHeaderLeftProps) => React.ReactNode;
+  headerLeft?: ((props: StackHeaderLeftProps) => React.ReactNode) | undefined;
   /**
    * Function which returns a React Element to display on the right side of the header.
    */
-  headerRight?: (props: StackHeaderRightProps) => React.ReactNode;
+  headerRight?: ((props: StackHeaderRightProps) => React.ReactNode) | undefined;
   /**
    * Whether back button title font should scale to respect Text Size accessibility settings. Defaults to `false`.
    */
-  headerBackAllowFontScaling?: boolean;
+  headerBackAllowFontScaling?: boolean | undefined;
   /**
    * Accessibility label for the header back button.
    */
-  headerBackAccessibilityLabel?: string;
+  headerBackAccessibilityLabel?: string | undefined;
   /**
    * ID to locate this back button in tests.
    */
-  headerBackTestID?: string;
+  headerBackTestID?: string | undefined;
   /**
    * Title string used by the back button on iOS.
    * 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.
    *
@@ -205,37 +214,62 @@ export type StackHeaderOptions = Omit<
    *
    * Defaults to "default" on iOS, and "minimal" on other platforms.
    */
-  headerBackButtonDisplayMode?: HeaderBackButtonDisplayMode;
+  headerBackButtonDisplayMode?: HeaderBackButtonDisplayMode | undefined;
   /**
    * Style object for the back title.
    */
   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)
+    | undefined;
 };
 
 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.
    */
   progress: SceneProgress;
+  /**
+   * Direction multiplier for the transition.
+   */
+  inverted: 1 | -1;
   /**
    * Options for the current screen.
    */
@@ -258,26 +292,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<
@@ -293,48 +327,45 @@ export type StackNavigationOptions = StackHeaderOptions &
     /**
      * String that can be displayed in the header as a fallback for `headerTitle`.
      */
-    title?: string;
+    title?: string | undefined;
     /**
      * Function that given `HeaderProps` returns a React Element to display as a header.
      */
-    header?: (props: StackHeaderProps) => React.ReactNode;
+    header?: ((props: StackHeaderProps) => React.ReactNode) | undefined;
     /**
      * Whether the header floats above the screen or part of the screen.
-     * Defaults to `float` on iOS for non-modals, and `screen` for the rest.
+     * Defaults to `float` on iOS for animations where the header transitions
+     * separately, and `screen` otherwise.
      */
-    headerMode?: StackHeaderMode;
+    headerMode?: StackHeaderMode | undefined;
     /**
      * Whether to show the header. The header is shown by default.
      * Setting this to `false` hides the header.
      */
-    headerShown?: boolean;
+    headerShown?: boolean | undefined;
     /**
-     * Whether a shadow is visible for the card during transitions. Defaults to `true`.
+     * Whether a shadow is visible for the card during transitions.
+     * Defaults to whether `cardStyleInterpolator` returns a `shadowStyle`.
+     * Setting this overrides the default behavior.
      */
-    cardShadowEnabled?: boolean;
+    cardShadowEnabled?: boolean | undefined;
     /**
      * Whether to have a semi-transparent dark overlay visible under the card during transitions.
-     * Defaults to `true` on Android and `false` on iOS.
+     * Defaults to whether `cardStyleInterpolator` returns an `overlayStyle`.
+     * Setting this overrides the default behavior.
      */
-    cardOverlayEnabled?: boolean;
+    cardOverlayEnabled?: boolean | undefined;
     /**
      * Function that returns a React Element to display as a overlay for the card.
      */
-    cardOverlay?: (props: {
-      style: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
-    }) => React.ReactNode;
+    cardOverlay?:
+      | ((props: {
+          style: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
+        }) => React.ReactNode)
+      | undefined;
     /**
      * 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,130 +379,119 @@ 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.
      *
      * Defaults to 'card'.
      */
-    presentation?: 'card' | 'modal' | 'transparentModal';
+    presentation?: 'card' | 'modal' | 'transparentModal' | undefined;
     /**
      * How the screen should animate when pushed or popped.
      *
      * Supported values:
      * - 'none': don't animate the screen
      * - 'default': use the platform default animation
-     * - 'fade': fade screen in or out
+     * - 'fade': fade between screens
      * - 'fade_from_bottom': fade screen in or out from bottom
+     * - 'fade_from_right': fade screen in from the right
+     * - 'flip': flip the screen horizontally
+     * - 'ios_from_left': use the iOS-style slide from left
+     * - 'ios_from_right': use the iOS-style slide from right
      * - 'slide_from_bottom': slide in the new screen from bottom
      * - 'slide_from_right': slide in the new screen from right
      * - 'slide_from_left': slide in the new screen from left
      * - 'reveal_from_bottom': reveal screen in from bottom to top
      * - 'scale_from_center': scale screen in from center
      */
-    animation?: StackAnimationName;
+    animation?: StackAnimationName | undefined;
     /**
      * The type of animation to use when this screen replaces another screen. Defaults to `push`.
      * When `pop` is used, the `pop` animation is applied to the screen being replaced.
      */
-    animationTypeForReplace?: 'push' | 'pop';
+    animationTypeForReplace?: 'push' | 'pop' | undefined;
     /**
-     * Whether you can use gestures to dismiss this screen. Defaults to `true` on iOS, `false` on Android.
+     * Whether you can use gestures to dismiss this screen. Defaults to `true`
+     * on iOS for navigation-style transitions with an interactive dismissal,
+     * and `false` otherwise.
      * Not supported on Web.
      */
-    gestureEnabled?: boolean;
+    gestureEnabled?: boolean | undefined;
     /**
      * Distance of touch start from the edge of the screen to recognize gestures.
      * Not supported on Web.
      */
-    gestureResponseDistance?: number;
+    gestureResponseDistance?: number | undefined;
     /**
      * Number which determines the relevance of velocity for the gesture. Defaults to 0.3.
      * 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;
+    gestureVelocityImpact?: number | undefined;
     /**
      * If `false`, the keyboard will NOT automatically dismiss when navigating to a new screen from this screen.
      * Defaults to `true`.
      */
-    keyboardHandlingEnabled?: boolean;
+    keyboardHandlingEnabled?: boolean | undefined;
+
     /**
-     * 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 =
   | {
       animation: 'spring';
       config: Omit<
         Animated.SpringAnimationConfig,
-        'toValue' | keyof Animated.AnimationConfig
+        'toValue' | 'useNativeDriver' | 'isInteraction' | 'velocity'
       >;
     }
   | {
       animation: 'timing';
       config: Omit<
         Animated.TimingAnimationConfig,
-        'toValue' | keyof Animated.AnimationConfig
+        'toValue' | 'useNativeDriver' | 'isInteraction'
       >;
     };
 
+type StackCardInterpolationState = {
+  /**
+   * Animated node representing the progress value of the screen.
+   */
+  progress: Animated.AnimatedInterpolation<number>;
+  /**
+   * Animated node representing whether the screen is using the closing or
+   * opening animation (1 - closing, 0 - opening).
+   */
+  closing: Animated.AnimatedInterpolation<0 | 1>;
+};
+
 export type StackCardInterpolationProps = {
   /**
    * Values for the current screen.
    */
-  current: {
-    /**
-     * Animated node representing the progress value of the current screen.
-     */
-    progress: Animated.AnimatedInterpolation<number>;
-  };
+  current: StackCardInterpolationState;
   /**
    * 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?: StackCardInterpolationState | undefined;
   /**
    * The index of the card with this interpolation in the stack.
    */
   index: number;
-  /**
-   * Animated node representing whether the card is closing (1 - closing, 0 - not closing).
-   */
-  closing: Animated.AnimatedInterpolation<0 | 1>;
   /**
    * Animated node representing whether the card is being swiped (1 - swiping, 0 - not swiping).
    */
@@ -513,6 +533,10 @@ export type StackCardInterpolatedStyle = {
    * Interpolated style for the view representing the semi-transparent overlay below the card.
    */
   overlayStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
+  /**
+   * Interpolated style for dim on top of the card content.
+   */
+  dimStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
   /**
    * Interpolated style representing the card shadow.
    */
@@ -537,16 +561,18 @@ 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.
+   * Direction multiplier for the transition.
    */
-  direction: LocaleDirection;
+  inverted: 1 | -1;
   /**
    * Layout measurements for various items we use for animation.
    */
@@ -566,19 +592,19 @@ export type StackHeaderInterpolatedStyle = {
   /**
    * Interpolated style for the left button (usually the back button).
    */
-  leftButtonStyle?: Animated.WithAnimatedValue<ViewStyle>;
+  leftButtonStyle?: Animated.WithAnimatedValue<ViewStyle> | undefined;
   /**
    * Interpolated style for the right button.
    */
-  rightButtonStyle?: Animated.WithAnimatedValue<ViewStyle>;
+  rightButtonStyle?: Animated.WithAnimatedValue<ViewStyle> | undefined;
   /**
    * Interpolated style for the header title text.
    */
-  titleStyle?: Animated.WithAnimatedValue<TextStyle>;
+  titleStyle?: Animated.WithAnimatedValue<TextStyle> | undefined;
   /**
    * Interpolated style for the header background.
    */
-  backgroundStyle?: Animated.WithAnimatedValue<ViewStyle>;
+  backgroundStyle?: Animated.WithAnimatedValue<ViewStyle> | undefined;
 };
 
 export type StackHeaderStyleInterpolator = (

package/src/utils/GestureHandlerContext.tsx

@@ -0,0 +1,5 @@
+import * as React from 'react';
+
+export const GestureHandlerContext = React.createContext<
+  import('react-native-gesture-handler').PanGesture | null
+>(null);

package/src/utils/gestureActivationCriteria.tsx

@@ -1,4 +1,5 @@
 import type { LocaleDirection } from '@react-navigation/native';
+import type { PanGestureConfig } from 'react-native-gesture-handler';
 
 import type { GestureDirection, Layout } from '../types';
 import { getInvertedMultiplier } from './getInvertedMultiplier';
@@ -17,9 +18,9 @@ export const gestureActivationCriteria = ({
 }: {
   direction: LocaleDirection;
   gestureDirection: GestureDirection;
-  gestureResponseDistance?: number;
+  gestureResponseDistance?: number | undefined;
   layout: Layout;
-}) => {
+}): PanGestureConfig => {
   const enableTrackpadTwoFingerGesture = true;
 
   const distance =
@@ -30,17 +31,20 @@ export const gestureActivationCriteria = ({
         ? GESTURE_RESPONSE_DISTANCE_VERTICAL
         : GESTURE_RESPONSE_DISTANCE_HORIZONTAL;
 
+  const failOffsetX: [number, number] = [-15, 15];
+  const failOffsetY: [number, number] = [-20, 20];
+
   if (gestureDirection === 'vertical') {
     return {
-      maxDeltaX: 15,
-      minOffsetY: 5,
+      failOffsetX,
+      activeOffsetY: 5,
       hitSlop: { bottom: -layout.height + distance },
       enableTrackpadTwoFingerGesture,
     };
   } else if (gestureDirection === 'vertical-inverted') {
     return {
-      maxDeltaX: 15,
-      minOffsetY: -5,
+      failOffsetX,
+      activeOffsetY: -5,
       hitSlop: { top: -layout.height + distance },
       enableTrackpadTwoFingerGesture,
     };
@@ -53,15 +57,15 @@ export const gestureActivationCriteria = ({
 
     if (invertedMultiplier === 1) {
       return {
-        minOffsetX: 5,
-        maxDeltaY: 20,
+        activeOffsetX: 5,
+        failOffsetY,
         hitSlop: { right: hitSlop },
         enableTrackpadTwoFingerGesture,
       };
     } else {
       return {
-        minOffsetX: -5,
-        maxDeltaY: 20,
+        activeOffsetX: -5,
+        failOffsetY,
         hitSlop: { left: hitSlop },
         enableTrackpadTwoFingerGesture,
       };

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/useGestureHandler.tsx

@@ -0,0 +1,9 @@
+import * as React from 'react';
+
+import { GestureHandlerContext } from './GestureHandlerContext';
+
+export function useGestureHandler() {
+  const gesture = React.useContext(GestureHandlerContext);
+
+  return gesture;
+}