react-native-screen-transitions 3.3.0 → 3.4.0-alpha.0

package/src/shared/utils/bounds/sugar/navigation/zoom.ts

@@ -0,0 +1,348 @@
+import { interpolate } from "react-native-reanimated";
+import {
+	EPSILON,
+	NAVIGATION_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_STYLE_ID,
+	NO_STYLES,
+} from "../../../../constants";
+import { BoundStore } from "../../../../stores/bounds";
+import type { TransitionInterpolatedStyle } from "../../../../types/animation.types";
+import type { Layout } from "../../../../types/screen.types";
+import { interpolateClamped } from "../../helpers/interpolate";
+import {
+	combineScales,
+	composeCompensatedTranslation,
+	computeCenterScaleShift,
+	normalizedToScale,
+	normalizedToTranslation,
+} from "../../helpers/math";
+import type { BoundsOptions } from "../../types/options";
+import { resolveNavigationConfig, toNumber } from "./helpers";
+import type { BuildNavigationStylesParams } from "./types";
+
+const DRAG_RESISTANCE = 0.4;
+const DIRECTIONAL_DRAG_SCALE_OUTPUT = [1, 0.25] as const;
+const IDENTITY_DRAG_SCALE_OUTPUT = [1, 1] as const;
+
+const getZoomContentTarget = ({
+	explicitTarget,
+	resolvedTag,
+	currentRouteKey,
+	previousRouteKey,
+	nextRouteKey,
+	entering,
+	screenLayout,
+	anchor,
+}: {
+	explicitTarget: BoundsOptions["target"] | undefined;
+	resolvedTag: string;
+	currentRouteKey?: string;
+	previousRouteKey?: string;
+	nextRouteKey?: string;
+	entering: boolean;
+	screenLayout: Layout;
+	anchor: BoundsOptions["anchor"] | undefined;
+}) => {
+	"worklet";
+	if (explicitTarget !== undefined) return explicitTarget;
+
+	const resolvedPair = BoundStore.resolveTransitionPair(resolvedTag, {
+		currentScreenKey: currentRouteKey,
+		previousScreenKey: previousRouteKey,
+		nextScreenKey: nextRouteKey,
+		entering,
+	});
+	const sourceBounds = resolvedPair.sourceBounds;
+	const screenWidth = screenLayout.width;
+
+	if (!sourceBounds || sourceBounds.width <= 0 || screenWidth <= 0) {
+		return "fullscreen" as const;
+	}
+
+	const height = (sourceBounds.height / sourceBounds.width) * screenWidth;
+	let horizontalAnchor: "leading" | "center" | "trailing";
+	switch (anchor) {
+		case "topLeading":
+		case "leading":
+		case "bottomLeading":
+			horizontalAnchor = "leading";
+			break;
+		case "topTrailing":
+		case "trailing":
+		case "bottomTrailing":
+			horizontalAnchor = "trailing";
+			break;
+		default:
+			horizontalAnchor = "center";
+			break;
+	}
+
+	let verticalAnchor: "top" | "center" | "bottom";
+	switch (anchor) {
+		case "topLeading":
+		case "top":
+		case "topTrailing":
+			verticalAnchor = "top";
+			break;
+		case "bottomLeading":
+		case "bottom":
+		case "bottomTrailing":
+			verticalAnchor = "bottom";
+			break;
+		default:
+			verticalAnchor = "center";
+			break;
+	}
+	const x =
+		horizontalAnchor === "leading"
+			? 0
+			: horizontalAnchor === "trailing"
+				? screenLayout.width - screenWidth
+				: (screenLayout.width - screenWidth) / 2;
+	const y =
+		verticalAnchor === "top"
+			? 0
+			: verticalAnchor === "bottom"
+				? screenLayout.height - height
+				: (screenLayout.height - height) / 2;
+
+	return {
+		x,
+		y,
+		pageX: x,
+		pageY: y,
+		width: screenWidth,
+		height,
+	};
+};
+
+export const buildZoomNavigationStyles = ({
+	id,
+	group,
+	navigationOptions,
+	props,
+	resolveTag,
+	computeRaw,
+}: BuildNavigationStylesParams): TransitionInterpolatedStyle => {
+	"worklet";
+
+	const focused = props.focused;
+	const progress = props.progress;
+	const currentRouteKey = props.current?.route.key;
+	const previousRouteKey = props.previous?.route.key;
+	const nextRouteKey = props.next?.route.key;
+	const entering = !props.next;
+	const screenLayout = props.layouts.screen;
+
+	const normX = props.active.gesture.normX;
+	const normY = props.active.gesture.normY;
+	const initialDirection = props.active.gesture.direction;
+
+	const xScaleOutput =
+		initialDirection === "horizontal"
+			? DIRECTIONAL_DRAG_SCALE_OUTPUT
+			: IDENTITY_DRAG_SCALE_OUTPUT;
+	const yScaleOutput =
+		initialDirection === "vertical"
+			? DIRECTIONAL_DRAG_SCALE_OUTPUT
+			: IDENTITY_DRAG_SCALE_OUTPUT;
+
+	const dragX = normalizedToTranslation({
+		normalized: normX,
+		dimension: screenLayout.width,
+		resistance: DRAG_RESISTANCE,
+	});
+	const dragY = normalizedToTranslation({
+		normalized: normY,
+		dimension: screenLayout.height,
+		resistance: DRAG_RESISTANCE,
+	});
+	const dragXScale = normalizedToScale({
+		normalized: normX,
+		outputRange: xScaleOutput,
+		exponent: 2,
+	});
+	const dragYScale = normalizedToScale({
+		normalized: normY,
+		outputRange: yScaleOutput,
+		exponent: 2,
+	});
+	const dragScale = combineScales(dragXScale, dragYScale);
+
+	const resolvedConfig = resolveNavigationConfig({
+		id,
+		group,
+		navigationOptions,
+		currentRouteKey,
+		resolveTag,
+		defaultAnchor: "top",
+	});
+
+	if (!resolvedConfig) return NO_STYLES;
+
+	const { resolvedTag, sharedOptions, explicitTarget } = resolvedConfig;
+
+	if (focused) {
+		const contentTarget = getZoomContentTarget({
+			explicitTarget,
+			resolvedTag,
+			currentRouteKey,
+			previousRouteKey,
+			nextRouteKey,
+			entering,
+			screenLayout,
+			anchor: sharedOptions.anchor,
+		});
+
+		const contentRaw = computeRaw({
+			...sharedOptions,
+			method: "content",
+			target: contentTarget,
+		});
+
+		const maskRaw = computeRaw({
+			...sharedOptions,
+			method: "size",
+			space: "absolute",
+			target: "fullscreen",
+		});
+
+		const focusedFade = props.active?.closing
+			? interpolate(progress, [0.6, 1], [0, 1], "clamp")
+			: interpolate(progress, [0, 0.5], [0, 1], "clamp");
+		const maskWidth = Math.max(1, toNumber(maskRaw.width));
+		const maskHeight = Math.max(1, toNumber(maskRaw.height));
+		const contentTranslateX = toNumber(contentRaw.translateX) + dragX;
+		const contentTranslateY = toNumber(contentRaw.translateY) + dragY;
+		const contentScale = toNumber(contentRaw.scale, 1) * dragScale;
+		const maskTranslateX = toNumber(maskRaw.translateX) + dragX;
+		const maskTranslateY = toNumber(maskRaw.translateY) + dragY;
+
+		return {
+			[NAVIGATION_CONTAINER_STYLE_ID]: {
+				style: {
+					opacity: focusedFade,
+					transform: [
+						{ translateX: contentTranslateX },
+						{ translateY: contentTranslateY },
+						{ scale: contentScale },
+					],
+				},
+			},
+			[NAVIGATION_MASK_STYLE_ID]: {
+				style: {
+					width: maskWidth,
+					height: maskHeight,
+					transform: [
+						{ translateX: maskTranslateX },
+						{ translateY: maskTranslateY },
+						{ scale: dragScale },
+					],
+					borderRadius: 12,
+				},
+			},
+			// Signal the destination boundary to stay visible during the transition.
+			// Without this, useAssociatedStyles enters "waiting-first-style" mode
+			// (opacity: 0) because it detects previous-screen evidence but never
+			// receives a resolved style for this tag.
+			[resolvedTag]: {
+				style: { opacity: 1 },
+			},
+		};
+	}
+
+	const unfocusedFade = props.active?.closing
+		? interpolate(progress, [1.6, 2], [1, 0], "clamp")
+		: interpolate(progress, [1, 1.5], [1, 0], "clamp");
+	const unfocusedScale = interpolateClamped(progress, [1, 2], [1, 0.95]);
+	const isUnfocusedIdle = props.active.settled === 1;
+
+	const elementTarget =
+		sharedOptions.scaleMode === "match"
+			? ("fullscreen" as const)
+			: getZoomContentTarget({
+					explicitTarget,
+					resolvedTag,
+					currentRouteKey,
+					previousRouteKey,
+					nextRouteKey,
+					entering,
+					screenLayout,
+					anchor: sharedOptions.anchor,
+				});
+
+	const elementRaw = computeRaw({
+		...sharedOptions,
+		method: "transform",
+		space: "relative",
+		target: elementTarget,
+	});
+
+	// Keep compensation tied to the element target's center. In `scaleMode: "match"`
+	// this target is fullscreen, so the center offset should resolve to zero.
+	const elementCenterY =
+		typeof elementTarget === "object"
+			? elementTarget.pageY + elementTarget.height / 2
+			: screenLayout.height / 2;
+
+	const scaleShiftY = computeCenterScaleShift({
+		center: elementCenterY,
+		containerCenter: screenLayout.height / 2,
+		scale: dragScale,
+	});
+
+	const compensatedGestureX = composeCompensatedTranslation({
+		gesture: dragX,
+		parentScale: unfocusedScale,
+		epsilon: EPSILON,
+	});
+	// dragY is measured in screen space and must be unscaled by the parent
+	// content shrink, while scaleShiftY is already in the parent's local space.
+	const compensatedGestureY = composeCompensatedTranslation({
+		gesture: dragY,
+		parentScale: unfocusedScale,
+		centerShift: scaleShiftY,
+		epsilon: EPSILON,
+	});
+	const elementTranslateX =
+		toNumber(elementRaw.translateX) + compensatedGestureX;
+	const elementTranslateY =
+		toNumber(elementRaw.translateY) + compensatedGestureY;
+	const elementScaleX = toNumber(elementRaw.scaleX, 1) * dragScale;
+	const elementScaleY = toNumber(elementRaw.scaleY, 1) * dragScale;
+
+	const resolvedElementStyle = isUnfocusedIdle
+		? {
+				transform: [
+					{ translateX: 0 },
+					{ translateY: 0 },
+					{ scaleX: 1 },
+					{ scaleY: 1 },
+				],
+				opacity: 0,
+				zIndex: 0,
+				elevation: 0,
+			}
+		: {
+				transform: [
+					{ translateX: elementTranslateX },
+					{ translateY: elementTranslateY },
+					{ scaleX: elementScaleX },
+					{ scaleY: elementScaleY },
+				],
+				opacity: unfocusedFade,
+				zIndex: 9999,
+				elevation: 9999,
+			};
+
+	return {
+		content: {
+			style: {
+				transform: [{ scale: unfocusedScale }],
+			},
+		},
+		[resolvedTag]: {
+			style: resolvedElementStyle,
+		},
+	};
+};

