react-native-screen-transitions 3.4.0-alpha.0 → 3.4.0-alpha.2

package/src/shared/components/overlay/variations/overlay-host.tsx

@@ -3,13 +3,11 @@ import {
 	NavigationRouteContext,
 } from "@react-navigation/native";
 import { memo, useMemo } from "react";
-import { Animated, StyleSheet, useWindowDimensions, View } from "react-native";
+import { Animated, StyleSheet, View } from "react-native";
 import { useDerivedValue } from "react-native-reanimated";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
 import type { StackScene } from "../../../hooks/navigation/use-stack";
 import { useScreenAnimation } from "../../../providers/screen/animation";
 import type { BaseDescriptor } from "../../../providers/screen/descriptors";
-import type { OverlayInterpolationProps } from "../../../types/animation.types";
 import type {
 	OverlayProps,
 	OverlayScreenState,
@@ -25,8 +23,6 @@ export const OverlayHost = memo(function OverlayHost({
 	overlayScreenState,
 }: OverlayHostProps) {
 	const OverlayComponent = scene.descriptor.options.overlay;
-	const screen = useWindowDimensions();
-	const insets = useSafeAreaInsets();
 
 	const screenAnimation = useScreenAnimation();
 	const relativeProgress = useDerivedValue(() => {
@@ -34,22 +30,12 @@ export const OverlayHost = memo(function OverlayHost({
 		return screenAnimation.value.stackProgress;
 	});
 
-	const overlayAnimation = useDerivedValue<OverlayInterpolationProps>(() => ({
-		progress: relativeProgress.value,
-		layouts: { screen },
-		insets,
-	}));
-
 	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(
 		() => ({
 			...overlayScreenState,
 			progress: relativeProgress,
-			/**@deprecated */
-			overlayAnimation,
-			/**@deprecated */
-			screenAnimation,
 		}),
-		[relativeProgress, overlayAnimation, screenAnimation, overlayScreenState],
+		[relativeProgress, overlayScreenState],
 	);
 
 	if (!OverlayComponent) {

package/src/shared/components/scene-view.tsx

@@ -4,8 +4,6 @@ import {
 } from "@react-navigation/native";
 import * as React from "react";
 import type { BaseStackDescriptor } from "../types/stack.types";
-import { isScreenOverlayVisible } from "../utils/overlay/visibility";
-import { Overlay } from "./overlay";
 
 type SceneViewProps = {
 	descriptor: BaseStackDescriptor;
@@ -24,7 +22,6 @@ export const SceneView = React.memo(function SceneView({
 	return (
 		<NavigationContext.Provider value={navigation as any}>
 			<NavigationRouteContext.Provider value={route}>
-				{isScreenOverlayVisible(descriptor.options) && <Overlay.Screen />}
 				{render?.()}
 			</NavigationRouteContext.Provider>
 		</NavigationContext.Provider>

package/src/shared/components/screen-container/hooks/use-content-layout.ts

@@ -0,0 +1,82 @@
+import { useCallback } from "react";
+import { type LayoutChangeEvent, useWindowDimensions } from "react-native";
+import { runOnUI } from "react-native-reanimated";
+import {
+	useDescriptorDerivations,
+	useDescriptors,
+} from "../../../providers/screen/descriptors";
+import { AnimationStore } from "../../../stores/animation.store";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+
+export function useContentLayout() {
+	const { current } = useDescriptors();
+	const { isFirstKey } = useDescriptorDerivations();
+	const { height: screenHeight } = useWindowDimensions();
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getRouteAnimations(routeKey);
+	const autoSnapPointValue = AnimationStore.getAnimation(
+		routeKey,
+		"autoSnapPoint",
+	);
+	const contentLayoutValue = AnimationStore.getAnimation(
+		routeKey,
+		"contentLayout",
+	);
+
+	return useCallback(
+		(event: LayoutChangeEvent) => {
+			const { width, height } = event.nativeEvent.layout;
+			if (width <= 0 || height <= 0) return;
+
+			const fraction = Math.min(height / screenHeight, 1);
+			const transitionSpec = current.options.transitionSpec;
+
+			runOnUI(
+				(
+					nextWidth: number,
+					nextHeight: number,
+					nextFraction: number,
+					isInitialScreen: boolean,
+					spec: typeof transitionSpec,
+				) => {
+					"worklet";
+					contentLayoutValue.value = {
+						width: nextWidth,
+						height: nextHeight,
+					};
+
+					const isFirstMeasurement = autoSnapPointValue.value <= 0;
+					autoSnapPointValue.value = nextFraction;
+
+					if (
+						!isFirstMeasurement ||
+						animations.progress.value !== 0 ||
+						animations.animating.value !== 0
+					) {
+						return;
+					}
+
+					if (isInitialScreen) {
+						animations.targetProgress.value = nextFraction;
+						animations.progress.value = nextFraction;
+						return;
+					}
+
+					animateToProgress({
+						target: nextFraction,
+						spec,
+						animations,
+					});
+				},
+			)(width, height, fraction, isFirstKey, transitionSpec);
+		},
+		[
+			animations,
+			autoSnapPointValue,
+			contentLayoutValue,
+			current.options.transitionSpec,
+			isFirstKey,
+			screenHeight,
+		],
+	);
+}

package/src/shared/components/screen-container/layers/backdrop.tsx

@@ -23,6 +23,12 @@ export const BackdropLayer = memo(function BackdropLayer() {
 	const { isBackdropActive, backdropBehavior } = useBackdropPointerEvents();
 
 	const BackdropComponent = current.options.backdropComponent;
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getRouteAnimations(routeKey);
+	const autoSnapPointValue = AnimationStore.getAnimation(
+		routeKey,
+		"autoSnapPoint",
+	);
 
 	const AnimatedBackdropComponent = useMemo(
 		() =>
@@ -38,24 +44,27 @@ export const BackdropLayer = memo(function BackdropLayer() {
 		}
 
 		if (backdropBehavior === "collapse") {
-			const snapPoints = current.options.snapPoints;
+			const rawSnapPoints = current.options.snapPoints;
 			const canDismiss = current.options.gestureEnabled !== false;
 
 			// No snap points → fallback to dismiss
-			if (!snapPoints || snapPoints.length === 0) {
+			if (!rawSnapPoints || rawSnapPoints.length === 0) {
 				dismissScreen();
 				return;
 			}
 
-			const animations = AnimationStore.getRouteAnimations(current.route.key);
-			const gestures = GestureStore.getRouteGestures(current.route.key);
+			const gestures = GestureStore.getRouteGestures(routeKey);
 			const transitionSpec = current.options.transitionSpec;
 
 			runOnUI(() => {
 				"worklet";
+				const resolvedSnaps = rawSnapPoints
+					.map((point) => (point === "auto" ? autoSnapPointValue.value : point))
+					.filter((point): point is number => typeof point === "number");
+
 				const { target, shouldDismiss } = findCollapseTarget(
 					animations.progress.value,
-					snapPoints,
+					resolvedSnaps,
 					canDismiss,
 				);
 
@@ -79,7 +88,14 @@ export const BackdropLayer = memo(function BackdropLayer() {
 				});
 			})();
 		}
-	}, [backdropBehavior, current, dismissScreen]);
+	}, [
+		animations,
+		autoSnapPointValue,
+		backdropBehavior,
+		current,
+		dismissScreen,
+		routeKey,
+	]);
 
 	const animatedBackdropStyle = useAnimatedStyle(() => {
 		"worklet";
@@ -97,6 +113,9 @@ export const BackdropLayer = memo(function BackdropLayer() {
 			pointerEvents={isBackdropActive ? "auto" : "none"}
 			onPress={isBackdropActive ? handleBackdropPress : undefined}
 		>
+			{/* Keep blur props and visual style separated.
+			 * BlurView's animatable ref points at the inner native blur view, and mixing
+			 * animated style with animatedProps can break intensity updates. */}
 			{AnimatedBackdropComponent && (
 				<AnimatedBackdropComponent
 					style={[StyleSheet.absoluteFillObject]}

package/src/shared/components/screen-container/layers/content.tsx

@@ -1,47 +1,36 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <Screen gesture is under the gesture context, so this will always exist.> */
-import { memo, useEffect } from "react";
+import { memo } from "react";
 import { StyleSheet, View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, {
 	useAnimatedProps,
 	useAnimatedStyle,
 } from "react-native-reanimated";
-import {
-	NAVIGATION_CONTAINER_STYLE_ID,
-	NAVIGATION_MASK_STYLE_ID,
-	NO_PROPS,
-	NO_STYLES,
-} from "../../../constants";
+import { NO_PROPS, NO_STYLES } from "../../../constants";
 import { useGestureContext } from "../../../providers/gestures";
 import { useDescriptors } from "../../../providers/screen/descriptors";
 import { useScreenStyles } from "../../../providers/screen/styles.provider";
-import { logger } from "../../../utils/logger";
+import { resolveNavigationMaskEnabled } from "../../../utils/resolve-screen-transition-options";
 import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
+import { useContentLayout } from "../hooks/use-content-layout";
+import { MaybeMaskedNavigationContainer } from "./maybe-masked-navigation-container";
 import { SurfaceContainer } from "./surface-container";
 
 type Props = {
 	children: React.ReactNode;
 };
 
-let LazyMaskedView = View;
-
-try {
-	LazyMaskedView = require("@react-native-masked-view/masked-view").default;
-} catch (_) {
-	// optional peer dependency
-}
-
-let hasWarnedMissingMaskedView = false;
-
 export const ContentLayer = memo(({ children }: Props) => {
 	const { stylesMap } = useScreenStyles();
 	const { current } = useDescriptors();
 	const { pointerEvents, isBackdropActive } = useBackdropPointerEvents();
 	const gestureContext = useGestureContext();
-	const isNavigationMaskEnabled = !!current.options.maskEnabled;
+	const isNavigationMaskEnabled = resolveNavigationMaskEnabled(current.options);
 	const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
+	const hasAutoSnapPoint =
+		current.options.snapPoints?.includes("auto") ?? false;
+	const handleContentLayout = useContentLayout();
 
-	// ── Content ──
 	const animatedContentStyle = useAnimatedStyle(() => {
 		"worklet";
 		return stylesMap.value.content?.style || NO_STYLES;
@@ -52,56 +41,6 @@ export const ContentLayer = memo(({ children }: Props) => {
 		return stylesMap.value.content?.props ?? NO_PROPS;
 	});
 
-	// ── Navigation mask / container ──
-	const animatedNavigationContainerStyle = useAnimatedStyle(() => {
-		"worklet";
-		return stylesMap.value[NAVIGATION_CONTAINER_STYLE_ID]?.style || NO_STYLES;
-	});
-
-	const animatedNavigationMaskStyle = useAnimatedStyle(() => {
-		"worklet";
-		return stylesMap.value[NAVIGATION_MASK_STYLE_ID]?.style || NO_STYLES;
-	});
-
-	useEffect(() => {
-		if (!isNavigationMaskEnabled) return;
-		if (LazyMaskedView !== View) return;
-		if (hasWarnedMissingMaskedView) return;
-
-		hasWarnedMissingMaskedView = true;
-		logger.warn(
-			"maskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
-		);
-	}, [isNavigationMaskEnabled]);
-
-	const contentChildren = isNavigationMaskEnabled ? (
-		LazyMaskedView !== View ? (
-			<LazyMaskedView
-				style={styles.navigationMaskedRoot}
-				// @ts-expect-error masked-view package types are too strict here
-				maskElement={
-					<Animated.View
-						style={[styles.navigationMaskElement, animatedNavigationMaskStyle]}
-					/>
-				}
-			>
-				<Animated.View
-					style={[styles.navigationContainer, animatedNavigationContainerStyle]}
-				>
-					{children}
-				</Animated.View>
-			</LazyMaskedView>
-		) : (
-			<Animated.View
-				style={[styles.navigationContainer, animatedNavigationContainerStyle]}
-			>
-				{children}
-			</Animated.View>
-		)
-	) : (
-		children
-	);
-
 	return (
 		<GestureDetector gesture={gestureContext!.panGesture}>
 			<Animated.View
@@ -109,9 +48,20 @@ export const ContentLayer = memo(({ children }: Props) => {
 				animatedProps={animatedContentProps}
 				pointerEvents={contentPointerEvents}
 			>
-				<SurfaceContainer pointerEvents={contentPointerEvents}>
-					{contentChildren}
-				</SurfaceContainer>
+				<MaybeMaskedNavigationContainer
+					pointerEvents={contentPointerEvents}
+					enabled={isNavigationMaskEnabled}
+				>
+					<SurfaceContainer pointerEvents={contentPointerEvents}>
+						{hasAutoSnapPoint ? (
+							<View collapsable={false} onLayout={handleContentLayout}>
+								{children}
+							</View>
+						) : (
+							children
+						)}
+					</SurfaceContainer>
+				</MaybeMaskedNavigationContainer>
 			</Animated.View>
 		</GestureDetector>
 	);
@@ -121,13 +71,4 @@ const styles = StyleSheet.create({
 	content: {
 		flex: 1,
 	},
-	navigationMaskedRoot: {
-		flex: 1,
-	},
-	navigationMaskElement: {
-		backgroundColor: "white",
-	},
-	navigationContainer: {
-		flex: 1,
-	},
 });

package/src/shared/components/screen-container/layers/maybe-masked-navigation-container.tsx

@@ -0,0 +1,101 @@
+import { memo, useEffect } from "react";
+import { Platform, StyleSheet, View, type ViewProps } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import {
+	NAVIGATION_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_STYLE_ID,
+	NO_STYLES,
+} from "../../../constants";
+import { useScreenStyles } from "../../../providers/screen/styles.provider";
+import { logger } from "../../../utils/logger";
+
+type Props = {
+	enabled: boolean;
+	children: React.ReactNode;
+	pointerEvents: ViewProps["pointerEvents"];
+};
+
+let LazyMaskedView = View;
+
+try {
+	LazyMaskedView = require("@react-native-masked-view/masked-view").default;
+} catch (_) {
+	// optional peer dependency
+}
+
+let hasWarnedMissingMaskedView = false;
+const IS_ANDROID = Platform.OS === "android";
+
+export const MaybeMaskedNavigationContainer = memo(
+	({ enabled, children, pointerEvents }: Props) => {
+		const { stylesMap } = useScreenStyles();
+		const animatedNavigationContainerStyle = useAnimatedStyle(() => {
+			"worklet";
+			return stylesMap.value[NAVIGATION_CONTAINER_STYLE_ID]?.style || NO_STYLES;
+		});
+
+		const animatedNavigationMaskStyle = useAnimatedStyle(() => {
+			"worklet";
+			return stylesMap.value[NAVIGATION_MASK_STYLE_ID]?.style || NO_STYLES;
+		});
+
+		useEffect(() => {
+			if (!enabled) return;
+			if (LazyMaskedView !== View) return;
+			if (hasWarnedMissingMaskedView) return;
+
+			hasWarnedMissingMaskedView = true;
+			logger.warn(
+				"navigationMaskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
+			);
+		}, [enabled]);
+
+		const navigationContainer = (
+			<Animated.View
+				style={[styles.navigationContainer, animatedNavigationContainerStyle]}
+				pointerEvents={pointerEvents}
+				collapsable={false}
+				renderToHardwareTextureAndroid={IS_ANDROID && !enabled}
+				needsOffscreenAlphaCompositing={IS_ANDROID && !enabled}
+			>
+				{children}
+			</Animated.View>
+		);
+
+		// Navigation zoom uses the root container transform even when the mask
+		// wrapper is disabled. Only the mask element itself is optional.
+		if (!enabled) return navigationContainer;
+
+		if (LazyMaskedView === View) {
+			return navigationContainer;
+		}
+
+		return (
+			<LazyMaskedView
+				style={styles.navigationMaskedRoot}
+				// @ts-expect-error masked-view package types are too strict here
+				maskElement={
+					<Animated.View
+						style={[styles.navigationMaskElement, animatedNavigationMaskStyle]}
+						pointerEvents="none"
+					/>
+				}
+				pointerEvents={pointerEvents}
+			>
+				{navigationContainer}
+			</LazyMaskedView>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	navigationMaskedRoot: {
+		flex: 1,
+	},
+	navigationMaskElement: {
+		backgroundColor: "white",
+	},
+	navigationContainer: {
+		flex: 1,
+	},
+});

package/src/shared/components/screen-lifecycle/hooks/use-close-transition/index.ts

@@ -1,7 +1,6 @@
-import { useEffect, useLayoutEffect } from "react";
+import { useLayoutEffect } from "react";
 import {
 	runOnJS,
-	runOnUI,
 	useAnimatedReaction,
 	useDerivedValue,
 } from "react-native-reanimated";

package/src/shared/components/screen-lifecycle/hooks/use-open-transition.ts

@@ -1,19 +1,22 @@
 import { useLayoutEffect } from "react";
 import type { BaseDescriptor } from "../../../providers/screen/descriptors";
 import type { AnimationStoreMap } from "../../../stores/animation.store";
+import type { SnapPoint } from "../../../types/screen.types";
 import { animateToProgress } from "../../../utils/animation/animate-to-progress";
 import { useHighRefreshRate } from "./use-high-refresh-rate";
 
 /**
  * Calculates the initial progress value based on snap points configuration.
+ * Returns `'auto'` if the initial snap point is the `'auto'` keyword
+ * (meaning the animation must be deferred until content is measured).
  */
 function getInitialProgress({
 	snapPoints,
 	initialSnapIndex,
 }: {
-	snapPoints?: number[];
+	snapPoints?: SnapPoint[];
 	initialSnapIndex: number;
-}): number | undefined {
+}): number | "auto" | undefined {
 	if (!snapPoints) {
 		return undefined;
 	}
@@ -41,14 +44,25 @@ export function useOpenTransition(
 	useLayoutEffect(() => {
 		const { snapPoints, initialSnapIndex = 0 } = current.options;
 		const targetProgress = getInitialProgress({ snapPoints, initialSnapIndex });
-		const target = targetProgress ?? 1;
 
 		if (isFirstKey) {
-			animations.targetProgress.set(target);
-			animations.progress.set(target);
+			if (targetProgress === "auto") {
+				animations.targetProgress.set(0);
+				animations.progress.set(0);
+			} else {
+				const target = targetProgress ?? 1;
+				animations.targetProgress.set(target);
+				animations.progress.set(target);
+			}
 			animations.animating.set(0);
 			animations.closing.set(0);
-			animations.entering.set(1);
+			animations.entering.set(0);
+			return;
+		}
+
+		// When the initial snap point is 'auto', defer the opening animation until
+		// ScreenContainer has measured the content and set autoSnapPoint.
+		if (targetProgress === "auto") {
 			return;
 		}
 

package/src/shared/constants.ts

@@ -11,6 +11,10 @@ import type { BaseStackRoute } from "./types/stack.types";
  */
 export const MASK_STYLE_ID = "_ROOT_MASKED";
 export const CONTAINER_STYLE_ID = "_ROOT_CONTAINER";
+
+/**
+ * Navigation mask integration
+ */
 export const NAVIGATION_MASK_HOST_FLAG_STYLE_ID = "_NAVIGATION_MASK_HOST";
 export const NAVIGATION_MASK_STYLE_ID = "_NAVIGATION_ROOT_MASK";
 export const NAVIGATION_CONTAINER_STYLE_ID = "_NAVIGATION_ROOT_CONTAINER";
@@ -51,7 +55,7 @@ export const createScreenTransitionState = (
 	closing: 0,
 	animating: 0,
 	settled: 1,
-	entering: 1,
+	entering: 0,
 	gesture: { ...DEFAULT_GESTURE_VALUES },
 	route,
 	meta,
@@ -66,7 +70,7 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 		closing: 0,
 		animating: 0,
 		settled: 1,
-		entering: 1,
+		entering: 0,
 		gesture: DEFAULT_GESTURE_VALUES,
 		route: {} as RouteProp<ParamListBase>,
 	});

package/src/shared/hooks/gestures/resolve-screen-gesture-target.ts

@@ -0,0 +1,66 @@
+import type { GestureContextType } from "../../providers/gestures";
+import type { ScreenGestureTarget } from "./types";
+
+type ScreenGestureRef = GestureContextType["panGestureRef"] | null;
+
+type Params = {
+	target: ScreenGestureTarget | undefined;
+	self: GestureContextType | null | undefined;
+};
+
+const isAncestorTarget = (
+	target: ScreenGestureTarget,
+): target is { ancestor: number } => {
+	return typeof target === "object" && target !== null && "ancestor" in target;
+};
+
+function getGestureAncestors(self: GestureContextType): GestureContextType[] {
+	const ancestors: GestureContextType[] = [];
+	const startIsolated = self.isIsolated;
+	let current = self.ancestorContext;
+
+	while (current) {
+		if (current.isIsolated !== startIsolated) {
+			break;
+		}
+
+		ancestors.push(current);
+		current = current.ancestorContext;
+	}
+
+	return ancestors;
+}
+
+export function resolveScreenGestureTarget({
+	target,
+	self,
+}: Params): ScreenGestureRef {
+	if (!self) {
+		return null;
+	}
+
+	if (!target || target === "self") {
+		return self.panGestureRef ?? null;
+	}
+
+	const ancestors = getGestureAncestors(self);
+
+	if (target === "parent") {
+		return ancestors[0]?.panGestureRef ?? null;
+	}
+
+	if (target === "root") {
+		return ancestors[ancestors.length - 1]?.panGestureRef ?? null;
+	}
+
+	if (!isAncestorTarget(target)) {
+		return null;
+	}
+
+	const depth = target.ancestor;
+	if (!Number.isInteger(depth) || depth < 1) {
+		return null;
+	}
+
+	return ancestors[depth - 1]?.panGestureRef ?? null;
+}

package/src/shared/hooks/gestures/types.ts

@@ -0,0 +1,5 @@
+export type ScreenGestureTarget =
+	| "self"
+	| "parent"
+	| "root"
+	| { ancestor: number };

package/src/shared/hooks/gestures/use-screen-gesture.ts

@@ -1,7 +1,11 @@
 import { useGestureContext } from "../../providers/gestures";
+import { resolveScreenGestureTarget } from "./resolve-screen-gesture-target";
+import type { ScreenGestureTarget } from "./types";
+
+export type { ScreenGestureTarget } from "./types";
 
 /**
- * Returns a ref to the screen's navigation pan gesture.
+ * Returns a ref to a screen navigation pan gesture.
  * Use this to coordinate child gestures with the navigation gesture.
  *
  * @example
@@ -13,7 +17,10 @@ import { useGestureContext } from "../../providers/gestures";
  *   .onUpdate(...);
  * ```
  */
-export const useScreenGesture = () => {
+export const useScreenGesture = (target?: ScreenGestureTarget) => {
 	const ctx = useGestureContext();
-	return ctx?.panGestureRef ?? null;
+	return resolveScreenGestureTarget({
+		target,
+		self: ctx,
+	});
 };

package/src/shared/hooks/navigation/use-stack.tsx

@@ -2,7 +2,7 @@ import type { Route } from "@react-navigation/native";
 import { createContext, useContext } from "react";
 import type { DerivedValue } from "react-native-reanimated";
 import type { StackCoreContextValue } from "../../providers/stack/core.provider";
-import type { OverlayMode, OverlayProps } from "../../types/overlay.types";
+import type { OverlayProps } from "../../types/overlay.types";
 import type {
 	BaseStackDescriptor,
 	BaseStackNavigation,
@@ -16,7 +16,6 @@ export interface StackDescriptor<
 > extends BaseStackDescriptor<TRoute, TNavigation> {
 	options: BaseStackDescriptor["options"] & {
 		overlay?: (props: OverlayProps) => React.ReactNode;
-		overlayMode?: OverlayMode;
 		overlayShown?: boolean;
 		meta?: Record<string, unknown>;
 		enableTransitions?: boolean;