react-native-screen-transitions 3.9.0 → 4.0.0-alpha.0

package/src/providers/screen/gestures/pinch/behavior/pinch-lifecycle.ts

@@ -0,0 +1,113 @@
+import { clamp } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { EPSILON, FALSE, TRUE } from "../../../../../constants";
+import { animateToProgress } from "../../../../../utils/animation/animate-to-progress";
+import { emit } from "../../../../../utils/animation/emit";
+import { normalizePinchScale } from "../../shared/physics";
+import { snapshotGestureHandoff } from "../../shared/snapshot";
+import { clearTransformTrackingValues } from "../../shared/values";
+import type {
+	PinchGestureEvent,
+	PinchGestureRuntime,
+	PinchReleaseResult,
+	PinchTrackState,
+} from "../../types";
+import { resetPinchGestureValues } from "./pinch-reset";
+
+export const startPinchBase = (runtime: PinchGestureRuntime) => {
+	"worklet";
+	const {
+		stores: { gestures, animations },
+	} = runtime;
+
+	const wasSettling = gestures.settling.get();
+	const hasResidualGesture =
+		Math.abs(gestures.normScale.get()) > EPSILON ||
+		Math.abs(gestures.rotation.get()) > EPSILON;
+
+	if (!wasSettling || !hasResidualGesture) {
+		emit(animations.willAnimate, TRUE, FALSE);
+	}
+
+	gestures.dragging.set(TRUE);
+	gestures.dismissing.set(0);
+	gestures.settling.set(0);
+	gestures.active.set(null);
+	gestures.direction.set(null);
+	gestures.velocity.set(0);
+	clearTransformTrackingValues(gestures);
+	gestures.internal.progressBaseline.set(animations.transitionProgress.get());
+};
+
+export const trackPinchGesture = (
+	event: PinchGestureEvent,
+	rawEvent: PinchGestureEvent,
+	gestures: PinchGestureRuntime["stores"]["gestures"],
+): PinchTrackState => {
+	"worklet";
+	const normScale = clamp(normalizePinchScale(event.scale), -1, 1);
+	const scale = clamp(1 + normScale, 0, 2);
+	const rawNormScale = clamp(normalizePinchScale(rawEvent.scale), -1, 1);
+	const rawScale = clamp(1 + rawNormScale, 0, 2);
+
+	gestures.scale.set(scale);
+	gestures.normScale.set(normScale);
+	gestures.raw.scale.set(rawScale);
+	gestures.raw.normScale.set(rawNormScale);
+
+	if (gestures.active.get() === null) {
+		gestures.active.set(
+			normScale < 0 ? "pinch-in" : normScale > 0 ? "pinch-out" : null,
+		);
+	}
+
+	return {
+		scale,
+		normScale,
+	};
+};
+
+export const finalizePinchRelease = (
+	release: PinchReleaseResult,
+	runtime: PinchGestureRuntime,
+	dismissScreen: ((finished: boolean) => void) | undefined,
+	requestDismiss?: () => void,
+) => {
+	"worklet";
+	const {
+		stores: { gestures, animations, system },
+	} = runtime;
+
+	if (typeof release.commitProgress === "number") {
+		animations.transitionProgress.set(release.commitProgress);
+		system.targetProgress.set(release.commitProgress);
+	}
+
+	if (release.shouldDismiss) {
+		snapshotGestureHandoff(gestures, {
+			velocity: release.handoffVelocity,
+		});
+	}
+
+	resetPinchGestureValues({
+		spec: release.resetSpec,
+		gestures,
+		shouldDismiss: release.shouldDismiss,
+		resetValuesImmediately: release.resetValuesImmediately,
+	});
+
+	if (release.shouldDismiss && requestDismiss) {
+		scheduleOnRN(requestDismiss);
+	}
+
+	animateToProgress({
+		target: release.target,
+		onAnimationFinish: release.shouldDismiss ? dismissScreen : undefined,
+		spec: release.transitionSpec,
+		emitWillAnimate: false,
+		markEntering: false,
+		animations,
+		targetProgress: system.targetProgress,
+		initialVelocity: release.initialVelocity,
+	});
+};

package/src/providers/stack/blank-stack-state/blank-stack-controller.ts

