react-native-screen-transitions 4.0.0 → 4.1.0-beta.0

package/src/providers/screen/screen-composer.tsx

@@ -1,45 +1,26 @@
-import type React from "react";
-import { ScreenContainer } from "../../components/screen-container";
-import { ScreenLifecycle } from "../../components/screen-lifecycle";
-import { ScreenAnimationProvider } from "./animation";
-import { type BaseDescriptor, DescriptorsProvider } from "./descriptors";
-import { ScreenGestureProvider } from "./gestures";
-import { ScreenOptionsProvider } from "./options";
-import { ScreenSlotProvider } from "./styles";
+import { ScreenContainer } from "../../components/screen/container";
+import { BuilderProvider, type BuilderProviderProps } from "./builder";
+import { MotionProvider } from "./motion";
+import { OrchestratorProvider } from "./orchestrator";
 
-type Props = {
-	previous?: BaseDescriptor;
-	current?: BaseDescriptor;
-	next?: BaseDescriptor;
-	routeKey?: string;
-	children: React.ReactNode;
+export type ScreenComposerProps = BuilderProviderProps & {
+	onDismissRequest?: () => void;
 };
 
 export function ScreenComposer({
-	previous,
-	current,
-	next,
-	routeKey,
 	children,
-}: Props) {
+	onDismissRequest,
+	...builderProps
+}: ScreenComposerProps) {
 	return (
-		<DescriptorsProvider
-			previous={previous}
-			current={current}
-			next={next}
-			routeKey={routeKey}
-		>
-			<ScreenLifecycle>
-				<ScreenOptionsProvider>
-					<ScreenGestureProvider>
-						<ScreenAnimationProvider>
-							<ScreenSlotProvider>
-								<ScreenContainer>{children}</ScreenContainer>
-							</ScreenSlotProvider>
-						</ScreenAnimationProvider>
-					</ScreenGestureProvider>
-				</ScreenOptionsProvider>
-			</ScreenLifecycle>
-		</DescriptorsProvider>
+		<BuilderProvider {...builderProps}>
+			<MotionProvider onDismissRequest={onDismissRequest}>
+				<OrchestratorProvider>
+					<ScreenContainer onDismissRequest={onDismissRequest}>
+						{children}
+					</ScreenContainer>
+				</OrchestratorProvider>
+			</MotionProvider>
+		</BuilderProvider>
 	);
 }

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

@@ -117,6 +117,27 @@ export const createBlankStackController = (
 		emit();
 	};
 
