react-native-screen-transitions 3.3.0 → 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/variations/float-overlay.tsx

@@ -2,21 +2,15 @@ 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 type { BaseDescriptor } from "../../../providers/screen/keys.provider";
-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 { OverlayProps } from "../../../types/overlay.types";
+import type { OverlayScreenState } from "../../../types/overlay.types";
+
 import { getActiveFloatOverlay } from "../helpers/get-active-overlay";
 import { OverlayHost } from "./overlay-host";
 
-type OverlayScreenState = Omit<
-	OverlayProps<BaseDescriptor["navigation"]>,
-	"progress" | "overlayAnimation" | "screenAnimation"
-> & {
-	index: number;
-	snapTo: (index: number) => void;
-};
-
 /**
  * Float overlay component that renders above all screens.
  * Gets routes and descriptors from stack context.
@@ -45,18 +39,19 @@ export function FloatOverlay() {
 		const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
 		const focusedDescriptor = focusedScene?.descriptor;
 
-		const overlayScreenState: OverlayScreenState = {
-			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);
-			},
-		};
+		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,
@@ -74,10 +69,12 @@ export function FloatOverlay() {
 	const { scene, previous, current, next, overlayScreenState } = overlayData;
 
 	return (
-		<KeysProvider current={current} previous={previous} next={next}>
-			<ScreenStylesProvider>
-				<OverlayHost scene={scene} overlayScreenState={overlayScreenState} />
-			</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,23 +6,18 @@ 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 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";
-
-type OverlayScreenState = Omit<
-	OverlayProps<BaseDescriptor["navigation"]>,
-	"progress" | "overlayAnimation" | "screenAnimation"
-> & {
-	index: number;
-	snapTo: (index: number) => void;
-};
+import type {
+	OverlayProps,
+	OverlayScreenState,
+} from "../../../types/overlay.types";
 
 type OverlayHostProps = {
 	scene: StackScene;
-	overlayScreenState: OverlayScreenState;
+	overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]>;
 };
 
 export const OverlayHost = memo(function OverlayHost({

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

@@ -6,19 +6,11 @@ import {
 	type StackScene,
 	useStack,
 } from "../../../hooks/navigation/use-stack";
-import { useKeys } from "../../../providers/screen/keys.provider";
-import type { OverlayProps } from "../../../types/overlay.types";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import type { OverlayScreenState } from "../../../types/overlay.types";
 import { isScreenOverlayVisible } from "../../../utils/overlay/visibility";
 import { OverlayHost } from "./overlay-host";
 
-type OverlayScreenState = Omit<
-	OverlayProps<StackDescriptor["navigation"]>,
-	"progress" | "overlayAnimation" | "screenAnimation"
-> & {
-	index: number;
-	snapTo: (index: number) => void;
-};
-
 /**
  * Screen overlay component that renders per-screen.
  * Gets current descriptor from keys context.
@@ -28,7 +20,7 @@ type OverlayScreenState = Omit<
  * to access animation values. This component will be removed in a future version.
  */
 export function ScreenOverlay() {
-	const { current } = useKeys<StackDescriptor>();
+	const { current } = useDescriptors<StackDescriptor>();
 	const { flags, routes, optimisticFocusedIndex, routeKeys } = useStack();
 	const focusedIndex = useOptimisticFocusedIndex(
 		optimisticFocusedIndex,
@@ -45,7 +37,9 @@ export function ScreenOverlay() {
 		[current],
 	);
 
-	const overlayScreenState = useMemo<OverlayScreenState>(
+	const overlayScreenState = useMemo<
+		OverlayScreenState<StackDescriptor["navigation"]>
+	>(
 		() => ({
 			index: routeKeys.indexOf(current.route.key),
 			options: current.options,

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>
+	);
+});

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

@@ -0,0 +1,133 @@
+/** 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 { 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 { useGestureContext } from "../../../providers/gestures";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useScreenStyles } from "../../../providers/screen/styles.provider";
+import { logger } from "../../../utils/logger";
+import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
+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 contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
+
+	// ── Content ──
+	const animatedContentStyle = useAnimatedStyle(() => {
+		"worklet";
+		return stylesMap.value.content?.style || NO_STYLES;
+	});
+
+	const animatedContentProps = useAnimatedProps(() => {
+		"worklet";
+		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
+				style={[styles.content, animatedContentStyle]}
+				animatedProps={animatedContentProps}
+				pointerEvents={contentPointerEvents}
+			>
+				<SurfaceContainer pointerEvents={contentPointerEvents}>
+					{contentChildren}
+				</SurfaceContainer>
+			</Animated.View>
+		</GestureDetector>
+	);
+});
+
+const styles = StyleSheet.create({
+	content: {
+		flex: 1,
+	},
+	navigationMaskedRoot: {
+		flex: 1,
+	},
+	navigationMaskElement: {
+		backgroundColor: "white",
+	},
+	navigationContainer: {
+		flex: 1,
+	},
+});