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

package/src/shared/providers/screen/gestures/hooks/use-gesture-builder-state.ts

@@ -0,0 +1,35 @@
+import { useMemo } from "react";
+import { useSharedValue } from "react-native-reanimated";
+import type { ScreenGestureParticipation } from "../types";
+
+/**
+ * Creates the shared values that both pan and pinch runtimes need while a
+ * recognizer is active.
+ *
+ * `gestureProgressBaseline` is set to the current animation progress when a
+ * gesture starts. Strategies use it as the stable baseline for cumulative
+ * pan/pinch deltas so progress can be recalculated from the gesture event
+ * instead of repeatedly accumulating into the current animated value.
+ *
+ * `lockedSnapPoint` is the current snap point chosen when a snap gesture starts.
+ * Snap strategies set it during `primeStart`: snap-locked gestures use the
+ * nearest resolved snap point, while unlocked snap gestures use the resolved max
+ * snap point. The value stays stable through the active gesture and is used as a
+ * progress bound/release target.
+ */
+export const useGestureBuilderState = (
+	participation: ScreenGestureParticipation,
+) => {
+	const gestureProgressBaseline = useSharedValue(1);
+	const lockedSnapPoint = useSharedValue(
+		participation.effectiveSnapPoints.maxSnapPoint,
+	);
+
+	return useMemo(
+		() => ({
+			gestureProgressBaseline,
+			lockedSnapPoint,
+		}),
+		[gestureProgressBaseline, lockedSnapPoint],
+	);
+};

package/src/shared/providers/screen/gestures/hooks/use-gesture-sensitivity.ts

@@ -0,0 +1,132 @@
+import { useCallback, useMemo } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import { useSharedValue } from "react-native-reanimated";
+import type { ScreenOptionsContextValue } from "../../options";
+import {
+	applyGestureSensitivity,
+	normalizePinchScale,
+} from "../helpers/gesture-physics";
+import type { PanGestureEvent, PinchGestureEvent } from "../types";
+
+export interface GestureSensitivityRawChangeState {
+	previousRawValue: SharedValue<number>;
+	adjustedValue: SharedValue<number>;
+}
+
+export const applyGestureSensitivityToRawChange = (
+	rawValue: number,
+	sensitivity: number,
+	state: GestureSensitivityRawChangeState,
+) => {
+	"worklet";
+	const rawChange = rawValue - state.previousRawValue.get();
+
+	// gestureSensitivity can change mid-gesture, so apply it to the latest
+	// raw movement only instead of rescaling the recognizer's cumulative value.
+	const adjustedValue =
+		state.adjustedValue.get() + applyGestureSensitivity(rawChange, sensitivity);
+
+	state.previousRawValue.set(rawValue);
+	state.adjustedValue.set(adjustedValue);
+
+	return adjustedValue;
+};
+
+const resetChangeState = (state: GestureSensitivityRawChangeState) => {
+	"worklet";
+	state.previousRawValue.set(0);
+	state.adjustedValue.set(0);
+};
+
+const useBuildSensitivityChangeState = () => {
+	const previousRawValue = useSharedValue(0);
+	const adjustedValue = useSharedValue(0);
+
+	return useMemo<GestureSensitivityRawChangeState>(
+		() => ({
+			previousRawValue,
+			adjustedValue,
+		}),
+		[previousRawValue, adjustedValue],
+	);
+};
+
+export const usePanGestureSensitivity = (
+	screenOptions: ScreenOptionsContextValue,
+) => {
+	const xSensitivityState = useBuildSensitivityChangeState();
+	const ySensitivityState = useBuildSensitivityChangeState();
+
+	const resetSensitivity = useCallback(() => {
+		"worklet";
+		resetChangeState(xSensitivityState);
+		resetChangeState(ySensitivityState);
+	}, [xSensitivityState, ySensitivityState]);
+
+	const withSensitivity = useCallback(
+		(event: PanGestureEvent): PanGestureEvent => {
+			"worklet";
+			const sensitivity = screenOptions.get().gestureSensitivity;
+
+			return {
+				...event,
+				translationX: applyGestureSensitivityToRawChange(
+					event.translationX,
+					sensitivity,
+					xSensitivityState,
+				),
+				translationY: applyGestureSensitivityToRawChange(
+					event.translationY,
+					sensitivity,
+					ySensitivityState,
+				),
+			};
+		},
+		[screenOptions, xSensitivityState, ySensitivityState],
+	);
+
+	return useMemo(
+		() => ({
+			withSensitivity,
+			resetSensitivity,
+		}),
+		[withSensitivity, resetSensitivity],
+	);
+};
+
+export const usePinchGestureSensitivity = (
+	screenOptions: ScreenOptionsContextValue,
+) => {
+	const scaleSensitivityState = useBuildSensitivityChangeState();
+
+	const resetSensitivity = useCallback(() => {
+		"worklet";
+		resetChangeState(scaleSensitivityState);
+	}, [scaleSensitivityState]);
+
+	const withSensitivity = useCallback(
+		(event: PinchGestureEvent): PinchGestureEvent => {
+			"worklet";
+			const sensitivity = screenOptions.get().gestureSensitivity;
+			const normScale = applyGestureSensitivityToRawChange(
+				normalizePinchScale(event.scale),
+				sensitivity,
+				scaleSensitivityState,
+			);
+
+			return {
+				...event,
+				scale: 1 + normScale,
+			};
+		},
+		[screenOptions, scaleSensitivityState],
+	);
+
+	return useMemo(
+		() => ({
+			withSensitivity,
+			resetSensitivity,
+		}),
+		[withSensitivity, resetSensitivity],
+	);
+};

