@robot-admin/naive-ui-components 0.16.0 → 0.17.1

package/docs/component-review-20261019.md

@@ -0,0 +1,55 @@
+# 表格布局、性能与组件复查
+
+日期：2026-10-19。基线为 `v0.17.0`，本轮修改通过 Changeset 登记为后续补丁，不将源码合入描述为已发布新 npm 版本。
+
+## 展开列间距的原因与默认行为
+
+原样式给非末列统一加 `min-width: 80px !important`；普通列映射又为辅助列填入业务默认宽度，展开/选择增强器随后丢弃显式元数据。宽屏自动布局还会把空余空间分给所有定宽列，不能只改一个 CSS 数字。
+
+本轮将辅助列默认宽度收敛为选择 40、展开 40、序号 50。未声明宽度的普通非固定业务列保持自然弹性，并保留首选最小宽度；辅助列与弹性业务列共存时默认采用原生 fixed 布局。显式宽度、上限、固定位置、全局列宽和原生 table-layout 不被改写。所有业务列均显式定宽时保留原生余量分配语义。
+
+相同 1440px 独立浏览器场景中，0.17.0 的三个辅助列各约 142.56px；修改后为 40/40/50px。该场景含一列未指定宽度、最小宽度 220px 的名称列，同时测试普通与固定列布局。详细配置见[表格指南](./guides/table-density.md)。
+
+## 性能改进的可验证范围
+
+| 位置           | 原问题                                        | 修改与验证                                                                          |
+| -------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 程序化跨页选择 | 每选择一个键都扫描本地数据                    | 首次使用时建索引，重复查询复用；1 万行选择末尾 100 行，rowKey 调用 995,150 → 10,100 |
+| 批量展开       | 每个新键线性找行，差集反复 includes           | 惰性行键索引与 Set 差集；1 万键展开线性访问，不重复扫描                             |
+| 树行辅助遍历   | 深度递归可栈溢出                              | 迭代 DFS，保留对象身份、顺序和循环/共享节点去重                                     |
+| 表单修改检测   | 只判断是否修改仍比较所有字段                  | 首个差异短路；嵌套 Map/Set 修改仍可触发外层计算                                     |
+| 图和甘特实例   | 第三方大型对象被 Vue 深代理，同帧配置多次重建 | 原始实例浅引用，甘特主题/配置合并监听与重复初始化取消                               |
+
+以上是算法调用量和生命周期验证，不表示整表 FPS 按同比例提升。2 万深、15 万宽的辅助遍历测试不代表 Naive 原生能渲染同等规模的 DOM；实际大表仍应使用分页、虚拟滚动、稳定且唯一的 rowKey。
+
+## 其他已修复问题
+
+| 组件                     | 修改                                                                              |
+| ------------------------ | --------------------------------------------------------------------------------- |
+| Login                    | 异步校验任务锁；等待后重新核对禁用、加载、表单快照、视图与卸载状态                |
+| ImageCropper / Signature | 新读取、清空、替换与卸载使旧图片结果失效；裁剪导出在 scope 结束时结算并释放计时器 |
+| WorkFlow                 | 清理旧定位延迟；卸载、替换画布、删除节点或重置后不打开旧配置                      |
+| TagsView                 | 批量关闭保留所有 affix 固定标签                                                   |
+| Chat                     | 历史前插保留阅读位置；同条数切换会话定位；末条消息更新仅在接近底部时跟随          |
+| VideoPlayer              | 常规 WebVTT 时间行正确解析；复用字幕请求，防切换乱序、关闭后重开和卸载后写入      |
+| Barcode                  | 按真实 vendor 契约传入 options，非法内容触发 error 并支持恢复                     |
+| Draggable                | 跨列表及克隆事件返回真实业务对象，避免把 DOM 或邻项当业务数据                     |
+
+## 审查范围与后续空间
+
+后续进展：本节列出的列表窗口化、字幕索引、瀑布流图片批处理及 Code/QRCode 异步边界已在后续专项处理中完善，见[大列表与异步任务](./guides/runtime-performance.md)。下文保留本次表格复查时的记录，不能将两个阶段的测试数量混用。
+
+本轮逐项源码审读 51 个公开组件：表单/表格/树与分割、导航/标签/主题、消息/工作流、图表、媒体/编辑器、选择/拖拽、加载与其他工具组件。Map、OrgChart、FilePreview、Upload 在另一个活动工作区单独改进，本轮不覆盖或混入其未提交修改。公共 `_shared` 目录不计作业务组件。
+
+审读重点是高频计算、重复初始化、事件/observer/计时器释放、异步任务身份、公开事件和 vendor 真实接入。只有已修改路径及明确场景有新增针对性回归，不能将源码审读等同于所有组件、浏览器、第三方引擎都做了压测。
+
+仍有专项空间：WaterFall 图片布局批处理与窗口化、Chat/Transfer/GlobalSearch 等海量列表的窗口化、长字幕的时间索引、媒体运行时配置切换与大文档编辑性能。现有普通 DOM 列表并非无限数据容器；应按实际数据量和耗时/内存证据推进，不为了统一形式给所有组件加入自建虚拟滚动和更多开关。
+
+次要异步状态仍可进一步完善：Code 快速切换语言时 loading 尚无独立请求代次；QRCode 的旧 Logo 图像请求虽不会提交过期结果，底层网络加载本身没有主动取消。这些没有作为本轮已修复项。
+
+## 本轮实际校验
+
+- 完整 `bun run verify` 通过：282 项单元、173 项真实组件挂载，以及 TypeScript、Vue/组件/消费者声明、lint、构建、ESM/CJS 与 Node16/NodeNext 打包消费者契约检查。
+- 包与四个轻量入口的体积预算通过，未放宽预算；消费者契约复用本机安装的依赖版本，没有宣称重新从公开 registry 安装了尚未发布的补丁。
+- 隔离浏览器以 1440/720/420px、明暗主题和三种密度组合运行 18 组场景、36 个表格实例，核对实际辅助列宽、表头/表体对齐、业务最小宽度、展开/收起、真实选择和页面错误。对比基线使用已发布 0.17.0 的实际产物。
+- 本轮没有运行真实业务后端、没有给所有第三方引擎做性能压测，也没有以 Chromium 结果替代其他浏览器/平台验收。

