x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/dropdown.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Dropdown AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
 
-先读 [通用接入](../core.md)。公开导出：`Dropdown`；模型：v-model:popup-visible；已核对事件：select、popupVisibleChange。
+先读 [通用接入](../core.md)。公开导出：`Dropdown, DropdownButton, DropdownGroup, DropdownOption, DropdownSubmenu`；主要模型：v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./dropdown-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`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 自动关闭仍有边界，不能据方向键导航推断这些能力已实现。
@@ -35,4 +37,391 @@ function select(value: unknown, _event: Event) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/dropdown.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./dropdown-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于承载一组收起的操作项或选择项，适合页面操作过多、需要按触发器就近展开菜单的场景。
+
+
+### 何时使用
+
+- 页面或列表行操作较多，需要把低频操作收纳起来。
+- 触发元素附近展示命令菜单，比 Dialog 或 Drawer 更轻量。
+- 菜单内容较短，用户选择后通常立即关闭浮层。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownOption } from 'x-next';
+import { ref } from 'vue';
+
+const selected = ref('未选择');
+
+const handleSelect = (value: unknown) => {
+  selected.value = String(value ?? '未选择');
+};
+</script>
+<template>
+<Dropdown @select="handleSelect">
+    <Button>更多操作</Button>
+    <template #content>
+      <DropdownOption value="edit">编辑</DropdownOption>
+      <DropdownOption value="copy">复制</DropdownOption>
+      <DropdownOption value="delete" disabled>删除</DropdownOption>
+    </template>
+  </Dropdown>
+  <p>当前选择：{{ selected }}</p>
+</template>
+```
+
+### 键盘操作
+
+聚焦触发按钮后按 Enter、Space 或 ArrowDown 打开首个启用项，ArrowUp 打开最后一项。菜单使用单个 Tab 停靠点；方向键循环、Home/End 跳到首尾，禁用项自动跳过。子菜单用 ArrowRight 进入，ArrowLeft 或 Escape 返回父项，根菜单 Escape 关闭后回到触发按钮。
+
+受控模式只在外部接受显隐请求后转移或归还焦点。鼠标悬浮打开不会主动抢走焦点。菜单项内部的自定义输入框保留其自己的方向键处理；本轮不提供字符搜索或 Tab 自动关闭行为。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Dropdown, DropdownOption, DropdownSubmenu } from 'x-next';
+import 'x-next/dist/style.css';
+
+const visible = ref(false);
+const selected = ref('未选择');
+</script>
+<template>
+<Dropdown v-model:popup-visible="visible" @select="(value) => selected = String(value)">
+    <Button>键盘操作菜单</Button>
+    <template #content>
+      <DropdownOption value="edit">编辑</DropdownOption>
+      <DropdownOption value="delete" disabled>删除</DropdownOption>
+      <DropdownSubmenu>
+        更多
+        <template #content>
+          <DropdownOption value="copy">复制</DropdownOption>
+          <DropdownOption value="archive">归档</DropdownOption>
+        </template>
+      </DropdownSubmenu>
+      <DropdownOption value="export">导出</DropdownOption>
+    </template>
+  </Dropdown>
+  <p role="status">{{ visible ? '打开' : '关闭' }}；{{ selected }}</p>
+</template>
+```
+
+### 弹出位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownOption } from 'x-next';
+
+</script>
+<template>
+<div class="demo-inline-group">
+    <Dropdown position="top">
+      <Button>Top</Button>
+      <template #content>
+        <DropdownOption value="edit">编辑</DropdownOption>
+        <DropdownOption value="copy">复制</DropdownOption>
+      </template>
+    </Dropdown>
+    <Dropdown position="br">
+      <Button>BR</Button>
+      <template #content>
+        <DropdownOption value="edit">编辑</DropdownOption>
+        <DropdownOption value="copy">复制</DropdownOption>
+      </template>
+    </Dropdown>
+  </div>
+</template>
+```
+
+### 触发方式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownOption } from 'x-next';
+
+</script>
+<template>
+<div class="demo-inline-group">
+    <Dropdown trigger="click">
+      <Button>点击触发</Button>
+      <template #content>
+        <DropdownOption value="click">点击菜单</DropdownOption>
+      </template>
+    </Dropdown>
+    <Dropdown trigger="hover">
+      <Button>悬浮触发</Button>
+      <template #content>
+        <DropdownOption value="hover">悬浮菜单</DropdownOption>
+      </template>
+    </Dropdown>
+  </div>
+</template>
+```
+
+### 受控显示
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Dropdown, Button, DropdownOption } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+
+const handleSelect = (value: unknown) => {
+  console.log(value);
+};
+</script>
+<template>
+<Space>
+    <Dropdown v-model:popup-visible="visible" @select="handleSelect">
+      <Button type="primary">受控菜单</Button>
+      <template #content>
+        <DropdownOption value="save">保存</DropdownOption>
+        <DropdownOption value="publish">发布</DropdownOption>
+      </template>
+    </Dropdown>
+    <Button @click="visible = true">外部打开</Button>
+    <Button @click="visible = false">外部关闭</Button>
+  </Space>
+</template>
+```
+
+### 分组
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownGroup, DropdownOption } from 'x-next';
+const handleSelect = (value: unknown) => {
+  console.log(value);
+};
+</script>
+<template>
+<Dropdown @select="handleSelect">
+    <Button>项目操作</Button>
+    <template #content>
+      <DropdownGroup title="常用">
+        <DropdownOption value="rename">重命名</DropdownOption>
+        <DropdownOption value="duplicate">复制项目</DropdownOption>
+      </DropdownGroup>
+      <DropdownGroup title="危险">
+        <DropdownOption value="archive">归档</DropdownOption>
+        <DropdownOption value="delete" disabled>删除</DropdownOption>
+      </DropdownGroup>
+    </template>
+  </Dropdown>
+</template>
+```
+
+### 子菜单
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownOption, DropdownSubmenu } from 'x-next';
+const handleSelect = (value: unknown) => {
+  console.log(value);
+};
+</script>
+<template>
+<Dropdown @select="handleSelect">
+    <Button>导出</Button>
+    <template #content>
+      <DropdownOption value="quick-export">快速导出</DropdownOption>
+      <DropdownSubmenu trigger="hover">
+        更多格式
+        <template #content>
+          <DropdownOption value="csv">CSV</DropdownOption>
+          <DropdownOption value="xlsx">Excel</DropdownOption>
+          <DropdownOption value="pdf">PDF</DropdownOption>
+        </template>
+      </DropdownSubmenu>
+    </template>
+  </Dropdown>
+</template>
+```
+
+### 右键菜单
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, DropdownOption } from 'x-next';
+const handleSelect = (value: unknown) => {
+  console.log(value);
+};
+</script>
+<template>
+<Dropdown trigger="contextMenu" align-point @select="handleSelect">
+    <div class="context-target">在此区域右键打开菜单</div>
+    <template #content>
+      <DropdownOption value="refresh">刷新</DropdownOption>
+      <DropdownOption value="copy-link">复制链接</DropdownOption>
+      <DropdownOption value="open-new">新窗口打开</DropdownOption>
+    </template>
+  </Dropdown>
+</template>
+<style scoped>
+.context-target {
+  padding: 24px;
+  border: 1px dashed #94a3b8;
+}
+</style>
+```
+
+### 图标、后缀和页脚
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownOption } from 'x-next';
+const handleSelect = (value: unknown) => {
+  console.log(value);
+};
+</script>
+<template>
+<Dropdown @select="handleSelect">
+    <Button>账户菜单</Button>
+    <template #content>
+      <DropdownOption value="profile">
+        <template #icon><span>P</span></template>
+        个人资料
+        <template #suffix>⌘P</template>
+      </DropdownOption>
+      <DropdownOption value="settings">
+        <template #icon><span>S</span></template>
+        设置
+        <template #suffix>⌘,</template>
+      </DropdownOption>
+    </template>
+    <template #footer>
+      <div>菜单页脚</div>
+    </template>
+  </Dropdown>
+</template>
+```
+
+### 选择后保持打开
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownOption } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+</script>
+<template>
+<Dropdown v-model:popup-visible="visible" :hide-on-select="false">
+    <Button>批量操作</Button>
+    <template #content>
+      <DropdownOption value="select-all">全选</DropdownOption>
+      <DropdownOption value="invert">反选</DropdownOption>
+      <DropdownOption value="clear">清空选择</DropdownOption>
+    </template>
+    <template #footer>
+      <Button size="mini" @click="visible = false">完成</Button>
+    </template>
+  </Dropdown>
+</template>
+```
+
+### 空态、加载和滚动
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Dropdown, Button, DropdownOption } from 'x-next';
+import { ref } from 'vue';
+
+const reached = ref(false);
+const items = Array.from({ length: 18 }, (_, index) => ({
+  label: `操作 ${index + 1}`,
+  value: `action-${index + 1}`,
+}));
+</script>
+<template>
+<Dropdown is-empty>
+    <Button>空菜单</Button>
+    <template #empty>暂无可用操作</template>
+  </Dropdown>
+
+  <Dropdown
+    :popup-max-height="144"
+    :bottom-offset="8"
+    @reach-bottom="reached = true"
+  >
+    <Button>滚动菜单</Button>
+    <template #content>
+      <DropdownOption v-for="item in items" :key="item.value" :value="item.value">
+        {{ item.label }}
+      </DropdownOption>
+    </template>
+  </Dropdown>
+</template>
+```
+
+### 按钮式下拉
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DropdownButton, DropdownOption } from 'x-next';
+const handleClick = () => {
+  console.log('main button');
+};
+
+const handleSelect = (value: unknown) => {
+  console.log(value);
+};
+</script>
+<template>
+<div class="demo-inline-group">
+    <DropdownButton type="primary" @click="handleClick" @select="handleSelect">
+      新建
+      <template #content>
+        <DropdownOption value="new-file">新建文件</DropdownOption>
+        <DropdownOption value="new-folder">新建文件夹</DropdownOption>
+        <DropdownOption value="import">导入</DropdownOption>
+      </template>
+    </DropdownButton>
+
+    <DropdownButton @click="handleClick" @select="handleSelect">
+      Publish
+      <template #content>
+        <DropdownOption value="publish-now">立即发布</DropdownOption>
+        <DropdownOption value="schedule">定时发布</DropdownOption>
+      </template>
+    </DropdownButton>
+
+    <DropdownButton disabled>
+      Disabled
+      <template #content>
+        <DropdownOption value="disabled">不可用</DropdownOption>
+      </template>
+    </DropdownButton>
+  </div>
+</template>
+```
+
+### 交互说明
+
+- 菜单项支持鼠标点击，也支持聚焦后按 Enter 或 Space 触发。
+- 复杂菜单项建议显式传入 `value`，避免默认文本值受到图标、后缀或隐藏文本影响。
+- 多级菜单支持 ArrowRight 进入、ArrowLeft/Escape 返回，键盘选中后按 `hideOnSelect` 决定关闭。字符搜索、复杂自定义控件代理及菜单外 Tab 自动关闭仍未提供。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./dropdown-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/empty-api.md

@@ -0,0 +1,36 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Empty 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Empty API
+
+公开声明：`dist/components/empty/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| description | 描述内容；传入 null 或空字符串时隐藏描述区域 | undefined &#124; null &#124; string | 否 | undefined |
+| imgSrc | 自定义图片地址 | undefined &#124; string | 否 | 未声明 |
+| component | 见场景用法与类型 | undefined &#124; string | 否 | "empty" |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 自定义描述内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| image | 自定义图片或图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Empty 用法](./empty.md)。

