react-native-screen-transitions 3.5.2 → 3.6.0-alpha.1

package/src/shared/providers/screen/gestures/ownership/use-walk-up-and-register-shadowing-claims.ts

@@ -0,0 +1,129 @@
+import { useEffect, useMemo } from "react";
+import { GestureStore } from "../../../../stores/gesture.store";
+import {
+	type ClaimedDirections,
+	DIRECTIONS,
+	type Direction,
+} from "../../../../types/ownership.types";
+import { useDescriptorDerivations } from "../../../screen/descriptors";
+import { useGestureContext } from "../gestures.provider";
+import { walkGestureAncestors } from "../shared/ancestors";
+import type { GestureContextType } from "../types";
+
+type ShadowedAncestor = {
+	ancestor: GestureContextType;
+	directions: Direction[];
+};
+
+const NO_SHADOWED_ANCESTORS: ShadowedAncestor[] = [];
+
+const findShadowedDirections = (
+	claimedDirections: ClaimedDirections,
+	ancestorDirections: ClaimedDirections,
+) => {
+	const shadowedDirections: Direction[] = [];
+
+	for (const dir of DIRECTIONS) {
+		if (claimedDirections[dir] && ancestorDirections[dir]) {
+			shadowedDirections.push(dir);
+		}
+	}
+
+	return shadowedDirections;
+};
+
+const findShadowedAncestors = (
+	parentContext: GestureContextType | null,
+	claimedDirections: ClaimedDirections,
+) => {
+	if (!parentContext) {
+		return NO_SHADOWED_ANCESTORS;
+	}
+
+	const ancestors: ShadowedAncestor[] = [];
+	for (const ancestor of walkGestureAncestors(parentContext)) {
+		const directions = findShadowedDirections(
+			claimedDirections,
+			ancestor.claimedDirections,
+		);
+
+		if (directions.length > 0) {
+			ancestors.push({ ancestor, directions });
+		}
+	}
+
+	return ancestors.length ? ancestors : NO_SHADOWED_ANCESTORS;
+};
+
+const registerShadowingClaims = (
+	shadowedAncestors: ShadowedAncestor[],
+	currentScreenKey: string,
+) => {
+	const isDismissing = GestureStore.getValue(currentScreenKey, "dismissing");
+
+	for (const { ancestor, directions } of shadowedAncestors) {
+		const newClaims = { ...ancestor.childDirectionClaims.get() };
+		for (const dir of directions) {
+			newClaims[dir] = { routeKey: currentScreenKey, isDismissing };
+		}
+		ancestor.childDirectionClaims.set(newClaims);
+	}
+};
+
+const clearShadowingClaims = (
+	shadowedAncestors: ShadowedAncestor[],
+	currentScreenKey: string,
+) => {
+	for (const { ancestor, directions } of shadowedAncestors) {
+		const currentClaims = ancestor.childDirectionClaims.get();
+		const newClaims = { ...currentClaims };
+		let needsUpdate = false;
+
+		for (const dir of directions) {
+			// Only remove claims written by this screen; a newer descendant may own it now.
+			if (currentClaims[dir]?.routeKey === currentScreenKey) {
+				newClaims[dir] = null;
+				needsUpdate = true;
+			}
+		}
+
+		if (needsUpdate) {
+			ancestor.childDirectionClaims.set(newClaims);
+		}
+	}
+};
+
+/**
+ * Registers this screen with ancestors that claim the same direction.
+ *
+ * Example, when C is top-most:
+ * A claims vertical
+ * └─ B claims horizontal
+ *    └─ C claims vertical
+ *
+ * C walks up the tree and writes itself into A.childDirectionClaims.vertical.
+ * B is skipped because it does not claim vertical.
+ */
+export function useWalkUpAndRegisterShadowingClaims(
+	claimedDirections: ClaimedDirections,
+): void {
+	const parentContext = useGestureContext();
+	const { isTopMostScreen, currentScreenKey } = useDescriptorDerivations();
+
+	const shadowedAncestors = useMemo(
+		() => findShadowedAncestors(parentContext, claimedDirections),
+		[parentContext, claimedDirections],
+	);
+
+	useEffect(() => {
+		if (!isTopMostScreen || !shadowedAncestors.length) {
+			return;
+		}
+
+		registerShadowingClaims(shadowedAncestors, currentScreenKey);
+
+		return () => {
+			clearShadowingClaims(shadowedAncestors, currentScreenKey);
+		};
+	}, [shadowedAncestors, currentScreenKey, isTopMostScreen]);
+}