package/docs/guides/form-density.en.md

@@ -0,0 +1,42 @@
+# Form and search density
+
+`C_Form`, `C_FormSearch`, and `C_Table` share `config.density`. Reuse a reactive value to align fields, action buttons, and spacing throughout a page.
+
+```vue
+<C_FormSearch v-model="query" :form-item-list="filters" :config="{ density }" />
+<C_Table :columns="columns" :data="rows" :config="{ density }" />
+<C_Form v-model="model" :options="fields" :config="{ density }" />
+```
+
+```ts
+import { ref } from 'vue'
+import type { ComponentDensity } from '@robot-admin/naive-ui-components/C_Form'
+
+const density = ref<ComponentDensity>('compact')
+```
+
+| Density       | Field and button size | Layout gap | Card padding | Form feedback minimum |
+| ------------- | --------------------- | ---------- | ------------ | --------------------- |
+| `default`     | `medium`              | 16px       | 24px         | 24px                  |
+| `compact`     | `small`               | 8px        | 12px         | 12px                  |
+| `comfortable` | `large`               | 20px       | 28px         | 28px                  |
+
+Validation feedback can grow beyond its minimum height. Changing density preserves form values, search drafts, expanded filters, and card collapse state. Each instance owns its density.
+
+Omitting `density` retains existing spacing and the default `medium` size. Explicit `C_Form` `config.size`, `C_FormSearch` `size`, field `attrs.size`, and individual layout gaps take precedence over the preset.
+
+Existing native `size` passthrough on `C_Form` retains its final-override priority and synchronizes fields and buttons. Prefer `config` for new integrations.
+
+```ts
+const config = { density: 'compact', grid: { xGap: 12 } } as const
+const fields = [
+  { type: 'input', prop: 'name' },
+  { type: 'select', prop: 'owner', attrs: { size: 'large' }, children: [] },
+]
+```
+
+All eight form layouts support density: default, inline, grid, card, tabs, steps, dynamic, and custom. Naive UI step indicators support only `small` and `medium`, so comfortable step indicators use `medium` while fields and action buttons use `large`. Custom renderers and business slots own their styling; controls with a different size contract, such as `Rate`, retain that contract.
+
+Density presets are plain data and preserve lazy loading of layouts and fields.
+
+`C_FormModal` applies `config.density` to both its form and footer buttons and inherits application form density. Without density it preserves its historical `small` field default. Table editor modals inherit table density as well.

package/docs/guides/form-density.md

