@done-coding/admin-core 0.18.0 → 0.19.0

package/src/components/display/docs/README-WatchSize.md

@@ -0,0 +1,70 @@
+# WatchSize（尺寸观测组件）
+
+> 通用尺寸观测：包一层即得自身 clientHeight / clientWidth 变化（激活首测 + window resize + onUpdated + 可选 ResizeObserver），按 mode 派发 heightChange / widthChange。
+> 范式页：无独立范式页——组件级测量工具，被容器组件内嵌消费（核心实证：`packages/core/src/components/display/__tests__/`）
+
+## 定位
+
+- **何时用**：需要拿到「自身盒子」尺寸变化的容器组件内部 / 消费方包装层
+- **何时不用**：需要「视口高 − 页头高 → 内容可用高」计算的场景用 `HeightProvider`（本组件只报自身测量值，不算账）
+- 测量时机：激活首测 + window resize + onUpdated（激活态）+（可选）RO；失活 cancel 在途防抖、卸载 flush 补发终值
+
+## 快速上手（最小可用）
+
+```html
+<WatchSize mode="height" @height-change="onHeightChange">
+  <div>...</div>
+</WatchSize>
+```
+
+**要点**：
+
+- `observeResize` 默认关；需要测「不触发自身重渲染的尺寸变化」（CSS 过渡折叠 / 异步撑开）时开启 RO
+- `debounceTime` 只吃初始值，后续变化不更新
+- 失活 cancel 在途防抖、卸载 flush 补发终值——终值不丢
+
+## 能力边界 / 按需使用
+
+- **`observeResize`（ResizeObserver）：默认关。** 默认测量链（激活首测 + window resize + onUpdated）已覆盖「渲染驱动的尺寸变化」（v-if/v-show / 样式响应式）——普通场景即够用；仅当测「不触发自身重渲染的尺寸变化」（CSS 过渡折叠 / 异步撑开）才开——判据：尺寸变化过程中组件自身不重渲染、onUpdated 读不到最终值。
+- **`debounceTime`：默认 `16`ms 即够用。** 仅当变化频率极高（连续 resize / 连续折叠）需聚合事件流时才调大；⚠️ 只吃初始值，后续变化不更新。
+- **`mode`：默认 `"height"`。** 仅需横向尺寸（侧栏宽 / 横向布局）才设 `"width"` / `"both"`。
+- **优先复用容器内嵌，[MUST NOT] 重复造轮**：ListPage（header / 操作槽量高）、HeightProvider（#header 量高得 reserve）等已内嵌消费本组件；仅自定义容器需要自身盒尺寸时才直用。
+- **完整能力演示**：无独立范式页（组件级测量工具）——核心实证 `packages/core/src/components/display/__tests__/`。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `mode` | `"height" \| "width" \| "both"?` | `"height"` | 观测维度，按 mode 派发 heightChange / widthChange |
+| `observeResize` | `boolean?` | `false` | 是否 ResizeObserver 观测自身盒，可测「不触发自身重渲染的尺寸变化」（CSS 过渡折叠/异步撑开） |
+| `debounceTime` | `number?` | `16` | 防抖毫秒；⚠️ 只吃初始值，后续变化不更新 |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `heightChange` | `value: number` | 高度变化（clientHeight，按 mode 派发） |
+| `widthChange` | `value: number` | 宽度变化（clientWidth，按 mode 派发） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 被观测内容 |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **过渡动画尺寸变化未开 observeResize**：onUpdated 读起点漏最终值（CSS transition 期间）——动画折叠场景 [MUST] 开 RO
+- **动态改 debounceTime**：只吃初始值，后续变化不更新（无效）
+
+## 关联
+
+- 下游消费：`HeightProvider`（#header 槽经 WatchSize 测高得 reserve）
+- 核心实证：`packages/core/src/components/display/__tests__/`

package/src/components/form/README.md

@@ -0,0 +1,24 @@
+# form 表单族
+
+配置式表单核心（11 组件，最大族）：`list` 配置驱动渲染 / 校验 / 序列化，`data` 同引用绑定，generate / parse / stringify 三方法 round-trip。
+
+## 组件文档（docs/）
+
+- [FormMain](./docs/README-FormMain.md) — 配置式表单核心容器
+- [FormSearch](./docs/README-FormSearch.md) — 搜索表单（折叠 / 操作区 / staticQuery）
+- [FormSubmitPanel](./docs/README-FormSubmitPanel.md) — 纯表单空间一等公民（提交 / 取消 / 重置操作区）
+- [FormSubmitBtn](./docs/README-FormSubmitBtn.md) — 提交按钮（validate → stringify → submitFn 管线）
+- [FormItemNestForm](./docs/README-FormItemNestForm.md) — 嵌套子表单（C1，级联校验）
+- [FormItemNestFormList](./docs/README-FormItemNestFormList.md) — 数组子表单（C4，行增删 + min/max）
+- FormSelect / FormRadioGroup / FormTree / FormVerifyImage / FormVerifyCode — 文档待补
+
+## 关键类型与 helper
+
+- 类型：`FormItemConfig` / `FormItemConfigList` / `FormMainInstance` / `FormSearchInstance` / `FormScope`（全部经 `./types` 导出）
+- helper：`nestFormItem`（C1）/ `nestFormItemList`（C4）/ `useNestForm` / `useNestFormList` / `useNestLayoutScale`
+- 工具：`generateFormData` / `parseFormData` / `stringifyFormData` / `swiftFormItemConfig`
+- 内部不导出：`FormItem`（仅 FormMain 内部）、`use-form-submit`、`use-layout-by-container`
+
+## 范式页（apps/reference）
+
+- `/form/guide`（FormMain 最佳实践）/ `/form/container-breakpoint`（容器断点）/ `/form/submit-btn/showcase`、`/form/submit-panel/showcase`、`/form/nest-form/showcase`、`/form/nest-form-list/showcase`、`/form/nest-form-submit-panel/showcase`

