@uistate/router 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 UIstate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# @uistate/router
+
+SPA router for EventState stores. Routing is just state.
+
+`navigate()` writes to store paths. Components subscribe. No framework required.
+
+## Install
+
+```bash
+npm install @uistate/router
+```
+
+## Quick Start
+
+```js
+import { createEventState } from '@uistate/core';
+import { createRouter } from '@uistate/router';
+
+const store = createEventState({ state: {} });
+
+const router = createRouter({
+  routes: [
+    { path: '/', view: 'home', component: HomeView },
+    { path: '/users', view: 'users', component: UsersView },
+    { path: '/users/:id', view: 'user', component: UserView },
+    { path: '/users/:id/posts/:postId', view: 'post', component: PostView },
+  ],
+  store,
+  fallback: { path: '/*', view: '404', component: NotFoundView },
+  debug: true,
+});
+
+router.start();
+```
+
+## How It Works
+
+Every navigation writes to the store:
+
+| Store Path | Value |
+|---|---|
+| `ui.route.view` | The matched `view` string (e.g. `'user'`) |
+| `ui.route.path` | The normalized path (e.g. `'/users/42'`) |
+| `ui.route.params` | Extracted params (e.g. `{ id: '42' }`) |
+| `ui.route.query` | Parsed query params (e.g. `{ tab: 'posts' }`) |
+| `ui.route.transitioning` | `true` during navigation, `false` after |
+
+Your components subscribe to these paths like any other state:
+
+```js
+store.subscribe('ui.route.view', (view) => {
+  console.log('View changed to:', view);
+});
+
+store.subscribe('ui.route.params', (params) => {
+  console.log('Route params:', params);
+});
+
+// Wildcard: react to any route change
+store.subscribe('ui.route.*', ({ path, value }) => {
+  console.log('Route state changed:', path, value);
+});
+```
+
+## Route Patterns
+
+Routes support static paths and dynamic `:param` segments:
+
+```js
+{ path: '/',                view: 'home' }       // exact match
+{ path: '/users',           view: 'users' }      // exact match
+{ path: '/users/:id',       view: 'user' }       // dynamic segment
+{ path: '/posts/:id/edit',  view: 'edit-post' }  // mixed
+```
+
+Params are extracted and available at `ui.route.params`:
+
+```js
+// URL: /users/42
+store.get('ui.route.params');  // { id: '42' }
+```
+
+## View Components
+
+A view component is any object with a `boot` method:
+
+```js
+const UserView = {
+  async boot({ store, el, signal, params }) {
+    el.innerHTML = `<h1>User ${params.id}</h1>`;
+
+    // Use signal for cleanup-aware async work
+    const res = await fetch(`/api/users/${params.id}`, { signal });
+    const user = await res.json();
+    el.innerHTML = `<h1>${user.name}</h1>`;
+
+    // Return an unboot function for cleanup
+    return () => {
+      console.log('UserView unmounted');
+    };
+  }
+};
+```
+
+The `boot` function receives:
+
+| Param | Description |
+|---|---|
+| `store` | The EventState store instance |
+| `el` | The root DOM element (from `rootSelector`) |
+| `signal` | An `AbortSignal` — aborted if the user navigates away before boot finishes |
+| `params` | Extracted route params (e.g. `{ id: '42' }`) |
+
+## API
+
+### `createRouter(config)`
+
+Returns a router instance.
+
+**Config options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `routes` | `Array` | `[]` | Route definitions |
+| `store` | `Object` | — | EventState store |
+| `rootSelector` | `string` | `'[data-route-root]'` | CSS selector for the mount point |
+| `fallback` | `Object` | `null` | Fallback route for unmatched paths |
+| `debug` | `boolean` | `false` | Log navigation to console |
+| `linkSelector` | `string` | `'a[data-link]'` | Selector for intercepted link clicks |
+
+### Router Instance
+
+#### `router.start()`
+
+Starts listening for link clicks and popstate events. Immediately navigates to the current URL.
+
+#### `router.stop()`
+
+Removes event listeners and calls the current view's unboot function.
+
+#### `router.navigate(pathname, opts?)`
+
+Programmatic navigation.
+
+```js
+router.navigate('/users/42');
+router.navigate('/search', { search: '?q=hello' });
+router.navigate('/users', { replace: true });
+```
+
+Options: `{ replace, search, restoreScroll }`
+
+#### `router.navigateQuery(patch, opts?)`
+
+Patch query parameters without changing the path.
+
+```js
+router.navigateQuery({ tab: 'posts' });           // add/update
+router.navigateQuery({ tab: null });               // remove
+router.navigateQuery({ page: '2', sort: 'name' }); // multiple
+```
+
+#### `router.getCurrent()`
+
+Returns `{ view, path, search }` for the current route.
+
+## Link Interception
+
+Any `<a>` matching `linkSelector` (default: `a[data-link]`) is intercepted for client-side navigation:
+
+```html
+<nav>
+  <a href="/" data-link>Home</a>
+  <a href="/users" data-link>Users</a>
+  <a href="/users/42" data-link>User 42</a>
+</nav>
+
+<div data-route-root></div>
+```
+
+Standard browser behavior is preserved for:
+- External links (different origin)
+- Modified clicks (Ctrl, Cmd, Shift, Alt, right-click)
+- Links without `data-link`
+
+## Active Nav (Subscribe, Don't Bake In)
+
+The router does **not** manage active nav styles. Instead, subscribe to the route path and manage your own UI:
+
+```js
+store.subscribe('ui.route.path', (path) => {
+  document.querySelectorAll('nav a[data-link]').forEach(a => {
+    const href = new URL(a.getAttribute('href'), location.href).pathname;
+    a.classList.toggle('active', href === path);
+  });
+});
+```
+
+This keeps the router focused on state. Your nav, your rules.
+
+## Base Path Support
+
+If your app is served from a subdirectory, add a `<base>` tag:
+
+```html
+<base href="/my-app/">
+```
+
+The router automatically detects it and adjusts all path operations.
+
+## Scroll Restoration
+
+The router saves scroll positions per route and restores them on back/forward navigation. Forward navigation scrolls to top.
+
+## Accessibility
+
+On every navigation, the router:
+1. Sets `tabindex="-1"` on the root element (if not already set)
+2. Focuses the root element (with `preventScroll`)
+
+This ensures screen readers announce the new content.
+
+## CSS Hooks
+
+The router sets attributes on `<html>` for CSS-driven transitions:
+
+```css
+/* Style based on current view */
+[data-view="home"] .hero { display: block; }
+[data-view="user"] .sidebar { display: flex; }
+
+/* Transition states */
+[data-transitioning="on"] [data-route-root] {
+  opacity: 0.5;
+  pointer-events: none;
+}
+```
+
+## Philosophy
+
+Routing is not special. It's a `set` call to a path in a JSON tree. The router writes `ui.route.*`, and anything that cares about routing subscribes to `ui.route.*`. The router doesn't know about your nav, your breadcrumbs, your analytics, or your loading spinners. They all subscribe independently. That's UIState: EventState + Routing.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1 @@
+export { createRouter } from './router.js';

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@uistate/router",
+  "version": "1.0.0",
+  "description": "SPA router for EventState stores — routing is just state",
+  "main": "index.js",
+  "module": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "router.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "router",
+    "spa",
+    "eventstate",
+    "uistate",
+    "state-management",
+    "path-based",
+    "vanilla-js",
+    "framework-agnostic"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ImsirovicAjdin/uistate-router"
+  },
+  "homepage": "https://uistate.com",
+  "peerDependencies": {
+    "@uistate/core": ">=5.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@uistate/core": {
+      "optional": true
+    }
+  }
+}

