react-native-screen-transitions 3.3.0-rc.3 → 3.4.0-alpha.0

package/src/shared/components/create-transition-aware-component.tsx

@@ -1,16 +1,18 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <This helper is usually being used inside a transitionable stack> */
 import type React from "react";
-import { type ComponentType, forwardRef, memo } from "react";
+import { type ComponentType, forwardRef, memo, useCallback } from "react";
 import type { View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, {
 	runOnUI,
 	useAnimatedRef,
 	useComposedEventHandler,
+	useSharedValue,
 } from "react-native-reanimated";
 import { useAssociatedStyles } from "../hooks/animation/use-associated-style";
 import { useScrollRegistry } from "../hooks/gestures/use-scroll-registry";
 import { RegisterBoundsProvider } from "../providers/register-bounds.provider";
+import { ScrollSettleProvider } from "../providers/scroll-settle.provider";
 import type { TransitionAwareProps } from "../types/screen.types";
 
 interface CreateTransitionAwareComponentOptions {
@@ -32,9 +34,20 @@ export function createTransitionAwareComponent<P extends object>(
 		const {
 			remeasureOnFocus: _remeasureOnFocus,
 			onScroll: userOnScroll,
+			onMomentumScrollEnd: userOnMomentumScrollEnd,
+			onScrollEndDrag: userOnScrollEndDrag,
 			...scrollableProps
 		} = props;
 
+		const settledSignal = useSharedValue(0);
+
+		const emitScrollSettled = useCallback(() => {
+			runOnUI(() => {
+				"worklet";
+				settledSignal.value = settledSignal.value + 1;
+			})();
+		}, [settledSignal]);
+
 		// Determine scroll direction from the horizontal prop (standard ScrollView API)
 		const scrollDirection = scrollableProps.horizontal
 			? "horizontal"
@@ -53,11 +66,37 @@ export function createTransitionAwareComponent<P extends object>(
 			userOnScroll ?? null,
 		]);
 
+		const handleMomentumScrollEnd = useCallback(
+			(event: unknown) => {
+				userOnMomentumScrollEnd?.(event);
+				emitScrollSettled();
+			},
+			[userOnMomentumScrollEnd, emitScrollSettled],
+		);
+
+		const handleScrollEndDrag = useCallback(
+			(event: any) => {
+				userOnScrollEndDrag?.(event);
+
+				const velocityX = Math.abs(event?.nativeEvent?.velocity?.x ?? 0);
+				const velocityY = Math.abs(event?.nativeEvent?.velocity?.y ?? 0);
+
+				// If there is no momentum, onMomentumScrollEnd may not fire.
+				// Emit settled signal here only when velocity is effectively zero.
+				if (velocityX < 0.01 && velocityY < 0.01) {
+					emitScrollSettled();
+				}
+			},
+			[userOnScrollEndDrag, emitScrollSettled],
+		);
+
 		const scrollableComponent = (
 			<AnimatedComponent
 				{...(scrollableProps as any)}
 				ref={ref}
 				onScroll={composedScrollHandler}
+				onMomentumScrollEnd={handleMomentumScrollEnd}
+				onScrollEndDrag={handleScrollEndDrag}
 				onContentSizeChange={onContentSizeChange}
 				onLayout={onLayout}
 				scrollEventThrottle={scrollableProps.scrollEventThrottle || 16}
@@ -65,14 +104,16 @@ export function createTransitionAwareComponent<P extends object>(
 		);
 
 		// If no gesture owner found for this axis, render without GestureDetector
-		if (!nativeGesture) {
-			return scrollableComponent;
-		}
-
 		return (
-			<GestureDetector gesture={nativeGesture}>
-				{scrollableComponent}
-			</GestureDetector>
+			<ScrollSettleProvider settledSignal={settledSignal}>
+				{!nativeGesture ? (
+					scrollableComponent
+				) : (
+					<GestureDetector gesture={nativeGesture}>
+						{scrollableComponent}
+					</GestureDetector>
+				)}
+			</ScrollSettleProvider>
 		);
 	});
 
@@ -92,9 +133,11 @@ export function createTransitionAwareComponent<P extends object>(
 
 		const animatedRef = useAnimatedRef<View>();
 
-		const { associatedStyles } = useAssociatedStyles({
+		const { associatedStyles, associatedProps } = useAssociatedStyles({
 			id: sharedBoundTag || styleId,
 			style,
+			resetTransformOnUnset: !!sharedBoundTag,
+			waitForFirstResolvedStyle: false,
 		});
 
 		return (
@@ -110,6 +153,7 @@ export function createTransitionAwareComponent<P extends object>(
 						{...(rest as any)}
 						ref={animatedRef}
 						style={[style, associatedStyles]}
+						animatedProps={associatedProps}
 						onPress={captureActiveOnPress}
 						onLayout={runOnUI(handleInitialLayout)}
 						collapsable={!sharedBoundTag}

package/src/shared/components/native-screen.tsx

@@ -46,20 +46,16 @@ export const NativeScreen = ({
 }: ScreenProps) => {
 	const {
 		flags: { DISABLE_NATIVE_SCREENS = false },
-	} = useStack();
-
-	const {
-		activeScreensLimit,
 		routes,
 		optimisticFocusedIndex,
-		backdropBehaviors,
-	} = useManagedStackContext();
+	} = useStack();
+	const { activeScreensLimit, backdropBehaviors } = useManagedStackContext();
 
 	const routesLength = routes.length;
 	const screenRef = useAnimatedRef<View>();
 
-	const sceneProgress = AnimationStore.getAnimation(routeKey, "progress");
-	const sceneClosing = AnimationStore.getAnimation(routeKey, "closing");
+	const sceneProgress = AnimationStore.getRouteAnimation(routeKey, "progress");
+	const sceneClosing = AnimationStore.getRouteAnimation(routeKey, "closing");
 	const screenActivity = useSharedValue<ScreenActivity>(
 		ScreenActivity.TRANSITIONING_OR_BELOW_TOP,
 	);

package/src/shared/components/overlay/helpers/get-active-overlay.ts

@@ -1,9 +1,10 @@
 import type { StackScene } from "../../../hooks/navigation/use-stack";
+import { isFloatOverlayVisible } from "../../../utils/overlay/visibility";
 
 /**
  * Find the active float overlay from scenes.
  * Scans from the top of the stack downward to find the first screen
- * with overlayMode="float" and overlayShown=true.
+ * with a visible overlay that isn't explicitly set to legacy screen mode.
  */
 export function getActiveFloatOverlay(
 	scenes: StackScene[],
@@ -29,7 +30,7 @@ export function getActiveFloatOverlay(
 			continue;
 		}
 
-		if (options?.overlayMode === "float" && options?.overlayShown) {
+		if (isFloatOverlayVisible(options)) {
 			return { scene, overlayIndex: i };
 		}
 	}

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

@@ -1,7 +1,13 @@
 import { useMemo } from "react";
+import { snapDescriptorToIndex } from "../../../animation/snap-to";
+import { useOptimisticFocusedIndex } from "../../../hooks/navigation/use-optimistic-focused-index";
 import { useStack } from "../../../hooks/navigation/use-stack";
-import { KeysProvider } from "../../../providers/screen/keys.provider";
+import { ScreenAnimationProvider } from "../../../providers/screen/animation";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import { DescriptorsProvider } from "../../../providers/screen/descriptors";
 import { ScreenStylesProvider } from "../../../providers/screen/styles.provider";
+import type { OverlayScreenState } from "../../../types/overlay.types";
+
 import { getActiveFloatOverlay } from "../helpers/get-active-overlay";
 import { OverlayHost } from "./overlay-host";
 
@@ -10,7 +16,12 @@ import { OverlayHost } from "./overlay-host";
  * Gets routes and descriptors from stack context.
  */
 export function FloatOverlay() {
-	const { scenes, focusedIndex, flags } = useStack();
+	const { scenes, optimisticFocusedIndex, flags, routes, routeKeys } =
+		useStack();
+	const focusedIndex = useOptimisticFocusedIndex(
+		optimisticFocusedIndex,
+		routeKeys.length,
+	);
 
 	const activeOverlay = useMemo(
 		() =>
@@ -18,21 +29,52 @@ export function FloatOverlay() {
 		[scenes, focusedIndex, flags.TRANSITIONS_ALWAYS_ON],
 	);
 
-	if (!activeOverlay) {
+	const overlayData = useMemo(() => {
+		if (!activeOverlay) return null;
+
+		const { scene, overlayIndex } = activeOverlay;
+		const previous = scenes[overlayIndex - 1]?.descriptor;
+		const current = scene.descriptor;
+		const next = scenes[overlayIndex + 1]?.descriptor;
+		const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
+		const focusedDescriptor = focusedScene?.descriptor;
+
+		const overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]> =
+			{
+				index: routeKeys.indexOf(current.route.key),
+				options: focusedDescriptor?.options ?? {},
+				routes,
+				focusedRoute: focusedScene?.route ?? current.route,
+				focusedIndex,
+				meta: focusedDescriptor?.options?.meta,
+				navigation: current.navigation,
+				snapTo: (index: number) => {
+					snapDescriptorToIndex(current, index);
+				},
+			};
+
+		return {
+			scene,
+			previous,
+			current,
+			next,
+			overlayScreenState,
+		};
+	}, [activeOverlay, scenes, focusedIndex, routeKeys, routes]);
+
+	if (!overlayData) {
 		return null;
 	}
 
-	const { scene, overlayIndex } = activeOverlay;
-
-	const previous = scenes[overlayIndex - 1]?.descriptor;
-	const current = scene.descriptor;
-	const next = scenes[overlayIndex + 1]?.descriptor;
+	const { scene, previous, current, next, overlayScreenState } = overlayData;
 
 	return (
-		<KeysProvider current={current} previous={previous} next={next}>
-			<ScreenStylesProvider>
-				<OverlayHost scene={scene} />
-			</ScreenStylesProvider>
-		</KeysProvider>
+		<DescriptorsProvider current={current} previous={previous} next={next}>
+			<ScreenAnimationProvider>
+				<ScreenStylesProvider>
+					<OverlayHost scene={scene} overlayScreenState={overlayScreenState} />
+				</ScreenStylesProvider>
+			</ScreenAnimationProvider>
+		</DescriptorsProvider>
 	);
 }

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

@@ -6,26 +6,29 @@ import { memo, useMemo } from "react";
 import { Animated, StyleSheet, useWindowDimensions, View } from "react-native";
 import { useDerivedValue } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { useScreenAnimation } from "../../../hooks/animation/use-screen-animation";
-import { useScreenState } from "../../../hooks/navigation/use-screen-state";
 import type { StackScene } from "../../../hooks/navigation/use-stack";
-import type { BaseDescriptor } from "../../../providers/screen/keys.provider";
+import { useScreenAnimation } from "../../../providers/screen/animation";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
 import type { OverlayInterpolationProps } from "../../../types/animation.types";
-import type { OverlayProps } from "../../../types/overlay.types";
+import type {
+	OverlayProps,
+	OverlayScreenState,
+} from "../../../types/overlay.types";
 
 type OverlayHostProps = {
 	scene: StackScene;
+	overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]>;
 };
 
 export const OverlayHost = memo(function OverlayHost({
 	scene,
+	overlayScreenState,
 }: OverlayHostProps) {
 	const OverlayComponent = scene.descriptor.options.overlay;
 	const screen = useWindowDimensions();
 	const insets = useSafeAreaInsets();
 
 	const screenAnimation = useScreenAnimation();
-	const screenState = useScreenState();
 	const relativeProgress = useDerivedValue(() => {
 		"worklet";
 		return screenAnimation.value.stackProgress;
@@ -39,12 +42,14 @@ export const OverlayHost = memo(function OverlayHost({
 
 	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(
 		() => ({
-			...screenState,
+			...overlayScreenState,
 			progress: relativeProgress,
-			overlayAnimation, //Deprecated
-			screenAnimation, //Deprecated
+			/**@deprecated */
+			overlayAnimation,
+			/**@deprecated */
+			screenAnimation,
 		}),
-		[relativeProgress, overlayAnimation, screenAnimation, screenState],
+		[relativeProgress, overlayAnimation, screenAnimation, overlayScreenState],
 	);
 
 	if (!OverlayComponent) {

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

@@ -1,10 +1,14 @@
 import { useMemo } from "react";
+import { snapDescriptorToIndex } from "../../../animation/snap-to";
+import { useOptimisticFocusedIndex } from "../../../hooks/navigation/use-optimistic-focused-index";
 import {
 	type StackDescriptor,
 	type StackScene,
 	useStack,
 } from "../../../hooks/navigation/use-stack";
-import { useKeys } from "../../../providers/screen/keys.provider";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import type { OverlayScreenState } from "../../../types/overlay.types";
+import { isScreenOverlayVisible } from "../../../utils/overlay/visibility";
 import { OverlayHost } from "./overlay-host";
 
 /**
@@ -16,8 +20,12 @@ import { OverlayHost } from "./overlay-host";
  * to access animation values. This component will be removed in a future version.
  */
 export function ScreenOverlay() {
-	const { current } = useKeys<StackDescriptor>();
-	const { flags } = useStack();
+	const { current } = useDescriptors<StackDescriptor>();
+	const { flags, routes, optimisticFocusedIndex, routeKeys } = useStack();
+	const focusedIndex = useOptimisticFocusedIndex(
+		optimisticFocusedIndex,
+		routeKeys.length,
+	);
 
 	const options = current.options;
 
@@ -29,14 +37,32 @@ export function ScreenOverlay() {
 		[current],
 	);
 
+	const overlayScreenState = useMemo<
+		OverlayScreenState<StackDescriptor["navigation"]>
+	>(
+		() => ({
+			index: routeKeys.indexOf(current.route.key),
+			options: current.options,
+			routes,
+			focusedRoute: routes[focusedIndex] ?? current.route,
+			focusedIndex,
+			meta: current.options?.meta,
+			navigation: current.navigation,
+			snapTo: (index: number) => {
+				snapDescriptorToIndex(current, index);
+			},
+		}),
+		[current, routeKeys, routes, focusedIndex],
+	);
+
 	// Skip screens without enableTransitions (native-stack only)
 	if (!flags.TRANSITIONS_ALWAYS_ON && !options.enableTransitions) {
 		return null;
 	}
 
-	if (!options.overlayShown || options.overlayMode !== "screen") {
+	if (!isScreenOverlayVisible(options)) {
 		return null;
 	}
 
-	return <OverlayHost scene={scene} />;
+	return <OverlayHost scene={scene} overlayScreenState={overlayScreenState} />;
 }

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

@@ -0,0 +1,32 @@
+import {
+	NavigationContext,
+	NavigationRouteContext,
+} 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;
+};
+
+/**
+ * Shared scene view for managed stacks (blank-stack, component-stack).
+ * Wraps screen render output with navigation context providers
+ * and optional screen overlay.
+ */
+export const SceneView = React.memo(function SceneView({
+	descriptor,
+}: SceneViewProps) {
+	const { route, navigation, render } = descriptor;
+
+	return (
+		<NavigationContext.Provider value={navigation as any}>
+			<NavigationRouteContext.Provider value={route}>
+				{isScreenOverlayVisible(descriptor.options) && <Overlay.Screen />}
+				{render?.()}
+			</NavigationRouteContext.Provider>
+		</NavigationContext.Provider>
+	);
+});

package/src/shared/{hooks → components/screen-container/hooks}/use-backdrop-pointer-events.ts

@@ -1,12 +1,13 @@
-import { useKeys } from "../providers/screen/keys.provider";
-import { useStackCoreContext } from "../providers/stack/core.provider";
-import { StackType } from "../types/stack.types";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useStackCoreContext } from "../../../providers/stack/core.provider";
+import { StackType } from "../../../types/stack.types";
 
 type BackdropBehavior = "block" | "passthrough" | "dismiss" | "collapse";
 
 interface BackdropPointerEventsResult {
 	pointerEvents: "box-none" | undefined;
 	backdropBehavior: BackdropBehavior;
+	isBackdropActive: boolean;
 }
 
 /**
@@ -17,7 +18,7 @@ interface BackdropPointerEventsResult {
  * - Other stacks default to 'block' (undefined = normal touch handling)
  */
 export function useBackdropPointerEvents(): BackdropPointerEventsResult {
-	const { current } = useKeys();
+	const { current } = useDescriptors();
 	const { flags } = useStackCoreContext();
 
 	const isComponentStack = flags.STACK_TYPE === StackType.COMPONENT;
@@ -28,5 +29,8 @@ export function useBackdropPointerEvents(): BackdropPointerEventsResult {
 	const pointerEvents =
 		backdropBehavior === "passthrough" ? "box-none" : undefined;
 
-	return { pointerEvents, backdropBehavior };
+	const isBackdropActive =
+		backdropBehavior === "dismiss" || backdropBehavior === "collapse";
+
+	return { pointerEvents, backdropBehavior, isBackdropActive };
 }

package/src/shared/components/screen-container/index.tsx

@@ -0,0 +1,26 @@
+import { memo } from "react";
+import { StyleSheet, View } from "react-native";
+import { useBackdropPointerEvents } from "./hooks/use-backdrop-pointer-events";
+import { BackdropLayer } from "./layers/backdrop";
+import { ContentLayer } from "./layers/content";
+
+type Props = {
+	children: React.ReactNode;
+};
+
+export const ScreenContainer = memo(({ children }: Props) => {
+	const { pointerEvents } = useBackdropPointerEvents();
+
+	return (
+		<View style={styles.container} pointerEvents={pointerEvents}>
+			<BackdropLayer />
+			<ContentLayer>{children}</ContentLayer>
+		</View>
+	);
+});
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+	},
+});

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

@@ -0,0 +1,111 @@
+import { memo, useCallback, useMemo } from "react";
+import { Pressable, StyleSheet } from "react-native";
+import Animated, {
+	runOnUI,
+	useAnimatedProps,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import { DefaultSnapSpec } from "../../../configs/specs";
+import { NO_PROPS, NO_STYLES } from "../../../constants";
+import { useNavigationHelpers } from "../../../hooks/navigation/use-navigation-helpers";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useScreenStyles } from "../../../providers/screen/styles.provider";
+import { AnimationStore } from "../../../stores/animation.store";
+import { GestureStore } from "../../../stores/gesture.store";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+import { findCollapseTarget } from "../../../utils/gesture/find-collapse-target";
+import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
+
+export const BackdropLayer = memo(function BackdropLayer() {
+	const { stylesMap } = useScreenStyles();
+	const { current } = useDescriptors();
+	const { dismissScreen } = useNavigationHelpers();
+	const { isBackdropActive, backdropBehavior } = useBackdropPointerEvents();
+
+	const BackdropComponent = current.options.backdropComponent;
+
+	const AnimatedBackdropComponent = useMemo(
+		() =>
+			BackdropComponent
+				? Animated.createAnimatedComponent(BackdropComponent)
+				: null,
+		[BackdropComponent],
+	);
+	const handleBackdropPress = useCallback(() => {
+		if (backdropBehavior === "dismiss") {
+			dismissScreen();
+			return;
+		}
+
+		if (backdropBehavior === "collapse") {
+			const snapPoints = current.options.snapPoints;
+			const canDismiss = current.options.gestureEnabled !== false;
+
+			// No snap points → fallback to dismiss
+			if (!snapPoints || snapPoints.length === 0) {
+				dismissScreen();
+				return;
+			}
+
+			const animations = AnimationStore.getRouteAnimations(current.route.key);
+			const gestures = GestureStore.getRouteGestures(current.route.key);
+			const transitionSpec = current.options.transitionSpec;
+
+			runOnUI(() => {
+				"worklet";
+				const { target, shouldDismiss } = findCollapseTarget(
+					animations.progress.value,
+					snapPoints,
+					canDismiss,
+				);
+
+				// If already dismissing, skip
+				if (gestures.dismissing.value) return;
+
+				gestures.dismissing.value = shouldDismiss ? 1 : 0;
+
+				const spec = shouldDismiss
+					? transitionSpec
+					: {
+							open: transitionSpec?.expand ?? DefaultSnapSpec,
+							close: transitionSpec?.collapse ?? DefaultSnapSpec,
+						};
+
+				animateToProgress({
+					target,
+					spec,
+					animations,
+					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
+				});
+			})();
+		}
+	}, [backdropBehavior, current, dismissScreen]);
+
+	const animatedBackdropStyle = useAnimatedStyle(() => {
+		"worklet";
+		return stylesMap.value.backdrop?.style ?? NO_STYLES;
+	});
+
+	const animatedBackdropProps = useAnimatedProps(() => {
+		"worklet";
+		return stylesMap.value.backdrop?.props ?? NO_PROPS;
+	});
+
+	return (
+		<Pressable
+			style={StyleSheet.absoluteFillObject}
+			pointerEvents={isBackdropActive ? "auto" : "none"}
+			onPress={isBackdropActive ? handleBackdropPress : undefined}
+		>
+			{AnimatedBackdropComponent && (
+				<AnimatedBackdropComponent
+					style={[StyleSheet.absoluteFillObject]}
+					animatedProps={animatedBackdropProps}
+				/>
+			)}
+			<Animated.View
+				style={[StyleSheet.absoluteFillObject, animatedBackdropStyle]}
+			/>
+		</Pressable>
+	);
+});