react-native-screen-transitions 3.5.2 → 3.6.0-alpha.1

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

@@ -0,0 +1,382 @@
+import {
+	DEFAULT_GESTURE_ACTIVATION_AREA,
+	DEFAULT_GESTURE_DIRECTION,
+	DEFAULT_GESTURE_PROGRESS_MODE,
+	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 {
+	gestureProgressModeDrivesProgress,
+	isGestureProgressMode,
+	resolveGestureProgressMode,
+} from "../../../utils/gesture-progress-mode";
+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;
+};
+
+const resolveGestureProgressModeOption = (
+	gestureProgressMode: unknown,
+	gestureDrivesProgress: unknown,
+	fallback: RequiredScreenOption<"gestureProgressMode">,
+): RequiredScreenOption<"gestureProgressMode"> => {
+	"worklet";
+	if (isGestureProgressMode(gestureProgressMode)) {
+		return gestureProgressMode;
+	}
+
+	return resolveGestureProgressMode({
+		gestureDrivesProgress:
+			typeof gestureDrivesProgress === "boolean"
+				? gestureDrivesProgress
+				: undefined,
+		fallback,
+	});
+};
+
+const areGestureActivationAreasEqual = (
+	left: RequiredScreenOption<"gestureActivationArea">,
+	right: RequiredScreenOption<"gestureActivationArea">,
+) => {
+	"worklet";
+	if (left === right) return true;
+
+	if (
+		typeof left !== "object" ||
+		left === null ||
+		typeof right !== "object" ||
+		right === null
+	) {
+		return false;
+	}
+
+	return (
+		left.left === right.left &&
+		left.right === right.right &&
+		left.top === right.top &&
+		left.bottom === right.bottom
+	);
+};
+
+const areGestureDirectionsEqual = (
+	left: RequiredScreenOption<"gestureDirection">,
+	right: RequiredScreenOption<"gestureDirection">,
+) => {
+	"worklet";
+	if (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 (left[i] !== right[i]) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+const areScreenOptionsEqual = (
+	left: ScreenOptionsState,
+	right: ScreenOptionsState,
+) => {
+	"worklet";
+	return (
+		left.gestureEnabled === right.gestureEnabled &&
+		left.experimental_allowDisabledGestureTracking ===
+			right.experimental_allowDisabledGestureTracking &&
+		areGestureDirectionsEqual(left.gestureDirection, right.gestureDirection) &&
+		left.gestureSensitivity === right.gestureSensitivity &&
+		left.gestureVelocityImpact === right.gestureVelocityImpact &&
+		left.gestureSnapVelocityImpact === right.gestureSnapVelocityImpact &&
+		left.gestureReleaseVelocityScale === right.gestureReleaseVelocityScale &&
+		left.gestureResponseDistance === right.gestureResponseDistance &&
+		left.gestureProgressMode === right.gestureProgressMode &&
+		left.gestureDrivesProgress === right.gestureDrivesProgress &&
+		areGestureActivationAreasEqual(
+			left.gestureActivationArea,
+			right.gestureActivationArea,
+		) &&
+		left.gestureSnapLocked === right.gestureSnapLocked &&
+		left.sheetScrollGestureBehavior === right.sheetScrollGestureBehavior &&
+		left.backdropBehavior === right.backdropBehavior &&
+		left.baseOptions === right.baseOptions
+	);
+};
+
+export const resolveBaseScreenOptions = (
+	options: ScreenTransitionOptions,
+): ScreenOptionsSnapshot => {
+	const gestureProgressMode = resolveGestureProgressModeOption(
+		options.gestureProgressMode,
+		options.gestureDrivesProgress,
+		DEFAULT_GESTURE_PROGRESS_MODE,
+	);
+
+	return {
+		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,
+		),
+		gestureProgressMode,
+		gestureDrivesProgress:
+			gestureProgressModeDrivesProgress(gestureProgressMode),
+		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";
+	const next = {
+		...base,
+		gestureDirection: cloneGestureDirection(base.gestureDirection),
+		gestureActivationArea: cloneGestureActivationArea(
+			base.gestureActivationArea,
+		),
+		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 gestureProgressMode = resolveGestureProgressModeOption(
+		options?.gestureProgressMode,
+		options?.gestureDrivesProgress,
+		base.gestureProgressMode,
+	);
+
+	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,
+		),
+		gestureProgressMode,
+		gestureDrivesProgress:
+			gestureProgressModeDrivesProgress(gestureProgressMode),
+		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,
+	};
+
+	if (!areScreenOptionsEqual(screenOptions.get(), next)) {
+		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,36 @@
+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">;
+	gestureProgressMode: RequiredScreenOption<"gestureProgressMode">;
+	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,7 +12,6 @@ export const MaybeFloatingContainer = memo(function MaybeFloatingContainer({
 	if (!isFloatingOverlay) {
 		return children;
 	}
-
 	return (
 		<View
 			style={[StyleSheet.absoluteFill, styles.float]}

package/src/shared/providers/screen/styles/constants.ts

@@ -3,20 +3,66 @@ import {
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
 } from "../../../constants";
 
-export const IDENTITY_TRANSFORM = [
+const IDENTITY_TRANSFORM = [
 	{ translateX: 0 },
 	{ translateY: 0 },
+	{ scale: 1 },
 	{ scaleX: 1 },
 	{ scaleY: 1 },
 ] as const;
 
-export const ALWAYS_RESET_STYLE_VALUES = {
+/**
+ * Safe identity resets for transition-owned style props.
+ *
+ * This list should stay limited to props with a predictable neutral value after
+ * an animation finishes. Avoid layout-owning props such as width, height, top,
+ * left, margin, padding, flex, or aspectRatio; resetting those to zero can clip
+ * or collapse user layout. If another visual-only transition prop needs cleanup,
+ * please add its identity value here in a PR.
+ */
+export const STYLE_RESET_VALUES: Record<string, unknown> = {
+	transform: IDENTITY_TRANSFORM,
+	translateX: 0,
+	translateY: 0,
+	scale: 1,
+	scaleX: 1,
+	scaleY: 1,
 	opacity: 1,
 	zIndex: 0,
 	elevation: 0,
-} as const;
+	overflow: "visible",
+	backgroundColor: "transparent",
+	borderColor: "transparent",
+	borderTopColor: "transparent",
+	borderRightColor: "transparent",
+	borderBottomColor: "transparent",
+	borderLeftColor: "transparent",
+	borderStartColor: "transparent",
+	borderEndColor: "transparent",
+	borderRadius: 0,
+	borderTopLeftRadius: 0,
+	borderTopRightRadius: 0,
+	borderBottomRightRadius: 0,
+	borderBottomLeftRadius: 0,
+	borderTopStartRadius: 0,
+	borderTopEndRadius: 0,
+	borderBottomStartRadius: 0,
+	borderBottomEndRadius: 0,
+	borderStartStartRadius: 0,
+	borderStartEndRadius: 0,
+	borderEndStartRadius: 0,
+	borderEndEndRadius: 0,
+	shadowColor: "transparent",
+	shadowOffset: { width: 0, height: 0 },
+	shadowOpacity: 0,
+	shadowRadius: 0,
+};
+
+export const PROP_RESET_VALUES: Record<string, unknown> = {
+	pointerEvents: "auto",
+};
 
-export const LOCAL_ONLY_STYLE_SLOT_IDS = {
+const LOCAL_ONLY_STYLE_SLOT_IDS = {
 	content: true,
 	backdrop: true,
 	surface: true,

package/src/shared/providers/screen/styles/helpers/normalize-slots.ts

@@ -30,11 +30,21 @@ const isAlreadyNormalizedStyleMap = (raw: Record<string, any>) => {
 	return true;
 };
 
+/**
+ * Normalizes an interpolator result into the canonical `{ style, props }` slot format.
+ *
+ * Handles three cases per key:
+ * 1. Proper `TransitionSlotStyle` values (has `style` or `props` key) — pass through
+ * 2. Style shorthand (plain StyleProps without wrapping) — auto-wrapped as `{ style: value }`
+ */
 export function normalizeSlots(
 	raw: Record<string, any>,
 ): NormalizedTransitionInterpolatedStyle {
 	"worklet";
 
+	// Most modern interpolators already return the canonical `{ style, props }`
+	// slot shape. In that common case, we can forward the raw object directly and
+	// avoid building a second map just to copy the same slot references over.
 	if (isAlreadyNormalizedStyleMap(raw)) {
 		return raw as NormalizedTransitionInterpolatedStyle;
 	}
@@ -45,14 +55,17 @@ export function normalizeSlots(
 	for (const key in raw) {
 		const value = raw[key];
 
+		// ── All other keys ──
 		if (value === undefined) {
 			normalized[key] = undefined;
 			continue;
 		}
 
 		if (isExplicitTransitionSlot(value)) {
+			// Proper TransitionSlotStyle — pass through
 			normalized[key] = value as NormalizedTransitionSlotStyle;
 		} else {
+			// Shorthand: plain StyleProps — wrap it
 			normalized[key] = { style: value };
 		}
 	}

package/src/shared/providers/screen/styles/helpers/preserve-animated-props-only.ts

@@ -0,0 +1,22 @@
+import { NO_STYLES } from "../../../../constants";
+import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
+
+export const preserveAnimatedPropsOnly = (
+	stylesMap: NormalizedTransitionInterpolatedStyle,
+): NormalizedTransitionInterpolatedStyle => {
+	"worklet";
+	let hasProps = false;
+	const propsOnly: NormalizedTransitionInterpolatedStyle = {};
+
+	for (const slotId in stylesMap) {
+		const slot = stylesMap[slotId];
+		if (!slot || slot.props === undefined) {
+			continue;
+		}
+
+		propsOnly[slotId] = { props: slot.props };
+		hasProps = true;
+	}
+
+	return hasProps ? propsOnly : NO_STYLES;
+};