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

package/src/providers/stack/stack-transition/stack-transition-controller.ts

@@ -0,0 +1,341 @@
+import { EPSILON } from "../../../constants";
+import type { BlankStackStoreValue } from "../../../types/providers/blank-stack-provider.types";
+import type { SnapPoint } from "../../../types/screen.types";
+
+export type StackTransitionDirection = "forward" | "backward";
+
+export type StackTransitionSelection = {
+	direction: StackTransitionDirection;
+	driverRouteKey: string;
+	sourceRouteKey: string;
+	targetRouteKey: string;
+};
+
+export type StackTransitionStateSnapshot = {
+	focusedIndex: number;
+	scenes: BlankStackStoreValue["scenes"];
+};
+
+export type StackTransitionControllerSnapshot = {
+	selection: StackTransitionSelection | null;
+};
+
+export enum StackTransitionDriverSignal {
+	Idle = 0,
+	Forward = 1,
+	Backward = 2,
+}
+
+export type StackTransitionDriverFrame = {
+	closing: number;
+	dismissalBoundary: number;
+	dismissing: number;
+	dragging: number;
+	entering: number;
+	progressBaseline: number;
+	progressSettled: number;
+	settling: number;
+	targetProgress: number;
+	visualProgress: number;
+};
+
+export type StackTransitionController = {
+	getSnapshot: () => StackTransitionControllerSnapshot;
+	handleDriverSignal: (signal: StackTransitionDriverSignal) => void;
+	subscribe: (listener: () => void) => () => void;
+	update: (snapshot: StackTransitionStateSnapshot) => void;
+};
+
+const getFocusedScene = (snapshot: StackTransitionStateSnapshot) =>
+	snapshot.scenes[snapshot.focusedIndex];
+
+const findScene = (
+	snapshot: StackTransitionStateSnapshot,
+	routeKey: string | undefined,
+) =>
+	routeKey
+		? snapshot.scenes.find((scene) => scene.route.key === routeKey)
+		: undefined;
+
+const createForwardSelection = (
+	snapshot: StackTransitionStateSnapshot,
+): StackTransitionSelection | null => {
+	const target = getFocusedScene(snapshot);
+	const source = findScene(snapshot, target?.previousDescriptor?.route.key);
+
+	if (!source || !target || target.activity !== "active") {
+		return null;
+	}
+
+	return {
+		direction: "forward",
+		driverRouteKey: target.route.key,
+		sourceRouteKey: source.route.key,
+		targetRouteKey: target.route.key,
+	};
+};
+
+const createBackwardSelection = (
+	snapshot: StackTransitionStateSnapshot,
+): StackTransitionSelection | null => {
+	const focused = getFocusedScene(snapshot);
+	const focusedPrevious = findScene(
+		snapshot,
+		focused?.previousDescriptor?.route.key,
+	);
+
+	if (focused?.activity === "active" && focusedPrevious) {
+		return {
+			direction: "backward",
+			driverRouteKey: focused.route.key,
+			sourceRouteKey: focused.route.key,
+			targetRouteKey: focusedPrevious.route.key,
+		};
+	}
+
+	const focusedRouteKey = focused?.route.key;
+	const closing = [...snapshot.scenes].reverse().find((scene) => {
+		if (scene.activity !== "closing") return false;
+		if (!focusedRouteKey) return true;
+
+		return scene.previousDescriptor?.route.key === focusedRouteKey;
+	});
+	const fallbackClosing =
+		closing ??
+		[...snapshot.scenes]
+			.reverse()
+			.find((scene) => scene.activity === "closing");
+	const target = findScene(
+		snapshot,
+		fallbackClosing?.previousDescriptor?.route.key,
+	);
+
+	if (!fallbackClosing || !target) {
+		return null;
+	}
+
+	return {
+		direction: "backward",
+		driverRouteKey: fallbackClosing.route.key,
+		sourceRouteKey: fallbackClosing.route.key,
+		targetRouteKey: target.route.key,
+	};
+};
+
+const createFocusChangeSelection = (
+	previous: StackTransitionStateSnapshot,
+	next: StackTransitionStateSnapshot,
+): StackTransitionSelection | null => {
+	const previousFocused = getFocusedScene(previous);
+	const nextFocused = getFocusedScene(next);
+
+	if (
+		!previousFocused ||
+		!nextFocused ||
+		previousFocused.route.key === nextFocused.route.key
+	) {
+		return null;
+	}
+
+	const targetExisted = previous.scenes.some(
+		(scene) => scene.route.key === nextFocused.route.key,
+	);
+
+	if (targetExisted) {
+		return {
+			direction: "backward",
+			driverRouteKey: previousFocused.route.key,
+			sourceRouteKey: previousFocused.route.key,
+			targetRouteKey: nextFocused.route.key,
+		};
+	}
+
+	return {
+		direction: "forward",
+		driverRouteKey: nextFocused.route.key,
+		sourceRouteKey: previousFocused.route.key,
+		targetRouteKey: nextFocused.route.key,
+	};
+};
+
+const areSelectionsEqual = (
+	left: StackTransitionSelection | null,
+	right: StackTransitionSelection | null,
+) =>
+	left === right ||
+	(left !== null &&
+		right !== null &&
+		left.direction === right.direction &&
+		left.driverRouteKey === right.driverRouteKey &&
+		left.sourceRouteKey === right.sourceRouteKey &&
+		left.targetRouteKey === right.targetRouteKey);
+
+export const normalizeStackTransitionProgress = (
+	direction: StackTransitionDirection,
+	driverProgress: number,
+	dismissalBoundary: number,
+) => {
+	"worklet";
+
+	const normalizedDriverProgress = Math.min(
+		1,
+		Math.max(0, driverProgress / Math.max(EPSILON, dismissalBoundary)),
+	);
+
+	return direction === "forward"
+		? normalizedDriverProgress
+		: 1 - normalizedDriverProgress;
+};
+
+export const resolveStackTransitionDismissalBoundary = ({
+	progressBaseline,
+	resolvedAutoSnapPoint,
+	snapPoints,
+}: {
+	progressBaseline: number;
+	resolvedAutoSnapPoint: number;
+	snapPoints: SnapPoint[] | undefined;
+}) => {
+	"worklet";
+
+	if (!snapPoints?.length) return progressBaseline;
+
+	let boundary = Number.POSITIVE_INFINITY;
+	for (let index = 0; index < snapPoints.length; index++) {
+		const snapPoint = snapPoints[index];
+		const resolvedSnapPoint =
+			snapPoint === "auto" ? resolvedAutoSnapPoint : snapPoint;
+
+		if (
+			Number.isFinite(resolvedSnapPoint) &&
+			resolvedSnapPoint > EPSILON &&
+			resolvedSnapPoint < boundary
+		) {
+			boundary = resolvedSnapPoint;
+		}
+	}
+
+	return Number.isFinite(boundary) ? boundary : progressBaseline;
+};
+
+export const resolveStackTransitionDriverSignal = ({
+	closing,
+	dismissalBoundary,
+	dismissing,
+	dragging,
+	entering,
+	progressBaseline,
+	progressSettled,
+	settling,
+	targetProgress,
+	visualProgress,
+}: StackTransitionDriverFrame): StackTransitionDriverSignal => {
+	"worklet";
+
+	if (closing || dismissing || (!progressSettled && targetProgress === 0)) {
+		return StackTransitionDriverSignal.Backward;
+	}
+
+	if (entering) {
+		return StackTransitionDriverSignal.Forward;
+	}
+
+	if (
+		(dragging || settling) &&
+		visualProgress < Math.min(progressBaseline, dismissalBoundary) - EPSILON
+	) {
+		return StackTransitionDriverSignal.Backward;
+	}
+
+	return StackTransitionDriverSignal.Idle;
+};
+
+export const createStackTransitionController = (
+	initialState: StackTransitionStateSnapshot,
+): StackTransitionController => {
+	let state = initialState;
+	let driverActivated = false;
+	let snapshot: StackTransitionControllerSnapshot = { selection: null };
+	const listeners = new Set<() => void>();
+
+	const setSelection = (
+		selection: StackTransitionSelection | null,
+		notify: boolean,
+	) => {
+		if (areSelectionsEqual(snapshot.selection, selection)) return false;
+
+		snapshot = { selection };
+		driverActivated = false;
+		if (notify) {
+			for (const listener of listeners) listener();
+		}
+		return true;
+	};
+
+	const update = (nextState: StackTransitionStateSnapshot) => {
+		const focusChange = createFocusChangeSelection(state, nextState);
+		state = nextState;
+
+		if (focusChange) {
+			setSelection(focusChange, false);
+			return;
+		}
+
+		const selection = snapshot.selection;
+		if (
+			selection &&
+			!nextState.scenes.some(
+				(scene) => scene.route.key === selection.driverRouteKey,
+			)
+		) {
+			setSelection(null, false);
+			return;
+		}
+
+		if (!selection) {
+			const closingSelection = createBackwardSelection(nextState);
+			if (
+				closingSelection &&
+				findScene(nextState, closingSelection.driverRouteKey)?.activity ===
+					"closing"
+			) {
+				setSelection(closingSelection, false);
+			}
+		}
+	};
+
+	const handleDriverSignal = (signal: StackTransitionDriverSignal) => {
+		if (signal === StackTransitionDriverSignal.Idle) {
+			if (driverActivated) setSelection(null, true);
+			return;
+		}
+
+		const direction =
+			signal === StackTransitionDriverSignal.Forward ? "forward" : "backward";
+		const currentSelection = snapshot.selection;
+
+		if (currentSelection?.direction === direction) {
+			driverActivated = true;
+			return;
+		}
+
+		const selection =
+			direction === "forward"
+				? createForwardSelection(state)
+				: createBackwardSelection(state);
+		if (!selection) return;
+
+		setSelection(selection, true);
+		driverActivated = true;
+	};
+
+	return {
+		getSnapshot: () => snapshot,
+		handleDriverSignal,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		update,
+	};
+};

