react-native-screen-transitions 3.3.0 → 3.4.0-alpha.0

package/src/shared/stores/bounds/internals/resolver.ts

@@ -0,0 +1,213 @@
+import { matchesScreenKey } from "../helpers/matching";
+import type {
+	ResolvedTransitionPair,
+	ResolveTransitionContext,
+	ScreenKey,
+	TagID,
+	TagLink,
+	TagState,
+} from "../types";
+import { getSnapshot } from "./registry";
+import { debugResolverLog, registry } from "./state";
+
+const findLatestLink = (
+	tagState: TagState,
+	predicate: (link: TagLink) => boolean,
+): TagLink | null => {
+	"worklet";
+	const stack = tagState.linkStack;
+	for (let i = stack.length - 1; i >= 0; i--) {
+		const link = stack[i];
+		if (predicate(link)) {
+			return link;
+		}
+	}
+	return null;
+};
+
+function findCompletedLinkByDestination(
+	tagState: TagState,
+	screenKey?: ScreenKey,
+): TagLink | null {
+	"worklet";
+	if (!screenKey) return null;
+
+	return findLatestLink(
+		tagState,
+		(link) =>
+			!!link.destination && matchesScreenKey(link.destination, screenKey),
+	);
+}
+
+function findCompletedLinkBySource(
+	tagState: TagState,
+	screenKey?: ScreenKey,
+): TagLink | null {
+	"worklet";
+	if (!screenKey) return null;
+
+	return findLatestLink(
+		tagState,
+		(link) => !!link.destination && matchesScreenKey(link.source, screenKey),
+	);
+}
+
+function findPendingLinkBySource(
+	tagState: TagState,
+	screenKey?: ScreenKey,
+): TagLink | null {
+	"worklet";
+	if (!screenKey) return null;
+
+	return findLatestLink(
+		tagState,
+		(link) =>
+			link.destination === null && matchesScreenKey(link.source, screenKey),
+	);
+}
+
+function getSnapshotBoundsByPriority(
+	tag: TagID,
+	keys: (ScreenKey | undefined)[],
+): { bounds: any; screenKey: ScreenKey } | null {
+	"worklet";
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		if (!key) continue;
+		const snapshot = getSnapshot(tag, key);
+		if (!snapshot) continue;
+		return {
+			bounds: snapshot.bounds,
+			screenKey: key,
+		};
+	}
+
+	return null;
+}
+
+function resolveTransitionPair(
+	tag: TagID,
+	context: ResolveTransitionContext,
+): ResolvedTransitionPair {
+	"worklet";
+	const tagState = registry.value[tag];
+	const stack = tagState?.linkStack;
+
+	let matchedLink: TagLink | null = null;
+	let usedPending = false;
+
+	if (tagState && stack && stack.length > 0) {
+		if (context.entering) {
+			matchedLink = findCompletedLinkByDestination(
+				tagState,
+				context.currentScreenKey,
+			);
+
+			if (!matchedLink) {
+				matchedLink = findPendingLinkBySource(
+					tagState,
+					context.previousScreenKey,
+				);
+				usedPending = !!matchedLink;
+			}
+
+			if (!matchedLink) {
+				matchedLink = findCompletedLinkBySource(
+					tagState,
+					context.previousScreenKey,
+				);
+			}
+
+			if (!matchedLink) {
+				matchedLink = findCompletedLinkByDestination(
+					tagState,
+					context.nextScreenKey,
+				);
+			}
+		} else {
+			matchedLink = findCompletedLinkBySource(
+				tagState,
+				context.currentScreenKey,
+			);
+
+			if (!matchedLink) {
+				matchedLink = findCompletedLinkByDestination(
+					tagState,
+					context.nextScreenKey,
+				);
+			}
+
+			if (!matchedLink) {
+				matchedLink = findPendingLinkBySource(
+					tagState,
+					context.currentScreenKey,
+				);
+				usedPending = !!matchedLink;
+			}
+		}
+	}
+
+	let sourceBounds = matchedLink?.source?.bounds ?? null;
+	let destinationBounds = matchedLink?.destination?.bounds ?? null;
+	let sourceScreenKey = matchedLink?.source?.screenKey ?? null;
+	let destinationScreenKey = matchedLink?.destination?.screenKey ?? null;
+	let usedSnapshotSource = false;
+	let usedSnapshotDestination = false;
+
+	const sourceFallbackKeys = context.entering
+		? [
+				context.previousScreenKey,
+				context.currentScreenKey,
+				context.nextScreenKey,
+			]
+		: [
+				context.currentScreenKey,
+				context.previousScreenKey,
+				context.nextScreenKey,
+			];
+
+	const destinationFallbackKeys = context.entering
+		? [context.currentScreenKey, context.nextScreenKey]
+		: [context.nextScreenKey, context.currentScreenKey];
+
+	if (!sourceBounds) {
+		const sourceSnapshot = getSnapshotBoundsByPriority(tag, sourceFallbackKeys);
+		if (sourceSnapshot) {
+			sourceBounds = sourceSnapshot.bounds;
+			sourceScreenKey = sourceSnapshot.screenKey;
+			usedSnapshotSource = true;
+		}
+	}
+
+	if (!destinationBounds) {
+		const destinationSnapshot = getSnapshotBoundsByPriority(
+			tag,
+			destinationFallbackKeys,
+		);
+		if (destinationSnapshot) {
+			destinationBounds = destinationSnapshot.bounds;
+			destinationScreenKey = destinationSnapshot.screenKey;
+			usedSnapshotDestination = true;
+		}
+	}
+
+	if (!sourceBounds || !destinationBounds) {
+		debugResolverLog(
+			`unresolved tag=${tag} entering=${context.entering ? 1 : 0} source=${
+				sourceBounds ? 1 : 0
+			} destination=${destinationBounds ? 1 : 0} pending=${usedPending ? 1 : 0}`,
+		);
+	}
+
+	return {
+		sourceBounds,
+		destinationBounds,
+		sourceScreenKey,
+		destinationScreenKey,
+		usedPending,
+		usedSnapshotSource,
+		usedSnapshotDestination,
+	};
+}
+
+export { resolveTransitionPair };

