Recenter router around Suspense transitions

[KidkArolis]

Goals

0.6 was callback-driven: apps hooked onNavigating to preload code and data, tracked their own navigating flags, and wired route state through external stores. This rewrite recenters the router on React's own machinery — a navigation is a useTransition:

1. Navigations are transitions. The previous page stays on screen and interactive while the destination loads. Pending state falls out of the transition for free — usePending() for "is a navigation happening", usePendingRoute() for "where to", and a per-link data-pending attribute for "was it this link" — for clicks, programmatic navigation, and browser back/forward alike.
2. Fetch as you render. Route resolver chunks and prepare(ctx) data fetches start the moment navigation begins (including cold direct loads), so code download and data loading overlap instead of waterfalling. Prepared cache entries stay pinned for exactly as long as the route is committed.
3. Loading UX is declarative and per-surface. Suspense boundaries decide what loading UI appears where. <DelayedSuspense> adds the browser-style "hold the old page briefly, then degrade to a skeleton" behavior with a single pendingDelayMs knob.

What it unlocks

const routes = [
  { path: '/', component: Home },
  {
    path: '/issues/:id',
    // chunk preloaded at navigation time, rendered via React.lazy
    resolver: () => import('./pages/IssueDetail'),
    // data fetch starts immediately, in parallel with the chunk
    prepare: ({ params }) => [issueStore.prepare({ id: Number(params.id) })],
  },
]

function App() {
  return (
    <Router pendingDelayMs={1000}>
      <Suspense fallback={null}>
        <Routes routes={routes} />
      </Suspense>
    </Router>
  )
}

// `id` arrives as a regular prop, injected from the `:id` path segment
export default function IssueDetail({ id }) {
  const issue = issueStore.read(id) // suspends only if prepare hasn't finished
  return (
    <>
      <h1>{issue.title}</h1>
      <DelayedSuspense fallback={<CommentsSkeleton />}>
        <Comments issueId={id} />
      </DelayedSuspense>
    </>
  )
}

/* active and pending link styling is pure CSS — no render-prop plumbing */
.nav-link[aria-current='page'] { font-weight: 600; }
.nav-link[data-pending] { opacity: 0.6; }

Clicking a link to /issues/123 keeps the current page up while the chunk and data load in parallel; the clicked link dims via data-pending. If loading outlasts pendingDelayMs, <DelayedSuspense> boundaries degrade to skeletons. usePendingRoute() covers destination-aware pending UI — e.g. highlighting the requested item in a list before it commits (see Mode D in the demo).

Breaking changes

• Route state moved inside <Router>; the onNavigating / onNavigated / useRoute props are gone. Use resolver/prepare for preloading and useRoute() + effects for observing navigations.
• Function-form <Link> props (className, style, extraProps) are gone. Style via aria-current / data-pending in CSS, or useLinkState(to) when state must affect rendered output.

See MIGRATION.md for the step-by-step guide and the docs for the full API reference.

Demo

npm run demo — an interactive tour of four loading-mode recipes (inner skeletons, hold-then-swap, delayed skeletons, detail swap fade) over simulated chunk and data latencies.

Verification

• npm test — 50 tests, 100% statement coverage
• npm run demo:build

🤖 Generated with Claude Code