react-native-screen-transitions 2.0.4 → 2.1.0

package/src/utils/bounds/_types/builder.ts

@@ -1,4 +1,5 @@
 import type { ScaledSize } from "react-native";
+import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
 import type { ScreenTransitionState } from "../../../types/animation";
 import type { BoundsMethod } from "../../../types/bounds";
 
@@ -14,22 +15,137 @@ export type BoundsBuilderInitParams = {
 	dimensions: ScaledSize;
 };
 
-/**
- * Params used internally for final computation. Method is required.
- */
-export type BoundsComputeParams = BoundsBuilderInitParams & {
-	method: BoundsMethod;
+export type BoundsAnchor =
+	| "topLeading"
+	| "top"
+	| "topTrailing"
+	| "leading"
+	| "center"
+	| "trailing"
+	| "bottomLeading"
+	| "bottom"
+	| "bottomTrailing";
+
+export type BoundsScaleMode = "match" | "none" | "uniform";
+
+export type BoundsTarget = "bound" | "fullscreen" | MeasuredDimensions;
+
+export type BoundsSpace = "relative" | "absolute";
+
+export type BoundsComputeParams = BoundsBuilderInitParams;
+
+export type RawSizeAbsoluteReturn = {
+	width: number;
+	height: number;
+	translateX: number;
+	translateY: number;
 };
 
-/**
- * Builder options that affect how math is applied.
- * Method is not an option; it's tracked separately by the builder.
- */
+export type RawSizeRelativeReturn = {
+	translateX: number;
+	translateY: number;
+	width: number;
+	height: number;
+};
+
+export type RawTransformAbsoluteReturn = {
+	translateX: number;
+	translateY: number;
+	scaleX: number;
+	scaleY: number;
+};
+
+export type RawTransformRelativeReturn = {
+	translateX: number;
+	translateY: number;
+	scaleX: number;
+	scaleY: number;
+};
+
+export type RawContentReturn = {
+	translateX: number;
+	translateY: number;
+	scale: number;
+};
+
+// 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 = {
-	gestures?: { x?: number; y?: number };
+	/**
+	 * @deprecated Use `content.scaleMode` instead.
+	 */
 	toFullscreen?: boolean;
+	/**
+	 * @deprecated Use `content.anchor` instead.
+	 */
 	absolute?: boolean;
+	/**
+	 * @deprecated Use `content.anchor` instead.
+	 */
 	relative?: boolean;
-	method?: BoundsMethod;
+	/**
+	 * @deprecated Use `scaleMode` instead.
+	 */
 	contentScaleMode?: "aspectFill" | "aspectFit" | "auto";
+
+	/**
+	 * The ID of the bound to compute bounds for. If not provided, uses the active bound ID.
+	 */
+	id?: string;
+
+	/**
+	 * The method to use to compute the bounds.
+	 *
+	 * - "transform": translates and scales (scaleX/scaleY), no width/height size
+	 * - "size": translates and sizes (width/height), no scaleX/scaleY
+	 * - "content": screen-level content transform that aligns the destination screen
+	 *   so the target bound matches the source at progress start
+	 * @default "transform"
+	 */
+	method?: BoundsMethod;
+
+	/**
+	 * The space to use to compute the bounds.
+	 *
+	 * - "relative": the bounds are computed with relative deltas, constrained by parent layout
+	 * - "absolute": the bounds are computed with absolute coordinates, unconstrained by parent layout
+	 * @default "relative"
+	 */
+	space?: BoundsSpace;
+	/**
+	 * Whether the bound should target the screen or the bound.
+	 * @default "bound"
+	 */
+	target?: BoundsTarget;
+	/**
+	 * The gesture offsets to apply to the bounds.
+	 */
+	gestures?: { x?: number; y?: number };
+	/**
+	 * How the bounds should be scaled between each other.
+	 * @default "match"
+	 */
+	scaleMode?: BoundsScaleMode;
+	/**
+	 * Where the bounds should be anchored between each other.
+	 * @default "center"
+	 */
+	anchor?: BoundsAnchor;
+	/**
+	 * If true, the raw values will be returned instead of the computed values.
+	 * @default false
+	 */
+	raw?: boolean;
 };

package/src/utils/bounds/_types/geometry.ts

@@ -1,5 +1,4 @@
 export type GeometryBase = {
-	ranges: readonly [number, number];
 	entering: boolean;
 };
 

