clear-react-router 1.3.4 → 1.3.6

package/README.md

@@ -13,6 +13,7 @@ A lightweight, type-safe routing library for React applications with nested rout
 - 📦 **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)
+- 🔍 **Typed Query Param** — Type-safe reading and writing of URL query parameters with built-in parsers for strings, numbers, booleans, arrays, and Zod schemas
 - 🎨 **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
@@ -279,6 +280,114 @@ useBeforeUnload(text ? onSave : undefined);
 ```
 > **Note:** Pass `undefined` to disable the handler (e.g., if there is no changes).
 
+### `useQueryParam()`
+
+A flexible hook for working with typed query parameters. You provide a parser function, and it returns the parsed value and a setter.
+
+```
+import { useQueryParam, parser } from 'clear-react-router';
+
+const ProductPage = () => {
+  // String parameter
+  const [brand, setBrand] = useQueryParam('brand', parser.string, 'nike');
+
+  // Number parameter
+  const [page, setPage] = useQueryParam('page', parser.integer, 1);
+
+  // Boolean parameter
+  const [isActive, setIsActive] = useQueryParam('active', parser.boolean, false);
+
+  // Array of strings
+  const [colors, setColors] = useQueryParam('colors', parser.stringArray);
+
+  // Array of numbers
+  const [prices, setPrices] = useQueryParam('prices', parser.floatArray);
+
+  return (
+    <div>
+      <p>Brand: {brand}</p>
+      <p>Page: {page}</p>
+      <button onClick={() => setPage(page + 1)}>Next</button>
+    </div>
+  );
+}
+```
+**Signature:** `useQueryParam<T>(field: string, parser: (arg: string[]) => T, defaultValue?: T): [T, (arg: T) => void]`
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `field` | `string` | The query parameter key (e.g., `'page'`, `'brand'`) |
+| `parser` | `(arg: string[]) => T` | Function that transforms the raw string array into the desired type |
+| `defaultValue` | `T` (optional) | Default value returned when the parameter is missing or empty |
+
+**Returns:**
+
+| Element | Type | Description |
+|---------|------|-------------|
+| `value` | `T` | The parsed value from the query parameter |
+| `setValue` | `(arg: T) => void` | Function to update the query parameter |
+
+### Built-in Parsers
+
+| Parser | Input | Output | Description |
+|--------|-------|--------|-------------|
+| `parser.string` | `string[]` | `string` | First value or empty string |
+| `parser.stringArray` | `string[]` | `string[]` | All values as array |
+| `parser.integer` | `string[]` | `number` | First value parsed as integer (default: `0`) |
+| `parser.integerArray` | `string[]` | `number[]` | All values parsed as integers |
+| `parser.float` | `string[]` | `number` | First value parsed as float (default: `0`) |
+| `parser.floatArray` | `string[]` | `number[]` | All values parsed as floats |
+| `parser.boolean` | `string[]` | `boolean` | First value parsed as boolean (`'true'` → `true`) |
+| `parser.booleanArray` | `string[]` | `boolean[]` | All values parsed as booleans |
+
+### Using Zod Schemas
+`useQueryParam` works seamlessly with Zod for complex validation:
+
+```
+import { z } from 'zod';
+import { useQueryParam, parser } from 'clear-react-router';
+
+const filterSchema = z.object({
+  name: z.string(),
+  age: z.number().min(0),
+  active: z.boolean().optional(),
+});
+
+function ProductFilter() {
+  const [filter, setFilter] = useQueryParam(
+    'filter',
+    parser.zodSchema(filterSchema),
+    { name: '', age: 0 }
+  );
+
+  return (
+    <div>
+      <p>Name: {filter.name}</p>
+      <p>Age: {filter.age}</p>
+      <button onClick={() => setFilter({ ...filter, age: filter.age + 1 })}>
+        Increment Age
+      </button>
+    </div>
+  );
+}
+```
+
+### Custom Parsers
+You can write your own parser for any format:
+
+```
+// Custom parser for comma-separated values
+const csvParser = (params: string[]): string[] => {
+  const value = params[0] || '';
+  return value ? value.split(',').map(v => v.trim()) : [];
+};
+
+const TagsFilter() {
+  const [tags, setTags] = useQueryParam('tags', csvParser, []);
+  // tags: string[]
+}
+```
+
 ### `useRouterContext()`
 
 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.
@@ -327,13 +436,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/context/RouterProviderContext.d.ts

@@ -1,3 +1,4 @@
+import { Dispatch, SetStateAction } from 'react';
 import { BlockerState, Location, RouteItem, UpdateBlockedRouteProps } from '../types/global';
 export type PropsContextValue = {
     routeList: RouteItem[];
@@ -10,6 +11,7 @@ export type NavigationContextValue = {
     shouldErrorElementShown: boolean;
 };
 export type ActionsContextValue = {
+    setLocation: Dispatch<SetStateAction<Location>>;
     updateLocation(route: Location): Promise<void>;
     updateBlockedRoute(arg: UpdateBlockedRouteProps): void;
     prefetchLoader(arg: string): Promise<void>;

package/dist/hooks/useHistoricalTrail.d.ts

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

package/dist/hooks/useQueryParam.d.ts

@@ -0,0 +1 @@
+export declare function useQueryParam<T>(field: string, parser: (arg: string[]) => T, defaultValue?: T): [T, (arg: T) => void];

package/dist/index.d.ts

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

package/dist/index.js

@@ -45,7 +45,7 @@ var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((expor
 var import_jsx_runtime = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = require_react_jsx_runtime_production();
 })))();
-var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, location, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated }) => {
+var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, location, setLocation, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated }) => {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PropsContext.Provider, {
 		value: {
 			routeList,
@@ -53,6 +53,7 @@ var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocat
 		},
 		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext.Provider, {
 			value: {
+				setLocation,
 				updateLocation,
 				updateBlockedRoute,
 				prefetchLoader,
@@ -431,6 +432,7 @@ var RouterProvider = ({ children, routeList, context: initialContext = {}, isAni
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
 		...useMemo(() => ({
 			location,
+			setLocation,
 			updateLocation,
 			loaderCache,
 			prefetchLoader,
@@ -611,7 +613,7 @@ var useRouterContext = () => {
 //#region hooks/useSearchParams.ts
 var useSearchParams = () => {
 	const location = useLocation();
-	const navigate = useNavigate();
+	const { setLocation } = useRouterActions();
 	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]);
@@ -621,11 +623,14 @@ var useSearchParams = () => {
 	}, [searchParams]);
 	const navigateWithSearchParams = useCallback((params) => {
 		const newSearch = params.toString();
-		navigate({
-			pathname: locationRef.current.pathname,
-			search: newSearch ? `?${newSearch}` : ""
-		});
-	}, [locationRef, navigate]);
+		const { pathname } = locationRef.current;
+		const search = newSearch ? `?${newSearch}` : "";
+		setLocation((prevState) => ({
+			...prevState,
+			search
+		}));
+		history.replaceState(null, "", pathname + search);
+	}, [locationRef, setLocation]);
 	return {
 		searchParams,
 		getSearchParams,
@@ -642,4 +647,71 @@ var useSearchParams = () => {
 	};
 };
 //#endregion
-export { Link, Router, RouterProvider, createRouter, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext, useSearchParams };
+//#region hooks/useQueryParam.ts
+function useQueryParam(field, parser, defaultValue) {
+	const { searchParams, setSearchParams } = useSearchParams();
+	return [useMemo(() => {
+		const result = parser(searchParams.getAll(field));
+		if (result !== void 0 && result !== null && result !== "") return result;
+		if (defaultValue !== void 0) return defaultValue;
+		return result;
+	}, [
+		field,
+		parser,
+		searchParams,
+		defaultValue
+	]), useCallback((value) => {
+		setSearchParams(field, (typeof value === "object" ? JSON.stringify : String)(value));
+	}, [setSearchParams, field])];
+}
+//#endregion
+//#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
+//#region utils/parser.ts
+var parser = {
+	string: (params) => params[0] || "",
+	stringArray: (params) => params,
+	integer: (params) => {
+		const result = parseInt(params[0] || "", 10);
+		return isNaN(result) ? 0 : result;
+	},
+	integerArray: (params) => params.map((el) => {
+		const result = parseInt(el, 10);
+		return isNaN(result) ? 0 : result;
+	}),
+	float: (params) => {
+		const result = parseFloat(params[0] || "");
+		return isNaN(result) ? 0 : result;
+	},
+	floatArray: (params) => params.map((el) => {
+		const result = parseFloat(el);
+		return isNaN(result) ? 0 : result;
+	}),
+	boolean: (params) => params[0]?.toLowerCase() === "true",
+	booleanArray: (params) => params.map((el) => el.toLowerCase() === "true"),
+	zodSchema: (schema) => (params) => {
+		let parsed;
+		try {
+			parsed = JSON.parse(params[0] ?? "{}");
+		} catch {
+			throw new Error("Invalid JSON");
+		}
+		const result = schema.safeParse(parsed);
+		if (!result.success) throw new Error("Invalid schema");
+		return result.data;
+	}
+};
+//#endregion
+export { Link, Router, RouterProvider, createRouter, parser, useBeforeUnload, useBlocker, useHistoricalTrail, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };

package/dist/provider/Provider.d.ts

@@ -3,5 +3,5 @@ import { type ActionsContextValue, type DataContextValue, type NavigationContext
 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 declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, location, setLocation, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/utils/parser.d.ts

@@ -0,0 +1,21 @@
+type ZodInterface<T> = {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+};
+export declare const parser: {
+    string: (params: string[]) => string;
+    stringArray: (params: string[]) => string[];
+    integer: (params: string[]) => number;
+    integerArray: (params: string[]) => number[];
+    float: (params: string[]) => number;
+    floatArray: (params: string[]) => number[];
+    boolean: (params: string[]) => boolean;
+    booleanArray: (params: string[]) => boolean[];
+    zodSchema: <T>(schema: ZodInterface<T>) => (params: string[]) => T;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "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",