react-native-screen-transitions 3.3.0-rc.3 → 3.4.0-alpha.0

package/src/shared/index.ts

@@ -1,10 +1,17 @@
 import { FlatList, Pressable, ScrollView, View } from "react-native";
+import {
+	Boundary,
+	createBoundaryComponent,
+} from "./components/create-boundary-component";
+import { buildBoundaryMatchKey } from "./components/create-boundary-component/utils/build-boundary-match-key";
 import { createTransitionAwareComponent } from "./components/create-transition-aware-component";
 import MaskedView from "./components/integrations/masked-view";
 import { Presets, Specs } from "./configs";
 
 export default {
 	createTransitionAwareComponent,
+	createBoundaryComponent,
+	Boundary,
 	View: createTransitionAwareComponent(View),
 	Pressable: createTransitionAwareComponent(Pressable),
 	ScrollView: createTransitionAwareComponent(ScrollView, {
@@ -19,18 +26,28 @@ export default {
 };
 
 export { snapTo } from "./animation/snap-to";
-export { useScreenAnimation } from "./hooks/animation/use-screen-animation";
 export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
 export { useHistory } from "./hooks/navigation/use-history";
 export {
 	type ScreenState,
 	useScreenState,
 } from "./hooks/navigation/use-screen-state";
+export { useScreenAnimation } from "./providers/screen/animation";
+export { buildBoundaryMatchKey };
 
 export type {
+	AnimatedViewStyle,
 	AnimationConfig,
 	BoundEntry,
 	BoundsLink,
+	BoundsNavigationAccessor,
+	BoundsNavigationOptions,
+	BoundsNavigationPreset,
+	BoundsStyleOptions,
+	LegacyTransitionInterpolatedStyle,
+	NewTransitionInterpolatedStyle,
+	NormalizedTransitionInterpolatedStyle,
+	NormalizedTransitionSlotStyle,
 	OverlayInterpolationProps,
 	OverlayMode,
 	OverlayProps,
@@ -38,5 +55,7 @@ export type {
 	ScreenStyleInterpolator,
 	ScreenTransitionConfig,
 	TransitionInterpolatedStyle,
+	TransitionSlotExplicit,
+	TransitionSlotStyle,
 	TransitionSpec,
 } from "./types";

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

@@ -0,0 +1,127 @@
+/**
+ * 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 { useMemo } from "react";
+import { useSharedValue } from "react-native-reanimated";
+import { StackType } from "../../types/stack.types";
+import createProvider from "../../utils/create-provider";
+import { computeClaimedDirections } from "../../utils/gesture/compute-claimed-directions";
+import { validateSnapPoints } from "../../utils/gesture/validate-snap-points";
+import {
+	useDescriptorDerivations,
+	useDescriptors,
+} from "../screen/descriptors";
+import { useStackCoreContext } from "../stack/core.provider";
+import { useRegisterDirectionClaims } from "./helpers/register-direction-claims";
+import {
+	type DirectionClaimMap,
+	type GestureContextType,
+	NO_CLAIMS,
+	type ScrollConfig,
+} from "./types";
+import { useBuildGestures } from "./use-build-gestures";
+
+interface ScreenGestureProviderProps {
+	children: React.ReactNode;
+}
+
+export const {
+	ScreenGestureProvider,
+	useScreenGestureContext: useGestureContext,
+} = createProvider("ScreenGesture", { guarded: false })<
+	ScreenGestureProviderProps,
+	GestureContextType
+>(({ children }): { value: GestureContextType; children: React.ReactNode } => {
+	const { current } = useDescriptors();
+	const { isFirstKey, isTopMostScreen } = useDescriptorDerivations();
+	const { flags } = useStackCoreContext();
+
+	const ancestorContext: GestureContextType | null = useGestureContext();
+	const isIsolated = flags.STACK_TYPE === StackType.COMPONENT;
+	const routeKey = current.route.key;
+
+	const canDismiss = Boolean(
+		isFirstKey ? false : current.options.gestureEnabled,
+	);
+
+	const { hasSnapPoints } = useMemo(
+		() =>
+			validateSnapPoints({
+				snapPoints: current.options.snapPoints,
+				canDismiss,
+			}),
+		[current.options.snapPoints, canDismiss],
+	);
+
+	const gestureEnabled = canDismiss || hasSnapPoints;
+
+	const claimedDirections = useMemo(
+		() =>
+			computeClaimedDirections(
+				gestureEnabled,
+				current.options.gestureDirection,
+				hasSnapPoints,
+			),
+		[gestureEnabled, current.options.gestureDirection, hasSnapPoints],
+	);
+
+	const scrollConfig = useSharedValue<ScrollConfig | null>(null);
+	const childDirectionClaims = useSharedValue<DirectionClaimMap>(NO_CLAIMS);
+
+	useRegisterDirectionClaims(
+		ancestorContext,
+		claimedDirections,
+		routeKey,
+		isIsolated,
+		isTopMostScreen,
+	);
+
+	const { panGesture, panGestureRef, gestureAnimationValues } =
+		useBuildGestures({
+			scrollConfig,
+			ancestorContext,
+			claimedDirections,
+			childDirectionClaims,
+			isIsolated,
+		});
+
+	const value = useMemo<GestureContextType>(
+		() => ({
+			panGesture,
+			panGestureRef,
+			scrollConfig,
+			gestureAnimationValues,
+			ancestorContext,
+			gestureEnabled,
+			isIsolated,
+			claimedDirections,
+			childDirectionClaims,
+		}),
+		[
+			panGesture,
+			panGestureRef,
+			scrollConfig,
+			gestureAnimationValues,
+			ancestorContext,
+			gestureEnabled,
+			isIsolated,
+			claimedDirections,
+			childDirectionClaims,
+		],
+	);
+
+	return {
+		value,
+		children,
+	};
+});

package/src/shared/{hooks/gestures/use-screen-gesture-handlers.ts → providers/gestures/handlers/use-handlers.ts}

@@ -1,5 +1,4 @@
 import { useMemo } from "react";
-import { useWindowDimensions } from "react-native";
 import type {
 	GestureStateChangeEvent,
 	GestureTouchEvent,
@@ -8,45 +7,61 @@ import type {
 } from "react-native-gesture-handler";
 import type { GestureStateManagerType } from "react-native-gesture-handler/lib/typescript/handlers/gestures/gestureStateManager";
 import { type SharedValue, useSharedValue } from "react-native-reanimated";
-import { DefaultSnapSpec } from "../../configs/specs";
+import { DefaultSnapSpec } from "../../../configs/specs";
 import {
 	DEFAULT_GESTURE_ACTIVATION_AREA,
 	DEFAULT_GESTURE_DIRECTION,
 	DEFAULT_GESTURE_DRIVES_PROGRESS,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+	DEFAULT_GESTURE_SNAP_LOCKED,
+	DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	DEFAULT_GESTURE_VELOCITY_IMPACT,
 	EPSILON,
 	FALSE,
-	GESTURE_VELOCITY_IMPACT,
-	SNAP_VELOCITY_IMPACT,
 	TRUE,
-} from "../../constants";
-import type {
-	DirectionClaimMap,
-	GestureContextType,
-	ScrollConfig,
-} from "../../providers/gestures.provider";
-import { useKeys } from "../../providers/screen/keys.provider";
-import { AnimationStore } from "../../stores/animation.store";
-import { GestureStore } from "../../stores/gesture.store";
-import { GestureOffsetState } from "../../types/gesture.types";
+} from "../../../constants";
+import useStableCallbackValue from "../../../hooks/use-stable-callback-value";
+import { AnimationStore } from "../../../stores/animation.store";
+import { GestureStore } from "../../../stores/gesture.store";
+import { GestureOffsetState } from "../../../types/gesture.types";
 import type {
 	ClaimedDirections,
 	Direction,
 	DirectionOwnership,
-} from "../../types/ownership.types";
-import { animateToProgress } from "../../utils/animation/animate-to-progress";
+} from "../../../types/ownership.types";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+import type { EffectiveSnapPointsResult } from "../../../utils/gesture/validate-snap-points";
+import { useDescriptors } from "../../screen/descriptors";
+import { useViewportContext } from "../../viewport.provider";
 import {
 	applyOffsetRules,
 	checkScrollBoundary,
-} from "../../utils/gesture/check-gesture-activation";
-import { determineDismissal } from "../../utils/gesture/determine-dismissal";
-import { determineSnapTarget } from "../../utils/gesture/determine-snap-target";
-import { mapGestureToProgress } from "../../utils/gesture/map-gesture-to-progress";
-import { resetGestureValues } from "../../utils/gesture/reset-gesture-values";
-import { shouldDeferToChildClaim } from "../../utils/gesture/should-defer-to-child-claim";
-import { validateSnapPoints } from "../../utils/gesture/validate-snap-points";
-import { velocity } from "../../utils/gesture/velocity";
-import { logger } from "../../utils/logger";
-import useStableCallbackValue from "../use-stable-callback-value";
+} from "../helpers/gesture-activation";
+import { shouldDeferToChildClaim } from "../helpers/gesture-claims";
+import {
+	clampVelocity,
+	getSnapAxis,
+	isExpandGestureForDirection,
+	resolveGestureDirections,
+	warnOnSnapDirectionArray,
+} from "../helpers/gesture-directions";
+import {
+	calculateProgressSpringVelocity,
+	mapGestureToProgress,
+	normalizeGestureTranslation,
+	normalizeVelocity,
+} from "../helpers/gesture-physics";
+import { resetGestureValues } from "../helpers/gesture-reset";
+import {
+	determineDismissal,
+	determineSnapTarget,
+} from "../helpers/gesture-targets";
+import type {
+	DirectionClaimMap,
+	GestureContextType,
+	ScrollConfig,
+} from "../types";
 
 interface UseScreenGestureHandlersProps {
 	scrollConfig: SharedValue<ScrollConfig | null>;
@@ -57,6 +72,7 @@ interface UseScreenGestureHandlersProps {
 	claimedDirections: ClaimedDirections;
 	ancestorContext: GestureContextType | null | undefined;
 	childDirectionClaims: SharedValue<DirectionClaimMap>;
+	effectiveSnapPoints: EffectiveSnapPointsResult;
 }
 
 /**
@@ -104,113 +120,47 @@ interface UseScreenGestureHandlersProps {
  * (e.g., vertical sheet claims vertical AND vertical-inverted). This allows
  * expand (drag up) and collapse/dismiss (drag down) gestures.
  */
-export const useScreenGestureHandlers = ({
+export const useHandlers = ({
 	scrollConfig,
 	ancestorIsDismissing,
 	canDismiss,
 	handleDismiss,
 	ownershipStatus,
 	childDirectionClaims,
+	effectiveSnapPoints,
 }: UseScreenGestureHandlersProps) => {
-	const dimensions = useWindowDimensions();
-	const { current } = useKeys();
-
-	const animations = AnimationStore.getAll(current.route.key);
-	const gestureAnimationValues = GestureStore.getRouteGestures(
-		current.route.key,
-	);
+	const { current } = useDescriptors();
 
 	const {
 		gestureDirection = DEFAULT_GESTURE_DIRECTION,
 		gestureDrivesProgress = DEFAULT_GESTURE_DRIVES_PROGRESS,
-		gestureVelocityImpact = GESTURE_VELOCITY_IMPACT,
-		snapVelocityImpact = SNAP_VELOCITY_IMPACT,
+		gestureVelocityImpact = DEFAULT_GESTURE_VELOCITY_IMPACT,
+		snapVelocityImpact = DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+		gestureReleaseVelocityScale = DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+		gestureReleaseVelocityMax = DEFAULT_GESTURE_RELEASE_VELOCITY_MAX,
 		gestureActivationArea = DEFAULT_GESTURE_ACTIVATION_AREA,
+		gestureSnapLocked = DEFAULT_GESTURE_SNAP_LOCKED,
+		expandViaScrollView = true,
 		gestureResponseDistance,
 		transitionSpec,
-		snapPoints: rawSnapPoints,
-		expandViaScrollView = true,
-		gestureSnapLocked = false,
 	} = current.options;
 
-	const { hasSnapPoints, snapPoints, minSnapPoint, maxSnapPoint } = useMemo(
-		() => validateSnapPoints({ snapPoints: rawSnapPoints, canDismiss }),
-		[rawSnapPoints, canDismiss],
+	const { dimensions } = useViewportContext();
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getRouteAnimations(current.route.key);
+	const gestureAnimationValues = GestureStore.getRouteGestures(
+		current.route.key,
 	);
 
-	const directions = useMemo(() => {
-		if (hasSnapPoints && Array.isArray(gestureDirection)) {
-			/**
-			 * Unsure if this behavior will change in the future, as I cannot find a use case as to why
-			 * you would want multiple gesture dismisals for a sheet.
-			 *
-			 * e.g. When defining a snap point with a gesture of vertical ( default ), the system
-			 * assumes that the inverse ( vertical-inverted ), will grow the sheet.
-			 */
-			logger.warn(
-				`gestureDirection array is not supported with snapPoints. ` +
-					`Only the first direction "${gestureDirection[0]}" will be used. ` +
-					`Snap points define a single axis of movement, so only one gesture direction is needed.`,
-			);
-		}
+	const { hasSnapPoints, snapPoints, minSnapPoint, maxSnapPoint } =
+		effectiveSnapPoints;
 
-		// When snap points are defined, use only the first direction from the array
-		const effectiveDirection = hasSnapPoints
-			? Array.isArray(gestureDirection)
-				? gestureDirection[0]
-				: gestureDirection
-			: gestureDirection;
-
-		const directionsArray = Array.isArray(effectiveDirection)
-			? effectiveDirection
-			: [effectiveDirection];
-
-		const isBidirectional = directionsArray.includes("bidirectional");
-
-		const hasHorizontalDirection =
-			directionsArray.includes("horizontal") ||
-			directionsArray.includes("horizontal-inverted");
-
-		const isSnapAxisInverted = hasHorizontalDirection
-			? directionsArray.includes("horizontal-inverted") &&
-				!directionsArray.includes("horizontal")
-			: directionsArray.includes("vertical-inverted") &&
-				!directionsArray.includes("vertical");
-
-		const enableBothVertical =
-			isBidirectional || (hasSnapPoints && !hasHorizontalDirection);
-		const enableBothHorizontal =
-			isBidirectional || (hasSnapPoints && hasHorizontalDirection);
-
-		return {
-			vertical: directionsArray.includes("vertical") || enableBothVertical,
-			verticalInverted:
-				directionsArray.includes("vertical-inverted") || enableBothVertical,
-			horizontal:
-				directionsArray.includes("horizontal") || enableBothHorizontal,
-			horizontalInverted:
-				directionsArray.includes("horizontal-inverted") || enableBothHorizontal,
-			snapAxisInverted: hasSnapPoints && isSnapAxisInverted,
-		};
+	const directions = useMemo(() => {
+		warnOnSnapDirectionArray({ gestureDirection, hasSnapPoints });
+		return resolveGestureDirections({ gestureDirection, hasSnapPoints });
 	}, [gestureDirection, hasSnapPoints]);
 
-	const snapAxis =
-		directions.horizontal || directions.horizontalInverted
-			? "horizontal"
-			: "vertical";
-
-	const isExpandGesture = (swipeDirection: Direction): boolean => {
-		"worklet";
-		if (snapAxis === "horizontal") {
-			return directions.snapAxisInverted
-				? swipeDirection === "horizontal"
-				: swipeDirection === "horizontal-inverted";
-		}
-
-		return directions.snapAxisInverted
-			? swipeDirection === "vertical"
-			: swipeDirection === "vertical-inverted";
-	};
+	const snapAxis = getSnapAxis(directions);
 
 	const initialTouch = useSharedValue({ x: 0, y: 0 });
 	const gestureOffsetState = useSharedValue<GestureOffsetState>(
@@ -226,8 +176,6 @@ export const useScreenGestureHandlers = ({
 		gestureOffsetState.value = GestureOffsetState.PENDING;
 	});
 
-	const routeKey = current.route.key;
-
 	const onTouchesMove = useStableCallbackValue(
 		(e: GestureTouchEvent, manager: GestureStateManagerType) => {
 			"worklet";
@@ -258,7 +206,7 @@ export const useScreenGestureHandlers = ({
 				return;
 			}
 
-			if (gestureAnimationValues.isDragging?.value) {
+			if (gestureAnimationValues.dragging?.value) {
 				manager.activate();
 				return;
 			}
@@ -296,14 +244,18 @@ export const useScreenGestureHandlers = ({
 			if (
 				hasSnapPoints &&
 				gestureSnapLocked &&
-				isExpandGesture(swipeDirection)
+				isExpandGestureForDirection(
+					swipeDirection,
+					snapAxis,
+					directions.snapAxisInverted ?? false,
+				)
 			) {
 				manager.fail();
 				return;
 			}
 
 			// Snap sheets can interrupt their own animation; non-snap cannot
-			if (!hasSnapPoints && gestureAnimationValues.isDismissing?.value) {
+			if (!hasSnapPoints && gestureAnimationValues.dismissing?.value) {
 				return;
 			}
 
@@ -325,7 +277,13 @@ export const useScreenGestureHandlers = ({
 
 				// Step 7: Expand check for snap sheets
 				if (hasSnapPoints) {
-					if (isExpandGesture(swipeDirection)) {
+					if (
+						isExpandGestureForDirection(
+							swipeDirection,
+							snapAxis,
+							directions.snapAxisInverted ?? false,
+						)
+					) {
 						if (!expandViaScrollView) {
 							manager.fail();
 							return;
@@ -372,8 +330,8 @@ export const useScreenGestureHandlers = ({
 			lockedSnapPoint.value = maxSnapPoint;
 		}
 
-		gestureAnimationValues.isDragging.value = TRUE;
-		gestureAnimationValues.isDismissing.value = FALSE;
+		gestureAnimationValues.dragging.value = TRUE;
+		gestureAnimationValues.dismissing.value = FALSE;
 		gestureStartProgress.value = animations.progress.value;
 		animations.animating.value = TRUE;
 	});
@@ -387,11 +345,11 @@ export const useScreenGestureHandlers = ({
 
 			gestureAnimationValues.x.value = translationX;
 			gestureAnimationValues.y.value = translationY;
-			gestureAnimationValues.normalizedX.value = velocity.normalizeTranslation(
+			gestureAnimationValues.normX.value = normalizeGestureTranslation(
 				translationX,
 				width,
 			);
-			gestureAnimationValues.normalizedY.value = velocity.normalizeTranslation(
+			gestureAnimationValues.normY.value = normalizeGestureTranslation(
 				translationY,
 				height,
 			);
@@ -502,11 +460,29 @@ export const useScreenGestureHandlers = ({
 					shouldDismiss,
 					event,
 					dimensions,
+					gestureReleaseVelocityScale,
+					gestureReleaseVelocityMax,
 				});
 
-				const velocitySign = directions.snapAxisInverted ? 1 : -1;
+				const snapDirection = Math.sign(
+					targetProgress - animations.progress.value,
+				);
+
+				const normalizedAxisVelocity = Math.abs(
+					normalizeVelocity(
+						axisVelocity,
+						axisDimension,
+						gestureReleaseVelocityMax,
+					),
+				);
+
+				const signedSnapVelocity =
+					snapDirection * normalizedAxisVelocity * gestureReleaseVelocityScale;
+
 				const initialVelocity =
-					velocitySign * velocity.normalize(axisVelocity, axisDimension);
+					snapDirection === 0
+						? 0
+						: clampVelocity(signedSnapVelocity, gestureReleaseVelocityMax);
 
 				animateToProgress({
 					target: targetProgress,
@@ -532,9 +508,11 @@ export const useScreenGestureHandlers = ({
 					shouldDismiss,
 					event,
 					dimensions,
+					gestureReleaseVelocityScale,
+					gestureReleaseVelocityMax,
 				});
 
-				const initialVelocity = velocity.calculateProgressVelocity({
+				const initialVelocity = calculateProgressSpringVelocity({
 					animations,
 					shouldDismiss,
 					event,
@@ -542,12 +520,17 @@ export const useScreenGestureHandlers = ({
 					directions,
 				});
 
+				const scaledInitialVelocity = clampVelocity(
+					initialVelocity * gestureReleaseVelocityScale,
+					gestureReleaseVelocityMax,
+				);
+
 				animateToProgress({
 					target: targetProgress,
 					onAnimationFinish: shouldDismiss ? handleDismiss : undefined,
 					spec: transitionSpec,
 					animations,
-					initialVelocity,
+					initialVelocity: scaledInitialVelocity,
 				});
 			}
 		},

package/src/shared/{utils/gesture/check-gesture-activation.ts → providers/gestures/helpers/gesture-activation.ts}

@@ -1,27 +1,20 @@
 import type { GestureStateManagerType } from "react-native-gesture-handler/lib/typescript/handlers/gestures/gestureStateManager";
 import type { SharedValue } from "react-native-reanimated";
-import type { ScrollConfig } from "../../providers/gestures.provider";
+import type { GestureDirections } from "../../../types/gesture.types";
 import {
 	type ActivationArea,
 	type GestureActivationArea,
 	GestureOffsetState,
 	type SideActivation,
-} from "../../types/gesture.types";
-import type { Direction } from "../../types/ownership.types";
-import type { Layout } from "../../types/screen.types";
-
-type Directions = {
-	vertical: boolean;
-	verticalInverted: boolean;
-	horizontal: boolean;
-	horizontalInverted: boolean;
-	snapAxisInverted?: boolean;
-};
+} from "../../../types/gesture.types";
+import type { Direction } from "../../../types/ownership.types";
+import type { Layout } from "../../../types/screen.types";
+import type { ScrollConfig } from "../types";
 
 interface CheckGestureActivationProps {
 	initialTouch: { x: number; y: number };
 	touch: { x: number; y: number };
-	directions: Directions;
+	directions: GestureDirections;
 	manager?: GestureStateManagerType;
 	gestureOffsetState: SharedValue<GestureOffsetState>;
 	activationArea?: GestureActivationArea;

package/src/shared/{utils/gesture/should-defer-to-child-claim.ts → providers/gestures/helpers/gesture-claims.ts}

@@ -1,4 +1,4 @@
-import type { DirectionClaim } from "../../providers/gestures.provider";
+import type { DirectionClaim } from "../types";
 
 /**
  * Determines if the parent gesture should defer to a child's claim on a direction.