clear-react-router 1.1.4 → 1.2.0

package/README.md

@@ -7,6 +7,7 @@ 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)
 - 🎯 **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
@@ -25,7 +26,7 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 | `path` | `string` | Route path, e.g., `/user/:userId` |
 | `element` | `ReactElement \| () => ReactElement \| LazyComponent` | Component to render |
 | `loader` | `() => Promise<unknown>` | Fetch data |
-| `beforeLoad` | `(context) => Promise<void>` | Auth checks, redirects |
+| `beforeLoad` | `({ context, redirect }) => Promise<void>` | Auth checks and redirects. `redirect` is provided by the router |
 | `afterLoad` | `(context) => Promise<void>` | Analytics, side effects |
 | `fallback` | `ReactElement \| () => ReactElement` | Loading fallback (for lazy loading) |
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback (for loader) |
@@ -37,10 +38,21 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 
 Main component that renders the application based on current URL.
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `routeList` | `RouteItem[]` | Array of route configurations |
-| `context` | `object` | Optional initial context (user, theme, etc.) |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `routeList` | `RouteItem[]` | required | Array of route configurations |
+| `context` | `object` | `{}` | Optional 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`) |
+
+**`AnimationOptions`:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `duration` | `number` | `300` | Animation duration in milliseconds |
+| `name` | `'fade' \| 'slide-left' \| 'slide-right'` | `'fade'` | Type of transition effect |
+
+> **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.
 
 ### `Link`
 
@@ -52,13 +64,26 @@ Component for client-side navigation with prefetch support.
 | `prefetch` | `boolean` | `true` |
 | `children` | `ReactElement` | required |
 
-### `redirect(url, search?)`
+### `redirect`
+
+Function provided to `beforeLoad` for programmatic redirection.
+
+**Type:** `(arg: Location) => Promise<void>`
 
-Redirects from `beforeLoad`.
 ```
-beforeLoad: context => {
-	if (!context.isAuthorized) return redirect('/');
-}
+import type { Location } from 'clear-react-router';
+
+const routes = createRouter([
+  {
+    path: '/dashboard',
+    element: <Dashboard />,
+    beforeLoad: ({ context, redirect }) => {
+      if (!context.isAuthorized) {
+        return redirect({ pathname: '/' });
+      }
+    },
+  },
+]);
 ```
 
 ## Hooks
@@ -149,6 +174,14 @@ const onSave = useCallback(() => {
 useBeforeUnload(text ? onSave : undefined);
 ```
 
+### `useRouterContext()`
+
+Handles router context.
+```
+const { setContext, context } = useRouterContext();
+const loginHandler = () => setContext({ ...context, user: { name: 'John' } });
+```
+
 ## Lazy Loading
 
 Clear Router supports code-splitting out of the box. Simply pass a function that returns a dynamic import:
