react-native-screen-transitions 3.11.3 → 3.12.0

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

@@ -2,53 +2,160 @@ import {
 	NavigationContext,
 	NavigationRouteContext,
 } from "@react-navigation/native";
-import { memo, useMemo } from "react";
-import { Animated, StyleSheet, View } from "react-native";
-import { useDerivedValue } from "react-native-reanimated";
-import type { StackScene } from "../../../hooks/navigation/use-stack";
-import { useScreenAnimation } from "../../../providers/screen/animation";
-import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import { memo, useMemo, useRef } from "react";
+import { StyleSheet, View } from "react-native";
+import Animated, { useDerivedValue } from "react-native-reanimated";
+import { snapDescriptorToIndex } from "../../../animation/snap-to";
+import { useStack } from "../../../hooks/navigation/use-stack";
+import { useScreenAnimationStore } from "../../../providers/screen/animation";
+import type { ScreenAnimationContextValue } from "../../../providers/screen/animation/animation.provider";
+import {
+	type ScreenSlotContextValue,
+	useScreenSlots,
+} from "../../../providers/screen/styles/slot.provider";
+import type { OverlayProps } from "../../../types/overlay.types";
 import type {
-	OverlayProps,
-	OverlayScreenState,
-} from "../../../types/overlay.types";
+	FloatOverlayActivity,
+	FloatOverlayEntry,
+} from "../helpers/get-active-overlay";
+import {
+	type ReadyOverlayResources,
+	retainReadyOverlayResources,
+} from "../helpers/retain-ready-overlay-resources";
+import { useOverlaySlot } from "../hooks/use-overlay-slot";
 
 type OverlayHostProps = {
-	scene: StackScene;
-	overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]>;
+	scene: FloatOverlayEntry["scene"];
+	driverScene: FloatOverlayEntry["scene"];
+	previousOverlayScene?: FloatOverlayEntry["scene"];
+	activity: FloatOverlayActivity;
+	layerIndex: number;
 };
 
 export const OverlayHost = memo(function OverlayHost({
 	scene,
-	overlayScreenState,
+	driverScene,
+	previousOverlayScene,
+	activity,
+	layerIndex,
 }: OverlayHostProps) {
-	const OverlayComponent = scene.descriptor.options.overlay;
+	const overlayAnimationStore = useScreenAnimationStore(scene.route.key);
+	const driverAnimationStore = useScreenAnimationStore(driverScene.route.key);
+	const previousOverlayAnimationStore = useScreenAnimationStore(
+		previousOverlayScene?.route.key ?? scene.route.key,
+	);
+	const driverSlots = useScreenSlots(driverScene.route.key);
+	const overlayComponentRef = useRef(scene.descriptor.options.overlay);
+	const OverlayComponent = overlayComponentRef.current;
+	const readyResourcesRef = useRef<ReadyOverlayResources | null>(null);
+	readyResourcesRef.current = retainReadyOverlayResources(
+		readyResourcesRef.current,
+		overlayAnimationStore,
+		driverScene,
+		driverAnimationStore,
+		driverSlots,
+	);
+	const readyResources = readyResourcesRef.current;
+
+	if (!OverlayComponent || !readyResources) {
+		return null;
+	}
+
+	return (
+		<ReadyOverlayHost
+			scene={scene}
+			driverScene={readyResources.driverScene}
+			activity={activity}
+			layerIndex={layerIndex}
+			overlayAnimationStore={readyResources.overlayAnimationStore}
+			driverAnimationStore={readyResources.driverAnimationStore}
+			previousOverlayAnimationStore={
+				previousOverlayScene ? previousOverlayAnimationStore : undefined
+			}
+			driverSlots={readyResources.driverSlots}
+			OverlayComponent={OverlayComponent}
+		/>
+	);
+});
+
+type ReadyOverlayHostProps = OverlayHostProps & {
+	overlayAnimationStore: ScreenAnimationContextValue;
+	driverAnimationStore: ScreenAnimationContextValue;
+	previousOverlayAnimationStore?: ScreenAnimationContextValue | null;
+	driverSlots: ScreenSlotContextValue;
+	OverlayComponent: NonNullable<
+		FloatOverlayEntry["scene"]["descriptor"]["options"]["overlay"]
+	>;
+};
 