@@ -0,0 +1,166 @@
+import type { BlankStackProviderProps } from "../../../types/providers/blank-stack-provider.types";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+} from "../../../types/stack.types";
+import { buildBlankStackState } from "./helpers/build-blank-stack-state";
+import { deriveBlankStackState } from "./helpers/derive-blank-stack-state";
+import type {
+	BlankStackControllerSnapshot,
+	BlankStackController as BlankStackControllerType,
+	BlankStackDescriptorSources,
+} from "./helpers/types";
+
+export type { BlankStackController } from "./helpers/types";
+
+const createPopAction = () => ({
+	type: "POP",
+	payload: { count: 1 },
+});
+
+/**
+ * Maintains the stack-local route snapshot used while blank stack transitions run.
+ *
+ * React Navigation remains the source of truth for settled routes, but it can
+ * remove descriptors before our close animation has finished. This controller
+ * keeps those closing routes locally until their lifecycle reports completion.
+ */
+export const createBlankStackController = <
+	TDescriptor extends BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation,
+>(
+	initialProps: BlankStackProviderProps<TDescriptor, TNavigation>,
+): BlankStackControllerType<TDescriptor, TNavigation> => {
+	const closingRouteKeys = new Set<string>();
+	let props = initialProps;
+	let previousRoutesSnapshot = initialProps.state.routes;
+	let snapshot: BlankStackControllerSnapshot<TDescriptor> = {
+		state: buildBlankStackState({
+			props,
+			routes: initialProps.state.routes,
+			descriptors:
+				initialProps.descriptors as BlankStackDescriptorSources<TDescriptor>,
+			closingRouteKeys,
+		}),
+	};
+	const listeners = new Set<() => void>();
+
+	const emit = () => {
+		for (const listener of listeners) {
+			listener();
+		}
+	};
+
+	const subscribe = (listener: () => void) => {
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	};
+
+	const getSnapshot = (): BlankStackControllerSnapshot<TDescriptor> => {
+		return snapshot;
+	};
+
+	const update = (
+		nextProps: BlankStackProviderProps<TDescriptor, TNavigation>,
+	) => {
+		const lastRoutesSnapshot = previousRoutesSnapshot;
+		props = nextProps;
+
+		const nextState = deriveBlankStackState({
+			props,
+			current: snapshot.state,
+			previousRoutesSnapshot: lastRoutesSnapshot,
+			closingRouteKeys,
+		});
+		previousRoutesSnapshot = nextProps.state.routes;
+
+		if (nextState === snapshot.state) {
+			return;
+		}
+
+		snapshot = {
+			state: nextState,
+		};
+	};
+
+	const handleCloseRoute = ({ route }: { route: BaseStackRoute }) => {
+		const { state, navigation } = props;
+
+		if (state.routes.some((candidate) => candidate.key === route.key)) {
+			navigation.dispatch({
+				...createPopAction(),
+				source: route.key,
+				target: state.key,
+			});
+			return;
+		}
+
+		closingRouteKeys.delete(route.key);
+
+		const current = snapshot.state;
+		const routeExists = current.routes.some(
+			(candidate) => candidate.key === route.key,
+		);
+
+		if (!routeExists) {
+			return;
+		}
+
+		const nextRoutes = current.routes.filter(
+			(candidate) => candidate.key !== route.key,
+		);
+
+		const nextDescriptors = { ...current.sourceDescriptors };
+		delete nextDescriptors[route.key];
+
+		snapshot = {
+			state: buildBlankStackState({
+				props,
+				routes: nextRoutes,
+				descriptors: nextDescriptors,
+				closingRouteKeys,
+				previousState: current,
+			}),
+		};
+		emit();
+	};
+
+	const requestDismiss = ({ route }: { route: BaseStackRoute }): boolean => {
+		const current = snapshot.state;
+		const routeIndex = current.routes.findIndex(
+			(candidate) => candidate.key === route.key,
+		);
+
+		if (routeIndex <= 0) {
+			return false;
+		}
+
+		if (closingRouteKeys.has(route.key)) {
+			return true;
+		}
+
+		closingRouteKeys.add(route.key);
+		snapshot = {
+			state: buildBlankStackState({
+				props,
+				routes: current.routes,
+				descriptors: current.sourceDescriptors,
+				closingRouteKeys,
+				previousState: current,
+			}),
+		};
+		emit();
+		return true;
+	};
+
+	return {
+		subscribe,
+		getSnapshot,
+		update,
+		handleCloseRoute,
+		requestDismiss,
+	};
+};

package/src/providers/stack/core.provider.tsx

