@robot-admin/naive-ui-components 0.11.7 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @robot-admin/naive-ui-components
 
+## 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
+
+- 修复 `C_Map` 在 Vite 深层按需加载、未整体预构建组件库时的 Leaflet CommonJS/ESM 互操作错误；组件同时兼容命名空间和 `default` 导出，并在 API 形态异常时返回明确错误。同步关闭 `C_VtableGantt` 在组件快速卸载或配置连续变化时的异步初始化竞态，避免向已经失效的容器创建实例。
+
 ## 0.11.7
 
 ### 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,40 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 </template>
 ```
 
+新增/编辑场景推荐用 `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 +250,65 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 </template>
 ```
 
+`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` 事件添加的业务图层。
@@ -248,14 +341,36 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 </template>
 ```
 
-组件实例提供 `getMap()`、`refresh()` 和 `fitToMarkers()`，适合标签页显示、容器尺寸变化和业务图层扩展。使用 `map-type="amap"` 时必须提供 `amap-key`；2021-12-02 之后申请的 Key 还必须按[高德官方安全密钥说明](https://lbs.amap.com/api/javascript-api-v2/guide/abc/jscode)配置 `:amap-security-config="{ serviceHost: '/_AMapService' }"`（生产推荐，由服务端代理保管安全密钥），或仅在开发环境传 `{ securityJsCode: '...' }`。安全配置会在 SDK 脚本加载前写入，并拒绝同页混用不同 Key。宿主应用还需在 CSP 的 `script-src` 中允许 `https://webapi.amap.com`，同时在高德控制台配置域名白名单和配额限制。
+组件实例提供 `getMap()`、`refresh()` 和 `fitToMarkers()`，适合标签页显示、容器尺寸变化和业务图层扩展。OpenStreetMap 模式会在组件内部兼容 Leaflet 的 ESM 命名空间和 CommonJS `default` 形态，宿主无需为正确性配置整包预构建。使用 `map-type="amap"` 时必须提供 `amap-key`；2021-12-02 之后申请的 Key 还必须按[高德官方安全密钥说明](https://lbs.amap.com/api/javascript-api-v2/guide/abc/jscode)配置 `:amap-security-config="{ serviceHost: '/_AMapService' }"`（生产推荐，由服务端代理保管安全密钥），或仅在开发环境传 `{ securityJsCode: '...' }`。安全配置会在 SDK 脚本加载前写入，并拒绝同页混用不同 Key。宿主应用还需在 CSP 的 `script-src` 中允许 `https://webapi.amap.com`，同时在高德控制台配置域名白名单和配额限制。
 
 `C_Date`、`C_Time`、`C_Menu`、`C_FormSearch` 均支持标准 `v-model`。组件可直接放在没有 `NMessageProvider` / `NDialogProvider` 的页面；如需统一提示、确认和文案，可在安装时传入 `feedback`、`locale`、`form` 与 `table.defaults`。
 
 ### 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 +392,37 @@ 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 个）
+### 📋 组件清单（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`     | 骨架屏占位组件          | -                             |
 
 #### 内容 & 编辑组件
 
@@ -339,6 +455,7 @@ import '@robot-admin/naive-ui-components/C_Table/base.css'
 | 组件              | 说明                                              | 外部依赖             |
 | ----------------- | ------------------------------------------------- | -------------------- |
 | `C_Form`          | 动态表单引擎（Grid/Tabs/Steps/Card/Dynamic 布局） | -                    |
+| `C_FormModal`     | 数据驱动的新增/编辑表单弹窗                       | -                    |
 | `C_FormSearch`    | 搜索表单                                          | -                    |
 | `C_CollapsePanel` | 折叠面板                                          | -                    |
 | `C_SplitPane`     | 分割面板                                          | -                    |
@@ -380,7 +497,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 +507,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 +522,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,40 @@ const { model, formRef, bindings } = useCForm({
 })
 ```
 
+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 +191,65 @@ const { bindings } = useTableQuery<UserRow, { keyword: string }>({
 })
 ```
 
+`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.
@@ -189,14 +282,36 @@ const { bindings } = useTableQuery<UserRow, { keyword: string }>({
 </template>
 ```
 
-The exposed instance provides `getMap()`, `refresh()`, and `fitToMarkers()` for tab visibility changes, container resizes, and custom business layers. `map-type="amap"` requires `amap-key`; keys created after 2021-12-02 also require `:amap-security-config="{ serviceHost: '/_AMapService' }"` (recommended in production so the server proxy retains the security secret), or `{ securityJsCode: '...' }` for development only, as described by the [official AMap security guidance](https://lbs.amap.com/api/javascript-api-v2/guide/abc/jscode). The config is installed before the SDK script and conflicting keys on one page are rejected. The host CSP must also allow `https://webapi.amap.com` in `script-src`, with domain allowlists and quotas enforced in the AMap console.
+The exposed instance provides `getMap()`, `refresh()`, and `fitToMarkers()` for tab visibility changes, container resizes, and custom business layers. OpenStreetMap mode normalizes both the Leaflet ESM namespace and CommonJS `default` shape internally, so hosts do not need whole-package prebundling for correctness. `map-type="amap"` requires `amap-key`; keys created after 2021-12-02 also require `:amap-security-config="{ serviceHost: '/_AMapService' }"` (recommended in production so the server proxy retains the security secret), or `{ securityJsCode: '...' }` for development only, as described by the [official AMap security guidance](https://lbs.amap.com/api/javascript-api-v2/guide/abc/jscode). The config is installed before the SDK script and conflicting keys on one page are rejected. The host CSP must also allow `https://webapi.amap.com` in `script-src`, with domain allowlists and quotas enforced in the AMap console.
 
 `C_Date`, `C_Time`, `C_Menu`, and `C_FormSearch` support standard `v-model`. Message/dialog providers are optional; application-wide feedback, locale, form defaults, and `table.defaults` can be supplied through plugin options.
 
 ### 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 +333,37 @@ 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)
+### 📋 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
 
@@ -280,6 +396,7 @@ With `require-server-verification`, a successful response must include a server
 | 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                                        | -                    |
@@ -321,7 +438,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 +448,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 +463,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;