react-native-screen-transitions 2.4.2-beta.2 → 3.0.0-beta.0

package/src/shared/providers/keys.tsx

@@ -0,0 +1,57 @@
+import type {
+	Descriptor,
+	NavigationProp,
+	ParamListBase,
+	RouteProp,
+} from "@react-navigation/native";
+import { createContext, useContext, useMemo } from "react";
+import type { ScreenTransitionConfig } from "../types/core";
+
+export type TransitionDescriptor = Descriptor<
+	ScreenTransitionConfig,
+	NavigationProp<ParamListBase>,
+	RouteProp<ParamListBase>
+>;
+
+export interface KeysContextType<
+	TDescriptor extends TransitionDescriptor = TransitionDescriptor,
+> {
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+}
+
+const KeysContext = createContext<
+	KeysContextType<TransitionDescriptor> | undefined
+>(undefined);
+
+interface KeysProviderProps<TDescriptor extends TransitionDescriptor> {
+	children: React.ReactNode;
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+}
+
+export function KeysProvider<TDescriptor extends TransitionDescriptor>({
+	children,
+	previous,
+	current,
+	next,
+}: KeysProviderProps<TDescriptor>) {
+	const value = useMemo<KeysContextType<TDescriptor>>(
+		() => ({ previous, current, next }),
+		[previous, current, next],
+	);
+
+	return <KeysContext.Provider value={value}>{children}</KeysContext.Provider>;
+}
+
+export function useKeys<
+	TDescriptor extends TransitionDescriptor = TransitionDescriptor,
+>(): KeysContextType<TDescriptor> {
+	const context = useContext(KeysContext);
+	if (context === undefined) {
+		throw new Error("useKeys must be used within a KeysProvider");
+	}
+	return context as KeysContextType<TDescriptor>;
+}

package/src/shared/providers/screen-transition-provider.tsx

@@ -0,0 +1,41 @@
+import type React from "react";
+import type { ComponentType } from "react";
+import type { ScreenLifecycleProps } from "../components/controllers/screen-lifecycle";
+import { RootTransitionAware } from "../components/root-transition-aware";
+import { ScreenGestureProvider } from "../providers/gestures";
+import { KeysProvider, type TransitionDescriptor } from "../providers/keys";
+import { TransitionStylesProvider } from "../providers/transition-styles";
+
+type Props<TDescriptor extends TransitionDescriptor> = {
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+	children: React.ReactNode;
+	LifecycleController: ComponentType<ScreenLifecycleProps>;
+};
+
+export function ScreenTransitionProvider<
+	TDescriptor extends TransitionDescriptor,
+>({
+	previous,
+	current,
+	next,
+	children,
+	LifecycleController,
+}: Props<TDescriptor>) {
+	return (
+		<KeysProvider<TDescriptor>
+			previous={previous}
+			current={current}
+			next={next}
+		>
+			<ScreenGestureProvider>
+				<LifecycleController>
+					<TransitionStylesProvider>
+						<RootTransitionAware>{children}</RootTransitionAware>
+					</TransitionStylesProvider>
+				</LifecycleController>
+			</ScreenGestureProvider>
+		</KeysProvider>
+	);
+}

package/src/shared/providers/transition-styles.tsx

