react-native-screen-transitions 3.3.0 → 3.4.0-alpha.1

package/src/shared/{utils/animation → providers/screen/animation/helpers}/derivations.ts

@@ -1,4 +1,4 @@
-import type { ScreenTransitionState } from "../../types/animation.types";
+import type { ScreenTransitionState } from "../../../../types/animation.types";
 
 interface DerivationsParams {
 	previous?: ScreenTransitionState;
@@ -24,18 +24,10 @@ export const derivations = ({ previous, current, next }: DerivationsParams) => {
 	// The screen NOT driving the transition
 	const inactive = focused ? previous : current;
 
-	const isActiveTransitioning = !!(
-		active.gesture.isDragging || active.animating
-	);
-
-	const isDismissing = !!(active.gesture.isDismissing || active.closing);
-
 	return {
 		progress,
 		focused,
 		active,
 		inactive,
-		isActiveTransitioning,
-		isDismissing,
 	};
 };

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

@@ -0,0 +1,290 @@
+import { useMemo } from "react";
+import {
+	type DerivedValue,
+	type SharedValue,
+	useDerivedValue,
+	useSharedValue,
+} from "react-native-reanimated";
+import type { NativeStackScreenTransitionConfig } from "../../../../../native-stack/types";
+import {
+	createScreenTransitionState,
+	DEFAULT_SCREEN_TRANSITION_STATE,
+} from "../../../../constants";
+import { useStack } from "../../../../hooks/navigation/use-stack";
+import { AnimationStore } from "../../../../stores/animation.store";
+import {
+	GestureStore,
+	type GestureStoreMap,
+} from "../../../../stores/gesture.store";
+import type {
+	ScreenInterpolationProps,
+	ScreenStyleInterpolator,
+	ScreenTransitionState,
+} from "../../../../types/animation.types";
+import type { BoundsAccessor } from "../../../../types/bounds.types";
+import type { ScreenTransitionConfig } from "../../../../types/screen.types";
+import type { BaseStackRoute } from "../../../../types/stack.types";
+import { createBoundsAccessor } from "../../../../utils/bounds";
+import { useViewportContext } from "../../../viewport.provider";
+import { type BaseDescriptor, useDescriptors } from "../../descriptors";
+import { derivations } from "./derivations";
+import { toPlainRoute, toPlainValue } from "./worklet";
+
+type BuiltState = {
+	progress: SharedValue<number>;
+	closing: SharedValue<number>;
+	animating: SharedValue<number>;
+	entering: SharedValue<number>;
+	gesture: GestureStoreMap;
+	route: BaseStackRoute;
+	meta?: Record<string, unknown>;
+	unwrapped: ScreenTransitionState;
+};
+
+export interface ScreenAnimationPipeline {
+	screenInterpolatorProps: DerivedValue<
+		Omit<ScreenInterpolationProps, "bounds">
+	>;
+	nextInterpolator: ScreenStyleInterpolator | undefined;
+	currentInterpolator: ScreenStyleInterpolator | undefined;
+	boundsAccessor: BoundsAccessor;
+}
+
+/**
+ * Computes the animated snap index based on progress and snap points.
+ * Returns -1 if no snap points, otherwise interpolates between indices.
+ */
+const computeSnapIndex = (progress: number, snapPoints: number[]): number => {
+	"worklet";
+	if (snapPoints.length === 0) return -1;
+	if (progress <= snapPoints[0]) return 0;
+	if (progress >= snapPoints[snapPoints.length - 1])
+		return snapPoints.length - 1;
+
+	for (let i = 0; i < snapPoints.length - 1; i++) {
+		if (progress <= snapPoints[i + 1]) {
+			const t =
+				(progress - snapPoints[i]) / (snapPoints[i + 1] - snapPoints[i]);
+			return i + t;
+		}
+	}
+	return snapPoints.length - 1;
+};
+
+const unwrapInto = (s: BuiltState): ScreenTransitionState => {
+	"worklet";
+	const out = s.unwrapped;
+	out.progress = s.progress.value;
+	out.closing = s.closing.value;
+	out.entering = s.entering.value;
+	out.animating = s.animating.value;
+	out.gesture.x = s.gesture.x.value;
+	out.gesture.y = s.gesture.y.value;
+	out.gesture.normX = s.gesture.normX.value;
+	out.gesture.normY = s.gesture.normY.value;
+	out.gesture.dismissing = s.gesture.dismissing.value;
+	out.gesture.dragging = s.gesture.dragging.value;
+	out.gesture.direction = s.gesture.direction.value;
+
+	// Deprecated aliases (kept for backwards compatibility)
+	out.gesture.normalizedX = out.gesture.normX;
+	out.gesture.normalizedY = out.gesture.normY;
+	out.gesture.isDismissing = out.gesture.dismissing;
+	out.gesture.isDragging = out.gesture.dragging;
+
+	out.settled =
+		out.gesture.dragging ||
+		out.animating ||
+		out.gesture.dismissing ||
+		out.closing
+			? 0
+			: 1;
+	out.meta = s.meta;
+
+	return out;
+};
+
+const useBuildScreenTransitionState = (
+	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 snapPoints = descriptor?.options?.snapPoints;
+
+	const shouldUseNeutralNextGestures =
+		slot === "next" &&
+		gestureEnabled === false &&
+		(!snapPoints || snapPoints.length === 0);
+
+	return useMemo(() => {
+		if (!key || !route) return undefined;
+
+		const plainRoute = toPlainRoute(route);
+		const plainMeta = meta
+			? (toPlainValue(meta) as Record<string, unknown>)
+			: undefined;
+
+		return {
+			progress: AnimationStore.getRouteAnimation(key, "progress"),
+			closing: AnimationStore.getRouteAnimation(key, "closing"),
+			entering: AnimationStore.getRouteAnimation(key, "entering"),
+			animating: AnimationStore.getRouteAnimation(key, "animating"),
+			gesture: shouldUseNeutralNextGestures
+				? (GestureStore.peekRouteGestures(key) ??
+					GestureStore.getNeutralGestures())
+				: GestureStore.getRouteGestures(key),
+			route: plainRoute,
+			meta: plainMeta,
+			unwrapped: createScreenTransitionState(plainRoute, plainMeta),
+		};
+	}, [key, meta, route, shouldUseNeutralNextGestures]);
+};
+
+const hasTransitionsEnabled = (
+	options: ScreenTransitionConfig | undefined,
+	alwaysOn: boolean,
+) => {
+	if (alwaysOn) return true;
+	return !!(options as NativeStackScreenTransitionConfig)?.enableTransitions;
+};
+
+export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
+	const { flags, stackProgress: rootStackProgress, routeKeys } = useStack();
+	const { dimensions, insets } = useViewportContext();
+	const transitionsAlwaysOn = flags.TRANSITIONS_ALWAYS_ON;
+
+	const {
+		current: currentDescriptor,
+		next: nextDescriptor,
+		previous: previousDescriptor,
+	} = useDescriptors();
+
+	const currentAnimation = useBuildScreenTransitionState(
+		currentDescriptor,
+		"current",
+	);
+	const nextAnimation = useBuildScreenTransitionState(nextDescriptor, "next");
+	const prevAnimation = useBuildScreenTransitionState(
+		previousDescriptor,
+		"previous",
+	);
+
+	const currentRouteKey = currentDescriptor?.route?.key;
+	const currentIndex = routeKeys.indexOf(currentRouteKey);
+
+	const sortedNumericSnapPoints = useMemo(() => {
+		const points = currentDescriptor?.options?.snapPoints;
+		if (!points) return [];
+		return points
+			.filter((p): p is number => typeof p === "number")
+			.sort((a, b) => a - b);
+	}, [currentDescriptor?.options?.snapPoints]);
+
+	const hasAutoSnapPoint = useMemo(
+		() => currentDescriptor?.options?.snapPoints?.includes("auto") ?? false,
+		[currentDescriptor?.options?.snapPoints],
+	);
+
+	const autoSnapPointValue = AnimationStore.getAnimation(
+		currentRouteKey ?? "_",
+		"autoSnapPoint",
+	);
+
+	const nextRouteKey = nextDescriptor?.route?.key;
+	const nextHasTransitions =
+		!!nextRouteKey &&
+		hasTransitionsEnabled(nextDescriptor?.options, transitionsAlwaysOn);
+
+	const framePropsMutable = useSharedValue<
+		Omit<ScreenInterpolationProps, "bounds">
+	>({
+		layouts: { screen: dimensions },
+		insets,
+		previous: undefined,
+		current: DEFAULT_SCREEN_TRANSITION_STATE,
+		next: undefined,
+		progress: 0,
+		stackProgress: 0,
+		snapIndex: -1,
+		focused: true,
+		active: DEFAULT_SCREEN_TRANSITION_STATE,
+		inactive: undefined,
+	});
+
+	const boundsAccessor = useMemo(() => {
+		return createBoundsAccessor(() => {
+			"worklet";
+			return framePropsMutable.value;
+		});
+	}, [framePropsMutable]);
+
+	const screenInterpolatorProps = useDerivedValue<
+		Omit<ScreenInterpolationProps, "bounds">
+	>(() => {
+		"worklet";
+
+		const previous = prevAnimation ? unwrapInto(prevAnimation) : undefined;
+
+		const next =
+			nextAnimation && nextHasTransitions
+				? unwrapInto(nextAnimation)
+				: undefined;
+
+		const current = currentAnimation
+			? unwrapInto(currentAnimation)
+			: DEFAULT_SCREEN_TRANSITION_STATE;
+
+		const { progress, ...helpers } = derivations({
+			previous,
+			current,
+			next,
+		});
+
+		// Compute relative stack progress: total - currentIndex
+		// This gives us the sum of progress values from current screen onwards
+		// Falls back to current progress if index is invalid
+		const stackProgress =
+			currentIndex >= 0 ? rootStackProgress.value - currentIndex : progress;
+
+		// Resolve 'auto' snap point reactively so computeSnapIndex stays accurate
+		const resolvedAutoSnap =
+			hasAutoSnapPoint && autoSnapPointValue.value > 0
+				? autoSnapPointValue.value
+				: null;
+		const resolvedSnapPoints =
+			resolvedAutoSnap !== null
+				? [...sortedNumericSnapPoints, resolvedAutoSnap].sort((a, b) => a - b)
+				: sortedNumericSnapPoints;
+
+		const snapIndex = computeSnapIndex(current.progress, resolvedSnapPoints);
+
+		const nextProps = {
+			layouts: { screen: dimensions },
+			insets,
+			previous,
+			current,
+			next,
+			progress,
+			stackProgress,
+			snapIndex,
+			...helpers,
+		};
+
+		framePropsMutable.value = nextProps;
+		return nextProps;
+	});
+
+	const nextInterpolator = nextDescriptor?.options.screenStyleInterpolator;
+	const currentInterpolator =
+		currentDescriptor?.options.screenStyleInterpolator;
+
+	return {
+		screenInterpolatorProps,
+		nextInterpolator,
+		currentInterpolator,
+		boundsAccessor,
+	};
+}

