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

package/src/providers/screen/orchestrator/helpers/pipeline.ts

@@ -0,0 +1,341 @@
+import { useMemo } from "react";
+import { useWindowDimensions } from "react-native";
+import {
+	type DerivedValue,
+	type SharedValue,
+	useDerivedValue,
+	useSharedValue,
+} from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import {
+	createScreenTransitionState,
+	DEFAULT_SCREEN_TRANSITION_STATE,
+} from "../../../../constants";
+import type {
+	ScreenInterpolationProps,
+	ScreenStyleInterpolator,
+	ScreenTransitionState,
+} from "../../../../types/animation.types";
+import { useOptionalBlankStackStore } from "../../../stack/blank-stack.provider";
+import { type BaseDescriptor, useBuilderStore } from "../../builder";
+import { useMotionStore, useOptionalMotionStore } from "../../motion";
+import { buildScreenTransitionOptions } from "../../motion/animation/helpers/build-screen-transition-options";
+import { hydrateTransitionState } from "../../motion/animation/helpers/hydrate-transition-state";
+import type { BuiltState } from "../../motion/animation/helpers/hydrate-transition-state/types";
+import {
+	toPlainRoute,
+	toPlainValue,
+} from "../../motion/animation/helpers/worklet";
+import { updateDerivations } from "./derivations";
+import type { SelectedInterpolatorOptions } from "./selected-interpolator-options";
+import { readStackProgress, type StackProgressEntry } from "./stack-progress";
+import { useInterpolatorState } from "./use-interpolator-state";
+
+const NO_ROUTE_KEYS: readonly string[] = [];
+
+export type ScreenInterpolatorFrame = Omit<
+	ScreenInterpolationProps,
+	"bounds" | "transition"
+>;
+
+export interface ScreenAnimationPipeline {
+	screenInterpolatorProps: DerivedValue<ScreenInterpolatorFrame>;
+	selectedInterpolatorOptions: SharedValue<SelectedInterpolatorOptions>;
+	nextInterpolator: ScreenStyleInterpolator | undefined;
+	currentInterpolator: ScreenStyleInterpolator | undefined;
+}
+
+const getInitialSettledProgress = (descriptor: BaseDescriptor) => {
+	const { snapPoints, initialSnapIndex = 0 } = descriptor.options;
+
+	if (!snapPoints?.length) {
+		return 1;
+	}
+
+	const clampedIndex = Math.min(
+		Math.max(0, initialSnapIndex),
+		snapPoints.length - 1,
+	);
+	const snapPoint = snapPoints[clampedIndex];
+
+	return typeof snapPoint === "number" ? snapPoint : 0;
+};
+
+const applyInitialProgress = ({
+	state,
+	dimensions,
+	progress,
+	entering = 0,
+	closing = 0,
+	animating = 0,
+	willAnimate = 0,
+	settled = entering || closing || animating ? 0 : 1,
+}: {
+	state: ScreenTransitionState;
+	dimensions: ScreenInterpolatorFrame["layouts"]["screen"];
+	progress: number;
+	entering?: number;
+	closing?: number;
+	animating?: number;
+	willAnimate?: number;
+	settled?: number;
+}) => {
+	state.progress = progress;
+	state.transitionProgress = progress;
+	state.entering = entering;
+	state.closing = closing;
+	state.animating = animating;
+	state.willAnimate = willAnimate;
+	state.settled = settled;
+	state.layouts.screen = dimensions;
+
+	return state;
+};
+
+const createInitialTransitionState = ({
+	descriptor,
+	dimensions,
+	progress,
+	entering,
+	animating,
+	willAnimate,
+	settled,
+}: {
+	descriptor: BaseDescriptor;
+	dimensions: ScreenInterpolatorFrame["layouts"]["screen"];
+	progress: number;
+	entering?: number;
+	animating?: number;
+	willAnimate?: number;
+	settled?: number;
+}) => {
+	const meta = descriptor.options.meta
+		? (toPlainValue(descriptor.options.meta) as Record<string, unknown>)
+		: undefined;
+	const state = createScreenTransitionState(
+		toPlainRoute(descriptor.route),
+		meta,
+		buildScreenTransitionOptions(descriptor.options),
+	);
+
+	return applyInitialProgress({
+		state,
+		dimensions,
+		progress,
+		entering,
+		animating,
+		willAnimate,
+		settled,
+	});
+};
+
+const createInitialInterpolatorProps = ({
+	dimensions,
+	insets,
+	currentDescriptor,
+	nextDescriptor,
+	prevDescriptor,
+}: {
+	dimensions: ScreenInterpolatorFrame["layouts"]["screen"];
+	insets: ScreenInterpolatorFrame["insets"];
+	currentDescriptor: BaseDescriptor;
+	nextDescriptor?: BaseDescriptor;
+	prevDescriptor?: BaseDescriptor;
+}): ScreenInterpolatorFrame => {
+	const hasIncomingNext = !!nextDescriptor;
+	const isFocusedEntering = !!prevDescriptor && !nextDescriptor;
+	const shouldAnimateInitialMount =
+		!prevDescriptor &&
+		!nextDescriptor &&
+		!!currentDescriptor.options.experimental_animateOnInitialMount;
+	const currentProgress =
+		hasIncomingNext || (!isFocusedEntering && !shouldAnimateInitialMount)
+			? getInitialSettledProgress(currentDescriptor)
+			: 0;
+	const currentEntering =
+		isFocusedEntering || shouldAnimateInitialMount ? 1 : 0;
+	const current = createInitialTransitionState({
+		descriptor: currentDescriptor,
+		dimensions,
+		progress: currentProgress,
+		entering: currentEntering,
+		animating: currentEntering,
+		willAnimate: 0,
+	});
+	const previous = prevDescriptor
+		? createInitialTransitionState({
+				descriptor: prevDescriptor,
+				dimensions,
+				progress: getInitialSettledProgress(prevDescriptor),
+			})
+		: undefined;
+	const next = nextDescriptor
+		? createInitialTransitionState({
+				descriptor: nextDescriptor,
+				dimensions,
+				progress: 0,
+				entering: 1,
+				animating: 1,
+				willAnimate: 0,
+				settled: 0,
+			})
+		: undefined;
+	const frame: ScreenInterpolatorFrame = {
+		layouts: current.layouts,
+		insets,
+		previous,
+		current,
+		next,
+		progress: 0,
+		transitionProgress: 0,
+		stackProgress: 0,
+		focused: true,
+		active: current,
+		inactive: undefined,
+	};
+
+	updateDerivations(frame);
+	frame.stackProgress = frame.progress;
+
+	return frame;
+};
+
+const hydrateInterpolatorFrame = <TFrame extends ScreenInterpolatorFrame>({
+	frame,
+	dimensions,
+	insets,
+	currentAnimation,
+	nextAnimation,
+	prevAnimation,
+	interpolatorOptions,
+	stackProgressEntries,
+	currentRouteKey,
+}: {
+	frame: TFrame;
+	dimensions: ScreenInterpolatorFrame["layouts"]["screen"];
+	insets: ScreenInterpolatorFrame["insets"];
+	currentAnimation: BuiltState | undefined;
+	nextAnimation: BuiltState | undefined;
+	prevAnimation: BuiltState | undefined;
+	interpolatorOptions: SelectedInterpolatorOptions;
+	stackProgressEntries: readonly StackProgressEntry[];
+	currentRouteKey: string;
+}): TFrame => {
+	"worklet";
+	const shouldApplyOptionsToCurrent = interpolatorOptions.owner === "current";
+	const shouldApplyOptionsToNext =
+		interpolatorOptions.owner === "next" && !!nextAnimation;
+
+	frame.previous = prevAnimation
+		? hydrateTransitionState(prevAnimation, dimensions)
+		: undefined;
+
+	frame.current = currentAnimation
+		? hydrateTransitionState(
+				currentAnimation,
+				dimensions,
+				shouldApplyOptionsToCurrent ? interpolatorOptions.options : undefined,
+			)
+		: DEFAULT_SCREEN_TRANSITION_STATE;
+
+	frame.next = nextAnimation
+		? hydrateTransitionState(
+				nextAnimation,
+				dimensions,
+				shouldApplyOptionsToNext ? interpolatorOptions.options : undefined,
+			)
+		: undefined;
+
+	frame.layouts = frame.current.layouts;
+	frame.insets = insets;
+
+	updateDerivations(frame);
+
+	frame.stackProgress = readStackProgress(
+		stackProgressEntries,
+		currentRouteKey,
+		frame.progress,
+	);
+
+	return frame;
+};
+
+export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
+	const routeKeys = useOptionalBlankStackStore(
+		(store) => store?.routeKeys ?? NO_ROUTE_KEYS,
+	);
+	const dimensions = useWindowDimensions();
+	const insets = useSafeAreaInsets();
+	const stackMotions = useMotionStore(routeKeys);
+	const stackProgressEntries = useMemo(
+		() =>
+			routeKeys.flatMap((routeKey, index) => {
+				const motion = stackMotions[index];
+				return motion
+					? [{ routeKey, visualProgress: motion.state.visualProgress }]
+					: [];
+			}),
+		[routeKeys, stackMotions],
+	);
+
+	const currDescriptor = useBuilderStore((store) => store.descriptors.current);
+	const nextDescriptor = useBuilderStore((store) => store.descriptors.next);
+	const prevDescriptor = useBuilderStore((store) => store.descriptors.previous);
+	const currentMotion = useMotionStore((store) => store.state);
+	const nextMotion = useOptionalMotionStore(
+		nextDescriptor?.route.key ?? null,
+		(store) => store.state,
+	);
+	const previousMotion = useOptionalMotionStore(
+		prevDescriptor?.route.key ?? null,
+		(store) => store.state,
+	);
+	const currentAnimation = useInterpolatorState(currentMotion);
+	const nextAnimation = useInterpolatorState(nextMotion);
+	const prevAnimation = useInterpolatorState(previousMotion);
+	const currentRouteKey = currDescriptor.route.key;
+
+	const initialInterpolatorProps = useMemo(
+		() =>
+			createInitialInterpolatorProps({
+				dimensions,
+				insets,
+				currentDescriptor: currDescriptor,
+				nextDescriptor,
+				prevDescriptor,
+			}),
+		[dimensions, insets, currDescriptor, nextDescriptor, prevDescriptor],
+	);
+
+	const selectedInterpolatorOptions =
+		useSharedValue<SelectedInterpolatorOptions>({
+			owner: "current",
+		});
+	const screenInterpolatorProps = useDerivedValue<ScreenInterpolatorFrame>(
+		() => {
+			"worklet";
+			const interpolatorOptions = selectedInterpolatorOptions.get();
+			return hydrateInterpolatorFrame({
+				frame: { ...initialInterpolatorProps },
+				dimensions,
+				insets,
+				currentAnimation,
+				nextAnimation,
+				prevAnimation,
+				interpolatorOptions,
+				stackProgressEntries,
+				currentRouteKey,
+			});
+		},
+	);
+
+	const nextInterpolator = nextDescriptor?.options.screenStyleInterpolator;
+	const currentInterpolator = currDescriptor.options.screenStyleInterpolator;
+
+	return {
+		screenInterpolatorProps,
+		selectedInterpolatorOptions,
+		nextInterpolator,
+		currentInterpolator,
+	};
+}

