react-native-screen-transitions 3.6.0 → 3.7.0-beta.0

package/src/shared/providers/stack/managed.provider.tsx

@@ -2,9 +2,10 @@ import type { Route } from "@react-navigation/native";
 import * as React from "react";
 import { useMemo } from "react";
 import {
-	StackContext,
 	type StackContextValue,
+	StackProvider,
 } from "../../hooks/navigation/use-stack";
+import { AnimationStore } from "../../stores/animation.store";
 import type {
 	ManagedStackContextValue,
 	ManagedStackProps,
@@ -17,9 +18,7 @@ import type {
 	BaseStackScene,
 } from "../../types/stack.types";
 import { useStackCoreContext } from "./core.provider";
-import { useClosingRouteMap } from "./helpers/use-closing-route-map";
-import { useLocalRoutes } from "./helpers/use-local-routes";
-import { useProcessedRoutes } from "./helpers/use-processed-routes";
+import { useManagedStackState } from "./helpers/managed-stack-state";
 import { useStackDerived } from "./helpers/use-stack-derived";
 
 const ManagedStackContext =
@@ -43,70 +42,55 @@ function useManagedStackValue<
 	props: ManagedStackProps<TDescriptor, TNavigation>,
 ): ManagedStackResult<TDescriptor> {
 	const { flags } = useStackCoreContext();
-	const { state, handleCloseRoute, closingRouteKeys } = useLocalRoutes(props);
+	const { state, handleCloseRoute, requestDismiss } =
+		useManagedStackState(props);
 	const navigatorKey = props.state.key;
 
-	const processed = useProcessedRoutes(state.routes, state.descriptors);
-	const { optimisticFocusedIndex } = useStackDerived(processed.animationMaps);
-	const closingRouteMap = useClosingRouteMap(
-		processed.routeKeys,
-		processed.animationMaps,
+	const animationMaps = useMemo(
+		() => state.routeKeys.map((routeKey) => AnimationStore.getBag(routeKey)),
+		[state.routeKeys],
 	);
+	const { optimisticFocusedIndex } = useStackDerived(animationMaps);
 
 	const focusedIndex = props.state.index;
 
-	// Common stack context (consumed by useStack())
 	const stackContextValue = useMemo<StackContextValue>(
 		() => ({
 			flags,
 			navigatorKey,
-			routeKeys: processed.routeKeys,
+			routeKeys: state.routeKeys,
 			routes: state.routes as Route<string>[],
-			scenes: processed.scenes as BaseStackScene[],
+			scenes: state.scenes as BaseStackScene[],
 			optimisticFocusedIndex,
+			focusedIndex,
+			requestDismiss,
 		}),
 		[
 			flags,
 			navigatorKey,
-			processed.routeKeys,
+			state.routeKeys,
 			state.routes,
-			processed.scenes,
+			state.scenes,
 			optimisticFocusedIndex,
+			focusedIndex,
+			requestDismiss,
 		],
 	);
 
-	// Managed-specific context (consumed by useManagedStackContext())
 	const managedContextValue = useMemo<ManagedStackContextValue>(
 		() => ({
-			activeScreensLimit: processed.activeScreensLimit,
-			closingRouteKeysShared: closingRouteKeys.shared,
 			handleCloseRoute,
-			backdropBehaviors: processed.backdropBehaviors,
 		}),
-		[
-			processed.activeScreensLimit,
-			closingRouteKeys.shared,
-			handleCloseRoute,
-			processed.backdropBehaviors,
-		],
+		[handleCloseRoute],
 	);
 
-	// Combined props for render children (stack-view components)
 	const renderProps = useMemo<ManagedStackRenderProps<TDescriptor>>(
 		() => ({
-			descriptors: state.descriptors,
-			scenes: processed.scenes,
+			scenes: state.scenes,
 			focusedIndex,
-			closingRouteMap,
-			shouldShowFloatOverlay: processed.shouldShowFloatOverlay,
+			shouldShowFloatOverlay: state.shouldShowFloatOverlay,
 		}),
-		[
-			state.descriptors,
-			processed.scenes,
-			focusedIndex,
-			closingRouteMap,
-			processed.shouldShowFloatOverlay,
-		],
+		[state.scenes, focusedIndex, state.shouldShowFloatOverlay],
 	);
 
 	return { stackContextValue, managedContextValue, renderProps };
@@ -125,11 +109,11 @@ function withManagedStack<
 			useManagedStackValue<TDescriptor, TNavigation>(props);
 
 		return (
-			<StackContext.Provider value={stackContextValue}>
+			<StackProvider value={stackContextValue}>
 				<ManagedStackContext.Provider value={managedContextValue}>
 					<Component {...renderProps} />
 				</ManagedStackContext.Provider>
-			</StackContext.Provider>
+			</StackProvider>
 		);
 	};
 }

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

