clear-react-router 1.8.4 → 1.8.6

package/README.md

@@ -70,7 +70,7 @@ It provides first-class support for:
 
 ### `createRouter(routes)`
 
-Normalizes route configuration, extracts dynamic params, builds nested paths.
+Normalizes route configuration. Extracts dynamic params, builds nested paths.
 
 | Property | Type | Description |
 |----------|------|-------------|
@@ -88,14 +88,26 @@ Normalizes route configuration, extracts dynamic params, builds nested paths.
 
 ### `Link`
 
-Component for client-side navigation with prefetch support.
+Component for client-side navigation with prefetch support, active state detection, and pending state styling.
 
-| Prop | Type | Default |
-|------|------|---------|
-| `to` | `string` | required |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `string` | required | Target path |
 | `prefetch` | `'hover' \| 'render' \| 'viewport' \| 'none'` | `Router` config | Override the global prefetch strategy |
 | `hoverPrefetchDelay` | `number` | `Router` config | Override the global hover delay |
-| `children` | `ReactElement` | required | Content to render inside the link |
+| `children` | `ReactNode` | required | Content to render inside the link |
+| `className` | `string \| ({ isActive, isPending }) => string` | `undefined` | CSS class name(s). Can be a function for dynamic styling |
+| `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 |
+
+**State values:**
+
+| State | Type | Description |
+|-------|------|-------------|
+| `isActive` | `boolean` | `true` when the link's `to` matches the current URL |
+| `isPending` | `boolean` | `true` when the target route is currently loading (loader is running) |
 
 ### Prefetch Strategies
 
@@ -123,6 +135,21 @@ import { Router, Link } from 'clear-react-router';
 <Link to="/admin" prefetch="none">
   Admin Panel
 </Link>
+
+// With custom active/pending classes
+<Link to="/settings" activeClassName="active-nav-link" pendingClassName="loading-nav-link">
+  Settings
+</Link>
+
+// With dynamic className
+<Link to="/dashboard" className={({ isActive, isPending }) => isActive ? 'text-blue-600' : isPending ? 'text-gray-400' : 'text-gray-600'}>
+  Dashboard
+</Link>
+
+// With dynamic style
+<Link to="/profile" style={({ isActive }) => ({ fontWeight: isActive ? 'bold' : 'normal' })}>
+  Profile
+</Link>
 ```
 **Important**: prefetch="render" should be used sparingly, as it preloads data immediately when the link is rendered, which may cause unnecessary network requests.
 
