x-next 1.10.0 → 1.11.0

package/AI_USAGE/components/tabs.md

@@ -0,0 +1,33 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Tabs AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Tabs`；模型：v-model:active-key；已核对事件：change。
+
+按需样式：`x-next/style/tabs`（包含 base.css、tabs.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/tabs)。使用 `v-model:active-key`，类型为 `string | number`；TabPane 用 Vue 的 `key` 标识页签，键类型须与模型一致。默认 `type='line'`、`position='top'`、`trigger='click'`、`lazyLoad=false`、`destroyOnHide=false`。
+
+`change(key)` 返回键值，`tab-click(key, event)` 还返回 `Event`。禁用配置放在 TabPane；TabPane 默认插槽放正文，`title` 插槽自定义标题，Tabs 的 `extra` 放额外内容。可编辑模式的 `add` / `delete` 事件需要业务维护页签数据。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Tabs, TabPane } from 'x-next';
+import 'x-next/dist/style.css';
+const active = ref<string | number>('overview');
+const feedback = ref('当前概览');
+function changed(key: string | number) { feedback.value = `当前页签：${key}`; }
+</script>
+<template>
+  <Tabs v-model:active-key="active" @change="changed">
+    <TabPane key="overview" title="概览">查看当前安排。</TabPane>
+    <TabPane key="history" title="历史">查看已完成记录。</TabPane>
+    <TabPane key="restricted" title="未开放" disabled>此内容暂不可选。</TabPane>
+  </Tabs>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/textarea.md

@@ -0,0 +1,31 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Textarea AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Textarea`；模型：v-model；已核对事件：input、change、clear。
+
+按需样式：`x-next/style/form-textarea`（包含 base.css、form-textarea.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/textarea)。`v-model` 为字符串，`input/change/clear` 与输入生命周期联动。原生 id、name、aria、rows、readonly 用 `textareaAttrs`，不支持组件层的 readonly prop；autoSize 控制自动高度。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Textarea } from 'x-next';
+import 'x-next/style/form-textarea';
+const summary = ref('');
+const log = ref('等待输入');
+const nativeAttrs = { id: 'article-summary', name: 'summary', 'aria-label': '文章摘要', rows: 3 };
+const readonlyAttrs = { id: 'saved-summary', name: 'savedSummary', 'aria-label': '只读摘要', readonly: true };
+</script>
+<template>
+  <label for="article-summary">文章摘要</label>
+  <Textarea v-model="summary" :textarea-attrs="nativeAttrs" :auto-size="{ minRows: 3, maxRows: 6 }"
+    @input="value => log = `input: ${value}`" />
+  <Textarea model-value="已保存的摘要" :textarea-attrs="readonlyAttrs" />
+  <p role="status">{{ log }}；当前值：{{ summary }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/time-picker.md

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

package/AI_USAGE/components/upload.md

@@ -0,0 +1,60 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Upload AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Upload`；模型：v-model:file-list；已核对事件：change、success、error、remove、exceed、reject、progress。
+
+按需样式：`x-next/style/upload`（包含 base.css、image.css、progress.css、trigger.css、tooltip.css、upload.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/upload)。`action` 是上传地址，也可用 `customRequest` 接管请求；两者都没提供时组件不会发起上传。`name` 是 FormData 字段名，默认 `'file'`；`method` 默认 `'post'`，`withCredentials` 默认 `false`。
+
+**接入已有上传方法的推荐写法**：`customRequest` 返回 Promise 时组件自动接管状态，resolve 即成功（结果写入 `file.response`，可用 `responseUrlKey` 提取 url，字符串支持 `data.url` 嵌套路径）、reject 即失败并出现重试入口，无需手动调用 `onSuccess` / `onError`。axios、flyio、fetch 或任何返回 Promise 的方法都适用。返回值是 fetch `Response` 时组件读取响应体；非 2xx 按失败处理，`error.status` 为状态码。需要进度与取消时，把 option 的 `signal`（取消 / 移除 / 卸载时触发）与 `onProgress`（0 ~ 1）透传给底层请求。返回 `{ abort }` 并手动回调的旧写法仍然支持。
+
+列表默认非受控，用 `defaultFileList` 给初值；需要外部驱动时用 `v-model:file-list`，列表项以 `uid` 为稳定标识。`listType` 取 `'text' | 'picture' | 'picture-card'`。`limit` 为数量上限，超出会触发 `exceed`，超出部分不进入列表；`beforeUpload` 返回 `false` 拦截、返回新 `File` 替换，支持 Promise。
+
+`change({ file, fileList })` 覆盖加入、进度、成功、失败和移除；`success` / `error` / `remove` / `progress` 是更细粒度的补充。`autoUpload=false` 时文件先以 `init` 入列，再用组件 `submit()` 上传、`abort()` 取消、`retry()` 重试。图片卡场景可加 `image-preview` 用内置 `ImagePreview` 看图。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Upload, type UploadFile } from 'x-next';
+import 'x-next/dist/style.css';
+const fileList = ref<UploadFile[]>([]);
+const status = ref('尚未选择文件');
+// 项目里已封装好的上传方法：返回 Promise 即可，组件自动显示成功与失败
+function uploadAttachment(params: { file: File; orderId: string }) {
+  const form = new FormData();
+  form.append('file', params.file);
+  form.append('orderId', params.orderId);
+  return fetch('/api/upload', { method: 'POST', body: form }).then((response) => {
+    if (!response.ok) throw new Error(`上传失败：${response.status}`);
+    return response.json() as Promise<{ data: { url: string } }>;
+  });
+}
+function changed(info: { file: UploadFile; fileList: UploadFile[] }) {
+  status.value = `${info.file.name}：${info.file.status ?? 'unknown'}`;
+}
+function beforeUpload(file: File) {
+  // 超过 2MB 直接拦截，文件不会进入列表
+  return file.size <= 2 * 1024 * 1024;
+}
+</script>
+<template>
+  <Upload
+    v-model:file-list="fileList"
+    :custom-request="({ file }) => uploadAttachment({ file, orderId: 'SO-20261003' })"
+    response-url-key="data.url"
+    name="file"
+    multiple
+    list-type="picture"
+    accept="image/*"
+    :limit="5"
+    :before-upload="beforeUpload"
+    @change="changed"
+  />
+  <p role="status">{{ status }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/core.md

@@ -0,0 +1,37 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# x-next AI 通用接入
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+```sh
+npm install x-next
+```
+
+应用需已有 Vue 3、TypeScript 和 Vue SFC 构建支持。按需具名导入无需安装全局插件；在 `main.ts` 引入一次样式：
+
+```ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import 'x-next/dist/style.css';
+
+createApp(App).mount('#app');
+```
+
+下方各节使用局部具名导入。需要全局注册时可另用 `app.use(XNext)`（默认导出），它会注册全部组件。根入口的 `Dialog` 是命令式服务，模板组件是 `DialogComponent`；MessageBox 使用服务函数。
+
+接入时遵循这些约定：
+
+- **按组件路由传原生属性**：Checkbox / Select 用已核实的 `id/name/aria-*` 属性对象 `v-bind`；Input 用 `inputAttrs`，Textarea 用 `textareaAttrs`。Textarea 的 readonly 也放在 `textareaAttrs` 中。组件 props 和事件直接绑定，不把未知组件 API 塞进 attrs。
+- **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。非受控初始化用 `defaultValue` / `defaultChecked`；把受控值改成 `undefined` 可能切换到内部状态。清空日期、时间统一保存 `''`。
+- **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 用 `renderTo`。容器须已挂载；局部容器要留意定位、滚动和裁剪。ConfigProvider 的主题会同步到 Trigger 浮层及组件形态 Dialog / Drawer；单独调用 applyThemeColor 或独立创建命令式实例时，仍需按实际 DOM 宿主处理主题。
+- **优先用公开主题变量**：参考[样式与主题](https://x-next.yjmf.com/guide/theme)。暗色容器上的 alias 链会重新声明；`themeColor` 写入的内联 primary alias 有覆盖边界，按主题文档设置相关公开 alias。
+- **约束业务全局 CSS**：reset 用 `:where(...)` 降低优先级并限定作用域；宽泛的原生元素选择器可能覆盖组件样式。自定义内容用插槽和公开属性，不依赖内部结构类名。
+- **清理页面创建的服务**：保留句柄，在路由页面卸载时调用 `close()`；KeepAlive 页面可在停用时清理。Dialog / MessageBox 的命令式关闭不触发确认、取消回调，业务取消逻辑需自行调用；Message / Notification 的关闭会触发各自的 `onClose`。
+
+## 按需样式
+
+使用无扩展名的公开 JS 样式入口，例如 `x-next/style/form-select`。它自动引入共享 base、Select 自身及 Trigger、Scrollbar、Empty、Spin、Checkbox 的 CSS；业务不需要逐个维护内部依赖。多个入口由打包器按文件去重。Input / Textarea 的样式路径分别是 `form-input` / `form-textarea`，不要根据组件名猜 `style/input`。
+
+若直接导入 `.css`，需要自己引入 base、自身和全部内部依赖；精选手册索引列出了依赖，发布包 `dist/style/dependencies.json` 提供完整组件映射。全量 `x-next/style.css` 仍可使用。不要同时混用全量与按需方案。
+
+完整组合：[按需表单 SFC](./recipes/form-on-demand.md)。回到 [索引](./index.md) 按需读取组件；已读且仍在上下文、消费内容未变时复用。规则模板在 [AI_CODING.md](../AI_CODING.md)。

package/AI_USAGE/index.md

@@ -0,0 +1,52 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# x-next AI 按需入口
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+AI 专用资料，与文档站独立分发。先读 [core.md](./core.md)，再只读本任务需要的组件页；每页提供真实约束、公共导出、模型/事件/样式和完整 Vue SFC。代码与同版本完整手册同源并严格检查；本索引不塞入完整示例。
+
+用 `require.resolve('x-next/AI_USAGE/index.md')` 定位本页，组件例如 `require.resolve('x-next/AI_USAGE/components/select.md')`。升级或本地 dist 重建后重新核对；文件不会被所有工具自动加载，消费项目须合并 [AI_CODING.md](../AI_CODING.md) 中的 AGENTS 建议。
+
+## 组件检索
+
+| 组件/服务 | 按需内容 | 模型 | 样式入口 |
+| --- | --- | --- | --- |
+| ConfigProvider | [config-provider](./components/config-provider.md) | 无 | `x-next/style/base.css` |
+| ColorPicker | [color-picker](./components/color-picker.md) | v-model、v-model:show | `x-next/style/color-picker` |
+| Button | [button](./components/button.md) | 无 | `x-next/style/button` |
+| Input | [input](./components/input.md) | v-model | `x-next/style/form-input` |
+| Textarea | [textarea](./components/textarea.md) | v-model | `x-next/style/form-textarea` |
+| Checkbox | [checkbox](./components/checkbox.md) | v-model | `x-next/style/form-checkbox` |
+| Radio | [radio](./components/radio.md) | v-model | `x-next/style/form-radio` |
+| Select | [select](./components/select.md) | v-model、v-model:popup-visible | `x-next/style/form-select` |
+| Slider | [slider](./components/slider.md) | v-model | `x-next/style/form-slider` |
+| Rate | [rate](./components/rate.md) | v-model | `x-next/style/rate` |
+| Switch | [switch](./components/switch.md) | v-model | `x-next/style/form-switch` |
+| DatePicker | [date-picker](./components/date-picker.md) | v-model、v-model:popup-visible | `x-next/style/date-picker` |
+| TimePicker | [time-picker](./components/time-picker.md) | v-model、v-model:popup-visible | `x-next/style/time-picker` |
+| Alert | [alert](./components/alert.md) | v-model:visible | `x-next/style/alert` |
+| Dialog | [dialog](./components/dialog.md) | v-model | `x-next/style/dialog` |
+| Message | [message](./components/message.md) | 无 | `x-next/style/message` |
+| MessageBox | [message-box](./components/message-box.md) | 无 | `x-next/style/message-box` |
+| Notification | [notification](./components/notification.md) | 无 | `x-next/style/notification` |
+| Popconfirm | [popconfirm](./components/popconfirm.md) | v-model | `x-next/style/popconfirm` |
+| Popover | [popover](./components/popover.md) | v-model:popup-visible | `x-next/style/popover` |
+| Progress | [progress](./components/progress.md) | 无 | `x-next/style/progress` |
+| Dropdown | [dropdown](./components/dropdown.md) | v-model:popup-visible | `x-next/style/dropdown` |
+| Pagination | [pagination](./components/pagination.md) | v-model:current、v-model:page-size | `x-next/style/pagination` |
+| Steps | [steps](./components/steps.md) | v-model:current | `x-next/style/steps` |
+| Tabs | [tabs](./components/tabs.md) | v-model:active-key | `x-next/style/tabs` |
+| Empty | [empty](./components/empty.md) | 无 | `x-next/style/empty` |
+| Upload | [upload](./components/upload.md) | v-model:file-list | `x-next/style/upload` |
+| BarChart | [bar-chart](./components/bar-chart.md) | 无 | `x-next/style/bar-chart` |
+| LineChart | [line-chart](./components/line-chart.md) | 无 | `x-next/style/line-chart` |
+| PieChart | [pie-chart](./components/pie-chart.md) | 无 | `x-next/style/pie-chart` |
+
+## 组合和未收录能力
+
+- [按需表单完整 SFC](./recipes/form-on-demand.md)：Input + Textarea + Select + Checkbox + ConfigProvider。
+- 编辑弹窗：读 Dialog、Input、Select；需要 Form 时再查 [公开组件导航](./catalog.md) 中的类型与组件文档。不要因手册缺节就判断没有组件。
+- [公开组件/服务导航](./catalog.md)：更多组件、子组件、别名和声明定位；精选覆盖 30 个契约，不代表全部导出。
+- [完整兼容手册](../AI_USAGE.md)：旧用法保留；新任务不默认读取全文。
+
+按需读取不能保证模型绝不读多或 API 绝不出错。保留通用规则和组件完整约束，并用严格类型、构建及真实浏览器验证；不以“读取过”代替验收。

package/AI_USAGE/recipes/form-on-demand.md

@@ -0,0 +1,42 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# 按需样式与表单接入
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)，相关组件规则：[config-provider](../components/config-provider.md)、[input](../components/input.md)、[textarea](../components/textarea.md)、[select](../components/select.md)、[checkbox](../components/checkbox.md)。
+
+使用无扩展名的公开 JS 样式入口，例如 `x-next/style/form-select`。它自动引入共享 base、Select 自身及 Trigger、Scrollbar、Empty、Spin、Checkbox 的 CSS；业务不需要逐个维护内部依赖。多个入口由打包器按文件去重。Input / Textarea 的样式路径分别是 `form-input` / `form-textarea`，不要根据组件名猜 `style/input`。
+
+若直接导入 `.css`，需要自己引入 base、自身和全部内部依赖；精选手册索引列出了依赖，发布包 `dist/style/dependencies.json` 提供完整组件映射。全量 `x-next/style.css` 仍可使用。不要同时混用全量与按需方案。
+
+下面是可独立复制的按需表单 SFC，原生属性按各组件真实路由传入：
+
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ConfigProvider, Input, Textarea, Select, Checkbox } from 'x-next';
+import 'x-next/style/form-input';
+import 'x-next/style/form-textarea';
+import 'x-next/style/form-select';
+import 'x-next/style/form-checkbox';
+const title = ref('');
+const summary = ref('只读接入说明');
+const scopes = ref<string[]>(['read']);
+const accepted = ref(false);
+const titleAttrs = { id: 'cms-title', name: 'title', 'aria-label': '标题', required: true };
+const summaryAttrs = { id: 'cms-summary', name: 'summary', 'aria-label': '说明', readonly: true };
+const selectAttrs = { id: 'cms-scopes', 'aria-label': '授权范围' };
+const checkboxAttrs = { name: 'agreement', 'aria-label': '同意条款' };
+const options = [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }];
+</script>
+<template>
+  <ConfigProvider theme-color="#0f766e">
+    <Input v-model="title" :input-attrs="titleAttrs" allow-clear />
+    <Textarea v-model="summary" :textarea-attrs="summaryAttrs" />
+    <Select v-model="scopes" :options="options" multiple v-bind="selectAttrs" />
+    <Checkbox v-model="accepted" v-bind="checkboxAttrs">同意条款</Checkbox>
+    <p role="status">标题：{{ title || '空' }}；范围：{{ scopes.join(', ') }}；同意：{{ accepted }}</p>
+  </ConfigProvider>
+</template>
+```

package/AI_USAGE.md

@@ -1,45 +1,58 @@
 <!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/manifest.js. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.10.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.11.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（精选示例、映射、版本与公开类型声明）：`c176a3e6388bb70f3e2b34f65c43da412a3a9166c20d276ddfbda3576370c40d`。
+来源指纹（精选示例、映射、样式依赖、版本与公开类型声明）：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
 
-本手册覆盖 27 个常用组件与服务；包内还有更多导出可用，只是未在此逐个展开。按业务需要选择即可，不必全部使用。
+本手册覆盖 30 个常用组件与服务；包内还有更多导出可用，只是未在此逐个展开。按业务需要选择即可，不必全部使用。
 
 读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。这个文件名不会自动让所有 AI 工具加载，消费项目应在自己的指令中明确引用。
 
 ## 组件选择索引
 
-| 组件/服务 | 公共导出 | 全局标签/形式 | 受控模型 | 详细文档 |
-| --- | --- | --- | --- | --- |
-| ConfigProvider | `ConfigProvider` | `<x-config-provider>` | 无 | [组件文档](https://x-next.yjmf.com/components/config-provider) |
-| Button | `Button` | `<x-button>` | 无 | [组件文档](https://x-next.yjmf.com/components/button) |
-| Checkbox | `Checkbox` | `<x-checkbox>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/checkbox) |
-| Radio | `Radio` | `<x-radio>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/radio) |
-| Select | `Select` | `<x-select>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/select) |
-| Slider | `Slider` | `<x-slider>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/slider) |
-| Rate | `Rate` | `<x-rate>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/rate) |
-| Switch | `Switch` | `<x-switch>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/switch) |
-| DatePicker | `DatePicker` | `<x-date-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/date-picker) |
-| TimePicker | `TimePicker` | `<x-time-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/time-picker) |
-| Alert | `Alert` | `<x-alert>` | `v-model:visible` | [组件文档](https://x-next.yjmf.com/components/alert) |
-| Dialog | `DialogComponent`, `Dialog` | `<x-dialog>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/dialog) |
-| Message | `Message`, `MessageComponent` | 命令式服务 | 无 | [组件文档](https://x-next.yjmf.com/components/message) |
-| MessageBox | `MessageBox` | 命令式服务 | 无 | [组件文档](https://x-next.yjmf.com/components/message-box) |
-| Notification | `Notification`, `NotificationComponent` | 命令式服务 | 无 | [组件文档](https://x-next.yjmf.com/components/notification) |
-| Popconfirm | `Popconfirm` | `<x-popconfirm>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/popconfirm) |
-| Popover | `Popover` | `<x-popover>` | `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/popover) |
-| Progress | `Progress` | `<x-progress>` | 无 | [组件文档](https://x-next.yjmf.com/components/progress) |
-| Dropdown | `Dropdown` | `<x-dropdown>` | `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/dropdown) |
-| Pagination | `Pagination` | `<x-pagination>` | `v-model:current`, `v-model:page-size` | [组件文档](https://x-next.yjmf.com/components/pagination) |
-| Steps | `Steps` | `<x-steps>` | `v-model:current` | [组件文档](https://x-next.yjmf.com/components/steps) |
-| Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | [组件文档](https://x-next.yjmf.com/components/tabs) |
-| Empty | `Empty` | `<x-empty>` | 无 | [组件文档](https://x-next.yjmf.com/components/empty) |
-| Upload | `Upload` | `<x-upload>` | `v-model:file-list` | [组件文档](https://x-next.yjmf.com/components/upload) |
-| BarChart | `BarChart` | `<x-bar-chart>` | 无 | [组件文档](https://x-next.yjmf.com/components/bar-chart) |
-| LineChart | `LineChart` | `<x-line-chart>` | 无 | [组件文档](https://x-next.yjmf.com/components/line-chart) |
-| PieChart | `PieChart` | `<x-pie-chart>` | 无 | [组件文档](https://x-next.yjmf.com/components/pie-chart) |
+样式入口自动包含 base、内部依赖及自身 CSS；依赖列用于直接消费 CSS 时核对，base 只需引入一次。
+
+| 组件/服务 | 公共导出 | 全局标签/形式 | 受控模型 | 样式入口 | 内部依赖 CSS | 详细文档 |
+| --- | --- | --- | --- | --- | --- | --- |
+| ConfigProvider | `ConfigProvider` | `<x-config-provider>` | 无 | `x-next/style/base.css` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/config-provider) |
+| ColorPicker | `ColorPicker` | `<x-color-picker>` | `v-model`, `v-model:show` | `x-next/style/color-picker` | `button.css`, `form-input.css`, `form-input-number.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/color-picker) |
+| Button | `Button` | `<x-button>` | 无 | `x-next/style/button` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/button) |
+| Input | `Input` | `<x-input>` | `v-model` | `x-next/style/form-input` | `button.css` | [组件文档](https://x-next.yjmf.com/components/input) |
+| Textarea | `Textarea` | `<x-textarea>` | `v-model` | `x-next/style/form-textarea` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/textarea) |
+| Checkbox | `Checkbox` | `<x-checkbox>` | `v-model` | `x-next/style/form-checkbox` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/checkbox) |
+| Radio | `Radio` | `<x-radio>` | `v-model` | `x-next/style/form-radio` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/radio) |
+| Select | `Select` | `<x-select>` | `v-model`, `v-model:popup-visible` | `x-next/style/form-select` | `empty.css`, `form-checkbox.css`, `scrollbar-v2.css`, `spin.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/select) |
+| Slider | `Slider` | `<x-slider>` | `v-model` | `x-next/style/form-slider` | `button.css`, `form-input.css`, `form-input-number.css`, `trigger.css`, `tooltip.css` | [组件文档](https://x-next.yjmf.com/components/slider) |
+| Rate | `Rate` | `<x-rate>` | `v-model` | `x-next/style/rate` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/rate) |
+| Switch | `Switch` | `<x-switch>` | `v-model` | `x-next/style/form-switch` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/switch) |
+| DatePicker | `DatePicker` | `<x-date-picker>` | `v-model`, `v-model:popup-visible` | `x-next/style/date-picker` | `button.css`, `scrollbar-v2.css`, `time-picker.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/date-picker) |
+| TimePicker | `TimePicker` | `<x-time-picker>` | `v-model`, `v-model:popup-visible` | `x-next/style/time-picker` | `button.css`, `scrollbar-v2.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/time-picker) |
+| Alert | `Alert` | `<x-alert>` | `v-model:visible` | `x-next/style/alert` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/alert) |
+| Dialog | `DialogComponent`, `Dialog` | `<x-dialog>` | `v-model` | `x-next/style/dialog` | `button.css`, `space.css` | [组件文档](https://x-next.yjmf.com/components/dialog) |
+| Message | `Message`, `MessageComponent` | 命令式服务 | 无 | `x-next/style/message` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/message) |
+| MessageBox | `MessageBox` | 命令式服务 | 无 | `x-next/style/message-box` | `button.css`, `dialog.css`, `space.css` | [组件文档](https://x-next.yjmf.com/components/message-box) |
+| Notification | `Notification`, `NotificationComponent` | 命令式服务 | 无 | `x-next/style/notification` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/notification) |
+| Popconfirm | `Popconfirm` | `<x-popconfirm>` | `v-model` | `x-next/style/popconfirm` | `button.css`, `space.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/popconfirm) |
+| Popover | `Popover` | `<x-popover>` | `v-model:popup-visible` | `x-next/style/popover` | `trigger.css` | [组件文档](https://x-next.yjmf.com/components/popover) |
+| Progress | `Progress` | `<x-progress>` | 无 | `x-next/style/progress` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/progress) |
+| Dropdown | `Dropdown` | `<x-dropdown>` | `v-model:popup-visible` | `x-next/style/dropdown` | `button.css`, `empty.css`, `scrollbar-v2.css`, `spin.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/dropdown) |
+| Pagination | `Pagination` | `<x-pagination>` | `v-model:current`, `v-model:page-size` | `x-next/style/pagination` | `button.css`, `empty.css`, `form-checkbox.css`, `form-input.css`, `form-input-number.css`, `form-select.css`, `scrollbar-v2.css`, `spin.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/pagination) |
+| Steps | `Steps` | `<x-steps>` | `v-model:current` | `x-next/style/steps` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/steps) |
+| Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | `x-next/style/tabs` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/tabs) |
+| Empty | `Empty` | `<x-empty>` | 无 | `x-next/style/empty` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/empty) |
+| Upload | `Upload` | `<x-upload>` | `v-model:file-list` | `x-next/style/upload` | `image.css`, `progress.css`, `trigger.css`, `tooltip.css` | [组件文档](https://x-next.yjmf.com/components/upload) |
+| BarChart | `BarChart` | `<x-bar-chart>` | 无 | `x-next/style/bar-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/bar-chart) |
+| LineChart | `LineChart` | `<x-line-chart>` | 无 | `x-next/style/line-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/line-chart) |
+| PieChart | `PieChart` | `<x-pie-chart>` | 无 | `x-next/style/pie-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/pie-chart) |
+<script setup lang="ts">
+import { ref } from 'vue';
+const cmsTitleDemo = ref('');
+const cmsScopesDemo = ref(['read']);
+const cmsAcceptedDemo = ref(false);
+const cmsOptionsDemo = [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }];
+</script>
+
 本页为每个组件提供一段可直接复制的 Vue SFC，从 `x-next` 根入口导入。把这些示例交给 AI 编程助手作为上下文，它生成的代码就会使用真实的 props 与事件，而不是照搬其他组件库的属性名。
 
 每节开头链接到对应的组件文档，那里有可交互的在线示例和完整 API 表；本页代码聚焦用法要点。随包分发的 `node_modules/x-next/AI_USAGE.md` 是本页的完整版本，可直接提供给 AI 工具读取。
