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

package/README.md

@@ -17,7 +17,7 @@ Explore the official [documentation](https://docs.solidjs.com/solid-router) for
 ## Core Features
 
 - **Typed Routing**: URLs built through a typed path proxy inferred from your route config — `paths.users(2).settings` typechecks against the tree
-- **Plain Anchors**: no link component — `<a>` elements get `aria-current`, `data-active`, and `data-pending` automatically via compiler-claimed anchors
+- **Plain Anchors**: no link component — `<a>` elements get `aria-current` and `data-active` automatically via compiler-claimed anchors, and `data-pending` with the opt-in `pendingLinks` plugin
 - **Universal Rendering**: one factory for browser, hash, memory, and server rendering; history adapters are imports, so unused ones never enter your bundle
 - **Preload Functions**: parallel data fetching following the render-as-you-fetch pattern, triggered eagerly on link hover/focus
 - **Data APIs with Caching**: `query` and `action` with deduplication, revalidation, single-flight mutations, and progressive enhancement — plus experimental `liveQuery` for keyed queries over live streams
@@ -425,7 +425,7 @@ const routes = [{ component: serverRouteComponent(query(appShell, "shell")), chi
 render(() => <Router routes={routes} />, document.body);
 ```
 
-`children` is the only client position the router fills, and the helper's type says so: a server component that requires other props — event handlers, refs, named slots — is rejected. Those come from the client, so that route has a client half; write it as an ordinary route component around `dynamic()`. Interaction that lives on the server — form posts to server actions via `action={addTodo}` — needs no client component at all.
+`children` is the only client position the router fills, and the helper's type says so: a server component that requires other props — event handlers, refs, named slots — is rejected. Those come from the client, so that route has a client half; write it as an ordinary route component around `dynamicComponent()`. Interaction that lives on the server — form posts to server actions via `action={addTodo}` — needs no client component at all.
 
 ### File-System Routes
 
@@ -517,7 +517,7 @@ Behavior modifiers are attributes, so they work identically in client, server-re
 <a href="https://example.com">External — untouched</a>
 ```
 
-Active and pending state is styled with CSS — one vocabulary for every kind of link:
+Active and pending state is styled with CSS — one vocabulary for every kind of link. `aria-current` and `data-active` are automatic; `data-pending` is opt-in:
 
 ```css
 nav a[aria-current="page"] {
@@ -528,9 +528,19 @@ nav a[data-active] {
 } /* exact or prefix match on the path */
 a[data-pending] {
   opacity: 0.6;
-} /* target of in-flight navigation */
+} /* target of in-flight navigation — needs `links: pendingLinks` */
 ```
 
+`data-pending` is opt-in, so an app that never shows pending link state doesn't ship the code that computes it. Pass the `pendingLinks` plugin to the router:
+
+```tsx
+import { createRouter, pendingLinks } from "@solidjs/router";
+
+const Router = createRouter({ routes, links: pendingLinks });
+```
+
+It marks the links whose path covers the in-flight destination of a link click or `navigate()` call — by the same path rule as `data-active` — until that navigation lands. Back/forward traversals don't mark links pending. `data-pending` agrees with `useLinkState().pending` at every moment; the hook works with or without the plugin.
+
 One rule decides both, for anchors and `useLinkState` alike:
 
 - **current** (`aria-current="page"`) — same path and same query, ignoring parameter order and the hash. On `/?filter=active`, `<a href="/?filter=active">` is current and `<a href="/">` is not.
@@ -793,6 +803,7 @@ createRouter(config);
 | `actionBase`    | `string`                  | Root url for server actions, default `/_server`                                                       |
 | `preloadLinks`  | `boolean`                 | Preload route code/data on link hover and focus, default `true`                                       |
 | `explicitLinks` | `boolean`                 | Require the `link` attribute for router handling instead of intercepting all anchors, default `false` |
+| `links`         | `LinksPlugin`             | Link claims plugin — `pendingLinks` adds `data-pending` to the in-flight navigation's target          |
 | `transformUrl`  | `(url: string) => string` | Rewrite URLs before matching                                                                          |
 
 The returned instance is the provider component and carries the static surface:
@@ -850,14 +861,24 @@ See [Typed Search Params](#typed-search-params). Reads are proxied — access pr
 
 ### useIsRouting
 
-A signal indicating whether the router is processing a navigation — useful for pending UI while the next route and its data settle:
+A signal indicating whether the router is processing a navigation — useful for pending UI while the next route and its data settle. It's the way to read routing state: `RouterContext` doesn't carry `isRouting` or `pendingTarget`.
 
 ```tsx
 const isRouting = useIsRouting();
 return <div classList={{ "grey-out": isRouting() }}>...</div>;
 ```
 
-In Solid's dev and observe builds the router also declares every navigation to the attribution engine (`solid-js/attribution`): holds and re-runs caused by a navigation are named after the route pattern (`navigation to /users/:id`), timed from the user event that started it, and redirect hops fold onto the navigation they belong to. `attribution.history("navigation")` and `feedback().navigations` list them; nothing of this exists in production builds.
+The router doesn't expose where a navigation is heading; read it off the location with Solid's `isPending` and `latest`. It covers back/forward traversals too:
+
+```tsx
+import { isPending, latest } from "solid-js";
+
+const location = useLocation();
+const target = () =>
+  isPending(() => location.pathname) ? latest(() => location.pathname) : undefined;
+```
+
+In Solid's dev and observe builds the router also declares every navigation to the attribution engine (`solid-js/attribution`): holds and re-runs caused by a navigation are named after the route pattern (`navigation to /users/:id`), timed from the user event that started it, and redirect hops fold onto the navigation they belong to. A link click or a native form submit the router handles runs in the interaction Solid records for that event, so the navigation or action belongs to the same record as any `onClick` work for that click. `attribution.history("navigation")` and `feedback().navigations` list them; nothing of this exists in production builds.
 
 ### useMatch
 
@@ -905,7 +926,7 @@ Reactive `active`/`current`/`pending` state for [custom link components](#links)
 
 - `current()` — same path and same query as the location, ignoring parameter order and the hash (what `aria-current="page"` reflects)
 - `active()` — the location's path is the link's path or lives under it, query ignored (`data-active`); a root link (`/`, which resolves to the router's `base`) is exact-only
-- `pending()` — the link's path is the target of an in-flight navigation (`data-pending`)
+- `pending()` — the link's path is the target of an in-flight navigation, back/forward excluded (`data-pending`). Works without the [`pendingLinks`](#links) plugin, which only adds the attribute to plain anchors
 
 Pass `{ end: true }` to make `active` (and `pending`) exact-path for any link.
 
@@ -1032,6 +1053,7 @@ Route props map 1:1 onto definition keys (`path`, `component`, `preload`, `match
 - `<A href replace noScroll state>` → `<a href replace noscroll state>` (attributes, all lowercase)
 - `activeClass` / `inactiveClass` → CSS attribute selectors on `[data-active]` / `[aria-current="page"]`
 - `end` → style exact matches with `[aria-current="page"]` (which also compares the query) instead of `[data-active]`; the root path already only matches exactly
+- Pending link styling → `[data-pending]`, opt-in with `createRouter({ routes, links: pendingLinks })`
 - Route-relative hrefs → typed `paths`; `useResolvedPath` / `useHref` remain for manual resolution
 - Custom link components → `useLinkState`
 
@@ -1042,6 +1064,7 @@ Route props map 1:1 onto definition keys (`path`, `component`, `preload`, `match
 - `redirect` / `reload` → import from `@solidjs/web`; they're protocol-level and work without the router
 - `json(data, init)` → `respond(data, init)` from `@solidjs/web`
 - `cache` (deprecated alias) → `query`
+- `RouterContext`'s `isRouting` / `pendingTarget` → `useIsRouting()`; for the in-flight destination, the [`isPending`/`latest` recipe](#useisrouting)
 
 ### Data APIs (Solid 2)
 

package/dist/claims.d.ts

@@ -1,4 +1,4 @@
-import type { RouterContext } from "./types.js";
+import type { LinksPlugin, RouterContext } from "./types.js";
 export declare function setFormClaimHandler(handler: ((form: HTMLFormElement) => void) | undefined): void;
 /**
  * The compiler claims every `a[href]` and `form[action]` at creation, and the
@@ -11,7 +11,9 @@ export declare function setFormClaimHandler(handler: ((form: HTMLFormElement) =>
  *   included (parameter order aside)
  * - `data-active` — pathname exact or prefix match (the router's root, its
  *   base path, exact only)
- * - `data-pending` — the link is the target of an in-flight navigation
+ * - `data-pending` — the link is the target of an in-flight navigation;
+ *   opt-in through `createRouter({ links: pendingLinks })`. Without the
+ *   plugin, claims never read pending state and the sweep does not track it.
  *
  * The matching rule is `matchLink`, shared with `useLinkState`. The router
  * only touches an `aria-current` it wrote itself: one the author set (a
@@ -26,4 +28,4 @@ export declare function setFormClaimHandler(handler: ((form: HTMLFormElement) =>
  * are the same one-shot untracked refresh, reading the element's current
  * `href` from the DOM.
  */
-export declare function setupLinkClaims(router: RouterContext, explicitLinks?: boolean): void;
+export declare function setupLinkClaims(router: RouterContext, explicitLinks?: boolean, links?: LinksPlugin): void;

package/dist/claims.js

@@ -22,7 +22,9 @@ export function setFormClaimHandler(handler) {
  *   included (parameter order aside)
  * - `data-active` — pathname exact or prefix match (the router's root, its
  *   base path, exact only)
- * - `data-pending` — the link is the target of an in-flight navigation
+ * - `data-pending` — the link is the target of an in-flight navigation;
+ *   opt-in through `createRouter({ links: pendingLinks })`. Without the
+ *   plugin, claims never read pending state and the sweep does not track it.
  *
  * The matching rule is `matchLink`, shared with `useLinkState`. The router
  * only touches an `aria-current` it wrote itself: one the author set (a
@@ -37,8 +39,9 @@ export function setFormClaimHandler(handler) {
  * are the same one-shot untracked refresh, reading the element's current
  * `href` from the DOM.
  */
-export function setupLinkClaims(router, explicitLinks) {
+export function setupLinkClaims(router, explicitLinks, links) {
     const basePath = router.base.path();
+    const plugin = links && links(router, basePath);
     // per-element record; `owned` is whether the `aria-current` on the element
     // is the router's, so it never writes over or removes an authored one
     const claimed = new WeakMap();
@@ -76,22 +79,18 @@ export function setupLinkClaims(router, explicitLinks) {
         // read reactive sources unconditionally so the owning effect stays
         // subscribed even while the anchor is not router-managed
         const location = router.location;
-        const routing = router.isRouting();
+        const routing = plugin && plugin.track();
         const url = managedUrl(a);
         const target = url && url.pathname + url.search;
         // no per-anchor `end` opt-out like useLinkState has
         const { active, current } = matchLink(location, target, basePath);
-        // effects observe the committed location during a transition, so the
-        // in-flight target comes from pendingTarget — readable here because the
-        // isRouting write flushes after the target is assigned
-        const pending = routing &&
-            !!router.pendingTarget &&
-            matchLink({ pathname: router.pendingTarget.value, search: "" }, target, basePath).active;
+        const pending = !!routing && plugin.pending(target);
         return { active, pending, current };
     }
     function apply(a, rec, { active, pending, current }) {
         active ? a.setAttribute("data-active", "") : a.removeAttribute("data-active");
-        pending ? a.setAttribute("data-pending", "") : a.removeAttribute("data-pending");
+        if (plugin)
+            pending ? a.setAttribute("data-pending", "") : a.removeAttribute("data-pending");
         // Ownership is read against the element, not just the record. A
         // server-component morph resets attributes to the server HTML, which
         // never carries router link state, then re-claims: an owned value that
@@ -114,9 +113,10 @@ export function setupLinkClaims(router, explicitLinks) {
     }
     const refresh = (a, rec) => untrack(() => apply(a, rec, linkState(a)));
     // The one subscription for every anchor: compute tracks the sources
-    // linkState derives from (the in-flight pendingTarget is readable in the
-    // effect phase because the isRouting write flushes after the target is
-    // assigned), the effect phase sweeps the registry untracked.
+    // linkState derives from (with the plugin, its pending read — the
+    // in-flight target is readable in the effect phase because the isRouting
+    // write flushes after the target is assigned), the effect phase sweeps the
+    // registry untracked.
     //
     // `transparent` keeps the effect invisible to the hydration id scheme.
     // This setup is client-only, so an id-consuming node here has no server
@@ -124,7 +124,7 @@ export function setupLinkClaims(router, explicitLinks) {
     // slot — lazy-route lookups miss and hydration leaves server nodes
     // unclaimed. (The option is honored by the runtime but missing from the
     // published EffectOptions type, hence the cast.)
-    createRenderEffect(() => (router.location.pathname, router.location.search, router.isRouting()), () => registry.forEach(a => refresh(a, claimed.get(a))), { transparent: true });
+    createRenderEffect(() => (router.location.pathname, router.location.search, plugin && plugin.track()), () => registry.forEach(a => refresh(a, claimed.get(a))), { transparent: true });
     onCleanup(registerElementClaim(node => {
         const name = node.nodeName.toUpperCase();
         if (name === "FORM")

package/dist/data/events.js

@@ -1,4 +1,4 @@
-import { delegateEvents } from "@solidjs/web";
+import { delegateEvents, dispatchAsInteraction } from "@solidjs/web";
 import { onCleanup } from "solid-js";
 import { isUnderBase } from "../utils.js";
 let formHandler;
@@ -52,12 +52,14 @@ export function setupNativeEvents({ preload = true, explicitLinks = false, actio
             const to = router.parsePath(url.pathname + url.search + url.hash);
             const state = a.getAttribute("state");
             evt.preventDefault();
-            navigateFromRoute(to, {
+            // Only a click the router acts on joins the event's interaction: this
+            // listener hears every click on the document.
+            dispatchAsInteraction(evt, () => navigateFromRoute(to, {
                 resolve: false,
                 replace: a.hasAttribute("replace"),
                 scroll: !a.hasAttribute("noscroll"),
                 state: state ? JSON.parse(state) : undefined
-            });
+            }));
         }
         function handleAnchorPreload(evt) {
             const res = handleAnchor(evt);
@@ -106,15 +108,17 @@ export function setupNativeEvents({ preload = true, explicitLinks = false, actio
             const data = new FormData(form, evt.submitter);
             import("./serverForms.js").then(m => m.submitServerForm(router, path, form, data));
         }
+        const handleSubmit = (evt) => dispatchAsInteraction(evt, () => handleFormSubmit(evt));
         // ensure delegated event run first
         delegateEvents(["click", "submit"]);
         document.addEventListener("click", handleAnchorClick);
+        // preloads are not interactions: those listeners run outside any frame
         if (preload) {
             document.addEventListener("mousemove", handleAnchorMove, { passive: true });
             document.addEventListener("focusin", handleAnchorPreload, { passive: true });
             document.addEventListener("touchstart", handleAnchorPreload, { passive: true });
         }
-        document.addEventListener("submit", handleFormSubmit);
+        document.addEventListener("submit", handleSubmit);
         onCleanup(() => {
             document.removeEventListener("click", handleAnchorClick);
             if (preload) {
@@ -122,7 +126,7 @@ export function setupNativeEvents({ preload = true, explicitLinks = false, actio
                 document.removeEventListener("focusin", handleAnchorPreload);
                 document.removeEventListener("touchstart", handleAnchorPreload);
             }
-            document.removeEventListener("submit", handleFormSubmit);
+            document.removeEventListener("submit", handleSubmit);
         });
     };
 }

package/dist/index.d.ts

@@ -21,9 +21,10 @@ 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 type { LinkState } 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";
 export type { RoutePaths, PathParamsOf, PathEnd, TypedMatchFilter, DefaultSearchTypes } from "./paths.js";
 export * from "./data/index.js";
-export type { Location, LocationChange, LocationWrite, SearchParams, MatchFilter, MatchFilters, NavigateOptions, Navigator, OutputMatch, Params, PathMatch, RouteComponent, RouteParams, RouteProps, RouteSectionProps, RoutePreloadFunc, RoutePreloadFuncArgs, RouteDefinition, RouteDescription, RouteMatch, RouterIntegration, RouterUtils, SetParams, SetSearchParams, ServerRouteArgs, ServerRouteParams, ServerRouteFunction, ServerRouteView, Submission, BeforeLeaveEventArgs, TypedPath, TypedSearchPath, StandardSchemaV1 } from "./types.js";
+export type { LinksPlugin, Location, LocationChange, LocationWrite, SearchParams, MatchFilter, MatchFilters, NavigateOptions, Navigator, OutputMatch, Params, PathMatch, RouteComponent, RouteParams, RouteProps, RouteSectionProps, RoutePreloadFunc, RoutePreloadFuncArgs, RouteDefinition, RouteDescription, RouteMatch, RouterIntegration, RouterUtils, SetParams, SetSearchParams, ServerRouteArgs, ServerRouteParams, ServerRouteFunction, ServerRouteView, Submission, BeforeLeaveEventArgs, TypedPath, TypedSearchPath, StandardSchemaV1 } from "./types.js";