Split link state out of useLinkProps into useLinkState and data-pending

useLinkProps now returns only spreadable anchor props — the non-enumerable
isCurrent/isPending trick is gone. Pending links carry a data-pending
attribute for CSS styling, and useLinkState(to) serves programmatic reads.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: KidkArolis

CHANGELOG.md

@@ -1,14 +1,14 @@
 ## 0.7.0
 
 - **Breaking**: move route state inside `<Router>` and remove the old prop-based lifecycle hooks (`useRoute`, `onNavigating`, `onNavigated`). Read the current route with `useRoute()` and observe committed route changes with regular React effects.
-- **Breaking**: remove function-form `<Link>` props and `extraProps`. Use `aria-current="page"` for CSS styling, or `useLinkProps()` when active/pending state needs to affect rendered output.
+- **Breaking**: remove function-form `<Link>` props and `extraProps`. Use `aria-current="page"` and `data-pending` for CSS styling, or `useLinkState()` when active/pending state needs to affect rendered output.
 - Add Suspense-aware route transitions backed by React `useTransition`, exposed through `usePending()`.
 - Add route `resolver` support for code-split route segments. Resolvers are preloaded during navigation and rendered through `React.lazy`.
 - Add route `prepare(ctx)` support for fetch-as-you-render data loading. Returned `PreparedHandle`s are pinned while the route is committed and released on the next commit or `<Routes>` unmount.
 - Add `<DelayedSuspense>` and `pendingDelayMs` for delayed skeleton fallbacks during in-flight route navigations.
 - Add `transformRoute(route)` for synchronous pre-commit route rewrites, including URL replacement when the transformed route changes `url`.
 - Inject matched path params as props onto the route segment that declares each param.
-- Add per-link pending state through `useLinkProps(to).isPending`.
+- Add per-link pending state: `<Link>` and `useLinkProps(to)` set a `data-pending` attribute while the link's navigation is in flight (style with `a[data-pending]`), and `useLinkState(to)` returns `{ isCurrent, isPending }` for programmatic reads.
 - Add `usePendingRoute()` exposing the transformed route an in-flight navigation is heading to. Registers clicks, programmatic navigation, and browser back/forward alike.
 - Prepare the initial route during the first render so cold direct loads suspend on prepared data instead of reading an unseeded cache, and so chunk download and data loading overlap on direct loads too.
 - Deliver browser back/forward navigations outside the popstate task, via space-router 1.2's pluggable `schedule` option. React 19 flushes popstate-scheduled updates synchronously, which showed Suspense fallbacks instead of holding the previous route and never painted pending state; deferring traversal emits to a macrotask restores the same async transition semantics as link clicks.

MIGRATION.md

@@ -220,11 +220,12 @@ sets:
 }
 ```
 
-For active-aware logic that cannot be expressed in CSS, use `useLinkProps()`:
+For active-aware logic that cannot be expressed in CSS, use `useLinkState()`:
 
 ```tsx
 const linkProps = useLinkProps('/settings')
