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

package/src/components/boundary/portal/utils/ownership.ts

@@ -0,0 +1,319 @@
+import {
+	getDestinationScreenKeyFromPairKey,
+	getLinkKeyFromTag,
+	getLink as getPairLink,
+	getSourceScreenKeyFromPairKey,
+} from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import type {
+	LinkKey,
+	LinkPairsState,
+	ScreenKey,
+	ScreenPairKey,
+	TagLink,
+} from "../../../../stores/bounds/types";
+
+export type PortalOwnershipSignal =
+	| {
+			hostScreenKey: null;
+			ownerPairKey?: ScreenPairKey;
+			ownerScreenKey: null;
+			status: "clear" | "pending";
+	  }
+	| {
+			hostScreenKey: ScreenKey;
+			ownerPairKey: ScreenPairKey;
+			ownerScreenKey: ScreenKey;
+			status: "complete";
+	  };
+
+export const isHandoffHostClosingComplete = ({
+	closing,
+	progressAnimating,
+	progressSettled,
+	willAnimate,
+}: {
+	closing: number;
+	progressAnimating: number;
+	progressSettled: number;
+	willAnimate: number;
+}) => {
+	"worklet";
+
+	// A close request marks `closing` before its animation starts. Springs can
+	// also enter their settle-distance threshold before their final frame.
+	return (
+		!!closing &&
+		willAnimate === 0 &&
+		progressSettled === 1 &&
+		progressAnimating === 0
+	);
+};
+
+const hasSeenScreenKey = (screenKeys: ScreenKey[], screenKey: ScreenKey) => {
+	"worklet";
+	for (let index = 0; index < screenKeys.length; index++) {
+		if (screenKeys[index] === screenKey) {
+			return true;
+		}
+	}
+	return false;
+};
+
+const isReturningToPreviousSourceHost = ({
+	hostScreenKey,
+	ownerPairKey,
+	previousOwnerPairKey,
+}: {
+	hostScreenKey: ScreenKey;
+	ownerPairKey: ScreenPairKey;
+	previousOwnerPairKey: ScreenPairKey;
+}) => {
+	"worklet";
+	const previousSourceScreenKey =
+		getSourceScreenKeyFromPairKey(previousOwnerPairKey);
+	const previousDestinationScreenKey =
+		getDestinationScreenKeyFromPairKey(previousOwnerPairKey);
+	const ownerDestinationScreenKey =
+		getDestinationScreenKeyFromPairKey(ownerPairKey);
+
+	return (
+		previousDestinationScreenKey !== "" &&
+		ownerDestinationScreenKey !== "" &&
+		previousDestinationScreenKey !== previousSourceScreenKey &&
+		ownerDestinationScreenKey === previousSourceScreenKey &&
+		hostScreenKey === previousSourceScreenKey
+	);
+};
+
+export const canSwitchHandoffHostImmediately = ({
+	hostScreenKey,
+	ownerPairKey,
+	previousOwnerPairKey,
+}: {
+	hostScreenKey: ScreenKey | null;
+	ownerPairKey?: ScreenPairKey;
+	previousOwnerPairKey?: ScreenPairKey;
+}) => {
+	"worklet";
+	if (!hostScreenKey || !ownerPairKey) {
+		return false;
+	}
+
+	if (hostScreenKey === getSourceScreenKeyFromPairKey(ownerPairKey)) {
+		return true;
+	}
+
+	if (!previousOwnerPairKey) {
+		return false;
+	}
+
+	return isReturningToPreviousSourceHost({
+		hostScreenKey,
+		ownerPairKey,
+		previousOwnerPairKey,
+	});
+};
+
+const isActiveHandoffLink = ({
+	link,
+	linkKey,
+	pairKey,
+	pairsState,
+}: {
+	link: TagLink;
+	linkKey: LinkKey;
+	pairKey: ScreenPairKey;
+	pairsState: LinkPairsState;
+}) => {
+	"worklet";
+	if (!link.group) {
+		return true;
+	}
+
+	const activeId = pairsState[pairKey]?.groups?.[link.group]?.activeId;
+	return !activeId || activeId === linkKey;
+};
+
+const resolveHandoffStyleOwnerScreenKey = ({
+	hostScreenKey,
+	isSettledHostReady,
+	settledHostScreenKey,
+	sourceScreenKey,
+}: {
+	hostScreenKey: ScreenKey;
+	isSettledHostReady: boolean;
+	settledHostScreenKey?: ScreenKey | null;
+	sourceScreenKey: ScreenKey;
+}): ScreenKey => {
+	"worklet";
+	if (settledHostScreenKey === hostScreenKey && isSettledHostReady) {
+		return hostScreenKey;
+	}
+
+	return sourceScreenKey;
+};
+
+const pendingSignal = (sourcePairKey: ScreenPairKey): PortalOwnershipSignal => {
+	"worklet";
+	return {
+		hostScreenKey: null,
+		ownerPairKey: sourcePairKey,
+		ownerScreenKey: null,
+		status: "pending",
+	};
+};
+
+const clearSignal = (sourcePairKey: ScreenPairKey): PortalOwnershipSignal => {
+	"worklet";
+	return {
+		hostScreenKey: null,
+		ownerPairKey: sourcePairKey,
+		ownerScreenKey: null,
+		status: "clear",
+	};
+};
+
+export const resolveBoundaryPortalOwnership = ({
+	boundaryId,
+	currentScreenKey,
+	handoff,
+	isSettledHostClosingComplete = false,
+	isSettledHostReady = false,
+	pairsState,
+	settledHostScreenKey = null,
+	sourcePairKey,
+}: {
+	boundaryId: string;
+	currentScreenKey: ScreenKey;
+	handoff: boolean;
+	isSettledHostClosingComplete?: boolean;
+	isSettledHostReady?: boolean;
+	pairsState: LinkPairsState;
+	settledHostScreenKey?: ScreenKey | null;
+	sourcePairKey: ScreenPairKey;
+}): PortalOwnershipSignal => {
+	"worklet";
+	const linkKey = getLinkKeyFromTag(boundaryId);
+	const link = getPairLink(pairsState, sourcePairKey, linkKey);
+
+	if (!link?.source) {
+		return pendingSignal(sourcePairKey);
+	}
+
+	if (
+		!isActiveHandoffLink({
+			link,
+			linkKey,
+			pairKey: sourcePairKey,
+			pairsState,
+		})
+	) {
+		return clearSignal(sourcePairKey);
+	}
+
+	if (!handoff) {
+		return {
+			hostScreenKey: currentScreenKey,
+			ownerPairKey: sourcePairKey,
+			ownerScreenKey: currentScreenKey,
+			status: "complete",
+		};
+	}
+
+	if (link.status !== "complete") {
+		return pendingSignal(sourcePairKey);
+	}
+
+	let hostScreenKey = link.destination.screenKey;
+	let ownerPairKey = sourcePairKey;
+	const seenScreenKeys: ScreenKey[] = [
+		getSourceScreenKeyFromPairKey(sourcePairKey),
+		hostScreenKey,
+	];
+
+	const pairKeys = Object.keys(pairsState);
+
+	for (let hop = 0; hop < pairKeys.length; hop++) {
+		let didAdvance = false;
+		let hasPendingNextHop = false;
+		let didHitVisitedScreen = false;
+
+		for (let index = 0; index < pairKeys.length; index++) {
+			const candidatePairKey = pairKeys[index];
+			if (!candidatePairKey || candidatePairKey === ownerPairKey) {
+				continue;
+			}
+
+			const candidate = getPairLink(pairsState, candidatePairKey, linkKey);
+			if (!candidate?.source || candidate.source.screenKey !== hostScreenKey) {
+				continue;
+			}
+
+			if (!candidate.source.handoff) {
+				continue;
+			}
+
+			if (
+				!isActiveHandoffLink({
+					link: candidate,
+					linkKey,
+					pairKey: candidatePairKey,
+					pairsState,
+				})
+			) {
+				continue;
+			}
+
+			if (candidate.status !== "complete") {
+				hasPendingNextHop = true;
+				continue;
+			}
+
+			const nextHostScreenKey = candidate.destination.screenKey;
+
+			ownerPairKey = candidatePairKey;
+			hostScreenKey = nextHostScreenKey;
+
+			if (hasSeenScreenKey(seenScreenKeys, nextHostScreenKey)) {
+				didHitVisitedScreen = true;
+				break;
+			}
+
+			seenScreenKeys.push(nextHostScreenKey);
+			didAdvance = true;
+			break;
+		}
+
+		if (didHitVisitedScreen) {
+			break;
+		}
+
+		if (didAdvance) {
+			continue;
+		}
+
+		if (hasPendingNextHop) {
+			return pendingSignal(ownerPairKey);
+		}
+
+		break;
+	}
+
+	if (isSettledHostClosingComplete && settledHostScreenKey === hostScreenKey) {
+		hostScreenKey = getSourceScreenKeyFromPairKey(ownerPairKey);
+	}
+
+	const ownerScreenKey = resolveHandoffStyleOwnerScreenKey({
+		hostScreenKey,
+		isSettledHostReady,
+		settledHostScreenKey,
+		sourceScreenKey: getSourceScreenKeyFromPairKey(ownerPairKey),
+	});
+
+	return {
+		hostScreenKey,
+		ownerPairKey,
+		ownerScreenKey,
+		status: "complete",
+	};
+};

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,
+		],
+	);
+}