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

package/src/shared/providers/screen/styles/helpers/collect-interpolator-shared-values.ts

@@ -0,0 +1,75 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { ScreenStyleInterpolator } from "../../../../types/animation.types";
+
+type WorkletClosure = Record<string, unknown>;
+
+type ClosureCarrier = {
+	__closure?: WorkletClosure;
+};
+
+type SharedValueLike = SharedValue<unknown> & {
+	_isReanimatedSharedValue: true;
+};
+
+const isSharedValueLike = (value: unknown): value is SharedValueLike =>
+	(value as Partial<SharedValueLike> | null)?._isReanimatedSharedValue === true;
+
+const getWorkletClosure = (value: unknown): WorkletClosure | undefined => {
+	if (
+		value === null ||
+		(typeof value !== "object" && typeof value !== "function")
+	) {
+		return undefined;
+	}
+
+	const closure = (value as Partial<ClosureCarrier>).__closure;
+	return closure && typeof closure === "object" ? closure : undefined;
+};
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+	value !== null &&
+	typeof value === "object" &&
+	Object.getPrototypeOf(value) === Object.prototype;
+
+export const collectInterpolatorSharedValues = (
+	interpolators: Array<ScreenStyleInterpolator | undefined>,
+): SharedValue<unknown>[] => {
+	const sharedValues: SharedValue<unknown>[] = [];
+	const seen = new Set<unknown>();
+
+	const visit = (value: unknown) => {
+		if (value === null || value === undefined || seen.has(value)) {
+			return;
+		}
+		seen.add(value);
+
+		if (isSharedValueLike(value)) {
+			sharedValues.push(value);
+			return;
+		}
+
+		if (typeof value === "function") {
+			visit(getWorkletClosure(value));
+			return;
+		}
+
+		if (Array.isArray(value)) {
+			for (let index = 0; index < value.length; index++) {
+				visit(value[index]);
+			}
+			return;
+		}
+
+		if (isPlainObject(value)) {
+			for (const item of Object.values(value)) {
+				visit(item);
+			}
+		}
+	};
+
+	for (let index = 0; index < interpolators.length; index++) {
+		visit(getWorkletClosure(interpolators[index]));
+	}
+
+	return sharedValues;
+};

package/src/shared/providers/screen/styles/hooks/use-interpolated-style-maps.tsx

@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { useDerivedValue, useSharedValue } from "react-native-reanimated";
 import { NO_STYLES } from "../../../../constants";
 import { AnimationStore } from "../../../../stores/animation.store";
@@ -22,6 +23,7 @@ import {
 	syncScreenOptionsOverrides,
 	useScreenOptionsContext,
 } from "../../options";
+import { collectInterpolatorSharedValues } from "../helpers/collect-interpolator-shared-values";
 import { normalizeSlots } from "../helpers/normalize-slots";
 import { isOpeningBeforeStart } from "../helpers/opening-phase";
 import type { LocalStyleLayers } from "../helpers/resolve-slot-styles";
@@ -146,6 +148,14 @@ export const useInterpolatedStylesMap = () => {
 	const transition = useBuildTransitionAccessor();
 	const nextInterpolatorReady = useSharedValue(0);
 
+	// In some cases, a user may want to use external shared values to drive animations in the interpoaltor.
+	// We can now support this by collecting those shared values and reading them here to trigger an update.
+	const interpolatorSharedValues = useMemo(
+		() =>
+			collectInterpolatorSharedValues([currentInterpolator, nextInterpolator]),
+		[currentInterpolator, nextInterpolator],
+	);
+
 	const activeScreenKey = nextScreenKey ?? currentScreenKey;
 	const {
 		entering: activeEntering,
@@ -162,6 +172,7 @@ export const useInterpolatedStylesMap = () => {
 			screenInterpolatorPropsRevision,
 			ancestorScreenAnimationSources,
 			descendantScreenAnimationSources,
+			interpolatorSharedValues,
 		);
 		const props = screenInterpolatorProps.get();
 

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;