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

package/src/shared/providers/screen/descriptors/helpers/derive-descriptor-derivations.ts

@@ -8,11 +8,7 @@ export interface DescriptorDerivations {
 	isFirstKey: boolean;
 	isTopMostScreen: boolean;
 	ancestorKeys: string[];
-	navigatorKey: string;
-	ancestorNavigatorKeys: string[];
 	hasConfiguredInterpolator: boolean;
-	isBranchScreen: boolean;
-	branchNavigatorKey?: string;
 }
 
 interface Params {
@@ -20,7 +16,6 @@ interface Params {
 	current: BaseStackDescriptor;
 	next?: BaseStackDescriptor;
 	ancestorKeys: string[];
-	ancestorNavigatorKeys: string[];
 }
 
 export function deriveDescriptorDerivations({
@@ -28,14 +23,12 @@ export function deriveDescriptorDerivations({
 	current,
 	next,
 	ancestorKeys,
-	ancestorNavigatorKeys,
 }: Params): DescriptorDerivations {
 	const previousScreenKey = previous?.route.key;
 	const currentScreenKey = current.route.key;
 	const nextScreenKey = next?.route.key;
 
 	const navigationState = current.navigation.getState();
-	const navigatorKey = navigationState?.key ?? "";
 	const routes = navigationState?.routes ?? [];
 	const isFirstKey =
 		routes.findIndex((route) => route.key === current.route.key) === 0;
@@ -44,14 +37,6 @@ export function deriveDescriptorDerivations({
 		!!current.options.screenStyleInterpolator ||
 		!!next?.options?.screenStyleInterpolator;
 
-	const currentRoute = routes.find((route) => route.key === current.route.key);
-	const hasBranchState = !!currentRoute && "state" in currentRoute;
-	const nestedState = hasBranchState
-		? (currentRoute as { state?: { key?: unknown } }).state
-		: undefined;
-	const branchNavigatorKey =
-		typeof nestedState?.key === "string" ? nestedState.key : undefined;
-
 	return {
 		previousScreenKey,
 		currentScreenKey,
@@ -60,10 +45,6 @@ export function deriveDescriptorDerivations({
 		isFirstKey,
 		isTopMostScreen,
 		ancestorKeys,
-		navigatorKey,
-		ancestorNavigatorKeys,
 		hasConfiguredInterpolator,
-		isBranchScreen: hasBranchState,
-		branchNavigatorKey,
 	};
 }

package/src/shared/providers/screen/gestures/gestures.provider.tsx

@@ -0,0 +1,85 @@
+import { useMemo } from "react";
+import { Gesture } from "react-native-gesture-handler";
+import { useSharedValue } from "react-native-reanimated";
+import { ScrollStore } from "../../../stores/scroll.store";
+import createProvider from "../../../utils/create-provider";
+import { useDescriptorDerivations } from "../descriptors";
+import { useScreenGestureConfig } from "./hooks/use-screen-gesture-config";
+import { useWalkUpAndRegisterShadowingClaims } from "./ownership/use-walk-up-and-register-shadowing-claims";
+import { useBuildPanGesture } from "./pan/build-pan-gesture";
+import { useBuildPinchGesture } from "./pinch/build-pinch-gesture";
+import {
+	type DirectionClaimMap,
+	type GestureContextType,
+	NO_DIRECTION_CLAIMS,
+} from "./types";
+
+interface ScreenGestureProviderProps {
+	children: React.ReactNode;
+}
+
+export const {
+	ScreenGestureProvider,
+	useScreenGestureContext: useGestureContext,
+} = createProvider("ScreenGesture", { guarded: false })<
+	ScreenGestureProviderProps,
+	GestureContextType
+>(({ children }): { value: GestureContextType; children: React.ReactNode } => {
+	const gestureContext = useGestureContext();
+	const gestureConfig = useScreenGestureConfig();
+	const { currentScreenKey } = useDescriptorDerivations();
+
+	const scrollState = ScrollStore.getValue(currentScreenKey, "state");
+
+	// Ancestors read this before activating. If a nested screen claims the same
+	// direction, it writes here so the ancestor can fail and let it take priority.
+	const childDirectionClaims =
+		useSharedValue<DirectionClaimMap>(NO_DIRECTION_CLAIMS);
+
+	const panGesture = useBuildPanGesture({
+		scrollState,
+		gestureConfig,
+		childDirectionClaims,
+	});
+
+	const pinchGesture = useBuildPinchGesture({
+		gestureConfig,
+	});
+
+	const detectorGesture = useMemo(
+		() => Gesture.Race(panGesture, pinchGesture),
+		[panGesture, pinchGesture],
+	);
+
+	const value = useMemo<GestureContextType>(
+		() => ({
+			routeKey: currentScreenKey,
+			detectorGesture,
+			panGesture,
+			pinchGesture,
+			scrollState,
+			gestureContext,
+			claimedDirections: gestureConfig.participation.claimedDirections,
+			childDirectionClaims,
+		}),
+		[
+			currentScreenKey,
+			detectorGesture,
+			panGesture,
+			pinchGesture,
+			scrollState,
+			gestureContext,
+			gestureConfig.participation.claimedDirections,
+			childDirectionClaims,
+		],
+	);
+
+	useWalkUpAndRegisterShadowingClaims(
+		gestureConfig.participation.claimedDirections,
+	);
+
+	return {
+		value,
+		children,
+	};
+});

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

@@ -0,0 +1,31 @@
+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. Lifecycle handlers 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 release primers set it on start: 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 {
+		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 "../shared/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,24 @@
+import { useMemo } from "react";
+import { useDescriptorDerivations, useDescriptors } from "../../descriptors";
+import { useGestureContext } from "../gestures.provider";
+import { resolveScreenGestureConfig } from "../shared/policy";
+import type { ScreenGestureConfig } from "../types";
+
+export function useScreenGestureConfig(): ScreenGestureConfig {
+	const gestureContext = useGestureContext();
+	const {
+		current: { options },
+	} = useDescriptors();
+
+	const { isFirstKey } = useDescriptorDerivations();
+
+	return useMemo(
+		() =>
+			resolveScreenGestureConfig({
+				options,
+				isFirstKey,
+				gestureContext,
+			}),
+		[isFirstKey, options, gestureContext],
+	);
+}

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

@@ -0,0 +1,33 @@
+import {
+	type ChainTarget,
+	resolveChainTarget,
+} from "../../../../utils/resolve-chain-target";
+import { useGestureContext } from "../gestures.provider";
+import { walkGestureAncestors } from "../shared/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();
+
+	return (
+		resolveChainTarget({
+			target,
+			self: ctx,
+			ancestors: walkGestureAncestors(ctx?.gestureContext),
+		})?.panGesture ?? null
+	);
+};

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

@@ -0,0 +1,45 @@
+import { useLayoutEffect, useMemo } from "react";
+import { type SharedValue, useSharedValue } from "react-native-reanimated";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { GestureStore } from "../../../../stores/gesture.store";
+import { SystemStore } from "../../../../stores/system.store";
+import { useDescriptorDerivations } from "../../descriptors";
+import type { GesturePolicy, GestureRuntime } from "../types";
+
+type RuntimeConfigInput<TPolicy extends GesturePolicy> = Omit<
+	GestureRuntime<TPolicy>,
+	"stores"
+>;
+
+export function useStableRuntimeConfig<TPolicy extends GesturePolicy>(
+	runtimeConfigInput: RuntimeConfigInput<TPolicy>,
+): SharedValue<GestureRuntime<TPolicy>> {
+	const { currentScreenKey } = useDescriptorDerivations();
+	const { participation, policy, gestureProgressBaseline, lockedSnapPoint } =
+		runtimeConfigInput;
+
+	const stores = useMemo(() => {
+		return {
+			gestures: GestureStore.getBag(currentScreenKey),
+			animations: AnimationStore.getBag(currentScreenKey),
+			system: SystemStore.getBag(currentScreenKey),
+		};
+	}, [currentScreenKey]);
+
+	const runtimeConfig = useMemo<GestureRuntime<TPolicy>>(() => {
+		return {
+			participation,
+			policy,
+			stores,
+			gestureProgressBaseline,
+			lockedSnapPoint,
+		};
+	}, [participation, policy, stores, gestureProgressBaseline, lockedSnapPoint]);
+	const stableRuntimeConfig = useSharedValue(runtimeConfig);
+
+	useLayoutEffect(() => {
+		stableRuntimeConfig.set(runtimeConfig);
+	}, [stableRuntimeConfig, runtimeConfig]);
+
+	return stableRuntimeConfig;
+}

package/src/shared/providers/{gestures → screen/gestures}/index.tsx

@@ -6,5 +6,7 @@ export type {
 	DirectionClaim,
 	DirectionClaimMap,
 	GestureContextType,
-	ScrollConfig,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
 } from "./types";

package/src/shared/providers/screen/gestures/ownership/compute-claimed-directions.ts

@@ -0,0 +1,101 @@
+import { DEFAULT_GESTURE_DIRECTION } from "../../../../constants";
+import type {
+	GestureDirection,
+	PanGestureDirection,
+} from "../../../../types/gesture.types";
+import {
+	type ClaimedDirections,
+	type Direction,
+	NO_CLAIMS,
+} from "../../../../types/ownership.types";
+
+const createClaimSet = (): ClaimedDirections => ({
+	vertical: false,
+	"vertical-inverted": false,
+	horizontal: false,
+	"horizontal-inverted": false,
+});
+
+const normalizePanGestureDirections = (
+	gestureDirection: GestureDirection | GestureDirection[] | undefined,
+): PanGestureDirection[] => {
+	const direction = gestureDirection ?? DEFAULT_GESTURE_DIRECTION;
+
+	return (Array.isArray(direction) ? direction : [direction]).filter(
+		(dir): dir is PanGestureDirection =>
+			dir !== "pinch-in" && dir !== "pinch-out",
+	);
+};
+
+const claimPanDirection = (
+	claims: ClaimedDirections,
+	direction: PanGestureDirection,
+) => {
+	if (direction === "bidirectional") {
+		claims.vertical = true;
+		claims["vertical-inverted"] = true;
+		claims.horizontal = true;
+		claims["horizontal-inverted"] = true;
+		return;
+	}
+
+	claims[direction as Direction] = true;
+};
+
+const expandSnapPointAxisClaims = (claims: ClaimedDirections) => {
+	const hasVerticalAxis = claims.vertical || claims["vertical-inverted"];
+	const hasHorizontalAxis = claims.horizontal || claims["horizontal-inverted"];
+
+	if (hasVerticalAxis) {
+		claims.vertical = true;
+		claims["vertical-inverted"] = true;
+	}
+
+	if (hasHorizontalAxis) {
+		claims.horizontal = true;
+		claims["horizontal-inverted"] = true;
+	}
+};
+
+/**
+ * Computes which directions a screen claims ownership of.
+ *
+ * A screen claims a direction when:
+ * 1. direction claiming is enabled AND
+ * 2. gestureDirection includes that direction
+ *
+ * For snap points, both directions on each configured pan axis are claimed.
+ * The first direction on an axis collapses; its inverse expands.
+ *
+ * @param canClaimDirections - Whether this screen can own gesture directions
+ * @param gestureDirection - The gesture direction(s) configured for this screen
+ * @param hasSnapPoints - Whether this screen has snap points configured
+ * @returns The claimed directions for this screen
+ */
+export function computeClaimedDirections(
+	canClaimDirections: boolean,
+	gestureDirection: GestureDirection | GestureDirection[] | undefined,
+	hasSnapPoints: boolean,
+): ClaimedDirections {
+	if (!canClaimDirections) {
+		return NO_CLAIMS;
+	}
+
+	const directions = normalizePanGestureDirections(gestureDirection);
+
+	if (directions.length === 0) {
+		return NO_CLAIMS;
+	}
+
+	const claims = createClaimSet();
+
+	for (const dir of directions) {
+		claimPanDirection(claims, dir);
+	}
+
+	if (hasSnapPoints) {
+		expandSnapPointAxisClaims(claims);
+	}
+
+	return claims;
+}

package/src/shared/{utils/gesture → providers/screen/gestures/ownership}/resolve-ownership.ts

@@ -1,10 +1,14 @@
-import type { ClaimedDirections, Direction } from "../../types/ownership.types";
+import type {
+	ClaimedDirections,
+	Direction,
+} from "../../../../types/ownership.types";
 import {
 	DIRECTIONS,
 	type DirectionOwnership,
 	NO_OWNERSHIP,
 	type OwnershipStatus,
-} from "../../types/ownership.types";
+} from "../../../../types/ownership.types";
+import type { DirectionClaim } from "../types";
 
 /**
  * Minimal interface for ancestor context needed for ownership resolution.
@@ -12,7 +16,7 @@ import {
  */
 interface AncestorClaimsContext {
 	claimedDirections: ClaimedDirections;
-	ancestorContext: AncestorClaimsContext | null;
+	gestureContext: AncestorClaimsContext | null;
 }
 
 /**
@@ -27,12 +31,12 @@ interface AncestorClaimsContext {
  * used in worklets since it's a plain object.
  *
  * @param selfClaims - The directions claimed by the current screen
- * @param ancestorContext - The ancestor context chain (can be null if no ancestors)
+ * @param gestureContext - The gesture context chain (can be null if no ancestors)
  * @returns Ownership status for all four directions
  */
 export function resolveOwnership(
 	selfClaims: ClaimedDirections,
-	ancestorContext: AncestorClaimsContext | null,
+	gestureContext: AncestorClaimsContext | null,
 ): DirectionOwnership {
 	const result: DirectionOwnership = { ...NO_OWNERSHIP };
 
@@ -40,7 +44,7 @@ export function resolveOwnership(
 		result[direction] = resolveDirectionOwnership(
 			direction,
 			selfClaims,
-			ancestorContext,
+			gestureContext,
 		);
 	}
 
@@ -53,7 +57,7 @@ export function resolveOwnership(
 function resolveDirectionOwnership(
 	direction: Direction,
 	selfClaims: ClaimedDirections,
-	ancestorContext: AncestorClaimsContext | null,
+	gestureContext: AncestorClaimsContext | null,
 ): OwnershipStatus {
 	// Check self first
 	if (selfClaims[direction]) {
@@ -61,14 +65,28 @@ function resolveDirectionOwnership(
 	}
 
 	// Walk ancestors looking for a claim
-	let ancestor = ancestorContext;
+	let ancestor = gestureContext;
 	while (ancestor) {
 		if (ancestor.claimedDirections?.[direction]) {
 			return "ancestor";
 		}
-		ancestor = ancestor.ancestorContext;
+		ancestor = ancestor.gestureContext;
 	}
 
 	// No one claims this direction
 	return "none";
 }
+
+/**
+ * Returns true when the current screen should fail and defer to a child claim.
+ */
+export function shouldDeferToChildClaim(
+	childClaim: DirectionClaim,
+	selfRouteKey: string,
+): boolean {
+	"worklet";
+	if (!childClaim) return false;
+	if (childClaim.routeKey === selfRouteKey) return false;
+	if (childClaim.isDismissing.get()) return false;
+	return true;
+}