lit-navigation-router 0.2.0

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+export * from './routes.js';
+export {Router, supportsNavigationApi} from './router.js';
+export type {InterceptOptions} from './router.js';

package/src/router.ts

@@ -0,0 +1,205 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Modifications Copyright 2026 VanLandingham Labs, same license.
+ * Rebuilt on the Navigation API; see NOTICE.md.
+ */
+
+import {Routes} from './routes.js';
+
+// We cache the origin since it can't change
+const origin = location.origin || location.protocol + '//' + location.host;
+
+/**
+ * The slice of `NavigateEvent` this router reads. Declared locally rather than
+ * typing the handler `any`: these properties *are* the correctness boundary, so
+ * a typo like `hashchange` for `hashChange` would silently disable a filter
+ * forever. Names verified against Chromium's `NavigateEvent.prototype`.
+ */
+interface NavigateEventLike {
+  readonly canIntercept: boolean;
+  readonly hashChange: boolean;
+  readonly downloadRequest: string | null;
+  readonly formData: FormData | null;
+  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+  readonly signal: AbortSignal;
+  readonly destination: {readonly url: string};
+  /** Not in every engine yet; used only as a best-effort `rel` check. */
+  readonly sourceElement?: Element | null;
+  intercept(options: InterceptOptions & {handler?: () => Promise<void>}): void;
+}
+
+/** The subset of `NavigationInterceptOptions` this router forwards. */
+export interface InterceptOptions {
+  focusReset?: 'after-transition' | 'manual';
+  scroll?: 'after-transition' | 'manual';
+}
+
+interface NavigationLike {
+  addEventListener(
+    type: 'navigate',
+    listener: (e: NavigateEventLike) => void
+  ): void;
+  removeEventListener(
+    type: 'navigate',
+    listener: (e: NavigateEventLike) => void
+  ): void;
+}
+
+const getNavigation = (): NavigationLike | undefined =>
+  (window as unknown as {navigation?: NavigationLike}).navigation;
+
+/**
+ * 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.
+ */
+export const supportsNavigationApi = (): boolean =>
+  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.
+ *
+ * ## 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.
+ */
+export class Router extends Routes {
+  /**
+   * Options forwarded to `navigateEvent.intercept()`. Leaving these unset
+   * gives the browser's default scroll and focus handling.
+   */
+  interceptOptions?: InterceptOptions;
+
+  private _listening = false;
+
+  override 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.
+    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.
+    void this.goto(window.location.pathname).catch((err) => {
+      queueMicrotask(() => {
+        throw err;
+      });
+    });
+  }
+
+  override hostDisconnected() {
+    super.hostDisconnected();
+    if (this._listening) {
+      getNavigation()?.removeEventListener('navigate', this._onNavigate);
+      this._listening = false;
+    }
+  }
+
+  /**
+   * Handles same-document navigation from every source at once: anchor clicks,
+   * `navigation.navigate()`, `history.pushState()`, and back/forward.
+   */
+  private _onNavigate = (e: NavigateEventLike) => {
+    // Not ours to handle: anything the browser says cannot be intercepted,
+    // fragment-only moves, downloads, and POST form submissions.
+    if (!e.canIntercept || e.hashChange || e.downloadRequest !== null) {
+      return;
+    }
+    if (e.formData) {
+      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.)
+    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.
+    if (e.sourceElement?.getAttribute?.('rel') === 'external') {
+      return;
+    }
+
+    const url = new URL(e.destination.url);
+    if (url.origin !== 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.
+    if (!this.hasRouteFor(url.pathname)) {
+      return;
+    }
+
+    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.
+        await this.goto(url.pathname, {signal: e.signal});
+      },
+    });
+  };
+}

package/src/routes.ts

