react-native-screen-transitions 4.1.0-beta.1 → 4.1.0-rc.0

package/src/navigators/blank-stack/state/helpers/reconcile-blank-stack-routes.ts

@@ -0,0 +1,199 @@
+import type { BlankStackDescriptorSources } from "../../../../types/providers/blank-stack-provider.types";
+import type { RouteWithKey } from "../../../../types/stack.types";
+import { composeDescriptors } from "./navigation/compose-descriptors";
+import { syncRoutesWithRemoved } from "./navigation/sync-routes-with-removed";
+import { routesHaveSameKeys } from "./state-equality";
+import type {
+	BlankStackRoutes,
+	LocalRoutesState,
+	ReconciledRoutes,
+} from "./types";
+
+type ReconcileBlankStackRoutesParams = {
+	current: LocalRoutesState;
+	previousRoutesSnapshot: BlankStackRoutes;
+	nextRoutesSnapshot: BlankStackRoutes;
+	nextDescriptors: BlankStackDescriptorSources;
+	closingRouteKeys: Set<string>;
+};
+
+const alignRoutesWithLatest = <
+	Route extends RouteWithKey,
+	DescriptorMap extends Record<string, unknown>,
+>(
+	currentRoutes: Route[],
+	currentDescriptors: DescriptorMap,
+	nextRoutes: Route[],
+	nextDescriptors: DescriptorMap,
+): { routes: Route[]; descriptors: DescriptorMap } => {
+	if (currentRoutes.length === 0) {
+		return {
+			routes: nextRoutes,
+			descriptors: composeDescriptors(
+				nextRoutes,
+				nextDescriptors,
+				currentDescriptors,
+			),
+		};
+	}
+
+	const nextRouteLookup = new Map<string, Route>();
+	for (const route of nextRoutes) {
+		nextRouteLookup.set(route.key, route);
+	}
+
+	let didChange = currentRoutes.length !== nextRoutes.length;
+	const alignedRoutes = currentRoutes.map((route) => {
+		const nextRoute = nextRouteLookup.get(route.key);
+
+		if (!nextRoute) {
+			return route;
+		}
+
+		if (nextRoute !== route) {
+			didChange = true;
+			return nextRoute;
+		}
+
+		return route;
+	});
+	const routesResult = didChange ? alignedRoutes : currentRoutes;
+
+	return {
+		routes: routesResult,
+		descriptors: composeDescriptors(
+			routesResult,
+			nextDescriptors,
+			currentDescriptors,
+		),
+	};
+};
+
+const acceptAlreadyClosingRouteRemovals = ({
+	current,
+	previousRoutesSnapshot,
+	nextRoutesSnapshot,
+	nextDescriptors,
+	closingRouteKeys,
+}: ReconcileBlankStackRoutesParams): ReconciledRoutes | null => {
+	const nextRouteKeys = new Set(nextRoutesSnapshot.map((route) => route.key));
+	const acceptedRemovedKeys = new Set<string>();
+
+	for (const route of previousRoutesSnapshot) {
+		if (nextRouteKeys.has(route.key)) {
+			continue;
+		}
+
+		if (!closingRouteKeys.has(route.key)) {
+			continue;
+		}
+
+		acceptedRemovedKeys.add(route.key);
+		closingRouteKeys.delete(route.key);
+	}
+
+	if (acceptedRemovedKeys.size === 0) {
+		return null;
+	}
+
+	const remainingClosingRoutes = current.routes.filter((route) => {
+		if (nextRouteKeys.has(route.key)) {
+			return false;
+		}
+
+		if (acceptedRemovedKeys.has(route.key)) {
+			return false;
+		}
+
+		return closingRouteKeys.has(route.key);
+	});
+
+	// An acknowledgement can arrive together with a new pop. Reconcile that
+	// pop after removing the acknowledged routes from the previous snapshot.
+	const hasNewRemoval = previousRoutesSnapshot.some(
+		(route) =>
+			!nextRouteKeys.has(route.key) && !acceptedRemovedKeys.has(route.key),
+	);
+	const result = hasNewRemoval
+		? syncRoutesWithRemoved({
+				prevRoutes: previousRoutesSnapshot.filter(
+					(route) => !acceptedRemovedKeys.has(route.key),
+				),
+				prevDescriptors: current.sourceDescriptors,
+				nextRoutes: nextRoutesSnapshot,
+				nextDescriptors,
+				closingRouteKeys,
+			})
+		: { routes: nextRoutesSnapshot };
+	const routes = [...result.routes];
+	if (nextRoutesSnapshot.length > 0) {
+		for (const route of remainingClosingRoutes) {
+			if (!routes.some((candidate) => candidate.key === route.key))
+				routes.push(route);
+			closingRouteKeys.add(route.key);
+		}
+	}
+	const descriptors = composeDescriptors(
+		routes,
+		nextDescriptors,
+		current.sourceDescriptors,
+	);
+
+	return {
+		routes,
+		descriptors,
+	};
+};
+
+export const reconcileBlankStackRoutes = (
+	params: ReconcileBlankStackRoutesParams,
+): ReconciledRoutes => {
+	const {
+		current,
+		previousRoutesSnapshot,
+		nextRoutesSnapshot,
+		nextDescriptors,
+		closingRouteKeys,
+	} = params;
+
+	const routeKeysUnchanged = routesHaveSameKeys(
+		previousRoutesSnapshot,
+		nextRoutesSnapshot,
+	);
+
+	if (routeKeysUnchanged) {
+		const result = alignRoutesWithLatest(
+			current.routes,
+			current.sourceDescriptors,
+			nextRoutesSnapshot,
+			nextDescriptors,
+		);
+
+		return {
+			routes: result.routes,
+			descriptors: result.descriptors,
+		};
+	}
+
+	const acceptedRemoval = acceptAlreadyClosingRouteRemovals(params);
+
+	if (acceptedRemoval) {
+		return acceptedRemoval;
+	}
+
+	const result = syncRoutesWithRemoved({
+		prevRoutes:
+			previousRoutesSnapshot.length > 0
+				? previousRoutesSnapshot
+				: current.routes,
+		prevDescriptors: current.sourceDescriptors,
+		nextRoutes: nextRoutesSnapshot,
+		nextDescriptors,
+		closingRouteKeys,
+	});
+
+	return {
+		routes: result.routes,
+		descriptors: result.descriptors,
+	};
+};

