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

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,
+	};
+}

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

@@ -0,0 +1,53 @@
+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 { PanGestureRuntime, PinchGestureRuntime } from "../types";
+
+type StableRuntimeConfig = PanGestureRuntime | PinchGestureRuntime;
+type PanRuntimeConfigInput = Omit<PanGestureRuntime, "stores">;
+type PinchRuntimeConfigInput = Omit<PinchGestureRuntime, "stores">;
+type StableRuntimeConfigInput = PanRuntimeConfigInput | PinchRuntimeConfigInput;
+
+export function useStableRuntimeConfig(
+	runtimeConfigInput: PanRuntimeConfigInput,
+): SharedValue<PanGestureRuntime>;
+export function useStableRuntimeConfig(
+	runtimeConfigInput: PinchRuntimeConfigInput,
+): SharedValue<PinchGestureRuntime>;
+export function useStableRuntimeConfig(
+	runtimeConfigInput: StableRuntimeConfigInput,
+): SharedValue<PanGestureRuntime> | SharedValue<PinchGestureRuntime> {
+	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<StableRuntimeConfig>(() => {
+		return {
+			participation,
+			policy,
+			stores,
+			gestureProgressBaseline,
+			lockedSnapPoint,
+		} as StableRuntimeConfig;
+	}, [participation, policy, stores, gestureProgressBaseline, lockedSnapPoint]);
+	const stableRuntimeConfig = useSharedValue(runtimeConfig);
+
+	useLayoutEffect(() => {
+		stableRuntimeConfig.set(runtimeConfig);
+	}, [stableRuntimeConfig, runtimeConfig]);
+
+	return stableRuntimeConfig as
+		| SharedValue<PanGestureRuntime>
+		| SharedValue<PinchGestureRuntime>;
+}

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/{utils/gesture → providers/screen/gestures/ownership}/compute-claimed-directions.ts

@@ -1,42 +1,51 @@
-import type { GestureDirection } from "../../types/gesture.types";
+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";
+} from "../../../../types/ownership.types";
 
 /**
  * Computes which directions a screen claims ownership of.
  *
  * A screen claims a direction when:
- * 1. gestureEnabled is true AND
+ * 1. direction claiming is enabled AND
  * 2. gestureDirection includes that direction
  *
- * For snap points, both directions on the axis are claimed automatically.
- * This is because a snap point sheet handles both expand (inverse) and collapse (primary) gestures.
+ * For snap points, both directions on each configured pan axis are claimed.
+ * The first direction on an axis collapses; its inverse expands.
  *
- * @param gestureEnabled - Whether gestures are enabled for this screen
+ * @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(
-	gestureEnabled: boolean,
+	canClaimDirections: boolean,
 	gestureDirection: GestureDirection | GestureDirection[] | undefined,
 	hasSnapPoints: boolean,
 ): ClaimedDirections {
-	// If gestures are not enabled, claim nothing
-	if (!gestureEnabled) {
+	if (!canClaimDirections) {
 		return NO_CLAIMS;
 	}
 
-	// Default to vertical if no direction specified
-	const direction = gestureDirection ?? "vertical";
+	const direction = gestureDirection ?? DEFAULT_GESTURE_DIRECTION;
 
 	// Normalize to array
-	const directions: GestureDirection[] = Array.isArray(direction)
-		? direction
-		: [direction];
+	const directions: PanGestureDirection[] = (
+		Array.isArray(direction) ? direction : [direction]
+	).filter(
+		(dir): dir is PanGestureDirection =>
+			dir !== "pinch-in" && dir !== "pinch-out",
+	);
+
+	if (directions.length === 0) {
+		return NO_CLAIMS;
+	}
 
 	// Start with no claims
 	const claims: ClaimedDirections = {
@@ -60,8 +69,7 @@ export function computeClaimedDirections(
 		}
 	}
 
-	// For snap points, claim both directions on the axis
-	// This enables both expand (inverse) and collapse/dismiss (primary) gestures
+	// Snap points own both directions on every configured pan axis.
 	if (hasSnapPoints) {
 		const hasVerticalAxis = claims.vertical || claims["vertical-inverted"];
 		const hasHorizontalAxis =
@@ -79,15 +87,3 @@ export function computeClaimedDirections(
 
 	return claims;
 }
-
-/**
- * Checks if any direction is claimed.
- */
-export function claimsAnyDirection(claims: ClaimedDirections): boolean {
-	return (
-		claims.vertical ||
-		claims["vertical-inverted"] ||
-		claims.horizontal ||
-		claims["horizontal-inverted"]
-	);
-}

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

