react-native-screen-transitions 3.9.0 → 4.0.0-alpha.0

package/src/components/boundary/portal/components/boundary-portal/hooks/use-host-measurement.ts

@@ -0,0 +1,152 @@
+import { useLayoutEffect, useState } from "react";
+import type { View } from "react-native";
+import {
+	cancelAnimation,
+	measure,
+	type SharedValue,
+	useAnimatedReaction,
+	useAnimatedRef,
+	useSharedValue,
+	withDelay,
+	withTiming,
+} from "react-native-reanimated";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
+import { useOriginContext } from "../../../../../../providers/screen/origin.provider";
+import { ScrollStore } from "../../../../../../stores/scroll.store";
+import { getVisibilityBlockOffset } from "../../../../../../utils/visibility-block-offset";
+import {
+	adjustedMeasuredBoundsForOverscrollDeltas,
+	isMeasurementInViewport,
+	normalizeMeasuredBoundsWithVisibilityGate,
+} from "../../../../utils/measured-bounds";
+import {
+	clearPortalHostBounds,
+	setPortalHostBounds,
+} from "../stores/host-bounds.store";
+
+const HOST_MEASUREMENT_RETRY_DELAY_MS = 16;
+
+type UseHostMeasurementParams = {
+	capturesScroll: boolean;
+	enabled: boolean;
+	hostKey: string;
+	screenKey: string;
+	visibilityBlocked: SharedValue<boolean>;
+	viewportHeight: number;
+	viewportWidth: number;
+};
+
+export const useHostMeasurement = ({
+	capturesScroll,
+	enabled,
+	hostKey,
+	screenKey,
+	visibilityBlocked,
+	viewportHeight,
+	viewportWidth,
+}: UseHostMeasurementParams) => {
+	const hostRef = useAnimatedRef<View>();
+	const scrollMetadata = ScrollStore.getValue(screenKey, "metadata");
+	const [canRenderHosts, setCanRenderHosts] = useState<boolean>(false);
+	const { originRef } = useOriginContext();
+	const hasMeasuredHost = useSharedValue(false);
+	const retryToken = useSharedValue(0);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) {
+				return null;
+			}
+
+			return [hasMeasuredHost.get(), retryToken.get()] as const;
+		},
+		(state) => {
+			"worklet";
+			if (!state) {
+				cancelAnimation(retryToken);
+				return;
+			}
+
+			const [hasAlreadyMeasured] = state;
+
+			if (!enabled || hasAlreadyMeasured) {
+				return;
+			}
+
+			const measured = measure(hostRef);
+			const measuredOrigin = measure(originRef);
+
+			if (!measured || !measuredOrigin) {
+				cancelAnimation(retryToken);
+				retryToken.set(
+					withDelay(
+						HOST_MEASUREMENT_RETRY_DELAY_MS,
+						withTiming(retryToken.get() + 1, { duration: 0 }),
+					),
+				);
+				return;
+			}
+
+			cancelAnimation(retryToken);
+			hasMeasuredHost.set(true);
+
+			// A measurement taken mid rubber-band would bake the transient
+			// overscroll displacement into the host frame. Store the at-rest
+			// position instead; clamped scroll deltas share that basis.
+			const currentScroll = scrollMetadata.get();
+			const overscrollNormalized = capturesScroll
+				? adjustedMeasuredBoundsForOverscrollDeltas(measured, currentScroll)
+				: measured;
+
+			const normalizedMeasured = normalizeMeasuredBoundsWithVisibilityGate({
+				measured: overscrollNormalized,
+				origin: measuredOrigin,
+				visibilityBlocked: visibilityBlocked.get(),
+				visibilityBlockOffset: getVisibilityBlockOffset(viewportHeight),
+				viewportWidth,
+				viewportHeight,
+			});
+
+			if (
+				!isMeasurementInViewport(
+					normalizedMeasured,
+					viewportWidth,
+					viewportHeight,
+				)
+			) {
+				cancelAnimation(retryToken);
+				retryToken.set(
+					withDelay(
+						HOST_MEASUREMENT_RETRY_DELAY_MS,
+						withTiming(retryToken.get() + 1, { duration: 0 }),
+					),
+				);
+				return;
+			}
+
+			setPortalHostBounds(hostKey, {
+				x: normalizedMeasured.x,
+				y: normalizedMeasured.y,
+				width: normalizedMeasured.width,
+				height: normalizedMeasured.height,
+				pageX: normalizedMeasured.pageX,
+				pageY: normalizedMeasured.pageY,
+				scroll: capturesScroll ? currentScroll : null,
+			});
+
+			scheduleOnRN(setCanRenderHosts, true);
+		},
+	);
+
+	useLayoutEffect(() => {
+		return () => {
+			scheduleOnUI(clearPortalHostBounds, hostKey);
+		};
+	}, [hostKey]);
+
+	return {
+		canRenderHosts,
+		hostRef,
+	};
+};