@@ -0,0 +1,141 @@
+import * as React from "react";
+import { useMemo } from "react";
+import { Dimensions, Platform, StyleSheet, View } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import {
+	initialWindowMetrics,
+	SafeAreaInsetsContext,
+	SafeAreaProvider,
+} from "react-native-safe-area-context";
+import { StackType } from "../../types/stack.types";
+import createProvider from "../../utils/create-provider";
+
+export interface StackCoreConfig {
+	TRANSITIONS_ALWAYS_ON?: boolean;
+	STACK_TYPE?: StackType;
+	DISABLE_NATIVE_SCREENS?: boolean;
+	DISABLE_NATIVE_SCREEN_CONTAINER?: boolean;
+}
+
+interface StackCoreProviderProps {
+	config: StackCoreConfig;
+	children: React.ReactNode;
+}
+
+export interface StackCoreContextValue {
+	flags: {
+		TRANSITIONS_ALWAYS_ON: boolean;
+		STACK_TYPE?: StackType;
+		DISABLE_NATIVE_SCREENS: boolean;
+		DISABLE_NATIVE_SCREEN_CONTAINER: boolean;
+	};
+}
+
+const { width = 0, height = 0 } = Dimensions.get("window");
+
+const initialSafeAreaMetrics =
+	Platform.OS === "web" || initialWindowMetrics == null
+		? {
+				frame: { x: 0, y: 0, width, height },
+				insets: { top: 0, left: 0, right: 0, bottom: 0 },
+			}
+		: initialWindowMetrics;
+
+function StackSafeAreaProvider({ children }: { children: React.ReactNode }) {
+	const insets = React.useContext(SafeAreaInsetsContext);
+
+	if (insets) {
+		return <View style={styles.container}>{children}</View>;
+	}
+
+	return (
+		<SafeAreaProvider
+			initialMetrics={initialSafeAreaMetrics}
+			style={styles.container}
+		>
+			{children}
+		</SafeAreaProvider>
+	);
+}
+
+const { StackCoreProvider: InternalStackCoreProvider, useStackCoreContext } =
+	createProvider("StackCore", { guarded: true })<
+		StackCoreProviderProps,
+		StackCoreContextValue
+	>(({ config, children }) => {
+		const {
+			TRANSITIONS_ALWAYS_ON = false,
+			DISABLE_NATIVE_SCREENS = false,
+			DISABLE_NATIVE_SCREEN_CONTAINER = false,
+			STACK_TYPE = StackType.BLANK,
+		} = config;
+
+		const flags = useMemo(
+			() => ({
+				TRANSITIONS_ALWAYS_ON,
+				STACK_TYPE,
+				DISABLE_NATIVE_SCREENS,
+				DISABLE_NATIVE_SCREEN_CONTAINER,
+			}),
+			[
+				TRANSITIONS_ALWAYS_ON,
+				STACK_TYPE,
+				DISABLE_NATIVE_SCREENS,
+				DISABLE_NATIVE_SCREEN_CONTAINER,
+			],
+		);
+
+		return {
+			value: { flags },
+			children: (
+				<GestureHandlerRootView
+					style={styles.container}
+					pointerEvents={
+						STACK_TYPE === StackType.COMPONENT ? "box-none" : undefined
+					}
+				>
+					<StackSafeAreaProvider>{children}</StackSafeAreaProvider>
+				</GestureHandlerRootView>
+			),
+		};
+	});
+
+/**
+ * HOC that wraps a component with the StackCore provider.
+ * Just a simple open gate
+ */
+export function withStackCore<TProps extends object>(
+	defaultConfig: StackCoreConfig,
+	Component: React.ComponentType<TProps>,
+): React.FC<TProps & StackCoreConfig> {
+	return function StackCoreWrapper({
+		DISABLE_NATIVE_SCREENS,
+		DISABLE_NATIVE_SCREEN_CONTAINER,
+		TRANSITIONS_ALWAYS_ON,
+		STACK_TYPE,
+		...props
+	}: TProps & StackCoreConfig) {
+		// Start from defaults, then apply explicit overrides from the caller.
+		const config: StackCoreConfig = {
+			TRANSITIONS_ALWAYS_ON:
+				TRANSITIONS_ALWAYS_ON ?? defaultConfig.TRANSITIONS_ALWAYS_ON,
+			STACK_TYPE: STACK_TYPE ?? defaultConfig.STACK_TYPE,
+			DISABLE_NATIVE_SCREENS:
+				DISABLE_NATIVE_SCREENS ?? defaultConfig.DISABLE_NATIVE_SCREENS,
+			DISABLE_NATIVE_SCREEN_CONTAINER:
+				DISABLE_NATIVE_SCREEN_CONTAINER ??
+				defaultConfig.DISABLE_NATIVE_SCREEN_CONTAINER,
+		};
+		return (
+			<InternalStackCoreProvider config={config}>
+				<Component {...(props as TProps)} />
+			</InternalStackCoreProvider>
+		);
+	};
+}
+
+const styles = StyleSheet.create({
+	container: { flex: 1 },
+});
+
+export { useStackCoreContext };

