@robot-admin/naive-ui-components 0.11.8 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @robot-admin/naive-ui-components
 
+## 0.13.0
+
+### Minor Changes
+
+- fc872e4: Release C_GlobalSearch's keyboard shortcut listener on unmount.
+
+  Keep CRUD delete feedback consistent with structured `{ data, error }` results and make tree `defaultExpandAll` work with controlled row expansion. Restore C_Table summaries in Naive UI's keyed-row format, validate persisted column settings, and avoid mutating caller-owned columns. Expose submit state and action in C_Form step slots, and harden C_FilePreview URL, auto-preview, loading, object-URL, and spreadsheet value handling. Tighten C_Icon's public types, isolate C_Editor focus styling to the component, make C_Chat preview, file, and retry actions keyboard accessible, and keep C_AudioPlayer state honest when playback fails or its playlist changes. Repair C_AntV BPMN domain-data round-trips and honor initial external BPMN/UML data. Make C_VtableGantt option merging prototype-safe and synchronize fullscreen state with the actual DOM lifecycle. Validate persisted C_CollapsePanel/C_TagsView state and avoid path interpolation in tag selectors. Isolate C_Upload's initial file list, consistently filter accepted picker/drop/paste files, label image actions, show per-file hashing progress, and make chunk cancellation effective throughout resume lookup, requests, and merging. Load initial C_WorkFlow models, isolate emitted snapshots and condition edits, honor readonly boundaries, prevent ID collisions, and clean up deferred view actions. Support timestamp and formatted string date ranges in C_FormSearch, hide decorative C_ActionBar icons from accessible names, and include Vue source templates in the verification gate.
+
+### Patch Changes
+
+- fc872e4: Harden smaller interaction components: keep login's remembered username current and reject malformed SMS recipients, load city data only when opened and scope letter navigation to each instance, make code actions keyboard-accessible and report modal close events, bound skeleton render counts, and synchronize menu expansion when route options arrive. Improve markdown, organization chart, timeline, tree, transfer, date/time, cascade, context menu, split pane, progress, avatar and step state and accessibility behavior.
+- fc872e4: Make image crop exports use one canvas snapshot, report failures, honor disabled state, and apply flips to the actual image. Make signature readonly mode effective, preserve imported/background images across redraws, and replace placeholder SVG output with a raster-backed SVG. Fix calendar local-date saving and reactive editable mode. Prevent stale QR renders, keep logo-bearing SVG exports consistent with previews, and relayout waterfall images by aspect ratio while suppressing duplicate infinite-load requests.
+- fc872e4: Keep C_NotificationCenter server read state authoritative, avoid duplicate popover toggles, forward WebSocket events, and validate action links before navigation. Prevent C_VideoPlayer from creating a player after unmount, remove duplicate shortcut/cleanup paths, and make mini-player controls keyboard accessible. Reject malformed C_Cron expressions without rewriting them, preview second-level schedules across the full search horizon, and honor disabled controls. Fix C_FormulaEditor logical operator evaluation, read-only input behavior, and keyboard accessibility.
+
+## 0.12.1
+
+### Minor Changes
+
+- Enhance `C_ActionBar` with semantic action presets, getter-based reactive states, guarded async loading, and icon-first compact `tiny` defaults, including consistent create/save/cancel/close actions for forms and details. Allow `C_Table` toolbars to consume the same left/right action model while preserving existing slots, configurable sizing, and independent table engines.
+
+- Polish the C_Captcha and C_Login verification flow with package-owned SVG state icons, explicit verification copy, theme variables, a visibility event for pausing expensive host effects, and a clearer verification-before-submit layout. Add an opt-in, lazily loaded ALTCHA provider for free self-hosted proof-of-work challenges while preserving the existing puzzle provider by default.
+
+- 新增公开的 `C_Tabs` 数据驱动紧凑标签页，支持 render、插槽、异步切换守卫、徽标、图标、关闭和 tabs-only 场景，并接入按需 Resolver 与独立样式入口。
+
+- Add `C_FormModal`, a compact data-driven create/edit modal that reuses `C_Form` and `C_ActionBar`, accepts any structurally compatible headless CRUD editor without coupling the component package to a request library, and keeps fields, validation, loading and footer actions out of business templates.
+
 ## 0.11.8
 
 ### Patch Changes

package/README.md

@@ -4,7 +4,7 @@
 
 **基于 Naive UI 的 Vue 3 企业级组件库**
 
