react-native-screen-transitions 4.0.0 → 4.1.0-beta.0

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

@@ -0,0 +1,37 @@
+import type { SharedValue } from "react-native-reanimated";
+import type {
+	ScreenTransitionOptions,
+	ScreenTransitionState,
+} from "../../../../../../types/animation.types";
+import type { ScrollMetadataState } from "../../../../../../types/gesture.types";
+import type { Layout } from "../../../../../../types/screen.types";
+import type { BaseStackRoute } from "../../../../../../types/stack.types";
+import type { MotionGestureValues, MotionValues } from "../../../types";
+
+export type MotionAnimationState = MotionValues & {
+	route: BaseStackRoute;
+	meta?: Record<string, unknown>;
+	options: ScreenTransitionOptions;
+	targetProgress: SharedValue<number>;
+	resolvedAutoSnapPoint: SharedValue<number>;
+	measuredContentLayout: SharedValue<Layout | null>;
+	scrollMetadata: SharedValue<ScrollMetadataState | null>;
+	hasAutoSnapPoint: boolean;
+	sortedNumericSnapPoints: number[];
+};
+
+// Each interpolator reader owns its mutable output and option overrides.
+export type BuiltState = Omit<
+	MotionAnimationState,
+	keyof MotionGestureValues
+> & {
+	gesture: MotionGestureValues;
+	optionsSlot: ScreenTransitionOptions;
+	contentLayoutSlot: Layout;
+	unwrapped: ScreenTransitionState;
+};
+
+export type SnapBounds = {
+	min: number;
+	max: number;
+};

package/src/providers/screen/motion/animation/helpers/worklet.ts

@@ -0,0 +1,47 @@
+import type { BaseStackRoute } from "../../../../../types/stack.types";
+
+/**
+ * Deep-clones a value, ensuring every object in the tree has Object.prototype.
+ * Handles null-prototype objects created by expo-router during deep linking.
+ * Non-plain objects (class instances, functions, symbols) are omitted.
+ */
+export const toPlainValue = (value: unknown): unknown => {
+	if (value === null || value === undefined) return value;
+
+	const type = typeof value;
+	if (type === "string" || type === "number" || type === "boolean")
+		return value;
+
+	if (type === "function" || type === "symbol") return undefined;
+
+	if (type !== "object") return undefined;
+
+	if (Array.isArray(value)) {
+		return value.map(toPlainValue);
+	}
+
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) {
+		return undefined;
+	}
+
+	const obj = value as Record<string, unknown>;
+	const result: Record<string, unknown> = {};
+	for (const key of Object.keys(obj)) {
+		result[key] = toPlainValue(obj[key]);
+	}
+	return result;
+};
+
+/**
+ * Creates a plain, serializable route object for worklet consumption.
+ * Deep-clones params to ensure all nested objects have Object.prototype
+ * (expo-router can produce null-prototype objects during deep linking).
+ */
+export const toPlainRoute = (route: BaseStackRoute): BaseStackRoute => {
+	return {
+		key: route.key,
+		name: route.name,
+		params: toPlainValue(route.params) as object | undefined,
+	};
+};

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

@@ -0,0 +1,4 @@
+export {
+	type ScreenAnimationTarget,
+	useScreenAnimation,
+} from "./use-screen-animation";

package/src/providers/screen/motion/animation/pipeline.ts