-return <a {...linkProps}>{linkProps.isCurrent ? 'Settings' : 'Go to settings'}</a>
+const { isCurrent } = useLinkState('/settings')
+return <a {...linkProps}>{isCurrent ? 'Settings' : 'Go to settings'}</a>
 ```
 
 User `onClick` handlers now compose with the router's internal click handling.

README.md

@@ -90,7 +90,8 @@ function IssueSection() {
 - `useNavigate()` returns a programmatic navigation function accepting a string URL or Space Router target object.
 - `usePending()` returns React transition pending state for route navigation.
 - `usePendingRoute()` returns the route an in-flight navigation is heading to (post-transform), or `null` when idle. Covers clicks, programmatic navigation, and browser back/forward.
-- `useLinkProps(to)` returns anchor props plus non-enumerable `isCurrent` and `isPending`.
+- `useLinkProps(to)` returns spreadable anchor props: `{ href, aria-current, data-pending, onClick }`. Style current links with `a[aria-current='page']` and in-flight links with `a[data-pending]` in CSS.
+- `useLinkState(to)` returns `{ isCurrent, isPending }` for programmatic per-target state — tabs, sidebar items, breadcrumb spinners.
 - `useMakeHref()` returns the underlying `router.href` helper.
 - `useInternalRouterInstance()` exposes the underlying Space Router instance for rare escape-hatch use.
 

demo/src/pages/ModeD.tsx

@@ -69,24 +69,22 @@ export default function ModeD({ id = ITEMS[0].id }: { id?: string }) {
 
       <div className='item-demo'>
         <aside className='item-list' aria-label='Items'>
-          {ITEMS.map((item) => {
-            const isCurrent = item.id === currentId
-            const isRequested = item.id === pendingItemId
-
-            return (
-              <Link
-                key={item.id}
-                href={{
-                  url: `/mode-d/${item.id}`,
-                  current: isCurrent,
-                }}
-                className={`item-link${isRequested ? ' requested' : ''}`}
-              >
-                <strong>{item.name}</strong>
-                <small>{item.meta}</small>
-              </Link>
-            )
-          })}
+          {ITEMS.map((item) => (
+            // The requested item lights up through the `data-pending`
+            // attribute `<Link>` sets while its navigation is in flight —
+            // styled in CSS via `.item-link[data-pending]`, no JS derivation.
+            <Link
+              key={item.id}
+              href={{
+                url: `/mode-d/${item.id}`,
+                current: item.id === currentId,
+              }}
+              className='item-link'
+            >
+              <strong>{item.name}</strong>
+              <small>{item.meta}</small>
+            </Link>
+          ))}
         </aside>
 
         <section className={`item-detail${isFading ? ' is-fading' : ''}`} aria-live='polite'>

demo/src/styles.css

@@ -138,6 +138,12 @@ code {
   border-left-color: var(--text);
 }
 
+/* the link whose navigation is in flight — attribute set by <Link> */
+.nav-link[data-pending] {
+  background: var(--surface-muted);
+  border-left-color: var(--text-dim);
+}
+
 .nav-link small {
   display: block;
   margin-top: 1px;
@@ -442,7 +448,7 @@ code {
   border-left-color: var(--text);
 }
 
-.item-link.requested {
+.item-link[data-pending] {
   background: var(--surface-muted);
 }
 

dist/index.d.ts

@@ -130,11 +130,26 @@ export declare function useMakeHref(): (to: import("space-router").To, curr?: Ro
 export interface LinkPropsResult {
     href: string;
     'aria-current': 'page' | undefined;
+    'data-pending': '' | undefined;
     onClick: (e: MouseEvent<HTMLAnchorElement>) => void;
+}
+export interface LinkState {
     isCurrent: boolean;
     isPending: boolean;
 }
+/**
+ * Anchor props for a router-driven `<a>`: `{ href, aria-current, data-pending,
+ * onClick }`. Everything returned is spreadable. Style current links with
+ * `a[aria-current='page']` and pending links with `a[data-pending]` in CSS;
+ * for programmatic reads use `useLinkState(to)`.
+ */
 export declare function useLinkProps(to: LinkTo): LinkPropsResult;
+/**
+ * Per-target link state without the anchor props: `{ isCurrent, isPending }`.
+ * Accepts the same target as `useLinkProps`, but works for any navigable UI,
+ * not just anchors — tab strips, sidebar items, breadcrumb spinners.
+ */
+export declare function useLinkState(to: LinkTo): LinkState;
 export interface LinkOwnProps {
     href?: LinkTo;
     replace?: boolean;

dist/index.d.ts.map

@@ -307,22 +307,34 @@ const linkProps = useLinkProps(to)
 <a {...linkProps} />
 ```
 
-Returns `{ href, aria-current, onClick, isCurrent, isPending }` so you can build your own anchor and get full router behavior without using `<Link />`. `isCurrent` and `isPending` are non-enumerable, so `<a {...useLinkProps(to)} />` stays safe, but you can still read them for active and per-link loading UI.
+Returns `{ href, aria-current, data-pending, onClick }` so you can build your own anchor and get full router behavior without using `<Link />`. Everything returned is spreadable — current and pending state ride along as attributes, so both can be styled in plain CSS:
+
+```css
+a[aria-current='page'] {
+  font-weight: 600;
+}
+a[data-pending] {
+  opacity: 0.6;
+}
+```
 
 Takes a `string` URL or an object — same fields as `useNavigate`, plus:
 
 - `current` override automatic current-page detection.
 
-For programmatic active-aware UI, read `isCurrent` from the returned props:
+### `useLinkState`
+
+```js
+const { isCurrent, isPending } = useLinkState(to)
+```
+
+Per-target link state for logic that cannot be expressed in CSS. Takes the same target as `useLinkProps`, but works for any navigable UI, not just anchors — tab strips, sidebar items, breadcrumb spinners:
 
 ```tsx
 const linkProps = useLinkProps('/settings')
+const { isCurrent } = useLinkState('/settings')
 
-return (
-  <a {...linkProps} className={cn('nav-link', linkProps.isCurrent && 'active')}>
-    Settings
-  </a>
-)
+return <a {...linkProps}>{isCurrent ? 'Settings' : 'Go to settings'}</a>
 ```
 
 ### `useMakeHref`