@@ -0,0 +1,72 @@
+import { createContext, useContext, useMemo } from "react";
+import { useDerivedValue } from "react-native-reanimated";
+import { NO_STYLES } from "../constants";
+import { _useScreenAnimation } from "../hooks/animation/use-screen-animation";
+import type { TransitionInterpolatedStyle } from "../types/animation";
+import { createBounds } from "../utils/bounds";
+
+type Props = {
+	children: React.ReactNode;
+};
+
+const TransitionStylesContext = createContext<ReturnType<
+	typeof useMemo<{
+		stylesMap: ReturnType<typeof useDerivedValue<TransitionInterpolatedStyle>>;
+	}>
+> | null>(null);
+
+export function TransitionStylesProvider({ children }: Props) {
+	const { screenInterpolatorProps, screenStyleInterpolator } =
+		_useScreenAnimation();
+
+	const stylesMap = useDerivedValue<TransitionInterpolatedStyle>(() => {
+		"worklet";
+
+		/**
+		 * ### Maintainer note
+		 *
+		 * From my understanding, reanimated will serialize the DerivedValue result. Thus resulting in us receiving a `bounds is not a function, it is an object` error. We'll build the bounds function inside here (the final step) and pass it alongside the interpolator instead.
+		 */
+		const props = screenInterpolatorProps.value;
+
+		const bounds = createBounds(props);
+		try {
+			if (!screenStyleInterpolator) return NO_STYLES;
+
+			return screenStyleInterpolator({
+				...props,
+				bounds,
+			});
+		} catch (err) {
+			if (__DEV__) {
+				console.warn(
+					"[react-native-screen-transitions] screenStyleInterpolator must be a worklet",
+					err,
+				);
+			}
+			return NO_STYLES;
+		}
+	});
+
+	const value = useMemo(() => {
+		return {
+			stylesMap,
+		};
+	}, [stylesMap]);
+
+	return (
+		<TransitionStylesContext.Provider value={value}>
+			{children}
+		</TransitionStylesContext.Provider>
+	);
+}
+
+export function useTransitionStyles() {
+	const ctx = useContext(TransitionStylesContext);
+	if (!ctx) {
+		throw new Error(
+			"useTransitionStyles must be used within a TransitionStylesProvider",
+		);
+	}
+	return ctx;
+}

package/src/shared/providers/utils/create-provider.ts

@@ -0,0 +1,64 @@
+/**
+ * Credits to
+ * https://github.com/heroui-inc/heroui-native/blob/beta/src/helpers/utils/create-context.ts
+ */
+import * as React from "react";
+
+export interface CreateContextOptions {
+	/**
+	 * If `true`, React will throw if context is `null` or `undefined`
+	 * In some cases, you might want to support nested context, so you can set it to `false`
+	 */
+	strict?: boolean;
+	/**
+	 * Error message to throw if the context is `undefined`
+	 */
+	errorMessage?: string;
+	/**
+	 * The display name of the context
+	 */
+	name?: string;
+}
+
+export type CreateContextReturn<T> = [
+	React.Provider<T>,
+	() => T,
+	React.Context<T>,
+];
+
+/**
+ * Creates a named context, provider, and hook.
+ *
+ * @param options create context options
+ */
+export function createContext<ContextType>(options: CreateContextOptions = {}) {
+	const {
+		strict = true,
+		errorMessage = "useContext: `context` is undefined. Seems you forgot to wrap component within the Provider",
+		name,
+	} = options;
+
+	const Context = React.createContext<ContextType | undefined>(undefined);
+
+	Context.displayName = name;
+
+	function useContext() {
+		const context = React.useContext(Context);
+
+		if (!context && strict) {
+			const error = new Error(errorMessage);
+
+			error.name = "ContextError";
+			Error.captureStackTrace?.(error, useContext);
+			throw error;
+		}
+
+		return context;
+	}
+
+	return [
+		Context.Provider,
+		useContext,
+		Context,
+	] as CreateContextReturn<ContextType>;
+}

package/src/shared/stores/animation-store.ts

@@ -0,0 +1,45 @@
+import { makeMutable, type SharedValue } from "react-native-reanimated";
+import type { ScreenKey } from "../types/core";
+
+export type AnimationStoreMap = {
+	progress: SharedValue<number>;
+	closing: SharedValue<number>;
+	animating: SharedValue<number>;
+};
+
+const store: Record<ScreenKey, AnimationStoreMap> = {};
+
+const ensure = (key: ScreenKey) => {
+	let bag = store[key];
+	if (!bag) {
+		bag = {
+			progress: makeMutable(0),
+			closing: makeMutable(0),
+			animating: makeMutable(0),
+		};
+		store[key] = bag;
+	}
+	return bag;
+};
+
+export function getAnimation(
+	key: ScreenKey,
+	type: "progress" | "closing" | "animating",
+): SharedValue<number> {
+	return ensure(key)[type];
+}
+
+export function getAll(key: ScreenKey) {
+	return ensure(key);
+}
+
+function clear(routeKey: ScreenKey) {
+	"worklet";
+	delete store[routeKey];
+}
+
+export const AnimationStore = {
+	getAnimation,
+	clear,
+	getAll,
+};