@@ -0,0 +1,59 @@
+# 表单与搜索密度
+
+`C_Form`、`C_FormSearch` 和 `C_Table` 使用同一项 `config.density`。同一个页面共享一个值即可同步字段、操作按钮和布局留白，不需要逐项传尺寸。
+
+```vue
+<C_FormSearch v-model="query" :form-item-list="filters" :config="{ density }" />
+<C_Table :columns="columns" :data="rows" :config="{ density }" />
+<C_Form v-model="model" :options="fields" :config="{ density }" />
+```
+
+```ts
+import { ref } from 'vue'
+import type { ComponentDensity } from '@robot-admin/naive-ui-components/C_Form'
+
+const density = ref<ComponentDensity>('compact')
+```
+
+| 密度          | 字段与操作按钮 | 布局间距 | 卡片留白 | 表单反馈预留高度 |
+| ------------- | -------------- | -------- | -------- | ---------------- |
+| `default`     | `medium`       | 16px     | 24px     | 24px             |
+| `compact`     | `small`        | 8px      | 12px     | 12px             |
+| `comfortable` | `large`        | 20px     | 28px     | 28px             |
+
+反馈预留高度是最小值，校验错误可自然撑开。密度支持响应式切换，切换不会清空表单值、搜索草稿、折叠条件或分组展开状态；不同实例可以使用不同密度。
+
+## 保留明确覆盖
+
+已有项目未配置 `density` 时保留原来的间距和默认 `medium` 尺寸。显式配置的控件尺寸、字段尺寸和布局间距继续优先，不需要迁移旧用法。
+
+已有 `C_Form` 原生 `size` 透传继续按原有末尾覆盖顺序生效，并同步字段与操作按钮；新接入推荐统一使用 `config`。
+
+```ts
+// 布局紧凑，只有指定字段保持较大尺寸。
+const formConfig = { density: 'compact', grid: { xGap: 12 } } as const
+const fields = [
+  { type: 'input', prop: 'name' },
+  { type: 'select', prop: 'owner', attrs: { size: 'large' }, children: [] },
+]
+
+// Form: config.size 优先于 density 推导的尺寸。
+const largeFields = { density: 'compact', size: 'large' } as const
+```
+
+`C_FormSearch` 的原 `size` 属性也保留优先级：
+
+```vue
+<C_FormSearch
+  v-model="query"
+  :form-item-list="filters"
+  :config="{ density: 'compact' }"
+  size="large"
+/>
+```
+
+`C_Form` 的默认、内联、网格、卡片、标签页、步骤、动态和自定义布局均支持密度。步骤指示器只支持 Naive UI 原生的 `small`/`medium`；`comfortable` 下指示器使用 `medium`，字段和操作按钮使用 `large`。自定义渲染器和业务插槽由使用侧控制自身样式；密度不会强改业务内容或 `Rate` 等使用不同尺寸协议的组件。
+
+卡片、网格等布局仍按需加载。密度预设仅为纯数据，不引入额外 UI 依赖。
+
+`C_FormModal` 的 `config.density` 同步控制表单与页脚按钮，也继承应用级表单密度；未配置密度时保留弹窗原有 `small` 字段默认值。表格编辑弹窗也会继承表格密度。

package/docs/guides/runtime-performance.md

@@ -0,0 +1,38 @@
+# 大列表与异步任务
+
+组件保持按需导入和现有事件契约。以下优化默认生效；普通接入无需配置虚拟列表引擎、分页游标或滚动状态。
+
+## 自动减少列表 DOM
+
+| 组件             | 生效条件                           | 保留的语义                                                   |
+| ---------------- | ---------------------------------- | ------------------------------------------------------------ |
+| `C_Transfer`     | 左右面板分别按筛选后项数，100 项起 | 完整数据筛选、全选、禁用项、移动顺序、v-model                |
+| `C_Chat`         | 消息 200 条起；联系人 100 条起     | 图片、文件、系统消息、重发、联系人事件；实际测量变高行       |
+| `C_GlobalSearch` | 搜索结果列表                       | 完整匹配结果、上下键跨视口定位、Enter 选择、输入法与历史记录 |
+
+```vue
+<C_Transfer v-model="selectedKeys" :data="people" filterable />
+<C_Chat :messages="messages" :contacts="contacts" @send="sendMessage" />
+<C_GlobalSearch :options="searchOptions" />
+```
+
+窗口化复用 `vueuc` 的公开 `VVirtualList`，兼容本包声明的 Naive UI 2.35；不依赖 Naive 内部导入，也不提高 Naive peer 下限。只减少渲染的 DOM，数据仍完整保存在内存中，搜索仍检查完整索引。
+
+穿梭框的三档行高和自定义方式见[穿梭框指南](./transfer.md)。聊天会实测文本、图片和文件行高度，无需调用方预先计算高度。业务 ID 应唯一、稳定；聊天容器应有确定高度，例如外层 `height: 600px`。
+
+若打印、DOM 集成或自定义穿梭框行高需要完整节点，可给 `C_Transfer` 或 `C_Chat` 设置 `:virtual-scroll="false"`。不要把此开关作为加载更多数据的接口；聊天加载历史仍通过 `load-more` 事件及 `loading-history` 状态接入。
+
+## 聊天滚动与输入
+
+打开或切换会话定位最新消息。阅读历史时，新增消息不抢滚动位置；前插历史保留阅读锚点。正在底部时，流式文本、迟到图片与面板高度变化继续跟随。跨越自动窗口化门槛也保持当前阅读状态。
+
+公开 `scrollToBottom()` 可用于主动跳到最新消息。输入法 Enter 确认候选不会提前发送；普通 Enter 保持发送行为。
+
+## 图片、字幕和异步状态
+
+- 瀑布流将同帧图片测量合并为一次布局，参数变化和公开 `relayout()` 仍立即计算。替换图片来源后忽略旧测量，卸载时取消待执行帧。导出的 `useWaterFallLayout` 原有四参数用法保持同步行为。
+- 字幕载入时编译时间索引；播放与前后跳转查询使用二分查找，保留重叠字幕按原文件顺序首匹配的语义。
+- 代码语言加载只由当前请求更新 loading 和高亮。语言注册后主动更新高亮器引用，同一种语言异步加载完成也会重新着色。复制事件返回点击当时的文本。
+- 二维码渲染及每次导出分别保存配置快照。新渲染取消旧 Logo 加载，导出相互独立；卸载取消所有任务并释放 Image 事件。组件销毁期间尚未完成的导出会以 `AbortError` 拒绝，调用方按普通异步错误处理即可。
+
+这些改进不代表列表、瀑布流和编辑器可以无限增加数据。大规模业务仍应按实际场景分段加载、回收历史，并测量内存、交互延迟与目标浏览器表现。

