react-native-screen-transitions 3.7.1 → 3.8.0-beta.0

package/src/shared/providers/stack/blank-stack.provider.tsx

@@ -0,0 +1,118 @@
+import type { Route } from "@react-navigation/native";
+import * as React from "react";
+import { useMemo } from "react";
+import {
+	type StackContextValue,
+	StackProvider,
+} from "../../hooks/navigation/use-stack";
+import type {
+	BlankStackProviderContextValue,
+	BlankStackProviderProps,
+	BlankStackProviderRenderProps,
+	BlankStackProviderResult,
+} from "../../types/providers/blank-stack-provider.types";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackScene,
+} from "../../types/stack.types";
+import { useBlankStackState } from "./blank-stack-state";
+import { useStackCoreContext } from "./core.provider";
+
+const BlankStackProviderContext =
+	React.createContext<BlankStackProviderContextValue | null>(null);
+BlankStackProviderContext.displayName = "BlankStackProvider";
+
+function useBlankStackContext(): BlankStackProviderContextValue {
+	const context = React.useContext(BlankStackProviderContext);
+	if (!context) {
+		throw new Error(
+			"useBlankStackContext must be used within BlankStackProvider",
+		);
+	}
+	return context;
+}
+
+function useBlankStackProviderValue<
+	TDescriptor extends BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation,
+>(
+	props: BlankStackProviderProps<TDescriptor, TNavigation>,
+): BlankStackProviderResult<TDescriptor> {
+	const { flags } = useStackCoreContext();
+	const { state, handleCloseRoute, requestDismiss } = useBlankStackState(props);
+	const navigatorKey = props.state.key;
+
+	const focusedIndex = props.state.index;
+
+	const stackContextValue = useMemo<StackContextValue>(
+		() => ({
+			flags,
+			navigatorKey,
+			routeKeys: state.routeKeys,
+			routes: state.routes as Route<string>[],
+			scenes: state.scenes as BaseStackScene[],
+			focusedIndex,
+			requestDismiss,
+		}),
+		[
+			flags,
+			navigatorKey,
+			state.routeKeys,
+			state.routes,
+			state.scenes,
+			focusedIndex,
+			requestDismiss,
+		],
+	);
+
+	const blankStackProviderContextValue =
+		useMemo<BlankStackProviderContextValue>(
+			() => ({
+				handleCloseRoute,
+			}),
+			[handleCloseRoute],
+		);
+
+	const renderProps = useMemo<BlankStackProviderRenderProps<TDescriptor>>(
+		() => ({
+			scenes: state.scenes,
+			focusedIndex,
+			shouldShowFloatOverlay: state.shouldShowFloatOverlay,
+		}),
+		[state.scenes, focusedIndex, state.shouldShowFloatOverlay],
+	);
+
+	return { stackContextValue, blankStackProviderContextValue, renderProps };
+}
+
+function withBlankStack<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+>(
+	Component: React.ComponentType<BlankStackProviderRenderProps<TDescriptor>>,
+): React.FC<BlankStackProviderProps<TDescriptor, TNavigation>> {
+	return function BlankStackProvider(
+		props: BlankStackProviderProps<TDescriptor, TNavigation>,
+	) {
+		const { stackContextValue, blankStackProviderContextValue, renderProps } =
+			useBlankStackProviderValue<TDescriptor, TNavigation>(props);
+
+		return (
+			<StackProvider value={stackContextValue}>
+				<BlankStackProviderContext.Provider
+					value={blankStackProviderContextValue}
+				>
+					<Component {...renderProps} />
+				</BlankStackProviderContext.Provider>
+			</StackProvider>
+		);
+	};
+}
+
+export type {
+	BlankStackProviderContextValue,
+	BlankStackProviderProps,
+	BlankStackProviderRenderProps,
+};
+export { useBlankStackContext, withBlankStack };

package/src/shared/providers/stack/direct.provider.tsx

@@ -5,10 +5,6 @@ import {
 	type StackContextValue,
 	StackProvider,
 } from "../../hooks/navigation/use-stack";
-import {
-	AnimationStore,
-	type AnimationStoreMap,
-} from "../../stores/animation.store";
 import type {
 	DirectStackContextValue,
 	DirectStackProps,
@@ -16,7 +12,6 @@ import type {
 } from "../../types/providers/direct-stack.types";
 import { isOverlayVisible } from "../../utils/overlay/visibility";
 import { useStackCoreContext } from "./core.provider";
-import { useStackDerived } from "./helpers/use-stack-derived";
 
 function useDirectStackValue(
 	props: DirectStackProps,
@@ -35,51 +30,49 @@ function useDirectStackValue(
 		);
 	}, [state.preloadedRoutes, describe]);
 
