react-native-screen-transitions 4.1.0-beta.1 → 4.1.0-rc.0

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

@@ -0,0 +1,306 @@
+import { useLayoutEffect, useMemo, useState } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import { Gesture, type GestureType } from "react-native-gesture-handler";
+import {
+	type SharedValue,
+	useAnimatedScrollHandler,
+	useDerivedValue,
+} from "react-native-reanimated";
+import { useSharedValueState } from "../../../../hooks/reanimated/use-shared-value-state";
+import useStableCallback from "../../../../hooks/use-stable-callback";
+import { ScrollStore } from "../../../../stores/scroll.store";
+import { useMotionStore, useOptionalMotionStore } from "../..";
+import { useGestureScrollCoordination } from "../ownership/use-gesture-scroll-coordination";
+import type {
+	ScrollGestureAxis,
+	ScrollGestureAxisState,
+	ScrollGestureState,
+	ScrollMetadataState,
+} from "../types";
+import {
+	useOptionalScrollMetadataOwnerStore,
+	useScrollMetadataOwnerProviderValue,
+} from "./scroll-metadata-owner";
+import {
+	clearScrollMetadataAxisState,
+	updateScrollGestureAxisState,
+	updateScrollMetadataAxisState,
+} from "./update-scroll-gesture-state";
+
+interface ScrollGestureCoordinationProps {
+	onContentSizeChange?: (width: number, height: number) => void;
+	onLayout?: (event: LayoutChangeEvent) => void;
+	direction?: ScrollGestureAxis;
+}
+
+type ScrollGesturePatch = Partial<ScrollGestureAxisState> & {
+	isTouched?: boolean;
+};
+
+const modifyScrollGestureAxisState = (
+	scrollState: SharedValue<ScrollGestureState | null>,
+	axis: ScrollGestureAxis,
+	patch: ScrollGesturePatch,
+) => {
+	"worklet";
+
+	scrollState.modify(<T extends ScrollGestureState | null>(state: T): T => {
+		"worklet";
+		return updateScrollGestureAxisState(state, axis, patch) as T;
+	});
+};
+
+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.
+ *
+ * Finds ALL gesture owners for the scroll axis (both directions) and coordinates
+ * with each of them. This ensures that:
+ * - A screen claiming `vertical-inverted` can handle swipe-up at bottom boundary
+ * - An ancestor claiming `vertical` can handle swipe-down at top boundary
+ * - Both work correctly with the same ScrollView
+ */
+export const useScrollGestureCoordination = (
+	props: ScrollGestureCoordinationProps,
+) => {
+	const context = useOptionalMotionStore((store) => store?.gestures ?? null);
+	const scrollDirection = props.direction ?? "vertical";
+	const routeKey = context?.routeKey ?? null;
+	const { scrollStates, panGestures, pinchGestures, ownerRouteKeys } =
+		useGestureScrollCoordination(routeKey, scrollDirection);
+
+	const metadataOwnerContext = useOptionalScrollMetadataOwnerStore();
+	const metadataOwnerProviderValue =
+		useScrollMetadataOwnerProviderValue(scrollDirection);
+	const isFirstMetadataWriterInTree = !metadataOwnerContext?.[scrollDirection];
+	const [metadataWriterId] = useState(() =>
+		ScrollStore.createMetadataWriterId(),
+	);
+	const [writesMetadata, setWritesMetadata] = useState(false);
+
+	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 ownerMotions = useMotionStore(ownerRouteKeys);
+	const ownerClosingValues = useMemo(
+		() =>
+			ownerMotions.flatMap((motion) => (motion ? [motion.state.closing] : [])),
+		[ownerMotions],
+	);
+
+	const scrollEventsEnabled = useSharedValueState(
+		useDerivedValue(() => {
+			"worklet";
+			for (let i = 0; i < ownerClosingValues.length; i++) {
+				if (ownerClosingValues[i].get()) {
+					return false;
+				}
+			}
+
+			return true;
+		}),
+	);
+
+	const nativeGesture = useMemo(() => {
+		// Ownership registrations disappear while a screen's Activity is paused.
+		// Keep its detector mounted through that gap: removing the wrapper remounts
+		// scroll children and loses state, including captured boundary measurements.
+		if (!routeKey) return null;
+
+		const setIsTouched = () => {
+			"worklet";
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					isTouched: true,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					isTouched: true,
+				});
+			}
+		};
+
+		const clearIsTouched = () => {
+			"worklet";
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					isTouched: false,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					isTouched: false,
+				});
+			}
+		};
+
+		let gesture = Gesture.Native()
+			.onTouchesDown(setIsTouched)
+			.onTouchesUp(clearIsTouched)
+			.onTouchesCancelled(clearIsTouched);
+
+		for (const panGesture of panGestures) {
+			gesture = gesture.requireExternalGestureToFail({
+				current: panGesture as unknown as GestureType,
+			});
+		}
+
+		for (const pinchGesture of pinchGestures) {
+			// A pinch must remain possible after the first finger lands. Making
+			// native scrolling wait for it to fail therefore stalls ordinary
+			// one-finger scrolling until touch-up. Let both recognizers run:
+			// the ScrollView can begin immediately, while a second finger can
+			// still promote the screen gesture to a pinch.
+			gesture = gesture.simultaneousWithExternalGesture({
+				current: pinchGesture as unknown as GestureType,
+			});
+		}
+
+		return gesture;
+	}, [
+		routeKey,
+		panGestures,
+		pinchGestures,
+		scrollStates,
+		scrollDirection,
+		writesMetadata,
+		metadataState,
+	]);
+
+	const scrollHandler = useAnimatedScrollHandler({
+		onScroll: (event) => {
+			const offset =
+				scrollDirection === "horizontal"
+					? event.contentOffset.x
+					: event.contentOffset.y;
+
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					offset,
+					isTouched: scrollState.get()?.[scrollDirection].isTouched ?? true,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					offset,
+					isTouched: metadataState.get()?.[scrollDirection]?.isTouched ?? true,
+				});
+			}
+		},
+	});
+
+	const onContentSizeChange = useStableCallback(
+		(width: number, height: number) => {
+			props.onContentSizeChange?.(width, height);
+
+			const contentSize = scrollDirection === "horizontal" ? width : height;
+
+			for (const scrollState of scrollStates) {
+				modifyScrollGestureAxisState(scrollState, scrollDirection, {
+					contentSize,
+				});
+			}
+
+			if (writesMetadata && metadataState) {
+				modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+					contentSize,
+				});
+			}
+		},
+	);
+
+	const onLayout = useStableCallback((event: LayoutChangeEvent) => {
+		props.onLayout?.(event);
+
+		const { width, height } = event.nativeEvent.layout;
+		const layoutSize = scrollDirection === "horizontal" ? width : height;
+
+		for (const scrollState of scrollStates) {
+			modifyScrollGestureAxisState(scrollState, scrollDirection, {
+				layoutSize,
+			});
+		}
+
+		if (writesMetadata && metadataState) {
+			modifyScrollMetadataAxisState(metadataState, scrollDirection, {
+				layoutSize,
+			});
+		}
+	});
+
+	return {
+		scrollHandler,
+		scrollEventsEnabled,
+		onContentSizeChange,
+		onLayout,
+		nativeGesture,
+		metadataOwnerProviderValue,
+	};
+};

