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

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

@@ -1,8 +1,8 @@
-import { useMemo } from "react";
 import { useWindowDimensions } from "react-native";
 import {
+	type DerivedValue,
 	type SharedValue,
-	useAnimatedReaction,
+	useDerivedValue,
 	useSharedValue,
 } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
@@ -12,41 +12,50 @@ import type {
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
 } from "../../../../types/animation.types";
-import type { BoundsAccessor } from "../../../../types/bounds.types";
 
-import { createBoundsAccessor } from "../../../../utils/bounds";
 import { useDescriptors } from "../../descriptors";
-import { derivations } from "./derivations";
+import { updateDerivations } from "./derivations";
 import { hasTransitionsEnabled } from "./has-transitions-enabled";
 import { hydrateTransitionState } from "./hydrate-transition-state";
+import type { SelectedInterpolatorOptions } from "./selected-interpolator-options";
 import { useBuildTransitionState } from "./use-build-transition-state";
 
-export type ScreenInterpolatorFrame = Omit<ScreenInterpolationProps, "bounds">;
+export type ScreenInterpolatorFrame = Omit<
+	ScreenInterpolationProps,
+	"bounds" | "transition"
+>;
 
 interface ScreenAnimationPipeline {
 	screenInterpolatorProps: SharedValue<ScreenInterpolatorFrame>;
+	screenInterpolatorPropsRevision: DerivedValue<number>;
+	selectedInterpolatorOptions: SharedValue<SelectedInterpolatorOptions>;
 	nextInterpolator: ScreenStyleInterpolator | undefined;
 	currentInterpolator: ScreenStyleInterpolator | undefined;
-	boundsAccessor: BoundsAccessor;
 }
 
 const createInitialBaseInterpolatorProps = (
 	dimensions: ScreenInterpolatorFrame["layouts"]["screen"],
 	insets: ScreenInterpolatorFrame["insets"],
-): ScreenInterpolatorFrame => ({
-	layouts: { screen: dimensions, navigationMaskEnabled: false },
-	insets,
-	previous: undefined,
-	current: DEFAULT_SCREEN_TRANSITION_STATE,
-	next: undefined,
-	progress: 0,
-	stackProgress: 0,
-	snapIndex: -1,
-	logicallySettled: 1,
-	focused: true,
-	active: DEFAULT_SCREEN_TRANSITION_STATE,
-	inactive: undefined,
-});
+): ScreenInterpolatorFrame => {
+	const current = {
+		...DEFAULT_SCREEN_TRANSITION_STATE,
+		layouts: { screen: dimensions, navigationMaskEnabled: false },
+	};
+
+	return {
+		layouts: current.layouts,
+		insets,
+		previous: undefined,
+		current,
+		next: undefined,
+		progress: 0,
+		stackProgress: 0,
+		logicallySettled: 1,
+		focused: true,
+		active: current,
+		inactive: undefined,
+	};
+};
 
 export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 	const { flags, stackProgress: rootStackProgress, routeKeys } = useStack();
@@ -60,9 +69,9 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 		previous: prevDescriptor,
 	} = useDescriptors();
 
-	const currentAnimation = useBuildTransitionState(currDescriptor, "current");
-	const nextAnimation = useBuildTransitionState(nextDescriptor, "next");
-	const prevAnimation = useBuildTransitionState(prevDescriptor, "previous");
+	const currentAnimation = useBuildTransitionState(currDescriptor);
+	const nextAnimation = useBuildTransitionState(nextDescriptor);
+	const prevAnimation = useBuildTransitionState(prevDescriptor);
 
 	const currentRouteKey = currDescriptor?.route?.key;
 	const currentIndex = routeKeys.indexOf(currentRouteKey);
@@ -72,102 +81,90 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 		!!nextRouteKey &&
 		hasTransitionsEnabled(nextDescriptor?.options, transitionsAlwaysOn);
 
