white-label-router 1.1.2 → 4.0.0

package/README.md

@@ -1,361 +1,246 @@
 # white-label-router
 
-A simple ES6 JS router based on the history api and pushstate.
+`white-label-router` is a small client-side router built on the browser History API. It maps URL prefixes to functions or view lifecycle objects, intercepts links marked with `data-pushstate`, handles browser back/forward navigation, and can receive navigation requests through a mediator.
 
-Learn more about ES6 classes here:
+## Requirements
 
-https://babeljs.io/docs/learn-es2015/
+- Node.js `^22.18.0` or `>=24.11.0` for installation and development
+- A browser environment with `window.history`, `window.location`, and standard DOM events at runtime
+- Server fallback configuration that serves the application entry page for client-managed URLs
 
-## Install
+## Install and import
 
-Install the node module:
-
-```
-npm install white-label-router --save
+```sh
+npm install white-label-router
 ```
 
-## Import
-
-```
+```js
 import Router from 'white-label-router';
 ```
 
+## Complete example
 
-## Defining Routes
-
-The most simple way simply executes any function you define:
+```js
+import Router from 'white-label-router';
 
-```
-const MyRoute = class extends Router {
+class ApplicationRouter extends Router {
     constructor() {
         super();
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
-    }
-};
-```
 
-or you can also define initialize and destroy functions in your view which will be automatically called as the user navigates your application:
-
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
+        this.scope = document.querySelector('main');
         this.routes = {
-            defaultRoute: {
-                view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the defaultRoute initialized');
-                    },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the defaultRoute has been destroyed');
-                    }
-                }
+            '/products': (scope, location) => {
+                scope.textContent = `Product: ${location.data.url[0] || 'all'}`;
             },
-            '/page2': {
-                view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the page2 initialized');
-                    },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the page2 has been destroyed');
-                    }
-                }
-            }
-        };
-    }
-};
-```
-
-You have some additional options when using the view object approach. They include the ability to set the page title for a route and also do security check before a route's view is initialized at the router level:
-
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
-        this.routes = {
-            defaultRoute: {
-                title: 'Home',
+            '/account': {
+                title: 'Your account',
+                secure: () => Boolean(window.currentUser),
                 view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the defaultRoute initialized');
+                    initialize: (scope, location) => {
+                        scope.textContent = 'Account';
+                        console.log(location.data.query);
                     },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the defaultRoute has been destroyed');
+                    destroy: () => {
+                        console.log('Leaving account');
                     }
                 }
             },
-            '/page2': {
-                title: 'Page 2',
-                view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the page2 initialized');
-                    },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the page2 has been destroyed');
-                    }
-                },
-                secure: this.isSecure
+            defaultRoute: () => {
+                console.log('No configured route matched.');
             }
         };
     }
-    isSecure (scope, locationData) => {
-        if (someCookieIsValid) {
-            return true;
-        } else {
-            return false;
-        }
-    }
-};
+}
+
+const router = new ApplicationRouter();
+router.initialize();
 ```
 
-NOTE: routes are matched by checking if the beginning of the url path name string matches a route. For the example above the route '/page2' would be executed for both path names '/page2' and '/page23/232'.
+At startup, `initialize()` reads the current path and query string, registers document click and browser `popstate` listeners, and navigates to the matching route.
 
-## Scope
+## Define routes
 
-Optionally you and provide a DOM element to be the scope of the router. That DOM object will then be passed into all your routes as they are executed. If you do not provide a scope then it will be passed in as null into your views. To do so you would like this:
+A route may be a function:
 
+```js
+this.routes = {
+    '/help': (scope, location) => {
+        scope.textContent = `Help page: ${location.url}`;
+    }
+};
 ```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
 
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
+Or it may describe a title, security check, and view lifecycle:
 
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
+```js
+this.routes = {
+    '/orders': {
+        title: 'Orders',
+        secure(scope, location) {
+            return Boolean(window.currentUser);
+        },
+        view: {
+            initialize(scope, location) {
+                scope.textContent = 'Order history';
             },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
+            destroy(scope, nextLocation) {
+                scope.replaceChildren();
             }
-        };
-
+        }
     }
 };
 ```
 
-## Instantiate
+The `secure` function must return exactly `true` to allow navigation. When navigation succeeds, the previous route's `destroy()` runs before the next route's `initialize()`.
 
-```
-const myRouter = new MyRouter();
-
-myRouter.initialize();
-```
+### Route matching behavior
 
-## HTML Linking To Routes
+Routes match complete path boundaries in object insertion order. For example, `/products` matches `/products` and `/products/42`, but it does not match `/products-old`. Put more specific routes before broader ones:
 
-you can make any anchor tigger a specified route by simply setting the href attribute to your route path and adding the attribute 'data-pushstate'.
-
-```
-<a href="/page2" data-pushstate>take me to page2</a>
+```js
+this.routes = {
+    '/products/sale': saleRoute,
+    '/products': productsRoute,
+    defaultRoute
+};
 ```
 