-从 Robot Admin 中提炼的 51 个高质量业务组件，支持全量注册、按需导入（Tree-Shaking）和子路径独立导入。
+从 Robot Admin 中提炼的 53 个高质量业务组件，支持全量注册、按需导入（Tree-Shaking）和子路径独立导入。
 
 [![NPM Version](https://img.shields.io/npm/v/@robot-admin/naive-ui-components)](https://www.npmjs.com/package/@robot-admin/naive-ui-components)
 [![License](https://img.shields.io/npm/l/@robot-admin/naive-ui-components)](./LICENSE)
@@ -167,6 +167,42 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 </template>
 ```
 
+自定义操作栏应调用 `action` 插槽的 `submit()`，不要用 `validate()` 代替提交。步骤布局的 `step-actions` 插槽同时提供 `isLastStep`、`submit()` 和 `submitting`，可在最后一步直接放置提交按钮。异步保存放在 `config.onSubmit` 中并等待完成；`@submit` 是保存成功后的通知事件，不承诺等待监听器返回的 Promise。
+
+新增/编辑场景推荐用 `C_FormModal` 直接消费 Headless CRUD 的结构化 `editor`。字段、校验和布局继续由 `C_Form` 配置驱动，页面不再重复编写 Modal、按钮、loading 和草稿状态；默认采用紧凑小尺寸表单和右下角带图标操作按钮，宽度、表单尺寸与动作文案仍可覆盖：
+
+```vue
+<script setup lang="ts">
+  import { C_FormModal } from '@robot-admin/naive-ui-components/C_FormModal'
+  import type { FormModalEditor } from '@robot-admin/naive-ui-components/C_FormModal'
+  import {
+    defineFormConfig,
+    defineFormOptions,
+  } from '@robot-admin/naive-ui-components/C_Form'
+
+  interface UserForm {
+    name: string
+  }
+
+  defineProps<{ editor: FormModalEditor<UserForm> }>()
+
+  const fields = defineFormOptions<UserForm>([
+    { type: 'input', prop: 'name', label: '名称', required: true },
+  ])
+  const formConfig = defineFormConfig<UserForm>({ labelPlacement: 'top' })
+</script>
+
+<template>
+  <C_FormModal
+    :editor="editor"
+    :options="fields"
+    :config="formConfig"
+  />
+</template>
+```
+
+`editor` 采用结构类型，不要求组件库依赖某个请求库；任何提供 `visible/mode/model/title/loading/setModel/close/submit` 的 Headless 控制器都可接入。弹窗默认保留关闭按钮、遮罩关闭和 Esc 行为，也可按高风险表单显式关闭。
+
 远程表格推荐交给 `useTableQuery` 管理请求取消、竞态、分页和 loading；只需把 `bindings` 绑定给组件。`rowKey` 必须稳定且唯一，默认会检测缺失和重复键。
 
 ```vue
@@ -216,6 +252,69 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 </template>
 ```
 
+将 Headless CRUD 绑定到 `:crud` 时，表格会识别操作结果中的 `{ error }`：失败不会触发删除成功事件，也不会重复展示 CRUD 控制器已经展示的反馈。自定义 `actions.delete` 可返回 Promise，或返回 `{ data, error }` 结构。
+
+树形数据可直接使用 `<C_Table :data="rows" :columns="columns" :config="{ tree: { defaultExpandAll: true }, pagination: false }" />`；`children` 是默认子节点字段，也可通过 `tree.childrenKey` 指定。默认展开会初始化所有父节点，并在异步追加新父节点时展开新节点，不会重新展开用户手动收起的旧节点。
+
+`C_Tabs` 是面向页面场景切换的统一数据驱动标签页，名称与全局 `C_*` 体系保持一致。默认使用紧凑
+`small` 尺寸、延迟呈现面板并支持受控/非受控状态；只做筛选或视图切换时启用 `tabsOnly`，组件
+不会执行面板内容，避免隐藏内容产生渲染开销或副作用。常规场景只维护数组，复杂内容可以按需使用 `render`、`pane` 或
+`pane-{key}` 插槽：
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue'
+  import { C_Tabs, defineTabs } from '@robot-admin/naive-ui-components/C_Tabs'
+
+  const activeView = ref('basic')
+  const views = defineTabs([
+    { key: 'basic', label: '基础表格', icon: 'mdi:table' },
+    { key: 'tree', label: '树形表格', icon: 'mdi:file-tree-outline' },
+  ])
+</script>
+
+<template>
+  <C_Tabs
+    v-model="activeView"
+    :items="views"
+    type="segment"
+    tabs-only
+  />
+</template>
+```
+
+| API                           | 说明                                                                      |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| `items`                       | `key/label` 为必填，支持 `icon`、`badge`、禁用、关闭及 `renderTab/render` |
+| `modelValue` / `defaultValue` | 同时支持受控和非受控状态                                                  |
+| `type` / `size` / `placement` | `line/card/bar/segment` 与常用尺寸、方向；默认 `line/small/top`           |
+| `tabsOnly`                    | 只呈现标签导航，适合表格场景和查询条件切换                                |
+| `beforeChange`                | 支持同步或异步切换守卫；返回 `false` 或抛错均保留当前页                   |
+| 插槽                          | `tab`、`pane` 和 `pane-{key}`，均提供当前 item 与 active 状态             |
+| 事件                          | `change`、`close`、`add` 及标准 `update:modelValue`                       |
+
+页面级和表格级按钮统一使用 `C_ActionBar`，无需再维护另一套 Toolbar。操作栏默认采用带图标的 `tiny` 紧凑按钮和 `6px` 间距；`add`、`refresh`、`export`、`columns`、`settings` 等语义 key 会自动补齐一致的文案、图标与按钮类型，自定义动作未传图标时使用中性操作图标。`show`、`disabled`、`loading` 可直接传布尔值、`Ref` 或 getter，异步操作默认防重复点击并自动展示 loading。`C_Table` 可在 `toolbar.actions` / `toolbar.rightActions` 中直接复用同一份动作配置，同时保留原有左右插槽；需要更大按钮时，通过 `actionBar.size` 或单个动作的 `size` 覆盖：
+
+```ts
+import { defineActions } from '@robot-admin/naive-ui-components/C_ActionBar'
+import { defineTableConfig } from '@robot-admin/naive-ui-components/C_Table'
+
+const actions = defineActions([
+  { key: 'add', onClick: openCreate },
+  { key: 'refresh', disabled: () => loading.value, onClick: refresh },
+  { key: 'settings', group: 'right', onClick: openSettings },
+])
+
+const config = defineTableConfig({
+  toolbar: {
+    actions,
+    actionBar: { size: 'small' }, // 可选；默认是 tiny
+  },
+})
+```
+
+`C_Table` 继续由当前 Naive UI 表格实现负责；需要 MachTable 时应由业务入口完整渲染 MachTable 及其原生配置，避免在两套列定义、事件和实例 API 之间做隐式转换。二者只共享 `C_ActionBar` 这类框架无关的页面动作模型，不互相污染。
+
 ### C_Map 推荐用法
 
 `C_Map` 统一以 `[纬度, 经度]` 接收中心点和标记坐标；切换高德地图时会在组件内部转换为其要求的 `[经度, 纬度]`，使用侧无需维护两套数据。非法标记会被隔离，组件只清理自己创建的 Marker，不会误删通过 `ready` 事件添加的业务图层。
@@ -254,8 +353,30 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 
 ### C_Captcha 服务端校验
 
+验证码入口使用组件库内置 SVG 状态图标，不依赖操作系统 Emoji 或在线图标服务；默认、校验中、成功和失败状态均保持一致的尺寸与语义颜色。`C_Login` 会把验证入口放在提交按钮之前并显示明确操作文案，同时透传 `captcha-visible-change`，宿主可在拼图交互期间暂停高开销背景动画。品牌接入可在外层通过 `--cc-height`、`--cc-radius`、`--cc-color`、`--cc-icon-color`、`--cc-bg`、`--cc-bg-hover`、`--cc-border`、`--cc-border-hover` 和 `--cc-focus` 调整外观，无需穿透组件内部 DOM。
+
 默认本地模式仅证明浏览器内的拼图交互已经完成，不能作为登录、支付等敏感操作的安全凭证。生产场景应传入 `verifier`，并开启 `require-server-verification`；组件会处理超时、取消和竞态，只在独立的服务端/验证码提供商确认后发出 `success`。请求中的 `token`、`timestamp` 都由客户端生成，只能用于关联和日志，服务端绝不能把它们本身当作可信证明。
 
+需要国内网络可用且长期免费的方案时，可显式选择开源 MIT 的 ALTCHA 自托管模式。该模式仅在使用时懒加载，不增加默认拼图入口的首屏执行成本；组件会强制服务端校验，缺少 `challenge-url` 或 `verifier` 时失败关闭。应用后端必须签发新鲜的一次性挑战、验证 PoW payload、阻止重放并限流；密钥只存于服务端。
+
+```vue
+<C_Captcha
+  provider="altcha"
+  challenge-url="/api/auth/captcha/challenge"
+  :verifier="
+    async ({ token, signal }) => {
+      const response = await fetch('/api/auth/captcha/verify', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ payload: token }),
+        signal,
+      })
+      return response.json() // { valid: boolean, token: '服务端一次性登录令牌' }
+    }
+  "
+/>
+```
+
 ```vue
 <C_Captcha
   require-server-verification
@@ -277,36 +398,39 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 />
 ```
 
-开启 `require-server-verification` 后，成功响应必须包含服务端 token。该 token 应短期、一次性使用，并绑定当前会话或业务请求。`C_Login` 可通过 `captchaVerifier`、`requireCaptchaServerVerification` 和 `captchaVerificationTimeout` 透传同一安全策略，并在 `submit` 数据中通过 `captchaVerifiedBy` 标识验证来源。更多边界说明见 [SECURITY.md](./SECURITY.md)。
+开启 `require-server-verification` 后，成功响应必须包含服务端 token。该 token 应短期、一次性使用，并绑定当前会话或业务请求。`C_Login` 可通过 `captchaProvider`、`captchaChallengeUrl`、`captchaVerifier`、`requireCaptchaServerVerification` 和 `captchaVerificationTimeout` 透传同一安全策略，并在 `submit` 数据中通过 `captchaType` 与 `captchaVerifiedBy` 标识验证类型和来源。更多边界说明见 [SECURITY.md](./SECURITY.md)。
 
-### 📋 组件清单（51 个）
+`C_Login` 的“记住我”只保存用户名，不保存密码。短信验证码仅对格式正确的手机号触发事件；组件会立即开始本地倒计时，发送结果和服务端限流仍由宿主处理。`C_City` 在首次打开时才加载城市索引，字母跳转只作用于当前实例；默认触发器、字母和城市项均可用键盘操作。
+
+### 📋 组件清单（53 个）
 
 > 💡 所有组件均提供 **在线交互演示**，访问 [组件文档](https://www.tzagileteam.com/robot/components/preface) 可直接在页面中体验真实效果（通过 iframe 嵌入 Robot Admin 生产环境）。
 
 #### 基础组件
 
-| 组件             | 说明             | 外部依赖                    |
-| ---------------- | ---------------- | --------------------------- |
-| `C_Icon`         | Iconify 图标封装 | `@iconify/vue`              |
-| `C_Code`         | 代码高亮显示     | `highlight.js`              |
-| `C_Barcode`      | 条形码生成器     | `@chenfengyuan/vue-barcode` |
-| `C_Captcha`      | 拼图验证码       | `vue3-puzzle-vcode`         |
-| `C_Cascade`      | 级联面板选择器   | -                           |
-| `C_Guide`        | 新手引导         | `driver.js`                 |
-| `C_Progress`     | 增强进度条       | -                           |
-| `C_Steps`        | 步骤条           | -                           |
-| `C_ActionBar`    | 操作按钮栏       | -                           |
-| `C_Theme`        | 主题切换器       | -                           |
-| `C_Language`     | 语言切换器       | -                           |
-| `C_Date`         | 日期选择器增强   | -                           |
-| `C_City`         | 省市区三级联动   | -                           |
-| `C_Breadcrumb`   | 面包屑导航       | -                           |
-| `C_Menu`         | 导航菜单         | -                           |
-| `C_TagsView`     | 标签页导航       | -                           |
-| `C_GlobalSearch` | 全局搜索面板     | -                           |
-| `C_AvatarGroup`  | 头像组合展示     | -                           |
-| `C_OrgChart`     | 组织架构图       | -                           |
-| `C_Skeleton`     | 骨架屏占位组件   | -                           |
+| 组件             | 说明                    | 外部依赖                      |
+| ---------------- | ----------------------- | ----------------------------- |
+| `C_Icon`         | Iconify 图标封装        | `@iconify/vue`                |
+| `C_Code`         | 代码高亮显示            | `highlight.js`                |
+| `C_Barcode`      | 条形码生成器            | `@chenfengyuan/vue-barcode`   |
+| `C_Captcha`      | 拼图/ALTCHA 人机验证    | `vue3-puzzle-vcode`、`altcha` |
+| `C_Cascade`      | 级联面板选择器          | -                             |
+| `C_Guide`        | 新手引导                | `driver.js`                   |
+| `C_Progress`     | 增强进度条              | -                             |
+| `C_Steps`        | 步骤条                  | -                             |
+| `C_ActionBar`    | 操作按钮栏              | -                             |
+| `C_Theme`        | 主题切换器              | -                             |
+| `C_Language`     | 语言切换器              | -                             |
+| `C_Date`         | 日期选择器增强          | -                             |
+| `C_City`         | 省市区三级联动          | -                             |
+| `C_Breadcrumb`   | 面包屑导航              | -                             |
+| `C_Menu`         | 导航菜单                | -                             |
+| `C_Tabs`         | 数据驱动标签页/场景切换 | -                             |
+| `C_TagsView`     | 标签页导航              | -                             |
+| `C_GlobalSearch` | 全局搜索面板            | -                             |
+| `C_AvatarGroup`  | 头像组合展示            | -                             |
+| `C_OrgChart`     | 组织架构图              | -                             |
+| `C_Skeleton`     | 骨架屏占位组件          | -                             |
 
 #### 内容 & 编辑组件
 
@@ -334,11 +458,14 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 | `C_FilePreview`  | 文件预览（PDF/Word/Excel）                | `xlsx`、`mammoth`          |
 | `C_Timeline`     | 时间线（垂直/水平/可折叠）                | -                          |
 
+图片/日历类组件的使用边界：`C_ImageCropper` 翻转会更新实际图片源并重置当前裁剪位置，加载和导出失败通过 `error: Error` 报告；`C_Signature` 的 `readonly` 只禁止用户交互，暴露方法仍可用于加载历史数据，其 SVG 导出是保留画布效果的栅格嵌入 SVG；`C_QRCode` 带 Logo 的 SVG 同样采用栅格嵌入，以保持预览与导出一致。`C_FullCalendar` 使用本地日历日期创建当日事件；`C_WaterFall` 会根据图片实际宽高比自动重排，建议以稳定唯一的 `id` 标识每项。
+
 #### 表单 & 布局组件
 
 | 组件              | 说明                                              | 外部依赖             |
 | ----------------- | ------------------------------------------------- | -------------------- |
 | `C_Form`          | 动态表单引擎（Grid/Tabs/Steps/Card/Dynamic 布局） | -                    |
+| `C_FormModal`     | 数据驱动的新增/编辑表单弹窗                       | -                    |
 | `C_FormSearch`    | 搜索表单                                          | -                    |
 | `C_CollapsePanel` | 折叠面板                                          | -                    |
 | `C_SplitPane`     | 分割面板                                          | -                    |
@@ -354,7 +481,7 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 | --------------- | -------------------------------------- | -------- |
 | `C_Chat`        | 聊天组件（联系人/消息气泡/输入框）     | -        |
 | `C_ContextMenu` | 右键菜单（嵌套子菜单/快捷键/危险操作） | -        |
-| `C_Login`       | 登录组件（5种模式/验证码/记住密码）    | -        |
+| `C_Login`       | 登录组件（5种模式/验证码/记住用户名）  | -        |
 
 #### 流程 & 通知组件
 
@@ -366,6 +493,22 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 
 ### 🔌 依赖说明
 
+`C_FilePreview` 的 URL 入口仅接受 HTTPS 或当前站点同源 HTTP（便于本地开发）；不接受脚本、数据 URL、带凭据 URL 或跨站明文 HTTP。`autoPreview` 会在有文件源时自动打开预览，已打开时切换文件源会刷新内容。重复预览会释放旧 PDF 对象 URL，并忽略过期加载结果。Excel 单元格的 `0` 与 `false` 会原样保留。
+
+`C_AntV` 的 BPMN 对外数据保持 `{ nodes, flows }` 领域结构；组件内部转换为 X6 单元格，并在 `data-change` / `getData()` 中还原节点位置、类型、属性和连线条件。BPMN/UML 仅在未提供 `data` 时加载内置示例；显式传入空数据会显示空画布。
+
+`C_VtableGantt` 合并预设与 `options` 时会保留未覆盖的嵌套配置、以新数组整体替换旧数组，并忽略原型相关键；全屏按钮状态仅反映该甘特图容器的实际全屏状态。
+
+`C_AudioPlayer` 只在浏览器确认 `play()` 成功后进入播放状态并触发 `play`；自动播放被拒绝时会触发 `error`，空播放列表不会产生虚假的播放事件。静音、曲目和进度条均可用键盘操作。
+
+`C_CollapsePanel` 与 `C_TagsView` 会校验本地持久化数据结构；损坏或旧格式数据会安全回退，不会阻断组件初始化。持久化标签仅恢复站内路径，特殊字符路径的定位不会拼接 CSS 选择器。
+
+`C_Table` 列设置只恢复有效的列键、可见性、列宽和固定方向；损坏的 `persistKey` 存储会回退到传入列。列设置在本地副本上操作，不会修改调用方的列对象。`C_Upload` 的默认文件列表同样会复制后再管理，文件选择、拖拽和粘贴共用 `accept` 过滤，图片操作可通过键盘识别和访问；并发计算哈希时，各文件显示自己的进度。分片上传在查询断点、请求或合并阶段取消后，不会继续派发请求或发出过期的完成事件。自定义上传请求的 `abort()` 即使不回调，也会释放分片等待任务。
+
+`C_WorkFlow` 会在首次渲染时加载传入的 `modelValue`，并在 `getCurrentWorkflowData()` / `save` / `change` / `node-click` 中输出隔离的数据快照，避免调用方意外修改内部节点。条件编辑弹窗在保存前不会修改画布数据，未填完整的条件不会被静默丢弃。`readonly` 禁止节点拖拽、连线、配置、增删与保存，但仍允许预览、验证和适应视图；节点与条件 ID 在同一时刻连续创建时保持唯一。
+
+类型验证同时覆盖 TypeScript 源码、Vue 单文件组件模板和发布后的使用侧示例。`C_Table` 合计行的 `summary.render` 应返回按列键组织的对象（`{ columnKey: { value, colSpan? } }`）；`C_FormSearch` 的日期范围兼容原有数字时间戳数组，也支持格式化字符串数组，两种值会分别绑定 Naive UI 对应的值接口。
+
 组件运行依赖已由本包声明，安装组件库时会自动解析。所有场景都需要：
 
 ```bash
@@ -380,7 +523,7 @@ bun add vue naive-ui
 
 ```
 bun run build
-  ├── 1. tsdown          → 多入口打包（51 组件 ESM/CJS/DTS）
+  ├── 1. tsdown          → 多入口打包（53 组件 ESM/CJS/DTS）
   ├── 2. sass CLI        → 编译共享变量入口 → global-scss.css
   ├── 3. merge-css.js    → 合并 Vue 编译后的 SFC CSS + 全局变量 → style.css
   ├── 4. gen-exports.js  → 自动生成 package.json exports 映射
@@ -390,7 +533,7 @@ bun run build
 
 #### 技术要点
 
-- **构建引擎**：[tsdown](https://github.com/rolldown/tsdown)（基于 Rolldown），51 个独立入口并行编译
+- **构建引擎**：[tsdown](https://github.com/rolldown/tsdown)（基于 Rolldown），53 个独立入口并行编译
 - **SCSS 处理**：自定义 `scssTransformPlugin` 在 Rolldown 管线内编译 SFC SCSS，独立 Sass CLI 仅编译共享变量入口
 - **CSS 合并**：构建后将 Vue 已完成 scoped 转换的 per-chunk CSS 与共享变量合并为单一 `style.css`，避免重复样式和原始 `:deep()` 选择器泄漏
 - **类型导出**：统一 `export *` barrel 模式，自动生成完整 `.d.ts`
@@ -405,7 +548,7 @@ bun run build
 ```
 dist/
 ├── index.js / index.cjs / index.d.ts     # 主入口
-├── C_Form.js / C_Form.cjs / C_Form.d.ts  # 子路径入口（51 组件）
+├── C_Form.js / C_Form.cjs / C_Form.d.ts  # 子路径入口（53 组件）
 ├── C_Form.base.css / C_Form.full.css      # 基础/完整样式层级
 ├── C_Table.base.css / C_Table.full.css    # 基础/完整样式层级
 ├── style.css                              # 合并后的全量样式

package/README_EN.md

@@ -4,7 +4,7 @@
 
 **Enterprise-grade Vue 3 component library built on Naive UI**
 
-51 production-ready business components extracted from Robot Admin, supporting global registration, on-demand imports (Tree-Shaking), and subpath imports.
+53 production-ready business components extracted from Robot Admin, supporting global registration, on-demand imports (Tree-Shaking), and subpath imports.
 
 [![NPM Version](https://img.shields.io/npm/v/@robot-admin/naive-ui-components)](https://www.npmjs.com/package/@robot-admin/naive-ui-components)
 [![License](https://img.shields.io/npm/l/@robot-admin/naive-ui-components)](./LICENSE)
@@ -135,6 +135,42 @@ const { model, formRef, bindings } = useCForm({
 })
 ```
 
+Custom action bars should call the `action` slot's `submit()` rather than treating `validate()` as submission. The step-layout `step-actions` slot also provides `isLastStep`, `submit()`, and `submitting`. Put asynchronous persistence in `config.onSubmit`; the `@submit` event is a post-success notification and does not await an event listener's promise.
+
+For create/edit flows, `C_FormModal` consumes a structural headless `editor` directly. Fields, validation, and layout remain data-driven by `C_Form`, while pages no longer own duplicate modal, draft, or loading state:
+
+```vue
+<script setup lang="ts">
+  import { C_FormModal } from '@robot-admin/naive-ui-components/C_FormModal'
+  import type { FormModalEditor } from '@robot-admin/naive-ui-components/C_FormModal'
+  import {
+    defineFormConfig,
+    defineFormOptions,
+  } from '@robot-admin/naive-ui-components/C_Form'
+
+  interface UserForm {
+    name: string
+  }
+
+  defineProps<{ editor: FormModalEditor<UserForm> }>()
+
+  const fields = defineFormOptions<UserForm>([
+    { type: 'input', prop: 'name', label: 'Name', required: true },
+  ])
+  const formConfig = defineFormConfig<UserForm>({ labelPlacement: 'top' })
+</script>
+
+<template>
+  <C_FormModal
+    :editor="editor"
+    :options="fields"
+    :config="formConfig"
+  />
+</template>
+```
+
+The editor contract is structural: the component package does not depend on a request library. Any controller exposing `visible/mode/model/title/loading/setModel/close/submit` can drive it. The default uses a responsive 620px width, `small` form controls, and a right-aligned icon-based `C_ActionBar` for a compact admin workflow. Close button, mask close, and Escape remain enabled by default and can be disabled for high-risk forms.
+
 For remote tables, `useTableQuery` owns cancellation, latest-request-wins behavior, pagination, and loading. Destructure its `bindings` and use `<C_Table v-bind="bindings" />`:
 
 ```ts
@@ -157,6 +193,69 @@ const { bindings } = useTableQuery<UserRow, { keyword: string }>({
 })
 ```
 
+When binding a headless CRUD controller through `:crud`, the table recognizes `{ error }` action results: failed deletes do not emit a successful-deletion event, and feedback already shown by the controller is not duplicated. Custom `actions.delete` callbacks may return a promise or a `{ data, error }` result.
+
+Tree data can use `<C_Table :data="rows" :columns="columns" :config="{ tree: { defaultExpandAll: true }, pagination: false }" />` directly. `children` is the default child key and can be changed with `tree.childrenKey`. Default expansion includes parent rows added later without reopening rows the user collapsed.
+
+`C_Tabs` is the data-driven page-scenario switcher for the global `C_*` system. It defaults to the compact
+`small` size, lazy pane display, and supports controlled or uncontrolled state. Set `tabsOnly` for filters or
+view switching; pane content is not executed, avoiding hidden render work and side effects. Most pages only maintain an item array; complex
+content can opt into `render`, `pane`, or `pane-{key}` slots:
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue'
+  import { C_Tabs, defineTabs } from '@robot-admin/naive-ui-components/C_Tabs'
+
+  const activeView = ref('basic')
+  const views = defineTabs([
+    { key: 'basic', label: 'Basic table', icon: 'mdi:table' },
+    { key: 'tree', label: 'Tree table', icon: 'mdi:file-tree-outline' },
+  ])
+</script>
+
+<template>
+  <C_Tabs
+    v-model="activeView"
+    :items="views"
+    type="segment"
+    tabs-only
+  />
+</template>
+```
+
+| API                           | Description                                                                                   |
+| ----------------------------- | --------------------------------------------------------------------------------------------- |
+| `items`                       | Requires `key/label`; supports icons, badges, disabled/closable state, and `renderTab/render` |
+| `modelValue` / `defaultValue` | Controlled and uncontrolled state                                                             |
+| `type` / `size` / `placement` | `line/card/bar/segment`, common sizes and placements; defaults to `line/small/top`            |
+| `tabsOnly`                    | Renders navigation only for table scenarios and query switches                                |
+| `beforeChange`                | Sync/async guard; `false` or an error keeps the current tab                                   |
+| Slots                         | `tab`, `pane`, and `pane-{key}`, each with item and active state                              |
+| Events                        | `change`, `close`, `add`, and standard `update:modelValue`                                    |
+
+Use `C_ActionBar` as the single page/table action model instead of maintaining another toolbar abstraction. It defaults to compact `tiny` buttons with icons and a `6px` gap. Semantic keys such as `add`, `refresh`, `export`, `columns`, and `settings` supply consistent labels, icons, and button types; custom actions receive a neutral icon when none is provided. `show`, `disabled`, and `loading` accept booleans, refs, or getters; async handlers are guarded against duplicate clicks and receive automatic loading feedback. `C_Table` consumes the same actions through `toolbar.actions` / `toolbar.rightActions` while preserving its existing toolbar slots. Override `actionBar.size` or an individual action's `size` when a larger control is required:
+
+```ts
+import { defineActions } from '@robot-admin/naive-ui-components/C_ActionBar'
+import { defineTableConfig } from '@robot-admin/naive-ui-components/C_Table'
+
+const actions = defineActions([
+  { key: 'add', onClick: openCreate },
+  { key: 'refresh', disabled: () => loading.value, onClick: refresh },
+  { key: 'settings', group: 'right', onClick: openSettings },
+])
+
+const config = defineTableConfig({
+  toolbar: {
+    actions,
+    actionBar: { size: 'small' }, // optional; tiny by default
+  },
+})
+```
+
+`C_Table` remains owned by its current Naive UI table implementation. A MachTable mode should render MachTable with its native columns, events, and instance API as a complete engine boundary rather than translating between the two engines. They only share engine-neutral page actions such as `C_ActionBar`.
+
 ### Recommended C_Map setup
 
 `C_Map` consistently accepts `[latitude, longitude]` for centers and markers. It converts coordinates to AMap's `[longitude, latitude]` order internally, filters invalid markers, and only removes markers owned by the component.
@@ -195,8 +294,30 @@ The exposed instance provides `getMap()`, `refresh()`, and `fitToMarkers()` for
 
 ### C_Captcha Server Verification
 
+The captcha trigger uses package-owned SVG status icons and does not depend on platform emoji or an online icon service. Idle, verifying, success, and error states keep consistent sizing and semantic colors. `C_Login` places the verification action before submit, keeps the action label explicit, and forwards `captcha-visible-change` so hosts can pause expensive background animation during puzzle interaction. Brand styling can be adjusted from the host with `--cc-height`, `--cc-radius`, `--cc-color`, `--cc-icon-color`, `--cc-bg`, `--cc-bg-hover`, `--cc-border`, `--cc-border-hover`, and `--cc-focus`, without reaching into internal DOM.
+
 The default local mode only proves that the browser-side puzzle interaction completed. It is not a security credential for login, payment, or other sensitive actions. In production, provide a `verifier` and enable `require-server-verification`. Timeout, cancellation, and stale attempts are handled by the component, and `success` is emitted only after approval by an independent server/provider challenge. Request `token` and `timestamp` values are client-generated telemetry and must never be trusted as proof by the server.
 
+For a permanently free, network-independent option, explicitly select the open-source MIT ALTCHA self-hosted provider. It is lazy-loaded only when selected, so the default puzzle path keeps its startup cost. ALTCHA mode always fails closed through server verification: the application server must issue fresh single-use challenges, verify the PoW payload, prevent replay, and rate-limit attempts while retaining all secrets server-side.
+
+```vue
+<C_Captcha
+  provider="altcha"
+  challenge-url="/api/auth/captcha/challenge"
+  :verifier="
+    async ({ token, signal }) => {
+      const response = await fetch('/api/auth/captcha/verify', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ payload: token }),
+        signal,
+      })
+      return response.json() // { valid: boolean, token: 'single-use-server-token' }
+    }
+  "
+/>
+```
+
 ```vue
 <C_Captcha
   require-server-verification
@@ -218,36 +339,39 @@ The default local mode only proves that the browser-side puzzle interaction comp
 />
 ```
 
-With `require-server-verification`, a successful response must include a server token. Server tokens should be short-lived, single-use, and bound to the current session or operation. `C_Login` forwards the same policy through `captchaVerifier`, `requireCaptchaServerVerification`, and `captchaVerificationTimeout`, and its `submit` payload identifies the result through `captchaVerifiedBy`. See [SECURITY.md](./SECURITY.md) for trust-boundary details.
+With `require-server-verification`, a successful response must include a server token. Server tokens should be short-lived, single-use, and bound to the current session or operation. `C_Login` forwards the same policy through `captchaProvider`, `captchaChallengeUrl`, `captchaVerifier`, `requireCaptchaServerVerification`, and `captchaVerificationTimeout`; its `submit` payload identifies the result through `captchaType` and `captchaVerifiedBy`. See [SECURITY.md](./SECURITY.md) for trust-boundary details.
 
-### 📋 Component List (51 Components)
+`C_Login` remembers only the username, never the password. SMS events require a valid phone number; the local countdown starts immediately, while delivery results and server-side rate limits remain the host's responsibility. `C_City` loads its city index on first open and scopes letter navigation to its own instance; the default trigger, letters, and city items are keyboard-operable.
+
+### 📋 Component List (53 Components)
 
 > 💡 All components provide **interactive live demos**. Visit the [Component Docs](https://www.tzagileteam.com/robot/components/preface) to try them out in real-time (rendered via iframe from Robot Admin production).
 
 #### Basic Components
 
-| Component        | Description              | External Deps               |
-| ---------------- | ------------------------ | --------------------------- |
-| `C_Icon`         | Iconify icon wrapper     | `@iconify/vue`              |
-| `C_Code`         | Code highlighting        | `highlight.js`              |
-| `C_Barcode`      | Barcode generator        | `@chenfengyuan/vue-barcode` |
-| `C_Captcha`      | Puzzle captcha           | `vue3-puzzle-vcode`         |
-| `C_Cascade`      | Cascade panel selector   | -                           |
-| `C_Guide`        | User guide / tour        | `driver.js`                 |
-| `C_Progress`     | Enhanced progress bar    | -                           |
-| `C_Steps`        | Step bar                 | -                           |
-| `C_ActionBar`    | Action button bar        | -                           |
-| `C_Theme`        | Theme switcher           | -                           |
-| `C_Language`     | Language switcher        | -                           |
-| `C_Date`         | Enhanced date picker     | -                           |
-| `C_City`         | Province / city selector | -                           |
-| `C_Breadcrumb`   | Breadcrumb navigation    | -                           |
-| `C_Menu`         | Navigation menu          | -                           |
-| `C_TagsView`     | Tab-based navigation     | -                           |
-| `C_GlobalSearch` | Global search panel      | -                           |
-| `C_AvatarGroup`  | Avatar group display     | -                           |
-| `C_OrgChart`     | Organization chart       | -                           |
-| `C_Skeleton`     | Skeleton placeholder     | -                           |
+| Component        | Description               | External Deps                 |
+| ---------------- | ------------------------- | ----------------------------- |
+| `C_Icon`         | Iconify icon wrapper      | `@iconify/vue`                |
+| `C_Code`         | Code highlighting         | `highlight.js`                |
+| `C_Barcode`      | Barcode generator         | `@chenfengyuan/vue-barcode`   |
+| `C_Captcha`      | Puzzle / ALTCHA captcha   | `vue3-puzzle-vcode`, `altcha` |
+| `C_Cascade`      | Cascade panel selector    | -                             |
+| `C_Guide`        | User guide / tour         | `driver.js`                   |
+| `C_Progress`     | Enhanced progress bar     | -                             |
+| `C_Steps`        | Step bar                  | -                             |
+| `C_ActionBar`    | Action button bar         | -                             |
+| `C_Theme`        | Theme switcher            | -                             |
+| `C_Language`     | Language switcher         | -                             |
+| `C_Date`         | Enhanced date picker      | -                             |
+| `C_City`         | Province / city selector  | -                             |
+| `C_Breadcrumb`   | Breadcrumb navigation     | -                             |
+| `C_Menu`         | Navigation menu           | -                             |
+| `C_Tabs`         | Data-driven scenario tabs | -                             |
+| `C_TagsView`     | Tab-based navigation      | -                             |
+| `C_GlobalSearch` | Global search panel       | -                             |
+| `C_AvatarGroup`  | Avatar group display      | -                             |
+| `C_OrgChart`     | Organization chart        | -                             |
+| `C_Skeleton`     | Skeleton placeholder      | -                             |
 
 #### Content & Editor Components
 
@@ -275,11 +399,14 @@ With `require-server-verification`, a successful response must include a server
 | `C_FilePreview`  | File preview (PDF/Word/Excel)                | `xlsx`, `mammoth`          |
 | `C_Timeline`     | Timeline (vertical/horizontal/collapsible)   | -                          |
 
+Image/calendar behavior notes: `C_ImageCropper` flips the actual source and resets the current crop position; load/export failures emit `error: Error`. `C_Signature` readonly mode blocks user interaction but keeps exposed methods available for loading saved data. Its SVG export embeds the rendered raster canvas. `C_QRCode` uses the same raster-in-SVG approach when a logo is present so preview and export match. `C_FullCalendar` creates same-day events in local calendar time. `C_WaterFall` relayouts from actual image aspect ratios; give each item a stable unique `id`.
+
 #### Form & Layout Components
 
 | Component         | Description                                       | External Deps        |
 | ----------------- | ------------------------------------------------- | -------------------- |
 | `C_Form`          | Dynamic form engine (Grid/Tabs/Steps/Card layout) | -                    |
+| `C_FormModal`     | Data-driven create/edit form modal                | -                    |
 | `C_FormSearch`    | Search form                                       | -                    |
 | `C_CollapsePanel` | Collapse panel                                    | -                    |
 | `C_SplitPane`     | Split pane                                        | -                    |
@@ -307,6 +434,22 @@ With `require-server-verification`, a successful response must include a server
 
 ### 🔌 Dependency Notes
 
+`C_FilePreview` accepts HTTPS URLs and same-origin HTTP URLs for local development. Script/data URLs, credential-bearing URLs, and cross-origin plain HTTP are rejected. `autoPreview` opens a supplied file automatically, and changing the source refreshes an open preview. Repeated previews release the previous PDF object URL and ignore stale loading results. Excel values `0` and `false` remain intact.
+
+`C_AntV` keeps the public BPMN model as `{ nodes, flows }`. It converts that model to X6 cells internally and restores node positions, types, properties, and flow conditions in `data-change` and `getData()`. BPMN and UML load built-in samples only when `data` is absent; an explicit empty model produces an empty canvas.
+
+`C_VtableGantt` merges presets and `options` without dropping untouched nested settings, replaces arrays as a whole, and ignores prototype-related keys. Its fullscreen button reflects the actual fullscreen state of that Gantt container.
+
+`C_AudioPlayer` enters the playing state and emits `play` only after the browser accepts `play()`. A rejected autoplay emits `error`, and an empty playlist cannot emit a false play event. Mute, playlist tracks, and seeking are keyboard operable.
+
+`C_CollapsePanel` and `C_TagsView` validate persisted data before restoring it, so corrupt or outdated JSON cannot break initialization. Persisted tags restore only in-app paths, and special characters in a path are no longer interpolated into CSS selectors.
+
+`C_Table` column settings restore only valid keys, visibility, widths, and fixed directions; corrupt `persistKey` storage falls back to the supplied columns. Settings operate on local column copies rather than mutating caller-owned objects. `C_Upload` copies its initial file list before managing it, applies the same `accept` filter to picker, drop, and paste input, labels image actions for keyboard users, and shows per-file progress during concurrent hashing. Cancelling a chunked upload during resume lookup, an active request, or merging cannot start later requests or emit stale completion; a custom request's `abort()` releases the pending chunk even if it never calls back.
+
+`C_WorkFlow` loads the supplied `modelValue` on first render and returns isolated snapshots from `getCurrentWorkflowData()`, `save`, `change`, and `node-click`, so callers cannot accidentally mutate its internal nodes. Editing conditions cannot change canvas data before Save, and incomplete conditions are not silently dropped. `readonly` blocks dragging, connecting, configuring, adding/removing, and saving while leaving preview, validation, and fit-to-view available. Node and condition IDs remain unique when created in the same tick.
+
+Type verification covers TypeScript source, Vue SFC templates, and consumer examples built against the package. `C_Table` summary rendering expects an object keyed by column (`{ columnKey: { value, colSpan? } }`). `C_FormSearch` preserves existing numeric timestamp ranges and also supports formatted string ranges, binding each to the matching Naive UI value API.
+
 Runtime component dependencies are declared by this package and resolved automatically. Every consumer needs:
 
 ```bash
@@ -321,7 +464,7 @@ Install optional peers per feature: `vue-router` for `C_Breadcrumb`/`C_TagsView`
 
 ```
 bun run build
-  ├── 1. tsdown          → Multi-entry bundling (51 components ESM/CJS/DTS)
+  ├── 1. tsdown          → Multi-entry bundling (53 components ESM/CJS/DTS)
   ├── 2. sass CLI        → Compile the shared-variable entry → global-scss.css
   ├── 3. merge-css.js    → Merge Vue-compiled SFC CSS + global variables → style.css
   ├── 4. gen-exports.js  → Auto-generate package.json exports map
@@ -331,7 +474,7 @@ bun run build
 
 #### Key Technical Details
 
-- **Build engine**: [tsdown](https://github.com/rolldown/tsdown) (Rolldown-based), 51 independent entries compiled in parallel
+- **Build engine**: [tsdown](https://github.com/rolldown/tsdown) (Rolldown-based), 53 independent entries compiled in parallel
 - **SCSS processing**: Custom `scssTransformPlugin` compiles SFC SCSS within the Rolldown pipeline; standalone Sass CLI only compiles the shared-variable entry
 - **CSS merging**: Post-build merges Vue scoped-compiled per-chunk CSS with shared variables into a single `style.css`, avoiding duplicate styles and leaked raw `:deep()` selectors
 - **Type exports**: Unified `export *` barrel pattern with auto-generated `.d.ts`
@@ -346,7 +489,7 @@ bun run build
 ```
 dist/
 ├── index.js / index.cjs / index.d.ts     # Main entry
-├── C_Form.js / C_Form.cjs / C_Form.d.ts  # Subpath entries (51 components)
+├── C_Form.js / C_Form.cjs / C_Form.d.ts  # Subpath entries (53 components)
 ├── C_Form.base.css / C_Form.full.css      # Base/full style tiers
 ├── C_Table.base.css / C_Table.full.css    # Base/full style tiers
 ├── style.css                              # Merged full styles

package/SECURITY.md

@@ -11,6 +11,7 @@ Please use GitHub's private security-advisory flow for the repository. Include t
 ## Trust boundaries
 
 - `C_Captcha` local mode is a UI interaction check, not authentication. Its client token and timestamp are untrusted telemetry. Sensitive flows must configure `verifier` with `requireServerVerification`, validate an independent server/provider-issued challenge, and return a short-lived, single-use token bound to the session or operation. Fail-closed mode rejects successful responses that omit this token.
+- `C_Captcha` ALTCHA mode is self-hosted and forces server verification. The application server must sign fresh challenges, validate payloads with a server-only secret, enforce expiration and single use, bind the returned token to the session or operation, and apply rate limits. The browser must never receive the HMAC secret.
 - Rich HTML is sanitized by the library, but applications must still apply server-side validation, output encoding, CSP, and authorization. Client-side sanitization is not an authorization boundary.
 - Formula evaluation uses a bounded parser and does not execute arbitrary JavaScript. Do not replace it with `eval` or `Function` for untrusted input.
 - Upload type, size, hashing, and chunk checks improve UX and integrity but do not replace server-side content validation, malware scanning, quotas, or access control.

package/dist/C_ActionBar.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./C_Icon2.cjs`);const e=require(`./C_ActionBar2.cjs`);exports.C_ActionBar=e.t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./C_Icon2.cjs`);const e=require(`./C_ActionBar2.cjs`);exports.ACTION_BAR_DEFAULT_CONFIG=e.n,exports.ACTION_PRESETS=e.r,exports.C_ActionBar=e.t,exports.DEFAULT_ACTION_ICON=e.i,exports.defineActions=e.a,exports.resolveActionPreset=e.o;