package/src/providers/screen/orchestrator/helpers/use-interpolator-state.ts

@@ -0,0 +1,35 @@
+import { useMemo, useState } from "react";
+import {
+	createScreenTransitionState,
+	DEFAULT_SCREEN_TRANSITION_STATE,
+} from "../../../../constants";
+import type {
+	BuiltState,
+	MotionAnimationState,
+} from "../../motion/animation/helpers/hydrate-transition-state/types";
+
+// Shared motion inputs can be read by multiple orchestrators. Only the output
+// objects are local, so one reader's overrides cannot mutate another's frame.
+export function useInterpolatorState(
+	motion: MotionAnimationState | null,
+): BuiltState | undefined {
+	// The UI output survives descriptor updates; hydration owns its contents.
+	const [unwrapped] = useState(() =>
+		createScreenTransitionState(
+			motion?.route ?? DEFAULT_SCREEN_TRANSITION_STATE.route,
+		),
+	);
+	return useMemo(
+		() =>
+			motion
+				? {
+						...motion,
+						gesture: motion,
+						optionsSlot: {},
+						contentLayoutSlot: { width: 0, height: 0 },
+						unwrapped,
+					}
+				: undefined,
+		[motion, unwrapped],
+	);
+}

package/src/providers/screen/orchestrator/helpers/use-pair-presentation.ts

