clear-react-router 2.0.5 → 2.0.7

package/README.md

@@ -46,10 +46,10 @@ It provides first-class support for:
 | `maxCacheSize` | `number \| undefined` | 60 for mobile, 150 for desktop | Maximum number of cached loader entries. Once the limit is reached, the least recently used entries are evicted |
 | `isAnimated` | `boolean \| undefined` | `false` | Enable smooth page fade transitions |
 | `animationDuration` | `number` | `optional` | Animation duration in milliseconds (browser default is used if not set) |
-| `spinner` | `boolean \| undefined` | `true` | Show a small spinner in the corner while loading data (only when `isAnimated` is enabled) |
+| `optimisticSpinner` | `boolean \| undefined` | `true` | Show a small spinner in the corner while optimistic route data revalidates in the background |
 | `context` | `object` | `{}` | Initial context (user, theme, etc.) |
 | `errorBoundary` | `ComponentType<{ children: ReactNode }>` | `undefined` | Custom error boundary component for catching render errors in route components |
-| `showFallbackOnAnimation` | `boolean \| undefined` | `false` | Show `loaderFallback` even when `isAnimated` is `true` (instead of spinner) |
+| `defaultMinLoaderDuration` | `number \| undefined` | `0` | Default minimum time the loader fallback stays visible, to avoid flickering |
 | `defaultLoaderFallback` | `ReactElement \| () => ReactElement` | `optional` | Default loading fallback for every route loader |
 | `defaultErrorElement` | `ReactElement \| () => ReactElement` | `optional` | Default error fallback for every route |
 | `defaultRetry` | `number \| { count: number; delay: number }` | `optional` | Default cache revalidation retry policy for all routes |
@@ -63,14 +63,6 @@ It provides first-class support for:
 
 > **Note:** Global lifecycle hooks wrap every route navigation. The global `defaultBeforeLoad` runs **before** the route-specific beforeLoad, while the global `defaultAfterLoad` runs **after** the route-specific afterLoad.
 
-```tsx
-<div>
-  <Navbar />
-  <Router routes={routes} spinner={false} isAnimated />  {/* disable the spinner */}
-</div>
-```
-> **Note:** When `isAnimated` is enabled, `loaderFallback` is not shown. Instead, a small spinner appears (if `spinner={true}`). On the initial page load, however, the route's loaderFallback is rendered if available.
-
 ### `createRouter(routes)`
 
 Normalizes route configuration. Extracts dynamic params, builds nested paths.
@@ -82,6 +74,7 @@ Normalizes route configuration. Extracts dynamic params, builds nested paths.
 | `beforeLoad` | `({ params, context, redirect, setContext }) => Promise<unknown> \| undefined \| void` | Runs before every route navigation. Auth checks and redirects. Can update context via `setContext`. `redirect` is provided by the router |
 | `loader` | `({ params, context, setContext, searchParams, signal }) => Promise<unknown>` | Fetch data using route params, search params, abort controller signal and context. Can update context via `setContext` |
 | `afterLoad` | `({ params, context, setContext }) => Promise<void>` | Runs after a successful navigation once the route has finished loading. Analytics, side effects after data is loaded. Can update context via `setContext` |
+| `minLoaderDuration` | `number \| undefined` | `undefined` | Minimum time the loader fallback stays visible, to avoid flickering |
 | `fallback` | `ReactElement \| () => ReactElement` | Loading fallback (for lazy loading) |
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback for the route's `loader`. Overrides the global `defaultLoaderFallback` set in `Router` |
 | `retry` | `number \| { count: number; delay: number }` | Overrides the global cache revalidation retry policy for this route |
@@ -816,8 +809,6 @@ Clear Router supports smooth page transitions using the native View Transitions
 ## How It Works
 
 - **Data loads first** — All `loader` and `beforeLoad` hooks complete before animation starts
-- **No `loaderFallback`** — The `loaderFallback` is not shown during animated transitions
-- **Subtle spinner** — A small spinner appears in the top-left corner while data is loading and `spinner` prop of `Router` component is on, so users know the app is responsive
 - **Native API** — Uses `document.startViewTransition` for smooth, hardware-accelerated animations
 
 ## Browser Support

package/dist/components/Router.d.ts

@@ -1,2 +1,2 @@
 import { RouterProps } from '../types';