package/src/utils/bounds/_utils/geometry.ts

@@ -0,0 +1,166 @@
+import type { ScaledSize } from "react-native";
+import type { MeasuredDimensions } from "react-native-reanimated";
+import type { BoundsAnchor, BoundsScaleMode } from "../_types/builder";
+import type {
+	ContentTransformGeometry,
+	RelativeGeometry,
+} from "../_types/geometry";
+
+/**
+ * Get the anchor point coordinates for a given bound
+ */
+function getAnchorPoint(
+	bounds: MeasuredDimensions,
+	anchor: BoundsAnchor = "center",
+): { x: number; y: number } {
+	"worklet";
+
+	const { pageX, pageY, width, height } = bounds;
+
+	switch (anchor) {
+		case "topLeading":
+			return { x: pageX, y: pageY };
+		case "top":
+			return { x: pageX + width / 2, y: pageY };
+		case "topTrailing":
+			return { x: pageX + width, y: pageY };
+		case "leading":
+			return { x: pageX, y: pageY + height / 2 };
+		case "center":
+			return { x: pageX + width / 2, y: pageY + height / 2 };
+		case "trailing":
+			return { x: pageX + width, y: pageY + height / 2 };
+		case "bottomLeading":
+			return { x: pageX, y: pageY + height };
+		case "bottom":
+			return { x: pageX + width / 2, y: pageY + height };
+		case "bottomTrailing":
+			return { x: pageX + width, y: pageY + height };
+		default:
+			// Default to center
+			return { x: pageX + width / 2, y: pageY + height / 2 };
+	}
+}
+
+/**
+ * Relative geometry between start/end bounds.
+ */
+export function computeRelativeGeometry({
+	start,
+	end,
+	entering,
+	anchor = "center",
+	scaleMode = "match",
+}: {
+	start: MeasuredDimensions;
+	end: MeasuredDimensions;
+	entering: boolean;
+	anchor?: BoundsAnchor;
+	scaleMode?: BoundsScaleMode;
+}): RelativeGeometry {
+	"worklet";
+
+	let scaleX: number;
+	let scaleY: number;
+
+	if (scaleMode === "none") {
+		scaleX = 1;
+		scaleY = 1;
+	} else if (scaleMode === "uniform") {
+		const sx = start.width / end.width;
+		const sy = start.height / end.height;
+
+		const startAspect = start.width / start.height;
+		const endAspect = end.width / end.height;
+		const aspectDifference = Math.abs(startAspect - endAspect);
+
+		const scale = aspectDifference < 0.1 ? Math.max(sx, sy) : Math.min(sx, sy);
+		scaleX = scale;
+		scaleY = scale;
+	} else {
+		scaleX = start.width / end.width;
+		scaleY = start.height / end.height;
+	}
+
+	const startAnchor = getAnchorPoint(start, anchor);
+	const endAnchor = getAnchorPoint(end, anchor);
+
+	const endCenter = getAnchorPoint(end, "center");
+	const anchorOffsetX = endAnchor.x - endCenter.x;
+	const anchorOffsetY = endAnchor.y - endCenter.y;
+
+	const dx = startAnchor.x - endCenter.x - anchorOffsetX * scaleX;
+	const dy = startAnchor.y - endCenter.y - anchorOffsetY * scaleY;
+
+	return { dx, dy, scaleX, scaleY, entering };
+}
+/**
+ * Computes the transform to apply to the entire destination screen so that
+ * its bound (end) matches the source bound (start) at progress start.
+ */
+export function computeContentTransformGeometry({
+	start,
+	end,
+	entering,
+	dimensions,
+	anchor = "center",
+	scaleMode = "uniform",
+}: {
+	start: MeasuredDimensions;
+	end: MeasuredDimensions;
+	entering: boolean;
+	dimensions: ScaledSize;
+	anchor?: BoundsAnchor;
+	scaleMode?: BoundsScaleMode;
+}): ContentTransformGeometry {
+	"worklet";
+
+	// Calculate scale based on how much we need to scale the screen
+	// so that the end element matches the start element's size
+	let s: number;
+
+	if (scaleMode === "none") {
+		s = 1;
+	} else if (scaleMode === "uniform") {
+		const sx = start.width / end.width;
+		const sy = start.height / end.height;
+
+		const startAspect = start.width / start.height;
+		const endAspect = end.width / end.height;
+		const aspectDifference = Math.abs(startAspect - endAspect);
+
+		s = aspectDifference < 0.1 ? Math.max(sx, sy) : Math.min(sx, sy);
+	} else {
+		// For "match" mode on full screen, we need uniform scale
+		const sx = start.width / end.width;
+		const sy = start.height / end.height;
+		s = (sx + sy) / 2;
+	}
+
+	// Get anchor points
+	const startAnchor = getAnchorPoint(start, anchor);
+	const endAnchor = getAnchorPoint(end, anchor);
+
+	// Screen center (scaling origin)
+	const screenCenterX = dimensions.width / 2;
+	const screenCenterY = dimensions.height / 2;
+
+	// How far the end anchor is from screen center
+	const endOffsetFromScreenCenterX = endAnchor.x - screenCenterX;
+	const endOffsetFromScreenCenterY = endAnchor.y - screenCenterY;
+
+	// After scaling the screen from its center, the end anchor moves to:
+	const scaledEndAnchorX = screenCenterX + endOffsetFromScreenCenterX * s;
+	const scaledEndAnchorY = screenCenterY + endOffsetFromScreenCenterY * s;
+
+	// Translation to align scaled end anchor with start anchor
+	const tx = startAnchor.x - scaledEndAnchorX;
+	const ty = startAnchor.y - scaledEndAnchorY;
+
+	return {
+		tx,
+		ty,
+		s,
+		entering,
+	};
+}

