clear-react-router 2.0.5 → 2.0.6

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/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,14 +226,15 @@ 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 { loaderStateRef, 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
@@ -279,44 +281,47 @@ 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);
-		}
+		} 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({
+		await Promise.all([revalidateCache({
 			routeItem,
-			pathname: location.pathname,
-			search: location.search,
+			pathname: nextLocation.pathname,
+			search: nextLocation.search,
 			signal
-		});
+		}), getLoaderDurationPromise(routeItem, nextLocation)]);
 		if (seq !== navigationSeq) return;
-		polling(routeItem, location);
+		polling(routeItem, nextLocation);
 	};
 	const afterLoad = async (routeItem, params) => {
 		const { defaultAfterLoad } = routerConfig;
@@ -338,7 +343,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;
@@ -430,16 +435,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 evict = () => {
 		if (loaderMap.size <= routerConfig.maxCacheSize) return;
 		const oldestKey = loaderMap.keys().next().value;
@@ -456,7 +453,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);
@@ -566,6 +562,7 @@ var createRouterInstance = () => {
 			from: "",
 			to: ""
 		}),
+		isOptimisticLoading: create(false),
 		loaderStateRef: new Cell(emptyLoaderState),
 		loaderMap: /* @__PURE__ */ new Map(),
 		loadingPromises: /* @__PURE__ */ new Map()
@@ -606,6 +603,7 @@ var createRouterInstance = () => {
 			useScrollMap: () => useGlobalState(routerState.scrollMapState),
 			usePendingState: () => useGlobalState(routerState.pendingState),
 			useContextState: () => useGlobalState(routerState.contextState),
+			useOptimisticLoading: () => useGlobalState(routerState.isOptimisticLoading),
 			useParams: () => getParamsObject(),
 			useNavigate: () => {
 				const { blockedRouteState } = routerState;
@@ -758,12 +756,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 [pendingRouteData] = usePendingState();
+	const [isOptimisticLoading] = useOptimisticLoading();
 	const loaderState = router.state.loaderStateRef.value;
-	const isLoading = Boolean(pendingState);
+	const isLoading = Boolean(pendingRouteData);
 	useNavigation();
 	useSetRouterConfig({
 		routes,
@@ -775,6 +774,7 @@ var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration,
 		defaultRetry,
 		defaultStaleTime,
 		defaultPreserveScroll,
+		defaultMinLoaderDuration,
 		maxCacheSize
 	});
 	useApplyCustomAnimation(animationDuration);
@@ -782,15 +782,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

package/dist/types.d.ts

@@ -33,6 +33,7 @@ export type ClientRouteItem = {
     optimistic?: boolean;
     pollingInterval?: number;
     retry?: Retry;
+    minLoaderDuration?: number;
     preserveScroll?: boolean;
     beforeLoad?: BeforeLoad;
     afterLoad?: (arg: {
@@ -85,15 +86,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;
@@ -124,6 +125,7 @@ export type RouterState = {
         from: string;
         to: string;
     }>;
+    isOptimisticLoading: Store<boolean>;
     loaderStateRef: Cell<LoaderState>;
     loaderMap: Map<string, LoaderStateItem>;
     loadingPromises: Map<string, LoadingPromise>;
@@ -144,6 +146,7 @@ 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>>;
         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/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.6",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {