x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/draggable.md

@@ -0,0 +1,259 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Draggable AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Draggable`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./draggable-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/base.css`（包含 base.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/draggable.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./draggable-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+基于 SortableJS 封装的列表拖拽排序能力，适合任务排序、跨列表流转、物料选择和轻量级编排场景。
+
+
+### 何时使用
+
+- 需要让用户调整一组同级数据的显示顺序。
+- 需要在多个列表之间移动或复制条目。
+- 需要组合 SortableJS 的高级能力，同时希望数据由 Vue 响应式状态驱动。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Draggable } from 'x-next';
+import { ref } from 'vue';
+
+const list = ref([
+  { id: 1, title: '需求评审' },
+  { id: 2, title: '交互设计' },
+  { id: 3, title: '组件实现' },
+]);
+</script>
+<template>
+<Draggable v-model="list" animation="150" ghost-class="ghost">
+    <div v-for="item in list" :key="item.id" class="item">
+      {{ item.title }}
+    </div>
+  </Draggable>
+</template>
+```
+
+### 拖拽手柄
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Draggable } from 'x-next';
+import { computed, ref } from 'vue';
+type Task = {
+  id: number;
+  title: string;
+  desc?: string;
+  locked?: boolean;
+};
+const handleList = ref<Task[]>([
+  { id: 11, title: '表单校验' },
+  { id: 12, title: '弹窗反馈' },
+  { id: 13, title: '列表排序' },
+]);
+
+const list = handleList;
+</script>
+<template>
+<Draggable v-model="list" handle=".drag-handle" animation="150">
+    <div v-for="item in list" :key="item.id">
+      <button class="drag-handle" type="button" aria-label="拖拽排序">⋮⋮</button>
+      <span>{{ item.title }}</span>
+    </div>
+  </Draggable>
+</template>
+```
+
+### 禁用状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Draggable } from 'x-next';
+import { ref } from 'vue';
+
+const disabled = ref(false);
+const list = ref([{ id: 1, title: '可拖拽项' }]);
+</script>
+<template>
+<Button @click="disabled = !disabled">
+    {{ disabled ? '恢复拖拽' : '禁用拖拽' }}
+  </Button>
+  <Draggable v-model="list" :disabled="disabled">
+    <div v-for="item in list" :key="item.id">{{ item.title }}</div>
+  </Draggable>
+</template>
+```
+
+### 跨列表拖拽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Draggable } from 'x-next';
+import { computed, ref } from 'vue';
+type Task = {
+  id: number;
+  title: string;
+  desc?: string;
+  locked?: boolean;
+};
+const todoList = ref<Task[]>([
+  { id: 31, title: '补 Props 表' },
+  { id: 32, title: '补 Events 表' },
+  { id: 33, title: '补 Methods 表' },
+]);
+const doneList = ref<Task[]>([
+  { id: 41, title: '基础示例' },
+]);
+
+const todo = todoList;
+const done = doneList;
+</script>
+<template>
+<Draggable
+    v-model="todo"
+    class="drop-list"
+    :group="{ name: 'tasks' }"
+    ghost-class="ghost"
+    chosen-class="chosen"
+    :empty-insert-threshold="48"
+  >
+    <div v-for="item in todo" :key="item.id">{{ item.title }}</div>
+  </Draggable>
+  <Draggable
+    v-model="done"
+    class="drop-list"
+    :group="{ name: 'tasks' }"
+    ghost-class="ghost"
+    chosen-class="chosen"
+    :empty-insert-threshold="48"
+  >
+    <div v-for="item in done" :key="item.id">{{ item.title }}</div>
+  </Draggable>
+</template>
+```
+
+### 克隆模式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Draggable } from 'x-next';
+import { computed, ref } from 'vue';
+type Task = {
+  id: number;
+  title: string;
+  desc?: string;
+  locked?: boolean;
+};
+const cloneSource = ref<Task[]>([
+  { id: 51, title: '输入框' },
+  { id: 52, title: '选择器' },
+  { id: 53, title: '按钮' },
+]);
+const cloneTarget = ref<Task[]>([
+  { id: 61, title: '表单区块' },
+]);
+let cloneId = 100;
+const cloneTask = (item: Task) => ({
+  ...item,
+  id: cloneId++,
+  title: `${item.title}副本`,
+});
+
+const source = cloneSource;
+const target = cloneTarget;
+const cloneItem = cloneTask;
+</script>
+<template>
+<Draggable
+    v-model="source"
+    :group="{ name: 'builder', pull: 'clone', put: false }"
+    :sort="false"
+    :clone="cloneItem"
+  >
+    <div v-for="item in source" :key="item.id">{{ item.title }}</div>
+  </Draggable>
+  <Draggable
+    v-model="target"
+    class="drop-list"
+    :group="{ name: 'builder' }"
+    ghost-class="ghost"
+    :empty-insert-threshold="48"
+  >
+    <div v-for="item in target" :key="item.id">{{ item.title }}</div>
+  </Draggable>
+</template>
+```
+
+### 事件与移动限制
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Draggable } from 'x-next';
+import { ref } from 'vue';
+
+const sortableList = ref([
+  { id: 1, title: '可排序任务 A' },
+  { id: 2, title: '可排序任务 B' },
+  { id: 3, title: '可排序任务 C' },
+]);
+const allowMove = () => true;
+const handleMove = (event: import('x-next').DraggableEvent) => {
+  console.log('move', event.oldDraggableIndex, event.newDraggableIndex);
+};
+const handleEnd = (event: import('x-next').DraggableEvent) => {
+  console.log(event.oldDraggableIndex, event.newDraggableIndex);
+};
+</script>
+<template>
+<div class="fixed-item">固定在顶部</div>
+  <Draggable v-model="sortableList" :allow-move="allowMove" @move="handleMove" @end="handleEnd">
+    <div v-for="item in sortableList" :key="item.id">
+      {{ item.title }}
+    </div>
+  </Draggable>
+</template>
+```
+
+### 指令用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { vDraggable } from 'x-next';
+import { ref } from 'vue';
+
+const list = ref([{ id: 1, title: '指令挂载' }]);
+</script>
+<template>
+<div v-draggable="[list, { animation: 150 }]">
+    <div v-for="item in list" :key="item.id">{{ item.title }}</div>
+  </div>
+</template>
+```
+
+### 已知限制
+
+- 当前键盘排序和屏幕阅读器提示仍需业务侧自行补充。
+- `@move` 是 Vue 事件监听，若要通过返回 `false` 阻止移动，请使用 `:allow-move` 或 `:move-validator`。
+- 使用 `draggable` / `filter` 时，列表数据应只对应可拖拽项。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./draggable-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/drawer-api.md

@@ -0,0 +1,78 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Drawer 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Drawer API
+
+公开声明：`dist/components/drawer/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| disabled | 是否禁用 Teleport | undefined &#124; false &#124; true | 否 | false |
+| modelValue | 是否显示抽屉 | undefined &#124; false &#124; true | 否 | false |
+| placement | 抽屉弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "right" &#124; "left" | 否 | "right" |
+| title | 标题 | undefined &#124; string | 否 | "" |
+| mask | 是否显示遮罩 | undefined &#124; false &#124; true | 否 | true |
+| showFooter | 是否显示底部操作区 | undefined &#124; false &#124; true | 否 | true |
+| maskToClose | 点击遮罩是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| escToClose | 按下 Esc 是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| destroyOnClosed | 关闭后是否销毁内容 | undefined &#124; false &#124; true | 否 | true |
+| width | 左右抽屉宽度 | undefined &#124; string &#124; number | 否 | 340 |
+| height | 上下抽屉高度 | undefined &#124; string &#124; number | 否 | 340 |
+| okText | 确认按钮文案 | undefined &#124; string | 否 | "" |
+| cancelText | 取消按钮文案 | undefined &#124; string | 否 | "" |
+| 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; } | 否 | 未声明 |
+| hideCancel | 是否隐藏默认取消按钮 | undefined &#124; false &#124; true | 否 | false |
+| onBeforeOk | 确认前拦截，返回 false 阻止关闭 | undefined &#124; (event?: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> | 否 | 未声明 |
+| onBeforeCancel | 取消前拦截，返回 false 阻止关闭 | undefined &#124; (event?: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> | 否 | 未声明 |
+| renderTo | 挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | "body" |
+| popupClass | 最外层自定义类名 | undefined &#124; string | 否 | undefined |
+| drawerStyle | 最外层样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| bodyClass | body 自定义类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| bodyStyle | body 自定义样式 | undefined &#124; null &#124; string &#124; false &#124; CSSProperties &#124; StyleValue[] | 否 | 未声明 |
+| showClose | 是否显示关闭按钮 | undefined &#124; false &#124; true | 否 | true |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 显隐状态变化时触发 | undefined &#124; (...args: any[]) => any |
+| close | 请求关闭且未被拦截时触发 | undefined &#124; (...args: any[]) => any |
+| closed | 关闭动画结束后触发 | undefined &#124; (...args: any[]) => any |
+| open | 打开时触发 | undefined &#124; (...args: any[]) => any |
+| opened | 打开动画结束后触发 | undefined &#124; (...args: any[]) => any |
+| ok | 点击确认且未被拦截时触发 | undefined &#124; (...args: any[]) => any |
+| cancel | 点击取消、关闭、遮罩或 Esc 且未被拦截时触发 | undefined &#124; (...args: any[]) => any |
+| beforeCancel | 见场景用法与类型 | undefined &#124; (event?: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> |
+| beforeOk | 见场景用法与类型 | undefined &#124; (event?: Event) => boolean &#124; void &#124; Promise<boolean &#124; void> |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 抽屉主体内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| title | 自定义标题 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| footer | 自定义底部操作区 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| fill | 完全自定义抽屉内部结构 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type Placement = 'top' | 'right' | 'bottom' | 'left';
+```
+
+
+返回 [Drawer 用法](./drawer.md)。

package/AI_USAGE/components/drawer.md

@@ -0,0 +1,227 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Drawer AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Drawer`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./drawer-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/drawer`（包含 base.css、button.css、drawer.css、scrollbar-v2.css、space.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/drawer.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./drawer-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+从屏幕边缘展开内容，适合详情、编辑和辅助配置。
+
+
+### 何时使用
+
+- 需要在不离开当前页面的情况下查看详情、编辑表单或配置参数。
+- 内容比 Popconfirm、Tooltip 更复杂，但又不需要 Dialog 那样强打断。
+- 希望任务完成后回到原页面上下文。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Drawer } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+</script>
+<template>
+<Button type="primary" @click="visible = true">打开抽屉</Button>
+  <Drawer v-model="visible" title="详情">
+    抽屉内容
+  </Drawer>
+</template>
+```
+
+### 位置与尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Drawer } from 'x-next';
+import { ref } from 'vue';
+const rightVisible = ref(false);
+
+const visible = rightVisible;
+</script>
+<template>
+<Drawer v-model="visible" placement="bottom" height="300px" title="底部抽屉">
+    内容
+  </Drawer>
+</template>
+```
+
+### 受控与事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Drawer } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+const handleOk = (event?: Event) => console.log('ok', event);
+const handleCancel = (event?: Event) => console.log('cancel', event);
+const handleClose = (action: 'ok' | 'cancel', event?: Event) => console.log(action, event);
+</script>
+<template>
+<Drawer
+    v-model="visible"
+    title="事件记录"
+    @ok="handleOk"
+    @cancel="handleCancel"
+    @close="handleClose"
+  >
+    内容
+  </Drawer>
+</template>
+```
+
+### 异步关闭
+
+等待期间确认、取消、关闭图标、遮罩和 Escape 共用防重保护；重复操作不会再次调用拦截回调。回调返回 false、抛错或拒绝时保持打开。外部关闭后重新打开，旧等待结果不会关闭新一轮。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Drawer } from 'x-next';
+import { ref } from 'vue';
+const visible = ref(false);
+const beforeOk = async () => {
+  await new Promise((resolve) => window.setTimeout(resolve, 1000));
+  return true;
+};
+</script>
+<template>
+<Drawer v-model="visible" title="提交确认" :on-before-ok="beforeOk">
+    点击确认后等待异步校验。
+  </Drawer>
+</template>
+```
+
+### 嵌套浮层、卸载与键盘
+
+打开 Drawer 后进入首个可聚焦元素，有遮罩时 Tab / Shift+Tab 在内部循环；无遮罩时不限制 Tab。关闭或卸载后归还原焦点，已移到其他交互区域的焦点会保留。无标题或使用 fill 时，可用 `aria-label` / `aria-labelledby` 给对话框命名。
+
+Drawer 与 Dialog 共用顺序焦点规则：正 tabindex 排序后再进入默认顺序，具名原生 radio 组优先进入选中项；建议保持默认 DOM 顺序。用键盘激活打开按钮可验证焦点归还。Button 鼠标点击会主动 blur，打开前焦点可能为 body，此时没有按钮焦点可归还。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, DialogComponent, Drawer, Input } from 'x-next';
+import { ref } from 'vue';
+const dialog = ref(false);
+const drawer = ref(false);
+const mounted = ref(true);
+import type { InputHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "抽屉内容" } satisfies InputHTMLAttributes;
+</script>
+<template>
+<Button @click="dialog = true">打开底层 Dialog</Button>
+  <DialogComponent v-model="dialog" title="底层对话框">
+    <Button @click="mounted = true; drawer = true">打开上层 Drawer</Button>
+    <p>卸载 Drawer 后，在此按 Escape 可以继续关闭。</p>
+    <Drawer v-if="mounted" v-model="drawer" title="上层抽屉" :show-footer="false">
+      <Input :input-attrs="nativeAttrs1"  placeholder="Tab 检查焦点循环" />
+      <Button @click="mounted = false; drawer = false">直接卸载本层</Button>
+    </Drawer>
+  </DialogComponent>
+</template>
+```
+
+### 遮罩和关闭
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Drawer } from 'x-next';
+import { ref } from 'vue';
+const maskVisible = ref(false);
+
+const visible = maskVisible;
+</script>
+<template>
+<Drawer
+    v-model="visible"
+    title="无遮罩"
+    :mask="false"
+    :mask-to-close="false"
+    :esc-to-close="false"
+    :show-close="false"
+  >
+    内容
+  </Drawer>
+</template>
+```
+
+### 自定义 Footer
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Drawer, Space, Button } from 'x-next';
+import { ref } from 'vue';
+const footerVisible = ref(false);
+
+const visible = footerVisible;
+</script>
+<template>
+<Drawer v-model="visible" title="自定义 Footer">
+    内容
+    <template #footer="{ ok, cancel, loadingObj }">
+      <Space>
+        <Button type="text" :loading="loadingObj.cancel" @click="cancel">
+          稍后处理
+        </Button>
+        <Button type="primary" :loading="loadingObj.ok" @click="ok">
+          保存
+        </Button>
+      </Space>
+    </template>
+  </Drawer>
+</template>
+```
+
+### 局部容器
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Drawer } from 'x-next';
+import { ref } from 'vue';
+const localVisible = ref(false);
+
+const visible = localVisible;
+</script>
+<template>
+<Button @click="visible = true">打开局部抽屉</Button>
+  <div id="drawer-local-container" class="demo-drawer-local-container">
+    局部容器
+  </div>
+  <Drawer
+    v-model="visible"
+    render-to="#drawer-local-container"
+    title="局部抽屉"
+    width="260px"
+  >
+    内容
+  </Drawer>
+</template>
+```
+
+### 已知限制
+
+- 当前暂不提供命令式 `Drawer.open()`。
+- 多层 Drawer push、`extra`、自定义关闭图标等能力后续再评估。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./drawer-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。