package/src/components/create-transition-aware-component.tsx

@@ -0,0 +1,172 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: <This helper is usually being used inside a transitionable stack> */
+import type React from "react";
+import { type ComponentType, forwardRef, memo } from "react";
+import type { View } from "react-native";
+import { GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+	useAnimatedRef,
+	useComposedEventHandler,
+} from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import { RegisterBoundsProvider } from "../providers/register-bounds.provider";
+import {
+	ScrollMetadataOwnerProvider,
+	useScrollGestureCoordination,
+} from "../providers/screen/gestures/scroll-coordination";
+import { useSlotProps, useSlotStyles } from "../providers/screen/styles";
+import type { TransitionAwareProps } from "../types/screen.types";
+
+interface CreateTransitionAwareComponentOptions {
+	isScrollable?: boolean;
+	alreadyAnimated?: boolean;
+}
+
+export function createTransitionAwareComponent<P extends object>(
+	Wrapped: ComponentType<P>,
+	options: CreateTransitionAwareComponentOptions = {},
+) {
+	const { isScrollable = false, alreadyAnimated = false } = options;
+
+	const AnimatedComponent = alreadyAnimated
+		? Wrapped
+		: Animated.createAnimatedComponent(Wrapped);
+
+	const ScrollableInner = forwardRef<
+		React.ComponentRef<typeof Wrapped>,
+		TransitionAwareProps<P>
+	>((props: any, ref) => {
+		const {
+			remeasureOnFocus: _remeasureOnFocus,
+			onScroll: userOnScroll,
+			onMomentumScrollEnd: userOnMomentumScrollEnd,
+			onScrollEndDrag: userOnScrollEndDrag,
+			children,
+			contentContainerStyle,
+			...scrollableProps
+		} = props;
+
+		// Determine scroll direction from the horizontal prop (standard ScrollView API)
+		const scrollDirection = scrollableProps.horizontal
+			? "horizontal"
+			: "vertical";
+
+		// Get scroll handlers and the gesture owner's nativeGesture for this axis
+		const {
+			scrollHandler,
+			scrollEventsEnabled,
+			onContentSizeChange,
+			onLayout,
+			nativeGesture,
+			metadataOwnerProviderValue,
+		} = useScrollGestureCoordination({
+			onContentSizeChange: scrollableProps.onContentSizeChange,
+			onLayout: scrollableProps.onLayout,
+			direction: scrollDirection,
+		});
+
+		const composedScrollHandler = useComposedEventHandler([
+			scrollHandler,
+			userOnScroll ?? null,
+		]);
+		const scrollableComponent = (
+			<AnimatedComponent
+				{...(scrollableProps as any)}
+				ref={ref}
+				contentContainerStyle={contentContainerStyle}
+				/**
+				 * Keep the scroll listener detached while the owning gesture screen is
+				 * closing. On iOS, a bounced ScrollView can keep sending native scroll
+				 * events after the transition gesture activates, which competes with
+				 * close animation work on the UI thread.
+				 */
+				onScroll={scrollEventsEnabled ? composedScrollHandler : undefined}
+				onMomentumScrollEnd={userOnMomentumScrollEnd}
+				onScrollEndDrag={userOnScrollEndDrag}
+				onContentSizeChange={onContentSizeChange}
+				onLayout={onLayout}
+				scrollEventThrottle={
+					scrollEventsEnabled
+						? scrollableProps.scrollEventThrottle || 16
+						: undefined
+				}
+			>
+				{children}
+			</AnimatedComponent>
+		);
+
+		const coordinatedScrollableComponent = nativeGesture ? (
+			<GestureDetector gesture={nativeGesture}>
+				{scrollableComponent}
+			</GestureDetector>
+		) : (
+			scrollableComponent
+		);
+
+		return (
+			<ScrollMetadataOwnerProvider value={metadataOwnerProviderValue}>
+				{coordinatedScrollableComponent}
+			</ScrollMetadataOwnerProvider>
+		);
+	});
+
+	const Inner = forwardRef<
+		React.ComponentRef<typeof AnimatedComponent>,
+		TransitionAwareProps<P>
+	>((props, _) => {
+		const {
+			children,
+			style,
+			sharedBoundTag,
+			styleId,
+			onPress,
+			remeasureOnFocus,
+			animatedProps: userAnimatedProps,
+			...rest
+		} = props as any;
+
+		const animatedRef = useAnimatedRef<View>();
+		const associatedId = sharedBoundTag || styleId;
+		const associatedStyles = useSlotStyles(associatedId);
+		const associatedProps = useSlotProps(associatedId);
+
+		return (
+			<RegisterBoundsProvider
+				animatedRef={animatedRef}
+				style={style}
+				onPress={onPress}
+				sharedBoundTag={sharedBoundTag}
+				remeasureOnFocus={remeasureOnFocus}
+			>
+				{({ captureActiveOnPress, handleInitialLayout }) => (
+					<AnimatedComponent
+						{...(rest as any)}
+						ref={animatedRef}
+						style={[style, associatedStyles]}
+						animatedProps={userAnimatedProps ?? associatedProps}
+						onPress={captureActiveOnPress}
+						onLayout={() => scheduleOnUI(handleInitialLayout)}
+						collapsable={!sharedBoundTag}
+					>
+						{children}
+					</AnimatedComponent>
+				)}
+			</RegisterBoundsProvider>
+		);
+	});
+
+	if (isScrollable) {
+		return memo(ScrollableInner) as React.MemoExoticComponent<
+			React.ForwardRefExoticComponent<
+				TransitionAwareProps<P> &
+					React.RefAttributes<React.ComponentRef<typeof Wrapped>>
+			>
+		>;
+	}
+
+	return memo(Inner) as React.MemoExoticComponent<
+		React.ForwardRefExoticComponent<
+			TransitionAwareProps<P> &
+				React.RefAttributes<React.ComponentRef<typeof Wrapped>>
+		>
+	>;
+}