package/router.js

@@ -0,0 +1,365 @@
+// @uistate/router — SPA router factory for EventState stores
+// Routing is just state: navigate() writes to store paths, components subscribe.
+
+/**
+ * Compile a route pattern like '/users/:id/posts/:postId' into a matcher.
+ * Returns { regex, paramNames } for extraction.
+ */
+function compilePattern(pattern) {
+  const paramNames = [];
+  const parts = pattern.split(/:([a-zA-Z_][a-zA-Z0-9_]*)/);
+  const regexStr = parts
+    .map((part, i) => {
+      if (i % 2 === 1) {
+        paramNames.push(part);
+        return '([^/]+)';
+      }
+      return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    })
+    .join('');
+  return { regex: new RegExp('^' + regexStr + '$'), paramNames };
+}
+
+/**
+ * Create a SPA router bound to an EventState store.
+ *
+ * @param {Object} config
+ * @param {Array}  config.routes       - [{ path: '/users/:id', view: 'user', component: UserView }]
+ * @param {Object} [config.store]      - EventState store instance
+ * @param {string} [config.rootSelector='[data-route-root]'] - Root element for view mounting
+ * @param {Object} [config.fallback]   - Fallback route when nothing matches
+ * @param {boolean} [config.debug=false]
+ * @param {string} [config.linkSelector='a[data-link]'] - Selector for intercepted links
+ * @param {string} [config.navSelector='nav a[data-link]'] - Selector for nav links to toggle .active class
+ *
+ * Store-driven navigation (requires store):
+ *   Any code with store access can navigate without importing the router:
+ *   - store.set('ui.route.go', '/about')
+ *   - store.set('ui.route.go', { path: '/users/1', search: '?tab=posts' })
+ *   - store.set('ui.route.go', { query: { tab: 'posts' } })  // patch query only
+ */
+export function createRouter(config) {
+  const {
+    routes = [],
+    store,
+    rootSelector = '[data-route-root]',
+    fallback = null,
+    debug = false,
+    linkSelector = 'a[data-link]',
+    navSelector = 'nav a[data-link]',
+  } = config;
+
+  // Pre-compile route patterns
+  const compiled = routes.map(route => ({
+    ...route,
+    ...compilePattern(route.path),
+  }));
+
+  const compiledFallback = fallback
+    ? { ...fallback, ...compilePattern(fallback.path || '/*'), params: {} }
+    : null;
+
+  // Detect base path from <base href> if present
+  const BASE_PATH = (() => {
+    const b = document.querySelector('base[href]');
+    if (!b) return '';
+    try {
+      const u = new URL(b.getAttribute('href'), location.href);
+      let p = u.pathname;
+      if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+      return p;
+    } catch { return ''; }
+  })();
+
+  function stripBase(pathname) {
+    if (BASE_PATH && pathname.startsWith(BASE_PATH)) {
+      const rest = pathname.slice(BASE_PATH.length) || '/';
+      return rest.startsWith('/') ? rest : ('/' + rest);
+    }
+    return pathname;
+  }
+
+  function withBase(pathname) {
+    if (!BASE_PATH) return pathname;
+    if (pathname === '/') return BASE_PATH || '/';
+    return BASE_PATH + (pathname.startsWith('/') ? '' : '/') + pathname;
+  }
+
+  function normalizePath(p) {
+    if (!p) return '/';
+    if (p[0] !== '/') p = '/' + p;
+    if (p === '/index.html') return '/';
+    if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+    return p;
+  }
+
+  function resolve(pathname) {
+    const p = normalizePath(pathname);
+    for (const route of compiled) {
+      const match = p.match(route.regex);
+      if (match) {
+        const params = {};
+        route.paramNames.forEach((name, i) => {
+          params[name] = decodeURIComponent(match[i + 1]);
+        });
+        return { path: route.path, view: route.view, component: route.component, params };
+      }
+    }
+    if (compiledFallback) return { ...compiledFallback, params: {} };
+    return null;
+  }
+
+  function getRoot() {
+    const el = document.querySelector(rootSelector);
+    if (!el) throw new Error('[router] Route root not found: ' + rootSelector);
+    return el;
+  }
+
+  function log(...args) {
+    if (debug) console.debug('[router]', ...args);
+  }
+
+  function setActiveNav(pathname) {
+    document.querySelectorAll(navSelector).forEach(a => {
+      const url = new URL(a.getAttribute('href'), location.href);
+      const linkPath = normalizePath(stripBase(url.pathname));
+      const here = normalizePath(pathname);
+      const isExact = linkPath === here;
+      const isParent = !isExact && linkPath !== '/' && here.startsWith(linkPath);
+      const active = isExact || isParent;
+      a.classList.toggle('active', active);
+      if (isExact) a.setAttribute('aria-current', 'page');
+      else a.removeAttribute('aria-current');
+    });
+  }
+
+  // Internal state
+  let current = { viewKey: null, unboot: null, path: null, search: '' };
+  let navController = null;
+  const scrollPositions = new Map();
+  history.scrollRestoration = 'manual';
+
+  /**
+   * Navigate to a pathname.
+   * @param {string} pathname
+   * @param {Object} [opts]
+   * @param {boolean} [opts.replace=false]
+   * @param {string}  [opts.search='']
+   * @param {boolean} [opts.restoreScroll=false]
+   */
+  async function navigate(pathname, { replace = false, search = '', restoreScroll = false } = {}) {
+    const root = getRoot();
+    const appPath = normalizePath(stripBase(pathname));
+    const resolved = resolve(appPath);
+
+    if (!resolved) {
+      log('no route found for:', appPath);
+      return;
+    }
+
+    const viewKey = resolved.view;
+    const component = resolved.component;
+    const searchStr = search && search.startsWith('?') ? search : (search ? ('?' + search) : '');
+
+    log('navigate', { from: current.path, to: appPath, view: viewKey, params: resolved.params });
+
+    // Same-route no-op guard
+    if (current.path === appPath && current.search === searchStr) {
+      return;
+    }
+
+    // Abort in-flight boot
+    if (navController) navController.abort();
+    navController = new AbortController();
+    const { signal } = navController;
+
+    // Transition start
+    const html = document.documentElement;
+    html.setAttribute('data-transitioning', 'on');
+    if (store) {
+      try { store.set('ui.route.transitioning', true); } catch {}
+    }
+
+    // Save scroll position for current route
+    if (current.path) {
+      scrollPositions.set(current.path, { x: scrollX, y: scrollY });
+      if (scrollPositions.size > 50) scrollPositions.delete(scrollPositions.keys().next().value);
+    }
+
+    // Unboot previous view
+    if (typeof current.unboot === 'function') {
+      try { await current.unboot(); } catch {}
+    }
+
+    // Clear root
+    root.replaceChildren();
+
+    // Boot new view
+    let unboot = null;
+    if (component && typeof component.boot === 'function') {
+      unboot = await component.boot({ store, el: root, signal, params: resolved.params });
+    }
+
+    // Guard: if navigation was superseded during boot, bail out
+    if (signal.aborted) return;
+
+    const prevViewKey = current.viewKey;
+    current = { viewKey, unboot, path: appPath, search: searchStr };
+
+    // Parse query params
+    const fullUrl = new URL(location.origin + withBase(appPath) + searchStr);
+    const query = {};
+    fullUrl.searchParams.forEach((v, k) => { query[k] = v; });
+
+    // Update store with route state + end transition atomically
+    if (store) {
+      try {
+        store.setMany({
+          'ui.route.view': viewKey,
+          'ui.route.path': appPath,
+          'ui.route.params': resolved.params || {},
+          'ui.route.query': query,
+          'ui.route.transitioning': false,
+        });
+      } catch {}
+    }
+
+    // Update browser history
+    const useReplace = replace;
+    if (useReplace) history.replaceState({}, '', withBase(appPath) + searchStr);
+    else history.pushState({}, '', withBase(appPath) + searchStr);
+
+    // Set view attribute on <html> for CSS hooks
+    html.setAttribute('data-view', viewKey);
+    html.setAttribute('data-transitioning', 'off');
+
+    // Update nav active state
+    setActiveNav(appPath);
+
+    // Focus management (accessibility)
+    if (!root.hasAttribute('tabindex')) root.setAttribute('tabindex', '-1');
+    try { root.focus({ preventScroll: true }); } catch {}
+
+    // Scroll
+    if (restoreScroll) {
+      const pos = scrollPositions.get(appPath);
+      if (pos) scrollTo(pos.x, pos.y);
+    } else {
+      scrollTo(0, 0);
+    }
+
+    log('routed', { view: viewKey, path: appPath, params: resolved.params, query });
+  }
+
+  /**
+   * Patch query parameters without changing the path.
+   * Pass null/undefined/'' as a value to remove a key.
+   */
+  function navigateQuery(patch = {}, { replace = true } = {}) {
+    const params = new URLSearchParams(current.search?.replace(/^\?/, '') || '');
+    for (const [k, v] of Object.entries(patch)) {
+      if (v === null || v === undefined || v === '') params.delete(k);
+      else params.set(k, String(v));
+    }
+    const searchStr = params.toString();
+    const prefixed = searchStr ? ('?' + searchStr) : '';
+    const path = current.path || normalizePath(stripBase(location.pathname));
+    return navigate(path, { search: prefixed, replace });
+  }
+
+  /**
+   * Navigate to a new path, keeping the current search string.
+   * @param {string} path
+   * @param {Object} [opts]
+   * @param {boolean} [opts.replace=true]
+   */
+  function navigatePath(path, { replace = true } = {}) {
+    const appPath = normalizePath(stripBase(path));
+    const searchStr = current.search || '';
+    return navigate(appPath, { search: searchStr, replace });
+  }
+
+  // Event handlers
+  function onClick(e) {
+    const a = e.target.closest(linkSelector);
+    if (!a) return;
+    if (e.defaultPrevented) return;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+    const href = a.getAttribute('href');
+    if (!href) return;
+    const url = new URL(href, location.href);
+    if (url.origin !== location.origin) return;
+    e.preventDefault();
+    log('click', { href, text: a.textContent.trim() });
+    navigate(url.pathname, { search: url.search }).catch(() => {});
+  }
+
+  function onPop() {
+    navigate(location.pathname, {
+      replace: true,
+      search: location.search,
+      restoreScroll: true,
+    }).catch(() => {});
+  }
+
+  // Store-driven navigation: write ui.route.go to navigate from anywhere
+  let unsubGo = null;
+  let processingGo = false;
+  if (store) {
+    unsubGo = store.subscribe('ui.route.go', (value) => {
+      if (processingGo || !value) return;
+      processingGo = true;
+      try { store.set('ui.route.go', null); } catch {}
+      processingGo = false;
+
+      if (typeof value === 'string') {
+        navigate(value).catch(() => {});
+      } else if (typeof value === 'object') {
+        if (!value.path && value.query) {
+          navigateQuery(value.query, { replace: value.replace ?? true }).catch(() => {});
+        } else {
+          navigate(value.path || '/', {
+            search: value.search || '',
+            replace: value.replace || false,
+          }).catch(() => {});
+        }
+      }
+    });
+  }
+
+  // Public API
+  return {
+    navigate,
+    navigateQuery,
+    navigatePath,
+
+    start() {
+      window.addEventListener('click', onClick);
+      window.addEventListener('popstate', onPop);
+      navigate(location.pathname, {
+        replace: true,
+        search: location.search,
+        restoreScroll: true,
+      });
+      return this;
+    },
+
+    stop() {
+      window.removeEventListener('click', onClick);
+      window.removeEventListener('popstate', onPop);
+      if (unsubGo) { unsubGo(); unsubGo = null; }
+      if (typeof current.unboot === 'function') {
+        try { Promise.resolve(current.unboot()).catch(() => {}); } catch {}
+      }
+      return this;
+    },
+
+    getCurrent() {
+      return {
+        view: current.viewKey,
+        path: current.path,
+        search: current.search,
+      };
+    },
+  };
+}