package/src/providers/stack/stack-transition/stack-transition.provider.tsx

@@ -0,0 +1,120 @@
+import { type ReactNode, useMemo, useRef, useSyncExternalStore } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { AnimationStore } from "../../../stores/animation.store";
+import { GestureStore } from "../../../stores/gesture.store";
+import { SystemStore } from "../../../stores/system.store";
+import type { SnapPoint } from "../../../types/screen.types";
+import createProvider from "../../../utils/create-provider";
+import { useBlankStackStore } from "../blank-stack.provider";
+import {
+	createStackTransitionController,
+	resolveStackTransitionDismissalBoundary,
+	resolveStackTransitionDriverSignal,
+	type StackTransitionController,
+	StackTransitionDriverSignal,
+	type StackTransitionSelection,
+} from "./stack-transition-controller";
+
+type StackTransitionProviderProps = {
+	children: ReactNode;
+};
+
+type StackTransitionStoreValue = {
+	selection: StackTransitionSelection | null;
+};
+
+const useDriverSignal = ({
+	controller,
+	driverRouteKey,
+	snapPoints,
+}: {
+	controller: StackTransitionController;
+	driverRouteKey: string | undefined;
+	snapPoints: SnapPoint[] | undefined;
+}) => {
+	const driver = useMemo(() => {
+		if (!driverRouteKey) return null;
+
+		return {
+			animations: AnimationStore.getBag(driverRouteKey),
+			gestures: GestureStore.getBag(driverRouteKey),
+			system: SystemStore.getBag(driverRouteKey),
+		};
+	}, [driverRouteKey]);
+
+	useAnimatedReaction(
+		() => {
+			if (!driver) return StackTransitionDriverSignal.Idle;
+			const progressBaseline = driver.gestures.internal.progressBaseline.get();
+
+			return resolveStackTransitionDriverSignal({
+				closing: driver.animations.closing.get(),
+				dismissalBoundary: resolveStackTransitionDismissalBoundary({
+					progressBaseline,
+					resolvedAutoSnapPoint: driver.system.resolvedAutoSnapPoint.get(),
+					snapPoints,
+				}),
+				dismissing: driver.gestures.dismissing.get(),
+				dragging: driver.gestures.dragging.get(),
+				entering: driver.animations.entering.get(),
+				progressBaseline,
+				progressSettled: driver.animations.progressSettled.get(),
+				settling: driver.gestures.settling.get(),
+				targetProgress: driver.system.targetProgress.get(),
+				visualProgress: driver.animations.visualProgress.get(),
+			});
+		},
+		(signal, previousSignal) => {
+			if (signal === previousSignal) return;
+
+			scheduleOnRN(controller.handleDriverSignal, signal);
+		},
+		[controller, driver, snapPoints],
+	);
+};
+
+export const { StackTransitionProvider, useStackTransitionStore } =
+	createProvider("StackTransition")<
+		StackTransitionProviderProps,
+		StackTransitionStoreValue
+	>(({ children }) => {
+		const focusedIndex = useBlankStackStore((store) => store.focusedIndex);
+		const scenes = useBlankStackStore((store) => store.scenes);
+		const controllerRef = useRef<StackTransitionController | null>(null);
+
+		if (!controllerRef.current) {
+			controllerRef.current = createStackTransitionController({
+				focusedIndex,
+				scenes,
+			});
+		}
+
+		const controller = controllerRef.current;
+		controller.update({ focusedIndex, scenes });
+
+		const snapshot = useSyncExternalStore(
+			controller.subscribe,
+			controller.getSnapshot,
+			controller.getSnapshot,
+		);
+		const focusedRouteKey = scenes[focusedIndex]?.route.key;
+		const driverRouteKey =
+			snapshot.selection?.driverRouteKey ?? focusedRouteKey;
+		const driverSnapPoints = scenes.find(
+			(scene) => scene.route.key === driverRouteKey,
+		)?.descriptor.options.snapPoints;
+
+		useDriverSignal({
+			controller,
+			driverRouteKey,
+			snapPoints: driverSnapPoints,
+		});
+
+		return {
+			children,
+			value: {
+				selection: snapshot.selection,
+			},
+		};
+	});