package/src/shared/providers/screen/gestures/hooks/use-screen-gesture-config.ts

@@ -0,0 +1,160 @@
+import { useMemo } from "react";
+import {
+	DEFAULT_GESTURE_ACTIVATION_AREA,
+	DEFAULT_GESTURE_DIRECTION,
+	DEFAULT_GESTURE_DRIVES_PROGRESS,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+	DEFAULT_GESTURE_SENSITIVITY,
+	DEFAULT_GESTURE_SNAP_LOCKED,
+	DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	DEFAULT_GESTURE_VELOCITY_IMPACT,
+} from "../../../../constants";
+import type { ScreenTransitionConfig } from "../../../../types";
+import { resolveSheetScrollGestureBehavior } from "../../../../utils/resolve-screen-transition-options";
+import { useDescriptorDerivations, useDescriptors } from "../../descriptors";
+import { useGestureContext } from "../gestures.provider";
+import {
+	getPanActivationDirections,
+	getPanGestureDirections,
+	getPanSnapAxisDirections,
+	getPinchGestureDirections,
+	getSnapPinchDirectionConfig,
+} from "../helpers/gesture-directions";
+import { resolveCanTrackGesture } from "../helpers/resolve-can-track-gesture";
+import { validateSnapPoints } from "../helpers/validate-snap-points";
+import { computeClaimedDirections } from "../ownership/compute-claimed-directions";
+import { resolveOwnership } from "../ownership/resolve-ownership";
+import type {
+	PanGesturePolicy,
+	PinchGesturePolicy,
+	ScreenGestureConfig,
+	ScreenGestureParticipation,
+} from "../types";
+
+function resolvePanPolicy(
+	options: ScreenTransitionConfig,
+	hasSnapPoints: boolean,
+): PanGesturePolicy {
+	const gestureDirection =
+		options.gestureDirection ?? DEFAULT_GESTURE_DIRECTION;
+	const hasPanDirection = getPanGestureDirections(gestureDirection).length > 0;
+
+	return {
+		enabled: hasPanDirection,
+		gestureDirection,
+		panActivationDirections: getPanActivationDirections({
+			gestureDirection,
+			hasSnapPoints,
+		}),
+		snapAxisDirections: getPanSnapAxisDirections(gestureDirection),
+		gestureDrivesProgress:
+			options.gestureDrivesProgress ?? DEFAULT_GESTURE_DRIVES_PROGRESS,
+		gestureSensitivity:
+			options.gestureSensitivity ?? DEFAULT_GESTURE_SENSITIVITY,
+		gestureVelocityImpact:
+			options.gestureVelocityImpact ?? DEFAULT_GESTURE_VELOCITY_IMPACT,
+		gestureSnapVelocityImpact:
+			options.gestureSnapVelocityImpact ?? DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+		gestureReleaseVelocityScale:
+			options.gestureReleaseVelocityScale ??
+			DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+		gestureReleaseVelocityMax:
+			options.gestureReleaseVelocityMax ?? DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+		gestureActivationArea:
+			options.gestureActivationArea ?? DEFAULT_GESTURE_ACTIVATION_AREA,
+		gestureSnapLocked: options.gestureSnapLocked ?? DEFAULT_GESTURE_SNAP_LOCKED,
+		sheetScrollGestureBehavior: resolveSheetScrollGestureBehavior(options),
+		gestureResponseDistance: options.gestureResponseDistance,
+		transitionSpec: options.transitionSpec,
+	};
+}
+
+function resolvePinchPolicy(
+	options: ScreenTransitionConfig,
+	hasSnapPoints: boolean,
+): PinchGesturePolicy {
+	const gestureDirection =
+		options.gestureDirection ?? DEFAULT_GESTURE_DIRECTION;
+	const pinchDirections = getPinchGestureDirections(gestureDirection);
+	const snapDirections = hasSnapPoints
+		? getSnapPinchDirectionConfig(gestureDirection)
+		: null;
+	const pinchInEnabled = snapDirections
+		? true
+		: pinchDirections.includes("pinch-in");
+	const pinchOutEnabled = snapDirections
+		? true
+		: pinchDirections.includes("pinch-out");
+
+	return {
+		enabled: pinchInEnabled || pinchOutEnabled,
+		gestureDirection,
+		snapDirections,
+		pinchInEnabled,
+		pinchOutEnabled,
+		gestureDrivesProgress:
+			options.gestureDrivesProgress ?? DEFAULT_GESTURE_DRIVES_PROGRESS,
+		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,
+		gestureReleaseVelocityMax:
+			options.gestureReleaseVelocityMax ?? DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+		transitionSpec: options.transitionSpec,
+	};
+}
+
+export function useScreenGestureConfig(): ScreenGestureConfig {
+	const gestureContext = useGestureContext();
+	const {
+		current: { options },
+	} = useDescriptors();
+
+	const { isFirstKey } = useDescriptorDerivations();
+
+	return useMemo(() => {
+		const canDismiss = Boolean(isFirstKey ? false : options.gestureEnabled);
+		// NOTE: The first screen still does not track gestures by default. Even if
+		// gesture-driven animations are broadly available, initial-route gesture
+		// animation should stay behind experimental_animateOnInitialMount until we
+		// have feedback on whether that behavior is useful.
+		const effectiveSnapPoints = validateSnapPoints({
+			snapPoints: options.snapPoints,
+			canDismiss,
+		});
+		const canTrackGesture = resolveCanTrackGesture({
+			isFirstKey,
+			canDismiss,
+			hasSnapPoints: effectiveSnapPoints.hasSnapPoints,
+			allowDisabledGestureTracking:
+				options.experimental_allowDisabledGestureTracking,
+		});
+		const canClaimDirections = canTrackGesture;
+
+		const claimedDirections = computeClaimedDirections(
+			canClaimDirections,
+			options.gestureDirection,
+			effectiveSnapPoints.hasSnapPoints,
+		);
+
+		const participation: ScreenGestureParticipation = {
+			isFirstKey,
+			canDismiss,
+			canTrackGesture,
+			effectiveSnapPoints,
+			claimedDirections,
+			ownershipStatus: resolveOwnership(claimedDirections, gestureContext),
+		};
+
+		return {
+			participation,
+			pan: resolvePanPolicy(options, effectiveSnapPoints.hasSnapPoints),
+			pinch: resolvePinchPolicy(options, effectiveSnapPoints.hasSnapPoints),
+		};
+	}, [isFirstKey, options, gestureContext]);
+}

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

