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

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,85 @@ 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";
+
+		//.some doesnt work here apparently... :-(
+		for (const closing of ancestorClosing) {
+			if (closing.get()) 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 +184,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 +200,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 +219,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 +236,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 +268,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 						currentScreenKey,
 						measured,
 						preparedStyles,
-						parentScreenKey,
+						ancestorKeys,
 					);
 				}
 
@@ -248,7 +279,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 						currentScreenKey,
 						measured,
 						preparedStyles,
-						parentScreenKey,
+						ancestorKeys,
 					);
 				}
 
@@ -259,7 +290,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 		const handleInitialLayout = useInitialLayoutHandler({
 			sharedBoundTag,
 			currentScreenKey,
-			parentScreenKey,
+			ancestorKeys,
 			maybeMeasureAndStore,
 		});
 
@@ -267,6 +298,7 @@ const { RegisterBoundsProvider, useRegisterBoundsContext } = createProvider(
 		const { markSourceCaptured } = useBlurMeasurement({
 			sharedBoundTag,
 			maybeMeasureAndStore,
+			ancestorKeys,
 		});
 
 		useParentSyncReaction({ parentContext, maybeMeasureAndStore });

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

@@ -0,0 +1,54 @@
+import { useMemo } from "react";
+import {
+	AnimationStore,
+	type AnimationStoreMap,
+} from "../stores/animation.store";
+import createProvider from "../utils/create-provider";
+
+interface RoutesProviderProps {
+	children: React.ReactNode;
+	routeKeys: string[];
+}
+
+interface RoutesContextValue {
+	/**
+	 * Array of route keys for all routes in the stack, in order.
+	 */
+	routeKeys: string[];
+}
+
+const { RoutesProvider, useRoutesContext } = createProvider("Routes", {
+	guarded: false,
+})<RoutesProviderProps, RoutesContextValue>(({ routeKeys }) => ({
+	value: { routeKeys },
+}));
+
+export { RoutesProvider, useRoutesContext };
+
+/**
+ * Hook to get animation values for all screens from a given index onwards.
+ * Useful for computing accumulated progress across multiple screens.
+ */
+export function useStackAnimationValues(
+	currentRouteKey: string | undefined,
+): AnimationStoreMap[] {
+	const routesContext = useRoutesContext();
+
+	return useMemo(() => {
+		if (!currentRouteKey || !routesContext) {
+			return [];
+		}
+
+		const { routeKeys } = routesContext;
+		const currentIndex = routeKeys.indexOf(currentRouteKey);
+
+		if (currentIndex === -1) {
+			return [];
+		}
+
+		// Get animation values for all screens from current index onwards
+		return routeKeys
+			.slice(currentIndex)
+			.map((key) => AnimationStore.getAll(key));
+	}, [currentRouteKey, routesContext]);
+}

package/src/shared/providers/screen-transition.provider.tsx

@@ -1,7 +1,7 @@
 import type React from "react";
 import type { ComponentType } from "react";
-import type { ScreenLifecycleProps } from "../components/controllers/screen-lifecycle";
 import { RootTransitionAware } from "../components/root-transition-aware";
+import type { Any } from "../types/utils.types";
 import { ScreenGestureProvider } from "./gestures.provider";
 import { KeysProvider, type TransitionDescriptor } from "./keys.provider";
 import { TransitionStylesProvider } from "./transition-styles.provider";
@@ -11,7 +11,7 @@ type Props<TDescriptor extends TransitionDescriptor> = {
 	current: TDescriptor;
 	next?: TDescriptor;
 	children: React.ReactNode;
-	LifecycleController: ComponentType<ScreenLifecycleProps>;
+	LifecycleController: ComponentType<Any>;
 };
 
 export function ScreenTransitionProvider<

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/animation.types.ts

@@ -75,6 +75,19 @@ export interface ScreenInterpolationProps {
 	 */
 	progress: number;
 
+	/**
+	 * Accumulated progress from the current screen's position onwards in the stack.
+	 * Unlike `progress` (0-2), this ranges from 0-N where N is the number of screens
+	 * above the current screen. Each screen at index I sees stackProgress as the
+	 * sum of all progress values from index I to the top of the stack.
+	 *
+	 * Example: With 4 screens pushed, screen at index 1 would see stackProgress = 3
+	 * when all screens are fully transitioned.
+	 *
+	 * Falls back to `progress` when not in blank-stack.
+	 */
+	stackProgress: number;
+
 	/**
 	 * Function that provides access to bounds builders for creating shared element transitions.
 	 */

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;
 };

package/src/shared/types/state.types.ts

@@ -0,0 +1,2 @@
+export const TRUE = 1;
+export const FALSE = 0;

package/src/shared/utils/animation/compute-stack-progress.ts

@@ -0,0 +1,16 @@
+import type { AnimationStoreMap } from "../../stores/animation.store";
+
+export const computeStackProgress = (
+	stackAnimationValues: AnimationStoreMap[],
+	fallback: number = 0,
+) => {
+	"worklet";
+	let computedStackProgress: number | undefined;
+	if (stackAnimationValues.length > 0) {
+		computedStackProgress = 0;
+		for (let i = 0; i < stackAnimationValues.length; i += 1) {
+			computedStackProgress += stackAnimationValues[i].progress.value;
+		}
+	}
+	return computedStackProgress ?? fallback;
+};

package/src/shared/utils/animation/derivations.ts

@@ -11,7 +11,7 @@ interface DerivationsParams {
 export const derivations = ({ current, next }: DerivationsParams) => {
 	"worklet";
 
-	// The combined progress
+	// The combined progress (current + next, 0-2 range)
 	const progress = current.progress + (next?.progress ?? 0);
 
 	// Whether the current screen is focused