package/src/shared/providers/screen/gestures/pan/build-pan-gesture.ts

@@ -0,0 +1,65 @@
+import { useMemo } from "react";
+import { useWindowDimensions } from "react-native";
+import { Gesture } from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import { useScreenOptionsContext } from "../../options";
+import { useGestureBuilderState } from "../hooks/use-gesture-builder-state";
+import { useStableRuntimeConfig } from "../hooks/use-stable-runtime-config";
+import type {
+	DirectionClaimMap,
+	PanGesture,
+	ScreenGestureConfig,
+	ScrollGestureState,
+} from "../types";
+import { usePanActivation } from "./pan-activation";
+import { usePanBehavior } from "./use-pan-behavior";
+
+interface BuildPanGestureHookProps {
+	scrollState: SharedValue<ScrollGestureState | null>;
+	gestureConfig: ScreenGestureConfig;
+	childDirectionClaims: SharedValue<DirectionClaimMap>;
+}
+
+export const useBuildPanGesture = ({
+	scrollState,
+	gestureConfig,
+	childDirectionClaims,
+}: BuildPanGestureHookProps): PanGesture => {
+	const dimensions = useWindowDimensions();
+	const { participation, pan: policy } = gestureConfig;
+	const screenOptions = useScreenOptionsContext();
+
+	const { gestureProgressBaseline, lockedSnapPoint } =
+		useGestureBuilderState(participation);
+
+	const runtime = useStableRuntimeConfig({
+		participation,
+		policy,
+		gestureProgressBaseline,
+		lockedSnapPoint,
+	});
+
+	const activation = usePanActivation({
+		scrollState,
+		childDirectionClaims,
+		runtime,
+		screenOptions,
+		dimensions,
+	});
+
+	const behavior = usePanBehavior(runtime, screenOptions, dimensions);
+
+	const panGesture = useMemo(() => {
+		return Gesture.Pan()
+			.enabled(true)
+			.manualActivation(true)
+			.maxPointers(1)
+			.onTouchesDown(activation.onTouchesDown)
+			.onTouchesMove(activation.onTouchesMove)
+			.onStart(behavior.onStart)
+			.onUpdate(behavior.onUpdate)
+			.onEnd(behavior.onEnd);
+	}, [activation, behavior]);
+
+	return panGesture;
+};

package/src/shared/providers/screen/gestures/pan/pan-activation-decision.ts

