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

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,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 };
 		}
 	}