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

package/src/shared/providers/gestures/handlers/use-handlers.ts

@@ -53,6 +53,10 @@ import {
 	normalizeVelocity,
 } from "../helpers/gesture-physics";
 import { resetGestureValues } from "../helpers/gesture-reset";
+import {
+	findNearestSnapPoint,
+	resolveRuntimeSnapPoints,
+} from "../helpers/gesture-snap-points";
 import {
 	determineDismissal,
 	determineSnapTarget,
@@ -147,14 +151,22 @@ export const useHandlers = ({
 
 	const { dimensions } = useViewportContext();
 	const routeKey = current.route.key;
-	const animations = AnimationStore.getRouteAnimations(current.route.key);
-	const gestureAnimationValues = GestureStore.getRouteGestures(
-		current.route.key,
+	const animations = AnimationStore.getRouteAnimations(routeKey);
+	const gestureAnimationValues = GestureStore.getRouteGestures(routeKey);
+	const {
+		hasSnapPoints,
+		hasAutoSnapPoint,
+		snapPoints,
+		minSnapPoint,
+		maxSnapPoint,
+	} = effectiveSnapPoints;
+
+	// Read the measured "auto" snap point reactively inside worklets.
+	const autoSnapPointValue = AnimationStore.getAnimation(
+		routeKey,
+		"autoSnapPoint",
 	);
 
-	const { hasSnapPoints, snapPoints, minSnapPoint, maxSnapPoint } =
-		effectiveSnapPoints;
-
 	const directions = useMemo(() => {
 		warnOnSnapDirectionArray({ gestureDirection, hasSnapPoints });
 		return resolveGestureDirections({ gestureDirection, hasSnapPoints });
@@ -289,9 +301,17 @@ export const useHandlers = ({
 							return;
 						}
 
+						const { resolvedMaxSnapPoint } = resolveRuntimeSnapPoints({
+							snapPoints,
+							hasAutoSnapPoint,
+							autoSnapPoint: autoSnapPointValue.value,
+							minSnapPoint,
+							maxSnapPoint,
+							canDismiss,
+						});
 						const effectiveMaxSnapPoint = gestureSnapLocked
 							? lockedSnapPoint.value
-							: maxSnapPoint;
+							: resolvedMaxSnapPoint;
 
 						const canExpandMore =
 							animations.progress.value < effectiveMaxSnapPoint - EPSILON &&
@@ -312,22 +332,23 @@ export const useHandlers = ({
 
 	const onStart = useStableCallbackValue(() => {
 		"worklet";
-		if (hasSnapPoints && gestureSnapLocked) {
-			let nearest = snapPoints[0] ?? animations.progress.value;
-			let smallestDistance = Math.abs(animations.progress.value - nearest);
-
-			for (let i = 1; i < snapPoints.length; i++) {
-				const point = snapPoints[i];
-				const distance = Math.abs(animations.progress.value - point);
-				if (distance < smallestDistance) {
-					smallestDistance = distance;
-					nearest = point;
-				}
-			}
+		const { resolvedSnapPoints, resolvedMaxSnapPoint } =
+			resolveRuntimeSnapPoints({
+				snapPoints,
+				hasAutoSnapPoint,
+				autoSnapPoint: autoSnapPointValue.value,
+				minSnapPoint,
+				maxSnapPoint,
+				canDismiss,
+			});
 
-			lockedSnapPoint.value = nearest;
+		if (hasSnapPoints && gestureSnapLocked) {
+			lockedSnapPoint.value = findNearestSnapPoint(
+				animations.progress.value,
+				resolvedSnapPoints,
+			);
 		} else {
-			lockedSnapPoint.value = maxSnapPoint;
+			lockedSnapPoint.value = resolvedMaxSnapPoint;
 		}
 
 		gestureAnimationValues.dragging.value = TRUE;
@@ -363,14 +384,25 @@ export const useHandlers = ({
 				const baseSign = -1;
 				const sign = directions.snapAxisInverted ? -baseSign : baseSign;
 				const progressDelta = (sign * translation) / dimension;
+
+				const { resolvedMinSnapPoint, resolvedMaxSnapPoint } =
+					resolveRuntimeSnapPoints({
+						snapPoints,
+						hasAutoSnapPoint,
+						autoSnapPoint: autoSnapPointValue.value,
+						minSnapPoint,
+						maxSnapPoint,
+						canDismiss,
+					});
+
 				const maxProgressForGesture = gestureSnapLocked
 					? lockedSnapPoint.value
-					: maxSnapPoint;
+					: resolvedMaxSnapPoint;
 				const minProgressForGesture = gestureSnapLocked
 					? canDismiss
 						? 0
 						: lockedSnapPoint.value
-					: minSnapPoint;
+					: resolvedMinSnapPoint;
 
 				animations.progress.value = Math.max(
 					minProgressForGesture,
@@ -430,9 +462,20 @@ export const useHandlers = ({
 					? -axisVelocity
 					: axisVelocity;
 
+				const { resolvedSnapPoints } = resolveRuntimeSnapPoints({
+					snapPoints,
+					hasAutoSnapPoint,
+					autoSnapPoint: autoSnapPointValue.value,
+					minSnapPoint,
+					maxSnapPoint,
+					canDismiss,
+				});
+
 				const result = determineSnapTarget({
 					currentProgress: animations.progress.value,
-					snapPoints: gestureSnapLocked ? [lockedSnapPoint.value] : snapPoints,
+					snapPoints: gestureSnapLocked
+						? [lockedSnapPoint.value]
+						: resolvedSnapPoints,
 					velocity: snapVelocity,
 					dimension: axisDimension,
 					velocityFactor: snapVelocityImpact,

package/src/shared/providers/gestures/helpers/gesture-snap-points.ts

@@ -0,0 +1,72 @@
+interface ResolveRuntimeSnapPointsProps {
+	snapPoints: number[];
+	hasAutoSnapPoint: boolean;
+	autoSnapPoint: number;
+	minSnapPoint: number;
+	maxSnapPoint: number;
+	canDismiss: boolean;
+}
+
+interface ResolvedRuntimeSnapPointsResult {
+	resolvedAutoSnapPoint: number | null;
+	resolvedSnapPoints: number[];
+	resolvedMinSnapPoint: number;
+	resolvedMaxSnapPoint: number;
+}
+
+export const resolveRuntimeSnapPoints = ({
+	snapPoints,
+	hasAutoSnapPoint,
+	autoSnapPoint,
+	minSnapPoint,
+	maxSnapPoint,
+	canDismiss,
+}: ResolveRuntimeSnapPointsProps): ResolvedRuntimeSnapPointsResult => {
+	"worklet";
+
+	const resolvedAutoSnapPoint =
+		hasAutoSnapPoint && autoSnapPoint > 0 ? autoSnapPoint : null;
+
+	const resolvedSnapPoints =
+		resolvedAutoSnapPoint === null
+			? snapPoints
+			: [...snapPoints, resolvedAutoSnapPoint].sort((a, b) => a - b);
+
+	const resolvedMinSnapPoint =
+		resolvedAutoSnapPoint !== null && !canDismiss
+			? Math.min(
+					minSnapPoint === -1 ? resolvedAutoSnapPoint : minSnapPoint,
+					resolvedAutoSnapPoint,
+				)
+			: minSnapPoint;
+
+	return {
+		resolvedAutoSnapPoint,
+		resolvedSnapPoints,
+		resolvedMinSnapPoint,
+		resolvedMaxSnapPoint:
+			resolvedSnapPoints[resolvedSnapPoints.length - 1] ?? maxSnapPoint,
+	};
+};
+
+export const findNearestSnapPoint = (
+	progress: number,
+	snapPoints: number[],
+): number => {
+	"worklet";
+
+	let nearest = snapPoints[0] ?? progress;
+	let smallestDistance = Math.abs(progress - nearest);
+
+	for (let i = 1; i < snapPoints.length; i++) {
+		const point = snapPoints[i];
+		const distance = Math.abs(progress - point);
+
+		if (distance < smallestDistance) {
+			smallestDistance = distance;
+			nearest = point;
+		}
+	}
+
+	return nearest;
+};

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

@@ -1,23 +1,26 @@
-import { type ReactNode, useMemo } from "react";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
 import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
 import type { ScreenInterpolationProps } from "../../../types/animation.types";
-import createProvider from "../../../utils/create-provider";
 import { useScreenAnimationPipeline } from "./helpers/pipeline";
 
 type Props = {
 	children: ReactNode;
 };
 
-type ScreenAnimationContextValue = ReturnType<
+export type ScreenAnimationContextValue = ReturnType<
 	typeof useScreenAnimationPipeline
 > & {
 	screenAnimation: DerivedValue<ScreenInterpolationProps>;
+	ancestorScreenAnimations: DerivedValue<ScreenInterpolationProps>[];
 };
 
-const { ScreenAnimationProvider, useScreenAnimationContext } = createProvider(
-	"ScreenAnimation",
-	{ guarded: true },
-)<Props, ScreenAnimationContextValue>(() => {
+const ScreenAnimationContext =
+	createContext<ScreenAnimationContextValue | null>(null);
+ScreenAnimationContext.displayName = "ScreenAnimation";
+
+function ScreenAnimationProvider({ children }: Props) {
+	const parentContext = useContext(ScreenAnimationContext);
+
 	const {
 		screenInterpolatorProps,
 		nextInterpolator,
@@ -34,6 +37,17 @@ const { ScreenAnimationProvider, useScreenAnimationContext } = createProvider(
 		};
 	});
 
+	const ancestorScreenAnimations = useMemo(() => {
+		if (!parentContext) {
+			return [];
+		}
+
+		return [
+			parentContext.screenAnimation,
+			...parentContext.ancestorScreenAnimations,
+		];
+	}, [parentContext]);
+
 	const value = useMemo(
 		() => ({
 			screenInterpolatorProps,
@@ -41,6 +55,7 @@ const { ScreenAnimationProvider, useScreenAnimationContext } = createProvider(
 			currentInterpolator,
 			boundsAccessor,
 			screenAnimation,
+			ancestorScreenAnimations,
 		}),
 		[
 			screenInterpolatorProps,
@@ -48,10 +63,31 @@ const { ScreenAnimationProvider, useScreenAnimationContext } = createProvider(
 			currentInterpolator,
 			boundsAccessor,
 			screenAnimation,
+			ancestorScreenAnimations,
 		],
 	);
 
-	return { value };
-});
+	return (
+		<ScreenAnimationContext.Provider value={value}>
+			{children}
+		</ScreenAnimationContext.Provider>
+	);
+}
 
-export { ScreenAnimationProvider, useScreenAnimationContext };
+function useScreenAnimationContext(): ScreenAnimationContextValue {
+	const context = useContext(ScreenAnimationContext);
+
+	if (!context) {
+		throw new Error(
+			"ScreenAnimation context must be used within a ScreenAnimationProvider",
+		);
+	}
+
+	return context;
+}
+
+export {
+	ScreenAnimationContext,
+	ScreenAnimationProvider,
+	useScreenAnimationContext,
+};

package/src/shared/providers/screen/animation/helpers/derivations.ts

@@ -24,18 +24,10 @@ export const derivations = ({ previous, current, next }: DerivationsParams) => {
 	// The screen NOT driving the transition
 	const inactive = focused ? previous : current;
 
-	// deprecated
-	const isActiveTransitioning = !!(active.gesture.dragging || active.animating);
-
-	// deprecated
-	const isDismissing = !!(active.gesture.dismissing || active.closing);
-
 	return {
 		progress,
 		focused,
 		active,
 		inactive,
-		isActiveTransitioning,
-		isDismissing,
 	};
 };

package/src/shared/providers/screen/animation/helpers/pipeline.ts

@@ -175,11 +175,24 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 	const currentRouteKey = currentDescriptor?.route?.key;
 	const currentIndex = routeKeys.indexOf(currentRouteKey);
 
-	const sortedSnapPoints = useMemo(() => {
+	const sortedNumericSnapPoints = useMemo(() => {
 		const points = currentDescriptor?.options?.snapPoints;
-		return points ? [...points].sort((a, b) => a - b) : [];
+		if (!points) return [];
+		return points
+			.filter((p): p is number => typeof p === "number")
+			.sort((a, b) => a - b);
 	}, [currentDescriptor?.options?.snapPoints]);
 
+	const hasAutoSnapPoint = useMemo(
+		() => currentDescriptor?.options?.snapPoints?.includes("auto") ?? false,
+		[currentDescriptor?.options?.snapPoints],
+	);
+
+	const autoSnapPointValue = AnimationStore.getAnimation(
+		currentRouteKey ?? "_",
+		"autoSnapPoint",
+	);
+
 	const nextRouteKey = nextDescriptor?.route?.key;
 	const nextHasTransitions =
 		!!nextRouteKey &&
@@ -199,8 +212,6 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 		focused: true,
 		active: DEFAULT_SCREEN_TRANSITION_STATE,
 		inactive: undefined,
-		isActiveTransitioning: false,
-		isDismissing: false,
 	});
 
 	const boundsAccessor = useMemo(() => {
@@ -238,7 +249,17 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 		const stackProgress =
 			currentIndex >= 0 ? rootStackProgress.value - currentIndex : progress;
 
-		const snapIndex = computeSnapIndex(current.progress, sortedSnapPoints);
+		// Resolve 'auto' snap point reactively so computeSnapIndex stays accurate
+		const resolvedAutoSnap =
+			hasAutoSnapPoint && autoSnapPointValue.value > 0
+				? autoSnapPointValue.value
+				: null;
+		const resolvedSnapPoints =
+			resolvedAutoSnap !== null
+				? [...sortedNumericSnapPoints, resolvedAutoSnap].sort((a, b) => a - b)
+				: sortedNumericSnapPoints;
+
+		const snapIndex = computeSnapIndex(current.progress, resolvedSnapPoints);
 
 		const nextProps = {
 			layouts: { screen: dimensions },

package/src/shared/providers/screen/animation/helpers/resolve-screen-animation-target.ts

@@ -0,0 +1,44 @@
+import type { DerivedValue } from "react-native-reanimated";
+import type { ScreenInterpolationProps } from "../../../../types/animation.types";
+import type { ScreenAnimationTarget } from "../types";
+
+type Params = {
+	target: ScreenAnimationTarget | undefined;
+	self: DerivedValue<ScreenInterpolationProps>;
+	ancestors: DerivedValue<ScreenInterpolationProps>[];
+};
+
+const isAncestorTarget = (
+	target: ScreenAnimationTarget,
+): target is { ancestor: number } => {
+	return typeof target === "object" && target !== null && "ancestor" in target;
+};
+
+export function resolveScreenAnimationTarget({
+	target,
+	self,
+	ancestors,
+}: Params): DerivedValue<ScreenInterpolationProps> {
+	if (!target || target === "self") {
+		return self;
+	}
+
+	if (target === "parent") {
+		return ancestors[0] ?? self;
+	}
+
+	if (target === "root") {
+		return ancestors[ancestors.length - 1] ?? self;
+	}
+
+	if (!isAncestorTarget(target)) {
+		return self;
+	}
+
+	const depth = target.ancestor;
+	if (!Number.isInteger(depth) || depth < 1) {
+		return self;
+	}
+
+	return ancestors[depth - 1] ?? self;
+}

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

@@ -2,4 +2,7 @@ export {
 	ScreenAnimationProvider,
 	useScreenAnimationContext,
 } from "./animation.provider";
-export { useScreenAnimation } from "./use-screen-animation";
+export {
+	type ScreenAnimationTarget,
+	useScreenAnimation,
+} from "./use-screen-animation";

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

@@ -0,0 +1,5 @@
+export type ScreenAnimationTarget =
+	| "self"
+	| "parent"
+	| "root"
+	| { ancestor: number };

package/src/shared/providers/screen/animation/use-screen-animation.tsx

@@ -1,6 +1,19 @@
+import type { DerivedValue } from "react-native-reanimated";
+import type { ScreenInterpolationProps } from "../../../types/animation.types";
 import { useScreenAnimationContext } from "./animation.provider";
+import { resolveScreenAnimationTarget } from "./helpers/resolve-screen-animation-target";
+import type { ScreenAnimationTarget } from "./types";
 
-export function useScreenAnimation() {
-	const { screenAnimation } = useScreenAnimationContext();
-	return screenAnimation;
+export type { ScreenAnimationTarget } from "./types";
+
+export function useScreenAnimation(
+	target?: ScreenAnimationTarget,
+): DerivedValue<ScreenInterpolationProps> {
+	const { screenAnimation, ancestorScreenAnimations } =
+		useScreenAnimationContext();
+	return resolveScreenAnimationTarget({
+		target,
+		self: screenAnimation,
+		ancestors: ancestorScreenAnimations,
+	});
 }

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

@@ -14,7 +14,7 @@ import type {
 	DirectStackProps,
 	DirectStackScene,
 } from "../../types/providers/direct-stack.types";
-import { isFloatOverlayVisible } from "../../utils/overlay/visibility";
+import { isOverlayVisible } from "../../utils/overlay/visibility";
 import { useStackCoreContext } from "./core.provider";
 import { useStackDerived } from "./helpers/use-stack-derived";
 
@@ -64,10 +64,7 @@ function useDirectStackValue(
 
 			if (!shouldShowFloatOverlay && descriptor) {
 				const options = descriptor.options;
-				if (
-					options?.enableTransitions === true &&
-					isFloatOverlayVisible(options)
-				) {
+				if (options?.enableTransitions === true && isOverlayVisible(options)) {
 					shouldShowFloatOverlay = true;
 				}
 			}

package/src/shared/providers/stack/helpers/use-processed-routes.ts

@@ -7,7 +7,7 @@ import type {
 	BaseStackDescriptor,
 	BaseStackScene,
 } from "../../../types/stack.types";
-import { isFloatOverlayVisible } from "../../../utils/overlay/visibility";
+import { isOverlayVisible } from "../../../utils/overlay/visibility";
 
 export interface ProcessedRoutes<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
@@ -52,7 +52,7 @@ export function useProcessedRoutes<
 			animationMaps[i] = AnimationStore.getRouteAnimations(route.key);
 
 			if (!shouldShowFloatOverlay) {
-				shouldShowFloatOverlay = isFloatOverlayVisible(options);
+				shouldShowFloatOverlay = isOverlayVisible(options);
 			}
 
 			if (!stopLimit) {

package/src/shared/stores/animation.store.ts

@@ -11,6 +11,8 @@ export type AnimationStoreMap = {
 	closing: SharedValue<number>;
 	entering: SharedValue<number>;
 	targetProgress: SharedValue<number>;
+	/** Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured. */
+	autoSnapPoint: SharedValue<number>;
 };
 
 const store: Record<ScreenKey, AnimationStoreMap> = {};
@@ -20,8 +22,9 @@ function createAnimationBag(): AnimationStoreMap {
 		progress: makeMutable(0),
 		closing: makeMutable(0),
 		animating: makeMutable(0),
-		entering: makeMutable(1),
+		entering: makeMutable(0),
 		targetProgress: makeMutable(1),
+		autoSnapPoint: makeMutable(-1),
 	};
 }
 
@@ -47,6 +50,13 @@ function getRouteAnimation(
 	return ensure(routeKey)[type];
 }
 
+function getAnimation(
+	routeKey: ScreenKey,
+	type: keyof AnimationStoreMap,
+): SharedValue<number> {
+	return getRouteAnimation(routeKey, type);
+}
+
 function getRouteAnimations(routeKey: ScreenKey): AnimationStoreMap {
 	return ensure(routeKey);
 }
@@ -59,11 +69,13 @@ function clear(routeKey: ScreenKey) {
 		cancelAnimation(bag.closing);
 		cancelAnimation(bag.entering);
 		cancelAnimation(bag.targetProgress);
+		cancelAnimation(bag.autoSnapPoint);
 	}
 	delete store[routeKey];
 }
 
 export const AnimationStore = {
+	getAnimation,
 	peekRouteAnimations,
 	getRouteAnimation,
 	getRouteAnimations,

package/src/shared/stores/bounds/internals/resolver.ts

@@ -1,3 +1,4 @@
+import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
 import { matchesScreenKey } from "../helpers/matching";
 import type {
 	ResolvedTransitionPair,
@@ -69,7 +70,11 @@ function findPendingLinkBySource(
 function getSnapshotBoundsByPriority(
 	tag: TagID,
 	keys: (ScreenKey | undefined)[],
-): { bounds: any; screenKey: ScreenKey } | null {
+): {
+	bounds: MeasuredDimensions;
+	styles: StyleProps;
+	screenKey: ScreenKey;
+} | null {
 	"worklet";
 	for (let i = 0; i < keys.length; i++) {
 		const key = keys[i];
@@ -78,6 +83,7 @@ function getSnapshotBoundsByPriority(
 		if (!snapshot) continue;
 		return {
 			bounds: snapshot.bounds,
+			styles: snapshot.styles,
 			screenKey: key,
 		};
 	}
@@ -149,6 +155,8 @@ function resolveTransitionPair(
 
 	let sourceBounds = matchedLink?.source?.bounds ?? null;
 	let destinationBounds = matchedLink?.destination?.bounds ?? null;
+	let sourceStyles = matchedLink?.source?.styles ?? null;
+	let destinationStyles = matchedLink?.destination?.styles ?? null;
 	let sourceScreenKey = matchedLink?.source?.screenKey ?? null;
 	let destinationScreenKey = matchedLink?.destination?.screenKey ?? null;
 	let usedSnapshotSource = false;
@@ -174,6 +182,7 @@ function resolveTransitionPair(
 		const sourceSnapshot = getSnapshotBoundsByPriority(tag, sourceFallbackKeys);
 		if (sourceSnapshot) {
 			sourceBounds = sourceSnapshot.bounds;
+			sourceStyles = sourceSnapshot.styles;
 			sourceScreenKey = sourceSnapshot.screenKey;
 			usedSnapshotSource = true;
 		}
@@ -186,6 +195,7 @@ function resolveTransitionPair(
 		);
 		if (destinationSnapshot) {
 			destinationBounds = destinationSnapshot.bounds;
+			destinationStyles = destinationSnapshot.styles;
 			destinationScreenKey = destinationSnapshot.screenKey;
 			usedSnapshotDestination = true;
 		}
@@ -202,6 +212,8 @@ function resolveTransitionPair(
 	return {
 		sourceBounds,
 		destinationBounds,
+		sourceStyles,
+		destinationStyles,
 		sourceScreenKey,
 		destinationScreenKey,
 		usedPending,

package/src/shared/stores/bounds/types.ts

@@ -43,6 +43,8 @@ export type ResolveTransitionContext = {
 export type ResolvedTransitionPair = {
 	sourceBounds: MeasuredDimensions | null;
 	destinationBounds: MeasuredDimensions | null;
+	sourceStyles: StyleProps | null;
+	destinationStyles: StyleProps | null;
 	sourceScreenKey: ScreenKey | null;
 	destinationScreenKey: ScreenKey | null;
 	usedPending: boolean;