react-native-screen-transitions 3.1.0 → 3.2.0-beta.1

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

@@ -0,0 +1,148 @@
+import {
+	NavigationContext,
+	NavigationRouteContext,
+	type Route,
+} from "@react-navigation/native";
+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, useStack } from "../../../hooks/navigation/use-stack";
+import { useSharedValueState } from "../../../hooks/reanimated/use-shared-value-state";
+import type { OverlayInterpolationProps } from "../../../types/animation.types";
+import type { OverlayProps } from "../../../types/overlay.types";
+
+type OverlayHostProps = {
+	scene: StackScene;
+	scenes: StackScene[];
+	routes: Route<string>[];
+	overlayIndex: number;
+	isFloating?: boolean;
+};
+
+export const OverlayHost = memo(function OverlayHost({
+	scene,
+	scenes,
+	routes,
+	overlayIndex,
+	isFloating,
+}: OverlayHostProps) {
+	const OverlayComponent = scene.descriptor.options.overlay;
+	const screen = useWindowDimensions();
+
+	const { stackProgress, optimisticFocusedIndex, routeKeys } = useStack();
+	const insets = useSafeAreaInsets();
+
+	const relativeProgress = useDerivedValue(() => {
+		"worklet";
+		return stackProgress.value - overlayIndex;
+	});
+
+	// For float overlays: global focused index (can be any screen in the stack)
+	// For screen overlays: relative to overlay position (only screens at or after)
+	const optimisticActiveIndex = useSharedValueState(
+		useDerivedValue(() => {
+			"worklet";
+			if (isFloating) {
+				// For float overlays, use global optimistic focused index directly
+				const globalIndex = optimisticFocusedIndex.get();
+				const clampedIndex = Math.max(
+					0,
+					Math.min(globalIndex, routeKeys.length - 1),
+				);
+				return clampedIndex;
+			}
+
+			// For screen overlays, compute relative to overlay position
+			const screensAbove = routeKeys.length - 1 - overlayIndex;
+			const relativeOptimistic = optimisticFocusedIndex.value - overlayIndex;
+			const result = Math.max(0, Math.min(relativeOptimistic, screensAbove));
+
+			return result;
+		}),
+	);
+
+	const overlayAnimation = useDerivedValue<OverlayInterpolationProps>(() => ({
+		progress: relativeProgress.value,
+		layouts: { screen },
+		insets,
+	}));
+
+	const focusedScene = useMemo(() => {
+		if (overlayIndex === -1) {
+			return scene;
+		}
+
+		if (isFloating) {
+			// For float overlays, optimisticActiveIndex is the global focused index
+			return scenes[optimisticActiveIndex] ?? scene;
+		}
+
+		// For screen overlays, optimisticActiveIndex is relative to overlayIndex
+		const maxOffset = Math.max(scenes.length - overlayIndex - 1, 0);
+		const normalizedIndex = Math.min(
+			Math.max(optimisticActiveIndex, 0),
+			maxOffset,
+		);
+
+		return scenes[overlayIndex + normalizedIndex] ?? scene;
+	}, [overlayIndex, optimisticActiveIndex, scenes, scene, isFloating]);
+
+	const screenAnimation = useScreenAnimation();
+
+	if (!OverlayComponent) {
+		return null;
+	}
+
+	const overlayProps: OverlayProps<typeof scene.descriptor.navigation> = {
+		routes,
+		overlayAnimation,
+		screenAnimation,
+		focusedRoute: focusedScene.route,
+		focusedIndex: optimisticActiveIndex,
+		meta: focusedScene.descriptor.options.meta,
+		navigation: scene.descriptor.navigation,
+	};
+
+	// Cast to OverlayProps function - container overlays are handled by ContainerOverlay component
+	const renderOverlay = OverlayComponent as (
+		props: OverlayProps,
+	) => React.ReactNode;
+
+	return (
+		<Animated.View
+			pointerEvents="box-none"
+			style={[
+				styles.container,
+				isFloating ? styles.floating : { zIndex: 1 },
+				styles.absolute,
+			]}
+		>
+			<NavigationContext.Provider
+				// biome-ignore lint/suspicious/noExplicitAny: navigation type varies by stack
+				value={scene.descriptor.navigation as any}
+			>
+				<NavigationRouteContext.Provider value={scene.route}>
+					<View pointerEvents="box-none" style={styles.overlay}>
+						{renderOverlay(overlayProps)}
+					</View>
+				</NavigationRouteContext.Provider>
+			</NavigationContext.Provider>
+		</Animated.View>
+	);
+});
+
+const styles = StyleSheet.create({
+	overlay: {
+		...StyleSheet.absoluteFillObject,
+		zIndex: 1,
+	},
+	container: {
+		flex: 1,
+	},
+	absolute: StyleSheet.absoluteFillObject,
+	floating: {
+		zIndex: 1000,
+	},
+});

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

