react-native-screen-transitions 3.11.2 → 3.12.0

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

package/src/shared/providers/screen/styles/hooks/slot-resolvers.tsx

@@ -1,3 +1,4 @@
+import { useRoute } from "@react-navigation/native";
 import { useMemo } from "react";
 import { useAnimatedProps, useAnimatedStyle } from "react-native-reanimated";
 import { NO_PROPS, NO_STYLES } from "../../../../constants";
@@ -7,8 +8,19 @@ import {
 } from "../helpers/compose-slot-style";
 import { useScreenSlots } from "../slot.provider";
 
+const useCurrentScreenSlotsMap = () => {
+	const route = useRoute();
+	const slotsMap = useScreenSlots(route.key, (store) => store.slotsMap);
+
+	if (!slotsMap) {
+		throw new Error(`ScreenSlot store for route "${route.key}" was not found`);
+	}
+
+	return slotsMap;
+};
+
 export const useSlotStyles = (slotId: string | undefined) => {
-	const { slotsMap } = useScreenSlots();
+	const slotsMap = useCurrentScreenSlotsMap();
 
 	return useAnimatedStyle(() => {
 		const slot = slotId ? slotsMap.get()[slotId] : undefined;
@@ -26,7 +38,7 @@ export const useComposedSlotStyles = (
 	slotId: string | undefined,
 	style: unknown,
 ) => {
-	const { slotsMap } = useScreenSlots();
+	const slotsMap = useCurrentScreenSlotsMap();
 	const localTransform = useMemo(
 		() => getLocalTransformForSlotComposition(style),
 		[style],
@@ -50,7 +62,7 @@ export const useComposedSlotStyles = (
  * target takes the full associated style. Yields `NO_STYLES` when neither is set.
  */
 export const useSlotStackingStyles = (slotId: string | undefined) => {
-	const { slotsMap } = useScreenSlots();
+	const slotsMap = useCurrentScreenSlotsMap();
 
 	return useAnimatedStyle(() => {
 		const baseStyle = slotId ? slotsMap.get()[slotId]?.style : undefined;
@@ -66,7 +78,7 @@ export const useSlotStackingStyles = (slotId: string | undefined) => {
 };
 
 export const useSlotLayoutStyles = (slotId: string | undefined) => {
-	const { slotsMap } = useScreenSlots();
+	const slotsMap = useCurrentScreenSlotsMap();
 
 	return useAnimatedStyle(() => {
 		const baseStyle = slotId ? slotsMap.get()[slotId]?.style : undefined;
@@ -103,7 +115,7 @@ export const useSlotLayoutStyles = (slotId: string | undefined) => {
 };
 
 export const useSlotProps = (slotId: string | undefined) => {
-	const { slotsMap } = useScreenSlots();
+	const slotsMap = useCurrentScreenSlotsMap();
 
 	return useAnimatedProps(() => {
 		return (slotId ? slotsMap.get()[slotId]?.props : undefined) ?? NO_PROPS;

package/src/shared/providers/screen/styles/hooks/use-interpolated-style-maps.tsx

@@ -40,6 +40,7 @@ import { stripInterpolatorOptions } from "../helpers/strip-interpolator-options"
 import {
 	hasCloseTransitionFinished,
 	isOpenTransitionBlocked,
+	isScreenInterpolatorReady,
 } from "../helpers/transition-visual-state";
 import { resolveInitialDestinationStyleGate } from "../helpers/visibility-gate";
 
@@ -144,17 +145,59 @@ export const useInterpolatedStylesMap = ({
 		(s) => s.derivations.destinationPairKey,
 	);
 	const screenOptions = useScreenOptionsStore();
-	const {
+	const screenInterpolatorProps = useScreenAnimationStore(
+		(store) => store.screenInterpolatorProps,
+	);
+	const screenInterpolatorPropsRevision = useScreenAnimationStore(
+		(store) => store.screenInterpolatorPropsRevision,
+	);
+	const selectedInterpolatorOptions = useScreenAnimationStore(
+		(store) => store.selectedInterpolatorOptions,
+	);
+	const nextInterpolator = useScreenAnimationStore(
+		(store) => store.nextInterpolator,
+	);
+	const currentInterpolator = useScreenAnimationStore(
+		(store) => store.currentInterpolator,
+	);
+	const ancestorScreenAnimationSources = useScreenAnimationStore(
+		(store) => store.ancestorScreenAnimationSources,
+	);
+	const descendantScreenAnimationSources = useScreenAnimationStore(
+		(store) => store.descendantScreenAnimationSources,
+	);
+	const transition = useBuildTransitionAccessor({
 		screenInterpolatorProps,
 		screenInterpolatorPropsRevision,
-		selectedInterpolatorOptions,
-		nextInterpolator,
-		currentInterpolator,
 		ancestorScreenAnimationSources,
 		descendantScreenAnimationSources,
-	} = useScreenAnimationStore();
-	const transition = useBuildTransitionAccessor();
-	const nextInterpolatorReady = useSharedValue(0);
+	});
+	const hasCurrentInterpolator = !!currentInterpolator;
+	const { closing: currentClosing, entering: currentEntering } =
+		AnimationStore.getBag(currentScreenKey);
+	const {
+		animationProgress: currentAnimationProgress,
+		pendingLifecycleRequestKind: currentPendingLifecycleRequestKind,
+		pendingLifecycleStartBlockCount: currentPendingLifecycleStartBlockCount,
+	} = SystemStore.getBag(currentScreenKey);
+	const interpolatorReady = useDerivedValue<number>(() => {
+		"worklet";
+		const isPendingOpen =
+			currentPendingLifecycleRequestKind.get() ===
+			LifecycleTransitionRequestKind.Open;
+		const opening = isPendingOpen || !!currentEntering.get();
+
+		return isScreenInterpolatorReady({
+			hasInterpolator: hasCurrentInterpolator,
+			opening,
+			closing: currentClosing.get(),
+			pendingLifecycleStartBlockCount:
+				currentPendingLifecycleStartBlockCount.get(),
+			animationProgress: currentAnimationProgress.get(),
+		})
+			? 1
+			: 0;
+	});
 
 	// In some cases, a user may want to use external shared values to drive animations in the interpoaltor.
 	// We can now support this by collecting those shared values and reading them here to trigger an update.
@@ -249,10 +292,6 @@ export const useInterpolatedStylesMap = ({
 			!nextInterpolator ||
 			isOpeningBlocked ||
 			hasCloseFinished;
-		const nextReady = currentOwnsInterpolator ? 0 : 1;
-
-		nextInterpolatorReady.set(nextReady);
-
 		const interpolatorOptionsOwner = currentOwnsInterpolator
 			? "current"
 			: "next";
@@ -328,7 +367,7 @@ export const useInterpolatedStylesMap = ({
 	});
 
 	return {
+		interpolatorReady,
 		localStylesMaps,
-		nextInterpolatorReady,
 	};
 };

package/src/shared/providers/screen/styles/slot.provider.tsx

@@ -1,4 +1,4 @@
-import { type ReactNode, useLayoutEffect, useMemo } from "react";
+import { type ReactNode, useMemo } from "react";
 import { StyleSheet } from "react-native";
 import Animated, { type SharedValue } from "react-native-reanimated";
 import type {
@@ -8,22 +8,16 @@ import type {
 import type { NormalizedTransitionInterpolatedStyle } from "../../../types/animation.types";
 import createProvider from "../../../utils/create-provider";
 import { useDescriptorsStore } from "../descriptors";
-import { FloatingOverlayLayer } from "./components/floating-overlay-layer";
-import type { LocalStyleLayers } from "./helpers/resolve-slot-styles";
 import { useInterpolatedStylesMap } from "./hooks/use-interpolated-style-maps";
 import { useMaybeBlockVisibility } from "./hooks/use-maybe-block-visibility";
 import { useResolvedStylesMap } from "./hooks/use-resolved-slot-style-map";
-import {
-	registerScreenSlots,
-	unregisterScreenSlots,
-} from "./stores/slot-references.store";
 
 type Props = {
 	children: ReactNode;
-	isFloatingOverlay?: boolean;
 };
 
 export type ScreenSlotName =
+	| "overlay"
 	| "content"
 	| "backdrop"
 	| "surface"
@@ -31,8 +25,7 @@ export type ScreenSlotName =
 	| typeof NAVIGATION_MASK_ELEMENT_STYLE_ID;
 
 export type ScreenSlotContextValue = {
-	localStylesMaps: SharedValue<LocalStyleLayers>;
-	nextInterpolatorReady: SharedValue<number>;
+	interpolatorReady: SharedValue<number>;
 	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
 	visibilityBlocked: SharedValue<boolean>;
 };
@@ -40,69 +33,52 @@ export type ScreenSlotContextValue = {
 export const { ScreenSlotProvider, useScreenSlotStore: useScreenSlots } =
 	createProvider("ScreenSlot", {
 		guarded: true,
-	})<Props, ScreenSlotContextValue>(
-		({ children, isFloatingOverlay }, { useParentStore }) => {
-			const parentContext = useParentStore();
-			const currentScreenKey = useDescriptorsStore(
-				(s) => s.derivations.currentScreenKey,
-			);
+		global: true,
+	})<Props, ScreenSlotContextValue>(({ children }, { useParentStore }) => {
+		const ancestorStylesMap = useParentStore(
+			(parentContext) => parentContext?.slotsMap,
+		);
+		const currentScreenKey = useDescriptorsStore(
+			(store) => store.derivations.currentScreenKey,
+		);
+		const { animatedStyle, animatedProps, shouldBlockVisibility } =
+			useMaybeBlockVisibility();
 
-			const { animatedStyle, animatedProps, shouldBlockVisibility } =
-				useMaybeBlockVisibility(isFloatingOverlay);
+		const { interpolatorReady, localStylesMaps } = useInterpolatedStylesMap({
+			enabled: true,
+			visibilityBlocked: shouldBlockVisibility,
+		});
 
-			const { localStylesMaps, nextInterpolatorReady } =
-				useInterpolatedStylesMap({
-					enabled: !isFloatingOverlay,
-					visibilityBlocked: shouldBlockVisibility,
-				});
+		const slotsMap = useResolvedStylesMap({
+			localStylesMaps,
+			ancestorStylesMap,
+		});
+		const value = useMemo(
+			() => ({
+				interpolatorReady,
+				slotsMap,
+				visibilityBlocked: shouldBlockVisibility,
+			}),
+			[interpolatorReady, shouldBlockVisibility, slotsMap],
+		);
+		const content = useMemo(
+			() => (
+				<Animated.View
+					style={[styles.container, animatedStyle]}
+					animatedProps={animatedProps}
+				>
+					{children}
+				</Animated.View>
+			),
+			[children, animatedStyle, animatedProps],
+		);
 
-			const slotsMap = useResolvedStylesMap({
-				localStylesMaps,
-				ancestorStylesMap: parentContext?.slotsMap,
-			});
-			const value = useMemo(
-				() => ({
-					localStylesMaps,
-					nextInterpolatorReady,
-					slotsMap,
-					visibilityBlocked: shouldBlockVisibility,
-				}),
-				[
-					localStylesMaps,
-					nextInterpolatorReady,
-					shouldBlockVisibility,
-					slotsMap,
-				],
-			);
-
-			useLayoutEffect(() => {
-				registerScreenSlots(currentScreenKey, value);
-
-				return () => {
-					unregisterScreenSlots(currentScreenKey, value);
-				};
-			}, [currentScreenKey, value]);
-
-			const content = useMemo(
-				() => (
-					<FloatingOverlayLayer enabled={isFloatingOverlay}>
-						<Animated.View
-							style={[styles.container, animatedStyle]}
-							animatedProps={animatedProps}
-						>
-							{children}
-						</Animated.View>
-					</FloatingOverlayLayer>
-				),
-				[children, animatedStyle, isFloatingOverlay, animatedProps],
-			);
-
-			return {
-				value,
-				children: content,
-			};
-		},
-	);
+		return {
+			key: currentScreenKey,
+			value,
+			children: content,
+		};
+	});
 
 const styles = StyleSheet.create({
 	container: { flex: 1 },

package/src/shared/providers/stack/blank-stack-state/blank-stack-controller.ts

@@ -5,6 +5,7 @@ import type {
 	BaseStackNavigation,
 	BaseStackRoute,
 } from "../../../types/stack.types";
+import { dispatchCloseAction } from "../../../utils/navigation/close-action-replay";
 import { buildBlankStackState } from "./helpers/build-blank-stack-state";
 import { deriveBlankStackState } from "./helpers/derive-blank-stack-state";
 import type {
@@ -86,10 +87,13 @@ export const createBlankStackController = <
 		const { state, navigation } = props;
 
 		if (state.routes.some((candidate) => candidate.key === route.key)) {
-			navigation.dispatch({
+			const action = {
 				...StackActions.pop(),
 				source: route.key,
 				target: state.key,
+			};
+			dispatchCloseAction(action, (closeAction) => {
+				navigation.dispatch(closeAction);
 			});
 			return;
 		}

package/src/shared/providers/stack/blank-stack-state/helpers/resolve-presented-index.ts

@@ -0,0 +1,22 @@
+import type { BaseStackRoute } from "../../../../types/stack.types";
+
+export function resolvePresentedIndex(
+	routes: BaseStackRoute[],
+	focusedRouteKey: string | undefined,
+	closingRouteKeys: ReadonlySet<string>,
+): number {
+	const focusedIndex = focusedRouteKey
+		? routes.findIndex((route) => route.key === focusedRouteKey)
+		: routes.length - 1;
+	const resolvedFocusedIndex =
+		focusedIndex >= 0 ? focusedIndex : routes.length - 1;
+
+	for (let index = resolvedFocusedIndex; index >= 0; index -= 1) {
+		const route = routes[index];
+		if (route && !closingRouteKeys.has(route.key)) {
+			return index;
+		}
+	}
+
+	return resolvedFocusedIndex;
+}

package/src/shared/providers/stack/blank-stack.provider.tsx

@@ -15,6 +15,7 @@ import type {
 } from "../../types/stack.types";
 import createProvider from "../../utils/create-provider";
 import { useBlankStackState } from "./blank-stack-state";
+import { resolvePresentedIndex } from "./blank-stack-state/helpers/resolve-presented-index";
 import { useStackCoreStore } from "./core.provider";
 
 type InternalBlankStackProviderProps = BlankStackProviderProps<
@@ -58,7 +59,11 @@ function BlankStackProvider({
 		state: stackState,
 	});
 	const navigatorKey = stackState.key;
-	const focusedIndex = stackState.index;
+	const focusedIndex = resolvePresentedIndex(
+		state.routes,
+		state.focusedRouteKey,
+		state.closingRouteKeys,
+	);
 	const scenesByKey = useMemo(
 		() => createScenesByKey(state.scenes),
 		[state.scenes],

package/src/shared/stores/bounds/internals/links.ts

@@ -242,7 +242,7 @@ const writeDestination = (
 
 	writePairLink(state, pairKey, linkKey, link);
 
-	if (link.group) {
+	if (link.group && !state[pairKey]?.groups?.[link.group]) {
 		writeGroup(state, pairKey, link.group, linkKey);
 	}
 };

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

@@ -9,8 +9,7 @@ import { createStore } from "../utils/create-store";
 export enum LifecycleTransitionRequestKind {
 	None = 0,
 	Open = 1,
-	BlankStackClose = 2,
-	NativeClose = 3,
+	Close = 2,
 }
 
 type SystemStoreState = {

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

@@ -384,6 +384,14 @@ export type TransitionInterpolatedStyle = {
 	 * This reserved key is stripped before style slot normalization.
 	 */
 	options?: TransitionInterpolatorOptions;
+	/**
+	 * Animated style and props for the route-owned floating overlay.
+	 *
+	 * Visible overlays form their own adjacency chain. A route that returns this
+	 * slot controls the previous visible overlay and, when it owns an overlay,
+	 * its entering overlay.
+	 */
+	overlay?: TransitionSlotStyle;
 	/** Animated style and props for the main screen content view. */
 	content?: TransitionSlotStyle;
 	/** Animated style and props for the backdrop layer between screens. */

package/src/shared/types/index.ts

@@ -51,7 +51,7 @@ export type {
 	ScrollMetadataState,
 	SideActivation,
 } from "./gesture.types";
-export type { OverlayProps } from "./overlay.types";
+export type { OverlayComponent, OverlayProps } from "./overlay.types";
 export type {
 	GestureTracking,
 	InactiveBehavior,

package/src/shared/types/overlay.types.ts

@@ -1,28 +1,44 @@
-import type { Route } from "@react-navigation/native";
+import type {
+	ParamListBase,
+	ParamListRoute,
+	RouteProp,
+} from "@react-navigation/native";
+import type { ReactNode } from "react";
 import type { DerivedValue } from "react-native-reanimated";
 import type { ScreenTransitionConfig } from "./screen.types";
 
 /**
- * Props passed to overlay components.
- * Generic over the navigation type since different stacks have different navigation props.
+ * Overlay state without the animated progress value.
  */
+export type OverlayScreenState<
+	TNavigation = unknown,
+	TParamList extends ParamListBase = ParamListBase,
+	TOwnerRouteName extends keyof TParamList = keyof TParamList,
+> = Omit<OverlayProps<TNavigation, TParamList, TOwnerRouteName>, "progress"> & {
+	snapTo: (index: number) => void;
+};
+
 /**
- * Overlay screen state passed to overlay host for rendering.
- * Generic over navigation type — defaults to `unknown` for flexibility.
+ * Props passed to a floating overlay component.
+ *
+ * `route` and `index` identify the screen that owns the overlay. Focused
+ * values may describe a later screen while that overlay remains visible.
  */
-export type OverlayScreenState<TNavigation = unknown> = Omit<
-	OverlayProps<TNavigation>,
-	"progress"
-> & {
+export type OverlayProps<
+	TNavigation = unknown,
+	TParamList extends ParamListBase = ParamListBase,
+	TOwnerRouteName extends keyof TParamList = keyof TParamList,
+> = {
+	/** Route that declared this overlay. */
+	route: RouteProp<TParamList, TOwnerRouteName>;
+
+	/** Index of the route that declared this overlay. */
 	index: number;
-	snapTo: (index: number) => void;
-};
 
-export type OverlayProps<TNavigation = unknown> = {
 	/**
 	 * Route of the currently focused screen in the stack.
 	 */
-	focusedRoute: Route<string>;
+	focusedRoute: ParamListRoute<TParamList>;
 
 	/**
 	 * Index of the focused route in the stack.
@@ -32,7 +48,7 @@ export type OverlayProps<TNavigation = unknown> = {
 	/**
 	 * All routes currently in the stack.
 	 */
-	routes: Route<string>[];
+	routes: ParamListRoute<TParamList>[];
 
 	/**
 	 * Custom metadata from the focused screen's options.
@@ -55,3 +71,14 @@ export type OverlayProps<TNavigation = unknown> = {
 	 */
 	progress: DerivedValue<number>;
 };
+
+/**
+ * Component rendered for a floating screen overlay.
+ *
+ * The callback is bivariant because React Navigation stores overlay components
+ * in navigator-wide screen options while applications annotate them for one
+ * specific route.
+ */
+export type OverlayComponent = {
+	bivarianceHack(props: OverlayProps): ReactNode;
+}["bivarianceHack"];

package/src/shared/types/screen.types.ts

@@ -11,7 +11,7 @@ import type {
 	GestureProgressMode,
 	ScrollMetadataState,
 } from "./gesture.types";
-import type { OverlayProps } from "./overlay.types";
+import type { OverlayComponent } from "./overlay.types";
 
 export type Layout = {
 	width: number;
@@ -336,7 +336,7 @@ export type ScreenTransitionConfig = {
 	/**
 	 * Function that returns a React Element to display as an overlay.
 	 */
-	overlay?: (props: OverlayProps) => React.ReactNode;
+	overlay?: OverlayComponent;
 
 	/**
 	 * Whether to show the overlay. The overlay is shown by default when `overlay` is provided.

package/src/shared/utils/animation/animate-to-progress.ts

@@ -1,4 +1,4 @@
-import { runOnJS, type SharedValue } from "react-native-reanimated";
+import type { SharedValue } from "react-native-reanimated";
 import { FALSE, TRUE } from "../../constants";
 import {
 	type AnimationStoreMap,
@@ -16,7 +16,6 @@ interface AnimateToProgressProps {
 	 */
 	target: "open" | "close" | number;
 	spec?: TransitionSpec;
-	onAnimationFinish?: (finished: boolean) => void;
 	animations: AnimationStoreMap;
 	targetProgress: SharedValue<number>;
 	animationProgress: SharedValue<number>;
@@ -61,7 +60,6 @@ export const resolveAnimationProgressRange = (
 export const animateToProgress = ({
 	target,
 	spec,
-	onAnimationFinish,
 	animations,
 	targetProgress,
 	animationProgress,
@@ -112,9 +110,6 @@ export const animateToProgress = ({
 				entering.set(FALSE);
 			}
 
-			if (onAnimationFinish) {
-				runOnJS(onAnimationFinish)(true);
-			}
 			return;
 		}
 
@@ -141,23 +136,7 @@ export const animateToProgress = ({
 
 					if (isClosing) {
 						progressAnimating.set(FALSE);
-
-						if (onAnimationFinish) {
-							// Paint the terminal UI-thread host/style state before React
-							// removes the closing route and its native portal host.
-							requestAnimationFrame(() => {
-								"worklet";
-								requestAnimationFrame(() => {
-									"worklet";
-									runOnJS(onAnimationFinish)(state.finished);
-								});
-							});
-						}
 					} else {
-						if (onAnimationFinish) {
-							runOnJS(onAnimationFinish)(state.finished);
-						}
-
 						// Delay clearing progress animation by one frame to ensure final frame is painted
 						requestAnimationFrame(() => {
 							progressAnimating.set(FALSE);