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

package/src/shared/animation/snap-to.ts

@@ -0,0 +1,62 @@
+import { runOnUI } from "react-native-reanimated";
+import { DefaultSnapSpec } from "../configs/specs";
+import { AnimationStore } from "../stores/animation.store";
+import { HistoryStore } from "../stores/history.store";
+import { animateToProgress } from "../utils/animation/animate-to-progress";
+
+/**
+ * Programmatically snap the currently focused screen to a specific snap point.
+ *
+ * @param index - The index of the snap point to snap to (0-based, sorted ascending)
+ *
+ * @example
+ * ```tsx
+ * import { snapTo } from 'react-native-screen-transitions';
+ *
+ * // Snap to the first (smallest) snap point
+ * snapTo(0);
+ *
+ * // Snap to the last (largest) snap point
+ * snapTo(2); // if there are 3 snap points
+ * ```
+ */
+export function snapTo(index: number): void {
+	const recent = HistoryStore.getMostRecent();
+
+	if (!recent) {
+		console.warn("snapTo: No screen in history");
+		return;
+	}
+
+	const { descriptor } = recent;
+	const snapPoints = descriptor.options?.snapPoints;
+
+	if (!snapPoints || snapPoints.length === 0) {
+		console.warn("snapTo: No snapPoints defined on current screen");
+		return;
+	}
+
+	const sorted = [...snapPoints].sort((a, b) => a - b);
+
+	if (index < 0 || index >= sorted.length) {
+		console.warn(
+			`snapTo: index ${index} out of bounds (0-${sorted.length - 1})`,
+		);
+		return;
+	}
+
+	const targetProgress = sorted[index];
+	const animations = AnimationStore.getAll(descriptor.route.key);
+
+	runOnUI(() => {
+		"worklet";
+		animateToProgress({
+			target: targetProgress,
+			animations,
+			spec: {
+				open: descriptor.options.transitionSpec?.expand ?? DefaultSnapSpec,
+				close: descriptor.options.transitionSpec?.collapse ?? DefaultSnapSpec,
+			},
+		});
+	})();
+}

package/src/shared/constants.ts

@@ -4,6 +4,7 @@ import type { MeasuredDimensions } from "react-native-reanimated";
 import type { ScreenTransitionState } from "./types/animation.types";
 import type { ActivationArea } from "./types/gesture.types";
 import type { Layout } from "./types/screen.types";
+import type { BaseStackRoute } from "./types/stack.types";
 
 /**
  * Masked view integration
@@ -16,6 +17,35 @@ export const CONTAINER_STYLE_ID = "_ROOT_CONTAINER";
  */
 export const NO_STYLES = Object.freeze({});
 
+/**
+ * Default gesture values
+ */
+const DEFAULT_GESTURE_VALUES = {
+	x: 0,
+	y: 0,
+	normalizedX: 0,
+	normalizedY: 0,
+	isDismissing: 0,
+	isDragging: 0,
+	direction: null,
+} as const;
+
+/**
+ * Creates a new screen transition state object
+ */
+export const createScreenTransitionState = (
+	route: BaseStackRoute,
+	meta?: Record<string, unknown>,
+): ScreenTransitionState => ({
+	progress: 0,
+	closing: 0,
+	animating: 0,
+	entering: 1,
+	gesture: { ...DEFAULT_GESTURE_VALUES },
+	route,
+	meta,
+});
+
 /**
  * Default screen transition state
  */
@@ -25,15 +55,7 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 		closing: 0,
 		animating: 0,
 		entering: 1,
-		gesture: {
-			x: 0,
-			y: 0,
-			normalizedX: 0,
-			normalizedY: 0,
-			isDismissing: 0,
-			isDragging: 0,
-			direction: null,
-		},
+		gesture: DEFAULT_GESTURE_VALUES,
 		route: {} as RouteProp<ParamListBase>,
 	});
 
@@ -79,3 +101,8 @@ export const IS_WEB = Platform.OS === "web";
 
 export const TRUE = 1;
 export const FALSE = 0;