-export declare const Router: ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated, spinner, defaultPreserveScroll, showFallbackOnAnimation, maxCacheSize, defaultPrefetch, defaultHoverPrefetchDelay, errorBoundary: ErrorBoundary, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Router: ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated, optimisticSpinner, defaultPreserveScroll, defaultMinLoaderDuration, maxCacheSize, defaultPrefetch, defaultHoverPrefetchDelay, errorBoundary: ErrorBoundary, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/config/routerConfig.d.ts

@@ -10,6 +10,7 @@ declare class RouterConfig {
     defaultRetry?: RouterProps['defaultRetry'];
     defaultStaleTime?: RouterProps['defaultStaleTime'];
     defaultPreserveScroll?: RouterProps['defaultPreserveScroll'];
+    defaultMinLoaderDuration?: RouterProps['defaultMinLoaderDuration'];
     configure(config: Partial<RouterConfig>): void;
 }
 export declare const routerConfig: RouterConfig;

package/dist/hooks/useLoaderState.d.ts

@@ -1,2 +1 @@
-import { LoaderState } from '../types';
-export declare const useLoaderState: <T>() => LoaderState<T>;
+export declare const useLoaderState: <T>() => import("../types").LoaderState<T>;

package/dist/index.js

@@ -30,12 +30,13 @@ var useGlobalState = ({ subscribe, getState, setState }) => {
 };
 //#endregion
 //#region utils/commitState.ts