@@ -0,0 +1,37 @@
+import {
+	type ChainTarget,
+	resolveChainTarget,
+} from "../../../../utils/resolve-chain-target";
+import { useGestureContext } from "../gestures.provider";
+import { walkGestureAncestors } from "../helpers/walk-gesture-ancestors";
+
+export type ScreenGestureTarget = ChainTarget;
+
+/**
+ * Returns a screen navigation pan gesture.
+ * Use this to coordinate child gestures with the navigation gesture.
+ *
+ * @example
+ * ```tsx
+ * const screenGesture = useScreenGesture();
+ *
+ * const myPanGesture = Gesture.Pan()
+ *   .requireExternalGestureToFail(screenGesture)
+ *   .onUpdate((...) => {});
+ * ```
+ */
+export const useScreenGesture = (target?: ScreenGestureTarget) => {
+	const ctx = useGestureContext();
+
+	if (!target || target === "self") {
+		return ctx?.panGesture ?? null;
+	}
+
+	return (
+		resolveChainTarget({
+			target,
+			self: ctx,
+			ancestors: walkGestureAncestors(ctx?.gestureContext),
+		})?.panGesture ?? null
+	);
+};

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

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

package/src/shared/providers/screen/gestures/hooks/use-scroll-gesture-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/hooks/use-scroll-gesture-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,
+	};
+};

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