@@ -231,6 +231,25 @@ export type BoundsNavigationRevealOptions = {
 	 * @default "freeform"
 	 */
 	gestureProgressMode?: GestureProgressMode;
+	/**
+	 * Scale applied to the unfocused background content while the reveal runs
+	 * above it.
+	 *
+	 * @default 0.9375
+	 */
+	backgroundScale?: number;
+	/**
+	 * Whether reveal should reset the unfocused background content scale once the
+	 * transition is logically settled.
+	 *
+	 * By default, reveal restores the background to scale `1` after settle so the
+	 * next drag or programmatic dismiss starts from a fresh, unmodified layout
+	 * measurement. Keeping the background transformed while idle can make the next
+	 * measurement read the scaled screen instead of the real screen geometry.
+	 *
+	 * @default true
+	 */
+	shouldBackgroundScaleResetOnSettled?: boolean;
 	/**
 	 * Temporarily blocks pointer-event pass-through on the inactive content until
 	 * the source element transition handoff reaches progress `0.25`.

package/src/shared/types/index.ts

@@ -34,6 +34,7 @@ export type {
 export type { OverlayProps } from "./overlay.types";
 export type {
 	GestureTracking,
+	InactiveBehavior,
 	Layout,
 	ScreenKey,
 	ScreenTransitionConfig,
@@ -46,4 +47,6 @@ export type {
 	BaseStackScene,
 	BaseStackState,
 	DescriptorMap,
+	StackDescriptorSource,
+	StackSceneActivity,
 } from "./stack.types";

package/src/shared/types/providers/managed-stack.types.ts

@@ -1,4 +1,3 @@
-import type { SharedValue } from "react-native-reanimated";
 import type { StackContextValue } from "../../hooks/navigation/use-stack";
 import type {
 	BaseStackDescriptor,
@@ -6,6 +5,7 @@ import type {
 	BaseStackRoute,
 	BaseStackScene,
 	BaseStackState,
+	StackDescriptorSource,
 } from "../stack.types";
 
 /**
@@ -18,8 +18,11 @@ export interface ManagedStackProps<
 > {
 	state: BaseStackState<TDescriptor["route"]>;
 	navigation: TNavigation;
-	descriptors: Record<string, TDescriptor>;
-	describe: (route: TDescriptor["route"], placeholder: boolean) => TDescriptor;
+	descriptors: Record<string, StackDescriptorSource<TDescriptor>>;
+	describe: (
+		route: TDescriptor["route"],
+		placeholder: boolean,
+	) => StackDescriptorSource<TDescriptor>;
 }
 
 /**
@@ -27,10 +30,7 @@ export interface ManagedStackProps<
  * Shared fields (routes, scenes, etc.) live in StackContext.
  */
 export interface ManagedStackContextValue {
-	activeScreensLimit: number;
-	closingRouteKeysShared: SharedValue<string[]>;
 	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
-	backdropBehaviors: string[];
 }
 
 /**
@@ -40,10 +40,8 @@ export interface ManagedStackContextValue {
 export interface ManagedStackRenderProps<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
-	descriptors: Record<string, TDescriptor>;
 	scenes: BaseStackScene<TDescriptor>[];
 	focusedIndex: number;
-	closingRouteMap: React.RefObject<Readonly<Record<string, true>>>;
 	shouldShowFloatOverlay: boolean;
 }
 

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

@@ -43,6 +43,31 @@ export type SnapPoint = number | "auto";
 
 export type BackdropBehavior = "block" | "passthrough" | "dismiss" | "collapse";
 
+/**
+ * Controls how an inactive screen is retained after it is no longer active.
+ *
+ * - `keep`
+ *   keep inactive screen mounted, attached, visible, not interactive
+ *   RNS: activityState=1, visible=true
+ *   React Activity: mode="visible"
+ *
+ * - `freeze`
+ *   keep last painted UI visible but stop/suspend inactive work where platform allows
+ *   RNS: activityState=1, visible=true, maybe freezeOnBlur/shouldFreeze later
+ *   React Activity: mode="hidden" with paint preserved
+ *
+ * - `detach`
+ *   remove inactive screen from native/view presentation after safe paint
+ *   RNS: activityState=0, visible=false
+ *   React Activity: mode="hidden" + display none, or equivalent
+ *
+ * - `unmount`
+ *   actually remove React subtree when the inactive screen is safe to remove
+ *   RNS native: only after safe paint for non-nested screens
+ *   web: return null
+ */
+export type InactiveBehavior = "keep" | "freeze" | "detach" | "unmount";
+
 export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	/**
 	 * Connects this component to custom animated styles defined in screenStyleInterpolator.

package/src/shared/types/stack.types.ts

@@ -18,6 +18,8 @@ export interface BaseStackRoute {
 	params?: object;
 }
 
+export type StackSceneActivity = "active" | "inert" | "inactive" | "closing";
+
 /**
  * Base navigation interface - minimal contract for gesture handling.
  * Both React Navigation helpers and ComponentNavigation satisfy this.
@@ -45,9 +47,16 @@ export interface BaseStackDescriptor<
 	route: TRoute;
 	navigation: TNavigation;
 	options: TOptions;
+	activity?: StackSceneActivity;
 	render?: () => React.JSX.Element | null;
 }
 
+export type StackDescriptorSource<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+> = Omit<TDescriptor, "activity"> & {
+	activity?: StackSceneActivity;
+};
+
 /**
  * Base scene interface - route + descriptor pair.
  * Used by all stack views to iterate over screens.
@@ -57,6 +66,8 @@ export interface BaseStackScene<
 > {
 	route: TDescriptor["route"];
 	descriptor: TDescriptor;
+	previousDescriptor?: TDescriptor;
+	nextDescriptor?: TDescriptor;
 }
 
 /**

package/src/shared/utils/bounds/navigation/reveal/build.ts

@@ -13,6 +13,7 @@ import {
 	DRAG_MASK_HEIGHT_COLLAPSE_END,
 	HORIZONTAL_DRAG_MASK_COLLAPSE_SCALE,
 	IDENTITY_DRAG_SCALE_OUTPUT,
+	REVEAL_BACKGROUND_SCALE,
 	REVEAL_BORDER_RADIUS,
 	REVEAL_SHADOW_OFFSET,
 	REVEAL_USES_TRANSFORM_MASK,
@@ -65,6 +66,10 @@ export function buildRevealStyles({
 	const disablePointerEventsTillElementTransition =
 		revealOptions?.disablePointerEventsTillElementTransition ?? true;
 	const maskSizingMode = revealOptions?.maskSizingMode ?? "auto";
+	const backgroundScale =
+		revealOptions?.backgroundScale ?? REVEAL_BACKGROUND_SCALE;
+	const shouldBackgroundScaleResetOnSettled =
+		revealOptions?.shouldBackgroundScaleResetOnSettled ?? true;
 	const usesTransformMask =
 		maskSizingMode === "auto"
 			? REVEAL_USES_TRANSFORM_MASK
@@ -366,8 +371,6 @@ export function buildRevealStyles({
 			},
 			[link.id]: {
 				style: {
-					position: "relative",
-					zIndex: 999,
 					transform: [{ translateX: elementTX }, { translateY: elementY }],
 				},
 			},
@@ -376,10 +379,11 @@ export function buildRevealStyles({
 
 	/* ---------------------------- Unfocused Screen ---------------------------- */
 
-	const unfocusedScale = mixUnit(1, 0.9375, props.active.progress);
-	const unfocusedContentScale = props.active.logicallySettled
-		? 1
-		: unfocusedScale;
+	const unfocusedScale = mixUnit(1, backgroundScale, props.active.progress);
+	const unfocusedContentScale =
+		props.active.logicallySettled && shouldBackgroundScaleResetOnSettled
+			? 1
+			: unfocusedScale;
 
 	const trackingContentTarget =
 		initialDestinationTarget ?? link.destination.bounds;

package/src/shared/utils/bounds/navigation/reveal/config.ts

@@ -15,6 +15,7 @@ export const DRAG_MASK_HEIGHT_COLLAPSE_END = 0.7;
 export const HORIZONTAL_DRAG_MASK_COLLAPSE_SCALE = 0.5;
 export const DISMISS_SCALE_ORBIT_DEPTH = 0.5;
 export const CLOSE_SOURCE_HANDOFF_PROGRESS = 0.25;
+export const REVEAL_BACKGROUND_SCALE = 0.9375;
 
 export const IDENTITY_DRAG_SCALE_OUTPUT = [1, 1] as const;
 export const ZERO_TO_ONE_RANGE = [0, 1] as const;

package/src/shared/utils/create-provider.tsx

@@ -6,12 +6,82 @@
 import {
 	createContext,
 	type ReactNode,
+	useCallback,
 	useContext,
+	useLayoutEffect,
 	useMemo,
 	useRef,
+	useSyncExternalStore,
 } from "react";
 
-type InnerProviderComponent = (props: { children: ReactNode }) => ReactNode;
+type InnerProviderComponent = React.FC<{ children: ReactNode }>;
+
+type ProviderSnapshot<
+	ContextValue,
+	Guarded extends boolean,
+> = Guarded extends true ? ContextValue : ContextValue | null;
+
+type ProviderSelector<ContextValue, Guarded extends boolean, Selected> = (
+	value: ProviderSnapshot<ContextValue, Guarded>,
+) => Selected;
+
+type ProviderStoreHook<ContextValue, Guarded extends boolean> = {
+	(): ProviderSnapshot<ContextValue, Guarded>;
+	<Selected>(
+		selector: ProviderSelector<ContextValue, Guarded, Selected>,
+	): Selected;
+};
+
+type ProviderOptionalStoreHook<ContextValue> = {
+	(): ContextValue | null;
+	<Selected>(selector: (value: ContextValue | null) => Selected): Selected;
+};
+
+export interface ProviderStoreApi<ContextValue> {
+	getSnapshot: () => ContextValue | null;
+	subscribe: (listener: () => void) => () => void;
+}
+
+interface MutableProviderStoreApi<ContextValue>
+	extends ProviderStoreApi<ContextValue> {
+	notify: () => void;
+	setSnapshot: (snapshot: ContextValue | null) => boolean;
+}
+
+const NullProviderStore: ProviderStoreApi<never> = {
+	getSnapshot: () => null,
+	subscribe: () => () => {},
+};
+
+const createProviderStore = <ContextValue,>(
+	initialSnapshot: ContextValue | null,
+): MutableProviderStoreApi<ContextValue> => {
+	let snapshot = initialSnapshot;
+	const listeners = new Set<() => void>();
+
+	return {
+		getSnapshot: () => snapshot,
+		notify: () => {
+			for (const listener of listeners) {
+				listener();
+			}
+		},
+		setSnapshot: (nextSnapshot) => {
+			if (Object.is(snapshot, nextSnapshot)) {
+				return false;
+			}
+
+			snapshot = nextSnapshot;
+			return true;
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+	};
+};
 
 export default function createProvider<
 	ProviderName extends string,
@@ -31,10 +101,17 @@ export default function createProvider<
 		},
 	) => {
 		const { guarded = true } = options ?? {};
+		const providerDisplayName = `${name}Provider`;
+		const innerProviderDisplayName = `${name}InnerProvider`;
 
 		const Context = createContext<ContextValue | null>(null);
 		Context.displayName = name;
 
+		const StoreContext = createContext<ProviderStoreApi<ContextValue> | null>(
+			null,
+		);
+		StoreContext.displayName = `${name}Store`;
+
 		const Provider: React.FC<ProviderProps> = (props) => {
 			const {
 				children = (props as { children?: ReactNode }).children,
@@ -53,20 +130,46 @@ export default function createProvider<
 				[enabled, value],
 			);
 
+			const storeRef = useRef<MutableProviderStoreApi<ContextValue> | null>(
+				null,
+			);
+			const pendingNotifyRef = useRef(false);
+
+			if (storeRef.current === null) {
+				storeRef.current = createProviderStore<ContextValue>(memoValue);
+			}
+			const store = storeRef.current;
+
+			pendingNotifyRef.current =
+				store.setSnapshot(memoValue) || pendingNotifyRef.current;
+
+			useLayoutEffect(() => {
+				if (!pendingNotifyRef.current) {
+					return;
+				}
+
+				pendingNotifyRef.current = false;
+				store.notify();
+			});
+
 			// Per-instance ref ensures InnerProvider reads latest value while keeping
 			// a stable component reference.
 			const valueRef = useRef<ContextValue | null>(memoValue);
 			valueRef.current = memoValue;
 
-			const InnerProvider = useMemo(
-				(): InnerProviderComponent =>
-					({ children }) => (
+			const InnerProvider = useMemo((): InnerProviderComponent => {
+				const NamedInnerProvider: InnerProviderComponent = ({ children }) => (
+					<StoreContext.Provider value={store}>
 						<Context.Provider value={valueRef.current}>
 							{children}
 						</Context.Provider>
-					),
-				[],
-			);
+					</StoreContext.Provider>
+				);
+
+				NamedInnerProvider.displayName = innerProviderDisplayName;
+
+				return NamedInnerProvider;
+			}, [store]);
 
 			if (typeof children === "function") {
 				return children({
@@ -74,8 +177,13 @@ export default function createProvider<
 				} as { [K in ProviderName as `${K}Provider`]: InnerProviderComponent });
 			}
 
-			return <Context.Provider value={memoValue}>{children}</Context.Provider>;
+			return (
+				<StoreContext.Provider value={store}>
+					<Context.Provider value={memoValue}>{children}</Context.Provider>
+				</StoreContext.Provider>
+			);
 		};
+		Provider.displayName = providerDisplayName;
 
 		const useEnhancedContext = (): ContextValue | null => {
 			const context = useContext(Context);
@@ -89,18 +197,85 @@ export default function createProvider<
 			return context;
 		};
 
+		const useStoreSelector = <Selected,>(
+			selector?: (value: ContextValue | null) => Selected,
+		): Selected | ContextValue | null => {
+			const store = useContext(StoreContext);
+			const resolvedStore =
+				store ?? (NullProviderStore as ProviderStoreApi<ContextValue>);
+			const selectorRef = useRef<typeof selector>(selector);
+			selectorRef.current = selector;
+
+			const getSelectedSnapshot = useCallback(() => {
+				if (guarded && store === null) {
+					throw new Error(
+						`${name} store must be used within a ${name}Provider`,
+					);
+				}
+
+				const snapshot = resolvedStore.getSnapshot();
+
+				if (guarded && snapshot === null) {
+					throw new Error(
+						`${name} store must be used within an enabled ${name}Provider`,
+					);
+				}
+
+				return selectorRef.current ? selectorRef.current(snapshot) : snapshot;
+			}, [resolvedStore, store]);
+
+			return useSyncExternalStore(
+				resolvedStore.subscribe,
+				getSelectedSnapshot,
+				getSelectedSnapshot,
+			);
+		};
+
+		const useOptionalStoreSelector = <Selected,>(
+			selector?: (value: ContextValue | null) => Selected,
+		): Selected | ContextValue | null => {
+			const store = useContext(StoreContext);
+			const resolvedStore =
+				store ?? (NullProviderStore as ProviderStoreApi<ContextValue>);
+			const selectorRef = useRef<typeof selector>(selector);
+			selectorRef.current = selector;
+
+			const getSelectedSnapshot = useCallback(() => {
+				const snapshot = resolvedStore.getSnapshot();
+				return selectorRef.current ? selectorRef.current(snapshot) : snapshot;
+			}, [resolvedStore]);
+
+			return useSyncExternalStore(
+				resolvedStore.subscribe,
+				getSelectedSnapshot,
+				getSelectedSnapshot,
+			);
+		};
+
 		return {
 			[`${name}Context`]: Context,
+			[`${name}StoreContext`]: StoreContext,
 			[`${name}Provider`]: Provider,
 			[`use${name}Context`]: useEnhancedContext,
+			[`use${name}Store`]: useStoreSelector,
+			[`use${name}OptionalStore`]: useOptionalStoreSelector,
 		} as {
 			[P in ProviderName as `${P}Context`]: React.Context<ContextValue>;
+		} & {
+			[P in ProviderName as `${P}StoreContext`]: React.Context<ProviderStoreApi<ContextValue> | null>;
 		} & {
 			[P in ProviderName as `${P}Provider`]: React.FC<ProviderProps>;
 		} & {
 			[P in ProviderName as `use${P}Context`]: () => Guarded extends true
 				? ContextValue
 				: ContextValue | null;
+		} & {
+			[P in ProviderName as `use${P}Store`]: ProviderStoreHook<
+				ContextValue,
+				Guarded
+			>;
+		} & {
+			[P in ProviderName as `use${P}OptionalStore`]: ProviderOptionalStoreHook<ContextValue>;
 		};
 	};
 }