package/src/utils/bounds/_utils/get-bounds.ts

@@ -0,0 +1,54 @@
+import type { BoundEntry } from "../../../types/bounds";
+
+import type { GetBoundsParams } from "../_types/get-bounds";
+
+const fallbackBounds = {
+	bounds: {
+		width: 0,
+		height: 0,
+		x: 0,
+		y: 0,
+		pageX: 0,
+		pageY: 0,
+	},
+	styles: {},
+};
+
+export const getBounds = (props: GetBoundsParams): BoundEntry => {
+	"worklet";
+	const boundId = props.id;
+	const phase = props.phase;
+
+	if (phase && boundId) {
+		const phaseMap = {
+			current: props.current?.bounds[boundId],
+			next: props.next?.bounds[boundId],
+			previous: props.previous?.bounds[boundId],
+		};
+
+		const phaseBounds = phaseMap[phase];
+
+		if (!phaseBounds) {
+			return fallbackBounds;
+		}
+
+		return {
+			bounds: phaseBounds.bounds,
+			styles: phaseBounds?.styles,
+		};
+	}
+
+	if (!props.next && boundId) {
+		const previousBounds = props.previous?.bounds[boundId];
+
+		return previousBounds || fallbackBounds;
+	}
+
+	if (boundId) {
+		const nextBounds = props.next?.bounds[boundId];
+
+		return nextBounds || fallbackBounds;
+	}
+
+	return fallbackBounds;
+};

package/src/utils/bounds/_utils/is-bounds-equal.ts

@@ -0,0 +1,24 @@
+import type { MeasuredDimensions } from "react-native-reanimated";
+import { Bounds } from "../../../stores/bounds";
+
+export const isBoundsEqual = ({
+	measured,
+	key,
+	sharedBoundTag,
+}: {
+	measured: MeasuredDimensions;
+	key: string;
+	sharedBoundTag: string;
+}) => {
+	"worklet";
+	const existing = Bounds.getBounds(key)?.[sharedBoundTag]?.bounds;
+	return (
+		existing &&
+		existing.width === measured.width &&
+		existing.height === measured.height &&
+		existing.pageX === measured.pageX &&
+		existing.pageY === measured.pageY &&
+		existing.x === measured.x &&
+		existing.y === measured.y
+	);
+};

package/src/utils/bounds/_utils/style-composers.ts