package/src/shared/stores/bounds/internals/state.ts

@@ -0,0 +1,115 @@
+import { makeMutable } from "react-native-reanimated";
+import type { GroupState, PresenceState, TagID, TagState } from "../types";
+
+export const createEmptyTagState = (): TagState => {
+	"worklet";
+	return {
+		snapshots: {},
+		linkStack: [],
+	};
+};
+
+export type RegistryState = Record<TagID, TagState>;
+export type GroupsState = Record<string, GroupState>;
+
+export const registry = makeMutable<RegistryState>({});
+export const presence = makeMutable<PresenceState>({});
+export const groups = makeMutable<GroupsState>({});
+
+const RESOLVER_LOG_PREFIX = "[bounds:resolver]";
+const ENABLE_RESOLVER_DEBUG_LOGS = false;
+const CLEAR_LOG_PREFIX = "[bounds:clear]";
+const ENABLE_CLEAR_DEBUG_LOGS = false;
+const SIZE_LOG_PREFIX = "[bounds:size]";
+const ENABLE_SIZE_DEBUG_LOGS = false;
+
+type BoundStoreSize = {
+	tags: number;
+	snapshots: number;
+	links: number;
+	pendingLinks: number;
+	completedLinks: number;
+	presenceTags: number;
+	presenceEntries: number;
+	presenceCount: number;
+	groups: number;
+};
+
+export function debugResolverLog(message: string) {
+	"worklet";
+	if (!ENABLE_RESOLVER_DEBUG_LOGS) return;
+	console.warn(`${RESOLVER_LOG_PREFIX} ${message}`);
+}
+
+export function debugClearLog(message: string) {
+	"worklet";
+	if (!ENABLE_CLEAR_DEBUG_LOGS) return;
+	console.warn(`${CLEAR_LOG_PREFIX} ${message}`);
+}
+
+const collectBoundStoreSize = (): BoundStoreSize => {
+	"worklet";
+	const currentRegistry = registry.value;
+	const currentPresence = presence.value;
+	const currentGroups = groups.value;
+
+	let tags = 0;
+	let snapshots = 0;
+	let links = 0;
+	let pendingLinks = 0;
+	let completedLinks = 0;
+
+	for (const tag in currentRegistry) {
+		tags++;
+		const tagState = currentRegistry[tag];
+		for (const _snapshotKey in tagState.snapshots) {
+			snapshots++;
+		}
+		for (let i = 0; i < tagState.linkStack.length; i++) {
+			links++;
+			if (tagState.linkStack[i].destination === null) {
+				pendingLinks++;
+			} else {
+				completedLinks++;
+			}
+		}
+	}
+
+	let presenceTags = 0;
+	let presenceEntries = 0;
+	let presenceCount = 0;
+	for (const tag in currentPresence) {
+		presenceTags++;
+		const entries = currentPresence[tag];
+		for (const screenKey in entries) {
+			presenceEntries++;
+			presenceCount += entries[screenKey].count ?? 0;
+		}
+	}
+
+	let groupsCount = 0;
+	for (const _group in currentGroups) {
+		groupsCount++;
+	}
+
+	return {
+		tags,
+		snapshots,
+		links,
+		pendingLinks,
+		completedLinks,
+		presenceTags,
+		presenceEntries,
+		presenceCount,
+		groups: groupsCount,
+	};
+};
+
+export function debugStoreSizeLog(action: string) {
+	"worklet";
+	if (!ENABLE_SIZE_DEBUG_LOGS) return;
+	const size = collectBoundStoreSize();
+	console.warn(
+		`${SIZE_LOG_PREFIX} ${action} tags=${size.tags} snapshots=${size.snapshots} links=${size.links} pending=${size.pendingLinks} completed=${size.completedLinks} presenceTags=${size.presenceTags} presenceEntries=${size.presenceEntries} presenceCount=${size.presenceCount} groups=${size.groups}`,
+	);
+}

