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

package/src/native-stack/types.ts

@@ -50,6 +50,11 @@ export type NativeStackNavigationEventMap = {
 	sheetDetentChange: { data: { index: number; stable: boolean } };
 };
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `@react-navigation/native-stack` or Expo Router's native stack with
+ * `withScreenTransitions` from `react-native-screen-transitions` instead.
+ */
 export type NativeStackNavigationProp<
 	ParamList extends ParamListBase,
 	RouteName extends keyof ParamList = string,
@@ -64,6 +69,11 @@ export type NativeStackNavigationProp<
 > &
 	StackActionHelpers<ParamList>;
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `@react-navigation/native-stack` or Expo Router's native stack with
+ * `withScreenTransitions` from `react-native-screen-transitions` instead.
+ */
 export type NativeStackScreenProps<
 	ParamList extends ParamListBase,
 	RouteName extends keyof ParamList = string,
@@ -148,6 +158,11 @@ export type NativeStackOverlayProps = OverlayProps<
 	NativeStackNavigationProp<ParamListBase>
 >;
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `NativeStackAdapterOptions` with `withScreenTransitions` from
+ * `react-native-screen-transitions` instead.
+ */
 export type NativeStackScreenTransitionConfig = ScreenTransitionConfig & {
 	/**
 	 * Whether to enable transitions. It sets the presentation to containedTransparentModal, animation none, and headerShown to false.
@@ -155,6 +170,11 @@ export type NativeStackScreenTransitionConfig = ScreenTransitionConfig & {
 	enableTransitions?: boolean;
 };
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `NativeStackAdapterOptions<NativeStackNavigationOptions>` with
+ * `@react-navigation/native-stack` and `withScreenTransitions` instead.
+ */
 export type NativeStackNavigationOptions = NativeStackScreenTransitionConfig & {
 	/**
 	 * String that can be displayed in the header as a fallback for `headerTitle`.
@@ -701,6 +721,11 @@ export type NativeStackNavigationOptions = NativeStackScreenTransitionConfig & {
 	unstable_sheetFooter?: () => React.ReactNode;
 };
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `@react-navigation/native-stack` or Expo Router's native stack with
+ * `withScreenTransitions` from `react-native-screen-transitions` instead.
+ */
 export type NativeStackNavigatorProps = DefaultNavigatorOptions<
 	ParamListBase,
 	string | undefined,

package/src/shared/adapters/with-screen-transitions/context.tsx

@@ -0,0 +1,42 @@
+import { createContext, useContext } from "react";
+import type { BaseStackDescriptor, BaseStackScene } from "../../types";
+
+export type ScreenTransitionsAdapterScene =
+	BaseStackScene<BaseStackDescriptor> & {
+		previousDescriptor?: BaseStackDescriptor;
+		nextDescriptor?: BaseStackDescriptor;
+	};
+
+export interface ScreenTransitionsAdapterContextValue {
+	routeIndexByKey: ReadonlyMap<string, number>;
+	scenes: ScreenTransitionsAdapterScene[];
+}
+
+const ScreenTransitionsAdapterContext =
+	createContext<ScreenTransitionsAdapterContextValue | null>(null);
+
+ScreenTransitionsAdapterContext.displayName = "ScreenTransitionsAdapter";
+
+export function ScreenTransitionsAdapterProvider({
+	children,
+	value,
+}: {
+	children: React.ReactNode;
+	value: ScreenTransitionsAdapterContextValue;
+}) {
+	return (
+		<ScreenTransitionsAdapterContext.Provider value={value}>
+			{children}
+		</ScreenTransitionsAdapterContext.Provider>
+	);
+}
+
+export function useScreenTransitionsAdapterContext() {
+	const context = useContext(ScreenTransitionsAdapterContext);
+	if (!context) {
+		throw new Error(
+			"useScreenTransitionsAdapterContext must be used within withScreenTransitions",
+		);
+	}
+	return context;
+}

package/src/shared/adapters/with-screen-transitions/index.tsx

@@ -0,0 +1,155 @@
+import type {
+	NavigatorTypeBagBase,
+	TypedNavigator,
+} from "@react-navigation/native";
+import type { ComponentType, ReactNode } from "react";
+import {
+	Children,
+	cloneElement,
+	forwardRef,
+	isValidElement,
+	useCallback,
+	useMemo,
+} from "react";
+import type {
+	NativeStackAdapterOptionInput,
+	NativeStackAdapterOptions,
+} from "./options";
+import { adaptNativeStackTransitionOptions } from "./options";
+import {
+	ScreenTransitionsScreenLayout,
+	ScreenTransitionsStackLayout,
+} from "./stack-layout";
+import type {
+	NavigatorLayout,
+	NavigatorLayoutArgs,
+	NavigatorWithScreenTransitions,
+	ScreenLayout,
+	ScreenLayoutArgs,
+} from "./types";
+
+export type {
+	NativeStackAdapterOptions,
+	NativeStackNativeGestureOptions,
+	ScreenTransitionDescriptorOptions,
+} from "./options";
+export { resolveScreenTransitionOptions } from "./options";
+
+type ScreenTransitionsNavigatorProps = {
+	layout?: NavigatorLayout;
+	screenLayout?: ScreenLayout;
+	[key: string]: any;
+};
+
+type ScreenTransitionsNavigatorTypeBag<TBag extends NavigatorTypeBagBase> =
+	Omit<TBag, "ScreenOptions"> & {
+		ScreenOptions: NativeStackAdapterOptions<TBag["ScreenOptions"]>;
+	};
+
+function adaptNavigatorChildren(children: ReactNode): ReactNode {
+	return Children.map(children, (child) => {
+		if (!isValidElement(child)) {
+			return child;
+		}
+
+		const props = child.props as Record<string, unknown>;
+		const nextProps: Record<string, unknown> = {};
+		let changed = false;
+
+		if ("options" in props) {
+			nextProps.options = adaptNativeStackTransitionOptions(
+				props.options as NativeStackAdapterOptionInput | undefined,
+			);
+			changed = true;
+		}
+
+		if ("screenOptions" in props) {
+			nextProps.screenOptions = adaptNativeStackTransitionOptions(
+				props.screenOptions as NativeStackAdapterOptionInput | undefined,
+			);
+			changed = true;
+		}
+
+		if (props.children !== undefined && typeof props.children !== "function") {
+			nextProps.children = adaptNavigatorChildren(props.children as ReactNode);
+			changed = true;
+		}
+
+		if (!changed) {
+			return child;
+		}
+
+		return cloneElement(child, nextProps);
+	});
+}
+
+export function withScreenTransitions<
+	TBag extends NavigatorTypeBagBase,
+	TConfig,
+>(
+	navigator: TypedNavigator<TBag, TConfig>,
+): TypedNavigator<ScreenTransitionsNavigatorTypeBag<TBag>, TConfig>;
+export function withScreenTransitions<
+	TNavigator extends NavigatorWithScreenTransitions,
+>(navigator: TNavigator): TNavigator;
+export function withScreenTransitions(
+	navigator: NavigatorWithScreenTransitions,
+): any {
+	const BaseNavigator = navigator.Navigator as ComponentType<any>;
+
+	const Navigator = forwardRef<unknown, ScreenTransitionsNavigatorProps>(
+		function ScreenTransitionsNavigator(
+			{ layout, screenLayout, ...props },
+			ref,
+		) {
+			const transitionLayout = useCallback(
+				(layoutArgs: NavigatorLayoutArgs) => (
+					<ScreenTransitionsStackLayout
+						layout={layout}
+						layoutArgs={layoutArgs}
+					/>
+				),
+				[layout],
+			);
+
+			const transitionScreenLayout = useCallback(
+				(screenLayoutArgs: ScreenLayoutArgs) => (
+					<ScreenTransitionsScreenLayout
+						screenLayout={screenLayout}
+						screenLayoutArgs={screenLayoutArgs}
+					/>
+				),
+				[screenLayout],
+			);
+			const screenOptions = useMemo(
+				() => adaptNativeStackTransitionOptions(props.screenOptions),
+				[props.screenOptions],
+			);
+			const children = useMemo(
+				() => adaptNavigatorChildren(props.children),
+				[props.children],
+			);
+
+			return (
+				<BaseNavigator
+					{...props}
+					screenOptions={screenOptions}
+					ref={ref as never}
+					layout={transitionLayout}
+					screenLayout={transitionScreenLayout}
+				>
+					{children}
+				</BaseNavigator>
+			);
+		},
+	);
+
+	Navigator.displayName = `withScreenTransitions(${
+		BaseNavigator.displayName ?? BaseNavigator.name ?? "Navigator"
+	})`;
+
+	return {
+		...navigator,
+		Navigator,
+	};
+}

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";