clear-react-router 1.2.1 → 1.2.3

package/README.md

@@ -25,9 +25,9 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 |----------|------|-------------|
 | `path` | `string` | Route path, e.g., `/user/:userId` |
 | `element` | `ReactElement \| () => ReactElement \| LazyComponent` | Component to render |
-| `loader` | `() => Promise<unknown>` | Fetch data |
-| `beforeLoad` | `({ context, redirect }) => Promise<void>` | Auth checks and redirects. `redirect` is provided by the router |
-| `afterLoad` | `(context) => Promise<void>` | Analytics, side effects |
+| `loader` | `({ params, context }) => Promise<unknown>` | Fetch data using route params and context |
+| `beforeLoad` | `({ params, context, redirect }) => Promise<unknown> \| undefined` | Auth checks and redirects. `redirect` is provided by the router |
+| `afterLoad` | `({ params, context }) => Promise<void>` | Analytics, side effects after data is loaded |
 | `fallback` | `ReactElement \| () => ReactElement` | Loading fallback (for lazy loading) |
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback (for loader) |
 | `errorElement` | `ReactElement \| () => ReactElement` | Error fallback |
@@ -86,6 +86,38 @@ const routes = createRouter([
 ]);
 ```
 
+### Usage with Parameters
+
+The `loader`, `beforeLoad`, and `afterLoad` hooks receive `params` (extracted from the URL) and `context` as arguments. This allows you to handle route-specific logic directly in the route configuration, keeping your components focused on rendering.
+
+```
+const routes = createRouter([
+  {
+    path: '/user/:userId',
+    element: <UserProfile />,
+    loader: async ({ params, context }) => {
+      // params.userId is available from the URL
+      const user = await fetchUser(params.userId);
+      return { user };
+    },
+    beforeLoad: async ({ params, context, redirect }) => {
+      // Authentication check
+      if (!context.isAuthorized) {
+        return redirect({ pathname: '/login' });
+      }
+      // Validate parameter
+      if (!params.userId || !isValidUserId(params.userId)) {
+        return redirect({ pathname: '/users' });
+      }
+    },
+    afterLoad: ({ params, context }) => {
+      // Analytics or side effects
+      console.log(`User ${params.userId} loaded`);
+    },
+  },
+]);
+```
+
 ## Hooks
 
 ### `useNavigate()`
@@ -111,8 +143,10 @@ console.log(state); // { userId: 123 }
 
 Returns route parameters object.
 
+```
 const params = useParams<{ userId: string }>();
 // URL: /user/123 → params.userId === '123'
+```
 
 ### `useLocation()`
 
@@ -124,6 +158,9 @@ const { pathname, search, state } = useLocation();
 ### `useLoaderState()`
 
 Returns loaderState from current route's loader.
+```
+const state = useLoaderState();
+```
 
 ### `useBlocker(callback)`
 
@@ -173,6 +210,7 @@ const onSave = useCallback(() => {
 // Auto-save when user tries to close/reload the page
 useBeforeUnload(text ? onSave : undefined);
 ```
+> **Note:** Pass `undefined` to disable the handler (e.g., if there is no changes).
 
 ### `useRouterContext()`
 
@@ -244,5 +282,5 @@ For older browsers, the router gracefully falls back to regular navigation witho
 - React 16.6+ (for React.lazy and Suspense)
 - Use `default` export for your lazy-loaded components
 
-## License
-MIT
+ ## License
+ MIT

package/dist/hooks/useHandleNavigation.d.ts

@@ -1,14 +1,15 @@
-import type { BlockerState, Location, RouteItem, UpdateBlockedRouteProps } from '../types/global.ts';
+import type { BlockerState, Location, RevalidateCacheArgs, RouteItem, UpdateBlockedRouteProps } from '../types/global';
 type UseHandleNavigation = {
     routeList: RouteItem[];
     setLocation: (arg: Location) => void;
     context: Record<string, unknown>;
-    revalidateCache(routeItem?: RouteItem, isCurrentRoute?: boolean): Promise<void>;
+    revalidateCache(arg: RevalidateCacheArgs): Promise<void>;
     isAnimated: boolean;
 };
 export declare const useHandleNavigation: ({ setLocation, routeList, context, revalidateCache, isAnimated, }: UseHandleNavigation) => {
     blockerState: BlockerState;
     updateLocation: (nextLocation: Location) => Promise<void>;
     updateBlockedRoute: ({ type, payload }: UpdateBlockedRouteProps) => void;
+    beforeLoadError: boolean;
 };
 export {};

