react-native-screen-transitions 3.6.0 → 3.7.0-alpha.0

package/src/shared/components/activity/variants/activity-container.tsx

@@ -0,0 +1,25 @@
+import { StyleSheet, View } from "react-native";
+
+import { ScreenContainer } from "react-native-screens";
+import { IS_WEB } from "../../../constants";
+import { useStack } from "../../../hooks/navigation/use-stack";
+
+interface Props {
+	children: React.ReactNode;
+}
+
+export const ActivityContainer = ({ children }: Props) => {
+	const nativeScreenDisabled = useStack((s) => s.flags.DISABLE_NATIVE_SCREENS);
+	const Component = IS_WEB || nativeScreenDisabled ? View : ScreenContainer;
+	return (
+		<Component collapsable={false} style={styles.container}>
+			{children}
+		</Component>
+	);
+};
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+	},
+});

package/src/shared/components/activity/variants/activity-screen.tsx

@@ -0,0 +1,133 @@
+import type * as React from "react";
+import { memo } from "react";
+import { StyleSheet, View, type ViewProps } from "react-native";
+import { useDerivedValue } from "react-native-reanimated";
+import { Screen } from "react-native-screens";
+import { IS_WEB } from "../../../constants";
+import { useStack } from "../../../hooks/navigation/use-stack";
+import { useSharedValueState } from "../../../hooks/reanimated/use-shared-value-state";
+import { AnimationStore } from "../../../stores/animation.store";
+import type { StackSceneActivity } from "../../../types/stack.types";
+import { DEFAULT_INACTIVE_BEHAVIOR, type InactiveBehavior } from "../helpers";
+
+type ActivityState = 0 | 1 | 2;
+const ActivityStateByActivity = {
+	active: 2,
+	inert: 1,
+	inactive: 0,
+	closing: 1,
+} satisfies Record<StackSceneActivity, ActivityState>;
+
+const PointerEventsByActivity = {
+	active: "auto",
+	inert: "auto",
+	inactive: "none",
+	closing: "none",
+} satisfies Record<StackSceneActivity, ViewProps["pointerEvents"]>;
+
+interface ActivityScreenProps {
+	activity: StackSceneActivity;
+	children: React.ReactNode;
+	inactiveBehavior?: InactiveBehavior;
+	paintDriverRouteKey?: string;
+	hasNestedState?: boolean;
+}
+
+export const ActivityScreen = memo(function ActivityScreen({
+	activity,
+	children,
+	inactiveBehavior = DEFAULT_INACTIVE_BEHAVIOR,
+	paintDriverRouteKey,
+	hasNestedState,
+}: ActivityScreenProps) {
+	const nativeScreenDisabled = useStack((s) => s.flags.DISABLE_NATIVE_SCREENS);
+	const paintDriverAnimations = paintDriverRouteKey
+		? AnimationStore.getBag(paintDriverRouteKey)
+		: undefined;
+
+	/**
+	 * Avoid hiding inactive content until the screen that exposes it has settled.
+	 *
+	 * For A(inactive), B(inert), C(active), A's paint depends on C finishing its
+	 * transition. Watching B can still leave a brief blank frame, so we wait for
+	 * C's progress to reach its settled value of 1 before hiding A.
+	 */
+	const isPaintDriverSettled = useDerivedValue(() => {
+		"worklet";
+
+		if (!paintDriverAnimations) {
+			return false;
+		}
+
+		return paintDriverAnimations.progress.get() >= 1;
+	});
+
+	const isPaintDriverSettledOnJS = useSharedValueState(isPaintDriverSettled);
+
+	let activityState: ActivityState = ActivityStateByActivity[activity];
+	let shouldFreeze = false;
+	let visible = activity !== "inactive";
+
+	const shouldWaitForPaintDriver = !isPaintDriverSettledOnJS;
+
+	if (activity === "inactive") {
+		if (inactiveBehavior === "keep") {
+			activityState = 1;
+			visible = true;
+		} else if (shouldWaitForPaintDriver) {
+			// Delay hiding until the paint driver has settled to avoid
+			// a blank frame during the transition.
+			activityState = 1;
+			visible = true;
+		} else if (inactiveBehavior === "freeze") {
+			activityState = 1;
+			shouldFreeze = true;
+			visible = true;
+		} else {
+			// `detach` hides native presentation. Non-nested `unmount`
+			// removes the React subtree through the JS guard below.
+			activityState = 0;
+			visible = false;
+		}
+	}
+
+	const shouldUnmount =
+		inactiveBehavior === "unmount" &&
+		activity === "inactive" &&
+		!hasNestedState &&
+		isPaintDriverSettledOnJS;
+
+	const pointerEvents = PointerEventsByActivity[activity];
+
+	if (shouldUnmount) {
+		return null;
+	}
+
+	const style = [StyleSheet.absoluteFill, visible ? undefined : styles.hidden];
+
+	if (IS_WEB || nativeScreenDisabled) {
+		return (
+			<View style={style} pointerEvents={pointerEvents} collapsable={false}>
+				{children}
+			</View>
+		);
+	}
+
+	return (
+		<Screen
+			style={style}
+			activityState={activityState}
+			shouldFreeze={shouldFreeze}
+			pointerEvents={pointerEvents}
+			collapsable={false}
+		>
+			{children}
+		</Screen>
+	);
+});
+
+const styles = StyleSheet.create({
+	hidden: {
+		display: "none",
+	},
+});

