react-native-screen-transitions 2.3.4 → 2.4.1

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/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,9 +18,10 @@ 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;
@@ -48,17 +49,18 @@ export const useBoundsRegistry = ({
 	onPress,
 }: BoundMeasurerHookProps) => {
 	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 emitUpdate = useCallback(() => {
+	const emitUpdate = useStableCallbackValue(() => {
 		"worklet";
 		if (IS_ROOT) ROOT_SIGNAL.value = ROOT_SIGNAL.value + 1;
-	}, [IS_ROOT, ROOT_SIGNAL]);
+	});
 
-	const maybeMeasureAndStore = useCallback(
+	const maybeMeasureAndStore = useStableCallbackValue(
 		({ onPress, skipMarkingActive }: MaybeMeasureAndStoreParams) => {
 			"worklet";
 			// Currently, there's no necessity to measure when the current route is blurred ( could potentially change in the future )
@@ -86,18 +88,17 @@ 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, next],
 	);
 
 	const hasMeasuredOnLayout = useSharedValue(false);
-	const handleInitialLayout = useCallback(() => {
+	const handleInitialLayout = useStableCallbackValue(() => {
 		"worklet";
 
 		const prevKey = previous?.route.key;
@@ -113,12 +114,7 @@ export const useBoundsRegistry = ({
 			// Should not measure again while in transition
 			hasMeasuredOnLayout.value = true;
 		}
-	}, [
-		maybeMeasureAndStore,
-		sharedBoundTag,
-		previous?.route.key,
-		hasMeasuredOnLayout,
-	]);
+	});
 
 	const captureActiveOnPress = useStableCallback(() => {
 		if (!sharedBoundTag) {

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],
+	);
+}

package/src/stores/gestures.ts

@@ -1,4 +1,5 @@
 import { makeMutable, type SharedValue } from "react-native-reanimated";
+import type { GestureDirection } from "../types/gesture";
 import type { ScreenKey } from "../types/navigator";
 
 export type GestureKey =
@@ -16,6 +17,7 @@ export type GestureMap = {
 	normalizedY: SharedValue<number>;
 	isDismissing: SharedValue<number>;
 	isDragging: SharedValue<number>;
+	direction: SharedValue<Omit<GestureDirection, "bidirectional"> | null>;
 };
 
 const store: Record<ScreenKey, GestureMap> = {};
@@ -30,6 +32,9 @@ function ensure(routeKey: ScreenKey): GestureMap {
 			normalizedY: makeMutable(0),
 			isDismissing: makeMutable(0),
 			isDragging: makeMutable(0),
+			direction: makeMutable<Omit<GestureDirection, "bidirectional"> | null>(
+				null,
+			),
 		};
 		store[routeKey] = bag;
 	}

package/src/types/animation.ts

@@ -18,10 +18,11 @@ export type ScreenTransitionState = {
 };
 
 export interface ScreenInterpolationProps {
-	/** Values for the screen that is the focus of the transition (e.g., the one opening). */
+	/** Values for the screen that came before the current one in the navigation stack. */
 	previous: ScreenTransitionState | undefined;
+	/** Values for the current screen being interpolated. */
 	current: ScreenTransitionState;
-	/** Values for the screen immediately behind the current one in the screen. */
+	/** Values for the screen that comes after the current one in the navigation stack. */
 	next: ScreenTransitionState | undefined;
 	/** Layout measurements for the screen. */
 	layouts: {
@@ -33,19 +34,19 @@ export interface ScreenInterpolationProps {
 	};
 	/** The safe area insets for the screen. */
 	insets: EdgeInsets;
-	/** The id of the active bound. */
+	/** The ID of the currently active shared bound (e.g., 'a' when Transition.Pressable has sharedBoundTag='a'). */
 	activeBoundId: string;
-	/** Whether the screen is focused. */
+	/** Whether the current screen is the focused (topmost) screen in the stack. */
 	focused: boolean;
-	/** The progress of the screen transitions (0-2). */
+	/** Combined progress of current and next screen transitions, ranging from 0-2. */
 	progress: number;
-	/** A function that returns a bounds builder for the screen. */
+	/** Function that provides access to bounds builders for creating shared element transitions. */
 	bounds: BoundsAccessor;
-	/** The active screen between current and next. */
+	/** The screen state that is currently driving the transition (either current or next, whichever is focused). */
 	active: ScreenTransitionState;
-	/** Whether the active screen is transitioning. */
+	/** Whether the active screen is currently transitioning (either being dragged or animating). */
 	isActiveTransitioning: boolean;
-	/** Whether the active screen is dismissing. */
+	/** Whether the active screen is in the process of being dismissed/closed. */
 	isDismissing: boolean;
 }
 

package/src/types/gesture.ts

@@ -49,4 +49,8 @@ export type GestureValues = {
 	 * A flag indicating if the screen is in the process of dismissing.
 	 */
 	isDismissing: number;
+	/**
+	 * The initial direction that activated the gesture.
+	 */
+	direction: Omit<GestureDirection, "bidirectional"> | null;
 };

package/src/types/utils.ts

@@ -1,3 +1,4 @@
+// biome-ignore lint/suspicious/noExplicitAny: <>
 export type Any = any;
 
 export type Complete<T> = { [K in keyof T]-?: Exclude<T[K], undefined> };

package/src/utils/bounds/_utils/styles.ts

@@ -0,0 +1,69 @@
+import type { ImageStyle, StyleProp, TextStyle, ViewStyle } from "react-native";
+import { isSharedValue } from "react-native-reanimated";
+import type { Any } from "../../../types/utils";
+
+type AnyStyle = ViewStyle | TextStyle | ImageStyle;
+type StyleValue = StyleProp<AnyStyle>;
+type PlainStyleObject = Record<string, Any>;
+
+function mergeStyleArrays<T extends StyleValue>(style: T): T {
+	"worklet";
+
+	// Early returns for non-objects
+	if (style === null || style === undefined || typeof style !== "object") {
+		return style;
+	}
+
+	// If not an array, return as-is
+	if (!Array.isArray(style)) {
+		return style;
+	}
+
+	// Merge array of styles into single object
+	const merged: PlainStyleObject = {};
+	for (let i = 0; i < style.length; i++) {
+		const currentStyle = mergeStyleArrays(style[i] as StyleValue);
+		if (currentStyle && typeof currentStyle === "object") {
+			Object.assign(merged, currentStyle);
+		}
+	}
+	return merged as T;
+}
+
+function stripNonSerializable<T>(value: T): T | undefined {
+	if (isSharedValue(value)) return value;
+
+	if (Array.isArray(value)) {
+		return value.map(stripNonSerializable) as T;
+	}
+
+	if (value && typeof value === "object") {
+		const cleaned: PlainStyleObject = {};
+		for (const key in value) {
+			if (key === "current") continue;
+
+			const cleanedValue = stripNonSerializable(value[key]);
+			if (cleanedValue !== undefined) {
+				cleaned[key] = cleanedValue;
+			}
+		}
+		return cleaned as T;
+	}
+
+	if (typeof value === "function") {
+		return undefined;
+	}
+
+	return value;
+}
+
+export function prepareStyleForBounds(
+	style: StyleValue | undefined,
+): PlainStyleObject {
+	if (!style) return {};
+
+	const flattened = mergeStyleArrays(style);
+	const serializable = stripNonSerializable(flattened);
+
+	return serializable || {};
+}

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

@@ -31,6 +31,7 @@ export const resetGestureValues = ({
 	const nx =
 		gestures.normalizedX.value ||
 		event.translationX / Math.max(1, dimensions.width);
+
 	const ny =
 		gestures.normalizedY.value ||
 		event.translationY / Math.max(1, dimensions.height);
@@ -38,11 +39,29 @@ export const resetGestureValues = ({
 	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 });
+	let remainingAnimations = 4;
+
+	const onFinish = (finished: boolean | undefined) => {
+		"worklet";
+		if (!finished) return;
+		remainingAnimations -= 1;
+		if (remainingAnimations === 0) {
+			gestures.direction.value = null;
+		}
+	};
 
-	gestures.normalizedX.value = animate(0, { ...spec, velocity: vxTowardZero });
-	gestures.normalizedY.value = animate(0, { ...spec, velocity: vyTowardZero });
+	gestures.x.value = animate(0, { ...spec, velocity: vxTowardZero }, onFinish);
+	gestures.y.value = animate(0, { ...spec, velocity: vyTowardZero }, onFinish);
+	gestures.normalizedX.value = animate(
+		0,
+		{ ...spec, velocity: vxTowardZero },
+		onFinish,
+	);
+	gestures.normalizedY.value = animate(
+		0,
+		{ ...spec, velocity: vyTowardZero },
+		onFinish,
+	);
 	gestures.isDragging.value = 0;
 	gestures.isDismissing.value = Number(shouldDismiss);
 };

package/src/utils/gesture/velocity.ts

@@ -41,11 +41,10 @@ const normalize = (velocityPixelsPerSecond: number, screenSize: number) => {
 const calculateRestoreVelocity = (
 	currentValueNormalized: number,
 	baseVelocityNormalized: number,
-	threshold: number = NEAR_ZERO_THRESHOLD,
 ) => {
 	"worklet";
 
-	if (Math.abs(currentValueNormalized) < threshold) return 0;
+	if (Math.abs(currentValueNormalized) < NEAR_ZERO_THRESHOLD) return 0;
 
 	const directionTowardZero = Math.sign(currentValueNormalized) || 1;
 	const clampedVelocity = Math.min(Math.abs(baseVelocityNormalized), 1);