-	const {
-		scenes,
-		shouldShowFloatOverlay,
-		routeKeys,
-		allRoutes,
-		animationMaps,
-	} = useMemo(() => {
-		const allRoutes = state.routes.concat(state.preloadedRoutes);
-		const scenes: DirectStackScene[] = [];
-		const routeKeys: string[] = [];
-		const animationMaps: AnimationStoreMap[] = [];
-		const allDescriptors: NativeStackDescriptorMap = {
-			...preloadedDescriptors,
-			...descriptors,
-		};
-		let shouldShowFloatOverlay = false;
+	const { scenes, shouldShowFloatOverlay, routeKeys, allRoutes } =
+		useMemo(() => {
+			const allRoutes = state.routes.concat(state.preloadedRoutes);
+			const scenes: DirectStackScene[] = [];
+			const routeKeys: string[] = [];
+			const allDescriptors: NativeStackDescriptorMap = {
+				...preloadedDescriptors,
+				...descriptors,
+			};
+			let shouldShowFloatOverlay = false;
 
-		for (const route of allRoutes) {
-			const descriptor = allDescriptors[route.key];
-			const isPreloaded =
-				preloadedDescriptors[route.key] !== undefined &&
-				descriptors[route.key] === undefined;
+			for (const route of allRoutes) {
+				const descriptor = allDescriptors[route.key];
+				const isPreloaded =
+					preloadedDescriptors[route.key] !== undefined &&
+					descriptors[route.key] === undefined;
 
-			scenes.push({ route, descriptor, isPreloaded });
-			routeKeys.push(route.key);
-			animationMaps.push(AnimationStore.getBag(route.key));
+				scenes.push({ route, descriptor, isPreloaded });
+				routeKeys.push(route.key);
 
-			if (!shouldShowFloatOverlay && descriptor) {
-				const options = descriptor.options;
-				if (options?.enableTransitions === true && isOverlayVisible(options)) {
-					shouldShowFloatOverlay = true;
+				if (!shouldShowFloatOverlay && descriptor) {
+					const options = descriptor.options;
+					if (
+						options?.enableTransitions === true &&
+						isOverlayVisible(options)
+					) {
+						shouldShowFloatOverlay = true;
+					}
 				}
 			}
-		}
 
-		return {
-			scenes,
-			shouldShowFloatOverlay,
-			routeKeys,
-			allRoutes,
-			animationMaps,
-		};
-	}, [state.routes, state.preloadedRoutes, preloadedDescriptors, descriptors]);
-
-	const { optimisticFocusedIndex } = useStackDerived(animationMaps);
+			return {
+				scenes,
+				shouldShowFloatOverlay,
+				routeKeys,
+				allRoutes,
+			};
+		}, [
+			state.routes,
+			state.preloadedRoutes,
+			preloadedDescriptors,
+			descriptors,
+		]);
 
 	const focusedIndex = state.index;
 
@@ -90,18 +83,9 @@ function useDirectStackValue(
 			routeKeys,
 			routes: allRoutes,
 			scenes,
-			optimisticFocusedIndex,
 			focusedIndex,
 		}),
-		[
-			flags,
-			navigatorKey,
-			routeKeys,
-			allRoutes,
-			scenes,
-			optimisticFocusedIndex,
-			focusedIndex,
-		],
+		[flags, navigatorKey, routeKeys, allRoutes, scenes, focusedIndex],
 	);
 
 	// DirectStack context value

package/src/shared/stores/animation.store.ts

@@ -10,6 +10,7 @@ export type AnimationStoreMap = {
 	effectiveProgress: SharedValue<number>;
 	willAnimate: SharedValue<number>;
 	progressAnimating: SharedValue<number>;
+	progressSettled: SharedValue<number>;
 	closing: SharedValue<number>;
 	entering: SharedValue<number>;
 };
@@ -21,6 +22,7 @@ function createAnimationBag(): AnimationStoreMap {
 		willAnimate: makeMutable(0),
 		closing: makeMutable(0),
 		progressAnimating: makeMutable(0),
+		progressSettled: makeMutable(1),
 		entering: makeMutable(0),
 	};
 }