package/dist/hooks/useLoader.d.ts

@@ -1,8 +1,13 @@
-import type { RouteItem } from '../types/global.ts';
-export declare const useLoader: (routeList: RouteItem[]) => {
+import type { RevalidateCacheArgs, RouteItem } from '../types/global';
+type UseLoaderParams = {
+    routeList: RouteItem[];
+    context: Record<string, unknown>;
+};
+export declare const useLoader: ({ routeList, context }: UseLoaderParams) => {
     loaderCache: unknown;
     loaderError: boolean;
     prefetchLoader: (pathname: string) => Promise<void>;
-    revalidateCache: (routeItem?: RouteItem, isCurrentRoute?: boolean) => Promise<void>;
+    revalidateCache: ({ routeItem, isCurrentRoute, pathname }: RevalidateCacheArgs) => Promise<void>;
     isLoading: boolean;
 };
+export {};

package/dist/index.js

@@ -98,10 +98,10 @@ var parseClientRouteItem = (el, parentParams = [], parentPath = "") => {
 	}, ...el.children?.flatMap((child) => parseClientRouteItem(child, currentParams, path)) || []];
 };
 var createRouter = (clientList) => clientList.flatMap((el) => parseClientRouteItem(el, []));
-var getParamsObject = (params) => {
-	const { pathname } = window.location;
+var getParamsObject = ({ routeItem, pathname }) => {
+	if (!routeItem?.params) return {};
 	const split = pathname.split("/");
-	return (params || []).map((el) => ({
+	return (routeItem.params || []).map((el) => ({
 		index: split.findIndex((item) => item === el.key),
 		value: el.value
 	})).reduce((acc, cur) => ({
@@ -135,6 +135,7 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 		from: "",
 		to: ""
 	});
+	const [beforeLoadError, setBeforeLoadError] = useState(false);
 	const prevPathname = useRef("");
 	const navigationSeq = useRef(0);
 	const navigation = useCallback((nextLocation) => {
@@ -151,31 +152,53 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 		}
 		else navigation(nextLocation);
 	}, [navigation]);
-	const setNextLocation = useCallback(async (nextLocation, isFirstCall) => {
+	const navigationHandler = useCallback(async (nextLocation, isFirstCall) => {
 		navigationSeq.current = navigationSeq.current + 1;
 		const seq = navigationSeq.current;
 		const nextItem = routeList.find((el) => comparePaths(el, nextLocation.pathname));
-		if (nextItem?.beforeLoad) await nextItem.beforeLoad({
-			context,
-			redirect: setNextLocation
+		const params = getParamsObject({
+			routeItem: nextItem,
+			pathname: nextLocation.pathname
 		});
+		if (nextItem?.beforeLoad) try {
+			await nextItem.beforeLoad({
+				context,
+				redirect: navigationHandler,
+				params
+			});
+		} catch {
+			setBeforeLoadError(true);
+			transitionedNavigation({
+				nextLocation,
+				isAnimated: false
+			});
+			return;
+		}
 		if (seq !== navigationSeq.current) return;
-		await revalidateCache(nextItem, true);
+		await revalidateCache({
+			routeItem: nextItem,
+			isCurrentRoute: true,
+			pathname: nextLocation.pathname
+		});
 		if (seq !== navigationSeq.current) return;
 		transitionedNavigation({
 			nextLocation,
-			isAnimated,
-			isFirstCall
+			isFirstCall,
+			isAnimated
+		});
+		setBeforeLoadError(false);
+		if (nextItem?.afterLoad) await nextItem.afterLoad({
+			context,
+			params
 		});
-		if (nextItem?.afterLoad) await nextItem.afterLoad(context);
 	}, [
 		context,
-		isAnimated,
 		revalidateCache,
 		routeList,
-		transitionedNavigation
+		transitionedNavigation,
+		isAnimated
 	]);
-	const setNextLocationRef = useLatest(setNextLocation);
+	const setNextLocationRef = useLatest(navigationHandler);
 	const updateBlockedRoute = useCallback(({ type, payload = "" }) => setBlockedRoute((prevState) => {
 		if (prevState.from === payload && type === "charge") return prevState;
 		if (payload && prevState.from !== payload && type === "charge") return {
@@ -226,26 +249,33 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 			return "unblocked";
 		}, [blockedRoute]),
 		updateLocation,
-		updateBlockedRoute
+		updateBlockedRoute,
+		beforeLoadError
 	};
 };
 //#endregion
 //#region hooks/useLoader.ts
-var useLoader = (routeList) => {
+var useLoader = ({ routeList, context }) => {
 	const [loaderCache, setLoaderCache] = useState();
 	const [loaderError, setLoaderError] = useState(false);
 	const [isLoading, setIsLoading] = useState(false);
 	const cacheTimestampsRef = useRef({});
 	const loaderCacheRef = useRef({});
-	const isCacheItemFresh = useCallback((routeItem) => {
+	const isCacheItemFresh = useCallback(({ routeItem, pathname }) => {
 		if (!routeItem) return true;
-		const currentCacheTimestamp = cacheTimestampsRef.current[routeItem.path];
+		const currentCacheTimestamp = cacheTimestampsRef.current[pathname];
 		return Boolean(currentCacheTimestamp && Date.now() - currentCacheTimestamp < (routeItem.staleTime || 0));
 	}, []);
-	const revalidateCache = useCallback(async (routeItem, isCurrentRoute) => {
+	const revalidateCache = useCallback(async ({ routeItem, isCurrentRoute, pathname }) => {
 		if (!routeItem?.loader) return;
-		if (isCacheItemFresh(routeItem) && isCurrentRoute) setLoaderCache(loaderCacheRef.current[routeItem.path]);
-		if (isCacheItemFresh(routeItem)) return;
+		if (isCacheItemFresh({
+			routeItem,
+			pathname
+		}) && isCurrentRoute) setLoaderCache(loaderCacheRef.current[pathname]);
+		if (isCacheItemFresh({
+			routeItem,
+			pathname
+		})) return;
 		if (isCurrentRoute) setIsLoading(true);
 		loaderCacheRef.current = Object.keys(loaderCacheRef.current).filter((el) => el !== routeItem.path).reduce((acc, cur) => ({
 			...acc,
@@ -253,14 +283,21 @@ var useLoader = (routeList) => {
 		}), {});
 		try {
 			if (isCurrentRoute) setLoaderError(false);
-			const result = await routeItem?.loader();
+			const params = getParamsObject({
+				routeItem,
+				pathname
+			});
+			const result = await routeItem?.loader({
+				params,
+				context
+			});
 			cacheTimestampsRef.current = {
 				...cacheTimestampsRef.current,
-				[routeItem.path]: Date.now()
+				[pathname]: Date.now()
 			};
 			loaderCacheRef.current = {
 				...loaderCacheRef.current,
-				[routeItem.path]: result
+				[pathname]: result
 			};
 			if (isCurrentRoute) setLoaderCache(result);
 		} catch {
@@ -268,13 +305,16 @@ var useLoader = (routeList) => {
 		} finally {
 			if (isCurrentRoute) setIsLoading(false);
 		}
-	}, [isCacheItemFresh]);
+	}, [context, isCacheItemFresh]);
 	return {
 		loaderCache,
 		loaderError,
 		prefetchLoader: useCallback(async (pathname) => {
 			const item = routeList.find((el) => comparePaths(el, pathname));
-			if (item) await revalidateCache(item);
+			if (item) await revalidateCache({
+				routeItem: item,
+				pathname
+			});
 		}, [revalidateCache, routeList]),
 		revalidateCache,
 		isLoading
@@ -283,6 +323,31 @@ var useLoader = (routeList) => {
 //#endregion
 //#region hooks/useApplyCustomAnimation.ts
 var useApplyCustomAnimation = (animationOptions) => {
+	useEffect(() => {
+		const style = document.createElement("style");
+		style.id = "spinner-style";
+		style.textContent = `
+	@keyframes cr-spin {
+	  0% { transform: rotate(0deg); }
+	  100% { transform: rotate(360deg); }
+	}
+	
+	.cr-spinner {
+	  position: fixed;
+	  top: 5px;
+	  left: 5px;
+	  z-index: 9999;
+	  width: 1rem;
+	  height: 1rem;
+	  border: 2px solid gray;
+	  border-bottom-color: transparent;
+	  border-radius: 50%;
+	  animation: cr-spin 1s linear infinite;
+	}
+	`;
+		document.head.appendChild(style);
+		return () => style.remove();
+	}, []);
 	useEffect(() => {
 		if (!animationOptions?.duration) return;
 		const style = document.createElement("style");
@@ -348,15 +413,21 @@ var Router = ({ routeList, context: initialContext = {}, isAnimated = false, ani
 	const [context, setContext] = useState(initialContext);
 	useApplyCustomAnimation(animationOptions);
 	const routeItem = useMemo(() => routeList.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, location.pathname)), [location.pathname, routeList]);
-	const { loaderError, loaderCache, prefetchLoader, revalidateCache, isLoading } = useLoader(routeList);
-	const { blockerState, updateLocation, updateBlockedRoute } = useHandleNavigation({
+	const params = useMemo(() => getParamsObject({
+		routeItem,
+		pathname: window.location.pathname
+	}), [routeItem]);
+	const { loaderError, loaderCache, prefetchLoader, revalidateCache, isLoading } = useLoader({
+		routeList,
+		context
+	});
+	const { blockerState, updateLocation, updateBlockedRoute, beforeLoadError } = useHandleNavigation({
 		setLocation,
 		routeList,
 		context,
 		revalidateCache,
 		isAnimated
 	});
-	const params = useMemo(() => routeItem?.params ? getParamsObject(routeItem.params) : {}, [routeItem]);
 	const providerProps = useMemo(() => ({
 		location,
 		updateLocation,
@@ -381,9 +452,9 @@ var Router = ({ routeList, context: initialContext = {}, isAnimated = false, ani
 		...providerProps,
 		children: renderElement(routeItem?.loaderFallback)
 	});
-	if (loaderError) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RouterProvider, {
+	if (loaderError || beforeLoadError) return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(RouterProvider, {
 		...providerProps,
-		children: renderElement(routeItem?.errorElement)
+		children: [renderElement(routeItem?.errorElement), isAnimated && isLoading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
 	});
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(RouterProvider, {
 		...providerProps,

package/dist/types/global.d.ts

@@ -5,7 +5,10 @@ export type LazyComponent = () => Promise<{
 export type ClientRouteItem = {
     path: string;
     element: (() => ReactElement) | ReactElement | LazyComponent;
-    loader?(...args: unknown[]): Promise<unknown>;
+    loader?(arg: {
+        params: Record<string, string>;
+        context: Record<string, unknown>;
+    }): Promise<unknown>;
     loaderFallback?: (() => ReactElement) | ReactElement;
     errorElement?: (() => ReactElement) | ReactElement;
     fallback?: (() => ReactElement) | ReactElement;
@@ -14,8 +17,12 @@ export type ClientRouteItem = {
     beforeLoad?: (arg: {
         context: Record<string, unknown>;
         redirect: (arg: Location) => Promise<void>;
+        params: Record<string, string>;
     }) => Promise<unknown> | undefined;
-    afterLoad?: (context: Record<string, unknown>) => Promise<unknown> | undefined;
+    afterLoad?: (arg: {
+        context: Record<string, unknown>;
+        params: Record<string, string>;
+    }) => Promise<void>;
 };
 export type RouteItem = ClientRouteItem & {
     element: (() => ReactElement) | ReactElement;
@@ -39,3 +46,8 @@ export type AnimationOptions = {
     duration?: number;
     name?: 'fade' | 'slide-left' | 'slide-right';
 };
+export type RevalidateCacheArgs = {
+    pathname: string;
+    routeItem?: RouteItem;
+    isCurrentRoute?: boolean;
+};

package/dist/utils/utils.d.ts

@@ -1,5 +1,8 @@
-import type { ClientRouteItem, Location, RouteItem } from '../types/global.ts';
+import type { ClientRouteItem, Location, RouteItem } from '../types/global';
 export declare const createRouter: (clientList: ClientRouteItem[]) => RouteItem[];
-export declare const getParamsObject: (params: RouteItem["params"]) => {};
+export declare const getParamsObject: ({ routeItem, pathname }: {
+    routeItem?: RouteItem;
+    pathname: string;
+}) => {};
 export declare const parseWindowLocation: (location: typeof window.location) => Location;
 export declare const comparePaths: (el: RouteItem, pathname: string) => boolean;

package/package.json

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