package/src/components/overlay/variations/overlay-host.tsx

@@ -0,0 +1,72 @@
+import { memo, useMemo } from "react";
+import { Animated, StyleSheet, View } from "react-native";
+import { useDerivedValue } from "react-native-reanimated";
+import type { StackScene } from "../../../hooks/navigation/use-stack";
+import { NavigationScreenProvider } from "../../../providers/navigation/navigation-host.provider";
+import { useScreenAnimation } from "../../../providers/screen/animation";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import type {
+	OverlayProps,
+	OverlayScreenState,
+} from "../../../types/overlay.types";
+
+type OverlayHostProps = {
+	scene: StackScene;
+	overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]>;
+};
+
+export const OverlayHost = memo(function OverlayHost({
+	scene,
+	overlayScreenState,
+}: OverlayHostProps) {
+	const OverlayComponent = scene.descriptor.options.overlay;
+
+	const screenAnimation = useScreenAnimation();
+	const relativeProgress = useDerivedValue(() => {
+		"worklet";
+		return screenAnimation.get().stackProgress;
+	});
+
+	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(
+		() => ({
+			...overlayScreenState,
+			progress: relativeProgress,
+		}),
+		[relativeProgress, overlayScreenState],
+	);
+
+	if (!OverlayComponent) {
+		return null;
+	}
+
+	return (
+		<Animated.View
+			pointerEvents="box-none"
+			style={[styles.container, styles.floating, StyleSheet.absoluteFill]}
+		>
+			<NavigationScreenProvider
+				navigation={scene.descriptor.navigation}
+				route={scene.route}
+			>
+				<View
+					pointerEvents="box-none"
+					style={[StyleSheet.absoluteFill, styles.overlay]}
+				>
+					<OverlayComponent {...overlayProps} />
+				</View>
+			</NavigationScreenProvider>
+		</Animated.View>
+	);
+});
+
+const styles = StyleSheet.create({
+	overlay: {
+		zIndex: 1,
+	},
+	container: {
+		flex: 1,
+	},
+	floating: {
+		zIndex: 1000,
+	},
+});

package/src/components/screen-container/hooks/use-backdrop-pointer-events.ts