@@ -1,10 +1,13 @@
-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";
 
 /**
  * Minimal interface for ancestor context needed for ownership resolution.
@@ -12,7 +15,7 @@ import {
  */
 interface AncestorClaimsContext {
 	claimedDirections: ClaimedDirections;
-	ancestorContext: AncestorClaimsContext | null;
+	gestureContext: AncestorClaimsContext | null;
 }
 
 /**
@@ -27,12 +30,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 +43,7 @@ export function resolveOwnership(
 		result[direction] = resolveDirectionOwnership(
 			direction,
 			selfClaims,
-			ancestorContext,
+			gestureContext,
 		);
 	}
 
@@ -53,7 +56,7 @@ export function resolveOwnership(
 function resolveDirectionOwnership(
 	direction: Direction,
 	selfClaims: ClaimedDirections,
-	ancestorContext: AncestorClaimsContext | null,
+	gestureContext: AncestorClaimsContext | null,
 ): OwnershipStatus {
 	// Check self first
 	if (selfClaims[direction]) {
@@ -61,12 +64,12 @@ 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

package/src/shared/providers/screen/gestures/ownership/should-defer-to-child-claim.ts

@@ -0,0 +1,15 @@
+import type { DirectionClaim } from "../types";
+
+/**
+ * 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;
+}

package/src/shared/providers/screen/gestures/ownership/use-walk-up-and-register-shadowing-claims.ts

@@ -0,0 +1,93 @@
+import { useEffect, useMemo } from "react";
+import { GestureStore } from "../../../../stores/gesture.store";
+import {
+	type ClaimedDirections,
+	DIRECTIONS,
+	type Direction,
+} from "../../../../types/ownership.types";
+import { useDescriptorDerivations } from "../../../screen/descriptors";
+import { useGestureContext } from "../gestures.provider";
+import { walkGestureAncestors } from "../helpers/walk-gesture-ancestors";
+import type { GestureContextType } from "../types";
+
+type ShadowedAncestor = {
+	ancestor: GestureContextType;
+	directions: Direction[];
+};
+
+const NO_SHADOWED_ANCESTORS: ShadowedAncestor[] = [];
+
+/**
+ * Registers this screen with ancestors that claim the same direction.
+ *
+ * Example, when C is top-most:
+ * A claims vertical
+ * └─ B claims horizontal
+ *    └─ C claims vertical
+ *
+ * C walks up the tree and writes itself into A.childDirectionClaims.vertical.
+ * B is skipped because it does not claim vertical.
+ */
+export function useWalkUpAndRegisterShadowingClaims(
+	claimedDirections: ClaimedDirections,
+): void {
+	const parentContext = useGestureContext();
+	const { isTopMostScreen, currentScreenKey } = useDescriptorDerivations();
+
+	const shadowedAncestors = useMemo(() => {
+		if (!parentContext) return NO_SHADOWED_ANCESTORS;
+
+		const ancestors: ShadowedAncestor[] = [];
+		for (const ancestor of walkGestureAncestors(parentContext)) {
+			const shadowedDirections: Direction[] = [];
+
+			for (const dir of DIRECTIONS) {
+				if (claimedDirections[dir] && ancestor.claimedDirections?.[dir]) {
+					shadowedDirections.push(dir);
+				}
+			}
+
+			if (shadowedDirections.length > 0) {
+				ancestors.push({ ancestor, directions: shadowedDirections });
+			}
+		}
+
+		return ancestors.length ? ancestors : NO_SHADOWED_ANCESTORS;
+	}, [parentContext, claimedDirections]);
+
+	useEffect(() => {
+		if (!isTopMostScreen || !shadowedAncestors.length) {
+			return;
+		}
+
+		const isDismissing = GestureStore.getValue(currentScreenKey, "dismissing");
+
+		for (const { ancestor, directions } of shadowedAncestors) {
+			const newClaims = { ...ancestor.childDirectionClaims.get() };
+			for (const dir of directions) {
+				newClaims[dir] = { routeKey: currentScreenKey, isDismissing };
+			}
+			ancestor.childDirectionClaims.set(newClaims);
+		}
+
+		return () => {
+			for (const { ancestor, directions } of shadowedAncestors) {
+				const currentClaims = ancestor.childDirectionClaims.get();
+				const newClaims = { ...currentClaims };
+				let needsUpdate = false;
+
+				for (const dir of directions) {
+					// Only remove claims written by this screen; a newer descendant may own it now.
+					if (currentClaims[dir]?.routeKey === currentScreenKey) {
+						newClaims[dir] = null;
+						needsUpdate = true;
+					}
+				}
+
+				if (needsUpdate) {
+					ancestor.childDirectionClaims.set(newClaims);
+				}
+			}
+		};
+	}, [shadowedAncestors, currentScreenKey, isTopMostScreen]);
+}