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

package/src/shared/__tests__/validate-snap-points.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "bun:test";
+import { validateSnapPoints } from "../utils/gesture/validate-snap-points";
+
+describe("validateSnapPoints", () => {
+	describe("when no snap points provided", () => {
+		it("returns hasSnapPoints false", () => {
+			const result = validateSnapPoints({});
+			expect(result.hasSnapPoints).toBe(false);
+		});
+
+		it("returns empty snapPoints array", () => {
+			const result = validateSnapPoints({});
+			expect(result.snapPoints).toEqual([]);
+		});
+
+		it("returns -1 for min and max", () => {
+			const result = validateSnapPoints({});
+			expect(result.minSnapPoint).toBe(-1);
+			expect(result.maxSnapPoint).toBe(-1);
+		});
+
+		it("handles undefined snapPoints", () => {
+			const result = validateSnapPoints({ snapPoints: undefined });
+			expect(result.hasSnapPoints).toBe(false);
+		});
+	});
+
+	describe("when snap points provided", () => {
+		it("returns hasSnapPoints true", () => {
+			const result = validateSnapPoints({ snapPoints: [0.3, 0.6, 1] });
+			expect(result.hasSnapPoints).toBe(true);
+		});
+
+		it("sorts snap points in ascending order", () => {
+			const result = validateSnapPoints({ snapPoints: [1, 0.3, 0.6] });
+			expect(result.snapPoints).toEqual([0.3, 0.6, 1]);
+		});
+
+		it("returns correct max snap point", () => {
+			const result = validateSnapPoints({ snapPoints: [0.3, 0.6, 1] });
+			expect(result.maxSnapPoint).toBe(1);
+		});
+
+		it("handles single snap point", () => {
+			const result = validateSnapPoints({ snapPoints: [0.5] });
+			expect(result.hasSnapPoints).toBe(true);
+			expect(result.snapPoints).toEqual([0.5]);
+			expect(result.minSnapPoint).toBe(0.5);
+			expect(result.maxSnapPoint).toBe(0.5);
+		});
+
+		it("does not mutate original array", () => {
+			const original = [1, 0.3, 0.6];
+			validateSnapPoints({ snapPoints: original });
+			expect(original).toEqual([1, 0.3, 0.6]);
+		});
+	});
+
+	describe("canDismiss behavior", () => {
+		it("sets minSnapPoint to 0 when canDismiss is true", () => {
+			const result = validateSnapPoints({
+				snapPoints: [0.3, 0.6, 1],
+				canDismiss: true,
+			});
+			expect(result.minSnapPoint).toBe(0);
+		});
+
+		it("sets minSnapPoint to first snap point when canDismiss is false", () => {
+			const result = validateSnapPoints({
+				snapPoints: [0.3, 0.6, 1],
+				canDismiss: false,
+			});
+			expect(result.minSnapPoint).toBe(0.3);
+		});
+
+		it("defaults canDismiss to falsy (minSnapPoint = first snap)", () => {
+			const result = validateSnapPoints({ snapPoints: [0.3, 0.6, 1] });
+			expect(result.minSnapPoint).toBe(0.3);
+		});
+
+		it("handles canDismiss with unsorted snap points", () => {
+			const result = validateSnapPoints({
+				snapPoints: [1, 0.5, 0.25],
+				canDismiss: false,
+			});
+			// After sorting: [0.25, 0.5, 1]
+			expect(result.minSnapPoint).toBe(0.25);
+			expect(result.maxSnapPoint).toBe(1);
+		});
+	});
+
+	describe("edge cases", () => {
+		it("handles empty array", () => {
+			const result = validateSnapPoints({ snapPoints: [] });
+			// Empty array is falsy for snap points
+			expect(result.hasSnapPoints).toBe(true); // Array exists but is empty
+			expect(result.snapPoints).toEqual([]);
+		});
+
+		it("handles snap points at 0", () => {
+			const result = validateSnapPoints({
+				snapPoints: [0, 0.5, 1],
+				canDismiss: true,
+			});
+			expect(result.minSnapPoint).toBe(0);
+			expect(result.snapPoints).toEqual([0, 0.5, 1]);
+		});
+
+		it("handles duplicate snap points", () => {
+			const result = validateSnapPoints({ snapPoints: [0.5, 0.5, 1] });
+			expect(result.snapPoints).toEqual([0.5, 0.5, 1]);
+		});
+
+		it("handles very small snap point values", () => {
+			const result = validateSnapPoints({ snapPoints: [0.01, 0.1, 0.5] });
+			expect(result.minSnapPoint).toBe(0.01);
+			expect(result.maxSnapPoint).toBe(0.5);
+		});
+
+		it("handles snap points greater than 1", () => {
+			const result = validateSnapPoints({ snapPoints: [0.5, 1, 1.5] });
+			expect(result.maxSnapPoint).toBe(1.5);
+		});
+	});
+});

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