package/src/shared/utils/bounds/types/{builder.ts → options.ts}

@@ -64,25 +64,33 @@ type RawContentReturn = {
 };
 
 // Conditional return type based on options
-export type BoundsReturnType<T extends BoundsBuilderOptions> =
-	T["raw"] extends true
-		? T["method"] extends "size"
-			? T["space"] extends "absolute"
-				? RawSizeAbsoluteReturn
-				: RawSizeRelativeReturn
-			: T["method"] extends "content"
-				? RawContentReturn
-				: T["space"] extends "absolute"
-					? RawTransformAbsoluteReturn
-					: RawTransformRelativeReturn
-		: StyleProps;
-
-export type BoundsBuilderOptions = {
+export type BoundsOptionsResult<T extends BoundsOptions> = T["raw"] extends true
+	? T["method"] extends "size"
+		? T["space"] extends "absolute"
+			? RawSizeAbsoluteReturn
+			: RawSizeRelativeReturn
+		: T["method"] extends "content"
+			? RawContentReturn
+			: T["space"] extends "absolute"
+				? RawTransformAbsoluteReturn
+				: RawTransformRelativeReturn
+	: StyleProps;
+
+export type BoundsOptions = {
 	/**
-	 * The ID of the bound to compute bounds for. If not provided, uses the active bound ID.
+	 * The ID of the bound to compute bounds for.
+	 * When `group` is also provided, this is the member id within the group (not the combined tag).
 	 */
 	id: string;
 
+	/**
+	 * Optional group name for collection/list scenarios.
+	 * When provided, boundaries are tracked as a group and the active member id
+	 * is managed automatically. The internal tag becomes `group:id`.
+	 * Without this, `id` is used directly as the tag (backward compatible).
+	 */
+	group?: string;
+
 	/**
 	 * Whether the bound should target the screen or the bound.
 	 */
@@ -100,10 +108,10 @@ export type BoundsBuilderOptions = {
 	method?: BoundsMethod;
 
 	/**
-	 * The space to use to compute the bounds.
+	 * Coordinate space selection.
 	 *
-	 * - "relative": the bounds are computed with relative deltas, constrained by parent layout
-	 * - "absolute": the bounds are computed with absolute coordinates, unconstrained by parent layout
+	 * For `bounds({ ... })` element styles, space is normalized to `"relative"`.
+	 * `"absolute"` is reserved for internal navigation helpers (e.g. mask geometry).
 	 * @default "relative"
 	 */
 	space?: BoundsSpace;

package/src/shared/utils/create-provider.tsx

@@ -4,7 +4,6 @@
  * SUPER COOL AMAZING UTILITY
  */
 import {
-	type ComponentType,
 	createContext,
 	type ReactNode,
 	useContext,
@@ -90,32 +89,10 @@ export default function createProvider<
 			return context;
 		};
 
-		/**
-		 * HOC that wraps a component with the provider.
-		 * Uses the Provider component internally to ensure hooks are called correctly.
-		 */
-		const withProvider = (Component: ComponentType<ContextValue>) => {
-			// Consumer component that reads context and passes to wrapped component
-			const ContextConsumer = () => {
-				const contextValue = useEnhancedContext();
-				if (!contextValue) return null;
-				return <Component {...contextValue} />;
-			};
-
-			return function WithProviderWrapper(props: ProviderProps) {
-				return (
-					<Provider {...props}>
-						<ContextConsumer />
-					</Provider>
-				);
-			};
-		};
-
 		return {
 			[`${name}Context`]: Context,
 			[`${name}Provider`]: Provider,
 			[`use${name}Context`]: useEnhancedContext,
-			[`with${name}Provider`]: withProvider,
 		} as {
 			[P in ProviderName as `${P}Context`]: React.Context<ContextValue>;
 		} & {
@@ -124,10 +101,6 @@ export default function createProvider<
 			[P in ProviderName as `use${P}Context`]: () => Guarded extends true
 				? ContextValue
 				: ContextValue | null;
-		} & {
-			[P in ProviderName as `with${P}Provider`]: (
-				Component: ComponentType<ContextValue>,
-			) => React.FC<ProviderProps>;
 		};
 	};
 }

package/src/shared/utils/gesture/find-collapse-target.ts

@@ -1,4 +1,5 @@
 import { EPSILON } from "../../constants";
+import { sanitizeSnapPoints } from "./validate-snap-points";
 
 interface FindCollapseTargetResult {
 	target: number;
@@ -22,9 +23,7 @@ export function findCollapseTarget(
 ): FindCollapseTargetResult {
 	"worklet";
 
-	const normalized = snapPoints.filter((point) =>
-		canDismiss ? Number.isFinite(point) : Number.isFinite(point) && point > 0,
-	);
+	const normalized = sanitizeSnapPoints(snapPoints, canDismiss);
 
 	if (normalized.length === 0) {
 		return canDismiss

package/src/shared/utils/gesture/resolve-ownership.ts

@@ -10,7 +10,7 @@ import {
  * Minimal interface for ancestor context needed for ownership resolution.
  * This allows the function to be used without importing the full GestureContextType.
  */
-export interface AncestorClaimsContext {
+interface AncestorClaimsContext {
 	claimedDirections: ClaimedDirections;
 	ancestorContext: AncestorClaimsContext | null;
 }
@@ -72,39 +72,3 @@ function resolveDirectionOwnership(
 	// No one claims this direction
 	return "none";
 }
-
-/**
- * Finds the nearest ancestor (or self if isCurrentOwner) that claims any direction.
- * Used for setting up native gesture relationships.
- *
- * @param selfClaimsAny - Whether the current screen claims any direction
- * @param ancestorContext - The ancestor context chain
- * @returns The nearest context that claims a direction, or null
- */
-export function findNearestOwner(
-	selfClaimsAny: boolean,
-	ancestorContext: AncestorClaimsContext | null,
-): AncestorClaimsContext | null {
-	// If self claims any direction, self is the nearest owner
-	// (but we return null since this is used for finding ANCESTOR owners)
-	if (selfClaimsAny) {
-		return null;
-	}
-
-	// Walk ancestors looking for one that claims any direction
-	let ancestor = ancestorContext;
-	while (ancestor) {
-		const claims = ancestor.claimedDirections;
-		if (
-			claims?.vertical ||
-			claims?.["vertical-inverted"] ||
-			claims?.horizontal ||
-			claims?.["horizontal-inverted"]
-		) {
-			return ancestor;
-		}
-		ancestor = ancestor.ancestorContext;
-	}
-
-	return null;
-}

package/src/shared/utils/gesture/validate-snap-points.ts

@@ -1,4 +1,18 @@
-interface ValidateSnapPointsResult {
+/**
+ * Filters snap points to only valid, finite values.
+ * Excludes zero (dismiss) when canDismiss is false.
+ */
+export function sanitizeSnapPoints(
+	snapPoints: number[],
+	canDismiss: boolean,
+): number[] {
+	"worklet";
+	return snapPoints.filter((point) =>
+		canDismiss ? Number.isFinite(point) : Number.isFinite(point) && point > 0,
+	);
+}
+
+export interface EffectiveSnapPointsResult {
 	hasSnapPoints: boolean;
 	snapPoints: number[];
 	minSnapPoint: number;
@@ -13,7 +27,7 @@ interface ValidateSnapPointsOptions {
 export const validateSnapPoints = ({
 	snapPoints,
 	canDismiss,
-}: ValidateSnapPointsOptions): ValidateSnapPointsResult => {
+}: ValidateSnapPointsOptions): EffectiveSnapPointsResult => {
 	if (!snapPoints || snapPoints.length === 0) {
 		return {
 			hasSnapPoints: false,
@@ -23,9 +37,7 @@ export const validateSnapPoints = ({
 		};
 	}
 
-	const normalizedSnaps = snapPoints.filter((point) =>
-		canDismiss ? Number.isFinite(point) : Number.isFinite(point) && point > 0,
-	);
+	const normalizedSnaps = sanitizeSnapPoints(snapPoints, canDismiss ?? false);
 
 	if (normalizedSnaps.length === 0) {
 		return {

package/src/shared/utils/logger.ts

@@ -10,6 +10,3 @@ export const logger = {
 		console.warn(`[${LIBRARY_NAME}] ${message}`);
 	},
 };
-
-export const error = (message: string) =>
-	new Error(`[${LIBRARY_NAME}] ${message}`);

package/src/shared/utils/navigation/compose-descriptors.ts

@@ -1,6 +1,4 @@
-interface RouteWithKey {
-	key: string;
-}
+import type { RouteWithKey } from "../../types/stack.types";
 
 export const composeDescriptors = <
 	Route extends RouteWithKey,

package/src/shared/utils/navigation/resolve-scene-neighbors.ts

@@ -0,0 +1,89 @@
+interface SceneWithKey {
+	route: { key: string };
+	descriptor: unknown;
+}
+
+type IsRouteClosing = (routeKey: string) => boolean;
+
+/**
+ * Resolves previous/next descriptors while accounting for routes that are
+ * visually closing.
+ *
+ * Rules:
+ * - Closing scenes are isolated (no previous/next) so their transition does not
+ *   mix with newly pushed screens.
+ * - Non-closing scenes skip over closing neighbors to find the actual active
+ *   neighbor.
+ * - If there is no non-closing neighbor above/below, we fall back to the first
+ *   closing neighbor (needed for normal back transitions).
+ */
+export function resolveSceneNeighbors<T extends SceneWithKey>(
+	scenes: T[],
+	sceneIndex: number,
+	isRouteClosing: IsRouteClosing,
+): {
+	previousDescriptor: T["descriptor"] | undefined;
+	nextDescriptor: T["descriptor"] | undefined;
+} {
+	const current = scenes[sceneIndex];
+	if (!current) {
+		return {
+			previousDescriptor: undefined,
+			nextDescriptor: undefined,
+		};
+	}
+
+	if (isRouteClosing(current.route.key)) {
+		return {
+			previousDescriptor: undefined,
+			nextDescriptor: undefined,
+		};
+	}
+
+	let nextDescriptor: T["descriptor"] | undefined;
+	let firstClosingAbove: T["descriptor"] | undefined;
+
+	for (let i = sceneIndex + 1; i < scenes.length; i++) {
+		const candidate = scenes[i];
+		if (!candidate) continue;
+
+		if (!isRouteClosing(candidate.route.key)) {
+			nextDescriptor = candidate.descriptor;
+			break;
+		}
+
+		if (firstClosingAbove === undefined) {
+			firstClosingAbove = candidate.descriptor;
+		}
+	}
+
+	if (nextDescriptor === undefined) {
+		nextDescriptor = firstClosingAbove;
+	}
+
+	let previousDescriptor: T["descriptor"] | undefined;
+	let firstClosingBelow: T["descriptor"] | undefined;
+
+	for (let i = sceneIndex - 1; i >= 0; i--) {
+		const candidate = scenes[i];
+		if (!candidate) continue;
+
+		if (!isRouteClosing(candidate.route.key)) {
+			previousDescriptor = candidate.descriptor;
+			break;
+		}
+
+		if (firstClosingBelow === undefined) {
+			firstClosingBelow = candidate.descriptor;
+		}
+	}
+
+	if (previousDescriptor === undefined) {
+		previousDescriptor = firstClosingBelow;
+	}
+
+	return {
+		previousDescriptor,
+		nextDescriptor,
+	};
+}

package/src/shared/utils/navigation/sync-routes-with-removed.ts

@@ -1,10 +1,7 @@
 import type { useClosingRouteKeys } from "../../hooks/navigation/use-closing-route-keys";
+import type { RouteWithKey } from "../../types/stack.types";
 import { composeDescriptors } from "./compose-descriptors";
 
-interface RouteWithKey {
-	key: string;
-}
-
 type SyncRoutesWithRemovedParams<
 	Route extends RouteWithKey,
 	DescriptorMap extends Record<string, unknown>,