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

package/src/shared/components/create-boundary-component/hooks/helpers/scroll-measurement.ts

@@ -0,0 +1,58 @@
+import type { View } from "react-native";
+import {
+	type AnimatedRef,
+	type MeasuredDimensions,
+	measure,
+} from "react-native-reanimated";
+import type {
+	ScrollGestureAxisState,
+	ScrollGestureState,
+} from "../../../../types/gesture.types";
+
+const SCROLL_MEASUREMENT_EPSILON = 1;
+
+const getOverscrollDelta = (axisState: ScrollGestureAxisState): number => {
+	"worklet";
+	const maxOffset = Math.max(0, axisState.contentSize - axisState.layoutSize);
+	const clampedOffset = Math.min(Math.max(axisState.offset, 0), maxOffset);
+	const delta = axisState.offset - clampedOffset;
+
+	return Math.abs(delta) > SCROLL_MEASUREMENT_EPSILON ? delta : 0;
+};
+
+export const adjustedMeasuredBoundsForOverscrollDeltas = (
+	measured: MeasuredDimensions,
+	scrollState: ScrollGestureState | null,
+): MeasuredDimensions => {
+	"worklet";
+
+	if (!scrollState) {
+		return measured;
+	}
+
+	const deltaX = getOverscrollDelta(scrollState.horizontal);
+	const deltaY = getOverscrollDelta(scrollState.vertical);
+
+	if (deltaX === 0 && deltaY === 0) {
+		return measured;
+	}
+
+	return {
+		...measured,
+		x: measured.x + deltaX,
+		y: measured.y + deltaY,
+		pageX: measured.pageX + deltaX,
+		pageY: measured.pageY + deltaY,
+	};
+};
+
+export const measureWithOverscrollAwareness = (
+	ref: AnimatedRef<View>,
+	scrollState: ScrollGestureState | null,
+): MeasuredDimensions | null => {
+	"worklet";
+	const measured = measure(ref);
+	if (!measured) return null;
+
+	return adjustedMeasuredBoundsForOverscrollDeltas(measured, scrollState);
+};

package/src/shared/components/create-boundary-component/hooks/use-boundary-presence.ts