package/src/shared/providers/screen/animation/helpers/resolve-screen-animation-target.ts

@@ -0,0 +1,44 @@
+import type { DerivedValue } from "react-native-reanimated";
+import type { ScreenInterpolationProps } from "../../../../types/animation.types";
+import type { ScreenAnimationTarget } from "../types";
+
+type Params = {
+	target: ScreenAnimationTarget | undefined;
+	self: DerivedValue<ScreenInterpolationProps>;
+	ancestors: DerivedValue<ScreenInterpolationProps>[];
+};
+
+const isAncestorTarget = (
+	target: ScreenAnimationTarget,
+): target is { ancestor: number } => {
+	return typeof target === "object" && target !== null && "ancestor" in target;
+};
+
+export function resolveScreenAnimationTarget({
+	target,
+	self,
+	ancestors,
+}: Params): DerivedValue<ScreenInterpolationProps> {
+	if (!target || target === "self") {
+		return self;
+	}
+
+	if (target === "parent") {
+		return ancestors[0] ?? self;
+	}
+
+	if (target === "root") {
+		return ancestors[ancestors.length - 1] ?? self;
+	}
+
+	if (!isAncestorTarget(target)) {
+		return self;
+	}
+
+	const depth = target.ancestor;
+	if (!Number.isInteger(depth) || depth < 1) {
+		return self;
+	}
+
+	return ancestors[depth - 1] ?? self;
+}

