x-next 1.10.1 → 1.11.0

package/AI_CODING.md

@@ -0,0 +1,97 @@
+# x-next AI Coding 使用规范
+
+本规范供业务仓库的 AI Coding Agent 与协作者使用。x-next 是 Vue 3 + TypeScript 组件库；模型没有预先学过它也可以通过已安装包的手册、公开类型和可运行示例完成接入。
+
+本文件规定查阅和交付流程，实际 API 与可复制 SFC 在独立的 `AI_USAGE/` 中。先读 `AI_USAGE/index.md` 与 `core.md`，再读目标组件/场景。内容从已校验的完整手册生成，保留同版本约束，不需要特定 MCP、插件或付费工具；文档站组件说明保持完整。
+
+## 建立项目入口
+
+将下方推荐段落合并到业务仓库根目录或前端目录的 `AGENTS.md`，保留项目既有端口、登录、验证与业务范围约定。Codex 按项目路径发现 AGENTS 指令；安装 npm 包不会自动把 `node_modules` 中的本规范加入所有 AI 工具的上下文。其他工具在其项目规则入口显式引用即可。
+
+在实际安装 x-next 的前端工作目录执行：
+
+```bash
+node -p "require('x-next/package.json').version"
+node -p "require.resolve('x-next/AI_CODING.md')"
+node -p "require.resolve('x-next/AI_USAGE/index.md')"
+node -p "require.resolve('x-next/AI_USAGE/components/select.md')"
+```
+
+旧版未提供独立目录时，定位其 `AI_USAGE.md` 后按章节读取；该完整文件继续兼容提供，新任务不默认读取。不要把仓库开发版本当成已安装版本，也不要在规则中固定手册覆盖数或个人机器绝对路径。模型无法读取本地文件时，由协作者提供安装版本和本任务所需组件页。
+
+## 可复制到 AGENTS.md 的推荐段落
+
+下面是一段独立可用的消费规则；本文件其余部分用于解释验证和同团队协作。
+
+```markdown
+## x-next 组件使用
+
+- 修改 x-next 组件调用、命令式服务，或准备新增通用 UI 控件时，先从实际前端目录用 `require.resolve('x-next/AI_USAGE/index.md')` 定位独立 AI 入口，并读取 `x-next/package.json` 确认安装版本。纯后端、文案或不涉及组件 API 的改动无需读取。
+- 初次接入读 AI_USAGE/index.md 和 core.md，再只读所需 components/*.md 或 recipes/*.md；组件页包含真实说明、模型/事件/样式和完整 SFC，要保留行为限制。不要把完整 AI_USAGE.md 或整个目录加入上下文，也不要把内容全集复制到 AGENTS.md。旧包没有独立目录时才按标题/行段读取原完整手册。
+- 已读内容仍在当前上下文，且安装包及相关本地构建未变时，不重复读取；升级、软链 dist 重建、遇到新 API 或上下文压缩后丢失具体契约时，补读受影响章节。在任务交接中记录版本、相关组件和已查依据。
+- 以同版本 AI 内容、公开 `.d.ts` 和实际加载实现为依据，不套用 Arco/AntDV/Element 的 prop、v-model、事件载荷或服务方法。精选页没有某组件时，查 AI_USAGE/catalog.md 中的公开导出/类型及组件文档，不能据此认定组件不存在；缺什么补查什么，不猜 API。
+- 使用局部具名导入后，模板用对应局部名称；仅 import 不会全局注册 `<x-*>`。根 `Dialog` 是服务，模板组件为 `DialogComponent`。原生属性、受控值、清空值、事件、插槽和实例方法逐项查实际契约，不用未知 attrs、any、ts-ignore 或关闭严格模板检查掩盖错误。
+- 样式遵循项目已有方案：全量样式或所需组件的公开按需入口。路径查手册，不按组件名猜；旧版的内部样式依赖按其版本核实。通过 props、slots、公开主题变量定制，不在业务侧 patch 组件内部实现，不依赖内部结构类名。
+- 只在需求范围内选组件，不自动迁移既有原生 table、输入框或编辑器交互。手写通用控件前先查库现有能力；深度绑定编辑器状态的块手柄、斜杠菜单等保留在编辑器。
+- 运行项目既有严格类型、构建及相关测试。UI 行为用可用的真实浏览器工具验证，先读页面结构/可访问性树，视觉问题再截图；鼠标、键盘等操作后检查事件和业务状态。不能用 HTTP 成功、脚本注入状态或单测通过代替宿主 UI 结论。
+- 发现缺陷或通用能力缺口，记录消费版本、最小复现、源码/类型依据、期望行为、临时处理和验收步骤，按团队职责反馈或进入库侧修复。升级后逐项复测旧问题，说明实际消费内容和业务回归结果。
+```
+
+这段规则把模型的默认动作改成“定位当前版本 → 检索章节 → 核实 API → 写代码 → 验收”。它不要求模型事先知道 x-next，也不要求仅因规则存在就扩大组件迁移范围。
+
+## 按任务查阅和验证
+
+新包使用下面这几个独立路径：
+
+| 文件 | 用途 | 读取时机 |
+| --- | --- | --- |
+| AI_USAGE/index.md | 短检索入口与路径 | 首次接入 / 新任务找能力 |
+| AI_USAGE/core.md | 安装、样式、受控值、原生属性、弹层与服务规则 | 首次接入 / 规则遗失 |
+| AI_USAGE/components/select.md 等 | 真实 API 约束、完整 SFC、样式依赖 | 任务涉及该组件 |
+| AI_USAGE/recipes/form-on-demand.md | 完整组合代码 | 需要该组合 |
+| AI_USAGE/catalog.md | 更多公共组件/服务和类型定位 | 精选页没有所需能力 |
+| AI_USAGE.md | 完整兼容手册 | 旧版回退或有明确全文需求 |
+
+编辑用户弹窗通常读取 Dialog、Input、Select 的组件页；涉及精选内容未展开的 Form，再通过 catalog 查其公开类型和组件文档。API 不确定时先补查，避免先照熟悉的组件库写一遍再试错。
+
+只有旧包没有独立目录时，才检索完整手册标题并输出所需一节：
+
+```bash
+x_next_ai_handbook="$(node -p "require.resolve('x-next/AI_USAGE.md')")"
+rg -n '^## ' "$x_next_ai_handbook"
+awk '$0 == "## Select" { reading = 1; print; next } reading && /^## / { exit } reading { print }' "$x_next_ai_handbook"
+```
+
+检索工具在本机扫描文件不等于把全文交给模型；上面只有标题和目标章节进入工具输出。提供给聊天模型的内容同样按目标页面裁剪，包含必要的通用规则。
+
+独立小文件让默认读取目标更明确，同时用项目 AGENTS 指明阅读顺序。规则仍不能保证所有 Agent 都遵守或 API 绝不出错；核对读取路径，保留通用与跨组件约束，并验证生成代码，不把“已读资料”代替验收。
+
+检查范围由行为决定：新增点击要追到回调和上层状态；表单检查原生属性落点、校验和提交；选择器检查打开/关闭、选择/取消、清空、禁用、空态与加载；弹层检查焦点、Escape、宿主、滚动与卸载；服务检查句柄和页面清理。无需为未涉及的组件跑全库 UI。
+
+真实浏览器验证优先用环境可用的浏览器连接器，缺失时使用可用的 Computer Use。区分通过浏览器 API 执行真实输入与直接修改 DOM/应用状态；也区分组件测试、独立生产消费页和宿主业务 E2E。工具缺失或某层未执行时写明范围，保留已完成的类型/构建结果。
+
+Playwright 官方 `locator.fill()` 会触发 `input`；需要逐键事件时使用 `pressSequentially()`，或当前连接器支持的真实键盘输入。页面或连接器出现异常时，先检查输入值、事件、Vue 状态与实际工具行为，不能把“fill 不触发 Vue input”作为通用规则。无需用 `force` 或注入状态让验收表面通过。
+
+## 同团队维护库时的补充规则
+
+YWiki、ycms 等明确由同团队维护 x-next 的项目，可再合并下面两段到自身 AGENTS.md：
+
+```markdown
+x-next 是本团队维护的组件库。发现库缺陷或适合复用的能力缺口，在本项目 `x-next问题收集/` 记录后进入库仓库，先读库侧 AGENTS.md，修复、构建、更新手册并回归，再回业务仓库更新依赖和验收。交付说明两个仓库的改动；深度耦合编辑器/业务状态的能力保留在业务侧。
+
+Git 提交 npm 依赖与锁文件；个人软链调试不提交相邻目录 link/override。联调先完成库构建再开浏览器；软链 dist 重建会触发消费端 reload。重建后按项目方式重启 Vite（需要时 --force），确认安装版本、包解析路径和实际加载来源，排除旧预构建缓存。升级后复测问题收集中的相关条目。
+```
+
+其他消费项目按自身权限反馈缺陷，不由“使用 x-next”推导出所有项目都有库源码修改权限。localhost/127.0.0.1、端口、登录与存储来源等实测信息写在各业务仓库，库规范不固定这些环境。
+
+## 交付与上下文
+
+交付说明改了哪些业务和库代码、消费版本/加载来源、验证命令与浏览器行为、遗留项。暂时绕过要记录原因和移除条件；发布后的状态仍需消费方实际验证。
+
+任务压缩/交接保留“版本、相关组件、重要契约、已验证结果、下一步”即可。上下文复用和提示缓存取决于具体工具与模型，不保证永久记忆、缓存命中或后续输入免费；精确 token/费用应使用实际 usage，不用文件 KB 或行数推算固定成本。
+
+官方机制参考：
+
+- Codex AGENTS 发现规则：https://developers.openai.com/codex/guides/agents-md
+- OpenAI 提示缓存：https://developers.openai.com/api/docs/guides/prompt-caching
+- Playwright 输入行为：https://playwright.dev/docs/input

