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

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

@@ -0,0 +1,188 @@
+import { EPSILON } from "../../../../../constants";
+import type { SnapBounds } from "./types";
+
+const getResolvedSnapPointCount = (
+	snapPoints: number[],
+	resolvedAutoSnap: number | null,
+) => {
+	"worklet";
+	return snapPoints.length + (resolvedAutoSnap !== null ? 1 : 0);
+};
+
+const getAutoSnapPointIndex = (
+	snapPoints: number[],
+	resolvedAutoSnap: number,
+) => {
+	"worklet";
+	let index = 0;
+
+	while (index < snapPoints.length && snapPoints[index] <= resolvedAutoSnap) {
+		index++;
+	}
+
+	return index;
+};
+
+const getResolvedSnapPointAt = (
+	snapPoints: number[],
+	resolvedAutoSnap: number | null,
+	autoSnapPointIndex: number,
+	index: number,
+) => {
+	"worklet";
+	if (resolvedAutoSnap === null) {
+		return snapPoints[index];
+	}
+
+	if (index < autoSnapPointIndex) {
+		return snapPoints[index];
+	}
+
+	if (index === autoSnapPointIndex) {
+		return resolvedAutoSnap;
+	}
+
+	return snapPoints[index - 1];
+};
+
+export const getResolvedSnapBounds = (
+	snapPoints: number[],
+	resolvedAutoSnap: number | null,
+): SnapBounds | null => {
+	"worklet";
+	const snapPointCount = getResolvedSnapPointCount(
+		snapPoints,
+		resolvedAutoSnap,
+	);
+
+	if (snapPointCount === 0) {
+		return null;
+	}
+
+	const autoSnapPointIndex =
+		resolvedAutoSnap === null
+			? -1
+			: getAutoSnapPointIndex(snapPoints, resolvedAutoSnap);
+	const firstSnapPoint = getResolvedSnapPointAt(
+		snapPoints,
+		resolvedAutoSnap,
+		autoSnapPointIndex,
+		0,
+	);
+	const lastSnapPoint = getResolvedSnapPointAt(
+		snapPoints,
+		resolvedAutoSnap,
+		autoSnapPointIndex,
+		snapPointCount - 1,
+	);
+
+	return {
+		min: Math.min(0, firstSnapPoint),
+		max: lastSnapPoint,
+	};
+};
+
+export const computeAnimatedSnapIndex = (
+	progress: number,
+	snapPoints: number[],
+	resolvedAutoSnap: number | null,
+): number => {
+	"worklet";
+	const snapPointCount = getResolvedSnapPointCount(
+		snapPoints,
+		resolvedAutoSnap,
+	);
+
+	if (snapPointCount === 0) return -1;
+
+	const autoSnapPointIndex =
+		resolvedAutoSnap === null
+			? -1
+			: getAutoSnapPointIndex(snapPoints, resolvedAutoSnap);
+	const firstSnapPoint = getResolvedSnapPointAt(
+		snapPoints,
+		resolvedAutoSnap,
+		autoSnapPointIndex,
+		0,
+	);
+	const lastSnapPoint = getResolvedSnapPointAt(
+		snapPoints,
+		resolvedAutoSnap,
+		autoSnapPointIndex,
+		snapPointCount - 1,
+	);
+
+	if (progress <= firstSnapPoint) return 0;
+	if (progress >= lastSnapPoint) return snapPointCount - 1;
+
+	for (let i = 0; i < snapPointCount - 1; i++) {
+		const currentSnapPoint = getResolvedSnapPointAt(
+			snapPoints,
+			resolvedAutoSnap,
+			autoSnapPointIndex,
+			i,
+		);
+		const nextSnapPoint = getResolvedSnapPointAt(
+			snapPoints,
+			resolvedAutoSnap,
+			autoSnapPointIndex,
+			i + 1,
+		);
+
+		if (progress <= nextSnapPoint) {
+			const t =
+				(progress - currentSnapPoint) / (nextSnapPoint - currentSnapPoint);
+			return i + t;
+		}
+	}
+	return snapPointCount - 1;
+};
+
+export const computeTargetSnapIndex = (
+	targetProgress: number,
+	snapPoints: number[],
+	resolvedAutoSnap: number | null,
+): number => {
+	"worklet";
+	const snapPointCount = getResolvedSnapPointCount(
+		snapPoints,
+		resolvedAutoSnap,
+	);
+
+	if (snapPointCount === 0) return -1;
+
+	const autoSnapPointIndex =
+		resolvedAutoSnap === null
+			? -1
+			: getAutoSnapPointIndex(snapPoints, resolvedAutoSnap);
+	const firstSnapPoint = getResolvedSnapPointAt(
+		snapPoints,
+		resolvedAutoSnap,
+		autoSnapPointIndex,
+		0,
+	);
+
+	if (targetProgress <= 0 && Math.abs(firstSnapPoint) > EPSILON) {
+		return -1;
+	}
+
+	let nearestIndex = 0;
+	let smallestDistance = Math.abs(targetProgress - firstSnapPoint);
+
+	for (let i = 1; i < snapPointCount; i++) {
+		const snapPoint = getResolvedSnapPointAt(
+			snapPoints,
+			resolvedAutoSnap,
+			autoSnapPointIndex,
+			i,
+		);
+		const distance = Math.abs(targetProgress - snapPoint);
+
+		if (distance < smallestDistance) {
+			smallestDistance = distance;
+			nearestIndex = i;
+		}
+	}
+
+	return nearestIndex;
+};

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