package/docs/guides/split-pane.en.md

@@ -0,0 +1,103 @@
+# Split panes and multiple-table workspaces
+
+`C_SplitPane` divides a container horizontally (left/right) or vertically (top/bottom). Nest the same component to build tree/list, master/detail and three-table layouts. Slots render directly, so resizing does not recreate child components or replace their refs.
+
+## Minimal configuration
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue'
+  import { C_SplitPane } from '@robot-admin/naive-ui-components/C_SplitPane'
+  import '@robot-admin/naive-ui-components/C_SplitPane/style.css'
+  const size = ref(30)
+</script>
+
+<template>
+  <div class="workspace">
+    <C_SplitPane
+      v-model:size="size"
+      :min-first-size="240"
+      :min-second-size="320"
+      aria-label="Departments"
+    >
+      <template #first><DepartmentTree /></template>
+      <template #second><OrderList /></template>
+    </C_SplitPane>
+  </div>
+</template>
+
+<style scoped>
+  .workspace {
+    height: 100%;
+    min-height: 0;
+    min-width: 0;
+  }
+</style>
+```
+
+Omit `size` for internal state; `defaultSize` is 50. Use `v-model:size` when the application owns layout preferences or persistence. The component does not access localStorage. Scope persisted state by account, tenant and page in the application.
+
+`size`, `defaultSize`, `minSize`, `maxSize` and `step` use percentage points. `minFirstSize`, `minSecondSize` and `gutterSize` use pixels. Percentages divide the space **remaining after the gutter**. A collapsed pane has an actual zero basis, avoiding negative width or height calculations.
+
+## Nested tables
+
+```vue
+<C_SplitPane v-model:size="masterSize" :min-first-size="280" :min-second-size="420">
+  <template #first="{ collapsed }"><OrderTable v-if="!collapsed" /></template>
+  <template #second>
+    <C_SplitPane v-model:size="detailSize" direction="vertical" :min-first-size="180" :min-second-size="180">
+      <template #first><MaterialDetails /></template>
+      <template #second><DeliveryDetails /></template>
+    </C_SplitPane>
+  </template>
+</C_SplitPane>
+```
+
+Each pane needs a complete, measurable height chain from the page through Tabs, cards and table wrappers. Set `min-height:0; min-width:0` on intermediate flex containers. `C_Table flex-height` fills that workspace and keeps table rows scrolling internally. A bare table `height:100%` cannot repair a missing parent height.
+
+Pane content scrolls automatically. For a table workspace, stretch the slot root to `height:100%` and let the table own row scrolling. For a long workbench with fixed-height tables, let the relevant pane or page own vertical document scrolling. Avoid adding competing page scrollbars to every intermediate wrapper.
+
+Both slots expose `{ size, collapsed }`. By default, collapse preserves mounted content and marks it `inert` / `aria-hidden`. Use `v-if="!collapsed"` to suspend expensive tables; keep selections, edits and column preferences outside that subtree when state must survive unmounting. Otherwise keep the table mounted and let its ResizeObserver handle visibility changes. Third-party tables requiring an explicit layout call should receive it through their own API after a Tab/dialog becomes visible.
+
+Do not wire SplitPane resize events to table data queries or make the layout component depend on table instances.
+
+## Configuration and boundaries
+
+| Prop                               | Unit / default  | Meaning                                                     |
+| ---------------------------------- | --------------- | ----------------------------------------------------------- |
+| `size`                             | % / unset       | Controlled first-pane share, accepted through `update:size` |
+| `defaultSize`                      | % / 50          | Internal initial value and current reset target             |
+| `minSize / maxSize`                | % / 0 / 100     | Allowed first-pane share; reversed bounds are normalized    |
+| `minFirstSize / minSecondSize`     | px / 0          | Physical minimum width or height while expanded             |
+| `direction`                        | `horizontal`    | `horizontal` for left/right; `vertical` for top/bottom      |
+| `gutterSize`                       | px / 6          | Divider space, minimum 4                                    |
+| `step`                             | % / 2           | Arrow-key adjustment; Shift multiplies it by 10             |
+| `collapsible / showCollapseButton` | true / true     | Collapse availability and button visibility                 |
+| `disabled`                         | false           | Disables user interaction; exposed methods remain available |
+| `ariaLabel`                        | accessible name | Name the primary pane / splitter                            |
+
+Pixel constraints update with the container size and orientation. Percentage limits, pixel minima and keyboard steps are reactive. Explicit collapse bypasses expanded minima. If the container cannot satisfy both pixel minima, the available space is shared proportionally, within the percentage bounds. No negative dimensions or forced container overflow result. The application should choose a stacked or Tab layout when multiple tables no longer fit usefully.
+
+Existing uncontrolled usage remains supported. Moving the gutter outside the percentage calculation preserves 50/50 layouts and corrects asymmetric layouts by a few pixels for a normal 6px divider.
+
+## Interaction
+
+A fine divider line carries a centered capsule grip (80px long, 16px thick by default). Nearby collapse buttons appear on hover or keyboard focus and stay visible while collapsed. Borders, a restrained shadow and local accent feedback use the existing `--c-primary`, `--c-bg-card`, `--c-border` and `--c-text-3` theme tokens in both orientations.
+
+The capsule itself accepts dragging without increasing the layout space reserved by `gutterSize`. Touch input gets a 24px grip thickness and permanently visible 28px buttons. Collapsed controls dock inside the container to avoid clipping. Inline SVG arrows require no remote icon request, and reduced-motion preferences disable transitions.
+
+The [W3C APG Window Splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/) informs keyboard behavior and separator semantics. Use Left/Right for left/right layouts and Up/Down for top/bottom layouts. Home/End move to the current boundaries. Enter collapses the first pane or restores an already collapsed pane. Double-click toggles the first pane.
+
+Pointer Events support mouse, pen and touch. Pointer cancellation, window blur, document hiding, disablement, direction changes and unmounting all dispose listeners and restore the previous body cursor / text selection styles. Nested splitters do not overwrite `document.onmousemove`.
+
+The separator exposes orientation, its decimal value, responsive limits and a unique controlled pane ID. Collapse buttons expose their target and expanded state, show keyboard focus and remain visible for touch input.
+
+`resize(first, second)` reports actual displayed proportions; `update:size` requests a controlled-state change. `drag-start/drag-end` report gesture boundaries. `collapse/expand` report actual state transitions. Exposed methods: `setSize`, `resetSize`, `collapse`, `expand`, `toggle`, `getPanelInfo`.
+
+## Production-reference comparison
+
+The `wl-ui-produce` comparison was read-only: no component migration or backend write was performed. Three Vue files use `jh-drag-row`; no current `src` call uses `jh-drag-col`. Left/right tree examples come from its local layout standard 14. The installed common-core source/declarations are partly stripped, so they cannot prove every threshold documented in that standard.
+
+Both implementations are movable pane separators. The production master/detail wrapper supplies `top-height=390/470` pixel initial values; the local standard shows `left-width=240`. This library deliberately retains percentage initial values and adds physical minima, rather than introducing multiple pixel aliases. Convert an exact pixel initial value at the application boundary when needed.
+
+`c_steelListPanel` owns its ResizeObserver and table layout call. `c_steelWorkstation` also coordinates forms, streams, Tabs and business data. SplitPane supplies geometry; it does not replace those domain responsibilities or establish equivalence with Element Plus / BaseTable / AG Grid. See the [coverage assessment](../wl-ui-produce-coverage.md) for the wider limitations.

package/docs/guides/split-pane.md

@@ -0,0 +1,126 @@
+# 分割面板与复杂多表布局
+
+`C_SplitPane` 是布局组件：`horizontal` 左右分栏，`vertical` 上下分栏，按相同方式嵌套即可组合左树右表、主从表、三表及工作台。两个 slot 都直接渲染，组件引用、表格选择和未保存编辑不会因拖动重建。
+
+## 最少配置
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue'
+  import { C_SplitPane } from '@robot-admin/naive-ui-components/C_SplitPane'
+  import '@robot-admin/naive-ui-components/C_SplitPane/style.css'
+
+  const size = ref(30)
+</script>
+
+<template>
+  <div class="workbench">
+    <C_SplitPane
+      v-model:size="size"
+      :min-first-size="240"
+      :min-second-size="320"
+    >
+      <template #first><DepartmentTree /></template>
+      <template #second><OrderList /></template>
+    </C_SplitPane>
+  </div>
+</template>
+
+<style scoped>
+  .workbench {
+    height: 100%;
+    min-height: 0;
+    min-width: 0;
+  }
+</style>
+```
+
+省略 `size` 即使用内部状态，`defaultSize` 默认 50%。`v-model:size` 由应用持有当前百分比，适合与页面路由、用户偏好或业务布局状态组合。组件不直接访问 localStorage，避免多账号、多租户、页面之间污染。
+
+`size/defaultSize/minSize/maxSize/step` 始终使用百分比；`minFirstSize/minSecondSize/gutterSize` 使用 px。百分比按**扣除手柄后的可用空间**计算，两个面板总比例为 100，手柄不再从两侧各扣半宽，折叠面板为合法的零宽/零高。
+
+## 三表与树表组合
+
+```vue
+<C_SplitPane v-model:size="treeSize" :min-first-size="220" :min-second-size="520">
+  <template #first><DepartmentTree /></template>
+  <template #second>
+    <C_SplitPane
+      v-model:size="masterSize"
+      direction="vertical"
+      :min-first-size="220"
+      :min-second-size="180"
+    >
+      <template #first="{ collapsed }">
+        <OrderTable v-if="!collapsed" />
+      </template>
+      <template #second>
+        <C_SplitPane :default-size="50" :min-first-size="220" :min-second-size="220">
+          <template #first><OrderDetails /></template>
+          <template #second><DeliveryDetails /></template>
+        </C_SplitPane>
+      </template>
+    </C_SplitPane>
+  </template>
+</C_SplitPane>
+```
+
+每个 `C_SplitPane` 负责自己的约束、键盘焦点和滚动容器。页根、Tabs 内容、slot 内的卡片与表格父容器都需要可计算的高度；使用 flex 布局时，中间层设置 `min-height: 0; min-width: 0`。仅设置表格 `height:100%` 无法补齐上级容器缺失的高度。
+
+两种滚动方式按内容选用：
+
+- 表格工作区：slot 根节点撑满面板，`C_Table flex-height` 在该高度内滚动；工具栏、搜索区与分页占用工作区自身的空间。不要给每一层卡片重复添加页面滚动。
+- 文档或纵向长工作台：保持面板内容的默认 `overflow:auto`，固定高度表格在内部滚动，面板负责其余纵向内容。
+
+`#first/#second` 都提供 `{ size, collapsed }`。默认折叠只隐藏布局并设置 `inert/aria-hidden`，保留组件状态；大型表格可选择 `v-if="!collapsed"` 释放观察器与渲染工作，但卸载也会丢失未外置的选择、列状态与编辑状态。需要保留状态时保持挂载，通过表格自身的 ResizeObserver 感知展开；第三方表格要求显式 `doLayout` 时，在对应 Tab/dialog 激活后调用其公开布局方法。
+
+不要在 SplitPane 内注入表格实例，也不要把 `@resize` 绑定成每个表格查询/数据刷新的触发器。拖动只改变容器尺寸，不应请求业务数据。
+
+## 约束与边界
+
+| 配置                               | 单位 / 默认  | 含义                                                     |
+| ---------------------------------- | ------------ | -------------------------------------------------------- |
+| `size` / `v-model:size`            | % / 未设置   | 受控首面板比例；父组件接受 `update:size` 后生效          |
+| `defaultSize`                      | % / 50       | 非受控初值；`resetSize()` 也使用当前默认值               |
+| `minSize / maxSize`                | % / 0 / 100  | 首面板可拖动比例范围；反向配置会自动排序                 |
+| `minFirstSize / minSecondSize`     | px / 0       | 展开时各面板的实际宽度或高度下限                         |
+| `direction`                        | `horizontal` | 左右；`vertical` 为上下                                  |
+| `gutterSize`                       | px / 6       | 手柄占用空间，最小 4                                     |
+| `step`                             | % / 2        | 方向键每次调整量                                         |
+| `collapsible / showCollapseButton` | true / true  | 是否允许折叠、是否显示折叠按钮                           |
+| `disabled`                         | false        | 禁止用户拖动、键盘调整及折叠按钮；公开方法仍可供应用控制 |
+
+像素约束随容器 ResizeObserver 和方向变化重新计算；`minSize/maxSize/minFirstSize/minSecondSize/step` 动态修改后立即使用新值。显式折叠可越过展开时的最小尺寸。容器比两个像素下限之和更小时，按两者比例分配可用空间，再遵守百分比范围，避免负尺寸和溢出；这时应用应视实际业务切换单表/Tab 布局，而不是宣称小屏仍可完整容纳任意多表。
+
+已有非受控用法保持兼容。百分比在旧实现中包含整条手柄，现在按剩余空间分配，可消除边缘负尺寸；默认 6px 手柄下，50/50 布局不变，非对称布局只有几个像素的修正。
+
+## 交互与无障碍
+
+手柄采用细轨道与居中胶囊握柄，默认长 80px、厚 16px，保留三点拖动提示。悬停和键盘聚焦时，在握柄两侧显示折叠入口，并以局部描边和轻阴影提示当前状态；折叠后入口持续显示。横向、纵向使用相同视觉规则，主题颜色复用 `--c-primary / --c-bg-card / --c-border / --c-text-3`。
+
+胶囊是独立的实际拖动区域，其视觉厚度不会改变 `gutterSize` 占用的布局空间。触屏下握柄厚度增至 24px、折叠按钮增至 28px，并保持按钮常驻；折叠到边缘时控件向容器内部停靠，避免被裁切。箭头使用本地 SVG，不请求远程图标。
+
+键盘交互与 separator 语义参照 [W3C APG Window Splitter](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)。可用 `aria-label="订单主表"` 设置面板对应的可访问名称。
+
+- 拖动支持鼠标、触控笔和触屏 Pointer Events，不接管宿主的 `document.onmousemove`。
+- 拖动结束、pointercancel、窗口失焦、页面隐藏、动态禁用、方向切换和卸载都会移除监听、恢复此前的光标与文本选择样式。
+- 左右布局使用 Left/Right，上下布局使用 Up/Down；Shift 将 `step` 放大 10 倍，Home/End 到当前可用边界。
+- Enter 折叠首面板，已折叠时还原；双击手柄折叠/展开首面板。按钮有明确的展开状态、目标面板、可见焦点和触屏常驻入口。
+- `role="separator"` 提供 orientation、当前百分比、真实上下限和唯一的受控面板 ID。折叠内容不能通过 Tab 获取焦点。
+
+`resize(first, second)` 表示实际显示比例变化，`update:size(size)` 用于受控状态更新；`drag-start/drag-end` 可记录拖动会话。`collapse/expand` 表示实际折叠状态变化。暴露 `setSize/resetSize/collapse/expand/toggle/getPanelInfo`，应用无需查找或操作内部 DOM。
+
+## 与 wl-ui-produce 的对应关系
+
+本轮只读对比 `wl-ui-produce` 的真实 `jh-drag-row` 调用（3 个 Vue 文件；当前 src 未发现 col 标签）、`@jhlc/common-core` 安装源码/声明以及本地布局规范 14，未修改该项目，也未更换其 BaseTable/AG Grid 或 Element Plus 技术栈。
+
+| 生产项目证据                                                                       | C_SplitPane 对应能力 / 边界                                                                                                                |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| 规范 14 的 `jh-drag-col` 左树右表示例、`leftWidth=240`（当前 src 无真实 col 调用） | 同类左右布局。这里保留百分比初值与双向绑定，新增各面板 px 最小值；**不提供** `leftWidth/rightWidth` 固定像素初值别名                       |
+| `c_steelMasterDetail` 使用 `jh-drag-row`，`top-height=390/470`                     | 同类上下主从布局，`direction="vertical"`；默认比例应按页面高度设计，精确 px 初值可由应用测量后换算，不把 px 值直接传给百分比 `defaultSize` |
+| 本地规范 14：原生 slot、多层嵌套和完整高度链                                       | 直接渲染 slot；组件自身包含 min-height/min-width:0，页面和 Tabs 的外部高度链仍由应用保证                                                   |
+| `c_steelListPanel` 自己观察 panel 并调用 `table.doLayout`                          | 同样保持布局与表格职责分离；原生 C_Table 的 flexHeight 负责表内尺寸适配                                                                    |
+| `c_steelWorkstation` 还有多 Tab 表单、流别/物料表和页面级纵向滚动                  | 这是工作台业务组合；分割面板能提供尺寸布局，不能替代查询/编辑/主从关系/Tab 状态与流程管理                                                  |
+| 规范 FAQ 提及 common-core 可配置像素阈值                                           | 安装包部分源码/声明被裁剪，未据此推断其完整实际 API；本库的像素约束以自身实现和测试为准                                                    |
+
+因此两者的分割手柄属于同一类机制；C_SplitPane 能作为复杂多表布局基础，但不能保证“任意业务场景零配置覆盖”。交叉冻结列、树表权限、主从联动、编辑提交、业务事务和超长工作台仍由各自组件与应用组合完成。