@@ -64,16 +77,63 @@ createApp(App).mount('#app');
 
 接入时遵循这些约定：
 
-- **原生属性直接传**：`id`、`name`、`aria-*` 等原生属性不在组件的 props 类型里，需要时用属性对象 `v-bind` 传入；组件 props 和事件照常直接绑定。
+- **按组件路由传原生属性**：Checkbox / Select 用已核实的 `id/name/aria-*` 属性对象 `v-bind`；Input 用 `inputAttrs`，Textarea 用 `textareaAttrs`。Textarea 的 readonly 也放在 `textareaAttrs` 中。组件 props 和事件直接绑定，不把未知组件 API 塞进 attrs。
 - **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。非受控初始化用 `defaultValue` / `defaultChecked`；把受控值改成 `undefined` 可能切换到内部状态。清空日期、时间统一保存 `''`。
-- **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 用 `renderTo`。容器须已挂载；局部容器要留意定位、滚动和裁剪，Teleport 到 `body` 的弹层不继承原局部容器的主题变量。
+- **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 用 `renderTo`。容器须已挂载；局部容器要留意定位、滚动和裁剪。ConfigProvider 的主题会同步到 Trigger 浮层及组件形态 Dialog / Drawer；单独调用 applyThemeColor 或独立创建命令式实例时，仍需按实际 DOM 宿主处理主题。
 - **优先用公开主题变量**：参考[样式与主题](https://x-next.yjmf.com/guide/theme)。暗色容器上的 alias 链会重新声明；`themeColor` 写入的内联 primary alias 有覆盖边界，按主题文档设置相关公开 alias。
 - **约束业务全局 CSS**：reset 用 `:where(...)` 降低优先级并限定作用域；宽泛的原生元素选择器可能覆盖组件样式。自定义内容用插槽和公开属性，不依赖内部结构类名。
 - **清理页面创建的服务**：保留句柄，在路由页面卸载时调用 `close()`；KeepAlive 页面可在停用时清理。Dialog / MessageBox 的命令式关闭不触发确认、取消回调，业务取消逻辑需自行调用；Message / Notification 的关闭会触发各自的 `onClose`。
 
+## 按需样式与表单接入
+
+使用无扩展名的公开 JS 样式入口，例如 `x-next/style/form-select`。它自动引入共享 base、Select 自身及 Trigger、Scrollbar、Empty、Spin、Checkbox 的 CSS；业务不需要逐个维护内部依赖。多个入口由打包器按文件去重。Input / Textarea 的样式路径分别是 `form-input` / `form-textarea`，不要根据组件名猜 `style/input`。
+
+若直接导入 `.css`，需要自己引入 base、自身和全部内部依赖；精选手册索引列出了依赖，发布包 `dist/style/dependencies.json` 提供完整组件映射。全量 `x-next/style.css` 仍可使用。不要同时混用全量与按需方案。
+
+下面是可独立复制的按需表单 SFC，原生属性按各组件真实路由传入：
+
+<div class="example-box example-box-column">
+  <x-config-provider theme-color="#0f766e">
+    <x-input v-model="cmsTitleDemo" :input-attrs="{ id: 'cms-title-demo', name: 'title', 'aria-label': '接入标题' }" allow-clear />
+    <x-textarea model-value="只读接入说明" :textarea-attrs="{ name: 'summary', 'aria-label': '接入说明', readonly: true }" />
+    <x-select v-model="cmsScopesDemo" :options="cmsOptionsDemo" multiple aria-label="接入授权范围" />
+    <x-checkbox v-model="cmsAcceptedDemo" aria-label="接入同意条款">同意条款</x-checkbox>
+  </x-config-provider>
+  <span role="status">标题：{{ cmsTitleDemo || '空' }}；范围：{{ cmsScopesDemo.join(', ') }}；同意：{{ cmsAcceptedDemo }}</span>
+</div>
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ConfigProvider, Input, Textarea, Select, Checkbox } from 'x-next';
+import 'x-next/style/form-input';
+import 'x-next/style/form-textarea';
+import 'x-next/style/form-select';
+import 'x-next/style/form-checkbox';
+const title = ref('');
+const summary = ref('只读接入说明');
+const scopes = ref<string[]>(['read']);
+const accepted = ref(false);
+const titleAttrs = { id: 'cms-title', name: 'title', 'aria-label': '标题', required: true };
+const summaryAttrs = { id: 'cms-summary', name: 'summary', 'aria-label': '说明', readonly: true };
+const selectAttrs = { id: 'cms-scopes', 'aria-label': '授权范围' };
+const checkboxAttrs = { name: 'agreement', 'aria-label': '同意条款' };
+const options = [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }];
+</script>
+<template>
+  <ConfigProvider theme-color="#0f766e">
+    <Input v-model="title" :input-attrs="titleAttrs" allow-clear />
+    <Textarea v-model="summary" :textarea-attrs="summaryAttrs" />
+    <Select v-model="scopes" :options="options" multiple v-bind="selectAttrs" />
+    <Checkbox v-model="accepted" v-bind="checkboxAttrs">同意条款</Checkbox>
+    <p role="status">标题：{{ title || '空' }}；范围：{{ scopes.join(', ') }}；同意：{{ accepted }}</p>
+  </ConfigProvider>
+</template>
+```
+
 ## ConfigProvider
 
-局部品牌色用 `themeColor`，它一次生成色阶并重绑定组件别名；不必逐个覆盖 Button、Switch 的颜色。将弹层宿主放在同一主题子树内，Teleport 后仍能继承。Select 默认跟随祖先滚动；要滚动关闭可传 `triggerProps.scrollToClose`。
+局部品牌色用 `themeColor`，它一次生成色阶并重绑定组件别名；不必逐个覆盖 Button、Switch 的颜色。默认 body 浮层也会同步当前配置；更换 popupContainer 只用于业务定位和裁剪需要。Select 默认跟随祖先滚动；要滚动关闭可传 `triggerProps.scrollToClose`。
 
 ```vue
 <script setup lang="ts">