@@ -0,0 +1,103 @@
+import { useDerivedValue } from "react-native-reanimated";
+import { NO_STYLES } from "../../../../constants";
+import { pairs } from "../../../../stores/bounds/internals/state";
+import type {
+	NormalizedTransitionInterpolatedStyle,
+	ScreenStyleInterpolator,
+} from "../../../../types/animation.types";
+import { useBuilderStore } from "../../builder";
+import { useMotionStore } from "../../motion";
+import { createInterpolatorScope } from "../styles/helpers/create-interpolator-scope";
+import { normalizeSlots } from "../styles/helpers/normalize-slots";
+import { selectInterpolatorFrame } from "../styles/helpers/select-interpolator-frame";
+import { stripInterpolatorOptions } from "../styles/helpers/strip-interpolator-options";
+import { updateDerivations } from "./derivations";
+import type {
+	ScreenAnimationPipeline,
+	ScreenInterpolatorFrame,
+} from "./pipeline";
+
+export type BoundaryPairPresentation = {
+	pairKey: string;
+	sourceKey: string;
+	destinationKey: string;
+	ready: boolean;
+	source: NormalizedTransitionInterpolatedStyle;
+	destination: NormalizedTransitionInterpolatedStyle;
+};
+
+export function boundarySourceFrame(
+	frame: ScreenInterpolatorFrame,
+): ScreenInterpolatorFrame | undefined {
+	"worklet";
+	if (!frame.previous) return undefined;
+	const source = {
+		...frame,
+		previous: undefined,
+		current: frame.previous,
+		next: frame.current,
+		layouts: frame.previous.layouts,
+	};
+	updateDerivations(source);
+	return source;
+}
+
+export function runBoundaryInterpolator(
+	interpolator: ScreenStyleInterpolator,
+	frame: ScreenInterpolatorFrame,
+	side: "source" | "destination",
+) {
+	"worklet";
+	const raw = interpolator(
+		createInterpolatorScope({
+			frame,
+			selectedFrame: selectInterpolatorFrame(frame, side === "destination"),
+		}),
+	);
+	return raw && typeof raw === "object"
+		? normalizeSlots(stripInterpolatorOptions(raw))
+		: NO_STYLES;
+}
+
+// Each destination owns the output of its incoming pair, even when its source
+// has moved on to another route. All boundaries read this same UI value.
+export function usePairPresentation({
+	screenInterpolatorProps,
+	currentInterpolator,
+}: ScreenAnimationPipeline) {
+	const pairKey = useBuilderStore((s) => s.derivations.destinationPairKey);
+	const ready = useMotionStore((s) => s.isScreenReady);
+	return useDerivedValue(() => {
+		const links = pairKey ? pairs.get()[pairKey]?.links : undefined;
+		if (!pairKey || !links || !currentInterpolator) return undefined;
+		let hasPortal = false;
+		for (const key in links) {
+			const { source, destination } = links[key];
+			if (
+				source?.handoff ||
+				source?.escapeClipping ||
+				destination?.handoff ||
+				destination?.escapeClipping
+			) {
+				hasPortal = true;
+				break;
+			}
+		}
+		if (!hasPortal) return undefined;
+		const frame = screenInterpolatorProps.get();
+		const source = boundarySourceFrame(frame);
+		if (!source) return undefined;
+		return {
+			pairKey,
+			sourceKey: source.current.route.key,
+			destinationKey: frame.current.route.key,
+			ready: ready.get(),
+			source: runBoundaryInterpolator(currentInterpolator, source, "source"),
+			destination: runBoundaryInterpolator(
+				currentInterpolator,
+				frame,
+				"destination",
+			),
+		} satisfies BoundaryPairPresentation;
+	});
+}