@@ -159,10 +192,57 @@ Clear Router supports code-splitting out of the box. Simply pass a function that
   fallback: () => <div>Loading...</div>,
 }
 ```
+## Animations
+
+Clear Router supports smooth page transitions using the native View Transitions API. When animations are enabled, the router waits for all data to load before starting the transition, ensuring a jank-free experience.
+
+### Quick Start
+
+```
+import { Router } from 'clear-react-router';
+
+// Enable default fade animation
+<Router routeList={routes} isAnimated />
+
+// Custom animation
+<Router 
+  routeList={routes} 
+  isAnimated 
+  animationOptions={{ 
+    duration: 500,        // milliseconds
+    name: 'slide-left'    // 'fade' | 'slide-left' | 'slide-right'
+  }} 
+/>
+```
+
+## 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
+- **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:
+
+- Chrome/Edge 111+
+- Safari 18+
+- Firefox 144+
+
+For older browsers, the router gracefully falls back to regular navigation without animation.
 
 ## Requirements
 - React 16.6+ (for React.lazy and Suspense)
 - Use `default` export for your lazy-loaded components
 
- ## License
- MIT
+## License
+MIT

package/dist/clear-react-router.css

@@ -0,0 +1,23 @@
+._spinner_1tekw_1 {
+    position: fixed;
+    top: 5px;
+    left: 5px;
+    z-index: 9999;
+    width: 1rem;
+    height: 1rem;
+    border: 2px solid gray;
+    border-bottom-color: transparent;
+    border-radius: 50%;
+    display: inline-block;
+    box-sizing: border-box;
+    animation: _rotation_1tekw_1 1s linear infinite;
+}
+
+@keyframes _rotation_1tekw_1 {
+    0% {
+        transform: rotate(0deg);
+    }
+    100% {
+        transform: rotate(360deg);
+    }
+}/*$vite$:1*/

package/dist/components/Router.d.ts

@@ -1,7 +1,9 @@
-import type { RouteItem } from '../types/global.ts';
+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 }: RouterProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Router: ({ routeList, context: initialContext, isAnimated, animationOptions, }: RouterProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Spinner/Spinner.d.ts

@@ -0,0 +1 @@
+export declare const Spinner: () => import("react/jsx-runtime").JSX.Element;

package/dist/hooks/useApplyCustomAnimation.d.ts

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

package/dist/hooks/useHandleNavigation.d.ts

@@ -4,8 +4,9 @@ type UseHandleNavigation = {
     setLocation: (arg: Location) => void;
     context: Record<string, unknown>;
     revalidateCache(routeItem?: RouteItem, isCurrentRoute?: boolean): Promise<void>;
+    isAnimated: boolean;
 };
-export declare const useHandleNavigation: ({ setLocation, routeList, context, revalidateCache }: UseHandleNavigation) => {
+export declare const useHandleNavigation: ({ setLocation, routeList, context, revalidateCache, isAnimated, }: UseHandleNavigation) => {
     blockerState: BlockerState;
     updateLocation: (nextLocation: Location) => Promise<void>;
     updateBlockedRoute: ({ type, payload }: UpdateBlockedRouteProps) => void;

package/dist/hooks/useLocation.d.ts

@@ -1 +1 @@
-export declare const useLocation: () => import("../types/global").Location;
+export declare const useLocation: () => import("..").Location;

package/dist/index.d.ts

@@ -8,5 +8,4 @@ export { useBlocker } from './hooks/useBlocker';
 export { useBeforeUnload } from './hooks/useBeforeUnload';
 export { useRouterContext } from './hooks/useRouterContext';
 export { createRouter } from './utils/utils';
-export { redirect } from './utils/redirect';
-export type { RouteItem, BlockerState } from './types/global';
+export type { RouteItem, BlockerState, Location } from './types/global';

package/dist/index.js

@@ -37,6 +37,7 @@ var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((expor
 		};
 	}
 	exports.jsx = jsxProd;
+	exports.jsxs = jsxProd;
 }));
 //#endregion
 //#region provider/RouterProvider.tsx
@@ -129,37 +130,52 @@ var useLatest = (value) => {
 };
 //#endregion
 //#region hooks/useHandleNavigation.ts
-var isRedirect = (error) => typeof error === "object" && error !== null && error.cause === "redirect";
-var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache }) => {
+var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, isAnimated }) => {
 	const [blockedRoute, setBlockedRoute] = useState({
 		from: "",
 		to: ""
 	});
 	const prevPathname = useRef("");
-	const setNextLocationRef = useLatest(useCallback(async (nextLocation) => {
-		try {
-			const nextItem = routeList.find((el) => comparePaths(el, nextLocation.pathname));
-			if (nextItem?.beforeLoad) await nextItem?.beforeLoad(context);
-			setLocation(nextLocation);
-			prevPathname.current = nextLocation.pathname;
-			if (nextLocation.pathname !== window.location.pathname) history.pushState(null, "", nextLocation.pathname);
-			await revalidateCache(nextItem, true);
-			if (nextItem?.afterLoad) await nextItem?.afterLoad(context);
-		} catch (error) {
-			const redirect = error;
-			if (!isRedirect(redirect)) return redirect;
-			history.replaceState(null, "", redirect.url);
-			setLocation({
-				pathname: redirect.url,
-				search: redirect.search
-			});
+	const navigationSeq = useRef(0);
+	const navigation = useCallback((nextLocation) => {
+		setLocation(nextLocation);
+		prevPathname.current = nextLocation.pathname;
+		if (nextLocation.pathname === window.location.pathname) return;
+		history.pushState(null, "", nextLocation.pathname);
+	}, [setLocation]);
+	const transitionedNavigation = useCallback(({ nextLocation, isFirstCall, isAnimated }) => {
+		if (isAnimated && !isFirstCall) try {
+			document.startViewTransition(() => navigation(nextLocation));
+		} catch {
+			navigation(nextLocation);
 		}
+		else navigation(nextLocation);
+	}, [navigation]);
+	const setNextLocation = useCallback(async (nextLocation, isFirstCall) => {
+		navigationSeq.current = navigationSeq.current + 1;
+		const seq = navigationSeq.current;
+		const nextItem = routeList.find((el) => comparePaths(el, nextLocation.pathname));
+		if (nextItem?.beforeLoad) await nextItem.beforeLoad({
+			context,
+			redirect: setNextLocation
+		});
+		if (seq !== navigationSeq.current) return;
+		await revalidateCache(nextItem, true);
+		if (seq !== navigationSeq.current) return;
+		transitionedNavigation({
+			nextLocation,
+			isAnimated,
+			isFirstCall
+		});
+		if (nextItem?.afterLoad) await nextItem.afterLoad(context);
 	}, [
 		context,
+		isAnimated,
 		revalidateCache,
 		routeList,
-		setLocation
-	]));
+		transitionedNavigation
+	]);
+	const setNextLocationRef = useLatest(setNextLocation);
 	const updateBlockedRoute = useCallback(({ type, payload = "" }) => setBlockedRoute((prevState) => {
 		if (prevState.from === payload && type === "charge") return prevState;
 		if (payload && prevState.from !== payload && type === "charge") return {
@@ -200,7 +216,7 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache })
 	}, [blockedRoute.from, setNextLocationRef]);
 	useEffect(() => {
 		const currentLocation = parseWindowLocation(window.location);
-		setNextLocationRef.current(currentLocation);
+		setNextLocationRef.current(currentLocation, true);
 		prevPathname.current = currentLocation.pathname;
 	}, [setNextLocationRef]);
 	return {
@@ -265,6 +281,63 @@ var useLoader = (routeList) => {
 	};
 };
 //#endregion
+//#region hooks/useApplyCustomAnimation.ts
+var useApplyCustomAnimation = (animationOptions) => {
+	useEffect(() => {
+		if (!animationOptions?.duration) 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);
+    }`;
+		document.head.appendChild(style);
+		return () => style.remove();
+	}, [animationOptions]);
+};
+var Spinner_module_default = {
+	spinner: "_spinner_1tekw_1",
+	rotation: "_rotation_1tekw_1"
+};
+//#endregion
+//#region components/Spinner/Spinner.tsx
+var Spinner = () => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: Spinner_module_default.spinner });
+//#endregion
 //#region utils/renderElement.tsx
 var renderElement = (Component) => {
 	if (!Component) return null;
@@ -274,16 +347,18 @@ var renderElement = (Component) => {
 //#region components/Router.tsx
 var PAGE_NOT_FOUND = "error 404. Page not found";
 var ALL_LOCATIONS = "*";
-var Router = ({ routeList, context: initialContext = {} }) => {
+var Router = ({ routeList, context: initialContext = {}, isAnimated = false, animationOptions = {} }) => {
 	const [location, setLocation] = useState(parseWindowLocation(window.location));
 	const [context, setContext] = useState(initialContext);
+	useApplyCustomAnimation(animationOptions);
 	const routeItem = useMemo(() => routeList.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, location.pathname)), [location.pathname, routeList]);
 	const { loaderError, loaderCache, prefetchLoader, revalidateCache, isLoading } = useLoader(routeList);
 	const { blockerState, updateLocation, updateBlockedRoute } = useHandleNavigation({
 		setLocation,
 		routeList,
 		context,
-		revalidateCache
+		revalidateCache,
+		isAnimated
 	});
 	const params = useMemo(() => routeItem?.params ? getParamsObject(routeItem.params) : {}, [routeItem]);
 	const providerProps = useMemo(() => ({
@@ -306,7 +381,7 @@ var Router = ({ routeList, context: initialContext = {} }) => {
 		updateBlockedRoute,
 		updateLocation
 	]);
-	if (routeItem?.loader && !loaderError && isLoading) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RouterProvider, {
+	if (!isAnimated && routeItem?.loader && !loaderError && isLoading) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RouterProvider, {
 		...providerProps,
 		children: renderElement(routeItem?.loaderFallback)
 	});
@@ -314,9 +389,9 @@ var Router = ({ routeList, context: initialContext = {} }) => {
 		...providerProps,
 		children: renderElement(routeItem?.errorElement)
 	});
-	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RouterProvider, {
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(RouterProvider, {
 		...providerProps,
-		children: renderElement(routeItem?.element) || PAGE_NOT_FOUND
+		children: [renderElement(routeItem?.element) || PAGE_NOT_FOUND, isAnimated && isLoading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
 	});
 };
 //#endregion
@@ -415,55 +490,4 @@ var useRouterContext = () => {
 	};
 };
 //#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) {
-		return typeof o;
-	} : function(o) {
-		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
-	}, _typeof(o);
-}
-//#endregion
-//#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];
-	if (void 0 !== e) {
-		var i = e.call(t, r || "default");
-		if ("object" != _typeof(i)) return i;
-		throw new TypeError("@@toPrimitive must return a primitive value.");
-	}
-	return ("string" === r ? String : Number)(t);
-}
-//#endregion
-//#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.132.0/helpers/defineProperty.js
-function _defineProperty(e, r, t) {
-	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
-		value: t,
-		enumerable: !0,
-		configurable: !0,
-		writable: !0
-	}) : e[r] = t, e;
-}
-//#endregion
-//#region utils/redirect.ts
-var Redirect = class {
-	constructor(url, search) {
-		_defineProperty(this, "url", void 0);
-		_defineProperty(this, "search", void 0);
-		_defineProperty(this, "cause", void 0);
-		this.url = url;
-		this.search = search;
-		this.cause = "redirect";
-	}
-};
-var redirect = (url, search) => Promise.reject(new Redirect(url, search));
-//#endregion
-export { Link, Router, createRouter, redirect, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext };
+export { Link, Router, createRouter, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext };

package/dist/types/global.d.ts

@@ -11,7 +11,10 @@ export type ClientRouteItem = {
     fallback?: (() => ReactElement) | ReactElement;
     children?: ClientRouteItem[];
     staleTime?: number;
-    beforeLoad?: (context: Record<string, unknown>) => Promise<unknown> | undefined;
+    beforeLoad?: (arg: {
+        context: Record<string, unknown>;
+        redirect: (arg: Location) => Promise<void>;
+    }) => Promise<unknown> | undefined;
     afterLoad?: (context: Record<string, unknown>) => Promise<unknown> | undefined;
 };
 export type RouteItem = ClientRouteItem & {
@@ -32,3 +35,7 @@ export type UpdateBlockedRouteProps = {
     type: 'process' | 'reset' | 'charge' | 'unblock';
     payload?: string;
 };
+export type AnimationOptions = {
+    duration?: number;
+    name?: 'fade' | 'slide-left' | 'slide-right';
+};

package/package.json

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

package/dist/utils/redirect.d.ts

@@ -1,7 +0,0 @@
-export declare class Redirect {
-    url: string;
-    search?: string;
-    cause: 'redirect';
-    constructor(url: string, search?: string);
-}
-export declare const redirect: (url: string, search?: string) => Promise<never>;