@@ -0,0 +1,56 @@
+import { useState } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useScreenOptionsContext } from "../../../providers/screen/options";
+import { useStackCoreContext } from "../../../providers/stack/core.provider";
+import type { BackdropBehavior } from "../../../types/screen.types";
+import { StackType } from "../../../types/stack.types";
+
+interface BackdropPointerEventsResult {
+	pointerEvents: "box-none" | undefined;
+	backdropBehavior: BackdropBehavior;
+	isBackdropActive: boolean;
+}
+
+/**
+ * Returns pointer events and backdrop behavior based on screen options.
+ *
+ * - Runtime interpolator `backdropBehavior` takes precedence
+ * - Explicit descriptor `backdropBehavior` option is next
+ * - Component stacks default to 'passthrough' (box-none)
+ * - Other stacks default to 'block' (undefined = normal touch handling)
+ */
+export function useBackdropPointerEvents(): BackdropPointerEventsResult {
+	const { current } = useDescriptors();
+	const screenOptions = useScreenOptionsContext();
+	const { flags } = useStackCoreContext();
+	const [runtimeBackdropBehavior, setRuntimeBackdropBehavior] = useState<
+		BackdropBehavior | undefined
+	>(undefined);
+
+	useAnimatedReaction(
+		() => screenOptions.get().backdropBehavior,
+		(next, previous) => {
+			"worklet";
+			if (next !== previous) {
+				scheduleOnRN(setRuntimeBackdropBehavior, next);
+			}
+		},
+		[screenOptions],
+	);
+
+	const isComponentStack = flags.STACK_TYPE === StackType.COMPONENT;
+	const backdropBehavior: BackdropBehavior =
+		runtimeBackdropBehavior ??
+		current.options.backdropBehavior ??
+		(isComponentStack ? "passthrough" : "block");
+
+	const pointerEvents =
+		backdropBehavior === "passthrough" ? "box-none" : undefined;
+
+	const isBackdropActive =
+		backdropBehavior === "dismiss" || backdropBehavior === "collapse";
+
+	return { pointerEvents, backdropBehavior, isBackdropActive };
+}

package/src/components/screen-container/hooks/use-content-layout.ts

@@ -0,0 +1,82 @@
+import { useCallback } from "react";
+import { type LayoutChangeEvent, useWindowDimensions } from "react-native";
+import { scheduleOnUI } from "react-native-worklets";
+import {
+	useDescriptorDerivations,
+	useDescriptors,
+} from "../../../providers/screen/descriptors";
+import { AnimationStore } from "../../../stores/animation.store";
+import {
+	LifecycleTransitionRequestKind,
+	SystemStore,
+} from "../../../stores/system.store";
+
+export function useContentLayout() {
+	const { current } = useDescriptors();
+	const { isFirstKey } = useDescriptorDerivations();
+	const { height: screenHeight } = useWindowDimensions();
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getBag(routeKey);
+	const system = SystemStore.getBag(routeKey);
+
+	const { targetProgress, resolvedAutoSnapPoint, measuredContentLayout } =
+		system;
+	const { requestLifecycleTransition } = system.actions;
+
+	const experimental_animateOnInitialMount =
+		current.options.experimental_animateOnInitialMount;
+
+	return useCallback(
+		(event: LayoutChangeEvent) => {
+			const { width, height } = event.nativeEvent.layout;
+			if (width <= 0 || height <= 0) return;
+
+			const fraction = Math.min(height / screenHeight, 1);
+
+			scheduleOnUI(
+				(nextWidth: number, nextHeight: number, nextFraction: number) => {
+					"worklet";
+					measuredContentLayout.set({
+						width: nextWidth,
+						height: nextHeight,
+					});
+
+					const isFirstMeasurement = resolvedAutoSnapPoint.get() <= 0;
+					resolvedAutoSnapPoint.set(nextFraction);
+
+					if (
+						!isFirstMeasurement ||
+						animations.transitionProgress.get() !== 0 ||
+						animations.progressAnimating.get() !== 0
+					) {
+						return;
+					}
+
+					if (isFirstKey && !experimental_animateOnInitialMount) {
+						targetProgress.set(nextFraction);
+						animations.transitionProgress.set(nextFraction);
+						return;
+					}
+
+					requestLifecycleTransition(
+						LifecycleTransitionRequestKind.Open,
+						nextFraction,
+					);
+				},
+				width,
+				height,
+				fraction,
+			);
+		},
+		[
+			animations,
+			targetProgress,
+			resolvedAutoSnapPoint,
+			measuredContentLayout,
+			isFirstKey,
+			screenHeight,
+			experimental_animateOnInitialMount,
+			requestLifecycleTransition,
+		],
+	);
+}

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