package/src/components/form/docs/README-FormItemNestForm.md

@@ -0,0 +1,86 @@
+# FormItemNestForm（嵌套子表单 C1）
+
+> 单层嵌套子表单：父 item 内嵌一个子 FormMain（modelValue 同引用绑定父 `data[key]`），级联校验 / 重置经父 FormMain 注册表自动贯通。
+> 范式页：`apps/reference/src/pages/form/nest-form/showcase/`（C1 单独场景）、`pages/form/nest-form-list/showcase/`（C4 行内套 C1）
+
+## 定位
+
+- **何时用**：一个字段下挂一组子字段（如「扩展信息」内含多字段），或 C4 行列表内每行再嵌套子表单
+- **何时不用**：同层平铺字段直接用 FormMain.list；多行同构子表用 `FormItemNestFormList`（C4）
+- 内部机制：子 FormMain 的 expose 经 `useNestForm` 注册进父 `FORM_NEST_REGISTRY_KEY`（`nestKey` 作索引）——父 `validate()` / `resetFields()` / `clearValidate(key?)` 自动级联到子表
+- 组件自身无 emits / slots / expose；推荐经 `nestFormItem` helper 织入配置，而非手写组件用法
+
+## 快速上手（最小可用）
+
+配置面走 helper（`nestFormItem` 是推荐姿势，织入普通 FormMain.list）：
+
+```ts
+import { FormMain, swiftFormItemConfig, nestFormItem, generateFormData } from "@done-coding/admin-core";
+const list: FormItemConfigList = [
+  swiftFormItemConfig({ key: "name", label: "姓名", type: "input", required: true, render: ElInput }),
+  nestFormItem({ key: "extra", label: "扩展信息", list: extraList }),  // 子表单零配置织入
+];
+const data = ref(generateFormData(list));
+```
+
+```html
+<FormMain :list="list" :data="data" />
+```
+
+**要点**：
+
+- `nestFormItem` 自动织入 `render`（markRaw 组件引用）+ `init`（缺省 `generateFormData(list)`）+ `stringify` / `parse`（缺省递归子 list）+ `parentSpan`——配置面只写 `{ key, label, list }` 即完成
+- v-model 语义：modelValue 是父 `data[key]` 对象，同引用 in-place——按此语义改属性，父 data 即子表数据
+- 级联校验零接线：父 FormMain `validate()` 穿透到子表单（nestKey 注册进 exposeMap）
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`nestFormItem({ key, label, list })` 即完成嵌套**（render / init / stringify / parse / parentSpan 自动织入，级联校验零接线）。以下全部按需开：
+- `layout` / `rowGutter`：默认未设 = 吃父级布局；仅当子表单需要独立布局才设。
+- `rebase`：默认 `true` 叠本层嵌套布局 rebase（配合 `parentSpan` 算因子）；仅当不需要层级缩放（layout 原样直透）才设 `false`。
+- `shadowColor`：默认吃 CSS 变量自适配（随主题 / 亮暗切换）；显式传仅当确需跨主题固定色。
+- 多行同构子表（一对多）→ 不走本组件，用 `FormItemNestFormList`（C4）。
+- **完整能力演示**（C1 单独场景 / C4 行内套 C1）：`apps/reference/src/pages/form/nest-form/showcase/`、`pages/form/nest-form-list/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `nestKey` | `string`（必填） | — | 所属父 item key（注册进父 FormMain exposeMap 的索引，供级联 validate / clear / reset） |
+| `list` | `FormItemConfigList`（必填） | — | 子表单配置 |
+| `layout` | `Partial<ColProps>` | 未设 | 子 FormMain 布局 |
+| `rowGutter` | `number` | 未设 | 子行间距 |
+| `shadowColor` | `string` | CSS 变量自适配 | 外环阴影色（显式传才内联覆盖） |
+| `parentSpan` | `number` | 未设 | 父 item 代表 span（P3 rebase 算因子） |
+| `rebase` | `boolean` | `true` | 是否叠本层嵌套布局 rebase（`false`=layout 原样直透） |
+
+### v-model
+
+`modelValue: Record<string, any>`（defineModel，默认 `() => ({})`）——等于父 `data[key]` 对象，同引用 in-place。
+
+### Emits / Slots / Expose
+
+无（子 FormMain expose 经 `useNestForm` 注册到父 registry）。
+
+### 配套 helper：`nestFormItem(options: NestFormItemOptions): FormItemConfig`
+
+自动织入：`render`（markRaw 组件引用）、`init`（缺省 `generateFormData(list)`）、`stringify` / `parse`（缺省递归子 list）、`parentSpan`。
+
+`NestFormItemOptions` 含：`key` / `label` / `list` / `layout` / `rowGutter` / `shadowColor` / `init` / `stringify` / `parse` / `rebase`。
+
+## 反模式 / 注意
+
+- **手写嵌套子表单配置**：直接手写 render 挂子 FormMain 会绕过注册机制，级联校验断裂——[MUST] 用 `nestFormItem` / 本组件
+- **nestKey 与父 key 不一致**：nestKey 是父 item key，注册索引对不上则级联失效
+- **shadowColor 显式传才内联覆盖**：默认吃 CSS 变量自适配（随主题 / 亮暗切换）；除非确需跨主题固定色，让默认值跟随主题系
+- **rebase 语义**：默认 `true` 叠本层嵌套布局 rebase（配合 `parentSpan` 算因子）；`false` 时 layout 原样直透
+
+## 关联
+
+- 表单族：`FormItemNestFormList`（C4 多行同构）、`FormMain`（底座与注册容器）、`FormSearch` / `FormSubmitPanel`（上层形态）
+- helpers：`nestFormItem`（C1 配置生成）、`useNestForm`（expose 注册）、`useNestLayoutScale`（布局 rebase）
+- 内部 provide：`FORM_NEST_REGISTRY_KEY`（FormMain）、`NEST_LAYOUT_SCALE_KEY`（FormMain）
+- 范式页：`apps/reference/src/pages/form/nest-form/showcase/`、`pages/form/nest-form-list/showcase/`

package/src/components/form/docs/README-FormItemNestFormList.md

@@ -0,0 +1,93 @@
+# FormItemNestFormList（嵌套行列表 C4）
+
+> 多行同构子表单列表：一行一个子 FormMain（v-model 数组真源），min / max 行数约束 + 新增 / 删除（可二次确认）+ render-fn 头部 / 底部自定义。
+> 范式页：`apps/reference/src/pages/form/nest-form-list/showcase/`
+
+## 定位
+
+- **何时用**：一对多子表（联系人列表、地址列表…），行内字段同构，可增删
+- **何时不用**：单层嵌套用 `FormItemNestForm`（C1）；行内字段需再异构嵌套时 C4 行内再套 C1
+- 内部机制：`useNestFormList` 注册 **1 个聚合 expose**（fan-out 遍历各行）进父 `FORM_NEST_REGISTRY_KEY`——父 `validate()` 级联校验每一行
+- 组件自身无 emits / slots / expose；推荐经 `nestFormItemList` helper 织入配置
+
+## 快速上手（最小可用）
+
+配置面走 helper（单层 C4 即完整；`nestFormItemList` 织入普通 FormMain.list）：
+
+```ts
+import { FormMain, swiftFormItemConfig, nestFormItemList, generateFormData } from "@done-coding/admin-core";
+const list: FormItemConfigList = [
+  swiftFormItemConfig({ key: "name", label: "姓名", type: "input", required: true, render: ElInput }),
+  nestFormItemList({ key: "addresses", label: "地址列表", list: addressList, min: 1, max: 2 }),
+];
+const data = ref(generateFormData(list));
+```
+
+```html
+<FormMain :list="list" :data="data" />
+```
+
+**要点**：
+
+- v-model 是**数组真源**：push / splice 原地改即增删行；行数约束叠加在增删动作上——删到 `min` 禁删、达 `max` 禁新增
+- `nestFormItemList` 自动织入 render / init / stringify / parse + `rules`（min / max 长度规则与自动织入合并）——`generateFormData(list)` 即按配置产出完整嵌套结构
+- 两层防线各管一段：min / max 硬约束（禁删 / 禁新增）在交互层，长度硬校验走父 item `rules`（不补数据）
+- `removeConfirm` 默认开：行删除二次确认（`true`=默认 popconfirm「确认删除该项？」；`false`=直删；对象=自定义）
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`nestFormItemList({ key, label, list })` 即完成增删行列表**（min/max 不约束、删除带默认确认）。以下全部按需开：
+- `min` / `max`：默认 `0` / `Infinity` 即够用（不约束）；仅当业务要求行数上下限才设——[MUST] 同时配 `rules`（长度硬校验走父 item `rules`，min / max 只是交互层禁删 / 禁增）。
+- `removeConfirm`：默认开（删除需确认）；仅当删除属低风险 / 高频操作（或外层已有更强确认层）才设 `false` 直删；对象 = 自定义文案。
+- `itemFactory`：默认 `generateFormData(list)` 即够用；仅当新增行需要特殊初始值才设。
+- `rowKey`：默认内部 WeakMap 自增 rowId 即够用（组件生命周期内行身份稳定）；仅当行身份需跨会话稳定（对应后端 id）才显式传字段名。
+- `headerRender` / `footerRender`：默认不设（内置新增按钮）；仅当列表头尾需要自定义内容（计数 / 汇总 / 定制按钮）才用 render-fn（非 slot）。
+- 行内再嵌套（C4 套 C4 / 行内套 C1）：按需，行 `list` 内再织 `nestFormItem` / `nestFormItemList`。
+- **完整能力演示**（C4 套 C4 / C1 三层嵌套 + hide 联动）：`apps/reference/src/pages/form/nest-form-list/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `nestKey` | `string`（必填） | — | 父 item key（聚合 expose 注册索引） |
+| `list` | `FormItemConfigList`（必填） | — | 每行子表单配置 |
+| `rowKey` | `string` | 未设 | 行稳定 id 字段（缺省内部 WeakMap 自增 rowId） |
+| `itemFactory` | `() => T` | `generateFormData(list)` | 新增行工厂 |
+| `min` | `number` | `0` | 最少行（删到 min 禁删；硬约束走父 item rules 长度校验，不补数据） |
+| `max` | `number` | `Infinity` | 最多行（达上限禁新增） |
+| `layout` / `rowGutter` | — | — | 每行子 FormMain 布局 / 行距 |
+| `addText` / `removeText` | `string` | `"新增"` / `"删除"` | 按钮文案 |
+| `headerRender` | `({ count, max }) => VNodeChild` | 未设 | 顶部自定义渲染（render-fn，非 slot） |
+| `footerRender` | `({ count, max, canAdd, add }) => VNodeChild` | 未设 | 底部自定义渲染（缺省=内置新增按钮） |
+| `shadowColor` | `string` | CSS 变量 | 外环 + 每行分割阴影色 |
+| `parentSpan` / `rebase` | — | rebase `true` | 同 C1（父 item 代表 span / 是否叠嵌套 rebase） |
+| `removeConfirm` | `boolean \| ActionBtnConfirmConfig` | `true` | 行删除二次确认（`true`=默认 popconfirm「确认删除该项？」；`false`=直删；对象=自定义） |
+
+### v-model
+
+`modelValue: T[]`（defineModel，默认 `() => []`）——数组真源，push / splice 原地改。
+
+### Emits / Slots / Expose
+
+无（`useNestFormList` 注册 1 个聚合 expose，fan-out 遍历各行）。
+
+### 配套 helper：`nestFormItemList(options: NestFormItemListOptions)`
+
+自动织入 render / init / stringify / parse + `parentSpan`；options 另含 `rules`（与自动织入的 min / max 长度规则合并）。
+
+## 反模式 / 注意
+
+- **手写行子表单配置**：绕过注册机制则多行级联校验断裂——[MUST] 用 `nestFormItemList` / 本组件
+- **只靠 min / max 交互约束**：禁删 / 禁新增是交互层防线，长度硬校验走父 item `rules`——需要提交时兜底校验（如绕过 UI 直接改数据）必须配 `rules`
+- **headerRender / footerRender 是 render-fn 不是 slot**：在配置内以函数形式提供，不能当插槽模板使用
+- **rowKey 稳定性**：缺省走内部 WeakMap 自增 rowId（组件生命周期内行身份稳定）；行身份需跨会话稳定（如对应后端 id）时显式传 `rowKey` 字段名
+
+## 关联
+
+- 表单族：`FormItemNestForm`（C1 单层嵌套）、`FormMain`（底座与注册容器）、`FormSubmitPanel`（提交面）
+- helpers：`nestFormItemList`（C4 配置生成）、`useNestFormList`（聚合 expose 注册）、`nestFormItem`（C1）、`useNestLayoutScale`（布局 rebase）
+- 内部 provide：`FORM_NEST_REGISTRY_KEY`（FormMain）、`NEST_LAYOUT_SCALE_KEY`（FormMain）
+- 范式页：`apps/reference/src/pages/form/nest-form-list/showcase/`

