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

package/src/shared/{hooks/animation/use-screen-animation.tsx → providers/screen/animation/helpers/pipeline.ts}

@@ -1,28 +1,34 @@
 import { useMemo } from "react";
-import { useWindowDimensions } from "react-native";
-import { type SharedValue, useDerivedValue } from "react-native-reanimated";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
-import type { NativeStackScreenTransitionConfig } from "../../../native-stack/types";
+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";
+} from "../../../../constants";
+import { useStack } from "../../../../hooks/navigation/use-stack";
+import { AnimationStore } from "../../../../stores/animation.store";
 import {
-	type BaseDescriptor,
-	useKeys,
-} from "../../providers/screen/keys.provider";
-import { AnimationStore } from "../../stores/animation.store";
-import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
+	GestureStore,
+	type GestureStoreMap,
+} from "../../../../stores/gesture.store";
 import type {
 	ScreenInterpolationProps,
+	ScreenStyleInterpolator,
 	ScreenTransitionState,
-} from "../../types/animation.types";
-import type { ScreenTransitionConfig } from "../../types/screen.types";
-import type { BaseStackRoute } from "../../types/stack.types";
-import { derivations } from "../../utils/animation/derivations";
-import { toPlainRoute, toPlainValue } from "../../utils/animation/worklet";
-import { createBounds } from "../../utils/bounds";
-import { useStack } from "../navigation/use-stack";
+} 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>;
@@ -35,6 +41,15 @@ type BuiltState = {
 	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.
@@ -65,11 +80,25 @@ const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 	out.animating = s.animating.value;
 	out.gesture.x = s.gesture.x.value;
 	out.gesture.y = s.gesture.y.value;
-	out.gesture.normalizedX = s.gesture.normalizedX.value;
-	out.gesture.normalizedY = s.gesture.normalizedY.value;
-	out.gesture.isDismissing = s.gesture.isDismissing.value;
-	out.gesture.isDragging = s.gesture.isDragging.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;
@@ -77,10 +106,18 @@ const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 
 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;
@@ -91,16 +128,19 @@ const useBuildScreenTransitionState = (
 			: undefined;
 
 		return {
-			progress: AnimationStore.getAnimation(key, "progress"),
-			closing: AnimationStore.getAnimation(key, "closing"),
-			entering: AnimationStore.getAnimation(key, "entering"),
-			animating: AnimationStore.getAnimation(key, "animating"),
-			gesture: GestureStore.getRouteGestures(key),
+			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]);
+	}, [key, meta, route, shouldUseNeutralNextGestures]);
 };
 
 const hasTransitionsEnabled = (
@@ -111,22 +151,26 @@ const hasTransitionsEnabled = (
 	return !!(options as NativeStackScreenTransitionConfig)?.enableTransitions;
 };
 
-export function _useScreenAnimation() {
-	const insets = useSafeAreaInsets();
-	const dimensions = useWindowDimensions();
-
+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,
-	} = useKeys();
+	} = useDescriptors();
 
-	const currentAnimation = useBuildScreenTransitionState(currentDescriptor);
-	const nextAnimation = useBuildScreenTransitionState(nextDescriptor);
-	const prevAnimation = useBuildScreenTransitionState(previousDescriptor);
+	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);
@@ -141,6 +185,31 @@ export function _useScreenAnimation() {
 		!!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,
+		isActiveTransitioning: false,
+		isDismissing: false,
+	});
+
+	const boundsAccessor = useMemo(() => {
+		return createBoundsAccessor(() => {
+			"worklet";
+			return framePropsMutable.value;
+		});
+	}, [framePropsMutable]);
+
 	const screenInterpolatorProps = useDerivedValue<
 		Omit<ScreenInterpolationProps, "bounds">
 	>(() => {
@@ -171,7 +240,7 @@ export function _useScreenAnimation() {
 
 		const snapIndex = computeSnapIndex(current.progress, sortedSnapPoints);
 
-		return {
+		const nextProps = {
 			layouts: { screen: dimensions },
 			insets,
 			previous,
@@ -182,6 +251,9 @@ export function _useScreenAnimation() {
 			snapIndex,
 			...helpers,
 		};
+
+		framePropsMutable.value = nextProps;
+		return nextProps;
 	});
 
 	const nextInterpolator = nextDescriptor?.options.screenStyleInterpolator;
@@ -192,17 +264,6 @@ export function _useScreenAnimation() {
 		screenInterpolatorProps,
 		nextInterpolator,
 		currentInterpolator,
+		boundsAccessor,
 	};
 }
-
-export function useScreenAnimation() {
-	const { screenInterpolatorProps } = _useScreenAnimation();
-
-	return useDerivedValue<ScreenInterpolationProps>(() => {
-		const props = screenInterpolatorProps.value;
-		return {
-			...props,
-			bounds: createBounds(props),
-		};
-	});
-}

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,5 @@
+export {
+	ScreenAnimationProvider,
+	useScreenAnimationContext,
+} from "./animation.provider";
+export { useScreenAnimation } from "./use-screen-animation";

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

@@ -0,0 +1,6 @@
+import { useScreenAnimationContext } from "./animation.provider";
+
+export function useScreenAnimation() {
+	const { screenAnimation } = useScreenAnimationContext();
+	return screenAnimation;
+}

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>
 	);
 }