@@ -0,0 +1,40 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { GestureStoreMap } from "../../../../../stores/gesture.store";
+import type {
+	ScreenTransitionOptions,
+	ScreenTransitionState,
+} from "../../../../../types/animation.types";
+import type { Layout } from "../../../../../types/screen.types";
+import type { BaseStackRoute } from "../../../../../types/stack.types";
+
+export type BuiltState = {
+	progress: SharedValue<number>;
+	willAnimate: SharedValue<number>;
+	closing: SharedValue<number>;
+	progressAnimating: SharedValue<number>;
+	entering: 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;
+};
+
+export type ComputeLogicallySettledParams = {
+	progress: number;
+	targetProgress: number;
+	frameCount: number;
+};
+
+export type SnapBounds = {
+	min: number;
+	max: number;
+};

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

@@ -1,4 +1,3 @@
-import { useMemo } from "react";
 import { useWindowDimensions } from "react-native";
 import {
 	type DerivedValue,
@@ -13,23 +12,22 @@ 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 { 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">;
 
 interface ScreenAnimationPipeline {
 	screenInterpolatorProps: SharedValue<ScreenInterpolatorFrame>;
-	screenInterpolatorFrameUpdater: DerivedValue<number>;
+	screenInterpolatorPropsRevision: DerivedValue<number>;
+	selectedInterpolatorOptions: SharedValue<SelectedInterpolatorOptions>;
 	nextInterpolator: ScreenStyleInterpolator | undefined;
 	currentInterpolator: ScreenStyleInterpolator | undefined;
-	boundsAccessor: BoundsAccessor;
 }
 
 const createInitialBaseInterpolatorProps = (
@@ -83,24 +81,48 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 	const screenInterpolatorProps = useSharedValue(
 		createInitialBaseInterpolatorProps(dimensions, insets),
 	);
+	const selectedInterpolatorOptions =
+		useSharedValue<SelectedInterpolatorOptions>({
+			owner: "current",
+		});
 
-	const screenInterpolatorFrameRevisionState = useSharedValue({ value: 0 });
-	const screenInterpolatorFrameUpdater = useDerivedValue<number>(() => {
+	const propsRevisionState = useSharedValue({ value: 0 });
+	const screenInterpolatorPropsRevision = useDerivedValue<number>(() => {
 		"worklet";
 
 		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;
 
 			frame.current = currentAnimation
-				? hydrateTransitionState(currentAnimation, dimensions)
+				? 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;
 
 			frame.layouts = frame.current.layouts;
@@ -117,35 +139,29 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 			return frame;
 		}, false);
 
-		// MAINTAINER NOTE: We increment a revision counter instead of returning a
-		// new frame object so consumers can subscribe to in-place frame updates.
+		// Critical reactive dependency for `screenInterpolatorProps`.
 		//
-		// Since we mutate the frame in place for performance reasons, readers must
-		// call `screenInterpolatorFrameUpdater.get()` before reading the frame.
-		screenInterpolatorFrameRevisionState.modify((revision) => {
+		// `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);
 
-		return screenInterpolatorFrameRevisionState.get().value;
+		return propsRevisionState.get().value;
 	});
 
-	const boundsAccessor = useMemo(() => {
-		return createBoundsAccessor(() => {
-			"worklet";
-			return screenInterpolatorProps.get();
-		});
-	}, [screenInterpolatorProps]);
-
 	const nextInterpolator = nextDescriptor?.options.screenStyleInterpolator;
 	const currentInterpolator = currDescriptor?.options.screenStyleInterpolator;
 
 	return {
 		screenInterpolatorProps,
-		screenInterpolatorFrameUpdater,
+		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

@@ -21,16 +21,15 @@ 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;
@@ -67,10 +66,12 @@ export const useBuildTransitionState = (
 			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 },

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 { ChainTarget } from "../../../utils/resolve-chain-target";
 import type { ScreenInterpolatorFrame } from "./helpers/pipeline";
 
-export type ScreenInterpolatorFrameUpdater = Pick<SharedValue<number>, "get">;
+export type ScreenInterpolatorPropsRevision = Pick<SharedValue<number>, "get">;
 
-export type ScreenAnimationTarget = ChainTarget;
+export type ScreenAnimationLegacyTarget =
+	| "self"
+	| "parent"
+	| "root"
+	| { ancestor: number };
+
+export type ScreenAnimationTarget =
+	| ScreenTransitionTarget
+	| ScreenAnimationLegacyTarget;
 
 export type ScreenAnimationSource = {
 	screenInterpolatorProps: SharedValue<ScreenInterpolatorFrame>;
-	screenInterpolatorFrameUpdater: ScreenInterpolatorFrameUpdater;
+	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,56 +1,111 @@
 import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
-import { resolveChainTarget } from "../../../utils/resolve-chain-target";
+import type {
+	ScreenInterpolationProps,
+	ScreenTransitionTarget,
+} from "../../../types/animation.types";
 import { useScreenAnimationContext } from "./animation.provider";
-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: Exclude<ScreenAnimationTarget, "self">,
-): DerivedValue<ScreenInterpolationProps> | null;
+	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> | null {
+):
+	| DerivedValue<ScreenInterpolationProps>
+	| DerivedValue<ScreenInterpolationProps | null> {
 	const {
-		screenInterpolatorProps,
-		screenInterpolatorFrameUpdater,
-		boundsAccessor,
+		screenInterpolatorPropsRevision,
 		ancestorScreenAnimationSources,
+		descendantScreenAnimationSources,
 	} = useScreenAnimationContext();
-
-	const selfSource: ScreenAnimationSource = {
-		screenInterpolatorProps,
-		screenInterpolatorFrameUpdater,
-		boundsAccessor,
-	};
-
-	const source = resolveChainTarget<ScreenAnimationSource>({
+	const transition = useBuildTransitionAccessor();
+	const transitionTarget = normalizeScreenAnimationTarget(
 		target,
-		self: selfSource,
-		ancestors: ancestorScreenAnimationSources,
-	});
-	const resolvedSource = source ?? selfSource;
+		ancestorScreenAnimationSources.length,
+	);
 
-	const animation = useDerivedValue<ScreenInterpolationProps>(() => {
+	const animation = useDerivedValue<ScreenInterpolationProps | null>(() => {
 		"worklet";
+		readScreenAnimationRevisions(
+			screenInterpolatorPropsRevision,
+			ancestorScreenAnimationSources,
+			descendantScreenAnimationSources,
+		);
+		return transition(transitionTarget);
+	});
 
-		resolvedSource.screenInterpolatorFrameUpdater.get();
-		const props = resolvedSource.screenInterpolatorProps.get();
+	return animation;
+}
 
-		return {
-			...props,
-			bounds: resolvedSource.boundsAccessor,
-		};
-	});
+const readScreenAnimationRevisions = (
+	screenInterpolatorPropsRevision: DerivedValue<number>,
+	ancestorScreenAnimationSources: ScreenAnimationSource[],
+	descendantScreenAnimationSources: ScreenAnimationDescendantSources,
+) => {
+	"worklet";
+	screenInterpolatorPropsRevision.get();
 
-	if (target && target !== "self" && !source) {
-		return null;
+	for (let index = 0; index < ancestorScreenAnimationSources.length; index++) {
+		ancestorScreenAnimationSources[
+			index
+		]?.screenInterpolatorPropsRevision.get();
 	}
 
-	return animation;
-}
+	// 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 };
+};