lit-navigation-router 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.6.0
+
+### Added
+
+- **`linkTo(name, params)` builds a URL from a route's `name`**
+  ([#16](https://github.com/VanLandinghamLabs/lit-router/issues/16), inherited
+  from [lit/lit#3352](https://github.com/lit/lit/issues/3352)).
+  `RouteConfig.name` has existed since the fork began and was never read by
+  anything, so a component could only link by URL and had to know where its
+  parent was mounted. `linkTo` runs a route's pattern backwards and prefixes it
+  with that route's ancestors, so moving a subtree no longer breaks the links
+  inside it.
+
+  Resolution covers the mounted controller tree: the controller it is called
+  on, its ancestors, and any descendant that has rendered. A route in an
+  unmounted branch is not addressable, because the mapping from a parent route
+  to its child controller only exists once that parent has rendered. An unknown
+  name, a duplicated one, or a missing parameter throws rather than returning a
+  wrong URL.
+
+  Patterns are reversed for literals, `:name`, `*` and `{...}` groups, each
+  optionally `?`. A regex group cannot be reversed and `+` or `*` repetition
+  has no single answer, so both throw. A trailing wildcard may be omitted,
+  since the empty tail is the index of a nested route space; any other wildcard
+  is required.
+
 ## 0.5.0
 
 ### Fixed
@@ -8,10 +34,10 @@
   ([#13](https://github.com/VanLandinghamLabs/lit-router/issues/13), inherited
   from [lit/lit#3517](https://github.com/lit/lit/issues/3517)). Patterns were
   executed as `exec({pathname})`, and `URLPattern` defaults every component the
-  caller omits to the empty string — so `new URLPattern({hash: 'one'})` was
+  caller omits to the empty string, so `new URLPattern({hash: 'one'})` was
   compared against a hash of `''` and could never match. A hash- or
-  search-constrained route matched nothing at all, which made `goto()` throw
-  `No route found` on every load rather than merely failing to fire. Matching
+  search-constrained route matched nothing at all, so `goto()` threw
+  `No route found` on every load instead of just failing to fire. Matching
   now sees the whole location. Named groups captured from the search and hash
   are merged into `params`; positional ones are not, since each component
   numbers its groups from zero and a merged `"0"` would masquerade as a tail.
@@ -23,8 +49,8 @@
 - **Fragment-only navigation is routed when a route asks for it.** `Router`
   declined every navigation with `hashChange` set, so a hash route could not be
   reached by clicking a link even once matching was fixed. Such navigations are
-  now intercepted when — and only when — some route in the tree constrains the
-  hash, so pathname-only apps keep the browser's native in-page scrolling.
+  now intercepted only when some route in the tree constrains the hash, so
+  pathname-only apps keep the browser's native in-page scrolling.
 
 ### Changed
 
@@ -100,7 +126,7 @@
     the second-to-last group as its tail.
 
   **This changes behaviour.** If a route combines a wildcard with a param name
-  containing a digit, the child controller now receives a different path — the
+  containing a digit, the child controller now receives a different path, the
   correct one. Anything relying on the old selection was relying on the child
   being given the wrong segment.
 
@@ -119,7 +145,7 @@
   running every pattern, and the fallback no longer rebuilds a `URLPattern` on
   every navigation.
 - `location.origin` is read per navigation rather than at module scope, so
-  importing the package no longer touches `location` — importing it where there
+  importing the package no longer touches `location`. Importing it where there
   is no DOM previously threw, contradicting `sideEffects: false`.
 
 ### Known issues

package/README.md

@@ -5,8 +5,8 @@
 A router for Lit, built on the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API).
 Published on npm as [`lit-navigation-router`](https://www.npmjs.com/package/lit-navigation-router).
 
-Fork of [`@lit-labs/router`](https://github.com/lit/lit/tree/main/packages/labs/router)
-— see [NOTICE.md](./NOTICE.md) for provenance, licence and the full list of
+Fork of [`@lit-labs/router`](https://github.com/lit/lit/tree/main/packages/labs/router).
+See [NOTICE.md](./NOTICE.md) for provenance, licence and the full list of
 changes. Not affiliated with or endorsed by Google or the Lit team.
 
 ```sh
@@ -62,9 +62,10 @@ await routes.goto('/item/1', {signal});
 
 ## Nested routes and tails
 
-A route whose pattern ends in a wildcard — `/docs/*` — hands what the wildcard
-matched (the *tail*) to any `Routes` controller mounted by its `render()`. The
-tail has no leading slash, and child routes are written the same way:
+A route whose pattern ends in a wildcard, such as `/docs/*`, hands what the
+wildcard matched (the tail) to any `Routes` controller mounted by its
+`render()`. The tail has no leading slash, and child routes are written the
+same way:
 
 ```ts
 // Parent
@@ -78,7 +79,7 @@ private _routes = new Routes(this, [
 ```
 
 The index of a nested route space is the empty tail, spelled `{path: ''}`.
-`{path: '/'}` matches nothing there: it would need a tail of `/`, i.e. a URL of
+`{path: '/'}` matches nothing there. It would need a tail of `/`, so a URL of
 `/docs//`.
 
 Only a trailing wildcard produces a tail. An unnamed regex group
@@ -90,7 +91,7 @@ tail it is handed and passes that on.
 
 ## Search and hash routes
 
-A `pattern` route can constrain `search` and `hash`, not just `pathname`:
+A `pattern` route can constrain `search` and `hash` as well as `pathname`:
 
 ```ts
 {pattern: new URLPattern({pathname: '/docs', hash: ':section'}),
@@ -106,32 +107,65 @@ independently, so merging them would make a fragment indistinguishable from a
 tail. Name the groups you need.
 
 Only the pathname nests. A child controller is handed the parent's tail as its
-pathname and the *same* search and hash — there is no way to split a query
-string or a fragment across a route tree.
+pathname and the same search and hash. There is no way to split a query string
+or a fragment across a route tree.
 
-Fragment-only navigation (`<a href="#section">`) is intercepted **only** when
-some route constrains the hash. An app that routes on pathnames alone keeps the
+Fragment-only navigation (`<a href="#section">`) is intercepted only when some
+route constrains the hash. An app that routes on pathnames alone keeps the
 browser's native in-page scrolling.
 
-## Browser support — please read
+## Named routes
 
-This router **requires the Navigation API**. There is no legacy fallback.
+Give a route a `name` and link to it by that name instead of by URL, so a
+component does not have to know where the route currently lives:
 
-The API is Baseline **Newly** Available (January 2026: Chrome/Edge, Safari 26.2,
-Firefox 147). Baseline **Widely** Available is not until roughly mid-2028, so
-older engines are still in the wild.
+```ts
+{name: 'page', path: ':page', render: ({page}) => html`<doc-page .page=${page}></doc-page>`}
+
+// Anywhere in the mounted tree:
+html`<a href="${this._routes.linkTo('page', {page: 'intro'})}">Intro</a>`
+// => /docs/intro
+```
+
+`linkTo(name, params)` runs the route's pattern backwards and prefixes it with
+the route's ancestors, so moving a subtree from `/docs/*` to `/guide/*` does not
+break the links inside it. To navigate rather than render an href, hand the
+result to `goto()`.
+
+Resolution covers the mounted controller tree: the controller you call it on,
+its ancestors, and any descendant that has rendered. A route in a branch that
+has not mounted yet is not addressable, because the mapping from a parent route
+to its child controller only exists once that parent has rendered. An unknown
+name, an ambiguous one, or a missing parameter throws rather than producing a
+wrong URL.
+
+A trailing wildcard may be left out, since the empty tail is the index of a
+nested route space: `linkTo('docs')` on `{name: 'docs', path: '/docs/*'}` gives
+`/docs/`. Any other wildcard is required, because dropping it would silently
+join the segments around it.
+
+Patterns are reversed for literals, `:name`, `*` and `{...}` groups, each
+optionally `?`. A regex group cannot be reversed and `+` or `*` repetition has
+no single answer, so both throw. Name the groups you want to link to.
+
+## Browser support, please read
+
+This router requires the Navigation API. There is no legacy fallback.
+
+The API is Baseline Newly Available (January 2026: Chrome/Edge, Safari 26.2,
+Firefox 147). Baseline Widely Available is not until roughly mid-2028, so older
+engines are still in the wild.
 
 On an engine without it, `Router` renders the current route on load but does not
-intercept navigation — every link becomes an ordinary full page load. If your
+intercept navigation, so every link becomes an ordinary full page load. If your
 server serves the app shell on every route that is slower, not broken. If it
 does not, those links 404.
 
-**One case is genuinely broken, not just slow.** If you navigate
-programmatically with `history.pushState()` + `router.goto()`, nothing listens
-for the resulting `popstate` — so Back moves the URL while the outlet stays put,
-which is the URL/outlet split this fork exists to eliminate. Apps using that
-pattern should gate on `supportsNavigationApi()` rather than accept the
-degradation.
+One case is broken rather than slow. If you navigate programmatically with
+`history.pushState()` plus `router.goto()`, nothing listens for the resulting
+`popstate`, so Back moves the URL while the outlet stays put. That is the
+URL/outlet split this fork exists to eliminate. Apps using that pattern should
+gate on `supportsNavigationApi()` rather than accept the degradation.
 
 `supportsNavigationApi()` is exported so you can detect this at boot:
 
@@ -144,15 +178,15 @@ if (!supportsNavigationApi()) {
 ```
 
 If you need real pre-2026 support, pair this with a Navigation API polyfill
-rather than a second router: one decision path, with compatibility isolated in
-a layer whose whole job is spec accuracy.
+rather than a second router. That keeps one decision path, with compatibility
+isolated in a layer whose whole job is spec accuracy.
 
 ## `URLPattern`
 
 Route patterns are compiled with `URLPattern`, which this package uses from the
-global scope and does **not** polyfill — same as upstream. Every engine that has
-the Navigation API also has `URLPattern`, so if the support check above passes
-you need nothing. If you support older engines anyway, load
+global scope and does not polyfill, same as upstream. Every engine that has the
+Navigation API also has `URLPattern`, so if the support check above passes you
+need nothing. If you support older engines anyway, load
 [`urlpattern-polyfill`](https://www.npmjs.com/package/urlpattern-polyfill)
 before the router:
 
@@ -163,14 +197,14 @@ if (!globalThis.URLPattern) {
 }
 ```
 
-The published types do not depend on it — `URLPatternRouteConfig.pattern` is
+The published types do not depend on it. `URLPatternRouteConfig.pattern` is
 typed structurally, so a consumer build never needs the polyfill's types.
 
 ## Develop
 
 ```sh
 npm install
-npm run build        # tsc → development/
+npm run build        # tsc to development/
 npm test             # Web Test Runner (Chromium via Playwright)
 npm run check-types
 ```

package/development/router.d.ts

@@ -13,61 +13,28 @@ export interface InterceptOptions {
     scroll?: 'after-transition' | 'manual';
 }
 /**
- * True when the Navigation API is available — Baseline Newly Available since
- * January 2026 (Chrome/Edge, Safari 26.2, Firefox 147).
- *
- * This router **requires** it. Exported so an app can detect an unsupported
- * engine at boot and say so, rather than leaving the user to notice that every
- * link reloads the page.
+ * True when the Navigation API is available (Baseline Newly Available, January
+ * 2026). This router requires it; exported so an app can detect an unsupported
+ * engine at boot rather than leaving users to notice every link reloading.
  */
 export declare const supportsNavigationApi: () => boolean;
 /**
- * A root-level router that intercepts navigation via the Navigation API.
- *
- * This class extends Routes so that it can also have a route configuration.
- *
- * There should only be one Router instance on a page, since the Router
- * installs a global listener. Nested routes should be configured with the
- * `Routes` class.
- *
- * ## Why the Navigation API
- *
- * Upstream intercepted navigation with a global click listener plus `popstate`
- * and committed with `history.pushState()`. That is structurally racy:
- * `pushState` is synchronous and `popstate` fires *after* the URL has already
- * moved, but `goto()` awaits `route.enter()` before swapping the outlet. The
- * URL leads and the outlet lags, leaving two sources of truth — the outgoing
- * route re-renders with stale params, and two quick navigations commit in
- * whatever order their `enter()` hooks happen to resolve.
- *
- * `navigateEvent.intercept({handler})` collapses that. The browser commits the
- * URL and holds the navigation un-finished while the handler runs, and it
- * aborts `navigateEvent.signal` when a newer navigation supersedes this one —
- * which `goto()` honours, so a superseded route can no longer win the outlet.
- *
- * ## No legacy fallback
- *
- * An earlier version of this fork kept upstream's click/popstate path for
- * pre-2026 engines. It was removed deliberately. Ten review rounds found
- * divergences between the two paths and **every one was in the click handler**,
- * never in this one — which is structural, not luck: this handler reads a
- * decision the browser has already made, while the click handler had to
- * re-derive it, re-implementing the rules for choosing a navigable, the
- * fragment-navigation predicate, and the modifier-key rules. Each round found
- * another place where the re-implementation and the spec disagreed.
- *
- * On an engine without the API, links fall back to ordinary full page loads.
- * For an app whose server serves the shell on every route that still works —
- * it is slower, not broken — and `supportsNavigationApi()` lets you detect it.
- * If real pre-2026 support is ever needed, use a Navigation API polyfill: one
- * decision path, with compatibility isolated in a layer whose whole job is
- * spec accuracy.
+ * A root-level router that intercepts navigation via the Navigation API. Use one
+ * per page, since it installs a global listener, and `Routes` for nested spaces.
+ *
+ * Upstream committed with `history.pushState()` and reacted to `popstate`, but
+ * swapped the outlet only after awaiting `enter()`. The URL led and the outlet
+ * lagged, so the outgoing route re-rendered with stale params and quick
+ * navigations committed out of order. `intercept({handler})` collapses that:
+ * the browser holds the navigation unfinished while the handler runs and aborts
+ * `signal` when a newer one supersedes it.
+ *
+ * There is no legacy fallback for pre-2026 engines. Without the API links
+ * become full page loads, which `supportsNavigationApi()` detects. See the
+ * README for what that degrades and what it breaks.
  */
 export declare class Router extends Routes {
-    /**
-     * Options forwarded to `navigateEvent.intercept()`. Leaving these unset
-     * gives the browser's default scroll and focus handling.
-     */
+    /** Forwarded to `navigateEvent.intercept()`. Unset uses browser defaults. */
     interceptOptions?: InterceptOptions;
     private _listening;
     hostConnected(): void;

package/development/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAqBnC,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAAC;IAC3C,MAAM,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAAC;CACxC;AAyBD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAO,OAEgB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,MAAO,SAAQ,MAAM;IAChC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC,OAAO,CAAC,UAAU,CAAS;IAElB,aAAa;IAwBb,gBAAgB;IAQzB;;;OAGG;IACH,OAAO,CAAC,WAAW,CAkEjB;CACH"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAoBnC,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAAC;IAC3C,MAAM,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAAC;CACxC;AAoBD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAO,OAEgB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,MAAO,SAAQ,MAAM;IAChC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC,OAAO,CAAC,UAAU,CAAS;IAElB,aAAa,SAerB;IAEQ,gBAAgB,SAMxB;IAED;;;OAGG;IACH,OAAO,CAAC,WAAW,CAgDjB;CACH"}

package/development/router.js

@@ -8,89 +8,44 @@
  */
 import { Routes } from './routes.js';
 const getNavigation = () => window.navigation;
-/**
- * The current location as a path string, in the form `goto()` parses.
- *
- * Only the origin is dropped: this router matches within one origin, and
- * `_onNavigate` declines anything else before it gets here.
- */
+/** The current location in the form `goto()` parses, minus the origin. */
 const currentPath = () => window.location.pathname + window.location.search + window.location.hash;
 /**
- * True when the Navigation API is available — Baseline Newly Available since
- * January 2026 (Chrome/Edge, Safari 26.2, Firefox 147).
- *
- * This router **requires** it. Exported so an app can detect an unsupported
- * engine at boot and say so, rather than leaving the user to notice that every
- * link reloads the page.
+ * True when the Navigation API is available (Baseline Newly Available, January
+ * 2026). This router requires it; exported so an app can detect an unsupported
+ * engine at boot rather than leaving users to notice every link reloading.
  */
 export const supportsNavigationApi = () => typeof window !== 'undefined' &&
     typeof getNavigation()?.addEventListener === 'function';
 /**
- * A root-level router that intercepts navigation via the Navigation API.
- *
- * This class extends Routes so that it can also have a route configuration.
- *
- * There should only be one Router instance on a page, since the Router
- * installs a global listener. Nested routes should be configured with the
- * `Routes` class.
+ * A root-level router that intercepts navigation via the Navigation API. Use one
+ * per page, since it installs a global listener, and `Routes` for nested spaces.
  *
- * ## Why the Navigation API
+ * Upstream committed with `history.pushState()` and reacted to `popstate`, but
+ * swapped the outlet only after awaiting `enter()`. The URL led and the outlet
+ * lagged, so the outgoing route re-rendered with stale params and quick
+ * navigations committed out of order. `intercept({handler})` collapses that:
+ * the browser holds the navigation unfinished while the handler runs and aborts
+ * `signal` when a newer one supersedes it.
  *
- * Upstream intercepted navigation with a global click listener plus `popstate`
- * and committed with `history.pushState()`. That is structurally racy:
- * `pushState` is synchronous and `popstate` fires *after* the URL has already
- * moved, but `goto()` awaits `route.enter()` before swapping the outlet. The
- * URL leads and the outlet lags, leaving two sources of truth — the outgoing
- * route re-renders with stale params, and two quick navigations commit in
- * whatever order their `enter()` hooks happen to resolve.
- *
- * `navigateEvent.intercept({handler})` collapses that. The browser commits the
- * URL and holds the navigation un-finished while the handler runs, and it
- * aborts `navigateEvent.signal` when a newer navigation supersedes this one —
- * which `goto()` honours, so a superseded route can no longer win the outlet.
- *
- * ## No legacy fallback
- *
- * An earlier version of this fork kept upstream's click/popstate path for
- * pre-2026 engines. It was removed deliberately. Ten review rounds found
- * divergences between the two paths and **every one was in the click handler**,
- * never in this one — which is structural, not luck: this handler reads a
- * decision the browser has already made, while the click handler had to
- * re-derive it, re-implementing the rules for choosing a navigable, the
- * fragment-navigation predicate, and the modifier-key rules. Each round found
- * another place where the re-implementation and the spec disagreed.
- *
- * On an engine without the API, links fall back to ordinary full page loads.
- * For an app whose server serves the shell on every route that still works —
- * it is slower, not broken — and `supportsNavigationApi()` lets you detect it.
- * If real pre-2026 support is ever needed, use a Navigation API polyfill: one
- * decision path, with compatibility isolated in a layer whose whole job is
- * spec accuracy.
+ * There is no legacy fallback for pre-2026 engines. Without the API links
+ * become full page loads, which `supportsNavigationApi()` detects. See the
+ * README for what that degrades and what it breaks.
  */
 export class Router extends Routes {
-    /**
-     * Options forwarded to `navigateEvent.intercept()`. Leaving these unset
-     * gives the browser's default scroll and focus handling.
-     */
+    /** Forwarded to `navigateEvent.intercept()`. Unset uses browser defaults. */
     interceptOptions;
     _listening = false;
     hostConnected() {
         super.hostConnected();
-        // Gated on the exported predicate, not on `navigation !== undefined`:
-        // a stub or partial polyfill under that name would otherwise make this
-        // branch throw out of connectedCallback while `supportsNavigationApi()`
-        // told the app it was unsupported — and then even the initial render below
-        // would not run.
+        // The predicate, not `navigation !== undefined`: a partial polyfill would
+        // otherwise throw out of connectedCallback and skip the render below.
         if (supportsNavigationApi()) {
             getNavigation().addEventListener('navigate', this._onNavigate);
             this._listening = true;
         }
-        // Kick off routed rendering by going to the current URL. Done even without
-        // the API: a full page load still renders the right route, which is what
-        // makes the unsupported-engine degradation "slow" rather than "blank".
-        // Surfaced rather than left as a bare unhandled rejection, matching the
-        // convention in routes.ts: on an engine without the API this is the *only*
-        // rendering path, and a deep link with no matching route throws here.
+        // Runs even without the API, which is what makes the degradation slow
+        // rather than blank. Surfaced because it is then the only rendering path.
         void this.goto(currentPath()).catch((err) => {
             queueMicrotask(() => {
                 throw err;
@@ -109,53 +64,36 @@ export class Router extends Routes {
      * `navigation.navigate()`, `history.pushState()`, and back/forward.
      */
     _onNavigate = (e) => {
-        // Not ours to handle: anything the browser says cannot be intercepted,
-        // downloads, and POST form submissions.
-        //
-        // `!= null`, not `!== null`: the spec types both as nullable-but-present,
-        // but a polyfill that leaves either unset would make a strict check true
-        // for every ordinary link and silently decline the whole app.
+        // `!= null`: a polyfill leaving either unset would make a strict check
+        // true for every link and silently decline the whole app.
         if (!e.canIntercept || e.downloadRequest != null || e.formData != null) {
             return;
         }
-        // Fragment-only moves belong to the browser unless a route actually reads
-        // the fragment. Intercepting them unconditionally would cost every
-        // pathname-only app its native in-page scrolling — and re-render the same
-        // route to no effect — while declining them unconditionally is the
-        // lit/lit#3517 bug this router inherited.
+        // Fragment-only moves are the browser's unless a route reads the fragment.
+        // Always intercepting costs native scrolling; never intercepting is
+        // lit/lit#3517. See #13.
         if (e.hashChange && !this._constrainsHash()) {
             return;
         }
         // Reloads must stay reloads. `canIntercept` is true for them, so without
-        // this `location.reload()` silently degrades to re-running goto() on the
-        // same path — the document is never replaced, breaking the standard
-        // "new version available, reload" escape hatch. (It would also disagree
-        // with the browser's own refresh button, which is not interceptable.)
+        // this `location.reload()` never replaces the document.
         if (e.navigationType === 'reload') {
             return;
         }
-        // `rel="external"` is a convention this router honours — it is not defined
-        // by HTML or by the Navigation API, so the browser will not decline these
-        // for us. Best-effort: `sourceElement` is not in every engine, and is
-        // absent for programmatic navigation.
+        // This router's convention, not HTML's, so the browser will not decline
+        // these for us. Best-effort: `sourceElement` is not everywhere.
         if (e.sourceElement?.getAttribute?.('rel') === 'external') {
             return;
         }
-        // Read per navigation rather than cached at module scope: the value cannot
-        // change, but reading it on import makes merely importing this module throw
-        // where there is no `location` (SSR, a bundler evaluating for tree-shaking
-        // under the package's `sideEffects: false` claim).
+        // Per navigation, not module scope: reading `location` on import throws
+        // under SSR, contradicting the package's `sideEffects: false`.
         const url = new URL(e.destination.url);
         if (url.origin !== window.location.origin) {
             return;
         }
-        // Only intercept what we can actually render. `canIntercept` is true for
-        // any same-origin URL, including cross-document ones — so without this a
-        // link to a server-rendered page, an export endpoint, or a GET form
-        // (whose `formData` is null) gets swallowed: the URL commits, goto()
-        // throws "No route found", and the address bar is left pointing somewhere
-        // the outlet never went. Declining lets the browser do the real
-        // navigation, which is the correct outcome.
+        // `canIntercept` is true for cross-document same-origin URLs too, so
+        // without this a server-rendered page or GET form gets swallowed: the URL
+        // commits, goto() throws, and the outlet never moves.
         const path = url.pathname + url.search + url.hash;
         if (!this.hasRouteFor(path)) {
             return;
@@ -163,8 +101,7 @@ export class Router extends Routes {
         e.intercept({
             ...this.interceptOptions,
             handler: async () => {
-                // `e.signal` aborts if another navigation starts before this handler
-                // resolves; goto() checks it after `enter()` and stands down.
+                // `e.signal` aborts if a newer navigation starts; goto() checks it.
                 await this.goto(path, { signal: e.signal });
             },
         });

package/development/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2021 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n *\n * Modifications Copyright 2026 VanLandingham Labs, same license.\n * Rebuilt on the Navigation API; see NOTICE.md.\n */\n\nimport {Routes} from './routes.js';\n\n/**\n * The slice of `NavigateEvent` this router reads. Declared locally rather than\n * typing the handler `any`: these properties *are* the correctness boundary, so\n * a typo like `hashchange` for `hashChange` would silently disable a filter\n * forever. Names verified against Chromium's `NavigateEvent.prototype`.\n */\ninterface NavigateEventLike {\n  readonly canIntercept: boolean;\n  readonly hashChange: boolean;\n  readonly downloadRequest: string | null;\n  readonly formData: FormData | null;\n  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';\n  readonly signal: AbortSignal;\n  readonly destination: {readonly url: string};\n  /** Not in every engine yet; used only as a best-effort `rel` check. */\n  readonly sourceElement?: Element | null;\n  intercept(options: InterceptOptions & {handler?: () => Promise<void>}): void;\n}\n\n/** The subset of `NavigationInterceptOptions` this router forwards. */\nexport interface InterceptOptions {\n  focusReset?: 'after-transition' | 'manual';\n  scroll?: 'after-transition' | 'manual';\n}\n\ninterface NavigationLike {\n  addEventListener(\n    type: 'navigate',\n    listener: (e: NavigateEventLike) => void\n  ): void;\n  removeEventListener(\n    type: 'navigate',\n    listener: (e: NavigateEventLike) => void\n  ): void;\n}\n\nconst getNavigation = (): NavigationLike | undefined =>\n  (window as unknown as {navigation?: NavigationLike}).navigation;\n\n/**\n * The current location as a path string, in the form `goto()` parses.\n *\n * Only the origin is dropped: this router matches within one origin, and\n * `_onNavigate` declines anything else before it gets here.\n */\nconst currentPath = (): string =>\n  window.location.pathname + window.location.search + window.location.hash;\n\n/**\n * True when the Navigation API is available — Baseline Newly Available since\n * January 2026 (Chrome/Edge, Safari 26.2, Firefox 147).\n *\n * This router **requires** it. Exported so an app can detect an unsupported\n * engine at boot and say so, rather than leaving the user to notice that every\n * link reloads the page.\n */\nexport const supportsNavigationApi = (): boolean =>\n  typeof window !== 'undefined' &&\n  typeof getNavigation()?.addEventListener === 'function';\n\n/**\n * A root-level router that intercepts navigation via the Navigation API.\n *\n * This class extends Routes so that it can also have a route configuration.\n *\n * There should only be one Router instance on a page, since the Router\n * installs a global listener. Nested routes should be configured with the\n * `Routes` class.\n *\n * ## Why the Navigation API\n *\n * Upstream intercepted navigation with a global click listener plus `popstate`\n * and committed with `history.pushState()`. That is structurally racy:\n * `pushState` is synchronous and `popstate` fires *after* the URL has already\n * moved, but `goto()` awaits `route.enter()` before swapping the outlet. The\n * URL leads and the outlet lags, leaving two sources of truth — the outgoing\n * route re-renders with stale params, and two quick navigations commit in\n * whatever order their `enter()` hooks happen to resolve.\n *\n * `navigateEvent.intercept({handler})` collapses that. The browser commits the\n * URL and holds the navigation un-finished while the handler runs, and it\n * aborts `navigateEvent.signal` when a newer navigation supersedes this one —\n * which `goto()` honours, so a superseded route can no longer win the outlet.\n *\n * ## No legacy fallback\n *\n * An earlier version of this fork kept upstream's click/popstate path for\n * pre-2026 engines. It was removed deliberately. Ten review rounds found\n * divergences between the two paths and **every one was in the click handler**,\n * never in this one — which is structural, not luck: this handler reads a\n * decision the browser has already made, while the click handler had to\n * re-derive it, re-implementing the rules for choosing a navigable, the\n * fragment-navigation predicate, and the modifier-key rules. Each round found\n * another place where the re-implementation and the spec disagreed.\n *\n * On an engine without the API, links fall back to ordinary full page loads.\n * For an app whose server serves the shell on every route that still works —\n * it is slower, not broken — and `supportsNavigationApi()` lets you detect it.\n * If real pre-2026 support is ever needed, use a Navigation API polyfill: one\n * decision path, with compatibility isolated in a layer whose whole job is\n * spec accuracy.\n */\nexport class Router extends Routes {\n  /**\n   * Options forwarded to `navigateEvent.intercept()`. Leaving these unset\n   * gives the browser's default scroll and focus handling.\n   */\n  interceptOptions?: InterceptOptions;\n\n  private _listening = false;\n\n  override hostConnected() {\n    super.hostConnected();\n    // Gated on the exported predicate, not on `navigation !== undefined`:\n    // a stub or partial polyfill under that name would otherwise make this\n    // branch throw out of connectedCallback while `supportsNavigationApi()`\n    // told the app it was unsupported — and then even the initial render below\n    // would not run.\n    if (supportsNavigationApi()) {\n      getNavigation()!.addEventListener('navigate', this._onNavigate);\n      this._listening = true;\n    }\n    // Kick off routed rendering by going to the current URL. Done even without\n    // the API: a full page load still renders the right route, which is what\n    // makes the unsupported-engine degradation \"slow\" rather than \"blank\".\n    // Surfaced rather than left as a bare unhandled rejection, matching the\n    // convention in routes.ts: on an engine without the API this is the *only*\n    // rendering path, and a deep link with no matching route throws here.\n    void this.goto(currentPath()).catch((err) => {\n      queueMicrotask(() => {\n        throw err;\n      });\n    });\n  }\n\n  override hostDisconnected() {\n    super.hostDisconnected();\n    if (this._listening) {\n      getNavigation()?.removeEventListener('navigate', this._onNavigate);\n      this._listening = false;\n    }\n  }\n\n  /**\n   * Handles same-document navigation from every source at once: anchor clicks,\n   * `navigation.navigate()`, `history.pushState()`, and back/forward.\n   */\n  private _onNavigate = (e: NavigateEventLike) => {\n    // Not ours to handle: anything the browser says cannot be intercepted,\n    // downloads, and POST form submissions.\n    //\n    // `!= null`, not `!== null`: the spec types both as nullable-but-present,\n    // but a polyfill that leaves either unset would make a strict check true\n    // for every ordinary link and silently decline the whole app.\n    if (!e.canIntercept || e.downloadRequest != null || e.formData != null) {\n      return;\n    }\n\n    // Fragment-only moves belong to the browser unless a route actually reads\n    // the fragment. Intercepting them unconditionally would cost every\n    // pathname-only app its native in-page scrolling — and re-render the same\n    // route to no effect — while declining them unconditionally is the\n    // lit/lit#3517 bug this router inherited.\n    if (e.hashChange && !this._constrainsHash()) {\n      return;\n    }\n\n    // Reloads must stay reloads. `canIntercept` is true for them, so without\n    // this `location.reload()` silently degrades to re-running goto() on the\n    // same path — the document is never replaced, breaking the standard\n    // \"new version available, reload\" escape hatch. (It would also disagree\n    // with the browser's own refresh button, which is not interceptable.)\n    if (e.navigationType === 'reload') {\n      return;\n    }\n\n    // `rel=\"external\"` is a convention this router honours — it is not defined\n    // by HTML or by the Navigation API, so the browser will not decline these\n    // for us. Best-effort: `sourceElement` is not in every engine, and is\n    // absent for programmatic navigation.\n    if (e.sourceElement?.getAttribute?.('rel') === 'external') {\n      return;\n    }\n\n    // Read per navigation rather than cached at module scope: the value cannot\n    // change, but reading it on import makes merely importing this module throw\n    // where there is no `location` (SSR, a bundler evaluating for tree-shaking\n    // under the package's `sideEffects: false` claim).\n    const url = new URL(e.destination.url);\n    if (url.origin !== window.location.origin) {\n      return;\n    }\n\n    // Only intercept what we can actually render. `canIntercept` is true for\n    // any same-origin URL, including cross-document ones — so without this a\n    // link to a server-rendered page, an export endpoint, or a GET form\n    // (whose `formData` is null) gets swallowed: the URL commits, goto()\n    // throws \"No route found\", and the address bar is left pointing somewhere\n    // the outlet never went. Declining lets the browser do the real\n    // navigation, which is the correct outcome.\n    const path = url.pathname + url.search + url.hash;\n    if (!this.hasRouteFor(path)) {\n      return;\n    }\n\n    e.intercept({\n      ...this.interceptOptions,\n      handler: async () => {\n        // `e.signal` aborts if another navigation starts before this handler\n        // resolves; goto() checks it after `enter()` and stands down.\n        await this.goto(path, {signal: e.signal});\n      },\n    });\n  };\n}\n"]}
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2021 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n *\n * Modifications Copyright 2026 VanLandingham Labs, same license.\n * Rebuilt on the Navigation API; see NOTICE.md.\n */\n\nimport {Routes} from './routes.js';\n\n/**\n * The slice of `NavigateEvent` this router reads. Typed rather than `any`\n * because these properties are the correctness boundary: `hashchange` for\n * `hashChange` would silently disable a filter forever.\n */\ninterface NavigateEventLike {\n  readonly canIntercept: boolean;\n  readonly hashChange: boolean;\n  readonly downloadRequest: string | null;\n  readonly formData: FormData | null;\n  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';\n  readonly signal: AbortSignal;\n  readonly destination: {readonly url: string};\n  /** Not in every engine yet; used only as a best-effort `rel` check. */\n  readonly sourceElement?: Element | null;\n  intercept(options: InterceptOptions & {handler?: () => Promise<void>}): void;\n}\n\n/** The subset of `NavigationInterceptOptions` this router forwards. */\nexport interface InterceptOptions {\n  focusReset?: 'after-transition' | 'manual';\n  scroll?: 'after-transition' | 'manual';\n}\n\ninterface NavigationLike {\n  addEventListener(\n    type: 'navigate',\n    listener: (e: NavigateEventLike) => void\n  ): void;\n  removeEventListener(\n    type: 'navigate',\n    listener: (e: NavigateEventLike) => void\n  ): void;\n}\n\nconst getNavigation = (): NavigationLike | undefined =>\n  (window as unknown as {navigation?: NavigationLike}).navigation;\n\n/** The current location in the form `goto()` parses, minus the origin. */\nconst currentPath = (): string =>\n  window.location.pathname + window.location.search + window.location.hash;\n\n/**\n * True when the Navigation API is available (Baseline Newly Available, January\n * 2026). This router requires it; exported so an app can detect an unsupported\n * engine at boot rather than leaving users to notice every link reloading.\n */\nexport const supportsNavigationApi = (): boolean =>\n  typeof window !== 'undefined' &&\n  typeof getNavigation()?.addEventListener === 'function';\n\n/**\n * A root-level router that intercepts navigation via the Navigation API. Use one\n * per page, since it installs a global listener, and `Routes` for nested spaces.\n *\n * Upstream committed with `history.pushState()` and reacted to `popstate`, but\n * swapped the outlet only after awaiting `enter()`. The URL led and the outlet\n * lagged, so the outgoing route re-rendered with stale params and quick\n * navigations committed out of order. `intercept({handler})` collapses that:\n * the browser holds the navigation unfinished while the handler runs and aborts\n * `signal` when a newer one supersedes it.\n *\n * There is no legacy fallback for pre-2026 engines. Without the API links\n * become full page loads, which `supportsNavigationApi()` detects. See the\n * README for what that degrades and what it breaks.\n */\nexport class Router extends Routes {\n  /** Forwarded to `navigateEvent.intercept()`. Unset uses browser defaults. */\n  interceptOptions?: InterceptOptions;\n\n  private _listening = false;\n\n  override hostConnected() {\n    super.hostConnected();\n    // The predicate, not `navigation !== undefined`: a partial polyfill would\n    // otherwise throw out of connectedCallback and skip the render below.\n    if (supportsNavigationApi()) {\n      getNavigation()!.addEventListener('navigate', this._onNavigate);\n      this._listening = true;\n    }\n    // Runs even without the API, which is what makes the degradation slow\n    // rather than blank. Surfaced because it is then the only rendering path.\n    void this.goto(currentPath()).catch((err) => {\n      queueMicrotask(() => {\n        throw err;\n      });\n    });\n  }\n\n  override hostDisconnected() {\n    super.hostDisconnected();\n    if (this._listening) {\n      getNavigation()?.removeEventListener('navigate', this._onNavigate);\n      this._listening = false;\n    }\n  }\n\n  /**\n   * Handles same-document navigation from every source at once: anchor clicks,\n   * `navigation.navigate()`, `history.pushState()`, and back/forward.\n   */\n  private _onNavigate = (e: NavigateEventLike) => {\n    // `!= null`: a polyfill leaving either unset would make a strict check\n    // true for every link and silently decline the whole app.\n    if (!e.canIntercept || e.downloadRequest != null || e.formData != null) {\n      return;\n    }\n\n    // Fragment-only moves are the browser's unless a route reads the fragment.\n    // Always intercepting costs native scrolling; never intercepting is\n    // lit/lit#3517. See #13.\n    if (e.hashChange && !this._constrainsHash()) {\n      return;\n    }\n\n    // Reloads must stay reloads. `canIntercept` is true for them, so without\n    // this `location.reload()` never replaces the document.\n    if (e.navigationType === 'reload') {\n      return;\n    }\n\n    // This router's convention, not HTML's, so the browser will not decline\n    // these for us. Best-effort: `sourceElement` is not everywhere.\n    if (e.sourceElement?.getAttribute?.('rel') === 'external') {\n      return;\n    }\n\n    // Per navigation, not module scope: reading `location` on import throws\n    // under SSR, contradicting the package's `sideEffects: false`.\n    const url = new URL(e.destination.url);\n    if (url.origin !== window.location.origin) {\n      return;\n    }\n\n    // `canIntercept` is true for cross-document same-origin URLs too, so\n    // without this a server-rendered page or GET form gets swallowed: the URL\n    // commits, goto() throws, and the outlet never moves.\n    const path = url.pathname + url.search + url.hash;\n    if (!this.hasRouteFor(path)) {\n      return;\n    }\n\n    e.intercept({\n      ...this.interceptOptions,\n      handler: async () => {\n        // `e.signal` aborts if a newer navigation starts; goto() checks it.\n        await this.goto(path, {signal: e.signal});\n      },\n    });\n  };\n}\n"]}