@@ -0,0 +1,51 @@
+import { useMemo } from "react";
+import {
+	type StackDescriptor,
+	type StackScene,
+	useStack,
+} from "../../../hooks/navigation/use-stack";
+import { useKeys } from "../../../providers/screen/keys.provider";
+import { OverlayHost } from "./overlay-host";
+
+/**
+ * Screen overlay component that renders per-screen.
+ * Gets current descriptor from keys context.
+ */
+export function ScreenOverlay() {
+	const { current } = useKeys<StackDescriptor>();
+	const { routeKeys, flags } = useStack();
+
+	const options = current.options;
+
+	const scene = useMemo<StackScene>(
+		() => ({
+			descriptor: current,
+			route: current.route,
+		}),
+		[current],
+	);
+
+	// Find the index of this screen in the stack
+	const overlayIndex = useMemo(
+		() => routeKeys.indexOf(current.route.key),
+		[routeKeys, current.route.key],
+	);
+
+	// Skip screens without enableTransitions (native-stack only)
+	if (!flags.TRANSITIONS_ALWAYS_ON && !options.enableTransitions) {
+		return null;
+	}
+
+	if (!options.overlayShown || options.overlayMode !== "screen") {
+		return null;
+	}
+
+	return (
+		<OverlayHost
+			scene={scene}
+			scenes={[scene]}
+			routes={[]}
+			overlayIndex={overlayIndex}
+		/>
+	);
+}

package/src/shared/components/root-transition-aware.tsx

@@ -2,14 +2,14 @@ import { memo } from "react";
 import { StyleSheet, View } from "react-native";
 import Animated, { useAnimatedStyle } from "react-native-reanimated";
 import { NO_STYLES } from "../constants";
