clear-react-router 1.3.3 → 1.3.5

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 />`) |
 
 ```
@@ -325,13 +327,25 @@ function ProductFilter() {
 
 **Key features:**
 
-- ✅ **Array support** — `getSearchParams` returns `string[]` when multiple values exist for the same key
-- ✅ **Functional updates** — Update parameters based on previous state without losing other params
-- ✅ **Type-safe** — Proper TypeScript support with overloads
-- ✅ **Stable reference** — `setSearchParams` reference is stable and safe to use in `useEffect`
+- **Array support** — `getSearchParams` returns `string[]` when multiple values exist for the same key
+- **Functional updates** — Update parameters based on previous state without losing other params
+- **Type-safe** — Proper TypeScript support with overloads
+- **Stable reference** — `setSearchParams` reference is stable and safe to use in `useEffect`
 
 > **Note:** `getSearchParams` returns `string` for single values, `string[]` for multiple values, and `''` if the key is not found.
 
+### `useHistoricalTrail()`
+
+Returns an array of pathnames representing the user's actual navigation history. Perfect for **history-based breadcrumbs** in dashboards, admin panels, multi-step forms, or any app where users navigate non-linearly.
+
+**Returns:** Array of pathnames in chronological visit order (e.g., `['/dashboard', '/users', '/settings']`)
+
+**Key features:**
+- **Chronological order** — Paths are stored in the order the user visited them
+- **Unique entries** — Revisiting a page trims the trail to that point
+- **Respects navigation blocking** — Only successful navigations are added
+- **Redirect-safe** — Redirected pages are not added to the trail
+
 ## Lazy Loading
 
 Clear Router supports code-splitting out of the box. Simply pass a function that returns a dynamic import:

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/useHistoricalTrail.d.ts

@@ -0,0 +1 @@
+export declare const useHistoricalTrail: () => string[];

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.d.ts

@@ -9,5 +9,6 @@ export { useBlocker } from './hooks/useBlocker';
 export { useBeforeUnload } from './hooks/useBeforeUnload';
 export { useRouterContext } from './hooks/useRouterContext';
 export { useSearchParams } from './hooks/useSearchParams';
+export { useHistoricalTrail } from './hooks/useHistoricalTrail';
 export { createRouter } from './utils/utils';
 export type { RouteItem, BlockerState, Location } from './types/global';

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(() => ({
@@ -610,4 +642,18 @@ var useSearchParams = () => {
 	};
 };
 //#endregion
-export { Link, Router, RouterProvider, createRouter, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext, useSearchParams };
+//#region hooks/useHistoricalTrail.ts
+var useHistoricalTrail = () => {
+	const { pathname } = useLocation();
+	const [trail, setTrail] = useState([]);
+	useEffect(() => {
+		if (!pathname) return;
+		setTrail((prevState) => {
+			const index = prevState.indexOf(pathname);
+			return index === -1 ? [...prevState, pathname] : prevState.slice(0, index + 1);
+		});
+	}, [pathname]);
+	return trail;
+};
+//#endregion
+export { Link, Router, RouterProvider, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useLoaderState, useLocation, useNavigate, useParams, useRouterContext, useSearchParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {
@@ -12,7 +12,16 @@
     "routing",
     "typescript",
     "spa",
-    "nested-routes"
+    "nested-routes",
+    "data-loading",
+    "navigation-blocker",
+    "scroll-restoration",
+    "breadcrumbs",
+    "search-params",
+    "lazy-loading",
+    "prefetching",
+    "view-transitions",
+    "animations"
   ],
   "repository": {
     "type": "git",