react-native-screen-transitions 3.5.2 → 3.6.0-alpha.1

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

@@ -0,0 +1,146 @@
+import type { NormalizedTransitionSlotStyle } from "../../../../../types/animation.types";
+import { getPropResetValue, getStyleResetValue } from "./reset-values";
+import type { ResettableStyleState } from "./types";
+
+const hasTrackedKey = (keys: Record<string, true> | undefined, key: string) => {
+	"worklet";
+	return keys !== undefined && keys[key] === true;
+};
+
+const isDefinedStyleValue = (value: unknown) => {
+	"worklet";
+	return value !== undefined && value !== null;
+};
+
+// fallow-ignore-next-line complexity
+const collectDefinedKeys = ({
+	source,
+	getResetValue,
+}: {
+	source: Record<string, unknown> | undefined;
+	getResetValue: (key: string, value: unknown) => unknown;
+}) => {
+	"worklet";
+	const sourceValues = source ?? {};
+	const keys: Record<string, true> = {};
+	const resetValues: Record<string, unknown> = {};
+	let hasKeys = false;
+	let hasResetValues = false;
+
+	for (const key in sourceValues) {
+		const value = sourceValues[key];
+
+		if (!isDefinedStyleValue(value)) {
+			continue;
+		}
+
+		keys[key] = true;
+		hasKeys = true;
+
+		const resetValue = getResetValue(key, value);
+
+		if (resetValue !== undefined) {
+			resetValues[key] = resetValue;
+			hasResetValues = true;
+		}
+	}
+
+	return {
+		keys: hasKeys ? keys : undefined,
+		resetValues: hasResetValues ? resetValues : undefined,
+		hasKeys,
+	};
+};
+
+export const hasDisappearedKeys = (
+	previousKeys: Record<string, true> | undefined,
+	currentKeys: Record<string, true> | undefined,
+) => {
+	"worklet";
+
+	if (!previousKeys) {
+		return false;
+	}
+
+	for (const key in previousKeys) {
+		if (!hasTrackedKey(currentKeys, key)) {
+			return true;
+		}
+	}
+
+	return false;
+};
+
+const hasEitherKeySet = (
+	styleKeys: Record<string, true> | undefined,
+	propKeys: Record<string, true> | undefined,
+) => {
+	"worklet";
+	return styleKeys !== undefined || propKeys !== undefined;
+};
+
+const getNextStyleState = ({
+	styleKeys,
+	styleResetValues,
+	propKeys,
+	propResetValues,
+}: {
+	styleKeys: Record<string, true> | undefined;
+	styleResetValues: Record<string, unknown> | undefined;
+	propKeys: Record<string, true> | undefined;
+	propResetValues: Record<string, unknown> | undefined;
+}): ResettableStyleState | undefined => {
+	"worklet";
+
+	if (!hasEitherKeySet(styleKeys, propKeys)) {
+		return undefined;
+	}
+
+	return {
+		styleKeys,
+		styleResetValues,
+		propKeys,
+		propResetValues,
+	};
+};
+
+export const getResolvedSlotState = (
+	slot: NormalizedTransitionSlotStyle | undefined,
+) => {
+	"worklet";
+	const baseStyle = slot?.style as Record<string, unknown> | undefined;
+	const baseProps = slot?.props as Record<string, unknown> | undefined;
+
+	const {
+		keys: styleKeys,
+		resetValues: styleResetValues,
+		hasKeys: hasAnyStyleKeys,
+	} = collectDefinedKeys({
+		source: baseStyle,
+		getResetValue: getStyleResetValue,
+	});
+	const {
+		keys: propKeys,
+		resetValues: propResetValues,
+		hasKeys: hasAnyPropKeys,
+	} = collectDefinedKeys({
+		source: baseProps,
+		getResetValue: getPropResetValue,
+	});
+
+	return {
+		baseStyle,
+		baseProps,
+		styleKeys,
+		propKeys,
+		hasAnyStyleKeys,
+		hasAnyPropKeys,
+		hasAnyKeys: hasAnyStyleKeys || hasAnyPropKeys,
+		nextState: getNextStyleState({
+			styleKeys,
+			styleResetValues,
+			propKeys,
+			propResetValues,
+		}),
+	};
+};

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

