x-next 1.10.0 → 1.11.0

package/AI_USAGE/components/empty.md

@@ -0,0 +1,30 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Empty AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Empty`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+
+按需样式：`x-next/style/empty`（包含 base.css、empty.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/empty)。`description` 未传时使用语言包默认文案，`null` 或 `''` 隐藏描述；`imgSrc` 自定义图片，`image` 插槽优先于图片地址。默认插槽替代描述，可放业务操作按钮。
+
+没有模型或业务事件；刷新、创建等动作由插槽中的业务控件处理。显式提供描述、图片或插槽时采用调用方配置；裸 Empty 才会交由外层 ConfigProvider 的 `empty` 插槽接管。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Empty } from 'x-next';
+import 'x-next/dist/style.css';
+const refreshed = ref(false);
+function refresh() { refreshed.value = true; }
+</script>
+<template>
+  <Empty>
+    <p>{{ refreshed ? '刷新完成，仍无记录' : '暂无记录' }}</p>
+    <Button @click="refresh">刷新记录</Button>
+  </Empty>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/input.md

@@ -0,0 +1,32 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Input AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Input`；模型：v-model；已核对事件：input、change、clear。
+
+按需样式：`x-next/style/form-input`（包含 base.css、button.css、form-input.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 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>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/line-chart.md

@@ -0,0 +1,45 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# LineChart AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`LineChart`；模型：无；已核对事件：lineClick、legendChange。
+
+按需样式：`x-next/style/line-chart`（包含 base.css、line-chart.css、spin.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/line-chart)。随时间看趋势就用它：`categories` 是时间轴标签，`series` 是数据系列（`{ name, data, color }`），按下标对应。多系列默认叠放，加 `area` 填充、再加 `stack` 变堆叠面积。按类目比大小用 BarChart，看占比用 PieChart，卡片角落的迷你走势用 TrendChart——完整选择指引见[图表总览](https://x-next.yjmf.com/components/charts)。
+
+**缺测要显式表达**：把没有数据的点写成 `null`，默认会在该处**断开**折线（不会画成跌到 0）；确需连线时传 `:connect-nulls="true"`。数值轴对纯正数数据保持 0 基线，出现负值才向下扩展；`min` / `max` 可锁定区间。`smooth` 默认开启，`show-points` 默认 `'auto'`（点数少时常显）。
+
+`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`（数值轴会按剩余可见系列重算）；点击触发 `lineClick`，命中数据点时带 `seriesIndex` / `value`。`valueFormatter` 同时作用于提示与图例，`labels.yFormatter` 只作用于数值轴。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { LineChart } from 'x-next';
+import 'x-next/dist/style.css';
+const categories = ref(['09-28', '09-29', '09-30', '10-01', '10-02']);
+// 10-01 当天缺测：null 会让折线在该处断开
+const series = ref([
+  { name: '请求量', data: [820, 932, null, 934, 1290] },
+  { name: '错误数', data: [12, 18, null, 9, 22] },
+]);
+const picked = ref('尚未选择');
+function onLineClick(data: { label: string; value: number | null }) {
+  picked.value = `${data.label}：${data.value ?? '缺测'}`;
+}
+</script>
+<template>
+  <LineChart
+    :categories="categories"
+    :series="series"
+    :height="280"
+    area
+    legend
+    @line-click="onLineClick"
+  />
+  <p role="status">{{ picked }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/message-box.md

@@ -0,0 +1,39 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# MessageBox AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`MessageBox`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+
+按需样式：`x-next/style/message-box`（包含 base.css、button.css、dialog.css、message-box.css、space.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/message-box)。调用 `MessageBox(options)`，默认类型为 `'success'`、宽度 `360`、居中、显示遮罩和关闭按钮、点击遮罩不关闭。`title` / `content` 支持文字、VNode 或渲染函数；`footer=false` 隐藏页脚。
+
+返回 `close()` / `update(options)` 句柄，结果通过 `onOk(event)` / `onCancel(event)` 回调处理。`beforeOnOk` / `beforeOnCancel` 返回 `boolean | Promise<boolean>`，必须返回 `true` 才放行；异步业务放在前置钩子。它不是 Promise，没有 `confirm()`；`.warning(title, content)` 等返回的 `.ok()` / `.cancel()` 用于注册链式回调。
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, ref } from 'vue';
+import { Button, MessageBox } from 'x-next';
+import 'x-next/dist/style.css';
+const feedback = ref('尚未确认');
+let handle: ReturnType<typeof MessageBox> | undefined;
+function ask() {
+  handle?.close();
+  feedback.value = '等待确认';
+  handle = MessageBox({ title: '确认保存？', content: '确认后保存当前安排。', type: 'warning',
+    beforeOnOk: () => true,
+    onOk: (_event: Event) => { feedback.value = '已确认保存'; },
+    onCancel: (_event: Event) => { feedback.value = '用户已取消'; } });
+}
+function close() { handle?.close(); feedback.value = '已主动关闭'; }
+onBeforeUnmount(() => handle?.close());
+</script>
+<template>
+  <Button @click="ask">请求确认</Button>
+  <Button @click="close">主动关闭</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/message.md