package/docs/guides/table-density.md

@@ -0,0 +1,87 @@
+# 表格密度与模式切换
+
+`C_Form`、`C_FormSearch` 和 `C_Table` 共用 `ComponentDensity`。普通页面只需共享一个状态：
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue'
+  import type { ComponentDensity } from '@robot-admin/naive-ui-components/C_Table'
+  const density = ref<ComponentDensity>('compact')
+</script>
+
+<template>
+  <C_FormSearch
+    v-model="query"
+    :form-item-list="searchFields"
+    :config="{ density }"
+  />
+  <C_Table
+    :data="rows"
+    :columns="columns"
+    :config="{ density, edit: 'cell', selection: true }"
+  />
+</template>
+```
+
+| density       | 原生控件尺寸 | 用途                           |
+| ------------- | ------------ | ------------------------------ |
+| `compact`     | `small`      | 高频操作、多表工作台、紧凑查询 |
+| `default`     | `medium`     | 常规管理页面                   |
+| `comfortable` | `large`      | 信息较少、强调可读性的录入页面 |
+
+密度同步表格行尺寸、编辑器、分页、工具栏按钮、批量按钮、内置编辑弹窗和组件内部留白。
+`display.size`、`pagination.size`、`toolbar.actionBar`、列 `editProps.size` 仍可分别覆盖；原生表格 attrs 保持既有覆盖顺序。
+不传 `density` 保留旧表格尺寸和紧凑工具按钮。密度仅影响当前实例，不修改全局主题和相邻表格。
+
+## 编辑模式使用一个配置项
+
+```ts
+const config = { density: 'compact', edit: 'row', pagination: false } as const
+```
+
+| edit                      | 行为           |
+| ------------------------- | -------------- |
+| `false` / `'none'` / 不传 | 只读           |
+| `true` / `'modal'`        | 弹窗编辑       |
+| `'row'`                   | 整行编辑       |
+| `'cell'`                  | 单元格编辑     |
+| `'both'`                  | 行与单元格编辑 |
+
+需要保存回调、标题或宽度时升级为对象，不增加额外开关：
+
+```ts
+const config = {
+  density: 'compact',
+  edit: { mode: 'row', onSave: saveRow, onError: reportError },
+  selection: true,
+  pagination: { remote: true, total: 100, pageSize: 20 },
+}
+```
+
+运行时修改密度保留草稿；修改编辑模式或关闭编辑会清理旧草稿。正在校验或保存的旧会话不能恢复草稿，旧结果也不会继续发出本地数据补丁。已经交给业务 `onSave` 的请求由业务自行取消或完成，组件不能撤销服务器写入。模式切换本身不会触发业务取消回调或自动保存。
+
+绑定 `crud` 且提供 `crud.save` 时，CRUD 的函数式 `actions.edit` 视为保存能力标记：点击铅笔按配置打开内置编辑器，确认后才通过 `crud.save` 保存一次。自定义打开方式显式放在 `config.actions.edit`；没有独立 `save` 的外部绑定仍保留原有函数行为。
+
+分页、树表、虚拟滚动、选择、导出继续使用各自的分组配置。它们是可组合能力，不设隐含开启多种行为的“万能模式”。
+
+多表分屏请参阅[分割面板](./split-pane.md)；表单优先级与布局示例请参阅[表单密度](./form-density.md)。
+
+## 展开、序号和弹性业务列
+
+默认辅助列宽度：选择列 `40px`、展开列 `40px`、序号列 `50px`。普通未固定的业务列不再被统一填上 `width: 180`；未指定宽度时，它按首选最小宽度吸收容器余量。有辅助列和自然弹性业务列时，默认使用原生 `fixed` 表格布局，避免空余空间把展开与序号撑大：
+
+```ts
+const columns: TableColumn<Order>[] = [
+  { type: 'selection' },
+  { type: 'expand' },
+  { type: 'index' },
+  { key: 'name', title: '订单名称', minWidth: 220 }, // 自然弹性列
+  { key: 'amount', title: '金额', width: 140 },
+]
+```
+
+不需要给每张表写辅助列 CSS。显式列 `width / minWidth / maxWidth / fixed / className / cellProps` 保持转发；`config.display.columnWidth`（包括全局配置中的显式 `180`）仍表示统一列宽。固定业务列继续使用可计算的数值默认宽度；原生 `table-layout` 属性可覆盖自动选择的布局。
+
+若所有业务列都显式指定宽度，且总宽小于容器，保留原生表格的剩余空间分配规则；这时声明的 `width` 不保证等于最后测量的像素。通常让名称或描述列保持弹性，比给所有列设宽更合适。虚拟横向滚动仍需按 Naive UI 的契约提供具体列宽。
+
+独立的列 `renderExpand` 直接转交原生表格；配置 `config.expand.onLoadData / renderContent` 后由组件的加载、失败重试和内容渲染器接管展开区。不要同时配置两套展开内容并依赖原生渲染器优先。自动横向滚动宽度按最终可见列计算，包含辅助列、动态选择列和操作列，不再额外追加固定留白。

package/docs/guides/transfer.md

@@ -0,0 +1,11 @@
+# 穿梭框与大列表
+
+```vue
+<C_Transfer v-model="selectedKeys" :data="people" filterable />
+```
+
+左右面板分别按搜索后的项数决定渲染方式：少于 100 项使用普通列表，100 项起复用 Naive UI 同样使用的官方 `vueuc/VVirtualList`，只挂载当前视口及相邻行。全选、禁用判断和移动顺序仍以完整列表为准；滚动到视口之外的选中项不会丢失。右侧保持 `modelValue` 的顺序，新增项按左侧数据顺序追加。
+
+`size="small | medium | large"` 对应 28 / 34 / 40px 固定行高。继续通过既有 `--tf-height` 覆盖列表高度，例如 `style="--tf-height: 240px"`；无需为大列表额外设置高度或分页。
+
+若项目自行改变行高、需要打印全部项，或依赖完整列表 DOM，可显式设置 `:virtual-scroll="false"` 保留普通渲染。默认开启自动判断，常规接入无需配置。搜索仍检查全部数据；虚拟列表减少 DOM 与组件挂载量，不把筛选或数据存储变成无限容量服务。