clear-react-router 1.6.5 → 1.6.8

package/README.md

@@ -47,7 +47,8 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback (for loader) |
 | `errorElement` | `ReactElement \| () => ReactElement` | Error fallback |
 | `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 |
+| `actions` | `({ params, context, invalidate, setContext }) => Record<string, (formData: FormData) => unknown \| Promise<unknown>>` | Defines route actions for data mutations. Actions receive `FormData`, can update context via `setContext`, and can refresh loader data using the router-provided `invalidate`. |
+
 
 ### `RouterProvider`
 
@@ -56,7 +57,6 @@ The root component that provides routing context to the application. Place stati
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `routes` | `RouteItem[]` | required | Array of route configurations |
-| `context` | `object` | `{}` | Initial context (user, theme, etc.) |
 | `children` | `ReactNode` | required | App content (must include `<Router />`) |
 
 ```tsx
@@ -86,6 +86,7 @@ Renders the current route's component. Must be placed inside `<RouterProvider>`.
 | `showFallbackOnAnimation` | `boolean \| undefined` | `false` | Show `loaderFallback` even when `isAnimated` is `true` (instead of spinner) |
 | `prefetch` | `'hover' \| 'render' \| 'viewport' \| 'none'` | `'hover'` | Default prefetch strategy for all `<Link>` components |
 | `hoverPrefetchDelay` | `number` | `150` | Delay in milliseconds before prefetching on hover (only for `'hover'` strategy) |
+| `context` | `object` | `{}` | Initial context (user, theme, etc.) |
 | `errorBoundary` | `ComponentType<{ children: ReactNode }>` | `undefined` | Custom error boundary component for catching render errors in route components |
 
 ```tsx
@@ -219,6 +220,114 @@ const routes = createRouter([
 ]);
 ```
 
+## Route Actions
+
+Defines route-specific actions for handling data mutations such as creating, updating, or deleting resources.
+
+Actions are available through the `Form` component and the `useAction` hook. After a successful action, the current route is automatically invalidated, causing both `beforeLoad` and `loader` to run again in the background.
+
+```tsx
+actions?: ({ context, params, invalidate, setContext }) => ({
+  save: async (formData) => {
+    await api.updatePost(params.id, formData);
+  },
+
+  remove: async () => {
+    await api.deletePost(params.id);
+  },
+})
+```
+
+#### Arguments
+
+| Property     | Type                                                | Description                                                                                  |
+| ------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `context`    | `Record<string, unknown>`                           | Current router context.                                                                      |
+| `params`     | `Record<string, string>`                            | Route parameters.                                                                            |
+| `invalidate` | `(path?: string) => Promise<void>`                  | Invalidates the current route or a specific route, re-running its `beforeLoad` and `loader`. |
+| `setContext` | `Dispatch<SetStateAction<Record<string, unknown>>>` | Updates the router context.                                                                  |
+
+#### Returns
+
+A record where each key is an action name and each value is a function accepting a `FormData` instance.
+
+These action names are referenced by both `Form` and `useAction`.
+
+```tsx
+<Form action="save" />
+
+const save = useAction('save');
+```
+
+
+Actions can be executed declaratively with `<Form />` or imperatively with `useAction()`.
+
+## Form
+
+`Form` automatically creates a `FormData` object, executes the specified route action, invalidates the current route, and optionally resets the form.
+
+`isSubmitting` value available inside the `Form` component from the `useFormContext` hook
+
+```tsx
+import { Form, useFormContext } from '../clear-router';
+
+const SubmitButton = () => {
+	const { isSubmitting } = useFormContext()
+	return <button disabled={isSubmitting} type='submit'>Save</button>
+}
+
+<Form action="save" onSuccess={() => console.log('Saved')} onError={console.error}>
+  <input name="title" />
+  <SubmitButton />
+</Form>
+
+```
+
+### Props
+
+| Prop        | Type                        | Description                                                                      |
+| ----------- | --------------------------- | -------------------------------------------------------------------------------- |
+| `action`    | `string`                    | Name of the route action to execute.                                             |
+| `onSuccess` | `(result: unknown) => void` | Called when the action completes successfully. Receives the action return value. |
+| `onError`   | `(error: unknown) => void`  | Called when the action throws.                                                   |
+| `autoReset` | `boolean`                   | Automatically resets the form after a successful submission. Default: `true`.    |
+
+During submission, `Form` exposes the current submission state through `useFormContext()`.
+
+After a successful action:
+
+* the current route is invalidated;
+* `beforeLoad` is executed again;
+* `loader` is executed again;
+* fresh loader data becomes available.
+
+## useAction
+
+`useAction` provides direct access to a route action without rendering a `<Form />`.
+
+```tsx
+const save = useAction('save');
+
+const handleClick = async () => {
+  const data = new FormData();
+
+  data.append('title', 'Hello');
+
+  await save(data);
+};
+```
+
+```tsx
+<button onClick={handleClick}>
+  Save
+</button>
+```
+
+`useAction` automatically invalidates the current route after a successful action, causing both `beforeLoad` and `loader` to run again in the background.
+
+This hook is useful when the mutation is triggered programmatically, such as from dialogs, context menus, drag-and-drop interactions, keyboard shortcuts, or custom UI components.
+
+
 ### Error Boundaries
 
 You can provide a custom error boundary to catch rendering errors in route components. This is useful for preventing the entire app from crashing when a specific route fails to render.
