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

package/src/shared/providers/screen/gestures/helpers/pinch-phases.ts

@@ -0,0 +1,98 @@
+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 type {
+	PinchGestureEvent,
+	PinchGestureRuntime,
+	PinchReleaseResult,
+	PinchTrackState,
+} from "../types";
+import { normalizePinchScale } from "./gesture-physics";
+import { resetPinchGestureValues } from "./gesture-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;
+
+	resetPinchGestureValues({
+		spec: release.resetSpec,
+		gestures,
+		shouldDismiss: release.shouldDismiss,
+	});
+
+	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/helpers/resolve-can-track-gesture.ts

@@ -0,0 +1,23 @@
+export type GestureTrackingParticipationInput = {
+	isFirstKey: boolean;
+	canDismiss: boolean;
+	hasSnapPoints: boolean;
+	allowDisabledGestureTracking?: boolean;
+};
+
+export function resolveCanTrackGesture({
+	isFirstKey,
+	canDismiss,
+	hasSnapPoints,
+	allowDisabledGestureTracking,
+}: GestureTrackingParticipationInput) {
+	if (isFirstKey) {
+		return false;
+	}
+
+	if (allowDisabledGestureTracking) {
+		return true;
+	}
+
+	return canDismiss || hasSnapPoints;
+}

package/src/shared/providers/screen/gestures/helpers/runtime-options.ts

