implement-rfc

实现 React Router RFC

实现以下 GitHub 讨论中的 RFC：$ARGUMENTS

分支管理

RFC 实现应从干净的工作树开始。如果有未提交的更改，请停止并要求我先解决这些更改，然后再继续。

• 如果你已经在一个命名分支上，且该分支的 HEAD 与 main 相同，则使用该分支。
• 否则，从 main 创建一个分支，格式为 {author}/rfc-{semantic-name}：

  git branch {author}/rfc-{semantic-name} main
  git checkout {author}/rfc-{semantic-name}
  

工作流

1. 获取并理解 RFC

使用 WebFetch 读取讨论 URL。如果给出的是 GitHub 讨论编号而不是 URL，则构造： https://github.com/remix-run/react-router/discussions/<number>

提取以下内容：

• 要解决的问题：此 RFC 解决了什么痛点？

• 提议的 API：确切的函数签名、hook 名称、类型、选项结构

• 受影响的模式：Declarative / Data / Framework / RSC Data / RSC Framework

• 破坏性变更：此变更是否会修改或移除现有的公开 API？

• 未决问题：任何被明确标记为未解决、"TBD"，或在提案中以问题形式提出的内容

• 状态：是否有链接的跟踪 issue？查找指向其他 github issue 的链接并阅读它们，看看是否有额外的上下文。

  gh issue view <number> --repo remix-run/react-router
  

2. 评估社区反馈

获取讨论中的所有评论：

对 https://github.com/remix-run/react-router/discussions/<number> 使用 WebFetch，并浏览完整的讨论串。查找：

• 社区成员或维护者提出的疑虑或反对意见
• 替代提案或 API 形态建议
• 提案未涉及的边缘情况
• 积极信号——对某个具体方案的反复称赞表明这是正确的方向
• 维护者的回应——Ryan Florence、Michael Jackson 或其他核心团队成员对意图的澄清

将社区意见总结为：

• 共识点（可以安全推进）
• 争议点（实现前需要解决）
• 原始提案中未回答的问题

3. 解决未决问题

在编写任何代码之前，向我呈现一份编号列表，列出所有未解决的问题——包括来自 RFC 本身和来自社区反馈的问题。对于每个问题：

• 清晰地陈述问题
• 总结相关的社区意见
• 给出带有理由的推荐答案

要求我确认、覆盖或跳过每个问题。在所有问题都得到回答或被明确推迟之前，不要进入实现阶段。

示例格式：

## Unresolved Questions

1. **Should `useRouterState()` accept a path argument for scoped matching?**
   Community feedback: 3 comments in favor, 1 against (concerns about complexity).
   Recommendation: Yes — scoped matching improves type safety for nested routes.
   → Your decision: [confirm / override / defer]

2. **What should happen when the path doesn't match the current location?**
   Recommendation: Return `null` for active state (consistent with `useMatch()`).
   → Your decision: [confirm / override / defer]

将已解决的决策保存到暂存文件 tasks/rfc-decisions.md 中，以供实现期间参考。

4. 规划实现

在编写代码之前，产出简明的实现计划，涵盖：

• 要添加的新类型/接口
• 要实现的新函数/hook 及其文件位置
• 要弃用的现有 API（用 @deprecated JSDoc + 开发环境控制台警告标记）
• 是否需要 future flag（见下文 §5）
• 要创建或扩展的测试文件（单元和/或集成）
• Changeset 版本升级级别（新功能用 minor，对于现在默认开启的 future flag 背后的破坏性变更用 major）

将计划呈现给我，并在实现前等待批准。

5. 破坏性变更的 Future Flags

如果 RFC 修改或移除了现有公开 API 行为，则它必须通过 future flag 发布，该 flag 以 unstable_ 前缀开头。

Future flag 模式：

1. 在 packages/react-router/lib/router/utils.ts 中的 FutureConfig 添加该 flag：

   export interface FutureConfig {
     // existing flags...
     unstable_myNewBehavior: boolean;
   }
   

