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

package/src/shared/providers/screen/styles.provider.tsx

@@ -1,126 +1,137 @@
-import { createContext, useContext, useMemo } from "react";
+import { type ReactNode, useContext, useMemo } from "react";
 import {
 	type SharedValue,
 	useDerivedValue,
 	useSharedValue,
 } from "react-native-reanimated";
 import { NO_STYLES } from "../../constants";
-import { _useScreenAnimation } from "../../hooks/animation/use-screen-animation";
-import type { TransitionInterpolatedStyle } from "../../types/animation.types";
-import { createBounds } from "../../utils/bounds";
+import type { NormalizedTransitionInterpolatedStyle } from "../../types/animation.types";
+import createProvider from "../../utils/create-provider";
+import { logger } from "../../utils/logger";
+import { normalizeInterpolatedStyle } from "../../utils/normalize-interpolated-style";
+import { useScreenAnimationContext } from "./animation";
 
 type Props = {
-	children: React.ReactNode;
+	children: ReactNode;
 };
 
 type ScreenStylesContextValue = {
-	stylesMap: SharedValue<TransitionInterpolatedStyle>;
-	ancestorStylesMaps: SharedValue<TransitionInterpolatedStyle>[];
+	stylesMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
+	ancestorStylesMaps: SharedValue<NormalizedTransitionInterpolatedStyle>[];
 };
 
