@react-navigation/stack 8.0.0-alpha.5 → 8.0.0-alpha.51

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,57 +400,43 @@ 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`.
+     *
+     * 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'
       >;
     };
 
@@ -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.
    */
@@ -513,6 +511,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,12 +539,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/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;
+}

package/src/utils/useKeyboardManager.tsx

@@ -1,12 +1,23 @@
 import * as React from 'react';
 import { type HostInstance, Keyboard, TextInput } from 'react-native';
 
-export function useKeyboardManager(isEnabled: () => boolean) {
+export function useKeyboardManager({
+  enabled,
+  focused,
+  contentRef,
+}: {
+  enabled: boolean;
+  focused: boolean;
+  contentRef: React.RefObject<HostInstance | null>;
+}) {
   // 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 focusedRef = React.useRef(focused);
 
   const clearKeyboardTimeout = React.useCallback(() => {
     if (keyboardTimeoutRef.current !== undefined) {
@@ -16,7 +27,7 @@ export function useKeyboardManager(isEnabled: () => boolean) {
   }, []);
 
   const onPageChangeStart = React.useCallback(() => {
-    if (!isEnabled()) {
+    if (!enabledRef.current || !focusedRef.current) {
       return;
     }
 
@@ -32,37 +43,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 || !focusedRef.current) {
       return;
     }
 
@@ -89,7 +73,86 @@ 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 || !focusedRef.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]);
+
+  // Dismiss keyboard if native focus is restored to an input in an unfocused screen.
+  // This can happen after dismissing a native alert when `autoFocus` is used on iOS.
+  React.useEffect(() => {
+    const blurInputInScreen = () => {
+      if (focusedRef.current || !enabledRef.current) {
+        return;
+      }
+
+      const input = TextInput.State.currentlyFocusedInput();
+
+      if (input && contentRef.current?.contains(input)) {
+        input.blur();
+      }
+    };
+
+    const subscriptions = [
+      Keyboard.addListener('keyboardWillShow', blurInputInScreen),
+      Keyboard.addListener('keyboardDidShow', blurInputInScreen),
+    ];
+
+    return () => {
+      subscriptions.forEach((subscription) => subscription.remove());
+    };
+  }, [contentRef]);
+
+  React.useLayoutEffect(() => {
+    enabledRef.current = enabled;
+    focusedRef.current = focused;
+  });
 
   React.useEffect(() => {
     return () => clearKeyboardTimeout();

package/src/views/GestureHandler.tsx

@@ -1,23 +1,34 @@
 import * as React from 'react';
 import { View } from 'react-native';
-import type { PanGestureHandlerProperties } from 'react-native-gesture-handler';
+import type {
+  PanGesture,
+  PanGestureConfig,
+} from 'react-native-gesture-handler';
 
-const Dummy: any = ({ children }: { children: React.ReactNode }) => (
-  <>{children}</>
-);
+import { GestureHandlerContext } from '../utils/GestureHandlerContext';
 
-export const PanGestureHandler =
-  Dummy as React.ComponentType<PanGestureHandlerProperties>;
+export function GestureDetector({
+  gesture,
+  children,
+}: {
+  gesture: PanGesture | undefined;
+  children: React.ReactNode;
+}) {
+  return (
+    <GestureHandlerContext.Provider value={gesture ?? null}>
+      {children}
+    </GestureHandlerContext.Provider>
+  );
+}
 
-export const GestureHandlerRootView = View;
+// eslint-disable-next-line @eslint-react/hooks-extra/no-unnecessary-use-prefix, @eslint-react/hooks-extra/ensure-custom-hooks-using-other-hooks
+export function usePanGesture(_config: PanGestureConfig) {
+  return undefined;
+}
 
-export const GestureState = {
-  UNDETERMINED: 0,
-  FAILED: 1,
-  BEGAN: 2,
-  CANCELLED: 3,
-  ACTIVE: 4,
-  END: 5,
-};
+export const GestureHandlerRootView = View;
 
-export type { PanGestureHandlerGestureEvent } from 'react-native-gesture-handler';
+export type {
+  PanGesture,
+  PanGestureActiveEvent,
+} from 'react-native-gesture-handler';

package/src/views/GestureHandlerNative.tsx

@@ -1,23 +1,37 @@
 import * as React from 'react';
 import {
-  PanGestureHandler as PanGestureHandlerNative,
-  type PanGestureHandlerProperties,
+  GestureDetector as GestureDetectorNative,
+  type PanGesture,
+  usePanGesture,
 } from 'react-native-gesture-handler';
 
-import { GestureHandlerRefContext } from '../utils/GestureHandlerRefContext';
+import { GestureHandlerContext } from '../utils/GestureHandlerContext';
 
-export function PanGestureHandler(props: PanGestureHandlerProperties) {
-  const gestureRef = React.useRef<PanGestureHandlerNative>(null);
+export function GestureDetector({
+  gesture,
+  children,
+}: {
+  gesture: PanGesture | undefined;
+  children: React.ReactNode;
+}) {
+  if (gesture == null) {
+    throw new Error(
+      'The provided gesture is undefined. A valid gesture must be passed to the GestureDetector on native platforms.'
+    );
+  }
 
   return (
-    <GestureHandlerRefContext.Provider value={gestureRef}>
-      <PanGestureHandlerNative {...props} ref={gestureRef} />
-    </GestureHandlerRefContext.Provider>
+    <GestureHandlerContext.Provider value={gesture}>
+      <GestureDetectorNative gesture={gesture}>
+        {children}
+      </GestureDetectorNative>
+    </GestureHandlerContext.Provider>
   );
 }
 
-export type { PanGestureHandlerGestureEvent } from 'react-native-gesture-handler';
-export {
-  GestureHandlerRootView,
-  State as GestureState,
+export { usePanGesture };
+export type {
+  PanGesture,
+  PanGestureActiveEvent,
 } from 'react-native-gesture-handler';
+export { GestureHandlerRootView } from 'react-native-gesture-handler';

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