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

package/src/shared/hooks/animation/use-associated-style.ts

@@ -0,0 +1,347 @@
+import {
+	type StyleProps,
+	useAnimatedProps,
+	useAnimatedStyle,
+	useSharedValue,
+} from "react-native-reanimated";
+import { EPSILON, NO_PROPS, NO_STYLES } from "../../constants";
+import { useDescriptorDerivations } from "../../providers/screen/descriptors";
+import { useScreenStyles } from "../../providers/screen/styles.provider";
+import { AnimationStore } from "../../stores/animation.store";
+import { BoundStore } from "../../stores/bounds";
+
+type Props = {
+	id?: string;
+	style?: StyleProps;
+	resetTransformOnUnset?: boolean;
+	waitForFirstResolvedStyle?: boolean;
+};
+
+const TRANSIENT_EMPTY_GRACE_FRAMES = 2;
+const TRANSITION_PROGRESS_COMPLETE = 1 - EPSILON;
+const IDENTITY_TRANSFORM = [
+	{ translateX: 0 },
+	{ translateY: 0 },
+	{ scaleX: 1 },
+	{ scaleY: 1 },
+] as any;
+const ALWAYS_RESET_STYLE_VALUES = {
+	zIndex: 0,
+	elevation: 0,
+} as const;
+
+type AssociatedStyleMode = "waiting-first-style" | "hold-last-style" | "live";
+
+type GroupTagParts = {
+	group: string;
+	memberId: string;
+};
+
+type KeyMeta = {
+	keys: Record<string, true>;
+	hasAny: boolean;
+};
+
+const hasAnyKeys = (record: Record<string, unknown>) => {
+	"worklet";
+	for (const _key in record) {
+		return true;
+	}
+	return false;
+};
+
+const collectKeyMeta = (record: Record<string, unknown>): KeyMeta => {
+	"worklet";
+	const keys: Record<string, true> = {};
+	let hasAny = false;
+	for (const key in record) {
+		keys[key] = true;
+		hasAny = true;
+	}
+	return { keys, hasAny };
+};
+
+const getGroupTagParts = (tag: string): GroupTagParts | null => {
+	"worklet";
+	const separatorIndex = tag.indexOf(":");
+	if (separatorIndex <= 0 || separatorIndex >= tag.length - 1) {
+		return null;
+	}
+
+	return {
+		group: tag.slice(0, separatorIndex),
+		memberId: tag.slice(separatorIndex + 1),
+	};
+};
+
+const allowPreviousTransitionEvidence = (tag: string): boolean => {
+	"worklet";
+	const groupTagParts = getGroupTagParts(tag);
+	if (!groupTagParts) {
+		return true;
+	}
+
+	// For grouped boundaries, only the active member can inherit
+	// transition evidence from the previous screen.
+	const activeGroupMemberId = BoundStore.getGroupActiveId(groupTagParts.group);
+	return (
+		activeGroupMemberId !== null &&
+		activeGroupMemberId === groupTagParts.memberId
+	);
+};
+
+const buildUnsetPatch = ({
+	previousKeys,
+	currentKeys,
+	shouldDeferUnset,
+	resetTransformOnUnset,
+}: {
+	previousKeys: Record<string, true>;
+	currentKeys: Record<string, true>;
+	shouldDeferUnset: boolean;
+	resetTransformOnUnset: boolean;
+}) => {
+	"worklet";
+	const unsetPatch: Record<string, any> = {};
+
+	for (const key in previousKeys) {
+		if (currentKeys[key]) continue;
+		const shouldAlwaysUnset = key in ALWAYS_RESET_STYLE_VALUES;
+		if (shouldDeferUnset && !shouldAlwaysUnset) continue;
+
+		if (key === "transform" && resetTransformOnUnset) {
+			unsetPatch.transform = IDENTITY_TRANSFORM;
+		} else if (key in ALWAYS_RESET_STYLE_VALUES) {
+			unsetPatch[key] =
+				ALWAYS_RESET_STYLE_VALUES[
+					key as keyof typeof ALWAYS_RESET_STYLE_VALUES
+				];
+		} else {
+			unsetPatch[key] = undefined;
+		}
+	}
+
+	return unsetPatch;
+};
+
+/**
+ * Resolves the animated style associated with an `id` (styleId/bound tag), while
+ * guarding against one-frame glitches during shared-boundary transitions.
+ *
+ * Why this exists:
+ * - During push/pop, links and style maps can be briefly out of sync.
+ * - Without guards, boundaries can flash raw layout for one frame.
+ * - Cleanup must be deterministic so stale transform keys do not linger.
+ *
+ * Visual model (worklet state machine):
+ *
+ *   expected transition + no resolved style yet -> waiting-first-style
+ *   expected transition + transient empty style map -> hold-last-style
+ *   otherwise -> live
+ *
+ * - `waiting-first-style`: return `opacity: 0` until first resolved style arrives.
+ * - `hold-last-style`: reuse last resolved style through short empty-map gaps.
+ * - `live`: apply current resolved style directly.
+ *
+ * For grouped tags (`group:id`), previous-screen transition evidence is only
+ * considered for the group's active member to avoid hiding non-active siblings.
+ *
+ * Set `waitForFirstResolvedStyle` to `false` for generic shared-bound-tag usage
+ * where the transition can be driven by other style ids.
+ */
+export const useAssociatedStyles = ({
+	id,
+	resetTransformOnUnset = false,
+	waitForFirstResolvedStyle = true,
+}: Props = {}) => {
+	const { stylesMap, ancestorStylesMaps } = useScreenStyles();
+	const { previousScreenKey, currentScreenKey, hasConfiguredInterpolator } =
+		useDescriptorDerivations();
+	const isAnimating = AnimationStore.getRouteAnimation(
+		currentScreenKey,
+		"animating",
+	);
+	const progress = AnimationStore.getRouteAnimation(
+		currentScreenKey,
+		"progress",
+	);
+	const isClosing = AnimationStore.getRouteAnimation(
+		currentScreenKey,
+		"closing",
+	);
+	const previousAppliedKeys = useSharedValue<Record<string, true>>({});
+	const emptyGraceFrameCount = useSharedValue(0);
+	const lastResolvedBase = useSharedValue<Record<string, any> | null>(null);
+
+	const associatedStyles = useAnimatedStyle(() => {
+		"worklet";
+
+		if (!id) {
+			return NO_STYLES;
+		}
+
+		// Check local slot first, then fall back to parent
+		const ownSlot = stylesMap.value[id];
+
+		const ancestorSlot = ancestorStylesMaps.find(
+			(ancestorMap) => ancestorMap.value[id],
+		)?.value[id];
+
+		const slot = ownSlot || ancestorSlot;
+		const base = slot?.style || NO_STYLES;
+
+		const { keys: currentKeys, hasAny: hasCurrentKeys } = collectKeyMeta(
+			base as Record<string, unknown>,
+		);
+
+		const hasPreviousKeys = hasAnyKeys(previousAppliedKeys.value);
+
+		const isTransitioning = isAnimating.get() !== 0 || isClosing.get() !== 0;
+		const isTransitionProgressInFlight =
+			progress.get() < TRANSITION_PROGRESS_COMPLETE;
+		const isTransitionInFlight =
+			isTransitioning || isTransitionProgressInFlight;
+
+		const canUsePreviousTransitionEvidence =
+			resetTransformOnUnset && allowPreviousTransitionEvidence(id);
+
+		const hasActiveLink =
+			resetTransformOnUnset &&
+			canUsePreviousTransitionEvidence &&
+			(BoundStore.hasPendingLink(id) ||
+				BoundStore.hasSourceLink(id, currentScreenKey) ||
+				BoundStore.hasDestinationLink(id, currentScreenKey));
+
+		const hasPreviousTransitionEvidence =
+			canUsePreviousTransitionEvidence &&
+			!!previousScreenKey &&
+			(!!BoundStore.getSnapshot(id, previousScreenKey) ||
+				BoundStore.hasBoundaryPresence(id, previousScreenKey));
+
+		// Split intent:
+		// - incoming: strict signal for first-style hiding
+		// - in-flight: broad signal to keep existing styles from resetting
+		const shouldExpectIncomingStyle =
+			resetTransformOnUnset &&
+			((hasActiveLink && canUsePreviousTransitionEvidence) ||
+				hasPreviousTransitionEvidence);
+
+		const shouldProtectInFlightStyles =
+			resetTransformOnUnset && (hasActiveLink || hasPreviousTransitionEvidence);
+
+		if (hasCurrentKeys) {
+			lastResolvedBase.value = base as Record<string, any>;
+		}
+
+		const hasPersistedResolvedStyle = !!lastResolvedBase.value;
+		const hasResolvedStyle = hasCurrentKeys || hasPersistedResolvedStyle;
+
+		const isTransientEmptyGap =
+			hasConfiguredInterpolator &&
+			shouldProtectInFlightStyles &&
+			!isTransitioning &&
+			!hasCurrentKeys &&
+			(hasPreviousKeys || hasPersistedResolvedStyle);
+
+		// Keep styles stable for a couple of frames to absorb
+		// transient empty-map gaps on slower devices.
+		if (isTransientEmptyGap) {
+			emptyGraceFrameCount.value = emptyGraceFrameCount.value + 1;
+		} else {
+			emptyGraceFrameCount.value = 0;
+		}
+
+		const isWithinGapGrace =
+			isTransientEmptyGap &&
+			emptyGraceFrameCount.value <= TRANSIENT_EMPTY_GRACE_FRAMES;
+
+		const shouldDeferUnset =
+			resetTransformOnUnset &&
+			shouldProtectInFlightStyles &&
+			(isTransitioning || isWithinGapGrace);
+
+		/**
+		 * Associated-style state machine:
+		 * - waiting-first-style: transition is expected but no style has resolved yet.
+		 * - hold-last-style: transient empty frame; reuse last resolved style.
+		 * - live: apply current resolved style normally.
+		 */
+		let mode: AssociatedStyleMode = "live";
+		if (
+			waitForFirstResolvedStyle &&
+			resetTransformOnUnset &&
+			hasConfiguredInterpolator &&
+			shouldExpectIncomingStyle &&
+			isTransitionInFlight &&
+			!hasResolvedStyle
+		) {
+			mode = "waiting-first-style";
+		} else if (
+			shouldDeferUnset &&
+			!hasCurrentKeys &&
+			hasPersistedResolvedStyle
+		) {
+			mode = "hold-last-style";
+		}
+
+		const resolvedBase =
+			mode === "hold-last-style"
+				? (lastResolvedBase.value as Record<string, any>)
+				: (base as Record<string, any>);
+
+		const unsetPatch = buildUnsetPatch({
+			previousKeys: previousAppliedKeys.value,
+			currentKeys,
+			shouldDeferUnset,
+			resetTransformOnUnset,
+		});
+
+		if (shouldDeferUnset) {
+			previousAppliedKeys.value = {
+				...previousAppliedKeys.value,
+				...currentKeys,
+			};
+		} else {
+			previousAppliedKeys.value = currentKeys;
+
+			// Drop cached style when fully idle so future transitions
+			// start from a clean state.
+			if (!hasCurrentKeys && !shouldProtectInFlightStyles && !isTransitioning) {
+				lastResolvedBase.value = null;
+			}
+		}
+
+		if (mode === "waiting-first-style") {
+			return { ...unsetPatch, opacity: 0 };
+		}
+
+		const mergedBase = { ...unsetPatch, ...resolvedBase };
+
+		let opacity = 1;
+
+		if ("opacity" in mergedBase) {
+			opacity = mergedBase.opacity as number;
+		}
+
+		if ("opacity" in mergedBase) {
+			return mergedBase;
+		}
+
+		return { ...mergedBase, opacity };
+	});
+
+	const associatedProps = useAnimatedProps(() => {
+		"worklet";
+
+		if (!id) return NO_PROPS;
+
+		const ownSlot = stylesMap.value[id];
+		const ancestorSlot = ancestorStylesMaps.find(
+			(ancestorMap) => ancestorMap.value[id],
+		)?.value[id];
+
+		return (ownSlot || ancestorSlot)?.props ?? NO_PROPS;
+	});
+
+	return { associatedStyles, associatedProps };
+};

