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

package/src/shared/adapters/with-screen-transitions/options.ts

@@ -0,0 +1,172 @@
+import type { ScreenProps } from "react-native-screens";
+import type { ScreenTransitionConfig } from "../../types";
+
+type NativeStackTransitionResetOptions = {
+	presentation: "containedTransparentModal";
+	animation: "none";
+	headerShown: false;
+	gestureEnabled: false;
+};
+
+export type NativeStackNativeGestureOptions = {
+	nativeGestureEnabled?: boolean;
+	nativeGestureDirection?: ScreenProps["swipeDirection"];
+	nativeGestureResponseDistance?: ScreenProps["gestureResponseDistance"];
+};
+
+export type ScreenTransitionDescriptorOptions = ScreenTransitionConfig & {
+	enableTransitions?: boolean;
+	screenTransition?: ScreenTransitionConfig | null | false;
+};
+
+export type NativeStackAdapterOptions<
+	TNativeOptions extends object = Record<string, unknown>,
+> = Omit<
+	TNativeOptions,
+	| keyof ScreenTransitionDescriptorOptions
+	| keyof NativeStackNativeGestureOptions
+> &
+	ScreenTransitionDescriptorOptions &
+	NativeStackNativeGestureOptions;
+
+const NATIVE_STACK_TRANSITION_RESET_OPTIONS: NativeStackTransitionResetOptions =
+	{
+		presentation: "containedTransparentModal",
+		animation: "none",
+		headerShown: false,
+		gestureEnabled: false,
+	};
+
+const COLLIDING_TRANSITION_OPTION_KEYS = [
+	"gestureEnabled",
+	"gestureDirection",
+	"gestureResponseDistance",
+] as const satisfies readonly (keyof ScreenTransitionConfig)[];
+
+type CollidingTransitionOptionKey =
+	(typeof COLLIDING_TRANSITION_OPTION_KEYS)[number];
+
+export type NativeStackAdapterOptionInput =
+	| Record<string, unknown>
+	| ((...args: any[]) => Record<string, unknown> | undefined);
+
+function isPlainOptions(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function extractCollidingTransitionOptions(
+	options: Record<string, unknown>,
+): ScreenTransitionConfig | undefined {
+	let screenTransition: ScreenTransitionConfig | undefined;
+
+	for (const key of COLLIDING_TRANSITION_OPTION_KEYS) {
+		if (!(key in options)) {
+			continue;
+		}
+
+		screenTransition ??= {};
+		screenTransition[key] = options[key] as never;
+	}
+
+	return screenTransition;
+}
+
+function removeCollidingTransitionOptions<
+	TOptions extends Record<string, unknown>,
+>(options: TOptions): Omit<TOptions, CollidingTransitionOptionKey> {
+	const nativeOptions = { ...options };
+
+	for (const key of COLLIDING_TRANSITION_OPTION_KEYS) {
+		delete nativeOptions[key];
+	}
+
+	return nativeOptions;
+}
+
+function applyNativeGestureAliases<TOptions extends Record<string, unknown>>(
+	options: TOptions,
+): TOptions {
+	const nativeOptions: Record<string, unknown> = { ...options };
+	const {
+		nativeGestureEnabled,
+		nativeGestureDirection,
+		nativeGestureResponseDistance,
+	} = options;
+	delete nativeOptions.nativeGestureEnabled;
+	delete nativeOptions.nativeGestureDirection;
+	delete nativeOptions.nativeGestureResponseDistance;
+
+	if (nativeGestureEnabled !== undefined) {
+		nativeOptions.gestureEnabled = nativeGestureEnabled;
+	}
+
+	if (nativeGestureDirection !== undefined) {
+		nativeOptions.gestureDirection = nativeGestureDirection;
+	}
+
+	if (nativeGestureResponseDistance !== undefined) {
+		nativeOptions.gestureResponseDistance = nativeGestureResponseDistance;
+	}
+
+	return nativeOptions as TOptions;
+}
+
+export function adaptNativeStackTransitionOptions<
+	TOptions extends NativeStackAdapterOptionInput | undefined,
+>(options: TOptions): TOptions {
+	if (typeof options === "function") {
+		return ((...args: any[]) =>
+			adaptNativeStackTransitionOptions(options(...args))) as TOptions;
+	}
+
+	if (!isPlainOptions(options)) {
+		return options;
+	}
+
+	const inlineScreenTransition = extractCollidingTransitionOptions(options);
+	const explicitScreenTransition = options.screenTransition;
+	const hasTransitionsEnabled =
+		options.enableTransitions === true || !!explicitScreenTransition;
+
+	if (!hasTransitionsEnabled) {
+		return applyNativeGestureAliases(options) as TOptions;
+	}
+
+	const nativeOptions = applyNativeGestureAliases(
+		removeCollidingTransitionOptions(options),
+	);
+	const nativeGestureEnabled = nativeOptions.gestureEnabled;
+	const screenTransition =
+		explicitScreenTransition && isPlainOptions(explicitScreenTransition)
+			? {
+					...inlineScreenTransition,
+					...explicitScreenTransition,
+				}
+			: inlineScreenTransition;
+
+	return {
+		...nativeOptions,
+		...NATIVE_STACK_TRANSITION_RESET_OPTIONS,
+		...(nativeGestureEnabled !== undefined
+			? { gestureEnabled: nativeGestureEnabled }
+			: null),
+		enableTransitions: true,
+		...(screenTransition ? { screenTransition } : null),
+	} as TOptions;
+}
+
+export function resolveScreenTransitionOptions<
+	TOptions extends ScreenTransitionDescriptorOptions,
+>(options: TOptions): TOptions & ScreenTransitionConfig {
+	const screenTransition = options.screenTransition;
+
+	if (!screenTransition) {
+		return options;
+	}
+
+	return {
+		...options,
+		...screenTransition,
+		enableTransitions: true,
+	};
+}

package/src/shared/adapters/with-screen-transitions/stack-layout.tsx

@@ -0,0 +1,233 @@
+import type { NavigationState, Route } from "@react-navigation/native";
+import { useMemo } from "react";
+import { Overlay } from "../../components/overlay";
+import {
+	type StackContextValue,
+	StackProvider,
+} from "../../hooks/navigation/use-stack";
+import { ScreenComposer } from "../../providers/screen/screen-composer";
+import {
+	useStackCoreContext,
+	withStackCore,
+} from "../../providers/stack/core.provider";
+import { useStackDerived } from "../../providers/stack/helpers/use-stack-derived";
+import {
+	AnimationStore,
+	type AnimationStoreMap,
+} from "../../stores/animation.store";
+import type { BaseStackDescriptor, BaseStackRoute } from "../../types";
+import { StackType } from "../../types/stack.types";
+import { isOverlayVisible } from "../../utils/overlay/visibility";
+import {
+	ScreenTransitionsAdapterProvider,
+	type ScreenTransitionsAdapterScene,
+	useScreenTransitionsAdapterContext,
+} from "./context";
+import {
+	resolveScreenTransitionOptions,
+	type ScreenTransitionDescriptorOptions,
+} from "./options";
+import type {
+	NavigatorLayout,
+	NavigatorLayoutArgs,
+	ScreenLayout,
+	ScreenLayoutArgs,
+} from "./types";
+
+type DescriptorMap = Record<string, BaseStackDescriptor>;
+
+type NavigationStateWithPreloads = NavigationState & {
+	preloadedRoutes?: Route<string>[];
+};
+
+type TransitionStackState = {
+	routes: BaseStackRoute[];
+	routeKeys: string[];
+	scenes: ScreenTransitionsAdapterScene[];
+	animationMaps: AnimationStoreMap[];
+	routeIndexByKey: Map<string, number>;
+	shouldShowFloatOverlay: boolean;
+};
+
+const EMPTY_PRELOADED_ROUTES: Route<string>[] = [];
+
+function getPreloadedRoutes(state: NavigationState): Route<string>[] {
+	return (
+		(state as NavigationStateWithPreloads).preloadedRoutes ??
+		EMPTY_PRELOADED_ROUTES
+	);
+}
+
+function normalizeDescriptor(
+	descriptor: BaseStackDescriptor,
+): BaseStackDescriptor {
+	return {
+		...descriptor,
+		options: resolveScreenTransitionOptions(
+			descriptor.options as ScreenTransitionDescriptorOptions,
+		),
+	};
+}
+
+function buildTransitionStackState({
+	state,
+	descriptors,
+}: {
+	state: NavigationState;
+	descriptors: DescriptorMap;
+}): TransitionStackState {
+	const routes = state.routes as BaseStackRoute[];
+	const preloadedRoutes = getPreloadedRoutes(state) as BaseStackRoute[];
+	const allRoutes = routes.concat(preloadedRoutes);
+	const routeKeys: string[] = [];
+	const scenes: ScreenTransitionsAdapterScene[] = [];
+	const animationMaps: AnimationStoreMap[] = [];
+	const routeIndexByKey = new Map<string, number>();
+	let shouldShowFloatOverlay = false;
+
+	for (const route of allRoutes) {
+		const descriptor = descriptors[route.key];
+		if (!descriptor) {
+			if (preloadedRoutes.includes(route)) {
+				continue;
+			}
+
+			throw new Error(
+				`withScreenTransitions could not find a descriptor for route "${route.key}".`,
+			);
+		}
+
+		const normalizedDescriptor = normalizeDescriptor(descriptor);
+		const sceneIndex = scenes.length;
+		const previousDescriptor = scenes[sceneIndex - 1]?.descriptor;
+
+		if (previousDescriptor) {
+			scenes[sceneIndex - 1] = {
+				...scenes[sceneIndex - 1],
+				nextDescriptor: normalizedDescriptor,
+			};
+		}
+
+		scenes.push({
+			route,
+			descriptor: normalizedDescriptor,
+			previousDescriptor,
+		});
+		routeKeys.push(route.key);
+		animationMaps.push(AnimationStore.getBag(route.key));
+		routeIndexByKey.set(route.key, sceneIndex);
+
+		if (
+			!shouldShowFloatOverlay &&
+			(normalizedDescriptor.options as ScreenTransitionDescriptorOptions)
+				.enableTransitions &&
+			isOverlayVisible(normalizedDescriptor.options)
+		) {
+			shouldShowFloatOverlay = true;
+		}
+	}
+
+	return {
+		routes: allRoutes,
+		routeKeys,
+		scenes,
+		animationMaps,
+		routeIndexByKey,
+		shouldShowFloatOverlay,
+	};
+}
+
+type ScreenTransitionsStackContentProps = {
+	layout?: NavigatorLayout;
+	layoutArgs: NavigatorLayoutArgs;
+};
+
+function ScreenTransitionsStackContent({
+	layout,
+	layoutArgs,
+}: ScreenTransitionsStackContentProps) {
+	const { flags } = useStackCoreContext();
+	const transitionState = useMemo(
+		() =>
+			buildTransitionStackState({
+				state: layoutArgs.state,
+				descriptors: layoutArgs.descriptors as DescriptorMap,
+			}),
+		[layoutArgs.state, layoutArgs.descriptors],
+	);
+	const { optimisticFocusedIndex } = useStackDerived(
+		transitionState.animationMaps,
+	);
+	const stackContextValue = useMemo<StackContextValue>(
+		() => ({
+			flags,
+			navigatorKey: layoutArgs.state.key,
+			routeKeys: transitionState.routeKeys,
+			routes: transitionState.routes as Route<string>[],
+			scenes: transitionState.scenes,
+			optimisticFocusedIndex,
+			focusedIndex: layoutArgs.state.index,
+		}),
+		[
+			flags,
+			layoutArgs.state.key,
+			layoutArgs.state.index,
+			transitionState.routeKeys,
+			transitionState.routes,
+			transitionState.scenes,
+			optimisticFocusedIndex,
+		],
+	);
+	const adapterContextValue = useMemo(
+		() => ({
+			routeIndexByKey: transitionState.routeIndexByKey,
+			scenes: transitionState.scenes,
+		}),
+		[transitionState.routeIndexByKey, transitionState.scenes],
+	);
+	const children = layout ? layout(layoutArgs) : layoutArgs.children;
+
+	return (
+		<ScreenTransitionsAdapterProvider value={adapterContextValue}>
+			<StackProvider value={stackContextValue}>
+				{transitionState.shouldShowFloatOverlay ? <Overlay.Float /> : null}
+				{children}
+			</StackProvider>
+		</ScreenTransitionsAdapterProvider>
+	);
+}
+
+export const ScreenTransitionsStackLayout = withStackCore(
+	{ TRANSITIONS_ALWAYS_ON: false, STACK_TYPE: StackType.NATIVE },
+	ScreenTransitionsStackContent,
+);
+
+export function ScreenTransitionsScreenLayout({
+	screenLayout,
+	screenLayoutArgs,
+}: {
+	screenLayout?: ScreenLayout;
+	screenLayoutArgs: ScreenLayoutArgs;
+}) {
+	const { routeIndexByKey, scenes } = useScreenTransitionsAdapterContext();
+	const sceneIndex = routeIndexByKey.get(screenLayoutArgs.route.key);
+	const children = screenLayout
+		? screenLayout(screenLayoutArgs)
+		: screenLayoutArgs.children;
+
+	if (sceneIndex === undefined) {
+		return <>{children}</>;
+	}
+
+	const scene = scenes[sceneIndex];
+
+	return (
+		<ScreenComposer
+			previous={scene.previousDescriptor}
+			current={scene.descriptor}
+			next={scene.nextDescriptor}
+		>
+			{children}
+		</ScreenComposer>
+	);
+}

package/src/shared/adapters/with-screen-transitions/types.ts

@@ -0,0 +1,28 @@
+import type { ComponentType, ReactNode } from "react";
+
+export type NavigatorLayoutArgs = {
+	state: any;
+	navigation: any;
+	descriptors: Record<string, any>;
+	children: ReactNode;
+};
+
+export type NavigatorLayout = (
+	props: NavigatorLayoutArgs,
+) => React.ReactElement;
+
+export type ScreenLayoutArgs = {
+	route: { key: string };
+	navigation: any;
+	options: any;
+	theme: any;
+	children: ReactNode;
+};
+
+export type ScreenLayout = (props: ScreenLayoutArgs) => React.ReactElement;
+
+export type NavigatorWithScreenTransitions = {
+	Navigator: ComponentType<any>;
+	Screen: unknown;
+	Group: unknown;
+};

package/src/shared/components/activity/helpers.ts

@@ -0,0 +1,8 @@
+import { IS_WEB } from "../../constants";
+import type { InactiveBehavior } from "../../types/screen.types";
+
+export type { InactiveBehavior } from "../../types/screen.types";
+
+export const DEFAULT_INACTIVE_BEHAVIOR: InactiveBehavior = IS_WEB
+	? "unmount"
+	: "detach";

package/src/shared/components/activity/index.tsx

@@ -0,0 +1,2 @@
+export { ActivityContainer } from "./variants/activity-container";
+export { ActivityScreen } from "./variants/activity-screen";

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,