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

package/src/shared/components/screen-container/helpers/find-collapse-target.ts

@@ -1,5 +1,5 @@
 import { EPSILON } from "../../../constants";
-import { sanitizeSnapPoints } from "../../../providers/screen/gestures/helpers/validate-snap-points";
+import { sanitizeSnapPoints } from "../../../providers/screen/gestures/shared/snap-points";
 
 interface FindCollapseTargetResult {
 	target: number;
@@ -31,14 +31,25 @@ export function findCollapseTarget(
 			: { target: currentProgress, shouldDismiss: false };
 	}
 
-	const sorted = [...normalized].sort((a, b) => a - b);
-	const minSnap = sorted[0];
+	let minSnap = normalized[0];
+	let nextLowerSnap: number | null = null;
 
-	// 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 };
+	for (let i = 0; i < normalized.length; i++) {
+		const snap = normalized[i];
+		if (snap < minSnap) {
+			minSnap = snap;
 		}
+
+		if (
+			snap < currentProgress - EPSILON &&
+			(nextLowerSnap === null || snap > nextLowerSnap)
+		) {
+			nextLowerSnap = snap;
+		}
+	}
+
+	if (nextLowerSnap !== null) {
+		return { target: nextLowerSnap, shouldDismiss: false };
 	}
 
 	// At or below min snap → dismiss if allowed

package/src/shared/components/screen-container/hooks/use-content-layout.ts

@@ -46,7 +46,7 @@ export function useContentLayout() {
 				if (
 					!isFirstMeasurement ||
 					animations.progress.get() !== 0 ||
-					animations.animating.get() !== 0
+					animations.progressAnimating.get() !== 0
 				) {
 					return;
 				}

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

@@ -63,11 +63,17 @@ export const BackdropLayer = memo(function BackdropLayer({
 
 			runOnUI(() => {
 				"worklet";
-				const resolvedSnaps = rawSnapPoints
-					.map((point) =>
-						point === "auto" ? resolvedAutoSnapPoint.get() : point,
-					)
-					.filter((point): point is number => typeof point === "number");
+				const resolvedSnaps: number[] = [];
+
+				for (let i = 0; i < rawSnapPoints.length; i++) {
+					const point = rawSnapPoints[i];
+					const resolvedPoint =
+						point === "auto" ? resolvedAutoSnapPoint.get() : point;
+
+					if (typeof resolvedPoint === "number") {
+						resolvedSnaps.push(resolvedPoint);
+					}
+				}
 
 				const { target, shouldDismiss } = findCollapseTarget(
 					animations.progress.get(),

package/src/shared/components/screen-container/layers/maybe-masked-navigation-container.tsx

@@ -27,8 +27,38 @@ let hasWarnedMissingMaskedView = false;
 
 export const MaybeMaskedNavigationContainer = memo(
 	({ enabled, children, pointerEvents }: Props) => {
+		if (!enabled || LazyMaskedView === View) {
+			return children;
+		}
+
+		return (
+			<MaskedNavigationContainer pointerEvents={pointerEvents}>
+				{children}
+			</MaskedNavigationContainer>
+		);
+	},
+);
+
+const MaskedNavigationContainer = memo(
+	({
+		children,
+		pointerEvents,
+	}: {
+		children: React.ReactNode;
+		pointerEvents: ViewProps["pointerEvents"];
+	}) => {
 		const { stylesMap } = useScreenStyles();
 
+		const maybeLogWarning = useCallback(() => {
+			if (LazyMaskedView !== View) return;
+			if (hasWarnedMissingMaskedView) return;
+
+			hasWarnedMissingMaskedView = true;
+			logger.warn(
+				"navigationMaskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
+			);
+		}, []);
+
 		const animatedNavigationMaskStyle = useAnimatedStyle(() => {
 			"worklet";
 			return (
@@ -43,21 +73,6 @@ export const MaybeMaskedNavigationContainer = memo(
 			);
 		});
 
-		const maybeLogWarning = useCallback(() => {
-			if (!enabled) return;
-			if (LazyMaskedView !== View) return;
-			if (hasWarnedMissingMaskedView) return;
-
-			hasWarnedMissingMaskedView = true;
-			logger.warn(
-				"navigationMaskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
-			);
-		}, [enabled]);
-
-		if (!enabled || LazyMaskedView === View) {
-			return children;
-		}
-
 		return (
 			<LazyMaskedView
 				style={styles.navigationMaskedRoot}

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

@@ -14,7 +14,6 @@ type Props = {
 };
 
 export const SurfaceContainer = memo(({ children, pointerEvents }: Props) => {
-	const { stylesMap } = useScreenStyles();
 	const { current } = useDescriptors();
 
 	const SurfaceComponent = current.options.surfaceComponent;
@@ -25,29 +24,50 @@ export const SurfaceContainer = memo(({ children, pointerEvents }: Props) => {
 			: null;
 	}, [SurfaceComponent]);
 
-	const animatedSurfaceStyle = useAnimatedStyle(() => {
-		"worklet";
-		return stylesMap.get().surface?.style ?? NO_STYLES;
-	});
-
-	const animatedSurfaceProps = useAnimatedProps(() => {
-		"worklet";
-		return stylesMap.get().surface?.props ?? NO_PROPS;
-	});
-
 	if (!AnimatedSurfaceComponent) return children;
 
 	return (
-		<AnimatedSurfaceComponent
-			style={[styles.surface, animatedSurfaceStyle]}
-			animatedProps={animatedSurfaceProps}
+		<AnimatedSurface
+			SurfaceComponent={AnimatedSurfaceComponent}
 			pointerEvents={pointerEvents}
 		>
 			{children}
-		</AnimatedSurfaceComponent>
+		</AnimatedSurface>
 	);
 });
 
+type AnimatedSurfaceProps = {
+	children: React.ReactNode;
+	pointerEvents: ViewProps["pointerEvents"];
+	SurfaceComponent: ComponentType<any>;
+};
+
+const AnimatedSurface = memo(
+	({ children, pointerEvents, SurfaceComponent }: AnimatedSurfaceProps) => {
+		const { stylesMap } = useScreenStyles();
+
+		const animatedSurfaceStyle = useAnimatedStyle(() => {
+			"worklet";
+			return stylesMap.get().surface?.style ?? NO_STYLES;
+		});
+
+		const animatedSurfaceProps = useAnimatedProps(() => {
+			"worklet";
+			return stylesMap.get().surface?.props ?? NO_PROPS;
+		});
+
+		return (
+			<SurfaceComponent
+				style={[styles.surface, animatedSurfaceStyle]}
+				animatedProps={animatedSurfaceProps}
+				pointerEvents={pointerEvents}
+			>
+				{children}
+			</SurfaceComponent>
+		);
+	},
+);
+
 const styles = StyleSheet.create({
 	surface: {
 		flex: 1,

package/src/shared/components/screen-lifecycle/hooks/helpers/reset-stores-for-screen.ts

@@ -1,35 +1,15 @@
 import { runOnUI } from "react-native-reanimated";
 import { AnimationStore } from "../../../../stores/animation.store";
-import {
-	clear,
-	clearByAncestor,
-	clearByBranch,
-} from "../../../../stores/bounds/internals/clear";
+import { clear } from "../../../../stores/bounds/internals/clear";
 import { GestureStore } from "../../../../stores/gesture.store";
 import { ScrollStore } from "../../../../stores/scroll.store";
 import { SystemStore } from "../../../../stores/system.store";
 
-export function resetStoresForScreen(
-	routeKey: string,
-	isBranchScreen: boolean,
-	branchNavigatorKey?: string,
-) {
+export function resetStoresForScreen(routeKey: string) {
 	AnimationStore.clearBag(routeKey);
 	GestureStore.clearBag(routeKey);
 	ScrollStore.clearBag(routeKey);
 	SystemStore.clearBag(routeKey);
 
-	runOnUI(() => {
-		"worklet";
-		if (!isBranchScreen) return;
-
-		clear(routeKey);
-
-		if (branchNavigatorKey) {
-			clearByBranch(branchNavigatorKey);
-			return;
-		}
-
-		clearByAncestor(routeKey);
-	})();
+	runOnUI(clear)(routeKey);
 }

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

@@ -68,7 +68,6 @@ const useManagedClose = ({
  */
 const useNativeStackClose = ({
 	current,
-	animations,
 	requestLifecycleTransition,
 	resetStores,
 }: CloseHookParams) => {
@@ -106,7 +105,6 @@ const useNativeStackClose = ({
 		const isFirstScreen = routeIndex <= 0;
 
 		if (!isEnabled || nearestAncestorDismissing?.get() || isFirstScreen) {
-			animations.closing.set(1);
 			resetStores();
 			return;
 		}
@@ -137,12 +135,11 @@ export function useCloseTransitionIntent(
 } {
 	const routeKey = current.route.key;
 	const { flags } = useStackCoreContext();
-	const { isBranchScreen, branchNavigatorKey } = useDescriptorDerivations();
 	const isNativeStack = flags.STACK_TYPE === StackType.NATIVE;
 	const { requestLifecycleTransition } = system.actions;
 
 	const resetStores = useStableCallback(() => {
-		resetStoresForScreen(routeKey, isBranchScreen, branchNavigatorKey);
+		resetStoresForScreen(routeKey);
 	});
 
 	const closeParams: CloseHookParams = {

package/src/shared/components/screen-lifecycle/hooks/use-open-transition-intent.ts

@@ -66,7 +66,7 @@ export function useOpenTransitionIntent(
 				system.targetProgress.set(target);
 				animations.progress.set(target);
 			}
-			animations.animating.set(0);
+			animations.progressAnimating.set(0);
 			animations.closing.set(0);
 			animations.entering.set(0);
 			return;

package/src/shared/configs/presets.ts

@@ -246,7 +246,7 @@ export const SharedIGImage = ({
 		gestureEnabled: true,
 		gestureDirection: ["vertical", "horizontal"],
 		enableTransitions: true,
-		gestureDrivesProgress: false,
+		gestureProgressMode: "freeform",
 		screenStyleInterpolator: ({
 			current,
 			layouts: {
@@ -394,7 +394,7 @@ export const SharedAppleMusic = ({
 		enableTransitions: true,
 		gestureEnabled: true,
 		gestureDirection: ["vertical", "horizontal"],
-		gestureDrivesProgress: false,
+		gestureProgressMode: "freeform",
 		screenStyleInterpolator: ({
 			bounds,
 			focused,
@@ -608,7 +608,7 @@ export const SharedXImage = ({
 		enableTransitions: true,
 		gestureEnabled: true,
 		gestureDirection: ["vertical", "vertical-inverted"],
-		gestureDrivesProgress: false,
+		gestureProgressMode: "freeform",
 		screenStyleInterpolator: ({
 			focused,
 			bounds,

package/src/shared/constants.ts

@@ -5,7 +5,10 @@ import type {
 	ScreenTransitionOptions,
 	ScreenTransitionState,
 } from "./types/animation.types";
-import type { ActivationArea } from "./types/gesture.types";
+import type {
+	ActivationArea,
+	GestureProgressMode,
+} from "./types/gesture.types";
 import type { Layout, SheetScrollGestureBehavior } from "./types/screen.types";
 import type { BaseStackRoute } from "./types/stack.types";
 
@@ -157,11 +160,11 @@ export const FULLSCREEN_DIMENSIONS = (
 
 export const DEFAULT_GESTURE_VELOCITY_IMPACT = 0.3;
 export const DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT = 0.1;
-export const DEFAULT_GESTURE_RELEASE_VELOCITY_MAX = 3.2;
 export const DEFAULT_GESTURE_SENSITIVITY = 1;
 export const DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE = 1;
 export const DEFAULT_GESTURE_DIRECTION = "horizontal";
-export const DEFAULT_GESTURE_DRIVES_PROGRESS = true;
+export const DEFAULT_GESTURE_PROGRESS_MODE: GestureProgressMode =
+	"progress-driven";
 export const DEFAULT_GESTURE_SNAP_LOCKED = false;
 export const DEFAULT_GESTURE_ACTIVATION_AREA: ActivationArea = "screen";
 export const DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR: SheetScrollGestureBehavior =
@@ -182,3 +185,14 @@ export const EPSILON = 1e-5;
  * Prevents micro-jitter/oscillation near animation endpoints.
  */
 export const ANIMATION_SNAP_THRESHOLD = 0.01;
+
+/**
+ * Number of consecutive frames progress must remain near its target before it
+ * is treated as logically settled.
+ */
+export const LOGICAL_SETTLE_REQUIRED_FRAMES = 5;
+
+/**
+ * Progress distance from target required for logical settle.
+ */
+export const LOGICAL_SETTLE_PROGRESS_THRESHOLD = 0.001;

package/src/shared/index.ts

@@ -56,7 +56,10 @@ export type {
 	OverlayProps,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
+	ScreenTransitionAccessor,
 	ScreenTransitionConfig,
+	ScreenTransitionDepthTarget,
+	ScreenTransitionTarget,
 	TransitionInterpolatedStyle,
 	TransitionSlotStyle,
 	TransitionSpec,

package/src/shared/providers/register-bounds.provider.tsx

@@ -87,11 +87,14 @@ const useInitialLayoutHandler = (params: {
 		maybeMeasureAndStore,
 	} = params;
 
-	const isAnimating = AnimationStore.getValue(currentScreenKey, "animating");
+	const isAnimating = AnimationStore.getValue(
+		currentScreenKey,
+		"progressAnimating",
+	);
 
 	// Check if any ancestor is animating
 	const ancestorAnimations = ancestorKeys.map((key) =>
-		AnimationStore.getValue(key, "animating"),
+		AnimationStore.getValue(key, "progressAnimating"),
 	);
 
 	const hasMeasuredOnLayout = useSharedValue(false);
@@ -246,8 +249,7 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 		children,
 	}) => {
 		const { current, next } = useDescriptors();
-		const { ancestorKeys, navigatorKey, ancestorNavigatorKeys } =
-			useDescriptorDerivations();
+		const { ancestorKeys } = useDescriptorDerivations();
 		const currentScreenKey = current.route.key;
 		const selectedNextRouteId = getRouteParamId(next?.route);
 
@@ -258,7 +260,10 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 		const updateSignal: SharedValue<number> =
 			parentContext?.updateSignal ?? ownSignal;
 
-		const isAnimating = AnimationStore.getValue(currentScreenKey, "animating");
+		const isAnimating = AnimationStore.getValue(
+			currentScreenKey,
+			"progressAnimating",
+		);
 		const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
 
 		const emitUpdate = useStableCallbackValue(() => {
@@ -285,9 +290,6 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 					if (existing?.bounds) {
 						applyMeasuredBoundsWrites({
 							sharedBoundTag,
-							ancestorKeys,
-							navigatorKey,
-							ancestorNavigatorKeys,
 							currentScreenKey,
 							measured: existing.bounds,
 							preparedStyles,
@@ -341,9 +343,6 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 					currentScreenKey,
 					measured,
 					preparedStyles,
-					ancestorKeys,
-					navigatorKey,
-					ancestorNavigatorKeys,
 					shouldSetSource: canSetSource,
 					shouldUpdateSource: canUpdateSource,
 					shouldSetDestination: canSetDestination,

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

@@ -1,7 +1,21 @@
-import { type ReactNode, useContext } from "react";
+import {
+	type ReactNode,
+	useCallback,
+	useContext,
+	useLayoutEffect,
+	useMemo,
+} from "react";
+import { useSharedValue } from "react-native-reanimated";
+import { createBoundsAccessor } from "../../../utils/bounds";
 import createProvider from "../../../utils/create-provider";
 import { useScreenAnimationPipeline } from "./helpers/pipeline";
-import type { ScreenAnimationSource } from "./types";
+import type {
+	RegisterScreenAnimationDescendant,
+	ScreenAnimationAncestorDescendantRegistrar,
+	ScreenAnimationDescendantSources,
+	ScreenAnimationSource,
+	ScreenAnimationTransitionSource,
+} from "./types";
 
 type Props = {
 	children: ReactNode;
@@ -11,6 +25,9 @@ export type ScreenAnimationContextValue = ReturnType<
 	typeof useScreenAnimationPipeline
 > & {
 	ancestorScreenAnimationSources: ScreenAnimationSource[];
+	descendantScreenAnimationSources: ScreenAnimationDescendantSources;
+	registerDescendantScreenAnimationSource: RegisterScreenAnimationDescendant;
+	ancestorDescendantScreenAnimationRegistrars: ScreenAnimationAncestorDescendantRegistrar[];
 };
 
 export type ScreenAnimationContextResult = {
@@ -25,35 +42,170 @@ export const {
 	guarded: true,
 })<Props, ScreenAnimationContextValue>((): ScreenAnimationContextResult => {
 	const parentContext = useContext(ScreenAnimationContext);
+	const parentScreenInterpolatorProps = parentContext?.screenInterpolatorProps;
+	const parentScreenInterpolatorPropsRevision =
+		parentContext?.screenInterpolatorPropsRevision;
+	const parentAncestorScreenAnimationSources =
+		parentContext?.ancestorScreenAnimationSources;
+	const parentRegisterDescendantScreenAnimationSource =
+		parentContext?.registerDescendantScreenAnimationSource;
+	const parentAncestorDescendantScreenAnimationRegistrars =
+		parentContext?.ancestorDescendantScreenAnimationRegistrars;
 
 	const {
 		screenInterpolatorProps,
-		screenInterpolatorFrameUpdater,
+		screenInterpolatorPropsRevision,
+		selectedInterpolatorOptions,
 		nextInterpolator,
 		currentInterpolator,
-		boundsAccessor,
 	} = useScreenAnimationPipeline();
 
-	const ancestorScreenAnimationSources = parentContext
-		? [
-				{
-					screenInterpolatorProps: parentContext.screenInterpolatorProps,
-					screenInterpolatorFrameUpdater:
-						parentContext.screenInterpolatorFrameUpdater,
-					boundsAccessor: parentContext.boundsAccessor,
-				},
-				...parentContext.ancestorScreenAnimationSources,
-			]
-		: [];
+	const selfScreenAnimationSource = useMemo<ScreenAnimationSource>(
+		() => ({
+			screenInterpolatorProps,
+			screenInterpolatorPropsRevision,
+		}),
+		[screenInterpolatorProps, screenInterpolatorPropsRevision],
+	);
+
+	const selfScreenAnimationTransitionSource =
+		useMemo<ScreenAnimationTransitionSource>(
+			() => ({
+				...selfScreenAnimationSource,
+				boundsAccessor: createBoundsAccessor(() => {
+					"worklet";
+					return selfScreenAnimationSource.screenInterpolatorProps.get();
+				}),
+			}),
+			[selfScreenAnimationSource],
+		);
+
+	const descendantScreenAnimationSources = useSharedValue<
+		ScreenAnimationDescendantSources["value"]
+	>([]);
+
+	const registerDescendantScreenAnimationSource =
+		useCallback<RegisterScreenAnimationDescendant>(
+			(source, depth) => {
+				descendantScreenAnimationSources.modify(
+					<T extends ScreenAnimationDescendantSources["value"]>(
+						currentSources: T,
+					): T => {
+						"worklet";
+						const existingIndex = currentSources.findIndex(
+							(currentSource) => currentSource.source === source,
+						);
+
+						if (
+							existingIndex !== -1 &&
+							currentSources[existingIndex]?.depth === depth
+						) {
+							return currentSources;
+						}
+
+						const nextSources =
+							existingIndex === -1
+								? [...currentSources, { source, depth }]
+								: currentSources.map((currentSource, index) =>
+										index === existingIndex ? { source, depth } : currentSource,
+									);
+
+						return nextSources.sort((a, b) => a.depth - b.depth) as T;
+					},
+				);
+
+				return () => {
+					descendantScreenAnimationSources.modify(
+						<T extends ScreenAnimationDescendantSources["value"]>(
+							currentSources: T,
+						): T => {
+							"worklet";
+							return currentSources.filter(
+								(currentSource) => currentSource.source !== source,
+							) as T;
+						},
+					);
+				};
+			},
+			[descendantScreenAnimationSources],
+		);
+
+	const ancestorScreenAnimationSources = useMemo(() => {
+		if (
+			!parentScreenInterpolatorProps ||
+			!parentScreenInterpolatorPropsRevision ||
+			!parentAncestorScreenAnimationSources
+		) {
+			return [];
+		}
+
+		return [
+			{
+				screenInterpolatorProps: parentScreenInterpolatorProps,
+				screenInterpolatorPropsRevision: parentScreenInterpolatorPropsRevision,
+			},
+			...parentAncestorScreenAnimationSources,
+		];
+	}, [
+		parentScreenInterpolatorProps,
+		parentScreenInterpolatorPropsRevision,
+		parentAncestorScreenAnimationSources,
+	]);
+
+	const ancestorDescendantScreenAnimationRegistrars = useMemo(() => {
+		if (!parentRegisterDescendantScreenAnimationSource) {
+			return [];
+		}
+
+		// Each provider exposes its own descendant registrar and forwards ancestor
+		// registrars, letting a mounted child register with every ancestor scope.
+		return [
+			{
+				register: parentRegisterDescendantScreenAnimationSource,
+				depth: 1,
+			},
+			...(parentAncestorDescendantScreenAnimationRegistrars ?? []).map(
+				(registrar) => ({
+					register: registrar.register,
+					depth: registrar.depth + 1,
+				}),
+			),
+		];
+	}, [
+		parentRegisterDescendantScreenAnimationSource,
+		parentAncestorDescendantScreenAnimationRegistrars,
+	]);
+
+	useLayoutEffect(() => {
+		const cleanups = ancestorDescendantScreenAnimationRegistrars.map(
+			(registrar) =>
+				registrar.register(
+					selfScreenAnimationTransitionSource,
+					registrar.depth,
+				),
+		);
+
+		return () => {
+			for (const cleanup of cleanups) {
+				cleanup();
+			}
+		};
+	}, [
+		ancestorDescendantScreenAnimationRegistrars,
+		selfScreenAnimationTransitionSource,
+	]);
 
 	return {
 		value: {
 			screenInterpolatorProps,
-			screenInterpolatorFrameUpdater,
+			screenInterpolatorPropsRevision,
+			selectedInterpolatorOptions,
 			nextInterpolator,
 			currentInterpolator,
-			boundsAccessor,
 			ancestorScreenAnimationSources,
+			descendantScreenAnimationSources,
+			registerDescendantScreenAnimationSource,
+			ancestorDescendantScreenAnimationRegistrars,
 		},
 	};
 });

package/src/shared/providers/screen/animation/helpers/accessors/use-build-bounds-accessor.tsx

@@ -0,0 +1,13 @@
+import { useMemo } from "react";
+import { createBoundsAccessor } from "../../../../../utils/bounds";
+import { useScreenAnimationContext } from "../../animation.provider";
+
+export const useBuildBoundsAccessor = () => {
+	const { screenInterpolatorProps } = useScreenAnimationContext();
+	return useMemo(() => {
+		return createBoundsAccessor(() => {
+			"worklet";
+			return screenInterpolatorProps.get();
+		});
+	}, [screenInterpolatorProps]);
+};