react-native-screen-transitions 3.6.0-alpha.0 → 3.6.0-alpha.2

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

@@ -1,13 +1,16 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
 import type { BoundsMethod } from "../../types/bounds.types";
+import type { ScreenKey } from "../../types/screen.types";
 import type {
 	BoundsAnchor,
 	BoundsScaleMode,
 } from "../../utils/bounds/types/options";
 
 export type TagID = string;
-export type ScreenKey = string;
-export type NavigatorKey = string;
+export type LinkKey = string;
+export type GroupKey = string;
+export type ScreenPairKey = string;
+export type { ScreenKey } from "../../types/screen.types";
 
 export type BoundaryConfig = {
 	anchor?: BoundsAnchor;
@@ -20,9 +23,6 @@ export type Entry = {
 	bounds: MeasuredDimensions | null;
 	styles: StyleProps;
 	boundaryConfig?: BoundaryConfig;
-	ancestorKeys?: ScreenKey[];
-	navigatorKey?: NavigatorKey;
-	ancestorNavigatorKeys?: NavigatorKey[];
 };
 
 export type MeasuredEntry = Entry & {
@@ -33,19 +33,14 @@ export type EntryPatch = {
 	bounds?: MeasuredDimensions | null;
 	styles?: StyleProps | null;
 	boundaryConfig?: BoundaryConfig | null;
-	ancestorKeys?: ScreenKey[] | null;
-	navigatorKey?: NavigatorKey | null;
-	ancestorNavigatorKeys?: NavigatorKey[] | null;
 };
 
 export type ScreenIdentifier = {
 	screenKey: ScreenKey;
-	ancestorKeys?: ScreenKey[];
-	navigatorKey?: NavigatorKey;
-	ancestorNavigatorKeys?: NavigatorKey[];
 };
 
 export type TagLink = {
+	group?: GroupKey;
 	source: ScreenIdentifier & MeasuredEntry;
 	/** Destination side once attached; null while the source is still pending. */
 	destination: (ScreenIdentifier & MeasuredEntry) | null;
@@ -73,14 +68,20 @@ export type ResolvedTransitionPair = {
 
 export type ScreenEntry = Entry;
 
-export type TagState = {
+export type BoundaryState = {
 	screens: Record<ScreenKey, ScreenEntry>;
-	linkStack: TagLink[];
 };
 
-export type GroupState = {
-	/** Latest requested group member id from mounted grouped bounds. */
-	activeId: string;
-	/** Group member id that started the current linked transition. */
-	initialId?: string;
+export type LinkGroupState = {
+	activeId: LinkKey;
+	initialId?: LinkKey;
 };
+
+export type LinkPairState = {
+	links: Record<LinkKey, TagLink>;
+	groups: Record<GroupKey, LinkGroupState>;
+};
+
+export type LinkPairsState = Record<ScreenPairKey, LinkPairState>;
+
+export type TagState = BoundaryState;

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

@@ -23,6 +23,7 @@ export type GestureStoreMap = {
 	y: SharedValue<number>;
 	normX: SharedValue<number>;
 	normY: SharedValue<number>;
+	velocity: SharedValue<number>;
 	scale: SharedValue<number>;
 	normScale: SharedValue<number>;
 	focalX: SharedValue<number>;
@@ -68,6 +69,7 @@ function createGestureBag(): GestureStoreMap {
 		y: makeMutable(0),
 		normX,
 		normY,
+		velocity: makeMutable(0),
 		scale,
 		normScale,
 		focalX: makeMutable(0),
@@ -108,6 +110,7 @@ export const GestureStore = createStore<GestureStoreMap>({
 		cancelAnimation(bag.y);
 		cancelAnimation(bag.normX);
 		cancelAnimation(bag.normY);
+		cancelAnimation(bag.velocity);
 		cancelAnimation(bag.scale);
 		cancelAnimation(bag.normScale);
 		cancelAnimation(bag.focalX);

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

@@ -3,6 +3,7 @@ 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";
 
@@ -36,6 +37,11 @@ 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.
@@ -72,6 +78,7 @@ export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 			LifecycleTransitionRequestKind.None,
 		),
 		pendingLifecycleRequestTarget: makeMutable<number>(0),
+		logicalSettleFrameCount: makeMutable(LOGICAL_SETTLE_REQUIRED_FRAMES),
 		pendingLifecycleStartBlockCount: makeMutable<number>(0),
 	}),
 	disposeBag: (bag) => {
@@ -80,6 +87,7 @@ 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

@@ -31,6 +31,7 @@ export type ScreenTransitionOptions = Pick<
 	| "gestureSnapVelocityImpact"
 	| "gestureReleaseVelocityScale"
 	| "gestureResponseDistance"
+	| "gestureProgressMode"
 	| "gestureDrivesProgress"
 	| "gestureActivationArea"
 	| "gestureSnapLocked"
@@ -162,6 +163,18 @@ export type ScreenTransitionState = {
 	snapIndex: number;
 };
 
+export type ScreenTransitionDepthTarget = {
+	/**
+	 * Relative transition depth.
+	 *
+	 * `0` resolves the current transition, negative values resolve ancestors, and
+	 * positive values resolve descendants.
+	 */
+	depth: number;
+};
+
+export type ScreenTransitionTarget = ScreenTransitionDepthTarget;
+
 export interface ScreenInterpolationProps {
 	/**
 	 * Values for the screen that came before the current one in the navigation stack.
@@ -278,11 +291,6 @@ export type TransitionSlotStyle = AnimatedViewStyle | TransitionSlotDefinition;
  */
 export type TransitionInterpolatorOptions = ScreenTransitionOptions;
 
-/**
- * @deprecated Use `TransitionInterpolatorOptions`.
- */
-export type TransitionInterpolatorConfig = TransitionInterpolatorOptions;
-
 /**
  * Internal normalized slot format.
  * Always uses the explicit `{ style, props }` shape (with Reanimated's full StyleProps).

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

@@ -212,4 +212,7 @@ export type BoundsAccessor = {
 	) => number;
 };
 
-export type BoundsInterpolationProps = Omit<ScreenInterpolationProps, "bounds">;
+export type BoundsInterpolationProps = Omit<
+	ScreenInterpolationProps,
+	"bounds" | "transition"
+>;

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

@@ -16,6 +16,8 @@ export type GestureDirection = PanGestureDirection | PinchGestureDirection;
 
 export type ActiveGesture = ResolvedPanGestureDirection | PinchGestureDirection;
 
+export type GestureProgressMode = "progress-driven" | "freeform";
+
 export type SnapPanAxis = "horizontal" | "vertical";
 
 export type ScrollGestureAxis = "vertical" | "horizontal";
@@ -64,8 +66,6 @@ export enum GestureActivationState {
 	FAILED,
 }
 
-export { GestureActivationState as GestureOffsetState };
-
 export type GestureActivationArea = ActivationArea | SideActivation;
 
 /**
@@ -105,6 +105,14 @@ export type GestureValues = {
 	 * The live normalized vertical translation of the gesture (-1 to 1).
 	 */
 	normY: number;
+	/**
+	 * A 0-1 scalar derived from the pan velocity magnitude, normalized against
+	 * a screen-relative full-flick threshold.
+	 *
+	 * This is live while dragging, frozen at release during dismiss animations,
+	 * and reset to 0 while idle or settling from a cancelled gesture.
+	 */
+	velocity: number;
 	/**
 	 * The live pinch scale after `gestureSensitivity` is applied.
 	 */

package/src/shared/types/index.ts

@@ -7,7 +7,6 @@ export type {
 	ScreenTransitionOptions,
 	ScreenTransitionState,
 	TransitionInterpolatedStyle,
-	TransitionInterpolatorConfig,
 	TransitionInterpolatorOptions,
 	TransitionSlotStyle,
 	TransitionSpec,

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

@@ -3,7 +3,11 @@ import type {
 	ScreenStyleInterpolator,
 	TransitionSpec,
 } from "./animation.types";
-import type { GestureActivationArea, GestureDirection } from "./gesture.types";
+import type {
+	GestureActivationArea,
+	GestureDirection,
+	GestureProgressMode,
+} from "./gesture.types";
 import type { OverlayProps } from "./overlay.types";
 
 export type Layout = {
@@ -219,8 +223,16 @@ export type ScreenTransitionConfig = {
 	 */
 	gestureResponseDistance?: number;
 
+	/**
+	 * Controls whether live gesture displacement drives transition progress or
+	 * stays available as freeform gesture values for custom interpolators.
+	 */
+	gestureProgressMode?: GestureProgressMode;
+
 	/**
 	 * Whether the gesture drives the progress.
+	 *
+	 * @deprecated Use `gestureProgressMode` instead.
 	 */
 	gestureDrivesProgress?: boolean;
 

package/src/shared/utils/animation/animate-to-progress.ts

@@ -22,6 +22,24 @@ interface AnimateToProgressProps {
 	initialVelocity?: number;
 }
 
+const setTransitionLifecycleFlags = (
+	animations: AnimationStoreMap,
+	isClosing: boolean,
+	markEntering: boolean,
+) => {
+	"worklet";
+
+	if (isClosing) {
+		animations.closing.set(TRUE);
+		animations.entering.set(FALSE);
+		return;
+	}
+
+	if (markEntering) {
+		animations.entering.set(TRUE);
+	}
+};
+
 export const animateToProgress = ({
 	target,
 	spec,
@@ -50,7 +68,7 @@ export const animateToProgress = ({
 			? { ...config, velocity: initialVelocity }
 			: config;
 
-	const { progress, willAnimate, animating, closing, entering } = animations;
+	const { progress, willAnimate, progressAnimating, entering } = animations;
 
 	const startAnimation = () => {
 		"worklet";
@@ -59,15 +77,10 @@ export const animateToProgress = ({
 		const shouldClearEnteringOnFinish =
 			!isClosing && (markEntering || entering.get());
 
-		if (isClosing) {
-			closing.set(TRUE);
-			entering.set(FALSE);
-		} else if (markEntering) {
-			entering.set(TRUE);
-		}
+		setTransitionLifecycleFlags(animations, isClosing, markEntering);
 
 		if (!config) {
-			animating.set(FALSE);
+			progressAnimating.set(FALSE);
 			progress.set(value);
 			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
@@ -79,7 +92,7 @@ export const animateToProgress = ({
 			return;
 		}
 
-		animating.set(TRUE); //<-- Do not move this into the callback
+		progressAnimating.set(TRUE); //<-- Do not move this into the callback
 		progress.set(
 			animate(value, effectiveConfig, (finished) => {
 				"worklet";
@@ -93,21 +106,16 @@ export const animateToProgress = ({
 					runOnJS(onAnimationFinish)(finished);
 				}
 
-				// Delay setting animating=FALSE by one frame to ensure final frame is painted
+				// Delay clearing progress animation by one frame to ensure final frame is painted
 				requestAnimationFrame(() => {
-					animating.set(FALSE);
+					progressAnimating.set(FALSE);
 				});
 			}),
 		);
 	};
 
 	if (emitWillAnimate) {
-		if (isClosing) {
-			closing.set(TRUE);
-			entering.set(FALSE);
-		} else if (markEntering) {
-			entering.set(TRUE);
-		}
+		setTransitionLifecycleFlags(animations, isClosing, markEntering);
 
 		willAnimate.set(TRUE);
 		requestAnimationFrame(() => {

package/src/shared/utils/bounds/helpers/create-bounds-accessor-core.ts

@@ -54,9 +54,11 @@ const createBoundsAccessorParts = ({
 			id: options.id,
 			group: options.group,
 		});
+
 		const computed = prepareBoundStyles({
 			props,
 			options,
+			syncGroupActiveId: true,
 		});
 		const scopedTag = tag ?? "";
 		const target = Object.isExtensible(computed) ? computed : { ...computed };

package/src/shared/utils/bounds/helpers/create-interpolators.ts

@@ -5,13 +5,13 @@ import {
 } from "react-native-reanimated";
 import { ENTER_RANGE, EXIT_RANGE } from "../../../constants";
 import { getEntry } from "../../../stores/bounds/internals/entries";
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
+import type { BoundsInterpolationProps } from "../../../types/bounds.types";
 import type { BoundId } from "../types/options";
 import type { LinkAccessor } from "./create-link-accessor";
 import { interpolateLinkStyle } from "./styles/interpolate-link-style";
 
 type InterpolatorParams = {
-	getProps: () => Omit<ScreenInterpolationProps, "bounds">;
+	getProps: () => BoundsInterpolationProps;
 	getLink: LinkAccessor["getLink"];
 };
 

package/src/shared/utils/bounds/helpers/create-link-accessor.ts

@@ -1,19 +1,20 @@
 import { getEntry } from "../../../stores/bounds/internals/entries";
-import { resolveGroupLink } from "../../../stores/bounds/internals/groups";
+import { getResolvedLink } from "../../../stores/bounds/internals/links";
 import type {
 	MeasuredEntry,
 	ResolvedTransitionPair,
 	TagLink,
 } from "../../../stores/bounds/types";
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
 import type {
+	BoundsInterpolationProps,
 	BoundsLink,
 	BoundsLinkComputeOptions,
 } from "../../../types/bounds.types";
 import type { BoundId, BoundsOptionsResult } from "../types/options";
 import { prepareBoundStyles } from "./prepare-bound-styles";
+import { resolveBoundsPairKey } from "./resolve-bounds-pair-key";
 
-type GetProps = () => Omit<ScreenInterpolationProps, "bounds">;
+type GetProps = () => BoundsInterpolationProps;
 
 export type LinkAccessor = {
 	getMeasured: (tag: BoundId, key?: string) => MeasuredEntry | null;
@@ -52,11 +53,10 @@ export const createLinkAccessor = (getProps: GetProps): LinkAccessor => {
 		"worklet";
 		const props = getProps();
 		const stringTag = String(tag);
-		const screenKey = props.current?.route.key;
-		const resolved = resolveGroupLink({
-			tag: stringTag,
-			screenKey,
-		});
+		const pairKey = resolveBoundsPairKey(props);
+		const resolved = pairKey
+			? getResolvedLink(pairKey, stringTag)
+			: { tag: stringTag, link: null };
 		const selectedTag = resolved.tag;
 		const link = resolved.link;
 

package/src/shared/utils/bounds/helpers/prepare-bound-styles.ts

@@ -1,10 +1,7 @@
 import { getEntry } from "../../../stores/bounds/internals/entries";
-import {
-	getGroupActiveId,
-	setGroupActiveId,
-} from "../../../stores/bounds/internals/groups";
+import { setActiveGroupId } from "../../../stores/bounds/internals/links";
 import type { ResolvedTransitionPair } from "../../../stores/bounds/types";
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
+import type { BoundsInterpolationProps } from "../../../types/bounds.types";
 import { DEFAULT_BOUNDS_OPTIONS } from "../constants";
 import type {
 	BoundId,
@@ -12,9 +9,10 @@ import type {
 	BoundsOptionsResult,
 } from "../types/options";
 import { createBoundTag } from "./create-bound-tag";
+import { resolveBoundsPairKey } from "./resolve-bounds-pair-key";
 import { computeBoundStyles } from "./styles/compute";
 
-type BaseInterpolatorProps = Omit<ScreenInterpolationProps, "bounds">;
+type BaseInterpolatorProps = BoundsInterpolationProps;
 
 type ComputeResolvedBoundsStylesParams<T extends BoundsOptions> = {
 	props: BaseInterpolatorProps;
@@ -24,7 +22,7 @@ type ComputeResolvedBoundsStylesParams<T extends BoundsOptions> = {
 };
 
 type BuildBoundsOptionsParams = {
-	props: Omit<ScreenInterpolationProps, "bounds">;
+	props: BoundsInterpolationProps;
 	id?: BoundId;
 	group?: string;
 	overrides?: Partial<BoundsOptions>;
@@ -57,25 +55,36 @@ const buildBoundsOptions = ({
 	return resolved;
 };
 
-const syncGroupActiveMember = (group?: string, id?: BoundId) => {
+const syncActiveGroupId = (params: {
+	props: BoundsInterpolationProps;
+	id?: BoundId;
+	group?: string;
+}) => {
 	"worklet";
-	if (!group || id == null || id === "") return;
-
-	const normalizedId = String(id);
+	const { props, id, group } = params;
+	if (id == null || id === "" || !group) return;
 
-	if (getGroupActiveId(group) === normalizedId) return;
+	const pairKey = resolveBoundsPairKey(props);
+	if (!pairKey) return;
 
-	setGroupActiveId(group, normalizedId);
+	setActiveGroupId(pairKey, group, String(id));
 };
 
 export const prepareBoundStyles = <T extends BoundsOptions>({
 	props,
 	options,
 	resolvedPair,
+	syncGroupActiveId = false,
 }: ComputeResolvedBoundsStylesParams<T>): BoundsOptionsResult<T> => {
 	"worklet";
 
-	syncGroupActiveMember(options.group, options.id);
+	if (syncGroupActiveId) {
+		syncActiveGroupId({
+			props,
+			id: options.id,
+			group: options.group,
+		});
+	}
 
 	const resolved = buildBoundsOptions({
 		props,

package/src/shared/utils/bounds/helpers/resolve-bounds-pair-key.ts

@@ -0,0 +1,22 @@
+import { createScreenPairKey } from "../../../stores/bounds/helpers/link-pairs.helpers";
+import type { ScreenPairKey } from "../../../stores/bounds/types";
+import type { BoundsInterpolationProps } from "../../../types/bounds.types";
+
+export const resolveBoundsPairKey = (
+	props: BoundsInterpolationProps,
+): ScreenPairKey | null => {
+	"worklet";
+	const currentScreenKey = props.current?.route.key;
+	const previousScreenKey = props.previous?.route.key;
+	const nextScreenKey = props.next?.route.key;
+
+	if (nextScreenKey && currentScreenKey) {
+		return createScreenPairKey(currentScreenKey, nextScreenKey);
+	}
+
+	if (previousScreenKey && currentScreenKey) {
+		return createScreenPairKey(previousScreenKey, currentScreenKey);
+	}
+
+	return null;
+};

package/src/shared/utils/bounds/navigation/math.ts

@@ -1,23 +1,7 @@
-import { interpolate } from "react-native-reanimated";
+import { clamp, interpolate } from "react-native-reanimated";
 
 type CombinedScaleMode = "multiply" | "average" | "max" | "min";
 
-const clamp = (value: number, min: number, max: number): number => {
-	"worklet";
-	const lower = min < max ? min : max;
-	const upper = max > min ? max : min;
-
-	if (value < lower) return lower;
-	if (value > upper) return upper;
-
-	return value;
-};
-
-const clamp01 = (value: number): number => {
-	"worklet";
-	return clamp(value, 0, 1);
-};
-
 const lerp = (from: number, to: number, t: number): number => {
 	"worklet";
 	return from + (to - from) * t;
@@ -46,7 +30,7 @@ const mapRangeClamped = (
 	outMax: number,
 ): number => {
 	"worklet";
-	const t = clamp01(inverseLerp(value, inMin, inMax));
+	const t = clamp(inverseLerp(value, inMin, inMax), 0, 1);
 	return lerp(outMin, outMax, t);
 };