package/src/providers/stack/direct.provider.tsx

@@ -0,0 +1,129 @@
+import type * as React from "react";
+import { useMemo } from "react";
+import {
+	type StackContextValue,
+	StackProvider,
+} from "../../hooks/navigation/use-stack";
+import type {
+	DirectStackContextValue,
+	DirectStackDescriptorMap,
+	DirectStackProps,
+	DirectStackScene,
+} from "../../types/providers/direct-stack.types";
+import { isOverlayVisible } from "../../utils/overlay/visibility";
+import { useStackCoreContext } from "./core.provider";
+
+function useDirectStackValue(
+	props: DirectStackProps,
+): DirectStackContextValue & { stackContextValue: StackContextValue } {
+	const { state, navigation, descriptors, describe } = props;
+	const { flags } = useStackCoreContext();
+	const navigatorKey = state.key;
+
+	const preloadedDescriptors = useMemo(() => {
+		return state.preloadedRoutes.reduce<DirectStackDescriptorMap>(
+			(acc, route) => {
+				acc[route.key] = acc[route.key] || describe(route, true);
+				return acc;
+			},
+			{},
+		);
+	}, [state.preloadedRoutes, describe]);
+
+	const { scenes, shouldShowFloatOverlay, routeKeys, allRoutes } =
+		useMemo(() => {
+			const allRoutes = state.routes.concat(state.preloadedRoutes);
+			const scenes: DirectStackScene[] = [];
+			const routeKeys: string[] = [];
+			const allDescriptors: DirectStackDescriptorMap = {
+				...preloadedDescriptors,
+				...descriptors,
+			};
+			let shouldShowFloatOverlay = false;
+
+			for (const route of allRoutes) {
+				const descriptor = allDescriptors[route.key];
+				const isPreloaded =
+					preloadedDescriptors[route.key] !== undefined &&
+					descriptors[route.key] === undefined;
+
+				scenes.push({ route, descriptor, isPreloaded });
+				routeKeys.push(route.key);
+
+				if (!shouldShowFloatOverlay && descriptor) {
+					const options = descriptor.options;
+					if (
+						options?.enableTransitions === true &&
+						isOverlayVisible(options)
+					) {
+						shouldShowFloatOverlay = true;
+					}
+				}
+			}
+
+			return {
+				scenes,
+				shouldShowFloatOverlay,
+				routeKeys,
+				allRoutes,
+			};
+		}, [
+			state.routes,
+			state.preloadedRoutes,
+			preloadedDescriptors,
+			descriptors,
+		]);
+
+	const focusedIndex = state.index;
+
+	const stackContextValue = useMemo<StackContextValue>(
+		() => ({
+			flags,
+			navigatorKey,
+			routeKeys,
+			routes: allRoutes,
+			scenes,
+			focusedIndex,
+		}),
+		[flags, navigatorKey, routeKeys, allRoutes, scenes, focusedIndex],
+	);
+
+	// DirectStack context value
+	const lifecycleValue = useMemo<DirectStackContextValue>(
+		() => ({
+			state,
+			navigation,
+			descriptors,
+			scenes,
+			focusedIndex,
+			shouldShowFloatOverlay,
+		}),
+		[
+			state,
+			navigation,
+			descriptors,
+			scenes,
+			focusedIndex,
+			shouldShowFloatOverlay,
+		],
+	);
+
+	return { ...lifecycleValue, stackContextValue };
+}
+
+function withDirectStack<TProps extends DirectStackProps>(
+	Component: React.ComponentType<DirectStackContextValue>,
+): React.FC<TProps> {
+	return function DirectStackProvider(props: TProps) {
+		const { stackContextValue, ...lifecycleValue } = useDirectStackValue(props);
+
+		return (
+			<StackProvider value={stackContextValue}>
+				<Component {...lifecycleValue} />
+			</StackProvider>
+		);
+	};
+}
+
+export type { DirectStackContextValue, DirectStackProps, DirectStackScene };
+export { withDirectStack };

package/src/types/blank-stack.types.ts