@@ -240,13 +349,15 @@ const App = () => (
 
 ### `useNavigate()`
 
-Returns function to navigate programmatically. Accepts a string (pathname), an object with `pathname`, `search`, and `state`, or `-1` to go back.
+Returns function to navigate programmatically. Accepts a string (pathname), an object of type Location, or `-1` to go back.
 
 ```tsx
+type Location = { pathname: string;	search?: string; state?: unknown }
+
 const navigate = useNavigate();
 
 navigate('/about');                                           // string
-navigate({ pathname: '/user/123', state: { from: 'home' } }); // object
+navigate({ pathname: '/user/123', state: { from: 'home' } }); // Location
 navigate(-1);                                                 // go back
 ```
 

package/dist/components/Form.d.ts

@@ -0,0 +1,9 @@
+import { PropsWithChildren } from 'react';
+type FormProps = {
+    action: string;
+    onSuccess?(arg: unknown): void;
+    onError?(arg: unknown): void;
+    autoReset?: boolean;
+};
+export declare const Form: ({ children, action: actionKey, onSuccess, onError, autoReset, }: PropsWithChildren<FormProps>) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Router.d.ts

@@ -1,2 +1,2 @@
 import { RouterProps } from '../types/global';
-export declare const Router: ({ isAnimated, animationDuration, spinner, preserveScroll, showFallbackOnAnimation, prefetch, hoverPrefetchDelay, errorBoundary: ErrorBoundary, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Router: ({ isAnimated, animationDuration, spinner, preserveScroll, showFallbackOnAnimation, prefetch, hoverPrefetchDelay, errorBoundary: ErrorBoundary, context: initialContext, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/RouterProvider.d.ts

@@ -3,7 +3,6 @@ import { RouteItem } from '../types/global';
 type RouteProviderProps = {
     children: ReactNode;
     routes: RouteItem[];
-    context?: Record<string, unknown>;
 };
-export declare const RouterProvider: ({ children, routes, context: initialContext }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const RouterProvider: ({ children, routes }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/context/FormContext.d.ts

@@ -0,0 +1,4 @@
+export type FormContextProps = {
+    isSubmitting: boolean;
+};
+export declare const FormContext: import("react").Context<FormContextProps>;

package/dist/context/RouterProviderContext.d.ts

@@ -1,22 +1,7 @@
-import { BlockerState, LoaderState, Location, RouteItem, RouteItemData, UpdateBlockedRouteProps } from '../types/global';
-export type NavigationContextValue = {
-    blockerState: BlockerState;
-    routeItemData: RouteItemData;
-    currentLoaderFallback: RouteItem['loaderFallback'];
-    isLoading: boolean;
-    loaderState: LoaderState;
-};
+import { Location } from '../types/global';
 export type ActionsContextValue = {
     updateLocation(route: Location): Promise<void>;
-    updateBlockedRoute(arg: UpdateBlockedRouteProps): void;
     prefetchLoader(arg: string): Promise<void>;
-    setContext(arg: object): void;
-    restoreScroll(): void;
-    invalidate(path?: string): void;
-};
-export type DataContextValue = {
-    context: Record<string, unknown>;
+    invalidate(path?: string): Promise<void>;
 };
 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/hooks/useAction.d.ts

@@ -0,0 +1 @@
+export declare const useAction: (actionKey: string, onError?: (args: unknown) => void) => (formData: FormData) => Promise<void>;

package/dist/hooks/useBlocker.d.ts

@@ -1,4 +1,4 @@
-import type { BlockerState } from '../types/global.ts';
+import { BlockerState } from '../types/global';
 type UseBlockerReturnValue = {
     state: BlockerState;
     process(): void;

package/dist/hooks/useFormContext.d.ts

@@ -0,0 +1 @@
+export declare const useFormContext: () => import("../context/FormContext").FormContextProps;

package/dist/hooks/useInvalidate.d.ts

@@ -1 +1 @@
-export declare const useInvalidate: () => (path?: string) => void;
+export declare const useInvalidate: () => (path?: string) => Promise<void>;

package/dist/hooks/useLoader.d.ts

@@ -1,11 +1,5 @@
-import { type Dispatch, type SetStateAction } from 'react';
 import type { LoaderState, RevalidateCacheArgs, RouteItem } from '../types/global';
-type UseLoaderParams = {
-    routes: RouteItem[];
-    context: Record<string, unknown>;
-    setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
-};
-export declare const useLoader: ({ routes, context, setContext }: UseLoaderParams) => {
+export declare const useLoader: (routes: RouteItem[]) => {
     prefetchLoader: (pathname: string) => Promise<void>;
     revalidateCache: ({ routeItem, pathname }: RevalidateCacheArgs) => Promise<unknown>;
     isCacheItemFresh: ({ routeItem, pathname }: {
@@ -13,6 +7,5 @@ export declare const useLoader: ({ routes, context, setContext }: UseLoaderParam
         pathname: string;
     }) => boolean;
     loaderStateRef: import("react").RefObject<LoaderState>;
-    clearTimestamp: (pathname: string) => void;
+    invalidate: (pathname?: string) => Promise<void>;
 };
-export {};

package/dist/hooks/useNavigate.d.ts

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

package/dist/hooks/useNavigation.d.ts

@@ -0,0 +1,13 @@
+import { RefObject } from 'react';
+import { LoaderState, Location, RevalidateCacheArgs, RouteItem } from '../types/global';
+type UseHandleNavigation = {
+    routes: RouteItem[];
+    revalidateCache(arg: RevalidateCacheArgs): Promise<unknown>;
+    isCacheItemFresh(arg: {
+        routeItem?: RouteItem;
+        pathname: string;
+    }): boolean;
+    loaderStateRef: RefObject<LoaderState>;
+};
+export declare const useNavigation: ({ routes, revalidateCache, isCacheItemFresh, loaderStateRef }: UseHandleNavigation) => (nextLocation: Location) => Promise<void>;
+export {};

package/dist/hooks/useRouterContext.d.ts

@@ -1,4 +1,4 @@
 export declare const useRouterContext: () => {
     context: Record<string, unknown>;
-    setContext: (arg: object) => void;
+    setContext: (action: Record<string, unknown> | ((prevState: Record<string, unknown>) => Record<string, unknown>)) => void;
 };

package/dist/hooks/useServiceContext.d.ts

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

package/dist/hooks/useSetInitialContext.d.ts

@@ -0,0 +1 @@
+export declare const useSetInitialContext: (initialContext?: Record<string, unknown>) => void;

package/dist/index.d.ts

@@ -1,17 +1,20 @@
 export { RouterProvider } from './components/RouterProvider';
 export { Router } from './components/Router';
 export { Link } from './components/Link';
+export { Form } from './components/Form';
 export { useNavigate } from './hooks/useNavigate';
 export { useParams } from './hooks/useParams';
 export { useLocation } from './hooks/useLocation';
 export { useLoaderState } from './hooks/useLoaderState';
 export { useInvalidate } from './hooks/useInvalidate';
 export { useBlocker } from './hooks/useBlocker';
+export { useAction } from './hooks/useAction';
 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 { useFormContext } from './hooks/useFormContext';
 export { adapter } from './utils/adapter';
 export { createRouter } from './utils/utils';
 export type { RouteItem, BlockerState, Location, AdapterType, RouterProps } from './types/global';

package/dist/index.js

@@ -4,8 +4,6 @@ var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).expor
 //#endregion
 //#region context/RouterProviderContext.ts
 var ActionsContext = createContext({});
-var DataContext = createContext({});
-var NavigationContext = createContext({});
 //#endregion
 //#region ../../node_modules/react/cjs/react-jsx-runtime.production.js
 /**
@@ -45,29 +43,14 @@ 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, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate }) => {
+var Provider = ({ children, updateLocation, prefetchLoader, invalidate }) => {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext.Provider, {
 		value: {
 			updateLocation,
-			updateBlockedRoute,
 			prefetchLoader,
-			setContext,
-			restoreScroll,
 			invalidate
 		},
-		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DataContext.Provider, {
-			value: { context },
-			children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NavigationContext.Provider, {
-				value: {
-					blockerState,
-					routeItemData,
-					currentLoaderFallback,
-					isLoading,
-					loaderState
-				},
-				children
-			})
-		})
+		children
 	});
 };
 //#endregion
@@ -80,10 +63,56 @@ var useLatest = (value) => {
 	return ref;
 };
 //#endregion
+//#region state/createState.ts
+var create = (initialState) => {
+	let state = initialState;
+	const subscribers = /* @__PURE__ */ new Set();
+	const getState = () => state;
+	const setState = (action) => {
+		const prevState = state;
+		const nextState = typeof action === "function" ? action(state) : action;
+		if (!Object.is(state, nextState)) {
+			state = nextState;
+			subscribers.forEach((listener) => listener(state, prevState));
+		}
+	};
+	const subscribe = (listener) => {
+		subscribers.add(listener);
+		return () => subscribers.delete(listener);
+	};
+	return {
+		subscribe,
+		getState,
+		setState
+	};
+};
+var useGlobalState = ({ subscribe, getState, setState }) => {
+	return [useSyncExternalStore(subscribe, getState), setState];
+};
+var createState = (initialState) => {
+	const store = create(initialState);
+	return () => useGlobalState(store);
+};
+//#endregion
 //#region constants.ts
 var emptyLoaderState = {};
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/typeof.js
+//#region state/state.ts
+var useIsLoading = createState(false);
+var useBlockedRoute = createState({
+	from: "",
+	to: ""
+});
+var useLoaderFallback = createState(void 0);
+var useRouteItemData = createState({
+	routeItem: void 0,
+	location: {}
+});
+var useCurrentLoaderState = createState(emptyLoaderState);
+var useScrollMap = createState({});
+var useContextState = createState({});
+//#endregion
+//#region \0@oxc-project+runtime@0.132.0/helpers/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -93,7 +122,7 @@ function _typeof(o) {
 	}, _typeof(o);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.132.0/helpers/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -105,13 +134,13 @@ function toPrimitive(t, r) {
 	return ("string" === r ? String : Number)(t);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.132.0/helpers/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.132.0/helpers/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -186,34 +215,19 @@ var comparePaths = (el, pathname) => {
 	return splitElementPath.every((item, index) => item === splitPathname[index + (index ? 1 : 0)]) && splitPathname.length === splitElementPath.length + paramsLength;
 };
 //#endregion
-//#region hooks/useHandleNavigation.ts
+//#region hooks/useNavigation.ts
 var ALL_LOCATIONS = "*";
-var useHandleNavigation = ({ routes, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp }) => {
+var useNavigation = ({ routes, revalidateCache, isCacheItemFresh, loaderStateRef }) => {
+	const [, setIsLoading] = useIsLoading();
+	const [, setScrollMap] = useScrollMap();
+	const [, setRouteItemData] = useRouteItemData();
+	const [, setLoaderState] = useCurrentLoaderState();
+	const [, setCurrentLoaderFallback] = useLoaderFallback();
+	const [context, setContext] = useContextState();
+	const [blockedRoute, setBlockedRoute] = useBlockedRoute();
 	const { isAnimated, showFallbackOnAnimation: showFallback } = routerConfig;
-	const [isLoading, setIsLoading] = useState(false);
-	const [blockedRoute, setBlockedRoute] = useState({
-		from: "",
-		to: ""
-	});
-	const [routeItemData, setRouteItemData] = useState({
-		routeItem: void 0,
-		location: {}
-	});
-	const [scrollMap, setScrollMap] = useState({});
-	const [currentLoaderFallback, setCurrentLoaderFallback] = useState();
-	const [loaderState, setLoaderState] = useState(emptyLoaderState);
 	const prevPathname = useRef("");
 	const navigationSeq = useRef(0);
-	const scrollMapLatest = useLatest(scrollMap);
-	const restoreScroll = useCallback(() => {
-		if (!prevPathname.current || !scrollMapLatest.current[prevPathname.current]) return;
-		requestAnimationFrame(() => {
-			window.scrollTo({
-				top: scrollMapLatest.current[prevPathname.current],
-				behavior: "smooth"
-			});
-		});
-	}, [scrollMapLatest]);
 	const navigation = useCallback((nextLocation, routeItem) => {
 		setRouteItemData({
 			routeItem,
@@ -226,7 +240,13 @@ var useHandleNavigation = ({ routes, context, revalidateCache, setContext, isCac
 		const fullPath = nextLocation.search ? `${nextLocation.pathname}${nextLocation.search}` : nextLocation.pathname;
 		if (fullPath === window.location.pathname + window.location.search) return;
 		history.pushState(null, "", fullPath);
-	}, [loaderStateRef]);
+	}, [
+		loaderStateRef,
+		setCurrentLoaderFallback,
+		setIsLoading,
+		setLoaderState,
+		setRouteItemData
+	]);
 	const transitionedNavigation = useCallback((nextLocation, routeItem) => {
 		if (!isAnimated) {
 			navigation(nextLocation, routeItem);
@@ -238,45 +258,6 @@ var useHandleNavigation = ({ routes, context, revalidateCache, setContext, isCac
 			navigation(nextLocation, routeItem);
 		}
 	}, [navigation, isAnimated]);
-	const invalidate = useCallback(async (pathname = routeItemData.location.pathname) => {
-		if (typeof pathname !== "string") return;
-		const routeItem = routes.find((el) => comparePaths(el, pathname));
-		const resultParams = getParamsObject({
-			params: routeItem?.params,
-			pathname
-		});
-		clearTimestamp(pathname);
-		try {
-			if (routeItem?.beforeLoad) await routeItem.beforeLoad({
-				context,
-				redirect: () => Promise.resolve(),
-				params: resultParams,
-				setContext
-			});
-			loaderStateRef.current = {
-				...loaderStateRef.current,
-				beforeLoadError: null
-			};
-		} catch (error) {
-			loaderStateRef.current = {
-				...loaderStateRef.current,
-				beforeLoadError: error
-			};
-		}
-		await revalidateCache({
-			routeItem,
-			pathname
-		});
-		if (pathname === routeItemData.location.pathname) setLoaderState(loaderStateRef.current);
-	}, [
-		clearTimestamp,
-		context,
-		loaderStateRef,
-		revalidateCache,
-		routeItemData.location.pathname,
-		routes,
-		setContext
-	]);
 	const navigationHandler = useCallback(async (nextLocation) => {
 		navigationSeq.current = navigationSeq.current + 1;
 		const seq = navigationSeq.current;
@@ -336,40 +317,20 @@ var useHandleNavigation = ({ routes, context, revalidateCache, setContext, isCac
 		});
 	}, [
 		context,
+		isAnimated,
+		isCacheItemFresh,
+		loaderStateRef,
 		revalidateCache,
 		routes,
-		transitionedNavigation,
 		setContext,
-		isCacheItemFresh,
-		isAnimated,
+		setCurrentLoaderFallback,
+		setIsLoading,
+		setScrollMap,
 		showFallback,
-		loaderStateRef
+		transitionedNavigation
 	]);
 	const setNextLocationRef = useLatest(navigationHandler);
-	const updateBlockedRoute = useCallback(({ type, payload = "" }) => setBlockedRoute((prevState) => {
-		if (prevState.from === payload && type === "charge") return prevState;
-		if (payload && prevState.from !== payload && type === "charge") return {
-			...prevState,
-			from: payload
-		};
-		if (type === "reset") return {
-			...prevState,
-			to: ""
-		};
-		if (type === "process") setNextLocationRef.current({ pathname: prevState.to });
-		if (!prevState.from && !prevState.to) return prevState;
-		return {
-			from: "",
-			to: ""
-		};
-	}), [setNextLocationRef]);
-	const updateLocation = useCallback(async (nextLocation) => {
-		if (blockedRoute.from) setBlockedRoute((prevState) => ({
-			...prevState,
-			to: nextLocation.pathname
-		}));
-		else await setNextLocationRef.current(nextLocation);
-	}, [blockedRoute.from, setNextLocationRef]);
+	const updateLocation = useCallback(async (nextLocation) => await setNextLocationRef.current(nextLocation), [setNextLocationRef]);
 	useEffect(() => {
 		const handler = async (event) => {
 			const newLocation = parseWindowLocation(event.target.location);
@@ -383,34 +344,28 @@ var useHandleNavigation = ({ routes, context, revalidateCache, setContext, isCac
 		};
 		window.addEventListener("popstate", handler);
 		return () => window.removeEventListener("popstate", handler);
-	}, [blockedRoute.from, setNextLocationRef]);
+	}, [
+		blockedRoute.from,
+		setBlockedRoute,
+		setNextLocationRef
+	]);
 	useEffect(() => {
 		const currentLocation = parseWindowLocation(window.location);
 		setNextLocationRef.current(currentLocation);
 		prevPathname.current = currentLocation.pathname;
 	}, [setNextLocationRef]);
-	return {
-		blockerState: useMemo(() => {
-			if (blockedRoute.from && blockedRoute.to) return "blocked";
-			if (blockedRoute.from) return "charged";
-			return "unblocked";
-		}, [blockedRoute]),
-		updateLocation,
-		updateBlockedRoute,
-		routeItemData,
-		restoreScroll,
-		currentLoaderFallback,
-		isLoading,
-		loaderState,
-		invalidate
-	};
+	return updateLocation;
 };
 //#endregion
 //#region hooks/useLoader.ts
-var useLoader = ({ routes, context, setContext }) => {
+var useLoader = (routes) => {
+	const [, setLoaderState] = useCurrentLoaderState();
+	const [routeItemData] = useRouteItemData();
+	const [context, setContext] = useContextState();
+	const loaderStateRef = useRef(emptyLoaderState);
+	const latestPathname = useLatest(routeItemData.location.pathname);
 	const timestampMapRef = useRef(/* @__PURE__ */ new Map());
 	const loaderMapRef = useRef({});
-	const loaderStateRef = useRef(emptyLoaderState);
 	const loadingPromises = useRef(/* @__PURE__ */ new Map());
 	const isCacheItemFresh = useCallback(({ routeItem, pathname }) => {
 		if (!routeItem) return true;
@@ -476,70 +431,64 @@ var useLoader = ({ routes, context, setContext }) => {
 		revalidateCache,
 		isCacheItemFresh,
 		loaderStateRef,
-		clearTimestamp: useCallback((pathname) => {
+		invalidate: useCallback(async (pathname = latestPathname.current) => {
+			if (typeof pathname !== "string") return;
+			const routeItem = routes.find((el) => comparePaths(el, pathname));
+			const resultParams = getParamsObject({
+				params: routeItem?.params,
+				pathname
+			});
 			timestampMapRef.current.delete(pathname);
-		}, [])
+			try {
+				if (routeItem?.beforeLoad) await routeItem.beforeLoad({
+					context,
+					redirect: () => Promise.resolve(),
+					params: resultParams,
+					setContext
+				});
+				loaderStateRef.current = {
+					...loaderStateRef.current,
+					beforeLoadError: null
+				};
+			} catch (error) {
+				loaderStateRef.current = {
+					...loaderStateRef.current,
+					beforeLoadError: error
+				};
+			}
+			await revalidateCache({
+				routeItem,
+				pathname
+			});
+			if (pathname === latestPathname.current) setLoaderState(loaderStateRef.current);
+		}, [
+			context,
+			loaderStateRef,
+			revalidateCache,
+			latestPathname,
+			routes,
+			setContext,
+			setLoaderState
+		])
 	};
 };
 //#endregion
 //#region components/RouterProvider.tsx
-var RouterProvider = ({ children, routes, context: initialContext = {} }) => {
-	const [context, setContext] = useState(initialContext);
-	const { prefetchLoader, revalidateCache, isCacheItemFresh, loaderStateRef, clearTimestamp } = useLoader({
-		routes,
-		context,
-		setContext
-	});
-	const { blockerState, updateLocation, updateBlockedRoute, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate } = useHandleNavigation({
-		routes,
-		context,
-		setContext,
-		revalidateCache,
-		isCacheItemFresh,
-		loaderStateRef,
-		clearTimestamp
-	});
+var RouterProvider = ({ children, routes }) => {
+	const { prefetchLoader, revalidateCache, isCacheItemFresh, loaderStateRef, invalidate } = useLoader(routes);
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
-		...useMemo(() => ({
-			updateLocation,
-			prefetchLoader,
-			updateBlockedRoute,
-			blockerState,
-			context,
-			setContext,
-			routeItemData,
-			restoreScroll,
-			currentLoaderFallback,
-			isLoading,
-			loaderState,
-			invalidate
-		}), [
-			blockerState,
-			context,
-			prefetchLoader,
-			routeItemData,
-			updateBlockedRoute,
-			updateLocation,
-			currentLoaderFallback,
-			restoreScroll,
-			isLoading,
-			loaderState,
-			invalidate
-		]),
+		updateLocation: useNavigation({
+			routes,
+			revalidateCache,
+			isCacheItemFresh,
+			loaderStateRef
+		}),
+		invalidate,
+		prefetchLoader,
 		children
 	});
 };
 //#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);
-//#endregion
 //#region hooks/useApplyCustomAnimation.ts
 var useApplyCustomAnimation = (animationDuration) => {
 	useEffect(() => {
@@ -579,8 +528,18 @@ var useApplyCustomAnimation = (animationDuration) => {
 //#endregion
 //#region hooks/usePreserveScroll.ts
 var usePreserveScroll = (preserveScroll) => {
-	const { restoreScroll } = useRouterActions();
-	const { routeItemData: { location: { pathname } } } = useNavigationState();
+	const [routeItemData] = useRouteItemData();
+	const [scrollMap] = useScrollMap();
+	const { pathname } = routeItemData.location;
+	const restoreScroll = useCallback(() => {
+		if (!pathname || !scrollMap[pathname]) return;
+		requestAnimationFrame(() => {
+			window.scrollTo({
+				top: scrollMap[pathname],
+				behavior: "smooth"
+			});
+		});
+	}, [pathname, scrollMap]);
 	useEffect(() => {
 		if (preserveScroll) restoreScroll();
 	}, [
@@ -595,6 +554,14 @@ var useSetRouterConfig = (routerProps) => {
 	useEffect(() => routerConfig.configure(routerProps), [routerProps]);
 };
 //#endregion
+//#region hooks/useSetInitialContext.ts
+var useSetInitialContext = (initialContext) => {
+	const [, setContext] = useContextState();
+	useEffect(() => {
+		if (initialContext) setContext(initialContext);
+	}, [initialContext, setContext]);
+};
+//#endregion
 //#region components/Spinner.tsx
 var Spinner = () => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "cr-spinner" });
 //#endregion
@@ -606,8 +573,11 @@ var renderElement = (Component) => {
 //#endregion
 //#region components/Router.tsx
 var EmptyBoundary = ({ children }) => children;
-var Router = ({ isAnimated, animationDuration, spinner = true, preserveScroll = true, showFallbackOnAnimation = false, prefetch = "hover", hoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary }) => {
-	const { routeItemData: { routeItem, location }, loaderState, currentLoaderFallback, isLoading } = useNavigationState();
+var Router = ({ isAnimated, animationDuration, spinner = true, preserveScroll = true, showFallbackOnAnimation = false, prefetch = "hover", hoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary, context: initialContext }) => {
+	const [isLoading] = useIsLoading();
+	const [currentLoaderFallback] = useLoaderFallback();
+	const [routeItemData] = useRouteItemData();
+	const [loaderState] = useCurrentLoaderState();
 	usePreserveScroll(preserveScroll);
 	useApplyCustomAnimation(animationDuration);
 	useSetRouterConfig({
@@ -616,9 +586,11 @@ var Router = ({ isAnimated, animationDuration, spinner = true, preserveScroll =
 		prefetch,
 		hoverPrefetchDelay
 	});
+	useSetInitialContext(initialContext);
 	const showErrorElement = !isLoading && Boolean(loaderState.loaderError || loaderState.beforeLoadError);
 	const showSpinner = spinner && isAnimated && isLoading;
 	const loadingContent = !showErrorElement && isLoading;
+	const { routeItem, location } = routeItemData;
 	if ((showFallbackOnAnimation || !isAnimated) && loadingContent) return renderElement(currentLoaderFallback);
 	if (!showFallbackOnAnimation && isAnimated && loadingContent) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {});
 	if (!routeItem) return null;
@@ -629,22 +601,45 @@ var Router = ({ isAnimated, animationDuration, spinner = true, preserveScroll =
 	});
 };
 //#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 useRouterActions = () => useServiceState(ActionsContext);
+//#endregion
 //#region hooks/useLocation.ts
 var useLocation = () => {
-	const { routeItemData: { location } } = useNavigationState();
-	return location;
+	const [routeItemData] = useRouteItemData();
+	return routeItemData.location;
 };
 //#endregion
 //#region hooks/useNavigate.ts
 var useNavigate = () => {
+	const [blockedRoute, setBlockedRoute] = useBlockedRoute();
 	const { updateLocation } = useRouterActions();
 	const locationRef = useLatest(useLocation());
+	const blockedRouteRef = useLatest(blockedRoute);
 	return useCallback(async (arg) => {
-		if (typeof arg === "number") return history.go(arg);
+		if (arg !== -1 && blockedRouteRef.current.from) {
+			const to = typeof arg === "object" ? arg.pathname : arg;
+			setBlockedRoute((prevState) => ({
+				...prevState,
+				to
+			}));
+			return;
+		}
+		if (arg === -1) 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]);
+	}, [
+		blockedRouteRef,
+		locationRef,
+		setBlockedRoute,
+		updateLocation
+	]);
 };
 //#endregion
 //#region components/Link.tsx
@@ -709,9 +704,16 @@ var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay }) => {
 	});
 };
 //#endregion
+//#region hooks/useInvalidate.ts
+var useInvalidate = () => {
+	const { invalidate } = useRouterActions();
+	return invalidate;
+};
+//#endregion
 //#region hooks/useParams.ts
 var useParams = () => {
-	const { routeItemData: { routeItem, location: { pathname } } } = useNavigationState();
+	const [routeItemData] = useRouteItemData();
+	const { routeItem, location: { pathname } } = routeItemData;
 	if (!routeItem) return void 0;
 	return getParamsObject({
 		params: routeItem?.params,
@@ -719,23 +721,89 @@ var useParams = () => {
 	});
 };
 //#endregion
+//#region context/FormContext.ts
+var FormContext = createContext({ isSubmitting: false });
+//#endregion
+//#region provider/FormProvider.tsx
+var FormProvider = ({ children, isSubmitting }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FormContext.Provider, {
+	value: { isSubmitting },
+	children
+});
+//#endregion
+//#region components/Form.tsx
+var Form = ({ children, action: actionKey, onSuccess, onError, autoReset = true }) => {
+	const invalidate = useInvalidate();
+	const [routeItemData] = useRouteItemData();
+	const [context, setContext] = useContextState();
+	const params = useParams();
+	const { routeItem } = routeItemData;
+	const [isSubmitting, setIsSubmitting] = useState(false);
+	const onSubmit = async (evt) => {
+		evt.preventDefault();
+		if (!routeItem) throw new Error("route not found");
+		if (!routeItem.actions) throw new Error("route action creator not found");
+		const action = routeItem.actions({
+			context,
+			setContext,
+			params,
+			invalidate
+		})[actionKey];
+		if (!action) throw new Error("action not found");
+		try {
+			setIsSubmitting(true);
+			const result = await action(new FormData(evt.target));
+			await invalidate();
+			if (autoReset) evt.target.reset();
+			onSuccess?.(result);
+		} catch (error) {
+			onError?.(error);
+		} finally {
+			setIsSubmitting(false);
+		}
+	};
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FormProvider, {
+		isSubmitting,
+		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("form", {
+			onSubmit,
+			children
+		})
+	});
+};
+//#endregion
 //#region hooks/useLoaderState.ts
 var useLoaderState = () => {
-	const { loaderState } = useNavigationState();
+	const [loaderState] = useCurrentLoaderState();
 	return loaderState;
 };
 //#endregion
-//#region hooks/useInvalidate.ts
-var useInvalidate = () => {
-	const { invalidate } = useRouterActions();
-	return invalidate;
-};
-//#endregion
 //#region hooks/useBlocker.ts
 var useBlocker = (blockerFn) => {
-	const { blockerState } = useNavigationState();
-	const { routeItemData: { location: { pathname } } } = useNavigationState();
-	const { updateBlockedRoute } = useRouterActions();
+	const [blockedRoute, setBlockedRoute] = useBlockedRoute();
+	const { updateLocation } = useRouterActions();
+	const [routeItemData] = useRouteItemData();
+	const { location: { pathname } } = routeItemData;
+	const updateBlockedRoute = useCallback(({ type, payload = "" }) => setBlockedRoute((prevState) => {
+		if (prevState.from === payload && type === "charge") return prevState;
+		if (payload && prevState.from !== payload && type === "charge") return {
+			...prevState,
+			from: payload
+		};
+		if (type === "reset") return {
+			...prevState,
+			to: ""
+		};
+		if (type === "process") updateLocation({ pathname: prevState.to });
+		if (!prevState.from && !prevState.to) return prevState;
+		return {
+			from: "",
+			to: ""
+		};
+	}), [setBlockedRoute, updateLocation]);
+	const blockerState = useMemo(() => {
+		if (blockedRoute.from && blockedRoute.to) return "blocked";
+		if (blockedRoute.from) return "charged";
+		return "unblocked";
+	}, [blockedRoute]);
 	const shouldBlock = blockerFn();
 	useEffect(() => updateBlockedRoute(shouldBlock ? {
 		type: "charge",
@@ -752,6 +820,41 @@ var useBlocker = (blockerFn) => {
 	};
 };
 //#endregion
+//#region hooks/useAction.ts
+var useAction = (actionKey, onError) => {
+	const invalidate = useInvalidate();
+	const [routeItemData] = useRouteItemData();
+	const [context, setContext] = useContextState();
+	const params = useParams();
+	const { routeItem } = routeItemData;
+	const latestContext = useLatest(context);
+	return useCallback(async (formData) => {
+		if (!routeItem) throw new Error("route not found");
+		if (!routeItem.actions) throw new Error("route action creator not found");
+		const action = routeItem.actions({
+			context: latestContext.current,
+			setContext,
+			params,
+			invalidate
+		})[actionKey];
+		if (!action) throw new Error("action not found");
+		try {
+			await action(formData);
+			await invalidate();
+		} catch (error) {
+			onError?.(error);
+		}
+	}, [
+		actionKey,
+		latestContext,
+		invalidate,
+		onError,
+		params,
+		routeItem,
+		setContext
+	]);
+};
+//#endregion
 //#region hooks/useBeforeUnload.ts
 var useBeforeUnload = (callback) => {
 	useEffect(() => {
@@ -767,8 +870,7 @@ var useBeforeUnload = (callback) => {
 //#endregion
 //#region hooks/useRouterContext.ts
 var useRouterContext = () => {
-	const { context } = useRouterData();
-	const { setContext } = useRouterActions();
+	const [context, setContext] = useContextState();
 	return {
 		context,
 		setContext
@@ -874,6 +976,9 @@ var useHistoricalTrail = () => {
 	return trail;
 };
 //#endregion
+//#region hooks/useFormContext.ts
+var useFormContext = () => useContext(FormContext);
+//#endregion
 //#region utils/adapter.ts
 var adapter = {
 	string: { parse: (params) => params[0] || "" },
@@ -936,4 +1041,4 @@ var adapter = {
 	})
 };
 //#endregion
-export { Link, Router, RouterProvider, adapter, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useInvalidate, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };
+export { Form, Link, Router, RouterProvider, adapter, createRouter, useAction, useBeforeUnload, useBlocker, useFormContext, useHistoricalTrail, useInvalidate, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };

package/dist/provider/FormProvider.d.ts

@@ -0,0 +1,3 @@
+import { PropsWithChildren } from 'react';
+import { FormContextProps } from '../context/FormContext';
+export declare const FormProvider: ({ children, isSubmitting }: PropsWithChildren<FormContextProps>) => import("react/jsx-runtime").JSX.Element;

package/dist/provider/Provider.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
-import { type ActionsContextValue, type DataContextValue, type NavigationContextValue } from '../context/RouterProviderContext';
-type ProviderProps = NavigationContextValue & ActionsContextValue & DataContextValue & {
+import { type ActionsContextValue } from '../context/RouterProviderContext';
+type ProviderProps = ActionsContextValue & {
     children: ReactNode;
 };
-export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Provider: ({ children, updateLocation, prefetchLoader, invalidate }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/state/createState.d.ts

@@ -0,0 +1,3 @@
+type SetStateAction<T> = ((prevState: T) => T) | T;
+export declare const createState: <T>(initialState: T) => () => readonly [T, (action: SetStateAction<T>) => void];
+export {};

package/dist/state/state.d.ts

@@ -0,0 +1,20 @@
+import { LoaderState, RouteItemData } from '../types/global';
+export declare const useIsLoading: () => readonly [boolean, (action: boolean | ((prevState: boolean) => boolean)) => void];
+export declare const useBlockedRoute: () => readonly [{
+    from: string;
+    to: string;
+}, (action: {
+    from: string;
+    to: string;
+} | ((prevState: {
+    from: string;
+    to: string;
+}) => {
+    from: string;
+    to: string;
+})) => void];
+export declare const useLoaderFallback: () => readonly [(import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement)) | undefined, (action: (import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement)) | ((prevState: (import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement)) | undefined) => (import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement)) | undefined) | undefined) => void];
+export declare const useRouteItemData: () => readonly [RouteItemData, (action: RouteItemData | ((prevState: RouteItemData) => RouteItemData)) => void];
+export declare const useCurrentLoaderState: () => readonly [LoaderState, (action: LoaderState | ((prevState: LoaderState) => LoaderState)) => void];
+export declare const useScrollMap: () => readonly [Record<string, number>, (action: Record<string, number> | ((prevState: Record<string, number>) => Record<string, number>)) => void];
+export declare const useContextState: () => readonly [Record<string, unknown>, (action: Record<string, unknown> | ((prevState: Record<string, unknown>) => Record<string, unknown>)) => void];

package/dist/types/global.d.ts

@@ -27,6 +27,12 @@ export type ClientRouteItem = {
         params: Record<string, string>;
         setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
     }) => Promise<void>;
+    actions?: (arg: {
+        context: Record<string, unknown>;
+        params: Record<string, string>;
+        invalidate: (path?: string) => Promise<void>;
+        setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
+    }) => Record<string, (arg: FormData) => Promise<unknown> | Promise<void> | void | unknown>;
 };
 export type RouteItem = ClientRouteItem & {
     element: Element;
@@ -42,10 +48,6 @@ export type Location = {
     state?: unknown;
 };
 export type BlockerState = 'blocked' | 'unblocked' | 'charged';
-export type UpdateBlockedRouteProps = {
-    type: 'process' | 'reset' | 'charge' | 'unblock';
-    payload?: string;
-};
 export type RevalidateCacheArgs = {
     pathname: string;
     routeItem?: RouteItem;
@@ -74,5 +76,6 @@ export type RouterProps = {
     errorBoundary?: ComponentType<{
         children: ReactNode;
     }>;
+    context?: Record<string, unknown>;
 };
 export {};

package/package.json

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

package/dist/hooks/useHandleNavigation.d.ts

@@ -1,26 +0,0 @@
-import { type Dispatch, RefObject, type SetStateAction } from 'react';
-import { BlockerState, LoaderState, Location, RevalidateCacheArgs, RouteItem, RouteItemData, UpdateBlockedRouteProps } from '../types/global';
-type UseHandleNavigation = {
-    routes: RouteItem[];
-    context: Record<string, unknown>;
-    revalidateCache(arg: RevalidateCacheArgs): Promise<unknown>;
-    setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
-    isCacheItemFresh(arg: {
-        routeItem?: RouteItem;
-        pathname: string;
-    }): boolean;
-    loaderStateRef: RefObject<LoaderState>;
-    clearTimestamp(path: string): void;
-};
-export declare const useHandleNavigation: ({ routes, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp, }: UseHandleNavigation) => {
-    blockerState: BlockerState;
-    updateLocation: (nextLocation: Location) => Promise<void>;
-    updateBlockedRoute: ({ type, payload }: UpdateBlockedRouteProps) => void;
-    routeItemData: RouteItemData;
-    restoreScroll: () => void;
-    currentLoaderFallback: (import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement)) | undefined;
-    isLoading: boolean;
-    loaderState: LoaderState;
-    invalidate: (pathname?: string) => Promise<void>;
-};
-export {};