@@ -0,0 +1,36 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Message AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Message, MessageComponent`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+
+按需样式：`x-next/style/message`（包含 base.css、message.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/message)。`Message(options)` 或 `.success()` / `.error()` / `.loading()` 等显示提示。默认 `type='info'`、`duration=3000` 毫秒、`position='top'`、`showClose=false`；`duration=0` 持续显示，内容用 `message` 或 `content`。
+
+返回句柄只有 `close()`；同一容器和位置下再次传相同 `id` 更新消息，没有句柄 `update()`。`onClose(id?)` 在自动或手动关闭时触发；自定义内容可用 VNode / 渲染函数。页面只清理自己持有的句柄。
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, ref } from 'vue';
+import { Button, Message } from 'x-next';
+import 'x-next/dist/style.css';
+const feedback = ref('尚未显示提示');
+let handle: ReturnType<typeof Message> | undefined;
+function show() {
+  handle?.close();
+  handle = Message({ message: '保存完成', type: 'success', duration: 0, showClose: true,
+    onClose: () => { feedback.value = '提示已关闭'; } });
+  feedback.value = '提示显示中';
+}
+onBeforeUnmount(() => handle?.close());
+</script>
+<template>
+  <Button @click="show">显示提示</Button>
+  <Button @click="handle?.close()">关闭提示</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/notification.md

@@ -0,0 +1,37 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Notification AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Notification, NotificationComponent`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+
+按需样式：`x-next/style/notification`（包含 base.css、notification.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/notification)。`Notification(options)` 或 `.success()` 等显示通知。服务默认 `type='info'`、`duration=3000` 毫秒、`position='top-right'`、`offset=20`、`showClose=true`；四角位置可选，`duration=0` 持续显示。
+
+`title` 和 `message` / `content` 是内容，`footer` / `icon` 可用 VNode 或渲染函数。返回句柄只有 `close()`；同一容器与位置下复用 `id` 更新。`onClick()` 无参数，`onClose(id?)` 接收标识；`.remove(id)` / `.clear(position?)` 是服务级方法。
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, ref } from 'vue';
+import { Button, Notification } from 'x-next';
+import 'x-next/dist/style.css';
+const feedback = ref('尚未显示通知');
+let handle: ReturnType<typeof Notification> | undefined;
+function show() {
+  handle?.close();
+  handle = Notification({ title: '任务完成', message: '结果已准备好。', type: 'success', duration: 0,
+    onClick: () => { feedback.value = '已点击通知'; },
+    onClose: () => { feedback.value = '通知已关闭'; } });
+  feedback.value = '通知显示中';
+}
+onBeforeUnmount(() => handle?.close());
+</script>
+<template>
+  <Button @click="show">显示通知</Button>
+  <Button @click="handle?.close()">关闭通知</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/pagination.md