package/src/providers/stack/stack-transition/use-stack-transition.ts

@@ -0,0 +1,77 @@
+import { useMemo } from "react";
+import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
+import { AnimationStore } from "../../../stores/animation.store";
+import { SystemStore } from "../../../stores/system.store";
+import type { BlankStackStoreValue } from "../../../types/providers/blank-stack-provider.types";
+import { useBlankStackStore } from "../blank-stack.provider";
+import { useStackTransitionStore } from "./stack-transition.provider";
+import {
+	normalizeStackTransitionProgress,
+	resolveStackTransitionDismissalBoundary,
+	type StackTransitionDirection,
+} from "./stack-transition-controller";
+
+export type StackTransition = {
+	direction: StackTransitionDirection;
+	driver: BlankStackStoreValue["scenes"][number];
+	progress: DerivedValue<number>;
+	source: BlankStackStoreValue["scenes"][number];
+	target: BlankStackStoreValue["scenes"][number];
+};
+
+export const useStackTransition = (): StackTransition | null => {
+	const selection = useStackTransitionStore((store) => store.selection);
+	const scenesByKey = useBlankStackStore((store) => store.scenesByKey);
+	const driverProgress = useMemo(
+		() =>
+			selection
+				? AnimationStore.getValue(selection.driverRouteKey, "visualProgress")
+				: null,
+		[selection],
+	);
+	const resolvedAutoSnapPoint = useMemo(
+		() =>
+			selection
+				? SystemStore.getValue(
+						selection.driverRouteKey,
+						"resolvedAutoSnapPoint",
+					)
+				: null,
+		[selection],
+	);
+	const driverSnapPoints = selection
+		? scenesByKey[selection.driverRouteKey]?.descriptor.options.snapPoints
+		: undefined;
+	const direction = selection?.direction ?? "forward";
+	const progress = useDerivedValue(() => {
+		if (!driverProgress) return 0;
+		const dismissalBoundary = resolveStackTransitionDismissalBoundary({
+			progressBaseline: 1,
+			resolvedAutoSnapPoint: resolvedAutoSnapPoint?.get() ?? -1,
+			snapPoints: driverSnapPoints,
+		});
+
+		return normalizeStackTransitionProgress(
+			direction,
+			driverProgress.get(),
+			dismissalBoundary,
+		);
+	}, [direction, driverProgress, driverSnapPoints, resolvedAutoSnapPoint]);
+
+	return useMemo(() => {
+		if (!selection) return null;
+
+		const source = scenesByKey[selection.sourceRouteKey];
+		const target = scenesByKey[selection.targetRouteKey];
+		const driver = scenesByKey[selection.driverRouteKey];
+		if (!source || !target || !driver) return null;
+
+		return {
+			direction: selection.direction,
+			driver,
+			progress,
+			source,
+			target,
+		};
+	}, [progress, scenesByKey, selection]);
+};