@@ -0,0 +1,40 @@
+import { useMemo } from "react";
+import { ScrollStore } from "../../../../stores/scroll.store";
+import { useBuilderStore } from "../../builder";
+import type { MotionValues } from "../types";
+import { buildScreenTransitionOptions } from "./helpers/build-screen-transition-options";
+import type { MotionAnimationState } from "./helpers/hydrate-transition-state/types";
+import { toPlainRoute, toPlainValue } from "./helpers/worklet";
+
+export function useMotionAnimationPipeline(
+	values: MotionValues,
+): MotionAnimationState {
+	const descriptor = useBuilderStore((store) => store.descriptors.current);
+	const route = descriptor.route;
+	const key = route.key;
+	const meta = descriptor.options.meta;
+	const snapPoints = descriptor.options.snapPoints;
+	return useMemo(() => {
+		const plainRoute = toPlainRoute(route);
+		const plainMeta = meta
+			? (toPlainValue(meta) as Record<string, unknown>)
+			: undefined;
+
+		const sortedNumericSnapPoints = (snapPoints ?? [])
+			.filter((p): p is number => typeof p === "number")
+			.sort((a, b) => a - b);
+
+		const transitionOptions = buildScreenTransitionOptions(descriptor.options);
+
+		return {
+			...values,
+			scrollMetadata: ScrollStore.getValue(key, "metadata"),
+			hasAutoSnapPoint:
+				snapPoints?.some((point) => typeof point === "string") ?? false,
+			sortedNumericSnapPoints,
+			route: plainRoute,
+			meta: plainMeta,
+			options: transitionOptions,
+		};
+	}, [key, meta, route, snapPoints, descriptor.options, values]);
+}

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

@@ -0,0 +1,3 @@
+import type { ScreenTransitionTarget } from "../../../../types/animation.types";
+
+export type ScreenAnimationTarget = ScreenTransitionTarget;

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

@@ -0,0 +1,70 @@
+import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
+import type {
+	ScreenInterpolationProps,
+	ScreenTransitionTarget,
+} from "../../../../types/animation.types";
+import { useOptionalBuilderStore } from "../../builder";
+import { useResolvedTransitionKey } from "../../builder/topology";
+import {
+	useOptionalOrchestratorStore,
+	useOrchestratorStore,
+} from "../../orchestrator/orchestrator.provider";
+import type { ScreenAnimationTarget } from "./types";
+
+export type { ScreenAnimationTarget } from "./types";
+
+export function useScreenAnimation(): DerivedValue<ScreenInterpolationProps>;
+export function useScreenAnimation(target: {
+	depth: 0;
+}): DerivedValue<ScreenInterpolationProps>;
+export function useScreenAnimation(
+	target: ScreenTransitionTarget,
+): DerivedValue<ScreenInterpolationProps | null>;
+export function useScreenAnimation(
+	target?: ScreenAnimationTarget,
+):
+	| DerivedValue<ScreenInterpolationProps>
+	| DerivedValue<ScreenInterpolationProps | null> {
+	const currentKey = useOptionalBuilderStore(
+		(store) => store?.derivations.currentScreenKey ?? null,
+	);
+
+	const localInterpolatorProps = useOrchestratorStore(
+		(store) => store.screenInterpolatorProps,
+	);
+	const localBoundsAccessor = useOrchestratorStore(
+		(store) => store.boundsAccessor,
+	);
+
+	const usesLocalStore =
+		target === undefined || (typeof target === "object" && target.depth === 0);
+
+	const screenKey = useResolvedTransitionKey(currentKey, target);
+
+	const keyedInterpolatorProps = useOptionalOrchestratorStore(
+		usesLocalStore ? null : screenKey,
+		(store) => store.screenInterpolatorProps,
+	);
+	const keyedBoundsAccessor = useOptionalOrchestratorStore(
+		usesLocalStore ? null : screenKey,
+		(store) => store.boundsAccessor,
+	);
+
+	const screenInterpolatorProps = usesLocalStore
+		? localInterpolatorProps
+		: keyedInterpolatorProps;
+	const boundsAccessor = usesLocalStore
+		? localBoundsAccessor
+		: keyedBoundsAccessor;
+
+	const animation = useDerivedValue<ScreenInterpolationProps | null>(() => {
+		if (!screenInterpolatorProps || !boundsAccessor) return null;
+
+		return {
+			...screenInterpolatorProps.get(),
+			bounds: boundsAccessor,
+		};
+	});
+
+	return animation;
+}

package/src/providers/screen/motion/gestures/index.tsx

@@ -0,0 +1,7 @@
+export type {
+	GestureContextType,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+} from "./types";
+export { useScreenGestures } from "./use-screen-gestures";

package/src/providers/screen/motion/gestures/ownership/compute-claimed-directions.ts

