react-native-screen-transitions 4.0.0-alpha.2 → 4.0.0-alpha.3

package/src/providers/stack/core.provider.tsx

@@ -1,5 +1,4 @@
-import * as React from "react";
-import { useMemo } from "react";
+import { memo, type ReactNode, useContext, useMemo } from "react";
 import { Dimensions, Platform, StyleSheet, View } from "react-native";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import {
@@ -19,7 +18,7 @@ export interface StackCoreConfig {
 
 interface StackCoreProviderProps {
 	config: StackCoreConfig;
-	children: React.ReactNode;
+	children: ReactNode;
 }
 
 export interface StackCoreContextValue {
@@ -41,8 +40,12 @@ const initialSafeAreaMetrics =
 			}
 		: initialWindowMetrics;
 
-function StackSafeAreaProvider({ children }: { children: React.ReactNode }) {
-	const insets = React.useContext(SafeAreaInsetsContext);
+const StackSafeAreaProvider = memo(function StackSafeAreaProvider({
+	children,
+}: {
+	children: ReactNode;
+}) {
+	const insets = useContext(SafeAreaInsetsContext);
 
 	if (insets) {
 		return <View style={styles.container}>{children}</View>;
@@ -56,86 +59,57 @@ function StackSafeAreaProvider({ children }: { children: React.ReactNode }) {
 			{children}
 		</SafeAreaProvider>
 	);
-}
+});
 
-const { StackCoreProvider: InternalStackCoreProvider, useStackCoreContext } =
-	createProvider("StackCore", { guarded: true })<
-		StackCoreProviderProps,
-		StackCoreContextValue
-	>(({ config, children }) => {
-		const {
-			TRANSITIONS_ALWAYS_ON = false,
-			DISABLE_NATIVE_SCREENS = false,
-			DISABLE_NATIVE_SCREEN_CONTAINER = false,
-			STACK_TYPE = StackType.BLANK,
-		} = config;
+const StackCoreRoot = memo(function StackCoreRoot({
+	children,
+	stackType,
+}: {
+	children: ReactNode;
+	stackType: StackType;
+}) {
+	return (
+		<GestureHandlerRootView
+			style={styles.container}
+			pointerEvents={stackType === StackType.COMPONENT ? "box-none" : undefined}
+		>
+			<StackSafeAreaProvider>{children}</StackSafeAreaProvider>
+		</GestureHandlerRootView>
+	);
+});
 
-		const flags = useMemo(
-			() => ({
-				TRANSITIONS_ALWAYS_ON,
-				STACK_TYPE,
-				DISABLE_NATIVE_SCREENS,
-				DISABLE_NATIVE_SCREEN_CONTAINER,
-			}),
-			[
-				TRANSITIONS_ALWAYS_ON,
-				STACK_TYPE,
-				DISABLE_NATIVE_SCREENS,
-				DISABLE_NATIVE_SCREEN_CONTAINER,
-			],
-		);
+export const { StackCoreProvider, useStackCoreStore } = createProvider(
+	"StackCore",
+	{ guarded: true },
+)<StackCoreProviderProps, StackCoreContextValue>(({ config, children }) => {
+	const {
+		TRANSITIONS_ALWAYS_ON = false,
+		DISABLE_NATIVE_SCREENS = false,
+		DISABLE_NATIVE_SCREEN_CONTAINER = false,
+		STACK_TYPE = StackType.BLANK,
+	} = config;
 
-		return {
-			value: { flags },
-			children: (
-				<GestureHandlerRootView
-					style={styles.container}
-					pointerEvents={
-						STACK_TYPE === StackType.COMPONENT ? "box-none" : undefined
-					}
-				>
-					<StackSafeAreaProvider>{children}</StackSafeAreaProvider>
-				</GestureHandlerRootView>
-			),
-		};
-	});
+	const flags = useMemo(
+		() => ({
+			TRANSITIONS_ALWAYS_ON,
+			STACK_TYPE,
+			DISABLE_NATIVE_SCREENS,
+			DISABLE_NATIVE_SCREEN_CONTAINER,
+		}),
+		[
+			TRANSITIONS_ALWAYS_ON,
+			STACK_TYPE,
+			DISABLE_NATIVE_SCREENS,
+			DISABLE_NATIVE_SCREEN_CONTAINER,
+		],
+	);
 
-/**
- * HOC that wraps a component with the StackCore provider.
- * Just a simple open gate
- */
-export function withStackCore<TProps extends object>(
-	defaultConfig: StackCoreConfig,
-	Component: React.ComponentType<TProps>,
-): React.FC<TProps & StackCoreConfig> {
-	return function StackCoreWrapper({
-		DISABLE_NATIVE_SCREENS,
-		DISABLE_NATIVE_SCREEN_CONTAINER,
-		TRANSITIONS_ALWAYS_ON,
-		STACK_TYPE,
-		...props
-	}: TProps & StackCoreConfig) {
-		// Start from defaults, then apply explicit overrides from the caller.
-		const config: StackCoreConfig = {
-			TRANSITIONS_ALWAYS_ON:
-				TRANSITIONS_ALWAYS_ON ?? defaultConfig.TRANSITIONS_ALWAYS_ON,
-			STACK_TYPE: STACK_TYPE ?? defaultConfig.STACK_TYPE,
-			DISABLE_NATIVE_SCREENS:
-				DISABLE_NATIVE_SCREENS ?? defaultConfig.DISABLE_NATIVE_SCREENS,
-			DISABLE_NATIVE_SCREEN_CONTAINER:
-				DISABLE_NATIVE_SCREEN_CONTAINER ??
-				defaultConfig.DISABLE_NATIVE_SCREEN_CONTAINER,
-		};
-		return (
-			<InternalStackCoreProvider config={config}>
-				<Component {...(props as TProps)} />
-			</InternalStackCoreProvider>
-		);
+	return {
+		value: { flags },
+		children: <StackCoreRoot stackType={STACK_TYPE}>{children}</StackCoreRoot>,
 	};
-}
+});
 
 const styles = StyleSheet.create({
 	container: { flex: 1 },
 });
-
-export { useStackCoreContext };

package/src/providers/stack/direct.provider.tsx

@@ -1,5 +1,4 @@
-import type * as React from "react";
-import { useMemo } from "react";
+import { type ReactNode, useMemo } from "react";
 import {
 	type StackContextValue,
 	StackProvider,
@@ -10,16 +9,34 @@ import type {
 	DirectStackProps,
 	DirectStackScene,
 } from "../../types/providers/direct-stack.types";
+import createProvider from "../../utils/create-provider";
 import { isOverlayVisible } from "../../utils/overlay/visibility";
-import { useStackCoreContext } from "./core.provider";
+import { useStackCoreStore } from "./core.provider";
 
-function useDirectStackValue(
-	props: DirectStackProps,
-): DirectStackContextValue & { stackContextValue: StackContextValue } {
-	const { state, navigation, descriptors, describe } = props;
-	const { flags } = useStackCoreContext();
-	const navigatorKey = state.key;
+type DirectStackProviderProps = DirectStackProps & {
+	children: ReactNode;
+};
+
+type DirectStackStoreProviderProps = {
+	children: ReactNode;
+	value: DirectStackContextValue;
+};
 
+const { DirectStackProvider: DirectStackStoreProvider, useDirectStackStore } =
+	createProvider("DirectStack", { guarded: true })<
+		DirectStackStoreProviderProps,
+		DirectStackContextValue
+	>(({ children, value }) => ({ children, value }));
+
+function DirectStackProvider({
+	state,
+	navigation,
+	descriptors,
+	describe,
+	children,
+}: DirectStackProviderProps) {
+	const flags = useStackCoreStore((store) => store.flags);
+	const navigatorKey = state.key;
 	const preloadedDescriptors = useMemo(() => {
 		return state.preloadedRoutes.reduce<DirectStackDescriptorMap>(
 			(acc, route) => {
@@ -41,23 +58,40 @@ function useDirectStackValue(
 			};
 			let shouldShowFloatOverlay = false;
 
-			for (const route of allRoutes) {
+			for (let index = 0; index < allRoutes.length; index++) {
+				const route = allRoutes[index];
+				if (!route) {
+					throw new Error(`Missing stack route at index ${index}.`);
+				}
 				const descriptor = allDescriptors[route.key];
+
+				if (!descriptor) {
+					throw new Error(`Missing descriptor for route "${route.key}".`);
+				}
+
 				const isPreloaded =
 					preloadedDescriptors[route.key] !== undefined &&
 					descriptors[route.key] === undefined;
 
-				scenes.push({ route, descriptor, isPreloaded });
+				scenes.push({
+					activity:
+						index === state.index
+							? "active"
+							: index === state.index - 1
+								? "inert"
+								: "inactive",
+					route,
+					descriptor,
+					isPreloaded,
+				});
 				routeKeys.push(route.key);
 
-				if (!shouldShowFloatOverlay && descriptor) {
-					const options = descriptor.options;
-					if (
-						options?.enableTransitions === true &&
-						isOverlayVisible(options)
-					) {
-						shouldShowFloatOverlay = true;
-					}
+				if (
+					!shouldShowFloatOverlay &&
+					descriptor.options?.enableTransitions === true &&
+					isOverlayVisible(descriptor.options)
+				) {
+					shouldShowFloatOverlay = true;
 				}
 			}
 
@@ -70,13 +104,13 @@ function useDirectStackValue(
 		}, [
 			state.routes,
 			state.preloadedRoutes,
+			state.index,
 			preloadedDescriptors,
 			descriptors,
 		]);
 
 	const focusedIndex = state.index;
-
-	const stackContextValue = useMemo<StackContextValue>(
+	const stackValue = useMemo<StackContextValue>(
 		() => ({
 			flags,
 			navigatorKey,
@@ -87,43 +121,28 @@ function useDirectStackValue(
 		}),
 		[flags, navigatorKey, routeKeys, allRoutes, scenes, focusedIndex],
 	);
+	const directStackValue = {
+		state,
+		navigation,
+		descriptors,
+		scenes,
+		focusedIndex,
+		shouldShowFloatOverlay,
+	};
 
-	// DirectStack context value
-	const lifecycleValue = useMemo<DirectStackContextValue>(
-		() => ({
-			state,
-			navigation,
-			descriptors,
-			scenes,
-			focusedIndex,
-			shouldShowFloatOverlay,
-		}),
-		[
-			state,
-			navigation,
-			descriptors,
-			scenes,
-			focusedIndex,
-			shouldShowFloatOverlay,
-		],
+	return (
+		<StackProvider value={stackValue}>
+			<DirectStackStoreProvider value={directStackValue}>
+				{children}
+			</DirectStackStoreProvider>
+		</StackProvider>
 	);
-
-	return { ...lifecycleValue, stackContextValue };
 }
 
-function withDirectStack<TProps extends DirectStackProps>(
-	Component: React.ComponentType<DirectStackContextValue>,
-): React.FC<TProps> {
-	return function DirectStackProvider(props: TProps) {
-		const { stackContextValue, ...lifecycleValue } = useDirectStackValue(props);
-
-		return (
-			<StackProvider value={stackContextValue}>
-				<Component {...lifecycleValue} />
-			</StackProvider>
-		);
-	};
-}
-
-export type { DirectStackContextValue, DirectStackProps, DirectStackScene };
-export { withDirectStack };
+export type {
+	DirectStackContextValue,
+	DirectStackProps,
+	DirectStackProviderProps,
+	DirectStackScene,
+};
+export { DirectStackProvider, useDirectStackStore };

package/src/stores/animation.store.ts

@@ -3,6 +3,8 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
+import { FALSE, TRUE } from "../constants";
+import { emit } from "../utils/animation/emit";
 import { createStore } from "../utils/create-store";
 
 export type AnimationStoreMap = {
@@ -16,6 +18,23 @@ export type AnimationStoreMap = {
 	entering: SharedValue<number>;
 };
 
+export const emitMotionStart = (animations: AnimationStoreMap) => {
+	"worklet";
+
+	animations.progressSettled.set(FALSE);
+
+	if (animations.progressAnimating.get()) {
+		return false;
+	}
+
+	emit(animations.willAnimate, TRUE, FALSE);
+	requestAnimationFrame(() => {
+		"worklet";
+		animations.progressAnimating.set(TRUE);
+	});
+	return true;
+};
+
 function createAnimationBag(): AnimationStoreMap {
 	return {
 		transitionProgress: makeMutable(0),

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

@@ -12,7 +12,6 @@ import type {
 } from "@react-navigation/native";
 import type { OverlayProps } from "./overlay.types";
 import type { InactiveBehavior, ScreenTransitionConfig } from "./screen.types";
-import type { StackSceneActivity } from "./stack.types";
 
 export type { InactiveBehavior } from "./screen.types";
 
@@ -141,6 +140,4 @@ export type BlankStackDescriptor = Descriptor<
 	BlankStackNavigationOptions,
 	BlankStackNavigationProp<ParamListBase>,
 	RouteProp<ParamListBase>
-> & {
-	activity: StackSceneActivity;
-};
+>;

package/src/types/gesture.types.ts

@@ -222,8 +222,14 @@ export type GestureValues = {
 	raw: RawGestureValues;
 	/**
 	 * The gesture that is currently active.
+	 *
+	 * @deprecated Use `initiator` for the accepted activation identity.
 	 */
 	active: ActiveGesture | null;
+	/**
+	 * The accepted activation identity for the current gesture attempt.
+	 */
+	initiator: ActiveGesture | "none";
 	/**
 	 * The initial pan direction that activated the gesture.
 	 *
@@ -240,6 +246,9 @@ export type GestureValues = {
 	handoff: GestureHandoffValues;
 	/**
 	 * A flag indicating if the screen is in the process of dismissing (0 or 1).
+	 *
+	 * @deprecated Use `closing` for public screen lifecycle state. Release handoff
+	 * details do not have a public replacement.
 	 */
 	dismissing: number;
 	/**
@@ -248,6 +257,8 @@ export type GestureValues = {
 	dragging: number;
 	/**
 	 * A flag indicating if released gesture values are animating back to neutral.
+	 *
+	 * @deprecated Use `animating` or `settled` for public motion state.
 	 */
 	settling: number;
 	/** @deprecated Use `normX` instead. */

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

@@ -1,4 +1,3 @@
-import type { StackContextValue } from "../../hooks/navigation/use-stack";
 import type {
 	BaseStackDescriptor,
 	BaseStackNavigation,
@@ -10,7 +9,7 @@ import type {
 
 /**
  * Props for blank stack - generic over descriptor and navigation types.
- * Defaults to base types for backward compatibility.
+ * Defaults to the shared base types.
  */
 export interface BlankStackProviderProps<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
@@ -29,29 +28,16 @@ export interface BlankStackProviderProps<
  * Context value for blank stack — only fields unique to blank stack lifecycle.
  * Shared fields (routes, scenes, etc.) live in StackContext.
  */
-export interface BlankStackProviderContextValue {
-	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
-}
-
-/**
- * Props passed to the render child of `withBlankStack`.
- * Only the fields that stack-view components actually consume.
- */
-export interface BlankStackProviderRenderProps<
+export interface BlankStackStoreValue<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
+	navigatorKey: string;
+	routeKeys: string[];
+	routes: TDescriptor["route"][];
 	scenes: BaseStackScene<TDescriptor>[];
+	scenesByKey: Record<string, BaseStackScene<TDescriptor>>;
 	focusedIndex: number;
+	requestDismiss: (payload: { route: BaseStackRoute }) => boolean;
 	shouldShowFloatOverlay: boolean;
-}
-
-/**
- * Internal result shape returned by useBlankStackProviderValue.
- */
-export interface BlankStackProviderResult<
-	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
-> {
-	stackContextValue: StackContextValue;
-	blankStackProviderContextValue: BlankStackProviderContextValue;
-	renderProps: BlankStackProviderRenderProps<TDescriptor>;
+	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
 }

package/src/types/providers/direct-stack.types.ts

@@ -8,7 +8,7 @@ import type {
 	StackNavigationState,
 } from "@react-navigation/native";
 import type { ScreenTransitionConfig } from "../screen.types";
-import type { DescriptorMap } from "../stack.types";
+import type { DescriptorMap, StackSceneActivity } from "../stack.types";
 
 export type DirectStackNavigationEventMap = {};
 
@@ -44,6 +44,7 @@ export type DirectStackDescriptor = Descriptor<
 export type DirectStackDescriptorMap = DescriptorMap<DirectStackDescriptor>;
 
 export interface DirectStackScene {
+	activity: StackSceneActivity;
 	route: StackNavigationState<ParamListBase>["routes"][number];
 	descriptor: DirectStackDescriptor;
 	isPreloaded: boolean;

package/src/types/screen.types.ts

@@ -169,38 +169,6 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * }
 	 */
 	styleId?: string;
-
-	/**
-	 * Marks this component for measurement to enable shared element transitions.
-	 * Components with the same tag across different screens will animate between each other.
-	 *
-	 * @example
-	 * // Screen A:
-	 * <Transition.View sharedBoundTag="profile-avatar">
-	 *   <Avatar size="small" />
-	 * </Transition.View>
-	 *
-	 * // Screen B:
-	 * <Transition.View sharedBoundTag="profile-avatar">
-	 *   <Avatar size="large" />
-	 * </Transition.View>
-	 *
-	 * @deprecated Use `Transition.Boundary` with `id` instead.
-	 */
-	sharedBoundTag?: string;
-
-	/**
-	 * Re-measures this component when the screen regains focus and updates
-	 * any matching shared-bound source link in place.
-	 *
-	 * Useful when layout can change while unfocused (for example, programmatic
-	 * ScrollView/FlatList scrolling triggered from another screen).
-	 *
-	 * @deprecated Legacy `sharedBoundTag` refresh option. The boundary
-	 * measurement pipeline refreshes layout through `Transition.Boundary`.
-	 * @default false
-	 */
-	remeasureOnFocus?: boolean;
 };
 
 export type ScreenTransitionConfig = {

package/src/types/stack.types.ts

@@ -47,15 +47,12 @@ 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;
-};
+> = TDescriptor;
 
 /**
  * Base scene interface - route + descriptor pair.
@@ -64,6 +61,7 @@ export type StackDescriptorSource<
 export interface BaseStackScene<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
+	activity: StackSceneActivity;
 	route: TDescriptor["route"];
 	descriptor: TDescriptor;
 	previousDescriptor?: TDescriptor;

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

@@ -1,7 +1,10 @@
 import type { SharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 import { FALSE, TRUE } from "../../constants";
-import type { AnimationStoreMap } from "../../stores/animation.store";
+import {
+	type AnimationStoreMap,
+	emitMotionStart,
+} from "../../stores/animation.store";
 import type { TransitionSpec } from "../../types/animation.types";
 import { animate, isSpringAnimationConfig } from "./animate";
 
@@ -22,6 +25,7 @@ interface AnimateToProgressProps {
 	markEntering?: boolean;
 	/** Optional initial velocity for spring-based progress (units: progress/sec). */
 	initialVelocity?: number;
+	isDragging?: SharedValue<number>;
 }
 
 const setTransitionLifecycleFlags = (
@@ -65,6 +69,7 @@ export const animateToProgress = ({
 	emitWillAnimate = true,
 	markEntering = true,
 	initialVelocity,
+	isDragging,
 }: AnimateToProgressProps) => {
 	"worklet";
 
@@ -83,15 +88,10 @@ export const animateToProgress = ({
 			? { ...config, velocity: initialVelocity }
 			: config;
 
-	const {
-		transitionProgress,
-		willAnimate,
-		progressAnimating,
-		progressSettled,
-		entering,
-	} = animations;
+	const { transitionProgress, progressAnimating, progressSettled, entering } =
+		animations;
 
-	const startAnimation = () => {
+	const startAnimation = (activateMotion: boolean) => {
 		"worklet";
 		const { from: animationProgressFrom, to: animationProgressTo } =
 			resolveAnimationProgressRange(transitionProgress.get(), value);
@@ -119,7 +119,9 @@ export const animateToProgress = ({
 			return;
 		}
 
-		progressAnimating.set(TRUE); //<-- Do not move this into the callback
+		if (activateMotion) {
+			progressAnimating.set(TRUE);
+		}
 		progressSettled.set(FALSE);
 		transitionProgress.set(
 			animate(
@@ -127,11 +129,10 @@ export const animateToProgress = ({
 				effectiveConfig,
 				(state) => {
 					"worklet";
-					if (state.settled) {
-						progressSettled.set(TRUE);
-					}
-
 					if (!state.finished) return;
+					if (isDragging?.get()) return;
+
+					progressSettled.set(TRUE);
 
 					animationProgress.set(animationProgressTo);
 
@@ -176,14 +177,13 @@ export const animateToProgress = ({
 	if (emitWillAnimate) {
 		setTransitionLifecycleFlags(animations, isClosing, markEntering);
 
-		willAnimate.set(TRUE);
+		emitMotionStart(animations);
 		requestAnimationFrame(() => {
 			"worklet";
-			willAnimate.set(FALSE);
-			startAnimation();
+			startAnimation(false);
 		});
 		return;
 	}
 
-	startAnimation();
+	startAnimation(true);
 };

package/src/utils/bounds/helpers/create-bounds-accessor-core.ts

@@ -1,3 +1,4 @@
+import { NO_STYLES } from "../../../constants";
 import type {
 	BoundsAccessor,
 	BoundsInterpolationProps,
@@ -64,6 +65,12 @@ const createBoundsAccessorParts = ({
 		const scoped: BoundsScopedAccessor = {
 			styles: (options?: BoundsComputeOptions): BoundsStyleResult => {
 				"worklet";
+				// Keep the component at its base layout for pre-animation refresh
+				// measurement, then remove generated styles again after settlement.
+				if (!props.active.animating) {
+					return NO_STYLES;
+				}
+
 				return prepareBoundStyles({
 					props,
 					options: {