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

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,30 @@
+import { useMemo } from "react";
+import { createScreenTransitionState } 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 {
+	return useMemo(
+		() =>
+			motion
+				? {
+						...motion,
+						gesture: motion,
+						optionsSlot: {},
+						contentLayoutSlot: { width: 0, height: 0 },
+						unwrapped: createScreenTransitionState(
+							motion.route,
+							motion.meta,
+							motion.options,
+						),
+					}
+				: undefined,
+		[motion],
+	);
+}

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,69 @@
+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 { 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;
+	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 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,
+			boundsAccessor,
+			slotsMap,
+		},
+	};
+});

package/src/providers/screen/orchestrator/styles/constants.ts

@@ -0,0 +1,86 @@
+import { PORTAL_HOST_NAME_RESET_VALUE } from "../../../../components/boundary/portal/utils/naming";
+import {
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_ELEMENT_STYLE_ID,
+} from "../../../../constants";
+
+const IDENTITY_TRANSFORM = [
+	{ translateX: 0 },
+	{ translateY: 0 },
+	{ scale: 1 },
+	{ scaleX: 1 },
+	{ scaleY: 1 },
+] as const;
+
+/**
+ * Safe identity resets for transition-owned style props.
+ *
+ * This list should stay limited to props with a predictable neutral value after
+ * an animation finishes. Avoid layout-owning props such as width, height, top,
+ * left, margin, padding, flex, or aspectRatio; resetting those to zero can clip
+ * or collapse user layout. If another visual-only transition prop needs cleanup,
+ * please add its identity value here in a PR.
+ */
+export const STYLE_RESET_VALUES: Record<string, unknown> = {
+	filter: [{ blur: 0.01 }],
+	transform: IDENTITY_TRANSFORM,
+	translateX: 0,
+	translateY: 0,
+	scale: 1,
+	scaleX: 1,
+	scaleY: 1,
+	opacity: 1,
+	zIndex: 0,
+	elevation: 0,
+	overflow: "visible",
+	backgroundColor: "transparent",
+	borderColor: "transparent",
+	borderTopColor: "transparent",
+	borderRightColor: "transparent",
+	borderBottomColor: "transparent",
+	borderLeftColor: "transparent",
+	borderStartColor: "transparent",
+	borderEndColor: "transparent",
+	borderRadius: 0,
+	borderTopLeftRadius: 0,
+	borderTopRightRadius: 0,
+	borderBottomRightRadius: 0,
+	borderBottomLeftRadius: 0,
+	borderTopStartRadius: 0,
+	borderTopEndRadius: 0,
+	borderBottomStartRadius: 0,
+	borderBottomEndRadius: 0,
+	borderStartStartRadius: 0,
+	borderStartEndRadius: 0,
+	borderEndStartRadius: 0,
+	borderEndEndRadius: 0,
+	shadowColor: "transparent",
+	shadowOffset: { width: 0, height: 0 },
+	shadowOpacity: 0,
+	shadowRadius: 0,
+};
+
+export const PROP_RESET_VALUES: Record<string, unknown> = {
+	hostName: PORTAL_HOST_NAME_RESET_VALUE,
+	pointerEvents: "auto",
+};
+
+const RESERVED_STYLE_SLOT_IDS = {
+	overlay: true,
+	content: true,
+	surface: true,
+	backdrop: true,
+	[NAVIGATION_MASK_ELEMENT_STYLE_ID]: true,
+	[NAVIGATION_MASK_CONTAINER_STYLE_ID]: true,
+} as const;
+
+export const isReservedStyleSlot = (slotId: string) => {
+	"worklet";
+	// biome-ignore lint/suspicious/noPrototypeBuiltins: <proj issue>
+	return Object.prototype.hasOwnProperty.call(RESERVED_STYLE_SLOT_IDS, slotId);
+};
+
+export const shouldSlotInherit = (slotId: string) => {
+	"worklet";
+	return !isReservedStyleSlot(slotId);
+};