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

package/src/providers/orchestrator/helpers/use-stack-progress-inputs.ts

@@ -0,0 +1,143 @@
+import { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Platform } from "react-native";
+import { type SharedValue, useSharedValue } from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import { useOptionalBlankStackStore } from "../../../navigators/blank-stack/state/blank-stack.provider";
+import { useMotionStore } from "../../motion";
+import type { StackProgressEntry } from "./stack-progress";
+
+const NO_ROUTE_KEYS: readonly string[] = [];
+
+// A reader only uses its own route and the routes above it. Keep the selected
+// keys stable when the stack changes below that reader; progress stays live.
+export function createStackProgressRouteSelector(currentRouteKey: string) {
+	let previous: readonly string[] = [];
+	return (
+		store: { routeKeys: readonly string[] } | null,
+	): readonly string[] => {
+		const keys = store?.routeKeys ?? NO_ROUTE_KEYS;
+		const index = keys.lastIndexOf(currentRouteKey);
+		const length = index < 0 ? 0 : keys.length - index;
+		if (
+			previous.length === length &&
+			previous.every((key, offset) => key === keys[index + offset])
+		) {
+			return previous;
+		}
+		previous = index < 0 ? [] : keys.slice(index);
+		return previous;
+	};
+}
+
+// Reanimated mapper IDs are positive. These listeners only attach to our own
+// visualProgress values, and each mounted reader receives a distinct ID.
+let nextListenerId = -1;
+
+type ProgressInputs = {
+	entries: SharedValue<readonly StackProgressEntry[]>;
+	revision: SharedValue<number>;
+	epoch: SharedValue<number>;
+};
+
+export function registerStackProgressInputs(
+	inputs: ProgressInputs,
+	entries: readonly StackProgressEntry[],
+	listenerId: number,
+	epoch: number,
+) {
+	"worklet";
+	const currentEpoch = inputs.epoch.get();
+	if (Math.abs(currentEpoch) >= epoch) return;
+	if (currentEpoch > 0) {
+		for (const entry of inputs.entries.get()) {
+			entry.visualProgress.removeListener(listenerId);
+		}
+	}
+	inputs.entries.set(entries);
+	inputs.epoch.set(epoch);
+	const revision = inputs.revision;
+	for (const entry of entries) {
+		entry.visualProgress.addListener(listenerId, () => {
+			// SharedValue listeners run synchronously after the value changes.
+			// Invalidate the frame directly, without a cached sum or mapper hop.
+			revision.set((value) => value + 1);
+		});
+	}
+	revision.set((value) => value + 1);
+}
+
+export function unregisterStackProgressInputs(
+	inputs: ProgressInputs,
+	listenerId: number,
+	epoch: number,
+) {
+	"worklet";
+	const currentEpoch = inputs.epoch.get();
+	if (Math.abs(currentEpoch) > epoch) return;
+	if (currentEpoch > 0) {
+		for (const entry of inputs.entries.get()) {
+			entry.visualProgress.removeListener(listenerId);
+		}
+	}
+	// Tombstone even a setup that has not arrived yet. A stale job must not
+	// install listeners after its owner has disconnected.
+	inputs.epoch.set(-epoch);
+}
+
+export function useStackProgressInputs(currentRouteKey: string) {
+	const selectProgressRoutes = useMemo(
+		() => createStackProgressRouteSelector(currentRouteKey),
+		[currentRouteKey],
+	);
+
+	const routeKeys = useOptionalBlankStackStore(selectProgressRoutes);
+	const stackProgressValues = useMotionStore(
+		routeKeys,
+		(store) => store.state.visualProgress,
+	);
+
+	const entries = useMemo<readonly StackProgressEntry[]>(
+		() =>
+			routeKeys.flatMap((routeKey, index) => {
+				const visualProgress = stackProgressValues[index];
+				return visualProgress ? [{ routeKey, visualProgress }] : [];
+			}),
+		[routeKeys, stackProgressValues],
+	);
+
+	const liveEntries = useSharedValue(entries);
+	const revision = useSharedValue(0);
+	const epoch = useSharedValue(0);
+	const [listenerId] = useState(() => nextListenerId--);
+	const generation = useRef(0);
+
+	useLayoutEffect(() => {
+		const nextEpoch = ++generation.current;
+		const inputs = { entries: liveEntries, revision, epoch };
+		if (Platform.OS === "web") {
+			registerStackProgressInputs(inputs, entries, listenerId, nextEpoch);
+		} else {
+			scheduleOnUI(
+				registerStackProgressInputs,
+				inputs,
+				entries,
+				listenerId,
+				nextEpoch,
+			);
+		}
+		return () => {
+			if (Platform.OS === "web") {
+				unregisterStackProgressInputs(inputs, listenerId, nextEpoch);
+			} else {
+				scheduleOnUI(
+					unregisterStackProgressInputs,
+					inputs,
+					listenerId,
+					nextEpoch,
+				);
+			}
+		};
+	}, [entries, liveEntries, revision, epoch, listenerId]);
+
+	return { entries: liveEntries, revision };
+}

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