package/src/shared/{utils/animation → providers/screen/animation/helpers}/worklet.ts

@@ -1,4 +1,4 @@
-import type { BaseStackRoute } from "../../types/stack.types";
+import type { BaseStackRoute } from "../../../../types/stack.types";
 
 /**
  * Deep-clones a value, ensuring every object in the tree has Object.prototype.

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

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

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

@@ -0,0 +1,5 @@
+export type ScreenAnimationTarget =
+	| "self"
+	| "parent"
+	| "root"
+	| { ancestor: number };

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

@@ -0,0 +1,19 @@
+import type { DerivedValue } from "react-native-reanimated";
+import type { ScreenInterpolationProps } from "../../../types/animation.types";
+import { useScreenAnimationContext } from "./animation.provider";
+import { resolveScreenAnimationTarget } from "./helpers/resolve-screen-animation-target";
+import type { ScreenAnimationTarget } from "./types";
+
+export type { ScreenAnimationTarget } from "./types";
+
+export function useScreenAnimation(
+	target?: ScreenAnimationTarget,
+): DerivedValue<ScreenInterpolationProps> {
+	const { screenAnimation, ancestorScreenAnimations } =
+		useScreenAnimationContext();
+	return resolveScreenAnimationTarget({
+		target,
+		self: screenAnimation,
+		ancestors: ancestorScreenAnimations,
+	});
+}

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

@@ -0,0 +1,113 @@
+import type { ReactNode } from "react";
+import { useMemo } from "react";
+import type { BaseStackDescriptor } from "../../../types/stack.types";
+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.
+ * This allows blank-stack and native-stack to work with the shared
+ * providers without tight coupling to React Navigation.
+ */
+export type BaseDescriptor = BaseStackDescriptor;
+
+export interface DescriptorsContextValue<
+	TDescriptor extends BaseDescriptor = BaseDescriptor,
+> {
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+}
+
+export type DescriptorDerivationsContextValue = DescriptorDerivations;
+
+interface DescriptorsProviderProps<TDescriptor extends BaseDescriptor> {
+	children: ReactNode;
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+}
+
+type InternalProviderProps = DescriptorsProviderProps<BaseDescriptor>;
+
+const {
+	DescriptorsProvider: InternalDescriptorsProvider,
+	useDescriptorsContext,
+} = createProvider("Descriptors", { guarded: true })<
+	InternalProviderProps,
+	DescriptorsContextValue<BaseDescriptor>
+>(({ previous, current, next }) => {
+	const value = useMemo(
+		() => ({ previous, current, next }),
+		[previous, current, next],
+	);
+
+	return {
+		value,
+	};
+});
+
+const {
+	DescriptorDerivationsProvider: InternalDescriptorDerivationsProvider,
+	useDescriptorDerivationsContext,
+} = createProvider("DescriptorDerivations", { guarded: true })<
+	InternalProviderProps,
+	DescriptorDerivationsContextValue
+>(({ previous, current, next, children }) => {
+	const ancestorKeys = useMemo(() => getAncestorKeys(current), [current]);
+	const ancestorNavigatorKeys = useMemo(
+		() => getAncestorNavigatorKeys(current),
+		[current],
+	);
+
+	const value = useMemo(
+		() =>
+			deriveDescriptorDerivations({
+				previous,
+				current,
+				next,
+				ancestorKeys,
+				ancestorNavigatorKeys,
+			}),
+		[previous, current, next, ancestorKeys, ancestorNavigatorKeys],
+	);
+
+	return {
+		value,
+		children,
+	};
+});
+
+export function DescriptorsProvider<TDescriptor extends BaseDescriptor>({
+	children,
+	previous,
+	current,
+	next,
+}: DescriptorsProviderProps<TDescriptor>) {
+	const providerProps = {
+		previous,
+		current,
+		next,
+	};
+
+	return (
+		<InternalDescriptorsProvider {...providerProps}>
+			<InternalDescriptorDerivationsProvider {...providerProps}>
+				{children}
+			</InternalDescriptorDerivationsProvider>
+		</InternalDescriptorsProvider>
+	);
+}
+
+export function useDescriptors<
+	TDescriptor extends BaseDescriptor = BaseDescriptor,
+>() {
+	return useDescriptorsContext() as DescriptorsContextValue<TDescriptor>;
+}
+
+export function useDescriptorDerivations(): DescriptorDerivationsContextValue {
+	return useDescriptorDerivationsContext();
+}

