lit-navigation-router 0.5.0 → 0.6.0

package/development/routes.d.ts

@@ -23,39 +23,23 @@ 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)
+ * 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 the pattern is limited to checking `pathname`, `search`
- * and `hash`.
+ * Routes are only checked within the current origin, so only `pathname`,
+ * `search` and `hash` are matched.
  */
 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.
+ * The part of `URLPattern` this router uses. Structural, not a reference to the
+ * global: `URLPattern` is not in TypeScript's `lib.dom`, so typing against it
+ * fails a consumer build with `TS2304`.
  */
 export interface URLPatternLike {
-    /**
-     * 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`).
-     */
+    /** Read by `tailOf`, which the groups object alone cannot answer. */
     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.
-     */
+    /** `'*'` means unconstrained. `Router` gates hash interception on this. */
     readonly hash: string;
     test(input: RouteLocation): boolean;
     exec(input: RouteLocation): {
@@ -77,23 +61,15 @@ export interface URLPatternLike {
     } | 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.
+ * The parts of a location this router matches against. `search` and `hash`
+ * carry no leading `?` or `#`: a real `URLPattern` canonicalises either form
+ * away, but `URLPatternLike` admits implementations that do not.
  */
 export interface RouteLocation {
     pathname: string;
     search: string;
     hash: string;
 }
-/**
- * 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 reactive controller that performs location-based routing using a
@@ -101,13 +77,14 @@ export type RouteConfig = PathRouteConfig | URLPatternRouteConfig;
  */
 export declare class Routes implements ReactiveController {
     private readonly _host;
+    /**
+     * The installed routes, in precedence order. Mutable, but mutating it starts
+     * no route transition; call `goto()` if a different route now matches.
+     */
     routes: Array<RouteConfig>;
     /**
-     * A default fallback route which will always be matched if none of the
-     * {@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.
+     * Matched when no route in {@link routes} does. Behaves like `/*`, so
+     * `params[0]` is the whole pathname minus any leading slash.
      */
     fallback?: BaseRouteConfig;
     private readonly _childRoutes;
@@ -116,23 +93,13 @@ export declare class Routes implements ReactiveController {
     private _gotoSeq;
     private _currentPathname;
     private _currentTail;
-    /**
-     * 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.
-     */
+    /** Ambient, not tailed: only the pathname nests. */
     private _currentSearch;
     private _currentHash;
     private _currentRoute;
     private _currentParams;
-    /**
-     * 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.
-     */
+    /** Must run in hostDisconnected, or this controller can receive another
+     * route's tail match. */
     private _onDisconnect;
     constructor(host: ReactiveControllerHost & HTMLElement, routes: Array<RouteConfig>, options?: {
         fallback?: BaseRouteConfig;
@@ -143,17 +110,30 @@ export declare class Routes implements ReactiveController {
      */
     link(pathname?: string): string;
     /**
-     * Navigates this routes controller to `pathname`.
+     * A URL for the route named `name`, with `params` substituted into its
+     * pattern.
      *
-     * 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 (`/*`).
+     * Lets a component say which route it means instead of where that route
+     * currently lives, so moving a route subtree does not silently break every
+     * hardcoded link inside it.
      *
-     * 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.
+     * Resolution covers the mounted controller tree: this controller, 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 or ambiguous name throws rather than producing a wrong URL.
+     */
+    linkTo(name: string, params?: {
+        [key: string]: string | undefined;
+    }): string;
+    /**
+     * Navigates this controller to `path`, which may carry a search and hash.
+     * Navigates child routes but not parent ones, so it is not yet a general page
+     * navigation API.
+     *
+     * `options.signal` makes the navigation abandonable. `enter()` is awaited, so
+     * a second `goto()` can finish while the first is still resolving; without a
+     * signal the slower one commits last onto a route the URL has left.
      */
     goto(path: string, options?: {
         signal?: AbortSignal;
@@ -169,74 +149,38 @@ export declare class Routes implements ReactiveController {
         [key: string]: string | undefined;
     };
     /**
-     * Hands a tail match to a child controller. Shared by the propagation loop in
-     * `goto()` and the late-mount path in `_onRoutesConnected`, so that identical
-     * input cannot be silent on one and an uncaught global throw on the other.
-     *
-     * A child with no route for the new tail is the expected case, not an error —
-     * the outgoing branch mid-swap, or a deep link to a path the child cannot
-     * render. Filtered structurally rather than by swallowing every rejection, so
-     * 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. A parent route with no tail
-     * at all is the same case: nothing to route, but still something to stand
-     * down.
+     * Hands a tail match to a child. Shared by `goto()`'s propagation loop and the
+     * late-mount path, so identical input behaves identically on both.
      *
-     * 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
-     * handed an already-aborted signal stands down with no newer goto() arriving
-     * to correct it, leaving the nested outlet stuck — reachable, because a
-     * hash-only navigation aborts the outstanding one without producing a
-     * replacement. Supersession is the counter's job.
+     * A child with no route for the tail is expected, not an error: the outgoing
+     * branch mid-swap, or a deep link it cannot render. Filtered structurally so
+     * a genuine `enter()` rejection still surfaces. Skipping must still supersede.
      */
     private _routeChild;
-    /**
-     * Invalidate any in-flight `goto()` on this controller without starting a
-     * new one. Same-class access, so `_gotoSeq` stays private to `Routes`.
-     */
+    /** Invalidate any in-flight `goto()` here without starting a new one. */
     private _supersede;
     /**
-     * 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.
+     * True when this controller or any below it constrains the hash. `Router`
+     * gates fragment-only interception on this, so a pathname-only app keeps
+     * native scrolling. Walks children because only the root sees the event.
      */
     protected _constrainsHash(seen?: Set<Routes>): boolean;
     /**
-     * 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
-     * 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.
+     * True when this controller can render `path`. `Router` gates interception on
+     * this: intercepting what we cannot render commits the URL and then throws,
+     * leaving the address bar moved and the outlet stale.
      */
     hasRouteFor(path: string): boolean;
     /**
-     * Matches `pathname` against the installed routes and returns the first match
-     * with its parsed parameters, or the fallback's match if one is configured.
-     *
-     * One `exec()` per candidate rather than `test()` to select and `exec()` to
-     * extract: that ran the winning pattern twice, and every caller that wants a
-     * route wants its params too.
+     * The first route matching `location`, or the fallback's match. One `exec()`
+     * per candidate; selecting with `test()` first ran the winner twice.
      */
     private _match;
     hostConnected(): void;
     hostDisconnected(): void;
     private _onRoutesConnected;
 }
-/**
- * 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.
- */
+/** Announces a Routes controller to its parent when the host connects. */
 export declare class RoutesConnectedEvent extends Event {
     static readonly eventName = "lit-routes-connected";
     readonly routes: Routes;

package/development/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}