react-native-screen-transitions 3.4.0-alpha.7 → 3.4.0-beta.1

package/src/shared/components/create-boundary-component/index.tsx

@@ -1,5 +1,4 @@
-import { View } from "react-native";
-import { Pressable } from "react-native-gesture-handler";
+import { Pressable, View } from "react-native";
 import { BoundaryTarget } from "./components/boundary-target";
 import { createBoundaryComponent } from "./create-boundary-component";
 
@@ -30,10 +29,16 @@ BoundaryTarget.displayName = "Transition.Boundary.Target";
  * - `Boundary.Target` to measure a nested descendant instead of the owner.
  */
 export const Boundary = {
-	/** Passive boundary wrapper (no built-in press semantics). */
+	/**
+	 * Passive boundary wrapper (no built-in press semantics).
+	 */
 	View: BoundaryView,
-	/** Pressable boundary wrapper with press-priority source capture. */
+	/**
+	 * Pressable boundary wrapper with press-priority source capture.
+	 */
 	Trigger: BoundaryTrigger,
-	/** Optional nested measurement override inside a boundary owner. */
+	/**
+	 * Optional nested measurement override inside a boundary owner.
+	 */
 	Target: BoundaryTarget,
 };

package/src/shared/components/create-boundary-component/types.ts

@@ -43,8 +43,7 @@ export type MeasurementIntent =
 	| "capture-source"
 	| "complete-destination"
 	| "refresh-source"