package/src/shared/utils/navigation/resolve-scene-neighbors.ts

@@ -4,6 +4,7 @@ interface SceneWithKey {
 }
 
 type IsRouteClosing = (routeKey: string) => boolean;
+type GetRouteClosingOrder = (routeKey: string) => number | undefined;
 
 const findPreviousDescriptor = <T extends SceneWithKey>(
 	scenes: T[],
@@ -45,6 +46,7 @@ export function resolveSceneNeighbors<T extends SceneWithKey>(
 	scenes: T[],
 	sceneIndex: number,
 	isRouteClosing: IsRouteClosing,
+	getRouteClosingOrder?: GetRouteClosingOrder,
 ): {
 	previousDescriptor: T["descriptor"] | undefined;
 	nextDescriptor: T["descriptor"] | undefined;
@@ -69,7 +71,8 @@ export function resolveSceneNeighbors<T extends SceneWithKey>(
 	}
 
 	let nextDescriptor: T["descriptor"] | undefined;
-	let firstClosingAbove: T["descriptor"] | undefined;
+	let latestClosingAbove: T["descriptor"] | undefined;
+	let latestClosingAboveOrder = Number.NEGATIVE_INFINITY;
 
 	for (let i = sceneIndex + 1; i < scenes.length; i++) {
 		const candidate = scenes[i];
@@ -80,13 +83,15 @@ export function resolveSceneNeighbors<T extends SceneWithKey>(
 			break;
 		}
 
-		if (firstClosingAbove === undefined) {
-			firstClosingAbove = candidate.descriptor;
+		const closeOrder = getRouteClosingOrder?.(candidate.route.key) ?? i;
+		if (closeOrder >= latestClosingAboveOrder) {
+			latestClosingAbove = candidate.descriptor;
+			latestClosingAboveOrder = closeOrder;
 		}
 	}
 
 	if (nextDescriptor === undefined) {
-		nextDescriptor = firstClosingAbove;
+		nextDescriptor = latestClosingAbove;
 	}
 
 	const previousDescriptor = findPreviousDescriptor(