@@ -0,0 +1,32 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Pagination AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Pagination`；模型：v-model:current、v-model:page-size；已核对事件：change、pageSizeChange。
+
+按需样式：`x-next/style/pagination`（包含 base.css、button.css、empty.css、form-checkbox.css、form-input.css、form-input-number.css、form-select.css、pagination.css、scrollbar-v2.css、spin.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/pagination)。`total` 必填且表示记录总数。使用 `v-model:current` 和 `v-model:page-size`；默认非受控值为页码 `1`、每页 `10`，`showTotal` / `showPageSize` / `showJumper` 默认关闭，`autoAdjust=true`。
+
+`change(current)` 和 `page-size-change(pageSize)` 各返回一个数字；不会请求数据。页码按总数裁剪，每页条数应为正数。`total` 插槽提供总数，`page-item` 提供页码；改变条数后的业务重新查询需自行实现。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Pagination } from 'x-next';
+import 'x-next/dist/style.css';
+const current = ref(1);
+const pageSize = ref(10);
+const feedback = ref('当前第 1 页');
+function changed(page: number) { feedback.value = `当前第 ${page} 页`; }
+function resized(size: number) { current.value = 1; feedback.value = `每页 ${size} 条，返回第一页`; }
+</script>
+<template>
+  <Pagination v-model:current="current" v-model:page-size="pageSize" :total="95" show-total show-page-size
+    :page-size-options="[10, 20, 50]" @change="changed" @page-size-change="resized" />
+  <p role="status">{{ feedback }}；每页 {{ pageSize }} 条</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/pie-chart.md

@@ -0,0 +1,55 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# PieChart AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`PieChart`；模型：无；已核对事件：itemClick、legendChange。
+
+按需样式：`x-next/style/pie-chart`（包含 base.css、pie-chart.css、spin.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/pie-chart)。表达占比：`data` 是 `{ name, value }[]`，值按**可见**分片求和换算角度。`innerRadius="62%"` 渲染成环形并在中心显示合计（推荐形态，信息密度更高）；数字形式的 `innerRadius` 按 px。负值、0 与非有限数会被跳过，不计入总量。
+
+**类别要收敛**：饼图超过 7 个分片就难以阅读，先按值排序、把尾部合并成「其他」再传入（下面给出写法）。需要精确比较大小改用 BarChart，需要看随时间的变化改用 LineChart。
+
+`legend` 开启后图例项展示数值与占比，点击可隐藏分片——剩余分片重新分配角度、中心合计同步更新，并触发 `legendChange`；点击分片触发 `itemClick`。`center` / `tooltip` / `label` / `legend` 插槽可分别自定义。
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { PieChart } from 'x-next';
+import 'x-next/dist/style.css';
+const raw = ref([
+  { name: 'search', value: 820 },
+  { name: 'read_file', value: 610 },
+  { name: 'write_file', value: 430 },
+  { name: 'run_shell', value: 320 },
+  { name: 'browse', value: 210 },
+  { name: 'exec_python', value: 180 },
+  { name: 'grep', value: 140 },
+]);
+const LIMIT = 5;
+// 饼图不宜超过 7 个分片：取前 N 项，尾部合并为「其他」
+const data = computed(() => {
+  const sorted = [...raw.value].sort((a, b) => b.value - a.value);
+  const top = sorted.slice(0, LIMIT);
+  const rest = sorted.slice(LIMIT).reduce((sum, item) => sum + item.value, 0);
+  return rest > 0 ? [...top, { name: '其他', value: rest }] : top;
+});
+const picked = ref('尚未选择');
+function onItemClick(item: { name: string; value: number; percent: number; formatPercent: (p: number) => string }) {
+  picked.value = `${item.name}：${item.value}（${item.formatPercent(item.percent)}）`;
+}
+</script>
+<template>
+  <PieChart
+    :data="data"
+    inner-radius="62%"
+    :height="280"
+    legend
+    @item-click="onItemClick"
+  />
+  <p role="status">{{ picked }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/popconfirm.md

@@ -0,0 +1,33 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Popconfirm AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Popconfirm`；模型：v-model；已核对事件：ok、cancel。
+
+按需样式：`x-next/style/popconfirm`（包含 base.css、button.css、popconfirm.css、space.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/popconfirm)。普通布尔 `v-model` 控制显示，`defaultVisible=false`、`type='danger'`、`position='top'`、`width=150`，点击默认插槽触发。`content` / `icon` 插槽可自定义确认内容；按钮文字用 `okText` / `cancelText`。
+
+`ok(event)` / `cancel(event)` 返回 `Event`，`change(visible)` 返回布尔值。`onBeforeOk` / `onBeforeCancel` 支持布尔、void 或 Promise，返回 `false` 可阻止关闭；异步钩子可自动等待，普通 `ok` 监听器不会自动阻止关闭。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Popconfirm } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('记录保留中');
+function remove(_event: Event) { feedback.value = '已确认删除'; }
+function cancel(_event: Event) { feedback.value = '已取消删除'; }
+</script>
+<template>
+  <Popconfirm v-model="visible" content="删除这条记录？" ok-text="删除" cancel-text="保留"
+    @ok="remove" @cancel="cancel">
+    <Button status="danger">删除记录</Button>
+  </Popconfirm>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/popover.md

