@robot-admin/naive-ui-components 0.14.2 → 0.15.0

package/docs/architecture.en.md

@@ -0,0 +1,83 @@
+[← Project README](../README_EN.md) · [中文](./architecture.md)
+
+# Architecture and isolation
+
+This library remains the independently maintained Naive UI adapter. A future Element Plus package will serve other applications with its own installation and releases. Adapters can share business protocols and proven logic, while keeping UI components, types and styles independent.
+
+## Current boundaries
+
+| Layer                                | Responsibility                                               | Constraint                                                       |
+| ------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `src/core/`                          | Feedback/locale protocols, dictionaries and pure translation | No Vue, UI library, browser environment or ambient runtime state |
+| `src/context.ts`, `src/composables/` | Vue injection keys and locale context                        | No Naive message/dialog implementation                           |
+| `src/adapters/naive/`                | Naive Message/Dialog integration                             | UI-specific feedback stays here                                  |
+| `src/components/`                    | Existing `C_*` components, Naive types and views             | Preserve existing APIs; these are not a generic UI core          |
+| `src/config.ts`                      | Compatibility exports                                        | Preserve established import paths                                |
+
+The core is currently an internal boundary, not a separately published package. A real Element Plus pilot will determine what becomes shared. The new adapter must not depend on this whole Naive package. Naive `FormInst`, native field behavior and `DataTableBaseColumn` remain adapter-specific.
+
+## Dependencies and published entries
+
+- Component subpaths load their own component graph and support page/route-level loading.
+- Full installation registers the public `C_*` names, avoiding collisions between inferred `index.vue` names or a host application's `index` component.
+- The root entry aggregates all components, including navigation, and preserves full installation. Runtime root imports require the optional `vue-router` peer, even for a non-routing named export. Applications without a router should use component subpaths.
+- `sortablejs` is needed only for the corresponding drag features. Selective JS loading does not mean ordinary runtime dependencies are selectively installed.
+- ESM resolves `.d.ts`; CJS resolves `.d.cts`. Each declaration condition matches its JavaScript format.
+- All public reachable declarations are checked for `naive-ui/es/*` and `naive-ui/lib/*` internal imports, in both formats.
+
+The consumer contract check unpacks a real tarball into a temporary directory and attaches the repository's resolved dependencies. It covers Node16/NodeNext ESM/CJS types and subpath runtime imports without optional peers. It does not reinstall online, so it does not replace minimum/latest dependency matrices or application acceptance.
+
+## Highlight instances
+
+```ts
+import {
+  createHighlight,
+  setupHighlight,
+} from '@robot-admin/naive-ui-components'
+
+const standalone = createHighlight({ autoDetect: true })
+const application = setupHighlight(app, { autoDetect: false })
+```
+
+Every `createHighlight()` and `setupHighlight()` owns its hljs instance, registered languages and loading state. In component setup, `useHighlight()` prefers the application's injected API; outside that context it creates an independent API. Retain an API explicitly when multiple calls should share it.
+
+`window.hljs` is untouched by default. Legacy consumers can explicitly use `setupHighlight(app, { exposeToWindow: true })`; unmount restores the previous property according to ownership and preserves subsequent host updates. The `highlightManager` injection key remains compatible.
+
+## Form renderer registries
+
+```ts
+import { createApp, h } from 'vue'
+import { NInput } from 'naive-ui'
+import Components, {
+  createFormRendererRegistry,
+} from '@robot-admin/naive-ui-components'
+import App from './App.vue'
+
+const renderers = createFormRendererRegistry({
+  input: props => h(NInput, { ...props, clearable: true }),
+})
+
+createApp(App).use(Components, { formRenderers: renderers }).mount('#app')
+```
+
+The full plugin creates a registry per application by default. Sharing is explicit by passing the same registry. With local component imports, use `app.provide(FORM_RENDERER_REGISTRY_KEY, registry)`; both the factory and key are also exported from the `C_Form` subpath.
+
+Precedence is: component `renderers` → independent registry → built-in renderer. Independent registries do not fall back to the legacy global registry. Registration returns an identity-bound disposer; a stale disposer cannot remove a newer registration, and runtime additions/removals update components.
+
+`registerRenderer()` / `unregisterRenderer()` remain explicit legacy global APIs for consumers without an independent registry. Existing full-plugin applications should migrate custom renderers to `formRenderers` or register on that same registry, rather than expecting global updates to affect installed applications.
+
+## Element Plus roadmap
+
+1. Stabilize current Naive entrypoints, styles, consumers and isolation contracts.
+2. Introduce an independent Element Plus package with a real business pilot for forms, search, tables, form dialogs and actions.
+3. Reuse `form-validate` RuleSpec, `request-core/vue` Headless CRUD and `theme/core` / `theme/tokens` where applicable.
+4. Extract neutral field, column, validation and state protocols from the pilot. UI props, events, instances and rendering stay in their adapters.
+5. Keep each package's UI peers, builds, releases and CSS entries independent. Installing one for an application must not require the other UI library.
+
+Running both UI libraries in one application is outside this iteration. That would additionally require registration names, style namespaces, overlay targets and theme ownership checks. Element Plus documents coordinated [ConfigProvider/SCSS namespaces](https://element-plus.org/en-US/guide/namespace.html) and [scoped theme variables](https://element-plus.org/en-US/guide/theming.html).
+
+## Acceptance
+
+Verify behavior through published consumers, public types, multiple applications, dynamic registration, unmount and host-state restoration. Source-level dependency guards complement runtime verification.
+
+`bun run verify` is the local quality gate. `bun run check:audit` remains a separate check and CI gate. Record actual advisory results; do not hide them by disabling checks or forcing unverified major versions.

package/docs/architecture.md

@@ -0,0 +1,83 @@
+[← 项目首页](../README.md) · [English](./architecture.en.md)
+
+# 架构与隔离边界
+
+本组件库继续作为 Naive UI 的独立适配包维护。未来 Element Plus 面向其他项目独立安装、独立发布；两套呈现层共享业务协议和经过实际验证的逻辑，不相互依赖组件、类型或样式。
+
+## 本轮收敛范围
+
+| 层级                                 | 当前职责                             | 边界                                    |
+| ------------------------------------ | ------------------------------------ | --------------------------------------- |
+| `src/core/`                          | 反馈／语言协议、默认语言和纯翻译函数 | 无 Vue、UI 库、浏览器环境与全局运行状态 |
+| `src/context.ts`、`src/composables/` | Vue 注入键与语言上下文绑定           | 不承担 Naive 消息、弹窗实现             |
+| `src/adapters/naive/`                | Naive Message / Dialog 适配          | Naive 消息／弹窗反馈留在适配层          |
+| `src/components/`                    | 现有 `C_*` 组件、Naive 类型与呈现    | 保留稳定 API，不假装为通用 UI 内核      |
+| `src/config.ts`                      | 原有配置导入的兼容入口               | 对已有消费者保留导出路径                |
+
+目前 `core` 是仓库内部边界，尚未发布独立公共 core 包。未来通过 Element Plus 的真实场景提取共享包，不让新适配器依赖整个 Naive 包。现有表单的 `FormInst`、原生字段与表格的 `DataTableBaseColumn` 继续属于 Naive 层。
+
+## 依赖与发布入口
+
+- 组件子路径消费目标组件及其依赖，适合独立页面和路由加载。
+- 全量插件使用公开的 `C_*` 名称注册组件，不以 SFC 的编译推断名注册，避免多个 `index.vue` 互相覆盖或覆盖宿主的 `index` 组件。
+- 根入口聚合全部组件并保留全量安装语义，包含导航组件；运行时导入根入口需要安装可选 peer `vue-router`，即使只使用根入口中的非路由组件。无需路由的项目优先使用组件子路径。
+- `sortablejs` 只在启用对应拖拽功能时需要。可选 peer 与 JS 按需加载不意味着普通运行依赖也按需安装。
+- ESM 使用 `.d.ts`，CJS 使用 `.d.cts`；条件类型入口与相应 JavaScript 格式对应。
+- 公共可达声明同时检查 ESM / CJS，不能引用 `naive-ui/es/*` 或 `naive-ui/lib/*` 内部路径。
+
+新增消费者契约验证使用真实 tarball，在临时目录解包并接入仓库已解析的依赖；覆盖 Node16 / NodeNext 的 ESM / CJS 类型与缺失可选 peer 的子路径运行行为。它不联网重新安装依赖，因此不能代替最低／最新依赖版本矩阵或真实应用验收。
+
+## 高亮实例
+
+```ts
+import {
+  createHighlight,
+  setupHighlight,
+} from '@robot-admin/naive-ui-components'
+
+const standalone = createHighlight({ autoDetect: true })
+const application = setupHighlight(app, { autoDetect: false })
+```
+
+`createHighlight()`、每次 `setupHighlight()` 均独立持有 hljs、语言注册和加载状态。组件 `setup` 中的 `useHighlight()` 优先读取当前应用注入；独立上下文调用则创建自己的 API。需要跨调用复用时，保留并传递同一个 API，不能依赖模块单例。
+
+默认不会写入 `window.hljs`。确实依赖旧窗口 API 的应用可显式使用 `setupHighlight(app, { exposeToWindow: true })`；卸载时按所有权恢复原属性，宿主后续覆盖的值不会被回收。现有 `highlightManager` 注入键及组件消费方式保留。
+
+## 表单渲染器
+
+```ts
+import { createApp, h } from 'vue'
+import { NInput } from 'naive-ui'
+import Components, {
+  createFormRendererRegistry,
+} from '@robot-admin/naive-ui-components'
+import App from './App.vue'
+
+const renderers = createFormRendererRegistry({
+  input: props => h(NInput, { ...props, clearable: true }),
+})
+
+createApp(App).use(Components, { formRenderers: renderers }).mount('#app')
+```
+
+全量插件默认为每个应用创建独立 registry；显式传入同一 registry 才共享。局部注册组件的应用可以使用 `app.provide(FORM_RENDERER_REGISTRY_KEY, registry)`，工厂和键也从 `C_Form` 子路径导出。
+
+优先级为：组件实例的 `renderers` → 独立 registry → 内置 renderer。独立 registry 不回退到 legacy 全局注册表。`register()` 返回身份绑定的注销函数；覆盖后调用旧注销函数不会删除新注册，运行时增删也会更新组件。
+
+`registerRenderer()` / `unregisterRenderer()` 仍作为显式 legacy 全局 API 保留，只用于没有独立 registry 的旧消费路径。已有全量插件项目应将自定义渲染器改为传入 `formRenderers`，或在同一个 registry 上注册；不再依赖全局注册影响已安装的其他应用。
+
+## Element Plus 演进顺序
+
+1. 保持 Naive 入口、样式和既有业务消费稳定，先收敛当前发布与状态隔离问题。
+2. 新建独立 Element Plus 适配包，从表单、查询、表格、表单弹窗和操作栏选择真实业务试点。
+3. 优先复用现有 `form-validate` 的 RuleSpec、`request-core/vue` 的 Headless CRUD，以及 `theme/core` / `theme/tokens`；不复制同一套数据状态机。
+4. 由试点提取中立字段、列、校验和状态协议；具体 UI props、事件映射、实例与渲染器分别留在各适配包。
+5. 两个包各自声明 UI peer、构建、发布和样式入口。独立应用安装其中一个时，不要求另一个 UI 库。
+
+本轮不要求同一应用同时运行两套 UI。未来如果新增该需求，需要另验组件注册名、样式命名空间、弹层挂载与主题所有权；Element Plus 的[命名空间](https://element-plus.org/en-US/guide/namespace.html)需要 ConfigProvider 与 SCSS 配置一致，其[主题文档](https://element-plus.org/en-US/guide/theming.html)也建议按局部类作用域覆盖变量。
+
+## 验收原则
+
+测试验证实际行为：发布消费者、稳定公共类型、双应用配置、动态注册／注销、卸载与宿主状态恢复。源码结构守卫只负责依赖方向，不能代替实际运行测试。
+
+`bun run verify` 覆盖本地完整质量门禁；`bun run check:audit` 保留独立执行与 CI 门禁。审计告警需按真实结果处理，不通过关闭门禁或未验证的主版本覆盖隐藏风险。

package/docs/assets/README.md

@@ -0,0 +1,47 @@
+# 品牌资源 / Brand assets
+
+沿用 Robot 家族的几何 R、机器人双眼和天线，以绿色区分 Naive UI 组件库；右下角模块表示组件独立导入。标识用于本项目文档，不代表 Naive UI 官方品牌。
+
+| 文件                                                               | 用途                             |
+| ------------------------------------------------------------------ | -------------------------------- |
+| [naive-ui-components-logo.svg](./naive-ui-components-logo.svg)     | 128 × 128，透明背景，可缩放 Logo |
+| [naive-ui-components-logo.png](./naive-ui-components-logo.png)     | 512 × 512，透明背景，通用预览    |
+| [naive-ui-components-banner.svg](./naive-ui-components-banner.svg) | 1280 × 420，可编辑封面源文件     |
+| [naive-ui-components-banner.png](./naive-ui-components-banner.png) | 2560 × 840，README 高清封面      |
+
+主色为 `#249D70` / `#0C5E47`，强调色为 `#A7F3CB`，封面底色为 `#0B1C19`。封面右侧是表单、表格与流程的示意插画。
+
+SVG 自包含，无外部字体、脚本、图片或网络请求。中英文 README 共用英文封面；项目定位与操作说明在各自正文中提供。
+
+修改 SVG 后，在具备 Playwright 和 Chromium 的环境中执行以下导出示例。`playwright` 是文档导出工具，组件库运行时无需安装。
+
+```js
+import { chromium } from 'playwright'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const browser = await chromium.launch()
+try {
+  for (const [name, width, height, scale] of [
+    ['banner', 1280, 420, 2],
+    ['logo', 128, 128, 4],
+  ]) {
+    const page = await browser.newPage({
+      viewport: { width, height },
+      deviceScaleFactor: scale,
+    })
+    const base = resolve(`docs/assets/naive-ui-components-${name}`)
+    await page.goto(pathToFileURL(`${base}.svg`).href)
+    await page
+      .locator('svg')
+      .first()
+      .screenshot({
+        path: `${base}.png`,
+        omitBackground: true,
+      })
+    await page.close()
+  }
+} finally {
+  await browser.close()
+}
+```

package/docs/assets/naive-ui-components-banner.svg

@@ -0,0 +1,69 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="420" viewBox="0 0 1280 420" role="img" aria-labelledby="title description">
+  <title id="title">Robot Naive UI Components</title>
+  <desc id="description">55 Vue 3 business components. Typed configuration, independent component entries and scoped styles, in the Robot ecosystem.</desc>
+  <defs>
+    <linearGradient id="background" x1="0" y1="0" x2="1280" y2="420" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#0B1C19"/><stop offset="1" stop-color="#102B24"/>
+    </linearGradient>
+    <linearGradient id="tile" x1="8" y1="4" x2="120" y2="128" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#249D70"/><stop offset="1" stop-color="#0C5E47"/>
+    </linearGradient>
+    <linearGradient id="shine" x1="20" y1="0" x2="110" y2="120" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFF" stop-opacity=".16"/><stop offset="1" stop-color="#FFF" stop-opacity="0"/>
+    </linearGradient>
+    <pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M32 0H0V32" fill="none" stroke="#A7F3CB" stroke-opacity=".035"/>
+    </pattern>
+    <radialGradient id="glow">
+      <stop stop-color="#49CF91" stop-opacity=".13"/><stop offset="1" stop-color="#49CF91" stop-opacity="0"/>
+    </radialGradient>
+    <clipPath id="bounds"><rect width="1280" height="420" rx="24"/></clipPath>
+  </defs>
+  <g clip-path="url(#bounds)">
+    <rect width="1280" height="420" fill="url(#background)"/>
+    <rect width="1280" height="420" fill="url(#grid)"/>
+    <ellipse cx="1080" cy="150" rx="340" ry="270" fill="url(#glow)"/>
+    <path d="M64 326H1216" stroke="#94B5A5" stroke-opacity=".18"/>
+    <!-- Robot family R mark; the detached tile represents independent components. -->
+    <svg x="60" y="112" width="130" height="130" viewBox="0 0 128 128">
+      <rect x="2" y="2" width="124" height="124" rx="30" fill="url(#tile)"/>
+      <rect x="2.5" y="2.5" width="123" height="123" rx="29.5" fill="url(#shine)" stroke="#FFF" stroke-opacity=".2"/>
+      <path d="M35 99V35H69C86 35 96 44 96 60C96 72 90 80 81 83L99 99H78L61 85H51V99H35ZM51 51V69H68C75 69 79 66 79 60C79 54 75 51 68 51H51Z" fill="#F2FFF7"/>
+      <path d="M66 34V28" stroke="#F2FFF7" stroke-width="4" stroke-linecap="round"/>
+      <circle cx="66" cy="23" r="4" fill="#A7F3CB"/>
+      <rect x="55" y="56" width="5" height="7" rx="2.5" fill="#64D8A0"/>
+      <rect x="67" y="56" width="5" height="7" rx="2.5" fill="#64D8A0"/>
+      <rect x="103" y="99" width="21" height="21" rx="6" fill="#B5F5D3" stroke="#0C5E47" stroke-width="3"/>
+    </svg>
+    <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif">
+      <text x="64" y="62" fill="#8BAE9E" font-size="12" font-weight="600" letter-spacing="2.4">ROBOT ECOSYSTEM / COMPONENT LIBRARY</text>
+      <text x="224" y="155" fill="#F2FFF7" font-size="52" font-weight="750" letter-spacing="-1.8">Naive UI Components</text>
+      <text x="227" y="196" fill="#B4CFC1" font-size="18">Business interfaces, composed with confidence.</text>
+      <text x="227" y="234" fill="#72DDA6" font-size="15" font-family="SFMono-Regular,Consolas,monospace">@robot-admin/naive-ui-components</text>
+      <text x="227" y="278" fill="#809F90" font-size="13">Forms · Tables · Editors · Workflow · Media</text>
+      <g font-size="12" font-weight="600" letter-spacing="1.4">
+        <text x="64" y="369" fill="#A7F3CB">55 COMPONENTS</text>
+        <text x="318" y="369" fill="#AFC9BC">VUE 3 + TYPESCRIPT</text>
+        <text x="633" y="369" fill="#AFC9BC">PER-COMPONENT IMPORTS</text>
+        <text x="1018" y="369" fill="#AFC9BC">OPEN SOURCE / MIT</text>
+      </g>
+    </g>
+    <!-- A composition of a form, a table and a flow; an illustration, not an application screenshot. -->
+    <g transform="translate(936 88)" stroke="#5C9D7F" stroke-width="1.3">
+      <path d="M70 84H96V50H140M96 50V156H154" fill="none" stroke="#72DDA6" stroke-opacity=".5"/>
+      <rect x="0" y="0" width="120" height="144" rx="12" fill="#112E25"/>
+      <path d="M0 29H120" stroke-opacity=".5"/>
+      <g fill="#83B79D" stroke="none"><circle cx="14" cy="15" r="2"/><circle cx="22" cy="15" r="2"/><circle cx="30" cy="15" r="2"/></g>
+      <g fill="#153C2F" stroke="#416B56"><rect x="16" y="45" width="88" height="20" rx="4"/><rect x="16" y="77" width="88" height="20" rx="4"/></g>
+      <rect x="60" y="111" width="44" height="17" rx="4" fill="#64D8A0" stroke="none"/>
+      <path d="M23 55H62M23 87H77" stroke="#81AA94" stroke-linecap="round"/>
+      <rect x="146" y="-13" width="122" height="101" rx="12" fill="#183C2E"/>
+      <path d="M146 14H268M146 39H268M146 63H268M183 14V88M224 14V88" stroke-opacity=".45"/>
+      <rect x="159" y="-1" width="44" height="4" rx="2" fill="#8ACBA8" stroke="none"/>
+      <g fill="#73DFA7" stroke="none"><rect x="157" y="23" width="14" height="5" rx="2"/><rect x="193" y="48" width="20" height="5" rx="2"/><rect x="235" y="72" width="20" height="5" rx="2"/></g>
+      <rect x="145" y="123" width="114" height="96" rx="12" fill="#112E25"/>
+      <path d="M202 149V184M175 184H229" fill="none" stroke="#72DDA6" stroke-opacity=".7"/>
+      <g fill="#285B42" stroke="#72DDA6"><rect x="187" y="139" width="30" height="19" rx="4"/><rect x="162" y="178" width="27" height="19" rx="4"/><rect x="216" y="178" width="27" height="19" rx="4"/></g>
+    </g>
+  </g>
+</svg>

package/docs/assets/naive-ui-components-logo.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-labelledby="title description">
+  <title id="title">Robot Naive UI Components logo</title>
+  <desc id="description">The Robot R monogram with two robot eyes, an antenna and a modular mint-green tile.</desc>
+  <defs>
+    <linearGradient id="tile" x1="8" y1="4" x2="120" y2="128" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#249D70"/>
+      <stop offset="1" stop-color="#0C5E47"/>
+    </linearGradient>
+    <linearGradient id="shine" x1="20" y1="0" x2="110" y2="120" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFF" stop-opacity=".16"/>
+      <stop offset="1" stop-color="#FFF" stop-opacity="0"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="124" height="124" rx="30" fill="url(#tile)"/>
+  <rect x="2.5" y="2.5" width="123" height="123" rx="29.5" fill="url(#shine)" stroke="#FFF" stroke-opacity=".2"/>
+  <path d="M35 99V35H69C86 35 96 44 96 60C96 72 90 80 81 83L99 99H78L61 85H51V99H35ZM51 51V69H68C75 69 79 66 79 60C79 54 75 51 68 51H51Z" fill="#F2FFF7"/>
+  <path d="M66 34V28" stroke="#F2FFF7" stroke-width="4" stroke-linecap="round"/>
+  <circle cx="66" cy="23" r="4" fill="#A7F3CB"/>
+  <rect x="55" y="56" width="5" height="7" rx="2.5" fill="#64D8A0"/>
+  <rect x="67" y="56" width="5" height="7" rx="2.5" fill="#64D8A0"/>
+  <rect x="103" y="99" width="21" height="21" rx="6" fill="#B5F5D3" stroke="#0C5E47" stroke-width="3"/>
+</svg>

package/docs/components.en.md

@@ -0,0 +1,118 @@
+[← English README](../README_EN.md) · [中文](./components.md)
+
+# Component catalog
+
+> 💡 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_Loading`      | Theme-aware SVG loading   | -                             |
+| `C_PageLoading`  | Theme-aware page loading  | -                             |
+| `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
+
+| Component         | Description                  | External Deps             |
+| ----------------- | ---------------------------- | ------------------------- |
+| `C_Editor`        | Rich text editor             | `@wangeditor-next/editor` |
+| `C_Markdown`      | Markdown editor/preview      | `md-editor-v3`            |
+| `C_FormulaEditor` | Formula editor (safe parser) | Built in                  |
+| `C_Signature`     | Electronic signature         | -                         |
+| `C_QRCode`        | QR code generator            | `qrcode`                  |
+| `C_ImageCropper`  | Image cropper                | `vue-cropper`             |
+
+## Data Display Components
+
+| Component        | Description                                  | External Deps              |
+| ---------------- | -------------------------------------------- | -------------------------- |
+| `C_Table`        | Advanced data table (CRUD/inline edit/print) | `print-js`, `html2canvas`  |
+| `C_Map`          | Map component (OSM/AMap)                     | `leaflet`                  |
+| `C_VtableGantt`  | Gantt chart                                  | `@visactor/vtable-gantt`   |
+| `C_AntV`         | Graph editor (ER/BPMN/UML)                   | `@antv/x6`, `html2canvas`  |
+| `C_WaterFall`    | Waterfall layout                             | -                          |
+| `C_FullCalendar` | Calendar events                              | `@fullcalendar/*`          |
+| `C_VideoPlayer`  | Video player (HLS/subtitles/bookmarks)       | `xgplayer`, `xgplayer-hls` |
+| `C_AudioPlayer`  | Audio player (waveform/progress/playlist)    | -                          |
+| `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                                        | -                    |
+| `C_Draggable`     | Drag & drop sorting                               | `vue-draggable-plus` |
+| `C_Tree`          | Advanced tree control                             | -                    |
+| `C_Time`          | Enhanced time picker                              | -                    |
+| `C_Cron`          | Cron expression editor                            | -                    |
+| `C_Transfer`      | Transfer / shuttle box                            | -                    |
+
+## Interactive & Business Components
+
+| Component       | Description                                   | External Deps |
+| --------------- | --------------------------------------------- | ------------- |
+| `C_Chat`        | Chat (contacts / message bubbles / input box) | -             |
+| `C_ContextMenu` | Context menu (nested / shortcuts / danger)    | -             |
+| `C_Login`       | Login panel (5 modes / captcha / remember me) | -             |
+
+## Workflow & Notification Components
+
+| Component              | Description                              | External Deps    |
+| ---------------------- | ---------------------------------------- | ---------------- |
+| `C_WorkFlow`           | Workflow editor (approval/CC/conditions) | `@vue-flow/core` |
+| `C_NotificationCenter` | Notification center (WebSocket/polling)  | -                |
+| `C_Upload`             | Large file upload (chunked/resumable)    | `spark-md5`      |
+
+## 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
+bun add vue naive-ui
+```
+
+Install optional peers per feature: `vue-router` for `C_Breadcrumb`/`C_TagsView`, and `sortablejs` for C_Table row/column dragging. Subpath imports do not require unrelated optional peers. The formula editor uses a bounded built-in parser and does not execute dynamic JavaScript.

package/docs/components.md

@@ -0,0 +1,118 @@
+[← 项目首页](../README.md) · [English](./components.en.md)
+
+# 组件目录
+
+> 💡 所有组件均提供 **在线交互演示**，访问 [组件文档](https://www.tzagileteam.com/robot/components/preface) 可直接在页面中体验真实效果（通过 iframe 嵌入 Robot Admin 生产环境）。
+
+## 基础组件
+
+| 组件             | 说明                    | 外部依赖                      |
+| ---------------- | ----------------------- | ----------------------------- |
+| `C_Icon`         | Iconify 图标封装        | `@iconify/vue`                |
+| `C_Loading`      | 主题化 SVG 加载态       | -                             |
+| `C_PageLoading`  | 主题化页面切换加载      | -                             |
+| `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`     | 骨架屏占位组件          | -                             |
+
+## 内容 & 编辑组件
+
+| 组件              | 说明                         | 外部依赖                  |
+| ----------------- | ---------------------------- | ------------------------- |
+| `C_Editor`        | 富文本编辑器                 | `@wangeditor-next/editor` |
+| `C_Markdown`      | Markdown 编辑器/预览         | `md-editor-v3`            |
+| `C_FormulaEditor` | 公式编辑器（安全表达式引擎） | 内置                      |
+| `C_Signature`     | 电子签名                     | -                         |
+| `C_QRCode`        | 二维码生成器                 | `qrcode`                  |
+| `C_ImageCropper`  | 图片裁剪器                   | `vue-cropper`             |
+
+## 数据展示组件
+
+| 组件             | 说明                                      | 外部依赖                   |
+| ---------------- | ----------------------------------------- | -------------------------- |
+| `C_Table`        | 高级数据表格（CRUD/行列编辑/动态行/打印） | `print-js`、`html2canvas`  |
+| `C_Map`          | 地图组件（OSM/高德）                      | `leaflet`                  |
+| `C_VtableGantt`  | 甘特图                                    | `@visactor/vtable-gantt`   |
+| `C_AntV`         | 图编辑器（ER/BPMN/UML）                   | `@antv/x6`、`html2canvas`  |
+| `C_WaterFall`    | 瀑布流布局                                | -                          |
+| `C_FullCalendar` | 日历事件                                  | `@fullcalendar/*`          |
+| `C_VideoPlayer`  | 视频播放器（HLS/字幕/书签/章节）          | `xgplayer`、`xgplayer-hls` |
+| `C_AudioPlayer`  | 音频播放器（波形/进度/播放列表）          | -                          |
+| `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`     | 分割面板                                          | -                    |
+| `C_Draggable`     | 拖拽排序                                          | `vue-draggable-plus` |
+| `C_Tree`          | 高级树形控件                                      | -                    |
+| `C_Time`          | 时间选择器增强                                    | -                    |
+| `C_Cron`          | Cron 表达式编辑器                                 | -                    |
+| `C_Transfer`      | 穿梭框（搜索/全选/批量操作）                      | -                    |
+
+## 交互 & 业务组件
+
+| 组件            | 说明                                   | 外部依赖 |
+| --------------- | -------------------------------------- | -------- |
+| `C_Chat`        | 聊天组件（联系人/消息气泡/输入框）     | -        |
+| `C_ContextMenu` | 右键菜单（嵌套子菜单/快捷键/危险操作） | -        |
+| `C_Login`       | 登录组件（5种模式/验证码/记住用户名）  | -        |
+
+## 流程 & 通知组件
+
+| 组件                   | 说明                                 | 外部依赖         |
+| ---------------------- | ------------------------------------ | ---------------- |
+| `C_WorkFlow`           | 工作流编辑器（审批/抄送/条件节点）   | `@vue-flow/core` |
+| `C_NotificationCenter` | 通知中心（WebSocket/轮询）           | -                |
+| `C_Upload`             | 大文件上传（分片/断点续传/哈希校验） | `spark-md5`      |
+
+## 依赖说明
+
+`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
+bun add vue naive-ui
+```
+
+按功能安装可选 peer：使用 `C_Breadcrumb`/`C_TagsView` 时安装 `vue-router`；启用 C_Table 行/列拖拽时安装 `sortablejs`。子路径导入不会要求无关的可选 peer。公式编辑器使用组件库内置的受限表达式解析器，不执行动态 JavaScript。