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

package/src/navigators/blank-stack/components/stack-view.tsx

@@ -0,0 +1,96 @@
+import { memo, type ReactNode, useMemo } from "react";
+import { StyleSheet } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+import { PortalProvider } from "../../../components/boundary/portal";
+import { Overlay } from "../../../components/overlay";
+import { ScreenLayers } from "../../../components/screen-layers";
+import { BuilderProvider } from "../../../providers/builder";
+import { MotionProvider } from "../../../providers/motion";
+import { OrchestratorProvider } from "../../../providers/orchestrator";
+import type { BlankStackProviderProps } from "../../../types/providers/blank-stack-provider.types";
+import { useNavigationHelpers } from "../hooks/use-navigation-helpers";
+import {
+	BlankStackProvider,
+	useBlankStackStore,
+} from "../state/blank-stack.provider";
+import { ActivityContainer, ActivityScreen } from "./activity";
+import { BlankStackLifecycle } from "./lifecycle/blank-stack";
+
+const SceneMotion = memo(function SceneMotion({
+	children,
+}: {
+	children: ReactNode;
+}) {
+	const { requestDismiss } = useNavigationHelpers();
+	return (
+		<MotionProvider onDismissRequest={requestDismiss}>
+			<OrchestratorProvider>
+				<ScreenLayers onDismissRequest={requestDismiss}>
+					{children}
+				</ScreenLayers>
+			</OrchestratorProvider>
+			<BlankStackLifecycle />
+		</MotionProvider>
+	);
+});
+
+interface RouteKeyProps {
+	routeKey: string;
+}
+
+const BlankSceneRow = memo(function BlankSceneRow({ routeKey }: RouteKeyProps) {
+	const scene = useBlankStackStore((store) => store.scenesByKey[routeKey]);
+	const descriptors = useMemo(
+		() => ({
+			current: scene.descriptor,
+			previous: scene.previousDescriptor,
+			next: scene.nextDescriptor,
+		}),
+		[scene.descriptor, scene.previousDescriptor, scene.nextDescriptor],
+	);
+
+	return (
+		<ActivityScreen routeKey={routeKey}>
+			<BuilderProvider routeKey={routeKey} descriptors={descriptors}>
+				<SceneMotion>{scene.descriptor.render?.()}</SceneMotion>
+			</BuilderProvider>
+		</ActivityScreen>
+	);
+});
+
+export const BlankStackView = memo(function BlankStackView() {
+	const routeKeys = useBlankStackStore((store) => store?.routeKeys);
+	return (
+		<PortalProvider>
+			<Overlay />
+			<ActivityContainer>
+				{routeKeys.map((routeKey) => (
+					<BlankSceneRow key={routeKey} routeKey={routeKey} />
+				))}
+			</ActivityContainer>
+		</PortalProvider>
+	);
+});
+
+export const BlankStack = memo(function BlankStack({
+	state,
+	navigation,
+	descriptors,
+}: BlankStackProviderProps) {
+	return (
+		<GestureHandlerRootView style={styles.container}>
+			<SafeAreaProvider>
+				<BlankStackProvider
+					state={state}
+					navigation={navigation}
+					descriptors={descriptors}
+				>
+					<BlankStackView />
+				</BlankStackProvider>
+			</SafeAreaProvider>
+		</GestureHandlerRootView>
+	);
+});
+
+const styles = StyleSheet.create({ container: { flex: 1 } });

package/src/navigators/blank-stack/create-blank-stack-navigator.tsx

@@ -0,0 +1,35 @@
+import { createStandardNavigator } from "standard-navigation";
+import type { BlankStackNavigationOptions } from "../../types/blank-stack.types";
+import type {
+	BaseStackNavigation,
+	BaseStackRoute,
+	BaseStackState,
+} from "../../types/stack.types";
+import { BlankStack } from "./components/stack-view";
+
+export type BlankStackStandardEventMap = {};
+
+export type BlankStackStandardNavigatorProps = {
+	navigationState?: BaseStackState<BaseStackRoute>;
+	navigation?: BaseStackNavigation;
+};
+
+export const BlankStackNavigator = createStandardNavigator<
+	BlankStackNavigationOptions,
+	BlankStackStandardEventMap,
+	BlankStackStandardNavigatorProps
+>(({ descriptors, navigation, navigationState }) => {
+	if (!navigationState || !navigation) {
+		throw new Error(
+			"BlankStack requires navigation state and helpers from its integration.",
+		);
+	}
+
+	return (
+		<BlankStack
+			state={navigationState}
+			navigation={navigation}
+			descriptors={descriptors}
+		/>
+	);
+});

package/src/navigators/blank-stack/hooks/use-navigation-helpers.ts

