react-native-screen-transitions 4.1.0-alpha.0 → 4.1.0-beta.1

package/src/providers/screen/motion/gestures/pinch/behavior/pinch-lifecycle.ts

@@ -0,0 +1,112 @@
+import { clamp } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { EPSILON, TRUE } from "../../../../../../constants";
+import { animateToProgress } from "../../../../../../utils/animation/animate-to-progress";
+import { emitMotionStart } from "../../../animation/emit-motion-start";
+import { normalizePinchScale } from "../../shared/physics";
+import { snapshotGestureHandoff } from "../../shared/snapshot";
+import { clearTransformTrackingValues } from "../../shared/values";
+import type {
+	PinchGestureEvent,
+	PinchGestureRuntime,
+	PinchReleaseResult,
+	PinchTrackState,
+} from "../../types";
+import { resetPinchGestureValues } from "./pinch-reset";
+
+export const startPinchBase = (runtime: PinchGestureRuntime) => {
+	"worklet";
+	const {
+		stores: { gestures, animations },
+	} = runtime;
+
+	emitMotionStart(animations);
+	gestures.dragging.set(TRUE);
+	gestures.dismissing.set(0);
+	gestures.settling.set(0);
+	gestures.initiator.set(null);
+	gestures.velocity.set(0);
+	clearTransformTrackingValues(gestures);
+	gestures.internal.progressBaseline.set(animations.transitionProgress.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.raw.scale.set(rawScale);
+	gestures.raw.normScale.set(rawNormScale);
+
+	if (gestures.initiator.get() === null) {
+		gestures.initiator.set(
+			normScale < 0 ? "pinch-in" : normScale > 0 ? "pinch-out" : null,
+		);
+	}
+
+	return {
+		scale,
+		normScale,
+	};
+};
+
+export const finalizePinchRelease = (
+	release: PinchReleaseResult,
+	runtime: PinchGestureRuntime,
+	requestDismiss?: () => void,
+) => {
+	"worklet";
+	const {
+		stores: { gestures, animations, system },
+	} = runtime;
+
+	if (typeof release.commitProgress === "number") {
+		animations.transitionProgress.set(release.commitProgress);
+		system.targetProgress.set(release.commitProgress);
+	}
+
+	const progressAlreadyAtTarget =
+		Math.abs(animations.transitionProgress.get() - release.target) <= EPSILON;
+
+	if (release.shouldDismiss) {
+		snapshotGestureHandoff(gestures, {
+			velocity: release.handoffVelocity,
+		});
+	}
+
+	resetPinchGestureValues({
+		spec: release.resetSpec,
+		gestures,
+		animations,
+		shouldDismiss: release.shouldDismiss,
+		resetValuesImmediately: release.resetValuesImmediately,
+	});
+
+	if (!release.shouldDismiss && progressAlreadyAtTarget) {
+		system.targetProgress.set(release.target);
+		return;
+	}
+
+	animateToProgress({
+		target: release.target,
+		spec: release.transitionSpec,
+		emitWillAnimate: false,
+		markEntering: false,
+		animations,
+		targetProgress: system.targetProgress,
+		animationProgress: system.animationProgress,
+		initialVelocity: release.initialVelocity,
+	});
+
+	if (release.shouldDismiss && requestDismiss) {
+		scheduleOnRN(requestDismiss);
+	}
+};

package/src/providers/screen/motion/gestures/pinch/behavior/pinch-reset.ts

@@ -0,0 +1,73 @@
+import { FALSE, TRUE } from "../../../../../../constants";
+import type { AnimationConfig } from "../../../../../../types/animation.types";
+import type {
+	MotionAnimationValues,
+	MotionGestureValues,
+} from "../../../types";
+import { animateMany } from "../../shared/reset";
+import {
+	clearFocalPoint,
+	clearRawTransformValues,
+	clearTransformTrackingValues,
+} from "../../shared/values";
+
+interface ResetPinchGestureValuesProps {
+	spec?: AnimationConfig;
+	gestures: MotionGestureValues;
+	animations?: MotionAnimationValues;
+	shouldDismiss: boolean;
+	resetValuesImmediately?: boolean;
+}
+
+export const resetPinchGestureValues = ({
+	spec,
+	gestures,
+	animations,
+	shouldDismiss,
+	resetValuesImmediately = false,
+}: ResetPinchGestureValuesProps) => {
+	"worklet";
+	const finishPinchReset = () => {
+		"worklet";
+		if (shouldDismiss) {
+			return;
+		}
+
+		clearFocalPoint(gestures);
+		gestures.initiator.set(null);
+		gestures.settling.set(FALSE);
+		animations?.progressAnimating.set(FALSE);
+		animations?.progressSettled.set(TRUE);
+	};
+
+	if (animations && !shouldDismiss) {
+		animations.progressAnimating.set(TRUE);
+		animations.progressSettled.set(FALSE);
+	}
+
+	clearRawTransformValues(gestures);
+
+	gestures.dragging.set(FALSE);
+	gestures.dismissing.set(shouldDismiss ? TRUE : FALSE);
+	gestures.settling.set(shouldDismiss ? FALSE : TRUE);
+
+	if (shouldDismiss) {
+		clearFocalPoint(gestures);
+	}
+
+	if (resetValuesImmediately) {
+		clearTransformTrackingValues(gestures);
+		finishPinchReset();
+		return;
+	}
+
+	animateMany(
+		[
+			{ value: gestures.scale, toValue: 1 },
+			{ value: gestures.normScale, toValue: 0 },
+			{ value: gestures.rotation, toValue: 0 },
+		],
+		spec,
+		finishPinchReset,
+	);
+};

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

@@ -0,0 +1,90 @@
+import { useCallback, useMemo } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { ScreenOptionsContextValue } from "../../../options";
+import { usePinchGestureSensitivity } from "../../ownership/hooks/use-gesture-sensitivity";
+import { resolvePinchRuntime } from "../../shared/runtime";
+import type {
+	GestureCompositionOwner,
+	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,
+	gestureCompositionOwner: SharedValue<GestureCompositionOwner>,
+	requestDismiss?: () => void,
+): PinchBehavior => {
+	const { withSensitivity, resetSensitivity } =
+		usePinchGestureSensitivity(screenOptions);
+
+	const onStart = useCallback(() => {
+		"worklet";
+		const latestRuntime = resolvePinchRuntime(
+			runtime.get(),
+			screenOptions.get(),
+		);
+		if (latestRuntime.participation.effectiveSnapPoints.hasSnapPoints) {
+			primeSnapPinchRelease(latestRuntime);
+		}
+		startPinchBase(latestRuntime);
+		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, requestDismiss);
+			gestureCompositionOwner.set(null);
+		},
+		[
+			runtime,
+			screenOptions,
+			requestDismiss,
+			withSensitivity,
+			gestureCompositionOwner,
+		],
+	);
+
+	return useMemo(
+		() => ({
+			onStart,
+			onUpdate,
+			onEnd,
+		}),
+		[onStart, onUpdate, onEnd],
+	);
+};

