react-native-screen-transitions 3.5.1 → 3.6.0-alpha.0

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

@@ -1,22 +1,17 @@
-import type {
-	GestureStateChangeEvent,
-	PanGestureHandlerEventPayload,
-} from "react-native-gesture-handler";
 import { clamp } from "react-native-reanimated";
-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";
+import { EPSILON } from "../../../../constants";
+import type { AnimationStoreMap } from "../../../../stores/animation.store";
+import type { GestureDirections } from "../../../../types/gesture.types";
+import type { PanGestureEvent } from "../types";
 
 interface CalculateProgressProps {
 	animations: AnimationStoreMap;
 	shouldDismiss: boolean;
-	event: GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+	event: PanGestureEvent;
 	dimensions: { width: number; height: number };
 	directions: GestureDirections;
+	gestureReleaseVelocityScale?: number;
+	gestureReleaseVelocityMax?: number;
 }
 
 type GestureAxisCandidate = {
@@ -25,19 +20,56 @@ type GestureAxisCandidate = {
 };
 
 /**
- * Converts velocity from pixels/second to normalized units/second (0-1 range)
- * and caps the result for stability
+ * Converts a pan velocity from pixels/second into progress/second.
  */
-export const normalizeVelocity = (
+export const toProgressVelocity = (
 	velocityPixelsPerSecond: number,
 	screenSize: number,
+) => {
+	"worklet";
+	return velocityPixelsPerSecond / Math.max(1, screenSize);
+};
+
+export const clampReleaseVelocity = (
+	velocity: number,
 	maxMagnitude?: number,
 ) => {
 	"worklet";
-	const resolvedMaxMagnitude =
-		maxMagnitude ?? DEFAULT_GESTURE_RELEASE_VELOCITY_MAX;
-	const max = Math.max(0, Math.abs(resolvedMaxMagnitude));
-	return clamp(velocityPixelsPerSecond / Math.max(1, screenSize), -max, max);
+	if (maxMagnitude === undefined) return velocity;
+
+	const max = Math.max(0, Math.abs(maxMagnitude));
+	return clamp(velocity, -max, max);
+};
+
+/**
+ * Converts pan release velocity into a spring handoff in progress units/second.
+ */
+export const getPanReleaseHandoffVelocity = (
+	velocityPixelsPerSecond: number,
+	screenSize: number,
+	gestureReleaseVelocityScale: number = 1,
+	gestureReleaseVelocityMax?: number,
+) => {
+	"worklet";
+	const velocity =
+		toProgressVelocity(velocityPixelsPerSecond, screenSize) *
+		Math.max(0, gestureReleaseVelocityScale);
+
+	return clampReleaseVelocity(velocity, gestureReleaseVelocityMax);
+};
+
+/**
+ * Converts pinch scale velocity into a spring handoff in progress units/second.
+ */
+export const getPinchReleaseHandoffVelocity = (
+	velocityScalePerSecond: number,
+	gestureReleaseVelocityScale: number = 1,
+	gestureReleaseVelocityMax?: number,
+) => {
+	"worklet";
+	const velocity =
+		velocityScalePerSecond * Math.max(0, gestureReleaseVelocityScale);
+	return clampReleaseVelocity(velocity, gestureReleaseVelocityMax);
 };
 
 /**
@@ -53,33 +85,21 @@ export const normalizeGestureTranslation = (
 };
 
 /**
- * Calculates a normalized velocity that moves the current value toward zero.
- * Used for spring-back animations when dismissing gestures.
+ * Picks the dominant active pan axis and returns a release handoff velocity
+ * in progress units/second oriented toward the animation target.
  */
-export const calculateRestoreVelocityTowardZero = (
-	currentValueNormalized: number,
-	baseVelocityNormalized: number,
-) => {
-	"worklet";
-
-	if (Math.abs(currentValueNormalized) < ANIMATION_SNAP_THRESHOLD) return 0;
-
-	const directionTowardZero = Math.sign(currentValueNormalized) || 1;
-	const clampedVelocity = Math.min(Math.abs(baseVelocityNormalized), 1);
-
-	return -directionTowardZero * clampedVelocity;
-};
-
-export const calculateProgressSpringVelocity = ({
+export const getPanReleaseProgressVelocity = ({
 	animations,
 	shouldDismiss,
 	event,
 	dimensions,
 	directions,
+	gestureReleaseVelocityScale,
+	gestureReleaseVelocityMax,
 }: CalculateProgressProps) => {
 	"worklet";
 
-	const currentProgress = animations.progress.value;
+	const currentProgress = animations.progress.get();
 	const targetProgress = shouldDismiss ? 0 : 1;
 	const progressDelta = targetProgress - currentProgress;
 
@@ -90,9 +110,11 @@ export const calculateProgressSpringVelocity = ({
 	if (directions.horizontal && event.translationX > 0) {
 		candidates.push({
 			progressContribution: event.translationX / Math.max(1, dimensions.width),
-			velocityContribution: normalizeVelocity(
+			velocityContribution: getPanReleaseHandoffVelocity(
 				event.velocityX,
 				dimensions.width,
+				gestureReleaseVelocityScale,
+				gestureReleaseVelocityMax,
 			),
 		});
 	}
@@ -100,9 +122,11 @@ export const calculateProgressSpringVelocity = ({
 	if (directions.horizontalInverted && event.translationX < 0) {
 		candidates.push({
 			progressContribution: -event.translationX / Math.max(1, dimensions.width),
-			velocityContribution: normalizeVelocity(
+			velocityContribution: getPanReleaseHandoffVelocity(
 				-event.velocityX,
 				dimensions.width,
+				gestureReleaseVelocityScale,
+				gestureReleaseVelocityMax,
 			),
 		});
 	}
@@ -110,9 +134,11 @@ export const calculateProgressSpringVelocity = ({
 	if (directions.vertical && event.translationY > 0) {
 		candidates.push({
 			progressContribution: event.translationY / Math.max(1, dimensions.height),
-			velocityContribution: normalizeVelocity(
+			velocityContribution: getPanReleaseHandoffVelocity(
 				event.velocityY,
 				dimensions.height,
+				gestureReleaseVelocityScale,
+				gestureReleaseVelocityMax,
 			),
 		});
 	}
@@ -121,9 +147,11 @@ export const calculateProgressSpringVelocity = ({
 		candidates.push({
 			progressContribution:
 				-event.translationY / Math.max(1, dimensions.height),
-			velocityContribution: normalizeVelocity(
+			velocityContribution: getPanReleaseHandoffVelocity(
 				-event.velocityY,
 				dimensions.height,
+				gestureReleaseVelocityScale,
+				gestureReleaseVelocityMax,
 			),
 		});
 	}
@@ -140,13 +168,17 @@ export const calculateProgressSpringVelocity = ({
 		}
 		progressVelocityMagnitude = Math.abs(dominant.velocityContribution);
 	} else {
-		const normalizedVelocityX = normalizeVelocity(
+		const normalizedVelocityX = getPanReleaseHandoffVelocity(
 			event.velocityX,
 			dimensions.width,
+			gestureReleaseVelocityScale,
+			gestureReleaseVelocityMax,
 		);
-		const normalizedVelocityY = normalizeVelocity(
+		const normalizedVelocityY = getPanReleaseHandoffVelocity(
 			event.velocityY,
 			dimensions.height,
+			gestureReleaseVelocityScale,
+			gestureReleaseVelocityMax,
 		);
 		progressVelocityMagnitude = Math.max(
 			Math.abs(normalizedVelocityX),
@@ -154,20 +186,16 @@ export const calculateProgressSpringVelocity = ({
 		);
 	}
 
-	// Apply direction and clamp to prevent overly energetic springs
-	return (
-		progressDirection *
-		clamp(progressVelocityMagnitude, 0, DEFAULT_GESTURE_RELEASE_VELOCITY_MAX)
-	);
+	return progressDirection * progressVelocityMagnitude;
 };
 
 /**
  * Determines if a gesture should trigger dismissal based on combined
  * translation and velocity in normalized screen units (0-1 range).
  *
- * Formula: |translation/screen + clamp(velocity/screen, ±1) * velocityWeight| > 0.5
+ * Formula: |translation/screen + velocity/screen * velocityWeight| > 0.5
  */
-export const shouldDismissFromTranslationAndVelocity = (
+export const shouldDismissFromProjection = (
 	translationPixels: number,
 	velocityPixelsPerSecond: number,
 	screenSize: number,
@@ -183,7 +211,7 @@ export const shouldDismissFromTranslationAndVelocity = (
 		return false;
 	}
 
-	const normalizedVelocity = normalizeVelocity(
+	const normalizedVelocity = toProgressVelocity(
 		velocityPixelsPerSecond,
 		screenSize,
 	);
@@ -212,3 +240,49 @@ export const mapGestureToProgress = (
 	const rawProgress = translation / dimension;
 	return Math.max(0, Math.min(1, rawProgress));
 };
+
+/**
+ * Scales live gesture movement before it is applied to transition progress.
+ * Lower values reduce sensitivity, higher values increase it.
+ */
+export const applyGestureSensitivity = (
+	progressDelta: number,
+	gestureSensitivity: number = 1,
+) => {
+	"worklet";
+	return progressDelta * Math.max(0, gestureSensitivity);
+};
+
+/**
+ * Normalizes pinch scale so idle is 0, pinch-in is negative, and pinch-out is positive.
+ * This intentionally returns the raw delta so sensitivity can be applied before
+ * the live gesture is clamped into progress space.
+ *
+ * Examples:
+ * - 0.5 scale => -0.5
+ * - 1.0 scale => 0
+ * - 1.5 scale => 0.5
+ * - 2.0 scale => 1
+ * - 3.0 scale => 2
+ */
+export const normalizePinchScale = (scale: number) => {
+	"worklet";
+	return scale - 1;
+};
+
+export const shouldDismissFromPinch = (
+	normalizedScale: number,
+	pinchInEnabled: boolean,
+	pinchOutEnabled: boolean,
+) => {
+	"worklet";
+	if (normalizedScale < 0 && !pinchInEnabled) {
+		return false;
+	}
+
+	if (normalizedScale > 0 && !pinchOutEnabled) {
+		return false;
+	}
+
+	return Math.abs(normalizedScale) > 0.5;
+};

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

@@ -0,0 +1,158 @@
+import type { SharedValue } from "react-native-reanimated";
+import { EPSILON, FALSE, TRUE } from "../../../../constants";
+import type { GestureStoreMap } from "../../../../stores/gesture.store";
+import type { AnimationConfig } from "../../../../types/animation.types";
+import { animate } from "../../../../utils/animation/animate";
+
+interface ResetGestureValuesProps {
+	spec?: AnimationConfig;
+	gestures: GestureStoreMap;
+	shouldDismiss: boolean;
+	velocityX?: number;
+	velocityY?: number;
+	velocityNormX?: number;
+	velocityNormY?: number;
+}
+
+const getGestureResetSpec = (
+	spec?: AnimationConfig,
+	velocity?: number,
+): AnimationConfig | undefined => {
+	"worklet";
+
+	const isSpring =
+		typeof spec === "object" && !("duration" in spec) && !("easing" in spec);
+
+	if (!isSpring) {
+		return spec;
+	}
+
+	const { velocity: _velocity, ...resetSpec } = spec as AnimationConfig & {
+		velocity?: number;
+	};
+	return (
+		typeof velocity === "number" ? { ...resetSpec, velocity } : resetSpec
+	) as AnimationConfig;
+};
+
+const animateResetValue = (
+	value: SharedValue<number>,
+	toValue: number,
+	config: AnimationConfig | undefined,
+	onFinished: () => void,
+) => {
+	"worklet";
+	value.set(
+		animate(toValue, config, (finished) => {
+			"worklet";
+			if (finished) {
+				onFinished();
+			}
+		}),
+	);
+};
+
+const clearPanSettlingIfResting = (gestures: GestureStoreMap) => {
+	"worklet";
+
+	if (
+		gestures.dragging.get() ||
+		gestures.dismissing.get() ||
+		Math.abs(gestures.x.get()) > EPSILON ||
+		Math.abs(gestures.y.get()) > EPSILON ||
+		Math.abs(gestures.normX.get()) > EPSILON ||
+		Math.abs(gestures.normY.get()) > EPSILON
+	) {
+		return;
+	}
+
+	gestures.active.set(null);
+	gestures.direction.set(null);
+	gestures.settling.set(FALSE);
+};
+
+const clearPinchSettlingIfResting = (gestures: GestureStoreMap) => {
+	"worklet";
+
+	if (
+		gestures.dragging.get() ||
+		gestures.dismissing.get() ||
+		Math.abs(gestures.scale.get() - 1) > EPSILON ||
+		Math.abs(gestures.normScale.get()) > EPSILON
+	) {
+		return;
+	}
+
+	gestures.focalX.set(0);
+	gestures.focalY.set(0);
+	gestures.active.set(null);
+	gestures.direction.set(null);
+	gestures.settling.set(FALSE);
+};
+
+export const resetGestureValues = ({
+	spec,
+	gestures,
+	shouldDismiss,
+	velocityX,
+	velocityY,
+	velocityNormX,
+	velocityNormY,
+}: ResetGestureValuesProps) => {
+	"worklet";
+
+	gestures.raw.x.set(0);
+	gestures.raw.y.set(0);
+	gestures.raw.normX.set(0);
+	gestures.raw.normY.set(0);
+	gestures.dragging.set(FALSE);
+	gestures.dismissing.set(shouldDismiss ? TRUE : FALSE);
+	gestures.settling.set(shouldDismiss ? FALSE : TRUE);
+
+	animateResetValue(gestures.x, 0, getGestureResetSpec(spec, velocityX), () =>
+		clearPanSettlingIfResting(gestures),
+	);
+	animateResetValue(gestures.y, 0, getGestureResetSpec(spec, velocityY), () =>
+		clearPanSettlingIfResting(gestures),
+	);
+	animateResetValue(
+		gestures.normX,
+		0,
+		getGestureResetSpec(spec, velocityNormX),
+		() => clearPanSettlingIfResting(gestures),
+	);
+	animateResetValue(
+		gestures.normY,
+		0,
+		getGestureResetSpec(spec, velocityNormY),
+		() => clearPanSettlingIfResting(gestures),
+	);
+};
+
+interface ResetPinchGestureValuesProps {
+	spec?: AnimationConfig;
+	gestures: GestureStoreMap;
+	shouldDismiss: boolean;
+}
+
+export const resetPinchGestureValues = ({
+	spec,
+	gestures,
+	shouldDismiss,
+}: ResetPinchGestureValuesProps) => {
+	"worklet";
+	const resetSpec = getGestureResetSpec(spec);
+
+	gestures.raw.scale.set(1);
+	gestures.raw.normScale.set(0);
+	gestures.dragging.set(FALSE);
+	gestures.dismissing.set(shouldDismiss ? TRUE : FALSE);
+	gestures.settling.set(shouldDismiss ? FALSE : TRUE);
+
+	animateResetValue(gestures.scale, 1, resetSpec, () =>
+		clearPinchSettlingIfResting(gestures),
+	);
+	animateResetValue(gestures.normScale, 0, resetSpec, () =>
+		clearPinchSettlingIfResting(gestures),
+	);
+};

package/src/shared/providers/{gestures → screen/gestures}/helpers/gesture-snap-points.ts

@@ -8,7 +8,6 @@ interface ResolveRuntimeSnapPointsProps {
 }
 
 interface ResolvedRuntimeSnapPointsResult {
-	resolvedAutoSnapPoint: number | null;
 	resolvedSnapPoints: number[];
 	resolvedMinSnapPoint: number;
 	resolvedMaxSnapPoint: number;
@@ -43,7 +42,6 @@ export const resolveRuntimeSnapPoints = ({
 			: minSnapPoint;
 
 	return {
-		resolvedAutoSnapPoint: nextResolvedAutoSnapPoint,
 		resolvedSnapPoints,
 		resolvedMinSnapPoint,
 		resolvedMaxSnapPoint:

package/src/shared/providers/{gestures → screen/gestures}/helpers/gesture-targets.ts

@@ -1,14 +1,7 @@
-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;
-}
+import { DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT } from "../../../../constants";
+import type { GestureDirections } from "../../../../types/gesture.types";
+import { shouldDismissFromProjection } from "./gesture-physics";
+import { sanitizeSnapPoints } from "./validate-snap-points";
 
 interface DetermineDismissalProps {
 	event: {
@@ -44,21 +37,6 @@ interface DetermineSnapTargetResult {
 	shouldDismiss: boolean;
 }
 
-const getAxisThreshold = ({
-	translation,
-	velocity,
-	screenSize,
-	gestureVelocityImpact,
-}: GetAxisThresholdProps) => {
-	"worklet";
-	return shouldDismissFromTranslationAndVelocity(
-		translation,
-		velocity,
-		screenSize,
-		gestureVelocityImpact,
-	);
-};
-
 export const determineDismissal = ({
 	event,
 	directions,
@@ -73,12 +51,12 @@ export const determineDismissal = ({
 		(directions.vertical && event.translationY > 0) ||
 		(directions.verticalInverted && event.translationY < 0)
 	) {
-		const dismiss = getAxisThreshold({
-			translation: event.translationY,
-			velocity: event.velocityY,
-			screenSize: dimensions.height,
+		const dismiss = shouldDismissFromProjection(
+			event.translationY,
+			event.velocityY,
+			dimensions.height,
 			gestureVelocityImpact,
-		});
+		);
 		if (dismiss) shouldDismiss = true;
 	}
 
@@ -86,12 +64,12 @@ export const determineDismissal = ({
 		(directions.horizontal && event.translationX > 0) ||
 		(directions.horizontalInverted && event.translationX < 0)
 	) {
-		const dismiss = getAxisThreshold({
-			translation: event.translationX,
-			velocity: event.velocityX,
-			screenSize: dimensions.width,
+		const dismiss = shouldDismissFromProjection(
+			event.translationX,
+			event.velocityX,
+			dimensions.width,
 			gestureVelocityImpact,
-		});
+		);
 
 		if (dismiss) shouldDismiss = true;
 	}

package/src/shared/providers/screen/gestures/helpers/pan-phases.ts

@@ -0,0 +1,124 @@
+import { clamp } from "react-native-reanimated";
+import { EPSILON, FALSE, TRUE } from "../../../../constants";
+import { animateToProgress } from "../../../../utils/animation/animate-to-progress";
+import { emit } from "../../../../utils/animation/emit";
+import type {
+	GestureDimensions,
+	PanGestureEvent,
+	PanGestureRuntime,
+	PanReleaseResult,
+	PanTrackState,
+} from "../types";
+import { normalizeGestureTranslation } from "./gesture-physics";
+import { resetGestureValues } from "./gesture-reset";
+
+export const startPanBase = (runtime: PanGestureRuntime) => {
+	"worklet";
+	const {
+		stores: { gestures, animations },
+		gestureProgressBaseline,
+	} = runtime;
+
+	const wasSettling = gestures.settling.get();
+	const hasResidualGesture =
+		Math.abs(gestures.normX.get()) > EPSILON ||
+		Math.abs(gestures.normY.get()) > EPSILON;
+
+	if (!wasSettling || !hasResidualGesture) {
+		emit(animations.willAnimate, TRUE, FALSE);
+	}
+
+	gestures.dragging.set(TRUE);
+	gestures.dismissing.set(0);
+	gestures.settling.set(0);
+	gestures.x.set(0);
+	gestures.y.set(0);
+	gestures.normX.set(0);
+	gestures.normY.set(0);
+	gestures.raw.x.set(0);
+	gestures.raw.y.set(0);
+	gestures.raw.normX.set(0);
+	gestures.raw.normY.set(0);
+	gestureProgressBaseline.set(animations.progress.get());
+};
+
+export const trackPanGesture = (
+	event: PanGestureEvent,
+	rawEvent: PanGestureEvent,
+	gestures: PanGestureRuntime["stores"]["gestures"],
+	dimensions: GestureDimensions,
+): PanTrackState => {
+	"worklet";
+	const { translationX: x, translationY: y } = event;
+	const { translationX: rawX, translationY: rawY } = rawEvent;
+	const { width, height } = dimensions;
+
+	const normX = clamp(normalizeGestureTranslation(x, width), -1, 1);
+	const normY = clamp(normalizeGestureTranslation(y, height), -1, 1);
+	const rawNormX = clamp(normalizeGestureTranslation(rawX, width), -1, 1);
+	const rawNormY = clamp(normalizeGestureTranslation(rawY, height), -1, 1);
+
+	gestures.x.set(x);
+	gestures.y.set(y);
+	gestures.normX.set(normX);
+	gestures.normY.set(normY);
+	gestures.raw.x.set(rawX);
+	gestures.raw.y.set(rawY);
+	gestures.raw.normX.set(rawNormX);
+	gestures.raw.normY.set(rawNormY);
+
+	return {
+		x,
+		y,
+		normX,
+		normY,
+	};
+};
+
+export const finalizePanRelease = (
+	release: PanReleaseResult,
+	runtime: PanGestureRuntime,
+	dismissScreen: (() => void) | undefined,
+	dimensions: GestureDimensions,
+	rawEvent: PanGestureEvent,
+) => {
+	"worklet";
+	const {
+		policy,
+		stores: { gestures, animations, system },
+	} = runtime;
+	const { width, height } = dimensions;
+	const releaseVelocityScale = Math.max(0, policy.gestureReleaseVelocityScale);
+	const resetVelocityX = rawEvent.velocityX * releaseVelocityScale;
+	const resetVelocityY = rawEvent.velocityY * releaseVelocityScale;
+
+	resetGestureValues({
+		spec: release.resetSpec,
+		gestures,
+		shouldDismiss: release.shouldDismiss,
+		velocityX: resetVelocityX,
+		velocityY: resetVelocityY,
+		velocityNormX: resetVelocityX / Math.max(1, width),
+		velocityNormY: resetVelocityY / Math.max(1, height),
+	});
+
+	const progressAlreadyAtTarget =
+		Math.abs(animations.progress.get() - release.target) <= EPSILON;
+
+	if (!release.shouldDismiss && progressAlreadyAtTarget) {
+		system.targetProgress.set(release.target);
+		animations.animating.set(FALSE);
+		return;
+	}
+
+	animateToProgress({
+		target: release.target,
+		onAnimationFinish: release.shouldDismiss ? dismissScreen : undefined,
+		spec: release.transitionSpec,
+		emitWillAnimate: false,
+		markEntering: false,
+		targetProgress: system.targetProgress,
+		animations,
+		initialVelocity: release.initialVelocity,
+	});
+};