lit-navigation-router 0.3.0 → 0.5.0

package/src/routes.ts

@@ -31,8 +31,8 @@ export interface PathRouteConfig extends BaseRouteConfig {
  *
  * While `URLPattern` can match against protocols, hostnames, and ports,
  * routes will only be checked for matches if they're part of the current
- * origin. This means that the pattern is limited to checking `pathname` and
- * `search`.
+ * origin. This means the pattern is limited to checking `pathname`, `search`
+ * and `hash`.
  */
 export interface URLPatternRouteConfig extends BaseRouteConfig {
   pattern: URLPatternLike;
@@ -49,12 +49,68 @@ export interface URLPatternRouteConfig extends BaseRouteConfig {
  * A real `URLPattern` satisfies this, so passing one still type-checks.
  */
 export interface URLPatternLike {
-  test(input: {pathname: string}): boolean;
-  exec(input: {pathname: string}): {
+  /**
+   * The pathname pattern string, as `URLPattern.prototype.pathname` returns
+   * it. Read to tell a trailing wildcard from any other positional group —
+   * the groups object alone cannot (see `tailOf`).
+   */
+  readonly pathname: string;
+  /**
+   * The hash pattern string. `'*'` means the route places no constraint on the
+   * fragment, which is what `URLPattern` fills in for any component the caller
+   * omits. `Router` reads this to decide whether a fragment-only navigation is
+   * its business or the browser's.
+   */
+  readonly hash: string;
+  test(input: RouteLocation): boolean;
+  exec(input: RouteLocation): {
     pathname: {groups: {[key: string]: string | undefined}};
+    search: {groups: {[key: string]: string | undefined}};
+    hash: {groups: {[key: string]: string | undefined}};
   } | null;
 }
 
+/**
+ * The parts of a location this router matches against, split out of a path
+ * string by `parseLocation`.
+ *
+ * `search` and `hash` carry no leading `?` or `#`. `URLPattern` canonicalises
+ * either form away on an init input, but only for a real `URLPattern` — the
+ * structural `URLPatternLike` above admits other implementations, so the
+ * delimiters are stripped here rather than left to the pattern.
+ */
+export interface RouteLocation {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+/**
+ * Splits `path` into the components a pattern is matched against.
+ *
+ * Deliberately not `new URL(path, origin)`: a nested controller's path is a
+ * *tail* — a bare relative segment like `abc` — which `URL` would resolve
+ * against the current directory and mangle.
+ */
+const parseLocation = (path: string): RouteLocation => {
+  const hashIndex = path.indexOf('#');
+  const hash = hashIndex === -1 ? '' : path.slice(hashIndex + 1);
+  const beforeHash = hashIndex === -1 ? path : path.slice(0, hashIndex);
+  const searchIndex = beforeHash.indexOf('?');
+  return {
+    pathname: searchIndex === -1 ? beforeHash : beforeHash.slice(0, searchIndex),
+    search: searchIndex === -1 ? '' : beforeHash.slice(searchIndex + 1),
+    hash,
+  };
+};
+
+/** Re-attaches `search` and `hash` to a pathname. Inverse of `parseLocation`. */
+const formatLocation = (
+  pathname: string,
+  {search, hash}: {search: string; hash: string}
+): string =>
+  pathname + (search === '' ? '' : `?${search}`) + (hash === '' ? '' : `#${hash}`);
+
 /**
  * A description of a route, which path or pattern to match against, and a
  * render() callback used to render a match to the outlet.
@@ -81,13 +137,46 @@ const getPattern = (route: RouteConfig): URLPatternLike => {
   return pattern;
 };
 
-// The implicit "/*" pattern every configured fallback matches against. Built on
-// first use rather than at module scope so that importing this module never
-// touches `URLPattern` — it may be polyfilled after import, or absent entirely.
-let wildcardPattern: URLPatternLike | undefined;
+/**
+ * Matches a pathname pattern that ends in a wildcard, in the forms
+ * `URLPattern.prototype.pathname` regenerates one: a bare `*` — which a
+ * trailing `(.*)` also normalises to — or `{*}`, which the generator emits for
+ * a wildcard after a modified group, e.g. `/docs{/}?*`. Either may be
+ * optional (`*?`). Not a wildcard: an escaped `\*`, or a `*` that is the
+ * modifier on a group (`(\d+)*`, `{/}*`) or on a named param (`:rest*`).
+ * Those exclusions matter when an earlier positional group exists —
+ * `/x/(\d+)/:rest*` — since that group would otherwise be taken for the tail.
+ */
+const TRAILING_WILDCARD = /(?:(?<![\\)}]|:[\w$]+)\*|\{\*\})\??$/;
 
-const getWildcardPattern = (): URLPatternLike =>
-  (wildcardPattern ??= new URLPattern({pathname: '/*'}));
+/**
+ * The tail of a match — what a trailing wildcard (`/foo/*`) captured — or
+ * undefined when the pattern has none.
+ *
+ * Decided from the pattern, not from the groups object: an unnamed regex group
+ * (`/post/(\d+)`) and a wildcard that is not last (`/foo/*` followed by
+ * `/bar`) are keyed by index exactly as a tail is, and reading either as one
+ * truncated `link()` and handed a child the wrong segment. When a trailing
+ * wildcard is present it is the last group in the pattern, so its key is the
+ * highest positional index.
+ */
+const tailOf = (
+  route: RouteConfig,
+  params: {[key: string]: string | undefined}
+): string | undefined => {
+  if (!TRAILING_WILDCARD.test(getPattern(route).pathname)) {
+    return undefined;
+  }
+  let tailIndex = -1;
+  for (const key of Object.keys(params)) {
+    // Numeric, not lexicographic: '9' sorts above '10' as a string, so a
+    // pattern with eleven or more wildcards picked group 9 as its tail.
+    if (/^\d+$/.test(key) && Number(key) > tailIndex) {
+      tailIndex = Number(key);
+    }
+  }
+  return tailIndex < 0 ? undefined : params[String(tailIndex)];
+};
 
 /**
  * A reactive controller that performs location-based routing using a
@@ -116,7 +205,10 @@ export class Routes implements ReactiveController {
 
   /**
    * A default fallback route which will always be matched if none of the
-   * {@link routes} match. Implicitly matches to the path "/*".
+   * {@link routes} match. Behaves like a `/*` route: `params[0]` is the whole
+   * pathname minus its leading slash, and is handed to child controllers as
+   * their tail. A nested controller's own pathname is a tail, with no leading
+   * slash; the fallback accepts that too.
    */
   fallback?: BaseRouteConfig;
 
@@ -139,6 +231,16 @@ export class Routes implements ReactiveController {
   private _gotoSeq = 0;
 
   private _currentPathname: string | undefined;
+  private _currentTail: string | undefined;
+  /**
+   * The search and hash of the current location.
+   *
+   * Ambient rather than tailed: only the pathname nests, so a child controller
+   * is handed the parent's tail as its pathname but the *same* search and
+   * hash. There is no meaningful way to split a fragment across a route tree.
+   */
+  private _currentSearch = '';
+  private _currentHash = '';
   private _currentRoute: RouteConfig | undefined;
   private _currentParams: {
     [key: string]: string | undefined;
@@ -192,13 +294,12 @@ export class Routes implements ReactiveController {
    * and the outlet ends up on a route the URL has already left. `Router`
    * threads `NavigateEvent.signal` through for exactly this reason.
    */
-  async goto(pathname: string, options?: {signal?: AbortSignal}) {
+  async goto(path: string, options?: {signal?: AbortSignal}) {
     // TODO (justinfagnani): handle absolute vs relative paths separately.
 
-    // TODO (justinfagnani): generalize this to handle query params and
-    // fragments. It currently only handles path names because it's easier to
-    // completely disregard the origin for now. The click handler only does
-    // an in-page navigation if the origin matches anyway.
+    const location = parseLocation(path);
+    const {pathname} = location;
+
     // Last-goto-wins, per controller. The navigation signal alone is not
     // enough: a child controller mounts as a *result* of its parent's render,
     // so its first goto() comes from `_onRoutesConnected` — after the parent's
@@ -207,23 +308,23 @@ export class Routes implements ReactiveController {
     // newer one. This also keeps `Routes` correct when used on its own, with
     // no `Router` and no Navigation API in the picture.
     const seq = ++this._gotoSeq;
-    let tailGroup: string | undefined;
+    let tail: string | undefined;
 
     if (this.routes.length === 0 && this.fallback === undefined) {
       // If a routes controller has none of its own routes it acts like it has
       // one route of `/*` so that it passes the whole pathname as a tail
       // match.
-      tailGroup = pathname;
+      tail = pathname;
       this._currentPathname = '';
       // Simulate a tail group with the whole pathname
-      this._currentParams = {0: tailGroup};
+      this._currentParams = {0: tail};
     } else {
-      const match = this._match(pathname);
+      const match = this._match(location);
       if (match === undefined) {
-        throw new Error(`No route found for ${pathname}`);
+        throw new Error(`No route found for ${path}`);
       }
       const {route, params} = match;
-      tailGroup = getTailGroup(params);
+      tail = match.tail;
       if (typeof route.enter === 'function') {
         const success = await route.enter(params);
         // If enter() returns false, cancel this navigation
@@ -240,10 +341,13 @@ export class Routes implements ReactiveController {
       this._currentRoute = route;
       this._currentParams = params;
       this._currentPathname =
-        tailGroup === undefined
+        tail === undefined
           ? pathname
-          : pathname.substring(0, pathname.length - tailGroup.length);
+          : pathname.substring(0, pathname.length - tail.length);
     }
+    this._currentTail = tail;
+    this._currentSearch = location.search;
+    this._currentHash = location.hash;
 
     // Propagate the tail match to children — deliberately NOT awaited.
     //
@@ -258,10 +362,13 @@ export class Routes implements ReactiveController {
     // committed, outlet stranded, i.e. this fork's own thesis bug one level
     // down. Nested supersession is handled by the goto counter above, not by
     // awaiting. `_routeChild` covers the per-child filtering and error policy.
-    if (tailGroup !== undefined) {
-      for (const childRoutes of this._childRoutes) {
-        this._routeChild(childRoutes, tailGroup);
-      }
+    //
+    // Runs whether or not there is a tail. A route without one has nothing for
+    // the children to render, but they must still be superseded — otherwise a
+    // child mid-`enter()` for the previous tail stays current and commits over
+    // a URL that has moved on.
+    for (const childRoutes of this._childRoutes) {
+      this._routeChild(childRoutes, tail);
     }
     this._host.requestUpdate();
   }
@@ -291,7 +398,9 @@ export class Routes implements ReactiveController {
    * a genuine `enter()` rejection still surfaces the way it does upstream.
    * Skipping must still supersede: `goto()` is where the counter is bumped, so
    * returning without it would leave an in-flight child navigation current,
-   * free to commit over a URL that has moved on.
+   * free to commit over a URL that has moved on. A parent route with no tail
+   * at all is the same case: nothing to route, but still something to stand
+   * down.
    *
    * No abort signal is threaded through, and the goto is deliberately not
    * awaited. The parent commits its own state before children run, so a child
@@ -300,12 +409,20 @@ export class Routes implements ReactiveController {
    * hash-only navigation aborts the outstanding one without producing a
    * replacement. Supersession is the counter's job.
    */
-  private _routeChild(child: Routes, tail: string) {
-    if (!child.hasRouteFor(tail)) {
+  private _routeChild(child: Routes, tail: string | undefined) {
+    if (tail === undefined) {
+      child._supersede();
+      return;
+    }
+    const childPath = formatLocation(tail, {
+      search: this._currentSearch,
+      hash: this._currentHash,
+    });
+    if (!child.hasRouteFor(childPath)) {
       child._supersede();
       return;
     }
-    void child.goto(tail).catch((err) => {
+    void child.goto(childPath).catch((err) => {
       queueMicrotask(() => {
         throw err;
       });
@@ -338,7 +455,32 @@ export class Routes implements ReactiveController {
   }
 
   /**
-   * True when this controller can render `pathname` — i.e. a route matches, or
+   * True when this controller, or any controller below it, has a route that
+   * constrains the hash.
+   *
+   * `Router` gates interception of fragment-only navigation on this. Left
+   * ungated, a pathname-only app would have every in-page anchor swallowed and
+   * re-rendered instead of scrolled; gated, such an app behaves exactly as it
+   * did before hash routes existed.
+   *
+   * Walks children because a nested controller may route on the hash while the
+   * top-level `Router` does not — and only the top-level one sees the
+   * navigate event.
+   */
+  protected _constrainsHash(seen: Set<Routes> = new Set()): boolean {
+    // Cycle guard, matching `_supersede`; see the note there.
+    if (seen.has(this)) {
+      return false;
+    }
+    seen.add(this);
+    return (
+      this.routes.some((r) => getPattern(r).hash !== '*') ||
+      this._childRoutes.some((c) => c._constrainsHash(seen))
+    );
+  }
+
+  /**
+   * True when this controller can render `path` — i.e. a route matches, or
    * a fallback is configured.
    *
    * `Router` gates interception on this: intercepting a path we cannot render
@@ -346,7 +488,7 @@ export class Routes implements ReactiveController {
    * moved and the outlet stale. Letting the browser handle it instead means a
    * server-rendered page, an export endpoint, or a GET form still works.
    */
-  hasRouteFor(pathname: string): boolean {
+  hasRouteFor(path: string): boolean {
     // A fallback matches everything, and a controller with no routes of its own
     // behaves as if it had a single `/*` route (goto()'s special case). Either
     // way the answer is yes without running a single pattern — worth
@@ -356,7 +498,8 @@ export class Routes implements ReactiveController {
     }
     // `test()`, not `_match()`: this only needs the yes/no, and `exec()` pays
     // ~8x on a hit to build a groups object the caller would throw away.
-    return this.routes.some((r) => getPattern(r).test({pathname}));
+    const location = parseLocation(path);
+    return this.routes.some((r) => getPattern(r).test(location));
   }
 
   /**
@@ -367,28 +510,45 @@ export class Routes implements ReactiveController {
    * extract: that ran the winning pattern twice, and every caller that wants a
    * route wants its params too.
    */
-  private _match(pathname: string):
-    | {route: RouteConfig; params: {[key: string]: string | undefined}}
+  private _match(location: RouteLocation):
+    | {
+        route: RouteConfig;
+        params: {[key: string]: string | undefined};
+        tail: string | undefined;
+      }
     | undefined {
     for (const route of this.routes) {
-      const result = getPattern(route).exec({pathname});
+      const result = getPattern(route).exec(location);
       if (result !== null) {
-        return {route, params: result.pathname.groups};
+        const params: {[key: string]: string | undefined} = {
+          ...result.pathname.groups,
+        };
+        // Named groups only. A positional group is keyed by index in every
+        // component independently, so `/child/*` with a hash of `*` yields a
+        // "0" in both — and `tailOf` picks the tail by highest numeric key.
+        // Merging them would let a fragment masquerade as the tail.
+        for (const groups of [result.search.groups, result.hash.groups]) {
+          for (const [key, value] of Object.entries(groups)) {
+            if (!/^\d+$/.test(key)) {
+              params[key] = value;
+            }
+          }
+        }
+        return {route, params, tail: tailOf(route, result.pathname.groups)};
       }
     }
     if (this.fallback === undefined) {
       return undefined;
     }
     // The fallback route behaves like it has a "/*" path. This is hidden from
-    // the public API but is added here to return a valid RouteConfig. The
-    // pattern is the shared one rather than one derived from this object:
-    // the spread produces a fresh object every call, which `patternCache` —
-    // keyed by identity — would miss, rebuilding a URLPattern per navigation.
-    const wildcard = getWildcardPattern();
-    return {
-      route: {...this.fallback, path: '/*'},
-      params: wildcard.exec({pathname})?.pathname.groups ?? {},
-    };
+    // the public API; the `path` is there to return a valid RouteConfig. The
+    // match itself is done by hand rather than with a real `/*` pattern: a
+    // nested controller is handed its tail *without* a leading slash, which
+    // `/*` does not match, so a nested fallback matched nothing — empty
+    // params, no tail, and its own children never routed.
+    const {pathname} = location;
+    const tail = pathname.startsWith('/') ? pathname.slice(1) : pathname;
+    return {route: {...this.fallback, path: '/*'}, params: {0: tail}, tail};
   }
 
   hostConnected() {
@@ -440,43 +600,12 @@ export class Routes implements ReactiveController {
 
     // A child that mounts under an existing tail match has to be caught up to
     // it — it missed the propagation loop in goto() that ran before it existed.
-    const tailGroup = getTailGroup(this._currentParams);
-    if (tailGroup !== undefined) {
-      this._routeChild(childRoutes, tailGroup);
-    }
+    // With no tail there is nothing to catch up to, and `_routeChild` then only
+    // supersedes, a no-op on a freshly mounted child.
+    this._routeChild(childRoutes, this._currentTail);
   };
 }
 
-/**
- * Returns the tail of a pathname groups object. This is the match from a
- * wildcard at the end of a pathname pattern, like `/foo/*`
- */
-const getTailGroup = (groups: {[key: string]: string | undefined}) => {
-  let tailIndex = -1;
-  for (const key of Object.keys(groups)) {
-    // Anchored. `URLPattern` keys a positional group by its index, so a
-    // non-digit key is never one — an unanchored test also accepts a *named*
-    // group containing a digit (`:id2`), and since a letter sorts above a
-    // digit it then won the comparison below and the param value was handed
-    // to the child instead of the tail.
-    //
-    // Necessary, not sufficient: an unnamed *regex* group is positional too
-    // (`/post/(\d+)` yields key "0"), as is a wildcard that is not last
-    // (`/foo/*/bar`). Both are mis-read as tails here, and both predate this
-    // check — selecting the tail properly needs the pattern, not just groups.
-    if (!/^\d+$/.test(key)) {
-      continue;
-    }
-    // Numeric, not lexicographic: '9' sorts above '10' as a string, so a
-    // pattern with eleven or more wildcards picked group 9 as its tail.
-    const index = Number(key);
-    if (index > tailIndex) {
-      tailIndex = index;
-    }
-  }
-  return tailIndex < 0 ? undefined : groups[String(tailIndex)];
-};
-
 /**
  * This event is fired from Routes controllers when their host is connected to
  * announce the child route and potentially connect to a parent routes controller.