react-native-screen-transitions 3.0.0-rc.4 → 3.0.0

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

@@ -1,5 +1,5 @@
 import { StackActions } from "@react-navigation/native";
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useRef } from "react";
 import { useWindowDimensions } from "react-native";
 import {
 	Gesture,
@@ -48,6 +48,7 @@ export const useBuildGestures = ({
 	ancestorContext,
 }: BuildGesturesHookProps): {
 	panGesture: GestureType;
+	panGestureRef: React.MutableRefObject<GestureType | undefined>;
 	nativeGesture: GestureType;
 	gestureAnimationValues: GestureStoreMap;
 } => {
@@ -63,6 +64,9 @@ export const useBuildGestures = ({
 		GestureOffsetState.PENDING,
 	);
 
+	// Ref for external gesture coordination (e.g., swipeable lists)
+	const panGestureRef = useRef<GestureType | undefined>(undefined);
+
 	const gestureAnimationValues = GestureStore.getRouteGestures(
 		current.route.key,
 	);
@@ -325,26 +329,49 @@ export const useBuildGestures = ({
 		},
 	);
 
+	// Memoize gestures to keep stable references - critical for RNGH
+	// Child gestures reference ancestor's pan via requireExternalGestureToFail,
+	// so the pan gesture MUST be stable or children will reference stale objects
 	return useMemo(() => {
-		const nativeGesture = Gesture.Native();
-
 		const panGesture = Gesture.Pan()
+			.withRef(panGestureRef)
 			.enabled(gestureEnabled)
 			.manualActivation(true)
 			.onTouchesDown(onTouchesDown)
 			.onTouchesMove(onTouchesMove)
 			.onStart(onStart)
 			.onUpdate(onUpdate)
-			.onEnd(onEnd)
-			.blocksExternalGesture(nativeGesture);
+			.onEnd(onEnd);
+
+		// Native gesture setup depends on whether this screen has gestures
+		let nativeGesture: GestureType;
+
+		if (gestureEnabled) {
+			// This screen has gestures - set up normal pan/native relationship
+			nativeGesture = Gesture.Native().requireExternalGestureToFail(panGesture);
+			panGesture.blocksExternalGesture(nativeGesture);
+		} else {
+			// This screen has no gestures
+			// Find nearest ancestor with gestureEnabled=true (attached pan)
+			let activePanAncestor = ancestorContext;
+			while (activePanAncestor && !activePanAncestor.gestureEnabled) {
+				activePanAncestor = activePanAncestor.ancestorContext;
+			}
 
-		// Allow ancestors to block child native gestures
-		if (ancestorContext?.panGesture && nativeGesture) {
-			ancestorContext.panGesture.blocksExternalGesture(nativeGesture);
+			if (activePanAncestor?.panGesture) {
+				// Found an ancestor with enabled pan - wait for it
+				nativeGesture = Gesture.Native().requireExternalGestureToFail(
+					activePanAncestor.panGesture,
+				);
+			} else {
+				// No ancestor with enabled pan - plain native
+				nativeGesture = Gesture.Native();
+			}
 		}
 
 		return {
 			panGesture,
+			panGestureRef,
 			nativeGesture,
 			gestureAnimationValues,
 		};

package/src/shared/hooks/gestures/use-screen-gesture.ts

@@ -0,0 +1,19 @@
+import { useGestureContext } from "../../providers/gestures.provider";
+
+/**
+ * Returns a ref to the screen's navigation pan gesture.
+ * Use this to coordinate child gestures with the navigation gesture.
+ *
+ * @example
+ * ```tsx
+ * const screenGesture = useScreenGesture();
+ *
+ * const myPanGesture = Gesture.Pan()
+ *   .waitFor(screenGesture) // Wait for navigation gesture to fail first
+ *   .onUpdate(...);
+ * ```
+ */
+export const useScreenGesture = () => {
+	const ctx = useGestureContext();
+	return ctx?.panGestureRef ?? null;
+};

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

@@ -1,3 +1,6 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: <Will always consume context from GestureProvider> */
+
+import { useMemo } from "react";
 import type { LayoutChangeEvent } from "react-native";
 import { useAnimatedScrollHandler } from "react-native-reanimated";
 import type { ReanimatedScrollEvent } from "react-native-reanimated/lib/typescript/hook/commonTypes";
@@ -12,13 +15,26 @@ interface ScrollProgressHookProps {
 }
 
 export const useScrollRegistry = (props: ScrollProgressHookProps) => {
-	const { scrollConfig, ancestorContext } = useGestureContext();
+	const context = useGestureContext()!;
+	const { scrollConfig, ancestorContext } = context;
+
+	const ancestorScrollConfigs = useMemo(() => {
+		const configs: (typeof scrollConfig)[] = [];
+		let current = ancestorContext;
+		while (current) {
+			if (current.scrollConfig) {
+				configs.push(current.scrollConfig);
+			}
+			current = current.ancestorContext;
+		}
+		return configs;
+	}, [ancestorContext]);
 
 	const scrollHandler = useAnimatedScrollHandler({
 		onScroll: (event) => {
 			props.onScroll?.(event);
 
-			scrollConfig.modify((v: Any) => {
+			const updateScrollPosition = (v: Any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -33,25 +49,13 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				v.x = event.contentOffset.x;
 				v.y = event.contentOffset.y;
 				return v;
-			});
-
-			if (ancestorContext?.scrollConfig) {
-				ancestorContext.scrollConfig.modify((v: Any) => {
-					"worklet";
-					if (v === null) {
-						return {
-							x: event.contentOffset.x,
-							y: event.contentOffset.y,
-							contentHeight: 0,
-							contentWidth: 0,
-							layoutHeight: 0,
-							layoutWidth: 0,
-						};
-					}
-					v.x = event.contentOffset.x;
-					v.y = event.contentOffset.y;
-					return v;
-				});
+			};
+
+			scrollConfig.modify(updateScrollPosition);
+
+			// Sync to ALL ancestors, not just immediate parent
+			for (const ancestorConfig of ancestorScrollConfigs) {
+				ancestorConfig.modify(updateScrollPosition);
 			}
 		},
 	});
@@ -60,7 +64,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		(width: number, height: number) => {
 			props.onContentSizeChange?.(width, height);
 
-			scrollConfig.modify((v: Any) => {
+			const updateContentSize = (v: Any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -75,24 +79,12 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				v.contentWidth = width;
 				v.contentHeight = height;
 				return v;
-			});
-			if (ancestorContext?.scrollConfig) {
-				ancestorContext.scrollConfig.modify((v: Any) => {
-					"worklet";
-					if (v === null) {
-						return {
-							x: 0,
-							y: 0,
-							layoutHeight: 0,
-							layoutWidth: 0,
-							contentWidth: width,
-							contentHeight: height,
-						};
-					}
-					v.contentWidth = width;
-					v.contentHeight = height;
-					return v;
-				});
+			};
+
+			scrollConfig.modify(updateContentSize);
+
+			for (const ancestorConfig of ancestorScrollConfigs) {
+				ancestorConfig.modify(updateContentSize);
 			}
 		},
 	);
@@ -101,7 +93,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		props.onLayout?.(event);
 		const { width, height } = event.nativeEvent.layout;
 
-		scrollConfig.modify((v: Any) => {
+		const updateLayout = (v: Any) => {
 			"worklet";
 			if (v === null) {
 				return {
@@ -116,24 +108,12 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 			v.layoutHeight = height;
 			v.layoutWidth = width;
 			return v;
-		});
-		if (ancestorContext?.scrollConfig) {
-			ancestorContext.scrollConfig.modify((v: Any) => {
-				"worklet";
-				if (v === null) {
-					return {
-						x: 0,
-						y: 0,
-						contentHeight: 0,
-						contentWidth: 0,
-						layoutHeight: height,
-						layoutWidth: width,
-					};
-				}
-				v.layoutHeight = height;
-				v.layoutWidth = width;
-				return v;
-			});
+		};
+
+		scrollConfig.modify(updateLayout);
+
+		for (const ancestorConfig of ancestorScrollConfigs) {
+			ancestorConfig.modify(updateLayout);
 		}
 	});
 

package/src/shared/index.ts

@@ -19,6 +19,7 @@ export default {
 };
 
 export { useScreenAnimation } from "./hooks/animation/use-screen-animation";
+export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
 
 export type {
 	AnimationConfig,
@@ -26,4 +27,5 @@ export type {
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
 } from "./types/animation.types";
+export type { BoundEntry, BoundsLink } from "./types/bounds.types";
 export type { ScreenTransitionConfig } from "./types/core.types";

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

@@ -1,11 +1,13 @@
-import { createContext, useContext, useMemo } from "react";
 import { StyleSheet, View } from "react-native";
-import type { GestureType } from "react-native-gesture-handler";
-import { GestureDetector } from "react-native-gesture-handler";
+import {
+	GestureDetector,
+	type GestureType,
+} from "react-native-gesture-handler";
 import type { SharedValue } from "react-native-reanimated";
 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";
 
 export type ScrollConfig = {
@@ -19,94 +21,52 @@ export type ScrollConfig = {
 
 export interface GestureContextType {
 	panGesture: GestureType;
+	panGestureRef: React.MutableRefObject<GestureType | undefined>;
 	nativeGesture: GestureType;
 	scrollConfig: SharedValue<ScrollConfig | null>;
 	gestureAnimationValues: GestureStoreMap;
-	ancestorContext: GestureContextType | undefined;
+	ancestorContext: GestureContextType | null;
+	gestureEnabled: boolean;
 }
 
-type GestureProviderProps = {
-	children: React.ReactNode;
-};
-
-const GestureContext = createContext<GestureContextType | undefined>(undefined);
-
-/**
- * Provider that creates gesture handling for a screen.
- * If the current screen doesn't have gestures enabled but a parent does,
- * we pass through the parent's context so scrollable children can coordinate
- * with the ancestor's gestures.
- */
-export const ScreenGestureProvider = ({ children }: GestureProviderProps) => {
-	const ancestorContext = useContext(GestureContext);
+export const {
+	ScreenGestureProvider,
+	useScreenGestureContext: useGestureContext,
+} = createProvider("ScreenGesture", { guarded: false })<
+	{ children: React.ReactNode },
+	GestureContextType
+>(({ children }) => {
 	const { current } = useKeys();
-
-	const hasOwnGestures = current.options.gestureEnabled === true;
-
-	// If this screen doesn't have its own gestures but an ancestor does,
-	// pass through so scrollable children coordinate with that ancestor
-	if (!hasOwnGestures && ancestorContext) {
-		return children;
-	}
-
-	return (
-		<ScreenGestureProviderInner ancestorContext={ancestorContext}>
-			{children}
-		</ScreenGestureProviderInner>
-	);
-};
-
-const ScreenGestureProviderInner = ({
-	children,
-	ancestorContext,
-}: GestureProviderProps & {
-	ancestorContext: GestureContextType | undefined;
-}) => {
+	const ancestorContext = useGestureContext();
 	const scrollConfig = useSharedValue<ScrollConfig | null>(null);
 
-	const { panGesture, nativeGesture, gestureAnimationValues } =
+	const hasGestures = current.options.gestureEnabled === true;
+
+	const { panGesture, panGestureRef, nativeGesture, gestureAnimationValues } =
 		useBuildGestures({
 			scrollConfig,
 			ancestorContext,
 		});
 
-	const value: GestureContextType = useMemo(
-		() => ({
-			panGesture,
-			scrollConfig,
-			nativeGesture,
-			gestureAnimationValues,
-			ancestorContext,
-		}),
-		[
-			panGesture,
-			scrollConfig,
-			nativeGesture,
-			gestureAnimationValues,
-			ancestorContext,
-		],
-	);
-
-	return (
-		<GestureContext.Provider value={value}>
+	const value: GestureContextType = {
+		panGesture,
+		panGestureRef,
+		scrollConfig,
+		nativeGesture,
+		gestureAnimationValues,
+		ancestorContext,
+		gestureEnabled: hasGestures,
+	};
+
+	return {
+		value,
+		children: (
 			<GestureDetector gesture={panGesture}>
 				<View style={styles.container}>{children}</View>
 			</GestureDetector>
-		</GestureContext.Provider>
-	);
-};
-
-export const useGestureContext = () => {
-	const context = useContext(GestureContext);
-
-	if (!context) {
-		throw new Error(
-			"useGestureContext must be used within a ScreenGestureProvider",
-		);
-	}
-
-	return context;
-};
+		),
+	};
+});
 
 const styles = StyleSheet.create({
 	container: {

package/src/shared/types/animation.types.ts

@@ -21,10 +21,59 @@ export interface OverlayInterpolationProps {
 }
 
 export type ScreenTransitionState = {
+	/**
+	 * Animation progress for this screen.
+	 * - `0`: Screen is fully off-screen (entering)
+	 * - `1`: Screen is fully visible (active)
+	 *
+	 * This value animates from 0 to 1 when the screen enters,
+	 * and from 1 to 0 when it exits.
+	 */
 	progress: number;
+
+	/**
+	 * Whether this screen is in the process of being dismissed.
+	 * - `0`: Screen is opening or active
+	 * - `1`: Screen is closing/being dismissed
+	 *
+	 * Use this to trigger different animations when navigating back vs forward.
+	 */
 	closing: number;
+
+	/**
+	 * Whether this screen is currently animating.
+	 * - `0`: No animation in progress
+	 * - `1`: Animation or gesture is in progress
+	 */
 	animating: number;
+
+	/**
+	 * Live gesture values for this screen.
+	 * Contains translation (x, y), normalized values (-1 to 1),
+	 * and flags for dragging/dismissing state.
+	 */
 	gesture: GestureValues;
+
+	/**
+	 * Custom metadata passed from screen options.
+	 * Use this for conditional animation logic instead of checking route names.
+	 *
+	 * @example
+	 * // In screen options:
+	 * options={{ meta: { scalesOthers: true } }}
+	 *
+	 * // In animation logic:
+	 * if (props.next?.meta?.scalesOthers) { ... }
+	 */
+	meta?: Record<string, unknown>;
+
+	/**
+	 * The route object for this screen.
+	 *
+	 * @deprecated Use `meta` instead for conditional animation logic.
+	 * Pass route params via options: `options={({ route }) => ({ meta: { id: route.params.id } })}`
+	 * This field may be removed in a future version.
+	 */
 	route: RouteProp<ParamListBase>;
 };
 

package/src/shared/types/bounds.types.ts

@@ -19,7 +19,18 @@ export type BoundEntry = {
 	styles: StyleProps;
 };
 
+export type BoundsLink = {
+	source: BoundEntry | null;
+	destination: BoundEntry | null;
+};
+
 export type BoundsAccessor = {
 	<T extends BoundsBuilderOptions>(options: T): BoundsReturnType<T>;
 	getSnapshot: (id: string, key?: string) => Snapshot | null;
+	getLink: (id: string) => BoundsLink | null;
+	interpolateStyle: (
+		id: string,
+		property: keyof StyleProps,
+		fallback?: number,
+	) => number;
 };

package/src/shared/types/core.types.ts

@@ -100,4 +100,12 @@ export type ScreenTransitionConfig = {
 	 * The area of the screen where the gesture is activated.
 	 */
 	gestureActivationArea?: GestureActivationArea;
+
+	/**
+	 * Custom metadata passed through to animation props.
+	 *
+	 * @example
+	 * options={{ meta: { scalesOthers: true } }}
+	 */
+	meta?: Record<string, unknown>;
 };

package/src/shared/utils/bounds/helpers/interpolate-style.ts

@@ -0,0 +1,38 @@
+import { interpolate } from "react-native-reanimated";
+import { ENTER_RANGE, EXIT_RANGE } from "../../../constants";
+import type { BoundsLink } from "../../../types/bounds.types";
+
+type InterpolateStyleOptions = {
+	fallback?: number;
+};
+
+/**
+ * Interpolates a numeric style property between source and destination bounds.
+ *
+ * @param link - The bounds link containing source and destination styles
+ * @param property - The style property to interpolate (e.g., "borderRadius", "opacity")
+ * @param progress - Animation progress value
+ * @param entering - Whether the screen is entering (focused) or exiting (unfocused)
+ * @param options - Optional configuration
+ * @returns The interpolated value
+ */
+export function interpolateLinkStyle(
+	link: BoundsLink | null,
+	property: string,
+	progress: number,
+	entering: boolean,
+	options: InterpolateStyleOptions = {},
+): number {
+	"worklet";
+
+	const { fallback = 0 } = options;
+
+	const sourceValue =
+		(link?.source?.styles?.[property] as number | undefined) ?? fallback;
+	const destValue =
+		(link?.destination?.styles?.[property] as number | undefined) ?? fallback;
+
+	const range = entering ? ENTER_RANGE : EXIT_RANGE;
+
+	return interpolate(progress, range, [sourceValue, destValue], "clamp");
+}

package/src/shared/utils/bounds/index.ts

@@ -11,12 +11,13 @@ import type {
 	ScreenInterpolationProps,
 	ScreenTransitionState,
 } from "../../types/animation.types";
-import type { BoundsAccessor } from "../../types/bounds.types";
+import type { BoundsAccessor, BoundsLink } from "../../types/bounds.types";
 import type { Layout } from "../../types/core.types";
 import {
 	computeContentTransformGeometry,
 	computeRelativeGeometry,
 } from "./helpers/geometry";
+import { interpolateLinkStyle } from "./helpers/interpolate-style";
 import {
 	composeContentStyle,
 	composeSizeAbsolute,
@@ -207,7 +208,36 @@ export const createBounds = (
 		return BoundStore.getSnapshot(tag, key);
 	};
 
+	const getLink = (tag: string): BoundsLink | null => {
+		"worklet";
+		const link = BoundStore.getActiveLink(tag, props.current?.route.key);
+		if (!link) return null;
+		return {
+			source: link.source
+				? { bounds: link.source.bounds, styles: link.source.styles }
+				: null,
+			destination: link.destination
+				? { bounds: link.destination.bounds, styles: link.destination.styles }
+				: null,
+		};
+	};
+
+	const interpolateStyle = (
+		tag: string,
+		property: string,
+		fallback?: number,
+	): number => {
+		"worklet";
+		const link = getLink(tag);
+		const entering = !props.next;
+		return interpolateLinkStyle(link, property, props.progress, entering, {
+			fallback,
+		});
+	};
+
 	return Object.assign(boundsFunction, {
 		getSnapshot,
+		getLink,
+		interpolateStyle,
 	}) as BoundsAccessor;
 };

package/src/shared/utils/create-provider.tsx

@@ -9,8 +9,11 @@ import {
 	type ReactNode,
 	useContext,
 	useMemo,
+	useRef,
 } from "react";
 
+type InnerProviderComponent = (props: { children: ReactNode }) => ReactNode;
+
 export default function createProvider<
 	ProviderName extends string,
 	Guarded extends boolean = true,
@@ -19,7 +22,13 @@ export default function createProvider<
 		factory: (props: ProviderProps) => {
 			value?: ContextValue;
 			enabled?: boolean;
-			children?: ReactNode;
+			children?:
+				| ReactNode
+				| ((
+						innerProvider: {
+							[K in ProviderName as `${K}Provider`]: InnerProviderComponent;
+						},
+				  ) => ReactNode);
 		},
 	) => {
 		const { guarded = true } = options ?? {};
@@ -45,6 +54,27 @@ export default function createProvider<
 				[enabled, value],
 			);
 
+			// Per-instance ref ensures InnerProvider reads latest value while keeping
+			// a stable component reference.
+			const valueRef = useRef<ContextValue | null>(memoValue);
+			valueRef.current = memoValue;
+
+			const InnerProvider = useMemo(
+				(): InnerProviderComponent =>
+					({ children }) => (
+						<Context.Provider value={valueRef.current}>
+							{children}
+						</Context.Provider>
+					),
+				[],
+			);
+
+			if (typeof children === "function") {
+				return children({
+					[`${name}Provider`]: InnerProvider,
+				} as { [K in ProviderName as `${K}Provider`]: InnerProviderComponent });
+			}
+
 			return <Context.Provider value={memoValue}>{children}</Context.Provider>;
 		};
 

package/src/shared/utils/gesture/check-gesture-activation.ts

@@ -72,7 +72,7 @@ const DEFAULT_EDGE_DISTANCE_HORIZONTAL = 50;
 const DEFAULT_EDGE_DISTANCE_VERTICAL = 135;
 const DEFAULT_ACTIVATION_AREA = "screen" as const;
 
-function normalizeSides(area?: GestureActivationArea): NormalizedSides {
+export function normalizeSides(area?: GestureActivationArea): NormalizedSides {
 	"worklet";
 	if (!area || typeof area === "string") {
 		const mode: ActivationArea = area ?? DEFAULT_ACTIVATION_AREA;
@@ -88,7 +88,7 @@ function normalizeSides(area?: GestureActivationArea): NormalizedSides {
 	};
 }
 
-function computeEdgeConstraints(
+export function computeEdgeConstraints(
 	initialTouch: { x: number; y: number },
 	dimensions: Layout,
 	sides: NormalizedSides,
@@ -108,7 +108,7 @@ function computeEdgeConstraints(
 	return { horizontalRight, horizontalLeft, verticalDown, verticalUp } as const;
 }
 
-function calculateSwipeDirs(deltaX: number, deltaY: number) {
+export function calculateSwipeDirs(deltaX: number, deltaY: number) {
 	"worklet";
 
 	const isVerticalSwipe = Math.abs(deltaY) > Math.abs(deltaX);
@@ -129,7 +129,7 @@ function calculateSwipeDirs(deltaX: number, deltaY: number) {
 	};
 }
 
-function shouldActivateOrFail(params: ShouldActivateOrFailProps) {
+export function shouldActivateOrFail(params: ShouldActivateOrFailProps) {
 	"worklet";
 
 	const {