react-native-screen-transitions 3.5.1 → 3.6.0-alpha.0

package/src/shared/providers/screen/gestures/types.ts

@@ -0,0 +1,222 @@
+import type {
+	Gesture,
+	GestureStateChangeEvent,
+	GestureUpdateEvent,
+	PanGestureHandlerEventPayload,
+	PinchGestureHandlerEventPayload,
+} from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+import type { GestureStoreMap } from "../../../stores/gesture.store";
+import type { SystemStoreMap } from "../../../stores/system.store";
+import type {
+	AnimationConfig,
+	TransitionSpec,
+} from "../../../types/animation.types";
+import type {
+	GestureActivationArea,
+	GestureDirections,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	SnapPanDirectionConfig,
+	SnapPinchDirectionConfig,
+} from "../../../types/gesture.types";
+import type {
+	ClaimedDirections,
+	DirectionOwnership,
+} from "../../../types/ownership.types";
+import type { ScreenTransitionConfig } from "../../../types/screen.types";
+import type { EffectiveSnapPointsResult } from "./helpers/validate-snap-points";
+
+export type PanGesture = ReturnType<typeof Gesture.Pan>;
+export type PinchGesture = ReturnType<typeof Gesture.Pinch>;
+export type ComposedGesture = ReturnType<typeof Gesture.Race>;
+
+export type PanGestureEvent =
+	| GestureUpdateEvent<PanGestureHandlerEventPayload>
+	| GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+
+export type PinchGestureEvent =
+	| GestureUpdateEvent<PinchGestureHandlerEventPayload>
+	| GestureStateChangeEvent<PinchGestureHandlerEventPayload>;
+
+export type { ScrollGestureAxis, ScrollGestureAxisState, ScrollGestureState };
+
+export type DirectionClaim = {
+	routeKey: string;
+	isDismissing: SharedValue<number>;
+} | null;
+
+export type DirectionClaimMap = {
+	vertical: DirectionClaim;
+	"vertical-inverted": DirectionClaim;
+	horizontal: DirectionClaim;
+	"horizontal-inverted": DirectionClaim;
+};
+
+export const NO_CLAIMS: DirectionClaimMap = {
+	vertical: null,
+	"vertical-inverted": null,
+	horizontal: null,
+	"horizontal-inverted": null,
+};
+
+export interface GestureContextType {
+	routeKey: string;
+	detectorGesture: ComposedGesture;
+	panGesture: PanGesture;
+	pinchGesture: PinchGesture;
+	scrollState: SharedValue<ScrollGestureState | null>;
+	gestureContext: GestureContextType | null;
+	claimedDirections: ClaimedDirections;
+	childDirectionClaims: SharedValue<DirectionClaimMap>;
+}
+
+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;
+	ownershipStatus: DirectionOwnership;
+}
+
+export interface ScreenGestureConfig {
+	participation: ScreenGestureParticipation;
+	pan: PanGesturePolicy;
+	pinch: PinchGesturePolicy;
+}
+
+export interface PanGesturePolicy {
+	enabled: boolean;
+	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>;
+	panActivationDirections: GestureDirections;
+	snapAxisDirections: SnapPanDirectionConfig;
+	gestureDrivesProgress: boolean;
+	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
+	gestureVelocityImpact: number;
+	gestureSnapVelocityImpact: number;
+	gestureReleaseVelocityScale: number;
+	/** @deprecated v3 compatibility only. Removed in the next gesture runtime. */
+	gestureReleaseVelocityMax: number;
+	gestureActivationArea: GestureActivationArea;
+	gestureSnapLocked: boolean;
+	sheetScrollGestureBehavior: NonNullable<
+		ScreenTransitionConfig["sheetScrollGestureBehavior"]
+	>;
+	gestureResponseDistance: ScreenTransitionConfig["gestureResponseDistance"];
+	transitionSpec: TransitionSpec | undefined;
+}
+
+export interface PinchGesturePolicy {
+	enabled: boolean;
+	gestureDirection: NonNullable<ScreenTransitionConfig["gestureDirection"]>;
+	snapDirections: SnapPinchDirectionConfig;
+	pinchInEnabled: boolean;
+	pinchOutEnabled: boolean;
+	gestureDrivesProgress: boolean;
+	gestureSensitivity: NonNullable<ScreenTransitionConfig["gestureSensitivity"]>;
+	gestureSnapVelocityImpact: number;
+	gestureSnapLocked: boolean;
+	gestureReleaseVelocityScale: number;
+	/** @deprecated v3 compatibility only. Removed in the next gesture runtime. */
+	gestureReleaseVelocityMax: number;
+	transitionSpec: TransitionSpec | undefined;
+}
+
+export interface GestureRuntimeStores {
+	gestures: GestureStoreMap;
+	animations: AnimationStoreMap;
+	system: SystemStoreMap;
+}
+
+export interface PanGestureRuntime {
+	participation: ScreenGestureParticipation;
+	policy: PanGesturePolicy;
+	stores: GestureRuntimeStores;
+	gestureProgressBaseline: SharedValue<number>;
+	lockedSnapPoint: SharedValue<number>;
+}
+
+export interface PinchGestureRuntime {
+	participation: ScreenGestureParticipation;
+	policy: PinchGesturePolicy;
+	stores: GestureRuntimeStores;
+	gestureProgressBaseline: SharedValue<number>;
+	lockedSnapPoint: SharedValue<number>;
+}
+
+export interface GestureDimensions {
+	width: number;
+	height: number;
+}
+
+export interface PanTrackState {
+	x: number;
+	y: number;
+	normX: number;
+	normY: number;
+}
+
+export interface PinchTrackState {
+	scale: number;
+	normScale: number;
+}
+
+export interface PanReleaseResult {
+	target: number;
+	shouldDismiss: boolean;
+	initialVelocity: number;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PinchReleaseResult {
+	target: number;
+	shouldDismiss: boolean;
+	initialVelocity: number;
+	transitionSpec: TransitionSpec | undefined;
+	resetSpec: AnimationConfig | undefined;
+}
+
+export interface PanBehaviorStrategy {
+	primeStart: (runtime: PanGestureRuntime) => void;
+	resolveProgress: (
+		runtime: PanGestureRuntime,
+		dimensions: GestureDimensions,
+		track: PanTrackState,
+	) => number;
+	resolveRelease: (
+		event: PanGestureEvent,
+		runtime: PanGestureRuntime,
+		dimensions: GestureDimensions,
+	) => PanReleaseResult;
+}
+
+export interface PinchBehaviorStrategy {
+	primeStart: (runtime: PinchGestureRuntime) => void;
+	resolveProgress: (
+		runtime: PinchGestureRuntime,
+		track: PinchTrackState,
+	) => number;
+	resolveRelease: (
+		event: PinchGestureEvent,
+		runtime: PinchGestureRuntime,
+	) => PinchReleaseResult;
+}
+
+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/shared/providers/screen/options/helpers.ts

@@ -0,0 +1,271 @@
+import {
+	DEFAULT_GESTURE_ACTIVATION_AREA,
+	DEFAULT_GESTURE_DIRECTION,
+	DEFAULT_GESTURE_DRIVES_PROGRESS,
+	DEFAULT_GESTURE_RELEASE_VELOCITY_SCALE,
+	DEFAULT_GESTURE_SENSITIVITY,
+	DEFAULT_GESTURE_SNAP_LOCKED,
+	DEFAULT_GESTURE_SNAP_VELOCITY_IMPACT,
+	DEFAULT_GESTURE_VELOCITY_IMPACT,
+	DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR,
+} from "../../../constants";
+import type {
+	ActivationArea,
+	GestureActivationArea,
+	GestureDirection,
+	ScreenTransitionOptions,
+	TransitionInterpolatedStyle,
+} from "../../../types";
+import type { BackdropBehavior } from "../../../types/screen.types";
+import { resolveSheetScrollGestureBehavior } from "../../../utils/resolve-screen-transition-options";
+import type {
+	RequiredScreenOption,
+	ScreenOptionsContextValue,
+	ScreenOptionsSnapshot,
+	ScreenOptionsState,
+} from "./types";
+
+const cloneGestureDirection = (
+	direction: RequiredScreenOption<"gestureDirection">,
+) => {
+	"worklet";
+	return Array.isArray(direction) ? [...direction] : direction;
+};
+
+const cloneGestureActivationArea = (
+	activationArea: RequiredScreenOption<"gestureActivationArea">,
+) => {
+	"worklet";
+	return typeof activationArea === "object" && activationArea !== null
+		? { ...activationArea }
+		: activationArea;
+};
+
+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 resolveGestureDirectionOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"gestureDirection">,
+): RequiredScreenOption<"gestureDirection"> => {
+	"worklet";
+	if (isGestureDirection(value)) {
+		return value;
+	}
+	if (Array.isArray(value) && value.every(isGestureDirection)) {
+		return [...value];
+	}
+	return cloneGestureDirection(fallback);
+};
+
+const isActivationArea = (value: unknown): value is ActivationArea => {
+	"worklet";
+	return value === "edge" || value === "screen";
+};
+
+const resolveGestureActivationAreaOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"gestureActivationArea">,
+): RequiredScreenOption<"gestureActivationArea"> => {
+	"worklet";
+	if (isActivationArea(value)) {
+		return value;
+	}
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+		const area = value as Record<string, unknown>;
+		const isValid =
+			(area.left === undefined || isActivationArea(area.left)) &&
+			(area.right === undefined || isActivationArea(area.right)) &&
+			(area.top === undefined || isActivationArea(area.top)) &&
+			(area.bottom === undefined || isActivationArea(area.bottom));
+		return isValid ? (area as GestureActivationArea) : fallback;
+	}
+	return cloneGestureActivationArea(fallback);
+};
+
+const resolveSheetScrollGestureBehaviorOption = (
+	value: unknown,
+	fallback: RequiredScreenOption<"sheetScrollGestureBehavior">,
+): RequiredScreenOption<"sheetScrollGestureBehavior"> => {
+	"worklet";
+	return value === "expand-and-collapse" || value === "collapse-only"
+		? value
+		: fallback;
+};
+
+const resolveBackdropBehaviorOption = (
+	value: unknown,
+	fallback: BackdropBehavior | undefined,
+): BackdropBehavior | undefined => {
+	"worklet";
+	return value === "block" ||
+		value === "passthrough" ||
+		value === "dismiss" ||
+		value === "collapse"
+		? value
+		: fallback;
+};
+
+export const resolveBaseScreenOptions = (
+	options: ScreenTransitionOptions,
+): ScreenOptionsSnapshot => ({
+	gestureEnabled: resolveBooleanOption(options.gestureEnabled, undefined),
+	experimental_allowDisabledGestureTracking: resolveBooleanOption(
+		options.experimental_allowDisabledGestureTracking,
+		false,
+	),
+	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,
+	),
+	gestureResponseDistance: resolveNumberOption(
+		options.gestureResponseDistance,
+		undefined,
+	),
+	gestureDrivesProgress: resolveBooleanOption(
+		options.gestureDrivesProgress,
+		DEFAULT_GESTURE_DRIVES_PROGRESS,
+	),
+	gestureActivationArea: resolveGestureActivationAreaOption(
+		options.gestureActivationArea,
+		DEFAULT_GESTURE_ACTIVATION_AREA,
+	),
+	gestureSnapLocked: resolveBooleanOption(
+		options.gestureSnapLocked,
+		DEFAULT_GESTURE_SNAP_LOCKED,
+	),
+	sheetScrollGestureBehavior: resolveSheetScrollGestureBehaviorOption(
+		resolveSheetScrollGestureBehavior(options),
+		DEFAULT_SHEET_SCROLL_GESTURE_BEHAVIOR,
+	),
+	backdropBehavior: resolveBackdropBehaviorOption(
+		options.backdropBehavior,
+		undefined,
+	),
+});
+
+export const syncScreenOptionsBase = (
+	screenOptions: ScreenOptionsContextValue,
+	base: ScreenOptionsSnapshot,
+) => {
+	"worklet";
+	screenOptions.set({
+		...base,
+		gestureDirection: cloneGestureDirection(base.gestureDirection),
+		gestureActivationArea: cloneGestureActivationArea(
+			base.gestureActivationArea,
+		),
+		baseOptions: base,
+	});
+};
+
+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,
+		),
+		experimental_allowDisabledGestureTracking: resolveBooleanOption(
+			options?.experimental_allowDisabledGestureTracking,
+			base.experimental_allowDisabledGestureTracking,
+		),
+		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,
+		),
+		gestureResponseDistance: resolveNumberOption(
+			options?.gestureResponseDistance,
+			base.gestureResponseDistance,
+		),
+		gestureDrivesProgress: resolveBooleanOption(
+			options?.gestureDrivesProgress,
+			base.gestureDrivesProgress,
+		),
+		gestureActivationArea: resolveGestureActivationAreaOption(
+			options?.gestureActivationArea,
+			base.gestureActivationArea,
+		),
+		gestureSnapLocked: resolveBooleanOption(
+			options?.gestureSnapLocked,
+			base.gestureSnapLocked,
+		),
+		sheetScrollGestureBehavior: resolveSheetScrollGestureBehaviorOption(
+			options?.sheetScrollGestureBehavior,
+			base.sheetScrollGestureBehavior,
+		),
+		backdropBehavior: resolveBackdropBehaviorOption(
+			options?.backdropBehavior,
+			base.backdropBehavior,
+		),
+		baseOptions: base,
+	};
+
+	screenOptions.set(next);
+};

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

