@solidjs/router 2.0.0-next.35 → 2.0.0-next.37

package/dist/index.jsx

@@ -1,6 +1,7 @@
 export * from "./routers/index.js";
 export * from "./lifecycle.js";
 export { useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, usePreloadRoute, useParams, useResolvedPath, useRouteMatches, useSearchParams, RouterContextObj as RouterContext } from "./routing.js";
+export { pendingLinks } from "./pending.js";
 export { mergeSearchString as _mergeSearchString } from "./utils.js";
 export { int } from "./paths.js";
 export { serverRouteComponent } from "./serverRouteComponent.js";

package/dist/paths.d.ts

@@ -82,9 +82,29 @@ type TuplePaths<R extends readonly unknown[], PAcc extends Params> = R extends r
     ...infer T extends readonly unknown[]
 ] ? RouteContrib<H, PAcc> & TuplePaths<T, PAcc> : {};
 type PathLeaf<Sch extends SearchTypes, C, PAcc extends Params> = PathEnd<Sch, Flat<PAcc>> & ChildPaths<C, PAcc>;
-type PathNode<Segs extends readonly string[], F, Sch extends SearchTypes, C, PAcc extends Params> = Segs extends readonly [infer H extends string, ...infer R extends readonly string[]] ? H extends `:${infer N}?` ? ((arg: ParamArg<N, F>) => PathNode<R, F, Sch, C, PAcc & {
+declare const PARAM_NEXT: unique symbol;
+/**
+ * Sibling routes that share a param prefix (`/posts/:id`, `/posts/:id/edit`)
+ * each contribute a call at that node, and a call on an intersection of
+ * function types resolves to its first overload only. So the call reads its
+ * result back through `this` — the whole intersection — where the
+ * continuations of every sibling with the same arity have merged.
+ */
+interface ParamCall<A extends readonly unknown[]> {
+    (...args: A): this extends {
+        readonly [PARAM_NEXT]: {
+            [K in A["length"]]: infer N;
+        };
+    } ? N : never;
+}
+type ParamCallTo<A extends readonly unknown[], N> = ParamCall<A> & {
+    readonly [PARAM_NEXT]: {
+        [K in A["length"]]: N;
+    };
+};
+type PathNode<Segs extends readonly string[], F, Sch extends SearchTypes, C, PAcc extends Params> = Segs extends readonly [infer H extends string, ...infer R extends readonly string[]] ? H extends `:${infer N}?` ? ParamCallTo<[ParamArg<N, F>], PathNode<R, F, Sch, C, PAcc & {
     [K in N]?: string;
-}>) & PathNode<R, F, Sch, C, PAcc & {
+}>> & PathNode<R, F, Sch, C, PAcc & {
     [K in N]?: string;
 }> : H extends `:${string}` | `*${string}` ? ParamCallNode<Segs, F, Sch, C, PAcc> : {
     [K in H]: PathNode<R, F, Sch, C, PAcc>;
@@ -93,7 +113,7 @@ type ParamCallNode<Segs extends readonly string[], F, Sch extends SearchTypes, C
     args: infer A extends readonly unknown[];
     params: infer P2 extends Params;
     rest: infer R2 extends readonly string[];
-} ? ((...args: A) => PathNode<R2, F, Sch, C, PAcc & P2>) & (R2 extends readonly [] ? {
+} ? ParamCallTo<A, PathNode<R2, F, Sch, C, PAcc & P2>> & (R2 extends readonly [] ? {
     (...args: [...A, Sch["input"], string?]): string;
 } : {}) & TypedPath<Flat<PAcc & P2>> : never;
 type RouteContrib<Def, PAcc extends Params> = Def extends {

package/dist/pending.d.ts

@@ -0,0 +1,25 @@
+import type { LinksPlugin, LocationChange, RouterContext } from "./types.js";
+/** Whether a navigation is in flight: one memo per router, under its owner. */
+export declare function routingState(router: RouterContext): () => boolean;
+/**
+ * The target of the in-flight programmatic navigation, if any. A
+ * back/forward traversal (`_navigation` -1) is not a link's target.
+ */
+export declare function pendingTarget(router: RouterContext): LocationChange | undefined;
+/** Whether `to` is the destination of the in-flight navigation. */
+export declare function linkPending(router: RouterContext, to: string | undefined, base: string, end?: boolean): boolean;
+/**
+ * Opt-in `data-pending` for plain anchors. Marks claimed links whose path
+ * covers the in-flight destination of a link click or `navigate()` (not
+ * back/forward), until it lands. Agrees with `useLinkState().pending`, which
+ * works without it. `aria-current` and `data-active` need no plugin.
+ *
+ * @example
+ * ```ts
+ * import { createRouter, pendingLinks } from "@solidjs/router";
+ *
+ * const Router = createRouter({ routes, links: pendingLinks });
+ * // CSS: a[data-pending] { opacity: .6 }
+ * ```
+ */
+export declare const pendingLinks: LinksPlugin;

package/dist/pending.js

@@ -0,0 +1,67 @@
+import { createMemo, DEV, isPending, latest, NotReadyError, runWithOwner } from "solid-js";
+import { matchLink } from "./utils.js";
+/**
+ * Pending navigation state, for the opt-in readers only: `useIsRouting`,
+ * `useLinkState().pending` and the `pendingLinks` claims plugin. `isPending`
+ * and `latest` are UI affordances — the router's own coordination reads its
+ * location writes and their `onSettled` instead — so an app that renders
+ * none of these never bundles Solid's verdict machinery.
+ */
+const routing = new WeakMap();
+/** Whether a navigation is in flight: one memo per router, under its owner. */
+export function routingState(router) {
+    let read = routing.get(router);
+    if (!read) {
+        const { location, matches, _source: source } = router;
+        // `transparent`: created on first use rather than at router setup, so it
+        // must not take a hydration id — the server may never create it, or
+        // create it at a different point.
+        const pending = runWithOwner(router._owner, () => createMemo(() => isPending(() => {
+            try {
+                matches();
+            }
+            catch (e) {
+                if (e instanceof NotReadyError)
+                    throw e;
+            }
+            location.search;
+            location.hash;
+        }), { transparent: true, ...(DEV && { name: "routingPending" }) }));
+        read = () => pending() || isPending(source);
+        routing.set(router, read);
+    }
+    return read;
+}
+/**
+ * The target of the in-flight programmatic navigation, if any. A
+ * back/forward traversal (`_navigation` -1) is not a link's target.
+ */
+export function pendingTarget(router) {
+    if (!routingState(router)())
+        return;
+    const target = latest(router._source);
+    return target._navigation && target._navigation > 0 ? target : undefined;
+}
+/** Whether `to` is the destination of the in-flight navigation. */
+export function linkPending(router, to, base, end) {
+    const target = pendingTarget(router);
+    return !!target && matchLink({ pathname: target.value, search: "" }, to, base, end).active;
+}
+/**
+ * Opt-in `data-pending` for plain anchors. Marks claimed links whose path
+ * covers the in-flight destination of a link click or `navigate()` (not
+ * back/forward), until it lands. Agrees with `useLinkState().pending`, which
+ * works without it. `aria-current` and `data-active` need no plugin.
+ *
+ * @example
+ * ```ts
+ * import { createRouter, pendingLinks } from "@solidjs/router";
+ *
+ * const Router = createRouter({ routes, links: pendingLinks });
+ * // CSS: a[data-pending] { opacity: .6 }
+ * ```
+ */
+export const pendingLinks = (router, base) => ({
+    track: routingState(router),
+    pending: target => linkPending(router, target, base)
+});

package/dist/routers/components.jsx

@@ -1,5 +1,5 @@
 /*@refresh skip*/
-import { createMemo, createRoot, getOwner, onCleanup, runWithOwner, untrack, Show } from "solid-js";
+import { createMemo, createOwner, createRoot, onCleanup, runWithOwner, untrack, Show } from "solid-js";
 import { getRequestEvent, isServer } from "@solidjs/web";
 import { createRouteContext, getIntent, getRouteMatches, resolveLazySubtree, RouteContextObj, setInPreloadFn, unresolvedLazyMatches } from "../routing.js";
 import { serverRouteArgs, serverRouteOf } from "../serverRouteShared.js";
@@ -55,9 +55,12 @@ export function Routes(props) {
     // they stay subscribed to `matches` and crash on a later navigation (#451)
     onCleanup(() => disposers.forEach(dispose => dispose()));
     // Route roots must outlive re-runs of the `routeStates` memo below, so they
-    // are created under the owner of this component rather than the memo's
-    // computation (which disposes its children every time it re-runs).
-    const owner = getOwner();
+    // are created under an owner of this component rather than the memo's
+    // computation (which disposes its children every time it re-runs). A
+    // dedicated one, created before the memo: the roots draw hydration ids from
+    // its counter, so the ids don't depend on whether the memo first parked on
+    // a lazy subtree (the server's render can park where the client's doesn't).
+    const owner = createOwner();
     const routeStates = createMemo((prev) => {
         // While a lazy subtree resolves, `matches()` is not ready and this
         // computation parks with it — no route contexts are created against

package/dist/routers/factory.d.ts

@@ -1,6 +1,6 @@
 import type { JSX } from "@solidjs/web";
 import type { RoutePaths } from "../paths.js";
-import type { DefinedRouteFilters, LazyRouteChildren, OutputMatch, Params, RouteDefinition, RouteInfo, RouteParams, RoutePreloadFunc, RoutePreloadFuncArgs, RouteSectionComponent, RouteSectionProps, StandardSchemaV1, TypedPath, ValidFilters } from "../types.js";
+import type { DefinedRouteFilters, LazyRouteChildren, LinksPlugin, OutputMatch, Params, RouteDefinition, RouteInfo, RouteParams, RoutePreloadFunc, RoutePreloadFuncArgs, RouteSectionComponent, RouteSectionProps, StandardSchemaV1, TypedPath, ValidFilters } from "../types.js";
 import type { RouterHistory } from "./history.js";
 /**
  * Identity helper that preserves literal types when the route tree is
@@ -83,13 +83,28 @@ export interface RouterConfig<R extends readonly RouteDefinition[] = RouteDefini
     singleFlight?: boolean;
     actionBase?: string;
     explicitLinks?: boolean;
+    /**
+     * Link claims plugin. `aria-current` and `data-active` are automatic; pass
+     * `pendingLinks` to also mark links covering the in-flight destination of a
+     * link click or `navigate()` with `data-pending`. Client-only.
+     *
+     * @example
+     * ```ts
+     * import { createRouter, pendingLinks } from "@solidjs/router";
+     *
+     * const Router = createRouter({ routes, links: pendingLinks });
+     * ```
+     */
+    links?: LinksPlugin;
     /** Preload route code/data on link hover and focus. Defaults to `true`. */
     preloadLinks?: boolean;
     /**
      * Explicit scroll restoration for back/forward navigation: positions are
      * saved per history entry and restored once the navigation settles,
      * replacing the browser heuristic that loses offsets when the destination
-     * route forces a layout while rendering. Defaults to `true` with the
+     * route forces a layout while rendering. Reloads of a server-rendered page
+     * are left to the browser's native restoration, which waits for the
+     * streamed document to finish loading. Defaults to `true` with the
      * default browser history; a custom `history` adapter owns its session and
      * must opt in explicitly.
      */

package/dist/routers/factory.jsx

@@ -1,5 +1,5 @@
 /*@refresh skip*/
-import { createSignal, getOwner, onCleanup, onSettled, runWithOwner, untrack } from "solid-js";
+import { createSignal, getOwner, isHydrating, onCleanup, onSettled, runWithOwner, untrack } from "solid-js";
 // standalone imports: `DEV` is undefined in solid's production build and
 // `OBSERVE` outside its observe/dev builds, so app bundlers fold the
 // `DEV &&` diagnostics and the `OBSERVE &&` attribution out of shipped bundles
@@ -118,8 +118,8 @@ function describeInitial(match, location) {
 /** Wraps a history adapter in the integration signal the router core consumes. Must run under a reactive owner. */
 function createIntegration(history, match) {
     let committing = false;
-    // Written, not yet in history (see `RouterIntegration.inflight`).
-    let inflight;
+    // Writes whose transition has landed (see `RouterIntegration.settled`).
+    const settled = new WeakSet();
     const wrap = (value) => (typeof value === "string" ? { value } : value);
     const [read, write] = createSignal(wrap(history.get()), {
         equals: (a, b) => a.value === b.value && a.state === b.state && a._navigation === b._navigation,
@@ -138,15 +138,16 @@ function createIntegration(history, match) {
                 // the no-op rule compares against it, so `navigate()` behind another
                 // write in one handler sees that write rather than the flushed world.
                 write(headed => (written = resolveLocationWrite(headed, next)) || headed);
-                if (written && written._navigation && written._navigation > 0) {
+                if (written && written._navigation) {
                     const next = written;
-                    inflight = next;
                     // Register out of band so a destination error boundary replacing the
-                    // Router subtree cannot suppress the winning history commit.
+                    // Router subtree cannot suppress the winning history commit. The
+                    // settle is tied to the transition carrying the write: it fires when
+                    // that lands, a rejection included, and a superseded write's settle
+                    // fires with the transition that absorbed it.
                     runWithOwner(null, () => onSettled(() => {
-                        if (inflight === next)
-                            inflight = undefined;
-                        if (read() !== next)
+                        settled.add(next);
+                        if (next._navigation < 0 || read() !== next)
                             return;
                         committing = true;
                         try {
@@ -182,7 +183,11 @@ function createIntegration(history, match) {
                 return;
             signal[1]({ ...wrap(value), _navigation: -1 });
         }));
-    return { signal, inflight: () => inflight, utils: history.utils };
+    return {
+        signal,
+        settled: write => settled.has(write),
+        utils: history.utils
+    };
 }
 /**
  * Server default: a static view of the request URL — no signal machinery, a
@@ -246,7 +251,7 @@ export function createRouter(config) {
         let restoration;
         let history = config.history;
         if (!isServer && (config.scrollRestoration ?? !history)) {
-            restoration = createScrollRestoration();
+            restoration = createScrollRestoration(isHydrating());
             history = withScrollRestoration(history || browserHistory(), restoration);
         }
         const integration = isServer
@@ -270,11 +275,15 @@ export function createRouter(config) {
                 actionBase: config.actionBase,
                 transformUrl: config.transformUrl
             })(routerState);
-            setupLinkClaims(routerState, config.explicitLinks);
+            setupLinkClaims(routerState, config.explicitLinks, config.links);
             if (routerState.singleFlight)
                 onCleanup(registerFlightRouter(routerState));
-            restoration && restoration.create(routerState);
+            restoration && restoration.create();
         }
+        // Registered on both sides, outside the client-only branch: an owned
+        // onSettled takes a hydration id on the server too, so the ids line up.
+        // A no-op when the arrival is left to the browser's native restore.
+        onSettled(() => restoration && restoration.settled());
         return (<RouterContextObj value={routerState}>
         <Root routerState={routerState} root={root} preload={config.preload}>
           {(context = getOwner()) && null}

package/dist/routers/scrollRestoration.d.ts

@@ -1,4 +1,3 @@
-import type { RouterContext } from "../types.js";
 import type { RouterHistory } from "./history.js";
 /**
  * Explicit scroll restoration for back/forward navigation. The browser's
@@ -13,7 +12,7 @@ import type { RouterHistory } from "./history.js";
  * so restoration survives reloads, which `scrollRestoration = "manual"`
  * otherwise disables.
  *
- * Restoration is a single scroll once routing settles — the same strategy
+ * Restoration is a single scroll once the traversal settles — the same strategy
  * SvelteKit, TanStack Router and React Router use. Settling after the
  * transition commits is what makes the offset reachable; chasing a still-
  * growing document afterwards (a ResizeObserver re-asserting the offset as
@@ -23,13 +22,38 @@ import type { RouterHistory } from "./history.js";
  * layout changes can feed it back into itself. Content that commits after the
  * transition settles — an image without reserved space, a boundary below the
  * fold — keeps whatever offset the document can hold.
+ *
+ * A server-rendered document load is the exception: the browser restores it
+ * natively once the document — streamed boundaries included — has loaded,
+ * which a restore at the first client flush cannot match. So an entry is
+ * handed back to the browser (`auto`) whenever its document may unload
+ * (pagehide), and a hydrating router arriving on a handed-back entry leaves
+ * the restore to the browser: it does not scroll, and it takes the entry back
+ * (`manual`) only after load or at the first client navigation, whichever
+ * comes first. A programmatic scroll during the load cancels the native
+ * restore in Firefox and WebKit, and WebKit restores just after the load
+ * event, so a `manual` write before then — inside a load listener included —
+ * suppresses it; the write waits a task. Handed-back depths are tracked here
+ * rather than read from `history.scrollRestoration`, which Firefox reports as
+ * the mode before pagehide after a reload. An entry this router pushed and
+ * never handed back stays `manual` and gets no native restore, so the router
+ * restores it as on a client-rendered load.
  */
-export declare function createScrollRestoration(): {
-    /** When the adapter notifies a traversal: mark the target for restoration. */
+export declare function createScrollRestoration(hydrating?: boolean): {
+    /**
+     * When the adapter notifies a traversal: mark the target and restore once
+     * the transition carrying it settles. The adapter notifies right before
+     * the location write, in the same tick, so the settle is that write's —
+     * a same-URL traversal included, which no location key would see.
+     */
     onPop(): void;
+    /** The initial page settled: restore a reload/back_forward arrival. */
+    settled: () => void;
+    /** Before a client navigation writes history: the entry it creates copies the current mode. */
+    beforeWrite: () => void;
     /** After a push: forward entries died, and this depth may be reused. */
     onPush(): void;
-    create(router: RouterContext): void;
+    create(): void;
 };
 export type ScrollRestoration = ReturnType<typeof createScrollRestoration>;
 /**

package/dist/routers/scrollRestoration.js

@@ -1,6 +1,7 @@
-import { createEffect, onCleanup } from "solid-js";
+import { onCleanup, onSettled, runWithOwner } from "solid-js";
 import { bindEvent, saveCurrentDepth } from "./history.js";
 const STORAGE_KEY = "solid-router:scroll";
+const AUTO_KEY = "solid-router:scroll-auto";
 /**
  * Explicit scroll restoration for back/forward navigation. The browser's
  * native same-document heuristic is unreliable for suspense-driven rendering:
@@ -14,7 +15,7 @@ const STORAGE_KEY = "solid-router:scroll";
  * so restoration survives reloads, which `scrollRestoration = "manual"`
  * otherwise disables.
  *
- * Restoration is a single scroll once routing settles — the same strategy
+ * Restoration is a single scroll once the traversal settles — the same strategy
  * SvelteKit, TanStack Router and React Router use. Settling after the
  * transition commits is what makes the offset reachable; chasing a still-
  * growing document afterwards (a ResizeObserver re-asserting the offset as
@@ -24,18 +25,53 @@ const STORAGE_KEY = "solid-router:scroll";
  * layout changes can feed it back into itself. Content that commits after the
  * transition settles — an image without reserved space, a boundary below the
  * fold — keeps whatever offset the document can hold.
+ *
+ * A server-rendered document load is the exception: the browser restores it
+ * natively once the document — streamed boundaries included — has loaded,
+ * which a restore at the first client flush cannot match. So an entry is
+ * handed back to the browser (`auto`) whenever its document may unload
+ * (pagehide), and a hydrating router arriving on a handed-back entry leaves
+ * the restore to the browser: it does not scroll, and it takes the entry back
+ * (`manual`) only after load or at the first client navigation, whichever
+ * comes first. A programmatic scroll during the load cancels the native
+ * restore in Firefox and WebKit, and WebKit restores just after the load
+ * event, so a `manual` write before then — inside a load listener included —
+ * suppresses it; the write waits a task. Handed-back depths are tracked here
+ * rather than read from `history.scrollRestoration`, which Firefox reports as
+ * the mode before pagehide after a reload. An entry this router pushed and
+ * never handed back stays `manual` and gets no native restore, so the router
+ * restores it as on a client-rendered load.
  */
-export function createScrollRestoration() {
-    window.history.scrollRestoration = "manual";
+export function createScrollRestoration(hydrating) {
+    const h = window.history;
     // the current entry needs its depth stamp for captures to have a key, even
     // if something replaced history.state after the adapter stamped it
     saveCurrentDepth();
+    const depth = () => window.history.state && window.history.state._depth;
     let positions = {};
+    let handedBack = {};
     try {
         positions = JSON.parse(sessionStorage.getItem(STORAGE_KEY)) || {};
+        handedBack = JSON.parse(sessionStorage.getItem(AUTO_KEY)) || {};
     }
     catch { }
-    const depth = () => window.history.state && window.history.state._depth;
+    const manual = () => {
+        h.scrollRestoration = "manual";
+        const d = depth();
+        if (d != null)
+            delete handedBack[d];
+    };
+    const d = depth();
+    let deferred = !!hydrating && (h.scrollRestoration === "auto" || (d != null && !!handedBack[d]));
+    if (!deferred)
+        manual();
+    const claim = () => {
+        if (!deferred)
+            return;
+        deferred = false;
+        manual();
+    };
+    let timer;
     let programmatic = false;
     let pending;
     const unbind = [
@@ -48,11 +84,22 @@ export function createScrollRestoration() {
                 pending = undefined;
         }),
         bindEvent(window, "pagehide", () => {
+            h.scrollRestoration = "auto";
+            const d = depth();
+            if (d != null)
+                handedBack[d] = 1;
             try {
                 sessionStorage.setItem(STORAGE_KEY, JSON.stringify(positions));
+                sessionStorage.setItem(AUTO_KEY, JSON.stringify(handedBack));
             }
             catch { }
-        })
+        }),
+        bindEvent(window, "pageshow", e => {
+            if (e.persisted)
+                manual();
+        }),
+        bindEvent(window, "load", () => deferred && (timer = setTimeout(claim))),
+        () => clearTimeout(timer)
     ];
     const restore = () => {
         if (pending == null)
@@ -68,43 +115,40 @@ export function createScrollRestoration() {
         programmatic = false;
     };
     return {
-        /** When the adapter notifies a traversal: mark the target for restoration. */
+        /**
+         * When the adapter notifies a traversal: mark the target and restore once
+         * the transition carrying it settles. The adapter notifies right before
+         * the location write, in the same tick, so the settle is that write's —
+         * a same-URL traversal included, which no location key would see.
+         */
         onPop() {
+            claim();
             pending = depth();
+            runWithOwner(null, () => onSettled(restore));
         },
+        /** The initial page settled: restore a reload/back_forward arrival. */
+        settled: () => restore(),
+        /** Before a client navigation writes history: the entry it creates copies the current mode. */
+        beforeWrite: claim,
         /** After a push: forward entries died, and this depth may be reused. */
         onPush() {
             const d = depth();
-            if (d != null)
+            if (d != null) {
                 for (const k in positions)
                     +k >= d && delete positions[k];
+                for (const k in handedBack)
+                    +k >= d && delete handedBack[k];
+            }
         },
-        create(router) {
-            // Restore once the traversal has settled: key on the location (a fully
-            // synchronous pop commits without isRouting ever flipping) and on
-            // isRouting, which reports in-flight transitions — native pops
-            // included — and holds the restore until they commit. restore() no-ops
-            // unless a traversal marked a target, so push navigations are inert.
-            // `transparent` keeps the effect invisible to the hydration id scheme —
-            // same reasoning as the link-claims effect (claims.ts): this setup is
-            // client-only, so an id-consuming node here has no server counterpart
-            // and every hydration id allocated after it shifts by one child slot.
-            // The visible failure is any <Loading> content that settled before the
-            // shell flush (a cache hit, a preloaded query): its serialized value and
-            // inlined markup are keyed under the server's ids, the shifted client
-            // misses both, recomputes, and re-renders the route fresh — duplicating
-            // the server DOM and leaving it inert.
-            createEffect(() => ({
-                url: router.location.pathname + router.location.search + router.location.hash,
-                routing: router.isRouting()
-            }), current => {
-                if (!current.routing)
-                    restore();
-            }, { transparent: true });
+        create() {
             onCleanup(() => unbind.forEach(u => u()));
             // reload/back_forward document loads land on an existing entry (a fresh
-            // navigation starts a new one and belongs at the top); the effect's
-            // initial run performs the restore after first render
+            // navigation starts a new one and belongs at the top); the router calls
+            // `settled` once the initial page has; a deferred arrival is the browser's
+            if (deferred) {
+                document.readyState === "complete" && claim();
+                return;
+            }
             const [nav] = performance.getEntriesByType?.("navigation");
             if (nav && nav.type !== "navigate")
                 pending = depth();
@@ -121,6 +165,7 @@ export function withScrollRestoration(history, restoration) {
     return {
         ...history,
         set(next) {
+            restoration.beforeWrite();
             history.set(next);
             next.replace || restoration.onPush();
         },

package/dist/routing.d.ts

@@ -54,6 +54,8 @@ export declare const useLocation: <S = unknown>() => Location<S>;
 /**
  * Retrieves a signal that indicates whether the router is currently processing a navigation.
  * Useful for showing pending navigation state while the next route and its data settle.
+ * This is the way to read routing state: `RouterContext` doesn't carry `isRouting`.
+ * For the in-flight destination, read the location with Solid's `isPending`/`latest`.
  *
  * @example
  * ```js
@@ -177,7 +179,11 @@ export interface LinkState {
      * parameter order and hash aside — what `aria-current="page"` reflects.
      */
     current: () => boolean;
-    /** This link is the target of an in-flight navigation. Styling: `data-pending`. */
+    /**
+     * This link is the target of an in-flight navigation (back/forward
+     * excluded). Works without the `pendingLinks` plugin, which only adds
+     * `data-pending` to plain anchors.
+     */
     pending: () => boolean;
 }
 /**