package/src/providers/motion/gestures/shared/directions.ts

@@ -0,0 +1,219 @@
+import type {
+	ActiveGesture,
+	GestureDirection,
+	GestureDirectionEntry,
+	GestureDirectionOption,
+	GestureDirections,
+	PanGestureDirection,
+	PinchGestureDirection,
+	ResolvedPanGestureDirection,
+	SnapPanAxis,
+	SnapPanAxisConfig,
+	SnapPanDirectionConfig,
+	SnapPinchDirectionConfig,
+} from "../../../../types/gesture.types";
+import type { Direction } from "../../../../types/ownership.types";
+
+interface GetPanActivationDirectionsProps {
+	gestureDirection: GestureDirectionOption;
+	hasSnapPoints: boolean;
+}
+
+const isPinchGestureDirection = (
+	direction: GestureDirection,
+): direction is PinchGestureDirection => {
+	"worklet";
+	return direction === "pinch-in" || direction === "pinch-out";
+};
+
+const isPanGestureDirection = (
+	direction: GestureDirection,
+): direction is PanGestureDirection => {
+	"worklet";
+	return !isPinchGestureDirection(direction);
+};
+
+export const isResolvedPanGestureDirection = (
+	gesture: ActiveGesture | null,
+): gesture is ResolvedPanGestureDirection => {
+	"worklet";
+	return (
+		gesture === "horizontal" ||
+		gesture === "horizontal-inverted" ||
+		gesture === "vertical" ||
+		gesture === "vertical-inverted"
+	);
+};
+
+export const getGestureDirectionEntryGesture = (
+	entry: GestureDirectionEntry,
+): GestureDirection => {
+	"worklet";
+	return typeof entry === "string" ? entry : entry.gesture;
+};
+
+export const getGestureDirectionEntries = (
+	gestureDirection: GestureDirectionOption,
+): GestureDirectionEntry[] => {
+	"worklet";
+	return Array.isArray(gestureDirection)
+		? gestureDirection
+		: [gestureDirection];
+};
+
+export const getPanGestureDirections = (
+	gestureDirection: GestureDirectionOption,
+): PanGestureDirection[] => {
+	"worklet";
+	const panDirections: PanGestureDirection[] = [];
+
+	for (const entry of getGestureDirectionEntries(gestureDirection)) {
+		const direction = getGestureDirectionEntryGesture(entry);
+		if (isPanGestureDirection(direction)) {
+			panDirections.push(direction);
+		}
+	}
+
+	return panDirections;
+};
+
+export const getPinchGestureDirections = (
+	gestureDirection: GestureDirectionOption,
+): PinchGestureDirection[] => {
+	"worklet";
+	const pinchDirections: PinchGestureDirection[] = [];
+
+	for (const entry of getGestureDirectionEntries(gestureDirection)) {
+		const direction = getGestureDirectionEntryGesture(entry);
+		if (isPinchGestureDirection(direction)) {
+			pinchDirections.push(direction);
+		}
+	}
+
+	return pinchDirections;
+};
+
+const getOppositePanDirection = (
+	direction: ResolvedPanGestureDirection,
+): ResolvedPanGestureDirection => {
+	"worklet";
+	switch (direction) {
+		case "horizontal":
+			return "horizontal-inverted";
+		case "horizontal-inverted":
+			return "horizontal";
+		case "vertical":
+			return "vertical-inverted";
+		case "vertical-inverted":
+			return "vertical";
+	}
+};
+
+const getPanDirectionAxis = (
+	direction: ResolvedPanGestureDirection,
+): SnapPanAxis => {
+	"worklet";
+	return direction === "horizontal" || direction === "horizontal-inverted"
+		? "horizontal"
+		: "vertical";
+};
+
+const setSnapPanAxisConfig = (
+	config: SnapPanDirectionConfig,
+	direction: ResolvedPanGestureDirection,
+) => {
+	"worklet";
+	const axis = getPanDirectionAxis(direction);
+
+	if (config[axis]) return;
+
+	config[axis] = {
+		collapse: direction,
+		expand: getOppositePanDirection(direction),
+		inverted:
+			direction === "horizontal-inverted" || direction === "vertical-inverted",
+		progressSign:
+			direction === "horizontal-inverted" || direction === "vertical-inverted"
+				? 1
+				: -1,
+	};
+};
+
+export const getPanSnapAxisDirections = (
+	gestureDirection: GestureDirectionOption,
+): SnapPanDirectionConfig => {
+	"worklet";
+	const config: SnapPanDirectionConfig = {
+		horizontal: null,
+		vertical: null,
+	};
+
+	for (const direction of getPanGestureDirections(gestureDirection)) {
+		if (direction === "bidirectional") {
+			setSnapPanAxisConfig(config, "horizontal");
+			setSnapPanAxisConfig(config, "vertical");
+			continue;
+		}
+
+		setSnapPanAxisConfig(config, direction);
+	}
+
+	return config;
+};
+
+export const getSnapPinchDirectionConfig = (
+	gestureDirection: GestureDirectionOption,
+): SnapPinchDirectionConfig => {
+	"worklet";
+	const pinchDirection = getPinchGestureDirections(gestureDirection)[0];
+
+	if (!pinchDirection) return null;
+
+	return {
+		collapse: pinchDirection,
+		expand: pinchDirection === "pinch-in" ? "pinch-out" : "pinch-in",
+	};
+};
+
+export const getPanActivationDirections = ({
+	gestureDirection,
+	hasSnapPoints,
+}: GetPanActivationDirectionsProps): GestureDirections => {
+	"worklet";
+	const panDirections = getPanGestureDirections(gestureDirection);
+
+	if (hasSnapPoints) {
+		const snapAxisDirections = getPanSnapAxisDirections(gestureDirection);
+
+		return {
+			vertical: !!snapAxisDirections.vertical,
+			verticalInverted: !!snapAxisDirections.vertical,
+			horizontal: !!snapAxisDirections.horizontal,
+			horizontalInverted: !!snapAxisDirections.horizontal,
+		};
+	}
+
+	const isBidirectional = panDirections.includes("bidirectional");
+
+	return {
+		vertical: panDirections.includes("vertical") || isBidirectional,
+		verticalInverted:
+			panDirections.includes("vertical-inverted") || isBidirectional,
+		horizontal: panDirections.includes("horizontal") || isBidirectional,
+		horizontalInverted:
+			panDirections.includes("horizontal-inverted") || isBidirectional,
+	};
+};
+
+export const getPanSnapAxisConfigForDirection = (
+	snapAxisDirections: SnapPanDirectionConfig,
+	direction: Direction,
+): { axis: SnapPanAxis; config: SnapPanAxisConfig } | null => {
+	"worklet";
+	const axis = getPanDirectionAxis(direction);
+	const config = snapAxisDirections[axis];
+
+	if (!config) return null;
+
+	return { axis, config };
+};