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

package/src/shared/utils/gesture/check-gesture-activation.ts

@@ -7,6 +7,7 @@ import {
 	GestureOffsetState,
 	type SideActivation,
 } from "../../types/gesture.types";
+import type { Direction } from "../../types/ownership.types";
 import type { Layout } from "../../types/screen.types";
 
 type Directions = {
@@ -311,129 +312,94 @@ export const applyOffsetRules = ({
 	};
 };
 
-interface ScrollAwareActivationParams {
-	swipeInfo: {
-		isSwipingDown: boolean;
-		isSwipingUp: boolean;
-		isSwipingRight: boolean;
-		isSwipingLeft: boolean;
-	};
-	directions: Directions;
-	scrollConfig: ScrollConfig | null;
-	hasSnapPoints?: boolean;
-	canExpandMore?: boolean;
-}
-
-type GestureDirection =
-	| "vertical"
-	| "vertical-inverted"
-	| "horizontal"
-	| "horizontal-inverted";
-
 /**
- * Checks if a gesture should activate based on scroll position.
- * Returns the direction to activate for, or null if activation should not occur.
+ * Checks if a ScrollView is at its boundary for the given swipe direction.
+ * This is a simplified boundary check that respects axis isolation.
+ *
+ * Per the spec:
+ * - A vertical ScrollView never yields to horizontal gestures
+ * - A horizontal ScrollView never yields to vertical gestures
+ * - ScrollView must be at boundary before yielding control
+ *
+ * For snap point sheets, the boundary depends on where the sheet originates from:
+ * - Bottom sheet (vertical): scrollY = 0 (top/base)
+ * - Top sheet (verticalInverted): scrollY >= maxY (bottom/end)
+ * - Right drawer (horizontal): scrollX = 0 (left/base)
+ * - Left drawer (horizontalInverted): scrollX >= maxX (right/end)
+ *
+ * The rule: "when the ScrollView can't scroll any further in the direction
+ * the sheet came from, yield to the gesture."
+ *
+ * @param scrollConfig - The current scroll state
+ * @param direction - The swipe direction to check
+ * @param snapAxisInverted - For snap point sheets, whether the axis is inverted (top sheet / left drawer)
+ * @returns true if at boundary (gesture should activate), false otherwise
  */
-export function checkScrollAwareActivation({
-	swipeInfo,
-	directions,
-	scrollConfig,
-	hasSnapPoints,
-	canExpandMore,
-}: ScrollAwareActivationParams): {
-	shouldActivate: boolean;
-	direction: GestureDirection | null;
-} {
+export function checkScrollBoundary(
+	scrollConfig: ScrollConfig | null,
+	direction: Direction,
+	snapAxisInverted?: boolean,
+): boolean {
 	"worklet";
 
-	const { isSwipingDown, isSwipingUp, isSwipingRight, isSwipingLeft } =
-		swipeInfo;
-
-	// Extract scroll values from config
-	const scrollX = scrollConfig?.x ?? 0;
-	const scrollY = scrollConfig?.y ?? 0;
-	const maxScrollX = scrollConfig
-		? scrollConfig.contentWidth - scrollConfig.layoutWidth
-		: 0;
-	const maxScrollY = scrollConfig
-		? scrollConfig.contentHeight - scrollConfig.layoutHeight
-		: 0;
-	const snapAxisInverted = directions.snapAxisInverted;
-
-	// With snap points, gestures should only activate based on the PRIMARY scroll edge
-	// (the edge where the sheet originates from), not the opposite edge.
-	// This prevents the auto-enabled opposite direction from hijacking scrolls.
-	if (hasSnapPoints) {
-		const isVerticalAxis = directions.vertical || directions.verticalInverted;
-		const isHorizontalAxis =
-			directions.horizontal || directions.horizontalInverted;
-
-		if (isVerticalAxis) {
-			if (snapAxisInverted) {
-				// Sheet from TOP (vertical-inverted): only activate at scroll BOTTOM
-				if (scrollY >= maxScrollY) {
-					if (isSwipingUp) {
-						return { shouldActivate: true, direction: "vertical-inverted" };
-					}
-					if (isSwipingDown && canExpandMore) {
-						return { shouldActivate: true, direction: "vertical" };
-					}
-				}
-			} else {
-				// Sheet from BOTTOM (vertical): only activate at scroll TOP
-				if (scrollY <= 0) {
-					if (isSwipingDown) {
-						return { shouldActivate: true, direction: "vertical" };
-					}
-					if (isSwipingUp && canExpandMore) {
-						return { shouldActivate: true, direction: "vertical-inverted" };
-					}
-				}
-			}
-		}
-
-		if (isHorizontalAxis) {
-			if (snapAxisInverted) {
-				// Sheet from LEFT (horizontal-inverted): only activate at scroll RIGHT
-				if (scrollX >= maxScrollX) {
-					if (isSwipingLeft) {
-						return { shouldActivate: true, direction: "horizontal-inverted" };
-					}
-					if (isSwipingRight && canExpandMore) {
-						return { shouldActivate: true, direction: "horizontal" };
-					}
-				}
-			} else {
-				// Sheet from RIGHT (horizontal): only activate at scroll LEFT
-				if (scrollX <= 0) {
-					if (isSwipingRight) {
-						return { shouldActivate: true, direction: "horizontal" };
-					}
-					if (isSwipingLeft && canExpandMore) {
-						return { shouldActivate: true, direction: "horizontal-inverted" };
-					}
-				}
-			}
-		}
-
-		return { shouldActivate: false, direction: null };
+	if (!scrollConfig) {
+		// No scroll config means no ScrollView - allow gesture
+		return true;
 	}
 
-	if (directions.vertical && isSwipingDown && scrollY <= 0) {
-		return { shouldActivate: true, direction: "vertical" };
-	}
-
-	if (directions.horizontal && isSwipingRight && scrollX <= 0) {
-		return { shouldActivate: true, direction: "horizontal" };
-	}
-
-	if (directions.verticalInverted && isSwipingUp && scrollY >= maxScrollY) {
-		return { shouldActivate: true, direction: "vertical-inverted" };
+	const {
+		x: scrollX,
+		y: scrollY,
+		contentWidth,
+		contentHeight,
+		layoutWidth,
+		layoutHeight,
+	} = scrollConfig;
+
+	// Calculate max scroll values
+	const maxScrollX = Math.max(0, contentWidth - layoutWidth);
+	const maxScrollY = Math.max(0, contentHeight - layoutHeight);
+
+	// For snap point sheets (snapAxisInverted is defined), boundary depends on sheet origin
+	// Even if content isn't scrollable, respect bounce/overscroll state
+	if (snapAxisInverted !== undefined) {
+		const isVerticalDirection =
+			direction === "vertical" || direction === "vertical-inverted";
+
+		if (isVerticalDirection) {
+			// Bottom sheet (not inverted): boundary at scroll top
+			// Top sheet (inverted): boundary at scroll bottom
+			return snapAxisInverted ? scrollY >= maxScrollY : scrollY <= 0;
+		}
+		// Horizontal direction
+		// Right drawer (not inverted): boundary at scroll left
+		// Left drawer (inverted): boundary at scroll right
+		return snapAxisInverted ? scrollX >= maxScrollX : scrollX <= 0;
 	}
 
-	if (directions.horizontalInverted && isSwipingLeft && scrollX >= maxScrollX) {
-		return { shouldActivate: true, direction: "horizontal-inverted" };
+	// Non-sheet screens: each direction has its own boundary
+	switch (direction) {
+		case "vertical":
+			// Swipe down - check if at top of vertical scroll
+			// Even if content isn't scrollable, respect bounce/overscroll state
+			return scrollY <= 0;
+
+		case "vertical-inverted":
+			// Swipe up - check if at bottom of vertical scroll
+			// Even if content isn't scrollable, respect bounce/overscroll state
+			return scrollY >= maxScrollY;
+
+		case "horizontal":
+			// Swipe right - check if at left of horizontal scroll
+			// Even if content isn't scrollable, respect bounce/overscroll state
+			return scrollX <= 0;
+
+		case "horizontal-inverted":
+			// Swipe left - check if at right of horizontal scroll
+			// Even if content isn't scrollable, respect bounce/overscroll state
+			return scrollX >= maxScrollX;
+
+		default:
+			return true;
 	}
-
-	return { shouldActivate: false, direction: null };
 }

package/src/shared/utils/gesture/compute-claimed-directions.ts

@@ -0,0 +1,93 @@
+import type { GestureDirection } from "../../types/gesture.types";
+import {
+	type ClaimedDirections,
+	type Direction,
+	NO_CLAIMS,
+} from "../../types/ownership.types";
+
+/**
+ * Computes which directions a screen claims ownership of.
+ *
+ * A screen claims a direction when:
+ * 1. gestureEnabled is true 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.
+ *
+ * @param gestureEnabled - Whether gestures are enabled for this screen
+ * @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,
+	gestureDirection: GestureDirection | GestureDirection[] | undefined,
+	hasSnapPoints: boolean,
+): ClaimedDirections {
+	// If gestures are not enabled, claim nothing
+	if (!gestureEnabled) {
+		return NO_CLAIMS;
+	}
+
+	// Default to vertical if no direction specified
+	const direction = gestureDirection ?? "vertical";
+
+	// Normalize to array
+	const directions: GestureDirection[] = Array.isArray(direction)
+		? direction
+		: [direction];
+
+	// Start with no claims
+	const claims: ClaimedDirections = {
+		vertical: false,
+		"vertical-inverted": false,
+		horizontal: false,
+		"horizontal-inverted": false,
+	};
+
+	// Process each direction
+	for (const dir of directions) {
+		if (dir === "bidirectional") {
+			// Bidirectional claims all four directions
+			claims.vertical = true;
+			claims["vertical-inverted"] = true;
+			claims.horizontal = true;
+			claims["horizontal-inverted"] = true;
+		} else {
+			// Claim the specific direction
+			claims[dir as Direction] = true;
+		}
+	}
+
+	// For snap points, claim both directions on the axis
+	// This enables both expand (inverse) and collapse/dismiss (primary) gestures
+	if (hasSnapPoints) {
+		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;
+		}
+	}
+
+	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/determine-snap-target.ts

@@ -5,7 +5,11 @@ interface DetermineSnapTargetProps {
 	velocity: number;
 	/** Screen dimension along the snap axis (width or height) */
 	dimension: number;
-	/** How much velocity affects the snap decision (0-1). Default 0.15 */
+	/**
+	 * How much velocity affects the snap decision.
+	 * Lower values = more deliberate/iOS-like, higher values = more responsive to flicks.
+	 * @default 0.1
+	 */
 	velocityFactor?: number;
 	/** Whether dismiss (progress=0) is allowed. Default true */
 	canDismiss?: boolean;
@@ -28,7 +32,7 @@ export function determineSnapTarget({
 	snapPoints,
 	velocity,
 	dimension,
-	velocityFactor = 0.15,
+	velocityFactor = 0.1,
 	canDismiss = true,
 }: DetermineSnapTargetProps): DetermineSnapTargetResult {
 	"worklet";

package/src/shared/utils/gesture/find-collapse-target.ts

@@ -0,0 +1,42 @@
+import { EPSILON } from "../../constants";
+
+interface FindCollapseTargetResult {
+	target: number;
+	shouldDismiss: boolean;
+}
+
+/**
+ * Finds the next lower snap point for backdrop collapse behavior.
+ *
+ * - If above min snap: returns next lower snap point
+ * - If at or below min snap: returns 0 (dismiss) if canDismiss, else stays at min
+ *
+ * @param currentProgress - Current animation progress
+ * @param snapPoints - Array of snap points
+ * @param canDismiss - Whether dismissing is allowed
+ */
+export function findCollapseTarget(
+	currentProgress: number,
+	snapPoints: number[],
+	canDismiss: boolean,
+): FindCollapseTargetResult {
+	"worklet";
+
+	const sorted = [...snapPoints].sort((a, b) => a - b);
+	const minSnap = sorted[0];
+
+	// Find next lower snap point
+	for (let i = sorted.length - 1; i >= 0; i--) {
+		if (sorted[i] < currentProgress - EPSILON) {
+			return { target: sorted[i], shouldDismiss: false };
+		}
+	}
+
+	// At or below min snap → dismiss if allowed
+	if (canDismiss) {
+		return { target: 0, shouldDismiss: true };
+	}
+
+	// Can't dismiss, stay at min
+	return { target: minSnap, shouldDismiss: false };
+}

package/src/shared/utils/gesture/resolve-ownership.ts

@@ -0,0 +1,110 @@
+import type { ClaimedDirections, Direction } from "../../types/ownership.types";
+import {
+	DIRECTIONS,
+	type DirectionOwnership,
+	NO_OWNERSHIP,
+	type OwnershipStatus,
+} from "../../types/ownership.types";
+
+/**
+ * Minimal interface for ancestor context needed for ownership resolution.
+ * This allows the function to be used without importing the full GestureContextType.
+ */
+export interface AncestorClaimsContext {
+	claimedDirections: ClaimedDirections;
+	ancestorContext: AncestorClaimsContext | null;
+}
+
+/**
+ * Resolves ownership status for all directions relative to the current screen.
+ *
+ * For each direction:
+ * 1. If the current screen claims it → 'self' (should activate)
+ * 2. Else, walk up ancestors looking for a claim → 'ancestor' (should fail to bubble)
+ * 3. If no one claims it → 'none' (should fail, no gesture response)
+ *
+ * This is computed during render (JS thread) and the result can be safely
+ * 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)
+ * @returns Ownership status for all four directions
+ */
+export function resolveOwnership(
+	selfClaims: ClaimedDirections,
+	ancestorContext: AncestorClaimsContext | null,
+): DirectionOwnership {
+	const result: DirectionOwnership = { ...NO_OWNERSHIP };
+
+	for (const direction of DIRECTIONS) {
+		result[direction] = resolveDirectionOwnership(
+			direction,
+			selfClaims,
+			ancestorContext,
+		);
+	}
+
+	return result;
+}
+
+/**
+ * Resolves ownership for a single direction.
+ */
+function resolveDirectionOwnership(
+	direction: Direction,
+	selfClaims: ClaimedDirections,
+	ancestorContext: AncestorClaimsContext | null,
+): OwnershipStatus {
+	// Check self first
+	if (selfClaims[direction]) {
+		return "self";
+	}
+
+	// Walk ancestors looking for a claim
+	let ancestor = ancestorContext;
+	while (ancestor) {
+		if (ancestor.claimedDirections?.[direction]) {
+			return "ancestor";
+		}
+		ancestor = ancestor.ancestorContext;
+	}
+
+	// No one claims this direction
+	return "none";
+}
+
+/**
+ * Finds the nearest ancestor (or self if isCurrentOwner) that claims any direction.
+ * Used for setting up native gesture relationships.
+ *
+ * @param selfClaimsAny - Whether the current screen claims any direction
+ * @param ancestorContext - The ancestor context chain
+ * @returns The nearest context that claims a direction, or null
+ */
+export function findNearestOwner(
+	selfClaimsAny: boolean,
+	ancestorContext: AncestorClaimsContext | null,
+): AncestorClaimsContext | null {
+	// If self claims any direction, self is the nearest owner
+	// (but we return null since this is used for finding ANCESTOR owners)
+	if (selfClaimsAny) {
+		return null;
+	}
+
+	// Walk ancestors looking for one that claims any direction
+	let ancestor = ancestorContext;
+	while (ancestor) {
+		const claims = ancestor.claimedDirections;
+		if (
+			claims?.vertical ||
+			claims?.["vertical-inverted"] ||
+			claims?.horizontal ||
+			claims?.["horizontal-inverted"]
+		) {
+			return ancestor;
+		}
+		ancestor = ancestor.ancestorContext;
+	}
+
+	return null;
+}

package/src/shared/utils/gesture/velocity.ts

@@ -3,6 +3,7 @@ import type {
 	PanGestureHandlerEventPayload,
 } from "react-native-gesture-handler";
 import { clamp } from "react-native-reanimated";
+import { ANIMATION_SNAP_THRESHOLD, EPSILON } from "../../constants";
 import type { AnimationStoreMap } from "../../stores/animation.store";
 
 interface CalculateProgressProps {
@@ -19,7 +20,6 @@ interface CalculateProgressProps {
 }
 
 const MAX_VELOCITY_MAGNITUDE = 3.2;
-const NEAR_ZERO_THRESHOLD = 0.01;
 
 /**
  * Converts velocity from pixels/second to normalized units/second (0-1 range)
@@ -53,7 +53,7 @@ const calculateRestoreVelocity = (
 ) => {
 	"worklet";
 
-	if (Math.abs(currentValueNormalized) < NEAR_ZERO_THRESHOLD) return 0;
+	if (Math.abs(currentValueNormalized) < ANIMATION_SNAP_THRESHOLD) return 0;
 
 	const directionTowardZero = Math.sign(currentValueNormalized) || 1;
 	const clampedVelocity = Math.min(Math.abs(baseVelocityNormalized), 1);
@@ -132,16 +132,26 @@ const shouldPassDismissalThreshold = (
 	"worklet";
 
 	const normalizedTranslation = translationPixels / Math.max(1, screenSize);
+
+	// If translation is essentially zero, velocity alone shouldn't trigger dismissal.
+	// User must have meaningfully moved in the dismiss direction.
+	if (Math.abs(normalizedTranslation) < EPSILON) {
+		return false;
+	}
+
 	const normalizedVelocity = normalize(velocityPixelsPerSecond, screenSize);
 
 	const projectedNormalizedPosition =
 		normalizedTranslation + normalizedVelocity * velocityWeight;
 
-	const exceedsThreshold = Math.abs(projectedNormalizedPosition) > 0.5;
-
-	const hasMovement = translationPixels !== 0 || velocityPixelsPerSecond !== 0;
+	// The dismiss direction is determined by the sign of the translation.
+	// Multiplying by this sign normalizes the projection so "toward dismiss" is always positive.
+	// This prevents dismissal when the user drags back (opposing velocity flips projection negative).
+	const dismissSign = Math.sign(translationPixels);
+	const projectedInDismissDirection = projectedNormalizedPosition * dismissSign;
+	const exceedsThreshold = projectedInDismissDirection > 0.5;
 
-	return exceedsThreshold && hasMovement;
+	return exceedsThreshold;
 };
 
 export const velocity = {