what-router 0.5.3 → 0.5.5

package/README.md

@@ -0,0 +1,188 @@
+# what-router
+
+Client-side router for [What Framework](https://whatfw.com). Supports dynamic routes, nested layouts, route groups, middleware, View Transitions API, scroll restoration, and prefetching.
+
+## Install
+
+```bash
+npm install what-router what-core
+```
+
+Or use via the main package:
+
+```js
+import { Router, Link, navigate } from 'what-framework/router';
+```
+
+## Quick Start
+
+```jsx
+import { mount } from 'what-framework';
+import { Router, Link, navigate } from 'what-router';
+
+function Home() {
+  return <h1>Home</h1>;
+}
+
+function User({ params }) {
+  return <h1>User {params.id}</h1>;
+}
+
+function App() {
+  return (
+    <div>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/users/1">User 1</Link>
+      </nav>
+      <Router
+        routes={[
+          { path: '/', component: Home },
+          { path: '/users/:id', component: User },
+        ]}
+      />
+    </div>
+  );
+}
+
+mount(<App />, '#app');
+```
+
+## Route Patterns
+
+```js
+{ path: '/users/:id', component: User }       // Dynamic param
+{ path: '/docs/*', component: DocsLayout }     // Catch-all
+{ path: '/blog/[slug]', component: Post }      // File-based syntax
+{ path: '/[...rest]', component: CatchAll }    // Named catch-all
+```
+
+## Navigation
+
+```js
+import { navigate, route } from 'what-router';
+
+// Programmatic navigation
+navigate('/dashboard');
+navigate('/login', { replace: true });
+navigate('/page', { transition: false }); // skip View Transition
+
+// Reactive route state
+route.path;       // current path
+route.params;     // { id: '123' }
+route.query;      // { page: '1' }
+route.hash;       // '#section'
+route.isNavigating;
+```
+
+## Link Component
+
+```jsx
+<Link href="/about">About</Link>
+<Link href="/about" activeClass="active" exactActiveClass="exact-active">About</Link>
+<Link href="/about" replace prefetch={false}>About</Link>
+```
+
+Links automatically get `active` and `exact-active` CSS classes based on the current route. Hover prefetching is enabled by default.
+
+## Nested Layouts
+
+```js
+import { defineRoutes, nestedRoutes, Outlet } from 'what-router';
+
+function DashboardLayout({ children }) {
+  return (
+    <div>
+      <Sidebar />
+      <main>{children}</main>
+    </div>
+  );
+}
+
+const routes = [
+  ...nestedRoutes('/dashboard', [
+    { path: '/', component: DashboardHome },
+    { path: '/settings', component: Settings },
+  ], { layout: DashboardLayout }),
+];
+```
+
+## Route Guards & Middleware
+
+```js
+import { guard, asyncGuard } from 'what-router';
+
+// Sync guard
+const requireAuth = guard(
+  () => isLoggedIn(),
+  '/login' // redirect on failure
+);
+
+const ProtectedPage = requireAuth(Dashboard);
+
+// Async guard
+const requireRole = asyncGuard(
+  async () => await checkPermission('admin'),
+  { fallback: '/unauthorized', loading: Spinner }
+);
+
+// Route-level middleware
+{
+  path: '/admin',
+  component: AdminPanel,
+  middleware: [authMiddleware, roleMiddleware],
+}
+```
+
+## View Transitions
+
+Navigation uses the View Transitions API by default when available. Use helpers to customize:
+
+```js
+import { viewTransitionName, setViewTransition } from 'what-router';
+
+// Name elements for transitions
+<img {...viewTransitionName('hero-image')} src={url} />
+
+// Set transition type
+setViewTransition('slide');
+```
+
+## Scroll Restoration
+
+```js
+import { enableScrollRestoration } from 'what-router';
+
+enableScrollRestoration(); // call once at app entry
+```
+
+## API
+
+| Export | Description |
+|---|---|
+| `Router` | Route matching component |
+| `Link` / `NavLink` | Navigation link with active states |
+| `navigate(to, opts?)` | Programmatic navigation |
+| `route` | Reactive route state object |
+| `useRoute()` | Hook returning computed route properties |
+| `defineRoutes(config)` | Create routes from flat object |
+| `nestedRoutes(base, children, opts?)` | Nested route helper |
+| `routeGroup(name, routes, opts?)` | Group routes without affecting URL |
+| `guard(check, fallback)` | Sync route guard |
+| `asyncGuard(check, opts?)` | Async route guard |
+| `Redirect` | Redirect component |
+| `Outlet` | Nested route outlet |
+| `FileRouter` | File-based router component |
+| `prefetch(href)` | Prefetch a route's assets |
+| `enableScrollRestoration()` | Enable scroll position restoration |
+| `viewTransitionName(name)` | View Transition name helper |
+| `setViewTransition(type)` | Set View Transition type |
+
+## Links
+
+- [Documentation](https://whatfw.com)
+- [GitHub](https://github.com/CelsianJs/whatfw)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-router",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "What Framework - File-based & programmatic router with View Transitions",
   "type": "module",
   "main": "src/index.js",
@@ -23,17 +23,17 @@
     "spa",
     "what-framework"
   ],
-  "author": "",
+  "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",
   "peerDependencies": {
     "what-core": "^0.5.3"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/zvndev/what-fw"
+    "url": "https://github.com/CelsianJs/whatfw"
   },
   "bugs": {
-    "url": "https://github.com/zvndev/what-fw/issues"
+    "url": "https://github.com/CelsianJs/whatfw/issues"
   },
-  "homepage": "https://whatframework.dev"
+  "homepage": "https://whatfw.com"
 }

package/src/index.js

@@ -28,19 +28,25 @@ export const route = {
 // --- Navigation with View Transitions ---
 
 export async function navigate(to, opts = {}) {
-  const { replace = false, state = null, transition = true } = opts;
+  const { replace = false, state = null, transition = true, _fromPopstate = false } = opts;
 
   // Don't navigate if already on the same URL
   if (to === _url()) return;
 
+  // Prevent concurrent navigations — wait for current to finish
+  if (_isNavigating.peek()) return;
+
   _isNavigating.set(true);
   _navigationError.set(null);
 
   const doNavigation = () => {
-    if (replace) {
-      history.replaceState(state, '', to);
-    } else {
-      history.pushState(state, '', to);
+    // Skip history manipulation on popstate (browser already updated the URL)
+    if (!_fromPopstate) {
+      if (replace) {
+        history.replaceState(state, '', to);
+      } else {
+        history.pushState(state, '', to);
+      }
     }
     _url.set(to);
     _isNavigating.set(false);
@@ -58,10 +64,12 @@ export async function navigate(to, opts = {}) {
   }
 }
 
-// Back/forward support
+// Back/forward support — route through navigate() so middleware runs
 if (typeof window !== 'undefined') {
   window.addEventListener('popstate', () => {
-    _url.set(location.pathname + location.search + location.hash);
+    const newUrl = location.pathname + location.search + location.hash;
+    // Use _fromPopstate flag so navigate() skips pushState (browser already updated URL)
+    navigate(newUrl, { replace: true, _fromPopstate: true, transition: false });
   });
 }
 
@@ -138,7 +146,19 @@ function parseQuery(search) {
   const qs = search.startsWith('?') ? search.slice(1) : search;
   for (const pair of qs.split('&')) {
     const [key, val] = pair.split('=');
-    if (key) params[decodeURIComponent(key)] = val ? decodeURIComponent(val) : '';
+    if (!key) continue;
+    const decodedKey = decodeURIComponent(key);
+    const decodedVal = val ? decodeURIComponent(val) : '';
+    if (decodedKey in params) {
+      // Collect repeated keys into arrays
+      if (Array.isArray(params[decodedKey])) {
+        params[decodedKey].push(decodedVal);
+      } else {
+        params[decodedKey] = [params[decodedKey], decodedVal];
+      }
+    } else {
+      params[decodedKey] = decodedVal;
+    }
   }
   return params;
 }
@@ -174,6 +194,10 @@ function buildLayoutChain(route, routes) {
   return layouts;
 }
 
+// --- Middleware redirect loop detection ---
+const _redirectHistory = [];
+const MAX_REDIRECTS = 10;
+
 // --- Router Component ---
 
 export function Router({ routes, fallback, globalLayout }) {
@@ -203,12 +227,43 @@ export function Router({ routes, fallback, globalLayout }) {
           return h('div', { class: 'what-403' }, h('h1', null, '403'), h('p', null, 'Access denied'));
         }
         if (typeof result === 'string') {
+          // Redirect loop detection
+          _redirectHistory.push(result);
+          if (_redirectHistory.length > MAX_REDIRECTS) {
+            const cycle = _redirectHistory.slice(-5).join(' → ');
+            _redirectHistory.length = 0;
+            console.error(`[what-router] Redirect loop detected: ${cycle}`);
+            _isNavigating.set(false);
+            return h('div', { class: 'what-redirect-loop' },
+              h('h1', null, 'Redirect Loop'),
+              h('p', null, 'Too many redirects. Check your middleware configuration.')
+            );
+          }
+          // Check for direct cycle (A → B → A)
+          const seen = new Set();
+          let hasCycle = false;
+          for (const url of _redirectHistory) {
+            if (seen.has(url)) { hasCycle = true; break; }
+            seen.add(url);
+          }
+          if (hasCycle) {
+            const cycle = _redirectHistory.join(' → ');
+            _redirectHistory.length = 0;
+            console.error(`[what-router] Redirect cycle detected: ${cycle}`);
+            _isNavigating.set(false);
+            return h('div', { class: 'what-redirect-loop' },
+              h('h1', null, 'Redirect Loop'),
+              h('p', null, 'Circular redirect detected. Check your middleware configuration.')
+            );
+          }
           // Middleware returned a redirect path
           navigate(result, { replace: true });
           return null;
         }
       }
     }
+    // Successful render — clear redirect history
+    _redirectHistory.length = 0;
 
     // Build element with loading state support
     let element;
@@ -265,11 +320,13 @@ export function Link({
   ...rest
 }) {
   const currentPath = route.path;
+  // Strip query string and hash from href for path comparison
+  const hrefPath = href.split('?')[0].split('#')[0];
   // Segment-boundary matching: '/blog' matches '/blog/123' but not '/blog-archive'
-  const isActive = href === '/'
+  const isActive = hrefPath === '/'
     ? currentPath === '/'
-    : currentPath === href || currentPath.startsWith(href + '/');
-  const isExactActive = currentPath === href;
+    : currentPath === hrefPath || currentPath.startsWith(hrefPath + '/');
+  const isExactActive = currentPath === hrefPath;
 
   const classes = [
     cls || className,
@@ -379,14 +436,20 @@ export function asyncGuard(check, options = {}) {
     return function AsyncGuardedRoute(props) {
       const status = signal('pending');
       const checkResult = signal(null);
+      let cancelled = false;
 
       effect(() => {
+        cancelled = false;
         Promise.resolve(check(props))
           .then(result => {
+            if (cancelled) return;
             checkResult.set(result);
             status.set(result ? 'allowed' : 'denied');
           })
-          .catch(() => status.set('denied'));
+          .catch(() => {
+            if (!cancelled) status.set('denied');
+          });
+        return () => { cancelled = true; };
       });
 
       const currentStatus = status();