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

package/src/shared/hooks/navigation/use-stack.tsx

@@ -0,0 +1,89 @@
+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 {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+	BaseStackScene,
+} from "../../types/stack.types";
+
+/**
+ * Stack descriptor with overlay options.
+ * Extends BaseStackDescriptor with overlay-specific options.
+ */
+export interface StackDescriptor<
+	TRoute extends BaseStackRoute = Route<string>,
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+> extends BaseStackDescriptor<TRoute, TNavigation> {
+	options: BaseStackDescriptor["options"] & {
+		overlay?: (props: OverlayProps) => React.ReactNode;
+		overlayMode?: OverlayMode;
+		overlayShown?: boolean;
+		meta?: Record<string, unknown>;
+		enableTransitions?: boolean;
+	};
+}
+
+/**
+ * Scene type for stack context (route + descriptor pair).
+ */
+export type StackScene<TDescriptor extends StackDescriptor = StackDescriptor> =
+	BaseStackScene<TDescriptor>;
+
+/**
+ * Common stack context value that both managed and direct stack providers populate.
+ * Used by overlays and shared components that need stack progress info.
+ */
+export interface StackContextValue extends StackCoreContextValue {
+	/**
+	 * Route keys for all routes in the stack.
+	 */
+	routeKeys: string[];
+	/**
+	 * All routes in the stack.
+	 */
+	routes: Route<string>[];
+	/**
+	 * Descriptor map for all routes.
+	 */
+	descriptors: Record<string, StackDescriptor>;
+	/**
+	 * Pre-computed scenes (route + descriptor pairs).
+	 */
+	scenes: StackScene[];
+	/**
+	 * The current focused index from navigation state.
+	 */
+	focusedIndex: number;
+	/**
+	 * Aggregated stack progress across all routes.
+	 * Sum of all individual screen progress values.
+	 * When 4 screens are fully visible, stackProgress = 4.
+	 */
+	stackProgress: DerivedValue<number>;
+	/**
+	 * Focused index that accounts for closing screens.
+	 * Returns currentIndex - 1 if any screen is closing, otherwise currentIndex.
+	 */
+	optimisticFocusedIndex: DerivedValue<number>;
+}
+
+export const StackContext = createContext<StackContextValue | null>(null);
+StackContext.displayName = "Stack";
+
+/**
+ * Hook to access common stack context values.
+ * Works in both blank-stack and native-stack navigators.
+ */
+export function useStack<T extends StackContextValue = StackContextValue>(): T {
+	const context = useContext(StackContext);
+
+	if (context === null) {
+		throw new Error("useStack must be used within a Stack provider");
+	}
+
+	return context as T;
+}

package/src/shared/hooks/reanimated/use-shared-value-state.ts

@@ -5,6 +5,7 @@ import {
 	type SharedValue,
 	useAnimatedReaction,
 } from "react-native-reanimated";