package/AI_USAGE/catalog.md

@@ -0,0 +1,111 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# 公开组件与服务导航
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+从当前构建的根公共声明生成，包含 100 个具名组件/服务导出（含子组件和别名，不等于组件族数量）。本页导航不宣称每项有精选示例。运行时仅从 `x-next` 导入，不深导入这些声明路径；未列出的 hooks、指令和类型继续查 [公共入口声明](../dist/index.d.ts)。
+
+| 导出 | 形式 | 用法覆盖 | 类型导航 | 样式导航 | 完整文档 |
+| --- | --- | --- | --- | --- | --- |
+| Alert | 组件 | [精选用法](./components/alert.md) | [公开声明](../dist/components/alert/index.d.ts) | x-next/style/alert | [文档](https://x-next.yjmf.com/components/alert) |
+| BarChart | 组件 | [精选用法](./components/bar-chart.md) | [公开声明](../dist/components/bar-chart/index.d.ts) | x-next/style/bar-chart | [文档](https://x-next.yjmf.com/components/bar-chart) |
+| Button | 组件 | [精选用法](./components/button.md) | [公开声明](../dist/components/button/index.d.ts) | x-next/style/button | [文档](https://x-next.yjmf.com/components/button) |
+| ButtonGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/button/index.d.ts) | x-next/style/button | [文档](https://x-next.yjmf.com/components/button) |
+| Checkbox | 组件 | [精选用法](./components/checkbox.md) | [公开声明](../dist/components/form-checkbox/index.d.ts) | x-next/style/form-checkbox | [文档](https://x-next.yjmf.com/components/checkbox) |
+| CheckboxGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-checkbox/index.d.ts) | x-next/style/form-checkbox | [文档](https://x-next.yjmf.com/components/checkbox) |
+| Col | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/grid/index.d.ts) | x-next/style/grid | [文档](https://x-next.yjmf.com/components/grid) |
+| ColorPicker | 组件 | [精选用法](./components/color-picker.md) | [公开声明](../dist/components/color-picker/index.d.ts) | x-next/style/color-picker | [文档](https://x-next.yjmf.com/components/color-picker) |
+| ConfigProvider | 组件 | [精选用法](./components/config-provider.md) | [公开声明](../dist/components/config-provider/index.d.ts) | x-next/style/base.css | [文档](https://x-next.yjmf.com/components/config-provider) |
+| DatePicker | 组件 | [精选用法](./components/date-picker.md) | [公开声明](../dist/components/date-picker/index.d.ts) | x-next/style/date-picker | [文档](https://x-next.yjmf.com/components/date-picker) |
+| Dialog | 服务 | [精选用法](./components/dialog.md) | [公开声明](../dist/components/dialog/use.d.ts) | x-next/style/dialog | [文档](https://x-next.yjmf.com/components/dialog) |
+| DialogComponent | 组件 | [精选用法](./components/dialog.md) | [公开声明](../dist/components/dialog/index.d.ts) | x-next/style/dialog | [文档](https://x-next.yjmf.com/components/dialog) |
+| Draggable | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/draggable/index.d.ts) | 按同版本组件文档核实 | [文档](https://x-next.yjmf.com/components/draggable) |
+| Drawer | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/drawer/index.d.ts) | x-next/style/drawer | [文档](https://x-next.yjmf.com/components/drawer) |
+| Dropdown | 组件 | [精选用法](./components/dropdown.md) | [公开声明](../dist/components/dropdown/index.d.ts) | x-next/style/dropdown | [文档](https://x-next.yjmf.com/components/dropdown) |
+| DropdownButton | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/dropdown/index.d.ts) | x-next/style/dropdown | [文档](https://x-next.yjmf.com/components/dropdown) |
+| DropdownGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/dropdown/index.d.ts) | x-next/style/dropdown | [文档](https://x-next.yjmf.com/components/dropdown) |
+| DropdownOption | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/dropdown/index.d.ts) | x-next/style/dropdown | [文档](https://x-next.yjmf.com/components/dropdown) |
+| DropdownSubmenu | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/dropdown/index.d.ts) | x-next/style/dropdown | [文档](https://x-next.yjmf.com/components/dropdown) |
+| Empty | 组件 | [精选用法](./components/empty.md) | [公开声明](../dist/components/empty/index.d.ts) | x-next/style/empty | [文档](https://x-next.yjmf.com/components/empty) |
+| Form | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form/index.d.ts) | x-next/style/form | [文档](https://x-next.yjmf.com/components/form) |
+| FormItem | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form/index.d.ts) | x-next/style/form | [文档](https://x-next.yjmf.com/components/form) |
+| Grid | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/grid/index.d.ts) | x-next/style/grid | [文档](https://x-next.yjmf.com/components/grid) |
+| GridItem | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/grid/index.d.ts) | x-next/style/grid | [文档](https://x-next.yjmf.com/components/grid) |
+| Heatmap | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/heatmap/index.d.ts) | x-next/style/heatmap | [文档](https://x-next.yjmf.com/components/heatmap) |
+| Icon | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/icons/index.d.ts) | 按同版本组件文档核实 | [文档](https://x-next.yjmf.com/components/icon) |
+| Image | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/image/index.d.ts) | x-next/style/image | [文档](https://x-next.yjmf.com/components/image) |
+| ImagePreview | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/image/index.d.ts) | x-next/style/image | [文档](https://x-next.yjmf.com/components/image) |
+| ImagePreviewAction | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/image/index.d.ts) | x-next/style/image | [文档](https://x-next.yjmf.com/components/image) |
+| ImagePreviewGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/image/index.d.ts) | x-next/style/image | [文档](https://x-next.yjmf.com/components/image) |
+| Input | 组件 | [精选用法](./components/input.md) | [公开声明](../dist/components/form-input/index.d.ts) | x-next/style/form-input | [文档](https://x-next.yjmf.com/components/input) |
+| InputGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-input/index.d.ts) | x-next/style/form-input | [文档](https://x-next.yjmf.com/components/input) |
+| InputNumber | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-input-number/index.d.ts) | x-next/style/form-input-number | [文档](https://x-next.yjmf.com/components/input-number) |
+| InputPassword | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-input/index.d.ts) | x-next/style/form-input | [文档](https://x-next.yjmf.com/components/input) |
+| InputSearch | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-input/index.d.ts) | x-next/style/form-input | [文档](https://x-next.yjmf.com/components/input) |
+| InputTag | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-input-tag/index.d.ts) | x-next/style/form-input-tag | [文档](https://x-next.yjmf.com/components/input-tag) |
+| Layout | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/layout/index.d.ts) | x-next/style/layout | [文档](https://x-next.yjmf.com/components/layout) |
+| LayoutSidebar | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/layout/index.d.ts) | x-next/style/layout | [文档](https://x-next.yjmf.com/components/layout) |
+| LineChart | 组件 | [精选用法](./components/line-chart.md) | [公开声明](../dist/components/line-chart/index.d.ts) | x-next/style/line-chart | [文档](https://x-next.yjmf.com/components/line-chart) |
+| Link | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/link/index.d.ts) | x-next/style/link | [文档](https://x-next.yjmf.com/components/link) |
+| Menu | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/menu/index.d.ts) | x-next/style/menu | [文档](https://x-next.yjmf.com/components/menu) |
+| MenuItem | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/menu/index.d.ts) | x-next/style/menu | [文档](https://x-next.yjmf.com/components/menu) |
+| MenuItemGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/menu/index.d.ts) | x-next/style/menu | [文档](https://x-next.yjmf.com/components/menu) |
+| MenuSubMenu | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/menu/index.d.ts) | x-next/style/menu | [文档](https://x-next.yjmf.com/components/menu) |
+| Message | 服务 | [精选用法](./components/message.md) | [公开声明](../dist/components/message/warp.d.ts) | x-next/style/message | [文档](https://x-next.yjmf.com/components/message) |
+| MessageBox | 服务 | [精选用法](./components/message-box.md) | [公开声明](../dist/components/message-box/MessageBox.d.ts) | x-next/style/message-box | [文档](https://x-next.yjmf.com/components/message-box) |
+| MessageComponent | 组件 | [精选用法](./components/message.md) | [公开声明](../dist/components/message/index.d.ts) | x-next/style/message | [文档](https://x-next.yjmf.com/components/message) |
+| MonthPicker | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/date-picker/index.d.ts) | x-next/style/date-picker | [文档](https://x-next.yjmf.com/components/date-picker) |
+| Network | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/network/index.d.ts) | x-next/style/network | [文档](https://x-next.yjmf.com/components/network) |
+| Notification | 服务 | [精选用法](./components/notification.md) | [公开声明](../dist/components/notification/warp.d.ts) | x-next/style/notification | [文档](https://x-next.yjmf.com/components/notification) |
+| NotificationComponent | 组件 | [精选用法](./components/notification.md) | [公开声明](../dist/components/notification/index.d.ts) | x-next/style/notification | [文档](https://x-next.yjmf.com/components/notification) |
+| Pagination | 组件 | [精选用法](./components/pagination.md) | [公开声明](../dist/components/pagination/index.d.ts) | x-next/style/pagination | [文档](https://x-next.yjmf.com/components/pagination) |
+| PieChart | 组件 | [精选用法](./components/pie-chart.md) | [公开声明](../dist/components/pie-chart/index.d.ts) | x-next/style/pie-chart | [文档](https://x-next.yjmf.com/components/pie-chart) |
+| Popconfirm | 组件 | [精选用法](./components/popconfirm.md) | [公开声明](../dist/components/popconfirm/index.d.ts) | x-next/style/popconfirm | [文档](https://x-next.yjmf.com/components/popconfirm) |
+| Popover | 组件 | [精选用法](./components/popover.md) | [公开声明](../dist/components/popover/index.d.ts) | x-next/style/popover | [文档](https://x-next.yjmf.com/components/popover) |
+| Popup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/popup/index.d.ts) | x-next/style/popup | [文档](https://x-next.yjmf.com/components/popup) |
+| Progress | 组件 | [精选用法](./components/progress.md) | [公开声明](../dist/components/progress/index.d.ts) | x-next/style/progress | [文档](https://x-next.yjmf.com/components/progress) |
+| QuarterPicker | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/date-picker/index.d.ts) | x-next/style/date-picker | [文档](https://x-next.yjmf.com/components/date-picker) |
+| Radio | 组件 | [精选用法](./components/radio.md) | [公开声明](../dist/components/form-radio/index.d.ts) | x-next/style/form-radio | [文档](https://x-next.yjmf.com/components/radio) |
+| RadioGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-radio/index.d.ts) | x-next/style/form-radio | [文档](https://x-next.yjmf.com/components/radio) |
+| RangePicker | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/date-picker/index.d.ts) | x-next/style/date-picker | [文档](https://x-next.yjmf.com/components/date-picker) |
+| Rate | 组件 | [精选用法](./components/rate.md) | [公开声明](../dist/components/rate/index.d.ts) | x-next/style/rate | [文档](https://x-next.yjmf.com/components/rate) |
+| ResizeBox | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/resize-box/index.d.ts) | x-next/style/resize-box | [文档](https://x-next.yjmf.com/components/resize-box) |
+| Row | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/grid/index.d.ts) | x-next/style/grid | [文档](https://x-next.yjmf.com/components/grid) |
+| Scrollbar | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/scrollbar-v2/index.d.ts) | x-next/style/scrollbar-v2 | [文档](https://x-next.yjmf.com/components/scrollbar) |
+| Select | 组件 | [精选用法](./components/select.md) | [公开声明](../dist/components/form-select/index.d.ts) | x-next/style/form-select | [文档](https://x-next.yjmf.com/components/select) |
+| SelectDropdown | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-select/index.d.ts) | x-next/style/form-select | [文档](https://x-next.yjmf.com/components/select) |
+| SelectOption | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-select/index.d.ts) | x-next/style/form-select | [文档](https://x-next.yjmf.com/components/select) |
+| SelectOptionGroup | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/form-select/index.d.ts) | x-next/style/form-select | [文档](https://x-next.yjmf.com/components/select) |
+| Skeleton | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/skeleton/index.d.ts) | x-next/style/skeleton | [文档](https://x-next.yjmf.com/components/skeleton) |
+| SkeletonLine | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/skeleton/index.d.ts) | x-next/style/skeleton | [文档](https://x-next.yjmf.com/components/skeleton) |
+| SkeletonShape | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/skeleton/index.d.ts) | x-next/style/skeleton | [文档](https://x-next.yjmf.com/components/skeleton) |
+| Slider | 组件 | [精选用法](./components/slider.md) | [公开声明](../dist/components/form-slider/index.d.ts) | x-next/style/form-slider | [文档](https://x-next.yjmf.com/components/slider) |
+| Space | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/space/index.d.ts) | x-next/style/space | [文档](https://x-next.yjmf.com/components/space) |
+| Spin | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/spin/index.d.ts) | x-next/style/spin | [文档](https://x-next.yjmf.com/components/spin) |
+| Step | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/steps/index.d.ts) | x-next/style/steps | [文档](https://x-next.yjmf.com/components/steps) |
+| Steps | 组件 | [精选用法](./components/steps.md) | [公开声明](../dist/components/steps/index.d.ts) | x-next/style/steps | [文档](https://x-next.yjmf.com/components/steps) |
+| Switch | 组件 | [精选用法](./components/switch.md) | [公开声明](../dist/components/form-switch/index.d.ts) | x-next/style/form-switch | [文档](https://x-next.yjmf.com/components/switch) |
+| Table | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/table/index.d.ts) | x-next/style/table | [文档](https://x-next.yjmf.com/components/table) |
+| TableColumn | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/table/index.d.ts) | x-next/style/table | [文档](https://x-next.yjmf.com/components/table) |
+| TabPane | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/tabs/index.d.ts) | x-next/style/tabs | [文档](https://x-next.yjmf.com/components/tabs) |
+| Tabs | 组件 | [精选用法](./components/tabs.md) | [公开声明](../dist/components/tabs/index.d.ts) | x-next/style/tabs | [文档](https://x-next.yjmf.com/components/tabs) |
+| Tag | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/tag/index.d.ts) | x-next/style/tag | [文档](https://x-next.yjmf.com/components/tag) |
+| Tbody | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/table/table-tbody.d.ts) | x-next/style/table | [文档](https://x-next.yjmf.com/components/table) |
+| Td | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/table/table-td.d.ts) | x-next/style/table | [文档](https://x-next.yjmf.com/components/table) |
+| Textarea | 组件 | [精选用法](./components/textarea.md) | [公开声明](../dist/components/form-textarea/index.d.ts) | x-next/style/form-textarea | [文档](https://x-next.yjmf.com/components/textarea) |
+| Th | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/table/table-th.d.ts) | x-next/style/table | [文档](https://x-next.yjmf.com/components/table) |
+| Thead | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/table/table-thead.d.ts) | x-next/style/table | [文档](https://x-next.yjmf.com/components/table) |
+| Timeline | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/timeline/index.d.ts) | x-next/style/timeline | [文档](https://x-next.yjmf.com/components/timeline) |
+| TimelineItem | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/timeline-item/index.d.ts) | 按同版本组件文档核实 | [文档](https://x-next.yjmf.com/components/timeline) |
+| TimePicker | 组件 | [精选用法](./components/time-picker.md) | [公开声明](../dist/components/time-picker/index.d.ts) | x-next/style/time-picker | [文档](https://x-next.yjmf.com/components/time-picker) |
+| TimeRangeSelector | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/time-range-selector/index.d.ts) | x-next/style/time-range-selector | [文档](https://x-next.yjmf.com/components/time-range-selector) |
+| Tooltip | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/tooltip/index.d.ts) | x-next/style/tooltip | [文档](https://x-next.yjmf.com/components/tooltip) |
+| Tr | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/table/table-tr.d.ts) | x-next/style/table | [文档](https://x-next.yjmf.com/components/table) |
+| TrendChart | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/trend-chart/index.d.ts) | 按同版本组件文档核实 | [文档](https://x-next.yjmf.com/components/trend-chart) |
+| Trigger | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/trigger/index.d.ts) | x-next/style/trigger | [文档](https://x-next.yjmf.com/components/trigger) |
+| Upload | 组件 | [精选用法](./components/upload.md) | [公开声明](../dist/components/upload/index.d.ts) | x-next/style/upload | [文档](https://x-next.yjmf.com/components/upload) |
+| Watermark | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/watermark/index.d.ts) | x-next/style/watermark | [文档](https://x-next.yjmf.com/components/watermark) |
+| WeekPicker | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/date-picker/index.d.ts) | x-next/style/date-picker | [文档](https://x-next.yjmf.com/components/date-picker) |
+| YearPicker | 组件 | 未展开精选用法；核对公开类型 | [公开声明](../dist/components/date-picker/index.d.ts) | x-next/style/date-picker | [文档](https://x-next.yjmf.com/components/date-picker) |
+
+服务/组件别名以根入口为准；Form、Table 等未展开能力存在于目录，先核对类型和对应文档，不套用其他库 API。

package/AI_USAGE/components/alert.md

@@ -0,0 +1,33 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Alert AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Alert`；模型：v-model:visible；已核对事件：close。
+
+按需样式：`x-next/style/alert`（包含 base.css、alert.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/alert)。用 `v-model:visible` 控制显示；`defaultVisible=true`、`type='info'`、`showIcon=true`、`closable=false`。常用类型为 info、success、warning、error、normal。
+
+`close(event)` 返回 `MouseEvent`，`after-close` 在关闭动画结束后触发且无参数。默认插槽放正文，`title` / `icon` / `action` / `close-element` 插槽可自定义对应内容。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Alert, Button } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(true);
+const feedback = ref('提示显示中');
+function closed(_event: MouseEvent) { feedback.value = '已点击关闭'; }
+function restore() { visible.value = true; feedback.value = '提示显示中'; }
+</script>
+<template>
+  <Alert v-model:visible="visible" type="warning" title="检查待提交内容" closable @close="closed">
+    提交前请核对所选日期。
+  </Alert>
+  <Button @click="restore">重新显示</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/bar-chart.md

@@ -0,0 +1,46 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# BarChart AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`BarChart`；模型：无；已核对事件：barClick、legendChange。
+
+按需样式：`x-next/style/bar-chart`（包含 base.css、bar-chart.css、spin.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/bar-chart)。按天 / 小时聚合的柱状趋势图：`categories` 是类目轴标签，`series` 是数据系列（`{ name, data, color }`），两者按下标对应。单系列就是普通柱状图；多系列默认并排，加 `stack` 变成堆叠并显示合计。轻量迷你走势用 TrendChart，需要坐标轴与读数用本组件。
+
+数值轴自动取 1/2/5 步长的整洁刻度（所以刻度行数可能少于 `grid.horizontalLinesNumber`）；传 `max` 可锁定上界。`loading` 显示加载遮罩；数据全为 0 时显示空态，可用 `empty` 插槽替换。`null` / 负数按 0 处理且不画柱体。
+
+`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`；点击柱体触发 `barClick`，命中具体柱体时带 `seriesIndex` / `value`，未命中时为 `null`。`valueFormatter` 统一控制提示、图例与数值轴的数字格式。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BarChart } from 'x-next';
+import 'x-next/dist/style.css';
+const categories = ref(['09-28', '09-29', '09-30', '10-01', '10-02']);
+const series = ref([
+  { name: '浏览量', data: [86, 142, 98, 210, 176] },
+  { name: '访客数', data: [52, 88, 61, 120, 96] },
+]);
+const picked = ref('尚未选择');
+// 原生属性（含 aria-*）用对象 v-bind 传递，组件 props 与事件仍直接绑定
+const chartAttrs = { 'aria-label': '每日浏览量与访客数' };
+function onBarClick(data: { label: string; total: number; value: number | null }) {
+  picked.value = `${data.label}：合计 ${data.total}`;
+}
+</script>
+<template>
+  <BarChart
+    v-bind="chartAttrs"
+    :categories="categories"
+    :series="series"
+    :height="240"
+    legend
+    @bar-click="onBarClick"
+  />
+  <p role="status">{{ picked }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/button.md

@@ -0,0 +1,35 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Button AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Button`；模型：无；已核对事件：click。
+
+按需样式：`x-next/style/button`（包含 base.css、button.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。独立使用时尺寸回退为 `'medium'`，`disabled` / `loading` 默认关闭。
+
+`click` 载荷为 `MouseEvent`，禁用或加载中不会触发。`default`、`prefix`、`suffix`、`icon` 插槽可组合内容；异步业务自行维护 `loading`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button } from 'x-next';
+import 'x-next/dist/style.css';
+const loading = ref(false);
+const result = ref('尚未保存');
+async function save(_event: MouseEvent) {
+  loading.value = true;
+  try {
+    await Promise.resolve();
+    result.value = '保存完成';
+  } finally { loading.value = false; }
+}
+</script>
+<template>
+  <Button type="primary" html-type="button" :loading="loading" @click="save">保存</Button>
+  <p role="status">{{ result }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/checkbox.md

@@ -0,0 +1,34 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Checkbox AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Checkbox`；模型：v-model；已核对事件：change。
+
+按需样式：`x-next/style/form-checkbox`（包含 base.css、form-checkbox.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/checkbox)。使用普通 `v-model`；模型支持 `boolean` 或 `(string | number | boolean)[]`，数组模式配合 `value`。`defaultChecked`、`disabled`、`indeterminate` 默认 `false`；半选状态不会替代模型值。
+
+`change(value, event)` 返回新值和原生 `Event`。默认插槽是文案，`checkbox` 插槽提供 `checked` / `disabled`。`id`、`name`、`required`、`form`、`tabindex`、`autofocus`、`autocomplete` 和 `aria-*` 传给原生复选框。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Checkbox } from 'x-next';
+import 'x-next/dist/style.css';
+const accepted = ref(false);
+const inputAttrs = { id: 'accept-terms', name: 'terms', required: true };
+const feedback = ref('尚未选择');
+function changed(value: boolean | (string | number | boolean)[], event: Event) {
+  feedback.value = `${value === true ? '已同意' : '未同意'}（${event.type}）`;
+}
+</script>
+<template>
+  <Checkbox v-model="accepted" v-bind="inputAttrs" @change="changed">
+    我已阅读使用说明
+  </Checkbox>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/color-picker.md

@@ -0,0 +1,36 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# ColorPicker AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`ColorPicker`；模型：v-model、v-model:show；已核对事件：change、showChange、clear、confirm。
+
+按需样式：`x-next/style/color-picker`（包含 base.css、color-picker.css、button.css、form-input.css、form-input-number.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/color-picker)。`v-model` 输出 hex 字符串；`v-model:show` 控制面板。清除恢复显式 defaultValue，未提供则提交空字符串；change、clear、confirm 都通知 Form 的 change 通道。自定义触发器将 triggerAttrs 绑定到原生按钮，保留键盘、ARIA、禁用与焦点行为。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ColorPicker } from 'x-next';
+const color = ref('#0f766e');
+const show = ref(false);
+const log = ref('等待操作');
+const pickerAttrs = { id: 'brand-color', 'aria-label': '品牌色' };
+</script>
+
+<template>
+  <ColorPicker v-model="color" v-model:show="show" size="small" v-bind="pickerAttrs"
+    :swatches="['#0f766e', '#1c61ff']"
+    @change="(value) => log = `change: ${value}`"
+    @clear="log = '已清除'"
+    @confirm="(value) => log = `confirm: ${value}`">
+    <template #trigger="{ value, visible, triggerAttrs }">
+      <button v-bind="triggerAttrs">{{ visible ? '选择中' : value }}</button>
+    </template>
+  </ColorPicker>
+  <p role="status">{{ log }}；保存值：{{ color || '空' }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/config-provider.md

@@ -0,0 +1,58 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# ConfigProvider AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`ConfigProvider`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+
+按需样式：`x-next/style/base.css`（包含 base.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+局部品牌色用 `themeColor`，它一次生成色阶并重绑定组件别名；不必逐个覆盖 Button、Switch 的颜色。默认 body 浮层也会同步当前配置；更换 popupContainer 只用于业务定位和裁剪需要。Select 默认跟随祖先滚动；要滚动关闭可传 `triggerProps.scrollToClose`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, ConfigProvider, Select, Switch } from 'x-next';
+
+const brand = ref('#2f6feb');
+const dark = ref(false);
+const value = ref('day');
+const switchAttrs = { 'aria-label': '局部暗色' };
+const selectAttrs = { 'aria-label': '统计粒度' };
+const options = [
+  { label: '按天', value: 'day' },
+  { label: '按周', value: 'week' },
+];
+</script>
+
+<template>
+  <ConfigProvider :theme-color="brand" :dark="dark" class="brand-scope">
+    <Button type="primary" @click="brand = brand === '#2f6feb' ? '#0f766e' : '#2f6feb'">
+      切换品牌色
+    </Button>
+    <Switch v-model="dark" v-bind="switchAttrs" />
+    <Select
+      v-model="value"
+      :options="options"
+      v-bind="selectAttrs"
+      style="width: 160px"
+    />
+  </ConfigProvider>
+</template>
+
+<style scoped>
+.brand-scope {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  color: var(--x-color-text-primary);
+  background: var(--x-color-bg-surface);
+}
+</style>
+```
+
+已有主题容器时，也可调用公开 `applyThemeColor(seed, { target, dark })`；切换暗色后需重新调用。只改后代的几条 semantic CSS 变量不会重算祖先 alias；`:tag="null"` 的 ConfigProvider 不创建本级主题边界，仍继承父级配置。
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/date-picker.md

@@ -0,0 +1,34 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# DatePicker AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`DatePicker`；模型：v-model、v-model:popup-visible；已核对事件：change。
+
+按需样式：`x-next/style/date-picker`（包含 base.css、button.css、date-picker.css、scrollbar-v2.css、time-picker.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/date-picker)。默认 `type='date'`、`allowClear=true`、`showToday=true`、`showTime=false`、`position='bl'`。`format` 控制显示，`valueFormat` 控制输出；本例使用 `'YYYY-MM-DD'` 字符串。公开 `DatePickerModelValue` 还包含数字、Date、数组和 `undefined`。
+
+`change(value, date, dateString)` 为提交值，`select` 是面板选择；后两个参数声明为 `unknown`。清空返回 `undefined`，本例归一化为 `''` 保持受控。支持 `cell` / `extra` / `prefix` / `suffix-icon` 插槽；带时间选择需确认后提交。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DatePicker, type DatePickerModelValue } from 'x-next';
+import 'x-next/dist/style.css';
+const date = ref('');
+const feedback = ref('尚未选择日期');
+function update(value: DatePickerModelValue) { date.value = typeof value === 'string' ? value : ''; }
+function changed(value: DatePickerModelValue, _date: unknown, _text: unknown) {
+  update(value);
+  feedback.value = date.value ? `日期：${date.value}` : '已清空日期';
+}
+</script>
+<template>
+  <DatePicker :model-value="date" value-format="YYYY-MM-DD" placeholder="选择日期"
+    @update:model-value="update" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/dialog.md

@@ -0,0 +1,37 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Dialog AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`DialogComponent, Dialog`；模型：v-model；已核对事件：close、closed。
+
+按需样式：`x-next/style/dialog`（包含 base.css、button.css、dialog.css、space.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/dialog)。从根入口导入 `DialogComponent as XDialog`，普通 `v-model` 为布尔值且默认 `false`。`renderTo='body'`、`mask=true`、`maskToClose=true`、`escToClose=true`、`destroyOnClosed=true`；`width` 支持数字或 CSS 长度。
+
+`title`、默认正文、`footer` 是公开插槽，默认不生成业务按钮。`close(action, event?)` 的 action 为 `'cancel' | 'ok'`，`closed` 表示关闭动画结束；直接改模型不会调用业务取消逻辑。根入口服务 `Dialog(options)` 返回 `close()` / `update(options)` 句柄。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, DialogComponent as XDialog } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('尚未确认');
+function confirm() { feedback.value = '已确认'; visible.value = false; }
+function cancel() { feedback.value = '已取消'; visible.value = false; }
+</script>
+<template>
+  <Button @click="visible = true">打开对话框</Button>
+  <XDialog v-model="visible" title="确认安排" :width="420">
+    <p>核对安排后确认。</p>
+    <template #footer>
+      <Button @click="cancel">取消</Button>
+      <Button type="primary" @click="confirm">确认</Button>
+    </template>
+  </XDialog>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/dropdown.md

@@ -0,0 +1,38 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Dropdown AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Dropdown`；模型：v-model:popup-visible；已核对事件：select、popupVisibleChange。
+
+按需样式：`x-next/style/dropdown`（包含 base.css、button.css、dropdown.css、empty.css、scrollbar-v2.css、spin.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/dropdown)。使用 `v-model:popup-visible`，默认 `trigger='click'`、`position='bottom'`、`hideOnSelect=true`。根入口导出 `DropdownOption`、`DropdownGroup`、`DropdownSubmenu`；菜单内容放 `content` 插槽，另有 `empty` / `footer` 插槽。
+
+`select(value, event)` 返回 `string | number | Record<string, any> | undefined` 和 `Event`，`popup-visible-change` 返回布尔值。选项支持 `disabled`；字符搜索 typeahead、自定义控件的通用键盘代理及 Tab 自动关闭仍有边界，不能据方向键导航推断这些能力已实现。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Dropdown, DropdownOption } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('尚未选择操作');
+function select(value: unknown, _event: Event) {
+  feedback.value = value === 'copy' ? '已选择复制' : '已选择下载';
+}
+</script>
+<template>
+  <Dropdown v-model:popup-visible="visible" @select="select">
+    <Button>更多操作</Button>
+    <template #content>
+      <DropdownOption value="copy">复制</DropdownOption>
+      <DropdownOption value="download">下载</DropdownOption>
+      <DropdownOption value="archive" disabled>归档暂不可用</DropdownOption>
+    </template>
+  </Dropdown>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。