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

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

@@ -1,47 +1,52 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <Screen gesture is under the gesture context, so this will always exist.> */
-import { memo, useEffect } from "react";
-import { StyleSheet, View } from "react-native";
+import { memo, useCallback } from "react";
+import {
+	type LayoutChangeEvent,
+	StyleSheet,
+	useWindowDimensions,
+	View,
+} from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, {
+	runOnUI,
 	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 {
+	useDescriptorDerivations,
+	useDescriptors,
+} from "../../../providers/screen/descriptors";
 import { useScreenStyles } from "../../../providers/screen/styles.provider";
-import { logger } from "../../../utils/logger";
+import { AnimationStore } from "../../../stores/animation.store";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
 import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
+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 { isFirstKey } = useDescriptorDerivations();
 	const { pointerEvents, isBackdropActive } = useBackdropPointerEvents();
 	const gestureContext = useGestureContext();
+	const { height: screenHeight } = useWindowDimensions();
 	const isNavigationMaskEnabled = !!current.options.maskEnabled;
 	const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getRouteAnimations(routeKey);
+	const autoSnapPointValue = AnimationStore.getAnimation(
+		routeKey,
+		"autoSnapPoint",
+	);
+	const hasAutoSnapPoint =
+		current.options.snapPoints?.includes("auto") ?? false;
 
-	// ── Content ──
 	const animatedContentStyle = useAnimatedStyle(() => {
 		"worklet";
 		return stylesMap.value.content?.style || NO_STYLES;
@@ -52,54 +57,53 @@ 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 handleContentLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const contentHeight = event.nativeEvent.layout.height;
+			if (contentHeight <= 0) return;
 
-	const animatedNavigationMaskStyle = useAnimatedStyle(() => {
-		"worklet";
-		return stylesMap.value[NAVIGATION_MASK_STYLE_ID]?.style || NO_STYLES;
-	});
+			const fraction = Math.min(contentHeight / screenHeight, 1);
+			const transitionSpec = current.options.transitionSpec;
 
-	useEffect(() => {
-		if (!isNavigationMaskEnabled) return;
-		if (LazyMaskedView !== View) return;
-		if (hasWarnedMissingMaskedView) return;
+			runOnUI(
+				(
+					nextFraction: number,
+					isInitialScreen: boolean,
+					spec: typeof transitionSpec,
+				) => {
+					"worklet";
+					const isFirstMeasurement = autoSnapPointValue.value <= 0;
+					autoSnapPointValue.value = nextFraction;
 
-		hasWarnedMissingMaskedView = true;
-		logger.warn(
-			"maskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
-		);
-	}, [isNavigationMaskEnabled]);
+					if (
+						!isFirstMeasurement ||
+						animations.progress.value !== 0 ||
+						animations.animating.value !== 0
+					) {
+						return;
+					}
 
-	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
+					if (isInitialScreen) {
+						animations.targetProgress.value = nextFraction;
+						animations.progress.value = nextFraction;
+						return;
+					}
+
+					animateToProgress({
+						target: nextFraction,
+						spec,
+						animations,
+					});
+				},
+			)(fraction, isFirstKey, transitionSpec);
+		},
+		[
+			animations,
+			autoSnapPointValue,
+			current.options.transitionSpec,
+			isFirstKey,
+			screenHeight,
+		],
 	);
 
 	return (
@@ -109,9 +113,17 @@ export const ContentLayer = memo(({ children }: Props) => {
 				animatedProps={animatedContentProps}
 				pointerEvents={contentPointerEvents}
 			>
-				<SurfaceContainer pointerEvents={contentPointerEvents}>
-					{contentChildren}
-				</SurfaceContainer>
+				<MaybeMaskedNavigationContainer enabled={isNavigationMaskEnabled}>
+					<SurfaceContainer pointerEvents={contentPointerEvents}>
+						{hasAutoSnapPoint ? (
+							<View collapsable={false} onLayout={handleContentLayout}>
+								{children}
+							</View>
+						) : (
+							children
+						)}
+					</SurfaceContainer>
+				</MaybeMaskedNavigationContainer>
 			</Animated.View>
 		</GestureDetector>
 	);
@@ -121,13 +133,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,93 @@
+import { memo, useEffect } from "react";
+import { StyleSheet, View } 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;
+};
+
+let LazyMaskedView = View;
+
+try {
+	LazyMaskedView = require("@react-native-masked-view/masked-view").default;
+} catch (_) {
+	// optional peer dependency
+}
+
+let hasWarnedMissingMaskedView = false;
+
+export const MaybeMaskedNavigationContainer = memo(
+	({ enabled, children }: 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(
+				"maskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
+			);
+		}, [enabled]);
+
+		if (!enabled) return children;
+
+		if (LazyMaskedView === View) {
+			return (
+				<Animated.View
+					style={[styles.navigationContainer, animatedNavigationContainerStyle]}
+				>
+					{children}
+				</Animated.View>
+			);
+		}
+
+		return (
+			<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>
+		);
+	},
+);
+
+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;

package/src/shared/index.ts

@@ -3,7 +3,6 @@ import {
 	Boundary,
 	createBoundaryComponent,
 } from "./components/create-boundary-component";
-import { buildBoundaryMatchKey } from "./components/create-boundary-component/utils/build-boundary-match-key";
 import { createTransitionAwareComponent } from "./components/create-transition-aware-component";
 import MaskedView from "./components/integrations/masked-view";
 import { Presets, Specs } from "./configs";
@@ -26,36 +25,35 @@ export default {
 };
 
 export { snapTo } from "./animation/snap-to";
-export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
+export {
+	NAVIGATION_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_HOST_FLAG_STYLE_ID,
+	NAVIGATION_MASK_STYLE_ID,
+} from "./constants";
+export {
+	type ScreenGestureTarget,
+	useScreenGesture,
+} from "./hooks/gestures/use-screen-gesture";
 export { useHistory } from "./hooks/navigation/use-history";
 export {
 	type ScreenState,
 	useScreenState,
 } from "./hooks/navigation/use-screen-state";
-export { useScreenAnimation } from "./providers/screen/animation";
-export { buildBoundaryMatchKey };
+export {
+	type ScreenAnimationTarget,
+	useScreenAnimation,
+} from "./providers/screen/animation";
 
 export type {
 	AnimatedViewStyle,
 	AnimationConfig,
-	BoundEntry,
-	BoundsLink,
 	BoundsNavigationAccessor,
-	BoundsNavigationOptions,
-	BoundsNavigationPreset,
-	BoundsStyleOptions,
-	LegacyTransitionInterpolatedStyle,
-	NewTransitionInterpolatedStyle,
-	NormalizedTransitionInterpolatedStyle,
-	NormalizedTransitionSlotStyle,
-	OverlayInterpolationProps,
-	OverlayMode,
+	BoundsNavigationZoomOptions,
 	OverlayProps,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
 	ScreenTransitionConfig,
 	TransitionInterpolatedStyle,
-	TransitionSlotExplicit,
 	TransitionSlotStyle,
 	TransitionSpec,
 } from "./types";