package/src/shared/hooks/gestures/use-screen-gesture.ts

@@ -1,4 +1,4 @@
-import { useGestureContext } from "../../providers/gestures.provider";
+import { useGestureContext } from "../../providers/gestures";
 
 /**
  * Returns a ref to the screen's navigation pan gesture.

package/src/shared/hooks/gestures/{use-scroll-registry.tsx → use-scroll-registry.ts}

@@ -21,7 +21,7 @@ import {
 	type GestureContextType,
 	type ScrollConfig,
 	useGestureContext,
-} from "../../providers/gestures.provider";
+} from "../../providers/gestures";
 import type { Direction } from "../../types/ownership.types";
 import useStableCallback from "../use-stable-callback";
 

package/src/shared/hooks/navigation/use-history.ts

@@ -2,7 +2,7 @@ import { useMemo, useSyncExternalStore } from "react";
 import { type HistoryEntry, HistoryStore } from "../../stores/history.store";
 import type { ScreenKey } from "../../types/screen.types";
 
-export interface UseHistoryReturn {
+interface UseHistoryReturn {
 	/**
 	 * The full history map.
 	 */

package/src/shared/hooks/navigation/use-navigation-helpers.ts

@@ -0,0 +1,25 @@
+import { StackActions } from "@react-navigation/native";
+import { useCallback } from "react";
+import { useDescriptors } from "../../providers/screen/descriptors";
+
+export function useNavigationHelpers() {
+	const { current } = useDescriptors();
+
+	const dismissScreen = useCallback((): boolean => {
+		const state = current.navigation.getState();
+		const routeIndex = state.routes.findIndex(
+			(route) => route.key === current.route.key,
+		);
+		const routeStillPresent = routeIndex !== -1;
+		if (!routeStillPresent || routeIndex === 0) return false;
+
+		current.navigation.dispatch({
+			...StackActions.pop(),
+			source: current.route.key,
+			target: state.key,
+		});
+		return true;
+	}, [current]);
+
+	return { dismissScreen };
+}