package/src/types/animation.types.ts

@@ -171,11 +171,7 @@ export type ScreenTransitionDepthTarget = {
 	depth: number;
 };
 
-export type ScreenTransitionTarget = ScreenTransitionDepthTarget;
-
-export type ScreenTransitionAccessor = (
-	target?: ScreenTransitionTarget,
-) => ScreenInterpolationProps | null;
+export type ScreenTransitionTarget = ScreenTransitionDepthTarget | string;
 
 export interface ScreenInterpolationProps {
 	/**
@@ -237,20 +233,6 @@ export interface ScreenInterpolationProps {
 	 */
 	bounds: BoundsAccessor;
 
-	/**
-	 * Resolves interpolation props for this screen's transition timeline or an
-	 * ancestor/descendant transition timeline.
-	 *
-	 * Calling without a target returns the current transition.
-	 * `transition({ depth: -1 })` returns the immediate parent transition.
-	 * `transition({ depth: 1 })` returns the immediate child transition.
-	 * `transition({ depth: 0 })` returns the current transition.
-	 *
-	 * When called from a returned transition scope, targets are resolved relative
-	 * to that scope.
-	 */
-	transition: ScreenTransitionAccessor;
-
 	/**
 	 * The screen state that is currently driving the transition (either current or next, whichever is focused).
 	 */

package/src/types/bounds.types.ts

@@ -229,9 +229,6 @@ export type BoundsAccessor = (
 	options: BoundsIdentityInput,
 ) => BoundsScopedAccessor;
 
-export type BoundsInterpolationProps = Omit<
-	ScreenInterpolationProps,
-	"bounds" | "transition"
->;
+export type BoundsInterpolationProps = Omit<ScreenInterpolationProps, "bounds">;
 
 export type { BoundsMotion, BoundsMotionFrame, BoundsMotionTransform };

package/src/types/index.ts

@@ -5,7 +5,6 @@ export type {
 	BoundaryHandoffTarget,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
-	ScreenTransitionAccessor,
 	ScreenTransitionDepthTarget,
 	ScreenTransitionOptions,
 	ScreenTransitionState,

package/src/types/ownership.types.ts

@@ -5,7 +5,7 @@
  * 1. Gestures dismiss stacks, not screens
  * 2. Ownership is per-direction (4 independent directions)
  * 3. Shadowing: child claiming same direction blocks parent
- * 4. Inheritance: no local claim walks up tree to find owner
+ * 4. Inheritance: topology resolves the nearest claiming ancestor
  */
 
 /**
@@ -50,28 +50,3 @@ export const NO_CLAIMS: ClaimedDirections = {
 	horizontal: false,
 	"horizontal-inverted": false,
 };
-
-/**
- * Ownership status for a direction relative to the current screen.
- *
- * - 'self': Current screen owns this direction (should activate)
- * - 'ancestor': An ancestor owns this direction (should fail to bubble up)
- * - 'none': No one owns this direction (should fail, no gesture response)
- */
-export type OwnershipStatus = "self" | "ancestor" | "none";
-
-/**
- * Map of ownership status for all four directions.
- * Pre-computed during render for worklet access.
- */
-export type DirectionOwnership = Record<Direction, OwnershipStatus>;
-
-/**
- * Empty ownership - used when no gestures are configured anywhere.
- */
-export const NO_OWNERSHIP: DirectionOwnership = {
-	vertical: "none",
-	"vertical-inverted": "none",
-	horizontal: "none",
-	"horizontal-inverted": "none",
-};

package/src/types/screen.types.ts

@@ -205,6 +205,16 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 };
 
 export type ScreenTransitionConfig = {
+	/**
+	 * Globally identifies this mounted screen for keyed animation observation.
+	 *
+	 * The key must be unique among mounted screens.
+	 *
+	 * @example
+	 * options={{ transitionKey: "feed" }}
+	 */
+	transitionKey?: string;
+
 	/**
 	 * The user-provided function to calculate styles based on animation progress.
 	 *