react-native-screen-transitions 3.8.0-beta.1 → 3.9.0-alpha.0

package/src/shared/providers/screen/styles/helpers/resolve-slot-styles/are-resettable-states-equal.ts

@@ -0,0 +1,74 @@
+import type { ResettableStyleStatesBySlot } from "./types";
+
+const areRecordsEqual = (
+	left: Record<string, unknown> | undefined,
+	right: Record<string, unknown> | undefined,
+) => {
+	"worklet";
+	if (left === right) {
+		return true;
+	}
+
+	if (!left || !right) {
+		return false;
+	}
+
+	for (const key in left) {
+		if (left[key] !== right[key]) {
+			return false;
+		}
+	}
+
+	for (const key in right) {
+		if (!(key in left)) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+const areResettableStatesEqual = (
+	left: ResettableStyleStatesBySlot[string] | undefined,
+	right: ResettableStyleStatesBySlot[string] | undefined,
+) => {
+	"worklet";
+	if (left === right) {
+		return true;
+	}
+
+	if (!left || !right) {
+		return false;
+	}
+
+	return (
+		areRecordsEqual(left.styleKeys, right.styleKeys) &&
+		areRecordsEqual(left.styleResetValues, right.styleResetValues) &&
+		areRecordsEqual(left.propKeys, right.propKeys) &&
+		areRecordsEqual(left.propResetValues, right.propResetValues)
+	);
+};
+
+export const areResettableStatesBySlotEqual = (
+	left: ResettableStyleStatesBySlot,
+	right: ResettableStyleStatesBySlot,
+) => {
+	"worklet";
+	if (left === right) {
+		return true;
+	}
+
+	for (const slotId in left) {
+		if (!areResettableStatesEqual(left[slotId], right[slotId])) {
+			return false;
+		}
+	}
+
+	for (const slotId in right) {
+		if (!(slotId in left)) {
+			return false;
+		}
+	}
+
+	return true;
+};

package/src/shared/providers/screen/styles/helpers/resolve-slot-styles/index.ts

@@ -11,6 +11,7 @@ import type {
 	ResettableStyleStatesBySlot,
 } from "./types";
 
+export { areResettableStatesBySlotEqual } from "./are-resettable-states-equal";
 export type { LocalStyleLayers, ResettableStyleStatesBySlot } from "./types";
 
 type ResolveSlotStylesContext = {

package/src/shared/providers/screen/styles/hooks/use-maybe-block-visibility.tsx

@@ -88,5 +88,6 @@ export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 	return {
 		animatedStyle,
 		animatedProps,
+		shouldBlockVisibility,
 	};
 };

package/src/shared/providers/screen/styles/styles.provider.tsx

@@ -15,6 +15,7 @@ type Props = {
 
 type ScreenStylesContextValue = {
 	stylesMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
+	shouldBlockVisibility: SharedValue<boolean>;
 };
 
 export const {
@@ -28,17 +29,18 @@ export const {
 
 	const rawStylesMaps = useInterpolatedStylesMap();
 
+	const { animatedStyle, animatedProps, shouldBlockVisibility } =
+		useMaybeBlockVisibility(isFloatingOverlay);
+
 	const stylesMap = useResolvedStylesMap({
 		localStylesMaps: rawStylesMaps,
 		ancestorStylesMap: parentContext?.stylesMap,
 	});
 
-	const { animatedStyle, animatedProps } =
-		useMaybeBlockVisibility(isFloatingOverlay);
-
 	return {
 		value: {
 			stylesMap,
+			shouldBlockVisibility,
 		},
 		children: (
 			<FloatingOverlayLayer enabled={isFloatingOverlay}>

package/src/shared/stores/bounds/helpers/link-pairs.helpers.ts

@@ -35,15 +35,6 @@ export const getSourceScreenKeyFromPairKey = (
 	return pairKey.slice(0, separatorIndex);
 };
 
-export const getDestinationScreenKeyFromPairKey = (
-	pairKey: ScreenPairKey,
-): ScreenIdentifier["screenKey"] | "" => {
-	"worklet";
-	const separatorIndex = pairKey.indexOf(PAIR_SEPARATOR);
-	if (separatorIndex === -1) return "";
-	return pairKey.slice(separatorIndex + PAIR_SEPARATOR.length);
-};
-
 export const isScreenPairKeyForScreen = (
 	pairKey: ScreenPairKey,
 	screenKey: ScreenIdentifier["screenKey"],
@@ -75,7 +66,7 @@ export const createGroupTag = (group: GroupKey, linkKey: LinkKey): string => {
 	return `${group}:${linkKey}`;
 };
 
-export const ensurePairState = (
+const ensurePairState = (
 	state: LinkPairsState,
 	pairKey: ScreenPairKey,
 ): LinkPairState => {

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

@@ -13,12 +13,10 @@ import { resolveTransitionPair } from "./internals/resolver";
 import type { MeasuredEntry } from "./types";
 
 export type {
-	BoundaryConfig,
-	Entry,
-	EntryPatch,
+	BoundsLink,
+	BoundsLinkStatus,
 	MeasuredEntry,
 	ResolvedTransitionPair,
-	ResolveTransitionContext,
 } from "./types";
 
 export type Snapshot = MeasuredEntry;

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

@@ -1,5 +1,5 @@
 import { hasAnyKeys } from "../helpers/keys";
-import type { EntryPatch, ScreenEntry, ScreenKey, TagID } from "../types";
+import type { Entry, EntryPatch, ScreenKey, TagID } from "../types";
 import { type BoundaryEntriesState, boundaryRegistry } from "./state";
 
 const ensureBoundaryState = (state: BoundaryEntriesState, tag: TagID) => {
@@ -16,7 +16,7 @@ const ensureScreenEntry = (
 	state: BoundaryEntriesState,
 	tag: TagID,
 	screenKey: ScreenKey,
-): ScreenEntry => {
+): Entry => {
 	"worklet";
 	const tagState = ensureBoundaryState(state, tag);
 	if (!tagState.screens[screenKey]) {
@@ -28,7 +28,7 @@ const ensureScreenEntry = (
 	return tagState.screens[screenKey];
 };
 
-const applyEntryPatch = (entry: ScreenEntry, patch: EntryPatch) => {
+const applyEntryPatch = (entry: Entry, patch: EntryPatch) => {
 	"worklet";
 	if (patch.bounds !== undefined) {
 		entry.bounds = patch.bounds;
@@ -49,7 +49,7 @@ const applyEntryPatch = (entry: ScreenEntry, patch: EntryPatch) => {
 	}
 };
 
-function getEntry(tag: TagID, key: ScreenKey): ScreenEntry | null {
+function getEntry(tag: TagID, key: ScreenKey): Entry | null {
 	"worklet";
 	return boundaryRegistry.get()[tag]?.screens[key] ?? null;
 }

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

@@ -14,19 +14,26 @@ import {
 	removePairLink,
 } from "../helpers/link-pairs.helpers";
 import type {
+	BoundsPortalAttachTarget,
 	GroupKey,
 	LinkKey,
 	LinkPairsState,
 	ScreenKey,
 	ScreenPairKey,
+	SourceHostRef,
+	SourceTagLinkSide,
 	TagID,
 	TagLink,
 } from "../types";
 import { pairs } from "./state";
 
-const toLinkKey = (tag: TagID): LinkKey => {
+const syncLinkStatus = (link: TagLink) => {
 	"worklet";
-	return getLinkKeyFromTag(tag);
+	link.status = link.source
+		? link.destination
+			? "complete"
+			: "destination-incomplete"
+		: "source-incomplete";
 };
 
 const createLinkSide = (
@@ -78,14 +85,23 @@ const writeDestination = (
 	group?: GroupKey,
 ) => {
 	"worklet";
-	const link = getPairLink(state, pairKey, linkKey);
-	if (!link) return;
+	const existingLink = getPairLink(state, pairKey, linkKey);
 
 	const destination = createLinkSide(screenKey, bounds, styles);
+	const link =
+		existingLink ??
+		({
+			group,
+			status: "source-incomplete",
+			source: null,
+			destination,
+			initialDestination: destination,
+		} satisfies TagLink);
 
 	link.group = group ?? link.group;
 	link.destination = destination;
 	link.initialDestination ??= destination;
+	syncLinkStatus(link);
 
 	writePairLink(state, pairKey, linkKey, link);
 
@@ -136,20 +152,31 @@ function setSource(
 	bounds: MeasuredDimensions,
 	styles: StyleProps = {},
 	group?: GroupKey,
+	portalAttachTarget?: BoundsPortalAttachTarget,
+	sourceHost?: SourceHostRef,
 ) {
 	"worklet";
 	pairs.modify(<T extends LinkPairsState>(state: T): T => {
 		"worklet";
-		const linkKey = toLinkKey(tag);
-		const source = createLinkSide(screenKey, bounds, styles);
+		const linkKey = getLinkKeyFromTag(tag);
 
 		const pairLinks = ensurePairLinks(state, pairKey);
 
 		const existingLink = pairLinks[linkKey];
+
+		// Refresh paths may re-measure the source without portal context;
+		// keep the previously recorded host in that case.
+		const source: SourceTagLinkSide = {
+			...createLinkSide(screenKey, bounds, styles),
+			portalAttachTarget:
+				portalAttachTarget ?? existingLink?.source?.portalAttachTarget,
+			sourceHost: sourceHost ?? existingLink?.source?.sourceHost,
+		};
 		const link =
 			existingLink ??
 			({
 				group,
+				status: "destination-incomplete",
 				source,
 				destination: null,
 				initialSource: source,
@@ -158,6 +185,7 @@ function setSource(
 		link.group = group ?? link.group;
 		link.source = source;
 		link.initialSource ??= source;
+		syncLinkStatus(link);
 
 		pairLinks[linkKey] = link;
 
@@ -181,7 +209,7 @@ function setDestination(
 	"worklet";
 	pairs.modify(<T extends LinkPairsState>(state: T): T => {
 		"worklet";
-		const linkKey = toLinkKey(tag);
+		const linkKey = getLinkKeyFromTag(tag);
 		promotePendingSource(state, pairKey, linkKey);
 		writeDestination(state, pairKey, linkKey, screenKey, bounds, styles, group);
 
@@ -193,7 +221,7 @@ function setActiveGroupId(pairKey: ScreenPairKey, group: GroupKey, tag: TagID) {
 	"worklet";
 	pairs.modify(<T extends LinkPairsState>(state: T): T => {
 		"worklet";
-		writeGroup(state, pairKey, group, toLinkKey(tag));
+		writeGroup(state, pairKey, group, getLinkKeyFromTag(tag));
 		return state;
 	});
 }
@@ -208,12 +236,14 @@ function getActiveGroupId(
 
 function getLink(pairKey: ScreenPairKey, tag: TagID): TagLink | null {
 	"worklet";
-	return getPairLink(pairs.get(), pairKey, toLinkKey(tag));
+	return getPairLink(pairs.get(), pairKey, getLinkKeyFromTag(tag));
 }
 
-const isCompletedLink = (link: TagLink | null): link is TagLink => {
+const hasSourceLink = (
+	link: TagLink | null,
+): link is TagLink & { source: NonNullable<TagLink["source"]> } => {
 	"worklet";
-	return !!link?.destination;
+	return !!link?.source;
 };
 
 const getPendingSourceLink = (
@@ -236,7 +266,7 @@ function getResolvedLink(
 ): { tag: TagID; link: TagLink | null } {
 	"worklet";
 	const state = pairs.get();
-	const linkKey = toLinkKey(tag);
+	const linkKey = getLinkKeyFromTag(tag);
 	const group = getGroupKeyFromTag(tag);
 	const requestedLink = getPairLink(state, pairKey, linkKey);
 
@@ -251,8 +281,9 @@ function getResolvedLink(
 	const link = requestedLink ?? fallbackPendingLink;
 
 	// Group active ids can update before the new member has a full source/destination
-	// link, so unresolved grouped links fall back to the initial id's measurements.
-	if (!group || isCompletedLink(link)) {
+	// link. As soon as the requested member has source bounds, prefer it; only
+	// fall back while the requested member has no source yet.
+	if (!group || hasSourceLink(link)) {
 		return {
 			tag,
 			link,
@@ -261,8 +292,11 @@ function getResolvedLink(
 
 	const initialId = state[pairKey]?.groups?.[group]?.initialId;
 	if (initialId) {
-		const initialLink = getPairLink(state, pairKey, initialId);
-		if (isCompletedLink(initialLink)) {
+		const initialLink =
+			getPairLink(state, pairKey, initialId) ??
+			getPendingSourceLink(state, pairKey, initialId);
+
+		if (hasSourceLink(initialLink)) {
 			return {
 				tag: createGroupTag(group, initialId),
 				link: initialLink,
@@ -281,7 +315,7 @@ function getSource(
 	tag: TagID,
 ): TagLink["source"] | null {
 	"worklet";
-	return getPairSource(pairs.get(), pairKey, toLinkKey(tag));
+	return getPairSource(pairs.get(), pairKey, getLinkKeyFromTag(tag));
 }
 
 function getDestination(
@@ -289,7 +323,7 @@ function getDestination(
 	tag: TagID,
 ): TagLink["destination"] | null {
 	"worklet";
-	return getPairDestination(pairs.get(), pairKey, toLinkKey(tag));
+	return getPairDestination(pairs.get(), pairKey, getLinkKeyFromTag(tag));
 }
 
 export {

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

@@ -33,12 +33,14 @@ function resolveTransitionPair(
 	const matchedLink = pairKey ? getResolvedLink(pairKey, tag).link : null;
 
 	return {
-		sourceBounds: matchedLink?.source.bounds ?? null,
+		sourceBounds: matchedLink?.source?.bounds ?? null,
 		destinationBounds: matchedLink?.destination?.bounds ?? null,
-		sourceStyles: matchedLink?.source.styles ?? null,
+		sourceStyles: matchedLink?.source?.styles ?? null,
 		destinationStyles: matchedLink?.destination?.styles ?? null,
-		sourceScreenKey: matchedLink?.source.screenKey ?? null,
+		sourceScreenKey: matchedLink?.source?.screenKey ?? null,
 		destinationScreenKey: matchedLink?.destination?.screenKey ?? null,
+		sourcePortalAttachTarget: matchedLink?.source?.portalAttachTarget,
+		sourceHost: matchedLink?.source?.sourceHost,
 	};
 }
 

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

@@ -1,7 +1,10 @@
 import { makeMutable } from "react-native-reanimated";
-import type { LinkPairsState, TagID, TagState } from "../types";
+import type { Entry, LinkPairsState, ScreenKey, TagID } from "../types";
 
-export type BoundaryEntriesState = Record<TagID, TagState>;
+export type BoundaryEntriesState = Record<
+	TagID,
+	{ screens: Record<ScreenKey, Entry> }
+>;
 
 export const boundaryRegistry = makeMutable<BoundaryEntriesState>({});
 

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

@@ -10,9 +10,10 @@ export type TagID = string;
 export type LinkKey = string;
 export type GroupKey = string;
 export type ScreenPairKey = string;
+export type BoundsPortalAttachTarget = "current-screen" | "matched-screen";
 export type { ScreenKey } from "../../types/screen.types";
 
-export type BoundaryConfig = {
+type BoundaryConfig = {
 	anchor?: BoundsAnchor;
 	scaleMode?: BoundsScaleMode;
 	target?: "bound" | "fullscreen" | MeasuredDimensions;
@@ -39,15 +40,64 @@ export type ScreenIdentifier = {
 	screenKey: ScreenKey;
 };
 
-export type TagLink = {
+export type BoundsLinkStatus =
+	| "source-incomplete"
+	| "destination-incomplete"
+	| "complete";
+
+export type TagLinkSide = ScreenIdentifier & MeasuredEntry;
+
+/**
+ * The source screen's active portal host at measure time. Recorded only when
+ * that host captures scroll (a Transition.ScrollView scope) — matched-screen
+ * placement uses it as a coordinate space to express the source rect in the
+ * source ScrollView's live frame. The portal never attaches here.
+ */
+export type SourceHostRef = {
+	hostKey: string;
+	capturesScroll: boolean;
+};
+
+export type SourceTagLinkSide = TagLinkSide & {
+	/** Where this boundary's portal content renders during the transition. */
+	portalAttachTarget?: BoundsPortalAttachTarget;
+	/** Scroll-scoped host the source originated from, if any. */
+	sourceHost?: SourceHostRef;
+};
+
+type TagLinkBase = {
 	group?: GroupKey;
-	source: ScreenIdentifier & MeasuredEntry;
-	/** Destination side once attached; null while the source is still pending. */
-	destination: (ScreenIdentifier & MeasuredEntry) | null;
 	/** First captured source side exposed for public link inspection. */
-	initialSource?: ScreenIdentifier & MeasuredEntry;
+	initialSource?: TagLinkSide;
 	/** First attached destination side, used to compensate reveal closes after destination refreshes. */
-	initialDestination?: ScreenIdentifier & MeasuredEntry;
+	initialDestination?: TagLinkSide;
+};
+
+export type TagLink =
+	| (TagLinkBase & {
+			status: "source-incomplete";
+			/** Source side once attached; null while destination captured first. */
+			source: null;
+			/** Destination side once attached; null while the source is still pending. */
+			destination: TagLinkSide | null;
+	  })
+	| (TagLinkBase & {
+			status: "destination-incomplete";
+			/** Source side once attached; null while destination captured first. */
+			source: SourceTagLinkSide;
+			/** Destination side once attached; null while the source is still pending. */
+			destination: null;
+	  })
+	| (TagLinkBase & {
+			status: "complete";
+			/** Source side once attached; null while destination captured first. */
+			source: SourceTagLinkSide;
+			/** Destination side once attached; null while the source is still pending. */
+			destination: TagLinkSide;
+	  });
+
+export type BoundsLink = TagLink & {
+	id: TagID;
 };
 
 export type ResolveTransitionContext = {
@@ -64,12 +114,8 @@ export type ResolvedTransitionPair = {
 	destinationStyles: StyleProps | null;
 	sourceScreenKey: ScreenKey | null;
 	destinationScreenKey: ScreenKey | null;
-};
-
-export type ScreenEntry = Entry;
-
-export type BoundaryState = {
-	screens: Record<ScreenKey, ScreenEntry>;
+	sourcePortalAttachTarget?: BoundsPortalAttachTarget;
+	sourceHost?: SourceHostRef;
 };
 
 export type LinkGroupState = {
@@ -83,5 +129,3 @@ export type LinkPairState = {
 };
 
 export type LinkPairsState = Record<ScreenPairKey, LinkPairState>;
-
-export type TagState = BoundaryState;

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

@@ -5,6 +5,7 @@ import {
 } from "react-native-reanimated";
 import type {
 	ScrollGestureAxis,
+	ScrollGestureAxisState,
 	ScrollGestureState,
 	ScrollMetadataState,
 } from "../types/gesture.types";
@@ -69,6 +70,73 @@ const clearMetadataWriters = (routeKey: ScreenKey) => {
 	delete metadataWriters[routeKey];
 };
 
+export const cloneScrollMetadataState = (
+	scroll: ScrollMetadataState | null | undefined,
+): ScrollMetadataState | null => {
+	"worklet";
+
+	if (!scroll) {
+		return null;
+	}
+
+	return {
+		vertical: scroll.vertical
+			? {
+					offset: scroll.vertical.offset,
+					contentSize: scroll.vertical.contentSize,
+					layoutSize: scroll.vertical.layoutSize,
+					isTouched: scroll.vertical.isTouched,
+				}
+			: null,
+		horizontal: scroll.horizontal
+			? {
+					offset: scroll.horizontal.offset,
+					contentSize: scroll.horizontal.contentSize,
+					layoutSize: scroll.horizontal.layoutSize,
+					isTouched: scroll.horizontal.isTouched,
+				}
+			: null,
+	};
+};
+
+/**
+ * Offset clamped to the axis layout range, so iOS rubber-band overscroll never
+ * leaks into coordinate-space deltas. Returns null when the axis is untracked.
+ */
+export const clampScrollAxisOffset = (
+	axisState: ScrollGestureAxisState | null | undefined,
+): number | null => {
+	"worklet";
+
+	if (!axisState) {
+		return null;
+	}
+
+	const maxOffset = Math.max(0, axisState.contentSize - axisState.layoutSize);
+	return Math.min(Math.max(axisState.offset, 0), maxOffset);
+};
+
+/**
+ * Clamped scroll travel between a captured snapshot and the current state on
+ * one axis. Returns 0 when either side does not track the axis.
+ */
+export const getClampedScrollAxisDelta = (
+	current: ScrollMetadataState | null | undefined,
+	captured: ScrollMetadataState | null | undefined,
+	axis: ScrollGestureAxis,
+): number => {
+	"worklet";
+
+	const currentOffset = clampScrollAxisOffset(current?.[axis]);
+	const capturedOffset = clampScrollAxisOffset(captured?.[axis]);
+
+	if (currentOffset === null || capturedOffset === null) {
+		return 0;
+	}
+
+	return currentOffset - capturedOffset;
+};
+
 /**
  * Route-keyed scroll geometry used by gesture activation and bounds measurement.
  * Coordination tracks gesture-owner scoped ScrollView offsets and dimensions;

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

@@ -292,11 +292,26 @@ export type ScreenStyleInterpolator = (
  */
 export type AnimatedViewStyle = ViewStyle & TextStyle;
 
+export type BoundaryTeleportControl =
+	| boolean
+	| {
+			enabled?: boolean;
+	  };
+
+export type TransitionSlotProps = Record<string, unknown> & {
+	/**
+	 * Controls whether a portal-enabled boundary should attach for the current
+	 * interpolator frame. `false` detaches the portal while keeping hostName
+	 * ownership internal.
+	 */
+	teleport?: BoundaryTeleportControl;
+};
+
 type TransitionSlotDefinition = {
 	/** Animated styles applied via `useAnimatedStyle`. */
 	style?: AnimatedViewStyle;
 	/** Animated props applied via `useAnimatedProps`. */
-	props?: Record<string, unknown>;
+	props?: TransitionSlotProps;
 };
 
 /**
@@ -330,7 +345,7 @@ export type TransitionInterpolatorOptions = Omit<
  */
 export type NormalizedTransitionSlotStyle = {
 	style?: StyleProps;
-	props?: Record<string, unknown>;
+	props?: TransitionSlotProps;
 };
 
 /**