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

package/src/shared/providers/screen/gestures/pinch/pinch-lifecycle.ts

@@ -0,0 +1,104 @@
+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 { normalizePinchScale } from "../shared/physics";
+import type {
+	PinchGestureEvent,
+	PinchGestureRuntime,
+	PinchReleaseResult,
+	PinchTrackState,
+} from "../types";
+import { resetPinchGestureValues } from "./pinch-reset";
+
+export const startPinchBase = (
+	runtime: PinchGestureRuntime,
+	event: PinchGestureEvent,
+) => {
+	"worklet";
+	const {
+		stores: { gestures, animations },
+		gestureProgressBaseline,
+	} = runtime;
+
+	const wasSettling = gestures.settling.get();
+	const hasResidualGesture = Math.abs(gestures.normScale.get()) > EPSILON;
+
+	if (!wasSettling || !hasResidualGesture) {
+		emit(animations.willAnimate, TRUE, FALSE);
+	}
+
+	gestures.dragging.set(TRUE);
+	gestures.dismissing.set(0);
+	gestures.settling.set(0);
+	gestures.active.set(null);
+	gestures.direction.set(null);
+	gestures.scale.set(1);
+	gestures.normScale.set(0);
+	gestures.raw.scale.set(1);
+	gestures.raw.normScale.set(0);
+	gestures.focalX.set(event.focalX);
+	gestures.focalY.set(event.focalY);
+	gestureProgressBaseline.set(animations.progress.get());
+};
+
+export const trackPinchGesture = (
+	event: PinchGestureEvent,
+	rawEvent: PinchGestureEvent,
+	gestures: PinchGestureRuntime["stores"]["gestures"],
+): PinchTrackState => {
+	"worklet";
+	const normScale = clamp(normalizePinchScale(event.scale), -1, 1);
+	const scale = clamp(1 + normScale, 0, 2);
+	const rawNormScale = clamp(normalizePinchScale(rawEvent.scale), -1, 1);
+	const rawScale = clamp(1 + rawNormScale, 0, 2);
+
+	gestures.scale.set(scale);
+	gestures.normScale.set(normScale);
+	gestures.focalX.set(event.focalX);
+	gestures.focalY.set(event.focalY);
+	gestures.raw.scale.set(rawScale);
+	gestures.raw.normScale.set(rawNormScale);
+	gestures.active.set(
+		normScale < 0 ? "pinch-in" : normScale > 0 ? "pinch-out" : null,
+	);
+
+	return {
+		scale,
+		normScale,
+	};
+};
+
+export const finalizePinchRelease = (
+	release: PinchReleaseResult,
+	runtime: PinchGestureRuntime,
+	dismissScreen: (() => void) | undefined,
+) => {
+	"worklet";
+	const {
+		stores: { gestures, animations, system },
+	} = runtime;
+
+	if (typeof release.commitProgress === "number") {
+		animations.progress.set(release.commitProgress);
+		system.targetProgress.set(release.commitProgress);
+	}
+
+	resetPinchGestureValues({
+		spec: release.resetSpec,
+		gestures,
+		shouldDismiss: release.shouldDismiss,
+		resetValuesImmediately: release.resetValuesImmediately,
+	});
+
+	animateToProgress({
+		target: release.target,
+		onAnimationFinish: release.shouldDismiss ? dismissScreen : undefined,
+		spec: release.transitionSpec,
+		emitWillAnimate: false,
+		markEntering: false,
+		animations,
+		targetProgress: system.targetProgress,
+		initialVelocity: release.initialVelocity,
+	});
+};

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

