white-label-router 1.1.1 → 4.0.0

package/README.md

@@ -1,299 +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: (locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (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: (locationData) => {
-                        window.console.log('the defaultRoute initialized');
-                    },
-                    destroy: (locationData) => {
-                        window.console.log('the defaultRoute has been destroyed');
-                    }
-                }
+            '/products': (scope, location) => {
+                scope.textContent = `Product: ${location.data.url[0] || 'all'}`;
             },
-            '/page2': {
+            '/account': {
+                title: 'Your account',
+                secure: () => Boolean(window.currentUser),
                 view: {
-                    initialize: (locationData) => {
-                        window.console.log('the page2 initialized');
+                    initialize: (scope, location) => {
+                        scope.textContent = 'Account';
+                        console.log(location.data.query);
                     },
-                    destroy: (locationData) => {
-                        window.console.log('the page2 has been destroyed');
+                    destroy: () => {
+                        console.log('Leaving account');
                     }
                 }
+            },
+            defaultRoute: () => {
+                console.log('No configured route matched.');
             }
         };
     }
-};
+}
+
+const router = new ApplicationRouter();
+router.initialize();
 ```
 
-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:
+At startup, `initialize()` reads the current path and query string, registers document click and browser `popstate` listeners, and navigates to the matching route.
+
+## Define routes
 
+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();
-        this.routes = {
-            defaultRoute: {
-                title: 'Home',
-                view: {
-                    initialize: (locationData) => {
-                        window.console.log('the defaultRoute initialized');
-                    },
-                    destroy: (locationData) => {
-                        window.console.log('the defaultRoute has been destroyed');
-                    }
-                }
+
+Or it may describe a title, security check, and view lifecycle:
+
+```js
+this.routes = {
+    '/orders': {
+        title: 'Orders',
+        secure(scope, location) {
+            return Boolean(window.currentUser);
+        },
+        view: {
+            initialize(scope, location) {
+                scope.textContent = 'Order history';
             },
-            '/page2': {
-                title: 'Page 2',
-                view: {
-                    initialize: (locationData) => {
-                        window.console.log('the page2 initialized');
-                    },
-                    destroy: (locationData) => {
-                        window.console.log('the page2 has been destroyed');
-                    }
-                },
-                secure: this.isSecure
+            destroy(scope, nextLocation) {
+                scope.replaceChildren();
             }
-        };
-    }
-    isSecure (locationData) => {
-        if (someCookieIsValid) {
-            return true;
-        } else {
-            return false;
         }
     }
 };
 ```
 
-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'.
+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()`.
 
-## Instantiate
+### Route matching behavior
 
-```
-const myRouter = new MyRouter();
+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:
 
-myRouter.initialize();
+```js
+this.routes = {
+    '/products/sale': saleRoute,
+    '/products': productsRoute,
+    defaultRoute
+};
 ```
 
-## HTML Linking To Routes
-
-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'.
+If no prefix matches, `defaultRoute` is used when present.
 
-```
-<a href="/page2" data-pushstate>take me to page2</a>
-```
+## Navigate from HTML
 
-## Navigate
+The router delegates one document-level click listener. Add `data-pushstate` to an anchor to use client-side navigation:
 
-you can also trigger navigation to a route with the navigate method
-
-```
-myRouter.navigate('/page2');
+```html
+<a href="/products/42" data-pushstate>
+    <span>View product 42</span>
+</a>
 ```
 
-## Mediator
-
-Optionally you can use a mediator, such as White Label Mediator, with the router. To do so you would like this:
+Clicks on nested elements such as the `span` are resolved to the enclosing anchor. Links without `data-pushstate` keep their normal browser behavior.
 
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
+Modified clicks, non-left clicks, downloads, links targeting another browsing context, and cross-origin URLs also keep their normal browser behavior.
 
-        this.mediator = myMediator;
+## Navigate from JavaScript
 
-        this.routes = {
-            defaultRoute: (locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
-
-    }
-};
-```
-
-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'
 });
 ```
 
-## Passing Data
+The second argument becomes `location.data.mediator`. Unless the call represents a browser `popstate`, successful navigation adds the URL to browser history.
 
-The router passes in a location data object to the route that is being executed. Here is an example object passed:
+## Location data
 
-```
+Every route receives the configured `scope` and a location object:
+
+```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() {
-        // always do this
-        super();
-        this.routes = {
-            defaultRoute: (locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
-    }
-};
 
-```
+The npm package publishes the compiled `dist` file and this README.
 
-instantiate your router
+## TypeScript development and version 4.0.0 migration
 
-```
-const myRouter = new MyRoute();
-```
+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.
 
-initialize your router
+```ts
+import Router from 'white-label-router';
 
-```
-myRouter.initialize();
+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();
 ```
 
-navigate to '/page2'
+`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.
 
+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.
+
+### 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;