Recenter router around Suspense transitions#10
Open
KidkArolis wants to merge 17 commits intomasterfrom
Open
Conversation
Why: the 0.6.x escape hatches (onNavigating, onNavigated, useRoute
injection prop) predate React's useTransition and force route state
out of the router, which breaks Suspense's transition contract — the
commit needs to be inside startTransition for the previous route to
stay on screen while the next one prepares.
Router: drops onNavigating/onNavigated/useRoute props. State is now
internal (useState + useTransition). Adds:
- prepare(ctx) per route — returns PreparedHandle[] for figbird-style
fetch-as-you-render data loading. Router pins handles for the
lifetime of the committed nav and releases them on the next commit
or on Routes unmount.
- resolver: () => import('./Page') — preloaded at navigate time and
rendered via React.lazy.
- transformRoute() — synchronous pre-commit URL rewrite hook,
replaces the one legitimate use case for onNavigating
(e.g. persisted-query restoration with history.replaceState).
- usePending() — exposes useTransition's isPending for top-bar
progress and "click did something" affordances.
- DelayedSuspense + Router pendingDelayMs — encapsulates the "hold
previous route for N ms then degrade to skeleton" pattern.
Internally uses a never-resolving-promise fallback during the
hold window so suspension propagates to the outer transition,
then swaps to the real fallback once the threshold elapses or
the boundary post-commits with reads still pending.
- defineRoute / defineRoutes — typed identity helpers.
Tests: rewritten for the new API; new coverage for transformRoute,
usePending, and the prepare/release lifecycle.
Docs: README, docs/content/_index.md fully updated. New MIGRATION.md
walks 0.6.x → 1.0 with recipes for the removed surfaces.
Demo: examples/loading-modes/ — Vite app showcasing the three
loading-mode patterns (immediate+skeletons, wait-for-ready, timed
fallback) against simulated chunk + data latencies, so the API
choices can be felt against real timings rather than argued in
the abstract.
dist/ rebuilt.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Plain object routes were always supposed to be the canonical shape;
the `defineRoute` / `defineRoutes` helpers in 1.0-WIP were leaning
toward a typed-routes future that doesn't fit how this library is
actually used (humaans has 100+ stable, simple-string param routes;
the wrapper-per-route ceremony wasn't earning its keep against
component-level typing).
Two changes that together replace the helpers:
- The `<Routes>` renderer now spreads each matched path param onto the
leaf segment's component as own props. Each segment receives only
the params declared in its own `path` — wrapping layouts that
didn't declare those params get nothing extra. Static `props` from
the route definition still spread alongside and win on key
collision so consumers can override intentionally.
- `defineRoute` and `defineRoutes` are removed. Routes are plain
objects in plain arrays. Components type the params they expect
via their own function signature; the runtime injection meets them
at that boundary. `prepare(ctx)` keeps `ctx.params` typed as
`Record<string, string>` — typo-resistance via TypeScript wasn't
worth the per-route wrapper or the mapped-tuple helper alternative.
Net result: humaans-style routes stay as `{ path, resolver, prepare }`
plain objects, and a page like:
export default function Workflow({ workflowId }: { workflowId: string }) { ... }
receives `workflowId` for free from a `path: '/workflows/:workflowId'`
route — no `useRoute()` dance, no helper wrappers, no codegen.
Demo's ModeD migrated to declare `{ id?: string }` directly instead
of reaching for `useRoute()`. Tests, MIGRATION, and docs updated.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Verification