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

package/src/components/screen-container/layers/backdrop.tsx

@@ -0,0 +1,152 @@
+import { type ComponentType, memo, useCallback, useMemo } from "react";
+import { Pressable, StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import { DefaultSnapSpec } from "../../../configs/specs";
+import { useNavigationHelpers } from "../../../hooks/navigation/use-navigation-helpers";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useSlotProps, useSlotStyles } from "../../../providers/screen/styles";
+import { AnimationStore } from "../../../stores/animation.store";
+import { GestureStore } from "../../../stores/gesture.store";
+import { SystemStore } from "../../../stores/system.store";
+import type {
+	BackdropBehavior,
+	ScreenBackdropComponentProps,
+} from "../../../types/screen.types";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+import { findCollapseTarget } from "../helpers/find-collapse-target";
+import { usesLayerRenderProps } from "./render-component";
+
+export const BackdropLayer = memo(function BackdropLayer({
+	backdropBehavior,
+	isBackdropActive,
+}: {
+	backdropBehavior: BackdropBehavior;
+	isBackdropActive: boolean;
+}) {
+	const { current } = useDescriptors();
+	const { dismissScreen } = useNavigationHelpers();
+
+	const BackdropComponent = current.options.backdropComponent;
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getBag(routeKey);
+	const { targetProgress, resolvedAutoSnapPoint } =
+		SystemStore.getBag(routeKey);
+
+	const AnimatedBackdropComponent = useMemo(
+		() =>
+			BackdropComponent && !usesLayerRenderProps(BackdropComponent)
+				? Animated.createAnimatedComponent(
+						BackdropComponent as ComponentType<any>,
+					)
+				: null,
+		[BackdropComponent],
+	);
+
+	const handleBackdropPress = useCallback(() => {
+		if (backdropBehavior === "dismiss") {
+			dismissScreen();
+			return;
+		}
+
+		if (backdropBehavior === "collapse") {
+			const rawSnapPoints = current.options.snapPoints;
+			const canDismiss = current.options.gestureEnabled !== false;
+
+			// No snap points → fallback to dismiss
+			if (!rawSnapPoints || rawSnapPoints.length === 0) {
+				dismissScreen();
+				return;
+			}
+
+			const gestures = GestureStore.getBag(routeKey);
+			const transitionSpec = current.options.transitionSpec;
+
+			scheduleOnUI(() => {
+				"worklet";
+				const resolvedSnaps: number[] = [];
+
+				for (let i = 0; i < rawSnapPoints.length; i++) {
+					const point = rawSnapPoints[i];
+					const resolvedPoint =
+						point === "auto" ? resolvedAutoSnapPoint.get() : point;
+
+					if (typeof resolvedPoint === "number") {
+						resolvedSnaps.push(resolvedPoint);
+					}
+				}
+
+				const { target, shouldDismiss } = findCollapseTarget(
+					animations.transitionProgress.get(),
+					resolvedSnaps,
+					canDismiss,
+				);
+
+				// If already dismissing, skip
+				if (gestures.dismissing.get()) return;
+
+				gestures.dismissing.set(shouldDismiss ? 1 : 0);
+
+				const spec = shouldDismiss
+					? transitionSpec
+					: {
+							open: transitionSpec?.expand ?? DefaultSnapSpec,
+							close: transitionSpec?.collapse ?? DefaultSnapSpec,
+						};
+
+				animateToProgress({
+					target,
+					spec,
+					animations,
+					targetProgress,
+					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
+				});
+			});
+		}
+	}, [
+		animations,
+		targetProgress,
+		resolvedAutoSnapPoint,
+		backdropBehavior,
+		current,
+		dismissScreen,
+		routeKey,
+	]);
+
+	const animatedBackdropStyle = useSlotStyles("backdrop");
+	const animatedBackdropProps = useSlotProps("backdrop");
+	const backdropPointerEvents = isBackdropActive ? "auto" : "none";
+	const backdropStyles = [
+		StyleSheet.absoluteFill,
+		animatedBackdropStyle,
+	] as ScreenBackdropComponentProps["styles"];
+	const backdropProps =
+		animatedBackdropProps as ScreenBackdropComponentProps["props"];
+
+	return (
+		<Pressable
+			style={StyleSheet.absoluteFill}
+			pointerEvents={isBackdropActive ? "auto" : "none"}
+			onPress={isBackdropActive ? handleBackdropPress : undefined}
+		>
+			{AnimatedBackdropComponent ? (
+				<AnimatedBackdropComponent
+					style={backdropStyles}
+					animatedProps={animatedBackdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : BackdropComponent ? (
+				<BackdropComponent
+					styles={backdropStyles}
+					props={backdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : (
+				<Animated.View
+					style={backdropStyles}
+					pointerEvents={backdropPointerEvents}
+				/>
+			)}
+		</Pressable>
+	);
+});

package/src/components/screen-lifecycle/hooks/helpers/reset-stores-for-screen.ts

@@ -0,0 +1,15 @@
+import { scheduleOnUI } from "react-native-worklets";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { clear } from "../../../../stores/bounds/internals/clear";
+import { GestureStore } from "../../../../stores/gesture.store";
+import { ScrollStore } from "../../../../stores/scroll.store";
+import { SystemStore } from "../../../../stores/system.store";
+
+export function resetStoresForScreen(routeKey: string) {
+	AnimationStore.clearBag(routeKey);
+	GestureStore.clearBag(routeKey);
+	ScrollStore.clearBag(routeKey);
+	SystemStore.clearBag(routeKey);
+
+	scheduleOnUI(clear, routeKey);
+}

package/src/components/screen-lifecycle/hooks/history/use-screen-history.ts

@@ -0,0 +1,90 @@
+import { useEffect } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import useStableCallback from "../../../../hooks/use-stable-callback";
+import type { BaseDescriptor } from "../../../../providers/screen/descriptors";
+import type { AnimationStoreMap } from "../../../../stores/animation.store";
+import { HistoryStore } from "../../../../stores/history.store";
+import {
+	registerMountedRoute,
+	unregisterMountedRoute,
+} from "./navigator-route-registry";
+
+function hasSnapPoints(descriptor: BaseDescriptor): boolean {
+	const snapPoints = descriptor.options?.snapPoints;
+	return Boolean(snapPoints && snapPoints.length > 0);
+}
+
+/**
+ * Check if a screen is a leaf (renders visible content) vs a navigator container.
+ * Navigator containers have nested state with routes.
+ */
+function isLeafScreen(navigation: BaseDescriptor["navigation"]): boolean {
+	const state = navigation.getState();
+	const index = state?.index ?? -1;
+	const currentRoute = state?.routes?.[index];
+	if (!currentRoute) return false;
+	return !("state" in currentRoute);
+}
+
+function shouldTrackInHistory(descriptor: BaseDescriptor): boolean {
+	return hasSnapPoints(descriptor) || isLeafScreen(descriptor.navigation);
+}
+
+/**
+ * Keeps navigator route registration and screen history in sync.
+ */
+export function useScreenHistory(
+	current: BaseDescriptor,
+	previous: BaseDescriptor | undefined,
+	animations: AnimationStoreMap,
+) {
+	const navigatorKey = current.navigation.getState()?.key ?? "";
+	const routeKey = current.route.key;
+
+	useEffect(() => {
+		registerMountedRoute(navigatorKey, routeKey);
+
+		return () => {
+			const shouldClearNavigator = unregisterMountedRoute(
+				navigatorKey,
+				routeKey,
+			);
+			if (shouldClearNavigator) {
+				HistoryStore.clearNavigator(navigatorKey);
+			}
+		};
+	}, [navigatorKey, routeKey]);
+
+	// Track history via focus listener - waits for nested navigators to initialize
+	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
+	useEffect(() => {
+		if (shouldTrackInHistory(current)) {
+			HistoryStore.focus(current, navigatorKey);
+		}
+
+		const unsubscribe = current.navigation.addListener?.("focus", () => {
+			if (shouldTrackInHistory(current)) {
+				HistoryStore.focus(current, navigatorKey);
+			}
+		});
+
+		return () => unsubscribe?.();
+	}, []);
+
+	const handleBlur = useStableCallback(() => {
+		if (previous && shouldTrackInHistory(previous)) {
+			const prevNavigatorKey = previous.navigation.getState()?.key ?? "";
+			HistoryStore.focus(previous, prevNavigatorKey);
+		}
+	});
+
+	useAnimatedReaction(
+		() => animations.closing.get(),
+		(closing, prevClosing) => {
+			if (closing && !prevClosing) {
+				scheduleOnRN(handleBlur);
+			}
+		},
+	);
+}

package/src/components/stack-view.tsx

@@ -0,0 +1,73 @@
+import { memo } from "react";
+import { ActivityContainer, ActivityScreen } from "../components/activity";
+import { PortalProvider } from "../components/boundary/portal";
+import { Overlay } from "../components/overlay";
+import { NavigationScreenProvider } from "../providers/navigation/navigation-host.provider";
+import { ScreenComposer } from "../providers/screen/screen-composer";
+import { withBlankStack } from "../providers/stack/blank-stack.provider";
+import { withStackCore } from "../providers/stack/core.provider";
+import type {
+	BlankStackDescriptor,
+	BlankStackNavigationHelpers,
+} from "../types/blank-stack.types";
+import type { BaseStackScene } from "../types/stack.types";
+
+interface BlankSceneRowProps {
+	scene: BaseStackScene<BlankStackDescriptor>;
+	paintDriverRouteKey?: string;
+}
+
+const BlankSceneRow = memo(function BlankSceneRow({
+	scene,
+	paintDriverRouteKey,
+}: BlankSceneRowProps) {
+	const descriptor = scene.descriptor;
+	const route = scene.route;
+
+	return (
+		<NavigationScreenProvider navigation={descriptor.navigation} route={route}>
+			<ActivityScreen
+				activity={descriptor.activity}
+				inactiveBehavior={descriptor.options.inactiveBehavior}
+				paintDriverRouteKey={paintDriverRouteKey}
+				hasNestedState={"state" in route}
+			>
+				<ScreenComposer
+					previous={scene.previousDescriptor}
+					current={descriptor}
+					next={scene.nextDescriptor}
+				>
+					{descriptor.render?.()}
+				</ScreenComposer>
+			</ActivityScreen>
+		</NavigationScreenProvider>
+	);
+});
+
+export const StackView = withStackCore(
+	{ TRANSITIONS_ALWAYS_ON: true, DISABLE_NATIVE_SCREENS: false },
+	withBlankStack<BlankStackDescriptor, BlankStackNavigationHelpers>(
+		({ scenes, shouldShowFloatOverlay }) => {
+			return (
+				<PortalProvider>
+					{shouldShowFloatOverlay ? <Overlay.Float /> : null}
+
+					<ActivityContainer>
+						{scenes.map((scene, index) => {
+							const route = scene.route;
+							const paintDriverRouteKey = scenes[index + 2]?.route.key;
+
+							return (
+								<BlankSceneRow
+									key={route.key}
+									scene={scene}
+									paintDriverRouteKey={paintDriverRouteKey}
+								/>
+							);
+						})}
+					</ActivityContainer>
+				</PortalProvider>
+			);
+		},
+	),
+);

package/src/configs/index.ts

@@ -0,0 +1,29 @@
+import {
+	DraggableCard,
+	ElasticCard,
+	SharedAppleMusic,
+	SharedIGImage,
+	SharedXImage,
+	SlideFromBottom,
+	SlideFromTop,
+	ZoomIn,
+} from "./presets";
+import { DefaultSnapSpec, DefaultSpec, FlingSpec, Zoom } from "./specs";
+
+export const Specs = {
+	DefaultSpec,
+	DefaultSnapSpec,
+	FlingSpec,
+	Zoom,
+};
+
+export const Presets = {
+	SlideFromTop,
+	ZoomIn,
+	SlideFromBottom,
+	DraggableCard,
+	ElasticCard,
+	SharedIGImage,
+	SharedAppleMusic,
+	SharedXImage,
+};

package/src/configs/specs.ts

@@ -0,0 +1,47 @@
+import type { WithSpringConfig } from "react-native-reanimated";
+import type { TransitionSpec } from "../types/animation.types";
+
+export const DefaultSpec: WithSpringConfig = {
+	stiffness: 1000,
+	damping: 500,
+	mass: 3,
+	overshootClamping: false,
+	// @ts-expect-error Reanimated v3 spring config support.
+	restSpeedThreshold: 0.02,
+};
+
+export const DefaultSnapSpec: WithSpringConfig = {
+	stiffness: 500,
+	damping: 50,
+	mass: 1,
+};
+
+export const FlingSpec: WithSpringConfig = {
+	damping: 23.5,
+	stiffness: 170,
+	mass: 1,
+	overshootClamping: false,
+	energyThreshold: 6e-9,
+};
+
+/**
+ * Paired spring configuration tuned for navigation zoom transitions.
+ */
+export const Zoom = {
+	open: {
+		stiffness: 1000,
+		damping: 500,
+		mass: 3,
+		overshootClamping: false,
+		// @ts-expect-error Reanimated v3 spring config support.
+		restSpeedThreshold: 0.02,
+	},
+	close: {
+		stiffness: 1100,
+		damping: 98,
+		mass: 3,
+		overshootClamping: false,
+		// @ts-expect-error Reanimated v3 spring config support.
+		restSpeedThreshold: 0.02,
+	},
+} satisfies TransitionSpec;

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

@@ -0,0 +1,35 @@
+import { useCallback } from "react";
+import { useDescriptorsStore } from "../../providers/screen/descriptors";
+import { useStack } from "./use-stack";
+
+const createPopAction = () => ({
+	type: "POP",
+	payload: { count: 1 },
+});
+
+export function useNavigationHelpers() {
+	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();
+		const routeIndex = state.routes.findIndex(
+			(route) => route.key === current.route.key,
+		);
+		const routeStillPresent = routeIndex !== -1;
+		if (!routeStillPresent || routeIndex === 0) return false;
+
+		current.navigation.dispatch({
+			...createPopAction(),
+			source: current.route.key,
+			target: state.key,
+		});
+		return true;
+	}, [current]);
+
+	return { dismissScreen, requestDismiss };
+}

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

@@ -0,0 +1,36 @@
+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.defaultPrevented) {
+						// When user taps on already focused tab and we're inside the tab,
+						// reset the stack to replicate native behaviour
+						navigation.dispatch({
+							type: "POP_TO_TOP",
+							target: stateKey,
+						});
+					}
+				});
+			}),
+		[navigation, stateIndex, stateKey],
+	);
+}

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