@@ -0,0 +1,76 @@
+import { useLayoutEffect, useMemo } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import { useOptionalBlankStackStore } from "../../../navigators/blank-stack/state/blank-stack.provider";
+import {
+	type ClaimedDirections,
+	NO_CLAIMS,
+} from "../../../types/ownership.types";
+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/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,
+		},
+	};
+});

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

@@ -0,0 +1,87 @@
+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 = {
+	clip: true,
+	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);
+};

package/src/providers/orchestrator/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/providers/orchestrator/styles/helpers/create-interpolator-scope.ts

@@ -0,0 +1,26 @@
+import type { ScreenInterpolationProps } from "../../../../types/animation.types";
+import { createBoundsAccessor } from "../../../../utils/bounds";
+import type { ScreenInterpolatorFrame } from "../../helpers/pipeline";
+import type { SelectedInterpolatorFrame } from "./select-interpolator-frame";
+
+export const createInterpolatorScope = ({
+	frame,
+	selectedFrame,
+}: {
+	frame: ScreenInterpolatorFrame;
+	selectedFrame: SelectedInterpolatorFrame;
+}): ScreenInterpolationProps => {
+	"worklet";
+
+	const selectedProps = {
+		...frame,
+		...selectedFrame,
+	};
+	return {
+		...selectedProps,
+		bounds: createBoundsAccessor(() => {
+			"worklet";
+			return selectedProps;
+		}),
+	};
+};

package/src/providers/orchestrator/styles/helpers/normalize-slots.ts

@@ -0,0 +1,111 @@
+import type {
+	NormalizedTransitionInterpolatedStyle,
+	NormalizedTransitionSlotStyle,
+} from "../../../../types/animation.types";
+import {
+	getBoundsLocalTransform,
+	stripBoundsLocalTransform,
+} from "../../../../utils/bounds/helpers/styles/local-transform";
+
+const isExplicitTransitionSlot = (value: unknown) => {
+	"worklet";
+	return (
+		typeof value === "object" &&
+		value != null &&
+		("style" in value || "props" in value)
+	);
+};
+
+const hasBoundsLocalTransformMarker = (style: unknown) => {
+	"worklet";
+	return !!getBoundsLocalTransform(style as any)?.length;
+};
+
+const isAlreadyNormalizedStyleMapWithoutBoundsMetadata = (
+	raw: Record<string, any>,
+) => {
+	"worklet";
+
+	for (const key in raw) {
+		const value = raw[key];
+
+		if (value === undefined) {
+			continue;
+		}
+
+		if (!isExplicitTransitionSlot(value)) {
+			return false;
+		}
+
+		if (
+			hasBoundsLocalTransformMarker(
+				(value as NormalizedTransitionSlotStyle).style,
+			)
+		) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+/**
+ * Normalizes an interpolator result into the canonical `{ style, props }` slot format.
+ *
+ * Handles three cases per key:
+ * 1. Proper `TransitionSlotStyle` values (has `style` or `props` key) — pass through
+ * 2. Style shorthand (plain StyleProps without wrapping) — auto-wrapped as `{ style: value }`
+ */
+export function normalizeSlots(
+	raw: Record<string, any>,
+): NormalizedTransitionInterpolatedStyle {
+	"worklet";
+
+	if (isAlreadyNormalizedStyleMapWithoutBoundsMetadata(raw)) {
+		return raw as NormalizedTransitionInterpolatedStyle;
+	}
+
+	const normalized: Record<string, NormalizedTransitionSlotStyle | undefined> =
+		{};
+
+	for (const key in raw) {
+		const value = raw[key];
+
+		// ── All other keys ──
+		if (value === undefined) {
+			normalized[key] = undefined;
+			continue;
+		}
+
+		if (isExplicitTransitionSlot(value)) {
+			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] = boundsLocalTransform?.length
+				? { style, boundsLocalTransform }
+				: { style };
+		}
+	}
+
+	return normalized as NormalizedTransitionInterpolatedStyle;
+}