react-native-screen-transitions 4.1.0-beta.1 → 4.1.0-rc.0

package/src/providers/motion/gestures/types.ts

@@ -0,0 +1,202 @@
+import type {
+	Gesture,
+	GestureStateChangeEvent,
+	GestureUpdateEvent,
+	PanGestureHandlerEventPayload,
+	PinchGestureHandlerEventPayload,
+} from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import type {
+	AnimationConfig,
+	TransitionSpec,
+} from "../../../types/animation.types";
+import type {
+	GestureDirections,
+	ResolvedGestureActivationArea,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	ScrollMetadataState,
+	SnapPanDirectionConfig,
+	SnapPinchDirectionConfig,
+} from "../../../types/gesture.types";
+import type {
+	ClaimedDirections,
+	Direction,
+} from "../../../types/ownership.types";
+import type { ScreenTransitionConfig } from "../../../types/screen.types";
+import type { MotionTransitionValues } from "../hooks/use-transition-values";
+import type { MotionAnimationValues, MotionGestureValues } from "../types";
+import type { EffectiveSnapPointsResult } from "./shared/snap-points";
+
+export type PanGesture = ReturnType<typeof Gesture.Pan>;
+export type PinchGesture = ReturnType<typeof Gesture.Pinch>;
+export type ComposedGesture = ReturnType<typeof Gesture.Simultaneous>;
+
+export type PanGestureEvent =
+	| GestureUpdateEvent<PanGestureHandlerEventPayload>
+	| GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+
+export type PinchGestureEvent =
+	| GestureUpdateEvent<PinchGestureHandlerEventPayload>
+	| GestureStateChangeEvent<PinchGestureHandlerEventPayload>;
+
+/** Gesture that owns navigation release for the current simultaneous composition. */
+export type GestureCompositionOwner = "pan" | "pinch" | null;
+
+export type {
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	ScrollMetadataState,
+};
+
+export type GestureOwnerMap = Record<Direction, string | null>;
+
+export const NO_GESTURE_OWNERS: GestureOwnerMap = {
+	vertical: null,
+	"vertical-inverted": null,
+	horizontal: null,
+	"horizontal-inverted": null,
+};
+
+export interface ScreenGestureSource {
+	routeKey: string;
+	detectorGesture: ComposedGesture;
+	panGesture: PanGesture;
+	pinchGesture: PinchGesture;
+	scrollState: SharedValue<ScrollGestureState | null>;
+}
+
+export type GestureContextType = ScreenGestureSource;
+
+export interface ScreenGestureParticipation {
+	/** Whether this route is the first route in its stack. First routes never track gestures. */
+	isFirstKey: boolean;
+	/** Whether this route can dismiss to progress 0 from a gesture release. */
+	canDismiss: boolean;
+	/** Whether recognizers can activate to expose gesture values to interpolators. */
+	canTrackGesture: boolean;
+	effectiveSnapPoints: EffectiveSnapPointsResult;
+	claimedDirections: ClaimedDirections;
+}
+
+export interface ScreenGestureConfig {
+	participation: ScreenGestureParticipation;
+	pan: PanGesturePolicy;
+	pinch: PinchGesturePolicy;
+}
+
+export interface PanGesturePolicy {
+	enabled: boolean;
+	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>;
+	panActivationDirections: GestureDirections;
+	snapAxisDirections: SnapPanDirectionConfig;
+	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
+	gestureVelocityImpact: number;
+	gestureSnapVelocityImpact: number;
+	gestureReleaseVelocityScale: number;
+	gestureActivationArea: ResolvedGestureActivationArea;
+	gestureSnapLocked: boolean;
+	sheetSnapBehavior: NonNullable<ScreenTransitionConfig["sheetSnapBehavior"]>;
+	sheetScrollGestureBehavior: NonNullable<
+		ScreenTransitionConfig["sheetScrollGestureBehavior"]
+	>;
+	transitionSpec: TransitionSpec | undefined;
+}
+
+export interface PinchGesturePolicy {
+	enabled: boolean;
+	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>;
+	snapDirections: SnapPinchDirectionConfig;
+	pinchInEnabled: boolean;
+	pinchOutEnabled: boolean;
+	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
+	gestureSnapVelocityImpact: number;
+	gestureSnapLocked: boolean;
+	sheetSnapBehavior: NonNullable<ScreenTransitionConfig["sheetSnapBehavior"]>;
+	gestureReleaseVelocityScale: number;
+	transitionSpec: TransitionSpec | undefined;
+}
+
+export interface GestureRuntimeStores {
+	gestures: MotionGestureValues;
+	animations: MotionAnimationValues;
+	system: MotionTransitionValues;
+}
+
+export type GesturePolicy = PanGesturePolicy | PinchGesturePolicy;
+
+export interface GestureRuntime<TPolicy extends GesturePolicy> {
+	participation: ScreenGestureParticipation;
+	policy: TPolicy;
+	stores: GestureRuntimeStores;
+}
+
+export type PanGestureRuntime = GestureRuntime<PanGesturePolicy>;
+
+export type PinchGestureRuntime = GestureRuntime<PinchGesturePolicy>;
+
+export interface GestureDimensions {
+	width: number;
+	height: number;
+}
+
+export interface PanTrackState {
+	x: number;
+	y: number;
+	normX: number;
+	normY: number;
+	velocity: number;
+}
+
+export interface PinchTrackState {
+	scale: number;
+	normScale: number;
+}
+
+export interface PanReleaseResult {
+	target: number;
+	shouldDismiss: boolean;
+	initialVelocity: number;
+	commitProgress?: number;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PanReleasePlan {
+	target: number;
+	shouldDismiss: boolean;
+	progressVelocity: number;
+	resetVelocityX: number;
+	resetVelocityY: number;
+	resetVelocityNormX: number;
+	resetVelocityNormY: number;
+	handoffVelocity: number;
+	commitProgress?: number;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PinchReleaseResult {
+	target: number;
+	shouldDismiss: boolean;
+	initialVelocity: number;
+	handoffVelocity: number;
+	commitProgress?: number;
+	resetValuesImmediately?: boolean;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PanBehavior {
+	onStart: () => void;
+	onUpdate: (event: PanGestureEvent) => void;
+	onEnd: (event: PanGestureEvent) => void;
+}
+
+export interface PinchBehavior {
+	onStart: (event: PinchGestureEvent) => void;
+	onUpdate: (event: PinchGestureEvent) => void;
+	onEnd: (event: PinchGestureEvent) => void;
+}

package/src/providers/motion/gestures/use-screen-gestures.ts

@@ -0,0 +1,66 @@
+import { useMemo } from "react";
+import { Gesture } from "react-native-gesture-handler";
+import { useSharedValue } from "react-native-reanimated";
+import { ScrollStore } from "../../../stores/scroll.store";
+import { useBuilderStore } from "../../builder";
+import type { ScreenOptionsContextValue } from "../options/types";
+import type { MotionValues } from "../types";
+import { useScreenGestureConfig } from "./ownership/hooks/use-screen-gesture-config";
+import { useBuildPanGesture } from "./pan/use-build-pan-gesture";
+import { useBuildPinchGesture } from "./pinch/use-build-pinch-gesture";
+import { type GestureCompositionOwner, NO_GESTURE_OWNERS } from "./types";
+
+export function useScreenGestures(
+	screenOptions: ScreenOptionsContextValue,
+	values: MotionValues,
+	onDismissRequest?: () => void,
+) {
+	const currentScreenKey = useBuilderStore(
+		(store) => store.derivations.currentScreenKey,
+	);
+	const gestureConfig = useScreenGestureConfig();
+	const scrollState = ScrollStore.getValue(currentScreenKey, "coordination");
+	const gestureOwners = useSharedValue({ ...NO_GESTURE_OWNERS });
+	const gestureCompositionOwner = useSharedValue<GestureCompositionOwner>(null);
+	const panGesture = useBuildPanGesture({
+		values,
+		onDismissRequest,
+		scrollState,
+		screenOptions,
+		gestureConfig,
+		gestureOwners,
+		gestureCompositionOwner,
+	});
+	const pinchGesture = useBuildPinchGesture({
+		values,
+		onDismissRequest,
+		screenOptions,
+		gestureConfig,
+		gestureCompositionOwner,
+	});
+	const detectorGesture = useMemo(
+		() => Gesture.Simultaneous(panGesture, pinchGesture),
+		[panGesture, pinchGesture],
+	);
+	const claimedDirections = gestureConfig.participation.claimedDirections;
+	return useMemo(
+		() => ({
+			routeKey: currentScreenKey,
+			detectorGesture,
+			panGesture,
+			pinchGesture,
+			scrollState,
+			owners: gestureOwners,
+			claimedDirections,
+		}),
+		[
+			currentScreenKey,
+			detectorGesture,
+			panGesture,
+			pinchGesture,
+			scrollState,
+			gestureOwners,
+			claimedDirections,
+		],
+	);
+}

package/src/providers/motion/hooks/use-maybe-block-visibility.tsx

@@ -0,0 +1,121 @@
+import { useWindowDimensions } from "react-native";
+import {
+	type SharedValue,
+	useAnimatedProps,
+	useAnimatedReaction,
+	useAnimatedStyle,
+	useDerivedValue,
+	useSharedValue,
+} from "react-native-reanimated";
+import { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
+import {
+	hasCloseTransitionFinished,
+	isScreenReady as resolveScreenReady,
+} from "../helpers/transition-visual-state";
+import { resolveScreenVisibilityGate } from "../helpers/visibility-gate";
+import type { MotionValues } from "../types";
+import { LifecycleTransitionRequestKind } from "./use-transition-values";
+
+type Params = {
+	motion: MotionValues;
+	ancestorIsScreenReady: SharedValue<boolean> | null;
+	isFloatingOverlay?: boolean;
+};
+
+export const useMaybeBlockVisibility = ({
+	motion,
+	ancestorIsScreenReady,
+	isFloatingOverlay,
+}: Params) => {
+	const { height } = useWindowDimensions();
+	const {
+		animationProgress,
+		entering,
+		closing,
+		pendingLifecycleStartBlockCount,
+		pendingLifecycleRequestKind,
+	} = motion;
+
+	const hasVisibilityGateOpened = useSharedValue(false);
+	const localVisibilityBlocked = useSharedValue(!isFloatingOverlay);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+
+			return resolveScreenVisibilityGate({
+				isFloatingOverlay,
+				hasVisibilityGateOpened: hasVisibilityGateOpened.get(),
+				pendingLifecycleStartBlockCount: pendingLifecycleStartBlockCount.get(),
+				pendingLifecycleRequestKind: pendingLifecycleRequestKind.get(),
+				animationProgress: animationProgress.get(),
+				entering: entering.get(),
+			});
+		},
+		(gate) => {
+			"worklet";
+
+			if (gate.shouldOpenGate) {
+				hasVisibilityGateOpened.set(true);
+			}
+
+			localVisibilityBlocked.set(gate.shouldBlock);
+		},
+	);
+
+	const isScreenReady = useDerivedValue(() => {
+		"worklet";
+		const isPendingOpen =
+			pendingLifecycleRequestKind.get() === LifecycleTransitionRequestKind.Open;
+
+		return (
+			!localVisibilityBlocked.get() &&
+			(ancestorIsScreenReady?.get() ?? true) &&
+			resolveScreenReady({
+				opening: isPendingOpen || !!entering.get(),
+				closing: closing.get(),
+				pendingLifecycleStartBlockCount: pendingLifecycleStartBlockCount.get(),
+				animationProgress: animationProgress.get(),
+			})
+		);
+	});
+
+	const animatedStyle = useAnimatedStyle(() => {
+		"worklet";
+		const offset = getVisibilityBlockOffset(height);
+		// Hide the outgoing screen after its visual close while React removes its
+		// host asynchronously.
+		const shouldHideClosedScreen = hasCloseTransitionFinished({
+			closing: closing.get(),
+			animationProgress: animationProgress.get(),
+		});
+		// Only the first unready ancestor applies the offset, including after close.
+		// Measurements can therefore use !isScreenReady to correct that one offset.
+		const appliesOffset =
+			!isScreenReady.get() && (ancestorIsScreenReady?.get() ?? true);
+
+		return {
+			opacity: shouldHideClosedScreen ? 0 : 1,
+			transform: [
+				{
+					translateY: appliesOffset ? offset : 0,
+				},
+			],
+		};
+	});
+
+	const animatedProps = useAnimatedProps(() => {
+		"worklet";
+		return {
+			pointerEvents: isScreenReady.get()
+				? ("box-none" as const)
+				: ("none" as const),
+		};
+	});
+
+	return {
+		animatedStyle,
+		animatedProps,
+		isScreenReady,
+	};
+};

package/src/providers/motion/hooks/use-motion-values.ts

@@ -0,0 +1,109 @@
+import { useMemo, useState } from "react";
+import { useSharedValue } from "react-native-reanimated";
+import type { ActiveGesture } from "../../../types/gesture.types";
+import type {
+	MotionAnimationValues,
+	MotionGestureValues,
+	MotionValues,
+} from "../types";
+import { useTransitionValues } from "./use-transition-values";
+
+function useAnimationValues(): MotionAnimationValues {
+	const values = {
+		transitionProgress: useSharedValue(0),
+		visualProgress: useSharedValue(0),
+		willAnimate: useSharedValue(0),
+		closing: useSharedValue(0),
+		progressAnimating: useSharedValue(0),
+		progressSettled: useSharedValue(1),
+		entering: useSharedValue(0),
+	};
+	const [state] = useState(values);
+	return state;
+}
+
+function useGestureValues(): MotionGestureValues {
+	const progressBaseline = useSharedValue(0);
+	const progressDeltaX = useSharedValue(0);
+	const progressDeltaY = useSharedValue(0);
+	const lockedSnapPoint = useSharedValue<number | null>(null);
+	const normX = useSharedValue(0);
+	const normY = useSharedValue(0);
+	const scale = useSharedValue(1);
+	const normScale = useSharedValue(0);
+	const dismissing = useSharedValue(0);
+	const dragging = useSharedValue(0);
+	const settling = useSharedValue(0);
+	const initiator = useSharedValue<ActiveGesture | null>(null);
+
+	const values = {
+		x: useSharedValue(0),
+		y: useSharedValue(0),
+		normX,
+		normY,
+		velocity: useSharedValue(0),
+		scale,
+		normScale,
+		focalX: useSharedValue(0),
+		focalY: useSharedValue(0),
+		pinchOriginX: useSharedValue(0),
+		pinchOriginY: useSharedValue(0),
+		rotation: useSharedValue(0),
+		raw: {
+			x: useSharedValue(0),
+			y: useSharedValue(0),
+			normX: useSharedValue(0),
+			normY: useSharedValue(0),
+			scale: useSharedValue(1),
+			normScale: useSharedValue(0),
+			rotation: useSharedValue(0),
+		},
+		internal: {
+			progressBaseline,
+			progressDeltaX,
+			progressDeltaY,
+			lockedSnapPoint,
+			snapshot: {
+				x: useSharedValue(0),
+				y: useSharedValue(0),
+				normX: useSharedValue(0),
+				normY: useSharedValue(0),
+				velocity: useSharedValue(0),
+				scale: useSharedValue(1),
+				normScale: useSharedValue(0),
+				focalX: useSharedValue(0),
+				focalY: useSharedValue(0),
+				pinchOriginX: useSharedValue(0),
+				pinchOriginY: useSharedValue(0),
+				rotation: useSharedValue(0),
+				raw: {
+					x: useSharedValue(0),
+					y: useSharedValue(0),
+					normX: useSharedValue(0),
+					normY: useSharedValue(0),
+					scale: useSharedValue(1),
+					normScale: useSharedValue(0),
+					rotation: useSharedValue(0),
+				},
+				active: useSharedValue<ActiveGesture | null>(null),
+			},
+		},
+		dismissing,
+		dragging,
+		settling,
+		initiator,
+	};
+	const [state] = useState(values);
+	return state;
+}
+
+export function useMotionValues(): MotionValues {
+	const animations = useAnimationValues();
+	const gesture = useGestureValues();
+	const transition = useTransitionValues();
+
+	return useMemo(
+		() => ({ ...animations, ...gesture, ...transition }),
+		[animations, gesture, transition],
+	);
+}

package/src/providers/motion/hooks/use-transition-values.ts

@@ -0,0 +1,136 @@
+import { useMemo } from "react";
+import { type SharedValue, useSharedValue } from "react-native-reanimated";
+import type { Layout } from "../../../types/screen.types";
+
+export enum LifecycleTransitionRequestKind {
+	None = 0,
+	Open = 1,
+	Close = 2,
+}
+
+type MotionTransitionRawValues = {
+	targetProgress: SharedValue<number>;
+
+	/**
+	 * Directional linear clock for the active progress animation. Increasing
+	 * animations run 0 -> 1; decreasing animations run 1 -> 0.
+	 */
+	animationProgress: SharedValue<number>;
+
+	/**
+	 * Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured.
+	 */
+	resolvedAutoSnapPoint: SharedValue<number>;
+
+	/**
+	 * Intrinsic measured content layout from the screen container wrapper.
+	 */
+	measuredContentLayout: SharedValue<Layout | null>;
+
+	/**
+	 * The currently pending lifecycle transition request.
+	 */
+	pendingLifecycleRequestKind: SharedValue<LifecycleTransitionRequestKind>;
+
+	/**
+	 * Progress target for the pending lifecycle transition request.
+	 */
+	pendingLifecycleRequestTarget: SharedValue<number>;
+
+	/**
+	 * Number of active blockers preventing a pending lifecycle request from
+	 * starting immediately.
+	 */
+	pendingLifecycleStartBlockCount: SharedValue<number>;
+};
+
+export interface MotionTransitionActions {
+	requestLifecycleTransition(
+		kind: LifecycleTransitionRequestKind,
+		target: number,
+	): void;
+	clearLifecycleTransitionRequest(): void;
+	blockLifecycleStart(): void;
+	unblockLifecycleStart(): void;
+	drainLifecycleStartBlocks(): void;
+}
+
+export type MotionTransitionValues = MotionTransitionRawValues & {
+	actions: MotionTransitionActions;
+};
+
+export function useTransitionValues(): MotionTransitionValues {
+	const targetProgress = useSharedValue(1);
+	const animationProgress = useSharedValue(0);
+	const resolvedAutoSnapPoint = useSharedValue(-1);
+	const measuredContentLayout = useSharedValue<Layout | null>(null);
+	const pendingLifecycleRequestKind = useSharedValue(
+		LifecycleTransitionRequestKind.None,
+	);
+	const pendingLifecycleRequestTarget = useSharedValue(0);
+	const pendingLifecycleStartBlockCount = useSharedValue(0);
+
+	return useMemo(() => {
+		const bag = {
+			targetProgress,
+			animationProgress,
+			resolvedAutoSnapPoint,
+			measuredContentLayout,
+			pendingLifecycleRequestKind,
+			pendingLifecycleRequestTarget,
+			pendingLifecycleStartBlockCount,
+		};
+
+		return {
+			...bag,
+			actions: {
+				requestLifecycleTransition(kind, target) {
+					"worklet";
+					bag.pendingLifecycleRequestTarget.set(target);
+					bag.pendingLifecycleRequestKind.set(kind);
+				},
+
+				clearLifecycleTransitionRequest() {
+					"worklet";
+					bag.pendingLifecycleRequestKind.set(
+						LifecycleTransitionRequestKind.None,
+					);
+					bag.pendingLifecycleRequestTarget.set(0);
+				},
+
+				blockLifecycleStart() {
+					"worklet";
+					bag.pendingLifecycleStartBlockCount.modify(
+						<T extends number>(count: T): T => {
+							"worklet";
+							return (count + 1) as T;
+						},
+					);
+				},
+
+				unblockLifecycleStart() {
+					"worklet";
+					bag.pendingLifecycleStartBlockCount.modify(
+						<T extends number>(count: T): T => {
+							"worklet";
+							return Math.max(0, count - 1) as T;
+						},
+					);
+				},
+
+				drainLifecycleStartBlocks() {
+					"worklet";
+					bag.pendingLifecycleStartBlockCount.set(0);
+				},
+			},
+		};
+	}, [
+		targetProgress,
+		animationProgress,
+		resolvedAutoSnapPoint,
+		measuredContentLayout,
+		pendingLifecycleRequestKind,
+		pendingLifecycleRequestTarget,
+		pendingLifecycleStartBlockCount,
+	]);
+}

package/src/providers/motion/motion.provider.tsx

@@ -0,0 +1,69 @@
+import { type ReactNode, useMemo } from "react";
+import { StyleSheet } from "react-native";
+import Animated, { type SharedValue } from "react-native-reanimated";
+import createProvider from "../../utils/create-provider";
+import { useBuilderStore } from "../builder";
+import { useMotionAnimationPipeline } from "./animation/pipeline";
+import { useScreenGestures } from "./gestures/use-screen-gestures";
+import { useMaybeBlockVisibility } from "./hooks/use-maybe-block-visibility";
+import { useMotionValues } from "./hooks/use-motion-values";
+import { useScreenOptions } from "./options/use-screen-options";
+
+export type MotionProviderProps = {
+	children: ReactNode;
+	onDismissRequest?: () => void;
+};
+
+export type MotionState = {
+	options: ReturnType<typeof useScreenOptions>;
+	gestures: ReturnType<typeof useScreenGestures>;
+	state: ReturnType<typeof useMotionAnimationPipeline>;
+	/** False until this screen and its ancestors are ready, or after visual close. */
+	isScreenReady: SharedValue<boolean>;
+};
+
+export const {
+	MotionProvider,
+	getMotionStore,
+	useMotionStore,
+	useOptionalMotionStore,
+} = createProvider("Motion", { global: true })<
+	MotionProviderProps,
+	MotionState
+>(({ onDismissRequest, children }) => {
+	const screenKey = useBuilderStore(
+		(store) => store.derivations.currentScreenKey,
+	);
+	const ancestorIsScreenReady = useOptionalMotionStore(
+		(store) => store?.isScreenReady ?? null,
+	);
+	const values = useMotionValues();
+	const options = useScreenOptions();
+
+	const gestures = useScreenGestures(options, values, onDismissRequest);
+
+	const state = useMotionAnimationPipeline(values);
+
+	const { animatedStyle, animatedProps, isScreenReady } =
+		useMaybeBlockVisibility({ motion: values, ancestorIsScreenReady });
+
+	const value = useMemo(
+		() => ({ options, gestures, state, isScreenReady }),
+		[options, gestures, state, isScreenReady],
+	);
+
+	return {
+		key: screenKey,
+		value,
+		children: (
+			<Animated.View
+				style={[styles.container, animatedStyle]}
+				animatedProps={animatedProps}
+			>
+				{children}
+			</Animated.View>
+		),
+	};
+});
+
+const styles = StyleSheet.create({ container: { flex: 1 } });