react-native-screen-transitions 2.3.2 → 2.3.4

package/src/__configs__/presets.ts

@@ -246,11 +246,13 @@ export const SharedIGImage = (
 				normX,
 				[-1, 0, 1],
 				[-width * 0.7, 0, width * 0.7],
+				"clamp",
 			);
 			const dragY = interpolate(
 				normY,
 				[-1, 0, 1],
 				[-height * 0.4, 0, height * 0.4],
+				"clamp",
 			);
 			const dragXScale = interpolate(normX, [0, 1], [1, 0.8]);
 			const dragYScale = interpolate(normY, [0, 1], [1, 0.8]);
@@ -328,6 +330,7 @@ export const SharedIGImage = (
 				damping: 1000,
 				mass: 3,
 				overshootClamping: true,
+				//@ts-expect-error
 				restSpeedThreshold: 0.02,
 			},
 			close: {
@@ -335,6 +338,7 @@ export const SharedIGImage = (
 				damping: 1000,
 				mass: 3,
 				overshootClamping: true,
+				//@ts-expect-error
 				restSpeedThreshold: 0.02,
 			},
 		},
@@ -507,13 +511,15 @@ export const SharedAppleMusic = (
 				damping: 500,
 				mass: 3,
 				overshootClamping: true,
+				//@ts-expect-error
 				restSpeedThreshold: 0.02,
 			},
 			close: {
 				stiffness: 600,
 				damping: 60,
-				mass: 3,
+				mass: 4,
 				overshootClamping: false,
+				//@ts-expect-error
 				restSpeedThreshold: 0.02,
 				restDisplacementThreshold: 0.002,
 			},

package/src/__configs__/specs.ts

@@ -5,5 +5,6 @@ export const DefaultSpec: WithSpringConfig = {
 	damping: 500,
 	mass: 3,
 	overshootClamping: true,
+	// @ts-expect-error
 	restSpeedThreshold: 0.02,
 };

package/src/components/controllers/screen-lifecycle.tsx