package/src/components/form/docs/README-FormMain.md

@@ -0,0 +1,101 @@
+# FormMain（配置化表单主体）
+
+> 配置化表单核心容器：`list` 配置驱动渲染 / 校验 / 序列化，`data` 同引用绑定，generate / parse / stringify 三方法做数据 round-trip。
+> 范式页：`apps/reference/src/pages/form/guide/`（最佳实践）
+
+## 定位
+
+- **何时用**：任何配置化表单页的主体——搜索类前缀走 FormSearch、提交类面板走 FormSubmitPanel，本组件是两者与嵌套子表单（FormItemNestForm / FormItemNestFormList）的底座
+- **何时不用**：搜索表单用 `FormSearch`（自带折叠 + 操作区）；带提交/取消操作区的用 `FormSubmitPanel`；嵌套子表用 C1 / C4 组件族
+- 内部组合：单项渲染由 `FormItem` 完成（未导出，仅 FormMain 内部）；内部 provide `FORM_NEST_REGISTRY_KEY`（嵌套子表单 expose 注册，级联 validate/clear/reset）与 `NEST_LAYOUT_SCALE_KEY`（嵌套布局 rebase）
+- 根节点为 ElForm，`inheritAttrs: true`（class / attrs 自然落 ElForm 根）
+
+## 快速上手（最小可用）
+
+最小表单 + 校验提交（默认值即够用）：
+
+```html
+<FormMain ref="formMain" :list="list" :data="data" />
+```
+
+```ts
+const formMain = ref<FormMainInstance>();
+const data = ref(generateFormData(list));
+const submit = async () => {
+  await formMain.value?.validate();                  // 校验不通过即 reject，闸住提交
+  const payload = stringifyFormData(data.value, list);  // 序列化为提交形态
+  await saveApi(payload);
+};
+```
+
+**要点**：
+
+- `list` 配置驱动渲染 / 校验 / 序列化；`data` 是 v-model 语义、**同引用绑定**——改 data 对象属性即改表单值
+- 提交 = `validate()` 通过 → `stringifyFormData` 序列化 → 发 API；搜索（FormSearch）/ 提交面板（FormSubmitPanel）已内置此管线，裸用本组件只需两条裸函数 + 一行 validate
+- 单项渲染可被具名槽 `#<config.key>` 覆盖；默认 slot 可整体接管栅格
+
+## 能力边界 / 按需使用
+
+- **三方法 round-trip（generate / parse / stringify）：最小形态只用两条裸函数路——`generateFormData` 建初值 + `stringifyFormData` 序列化提交，即够用。** 仅当页面有「新增 / 编辑」双模式（编辑回填走 `parseFormData` + 留存分支编排）才需要三方法完整编排。
+- `layout` / `rowGutter`：默认即够用（rowGutter=8，单项自带 layout）；仅当需要整体栅格统一（如多列 span）才设 `layout`——单项 `layout` 优先。
+- 具名槽 `#<config.key>`：默认关（单项由配置 render / props 驱动）；仅当单一项需要完全自定义渲染（复杂组合控件）才开。
+- `#default` 整体接管栅格：默认关、少用；仅当整个栅格结构需重构时开。
+- `layoutByContainer`：默认关（按 window 媒体查询）；仅当表单落入窄容器（侧栏 / 抽屉内嵌）且视口响应式挤崩时才开。
+- **完整能力演示**（新增 / 编辑双模式三方法编排 + 校验提交）：`apps/reference/src/pages/form/guide/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `PO` 解析模型 / `SO` 格式化模型，`FormMainProps<PO, SO>`）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `list` | `FormItemConfigList<PO, SO>`（必填） | — | 表单项配置数组（驱动渲染/校验/序列化） |
+| `data` | `PO`（必填） | — | 表单数据模型（v-model 语义，直接同引用绑定——改 data 对象属性即改表单值） |
+| `layout` | `Partial<ColProps>` | 未设（不传则单项各自 layout） | 表单整体栅格布局，单项 layout 优先 |
+| `rowGutter` | `number` | `8` | ElRow 横向列间距 |
+| `layoutScale` | `number` | `1` | P3 嵌套 rebase 累乘因子（缺省 1=顶级行为不变，由联结薄壳算后传入） |
+| `layoutByContainer` | `boolean` | `false` | 按容器断点校准响应式 span（默认按 window 媒体查询） |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `loadingChange` | `boolean` | 表单项变更 loading 状态变化（如上传在途） |
+| `visibleChange` | `boolean` | 显隐（hide 驱动）变化 |
+| `submit` | `FormItemSubmitType` | 表单项触发提交（`"blur"` / `"change"` / `"enter"`） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#<config.key>` | FormItem 内部 mainProps（`modelValue` / `onUpdate:modelValue` / `placeholder` / 事件） | 覆盖单项渲染 |
+| `#default` | `{ mergeLayout }` | 整体接管栅格（少用） |
+
+### Expose（`FormMainInstance<PO, SO>`）
+
+`validate(): Promise<void>`（本层 + 隐藏项过滤 + 嵌套子表单级联）、`resetFields()`、`clearValidate(key?)`、`generate(): PO`、`parse(stringifyData): PO`、`stringify()`（序列化对象）——三方法 round-trip。
+
+### 关键类型
+
+- `FormItemConfig<PO, SO, PK, PV, SV>`：单表单项配置——`key` / `label` / `labelHide` / `tip` / `layout` / `wrapProps` / `props` / `render` / `rules` / `init` / `parse` / `stringify` / `ignore` / `hide` / `beLink` / `extra`
+- `FormItemConfigList<PO, SO>`：表单项配置数组（`FormMain.list` 的类型）
+- `FormItemConfigExtra`：`extra` 快捷项——`isInput` / `isSelect`（OnlyOneKey 互斥）+ `enterSubmit` / `blurSubmit` / `changeSubmit`
+- `FormItemLinkConfig<K, BV, OV>`：`beLink` 联动配置——`key` + `getValue(hostValue, ownValue, attachInfo)`
+- `FormScope<PO, SO, ...>`：渲染 / 函数式配置的作用域——`{ data, config }`
+- `ExtractFormStringifyFromObject` / `FromList`：从 `PO`+`SO` 提取序列化提交形态（类型级提取，剔除 symbol / never 键）
+
+## 反模式 / 注意
+
+- **手写嵌套子表单 render**：嵌套子表单（C1 / C4）与 `nestFormItem` / `nestFormItemList` helper 是既定通道，`FormItem` 未导出（仅 FormMain 内部）——[MUST NOT] 手写内联子表单 render 绕开注册机制（会失去级联 validate / clear / reset）
+- **变更 loading 中提交**：表单项处于变更 loading（`FORM_ITEM_CHANGE_LOADING` Symbol 标记，如上传在途）时，`validate()` 直接 reject——提交被闸住，[MUST NOT] 绕过 validate 直发提交
+- **`layout` 与单项 `layout` 关系**：整体 layout 是兜底，单项 `layout` 优先（单项未设才吃整体）
+- **三方法成对使用**：初值 / 回填 / 提交永远走 `generateFormData` / `parseFormData` / `stringifyFormData`（或 expose 三方法），避免手工拼对象破坏 round-trip
+
+## 关联
+
+- 表单族：`FormSearch`（搜索前缀，折叠 + 操作区）、`FormSubmitPanel`（提交面板）、`FormSubmitBtn`（提交按钮）、`FormItemNestForm`（C1 嵌套子表单）、`FormItemNestFormList`（C4 行列表）、`FormSelect` / `FormRadioGroup` / `FormTree` / `FormVerifyImage` / `FormVerifyCode`（单项形态）
+- utils 公共函数：`generateFormData` / `parseFormData` / `stringifyFormData`、`getVModelSugar`、`getPlaceholder`、`getEnterSubmit` / `getBlurSubmit` / `getChangeSubmit`、`getDatePickerShortcuts`、`swiftFormItemConfig`、`resolveFormLayout`、`resolveLayoutSpan`、`ceilToTier`、`NEST_LAYOUT_TIERS`、`setInputComponent` / `setSelectComponent`、`FORM_ITEM_CHANGE_LOADING`（Symbol）
+- helpers：`nestFormItem`（C1 配置生成）、`nestFormItemList`（C4）、`createNestFormExposeMap`、`useNestForm`、`useNestFormList`、`useNestLayoutScale`
+- 内部 provide：`FORM_NEST_REGISTRY_KEY`（嵌套 expose 注册）、`NEST_LAYOUT_SCALE_KEY`（布局 rebase）
+- 范式页：`apps/reference/src/pages/form/guide/`、`pages/form/nest-form/`（C1）、`pages/form/nest-form-list/`（C4）

