clear-react-router 1.2.5 → 1.3.1

package/README.md

@@ -7,7 +7,8 @@ A lightweight, type-safe routing library for React applications with nested rout
 - 🧩 **Nested Routes** - Organize your UI with nested layouts and routes
 - ⚡ **Data Loading** - Built-in loaders with caching and stale-while-revalidate strategy
 - 🔒 **Navigation Blocking** - Prevent accidental navigation with `useBlocker`
-- ✨ **Smooth Animations** - Page transitions with fade and slide effects (customizable type and duration)
+- ✨ **Smooth Animations** - Page transitions with fade effect (customizable duration)
+- 🏗️ **Static Layout** — Keep navbar, footer, and other elements outside the router to avoid unnecessary re-renders
 - 🎯 **Type-safe Redirects** - Redirect from loaders and beforeLoad hooks
 - 📦 **Prefetching** - Preload data on hover for instant navigation
 - 🚀 **Lazy Loading** - Code-split your routes with dynamic imports for optimal performance
@@ -31,28 +32,51 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 | `fallback` | `ReactElement \| () => ReactElement` | Loading fallback (for lazy loading) |
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback (for loader) |
 | `errorElement` | `ReactElement \| () => ReactElement` | Error fallback |
-| `staleTime` | `number` | Cache duration in ms for loader data |
+| `staleTime` | `number` | Time in ms before cached data is considered stale and re-fetched in the background. If not provided, data never expires (cached forever) |
 | `children` | `RouteItem[]` | Nested routes |
 
-### `Router`
+### `RouterProvider`
 
-Main component that renders the application based on current URL.
+The root component that provides routing context to the application. Place static UI elements (like navbar or footer) outside `<Router />` to prevent unnecessary re-renders.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `routeList` | `RouteItem[]` | required | Array of route configurations |
-| `context` | `object` | `{}` | Optional initial context (user, theme, etc.) |
+| `context` | `object` | `{}` | Initial context (user, theme, etc.) |
 | `isAnimated` | `boolean` | `false` | Enable smooth page transitions |
-| `animationOptions` | `AnimationOptions` | `{ duration: 300, name: 'fade' }` | Animation settings (only when `isAnimated` is `true`) |
+| `animationDuration` | `number` | `optional` | Animation duration in milliseconds (browser default is used if not set) |
+| `children` | `ReactNode` | required | App content (must include `<Router />`) |
+
+```
+function App() {
+  return (
+    <RouterProvider routeList={routes} isAnimated animationDuration={800}>
+      <Navbar />           {/* Static — won't re-render on route change */}
+      <main>
+        <Router />         {/* Dynamic — renders current page */}
+      </main>
+      <Footer />           {/* Static — won't re-render on route change */}
+    </RouterProvider>
+  );
+}
+```
+
+### `Router`
 
-**`AnimationOptions`:**
+Renders the current route's component. Must be placed inside `<RouterProvider>`.
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `duration` | `number` | `300` | Animation duration in milliseconds |
-| `name` | `'fade' \| 'slide-left' \| 'slide-right'` | `'fade'` | Type of transition effect |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `spinner` | `boolean /| undefined` | `true` | Show a small spinner in the corner while loading data (only when `isAnimated` is enabled) |
 
-> **Note:** When `isAnimated` is enabled, the `loaderFallback` is not displayed. Instead, a small spinner appears in the corner while data loads, ensuring smooth transitions without layout shifts.
+```
+<RouterProvider routeList={routes} isAnimated>
+  <Navbar />
+  <Router spinner={false} />  {/* disable the spinner */}
+</RouterProvider>
+```
+
+> **Note:** When `isAnimated` is enabled, `loaderFallback` is not shown. Instead, a small spinner appears (if `spinner={true}`).
 
 ### `Link`
 
@@ -68,7 +92,7 @@ Component for client-side navigation with prefetch support.
 
 Function provided to `beforeLoad` for programmatic redirection.
 
