react-native-screen-transitions 3.3.0-beta.2 → 3.3.0-beta.4

package/src/shared/hooks/gestures/use-scroll-registry.tsx

@@ -1,41 +1,107 @@
-/** biome-ignore-all lint/style/noNonNullAssertion: <Will always consume context from GestureProvider> */
+/**
+ * Connects ScrollViews to the gesture ownership system.
+ * Finds the gesture owner for the scroll axis and coordinates with their panGesture.
+ */
 
 import { useMemo } from "react";
-import type { GestureResponderEvent, LayoutChangeEvent } from "react-native";
+import type { LayoutChangeEvent } from "react-native";
+import { Gesture, type GestureType } from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
 import { useAnimatedScrollHandler } from "react-native-reanimated";
 import type { ReanimatedScrollEvent } from "react-native-reanimated/lib/typescript/hook/commonTypes";
-import { useGestureContext } from "../../providers/gestures.provider";
+import {
+	type GestureContextType,
+	type ScrollConfig,
+	useGestureContext,
+} from "../../providers/gestures.provider";
 import useStableCallback from "../use-stable-callback";
 
+/** Walks up context tree to find the screen that owns this scroll axis. */
+function findGestureOwnerForAxis(
+	context: GestureContextType | null | undefined,
+	axis: "vertical" | "horizontal",
+): {
+	scrollConfig: SharedValue<ScrollConfig | null> | null;
+	panGesture: GestureType | null;
+} {
+	let current = context;
+	const startIsolated = context?.isIsolated;
+
+	while (current) {
+		if (startIsolated !== undefined && current.isIsolated !== startIsolated) {
+			break;
+		}
+
+		const ownsAxis =
+			axis === "vertical"
+				? current.claimedDirections?.vertical ||
+					current.claimedDirections?.["vertical-inverted"]
+				: current.claimedDirections?.horizontal ||
+					current.claimedDirections?.["horizontal-inverted"];
+
+		if (ownsAxis) {
+			return {
+				scrollConfig: current.scrollConfig,
+				panGesture: current.panGesture,
+			};
+		}
+
+		current = current.ancestorContext;
+	}
+
+	return { scrollConfig: null, panGesture: null };
+}
+
 interface ScrollProgressHookProps {
 	onScroll?: (event: ReanimatedScrollEvent) => void;
 	onContentSizeChange?: (width: number, height: number) => void;
 	onLayout?: (event: LayoutChangeEvent) => void;
-	onTouchStart?: (event: GestureResponderEvent) => void;
-	onTouchEnd?: (event: GestureResponderEvent) => void;
+	direction?: "vertical" | "horizontal";
 }
 