@@ -0,0 +1,152 @@
+import { type ComponentType, memo, useCallback, useMemo } from "react";
+import { Pressable, StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import { DefaultSnapSpec } from "../../../configs/specs";
+import { useNavigationHelpers } from "../../../hooks/navigation/use-navigation-helpers";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+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,
+	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,
+	isBackdropActive,
+}: {
+	backdropBehavior: BackdropBehavior;
+	isBackdropActive: boolean;
+}) {
+	const { current } = useDescriptors();
+	const { dismissScreen } = useNavigationHelpers();
+
+	const BackdropComponent = current.options.backdropComponent;
+	const routeKey = current.route.key;
+	const animations = AnimationStore.getBag(routeKey);
+	const { targetProgress, resolvedAutoSnapPoint } =
+		SystemStore.getBag(routeKey);
+
+	const AnimatedBackdropComponent = useMemo(
+		() =>
+			BackdropComponent && !usesLayerRenderProps(BackdropComponent)
+				? Animated.createAnimatedComponent(
+						BackdropComponent as ComponentType<any>,
+					)
+				: null,
+		[BackdropComponent],
+	);
+
+	const handleBackdropPress = useCallback(() => {
+		if (backdropBehavior === "dismiss") {
+			dismissScreen();
+			return;
+		}
+
+		if (backdropBehavior === "collapse") {
+			const rawSnapPoints = current.options.snapPoints;
+			const canDismiss = current.options.gestureEnabled !== false;
+
+			// No snap points → fallback to dismiss
+			if (!rawSnapPoints || rawSnapPoints.length === 0) {
+				dismissScreen();
+				return;
+			}
+
+			const gestures = GestureStore.getBag(routeKey);
+			const transitionSpec = current.options.transitionSpec;
+
+			scheduleOnUI(() => {
+				"worklet";
+				const resolvedSnaps: number[] = [];
+
+				for (let i = 0; i < rawSnapPoints.length; i++) {
+					const point = rawSnapPoints[i];
+					const resolvedPoint =
+						point === "auto" ? resolvedAutoSnapPoint.get() : point;
+
+					if (typeof resolvedPoint === "number") {
+						resolvedSnaps.push(resolvedPoint);
+					}
+				}
+
+				const { target, shouldDismiss } = findCollapseTarget(
+					animations.transitionProgress.get(),
+					resolvedSnaps,
+					canDismiss,
+				);
+
+				// If already dismissing, skip
+				if (gestures.dismissing.get()) return;
+
+				gestures.dismissing.set(shouldDismiss ? 1 : 0);
+
+				const spec = shouldDismiss
+					? transitionSpec
+					: {
+							open: transitionSpec?.expand ?? DefaultSnapSpec,
+							close: transitionSpec?.collapse ?? DefaultSnapSpec,
+						};
+
+				animateToProgress({
+					target,
+					spec,
+					animations,
+					targetProgress,
+					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
+				});
+			});
+		}
+	}, [
+		animations,
+		targetProgress,
+		resolvedAutoSnapPoint,
+		backdropBehavior,
+		current,
+		dismissScreen,
+		routeKey,
+	]);
+
+	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
+			style={StyleSheet.absoluteFill}
+			pointerEvents={isBackdropActive ? "auto" : "none"}
+			onPress={isBackdropActive ? handleBackdropPress : undefined}
+		>
+			{AnimatedBackdropComponent ? (
+				<AnimatedBackdropComponent
+					style={backdropStyles}
+					animatedProps={animatedBackdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : BackdropComponent ? (
+				<BackdropComponent
+					styles={backdropStyles}
+					props={backdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : (
+				<Animated.View
+					style={backdropStyles}
+					pointerEvents={backdropPointerEvents}
+				/>
+			)}
+		</Pressable>
+	);
+});

package/src/components/screen-lifecycle/hooks/helpers/reset-stores-for-screen.ts

@@ -0,0 +1,15 @@
+import { scheduleOnUI } from "react-native-worklets";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { clear } from "../../../../stores/bounds/internals/clear";
+import { GestureStore } from "../../../../stores/gesture.store";
+import { ScrollStore } from "../../../../stores/scroll.store";
+import { SystemStore } from "../../../../stores/system.store";
+
+export function resetStoresForScreen(routeKey: string) {
+	AnimationStore.clearBag(routeKey);
+	GestureStore.clearBag(routeKey);
+	ScrollStore.clearBag(routeKey);
+	SystemStore.clearBag(routeKey);
+
+	scheduleOnUI(clear, routeKey);
+}