@@ -0,0 +1,6 @@
+export { syncScreenOptionsOverrides } from "./helpers";
+export {
+	ScreenOptionsProvider,
+	useScreenOptionsContext,
+} from "./options.provider";
+export type { ScreenOptionsContextValue, ScreenOptionsSnapshot } from "./types";

package/src/shared/providers/screen/options/options.provider.tsx

@@ -0,0 +1,43 @@
+import { useLayoutEffect, useMemo } from "react";
+import { useSharedValue } from "react-native-reanimated";
+import createProvider from "../../../utils/create-provider";
+import { useDescriptors } from "../descriptors";
+import { resolveBaseScreenOptions, syncScreenOptionsBase } from "./helpers";
+import type {
+	ScreenOptionsContextValue,
+	ScreenOptionsProviderProps,
+	ScreenOptionsState,
+} from "./types";
+
+export const { ScreenOptionsProvider, useScreenOptionsContext } =
+	createProvider("ScreenOptions")<
+		ScreenOptionsProviderProps,
+		ScreenOptionsContextValue
+	>(() => {
+		const {
+			current: { options },
+		} = useDescriptors();
+
+		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/shared/providers/screen/options/types.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { ScreenTransitionOptions } from "../../../types";
+
+export type RuntimeOption<T> = SharedValue<T>;
+export type RequiredScreenOption<K extends keyof ScreenTransitionOptions> =
+	NonNullable<ScreenTransitionOptions[K]>;
+export type OptionalScreenOption<K extends keyof ScreenTransitionOptions> =
+	ScreenTransitionOptions[K];
+
+export type ScreenOptionsSnapshot = {
+	gestureEnabled: OptionalScreenOption<"gestureEnabled">;
+	experimental_allowDisabledGestureTracking: RequiredScreenOption<"experimental_allowDisabledGestureTracking">;
+	gestureDirection: RequiredScreenOption<"gestureDirection">;
+	gestureSensitivity: RequiredScreenOption<"gestureSensitivity">;
+	gestureVelocityImpact: RequiredScreenOption<"gestureVelocityImpact">;
+	gestureSnapVelocityImpact: RequiredScreenOption<"gestureSnapVelocityImpact">;
+	gestureReleaseVelocityScale: RequiredScreenOption<"gestureReleaseVelocityScale">;
+	gestureResponseDistance: OptionalScreenOption<"gestureResponseDistance">;
+	gestureDrivesProgress: RequiredScreenOption<"gestureDrivesProgress">;
+	gestureActivationArea: RequiredScreenOption<"gestureActivationArea">;
+	gestureSnapLocked: RequiredScreenOption<"gestureSnapLocked">;
+	sheetScrollGestureBehavior: RequiredScreenOption<"sheetScrollGestureBehavior">;
+	backdropBehavior: OptionalScreenOption<"backdropBehavior">;
+};
+
+export type ScreenOptionsState = ScreenOptionsSnapshot & {
+	baseOptions: ScreenOptionsSnapshot;
+};
+
+export type ScreenOptionsContextValue = RuntimeOption<ScreenOptionsState>;
+
+export interface ScreenOptionsProviderProps {
+	children: ReactNode;
+}

package/src/shared/providers/screen/screen-composer.tsx

@@ -1,9 +1,10 @@
 import type React from "react";
 import { ScreenContainer } from "../../components/screen-container";
 import { ScreenLifecycle } from "../../components/screen-lifecycle";
-import { ScreenGestureProvider } from "../gestures";
 import { ScreenAnimationProvider } from "./animation";
 import { type BaseDescriptor, DescriptorsProvider } from "./descriptors";
+import { ScreenGestureProvider } from "./gestures";
+import { ScreenOptionsProvider } from "./options";
 import { ScreenStylesProvider } from "./styles";
 
 type Props<TDescriptor extends BaseDescriptor> = {
@@ -22,13 +23,15 @@ export function ScreenComposer<TDescriptor extends BaseDescriptor>({
 	return (
 		<DescriptorsProvider previous={previous} current={current} next={next}>
 			<ScreenLifecycle>
-				<ScreenGestureProvider>
-					<ScreenAnimationProvider>
-						<ScreenStylesProvider>
-							<ScreenContainer>{children}</ScreenContainer>
-						</ScreenStylesProvider>
-					</ScreenAnimationProvider>
-				</ScreenGestureProvider>
+				<ScreenOptionsProvider>
+					<ScreenGestureProvider>
+						<ScreenAnimationProvider>
+							<ScreenStylesProvider>
+								<ScreenContainer>{children}</ScreenContainer>
+							</ScreenStylesProvider>
+						</ScreenAnimationProvider>
+					</ScreenGestureProvider>
+				</ScreenOptionsProvider>
 			</ScreenLifecycle>
 		</DescriptorsProvider>
 	);

package/src/shared/providers/screen/styles/components/maybe-floating-container.tsx

@@ -5,7 +5,6 @@ interface MaybeFloatingContainerProps {
 	children: React.ReactNode;
 	isFloatingOverlay?: boolean;
 }
-
 export const MaybeFloatingContainer = memo(function MaybeFloatingContainer({
 	children,
 	isFloatingOverlay,
@@ -13,9 +12,11 @@ export const MaybeFloatingContainer = memo(function MaybeFloatingContainer({
 	if (!isFloatingOverlay) {
 		return children;
 	}
-
 	return (
-		<View style={styles.float} pointerEvents="box-none">
+		<View
+			style={[StyleSheet.absoluteFill, styles.float]}
+			pointerEvents="box-none"
+		>
 			{children}
 		</View>
 	);
@@ -23,7 +24,6 @@ export const MaybeFloatingContainer = memo(function MaybeFloatingContainer({
 
 const styles = StyleSheet.create({
 	float: {
-		...StyleSheet.absoluteFillObject,
 		zIndex: 999,
 	},
 });