clear-react-router 1.9.2 → 1.9.4

package/README.md

@@ -31,6 +31,7 @@ It provides first-class support for:
 - **Prefetching** - Preload data on hover for instant navigation
 - **Lazy Loading** - Code-split your routes with dynamic imports for optimal performance
 - **Scroll Restoration** — Automatically saves and restores scroll position when navigating back to a page (preserves user's scroll position)
+- **Optimistic navigation** — Instantly renders stale cached data while fresh data is loaded in the background.
 - **Flexible API** - Use components or hooks as you prefer
 - **Browser History** - Full support for browser back/forward buttons
 - **Context-aware** - Pass and update context through routes
@@ -81,12 +82,13 @@ Normalizes route configuration. Extracts dynamic params, builds nested paths.
 | `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` |
 | `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 }` | `undefined` | Overrides the global cache revalidation retry policy for this route |
+| `retry` | `number \| { count: number; delay: number }` | Overrides the global cache revalidation retry policy for this route |
+| `optimistic` |  `boolean \| undefined` | Instant navigation using stale data while fresh data is loaded in the background |
 | `errorElement` | `ReactElement \| () => ReactElement` | Error fallback for the route. Overrides the global `defaultErrorElement` set in `Router` |
 | `staleTime` | `number` | Time in milliseconds before cached loader data is considered stale. Overrides Router.defaultStaleTime. If neither value is provided, cached data never expires |
 | `actions` | `({ params, context, invalidate, setContext }) => Record<string, (formData: FormData) => unknown \| Promise<unknown>>` | Defines route actions for data mutations. Actions receive `FormData`, can update context via `setContext`, and can invalidate cached loader data using the router-provided `invalidate` |
-| `pollingInterval` | `number \| undefined` | `undefined` | Polling interval (in milliseconds) for automatically revalidating data while the route is active |
-| `preserveScroll` | `boolean \| undefined` | `undefined` | Save and restore route scroll position when navigating between pages |
+| `pollingInterval` | `number \| undefined` | Polling interval (in milliseconds) for automatically revalidating data while the route is active |
+| `preserveScroll` | `boolean \| undefined` | Save and restore route scroll position when navigating between pages |
 
 Loader arguments:
 ```ts
@@ -105,6 +107,8 @@ Component for client-side navigation with prefetch support, active state detecti
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `to` | `string` | required | Target path |
+| `as` | `(props: ElementProps<T>) => ReactElement` | renders `<a>` | Render prop for using a custom element/component instead of the default `<a>`. Receives the computed isActive and isPending values, event handlers, and ref to attach to your own element |
+| `exact` | `boolean` | `false` | When `false`, the link is also considered active if the current URL starts with `to` (useful for nested routes) |
 | `prefetch` | `'hover' \| 'render' \| 'viewport' \| 'none'` | `Router` config | Override the global prefetch strategy |
 | `hoverPrefetchDelay` | `number` | `Router` config | Override the global hover delay |
 | `children` | `ReactNode` | required | Content to render inside the link |
@@ -112,13 +116,13 @@ Component for client-side navigation with prefetch support, active state detecti
 | `style` | `CSSProperties \| ({ isActive, isPending }) => CSSProperties` | `undefined` | Inline styles. Can be a function for dynamic styling |
 | `activeClassName` | `string` optional | `'active-link'` | Class name applied when the link matches the current URL |
 | `pendingClassName` | `string` optional | `'pending-link'` | Class name applied when the link's target is loading |
-| `onClick` | `() => void` | `undefined` | Callback fired before navigation |
+| `beforeNavigate` | `() => Promise<void> \| undefined` | `undefined` | Callback fired before navigation |
 
 **State values:**
 
 | State | Type | Description |
 |-------|------|-------------|
-| `isActive` | `boolean` | `true` when the link's `to` matches the current URL |
+| `isActive` | `boolean` | `true` when the link's `to` matches the current URL considering `exact` value |
 | `isPending` | `boolean` | `true` when the target route is currently loading (loader is running) |
 
 ### Prefetch Strategies
@@ -135,6 +139,22 @@ Component for client-side navigation with prefetch support, active state detecti
 ```tsx
 import { Router, Link } from 'clear-react-router';
 
+// Render a custom element/component via `as`. The function receives ref, event handlers, isActive/isPending and must render them itself
+import { Button } from '@mui/material';
+
+<Link
+  to="/dashboard"
+  as={({ isActive, isPending, ...props }) => (
+    <Button
+      {...props}
+      variant={isActive ? 'contained' : 'outlined'}
+      sx={{ opacity: isPending ? 0.5 : 1 }}
+    />
+  )}
+>
+  Dashboard
+</Link>
+
 // Global prefetch: hover with 100ms delay
 <Router routes={routes} prefetch="hover" hoverPrefetchDelay={100} />
 
@@ -162,6 +182,17 @@ import { Router, Link } from 'clear-react-router';
 <Link to="/profile" style={({ isActive }) => ({ fontWeight: isActive ? 'bold' : 'normal' })}>
   Profile
 </Link>
+
+// Use `beforeNavigate`
+<Link to="/details" beforeNavigate={saveDashboardData}>
+  Admin Panel
+</Link>
+
+// `exact={false}` — active for nested routes too
+// e.g. active when current URL is "/settings" or "/settings/profile"
+<Link to="/settings" exact={false}>
+  Settings
+</Link>
 ```
 **Important**: prefetch="render" should be used sparingly, as it preloads data immediately when the link is rendered, which may cause unnecessary network requests.
 

package/dist/components/Link.d.ts

@@ -1,19 +1,33 @@
-import { type CSSProperties, ReactNode, ComponentPropsWithoutRef } from 'react';
+import { type CSSProperties, ReactNode, MouseEvent, ReactElement, Ref } from 'react';
 import { RouterProps } from '../types';
 type States = {
     isActive: boolean;
     isPending: boolean;
 };
-type LinkProps = Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'className' | 'style'> & {
+type ElementProps<T extends HTMLElement = HTMLElement> = {
+    ref: Ref<T>;
+    href: string;
+    isActive: boolean;
+    isPending: boolean;
+    onClick(event: MouseEvent): void;
+    onMouseEnter(event: MouseEvent): void;
+    onMouseLeave(event: MouseEvent): void;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+};
+type LinkProps<T extends HTMLElement = HTMLAnchorElement> = {
     to: string;
-    children: ReactNode;
+    children?: ReactNode;
+    as?: (props: ElementProps<T>) => ReactElement;
     prefetch?: RouterProps['prefetch'];
     hoverPrefetchDelay?: number;
-    style?: CSSProperties | ((arg: States) => CSSProperties);
     className?: string | ((arg: States) => string);
     activeClassName?: string;
     pendingClassName?: string;
-    onClick?(): void;
+    beforeNavigate?(): Promise<void>;
+    style?: CSSProperties | ((arg: States) => CSSProperties);
+    exact?: boolean;
 };
-export declare const Link: ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, onClick, activeClassName, pendingClassName, }: LinkProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Link: <T extends HTMLElement = HTMLAnchorElement>({ children, to, as, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, exact, activeClassName, pendingClassName, }: LinkProps<T>) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export {};

package/dist/index.js

@@ -44,7 +44,7 @@ var createCommitState = ({ routeItemDataState, pendingState }) => (nextLocation,
 //#region constants.ts
 var emptyLoaderState = {};
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.132.0/helpers/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -54,7 +54,7 @@ function _typeof(o) {
 	}, _typeof(o);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.132.0/helpers/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -66,13 +66,13 @@ function toPrimitive(t, r) {
 	return ("string" === r ? String : Number)(t);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.132.0/helpers/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.132.0/helpers/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -113,13 +113,13 @@ var createCommitNavigation = (navigationExecutor, routeItemDataState) => (nextLo
 };
 //#endregion
 //#region utils/isCacheItemFresh.ts
-var createIsCacheItemFresh = (timestampMap) => ({ routeItem, pathname }) => {
+var createIsCacheItemFresh = (loaderMap) => ({ routeItem, pathname }) => {
 	if (!routeItem) return true;
-	const timestamp = timestampMap.get(pathname);
-	if (timestamp === void 0) return false;
+	const item = loaderMap.get(pathname);
+	if (item === void 0) return false;
 	const staleTime = routeItem.staleTime ?? routerConfig.defaultStaleTime;
 	if (staleTime === void 0) return true;
-	return Date.now() - timestamp <= staleTime;
+	return Date.now() - item.timestamp <= staleTime;
 };
 //#endregion
 //#region ../../node_modules/react/cjs/react-jsx-runtime.production.js
@@ -216,9 +216,9 @@ var findRoute = (pathname, includeAll) => {
 var navigationSeq = 0;
 var interval = 0;
 var createNavigate = (routerState, revalidateCache) => {
-	const { loaderStateRef, scrollMapState, pendingState, contextState, timestampMap, routeItemDataState } = routerState;
+	const { loaderStateRef, scrollMapState, pendingState, contextState, loaderMap, routeItemDataState } = routerState;
 	const commitNavigation = createCommitNavigation(createCommitState(routerState), routeItemDataState);
-	const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
+	const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
 	const getContext = () => ({
 		context: contextState.getState(),
 		setContext: contextState.setState
@@ -265,14 +265,23 @@ var createNavigate = (routerState, revalidateCache) => {
 				[prevPathname]: scrollPosition
 			};
 		});
-		const pendingShouldExist = routeItem?.loader && !isCacheItemFresh({
-			routeItem,
-			pathname: location.pathname
-		});
-		pendingState.setState(pendingShouldExist ? {
-			routeItem,
-			location
-		} : void 0);
+		if (routeItem?.optimistic && loaderMap.has(location.pathname)) {
+			routeItemDataState.setState({
+				routeItem,
+				location
+			});
+			const currentLoaderState = loaderMap.get(location.pathname)?.state;
+			if (currentLoaderState) loaderStateRef.set(currentLoaderState);
+		} else {
+			const pendingShouldExist = routeItem?.loader && !isCacheItemFresh({
+				routeItem,
+				pathname: location.pathname
+			});
+			pendingState.setState(pendingShouldExist ? {
+				routeItem,
+				location
+			} : void 0);
+		}
 	};
 	const afterEachLoad = (routeItem) => {
 		if (!routeItem?.pollingInterval) return;
@@ -319,10 +328,10 @@ var createNavigate = (routerState, revalidateCache) => {
 //#endregion
 //#region runtime/invalidate.ts
 var redirect = () => Promise.resolve();
-var createInvalidate = ({ routeItemDataState, loaderStateRef, timestampMap, currentLoaderState, contextState }, revalidateCache) => {
+var createInvalidate = ({ routeItemDataState, loaderStateRef, loaderMap, currentLoaderState, contextState }, revalidateCache) => {
 	const invalidatePath = async (routeItem, pathname, options) => {
 		const routePathname = routeItemDataState.getState().location.pathname;
-		timestampMap.delete(pathname);
+		loaderMap.delete(pathname);
 		const params = getParamsObject();
 		try {
 			if (routeItem?.beforeLoad && options?.withBeforeLoad) {
@@ -359,7 +368,7 @@ var createInvalidate = ({ routeItemDataState, loaderStateRef, timestampMap, curr
 		const routeItem = findRoute(pathname);
 		if (!routeItem) return [];
 		const pathnameArray = [];
-		for (const [key] of timestampMap) if (comparePaths(routeItem, key)) pathnameArray.push(key);
+		for (const [key] of loaderMap) if (comparePaths(routeItem, key)) pathnameArray.push(key);
 		const currentResults = await Promise.all(pathnameArray.map((pathname) => invalidatePath(routeItem, pathname, options)));
 		if (!options?.withChildren || !routeItem.children?.length) return currentResults;
 		const childResults = await Promise.all(routeItem.children.map((child) => invalidateItem(`${pathname}${child.path}`, options)));
@@ -385,7 +394,6 @@ var createPrefetch = (revalidateCache) => async (pathname) => {
 };
 //#endregion
 //#region utils/revalidateCache.ts
-var loaderMapRef = {};
 var loadingPromises = /* @__PURE__ */ new Map();
 var isObjectRetry = (arg) => typeof arg === "object";
 var createRetry = (arg) => {
@@ -406,16 +414,17 @@ var getRetry = (routeItem) => {
 };
 var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var createRevalidateCache = (routerState) => {
-	const { loaderStateRef, timestampMap, contextState } = routerState;
+	const { loaderStateRef, contextState, loaderMap } = routerState;
 	const revalidateCache = async ({ routeItem, pathname, search = "" }, retried = 0) => {
 		if (!routeItem?.loader) return;
-		const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
+		const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
 		if (loadingPromises.has(pathname)) return loadingPromises.get(pathname);
 		if (isCacheItemFresh({
 			routeItem,
 			pathname
 		})) {
-			loaderStateRef.set(loaderMapRef[pathname]);
+			const item = loaderMap.get(pathname);
+			if (item?.state) loaderStateRef.set(item.state);
 			return;
 		}
 		const promise = (async () => {
@@ -431,13 +440,15 @@ var createRevalidateCache = (routerState) => {
 					setContext,
 					searchParams
 				});
-				timestampMap.set(`${pathname}${search}`, Date.now());
 				loaderStateRef.set((prev) => ({
 					...prev,
 					data: result,
 					loaderError: null
 				}));
-				loaderMapRef[`${pathname}${search}`] = loaderStateRef.value;
+				loaderMap.set(`${pathname}${search}`, {
+					state: loaderStateRef.value,
+					timestamp: Date.now()
+				});
 				return {
 					data: result,
 					error: null
@@ -506,7 +517,7 @@ var createRouterInstance = () => {
 			to: ""
 		}),
 		loaderStateRef: new Cell(emptyLoaderState),
-		timestampMap: /* @__PURE__ */ new Map()
+		loaderMap: /* @__PURE__ */ new Map()
 	};
 	const revalidateCache = createRevalidateCache(routerState);
 	const invalidate = createInvalidate(routerState, revalidateCache);
@@ -745,12 +756,13 @@ var useLocation = () => {
 };
 //#endregion
 //#region components/Link.tsx
-var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, onClick, activeClassName = "active-link", pendingClassName = "pending-link" }) => {
+var defaultAs = ({ isActive, isPending, ...props }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", { ...props });
+var Link = ({ children, to, as = defaultAs, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, exact = false, activeClassName = "active-link", pendingClassName = "pending-link" }) => {
 	const isPending = useIsRoutePending(to);
 	const { pathname } = useLocation();
 	const navigate = useNavigate();
 	const timeout = useRef(0);
-	const ref = useRef(null);
+	const elementRef = useRef(null);
 	const { prefetch: configPrefetch, hoverPrefetchDelay: configPrefetchDelay } = routerConfig;
 	const prefetch = prefetchLink || configPrefetch;
 	const prefetchDelay = hoverPrefetchDelay ?? configPrefetchDelay;
@@ -778,17 +790,19 @@ var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, classNam
 	}, [prefetch, to]);
 	useEffect(() => {
 		if (prefetch !== "viewport") return;
-		const element = ref.current;
+		const element = elementRef.current;
+		if (!element) return;
 		const observer = new IntersectionObserver(async () => {
 			await router.runtime.prefetch(to);
 			observer.disconnect();
 		});
-		if (element) observer.observe(element);
-		return () => {
-			if (element) observer.disconnect();
-		};
+		observer.observe(element);
+		return () => observer.disconnect();
 	}, [prefetch, to]);
-	const isActive = to === pathname;
+	useEffect(() => () => {
+		if (timeout.current) clearTimeout(timeout.current);
+	}, []);
+	const isActive = to === "/" ? pathname === "/" : exact ? pathname === to : pathname === to || pathname?.startsWith(`${to}/`);
 	const normalizedClassName = typeof className === "function" ? className({
 		isActive,
 		isPending
@@ -803,18 +817,21 @@ var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, classNam
 		normalizedClassName
 	].filter(Boolean).join(" ");
 	const clickHandler = async (event) => {
+		if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
 		event.preventDefault();
-		onClick?.();
+		await beforeNavigate?.();
 		await navigate(to);
 	};
-	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", {
+	return as({
+		ref: elementRef,
 		href: to,
-		ref,
 		style: normalizedStyle,
 		className: resultClassName,
 		onClick: clickHandler,
 		onMouseEnter,
 		onMouseLeave,
+		isActive,
+		isPending,
 		children
 	});
 };

package/dist/runtime/invalidate.d.ts

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

package/dist/types.d.ts

@@ -25,6 +25,7 @@ export type ClientRouteItem = {
     fallback?: RenderElement;
     children?: ClientRouteItem[];
     staleTime?: number;
+    optimistic?: boolean;
     pollingInterval?: number;
     retry?: Retry;
     preserveScroll?: boolean;
@@ -94,6 +95,10 @@ export type RouterProps = {
     afterLoad?: ClientRouteItem['afterLoad'];
     context?: Record<string, unknown>;
 };
+export type LoaderStateItem = {
+    state: LoaderState;
+    timestamp: number;
+};
 export type RouterState = {
     routeItemDataState: Store<RouteItemData>;
     pendingState: Store<RouteItemData | undefined>;
@@ -105,7 +110,7 @@ export type RouterState = {
         to: string;
     }>;
     loaderStateRef: Cell<LoaderState>;
-    timestampMap: Map<string, number>;
+    loaderMap: Map<string, LoaderStateItem>;
 };
 export type RouterType = {
     state: Omit<RouterState, 'timestampMap'>;

package/dist/utils/isCacheItemFresh.d.ts

@@ -1,5 +1,5 @@
-import type { RouteItem } from '../types';
-export declare const createIsCacheItemFresh: (timestampMap: Map<string, number>) => ({ routeItem, pathname }: {
+import { LoaderStateItem, RouteItem } from '../types';
+export declare const createIsCacheItemFresh: (loaderMap: Map<string, LoaderStateItem>) => ({ routeItem, pathname }: {
     routeItem?: RouteItem;
     pathname: string;
 }) => boolean;

package/package.json

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