package/src/components/form/docs/README-FormSearch.md

@@ -0,0 +1,89 @@
+# FormSearch（搜索表单）
+
+> FormMain 的搜索前缀：自带折叠（maxRows 按真实几何换行）+ 内置操作区（展开更多 / 重置 / 查询），search emit 自动并入静态参数。
+> 范式页：`apps/reference/src/pages/menu/showcase/`（独立裸用）；ListPage 内嵌场景见 `apps/reference/src/pages/list-page/guide/`
+
+## 定位
+
+- **空间一等公民是 `ListPage` 的搜索侧**：常规列表页 [MUST] 走 `ListPage`（内部即「FormSearch + TableMain」组合，搜索侧 props 双子扁平化、`staticQuery` 提升为直属 prop）——**FormSearch 一般不直接使用**
+- **独立裸用仅当**：纯搜索区页面/组件（无表格，配合外部触发查询）
+- **何时不用**：普通录入表单用 `FormMain`；带提交 / 取消操作区的用 `FormSubmitPanel`
+- 与 FormMain 的差异：`rowGutter` 默认 14（FormMain 为 8）、`layout` 默认 `{xs:24, sm:12, md:12, lg:8, xl:6}`、`maxRows` 折叠、内置操作区按钮、`staticQuery` 并入 emit、expose 增 trigger 与折叠控制
+- 根节点为 WatchSize 包裹的 `.form-search`，`inheritAttrs: false`（attrs 显式转发内层 FormMain）
+
+## 快速上手（最小可用）
+
+最小搜索表单（list / data / @search 即完整）：
+
+```html
+<FormSearch :list="list" :data="data" @search="(q: any) => (query = q)" />
+```
+
+**要点**：
+
+- `@search` 载荷 = 表单序列化结果 `ExtractFormStringifyFromObject<PO, SO>` **并上 `staticQuery`**——静态参数天然并入，无需手工拼接
+- 折叠（`maxRows` 默认 2 收起）+ 展开更多 / 重置 / 查询操作区内置默认即生效，零配置
+- 单项覆盖走具名槽 `#<config.key>`，scope 是 FormItem 内部 mainProps——`v-bind="scope"` 直透给组件即可
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`list` + `data` + `@search` 即为完整搜索形态**（折叠 + 操作区内置）。以下全部按需开：
+- `staticQuery`：默认未设即够用；仅当有非表单静态参数（如固定状态筛选）需并入搜索载荷才设。
+- `maxRows`：默认 `2`（收起折叠）即够用；`0`=不折叠全展开，仅当搜索项少 / 页面想全显才设。
+- 具名槽 `#<config.key>`：默认关（单项由配置驱动）；仅当单项需要完全自定义渲染（复杂组合控件）才开。
+- `compact`：默认关；仅当搜索区落入受限窄栏（独立侧栏搜索）才开——窄栏场景优先容器断点系（`compact` / `layoutByContainer`），而非给单项 layout 写死 span。
+- `layoutByContainer`：默认关；仅当容器断点折叠几何需要切到容器档才开。
+- expose `triggerSearch()` / `triggerReset()` / `toggleCollapse()`：默认不需要（操作区按钮内置）；仅当外部需程序化触发（如 ListPage 列插槽注入）才用。
+- **完整能力演示**（staticQuery + 多 slot 覆盖 + 折叠回调）：`apps/reference/src/pages/menu/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `PO` 解析 / `SO` 格式化 / `SQ` 静态参数，`FormSearchProps<PO, SO, SQ>` = FormMainProps + 以下）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `list` | `FormItemConfigList<PO, SO>`（必填） | — | 同 FormMain，透传 |
+| `data` | `PO`（必填） | — | 同 FormMain，透传 |
+| `layout` | `Partial<ColProps>` | `{xs: 24, sm: 12, md: 12, lg: 8, xl: 6}` | 同 FormMain，默认值不同（搜索三列感） |
+| `rowGutter` | `number` | `14` | 同 FormMain，默认值不同（FormMain 为 8） |
+| `layoutScale` | `number` | `1` | 已声明 prop 不入 attrs 且未显式转发——**实际不传递**（内层 FormMain 恒吃默认 1），消费方传了无效 |
+| `layoutByContainer` | `boolean` | `false` | 开启时折叠几何引擎断点源一并切到容器档 |
+| `labelPosition` | `"right" \| "left" \| "top"` | `"right"` | 标签位置 |
+| `labelWidth` | `string` | `"auto"` | 标签宽度 |
+| `staticQuery` | `SQ` | 未设 | 静态参数（非表单非分页），并入搜索 emit 结果 |
+| `maxRows` | `number` | `2` | 收起态最多渲染视觉行数（含操作区行），0=不折叠全展开；按真实几何换行计算 |
+| `compact` | `boolean` | `false` | 受限窄栏模式：统一单列 span24 + label 置顶，maxRows 仍外部可控 |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `search` | `data: ExtractFormStringifyFromObject<PO, SO> & SQ`；`type: FormSearchSearchType` | 查询 / 重置 / 单项提交触发（`"search"` / `"reset"` / `"blur"` / `"change"` / `"enter"`） |
+| `heightChange` | `number` | 折叠 / 展开容器高度变化 |
+| `visibleChange` | `boolean` | 显隐变化 |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#<config.key>` | FormItem 内部 mainProps | 覆盖搜索单项（透传 FormMain） |
+| `#default` | — | ⚠️ 被内置操作区按钮（展开更多 / 重置 / 查询）占用，消费方默认插槽不会被转发 |
+
+### Expose（`FormSearchInstance<PO, SO>`，extends `Omit<FormMainInstance, "generate" \| "parse" \| "stringify">`）
+
+继承：`validate()` / `resetFields()` / `clearValidate(key?)`（无三方法——搜索无 round-trip 需求）；新增：`triggerSearch()` / `triggerReset()` / `toggleCollapse(nextValue?)` / `isCollapsed: ComputedRef<boolean>`。
+
+## 反模式 / 注意
+
+- **用 `#default` 插自定义按钮**：默认槽被内置操作区占用，不会渲染——自定义操作走 expose 的 trigger 方法，或交给 ListPage / 外层编排
+- **`@search` 后手工再并 staticQuery**：载荷已含静态参数，再拼一次会重复
+- **class 定向落点**：`inheritAttrs: false` + attrs 显式转发内层 FormMain——消费方 class 落在内层 ElForm，而非 `.form-search` 根（WatchSize 包裹）；定向样式按实际落点写选择器
+- **窄栏场景改 layout 硬撑**：`compact`（或 `layoutByContainer`）走容器断点几何，与 ElCol 的视口响应式不同源——窄栏挤崩场景优先容器断点系，而非给单项 layout 写死 span
+
+## 关联
+
+- 表单族：`FormMain`（底座，本组件为其搜索前缀）、`FormSubmitPanel` / `FormSubmitBtn`（提交面）、`FormItemNestForm` / `FormItemNestFormList`（嵌套）
+- 组合页：`ListPage`（内部即「FormSearch + TableMain」，搜索侧 props 双子扁平化；`staticQuery` 被扁平提升为直属 prop，禁放 formSearchProps 内）
+- 类型：`FormSearchSearchType` = `"search" \| "reset" \| FormItemSubmitType`；`FormSearchInstance<PO, SO>`
+- 范式页：`apps/reference/src/pages/menu/showcase/`、`pages/list-page/guide/`