@@ -0,0 +1,146 @@
+import type {
+	DefaultNavigatorOptions,
+	Descriptor,
+	NavigationHelpers,
+	NavigationProp,
+	ParamListBase,
+	RouteProp,
+	StackActionHelpers,
+	StackNavigationState,
+	StackRouterOptions,
+	Theme,
+} from "@react-navigation/native";
+import type { OverlayProps } from "./overlay.types";
+import type { InactiveBehavior, ScreenTransitionConfig } from "./screen.types";
+import type { StackSceneActivity } from "./stack.types";
+
+export type { InactiveBehavior } from "./screen.types";
+
+export type BlankStackNavigationEventMap = {};
+
+export type BlankStackNavigationProp<
+	ParamList extends ParamListBase,
+	RouteName extends keyof ParamList = string,
+	NavigatorID extends string | undefined = undefined,
+> = NavigationProp<
+	ParamList,
+	RouteName,
+	NavigatorID,
+	StackNavigationState<ParamList>,
+	BlankStackNavigationOptions,
+	BlankStackNavigationEventMap
+> &
+	StackActionHelpers<ParamList>;
+
+export type BlankStackScreenProps<
+	ParamList extends ParamListBase,
+	RouteName extends keyof ParamList = string,
+	NavigatorID extends string | undefined = undefined,
+> = {
+	navigation: BlankStackNavigationProp<ParamList, RouteName, NavigatorID>;
+	route: RouteProp<ParamList, RouteName>;
+};
+
+export type BlankStackOptionsArgs<
+	ParamList extends ParamListBase,
+	RouteName extends keyof ParamList = keyof ParamList,
+	NavigatorID extends string | undefined = undefined,
+> = BlankStackScreenProps<ParamList, RouteName, NavigatorID> & {
+	theme: Theme;
+};
+
+export type BlankStackNavigationHelpers = NavigationHelpers<
+	ParamListBase,
+	BlankStackNavigationEventMap
+>;
+
+/**
+ * Additional props accepted by the blank stack navigator.
+ *
+ * These can be passed to `<BlankStack.Navigator />` in the dynamic API, and
+ * they are also supported as top-level keys in static navigator config.
+ */
+export interface BlankStackFactoryOptions {
+	/**
+	 * Controls whether blank-stack screens are rendered with react-native-screens.
+	 *
+	 * When enabled, inactive presentation state is backed by
+	 * `ScreenContainer`/`Screen.activityState`. Set this to `false` to render
+	 * screens as regular React Native views.
+	 *
+	 * @default true
+	 */
+	nativeScreens?: boolean;
+
+	/**
+	 * Enables react-native-screens for blank-stack screen retention.
+	 *
+	 * @deprecated Use `nativeScreens` instead.
+	 */
+	enableNativeScreens?: boolean;
+
+	/**
+	 * Creates an isolated navigation tree for embedded flows.
+	 *
+	 * Use this when the blank stack needs to live inside another screen or host
+	 * application without joining the parent React Navigation tree.
+	 *
+	 * When enabled, the navigator:
+	 * - wraps itself in `NavigationIndependentTree` + `NavigationContainer`
+	 *
+	 * Leave this disabled for normal top-level app stacks.
+	 */
+	independent?: boolean;
+}
+
+/**
+ * Props passed to overlay components in blank-stack.
+ * Uses the shared OverlayProps type with blank-stack's navigation type.
+ */
+export type BlankStackOverlayProps = OverlayProps<
+	BlankStackNavigationProp<ParamListBase>
+>;
+
+export type BlankStackNavigationOptions = ScreenTransitionConfig & {
+	/**
+	 * Controls how inactive blank-stack screens are retained after they are no
+	 * longer active.
+	 *
+	 * For a stack shaped as A(inactive), B(inert), C(active):
+	 *
+	 * - `hide`: keeps A mounted, pauses/freezes inactive work where supported,
+	 *   and hides native/view presentation after the screen that exposes it has
+	 *   safely painted.
+	 * - `pause`: keeps A's last painted UI visible and asks the platform to stop
+	 *   or suspend inactive work where possible.
+	 * - `unmount`: removes A's React subtree after safe paint when the route has
+	 *   no nested navigation state.
+	 * - `keep`: keeps A mounted, attached, visible, non-interactive, and running.
+	 *
+	 * On web, or when native screens are disabled, `hide` and `pause` cannot
+	 * currently suspend React work. This will change once the implementation can
+	 * use React 19.2's Activity component.
+	 *
+	 * @default "hide" on native, "unmount" on web
+	 */
+	inactiveBehavior?: InactiveBehavior;
+};
+
+export type BlankStackNavigatorProps = DefaultNavigatorOptions<
+	ParamListBase,
+	string | undefined,
+	StackNavigationState<ParamListBase>,
+	BlankStackNavigationOptions,
+	BlankStackNavigationEventMap,
+	BlankStackNavigationProp<ParamListBase>
+> &
+	StackRouterOptions &
+	BlankStackFactoryOptions;
+
+export type BlankStackDescriptor = Descriptor<
+	BlankStackNavigationOptions,
+	BlankStackNavigationProp<ParamListBase>,
+	RouteProp<ParamListBase>
+> & {
+	activity: StackSceneActivity;
+};