react-native-screen-transitions 3.0.0-rc.2 → 3.0.0-rc.3

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

@@ -5,6 +5,7 @@ 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,
 	useKeys,
@@ -16,6 +17,7 @@ import type {
 	ScreenTransitionState,
 } from "../../types/animation.types";
 import type { ScreenTransitionConfig } from "../../types/core.types";
+import type { GestureDirection } from "../../types/gesture.types";
 import { derivations } from "../../utils/animation/derivations";
 import { createBounds } from "../../utils/bounds";
 
@@ -25,30 +27,45 @@ type BuiltState = {
 	animating: SharedValue<number>;
 	gesture: GestureStoreMap;
 	route: RouteProp<ParamListBase>;
+	unwrapped: ScreenTransitionState;
 };
 
-const unwrap = (
-	s: BuiltState | undefined,
-	key: string | undefined,
-): ScreenTransitionState | undefined => {
+const createScreenTransitionState = (
+	route: RouteProp<ParamListBase>,
+): ScreenTransitionState => ({
+	progress: 0,
+	closing: 0,
+	animating: 0,
+	gesture: {
+		x: 0,
+		y: 0,
+		normalizedX: 0,
+		normalizedY: 0,
+		isDismissing: 0,
+		isDragging: 0,
+		direction: null,
+	},
+	route,
+});
+
+const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 	"worklet";
-	if (!s || !key) return undefined;
-
-	return {
-		progress: s.progress.value,
-		closing: s.closing.value,
-		animating: s.animating.value,
-		gesture: {
-			x: s.gesture.x.value,
-			y: s.gesture.y.value,
-			normalizedX: s.gesture.normalizedX.value,
-			normalizedY: s.gesture.normalizedY.value,
-			isDismissing: s.gesture.isDismissing.value,
-			isDragging: s.gesture.isDragging.value,
-			direction: s.gesture.direction.value,
-		},
-		route: s.route,
-	};
+	const out = s.unwrapped;
+	out.progress = s.progress.value;
+	out.closing = s.closing.value;
+	out.animating = s.animating.value;
+	out.gesture.x = s.gesture.x.value;
+	out.gesture.y = s.gesture.y.value;
+	out.gesture.normalizedX = s.gesture.normalizedX.value;
+	out.gesture.normalizedY = s.gesture.normalizedY.value;
+	out.gesture.isDismissing = s.gesture.isDismissing.value;
+	out.gesture.isDragging = s.gesture.isDragging.value;
+	out.gesture.direction = s.gesture.direction.value as Omit<
+		GestureDirection,
+		"bidirectional"
+	> | null;
+
+	return out;
 };
 
 const useBuildScreenTransitionState = (
@@ -65,18 +82,25 @@ const useBuildScreenTransitionState = (
 			animating: AnimationStore.getAnimation(key, "animating"),
 			gesture: GestureStore.getRouteGestures(key),
 			route: descriptor.route,
+			unwrapped: createScreenTransitionState(descriptor.route),
 		};
 	}, [key, descriptor?.route]);
 };
 