2. 基于该 flag 控制新行为：

   if (router.future.unstable_myNewBehavior) {
     // new behavior
   } else {
     // legacy behavior
   }
   

3. 如果 docs/upgrading/future-flags.md 存在，在该文档中记录该 flag。

新增的增量式 API（不改变现有代码行为）不需要 future flag。

6. 关键文件位置

领域	文件
核心路由逻辑	packages/react-router/lib/router/router.ts
路由类型/工具	packages/react-router/lib/router/utils.ts
React 组件	packages/react-router/lib/components.tsx
React hooks	packages/react-router/lib/hooks.tsx
公共导出	packages/react-router/index.ts
DOM 工具	packages/react-router/lib/dom/
框架/Vite 插件	packages/react-router-dev/vite/plugin.ts
RSC 运行时	packages/react-router/lib/rsc/
单元测试	packages/react-router/__tests__/
集成测试	integration/
未来标志文档	docs/upgrading/future-flags.md

在编写新代码前确认现有模式——优先使用 LSP，但 Grep/Glob 也可以。严格匹配命名约定和代码风格。

7. 实现功能

遵循已批准的计划。对于每个逻辑工作单元：

1. 编写实现
2. 从适当的公共入口点导出（packages/react-router/index.ts）
3. 为任何被取代的 API 添加 @deprecated JSDoc
4. 运行类型检查以尽早捕获类型错误：

   pnpm typecheck
   

保持更改最小且集中。不要重构无关代码。根据需要随时提交。

8. 编写测试

单元测试（针对 hooks、纯路由逻辑、组件行为——无需构建）：

• 位置：packages/react-router/__tests__/
• 运行器：Jest → pnpm test packages/react-router/__tests__/<file>
• 覆盖：正常路径、RFC/社区反馈中识别的边缘情况、未来标志门控（如适用）、弃用警告

集成测试（针对 Vite/框架模式、SSR、水合）：

• 位置：integration/
• 运行器：Playwright → pnpm test:integration:run --project chromium integration/<file>
• 如果 RFC 涉及框架模式、文件系统路由或 SSR 行为，则必需

运行所有测试并确认它们通过：

pnpm test packages/react-router/
pnpm test:integration:run --project chromium  # only if integration tests were added/changed

9. Lint 和类型检查

pnpm lint
pnpm typecheck

在继续之前修复所有错误。

10. 创建变更文件

创建 packages/<package>/.changes/<bump-level>.<descriptive-name>.md。使用 RFC 标题或跟踪问题作为描述：

feat: <brief description matching the RFC title>

Implements the `useRouterState()` RFC (#12358). Deprecates `useLocation`,
`useParams`, `useSearchParams`, `useNavigation`, `useMatches`, `useMatch`,
`useNavigationType`, and `useViewTransitionState` in favor of a unified API.

Enable the `unstable_consolidatedRouterState` future flag to opt in.

Bump 级别：

• patch — 仅 Bug 相邻修复
• minor — 新的增量 API（无破坏性更改）
• major — 破坏性更改（应该很少见；大多数破坏性更改先作为 minor 放在未来标志后面）
• unstable — 尚未稳定的新 API（例如在未来标志中添加，或可能在没有 major bump 的情况下移除的实验性 API）

11. 报告和审查

总结：

• 实现了什么 RFC 以及做出了哪些决定
• 添加的新公共 API（附简要用法示例）
• 弃用的 API 及迁移路径
• 未来标志名称（如适用）以及如何选择加入
• 添加的测试覆盖
• 任何推迟或明确超出范围的内容

在打开 PR 之前，请让我审查并迭代。

12. 提交

一旦我批准，提交并打开 PR 到 main：

gh pr create --base main --title "feat: <RFC title>" --body "..."

PR 正文应包括：

• 链接到 RFC 讨论（Closes 或 Implements #NNNN）
• 实现内容的摘要
• 未来标志说明（如适用）
• 测试说明
• 任何偏离原始提案的决定及原因