package/src/providers/screen/motion/gestures/pinch/use-build-pinch-gesture.ts

@@ -0,0 +1,65 @@
+import { useMemo } from "react";
+import { Gesture } from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import type { ScreenOptionsContextValue } from "../../options/types";
+import type { MotionValues } from "../../types";
+import { useStableRuntimeConfig } from "../ownership/hooks/use-stable-runtime-config";
+import type {
+	GestureCompositionOwner,
+	PinchGesture,
+	ScreenGestureConfig,
+} from "../types";
+import { usePinchActivation } from "./activation/use-pinch-activation";
+import { usePinchBehavior } from "./behavior/use-pinch-behavior";
+
+interface UseBuildPinchGestureProps {
+	values: MotionValues;
+	onDismissRequest?: () => void;
+	screenOptions: ScreenOptionsContextValue;
+	gestureConfig: ScreenGestureConfig;
+	gestureCompositionOwner: SharedValue<GestureCompositionOwner>;
+}
+
+export const useBuildPinchGesture = ({
+	values,
+	onDismissRequest,
+	screenOptions,
+	gestureConfig,
+	gestureCompositionOwner,
+}: UseBuildPinchGestureProps): PinchGesture => {
+	const { participation, pinch: policy } = gestureConfig;
+
+	const runtime = useStableRuntimeConfig(
+		{
+			participation,
+			policy,
+		},
+		values,
+	);
+
+	const activation = usePinchActivation({
+		runtime,
+		screenOptions,
+		gestureCompositionOwner,
+	});
+
+	const behavior = usePinchBehavior(
+		runtime,
+		screenOptions,
+		gestureCompositionOwner,
+		onDismissRequest,
+	);
+
+	const pinchGesture = useMemo(() => {
+		return Gesture.Pinch()
+			.enabled(true)
+			.manualActivation(true)
+			.onTouchesDown(activation.onTouchesDown)
+			.onTouchesMove(activation.onTouchesMove)
+			.onStart(behavior.onStart)
+			.onUpdate(behavior.onUpdate)
+			.onEnd(behavior.onEnd);
+	}, [activation, behavior]);
+
+	return pinchGesture;
+};

