react-native-screen-transitions 3.9.0-alpha.1 → 3.9.0-alpha.3

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

@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { useWindowDimensions } from "react-native";
 import {
 	type DerivedValue,
@@ -6,20 +7,26 @@ import {
 	useSharedValue,
 } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { DEFAULT_SCREEN_TRANSITION_STATE } from "../../../../constants";
+import {
+	createScreenTransitionState,
+	DEFAULT_SCREEN_TRANSITION_STATE,
+} from "../../../../constants";
 import { useStack } from "../../../../hooks/navigation/use-stack";
 import type {
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
+	ScreenTransitionState,
 } from "../../../../types/animation.types";
 
-import { useDescriptors } from "../../descriptors";
+import { type BaseDescriptor, useDescriptors } from "../../descriptors";
+import { buildScreenTransitionOptions } from "./build-screen-transition-options";
 import { updateDerivations } from "./derivations";
 import { hasTransitionsEnabled } from "./has-transitions-enabled";
 import { hydrateTransitionState } from "./hydrate-transition-state";
 import type { SelectedInterpolatorOptions } from "./selected-interpolator-options";
 import { resolveStackProgress } from "./stack-progress";
 import { useBuildTransitionState } from "./use-build-transition-state";
+import { toPlainRoute, toPlainValue } from "./worklet";
 
 export type ScreenInterpolatorFrame = Omit<
 	ScreenInterpolationProps,
@@ -34,28 +41,236 @@ interface ScreenAnimationPipeline {
 	currentInterpolator: ScreenStyleInterpolator | undefined;
 }
 
-const createInitialBaseInterpolatorProps = (
-	dimensions: ScreenInterpolatorFrame["layouts"]["screen"],
-	insets: ScreenInterpolatorFrame["insets"],
-): ScreenInterpolatorFrame => {
-	const current = {
-		...DEFAULT_SCREEN_TRANSITION_STATE,
-		layouts: { screen: dimensions },
-	};
+const getInitialSettledProgress = (descriptor: BaseDescriptor) => {
+	const { snapPoints, initialSnapIndex = 0 } = descriptor.options;
 
-	return {
+	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.logicallySettled = 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: currentEntering,
+	});
+	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: 1,
+				settled: 0,
+			})
+		: undefined;
+	const frame: ScreenInterpolatorFrame = {
 		layouts: current.layouts,
 		insets,
-		previous: undefined,
+		previous,
 		current,
-		next: undefined,
+		next,
 		progress: 0,
+		transitionProgress: 0,
 		stackProgress: 0,
 		logicallySettled: 1,
 		focused: true,
 		active: current,
 		inactive: undefined,
 	};
+
+	updateDerivations(frame);
+	frame.stackProgress = frame.progress;
+	frame.logicallySettled = frame.active.settled;
+
+	return frame;
+};
+
+type BuiltTransitionState = NonNullable<
+	ReturnType<typeof useBuildTransitionState>
+>;
+
+const hydrateInterpolatorFrame = <TFrame extends ScreenInterpolatorFrame>({
+	frame,
+	dimensions,
+	insets,
+	currentAnimation,
+	nextAnimation,
+	prevAnimation,
+	nextHasTransitions,
+	interpolatorOptions,
+}: {
+	frame: TFrame;
+	dimensions: ScreenInterpolatorFrame["layouts"]["screen"];
+	insets: ScreenInterpolatorFrame["insets"];
+	currentAnimation: BuiltTransitionState | undefined;
+	nextAnimation: BuiltTransitionState | undefined;
+	prevAnimation: BuiltTransitionState | undefined;
+	nextHasTransitions: boolean;
+	interpolatorOptions: SelectedInterpolatorOptions;
+}): TFrame => {
+	"worklet";
+	const shouldApplyOptionsToCurrent = interpolatorOptions.owner === "current";
+	const shouldApplyOptionsToNext =
+		interpolatorOptions.owner === "next" &&
+		!!nextAnimation &&
+		nextHasTransitions;
+	const previousCurrentProgress = currentAnimation?.visualProgress.get();
+	const previousNextProgress =
+		nextAnimation && nextHasTransitions
+			? nextAnimation.visualProgress.get()
+			: undefined;
+
+	frame.previous = prevAnimation
+		? hydrateTransitionState(prevAnimation, dimensions)
+		: undefined;
+
+	frame.current = currentAnimation
+		? hydrateTransitionState(
+				currentAnimation,
+				dimensions,
+				shouldApplyOptionsToCurrent ? interpolatorOptions.options : undefined,
+			)
+		: DEFAULT_SCREEN_TRANSITION_STATE;
+
+	frame.next =
+		nextAnimation && nextHasTransitions
+			? hydrateTransitionState(
+					nextAnimation,
+					dimensions,
+					shouldApplyOptionsToNext ? interpolatorOptions.options : undefined,
+				)
+			: undefined;
+
+	frame.layouts = frame.current.layouts;
+	frame.insets = insets;
+
+	updateDerivations(frame);
+
+	frame.stackProgress = resolveStackProgress(
+		currentAnimation?.stackProgress,
+		frame.progress,
+		frame.current.progress,
+		previousCurrentProgress,
+		frame.next?.progress,
+		previousNextProgress,
+	);
+	frame.logicallySettled = frame.active.settled;
+
+	return frame;
 };
 
 export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
