react-native-screen-transitions 4.1.0-alpha.0 → 4.1.0-beta.1

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

@@ -0,0 +1,189 @@
+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,
+	canDismiss = true,
+): 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: canDismiss ? Math.min(0, firstSnapPoint) : 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/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;
+}