+	const handleOpenRoute = ({ route }: { route: BaseStackRoute }) => {
+		const current = snapshot.state;
+		const openedIndex = current.routes.findIndex(
+			(candidate) => candidate.key === route.key,
+		);
+		const navigationKeys = new Set(
+			props.state.routes.map((candidate) => candidate.key),
+		);
+		if (!navigationKeys.has(route.key)) return;
+
+		// Retained replacements stay under the incoming screen until it opens.
+		for (const candidate of current.routes.slice(0, Math.max(openedIndex, 0))) {
+			if (
+				!navigationKeys.has(candidate.key) &&
+				!closingRouteKeys.has(candidate.key)
+			) {
+				handleCloseRoute({ route: candidate });
+			}
+		}
+	};
+
 	const requestDismiss = ({ route }: { route: BaseStackRoute }): boolean => {
 		const current = snapshot.state;
 		const routeIndex = current.routes.findIndex(
@@ -150,6 +171,7 @@ export const createBlankStackController = (
 		getSnapshot,
 		update,
 		handleCloseRoute,
+		handleOpenRoute,
 		requestDismiss,
 	};
 };

package/src/providers/stack/blank-stack-state/helpers/build-blank-stack-state.ts

@@ -8,7 +8,6 @@ import type {
 	BaseStackScene,
 	StackSceneActivity,
 } from "../../../../types/stack.types";
-import { isOverlayVisible } from "../../../../utils/overlay/visibility";
 import { resolveSceneNeighbors } from "./navigation/resolve-scene-neighbors";
 import {
 	areDescriptorSourcesEquivalent,
@@ -204,7 +203,9 @@ const buildBaseScenes = ({
 		blankStackDescriptors[route.key] = descriptor;
 
 		if (!shouldShowFloatOverlay) {
-			shouldShowFloatOverlay = isOverlayVisible(sourceDescriptor?.options);
+			const options = sourceDescriptor?.options;
+			shouldShowFloatOverlay =
+				Boolean(options?.overlay) && options?.overlayShown !== false;
 		}
 
 		scenes.push({

package/src/providers/stack/blank-stack-state/helpers/types.ts

@@ -34,6 +34,7 @@ export type BlankStackController = {
 	subscribe: (listener: () => void) => () => void;
 	getSnapshot: () => BlankStackControllerSnapshot;
 	update: (props: BlankStackProviderProps) => void;
+	handleOpenRoute: (payload: { route: BaseStackRoute }) => void;
 	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
 	requestDismiss: (payload: { route: BaseStackRoute }) => boolean;
 };

package/src/providers/stack/blank-stack-state/index.ts

@@ -24,6 +24,7 @@ export const useBlankStackState = (props: BlankStackProviderProps) => {
 	return {
 		state: snapshot.state,
 		handleCloseRoute: controller.handleCloseRoute,
+		handleOpenRoute: controller.handleOpenRoute,
 		requestDismiss: controller.requestDismiss,
 	};
 };

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

@@ -27,14 +27,16 @@ const {
 	StoreProvider: BlankStackStoreProvider,
 	BlankStackProvider,
 	useBlankStackStore,
+	useOptionalBlankStackStore,
 } = createProvider("BlankStack")<
 	InternalBlankStackProviderProps,
 	BlankStackStoreValue
 >(({ state: stackState, children, ...props }) => {
-	const { state, handleCloseRoute, requestDismiss } = useBlankStackState({
-		...props,
-		state: stackState,
-	});
+	const { state, handleCloseRoute, handleOpenRoute, requestDismiss } =
+		useBlankStackState({
+			...props,
+			state: stackState,
+		});
 	const navigatorKey = stackState.key;
 	const focusedIndex = resolvePresentedIndex(
 		state.routes,
@@ -67,10 +69,16 @@ const {
 			requestDismiss,
 			shouldShowFloatOverlay: state.shouldShowFloatOverlay,
 			handleCloseRoute,
+			handleOpenRoute,
 		},
 		children,
 	};
 });
 
 export type { BlankStackProviderProps, BlankStackStoreValue };
-export { BlankStackProvider, BlankStackStoreProvider, useBlankStackStore };
+export {
+	BlankStackProvider,
+	BlankStackStoreProvider,
+	useBlankStackStore,
+	useOptionalBlankStackStore,
+};

package/src/types/animation.types.ts

@@ -171,11 +171,7 @@ export type ScreenTransitionDepthTarget = {
 	depth: number;
 };
 
-export type ScreenTransitionTarget = ScreenTransitionDepthTarget;
-
-export type ScreenTransitionAccessor = (
-	target?: ScreenTransitionTarget,
-) => ScreenInterpolationProps | null;
+export type ScreenTransitionTarget = ScreenTransitionDepthTarget | string;
 
 export interface ScreenInterpolationProps {
 	/**
@@ -237,20 +233,6 @@ export interface ScreenInterpolationProps {
 	 */
 	bounds: BoundsAccessor;
 
-	/**
-	 * Resolves interpolation props for this screen's transition timeline or an
-	 * ancestor/descendant transition timeline.
-	 *
-	 * Calling without a target returns the current transition.
-	 * `transition({ depth: -1 })` returns the immediate parent transition.
-	 * `transition({ depth: 1 })` returns the immediate child transition.
-	 * `transition({ depth: 0 })` returns the current transition.
-	 *
-	 * When called from a returned transition scope, targets are resolved relative
-	 * to that scope.
-	 */
-	transition: ScreenTransitionAccessor;
-
 	/**
 	 * The screen state that is currently driving the transition (either current or next, whichever is focused).
 	 */

package/src/types/bounds.types.ts

@@ -229,9 +229,6 @@ export type BoundsAccessor = (
 	options: BoundsIdentityInput,
 ) => BoundsScopedAccessor;
 
-export type BoundsInterpolationProps = Omit<
-	ScreenInterpolationProps,
-	"bounds" | "transition"
->;
+export type BoundsInterpolationProps = Omit<ScreenInterpolationProps, "bounds">;
 
 export type { BoundsMotion, BoundsMotionFrame, BoundsMotionTransform };

package/src/types/index.ts

@@ -5,7 +5,6 @@ export type {
 	BoundaryHandoffTarget,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
-	ScreenTransitionAccessor,
 	ScreenTransitionDepthTarget,
 	ScreenTransitionOptions,
 	ScreenTransitionState,

package/src/types/ownership.types.ts

@@ -5,7 +5,7 @@
  * 1. Gestures dismiss stacks, not screens
  * 2. Ownership is per-direction (4 independent directions)
  * 3. Shadowing: child claiming same direction blocks parent
- * 4. Inheritance: no local claim walks up tree to find owner
+ * 4. Inheritance: topology resolves the nearest claiming ancestor
  */
 
 /**
@@ -50,28 +50,3 @@ export const NO_CLAIMS: ClaimedDirections = {
 	horizontal: false,
 	"horizontal-inverted": false,
 };
-
-/**
- * Ownership status for a direction relative to the current screen.
- *
- * - 'self': Current screen owns this direction (should activate)
- * - 'ancestor': An ancestor owns this direction (should fail to bubble up)
- * - 'none': No one owns this direction (should fail, no gesture response)
- */
-export type OwnershipStatus = "self" | "ancestor" | "none";
-
-/**
- * Map of ownership status for all four directions.
- * Pre-computed during render for worklet access.
- */
-export type DirectionOwnership = Record<Direction, OwnershipStatus>;
-
-/**
- * Empty ownership - used when no gestures are configured anywhere.
- */
-export const NO_OWNERSHIP: DirectionOwnership = {
-	vertical: "none",
-	"vertical-inverted": "none",
-	horizontal: "none",
-	"horizontal-inverted": "none",
-};

package/src/types/providers/blank-stack-provider.types.ts

@@ -32,5 +32,6 @@ export interface BlankStackStoreValue {
 	focusedIndex: number;
 	requestDismiss?: (payload: { route: BaseStackRoute }) => boolean;
 	shouldShowFloatOverlay: boolean;
+	handleOpenRoute?: (payload: { route: BaseStackRoute }) => void;
 	handleCloseRoute?: (payload: { route: BaseStackRoute }) => void;
 }

package/src/types/screen.types.ts

@@ -57,7 +57,7 @@ export type GestureTracking = "auto" | "never" | "always";
  * A single snap point value. Either a fraction of screen height (0–1) or
  * `'auto'` to snap to the intrinsic height of the screen content.
  */
-export type SnapPoint = number | "auto";
+export type SnapPoint = number | "auto" | (string & {});
 
 export type BackdropBehavior = "block" | "passthrough" | "dismiss" | "collapse";
 
@@ -205,6 +205,16 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 };
 
 export type ScreenTransitionConfig = {
+	/**
+	 * Globally identifies this mounted screen for keyed animation observation.
+	 *
+	 * The key must be unique among mounted screens.
+	 *
+	 * @example
+	 * options={{ transitionKey: "feed" }}
+	 */
+	transitionKey?: string;
+
 	/**
 	 * The user-provided function to calculate styles based on animation progress.
 	 *

package/src/types/stack.types.ts

@@ -1,8 +1,6 @@
 import type { ScreenTransitionConfig } from "./screen.types";
 
-export type StackTransitionOptions = ScreenTransitionConfig & {
-	enableTransitions?: boolean;
-};
+export type StackTransitionOptions = ScreenTransitionConfig;
 
 /**
  * Minimal route shape for navigation utilities.

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

@@ -1,9 +1,7 @@
 import type { SharedValue } from "react-native-reanimated";
 import { FALSE, TRUE } from "../../constants";
-import {
-	type AnimationStoreMap,
-	emitMotionStart,
-} from "../../stores/animation.store";
+import { emitMotionStart } from "../../providers/screen/motion/animation/emit-motion-start";
+import type { MotionAnimationValues } from "../../providers/screen/motion/types";
 import type { TransitionSpec } from "../../types/animation.types";
 import { animate, isSpringAnimationConfig } from "./animate";
 
@@ -16,7 +14,7 @@ interface AnimateToProgressProps {
 	 */
 	target: "open" | "close" | number;
 	spec?: TransitionSpec;
-	animations: AnimationStoreMap;
+	animations: MotionAnimationValues;
 	targetProgress: SharedValue<number>;
 	animationProgress: SharedValue<number>;
 	emitWillAnimate?: boolean;
@@ -27,7 +25,7 @@ interface AnimateToProgressProps {
 }
 
 const setTransitionLifecycleFlags = (
-	animations: AnimationStoreMap,
+	animations: MotionAnimationValues,
 	isClosing: boolean,
 	markEntering: boolean,
 ) => {

package/src/utils/create-provider.tsx

@@ -19,7 +19,8 @@
  *
  * Providers created with `global: true` return a `key` from their factory.
  * Both generated store hooks accept that key to subscribe to the original
- * provider store from outside its React context.
+ * provider store from outside its React context. Arrays of keys return ordered
+ * snapshots (null for unmounted keys) and apply the selector to each store.
  */
 import {
 	createContext,
@@ -37,6 +38,11 @@ type ProviderStoreHook<ContextValue> = {
 };
 
 type GlobalProviderStoreHook<ContextValue> = {
+	(keys: readonly string[]): readonly (ContextValue | null)[];
+	<Selected>(
+		keys: readonly string[],
+		selector: (value: ContextValue) => Selected,
+	): readonly (Selected | null)[];
 	(key: string): ContextValue;
 	<Selected>(
 		key: string,
@@ -50,6 +56,11 @@ type OptionalProviderStoreHook<ContextValue> = {
 };
 
 type OptionalGlobalProviderStoreHook<ContextValue> = {
+	(keys: readonly string[]): readonly (ContextValue | null)[];
+	<Selected>(
+		keys: readonly string[],
+		selector: (value: ContextValue) => Selected,
+	): readonly (Selected | null)[];
 	(key: string | null): ContextValue | null;
 	<Selected>(
 		key: string | null,
@@ -74,7 +85,6 @@ type ResolvedOptionalProviderStoreHook<
 type ProviderFactoryResult<ContextValue, Global extends boolean> = {
 	value: ContextValue;
 	children?: ReactNode;
-	unregisterOnCleanup?: boolean;
 } & (Global extends true ? { key: string } : { key?: never });
 
 interface ProviderStoreApi<ContextValue> {
@@ -227,54 +237,96 @@ export default function createProvider<
 			required: boolean,
 			selectorOrKey?:
 				| string
+				| readonly string[]
 				| null
 				| ((value: ContextValue | null) => Selected),
 			globalSelector?: (value: ContextValue) => Selected,
-		): Selected | ContextValue | null => {
+		):
+			| Selected
+			| ContextValue
+			| null
+			| readonly (Selected | ContextValue | null)[] => {
+			const keys =
+				global && Array.isArray(selectorOrKey)
+					? (selectorOrKey as readonly string[])
+					: null;
 			const isGlobalLookup =
-				global && (typeof selectorOrKey === "string" || selectorOrKey === null);
-			const key = isGlobalLookup ? selectorOrKey : null;
+				global &&
+				(keys !== null ||
+					typeof selectorOrKey === "string" ||
+					selectorOrKey === null);
+			const key =
+				isGlobalLookup && typeof selectorOrKey === "string"
+					? selectorOrKey
+					: null;
 			const selector = (isGlobalLookup ? globalSelector : selectorOrKey) as
 				| ((value: ContextValue | null) => Selected)
 				| undefined;
 			const contextStore = useContext(StoreContext);
+			const selectionCache = useRef<
+				readonly (Selected | ContextValue | null)[]
+			>([]);
 			const selectorRef = useRef(selector);
 			selectorRef.current = selector;
-			const getStore = useCallback(() => {
-				if (isGlobalLookup) {
-					return key !== null && globalRegistry
-						? globalRegistry.getStore(key)
-						: null;
-				}
+			const getStore = useCallback(
+				(lookupKey: string | null = key) => {
+					if (isGlobalLookup) {
+						return lookupKey !== null && globalRegistry
+							? globalRegistry.getStore(lookupKey)
+							: null;
+					}
 
-				return contextStore;
-			}, [contextStore, isGlobalLookup, key]);
+					return contextStore;
+				},
+				[contextStore, isGlobalLookup, key],
+			);
 			const subscribe = useCallback(
 				(listener: () => void) => {
-					let unsubscribeStore = (
-						getStore() ?? (NullProviderStore as ProviderStoreApi<ContextValue>)
-					).subscribe(listener);
-					const unsubscribeRegistry =
-						isGlobalLookup && key !== null && globalRegistry
-							? globalRegistry.subscribe(key, () => {
-									unsubscribeStore();
-									unsubscribeStore = (
-										getStore() ??
-										(NullProviderStore as ProviderStoreApi<ContextValue>)
-									).subscribe(listener);
-									listener();
-								})
-							: () => {};
-
+					const cleanups = (keys ?? [key]).map((lookupKey) => {
+						let unsubscribeStore = (
+							getStore(lookupKey) ?? NullProviderStore
+						).subscribe(listener);
+						const unsubscribeRegistry =
+							isGlobalLookup && lookupKey !== null && globalRegistry
+								? globalRegistry.subscribe(lookupKey, () => {
+										unsubscribeStore();
+										unsubscribeStore = (
+											getStore(lookupKey) ?? NullProviderStore
+										).subscribe(listener);
+										listener();
+									})
+								: undefined;
+						return () => {
+							unsubscribeRegistry?.();
+							unsubscribeStore();
+						};
+					});
 					return () => {
-						unsubscribeRegistry();
-						unsubscribeStore();
+						for (const cleanup of cleanups) cleanup();
 					};
 				},
-				[getStore, isGlobalLookup, key],
+				[getStore, isGlobalLookup, key, keys],
 			);
 
 			const getSelectedSnapshot = useCallback(() => {
+				if (keys) {
+					const selected = keys.map((lookupKey) => {
+						const snapshot = getStore(lookupKey)?.getSnapshot() ?? null;
+						return snapshot !== null && selectorRef.current
+							? selectorRef.current(snapshot)
+							: snapshot;
+					});
+					if (
+						selected.length !== selectionCache.current.length ||
+						selected.some(
+							(value, index) =>
+								!Object.is(value, selectionCache.current[index]),
+						)
+					) {
+						selectionCache.current = selected;
+					}
+					return selectionCache.current;
+				}
 				const snapshot = getStore()?.getSnapshot() ?? null;
 
 				if (required && snapshot === null) {
@@ -292,7 +344,7 @@ export default function createProvider<
 				return typeof selectorRef.current === "function"
 					? selectorRef.current(snapshot)
 					: snapshot;
-			}, [getStore, isGlobalLookup, key, required]);
+			}, [getStore, isGlobalLookup, key, keys, required]);
 
 			return useSyncExternalStore(
 				subscribe,
@@ -303,18 +355,23 @@ export default function createProvider<
 		const useOptionalStoreSelector = <Selected,>(
 			selectorOrKey?:
 				| string
+				| readonly string[]
 				| null
 				| ((value: ContextValue | null) => Selected),
 			globalSelector?: (value: ContextValue) => Selected,
 		) => useStoreSelection(false, selectorOrKey, globalSelector);
 		const useStoreSelector = <Selected,>(
-			selectorOrKey?: string | ((value: ContextValue) => Selected),
+			selectorOrKey?:
+				| string
+				| readonly string[]
+				| ((value: ContextValue) => Selected),
 			globalSelector?: (value: ContextValue) => Selected,
 		) =>
 			useStoreSelection(
 				true,
 				selectorOrKey as
 					| string
+					| readonly string[]
 					| ((value: ContextValue | null) => Selected)
 					| undefined,
 				globalSelector,
@@ -323,21 +380,17 @@ export default function createProvider<
 			children,
 			registerGlobally = true,
 			storeKey,
-			unregisterOnCleanup = true,
 			value,
 		}: {
 			children?: ReactNode;
 			registerGlobally?: boolean;
 			storeKey?: string;
-			unregisterOnCleanup?: boolean;
 			value: ContextValue;
 		}) => {
 			const storeRef = useRef<MutableProviderStoreApi<ContextValue> | null>(
 				null,
 			);
 			const pendingNotifyRef = useRef(false);
-			const unregisterOnCleanupRef = useRef(unregisterOnCleanup);
-			unregisterOnCleanupRef.current = unregisterOnCleanup;
 
 			if (storeRef.current === null) {
 				storeRef.current = createProviderStore<ContextValue>(value);
@@ -355,13 +408,7 @@ export default function createProvider<
 					);
 				}
 
-				const unregister = globalRegistry.register(storeKey, store);
-
-				return () => {
-					if (unregisterOnCleanupRef.current) {
-						unregister();
-					}
-				};
+				return globalRegistry.register(storeKey, store);
 			}, [registerGlobally, storeKey, store]);
 
 			pendingNotifyRef.current =
@@ -382,32 +429,79 @@ export default function createProvider<
 		};
 		StoreProvider.displayName = `${name}StoreProvider`;
 
-		const Provider: React.FC<ProviderProps> = (props) => {
+		const OwnedProvider: React.FC<ProviderProps> = (props) => {
 			const {
 				children = (props as { children?: ReactNode }).children,
 				key,
-				unregisterOnCleanup,
 				value,
 			} = factory(props);
 			return (
-				<StoreProvider
-					storeKey={key}
-					unregisterOnCleanup={unregisterOnCleanup}
-					value={value}
-				>
+				<StoreProvider storeKey={key} value={value}>
 					{children}
 				</StoreProvider>
 			);
 		};
+		type ReuseProps = { screenKey: string; children?: ReactNode };
+		const ReusedProvider = ({ screenKey, children }: ReuseProps) => {
+			const retainedStore = useRef<ProviderStoreApi<ContextValue> | null>(null);
+			const subscribe = useCallback(
+				(listener: () => void) =>
+					globalRegistry?.subscribe(screenKey, listener) ??
+					NullProviderStore.subscribe(listener),
+				[screenKey],
+			);
+			const getSnapshot = useCallback(
+				() => globalRegistry?.getStore(screenKey) ?? null,
+				[screenKey],
+			);
+			const registeredStore = useSyncExternalStore(
+				subscribe,
+				getSnapshot,
+				getSnapshot,
+			);
+			// Keep the same context alive while a departing screen's overlay finishes.
+			if (registeredStore) retainedStore.current = registeredStore;
+			const store = registeredStore ?? retainedStore.current;
+			return store ? (
+				<StoreContext.Provider value={store}>{children}</StoreContext.Provider>
+			) : null;
+		};
+		type Props = ProviderProps | (Global extends true ? ReuseProps : never);
+		const Provider: React.FC<Props> = (props) => {
+			if (
+				global &&
+				"screenKey" in props &&
+				typeof props.screenKey === "string"
+			) {
+				return (
+					<ReusedProvider key={props.screenKey} screenKey={props.screenKey}>
+						{(props as ReuseProps).children}
+					</ReusedProvider>
+				);
+			}
+			return <OwnedProvider {...(props as ProviderProps)} />;
+		};
 		Provider.displayName = providerDisplayName;
 
+		const getStore = (key: string): ContextValue => {
+			const value = globalRegistry?.getStore(key)?.getSnapshot();
+			if (value === null || value === undefined)
+				throw new Error(`${name}Store is unavailable for key "${key}"`);
+			return value;
+		};
+
 		return {
 			StoreProvider,
+			...(global ? { [`get${name}Store`]: getStore } : {}),
 			[`${name}Provider`]: Provider,
 			[`useOptional${name}Store`]: useOptionalStoreSelector,
 			[`use${name}Store`]: useStoreSelector,
-		} as { StoreProvider: typeof StoreProvider } & {
-			[P in ProviderName as `${P}Provider`]: React.FC<ProviderProps>;
+		} as (Global extends true
+			? {
+					[P in ProviderName as `get${P}Store`]: (key: string) => ContextValue;
+				}
+			: unknown) & { StoreProvider: typeof StoreProvider } & {
+			[P in ProviderName as `${P}Provider`]: React.FC<Props>;
 		} & {
 			[P in ProviderName as `useOptional${P}Store`]: ResolvedOptionalProviderStoreHook<
 				ContextValue,