-## Navigate
-
-you can also trigger navigation to a route with the navigate method
+If no prefix matches, `defaultRoute` is used when present.
 
-```
-myRouter.navigate('/page2');
-```
+## Navigate from HTML
 
-## Mediator
-
-Optionally you can use a mediator, such as White Label Mediator, with the router. To do so you would like this:
+The router delegates one document-level click listener. Add `data-pushstate` to an anchor to use client-side navigation:
 
+```html
+<a href="/products/42" data-pushstate>
+    <span>View product 42</span>
+</a>
 ```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
 
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
+Clicks on nested elements such as the `span` are resolved to the enclosing anchor. Links without `data-pushstate` keep their normal browser behavior.
 
-        this.mediator = myMediator;
+Modified clicks, non-left clicks, downloads, links targeting another browsing context, and cross-origin URLs also keep their normal browser behavior.
 
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
+## Navigate from JavaScript
 
-    }
-};
-```
-
-Then anywhere else in the application you want to trigger the router to navigate you could do so like this:
-
-```
-myMediator.emit('router:navigate', {
-    url: '/authentication',
-    message: 'Session expired, please login again.'
+```js
+router.navigate('/products/42', {
+    source: 'featured-products'
 });
 ```
 
-## Scope
-
-Optionally you and provide a DOM element to be the scope of the router. That DOM object will then be passed into all your routes as they are executed. To do so you would like this:
-
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
-
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
+The second argument becomes `location.data.mediator`. Unless the call represents a browser `popstate`, successful navigation adds the URL to browser history.
 
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
+## Location data
 
-    }
-};
-```
+Every route receives the configured `scope` and a location object:
 
-## Passing Data
-
-The router passes in a location data object to the route that is being executed. Here is an example object passed:
-
-```
+```js
 {
-    url: ['/user'],
+    url: '/products/42?color=blue',
     data: {
-        url: [],
-        mediator: {},
-        query: {}
+        url: ['42'],
+        mediator: {
+            source: 'featured-products'
+        },
+        query: {
+            color: 'blue'
+        }
     }
 }
 ```
 
-'data.url' is an array of values parsed from the url being requested. For Example if the url was '/user/fred' and we defined a route for '/user' then data object passed into the '/user' route would be the following:
+- `url` is the complete route URL.
+- `data.url` contains path segments after the matched route prefix.
+- `data.mediator` contains the object passed to `navigate()` or received from the mediator.
+- `data.query` contains parsed query values.
 
-```
-{
-    url: ['/user/fred'],
-    data: {
-        url: ['fred'],
-        mediator: {},
-        query: {}
-    }
-}
-```
+Path segments and query values are URI-decoded with browser-native URL APIs. Application code must still validate values before using them.
 
-'data.query' is an object of values parsed from the url query string. For Example if the url was '/user?name=fred' and we defined a route for '/user' then data object passed into the '/user' route would be the following:
+## Version 3 migration note
 
-```
-{
-    url: ['/user?name=fred'],
-    data: {
-        url: [],
-        mediator: {},
-        query: {
-            name: 'fred'
-        }
-    }
-}
-```
+Version 3 changes route matching from unrestricted string prefixes to path boundaries. A route such as `/page2` no longer matches `/page23`. Define `/page23` explicitly if the application previously depended on that behavior.
 
-'data.mediator' is an object of values parsed through the optional mediator. For Example if this was emitted through the mediator:
+## Mediator navigation
 