package/src/providers/screen/orchestrator/hooks/use-register-gesture-ownership.ts

@@ -0,0 +1,76 @@
+import { useLayoutEffect, useMemo } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import {
+	type ClaimedDirections,
+	NO_CLAIMS,
+} from "../../../../types/ownership.types";
+import { useOptionalBlankStackStore } from "../../../stack/blank-stack.provider";
+import { type BaseDescriptor, useBuilderStore } from "../../builder";
+import { gestureOwnershipCoordinator } from "../../motion/gestures/ownership/gesture-ownership-coordinator";
+import { resolveShadowingClaimDirections } from "../../motion/gestures/ownership/shadowing-claims";
+import { resolveScreenGestureConfig } from "../../motion/gestures/shared/policy";
+import type {
+	GestureOwnerMap,
+	ScreenGestureSource,
+} from "../../motion/gestures/types";
+
+const getDescriptorIsFirstKey = (descriptor: BaseDescriptor): boolean => {
+	const routes = descriptor.navigation.getState()?.routes ?? [];
+	return routes.findIndex((route) => route.key === descriptor.route.key) === 0;
+};
+
+const getDescriptorClaimedDirections = (
+	descriptor: BaseDescriptor | undefined,
+): ClaimedDirections => {
+	if (!descriptor) return NO_CLAIMS;
+
+	return resolveScreenGestureConfig({
+		options: descriptor.options,
+		isFirstKey: getDescriptorIsFirstKey(descriptor),
+	}).participation.claimedDirections;
+};
+
+export const useRegisterGestureOwnership = ({
+	claimedDirections,
+	owners,
+	source,
+}: {
+	claimedDirections: ClaimedDirections;
+	owners: SharedValue<GestureOwnerMap>;
+	source: ScreenGestureSource;
+}) => {
+	const previous = useBuilderStore((store) => store.descriptors.previous);
+	const isClosing = useOptionalBlankStackStore(
+		(store) => store?.scenesByKey[source.routeKey]?.activity === "closing",
+	);
+	const previousClaimedDirections = useMemo(
+		() => getDescriptorClaimedDirections(previous),
+		[previous],
+	);
+	const effectiveClaimedDirections = useMemo(
+		() =>
+			resolveShadowingClaimDirections({
+				isCurrentScreenClosing: isClosing,
+				currentClaimedDirections: claimedDirections,
+				previousClaimedDirections,
+			}),
+		[claimedDirections, isClosing, previousClaimedDirections],
+	);
+
+	useLayoutEffect(() => {
+		gestureOwnershipCoordinator.register({
+			screenKey: source.routeKey,
+			source,
+			claimedDirections,
+			effectiveClaimedDirections,
+			owners,
+		});
+	}, [claimedDirections, effectiveClaimedDirections, owners, source]);
+
+	useLayoutEffect(
+		() => () => {
+			gestureOwnershipCoordinator.unregister(source.routeKey);
+		},
+		[source.routeKey],
+	);
+};

