react-native-screen-transitions 3.3.0-rc.3 → 3.3.0

package/src/shared/components/screen-container.tsx

@@ -25,6 +25,8 @@ export const ScreenContainer = memo(({ children }: Props) => {
 	const { pointerEvents, backdropBehavior } = useBackdropPointerEvents();
 	const gestureContext = useGestureContext();
 
+	const BackdropComponent = current.options.backdropComponent;
+
 	const isBackdropActive =
 		backdropBehavior === "dismiss" || backdropBehavior === "collapse";
 
@@ -101,15 +103,19 @@ export const ScreenContainer = memo(({ children }: Props) => {
 
 	return (
 		<View style={styles.container} pointerEvents={pointerEvents}>
-			<Pressable
-				style={StyleSheet.absoluteFillObject}
-				pointerEvents={isBackdropActive ? "auto" : "none"}
-				onPress={isBackdropActive ? handleBackdropPress : undefined}
-			>
-				<Animated.View
-					style={[StyleSheet.absoluteFillObject, animatedBackdropStyle]}
-				/>
-			</Pressable>
+			{BackdropComponent ? (
+				<BackdropComponent />
+			) : (
+				<Pressable
+					style={StyleSheet.absoluteFillObject}
+					pointerEvents={isBackdropActive ? "auto" : "none"}
+					onPress={isBackdropActive ? handleBackdropPress : undefined}
+				>
+					<Animated.View
+						style={[StyleSheet.absoluteFillObject, animatedBackdropStyle]}
+					/>
+				</Pressable>
+			)}
 			<GestureDetector gesture={gestureContext!.panGesture}>
 				<Animated.View
 					style={[styles.content, animatedContentStyle]}

package/src/shared/hooks/gestures/use-build-gestures.tsx

@@ -12,6 +12,7 @@ import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 import type { ClaimedDirections, Direction } from "../../types/ownership.types";
 import { claimsAnyDirection } from "../../utils/gesture/compute-claimed-directions";
 import { resolveOwnership } from "../../utils/gesture/resolve-ownership";
+import { validateSnapPoints } from "../../utils/gesture/validate-snap-points";
 import { useScreenGestureHandlers } from "./use-screen-gesture-handlers";
 
 const DIRECTIONS: Direction[] = [
@@ -94,7 +95,10 @@ export const useBuildGestures = ({
 	const canDismiss = Boolean(
 		isFirstScreen ? false : current.options.gestureEnabled,
 	);
-	const hasSnapPoints = Array.isArray(snapPoints) && snapPoints.length > 0;
+	const { hasSnapPoints } = useMemo(
+		() => validateSnapPoints({ snapPoints, canDismiss }),
+		[snapPoints, canDismiss],
+	);
 	const gestureEnabled = canDismiss || hasSnapPoints;
 
 	const ownershipStatus = useMemo(

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

@@ -123,18 +123,22 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		const setIsTouched = () => {
 			"worklet";
 			for (const scrollConfig of scrollConfigs) {
-				if (scrollConfig.value) {
-					scrollConfig.value = { ...scrollConfig.value, isTouched: true };
-				}
+				scrollConfig.modify((v) => {
+					"worklet";
+					if (v) v.isTouched = true;
+					return v;
+				});
 			}
 		};
 
 		const clearIsTouched = () => {
 			"worklet";
 			for (const scrollConfig of scrollConfigs) {
-				if (scrollConfig.value) {
-					scrollConfig.value = { ...scrollConfig.value, isTouched: false };
-				}
+				scrollConfig.modify((v) => {
+					"worklet";
+					if (v) v.isTouched = false;
+					return v;
+				});
 			}
 		};
 

package/src/shared/hooks/lifecycle/use-close-transition.ts

@@ -47,9 +47,12 @@ const useManagedClose = ({
 	const transitionSpec = current.options.transitionSpec;
 
 	useAnimatedReaction(
-		() => closingRouteKeysShared.value,
-		(keys) => {
-			if (!keys?.includes(routeKey)) return;
+		() => {
+			const keys = closingRouteKeysShared.value;
+			return keys?.includes(routeKey) ?? false;
+		},
+		(isClosing, wasClosing) => {
+			if (!isClosing || wasClosing) return;
 
 			runOnJS(activate)();
 			animateToProgress({

package/src/shared/hooks/navigation/use-optimistic-focused-index.ts

@@ -0,0 +1,19 @@
+import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
+import { useSharedValueState } from "../reanimated/use-shared-value-state";
+
+/**
+ * Returns a JS-focused index derived from optimisticFocusedIndex and clamped to route count.
+ * Keeps callers aligned on focus behavior during transitions with closing screens.
+ */
+export function useOptimisticFocusedIndex(
+	optimisticFocusedIndex: DerivedValue<number>,
+	routeCount: number,
+): number {
+	return useSharedValueState(
+		useDerivedValue(() => {
+			const globalIndex = optimisticFocusedIndex.get();
+			if (routeCount <= 0) return 0;
+			return Math.max(0, Math.min(globalIndex, routeCount - 1));
+		}),
+	);
+}

package/src/shared/hooks/navigation/use-screen-state.tsx

@@ -1,6 +1,5 @@
 import type { Route } from "@react-navigation/native";
 import { useCallback, useMemo } from "react";
-import { useDerivedValue } from "react-native-reanimated";
 import { snapDescriptorToIndex } from "../../animation/snap-to";
 import {
 	type BaseDescriptor,
@@ -8,7 +7,7 @@ import {
 } from "../../providers/screen/keys.provider";
 import type { ScreenTransitionConfig } from "../../types/screen.types";
 import type { BaseStackNavigation } from "../../types/stack.types";
-import { useSharedValueState } from "../reanimated/use-shared-value-state";
+import { useOptimisticFocusedIndex } from "./use-optimistic-focused-index";
 import { type StackContextValue, useStack } from "./use-stack";
 
 export interface ScreenState<
@@ -74,11 +73,9 @@ export function useScreenState<
 		[routeKeys, current.route.key],
 	);
 
-	const focusedIndex = useSharedValueState(
-		useDerivedValue(() => {
-			const globalIndex = optimisticFocusedIndex.get();
-			return Math.max(0, Math.min(globalIndex, routeKeys.length - 1));
-		}),
+	const focusedIndex = useOptimisticFocusedIndex(
+		optimisticFocusedIndex,
+		routeKeys.length,
 	);
 
 	const focusedScene = useMemo(() => {

package/src/shared/hooks/reanimated/use-shared-value-state.ts

@@ -26,7 +26,10 @@ export function useSharedValueState<T>(sharedValue: SharedValue<T>): T {
 
 	useAnimatedReaction(
 		() => sharedValue.value,
-		(value) => runOnJS(setState)(value),
+		(value, previousValue) => {
+			if (Object.is(value, previousValue)) return;
+			runOnJS(setState)(value);
+		},
 	);
 
 	return state;

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

@@ -22,6 +22,7 @@ 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 { validateSnapPoints } from "../utils/gesture/validate-snap-points";
 import { useKeys } from "./screen/keys.provider";
 import { useStackCoreContext } from "./stack/core.provider";
 
@@ -159,30 +160,43 @@ export const {
 } = createProvider("ScreenGesture", { guarded: false })<
 	ScreenGestureProviderProps,
 	GestureContextType
->(({ children }) => {
+>(({ children }): { value: GestureContextType; children: React.ReactNode } => {
 	const { current } = useKeys();
 	const { flags } = useStackCoreContext();
-	const ancestorContext = useGestureContext();
-
-	const hasGestures = current.options.gestureEnabled === true;
+	const ancestorContext: GestureContextType | null = useGestureContext();
 	const isIsolated = flags.STACK_TYPE === StackType.COMPONENT;
+	const routeKey = current.route.key;
 
-	const hasSnapPoints =
-		Array.isArray(current.options.snapPoints) &&
-		current.options.snapPoints.length > 0;
+	const isFirstScreen = useNavigationState((state) => {
+		const index = state.routes.findIndex((route) => route.key === routeKey);
+		return index === 0;
+	});
+
+	const canDismiss = Boolean(
+		isFirstScreen ? 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(
-				hasGestures,
+				gestureEnabled,
 				current.options.gestureDirection,
 				hasSnapPoints,
 			),
-		[hasGestures, current.options.gestureDirection, hasSnapPoints],
+		[gestureEnabled, current.options.gestureDirection, hasSnapPoints],
 	);
 
-	const routeKey = current.route.key;
-
 	// Check if this screen is the current (topmost) route in its navigator
 	const isCurrentRoute = useNavigationState(
 		(state) => state.routes[state.index]?.key === routeKey,
@@ -208,17 +222,30 @@ export const {
 			isIsolated,
 		});
 
-	const value: GestureContextType = {
-		panGesture,
-		panGestureRef,
-		scrollConfig,
-		gestureAnimationValues,
-		ancestorContext,
-		gestureEnabled: hasGestures,
-		isIsolated,
-		claimedDirections,
-		childDirectionClaims,
-	};
+	const value = useMemo<GestureContextType>(
+		() => ({
+			panGesture,
+			panGestureRef,
+			scrollConfig,
+			gestureAnimationValues,
+			ancestorContext,
+			gestureEnabled,
+			isIsolated,
+			claimedDirections,
+			childDirectionClaims,
+		}),
+		[
+			panGesture,
+			panGestureRef,
+			scrollConfig,
+			gestureAnimationValues,
+			ancestorContext,
+			gestureEnabled,
+			isIsolated,
+			claimedDirections,
+			childDirectionClaims,
+		],
+	);
 
 	return {
 		value,

package/src/shared/providers/layout-anchor.provider.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { type ReactNode, useCallback, useMemo } from "react";
 import { useWindowDimensions, type View } from "react-native";
 import {
 	type AnimatedRef,
@@ -44,35 +44,38 @@ const { LayoutAnchorProvider, useLayoutAnchorContext } = createProvider(
 	({ anchorRef, children }) => {
 		const { width: screenWidth, height: screenHeight } = useWindowDimensions();
 
-		const correctMeasurement = (
-			measured: MeasuredDimensions,
-		): MeasuredDimensions => {
-			"worklet";
-			const anchor = measure(anchorRef);
-			if (!anchor) return measured;
+		const correctMeasurement = useCallback(
+			(measured: MeasuredDimensions): MeasuredDimensions => {
+				"worklet";
+				const anchor = measure(anchorRef);
+				if (!anchor) return measured;
 
-			// Compute scale factor by comparing anchor size to expected screen size.
-			// Anchor should be full-screen (absoluteFill), so any difference is from scale.
-			const scaleX = anchor.width > 0 ? anchor.width / screenWidth : 1;
-			const scaleY = anchor.height > 0 ? anchor.height / screenHeight : 1;
+				// Compute scale factor by comparing anchor size to expected screen size.
+				// Anchor should be full-screen (absoluteFill), so any difference is from scale.
+				const scaleX = anchor.width > 0 ? anchor.width / screenWidth : 1;
+				const scaleY = anchor.height > 0 ? anchor.height / screenHeight : 1;
 
-			// Get element position relative to anchor (removes translation)
-			const relativeX = measured.pageX - anchor.pageX;
-			const relativeY = measured.pageY - anchor.pageY;
+				// Get element position relative to anchor (removes translation)
+				const relativeX = measured.pageX - anchor.pageX;
+				const relativeY = measured.pageY - anchor.pageY;
 
-			// Reverse scale: divide relative position and dimensions by scale factor
-			return {
-				x: measured.x,
-				y: measured.y,
-				width: scaleX !== 1 ? measured.width / scaleX : measured.width,
-				height: scaleY !== 1 ? measured.height / scaleY : measured.height,
-				pageX: scaleX !== 1 ? relativeX / scaleX : relativeX,
-				pageY: scaleY !== 1 ? relativeY / scaleY : relativeY,
-			};
-		};
+				// Reverse scale: divide relative position and dimensions by scale factor
+				return {
+					x: measured.x,
+					y: measured.y,
+					width: scaleX !== 1 ? measured.width / scaleX : measured.width,
+					height: scaleY !== 1 ? measured.height / scaleY : measured.height,
+					pageX: scaleX !== 1 ? relativeX / scaleX : relativeX,
+					pageY: scaleY !== 1 ? relativeY / scaleY : relativeY,
+				};
+			},
+			[anchorRef, screenWidth, screenHeight],
+		);
+
+		const value = useMemo(() => ({ correctMeasurement }), [correctMeasurement]);
 
 		return {
-			value: { correctMeasurement },
+			value,
 			children,
 		};
 	},

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

@@ -37,7 +37,7 @@ export function ScreenStylesProvider({ children }: Props) {
 	const stylesMap = useDerivedValue<TransitionInterpolatedStyle>(() => {
 		"worklet";
 		const props = screenInterpolatorProps.value;
-		const { current, next, progress, stackProgress } = props;
+		const { current, next, progress } = props;
 		const isDragging = current.gesture.isDragging;
 		const isNextClosing = !!next?.closing;
 
@@ -51,9 +51,6 @@ export function ScreenStylesProvider({ children }: Props) {
 
 		const isInGestureMode = isDragging || isGesturingDuringCloseAnimation.value;
 
-		const hasPushedScreenWhileClosing =
-			!isInGestureMode && isNextClosing && stackProgress > progress;
-
 		// Select interpolator
 		//  - If in gesture mode, use current screen's interpolator since we're driving
 		//    the animation from this screen (dragging back to dismiss next).
@@ -65,7 +62,6 @@ export function ScreenStylesProvider({ children }: Props) {
 
 		// Build effective props with corrected progress
 		//  - Gesture mode: use current.progress only (avoids jumps during drag)
-		//  - Pushed while closing: use stackProgress (includes new screen)
 		//  - Normal: use derived progress as-is
 
 		let effectiveProgress = progress;
@@ -74,8 +70,6 @@ export function ScreenStylesProvider({ children }: Props) {
 		if (isInGestureMode) {
 			effectiveProgress = current.progress;
 			effectiveNext = undefined;
-		} else if (hasPushedScreenWhileClosing) {
-			effectiveProgress = stackProgress;
 		}
 
 		try {

package/src/shared/providers/stack/direct.provider.tsx

@@ -20,6 +20,7 @@ import {
 	type AnimationStoreMap,
 } from "../../stores/animation.store";
 import { HistoryStore } from "../../stores/history.store";
+import { isFloatOverlayVisible } from "../../utils/overlay/visibility";
 import { useStackCoreContext } from "./core.provider";
 
 export interface DirectStackScene {
@@ -116,8 +117,7 @@ function useDirectStackValue(
 				const options = descriptor.options;
 				if (
 					options?.enableTransitions === true &&
-					options?.overlayMode === "float" &&
-					options?.overlayShown === true
+					isFloatOverlayVisible(options)
 				) {
 					shouldShowFloatOverlay = true;
 				}

package/src/shared/providers/stack/managed.provider.tsx

@@ -22,6 +22,7 @@ import type {
 	BaseStackScene,
 	BaseStackState,
 } from "../../types/stack.types";
+import { isFloatOverlayVisible } from "../../utils/overlay/visibility";
 import { useStackCoreContext } from "./core.provider";
 import { useLocalRoutes } from "./helpers/use-local-routes";
 
@@ -115,8 +116,7 @@ function useManagedStackValue<
 			animationMaps[i] = AnimationStore.getAll(route.key);
 
 			if (!shouldShowFloatOverlay) {
-				shouldShowFloatOverlay =
-					options?.overlayMode === "float" && options?.overlayShown === true;
+				shouldShowFloatOverlay = isFloatOverlayVisible(options);
 			}
 
 			if (!stopLimit) {

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

@@ -77,7 +77,10 @@ export type ScreenTransitionConfig = {
 	transitionSpec?: TransitionSpec;
 
 	/**
-	 * Whether the gesture is enabled.
+	 * Controls whether swipe-to-dismiss is enabled.
+	 *
+	 * For screens with `snapPoints`, gesture-driven snapping between non-dismiss
+	 * snap points remains available even when this is `false`.
 	 */
 	gestureEnabled?: boolean;
 
@@ -210,4 +213,17 @@ export type ScreenTransitionConfig = {
 	 * @default 'block' (or 'passthrough' for component stacks)
 	 */
 	backdropBehavior?: "block" | "passthrough" | "dismiss" | "collapse";
+
+	/**
+	 * Custom component to render as the backdrop layer.
+	 * When provided, replaces the default backdrop entirely — including press handling.
+	 *
+	 * Use `useScreenAnimation()` inside the component to access animation values.
+	 * Use your navigation method of choice (e.g. `router.back()`) to handle dismissal.
+	 *
+	 * `backdropBehavior` still controls container-level pointer events when this is set.
+	 *
+	 * @default undefined
+	 */
+	backdropComponent?: React.FC;
 };

package/src/shared/utils/gesture/determine-snap-target.ts

@@ -43,10 +43,21 @@ export function determineSnapTarget({
 	// Project where we'd end up with velocity
 	const projectedProgress = currentProgress - velocityInProgress;
 
+	const sanitizedSnapPoints = snapPoints.filter((point) =>
+		canDismiss ? Number.isFinite(point) : Number.isFinite(point) && point > 0,
+	);
+
 	// Build all possible targets: dismiss (0) only if allowed, plus all snap points
-	const allTargets = canDismiss
-		? [0, ...snapPoints].sort((a, b) => a - b)
-		: [...snapPoints].sort((a, b) => a - b);
+	const allTargets = Array.from(
+		new Set(canDismiss ? [0, ...sanitizedSnapPoints] : sanitizedSnapPoints),
+	).sort((a, b) => a - b);
+
+	if (allTargets.length === 0) {
+		return {
+			targetProgress: currentProgress,
+			shouldDismiss: false,
+		};
+	}
 
 	// Find the target whose zone contains the projected progress
 	// Zones are split at midpoints between adjacent targets
@@ -74,6 +85,6 @@ export function determineSnapTarget({
 
 	return {
 		targetProgress,
-		shouldDismiss: targetProgress === 0,
+		shouldDismiss: canDismiss && targetProgress === 0,
 	};
 }

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

@@ -22,7 +22,17 @@ export function findCollapseTarget(
 ): FindCollapseTargetResult {
 	"worklet";
 
-	const sorted = [...snapPoints].sort((a, b) => a - b);
+	const normalized = snapPoints.filter((point) =>
+		canDismiss ? Number.isFinite(point) : Number.isFinite(point) && point > 0,
+	);
+
+	if (normalized.length === 0) {
+		return canDismiss
+			? { target: 0, shouldDismiss: true }
+			: { target: currentProgress, shouldDismiss: false };
+	}
+
+	const sorted = [...normalized].sort((a, b) => a - b);
 	const minSnap = sorted[0];
 
 	// Find next lower snap point

package/src/shared/utils/gesture/validate-snap-points.ts

@@ -14,7 +14,7 @@ export const validateSnapPoints = ({
 	snapPoints,
 	canDismiss,
 }: ValidateSnapPointsOptions): ValidateSnapPointsResult => {
-	if (!snapPoints) {
+	if (!snapPoints || snapPoints.length === 0) {
 		return {
 			hasSnapPoints: false,
 			snapPoints: [],
@@ -23,7 +23,20 @@ export const validateSnapPoints = ({
 		};
 	}
 
-	const sortedSnaps = snapPoints.slice().sort((a, b) => a - b);
+	const normalizedSnaps = snapPoints.filter((point) =>
+		canDismiss ? Number.isFinite(point) : Number.isFinite(point) && point > 0,
+	);
+
+	if (normalizedSnaps.length === 0) {
+		return {
+			hasSnapPoints: false,
+			snapPoints: [],
+			minSnapPoint: -1,
+			maxSnapPoint: -1,
+		};
+	}
+
+	const sortedSnaps = normalizedSnaps.slice().sort((a, b) => a - b);
 	// Clamp to snap point bounds (dismiss at 0 only if allowed)
 	const minProgress = canDismiss ? 0 : sortedSnaps[0];
 	const maxProgress = sortedSnaps[sortedSnaps.length - 1];

package/src/shared/utils/overlay/visibility.ts

@@ -0,0 +1,23 @@
+import type { OverlayMode } from "../../types/overlay.types";
+
+type OverlayOptionsLike = {
+	overlay?: unknown;
+	overlayMode?: OverlayMode;
+	overlayShown?: boolean;
+};
+
+export const isOverlayVisible = (options?: OverlayOptionsLike): boolean => {
+	return Boolean(options?.overlay) && options?.overlayShown !== false;
+};
+
+export const isFloatOverlayVisible = (
+	options?: OverlayOptionsLike,
+): boolean => {
+	return isOverlayVisible(options) && options?.overlayMode !== "screen";
+};
+
+export const isScreenOverlayVisible = (
+	options?: OverlayOptionsLike,
+): boolean => {
+	return isOverlayVisible(options) && options?.overlayMode === "screen";
+};