-	const screenInterpolatorProps = useSharedValue<ScreenInterpolatorFrame>(
+	const screenInterpolatorProps = useSharedValue(
 		createInitialBaseInterpolatorProps(dimensions, insets),
 	);
-
-	const boundsAccessor = useMemo(() => {
-		return createBoundsAccessor(() => {
-			"worklet";
-			return screenInterpolatorProps.get();
+	const selectedInterpolatorOptions =
+		useSharedValue<SelectedInterpolatorOptions>({
+			owner: "current",
 		});
-	}, [screenInterpolatorProps]);
 
-	useAnimatedReaction(
-		() => {
-			"worklet";
+	const propsRevisionState = useSharedValue({ value: 0 });
+	const screenInterpolatorPropsRevision = useDerivedValue<number>(() => {
+		"worklet";
 
-			const previous = prevAnimation
+		screenInterpolatorProps.modify((frame) => {
+			"worklet";
+			const interpolatorOptions = selectedInterpolatorOptions.get();
+			const shouldApplyOptionsToCurrent =
+				interpolatorOptions.owner === "current";
+			const shouldApplyOptionsToNext =
+				interpolatorOptions.owner === "next" &&
+				!!nextAnimation &&
+				nextHasTransitions;
+
+			frame.previous = prevAnimation
 				? hydrateTransitionState(prevAnimation, dimensions)
 				: undefined;
 
-			const next =
+			frame.current = currentAnimation
+				? hydrateTransitionState(
+						currentAnimation,
+						dimensions,
+						shouldApplyOptionsToCurrent
+							? interpolatorOptions.options
+							: undefined,
+					)
+				: DEFAULT_SCREEN_TRANSITION_STATE;
+
+			frame.next =
 				nextAnimation && nextHasTransitions
-					? hydrateTransitionState(nextAnimation, dimensions)
+					? hydrateTransitionState(
+							nextAnimation,
+							dimensions,
+							shouldApplyOptionsToNext
+								? interpolatorOptions.options
+								: undefined,
+						)
 					: undefined;
 
-			const current = currentAnimation
-				? hydrateTransitionState(currentAnimation, dimensions)
-				: DEFAULT_SCREEN_TRANSITION_STATE;
+			frame.layouts = frame.current.layouts;
+			frame.insets = insets;
 
-			const { progress, ...helpers } = derivations({
-				previous,
-				current,
-				next,
-			});
-
-			const stackProgress =
-				currentIndex >= 0 ? rootStackProgress.get() - currentIndex : progress;
-
-			const focused = helpers.focused;
-			const active = helpers.active;
-			const inactive = helpers.inactive;
-			const snapIndex = current.snapIndex;
-			const logicallySettled = active.logicallySettled;
-
-			return {
-				previous,
-				current,
-				next,
-				progress,
-				stackProgress,
-				snapIndex,
-				logicallySettled,
-				focused,
-				active,
-				inactive,
-			};
-		},
-		({
-			previous,
-			current,
-			next,
-			progress,
-			stackProgress,
-			snapIndex,
-			logicallySettled,
-			focused,
-			active,
-			inactive,
-		}) => {
+			updateDerivations(frame);
+
+			frame.stackProgress =
+				currentIndex >= 0
+					? rootStackProgress.get() - currentIndex
+					: frame.progress;
+			frame.logicallySettled = frame.active.logicallySettled;
+
+			return frame;
+		}, false);
+
+		// Critical reactive dependency for `screenInterpolatorProps`.
+		//
+		// `screenInterpolatorProps` is mutated in place to avoid allocating a large
+		// interpolator frame every tick. Consumers must read this revision before
+		// reading `screenInterpolatorProps`, otherwise Reanimated may not subscribe
+		// to frame updates and can observe stale transition state.
+		propsRevisionState.modify((revision) => {
 			"worklet";
+			revision.value += 1;
+			return revision;
+		}, false);
 
-			screenInterpolatorProps.modify((frame) => {
-				"worklet";
-				frame.layouts = current.layouts;
-				frame.insets = insets;
-				frame.previous = previous;
-				frame.current = current;
-				frame.next = next;
-				frame.progress = progress;
-				frame.stackProgress = stackProgress;
-				frame.snapIndex = snapIndex;
-				frame.logicallySettled = logicallySettled;
-				frame.focused = focused;
-				frame.active = active;
-				frame.inactive = inactive;
-				return frame;
-			});
-		},
-	);
+		return propsRevisionState.get().value;
+	});
 
 	const nextInterpolator = nextDescriptor?.options.screenStyleInterpolator;
 	const currentInterpolator = currDescriptor?.options.screenStyleInterpolator;
 
 	return {
 		screenInterpolatorProps,
+		screenInterpolatorPropsRevision,
+		selectedInterpolatorOptions,
 		nextInterpolator,
 		currentInterpolator,
-		boundsAccessor,
 	};
 }

package/src/shared/providers/screen/animation/helpers/selected-interpolator-options.ts

@@ -0,0 +1,99 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { TransitionInterpolatorOptions } from "../../../../types/animation.types";
+
+export type SelectedInterpolatorOwner = "current" | "next";
+
+export type SelectedInterpolatorOptions = {
+	owner: SelectedInterpolatorOwner;
+	options?: TransitionInterpolatorOptions;
+};
+
+const areGestureDirectionsEqual = (
+	left: TransitionInterpolatorOptions["gestureDirection"],
+	right: TransitionInterpolatorOptions["gestureDirection"],
+) => {
+	"worklet";
+	if (left === right) return true;
+	if (!Array.isArray(left) || !Array.isArray(right)) return false;
+	if (left.length !== right.length) return false;
+
+	for (let i = 0; i < left.length; i++) {
+		if (left[i] !== right[i]) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+const areGestureActivationAreasEqual = (
+	left: TransitionInterpolatorOptions["gestureActivationArea"],
+	right: TransitionInterpolatorOptions["gestureActivationArea"],
+) => {
+	"worklet";
+	if (left === right) return true;
+
+	if (
+		typeof left !== "object" ||
+		left === null ||
+		typeof right !== "object" ||
+		right === null
+	) {
+		return false;
+	}
+
+	return (
+		left.left === right.left &&
+		left.right === right.right &&
+		left.top === right.top &&
+		left.bottom === right.bottom
+	);
+};
+
+const areInterpolatorOptionsEqual = (
+	left?: TransitionInterpolatorOptions,
+	right?: TransitionInterpolatorOptions,
+) => {
+	"worklet";
+	if (left === right) return true;
+	if (!left || !right) return false;
+
+	return (
+		left.gestureEnabled === right.gestureEnabled &&
+		left.experimental_allowDisabledGestureTracking ===
+			right.experimental_allowDisabledGestureTracking &&
+		areGestureDirectionsEqual(left.gestureDirection, right.gestureDirection) &&
+		left.gestureSensitivity === right.gestureSensitivity &&
+		left.gestureVelocityImpact === right.gestureVelocityImpact &&
+		left.gestureSnapVelocityImpact === right.gestureSnapVelocityImpact &&
+		left.gestureReleaseVelocityScale === right.gestureReleaseVelocityScale &&
+		left.gestureResponseDistance === right.gestureResponseDistance &&
+		left.gestureProgressMode === right.gestureProgressMode &&
+		left.gestureDrivesProgress === right.gestureDrivesProgress &&
+		areGestureActivationAreasEqual(
+			left.gestureActivationArea,
+			right.gestureActivationArea,
+		) &&
+		left.gestureSnapLocked === right.gestureSnapLocked &&
+		left.sheetScrollGestureBehavior === right.sheetScrollGestureBehavior &&
+		left.backdropBehavior === right.backdropBehavior
+	);
+};
+
+export const syncSelectedInterpolatorOptions = (
+	state: SharedValue<SelectedInterpolatorOptions>,
+	owner: SelectedInterpolatorOwner,
+	options?: TransitionInterpolatorOptions,
+) => {
+	"worklet";
+	const current = state.get();
+
+	if (
+		current.owner === owner &&
+		areInterpolatorOptionsEqual(current.options, options)
+	) {
+		return;
+	}
+
+	state.set(options ? { owner, options } : { owner });
+};

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

@@ -12,23 +12,27 @@ import type {
 	Layout,
 	ScreenTransitionState,
 } from "../../../../types";
+import type { ScreenTransitionOptions } from "../../../../types/animation.types";
 import type { BaseDescriptor } from "../../descriptors";
+import { buildScreenTransitionOptions } from "./build-screen-transition-options";
 import { toPlainRoute, toPlainValue } from "./worklet";
 
 type BuiltState = {
 	progress: SharedValue<number>;
 	willAnimate: SharedValue<number>;
 	closing: SharedValue<number>;
-	animating: SharedValue<number>;
+	progressAnimating: SharedValue<number>;
 	entering: SharedValue<number>;
-	settled: SharedValue<number>;
-	logicallySettled: SharedValue<number>;
 	gesture: GestureStoreMap;
 	route: BaseStackRoute;
 	meta?: Record<string, unknown>;
+	options: ScreenTransitionOptions;
+	navigationMaskEnabled: boolean;
 	targetProgress: SharedValue<number>;
+	logicalSettleFrameCount: SharedValue<number>;
 	resolvedAutoSnapPoint: SharedValue<number>;
 	measuredContentLayout: SharedValue<Layout | null>;
+	contentLayoutSlot: Layout;
 	hasAutoSnapPoint: boolean;
 	sortedNumericSnapPoints: number[];
 	unwrapped: ScreenTransitionState;
@@ -36,20 +40,13 @@ type BuiltState = {
 
 export const useBuildTransitionState = (
 	descriptor: BaseDescriptor | undefined,
-	slot: "current" | "next" | "previous",
 ): BuiltState | undefined => {
 	const key = descriptor?.route?.key;
 	const meta = descriptor?.options?.meta;
 	const route = descriptor?.route;
-	const gestureEnabled = descriptor?.options?.gestureEnabled;
 	const navigationMaskEnabled = !!descriptor?.options?.navigationMaskEnabled;
 	const snapPoints = descriptor?.options?.snapPoints;
 
-	const shouldUseNeutralNextGestures =
-		slot === "next" &&
-		gestureEnabled === false &&
-		(!snapPoints || snapPoints.length === 0);
-
 	return useMemo(() => {
 		if (!key || !route) return undefined;
 
@@ -62,36 +59,42 @@ export const useBuildTransitionState = (
 			.filter((p): p is number => typeof p === "number")
 			.sort((a, b) => a - b);
 
+		const transitionOptions = buildScreenTransitionOptions(descriptor.options);
+
 		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"),
+			progressAnimating: AnimationStore.getValue(key, "progressAnimating"),
 			targetProgress: SystemStore.getValue(key, "targetProgress"),
+			logicalSettleFrameCount: SystemStore.getValue(
+				key,
+				"logicalSettleFrameCount",
+			),
 			resolvedAutoSnapPoint: SystemStore.getValue(key, "resolvedAutoSnapPoint"),
 			measuredContentLayout: SystemStore.getValue(key, "measuredContentLayout"),
+			contentLayoutSlot: { width: 0, height: 0 },
 			hasAutoSnapPoint: snapPoints?.includes("auto") ?? false,
 			sortedNumericSnapPoints,
-			gesture: shouldUseNeutralNextGestures
-				? (GestureStore.peekBag(key) ?? GestureStore.getCachedBag())
-				: GestureStore.getBag(key),
+			gesture: GestureStore.getBag(key),
 			route: plainRoute,
 			meta: plainMeta,
+			options: transitionOptions,
+			navigationMaskEnabled,
 			unwrapped: createScreenTransitionState(
 				plainRoute,
 				plainMeta,
 				navigationMaskEnabled,
+				transitionOptions,
 			),
 		};
 	}, [
 		key,
 		meta,
 		route,
-		shouldUseNeutralNextGestures,
 		snapPoints,
 		navigationMaskEnabled,
+		descriptor?.options,
 	]);
 };

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

@@ -1,14 +1,44 @@
 import type { SharedValue } from "react-native-reanimated";
+import type { ScreenTransitionTarget } from "../../../types/animation.types";
 import type { BoundsAccessor } from "../../../types/bounds.types";
 import type { ScreenInterpolatorFrame } from "./helpers/pipeline";
 
-export type ScreenAnimationTarget =
+export type ScreenInterpolatorPropsRevision = Pick<SharedValue<number>, "get">;
+
+export type ScreenAnimationLegacyTarget =
 	| "self"
 	| "parent"
 	| "root"
 	| { ancestor: number };
 
+export type ScreenAnimationTarget =
+	| ScreenTransitionTarget
+	| ScreenAnimationLegacyTarget;
+
 export type ScreenAnimationSource = {
 	screenInterpolatorProps: SharedValue<ScreenInterpolatorFrame>;
+	screenInterpolatorPropsRevision: ScreenInterpolatorPropsRevision;
+};
+
+export type ScreenAnimationTransitionSource = ScreenAnimationSource & {
 	boundsAccessor: BoundsAccessor;
 };
+
+export type ScreenAnimationDescendantSource = {
+	source: ScreenAnimationTransitionSource;
+	depth: number;
+};
+
+export type ScreenAnimationDescendantSources = SharedValue<
+	ScreenAnimationDescendantSource[]
+>;
+
+export type RegisterScreenAnimationDescendant = (
+	source: ScreenAnimationTransitionSource,
+	depth: number,
+) => () => void;
+
+export type ScreenAnimationAncestorDescendantRegistrar = {
+	register: RegisterScreenAnimationDescendant;
+	depth: number;
+};

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

@@ -1,37 +1,111 @@
 import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
+import type {
+	ScreenInterpolationProps,
+	ScreenTransitionTarget,
+} from "../../../types/animation.types";
 import { useScreenAnimationContext } from "./animation.provider";
-import { resolveScreenAnimationTarget } from "./helpers/resolve-screen-animation-target";
-import type { ScreenAnimationSource, ScreenAnimationTarget } from "./types";
+import { useBuildTransitionAccessor } from "./helpers/accessors/use-build-transition-accessor";
+import type {
+	ScreenAnimationDescendantSources,
+	ScreenAnimationLegacyTarget,
+	ScreenAnimationSource,
+	ScreenAnimationTarget,
+} from "./types";
 
 export type { ScreenAnimationTarget } from "./types";
 
+export function useScreenAnimation(): DerivedValue<ScreenInterpolationProps>;
+export function useScreenAnimation(target: {
+	depth: 0;
+}): DerivedValue<ScreenInterpolationProps>;
+/** @deprecated Use `{ depth: 0 }`. */
+export function useScreenAnimation(
+	target: "self",
+): DerivedValue<ScreenInterpolationProps>;
+export function useScreenAnimation(
+	target: ScreenTransitionTarget,
+): DerivedValue<ScreenInterpolationProps | null>;
+/** @deprecated Use `{ depth }`. */
+export function useScreenAnimation(
+	target: Exclude<ScreenAnimationLegacyTarget, "self">,
+): DerivedValue<ScreenInterpolationProps | null>;
 export function useScreenAnimation(
 	target?: ScreenAnimationTarget,
-): DerivedValue<ScreenInterpolationProps> {
+):
+	| DerivedValue<ScreenInterpolationProps>
+	| DerivedValue<ScreenInterpolationProps | null> {
 	const {
-		screenInterpolatorProps,
-		boundsAccessor,
+		screenInterpolatorPropsRevision,
 		ancestorScreenAnimationSources,
+		descendantScreenAnimationSources,
 	} = useScreenAnimationContext();
-
-	const source = resolveScreenAnimationTarget<ScreenAnimationSource>({
+	const transition = useBuildTransitionAccessor();
+	const transitionTarget = normalizeScreenAnimationTarget(
 		target,
-		self: {
-			screenInterpolatorProps,
-			boundsAccessor,
-		},
-		ancestors: ancestorScreenAnimationSources,
-	});
+		ancestorScreenAnimationSources.length,
+	);
 
-	return useDerivedValue<ScreenInterpolationProps>(() => {
+	const animation = useDerivedValue<ScreenInterpolationProps | null>(() => {
 		"worklet";
-
-		const props = source.screenInterpolatorProps.get();
-
-		return {
-			...props,
-			bounds: source.boundsAccessor,
-		};
+		readScreenAnimationRevisions(
+			screenInterpolatorPropsRevision,
+			ancestorScreenAnimationSources,
+			descendantScreenAnimationSources,
+		);
+		return transition(transitionTarget);
 	});
+
+	return animation;
 }
+
+const readScreenAnimationRevisions = (
+	screenInterpolatorPropsRevision: DerivedValue<number>,
+	ancestorScreenAnimationSources: ScreenAnimationSource[],
+	descendantScreenAnimationSources: ScreenAnimationDescendantSources,
+) => {
+	"worklet";
+	screenInterpolatorPropsRevision.get();
+
+	for (let index = 0; index < ancestorScreenAnimationSources.length; index++) {
+		ancestorScreenAnimationSources[
+			index
+		]?.screenInterpolatorPropsRevision.get();
+	}
+
+	// The accessor reads descendant sources through this shared value. Reading it
+	// here makes this derived value rerun when descendants mount or unmount.
+	descendantScreenAnimationSources.get();
+};
+
+const isTransitionTarget = (
+	target: ScreenAnimationTarget,
+): target is ScreenTransitionTarget => {
+	return typeof target === "object" && target !== null && "depth" in target;
+};
+
+const normalizeScreenAnimationTarget = (
+	target: ScreenAnimationTarget | undefined,
+	ancestorCount: number,
+): ScreenTransitionTarget | undefined => {
+	if (target === undefined || isTransitionTarget(target)) {
+		return target;
+	}
+
+	if (target === "self") {
+		return { depth: 0 };
+	}
+
+	if (target === "parent") {
+		return { depth: -1 };
+	}
+
+	if (target === "root") {
+		return { depth: ancestorCount > 0 ? -ancestorCount : -1 };
+	}
+
+	if (!Number.isInteger(target.ancestor) || target.ancestor < 1) {
+		return { depth: Number.NaN };
+	}
+
+	return { depth: -target.ancestor };
+};

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

@@ -5,7 +5,6 @@ import createProvider from "../../../utils/create-provider";
 import type { DescriptorDerivations } from "./helpers/derive-descriptor-derivations";
 import { deriveDescriptorDerivations } from "./helpers/derive-descriptor-derivations";
 import { getAncestorKeys } from "./helpers/get-ancestor-keys";
-import { getAncestorNavigatorKeys } from "./helpers/get-ancestor-navigator-keys";
 
 /**
  * Base descriptor interface - minimal contract for all stack types.
@@ -58,10 +57,6 @@ const {
 	DescriptorDerivationsContextValue
 >(({ previous, current, next, children }) => {
 	const ancestorKeys = useMemo(() => getAncestorKeys(current), [current]);
-	const ancestorNavigatorKeys = useMemo(
-		() => getAncestorNavigatorKeys(current),
-		[current],
-	);
 
 	const value = useMemo(
 		() =>
@@ -70,9 +65,8 @@ const {
 				current,
 				next,
 				ancestorKeys,
-				ancestorNavigatorKeys,
 			}),
-		[previous, current, next, ancestorKeys, ancestorNavigatorKeys],
+		[previous, current, next, ancestorKeys],
 	);
 
 	return {