-	const screenAnimation = useScreenAnimation();
+function ReadyOverlayHost({
+	scene,
+	driverScene,
+	activity,
+	layerIndex,
+	overlayAnimationStore,
+	driverAnimationStore,
+	previousOverlayAnimationStore,
+	driverSlots,
+	OverlayComponent,
+}: ReadyOverlayHostProps) {
+	const { scenes, focusedIndex, routeKeys, routes } = useStack();
+	const descriptor = scene.descriptor;
+	const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
+	const focusedDescriptor = focusedScene?.descriptor;
+	const { animatedProps, animatedStyle } = useOverlaySlot({
+		overlayAnimationStore,
+		driverAnimationStore,
+		previousOverlayAnimationStore: previousOverlayAnimationStore ?? undefined,
+		driverInterpolator: driverScene.descriptor.options.screenStyleInterpolator,
+		interpolatorReady: driverSlots.interpolatorReady,
+		isIncoming: scene.route.key === driverScene.route.key,
+	});
 	const relativeProgress = useDerivedValue(() => {
 		"worklet";
-		return screenAnimation.get().stackProgress;
+		overlayAnimationStore.screenInterpolatorPropsRevision.get();
+		return overlayAnimationStore.screenInterpolatorProps.get().stackProgress;
 	});
 
-	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(
+	const overlayProps: OverlayProps = useMemo(
 		() => ({
-			...overlayScreenState,
+			route: scene.route,
+			index: routeKeys.indexOf(scene.route.key),
+			options: focusedDescriptor?.options ?? {},
+			routes,
+			focusedRoute: focusedScene?.route ?? scene.route,
+			focusedIndex,
+			meta: focusedDescriptor?.options?.meta,
+			navigation: scene.descriptor.navigation,
+			snapTo: (index: number) => {
+				snapDescriptorToIndex(scene.descriptor, index);
+			},
 			progress: relativeProgress,
 		}),
-		[relativeProgress, overlayScreenState],
+		[
+			scene,
+			focusedDescriptor?.options,
+			focusedIndex,
+			focusedScene?.route,
+			relativeProgress,
+			routeKeys,
+			routes,
+		],
 	);
-
-	if (!OverlayComponent) {
-		return null;
-	}
-
 	return (
 		<Animated.View
-			pointerEvents="box-none"
-			style={[styles.container, styles.floating, StyleSheet.absoluteFill]}
+			animatedProps={animatedProps}
+			pointerEvents={activity === "active" ? "box-none" : "none"}
+			style={[
+				styles.container,
+				styles.floating,
+				StyleSheet.absoluteFill,
+				{ zIndex: 1000 + layerIndex },
+				animatedStyle,
+			]}
 		>
-			<NavigationContext.Provider value={scene.descriptor.navigation as any}>
-				<NavigationRouteContext.Provider value={scene.route}>
+			<NavigationContext.Provider value={descriptor.navigation as any}>
+				<NavigationRouteContext.Provider value={descriptor.route}>
 					<View
 						pointerEvents="box-none"
 						style={[StyleSheet.absoluteFill, styles.overlay]}
@@ -59,7 +166,7 @@ export const OverlayHost = memo(function OverlayHost({
 			</NavigationContext.Provider>
 		</Animated.View>
 	);
-});
+}
 
 const styles = StyleSheet.create({
 	overlay: {

package/src/shared/components/screen-lifecycle/hooks/use-close-transition-intent.ts

@@ -105,8 +105,12 @@ export function useCloseTransitionIntent(current: BaseDescriptor): {
 
 	// biome-ignore lint/correctness/useExhaustiveDependencies: navigation listener should only rebind when the navigator instance changes
 	useLayoutEffect(() => {
+		if (stackType !== StackType.NATIVE) {
+			return;
+		}
+
 		return current.navigation.addListener?.("beforeRemove", handleBeforeRemove);
-	}, [current.navigation]);
+	}, [current.navigation, stackType]);
 
 	return { completeClose };
 }

package/src/shared/index.ts

@@ -71,6 +71,7 @@ export type {
 	BoundsNavigationZoomStyle,
 	GestureHandoffValues,
 	InactiveBehavior,
+	OverlayComponent,
 	OverlayProps,
 	RawGestureValues,
 	ScreenBackdropComponent,

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

@@ -2,6 +2,7 @@ import { type ReactNode, useCallback, useLayoutEffect, useMemo } from "react";
 import { useSharedValue } from "react-native-reanimated";
 import { createBoundsAccessor } from "../../../utils/bounds";
 import createProvider from "../../../utils/create-provider";
+import { useDescriptorsStore } from "../descriptors";
 import { useScreenAnimationPipeline } from "./helpers/pipeline";
 import type {
 	RegisterScreenAnimationDescendant,
@@ -25,25 +26,36 @@ export type ScreenAnimationContextValue = ReturnType<
 };
 
 export type ScreenAnimationContextResult = {
+	key: string;
 	value: ScreenAnimationContextValue;
 };
 
 export const { ScreenAnimationProvider, useScreenAnimationStore } =
 	createProvider("ScreenAnimation", {
 		guarded: true,
+		global: true,
 	})<Props, ScreenAnimationContextValue>(
 		(_props, { useParentStore }): ScreenAnimationContextResult => {
-			const parentContext = useParentStore();
-			const parentScreenInterpolatorProps =
-				parentContext?.screenInterpolatorProps;
-			const parentScreenInterpolatorPropsRevision =
-				parentContext?.screenInterpolatorPropsRevision;
-			const parentAncestorScreenAnimationSources =
-				parentContext?.ancestorScreenAnimationSources;
-			const parentRegisterDescendantScreenAnimationSource =
-				parentContext?.registerDescendantScreenAnimationSource;
-			const parentAncestorDescendantScreenAnimationRegistrars =
-				parentContext?.ancestorDescendantScreenAnimationRegistrars;
+			const currentScreenKey = useDescriptorsStore(
+				(store) => store.derivations.currentScreenKey,
+			);
+			const parentScreenInterpolatorProps = useParentStore(
+				(parentContext) => parentContext?.screenInterpolatorProps,
+			);
+			const parentScreenInterpolatorPropsRevision = useParentStore(
+				(parentContext) => parentContext?.screenInterpolatorPropsRevision,
+			);
+			const parentAncestorScreenAnimationSources = useParentStore(
+				(parentContext) => parentContext?.ancestorScreenAnimationSources,
+			);
+			const parentRegisterDescendantScreenAnimationSource = useParentStore(
+				(parentContext) =>
+					parentContext?.registerDescendantScreenAnimationSource,
+			);
+			const parentAncestorDescendantScreenAnimationRegistrars = useParentStore(
+				(parentContext) =>
+					parentContext?.ancestorDescendantScreenAnimationRegistrars,
+			);
 
 			const {
 				screenInterpolatorProps,
@@ -192,6 +204,7 @@ export const { ScreenAnimationProvider, useScreenAnimationStore } =
 			]);
 
 			return {
+				key: currentScreenKey,
 				value: {
 					screenInterpolatorProps,
 					screenInterpolatorPropsRevision,

package/src/shared/providers/screen/animation/helpers/accessors/use-build-transition-accessor.ts

@@ -4,7 +4,7 @@ import type {
 	ScreenTransitionTarget,
 } from "../../../../../types/animation.types";
 import { createBoundsAccessor } from "../../../../../utils/bounds";
-import { useScreenAnimationStore } from "../../animation.provider";
+import type { ScreenAnimationContextValue } from "../../animation.provider";
 import type {
 	ScreenAnimationDescendantSources,
 	ScreenAnimationSource,
@@ -15,6 +15,14 @@ type TransitionSourceIndex = number;
 
 export type TransitionAccessorSource = ScreenAnimationTransitionSource;
 
+type TransitionAccessorStore = Pick<
+	ScreenAnimationContextValue,
+	| "screenInterpolatorProps"
+	| "screenInterpolatorPropsRevision"
+	| "ancestorScreenAnimationSources"
+	| "descendantScreenAnimationSources"
+>;
+
 const resolveTargetIndex = (
 	target: ScreenTransitionTarget | undefined,
 	currentIndex: TransitionSourceIndex,
@@ -118,14 +126,12 @@ const buildSourceBoundsAccessor = (source: ScreenAnimationSource) => {
 	});
 };
 
-export const useBuildTransitionAccessor = () => {
-	const {
-		screenInterpolatorProps,
-		screenInterpolatorPropsRevision,
-		ancestorScreenAnimationSources,
-		descendantScreenAnimationSources,
-	} = useScreenAnimationStore();
-
+export const useBuildTransitionAccessor = ({
+	screenInterpolatorProps,
+	screenInterpolatorPropsRevision,
+	ancestorScreenAnimationSources,
+	descendantScreenAnimationSources,
+}: TransitionAccessorStore) => {
 	return useMemo(() => {
 		const selfSource = {
 			screenInterpolatorProps,

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

@@ -1,3 +1,4 @@
+import { useRoute } from "@react-navigation/native";
 import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
 import type {
 	ScreenInterpolationProps,
@@ -33,12 +34,21 @@ export function useScreenAnimation(
 ):
 	| DerivedValue<ScreenInterpolationProps>
 	| DerivedValue<ScreenInterpolationProps | null> {
+	const route = useRoute();
+	const screenAnimationStore = useScreenAnimationStore(route.key);
+
+	if (!screenAnimationStore) {
+		throw new Error(
+			`ScreenAnimation store for route "${route.key}" was not found`,
+		);
+	}
+
 	const {
 		screenInterpolatorPropsRevision,
 		ancestorScreenAnimationSources,
 		descendantScreenAnimationSources,
-	} = useScreenAnimationStore();
-	const transition = useBuildTransitionAccessor();
+	} = screenAnimationStore;
+	const transition = useBuildTransitionAccessor(screenAnimationStore);
 	const transitionTarget = normalizeScreenAnimationTarget(
 		target,
 		ancestorScreenAnimationSources.length,

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

@@ -1,11 +1,11 @@
-import { useMemo } from "react";
+import { Fragment, useMemo } from "react";
 import { Gesture } from "react-native-gesture-handler";
 import { useSharedValue } from "react-native-reanimated";
 import { ScrollStore } from "../../../stores/scroll.store";
 import createProvider from "../../../utils/create-provider";
 import { useDescriptorsStore } from "../descriptors";
 import { useScreenGestureConfig } from "./hooks/use-screen-gesture-config";
-import { useWalkUpAndRegisterShadowingClaims } from "./ownership/use-walk-up-and-register-shadowing-claims";
+import { GestureOwnershipBridge } from "./ownership/gesture-ownership-bridge";
 import { useBuildPanGesture } from "./pan/use-build-pan-gesture";
 import { useBuildPinchGesture } from "./pinch/use-build-pinch-gesture";
 import {
@@ -28,11 +28,16 @@ export const { ScreenGestureProvider, useScreenGestureStore: useGestureStore } =
 			{ children },
 			{ useParentStore },
 		): { value: GestureContextType; children: React.ReactNode } => {
-			const gestureContext = useParentStore();
-			const gestureConfig = useScreenGestureConfig();
 			const currentScreenKey = useDescriptorsStore(
 				(store) => store.derivations.currentScreenKey,
 			);
+			const isTopMostScreen = useDescriptorsStore(
+				(store) => store.derivations.isTopMostScreen,
+			);
+			const gestureContext = useParentStore((parentContext) =>
+				isTopMostScreen ? parentContext : null,
+			);
+			const gestureConfig = useScreenGestureConfig(gestureContext);
 
 			const scrollState = ScrollStore.getValue(
 				currentScreenKey,
@@ -89,13 +94,19 @@ export const { ScreenGestureProvider, useScreenGestureStore: useGestureStore } =
 				],
 			);
 
-			useWalkUpAndRegisterShadowingClaims(
-				gestureConfig.participation.claimedDirections,
+			const content = useMemo(
+				() => (
+					<Fragment>
+						<GestureOwnershipBridge />
+						{children}
+					</Fragment>
+				),
+				[children],
 			);
 
 			return {
 				value,
-				children,
+				children: content,
 			};
 		},
 	);

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

@@ -1,12 +1,12 @@
 import { usePreventRemoveContext } from "@react-navigation/native";
 import { useMemo } from "react";
 import { useDescriptorsStore } from "../../descriptors";
-import { useGestureStore } from "../gestures.provider";
 import { resolveScreenGestureConfig } from "../shared/policy";
-import type { ScreenGestureConfig } from "../types";
+import type { GestureContextType, ScreenGestureConfig } from "../types";
 
-export function useScreenGestureConfig(): ScreenGestureConfig {
-	const gestureContext = useGestureStore();
+export function useScreenGestureConfig(
+	gestureContext: GestureContextType | null,
+): ScreenGestureConfig {
 	const options = useDescriptorsStore((store) => store.options);
 	const isFirstKey = useDescriptorsStore(
 		(store) => store.derivations.isFirstKey,

package/src/shared/providers/screen/gestures/ownership/{use-walk-up-and-register-shadowing-claims.ts → gesture-ownership-bridge.tsx}

@@ -30,9 +30,9 @@ const findShadowedDirections = (
 ) => {
 	const shadowedDirections: Direction[] = [];
 
-	for (const dir of DIRECTIONS) {
-		if (claimedDirections[dir] && ancestorDirections[dir]) {
-			shadowedDirections.push(dir);
+	for (const direction of DIRECTIONS) {
+		if (claimedDirections[direction] && ancestorDirections[direction]) {
+			shadowedDirections.push(direction);
 		}
 	}
 
@@ -70,8 +70,8 @@ const registerShadowingClaims = (
 
 	for (const { ancestor, directions } of shadowedAncestors) {
 		const newClaims = { ...ancestor.childDirectionClaims.get() };
-		for (const dir of directions) {
-			newClaims[dir] = { routeKey: currentScreenKey, isDismissing };
+		for (const direction of directions) {
+			newClaims[direction] = { routeKey: currentScreenKey, isDismissing };
 		}
 		ancestor.childDirectionClaims.set(newClaims);
 	}
@@ -86,10 +86,9 @@ const clearShadowingClaims = (
 		const newClaims = { ...currentClaims };
 		let needsUpdate = false;
 
-		for (const dir of directions) {
-			// Only remove claims written by this screen; a newer descendant may own it now.
-			if (currentClaims[dir]?.routeKey === currentScreenKey) {
-				newClaims[dir] = null;
+		for (const direction of directions) {
+			if (currentClaims[direction]?.routeKey === currentScreenKey) {
+				newClaims[direction] = null;
 				needsUpdate = true;
 			}
 		}
@@ -121,51 +120,32 @@ const getDescriptorClaimedDirections = (
 	}).participation.claimedDirections;
 };
 
-/**
- * Registers this screen with ancestors that claim the same direction.
- *
- * Example, when C is top-most:
- * A claims vertical
- * └─ B claims horizontal
- *    └─ C claims vertical
- *
- * C walks up the tree and writes itself into A.childDirectionClaims.vertical.
- * B is skipped because it does not claim vertical.
- */
-export function useWalkUpAndRegisterShadowingClaims(
-	claimedDirections: ClaimedDirections,
-): void {
-	const parentContext = useGestureStore();
+const requireGestureContext = (
+	gestureContext: GestureContextType | null,
+): GestureContextType => {
+	if (!gestureContext) {
+		throw new Error(
+			"GestureOwnershipBridge must be rendered within a ScreenGestureProvider",
+		);
+	}
+
+	return gestureContext;
+};
+
+function ActiveGestureOwnershipBridge() {
+	const gestureContext = requireGestureContext(useGestureStore());
 	const previous = useDescriptorsStore((store) => store.previous);
-	const isTopMostScreen = useDescriptorsStore(
-		(store) => store.derivations.isTopMostScreen,
-	);
-	const currentScreenKey = useDescriptorsStore(
-		(store) => store.derivations.currentScreenKey,
-	);
 	const isCurrentScreenClosing = useBlankStackStore(
-		(store) => store?.scenesByKey[currentScreenKey]?.activity === "closing",
+		(store) =>
+			store?.scenesByKey[gestureContext.routeKey]?.activity === "closing",
 	);
-
-	/*
-	 * We want to calculate effective claimed directions as claimedDirections is not enough for us.
-	 * What this solves is lingering claimed directions when a screen is closing.
-	 *
-	 * Overlay claims horizontal
-	 *   └─ A has no local horizontal claim
-	 *   └─ B claims horizontal (closing)
-	 *   └─ C claims horizontal (closing)
-	 *
-	 * Closing screens are still mounted, so they can still block parent gestures.
-	 * But they cannot receive touches anymore.
-	 *
-	 * So when B/C are closing and the user is really touching A, B/C should not
-	 * keep blocking the parent with their own gesture config.
-	 *
-	 * A closing screen should act like the visible screen underneath it:
-	 * - if the screen underneath claims the gesture, keep blocking the parent
-	 * - if the screen underneath does not claim it, let the parent handle it
-	 */
+	const {
+		claimedDirections,
+		gestureContext: parentContext,
+		routeKey: currentScreenKey,
+	} = gestureContext;
+	// A retained closing screen cannot receive touches, so its ownership must
+	// mirror the visible screen underneath instead of blocking an ancestor.
 	const effectiveClaimedDirections = useMemo(
 		() =>
 			resolveShadowingClaimDirections({
@@ -178,14 +158,13 @@ export function useWalkUpAndRegisterShadowingClaims(
 			}),
 		[isCurrentScreenClosing, claimedDirections, previous, parentContext],
 	);
-
 	const shadowedAncestors = useMemo(
 		() => findShadowedAncestors(parentContext, effectiveClaimedDirections),
 		[parentContext, effectiveClaimedDirections],
 	);
 
 	useLayoutEffect(() => {
-		if (!isTopMostScreen || !shadowedAncestors.length) {
+		if (!shadowedAncestors.length) {
 			return;
 		}
 
@@ -194,5 +173,16 @@ export function useWalkUpAndRegisterShadowingClaims(
 		return () => {
 			clearShadowingClaims(shadowedAncestors, currentScreenKey);
 		};
-	}, [shadowedAncestors, currentScreenKey, isTopMostScreen]);
+	}, [shadowedAncestors, currentScreenKey]);
+
+	return null;
+}
+
+/** Keeps gesture ownership subscriptions attached only to participating screens. */
+export function GestureOwnershipBridge() {
+	const isTopMostScreen = useDescriptorsStore(
+		(store) => store.derivations.isTopMostScreen,
+	);
+
+	return isTopMostScreen ? <ActiveGestureOwnershipBridge /> : null;
 }

package/src/shared/providers/screen/styles/constants.ts

@@ -65,6 +65,7 @@ export const PROP_RESET_VALUES: Record<string, unknown> = {
 };
 
 const RESERVED_STYLE_SLOT_IDS = {
+	overlay: true,
 	content: true,
 	backdrop: true,
 	surface: true,

package/src/shared/providers/screen/styles/helpers/transition-visual-state.ts

@@ -42,3 +42,29 @@ export const hasCloseTransitionFinished = ({
 	"worklet";
 	return !!closing && animationProgress === 0;
 };
+
+export const isScreenInterpolatorReady = ({
+	hasInterpolator,
+	opening,
+	closing,
+	pendingLifecycleStartBlockCount,
+	animationProgress,
+}: {
+	hasInterpolator: boolean;
+	opening: boolean;
+	closing: number;
+	pendingLifecycleStartBlockCount: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+
+	return (
+		hasInterpolator &&
+		!isOpenTransitionBlocked({
+			opening,
+			pendingLifecycleStartBlockCount,
+			animationProgress,
+		}) &&
+		!hasCloseTransitionFinished({ closing, animationProgress })
+	);
+};