-const ScreenStylesContext = createContext<ScreenStylesContextValue | null>(
-	null,
+const {
+	ScreenStylesProvider,
+	ScreenStylesContext,
+	useScreenStylesContext: useScreenStyles,
+} = createProvider("ScreenStyles", {
+	guarded: true,
+})<Props, ScreenStylesContextValue>(
+	({ children }): { value: ScreenStylesContextValue; children: ReactNode } => {
+		const parentCtx = useContext(ScreenStylesContext);
+
+		const {
+			screenInterpolatorProps,
+			nextInterpolator,
+			currentInterpolator,
+			boundsAccessor,
+		} = useScreenAnimationContext();
+
+		/**
+		 * Tracks when user starts a gesture while another screen is still closing.
+		 * This persists until both the gesture ends AND the closing animation completes.
+		 */
+		const isGesturingDuringCloseAnimation = useSharedValue(false);
+		const hasWarnedLegacy = useSharedValue(false);
+
+		const stylesMap = useDerivedValue<NormalizedTransitionInterpolatedStyle>(
+			() => {
+				"worklet";
+				const props = screenInterpolatorProps.value;
+				const { current, next, progress } = props;
+				const isDragging = current.gesture.dragging;
+				const isNextClosing = !!next?.closing;
+
+				if (isDragging && isNextClosing) {
+					isGesturingDuringCloseAnimation.value = true;
+				}
+
+				if (!isDragging && !isNextClosing) {
+					isGesturingDuringCloseAnimation.value = false;
+				}
+
+				const isInGestureMode =
+					isDragging || isGesturingDuringCloseAnimation.value;
+
+				// Select interpolator
+				//  - If in gesture mode, use current screen's interpolator since we're driving
+				//    the animation from this screen (dragging back to dismiss next).
+				const interpolator = isInGestureMode
+					? currentInterpolator
+					: (nextInterpolator ?? currentInterpolator);
+
+				if (!interpolator)
+					return NO_STYLES as NormalizedTransitionInterpolatedStyle;
+
+				// Build effective props with corrected progress
+				//  - Gesture mode: use current.progress only (avoids jumps during drag)
+				//  - Normal: use derived progress as-is
+
+				let effectiveProgress = progress;
+				let effectiveNext = next;
+
+				if (isInGestureMode) {
+					effectiveProgress = current.progress;
+					effectiveNext = undefined;
+				}
+
+				try {
+					const raw = interpolator({
+						...props,
+						progress: effectiveProgress,
+						next: effectiveNext,
+						bounds: boundsAccessor,
+					});
+
+					const { result, wasLegacy } = normalizeInterpolatedStyle(
+						raw as Record<string, any>,
+					);
+
+					if (__DEV__ && wasLegacy && !hasWarnedLegacy.value) {
+						hasWarnedLegacy.value = true;
+						logger.warn(
+							"Flat interpolator return shape (contentStyle/backdropStyle) is deprecated. " +
+								"Use the nested format instead: { content: { style }, backdrop: { style } }.",
+						);
+					}
+
+					return result;
+				} catch (err) {
+					if (__DEV__) {
+						console.warn(
+							"[react-native-screen-transitions] screenStyleInterpolator must be a worklet",
+							err,
+						);
+					}
+					return NO_STYLES as NormalizedTransitionInterpolatedStyle;
+				}
+			},
+		);
+
+		const value = useMemo<ScreenStylesContextValue>(() => {
+			// Build ancestor chain: [parent, grandparent, great-grandparent, ...]
+			const ancestorStylesMaps = parentCtx
+				? [parentCtx.stylesMap, ...parentCtx.ancestorStylesMaps]
+				: [];
+
+			return {
+				stylesMap,
+				ancestorStylesMaps,
+			};
+		}, [stylesMap, parentCtx]);
+
+		return { value, children };
+	},
 );
 
-export function ScreenStylesProvider({ children }: Props) {
-	const parentCtx = useContext(ScreenStylesContext);
-
-	const { screenInterpolatorProps, nextInterpolator, currentInterpolator } =
-		_useScreenAnimation();
-
-	/**
-	 * Tracks when user starts a gesture while another screen is still closing.
-	 * This persists until both the gesture ends AND the closing animation completes.
-	 */
-	const isGesturingDuringCloseAnimation = useSharedValue(false);
-
-	const stylesMap = useDerivedValue<TransitionInterpolatedStyle>(() => {
-		"worklet";
-		const props = screenInterpolatorProps.value;
-		const { current, next, progress, stackProgress } = props;
-		const isDragging = current.gesture.isDragging;
-		const isNextClosing = !!next?.closing;
-
-		if (isDragging && isNextClosing) {
-			isGesturingDuringCloseAnimation.value = true;
-		}
-
-		if (!isDragging && !isNextClosing) {
-			isGesturingDuringCloseAnimation.value = false;
-		}
-
-		const isInGestureMode = isDragging || isGesturingDuringCloseAnimation.value;
-
-		const hasPushedScreenWhileClosing =
-			!isInGestureMode && isNextClosing && stackProgress > progress;
-
-		// Select interpolator
-		//  - If in gesture mode, use current screen's interpolator since we're driving
-		//    the animation from this screen (dragging back to dismiss next).
-		const interpolator = isInGestureMode
-			? currentInterpolator
-			: (nextInterpolator ?? currentInterpolator);
-
-		if (!interpolator) return NO_STYLES;
-
-		// Build effective props with corrected progress
-		//  - Gesture mode: use current.progress only (avoids jumps during drag)
-		//  - Pushed while closing: use stackProgress (includes new screen)
-		//  - Normal: use derived progress as-is
-
-		let effectiveProgress = progress;
-		let effectiveNext = next;
-
-		if (isInGestureMode) {
-			effectiveProgress = current.progress;
-			effectiveNext = undefined;
-		} else if (hasPushedScreenWhileClosing) {
-			effectiveProgress = stackProgress;
-		}
-
-		try {
-			return interpolator({
-				...props,
-				progress: effectiveProgress,
-				next: effectiveNext,
-				bounds: createBounds(props),
-			});
-		} catch (err) {
-			if (__DEV__) {
-				console.warn(
-					"[react-native-screen-transitions] screenStyleInterpolator must be a worklet",
-					err,
-				);
-			}
-			return NO_STYLES;
-		}
-	});
-
-	const value = useMemo(() => {
-		// Build ancestor chain: [parent, grandparent, great-grandparent, ...]
-		const ancestorStylesMaps = parentCtx
-			? [parentCtx.stylesMap, ...parentCtx.ancestorStylesMaps]
-			: [];
-
-		return {
-			stylesMap,
-			ancestorStylesMaps,
-		};
-	}, [stylesMap, parentCtx]);
-
-	return (
-		<ScreenStylesContext.Provider value={value}>
-			{children}
-		</ScreenStylesContext.Provider>
-	);
-}
-
-export function useScreenStyles() {
-	const ctx = useContext(ScreenStylesContext);
-	if (!ctx) {
-		throw new Error(
-			"useScreenStyles must be used within a ScreenStylesProvider",
-		);
-	}
-	return ctx;
-}
+export { ScreenStylesProvider, useScreenStyles };

package/src/shared/providers/scroll-settle.provider.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import createProvider from "../utils/create-provider";
+
+interface ScrollSettleProviderProps {
+	settledSignal: SharedValue<number>;
+	children: ReactNode;
+}
+
+interface ScrollSettleContextValue {
+	settledSignal: SharedValue<number>;
+}
+
+const { ScrollSettleProvider, useScrollSettleContext } = createProvider(
+	"ScrollSettle",
+	{ guarded: false },
+)<ScrollSettleProviderProps, ScrollSettleContextValue>(
+	({ settledSignal, children }) => ({
+		value: { settledSignal },
+		children,
+	}),
+);
+
+export { ScrollSettleProvider, useScrollSettleContext };

package/src/shared/providers/stack/core.provider.tsx

@@ -1,9 +1,11 @@
 import { SafeAreaProviderCompat } from "@react-navigation/elements";
 import type * as React from "react";
+import { useMemo } from "react";
 import { StyleSheet } from "react-native";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { StackType } from "../../types/stack.types";
 import createProvider from "../../utils/create-provider";
+import { ViewportProvider } from "../viewport.provider";
 
 export interface StackCoreConfig {
 	TRANSITIONS_ALWAYS_ON?: boolean;
@@ -35,14 +37,15 @@ const { StackCoreProvider: InternalStackCoreProvider, useStackCoreContext } =
 			STACK_TYPE = StackType.BLANK,
 		} = config;
 
+		const flags = useMemo(
+			() => ({ TRANSITIONS_ALWAYS_ON, STACK_TYPE, DISABLE_NATIVE_SCREENS }),
+			[TRANSITIONS_ALWAYS_ON, STACK_TYPE, DISABLE_NATIVE_SCREENS],
+		);
+
+		const value = useMemo(() => ({ flags }), [flags]);
+
 		return {
-			value: {
-				flags: {
-					TRANSITIONS_ALWAYS_ON,
-					STACK_TYPE,
-					DISABLE_NATIVE_SCREENS,
-				},
-			},
+			value,
 			children: (
 				<GestureHandlerRootView
 					style={styles.container}
@@ -50,7 +53,9 @@ const { StackCoreProvider: InternalStackCoreProvider, useStackCoreContext } =
 						STACK_TYPE === StackType.COMPONENT ? "box-none" : undefined
 					}
 				>
-					<SafeAreaProviderCompat>{children}</SafeAreaProviderCompat>
+					<SafeAreaProviderCompat>
+						<ViewportProvider>{children}</ViewportProvider>
+					</SafeAreaProviderCompat>
 				</GestureHandlerRootView>
 			),
 		};

