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

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/stores/bounds/internals/links.ts

@@ -215,11 +215,12 @@ const writeDestination = (
 	bounds: MeasuredDimensions,
 	styles: StyleProps,
 	group?: GroupKey,
+	runtimeFlags: BoundaryRuntimeFlags = {},
 ) => {
 	"worklet";
 	const existingLink = getPairLink(state, pairKey, linkKey);
 
-	const destination = createLinkSide(screenKey, bounds, styles);
+	const destination = createLinkSide(screenKey, bounds, styles, runtimeFlags);
 	const link =
 		existingLink ??
 		({
@@ -296,12 +297,22 @@ function setDestination(
 	bounds: MeasuredDimensions,
 	styles: StyleProps = {},
 	group?: GroupKey,
+	runtimeFlags: BoundaryRuntimeFlags = {},
 ) {
 	"worklet";
 	pairs.modify(<T extends LinkPairsState>(state: T): T => {
 		"worklet";
 		const linkKey = getLinkKeyFromTag(tag);
-		writeDestination(state, pairKey, linkKey, screenKey, bounds, styles, group);
+		writeDestination(
+			state,
+			pairKey,
+			linkKey,
+			screenKey,
+			bounds,
+			styles,
+			group,
+			runtimeFlags,
+		);
 
 		return state;
 	});

package/src/stores/scroll.store.ts

@@ -137,6 +137,29 @@ export const getClampedScrollAxisDelta = (
 	return currentOffset - capturedOffset;
 };
 
+/**
+ * Visual scroll travel from a bounds snapshot normalized to its at-rest
+ * position. The captured side is clamped because measurement removes transient
+ * rubber-band displacement; the current side stays raw so consumers can follow
+ * the position that is actually visible on iOS.
+ */
+export const getVisualScrollAxisDelta = (
+	current: ScrollMetadataState | null | undefined,
+	captured: ScrollMetadataState | null | undefined,
+	axis: ScrollGestureAxis,
+): number => {
+	"worklet";
+
+	const currentAxisState = current?.[axis];
+	const capturedOffset = clampScrollAxisOffset(captured?.[axis]);
+
+	if (!currentAxisState || capturedOffset === null) {
+		return 0;
+	}
+
+	return currentAxisState.offset - capturedOffset;
+};
+
 /**
  * Route-keyed scroll geometry used by gesture activation and bounds measurement.
  * Coordination tracks gesture-owner scoped ScrollView offsets and dimensions;

package/src/stores/system.store.ts

@@ -16,6 +16,12 @@ export enum LifecycleTransitionRequestKind {
 type SystemStoreState = {
 	targetProgress: SharedValue<number>;
 
+	/**
+	 * Directional linear clock for the active progress animation. Increasing
+	 * animations run 0 -> 1; decreasing animations run 1 -> 0.
+	 */
+	animationProgress: SharedValue<number>;
+
 	/**
 	 * Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured.
 	 */
@@ -67,6 +73,7 @@ export type SystemStoreMap = SystemStoreState & {
 export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 	createBag: () => ({
 		targetProgress: makeMutable(1),
+		animationProgress: makeMutable(0),
 		resolvedAutoSnapPoint: makeMutable(-1),
 		measuredContentLayout: makeMutable<Layout | null>(null),
 		pendingLifecycleRequestKind: makeMutable<LifecycleTransitionRequestKind>(
@@ -77,6 +84,7 @@ export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 	}),
 	disposeBag: (bag) => {
 		cancelAnimation(bag.targetProgress);
+		cancelAnimation(bag.animationProgress);
 		cancelAnimation(bag.resolvedAutoSnapPoint);
 		cancelAnimation(bag.measuredContentLayout);
 		cancelAnimation(bag.pendingLifecycleRequestKind);

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";
 
@@ -17,10 +20,12 @@ interface AnimateToProgressProps {
 	onAnimationFinish?: (finished: boolean) => void;
 	animations: AnimationStoreMap;
 	targetProgress: SharedValue<number>;
+	animationProgress: SharedValue<number>;
 	emitWillAnimate?: boolean;
 	markEntering?: boolean;
 	/** Optional initial velocity for spring-based progress (units: progress/sec). */
 	initialVelocity?: number;
+	isDragging?: SharedValue<number>;
 }
 
 const setTransitionLifecycleFlags = (
@@ -36,20 +41,35 @@ const setTransitionLifecycleFlags = (
 		return;
 	}
 
+	animations.closing.set(FALSE);
+
 	if (markEntering) {
 		animations.entering.set(TRUE);
 	}
 };
 
+export const resolveAnimationProgressRange = (
+	currentProgress: number,
+	targetProgress: number,
+) => {
+	"worklet";
+	return {
+		from: Math.min(1, Math.max(0, currentProgress)),
+		to: targetProgress,
+	};
+};
+
 export const animateToProgress = ({
 	target,
 	spec,
 	onAnimationFinish,
 	animations,
 	targetProgress,
+	animationProgress,
 	emitWillAnimate = true,
 	markEntering = true,
 	initialVelocity,
+	isDragging,
 }: AnimateToProgressProps) => {
 	"worklet";
 
@@ -68,17 +88,16 @@ 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);
+
 		targetProgress.set(value);
+		animationProgress.set(animationProgressFrom);
 
 		const shouldClearEnteringOnFinish =
 			!isClosing && (markEntering || entering.get());
@@ -89,6 +108,7 @@ export const animateToProgress = ({
 			progressAnimating.set(FALSE);
 			progressSettled.set(TRUE);
 			transitionProgress.set(value);
+			animationProgress.set(animationProgressTo);
 			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
 			}
@@ -99,60 +119,71 @@ 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(value, effectiveConfig, (state) => {
-				"worklet";
-				if (state.settled) {
+			animate(
+				value,
+				effectiveConfig,
+				(state) => {
+					"worklet";
+					if (!state.finished) return;
+					if (isDragging?.get()) return;
+
 					progressSettled.set(TRUE);
-				}
 
-				if (!state.finished) return;
+					animationProgress.set(animationProgressTo);
 
-				if (shouldClearEnteringOnFinish) {
-					entering.set(FALSE);
-				}
+					if (shouldClearEnteringOnFinish) {
+						entering.set(FALSE);
+					}
 
-				if (isClosing) {
-					progressAnimating.set(FALSE);
+					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";
+						if (onAnimationFinish) {
+							// Paint the terminal UI-thread host/style state before React
+							// removes the closing route and its native portal host.
 							requestAnimationFrame(() => {
 								"worklet";
-								scheduleOnRN(onAnimationFinish, state.finished);
+								requestAnimationFrame(() => {
+									"worklet";
+									scheduleOnRN(onAnimationFinish, state.finished);
+								});
 							});
+						}
+					} else {
+						if (onAnimationFinish) {
+							scheduleOnRN(onAnimationFinish, state.finished);
+						}
+
+						// Delay clearing progress animation by one frame to ensure final frame is painted
+						requestAnimationFrame(() => {
+							progressAnimating.set(FALSE);
 						});
 					}
-				} else {
-					if (onAnimationFinish) {
-						scheduleOnRN(onAnimationFinish, state.finished);
-					}
-
-					// Delay clearing progress animation by one frame to ensure final frame is painted
-					requestAnimationFrame(() => {
-						progressAnimating.set(FALSE);
-					});
-				}
-			}),
+				},
+				{
+					value: animationProgress,
+					from: animationProgressFrom,
+					to: animationProgressTo,
+				},
+			),
 		);
 	};
 
 	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/animation/animate.ts

@@ -1,7 +1,7 @@
 import type { WithTimingConfig } from "react-native-reanimated";
 import { withTiming } from "react-native-reanimated";
 import { type SpringConfig, withInternalSpring } from "./spring";
-import type { AnimationStateCallback } from "./state";
+import type { AnimationProgressDriver, AnimationStateCallback } from "./state";
 
 export type TimingAnimationConfig = WithTimingConfig;
 export type SpringAnimationConfig = SpringConfig;
@@ -9,6 +9,11 @@ export type ScreenAnimationConfig =
 	| SpringAnimationConfig
 	| TimingAnimationConfig;
 
+const linearEasing = (progress: number) => {
+	"worklet";
+	return progress;
+};
+
 export const isSpringAnimationConfig = (
 	config: ScreenAnimationConfig | undefined,
 ): config is SpringAnimationConfig => {
@@ -33,10 +38,21 @@ export const animate = (
 	toValue: number,
 	config?: ScreenAnimationConfig,
 	callback?: AnimationStateCallback,
+	animationProgress?: AnimationProgressDriver,
 ) => {
 	"worklet";
 
 	if (!isSpringAnimationConfig(config)) {
+		if (animationProgress) {
+			animationProgress.value.set(animationProgress.from);
+			animationProgress.value.set(
+				withTiming(animationProgress.to, {
+					...config,
+					easing: linearEasing,
+				}),
+			);
+		}
+
 		return withTiming(toValue, config, (finished) => {
 			"worklet";
 			const didFinish = finished === true;
@@ -47,5 +63,5 @@ export const animate = (
 		});
 	}
 
-	return withInternalSpring(toValue, config, callback);
+	return withInternalSpring(toValue, config, callback, animationProgress);
 };

package/src/utils/animation/spring/spring.ts

@@ -3,7 +3,7 @@ import type {
 	AnimationCallback,
 	ReduceMotion,
 } from "react-native-reanimated";
-import type { AnimationStateCallback } from "../state";
+import type { AnimationProgressDriver, AnimationStateCallback } from "../state";
 import type { SpringConfig } from "./springConfigs";
 import type {
 	DefaultSpringConfig,
@@ -13,6 +13,7 @@ import type {
 } from "./springUtils";
 import {
 	calculateNewStiffnessToMatchDuration,
+	calculateSpringAnimationDuration,
 	checkIfConfigIsValid,
 	criticallyDampedSpringCalculations,
 	getEnergy,
@@ -30,6 +31,7 @@ const REACT_NATIVE_RUNTIME_KIND = 1;
 const REDUCE_MOTION_SYSTEM = "system";
 const REDUCE_MOTION_ALWAYS = "always";
 const DEFAULT_SPRING_SETTLE_DISTANCE = 0.001;
+const MAX_UNFINISHED_ANIMATION_PROGRESS = 1 - 1e-6;
 
 const DEFAULT_SPRING_CONFIG = {
 	damping: 120,
@@ -61,6 +63,7 @@ const getReduceMotionForAnimation = (config?: ReduceMotion) => {
 const defineSpringAnimation = <TAnimation extends Animation<TAnimation>>(
 	_starting: number,
 	factory: () => TAnimation,
+	onReducedMotion?: () => void,
 ): TAnimation => {
 	"worklet";
 	const create = (() => {
@@ -76,6 +79,7 @@ const defineSpringAnimation = <TAnimation extends Animation<TAnimation>>(
 		) => {
 			"worklet";
 			if (animation.reduceMotion) {
+				onReducedMotion?.();
 				animation.current = animation.toValue;
 				animation.onFrame = () => true;
 				return;
@@ -99,6 +103,7 @@ type withSpringType = (
 	toValue: number,
 	userConfig?: SpringConfig,
 	callback?: AnimationStateCallback,
+	animationProgress?: AnimationProgressDriver,
 ) => number;
 
 /**
@@ -123,9 +128,11 @@ export const withInternalSpring = ((
 	toValue: number,
 	userConfig?: SpringConfig,
 	callback?: AnimationStateCallback,
+	animationProgress?: AnimationProgressDriver,
 ): Animation<SpringAnimation> => {
 	"worklet";
 
+	// biome-ignore format: Keep this Reanimated fork aligned with its upstream layout.
 	return defineSpringAnimation<SpringAnimation>(toValue, () => {
 		"worklet";
 		const config: DefaultSpringConfig & SpringConfigInner = safeMergeConfigs<
@@ -175,6 +182,7 @@ export const withInternalSpring = ((
 
 			if (config.skipAnimation) {
 				animation.current = toValue;
+				animationProgress?.value.set(animationProgress.to);
 				animation.lastTimestamp = 0;
 				return true;
 			}
@@ -182,6 +190,7 @@ export const withInternalSpring = ((
 
 			const deltaTime = Math.min(Math.max(now - lastTimestamp, 0), 64);
 			animation.lastTimestamp = now;
+			animation.animationProgressElapsed += deltaTime;
 
 			const t = deltaTime / 1000;
 			const v0 = velocity as number;
@@ -212,6 +221,7 @@ export const withInternalSpring = ((
 			if (isAnimationTerminatingCalculation(animation, config)) {
 				animation.velocity = 0;
 				animation.current = toValue;
+				animationProgress?.value.set(animationProgress.to);
 				settled = true;
 				animation.settled = true;
 				// clear lastTimestamp to avoid using stale value by the next spring animation that starts after this one
@@ -221,6 +231,21 @@ export const withInternalSpring = ((
 
 			notifySettled(animation);
 
+			if (animationProgress) {
+				const elapsedFraction =
+					animation.animationProgressDuration <= 0
+						? MAX_UNFINISHED_ANIMATION_PROGRESS
+						: Math.min(
+								animation.animationProgressElapsed /
+									animation.animationProgressDuration,
+								MAX_UNFINISHED_ANIMATION_PROGRESS,
+							);
+				const nextAnimationProgress =
+					animationProgress.from +
+					(animationProgress.to - animationProgress.from) * elapsedFraction;
+				animationProgress.value.set(nextAnimationProgress);
+			}
+
 			return false;
 		}
 
@@ -307,6 +332,11 @@ export const withInternalSpring = ((
 				config.mass,
 			);
 			animation.initialEnergy = initialEnergy;
+			animation.animationProgressElapsed = 0;
+			animation.animationProgressDuration = config.skipAnimation
+				? 0
+				: calculateSpringAnimationDuration(animation, config);
+			animationProgress?.value.set(animationProgress.from);
 
 			animation.lastTimestamp = previousAnimation?.lastTimestamp || now;
 
@@ -339,9 +369,14 @@ export const withInternalSpring = ((
 			omega0: 0,
 			omega1: 0,
 			initialEnergy: 0,
+			animationProgressElapsed: 0,
+			animationProgressDuration: 0,
 			reduceMotion: getReduceMotionForAnimation(config.reduceMotion),
 		} as SpringAnimation;
 
 		return animation;
+	}, () => {
+		"worklet";
+		animationProgress?.value.set(animationProgress.to);
 	});
 }) as unknown as withSpringType;