+/**
+ * Returns scroll handlers and a native gesture for ScrollView coordination.
+ * Automatically finds the gesture owner for the scroll axis.
+ */
 export const useScrollRegistry = (props: ScrollProgressHookProps) => {
-	const context = useGestureContext()!;
-	const { scrollConfig, ancestorContext } = context;
-
-	const ancestorScrollConfigs = useMemo(() => {
-		const configs: (typeof scrollConfig)[] = [];
-		let current = ancestorContext;
-		while (current) {
-			if (current.scrollConfig) {
-				configs.push(current.scrollConfig);
+	const context = useGestureContext();
+	const scrollDirection = props.direction ?? "vertical";
+
+	const { scrollConfig, panGesture } = findGestureOwnerForAxis(
+		context,
+		scrollDirection,
+	);
+
+	const nativeGesture = useMemo(() => {
+		if (!panGesture || !scrollConfig) return null;
+
+		const setIsTouched = () => {
+			"worklet";
+			if (scrollConfig.value) {
+				scrollConfig.value = { ...scrollConfig.value, isTouched: true };
 			}
-			current = current.ancestorContext;
-		}
-		return configs;
-	}, [ancestorContext]);
+		};
+
+		const clearIsTouched = () => {
+			"worklet";
+			if (scrollConfig.value) {
+				scrollConfig.value = { ...scrollConfig.value, isTouched: false };
+			}
+		};
+
+		return Gesture.Native()
+			.onTouchesDown(setIsTouched)
+			.onTouchesUp(clearIsTouched)
+			.onTouchesCancelled(clearIsTouched)
+			.requireExternalGestureToFail(panGesture);
+	}, [panGesture, scrollConfig]);
 
 	const scrollHandler = useAnimatedScrollHandler({
 		onScroll: (event) => {
 			props.onScroll?.(event);
+			if (!scrollConfig) return;
 
-			const updateScrollPosition = (v: any) => {
+			const update = (v: any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -52,21 +118,16 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				v.y = event.contentOffset.y;
 				return v;
 			};
-
-			scrollConfig.modify(updateScrollPosition);
-
-			// Sync to ALL ancestors, not just immediate parent
-			for (const ancestorConfig of ancestorScrollConfigs) {
-				ancestorConfig.modify(updateScrollPosition);
-			}
+			scrollConfig.modify(update);
 		},
 	});
 
 	const onContentSizeChange = useStableCallback(
 		(width: number, height: number) => {
 			props.onContentSizeChange?.(width, height);
+			if (!scrollConfig) return;
 
-			const updateContentSize = (v: any) => {
+			const update = (v: any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -83,20 +144,17 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				v.contentHeight = height;
 				return v;
 			};
-
-			scrollConfig.modify(updateContentSize);
-
-			for (const ancestorConfig of ancestorScrollConfigs) {
-				ancestorConfig.modify(updateContentSize);
-			}
+			scrollConfig.modify(update);
 		},
 	);
 
 	const onLayout = useStableCallback((event: LayoutChangeEvent) => {
 		props.onLayout?.(event);
+		if (!scrollConfig) return;
+
 		const { width, height } = event.nativeEvent.layout;
 
-		const updateLayout = (v: any) => {
+		const update = (v: any) => {
 			"worklet";
 			if (v === null) {
 				return {
@@ -113,63 +171,13 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 			v.layoutWidth = width;
 			return v;
 		};
-
-		scrollConfig.modify(updateLayout);
-
-		for (const ancestorConfig of ancestorScrollConfigs) {
-			ancestorConfig.modify(updateLayout);
-		}
-	});
-
-	const onTouchStart = useStableCallback((event: GestureResponderEvent) => {
-		props.onTouchStart?.(event);
-
-		const setTouched = (v: any) => {
-			"worklet";
-			if (v === null) {
-				return {
-					x: 0,
-					y: 0,
-					contentHeight: 0,
-					contentWidth: 0,
-					layoutHeight: 0,
-					layoutWidth: 0,
-					isTouched: true,
-				};
-			}
-			v.isTouched = true;
-			return v;
-		};
-
-		scrollConfig.modify(setTouched);
-
-		for (const ancestorConfig of ancestorScrollConfigs) {
-			ancestorConfig.modify(setTouched);
-		}
-	});
-
-	const onTouchEnd = useStableCallback((event: GestureResponderEvent) => {
-		props.onTouchEnd?.(event);
-
-		const clearTouched = (v: any) => {
-			"worklet";
-			if (v === null) return v;
-			v.isTouched = false;
-			return v;
-		};
-
-		scrollConfig.modify(clearTouched);
-
-		for (const ancestorConfig of ancestorScrollConfigs) {
-			ancestorConfig.modify(clearTouched);
-		}
+		scrollConfig.modify(update);
 	});
 
 	return {
 		scrollHandler,
 		onContentSizeChange,
 		onLayout,
-		onTouchStart,
-		onTouchEnd,
+		nativeGesture,
 	};
 };

package/src/shared/hooks/use-backdrop-pointer-events.ts

@@ -2,7 +2,7 @@ import { useKeys } from "../providers/screen/keys.provider";
 import { useStackCoreContext } from "../providers/stack/core.provider";
 import { StackType } from "../types/stack.types";
 
-type BackdropBehavior = "block" | "passthrough" | "dismiss";
+type BackdropBehavior = "block" | "passthrough" | "dismiss" | "collapse";
 
 interface BackdropPointerEventsResult {
 	pointerEvents: "box-none" | undefined;

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

@@ -1,15 +1,29 @@
-import { StyleSheet, View } from "react-native";
-import {
-	GestureDetector,
-	type GestureType,
-} from "react-native-gesture-handler";
+/**
+ * Gesture System - Core Provider
+ *
+ * Each screen gets a GestureContext containing:
+ * - panGesture: Pan gesture handler for dismiss/snap
+ * - scrollConfig: Scroll state for boundary detection
+ * - claimedDirections: Which directions this screen handles
+ * - childDirectionClaims: Claims registered by descendant screens
+ *
+ * ScrollView coordination is handled by useScrollRegistry, which finds the
+ * gesture owner for the scroll axis and creates appropriate Native gestures.
+ */
+
+import { useNavigationState } from "@react-navigation/native";
+import { useEffect, useMemo } from "react";
+import type { GestureType } from "react-native-gesture-handler";
 import type { SharedValue } from "react-native-reanimated";
 import { useSharedValue } from "react-native-reanimated";
 import { useBuildGestures } from "../hooks/gestures/use-build-gestures";
-import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
-import type { GestureStoreMap } from "../stores/gesture.store";
+import { GestureStore, type GestureStoreMap } from "../stores/gesture.store";
+import type { ClaimedDirections, Direction } from "../types/ownership.types";
+import { StackType } from "../types/stack.types";
 import createProvider from "../utils/create-provider";
+import { computeClaimedDirections } from "../utils/gesture/compute-claimed-directions";
 import { useKeys } from "./screen/keys.provider";
+import { useStackCoreContext } from "./stack/core.provider";
 
 export type ScrollConfig = {
 	x: number;
@@ -21,14 +35,118 @@ export type ScrollConfig = {
 	isTouched: boolean;
 };
 
+export type DirectionClaim = {
+	routeKey: string;
+	isDismissing: SharedValue<number>;
+} | null;
+
+export type DirectionClaimMap = {
+	vertical: DirectionClaim;
+	"vertical-inverted": DirectionClaim;
+	horizontal: DirectionClaim;
+	"horizontal-inverted": DirectionClaim;
+};
+
+const NO_CLAIMS: DirectionClaimMap = {
+	vertical: null,
+	"vertical-inverted": null,
+	horizontal: null,
+	"horizontal-inverted": null,
+};
+
+const DIRECTIONS: Direction[] = [
+	"vertical",
+	"vertical-inverted",
+	"horizontal",
+	"horizontal-inverted",
+];
+
+/**
+ * Registers direction claims on ancestors that this screen shadows.
+ * Only registers claims when this screen is the current (topmost) route
+ * in its navigator, preventing unfocused screens from blocking gestures.
+ */
+function useRegisterDirectionClaims(
+	ancestorContext: GestureContextType | null | undefined,
+	claimedDirections: ClaimedDirections,
+	routeKey: string,
+	isIsolated: boolean,
+	isCurrentRoute: boolean,
+) {
+	useEffect(() => {
+		// Only register claims when this screen is the current route
+		if (!isCurrentRoute || !ancestorContext) {
+			return;
+		}
+
+		const gestureValues = GestureStore.getRouteGestures(routeKey);
+		const isDismissing = gestureValues.isDismissing;
+
+		const claimedAncestors: Array<{
+			ancestor: GestureContextType;
+			directions: Direction[];
+		}> = [];
+
+		let ancestor: GestureContextType | null = ancestorContext;
+		while (ancestor) {
+			if (ancestor.isIsolated !== isIsolated) break;
+
+			const shadowedDirections: Direction[] = [];
+			for (const dir of DIRECTIONS) {
+				if (claimedDirections[dir] && ancestor.claimedDirections?.[dir]) {
+					shadowedDirections.push(dir);
+				}
+			}
+
+			if (shadowedDirections.length > 0) {
+				claimedAncestors.push({ ancestor, directions: shadowedDirections });
+				const newClaims = { ...ancestor.childDirectionClaims.value };
+				for (const dir of shadowedDirections) {
+					newClaims[dir] = { routeKey, isDismissing };
+				}
+				ancestor.childDirectionClaims.value = newClaims;
+			}
+
+			ancestor = ancestor.ancestorContext;
+		}
+
+		return () => {
+			for (const { ancestor, directions } of claimedAncestors) {
+				const currentClaims = ancestor.childDirectionClaims.value;
+				const newClaims = { ...currentClaims };
+				let needsUpdate = false;
+
+				for (const dir of directions) {
+					if (currentClaims[dir]?.routeKey === routeKey) {
+						newClaims[dir] = null;
+						needsUpdate = true;
+					}
+				}
+
+				if (needsUpdate) {
+					ancestor.childDirectionClaims.value = newClaims;
+				}
+			}
+		};
+	}, [
+		ancestorContext,
+		claimedDirections,
+		routeKey,
+		isIsolated,
+		isCurrentRoute,
+	]);
+}
+
 export interface GestureContextType {
 	panGesture: GestureType;
 	panGestureRef: React.MutableRefObject<GestureType | undefined>;
-	nativeGesture: GestureType;
 	scrollConfig: SharedValue<ScrollConfig | null>;
 	gestureAnimationValues: GestureStoreMap;
 	ancestorContext: GestureContextType | null;
 	gestureEnabled: boolean;
+	isIsolated: boolean;
+	claimedDirections: ClaimedDirections;
+	childDirectionClaims: SharedValue<DirectionClaimMap>;
 }
 
 interface ScreenGestureProviderProps {
@@ -43,42 +161,67 @@ export const {
 	GestureContextType
 >(({ children }) => {
 	const { current } = useKeys();
+	const { flags } = useStackCoreContext();
 	const ancestorContext = useGestureContext();
-	const scrollConfig = useSharedValue<ScrollConfig | null>(null);
-	const { pointerEvents } = useBackdropPointerEvents();
 
 	const hasGestures = current.options.gestureEnabled === true;
+	const isIsolated = flags.STACK_TYPE === StackType.COMPONENT;
+
+	const hasSnapPoints =
+		Array.isArray(current.options.snapPoints) &&
+		current.options.snapPoints.length > 0;
+
+	const claimedDirections = useMemo(
+		() =>
+			computeClaimedDirections(
+				hasGestures,
+				current.options.gestureDirection,
+				hasSnapPoints,
+			),
+		[hasGestures, current.options.gestureDirection, hasSnapPoints],
+	);
+
+	const routeKey = current.route.key;
 
-	const { panGesture, panGestureRef, nativeGesture, gestureAnimationValues } =
+	// Check if this screen is the current (topmost) route in its navigator
+	const isCurrentRoute = useNavigationState(
+		(state) => state.routes[state.index]?.key === routeKey,
+	);
+
+	const scrollConfig = useSharedValue<ScrollConfig | null>(null);
+	const childDirectionClaims = useSharedValue<DirectionClaimMap>(NO_CLAIMS);
+
+	useRegisterDirectionClaims(
+		ancestorContext,
+		claimedDirections,
+		routeKey,
+		isIsolated,
+		isCurrentRoute,
+	);
+
+	const { panGesture, panGestureRef, gestureAnimationValues } =
 		useBuildGestures({
 			scrollConfig,
 			ancestorContext,
+			claimedDirections,
+			childDirectionClaims,
+			isIsolated,
 		});
 
 	const value: GestureContextType = {
 		panGesture,
 		panGestureRef,
 		scrollConfig,
-		nativeGesture,
 		gestureAnimationValues,
 		ancestorContext,
 		gestureEnabled: hasGestures,
+		isIsolated,
+		claimedDirections,
+		childDirectionClaims,
 	};
 
 	return {
 		value,
-		children: (
-			<GestureDetector gesture={panGesture}>
-				<View style={styles.container} pointerEvents={pointerEvents}>
-					{children}
-				</View>
-			</GestureDetector>
-		),
+		children,
 	};
 });
-
-const styles = StyleSheet.create({
-	container: {
-		flex: 1,
-	},
-});

package/src/shared/types/ownership.types.ts

@@ -0,0 +1,77 @@
+/**
+ * Gesture Ownership System Types
+ *
+ * Core principles:
+ * 1. Gestures dismiss stacks, not screens
+ * 2. Ownership is per-direction (4 independent directions)
+ * 3. Shadowing: child claiming same direction blocks parent
+ * 4. Inheritance: no local claim walks up tree to find owner
+ */
+
+/**
+ * The four independent gesture directions.
+ * Each direction is owned independently.
+ *
+ * Uses the same format as GestureDirection from gesture.types.ts
+ * (excluding 'bidirectional' which expands to all four).
+ */
+export type Direction =
+	| "vertical"
+	| "vertical-inverted"
+	| "horizontal"
+	| "horizontal-inverted";
+
+/**
+ * All possible directions as an array for iteration.
+ */
+export const DIRECTIONS: Direction[] = [
+	"vertical",
+	"vertical-inverted",
+	"horizontal",
+	"horizontal-inverted",
+];
+
+/**
+ * Map of which directions a screen claims ownership of.
+ * A screen claims a direction when:
+ * - gestureEnabled is true AND
+ * - gestureDirection includes that direction
+ *
+ * For snap points, both directions on the axis are claimed automatically.
+ */
+export type ClaimedDirections = Record<Direction, boolean>;
+
+/**
+ * Empty claims - used when gestureEnabled is false.
+ */
+export const NO_CLAIMS: ClaimedDirections = {
+	vertical: false,
+	"vertical-inverted": false,
+	horizontal: false,
+	"horizontal-inverted": false,
+};
+
+/**
+ * Ownership status for a direction relative to the current screen.
+ *
+ * - 'self': Current screen owns this direction (should activate)
+ * - 'ancestor': An ancestor owns this direction (should fail to bubble up)
+ * - 'none': No one owns this direction (should fail, no gesture response)
+ */
+export type OwnershipStatus = "self" | "ancestor" | "none";
+
+/**
+ * Map of ownership status for all four directions.
+ * Pre-computed during render for worklet access.
+ */
+export type DirectionOwnership = Record<Direction, OwnershipStatus>;
+
+/**
+ * Empty ownership - used when no gestures are configured anywhere.
+ */
+export const NO_OWNERSHIP: DirectionOwnership = {
+	vertical: "none",
+	"vertical-inverted": "none",
+	horizontal: "none",
+	"horizontal-inverted": "none",
+};

package/src/shared/types/screen.types.ts

@@ -77,9 +77,17 @@ export type ScreenTransitionConfig = {
 
 	/**
 	 * How much the gesture's final velocity impacts the dismiss decision.
+	 * @default 0.3
 	 */
 	gestureVelocityImpact?: number;
 
+	/**
+	 * How much velocity affects snap point targeting. Lower values make snapping
+	 * feel more deliberate (iOS-like), higher values make it more responsive to flicks.
+	 * @default 0.1
+	 */
+	snapVelocityImpact?: number;
+
 	/**
 	 * Distance threshold for gesture recognition throughout the screen.
 	 */
@@ -155,14 +163,29 @@ export type ScreenTransitionConfig = {
 	 */
 	initialSnapIndex?: number;
 
+	/**
+	 * Controls whether swiping to expand the sheet works from within a ScrollView.
+	 *
+	 * - `true` (Apple Maps style): Swiping up at scroll top expands the sheet
+	 * - `false` (Instagram style): Expand only works via deadspace (non-scrollable areas)
+	 *
+	 * Collapse (swipe down at scroll top) always works regardless of this setting.
+	 *
+	 * Only applies to screens with `snapPoints` configured.
+	 *
+	 * @default true
+	 */
+	expandViaScrollView?: boolean;
+
 	/**
 	 * Controls how touches interact with the backdrop area (outside the screen content).
 	 *
 	 * - `'block'`: Backdrop catches all touches (default for most screens)
 	 * - `'passthrough'`: Touches pass through to content behind (default for component stacks)
 	 * - `'dismiss'`: Tapping backdrop dismisses the screen
+	 * - `'collapse'`: Tapping backdrop collapses to next lower snap point (dismisses at min)
 	 *
 	 * @default 'block' (or 'passthrough' for component stacks)
 	 */
-	backdropBehavior?: "block" | "passthrough" | "dismiss";
+	backdropBehavior?: "block" | "passthrough" | "dismiss" | "collapse";
 };