@@ -0,0 +1,65 @@
+import { useCallback } from "react";
+import { runOnUISync } from "react-native-worklets";
+import { useBuilderStore } from "../../../providers/builder";
+import { getMotionStore } from "../../../providers/motion";
+import { LifecycleTransitionRequestKind } from "../../../providers/motion/hooks/use-transition-values";
+import { dispatchCloseAction } from "../../../utils/navigation/close-action-replay";
+import { useBlankStackStore } from "../state/blank-stack.provider";
+
+export function useNavigationHelpers() {
+	const route = useBuilderStore((store) => store.descriptors.current.route);
+	const navigation = useBuilderStore(
+		(store) => store.descriptors.current.navigation,
+	);
+	const requestStackDismiss = useBlankStackStore(
+		(stack) => stack.requestDismiss,
+	);
+
+	const dismissScreen = useCallback((): boolean => {
+		const state = navigation.getState();
+		const routeIndex = state.routes.findIndex(
+			(stateRoute) => stateRoute.key === route.key,
+		);
+		const routeStillPresent = routeIndex !== -1;
+		if (!routeStillPresent || routeIndex === 0) return false;
+
+		const action = {
+			type: "POP",
+			payload: { count: 1 },
+			source: route.key,
+			target: state.key,
+		};
+		dispatchCloseAction(action, (closeAction) => {
+			navigation.dispatch(closeAction);
+		});
+		return true;
+	}, [navigation, route.key]);
+
+	const requestDismiss = useCallback((): boolean => {
+		if (requestStackDismiss) {
+			if (!requestStackDismiss({ route })) return false;
+		} else {
+			const state = navigation.getState();
+			const routeIndex = state.routes.findIndex(
+				(stateRoute) => stateRoute.key === route.key,
+			);
+			if (routeIndex <= 0) return false;
+		}
+
+		const {
+			closing,
+			actions: { requestLifecycleTransition },
+		} = getMotionStore(route.key).state;
+
+		// Publish before the remaining React commit delays JS's queued UI writes.
+		runOnUISync(() => {
+			"worklet";
+			if (!closing.get()) {
+				requestLifecycleTransition(LifecycleTransitionRequestKind.Close, 0);
+			}
+		});
+		return true;
+	}, [navigation, route, requestStackDismiss]);
+
+	return { dismissScreen, requestDismiss };
+}

package/src/navigators/blank-stack/state/blank-stack.provider.tsx

@@ -0,0 +1,90 @@
+import { type ReactNode, useMemo } from "react";
+import type { BlankStackDescriptor } from "../../../types/blank-stack.types";
+import type {
+	BlankStackProviderProps,
+	BlankStackStoreValue,
+} from "../../../types/providers/blank-stack-provider.types";
+import type { BaseStackScene } from "../../../types/stack.types";
+import createProvider from "../../../utils/create-provider";
+import { resolvePresentedIndex } from "./helpers/resolve-presented-index";
+import { useBlankStackState } from "./use-blank-stack-state";
+
+type InternalBlankStackProviderProps = BlankStackProviderProps & {
+	children: ReactNode;
+};
+
+const createScenesByKey = (scenes: BaseStackScene<BlankStackDescriptor>[]) => {
+	const scenesByKey: Record<string, BaseStackScene<BlankStackDescriptor>> = {};
+
+	for (const scene of scenes) {
+		scenesByKey[scene.route.key] = scene;
+	}
+
+	return scenesByKey;
+};
+
+const {
+	StoreProvider: BlankStackStoreProvider,
+	BlankStackProvider,
+	useBlankStackStore,
+	useOptionalBlankStackStore,
+} = createProvider("BlankStack")<
+	InternalBlankStackProviderProps,
+	BlankStackStoreValue
+>(
+	({ state: stackState, children, ...props }) => {
+		const { state, handleCloseRoute, handleOpenRoute, requestDismiss } =
+			useBlankStackState({
+				...props,
+				state: stackState,
+			});
+
+		const navigatorKey = stackState.key;
+		const focusedIndex = resolvePresentedIndex(
+			state.routes,
+			state.focusedRouteKey,
+			state.closingRouteKeys,
+		);
+
+		const scenesByKey = useMemo(
+			() => createScenesByKey(state.scenes),
+			[state.scenes],
+		);
+
+		const paintDriverRouteKeyByRouteKey = useMemo(() => {
+			const paintDrivers = new Map<string, string>();
+
+			for (let index = 0; index + 2 < state.routeKeys.length; index++) {
+				paintDrivers.set(state.routeKeys[index], state.routeKeys[index + 2]);
+			}
+
+			return paintDrivers;
+		}, [state.routeKeys]);
+
+		return {
+			value: {
+				navigatorKey,
+				routeKeys: state.routeKeys,
+				routes: state.routes,
+				scenes: state.scenes,
+				scenesByKey,
+				paintDriverRouteKeyByRouteKey,
+				focusedIndex,
+				requestDismiss,
+				shouldShowFloatOverlay: state.shouldShowFloatOverlay,
+				handleCloseRoute,
+				handleOpenRoute,
+			},
+			children,
+		};
+	},
+	{ getRouteActivity: (store, key) => store.scenesByKey[key]?.activity },
+);
+
+export type { BlankStackProviderProps, BlankStackStoreValue };
+export {
+	BlankStackProvider,
+	BlankStackStoreProvider,
+	useBlankStackStore,
+	useOptionalBlankStackStore,
+};

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,
+	};
+}