x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/pie-chart.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # PieChart AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`PieChart`；模型：无；已核对事件：itemClick、legendChange。
+先读 [通用接入](../core.md)。公开导出：`PieChart`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./pie-chart-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`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。
@@ -52,4 +54,244 @@ function onItemClick(item: { name: string; value: number; percent: number; forma
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/pie-chart.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./pie-chart-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于展示各部分在整体中的占比：支持饼图与环形图、中心内容、外围标签与图例联动。
+
+
+### 何时使用
+
+- 需要表达「各部分占整体的比例」，且只关心少数几个主要类别（建议不超过 7 个）。
+- 数据总和有意义（如各类别调用量、各渠道订单数）。
+- 环形模式适合在中心放一个合计值或关键指标，信息密度更高。
+
+
+### 什么时候不要用
+
+饼图表达力弱：角度比长度更难精确比较，分片一多就会退化成一圈小色块。
+
+| 情况 | 改用 |
+| --- | --- |
+| 类别超过 7 个 | 堆叠柱状（[BarChart](./bar-chart.md) 的 `stack`），或先把小项合并为「其他」 |
+| 需要精确比较各类别大小 | [BarChart 柱状趋势图](./bar-chart.md) 并排柱状 |
+| 要表达随时间的变化 | [LineChart 折线图](./line-chart.md) |
+| 只有一个占比（如使用率 62%） | 用 [Progress 进度条](./progress.md) 或环形进度，不要用两个分片的饼图 |
+
+
+### 基础用法
+
+`data` 为 `{ name, value }[]`；值为负、为 0 或非有限数会被跳过，不计入总量。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { PieChart } from 'x-next';
+import { ref } from 'vue';
+
+const data = ref([
+  { name: 'deepseek-flash', value: 13260000 },
+  { name: 'gpt-4o-mini', value: 4820000 },
+  { name: 'claude-haiku', value: 2140000 },
+]);
+const formatCompact = (value: number) => `${(value / 10000).toFixed(1)} 万`;
+</script>
+<template>
+<PieChart :data="data" :value-formatter="formatCompact" ariaLabel="各模型 Token 占比" />
+</template>
+```
+
+### 环形与中心内容
+
+`innerRadius` 大于 0 时渲染为环形：数字按 px，`'62%'` 按外半径比例。环形默认在中心展示合计，也可用 `center` 插槽自定义。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { PieChart } from 'x-next';
+import { ref } from 'vue';
+
+const innerRadius = ref('62%');
+const data = ref([
+  { name: 'Web', value: 4280 },
+  { name: 'iOS', value: 3160 },
+  { name: 'Android', value: 2870 },
+  { name: 'API', value: 1520 },
+]);
+const formatCalls = (value: number) => `${value} 次`;
+</script>
+<template>
+<PieChart
+    :data="data"
+    :inner-radius="innerRadius"
+    :value-formatter="formatCalls"
+  />
+</template>
+```
+
+### 自定义中心
+
+`center` 插槽接管环形中心，可放合计之外的内容（如环比的箭头与增幅）。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { PieChart } from 'x-next';
+import { ref } from 'vue';
+
+const data = ref([
+  { name: 'Web', value: 4280 },
+  { name: 'iOS', value: 3160 },
+  { name: 'Android', value: 2870 },
+  { name: 'API', value: 1520 },
+]);
+</script>
+<template>
+<PieChart :data="data" inner-radius="62%">
+    <template #center="{ total, formatValue }">
+      <text x="50%" y="46%" text-anchor="middle">总调用量</text>
+      <text x="50%" y="56%" text-anchor="middle">{{ formatValue(total) }}</text>
+    </template>
+  </PieChart>
+</template>
+```
+
+### 类别过多时合并「其他」
+
+饼图不宜超过 7 个分片。先按值排序，把尾部合并成一项再传入，是最省事也最可控的做法。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { PieChart } from 'x-next';
+import { computed, ref } from 'vue';
+
+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 },
+  { name: 'edit', value: 110 },
+  { name: 'todo_write', value: 90 },
+]);
+const LIMIT = 5;
+// 取前 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 formatCalls = (value: number) => `${value} 次`;
+</script>
+<template>
+<PieChart :data="data" inner-radius="62%" :value-formatter="formatCalls" legend />
+</template>
+```
+
+### 图例联动与点击事件
+
+`legend` 开启后，图例项展示数值与占比，点击可临时隐藏分片——剩余分片会重新分配角度、中心合计同步更新。点击分片触发 `item-click`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { PieChart } from 'x-next';
+import { ref } from 'vue';
+
+const data = ref([
+  { name: 'Web', value: 4280 },
+  { name: 'iOS', value: 3160 },
+  { name: 'Android', value: 2870 },
+  { name: 'API', value: 1520 },
+]);
+const clickLog = ref('尚未点击分片');
+const visibleCount = ref(4);
+const onItemClick = (data: { name: string; value: number; percent: number; formatPercent: (p: number) => string }) => {
+  clickLog.value = `${data.name}：${data.value}（${data.formatPercent(data.percent)}）`;
+};
+const onLegendChange = (indexes: number[]) => {
+  visibleCount.value = indexes.length;
+};
+</script>
+<template>
+<PieChart
+    :data="data"
+    inner-radius="62%"
+    legend
+    @item-click="onItemClick"
+    @legend-change="onLegendChange"
+  />
+  <p>{{ clickLog }}</p>
+</template>
+```
+
+### 自定义提示
+
+`tooltip` 插槽可显示调用次数、占比与环比等组合信息。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { PieChart } from 'x-next';
+import { ref } from 'vue';
+
+const data = ref([
+  { name: 'Web', value: 4280 },
+  { name: 'iOS', value: 3160 },
+  { name: 'Android', value: 2870 },
+  { name: 'API', value: 1520 },
+]);
+const formatCalls = (value: number) => `${value} 次`;
+</script>
+<template>
+<PieChart :data="data" inner-radius="62%" :value-formatter="formatCalls">
+    <template #tooltip="{ name, value, percent, formatValue, formatPercent }">
+      <div style="font-weight: 500">{{ name }}</div>
+      <div>{{ formatValue(value) }} · {{ formatPercent(percent) }}</div>
+    </template>
+  </PieChart>
+</template>
+```
+
+### 加载与空数据
+
+`loading` 覆盖加载遮罩；没有正数分片时显示空态，可用 `empty` 插槽替换。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { PieChart } from 'x-next';
+import { ref } from 'vue';
+
+const loading = ref(true);
+const data = ref([
+  { name: 'Web', value: 4280 },
+  { name: 'iOS', value: 3160 },
+]);
+</script>
+<template>
+<PieChart :data="data" inner-radius="62%" :loading="loading">
+    <template #empty>该时段没有调用记录</template>
+  </PieChart>
+</template>
+```
+
+### 交互说明
+
+- **占比计算**：按**可见**分片求和；隐藏某个分片后，其余分片重新分配角度，中心合计同步更新。
+- **单分片**：只有一个可见分片时不做缝隙，渲染为完整圆（否则会被切掉一小角，看起来像渲染错误）。
+- **小分片标签**：占比低于 4% 的分片不绘制外围标签，避免标签挤在一起；`tooltip` 与 `legend` 仍可查看其数值。
+- **零值处理**：值为 0、负数或非有限数的分片不渲染，也不计入总量。
+- **键盘导航**：画布可聚焦，左右方向键在分片间循环移动、Home / End 跳到首尾、Esc 关闭提示；键盘导航时通过 `aria-live` 播报。
+- **性能**：分片数量建议控制在 7 个以内，既符合可视化最佳实践，也避免 `stroke` 描边在细长分片上糊成一片。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./pie-chart-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/popconfirm-api.md