package/src/shared/stores/bounds/types.ts

@@ -0,0 +1,76 @@
+import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
+import type { BoundsMethod } from "../../types/bounds.types";
+import type {
+	BoundsAnchor,
+	BoundsScaleMode,
+} from "../../utils/bounds/types/options";
+
+export type TagID = string;
+export type ScreenKey = string;
+export type NavigatorKey = string;
+
+export type BoundaryConfig = {
+	anchor?: BoundsAnchor;
+	scaleMode?: BoundsScaleMode;
+	target?: "bound" | "fullscreen" | MeasuredDimensions;
+	method?: BoundsMethod;
+};
+
+export type Snapshot = {
+	bounds: MeasuredDimensions;
+	styles: StyleProps;
+};
+
+export type ScreenIdentifier = {
+	screenKey: ScreenKey;
+	ancestorKeys?: ScreenKey[];
+	navigatorKey?: NavigatorKey;
+	ancestorNavigatorKeys?: NavigatorKey[];
+};
+
+export type TagLink = {
+	source: ScreenIdentifier & Snapshot;
+	destination: (ScreenIdentifier & Snapshot) | null;
+};
+
+export type ResolveTransitionContext = {
+	currentScreenKey?: ScreenKey;
+	previousScreenKey?: ScreenKey;
+	nextScreenKey?: ScreenKey;
+	entering: boolean;
+};
+
+export type ResolvedTransitionPair = {
+	sourceBounds: MeasuredDimensions | null;
+	destinationBounds: MeasuredDimensions | null;
+	sourceScreenKey: ScreenKey | null;
+	destinationScreenKey: ScreenKey | null;
+	usedPending: boolean;
+	usedSnapshotSource: boolean;
+	usedSnapshotDestination: boolean;
+};
+
+export type SnapshotEntry = Snapshot & {
+	ancestorKeys?: ScreenKey[];
+	navigatorKey?: NavigatorKey;
+	ancestorNavigatorKeys?: NavigatorKey[];
+};
+
+export type TagState = {
+	snapshots: Record<ScreenKey, SnapshotEntry>;
+	linkStack: TagLink[];
+};
+
+export type PresenceEntry = {
+	count: number;
+	ancestorKeys?: ScreenKey[];
+	navigatorKey?: NavigatorKey;
+	ancestorNavigatorKeys?: NavigatorKey[];
+	boundaryConfig?: BoundaryConfig;
+};
+
+export type PresenceState = Record<TagID, Record<ScreenKey, PresenceEntry>>;
+
+export type GroupState = {
+	activeId: string;
+};

package/src/shared/stores/gesture.store.ts