@@ -0,0 +1,216 @@
+import {
+	interpolate,
+	type MeasuredDimensions,
+	type StyleProps,
+} from "react-native-reanimated";
+import type { BoundsBuilderOptions } from "../_types/builder";
+import type {
+	ContentTransformGeometry,
+	RelativeGeometry,
+} from "../_types/geometry";
+
+/**
+ * Element-level (relative) params shared by size/transform composers.
+ * - start/end: absolute window bounds of the element in previous/next phases
+ * - geometry: relative deltas and scales between start/end (dx, dy, scaleX, scaleY, ...)
+ * - interp: function to interpolate between numbers using the correct progress range
+ */
+export type ElementComposeParams = {
+	start: MeasuredDimensions;
+	end: MeasuredDimensions;
+	geometry: RelativeGeometry;
+	progress: number;
+	ranges: readonly [number, number];
+	computeOptions: BoundsBuilderOptions;
+};
+
+/**
+ * Screen-level content transform params (for aligning destination bound to source).
+ * - start/end: absolute window bounds for the shared id (source/destination)
+ * - geometry: precomputed screen-level tx/ty/sx/sy plus ranges/entering
+ * - interp: function to interpolate between numbers using the correct progress range
+ */
+export type ContentComposeParams = {
+	start: MeasuredDimensions;
+	end: MeasuredDimensions;
+	geometry: ContentTransformGeometry;
+	progress: number;
+	ranges: readonly [number, number];
+	computeOptions: BoundsBuilderOptions;
+};
+
+export function composeSizeAbsolute(params: ElementComposeParams): StyleProps {
+	"worklet";
+	const { start, end, geometry, progress, ranges, computeOptions } = params;
+
+	const width = geometry.entering
+		? interpolate(progress, ranges, [start.width, end.width])
+		: interpolate(progress, ranges, [end.width, start.width]);
+	const height = geometry.entering
+		? interpolate(progress, ranges, [start.height, end.height])
+		: interpolate(progress, ranges, [end.height, start.height]);
+
+	const translateX = geometry.entering
+		? interpolate(progress, ranges, [start.pageX, end.pageX])
+		: interpolate(progress, ranges, [end.pageX, start.pageX]);
+	const translateY = geometry.entering
+		? interpolate(progress, ranges, [start.pageY, end.pageY])
+		: interpolate(progress, ranges, [end.pageY, start.pageY]);
+
+	if (computeOptions.raw) {
+		return {
+			width,
+			height,
+			translateX,
+			translateY,
+		};
+	}
+
+	return {
+		width,
+		height,
+		transform: [{ translateX }, { translateY }],
+	};
+}
+
+export function composeSizeRelative(params: ElementComposeParams): StyleProps {
+	"worklet";
+	const { start, end, geometry, progress, ranges, computeOptions } = params;
+
+	const translateX = geometry.entering
+		? interpolate(progress, ranges, [geometry.dx, 0])
+		: interpolate(progress, ranges, [0, -geometry.dx]);
+
+	const translateY = geometry.entering
+		? interpolate(progress, ranges, [geometry.dy, 0])
+		: interpolate(progress, ranges, [0, -geometry.dy]);
+
+	const width = geometry.entering
+		? interpolate(progress, ranges, [start.width, end.width])
+		: interpolate(progress, ranges, [end.width, start.width]);
+
+	const height = geometry.entering
+		? interpolate(progress, ranges, [start.height, end.height])
+		: interpolate(progress, ranges, [end.height, start.height]);
+
+	if (computeOptions.raw) {
+		return {
+			translateX,
+			translateY,
+			width,
+			height,
+		};
+	}
+
+	return {
+		transform: [{ translateX }, { translateY }],
+		width,
+		height,
+	};
+}
+
+export function composeTransformAbsolute(
+	params: ElementComposeParams,
+): StyleProps {
+	"worklet";
+	const { start, end, geometry, progress, ranges, computeOptions } = params;
+
+	const translateX = geometry.entering
+		? interpolate(progress, ranges, [start.pageX, end.pageX])
+		: interpolate(progress, ranges, [end.pageX, start.pageX]);
+	const translateY = geometry.entering
+		? interpolate(progress, ranges, [start.pageY, end.pageY])
+		: interpolate(progress, ranges, [end.pageY, start.pageY]);
+	const scaleX = geometry.entering
+		? interpolate(progress, ranges, [geometry.scaleX, 1])
+		: interpolate(progress, ranges, [1, 1 / geometry.scaleX]);
+	const scaleY = geometry.entering
+		? interpolate(progress, ranges, [geometry.scaleY, 1])
+		: interpolate(progress, ranges, [1, 1 / geometry.scaleY]);
+
+	if (computeOptions.raw) {
+		return {
+			translateX,
+			translateY,
+			scaleX,
+			scaleY,
+		};
+	}
+
+	return {
+		transform: [{ translateX }, { translateY }, { scaleX }, { scaleY }],
+	};
+}
+
+export function composeTransformRelative(
+	params: ElementComposeParams,
+): StyleProps {
+	"worklet";
+	const { geometry, computeOptions, progress, ranges } = params;
+
+	const translateX = geometry.entering
+		? interpolate(progress, ranges, [geometry.dx, 0])
+		: interpolate(progress, ranges, [0, -geometry.dx]);
+	const translateY = geometry.entering
+		? interpolate(progress, ranges, [geometry.dy, 0])
+		: interpolate(progress, ranges, [0, -geometry.dy]);
+	const scaleX = geometry.entering
+		? interpolate(progress, ranges, [geometry.scaleX, 1])
+		: interpolate(progress, ranges, [1, 1 / geometry.scaleX]);
+	const scaleY = geometry.entering
+		? interpolate(progress, ranges, [geometry.scaleY, 1])
+		: interpolate(progress, ranges, [1, 1 / geometry.scaleY]);
+
+	if (computeOptions.raw) {
+		return {
+			translateX,
+			translateY,
+			scaleX,
+			scaleY,
+		};
+	}
+
+	return {
+		transform: [
+			{ translateX: computeOptions.gestures?.x ?? 0 },
+			{ translateY: computeOptions.gestures?.y ?? 0 },
+			{ translateX },
+			{ translateY },
+			{ scaleX },
+			{ scaleY },
+		],
+	};
+}
+
+export function composeContentStyle(params: ContentComposeParams): StyleProps {
+	"worklet";
+	const {
+		geometry,
+		progress,
+		ranges,
+		computeOptions: { raw },
+	} = params;
+	const { s, tx, ty, entering } = geometry;
+
+	const translateX = entering
+		? interpolate(progress, ranges, [tx, 0])
+		: interpolate(progress, ranges, [0, tx]);
+	const translateY = entering
+		? interpolate(progress, ranges, [ty, 0])
+		: interpolate(progress, ranges, [0, ty]);
+	const scale = entering
+		? interpolate(progress, ranges, [s, 1])
+		: interpolate(progress, ranges, [1, s]);
+
+	if (raw) {
+		return {
+			translateX,
+			translateY,
+			scale,
+		};
+	}
+
+	return {
+		transform: [{ translateX }, { translateY }, { scale }],
+	};
+}