@@ -37,6 +39,7 @@ export const AnimationStore = createStore<AnimationStoreMap>({
 		cancelAnimation(bag.effectiveProgress);
 		cancelAnimation(bag.willAnimate);
 		cancelAnimation(bag.progressAnimating);
+		cancelAnimation(bag.progressSettled);
 		cancelAnimation(bag.closing);
 		cancelAnimation(bag.entering);
 	},

package/src/shared/stores/gesture.store.ts

@@ -16,6 +16,7 @@ type GestureRawStoreMap = {
 	normY: SharedValue<number>;
 	scale: SharedValue<number>;
 	normScale: SharedValue<number>;
+	rotation: SharedValue<number>;
 };
 
 export type GestureStoreMap = {
@@ -28,6 +29,7 @@ export type GestureStoreMap = {
 	normScale: SharedValue<number>;
 	focalX: SharedValue<number>;
 	focalY: SharedValue<number>;
+	rotation: SharedValue<number>;
 	raw: GestureRawStoreMap;
 	dismissing: SharedValue<number>;
 	dragging: SharedValue<number>;
@@ -74,6 +76,7 @@ function createGestureBag(): GestureStoreMap {
 		normScale,
 		focalX: makeMutable(0),
 		focalY: makeMutable(0),
+		rotation: makeMutable(0),
 		raw: {
 			x: makeMutable(0),
 			y: makeMutable(0),
@@ -81,6 +84,7 @@ function createGestureBag(): GestureStoreMap {
 			normY: makeMutable(0),
 			scale: makeMutable(1),
 			normScale: makeMutable(0),
+			rotation: makeMutable(0),
 		},
 		dismissing,
 		dragging,
@@ -115,12 +119,14 @@ export const GestureStore = createStore<GestureStoreMap>({
 		cancelAnimation(bag.normScale);
 		cancelAnimation(bag.focalX);
 		cancelAnimation(bag.focalY);
+		cancelAnimation(bag.rotation);
 		cancelAnimation(bag.raw.x);
 		cancelAnimation(bag.raw.y);
 		cancelAnimation(bag.raw.normX);
 		cancelAnimation(bag.raw.normY);
 		cancelAnimation(bag.raw.scale);
 		cancelAnimation(bag.raw.normScale);
+		cancelAnimation(bag.raw.rotation);
 		cancelAnimation(bag.dismissing);
 		cancelAnimation(bag.dragging);
 		cancelAnimation(bag.settling);

package/src/shared/stores/scroll.store.ts

@@ -3,23 +3,96 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import type { ScrollGestureState } from "../types/gesture.types";
+import type {
+	ScrollGestureAxis,
+	ScrollGestureState,
+	ScrollMetadataState,
+} from "../types/gesture.types";
+import type { ScreenKey } from "../types/screen.types";
 import { createStore } from "../utils/create-store";
 
 export type ScrollStoreMap = {
-	state: SharedValue<ScrollGestureState | null>;
+	coordination: SharedValue<ScrollGestureState | null>;
+	metadata: SharedValue<ScrollMetadataState | null>;
+};
+
+const metadataWriters: Record<
+	ScreenKey,
+	Partial<Record<ScrollGestureAxis, string>>
+> = {};
+
+let nextMetadataWriterId = 0;
+
+const createMetadataWriterId = () => {
+	nextMetadataWriterId += 1;
+	return `scroll-metadata-${nextMetadataWriterId}`;
+};
+
+const claimMetadataWriter = (
+	routeKey: ScreenKey,
+	axis: ScrollGestureAxis,
+	writerId: string,
+): boolean => {
+	const writers = metadataWriters[routeKey] ?? {};
+	metadataWriters[routeKey] = writers;
+
+	if (!writers[axis]) {
+		writers[axis] = writerId;
+	}
+
+	return writers[axis] === writerId;
+};
+
+const releaseMetadataWriter = (
+	routeKey: ScreenKey,
+	axis: ScrollGestureAxis,
+	writerId: string,
+): boolean => {
+	const writers = metadataWriters[routeKey];
+	if (!writers || writers[axis] !== writerId) return false;
+
+	delete writers[axis];
+
+	if (!writers.vertical && !writers.horizontal) {
+		delete metadataWriters[routeKey];
+	}
+
+	return true;
+};
+
+const hasMetadataWriters = (routeKey: ScreenKey): boolean => {
+	const writers = metadataWriters[routeKey];
+	return Boolean(writers?.vertical || writers?.horizontal);
+};
+
+const clearMetadataWriters = (routeKey: ScreenKey) => {
+	delete metadataWriters[routeKey];
 };
 
 /**
  * Route-keyed scroll geometry used by gesture activation and bounds measurement.
- * The state tracks coordinated ScrollView offsets and dimensions so consumers
- * can reason about overscroll without coupling to a specific scroll component.
+ * Coordination tracks gesture-owner scoped ScrollView offsets and dimensions;
+ * metadata tracks screen-scoped scroll values exposed to animation consumers.
  */
-export const ScrollStore = createStore<ScrollStoreMap>({
+const scrollStore = createStore<ScrollStoreMap>({
 	createBag: () => ({
-		state: makeMutable<ScrollGestureState | null>(null),
+		coordination: makeMutable<ScrollGestureState | null>(null),
+		metadata: makeMutable<ScrollMetadataState | null>(null),
 	}),
 	disposeBag: (bag) => {
-		cancelAnimation(bag.state);
+		cancelAnimation(bag.coordination);
+		cancelAnimation(bag.metadata);
 	},
 });
+
+export const ScrollStore = {
+	...scrollStore,
+	createMetadataWriterId,
+	claimMetadataWriter,
+	releaseMetadataWriter,
+	hasMetadataWriters,
+	clearBag(routeKey: ScreenKey) {
+		clearMetadataWriters(routeKey);
+		scrollStore.clearBag(routeKey);
+	},
+};

package/src/shared/stores/system.store.ts

@@ -3,14 +3,13 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import { LOGICAL_SETTLE_REQUIRED_FRAMES } from "../constants";
 import type { Layout } from "../types/screen.types";
 import { createStore } from "../utils/create-store";
 
 export enum LifecycleTransitionRequestKind {
 	None = 0,
 	Open = 1,
-	ManagedClose = 2,
+	BlankStackClose = 2,
 	NativeClose = 3,
 }
 
@@ -37,11 +36,6 @@ type SystemStoreState = {
 	 */
 	pendingLifecycleRequestTarget: SharedValue<number>;
 
-	/**
-	 * Number of consecutive frames progress has stayed near its target.
-	 */
-	logicalSettleFrameCount: SharedValue<number>;
-
 	/**
 	 * Number of active blockers preventing a pending lifecycle request from
 	 * starting immediately.
@@ -78,7 +72,6 @@ export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 			LifecycleTransitionRequestKind.None,
 		),
 		pendingLifecycleRequestTarget: makeMutable<number>(0),
-		logicalSettleFrameCount: makeMutable(LOGICAL_SETTLE_REQUIRED_FRAMES),
 		pendingLifecycleStartBlockCount: makeMutable<number>(0),
 	}),
 	disposeBag: (bag) => {
@@ -87,7 +80,6 @@ export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 		cancelAnimation(bag.measuredContentLayout);
 		cancelAnimation(bag.pendingLifecycleRequestKind);
 		cancelAnimation(bag.pendingLifecycleRequestTarget);
-		cancelAnimation(bag.logicalSettleFrameCount);
 		cancelAnimation(bag.pendingLifecycleStartBlockCount);
 	},
 	actions: (bag) => ({

package/src/shared/types/animation.types.ts

@@ -1,14 +1,11 @@
 import type { TextStyle, ViewStyle } from "react-native";
-import type {
-	StyleProps,
-	WithSpringConfig,
-	WithTimingConfig,
-} from "react-native-reanimated";
+import type { StyleProps } from "react-native-reanimated";
 import type { EdgeInsets } from "react-native-safe-area-context";
 import {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
 } from "../constants";
+import type { ScreenAnimationConfig } from "../utils/animation/animate";
 import type { BoundsAccessor } from "./bounds.types";
 import type { GestureValues } from "./gesture.types";
 import type { ScreenLayouts, ScreenTransitionConfig } from "./screen.types";
@@ -90,18 +87,19 @@ export type ScreenTransitionState = {
 	animating: number;
 
 	/**
-	 * Whether this screen is fully settled (not transitioning and not dismissing).
-	 * - `0`: Transition/gesture is active or dismissing
-	 * - `1`: Screen is fully settled/idle
+	 * Whether this screen is visually settled for choreography purposes.
+	 * - `0`: The screen is still meaningfully away from its animation target
+	 * - `1`: The screen is close enough to its target to be treated as done
+	 *
+	 * This may become `1` while `animating` is still `1`, since the animation
+	 * driver can keep physically settling after the transition is visually done.
 	 */
 	settled: number;
 
 	/**
-	 * Whether this screen is logically complete for choreography purposes.
-	 * - `0`: The screen is still meaningfully away from its animation target
-	 * - `1`: The screen is visually close enough to its target to be treated as done
+	 * Deprecated alias for `settled`.
 	 *
-	 * Unlike `settled`, this may become `1` before the underlying spring fully stops.
+	 * @deprecated Use `settled` instead.
 	 */
 	logicallySettled: number;
 
@@ -233,7 +231,7 @@ export interface ScreenInterpolationProps {
 	 * Whether the active transition is visually close enough to its target to be
 	 * treated as complete, even if the animation is still physically settling.
 	 *
-	 * @deprecated Use `active.logicallySettled` instead. Screen settlement state
+	 * @deprecated Use `active.settled` instead. Screen settlement state
 	 * belongs on the screen state object.
 	 */
 	logicallySettled: number;
@@ -372,7 +370,7 @@ export type TransitionInterpolatedStyle = {
 /**
  * A Reanimated animation configuration object.
  */
-export type AnimationConfig = WithSpringConfig | WithTimingConfig;
+export type AnimationConfig = ScreenAnimationConfig;
 
 /**
  * Defines separate animation configurations for screen transitions and snap point changes.

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

@@ -240,7 +240,7 @@ export type BoundsNavigationRevealOptions = {
 	backgroundScale?: number;
 	/**
 	 * Whether reveal should reset the unfocused background content scale once the
-	 * transition is logically settled.
+	 * transition is visually settled.
 	 *
 	 * By default, reveal restores the background to scale `1` after settle so the
 	 * next drag or programmatic dismiss starts from a fresh, unmodified layout

package/src/shared/types/gesture.types.ts

@@ -20,18 +20,35 @@ export type GestureProgressMode = "progress-driven" | "freeform";
 
 export type SnapPanAxis = "horizontal" | "vertical";
 
+/**
+ * Axis reported by a transition-aware scrollable.
+ */
 export type ScrollGestureAxis = "vertical" | "horizontal";
 
+/**
+ * Scroll geometry for one axis of a transition-aware scrollable.
+ */
 export type ScrollGestureAxisState = {
 	offset: number;
 	contentSize: number;
 	layoutSize: number;
+	isTouched: boolean;
+};
+
+/**
+ * Scroll metadata exposed through screen transition layouts.
+ */
+export type ScrollMetadataState = {
+	vertical: ScrollGestureAxisState | null;
+	horizontal: ScrollGestureAxisState | null;
 };
 
+/**
+ * Scroll geometry used by gesture coordination.
+ */
 export type ScrollGestureState = {
 	vertical: ScrollGestureAxisState;
 	horizontal: ScrollGestureAxisState;
-	isTouched: boolean;
 };
 
 export type SnapPanAxisConfig = {
@@ -60,12 +77,40 @@ export type SideActivation = {
 	bottom?: ActivationArea;
 };
 
+export type GestureDirectionActivationArea = ActivationArea | number;
+
+export type GestureDirectionConfig = {
+	gesture: GestureDirection;
+	/**
+	 * Pan-only activation area for this gesture direction. Pinch directions
+	 * ignore this field.
+	 *
+	 * A number means an edge distance in points.
+	 */
+	area?: GestureDirectionActivationArea;
+};
+
+export type GestureDirectionEntry = GestureDirection | GestureDirectionConfig;
+
+export type GestureDirectionOption =
+	| GestureDirectionEntry
+	| GestureDirectionEntry[];
+
 export enum GestureActivationState {
 	PENDING,
 	PASSED,
 	FAILED,
 }
 
+export type ResolvedGestureActivationArea =
+	| GestureDirectionActivationArea
+	| {
+			left?: GestureDirectionActivationArea;
+			right?: GestureDirectionActivationArea;
+			top?: GestureDirectionActivationArea;
+			bottom?: GestureDirectionActivationArea;
+	  };
+
 export type GestureActivationArea = ActivationArea | SideActivation;
 
 /**
@@ -86,6 +131,7 @@ export type RawGestureValues = {
 	normY: number;
 	scale: number;
 	normScale: number;
+	rotation: number;
 };
 
 export type GestureValues = {
@@ -129,6 +175,10 @@ export type GestureValues = {
 	 * The live pinch focal point y-position in screen coordinates.
 	 */
 	focalY: number;
+	/**
+	 * The live two-finger rotation in radians.
+	 */
+	rotation: number;
 	/**
 	 * Physical gesture values before `gestureSensitivity` is applied.
 	 */

package/src/shared/types/index.ts

@@ -29,9 +29,17 @@ export type {
 	ActivationArea,
 	GestureActivationArea,
 	GestureDirection,
+	GestureDirectionActivationArea,
+	GestureDirectionConfig,
+	GestureDirectionEntry,
+	GestureDirectionOption,
 	GestureValues,
 	PanGestureDirection,
 	PinchGestureDirection,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	ScrollMetadataState,
 	SideActivation,
 } from "./gesture.types";
 export type { OverlayProps } from "./overlay.types";