package/src/components/form/docs/README-FormSubmitBtn.md

@@ -0,0 +1,72 @@
+# FormSubmitBtn（提交按钮）
+
+> 挂 FormMain 实例的提交按钮：内置「validate → stringify → submitFn → 按钮 loading」管线。
+> 范式页：`apps/reference/src/pages/form/submit-btn/showcase/`；FormSubmitPanel 内置场景见 `apps/reference/src/pages/form/submit-panel/showcase/`
+
+## 定位
+
+- **何时用**：已有 FormMain 实例，需要一个提交按钮且不想自管「校验 → 序列化 → 提交 → loading」管线
+- **何时不用**：提交 + 取消 / 重置 + 面板壳用 `FormSubmitPanel`（内部即内置本组件，经 `submitBtnProps` 定制）；无表单实例的普通按钮用 `ActionBtn`
+- 提交 loading 由管线内置管理（`loading` 已从透传面 Omit）
+
+## 快速上手（最小可用）
+
+最小骨架（仅用必填 / 默认项，管线内部完成）：
+
+```html
+<FormSubmitBtn
+  :formMainInstance="formMain"
+  :submitFn="submitFn"
+  submitText="保存"
+  @success="onSuccess" @fail="onFail" />
+```
+
+**要点**：
+
+- `formMainInstance` 传入 FormMain 的 ref 实例——管线在内部调 `validate()` / `stringify()`，消费方零接线
+- `submitFn` 收 `stringifyData` 返回 Promise：resolve → `@success(stringifyData)`；reject → `@fail(error)`；在途按钮自动 loading
+- `onSubmitStart()` 可在提交发起时同步回调（如弹层整体 loading 态）
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`formMainInstance` + `submitFn` 即为完整提交按钮**（validate → stringify → submitFn → 按钮 loading 管线全内置）；`submitText` 默认 `"提交"`。
+- `onSubmitStart`：默认不设；仅当需要在提交发起时同步做外部动作（如弹层整体 loading 态）才设。
+- 其余 ButtonProps：`type` 默认 `"primary"` 即够用；仅当需要按钮视觉定制（size / 样式）才传（`loading` 除外，由管线接管）。
+- **完整能力演示**：`apps/reference/src/pages/form/submit-btn/showcase/`；FormSubmitPanel 内置场景见 `apps/reference/src/pages/form/submit-panel/showcase/`。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（`FormSubmitBtnProps` = `Omit<ButtonProps, "loading">` + 以下）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `formMainInstance` | `FormMainInstance`（必填） | — | 提交所挂的 FormMain 实例（管线内调 validate / stringify） |
+| `submitFn` | `(stringifyData) => Promise<unknown>`（必填） | — | 提交方法 |
+| `submitText` | `string` | `"提交"` | 按钮文本 |
+| `onSubmitStart` | `() => void` | 未设 | 提交发起时同步回调 |
+| 其余 | `Omit<ButtonProps, "loading">` | `type` 默认 `"primary"` | ElButton 全量透传（loading 除外，由管线接管） |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `success` | `stringifyData` | submitFn resolve |
+| `fail` | `error` | submitFn reject |
+
+### Slots / Expose
+
+无。
+
+## 反模式 / 注意
+
+- **自管 loading**：按钮 loading 由管线内置（`loading` 已从透传面 Omit）——[MUST NOT] 外部再传 `:loading` 或自建 submitting 状态
+- **脱离表单实例使用**：`formMainInstance` 必填，未接实例时管线无处校验 / 序列化——裸用无意义
+- **管线顺序固定**：validate → stringify → submitFn；校验失败即停，不发 submitFn
+
+## 关联
+
+- 内置进 `FormSubmitPanel`（经 `submitBtnProps` 定制，勿重复外挂）
+- 按钮原语：`ActionBtn`（display 桶，confirm / loading 超集）——无表单实例的按钮走 ActionBtn
+- 类型：`FormMainInstance<PO, SO>`（FormMain expose 类型）
+- 范式页：`apps/reference/src/pages/form/submit-btn/showcase/`、`pages/form/submit-panel/showcase/`