@@ -22,14 +22,12 @@ export const ScreenLifecycleController = ({
 		const key = current.navigation.getParent()?.getState().key;
 		const requestedDismissOnNavigator = NavigatorDismissState.get(key);
 
-		// Don't run e.preventDefault when the dismissal was on the local root
-		if (requestedDismissOnNavigator) {
-			resetStoresForScreen(current);
-			return;
-		}
+		const isEnabled = current.options.enableTransitions;
+		const isRequestedDismissOnNavigator = requestedDismissOnNavigator;
+		const isFirstScreen = current.navigation.getState().index === 0;
 
-		// Don't run e.preventDefault when this is the first screen of the stack
-		if (current.navigation.getState().index === 0) {
+		// If transitions are disabled, or the dismissal was on the local root, or this is the first screen of the stack, reset the stores
+		if (!isEnabled || isRequestedDismissOnNavigator || isFirstScreen) {
 			resetStoresForScreen(current);
 			return;
 		}

package/src/components/create-transition-aware-component.tsx

@@ -62,7 +62,7 @@ export function createTransitionAwareComponent<P extends object>(
 		});
 
 		const {
-			handleTransitionLayout,
+			handleInitialLayout,
 			captureActiveOnPress,
 			MeasurementSyncProvider,
 		} = useBoundsRegistry({
@@ -79,7 +79,7 @@ export function createTransitionAwareComponent<P extends object>(
 					ref={animatedRef}
 					style={[style, associatedStyles]}
 					onPress={captureActiveOnPress}
-					onLayout={runOnUI(handleTransitionLayout)}
+					onLayout={runOnUI(handleInitialLayout)}
 					collapsable={!sharedBoundTag}
 				>
 					{children}

package/src/hooks/bounds/use-bound-registry.tsx

@@ -25,11 +25,15 @@ import useStableCallback from "../use-stable-callback";
 interface BoundMeasurerHookProps {
 	sharedBoundTag?: string;
 	animatedRef: AnimatedRef<View>;
-
 	style: StyleProps;
 	onPress?: ((...args: unknown[]) => void) | undefined;
 }
 
+interface MaybeMeasureAndStoreParams {
+	onPress?: ((...args: unknown[]) => void) | undefined;
+	skipMarkingActive?: boolean;
+}
+
 interface MeasurementUpdateContextType {
 	updateSignal: SharedValue<number>;
 }
@@ -43,12 +47,11 @@ export const useBoundsRegistry = ({
 	style,
 	onPress,
 }: BoundMeasurerHookProps) => {
-	const { previous, current } = useKeys();
+	const { previous, current, next } = useKeys();
 
 	const ROOT_MEASUREMENT_SIGNAL = useContext(MeasurementUpdateContext);
 	const ROOT_SIGNAL = useSharedValue(0);
 	const IS_ROOT = !ROOT_MEASUREMENT_SIGNAL;
-	const hasMeasured = useSharedValue(false);
 
 	const emitUpdate = useCallback(() => {
 		"worklet";
@@ -56,15 +59,10 @@ export const useBoundsRegistry = ({
 	}, [IS_ROOT, ROOT_SIGNAL]);
 
 	const maybeMeasureAndStore = useCallback(
-		({
-			onPress,
-			skipMarkingActive,
-		}: {
-			onPress?: () => void;
-			skipMarkingActive?: boolean;
-		}) => {
+		({ onPress, skipMarkingActive }: MaybeMeasureAndStoreParams) => {
 			"worklet";
-			if (!sharedBoundTag) return;
+			// Currently, there's no necessity to measure when the current route is blurred ( could potentially change in the future )
+			if (!sharedBoundTag || next) return;
 
 			const measured = measure(animatedRef);
 
@@ -95,14 +93,15 @@ export const useBoundsRegistry = ({
 
 			if (onPress) runOnJS(onPress)();
 		},
-		[sharedBoundTag, animatedRef, current.route.key, style, emitUpdate],
+		[sharedBoundTag, animatedRef, current.route.key, style, emitUpdate, next],
 	);
 
-	const handleTransitionLayout = useCallback(() => {
+	const hasMeasuredOnLayout = useSharedValue(false);
+	const handleInitialLayout = useCallback(() => {
 		"worklet";
 
 		const prevKey = previous?.route.key;
-		if (!sharedBoundTag || hasMeasured.value || !prevKey) {
+		if (!sharedBoundTag || hasMeasuredOnLayout.value || !prevKey) {
 			return;
 		}
 
@@ -112,9 +111,14 @@ export const useBoundsRegistry = ({
 			// Should skip mark active if we are in a transition
 			maybeMeasureAndStore({ skipMarkingActive: true });
 			// Should not measure again while in transition
-			hasMeasured.value = true;
+			hasMeasuredOnLayout.value = true;
 		}
-	}, [maybeMeasureAndStore, sharedBoundTag, previous?.route.key, hasMeasured]);
+	}, [
+		maybeMeasureAndStore,
+		sharedBoundTag,
+		previous?.route.key,
+		hasMeasuredOnLayout,
+	]);
 
 	const captureActiveOnPress = useStableCallback(() => {
 		if (!sharedBoundTag) {
@@ -152,8 +156,7 @@ export const useBoundsRegistry = ({
 	);
 
 	return {
-		maybeMeasureAndStore,
-		handleTransitionLayout,
+		handleInitialLayout,
 		captureActiveOnPress,
 		MeasurementSyncProvider,
 	};

package/src/hooks/gestures/use-build-gestures.tsx

@@ -27,11 +27,12 @@ import { Animations } from "../../stores/animations";
 import { Gestures } from "../../stores/gestures";
 import { NavigatorDismissState } from "../../stores/navigator-dismiss-state";
 import { GestureOffsetState } from "../../types/gesture";
-import { animate } from "../../utils/animation/animate";
 import { startScreenTransition } from "../../utils/animation/start-screen-transition";
 import { applyOffsetRules } from "../../utils/gesture/check-gesture-activation";
 import { determineDismissal } from "../../utils/gesture/determine-dismissal";
 import { mapGestureToProgress } from "../../utils/gesture/map-gesture-to-progress";
+import { resetGestureValues } from "../../utils/gesture/reset-gesture-values";
+import { velocity } from "../../utils/gesture/velocity";
 import useStableCallback from "../use-stable-callback";
 
 interface BuildGesturesHookProps {
@@ -51,6 +52,7 @@ export const useBuildGestures = ({
 		x: 0,
 		y: 0,
 	});
+
 	const gestureOffsetState = useSharedValue<GestureOffsetState>(
 		GestureOffsetState.PENDING,
 	);
@@ -268,7 +270,7 @@ export const useBuildGestures = ({
 		(event: GestureStateChangeEvent<PanGestureHandlerEventPayload>) => {
 			"worklet";
 
-			const { shouldDismiss, velocity } = determineDismissal({
+			const { shouldDismiss } = determineDismissal({
 				event,
 				directions,
 				dimensions,
@@ -277,29 +279,32 @@ export const useBuildGestures = ({
 
 			const spec = shouldDismiss ? transitionSpec?.close : transitionSpec?.open;
 
-			gestures.isDismissing.value = Number(shouldDismiss);
-
-			// Provide per-axis velocities so drag return can bounce naturally
-			const vxPx = event.velocityX;
-			const vyPx = event.velocityY;
-			const vxNorm = vxPx / Math.max(1, dimensions.width);
-			const vyNorm = vyPx / Math.max(1, dimensions.height);
-			gestures.x.value = animate(0, { ...spec, velocity: vxPx });
-			gestures.y.value = animate(0, { ...spec, velocity: vyPx });
-			gestures.normalizedX.value = animate(0, { ...spec, velocity: vxNorm });
-			gestures.normalizedY.value = animate(0, { ...spec, velocity: vyNorm });
-			gestures.isDragging.value = 0;
+			resetGestureValues({
+				spec,
+				gestures,
+				shouldDismiss,
+				event,
+				dimensions,
+			});
 
 			if (shouldDismiss) {
 				runOnJS(setNavigatorDismissal)();
 			}
 
+			const initialVelocity = velocity.calculateProgressVelocity({
+				animations,
+				shouldDismiss,
+				event,
+				dimensions,
+				directions,
+			});
+
 			startScreenTransition({
 				target: shouldDismiss ? "close" : "open",
 				onAnimationFinish: shouldDismiss ? handleDismiss : undefined,
 				spec: transitionSpec,
-				velocity,
 				animations,
+				initialVelocity,
 			});
 		},
 		[

package/src/integrations/native-stack/views/NativeStackView.native.tsx

@@ -267,12 +267,12 @@ const SceneView = ({
 	}, [canGoBack, backTitle]);
 
 	const isRemovePrevented = preventedRoutes[route.key]?.preventRemove;
+
 	const modifiedPresentation = enableTransitions
 		? "containedTransparentModal"
 		: presentation === "card"
 			? "push"
 			: presentation;
-
 	const modifiedAnimation = enableTransitions ? "none" : animation;
 	const modifiedHeaderShown =
 		enableTransitions || header !== undefined ? false : headerShown;

package/src/utils/animation/start-screen-transition.ts

@@ -8,7 +8,8 @@ interface StartScreenTransitionProps {
 	spec?: TransitionSpec;
 	onAnimationFinish?: (finished: boolean) => void;
 	animations: AnimationMap;
-	velocity?: number;
+	/** Optional initial velocity for spring-based progress (units: progress/sec). */
+	initialVelocity?: number;
 }
 
 export const startScreenTransition = ({
@@ -16,12 +17,20 @@ export const startScreenTransition = ({
 	spec,
 	onAnimationFinish,
 	animations,
-	velocity,
+	initialVelocity,
 }: StartScreenTransitionProps) => {
 	"worklet";
 	const value = target === "open" ? 1 : 0;
 	const config = target === "open" ? spec?.open : spec?.close;
 
+	const isSpringConfig =
+		!!config && !("duration" in config) && !("easing" in config);
+
+	const effectiveConfig =
+		isSpringConfig && typeof initialVelocity === "number"
+			? { ...config, velocity: initialVelocity }
+			: config;
+
 	const { progress, animating, closing } = animations;
 
 	if (target === "close") {
@@ -40,13 +49,13 @@ export const startScreenTransition = ({
 
 	animating.value = 1;
 
-	progress.value = animate(value, { ...config, velocity }, (finished) => {
+	progress.value = animate(value, effectiveConfig, (finished) => {
 		"worklet";
 		if (finished) {
-			animating.value = 0;
 			if (onAnimationFinish) {
 				runOnJS(onAnimationFinish)(finished);
 			}
+			animating.value = 0;
 		}
 	});
 };

package/src/utils/gesture/determine-dismissal.ts

@@ -22,10 +22,7 @@ interface DetermineDismissalProps {
 	gestureVelocityImpact: number;
 }
 
-// Note: we normalize velocity by the axis dimension to map px/s to progress/s.
-// This produces consistent behavior across devices and enables realistic bounce.
-
-const MAX_PROGRESS_VELOCITY = 3.5; // ~3 progress units/second
+import { velocity as V } from "./velocity";
 
 const getAxisThreshold = ({
 	translation,
@@ -34,31 +31,14 @@ const getAxisThreshold = ({
 	gestureVelocityImpact,
 }: GetAxisThresholdProps) => {
 	"worklet";
-	const finalTranslation = translation + velocity * gestureVelocityImpact;
-
-	return (
-		Math.abs(finalTranslation) > screenSize / 2 &&
-		(velocity !== 0 || translation !== 0)
+	return V.shouldPassDismissalThreshold(
+		translation,
+		velocity,
+		screenSize,
+		gestureVelocityImpact,
 	);
 };
 
-const getVelocity = (
-	dimensions: { width: number; height: number },
-	velocityX: number,
-	velocityY: number,
-	dismissAxis: "x" | "y",
-) => {
-	"worklet";
-	const axisSize = dismissAxis === "y" ? dimensions.height : dimensions.width;
-	const axisVelocityPx = dismissAxis === "y" ? velocityY : velocityX;
-	let velocity = axisVelocityPx / Math.max(1, axisSize);
-
-	if (velocity > MAX_PROGRESS_VELOCITY) velocity = MAX_PROGRESS_VELOCITY;
-	if (velocity < -MAX_PROGRESS_VELOCITY) velocity = -MAX_PROGRESS_VELOCITY;
-
-	return velocity;
-};
-
 export const determineDismissal = ({
 	event,
 	directions,
@@ -68,45 +48,24 @@ export const determineDismissal = ({
 	"worklet";
 
 	let shouldDismiss: boolean = false;
-	let dismissAxis: "x" | "y" = "x";
 
-	if (directions.vertical && event.translationY > 0) {
-		const dismiss = getAxisThreshold({
-			translation: event.translationY,
-			velocity: event.velocityY,
-			screenSize: dimensions.height,
-			gestureVelocityImpact,
-		});
-		if (dismiss) {
-			dismissAxis = "y";
-			shouldDismiss = true;
-		}
-	}
-	if (directions.verticalInverted && event.translationY < 0) {
+	if (
+		(directions.vertical && event.translationY > 0) ||
+		(directions.verticalInverted && event.translationY < 0)
+	) {
 		const dismiss = getAxisThreshold({
 			translation: event.translationY,
 			velocity: event.velocityY,
 			screenSize: dimensions.height,
 			gestureVelocityImpact,
 		});
-		if (dismiss) {
-			dismissAxis = "y";
-			shouldDismiss = true;
-		}
-	}
-	if (directions.horizontal && event.translationX > 0) {
-		const dismiss = getAxisThreshold({
-			translation: event.translationX,
-			velocity: event.velocityX,
-			screenSize: dimensions.width,
-			gestureVelocityImpact,
-		});
-		if (dismiss) {
-			dismissAxis = "x";
-			shouldDismiss = true;
-		}
+		if (dismiss) shouldDismiss = true;
 	}
-	if (directions.horizontalInverted && event.translationX < 0) {
+
+	if (
+		(directions.horizontal && event.translationX > 0) ||
+		(directions.horizontalInverted && event.translationX < 0)
+	) {
 		const dismiss = getAxisThreshold({
 			translation: event.translationX,
 			velocity: event.velocityX,
@@ -114,18 +73,8 @@ export const determineDismissal = ({
 			gestureVelocityImpact,
 		});
 
-		if (dismiss) {
-			dismissAxis = "x";
-			shouldDismiss = true;
-		}
+		if (dismiss) shouldDismiss = true;
 	}
 
-	const velocity = getVelocity(
-		dimensions,
-		event.velocityX,
-		event.velocityY,
-		dismissAxis,
-	);
-
-	return { shouldDismiss, velocity };
+	return { shouldDismiss };
 };

package/src/utils/gesture/reset-gesture-values.ts

@@ -0,0 +1,48 @@
+import type {
+	GestureStateChangeEvent,
+	PanGestureHandlerEventPayload,
+} from "react-native-gesture-handler";
+import type { GestureMap } from "../../stores/gestures";
+import type { AnimationConfig } from "../../types/animation";
+import { animate } from "../animation/animate";
+import { velocity } from "./velocity";
+
+interface ResetGestureValuesProps {
+	spec?: AnimationConfig;
+	gestures: GestureMap;
+	shouldDismiss: boolean;
+	event: GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+	dimensions: { width: number; height: number };
+}
+
+export const resetGestureValues = ({
+	spec,
+	gestures,
+	shouldDismiss,
+	event,
+	dimensions,
+}: ResetGestureValuesProps) => {
+	"worklet";
+
+	const vxNorm = velocity.normalize(event.velocityX, dimensions.width);
+	const vyNorm = velocity.normalize(event.velocityY, dimensions.height);
+
+	// Ensure spring starts moving toward zero using normalized gesture values for direction.
+	const nx =
+		gestures.normalizedX.value ||
+		event.translationX / Math.max(1, dimensions.width);
+	const ny =
+		gestures.normalizedY.value ||
+		event.translationY / Math.max(1, dimensions.height);
+
+	const vxTowardZero = velocity.calculateRestoreVelocity(nx, vxNorm);
+	const vyTowardZero = velocity.calculateRestoreVelocity(ny, vyNorm);
+
+	gestures.x.value = animate(0, { ...spec, velocity: vxTowardZero });
+	gestures.y.value = animate(0, { ...spec, velocity: vyTowardZero });
+
+	gestures.normalizedX.value = animate(0, { ...spec, velocity: vxTowardZero });
+	gestures.normalizedY.value = animate(0, { ...spec, velocity: vyTowardZero });
+	gestures.isDragging.value = 0;
+	gestures.isDismissing.value = Number(shouldDismiss);
+};

package/src/utils/gesture/velocity.ts

@@ -0,0 +1,144 @@
+import type {
+	GestureStateChangeEvent,
+	PanGestureHandlerEventPayload,
+} from "react-native-gesture-handler";
+import { clamp } from "react-native-reanimated";
+import type { AnimationMap } from "../../stores/animations";
+
+interface CalculateProgressProps {
+	animations: AnimationMap;
+	shouldDismiss: boolean;
+	event: GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+	dimensions: { width: number; height: number };
+	directions: {
+		horizontal: boolean;
+		horizontalInverted: boolean;
+		vertical: boolean;
+		verticalInverted: boolean;
+	};
+}
+
+const MAX_VELOCITY_MAGNITUDE = 3.2;
+const NEAR_ZERO_THRESHOLD = 0.01;
+
+/**
+ * Converts velocity from pixels/second to normalized units/second (0-1 range)
+ * and caps the result for stability
+ */
+const normalize = (velocityPixelsPerSecond: number, screenSize: number) => {
+	"worklet";
+	return clamp(
+		velocityPixelsPerSecond / Math.max(1, screenSize),
+		-MAX_VELOCITY_MAGNITUDE,
+		MAX_VELOCITY_MAGNITUDE,
+	);
+};
+
+/**
+ * Calculates a normalized velocity that moves the current value toward zero.
+ * Used for spring-back animations when dismissing gestures.
+ */
+const calculateRestoreVelocity = (
+	currentValueNormalized: number,
+	baseVelocityNormalized: number,
+	threshold: number = NEAR_ZERO_THRESHOLD,
+) => {
+	"worklet";
+
+	if (Math.abs(currentValueNormalized) < threshold) return 0;
+
+	const directionTowardZero = Math.sign(currentValueNormalized) || 1;
+	const clampedVelocity = Math.min(Math.abs(baseVelocityNormalized), 1);
+
+	return -directionTowardZero * clampedVelocity;
+};
+
+const calculateProgressVelocity = ({
+	animations,
+	shouldDismiss,
+	event,
+	dimensions,
+	directions,
+}: CalculateProgressProps) => {
+	"worklet";
+
+	const currentProgress = animations.progress.value;
+	const targetProgress = shouldDismiss ? 0 : 1;
+	const progressDelta = targetProgress - currentProgress;
+
+	const progressDirection = progressDelta === 0 ? 0 : Math.sign(progressDelta);
+
+	const normalizedVelocityX = normalize(event.velocityX, dimensions.width);
+	const normalizedVelocityY = normalize(event.velocityY, dimensions.height);
+
+	const normalizedTranslationX = Math.abs(
+		event.translationX / dimensions.width,
+	);
+	const normalizedTranslationY = Math.abs(
+		event.translationY / dimensions.height,
+	);
+
+	const supportsHorizontalGestures =
+		directions.horizontal || directions.horizontalInverted;
+
+	const supportsVerticalGestures =
+		directions.vertical || directions.verticalInverted;
+
+	let progressVelocityMagnitude = 0;
+
+	// Determine which axis should drive the progress velocity
+	if (
+		supportsHorizontalGestures &&
+		(!supportsVerticalGestures ||
+			normalizedTranslationX >= normalizedTranslationY)
+	) {
+		progressVelocityMagnitude = Math.abs(normalizedVelocityX);
+	} else if (supportsVerticalGestures) {
+		progressVelocityMagnitude = Math.abs(normalizedVelocityY);
+	} else {
+		progressVelocityMagnitude = Math.max(
+			Math.abs(normalizedVelocityX),
+			Math.abs(normalizedVelocityY),
+		);
+	}
+
+	// Apply direction and clamp to prevent overly energetic springs
+	return (
+		progressDirection *
+		clamp(progressVelocityMagnitude, 0, MAX_VELOCITY_MAGNITUDE)
+	);
+};
+
+/**
+ * Determines if a gesture should trigger dismissal based on combined
+ * translation and velocity in normalized screen units (0-1 range).
+ *
+ * Formula: |translation/screen + clamp(velocity/screen, ±1) * velocityWeight| > 0.5
+ */
+const shouldPassDismissalThreshold = (
+	translationPixels: number,
+	velocityPixelsPerSecond: number,
+	screenSize: number,
+	velocityWeight: number,
+) => {
+	"worklet";
+
+	const normalizedTranslation = translationPixels / Math.max(1, screenSize);
+	const normalizedVelocity = normalize(velocityPixelsPerSecond, screenSize);
+
+	const projectedNormalizedPosition =
+		normalizedTranslation + normalizedVelocity * velocityWeight;
+
+	const exceedsThreshold = Math.abs(projectedNormalizedPosition) > 0.5;
+
+	const hasMovement = translationPixels !== 0 || velocityPixelsPerSecond !== 0;
+
+	return exceedsThreshold && hasMovement;
+};
+
+export const velocity = {
+	normalize,
+	calculateRestoreVelocity,
+	calculateProgressVelocity,
+	shouldPassDismissalThreshold,
+};

package/src/utils/reanimated/version.ts

@@ -0,0 +1,5 @@
+import { reanimatedVersion } from "react-native-reanimated";
+
+export const isReanimated4 = () => {
+	return reanimatedVersion.split(".")[0] === "4";
+};