package/AI_USAGE/components/empty.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Empty AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
 
-先读 [通用接入](../core.md)。公开导出：`Empty`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+先读 [通用接入](../core.md)。公开导出：`Empty`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./empty-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`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` 插槽接管。
@@ -27,4 +29,226 @@ function refresh() { refreshed.value = true; }
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/empty.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./empty-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于无数据、搜索无结果或空白占位状态。
+
+
+### 何时使用
+
+- 列表、表格、选择器等数据容器没有可展示内容时。
+- 搜索、筛选或加载后没有匹配结果时。
+- 需要用轻量占位提示用户当前区域为空时。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Empty } from 'x-next';
+
+</script>
+<template>
+<Empty />
+  <Empty description="暂无数据" />
+</template>
+```
+
+### 无描述
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Empty } from 'x-next';
+
+</script>
+<template>
+<Empty :description="null" />
+</template>
+```
+
+### 自定义图片
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Empty } from 'x-next';
+const emptyImageSrc =
+  'data:image/svg+xml;utf8,%3Csvg xmlns="http://www.w3.org/2000/svg" width="96" height="72" viewBox="0 0 96 72"%3E%3Crect x="12" y="10" width="72" height="52" rx="10" fill="%23f8fafc" stroke="%23cbd5e1" stroke-width="2"/%3E%3Cpath d="M30 31h36M30 42h24" stroke="%2394a3b8" stroke-width="6" stroke-linecap="round"/%3E%3C/svg%3E';
+</script>
+<template>
+<Empty :img-src="emptyImageSrc">暂无组件</Empty>
+</template>
+```
+
+### 自定义 image 插槽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Empty } from 'x-next';
+
+</script>
+<template>
+<Empty>
+    <template #image>
+      <span class="empty-image" aria-hidden="true">
+        <span class="empty-image-line"></span>
+        <span class="empty-image-line is-short"></span>
+      </span>
+    </template>
+    暂无组件
+  </Empty>
+</template>
+<style scoped>
+.empty-image {
+  display: inline-flex;
+  flex-direction: column;
+  justify-content: center;
+  width: 72px;
+  height: 56px;
+  padding: 12px;
+  background: #f8fafc;
+  border: 1px solid #dbe3ef;
+  border-radius: 8px;
+}
+
+.empty-image-line {
+  width: 100%;
+  height: 6px;
+  background: #cbd5e1;
+  border-radius: 999px;
+}
+
+.empty-image-line + .empty-image-line {
+  margin-top: 8px;
+}
+
+.empty-image-line.is-short {
+  width: 62%;
+}
+</style>
+```
+
+### 自定义图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Empty } from 'x-next';
+
+</script>
+<template>
+<Empty description="没有找到匹配结果">
+    <template #image>
+      <span class="empty-icon">?</span>
+    </template>
+  </Empty>
+</template>
+<style scoped>
+.empty-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 48px;
+  height: 48px;
+  color: #2563eb;
+  font-size: 24px;
+  font-weight: 600;
+  background: #eff6ff;
+  border: 1px solid #bfdbfe;
+  border-radius: 50%;
+}
+</style>
+```
+
+### 自定义描述
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Empty } from 'x-next';
+
+</script>
+<template>
+<Empty>
+    <span>当前筛选条件下没有数据，尝试放宽时间范围。</span>
+  </Empty>
+</template>
+```
+
+### 组合空态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select, Empty } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+</script>
+<template>
+<Select v-model="value" allow-search placeholder="搜索成员">
+    <template #empty>
+      <Empty description="没有匹配成员">
+        <template #image>
+          <span class="empty-small-icon">0</span>
+        </template>
+      </Empty>
+    </template>
+  </Select>
+</template>
+<style scoped>
+.empty-small-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  color: #64748b;
+  font-size: 16px;
+  background: #f8fafc;
+  border: 1px solid #e2e8f0;
+  border-radius: 50%;
+}
+</style>
+```
+
+### 全局空态配置
+
+`Empty` 会读取 `ConfigProvider` 的 `empty` 插槽，回调参数 `component` 标明请求来源（`empty` / `select` / `table` / `dropdown`），便于按组件区分空态。
+
+调用方显式传了 `description`、`imgSrc`、`image` 或默认插槽时以自身配置为准，`empty` 插槽只接管「裸空态」——否则组件上配置的内容会被全局配置静默覆盖。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Empty, Select } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+</script>
+<template>
+<ConfigProvider>
+    <template #empty="{ component }">
+      <Empty :description="`${component} 暂无内容`" />
+    </template>
+    <Empty />
+    <Select v-model="value" allow-search placeholder="搜索成员" />
+  </ConfigProvider>
+</template>
+```
+
+### 已知限制
+
+- 默认插画是多色美术资源，四层灰阶走 `--x-empty-illustration-*` token，会随亮/暗主题自动换色；它是定稿的图形，不支持通过 `--x-empty-image-color` 改色。需要自定义图形时请用 `imgSrc` 或 `image` 插槽。
+- `empty` 插槽只接管「裸空态」。调用方传了 `description`、`imgSrc`、默认插槽或 `image` 插槽时，以调用方配置为准，不再读取全局配置。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./empty-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。