@@ -0,0 +1,98 @@
+import { DEFAULT_GESTURE_DIRECTION } from "../../../../../constants";
+import type {
+	GestureDirectionOption,
+	PanGestureDirection,
+} from "../../../../../types/gesture.types";
+import {
+	type ClaimedDirections,
+	type Direction,
+	NO_CLAIMS,
+} from "../../../../../types/ownership.types";
+import { getPanGestureDirections } from "../shared/directions";
+
+const createClaimSet = (): ClaimedDirections => ({
+	vertical: false,
+	"vertical-inverted": false,
+	horizontal: false,
+	"horizontal-inverted": false,
+});
+
+const normalizePanGestureDirections = (
+	gestureDirection: GestureDirectionOption | undefined,
+) => {
+	const direction = gestureDirection ?? DEFAULT_GESTURE_DIRECTION;
+	return getPanGestureDirections(direction);
+};
+
+const claimPanDirection = (
+	claims: ClaimedDirections,
+	direction: PanGestureDirection,
+) => {
+	if (direction === "bidirectional") {
+		claims.vertical = true;
+		claims["vertical-inverted"] = true;
+		claims.horizontal = true;
+		claims["horizontal-inverted"] = true;
+		return;
+	}
+
+	claims[direction as Direction] = true;
+};
+
+const expandSnapPointAxisClaims = (claims: ClaimedDirections) => {
+	const hasVerticalAxis = claims.vertical || claims["vertical-inverted"];
+	const hasHorizontalAxis = claims.horizontal || claims["horizontal-inverted"];
+
+	if (hasVerticalAxis) {
+		claims.vertical = true;
+		claims["vertical-inverted"] = true;
+	}
+
+	if (hasHorizontalAxis) {
+		claims.horizontal = true;
+		claims["horizontal-inverted"] = true;
+	}
+};
+
+/**
+ * Computes which directions a screen claims ownership of.
+ *
+ * A screen claims a direction when:
+ * 1. direction claiming is enabled AND
+ * 2. gestureDirection includes that direction
+ *
+ * For snap points, both directions on each configured pan axis are claimed.
+ * The first direction on an axis collapses; its inverse expands.
+ *
+ * @param canClaimDirections - Whether this screen can own gesture directions
+ * @param gestureDirection - The gesture direction(s) configured for this screen
+ * @param hasSnapPoints - Whether this screen has snap points configured
+ * @returns The claimed directions for this screen
+ */
+export function computeClaimedDirections(
+	canClaimDirections: boolean,
+	gestureDirection: GestureDirectionOption | undefined,
+	hasSnapPoints: boolean,
+): ClaimedDirections {
+	if (!canClaimDirections) {
+		return NO_CLAIMS;
+	}
+
+	const directions = normalizePanGestureDirections(gestureDirection);
+
+	if (directions.length === 0) {
+		return NO_CLAIMS;
+	}
+
+	const claims = createClaimSet();
+
+	for (const dir of directions) {
+		claimPanDirection(claims, dir);
+	}
+
+	if (hasSnapPoints) {
+		expandSnapPointAxisClaims(claims);
+	}
+
+	return claims;
+}

package/src/providers/screen/motion/gestures/ownership/gesture-ownership-coordinator.ts