package/src/shared/hooks/navigation/{use-previous.tsx → use-previous.ts}

@@ -1,6 +1,6 @@
 import { useEffect, useRef } from "react";
 
-export const usePrevious = <T,>(value: T): T | null => {
+export const usePrevious = <T>(value: T): T | null => {
 	const ref = useRef<T>(null);
 
 	useEffect(() => {

package/src/shared/hooks/navigation/{use-screen-state.tsx → use-screen-state.ts}

@@ -3,8 +3,8 @@ import { useCallback, useMemo } from "react";
 import { snapDescriptorToIndex } from "../../animation/snap-to";
 import {
 	type BaseDescriptor,
-	useKeys,
-} from "../../providers/screen/keys.provider";
+	useDescriptors,
+} from "../../providers/screen/descriptors";
 import type { ScreenTransitionConfig } from "../../types/screen.types";
 import type { BaseStackNavigation } from "../../types/stack.types";
 import { useOptimisticFocusedIndex } from "./use-optimistic-focused-index";
@@ -66,7 +66,7 @@ export function useScreenState<
 >(): ScreenState<TNavigation> {
 	const { routes, scenes, routeKeys, optimisticFocusedIndex } =
 		useStack<StackContextValue>();
-	const { current } = useKeys<BaseDescriptor>();
+	const { current } = useDescriptors<BaseDescriptor>();
 
 	const index = useMemo(
 		() => routeKeys.indexOf(current.route.key),

package/src/shared/hooks/navigation/use-stack.tsx

@@ -10,10 +10,6 @@ import type {
 	BaseStackScene,
 } from "../../types/stack.types";
 
-/**
- * Stack descriptor with overlay options.
- * Extends BaseStackDescriptor with overlay-specific options.
- */
 export interface StackDescriptor<
 	TRoute extends BaseStackRoute = Route<string>,
 	TNavigation extends BaseStackNavigation = BaseStackNavigation,
@@ -27,57 +23,21 @@ export interface StackDescriptor<
 	};
 }
 
-/**
- * Scene type for stack context (route + descriptor pair).
- */
 export type StackScene<TDescriptor extends StackDescriptor = StackDescriptor> =
 	BaseStackScene<TDescriptor>;
 
-/**
- * Common stack context value that both managed and direct stack providers populate.
- * Used by overlays and shared components that need stack progress info.
- */
 export interface StackContextValue extends StackCoreContextValue {
-	/**
-	 * Route keys for all routes in the stack.
-	 */
+	navigatorKey: string;
 	routeKeys: string[];
-	/**
-	 * All routes in the stack.
-	 */
 	routes: Route<string>[];
-	/**
-	 * Descriptor map for all routes.
-	 */
-	descriptors: Record<string, StackDescriptor>;
-	/**
-	 * Pre-computed scenes (route + descriptor pairs).
-	 */
 	scenes: StackScene[];
-	/**
-	 * The current focused index from navigation state.
-	 */
-	focusedIndex: number;
-	/**
-	 * Aggregated stack progress across all routes.
-	 * Sum of all individual screen progress values.
-	 * When 4 screens are fully visible, stackProgress = 4.
-	 */
 	stackProgress: DerivedValue<number>;
-	/**
-	 * Focused index that accounts for closing screens.
-	 * Returns currentIndex - 1 if any screen is closing, otherwise currentIndex.
-	 */
 	optimisticFocusedIndex: DerivedValue<number>;
 }
 
 export const StackContext = createContext<StackContextValue | null>(null);
 StackContext.displayName = "Stack";
 
-/**
- * Hook to access common stack context values.
- * Works in both blank-stack and native-stack navigators.
- */
 export function useStack<T extends StackContextValue = StackContextValue>(): T {
 	const context = useContext(StackContext);
 

package/src/shared/hooks/navigation/use-tab-press-reset.ts

@@ -0,0 +1,41 @@
+import { type EventArg, StackActions } from "@react-navigation/native";
+import * as React from "react";
+
+/**
+ * When inside a tab navigator, resets the stack to the first screen
+ * when the already-focused tab is pressed again. Replicates native behaviour.
+ */
+export function useTabPressReset(
+	navigation: {
+		isFocused: () => boolean;
+		addListener?: (event: string, callback: (e: any) => void) => () => void;
+		dispatch: (action: any) => void;
+	},
+	stateIndex: number,
+	stateKey: string,
+) {
+	React.useEffect(
+		() =>
+			navigation?.addListener?.("tabPress", (e: any) => {
+				const isFocused = navigation.isFocused();
+
+				// Run the operation in the next frame so we're sure all listeners have been run
+				// This is necessary to know if preventDefault() has been called
+				requestAnimationFrame(() => {
+					if (
+						stateIndex > 0 &&
+						isFocused &&
+						!(e as EventArg<"tabPress", true>).defaultPrevented
+					) {
+						// When user taps on already focused tab and we're inside the tab,
+						// reset the stack to replicate native behaviour
+						navigation.dispatch({
+							...StackActions.popToTop(),
+							target: stateKey,
+						});
+					}
+				});
+			}),
+		[navigation, stateIndex, stateKey],
+	);
+}

package/src/shared/hooks/reanimated/use-shared-value-ref.ts

@@ -0,0 +1,43 @@
+import { useCallback, useRef } from "react";
+import {
+	executeOnUIRuntimeSync,
+	runOnJS,
+	type SharedValue,
+	useAnimatedReaction,
+} from "react-native-reanimated";
+import { IS_WEB } from "../../constants";
+
+export function readInitialValue<T>(sharedValue: SharedValue<T>): T {
+	if (IS_WEB) {
+		return sharedValue.value;
+	}
+	const readOnUI = executeOnUIRuntimeSync((sv: SharedValue<T>) => {
+		"worklet";
+		return sv.value;
+	});
+	return readOnUI(sharedValue);
+}
+
+/**
+ * Mirrors a Reanimated SharedValue into a React ref.
+ * Same bridging as useSharedValueState but without triggering rerenders.
+ */
+export function useSharedValueRef<T>(
+	sharedValue: SharedValue<T>,
+): React.RefObject<T> {
+	const ref = useRef<T>(readInitialValue(sharedValue));
+
+	const updateRef = useCallback((value: T) => {
+		ref.current = value;
+	}, []);
+
+	useAnimatedReaction(
+		() => sharedValue.value,
+		(value, previousValue) => {
+			if (Object.is(value, previousValue)) return;
+			runOnJS(updateRef)(value);
+		},
+	);
+
+	return ref;
+}

package/src/shared/hooks/reanimated/use-shared-value-state.ts

@@ -1,28 +1,17 @@
 import { useState } from "react";
 import {
-	executeOnUIRuntimeSync,
 	runOnJS,
 	type SharedValue,
 	useAnimatedReaction,
 } from "react-native-reanimated";
-import { IS_WEB } from "../../constants";
+import { readInitialValue } from "./use-shared-value-ref";
 
 /**
  * Derives React state from a Reanimated SharedValue.
  * Updates the state whenever the shared value changes.
  */
 export function useSharedValueState<T>(sharedValue: SharedValue<T>): T {
-	const [state, setState] = useState<T>(() => {
-		if (IS_WEB) {
-			// Web fallback - executeOnUIRuntimeSync not available
-			return sharedValue.value;
-		}
-		const readOnUI = executeOnUIRuntimeSync((sv: SharedValue<T>) => {
-			"worklet";
-			return sv.value;
-		});
-		return readOnUI(sharedValue);
-	});
+	const [state, setState] = useState<T>(() => readInitialValue(sharedValue));
 
 	useAnimatedReaction(
 		() => sharedValue.value,

package/src/shared/index.ts

@@ -1,10 +1,17 @@
 import { FlatList, Pressable, ScrollView, View } from "react-native";
+import {
+	Boundary,
+	createBoundaryComponent,
+} from "./components/create-boundary-component";
+import { buildBoundaryMatchKey } from "./components/create-boundary-component/utils/build-boundary-match-key";
 import { createTransitionAwareComponent } from "./components/create-transition-aware-component";
 import MaskedView from "./components/integrations/masked-view";
 import { Presets, Specs } from "./configs";
 
 export default {
 	createTransitionAwareComponent,
+	createBoundaryComponent,
+	Boundary,
 	View: createTransitionAwareComponent(View),
 	Pressable: createTransitionAwareComponent(Pressable),
 	ScrollView: createTransitionAwareComponent(ScrollView, {
@@ -19,18 +26,28 @@ export default {
 };
 
 export { snapTo } from "./animation/snap-to";
-export { useScreenAnimation } from "./hooks/animation/use-screen-animation";
 export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
 export { useHistory } from "./hooks/navigation/use-history";
 export {
 	type ScreenState,
 	useScreenState,
 } from "./hooks/navigation/use-screen-state";
+export { useScreenAnimation } from "./providers/screen/animation";
+export { buildBoundaryMatchKey };
 
 export type {
+	AnimatedViewStyle,
 	AnimationConfig,
 	BoundEntry,
 	BoundsLink,
+	BoundsNavigationAccessor,
+	BoundsNavigationOptions,
+	BoundsNavigationPreset,
+	BoundsStyleOptions,
+	LegacyTransitionInterpolatedStyle,
+	NewTransitionInterpolatedStyle,
+	NormalizedTransitionInterpolatedStyle,
+	NormalizedTransitionSlotStyle,
 	OverlayInterpolationProps,
 	OverlayMode,
 	OverlayProps,
@@ -38,5 +55,7 @@ export type {
 	ScreenStyleInterpolator,
 	ScreenTransitionConfig,
 	TransitionInterpolatedStyle,
+	TransitionSlotExplicit,
+	TransitionSlotStyle,
 	TransitionSpec,
 } from "./types";