package/src/providers/screen/orchestrator/index.ts

@@ -0,0 +1,6 @@
+export {
+	OrchestratorProvider,
+	type OrchestratorState,
+	useOptionalOrchestratorStore,
+	useOrchestratorStore,
+} from "./orchestrator.provider";

package/src/providers/screen/orchestrator/orchestrator.provider.tsx

@@ -0,0 +1,73 @@
+import { type ReactNode, useMemo } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { NormalizedTransitionInterpolatedStyle } from "../../../types/animation.types";
+import type { BoundsAccessor } from "../../../types/bounds.types";
+import { createBoundsAccessor } from "../../../utils/bounds";
+import createProvider from "../../../utils/create-provider";
+import { useBuilderStore } from "../builder";
+import { useMotionStore } from "../motion";
+import { useScreenAnimationPipeline } from "./helpers/pipeline";
+import { usePairPresentation } from "./helpers/use-pair-presentation";
+import { useRegisterGestureOwnership } from "./hooks/use-register-gesture-ownership";
+import { useInterpolatedStylesMap } from "./styles/hooks/use-interpolated-style-maps";
+import { useResolvedStylesMap } from "./styles/hooks/use-resolved-slot-style-map";
+
+export type OrchestratorProviderProps = {
+	children: ReactNode;
+	/** Reuse an existing screen’s orchestration without rebuilding it. */
+	screenKey?: string;
+};
+
+export type OrchestratorState = ReturnType<
+	typeof useScreenAnimationPipeline
+> & {
+	boundsAccessor: BoundsAccessor;
+	pairPresentation: ReturnType<typeof usePairPresentation>;
+	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
+};
+
+export const {
+	OrchestratorProvider,
+	useOptionalOrchestratorStore,
+	useOrchestratorStore,
+} = createProvider("Orchestrator", {
+	global: true,
+})<OrchestratorProviderProps, OrchestratorState>(() => {
+	const currentScreenKey = useBuilderStore(
+		(store) => store.derivations.currentScreenKey,
+	);
+	const gestures = useMotionStore((store) => store.gestures);
+
+	const pipeline = useScreenAnimationPipeline();
+	const pairPresentation = usePairPresentation(pipeline);
+
+	const localStylesMaps = useInterpolatedStylesMap({ pipeline });
+	const slotsMap = useResolvedStylesMap({ localStylesMaps });
+
+	const { screenInterpolatorProps } = pipeline;
+
+	const boundsAccessor = useMemo(
+		() =>
+			createBoundsAccessor(() => {
+				"worklet";
+				return screenInterpolatorProps.get();
+			}),
+		[screenInterpolatorProps],
+	);
+
+	useRegisterGestureOwnership({
+		claimedDirections: gestures.claimedDirections,
+		owners: gestures.owners,
+		source: gestures,
+	});
+
+	return {
+		key: currentScreenKey,
+		value: {
+			...pipeline,
+			pairPresentation,
+			boundsAccessor,
+			slotsMap,
+		},
+	};
+});