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

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

@@ -11,7 +11,6 @@ interface CalculateProgressProps {
 	dimensions: { width: number; height: number };
 	directions: GestureDirections;
 	gestureReleaseVelocityScale?: number;
-	gestureReleaseVelocityMax?: number;
 }
 
 type GestureAxisCandidate = {
@@ -19,6 +18,8 @@ type GestureAxisCandidate = {
 	velocityContribution: number;
 };
 
+const FULL_GESTURE_VELOCITY_PROGRESS_PER_SECOND = 4;
+
 /**
  * Converts a pan velocity from pixels/second into progress/second.
  */
@@ -30,15 +31,27 @@ export const toProgressVelocity = (
 	return velocityPixelsPerSecond / Math.max(1, screenSize);
 };
 
-export const clampReleaseVelocity = (
-	velocity: number,
-	maxMagnitude?: number,
+/**
+ * Converts normalized pan velocity into a 0-1 scalar for interpolators.
+ *
+ * `1` means the velocity reached or exceeded the library's full-velocity
+ * threshold, not a physical maximum for the device.
+ */
+export const resolveGestureVelocity = (
+	velocityNormX: number,
+	velocityNormY: number,
 ) => {
 	"worklet";
-	if (maxMagnitude === undefined) return velocity;
 
-	const max = Math.max(0, Math.abs(maxMagnitude));
-	return clamp(velocity, -max, max);
+	const dominantVelocity = Math.max(
+		Math.abs(velocityNormX),
+		Math.abs(velocityNormY),
+	);
+
+	return Math.min(
+		1,
+		dominantVelocity / FULL_GESTURE_VELOCITY_PROGRESS_PER_SECOND,
+	);
 };
 
 /**
@@ -48,14 +61,12 @@ export const getPanReleaseHandoffVelocity = (
 	velocityPixelsPerSecond: number,
 	screenSize: number,
 	gestureReleaseVelocityScale: number = 1,
-	gestureReleaseVelocityMax?: number,
 ) => {
 	"worklet";
-	const velocity =
+	return (
 		toProgressVelocity(velocityPixelsPerSecond, screenSize) *
-		Math.max(0, gestureReleaseVelocityScale);
-
-	return clampReleaseVelocity(velocity, gestureReleaseVelocityMax);
+		Math.max(0, gestureReleaseVelocityScale)
+	);
 };
 
 /**
@@ -64,12 +75,139 @@ export const getPanReleaseHandoffVelocity = (
 export const getPinchReleaseHandoffVelocity = (
 	velocityScalePerSecond: number,
 	gestureReleaseVelocityScale: number = 1,
-	gestureReleaseVelocityMax?: number,
 ) => {
 	"worklet";
-	const velocity =
-		velocityScalePerSecond * Math.max(0, gestureReleaseVelocityScale);
-	return clampReleaseVelocity(velocity, gestureReleaseVelocityMax);
+	return velocityScalePerSecond * Math.max(0, gestureReleaseVelocityScale);
+};
+
+const getPanAxisCandidate = (
+	isEnabled: boolean,
+	translationTowardDismiss: number,
+	velocityTowardDismiss: number,
+	screenSize: number,
+	gestureReleaseVelocityScale?: number,
+): GestureAxisCandidate | null => {
+	"worklet";
+	if (!isEnabled || translationTowardDismiss <= 0) {
+		return null;
+	}
+
+	return {
+		progressContribution: translationTowardDismiss / Math.max(1, screenSize),
+		velocityContribution: getPanReleaseHandoffVelocity(
+			velocityTowardDismiss,
+			screenSize,
+			gestureReleaseVelocityScale,
+		),
+	};
+};
+
+const pushPanAxisCandidate = (
+	candidates: GestureAxisCandidate[],
+	candidate: GestureAxisCandidate | null,
+) => {
+	"worklet";
+	if (candidate) {
+		candidates.push(candidate);
+	}
+};
+
+const collectPanAxisCandidates = ({
+	event,
+	dimensions,
+	directions,
+	gestureReleaseVelocityScale,
+}: Pick<
+	CalculateProgressProps,
+	"event" | "dimensions" | "directions" | "gestureReleaseVelocityScale"
+>) => {
+	"worklet";
+	const candidates: GestureAxisCandidate[] = [];
+
+	pushPanAxisCandidate(
+		candidates,
+		getPanAxisCandidate(
+			directions.horizontal,
+			event.translationX,
+			event.velocityX,
+			dimensions.width,
+			gestureReleaseVelocityScale,
+		),
+	);
+	pushPanAxisCandidate(
+		candidates,
+		getPanAxisCandidate(
+			directions.horizontalInverted,
+			-event.translationX,
+			-event.velocityX,
+			dimensions.width,
+			gestureReleaseVelocityScale,
+		),
+	);
+	pushPanAxisCandidate(
+		candidates,
+		getPanAxisCandidate(
+			directions.vertical,
+			event.translationY,
+			event.velocityY,
+			dimensions.height,
+			gestureReleaseVelocityScale,
+		),
+	);
+	pushPanAxisCandidate(
+		candidates,
+		getPanAxisCandidate(
+			directions.verticalInverted,
+			-event.translationY,
+			-event.velocityY,
+			dimensions.height,
+			gestureReleaseVelocityScale,
+		),
+	);
+
+	return candidates;
+};
+
+const getDominantPanCandidateVelocity = (
+	candidates: GestureAxisCandidate[],
+): number | null => {
+	"worklet";
+	if (candidates.length === 0) {
+		return null;
+	}
+
+	let dominant = candidates[0];
+	for (let i = 1; i < candidates.length; i++) {
+		const candidate = candidates[i];
+		if (candidate.progressContribution > dominant.progressContribution) {
+			dominant = candidate;
+		}
+	}
+
+	return Math.abs(dominant.velocityContribution);
+};
+
+const getFallbackPanReleaseVelocityMagnitude = ({
+	event,
+	dimensions,
+	gestureReleaseVelocityScale,
+}: Pick<
+	CalculateProgressProps,
+	"event" | "dimensions" | "gestureReleaseVelocityScale"
+>) => {
+	"worklet";
+	const normalizedVelocityX = getPanReleaseHandoffVelocity(
+		event.velocityX,
+		dimensions.width,
+		gestureReleaseVelocityScale,
+	);
+	const normalizedVelocityY = getPanReleaseHandoffVelocity(
+		event.velocityY,
+		dimensions.height,
+		gestureReleaseVelocityScale,
+	);
+
+	return Math.max(Math.abs(normalizedVelocityX), Math.abs(normalizedVelocityY));
 };
 
 /**
@@ -95,7 +233,6 @@ export const getPanReleaseProgressVelocity = ({
 	dimensions,
 	directions,
 	gestureReleaseVelocityScale,
-	gestureReleaseVelocityMax,
 }: CalculateProgressProps) => {
 	"worklet";
 
@@ -105,86 +242,21 @@ export const getPanReleaseProgressVelocity = ({
 
 	const progressDirection = progressDelta === 0 ? 0 : Math.sign(progressDelta);
 
-	const candidates: GestureAxisCandidate[] = [];
-
-	if (directions.horizontal && event.translationX > 0) {
-		candidates.push({
-			progressContribution: event.translationX / Math.max(1, dimensions.width),
-			velocityContribution: getPanReleaseHandoffVelocity(
-				event.velocityX,
-				dimensions.width,
-				gestureReleaseVelocityScale,
-				gestureReleaseVelocityMax,
-			),
-		});
-	}
-
-	if (directions.horizontalInverted && event.translationX < 0) {
-		candidates.push({
-			progressContribution: -event.translationX / Math.max(1, dimensions.width),
-			velocityContribution: getPanReleaseHandoffVelocity(
-				-event.velocityX,
-				dimensions.width,
-				gestureReleaseVelocityScale,
-				gestureReleaseVelocityMax,
-			),
-		});
-	}
-
-	if (directions.vertical && event.translationY > 0) {
-		candidates.push({
-			progressContribution: event.translationY / Math.max(1, dimensions.height),
-			velocityContribution: getPanReleaseHandoffVelocity(
-				event.velocityY,
-				dimensions.height,
-				gestureReleaseVelocityScale,
-				gestureReleaseVelocityMax,
-			),
-		});
-	}
-
-	if (directions.verticalInverted && event.translationY < 0) {
-		candidates.push({
-			progressContribution:
-				-event.translationY / Math.max(1, dimensions.height),
-			velocityContribution: getPanReleaseHandoffVelocity(
-				-event.velocityY,
-				dimensions.height,
-				gestureReleaseVelocityScale,
-				gestureReleaseVelocityMax,
-			),
-		});
-	}
-
-	let progressVelocityMagnitude = 0;
-
-	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 = getPanReleaseHandoffVelocity(
-			event.velocityX,
-			dimensions.width,
+	const dominantVelocity = getDominantPanCandidateVelocity(
+		collectPanAxisCandidates({
+			event,
+			dimensions,
+			directions,
 			gestureReleaseVelocityScale,
-			gestureReleaseVelocityMax,
-		);
-		const normalizedVelocityY = getPanReleaseHandoffVelocity(
-			event.velocityY,
-			dimensions.height,
+		}),
+	);
+	const progressVelocityMagnitude =
+		dominantVelocity ??
+		getFallbackPanReleaseVelocityMagnitude({
+			event,
+			dimensions,
 			gestureReleaseVelocityScale,
-			gestureReleaseVelocityMax,
-		);
-		progressVelocityMagnitude = Math.max(
-			Math.abs(normalizedVelocityX),
-			Math.abs(normalizedVelocityY),
-		);
-	}
+		});
 
 	return progressDirection * progressVelocityMagnitude;
 };
@@ -229,18 +301,6 @@ export const shouldDismissFromProjection = (
 	return exceedsThreshold;
 };
 
-/**
- * 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));
-};
-
 /**
  * Scales live gesture movement before it is applied to transition progress.
  * Lower values reduce sensitivity, higher values increase it.

package/src/shared/providers/screen/gestures/shared/policy.ts

@@ -0,0 +1,344 @@
+import {
+	DEFAULT_GESTURE_ACTIVATION_AREA,
+	DEFAULT_GESTURE_DIRECTION,
+	DEFAULT_GESTURE_PROGRESS_MODE,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+	DEFAULT_GESTURE_SENSITIVITY,
+	DEFAULT_GESTURE_SNAP_LOCKED,
+	DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	DEFAULT_GESTURE_VELOCITY_IMPACT,
+	DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR,
+} from "../../../../constants";
+import type {
+	GestureActivationArea,
+	GestureDirection,
+	GestureProgressMode,
+} from "../../../../types/gesture.types";
+import type {
+	ScreenTransitionConfig,
+	SheetScrollGestureBehavior,
+	SnapPoint,
+} from "../../../../types/screen.types";
+import { resolveGestureProgressMode } from "../../../../utils/gesture-progress-mode";
+import { computeClaimedDirections } from "../ownership/compute-claimed-directions";
+import { resolveOwnership } from "../ownership/resolve-ownership";
+import type {
+	GestureContextType,
+	PanGesturePolicy,
+	PinchGesturePolicy,
+	ScreenGestureConfig,
+	ScreenGestureParticipation,
+} from "../types";
+import {
+	getPanActivationDirections,
+	getPanGestureDirections,
+	getPanSnapAxisDirections,
+	getPinchGestureDirections,
+	getSnapPinchDirectionConfig,
+} from "./directions";
+import { validateSnapPoints } from "./snap-points";
+
+export type GesturePolicyOptions = {
+	experimental_allowDisabledGestureTracking?: boolean;
+	expandViaScrollView?: boolean;
+	gestureActivationArea?: GestureActivationArea;
+	gestureDirection?: GestureDirection | GestureDirection[];
+	gestureDrivesProgress?: boolean;
+	gestureEnabled?: boolean;
+	gestureProgressMode?: GestureProgressMode;
+	gestureReleaseVelocityScale?: number;
+	gestureResponseDistance?: number;
+	gestureSensitivity?: number;
+	gestureSnapLocked?: boolean;
+	gestureSnapVelocityImpact?: number;
+	gestureVelocityImpact?: number;
+	sheetScrollGestureBehavior?: SheetScrollGestureBehavior;
+	snapPoints?: SnapPoint[];
+	transitionSpec?: ScreenTransitionConfig["transitionSpec"];
+};
+
+const resolveGestureDirection = (options: GesturePolicyOptions) => {
+	"worklet";
+	return options.gestureDirection ?? DEFAULT_GESTURE_DIRECTION;
+};
+
+function resolveGestureProgressModePolicy(options: GesturePolicyOptions) {
+	"worklet";
+	return resolveGestureProgressMode({
+		gestureProgressMode: options.gestureProgressMode,
+		gestureDrivesProgress: options.gestureDrivesProgress,
+		fallback: DEFAULT_GESTURE_PROGRESS_MODE,
+	});
+}
+
+const resolveCommonGesturePolicy = (options: GesturePolicyOptions) => {
+	"worklet";
+	return {
+		gestureProgressMode: resolveGestureProgressModePolicy(options),
+		gestureSensitivity:
+			options.gestureSensitivity ?? DEFAULT_GESTURE_SENSITIVITY,
+		gestureSnapVelocityImpact:
+			options.gestureSnapVelocityImpact ?? DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+		gestureSnapLocked: options.gestureSnapLocked ?? DEFAULT_GESTURE_SNAP_LOCKED,
+		gestureReleaseVelocityScale:
+			options.gestureReleaseVelocityScale ??
+			DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+		transitionSpec: options.transitionSpec,
+	};
+};
+
+function resolvePolicySheetScrollGestureBehavior(
+	options: GesturePolicyOptions,
+): SheetScrollGestureBehavior {
+	"worklet";
+	const explicitBehavior = options.sheetScrollGestureBehavior;
+	if (explicitBehavior) {
+		return explicitBehavior;
+	}
+
+	const legacyBehavior = options.expandViaScrollView;
+	if (legacyBehavior !== undefined) {
+		return legacyBehavior ? "expand-and-collapse" : "collapse-only";
+	}
+
+	return DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR;
+}
+
+const resolvePinchDirections = (
+	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>,
+	hasSnapPoints: boolean,
+) => {
+	"worklet";
+	const pinchDirections = getPinchGestureDirections(gestureDirection);
+	const snapDirections = hasSnapPoints
+		? getSnapPinchDirectionConfig(gestureDirection)
+		: null;
+
+	if (snapDirections) {
+		return {
+			snapDirections,
+			pinchInEnabled: true,
+			pinchOutEnabled: true,
+		};
+	}
+
+	return {
+		snapDirections,
+		pinchInEnabled: pinchDirections.includes("pinch-in"),
+		pinchOutEnabled: pinchDirections.includes("pinch-out"),
+	};
+};
+
+const resolveGestureCanDismiss = ({
+	isFirstKey,
+	gestureEnabled,
+}: {
+	isFirstKey: boolean;
+	gestureEnabled?: boolean;
+}) => {
+	"worklet";
+	return Boolean(isFirstKey ? false : gestureEnabled);
+};
+
+export const resolveGestureCanTrack = ({
+	isFirstKey,
+	canDismiss,
+	hasSnapPoints,
+	allowDisabledGestureTracking,
+}: {
+	isFirstKey: boolean;
+	canDismiss: boolean;
+	hasSnapPoints: boolean;
+	allowDisabledGestureTracking?: boolean;
+}) => {
+	"worklet";
+	if (isFirstKey) {
+		return false;
+	}
+
+	if (canDismiss) {
+		return true;
+	}
+
+	if (hasSnapPoints) {
+		return true;
+	}
+
+	return allowDisabledGestureTracking === true;
+};
+
+export const resolvePanPolicy = (
+	options: GesturePolicyOptions,
+	hasSnapPoints: boolean,
+): PanGesturePolicy => {
+	"worklet";
+	const gestureDirection = resolveGestureDirection(options);
+	const hasPanDirection = getPanGestureDirections(gestureDirection).length > 0;
+
+	return {
+		enabled: hasPanDirection,
+		gestureDirection,
+		panActivationDirections: getPanActivationDirections({
+			gestureDirection,
+			hasSnapPoints,
+		}),
+		snapAxisDirections: getPanSnapAxisDirections(gestureDirection),
+		...resolveCommonGesturePolicy(options),
+		gestureVelocityImpact:
+			options.gestureVelocityImpact ?? DEFAULT_GESTURE_VELOCITY_IMPACT,
+		gestureActivationArea:
+			options.gestureActivationArea ?? DEFAULT_GESTURE_ACTIVATION_AREA,
+		sheetScrollGestureBehavior:
+			resolvePolicySheetScrollGestureBehavior(options),
+		gestureResponseDistance: options.gestureResponseDistance,
+	};
+};
+
+export const resolvePinchPolicy = (
+	options: GesturePolicyOptions,
+	hasSnapPoints: boolean,
+): PinchGesturePolicy => {
+	"worklet";
+	const gestureDirection = resolveGestureDirection(options);
+	const pinchDirections = resolvePinchDirections(
+		gestureDirection,
+		hasSnapPoints,
+	);
+
+	return {
+		enabled: pinchDirections.pinchInEnabled || pinchDirections.pinchOutEnabled,
+		gestureDirection,
+		...pinchDirections,
+		...resolveCommonGesturePolicy(options),
+	};
+};
+
+const resolveGestureParticipation = ({
+	options,
+	isFirstKey,
+	gestureContext,
+}: {
+	options: GesturePolicyOptions;
+	isFirstKey: boolean;
+	gestureContext: GestureContextType | null;
+}): ScreenGestureParticipation => {
+	const canDismiss = resolveGestureCanDismiss({
+		isFirstKey,
+		gestureEnabled: options.gestureEnabled,
+	});
+	const effectiveSnapPoints = validateSnapPoints({
+		snapPoints: options.snapPoints,
+		canDismiss,
+	});
+	const canTrackGesture = resolveGestureCanTrack({
+		isFirstKey,
+		canDismiss,
+		hasSnapPoints: effectiveSnapPoints.hasSnapPoints,
+		allowDisabledGestureTracking:
+			options.experimental_allowDisabledGestureTracking,
+	});
+	const claimedDirections = computeClaimedDirections(
+		canTrackGesture,
+		options.gestureDirection,
+		effectiveSnapPoints.hasSnapPoints,
+	);
+
+	return {
+		isFirstKey,
+		canDismiss,
+		canTrackGesture,
+		effectiveSnapPoints,
+		claimedDirections,
+		ownershipStatus: resolveOwnership(claimedDirections, gestureContext),
+	};
+};
+
+export const resolveScreenGestureConfig = ({
+	options,
+	isFirstKey,
+	gestureContext,
+}: {
+	options: ScreenTransitionConfig;
+	isFirstKey: boolean;
+	gestureContext: GestureContextType | null;
+}): ScreenGestureConfig => {
+	const participation = resolveGestureParticipation({
+		options,
+		isFirstKey,
+		gestureContext,
+	});
+	const hasSnapPoints = participation.effectiveSnapPoints.hasSnapPoints;
+
+	return {
+		participation,
+		pan: resolvePanPolicy(options, hasSnapPoints),
+		pinch: resolvePinchPolicy(options, hasSnapPoints),
+	};
+};
+
+function resolveRuntimeCanDismiss(
+	participation: Pick<ScreenGestureParticipation, "isFirstKey" | "canDismiss">,
+	options: GesturePolicyOptions,
+) {
+	"worklet";
+	if (participation.isFirstKey) {
+		return false;
+	}
+
+	const gestureEnabled = options.gestureEnabled;
+	if (gestureEnabled === false) {
+		return false;
+	}
+
+	if (gestureEnabled === true) {
+		return true;
+	}
+
+	return participation.canDismiss;
+}
+
+function resolveRuntimeCanTrackGesture(
+	participation: Pick<
+		ScreenGestureParticipation,
+		"isFirstKey" | "canTrackGesture" | "effectiveSnapPoints"
+	>,
+	options: GesturePolicyOptions,
+) {
+	"worklet";
+	if (participation.isFirstKey) {
+		return false;
+	}
+
+	if (options.experimental_allowDisabledGestureTracking === true) {
+		return true;
+	}
+
+	const gestureEnabled = options.gestureEnabled;
+	if (gestureEnabled === true) {
+		return true;
+	}
+
+	if (gestureEnabled === false) {
+		return participation.effectiveSnapPoints.hasSnapPoints;
+	}
+
+	return participation.canTrackGesture;
+}
+
+export const resolveRuntimeGestureParticipation = ({
+	participation,
+	options,
+}: {
+	participation: ScreenGestureParticipation;
+	options: GesturePolicyOptions;
+}): ScreenGestureParticipation => {
+	"worklet";
+	const canDismiss = resolveRuntimeCanDismiss(participation, options);
+	const canTrackGesture = resolveRuntimeCanTrackGesture(participation, options);
+
+	return {
+		...participation,
+		canDismiss,
+		canTrackGesture,
+	};
+};

package/src/shared/providers/screen/gestures/shared/release.ts

@@ -0,0 +1,43 @@
+import type { TransitionSpec } from "../../../../types/animation.types";
+import { resolveSnapTransitionSpec } from "../../../../utils/animation/resolve-snap-transition-spec";
+
+export const getProgressVelocityTowardTarget = ({
+	handoffVelocity,
+	target,
+	currentProgress,
+}: {
+	handoffVelocity: number;
+	target: number;
+	currentProgress: number;
+}) => {
+	"worklet";
+	const progressDirection = Math.sign(target - currentProgress);
+
+	if (progressDirection === 0) {
+		return 0;
+	}
+
+	return progressDirection * Math.abs(handoffVelocity);
+};
+
+export const resolveGestureSnapTransitionSpec = ({
+	transitionSpec,
+	shouldDismiss,
+	target,
+	currentProgress,
+}: {
+	transitionSpec: TransitionSpec | undefined;
+	shouldDismiss: boolean;
+	target: number;
+	currentProgress: number;
+}) => {
+	"worklet";
+	if (shouldDismiss) {
+		return transitionSpec;
+	}
+
+	return resolveSnapTransitionSpec(
+		transitionSpec,
+		target < currentProgress ? "collapse" : "expand",
+	);
+};