feat: add usePendingMatches hook

[thomastvedt]

Closes #7859

Since the granular stores refactor, pendingMatches is no longer part of RouterState, so there is no public reactive way to read the matches of an in-flight navigation — useRouterState({ select: (s) => s.pendingMatches }) no longer compiles. The data still exists on router.stores.pendingMatches (already a derived reactive store, cleared on commit), but nothing public subscribes to it.

This PR adds a usePendingMatches hook mirroring useMatches over router.stores.pendingMatches, in all three adapters:

• react-router: same shape as useMatches, including select, structuralSharing and the SSR short-circuit
• solid-router: createMemo + replaceEqualDeep, same as useMatches
• vue-router: useStore over the pending store, same as useMatches

The hook returns an empty array when no navigation is in flight.

Use case (from the issue): when migrating from react-router, reactively highlighting the destination navigation item from the pending matches' staticData as soon as navigation starts, before code-split chunks and loaders resolve — without reaching into router.stores and hand-rolling useSyncExternalStore over router events.

Also included:

• Docs page docs/router/api/router/usePendingMatchesHook.md, linked from the API index
• Unit tests for all three adapters: pending matches expose the destination path while a loader is blocked, and clear once the navigation resolves

test:eslint, test:types and test:unit pass for the three packages. Developed with AI assistance (Claude Code).

Summary by CodeRabbit

• New Features
  • Added usePendingMatches for React, Solid, and Vue to access destination route matches while navigation is in-flight.
  • Supports select to derive custom values from pending matches.
  • Pending matches automatically clear once navigation completes.
• Documentation
  • Updated Router API docs and added a new page documenting usePendingMatches with examples.
• Tests
  • Added coverage for pending-match behavior during unresolved navigation and after completion.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 41114dba-aff7-44ea-9e4a-c5a6fea6e9ca

📥 Commits

Reviewing files that changed from the base of the PR and between 357e0ce and 81cf241.

📒 Files selected for processing (1)

• packages/solid-router/src/Matches.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/solid-router/src/Matches.tsx

---

📝 Walkthrough

Walkthrough

Adds usePendingMatches to the React, Solid, and Vue routers, exposes it through package entry points, tests pending navigation behavior, and documents its options and return contract.

Changes

Pending matches API

Layer / File(s)	Summary
Framework hook implementations packages/react-router/src/Matches.tsx, packages/solid-router/src/Matches.tsx, packages/vue-router/src/Matches.tsx	Adds framework-specific reactive hooks that read router.stores.pendingMatches and support optional selection.
Public exports and navigation tests packages/*-router/src/index.tsx, packages/*-router/tests/Matches.test.tsx	Re-exports usePendingMatches and verifies selected destination paths during unresolved and completed navigations.
Hook documentation docs/router/api/router.md, docs/router/api/router/usePendingMatchesHook.md	Adds the API index entry and documents behavior, options, return values, and usage.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Router
  participant PendingMatchesHook
  participant DestinationLoader
  User->>Router: click destination link
  Router->>PendingMatchesHook: expose destination pending match
  PendingMatchesHook-->>User: selected destination pathname
  Router->>DestinationLoader: await route loader
  DestinationLoader-->>Router: resolve loader
  Router->>PendingMatchesHook: clear pending matches

Loading

Suggested labels: package: react-router, package: solid-router, package: vue-router

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding the usePendingMatches hook.
Linked Issues check	✅ Passed	The PR restores a public reactive API for pendingMatches via usePendingMatches across adapters, matching the issue request.
Out of Scope Changes check	✅ Passed	The changes are scoped to the new hook, exports, docs, and tests, with only a no-op Solid formatting refactor.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/router/api/router/usePendingMatchesHook.md`:
- Around line 6-8: Update the usePendingMatches documentation to state that
destination RouteMatch objects are available during any in-flight navigation,
including navigations blocked by pending conditions, not only while loading.
Preserve the existing behavior description for resolved or idle navigations and
the useMatches reference.
- Around line 23-28: Update the `opts.structuralSharing` documentation in
`usePendingMatchesHook` so it is explicitly scoped to the React adapter rather
than presented as a universal option. Do not claim Solid or Vue support unless
their hook option types and implementations are updated to expose it.

In `@packages/solid-router/src/Matches.tsx`:
- Around line 233-234: Update the conditional return logic in Matches.tsx to
wrap the prev === undefined branch in curly braces, and replace the any cast on
replaceEqualDeep with UseMatchesResult to preserve strict typing.

In `@packages/vue-router/src/Matches.tsx`:
- Around line 311-314: Update the fallback branch in the Matches selection logic
to remove the any cast and use the appropriate strict TypeScript type for
matches, while preserving the existing opts.select behavior and return value.

In `@packages/vue-router/tests/Matches.test.tsx`:
- Around line 386-389: Remove the explicit Array<any> annotation from the select
callback in usePendingMatches and let TypeScript infer the matches parameter
type. Preserve the existing last-match pathname selection and empty-string
fallback.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ea2d10bb-f2e0-46b4-b7bd-50d732ddb506

📥 Commits

Reviewing files that changed from the base of the PR and between edf5575 and d48b08a.

📒 Files selected for processing (11)

• docs/router/api/router.md
• docs/router/api/router/usePendingMatchesHook.md
• packages/react-router/src/Matches.tsx
• packages/react-router/src/index.tsx
• packages/react-router/tests/Matches.test.tsx
• packages/solid-router/src/Matches.tsx
• packages/solid-router/src/index.tsx
• packages/solid-router/tests/Matches.test.tsx
• packages/vue-router/src/Matches.tsx
• packages/vue-router/src/index.tsx
• packages/vue-router/tests/Matches.test.tsx