@@ -83,7 +143,6 @@ import { Button, ConfigProvider, Select, Switch } from 'x-next';
 const brand = ref('#2f6feb');
 const dark = ref(false);
 const value = ref('day');
-const overlayHost = ref<HTMLElement>();
 const switchAttrs = { 'aria-label': '局部暗色' };
 const selectAttrs = { 'aria-label': '统计粒度' };
 const options = [
@@ -99,14 +158,11 @@ const options = [
     </Button>
     <Switch v-model="dark" v-bind="switchAttrs" />
     <Select
-      v-if="overlayHost"
       v-model="value"
       :options="options"
-      :popup-container="overlayHost"
       v-bind="selectAttrs"
       style="width: 160px"
     />
-    <div ref="overlayHost" class="brand-overlay" />
   </ConfigProvider>
 </template>
 
@@ -120,16 +176,38 @@ const options = [
   color: var(--x-color-text-primary);
   background: var(--x-color-bg-surface);
 }
-.brand-overlay {
-  position: fixed;
-  inset: 0;
-  pointer-events: none;
-  z-index: 2000;
-}
 </style>
 ```
 
-已有主题容器时，也可调用公开 `applyThemeColor(seed, { target, dark })`；切换暗色后需重新调用。只改后代的几条 semantic CSS 变量不会重算祖先 alias；`:tag="null"` 的 ConfigProvider 没有承载局部主题的 DOM。
+已有主题容器时，也可调用公开 `applyThemeColor(seed, { target, dark })`；切换暗色后需重新调用。只改后代的几条 semantic CSS 变量不会重算祖先 alias；`:tag="null"` 的 ConfigProvider 不创建本级主题边界，仍继承父级配置。
+
+## ColorPicker
+
+[组件文档与 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>
+```
 
 ## Button
 
@@ -158,6 +236,53 @@ async function save(_event: MouseEvent) {
 </template>
 ```
 
+## Input
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/input)。`v-model` 为字符串，`input` 随输入触发，`change` 在失焦或回车时触发，`clear` 通知清空；readonly 是组件 prop。原生 id、name、aria、required 用 `inputAttrs`，外部 class / style 落在容器。内部装饰用 prefix / suffix，外侧标签用 prepend / append。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Input } from 'x-next';
+import 'x-next/style/form-input';
+const title = ref('');
+const log = ref('等待输入');
+const nativeAttrs = { id: 'article-title', name: 'title', 'aria-label': '文章标题', required: true };
+</script>
+<template>
+  <label for="article-title">文章标题</label>
+  <Input v-model="title" :input-attrs="nativeAttrs" allow-clear
+    @input="value => log = `input: ${value}`" @clear="log = '已清空'">
+    <template #prefix>标题</template>
+  </Input>
+  <Input model-value="只读标题" readonly :input-attrs="{ 'aria-label': '只读标题' }" />
+  <p role="status">{{ log }}；当前值：{{ title }}</p>
+</template>
+```
+
+## Textarea
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/textarea)。`v-model` 为字符串，`input/change/clear` 与输入生命周期联动。原生 id、name、aria、rows、readonly 用 `textareaAttrs`，不支持组件层的 readonly prop；autoSize 控制自动高度。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Textarea } from 'x-next';
+import 'x-next/style/form-textarea';
+const summary = ref('');
+const log = ref('等待输入');
+const nativeAttrs = { id: 'article-summary', name: 'summary', 'aria-label': '文章摘要', rows: 3 };
+const readonlyAttrs = { id: 'saved-summary', name: 'savedSummary', 'aria-label': '只读摘要', readonly: true };
+</script>
+<template>
+  <label for="article-summary">文章摘要</label>
+  <Textarea v-model="summary" :textarea-attrs="nativeAttrs" :auto-size="{ minRows: 3, maxRows: 6 }"
+    @input="value => log = `input: ${value}`" />
+  <Textarea model-value="已保存的摘要" :textarea-attrs="readonlyAttrs" />
+  <p role="status">{{ log }}；当前值：{{ summary }}</p>
+</template>
+```
+
 ## Checkbox
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/checkbox)。使用普通 `v-model`；模型支持 `boolean` 或 `(string | number | boolean)[]`，数组模式配合 `value`。`defaultChecked`、`disabled`、`indeterminate` 默认 `false`；半选状态不会替代模型值。
@@ -217,6 +342,8 @@ function changed(value: string | number | boolean, _event: Event) {
 
 `change(value)` 返回新值，`clear(event)` 返回 `Event`；单选清空通常为 `''`，多选为 `[]`，已选禁用项可能保留。`v-model:popup-visible` 控制弹层，`option` / `empty` / `header` / `footer` 等插槽见组件文档。
 
+有值且可清空时，右侧 × 与箭头共用位置，点击 × 不切换面板。`v-model:input-value` 控制搜索输入；远程搜索设置 `filterOption=false`，用 `@search` 请求数据并由业务取消旧请求。对象值用 `valueKey` 标识，`fallbackOption` 处理暂时缺失的候选项。默认触发器 ref 类型为 `SelectInstance`，提供 `focus()` / `blur()`；自定义 `trigger` 插槽将 `onKeydown` 绑定到自己的可聚焦节点。
+
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';