Skip to content

Commit 69e5769

Browse files
docs: document the data-pending opt-in, useIsRouting as the routing-state read, and the RouterContext removal (#655)
Co-authored-by: Cursor <[email protected]>
1 parent 37a19cb commit 69e5769

5 files changed

Lines changed: 38 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -517,7 +517,7 @@ Behavior modifiers are attributes, so they work identically in client, server-re
517517
<a href="https://example.com">External — untouched</a>
518518
```
519519

520-
Active and pending state is styled with CSS — one vocabulary for every kind of link:
520+
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:
521521

522522
```css
523523
nav a[aria-current="page"] {
@@ -539,7 +539,7 @@ import { createRouter, pendingLinks } from "@solidjs/router";
539539
const Router = createRouter({ routes, links: pendingLinks });
540540
```
541541

542-
With it, `data-pending` agrees with `useLinkState().pending` at every moment. Back/forward traversals don't mark links pending.
542+
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.
543543

544544
One rule decides both, for anchors and `useLinkState` alike:
545545

@@ -861,7 +861,7 @@ See [Typed Search Params](#typed-search-params). Reads are proxied — access pr
861861

862862
### useIsRouting
863863

864-
A signal indicating whether the router is processing a navigation — useful for pending UI while the next route and its data settle:
864+
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`.
865865

866866
```tsx
867867
const isRouting = useIsRouting();
@@ -926,7 +926,7 @@ Reactive `active`/`current`/`pending` state for [custom link components](#links)
926926

927927
- `current()` — same path and same query as the location, ignoring parameter order and the hash (what `aria-current="page"` reflects)
928928
- `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
929-
- `pending()` — the link's path is the target of an in-flight navigation, back/forward excluded (`data-pending`, with [`pendingLinks`](#links))
929+
- `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
930930

931931
Pass `{ end: true }` to make `active` (and `pending`) exact-path for any link.
932932

@@ -1053,6 +1053,7 @@ Route props map 1:1 onto definition keys (`path`, `component`, `preload`, `match
10531053
- `<A href replace noScroll state>` → `<a href replace noscroll state>` (attributes, all lowercase)
10541054
- `activeClass` / `inactiveClass` → CSS attribute selectors on `[data-active]` / `[aria-current="page"]`
10551055
- `end` → style exact matches with `[aria-current="page"]` (which also compares the query) instead of `[data-active]`; the root path already only matches exactly
1056+
- Pending link styling → `[data-pending]`, opt-in with `createRouter({ routes, links: pendingLinks })`
10561057
- Route-relative hrefs → typed `paths`; `useResolvedPath` / `useHref` remain for manual resolution
10571058
- Custom link components → `useLinkState`
10581059

@@ -1063,6 +1064,7 @@ Route props map 1:1 onto definition keys (`path`, `component`, `preload`, `match
10631064
- `redirect` / `reload` → import from `@solidjs/web`; they're protocol-level and work without the router
10641065
- `json(data, init)` → `respond(data, init)` from `@solidjs/web`
10651066
- `cache` (deprecated alias) → `query`
1067+
- `RouterContext`'s `isRouting` / `pendingTarget` → `useIsRouting()`; for the in-flight destination, the [`isPending`/`latest` recipe](#useisrouting)
10661068

10671069
### Data APIs (Solid 2)
10681070

‎src/pending.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,17 @@ export function linkPending(
6363
}
6464

6565
/**
66-
* Claims plugin: marks claimed anchors that are the target of the in-flight
67-
* navigation with `data-pending`, agreeing with `useLinkState().pending`.
66+
* Opt-in `data-pending` for plain anchors. Marks claimed links whose path
67+
* covers the in-flight destination of a link click or `navigate()` (not
68+
* back/forward), until it lands. Agrees with `useLinkState().pending`, which
69+
* works without it. `aria-current` and `data-active` need no plugin.
6870
*
6971
* @example
7072
* ```ts
73+
* import { createRouter, pendingLinks } from "@solidjs/router";
74+
*
7175
* const Router = createRouter({ routes, links: pendingLinks });
76+
* // CSS: a[data-pending] { opacity: .6 }
7277
* ```
7378
*/
7479
export const pendingLinks: LinksPlugin = (router, base) => ({

‎src/routers/factory.tsx‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -170,8 +170,16 @@ export interface RouterConfig<R extends readonly RouteDefinition[] = RouteDefini
170170
actionBase?: string;
171171
explicitLinks?: boolean;
172172
/**
173-
* Link claims plugin. Pass `pendingLinks` to mark claimed anchors that are
174-
* the target of the in-flight navigation with `data-pending`. Client-only.
173+
* Link claims plugin. `aria-current` and `data-active` are automatic; pass
174+
* `pendingLinks` to also mark links covering the in-flight destination of a
175+
* link click or `navigate()` with `data-pending`. Client-only.
176+
*
177+
* @example
178+
* ```ts
179+
* import { createRouter, pendingLinks } from "@solidjs/router";
180+
*
181+
* const Router = createRouter({ routes, links: pendingLinks });
182+
* ```
175183
*/
176184
links?: LinksPlugin;
177185
/** Preload route code/data on link hover and focus. Defaults to `true`. */

‎src/routing.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,8 @@ export const useLocation = <S = unknown>() => useRouter().location as Location<S
173173
/**
174174
* Retrieves a signal that indicates whether the router is currently processing a navigation.
175175
* Useful for showing pending navigation state while the next route and its data settle.
176+
* This is the way to read routing state: `RouterContext` doesn't carry `isRouting`.
177+
* For the in-flight destination, read the location with Solid's `isPending`/`latest`.
176178
*
177179
* @example
178180
* ```js
@@ -373,7 +375,11 @@ export interface LinkState {
373375
* parameter order and hash aside — what `aria-current="page"` reflects.
374376
*/
375377
current: () => boolean;
376-
/** This link is the target of an in-flight navigation. Styling: `data-pending`. */
378+
/**
379+
* This link is the target of an in-flight navigation (back/forward
380+
* excluded). Works without the `pendingLinks` plugin, which only adds
381+
* `data-pending` to plain anchors.
382+
*/
377383
pending: () => boolean;
378384
}
379385

‎src/types.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -468,8 +468,14 @@ export interface RouterContext {
468468
}
469469

470470
/**
471-
* Extends the link claims (see `pendingLinks`): built once per router with
472-
* its base path.
471+
* A plugin for the router's `links` option that extends the state it writes
472+
* onto claimed anchors. Built once per router with its base path. The router
473+
* ships `pendingLinks`, which adds `data-pending`.
474+
*
475+
* @example
476+
* ```ts
477+
* const Router = createRouter({ routes, links: pendingLinks });
478+
* ```
473479
*/
474480
export type LinksPlugin = (
475481
router: RouterContext,

0 commit comments

Comments
 (0)