react-native-screen-transitions 3.11.2 → 3.12.0

package/src/shared/components/boundary/providers/boundary-root.provider.tsx

@@ -8,7 +8,7 @@ import {
 } from "react";
 import type { View } from "react-native";
 import type { AnimatedRef } from "react-native-reanimated";
-import { useAnimatedRef } from "react-native-reanimated";
+import { useAnimatedRef, useSharedValue } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../providers/screen/descriptors";
 import {
 	useComposedSlotStyles,
@@ -19,7 +19,7 @@ import { createBoundTag } from "../../../stores/bounds/helpers/link-pairs.helper
 import type { BoundTag } from "../../../stores/bounds/types";
 import createProvider from "../../../utils/create-provider";
 import { logger } from "../../../utils/logger";
-import { useBoundaryMeasurement } from "../hooks/use-boundary-measurement";
+import { BoundaryLifecycle } from "../components/boundary-lifecycle";
 import {
 	type BoundaryPortalRuntime,
 	resolveBoundaryPortal,
@@ -27,6 +27,8 @@ import {
 import type {
 	BoundaryConfigProps,
 	BoundaryId,
+	BoundaryLocalMeasurement,
+	BoundaryLocalMeasurementValue,
 	BoundaryOwnProps,
 } from "../types";
 
@@ -44,6 +46,7 @@ export type BoundaryRootRenderState = {
 	boundTag: BoundTag;
 	currentScreenKey: string;
 	handoffEnabled: boolean;
+	localMeasurement: BoundaryLocalMeasurementValue;
 	measurementRef: AnimatedRef<View>;
 	portalRuntime: BoundaryPortalRuntime;
 	ref: AnimatedRef<View>;
@@ -96,7 +99,9 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 			(s) => s.derivations.currentScreenKey,
 		);
 		const isCurrentScreenClosing = useBlankStackStore(
-			(store) => store?.scenesByKey[currentScreenKey]?.activity === "closing",
+			(store) =>
+				portalRuntime.handoff &&
+				store?.scenesByKey[currentScreenKey]?.activity === "closing",
 		);
 		const retainedBoundTagRef = useRef(requestedBoundTag);
 		const shouldRetainClosingBoundTag =
@@ -110,10 +115,6 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 		}
 
 		const boundTag = retainedBoundTagRef.current;
-		const hasConfiguredInterpolator = useDescriptorsStore(
-			(s) => s.derivations.hasConfiguredInterpolator,
-		);
-		const runtimeEnabled = enabled && hasConfiguredInterpolator;
 		// Associated slot styles attach whenever the boundary is enabled,
 		// independent of whether an interpolator is configured for this transition.
 		const shouldAttachAssociatedStyles = enabled;
@@ -123,6 +124,9 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
 		const rootRef = useAnimatedRef<View>();
 		const measurementRef = useAnimatedRef<View>();
+		const localMeasurement = useSharedValue<BoundaryLocalMeasurement | null>(
+			null,
+		);
 
 		useLayoutEffect(() => {
 			if (__DEV__ && targetCount > 1) {
@@ -137,18 +141,6 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 
 		useImperativeHandle(forwardedRef, () => rootRef.current as any, [rootRef]);
 
-		useBoundaryMeasurement({
-			boundTag,
-			enabled,
-			runtimeEnabled,
-			currentScreenKey,
-			measuredRef,
-			style: hasTarget ? targetStyle : style,
-			handoff: portalRuntime.handoff,
-			escapeClipping: portalRuntime.escapeClipping,
-			config,
-		});
-
 		const shouldRenderBoundaryRootThroughPortal =
 			shouldEscapeBoundaryRootToScreenHost && !hasTarget;
 		const handoffEnabled = enabled && portalRuntime.handoff;
@@ -173,6 +165,7 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 				boundTag,
 				currentScreenKey,
 				handoffEnabled,
+				localMeasurement,
 				measurementRef,
 				portalRuntime,
 				ref: rootRef,
@@ -185,6 +178,7 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 				currentScreenKey,
 				handoffEnabled,
 				hasTarget,
+				localMeasurement,
 				measurementRef,
 				portalRuntime,
 				rootRef,
@@ -194,7 +188,22 @@ export const { BoundaryRootProvider, useBoundaryRootStore } = createProvider(
 
 		return {
 			value,
-			children: children(value),
+			children: (
+				<>
+					{children(value)}
+					<BoundaryLifecycle
+						boundTag={boundTag}
+						config={config}
+						currentScreenKey={currentScreenKey}
+						enabled={enabled}
+						escapeClipping={portalRuntime.escapeClipping}
+						handoff={portalRuntime.handoff}
+						localMeasurement={localMeasurement}
+						measuredRef={measuredRef}
+						style={hasTarget ? targetStyle : style}
+					/>
+				</>
+			),
 		};
 	},
 );

package/src/shared/components/boundary/types.ts

@@ -1,3 +1,4 @@
+import type { MeasuredDimensions, SharedValue } from "react-native-reanimated";
 import type { ScreenPairKey } from "../../stores/bounds/types";
 import type { BoundsOptions } from "../../utils/bounds/types/options";
 
@@ -60,3 +61,11 @@ export type MeasureTarget =
 	  };
 
 export type MeasureBoundary = (target: MeasureTarget) => void;
+
+export type BoundaryLocalMeasurement = {
+	bounds: MeasuredDimensions;
+	pairKey: ScreenPairKey;
+};
+
+export type BoundaryLocalMeasurementValue =
+	SharedValue<BoundaryLocalMeasurement | null>;

package/src/shared/components/boundary/utils/refresh-signals.ts

@@ -34,6 +34,7 @@ export const getRefreshBoundarySignal = (params: {
 	linkId: string;
 	group?: string;
 	shouldRefresh: boolean;
+	settled?: boolean;
 	closing: boolean;
 	linkState?: LinkPairsState;
 }): RefreshBoundarySignal | null => {
@@ -46,13 +47,14 @@ export const getRefreshBoundarySignal = (params: {
 		linkId,
 		group,
 		shouldRefresh,
+		settled = false,
 		closing,
 		linkState,
 	} = params;
 
 	if (!enabled) return null;
 
-	if (!shouldRefresh) {
+	if (!shouldRefresh && (!group || !settled)) {
 		return null;
 	}
 
@@ -95,16 +97,33 @@ export const getRefreshBoundarySignal = (params: {
 	// Source side:
 	// When the activeId changes, trigger a refresh to ensure the source bounds are captured.
 	if (sourcePairKey) {
-		const activeId = linkState?.[sourcePairKey]?.groups?.[group]?.activeId;
+		const pair = linkState?.[sourcePairKey];
+		const groupState = pair?.groups?.[group];
+		const activeId = groupState?.activeId;
 
 		if (activeId !== linkId) {
 			return null;
 		}
 
+		// The opening member is captured by the initial handshake. A settled
+		// refresh is only needed after selection moves to another member.
+		if (
+			!shouldRefresh &&
+			(groupState?.initialId === undefined ||
+				activeId === groupState.initialId ||
+				!!pair?.links?.[linkId]?.source)
+		) {
+			return null;
+		}
+
 		return buildRefreshSignal(
 			"source",
 			sourcePairKey,
-			[group, linkId, closing ? "closing" : "settled"].join("|"),
+			[
+				group,
+				linkId,
+				shouldRefresh ? (closing ? "closing" : "settled") : "retarget",
+			].join("|"),
 		);
 	}
 
@@ -114,8 +133,9 @@ export const getRefreshBoundarySignal = (params: {
 
 	// Destination side:
 	// When the activeId changes, trigger a refresh to ensure the destination bounds are captured.
-	const activeId =
-		linkState?.[refreshDestinationPairKey]?.groups?.[group]?.activeId;
+	const pair = linkState?.[refreshDestinationPairKey];
+	const groupState = pair?.groups?.[group];
+	const activeId = groupState?.activeId;
 
 	// Destination retargeting should only measure a concrete member that already
 	// participates in the pair. Missing members fall back to initialId at resolve.
@@ -123,9 +143,22 @@ export const getRefreshBoundarySignal = (params: {
 		return null;
 	}
 
+	if (
+		!shouldRefresh &&
+		(groupState?.initialId === undefined ||
+			activeId === groupState.initialId ||
+			!!pair?.links?.[linkId]?.destination)
+	) {
+		return null;
+	}
+
 	return buildRefreshSignal(
 		"destination",
 		refreshDestinationPairKey,
-		[group, linkId, closing ? "closing" : "settled"].join("|"),
+		[
+			group,
+			linkId,
+			shouldRefresh ? (closing ? "closing" : "settled") : "retarget",
+		].join("|"),
 	);
 };

package/src/shared/components/overlay/helpers/create-overlay-interpolator-frame.ts

@@ -0,0 +1,29 @@
+import { updateDerivations } from "../../../providers/screen/animation/helpers/derivations";
+import type { ScreenInterpolatorFrame } from "../../../providers/screen/animation/helpers/pipeline";
+
+export const createOverlayInterpolatorFrame = ({
+	overlayFrame,
+	driverFrame,
+	previousOverlayFrame,
+}: {
+	overlayFrame: ScreenInterpolatorFrame;
+	driverFrame: ScreenInterpolatorFrame;
+	previousOverlayFrame?: ScreenInterpolatorFrame;
+}): ScreenInterpolatorFrame => {
+	"worklet";
+	const current = overlayFrame.current;
+	const driverIsCurrent = driverFrame.current.route.key === current.route.key;
+	const frame: ScreenInterpolatorFrame = {
+		...overlayFrame,
+		previous: previousOverlayFrame?.current,
+		current,
+		next: driverIsCurrent ? undefined : driverFrame.current,
+		layouts: current.layouts,
+	};
+
+	updateDerivations(frame);
+	frame.stackProgress = frame.progress;
+	frame.logicallySettled = frame.active.settled;
+
+	return frame;
+};

package/src/shared/components/overlay/helpers/get-active-overlay.ts

@@ -1,39 +1,81 @@
 import type { StackScene } from "../../../hooks/navigation/use-stack";
 import { isOverlayVisible } from "../../../utils/overlay/visibility";
 
+export type FloatOverlayActivity = "active" | "inert" | "inactive" | "closing";
+
+export type FloatOverlayEntry = {
+	scene: StackScene;
+	overlayIndex: number;
+	activity: FloatOverlayActivity;
+};
+
+export type FloatOverlayTransitionEntry = FloatOverlayEntry & {
+	driverScene: StackScene;
+};
+
+type OverlayCandidate = Omit<FloatOverlayEntry, "activity">;
+
+const resolveOverlayActivity = (
+	scene: StackScene,
+	distanceFromTop: number,
+): FloatOverlayActivity => {
+	if (distanceFromTop === 0 && scene.activity === "closing") {
+		return "closing";
+	}
+
+	if (distanceFromTop === 0) {
+		return "active";
+	}
+
+	if (distanceFromTop === 1) {
+		return "inert";
+	}
+
+	return "inactive";
+};
+
 /**
- * Find the active float overlay from scenes.
- * Scans from the top of the stack downward to find the first screen
- * with a visible overlay.
+ * Finds every visible floating-overlay checkpoint in stack order.
+ *
+ * The newest checkpoint owns the active overlay. Its immediate predecessor
+ * remains visible and inert; all older checkpoints are retained but inactive.
+ * This mirrors the screen activity window without making plain screens create
+ * a new overlay checkpoint.
  */
-export function getActiveFloatOverlay(
+export function getFloatOverlayStack(
 	scenes: StackScene[],
-	index: number,
 	transitionsAlwaysOn: boolean,
-): { scene: StackScene; overlayIndex: number } | null {
-	if (scenes.length === 0) {
-		return null;
-	}
-
-	// When navigating back, closing scenes are kept at the top of the local stack
-	// while the focused index already points to the destination screen. We need to
-	// start scanning from the actual top of the stack so the overlay can animate
-	// out together with its closing screen instead of disappearing immediately.
-	const startIndex = Math.max(index, scenes.length - 1);
+): FloatOverlayEntry[] {
+	const candidates: OverlayCandidate[] = [];
 
-	for (let i = startIndex; i >= 0; i--) {
-		const scene = scenes[i];
+	for (let index = 0; index < scenes.length; index += 1) {
+		const scene = scenes[index];
 		const options = scene?.descriptor?.options;
 
-		// Skip screens without enableTransitions (native-stack only)
 		if (!transitionsAlwaysOn && !options?.enableTransitions) {
 			continue;
 		}
 
 		if (isOverlayVisible(options)) {
-			return { scene, overlayIndex: i };
+			candidates.push({ scene, overlayIndex: index });
 		}
 	}
 
-	return null;
+	const topIndex = candidates.length - 1;
+	return candidates.map((candidate, index) => ({
+		...candidate,
+		activity: resolveOverlayActivity(candidate.scene, topIndex - index),
+	}));
+}
+
+export function getFloatOverlayTransitions(
+	overlayStack: FloatOverlayEntry[],
+	scenes: StackScene[],
+): FloatOverlayTransitionEntry[] {
+	const topScene = scenes[scenes.length - 1];
+
+	return overlayStack.map((entry, index) => ({
+		...entry,
+		driverScene: overlayStack[index + 1]?.scene ?? topScene ?? entry.scene,
+	}));
 }

package/src/shared/components/overlay/helpers/retain-ready-overlay-resources.ts

@@ -0,0 +1,38 @@
+import type { ScreenAnimationContextValue } from "../../../providers/screen/animation/animation.provider";
+import type { ScreenSlotContextValue } from "../../../providers/screen/styles/slot.provider";
+import type { FloatOverlayEntry } from "./get-active-overlay";
+
+export type ReadyOverlayResources = {
+	overlayAnimationStore: ScreenAnimationContextValue;
+	driverScene: FloatOverlayEntry["scene"];
+	driverAnimationStore: ScreenAnimationContextValue;
+	driverSlots: ScreenSlotContextValue;
+};
+
+export function retainReadyOverlayResources(
+	previous: ReadyOverlayResources | null,
+	overlayAnimationStore: ScreenAnimationContextValue | null,
+	driverScene: FloatOverlayEntry["scene"],
+	driverAnimationStore: ScreenAnimationContextValue | null,
+	driverSlots: ScreenSlotContextValue | null,
+): ReadyOverlayResources | null {
+	if (!overlayAnimationStore || !driverAnimationStore || !driverSlots) {
+		return previous;
+	}
+
+	if (
+		previous?.overlayAnimationStore === overlayAnimationStore &&
+		previous.driverScene === driverScene &&
+		previous.driverAnimationStore === driverAnimationStore &&
+		previous.driverSlots === driverSlots
+	) {
+		return previous;
+	}
+
+	return {
+		overlayAnimationStore,
+		driverScene,
+		driverAnimationStore,
+		driverSlots,
+	};
+}

package/src/shared/components/overlay/helpers/run-overlay-slot-interpolator.ts

@@ -0,0 +1,48 @@
+import type { ScreenInterpolatorFrame } from "../../../providers/screen/animation/helpers/pipeline";
+import { createInterpolatorScope } from "../../../providers/screen/styles/helpers/create-interpolator-scope";
+import { normalizeSlots } from "../../../providers/screen/styles/helpers/normalize-slots";
+import { selectInterpolatorFrame } from "../../../providers/screen/styles/helpers/select-interpolator-frame";
+import type {
+	NormalizedTransitionSlotStyle,
+	ScreenStyleInterpolator,
+	ScreenTransitionAccessor,
+} from "../../../types/animation.types";
+import { logger } from "../../../utils/logger";
+
+export const runOverlaySlotInterpolator = ({
+	frame,
+	interpolator,
+	transition,
+}: {
+	frame: ScreenInterpolatorFrame;
+	interpolator: ScreenStyleInterpolator | undefined;
+	transition: ScreenTransitionAccessor;
+}): NormalizedTransitionSlotStyle | undefined => {
+	"worklet";
+
+	if (!interpolator) {
+		return undefined;
+	}
+
+	try {
+		const raw = interpolator(
+			createInterpolatorScope({
+				frame,
+				selectedFrame: selectInterpolatorFrame(frame, false),
+				transition,
+			}),
+		);
+
+		if (!raw?.overlay) {
+			return undefined;
+		}
+
+		return normalizeSlots({ overlay: raw.overlay }).overlay;
+	} catch (_) {
+		if (__DEV__) {
+			logger.warn("screenStyleInterpolator must be a worklet");
+		}
+
+		return undefined;
+	}
+};

package/src/shared/components/overlay/hooks/use-overlay-slot.ts

@@ -0,0 +1,103 @@
+import { useMemo } from "react";
+import { useWindowDimensions } from "react-native";
+import {
+	type SharedValue,
+	useAnimatedProps,
+	useAnimatedStyle,
+	useDerivedValue,
+} from "react-native-reanimated";
+import { NO_PROPS, NO_STYLES } from "../../../constants";
+import type { ScreenAnimationContextValue } from "../../../providers/screen/animation/animation.provider";
+import { useBuildTransitionAccessor } from "../../../providers/screen/animation/helpers/accessors/use-build-transition-accessor";
+import { collectInterpolatorSharedValues } from "../../../providers/screen/styles/helpers/collect-interpolator-shared-values";
+import type {
+	NormalizedTransitionSlotStyle,
+	ScreenStyleInterpolator,
+} from "../../../types/animation.types";
+import { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
+import { createOverlayInterpolatorFrame } from "../helpers/create-overlay-interpolator-frame";
+import { runOverlaySlotInterpolator } from "../helpers/run-overlay-slot-interpolator";
+
+export const useOverlaySlot = ({
+	overlayAnimationStore,
+	driverAnimationStore,
+	previousOverlayAnimationStore,
+	driverInterpolator,
+	interpolatorReady,
+	isIncoming,
+}: {
+	overlayAnimationStore: ScreenAnimationContextValue;
+	driverAnimationStore: ScreenAnimationContextValue;
+	previousOverlayAnimationStore?: ScreenAnimationContextValue;
+	driverInterpolator: ScreenStyleInterpolator | undefined;
+	interpolatorReady: SharedValue<number>;
+	isIncoming: boolean;
+}) => {
+	const { height } = useWindowDimensions();
+	const transition = useBuildTransitionAccessor(driverAnimationStore);
+
+	const interpolatorSharedValues = useMemo(
+		() => collectInterpolatorSharedValues([driverInterpolator]),
+		[driverInterpolator],
+	);
+
+	const overlaySlot = useDerivedValue<
+		NormalizedTransitionSlotStyle | undefined
+	>(() => {
+		"worklet";
+		overlayAnimationStore.screenInterpolatorPropsRevision.get();
+		driverAnimationStore.screenInterpolatorPropsRevision.get();
+		previousOverlayAnimationStore?.screenInterpolatorPropsRevision.get();
+
+		for (let index = 0; index < interpolatorSharedValues.length; index++) {
+			interpolatorSharedValues[index]?.get();
+		}
+
+		const frame = createOverlayInterpolatorFrame({
+			overlayFrame: overlayAnimationStore.screenInterpolatorProps.get(),
+			driverFrame: driverAnimationStore.screenInterpolatorProps.get(),
+			previousOverlayFrame:
+				previousOverlayAnimationStore?.screenInterpolatorProps.get(),
+		});
+
+		return runOverlaySlotInterpolator({
+			frame,
+			interpolator: driverInterpolator,
+			transition,
+		});
+	});
+
+	const animatedStyle = useAnimatedStyle(() => {
+		"worklet";
+		const slot = overlaySlot.get();
+		if (!slot) {
+			return NO_STYLES;
+		}
+
+		if (isIncoming && !interpolatorReady.get()) {
+			return {
+				transform: [{ translateY: getVisibilityBlockOffset(height) }],
+			};
+		}
+
+		return slot.style ?? NO_STYLES;
+	});
+
+	const animatedProps = useAnimatedProps(() => {
+		"worklet";
+		const slotProps = overlaySlot.get()?.props;
+		if (!slotProps) {
+			return NO_PROPS;
+		}
+
+		const {
+			pointerEvents: _pointerEvents,
+			teleport: _teleport,
+			...props
+		} = slotProps;
+
+		return props;
+	});
+
+	return { animatedProps, animatedStyle };
+};

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

@@ -1,14 +1,9 @@
-import { useMemo } from "react";
-import { snapDescriptorToIndex } from "../../../animation/snap-to";
 import { useStack } from "../../../hooks/navigation/use-stack";
-import { ScreenAnimationProvider } from "../../../providers/screen/animation";
-import type { BaseDescriptor } from "../../../providers/screen/descriptors";
-import { DescriptorsProvider } from "../../../providers/screen/descriptors";
-import { ScreenOptionsProvider } from "../../../providers/screen/options";
-import { ScreenSlotProvider } from "../../../providers/screen/styles";
-import type { OverlayScreenState } from "../../../types/overlay.types";
 
-import { getActiveFloatOverlay } from "../helpers/get-active-overlay";
+import {
+	getFloatOverlayStack,
+	getFloatOverlayTransitions,
+} from "../helpers/get-active-overlay";
 import { OverlayHost } from "./overlay-host";
 
 /**
@@ -16,65 +11,28 @@ import { OverlayHost } from "./overlay-host";
  * Gets routes and descriptors from stack context.
  */
 export function FloatOverlay() {
-	const { scenes, focusedIndex, flags, routes, routeKeys } = useStack();
+	const { scenes, flags } = useStack();
 
-	const activeOverlay = useMemo(
-		() =>
-			getActiveFloatOverlay(scenes, focusedIndex, flags.TRANSITIONS_ALWAYS_ON),
-		[scenes, focusedIndex, flags.TRANSITIONS_ALWAYS_ON],
+	const overlayStack = getFloatOverlayStack(
+		scenes,
+		flags.TRANSITIONS_ALWAYS_ON,
 	);
-
-	const overlayData = useMemo(() => {
-		if (!activeOverlay) return null;
-
-		const { scene, overlayIndex } = activeOverlay;
-		const previous = scenes[overlayIndex - 1]?.descriptor;
-		const current = scene.descriptor;
-		const next = scenes[overlayIndex + 1]?.descriptor;
-		const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
-		const focusedDescriptor = focusedScene?.descriptor;
-
-		const overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]> =
-			{
-				index: routeKeys.indexOf(current.route.key),
-				options: focusedDescriptor?.options ?? {},
-				routes,
-				focusedRoute: focusedScene?.route ?? current.route,
-				focusedIndex,
-				meta: focusedDescriptor?.options?.meta,
-				navigation: current.navigation,
-				snapTo: (index: number) => {
-					snapDescriptorToIndex(current, index);
-				},
-			};
-
-		return {
-			scene,
-			previous,
-			current,
-			next,
-			overlayScreenState,
-		};
-	}, [activeOverlay, scenes, focusedIndex, routeKeys, routes]);
-
-	if (!overlayData) {
+	if (overlayStack.length === 0) {
 		return null;
 	}
 
-	const { scene, previous, current, next, overlayScreenState } = overlayData;
-
-	return (
-		<DescriptorsProvider current={current} previous={previous} next={next}>
-			<ScreenOptionsProvider>
-				<ScreenAnimationProvider>
-					<ScreenSlotProvider isFloatingOverlay>
-						<OverlayHost
-							scene={scene}
-							overlayScreenState={overlayScreenState}
-						/>
-					</ScreenSlotProvider>
-				</ScreenAnimationProvider>
-			</ScreenOptionsProvider>
-		</DescriptorsProvider>
+	const overlayTransitions = getFloatOverlayTransitions(overlayStack, scenes);
+
+	return overlayTransitions.map(
+		({ scene, activity, driverScene }, layerIndex) => (
+			<OverlayHost
+				key={scene.route.key}
+				scene={scene}
+				driverScene={driverScene}
+				previousOverlayScene={overlayTransitions[layerIndex - 1]?.scene}
+				activity={activity}
+				layerIndex={layerIndex}
+			/>
+		),
 	);
 }