@@ -0,0 +1,183 @@
+import { clamp } from "react-native-reanimated";
+import {
+	getPinchReleaseHandoffVelocity,
+	normalizePinchScale,
+	shouldDismissFromPinch,
+} from "../shared/physics";
+import {
+	getProgressVelocityTowardTarget,
+	resolveGestureSnapTransitionSpec,
+} from "../shared/release";
+import {
+	primeRuntimeSnapPoint,
+	resolveRuntimeGestureSnapPoints,
+} from "../shared/snap-points";
+import { determineSnapTarget } from "../shared/targets";
+import type {
+	PinchGestureEvent,
+	PinchGestureRuntime,
+	PinchReleaseResult,
+} from "../types";
+
+const getPinchSnapDirection = (normalizedScale: number) => {
+	"worklet";
+	if (normalizedScale < 0) {
+		return "pinch-in";
+	}
+
+	if (normalizedScale > 0) {
+		return "pinch-out";
+	}
+
+	return null;
+};
+
+const getPinchSnapVelocity = (
+	event: PinchGestureEvent,
+	runtime: PinchGestureRuntime,
+	normalizedScale: number,
+) => {
+	"worklet";
+	const pinchDirection = getPinchSnapDirection(normalizedScale);
+	const snapDirections = runtime.policy.snapDirections;
+
+	if (!pinchDirection || !snapDirections) {
+		return 0;
+	}
+
+	return snapDirections.collapse === pinchDirection
+		? Math.abs(event.velocity)
+		: -Math.abs(event.velocity);
+};
+
+const getPinchSnapReleaseProgress = ({
+	runtime,
+	normalizedScale,
+	minSnapPoint,
+	maxSnapPoint,
+}: {
+	runtime: PinchGestureRuntime;
+	normalizedScale: number;
+	minSnapPoint: number;
+	maxSnapPoint: number;
+}) => {
+	"worklet";
+	const pinchDirection = getPinchSnapDirection(normalizedScale);
+	const snapDirections = runtime.policy.snapDirections;
+
+	if (!pinchDirection || !snapDirections) {
+		return runtime.stores.animations.progress.get();
+	}
+
+	const progressDelta =
+		snapDirections.collapse === pinchDirection
+			? -Math.abs(normalizedScale)
+			: Math.abs(normalizedScale);
+
+	return clamp(
+		runtime.gestureProgressBaseline.get() + progressDelta,
+		minSnapPoint,
+		maxSnapPoint,
+	);
+};
+
+export const primeSnapPinchRelease = (runtime: PinchGestureRuntime) => {
+	"worklet";
+	primeRuntimeSnapPoint(runtime);
+};
+
+export const resolvePinchRelease = (
+	event: PinchGestureEvent,
+	runtime: PinchGestureRuntime,
+): PinchReleaseResult => {
+	"worklet";
+	const {
+		participation,
+		policy,
+		gestureProgressBaseline,
+		stores: { animations },
+	} = runtime;
+	const normalizedScale = clamp(normalizePinchScale(event.scale), -1, 1);
+	const currentProgress = animations.progress.get();
+	const shouldDismiss =
+		participation.canDismiss &&
+		shouldDismissFromPinch(
+			normalizedScale,
+			policy.pinchInEnabled,
+			policy.pinchOutEnabled,
+		);
+	const target = shouldDismiss ? 0 : gestureProgressBaseline.get();
+
+	return {
+		target,
+		shouldDismiss,
+		initialVelocity: getProgressVelocityTowardTarget({
+			handoffVelocity: getPinchReleaseHandoffVelocity(
+				event.velocity,
+				policy.gestureReleaseVelocityScale,
+			),
+			target,
+			currentProgress,
+		}),
+		transitionSpec: policy.transitionSpec,
+		resetSpec: shouldDismiss
+			? policy.transitionSpec?.close
+			: policy.transitionSpec?.open,
+	};
+};
+
+export const resolveSnapPinchRelease = (
+	event: PinchGestureEvent,
+	runtime: PinchGestureRuntime,
+): PinchReleaseResult => {
+	"worklet";
+	const { participation, policy, lockedSnapPoint } = runtime;
+	const normalizedScale = clamp(normalizePinchScale(event.scale), -1, 1);
+
+	const { resolvedSnapPoints, resolvedMinSnapPoint, resolvedMaxSnapPoint } =
+		resolveRuntimeGestureSnapPoints(runtime);
+	const currentProgress = getPinchSnapReleaseProgress({
+		runtime,
+		normalizedScale,
+		minSnapPoint: resolvedMinSnapPoint,
+		maxSnapPoint: resolvedMaxSnapPoint,
+	});
+
+	const result = determineSnapTarget({
+		currentProgress,
+		snapPoints: policy.gestureSnapLocked
+			? [lockedSnapPoint.get()]
+			: resolvedSnapPoints,
+		velocity: getPinchSnapVelocity(event, runtime, normalizedScale),
+		dimension: 1,
+		velocityFactor: policy.gestureSnapVelocityImpact,
+		canDismiss: participation.canDismiss,
+	});
+
+	const shouldDismiss = participation.canDismiss && result.shouldDismiss;
+	const target = shouldDismiss ? 0 : result.targetProgress;
+
+	return {
+		target,
+		shouldDismiss,
+		initialVelocity: getProgressVelocityTowardTarget({
+			handoffVelocity: getPinchReleaseHandoffVelocity(
+				event.velocity,
+				policy.gestureReleaseVelocityScale,
+			),
+			target,
+			currentProgress,
+		}),
+		commitProgress: currentProgress,
+		resetValuesImmediately: policy.gestureProgressMode === "progress-driven",
+		transitionSpec: resolveGestureSnapTransitionSpec({
+			transitionSpec: policy.transitionSpec,
+			shouldDismiss,
+			target,
+			currentProgress,
+		}),
+		resetSpec: shouldDismiss
+			? policy.transitionSpec?.close
+			: policy.transitionSpec?.open,
+	};
+};