-var createCommitState = ({ routeItemDataState, pendingState }) => (nextLocation, routeItem) => {
+var createCommitState = ({ routeItemDataState, pendingState, isOptimisticLoading }) => (nextLocation, routeItem) => {
 	routeItemDataState.setState({
 		routeItem,
 		location: nextLocation
 	});
 	pendingState.setState(void 0);
+	isOptimisticLoading.setState(false);
 	const fullPath = nextLocation.search ? `${nextLocation.pathname}${nextLocation.search}` : nextLocation.pathname;
 	if (fullPath === window.location.pathname + window.location.search) return;
 	history.pushState(null, "", fullPath);
@@ -95,6 +96,7 @@ var RouterConfig = class {
 		_defineProperty(this, "defaultRetry", void 0);
 		_defineProperty(this, "defaultStaleTime", void 0);
 		_defineProperty(this, "defaultPreserveScroll", void 0);
+		_defineProperty(this, "defaultMinLoaderDuration", void 0);
 	}
 	configure(config) {
 		Object.assign(this, config);
@@ -103,13 +105,12 @@ var RouterConfig = class {
 var routerConfig = new RouterConfig();
 //#endregion
 //#region utils/commitNavigation.ts
-var createCommitNavigation = (navigationExecutor, routeItemDataState) => (nextLocation, routeItem) => {
-	const isFirstLoad = !routeItemDataState.getState().location.pathname;
-	if (!routerConfig.isAnimated || isFirstLoad) return navigationExecutor(nextLocation, routeItem);
+var commitNavigation = (callback) => {
+	if (!routerConfig.isAnimated) return callback();
 	try {
-		document.startViewTransition(() => navigationExecutor(nextLocation, routeItem));
+		document.startViewTransition(callback);
 	} catch {
-		navigationExecutor(nextLocation, routeItem);
+		callback();
 	}
 };
 //#endregion
@@ -133,7 +134,7 @@ var createIsCacheItemFresh = (loaderMap) => (path) => {
 * LICENSE file in the root directory of this source tree.
 */
 var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((exports) => {
-	var REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element"), REACT_FRAGMENT_TYPE = Symbol.for("react.fragment");
+	var REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element");
 	function jsxProd(type, config, maybeKey) {
 		var key = null;
 		void 0 !== maybeKey && (key = "" + maybeKey);
@@ -151,7 +152,6 @@ var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((expor
 			props: maybeKey
 		};
 	}
-	exports.Fragment = REACT_FRAGMENT_TYPE;
 	exports.jsx = jsxProd;
 	exports.jsxs = jsxProd;
 }));
@@ -215,6 +215,7 @@ var isMobile = () => {
 	const isSmallScreen = window.matchMedia("(max-width: 768px)").matches;
 	return hasCoarsePointer && isSmallScreen;
 };
+var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var findRoute = (pathname, includeAll) => {
 	if (includeAll) return routerConfig.routes.find((el) => el.path === "*" || comparePaths(el, pathname));
 	return routerConfig.routes.find((el) => comparePaths(el, pathname));
@@ -225,20 +226,21 @@ var createNavigate = (routerState, revalidateCache) => {
 	let navigationSeq = 0;
 	let interval = 0;
 	let abortController = null;
-	const { loaderStateRef, scrollMapState, pendingState, contextState, loaderMap, routeItemDataState } = routerState;
-	const commitNavigation = createCommitNavigation(createCommitState(routerState), routeItemDataState);
+	const { loaderState, scrollMapState, pendingState, contextState, loaderMap, routeItemDataState, isOptimisticLoading } = routerState;
+	const navigationExecutor = createCommitState(routerState);
 	const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
 	const createSignal = () => {
 		abortController?.abort();
 		abortController = new AbortController();
 		return abortController.signal;
 	};
+	const getPath = (nextLocation) => `${nextLocation.pathname}${nextLocation.search ?? ""}`;
 	const getContext = () => ({
 		context: contextState.getState(),
 		setContext: contextState.setState
 	});
 	const routeResolve = (location) => {
-		loaderStateRef.set(emptyLoaderState);
+		loaderState.setState(emptyLoaderState);
 		const nextItem = findRoute(location.pathname, true);
 		return {
 			nextItem,
@@ -255,12 +257,12 @@ var createNavigate = (routerState, revalidateCache) => {
 					redirect,
 					params
 				});
-				loaderStateRef.set((prev) => ({
+				loaderState.setState((prev) => ({
 					...prev,
 					beforeLoadError: null
 				}));
 			} catch (error) {
-				loaderStateRef.set((prev) => ({
+				loaderState.setState((prev) => ({
 					...prev,
 					beforeLoadError: error
 				}));
@@ -279,44 +281,51 @@ var createNavigate = (routerState, revalidateCache) => {
 				[prevPathname]: scrollPosition
 			};
 		});
-		const path = `${location.pathname}${location.search}`;
+		const path = getPath(location);
 		if (routeItem?.optimistic && loaderMap.has(path)) {
 			routeItemDataState.setState({
 				routeItem,
 				location
 			});
+			isOptimisticLoading.setState(true);
 			const currentLoaderState = loaderMap.get(path)?.state;
-			if (currentLoaderState) loaderStateRef.set(currentLoaderState);
-		} else {
-			const pendingShouldExist = routeItem?.loader && !isCacheItemFresh(path);
-			pendingState.setState(pendingShouldExist ? {
-				routeItem,
-				location
-			} : void 0);
-		}
+			if (currentLoaderState) loaderState.setState(currentLoaderState);
+		} else if (routeItem?.loader && !isCacheItemFresh(path)) commitNavigation(() => pendingState.setState({
+			routeItem,
+			location
+		}));
+		else pendingState.setState(void 0);
 	};
-	const polling = (routeItem, location) => {
+	const polling = (routeItem, nextLocation) => {
 		if (!routeItem?.pollingInterval) return;
 		const signal = createSignal();
 		interval = window.setInterval(() => revalidateCache({
 			routeItem,
-			pathname: location.pathname,
-			search: location.search,
+			pathname: nextLocation.pathname,
+			search: nextLocation.search,
 			signal
 		}), routeItem.pollingInterval);
 	};
-	const loader = async (routeItem, location, seq) => {
+	const getLoaderDurationPromise = (routeItem, nextLocation) => {
+		const minLoaderDuration = routeItem?.minLoaderDuration ?? routerConfig.defaultMinLoaderDuration ?? 0;
+		return minLoaderDuration && !isCacheItemFresh(getPath(nextLocation)) ? sleep(minLoaderDuration) : Promise.resolve;
+	};
+	const loader = async (routeItem, nextLocation, seq) => {
 		if (!routeItem?.loader) return;
 		window.clearInterval(interval);
 		const signal = createSignal();
-		await revalidateCache({
+		const [result] = await Promise.all([revalidateCache({
 			routeItem,
-			pathname: location.pathname,
-			search: location.search,
+			pathname: nextLocation.pathname,
+			search: nextLocation.search,
 			signal
-		});
+		}), getLoaderDurationPromise(routeItem, nextLocation)]);
+		if (result) loaderState.setState((prev) => ({
+			...prev,
+			...result
+		}));
 		if (seq !== navigationSeq) return;
-		polling(routeItem, location);
+		polling(routeItem, nextLocation);
 	};
 	const afterLoad = async (routeItem, params) => {
 		const { defaultAfterLoad } = routerConfig;
@@ -338,7 +347,7 @@ var createNavigate = (routerState, revalidateCache) => {
 		prepareNavigation(nextItem, nextLocation);
 		await loader(nextItem, nextLocation, seq);
 		if (seq !== navigationSeq) return;
-		commitNavigation(nextLocation, nextItem);
+		commitNavigation(() => navigationExecutor(nextLocation, nextItem));
 		await afterLoad(nextItem, params);
 	};
 	return navigate;
@@ -346,7 +355,7 @@ var createNavigate = (routerState, revalidateCache) => {
 //#endregion
 //#region runtime/invalidate.ts
 var redirect = Promise.resolve;
-var createInvalidate = ({ routeItemDataState, loaderStateRef, loaderMap, currentLoaderState, contextState }, revalidateCache) => {
+var createInvalidate = ({ routeItemDataState, loaderState, loaderMap, contextState }, revalidateCache) => {
 	const invalidatePath = async (routeItem, pathname, options) => {
 		const routePathname = routeItemDataState.getState().location.pathname;
 		loaderMap.delete(pathname);
@@ -362,12 +371,12 @@ var createInvalidate = ({ routeItemDataState, loaderStateRef, loaderMap, current
 					setContext
 				});
 			}
-			loaderStateRef.set((prev) => ({
+			loaderState.setState((prev) => ({
 				...prev,
 				beforeLoadError: null
 			}));
 		} catch (error) {
-			loaderStateRef.set((prev) => ({
+			loaderState.setState((prev) => ({
 				...prev,
 				beforeLoadError: error
 			}));
@@ -376,7 +385,11 @@ var createInvalidate = ({ routeItemDataState, loaderStateRef, loaderMap, current
 			routeItem,
 			pathname
 		});
-		if (pathname === routePathname) currentLoaderState.setState(loaderStateRef.value);
+		if (result && pathname === routePathname) loaderState.setState({
+			data: result.data,
+			loaderError: result.error,
+			beforeLoadError: null
+		});
 		return {
 			path: pathname,
 			...result
@@ -430,16 +443,8 @@ var getRetry = (routeItem) => {
 		delay: routeRetry ? routeRetry.delay : globalRetry?.delay || 0
 	};
 };
-var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var createRevalidateCache = (routerState) => {
-	const { loaderStateRef, contextState, loaderMap, loadingPromises } = routerState;
-	const removeStaleItems = () => {
-		const deletedItems = [...loaderMap.entries()].filter(([, item]) => {
-			const staleTime = item.staleTime ?? routerConfig.defaultStaleTime;
-			return staleTime && staleTime + item.timestamp < Date.now();
-		});
-		if (deletedItems.length) deletedItems.forEach((item) => loaderMap.delete(item[0]));
-	};
+	const { contextState, loaderMap, loadingPromises } = routerState;
 	const evict = () => {
 		if (loaderMap.size <= routerConfig.maxCacheSize) return;
 		const oldestKey = loaderMap.keys().next().value;
@@ -456,7 +461,6 @@ var createRevalidateCache = (routerState) => {
 	const revalidateCache = async ({ routeItem, pathname, search = "", signal }, retried = 0) => {
 		if (!routeItem?.loader) return;
 		const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
-		removeStaleItems();
 		const path = `${pathname}${search}`;
 		if (loadingPromises.has(path)) {
 			moveItemToLastPosition(path);
@@ -464,8 +468,14 @@ var createRevalidateCache = (routerState) => {
 		}
 		if (isCacheItemFresh(path)) {
 			const item = moveItemToLastPosition(path);
-			if (item?.state) loaderStateRef.set(item.state);
-			return;
+			if (!item?.state) return void 0;
+			return item.state.loaderError ? {
+				data: null,
+				error: item.state.loaderError
+			} : {
+				data: item.state.data,
+				error: null
+			};
 		}
 		const promise = (async () => {
 			if (!routeItem?.loader) return;
@@ -482,13 +492,12 @@ var createRevalidateCache = (routerState) => {
 					searchParams,
 					signal: effectiveSignal
 				});
-				loaderStateRef.set((prev) => ({
-					...prev,
-					data: result,
-					loaderError: null
-				}));
 				loaderMap.set(path, {
-					state: loaderStateRef.value,
+					state: {
+						data: result,
+						beforeLoadError: null,
+						loaderError: null
+					},
 					timestamp: Date.now(),
 					staleTime: routeItem.staleTime
 				});
@@ -506,27 +515,16 @@ var createRevalidateCache = (routerState) => {
 				if (retry && retry.count > retried) {
 					loadingPromises.delete(path);
 					if (retry.delay) await sleep(retry.delay);
-					await revalidateCache({
+					return revalidateCache({
 						routeItem,
 						pathname,
 						search,
 						signal
 					}, retried + 1);
-					return {
-						data: null,
-						error
-					};
-				} else {
-					loaderStateRef.set((prev) => ({
-						...prev,
-						data: null,
-						loaderError: error
-					}));
-					return {
-						data: null,
-						error
-					};
-				}
+				} else return {
+					data: null,
+					error
+				};
 			} finally {
 				loadingPromises.delete(path);
 			}
@@ -537,20 +535,6 @@ var createRevalidateCache = (routerState) => {
 	return revalidateCache;
 };
 //#endregion
-//#region cell.ts
-var Cell = class {
-	constructor(_value) {
-		_defineProperty(this, "_value", void 0);
-		this._value = _value;
-	}
-	get value() {
-		return this._value;
-	}
-	set(action) {
-		this._value = typeof action === "function" ? action(this._value) : action;
-	}
-};
-//#endregion
 //#region utils/createRouterInstance.ts
 var createRouterInstance = () => {
 	const routerState = {
@@ -559,14 +543,14 @@ var createRouterInstance = () => {
 			location: {}
 		}),
 		pendingState: create(void 0),
-		currentLoaderState: create(emptyLoaderState),
 		scrollMapState: create({}),
 		contextState: create({}),
 		blockedRouteState: create({
 			from: "",
 			to: ""
 		}),
-		loaderStateRef: new Cell(emptyLoaderState),
+		isOptimisticLoading: create(false),
+		loaderState: create(emptyLoaderState),
 		loaderMap: /* @__PURE__ */ new Map(),
 		loadingPromises: /* @__PURE__ */ new Map()
 	};
@@ -606,6 +590,8 @@ var createRouterInstance = () => {
 			useScrollMap: () => useGlobalState(routerState.scrollMapState),
 			usePendingState: () => useGlobalState(routerState.pendingState),
 			useContextState: () => useGlobalState(routerState.contextState),
+			useOptimisticLoading: () => useGlobalState(routerState.isOptimisticLoading),
+			useLoaderState: () => useGlobalState(routerState.loaderState)[0],
 			useParams: () => getParamsObject(),
 			useNavigate: () => {
 				const { blockedRouteState } = routerState;
@@ -681,6 +667,9 @@ var useNavigation = () => {
 	}, [navigate]);
 };
 //#endregion
+//#region hooks/useLoaderState.ts
+var useLoaderState = router.hooks.useLoaderState;
+//#endregion
 //#region hooks/useApplyCustomAnimation.ts
 var useApplyCustomAnimation = (animationDuration) => {
 	useEffect(() => {
@@ -758,12 +747,13 @@ var EmptyBoundary = ({ children }) => children;
 var IS_MOBILE = isMobile();
 var MOBILE_CACHE_SIZE = 60;
 var DESKTOP_CACHE_SIZE = 150;
-var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated = false, spinner = true, defaultPreserveScroll = true, showFallbackOnAnimation = false, maxCacheSize = IS_MOBILE ? MOBILE_CACHE_SIZE : DESKTOP_CACHE_SIZE, defaultPrefetch = IS_MOBILE ? "viewport" : "hover", defaultHoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary }) => {
-	const { useRouteItemData, usePendingState } = router.hooks;
+var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated = false, optimisticSpinner = true, defaultPreserveScroll = true, defaultMinLoaderDuration = 0, maxCacheSize = IS_MOBILE ? MOBILE_CACHE_SIZE : DESKTOP_CACHE_SIZE, defaultPrefetch = IS_MOBILE ? "viewport" : "hover", defaultHoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary }) => {
+	const { useRouteItemData, usePendingState, useOptimisticLoading } = router.hooks;
 	const [routeItemData] = useRouteItemData();
-	const [pendingState] = usePendingState();
-	const loaderState = router.state.loaderStateRef.value;
-	const isLoading = Boolean(pendingState);
+	const [pendingRouteData] = usePendingState();
+	const [isOptimisticLoading] = useOptimisticLoading();
+	const loaderState = useLoaderState();
+	const isLoading = Boolean(pendingRouteData);
 	useNavigation();
 	useSetRouterConfig({
 		routes,
@@ -775,6 +765,7 @@ var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration,
 		defaultRetry,
 		defaultStaleTime,
 		defaultPreserveScroll,
+		defaultMinLoaderDuration,
 		maxCacheSize
 	});
 	useApplyCustomAnimation(animationDuration);
@@ -782,15 +773,12 @@ var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration,
 	usePreserveScroll(routeItemData);
 	const { routeItem, location } = routeItemData;
 	const showErrorElement = !isLoading && Boolean(loaderState.loaderError || loaderState.beforeLoadError);
-	const showSpinner = spinner && isAnimated && isLoading;
-	const loadingContent = !showErrorElement && isLoading;
-	if ((showFallbackOnAnimation || !isAnimated) && loadingContent) return renderElement(pendingState?.routeItem?.loaderFallback || defaultLoaderFallback);
-	if (!showFallbackOnAnimation && isAnimated && loadingContent) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {});
+	if (!showErrorElement && isLoading) return renderElement(pendingRouteData?.routeItem?.loaderFallback || defaultLoaderFallback);
 	if (!routeItem) return null;
-	if (showErrorElement) return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [renderElement(routeItem.errorElement || defaultErrorElement), showSpinner && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})] });
+	if (showErrorElement) return renderElement(routeItem.errorElement || defaultErrorElement);
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 		style: { viewTransitionName: "page" },
-		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ErrorBoundary, { children: renderElement(routeItem.element) }, location.pathname), showSpinner && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
+		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ErrorBoundary, { children: renderElement(routeItem.element) }, location.pathname), optimisticSpinner && isOptimisticLoading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
 	});
 };
 //#endregion
@@ -932,9 +920,6 @@ var Form = ({ children, action, onSuccess, onError, autoReset = true }) => {
 //#region hooks/useParams.ts
 var useParams = router.hooks.useParams;
 //#endregion
-//#region hooks/useLoaderState.ts
-var useLoaderState = () => router.state.loaderStateRef.value;
-//#endregion
 //#region hooks/useInvalidate.ts
 var useInvalidate = () => router.runtime.invalidate;
 //#endregion

package/dist/runtime/invalidate.d.ts

@@ -1,2 +1,2 @@
 import { type InvalidateOptions, InvalidateResult, RevalidateCache, RouterState } from '../types';
-export declare const createInvalidate: ({ routeItemDataState, loaderStateRef, loaderMap, currentLoaderState, contextState }: RouterState, revalidateCache: RevalidateCache) => (pathList?: string | string[], options?: InvalidateOptions) => Promise<InvalidateResult[]>;
+export declare const createInvalidate: ({ routeItemDataState, loaderState, loaderMap, contextState }: RouterState, revalidateCache: RevalidateCache) => (pathList?: string | string[], options?: InvalidateOptions) => Promise<InvalidateResult[]>;

package/dist/types.d.ts

@@ -1,6 +1,5 @@
 import { ComponentType, type CSSProperties, Dispatch, MouseEvent, ReactElement, ReactNode, Ref, SetStateAction } from 'react';
 import { Store, useGlobalState } from './create';
-import { Cell } from './cell';
 export declare const LAZY_MARKER: unique symbol;
 export type LazyComponent = {
     readonly [LAZY_MARKER]: true;
@@ -33,6 +32,7 @@ export type ClientRouteItem = {
     optimistic?: boolean;
     pollingInterval?: number;
     retry?: Retry;
+    minLoaderDuration?: number;
     preserveScroll?: boolean;
     beforeLoad?: BeforeLoad;
     afterLoad?: (arg: {
@@ -85,15 +85,15 @@ export type RouterProps = {
     routes: RouteItem[];
     isAnimated?: boolean;
     animationDuration?: number;
-    spinner?: boolean;
+    optimisticSpinner?: boolean;
     defaultPreserveScroll?: boolean;
     defaultRetry?: Retry;
     defaultStaleTime?: number;
     defaultLoaderFallback?: RenderElement;
     defaultErrorElement?: RenderElement;
-    showFallbackOnAnimation?: boolean;
     defaultPrefetch?: 'hover' | 'render' | 'viewport' | 'none';
     defaultHoverPrefetchDelay?: number;
+    defaultMinLoaderDuration?: number;
     maxCacheSize?: number;
     errorBoundary?: ComponentType<{
         children: ReactNode;
@@ -117,14 +117,14 @@ export type LoadingPromise = Promise<{
 export type RouterState = {
     routeItemDataState: Store<RouteItemData>;
     pendingState: Store<RouteItemData | undefined>;
-    currentLoaderState: Store<LoaderState>;
     scrollMapState: Store<Record<string, number>>;
     contextState: Store<Record<string, unknown>>;
     blockedRouteState: Store<{
         from: string;
         to: string;
     }>;
-    loaderStateRef: Cell<LoaderState>;
+    isOptimisticLoading: Store<boolean>;
+    loaderState: Store<LoaderState>;
     loaderMap: Map<string, LoaderStateItem>;
     loadingPromises: Map<string, LoadingPromise>;
 };
@@ -144,6 +144,8 @@ export type RouterType = {
         useScrollMap: () => ReturnType<typeof useGlobalState<Record<string, number>>>;
         usePendingState: () => ReturnType<typeof useGlobalState<RouteItemData | undefined>>;
         useContextState: () => ReturnType<typeof useGlobalState<Record<string, unknown>>>;
+        useOptimisticLoading: () => ReturnType<typeof useGlobalState<boolean>>;
+        useLoaderState: <T>() => LoaderState<T>;
         useParams: <T>() => T;
         useNavigate: () => (arg: Location | string | -1) => Promise<void>;
         useGetAction: (actionKey: string) => {

package/dist/utils/commitNavigation.d.ts

@@ -1,3 +1 @@
-import { Store } from '../create';
-import { Location, RouteItem, RouteItemData } from '../types';
-export declare const createCommitNavigation: (navigationExecutor: (arg: Location, routeItem: RouteItem | undefined) => void, routeItemDataState: Store<RouteItemData>) => (nextLocation: Location, routeItem: RouteItem | undefined) => void;
+export declare const commitNavigation: (callback: () => void) => void;

package/dist/utils/commitState.d.ts

@@ -1,2 +1,2 @@
 import { Location, RouteItem, RouterState } from '../types';
-export declare const createCommitState: ({ routeItemDataState, pendingState }: RouterState) => (nextLocation: Location, routeItem: RouteItem | undefined) => void;
+export declare const createCommitState: ({ routeItemDataState, pendingState, isOptimisticLoading }: RouterState) => (nextLocation: Location, routeItem: RouteItem | undefined) => void;

package/dist/utils/revalidateCache.d.ts

@@ -1,8 +1,2 @@
-import { RevalidateCacheArgs, RouterState } from '../types';
-export declare const createRevalidateCache: (routerState: RouterState) => ({ routeItem, pathname, search, signal }: RevalidateCacheArgs, retried?: number) => Promise<{
-    data: unknown;
-    error: null;
-} | {
-    data: null;
-    error: unknown;
-} | undefined>;
+import { LoadingPromise, RevalidateCacheArgs, RouterState } from '../types';
+export declare const createRevalidateCache: (routerState: RouterState) => ({ routeItem, pathname, search, signal }: RevalidateCacheArgs, retried?: number) => LoadingPromise;

package/dist/utils/utils.d.ts

@@ -4,3 +4,4 @@ export declare const getParamsObject: (nextItem?: RouteItem, nextPathname?: stri
 export declare const parseWindowLocation: (location: typeof window.location) => Location;
 export declare const comparePaths: (route: RouteItem, pathname: string) => boolean;
 export declare const isMobile: () => boolean;
+export declare const sleep: (ms: number) => Promise<unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {

package/dist/cell.d.ts

@@ -1,6 +0,0 @@
-export declare class Cell<T> {
-    private _value;
-    constructor(_value: T);
-    get value(): T;
-    set(action: T | ((prev: T) => T)): void;
-}