-const hasTransitionsEnabled = (options?: ScreenTransitionConfig) => {
+const hasTransitionsEnabled = (
+	options: ScreenTransitionConfig | undefined,
+	alwaysOn: boolean,
+) => {
 	"worklet";
+	if (alwaysOn) return true;
 	return !!(options as NativeStackScreenTransitionConfig)?.enableTransitions;
 };
 
 export function _useScreenAnimation() {
 	const dimensions = useWindowDimensions();
 	const insets = useSafeAreaInsets();
+	const flags = useFlagsContext();
+	const transitionsAlwaysOn = flags?.TRANSITIONS_ALWAYS_ON ?? false;
 
 	const {
 		current: currentDescriptor,
@@ -93,15 +117,17 @@ export function _useScreenAnimation() {
 	>(() => {
 		"worklet";
 
-		const previous = unwrap(prevAnimation, previousDescriptor?.route.key);
+		const previous = prevAnimation ? unwrapInto(prevAnimation) : undefined;
 
-		const next = hasTransitionsEnabled(nextDescriptor?.options)
-			? unwrap(nextAnimation, nextDescriptor?.route.key)
-			: undefined;
+		const next =
+			nextAnimation &&
+			hasTransitionsEnabled(nextDescriptor?.options, transitionsAlwaysOn)
+				? unwrapInto(nextAnimation)
+				: undefined;
 
-		const current =
-			unwrap(currentAnimation, currentDescriptor?.route.key) ??
-			DEFAULT_SCREEN_TRANSITION_STATE;
+		const current = currentAnimation
+			? unwrapInto(currentAnimation)
+			: DEFAULT_SCREEN_TRANSITION_STATE;
 
 		const helpers = derivations({
 			current,

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

@@ -26,7 +26,10 @@ import { useKeys } from "../../providers/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 
-import { type GestureDirection, GestureOffsetState } from "../../types/gesture.types";
+import {
+	type GestureDirection,
+	GestureOffsetState,
+} from "../../types/gesture.types";
 import { startScreenTransition } from "../../utils/animation/start-screen-transition";
 import { applyOffsetRules } from "../../utils/gesture/check-gesture-activation";
 import { determineDismissal } from "../../utils/gesture/determine-dismissal";

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

@@ -0,0 +1,21 @@
+import createProvider from "../utils/create-provider";
+
+interface FlagsValue {
+	TRANSITIONS_ALWAYS_ON: boolean;
+}
+
+interface FlagsProviderProps {
+	TRANSITIONS_ALWAYS_ON?: boolean;
+	children: React.ReactNode;
+}
+
+const { FlagsProvider, useFlagsContext } = createProvider("Flags", {
+	guarded: false,
+})<FlagsProviderProps, FlagsValue>(
+	({ TRANSITIONS_ALWAYS_ON = false, children }) => ({
+		value: { TRANSITIONS_ALWAYS_ON },
+		children,
+	}),
+);
+
+export { FlagsProvider, useFlagsContext };

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

@@ -43,27 +43,26 @@ interface RegisterBoundsContextValue {
 }
 
 /**
- * Gets the parent screen's route key for nested navigators.
- * Returns undefined if we're not inside a nested navigator.
+ * Builds the full ancestor key chain for nested navigators.
+ * Returns an array of screen keys from immediate parent to root.
+ * [parentKey, grandparentKey, greatGrandparentKey, ...]
  */
-const getParentScreenKey = (current: TransitionDescriptor) => {
-	const parent = current.navigation.getParent();
-	if (!parent) return undefined;
-
-	const parentState = parent.getState();
-	if (!parentState?.routes) return undefined;
-
-	// Check if our route key exists directly in parent's routes
-	const existsInParent = parentState.routes.some(
-		(r) => r.key === current.route.key,
-	);
-
-	// If we don't exist in parent's routes, we're nested inside the focused route
-	if (!existsInParent && parentState.index !== undefined) {
-		return parentState.routes[parentState.index]?.key;
+const getAncestorKeys = (current: TransitionDescriptor): string[] => {
+	const ancestors: string[] = [];
+	let nav = current.navigation.getParent();
+
+	while (nav) {
+		const state = nav.getState();
+		if (state?.routes && state.index !== undefined) {
+			const focusedRoute = state.routes[state.index];
+			if (focusedRoute?.key) {
+				ancestors.push(focusedRoute.key);
+			}
+		}
+		nav = nav.getParent();
 	}
 
-	return undefined;
+	return ancestors;
 };
 
 /**
@@ -73,13 +72,13 @@ const getParentScreenKey = (current: TransitionDescriptor) => {
 const useInitialLayoutHandler = (params: {
 	sharedBoundTag?: string;
 	currentScreenKey: string;
-	parentScreenKey?: string;
+	ancestorKeys: string[];
 	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
 }) => {
 	const {
 		sharedBoundTag,
 		currentScreenKey,
-		parentScreenKey,
+		ancestorKeys,
 		maybeMeasureAndStore,
 	} = params;
 
@@ -87,57 +86,84 @@ const useInitialLayoutHandler = (params: {
 		currentScreenKey,
 		"animating",
 	);
-	const isParentAnimating = parentScreenKey
-		? AnimationStore.getAnimation(parentScreenKey, "animating")
-		: null;
+
+	// Check if any ancestor is animating
+	const ancestorAnimations = ancestorKeys.map((key) =>
+		AnimationStore.getAnimation(key, "animating"),
+	);
 
 	const hasMeasuredOnLayout = useSharedValue(false);
 
 	return useCallback(() => {
 		"worklet";
-		if (!sharedBoundTag || hasMeasuredOnLayout.value) return;
-		if (!isAnimating.value && !isParentAnimating?.value) return;
+		if (!sharedBoundTag || hasMeasuredOnLayout.get()) return;
+
+		// Check if current or any ancestor is animating
+		let isAnyAnimating = isAnimating.get();
+		for (let i = 0; i < ancestorAnimations.length; i++) {
+			if (ancestorAnimations[i].get()) {
+				isAnyAnimating = 1;
+				break;
+			}
+		}
+
+		if (!isAnyAnimating) return;
 
 		maybeMeasureAndStore({
 			shouldSetSource: false,
 			shouldSetDestination: true,
 		});
 
-		hasMeasuredOnLayout.value = true;
+		hasMeasuredOnLayout.set(true);
 	}, [
 		sharedBoundTag,
 		hasMeasuredOnLayout,
 		isAnimating,
-		isParentAnimating,
+		ancestorAnimations,
 		maybeMeasureAndStore,
 	]);
 };
 
+/**
+ * Measures non-pressable elements when screen becomes blurred.
+ * Captures bounds right before transition starts.
+ */
 /**
  * Measures non-pressable elements when screen becomes blurred.
  * Captures bounds right before transition starts.
  */
 const useBlurMeasurement = (params: {
 	sharedBoundTag?: string;
+	ancestorKeys: string[];
 	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
 }) => {
-	const { sharedBoundTag, maybeMeasureAndStore } = params;
-	const isFocused = useRef(true);
+	const { current } = useKeys();
+	const { sharedBoundTag, ancestorKeys, maybeMeasureAndStore } = params;
 	const hasCapturedSource = useRef(false);
 
+	const ancestorClosing = [current.route.key, ...ancestorKeys].map((key) =>
+		AnimationStore.getAnimation(key, "closing"),
+	);
+
+	const maybeMeasureOnBlur = useStableCallbackValue(() => {
+		"worklet";
+
+		// Don't measure if current / any ancestor is closing
+		const isOneClosing = ancestorClosing.some((closing) => closing.get());
+		if (isOneClosing) return;
+
+		maybeMeasureAndStore({ shouldSetSource: true });
+	});
+
 	useFocusEffect(
 		useCallback(() => {
-			isFocused.current = true;
 			hasCapturedSource.current = false;
 
 			return () => {
-				if (!sharedBoundTag) return;
-				if (hasCapturedSource.current) return;
-
-				isFocused.current = false;
-				runOnUI(maybeMeasureAndStore)({ shouldSetSource: true });
+				if (!sharedBoundTag || hasCapturedSource.current) return;
+				runOnUI(maybeMeasureOnBlur)();
 			};
-		}, [sharedBoundTag, maybeMeasureAndStore]),
+		}, [sharedBoundTag, maybeMeasureOnBlur]),
 	);
 
 	return {
@@ -157,7 +183,7 @@ const useParentSyncReaction = (params: {
 	const { parentContext, maybeMeasureAndStore } = params;
 
 	useAnimatedReaction(
-		() => parentContext?.updateSignal.value,
+		() => parentContext?.updateSignal.get(),
 		(value) => {
 			"worklet";
 			if (value === 0 || value === undefined) return;
@@ -173,11 +199,12 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 	({ style, onPress, sharedBoundTag, animatedRef, children }) => {
 		const { current } = useKeys();
 		const currentScreenKey = current.route.key;
-		const parentScreenKey = getParentScreenKey(current);
+		const ancestorKeys = useMemo(() => getAncestorKeys(current), [current]);
 
 		// Context & signals
 		const parentContext: RegisterBoundsContextValue | null =
 			useRegisterBoundsContext();
+
 		const ownSignal = useSharedValue(0);
 		const updateSignal: SharedValue<number> =
 			parentContext?.updateSignal ?? ownSignal;
@@ -191,7 +218,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 		const emitUpdate = useStableCallbackValue(() => {
 			"worklet";
 			const isRoot = !parentContext;
-			if (isRoot) updateSignal.value = updateSignal.value + 1;
+			if (isRoot) updateSignal.set(updateSignal.get() + 1);
 		});
 
 		const maybeMeasureAndStore = useStableCallbackValue(
@@ -208,28 +235,31 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 
 				emitUpdate();
 
-				// Always register occurrence
-				BoundStore.registerOccurrence(
+				BoundStore.registerSnapshot(
 					sharedBoundTag,
 					currentScreenKey,
 					measured,
 					preparedStyles,
+					ancestorKeys,
 				);
 
-				// Set as source (on press or blur)
 				if (shouldSetSource) {
-					if (isAnimating.value) {
-						const existing = BoundStore.getOccurrence(
-							sharedBoundTag,
-							currentScreenKey,
-						);
-						BoundStore.setLinkSource(
+					if (isAnimating.get()) {
+						// If animation is already in progress,
+						// lets use the existing measuremenets.
+						const existing = BoundStore.getSnapshot(
 							sharedBoundTag,
 							currentScreenKey,
-							existing.bounds,
-							preparedStyles,
-							parentScreenKey,
 						);
+						if (existing) {
+							BoundStore.setLinkSource(
+								sharedBoundTag,
+								currentScreenKey,
+								existing.bounds,
+								preparedStyles,
+								ancestorKeys,
+							);
+						}
 						return;
 					}
 					BoundStore.setLinkSource(
@@ -237,7 +267,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 						currentScreenKey,
 						measured,
 						preparedStyles,
-						parentScreenKey,
+						ancestorKeys,
 					);
 				}
 
@@ -248,7 +278,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 						currentScreenKey,
 						measured,
 						preparedStyles,
-						parentScreenKey,
+						ancestorKeys,
 					);
 				}
 
@@ -259,7 +289,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 		const handleInitialLayout = useInitialLayoutHandler({
 			sharedBoundTag,
 			currentScreenKey,
-			parentScreenKey,
+			ancestorKeys,
 			maybeMeasureAndStore,
 		});
 
@@ -267,6 +297,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 		const { markSourceCaptured } = useBlurMeasurement({
 			sharedBoundTag,
 			maybeMeasureAndStore,
+			ancestorKeys,
 		});
 
 		useParentSyncReaction({ parentContext, maybeMeasureAndStore });

package/src/shared/stores/bounds.store.ts

@@ -8,51 +8,42 @@ import type { Any } from "../types/utils.types";
 type TagID = string;
 type ScreenKey = string;
 
-export type TagData = {
+export type Snapshot = {
 	bounds: MeasuredDimensions;
 	styles: StyleProps;
 };
 
 type ScreenIdentifier = {
 	screenKey: ScreenKey;
-	parentScreenKey?: ScreenKey;
+	ancestorKeys?: ScreenKey[];
 };
 
 type TagLink = {
-	source: ScreenIdentifier & TagData;
-	destination: (ScreenIdentifier & TagData) | null;
+	source: ScreenIdentifier & Snapshot;
+	destination: (ScreenIdentifier & Snapshot) | null;
 };
 
 type TagState = {
-	occurrences: Record<ScreenKey, TagData>;
+	snapshots: Record<ScreenKey, Snapshot & { ancestorKeys?: ScreenKey[] }>;
 	linkStack: TagLink[];
 };
 
-/**
- * Note on cleanup: We intentionally skip automatic cleanup of old links.
- * The linkStack grows by one entry per navigation, but `getActiveLink`
- * finds the correct link via screenKey matching regardless of stack size.
- * This is unlikely to cause performance issues in typical apps, but if
- * memory becomes a concern in apps with heavy navigation (hundreds of
- * transitions), we should consider implementing cleanup on screen unmount using
- * screenKey filtering.
- */
-
 const registry = makeMutable<Record<TagID, TagState>>({});
 
-function registerOccurrence(
+function registerSnapshot(
 	tag: TagID,
 	screenKey: ScreenKey,
 	bounds: MeasuredDimensions,
 	styles: StyleProps = {},
+	ancestorKeys?: ScreenKey[],
 ) {
 	"worklet";
 	registry.modify((state: Any) => {
 		"worklet";
 		if (!state[tag]) {
-			state[tag] = { occurrences: {}, linkStack: [] };
+			state[tag] = { snapshots: {}, linkStack: [] };
 		}
-		state[tag].occurrences[screenKey] = { bounds, styles };
+		state[tag].snapshots[screenKey] = { bounds, styles, ancestorKeys };
 		return state;
 	});
 }
@@ -62,16 +53,15 @@ function setLinkSource(
 	screenKey: ScreenKey,
 	bounds: MeasuredDimensions,
 	styles: StyleProps = {},
-	parentScreenKey?: ScreenKey,
+	ancestorKeys?: ScreenKey[],
 ) {
 	"worklet";
 	registry.modify((state: Any) => {
 		"worklet";
-		if (!state[tag]) state[tag] = { occurrences: {}, linkStack: [] };
+		if (!state[tag]) state[tag] = { snapshots: {}, linkStack: [] };
 
-		// Push new link onto stack
 		state[tag].linkStack.push({
-			source: { screenKey, parentScreenKey, bounds, styles },
+			source: { screenKey, ancestorKeys, bounds, styles },
 			destination: null,
 		});
 		return state;
@@ -83,7 +73,7 @@ function setLinkDestination(
 	screenKey: ScreenKey,
 	bounds: MeasuredDimensions,
 	styles: StyleProps = {},
-	parentScreenKey?: ScreenKey,
+	ancestorKeys?: ScreenKey[],
 ) {
 	"worklet";
 	registry.modify((state: Any) => {
@@ -94,7 +84,7 @@ function setLinkDestination(
 		// Find the topmost link without a destination
 		for (let i = stack.length - 1; i >= 0; i--) {
 			if (stack[i].destination === null) {
-				stack[i].destination = { screenKey, parentScreenKey, bounds, styles };
+				stack[i].destination = { screenKey, ancestorKeys, bounds, styles };
 				break;
 			}
 		}
@@ -102,22 +92,53 @@ function setLinkDestination(
 	});
 }
 
-function getOccurrence(tag: TagID, key: ScreenKey) {
-	"worklet";
-	return registry.value[tag]?.occurrences[key] ?? null;
-}
-
-// Helper to check if a screen identifier matches a given key
+/**
+ * Helper to check if a screen identifier matches a given key.
+ * Checks both direct screenKey match and ancestor chain.
+ */
 function matchesScreenKey(
 	identifier: ScreenIdentifier | null | undefined,
 	key: ScreenKey,
 ): boolean {
 	"worklet";
 	if (!identifier) return false;
-	return identifier.screenKey === key || identifier.parentScreenKey === key;
+
+	// Direct match
+	if (identifier.screenKey === key) return true;
+
+	// Check ancestor chain
+	return identifier.ancestorKeys?.includes(key) ?? false;
+}
+
+/**
+ * Get snapshot by tag and optional key.
+ * If key is provided, supports ancestor matching - if the key matches any ancestor
+ * of a stored snapshot, that snapshot will be returned.
+ * If key is omitted, returns the most recently registered snapshot.
+ */
+function getSnapshot(tag: TagID, key: ScreenKey): Snapshot | null {
+	"worklet";
+	const tagState = registry.value[tag];
+	if (!tagState) return null;
+
+	// Direct match in occurrences
+	if (tagState.snapshots[key]) {
+		const snap = tagState.snapshots[key];
+		return { bounds: snap.bounds, styles: snap.styles };
+	}
+
+	// Ancestor match
+	for (const screenKey in tagState.snapshots) {
+		const snap = tagState.snapshots[screenKey];
+		if (snap.ancestorKeys?.includes(key)) {
+			return { bounds: snap.bounds, styles: snap.styles };
+		}
+	}
+
+	return null;
 }
 
-function getActiveLink(tag: TagID, screenKey?: ScreenKey, isClosing?: boolean) {
+function getActiveLink(tag: TagID, screenKey?: ScreenKey): TagLink | null {
 	"worklet";
 	const stack = registry.value[tag]?.linkStack;
 
@@ -127,40 +148,55 @@ function getActiveLink(tag: TagID, screenKey?: ScreenKey, isClosing?: boolean) {
 
 	// If screenKey provided, find link involving that screen
 	if (screenKey) {
-		// When closing (backward nav), we want the link where this screen is the DESTINATION
-		// When opening (forward nav), we want the link where this screen is the DESTINATION too
-		// The source is always the "from" screen, destination is the "to" screen
-
-		if (isClosing) {
-			// Backward: find link where I am the destination (I'm going back to source)
-			for (let i = stack.length - 1; i >= 0; i--) {
-				const link = stack[i];
-				if (matchesScreenKey(link.destination, screenKey)) {
-					return link;
-				}
-			}
-		}
-
-		// Forward or fallback: find any link involving this screen
 		for (let i = stack.length - 1; i >= 0; i--) {
 			const link = stack[i];
-			if (
-				matchesScreenKey(link.source, screenKey) ||
-				matchesScreenKey(link.destination, screenKey)
-			) {
+			if (!link.destination) continue;
+
+			const isSource = matchesScreenKey(link.source, screenKey);
+			const isDestination = matchesScreenKey(link.destination, screenKey);
+
+			if (isSource || isDestination) {
+				// If I match the source, I'm closing (going back to where I came from)
 				return link;
 			}
 		}
 		return null;
 	}
 
-	return stack[stack.length - 1] ?? null;
+	const lastLink = stack[stack.length - 1];
+	return lastLink ? lastLink : null;
+}
+
+/**
+ * Clear all snapshots and links for a screen across all tags.
+ * Called when a screen unmounts.
+ */
+function clear(screenKey: ScreenKey) {
+	"worklet";
+	registry.modify((state: Any) => {
+		"worklet";
+		for (const tag in state) {
+			// Remove snapshot
+			if (state[tag].snapshots[screenKey]) {
+				delete state[tag].snapshots[screenKey];
+			}
+
+			// Remove links involving this screen
+			state[tag].linkStack = state[tag].linkStack.filter((link: TagLink) => {
+				const sourceMatches = matchesScreenKey(link.source, screenKey);
+				const destMatches = matchesScreenKey(link.destination, screenKey);
+				return !sourceMatches && !destMatches;
+			});
+		}
+		return state;
+	});
 }
 
 export const BoundStore = {
-	registerOccurrence,
+	registerSnapshot,
 	setLinkSource,
 	setLinkDestination,
 	getActiveLink,
-	getOccurrence,
+	getSnapshot,
+	clear,
 };

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

@@ -1,5 +1,5 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
-import type { TagData } from "../stores/bounds.store";
+import type { Snapshot } from "../stores/bounds.store";
 import type {
 	BoundsBuilderOptions,
 	BoundsReturnType,
@@ -21,5 +21,5 @@ export type BoundEntry = {
 
 export type BoundsAccessor = {
 	<T extends BoundsBuilderOptions>(options: T): BoundsReturnType<T>;
-	getOccurrence: (id: string, key: string) => TagData;
+	getSnapshot: (id: string, key?: string) => Snapshot | null;
 };