@@ -0,0 +1,75 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Popconfirm 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Popconfirm API
+
+公开声明：`dist/components/popconfirm/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 是否显示气泡，未传时使用内部状态 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultVisible | 默认是否显示气泡，非受控模式使用 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| width | 气泡宽度 | undefined &#124; string &#124; number | 否 | 150 |
+| type | 类型 | undefined &#124; "success" &#124; "warning" &#124; "strong" &#124; "info" &#124; "primary" &#124; "danger" | 否 | "danger" |
+| content | 确认内容 | undefined &#124; string &#124; number | 否 | 未声明 |
+| position | 弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "right" &#124; "left" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" &#124; "lt" &#124; "rt" &#124; "lb" &#124; "rb" | 否 | "top" |
+| okText | 确认按钮文案 | undefined &#124; string | 否 | undefined |
+| cancelText | 取消按钮文案 | undefined &#124; string | 否 | undefined |
+| okLoading | 确认按钮是否为 loading | undefined &#124; false &#124; true | 否 | false |
+| okButtonProps | 确认按钮 props | undefined &#124; { disabled?: boolean; block?: boolean; loading?: boolean; loadingFill?: boolean; debounce?: number; shape?: ButtonShape; link?: boolean; type?: ButtonTypes; htmlType?: ButtonHtmlType; status?: ButtonStatus; plain?: boolean; size?: ButtonSize; border?: boolean; narrow?: boolean; } | 否 | 未声明 |
+| cancelButtonProps | 取消按钮 props | undefined &#124; { disabled?: boolean; block?: boolean; loading?: boolean; loadingFill?: boolean; debounce?: number; shape?: ButtonShape; link?: boolean; type?: ButtonTypes; htmlType?: ButtonHtmlType; status?: ButtonStatus; plain?: boolean; size?: ButtonSize; border?: boolean; narrow?: boolean; } | 否 | 未声明 |
+| onBeforeOk | 确认前拦截，返回 false 阻止关闭；返回 Promise 时确认按钮进入 loading | undefined &#124; (e: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> | 否 | undefined |
+| onBeforeCancel | 取消前拦截，返回 false 阻止关闭；返回 Promise 时取消按钮进入 loading | undefined &#124; (e: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> | 否 | undefined |
+| renderTo | 弹层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| renderToBody | 是否挂载到容器；关闭后可配合 Trigger 逻辑控制 Teleport | undefined &#124; false &#124; true | 否 | true |
+| unmountOnClose | 关闭时是否卸载弹层节点 | undefined &#124; false &#124; true | 否 | true |
+| popupClass | 弹层自定义类名 | undefined &#124; string | 否 | 未声明 |
+| contentClass | 弹层内容自定义类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| contentStyle | 弹层内容自定义样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| arrowClass | 箭头自定义类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| arrowStyle | 箭头自定义样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| ok | 点击确认且未被拦截时触发 | undefined &#124; (...args: any[]) => any |
+| cancel | 点击取消且未被拦截时触发 | undefined &#124; (...args: any[]) => any |
+| change | 显隐状态变化时触发 | undefined &#124; (...args: any[]) => any |
+| update:modelValue | 显隐状态变化时触发，用于 v-model | undefined &#124; (...args: any[]) => any |
+| beforeCancel | 见场景用法与类型 | undefined &#124; (e: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> |
+| beforeOk | 见场景用法与类型 | undefined &#124; (e: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 触发元素 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| content | 自定义确认内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| icon | 自定义默认内容布局中的图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+declare const positions: readonly ["top", "tl", "tr", "bottom", "bl", "br", "left", "lt", "lb", "right", "rt", "rb"];
+
+type Position = (typeof positions)[number];
+
+type PopconfirmTypes = 'primary' | 'success' | 'warning' | 'strong' | 'danger' | 'info';
+```
+
+
+返回 [Popconfirm 用法](./popconfirm.md)。