-	| "refresh-destination"
-	| "snapshot-only";
+	| "refresh-destination";
 
 export interface MaybeMeasureAndStoreParams {
 	intent?: MeasurementIntent | readonly MeasurementIntent[];

package/src/shared/components/create-transition-aware-component.tsx

@@ -1,6 +1,6 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <This helper is usually being used inside a transitionable stack> */
 import type React from "react";
-import { type ComponentType, forwardRef, memo, useCallback } from "react";
+import { type ComponentType, forwardRef, memo } from "react";
 import type { View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, {
@@ -9,13 +9,11 @@ import Animated, {
 	useAnimatedRef,
 	useAnimatedStyle,
 	useComposedEventHandler,
-	useSharedValue,
 } from "react-native-reanimated";
 import { NO_PROPS, NO_STYLES } from "../constants";
 import { useScrollRegistry } from "../hooks/gestures/use-scroll-registry";
 import { RegisterBoundsProvider } from "../providers/register-bounds.provider";
 import { useScreenStyles } from "../providers/screen/styles";
-import { ScrollSettleProvider } from "../providers/scroll-settle.provider";
 import type { TransitionAwareProps } from "../types/screen.types";
 
 interface CreateTransitionAwareComponentOptions {
@@ -45,15 +43,6 @@ export function createTransitionAwareComponent<P extends object>(
 			...scrollableProps
 		} = props;
 
-		const settledSignal = useSharedValue(0);
-
-		const emitScrollSettled = useCallback(() => {
-			runOnUI(() => {
-				"worklet";
-				settledSignal.value = settledSignal.value + 1;
-			})();
-		}, [settledSignal]);
-
 		// Determine scroll direction from the horizontal prop (standard ScrollView API)
 		const scrollDirection = scrollableProps.horizontal
 			? "horizontal"
@@ -72,54 +61,28 @@ export function createTransitionAwareComponent<P extends object>(
 			userOnScroll ?? null,
 		]);
 
-		const handleMomentumScrollEnd = useCallback(
-			(event: unknown) => {
-				userOnMomentumScrollEnd?.(event);
-				emitScrollSettled();
-			},
-			[userOnMomentumScrollEnd, emitScrollSettled],
-		);
-
-		const handleScrollEndDrag = useCallback(
-			(event: any) => {
-				userOnScrollEndDrag?.(event);
-
-				const velocityX = Math.abs(event?.nativeEvent?.velocity?.x ?? 0);
-				const velocityY = Math.abs(event?.nativeEvent?.velocity?.y ?? 0);
-
-				// If there is no momentum, onMomentumScrollEnd may not fire.
-				// Emit settled signal here only when velocity is effectively zero.
-				if (velocityX < 0.01 && velocityY < 0.01) {
-					emitScrollSettled();
-				}
-			},
-			[userOnScrollEndDrag, emitScrollSettled],
-		);
-
 		const scrollableComponent = (
 			<AnimatedComponent
 				{...(scrollableProps as any)}
 				ref={ref}
 				onScroll={composedScrollHandler}
-				onMomentumScrollEnd={handleMomentumScrollEnd}
-				onScrollEndDrag={handleScrollEndDrag}
+				onMomentumScrollEnd={userOnMomentumScrollEnd}
+				onScrollEndDrag={userOnScrollEndDrag}
 				onContentSizeChange={onContentSizeChange}
 				onLayout={onLayout}
 				scrollEventThrottle={scrollableProps.scrollEventThrottle || 16}
 			/>
 		);
 
+		if (!nativeGesture) {
+			return scrollableComponent;
+		}
+
 		// If no gesture owner found for this axis, render without GestureDetector
 		return (
-			<ScrollSettleProvider settledSignal={settledSignal}>
-				{!nativeGesture ? (
-					scrollableComponent
-				) : (
-					<GestureDetector gesture={nativeGesture}>
-						{scrollableComponent}
-					</GestureDetector>
-				)}
-			</ScrollSettleProvider>
+			<GestureDetector gesture={nativeGesture}>
+				{scrollableComponent}
+			</GestureDetector>
 		);
 	});
 

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

@@ -15,15 +15,8 @@ export function useContentLayout() {
 	const { height: screenHeight } = useWindowDimensions();
 	const routeKey = current.route.key;
 	const animations = AnimationStore.getBag(routeKey);
-	const targetProgressValue = SystemStore.getValue(routeKey, "targetProgress");
-	const resolvedAutoSnapPointValue = SystemStore.getValue(
-		routeKey,
-		"resolvedAutoSnapPoint",
-	);
-	const measuredContentLayoutValue = SystemStore.getValue(
-		routeKey,
-		"measuredContentLayout",
-	);
+	const { targetProgress, resolvedAutoSnapPoint, measuredContentLayout } =
+		SystemStore.getBag(routeKey);
 	const experimental_animateOnInitialMount =
 		current.options.experimental_animateOnInitialMount;
 	const transitionSpec = current.options.transitionSpec;
@@ -37,13 +30,13 @@ export function useContentLayout() {
 
 			runOnUI((nextWidth: number, nextHeight: number, nextFraction: number) => {
 				"worklet";
-				measuredContentLayoutValue.value = {
+				measuredContentLayout.value = {
 					width: nextWidth,
 					height: nextHeight,
 				};
 
-				const isFirstMeasurement = resolvedAutoSnapPointValue.value <= 0;
-				resolvedAutoSnapPointValue.value = nextFraction;
+				const isFirstMeasurement = resolvedAutoSnapPoint.value <= 0;
+				resolvedAutoSnapPoint.value = nextFraction;
 
 				if (
 					!isFirstMeasurement ||
@@ -54,7 +47,7 @@ export function useContentLayout() {
 				}
 
 				if (isFirstKey && !experimental_animateOnInitialMount) {
-					targetProgressValue.value = nextFraction;
+					targetProgress.value = nextFraction;
 					animations.progress.value = nextFraction;
 					return;
 				}
@@ -63,15 +56,15 @@ export function useContentLayout() {
 					target: nextFraction,
 					spec: transitionSpec,
 					animations,
-					targetProgress: targetProgressValue,
+					targetProgress,
 				});
 			})(width, height, fraction);
 		},
 		[
 			animations,
-			targetProgressValue,
-			resolvedAutoSnapPointValue,
-			measuredContentLayoutValue,
+			targetProgress,
+			resolvedAutoSnapPoint,
+			measuredContentLayout,
 			isFirstKey,
 			screenHeight,
 			experimental_animateOnInitialMount,

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

@@ -31,11 +31,8 @@ export const BackdropLayer = memo(function BackdropLayer({
 	const BackdropComponent = current.options.backdropComponent;
 	const routeKey = current.route.key;
 	const animations = AnimationStore.getBag(routeKey);
-	const targetProgressValue = SystemStore.getValue(routeKey, "targetProgress");
-	const resolvedAutoSnapPointValue = SystemStore.getValue(
-		routeKey,
-		"resolvedAutoSnapPoint",
-	);
+	const { targetProgress, resolvedAutoSnapPoint } =
+		SystemStore.getBag(routeKey);
 
 	const AnimatedBackdropComponent = useMemo(
 		() =>
@@ -68,7 +65,7 @@ export const BackdropLayer = memo(function BackdropLayer({
 				"worklet";
 				const resolvedSnaps = rawSnapPoints
 					.map((point) =>
-						point === "auto" ? resolvedAutoSnapPointValue.value : point,
+						point === "auto" ? resolvedAutoSnapPoint.value : point,
 					)
 					.filter((point): point is number => typeof point === "number");
 
@@ -94,15 +91,15 @@ export const BackdropLayer = memo(function BackdropLayer({
 					target,
 					spec,
 					animations,
-					targetProgress: targetProgressValue,
+					targetProgress,
 					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
 				});
 			})();
 		}
 	}, [
 		animations,
-		targetProgressValue,
-		resolvedAutoSnapPointValue,
+		targetProgress,
+		resolvedAutoSnapPoint,
 		backdropBehavior,
 		current,
 		dismissScreen,

package/src/shared/components/screen-lifecycle/index.tsx

@@ -20,10 +20,7 @@ export const ScreenLifecycle = ({ children }: Props) => {
 	const { current, previous } = useDescriptors();
 	const { isFirstKey } = useDescriptorDerivations();
 	const animations = AnimationStore.getBag(current.route.key);
-	const targetProgress = SystemStore.getValue(
-		current.route.key,
-		"targetProgress",
-	);
+	const { targetProgress } = SystemStore.getBag(current.route.key);
 
 	const { activateHighRefreshRate, deactivateHighRefreshRate } =
 		useOpenTransition(current, animations, targetProgress, isFirstKey);

package/src/shared/constants.ts

@@ -56,6 +56,7 @@ export const createScreenTransitionState = (
 	progress: 0,
 	closing: 0,
 	animating: 0,
+	willAnimate: 0,
 	settled: 1,
 	logicallySettled: 1,
 	entering: 0,
@@ -79,6 +80,7 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 		progress: 0,
 		closing: 0,
 		animating: 0,
+		willAnimate: 0,
 		settled: 1,
 		logicallySettled: 1,
 		entering: 0,
@@ -105,7 +107,15 @@ export const EMPTY_BOUND_HELPER_RESULT_RAW = Object.freeze({
 	translateY: 0,
 	width: 0,
 	height: 0,
-	...HIDDEN_STYLE,
+});
+export const TRANSFORM_RESET = Object.freeze({
+	transform: [
+		{ translateX: 0 },
+		{ translateY: 0 },
+		{ scale: 1 },
+		{ scaleX: 1 },
+		{ scaleY: 1 },
+	],
 });
 export const ENTER_RANGE = [0, 1] as const;
 export const EXIT_RANGE = [1, 2] as const;

package/src/shared/hooks/reanimated/use-animated-debounce.ts

@@ -0,0 +1,56 @@
+import {
+	cancelAnimation,
+	useAnimatedReaction,
+	useSharedValue,
+	withDelay,
+	withTiming,
+} from "react-native-reanimated";
+
+const SCROLL_SETTLE_DELAY_MS = 25;
+
+interface AnimatedDebounceControls {
+	trigger: () => void;
+	cancel: () => void;
+}
+
+/**
+ * Debounces a UI-thread callback using Reanimated timing primitives.
+ *
+ * Call `trigger()` from a worklet to reset the debounce window. When no new
+ * trigger arrives within `delayMs`, `onDebounced` fires once on the UI thread.
+ */
+export function useAnimatedDebounce(
+	onDebounced: () => void,
+	delayMs: number = SCROLL_SETTLE_DELAY_MS,
+): AnimatedDebounceControls {
+	const token = useSharedValue(0);
+
+	const trigger = () => {
+		"worklet";
+		cancelAnimation(token);
+		token.value = withDelay(
+			delayMs,
+			withTiming(token.value + 1, { duration: 0 }),
+		);
+	};
+
+	const cancel = () => {
+		"worklet";
+		cancelAnimation(token);
+	};
+
+	useAnimatedReaction(
+		() => token.value,
+		(nextToken, previousToken) => {
+			"worklet";
+			if (nextToken === 0 || nextToken === previousToken) {
+				return;
+			}
+
+			onDebounced();
+		},
+		[delayMs, onDebounced],
+	);
+
+	return { trigger, cancel };
+}

package/src/shared/index.ts

@@ -28,6 +28,7 @@ export { snapTo } from "./animation/snap-to";
 export {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
+	TRANSFORM_RESET,
 } from "./constants";
 export {
 	type ScreenGestureTarget,
@@ -47,6 +48,8 @@ export type {
 	AnimatedViewStyle,
 	AnimationConfig,
 	BoundsNavigationAccessor,
+	BoundsNavigationZoomOpacityRange,
+	BoundsNavigationZoomOpacityRanges,
 	BoundsNavigationZoomOptions,
 	BoundsNavigationZoomStyle,
 	OverlayProps,

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

@@ -356,6 +356,7 @@ export const useHandlers = ({
 			lockedSnapPoint.value = resolvedMaxSnapPoint;
 		}
 
+		animations.willAnimate.value = TRUE;
 		gestureAnimationValues.dragging.value = TRUE;
 		gestureAnimationValues.dismissing.value = FALSE;
 		gestureStartProgress.value = animations.progress.value;
@@ -365,6 +366,10 @@ export const useHandlers = ({
 		(event: GestureUpdateEvent<PanGestureHandlerEventPayload>) => {
 			"worklet";
 
+			if (animations.willAnimate.value) {
+				animations.willAnimate.value = FALSE;
+			}
+
 			const { translationX, translationY } = event;
 			const { width, height } = dimensions;
 
@@ -454,6 +459,8 @@ export const useHandlers = ({
 		(event: GestureStateChangeEvent<PanGestureHandlerEventPayload>) => {
 			"worklet";
 
+			animations.willAnimate.value = FALSE;
+
 			if (hasSnapPoints) {
 				const isHorizontal = snapAxis === "horizontal";
 				const axisVelocity = isHorizontal ? event.velocityX : event.velocityY;
@@ -537,6 +544,7 @@ export const useHandlers = ({
 					spec: effectiveSpec,
 					animations,
 					targetProgress: targetProgressValue,
+					emitWillAnimate: false,
 					initialVelocity,
 				});
 			} else {
@@ -579,6 +587,7 @@ export const useHandlers = ({
 					spec: transitionSpec,
 					animations,
 					targetProgress: targetProgressValue,
+					emitWillAnimate: false,
 					initialVelocity: scaledInitialVelocity,
 				});
 			}

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

@@ -16,7 +16,7 @@ import useStableCallbackValue from "../hooks/use-stable-callback-value";
 import { AnimationStore } from "../stores/animation.store";
 import { BoundStore } from "../stores/bounds";
 import { applyMeasuredBoundsWrites } from "../stores/bounds/helpers/apply-measured-bounds-writes";
-import { prepareStyleForBounds } from "../utils/bounds/helpers/styles";
+import { prepareStyleForBounds } from "../utils/bounds/helpers/styles/styles";
 import createProvider from "../utils/create-provider";
 import { useLayoutAnchorContext } from "./layout-anchor.provider";
 import { useDescriptorDerivations, useDescriptors } from "./screen/descriptors";
@@ -417,6 +417,13 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 	},
 );
 
+/**
+ * Legacy bounds registration provider used by transition-aware components.
+ *
+ * @deprecated Prefer the newer bounds system (`Transition.Boundary`, `bounds()`,
+ * and navigation-style bounds helpers) for new code. This provider remains only
+ * for backwards compatibility with the older shared-bound-tag registration path.
+ */
 const RegisterBoundsProvider = registerBoundsBundle.RegisterBoundsProvider;
 useRegisterBoundsContext = registerBoundsBundle.useRegisterBoundsContext;
 

package/src/shared/providers/screen/animation/helpers/hydrate-transition-state.ts

@@ -12,9 +12,12 @@ import type { BaseStackRoute } from "../../../../types/stack.types";
 
 type BuiltState = {
 	progress: SharedValue<number>;
+	willAnimate: SharedValue<number>;
 	closing: SharedValue<number>;
 	animating: SharedValue<number>;
 	entering: SharedValue<number>;
+	settled: SharedValue<number>;
+	logicallySettled: SharedValue<number>;
 	gesture: GestureStoreMap;
 	route: BaseStackRoute;
 	meta?: Record<string, unknown>;
@@ -33,6 +36,16 @@ interface ComputeLogicallySettledParams {
 	dragging: number;
 }
 
+const computeSettled = (params: {
+	animating: number;
+	dismissing: number;
+	closing: number;
+}) => {
+	"worklet";
+	const { animating, dismissing, closing } = params;
+	return animating || dismissing || closing ? FALSE : TRUE;
+};
+
 /**
  * Computes the animated snap index based on progress and snap points.
  * Returns -1 if no snap points, otherwise interpolates between indices.
@@ -90,6 +103,7 @@ export const hydrateTransitionState = (
 	"worklet";
 	const out = s.unwrapped;
 	out.progress = s.progress.value;
+	out.willAnimate = s.willAnimate.value;
 	out.closing = s.closing.value;
 	out.entering = s.entering.value;
 	out.gesture.x = s.gesture.x.value;
@@ -113,7 +127,11 @@ export const hydrateTransitionState = (
 	out.gesture.isDismissing = out.gesture.dismissing;
 	out.gesture.isDragging = out.gesture.dragging;
 
-	out.settled = out.animating || out.gesture.dismissing || out.closing ? 0 : 1;
+	out.settled = computeSettled({
+		animating: out.animating,
+		dismissing: out.gesture.dismissing,
+		closing: out.closing,
+	});
 	out.logicallySettled = computeLogicallySettled({
 		progress: out.progress,
 		targetProgress: s.targetProgress.value,
@@ -121,6 +139,14 @@ export const hydrateTransitionState = (
 		dragging: out.gesture.dragging,
 	});
 
+	if (s.settled.value !== out.settled) {
+		s.settled.value = out.settled;
+	}
+
+	if (s.logicallySettled.value !== out.logicallySettled) {
+		s.logicallySettled.value = out.logicallySettled;
+	}
+
 	out.meta = s.meta;
 	out.layouts.screen.width = dimensions.width;
 	out.layouts.screen.height = dimensions.height;

package/src/shared/providers/screen/animation/helpers/use-build-transition-state.ts

@@ -17,9 +17,12 @@ import { toPlainRoute, toPlainValue } from "./worklet";
 
 type BuiltState = {
 	progress: SharedValue<number>;
+	willAnimate: SharedValue<number>;
 	closing: SharedValue<number>;
 	animating: SharedValue<number>;
 	entering: SharedValue<number>;
+	settled: SharedValue<number>;
+	logicallySettled: SharedValue<number>;
 	gesture: GestureStoreMap;
 	route: BaseStackRoute;
 	meta?: Record<string, unknown>;
@@ -60,9 +63,12 @@ export const useBuildTransitionState = (
 
 		return {
 			progress: AnimationStore.getValue(key, "progress"),
+			willAnimate: AnimationStore.getValue(key, "willAnimate"),
 			closing: AnimationStore.getValue(key, "closing"),
 			entering: AnimationStore.getValue(key, "entering"),
 			animating: AnimationStore.getValue(key, "animating"),
+			settled: AnimationStore.getValue(key, "settled"),
+			logicallySettled: AnimationStore.getValue(key, "logicallySettled"),
 			targetProgress: SystemStore.getValue(key, "targetProgress"),
 			resolvedAutoSnapPoint: SystemStore.getValue(key, "resolvedAutoSnapPoint"),
 			measuredContentLayout: SystemStore.getValue(key, "measuredContentLayout"),

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

@@ -44,9 +44,6 @@ export const {
 
 		const isGesturingDuringCloseAnimation = useSharedValue(false);
 		const hasWarnedLegacy = useSharedValue(false);
-		const previousLayerStyleKeysBySlot = useSharedValue<
-			Record<string, StyleKeySet>
-		>({});
 		const previousElementStyleKeysBySlot = useSharedValue<
 			Record<string, StyleKeySet>
 		>({});
@@ -134,15 +131,7 @@ export const {
 		const layerStylesMap =
 			useDerivedValue<NormalizedTransitionInterpolatedStyle>(() => {
 				"worklet";
-				const { resolvedStylesMap, nextPreviousStyleKeysBySlot } =
-					buildResolvedStyleMap({
-						currentStylesMap: rawStyleResolution.value.layerStylesMap,
-						fallbackStylesMap: NO_STYLES,
-						previousStyleKeysBySlot: previousLayerStyleKeysBySlot.value,
-					});
-
-				previousLayerStyleKeysBySlot.value = nextPreviousStyleKeysBySlot;
-				return resolvedStylesMap;
+				return rawStyleResolution.value.layerStylesMap;
 			});
 
 		const elementStylesMap =

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

@@ -7,31 +7,40 @@ import { createStore } from "../utils/create-store";
 
 export type AnimationStoreMap = {
 	progress: SharedValue<number>;
+	willAnimate: SharedValue<number>;
 	animating: SharedValue<number>;
 	closing: SharedValue<number>;
 	entering: SharedValue<number>;
+	settled: SharedValue<number>;
+	logicallySettled: SharedValue<number>;
 };
 
 function createAnimationBag(): AnimationStoreMap {
 	return {
 		progress: makeMutable(0),
+		willAnimate: makeMutable(0),
 		closing: makeMutable(0),
 		animating: makeMutable(0),
 		entering: makeMutable(0),
+		settled: makeMutable(1),
+		logicallySettled: makeMutable(1),
 	};
 }
 
 /**
  * Route-keyed screen transition state for the public animation lifecycle. These
- * shared values track the current progress and whether a screen is entering,
- * closing, or actively animating.
+ * shared values track the current progress, whether a transition is about to
+ * begin, and whether a screen is entering, closing, or actively animating.
  */
 export const AnimationStore = createStore<AnimationStoreMap>({
 	createBag: createAnimationBag,
 	disposeBag: (bag) => {
 		cancelAnimation(bag.progress);
+		cancelAnimation(bag.willAnimate);
 		cancelAnimation(bag.animating);
 		cancelAnimation(bag.closing);
 		cancelAnimation(bag.entering);
+		cancelAnimation(bag.settled);
+		cancelAnimation(bag.logicallySettled);
 	},
 });