package/src/navigators/expo-router/index.tsx

@@ -9,7 +9,7 @@ import {
 	BlankStackNavigator,
 	type BlankStackStandardEventMap,
 	type BlankStackStandardNavigatorProps,
-} from "../create-blank-stack-navigator";
+} from "../blank-stack/create-blank-stack-navigator";
 
 type BlankStackExpoRouterParamList = Record<string, object | undefined>;
 

package/src/navigators/react-navigation/index.tsx

@@ -13,7 +13,7 @@ import type {
 import {
 	BlankStackNavigator,
 	type BlankStackStandardNavigatorProps,
-} from "../create-blank-stack-navigator";
+} from "../blank-stack/create-blank-stack-navigator";
 
 interface BlankStackStandardTypeBag extends StandardNavigationTypeBagBase {
 	State: StackNavigationState<this["ParamList"]>;
@@ -44,3 +44,5 @@ export type {
 	BlankStackScreenProps,
 	InactiveBehavior,
 } from "../../types/blank-stack.types";
+
+export type { BlankStackStandardNavigatorProps } from "../blank-stack/create-blank-stack-navigator";

package/src/providers/builder/builder.provider.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from "react";
+import { useMemo } from "react";
+import type { BaseStackDescriptor } from "../../types/stack.types";
+import createProvider from "../../utils/create-provider";
+import type { DescriptorDerivations } from "./helpers/derive-descriptor-derivations";
+import { deriveDescriptorDerivations } from "./helpers/derive-descriptor-derivations";
+
+import { useScreenTopology } from "./hooks/use-screen-topology";
+
+export type BaseDescriptor = BaseStackDescriptor;
+
+export interface DescriptorsContextValue {
+	previous?: BaseDescriptor;
+	current: BaseDescriptor;
+	next?: BaseDescriptor;
+}
+
+export type DescriptorDerivationsContextValue = DescriptorDerivations;
+
+interface BuilderStoreValue {
+	descriptors: DescriptorsContextValue;
+	derivations: DescriptorDerivationsContextValue;
+	options: BaseDescriptor["options"];
+}
+
+export type BuilderProviderProps = {
+	children: ReactNode;
+	routeKey: string;
+	descriptors: DescriptorsContextValue;
+};
+
+const createBuilderProvider = createProvider("Builder", {
+	global: true,
+})<BuilderProviderProps, BuilderStoreValue>;
+
+const {
+	StoreProvider: BuilderStoreProvider,
+	getBuilderStore,
+	BuilderProvider,
+	useBuilderStore,
+	useOptionalBuilderStore,
+}: ReturnType<typeof createBuilderProvider> = createBuilderProvider(
+	({ routeKey, children, descriptors: inputDescriptors }) => {
+		const currentDescriptor = inputDescriptors.current;
+		const previousDescriptor = inputDescriptors.previous;
+		const nextDescriptor = inputDescriptors.next;
+		const options = currentDescriptor.options;
+
+		const descriptors = useMemo(() => {
+			return {
+				previous: previousDescriptor,
+				current: currentDescriptor,
+				next: nextDescriptor,
+			};
+		}, [previousDescriptor, currentDescriptor, nextDescriptor]);
+
+		const derivations = useMemo(() => {
+			return deriveDescriptorDerivations({
+				previous: previousDescriptor,
+				current: currentDescriptor,
+				next: nextDescriptor,
+			});
+		}, [previousDescriptor, currentDescriptor, nextDescriptor]);
+
+		useScreenTopology(routeKey);
+
+		const value = useMemo(
+			() => ({ descriptors, derivations, options }),
+			[descriptors, derivations, options],
+		);
+
+		return {
+			key: routeKey,
+			value,
+			children,
+		};
+	},
+);
+
+export {
+	BuilderProvider,
+	BuilderStoreProvider,
+	getBuilderStore,
+	useBuilderStore,
+	useOptionalBuilderStore,
+};

package/src/providers/builder/helpers/derive-descriptor-derivations.ts

@@ -0,0 +1,56 @@
+import { createScreenPairKey } from "../../../stores/bounds/helpers/link-pairs.helpers";
+import type { ScreenPairKey } from "../../../stores/bounds/types";
+import type { BaseStackDescriptor } from "../../../types/stack.types";
+
+export interface DescriptorDerivations {
+	previousScreenKey?: string;
+	currentScreenKey: string;
+	nextScreenKey?: string;
+	sourcePairKey?: ScreenPairKey;
+	destinationPairKey?: ScreenPairKey;
+	isFirstKey: boolean;
+	isTopMostScreen: boolean;
+	hasConfiguredInterpolator: boolean;
+}
+
+interface Params {
+	previous?: BaseStackDescriptor;
+	current: BaseStackDescriptor;
+	next?: BaseStackDescriptor;
+}
+
+export function deriveDescriptorDerivations({
+	previous,
+	current,
+	next,
+}: Params): DescriptorDerivations {
+	const previousScreenKey = previous?.route.key;
+	const currentScreenKey = current.route.key;
+	const nextScreenKey = next?.route.key;
+	const sourcePairKey = nextScreenKey
+		? createScreenPairKey(currentScreenKey, nextScreenKey)
+		: undefined;
+	const destinationPairKey = previousScreenKey
+		? createScreenPairKey(previousScreenKey, currentScreenKey)
+		: undefined;
+
+	const navigationState = current.navigation.getState();
+	const routes = navigationState?.routes ?? [];
+	const isFirstKey =
+		routes.findIndex((route) => route.key === current.route.key) === 0;
+	const isTopMostScreen = !next;
+	const hasConfiguredInterpolator =
+		!!current.options.screenStyleInterpolator ||
+		!!next?.options?.screenStyleInterpolator;
+
+	return {
+		previousScreenKey,
+		currentScreenKey,
+		nextScreenKey,
+		sourcePairKey,
+		destinationPairKey,
+		isFirstKey,
+		isTopMostScreen,
+		hasConfiguredInterpolator,
+	};
+}

package/src/providers/builder/hooks/use-screen-topology.ts

@@ -0,0 +1,52 @@
+import { useLayoutEffect } from "react";
+import { useOptionalBlankStackStore } from "../../../navigators/blank-stack/state/blank-stack.provider";
+import { useOptionalBuilderStore } from "../builder.provider";
+import { screenTopology } from "../topology/helpers/create-screen-topology";
+
+export function useScreenTopology(screenKey: string) {
+	const parentScreenKey = useOptionalBuilderStore(
+		(store) => store?.derivations.currentScreenKey,
+	);
+
+	const transitionKey = useOptionalBlankStackStore(
+		(store) => store?.scenesByKey[screenKey]?.descriptor.options.transitionKey,
+	);
+
+	const navigatorKey = useOptionalBlankStackStore((store) =>
+		store?.scenesByKey[screenKey] ? store.navigatorKey : undefined,
+	);
+
+	const isActiveScreen = useOptionalBlankStackStore((store) => {
+		const focusedScene = store?.scenes[store.focusedIndex];
+		return (
+			focusedScene?.route.key === screenKey &&
+			focusedScene.activity === "active"
+		);
+	});
+
+	const enabled = navigatorKey !== undefined;
+
+	useLayoutEffect(() => {
+		if (!enabled) return;
+		screenTopology.register({
+			screenKey,
+			navigatorKey,
+			parentScreenKey,
+			transitionKey,
+		});
+	}, [enabled, screenKey, navigatorKey, parentScreenKey, transitionKey]);
+
+	useLayoutEffect(() => {
+		if (!enabled || !isActiveScreen || !parentScreenKey) return;
+
+		screenTopology.activate({
+			screenKey,
+			parentScreenKey,
+		});
+	}, [enabled, isActiveScreen, parentScreenKey, screenKey]);
+
+	useLayoutEffect(() => {
+		if (!enabled) return;
+		return () => screenTopology.unregister(screenKey);
+	}, [enabled, screenKey]);
+}

package/src/providers/builder/topology/hooks/use-resolved-transition-key.ts

@@ -0,0 +1,29 @@
+import { useCallback, useSyncExternalStore } from "react";
+import type { ScreenTransitionTarget } from "../../../../types/animation.types";
+import { screenTopology } from "../helpers/create-screen-topology";
+
+export const useResolvedTransitionKey = (
+	screenKey: string | null,
+	target?: ScreenTransitionTarget,
+) => {
+	const depth = typeof target === "string" ? null : (target?.depth ?? 0);
+	const requiresResolution = typeof target === "string" || depth !== 0;
+	const subscribe = useCallback(
+		(listener: () => void) =>
+			requiresResolution
+				? screenTopology.subscribeResolution(listener)
+				: () => {},
+		[requiresResolution],
+	);
+	const getSnapshot = useCallback(
+		() =>
+			typeof target === "string"
+				? screenTopology.resolveTransitionKey(target)
+				: requiresResolution && screenKey
+					? screenTopology.resolve(screenKey, depth ?? 0)
+					: screenKey,
+		[depth, requiresResolution, screenKey, target],
+	);
+
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};

package/src/providers/motion/animation/emit-motion-start.ts

@@ -0,0 +1,20 @@
+import { FALSE, TRUE } from "../../../constants";
+import { emit } from "../../../utils/animation/emit";
+import type { MotionAnimationValues } from "../types";
+
+export const emitMotionStart = (animations: MotionAnimationValues) => {
+	"worklet";
+
+	animations.progressSettled.set(FALSE);
+
+	if (animations.progressAnimating.get()) {
+		return false;
+	}
+
+	emit(animations.willAnimate, TRUE, FALSE);
+	requestAnimationFrame(() => {
+		"worklet";
+		animations.progressAnimating.set(TRUE);
+	});
+	return true;
+};

package/src/providers/motion/animation/helpers/build-screen-transition-options.ts

@@ -0,0 +1,22 @@
+import type {
+	ScreenTransitionConfig,
+	ScreenTransitionOptions,
+} from "../../../../types";
+
+export const buildScreenTransitionOptions = (
+	options: ScreenTransitionConfig,
+): ScreenTransitionOptions => {
+	return {
+		gestureEnabled: options.gestureEnabled,
+		gestureTracking: options.gestureTracking,
+		gestureDirection: options.gestureDirection,
+		gestureSensitivity: options.gestureSensitivity,
+		gestureVelocityImpact: options.gestureVelocityImpact,
+		gestureSnapVelocityImpact: options.gestureSnapVelocityImpact,
+		gestureReleaseVelocityScale: options.gestureReleaseVelocityScale,
+		gestureSnapLocked: options.gestureSnapLocked,
+		sheetSnapBehavior: options.sheetSnapBehavior,
+		sheetScrollGestureBehavior: options.sheetScrollGestureBehavior,
+		backdropBehavior: options.backdropBehavior,
+	};
+};

package/src/providers/motion/animation/helpers/hydrate-transition-state/gesture-progress.ts

@@ -0,0 +1,192 @@
+import { clamp } from "react-native-reanimated";
+import { DEFAULT_GESTURE_DIRECTION, EPSILON } from "../../../../../constants";
+import type {
+	GestureDirectionOption,
+	GestureValues,
+} from "../../../../../types/gesture.types";
+import type { SheetSnapBehavior } from "../../../../../types/screen.types";
+import {
+	getPanActivationDirections,
+	getPanSnapAxisConfigForDirection,
+	getPanSnapAxisDirections,
+	getPinchGestureDirections,
+	getSnapPinchDirectionConfig,
+	isResolvedPanGestureDirection,
+} from "../../../gestures/shared/directions";
+import { resolveStepSnapProgress } from "../../../gestures/shared/snap-points";
+import type { SnapBounds } from "./types";
+
+type PanProgressDelta = {
+	x: number;
+	y: number;
+};
+
+const resolvePanGestureAffectedProgress = (
+	transitionProgress: number,
+	gesture: GestureValues,
+	progressDelta: PanProgressDelta,
+	gestureDirection: GestureDirectionOption,
+	hasSnapPoints: boolean,
+	snapBounds: SnapBounds | null,
+	snapPoints: number[],
+	sheetSnapBehavior: SheetSnapBehavior,
+) => {
+	"worklet";
+
+	if (hasSnapPoints) {
+		const activeGesture =
+			gesture.initiator === "none" ? null : gesture.initiator;
+		const activeAxis = isResolvedPanGestureDirection(activeGesture)
+			? getPanSnapAxisConfigForDirection(
+					getPanSnapAxisDirections(gestureDirection),
+					activeGesture,
+				)
+			: null;
+
+		if (!activeAxis || !snapBounds) {
+			return transitionProgress;
+		}
+
+		const axisValue =
+			activeAxis.axis === "horizontal" ? progressDelta.x : progressDelta.y;
+		const signedProgressDelta = activeAxis.config.progressSign * axisValue;
+		if (sheetSnapBehavior === "step") {
+			return resolveStepSnapProgress({
+				baseline: transitionProgress,
+				normalizedDelta: signedProgressDelta,
+				snapPoints,
+			});
+		}
+
+		return clamp(
+			transitionProgress + signedProgressDelta,
+			snapBounds.min,
+			snapBounds.max,
+		);
+	}
+
+	const directions = getPanActivationDirections({
+		gestureDirection,
+		hasSnapPoints: false,
+	});
+	let progressOffset = 0;
+
+	if (directions.horizontal && progressDelta.x > 0) {
+		progressOffset = Math.max(progressOffset, progressDelta.x);
+	}
+
+	if (directions.horizontalInverted && progressDelta.x < 0) {
+		progressOffset = Math.max(progressOffset, -progressDelta.x);
+	}
+
+	if (directions.vertical && progressDelta.y > 0) {
+		progressOffset = Math.max(progressOffset, progressDelta.y);
+	}
+
+	if (directions.verticalInverted && progressDelta.y < 0) {
+		progressOffset = Math.max(progressOffset, -progressDelta.y);
+	}
+
+	return clamp(transitionProgress - progressOffset, 0, transitionProgress);
+};
+
+const resolvePinchGestureAffectedProgress = (
+	transitionProgress: number,
+	gesture: GestureValues,
+	gestureDirection: GestureDirectionOption,
+	hasSnapPoints: boolean,
+	snapBounds: SnapBounds | null,
+	snapPoints: number[],
+	sheetSnapBehavior: SheetSnapBehavior,
+) => {
+	"worklet";
+	const pinchDirection =
+		gesture.normScale < 0
+			? "pinch-in"
+			: gesture.normScale > 0
+				? "pinch-out"
+				: null;
+
+	if (!pinchDirection) {
+		return transitionProgress;
+	}
+
+	if (hasSnapPoints) {
+		const snapDirections = getSnapPinchDirectionConfig(gestureDirection);
+		if (!snapDirections || !snapBounds) {
+			return transitionProgress;
+		}
+
+		const progressDelta =
+			snapDirections.collapse === pinchDirection
+				? -Math.abs(gesture.normScale)
+				: Math.abs(gesture.normScale);
+		if (sheetSnapBehavior === "step") {
+			return resolveStepSnapProgress({
+				baseline: transitionProgress,
+				normalizedDelta: progressDelta,
+				snapPoints,
+			});
+		}
+
+		return clamp(
+			transitionProgress + progressDelta,
+			snapBounds.min,
+			snapBounds.max,
+		);
+	}
+
+	const pinchDirections = getPinchGestureDirections(gestureDirection);
+	if (!pinchDirections.includes(pinchDirection)) {
+		return transitionProgress;
+	}
+
+	return clamp(
+		transitionProgress - Math.abs(gesture.normScale),
+		0,
+		transitionProgress,
+	);
+};
+
+export const resolveGestureAffectedProgress = (
+	transitionProgress: number,
+	gesture: GestureValues,
+	panProgressDelta: PanProgressDelta,
+	gestureDirection: GestureDirectionOption | undefined,
+	snapBounds: SnapBounds | null,
+	snapPoints: number[] = [],
+	sheetSnapBehavior: SheetSnapBehavior = "continuous",
+) => {
+	"worklet";
+	const resolvedGestureDirection =
+		gestureDirection ?? DEFAULT_GESTURE_DIRECTION;
+
+	const hasSnapPoints = snapBounds !== null;
+
+	if (
+		gesture.initiator === "pinch-in" ||
+		gesture.initiator === "pinch-out" ||
+		Math.abs(gesture.normScale) > EPSILON
+	) {
+		return resolvePinchGestureAffectedProgress(
+			transitionProgress,
+			gesture,
+			resolvedGestureDirection,
+			hasSnapPoints,
+			snapBounds,
+			snapPoints,
+			sheetSnapBehavior,
+		);
+	}
+
+	return resolvePanGestureAffectedProgress(
+		transitionProgress,
+		gesture,
+		panProgressDelta,
+		resolvedGestureDirection,
+		hasSnapPoints,
+		snapBounds,
+		snapPoints,
+		sheetSnapBehavior,
+	);
+};