@@ -0,0 +1,35 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Popover AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Popover`；模型：v-model:popup-visible；已核对事件：popupVisibleChange。
+
+按需样式：`x-next/style/popover`（包含 base.css、popover.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/popover)。使用 `v-model:popup-visible`；默认 `trigger='click'`、`position='bottom'`、`showArrow=false`、`defaultPopupVisible=false`、`unmountOnClose=true`。默认插槽是触发器，`title` / `content` 插槽放浮层内容。
+
+`popup-visible-change(visible)` 返回布尔值，`show` / `hide` 无参数。点击触发器或外部默认可以关闭；`popupContainer` 和 `renderToBody` 决定宿主，局部主题下按实际挂载位置核对样式。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Popover } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('说明未打开');
+function changed(value: boolean) { feedback.value = value ? '说明已打开' : '说明已关闭'; }
+</script>
+<template>
+  <Popover v-model:popup-visible="visible" title="安排说明" show-arrow @popup-visible-change="changed">
+    <Button>查看说明</Button>
+    <template #content>
+      <p>时间以页面所选值为准。</p>
+      <Button @click="visible = false">关闭说明</Button>
+    </template>
+  </Popover>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/progress.md

@@ -0,0 +1,32 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Progress AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Progress`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+
+按需样式：`x-next/style/progress`（包含 base.css、progress.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/progress)。`percent` 为 **0 到 1** 的比例，默认 `0`，不是 0 到 100；超出范围会裁剪，非有限值显示为 0。默认 `type='line'`、`showText=true`、`animation=false`，`steps>0` 使用分段模式。
+
+无模型和业务 change 事件，由业务更新 `percent`。`status` 为 normal、success、warning、danger，未设置时达到 1 自动为 success；`text` 插槽提供 `{ percent }`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Progress } from 'x-next';
+import 'x-next/dist/style.css';
+const percent = ref(0.25);
+function advance() { percent.value = Math.min(1, percent.value + 0.25); }
+</script>
+<template>
+  <div style="max-width: 320px">
+    <Progress :percent="percent">
+      <template #text="scope">已完成 {{ Math.round(scope.percent * 100) }}%</template>
+    </Progress>
+    <Button :disabled="percent >= 1" @click="advance">推进任务</Button>
+  </div>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/radio.md

@@ -0,0 +1,35 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Radio AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Radio`；模型：v-model；已核对事件：change。
+
+按需样式：`x-next/style/form-radio`（包含 base.css、form-radio.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/radio)。`Radio` / `RadioGroup` 的模型和选项值支持 `string | number | boolean`，保留值类型；布尔选项写 `:value="true"`。单个 Radio 的 `value` 默认 `true`，组的非受控默认值为 `''`。
+
+组默认 `type='radio'`、`direction='horizontal'`、`disabled=false`；`change(value, event)` 返回选项值和 `Event`。Radio 默认插槽是文案，组也支持 `options` 和 `label` / `radio` 插槽。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Radio, RadioGroup } from 'x-next';
+import 'x-next/dist/style.css';
+const enabled = ref<string | number | boolean>(true);
+const controlAttrs = { name: 'delivery-mode', 'aria-label': '是否开启通知' };
+const feedback = ref('当前开启');
+function changed(value: string | number | boolean, _event: Event) {
+  feedback.value = value === true ? '当前开启' : '当前关闭';
+}
+</script>
+<template>
+  <RadioGroup v-model="enabled" v-bind="controlAttrs" @change="changed">
+    <Radio :value="true">开启</Radio>
+    <Radio :value="false">关闭</Radio>
+  </RadioGroup>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/rate.md

@@ -0,0 +1,30 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Rate AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Rate`；模型：v-model；已核对事件：change。
+
+按需样式：`x-next/style/rate`（包含 base.css、rate.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/rate)。数值模型默认非受控值为 `0`，`count=5`；`allowHalf`、`allowClear`、`readonly`、`disabled` 默认关闭。启用半星后步长为 `0.5`，值限制在有效数量内；没有 `size` 属性。
+
+`change(value)` 返回 `number`，`hover-change(value)` 返回 `number | undefined`。`character` 插槽提供 `index`、`value`、`count`、`disabled`；`tooltips` 为提示数组。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Rate } from 'x-next';
+import 'x-next/dist/style.css';
+const score = ref(3.5);
+const controlAttrs = { 'aria-label': '服务评分' };
+const feedback = ref('请评分');
+function changed(value: number) { feedback.value = value ? `评分 ${value}` : '已清除评分'; }
+</script>
+<template>
+  <Rate v-model="score" allow-half allow-clear v-bind="controlAttrs" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/select.md