@@ -0,0 +1,8 @@
+export type ResettableStyleState = {
+	styleKeys?: Record<string, true>;
+	styleResetValues?: Record<string, unknown>;
+	propKeys?: Record<string, true>;
+	propResetValues?: Record<string, unknown>;
+};
+
+export type ResettableStyleStatesBySlot = Record<string, ResettableStyleState>;

package/src/shared/providers/screen/styles/helpers/strip-interpolator-options.ts

@@ -0,0 +1,17 @@
+export const stripInterpolatorOptions = (raw: Record<string, any>) => {
+	"worklet";
+
+	if (!("options" in raw)) {
+		return raw;
+	}
+
+	const slots: Record<string, any> = {};
+
+	for (const key in raw) {
+		if (key !== "options") {
+			slots[key] = raw[key];
+		}
+	}
+
+	return slots;
+};

package/src/shared/providers/screen/styles/helpers/visibility-gate.ts

@@ -0,0 +1,57 @@
+import { LifecycleTransitionRequestKind } from "../../../../stores/system.store";
+
+type ScreenVisibilityGateState = {
+	isFloatingOverlay?: boolean;
+	hasVisibilityGateOpened: boolean;
+	pendingLifecycleStartBlockCount: number;
+	pendingLifecycleRequestKind: LifecycleTransitionRequestKind;
+	progress: number;
+	entering: number;
+};
+
+type ScreenVisibilityGateDecision = {
+	shouldBlock: boolean;
+	shouldOpenGate: boolean;
+};
+
+export const resolveScreenVisibilityGate = ({
+	isFloatingOverlay,
+	hasVisibilityGateOpened,
+	pendingLifecycleStartBlockCount,
+	pendingLifecycleRequestKind,
+	progress,
+	entering,
+}: ScreenVisibilityGateState): ScreenVisibilityGateDecision => {
+	"worklet";
+	if (isFloatingOverlay || hasVisibilityGateOpened) {
+		return {
+			shouldBlock: false,
+			shouldOpenGate: false,
+		};
+	}
+
+	const hasPendingLifecycleBlock = pendingLifecycleStartBlockCount > 0;
+	const isPendingOpen =
+		pendingLifecycleRequestKind === LifecycleTransitionRequestKind.Open;
+	const isOpening = isPendingOpen || !!entering;
+
+	// Keep the screen hidden until the first transformed opening frame exists.
+	// The lifecycle request is cleared before the RAF-scheduled progress
+	// animation starts, so `entering` carries the gate through that one-frame gap.
+	const isWaitingForOpenToStart = progress <= 0;
+
+	const shouldBlock =
+		(hasPendingLifecycleBlock || isWaitingForOpenToStart) && isOpening;
+
+	return {
+		shouldBlock,
+		shouldOpenGate: !shouldBlock && progress > 0,
+	};
+};
+
+export const shouldBlockScreenVisibility = (
+	state: ScreenVisibilityGateState,
+) => {
+	"worklet";
+	return resolveScreenVisibilityGate(state).shouldBlock;
+};

package/src/shared/providers/screen/styles/hooks/use-interpolated-style-maps.tsx

@@ -1,21 +1,61 @@
 import { useDerivedValue, useSharedValue } from "react-native-reanimated";
 import { NO_STYLES } from "../../../../constants";
 import { SystemStore } from "../../../../stores/system.store";
-import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
+import type {
+	NormalizedTransitionInterpolatedStyle,
+	TransitionInterpolatedStyle,
+} from "../../../../types/animation.types";
 import { logger } from "../../../../utils/logger";
 import { useScreenAnimationContext } from "../../animation";
+import { useBuildBoundsAccessor } from "../../animation/helpers/accessors/use-build-bounds-accessor";
+import { useBuildTransitionAccessor } from "../../animation/helpers/accessors/use-build-transition-accessor";
+import { syncSelectedInterpolatorOptions } from "../../animation/helpers/selected-interpolator-options";
 import { useDescriptorDerivations } from "../../descriptors";
