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

package/src/providers/screen/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/screen/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/screen/motion/helpers/transition-visual-state.ts

@@ -0,0 +1,66 @@
+/**
+ * Visual lifecycle boundaries use the internal directional clock rather than
+ * physical transition progress, which may overshoot or revisit an endpoint.
+ */
+export const hasOpenTransitionStarted = ({
+	pendingLifecycleStartBlockCount,
+	animationProgress,
+}: {
+	pendingLifecycleStartBlockCount: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+	return pendingLifecycleStartBlockCount === 0 && animationProgress > 0;
+};
+
+export const isOpenTransitionBlocked = ({
+	opening,
+	pendingLifecycleStartBlockCount,
+	animationProgress,
+}: {
+	opening: boolean;
+	pendingLifecycleStartBlockCount: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+	return (
+		opening &&
+		!hasOpenTransitionStarted({
+			pendingLifecycleStartBlockCount,
+			animationProgress,
+		})
+	);
+};
+
+export const hasCloseTransitionFinished = ({
+	closing,
+	animationProgress,
+}: {
+	closing: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+	return !!closing && animationProgress === 0;
+};
+
+export const isScreenReady = ({
+	opening,
+	closing,
+	pendingLifecycleStartBlockCount,
+	animationProgress,
+}: {
+	opening: boolean;
+	closing: number;
+	pendingLifecycleStartBlockCount: number;
+	animationProgress: number;
+}) => {
+	"worklet";
+
+	return (
+		!isOpenTransitionBlocked({
+			opening,
+			pendingLifecycleStartBlockCount,
+			animationProgress,
+		}) && !hasCloseTransitionFinished({ closing, animationProgress })
+	);
+};

package/src/providers/screen/motion/helpers/visibility-gate.ts

@@ -0,0 +1,80 @@
+import { LifecycleTransitionRequestKind } from "../hooks/use-transition-values";
+import {
+	hasOpenTransitionStarted,
+	isOpenTransitionBlocked,
+} from "./transition-visual-state";
+
+type ScreenVisibilityGateState = {
+	isFloatingOverlay?: boolean;
+	hasVisibilityGateOpened: boolean;
+	pendingLifecycleStartBlockCount: number;
+	pendingLifecycleRequestKind: LifecycleTransitionRequestKind;
+	animationProgress: number;
+	entering: number;
+};
+
+type ScreenVisibilityGateDecision = {
+	shouldBlock: boolean;
+	shouldOpenGate: boolean;
+};
+
+type InitialDestinationStyleGateState = {
+	shouldPrepareStyles: boolean;
+	isScreenReady: boolean;
+	stylesReady: boolean;
+};
+
+type InitialDestinationStyleGateDecision = {
+	shouldMarkStylesReady: boolean;
+	shouldWithholdStyles: boolean;
+};
+
+export const resolveInitialDestinationStyleGate = ({
+	shouldPrepareStyles,
+	isScreenReady,
+	stylesReady,
+}: InitialDestinationStyleGateState): InitialDestinationStyleGateDecision => {
+	"worklet";
+
+	return {
+		shouldMarkStylesReady:
+			shouldPrepareStyles && !isScreenReady && !stylesReady,
+		shouldWithholdStyles: shouldPrepareStyles && !stylesReady,
+	};
+};
+
+export const resolveScreenVisibilityGate = ({
+	isFloatingOverlay,
+	hasVisibilityGateOpened,
+	pendingLifecycleStartBlockCount,
+	pendingLifecycleRequestKind,
+	animationProgress,
+	entering,
+}: ScreenVisibilityGateState): ScreenVisibilityGateDecision => {
+	"worklet";
+	if (isFloatingOverlay || hasVisibilityGateOpened) {
+		return {
+			shouldBlock: false,
+			shouldOpenGate: false,
+		};
+	}
+
+	const isPendingOpen =
+		pendingLifecycleRequestKind === LifecycleTransitionRequestKind.Open;
+	const isOpening = isPendingOpen || !!entering;
+	const shouldBlock = isOpenTransitionBlocked({
+		opening: isOpening,
+		pendingLifecycleStartBlockCount,
+		animationProgress,
+	});
+
+	return {
+		shouldBlock,
+		shouldOpenGate:
+			!shouldBlock &&
+			hasOpenTransitionStarted({
+				pendingLifecycleStartBlockCount,
+				animationProgress,
+			}),
+	};
+};

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

@@ -0,0 +1,119 @@
+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,
+		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: motion.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 || !!motion.entering.get(),
+				closing: motion.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: motion.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/screen/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],
+	);
+}