clear-react-router 1.3.3 → 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
@@ -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 />`) |
 
 ```

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

@@ -7,8 +7,9 @@ type UseHandleNavigation = {
     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, setContext, }: 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/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

@@ -138,7 +138,7 @@ var comparePaths = (el, pathname) => {
 };
 //#endregion
 //#region hooks/useHandleNavigation.ts
-var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, isAnimated, setContext }) => {
+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,
@@ -209,7 +218,8 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 		routeList,
 		transitionedNavigation,
 		isAnimated,
-		setContext
+		setContext,
+		updateScrollMap
 	]);
 	const setNextLocationRef = useLatest(navigationHandler);
 	const updateBlockedRoute = useCallback(({ type, payload = "" }) => setBlockedRoute((prevState) => {
@@ -341,6 +351,23 @@ var useLoader = ({ routeList, context, setContext }) => {
 	};
 };
 //#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(() => {
@@ -379,10 +406,14 @@ 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,
@@ -394,7 +425,8 @@ var RouterProvider = ({ children, routeList, context: initialContext = {}, isAni
 		context,
 		setContext,
 		revalidateCache,
-		isAnimated
+		isAnimated,
+		setScrollMap
 	});
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
 		...useMemo(() => ({

package/package.json

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