+
+/**
+ * Small value for floating-point comparisons to handle animation/interpolation imprecision
+ */
+export const EPSILON = 1e-5;

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

@@ -3,7 +3,10 @@ import { useWindowDimensions } from "react-native";
 import { type SharedValue, useDerivedValue } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import type { NativeStackScreenTransitionConfig } from "../../../native-stack/types";
-import { DEFAULT_SCREEN_TRANSITION_STATE } from "../../constants";
+import {
+	createScreenTransitionState,
+	DEFAULT_SCREEN_TRANSITION_STATE,
+} from "../../constants";
 import {
 	type BaseDescriptor,
 	useKeys,
@@ -31,26 +34,26 @@ type BuiltState = {
 	unwrapped: ScreenTransitionState;
 };
 
-const createScreenTransitionState = (
-	route: BaseStackRoute,
-	meta?: Record<string, unknown>,
-): ScreenTransitionState => ({
-	progress: 0,
-	closing: 0,
-	animating: 0,
-	entering: 1,
-	gesture: {
-		x: 0,
-		y: 0,
-		normalizedX: 0,
-		normalizedY: 0,
-		isDismissing: 0,
-		isDragging: 0,
-		direction: null,
-	},
-	route,
-	meta,
-});
+/**
+ * Computes the animated snap index based on progress and snap points.
+ * Returns -1 if no snap points, otherwise interpolates between indices.
+ */
+const computeSnapIndex = (progress: number, snapPoints: number[]): number => {
+	"worklet";
+	if (snapPoints.length === 0) return -1;
+	if (progress <= snapPoints[0]) return 0;
+	if (progress >= snapPoints[snapPoints.length - 1])
+		return snapPoints.length - 1;
+
+	for (let i = 0; i < snapPoints.length - 1; i++) {
+		if (progress <= snapPoints[i + 1]) {
+			const t =
+				(progress - snapPoints[i]) / (snapPoints[i + 1] - snapPoints[i]);
+			return i + t;
+		}
+	}
+	return snapPoints.length - 1;
+};
 
 const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 	"worklet";
@@ -123,6 +126,11 @@ export function _useScreenAnimation() {
 	const currentRouteKey = currentDescriptor?.route?.key;
 	const currentIndex = routeKeys.indexOf(currentRouteKey);
 
+	const sortedSnapPoints = useMemo(() => {
+		const points = currentDescriptor?.options?.snapPoints;
+		return points ? [...points].sort((a, b) => a - b) : [];
+	}, [currentDescriptor?.options?.snapPoints]);
+
 	const screenInterpolatorProps = useDerivedValue<
 		Omit<ScreenInterpolationProps, "bounds">
 	>(() => {
@@ -152,6 +160,8 @@ export function _useScreenAnimation() {
 		const stackProgress =
 			currentIndex >= 0 ? rootStackProgress.value - currentIndex : progress;
 
+		const snapIndex = computeSnapIndex(current.progress, sortedSnapPoints);
+
 		return {
 			layouts: { screen: dimensions },
 			insets,
@@ -160,6 +170,7 @@ export function _useScreenAnimation() {
 			next,
 			progress,
 			stackProgress,
+			snapIndex,
 			...helpers,
 		};
 	});

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

@@ -1,20 +1,12 @@
 import { StackActions } from "@react-navigation/native";
 import { useCallback, useMemo, useRef } from "react";
-import { useWindowDimensions } from "react-native";
 import { Gesture, type GestureType } from "react-native-gesture-handler";
 import type { SharedValue } from "react-native-reanimated";
-import {
-	DEFAULT_GESTURE_ACTIVATION_AREA,
-	DEFAULT_GESTURE_DIRECTION,
-	DEFAULT_GESTURE_DRIVES_PROGRESS,
-	GESTURE_VELOCITY_IMPACT,
-} from "../../constants";
 import type {
 	GestureContextType,
 	ScrollConfig,
 } from "../../providers/gestures.provider";
 import { useKeys } from "../../providers/screen/keys.provider";
-import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 import { useScreenGestureHandlers } from "./use-screen-gesture-handlers";
 
@@ -32,8 +24,6 @@ export const useBuildGestures = ({
 	nativeGesture: GestureType;
 	gestureAnimationValues: GestureStoreMap;
 } => {
-	const dimensions = useWindowDimensions();
-
 	const { current } = useKeys();
 
 	const navState = current.navigation.getState();
@@ -48,17 +38,8 @@ export const useBuildGestures = ({
 	const gestureAnimationValues = GestureStore.getRouteGestures(
 		current.route.key,
 	);
-	const animations = AnimationStore.getAll(current.route.key);
-
-	const {
-		gestureDirection = DEFAULT_GESTURE_DIRECTION,
-		gestureVelocityImpact = GESTURE_VELOCITY_IMPACT,
-		gestureDrivesProgress = DEFAULT_GESTURE_DRIVES_PROGRESS,
-		gestureActivationArea = DEFAULT_GESTURE_ACTIVATION_AREA,
-		gestureResponseDistance,
-		transitionSpec,
-		snapPoints,
-	} = current.options;
+
+	const { snapPoints } = current.options;
 
 	// Dismiss gesture is controlled by gestureEnabled (disabled for first screen)
 	const canDismiss = Boolean(
@@ -97,26 +78,13 @@ export const useBuildGestures = ({
 
 	const { onTouchesDown, onTouchesMove, onStart, onUpdate, onEnd } =
 		useScreenGestureHandlers({
-			dimensions,
-			animations,
-			gestureAnimationValues,
-			gestureDirection,
-			gestureDrivesProgress,
-			gestureVelocityImpact,
 			scrollConfig,
-			gestureActivationArea,
-			gestureResponseDistance,
-			snapPoints,
 			canDismiss,
-			transitionSpec,
 			handleDismiss,
 			ancestorIsDismissing:
 				ancestorContext?.gestureAnimationValues.isDismissing,
 		});
 
-	// Memoize gestures to keep stable references - critical for RNGH
-	// Child gestures reference ancestor's pan via requireExternalGestureToFail,
-	// so the pan gesture MUST be stable or children will reference stale objects
 	return useMemo(() => {
 		const panGesture = Gesture.Pan()
 			.withRef(panGestureRef)

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,12 @@ 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
+			// Also check targetProgress - if we're already animating toward max, scroll should win
 			const canExpandMore =
-				hasSnapPoints && animations.progress.value < maxSnapPoint - 0.01;
+				hasSnapPoints &&
+				animations.progress.value < maxSnapPoint - EPSILON &&
+				animations.targetProgress.value < maxSnapPoint - EPSILON;
 
 			const { shouldActivate, direction: activatedDirection } =
 				checkScrollAwareActivation({
@@ -212,10 +231,7 @@ export const useScreenGestureHandlers = ({
 						isSwipingLeft,
 					},
 					directions,
-					scrollX,
-					scrollY,
-					maxScrollX,
-					maxScrollY,
+					scrollConfig: scrollCfg,
 					hasSnapPoints,
 					canExpandMore,
 				});
@@ -242,6 +258,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 +268,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 +280,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 +298,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 +396,6 @@ export const useScreenGestureHandlers = ({
 					initialVelocity,
 				});
 			} else {
-				// Standard mode: use determineDismissal
 				const result = determineDismissal({
 					event,
 					directions,
@@ -403,7 +404,8 @@ export const useScreenGestureHandlers = ({
 				});
 
 				const shouldDismiss = result.shouldDismiss;
-				const targetProgress = shouldDismiss ? 0 : gestureStartProgress.value;
+				// Without snap points, always animate to fully visible (1) when not dismissing
+				const targetProgress = shouldDismiss ? 0 : 1;
 
 				resetGestureValues({
 					spec: shouldDismiss ? transitionSpec?.close : transitionSpec?.open,