react-native-screen-transitions 3.3.0-beta.0 → 3.3.0-beta.1

package/src/shared/hooks/gestures/use-screen-gesture-handlers.ts

@@ -1,4 +1,5 @@
 import { useMemo } from "react";
+import { useWindowDimensions } from "react-native";
 import type {
 	GestureStateChangeEvent,
 	GestureTouchEvent,
@@ -8,17 +9,20 @@ import type {
 import type { GestureStateManagerType } from "react-native-gesture-handler/lib/typescript/handlers/gestures/gestureStateManager";
 import { type SharedValue, useSharedValue } from "react-native-reanimated";
 import { DefaultSnapSpec } from "../../configs/specs";
-import { FALSE, TRUE } from "../../constants";
-import type { ScrollConfig } from "../../providers/gestures.provider";
-import type { AnimationStoreMap } from "../../stores/animation.store";
-import type { GestureStoreMap } from "../../stores/gesture.store";
-import type { TransitionSpec } from "../../types/animation.types";
 import {
-	type GestureActivationArea,
-	type GestureDirection,
-	GestureOffsetState,
-} from "../../types/gesture.types";
-import type { Layout } from "../../types/screen.types";
+	DEFAULT_GESTURE_ACTIVATION_AREA,
+	DEFAULT_GESTURE_DIRECTION,
+	DEFAULT_GESTURE_DRIVES_PROGRESS,
+	EPSILON,
+	FALSE,
+	GESTURE_VELOCITY_IMPACT,
+	TRUE,
+} from "../../constants";
+import type { ScrollConfig } from "../../providers/gestures.provider";
+import { useKeys } from "../../providers/screen/keys.provider";
+import { AnimationStore } from "../../stores/animation.store";
+import { GestureStore } from "../../stores/gesture.store";
+import { GestureOffsetState } from "../../types/gesture.types";
 import { animateToProgress } from "../../utils/animation/animate-to-progress";
 import {
 	applyOffsetRules,
@@ -30,50 +34,71 @@ import { mapGestureToProgress } from "../../utils/gesture/map-gesture-to-progres
 import { resetGestureValues } from "../../utils/gesture/reset-gesture-values";
 import { validateSnapPoints } from "../../utils/gesture/validate-snap-points";
 import { velocity } from "../../utils/gesture/velocity";
+import { logger } from "../../utils/logger";
 import useStableCallbackValue from "../use-stable-callback-value";
 
 interface UseScreenGestureHandlersProps {
-	dimensions: Layout;
-	animations: AnimationStoreMap;
-	gestureAnimationValues: GestureStoreMap;
-	gestureDirection: GestureDirection | GestureDirection[];
-	gestureDrivesProgress: boolean;
-	gestureVelocityImpact: number;
 	scrollConfig: SharedValue<ScrollConfig | null>;
-	gestureActivationArea: GestureActivationArea;
-	gestureResponseDistance?: number;
 	ancestorIsDismissing?: SharedValue<number> | null;
-	snapPoints?: number[];
 	canDismiss: boolean;
-	transitionSpec?: TransitionSpec;
 	handleDismiss: () => void;
 }
 
 export const useScreenGestureHandlers = ({
-	dimensions,
-	animations,
-	gestureAnimationValues,
-	gestureDirection,
-	gestureDrivesProgress,
-	gestureVelocityImpact,
 	scrollConfig,
-	gestureActivationArea,
-	gestureResponseDistance,
 	ancestorIsDismissing,
-	snapPoints: rawSnapPoints,
 	canDismiss,
-	transitionSpec,
 	handleDismiss,
 }: UseScreenGestureHandlersProps) => {
+	const dimensions = useWindowDimensions();
+	const { current } = useKeys();
+
+	const animations = AnimationStore.getAll(current.route.key);
+	const gestureAnimationValues = GestureStore.getRouteGestures(
+		current.route.key,
+	);
+
+	const {
+		gestureDirection = DEFAULT_GESTURE_DIRECTION,
+		gestureDrivesProgress = DEFAULT_GESTURE_DRIVES_PROGRESS,
+		gestureVelocityImpact = GESTURE_VELOCITY_IMPACT,
+		gestureActivationArea = DEFAULT_GESTURE_ACTIVATION_AREA,
+		gestureResponseDistance,
+		transitionSpec,
+		snapPoints: rawSnapPoints,
+	} = current.options;
+
 	const { hasSnapPoints, snapPoints, minSnapPoint, maxSnapPoint } = useMemo(
 		() => validateSnapPoints({ snapPoints: rawSnapPoints, canDismiss }),
 		[rawSnapPoints, canDismiss],
 	);
 
 	const directions = useMemo(() => {
-		const directionsArray = Array.isArray(gestureDirection)
-			? gestureDirection
-			: [gestureDirection];
+		if (hasSnapPoints && Array.isArray(gestureDirection)) {
+			/**
+			 * Unsure if this behavior will change in the future, as I cannot find a use case as to why
+			 * you would want multiple gesture dismisals for a sheet.
+			 *
+			 * e.g. When defining a snap point with a gesture of vertical ( default ), the system
+			 * assumes that the inverse ( vertical-inverted ), will grow the sheet.
+			 */
+			logger.warn(
+				`gestureDirection array is not supported with snapPoints. ` +
+					`Only the first direction "${gestureDirection[0]}" will be used. ` +
+					`Snap points define a single axis of movement, so only one gesture direction is needed.`,
+			);
+		}
+
+		// When snap points are defined, use only the first direction from the array
+		const effectiveDirection = hasSnapPoints
+			? Array.isArray(gestureDirection)
+				? gestureDirection[0]
+				: gestureDirection
+			: gestureDirection;
+
+		const directionsArray = Array.isArray(effectiveDirection)
+			? effectiveDirection
+			: [effectiveDirection];
 
 		const isBidirectional = directionsArray.includes("bidirectional");
 
@@ -128,7 +153,7 @@ export const useScreenGestureHandlers = ({
 
 			// If an ancestor navigator is already dismissing via gesture, block new gestures here.
 			if (ancestorIsDismissing?.value) {
-				gestureOffsetState.set(GestureOffsetState.FAILED);
+				gestureOffsetState.value = GestureOffsetState.FAILED;
 				manager.fail();
 				return;
 			}
@@ -176,13 +201,13 @@ export const useScreenGestureHandlers = ({
 				}
 
 				if (isSwipingDown) {
-					gestureAnimationValues.direction.set("vertical");
+					gestureAnimationValues.direction.value = "vertical";
 				} else if (isSwipingUp) {
-					gestureAnimationValues.direction.set("vertical-inverted");
+					gestureAnimationValues.direction.value = "vertical-inverted";
 				} else if (isSwipingRight) {
-					gestureAnimationValues.direction.set("horizontal");
+					gestureAnimationValues.direction.value = "horizontal";
 				} else if (isSwipingLeft) {
-					gestureAnimationValues.direction.set("horizontal-inverted");
+					gestureAnimationValues.direction.value = "horizontal-inverted";
 				}
 
 				manager.activate();
@@ -190,18 +215,9 @@ export const useScreenGestureHandlers = ({
 			}
 
 			// Touch IS on ScrollView - apply scroll-aware rules
-			const scrollX = scrollCfg?.x ?? 0;
-			const scrollY = scrollCfg?.y ?? 0;
-			const maxScrollX = scrollCfg?.contentWidth
-				? scrollCfg.contentWidth - scrollCfg.layoutWidth
-				: 0;
-			const maxScrollY = scrollCfg?.contentHeight
-				? scrollCfg.contentHeight - scrollCfg.layoutHeight
-				: 0;
-
 			// Snap mode: determine if sheet can still expand
 			const canExpandMore =
-				hasSnapPoints && animations.progress.value < maxSnapPoint - 0.01;
+				hasSnapPoints && animations.progress.value < maxSnapPoint - EPSILON;
 
 			const { shouldActivate, direction: activatedDirection } =
 				checkScrollAwareActivation({
@@ -212,10 +228,7 @@ export const useScreenGestureHandlers = ({
 						isSwipingLeft,
 					},
 					directions,
-					scrollX,
-					scrollY,
-					maxScrollX,
-					maxScrollY,
+					scrollConfig: scrollCfg,
 					hasSnapPoints,
 					canExpandMore,
 				});
@@ -242,6 +255,7 @@ export const useScreenGestureHandlers = ({
 		gestureAnimationValues.isDragging.value = TRUE;
 		gestureAnimationValues.isDismissing.value = FALSE;
 		gestureStartProgress.value = animations.progress.value;
+		animations.animating.value = TRUE;
 	});
 
 	const onUpdate = useStableCallbackValue(
@@ -251,7 +265,6 @@ export const useScreenGestureHandlers = ({
 			const { translationX, translationY } = event;
 			const { width, height } = dimensions;
 
-			// Update gesture values (shared across all modes)
 			gestureAnimationValues.x.value = translationX;
 			gestureAnimationValues.y.value = translationY;
 			gestureAnimationValues.normalizedX.value = velocity.normalizeTranslation(
@@ -264,7 +277,6 @@ export const useScreenGestureHandlers = ({
 			);
 
 			if (hasSnapPoints && gestureDrivesProgress) {
-				// Snap mode: bidirectional tracking on snap axis
 				const isHorizontal = snapAxis === "horizontal";
 				const translation = isHorizontal ? translationX : translationY;
 				const dimension = isHorizontal ? width : height;
@@ -283,43 +295,30 @@ export const useScreenGestureHandlers = ({
 					Math.min(maxSnapPoint, gestureStartProgress.value + progressDelta),
 				);
 			} else if (gestureDrivesProgress) {
-				// Standard mode: find max progress across allowed directions
-				const axes = [
-					{
-						enabled: directions.horizontal,
-						translation: translationX,
-						dimension: width,
-						sign: 1,
-					},
-					{
-						enabled: directions.horizontalInverted,
-						translation: translationX,
-						dimension: width,
-						sign: -1,
-					},
-					{
-						enabled: directions.vertical,
-						translation: translationY,
-						dimension: height,
-						sign: 1,
-					},
-					{
-						enabled: directions.verticalInverted,
-						translation: translationY,
-						dimension: height,
-						sign: -1,
-					},
-				];
-
 				let maxProgress = 0;
-				for (const axis of axes) {
-					if (axis.enabled && axis.translation * axis.sign > 0) {
-						const progress = mapGestureToProgress(
-							Math.abs(axis.translation),
-							axis.dimension,
-						);
-						maxProgress = Math.max(maxProgress, progress);
-					}
+
+				// Horizontal swipe right (positive X)
+				if (directions.horizontal && translationX > 0) {
+					const progress = mapGestureToProgress(translationX, width);
+					maxProgress = Math.max(maxProgress, progress);
+				}
+
+				// Horizontal inverted swipe left (negative X)
+				if (directions.horizontalInverted && translationX < 0) {
+					const progress = mapGestureToProgress(-translationX, width);
+					maxProgress = Math.max(maxProgress, progress);
+				}
+
+				// Vertical swipe down (positive Y)
+				if (directions.vertical && translationY > 0) {
+					const progress = mapGestureToProgress(translationY, height);
+					maxProgress = Math.max(maxProgress, progress);
+				}
+
+				// Vertical inverted swipe up (negative Y)
+				if (directions.verticalInverted && translationY < 0) {
+					const progress = mapGestureToProgress(-translationY, height);
+					maxProgress = Math.max(maxProgress, progress);
 				}
 
 				animations.progress.value = Math.max(
@@ -394,7 +393,6 @@ export const useScreenGestureHandlers = ({
 					initialVelocity,
 				});
 			} else {
-				// Standard mode: use determineDismissal
 				const result = determineDismissal({
 					event,
 					directions,

package/src/shared/hooks/navigation/use-screen-state.tsx

@@ -1,10 +1,6 @@
 import type { Route } from "@react-navigation/native";
 import { useCallback, useMemo } from "react";
-import {
-	runOnUI,
-	type SharedValue,
-	useDerivedValue,
-} from "react-native-reanimated";
+import { runOnUI, useDerivedValue } from "react-native-reanimated";
 import { DefaultSnapSpec } from "../../configs/specs";
 import {
 	type BaseDescriptor,
@@ -62,13 +58,6 @@ export interface ScreenState<
 	 * @param index - The index of the snap point to snap to (0-based)
 	 */
 	snapTo: (index: number) => void;
-
-	/**
-	 * Animated value representing the current snap point index.
-	 * Interpolates between indices during gestures (e.g., 0.5 means halfway between snap 0 and 1).
-	 * Returns -1 if no snap points are defined.
-	 */
-	animatedSnapIndex: SharedValue<number>;
 }
 
 /**
@@ -100,63 +89,29 @@ export function useScreenState<
 	}, [scenes, focusedIndex]);
 
 	const currentOptions = current.options;
-	const snapPoints = currentOptions?.snapPoints;
 	const animations = useMemo(
 		() => AnimationStore.getAll(current.route.key),
 		[current.route.key],
 	);
 
-	// Pre-sort snap points for the derived value (avoids sorting in worklet)
-	const sortedSnapPoints = useMemo(
-		() => (snapPoints ? [...snapPoints].sort((a, b) => a - b) : []),
-		[snapPoints],
-	);
-
-	const animatedSnapIndex = useDerivedValue(() => {
-		if (sortedSnapPoints.length === 0) {
-			return -1;
-		}
-
-		const progress = animations.progress.value;
-
-		// Below first snap point
-		if (progress <= sortedSnapPoints[0]) {
-			return 0;
-		}
-
-		// Above last snap point
-		if (progress >= sortedSnapPoints[sortedSnapPoints.length - 1]) {
-			return sortedSnapPoints.length - 1;
-		}
-
-		// Find segment and interpolate
-		for (let i = 0; i < sortedSnapPoints.length - 1; i++) {
-			if (progress <= sortedSnapPoints[i + 1]) {
-				const t =
-					(progress - sortedSnapPoints[i]) /
-					(sortedSnapPoints[i + 1] - sortedSnapPoints[i]);
-				return i + t;
-			}
-		}
-
-		return sortedSnapPoints.length - 1;
-	});
-
 	const snapTo = useCallback(
 		(targetIndex: number) => {
-			if (!sortedSnapPoints || sortedSnapPoints.length === 0) {
+			const points = currentOptions?.snapPoints;
+			if (!points || points.length === 0) {
 				console.warn("snapTo called but no snapPoints defined");
 				return;
 			}
 
-			if (targetIndex < 0 || targetIndex >= sortedSnapPoints.length) {
+			const sorted = [...points].sort((a, b) => a - b);
+
+			if (targetIndex < 0 || targetIndex >= sorted.length) {
 				console.warn(
-					`snapTo index ${targetIndex} out of bounds (0-${sortedSnapPoints.length - 1})`,
+					`snapTo index ${targetIndex} out of bounds (0-${sorted.length - 1})`,
 				);
 				return;
 			}
 
-			const targetProgress = sortedSnapPoints[targetIndex];
+			const targetProgress = sorted[targetIndex];
 
 			runOnUI(() => {
 				"worklet";
@@ -174,7 +129,7 @@ export function useScreenState<
 				});
 			})();
 		},
-		[sortedSnapPoints, animations, focusedScene],
+		[currentOptions?.snapPoints, animations, focusedScene],
 	);
 
 	return useMemo(
@@ -187,7 +142,6 @@ export function useScreenState<
 			meta: focusedScene?.descriptor?.options?.meta,
 			navigation: current.navigation as TNavigation,
 			snapTo,
-			animatedSnapIndex,
 		}),
 		[
 			index,
@@ -197,7 +151,6 @@ export function useScreenState<
 			current.navigation,
 			current.route,
 			snapTo,
-			animatedSnapIndex,
 		],
 	);
 }

package/src/shared/types/animation.types.ts

@@ -142,6 +142,16 @@ export interface ScreenInterpolationProps {
 	 */
 	stackProgress: number;
 
+	/**
+	 * Animated index of the current snap point.
+	 * Interpolates between indices during gestures/animations.
+	 * - Returns -1 if no snap points are defined
+	 * - Returns 0 when at or below first snap point
+	 * - Returns fractional values between snap points (e.g., 1.5 = halfway between snap 1 and 2)
+	 * - Returns length-1 when at or above last snap point
+	 */
+	snapIndex: number;
+
 	/**
 	 * Function that provides access to bounds builders for creating shared element transitions.
 	 */

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

@@ -73,7 +73,10 @@ export const animateToProgress = ({
 				runOnJS(onAnimationFinish)(finished);
 			}
 
-			animating.set(FALSE);
+			// Delay setting animating=FALSE by one frame to ensure final frame is painted
+			requestAnimationFrame(() => {
+				animating.set(FALSE);
+			});
 		}),
 	);
 };

package/src/shared/utils/gesture/check-gesture-activation.ts

@@ -1,5 +1,6 @@
 import type { GestureStateManagerType } from "react-native-gesture-handler/lib/typescript/handlers/gestures/gestureStateManager";
 import type { SharedValue } from "react-native-reanimated";
+import type { ScrollConfig } from "../../providers/gestures.provider";
 import {
 	type ActivationArea,
 	type GestureActivationArea,
@@ -13,6 +14,7 @@ type Directions = {
 	verticalInverted: boolean;
 	horizontal: boolean;
 	horizontalInverted: boolean;
+	snapAxisInverted?: boolean;
 };
 
 interface CheckGestureActivationProps {
@@ -317,10 +319,7 @@ interface ScrollAwareActivationParams {
 		isSwipingLeft: boolean;
 	};
 	directions: Directions;
-	scrollX: number;
-	scrollY: number;
-	maxScrollX: number;
-	maxScrollY: number;
+	scrollConfig: ScrollConfig | null;
 	hasSnapPoints?: boolean;
 	canExpandMore?: boolean;
 }
@@ -338,10 +337,7 @@ type GestureDirection =
 export function checkScrollAwareActivation({
 	swipeInfo,
 	directions,
-	scrollX,
-	scrollY,
-	maxScrollX,
-	maxScrollY,
+	scrollConfig,
 	hasSnapPoints,
 	canExpandMore,
 }: ScrollAwareActivationParams): {
@@ -353,6 +349,76 @@ export function checkScrollAwareActivation({
 	const { isSwipingDown, isSwipingUp, isSwipingRight, isSwipingLeft } =
 		swipeInfo;
 
+	// Extract scroll values from config
+	const scrollX = scrollConfig?.x ?? 0;
+	const scrollY = scrollConfig?.y ?? 0;
+	const maxScrollX = scrollConfig
+		? scrollConfig.contentWidth - scrollConfig.layoutWidth
+		: 0;
+	const maxScrollY = scrollConfig
+		? scrollConfig.contentHeight - scrollConfig.layoutHeight
+		: 0;
+	const snapAxisInverted = directions.snapAxisInverted;
+
+	// With snap points, gestures should only activate based on the PRIMARY scroll edge
+	// (the edge where the sheet originates from), not the opposite edge.
+	// This prevents the auto-enabled opposite direction from hijacking scrolls.
+	if (hasSnapPoints) {
+		const isVerticalAxis = directions.vertical || directions.verticalInverted;
+		const isHorizontalAxis =
+			directions.horizontal || directions.horizontalInverted;
+
+		if (isVerticalAxis) {
+			if (snapAxisInverted) {
+				// Sheet from TOP (vertical-inverted): only activate at scroll BOTTOM
+				if (scrollY >= maxScrollY) {
+					if (isSwipingUp) {
+						return { shouldActivate: true, direction: "vertical-inverted" };
+					}
+					if (isSwipingDown && canExpandMore) {
+						return { shouldActivate: true, direction: "vertical" };
+					}
+				}
+			} else {
+				// Sheet from BOTTOM (vertical): only activate at scroll TOP
+				if (scrollY <= 0) {
+					if (isSwipingDown) {
+						return { shouldActivate: true, direction: "vertical" };
+					}
+					if (isSwipingUp && canExpandMore) {
+						return { shouldActivate: true, direction: "vertical-inverted" };
+					}
+				}
+			}
+		}
+
+		if (isHorizontalAxis) {
+			if (snapAxisInverted) {
+				// Sheet from LEFT (horizontal-inverted): only activate at scroll RIGHT
+				if (scrollX >= maxScrollX) {
+					if (isSwipingLeft) {
+						return { shouldActivate: true, direction: "horizontal-inverted" };
+					}
+					if (isSwipingRight && canExpandMore) {
+						return { shouldActivate: true, direction: "horizontal" };
+					}
+				}
+			} else {
+				// Sheet from RIGHT (horizontal): only activate at scroll LEFT
+				if (scrollX <= 0) {
+					if (isSwipingRight) {
+						return { shouldActivate: true, direction: "horizontal" };
+					}
+					if (isSwipingLeft && canExpandMore) {
+						return { shouldActivate: true, direction: "horizontal-inverted" };
+					}
+				}
+			}
+		}
+
+		return { shouldActivate: false, direction: null };
+	}
+
 	if (directions.vertical && isSwipingDown && scrollY <= 0) {
 		return { shouldActivate: true, direction: "vertical" };
 	}
@@ -369,20 +435,5 @@ export function checkScrollAwareActivation({
 		return { shouldActivate: true, direction: "horizontal-inverted" };
 	}
 
-	if (hasSnapPoints && canExpandMore) {
-		// Vertical sheet: swipe up at scroll top → expand
-		const enabledYAxis = directions.vertical || directions.verticalInverted;
-		const enabledXAxis = directions.horizontal || directions.horizontalInverted;
-
-		if (enabledYAxis && isSwipingUp && scrollY <= 0) {
-			return { shouldActivate: true, direction: "vertical-inverted" };
-		}
-
-		// Horizontal sheet: swipe left at scroll left → expand
-		if (enabledXAxis && isSwipingLeft && scrollX <= 0) {
-			return { shouldActivate: true, direction: "horizontal-inverted" };
-		}
-	}
-
 	return { shouldActivate: false, direction: null };
 }

package/src/shared/utils/logger.ts

@@ -0,0 +1,15 @@
+const LIBRARY_NAME = "react-native-screen-transitions";
+
+export const logger = {
+	error(message: string) {
+		"worklet";
+		console.error(`[${LIBRARY_NAME}] ${message}`);
+	},
+	warn(message: string) {
+		"worklet";
+		console.warn(`[${LIBRARY_NAME}] ${message}`);
+	},
+};
+
+export const error = (message: string) =>
+	new Error(`[${LIBRARY_NAME}] ${message}`);