package/src/shared/stores/bound-store/index.ts

@@ -0,0 +1,125 @@
+import {
+	type MeasuredDimensions,
+	makeMutable,
+	type StyleProps,
+} from "react-native-reanimated";
+import type { ScreenTransitionState } from "../../types/animation";
+import type { ScreenKey } from "../../types/core";
+import type { Any } from "../../types/utils";
+import { pairKey, resolveActiveBound } from "./_utils";
+
+type BoundsDict = Record<
+	string,
+	Record<string, { bounds: MeasuredDimensions; styles: StyleProps }>
+>;
+
+const registry = makeMutable<BoundsDict>({});
+const pairCache = makeMutable<Record<string, string>>({});
+const lastActiveByRoute = makeMutable<Record<string, string>>({});
+
+function setBounds(
+	screenId: string,
+	boundId: string,
+	bounds: MeasuredDimensions | null = null,
+	styles: StyleProps = {},
+) {
+	"worklet";
+	registry.modify((state: Any) => {
+		"worklet";
+		if (!state[screenId]) {
+			state[screenId] = {};
+		}
+		state[screenId][boundId] = { bounds, styles };
+
+		return state;
+	});
+}
+
+function getBounds(screenId: string) {
+	"worklet";
+	return registry.value[screenId] ?? {};
+}
+
+function setRouteActive(routeKey: string, boundId: string) {
+	"worklet";
+	lastActiveByRoute.modify((state: Any) => {
+		"worklet";
+		state[routeKey] = boundId;
+		return state;
+	});
+}
+
+function getRouteActive(routeKey: string) {
+	"worklet";
+	return lastActiveByRoute.value[routeKey] ?? null;
+}
+
+function setPairCache(fromKey: string, toKey: string, boundId: string) {
+	"worklet";
+	const key = pairKey(fromKey, toKey);
+	if (!key) return;
+	pairCache.modify((state: Any) => {
+		"worklet";
+		state[key] = boundId;
+		return state;
+	});
+}
+
+function getPairCache(fromKey: string, toKey: string) {
+	"worklet";
+	const key = pairKey(fromKey, toKey);
+	if (!key) return null;
+	return pairCache.value[key] ?? null;
+}
+
+function clear(routeKey: ScreenKey) {
+	"worklet";
+	registry.modify((state) => {
+		"worklet";
+		delete state[routeKey];
+		return state;
+	});
+	lastActiveByRoute.modify((state) => {
+		"worklet";
+		if (state[routeKey]) delete state[routeKey];
+		return state;
+	});
+
+	pairCache.modify((state) => {
+		"worklet";
+		const keys = Object.keys(state);
+		for (let i = 0; i < keys.length; i++) {
+			const k = keys[i];
+			const [from, to] = k.split("|");
+			if (from === routeKey || to === routeKey) {
+				delete state[k];
+			}
+		}
+		return state;
+	});
+}
+
+function getActiveBound(
+	current: ScreenTransitionState,
+	next: ScreenTransitionState | undefined,
+	previous: ScreenTransitionState | undefined,
+) {
+	"worklet";
+	return resolveActiveBound({
+		current,
+		next,
+		previous,
+		getPairCache,
+		setPairCache,
+		getRouteActive,
+	});
+}
+
+export const BoundStore = {
+	setBounds,
+	getBounds,
+	setRouteActive,
+	getRouteActive,
+	clear,
+	getActiveBound,
+};

package/src/shared/stores/gesture-store.ts