package/src/shared/providers/screen/descriptors/helpers/derive-descriptor-derivations.ts

@@ -0,0 +1,67 @@
+import type { BaseStackDescriptor } from "../../../../types/stack.types";
+
+export interface DescriptorDerivations {
+	previousScreenKey?: string;
+	currentScreenKey: string;
+	nextScreenKey?: string;
+	isFirstKey: boolean;
+	isTopMostScreen: boolean;
+	ancestorKeys: string[];
+	navigatorKey: string;
+	ancestorNavigatorKeys: string[];
+	hasConfiguredInterpolator: boolean;
+	isBranchScreen: boolean;
+	branchNavigatorKey?: string;
+}
+
+interface Params {
+	previous?: BaseStackDescriptor;
+	current: BaseStackDescriptor;
+	next?: BaseStackDescriptor;
+	ancestorKeys: string[];
+	ancestorNavigatorKeys: string[];
+}
+
+export function deriveDescriptorDerivations({
+	previous,
+	current,
+	next,
+	ancestorKeys,
+	ancestorNavigatorKeys,
+}: Params): DescriptorDerivations {
+	const previousScreenKey = previous?.route.key;
+	const currentScreenKey = current.route.key;
+	const nextScreenKey = next?.route.key;
+
+	const navigationState = current.navigation.getState();
+	const navigatorKey = navigationState?.key ?? "";
+	const routes = navigationState?.routes ?? [];
+	const isFirstKey =
+		routes.findIndex((route) => route.key === current.route.key) === 0;
+	const isTopMostScreen = !next;
+	const hasConfiguredInterpolator =
+		!!current.options.screenStyleInterpolator ||
+		!!next?.options?.screenStyleInterpolator;
+
+	const currentRoute = routes.find((route) => route.key === current.route.key);
+	const hasBranchState = !!currentRoute && "state" in currentRoute;
+	const nestedState = hasBranchState
+		? (currentRoute as { state?: { key?: unknown } }).state
+		: undefined;
+	const branchNavigatorKey =
+		typeof nestedState?.key === "string" ? nestedState.key : undefined;
+
+	return {
+		previousScreenKey,
+		currentScreenKey,
+		nextScreenKey,
+		isFirstKey,
+		isTopMostScreen,
+		ancestorKeys,
+		navigatorKey,
+		ancestorNavigatorKeys,
+		hasConfiguredInterpolator,
+		isBranchScreen: hasBranchState,
+		branchNavigatorKey,
+	};
+}

