react-native-screen-transitions 2.3.3 → 2.4.0

package/src/__configs__/presets.ts

@@ -173,7 +173,6 @@ export const ElasticCard = (
 			/**
 			 * Applies to both screens ( previous and incoming)
 			 */
-
 			const scale = interpolate(progress, [0, 1, 2], [0, 1, 0.8]);
 
 			// applies to current screen
@@ -367,16 +366,33 @@ export const SharedAppleMusic = (
 
 			const normX = active.gesture.normalizedX;
 			const normY = active.gesture.normalizedY;
+			const initialDirection = active.gesture.direction;
 
 			/**
 			 * ===============================
 			 * Animations for both bounds
 			 * ===============================
 			 */
-			const dragX = interpolate(normX, [0, 1], [0, screen.width * 0.8]);
-			const dragY = interpolate(normY, [0, 1], [0, screen.height * 0.8]);
-			const dragXScale = interpolate(normX, [0, 1], [1, 0.75]);
-			const dragYScale = interpolate(normY, [0, 1], [1, 0.75]);
+			const xResistance = initialDirection === "horizontal" ? 0.7 : 0.4;
+			const yResistance = initialDirection === "vertical" ? 0.7 : 0.4;
+
+			const xScaleOuput = initialDirection === "horizontal" ? [1, 0.5] : [1, 1];
+			const yScaleOuput = initialDirection === "vertical" ? [1, 0.5] : [1, 1];
+
+			const dragX = interpolate(
+				normX,
+				[-1, 0, 1],
+				[-screen.width * xResistance, 0, screen.width * xResistance],
+				"clamp",
+			);
+			const dragY = interpolate(
+				normY,
+				[-1, 0, 1],
+				[-screen.height * yResistance, 0, screen.height * yResistance],
+				"clamp",
+			);
+			const dragXScale = interpolate(normX, [0, 1], xScaleOuput);
+			const dragYScale = interpolate(normY, [0, 1], yScaleOuput);
 
 			const boundValues = bounds({
 				method: focused ? "content" : "transform",
@@ -387,8 +403,8 @@ export const SharedAppleMusic = (
 
 			const opacity = interpolate(
 				progress,
-				[0, 0.35, 1, 1.25, 2],
-				[0, 1, 1, 1, 0],
+				[0, 0.25, 1.25, 2],
+				[0, 1, 1, 0],
 				"clamp",
 			);
 

package/src/__tests__/determine-dismissal.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it, mock } from "bun:test";
+
+mock.module("react-native", () => ({}));
+mock.module("react-native-gesture-handler", () => ({}));
+mock.module("react-native-reanimated", () => ({
+	clamp: (value: number, lower: number, upper: number) =>
+		Math.min(Math.max(value, lower), upper),
+}));
+
+const { determineDismissal } = await import(
+	"../utils/gesture/determine-dismissal"
+);
+
+describe("determineDismissal", () => {
+	const dimensions = { width: 320, height: 640 };
+
+	it("dismisses when horizontal translation exceeds the threshold", () => {
+		const { shouldDismiss } = determineDismissal({
+			event: {
+				translationX: 170,
+				translationY: 0,
+				velocityX: 0,
+				velocityY: 0,
+			},
+			directions: {
+				vertical: false,
+				verticalInverted: false,
+				horizontal: true,
+				horizontalInverted: false,
+			},
+			dimensions,
+			gestureVelocityImpact: 0.3,
+		});
+
+		expect(shouldDismiss).toBe(true);
+	});
+
+	it("ignores movement in disallowed directions", () => {
+		const { shouldDismiss } = determineDismissal({
+			event: {
+				translationX: 200,
+				translationY: 0,
+				velocityX: 0,
+				velocityY: 0,
+			},
+			directions: {
+				vertical: true,
+				verticalInverted: false,
+				horizontal: false,
+				horizontalInverted: false,
+			},
+			dimensions,
+			gestureVelocityImpact: 0.3,
+		});
+
+		expect(shouldDismiss).toBe(false);
+	});
+
+	it("dismisses vertical gestures when velocity pushes the projection past the threshold", () => {
+		const { shouldDismiss } = determineDismissal({
+			event: {
+				translationX: 0,
+				translationY: 40,
+				velocityX: 0,
+				velocityY: 1800,
+			},
+			directions: {
+				vertical: true,
+				verticalInverted: false,
+				horizontal: false,
+				horizontalInverted: false,
+			},
+			dimensions,
+			gestureVelocityImpact: 0.3,
+		});
+
+		expect(shouldDismiss).toBe(true);
+	});
+
+	it("respects inverted horizontal directions", () => {
+		const { shouldDismiss } = determineDismissal({
+			event: {
+				translationX: -160,
+				translationY: 0,
+				velocityX: -700,
+				velocityY: 0,
+			},
+			directions: {
+				vertical: false,
+				verticalInverted: false,
+				horizontal: false,
+				horizontalInverted: true,
+			},
+			dimensions,
+			gestureVelocityImpact: 0.25,
+		});
+
+		expect(shouldDismiss).toBe(true);
+	});
+
+	it("returns false when movement never exceeds the composite threshold", () => {
+		const { shouldDismiss } = determineDismissal({
+			event: {
+				translationX: 30,
+				translationY: 0,
+				velocityX: 100,
+				velocityY: 0,
+			},
+			directions: {
+				vertical: false,
+				verticalInverted: false,
+				horizontal: true,
+				horizontalInverted: false,
+			},
+			dimensions,
+			gestureVelocityImpact: 0.2,
+		});
+
+		expect(shouldDismiss).toBe(false);
+	});
+});

package/src/__tests__/gesture.velocity.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it, mock } from "bun:test";
+
+mock.module("react-native", () => ({}));
+mock.module("react-native-gesture-handler", () => ({}));
+mock.module("react-native-reanimated", () => ({
+	clamp: (value: number, lower: number, upper: number) =>
+		Math.min(Math.max(value, lower), upper),
+}));
+
+const { velocity } = await import("../utils/gesture/velocity");
+
+type Directions = {
+	horizontal: boolean;
+	horizontalInverted: boolean;
+	vertical: boolean;
+	verticalInverted: boolean;
+};
+
+type GestureEventInit = {
+	translationX?: number;
+	translationY?: number;
+	velocityX?: number;
+	velocityY?: number;
+};
+
+const createAnimations = (progress: number) =>
+	({
+		progress: { value: progress },
+		closing: { value: 0 },
+		animating: { value: 0 },
+	}) as const;
+
+const createEvent = ({
+	translationX = 0,
+	translationY = 0,
+	velocityX = 0,
+	velocityY = 0,
+}: GestureEventInit) =>
+	({ translationX, translationY, velocityX, velocityY }) as any;
+
+const createDirections = (overrides: Partial<Directions> = {}) => ({
+	horizontal: false,
+	horizontalInverted: false,
+	vertical: false,
+	verticalInverted: false,
+	...overrides,
+});
+
+describe("velocity.normalize", () => {
+	it("clamps values to the configured range", () => {
+		expect(velocity.normalize(6400, 320)).toBeCloseTo(3.2, 5);
+		expect(velocity.normalize(-6400, 320)).toBeCloseTo(-3.2, 5);
+	});
+});
+
+describe("velocity.calculateProgressVelocity", () => {
+	const dimensions = { width: 320, height: 640 };
+
+	it("returns positive magnitude when progressing toward open target", () => {
+		const animations = createAnimations(0.25);
+		const event = createEvent({
+			translationX: 48,
+			translationY: 6,
+			velocityX: 800,
+		});
+
+		const result = velocity.calculateProgressVelocity({
+			animations: animations as any,
+			shouldDismiss: false,
+			event,
+			dimensions,
+			directions: createDirections({ horizontal: true }),
+		});
+
+		expect(result).toBeCloseTo(2.5, 5);
+	});
+
+	it("prefers the axis with greater normalized translation", () => {
+		const animations = createAnimations(0.8);
+		const event = createEvent({
+			translationX: 24,
+			translationY: -140,
+			velocityX: 120,
+			velocityY: -900,
+		});
+
+		const result = velocity.calculateProgressVelocity({
+			animations: animations as any,
+			shouldDismiss: true,
+			event,
+			dimensions,
+			directions: createDirections({ horizontal: true, verticalInverted: true }),
+		});
+
+		expect(result).toBeLessThan(0);
+		expect(Math.abs(result)).toBeCloseTo(1.406, 3);
+	});
+
+	it("caps the returned magnitude using clamp", () => {
+		const animations = createAnimations(0.5);
+		const event = createEvent({
+			translationX: 10,
+			velocityX: 5000,
+		});
+
+		const result = velocity.calculateProgressVelocity({
+			animations: animations as any,
+			shouldDismiss: false,
+			event,
+			dimensions,
+			directions: createDirections({ horizontal: true }),
+		});
+
+		expect(result).toBeCloseTo(3.2, 5);
+	});
+});
+
+describe("velocity.shouldPassDismissalThreshold", () => {
+	const width = 320;
+
+	it("returns true once translation alone crosses half the screen", () => {
+		expect(
+			velocity.shouldPassDismissalThreshold(170, 0, width, 0.3),
+		).toBe(true);
+	});
+
+	it("combines translation with weighted velocity", () => {
+		expect(
+			velocity.shouldPassDismissalThreshold(40, 2500, width, 0.5),
+		).toBe(true);
+	});
+
+	it("returns false when movement is negligible", () => {
+		expect(
+			velocity.shouldPassDismissalThreshold(0, 0, width, 0.3),
+		).toBe(false);
+	});
+});

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/constants.ts

@@ -33,6 +33,7 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 			normalizedY: 0,
 			isDismissing: 0,
 			isDragging: 0,
+			direction: null,
 		},
 		bounds: {} as Record<string, BoundEntry>,
 		route: {} as RouteProp<ParamListBase>,
@@ -54,6 +55,7 @@ export const EMPTY_BOUND_HELPER_RESULT_RAW = Object.freeze({
 });
 export const ENTER_RANGE = [0, 1] as const;
 export const EXIT_RANGE = [1, 2] as const;
+
 export const FULLSCREEN_DIMENSIONS = (
 	dimensions: ScaledSize,
 ): MeasuredDimensions => {

package/src/hooks/animation/use-screen-animation.tsx

@@ -45,6 +45,7 @@ const unwrap = (
 			normalizedY: s.gesture.normalizedY.value,
 			isDismissing: s.gesture.isDismissing.value,
 			isDragging: s.gesture.isDragging.value,
+			direction: s.gesture.direction.value,
 		},
 		bounds: Bounds.getBounds(key) || NO_BOUNDS_MAP,
 		route: s.route,

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

@@ -18,18 +18,23 @@ import {
 import type { SharedValue } from "react-native-reanimated/lib/typescript/commonTypes";
 import { useKeys } from "../../providers/keys";
 import { Bounds } from "../../stores/bounds";
-import { flattenStyle } from "../../utils/bounds/_utils/flatten-styles";
 import { isBoundsEqual } from "../../utils/bounds/_utils/is-bounds-equal";
+import { prepareStyleForBounds } from "../../utils/bounds/_utils/styles";
 import useStableCallback from "../use-stable-callback";
+import useStableCallbackValue from "../use-stable-callback-value";
 
 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,28 +48,23 @@ export const useBoundsRegistry = ({
 	style,
 	onPress,
 }: BoundMeasurerHookProps) => {
-	const { previous, current } = useKeys();
+	const { previous, current, next } = useKeys();
+	const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
 
 	const ROOT_MEASUREMENT_SIGNAL = useContext(MeasurementUpdateContext);
 	const ROOT_SIGNAL = useSharedValue(0);
 	const IS_ROOT = !ROOT_MEASUREMENT_SIGNAL;
-	const hasMeasured = useSharedValue(false);
 
-	const emitUpdate = useCallback(() => {
+	const emitUpdate = useStableCallbackValue(() => {
 		"worklet";
 		if (IS_ROOT) ROOT_SIGNAL.value = ROOT_SIGNAL.value + 1;
-	}, [IS_ROOT, ROOT_SIGNAL]);
-
-	const maybeMeasureAndStore = useCallback(
-		({
-			onPress,
-			skipMarkingActive,
-		}: {
-			onPress?: () => void;
-			skipMarkingActive?: boolean;
-		}) => {
+	});
+
+	const maybeMeasureAndStore = useStableCallbackValue(
+		({ 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);
 
@@ -88,21 +88,21 @@ export const useBoundsRegistry = ({
 
 			emitUpdate();
 
-			Bounds.setBounds(key, sharedBoundTag, measured, flattenStyle(style));
+			Bounds.setBounds(key, sharedBoundTag, measured, preparedStyles);
 			if (!skipMarkingActive) {
 				Bounds.setRouteActive(key, sharedBoundTag);
 			}
 
 			if (onPress) runOnJS(onPress)();
 		},
-		[sharedBoundTag, animatedRef, current.route.key, style, emitUpdate],
 	);
 
-	const handleTransitionLayout = useCallback(() => {
+	const hasMeasuredOnLayout = useSharedValue(false);
+	const handleInitialLayout = useStableCallbackValue(() => {
 		"worklet";
 
 		const prevKey = previous?.route.key;
-		if (!sharedBoundTag || hasMeasured.value || !prevKey) {
+		if (!sharedBoundTag || hasMeasuredOnLayout.value || !prevKey) {
 			return;
 		}
 
@@ -112,9 +112,9 @@ 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]);
+	});
 
 	const captureActiveOnPress = useStableCallback(() => {
 		if (!sharedBoundTag) {
@@ -152,7 +152,7 @@ export const useBoundsRegistry = ({
 	);
 
 	return {
-		handleTransitionLayout,
+		handleInitialLayout,
 		captureActiveOnPress,
 		MeasurementSyncProvider,
 	};

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

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from "react";
+import { useMemo } from "react";
 import { useWindowDimensions } from "react-native";
 import {
 	Gesture,
@@ -26,7 +26,7 @@ import { useKeys } from "../../providers/keys";
 import { Animations } from "../../stores/animations";
 import { Gestures } from "../../stores/gestures";
 import { NavigatorDismissState } from "../../stores/navigator-dismiss-state";
-import { GestureOffsetState } from "../../types/gesture";
+import { type GestureDirection, GestureOffsetState } from "../../types/gesture";
 import { startScreenTransition } from "../../utils/animation/start-screen-transition";
 import { applyOffsetRules } from "../../utils/gesture/check-gesture-activation";
 import { determineDismissal } from "../../utils/gesture/determine-dismissal";
@@ -34,6 +34,7 @@ import { mapGestureToProgress } from "../../utils/gesture/map-gesture-to-progres
 import { resetGestureValues } from "../../utils/gesture/reset-gesture-values";
 import { velocity } from "../../utils/gesture/velocity";
 import useStableCallback from "../use-stable-callback";
+import useStableCallbackValue from "../use-stable-callback-value";
 
 interface BuildGesturesHookProps {
 	scrollConfig: SharedValue<ScrollConfig | null>;
@@ -98,17 +99,14 @@ export const useBuildGestures = ({
 		NavigatorDismissState.remove(key);
 	});
 
-	const onTouchesDown = useCallback(
-		(e: GestureTouchEvent) => {
-			"worklet";
-			const firstTouch = e.changedTouches[0];
-			initialTouch.value = { x: firstTouch.x, y: firstTouch.y };
-			gestureOffsetState.value = GestureOffsetState.PENDING;
-		},
-		[initialTouch, gestureOffsetState],
-	);
+	const onTouchesDown = useStableCallbackValue((e: GestureTouchEvent) => {
+		"worklet";
+		const firstTouch = e.changedTouches[0];
+		initialTouch.value = { x: firstTouch.x, y: firstTouch.y };
+		gestureOffsetState.value = GestureOffsetState.PENDING;
+	});
 
-	const onTouchesMove = useCallback(
+	const onTouchesMove = useStableCallbackValue(
 		(e: GestureTouchEvent, manager: GestureStateManagerType) => {
 			"worklet";
 
@@ -151,18 +149,24 @@ export const useBuildGestures = ({
 			const scrollCfg = scrollConfig.value;
 
 			let shouldActivate = false;
+			let activatedDirection: GestureDirection | null = null;
+
 			if (recognizedDirection) {
 				if (directions.vertical && isSwipingDown) {
 					shouldActivate = scrollCfg ? scrollCfg.y <= 0 : true;
+					if (shouldActivate) activatedDirection = "vertical";
 				}
 				if (directions.horizontal && isSwipingRight) {
 					shouldActivate = scrollCfg ? scrollCfg.x <= 0 : true;
+					if (shouldActivate) activatedDirection = "horizontal";
 				}
 				if (directions.verticalInverted && isSwipingUp) {
 					shouldActivate = scrollCfg ? scrollCfg.y >= maxScrollY : true;
+					if (shouldActivate) activatedDirection = "vertical-inverted";
 				}
 				if (directions.horizontalInverted && isSwipingLeft) {
 					shouldActivate = scrollCfg ? scrollCfg.x >= maxScrollX : true;
+					if (shouldActivate) activatedDirection = "horizontal-inverted";
 				}
 			}
 
@@ -176,29 +180,20 @@ export const useBuildGestures = ({
 				gestureOffsetState.value === GestureOffsetState.PASSED &&
 				!gestures.isDismissing?.value
 			) {
+				gestures.direction.value = activatedDirection;
 				manager.activate();
 				return;
 			}
 		},
-		[
-			initialTouch,
-			scrollConfig,
-			gestures,
-			directions,
-			gestureOffsetState,
-			dimensions,
-			gestureActivationArea,
-			gestureResponseDistance,
-		],
 	);
 
-	const onStart = useCallback(() => {
+	const onStart = useStableCallbackValue(() => {
 		"worklet";
 		gestures.isDragging.value = 1;
 		gestures.isDismissing.value = 0;
-	}, [gestures]);
+	});
 
-	const onUpdate = useCallback(
+	const onUpdate = useStableCallbackValue(
 		(event: GestureUpdateEvent<PanGestureHandlerEventPayload>) => {
 			"worklet";
 
@@ -263,10 +258,9 @@ export const useBuildGestures = ({
 				animations.progress.value = 1 - gestureProgress;
 			}
 		},
-		[dimensions, gestures, animations, gestureDrivesProgress, directions],
 	);
 
-	const onEnd = useCallback(
+	const onEnd = useStableCallbackValue(
 		(event: GestureStateChangeEvent<PanGestureHandlerEventPayload>) => {
 			"worklet";
 
@@ -307,16 +301,6 @@ export const useBuildGestures = ({
 				initialVelocity,
 			});
 		},
-		[
-			dimensions,
-			animations,
-			transitionSpec,
-			setNavigatorDismissal,
-			handleDismiss,
-			gestures,
-			directions,
-			gestureVelocityImpact,
-		],
 	);
 
 	return useMemo(() => {

package/src/hooks/use-stable-callback-value.tsx

@@ -0,0 +1,68 @@
+/**
+ * Credit:
+ * https://github.com/MatiPl01/react-native-sortables/blob/main/packages/react-native-sortables/src/integrations/reanimated/hooks/useStableCallbackValue.ts
+ */
+import { useCallback, useEffect, useState } from "react";
+import {
+	isWorkletFunction,
+	makeMutable,
+	runOnJS,
+} from "react-native-reanimated";
+
+// biome-ignore lint/suspicious/noExplicitAny: <Does not matter>
+type AnyFunction = (...args: Array<any>) => any;
+
+function useMutableValue<T>(initialValue: T) {
+	return useState(() => makeMutable(initialValue))[0];
+}
+
+// We cannot store a function as a SharedValue because reanimated will treat
+// it as an animation and will try to execute the animation when assigned
+// to the SharedValue. Since we want the function to be treated as a value,
+// we wrap it in an object and store the object in the SharedValue.
+type WrappedCallback<C extends AnyFunction> = {
+	call: C;
+};
+
+const wrap = <C extends AnyFunction>(callback: C): WrappedCallback<C> => {
+	if (isWorkletFunction(callback)) {
+		return { call: callback };
+	}
+	return {
+		call: ((...args: Parameters<C>) => {
+			"worklet";
+			runOnJS(callback)(...args);
+		}) as C,
+	};
+};
+
+/** Creates a stable worklet callback that can be called from the UI runtime
+ * @param callback The JavaScript or worklet function to be called
+ * @returns A worklet function that can be safely called from the UI thread
+ * @default Behavior:
+ * - If passed a regular JS function, calls it on the JS thread using runOnJS
+ * - If passed a worklet function, calls it directly on the UI thread
+ * @important The returned function maintains a stable reference and properly handles
+ * thread execution based on the input callback type
+ */
+export default function useStableCallbackValue<C extends AnyFunction>(
+	callback?: C,
+) {
+	const stableCallback = useMutableValue<null | WrappedCallback<C>>(null);
+
+	useEffect(() => {
+		if (callback) {
+			stableCallback.value = wrap(callback);
+		} else {
+			stableCallback.value = null;
+		}
+	}, [callback, stableCallback]);
+
+	return useCallback(
+		(...args: Parameters<C>) => {
+			"worklet";
+			stableCallback.value?.call(...args);
+		},
+		[stableCallback],
+	);
+}