@@ -0,0 +1,252 @@
+import type { SharedValue } from "react-native-reanimated";
+import type {
+	ClaimedDirections,
+	Direction,
+} from "../../../../../types/ownership.types";
+import { DIRECTIONS } from "../../../../../types/ownership.types";
+import { screenTopology } from "../../../builder/topology";
+import type { ScreenTopology } from "../../../builder/topology/types";
+import type {
+	GestureOwnerMap,
+	PanGesture,
+	PinchGesture,
+	ScreenGestureSource,
+	ScrollGestureAxis,
+	ScrollGestureState,
+} from "../types";
+
+export type GestureOwnershipRegistration = {
+	screenKey: string;
+	source: ScreenGestureSource;
+	claimedDirections: ClaimedDirections;
+	effectiveClaimedDirections: ClaimedDirections;
+	owners: SharedValue<GestureOwnerMap>;
+};
+
+export type ScrollGestureCoordination = {
+	panGestures: PanGesture[];
+	pinchGestures: PinchGesture[];
+	scrollStates: SharedValue<ScrollGestureState | null>[];
+	ownerRouteKeys: string[];
+};
+
+export type GestureOwnershipCoordinator = {
+	register(registration: GestureOwnershipRegistration): void;
+	unregister(screenKey: string): void;
+	getScrollCoordination(
+		screenKey: string,
+		axis: ScrollGestureAxis,
+	): ScrollGestureCoordination;
+	subscribe(screenKey: string, listener: () => void): () => void;
+};
+
+const EMPTY_SCROLL_COORDINATION: ScrollGestureCoordination = {
+	panGestures: [],
+	pinchGestures: [],
+	scrollStates: [],
+	ownerRouteKeys: [],
+};
+
+const createEmptyOwners = (): GestureOwnerMap => ({
+	vertical: null,
+	"vertical-inverted": null,
+	horizontal: null,
+	"horizontal-inverted": null,
+});
+
+const areOwnersEqual = (left: GestureOwnerMap, right: GestureOwnerMap) =>
+	DIRECTIONS.every((direction) => left[direction] === right[direction]);
+
+const areArraysEqual = <T>(left: readonly T[], right: readonly T[]) =>
+	left.length === right.length &&
+	left.every((value, index) => value === right[index]);
+
+const areScrollCoordinationsEqual = (
+	left: ScrollGestureCoordination,
+	right: ScrollGestureCoordination,
+) =>
+	areArraysEqual(left.panGestures, right.panGestures) &&
+	areArraysEqual(left.pinchGestures, right.pinchGestures) &&
+	areArraysEqual(left.scrollStates, right.scrollStates) &&
+	areArraysEqual(left.ownerRouteKeys, right.ownerRouteKeys);
+
+const getAxisDirections = (
+	axis: ScrollGestureAxis,
+): readonly [Direction, Direction] =>
+	axis === "vertical"
+		? ["vertical", "vertical-inverted"]
+		: ["horizontal", "horizontal-inverted"];
+
+export const createGestureOwnershipCoordinator = (
+	topology: ScreenTopology,
+): GestureOwnershipCoordinator => {
+	const registrations = new Map<string, GestureOwnershipRegistration>();
+	const scrollCache = new Map<
+		string,
+		Record<ScrollGestureAxis, ScrollGestureCoordination>
+	>();
+	const listenersByScreenKey = new Map<string, Set<() => void>>();
+
+	const getNearestAncestorOwner = (screenKey: string, direction: Direction) => {
+		const visited = new Set<string>();
+		let candidate: string | null = screenKey;
+
+		while (candidate && !visited.has(candidate)) {
+			visited.add(candidate);
+			if (registrations.get(candidate)?.claimedDirections[direction]) {
+				return candidate;
+			}
+			candidate = topology.getRelationships(candidate).parentScreenKey;
+		}
+
+		return null;
+	};
+
+	const getDeepestActiveOwner = (screenKey: string, direction: Direction) => {
+		const visited = new Set<string>();
+		let candidate: string | null = screenKey;
+		let owner: string | null = null;
+		let isOrigin = true;
+
+		while (candidate && !visited.has(candidate)) {
+			visited.add(candidate);
+			const registration = registrations.get(candidate);
+			const claims = isOrigin
+				? registration?.claimedDirections
+				: registration?.effectiveClaimedDirections;
+			if (claims?.[direction]) owner = candidate;
+
+			candidate = topology.getRelationships(candidate).activeChildScreenKey;
+			isOrigin = false;
+		}
+
+		return owner;
+	};
+
+	const resolveOwners = (screenKey: string): GestureOwnerMap => {
+		const owners = createEmptyOwners();
+		for (const direction of DIRECTIONS) {
+			owners[direction] =
+				getDeepestActiveOwner(screenKey, direction) ??
+				getNearestAncestorOwner(screenKey, direction);
+		}
+		return owners;
+	};
+
+	const resolveScrollCoordination = (
+		screenKey: string,
+		axis: ScrollGestureAxis,
+	): ScrollGestureCoordination => {
+		const ownerKeys: string[] = [];
+		for (const direction of getAxisDirections(axis)) {
+			const ownerKey = getNearestAncestorOwner(screenKey, direction);
+			if (ownerKey && !ownerKeys.includes(ownerKey)) ownerKeys.push(ownerKey);
+		}
+
+		const panGestures: PanGesture[] = [];
+		const scrollStates: SharedValue<ScrollGestureState | null>[] = [];
+		for (const ownerKey of ownerKeys) {
+			const source = registrations.get(ownerKey)?.source;
+			if (!source) continue;
+			panGestures.push(source.panGesture);
+			scrollStates.push(source.scrollState);
+		}
+
+		const pinchGestures: PinchGesture[] = [];
+		const visited = new Set<string>();
+		let candidate: string | null = screenKey;
+		while (candidate && !visited.has(candidate)) {
+			visited.add(candidate);
+			const pinchGesture = registrations.get(candidate)?.source.pinchGesture;
+			if (pinchGesture && !pinchGestures.includes(pinchGesture)) {
+				pinchGestures.push(pinchGesture);
+			}
+			candidate = topology.getRelationships(candidate).parentScreenKey;
+		}
+
+		return {
+			panGestures,
+			pinchGestures,
+			scrollStates,
+			ownerRouteKeys: ownerKeys,
+		};
+	};
+
+	const notify = (screenKey: string) => {
+		for (const listener of listenersByScreenKey.get(screenKey) ?? []) {
+			listener();
+		}
+	};
+
+	const recompute = () => {
+		for (const [screenKey, registration] of registrations) {
+			const nextOwners = resolveOwners(screenKey);
+			if (!areOwnersEqual(registration.owners.get(), nextOwners)) {
+				registration.owners.set(nextOwners);
+			}
+
+			const previousScroll = scrollCache.get(screenKey);
+			const nextScroll = {
+				vertical: resolveScrollCoordination(screenKey, "vertical"),
+				horizontal: resolveScrollCoordination(screenKey, "horizontal"),
+			};
+			const vertical =
+				previousScroll &&
+				areScrollCoordinationsEqual(
+					previousScroll.vertical,
+					nextScroll.vertical,
+				)
+					? previousScroll.vertical
+					: nextScroll.vertical;
+			const horizontal =
+				previousScroll &&
+				areScrollCoordinationsEqual(
+					previousScroll.horizontal,
+					nextScroll.horizontal,
+				)
+					? previousScroll.horizontal
+					: nextScroll.horizontal;
+			if (
+				!previousScroll ||
+				vertical !== previousScroll.vertical ||
+				horizontal !== previousScroll.horizontal
+			) {
+				scrollCache.set(screenKey, { vertical, horizontal });
+				notify(screenKey);
+			}
+		}
+	};
+
+	topology.subscribeResolution(recompute);
+
+	return {
+		register: (registration) => {
+			registrations.set(registration.screenKey, registration);
+			recompute();
+		},
+		unregister: (screenKey) => {
+			if (!registrations.has(screenKey)) return;
+
+			registrations.delete(screenKey);
+			scrollCache.delete(screenKey);
+			recompute();
+			notify(screenKey);
+		},
+		getScrollCoordination: (screenKey, axis) =>
+			scrollCache.get(screenKey)?.[axis] ?? EMPTY_SCROLL_COORDINATION,
+		subscribe: (screenKey, listener) => {
+			const listeners =
+				listenersByScreenKey.get(screenKey) ?? new Set<() => void>();
+			listeners.add(listener);
+			listenersByScreenKey.set(screenKey, listeners);
+
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size === 0) listenersByScreenKey.delete(screenKey);
+			};
+		},
+	};
+};
+
+export const gestureOwnershipCoordinator =
+	createGestureOwnershipCoordinator(screenTopology);

