react-native-screen-transitions 3.5.2 → 3.6.0-alpha.1

package/src/shared/providers/screen/gestures/shared/snap-points.ts

@@ -0,0 +1,250 @@
+import type { SnapPoint } from "../../../../types/screen.types";
+import type { GesturePolicy, GestureRuntime } from "../types";
+
+const createEmptySnapPoints = (): EffectiveSnapPointsResult => ({
+	hasSnapPoints: false,
+	hasAutoSnapPoint: false,
+	snapPoints: [],
+	minSnapPoint: -1,
+	maxSnapPoint: -1,
+});
+
+const isNumericSnapPoint = (point: SnapPoint): point is number => {
+	"worklet";
+	return typeof point === "number" && Number.isFinite(point);
+};
+
+const canUseSnapPoint = (point: number, canDismiss: boolean) => {
+	"worklet";
+	return canDismiss || point > 0;
+};
+
+/**
+ * Filters snap points to only valid, finite numeric values.
+ * Excludes zero (dismiss) when canDismiss is false.
+ */
+export function sanitizeSnapPoints(
+	snapPoints: SnapPoint[],
+	canDismiss: boolean,
+): number[] {
+	"worklet";
+	const normalized: number[] = [];
+
+	for (let i = 0; i < snapPoints.length; i++) {
+		const point = snapPoints[i];
+		if (!isNumericSnapPoint(point) || !canUseSnapPoint(point, canDismiss)) {
+			continue;
+		}
+
+		normalized.push(point);
+	}
+
+	return normalized;
+}
+
+export interface EffectiveSnapPointsResult {
+	hasSnapPoints: boolean;
+	hasAutoSnapPoint: boolean;
+	snapPoints: number[];
+	minSnapPoint: number;
+	maxSnapPoint: number;
+}
+
+interface ResolveRuntimeSnapPointsProps {
+	snapPoints: number[];
+	hasAutoSnapPoint: boolean;
+	resolvedAutoSnapPoint: number;
+	minSnapPoint: number;
+	maxSnapPoint: number;
+	canDismiss: boolean;
+}
+
+interface ResolvedRuntimeSnapPointsResult {
+	resolvedSnapPoints: number[];
+	resolvedMinSnapPoint: number;
+	resolvedMaxSnapPoint: number;
+}
+
+interface ValidateSnapPointsOptions {
+	snapPoints?: SnapPoint[];
+	canDismiss?: boolean;
+}
+
+const hasRuntimeSnapPoints = (snapPoints: SnapPoint[]) => {
+	return snapPoints.length > 0;
+};
+
+const hasResolvedSnapPoints = (
+	snapPoints: number[],
+	hasAutoSnapPoint: boolean,
+) => {
+	return snapPoints.length > 0 || hasAutoSnapPoint;
+};
+
+const getMinSnapPoint = (snapPoints: number[], canDismiss?: boolean) => {
+	return canDismiss ? 0 : (snapPoints[0] ?? -1);
+};
+
+const getMaxSnapPoint = (snapPoints: number[]) => {
+	return snapPoints[snapPoints.length - 1] ?? -1;
+};
+
+const resolveAutoSnapPoint = (
+	hasAutoSnapPoint: boolean,
+	resolvedAutoSnapPoint: number,
+) => {
+	"worklet";
+	return hasAutoSnapPoint && resolvedAutoSnapPoint > 0
+		? resolvedAutoSnapPoint
+		: null;
+};
+
+const addAutoSnapPoint = (
+	snapPoints: number[],
+	resolvedAutoSnapPoint: number | null,
+) => {
+	"worklet";
+	return resolvedAutoSnapPoint === null
+		? snapPoints
+		: [...snapPoints, resolvedAutoSnapPoint].sort((a, b) => a - b);
+};
+
+const resolveMinSnapPoint = ({
+	minSnapPoint,
+	resolvedAutoSnapPoint,
+	canDismiss,
+}: {
+	minSnapPoint: number;
+	resolvedAutoSnapPoint: number | null;
+	canDismiss: boolean;
+}) => {
+	"worklet";
+	if (resolvedAutoSnapPoint === null || canDismiss) {
+		return minSnapPoint;
+	}
+
+	return Math.min(
+		minSnapPoint === -1 ? resolvedAutoSnapPoint : minSnapPoint,
+		resolvedAutoSnapPoint,
+	);
+};
+
+export const validateSnapPoints = ({
+	snapPoints,
+	canDismiss,
+}: ValidateSnapPointsOptions): EffectiveSnapPointsResult => {
+	if (!snapPoints || !hasRuntimeSnapPoints(snapPoints)) {
+		return createEmptySnapPoints();
+	}
+
+	const hasAuto = snapPoints.includes("auto");
+	const normalizedSnaps = sanitizeSnapPoints(snapPoints, canDismiss ?? false);
+
+	if (!hasResolvedSnapPoints(normalizedSnaps, hasAuto)) {
+		return createEmptySnapPoints();
+	}
+
+	const sortedSnaps = normalizedSnaps.slice().sort((a, b) => a - b);
+
+	return {
+		hasSnapPoints: true,
+		hasAutoSnapPoint: hasAuto,
+		snapPoints: sortedSnaps,
+		minSnapPoint: getMinSnapPoint(sortedSnaps, canDismiss),
+		maxSnapPoint: getMaxSnapPoint(sortedSnaps),
+	};
+};
+
+export const resolveRuntimeSnapPoints = ({
+	snapPoints,
+	hasAutoSnapPoint,
+	resolvedAutoSnapPoint,
+	minSnapPoint,
+	maxSnapPoint,
+	canDismiss,
+}: ResolveRuntimeSnapPointsProps): ResolvedRuntimeSnapPointsResult => {
+	"worklet";
+
+	const resolvedAuto = resolveAutoSnapPoint(
+		hasAutoSnapPoint,
+		resolvedAutoSnapPoint,
+	);
+	const resolvedSnapPoints = addAutoSnapPoint(snapPoints, resolvedAuto);
+
+	return {
+		resolvedSnapPoints,
+		resolvedMinSnapPoint: resolveMinSnapPoint({
+			minSnapPoint,
+			resolvedAutoSnapPoint: resolvedAuto,
+			canDismiss,
+		}),
+		resolvedMaxSnapPoint:
+			resolvedSnapPoints[resolvedSnapPoints.length - 1] ?? maxSnapPoint,
+	};
+};
+
+export const resolveRuntimeGestureSnapPoints = (
+	runtime: GestureRuntime<GesturePolicy>,
+): ResolvedRuntimeSnapPointsResult => {
+	"worklet";
+	const {
+		participation,
+		stores: { system },
+	} = runtime;
+	const { hasAutoSnapPoint, snapPoints, minSnapPoint, maxSnapPoint } =
+		participation.effectiveSnapPoints;
+
+	return resolveRuntimeSnapPoints({
+		snapPoints,
+		hasAutoSnapPoint,
+		resolvedAutoSnapPoint: system.resolvedAutoSnapPoint.get(),
+		minSnapPoint,
+		maxSnapPoint,
+		canDismiss: participation.canDismiss,
+	});
+};
+
+const findNearestSnapPoint = (
+	progress: number,
+	snapPoints: number[],
+): number => {
+	"worklet";
+
+	let nearest = snapPoints[0] ?? progress;
+	let smallestDistance = Math.abs(progress - nearest);
+
+	for (let i = 1; i < snapPoints.length; i++) {
+		const point = snapPoints[i];
+		const distance = Math.abs(progress - point);
+
+		if (distance < smallestDistance) {
+			smallestDistance = distance;
+			nearest = point;
+		}
+	}
+
+	return nearest;
+};
+
+export const primeRuntimeSnapPoint = (
+	runtime: GestureRuntime<GesturePolicy>,
+) => {
+	"worklet";
+	const {
+		policy,
+		stores: { animations },
+		lockedSnapPoint,
+	} = runtime;
+
+	const { resolvedSnapPoints, resolvedMaxSnapPoint } =
+		resolveRuntimeGestureSnapPoints(runtime);
+
+	if (policy.gestureSnapLocked) {
+		lockedSnapPoint.set(
+			findNearestSnapPoint(animations.progress.get(), resolvedSnapPoints),
+		);
+		return;
+	}
+
+	lockedSnapPoint.set(resolvedMaxSnapPoint);
+};

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

