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

package/src/providers/screen/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/screen/motion/index.ts

@@ -0,0 +1,7 @@
+export {
+	getMotionStore,
+	MotionProvider,
+	type MotionState,
+	useMotionStore,
+	useOptionalMotionStore,
+} from "./motion.provider";

package/src/providers/screen/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 } });

package/src/providers/screen/motion/options/helpers.ts

@@ -0,0 +1,344 @@
+import {
+	DEFAULT_GESTURE_DIRECTION,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+	DEFAULT_GESTURE_SENSITIVITY,
+	DEFAULT_GESTURE_SNAP_LOCKED,
+	DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	DEFAULT_GESTURE_TRACKING,
+	DEFAULT_GESTURE_VELOCITY_IMPACT,
+	DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR,
+	DEFAULT_SHEET_SNAP_BEHAVIOR,
+} from "../../../../constants";
+import type {
+	GestureDirection,
+	GestureDirectionActivationArea,
+	GestureDirectionEntry,
+	ScreenTransitionConfig,
+	TransitionInterpolatedStyle,
+} from "../../../../types";
+import type { BackdropBehavior } from "../../../../types/screen.types";
+import type {
+	RequiredScreenOption,
+	ScreenOptionsContextValue,
+	ScreenOptionsSnapshot,
+	ScreenOptionsState,
+} from "./types";
+
+const resolveBooleanOption = <T extends boolean | undefined>(
+	value: unknown,
+	fallback: T,
+): T => {
+	"worklet";
+	return typeof value === "boolean" ? (value as T) : fallback;
+};
+
+const resolveNumberOption = <T extends number | undefined>(
+	value: unknown,
+	fallback: T,
+): T => {
+	"worklet";
+	return typeof value === "number" && Number.isFinite(value)
+		? (value as T)
+		: fallback;
+};
+
+const isGestureDirection = (value: unknown): value is GestureDirection => {
+	"worklet";
+	return (
+		value === "horizontal" ||
+		value === "horizontal-inverted" ||
+		value === "vertical" ||
+		value === "vertical-inverted" ||
+		value === "bidirectional" ||
+		value === "pinch-in" ||
+		value === "pinch-out"
+	);
+};
+
+const isGestureDirectionActivationArea = (
+	value: unknown,
+): value is GestureDirectionActivationArea => {
+	"worklet";
+	return (
+		value === "edge" ||
+		value === "screen" ||
+		(typeof value === "number" && Number.isFinite(value) && value >= 0)
+	);
+};
+
+const isGestureDirectionEntry = (
+	value: unknown,
+): value is GestureDirectionEntry => {
+	"worklet";
+	if (isGestureDirection(value)) {
+		return true;
+	}
+
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return false;
+	}
+
+	const config = value as Record<string, unknown>;
+	return (
+		isGestureDirection(config.gesture) &&
+		(config.area === undefined || isGestureDirectionActivationArea(config.area))
+	);
+};
+
+const cloneGestureDirectionEntry = (
+	entry: GestureDirectionEntry,
+): GestureDirectionEntry => {
+	"worklet";
+	if (typeof entry === "string") {
+		return entry;
+	}
+
+	return entry.area === undefined
+		? { gesture: entry.gesture }
+		: { gesture: entry.gesture, area: entry.area };
+};
+
+const resolveGestureDirectionOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"gestureDirection">,
+): RequiredScreenOption<"gestureDirection"> => {
+	"worklet";
+	if (isGestureDirectionEntry(value)) {
+		return cloneGestureDirectionEntry(value);
+	}
+	if (Array.isArray(value)) {
+		const entries: GestureDirectionEntry[] = [];
+		for (const entry of value) {
+			if (!isGestureDirectionEntry(entry)) {
+				return fallback;
+			}
+			entries.push(cloneGestureDirectionEntry(entry));
+		}
+		return entries;
+	}
+	return fallback;
+};
+
+const resolveSheetScrollGestureBehaviorOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"sheetScrollGestureBehavior">,
+): RequiredScreenOption<"sheetScrollGestureBehavior"> => {
+	"worklet";
+	return value === "expand-and-collapse" || value === "collapse-only"
+		? value
+		: fallback;
+};
+
+const resolveSheetSnapBehaviorOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"sheetSnapBehavior">,
+): RequiredScreenOption<"sheetSnapBehavior"> => {
+	"worklet";
+	return value === "continuous" || value === "step" ? value : fallback;
+};
+
+const resolveGestureTrackingOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"gestureTracking">,
+): RequiredScreenOption<"gestureTracking"> => {
+	"worklet";
+	return value === "auto" || value === "never" || value === "always"
+		? value
+		: fallback;
+};
+
+const resolveBackdropBehaviorOption = (
+	value: unknown,
+	fallback: BackdropBehavior | undefined,
+): BackdropBehavior | undefined => {
+	"worklet";
+	return value === "block" ||
+		value === "passthrough" ||
+		value === "dismiss" ||
+		value === "collapse"
+		? value
+		: fallback;
+};
+
+const areGestureDirectionEntriesEqual = (
+	left: GestureDirectionEntry,
+	right: GestureDirectionEntry,
+) => {
+	"worklet";
+	if (left === right) return true;
+
+	if (typeof left === "string" || typeof right === "string") {
+		return false;
+	}
+
+	return left.gesture === right.gesture && left.area === right.area;
+};
+
+const areGestureDirectionsEqual = (
+	left: RequiredScreenOption<"gestureDirection">,
+	right: RequiredScreenOption<"gestureDirection">,
+) => {
+	"worklet";
+	if (
+		!Array.isArray(left) &&
+		!Array.isArray(right) &&
+		areGestureDirectionEntriesEqual(left, right)
+	) {
+		return true;
+	}
+	if (!Array.isArray(left) || !Array.isArray(right)) return false;
+	if (left.length !== right.length) return false;
+
+	for (let i = 0; i < left.length; i++) {
+		if (!areGestureDirectionEntriesEqual(left[i], right[i])) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+const areScreenOptionsEqual = (
+	left: ScreenOptionsState,
+	right: ScreenOptionsState,
+) => {
+	"worklet";
+	return (
+		left.gestureEnabled === right.gestureEnabled &&
+		left.gestureTracking === right.gestureTracking &&
+		areGestureDirectionsEqual(left.gestureDirection, right.gestureDirection) &&
+		left.gestureSensitivity === right.gestureSensitivity &&
+		left.gestureVelocityImpact === right.gestureVelocityImpact &&
+		left.gestureSnapVelocityImpact === right.gestureSnapVelocityImpact &&
+		left.gestureReleaseVelocityScale === right.gestureReleaseVelocityScale &&
+		left.gestureSnapLocked === right.gestureSnapLocked &&
+		left.sheetSnapBehavior === right.sheetSnapBehavior &&
+		left.sheetScrollGestureBehavior === right.sheetScrollGestureBehavior &&
+		left.backdropBehavior === right.backdropBehavior &&
+		left.transitionSpec === right.transitionSpec &&
+		left.baseOptions === right.baseOptions
+	);
+};
+
+export const resolveBaseScreenOptions = (
+	options: ScreenTransitionConfig,
+): ScreenOptionsSnapshot => {
+	return {
+		gestureEnabled: resolveBooleanOption(options.gestureEnabled, undefined),
+		gestureTracking: resolveGestureTrackingOption(
+			options.gestureTracking,
+			DEFAULT_GESTURE_TRACKING,
+		),
+		gestureDirection: resolveGestureDirectionOption(
+			options.gestureDirection,
+			DEFAULT_GESTURE_DIRECTION,
+		),
+		gestureSensitivity: resolveNumberOption(
+			options.gestureSensitivity,
+			DEFAULT_GESTURE_SENSITIVITY,
+		),
+		gestureVelocityImpact: resolveNumberOption(
+			options.gestureVelocityImpact,
+			DEFAULT_GESTURE_VELOCITY_IMPACT,
+		),
+		gestureSnapVelocityImpact: resolveNumberOption(
+			options.gestureSnapVelocityImpact,
+			DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+		),
+		gestureReleaseVelocityScale: resolveNumberOption(
+			options.gestureReleaseVelocityScale,
+			DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+		),
+		gestureSnapLocked: resolveBooleanOption(
+			options.gestureSnapLocked,
+			DEFAULT_GESTURE_SNAP_LOCKED,
+		),
+		sheetSnapBehavior: resolveSheetSnapBehaviorOption(
+			options.sheetSnapBehavior,
+			DEFAULT_SHEET_SNAP_BEHAVIOR,
+		),
+		sheetScrollGestureBehavior: resolveSheetScrollGestureBehaviorOption(
+			options.sheetScrollGestureBehavior,
+			DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR,
+		),
+		backdropBehavior: resolveBackdropBehaviorOption(
+			options.backdropBehavior,
+			undefined,
+		),
+		transitionSpec: options.transitionSpec,
+	};
+};
+
+export const syncScreenOptionsBase = (
+	screenOptions: ScreenOptionsContextValue,
+	base: ScreenOptionsSnapshot,
+) => {
+	"worklet";
+	const next = {
+		...base,
+		baseOptions: base,
+	};
+
+	if (!areScreenOptionsEqual(screenOptions.get(), next)) {
+		screenOptions.set(next);
+	}
+};
+
+export const syncScreenOptionsOverrides = (
+	raw: TransitionInterpolatedStyle | undefined,
+	screenOptions: ScreenOptionsContextValue,
+) => {
+	"worklet";
+	const options = raw?.options;
+	const base = screenOptions.get().baseOptions;
+
+	const next: ScreenOptionsState = {
+		gestureEnabled: resolveBooleanOption(
+			options?.gestureEnabled,
+			base.gestureEnabled,
+		),
+		gestureTracking: base.gestureTracking,
+		gestureDirection: resolveGestureDirectionOption(
+			options?.gestureDirection,
+			base.gestureDirection,
+		),
+		gestureSensitivity: resolveNumberOption(
+			options?.gestureSensitivity,
+			base.gestureSensitivity,
+		),
+		gestureVelocityImpact: resolveNumberOption(
+			options?.gestureVelocityImpact,
+			base.gestureVelocityImpact,
+		),
+		gestureSnapVelocityImpact: resolveNumberOption(
+			options?.gestureSnapVelocityImpact,
+			base.gestureSnapVelocityImpact,
+		),
+		gestureReleaseVelocityScale: resolveNumberOption(
+			options?.gestureReleaseVelocityScale,
+			base.gestureReleaseVelocityScale,
+		),
+		gestureSnapLocked: resolveBooleanOption(
+			options?.gestureSnapLocked,
+			base.gestureSnapLocked,
+		),
+		sheetSnapBehavior: resolveSheetSnapBehaviorOption(
+			options?.sheetSnapBehavior,
+			base.sheetSnapBehavior,
+		),
+		sheetScrollGestureBehavior: resolveSheetScrollGestureBehaviorOption(
+			options?.sheetScrollGestureBehavior,
+			base.sheetScrollGestureBehavior,
+		),
+		backdropBehavior: resolveBackdropBehaviorOption(
+			options?.backdropBehavior,
+			base.backdropBehavior,
+		),
+		transitionSpec: base.transitionSpec,
+		baseOptions: base,
+	};
+
+	if (!areScreenOptionsEqual(screenOptions.get(), next)) {
+		screenOptions.set(next);
+	}
+};

package/src/providers/screen/motion/options/index.ts

@@ -0,0 +1,3 @@
+export { syncScreenOptionsOverrides } from "./helpers";
+export type { ScreenOptionsContextValue, ScreenOptionsSnapshot } from "./types";
+export { useScreenOptions } from "./use-screen-options";

package/src/providers/screen/motion/options/types.ts

@@ -0,0 +1,29 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { ScreenTransitionConfig } from "../../../../types";
+
+export type RuntimeOption<T> = SharedValue<T>;
+export type RequiredScreenOption<K extends keyof ScreenTransitionConfig> =
+	NonNullable<ScreenTransitionConfig[K]>;
+export type OptionalScreenOption<K extends keyof ScreenTransitionConfig> =
+	ScreenTransitionConfig[K];
+
+export type ScreenOptionsSnapshot = {
+	gestureEnabled: OptionalScreenOption<"gestureEnabled">;
+	gestureTracking: RequiredScreenOption<"gestureTracking">;
+	gestureDirection: RequiredScreenOption<"gestureDirection">;
+	gestureSensitivity: RequiredScreenOption<"gestureSensitivity">;
+	gestureVelocityImpact: RequiredScreenOption<"gestureVelocityImpact">;
+	gestureSnapVelocityImpact: RequiredScreenOption<"gestureSnapVelocityImpact">;
+	gestureReleaseVelocityScale: RequiredScreenOption<"gestureReleaseVelocityScale">;
+	gestureSnapLocked: RequiredScreenOption<"gestureSnapLocked">;
+	sheetSnapBehavior: RequiredScreenOption<"sheetSnapBehavior">;
+	sheetScrollGestureBehavior: RequiredScreenOption<"sheetScrollGestureBehavior">;
+	backdropBehavior: OptionalScreenOption<"backdropBehavior">;
+	transitionSpec: OptionalScreenOption<"transitionSpec">;
+};
+
+export type ScreenOptionsState = ScreenOptionsSnapshot & {
+	baseOptions: ScreenOptionsSnapshot;
+};
+
+export type ScreenOptionsContextValue = RuntimeOption<ScreenOptionsState>;

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

@@ -0,0 +1,30 @@
+import { useLayoutEffect, useMemo } from "react";
+import { useSharedValue } from "react-native-reanimated";
+import { useBuilderStore } from "../../builder";
+import { resolveBaseScreenOptions, syncScreenOptionsBase } from "./helpers";
+import type { ScreenOptionsContextValue, ScreenOptionsState } from "./types";
+
+export function useScreenOptions(): ScreenOptionsContextValue {
+	const options = useBuilderStore((store) => store.options);
+
+	const baseScreenOptions = useMemo(
+		() => resolveBaseScreenOptions(options),
+		[options],
+	);
+
+	const initialScreenOptions = useMemo<ScreenOptionsState>(
+		() => ({
+			...baseScreenOptions,
+			baseOptions: baseScreenOptions,
+		}),
+		[baseScreenOptions],
+	);
+
+	const value = useSharedValue(initialScreenOptions);
+
+	useLayoutEffect(() => {
+		syncScreenOptionsBase(value, baseScreenOptions);
+	}, [value, baseScreenOptions]);
+
+	return value;
+}

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

@@ -0,0 +1,73 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { ActiveGesture } from "../../../types/gesture.types";
+import type { MotionTransitionValues } from "./hooks/use-transition-values";
+
+export type MotionAnimationValues = {
+	transitionProgress: SharedValue<number>;
+	visualProgress: SharedValue<number>;
+	willAnimate: SharedValue<number>;
+	progressAnimating: SharedValue<number>;
+	progressSettled: SharedValue<number>;
+	closing: SharedValue<number>;
+	entering: SharedValue<number>;
+};
+
+type GestureRawValues = {
+	x: SharedValue<number>;
+	y: SharedValue<number>;
+	normX: SharedValue<number>;
+	normY: SharedValue<number>;
+	scale: SharedValue<number>;
+	normScale: SharedValue<number>;
+	rotation: SharedValue<number>;
+};
+
+type GestureSnapshotValues = {
+	x: SharedValue<number>;
+	y: SharedValue<number>;
+	normX: SharedValue<number>;
+	normY: SharedValue<number>;
+	velocity: SharedValue<number>;
+	scale: SharedValue<number>;
+	normScale: SharedValue<number>;
+	focalX: SharedValue<number>;
+	focalY: SharedValue<number>;
+	pinchOriginX: SharedValue<number>;
+	pinchOriginY: SharedValue<number>;
+	rotation: SharedValue<number>;
+	raw: GestureRawValues;
+	active: SharedValue<ActiveGesture | null>;
+};
+
+type GestureInternalValues = {
+	progressBaseline: SharedValue<number>;
+	progressDeltaX: SharedValue<number>;
+	progressDeltaY: SharedValue<number>;
+	lockedSnapPoint: SharedValue<number | null>;
+	snapshot: GestureSnapshotValues;
+};
+
+export type MotionGestureValues = {
+	x: SharedValue<number>;
+	y: SharedValue<number>;
+	normX: SharedValue<number>;
+	normY: SharedValue<number>;
+	velocity: SharedValue<number>;
+	scale: SharedValue<number>;
+	normScale: SharedValue<number>;
+	focalX: SharedValue<number>;
+	focalY: SharedValue<number>;
+	pinchOriginX: SharedValue<number>;
+	pinchOriginY: SharedValue<number>;
+	rotation: SharedValue<number>;
+	raw: GestureRawValues;
+	internal: GestureInternalValues;
+	dismissing: SharedValue<number>;
+	dragging: SharedValue<number>;
+	settling: SharedValue<number>;
+	initiator: SharedValue<ActiveGesture | null>;
+};
+
+export type MotionValues = MotionAnimationValues &
+	MotionGestureValues &
+	MotionTransitionValues;