@@ -0,0 +1,38 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Select AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Select`；模型：v-model、v-model:popup-visible；已核对事件：change、popupVisibleChange。
+
+按需样式：`x-next/style/form-select`（包含 base.css、empty.css、form-checkbox.css、form-select.css、scrollbar-v2.css、spin.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/select)。`v-model` 返回选项的 `value`；单选通常为标量，多选为数组，也支持对象值。`multiple=false`、`allowClear=false`；单选搜索默认关闭，多选默认开启。`options` 使用可变数组，常用字段是 `label`、`value`、`disabled`。
+
+`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';
+import { Select } from 'x-next';
+import 'x-next/dist/style.css';
+const city = ref('');
+const options = [
+  { label: '杭州', value: 'hangzhou' },
+  { label: '上海', value: 'shanghai' },
+  { label: '暂未开放', value: 'pending', disabled: true },
+];
+const feedback = ref('尚未选择');
+function changed(value: unknown) {
+  feedback.value = typeof value === 'string' && value ? `城市代码：${value}` : '已清空';
+}
+</script>
+<template>
+  <Select v-model="city" :options="options" allow-search allow-clear placeholder="选择城市" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/slider.md

@@ -0,0 +1,34 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Slider AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Slider`；模型：v-model；已核对事件：change。
+
+按需样式：`x-next/style/form-slider`（包含 base.css、button.css、form-input.css、form-input-number.css、form-slider.css、trigger.css、tooltip.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/slider)。普通模型为 `number`，`range` 模式为 `[number, number]`。默认 `min=0`、`max=100`、`step=1`、`range=false`、`disabled=false`、`showTooltip=true`；范围端点按大小排序并按步长归一化。
+
+`change(value)` 表示值变化，`change-end(value)` 表示一次拖拽、点击、键盘或输入提交结束，载荷均为 `number | [number, number]`。`marks` 是数值键到文字的映射，`formatTooltip` 可格式化提示。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Slider } from 'x-next';
+import 'x-next/dist/style.css';
+const volume = ref(40);
+const controlAttrs = { 'aria-label': '音量' };
+const committed = ref('尚未调整');
+function finish(value: number | [number, number]) {
+  committed.value = typeof value === 'number' ? `已提交音量 ${value}` : value.join(' ～ ');
+}
+</script>
+<template>
+  <div style="max-width: 320px">
+    <Slider v-model="volume" :step="10" :marks="{ 0: '静音', 100: '最大' }" v-bind="controlAttrs" @change-end="finish" />
+    <p role="status">当前 {{ volume }}；{{ committed }}</p>
+  </div>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/steps.md

@@ -0,0 +1,33 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Steps AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Steps`；模型：v-model:current；已核对事件：change。
+
+按需样式：`x-next/style/steps`（包含 base.css、steps.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/steps)。子组件的公开名称是 `Step`。使用 `v-model:current`，序号从 **1** 开始，`defaultCurrent=1`、`status='process'`、`type='default'`、`direction='horizontal'`；点击切换需开启 `changeable`，默认关闭。
+
+`change(step, event)` 返回步骤号和 `Event`。Step 支持 `title`、`description`、`disabled`、`status`；`node` / `icon` 插槽提供步骤与状态，默认 / `description` 插槽可替换文案。业务完成状态由业务自身维护。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Steps, Step } from 'x-next';
+import 'x-next/dist/style.css';
+const current = ref(1);
+const feedback = ref('正在填写');
+function changed(step: number, _event: Event) { feedback.value = `已切换到第 ${step} 步`; }
+</script>
+<template>
+  <Steps v-model:current="current" changeable @change="changed">
+    <Step title="填写" description="准备安排" />
+    <Step title="核对" description="检查内容" />
+    <Step title="完成" description="提交结果" />
+  </Steps>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/switch.md

@@ -0,0 +1,32 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+# Switch AI 使用
+
+适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+
+先读 [通用接入](../core.md)。公开导出：`Switch`；模型：v-model；已核对事件：change。
+
+按需样式：`x-next/style/form-switch`（包含 base.css、form-switch.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/switch)。普通 `v-model` 支持 `boolean | string | number`；`checkedValue=true`、`uncheckedValue=false`、`defaultChecked=false`，默认 `type='circle'`。`disabled` / `loading` 阻止切换。
+
+`change(value, event)` 返回新值和 `Event`；`beforeChange(newValue)` 可返回布尔值或 Promise，`false` 或拒绝阻止切换。`checked` / `unchecked` 插槽及 `checkedText` / `uncheckedText` 显示两态文案，line 类型不显示文案。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Switch } from 'x-next';
+import 'x-next/dist/style.css';
+const enabled = ref(false);
+const controlAttrs = { 'aria-label': '通知开关' };
+const feedback = ref('通知关闭');
+function changed(value: boolean | string | number, _event: Event) {
+  feedback.value = value === true ? '通知开启' : '通知关闭';
+}
+</script>
+<template>
+  <Switch v-model="enabled" checked-text="开" unchecked-text="关" v-bind="controlAttrs" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。