@@ -3,7 +3,7 @@ import { runOnUI } from "react-native-reanimated";
 import {
 	removeEntry,
 	setEntry,
-} from "../../../stores/bounds/internals/registry";
+} from "../../../stores/bounds/internals/entries";
 import type { BoundaryConfigProps } from "../types";
 
 export const useBoundaryPresence = (params: {

package/src/shared/components/create-boundary-component/hooks/{use-capture-destination-boundary.ts → use-initial-destination-measurement.ts}

@@ -1,47 +1,36 @@
-import { useLayoutEffect } from "react";
 import {
 	cancelAnimation,
-	runOnUI,
 	useAnimatedReaction,
 	useSharedValue,
 	withDelay,
 	withTiming,
 } from "react-native-reanimated";
 import { AnimationStore } from "../../../stores/animation.store";
-import { getGroupActiveId } from "../../../stores/bounds/internals/groups";
+import { hasDestinationLink } from "../../../stores/bounds/internals/links";
 import {
-	getPendingLink,
-	hasDestinationLink,
-	hasSourceLink,
-} from "../../../stores/bounds/internals/registry";
-import { SystemStore } from "../../../stores/system.store";
-import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
-import type { BoundaryId, MeasureParams } from "../types";
+	LifecycleTransitionRequestKind,
+	SystemStore,
+} from "../../../stores/system.store";
+import type { MeasureParams } from "../types";
 
 const VIEWPORT_RETRY_DELAY_MS = 16;
 
-interface UseCaptureDestinationBoundaryParams {
+interface UseInitialDestinationMeasurementParams {
 	sharedBoundTag: string;
 	enabled: boolean;
-	id: BoundaryId;
-	group?: string;
 	currentScreenKey: string;
-	expectedSourceScreenKey?: string;
 	measureBoundary: (options: MeasureParams) => void;
 }
 
-export const useCaptureDestinationBoundary = ({
+export const useInitialDestinationMeasurement = ({
 	sharedBoundTag,
 	enabled,
-	id,
-	group,
 	currentScreenKey,
-	expectedSourceScreenKey,
 	measureBoundary,
-}: UseCaptureDestinationBoundaryParams) => {
-	const animating = AnimationStore.getValue(currentScreenKey, "animating");
-	const closing = AnimationStore.getValue(currentScreenKey, "closing");
+}: UseInitialDestinationMeasurementParams) => {
+	const progress = AnimationStore.getValue(currentScreenKey, "progress");
 	const system = SystemStore.getBag(currentScreenKey);
+	const { pendingLifecycleRequestKind } = system;
 	const { blockLifecycleStart, unblockLifecycleStart } = system.actions;
 	const isBlockingLifecycleStart = useSharedValue(0);
 	const retryToken = useSharedValue(0);
@@ -84,37 +73,27 @@ export const useCaptureDestinationBoundary = ({
 			"worklet";
 			const retryTick = retryToken.get();
 
-			if (closing.get() || animating.get()) {
+			const hasPendingOpenRequest =
+				pendingLifecycleRequestKind.get() ===
+				LifecycleTransitionRequestKind.Open;
+
+			const isWaitingForOpenToStart = progress.get() <= 0;
+
+			if (!hasPendingOpenRequest || !isWaitingForOpenToStart) {
 				return [0, retryTick] as const;
 			}
 
-			const resolvedSourceKey = resolvePendingSourceKey(
-				sharedBoundTag,
-				expectedSourceScreenKey,
-			);
-			const hasAttachableSourceLink = resolvedSourceKey
-				? getPendingLink(sharedBoundTag, resolvedSourceKey) !== null ||
-					hasSourceLink(sharedBoundTag, resolvedSourceKey)
-				: false;
 			const hasDestination = hasDestinationLink(
 				sharedBoundTag,
 				currentScreenKey,
 			);
 
-			const shouldBlock =
-				enabled &&
-				!!resolvedSourceKey &&
-				hasAttachableSourceLink &&
-				!hasDestination;
+			const shouldBlock = enabled && !hasDestination;
 
 			if (!shouldBlock) {
 				return [0, retryTick] as const;
 			}
 
-			if (group && getGroupActiveId(group) !== String(id)) {
-				return [0, retryTick] as const;
-			}
-
 			return [1, retryTick] as const;
 		},
 		([shouldBlock]) => {
@@ -135,20 +114,4 @@ export const useCaptureDestinationBoundary = ({
 			scheduleViewportRetry();
 		},
 	);
-
-	useLayoutEffect(() => {
-		return () => {
-			runOnUI(() => {
-				"worklet";
-				cancelAnimation(retryToken);
-
-				if (!isBlockingLifecycleStart.get()) {
-					return;
-				}
-
-				unblockLifecycleStart();
-				isBlockingLifecycleStart.set(0);
-			})();
-		};
-	}, [isBlockingLifecycleStart, retryToken, unblockLifecycleStart]);
 };

package/src/shared/components/create-boundary-component/hooks/use-initial-source-measurement.ts

@@ -0,0 +1,27 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import type { MeasureParams } from "../types";
+
+export const useInitialSourceMeasurement = (params: {
+	enabled: boolean;
+	nextScreenKey?: string;
+	measureBoundary: (options: MeasureParams) => void;
+}) => {
+	const { enabled, nextScreenKey, measureBoundary } = params;
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled || !nextScreenKey) {
+				return 0;
+			}
+
+			return nextScreenKey;
+		},
+		(captureSignal) => {
+			"worklet";
+			if (!enabled || !captureSignal) return;
+
+			measureBoundary({ intent: "capture-source" });
+		},
+	);
+};

package/src/shared/components/create-boundary-component/hooks/use-measurer.ts

@@ -1,28 +1,18 @@
 import { useCallback } from "react";
 import type { View } from "react-native";
 import { useWindowDimensions } from "react-native";
-import {
-	type AnimatedRef,
-	measure,
-	type StyleProps,
-} from "react-native-reanimated";
-import { applyMeasuredBoundsWrites } from "../../../stores/bounds/helpers/apply-measured-bounds-writes";
-import {
-	getMeasuredEntry,
-	getPendingLink,
-	hasDestinationLink,
-	hasSourceLink,
-} from "../../../stores/bounds/internals/registry";
-import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
+import type { AnimatedRef, StyleProps } from "react-native-reanimated";
+import { ScrollStore } from "../../../stores/scroll.store";
+import { SystemStore } from "../../../stores/system.store";
+import { applyMeasuredBoundsWrites } from "../helpers/apply-measured-bounds-writes";
 import type { MeasureParams } from "../types";
+import { createLinkContext } from "./helpers/boundary-link-context";
+import { isMeasurementInViewport } from "./helpers/measurement";
 import {
-	areMeasurementsEqual,
-	isMeasurementInViewport,
-} from "./helpers/measurement";
-import {
+	buildMeasurementWritePlan,
 	getMeasureIntentFlags,
-	resolveMeasureWritePlan,
 } from "./helpers/measurement-rules";
+import { measureWithOverscrollAwareness } from "./helpers/scroll-measurement";
 
 interface UseMeasurerParams {
 	enabled: boolean;
@@ -50,64 +40,77 @@ export const useMeasurer = ({
 	const { width: viewportWidth, height: viewportHeight } =
 		useWindowDimensions();
 
+	const scrollState = ScrollStore.getValue(currentScreenKey, "state");
+	const pendingLifecycleStartBlockCount = SystemStore.getValue(
+		currentScreenKey,
+		"pendingLifecycleStartBlockCount",
+	);
+
 	return useCallback(
 		({ intent }: MeasureParams = {}) => {
 			"worklet";
 			if (!enabled) return;
 
 			const intents = getMeasureIntentFlags(intent);
-
-			const expectedSourceScreenKey: string | undefined =
-				resolvePendingSourceKey(sharedBoundTag, preferredSourceScreenKey) ||
-				undefined;
-
-			const pendingLink = expectedSourceScreenKey
-				? getPendingLink(sharedBoundTag, expectedSourceScreenKey)
-				: getPendingLink(sharedBoundTag);
-			const hasPendingLink = pendingLink !== null;
-			const hasAttachableSourceLink = expectedSourceScreenKey
-				? hasSourceLink(sharedBoundTag, expectedSourceScreenKey)
-				: false;
-			const hasSource = hasSourceLink(sharedBoundTag, currentScreenKey);
-			const hasDestination = hasDestinationLink(
+			const currentLink = createLinkContext({
 				sharedBoundTag,
 				currentScreenKey,
-			);
+				preferredSourceScreenKey,
+			});
 
-			const writePlan = resolveMeasureWritePlan({
+			const writePlan = buildMeasurementWritePlan({
 				intents,
-				hasPendingLink,
-				hasSourceLink: hasSource,
-				hasDestinationLink: hasDestination,
-				hasAttachableSourceLink,
+				hasPendingLink: currentLink.hasPendingLink,
+				hasSourceLink: currentLink.hasSourceLink,
+				hasDestinationLink: currentLink.hasDestinationLink,
+				hasAttachableSourceLink: currentLink.hasAttachableSourceLink,
 			});
 
-			if (!writePlan.writesAny) {
-				return;
-			}
+			if (!writePlan.writesAny) return;
+
+			const measured = measureWithOverscrollAwareness(
+				measuredAnimatedRef,
+				scrollState.get(),
+			);
 
-			const measured = measure(measuredAnimatedRef);
 			if (!measured) return;
 
-			const destinationInViewport =
-				!writePlan.wantsDestinationWrite ||
+			/**
+			 * Source Pass
+			 * Source intents are intentionally used & kept unguarded.
+			 */
+			const sourceWrites = {
+				shouldSetSource: writePlan.captureSource,
+				shouldUpdateSource: writePlan.refreshSource,
+			};
+
+			/**
+			 * - Destination Pass -
+			 * Be strict while lifecycle start is blocked for destination capture.
+			 * This is the initial attach window: the transition has not started yet,
+			 * and malformed off-screen destination measurements should keep the
+			 * lifecycle blocked until a valid retry lands.
+			 */
+			const shouldGuardDestinationViewport =
+				pendingLifecycleStartBlockCount.get() > 0;
+			const viewportAllowsDestinationWrite =
+				!shouldGuardDestinationViewport ||
 				isMeasurementInViewport(measured, viewportWidth, viewportHeight);
 
-			if (
-				!destinationInViewport &&
-				!writePlan.captureSource &&
-				!writePlan.refreshSource
-			) {
-				return;
-			}
+			const destinationWrites = {
+				shouldSetDestination:
+					viewportAllowsDestinationWrite && writePlan.completeDestination,
+				shouldUpdateDestination:
+					viewportAllowsDestinationWrite && writePlan.refreshDestination,
+			};
 
-			const existingMeasuredEntry = getMeasuredEntry(
-				sharedBoundTag,
-				currentScreenKey,
-			);
-			const hasMeasuredEntryChanged =
-				!existingMeasuredEntry ||
-				!areMeasurementsEqual(existingMeasuredEntry.bounds, measured);
+			const shouldApplyMeasurement =
+				sourceWrites.shouldSetSource ||
+				sourceWrites.shouldUpdateSource ||
+				destinationWrites.shouldSetDestination ||
+				destinationWrites.shouldUpdateDestination;
+
+			if (!shouldApplyMeasurement) return;
 
 			applyMeasuredBoundsWrites({
 				sharedBoundTag,
@@ -117,16 +120,9 @@ export const useMeasurer = ({
 				ancestorKeys,
 				navigatorKey,
 				ancestorNavigatorKeys,
-				expectedSourceScreenKey,
-				shouldWriteEntry: hasMeasuredEntryChanged,
-				shouldSetSource: writePlan.captureSource,
-				shouldUpdateSource: writePlan.refreshSource && hasMeasuredEntryChanged,
-				shouldUpdateDestination:
-					writePlan.refreshDestination &&
-					destinationInViewport &&
-					hasMeasuredEntryChanged,
-				shouldSetDestination:
-					writePlan.completeDestination && destinationInViewport,
+				expectedSourceScreenKey: currentLink.expectedSourceScreenKey,
+				...sourceWrites,
+				...destinationWrites,
 			});
 		},
 		[
@@ -141,6 +137,8 @@ export const useMeasurer = ({
 			measuredAnimatedRef,
 			viewportWidth,
 			viewportHeight,
+			scrollState,
+			pendingLifecycleStartBlockCount,
 		],
 	);
 };

package/src/shared/components/create-boundary-component/hooks/use-refresh-boundary.ts

@@ -1,8 +1,10 @@
 import { useAnimatedReaction } from "react-native-reanimated";
 import { AnimationStore } from "../../../stores/animation.store";
 import { getGroupActiveId } from "../../../stores/bounds/internals/groups";
-import { hasSourceLink } from "../../../stores/bounds/internals/registry";
-import { GestureStore } from "../../../stores/gesture.store";
+import {
+	hasDestinationLink,
+	hasSourceLink,
+} from "../../../stores/bounds/internals/links";
 import type { BoundaryId, MeasureParams } from "../types";
 
 interface UseRefreshBoundaryParams {
@@ -30,63 +32,63 @@ export const useRefreshBoundary = ({
 		currentScreenKey,
 		"willAnimate",
 	);
+	const currentClosing = AnimationStore.getValue(currentScreenKey, "closing");
+	const currentEntering = AnimationStore.getValue(currentScreenKey, "entering");
 	const currentAnimating = AnimationStore.getValue(
 		currentScreenKey,
 		"animating",
 	);
-	const currentDragging = GestureStore.getValue(currentScreenKey, "dragging");
+	const currentProgress = AnimationStore.getValue(currentScreenKey, "progress");
 	const nextWillAnimate = nextScreenKey
 		? AnimationStore.getValue(nextScreenKey, "willAnimate")
 		: null;
-	const nextAnimating = nextScreenKey
-		? AnimationStore.getValue(nextScreenKey, "animating")
+
+	const nextClosing = nextScreenKey
+		? AnimationStore.getValue(nextScreenKey, "closing")
 		: null;
-	const nextDragging = nextScreenKey
-		? GestureStore.getValue(nextScreenKey, "dragging")
+	const nextEntering = nextScreenKey
+		? AnimationStore.getValue(nextScreenKey, "entering")
 		: null;
 
 	useAnimatedReaction(
-		() => (hasNextScreen ? (nextWillAnimate?.get() ?? 0) : 0),
-		(nextValue, previousValue) => {
+		() => {
 			"worklet";
-			if (!enabled || !hasNextScreen) return;
-			if (nextValue === 0 || nextValue === previousValue) return;
-
-			const currentGroupActiveId = group ? getGroupActiveId(group) : null;
-
-			if (group && currentGroupActiveId !== String(id)) {
-				return;
-			}
-
-			const shouldCancelMeasurement =
-				!!nextAnimating?.get() && !!nextDragging?.get();
 
-			if (shouldCancelMeasurement) {
-				return;
+			const shouldRefresh = hasNextScreen
+				? (nextWillAnimate?.get() ?? 0)
+				: currentWillAnimate.get();
+			const closing = hasNextScreen
+				? (nextClosing?.get() ?? 0)
+				: currentClosing.get();
+			const entering = hasNextScreen
+				? (nextEntering?.get() ?? 0)
+				: currentEntering.get();
+
+			// Programmatic close marks `closing` before pulsing `willAnimate`.
+			// This frame is still settled, so destination refresh is valid and
+			// reveal can compute initial/current destination delta before progress moves.
+			const canRefreshPreCloseDestination =
+				!hasNextScreen &&
+				shouldRefresh &&
+				closing &&
+				!entering &&
+				!currentAnimating.get() &&
+				currentProgress.get() >= 1;
+
+			if (
+				canRefreshPreCloseDestination ||
+				(shouldRefresh && !closing && !entering)
+			) {
+				return 1;
 			}
 
-			const hasSource = hasSourceLink(sharedBoundTag, currentScreenKey);
-
-			const intent = !hasSource
-				? "capture-source"
-				: group
-					? "refresh-source"
-					: null;
-
-			if (!intent) {
-				return;
-			}
-
-			measureBoundary({ intent });
+			return 0;
 		},
-	);
-
-	useAnimatedReaction(
-		() => (!hasNextScreen ? currentWillAnimate.get() : 0),
-		(nextValue, previousValue) => {
+		(shouldRefresh, prevShouldRefresh) => {
 			"worklet";
-			if (!enabled || hasNextScreen) return;
-			if (nextValue === 0 || nextValue === previousValue) return;
+
+			if (!enabled || !shouldRefresh || shouldRefresh === prevShouldRefresh)
+				return;
 
 			const currentGroupActiveId = group ? getGroupActiveId(group) : null;
 
@@ -94,15 +96,21 @@ export const useRefreshBoundary = ({
 				return;
 			}
 
-			const shouldCancelMeasurement =
-				!!currentAnimating.get() && !!currentDragging.get();
+			if (hasNextScreen) {
+				if (
+					!nextScreenKey ||
+					!hasSourceLink(sharedBoundTag, currentScreenKey) ||
+					!hasDestinationLink(sharedBoundTag, nextScreenKey)
+				) {
+					return;
+				}
 
-			if (shouldCancelMeasurement) {
+				measureBoundary({ intent: "refresh-source" });
 				return;
 			}
 
 			measureBoundary({
-				intent: ["complete-destination", "refresh-destination"] as const,
+				intent: "refresh-destination",
 			});
 		},
 	);

package/src/shared/components/create-boundary-component/providers/boundary-owner.provider.tsx

@@ -10,7 +10,7 @@ import {
 } from "react";
 import type { View } from "react-native";
 import type Animated from "react-native-reanimated";
-import type { AnimatedRef } from "react-native-reanimated";
+import type { AnimatedRef, StyleProps } from "react-native-reanimated";
 
 type BoundaryAssociatedStyle = React.ComponentProps<
 	typeof Animated.View
@@ -18,12 +18,20 @@ type BoundaryAssociatedStyle = React.ComponentProps<
 
 interface BoundaryOwnerContextValue {
 	ownerRef: AnimatedRef<View>;
-	registerTargetRef: (targetRef: AnimatedRef<View>) => void;
+	registerTargetRef: (
+		targetRef: AnimatedRef<View>,
+		preparedStyles: StyleProps,
+	) => void;
 	unregisterTargetRef: (targetRef: AnimatedRef<View>) => void;
 	activeTargetRef: AnimatedRef<View> | null;
 	associatedTargetStyles?: BoundaryAssociatedStyle;
 }
 
+type BoundaryTargetEntry = {
+	ref: AnimatedRef<View>;
+	preparedStyles: StyleProps;
+};
+
 const BoundaryOwnerContext = createContext<BoundaryOwnerContextValue | null>(
 	null,
 );
@@ -57,31 +65,34 @@ export const useBoundaryOwner = (params: {
 }) => {
 	const { ownerRef, associatedTargetStyles } = params;
 	const warnedAboutMultipleTargetsRef = useRef(false);
-	const [targetRefs, setTargetRefs] = useState<AnimatedRef<View>[]>([]);
-
-	const registerTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
-		setTargetRefs((prev) => {
-			if (prev.includes(targetRef)) {
-				return prev;
-			}
-
-			if (
-				__DEV__ &&
-				prev.length > 0 &&
-				!warnedAboutMultipleTargetsRef.current
-			) {
-				warnedAboutMultipleTargetsRef.current = true;
-				console.warn(MULTIPLE_TARGETS_WARNING);
-			}
-
-			return [...prev, targetRef];
-		});
-	}, []);
+	const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
+		null,
+	);
+
+	const registerTargetRef = useCallback(
+		(targetRef: AnimatedRef<View>, preparedStyles: StyleProps) => {
+			setTargetEntry((prev) => {
+				if (prev?.ref === targetRef) {
+					return prev;
+				}
+
+				if (
+					__DEV__ &&
+					prev !== null &&
+					!warnedAboutMultipleTargetsRef.current
+				) {
+					warnedAboutMultipleTargetsRef.current = true;
+					console.warn(MULTIPLE_TARGETS_WARNING);
+				}
+
+				return prev ?? { ref: targetRef, preparedStyles };
+			});
+		},
+		[],
+	);
 
 	const unregisterTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
-		setTargetRefs((prev) =>
-			prev.filter((existingRef) => existingRef !== targetRef),
-		);
+		setTargetEntry((prev) => (prev?.ref === targetRef ? null : prev));
 	}, []);
 
 	const contextValue = useMemo(
@@ -89,21 +100,22 @@ export const useBoundaryOwner = (params: {
 			ownerRef,
 			registerTargetRef,
 			unregisterTargetRef,
-			activeTargetRef: targetRefs[0] ?? null,
+			activeTargetRef: targetEntry?.ref ?? null,
 			associatedTargetStyles,
 		}),
 		[
 			ownerRef,
 			registerTargetRef,
 			unregisterTargetRef,
-			targetRefs,
+			targetEntry,
 			associatedTargetStyles,
 		],
 	);
 
 	return {
 		contextValue,
-		hasActiveTarget: targetRefs.length > 0,
-		measuredRef: targetRefs[0] ?? ownerRef,
+		hasActiveTarget: targetEntry !== null,
+		measuredRef: targetEntry?.ref ?? ownerRef,
+		targetPreparedStyles: targetEntry?.preparedStyles,
 	};
 };

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

@@ -1,4 +1,3 @@
-import type { ViewProps } from "react-native";
 import type { BoundsOptions } from "../../utils/bounds/types/options";
 
 export type BoundaryId = string | number;
@@ -36,19 +35,12 @@ export interface BoundaryOwnProps extends BoundaryConfigProps {
 export type BoundaryComponentProps<P extends object> = Omit<P, "id"> &
 	BoundaryOwnProps;
 
-/** Convenience alias for a View-based boundary (the most common case). */
-export type BoundaryProps = BoundaryComponentProps<ViewProps>;
-
 export type MeasureIntent =
 	| "capture-source"
 	| "complete-destination"
 	| "refresh-source"
 	| "refresh-destination";
 
-export type MeasurementIntent = MeasureIntent;
-
 export interface MeasureParams {
 	intent?: MeasureIntent | readonly MeasureIntent[];
 }
-
-export interface MaybeMeasureAndStoreParams extends MeasureParams {}