react-native-screen-transitions 3.7.1 → 3.8.0-beta.0

package/src/shared/types/providers/{managed-stack.types.ts → blank-stack-provider.types.ts}

@@ -9,10 +9,10 @@ import type {
 } from "../stack.types";
 
 /**
- * Props for managed stack - generic over descriptor and navigation types.
+ * Props for blank stack - generic over descriptor and navigation types.
  * Defaults to base types for backward compatibility.
  */
-export interface ManagedStackProps<
+export interface BlankStackProviderProps<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 	TNavigation extends BaseStackNavigation = BaseStackNavigation,
 > {
@@ -26,18 +26,18 @@ export interface ManagedStackProps<
 }
 
 /**
- * Context value for managed stack — only fields unique to managed lifecycle.
+ * Context value for blank stack — only fields unique to blank stack lifecycle.
  * Shared fields (routes, scenes, etc.) live in StackContext.
  */
-export interface ManagedStackContextValue {
+export interface BlankStackProviderContextValue {
 	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
 }
 
 /**
- * Props passed to the render child of `withManagedStack`.
+ * Props passed to the render child of `withBlankStack`.
  * Only the fields that stack-view components actually consume.
  */
-export interface ManagedStackRenderProps<
+export interface BlankStackProviderRenderProps<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
 	scenes: BaseStackScene<TDescriptor>[];
@@ -46,12 +46,12 @@ export interface ManagedStackRenderProps<
 }
 
 /**
- * Internal result shape returned by useManagedStackValue.
+ * Internal result shape returned by useBlankStackProviderValue.
  */
-export interface ManagedStackResult<
+export interface BlankStackProviderResult<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
 	stackContextValue: StackContextValue;
-	managedContextValue: ManagedStackContextValue;
-	renderProps: ManagedStackRenderProps<TDescriptor>;
+	blankStackProviderContextValue: BlankStackProviderContextValue;
+	renderProps: BlankStackProviderRenderProps<TDescriptor>;
 }

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

@@ -5,8 +5,9 @@ import type {
 } from "./animation.types";
 import type {
 	GestureActivationArea,
-	GestureDirection,
+	GestureDirectionOption,
 	GestureProgressMode,
+	ScrollMetadataState,
 } from "./gesture.types";
 import type { OverlayProps } from "./overlay.types";
 
@@ -27,6 +28,13 @@ export type ScreenLayouts = {
 	 * auto snap-point sizing. It is undefined until a real measurement exists.
 	 */
 	content?: Layout;
+	/**
+	 * Scroll metadata from the primary transition-aware scrollable on this screen.
+	 *
+	 * For nested same-axis scrollables, the outermost scrollable owns that axis.
+	 * Cross-axis nested scrollables can each publish their own axis.
+	 */
+	scroll?: ScrollMetadataState;
 };
 
 export type ScreenKey = string;
