@thi.ng/router 4.0.11 → 4.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-06-21T19:34:38Z
+- **Last updated**: 2024-07-02T12:48:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [4.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@4.1.0) (2024-07-02)
+
+#### 🚀 Features
+
+- update HTMLRouter initial & default route handling ([8ea075e](https://github.com/thi-ng/umbrella/commit/8ea075e))
+  - avoid duplicate dispatch (and breaking back button) for missing routes
+  - new behavior: HTMLRouter dispatches default route redirect, but does **not** push it to history
+  - update initial route handling to use `replaceState()` instead of `pushState()`
+
 ### [4.0.11](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@4.0.11) (2024-06-21)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 193 standalone projects, maintained as part
+> This is one of 189 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -71,7 +71,7 @@ Browser ESM import:
 
 [JSDelivr documentation](https://www.jsdelivr.com/)
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.94 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.93 KB
 
 ## Dependencies
 
@@ -83,12 +83,13 @@ Package sizes (brotli'd, pre-treeshake): ESM: 1.94 KB
 
 ## Usage examples
 
-One project in this repo's
+Several projects in this repo's
 [/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
-directory is using this package:
+directory are using this package:
 
 | Screenshot                                                                                                           | Description                                             | Live demo                                           | Source                                                                           |
 |:---------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------|:----------------------------------------------------|:---------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-router.jpg" width="240"/>   | Basic thi.ng/router usage with thi.ng/rdom components   | [Demo](https://demo.thi.ng/umbrella/rdom-router/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-router)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/router-basics.jpg" width="240"/> | Complete mini SPA app w/ router & async content loading | [Demo](https://demo.thi.ng/umbrella/router-basics/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/router-basics) |
 
 ## API

package/api.d.ts

@@ -136,11 +136,19 @@ export interface RouterOpts<T = any> {
     /**
      * Fallback route ID (MUST exist in `routes`), used if none of the defined
      * routes could be matched against user input, e.g. a home or error page.
+     *
+     * @remarks
+     * If using {@link HTMLRouter}, any redirects to this route will **not** be
+     * recorded to the browser history.
      */
     default: string;
     /**
      * Optional initial route to trigger when router starts. If given, this MUST
      * be a route without params.
+     *
+     * @remarks
+     * If using {@link HTMLRouter}, this route will be applied to the browser
+     * history using `replaceState()`.
      */
     initial?: string;
     /**

package/html.d.ts

@@ -6,26 +6,24 @@ export declare class HTMLRouter<T = any> extends Router<T> {
     protected popHandler: Fn<PopStateEvent, void>;
     protected hashHandler: EventListener;
     protected useFragment: boolean;
-    protected ignoreHashChange: boolean;
     constructor(config: HTMLRouterOpts);
     start(): void;
     release(): void;
     /**
-     * Like {@link Router.route}, but takes additional arg to control if
-     * this routing operation should manipulate the browser's `history`.
+     * Like {@link Router.route}, but takes additional arg to control if this
+     * routing operation should manipulate the browser's `history`.
      *
      * @remarks
-     * If called from userland, this normally is true (also default). However,
-     * we want to avoid this if called from this router's own event handlers.
+     * If called from userland, this normally is set to "push" (also the
+     * default). However, we want to adjust this behavior if called internally.
      *
      * @param src -
      * @param ctx -
-     * @param pushState -
+     * @param mode -
      */
-    route(src: string, ctx?: T, pushState?: boolean): import("@thi.ng/api").Maybe<import("./api.js").RouteMatch>;
+    route(src: string, ctx?: T, mode?: "push" | "replace" | "none"): import("@thi.ng/api").Maybe<import("./api.js").RouteMatch>;
     routeTo(route: string, ctx?: T): void;
     protected handlePopChange(): Fn<PopStateEvent, void>;
     protected handleHashChange(): EventListener;
-    protected handleRouteFailure(): boolean;
 }
 //# sourceMappingURL=html.d.ts.map

package/html.js

@@ -5,11 +5,9 @@ class HTMLRouter extends Router {
   popHandler;
   hashHandler;
   useFragment;
-  ignoreHashChange;
   constructor(config) {
     super({ prefix: config.useFragment ? "#/" : "/", ...config });
     this.useFragment = config.useFragment !== false;
-    this.ignoreHashChange = false;
   }
   start() {
     window.addEventListener("popstate", this.handlePopChange());
@@ -18,7 +16,7 @@ class HTMLRouter extends Router {
     }
     if (this.opts.initial) {
       const route = this.routeForID(this.opts.initial);
-      this.route(this.format({ id: route.id }));
+      this.route(this.format({ id: route.id }), void 0, "replace");
     } else {
       this.route(this.useFragment ? location.hash : location.pathname);
     }
@@ -30,24 +28,26 @@ class HTMLRouter extends Router {
     }
   }
   /**
-   * Like {@link Router.route}, but takes additional arg to control if
-   * this routing operation should manipulate the browser's `history`.
+   * Like {@link Router.route}, but takes additional arg to control if this
+   * routing operation should manipulate the browser's `history`.
    *
    * @remarks
-   * If called from userland, this normally is true (also default). However,
-   * we want to avoid this if called from this router's own event handlers.
+   * If called from userland, this normally is set to "push" (also the
+   * default). However, we want to adjust this behavior if called internally.
    *
    * @param src -
    * @param ctx -
-   * @param pushState -
+   * @param mode -
    */
-  route(src, ctx, pushState = true) {
+  route(src, ctx, mode = "push") {
     const old = this.current;
     const route = super.route(src, ctx);
     if (route && !equiv(route, old)) {
       this.currentPath = this.format(route);
-      if (pushState) {
+      if (mode === "push") {
         history.pushState(this.currentPath, "", this.currentPath);
+      } else if (mode === "replace") {
+        history.replaceState(this.currentPath, "", this.currentPath);
       }
     }
     return route;
@@ -63,28 +63,20 @@ class HTMLRouter extends Router {
       this.route(
         e.state || (this.useFragment ? location.hash : location.pathname),
         void 0,
-        false
+        "none"
       );
     }).bind(this);
   }
   handleHashChange() {
     return this.hashHandler = this.hashHandler || ((e) => {
-      if (!this.ignoreHashChange) {
+      if (!this.current?.redirect) {
         const hash = e.newURL.substring(e.newURL.indexOf("#"));
         if (hash !== this.currentPath) {
-          this.route(hash, void 0, false);
+          this.route(hash, void 0, "none");
         }
       }
     }).bind(this);
   }
-  handleRouteFailure() {
-    this.ignoreHashChange = true;
-    location.hash = this.format({
-      id: this.routeForID(this.opts.default).id
-    });
-    this.ignoreHashChange = false;
-    return true;
-  }
 }
 export {
   HTMLRouter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/router",
-  "version": "4.0.11",
+  "version": "4.1.0",
   "description": "Generic trie-based router with support for wildcards, route param validation/coercion, auth",
   "type": "module",
   "module": "./index.js",
@@ -36,10 +36,10 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.3",
-    "@thi.ng/checks": "^3.6.5",
-    "@thi.ng/equiv": "^2.1.59",
-    "@thi.ng/errors": "^2.5.8",
+    "@thi.ng/api": "^8.11.4",
+    "@thi.ng/checks": "^3.6.6",
+    "@thi.ng/equiv": "^2.1.60",
+    "@thi.ng/errors": "^2.5.9",
     "tslib": "^2.6.3"
   },
   "devDependencies": {
@@ -97,5 +97,5 @@
     ],
     "year": 2014
   },
-  "gitHead": "154c95cf9d6bab32174498ec3b5b5d87e42be7f9\n"
+  "gitHead": "4a2f35b6e720cc4ad3e2ff2549b78beb3f80732e\n"
 }