package/src/shared/providers/screen/gestures/pinch/pinch-reset.ts

@@ -0,0 +1,65 @@
+import { EPSILON, FALSE, TRUE } from "../../../../constants";
+import type { GestureStoreMap } from "../../../../stores/gesture.store";
+import type { AnimationConfig } from "../../../../types/animation.types";
+import {
+	animateResetValue,
+	clearGestureSettlingIfResting,
+	getGestureResetSpec,
+} from "../shared/reset";
+
+interface ResetPinchGestureValuesProps {
+	spec?: AnimationConfig;
+	gestures: GestureStoreMap;
+	shouldDismiss: boolean;
+	resetValuesImmediately?: boolean;
+}
+
+const clearPinchSettlingIfResting = (gestures: GestureStoreMap) => {
+	"worklet";
+
+	const isResting =
+		!gestures.dragging.get() &&
+		!gestures.dismissing.get() &&
+		Math.abs(gestures.scale.get() - 1) <= EPSILON &&
+		Math.abs(gestures.normScale.get()) <= EPSILON;
+
+	if (isResting) {
+		gestures.focalX.set(0);
+		gestures.focalY.set(0);
+	}
+
+	clearGestureSettlingIfResting(gestures, isResting);
+};
+
+export const resetPinchGestureValues = ({
+	spec,
+	gestures,
+	shouldDismiss,
+	resetValuesImmediately = false,
+}: ResetPinchGestureValuesProps) => {
+	"worklet";
+	const resetSpec = getGestureResetSpec(spec);
+
+	if (!shouldDismiss) {
+		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);
+
+	if (resetValuesImmediately) {
+		gestures.scale.set(1);
+		gestures.normScale.set(0);
+		clearPinchSettlingIfResting(gestures);
+		return;
+	}
+
+	animateResetValue(gestures.scale, 1, resetSpec, () =>
+		clearPinchSettlingIfResting(gestures),
+	);
+	animateResetValue(gestures.normScale, 0, resetSpec, () =>
+		clearPinchSettlingIfResting(gestures),
+	);
+};

package/src/shared/providers/screen/gestures/pinch/use-pinch-behavior.ts