@@ -174,8 +182,11 @@ export type ScreenTransitionConfig = {
 	 *
 	 * Supports pan directions (`horizontal`, `vertical`, etc.) and pinch
 	 * directions (`pinch-in`, `pinch-out`).
+	 *
+	 * Pan directions may be configured with an activation area:
+	 * `[{ gesture: "vertical", area: "edge" }]`.
 	 */
-	gestureDirection?: GestureDirection | GestureDirection[];
+	gestureDirection?: GestureDirectionOption;
 
 	/**
 	 * Controls how directly live gesture movement maps into transition progress
@@ -251,6 +262,8 @@ export type ScreenTransitionConfig = {
 
 	/**
 	 * The area of the screen where the gesture is activated.
+	 *
+	 * @deprecated Use `gestureDirection` entries with per-direction `area`.
 	 */
 	gestureActivationArea?: GestureActivationArea;
 

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

@@ -2,7 +2,7 @@ import { runOnJS, type SharedValue } from "react-native-reanimated";
 import { FALSE, TRUE } from "../../constants";
 import type { AnimationStoreMap } from "../../stores/animation.store";
 import type { TransitionSpec } from "../../types/animation.types";
-import { animate } from "./animate";
+import { animate, isSpringAnimationConfig } from "./animate";
 
 interface AnimateToProgressProps {
 	/**
@@ -60,15 +60,20 @@ export const animateToProgress = ({
 	// Select spec based on direction (closing uses close spec, otherwise open)
 	const config = isClosing ? spec?.close : spec?.open;
 
-	const isSpringConfig =
-		!!config && !("duration" in config) && !("easing" in config);
+	const isSpringConfig = isSpringAnimationConfig(config);
 
 	const effectiveConfig =
 		isSpringConfig && typeof initialVelocity === "number"
 			? { ...config, velocity: initialVelocity }
 			: config;
 
-	const { progress, willAnimate, progressAnimating, entering } = animations;
+	const {
+		progress,
+		willAnimate,
+		progressAnimating,
+		progressSettled,
+		entering,
+	} = animations;
 
 	const startAnimation = () => {
 		"worklet";
@@ -81,6 +86,7 @@ export const animateToProgress = ({
 
 		if (!config) {
 			progressAnimating.set(FALSE);
+			progressSettled.set(TRUE);
 			progress.set(value);
 			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
@@ -93,17 +99,22 @@ export const animateToProgress = ({
 		}
 
 		progressAnimating.set(TRUE); //<-- Do not move this into the callback
+		progressSettled.set(FALSE);
 		progress.set(
-			animate(value, effectiveConfig, (finished) => {
+			animate(value, effectiveConfig, (state) => {
 				"worklet";
-				if (!finished) return;
+				if (state.settled) {
+					progressSettled.set(TRUE);
+				}
+
+				if (!state.finished) return;
 
 				if (shouldClearEnteringOnFinish) {
 					entering.set(FALSE);
 				}
 
 				if (onAnimationFinish) {
-					runOnJS(onAnimationFinish)(finished);
+					runOnJS(onAnimationFinish)(state.finished);
 				}
 
 				// Delay clearing progress animation by one frame to ensure final frame is painted

package/src/shared/utils/animation/animate.ts

@@ -1,28 +1,51 @@
-import {
-	type WithSpringConfig,
-	type WithTimingConfig,
-	withSpring,
-	withTiming,
-} from "react-native-reanimated";
-import type {
-	AnimatableValue,
-	AnimationCallback,
-} from "react-native-reanimated/lib/typescript/commonTypes";
+import type { WithTimingConfig } from "react-native-reanimated";
+import { withTiming } from "react-native-reanimated";
+import { type SpringConfig, withInternalSpring } from "./spring";
+import type { AnimationStateCallback } from "./state";
 
-export const animate = <T extends AnimatableValue>(
-	toValue: T,
-	config?: WithSpringConfig | WithTimingConfig,
-	callback?: AnimationCallback,
+export type TimingAnimationConfig = WithTimingConfig;
+export type SpringAnimationConfig = SpringConfig;
+export type ScreenAnimationConfig =
+	| SpringAnimationConfig
+	| TimingAnimationConfig;
+
+export const isSpringAnimationConfig = (
+	config: ScreenAnimationConfig | undefined,
+): config is SpringAnimationConfig => {
+	"worklet";
+	if (typeof config !== "object" || config === null) {
+		return false;
+	}
+
+	return (
+		"stiffness" in config ||
+		"damping" in config ||
+		"mass" in config ||
+		"velocity" in config ||
+		"overshootClamping" in config ||
+		"energyThreshold" in config ||
+		"dampingRatio" in config ||
+		"clamp" in config
+	);
+};
+
+export const animate = (
+	toValue: number,
+	config?: ScreenAnimationConfig,
+	callback?: AnimationStateCallback,
 ) => {
 	"worklet";
-	const isSpring =
-		typeof config === "object" &&
-		!("duration" in config) &&
-		!("easing" in config);
 
-	if (!isSpring) {
-		return withTiming(toValue, config, callback);
+	if (!isSpringAnimationConfig(config)) {
+		return withTiming(toValue, config, (finished) => {
+			"worklet";
+			const didFinish = finished === true;
+			callback?.({
+				finished: didFinish,
+				settled: didFinish,
+			});
+		});
 	}
 
-	return withSpring(toValue, config, callback);
+	return withInternalSpring(toValue, config, callback);
 };

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

@@ -0,0 +1,2 @@
+export { withInternalSpring } from "./spring";
+export type { SpringConfig } from "./springConfigs";

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

@@ -0,0 +1,347 @@
+import type {
+	Animation,
+	AnimationCallback,
+	ReduceMotion,
+} from "react-native-reanimated";
+import type { AnimationStateCallback } from "../state";
+import type { SpringConfig } from "./springConfigs";
+import type {
+	DefaultSpringConfig,
+	InnerSpringAnimation,
+	SpringAnimation,
+	SpringConfigInner,
+} from "./springUtils";
+import {
+	calculateNewStiffnessToMatchDuration,
+	checkIfConfigIsValid,
+	criticallyDampedSpringCalculations,
+	getEnergy,
+	initialCalculations,
+	isAnimationSettledCalculation,
+	isAnimationTerminatingCalculation,
+	safeMergeConfigs,
+	scaleZetaToMatchClamps,
+	underDampedSpringCalculations,
+} from "./springUtils";
+
+type Timestamp = number;
+
+const REACT_NATIVE_RUNTIME_KIND = 1;
+const REDUCE_MOTION_SYSTEM = "system";
+const REDUCE_MOTION_ALWAYS = "always";
+const DEFAULT_SPRING_SETTLE_DISTANCE = 0.001;
+
+const DEFAULT_SPRING_CONFIG = {
+	damping: 120,
+	mass: 4,
+	stiffness: 900,
+	duration: 550,
+	dampingRatio: 1,
+	overshootClamping: false,
+	energyThreshold: 6e-9,
+	velocity: 0,
+	reduceMotion: undefined,
+	clamp: undefined,
+} as const satisfies DefaultSpringConfig;
+
+const getRuntimeKind = () => {
+	"worklet";
+	return (globalThis as { __RUNTIME_KIND?: number }).__RUNTIME_KIND;
+};
+
+const getReduceMotionForAnimation = (config?: ReduceMotion) => {
+	"worklet";
+	if (!config || config === REDUCE_MOTION_SYSTEM) {
+		return undefined;
+	}
+
+	return config === REDUCE_MOTION_ALWAYS;
+};
+
+const defineSpringAnimation = <TAnimation extends Animation<TAnimation>>(
+	_starting: number,
+	factory: () => TAnimation,
+): TAnimation => {
+	"worklet";
+	const create = (() => {
+		"worklet";
+		const animation = factory();
+		const baseOnStart = animation.onStart;
+
+		animation.onStart = (
+			animation: TAnimation,
+			value: Parameters<TAnimation["onStart"]>[1],
+			timestamp: Timestamp,
+			previousAnimation: Parameters<TAnimation["onStart"]>[3],
+		) => {
+			"worklet";
+			if (animation.reduceMotion) {
+				animation.current = animation.toValue;
+				animation.onFrame = () => true;
+				return;
+			}
+
+			baseOnStart(animation, value, timestamp, previousAnimation);
+		};
+
+		return animation;
+	}) as (() => TAnimation) & { __isAnimationDefinition?: true };
+
+	if (getRuntimeKind() !== REACT_NATIVE_RUNTIME_KIND) {
+		return create();
+	}
+
+	create.__isAnimationDefinition = true;
+	return create as unknown as TAnimation;
+};
+
+type withSpringType = (
+	toValue: number,
+	userConfig?: SpringConfig,
+	callback?: AnimationStateCallback,
+) => number;
+
+/**
+ * Internal numeric spring forked from Reanimated's `withSpring`.
+ *
+ * As of version 4.4, Reanimated resets the spring velocity to zero whenever it
+ * initially points away from the target (see
+ * https://github.com/software-mansion/react-native-reanimated/pull/9463).
+ * That's a reasonable fix for stale inherited velocity in Reanimated's public
+ * spring behavior, but our gesture release handoff relies on that
+ * away-from-target velocity on purpose. It's what preserves the visual
+ * dismissal tail controlled by `gestureReleaseVelocityScale`.
+ *
+ * We went with this fork rather than trying to recreate the velocity scale
+ * outside the spring, since that approach pushed too much state and timing
+ * logic into the transition layer, bloated the code, and made the handoff
+ * easier to get subtly wrong. Keeping the fork lets screen transitions hold on
+ * to the native spring handoff behavior while keeping our own surface small and
+ * easy to extend with callbacks tailored to the transition lifecycle.
+ */
+export const withInternalSpring = ((
+	toValue: number,
+	userConfig?: SpringConfig,
+	callback?: AnimationStateCallback,
+): Animation<SpringAnimation> => {
+	"worklet";
+
+	return defineSpringAnimation<SpringAnimation>(toValue, () => {
+		"worklet";
+		const config: DefaultSpringConfig & SpringConfigInner = safeMergeConfigs<
+			DefaultSpringConfig & SpringConfigInner
+		>(
+			{
+				...DEFAULT_SPRING_CONFIG,
+				useDuration: !!(userConfig?.duration || userConfig?.dampingRatio),
+				skipAnimation: false,
+				settleDistance: DEFAULT_SPRING_SETTLE_DISTANCE,
+			},
+			userConfig,
+		);
+
+		let settled = false;
+
+		const notifySettled = (animation: SpringAnimation) => {
+			"worklet";
+			if (settled) {
+				return;
+			}
+
+			if (!isAnimationSettledCalculation(animation, config)) {
+				return;
+			}
+
+			settled = true;
+			animation.settled = true;
+			callback?.({
+				finished: false,
+				settled: true,
+			});
+		};
+
+		config.skipAnimation = !checkIfConfigIsValid(config);
+
+		if (config.duration === 0) {
+			config.skipAnimation = true;
+		}
+
+		function springOnFrame(
+			animation: InnerSpringAnimation,
+			now: Timestamp,
+		): boolean {
+			// eslint-disable-next-line @typescript-eslint/no-shadow
+			const { toValue, current } = animation;
+
+			if (config.skipAnimation) {
+				animation.current = toValue;
+				animation.lastTimestamp = 0;
+				return true;
+			}
+			const { lastTimestamp, velocity } = animation;
+
+			const deltaTime = Math.min(Math.max(now - lastTimestamp, 0), 64);
+			animation.lastTimestamp = now;
+
+			const t = deltaTime / 1000;
+			const v0 = velocity as number;
+			const x0 = current - toValue;
+
+			const { zeta, omega0, omega1 } = animation;
+
+			const { position: newPosition, velocity: newVelocity } =
+				zeta < 1
+					? underDampedSpringCalculations(animation, {
+							zeta,
+							v0,
+							x0,
+							omega0,
+							omega1,
+							t,
+						})
+					: criticallyDampedSpringCalculations(animation, {
+							v0,
+							x0,
+							omega0,
+							t,
+						});
+
+			animation.current = newPosition;
+			animation.velocity = newVelocity;
+
+			if (isAnimationTerminatingCalculation(animation, config)) {
+				animation.velocity = 0;
+				animation.current = toValue;
+				settled = true;
+				animation.settled = true;
+				// clear lastTimestamp to avoid using stale value by the next spring animation that starts after this one
+				animation.lastTimestamp = 0;
+				return true;
+			}
+
+			notifySettled(animation);
+
+			return false;
+		}
+
+		function isTriggeredTwice(
+			previousAnimation: SpringAnimation | undefined,
+			animation: SpringAnimation,
+		) {
+			return (
+				previousAnimation?.lastTimestamp &&
+				previousAnimation?.startTimestamp &&
+				previousAnimation?.toValue === animation.toValue &&
+				previousAnimation?.duration === animation.duration &&
+				previousAnimation?.dampingRatio === animation.dampingRatio
+			);
+		}
+
+		function onStart(
+			animation: SpringAnimation,
+			value: number,
+			now: Timestamp,
+			previousAnimation: SpringAnimation | undefined,
+		): void {
+			animation.current = value;
+
+			let stiffness = config.stiffness;
+			const triggeredTwice = isTriggeredTwice(previousAnimation, animation);
+
+			const duration = config.duration;
+
+			const x0 = triggeredTwice
+				? // If animation is triggered twice we want to continue the previous animation
+					// form the previous starting point
+					(previousAnimation?.startValue as number)
+				: value - (animation.toValue as number);
+
+			animation.startValue = x0;
+
+			if (previousAnimation) {
+				animation.velocity =
+					(triggeredTwice
+						? previousAnimation?.velocity
+						: previousAnimation?.velocity + config.velocity) || 0;
+			} else {
+				animation.velocity = config.velocity || 0;
+			}
+
+			if (triggeredTwice) {
+				animation.zeta = previousAnimation?.zeta || 0;
+				animation.omega0 = previousAnimation?.omega0 || 0;
+				animation.omega1 = previousAnimation?.omega1 || 0;
+			} else {
+				if (config.useDuration) {
+					const actualDuration = triggeredTwice
+						? // If animation is triggered twice we want to continue the previous animation
+							// so we need to include the time that already elapsed
+							duration -
+							((previousAnimation?.lastTimestamp || 0) -
+								(previousAnimation?.startTimestamp || 0))
+						: duration;
+
+					config.duration = actualDuration;
+					stiffness = calculateNewStiffnessToMatchDuration(
+						x0,
+						config,
+						animation.velocity,
+					);
+					config.stiffness = stiffness;
+				}
+
+				const { zeta, omega0, omega1 } = initialCalculations(stiffness, config);
+				animation.zeta = zeta;
+				animation.omega0 = omega0;
+				animation.omega1 = omega1;
+
+				if (config.clamp !== undefined) {
+					animation.zeta = scaleZetaToMatchClamps(animation, config.clamp);
+				}
+			}
+
+			const initialEnergy = getEnergy(
+				x0,
+				config.velocity,
+				config.stiffness,
+				config.mass,
+			);
+			animation.initialEnergy = initialEnergy;
+
+			animation.lastTimestamp = previousAnimation?.lastTimestamp || now;
+
+			animation.startTimestamp = triggeredTwice
+				? previousAnimation?.startTimestamp || now
+				: now;
+
+			notifySettled(animation);
+		}
+
+		const animation = {
+			onFrame: springOnFrame,
+			onStart,
+			toValue,
+			velocity: config.velocity || 0,
+			current: toValue,
+			settled: false,
+			startValue: 0,
+			callback: ((finished?: boolean) => {
+				"worklet";
+				const didFinish = finished === true;
+				callback?.({
+					finished: didFinish,
+					settled: didFinish || settled,
+				});
+			}) as AnimationCallback,
+			lastTimestamp: 0,
+			startTimestamp: 0,
+			zeta: 0,
+			omega0: 0,
+			omega1: 0,
+			initialEnergy: 0,
+			reduceMotion: getReduceMotionForAnimation(config.reduceMotion),
+		} as SpringAnimation;
+
+		return animation;
+	});
+}) as unknown as withSpringType;

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

@@ -0,0 +1,46 @@
+import type { ReduceMotion } from "react-native-reanimated";
+
+/**
+ * Internal spring animation configuration.
+ *
+ * @param mass - The weight of the spring. Reducing this value makes the
+ *   animation faster.
+ * @param damping - How quickly a spring slows down. Higher damping means the
+ *   spring will come to rest faster.
+ * @param stiffness - How bouncy the spring is.
+ * @param duration - Perceptual duration of the animation in milliseconds.
+ *   Actual duration is 1.5 times the value of perceptual duration.
+ * @param dampingRatio - How damped the spring is. Value `1` means the spring is
+ *   critically damped, value `<1` means the spring is underdamped and value
+ *   `>1` means the spring is overdamped.
+ * @param velocity - Initial velocity applied to the spring equation.
+ * @param overshootClamping - Whether a spring can bounce over the `toValue`.
+ * @param energyThreshold - Relative energy threshold below which the spring
+ *   will snap to `toValue` without further oscillations.
+ * @param reduceMotion - Optional reduced-motion override. `ReduceMotion.Always`
+ *   finishes immediately, `ReduceMotion.Never` runs normally, and
+ *   `ReduceMotion.System` is treated like the default in this internal fork.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withSpring/#config-
+ */
+export type SpringConfig = {
+	mass?: number;
+	overshootClamping?: boolean;
+	energyThreshold?: number;
+	velocity?: number;
+	reduceMotion?: ReduceMotion;
+} & (
+	| {
+			stiffness?: number;
+			damping?: number;
+			duration?: never;
+			dampingRatio?: never;
+			clamp?: never;
+	  }
+	| {
+			stiffness?: never;
+			damping?: never;
+			duration?: number;
+			dampingRatio?: number;
+			clamp?: { min?: number; max?: number };
+	  }
+);