-import { useTransitionStyles } from "../providers/transition-styles.provider";
+import { useScreenStyles } from "../providers/screen/styles.provider";
 
 type Props = {
 	children: React.ReactNode;
 };
 
 export const RootTransitionAware = memo(({ children }: Props) => {
-	const { stylesMap } = useTransitionStyles();
+	const { stylesMap } = useScreenStyles();
 
 	const animatedContentStyle = useAnimatedStyle(() => {
 		"worklet";

package/src/shared/configs/presets.ts

@@ -4,7 +4,7 @@ import {
 	interpolate,
 	interpolateColor,
 } from "react-native-reanimated";
-import type { ScreenTransitionConfig } from "../types/core.types";
+import type { ScreenTransitionConfig } from "../types/screen.types";
 import { DefaultSpec } from "./specs";
 
 const platform = Platform.OS;

package/src/shared/constants.ts

@@ -1,11 +1,9 @@
 import type { ParamListBase, RouteProp } from "@react-navigation/native";
+import { Platform } from "react-native";
 import type { MeasuredDimensions } from "react-native-reanimated";
 import type { ScreenTransitionState } from "./types/animation.types";
-import type { BoundEntry } from "./types/bounds.types";
-import type { Layout } from "./types/core.types";
 import type { ActivationArea } from "./types/gesture.types";
-import type { Complete } from "./types/utils.types";
-import type { BoundsBuilderOptions } from "./utils/bounds/types/builder";
+import type { Layout } from "./types/screen.types";
 
 /**
  * Masked view integration
@@ -41,7 +39,6 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 /**
  * Bounds API Defaults
  */
-export const NO_BOUNDS_MAP: Record<string, BoundEntry> = Object.freeze({});
 export const EMPTY_BOUND_HELPER_RESULT = Object.freeze({});
 export const EMPTY_BOUND_HELPER_RESULT_RAW = Object.freeze({
 	scaleX: 1,
@@ -69,23 +66,6 @@ export const FULLSCREEN_DIMENSIONS = (
 	};
 };
 
-export const DEFAULT_BUILDER_OPTIONS: Complete<
-	Omit<BoundsBuilderOptions, "id">
-> = Object.freeze({
-	gestures: { x: 0, y: 0 },
-	toFullscreen: false,
-	absolute: false,
-	relative: true,
-	method: "transform",
-	contentScaleMode: "auto",
-	//
-	space: "relative",
-	target: "bound",
-	scaleMode: "match",
-	anchor: "center",
-	raw: false,
-} as const);
-
 /**
  * Default gesture config
  */
@@ -95,13 +75,4 @@ export const DEFAULT_GESTURE_ENABLED = false;
 export const DEFAULT_GESTURE_DRIVES_PROGRESS = true;
 export const DEFAULT_GESTURE_ACTIVATION_AREA: ActivationArea = "screen";
 
-/**
- * Default gesture offset
- */
-export const GESTURE_ACTIVATION_THRESHOLD_X = 10;
-export const GESTURE_ACTIVATION_THRESHOLD_Y = 10;
-export const GESTURE_FAIL_TOLERANCE_X = 15;
-export const GESTURE_FAIL_TOLERANCE_Y = 20;
-export const DEFAULT_EDGE_DISTANCE_HORIZONTAL = 50;
-export const DEFAULT_EDGE_DISTANCE_VERTICAL = 135;
-export const DEFAULT_ACTIVATION_AREA = "screen" as const;
+export const IS_WEB = Platform.OS === "web";

package/src/shared/controller/managed-lifecycle.tsx

@@ -0,0 +1,73 @@
+import { useLayoutEffect } from "react";
+import { runOnJS, useAnimatedReaction } from "react-native-reanimated";
+import type { BlankStackDescriptor } from "../../blank-stack/types";
+import { useHighRefreshRate } from "../hooks/animation/use-high-refresh-rate";
+import useStableCallback from "../hooks/use-stable-callback";
+import { useKeys } from "../providers/screen/keys.provider";
+import { useManagedStackContext } from "../providers/stack/managed.provider";
+import { AnimationStore } from "../stores/animation.store";
+import { startScreenTransition } from "../utils/animation/start-screen-transition";
+import { resetStoresForScreen } from "../utils/reset-stores-for-screen";
+
+interface Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Lifecycle controller built out for Blank Stack implementation.
+ */
+export const ManagedLifecycle = ({ children }: Props) => {
+	const { current } = useKeys<BlankStackDescriptor>();
+	const { handleCloseRoute, closingRouteKeysShared } = useManagedStackContext();
+
+	const animations = AnimationStore.getAll(current.route.key);
+
+	const { deactivateHighRefreshRate, activateHighRefreshRate } =
+		useHighRefreshRate(current);
+
+	const handleInitialize = useStableCallback(() => {
+		activateHighRefreshRate();
+		startScreenTransition({
+			target: "open",
+			spec: current.options.transitionSpec,
+			animations,
+			onAnimationFinish: deactivateHighRefreshRate,
+		});
+	});
+
+	const handleCloseEnd = useStableCallback((finished: boolean) => {
+		if (!finished) {
+			return;
+		}
+		handleCloseRoute({ route: current.route });
+		requestAnimationFrame(() => {
+			deactivateHighRefreshRate();
+			resetStoresForScreen(current);
+		});
+	});
+
+	useAnimatedReaction(
+		() => ({
+			keys: closingRouteKeysShared.value,
+		}),
+		({ keys }) => {
+			if (!keys.includes(current.route.key)) {
+				return;
+			}
+
+			runOnJS(activateHighRefreshRate)();
+			startScreenTransition({
+				target: "close",
+				spec: current.options.transitionSpec,
+				animations,
+				onAnimationFinish: handleCloseEnd,
+			});
+		},
+	);
+
+	useLayoutEffect(() => {
+		handleInitialize();
+	}, [handleInitialize]);
+
+	return children;
+};

package/src/shared/hooks/animation/use-associated-style.tsx

@@ -5,7 +5,7 @@ import {
 	useSharedValue,
 } from "react-native-reanimated";
 import { NO_STYLES } from "../../constants";
-import { useTransitionStyles } from "../../providers/transition-styles.provider";
+import { useScreenStyles } from "../../providers/screen/styles.provider";
 
 type Props = {
 	id?: string;
@@ -16,7 +16,7 @@ type Props = {
  * This hook is used to get the associated styles for a given styleId / boundTag.
  */
 export const useAssociatedStyles = ({ id }: Props = {}) => {
-	const { stylesMap, ancestorStylesMaps } = useTransitionStyles();
+	const { stylesMap, ancestorStylesMaps } = useScreenStyles();
 	const showAfterFirstFrame = useSharedValue(false);
 
 	useDerivedValue(() => {

package/src/shared/hooks/animation/use-high-refresh-rate.tsx

@@ -0,0 +1,34 @@
+import { useFrameCallback } from "react-native-reanimated";
+import type { BaseDescriptor } from "../../providers/screen/keys.provider";
+import useStableCallback from "../use-stable-callback";
+
+/**
+ * Maintainer Notes:
+ * Marking as experimental for now since, I'll be honest, I'm not sure if this does much. This was taken
+ * right from this https://github.com/software-mansion/react-native-reanimated/issues/4738
+ *
+ * Not noticing much of a difference in prod.
+ */
+export const useHighRefreshRate = (current: BaseDescriptor) => {
+	const enableHighRefreshRate =
+		current.options.experimental_enableHighRefreshRate ?? false;
+
+	const frameCallback = useFrameCallback(() => {}, false);
+
+	const activateHighRefreshRate = useStableCallback(() => {
+		if (enableHighRefreshRate) {
+			frameCallback.setActive(true);
+		}
+	});
+
+	const deactivateHighRefreshRate = useStableCallback(() => {
+		if (enableHighRefreshRate) {
+			frameCallback.setActive(false);
+		}
+	});
+
+	return {
+		activateHighRefreshRate,
+		deactivateHighRefreshRate,
+	};
+};

package/src/shared/hooks/animation/use-screen-animation.tsx

@@ -1,39 +1,37 @@
-import type { ParamListBase, RouteProp } from "@react-navigation/native";
 import { useMemo } from "react";
 import { useWindowDimensions } from "react-native";
 import { type SharedValue, useDerivedValue } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import type { NativeStackScreenTransitionConfig } from "../../../native-stack/types";
 import { DEFAULT_SCREEN_TRANSITION_STATE } from "../../constants";
-import { useFlagsContext } from "../../providers/flags.provider";
 import {
-	type TransitionDescriptor,
+	type BaseDescriptor,
+	type BaseRoute,
 	useKeys,
-} from "../../providers/keys.provider";
-import { useStackAnimationValues } from "../../providers/routes.provider";
+} from "../../providers/screen/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 import type {
 	ScreenInterpolationProps,
 	ScreenTransitionState,
 } from "../../types/animation.types";
-import type { ScreenTransitionConfig } from "../../types/core.types";
-import { computeStackProgress } from "../../utils/animation/compute-stack-progress";
+import type { ScreenTransitionConfig } from "../../types/screen.types";
 import { derivations } from "../../utils/animation/derivations";
 import { createBounds } from "../../utils/bounds";
+import { useStack } from "../navigation/use-stack";
 
 type BuiltState = {
 	progress: SharedValue<number>;
 	closing: SharedValue<number>;
 	animating: SharedValue<number>;
 	gesture: GestureStoreMap;
-	route: RouteProp<ParamListBase>;
+	route: BaseRoute;
 	meta?: Record<string, unknown>;
 	unwrapped: ScreenTransitionState;
 };
 
 const createScreenTransitionState = (
-	route: RouteProp<ParamListBase>,
+	route: BaseRoute,
 	meta?: Record<string, unknown>,
 ): ScreenTransitionState => ({
 	progress: 0,
@@ -71,7 +69,7 @@ const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 };
 
 const useBuildScreenTransitionState = (
-	descriptor: TransitionDescriptor | undefined,
+	descriptor: BaseDescriptor | undefined,
 ): BuiltState | undefined => {
 	const key = descriptor?.route.key;
 	const meta = descriptor?.options?.meta;
@@ -101,10 +99,12 @@ const hasTransitionsEnabled = (
 };
 
 export function _useScreenAnimation() {
-	const dimensions = useWindowDimensions();
+	const windowDimensions = useWindowDimensions();
+	const dimensions = windowDimensions;
+
 	const insets = useSafeAreaInsets();
-	const flags = useFlagsContext();
-	const transitionsAlwaysOn = flags?.TRANSITIONS_ALWAYS_ON ?? false;
+	const { flags, stackProgress: rootStackProgress, routeKeys } = useStack();
+	const transitionsAlwaysOn = flags.TRANSITIONS_ALWAYS_ON;
 
 	const {
 		current: currentDescriptor,
@@ -117,7 +117,7 @@ export function _useScreenAnimation() {
 	const prevAnimation = useBuildScreenTransitionState(previousDescriptor);
 
 	const currentRouteKey = currentDescriptor?.route?.key;
-	const stackAnimationValues = useStackAnimationValues(currentRouteKey);
+	const currentIndex = routeKeys.indexOf(currentRouteKey);
 
 	const screenInterpolatorProps = useDerivedValue<
 		Omit<ScreenInterpolationProps, "bounds">
@@ -142,7 +142,11 @@ export function _useScreenAnimation() {
 			next,
 		});
 
-		const stackProgress = computeStackProgress(stackAnimationValues, progress);
+		// Compute relative stack progress: total - currentIndex
+		// This gives us the sum of progress values from current screen onwards
+		// Falls back to current progress if index is invalid
+		const stackProgress =
+			currentIndex >= 0 ? rootStackProgress.value - currentIndex : progress;
 
 		return {
 			layouts: { screen: dimensions },
@@ -160,9 +164,11 @@ export function _useScreenAnimation() {
 	const currentInterpolator =
 		currentDescriptor?.options.screenStyleInterpolator;
 
-	const screenStyleInterpolator = nextInterpolator ?? currentInterpolator;
-
-	return { screenInterpolatorProps, screenStyleInterpolator };
+	return {
+		screenInterpolatorProps,
+		nextInterpolator,
+		currentInterpolator,
+	};
 }
 
 export function useScreenAnimation() {

package/src/shared/hooks/gestures/use-build-gestures.tsx

@@ -22,10 +22,9 @@ import type {
 	GestureContextType,
 	ScrollConfig,
 } from "../../providers/gestures.provider";
-import { useKeys } from "../../providers/keys.provider";
+import { useKeys } from "../../providers/screen/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
-
 import {
 	type GestureDirection,
 	GestureOffsetState,
@@ -36,6 +35,7 @@ import { determineDismissal } from "../../utils/gesture/determine-dismissal";
 import { mapGestureToProgress } from "../../utils/gesture/map-gesture-to-progress";
 import { resetGestureValues } from "../../utils/gesture/reset-gesture-values";
 import { velocity } from "../../utils/gesture/velocity";
+import { useStack } from "../navigation/use-stack";
 import useStableCallbackValue from "../use-stable-callback-value";
 
 interface BuildGesturesHookProps {
@@ -53,7 +53,11 @@ export const useBuildGestures = ({
 	gestureAnimationValues: GestureStoreMap;
 } => {
 	const dimensions = useWindowDimensions();
+
 	const { current } = useKeys();
+	const navState = current.navigation.getState();
+	const isFirstScreen =
+		navState.routes.findIndex((r) => r.key === current.route.key) === 0;
 
 	const initialTouch = useSharedValue({
 		x: 0,
@@ -74,7 +78,6 @@ export const useBuildGestures = ({
 
 	const {
 		gestureDirection = DEFAULT_GESTURE_DIRECTION,
-		gestureEnabled = DEFAULT_GESTURE_ENABLED,
 		gestureVelocityImpact = GESTURE_VELOCITY_IMPACT,
 		gestureDrivesProgress = DEFAULT_GESTURE_DRIVES_PROGRESS,
 		gestureActivationArea = DEFAULT_GESTURE_ACTIVATION_AREA,
@@ -82,6 +85,10 @@ export const useBuildGestures = ({
 		transitionSpec,
 	} = current.options;
 
+	const gestureEnabled = Boolean(
+		isFirstScreen ? false : current.options.gestureEnabled,
+	);
+
 	const directions = useMemo(() => {
 		const directionsArray = Array.isArray(gestureDirection)
 			? gestureDirection

package/src/shared/hooks/gestures/use-scroll-registry.tsx

@@ -5,7 +5,6 @@ import type { LayoutChangeEvent } from "react-native";
 import { useAnimatedScrollHandler } from "react-native-reanimated";
 import type { ReanimatedScrollEvent } from "react-native-reanimated/lib/typescript/hook/commonTypes";
 import { useGestureContext } from "../../providers/gestures.provider";
-import type { Any } from "../../types/utils.types";
 import useStableCallback from "../use-stable-callback";
 
 interface ScrollProgressHookProps {
@@ -34,7 +33,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		onScroll: (event) => {
 			props.onScroll?.(event);
 
-			const updateScrollPosition = (v: Any) => {
+			const updateScrollPosition = (v: any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -64,7 +63,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		(width: number, height: number) => {
 			props.onContentSizeChange?.(width, height);
 
-			const updateContentSize = (v: Any) => {
+			const updateContentSize = (v: any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -93,7 +92,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		props.onLayout?.(event);
 		const { width, height } = event.nativeEvent.layout;
 
-		const updateLayout = (v: Any) => {
+		const updateLayout = (v: any) => {
 			"worklet";
 			if (v === null) {
 				return {

package/src/{blank-stack/utils/with-stack-navigation/hooks → shared/hooks/navigation}/use-closing-route-keys.tsx

@@ -1,6 +1,6 @@
 import { useMemo, useRef } from "react";
 import { useSharedValue } from "react-native-reanimated";
-import useStableCallback from "../../../../shared/hooks/use-stable-callback";
+import useStableCallback from "../use-stable-callback";
 
 export const useClosingRouteKeys = () => {
 	const keysRef = useRef<Set<string>>(new Set());