+import {
+	syncScreenOptionsOverrides,
+	useScreenOptionsContext,
+} from "../../options";
 import { normalizeSlots } from "../helpers/normalize-slots";
-
+import { preserveAnimatedPropsOnly } from "../helpers/preserve-animated-props-only";
+import { stripInterpolatorOptions } from "../helpers/strip-interpolator-options";
+
+/**
+ * Builds the raw interpolated styles map for the current screen pass.
+ *
+ * This hook exists to stabilize style ownership during rapid navigation,
+ * especially when an interactive close gesture overlaps with a new navigation
+ * event. In flows like `A -> B`, begin closing `B`, then quickly open `C`,
+ * the active route state can change before the gesture-driven close has
+ * visually finished.
+ *
+ * If we immediately switch to the next interpolator in that window, styles can
+ * be computed against the wrong route pair and leave layer or element slots
+ * stranded in an intermediate state. We therefore latch onto the current
+ * gesture interpolator for the lifetime of that close interaction, then resume
+ * normal interpolator selection once the gesture-driven close is no longer in
+ * play.
+ *
+ * Visibility gating happens downstream while lifecycle start is blocked for
+ * pending destination measurement. We still run the interpolator during that
+ * hidden window so animated props and runtime options stay warm, but defer style
+ * buckets so measurement sees the final untransformed layout.
+ *
+ * The result stays as a single slot map. Resolution happens downstream, where
+ * slot ids determine whether a slot may inherit from ancestors or must remain
+ * local to the owning screen container.
+ */
 export const useInterpolatedStylesMap = () => {
 	const { currentScreenKey } = useDescriptorDerivations();
+	const screenOptions = useScreenOptionsContext();
 	const {
 		screenInterpolatorProps,
+		screenInterpolatorPropsRevision,
+		selectedInterpolatorOptions,
 		nextInterpolator,
 		currentInterpolator,
-		boundsAccessor,
 	} = useScreenAnimationContext();
-
+	const boundsAccessor = useBuildBoundsAccessor();
+	const transition = useBuildTransitionAccessor();
 	const pendingLifecycleStartBlockCount = SystemStore.getValue(
 		currentScreenKey,
 		"pendingLifecycleStartBlockCount",
@@ -25,15 +65,29 @@ export const useInterpolatedStylesMap = () => {
 
 	return useDerivedValue<NormalizedTransitionInterpolatedStyle>(() => {
 		"worklet";
-		if (pendingLifecycleStartBlockCount.get() > 0) {
-			return NO_STYLES;
-		}
-
+		screenInterpolatorPropsRevision.get();
 		const props = screenInterpolatorProps.get();
+
+		/**
+		 * There is a niche case where bounds can be attached to a view that's styles are out of viewport.
+		 * Due to our blocking mechanism and ensuring accurate measurement, this boundary measurement
+		 * will be blocked and the screen will never be visible. To mitigate this, we:
+		 *
+		 * - Defer the style buckets (props are fine), to ensure we get the correct position of the boundary
+		 *
+		 * Again this is very niche, and since we're not marketing ourselves as a proper shared element transition
+		 * package, we won't spend time finding a better solution for this.
+		 *
+		 */
+		const shouldDeferStyleBuckets = pendingLifecycleStartBlockCount.get() > 0;
+
 		const { current, next, progress } = props;
 		const isDragging = current.gesture.dragging;
 		const isNextClosing = !!next?.closing;
 
+		// Keep using the gesture-driven interpolator until the closing gesture has
+		// fully released. This avoids switching style ownership mid-flight when a
+		// new navigation event lands before the close interaction visually settles.
 		if (isDragging && isNextClosing) {
 			isGesturingDuringCloseAnimation.set(true);
 		}
@@ -42,13 +96,19 @@ export const useInterpolatedStylesMap = () => {
 			isGesturingDuringCloseAnimation.set(false);
 		}
 
-		const isInGestureMode = isDragging || isGesturingDuringCloseAnimation.get();
+		const isInGestureMode =
+			!!isDragging || isGesturingDuringCloseAnimation.get();
 
-		const interpolator = isInGestureMode
-			? currentInterpolator
-			: (nextInterpolator ?? currentInterpolator);
+		const interpolatorOptionsOwner =
+			isInGestureMode || !nextInterpolator ? "current" : "next";
+		const interpolator =
+			interpolatorOptionsOwner === "current"
+				? currentInterpolator
+				: nextInterpolator;
 
 		if (!interpolator) {
+			syncSelectedInterpolatorOptions(selectedInterpolatorOptions, "current");
+			syncScreenOptionsOverrides(undefined, screenOptions);
 			return NO_STYLES;
 		}
 
@@ -66,19 +126,36 @@ export const useInterpolatedStylesMap = () => {
 				progress: effectiveProgress,
 				next: effectiveNext,
 				bounds: boundsAccessor,
+				transition,
 			});
 
-			const stylesMap =
-				typeof raw !== "object" || raw == null
-					? NO_STYLES
-					: normalizeSlots(raw);
-
-			return stylesMap;
+			const rawStyleMap: TransitionInterpolatedStyle | undefined =
+				typeof raw === "object" && raw != null ? raw : undefined;
+
+			syncSelectedInterpolatorOptions(
+				selectedInterpolatorOptions,
+				interpolatorOptionsOwner,
+				rawStyleMap?.options,
+			);
+			syncScreenOptionsOverrides(
+				interpolatorOptionsOwner === "current" ? rawStyleMap : undefined,
+				screenOptions,
+			);
+
+			const stylesMap = !rawStyleMap
+				? NO_STYLES
+				: normalizeSlots(stripInterpolatorOptions(rawStyleMap));
+
+			return shouldDeferStyleBuckets
+				? preserveAnimatedPropsOnly(stylesMap)
+				: stylesMap;
 		} catch (_) {
 			if (__DEV__) {
 				logger.warn("screenStyleInterpolator must be a worklet");
 			}
 
+			syncSelectedInterpolatorOptions(selectedInterpolatorOptions, "current");
+			syncScreenOptionsOverrides(undefined, screenOptions);
 			return NO_STYLES;
 		}
 	});

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

@@ -1,35 +1,59 @@
 import {
 	useAnimatedProps,
+	useAnimatedReaction,
 	useAnimatedStyle,
-	useDerivedValue,
+	useSharedValue,
 } from "react-native-reanimated";
 import { AnimationStore } from "../../../../stores/animation.store";
 import { SystemStore } from "../../../../stores/system.store";
 import { useDescriptorDerivations } from "../../descriptors";
+import { resolveScreenVisibilityGate } from "../helpers/visibility-gate";
 
 export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 	const { currentScreenKey } = useDescriptorDerivations();
-	const progress = AnimationStore.getValue(currentScreenKey, "progress");
+	const { entering, progress } = AnimationStore.getBag(currentScreenKey);
 
-	const { pendingLifecycleStartBlockCount } =
+	const { pendingLifecycleStartBlockCount, pendingLifecycleRequestKind } =
 		SystemStore.getBag(currentScreenKey);
 
-	const shouldBlockVisibility = useDerivedValue(() => {
-		"worklet";
+	const hasVisibilityGateOpened = useSharedValue(false);
+	const shouldBlockVisibility = useSharedValue(!isFloatingOverlay);
 
-		if (isFloatingOverlay) {
-			return false;
-		}
+	/**
+	 * Visibility has to start blocked before the first animated style pass.
+	 *
+	 * `useDerivedValue` can publish its computed value after `useAnimatedStyle`
+	 * has already read the initial one, which briefly exposes an unhydrated
+	 * screen. Keep the visible state in an eagerly initialized shared value, then
+	 * let the reaction open it once the visibility gate allows the first
+	 * transformed frame to render.
+	 */
+	useAnimatedReaction(
+		() => {
+			"worklet";
 
-		const hasPendingLifecycleBlock = pendingLifecycleStartBlockCount.get() > 0;
-		const isWaitingForOpenToStart = progress.get() <= 0;
+			return resolveScreenVisibilityGate({
+				isFloatingOverlay,
+				hasVisibilityGateOpened: hasVisibilityGateOpened.get(),
+				pendingLifecycleStartBlockCount: pendingLifecycleStartBlockCount.get(),
+				pendingLifecycleRequestKind: pendingLifecycleRequestKind.get(),
+				progress: progress.get(),
+				entering: entering.get(),
+			});
+		},
+		(gate) => {
+			"worklet";
 
-		return hasPendingLifecycleBlock || isWaitingForOpenToStart;
-	});
+			if (gate.shouldOpenGate) {
+				hasVisibilityGateOpened.set(true);
+			}
+
+			shouldBlockVisibility.set(gate.shouldBlock);
+		},
+	);
 
 	const animatedStyle = useAnimatedStyle(() => {
 		"worklet";
-
 		return {
 			opacity: shouldBlockVisibility.get() ? 0 : 1,
 		};

package/src/shared/providers/screen/styles/hooks/use-resolved-slot-style-map.tsx

@@ -5,9 +5,11 @@ import {
 } from "react-native-reanimated";
 import { NO_STYLES } from "../../../../constants";
 import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
+import { useScreenAnimationContext } from "../../animation";
 import {
 	type ResettableStyleStatesBySlot,
 	resolveSlotStyles,
+	reuseEqualResolvedSlots,
 } from "../helpers/resolve-slot-styles";
 
 interface UseResolvedStylesMapParams {
@@ -19,22 +21,38 @@ export const useResolvedStylesMap = ({
 	currentStylesMap,
 	ancestorStylesMap,
 }: UseResolvedStylesMapParams) => {
+	const { screenInterpolatorProps, screenInterpolatorPropsRevision } =
+		useScreenAnimationContext();
 	const previousStyleStatesBySlot = useSharedValue<ResettableStyleStatesBySlot>(
 		{},
 	);
+	const previousResolvedStylesMap =
+		useSharedValue<NormalizedTransitionInterpolatedStyle>(NO_STYLES);
 
 	return useDerivedValue(() => {
 		"worklet";
+		screenInterpolatorPropsRevision.get();
+
+		const props = screenInterpolatorProps.get();
+		// Keep missing local slots alive while another route drives this screen.
+		// Custom ids and keys from slots that still exist are still reset.
+		const deferLocalSlotResets = !props.focused && !props.current.closing;
 
 		const { resolvedStylesMap, nextPreviousStyleStatesBySlot } =
 			resolveSlotStyles({
 				currentStylesMap: currentStylesMap.get(),
 				ancestorStylesMap: ancestorStylesMap?.get() ?? NO_STYLES,
 				previousStyleStatesBySlot: previousStyleStatesBySlot.get(),
+				deferLocalSlotResets,
 			});
 
 		previousStyleStatesBySlot.set(nextPreviousStyleStatesBySlot);
+		const stableResolvedStylesMap = reuseEqualResolvedSlots({
+			resolvedStylesMap,
+			previousResolvedStylesMap: previousResolvedStylesMap.get(),
+		});
+		previousResolvedStylesMap.set(stableResolvedStylesMap);
 
-		return resolvedStylesMap;
+		return stableResolvedStylesMap;
 	});
 };

package/src/shared/providers/stack/helpers/use-closing-route-map.ts

@@ -15,7 +15,7 @@ export const useClosingRouteMap = (
 			"worklet";
 			const map: Record<string, true> = {};
 			for (let i = 0; i < animationMaps.length; i++) {
-				if (animationMaps[i].closing.value > 0) {
+				if (animationMaps[i].closing.get() > 0) {
 					const routeKey = routeKeys[i];
 					if (routeKey) {
 						map[routeKey] = true;

package/src/shared/providers/stack/helpers/use-stack-derived.ts

@@ -23,7 +23,7 @@ export function useStackDerived(
 		"worklet";
 		let total = 0;
 		for (let i = 0; i < animationMaps.length; i++) {
-			total += animationMaps[i].progress.value;
+			total += animationMaps[i].progress.get();
 		}
 		return total;
 	});
@@ -33,7 +33,7 @@ export function useStackDerived(
 		const lastIndex = animationMaps.length - 1;
 		let closingFromTop = 0;
 		for (let i = lastIndex; i >= 0; i--) {
-			if (animationMaps[i].closing.value > 0) closingFromTop++;
+			if (animationMaps[i].closing.get() > 0) closingFromTop++;
 			else break;
 		}
 		return lastIndex - closingFromTop;

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

@@ -8,11 +8,9 @@ import { createStore } from "../utils/create-store";
 export type AnimationStoreMap = {
 	progress: SharedValue<number>;
 	willAnimate: SharedValue<number>;
-	animating: SharedValue<number>;
+	progressAnimating: SharedValue<number>;
 	closing: SharedValue<number>;
 	entering: SharedValue<number>;
-	settled: SharedValue<number>;
-	logicallySettled: SharedValue<number>;
 };
 
 function createAnimationBag(): AnimationStoreMap {
@@ -20,10 +18,8 @@ function createAnimationBag(): AnimationStoreMap {
 		progress: makeMutable(0),
 		willAnimate: makeMutable(0),
 		closing: makeMutable(0),
-		animating: makeMutable(0),
+		progressAnimating: makeMutable(0),
 		entering: makeMutable(0),
-		settled: makeMutable(1),
-		logicallySettled: makeMutable(1),
 	};
 }
 
@@ -37,10 +33,8 @@ export const AnimationStore = createStore<AnimationStoreMap>({
 	disposeBag: (bag) => {
 		cancelAnimation(bag.progress);
 		cancelAnimation(bag.willAnimate);
-		cancelAnimation(bag.animating);
+		cancelAnimation(bag.progressAnimating);
 		cancelAnimation(bag.closing);
 		cancelAnimation(bag.entering);
-		cancelAnimation(bag.settled);
-		cancelAnimation(bag.logicallySettled);
 	},
 });

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

@@ -0,0 +1,55 @@
+import type { EntryPatch, ScreenEntry, ScreenKey, TagState } from "../types";
+
+type EntryPatchOptionalField = "boundaryConfig";
+
+const ENTRY_PATCH_OPTIONAL_FIELDS = [
+	"boundaryConfig",
+] as const satisfies readonly EntryPatchOptionalField[];
+
+export const ensureScreenEntry = (
+	tagState: TagState,
+	screenKey: ScreenKey,
+): ScreenEntry => {
+	"worklet";
+	if (!tagState.screens[screenKey]) {
+		tagState.screens[screenKey] = {
+			bounds: null,
+			styles: {},
+		};
+	}
+	return tagState.screens[screenKey];
+};
+
+export const applyEntryPatch = (entry: ScreenEntry, patch: EntryPatch) => {
+	"worklet";
+	if (patch.bounds !== undefined) {
+		entry.bounds = patch.bounds;
+	}
+
+	if (patch.styles !== undefined) {
+		entry.styles = patch.styles ?? {};
+	}
+
+	const target = entry as Record<EntryPatchOptionalField, unknown>;
+	for (let i = 0; i < ENTRY_PATCH_OPTIONAL_FIELDS.length; i++) {
+		const field = ENTRY_PATCH_OPTIONAL_FIELDS[i];
+		const value = patch[field];
+		if (value === undefined) continue;
+
+		if (value === null) {
+			delete target[field];
+		} else {
+			target[field] = value;
+		}
+	}
+};
+
+export const findMatchingScreenEntry = (
+	tagState: TagState | undefined,
+	screenKey: ScreenKey,
+): ScreenEntry | null => {
+	"worklet";
+	if (!tagState) return null;
+
+	return tagState.screens[screenKey] ?? null;
+};

package/src/shared/stores/bounds/helpers/find-latest.ts

@@ -0,0 +1,22 @@
+export const findLatestIndex = <T>(
+	items: readonly T[],
+	matches: (item: T) => boolean,
+): number => {
+	"worklet";
+	for (let i = items.length - 1; i >= 0; i--) {
+		if (matches(items[i])) {
+			return i;
+		}
+	}
+
+	return -1;
+};
+
+export const findLatest = <T>(
+	items: readonly T[],
+	matches: (item: T) => boolean,
+): T | null => {
+	"worklet";
+	const index = findLatestIndex(items, matches);
+	return index === -1 ? null : (items[index] ?? null);
+};