package/src/providers/screen/motion/gestures/scroll-coordination/scroll-metadata-owner.tsx

@@ -0,0 +1,40 @@
+import { type ReactNode, useMemo } from "react";
+import createProvider from "../../../../../utils/create-provider";
+import type { ScrollGestureAxis } from "../types";
+
+type ScrollMetadataOwnerContextValue = Record<ScrollGestureAxis, boolean>;
+
+interface ScrollMetadataOwnerProviderProps {
+	children: ReactNode;
+	value: ScrollMetadataOwnerContextValue;
+}
+
+const DEFAULT_SCROLL_METADATA_OWNER_CONTEXT: ScrollMetadataOwnerContextValue = {
+	vertical: false,
+	horizontal: false,
+};
+
+export const {
+	ScrollMetadataOwnerProvider,
+	useOptionalScrollMetadataOwnerStore,
+} = createProvider("ScrollMetadataOwner")<
+	ScrollMetadataOwnerProviderProps,
+	ScrollMetadataOwnerContextValue
+>(({ children, value }) => ({ children, value }));
+
+export const useScrollMetadataOwnerProviderValue = (
+	axis: ScrollGestureAxis,
+) => {
+	const parent =
+		useOptionalScrollMetadataOwnerStore() ??
+		DEFAULT_SCROLL_METADATA_OWNER_CONTEXT;
+
+	return useMemo(() => {
+		if (parent[axis]) return parent;
+
+		return {
+			...parent,
+			[axis]: true,
+		};
+	}, [axis, parent]);
+};

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