@@ -0,0 +1,60 @@
+import { makeMutable, type SharedValue } from "react-native-reanimated";
+import type { ScreenKey } from "../types/core";
+import type { GestureDirection } from "../types/gesture";
+
+export type GestureKey =
+	| "x"
+	| "y"
+	| "normalizedX"
+	| "normalizedY"
+	| "isDismissing"
+	| "isDragging";
+
+export type GestureStoreMap = {
+	x: SharedValue<number>;
+	y: SharedValue<number>;
+	normalizedX: SharedValue<number>;
+	normalizedY: SharedValue<number>;
+	isDismissing: SharedValue<number>;
+	isDragging: SharedValue<number>;
+	direction: SharedValue<Omit<GestureDirection, "bidirectional"> | null>;
+};
+
+const store: Record<ScreenKey, GestureStoreMap> = {};
+
+function ensure(routeKey: ScreenKey): GestureStoreMap {
+	let bag = store[routeKey];
+	if (!bag) {
+		bag = {
+			x: makeMutable(0),
+			y: makeMutable(0),
+			normalizedX: makeMutable(0),
+			normalizedY: makeMutable(0),
+			isDismissing: makeMutable(0),
+			isDragging: makeMutable(0),
+			direction: makeMutable<Omit<GestureDirection, "bidirectional"> | null>(
+				null,
+			),
+		};
+		store[routeKey] = bag;
+	}
+	return bag;
+}
+
+function getGesture(routeKey: ScreenKey, gestureKey: GestureKey) {
+	return ensure(routeKey)[gestureKey];
+}
+
+function getRouteGestures(routeKey: ScreenKey) {
+	return ensure(routeKey);
+}
+
+function clear(routeKey: ScreenKey) {
+	delete store[routeKey];
+}
+
+export const GestureStore = {
+	getGesture,
+	getRouteGestures,
+	clear,
+};

package/src/shared/stores/utils/reset-stores-for-screen.ts

@@ -0,0 +1,13 @@
+import type { NativeStackDescriptor } from "../../../native-stack/types";
+import { AnimationStore } from "../animation-store";
+import { BoundStore } from "../bound-store";
+import { GestureStore } from "../gesture-store";
+
+/**
+ * Reset all stores for a given screen
+ */
+export const resetStoresForScreen = (current: NativeStackDescriptor) => {
+	AnimationStore.clear(current.route.key);
+	GestureStore.clear(current.route.key);
+	BoundStore.clear(current.route.key);
+};

package/src/shared/types/animation.ts

@@ -0,0 +1,90 @@
+import type { ParamListBase, RouteProp } from "@react-navigation/native";
+import type {
+	StyleProps,
+	WithSpringConfig,
+	WithTimingConfig,
+} from "react-native-reanimated";
+import type { EdgeInsets } from "react-native-safe-area-context";
+import type { BoundEntry, BoundsAccessor } from "./bounds";
+import type { Layout } from "./core";
+import type { GestureValues } from "./gesture";
+
+export interface OverlayInterpolationProps {
+	progress: number;
+	layouts: {
+		/** The `width` and `height` of the screen container. */
+		screen: Layout;
+	};
+	insets: EdgeInsets;
+}
+
+export type ScreenTransitionState = {
+	progress: number;
+	closing: number;
+	animating: number;
+	gesture: GestureValues;
+	bounds: Record<string, BoundEntry>;
+	route: RouteProp<ParamListBase>;
+};
+
+export interface ScreenInterpolationProps {
+	/** Values for the screen that came before the current one in the navigation stack. */
+	previous: ScreenTransitionState | undefined;
+	/** Values for the current screen being interpolated. */
+	current: ScreenTransitionState;
+	/** Values for the screen that comes after the current one in the navigation stack. */
+	next: ScreenTransitionState | undefined;
+	/** Layout measurements for the screen. */
+	layouts: {
+		/** The `width` and `height` of the screen container. */
+		screen: Layout;
+	};
+	/** The safe area insets for the screen. */
+	insets: EdgeInsets;
+	/** The ID of the currently active shared bound (e.g., 'a' when Transition.Pressable has sharedBoundTag='a'). */
+	activeBoundId: string;
+	/** Whether the current screen is the focused (topmost) screen in the stack. */
+	focused: boolean;
+	/** Combined progress of current and next screen transitions, ranging from 0-2. */
+	progress: number;
+	/** Function that provides access to bounds builders for creating shared element transitions. */
+	bounds: BoundsAccessor;
+	/** The screen state that is currently driving the transition (either current or next, whichever is focused). */
+	active: ScreenTransitionState;
+	/** Whether the active screen is currently transitioning (either being dragged or animating). */
+	isActiveTransitioning: boolean;
+	/** Whether the active screen is in the process of being dismissed/closed. */
+	isDismissing: boolean;
+}
+
+export type ScreenStyleInterpolator = (
+	props: ScreenInterpolationProps,
+) => TransitionInterpolatedStyle;
+
+export type TransitionInterpolatedStyle = {
+	/**
+	 * Animated style for the main screen view. Styles are only applied when Transition.View is present.
+	 */
+	contentStyle?: StyleProps;
+	/**
+	 * Animated style for a semi-transparent overlay. Styles are only applied when Transition.View is present.
+	 */
+	overlayStyle?: StyleProps;
+	/**
+	 * Define your own custom styles by using an id as the key: [id]: StyleProps
+	 */
+	[id: string]: StyleProps | undefined;
+};
+
+/**
+ * A Reanimated animation configuration object.
+ */
+export type AnimationConfig = WithSpringConfig | WithTimingConfig;
+
+/**
+ * Defines separate animation configurations for opening and closing a screen.
+ */
+export interface TransitionSpec {
+	open?: AnimationConfig;
+	close?: AnimationConfig;
+}

