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

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/{utils/gesture/determine-snap-target.ts → providers/gestures/helpers/gesture-targets.ts}

@@ -1,3 +1,27 @@
+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[];
@@ -20,6 +44,61 @@ interface DetermineSnapTargetResult {
 	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.
  *
@@ -32,7 +111,7 @@ export function determineSnapTarget({
 	snapPoints,
 	velocity,
 	dimension,
-	velocityFactor = 0.1,
+	velocityFactor = DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
 	canDismiss = true,
 }: DetermineSnapTargetProps): DetermineSnapTargetResult {
 	"worklet";
@@ -43,9 +122,7 @@ export function determineSnapTarget({
 	// Project where we'd end up with velocity
 	const projectedProgress = currentProgress - velocityInProgress;
 
-	const sanitizedSnapPoints = snapPoints.filter((point) =>
-		canDismiss ? Number.isFinite(point) : Number.isFinite(point) && point > 0,
-	);
+	const sanitizedSnapPoints = sanitizeSnapPoints(snapPoints, canDismiss);
 
 	// Build all possible targets: dismiss (0) only if allowed, plus all snap points
 	const allTargets = Array.from(

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";

package/src/shared/providers/gestures/types.ts

@@ -0,0 +1,45 @@
+import type { GestureType } from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import type { GestureStoreMap } from "../../stores/gesture.store";
+import type { ClaimedDirections } from "../../types/ownership.types";
+
+export type ScrollConfig = {
+	x: number;
+	y: number;
+	contentHeight: number;
+	contentWidth: number;
+	layoutHeight: number;
+	layoutWidth: number;
+	isTouched: boolean;
+};
+
+export type DirectionClaim = {
+	routeKey: string;
+	isDismissing: SharedValue<number>;
+} | null;
+
+export type DirectionClaimMap = {
+	vertical: DirectionClaim;
+	"vertical-inverted": DirectionClaim;
+	horizontal: DirectionClaim;
+	"horizontal-inverted": DirectionClaim;
+};
+
+export const NO_CLAIMS: DirectionClaimMap = {
+	vertical: null,
+	"vertical-inverted": null,
+	horizontal: null,
+	"horizontal-inverted": null,
+};
+
+export interface GestureContextType {
+	panGesture: GestureType;
+	panGestureRef: React.MutableRefObject<GestureType | undefined>;
+	scrollConfig: SharedValue<ScrollConfig | null>;
+	gestureAnimationValues: GestureStoreMap;
+	ancestorContext: GestureContextType | null;
+	gestureEnabled: boolean;
+	isIsolated: boolean;
+	claimedDirections: ClaimedDirections;
+	childDirectionClaims: SharedValue<DirectionClaimMap>;
+}