+import { IS_WEB } from "../../constants";
 
 /**
  * Derives React state from a Reanimated SharedValue.
@@ -12,6 +13,10 @@ import {
  */
 export function useSharedValueState<T>(sharedValue: SharedValue<T>): T {
 	const [state, setState] = useState<T>(() => {
+		if (IS_WEB) {
+			// Web fallback - executeOnUIRuntimeSync not available
+			return sharedValue.value;
+		}
 		const readOnUI = executeOnUIRuntimeSync((sv: SharedValue<T>) => {
 			"worklet";
 			return sv.value;

package/src/shared/index.ts

@@ -23,9 +23,14 @@ export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
 
 export type {
 	AnimationConfig,
+	BoundEntry,
+	BoundsLink,
 	OverlayInterpolationProps,
+	OverlayMode,
+	OverlayProps,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
-} from "./types/animation.types";
-export type { BoundEntry, BoundsLink } from "./types/bounds.types";
-export type { ScreenTransitionConfig } from "./types/core.types";
+	ScreenTransitionConfig,
+	TransitionInterpolatedStyle,
+	TransitionSpec,
+} from "./types";

package/src/shared/providers/gestures.provider.tsx

@@ -8,7 +8,7 @@ import { useSharedValue } from "react-native-reanimated";
 import { useBuildGestures } from "../hooks/gestures/use-build-gestures";
 import type { GestureStoreMap } from "../stores/gesture.store";
 import createProvider from "../utils/create-provider";
-import { useKeys } from "./keys.provider";
+import { useKeys } from "./screen/keys.provider";
 
 export type ScrollConfig = {
 	x: number;
@@ -29,11 +29,15 @@ export interface GestureContextType {
 	gestureEnabled: boolean;
 }
 
+interface ScreenGestureProviderProps {
+	children: React.ReactNode;
+}
+
 export const {
 	ScreenGestureProvider,
 	useScreenGestureContext: useGestureContext,
 } = createProvider("ScreenGesture", { guarded: false })<
-	{ children: React.ReactNode },
+	ScreenGestureProviderProps,
 	GestureContextType
 >(({ children }) => {
 	const { current } = useKeys();

package/src/shared/providers/layout-anchor.provider.tsx

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+import { useWindowDimensions, type View } from "react-native";
+import {
+	type AnimatedRef,
+	type MeasuredDimensions,
+	measure,
+} from "react-native-reanimated";
+import createProvider from "../utils/create-provider";
+
+interface LayoutAnchorProviderProps {
+	anchorRef: AnimatedRef<View>;
+	children: ReactNode;
+}
+
+interface LayoutAnchorContextValue {
+	/**
+	 * Corrects measured dimensions for parent transforms (translation and scale).
+	 * The anchor should be at (0, 0) with full screen dimensions - any difference
+	 * is from parent transforms. This function reverses those transforms to yield
+	 * the true layout position and dimensions.
+	 */
+	correctMeasurement: (measured: MeasuredDimensions) => MeasuredDimensions;
+}
+
+/**
+ * Provides a reference point for correcting bounds measurements.
+ *
+ * When a parent view has transforms applied (e.g., during screen transitions),
+ * `measure()` returns visual positions that include those transforms. This provider
+ * establishes an anchor point (typically the screen container at 0,0) and exposes
+ * a `correctMeasurement` function that reverses translation and scale transforms
+ * to yield the true layout position and dimensions.
+ *
+ * ## How it works
+ *
+ * 1. **Translation**: Subtract anchor's pageX/pageY offset
+ * 2. **Scale**: Compare anchor's measured size to expected (screen) size to compute
+ *    scale factor, then divide positions and dimensions by that factor
+ */
+const { LayoutAnchorProvider, useLayoutAnchorContext } = createProvider(
+	"LayoutAnchor",
+	{ guarded: false },
+)<LayoutAnchorProviderProps, LayoutAnchorContextValue>(
+	({ anchorRef, children }) => {
+		const { width: screenWidth, height: screenHeight } = useWindowDimensions();
+
+		const correctMeasurement = (
+			measured: MeasuredDimensions,
+		): MeasuredDimensions => {
+			"worklet";
+			const anchor = measure(anchorRef);
+			if (!anchor) return measured;
+
+			// Compute scale factor by comparing anchor size to expected screen size.
+			// Anchor should be full-screen (absoluteFill), so any difference is from scale.
+			const scaleX = anchor.width > 0 ? anchor.width / screenWidth : 1;
+			const scaleY = anchor.height > 0 ? anchor.height / screenHeight : 1;
+
+			// Get element position relative to anchor (removes translation)
+			const relativeX = measured.pageX - anchor.pageX;
+			const relativeY = measured.pageY - anchor.pageY;
+
+			// Reverse scale: divide relative position and dimensions by scale factor
+			return {
+				x: measured.x,
+				y: measured.y,
+				width: scaleX !== 1 ? measured.width / scaleX : measured.width,
+				height: scaleY !== 1 ? measured.height / scaleY : measured.height,
+				pageX: scaleX !== 1 ? relativeX / scaleX : relativeX,
+				pageY: scaleY !== 1 ? relativeY / scaleY : relativeY,
+			};
+		};
+
+		return {
+			value: { correctMeasurement },
+			children,
+		};
+	},
+);
+
+export { LayoutAnchorProvider, useLayoutAnchorContext };

package/src/shared/providers/register-bounds.provider.tsx

@@ -17,7 +17,8 @@ import { AnimationStore } from "../stores/animation.store";
 import { BoundStore } from "../stores/bounds.store";
 import { prepareStyleForBounds } from "../utils/bounds/helpers/styles";
 import createProvider from "../utils/create-provider";
-import { type TransitionDescriptor, useKeys } from "./keys.provider";
+import { useLayoutAnchorContext } from "./layout-anchor.provider";
+import { type BaseDescriptor, useKeys } from "./screen/keys.provider";
 
 interface MaybeMeasureAndStoreParams {
 	onPress?: ((...args: unknown[]) => void) | undefined;
@@ -47,19 +48,26 @@ interface RegisterBoundsContextValue {
  * Returns an array of screen keys from immediate parent to root.
  * [parentKey, grandparentKey, greatGrandparentKey, ...]
  */
-const getAncestorKeys = (current: TransitionDescriptor): string[] => {
+const getAncestorKeys = (current: BaseDescriptor): string[] => {
 	const ancestors: string[] = [];
-	let nav = current.navigation.getParent();
+	const nav = current.navigation as any;
 
-	while (nav) {
-		const state = nav.getState();
+	// Safety check for navigators without getParent
+	if (typeof nav?.getParent !== "function") {
+		return ancestors;
+	}
+
+	let parent = nav.getParent();
+
+	while (parent) {
+		const state = parent.getState();
 		if (state?.routes && state.index !== undefined) {
 			const focusedRoute = state.routes[state.index];
 			if (focusedRoute?.key) {
 				ancestors.push(focusedRoute.key);
 			}
 		}
-		nav = nav.getParent();
+		parent = parent.getParent();
 	}
 
 	return ancestors;
@@ -201,6 +209,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 		const { current } = useKeys();
 		const currentScreenKey = current.route.key;
 		const ancestorKeys = useMemo(() => getAncestorKeys(current), [current]);
+		const layoutAnchor = useLayoutAnchorContext();
 
 		// Context & signals
 		const parentContext: RegisterBoundsContextValue | null =
@@ -234,12 +243,17 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 				const measured = measure(animatedRef);
 				if (!measured) return;
 
+				// Correct for parent transforms (e.g., when parent screen is animating)
+				const correctedMeasured = layoutAnchor
+					? layoutAnchor.correctMeasurement(measured)
+					: measured;
+
 				emitUpdate();
 
 				BoundStore.registerSnapshot(
 					sharedBoundTag,
 					currentScreenKey,
-					measured,
+					correctedMeasured,
 					preparedStyles,
 					ancestorKeys,
 				);
@@ -266,7 +280,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 					BoundStore.setLinkSource(
 						sharedBoundTag,
 						currentScreenKey,
-						measured,
+						correctedMeasured,
 						preparedStyles,
 						ancestorKeys,
 					);
@@ -277,7 +291,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 					BoundStore.setLinkDestination(
 						sharedBoundTag,
 						currentScreenKey,
-						measured,
+						correctedMeasured,
 						preparedStyles,
 						ancestorKeys,
 					);

package/src/shared/providers/{keys.provider.tsx → screen/keys.provider.tsx}

@@ -5,34 +5,49 @@ import type {
 	RouteProp,
 } from "@react-navigation/native";
 import { createContext, useContext, useMemo } from "react";
-import type { ScreenTransitionConfig } from "../types/core.types";
+import type { ScreenTransitionConfig } from "../../types/screen.types";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+} from "../../types/stack.types";
+
+// Re-export for backward compatibility
+export type { BaseStackNavigation as BaseNavigation };
+export type { BaseStackRoute as BaseRoute };
+
+/**
+ * Base descriptor interface - minimal contract for all stack types.
+ * This allows blank-stack and native-stack to work with the shared
+ * providers without tight coupling to React Navigation.
+ */
+export type BaseDescriptor = BaseStackDescriptor;
 
+/**
+ * React Navigation specific descriptor - extends base with full typing
+ */
 export type TransitionDescriptor = Descriptor<
 	ScreenTransitionConfig,
 	NavigationProp<ParamListBase>,
 	RouteProp<ParamListBase>
 >;
 
-export interface KeysContextType<
-	TDescriptor extends TransitionDescriptor = TransitionDescriptor,
-> {
+interface KeysContextType<TDescriptor extends BaseDescriptor = BaseDescriptor> {
 	previous?: TDescriptor;
 	current: TDescriptor;
 	next?: TDescriptor;
 }
 
-const KeysContext = createContext<
-	KeysContextType<TransitionDescriptor> | undefined
->(undefined);
+const KeysContext = createContext<KeysContextType | undefined>(undefined);
 
-interface KeysProviderProps<TDescriptor extends TransitionDescriptor> {
+interface KeysProviderProps<TDescriptor extends BaseDescriptor> {
 	children: React.ReactNode;
 	previous?: TDescriptor;
 	current: TDescriptor;
 	next?: TDescriptor;
 }
 
-export function KeysProvider<TDescriptor extends TransitionDescriptor>({
+export function KeysProvider<TDescriptor extends BaseDescriptor>({
 	children,
 	previous,
 	current,
@@ -47,7 +62,7 @@ export function KeysProvider<TDescriptor extends TransitionDescriptor>({
 }
 
 export function useKeys<
-	TDescriptor extends TransitionDescriptor = TransitionDescriptor,
+	TDescriptor extends BaseDescriptor = BaseDescriptor,
 >(): KeysContextType<TDescriptor> {
 	const context = useContext(KeysContext);
 	if (context === undefined) {

package/src/shared/providers/screen/screen-composer.tsx

@@ -0,0 +1,38 @@
+import type React from "react";
+import type { ComponentType } from "react";
+import { RootTransitionAware } from "../../components/root-transition-aware";
+import { ScreenGestureProvider } from "../gestures.provider";
+import { type BaseDescriptor, KeysProvider } from "./keys.provider";
+import { ScreenStylesProvider } from "./styles.provider";
+
+type Props<TDescriptor extends BaseDescriptor> = {
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+	children: React.ReactNode;
+	LifecycleController: ComponentType<any>;
+};
+
+export function ScreenComposer<TDescriptor extends BaseDescriptor>({
+	previous,
+	current,
+	next,
+	children,
+	LifecycleController,
+}: Props<TDescriptor>) {
+	return (
+		<KeysProvider<TDescriptor>
+			previous={previous}
+			current={current}
+			next={next}
+		>
+			<ScreenGestureProvider>
+				<LifecycleController>
+					<ScreenStylesProvider>
+						<RootTransitionAware>{children}</RootTransitionAware>
+					</ScreenStylesProvider>
+				</LifecycleController>
+			</ScreenGestureProvider>
+		</KeysProvider>
+	);
+}

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

@@ -0,0 +1,120 @@
+import { createContext, 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";
+
+type Props = {
+	children: React.ReactNode;
+};
+
+type ScreenStylesContextValue = {
+	stylesMap: SharedValue<TransitionInterpolatedStyle>;
+	ancestorStylesMaps: SharedValue<TransitionInterpolatedStyle>[];
+};
+
+const ScreenStylesContext = createContext<ScreenStylesContextValue | null>(
+	null,
+);
+
+export function ScreenStylesProvider({ children }: Props) {
+	const parentCtx = useContext(ScreenStylesContext);
+
+	const { screenInterpolatorProps, nextInterpolator, currentInterpolator } =
+		_useScreenAnimation();
+
+	// Track when a gesture is triggered while another screen is closing
+	const hasTriggeredGestureWhileInFlight = useSharedValue(false);
+
+	const stylesMap = useDerivedValue<TransitionInterpolatedStyle>(() => {
+		"worklet";
+		const props = screenInterpolatorProps.value;
+		const bounds = createBounds(props);
+
+		// Detect when user starts gesture on current screen while next screen is closing
+		if (props.current.gesture.isDragging && props.next?.closing) {
+			hasTriggeredGestureWhileInFlight.value = true;
+		}
+
+		// Reset the flag when no longer dragging and next screen is done closing
+		if (
+			!props.current.gesture.isDragging &&
+			!props.next?.closing &&
+			hasTriggeredGestureWhileInFlight.value
+		) {
+			hasTriggeredGestureWhileInFlight.value = false;
+		}
+
+		// Use current interpolator when gesture triggered while in-flight,
+		// otherwise use next interpolator if available (normal case)
+		const shouldUseCurrentInterpolator =
+			props.current.gesture.isDragging ||
+			hasTriggeredGestureWhileInFlight.value;
+
+		const interpolator = shouldUseCurrentInterpolator
+			? currentInterpolator
+			: (nextInterpolator ?? currentInterpolator);
+
+		/**
+		 * Maintainer Note:
+		 * To avoid unnecessary jumps in off directions, we have to snap back to the currents progress.
+		 * While this still introduces a 'snap back' animation, it's still very rare that a user would encounter this unless
+		 * they're spamming things out. Not ideal, but this is the best way to go about dealing with fast rapid gestures.
+		 *
+		 * The alternative was preventing users from actually being able to drag back while animation was still in flight. But there was a significant delay
+		 * when waiting for gestures to register again.
+		 */
+		const effectiveProps = shouldUseCurrentInterpolator
+			? { ...props, progress: props.current.progress, next: undefined }
+			: props;
+
+		try {
+			if (!interpolator) return NO_STYLES;
+			return interpolator({
+				...effectiveProps,
+				bounds,
+			});
+		} 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(
+			"useTransitionStyles must be used within a TransitionStylesProvider",
+		);
+	}
+	return ctx;
+}

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

@@ -0,0 +1,87 @@
+import { SafeAreaProviderCompat } from "@react-navigation/elements";
+import type * as React 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";
+
+export interface StackCoreConfig {
+	TRANSITIONS_ALWAYS_ON?: boolean;
+	STACK_TYPE?: StackType;
+	DISABLE_NATIVE_SCREENS?: boolean;
+}
+
+interface StackCoreProviderProps {
+	config: StackCoreConfig;
+	children: React.ReactNode;
+}
+
+export interface StackCoreContextValue {
+	flags: {
+		TRANSITIONS_ALWAYS_ON: boolean;
+		STACK_TYPE?: StackType;
+		DISABLE_NATIVE_SCREENS: boolean;
+	};
+}
+
+const { StackCoreProvider: InternalStackCoreProvider, useStackCoreContext } =
+	createProvider("StackCore", { guarded: true })<
+		StackCoreProviderProps,
+		StackCoreContextValue
+	>(({ config, children }) => {
+		const {
+			TRANSITIONS_ALWAYS_ON = false,
+			DISABLE_NATIVE_SCREENS = false,
+			STACK_TYPE = StackType.BLANK,
+		} = config;
+
+		return {
+			value: {
+				flags: {
+					TRANSITIONS_ALWAYS_ON,
+					STACK_TYPE,
+					DISABLE_NATIVE_SCREENS,
+				},
+			},
+			children: (
+				<GestureHandlerRootView style={styles.container}>
+					<SafeAreaProviderCompat>{children}</SafeAreaProviderCompat>
+				</GestureHandlerRootView>
+			),
+		};
+	});
+
+/**
+ * HOC that wraps a component with the StackCore provider.
+ * Just a simple open gate
+ */
+export function withStackCore<TProps extends object>(
+	defaultConfig: StackCoreConfig,
+	Component: React.ComponentType<TProps>,
+): React.FC<TProps & StackCoreConfig> {
+	return function StackCoreWrapper({
+		DISABLE_NATIVE_SCREENS,
+		TRANSITIONS_ALWAYS_ON,
+		STACK_TYPE,
+		...props
+	}: TProps & StackCoreConfig) {
+		// User props first, then defaultConfig overrides (config takes priority)
+		const config: StackCoreConfig = {
+			...(DISABLE_NATIVE_SCREENS !== undefined && { DISABLE_NATIVE_SCREENS }),
+			...(TRANSITIONS_ALWAYS_ON !== undefined && { TRANSITIONS_ALWAYS_ON }),
+			...(STACK_TYPE !== undefined && { STACK_TYPE }),
+			...defaultConfig,
+		};
+		return (
+			<InternalStackCoreProvider config={config}>
+				<Component {...(props as TProps)} />
+			</InternalStackCoreProvider>
+		);
+	};
+}
+
+const styles = StyleSheet.create({
+	container: { flex: 1 },
+});
+
+export { useStackCoreContext };