react-native-screen-transitions 3.4.0 → 3.5.0

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

@@ -16,9 +16,26 @@ export type BoundaryConfig = {
 	method?: BoundsMethod;
 };
 
-export type Snapshot = {
-	bounds: MeasuredDimensions;
+export type Entry = {
+	bounds: MeasuredDimensions | null;
 	styles: StyleProps;
+	boundaryConfig?: BoundaryConfig;
+	ancestorKeys?: ScreenKey[];
+	navigatorKey?: NavigatorKey;
+	ancestorNavigatorKeys?: NavigatorKey[];
+};
+
+export type MeasuredEntry = Entry & {
+	bounds: MeasuredDimensions;
+};
+
+export type EntryPatch = {
+	bounds?: MeasuredDimensions | null;
+	styles?: StyleProps | null;
+	boundaryConfig?: BoundaryConfig | null;
+	ancestorKeys?: ScreenKey[] | null;
+	navigatorKey?: NavigatorKey | null;
+	ancestorNavigatorKeys?: NavigatorKey[] | null;
 };
 
 export type ScreenIdentifier = {
@@ -29,8 +46,8 @@ export type ScreenIdentifier = {
 };
 
 export type TagLink = {
-	source: ScreenIdentifier & Snapshot;
-	destination: (ScreenIdentifier & Snapshot) | null;
+	source: ScreenIdentifier & MeasuredEntry;
+	destination: (ScreenIdentifier & MeasuredEntry) | null;
 };
 
 export type ResolveTransitionContext = {
@@ -47,30 +64,15 @@ export type ResolvedTransitionPair = {
 	destinationStyles: StyleProps | null;
 	sourceScreenKey: ScreenKey | null;
 	destinationScreenKey: ScreenKey | null;
-	usedPending: boolean;
 };
 
-export type SnapshotEntry = Snapshot & {
-	ancestorKeys?: ScreenKey[];
-	navigatorKey?: NavigatorKey;
-	ancestorNavigatorKeys?: NavigatorKey[];
-};
+export type ScreenEntry = Entry;
 
 export type TagState = {
-	snapshots: Record<ScreenKey, SnapshotEntry>;
+	screens: Record<ScreenKey, ScreenEntry>;
 	linkStack: TagLink[];
 };
 
-export type PresenceEntry = {
-	count: number;
-	ancestorKeys?: ScreenKey[];
-	navigatorKey?: NavigatorKey;
-	ancestorNavigatorKeys?: NavigatorKey[];
-	boundaryConfig?: BoundaryConfig;
-};
-
-export type PresenceState = Record<TagID, Record<ScreenKey, PresenceEntry>>;
-
 export type GroupState = {
 	activeId: string;
 };

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

@@ -6,7 +6,14 @@ import {
 import type { Layout } from "../types/screen.types";
 import { createStore } from "../utils/create-store";
 
-export type SystemStoreMap = {
+export enum LifecycleTransitionRequestKind {
+	None = 0,
+	Open = 1,
+	ManagedClose = 2,
+	NativeClose = 3,
+}
+
+type SystemStoreState = {
 	targetProgress: SharedValue<number>;
 
 	/**
@@ -18,27 +25,88 @@ export type SystemStoreMap = {
 	 * Intrinsic measured content layout from the screen container wrapper.
 	 */
 	measuredContentLayout: SharedValue<Layout | null>;
+
+	/**
+	 * The currently pending lifecycle transition request.
+	 */
+	pendingLifecycleRequestKind: SharedValue<LifecycleTransitionRequestKind>;
+
+	/**
+	 * Progress target for the pending lifecycle transition request.
+	 */
+	pendingLifecycleRequestTarget: SharedValue<number>;
+
+	/**
+	 * Number of active blockers preventing a pending lifecycle request from
+	 * starting immediately.
+	 */
+	pendingLifecycleStartBlockCount: SharedValue<number>;
 };
 
-function createSystemBag(): SystemStoreMap {
-	return {
-		targetProgress: makeMutable(1),
-		resolvedAutoSnapPoint: makeMutable(-1),
-		measuredContentLayout: makeMutable<Layout | null>(null),
-	};
+export interface SystemStoreActions {
+	requestLifecycleTransition(
+		kind: LifecycleTransitionRequestKind,
+		target: number,
+	): void;
+	clearLifecycleTransitionRequest(): void;
+	blockLifecycleStart(): void;
+	unblockLifecycleStart(): void;
 }
 
+export type SystemStoreMap = SystemStoreState & {
+	actions: SystemStoreActions;
+};
+
 /**
  * Route-keyed internal engine state that should not be treated as public screen
  * animation data. These values support runtime measurement and orchestration,
  * such as resolved auto snap points, measured content layout, and the current
  * animation target progress. This could possibly grow in the future.
  */
-export const SystemStore = createStore<SystemStoreMap>({
-	createBag: createSystemBag,
+export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
+	createBag: () => ({
+		targetProgress: makeMutable(1),
+		resolvedAutoSnapPoint: makeMutable(-1),
+		measuredContentLayout: makeMutable<Layout | null>(null),
+		pendingLifecycleRequestKind: makeMutable<LifecycleTransitionRequestKind>(
+			LifecycleTransitionRequestKind.None,
+		),
+		pendingLifecycleRequestTarget: makeMutable<number>(0),
+		pendingLifecycleStartBlockCount: makeMutable<number>(0),
+	}),
 	disposeBag: (bag) => {
 		cancelAnimation(bag.targetProgress);
 		cancelAnimation(bag.resolvedAutoSnapPoint);
 		cancelAnimation(bag.measuredContentLayout);
+		cancelAnimation(bag.pendingLifecycleRequestKind);
+		cancelAnimation(bag.pendingLifecycleRequestTarget);
+		cancelAnimation(bag.pendingLifecycleStartBlockCount);
 	},
+	actions: (bag) => ({
+		requestLifecycleTransition(kind, target) {
+			"worklet";
+			bag.pendingLifecycleRequestTarget.set(target);
+			bag.pendingLifecycleRequestKind.set(kind);
+		},
+
+		clearLifecycleTransitionRequest() {
+			"worklet";
+			bag.pendingLifecycleRequestKind.set(LifecycleTransitionRequestKind.None);
+			bag.pendingLifecycleRequestTarget.set(0);
+		},
+
+		blockLifecycleStart() {
+			"worklet";
+			bag.pendingLifecycleStartBlockCount.set(
+				bag.pendingLifecycleStartBlockCount.get() + 1,
+			);
+		},
+
+		unblockLifecycleStart() {
+			"worklet";
+			bag.pendingLifecycleStartBlockCount.set(
+				Math.max(0, bag.pendingLifecycleStartBlockCount.get() - 1),
+			);
+		},
+	}),
 });

package/src/shared/types/animation.types.ts

@@ -11,7 +11,7 @@ import {
 } from "../constants";
 import type { BoundsAccessor } from "./bounds.types";
 import type { GestureValues } from "./gesture.types";
-import type { Layout } from "./screen.types";
+import type { ScreenLayouts } from "./screen.types";
 import type { BaseStackRoute } from "./stack.types";
 
 export type ScreenTransitionState = {
@@ -107,19 +107,7 @@ export type ScreenTransitionState = {
 	/**
 	 * Layout measurements for this specific screen.
 	 */
-	layouts: {
-		/**
-		 * The `width` and `height` of the screen container.
-		 */
-		screen: Layout;
-		/**
-		 * The intrinsic measured content wrapper layout when available.
-		 *
-		 * This is currently populated for the measured screen-container path used by
-		 * auto snap-point sizing. It is undefined until a real measurement exists.
-		 */
-		content?: Layout;
-	};
+	layouts: ScreenLayouts;
 
 	/**
 	 * Animated index of this screen's current snap point.
@@ -154,17 +142,9 @@ export interface ScreenInterpolationProps {
 	 * @deprecated Use `current.layouts` instead.
 	 */
 	layouts: {
-		/**
-		 * The `width` and `height` of the screen container.
-		 */
-		screen: Layout;
-		/**
-		 * The intrinsic measured content wrapper layout when available.
-		 *
-		 * This is currently populated for the measured screen-container path used by
-		 * auto snap-point sizing. It is undefined until a real measurement exists.
-		 */
-		content?: Layout;
+		screen: ScreenLayouts["screen"];
+		content?: ScreenLayouts["content"];
+		navigationMaskEnabled: ScreenLayouts["navigationMaskEnabled"];
 	};
 
 	/**

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

@@ -3,7 +3,7 @@ import {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
 } from "../constants";
-import type { Snapshot } from "../stores/bounds";
+import type { MeasuredEntry } from "../stores/bounds";
 import type {
 	BoundId,
 	BoundsOptions,
@@ -166,7 +166,11 @@ type BoundsCallResult<T extends BoundsOptions> = BoundsOptionsResult<T> &
 
 export type BoundsAccessor = {
 	<T extends BoundsOptions>(options: T): BoundsCallResult<T>;
-	getSnapshot: (id: BoundId, key?: string) => Snapshot | null;
+	getMeasured: (id: BoundId, key?: string) => MeasuredEntry | null;
+	/**
+	 * @deprecated Use `getMeasured` instead. `getSnapshot` will be removed in the next major version.
+	 */
+	getSnapshot: (id: BoundId, key?: string) => MeasuredEntry | null;
 	getLink: (id: BoundId) => BoundsLink | null;
 	interpolateStyle: (
 		id: BoundId,
@@ -181,9 +185,4 @@ export type BoundsAccessor = {
 	) => number;
 };
 
-export type BoundsInterpolationProps = Omit<
-	ScreenInterpolationProps,
-	"bounds"
-> & {
-	navigationMaskEnabled?: boolean;
-};
+export type BoundsInterpolationProps = Omit<ScreenInterpolationProps, "bounds">;

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

@@ -11,6 +11,27 @@ export type Layout = {
 	height: number;
 };
 
+export type ScreenLayouts = {
+	/**
+	 * The `width` and `height` of the screen container.
+	 */
+	screen: Layout;
+	/**
+	 * The intrinsic measured content wrapper layout when available.
+	 *
+	 * This is currently populated for the measured screen-container path used by
+	 * auto snap-point sizing. It is undefined until a real measurement exists.
+	 */
+	content?: Layout;
+	/**
+	 * Whether navigation bounds masking is enabled for this screen.
+	 *
+	 * When enabled, navigation zoom helpers target the masked container path
+	 * instead of the plain content slot.
+	 */
+	navigationMaskEnabled: boolean;
+};
+
 export type ScreenKey = string;
 export type SheetScrollGestureBehavior =
 	| "expand-and-collapse"

package/src/shared/utils/bounds/helpers/create-bound-tag.ts

@@ -1,14 +1,18 @@
 import type { BoundId } from "../types/options";
 
-export type ResolveBoundTagParams = {
+export type CreateBoundTagParams = {
 	id?: BoundId;
 	group?: string;
 };
 
+/**
+ * Creates a bound tag by formatting the given id and optional group
+ * into a `group:id` string. If no group is provided, returns just the id.
+ */
 export const createBoundTag = ({
 	id,
 	group,
-}: ResolveBoundTagParams): string | undefined => {
+}: CreateBoundTagParams): string | undefined => {
 	"worklet";
 
 	if (id == null || id === "") return undefined;

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

@@ -35,7 +35,7 @@ export const createInterpolators = ({
 		});
 	};
 
-	const interpolateBoundsFromSnapshot = (
+	const interpolateBoundsFromMeasuredEntry = (
 		tag: BoundId,
 		property: keyof MeasuredDimensions,
 		targetKey: string,
@@ -50,13 +50,16 @@ export const createInterpolators = ({
 		const fb = fallback ?? 0;
 		const normalizedTag = String(tag);
 
-		const currentSnapshot = currentKey
-			? BoundStore.getSnapshot(normalizedTag, currentKey)
+		const currentMeasuredEntry = currentKey
+			? BoundStore.entry.getMeasured(normalizedTag, currentKey)
 			: null;
-		const targetSnapshot = BoundStore.getSnapshot(normalizedTag, targetKey);
+		const targetMeasuredEntry = BoundStore.entry.getMeasured(
+			normalizedTag,
+			targetKey,
+		);
 
-		const currentValue = currentSnapshot?.bounds?.[property] ?? fb;
-		const targetValue = targetSnapshot?.bounds?.[property] ?? fb;
+		const currentValue = currentMeasuredEntry?.bounds?.[property] ?? fb;
+		const targetValue = targetMeasuredEntry?.bounds?.[property] ?? fb;
 
 		return interpolate(
 			props.progress,
@@ -99,7 +102,7 @@ export const createInterpolators = ({
 		"worklet";
 
 		if (typeof fallbackOrTargetKey === "string") {
-			return interpolateBoundsFromSnapshot(
+			return interpolateBoundsFromMeasuredEntry(
 				tag,
 				property,
 				fallbackOrTargetKey,

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

@@ -1,4 +1,4 @@
-import { BoundStore, type Snapshot } from "../../../stores/bounds";
+import { BoundStore, type MeasuredEntry } from "../../../stores/bounds";
 import type { ScreenInterpolationProps } from "../../../types/animation.types";
 import type { BoundsLink } from "../../../types/bounds.types";
 import type { BoundId } from "../types/options";
@@ -6,23 +6,29 @@ import type { BoundId } from "../types/options";
 type GetProps = () => Omit<ScreenInterpolationProps, "bounds">;
 
 export type LinkAccessor = {
-	getSnapshot: (tag: BoundId, key?: string) => Snapshot | null;
+	getMeasured: (tag: BoundId, key?: string) => MeasuredEntry | null;
+	getSnapshot: (tag: BoundId, key?: string) => MeasuredEntry | null;
 	getLink: (tag: BoundId) => BoundsLink | null;
 };
 
 export const createLinkAccessor = (getProps: GetProps): LinkAccessor => {
 	"worklet";
 
-	const getSnapshot = (tag: BoundId, key?: string): Snapshot | null => {
+	const getMeasured = (tag: BoundId, key?: string): MeasuredEntry | null => {
 		"worklet";
 		if (!key) return null;
-		return BoundStore.getSnapshot(String(tag), key);
+		return BoundStore.entry.getMeasured(String(tag), key);
+	};
+
+	const getSnapshot = (tag: BoundId, key?: string): MeasuredEntry | null => {
+		"worklet";
+		return getMeasured(tag, key);
 	};
 
 	const getLink = (tag: BoundId): BoundsLink | null => {
 		"worklet";
 		const props = getProps();
-		const link = BoundStore.getActiveLink(
+		const link = BoundStore.link.getActive(
 			String(tag),
 			props.current?.route.key,
 		);
@@ -38,6 +44,7 @@ export const createLinkAccessor = (getProps: GetProps): LinkAccessor => {
 	};
 
 	return {
+		getMeasured,
 		getSnapshot,
 		getLink,
 	};

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

@@ -41,7 +41,7 @@ export const buildBoundsOptions = ({
 
 	const boundaryConfig =
 		tag && currentScreenKey
-			? BoundStore.getBoundaryConfig(tag, currentScreenKey)
+			? BoundStore.entry.getConfig(tag, currentScreenKey)
 			: null;
 
 	const resolved = {
@@ -61,22 +61,19 @@ const syncGroupActiveMember = (group?: string, id?: BoundId) => {
 
 	const normalizedId = String(id);
 
-	if (BoundStore.getGroupActiveId(group) === normalizedId) return;
+	if (BoundStore.group.getActiveId(group) === normalizedId) return;
 
-	BoundStore.setGroupActiveId(group, normalizedId);
+	BoundStore.group.setActiveId(group, normalizedId);
 };
 
 export const prepareBoundStyles = <T extends BoundsOptions>({
 	props,
 	options,
 	resolvedPair,
-	syncGroupActiveId = true,
 }: ComputeResolvedBoundsStylesParams<T>): BoundsOptionsResult<T> => {
 	"worklet";
 
-	if (syncGroupActiveId) {
-		syncGroupActiveMember(options.group, options.id);
-	}
+	syncGroupActiveMember(options.group, options.id);
 
 	const resolved = buildBoundsOptions({
 		props,

package/src/shared/utils/bounds/helpers/styles/compute.ts

@@ -1,10 +1,8 @@
 import type { MeasuredDimensions } from "react-native-reanimated";
 import {
-	EMPTY_BOUND_HELPER_RESULT_RAW,
 	ENTER_RANGE,
 	EXIT_RANGE,
 	FULLSCREEN_DIMENSIONS,
-	HIDDEN_STYLE,
 	NO_STYLES,
 } from "../../../../constants";
 import {
@@ -56,7 +54,7 @@ const resolveStartEnd = (params: {
 
 	const resolvedPair =
 		params.resolvedPair ??
-		BoundStore.resolveTransitionPair(String(params.id), {
+		BoundStore.link.getPair(String(params.id), {
 			currentScreenKey,
 			previousScreenKey,
 			nextScreenKey,
@@ -122,9 +120,6 @@ export const computeBoundStyles = (
 	"worklet";
 
 	if (!id) {
-		if (computeOptions.raw) {
-			return EMPTY_BOUND_HELPER_RESULT_RAW;
-		}
 		return NO_STYLES;
 	}
 
@@ -146,10 +141,7 @@ export const computeBoundStyles = (
 	});
 
 	if (!start || !end) {
-		if (computeOptions.raw) {
-			return EMPTY_BOUND_HELPER_RESULT_RAW;
-		}
-		return HIDDEN_STYLE;
+		return NO_STYLES;
 	}
 
 	const ranges: readonly [number, number] = entering ? ENTER_RANGE : EXIT_RANGE;

package/src/shared/utils/bounds/index.ts

@@ -26,7 +26,7 @@ export const createBoundsAccessor = (
 		// Navigation helpers are intentionally opinionated. Only the resolved
 		// tag from `id`/`group` is allowed to flow into `navigation.zoom()`;
 		// base bounds overrides like `target`, `anchor`, or `scaleMode` must not.
-		const navigationTag = createBoundTag({
+		const tag = createBoundTag({
 			id: options.id,
 			group: options.group,
 		});
@@ -35,12 +35,12 @@ export const createBoundsAccessor = (
 
 		Object.defineProperty(target, "navigation", {
 			value: {
-				zoom: (options?: BoundsNavigationZoomOptions) => {
+				zoom: (zoomOptions?: BoundsNavigationZoomOptions) => {
 					"worklet";
 					return buildZoomStyles({
-						props: getProps(),
-						resolvedTag: navigationTag,
-						zoomOptions: options,
+						props,
+						tag,
+						zoomOptions,
 					});
 				},
 			},
@@ -51,13 +51,14 @@ export const createBoundsAccessor = (
 		return target;
 	};
 
-	const { getSnapshot, getLink } = createLinkAccessor(getProps);
+	const { getMeasured, getSnapshot, getLink } = createLinkAccessor(getProps);
 	const { interpolateStyle, interpolateBounds } = createInterpolators({
 		getProps,
 		getLink,
 	});
 
 	return Object.assign(computeBounds, {
+		getMeasured,
 		getSnapshot,
 		getLink,
 		interpolateStyle,