-**Type:** `(arg: Location) => Promise<void>`
+**Type:** `(arg: Location | string) => Promise<void>`
 
 ```
 import type { Location } from 'clear-react-router';
@@ -78,12 +102,23 @@ const routes = createRouter([
     path: '/dashboard',
     element: <Dashboard />,
     beforeLoad: ({ context, redirect }) => {
-      if (!context.isAuthorized) {
-        return redirect({ pathname: '/' });
-      }
+      if (!context.isAuthorized) return redirect('/');
     },
   },
 ]);
+
+or
+
+const routes = createRouter([
+  {
+    path: '/dashboard',
+    element: <Dashboard />,
+    beforeLoad: ({ context, redirect }) => {
+      if (!context.isAuthorized) return redirect({ pathname: '/login', state: { from: '/dashboard' } });
+    },
+  },
+]);
+ 
 ```
 
 ### Usage with Parameters
@@ -103,11 +138,11 @@ const routes = createRouter([
     beforeLoad: async ({ params, context, redirect }) => {
       // Authentication check
       if (!context.isAuthorized) {
-        return redirect({ pathname: '/login' });
+        return redirect('/login');
       }
       // Validate parameter
       if (!params.userId || !isValidUserId(params.userId)) {
-        return redirect({ pathname: '/users' });
+        return redirect('/users');
       }
     },
     afterLoad: ({ params, context }) => {
@@ -122,11 +157,15 @@ const routes = createRouter([
 
 ### `useNavigate()`
 
-Returns function to navigate programmatically:
+Returns function to navigate programmatically. Accepts a string (pathname), an object with `pathname`, `search`, and `state`, or `-1` to go back.
+
+```
+const navigate = useNavigate();
 
-- `navigate({ pathname: '/about' })` - navigate to path
-- `navigate({ pathname: '/user/123', state: { fromDashboard: true } })` - navigate with state
-- `navigate(-1)` - go back
+navigate('/about');                                           // string
+navigate({ pathname: '/user/123', state: { from: 'home' } }); // object
+navigate(-1);                                                 // go back
+```
 
 **Note:** Navigation state can be accessed via `useLocation()`:
 
@@ -157,9 +196,22 @@ const { pathname, search, state } = useLocation();
 
 ### `useLoaderState()`
 
-Returns loaderState from current route's loader.
+Returns the cached data loaded by the current route's `loader`. Data is automatically cached and reused when navigating back to the same route.
+```
+const UserProfile = () => {
+  const user = useLoaderState();
+  return <div>{user.name}</div>;
+}
 ```
-const state = useLoaderState();
+### Caching behavior:
+- The loader result is cached and reused when navigating back to the same route (e.g., from /user/123 back to /user/456 it will be a new request because different params, but from /user/456 to /user/456 — cache hit).
+- Use staleTime in route config to control how long cache is considered fresh:
+```
+{
+  path: '/user/:userId',
+  loader: async ({ params }) => fetchUser(params.userId),
+  staleTime: 60000, // 1 minute — cache is fresh for 60 seconds
+}
 ```
 
 ### `useBlocker(callback)`
@@ -214,12 +266,59 @@ useBeforeUnload(text ? onSave : undefined);
 
 ### `useRouterContext()`
 
-Handles router context.
+Returns the router context object and a function to update it. Useful for accessing or modifying global state (like user authentication, theme, etc.) from anywhere in your app.
 ```
 const { setContext, context } = useRouterContext();
 const loginHandler = () => setContext({ ...context, user: { name: 'John' } });
 ```
 
+### `useSearchParams()`
+
+Returns an object for working with URL query parameters. Supports reading and setting both single values and arrays.
+
+```
+import { useSearchParams } from 'clear-react-router';
+
+function ProductFilter() {
+  const { searchParams, getSearchParams, setSearchParams } = useSearchParams();
+
+  // Get a single value or array
+  const brand = getSearchParams('brand'); // 'nike' | ['nike', 'reebok'] | ''
+
+  // Set a single value
+  setSearchParams('brand', 'nike'); // ?brand=nike
+
+  // Set multiple values (array)
+  setSearchParams('brand', ['nike', 'reebok']); // ?brand=nike&brand=reebok
+
+  // Functional update (preserves other params)
+  setSearchParams((prev) => {
+    prev.set('page', '2');
+    prev.append('color', 'red');
+    return prev;
+  });
+
+  // Direct access to URLSearchParams
+  const allParams = searchParams.toString(); // "brand=nike&brand=reebok&page=2"
+}
+```
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `searchParams` | `URLSearchParams` | Raw `URLSearchParams` object for low-level access |
+| `getSearchParams` | `(key: string) => string \| string[]` | Returns a single value or an array if multiple values exist for the key |
+| `setSearchParams` | `(param: string, value: string \| string[]) => void` `or` `(updater: (prev: URLSearchParams) => URLSearchParams) => void` | Update query parameters. Supports single values, arrays, or functional updates |
+
+**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`
+
+> **Note:** `getSearchParams` returns `string` for single values, `string[]` for multiple values, and `''` if the key is not found.
+
 ## Lazy Loading
 
 Clear Router supports code-splitting out of the box. Simply pass a function that returns a dynamic import:
@@ -239,35 +338,24 @@ Clear Router supports smooth page transitions using the native View Transitions
 ```
 import { Router } from 'clear-react-router';
 
-// Enable default fade animation
-<Router routeList={routes} isAnimated />
+// Enable fade animation
+<RouterProvider routeList={routes} isAnimated>
+  <Router />
+</RouterProvider>  
 
-// Custom animation
-<Router 
-  routeList={routes} 
-  isAnimated 
-  animationOptions={{ 
-    duration: 500,        // milliseconds
-    name: 'slide-left'    // 'fade' | 'slide-left' | 'slide-right'
-  }} 
-/>
+// Custom animation duration
+<RouterProvider routeList={routes} isAnimated animationDuration={800}>
+  <Router />
+</RouterProvider>
 ```
 
 ## How It Works
 
 - **Data loads first** — All `loader` and `beforeLoad` hooks complete before animation starts
 - **No `loaderFallback`** — The `loaderFallback` is not shown during animated transitions
-- **Subtle spinner** — A small spinner appears in the top-left corner while data is loading, so users know the app is responsive
+- **Subtle spinner** — A small spinner appears in the top-left corner while data is loading and `spinner` prop of `Router` component is on, so users know the app is responsive
 - **Native API** — Uses `document.startViewTransition` for smooth, hardware-accelerated animations
 
-## Animation Types
-
-| Name | Effect |
-|------|--------|
-| `fade` | Cross-fade between pages (default) |
-| `slide-left` | New page slides in from right, old page slides out to left |
-| `slide-right` | New page slides in from left, old page slides out to right |
-
 ## Browser Support
 
 View Transitions API requires modern browsers:

package/dist/components/Router.d.ts

@@ -1,9 +1,3 @@
-import { AnimationOptions, RouteItem } from '../types/global';
-type RouterProps = {
-    routeList: RouteItem[];
-    context?: Record<string, unknown>;
-    isAnimated?: boolean;
-    animationOptions?: AnimationOptions;
-};
-export declare const Router: ({ routeList, context: initialContext, isAnimated, animationOptions, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;
-export {};
+export declare const Router: ({ spinner }: {
+    spinner?: boolean;
+}) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/RouterProvider.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { RouteItem } from '../types/global';
+type RouteProviderProps = {
+    children: ReactNode;
+    routeList: RouteItem[];
+    context?: Record<string, unknown>;
+    isAnimated?: boolean;
+    animationDuration?: number;
+};
+export declare const RouterProvider: ({ children, routeList, context: initialContext, isAnimated, animationDuration, }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/context/{RouterContext.d.ts → RouterProviderContext.d.ts}

@@ -1,8 +1,13 @@
-import type { BlockerState, Location, UpdateBlockedRouteProps } from '../types/global';
+import { BlockerState, Location, RouteItem, UpdateBlockedRouteProps } from '../types/global';
+export type PropsContextValue = {
+    routeList: RouteItem[];
+    isAnimated: boolean;
+};
 export type NavigationContextValue = {
     location: Location;
-    params: Record<string, string>;
     blockerState: BlockerState;
+    isLoading: boolean;
+    shouldErrorElementShown: boolean;
 };
 export type ActionsContextValue = {
     updateLocation(route: Location): Promise<void>;
@@ -14,6 +19,7 @@ export type DataContextValue = {
     loaderCache: unknown;
     context: Record<string, unknown>;
 };
+export declare const PropsContext: import("react").Context<PropsContextValue>;
 export declare const ActionsContext: import("react").Context<ActionsContextValue>;
 export declare const DataContext: import("react").Context<DataContextValue>;
 export declare const NavigationContext: import("react").Context<NavigationContextValue>;

package/dist/context/RouterViewContext.d.ts

@@ -0,0 +1 @@
+export declare const RouterViewContext: import("react").Context<Record<string, string>>;

package/dist/hooks/useApplyCustomAnimation.d.ts

@@ -1,2 +1 @@
-import { AnimationOptions } from '../types/global';
-export declare const useApplyCustomAnimation: (animationOptions: AnimationOptions) => void;
+export declare const useApplyCustomAnimation: (animationDuration?: number) => void;

package/dist/hooks/useNavigate.d.ts

@@ -1,2 +1,2 @@
-import type { Location } from '../types/global.ts';
-export declare const useNavigate: () => (arg: Location | -1) => Promise<void>;
+import type { Location } from '../types/global';
+export declare const useNavigate: () => (arg: Location | string | number) => Promise<void>;

package/dist/hooks/useSearchParams.d.ts

@@ -0,0 +1,10 @@
+type UseSearchParamsReturn = {
+    searchParams: URLSearchParams;
+    getSearchParams(arg: string): string | string[];
+    setSearchParams: {
+        (param: string, value: string | string[]): void;
+        (param: (prevState: URLSearchParams) => URLSearchParams): void;
+    };
+};
+export declare const useSearchParams: () => UseSearchParamsReturn;
+export {};

package/dist/hooks/useServiceContext.d.ts

@@ -1,3 +1,4 @@
-export declare const useNavigationState: () => import("../context/RouterContext").NavigationContextValue;
-export declare const useRouterActions: () => import("../context/RouterContext").ActionsContextValue;
-export declare const useRouterData: () => import("../context/RouterContext").DataContextValue;
+export declare const useNavigationState: () => import("../context/RouterProviderContext").NavigationContextValue;
+export declare const useRouterActions: () => import("../context/RouterProviderContext").ActionsContextValue;
+export declare const useRouterData: () => import("../context/RouterProviderContext").DataContextValue;
+export declare const usePropsData: () => import("../context/RouterProviderContext").PropsContextValue;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { RouterProvider } from './components/RouterProvider';
 export { Router } from './components/Router';
 export { Link } from './components/Link';
 export { useNavigate } from './hooks/useNavigate';
@@ -7,5 +8,6 @@ export { useLoaderState } from './hooks/useLoaderState';
 export { useBlocker } from './hooks/useBlocker';
 export { useBeforeUnload } from './hooks/useBeforeUnload';
 export { useRouterContext } from './hooks/useRouterContext';
+export { useSearchParams } from './hooks/useSearchParams';
 export { createRouter } from './utils/utils';
 export type { RouteItem, BlockerState, Location } from './types/global';

package/dist/index.js

@@ -2,7 +2,8 @@ import { Suspense, createContext, lazy, useCallback, useContext, useEffect, useM
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
-//#region context/RouterContext.ts
+//#region context/RouterProviderContext.ts
+var PropsContext = createContext({});
 var ActionsContext = createContext({});
 var DataContext = createContext({});
 var NavigationContext = createContext({});
@@ -40,30 +41,37 @@ var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((expor
 	exports.jsxs = jsxProd;
 }));
 //#endregion
-//#region provider/RouterProvider.tsx
+//#region provider/Provider.tsx
 var import_jsx_runtime = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = require_react_jsx_runtime_production();
 })))();
-var RouterProvider = ({ children, setContext, context, updateBlockedRoute, updateLocation, location, params, prefetchLoader, loaderCache, blockerState }) => {
-	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext.Provider, {
+var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, location, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated }) => {
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PropsContext.Provider, {
 		value: {
-			updateLocation,
-			updateBlockedRoute,
-			prefetchLoader,
-			setContext
+			routeList,
+			isAnimated
 		},
-		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DataContext.Provider, {
+		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext.Provider, {
 			value: {
-				context,
-				loaderCache
+				updateLocation,
+				updateBlockedRoute,
+				prefetchLoader,
+				setContext
 			},
-			children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NavigationContext.Provider, {
+			children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DataContext.Provider, {
 				value: {
-					blockerState,
-					params,
-					location
+					context,
+					loaderCache
 				},
-				children
+				children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NavigationContext.Provider, {
+					value: {
+						blockerState,
+						location,
+						shouldErrorElementShown,
+						isLoading
+					},
+					children
+				})
 			})
 		})
 	});
@@ -141,8 +149,9 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 	const navigation = useCallback((nextLocation) => {
 		setLocation(nextLocation);
 		prevPathname.current = nextLocation.pathname;
-		if (nextLocation.pathname === window.location.pathname) return;
-		history.pushState(null, "", nextLocation.pathname);
+		const fullPath = nextLocation.search ? `${nextLocation.pathname}${nextLocation.search}` : nextLocation.pathname;
+		if (fullPath === window.location.pathname + window.location.search) return;
+		history.pushState(null, "", fullPath);
 	}, [setLocation]);
 	const transitionedNavigation = useCallback(({ nextLocation, isFirstCall, isAnimated }) => {
 		if (isAnimated && !isFirstCall) try {
@@ -161,9 +170,10 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 			pathname: nextLocation.pathname
 		});
 		if (nextItem?.beforeLoad) try {
+			const redirect = async (location) => typeof location === "string" ? await navigationHandler({ pathname: location }) : await navigationHandler(location);
 			await nextItem.beforeLoad({
 				context,
-				redirect: navigationHandler,
+				redirect,
 				params
 			});
 		} catch {
@@ -264,7 +274,9 @@ var useLoader = ({ routeList, context }) => {
 	const isCacheItemFresh = useCallback(({ routeItem, pathname }) => {
 		if (!routeItem) return true;
 		const currentCacheTimestamp = cacheTimestampsRef.current[pathname];
-		return Boolean(currentCacheTimestamp && Date.now() - currentCacheTimestamp < (routeItem.staleTime || 0));
+		if (!currentCacheTimestamp) return false;
+		if (!routeItem.staleTime) return true;
+		return Date.now() - currentCacheTimestamp < routeItem.staleTime;
 	}, []);
 	const revalidateCache = useCallback(async ({ routeItem, isCurrentRoute, pathname }) => {
 		if (!routeItem?.loader) return;
@@ -322,7 +334,7 @@ var useLoader = ({ routeList, context }) => {
 };
 //#endregion
 //#region hooks/useApplyCustomAnimation.ts
-var useApplyCustomAnimation = (animationOptions) => {
+var useApplyCustomAnimation = (animationDuration) => {
 	useEffect(() => {
 		const style = document.createElement("style");
 		style.id = "spinner-style";
@@ -349,51 +361,61 @@ var useApplyCustomAnimation = (animationOptions) => {
 		return () => style.remove();
 	}, []);
 	useEffect(() => {
-		if (!animationOptions?.duration) return;
+		if (!animationDuration) return;
 		const style = document.createElement("style");
 		style.id = "dynamic-view-transition-duration-style";
-		style.textContent = `::view-transition-group(root) { animation-duration: ${animationOptions.duration}ms; }`;
-		document.head.appendChild(style);
-		return () => style.remove();
-	}, [animationOptions]);
-	useEffect(() => {
-		if (!animationOptions.name) return;
-		const style = document.createElement("style");
-		style.id = "dynamic-view-transition-duration-name";
-		style.textContent = `
-    @keyframes fade-out {
-      from { opacity: 1; }
-      to { opacity: 0; }
-    }    
-    @keyframes fade-in {
-      from { opacity: 0; }
-      to { opacity: 1; }
-    }
-    @keyframes slide-left-out {
-    from { transform: translateX(0); }
-    to { transform: translateX(-100%); }
-    }
-    @keyframes slide-left-in {
-      from { transform: translateX(100%); }
-      to { transform: translateX(0); }
-    }
-    @keyframes slide-right-out {
-    from { transform: translateX(0); }
-    to { transform: translateX(100%); }
-    }
-    @keyframes slide-right-in {
-      from { transform: translateX(-100%); }
-      to { transform: translateX(0); }
-    }
-	::view-transition-old(root) {
-      animation: ${animationOptions.name}-out ${animationOptions.duration ?? 800}ms cubic-bezier(0.4, 0, 0.2, 1);
-    }
-    ::view-transition-new(root) {
-      animation: ${animationOptions.name}-in ${animationOptions.duration ?? 800}ms cubic-bezier(0.4, 0, 0.2, 1);
-    }`;
+		style.textContent = `::view-transition-group(page) { animation-duration: ${animationDuration}ms; }`;
 		document.head.appendChild(style);
 		return () => style.remove();
-	}, [animationOptions]);
+	}, [animationDuration]);
+};
+//#endregion
+//#region components/RouterProvider.tsx
+var RouterProvider = ({ children, routeList, context: initialContext = {}, isAnimated = false, animationDuration }) => {
+	const [location, setLocation] = useState({});
+	const [context, setContext] = useState(initialContext);
+	useApplyCustomAnimation(animationDuration);
+	const { loaderError, loaderCache, prefetchLoader, revalidateCache, isLoading } = useLoader({
+		routeList,
+		context
+	});
+	const { blockerState, updateLocation, updateBlockedRoute, beforeLoadError } = useHandleNavigation({
+		setLocation,
+		routeList,
+		context,
+		revalidateCache,
+		isAnimated
+	});
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
+		...useMemo(() => ({
+			location,
+			updateLocation,
+			loaderCache,
+			prefetchLoader,
+			updateBlockedRoute,
+			blockerState,
+			context,
+			setContext,
+			routeList,
+			isLoading,
+			shouldErrorElementShown: loaderError || beforeLoadError,
+			isAnimated
+		}), [
+			beforeLoadError,
+			blockerState,
+			context,
+			isLoading,
+			loaderCache,
+			loaderError,
+			location,
+			prefetchLoader,
+			routeList,
+			updateBlockedRoute,
+			updateLocation,
+			isAnimated
+		]),
+		children
+	});
 };
 //#endregion
 //#region components/Spinner.tsx
@@ -405,13 +427,34 @@ var renderElement = (Component) => {
 	return typeof Component === "function" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Component, {}) : Component;
 };
 //#endregion
+//#region hooks/useServiceContext.ts
+var useServiceState = (reactContext) => {
+	const context = useContext(reactContext);
+	if (!Object.keys(context).length) throw new Error("hooks and Router component must be used within RouterProvider");
+	return context;
+};
+var useNavigationState = () => useServiceState(NavigationContext);
+var useRouterActions = () => useServiceState(ActionsContext);
+var useRouterData = () => useServiceState(DataContext);
+var usePropsData = () => useServiceState(PropsContext);
+//#endregion
+//#region context/RouterViewContext.ts
+var RouterViewContext = createContext({});
+//#endregion
+//#region provider/ViewProvider.tsx
+var ViewProvider = ({ children, params }) => {
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RouterViewContext.Provider, {
+		value: params,
+		children
+	});
+};
+//#endregion
 //#region components/Router.tsx
 var PAGE_NOT_FOUND = "error 404. Page not found";
 var ALL_LOCATIONS = "*";
-var Router = ({ routeList, context: initialContext = {}, isAnimated = false, animationOptions = {} }) => {
-	const [location, setLocation] = useState({});
-	const [context, setContext] = useState(initialContext);
-	useApplyCustomAnimation(animationOptions);
+var Router = ({ spinner = true }) => {
+	const { location, isLoading, shouldErrorElementShown } = useNavigationState();
+	const { routeList, isAnimated } = usePropsData();
 	const routeItem = useMemo(() => {
 		if (!location.pathname) return void 0;
 		return routeList.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, location.pathname));
@@ -420,74 +463,41 @@ var Router = ({ routeList, context: initialContext = {}, isAnimated = false, ani
 		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 providerProps = useMemo(() => ({
-		location,
-		updateLocation,
-		params,
-		loaderCache,
-		prefetchLoader,
-		updateBlockedRoute,
-		blockerState,
-		context,
-		setContext
-	}), [
-		blockerState,
-		loaderCache,
-		location,
-		params,
-		prefetchLoader,
-		context,
-		updateBlockedRoute,
-		updateLocation
-	]);
+	if (spinner && !routeItem && isLoading) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {});
 	if (!routeItem && isLoading) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {});
 	if (!routeItem) return null;
-	if (!isAnimated && routeItem?.loader && !loaderError && isLoading) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RouterProvider, {
-		...providerProps,
+	if (!isAnimated && routeItem?.loader && !shouldErrorElementShown && isLoading) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ViewProvider, {
+		params,
 		children: renderElement(routeItem?.loaderFallback)
 	});
-	if (loaderError || beforeLoadError) return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(RouterProvider, {
-		...providerProps,
-		children: [renderElement(routeItem?.errorElement), isAnimated && isLoading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
+	if (shouldErrorElementShown) return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(ViewProvider, {
+		params,
+		children: [renderElement(routeItem?.errorElement), spinner && isAnimated && isLoading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
 	});
-	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(RouterProvider, {
-		...providerProps,
-		children: [renderElement(routeItem?.element) || PAGE_NOT_FOUND, isAnimated && isLoading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
+		style: { viewTransitionName: "page" },
+		children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(ViewProvider, {
+			params,
+			children: [renderElement(routeItem?.element) || PAGE_NOT_FOUND, spinner && isAnimated && isLoading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
+		})
 	});
 };
 //#endregion
-//#region hooks/useServiceContext.ts
-var useNavigationState = () => {
-	const context = useContext(NavigationContext);
-	if (!Object.keys(context).length) throw new Error("useNavigationState must be used within Router component");
-	return context;
-};
-var useRouterActions = () => {
-	const context = useContext(ActionsContext);
-	if (!Object.keys(context).length) throw new Error("useRouterActions must be used within Router component");
-	return context;
-};
-var useRouterData = () => {
-	const context = useContext(DataContext);
-	if (!Object.keys(context).length) throw new Error("useRouterData must be used within Router component");
-	return context;
+//#region hooks/useLocation.ts
+var useLocation = () => {
+	return useNavigationState().location;
 };
 //#endregion
 //#region hooks/useNavigate.ts
 var useNavigate = () => {
 	const { updateLocation } = useRouterActions();
-	return useCallback(async (arg) => arg === -1 ? history.go(-1) : await updateLocation(arg), [updateLocation]);
+	const locationRef = useLatest(useLocation());
+	return useCallback(async (arg) => {
+		if (typeof arg === "number") return history.go(arg);
+		if (typeof arg === "string") {
+			if (arg !== locationRef.current.pathname) await updateLocation({ pathname: arg });
+		} else if (JSON.stringify(arg) !== JSON.stringify(locationRef.current)) await updateLocation(arg);
+	}, [updateLocation, locationRef]);
 };
 //#endregion
 //#region components/Link.tsx
@@ -496,7 +506,7 @@ var Link = ({ children, to, prefetch = true }) => {
 	const navigate = useNavigate();
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", {
 		style: { cursor: "pointer" },
-		onClick: () => navigate({ pathname: to }),
+		onClick: () => navigate(to),
 		onMouseOver: () => prefetch && prefetchLoader(to),
 		children
 	});
@@ -504,13 +514,7 @@ var Link = ({ children, to, prefetch = true }) => {
 //#endregion
 //#region hooks/useParams.ts
 var useParams = () => {
-	const { params } = useNavigationState();
-	return params;
-};
-//#endregion
-//#region hooks/useLocation.ts
-var useLocation = () => {
-	return useNavigationState().location;
+	return useContext(RouterViewContext);
 };
 //#endregion
 //#region hooks/useLoaderState.ts
@@ -562,4 +566,38 @@ var useRouterContext = () => {
 	};
 };
 //#endregion
-export { Link, Router, createRouter, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext };
+//#region hooks/useSearchParams.ts
+var useSearchParams = () => {
+	const location = useLocation();
+	const navigate = useNavigate();
+	const locationRef = useLatest(location);
+	const searchString = useMemo(() => location.search ? location.search.replace("?", "") : location.pathname.split("?")?.[1] ?? "", [location.pathname, location.search]);
+	const searchParams = useMemo(() => new URLSearchParams(searchString), [searchString]);
+	const getSearchParams = useCallback((param) => {
+		const allValues = searchParams.getAll(param);
+		return allValues.length > 1 ? allValues : allValues[0] ?? "";
+	}, [searchParams]);
+	const navigateWithSearchParams = useCallback((params) => {
+		const newSearch = params.toString();
+		navigate({
+			pathname: locationRef.current.pathname,
+			search: newSearch ? `?${newSearch}` : ""
+		});
+	}, [locationRef, navigate]);
+	return {
+		searchParams,
+		getSearchParams,
+		setSearchParams: useCallback((param, value) => {
+			const search = locationRef.current.search || "";
+			const currentParams = new URLSearchParams(search);
+			if (typeof param === "string" && value !== void 0) {
+				currentParams.delete(param);
+				(Array.isArray(value) ? value : [value]).forEach((v) => currentParams.append(param, v));
+				navigateWithSearchParams(currentParams);
+			} else if (typeof param === "function") navigateWithSearchParams(param(currentParams));
+			else throw new Error("useSearchParams first argument must be either function or string");
+		}, [locationRef, navigateWithSearchParams])
+	};
+};
+//#endregion
+export { Link, Router, RouterProvider, createRouter, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext, useSearchParams };

package/dist/provider/Provider.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+import { type ActionsContextValue, type DataContextValue, type NavigationContextValue, PropsContextValue } from '../context/RouterProviderContext';
+type ProviderProps = PropsContextValue & NavigationContextValue & ActionsContextValue & DataContextValue & {
+    children: ReactNode;
+};
+export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, location, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/provider/ViewProvider.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+type ViewProviderProps = {
+    params: Record<string, string>;
+    children: ReactNode;
+};
+export declare const ViewProvider: ({ children, params }: ViewProviderProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/global.d.ts

@@ -16,7 +16,7 @@ export type ClientRouteItem = {
     staleTime?: number;
     beforeLoad?: (arg: {
         context: Record<string, unknown>;
-        redirect: (arg: Location) => Promise<void>;
+        redirect: (arg: Location | string) => Promise<void>;
         params: Record<string, string>;
     }) => Promise<unknown> | undefined;
     afterLoad?: (arg: {
@@ -42,10 +42,6 @@ export type UpdateBlockedRouteProps = {
     type: 'process' | 'reset' | 'charge' | 'unblock';
     payload?: string;
 };
-export type AnimationOptions = {
-    duration?: number;
-    name?: 'fade' | 'slide-left' | 'slide-right';
-};
 export type RevalidateCacheArgs = {
     pathname: string;
     routeItem?: RouteItem;

package/package.json

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

package/dist/provider/RouterProvider.d.ts

@@ -1,7 +0,0 @@
-import { type ReactNode } from 'react';
-import { type ActionsContextValue, type DataContextValue, type NavigationContextValue } from '../context/RouterContext';
-type RouterProviderProps = NavigationContextValue & ActionsContextValue & DataContextValue & {
-    children: ReactNode;
-};
-export declare const RouterProvider: ({ children, setContext, context, updateBlockedRoute, updateLocation, location, params, prefetchLoader, loaderCache, blockerState, }: RouterProviderProps) => import("react/jsx-runtime").JSX.Element;
-export {};