package/src/shared/types/core.ts

@@ -0,0 +1,97 @@
+import type { AnimatedProps } from "react-native-reanimated";
+import type { ScreenStyleInterpolator, TransitionSpec } from "./animation";
+import type { GestureActivationArea, GestureDirection } from "./gesture";
+
+export type Layout = {
+	width: number;
+	height: number;
+};
+
+export type ScreenKey = string;
+
+export type ScreenPhase = "previous" | "current" | "next";
+
+export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
+	/**
+	 * Connects this component to custom animated styles defined in screenStyleInterpolator.
+	 *
+	 * When you return custom styles from your interpolator with a matching key,
+	 * those styles will be applied to this component during transitions.
+	 *
+	 * @example
+	 * // In your component:
+	 * <Transition.View styleId="hero-image">
+	 *   <Image source={...} />
+	 * </Transition.View>
+	 *
+	 * // In your screenStyleInterpolator:
+	 * return {
+	 *   'hero-image': {
+	 *     opacity: interpolate(progress, [0, 1], [0, 1]),
+	 *     transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }]
+	 *   }
+	 * }
+	 */
+	styleId?: string;
+
+	/**
+	 * Marks this component for measurement to enable shared element transitions.
+	 * Components with the same tag across different screens will animate between each other.
+	 *
+	 * @example
+	 * // Screen A:
+	 * <Transition.View sharedBoundTag="profile-avatar">
+	 *   <Avatar size="small" />
+	 * </Transition.View>
+	 *
+	 * // Screen B:
+	 * <Transition.View sharedBoundTag="profile-avatar">
+	 *   <Avatar size="large" />
+	 * </Transition.View>
+	 */
+	sharedBoundTag?: string;
+};
+
+export type TransitionConfig = {
+	open: TransitionSpec;
+	close: TransitionSpec;
+};
+
+export type ScreenTransitionConfig = {
+	/**
+	 * The user-provided function to calculate styles based on animation progress.
+	 */
+	screenStyleInterpolator?: ScreenStyleInterpolator;
+	/**
+	 * The Reanimated animation config for opening and closing transitions.
+	 */
+	transitionSpec?: TransitionSpec;
+	/**
+	 * Whether the gesture is enabled.
+	 */
+	gestureEnabled?: boolean;
+	/**
+	 * The direction of the swipe gesture used to dismiss the screen.
+	 */
+	gestureDirection?: GestureDirection | GestureDirection[];
+	/**
+	 * How much the gesture's final velocity impacts the dismiss decision.
+	 */
+	gestureVelocityImpact?: number;
+	/**
+	 * Distance threshold for gesture recognition throughout the screen.
+	 */
+	gestureResponseDistance?: number;
+	/**
+	 * Whether the gesture drives the progress.
+	 */
+	gestureDrivesProgress?: boolean;
+	/**
+	 * The area of the screen where the gesture is activated.
+	 */
+	gestureActivationArea?: GestureActivationArea;
+	/**
+	 * Whether to enable transitions. It sets the presentation to containedTransparentModal, animation none, and headerShown to false.
+	 */
+	enableTransitions?: boolean;
+};