package/src/shared/components/create-boundary-component/hooks/use-measurer.ts

@@ -9,8 +9,10 @@ import {
 } from "../../../stores/bounds/internals/links";
 import { ScrollStore } from "../../../stores/scroll.store";
 import { SystemStore } from "../../../stores/system.store";
+import { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
 import type { MeasureBoundary } from "../types";
 import {
+	applyVisibilityBlockOffset,
 	isMeasurementInViewport,
 	measureWithOverscrollAwareness,
 } from "../utils/measured-bounds";
@@ -55,6 +57,19 @@ export const useMeasurer = ({
 
 			if (!measured) return;
 
+			// Source boundaries do not need offset correction. Only destination
+			// captures can measure while the visibility gate is still blocked.
+			const shouldAdjustBlockedDestination =
+				target.type === "destination" &&
+				pendingLifecycleStartBlockCount.get() > 0;
+
+			const normalizedMeasured = shouldAdjustBlockedDestination
+				? applyVisibilityBlockOffset(
+						measured,
+						getVisibilityBlockOffset(viewportHeight),
+					)
+				: measured;
+
 			/**
 			 * - Destination Pass -
 			 * Be strict while lifecycle start is blocked for destination capture.
@@ -68,14 +83,18 @@ export const useMeasurer = ({
 			const viewportAllowsDestinationWrite =
 				target.type !== "destination" ||
 				!shouldGuardDestinationViewport ||
-				isMeasurementInViewport(measured, viewportWidth, viewportHeight);
+				isMeasurementInViewport(
+					normalizedMeasured,
+					viewportWidth,
+					viewportHeight,
+				);
 
 			if (!viewportAllowsDestinationWrite) return;
 
 			// Set the bounds entry on every measure to avoid any stale measurements
 			// for the public read API.
 			setEntry(entryTag, currentScreenKey, {
-				bounds: measured,
+				bounds: normalizedMeasured,
 			});
 
 			if (target.type === "source") {
@@ -83,7 +102,7 @@ export const useMeasurer = ({
 					target.pairKey,
 					linkId,
 					currentScreenKey,
-					measured,
+					normalizedMeasured,
 					preparedStyles,
 					group,
 				);
@@ -94,7 +113,7 @@ export const useMeasurer = ({
 					target.pairKey,
 					linkId,
 					currentScreenKey,
-					measured,
+					normalizedMeasured,
 					preparedStyles,
 					group,
 				);

package/src/shared/components/create-boundary-component/utils/measured-bounds.ts

@@ -46,6 +46,21 @@ export const adjustedMeasuredBoundsForOverscrollDeltas = (
 	};
 };
 
+export const applyVisibilityBlockOffset = (
+	measured: MeasuredDimensions,
+	offset: number,
+): MeasuredDimensions => {
+	"worklet";
+	if (offset === 0) {
+		return measured;
+	}
+
+	return {
+		...measured,
+		pageY: measured.pageY - offset,
+	};
+};
+
 export const isMeasurementInViewport = (
 	measured: MeasuredDimensions,
 	viewportWidth: number,

package/src/shared/components/screen-lifecycle/hooks/use-close-transition-intent.ts

@@ -1,6 +1,5 @@
 /** biome-ignore-all lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per navigator */
 import { useLayoutEffect, useMemo, useRef } from "react";
-import { useAnimatedReaction } from "react-native-reanimated";
 import useStableCallback from "../../../hooks/use-stable-callback";
 import {
 	type BaseDescriptor,
@@ -8,7 +7,6 @@ import {
 } from "../../../providers/screen/descriptors";
 import { useStackCoreContext } from "../../../providers/stack/core.provider";
 import { useManagedStackContext } from "../../../providers/stack/managed.provider";
-import type { AnimationStoreMap } from "../../../stores/animation.store";
 import { GestureStore } from "../../../stores/gesture.store";
 import {
 	LifecycleTransitionRequestKind,
@@ -20,22 +18,24 @@ import { resetStoresForScreen } from "./helpers/reset-stores-for-screen";
 
 interface CloseHookParams {
 	current: BaseDescriptor;
-	animations: AnimationStoreMap;
 	requestLifecycleTransition: SystemStoreActions["requestLifecycleTransition"];
 	resetStores: () => void;
 }
 
-/**
- * Managed close - reacts to closingRouteKeysShared from ManagedStackContext.
- * Used by blank-stack and component-stack.
- */
 const useManagedClose = ({
 	current,
 	requestLifecycleTransition,
 	resetStores,
 }: CloseHookParams) => {
-	const { handleCloseRoute, closingRouteKeysShared } = useManagedStackContext();
-	const routeKey = current.route.key;
+	const { handleCloseRoute } = useManagedStackContext();
+
+	useLayoutEffect(() => {
+		if (current.activity !== "closing") {
+			return;
+		}
+
+		requestLifecycleTransition(LifecycleTransitionRequestKind.ManagedClose, 0);
+	}, [current.activity, requestLifecycleTransition]);
 
 	const handleManagedCloseEnd = useStableCallback((finished: boolean) => {
 		if (!finished) return;
@@ -45,21 +45,6 @@ const useManagedClose = ({
 		});
 	});
 
-	useAnimatedReaction(
-		() => {
-			const keys = closingRouteKeysShared.get();
-			return keys?.includes(routeKey) ?? false;
-		},
-		(isClosing, wasClosing) => {
-			if (!isClosing || wasClosing) return;
-
-			requestLifecycleTransition(
-				LifecycleTransitionRequestKind.ManagedClose,
-				0,
-			);
-		},
-	);
-
 	return { handleManagedCloseEnd };
 };
 
@@ -127,7 +112,6 @@ const useNativeStackClose = ({
  */
 export function useCloseTransitionIntent(
 	current: BaseDescriptor,
-	animations: AnimationStoreMap,
 	system: SystemStoreMap,
 ): {
 	handleManagedCloseEnd?: (finished: boolean) => void;
@@ -144,7 +128,6 @@ export function useCloseTransitionIntent(
 
 	const closeParams: CloseHookParams = {
 		current,
-		animations,
 		requestLifecycleTransition,
 		resetStores,
 	};

package/src/shared/components/screen-lifecycle/index.tsx

@@ -21,7 +21,7 @@ export const ScreenLifecycle = ({ children }: Props) => {
 	const system = SystemStore.getBag(current.route.key);
 
 	const { handleManagedCloseEnd, handleNativeCloseEnd } =
-		useCloseTransitionIntent(current, animations, system);
+		useCloseTransitionIntent(current, system);
 
 	useOpenTransitionIntent(current, animations, system);
 

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

@@ -1,9 +1,15 @@
 import { StackActions } from "@react-navigation/native";
 import { useCallback } from "react";
-import { useDescriptors } from "../../providers/screen/descriptors";
+import { useDescriptorsStore } from "../../providers/screen/descriptors";
+import { useStack } from "./use-stack";
 
 export function useNavigationHelpers() {
-	const { current } = useDescriptors();
+	const current = useDescriptorsStore((store) => store.descriptors.current);
+	const requestStackDismiss = useStack((stack) => stack.requestDismiss);
+
+	const requestDismiss = useCallback((): boolean => {
+		return requestStackDismiss?.({ route: current.route }) ?? false;
+	}, [current.route, requestStackDismiss]);
 
 	const dismissScreen = useCallback((): boolean => {
 		const state = current.navigation.getState();
@@ -21,5 +27,5 @@ export function useNavigationHelpers() {
 		return true;
 	}, [current]);
 
-	return { dismissScreen };
+	return { dismissScreen, requestDismiss };
 }

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

@@ -1,5 +1,13 @@
 import type { Route } from "@react-navigation/native";
-import { createContext, useContext } from "react";
+import {
+	createContext,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useLayoutEffect,
+	useRef,
+	useSyncExternalStore,
+} from "react";
 import type { DerivedValue } from "react-native-reanimated";
 import type { StackCoreContextValue } from "../../providers/stack/core.provider";
 import type { OverlayProps } from "../../types/overlay.types";
@@ -25,23 +33,124 @@ export interface StackDescriptor<
 export type StackScene<TDescriptor extends StackDescriptor = StackDescriptor> =
 	BaseStackScene<TDescriptor>;
 
+type StackDismissRequest = (payload: { route: BaseStackRoute }) => boolean;
+type StackSelector<T> = (stack: StackContextValue) => T;
+
 export interface StackContextValue extends StackCoreContextValue {
 	navigatorKey: string;
 	routeKeys: string[];
 	routes: Route<string>[];
 	scenes: StackScene[];
 	optimisticFocusedIndex: DerivedValue<number>;
+	focusedIndex: number;
+	requestDismiss?: StackDismissRequest;
+}
+
+interface StackStoreApi {
+	getSnapshot: () => StackContextValue;
+	subscribe: (listener: () => void) => () => void;
 }
 
-export const StackContext = createContext<StackContextValue | null>(null);
+interface MutableStackStoreApi extends StackStoreApi {
+	notify: () => void;
+	setSnapshot: (snapshot: StackContextValue) => boolean;
+}
+
+const createStackStore = (
+	initialSnapshot: StackContextValue,
+): MutableStackStoreApi => {
+	let snapshot = initialSnapshot;
+	const listeners = new Set<() => void>();
+
+	return {
+		getSnapshot: () => snapshot,
+		notify: () => {
+			for (const listener of listeners) {
+				listener();
+			}
+		},
+		setSnapshot: (nextSnapshot) => {
+			if (Object.is(snapshot, nextSnapshot)) {
+				return false;
+			}
+
+			snapshot = nextSnapshot;
+			return true;
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+	};
+};
+
+const StackContext = createContext<StackStoreApi | null>(null);
 StackContext.displayName = "Stack";
 
-export function useStack<T extends StackContextValue = StackContextValue>(): T {
-	const context = useContext(StackContext);
+export function StackProvider({
+	children,
+	value,
+}: {
+	children: ReactNode;
+	value: StackContextValue;
+}) {
+	const storeRef = useRef<MutableStackStoreApi | null>(null);
+	const pendingNotifyRef = useRef(false);
+
+	let store = storeRef.current;
+	if (!store) {
+		store = createStackStore(value);
+		storeRef.current = store;
+	}
 
-	if (context === null) {
+	pendingNotifyRef.current =
+		store.setSnapshot(value) || pendingNotifyRef.current;
+
+	useLayoutEffect(() => {
+		if (!pendingNotifyRef.current) {
+			return;
+		}
+
+		pendingNotifyRef.current = false;
+		store.notify();
+	});
+
+	return (
+		<StackContext.Provider value={store}>{children}</StackContext.Provider>
+	);
+}
+
+function useStackStore(): StackStoreApi {
+	const store = useContext(StackContext);
+
+	if (store === null) {
 		throw new Error("useStack must be used within a Stack provider");
 	}
 
-	return context as T;
+	return store;
+}
+
+export function useStack<T extends StackContextValue = StackContextValue>(): T;
+export function useStack<T>(selector: StackSelector<T>): T;
+export function useStack<T>(
+	selector?: StackSelector<T>,
+): StackContextValue | T {
+	const store = useStackStore();
+	const selectorRef = useRef<StackSelector<StackContextValue | T>>(
+		selector ?? ((stack) => stack),
+	);
+	selectorRef.current = selector ?? ((stack) => stack);
+
+	const getSelectedSnapshot = useCallback(
+		() => selectorRef.current(store.getSnapshot()),
+		[store],
+	);
+
+	return useSyncExternalStore(
+		store.subscribe,
+		getSelectedSnapshot,
+		getSelectedSnapshot,
+	);
 }

package/src/shared/index.ts

@@ -1,4 +1,5 @@
 import { FlatList, Pressable, ScrollView, View } from "react-native";
+import { withScreenTransitions } from "./adapters/with-screen-transitions";
 import {
 	Boundary,
 	createBoundaryComponent,
@@ -10,6 +11,7 @@ import { Presets, Specs } from "./configs";
 export default {
 	createTransitionAwareComponent,
 	createBoundaryComponent,
+	withScreenTransitions,
 	Boundary,
 	View: createTransitionAwareComponent(View),
 	Pressable: createTransitionAwareComponent(Pressable),
@@ -24,6 +26,12 @@ export default {
 	Specs,
 };
 
+export type {
+	NativeStackAdapterOptions,
+	NativeStackNativeGestureOptions,
+	ScreenTransitionDescriptorOptions,
+} from "./adapters/with-screen-transitions";
+export { withScreenTransitions } from "./adapters/with-screen-transitions";
 export { snapTo } from "./animation/snap-to";
 export {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
@@ -53,6 +61,7 @@ export type {
 	BoundsNavigationZoomOpacityRanges,
 	BoundsNavigationZoomOptions,
 	BoundsNavigationZoomStyle,
+	InactiveBehavior,
 	OverlayProps,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,

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

@@ -8,8 +8,8 @@ import { getAncestorKeys } from "./helpers/get-ancestor-keys";
 
 /**
  * Base descriptor interface - minimal contract for all stack types.
- * This allows blank-stack and native-stack to work with the shared
- * providers without tight coupling to React Navigation.
+ * This allows stack implementations to work with the shared providers without
+ * tight coupling to React Navigation.
  */
 export type BaseDescriptor = BaseStackDescriptor;
 
@@ -23,6 +23,13 @@ export interface DescriptorsContextValue<
 
 export type DescriptorDerivationsContextValue = DescriptorDerivations;
 
+interface DescriptorStoreValue<
+	TDescriptor extends BaseDescriptor = BaseDescriptor,
+> {
+	descriptors: DescriptorsContextValue<TDescriptor>;
+	derivations: DescriptorDerivationsContextValue;
+}
+
 interface DescriptorsProviderProps<TDescriptor extends BaseDescriptor> {
 	children: ReactNode;
 	previous?: TDescriptor;
@@ -30,35 +37,21 @@ interface DescriptorsProviderProps<TDescriptor extends BaseDescriptor> {
 	next?: TDescriptor;
 }
 
-type InternalProviderProps = DescriptorsProviderProps<BaseDescriptor>;
-
 const {
 	DescriptorsProvider: InternalDescriptorsProvider,
-	useDescriptorsContext,
+	useDescriptorsStore,
 } = createProvider("Descriptors", { guarded: true })<
-	InternalProviderProps,
-	DescriptorsContextValue<BaseDescriptor>
->(({ previous, current, next }) => {
-	const value = useMemo(
+	DescriptorsProviderProps<BaseDescriptor>,
+	DescriptorStoreValue<BaseDescriptor>
+>(({ previous, current, next, children }) => {
+	const descriptors = useMemo(
 		() => ({ previous, current, next }),
 		[previous, current, next],
 	);
 
-	return {
-		value,
-	};
-});
-
-const {
-	DescriptorDerivationsProvider: InternalDescriptorDerivationsProvider,
-	useDescriptorDerivationsContext,
-} = createProvider("DescriptorDerivations", { guarded: true })<
-	InternalProviderProps,
-	DescriptorDerivationsContextValue
->(({ previous, current, next, children }) => {
 	const ancestorKeys = useMemo(() => getAncestorKeys(current), [current]);
 
-	const value = useMemo(
+	const derivations = useMemo(
 		() =>
 			deriveDescriptorDerivations({
 				previous,
@@ -69,6 +62,14 @@ const {
 		[previous, current, next, ancestorKeys],
 	);
 
+	const value = useMemo(
+		() => ({
+			descriptors,
+			derivations,
+		}),
+		[descriptors, derivations],
+	);
+
 	return {
 		value,
 		children,
@@ -85,23 +86,22 @@ export function DescriptorsProvider<TDescriptor extends BaseDescriptor>({
 		previous,
 		current,
 		next,
+		children,
 	};
 
-	return (
-		<InternalDescriptorsProvider {...providerProps}>
-			<InternalDescriptorDerivationsProvider {...providerProps}>
-				{children}
-			</InternalDescriptorDerivationsProvider>
-		</InternalDescriptorsProvider>
-	);
+	return <InternalDescriptorsProvider {...providerProps} />;
 }
 
 export function useDescriptors<
 	TDescriptor extends BaseDescriptor = BaseDescriptor,
 >() {
-	return useDescriptorsContext() as DescriptorsContextValue<TDescriptor>;
+	return useDescriptorsStore(
+		(store) => store.descriptors,
+	) as DescriptorsContextValue<TDescriptor>;
 }
 
 export function useDescriptorDerivations(): DescriptorDerivationsContextValue {
-	return useDescriptorDerivationsContext();
+	return useDescriptorsStore((store) => store.derivations);
 }
+
+export { useDescriptorsStore };

package/src/shared/providers/screen/descriptors/index.tsx

@@ -3,4 +3,5 @@ export {
 	DescriptorsProvider,
 	useDescriptorDerivations,
 	useDescriptors,
+	useDescriptorsStore,
 } from "./descriptors.provider";

package/src/shared/providers/screen/gestures/ownership/resolve-ownership.ts

@@ -87,6 +87,7 @@ export function shouldDeferToChildClaim(
 	"worklet";
 	if (!childClaim) return false;
 	if (childClaim.routeKey === selfRouteKey) return false;
-	if (childClaim.isDismissing.get()) return false;
+	// A closing child still owns its axis until its claim is cleaned up; otherwise
+	// an ancestor can steal the next drag while the previous screen is visible.
 	return true;
 }

package/src/shared/providers/screen/gestures/ownership/use-walk-up-and-register-shadowing-claims.ts

@@ -1,4 +1,4 @@
-import { useEffect, useMemo } from "react";
+import { useLayoutEffect, useMemo } from "react";
 import { GestureStore } from "../../../../stores/gesture.store";
 import {
 	type ClaimedDirections,
@@ -115,7 +115,7 @@ export function useWalkUpAndRegisterShadowingClaims(
 		[parentContext, claimedDirections],
 	);
 
-	useEffect(() => {
+	useLayoutEffect(() => {
 		if (!isTopMostScreen || !shadowedAncestors.length) {
 			return;
 		}