react-native-screen-transitions 3.3.0-rc.3 → 3.4.0-alpha.0

package/src/shared/providers/gestures/helpers/gesture-directions.ts

@@ -0,0 +1,97 @@
+import type {
+	GestureDirection,
+	GestureDirections,
+} from "../../../types/gesture.types";
+import type { Direction } from "../../../types/ownership.types";
+import { logger } from "../../../utils/logger";
+
+interface ResolveGestureDirectionsProps {
+	gestureDirection: GestureDirection | GestureDirection[];
+	hasSnapPoints: boolean;
+}
+
+export const warnOnSnapDirectionArray = ({
+	gestureDirection,
+	hasSnapPoints,
+}: ResolveGestureDirectionsProps) => {
+	if (!hasSnapPoints || !Array.isArray(gestureDirection)) return;
+
+	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.`,
+	);
+};
+
+export const resolveGestureDirections = ({
+	gestureDirection,
+	hasSnapPoints,
+}: ResolveGestureDirectionsProps): GestureDirections => {
+	const effectiveDirection = hasSnapPoints
+		? Array.isArray(gestureDirection)
+			? gestureDirection[0]
+			: gestureDirection
+		: gestureDirection;
+
+	const directionsArray = Array.isArray(effectiveDirection)
+		? effectiveDirection
+		: [effectiveDirection];
+
+	const isBidirectional = directionsArray.includes("bidirectional");
+
+	const hasHorizontalDirection =
+		directionsArray.includes("horizontal") ||
+		directionsArray.includes("horizontal-inverted");
+
+	const isSnapAxisInverted = hasHorizontalDirection
+		? directionsArray.includes("horizontal-inverted") &&
+			!directionsArray.includes("horizontal")
+		: directionsArray.includes("vertical-inverted") &&
+			!directionsArray.includes("vertical");
+
+	const enableBothVertical =
+		isBidirectional || (hasSnapPoints && !hasHorizontalDirection);
+	const enableBothHorizontal =
+		isBidirectional || (hasSnapPoints && hasHorizontalDirection);
+
+	return {
+		vertical: directionsArray.includes("vertical") || enableBothVertical,
+		verticalInverted:
+			directionsArray.includes("vertical-inverted") || enableBothVertical,
+		horizontal: directionsArray.includes("horizontal") || enableBothHorizontal,
+		horizontalInverted:
+			directionsArray.includes("horizontal-inverted") || enableBothHorizontal,
+		snapAxisInverted: hasSnapPoints && isSnapAxisInverted,
+	};
+};
+
+export const getSnapAxis = (
+	directions: GestureDirections,
+): "horizontal" | "vertical" => {
+	return directions.horizontal || directions.horizontalInverted
+		? "horizontal"
+		: "vertical";
+};
+
+export const isExpandGestureForDirection = (
+	swipeDirection: Direction,
+	snapAxis: "horizontal" | "vertical",
+	snapAxisInverted: boolean,
+): boolean => {
+	"worklet";
+	if (snapAxis === "horizontal") {
+		return snapAxisInverted
+			? swipeDirection === "horizontal"
+			: swipeDirection === "horizontal-inverted";
+	}
+
+	return snapAxisInverted
+		? swipeDirection === "vertical"
+		: swipeDirection === "vertical-inverted";
+};
+
+export const clampVelocity = (value: number, maxMagnitude: number) => {
+	"worklet";
+	const max = Math.max(0, Math.abs(maxMagnitude));
+	return Math.max(-max, Math.min(max, value));
+};

package/src/shared/{utils/gesture/velocity.ts → providers/gestures/helpers/gesture-physics.ts}

@@ -3,42 +3,49 @@ import type {
 	PanGestureHandlerEventPayload,
 } from "react-native-gesture-handler";
 import { clamp } from "react-native-reanimated";
-import { ANIMATION_SNAP_THRESHOLD, EPSILON } from "../../constants";
-import type { AnimationStoreMap } from "../../stores/animation.store";
+import {
+	ANIMATION_SNAP_THRESHOLD,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+	EPSILON,
+} from "../../../constants";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+import type { GestureDirections } from "../../../types/gesture.types";
 
 interface CalculateProgressProps {
 	animations: AnimationStoreMap;
 	shouldDismiss: boolean;
 	event: GestureStateChangeEvent<PanGestureHandlerEventPayload>;
 	dimensions: { width: number; height: number };
-	directions: {
-		horizontal: boolean;
-		horizontalInverted: boolean;
-		vertical: boolean;
-		verticalInverted: boolean;
-	};
+	directions: GestureDirections;
 }
 
-const MAX_VELOCITY_MAGNITUDE = 3.2;
+type GestureAxisCandidate = {
+	progressContribution: number;
+	velocityContribution: number;
+};
 
 /**
  * Converts velocity from pixels/second to normalized units/second (0-1 range)
  * and caps the result for stability
  */
-const normalize = (velocityPixelsPerSecond: number, screenSize: number) => {
+export const normalizeVelocity = (
+	velocityPixelsPerSecond: number,
+	screenSize: number,
+	maxMagnitude: number = DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+) => {
 	"worklet";
-	return clamp(
-		velocityPixelsPerSecond / Math.max(1, screenSize),
-		-MAX_VELOCITY_MAGNITUDE,
-		MAX_VELOCITY_MAGNITUDE,
-	);
+	const max = Math.max(0, Math.abs(maxMagnitude));
+	return clamp(velocityPixelsPerSecond / Math.max(1, screenSize), -max, max);
 };
 
 /**
  * Normalizes translation to -1...1 range (for gesture tracking).
  * Used to convert pixel translation to normalized gesture values.
  */
-const normalizeTranslation = (translation: number, dimension: number) => {
+export const normalizeGestureTranslation = (
+	translation: number,
+	dimension: number,
+) => {
 	"worklet";
 	return clamp(translation / Math.max(1, dimension), -1, 1);
 };
@@ -47,7 +54,7 @@ const normalizeTranslation = (translation: number, dimension: number) => {
  * Calculates a normalized velocity that moves the current value toward zero.
  * Used for spring-back animations when dismissing gestures.
  */
-const calculateRestoreVelocity = (
+export const calculateRestoreVelocityTowardZero = (
 	currentValueNormalized: number,
 	baseVelocityNormalized: number,
 ) => {
@@ -61,7 +68,7 @@ const calculateRestoreVelocity = (
 	return -directionTowardZero * clampedVelocity;
 };
 
-const calculateProgressVelocity = ({
+export const calculateProgressSpringVelocity = ({
 	animations,
 	shouldDismiss,
 	event,
@@ -76,34 +83,69 @@ const calculateProgressVelocity = ({
 
 	const progressDirection = progressDelta === 0 ? 0 : Math.sign(progressDelta);
 
-	const normalizedVelocityX = normalize(event.velocityX, dimensions.width);
-	const normalizedVelocityY = normalize(event.velocityY, dimensions.height);
+	const candidates: GestureAxisCandidate[] = [];
 
-	const normalizedTranslationX = Math.abs(
-		event.translationX / dimensions.width,
-	);
-	const normalizedTranslationY = Math.abs(
-		event.translationY / dimensions.height,
-	);
+	if (directions.horizontal && event.translationX > 0) {
+		candidates.push({
+			progressContribution: event.translationX / Math.max(1, dimensions.width),
+			velocityContribution: normalizeVelocity(
+				event.velocityX,
+				dimensions.width,
+			),
+		});
+	}
+
+	if (directions.horizontalInverted && event.translationX < 0) {
+		candidates.push({
+			progressContribution: -event.translationX / Math.max(1, dimensions.width),
+			velocityContribution: normalizeVelocity(
+				-event.velocityX,
+				dimensions.width,
+			),
+		});
+	}
 
-	const supportsHorizontalGestures =
-		directions.horizontal || directions.horizontalInverted;
+	if (directions.vertical && event.translationY > 0) {
+		candidates.push({
+			progressContribution: event.translationY / Math.max(1, dimensions.height),
+			velocityContribution: normalizeVelocity(
+				event.velocityY,
+				dimensions.height,
+			),
+		});
+	}
 
-	const supportsVerticalGestures =
-		directions.vertical || directions.verticalInverted;
+	if (directions.verticalInverted && event.translationY < 0) {
+		candidates.push({
+			progressContribution:
+				-event.translationY / Math.max(1, dimensions.height),
+			velocityContribution: normalizeVelocity(
+				-event.velocityY,
+				dimensions.height,
+			),
+		});
+	}
 
 	let progressVelocityMagnitude = 0;
 
-	// Determine which axis should drive the progress velocity
-	if (
-		supportsHorizontalGestures &&
-		(!supportsVerticalGestures ||
-			normalizedTranslationX >= normalizedTranslationY)
-	) {
-		progressVelocityMagnitude = Math.abs(normalizedVelocityX);
-	} else if (supportsVerticalGestures) {
-		progressVelocityMagnitude = Math.abs(normalizedVelocityY);
+	if (candidates.length > 0) {
+		let dominant = candidates[0];
+		for (let i = 1; i < candidates.length; i++) {
+			const candidate = candidates[i];
+			if (candidate.progressContribution > dominant.progressContribution) {
+				dominant = candidate;
+			}
+		}
+		progressVelocityMagnitude = Math.abs(dominant.velocityContribution);
 	} else {
+		const normalizedVelocityX = normalizeVelocity(
+			event.velocityX,
+			dimensions.width,
+		);
+		const normalizedVelocityY = normalizeVelocity(
+			event.velocityY,
+			dimensions.height,
+		);
 		progressVelocityMagnitude = Math.max(
 			Math.abs(normalizedVelocityX),
 			Math.abs(normalizedVelocityY),
@@ -113,7 +155,7 @@ const calculateProgressVelocity = ({
 	// Apply direction and clamp to prevent overly energetic springs
 	return (
 		progressDirection *
-		clamp(progressVelocityMagnitude, 0, MAX_VELOCITY_MAGNITUDE)
+		clamp(progressVelocityMagnitude, 0, DEFAULT_GESTURE_RELEASE_VELOCITY_MAX)
 	);
 };
 
@@ -123,7 +165,7 @@ const calculateProgressVelocity = ({
  *
  * Formula: |translation/screen + clamp(velocity/screen, ±1) * velocityWeight| > 0.5
  */
-const shouldPassDismissalThreshold = (
+export const shouldDismissFromTranslationAndVelocity = (
 	translationPixels: number,
 	velocityPixelsPerSecond: number,
 	screenSize: number,
@@ -139,7 +181,10 @@ const shouldPassDismissalThreshold = (
 		return false;
 	}
 
-	const normalizedVelocity = normalize(velocityPixelsPerSecond, screenSize);
+	const normalizedVelocity = normalizeVelocity(
+		velocityPixelsPerSecond,
+		screenSize,
+	);
 
 	const projectedNormalizedPosition =
 		normalizedTranslation + normalizedVelocity * velocityWeight;
@@ -154,10 +199,14 @@ const shouldPassDismissalThreshold = (
 	return exceedsThreshold;
 };
 
-export const velocity = {
-	normalize,
-	normalizeTranslation,
-	calculateRestoreVelocity,
-	calculateProgressVelocity,
-	shouldPassDismissalThreshold,
+/**
+ * Utility function to map raw gesture translation to a progress value.
+ */
+export const mapGestureToProgress = (
+	translation: number,
+	dimension: number,
+) => {
+	"worklet";
+	const rawProgress = translation / dimension;
+	return Math.max(0, Math.min(1, rawProgress));
 };

package/src/shared/providers/gestures/helpers/gesture-reset.ts

@@ -0,0 +1,108 @@
+import type {
+	GestureStateChangeEvent,
+	PanGestureHandlerEventPayload,
+} from "react-native-gesture-handler";
+import {
+	DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+	FALSE,
+	TRUE,
+} from "../../../constants";
+import type { GestureStoreMap } from "../../../stores/gesture.store";
+import type { AnimationConfig } from "../../../types/animation.types";
+import { animateMany } from "../../../utils/animation/animate-many";
+import {
+	calculateRestoreVelocityTowardZero,
+	normalizeVelocity,
+} from "./gesture-physics";
+
+interface ResetGestureValuesProps {
+	spec?: AnimationConfig;
+	gestures: GestureStoreMap;
+	shouldDismiss: boolean;
+	event: GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+	dimensions: { width: number; height: number };
+	gestureReleaseVelocityScale?: number;
+	gestureReleaseVelocityMax?: number;
+}
+
+export const resetGestureValues = ({
+	spec,
+	gestures,
+	shouldDismiss,
+	event,
+	dimensions,
+	gestureReleaseVelocityScale = DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+	gestureReleaseVelocityMax = DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+}: ResetGestureValuesProps) => {
+	"worklet";
+
+	const effectiveReleaseVelocityMax = Math.max(
+		0,
+		Math.abs(gestureReleaseVelocityMax),
+	);
+
+	const vxNorm = normalizeVelocity(
+		event.velocityX,
+		dimensions.width,
+		effectiveReleaseVelocityMax,
+	);
+	const vyNorm = normalizeVelocity(
+		event.velocityY,
+		dimensions.height,
+		effectiveReleaseVelocityMax,
+	);
+
+	// Ensure spring starts moving toward zero using normalized gesture values for direction.
+	const nx =
+		gestures.normX.value || event.translationX / Math.max(1, dimensions.width);
+
+	const ny =
+		gestures.normY.value || event.translationY / Math.max(1, dimensions.height);
+
+	const vxTowardZero = calculateRestoreVelocityTowardZero(nx, vxNorm);
+	const vyTowardZero = calculateRestoreVelocityTowardZero(ny, vyNorm);
+
+	// When dismissing, use raw fling velocity (scaled by gestureReleaseVelocityScale)
+	// so the spring carries the gesture's momentum. The spec controls the
+	// spring character — use an underdamped spec (e.g. FlingSpec) for orbit/fling.
+	const resetVX = shouldDismiss
+		? vxNorm * gestureReleaseVelocityScale
+		: vxTowardZero;
+
+	const resetVY = shouldDismiss
+		? vyNorm * gestureReleaseVelocityScale
+		: vyTowardZero;
+
+	animateMany({
+		items: [
+			{
+				value: gestures.x,
+				toValue: 0,
+				config: { ...spec, velocity: resetVX },
+			},
+			{
+				value: gestures.y,
+				toValue: 0,
+				config: { ...spec, velocity: resetVY },
+			},
+			{
+				value: gestures.normX,
+				toValue: 0,
+				config: { ...spec, velocity: resetVX },
+			},
+			{
+				value: gestures.normY,
+				toValue: 0,
+				config: { ...spec, velocity: resetVY },
+			},
+		],
+		onAllFinished: () => {
+			"worklet";
+			gestures.direction.value = null;
+		},
+	});
+
+	gestures.dragging.value = FALSE;
+	gestures.dismissing.value = shouldDismiss ? TRUE : FALSE;
+};

package/src/shared/providers/gestures/helpers/gesture-targets.ts

@@ -0,0 +1,167 @@
+import { DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT } from "../../../constants";
+import type { GestureDirections } from "../../../types/gesture.types";
+import { sanitizeSnapPoints } from "../../../utils/gesture/validate-snap-points";
+import { shouldDismissFromTranslationAndVelocity } from "./gesture-physics";
+
+interface GetAxisThresholdProps {
+	translation: number;
+	velocity: number;
+	screenSize: number;
+	gestureVelocityImpact: number;
+}
+
+interface DetermineDismissalProps {
+	event: {
+		translationX: number;
+		translationY: number;
+		velocityX: number;
+		velocityY: number;
+	};
+	directions: GestureDirections;
+	dimensions: { width: number; height: number };
+	gestureVelocityImpact: number;
+}
+
+interface DetermineSnapTargetProps {
+	currentProgress: number;
+	snapPoints: number[];
+	/** Velocity along the snap axis (positive = toward dismiss) */
+	velocity: number;
+	/** Screen dimension along the snap axis (width or height) */
+	dimension: number;
+	/**
+	 * How much velocity affects the snap decision.
+	 * Lower values = more deliberate/iOS-like, higher values = more responsive to flicks.
+	 * @default 0.1
+	 */
+	velocityFactor?: number;
+	/** Whether dismiss (progress=0) is allowed. Default true */
+	canDismiss?: boolean;
+}
+
+interface DetermineSnapTargetResult {
+	targetProgress: number;
+	shouldDismiss: boolean;
+}
+
+const getAxisThreshold = ({
+	translation,
+	velocity,
+	screenSize,
+	gestureVelocityImpact,
+}: GetAxisThresholdProps) => {
+	"worklet";
+	return shouldDismissFromTranslationAndVelocity(
+		translation,
+		velocity,
+		screenSize,
+		gestureVelocityImpact,
+	);
+};
+
+export const determineDismissal = ({
+	event,
+	directions,
+	dimensions,
+	gestureVelocityImpact,
+}: DetermineDismissalProps) => {
+	"worklet";
+
+	let shouldDismiss: boolean = false;
+
+	if (
+		(directions.vertical && event.translationY > 0) ||
+		(directions.verticalInverted && event.translationY < 0)
+	) {
+		const dismiss = getAxisThreshold({
+			translation: event.translationY,
+			velocity: event.velocityY,
+			screenSize: dimensions.height,
+			gestureVelocityImpact,
+		});
+		if (dismiss) shouldDismiss = true;
+	}
+
+	if (
+		(directions.horizontal && event.translationX > 0) ||
+		(directions.horizontalInverted && event.translationX < 0)
+	) {
+		const dismiss = getAxisThreshold({
+			translation: event.translationX,
+			velocity: event.velocityX,
+			screenSize: dimensions.width,
+			gestureVelocityImpact,
+		});
+
+		if (dismiss) shouldDismiss = true;
+	}
+
+	return { shouldDismiss };
+};
+
+/**
+ * Determines which snap point to animate to based on current progress and velocity.
+ *
+ * Logic: Snap to whichever point is closest, factoring in velocity.
+ * The "zones" between snap points are split at midpoints.
+ * Velocity can push you into the next zone.
+ */
+export function determineSnapTarget({
+	currentProgress,
+	snapPoints,
+	velocity,
+	dimension,
+	velocityFactor = DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	canDismiss = true,
+}: DetermineSnapTargetProps): DetermineSnapTargetResult {
+	"worklet";
+
+	// Convert velocity to progress units (positive = toward dismiss = decreasing progress)
+	const velocityInProgress = (velocity / dimension) * velocityFactor;
+
+	// Project where we'd end up with velocity
+	const projectedProgress = currentProgress - velocityInProgress;
+
+	const sanitizedSnapPoints = sanitizeSnapPoints(snapPoints, canDismiss);
+
+	// Build all possible targets: dismiss (0) only if allowed, plus all snap points
+	const allTargets = Array.from(
+		new Set(canDismiss ? [0, ...sanitizedSnapPoints] : sanitizedSnapPoints),
+	).sort((a, b) => a - b);
+
+	if (allTargets.length === 0) {
+		return {
+			targetProgress: currentProgress,
+			shouldDismiss: false,
+		};
+	}
+
+	// Find the target whose zone contains the projected progress
+	// Zones are split at midpoints between adjacent targets
+	let targetProgress = allTargets[0];
+
+	for (let i = 0; i < allTargets.length; i++) {
+		const current = allTargets[i];
+		const next = allTargets[i + 1];
+
+		if (next === undefined) {
+			// Last target - if we're above the midpoint to here, snap to it
+			targetProgress = current;
+			break;
+		}
+
+		const midpoint = (current + next) / 2;
+
+		if (projectedProgress < midpoint) {
+			targetProgress = current;
+			break;
+		}
+
+		targetProgress = next;
+	}
+
+	return {
+		targetProgress,
+		shouldDismiss: canDismiss && targetProgress === 0,
+	};
+}

package/src/shared/providers/gestures/helpers/register-direction-claims.ts

@@ -0,0 +1,84 @@
+import { useEffect } from "react";
+import { GestureStore } from "../../../stores/gesture.store";
+import {
+	type ClaimedDirections,
+	DIRECTIONS,
+	type Direction,
+} from "../../../types/ownership.types";
+import type { GestureContextType } from "../types";
+
+/**
+ * Registers direction claims on ancestors that this screen shadows.
+ * Only registers claims when this screen is the current (topmost) route
+ * in its navigator, preventing unfocused screens from blocking gestures.
+ */
+export function useRegisterDirectionClaims(
+	ancestorContext: GestureContextType | null | undefined,
+	claimedDirections: ClaimedDirections,
+	routeKey: string,
+	isIsolated: boolean,
+	isCurrentRoute: boolean,
+) {
+	useEffect(() => {
+		// Only register claims when this screen is the current route
+		if (!isCurrentRoute || !ancestorContext) {
+			return;
+		}
+
+		const gestureValues = GestureStore.getRouteGestures(routeKey);
+		const isDismissing = gestureValues.dismissing;
+
+		const claimedAncestors: Array<{
+			ancestor: GestureContextType;
+			directions: Direction[];
+		}> = [];
+
+		let ancestor: GestureContextType | null = ancestorContext;
+		while (ancestor) {
+			if (ancestor.isIsolated !== isIsolated) break;
+
+			const shadowedDirections: Direction[] = [];
+			for (const dir of DIRECTIONS) {
+				if (claimedDirections[dir] && ancestor.claimedDirections?.[dir]) {
+					shadowedDirections.push(dir);
+				}
+			}
+
+			if (shadowedDirections.length > 0) {
+				claimedAncestors.push({ ancestor, directions: shadowedDirections });
+				const newClaims = { ...ancestor.childDirectionClaims.value };
+				for (const dir of shadowedDirections) {
+					newClaims[dir] = { routeKey, isDismissing };
+				}
+				ancestor.childDirectionClaims.value = newClaims;
+			}
+
+			ancestor = ancestor.ancestorContext;
+		}
+
+		return () => {
+			for (const { ancestor, directions } of claimedAncestors) {
+				const currentClaims = ancestor.childDirectionClaims.value;
+				const newClaims = { ...currentClaims };
+				let needsUpdate = false;
+
+				for (const dir of directions) {
+					if (currentClaims[dir]?.routeKey === routeKey) {
+						newClaims[dir] = null;
+						needsUpdate = true;
+					}
+				}
+
+				if (needsUpdate) {
+					ancestor.childDirectionClaims.value = newClaims;
+				}
+			}
+		};
+	}, [
+		ancestorContext,
+		claimedDirections,
+		routeKey,
+		isIsolated,
+		isCurrentRoute,
+	]);
+}

package/src/shared/providers/gestures/index.tsx

@@ -0,0 +1,10 @@
+export {
+	ScreenGestureProvider,
+	useGestureContext,
+} from "./gestures.provider";
+export type {
+	DirectionClaim,
+	DirectionClaimMap,
+	GestureContextType,
+	ScrollConfig,
+} from "./types";