package/src/shared/providers/screen/descriptors/helpers/get-ancestor-keys.ts

@@ -0,0 +1,30 @@
+import type { BaseStackDescriptor } from "../../../../types/stack.types";
+
+/**
+ * Builds the full ancestor key chain for nested navigators.
+ * Returns an array of screen keys from immediate parent to root.
+ * [parentKey, grandparentKey, greatGrandparentKey, ...]
+ */
+export function getAncestorKeys(current: BaseStackDescriptor): string[] {
+	const ancestors: string[] = [];
+	const nav = current.navigation as any;
+
+	if (typeof nav?.getParent !== "function") {
+		return ancestors;
+	}
+
+	let parent = nav.getParent();
+
+	while (parent) {
+		const state = parent.getState();
+		if (state?.routes && state.index !== undefined) {
+			const focusedRoute = state.routes[state.index];
+			if (focusedRoute?.key) {
+				ancestors.push(focusedRoute.key);
+			}
+		}
+		parent = parent.getParent();
+	}
+
+	return ancestors;
+}

package/src/shared/providers/screen/descriptors/helpers/get-ancestor-navigator-keys.ts

@@ -0,0 +1,29 @@
+import type { BaseStackDescriptor } from "../../../../types/stack.types";
+
+/**
+ * Builds the parent navigator key chain for nested navigators.
+ * Returns keys from immediate parent navigator to root navigator.
+ */
+export function getAncestorNavigatorKeys(
+	current: BaseStackDescriptor,
+): string[] {
+	const ancestors: string[] = [];
+	const nav = current.navigation as any;
+
+	if (typeof nav?.getParent !== "function") {
+		return ancestors;
+	}
+
+	let parent = nav.getParent();
+
+	while (parent) {
+		const state = parent.getState?.();
+		const key = state?.key;
+		if (typeof key === "string") {
+			ancestors.push(key);
+		}
+		parent = parent.getParent?.();
+	}
+
+	return ancestors;
+}

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