@@ -0,0 +1,82 @@
+import { useCallback } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import { useNavigationHelpers } from "../../../../hooks/navigation/use-navigation-helpers";
+import type { ScreenOptionsContextValue } from "../../options";
+import { usePinchGestureSensitivity } from "../hooks/use-gesture-sensitivity";
+import { resolvePinchRuntime } from "../shared/runtime";
+import type {
+	PinchBehavior,
+	PinchGestureEvent,
+	PinchGestureRuntime,
+} from "../types";
+import {
+	finalizePinchRelease,
+	startPinchBase,
+	trackPinchGesture,
+} from "./pinch-lifecycle";
+import {
+	primeSnapPinchRelease,
+	resolvePinchRelease,
+	resolveSnapPinchRelease,
+} from "./pinch-release";
+
+export const usePinchBehavior = (
+	runtime: SharedValue<PinchGestureRuntime>,
+	screenOptions: ScreenOptionsContextValue,
+): PinchBehavior => {
+	const { dismissScreen } = useNavigationHelpers();
+	const { withSensitivity, resetSensitivity } =
+		usePinchGestureSensitivity(screenOptions);
+
+	const onStart = useCallback(
+		(event: PinchGestureEvent) => {
+			"worklet";
+			const latestRuntime = resolvePinchRuntime(
+				runtime.get(),
+				screenOptions.get(),
+			);
+			if (latestRuntime.participation.effectiveSnapPoints.hasSnapPoints) {
+				primeSnapPinchRelease(latestRuntime);
+			}
+			startPinchBase(latestRuntime, event);
+			resetSensitivity();
+		},
+		[runtime, screenOptions, resetSensitivity],
+	);
+
+	const onUpdate = useCallback(
+		(rawEvent: PinchGestureEvent) => {
+			"worklet";
+			const latestRuntime = resolvePinchRuntime(
+				runtime.get(),
+				screenOptions.get(),
+			);
+			const event = withSensitivity(rawEvent);
+			trackPinchGesture(event, rawEvent, latestRuntime.stores.gestures);
+		},
+		[runtime, screenOptions, withSensitivity],
+	);
+
+	const onEnd = useCallback(
+		(rawEvent: PinchGestureEvent) => {
+			"worklet";
+			const latestRuntime = resolvePinchRuntime(
+				runtime.get(),
+				screenOptions.get(),
+			);
+			const event = withSensitivity(rawEvent);
+			const release = latestRuntime.participation.effectiveSnapPoints
+				.hasSnapPoints
+				? resolveSnapPinchRelease(event, latestRuntime)
+				: resolvePinchRelease(event, latestRuntime);
+			finalizePinchRelease(release, latestRuntime, dismissScreen);
+		},
+		[runtime, screenOptions, dismissScreen, withSensitivity],
+	);
+
+	return {
+		onStart,
+		onUpdate,
+		onEnd,
+	};
+};

package/src/shared/providers/screen/gestures/scroll-coordination/index.ts

@@ -0,0 +1 @@
+export { useScrollGestureCoordination } from "./use-scroll-gesture-coordination";

package/src/shared/providers/screen/gestures/scroll-coordination/update-scroll-gesture-state.ts

@@ -0,0 +1,44 @@
+import type {
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+} from "../types";
+
+const createScrollGestureState = (): ScrollGestureState => {
+	"worklet";
+	return {
+		vertical: { offset: 0, contentSize: 0, layoutSize: 0 },
+		horizontal: { offset: 0, contentSize: 0, layoutSize: 0 },
+		isTouched: false,
+	};
+};
+
+export const updateScrollGestureAxisState = (
+	state: ScrollGestureState | null,
+	axis: ScrollGestureAxis,
+	patch: Partial<ScrollGestureAxisState> & { isTouched?: boolean },
+): ScrollGestureState => {
+	"worklet";
+
+	const nextState = state ?? createScrollGestureState();
+
+	const axisState = nextState[axis];
+
+	if (patch.offset !== undefined) {
+		axisState.offset = patch.offset;
+	}
+
+	if (patch.contentSize !== undefined) {
+		axisState.contentSize = patch.contentSize;
+	}
+
+	if (patch.layoutSize !== undefined) {
+		axisState.layoutSize = patch.layoutSize;
+	}
+
+	if (patch.isTouched !== undefined) {
+		nextState.isTouched = patch.isTouched;
+	}
+
+	return nextState;
+};

package/src/shared/providers/screen/gestures/scroll-coordination/use-scroll-gesture-coordination.ts

