base-ui

Base UI

将 Base UI 用作无样式且易于访问的 React 基础组件层。在适配宿主应用的设计系统时，保留语义、焦点、标签、键盘行为和样式钩子。

快照：@base-ui/[email protected]（latest，发布于 2026-09-04；于 2026-10-01 重新验证）。如果项目固定在其他版本，请根据 source-map.md 更新。

工作流

1. 在修改代码前，确认项目中已安装的包及其版本。使用 @base-ui/react，不要使用已弃用的包名 @base-ui-components/react。
2. 实现前先阅读相关参考资料：
   • references/source-map.md：文档来源、包状态、清单，以及 1.7 到 1.8 的差异。
   • references/core-patterns.md：设置、样式、组合、状态、TypeScript、动画、无障碍和实用工具。
   • references/component-patterns.md：按组件系列整理的结构和实现说明。
3. 当具体属性名、事件原因、版本行为或组件 API 至关重要时，获取最新的官方文档。优先查阅已安装包附带的文档（node_modules/@base-ui/react/docs/index.md，与版本匹配），然后查阅 Context7 库 /mui/base-ui，或 https://base-ui.com/llms.txt 中对应页面的 .md URL。
4. 先基于文档中的复合部件构建，再仅通过 render 属性或保留属性与 refs 的轻量封装，包装成本地设计系统组件。
5. 验证键盘行为、焦点返回、无障碍名称、受控／非受控状态、portal 层级、动画退出行为，以及响应式／移动端行为。

实现规则

• 从组件子路径导入，例如 @base-ui/react/dialog、@base-ui/react/combobox 和 @base-ui/react/field。
• 按文档组装各部件。不要自行创造组件、部件或快捷方式。大多数覆盖层都需要 Root、触发器、portal、positioner 或 viewport、popup、标签／标题／描述，以及关闭操作。
• 将 Base UI 视为无样式组件。使用 className、支持状态的 className／style 函数、数据属性和 CSS 变量设置样式。
• 明确设置无障碍名称。使用 Field.Label、组件专用标签、原生标签，或 aria-label／aria-labelledby。
• 自定义 render 元素必须转发 refs，并将收到的所有属性展开到基础 DOM 节点上。
• 除非产品需要外部状态，否则优先使用非受控组件。使用 open／value 配合 onOpenChange／onValueChange 实现受控状态。
• 有意使用事件详情：eventDetails.cancel() 会阻止内部状态更新；eventDetails.allowPropagation() 会让通常会被停止冒泡的 DOM 事件继续冒泡。
• 对于 Combobox ID 选择，使用 Combobox.createItems 和 Combobox.Root.Props<Value, Multiple, Item>。Autocomplete 没有 createItems。
• 不要将仅适用于 Tailwind v4 的语法复制到 Tailwind v3 项目中。
• 如果应用缺少 portal 设置，请补充：隔离应用根节点，并按照核心模式参考资料设置 iOS 26+ 的 body 样式。

验证清单

• 标记使用了预期的角色、标签、禁用／只读状态和焦点可见样式。
• 键盘导航涵盖方向键、Home／End、Enter／Space、Escape、Tab 顺序，以及适用时的焦点返回。
• Popup／抽屉／对话框层显示在应用上方，并可通过触发器、关闭按钮、Escape、外部交互以及路由变化／卸载关闭。
• 表单控件提交预期的名称／值，并显示原生、服务端或外部库的验证错误。
• 动画正确使用 data-starting-style／data-ending-style 或 keepMounted；减少动画或无动画时仍可正常使用。
• TypeScript 封装提供正确的 Component.Part.Props 类型（包括 Combobox 的第三个泛型 Item），且不会丢失 refs、处理器或数据属性。