@@ -80,74 +295,42 @@ export function useScreenAnimationPipeline(): ScreenAnimationPipeline {
 		!!nextRouteKey &&
 		hasTransitionsEnabled(nextDescriptor?.options, transitionsAlwaysOn);
 
-	const screenInterpolatorProps = useSharedValue(
-		createInitialBaseInterpolatorProps(dimensions, insets),
+	const initialInterpolatorProps = useMemo(
+		() =>
+			createInitialInterpolatorProps({
+				dimensions,
+				insets,
+				currentDescriptor: currDescriptor,
+				nextDescriptor,
+				prevDescriptor,
+			}),
+		[dimensions, insets, currDescriptor, nextDescriptor, prevDescriptor],
 	);
+
+	const screenInterpolatorProps = useSharedValue(initialInterpolatorProps);
 	const selectedInterpolatorOptions =
 		useSharedValue<SelectedInterpolatorOptions>({
 			owner: "current",
 		});
 
 	const propsRevisionState = useSharedValue({ value: 0 });
+
 	const screenInterpolatorPropsRevision = useDerivedValue<number>(() => {
 		"worklet";
 
 		screenInterpolatorProps.modify((frame) => {
 			"worklet";
 			const interpolatorOptions = selectedInterpolatorOptions.get();
-			const shouldApplyOptionsToCurrent =
-				interpolatorOptions.owner === "current";
-			const shouldApplyOptionsToNext =
-				interpolatorOptions.owner === "next" &&
-				!!nextAnimation &&
-				nextHasTransitions;
-			const previousCurrentProgress = currentAnimation?.visualProgress.get();
-			const previousNextProgress =
-				nextAnimation && nextHasTransitions
-					? nextAnimation.visualProgress.get()
-					: undefined;
-
-			frame.previous = prevAnimation
-				? hydrateTransitionState(prevAnimation, dimensions)
-				: undefined;
-
-			frame.current = currentAnimation
-				? hydrateTransitionState(
-						currentAnimation,
-						dimensions,
-						shouldApplyOptionsToCurrent
-							? interpolatorOptions.options
-							: undefined,
-					)
-				: DEFAULT_SCREEN_TRANSITION_STATE;
-
-			frame.next =
-				nextAnimation && nextHasTransitions
-					? hydrateTransitionState(
-							nextAnimation,
-							dimensions,
-							shouldApplyOptionsToNext
-								? interpolatorOptions.options
-								: undefined,
-						)
-					: undefined;
-
-			frame.layouts = frame.current.layouts;
-			frame.insets = insets;
-
-			updateDerivations(frame);
-
-			frame.stackProgress = resolveStackProgress(
-				currentAnimation?.stackProgress,
-				frame.progress,
-				frame.current.progress,
-				previousCurrentProgress,
-				frame.next?.progress,
-				previousNextProgress,
-			);
-			frame.logicallySettled = frame.active.settled;
-
-			return frame;
+			return hydrateInterpolatorFrame({
+				frame,
+				dimensions,
+				insets,
+				currentAnimation,
+				nextAnimation,
+				prevAnimation,
+				nextHasTransitions,
+				interpolatorOptions,
+			});
 		}, false);
 
 		// Critical reactive dependency for `screenInterpolatorProps`.

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

@@ -5,7 +5,7 @@ import { ScreenAnimationProvider } from "./animation";
 import { type BaseDescriptor, DescriptorsProvider } from "./descriptors";
 import { ScreenGestureProvider } from "./gestures";
 import { ScreenOptionsProvider } from "./options";
-import { ScreenStylesProvider } from "./styles";
+import { ScreenSlotProvider } from "./styles";
 
 type Props<TDescriptor extends BaseDescriptor> = {
 	previous?: TDescriptor;
@@ -26,9 +26,9 @@ export function ScreenComposer<TDescriptor extends BaseDescriptor>({
 				<ScreenOptionsProvider>
 					<ScreenGestureProvider>
 						<ScreenAnimationProvider>
-							<ScreenStylesProvider>
+							<ScreenSlotProvider>
 								<ScreenContainer>{children}</ScreenContainer>
-							</ScreenStylesProvider>
+							</ScreenSlotProvider>
 						</ScreenAnimationProvider>
 					</ScreenGestureProvider>
 				</ScreenOptionsProvider>

package/src/shared/providers/screen/styles/helpers/compose-slot-style.ts

@@ -0,0 +1,129 @@
+import type { StyleProps, TransformArrayItem } from "react-native-reanimated";
+import { NO_STYLES } from "../../../../constants";
+
+type SharedValueLike = {
+	_isReanimatedSharedValue: true;
+	get?: () => unknown;
+	value?: unknown;
+};
+
+const isSharedValueLike = (value: unknown): value is SharedValueLike => {
+	"worklet";
+	return (
+		(value as Partial<SharedValueLike> | null)?._isReanimatedSharedValue ===
+		true
+	);
+};
+
+const resolveTransformValue = <T>(value: T): T | unknown => {
+	"worklet";
+	if (isSharedValueLike(value)) {
+		return value.value;
+	}
+
+	if (Array.isArray(value)) {
+		const resolved = [];
+		for (let index = 0; index < value.length; index++) {
+			const item = value[index];
+			resolved.push(isSharedValueLike(item) ? item.value : item);
+		}
+		return resolved;
+	}
+
+	return value;
+};
+
+const resolveTransformItem = (
+	value: TransformArrayItem,
+): TransformArrayItem => {
+	"worklet";
+	if (typeof value === "object" && value !== null) {
+		const resolved: Record<string, unknown> = {};
+		const source = value as Record<string, unknown>;
+		for (const key in source) {
+			resolved[key] = resolveTransformValue(source[key]);
+		}
+		return resolved as TransformArrayItem;
+	}
+
+	return value;
+};
+
+const resolveLocalTransform = (
+	transform: TransformArrayItem[],
+): TransformArrayItem[] => {
+	"worklet";
+	const resolved: TransformArrayItem[] = [];
+
+	for (let index = 0; index < transform.length; index++) {
+		resolved.push(resolveTransformItem(transform[index]));
+	}
+
+	return resolved;
+};
+
+const flattenStyleObject = (
+	style: unknown,
+): Record<string, unknown> | undefined => {
+	if (style === null || style === undefined || typeof style !== "object") {
+		return undefined;
+	}
+
+	if (!Array.isArray(style)) {
+		return style as Record<string, unknown>;
+	}
+
+	let flattened: Record<string, unknown> | undefined;
+	for (let index = 0; index < style.length; index++) {
+		const child = flattenStyleObject(style[index]);
+
+		if (!child) {
+			continue;
+		}
+
+		flattened = flattened ?? {};
+		Object.assign(flattened, child);
+	}
+
+	return flattened;
+};
+
+export const getLocalTransformForSlotComposition = (
+	style: unknown,
+): TransformArrayItem[] | undefined => {
+	const flattened = flattenStyleObject(style);
+	const transform = flattened?.transform;
+
+	return Array.isArray(transform)
+		? (transform as TransformArrayItem[])
+		: undefined;
+};
+
+export const composeSlotStyleWithLocalTransform = (
+	slotStyle: StyleProps | undefined,
+	localTransform: TransformArrayItem[] | undefined,
+	boundsLocalTransform?: TransformArrayItem[],
+): StyleProps => {
+	"worklet";
+	const resolvedSlotStyle = (slotStyle ?? NO_STYLES) as StyleProps;
+	// The measured bounds snapshot supersedes the live local transform so bounds
+	// geometry and payload scale are composed from the same measurement frame.
+	const transformToCompose = boundsLocalTransform ?? localTransform;
+
+	if (!transformToCompose?.length) {
+		return resolvedSlotStyle;
+	}
+
+	const slotTransform = resolvedSlotStyle.transform;
+	if (!Array.isArray(slotTransform)) {
+		return resolvedSlotStyle;
+	}
+
+	return {
+		...resolvedSlotStyle,
+		transform: [
+			...(slotTransform as TransformArrayItem[]),
+			...resolveLocalTransform(transformToCompose),
+		],
+	};
+};

package/src/shared/providers/screen/styles/helpers/normalize-slots.ts

@@ -2,6 +2,10 @@ import type {
 	NormalizedTransitionInterpolatedStyle,
 	NormalizedTransitionSlotStyle,
 } from "../../../../types/animation.types";
+import {
+	getBoundsLocalTransform,
+	stripBoundsLocalTransform,
+} from "../../../../utils/bounds/helpers/styles/local-transform";
 
 const isExplicitTransitionSlot = (value: unknown) => {
 	"worklet";
@@ -12,7 +16,14 @@ const isExplicitTransitionSlot = (value: unknown) => {
 	);
 };
 
-const isAlreadyNormalizedStyleMap = (raw: Record<string, any>) => {
+const hasBoundsLocalTransformMarker = (style: unknown) => {
+	"worklet";
+	return !!getBoundsLocalTransform(style as any)?.length;
+};
+
+const isAlreadyNormalizedStyleMapWithoutBoundsMetadata = (
+	raw: Record<string, any>,
+) => {
 	"worklet";
 
 	for (const key in raw) {
@@ -25,6 +36,14 @@ const isAlreadyNormalizedStyleMap = (raw: Record<string, any>) => {
 		if (!isExplicitTransitionSlot(value)) {
 			return false;
 		}
+
+		if (
+			hasBoundsLocalTransformMarker(
+				(value as NormalizedTransitionSlotStyle).style,
+			)
+		) {
+			return false;
+		}
 	}
 
 	return true;
@@ -42,10 +61,7 @@ export function normalizeSlots(
 ): NormalizedTransitionInterpolatedStyle {
 	"worklet";
 
-	// Most modern interpolators already return the canonical `{ style, props }`
-	// slot shape. In that common case, we can forward the raw object directly and
-	// avoid building a second map just to copy the same slot references over.
-	if (isAlreadyNormalizedStyleMap(raw)) {
+	if (isAlreadyNormalizedStyleMapWithoutBoundsMetadata(raw)) {
 		return raw as NormalizedTransitionInterpolatedStyle;
 	}
 
@@ -62,11 +78,32 @@ export function normalizeSlots(
 		}
 
 		if (isExplicitTransitionSlot(value)) {
-			// Proper TransitionSlotStyle — pass through
-			normalized[key] = value as NormalizedTransitionSlotStyle;
+			const explicitSlot = value as NormalizedTransitionSlotStyle;
+			const boundsLocalTransform = getBoundsLocalTransform(explicitSlot.style);
+
+			if (!boundsLocalTransform?.length) {
+				normalized[key] = explicitSlot;
+				continue;
+			}
+
+			normalized[key] = {
+				style: explicitSlot.style
+					? stripBoundsLocalTransform(explicitSlot.style)
+					: undefined,
+				props: explicitSlot.props,
+				boundsLocalTransform,
+			};
 		} else {
+			const boundsLocalTransform = getBoundsLocalTransform(value);
+			const style =
+				boundsLocalTransform?.length && value
+					? stripBoundsLocalTransform(value)
+					: value;
+
 			// Shorthand: plain StyleProps — wrap it
-			normalized[key] = { style: value };
+			normalized[key] = boundsLocalTransform?.length
+				? { style, boundsLocalTransform }
+				: { style };
 		}
 	}
 

package/src/shared/providers/screen/styles/helpers/opening-phase.ts

@@ -0,0 +1,25 @@
+/**
+ * The "pre-start" window of an opening transition: the screen has committed to
+ * opening (`entering`) but `transitionProgress` has not yet moved past 0, so no
+ * transformed frame has been produced yet.
+ *
+ * This window is a quarantine, and two source-level guards key off it:
+ * - the visibility gate keeps the entering screen hidden (it must not be SEEN), and
+ * - interpolator ownership stays on "current" so the entering screen does not
+ *   DRIVE other screens' styles until its transition is actually live.
+ *
+ * Both must agree on when the open transition has started, so the threshold
+ * lives here in one place rather than being re-derived at each site.
+ */
+export const hasOpenTransitionStarted = (transitionProgress: number) => {
+	"worklet";
+	return transitionProgress > 0;
+};
+
+export const isOpeningBeforeStart = (
+	entering: number,
+	transitionProgress: number,
+) => {
+	"worklet";
+	return !!entering && !hasOpenTransitionStarted(transitionProgress);
+};