-```
-myMediator.emit('router:navigate', {
-    url: '/authentication',
-    message: 'Session expired, please login again.'
+Assign an EventEmitter-compatible mediator before initialization:
+
+```js
+import Mediator from 'white-label-mediator';
+
+const mediator = new Mediator();
+const router = new ApplicationRouter();
+router.mediator = mediator;
+router.initialize();
+
+mediator.emit('router:navigate', {
+    url: '/account',
+    reason: 'Session refreshed'
 });
 ```
 
-Then the location data passed in to the '/authentication' route would be the following:
+The complete emitted object is passed to the route as `location.data.mediator`. `destroy()` removes the document, window, and mediator listeners. Repeated listener initialization is idempotent and does not add duplicate listeners.
 
-```
-{
-    url: ['/authentication'],
-    data: {
-        url: [],
-        mediator: {
-            url: '/authentication',
-            message: 'Session expired, please login again.'
-        }
-    }
-}
-```
+## Lifecycle
 
-## Let's look at an example:
+| Method | Behavior |
+| --- | --- |
+| `initialize()` | Reads the browser URL, adds listeners, and runs the initial route. |
+| `navigate(url, data, isPopState)` | Matches and runs a route, updates history, and returns the router; returns `false` when blocked or invalid. |
+| `addListeners()` | Adds browser and optional mediator listeners once. |
+| `removeListeners()` | Removes listeners previously added by this router. |
+| `destroy()` | Calls `removeListeners()` and returns the router. |
 
-import the module
+Call `destroy()` when the router is no longer used:
 
-```
-import Router from 'white-label-router';
+```js
+router.destroy();
 ```
 
-extend the router
+## Development
 
+```sh
+npm ci
+npm run build
+npm run typecheck
+npm test
+npm run coverage
+npm run audit
 ```
-const myRouter = class extends Router {
-    // this is the constructor. This executed whenever the view is instantiated.
-    constructor() {
 
-        super();
+The npm package publishes the compiled `dist` file and this README.
 
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
+## TypeScript development and version 4.0.0 migration
 
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
-        
-    }
-};
+Implementation code now uses strict TypeScript. Builds emit JavaScript, source maps with embedded source, and `.d.ts` declarations into `dist`. JavaScript callers can still use the package without compiling TypeScript themselves. JSDoc comments describe parameters, return values, lifecycle behavior, and validation at the implementation, and are retained in declarations.
 
-```
-
-instantiate your router
+```ts
+import Router from 'white-label-router';
 
-```
-const myRouter = new MyRoute();
+const router = new Router();
+const greeting: Router.Route = (scope, location) => {
+    console.log(location.data.query.name); // /hello?name=Ada
+};
+router.routes['/hello'] = greeting;
+router.initialize();
 ```
 
-initialize your router
+`Router.Route` covers function routes and objects with a guard or view lifecycle. `Router.Location` describes decoded URL data, `Router.Navigation` describes mediator payloads, and `Router.Handler` describes a route callback. Browser DOM types are required when compiling a consuming application.
 
-```
-myRouter.initialize();
-```
+This is a major release because the distribution is now CommonJS emitted by TypeScript, replacing the previous UMD wrapper. CommonJS `require` and the documented ESM imports remain supported. Direct AMD loading or browser script tags that depended on UMD globals must migrate to a browser bundler. Edit `src/*.ts`, then run `npm run build`; do not edit generated `dist` files. The obsolete Babel build dependencies have been removed.
 
-navigate to '/page2'
+### Verification and coverage
 
+```sh
+npm ci --ignore-scripts
+npm run typecheck
+npm test
+npm run coverage
+npm pack --dry-run
 ```