@@ -0,0 +1,180 @@
+import { useMemo } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import { Gesture, type GestureType } from "react-native-gesture-handler";
+import {
+	type SharedValue,
+	useAnimatedScrollHandler,
+	useDerivedValue,
+} from "react-native-reanimated";
+import { useSharedValueState } from "../../../../hooks/reanimated/use-shared-value-state";
+import useStableCallback from "../../../../hooks/use-stable-callback";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { useGestureContext } from "../gestures.provider";
+import type {
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+} from "../types";
+import { updateScrollGestureAxisState } from "./update-scroll-gesture-state";
+import { walkUpScrollGestureCoordination } from "./walk-up-scroll-gesture-coordination";
+
+interface ScrollGestureCoordinationProps {
+	onContentSizeChange?: (width: number, height: number) => void;
+	onLayout?: (event: LayoutChangeEvent) => void;
+	direction?: ScrollGestureAxis;
+}
+
+type ScrollGesturePatch = Partial<ScrollGestureAxisState> & {
+	isTouched?: boolean;
+};
+
+const modifyScrollGestureAxisState = (
+	scrollState: SharedValue<ScrollGestureState | null>,
+	axis: ScrollGestureAxis,
+	patch: ScrollGesturePatch,
+) => {
+	"worklet";
+
+	scrollState.modify(<T extends ScrollGestureState | null>(state: T): T => {
+		"worklet";
+		return updateScrollGestureAxisState(state, axis, patch) as T;
+	});
+};
+
+/**
+ * Returns scroll handlers and a native gesture for ScrollView coordination.
+ *
+ * Finds ALL gesture owners for the scroll axis (both directions) and coordinates
+ * with each of them. This ensures that:
+ * - A screen claiming `vertical-inverted` can handle swipe-up at bottom boundary
+ * - An ancestor claiming `vertical` can handle swipe-down at top boundary
+ * - Both work correctly with the same ScrollView
+ */
+export const useScrollGestureCoordination = (
+	props: ScrollGestureCoordinationProps,
+) => {
+	const context = useGestureContext();
+	const scrollDirection = props.direction ?? "vertical";
+
+	const { scrollStates, panGestures, pinchGestures, ownerRouteKeys } = useMemo(
+		() => walkUpScrollGestureCoordination(context, scrollDirection),
+		[context, scrollDirection],
+	);
+
+	const ownerClosingValues = useMemo(
+		() =>
+			ownerRouteKeys.map((routeKey) =>
+				AnimationStore.getValue(routeKey, "closing"),
+			),
+		[ownerRouteKeys],
+	);
+
+	const scrollEventsEnabled = useSharedValueState(
+		useDerivedValue(() => {
+			"worklet";
+			for (let i = 0; i < ownerClosingValues.length; i++) {
+				if (ownerClosingValues[i].get()) {
+					return false;
+				}
+			}
+
+			return true;
+		}),
+	);
+
+	const nativeGesture = useMemo(() => {
+		if (panGestures.length === 0 && pinchGestures.length === 0) return null;
+
+		const setIsTouched = () => {
+			"worklet";
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					isTouched: true,
+				});
+			}
+		};
+
+		const clearIsTouched = () => {
+			"worklet";
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					isTouched: false,
+				});
+			}
+		};
+
+		let gesture = Gesture.Native()
+			.onTouchesDown(setIsTouched)
+			.onTouchesUp(clearIsTouched)
+			.onTouchesCancelled(clearIsTouched);
+
+		for (const panGesture of panGestures) {
+			gesture = gesture.requireExternalGestureToFail({
+				current: panGesture as unknown as GestureType,
+			});
+		}
+
+		for (const pinchGesture of pinchGestures) {
+			gesture = gesture.requireExternalGestureToFail({
+				current: pinchGesture as unknown as GestureType,
+			});
+		}
+
+		return gesture;
+	}, [panGestures, pinchGestures, scrollStates, scrollDirection]);
+
+	const scrollHandler = useAnimatedScrollHandler({
+		onScroll: (event) => {
+			if (scrollStates.length === 0) return;
+
+			const offset =
+				scrollDirection === "horizontal"
+					? event.contentOffset.x
+					: event.contentOffset.y;
+
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					offset,
+					isTouched: scrollState.get()?.isTouched ?? true,
+				});
+			}
+		},
+	});
+
+	const onContentSizeChange = useStableCallback(
+		(width: number, height: number) => {
+			props.onContentSizeChange?.(width, height);
+			if (scrollStates.length === 0) return;
+
+			const contentSize = scrollDirection === "horizontal" ? width : height;
+
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					contentSize,
+				});
+			}
+		},
+	);
+
+	const onLayout = useStableCallback((event: LayoutChangeEvent) => {
+		props.onLayout?.(event);
+		if (scrollStates.length === 0) return;
+
+		const { width, height } = event.nativeEvent.layout;
+		const layoutSize = scrollDirection === "horizontal" ? width : height;
+
+		for (const scrollState of scrollStates) {
+			modifyScrollGestureAxisState(scrollState, scrollDirection, {
+				layoutSize,
+			});
+		}
+	});
+
+	return {
+		scrollHandler,
+		scrollEventsEnabled,
+		onContentSizeChange,
+		onLayout,
+		nativeGesture,
+	};
+};