package/src/providers/screen/motion/gestures/ownership/hooks/use-gesture-sensitivity.ts

@@ -0,0 +1,132 @@
+import { useCallback, useMemo } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import { useSharedValue } from "react-native-reanimated";
+import type { ScreenOptionsContextValue } from "../../../options";
+import {
+	applyGestureSensitivity,
+	normalizePinchScale,
+} from "../../shared/physics";
+import type { PanGestureEvent, PinchGestureEvent } from "../../types";
+
+export interface GestureSensitivityRawChangeState {
+	previousRawValue: SharedValue<number>;
+	adjustedValue: SharedValue<number>;
+}
+
+export const applyGestureSensitivityToRawChange = (
+	rawValue: number,
+	sensitivity: number,
+	state: GestureSensitivityRawChangeState,
+) => {
+	"worklet";
+	const rawChange = rawValue - state.previousRawValue.get();
+
+	// gestureSensitivity can change mid-gesture, so apply it to the latest
+	// raw movement only instead of rescaling the recognizer's cumulative value.
+	const adjustedValue =
+		state.adjustedValue.get() + applyGestureSensitivity(rawChange, sensitivity);
+
+	state.previousRawValue.set(rawValue);
+	state.adjustedValue.set(adjustedValue);
+
+	return adjustedValue;
+};
+
+const resetChangeState = (state: GestureSensitivityRawChangeState) => {
+	"worklet";
+	state.previousRawValue.set(0);
+	state.adjustedValue.set(0);
+};
+
+const useBuildSensitivityChangeState = () => {
+	const previousRawValue = useSharedValue(0);
+	const adjustedValue = useSharedValue(0);
+
+	return useMemo<GestureSensitivityRawChangeState>(
+		() => ({
+			previousRawValue,
+			adjustedValue,
+		}),
+		[previousRawValue, adjustedValue],
+	);
+};
+
+export const usePanGestureSensitivity = (
+	screenOptions: ScreenOptionsContextValue,
+) => {
+	const xSensitivityState = useBuildSensitivityChangeState();
+	const ySensitivityState = useBuildSensitivityChangeState();
+
+	const resetSensitivity = useCallback(() => {
+		"worklet";
+		resetChangeState(xSensitivityState);
+		resetChangeState(ySensitivityState);
+	}, [xSensitivityState, ySensitivityState]);
+
+	const withSensitivity = useCallback(
+		(event: PanGestureEvent): PanGestureEvent => {
+			"worklet";
+			const sensitivity = screenOptions.get().gestureSensitivity;
+
+			return {
+				...event,
+				translationX: applyGestureSensitivityToRawChange(
+					event.translationX,
+					sensitivity,
+					xSensitivityState,
+				),
+				translationY: applyGestureSensitivityToRawChange(
+					event.translationY,
+					sensitivity,
+					ySensitivityState,
+				),
+			};
+		},
+		[screenOptions, xSensitivityState, ySensitivityState],
+	);
+
+	return useMemo(
+		() => ({
+			withSensitivity,
+			resetSensitivity,
+		}),
+		[withSensitivity, resetSensitivity],
+	);
+};
+
+export const usePinchGestureSensitivity = (
+	screenOptions: ScreenOptionsContextValue,
+) => {
+	const scaleSensitivityState = useBuildSensitivityChangeState();
+
+	const resetSensitivity = useCallback(() => {
+		"worklet";
+		resetChangeState(scaleSensitivityState);
+	}, [scaleSensitivityState]);
+
+	const withSensitivity = useCallback(
+		(event: PinchGestureEvent): PinchGestureEvent => {
+			"worklet";
+			const sensitivity = screenOptions.get().gestureSensitivity;
+			const normScale = applyGestureSensitivityToRawChange(
+				normalizePinchScale(event.scale),
+				sensitivity,
+				scaleSensitivityState,
+			);
+
+			return {
+				...event,
+				scale: 1 + normScale,
+			};
+		},
+		[screenOptions, scaleSensitivityState],
+	);
+
+	return useMemo(
+		() => ({
+			withSensitivity,
+			resetSensitivity,
+		}),
+		[withSensitivity, resetSensitivity],
+	);
+};