-myRouter.navigate('/page2');
-```
 
-In the example above we have set up two routes. The first route 'defaultRoute' is a catch all route. If no other routes match the specified url path this is the route that will be executed. In this example the defaultRoute would be executed for 'http://example.com' or 'http://example.com/home', but not 'http://example.com/page2'.
+`npm test` builds the code, checks TypeScript consumer examples against the emitted declarations, and runs the tests. `npm run coverage` additionally enforces **100% statements, branches, functions, and lines for each implementation file**. Unexecuted implementation files count toward the result; declaration-only files contain no executable code and are excluded. Reports are written to `coverage`, including `lcov.info` for coverage viewers. CI runs the same gate and checks committed build output for drift.
+
+Tests exercise the compiled JavaScript interface used by downstream callers. Coverage is an execution metric, not proof that all possible inputs or external integrations are correct.
 
-The second defined route 'page2' will only be executed when the specified url path starts with '/page2', or for example 'http://example.com/page2'.
+To undo this migration, revert its commit and run `npm ci` from the restored lockfile. No npm release, database migration, or production deployment is performed by these development changes.

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+/** Navigation payload, including caller-defined metadata. */
+interface NavigationData {
+    url?: string;
+    [key: string]: unknown;
+}
+/** URL-derived values supplied to route handlers. */
+interface LocationData {
+    url: string;
+    data: {
+        url: string[];
+        mediator: NavigationData | undefined;
+        query: Record<string, string>;
+    };
+}
+type RouteHandler = (scope: Element | null, location: LocationData) => unknown;
+/** An object route can own a function or a view lifecycle. */
+interface RouteObject {
+    title?: string;
+    secure?: RouteHandler;
+    view?: RouteHandler | {
+        initialize?: RouteHandler;
+        destroy?: RouteHandler;
+    };
+}
+type Route = RouteHandler | RouteObject;
+/** Minimal event-bus contract required by the router. */
+interface NavigationMediator {
+    on(event: string, callback: (data?: NavigationData) => unknown): unknown;
+    removeListener?(event: string, callback: (data?: NavigationData) => unknown): unknown;
+}
+/** History API router with ordered path-boundary matching. */
+declare class Router {
+    routes: Record<string, Route>;
+    url: string;
+    route: string | null;
+    scope: Element | null;
+    previousRoute: string | null;
+    pageTitle: string | null;
+    mediator: NavigationMediator | false;
+    boundPushStateClick: (event: MouseEvent) => unknown;
+    boundPopState: (event: PopStateEvent) => unknown;
+    boundMediatorNavigate: (data?: NavigationData) => unknown;
+    listenersInitialized: boolean;
+    locationData: LocationData;
+    /**
+     * Create an instance with its own state and listener references.
+     */
+    constructor();
+    /**
+     * Start this instance and return it for lifecycle chaining.
+     * @returns This instance for chaining.
+     */
+    initialize(): this;
+    /**
+     * Register stable document, history, and optional mediator handlers once.
+     * @returns This instance for chaining.
+     */
+    addListeners(): this;
+    /**
+     * Release owned state and listeners so the instance can leave the application lifecycle.
+     * @returns This instance after cleanup.
+     */
+    destroy(): this;
+    /**
+     * Release listeners owned by this instance; subclasses may extend the lifecycle hook.
+     * @returns This instance for chaining.
+     */
+    removeListeners(): this;
+    /**
+     * Intercept eligible same-origin push-state links while preserving normal browser actions.
+     * @param e - Browser event being handled.
+     * @returns True when the browser should handle the event, or this router after interception.
+     */
+    eventPushStateClick(e: MouseEvent): true | this;
+    /**
+     * Restore browser history state without adding a new history entry.
+     * @param e - Browser event being handled.
+     * @returns This router after restoring the history state.
+     */
+    eventPopState(e: PopStateEvent): this;
+    /**
+     * Decode URL query parameters, keeping the last value for duplicate keys.
+     * @param queryString - Encoded URL query portion.
+     * @returns A record of decoded query names and their final values.
+     */
+    parseQueryString(queryString: string): {
+        [k: string]: string;
+    };
+    /**
+     * Build decoded path, query, and mediator data for the selected route.
+     * @param mediatorData - Optional caller metadata passed to the route.
+     * @returns No value; locationData is updated in place.
+     */
+    setLocationData(mediatorData?: NavigationData): void;
+    /**
+     * Select a route, enforce its guard, transition view lifecycles, and update history and title.
+     * @param url - URL or optional adapter argument.
+     * @param mediatorData - Optional caller metadata passed to the route.
+     * @param isPopState - Whether navigation came from browser history.
+     * @returns False when a guard or route rejects navigation; otherwise this router.
+     */
+    navigate(url?: string | false, mediatorData?: NavigationData, isPopState?: boolean): false | this;
+}
+/** Public route configuration and navigation payload types. */
+declare namespace Router {
+    type Handler = RouteHandler;
+    type Route = RouteHandler | RouteObject;
+    type Location = LocationData;
+    type Navigation = NavigationData;
+}
+export = Router;