@@ -0,0 +1,159 @@
+import type { ScreenOptionsSnapshot } from "../../options";
+import type {
+	PanGesturePolicy,
+	PanGestureRuntime,
+	PinchGesturePolicy,
+	PinchGestureRuntime,
+} from "../types";
+import {
+	getPanActivationDirections,
+	getPanGestureDirections,
+	getPanSnapAxisDirections,
+	getPinchGestureDirections,
+	getSnapPinchDirectionConfig,
+} from "./gesture-directions";
+
+export const resolveRuntimeCanTrackGesture = (
+	runtime: PanGestureRuntime | PinchGestureRuntime,
+	screenOptions: ScreenOptionsSnapshot,
+) => {
+	"worklet";
+	const { participation } = runtime;
+
+	if (participation.isFirstKey) {
+		return false;
+	}
+
+	if (screenOptions.experimental_allowDisabledGestureTracking === true) {
+		return true;
+	}
+
+	const gestureEnabled = screenOptions.gestureEnabled;
+	if (gestureEnabled === true) {
+		return true;
+	}
+
+	if (gestureEnabled === false) {
+		return participation.effectiveSnapPoints.hasSnapPoints;
+	}
+
+	return participation.canTrackGesture;
+};
+
+export const resolveRuntimeCanDismiss = (
+	runtime: PanGestureRuntime | PinchGestureRuntime,
+	screenOptions: ScreenOptionsSnapshot,
+) => {
+	"worklet";
+	const { participation } = runtime;
+
+	if (participation.isFirstKey) {
+		return false;
+	}
+
+	const gestureEnabled = screenOptions.gestureEnabled;
+	if (gestureEnabled === false) {
+		return false;
+	}
+
+	if (gestureEnabled === true) {
+		return true;
+	}
+
+	return participation.canDismiss;
+};
+
+export const resolvePanRuntimePolicy = (
+	runtime: PanGestureRuntime,
+	screenOptions: ScreenOptionsSnapshot,
+): PanGesturePolicy => {
+	"worklet";
+	const { policy, participation } = runtime;
+	const gestureDirection = screenOptions.gestureDirection;
+	const hasSnapPoints = participation.effectiveSnapPoints.hasSnapPoints;
+
+	return {
+		...policy,
+		enabled: getPanGestureDirections(gestureDirection).length > 0,
+		gestureDirection,
+		panActivationDirections: getPanActivationDirections({
+			gestureDirection,
+			hasSnapPoints,
+		}),
+		snapAxisDirections: getPanSnapAxisDirections(gestureDirection),
+		gestureDrivesProgress: screenOptions.gestureDrivesProgress,
+		gestureSensitivity: screenOptions.gestureSensitivity,
+		gestureVelocityImpact: screenOptions.gestureVelocityImpact,
+		gestureSnapVelocityImpact: screenOptions.gestureSnapVelocityImpact,
+		gestureReleaseVelocityScale: screenOptions.gestureReleaseVelocityScale,
+		gestureResponseDistance: screenOptions.gestureResponseDistance,
+		gestureActivationArea: screenOptions.gestureActivationArea,
+		gestureSnapLocked: screenOptions.gestureSnapLocked,
+		sheetScrollGestureBehavior: screenOptions.sheetScrollGestureBehavior,
+	};
+};
+
+export const resolvePinchRuntimePolicy = (
+	runtime: PinchGestureRuntime,
+	screenOptions: ScreenOptionsSnapshot,
+): PinchGesturePolicy => {
+	"worklet";
+	const { policy, participation } = runtime;
+	const gestureDirection = screenOptions.gestureDirection;
+	const pinchDirections = getPinchGestureDirections(gestureDirection);
+	const snapDirections = participation.effectiveSnapPoints.hasSnapPoints
+		? getSnapPinchDirectionConfig(gestureDirection)
+		: null;
+	const pinchInEnabled = snapDirections
+		? true
+		: pinchDirections.includes("pinch-in");
+	const pinchOutEnabled = snapDirections
+		? true
+		: pinchDirections.includes("pinch-out");
+
+	return {
+		...policy,
+		enabled: pinchInEnabled || pinchOutEnabled,
+		gestureDirection,
+		snapDirections,
+		pinchInEnabled,
+		pinchOutEnabled,
+		gestureDrivesProgress: screenOptions.gestureDrivesProgress,
+		gestureSensitivity: screenOptions.gestureSensitivity,
+		gestureSnapVelocityImpact: screenOptions.gestureSnapVelocityImpact,
+		gestureReleaseVelocityScale: screenOptions.gestureReleaseVelocityScale,
+		gestureSnapLocked: screenOptions.gestureSnapLocked,
+	};
+};
+
+export const resolvePanRuntime = (
+	runtime: PanGestureRuntime,
+	screenOptions: ScreenOptionsSnapshot,
+): PanGestureRuntime => {
+	"worklet";
+	return {
+		...runtime,
+		participation: {
+			...runtime.participation,
+			canDismiss: resolveRuntimeCanDismiss(runtime, screenOptions),
+			canTrackGesture: resolveRuntimeCanTrackGesture(runtime, screenOptions),
+		},
+		policy: resolvePanRuntimePolicy(runtime, screenOptions),
+	};
+};
+
+export const resolvePinchRuntime = (
+	runtime: PinchGestureRuntime,
+	screenOptions: ScreenOptionsSnapshot,
+): PinchGestureRuntime => {
+	"worklet";
+	return {
+		...runtime,
+		participation: {
+			...runtime.participation,
+			canDismiss: resolveRuntimeCanDismiss(runtime, screenOptions),
+			canTrackGesture: resolveRuntimeCanTrackGesture(runtime, screenOptions),
+		},
+		policy: resolvePinchRuntimePolicy(runtime, screenOptions),
+	};
+};

package/src/shared/{utils/gesture → providers/screen/gestures/helpers}/validate-snap-points.ts

@@ -1,4 +1,4 @@
-import type { SnapPoint } from "../../types/screen.types";
+import type { SnapPoint } from "../../../../types/screen.types";
 
 /**
  * Filters snap points to only valid, finite numeric values.

package/src/shared/providers/screen/gestures/helpers/walk-gesture-ancestors.ts

@@ -0,0 +1,27 @@
+type GestureAncestorNode<T> = {
+	gestureContext: T | null;
+	isIsolated?: boolean;
+};
+
+/**
+ * Returns the gesture context chain, starting at `context`, then walking upward.
+ * When `isIsolated` is provided, the walk stops at a stack isolation boundary.
+ */
+export function walkGestureAncestors<T extends GestureAncestorNode<T>>(
+	context: T | null | undefined,
+	isIsolated?: boolean,
+): T[] {
+	const ancestors: T[] = [];
+	let ancestor = context ?? null;
+
+	while (ancestor) {
+		if (isIsolated !== undefined && ancestor.isIsolated !== isIsolated) {
+			break;
+		}
+
+		ancestors.push(ancestor);
+		ancestor = ancestor.gestureContext;
+	}
+
+	return ancestors;
+}

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";