@@ -0,0 +1,39 @@
+import { useCallback, useRef } from "react";
+import { type SharedValue, useAnimatedReaction } from "react-native-reanimated";
+import { executeOnUIRuntimeSync, scheduleOnRN } from "react-native-worklets";
+import { IS_WEB } from "../../constants";
+
+export function readInitialValue<T>(sharedValue: SharedValue<T>): T {
+	if (IS_WEB) {
+		return sharedValue.get();
+	}
+	const readOnUI = executeOnUIRuntimeSync((sv: SharedValue<T>) => {
+		"worklet";
+		return sv.get();
+	});
+	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.get(),
+		(value, previousValue) => {
+			if (Object.is(value, previousValue)) return;
+			scheduleOnRN(updateRef, value);
+		},
+	);
+
+	return ref;
+}

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

@@ -0,0 +1,22 @@
+import { useState } from "react";
+import { type SharedValue, useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+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>(() => readInitialValue(sharedValue));
+
+	useAnimatedReaction(
+		() => sharedValue.get(),
+		(value, previousValue) => {
+			if (Object.is(value, previousValue)) return;
+			scheduleOnRN(setState, value);
+		},
+	);
+
+	return state;
+}

package/src/hooks/use-stable-callback-value.ts

@@ -0,0 +1,72 @@
+/**
+ * Credit:
+ * https://github.com/MatiPl01/react-native-sortables/blob/main/packages/react-native-sortables/src/integrations/reanimated/hooks/useStableCallbackValue.ts
+ */
+import { useCallback, useEffect, useState } from "react";
+import { cancelAnimation, makeMutable } from "react-native-reanimated";
+import { isWorkletFunction, scheduleOnRN } from "react-native-worklets";
+
+type AnyFunction = (...args: Array<any>) => any;
+
+function useMutableValue<T>(initialValue: T) {
+	const [mutable] = useState(() => makeMutable(initialValue));
+
+	useEffect(() => {
+		return () => {
+			cancelAnimation(mutable);
+		};
+	}, [mutable]);
+
+	return mutable;
+}
+
+// We cannot store a function as a SharedValue because reanimated will treat
+// it as an animation and will try to execute the animation when assigned
+// to the SharedValue. Since we want the function to be treated as a value,
+// we wrap it in an object and store the object in the SharedValue.
+type WrappedCallback<C extends AnyFunction> = {
+	call: C;
+};
+
+const wrap = <C extends AnyFunction>(callback: C): WrappedCallback<C> => {
+	if (isWorkletFunction(callback)) {
+		return { call: callback };
+	}
+	return {
+		call: ((...args: Parameters<C>) => {
+			"worklet";
+			scheduleOnRN(callback, ...args);
+		}) as C,
+	};
+};
+
+/** Creates a stable worklet callback that can be called from the UI runtime
+ * @param callback The JavaScript or worklet function to be called
+ * @returns A worklet function that can be safely called from the UI thread
+ * @default Behavior:
+ * - If passed a regular JS function, schedules it on the JS thread
+ * - If passed a worklet function, calls it directly on the UI thread
+ * @important The returned function maintains a stable reference and properly handles
+ * thread execution based on the input callback type
+ */
+export default function useStableCallbackValue<C extends AnyFunction>(
+	callback?: C,
+) {
+	const stableCallback = useMutableValue<null | WrappedCallback<C>>(null);
+
+	useEffect(() => {
+		if (callback) {
+			stableCallback.set(wrap(callback));
+		} else {
+			stableCallback.set(null);
+		}
+	}, [callback, stableCallback]);
+
+	return useCallback(
+		(...args: Parameters<C>) => {
+			"worklet";
+			stableCallback.get()?.call(...args);
+		},
+		[stableCallback],
+	);
+}