clear-react-router 1.3.2 → 1.3.4

package/README.md

@@ -12,6 +12,7 @@ A lightweight, type-safe routing library for React applications with nested rout
 - 🎯 **Type-safe Redirects** - Redirect from beforeLoad hook
 - 📦 **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)
 - 🎨 **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
@@ -26,9 +27,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` | `({ 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 |
+| `loader` | `({ params, context, setContext }) => Promise<unknown>` | Fetch data using route params and context. Can update context via `setContext` |
+| `beforeLoad` | `({ params, context, redirect, setContext }) => Promise<unknown> \| undefined \| void` | Auth checks and redirects. Can update context via `setContext`. `redirect` is provided by the router |
+| `afterLoad` | `({ params, context, setContext }) => Promise<void>` | 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 loader) |
 | `errorElement` | `ReactElement \| () => ReactElement` | Error fallback |
@@ -45,6 +46,7 @@ The root component that provides routing context to the application. Place stati
 | `context` | `object` | `{}` | Initial context (user, theme, etc.) |
 | `isAnimated` | `boolean` | `false` | Enable smooth page transitions |
 | `animationDuration` | `number` | `optional` | Animation duration in milliseconds (browser default is used if not set) |
+| `preserveScroll` | `boolean` | `true` | Save and restore scroll position when navigating between pages |
 | `children` | `ReactNode` | required | App content (must include `<Router />`) |
 
 ```
@@ -95,7 +97,7 @@ Function provided to `beforeLoad` for programmatic redirection.
 **Type:** `(arg: Location | string) => Promise<void>`
 
 ```
-import type { Location } from 'clear-react-router';
+import type { createRouter } from 'clear-react-router';
 
 const routes = createRouter([
   {
@@ -107,8 +109,6 @@ const routes = createRouter([
   },
 ]);
 
-or
-
 const routes = createRouter([
   {
     path: '/dashboard',
@@ -118,6 +118,21 @@ const routes = createRouter([
     },
   },
 ]);
+
+const routes = createRouter([
+  {
+    path: '/user/:userId',
+    loader: async ({ params, context, setContext }) => {
+      const user = await fetchUser(params.userId);
+      setContext({ ...context, currentUser: user });
+      return { user };
+    },
+    beforeLoad: async ({ context, setContext, redirect }) => {
+      if (!context.token) return redirect('/login');
+      setContext({ ...context, lastVisit: Date.now() });
+    },
+  }
+]);
  
 ```
 

package/dist/components/RouterProvider.d.ts

@@ -6,6 +6,7 @@ type RouteProviderProps = {
     context?: Record<string, unknown>;
     isAnimated?: boolean;
     animationDuration?: number;
+    preserveScroll?: boolean;
 };
-export declare const RouterProvider: ({ children, routeList, context: initialContext, isAnimated, animationDuration, }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const RouterProvider: ({ children, routeList, context: initialContext, isAnimated, animationDuration, preserveScroll, }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/hooks/useHandleNavigation.d.ts

@@ -1,3 +1,4 @@
+import { type Dispatch, type SetStateAction } from 'react';
 import type { BlockerState, Location, RevalidateCacheArgs, RouteItem, UpdateBlockedRouteProps } from '../types/global';
 type UseHandleNavigation = {
     routeList: RouteItem[];
@@ -5,8 +6,10 @@ type UseHandleNavigation = {
     context: Record<string, unknown>;
     revalidateCache(arg: RevalidateCacheArgs): Promise<void>;
     isAnimated: boolean;
+    setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
+    setScrollMap: Dispatch<SetStateAction<Record<string, number>>>;
 };
-export declare const useHandleNavigation: ({ setLocation, routeList, context, revalidateCache, isAnimated, }: UseHandleNavigation) => {
+export declare const useHandleNavigation: ({ setLocation, routeList, context, revalidateCache, isAnimated, setContext, setScrollMap, }: UseHandleNavigation) => {
     blockerState: BlockerState;
     updateLocation: (nextLocation: Location) => Promise<void>;
     updateBlockedRoute: ({ type, payload }: UpdateBlockedRouteProps) => void;

package/dist/hooks/useLoader.d.ts

@@ -1,9 +1,11 @@
+import { type Dispatch, type SetStateAction } from 'react';
 import type { RevalidateCacheArgs, RouteItem } from '../types/global';
 type UseLoaderParams = {
     routeList: RouteItem[];
     context: Record<string, unknown>;
+    setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
 };
-export declare const useLoader: ({ routeList, context }: UseLoaderParams) => {
+export declare const useLoader: ({ routeList, context, setContext }: UseLoaderParams) => {
     loaderCache: unknown;
     loaderError: boolean;
     prefetchLoader: (pathname: string) => Promise<void>;

package/dist/hooks/usePreserveScroll.d.ts

@@ -0,0 +1,6 @@
+type UsePreserveScrollParams = {
+    pathname: string;
+    preserveScroll: boolean;
+};
+export declare const usePreserveScroll: ({ pathname, preserveScroll }: UsePreserveScrollParams) => import("react").Dispatch<import("react").SetStateAction<Record<string, number>>>;
+export {};

package/dist/index.js

@@ -77,6 +77,15 @@ var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocat
 	});
 };
 //#endregion
+//#region hooks/useLatest.ts
+var useLatest = (value) => {
+	const ref = useRef(value);
+	useEffect(() => {
+		ref.current = value;
+	}, [value]);
+	return ref;
+};
+//#endregion
 //#region utils/createLazyComponent.tsx
 var createLazyComponent = (importFn, fallback) => {
 	const LazyComp = lazy(() => importFn().then((module) => ({ default: module.default || module })));
@@ -128,17 +137,8 @@ var comparePaths = (el, pathname) => {
 	return splitElementPath.every((item, index) => item === splitPathname[index + (index ? 1 : 0)]) && splitPathname.length === splitElementPath.length + paramsLength;
 };
 //#endregion
-//#region hooks/useLatest.ts
-var useLatest = (value) => {
-	const ref = useRef(value);
-	useEffect(() => {
-		ref.current = value;
-	}, [value]);
-	return ref;
-};
-//#endregion
 //#region hooks/useHandleNavigation.ts
-var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, isAnimated }) => {
+var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, isAnimated, setContext, setScrollMap }) => {
 	const [blockedRoute, setBlockedRoute] = useState({
 		from: "",
 		to: ""
@@ -146,6 +146,14 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 	const [beforeLoadError, setBeforeLoadError] = useState(false);
 	const prevPathname = useRef("");
 	const navigationSeq = useRef(0);
+	const updateScrollMap = useCallback(() => setScrollMap((prevState) => {
+		const scrollPosition = document.scrollingElement?.scrollTop ?? 0;
+		if (!scrollPosition || prevState[prevPathname.current] === scrollPosition) return prevState;
+		return {
+			...prevState,
+			[prevPathname.current]: scrollPosition
+		};
+	}), [setScrollMap]);
 	const navigation = useCallback((nextLocation) => {
 		setLocation(nextLocation);
 		prevPathname.current = nextLocation.pathname;
@@ -164,6 +172,7 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 	const navigationHandler = useCallback(async (nextLocation, isFirstCall) => {
 		navigationSeq.current = navigationSeq.current + 1;
 		const seq = navigationSeq.current;
+		updateScrollMap();
 		const nextItem = routeList.find((el) => comparePaths(el, nextLocation.pathname));
 		const params = getParamsObject({
 			routeItem: nextItem,
@@ -174,7 +183,8 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 			await nextItem.beforeLoad({
 				context,
 				redirect,
-				params
+				params,
+				setContext
 			});
 		} catch {
 			setBeforeLoadError(true);
@@ -199,14 +209,17 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 		setBeforeLoadError(false);
 		if (nextItem?.afterLoad) await nextItem.afterLoad({
 			context,
-			params
+			params,
+			setContext
 		});
 	}, [
 		context,
 		revalidateCache,
 		routeList,
 		transitionedNavigation,
-		isAnimated
+		isAnimated,
+		setContext,
+		updateScrollMap
 	]);
 	const setNextLocationRef = useLatest(navigationHandler);
 	const updateBlockedRoute = useCallback(({ type, payload = "" }) => setBlockedRoute((prevState) => {
@@ -265,7 +278,7 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 };
 //#endregion
 //#region hooks/useLoader.ts
-var useLoader = ({ routeList, context }) => {
+var useLoader = ({ routeList, context, setContext }) => {
 	const [loaderCache, setLoaderCache] = useState();
 	const [loaderError, setLoaderError] = useState(false);
 	const [isLoading, setIsLoading] = useState(false);
@@ -301,7 +314,8 @@ var useLoader = ({ routeList, context }) => {
 			});
 			const result = await routeItem?.loader({
 				params,
-				context
+				context,
+				setContext
 			});
 			cacheTimestampsRef.current = {
 				...cacheTimestampsRef.current,
@@ -317,7 +331,11 @@ var useLoader = ({ routeList, context }) => {
 		} finally {
 			if (isCurrentRoute) setIsLoading(false);
 		}
-	}, [context, isCacheItemFresh]);
+	}, [
+		context,
+		isCacheItemFresh,
+		setContext
+	]);
 	return {
 		loaderCache,
 		loaderError,
@@ -333,6 +351,23 @@ var useLoader = ({ routeList, context }) => {
 	};
 };
 //#endregion
+//#region hooks/usePreserveScroll.ts
+var usePreserveScroll = ({ pathname, preserveScroll }) => {
+	const [scrollMap, setScrollMap] = useState({});
+	useEffect(() => {
+		if (!preserveScroll || !pathname || !scrollMap[pathname]) return;
+		document.scrollingElement?.scrollTo({
+			top: scrollMap[pathname],
+			behavior: "smooth"
+		});
+	}, [
+		pathname,
+		scrollMap,
+		preserveScroll
+	]);
+	return setScrollMap;
+};
+//#endregion
 //#region hooks/useApplyCustomAnimation.ts
 var useApplyCustomAnimation = (animationDuration) => {
 	useEffect(() => {
@@ -371,20 +406,27 @@ var useApplyCustomAnimation = (animationDuration) => {
 };
 //#endregion
 //#region components/RouterProvider.tsx
-var RouterProvider = ({ children, routeList, context: initialContext = {}, isAnimated = false, animationDuration }) => {
+var RouterProvider = ({ children, routeList, context: initialContext = {}, isAnimated = false, animationDuration, preserveScroll = true }) => {
 	const [location, setLocation] = useState({});
 	const [context, setContext] = useState(initialContext);
 	useApplyCustomAnimation(animationDuration);
+	const setScrollMap = usePreserveScroll({
+		pathname: location.pathname,
+		preserveScroll
+	});
 	const { loaderError, loaderCache, prefetchLoader, revalidateCache, isLoading } = useLoader({
 		routeList,
-		context
+		context,
+		setContext
 	});
 	const { blockerState, updateLocation, updateBlockedRoute, beforeLoadError } = useHandleNavigation({
 		setLocation,
 		routeList,
 		context,
+		setContext,
 		revalidateCache,
-		isAnimated
+		isAnimated,
+		setScrollMap
 	});
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
 		...useMemo(() => ({

package/dist/types/global.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, ReactElement } from 'react';
+import type { ComponentType, Dispatch, ReactElement, SetStateAction } from 'react';
 export type LazyComponent = () => Promise<{
     default: ComponentType<unknown>;
 }>;
@@ -8,6 +8,7 @@ export type ClientRouteItem = {
     loader?(arg: {
         params: Record<string, string>;
         context: Record<string, unknown>;
+        setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
     }): Promise<unknown>;
     loaderFallback?: (() => ReactElement) | ReactElement;
     errorElement?: (() => ReactElement) | ReactElement;
@@ -18,10 +19,12 @@ export type ClientRouteItem = {
         context: Record<string, unknown>;
         redirect: (arg: Location | string) => Promise<void>;
         params: Record<string, string>;
-    }) => Promise<unknown> | undefined;
+        setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
+    }) => Promise<unknown> | undefined | void;
     afterLoad?: (arg: {
         context: Record<string, unknown>;
         params: Record<string, string>;
+        setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
     }) => Promise<void>;
 };
 export type RouteItem = ClientRouteItem & {

package/package.json

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