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

package/src/shared/providers/screen/gestures/scroll-coordination/use-scroll-gesture-coordination.ts

@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { useLayoutEffect, useMemo, useState } from "react";
 import type { LayoutChangeEvent } from "react-native";
 import { Gesture, type GestureType } from "react-native-gesture-handler";
 import {
@@ -9,13 +9,23 @@ import {
 import { useSharedValueState } from "../../../../hooks/reanimated/use-shared-value-state";
 import useStableCallback from "../../../../hooks/use-stable-callback";
 import { AnimationStore } from "../../../../stores/animation.store";
+import { ScrollStore } from "../../../../stores/scroll.store";
 import { useGestureContext } from "../gestures.provider";
 import type {
 	ScrollGestureAxis,
 	ScrollGestureAxisState,
 	ScrollGestureState,
+	ScrollMetadataState,
 } from "../types";
-import { updateScrollGestureAxisState } from "./update-scroll-gesture-state";
+import {
+	useScrollMetadataOwnerContext,
+	useScrollMetadataOwnerProviderValue,
+} from "./scroll-metadata-owner";
+import {
+	clearScrollMetadataAxisState,
+	updateScrollGestureAxisState,
+	updateScrollMetadataAxisState,
+} from "./update-scroll-gesture-state";
 import { walkUpScrollGestureCoordination } from "./walk-up-scroll-gesture-coordination";
 
 interface ScrollGestureCoordinationProps {
@@ -41,6 +51,31 @@ const modifyScrollGestureAxisState = (
 	});
 };
 
+const modifyScrollMetadataAxisState = (
+	scrollState: SharedValue<ScrollMetadataState | null>,
+	axis: ScrollGestureAxis,
+	patch: ScrollGesturePatch,
+) => {
+	"worklet";
+
+	scrollState.modify(<T extends ScrollMetadataState | null>(state: T): T => {
+		"worklet";
+		return updateScrollMetadataAxisState(state, axis, patch) as T;
+	});
+};
+
+const clearScrollMetadataAxis = (
+	scrollState: SharedValue<ScrollMetadataState | null>,
+	axis: ScrollGestureAxis,
+) => {
+	"worklet";
+
+	scrollState.modify(<T extends ScrollMetadataState | null>(state: T): T => {
+		"worklet";
+		return clearScrollMetadataAxisState(state, axis) as T;
+	});
+};
+
 /**
  * Returns scroll handlers and a native gesture for ScrollView coordination.
  *
@@ -56,11 +91,63 @@ export const useScrollGestureCoordination = (
 	const context = useGestureContext();
 	const scrollDirection = props.direction ?? "vertical";
 
+	const metadataOwnerContext = useScrollMetadataOwnerContext();
+	const metadataOwnerProviderValue =
+		useScrollMetadataOwnerProviderValue(scrollDirection);
+	const isFirstMetadataWriterInTree = !metadataOwnerContext[scrollDirection];
+	const [metadataWriterId] = useState(() =>
+		ScrollStore.createMetadataWriterId(),
+	);
+	const [writesMetadata, setWritesMetadata] = useState(false);
+
 	const { scrollStates, panGestures, pinchGestures, ownerRouteKeys } = useMemo(
 		() => walkUpScrollGestureCoordination(context, scrollDirection),
 		[context, scrollDirection],
 	);
 
+	const routeKey = context?.routeKey;
+	const metadataState = useMemo(
+		() => (routeKey ? ScrollStore.getValue(routeKey, "metadata") : null),
+		[routeKey],
+	);
+
+	useLayoutEffect(() => {
+		if (!routeKey || !isFirstMetadataWriterInTree) {
+			setWritesMetadata(false);
+			return;
+		}
+
+		const claimed = ScrollStore.claimMetadataWriter(
+			routeKey,
+			scrollDirection,
+			metadataWriterId,
+		);
+		setWritesMetadata(claimed);
+
+		return () => {
+			const released = ScrollStore.releaseMetadataWriter(
+				routeKey,
+				scrollDirection,
+				metadataWriterId,
+			);
+
+			if (!released || !metadataState) return;
+
+			if (!ScrollStore.hasMetadataWriters(routeKey)) {
+				metadataState.set(null);
+				return;
+			}
+
+			clearScrollMetadataAxis(metadataState, scrollDirection);
+		};
+	}, [
+		routeKey,
+		scrollDirection,
+		isFirstMetadataWriterInTree,
+		metadataState,
+		metadataWriterId,
+	]);
+
 	const ownerClosingValues = useMemo(
 		() =>
 			ownerRouteKeys.map((routeKey) =>
@@ -92,6 +179,12 @@ export const useScrollGestureCoordination = (
 					isTouched: true,
 				});
 			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					isTouched: true,
+				});
+			}
 		};
 
 		const clearIsTouched = () => {
@@ -101,6 +194,12 @@ export const useScrollGestureCoordination = (
 					isTouched: false,
 				});
 			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					isTouched: false,
+				});
+			}
 		};
 
 		let gesture = Gesture.Native()
@@ -121,12 +220,17 @@ export const useScrollGestureCoordination = (
 		}
 
 		return gesture;
-	}, [panGestures, pinchGestures, scrollStates, scrollDirection]);
+	}, [
+		panGestures,
+		pinchGestures,
+		scrollStates,
+		scrollDirection,
+		writesMetadata,
+		metadataState,
+	]);
 
 	const scrollHandler = useAnimatedScrollHandler({
 		onScroll: (event) => {
-			if (scrollStates.length === 0) return;
-
 			const offset =
 				scrollDirection === "horizontal"
 					? event.contentOffset.x
@@ -135,7 +239,14 @@ export const useScrollGestureCoordination = (
 			for (const scrollState of scrollStates) {
 				modifyScrollGestureAxisState(scrollState, scrollDirection, {
 					offset,
-					isTouched: scrollState.get()?.isTouched ?? true,
+					isTouched: scrollState.get()?.[scrollDirection].isTouched ?? true,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					offset,
+					isTouched: metadataState.get()?.[scrollDirection]?.isTouched ?? true,
 				});
 			}
 		},
@@ -144,7 +255,6 @@ export const useScrollGestureCoordination = (
 	const onContentSizeChange = useStableCallback(
 		(width: number, height: number) => {
 			props.onContentSizeChange?.(width, height);
-			if (scrollStates.length === 0) return;
 
 			const contentSize = scrollDirection === "horizontal" ? width : height;
 
@@ -153,12 +263,17 @@ export const useScrollGestureCoordination = (
 					contentSize,
 				});
 			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					contentSize,
+				});
+			}
 		},
 	);
 
 	const onLayout = useStableCallback((event: LayoutChangeEvent) => {
 		props.onLayout?.(event);
-		if (scrollStates.length === 0) return;
 
 		const { width, height } = event.nativeEvent.layout;
 		const layoutSize = scrollDirection === "horizontal" ? width : height;
@@ -168,6 +283,12 @@ export const useScrollGestureCoordination = (
 				layoutSize,
 			});
 		}
+
+		if (writesMetadata && metadataState) {
+			modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+				layoutSize,
+			});
+		}
 	});
 
 	return {
@@ -176,5 +297,6 @@ export const useScrollGestureCoordination = (
 		onContentSizeChange,
 		onLayout,
 		nativeGesture,
+		metadataOwnerProviderValue,
 	};
 };

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

@@ -21,6 +21,7 @@ import type {
 	ScrollGestureAxis,
 	ScrollGestureAxisState,
 	ScrollGestureState,
+	ScrollMetadataState,
 	SnapPanDirectionConfig,
 	SnapPinchDirectionConfig,
 } from "../../../types/gesture.types";
@@ -56,6 +57,7 @@ export type {
 	ScrollGestureAxis,
 	ScrollGestureAxisState,
 	ScrollGestureState,
+	ScrollMetadataState,
 };
 
 export type DirectionClaim = {

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/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 = {

package/src/shared/types/index.ts

@@ -36,6 +36,10 @@ export type {
 	GestureValues,
 	PanGestureDirection,
 	PinchGestureDirection,
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	ScrollMetadataState,
 	SideActivation,
 } from "./gesture.types";
 export type { OverlayProps } from "./overlay.types";

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

@@ -7,6 +7,7 @@ import type {
 	GestureActivationArea,
 	GestureDirectionOption,
 	GestureProgressMode,
+	ScrollMetadataState,
 } from "./gesture.types";
 import type { OverlayProps } from "./overlay.types";
 
@@ -27,6 +28,13 @@ export type ScreenLayouts = {
 	 * auto snap-point sizing. It is undefined until a real measurement exists.
 	 */
 	content?: Layout;
+	/**
+	 * Scroll metadata from the primary transition-aware scrollable on this screen.
+	 *
+	 * For nested same-axis scrollables, the outermost scrollable owns that axis.
+	 * Cross-axis nested scrollables can each publish their own axis.
+	 */
+	scroll?: ScrollMetadataState;
 };
 
 export type ScreenKey = string;

package/src/shared/utils/animation/spring/spring.ts

@@ -142,7 +142,7 @@ export const withInternalSpring = ((
 
 		let settled = false;
 
-		const updateSettled = (animation: SpringAnimation) => {
+		const notifySettled = (animation: SpringAnimation) => {
 			"worklet";
 			if (settled) {
 				return;
@@ -154,6 +154,10 @@ export const withInternalSpring = ((
 
 			settled = true;
 			animation.settled = true;
+			callback?.({
+				finished: false,
+				settled: true,
+			});
 		};
 
 		config.skipAnimation = !checkIfConfigIsValid(config);
@@ -215,7 +219,7 @@ export const withInternalSpring = ((
 				return true;
 			}
 
-			updateSettled(animation);
+			notifySettled(animation);
 
 			return false;
 		}
@@ -310,7 +314,7 @@ export const withInternalSpring = ((
 				? previousAnimation?.startTimestamp || now
 				: now;
 
-			updateSettled(animation);
+			notifySettled(animation);
 		}
 
 		const animation = {