@@ -0,0 +1,458 @@
+import type { GestureTouchEvent } from "react-native-gesture-handler";
+import { EPSILON } from "../../../../constants";
+import {
+	GestureActivationState,
+	type ScrollGestureState,
+} from "../../../../types/gesture.types";
+import type { Direction } from "../../../../types/ownership.types";
+import { shouldDeferToChildClaim } from "../ownership/resolve-ownership";
+import { getPanSnapAxisConfigForDirection } from "../shared/directions";
+import { resolveRuntimeSnapPoints } from "../shared/snap-points";
+import type {
+	DirectionClaimMap,
+	GestureDimensions,
+	PanGestureRuntime,
+} from "../types";
+import {
+	checkScrollBoundary,
+	resolveOffsetRules,
+} from "./pan-activation-rules";
+
+export type PanActivationAction = "activate" | "fail" | "wait";
+
+export type PanActivationReason =
+	| "ancestor-dismissing"
+	| "already-dragging"
+	| "child-claim"
+	| "disabled"
+	| "dismissing"
+	| "multi-touch"
+	| "no-direction"
+	| "offset-failed"
+	| "ownership"
+	| "ready"
+	| "scroll-boundary"
+	| "scroll-collapse-only"
+	| "scroll-max-expanded"
+	| "snap-locked"
+	| "threshold-pending";
+
+export interface PanActivationDecision {
+	action: PanActivationAction;
+	reason: PanActivationReason;
+	direction: Direction | null;
+	nextActivationState: GestureActivationState;
+}
+
+interface ResolvePanActivationMoveDecisionProps {
+	event: GestureTouchEvent;
+	runtime: PanGestureRuntime;
+	dimensions: GestureDimensions;
+	initialTouch: { x: number; y: number };
+	activationState: GestureActivationState;
+	ancestorDismissing: boolean;
+	childDirectionClaims: DirectionClaimMap;
+	currentScreenKey: string;
+	scrollState: ScrollGestureState | null;
+}
+
+type OffsetRuleResult = ReturnType<typeof resolveOffsetRules>;
+type ActiveSnapAxis = ReturnType<typeof getPanSnapAxisConfigForDirection>;
+
+const createDecision = (
+	action: PanActivationAction,
+	reason: PanActivationReason,
+	direction: Direction | null,
+	nextActivationState: GestureActivationState,
+): PanActivationDecision => {
+	"worklet";
+	return {
+		action,
+		reason,
+		direction,
+		nextActivationState,
+	};
+};
+
+const getSwipeDirection = ({
+	isSwipingDown,
+	isSwipingUp,
+	isSwipingRight,
+	isSwipingLeft,
+}: {
+	isSwipingDown: boolean;
+	isSwipingUp: boolean;
+	isSwipingRight: boolean;
+	isSwipingLeft: boolean;
+}): Direction | null => {
+	"worklet";
+	if (isSwipingDown) return "vertical";
+	if (isSwipingUp) return "vertical-inverted";
+	if (isSwipingRight) return "horizontal";
+	if (isSwipingLeft) return "horizontal-inverted";
+	return null;
+};
+
+const resolvePreflightDecision = (
+	event: GestureTouchEvent,
+	runtime: PanGestureRuntime,
+	ancestorDismissing: boolean,
+): PanActivationDecision | null => {
+	"worklet";
+	if (event.numberOfTouches !== 1) {
+		return createDecision(
+			"fail",
+			"multi-touch",
+			null,
+			GestureActivationState.FAILED,
+		);
+	}
+
+	if (ancestorDismissing) {
+		return createDecision(
+			"fail",
+			"ancestor-dismissing",
+			null,
+			GestureActivationState.FAILED,
+		);
+	}
+
+	if (!runtime.participation.canTrackGesture || !runtime.policy.enabled) {
+		return createDecision(
+			"fail",
+			"disabled",
+			null,
+			GestureActivationState.FAILED,
+		);
+	}
+
+	return null;
+};
+
+const resolveOffsetFailureDecision = (
+	offset: OffsetRuleResult,
+): PanActivationDecision | null => {
+	"worklet";
+	if (offset.nextActivationState !== GestureActivationState.FAILED) {
+		return null;
+	}
+
+	return createDecision(
+		"fail",
+		"offset-failed",
+		null,
+		offset.nextActivationState,
+	);
+};
+
+const resolveDirectionGateDecision = (
+	swipeDirection: Direction | null,
+	runtime: PanGestureRuntime,
+	offset: OffsetRuleResult,
+	childDirectionClaims: DirectionClaimMap,
+	currentScreenKey: string,
+): PanActivationDecision | null => {
+	"worklet";
+	if (!swipeDirection) {
+		return createDecision(
+			"wait",
+			"no-direction",
+			null,
+			offset.nextActivationState,
+		);
+	}
+
+	if (runtime.participation.ownershipStatus[swipeDirection] !== "self") {
+		return createDecision(
+			"fail",
+			"ownership",
+			swipeDirection,
+			offset.nextActivationState,
+		);
+	}
+
+	const childClaim = childDirectionClaims[swipeDirection];
+	if (shouldDeferToChildClaim(childClaim, currentScreenKey)) {
+		return createDecision(
+			"fail",
+			"child-claim",
+			swipeDirection,
+			offset.nextActivationState,
+		);
+	}
+
+	if (offset.nextActivationState !== GestureActivationState.PASSED) {
+		return createDecision(
+			"wait",
+			"threshold-pending",
+			swipeDirection,
+			offset.nextActivationState,
+		);
+	}
+
+	return null;
+};
+
+const resolveSnapLockDecision = (
+	hasSnapPoints: boolean,
+	gestureSnapLocked: boolean,
+	isExpandGesture: boolean,
+	swipeDirection: Direction,
+	nextActivationState: GestureActivationState,
+): PanActivationDecision | null => {
+	"worklet";
+	if (!hasSnapPoints || !gestureSnapLocked || !isExpandGesture) {
+		return null;
+	}
+
+	return createDecision(
+		"fail",
+		"snap-locked",
+		swipeDirection,
+		nextActivationState,
+	);
+};
+
+const resolveSnapScrollExpansionDecision = (
+	runtime: PanGestureRuntime,
+	swipeDirection: Direction,
+	nextActivationState: GestureActivationState,
+): PanActivationDecision | null => {
+	"worklet";
+	const {
+		participation,
+		policy,
+		stores: { animations, system },
+	} = runtime;
+	const { hasAutoSnapPoint, snapPoints, minSnapPoint, maxSnapPoint } =
+		participation.effectiveSnapPoints;
+
+	if (policy.sheetScrollGestureBehavior === "collapse-only") {
+		return createDecision(
+			"fail",
+			"scroll-collapse-only",
+			swipeDirection,
+			nextActivationState,
+		);
+	}
+
+	const { resolvedMaxSnapPoint } = resolveRuntimeSnapPoints({
+		snapPoints,
+		hasAutoSnapPoint,
+		resolvedAutoSnapPoint: system.resolvedAutoSnapPoint.get(),
+		minSnapPoint,
+		maxSnapPoint,
+		canDismiss: participation.canDismiss,
+	});
+
+	const canExpandMore =
+		animations.progress.get() < resolvedMaxSnapPoint - EPSILON &&
+		system.targetProgress.get() < resolvedMaxSnapPoint - EPSILON;
+
+	if (canExpandMore) {
+		return null;
+	}
+
+	return createDecision(
+		"fail",
+		"scroll-max-expanded",
+		swipeDirection,
+		nextActivationState,
+	);
+};
+
+const resolveDismissingDecision = (
+	hasSnapPoints: boolean,
+	isDismissing: boolean,
+	swipeDirection: Direction,
+	nextActivationState: GestureActivationState,
+): PanActivationDecision | null => {
+	"worklet";
+	if (hasSnapPoints || !isDismissing) {
+		return null;
+	}
+
+	return createDecision(
+		"wait",
+		"dismissing",
+		swipeDirection,
+		nextActivationState,
+	);
+};
+
+const resolveUntouchedScrollDecision = (
+	scrollState: ScrollGestureState | null,
+	swipeDirection: Direction,
+	nextActivationState: GestureActivationState,
+): PanActivationDecision | null => {
+	"worklet";
+	if (scrollState?.isTouched ?? false) {
+		return null;
+	}
+
+	return createDecision(
+		"activate",
+		"ready",
+		swipeDirection,
+		nextActivationState,
+	);
+};
+
+const resolveScrollBoundaryDecision = (
+	scrollState: ScrollGestureState,
+	swipeDirection: Direction,
+	activeSnapAxis: ActiveSnapAxis,
+	nextActivationState: GestureActivationState,
+): PanActivationDecision | null => {
+	"worklet";
+	const atBoundary = checkScrollBoundary(
+		scrollState,
+		swipeDirection,
+		activeSnapAxis?.config.inverted,
+	);
+
+	if (atBoundary) {
+		return null;
+	}
+
+	return createDecision(
+		"fail",
+		"scroll-boundary",
+		swipeDirection,
+		nextActivationState,
+	);
+};
+
+const resolveScrollDecision = (
+	runtime: PanGestureRuntime,
+	scrollState: ScrollGestureState | null,
+	swipeDirection: Direction,
+	activeSnapAxis: ActiveSnapAxis,
+	isExpandGesture: boolean,
+	nextActivationState: GestureActivationState,
+): PanActivationDecision => {
+	"worklet";
+	const hasSnapPoints = runtime.participation.effectiveSnapPoints.hasSnapPoints;
+
+	const dismissingDecision = resolveDismissingDecision(
+		hasSnapPoints,
+		Boolean(runtime.stores.gestures.dismissing.get()),
+		swipeDirection,
+		nextActivationState,
+	);
+	if (dismissingDecision) return dismissingDecision;
+
+	const untouchedScrollDecision = resolveUntouchedScrollDecision(
+		scrollState,
+		swipeDirection,
+		nextActivationState,
+	);
+	if (untouchedScrollDecision) return untouchedScrollDecision;
+
+	const activeScrollState = scrollState as ScrollGestureState;
+	const boundaryDecision = resolveScrollBoundaryDecision(
+		activeScrollState,
+		swipeDirection,
+		activeSnapAxis,
+		nextActivationState,
+	);
+	if (boundaryDecision) return boundaryDecision;
+
+	const snapExpandDecision =
+		hasSnapPoints && isExpandGesture
+			? resolveSnapScrollExpansionDecision(
+					runtime,
+					swipeDirection,
+					nextActivationState,
+				)
+			: null;
+
+	return (
+		snapExpandDecision ??
+		createDecision("activate", "ready", swipeDirection, nextActivationState)
+	);
+};
+
+export const resolvePanActivationMoveDecision = ({
+	event,
+	runtime,
+	dimensions,
+	initialTouch,
+	activationState,
+	ancestorDismissing,
+	childDirectionClaims,
+	currentScreenKey,
+	scrollState,
+}: ResolvePanActivationMoveDecisionProps): PanActivationDecision => {
+	"worklet";
+	const preflightDecision = resolvePreflightDecision(
+		event,
+		runtime,
+		ancestorDismissing,
+	);
+	if (preflightDecision) return preflightDecision;
+
+	const { policy } = runtime;
+	const touch = event.changedTouches[0];
+	const offset = resolveOffsetRules({
+		touch,
+		initialTouch,
+		directions: policy.panActivationDirections,
+		dimensions,
+		activationState,
+		activationArea: policy.gestureActivationArea,
+		responseDistance: policy.gestureResponseDistance,
+	});
+
+	const offsetFailureDecision = resolveOffsetFailureDecision(offset);
+	if (offsetFailureDecision) return offsetFailureDecision;
+
+	if (runtime.stores.gestures.dragging.get()) {
+		return createDecision(
+			"activate",
+			"already-dragging",
+			null,
+			offset.nextActivationState,
+		);
+	}
+
+	const swipeDirection = getSwipeDirection(offset);
+	const directionGateDecision = resolveDirectionGateDecision(
+		swipeDirection,
+		runtime,
+		offset,
+		childDirectionClaims,
+		currentScreenKey,
+	);
+	if (directionGateDecision) return directionGateDecision;
+
+	const activeDirection = swipeDirection as Direction;
+	const { participation } = runtime;
+	const { hasSnapPoints } = participation.effectiveSnapPoints;
+
+	const activeSnapAxis = hasSnapPoints
+		? getPanSnapAxisConfigForDirection(
+				policy.snapAxisDirections,
+				activeDirection,
+			)
+		: null;
+	const isExpandGesture = activeSnapAxis?.config.expand === activeDirection;
+
+	const snapLockDecision = resolveSnapLockDecision(
+		hasSnapPoints,
+		policy.gestureSnapLocked,
+		isExpandGesture,
+		activeDirection,
+		offset.nextActivationState,
+	);
+	if (snapLockDecision) return snapLockDecision;
+
+	return resolveScrollDecision(
+		runtime,
+		scrollState,
+		activeDirection,
+		activeSnapAxis,
+		isExpandGesture,
+		offset.nextActivationState,
+	);
+};