react-native-screen-transitions 3.9.0-alpha.3 → 3.9.0-beta.0

package/src/shared/components/screen-container/layers/backdrop.tsx

@@ -1,4 +1,4 @@
-import { memo, useCallback, useMemo } from "react";
+import { type ComponentType, memo, useCallback, useMemo } from "react";
 import { Pressable, StyleSheet } from "react-native";
 import Animated, { runOnUI } from "react-native-reanimated";
 import { DefaultSnapSpec } from "../../../configs/specs";
@@ -8,9 +8,13 @@ import { useSlotProps, useSlotStyles } from "../../../providers/screen/styles";
 import { AnimationStore } from "../../../stores/animation.store";
 import { GestureStore } from "../../../stores/gesture.store";
 import { SystemStore } from "../../../stores/system.store";
-import type { BackdropBehavior } from "../../../types/screen.types";
+import type {
+	BackdropBehavior,
+	ScreenBackdropComponentProps,
+} from "../../../types/screen.types";
 import { animateToProgress } from "../../../utils/animation/animate-to-progress";
 import { findCollapseTarget } from "../helpers/find-collapse-target";
+import { usesLayerRenderProps } from "./render-component";
 
 export const BackdropLayer = memo(function BackdropLayer({
 	backdropBehavior,
@@ -30,8 +34,10 @@ export const BackdropLayer = memo(function BackdropLayer({
 
 	const AnimatedBackdropComponent = useMemo(
 		() =>
-			BackdropComponent
-				? Animated.createAnimatedComponent(BackdropComponent)
+			BackdropComponent && !usesLayerRenderProps(BackdropComponent)
+				? Animated.createAnimatedComponent(
+						BackdropComponent as ComponentType<any>,
+					)
 				: null,
 		[BackdropComponent],
 	);
@@ -108,6 +114,13 @@ export const BackdropLayer = memo(function BackdropLayer({
 
 	const animatedBackdropStyle = useSlotStyles("backdrop");
 	const animatedBackdropProps = useSlotProps("backdrop");
+	const backdropPointerEvents = isBackdropActive ? "auto" : "none";
+	const backdropStyles = [
+		StyleSheet.absoluteFill,
+		animatedBackdropStyle,
+	] as ScreenBackdropComponentProps["styles"];
+	const backdropProps =
+		animatedBackdropProps as ScreenBackdropComponentProps["props"];
 
 	return (
 		<Pressable
@@ -115,16 +128,24 @@ export const BackdropLayer = memo(function BackdropLayer({
 			pointerEvents={isBackdropActive ? "auto" : "none"}
 			onPress={isBackdropActive ? handleBackdropPress : undefined}
 		>
-			{/* Keep blur props and visual style separated.
-			 * BlurView's animatable ref points at the inner native blur view, and mixing
-			 * animated style with animatedProps can break intensity updates. */}
-			{AnimatedBackdropComponent && (
+			{AnimatedBackdropComponent ? (
 				<AnimatedBackdropComponent
-					style={[StyleSheet.absoluteFill]}
+					style={backdropStyles}
 					animatedProps={animatedBackdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : BackdropComponent ? (
+				<BackdropComponent
+					styles={backdropStyles}
+					props={backdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : (
+				<Animated.View
+					style={backdropStyles}
+					pointerEvents={backdropPointerEvents}
 				/>
 			)}
-			<Animated.View style={[StyleSheet.absoluteFill, animatedBackdropStyle]} />
 		</Pressable>
 	);
 });

package/src/shared/components/screen-container/layers/content.tsx

@@ -1,5 +1,5 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <Screen gesture is under the gesture context, so this will always exist.> */
-import { memo } from "react";
+import { type ComponentType, memo, useMemo } from "react";
 import { StyleSheet, View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated from "react-native-reanimated";
@@ -7,9 +7,11 @@ import { useDescriptors } from "../../../providers/screen/descriptors";
 import { useGestureContext } from "../../../providers/screen/gestures";
 import { OriginProvider } from "../../../providers/screen/origin.provider";
 import { useSlotProps, useSlotStyles } from "../../../providers/screen/styles";
+import type { ScreenContentComponentProps } from "../../../types";
 import { ScreenFallbackHost } from "../../boundary/portal/components/host";
 import { useContentLayout } from "../hooks/use-content-layout";
 import { MaybeMaskedNavigationContainer } from "./maybe-masked-navigation-container";
+import { usesLayerRenderProps } from "./render-component";
 import { SurfaceContainer } from "./surface-container";
 
 type Props = {
@@ -23,9 +25,18 @@ export const ContentLayer = memo(
 		const { current } = useDescriptors();
 
 		const gestureContext = useGestureContext();
+		const ContentComponent = current.options.contentComponent;
 		const isNavigationMaskEnabled = !!current.options.navigationMaskEnabled;
 		const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
 
+		const AnimatedContentComponent = useMemo(() => {
+			return ContentComponent && !usesLayerRenderProps(ContentComponent)
+				? Animated.createAnimatedComponent(
+						ContentComponent as ComponentType<any>,
+					)
+				: null;
+		}, [ContentComponent]);
+
 		const hasAutoSnapPoint =
 			current.options.snapPoints?.includes("auto") ?? false;
 
@@ -33,32 +44,60 @@ export const ContentLayer = memo(
 
 		const animatedContentStyle = useSlotStyles("content");
 		const animatedContentProps = useSlotProps("content");
+		const contentStyles = [
+			styles.content,
+			animatedContentStyle,
+		] as ScreenContentComponentProps["styles"];
+		const contentProps =
+			animatedContentProps as ScreenContentComponentProps["props"];
+
+		const contentChildren = (
+			<MaybeMaskedNavigationContainer
+				pointerEvents={contentPointerEvents}
+				enabled={isNavigationMaskEnabled}
+			>
+				<SurfaceContainer pointerEvents={contentPointerEvents}>
+					<OriginProvider>
+						{hasAutoSnapPoint ? (
+							<View collapsable={false} onLayout={handleContentLayout}>
+								{children}
+							</View>
+						) : (
+							children
+						)}
+						<ScreenFallbackHost />
+					</OriginProvider>
+				</SurfaceContainer>
+			</MaybeMaskedNavigationContainer>
+		);
 
 		return (
 			<GestureDetector gesture={gestureContext!.detectorGesture}>
-				<Animated.View
-					style={[styles.content, animatedContentStyle]}
-					animatedProps={animatedContentProps}
-					pointerEvents={contentPointerEvents}
-				>
-					<MaybeMaskedNavigationContainer
+				{AnimatedContentComponent ? (
+					<AnimatedContentComponent
+						style={contentStyles}
+						animatedProps={animatedContentProps}
+						pointerEvents={contentPointerEvents}
+					>
+						{contentChildren}
+					</AnimatedContentComponent>
+				) : ContentComponent ? (
+					<ContentComponent
+						styles={contentStyles}
+						props={contentProps}
+						pointerEvents={contentPointerEvents}
+					>
+						{contentChildren}
+					</ContentComponent>
+				) : (
+					<Animated.View
+						style={contentStyles}
+						animatedProps={animatedContentProps}
 						pointerEvents={contentPointerEvents}
-						enabled={isNavigationMaskEnabled}
 					>
-						<SurfaceContainer pointerEvents={contentPointerEvents}>
-							<OriginProvider>
-								{hasAutoSnapPoint ? (
-									<View collapsable={false} onLayout={handleContentLayout}>
-										{children}
-									</View>
-								) : (
-									children
-								)}
-								<ScreenFallbackHost />
-							</OriginProvider>
-						</SurfaceContainer>
-					</MaybeMaskedNavigationContainer>
-				</Animated.View>
+						{contentChildren}
+					</Animated.View>
+				)}
 			</GestureDetector>
 		);
 	},

package/src/shared/components/screen-container/layers/render-component.ts

@@ -0,0 +1,9 @@
+import type { ComponentType } from "react";
+
+export function usesLayerRenderProps(
+	component: ComponentType<any>,
+): component is ComponentType<Record<string, unknown>> {
+	return (
+		typeof component === "function" && !component.prototype?.isReactComponent
+	);
+}

package/src/shared/components/screen-container/layers/surface-container.tsx

@@ -12,13 +12,14 @@ type Props = {
 export const SurfaceContainer = memo(({ children, pointerEvents }: Props) => {
 	const { current } = useDescriptors();
 
-	const SurfaceComponent = current.options.surfaceComponent;
+	/** @deprecated Use `contentComponent` instead. */
+	const DeprecatedSurfaceComponent = current.options.surfaceComponent;
 
 	const AnimatedSurfaceComponent = useMemo<ComponentType<any> | null>(() => {
-		return SurfaceComponent
-			? Animated.createAnimatedComponent(SurfaceComponent)
+		return DeprecatedSurfaceComponent
+			? Animated.createAnimatedComponent(DeprecatedSurfaceComponent)
 			: null;
-	}, [SurfaceComponent]);
+	}, [DeprecatedSurfaceComponent]);
 
 	if (!AnimatedSurfaceComponent) return children;
 

package/src/shared/index.ts

@@ -18,6 +18,10 @@ export default {
 	FlatList: createTransitionAwareComponent(FlatList, {
 		isScrollable: true,
 	}),
+	/**
+	 * @deprecated Use `navigationMaskEnabled` with the navigation mask style IDs
+	 * instead.
+	 */
 	MaskedView: MaskedView,
 	Presets,
 	Specs,
@@ -63,7 +67,12 @@ export type {
 	InactiveBehavior,
 	OverlayProps,
 	RawGestureValues,
+	ScreenBackdropComponent,
+	ScreenBackdropComponentProps,
+	ScreenContentComponent,
+	ScreenContentComponentProps,
 	ScreenInterpolationProps,
+	ScreenLayerComponentProps,
 	ScreenStyleInterpolator,
 	ScreenTransitionAccessor,
 	ScreenTransitionConfig,

package/src/shared/providers/register-bounds.provider.tsx

@@ -25,6 +25,11 @@ import createProvider from "../utils/create-provider";
 import { applyMeasuredBoundsWrites } from "./helpers/measured-bounds-writes";
 import { useDescriptorDerivations, useDescriptors } from "./screen/descriptors";
 
+/**
+ * @deprecated Internal legacy provider for the old shared-bound-tag registration
+ * path. Do not build new boundary behavior here; use the Transition.Boundary
+ * measurement pipeline instead.
+ */
 interface MaybeMeasureAndStoreParams {
 	onPress?: ((...args: unknown[]) => void) | undefined;
 	shouldSetSource?: boolean;

package/src/shared/types/index.ts

@@ -54,7 +54,12 @@ export type {
 	GestureTracking,
 	InactiveBehavior,
 	Layout,
+	ScreenBackdropComponent,
+	ScreenBackdropComponentProps,
+	ScreenContentComponent,
+	ScreenContentComponentProps,
 	ScreenKey,
+	ScreenLayerComponentProps,
 	ScreenTransitionConfig,
 	TransitionAwareProps,
 } from "./screen.types";

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

@@ -1,3 +1,5 @@
+import type { ComponentType, ReactNode } from "react";
+import type { ViewProps } from "react-native";
 import type { AnimatedProps } from "react-native-reanimated";
 import type {
 	ScreenStyleInterpolator,
@@ -51,6 +53,71 @@ export type SnapPoint = number | "auto";
 
 export type BackdropBehavior = "block" | "passthrough" | "dismiss" | "collapse";
 
+/**
+ * Props passed to custom screen layer component renderers such as
+ * {@linkcode ScreenTransitionConfig.backdropComponent}.
+ */
+export type ScreenLayerComponentProps = {
+	/**
+	 * Animated styles for the target layer, including the library-owned base
+	 * layout style for that layer.
+	 */
+	styles: AnimatedProps<ViewProps>["style"];
+
+	/**
+	 * Animated props resolved from the matching `screenStyleInterpolator` slot.
+	 */
+	props: AnimatedProps<Record<string, unknown>>["animatedProps"];
+
+	/**
+	 * Pointer-event behavior resolved for the current layer state.
+	 */
+	pointerEvents: ViewProps["pointerEvents"];
+};
+
+/**
+ * Props passed to {@linkcode ScreenTransitionConfig.backdropComponent} when it
+ * is provided as a render-style component.
+ */
+export type ScreenBackdropComponentProps = ScreenLayerComponentProps;
+
+/**
+ * Props passed to {@linkcode ScreenTransitionConfig.contentComponent} when it
+ * is provided as a render-style component.
+ */
+export type ScreenContentComponentProps = ScreenLayerComponentProps & {
+	/**
+	 * The screen subtree rendered inside the content layer.
+	 */
+	children: ReactNode;
+};
+
+/**
+ * Custom renderer for the backdrop layer.
+ *
+ * Component types such as `BlurView` are still accepted for compatibility.
+ * Function components can also receive {@linkcode ScreenBackdropComponentProps}
+ * to render the animated styles and props manually.
+ *
+ * @see {@linkcode ScreenTransitionConfig.backdropComponent}
+ */
+export type ScreenBackdropComponent =
+	| ComponentType<any>
+	| ComponentType<ScreenBackdropComponentProps>;
+
+/**
+ * Custom renderer for the screen content layer.
+ *
+ * Component types such as a custom native view are accepted directly. Function
+ * components can also receive {@linkcode ScreenContentComponentProps} to render
+ * the animated styles, props, pointer-events, and children manually.
+ *
+ * @see {@linkcode ScreenTransitionConfig.contentComponent}
+ */
+export type ScreenContentComponent =
+	| ComponentType<any>
+	| ComponentType<ScreenContentComponentProps>;
+
 /**
  * Controls how an inactive screen is retained after it is no longer active.
  *
@@ -117,6 +184,8 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * <Transition.View sharedBoundTag="profile-avatar">
 	 *   <Avatar size="large" />
 	 * </Transition.View>
+	 *
+	 * @deprecated Use `Transition.Boundary` with `id` instead.
 	 */
 	sharedBoundTag?: string;
 
@@ -127,6 +196,8 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * Useful when layout can change while unfocused (for example, programmatic
 	 * ScrollView/FlatList scrolling triggered from another screen).
 	 *
+	 * @deprecated Legacy `sharedBoundTag` refresh option. The boundary
+	 * measurement pipeline refreshes layout through `Transition.Boundary`.
 	 * @default false
 	 */
 	remeasureOnFocus?: boolean;
@@ -209,6 +280,8 @@ export type ScreenTransitionConfig = {
 	/**
 	 * How much velocity affects snap point targeting. Lower values make snapping
 	 * feel more deliberate (iOS-like), higher values make it more responsive to flicks.
+	 *
+	 * @deprecated Use `gestureSnapVelocityImpact` instead.
 	 * @default 0.1
 	 */
 	snapVelocityImpact?: number;
@@ -400,13 +473,21 @@ export type ScreenTransitionConfig = {
 	/**
 	 * Custom component to render as the backdrop layer (between screens).
 	 *
-	 * The library wraps this component with `Animated.createAnimatedComponent` internally.
-	 * Animated styles and props are driven by the `backdrop` slot in the interpolator return value.
+	 * Direct component types are wrapped with `Animated.createAnimatedComponent`
+	 * internally. Function components can receive `{ styles, props, pointerEvents }`
+	 * and decide how to render the layer. Animated styles and props are driven by
+	 * the `backdrop` slot in the interpolator return value.
 	 *
 	 * `backdropBehavior` still controls the wrapping Pressable for dismiss/collapse handling.
 	 *
 	 * @example
-	 * backdropComponent: BlurView,
+	 * backdropComponent: ({ styles, props, pointerEvents }) => (
+	 *   <AnimatedBlurView
+	 *     style={styles}
+	 *     animatedProps={props}
+	 *     pointerEvents={pointerEvents}
+	 *   />
+	 * ),
 	 * screenStyleInterpolator: ({ progress }) => {
 	 *   "worklet";
 	 *   return {
@@ -419,7 +500,32 @@ export type ScreenTransitionConfig = {
 	 *
 	 * @default undefined
 	 */
-	backdropComponent?: React.ComponentType<any>;
+	backdropComponent?: ScreenBackdropComponent;
+
+	/**
+	 * Custom component to render as the screen's content layer.
+	 *
+	 * The component receives the `content` slot's animated styles and props. A
+	 * direct component type is wrapped with `Animated.createAnimatedComponent`;
+	 * a function component can receive `{ styles, props, pointerEvents, children }`
+	 * and decide how to render the layer.
+	 *
+	 * `contentComponent` replaces `surfaceComponent` for custom screen shells.
+	 *
+	 * @example
+	 * contentComponent: ({ styles, props, pointerEvents, children }) => (
+	 *   <AnimatedSquircleView
+	 *     style={styles}
+	 *     animatedProps={props}
+	 *     pointerEvents={pointerEvents}
+	 *   >
+	 *     {children}
+	 *   </AnimatedSquircleView>
+	 * )
+	 *
+	 * @default undefined
+	 */
+	contentComponent?: ScreenContentComponent;
 
 	/**
 	 * Custom component to render as the screen's surface layer.
@@ -443,6 +549,7 @@ export type ScreenTransitionConfig = {
 	 * }
 	 *
 	 * @default undefined
+	 * @deprecated Use `contentComponent` instead.
 	 */
 	surfaceComponent?: React.ComponentType<any>;
 };

package/src/shared/utils/bounds/types/options.ts

@@ -237,6 +237,8 @@ export type BoundsOptions = {
 
 	/**
 	 * If true, the raw values will be returned instead of the computed values.
+	 *
+	 * @deprecated Use `bounds(id).math(options)` instead of passing `raw`.
 	 * @default false
 	 */
 	raw?: boolean;