@@ -557,6 +584,14 @@ await invalidate('/posts', { withBeforeLoad: true });
 await invalidate(['/posts', '/users'], { withBeforeLoad: true });
 ```
 
+#### Returns
+
+An array of objects with the following structure:
+```ts
+{ path: string; data: unknown; error: unknown }
+```
+Each object represents a revalidated route, where `path` is the route pathname, `data` is the revalidated loader result, and `error` is the loader error, if any.
+
 #### Notes
 
 * **Only routes that already have cached data are revalidated.**

package/dist/components/Link.d.ts

@@ -1,13 +1,19 @@
-import { type ReactElement, type MouseEvent, type CSSProperties } from 'react';
+import { type CSSProperties, ReactNode, ComponentPropsWithoutRef } from 'react';
 import { RouterProps } from '../types';
-type LinkProps = {
+type States = {
+    isActive: boolean;
+    isPending: boolean;
+};
+type LinkProps = Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'className' | 'style'> & {
     to: string;
-    children: ReactElement<{
-        onClick: (e: MouseEvent) => void;
-        style: CSSProperties;
-    }>;
+    children: ReactNode;
     prefetch?: RouterProps['prefetch'];
     hoverPrefetchDelay?: number;
+    style?: CSSProperties | ((arg: States) => CSSProperties);
+    className?: string | ((arg: States) => string);
+    activeClassName?: string;
+    pendingClassName?: string;
+    onClick?(): void;
 };
-export declare const Link: ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay }: LinkProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Link: ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, onClick, activeClassName, pendingClassName, }: LinkProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/hooks/useInvalidate.d.ts

@@ -1 +1 @@
-export declare const useInvalidate: () => (pathList?: string | string[], options?: import("../types").InvalidateOptions) => Promise<void>;
+export declare const useInvalidate: () => (pathList?: string | string[], options?: import("../types").InvalidateOptions) => Promise<import("../types").InvalidateResult[]>;

package/dist/hooks/useIsRoutePending.d.ts

@@ -0,0 +1 @@
+export declare const useIsRoutePending: (routePath: string) => boolean;

package/dist/index.js

@@ -212,7 +212,7 @@ var findRoute = (pathname, includeAll) => {
 //#region runtime/navigate.ts
 var navigationSeq = 0;
 var createNavigate = (routerState, revalidateCache) => {
-	const { loaderStateRef, scrollMapState, prevPathnameRef, loaderFallbackState, isLoadingState, contextState, timestampMap } = routerState;
+	const { loaderStateRef, scrollMapState, prevPathnameRef, loaderFallbackState, isLoadingState, contextState, timestampMap, pendingPathRef } = routerState;
 	const commitNavigation = createCommitNavigation(createCommitState(routerState), prevPathnameRef);
 	const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
 	const getContext = () => ({
@@ -269,10 +269,12 @@ var createNavigate = (routerState, revalidateCache) => {
 	const loader = async (routeItem, location) => {
 		if (!routeItem?.loader) return;
 		isLoadingState.setState(true);
+		pendingPathRef.set(location.pathname);
 		await revalidateCache({
 			routeItem,
 			pathname: location.pathname
 		});
+		pendingPathRef.set("");
 	};
 	const afterLoad = async (routeItem, params) => {
 		const { afterLoad } = routerConfig;
@@ -328,27 +330,30 @@ var createInvalidate = ({ routeItemDataState, loaderStateRef, timestampMap, curr
 				beforeLoadError: error
 			}));
 		}
-		await revalidateCache({
+		const result = await revalidateCache({
 			routeItem,
 			pathname
 		});
 		if (pathname === routePathname) currentLoaderState.setState(loaderStateRef.value);
+		return {
+			path: pathname,
+			...result
+		};
 	};
 	const invalidateItem = async (pathname, options) => {
 		const routeItem = findRoute(pathname);
-		if (!routeItem) return;
+		if (!routeItem) return [];
 		const pathnameArray = [];
 		for (const [key] of timestampMap) if (comparePaths(routeItem, key)) pathnameArray.push(key);
-		await Promise.all(pathnameArray.map((pathname) => invalidatePath(routeItem, pathname, options)));
-		if (options?.withChildren && routeItem.children?.length) {
-			const childPathList = routeItem.children.map((el) => el.path);
-			await Promise.all(childPathList.map((el) => invalidateItem(`${pathname}${el}`, options)));
-		}
+		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)));
+		return [...currentResults, ...childResults.flat()];
 	};
 	return async (pathList, options) => {
 		const routePathname = routeItemDataState.getState().location.pathname;
 		const pathnameList = Array.isArray(pathList) ? pathList : pathList ? [pathList] : [routePathname];
-		await Promise.all(pathnameList.map((pathname) => invalidateItem(pathname, options)));
+		return (await Promise.all(pathnameList.map((pathname) => invalidateItem(pathname, options)))).flat();
 	};
 };
 //#endregion
@@ -383,18 +388,15 @@ var getRetry = (routeItem) => {
 };
 var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var createRevalidateCache = (routerState) => {
+	const { loaderStateRef, timestampMap, contextState } = routerState;
 	const revalidateCache = async ({ routeItem, pathname }, retried = 0) => {
 		if (!routeItem?.loader) return;
-		const isCacheItemFresh = createIsCacheItemFresh(routerState.timestampMap);
-		const { loaderStateRef, timestampMap, contextState } = routerState;
+		const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
 		if (loadingPromises.has(pathname)) return loadingPromises.get(pathname);
 		if (isCacheItemFresh({
 			routeItem,
 			pathname
-		})) {
-			loaderStateRef.set(loaderMapRef[pathname]);
-			return;
-		}
+		})) loaderStateRef.set(loaderMapRef[pathname]);
 		const promise = (async () => {
 			if (!routeItem?.loader) return;
 			try {
@@ -413,6 +415,10 @@ var createRevalidateCache = (routerState) => {
 					loaderError: null
 				}));
 				loaderMapRef[pathname] = loaderStateRef.value;
+				return {
+					data: result,
+					error: null
+				};
 			} catch (error) {
 				const retry = getRetry(routeItem);
 				if (retry && retry.count > retried) {
@@ -422,11 +428,21 @@ var createRevalidateCache = (routerState) => {
 						routeItem,
 						pathname
 					}, retried + 1);
-				} else loaderStateRef.set((prev) => ({
-					...prev,
-					data: null,
-					loaderError: error
-				}));
+					return {
+						data: null,
+						error
+					};
+				} else {
+					loaderStateRef.set((prev) => ({
+						...prev,
+						data: null,
+						loaderError: error
+					}));
+					return {
+						data: null,
+						error
+					};
+				}
 			} finally {
 				loadingPromises.delete(pathname);
 			}
@@ -471,6 +487,7 @@ var createRouterInstance = () => {
 		}),
 		loaderStateRef: new Cell(emptyLoaderState),
 		prevPathnameRef: new Cell(""),
+		pendingPathRef: new Cell(""),
 		timestampMap: /* @__PURE__ */ new Map()
 	};
 	const revalidateCache = createRevalidateCache(routerState);
@@ -505,7 +522,8 @@ var createRouterInstance = () => {
 			scrollMapState: routerState.scrollMapState,
 			contextState: routerState.contextState,
 			blockedRouteState: routerState.blockedRouteState,
-			prevPathnameRef: routerState.prevPathnameRef
+			prevPathnameRef: routerState.prevPathnameRef,
+			pendingPathRef: routerState.pendingPathRef
 		},
 		runtime: {
 			navigate,
@@ -711,17 +729,26 @@ var Router = ({ routes, beforeLoad, afterLoad, animationDuration, isAnimated = f
 	});
 };
 //#endregion
+//#region hooks/useIsRoutePending.ts
+var useIsRoutePending = (routePath) => {
+	const { hooks: { useIsLoading }, state: { pendingPathRef } } = router;
+	const [isPending] = useIsLoading();
+	return isPending && pendingPathRef.value === routePath;
+};
+//#endregion
 //#region hooks/useNavigate.ts
 var useNavigate = router.hooks.useNavigate;
 //#endregion
 //#region components/Link.tsx
-var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay }) => {
-	const { prefetch: configPrefetch, hoverPrefetchDelay: configPrefetchDelay } = routerConfig;
-	const prefetch = prefetchLink || configPrefetch;
-	const prefetchDelay = hoverPrefetchDelay ?? configPrefetchDelay;
+var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, onClick, 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 { prefetch: configPrefetch, hoverPrefetchDelay: configPrefetchDelay } = routerConfig;
+	const prefetch = prefetchLink || configPrefetch;
+	const prefetchDelay = hoverPrefetchDelay ?? configPrefetchDelay;
 	const onMouseEnter = useCallback(() => {
 		if (prefetch !== "hover" || !prefetchDelay) return;
 		if (timeout.current) clearTimeout(timeout.current);
@@ -756,10 +783,31 @@ var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay }) => {
 			if (element) observer.disconnect();
 		};
 	}, [prefetch, to]);
+	const isActive = to === pathname;
+	const normalizedClassName = typeof className === "function" ? className({
+		isActive,
+		isPending
+	}) : className;
+	const normalizedStyle = typeof style === "function" ? style({
+		isActive,
+		isPending
+	}) : style;
+	const resultClassName = [
+		isActive && activeClassName,
+		isPending && pendingClassName,
+		normalizedClassName
+	].filter(Boolean).join(" ");
+	const clickHandler = async (event) => {
+		event.preventDefault();
+		onClick?.();
+		await navigate(to);
+	};
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", {
+		href: to,
 		ref,
-		style: { cursor: "pointer" },
-		onClick: () => navigate(to),
+		style: normalizedStyle,
+		className: resultClassName,
+		onClick: clickHandler,
 		onMouseEnter,
 		onMouseLeave,
 		children

package/dist/runtime/invalidate.d.ts

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

package/dist/types.d.ts

@@ -34,7 +34,7 @@ export type ClientRouteItem = {
     actions?: (arg: {
         context: Record<string, unknown>;
         params: Record<string, string>;
-        invalidate: (path?: string) => Promise<void>;
+        invalidate: (path?: string) => Promise<InvalidateResult[]>;
         setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
     }) => Record<string, (arg: FormData) => Promise<unknown> | Promise<void> | void | unknown>;
 };
@@ -103,13 +103,14 @@ export type RouterState = {
     }>;
     loaderStateRef: Cell<LoaderState>;
     prevPathnameRef: Cell<string>;
+    pendingPathRef: Cell<string>;
     timestampMap: Map<string, number>;
 };
 export type RouterType = {
     state: Omit<RouterState, 'loaderStateRef' | 'timestampMap'>;
     runtime: {
         navigate(arg: Location): Promise<void>;
-        invalidate(pathList?: string | string[], options?: InvalidateOptions): Promise<void>;
+        invalidate(pathList?: string | string[], options?: InvalidateOptions): Promise<InvalidateResult[]>;
         prefetch(pathname: string): Promise<void>;
     };
     hooks: {
@@ -127,7 +128,7 @@ export type RouterType = {
         useNavigate: () => (arg: Location | string | -1) => Promise<void>;
         useGetAction: (actionKey: string) => {
             currentAction: (arg: FormData) => Promise<unknown> | Promise<void> | void | unknown;
-            invalidate: (pathList?: string | string[], options?: InvalidateOptions) => Promise<void>;
+            invalidate: (pathList?: string | string[], options?: InvalidateOptions) => Promise<InvalidateResult[]>;
         };
         useRestoreScroll: () => () => void;
         useAction: (action: string, options?: Options) => (arg: FormData) => Promise<void>;
@@ -137,9 +138,16 @@ export type InvalidateOptions = {
     withChildren?: boolean;
     withBeforeLoad?: boolean;
 };
-export type RevalidateCache = ({ routeItem, pathname }: RevalidateCacheArgs) => Promise<unknown> | undefined;
+export type RevalidateCache = ({ routeItem, pathname, }: RevalidateCacheArgs) => Promise<{
+    data: unknown;
+    error: unknown;
+}>;
 export type Options = Partial<{
     onSuccess: (args: unknown) => void;
     onError: (args: unknown) => void;
 }> | undefined;
+export type InvalidateResult = {
+    path: string;
+    data: unknown;
+};
 export {};

package/package.json

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