@@ -0,0 +1,471 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Modifications Copyright 2026 VanLandingham Labs, same license. See NOTICE.md.
+ */
+
+/// <reference types="urlpattern-polyfill" />
+
+import type {ReactiveController, ReactiveControllerHost} from 'lit';
+
+export interface BaseRouteConfig {
+  name?: string | undefined;
+  render?: (params: {[key: string]: string | undefined}) => unknown;
+  enter?: (params: {
+    [key: string]: string | undefined;
+  }) => Promise<boolean> | boolean;
+}
+
+/**
+ * A RouteConfig that matches against a `path` string. `path` must be a
+ * [`URLPattern` compatible pathname pattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/pathname).
+ */
+export interface PathRouteConfig extends BaseRouteConfig {
+  path: string;
+}
+
+/**
+ * A RouteConfig that matches against a given [`URLPattern`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern)
+ *
+ * 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`.
+ */
+export interface URLPatternRouteConfig extends BaseRouteConfig {
+  pattern: URLPatternLike;
+}
+
+/**
+ * The part of `URLPattern` this router uses.
+ *
+ * Declared structurally rather than referencing the global so the emitted
+ * `.d.ts` is self-contained: the `/// <reference types="urlpattern-polyfill" />`
+ * above is not carried into declaration output, and `URLPattern` is not in
+ * TypeScript's bundled `lib.dom`, so a published package typed against the
+ * global fails a consumer build with `TS2304: Cannot find name 'URLPattern'`.
+ * A real `URLPattern` satisfies this, so passing one still type-checks.
+ */
+export interface URLPatternLike {
+  test(input: {pathname: string}): boolean;
+  exec(input: {pathname: string}): {
+    pathname: {groups: {[key: string]: string | undefined}};
+  } | null;
+}
+
+/**
+ * A description of a route, which path or pattern to match against, and a
+ * render() callback used to render a match to the outlet.
+ */
+export type RouteConfig = PathRouteConfig | URLPatternRouteConfig;
+
+// A cache of URLPatterns created for PathRouteConfig.
+// Rather than converting all given RoutConfigs to URLPatternRouteConfig, this
+// lets us make `routes` mutable so users can add new PathRouteConfigs
+// dynamically.
+const patternCache = new WeakMap<PathRouteConfig, URLPatternLike>();
+
+const isPatternConfig = (route: RouteConfig): route is URLPatternRouteConfig =>
+  (route as URLPatternRouteConfig).pattern !== undefined;
+
+const getPattern = (route: RouteConfig): URLPatternLike => {
+  if (isPatternConfig(route)) {
+    return route.pattern;
+  }
+  let pattern = patternCache.get(route);
+  if (pattern === undefined) {
+    patternCache.set(route, (pattern = new URLPattern({pathname: route.path})));
+  }
+  return pattern;
+};
+
+/**
+ * A reactive controller that performs location-based routing using a
+ * configuration of URL patterns and associated render callbacks.
+ */
+export class Routes implements ReactiveController {
+  private readonly _host: ReactiveControllerHost & HTMLElement;
+
+  /*
+   * The currently installed set of routes in precedence order.
+   *
+   * This array is mutable. To dynamically add a new route you can write:
+   *
+   * ```ts
+   * this._routes.routes.push({
+   *   path: '/foo',
+   *   render: () => html`<p>Foo</p>`,
+   * });
+   * ```
+   *
+   * Mutating this property does not trigger any route transitions. If the
+   * changes may result is a different route matching for the current path, you
+   * must instigate a route update with `goto()`.
+   */
+  routes: Array<RouteConfig> = [];
+
+  /**
+   * A default fallback route which will always be matched if none of the
+   * {@link routes} match. Implicitly matches to the path "/*".
+   */
+  fallback?: BaseRouteConfig;
+
+  /*
+   * The current set of child Routes controllers. These are connected via
+   * the routes-connected event.
+   */
+  private readonly _childRoutes: Array<Routes> = [];
+
+  private _parentRoutes: Routes | undefined;
+
+  /*
+   * State related to the current matching route.
+   *
+   * We keep this so that consuming code can access current parameters, and so
+   * that we can propagate tail matches to child routes if they are added after
+   * navigation / matching.
+   */
+  /** Monotonic goto counter; see the last-goto-wins note in goto(). */
+  private _gotoSeq = 0;
+
+  private _currentPathname: string | undefined;
+  private _currentRoute: RouteConfig | undefined;
+  private _currentParams: {
+    [key: string]: string | undefined;
+  } = {};
+
+  /**
+   * Callback to call when this controller is disconnected.
+   *
+   * It's critical to call this immediately in hostDisconnected so that this
+   * controller instance doesn't receive a tail match meant for another route.
+   */
+  // TODO (justinfagnani): Do we need this now that we have a direct reference
+  // to the parent? We can call `this._parentRoutes.disconnect(this)`.
+  private _onDisconnect: (() => void) | undefined;
+
+  constructor(
+    host: ReactiveControllerHost & HTMLElement,
+    routes: Array<RouteConfig>,
+    options?: {fallback?: BaseRouteConfig}
+  ) {
+    (this._host = host).addController(this);
+    this.routes = [...routes];
+    this.fallback = options?.fallback;
+  }
+
+  /**
+   * Returns a URL string of the current route, including parent routes,
+   * optionally replacing the local path with `pathname`.
+   */
+  link(pathname?: string): string {
+    if (pathname?.startsWith('/')) {
+      return pathname;
+    }
+    if (pathname?.startsWith('.')) {
+      throw new Error('Not implemented');
+    }
+    pathname ??= this._currentPathname;
+    return (this._parentRoutes?.link() ?? '') + pathname;
+  }
+
+  /**
+   * Navigates this routes controller to `pathname`.
+   *
+   * This does not navigate parent routes, so it isn't (yet) a general page
+   * navigation API. It does navigate child routes if pathname matches a
+   * pattern with a tail wildcard pattern (`/*`).
+   *
+   * Pass `options.signal` to make the navigation abandonable. `enter()` is
+   * awaited, so a second `goto()` can start — and finish — while the first is
+   * still resolving its route; without a signal the slower one commits last
+   * 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}) {
+    // 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 signal = options?.signal;
+    // 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
+    // navigation has already finished, and therefore with a signal that will
+    // never abort. Without this counter a slow first child load commits over a
+    // 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;
+    const superseded = () => signal?.aborted === true || seq !== this._gotoSeq;
+    let tailGroup: 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;
+      this._currentPathname = '';
+      // Simulate a tail group with the whole pathname
+      this._currentParams = {0: tailGroup};
+    } else {
+      const route = this._getRoute(pathname);
+      if (route === undefined) {
+        throw new Error(`No route found for ${pathname}`);
+      }
+      const pattern = getPattern(route);
+      const result = pattern.exec({pathname});
+      const params = result?.pathname.groups ?? {};
+      tailGroup = getTailGroup(params);
+      if (typeof route.enter === 'function') {
+        const success = await route.enter(params);
+        // If enter() returns false, cancel this navigation
+        if (success === false) {
+          return;
+        }
+      }
+      // A newer navigation superseded this one while `enter` was awaiting.
+      // Committing now would swap the outlet onto a route the URL has left.
+      if (superseded()) {
+        return;
+      }
+      // Only update route state if the enter handler completes successfully
+      this._currentRoute = route;
+      this._currentParams = params;
+      this._currentPathname =
+        tailGroup === undefined
+          ? pathname
+          : pathname.substring(0, pathname.length - tailGroup.length);
+    }
+
+    // Propagate the tail match to children — deliberately NOT awaited.
+    //
+    // Awaiting looks like it would make `navigation.finished` cover the whole
+    // tree, and an earlier revision of this fork did it. It is wrong twice
+    // over. At this point `requestUpdate()` has not run, so `_childRoutes`
+    // still holds the *outgoing* branch's controller: awaiting it gates the
+    // parent's outlet swap on an `enter()` for a tail that controller will
+    // never render (a hung one blocks the navigation forever), and if that
+    // child has no route for the new tail its `No route found` throw
+    // propagates out of here and `requestUpdate()` below never runs — URL
+    // 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. Errors are swallowed rather than left as unhandled rejections.
+    if (tailGroup !== undefined) {
+      for (const childRoutes of this._childRoutes) {
+        // No signal, for the same reason as the late-mount path below: the
+        // parent commits before children run, so a child handed an aborted
+        // signal stands down with no newer goto() arriving to correct it,
+        // leaving the nested outlet stuck. A hash-only navigation aborts the
+        // outstanding one without producing a replacement, so this is
+        // reachable. Supersession is the counter's job.
+        //
+        // The expected failure here is a child with no route for the new tail
+        // — the outgoing branch, mid-swap. Filter that structurally rather
+        // than swallowing everything, so a genuine `enter()` rejection still
+        // surfaces the way it does upstream instead of vanishing.
+        if (!childRoutes.hasRouteFor(tailGroup)) {
+          // Skip the navigation but still supersede: `goto()` is where the
+          // counter is bumped, so returning early here would leave an
+          // in-flight child navigation current, free to commit over a URL that
+          // has moved on. Removing the abort signal above is only safe because
+          // the counter always runs — including here.
+          childRoutes._supersede();
+          continue;
+        }
+        void childRoutes.goto(tailGroup).catch((err) => {
+          queueMicrotask(() => {
+            throw err;
+          });
+        });
+      }
+    }
+    this._host.requestUpdate();
+  }
+
+  /**
+   * The result of calling the current route's render() callback.
+   */
+  outlet() {
+    return this._currentRoute?.render?.(this._currentParams);
+  }
+
+  /**
+   * The current parsed route parameters.
+   */
+  get params() {
+    return this._currentParams;
+  }
+
+  /**
+   * Invalidate any in-flight `goto()` on this controller without starting a
+   * new one. Same-class access, so `_gotoSeq` stays private to `Routes`.
+   */
+  private _supersede(seen: Set<Routes> = new Set()): void {
+    // Unreachable defence in depth. Upstream *can* produce a `_childRoutes`
+    // cycle — a host carrying two Routes controllers, disconnected and
+    // reconnected, ends up with each registered as the other's child — but
+    // `hostDisconnected` below removes the listener that causes it, and a test
+    // asserts the cycle cannot form. Kept because an unguarded recursive walk
+    // over a cycle is a stack overflow rather than a misrender.
+    if (seen.has(this)) {
+      return;
+    }
+    seen.add(this);
+    this._gotoSeq++;
+    // Recursive: on the navigating branch the child's own propagation loop
+    // reaches the grandchildren, but a skipped child never runs one — so
+    // without this an in-flight grandchild `enter()` stays current and commits
+    // over a URL that has moved on, the same defect one level deeper.
+    for (const child of this._childRoutes) {
+      child._supersede(seen);
+    }
+  }
+
+  /**
+   * True when this controller can render `pathname` — i.e. a route matches, or
+   * a fallback is configured.
+   *
+   * `Router` gates interception on this: intercepting a path we cannot render
+   * commits the URL and then throws out of `goto()`, leaving the address bar
+   * 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 {
+    // Mirrors goto()'s special case: a controller with no routes of its own
+    // behaves as if it had a single `/*` route.
+    if (this.routes.length === 0 && this.fallback === undefined) {
+      return true;
+    }
+    return this._getRoute(pathname) !== undefined;
+  }
+
+  /**
+   * Matches `url` against the installed routes and returns the first match.
+   */
+  private _getRoute(pathname: string): RouteConfig | undefined {
+    const matchedRoute = this.routes.find((r) =>
+      getPattern(r).test({pathname: pathname})
+    );
+    if (matchedRoute || this.fallback === undefined) {
+      return matchedRoute;
+    }
+    if (this.fallback) {
+      // 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.
+      return {...this.fallback, path: '/*'};
+    }
+    return undefined;
+  }
+
+  hostConnected() {
+    this._host.addEventListener(
+      RoutesConnectedEvent.eventName,
+      this._onRoutesConnected
+    );
+    const event = new RoutesConnectedEvent(this);
+    this._host.dispatchEvent(event);
+    this._onDisconnect = event.onDisconnect;
+  }
+
+  hostDisconnected() {
+    // Remove the listener hostConnected added. Without this a host that is
+    // disconnected and reconnected (a repeat() reorder, a tab swap) leaves the
+    // sibling controller's listener installed, so on the second connect it
+    // claims the re-dispatching controller as *its* child and the pair point
+    // at each other — a real `_childRoutes` cycle, which recursive walks turn
+    // into a stack overflow.
+    this._host.removeEventListener(
+      RoutesConnectedEvent.eventName,
+      this._onRoutesConnected
+    );
+    // When this child routes controller is disconnected because a parent
+    // outlet rendered a different template, disconnecting will ensure that
+    // this controller doesn't receive a tail match meant for another route.
+    this._onDisconnect?.();
+    this._parentRoutes = undefined;
+  }
+
+  private _onRoutesConnected = (e: RoutesConnectedEvent) => {
+    // Don't handle the event fired by this routes controller, which we get
+    // because we do this.dispatchEvent(...)
+    if (e.routes === this) {
+      return;
+    }
+
+    const childRoutes = e.routes;
+    this._childRoutes.push(childRoutes);
+    childRoutes._parentRoutes = this;
+
+    e.stopImmediatePropagation();
+    e.onDisconnect = () => {
+      // Remove route from this._childRoutes:
+      // `>>> 0` converts -1 to 2**32-1
+      this._childRoutes?.splice(
+        this._childRoutes.indexOf(childRoutes) >>> 0,
+        1
+      );
+    };
+
+    const tailGroup = getTailGroup(this._currentParams);
+    // Same structural filter as the propagation path in goto(): a child that
+    // mounts under a tail it cannot render is the expected case (a deep link
+    // to `/x/unknown`), not an error. Without this the two call sites disagree
+    // — silent there, uncaught global throw here — for identical input.
+    if (tailGroup !== undefined && childRoutes.hasRouteFor(tailGroup)) {
+      // No signal here on purpose. The parent commits its own state before
+      // children run, so by the time a late child mounts the navigation may
+      // already have been aborted — handing it that signal makes it stand down
+      // with no newer goto() ever arriving to correct it, leaving the nested
+      // outlet blank permanently. The goto counter covers what matters
+      // (supersession by a newer goto).
+      void childRoutes.goto(tailGroup).catch((err) => {
+        queueMicrotask(() => {
+          throw err;
+        });
+      });
+    }
+  };
+}
+
+/**
+ * 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 tailKey: string | undefined;
+  for (const key of Object.keys(groups)) {
+    if (/\d+/.test(key) && (tailKey === undefined || key > tailKey!)) {
+      tailKey = key;
+    }
+  }
+  return tailKey && groups[tailKey];
+};
+
+/**
+ * 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.
+ */
+export class RoutesConnectedEvent extends Event {
+  static readonly eventName = 'lit-routes-connected';
+  readonly routes: Routes;
+  onDisconnect?: () => void;
+
+  constructor(routes: Routes) {
+    super(RoutesConnectedEvent.eventName, {
+      bubbles: true,
+      composed: true,
+      cancelable: false,
+    });
+    this.routes = routes;
+  }
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    [RoutesConnectedEvent.eventName]: RoutesConnectedEvent;
+  }
+}