@@ -0,0 +1,202 @@
+import { DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT } from "../../../../constants";
+import type { GestureDirections } from "../../../../types/gesture.types";
+import { shouldDismissFromProjection } from "./physics";
+import { sanitizeSnapPoints } from "./snap-points";
+
+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 isMovingTowardDismiss = (
+	positiveDirectionEnabled: boolean,
+	negativeDirectionEnabled: boolean,
+	translation: number,
+) => {
+	"worklet";
+	return (
+		(positiveDirectionEnabled && translation > 0) ||
+		(negativeDirectionEnabled && translation < 0)
+	);
+};
+
+const shouldDismissAlongAxis = ({
+	positiveDirectionEnabled,
+	negativeDirectionEnabled,
+	translation,
+	velocity,
+	dimension,
+	gestureVelocityImpact,
+}: {
+	positiveDirectionEnabled: boolean;
+	negativeDirectionEnabled: boolean;
+	translation: number;
+	velocity: number;
+	dimension: number;
+	gestureVelocityImpact: number;
+}) => {
+	"worklet";
+	return (
+		isMovingTowardDismiss(
+			positiveDirectionEnabled,
+			negativeDirectionEnabled,
+			translation,
+		) &&
+		shouldDismissFromProjection(
+			translation,
+			velocity,
+			dimension,
+			gestureVelocityImpact,
+		)
+	);
+};
+
+export const determineDismissal = ({
+	event,
+	directions,
+	dimensions,
+	gestureVelocityImpact,
+}: DetermineDismissalProps) => {
+	"worklet";
+
+	const verticalDismiss = shouldDismissAlongAxis({
+		positiveDirectionEnabled: directions.vertical,
+		negativeDirectionEnabled: directions.verticalInverted,
+		translation: event.translationY,
+		velocity: event.velocityY,
+		dimension: dimensions.height,
+		gestureVelocityImpact,
+	});
+	const horizontalDismiss = shouldDismissAlongAxis({
+		positiveDirectionEnabled: directions.horizontal,
+		negativeDirectionEnabled: directions.horizontalInverted,
+		translation: event.translationX,
+		velocity: event.velocityX,
+		dimension: dimensions.width,
+		gestureVelocityImpact,
+	});
+
+	return { shouldDismiss: verticalDismiss || horizontalDismiss };
+};
+
+const buildSnapTargetList = (snapPoints: number[], canDismiss: boolean) => {
+	"worklet";
+	const sanitizedSnapPoints = sanitizeSnapPoints(snapPoints, canDismiss);
+	const targets = canDismiss
+		? [0, ...sanitizedSnapPoints]
+		: sanitizedSnapPoints;
+
+	return Array.from(new Set(targets)).sort((a, b) => a - b);
+};
+
+const projectSnapProgress = (
+	currentProgress: number,
+	velocity: number,
+	dimension: number,
+	velocityFactor: number,
+) => {
+	"worklet";
+	// Convert velocity to progress units (positive = toward dismiss = decreasing progress)
+	const velocityInProgress = (velocity / dimension) * velocityFactor;
+	return currentProgress - velocityInProgress;
+};
+
+const findTargetForProjectedProgress = (
+	projectedProgress: number,
+	targets: number[],
+) => {
+	"worklet";
+	let targetProgress = targets[0];
+
+	for (let i = 0; i < targets.length; i++) {
+		const current = targets[i];
+		const next = targets[i + 1];
+
+		if (next === undefined) {
+			return current;
+		}
+
+		const midpoint = (current + next) / 2;
+
+		if (projectedProgress < midpoint) {
+			return current;
+		}
+
+		targetProgress = next;
+	}
+
+	return targetProgress;
+};
+
+/**
+ * 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,
+	canDismiss,
+}: DetermineSnapTargetProps): DetermineSnapTargetResult {
+	"worklet";
+	const resolvedVelocityFactor =
+		velocityFactor ?? DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT;
+	const resolvedCanDismiss = canDismiss ?? true;
+	const allTargets = buildSnapTargetList(snapPoints, resolvedCanDismiss);
+
+	if (allTargets.length === 0) {
+		return {
+			targetProgress: currentProgress,
+			shouldDismiss: false,
+		};
+	}
+
+	const targetProgress = findTargetForProjectedProgress(
+		projectSnapProgress(
+			currentProgress,
+			velocity,
+			dimension,
+			resolvedVelocityFactor,
+		),
+		allTargets,
+	);
+
+	return {
+		targetProgress,
+		shouldDismiss: resolvedCanDismiss && targetProgress === 0,
+	};
+}

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

@@ -0,0 +1,216 @@
+import type {
+	Gesture,
+	GestureStateChangeEvent,
+	GestureUpdateEvent,
+	PanGestureHandlerEventPayload,
+	PinchGestureHandlerEventPayload,
+} from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+import type { GestureStoreMap } from "../../../stores/gesture.store";
+import type { SystemStoreMap } from "../../../stores/system.store";
+import type {
+	AnimationConfig,
+	TransitionSpec,
+} from "../../../types/animation.types";
+import type {
+	GestureActivationArea,
+	GestureDirections,
+	GestureProgressMode,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	SnapPanDirectionConfig,
+	SnapPinchDirectionConfig,
+} from "../../../types/gesture.types";
+import type {
+	ClaimedDirections,
+	DirectionOwnership,
+} from "../../../types/ownership.types";
+import type { ScreenTransitionConfig } from "../../../types/screen.types";
+import type { EffectiveSnapPointsResult } from "./shared/snap-points";
+
+export type PanGesture = ReturnType<typeof Gesture.Pan>;
+export type PinchGesture = ReturnType<typeof Gesture.Pinch>;
+export type ComposedGesture = ReturnType<typeof Gesture.Race>;
+
+export type PanGestureEvent =
+	| GestureUpdateEvent<PanGestureHandlerEventPayload>
+	| GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+
+export type PinchGestureEvent =
+	| GestureUpdateEvent<PinchGestureHandlerEventPayload>
+	| GestureStateChangeEvent<PinchGestureHandlerEventPayload>;
+
+export type {
+	GestureProgressMode,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+};
+
+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_DIRECTION_CLAIMS: DirectionClaimMap = {
+	vertical: null,
+	"vertical-inverted": null,
+	horizontal: null,
+	"horizontal-inverted": null,
+};
+
+export interface GestureContextType {
+	routeKey: string;
+	detectorGesture: ComposedGesture;
+	panGesture: PanGesture;
+	pinchGesture: PinchGesture;
+	scrollState: SharedValue<ScrollGestureState | null>;
+	gestureContext: GestureContextType | null;
+	claimedDirections: ClaimedDirections;
+	childDirectionClaims: SharedValue<DirectionClaimMap>;
+}
+
+export interface ScreenGestureParticipation {
+	/** Whether this route is the first route in its stack. First routes never track gestures. */
+	isFirstKey: boolean;
+	/** Whether this route can dismiss to progress 0 from a gesture release. */
+	canDismiss: boolean;
+	/** Whether recognizers can activate to expose gesture values to interpolators. */
+	canTrackGesture: boolean;
+	effectiveSnapPoints: EffectiveSnapPointsResult;
+	claimedDirections: ClaimedDirections;
+	ownershipStatus: DirectionOwnership;
+}
+
+export interface ScreenGestureConfig {
+	participation: ScreenGestureParticipation;
+	pan: PanGesturePolicy;
+	pinch: PinchGesturePolicy;
+}
+
+export interface PanGesturePolicy {
+	enabled: boolean;
+	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>;
+	panActivationDirections: GestureDirections;
+	snapAxisDirections: SnapPanDirectionConfig;
+	gestureProgressMode: GestureProgressMode;
+	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
+	gestureVelocityImpact: number;
+	gestureSnapVelocityImpact: number;
+	gestureReleaseVelocityScale: number;
+	gestureActivationArea: GestureActivationArea;
+	gestureSnapLocked: boolean;
+	sheetScrollGestureBehavior: NonNullable<
+		ScreenTransitionConfig["sheetScrollGestureBehavior"]
+	>;
+	gestureResponseDistance: ScreenTransitionConfig["gestureResponseDistance"];
+	transitionSpec: TransitionSpec | undefined;
+}
+
+export interface PinchGesturePolicy {
+	enabled: boolean;
+	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>;
+	snapDirections: SnapPinchDirectionConfig;
+	pinchInEnabled: boolean;
+	pinchOutEnabled: boolean;
+	gestureProgressMode: GestureProgressMode;
+	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
+	gestureSnapVelocityImpact: number;
+	gestureSnapLocked: boolean;
+	gestureReleaseVelocityScale: number;
+	transitionSpec: TransitionSpec | undefined;
+}
+
+export interface GestureRuntimeStores {
+	gestures: GestureStoreMap;
+	animations: AnimationStoreMap;
+	system: SystemStoreMap;
+}
+
+export type GesturePolicy = PanGesturePolicy | PinchGesturePolicy;
+
+export interface GestureRuntime<TPolicy extends GesturePolicy> {
+	participation: ScreenGestureParticipation;
+	policy: TPolicy;
+	stores: GestureRuntimeStores;
+	gestureProgressBaseline: SharedValue<number>;
+	lockedSnapPoint: SharedValue<number>;
+}
+
+export type PanGestureRuntime = GestureRuntime<PanGesturePolicy>;
+
+export type PinchGestureRuntime = GestureRuntime<PinchGesturePolicy>;
+
+export interface GestureDimensions {
+	width: number;
+	height: number;
+}
+
+export interface PanTrackState {
+	x: number;
+	y: number;
+	normX: number;
+	normY: number;
+}
+
+export interface PinchTrackState {
+	scale: number;
+	normScale: number;
+}
+
+export interface PanReleaseResult {
+	target: number;
+	shouldDismiss: boolean;
+	initialVelocity: number;
+	commitProgress?: number;
+	resetNormalizedValuesImmediately?: boolean;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PanReleasePlan {
+	target: number;
+	shouldDismiss: boolean;
+	progressVelocity: number;
+	resetVelocityX: number;
+	resetVelocityY: number;
+	resetVelocityNormX: number;
+	resetVelocityNormY: number;
+	resetNormalizedValues: boolean;
+	resetNormalizedValuesImmediately: boolean;
+	preserveRawValues: boolean;
+	commitProgress?: number;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PinchReleaseResult {
+	target: number;
+	shouldDismiss: boolean;
+	initialVelocity: number;
+	commitProgress?: number;
+	resetValuesImmediately?: boolean;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PanBehavior {
+	onStart: () => void;
+	onUpdate: (event: PanGestureEvent) => void;
+	onEnd: (event: PanGestureEvent) => void;
+}
+
+export interface PinchBehavior {
+	onStart: (event: PinchGestureEvent) => void;
+	onUpdate: (event: PinchGestureEvent) => void;
+	onEnd: (event: PinchGestureEvent) => void;
+}