package/AI_USAGE/components/popconfirm.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Popconfirm AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Popconfirm`；模型：v-model；已核对事件：ok、cancel。
+先读 [通用接入](../core.md)。公开导出：`Popconfirm`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./popconfirm-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`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` 监听器不会自动阻止关闭。
@@ -30,4 +32,230 @@ function cancel(_event: Event) { feedback.value = '已取消删除'; }
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/popconfirm.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./popconfirm-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于在按钮或链接旁边完成低成本二次确认。
+
+
+### 何时使用
+
+- 操作会产生删除、提交、发布等不可直接撤销的结果。
+- 不需要打断整页流程，只需要在触发元素附近让用户二次确认。
+- 确认内容较短，适合在小型气泡中展示。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popconfirm, Button } from 'x-next';
+const handleOk = (event: Event) => {
+  console.log('ok', event);
+};
+
+const handleCancel = (event: Event) => {
+  console.log('cancel', event);
+};
+</script>
+<template>
+<Popconfirm content="确认删除这条记录？" @ok="handleOk" @cancel="handleCancel">
+    <Button status="danger">删除</Button>
+  </Popconfirm>
+</template>
+```
+
+### 类型
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popconfirm, Button } from 'x-next';
+
+</script>
+<template>
+<div class="demo-inline-group">
+    <Popconfirm type="danger" content="危险操作确认？">
+      <Button status="danger">Danger</Button>
+    </Popconfirm>
+    <Popconfirm type="warning" content="继续执行风险操作？">
+      <Button status="warning">Warning</Button>
+    </Popconfirm>
+    <Popconfirm type="success" content="确认完成任务？">
+      <Button status="success">Success</Button>
+    </Popconfirm>
+  </div>
+</template>
+```
+
+### 位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popconfirm, Button } from 'x-next';
+
+</script>
+<template>
+<div class="demo-inline-group">
+    <Popconfirm position="top" content="上方弹出">
+      <Button>Top</Button>
+    </Popconfirm>
+    <Popconfirm position="bottom" content="下方弹出">
+      <Button>Bottom</Button>
+    </Popconfirm>
+    <Popconfirm position="left" content="左侧弹出">
+      <Button>Left</Button>
+    </Popconfirm>
+    <Popconfirm position="right" content="右侧弹出">
+      <Button>Right</Button>
+    </Popconfirm>
+  </div>
+</template>
+```
+
+### 受控显示
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Popconfirm, Button } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+</script>
+<template>
+<Space>
+    <Popconfirm v-model="visible" content="确认提交当前表单？" position="bottom">
+      <Button type="primary">提交</Button>
+    </Popconfirm>
+    <Button @click="visible = true">外部打开</Button>
+    <Button @click="visible = false">外部关闭</Button>
+  </Space>
+</template>
+```
+
+### 默认显示
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popconfirm, Button } from 'x-next';
+
+</script>
+<template>
+<Popconfirm default-visible content="默认打开，点击取消或确认会关闭">
+    <Button>默认打开</Button>
+  </Popconfirm>
+</template>
+```
+
+### 异步拦截
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popconfirm, Button } from 'x-next';
+const beforeOk = () => {
+  return new Promise<boolean>((resolve) => {
+    window.setTimeout(() => resolve(true), 1000);
+  });
+};
+
+const handleOk = () => {
+  console.log('confirmed');
+};
+</script>
+<template>
+<Popconfirm content="1 秒后完成确认" :on-before-ok="beforeOk" @ok="handleOk">
+    <Button type="primary">异步确认</Button>
+  </Popconfirm>
+</template>
+```
+
+### 按钮状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Popconfirm, Button } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+const saving = ref(false);
+
+const handleOk = () => {
+  visible.value = false;
+};
+</script>
+<template>
+<Space>
+    <Popconfirm
+      v-model="visible"
+      content="确认按钮 loading 可由外部状态控制"
+      ok-text="保存"
+      :ok-loading="saving"
+      :ok-button-props="{ status: 'success' }"
+      :cancel-button-props="{ type: 'text' }"
+      @ok="handleOk"
+    >
+      <Button>按钮 Props</Button>
+    </Popconfirm>
+    <Button @click="saving = !saving">
+      {{ saving ? '关闭 loading' : '开启 loading' }}
+    </Button>
+  </Space>
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popconfirm, Button } from 'x-next';
+
+</script>
+<template>
+<Popconfirm width="240" ok-text="归档" cancel-text="取消">
+    <Button>归档项目</Button>
+    <template #icon>
+      <span class="demo-popconfirm-icon">!</span>
+    </template>
+    <template #content>
+      <div class="demo-popconfirm-content">
+        <strong>归档后项目将移入历史列表</strong>
+        <span>团队成员仍可在历史项目中查看。</span>
+      </div>
+    </template>
+  </Popconfirm>
+</template>
+```
+
+### 禁用状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popconfirm, Button } from 'x-next';
+
+</script>
+<template>
+<Popconfirm disabled content="禁用后不会弹出">
+    <Button disabled>禁用触发</Button>
+  </Popconfirm>
+</template>
+```
+
+### 已知限制
+
+- Popconfirm 现在基于 `Trigger` 实现，滚动更新、外部点击关闭和箭头定位遵循 Trigger 当前行为。
+- Esc 关闭目前在焦点位于弹层内时生效，触发元素仍依赖原生按钮键盘行为。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./popconfirm-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/popover-api.md

@@ -0,0 +1,75 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Popover 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Popover API
+
+公开声明：`dist/components/popover/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| popupVisible | 弹出层是否可见，支持 v-model:popup-visible | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认是否显示，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| trigger | 触发方式 | undefined &#124; "click" &#124; "hover" &#124; "focus" &#124; "contextMenu" &#124; ("click" &#124; "hover" &#124; "focus" &#124; "contextMenu")[] | 否 | "click" |
+| position | 弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "right" &#124; "left" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" &#124; "lt" &#124; "rt" &#124; "lb" &#124; "rb" | 否 | "bottom" |
+| title | 标题内容 | undefined &#124; string &#124; number | 否 | 未声明 |
+| content | 正文内容 | undefined &#124; string &#124; number | 否 | 未声明 |
+| disabled | 是否禁用触发 | undefined &#124; false &#124; true | 否 | false |
+| popupOffset | 弹出层与触发元素的距离 | undefined &#124; number | 否 | 8 |
+| popupTranslate | 在原位置基础上的偏移量 | undefined &#124; [number, number] &#124; { top?: [number, number] &#124; undefined; bottom?: [number, number] &#124; undefined; right?: [number, number] &#124; undefined; left?: [number, number] &#124; undefined; tl?: [number, number] &#124; undefined; tr?: [number, number] &#124; undefined; bl?: [number, number] &#124; undefined; br?: [number, number] &#124; undefined; lt?: [number, number] &#124; undefined; rt?: [number, number] &#124; undefined; lb?: [number, number] &#124; undefined; rb?: [number, number] &#124; undefined; } | 否 | 未声明 |
+| showArrow | 是否显示箭头 | undefined &#124; false &#124; true | 否 | false |
+| alignPoint | 是否跟随鼠标点定位，常用于右键菜单 | undefined &#124; false &#124; true | 否 | false |
+| popupHoverStay | hover 触发时移入浮层是否保持显示 | undefined &#124; false &#124; true | 否 | true |
+| blurToClose | focus 触发时失焦是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| clickToClose | 点击触发器时是否允许关闭 | undefined &#124; false &#124; true | 否 | true |
+| clickOutsideToClose | 点击外部区域是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| unmountOnClose | 关闭后是否卸载浮层节点 | undefined &#124; false &#124; true | 否 | true |
+| contentClass | 弹出内容类名 | undefined &#124; string &#124; { [x: string]: boolean; } &#124; (string &#124; Record<string, boolean>)[] | 否 | 未声明 |
+| contentStyle | 弹出内容样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| arrowClass | 箭头类名 | undefined &#124; string &#124; { [x: string]: boolean; } &#124; (string &#124; Record<string, boolean>)[] | 否 | 未声明 |
+| arrowStyle | 箭头样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| popupStyle | 弹出层定位节点样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| animationName | 动画名称 | undefined &#124; string | 否 | "x-zoom-in-fade-out" |
+| duration | 动画时长 | undefined &#124; number &#124; { enter: number; leave: number; } | 否 | 未声明 |
+| mouseEnterDelay | mouseenter 延迟触发时间，单位毫秒 | undefined &#124; number | 否 | 100 |
+| mouseLeaveDelay | mouseleave 延迟关闭时间，单位毫秒 | undefined &#124; number | 否 | 100 |
+| focusDelay | focus 延迟触发时间，单位毫秒 | undefined &#124; number | 否 | 0 |
+| autoFitPopupWidth | 是否将浮层宽度设为触发器宽度 | undefined &#124; false &#124; true | 否 | false |
+| autoFitPopupMinWidth | 是否将浮层最小宽度设为触发器宽度 | undefined &#124; false &#124; true | 否 | false |
+| autoFixPosition | 触发器尺寸变化时是否重新计算位置 | undefined &#124; false &#124; true | 否 | true |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| updateAtScroll | 容器滚动时是否更新浮层位置 | undefined &#124; false &#124; true | 否 | false |
+| autoFitPosition | 是否自动调整位置以适应视口 | undefined &#124; false &#124; true | 否 | true |
+| renderToBody | 是否挂载到 body 体系下 | undefined &#124; false &#124; true | 否 | true |
+| preventFocus | 是否阻止浮层内元素点击时获得焦点 | undefined &#124; false &#124; true | 否 | false |
+| scrollToClose | 滚动时是否关闭浮层 | undefined &#124; false &#124; true | 否 | false |
+| scrollToCloseDistance | 滚动关闭阈值 | undefined &#124; number | 否 | 0 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:popupVisible | 显隐状态更新时触发 | undefined &#124; (visible: boolean) => any |
+| popupVisibleChange | 显隐状态变化时触发 | undefined &#124; (visible: boolean) => any |
+| show | 显示动画结束后触发 | undefined &#124; () => any |
+| hide | 隐藏动画结束后触发 | undefined &#124; () => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 触发元素 | any |
+| title | 标题内容 | any |
+| content | 正文内容 | any |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Popover 用法](./popover.md)。