@dharmax/state-router 3.2.0 → 3.2.1

package/ReadMe.md

@@ -1,57 +1,188 @@
 
-# General 
-This package contains a functional router and a web-application state manager.
+## Overview
 
-What is a functional router? it's a router that captures a url changes and 
-per specific pattern of url, it simply triggers a handler. It supports hash notation 
-as well as normal url patterns. It also supports contexts (url parameters).
+This package contains a tiny, functional router and a web‑application state manager.
 
-Together with the state manager - which will be the main object you'd need 
-to work with, you get a very simple semantic application state management: 
-each state can be given a logical name, route and an associated page/component.
+The router captures URL changes and triggers a handler for the first matching route pattern. It supports both hash (`#/path`) and history (`/path`) modes, and passes route parameters and query data to your handler.
 
-The router by default ignores file extensions '.json', '.css', '.js', '.png', '.jpg', '.svg', '.webp','md'
-and you can access the router's staticFilters member to replace or add other rules
-for static serving support.
+The state manager provides a minimal semantic state layer on top of the router: define named states, their route, and optional mode(s); listen for changes; and gate transitions with async guards.
 
-you can use the hash notation or not (set the router's mode to 'history' or 'hash')
+- Static files: the router ignores common static file extensions (e.g. `.css`, `.js`, `.png`, `.svg`, `.webp`, `.json`, `.md`, `.txt`, `.ejs`, `.jsm`). You can customize `router.staticFilters` to adjust.
+- Modes: use `router.listen('hash' | 'history')`. For static file serving (file:// or a simple static server), prefer `hash`.
 
+## Installation
 
-# Example
+Install as usual and build the TypeScript sources:
 
-## state definitions
+```
+npm install
+npm run build
+```
+
+## Quick Start
+
+```ts
+import { router, StateManager } from '@dharmax/state-router'
+
+// Router: match params and use query context
+router
+  .add(/^user\/(\d+)$/, function (id: string) {
+    // `this` holds query params from the current URL
+    // @ts-ignore
+    console.log('user', id, 'q=', this.queryParams?.q)
+  })
+  .listen('hash')
+
+// State Manager: define states and react
+const sm = new StateManager('hash')
+sm.addState('home', 'home', /^home$/)
+sm.addState('post', 'post', /^post\/(\w+)$/)
 
-```javascript
-    stateManager.addState('main', 'main-page', /main$/);
-    stateManager.addState('login', 'login-box', 'login')
-    stateManager.addState('signup', 'signup-box', /signup/)
-    stateManager.addState('my-profile') // will assume the page name and the route are the same...
-    stateManager.addState('inbox')
-    stateManager.addState('about')
-    stateManager.addState('discussion', 'discussion-page', 'discussion/%')
-    stateManager.addState('article', 'article-page', 'article/%','article-mode')
-    stateManager.addState('blog', 'article-page', 'blog/%','blog-mode')
+sm.onChange((event, state) => {
+  console.log('state changed to', state.name, 'context=', sm.context)
+})
+
+// Navigate
+router.navigate('home')
+router.navigate('post/hello')
 ```
 
-## usage in the gui
+## Router API
+
+- `router.add(pattern: RegExp | RouteHandler, handler?: RouteHandler)`
+  - If `pattern` is a RegExp, captured groups are passed as handler arguments.
+  - If `pattern` is omitted (i.e., you pass only a function), it becomes a catch‑all route.
+  - The handler’s `this` contains `queryParams` built from `window.location.search`.
+  - String patterns with named params are supported: `'/users/:id'` produces `this.params = { id: '...' }` and still passes the captured values as handler args.
+
+- `router.listen(mode?: 'hash' | 'history')`
+  - In `history` mode, internal `<a href="/...">` clicks and Enter on focused links are intercepted.
+  - Interception is hardened: uses `closest('a')`; ignores modified clicks (meta/ctrl/shift), non‑left clicks, `target=_blank`, `download`, `rel=noreferrer`, and external origins or different hostnames; and skips static‑looking URLs (by extension).
+
+- `router.navigate(path: string, opts?: { replace?: boolean })`
+  - Navigates according to the active mode and triggers routing.
+  - If `opts.replace` is true (history mode), uses `history.replaceState` instead of `pushState`.
+
+- `router.replace(path: string)`
+  - Shorthand for `router.navigate(path, { replace: true })`.
+
+- `router.resetRoot(root: string)`
+  - Set a base root for history URL calculation.
+
+- `router.unlisten()`
+  - Removes all listeners previously attached by `listen()` (click, keydown, popstate/hashchange). Useful for cleanup and tests.
+
+- `router.onNotFound(handler)`
+  - Registers a fallback called when no routes match. Returns `true` from `handleChange()` after invoking the hook.
+
+- `router.getQueryParams(search?: string)`
+  - Returns a parsed query map from the current URL (or from a provided search string). Useful if you’d rather not use handler `this`.
+
+- `router.setDecodeParams(boolean)`
+  - Optionally `decodeURIComponent` route parameters before passing them to handlers and `this.params`.
+
+Notes: the router lazily accesses `window`/`document` to be SSR‑safe; outside a browser environment, listeners are not attached and navigation no‑ops.
+
+- `createRouter()`
+  - Factory that returns a fresh Router instance. Useful for testing or isolating multiple routers.
+
+## State Manager API
+
+- `new StateManager(mode?: 'hash' | 'history', autostart = true, routerInstance = router)`
+  - When `autostart` is true, calls `router.listen(mode)` automatically.
+  - You can pass a custom router instance (e.g., from `createRouter()`) for isolation.
+  - Call `sm.stop()` to unlisten the router.
+
+- `addState(name, pageName?, route?: RegExp | string, mode?: string | string[])`
+  - If `route` is a string and contains `%`, each `%` is expanded to a non‑mandatory capture `?(.*)` for “the rest of the path”. For example, `'docs%'` becomes `^docs?(.*)$` and the first capture is provided as the state context (e.g., `'/guide'`).
+  - If `route` is a RegExp, the first capturing group is passed as the state context.
 
-In your main component, you write something like that:
+- `setState(name, context?)`
+  - Programmatically set the state and optional context (e.g., a sub‑state or id).
 
-```javascript
+- `getState()` / `previous` / `context`
+  - Access current, previous state, and the last context value.
+  - Context can be a string, an array (for multi‑capture regex), or an object (for named params).
 
-stateManager.onChange( event => {
-    // this specific example works with RiotJs, but you get the drift
-    this.update({
-        currentPage: event.data.pageName
-    })
+- `onChange(handler)`
+  - Subscribes to `state:changed` events via `@dharmax/pubsub`.
+
+- `onBeforeChange(handler)` / `onAfterChange(handler)`
+  - Optional hooks around transitions. `onBeforeChange` can veto by returning `false` (sync or async). `onAfterChange` runs after a successful transition.
+
+- `onNotFound(handler)`
+  - Subscribe to router‐level notFound events via the state manager for convenience.
+
+- `registerChangeAuthority(authority: (target) => Promise<boolean>)`
+  - All registered authorities must return `true` to allow a transition.
+
+- `restoreState(defaultState)`
+  - Attempts to restore from current URL; otherwise navigates to the default state (hash mode).
+
+- `createStateManager(mode?: 'hash' | 'history', autostart = true, routerInstance = router)`
+  - Factory returning a new StateManager; pass a custom router if desired.
+
+## Data, Context, and Parameter Passing
+
+- Route parameters: each capturing group in your route RegExp is passed to the route handler as an argument in order. For `^user\/(\d+)$`, the handler receives the user id string.
+- Query params: inside a route handler, `this.queryParams` exposes an object of the URL’s query parameters (e.g., `{ q: 'hello' }`).
+- State context: when a route defined via `addState` matches, the first capture group is forwarded to the StateManager as the state “context”. Access it via `stateManager.context` after the transition.
+
+## Examples
+
+```ts
+// 1) Params + query
+router.add(/^user\/(\d+)$/, function (id) {
+  // @ts-ignore
+  const { q } = this.queryParams
+  console.log('id=', id, 'q=', q)
 })
 
+// 2) State context from route
+sm.addState('docs', 'docs', 'docs%') // captures the suffix as context, e.g. '/guide'
 
+// 3) Async guard
+sm.registerChangeAuthority(async (target) => {
+  return target.name !== 'admin-only'
+})
 ```
 
-## More
-* pageChangeHandler - it's a global optional page change listener that receives ('send', 'pageview', `/${state.name}/${context || ''}`);
-* google analytics (ga) is automatically used if it was found
-* query parameters are passed to the state context under queryParams object
-* on page change, an event state:changed is fired with the new state (that include the context)
-* in addState, the last (optional) parameter can contain either a string an array of strings and it can be used for in-state special logic, or sub-states within the same parent-component, for example  
+## Development & Testing
+
+- Build: `npm run build` → compiles TypeScript into `dist/`.
+- Manual demo: serve `test/` (e.g., `npx http-server test`) after build. Use `hash` mode for static servers.
+- Automated tests: Vitest + jsdom
+  - Run once with coverage: `npm test`
+  - Watch mode: `npm run test:watch`
+  - Notes:
+    - Tests use dynamic imports with `vi.resetModules()` to isolate the singleton router/state manager between cases.
+    - Some tests mock `URLSearchParams` to simulate query strings in jsdom without full navigation.
+    - Tests use history mode in jsdom via `history.pushState` and `popstate` events; avoid direct `window.location.search = '...'` (jsdom limitation).
+
+## History Mode Server Config
+
+When using `history` mode, your server must serve your SPA entry (e.g., `index.html`) for application routes to avoid 404s on refresh or deep links. Static assets should still be served normally.
+
+Examples:
+
+- Node/Express
+  - Serve static first, then a catch‑all returning `index.html`.
+    - `app.use(express.static('public'))`
+    - `app.get('*', (req, res) => res.sendFile(path.join(__dirname, 'public/index.html')))`
+
+- Nginx
+  - In your `location /` block: `try_files $uri /index.html;`
+
+- Apache
+  - Use `FallbackResource /index.html` or an `.htaccess` rewrite.
+
+Tip: Keep `router.staticFilters` tuned so links to real files (e.g., `/assets/app.css`) are not intercepted.
+
+## Analytics Hooks
+
+If present, the following globals will be invoked on successful state changes:
+
+- `window.pageChangeHandler('send', 'pageview', '/<state>/<context>')`
+- `window.ga('send', 'pageview', '/<state>/<context>')`
+
+These are optional and ignored if missing.

package/dist/router.d.ts

@@ -1,18 +1,28 @@
-type RouteHandler = (...args: any[]) => void;
+type RouteHandler = (...args: string[]) => void;
 export type RoutingMode = 'history' | 'hash';
-declare class Router {
+export declare class Router {
     private mode;
     private routes;
     private root;
+    private rootCompare;
     private baseLocation;
     staticFilters: ((url: string) => boolean)[];
+    private isListening;
+    private bound;
+    private notFoundHandler?;
+    private decodeParams;
     constructor();
     private cleanPathString;
     private clearQuery;
     private isStaticFile;
     resetRoot(root: string): void;
     getLocation(): string;
-    add(pattern: RegExp | RouteHandler, handler?: RouteHandler): Router;
+    add(pattern: RegExp | string | RouteHandler, handler?: RouteHandler): Router;
+    onNotFound(handler: (path: string) => void): Router;
+    setDecodeParams(decode: boolean): Router;
+    getQueryParams(search?: string): Record<string, string>;
+    private isBrowser;
+    private compilePattern;
     /**
      *
      * @param location
@@ -20,7 +30,12 @@ declare class Router {
      */
     handleChange(location?: string): boolean;
     listen(mode?: RoutingMode): void;
-    navigate(path?: string): boolean;
+    unlisten(): void;
+    navigate(path?: string, opts?: {
+        replace?: boolean;
+    }): boolean;
+    replace(path?: string): boolean;
 }
 export declare const router: Router;
+export declare function createRouter(): Router;
 export {};

package/dist/router.js

@@ -1,9 +1,14 @@
-class Router {
+export class Router {
     mode = 'hash';
     routes = [];
     root = '/';
+    rootCompare = '';
     baseLocation = null;
     staticFilters = [];
+    isListening = false;
+    bound = {};
+    notFoundHandler;
+    decodeParams = false;
     constructor() {
         this.staticFilters.push(url => {
             const staticFileExtensions = ['.json', '.css', '.js', '.png', '.jpg', '.svg', '.webp', '.md', '.ejs', '.jsm', '.txt'];
@@ -25,13 +30,23 @@ class Router {
         return (this.staticFilters || []).some(filter => filter(url));
     }
     resetRoot(root) {
-        this.root = '/' + this.cleanPathString(root) + '/';
+        const cleaned = this.cleanPathString(root);
+        this.root = '/' + cleaned + '/';
+        this.rootCompare = cleaned ? cleaned + '/' : '';
     }
     getLocation() {
+        if (!this.isBrowser())
+            return '';
         if (this.mode === 'history') {
-            let fragment = this.cleanPathString(decodeURI(window.location.pathname + window.location.search));
+            let fragment = decodeURI(window.location.pathname + window.location.search);
             fragment = this.clearQuery(fragment);
-            return this.root !== '/' ? fragment.replace(this.root, '') : fragment;
+            // strip leading slash for comparison convenience
+            fragment = fragment.replace(/^\//, '');
+            if (this.root !== '/' && this.rootCompare && fragment.startsWith(this.rootCompare)) {
+                fragment = fragment.slice(this.rootCompare.length);
+            }
+            fragment = this.cleanPathString(fragment);
+            return fragment;
         }
         else {
             const match = window.location.href.match(/#(.*)$/);
@@ -39,77 +54,207 @@ class Router {
         }
     }
     add(pattern, handler) {
+        let paramNames;
         if (typeof pattern === 'function') {
             handler = pattern;
             pattern = /^.*$/; // Match any path
         }
-        this.routes.push({ pattern, handler: handler });
+        else if (typeof pattern === 'string') {
+            const compiled = this.compilePattern(pattern);
+            pattern = compiled.regex;
+            paramNames = compiled.paramNames;
+        }
+        this.routes.push({ pattern: pattern, handler: handler, paramNames });
+        return this;
+    }
+    onNotFound(handler) {
+        this.notFoundHandler = handler;
+        return this;
+    }
+    setDecodeParams(decode) {
+        this.decodeParams = decode;
         return this;
     }
+    getQueryParams(search) {
+        if (!this.isBrowser() && !search)
+            return {};
+        const qs = typeof search === 'string' ? search : window.location.search || '';
+        const usp = new URLSearchParams(qs);
+        const obj = {};
+        usp.forEach((v, k) => { obj[k] = v; });
+        return obj;
+    }
+    isBrowser() {
+        return typeof window !== 'undefined' && typeof document !== 'undefined';
+    }
+    compilePattern(pattern) {
+        // normalize leading slash to align with cleanPathString behavior
+        const normalized = pattern.replace(/^\//, '');
+        const paramNames = [];
+        // convert /users/:id -> ^users/([^/]+)$
+        const reStr = normalized
+            .replace(/([.*+?^${}()|[\]\\])/g, '\\$1') // escape regex specials
+            .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_m, p1) => {
+            paramNames.push(p1);
+            return '([^/]+)';
+        });
+        return { regex: new RegExp(`^${reStr}$`), paramNames };
+    }
     /**
      *
      * @param location
      * @return true if it was intercepted or false if not handled
      */
     handleChange(location) {
-        const path = location || this.getLocation();
+        const path = (location ?? this.getLocation()) || '';
         if (this.isStaticFile(path))
             return false; // Bypass routing for static files
         for (const route of this.routes) {
-            const match = path.match(route.pattern);
+            const match = route.pattern ? path.match(route.pattern) : null;
             if (match) {
                 match.shift(); // Remove the full match element
-                const queryParams = Object.fromEntries(new URLSearchParams(window.location.search));
-                route.handler({ queryParams }, match);
+                const queryParams = this.getQueryParams();
+                const captures = this.decodeParams ? match.map(v => safeDecode(v)) : match;
+                let params;
+                if (route.paramNames && route.paramNames.length) {
+                    params = {};
+                    route.paramNames.forEach((n, i) => params[n] = captures[i]);
+                }
+                route.handler.call({ queryParams, params }, ...captures);
                 return true;
             }
         }
-        console.warn(`No routing found for ${path}`);
+        if (this.notFoundHandler) {
+            this.notFoundHandler(path);
+            return true;
+        }
+        if (path)
+            console.warn(`No routing found for ${path}`);
         return false;
     }
     listen(mode = 'hash') {
+        if (!this.isBrowser())
+            return;
+        // avoid duplicate listeners
+        if (this.isListening)
+            this.unlisten();
         const self = this;
         this.mode = mode;
-        switch (mode) {
-            case "hash":
-                window.addEventListener('hashchange', () => handler());
-                break;
-            case "history":
-                window.addEventListener('popstate', event => handler(event.state?.path));
-                document.addEventListener('click', handleInternalNavigation);
-                document.addEventListener('keydown', event => {
-                    // @ts-ignore
-                    if (event.key === 'Enter' && event.target.tagName === 'A')
-                        handleInternalNavigation(event);
-                });
-        }
-        function handleInternalNavigation(event) {
-            const node = event.target;
-            const href = node.getAttribute('href');
-            if (href) {
-                event.preventDefault();
-                history.pushState({ path: href }, '', href);
-                handler(href);
-            }
-        }
-        function handler(path) {
-            path = path || location.href.split('#')[0];
-            if (self.isStaticFile(path))
+        const handler = (path) => {
+            const p = path || location.href.split('#')[0];
+            if (self.isStaticFile(p))
                 return;
             const currentLocation = self.getLocation();
             if (self.baseLocation !== currentLocation) {
                 self.baseLocation = currentLocation;
                 self.handleChange(currentLocation);
             }
+        };
+        const handleInternalNavigation = (event) => {
+            // modified clicks or non-left clicks
+            const me = event;
+            if (event.type === 'click') {
+                if (me.button !== 0)
+                    return; // left-click only
+                if (me.metaKey || me.ctrlKey || me.shiftKey)
+                    return;
+            }
+            const target = event.target;
+            if (!target || !('closest' in target))
+                return;
+            const anchor = target.closest?.('a');
+            if (!anchor)
+                return;
+            if (event.type === 'keydown') {
+                const ke = event;
+                if (ke.key !== 'Enter')
+                    return;
+            }
+            const href = anchor.getAttribute('href') || '';
+            if (!href)
+                return;
+            const url = new URL(href, window.location.href);
+            // ignore external origins or different hostnames
+            if (url.origin !== window.location.origin)
+                return;
+            // ignore target=_blank, download, or rel=noreferrer
+            const t = anchor.getAttribute('target');
+            if (t && t.toLowerCase() === '_blank')
+                return;
+            if (anchor.hasAttribute('download'))
+                return;
+            const rel = anchor.getAttribute('rel');
+            if (rel && /\bnoreferrer\b/i.test(rel))
+                return;
+            const pathWithQuery = url.pathname + (url.search || '');
+            if (self.isStaticFile(pathWithQuery) || self.isStaticFile(url.pathname))
+                return;
+            event.preventDefault();
+            history.pushState({ path: pathWithQuery }, '', pathWithQuery);
+            handler(pathWithQuery);
+        };
+        switch (mode) {
+            case 'hash':
+                this.bound.hashchange = () => handler();
+                window.addEventListener('hashchange', this.bound.hashchange);
+                break;
+            case 'history':
+                this.bound.popstate = (event) => handler(event.state?.path);
+                this.bound.click = handleInternalNavigation;
+                this.bound.keydown = (event) => handleInternalNavigation(event);
+                window.addEventListener('popstate', this.bound.popstate);
+                document.addEventListener('click', this.bound.click);
+                document.addEventListener('keydown', this.bound.keydown);
+                break;
         }
+        this.isListening = true;
         handler();
     }
-    navigate(path = '') {
-        if (this.mode === 'history')
-            history.pushState(null, null, this.root + this.cleanPathString(path));
+    unlisten() {
+        if (!this.isBrowser() || !this.isListening)
+            return;
+        switch (this.mode) {
+            case 'hash':
+                if (this.bound.hashchange)
+                    window.removeEventListener('hashchange', this.bound.hashchange);
+                break;
+            case 'history':
+                if (this.bound.popstate)
+                    window.removeEventListener('popstate', this.bound.popstate);
+                if (this.bound.click)
+                    document.removeEventListener('click', this.bound.click);
+                if (this.bound.keydown)
+                    document.removeEventListener('keydown', this.bound.keydown);
+                break;
+        }
+        this.bound = {};
+        this.isListening = false;
+    }
+    navigate(path = '', opts) {
+        if (!this.isBrowser())
+            return false;
+        if (this.mode === 'history') {
+            const url = this.root + this.cleanPathString(path);
+            if (opts?.replace)
+                history.replaceState(null, '', url);
+            else
+                history.pushState(null, '', url);
+        }
         else
             window.location.hash = this.cleanPathString(path);
         return this.handleChange();
     }
+    replace(path = '') {
+        return this.navigate(path, { replace: true });
+    }
 }
 export const router = new Router();
+export function createRouter() { return new Router(); }
+function safeDecode(v) {
+    try {
+        return decodeURIComponent(v);
+    }
+    catch {
+        return v;
+    }
+}

package/dist/state-manager.d.ts

@@ -1,10 +1,10 @@
-import { RoutingMode } from "./router";
+import { RoutingMode, Router as RouterType } from "./router";
 import { IPubSubHandle, PubSubEvent } from "@dharmax/pubsub";
 export type ApplicationStateName = string;
 export type ApplicationState = {
     name: ApplicationStateName;
     pageName: string;
-    route: RegExp;
+    route: RegExp | string;
     mode?: string | string[];
 };
 export type ChangeAuthority = (state: ApplicationState) => Promise<boolean>;
@@ -16,13 +16,17 @@ export declare class StateManager {
     private stateContext;
     static dispatcher: import("@dharmax/pubsub").PubSub;
     private changeAuthorities;
-    constructor(mode?: RoutingMode, autostart?: boolean);
+    private router;
+    private beforeChangeHandlers;
+    private afterChangeHandlers;
+    constructor(mode?: RoutingMode, autostart?: boolean, routerInstance?: RouterType);
     start(): void;
+    stop(): void;
     onChange(handler: (event: PubSubEvent, data: any) => void): IPubSubHandle;
     registerChangeAuthority(authorityCallback: (targetState: ApplicationState) => Promise<boolean>): void;
     getState(): ApplicationState;
     get previous(): ApplicationState;
-    get context(): ApplicationState;
+    get context(): any;
     /**
      * set current page state
      * @param state can be either just a state or a state and context (which can be sub-state, or anything else)
@@ -45,4 +49,8 @@ export declare class StateManager {
      */
     addState(name: string, pageName?: string, route?: RegExp | string, mode?: string | string[]): void;
     registerStateByState(state: ApplicationState): void;
+    onBeforeChange(handler: (target: ApplicationState, context?: any) => boolean | Promise<boolean>): void;
+    onAfterChange(handler: (state: ApplicationState, context?: any, previous?: ApplicationState) => void | Promise<void>): void;
+    onNotFound(handler: (path: string) => void): void;
 }
+export declare function createStateManager(mode?: RoutingMode, autostart?: boolean, routerInstance?: RouterType): StateManager;