@@ -0,0 +1,6 @@
+export {
+	type BaseDescriptor,
+	DescriptorsProvider,
+	useDescriptorDerivations,
+	useDescriptors,
+} from "./descriptors.provider";

package/src/shared/providers/screen/screen-composer.tsx

@@ -1,8 +1,9 @@
 import type React from "react";
 import { ScreenContainer } from "../../components/screen-container";
 import { ScreenLifecycle } from "../../components/screen-lifecycle";
-import { ScreenGestureProvider } from "../gestures.provider";
-import { type BaseDescriptor, KeysProvider } from "./keys.provider";
+import { ScreenGestureProvider } from "../gestures";
+import { ScreenAnimationProvider } from "./animation";
+import { type BaseDescriptor, DescriptorsProvider } from "./descriptors";
 import { ScreenStylesProvider } from "./styles.provider";
 
 type Props<TDescriptor extends BaseDescriptor> = {
@@ -19,14 +20,16 @@ export function ScreenComposer<TDescriptor extends BaseDescriptor>({
 	children,
 }: Props<TDescriptor>) {
 	return (
-		<ScreenLifecycle current={current} previous={previous}>
-			<KeysProvider previous={previous} current={current} next={next}>
+		<DescriptorsProvider previous={previous} current={current} next={next}>
+			<ScreenLifecycle>
 				<ScreenGestureProvider>
-					<ScreenStylesProvider>
-						<ScreenContainer>{children}</ScreenContainer>
-					</ScreenStylesProvider>
+					<ScreenAnimationProvider>
+						<ScreenStylesProvider>
+							<ScreenContainer>{children}</ScreenContainer>
+						</ScreenStylesProvider>
+					</ScreenAnimationProvider>
 				</ScreenGestureProvider>
-			</KeysProvider>
-		</ScreenLifecycle>
+			</ScreenLifecycle>
+		</DescriptorsProvider>
 	);
 }