package/src/utils/bounds/constants.ts

@@ -1,25 +1,40 @@
-import type { ScaledSize } from 'react-native';
-import type { MeasuredDimensions } from 'react-native-reanimated';
-import type { Complete } from '../../types/utils';
-import type { BoundsBuilderOptions } from './_types/builder';
+import type { ScaledSize } from "react-native";
+import type { MeasuredDimensions } from "react-native-reanimated";
+import type { Complete } from "../../types/utils";
+import type { BoundsBuilderOptions } from "./_types/builder";
 
-export const FULLSCREEN_DIMENSIONS = (dimensions: ScaledSize): MeasuredDimensions => {
-  'worklet';
-  return {
-    x: 0,
-    y: 0,
-    pageX: 0,
-    pageY: 0,
-    width: dimensions.width,
-    height: dimensions.height,
-  };
+export const FULLSCREEN_DIMENSIONS = (
+	dimensions: ScaledSize,
+): MeasuredDimensions => {
+	"worklet";
+	return {
+		x: 0,
+		y: 0,
+		pageX: 0,
+		pageY: 0,
+		width: dimensions.width,
+		height: dimensions.height,
+	};
 };
 
-export const DEFAULT_BUILDER_OPTIONS: Complete<BoundsBuilderOptions> = Object.freeze({
-  gestures: { x: 0, y: 0 },
-  toFullscreen: false,
-  absolute: false,
-  relative: true,
-  method: 'transform',
-  contentScaleMode: 'auto',
-});
+export const DEFAULT_BUILDER_OPTIONS: Complete<
+	Omit<BoundsBuilderOptions, "id">
+> = Object.freeze({
+	gestures: { x: 0, y: 0 },
+	toFullscreen: false,
+	absolute: false,
+	relative: true,
+	method: "transform",
+	contentScaleMode: "auto",
+	space: "relative",
+	target: "bound",
+	/**
+	 * Controls how elements scale during transitions
+	 * - "match": Scale to match destination bounds (default for center anchor)
+	 * - "none": No scaling, maintain original size (default for non-center anchors)
+	 * - "uniform": Scale uniformly (maintain aspect ratio)
+	 */
+	scaleMode: "match",
+	anchor: "center",
+	raw: false,
+} as const);