package/src/shared/providers/stack/direct.provider.tsx

@@ -1,16 +1,6 @@
-import type {
-	ParamListBase,
-	RouteProp,
-	StackNavigationState,
-} from "@react-navigation/native";
-import * as React from "react";
-import { useEffect, useMemo } from "react";
-import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
-import type {
-	NativeStackDescriptor,
-	NativeStackDescriptorMap,
-	NativeStackNavigationHelpers,
-} from "../../../native-stack/types";
+import type * as React from "react";
+import { useMemo } from "react";
+import type { NativeStackDescriptorMap } from "../../../native-stack/types";
 import {
 	StackContext,
 	type StackContextValue,
@@ -19,60 +9,21 @@ import {
 	AnimationStore,
 	type AnimationStoreMap,
 } from "../../stores/animation.store";
-import { HistoryStore } from "../../stores/history.store";
+import type {
+	DirectStackContextValue,
+	DirectStackProps,
+	DirectStackScene,
+} from "../../types/providers/direct-stack.types";
+import { isFloatOverlayVisible } from "../../utils/overlay/visibility";
 import { useStackCoreContext } from "./core.provider";
+import { useStackDerived } from "./helpers/use-stack-derived";
 
-export interface DirectStackScene {
-	route: StackNavigationState<ParamListBase>["routes"][number];
-	descriptor: NativeStackDescriptor;
-	isPreloaded: boolean;
-}
-
-export interface DirectStackProps {
-	state: StackNavigationState<ParamListBase>;
-	navigation: NativeStackNavigationHelpers;
-	descriptors: NativeStackDescriptorMap;
-	describe: (
-		route: RouteProp<ParamListBase>,
-		placeholder: boolean,
-	) => NativeStackDescriptor;
-}
-
-export interface DirectStackContextValue {
-	state: StackNavigationState<ParamListBase>;
-	navigation: NativeStackNavigationHelpers;
-	descriptors: NativeStackDescriptorMap;
-	preloadedDescriptors: NativeStackDescriptorMap;
-	scenes: DirectStackScene[];
-	focusedIndex: number;
-	shouldShowFloatOverlay: boolean;
-	stackProgress: DerivedValue<number>;
-	optimisticFocusedIndex: DerivedValue<number>;
-}
-
-const DirectStackContext = React.createContext<DirectStackContextValue | null>(
-	null,
-);
-DirectStackContext.displayName = "DirectStack";
-
-function useDirectStackContext(): DirectStackContextValue {
-	const context = React.useContext(DirectStackContext);
-	if (!context) {
-		throw new Error(
-			"useDirectStackContext must be used within DirectStackProvider",
-		);
-	}
-	return context;
-}
-
-/**
- * Internal hook that computes all lifecycle values.
- */
 function useDirectStackValue(
 	props: DirectStackProps,
 ): DirectStackContextValue & { stackContextValue: StackContextValue } {
 	const { state, navigation, descriptors, describe } = props;
 	const { flags } = useStackCoreContext();
+	const navigatorKey = state.key;
 
 	const preloadedDescriptors = useMemo(() => {
 		return state.preloadedRoutes.reduce<NativeStackDescriptorMap>(
@@ -89,7 +40,6 @@ function useDirectStackValue(
 		shouldShowFloatOverlay,
 		routeKeys,
 		allRoutes,
-		allDescriptors,
 		animationMaps,
 	} = useMemo(() => {
 		const allRoutes = state.routes.concat(state.preloadedRoutes);
@@ -110,14 +60,13 @@ function useDirectStackValue(
 
 			scenes.push({ route, descriptor, isPreloaded });
 			routeKeys.push(route.key);
-			animationMaps.push(AnimationStore.getAll(route.key));
+			animationMaps.push(AnimationStore.getRouteAnimations(route.key));
 
 			if (!shouldShowFloatOverlay && descriptor) {
 				const options = descriptor.options;
 				if (
 					options?.enableTransitions === true &&
-					options?.overlayMode === "float" &&
-					options?.overlayShown === true
+					isFloatOverlayVisible(options)
 				) {
 					shouldShowFloatOverlay = true;
 				}
@@ -129,53 +78,33 @@ function useDirectStackValue(
 			shouldShowFloatOverlay,
 			routeKeys,
 			allRoutes,
-			allDescriptors,
 			animationMaps,
 		};
 	}, [state.routes, state.preloadedRoutes, preloadedDescriptors, descriptors]);
 
-	const stackProgress = useDerivedValue(() => {
-		"worklet";
-		let total = 0;
-		for (let i = 0; i < animationMaps.length; i++) {
-			total += animationMaps[i].progress.value;
-		}
-		return total;
-	});
-
-	const optimisticFocusedIndex = useDerivedValue(() => {
-		"worklet";
-		const lastIndex = animationMaps.length - 1;
-		let closingFromTop = 0;
-		for (let i = lastIndex; i >= 0; i--) {
-			if (animationMaps[i].closing.value > 0) closingFromTop++;
-			else break;
-		}
-		return lastIndex - closingFromTop;
-	});
+	const { stackProgress, optimisticFocusedIndex } =
+		useStackDerived(animationMaps);
 
 	const focusedIndex = state.index;
 
 	const stackContextValue = useMemo<StackContextValue>(
 		() => ({
 			flags,
+			navigatorKey,
 			routeKeys,
 			routes: allRoutes,
-			descriptors: allDescriptors,
 			scenes,
-			focusedIndex,
 			stackProgress,
 			optimisticFocusedIndex,
 		}),
 		[
+			flags,
+			navigatorKey,
 			routeKeys,
 			allRoutes,
 			scenes,
-			focusedIndex,
 			stackProgress,
 			optimisticFocusedIndex,
-			flags,
-			allDescriptors,
 		],
 	);
 
@@ -185,56 +114,36 @@ function useDirectStackValue(
 			state,
 			navigation,
 			descriptors,
-			preloadedDescriptors,
 			scenes,
 			focusedIndex,
 			shouldShowFloatOverlay,
-			stackProgress,
-			optimisticFocusedIndex,
 		}),
 		[
 			state,
 			navigation,
 			descriptors,
-			preloadedDescriptors,
 			scenes,
 			focusedIndex,
 			shouldShowFloatOverlay,
-			stackProgress,
-			optimisticFocusedIndex,
 		],
 	);
 
 	return { ...lifecycleValue, stackContextValue };
 }
 
-/**
- * HOC that wraps component with DirectStack provider AND StackContext.
- * Used by native-stack which uses navigation state directly (no local route management).
- */
 function withDirectStack<TProps extends DirectStackProps>(
 	Component: React.ComponentType<DirectStackContextValue>,
 ): React.FC<TProps> {
 	return function DirectStackProvider(props: TProps) {
-		const navigatorKey = props.state.key;
-
-		// Clean up history when navigator unmounts
-		useEffect(() => {
-			return () => {
-				HistoryStore.clearNavigator(navigatorKey);
-			};
-		}, [navigatorKey]);
-
 		const { stackContextValue, ...lifecycleValue } = useDirectStackValue(props);
 
 		return (
 			<StackContext.Provider value={stackContextValue}>
-				<DirectStackContext.Provider value={lifecycleValue}>
-					<Component {...lifecycleValue} />
-				</DirectStackContext.Provider>
+				<Component {...lifecycleValue} />
 			</StackContext.Provider>
 		);
 	};
 }
 
-export { useDirectStackContext, withDirectStack };
+export { withDirectStack };
+export type { DirectStackContextValue, DirectStackProps, DirectStackScene };

package/src/shared/providers/stack/helpers/use-closing-route-map.ts

@@ -0,0 +1,28 @@
+import { useDerivedValue } from "react-native-reanimated";
+import { useSharedValueRef } from "../../../hooks/reanimated/use-shared-value-ref";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+
+/**
+ * Ref-based hash map of routes that are visually closing.
+ * Derived on the UI thread and bridged to a JS ref — no rerenders.
+ */
+export const useClosingRouteMap = (
+	routeKeys: string[],
+	animationMaps: AnimationStoreMap[],
+): React.RefObject<Readonly<Record<string, true>>> => {
+	return useSharedValueRef(
+		useDerivedValue(() => {
+			"worklet";
+			const map: Record<string, true> = {};
+			for (let i = 0; i < animationMaps.length; i++) {
+				if (animationMaps[i].closing.value > 0) {
+					const routeKey = routeKeys[i];
+					if (routeKey) {
+						map[routeKey] = true;
+					}
+				}
+			}
+			return map;
+		}),
+	);
+};

package/src/shared/{utils/navigation → providers/stack/helpers/use-local-routes/helpers}/align-routes-with-latest.ts

@@ -1,8 +1,5 @@
-import { composeDescriptors } from "./compose-descriptors";
-
-interface RouteWithKey {
-	key: string;
-}
+import type { RouteWithKey } from "../../../../../types/stack.types";
+import { composeDescriptors } from "../../../../../utils/navigation/compose-descriptors";
 
 /**
  * Aligns current routes with the latest route data while preserving references

package/src/shared/{utils/navigation → providers/stack/helpers/use-local-routes/helpers}/have-same-route-keys.ts

@@ -1,6 +1,4 @@
-interface RouteWithKey {
-	key: string;
-}
+import type { RouteWithKey } from "../../../../../types/stack.types";
 
 export const haveSameRouteKeys = <Route extends RouteWithKey>(
 	previous: Route[],

package/src/shared/{utils/navigation → providers/stack/helpers/use-local-routes/helpers}/routes-are-identical.ts

@@ -1,6 +1,4 @@
-interface RouteWithKey {
-	key: string;
-}
+import type { RouteWithKey } from "../../../../../types/stack.types";
 
 export const routesAreIdentical = <Route extends RouteWithKey>(
 	a: Route[],