@@ -0,0 +1,72 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { Direction } from "../../../../../types/ownership.types";
+import { walkGestureAncestors } from "../../helpers/walk-gesture-ancestors";
+import type {
+	GestureContextType,
+	PanGesture,
+	PinchGesture,
+	ScrollGestureAxis,
+	ScrollGestureState,
+} from "../../types";
+
+/** Walks up the gesture tree until it finds the owner for a specific direction. */
+function findGestureOwnerForDirection(
+	ancestors: GestureContextType[],
+	direction: Direction,
+): GestureContextType | null {
+	for (const ancestor of ancestors) {
+		if (ancestor.claimedDirections?.[direction]) return ancestor;
+	}
+
+	return null;
+}
+
+interface WalkUpScrollGestureCoordinationResult {
+	panGestures: PanGesture[];
+	pinchGestures: PinchGesture[];
+	scrollStates: SharedValue<ScrollGestureState | null>[];
+	ownerRouteKeys: string[];
+}
+
+export function walkUpScrollGestureCoordination(
+	context: GestureContextType | null,
+	axis: ScrollGestureAxis,
+): WalkUpScrollGestureCoordinationResult {
+	const directions: readonly [Direction, Direction] =
+		axis === "vertical"
+			? ["vertical", "vertical-inverted"]
+			: ["horizontal", "horizontal-inverted"];
+
+	const seenOwners: GestureContextType[] = [];
+	const panGestures: GestureContextType["panGesture"][] = [];
+	const pinchGestures: GestureContextType["pinchGesture"][] = [];
+	const scrollStates: GestureContextType["scrollState"][] = [];
+	const ownerRouteKeys: string[] = [];
+	const ancestors = walkGestureAncestors(context);
+
+	for (const ancestor of ancestors) {
+		if (!pinchGestures.includes(ancestor.pinchGesture)) {
+			pinchGestures.push(ancestor.pinchGesture);
+		}
+	}
+
+	for (const direction of directions) {
+		const owner = findGestureOwnerForDirection(ancestors, direction);
+
+		if (!owner || seenOwners.includes(owner)) {
+			continue;
+		}
+
+		seenOwners.push(owner);
+		panGestures.push(owner.panGesture);
+		scrollStates.push(owner.scrollState);
+		ownerRouteKeys.push(owner.routeKey);
+	}
+
+	return {
+		panGestures,
+		pinchGestures,
+		scrollStates,
+		ownerRouteKeys,
+	};
+}