@@ -27,10 +27,18 @@ export function createTransitionAwareComponent<P extends object>(
 		TransitionAwareProps<P>
 	>((props: any, ref) => {
 		const { nativeGesture } = useGestureContext()!;
-		const { scrollHandler, onContentSizeChange, onLayout } = useScrollRegistry({
+		const {
+			scrollHandler,
+			onContentSizeChange,
+			onLayout,
+			onTouchStart,
+			onTouchEnd,
+		} = useScrollRegistry({
 			onScroll: props.onScroll,
 			onContentSizeChange: props.onContentSizeChange,
 			onLayout: props.onLayout,
+			onTouchStart: props.onTouchStart,
+			onTouchEnd: props.onTouchEnd,
 		});
 
 		return (
@@ -41,6 +49,8 @@ export function createTransitionAwareComponent<P extends object>(
 					onScroll={scrollHandler}
 					onContentSizeChange={onContentSizeChange}
 					onLayout={onLayout}
+					onTouchStart={onTouchStart}
+					onTouchEnd={onTouchEnd}
 					scrollEventThrottle={props.scrollEventThrottle || 16}
 				/>
 			</GestureDetector>

package/src/shared/components/screen-container.tsx

@@ -0,0 +1,65 @@
+import { StackActions } from "@react-navigation/native";
+import { memo, useCallback } from "react";
+import { Pressable, StyleSheet, View } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { NO_STYLES } from "../constants";
+import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
+import { useKeys } from "../providers/screen/keys.provider";
+import { useScreenStyles } from "../providers/screen/styles.provider";
+
+type Props = {
+	children: React.ReactNode;
+};
+
+export const ScreenContainer = memo(({ children }: Props) => {
+	const { stylesMap } = useScreenStyles();
+	const { current } = useKeys();
+	const { pointerEvents, backdropBehavior } = useBackdropPointerEvents();
+
+	const isDismissable = backdropBehavior === "dismiss";
+
+	const handleBackdropPress = useCallback(() => {
+		current.navigation.dispatch(StackActions.pop());
+	}, [current.navigation]);
+
+	const animatedContentStyle = useAnimatedStyle(() => {
+		"worklet";
+		return stylesMap.value.contentStyle || NO_STYLES;
+	});
+
+	const animatedBackdropStyle = useAnimatedStyle(() => {
+		"worklet";
+		return (
+			stylesMap.value.backdropStyle ?? stylesMap.value.overlayStyle ?? NO_STYLES
+		);
+	});
+
+	return (
+		<View style={styles.container} pointerEvents={pointerEvents}>
+			<Pressable
+				style={StyleSheet.absoluteFillObject}
+				pointerEvents={isDismissable ? "auto" : "none"}
+				onPress={isDismissable ? handleBackdropPress : undefined}
+			>
+				<Animated.View
+					style={[StyleSheet.absoluteFillObject, animatedBackdropStyle]}
+				/>
+			</Pressable>
+			<Animated.View
+				style={[styles.content, animatedContentStyle]}
+				pointerEvents={isDismissable ? "box-none" : pointerEvents}
+			>
+				{children}
+			</Animated.View>
+		</View>
+	);
+});
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+	},
+	content: {
+		flex: 1,
+	},
+});

package/src/shared/configs/presets.ts

@@ -208,7 +208,7 @@ export const ElasticCard = (
 				contentStyle: {
 					transform: [{ scale }, { translateX }, { translateY }],
 				},
-				overlayStyle: {
+				backdropStyle: {
 					backgroundColor: !next ? overlayColor : "rgba(0,0,0,0)",
 				},
 			};
@@ -281,7 +281,7 @@ export const SharedIGImage = ({
 				});
 
 				return {
-					overlayStyle: {
+					backdropStyle: {
 						backgroundColor: "black",
 						opacity: interpolate(progress, [0, 1], [0, 0.5]),
 					},
@@ -634,7 +634,7 @@ export const SharedXImage = ({
 					transform: [{ translateY: contentY }, { translateY: dragY }],
 					pointerEvents: current.animating ? "none" : "auto",
 				},
-				overlayStyle: {
+				backdropStyle: {
 					backgroundColor: overlayClr,
 				},
 			};

package/src/shared/configs/specs.ts

@@ -8,3 +8,9 @@ export const DefaultSpec: WithSpringConfig = {
 	// @ts-expect-error
 	restSpeedThreshold: 0.02,
 };
+
+export const DefaultSnapSpec: WithSpringConfig = {
+	stiffness: 500,
+	damping: 50,
+	mass: 1,
+};

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