@@ -0,0 +1,306 @@
+import { useLayoutEffect, useMemo, useState } 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 { ScrollStore } from "../../../../../stores/scroll.store";
+import { useMotionStore, useOptionalMotionStore } from "../..";
+import { useGestureScrollCoordination } from "../ownership/use-gesture-scroll-coordination";
+import type {
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	ScrollMetadataState,
+} from "../types";
+import {
+	useOptionalScrollMetadataOwnerStore,
+	useScrollMetadataOwnerProviderValue,
+} from "./scroll-metadata-owner";
+import {
+	clearScrollMetadataAxisState,
+	updateScrollGestureAxisState,
+	updateScrollMetadataAxisState,
+} from "./update-scroll-gesture-state";
+
+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;
+	});
+};
+
+const modifyScrollMetadataAxisState = (
+	scrollState: SharedValue<ScrollMetadataState | null>,
+	axis: ScrollGestureAxis,
+	patch: ScrollGesturePatch,
+) => {
+	"worklet";
+
+	scrollState.modify(<T extends ScrollMetadataState | null>(state: T): T => {
+		"worklet";
+		return updateScrollMetadataAxisState(state, axis, patch) as T;
+	});
+};
+
+const clearScrollMetadataAxis = (
+	scrollState: SharedValue<ScrollMetadataState | null>,
+	axis: ScrollGestureAxis,
+) => {
+	"worklet";
+
+	scrollState.modify(<T extends ScrollMetadataState | null>(state: T): T => {
+		"worklet";
+		return clearScrollMetadataAxisState(state, axis) 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 = useOptionalMotionStore((store) => store?.gestures ?? null);
+	const scrollDirection = props.direction ?? "vertical";
+	const routeKey = context?.routeKey ?? null;
+	const { scrollStates, panGestures, pinchGestures, ownerRouteKeys } =
+		useGestureScrollCoordination(routeKey, scrollDirection);
+
+	const metadataOwnerContext = useOptionalScrollMetadataOwnerStore();
+	const metadataOwnerProviderValue =
+		useScrollMetadataOwnerProviderValue(scrollDirection);
+	const isFirstMetadataWriterInTree = !metadataOwnerContext?.[scrollDirection];
+	const [metadataWriterId] = useState(() =>
+		ScrollStore.createMetadataWriterId(),
+	);
+	const [writesMetadata, setWritesMetadata] = useState(false);
+
+	const metadataState = useMemo(
+		() => (routeKey ? ScrollStore.getValue(routeKey, "metadata") : null),
+		[routeKey],
+	);
+
+	useLayoutEffect(() => {
+		if (!routeKey || !isFirstMetadataWriterInTree) {
+			setWritesMetadata(false);
+			return;
+		}
+
+		const claimed = ScrollStore.claimMetadataWriter(
+			routeKey,
+			scrollDirection,
+			metadataWriterId,
+		);
+		setWritesMetadata(claimed);
+
+		return () => {
+			const released = ScrollStore.releaseMetadataWriter(
+				routeKey,
+				scrollDirection,
+				metadataWriterId,
+			);
+
+			if (!released || !metadataState) return;
+
+			if (!ScrollStore.hasMetadataWriters(routeKey)) {
+				metadataState.set(null);
+				return;
+			}
+
+			clearScrollMetadataAxis(metadataState, scrollDirection);
+		};
+	}, [
+		routeKey,
+		scrollDirection,
+		isFirstMetadataWriterInTree,
+		metadataState,
+		metadataWriterId,
+	]);
+
+	const ownerMotions = useMotionStore(ownerRouteKeys);
+	const ownerClosingValues = useMemo(
+		() =>
+			ownerMotions.flatMap((motion) => (motion ? [motion.state.closing] : [])),
+		[ownerMotions],
+	);
+
+	const scrollEventsEnabled = useSharedValueState(
+		useDerivedValue(() => {
+			"worklet";
+			for (let i = 0; i < ownerClosingValues.length; i++) {
+				if (ownerClosingValues[i].get()) {
+					return false;
+				}
+			}
+
+			return true;
+		}),
+	);
+
+	const nativeGesture = useMemo(() => {
+		// Ownership registrations disappear while a screen's Activity is paused.
+		// Keep its detector mounted through that gap: removing the wrapper remounts
+		// scroll children and loses state, including captured boundary measurements.
+		if (!routeKey) return null;
+
+		const setIsTouched = () => {
+			"worklet";
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					isTouched: true,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					isTouched: true,
+				});
+			}
+		};
+
+		const clearIsTouched = () => {
+			"worklet";
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					isTouched: false,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, 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) {
+			// A pinch must remain possible after the first finger lands. Making
+			// native scrolling wait for it to fail therefore stalls ordinary
+			// one-finger scrolling until touch-up. Let both recognizers run:
+			// the ScrollView can begin immediately, while a second finger can
+			// still promote the screen gesture to a pinch.
+			gesture = gesture.simultaneousWithExternalGesture({
+				current: pinchGesture as unknown as GestureType,
+			});
+		}
+
+		return gesture;
+	}, [
+		routeKey,
+		panGestures,
+		pinchGestures,
+		scrollStates,
+		scrollDirection,
+		writesMetadata,
+		metadataState,
+	]);
+
+	const scrollHandler = useAnimatedScrollHandler({
+		onScroll: (event) => {
+			const offset =
+				scrollDirection === "horizontal"
+					? event.contentOffset.x
+					: event.contentOffset.y;
+
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					offset,
+					isTouched: scrollState.get()?.[scrollDirection].isTouched ?? true,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					offset,
+					isTouched: metadataState.get()?.[scrollDirection]?.isTouched ?? true,
+				});
+			}
+		},
+	});
+
+	const onContentSizeChange = useStableCallback(
+		(width: number, height: number) => {
+			props.onContentSizeChange?.(width, height);
+
+			const contentSize = scrollDirection === "horizontal" ? width : height;
+
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					contentSize,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					contentSize,
+				});
+			}
+		},
+	);
+
+	const onLayout = useStableCallback((event: LayoutChangeEvent) => {
+		props.onLayout?.(event);
+
+		const { width, height } = event.nativeEvent.layout;
+		const layoutSize = scrollDirection === "horizontal" ? width : height;
+
+		for (const scrollState of scrollStates) {
+			modifyScrollGestureAxisState(scrollState, scrollDirection, {
+				layoutSize,
+			});
+		}
+
+		if (writesMetadata && metadataState) {
+			modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+				layoutSize,
+			});
+		}
+	});
+
+	return {
+		scrollHandler,
+		scrollEventsEnabled,
+		onContentSizeChange,
+		onLayout,
+		nativeGesture,
+		metadataOwnerProviderValue,
+	};
+};