@@ -6,69 +6,94 @@ import {
 import type { GestureDirection } from "../types/gesture.types";
 import type { ScreenKey } from "../types/screen.types";
 
-type GestureKey =
-	| "x"
-	| "y"
-	| "normalizedX"
-	| "normalizedY"
-	| "isDismissing"
-	| "isDragging";
-
 export type GestureStoreMap = {
 	x: SharedValue<number>;
 	y: SharedValue<number>;
+	normX: SharedValue<number>;
+	normY: SharedValue<number>;
+	dismissing: SharedValue<number>;
+	dragging: SharedValue<number>;
+	direction: SharedValue<Omit<GestureDirection, "bidirectional"> | null>;
+
+	/** @deprecated Use `normX` instead. */
 	normalizedX: SharedValue<number>;
+	/** @deprecated Use `normY` instead. */
 	normalizedY: SharedValue<number>;
+	/** @deprecated Use `dismissing` instead. */
 	isDismissing: SharedValue<number>;
+	/** @deprecated Use `dragging` instead. */
 	isDragging: SharedValue<number>;
-	direction: SharedValue<Omit<GestureDirection, "bidirectional"> | null>;
 };
 
 const store: Record<ScreenKey, GestureStoreMap> = {};
+let neutralGestures: GestureStoreMap | undefined;
+
+function createGestureBag(): GestureStoreMap {
+	const normX = makeMutable(0);
+	const normY = makeMutable(0);
+	const dismissing = makeMutable(0);
+	const dragging = makeMutable(0);
+
+	return {
+		x: makeMutable(0),
+		y: makeMutable(0),
+		normX,
+		normY,
+		dismissing,
+		dragging,
+		direction: makeMutable<Omit<GestureDirection, "bidirectional"> | null>(
+			null,
+		),
+
+		// Deprecated aliases (same underlying SharedValue)
+		normalizedX: normX,
+		normalizedY: normY,
+		isDismissing: dismissing,
+		isDragging: dragging,
+	};
+}
 
 function ensure(routeKey: ScreenKey): GestureStoreMap {
 	let bag = store[routeKey];
 	if (!bag) {
-		bag = {
-			x: makeMutable(0),
-			y: makeMutable(0),
-			normalizedX: makeMutable(0),
-			normalizedY: makeMutable(0),
-			isDismissing: makeMutable(0),
-			isDragging: makeMutable(0),
-			direction: makeMutable<Omit<GestureDirection, "bidirectional"> | null>(
-				null,
-			),
-		};
+		bag = createGestureBag();
 		store[routeKey] = bag;
 	}
 	return bag;
 }
 
-function getGesture(routeKey: ScreenKey, gestureKey: GestureKey) {
-	return ensure(routeKey)[gestureKey];
+function peekRouteGestures(routeKey: ScreenKey): GestureStoreMap | undefined {
+	return store[routeKey];
 }
 
 function getRouteGestures(routeKey: ScreenKey) {
 	return ensure(routeKey);
 }
 
+function getNeutralGestures(): GestureStoreMap {
+	if (!neutralGestures) {
+		neutralGestures = createGestureBag();
+	}
+	return neutralGestures;
+}
+
 function clear(routeKey: ScreenKey) {
 	const bag = store[routeKey];
 	if (bag) {
 		cancelAnimation(bag.x);
 		cancelAnimation(bag.y);
-		cancelAnimation(bag.normalizedX);
-		cancelAnimation(bag.normalizedY);
-		cancelAnimation(bag.isDismissing);
-		cancelAnimation(bag.isDragging);
+		cancelAnimation(bag.normX);
+		cancelAnimation(bag.normY);
+		cancelAnimation(bag.dismissing);
+		cancelAnimation(bag.dragging);
 		cancelAnimation(bag.direction);
 	}
 	delete store[routeKey];
 }
 
 export const GestureStore = {
-	getGesture,
+	peekRouteGestures,
 	getRouteGestures,
+	getNeutralGestures,
 	clear,
 };

package/src/shared/types/animation.types.ts

@@ -1,3 +1,4 @@
+import type { TextStyle, ViewStyle } from "react-native";
 import type {
 	StyleProps,
 	WithSpringConfig,
@@ -56,6 +57,13 @@ export type ScreenTransitionState = {
 	 */
 	animating: number;
 
+	/**
+	 * Whether this screen is fully settled (not transitioning and not dismissing).
+	 * - `0`: Transition/gesture is active or dismissing
+	 * - `1`: Screen is fully settled/idle
+	 */
+	settled: number;
+
 	/**
 	 * Live gesture values for this screen.
 	 * Contains translation (x, y), normalized values (-1 to 1),
@@ -113,12 +121,6 @@ export interface ScreenInterpolationProps {
 	 */
 	insets: EdgeInsets;
 
-	/**
-	 * The ID of the currently active shared bound (e.g., 'a' when Transition.Pressable has sharedBoundTag='a').
-	 * @deprecated
-	 */
-	activeBoundId?: never;
-
 	/**
 	 * Whether the current screen is the focused (topmost) screen in the stack.
 	 */
@@ -153,7 +155,7 @@ export interface ScreenInterpolationProps {
 	snapIndex: number;
 
 	/**
-	 * Function that provides access to bounds builders for creating shared element transitions.
+	 * Function that provides access to bounds helpers for shared screen transitions.
 	 */
 	bounds: BoundsAccessor;
 
@@ -185,34 +187,94 @@ export type ScreenStyleInterpolator = (
 	props: ScreenInterpolationProps,
 ) => TransitionInterpolatedStyle;
 
-export type TransitionInterpolatedStyle = {
-	/**
-	 * Animated style for the main screen view. Styles are only applied when Transition.View is present.
-	 */
-	contentStyle?: StyleProps;
+/**
+ * Animated style properties with full autocomplete.
+ *
+ * Uses React Native's `ViewStyle & TextStyle` instead of Reanimated's `StyleProps`
+ * (which has `[key: string]: any`) so TypeScript can provide autocomplete and catch typos.
+ */
+export type AnimatedViewStyle = ViewStyle & TextStyle;
 
-	/**
-	 * Animated style for the semi-transparent backdrop layer behind screen content.
-	 *
-	 * @example
-	 * backdropStyle: {
-	 *   backgroundColor: "black",
-	 *   opacity: interpolate(progress, [0, 1], [0, 0.5]),
-	 * }
-	 */
-	backdropStyle?: StyleProps;
+/**
+ * Explicit slot format with separate `style` and `props` buckets.
+ *
+ * - `style` is applied via `useAnimatedStyle` (transform, opacity, backgroundColor, etc.)
+ * - `props` is applied via `useAnimatedProps` (component-specific props like BlurView intensity)
+ */
+export type TransitionSlotExplicit = {
+	/** Animated styles applied via useAnimatedStyle. */
+	style?: AnimatedViewStyle;
+	/** Animated props applied via useAnimatedProps (e.g., BlurView intensity, SquircleView cornerRadius). */
+	props?: Record<string, any>;
+};
 
-	/**
-	 * @deprecated Use `backdropStyle` instead. Will be removed in next major version.
-	 */
-	overlayStyle?: StyleProps;
+/**
+ * A slot in the interpolated style map.
+ *
+ * Can be written in two forms:
+ * - **Shorthand**: Write styles directly — `{ opacity: 0.5, transform: [...] }`
+ * - **Explicit**: Use `style` and/or `props` buckets — `{ style: { opacity: 0.5 }, props: { intensity: 80 } }`
+ */
+export type TransitionSlotStyle = AnimatedViewStyle | TransitionSlotExplicit;
 
-	/**
-	 * Define your own custom styles by using an id as the key: [id]: StyleProps
-	 */
-	[id: string]: StyleProps | undefined;
+/**
+ * Internal normalized slot format used after the backward-compat shim.
+ * Always uses the explicit `{ style, props }` shape (with Reanimated's full StyleProps).
+ */
+export type NormalizedTransitionSlotStyle = {
+	style?: StyleProps;
+	props?: Record<string, any>;
+};
+
+/**
+ * Normalized interpolated style map used internally after the backward-compat shim.
+ * All slots use the explicit `{ style, props }` shape.
+ */
+export type NormalizedTransitionInterpolatedStyle = {
+	/** Animated style and props for the main screen content view. */
+	content?: NormalizedTransitionSlotStyle;
+	/** Animated style and props for the backdrop layer between screens. */
+	backdrop?: NormalizedTransitionSlotStyle;
+	/** Animated style and props for the surface component layer within the screen. */
+	surface?: NormalizedTransitionSlotStyle;
+	/** Custom styles/props by id for Transition.View components. */
+	[id: string]: NormalizedTransitionSlotStyle | undefined;
+};
+
+/**
+ * Public new-format interpolator result with type-safe style autocomplete.
+ * Uses `TransitionSlotStyle` (backed by `AnimatedViewStyle`) for full style autocomplete.
+ */
+export type NewTransitionInterpolatedStyle = {
+	/** Animated style and props for the main screen content view. */
+	content?: TransitionSlotStyle;
+	/** Animated style and props for the backdrop layer between screens. */
+	backdrop?: TransitionSlotStyle;
+	/** Animated style and props for the surface component layer within the screen. */
+	surface?: TransitionSlotStyle;
+	/** Custom styles/props by id for Transition.View components. */
+	[id: string]: TransitionSlotStyle | undefined;
+};
+
+/**
+ * @deprecated Use the nested format instead: `{ content: { style }, backdrop: { style } }`.
+ * This flat format is auto-converted via a backward-compat shim.
+ */
+export type LegacyTransitionInterpolatedStyle = {
+	contentStyle?: AnimatedViewStyle;
+	backdropStyle?: AnimatedViewStyle;
+	overlayStyle?: AnimatedViewStyle;
+	[id: string]: AnimatedViewStyle | undefined;
 };
 
+/**
+ * The return type of `screenStyleInterpolator`.
+ * Accepts both the new nested format and the legacy flat format (auto-converted).
+ */
+export type TransitionInterpolatedStyle =
+	| NewTransitionInterpolatedStyle
+	| LegacyTransitionInterpolatedStyle;
+
 /**
  * A Reanimated animation configuration object.
  */