@done-coding/admin-core 0.21.0 → 0.21.1-alpha.0

package/src/components/display/README.md

@@ -1,6 +1,6 @@
 # display 展示族
 
-展示与交互原语：TabsMain（Tab 容器）/ ActionBtn 系列（确认闸门 + 自动 loading）/ 尺寸与高度工具（WatchSize / HeightProvider）/ BooleanTag。
+展示与交互原语：TabsMain（Tab 容器）/ ActionBtn 系列（确认闸门 + 自动 loading）/ 尺寸与高度工具（WatchSize / HeightProvider）/ BooleanTag / ShadowClone（影分身双渲染位）。
 
 ## 组件文档（docs/）
 
@@ -11,13 +11,19 @@
 - [WatchSize](./docs/README-WatchSize.md) — 尺寸监听容器（mode / observeResize / debounce）
 - [HeightProvider](./docs/README-HeightProvider.md) — 纯数值高度预算节点（available = viewportHeight − reserve）
 - [BooleanTag](./docs/README-BooleanTag.md) — boolean 只读彩色标签
+- [ShadowClone](./docs/README-ShadowClone.md) — 影分身（零 DOM 输出双渲染位：本体就地 + 分身 teleport，目标晚渲染自动等待）
 
 ## 关键类型
 
-- `TabsMainProps` / `TabsMainItem` / `ActionBtnProps` / `ActionBtnConfirmConfig` / `ActionBtnConfigItem` / `ActionBtnGroupProps` / `ActionConfirmProps` / `BooleanTagProps`（经 `./types` 导出）
-- 内部件不导出：`TabsHeader` / `TabsTile` / `TabsRefineFlow` / `TabsNaturalFlow` / `use-tabs-query-sync`
+- `TabsMainProps` / `TabsMainItem` / `ActionBtnProps` / `ActionBtnConfirmConfig` / `ActionBtnConfigItem` / `ActionBtnGroupProps` / `ActionConfirmProps` / `BooleanTagProps` / `ShadowCloneProps`（经 `./types` 导出）
+- 内部件不导出：`TabsHeader` / `TabsTile` / `TabsRefineFlow` / `TabsNaturalFlow` / `use-tabs-query-sync` / `use-shadow-target`
+
+## 跨族依赖（被依赖）
+
+- form 族 → display 族（单向）：`FormSort` 依赖 `ShadowClone`（分身机制）、`FormActiveFilter` 依赖 `ActionBtn`（清除全部按钮）
 
 ## 范式页（apps/reference）
 
 - `/display/tabs/showcase`（基础 + queryKey）、`/display/tabs/guide`（channel 嵌套最佳实践）、`/display/tabs/tile`（平铺）、`/display/tabs/fullpage`（顶级自撑）、`/display/tabs/nested-channel`
 - `/display/action-btn/showcase`（16 场景）、`/display/action-btn-group/showcase`（5 场景）
+- 影分身场景见 `/form/sort/showcase`（FormSort 分身到表格表头）

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

@@ -0,0 +1,75 @@
+# ShadowClone（影分身）
+
+> 零 DOM 输出双渲染位原语：插槽内容渲染两处——本体就地 + 分身 teleport 到 `to` 目标（`disabled` 关闭分身仅就地）。「分身」≠「瞬移」：官方 teleport 是搬移（源位置不留内容），本组件本体与分身同时存在。分身位内容可选 `clone` 具名槽**独立提供**（本体/分身可不同 props，如交互模式差异）；未提供时 fallback 渲染默认槽（双份一致，向后兼容）。
+> 范式页：`apps/reference/src/pages/display/shadow-clone/`（影分身专项展示）+ `apps/reference/src/pages/form/sort/showcase/`（FormSortSwitchGroup 排序分身到表格表头场景）。
+
+## 定位
+
+- **同一受控内容的多渲染位底层机制**：表单控件分身到表格表头（FormSortSwitchGroup `shadowClone` per-option 影分身）、配置化体系的「一处配置多处展示」等
+- **独立裸用当**：任何「同一内容需要同时出现在两个位置」的场景（表头副本 / 悬浮副本等）
+- **何时不用**：单处展示直接写；「搬移」语义用 Vue 原生 `<teleport>`
+
+## 快速上手（最小可用）
+
+```html
+<ShadowClone to=".table-head">
+  <MySortWidget v-model="sortRules" />
+</ShadowClone>
+```
+
+**要点**：
+
+- `to` 传 CSS 选择器或 DOM 元素；**目标晚渲染是常态**（表格表头在表单下方）——组件内置 MutationObserver 等待目标出现后自动激活分身，零时序手控
+- `to` 无效（空 / selector 未命中）时分身静默等待不挂载——**不会触发 Vue 的「Invalid Teleport target」warn**（peer vue ^3.4 无 teleport `defer`，此为自实现等价物）
+- `disabled` 关闭分身（仅就地单处）
+
+## 分身位独立内容（clone 具名槽）
+
+本体与分身需要**不同 props / 内容**时（如排序本体整块循环、分身点小箭头），用 `clone` 具名槽独立提供分身内容：
+
+```html
+<ShadowClone to=".table-head">
+  <!-- 本体位：默认槽 -->
+  <FormSortSwitch v-model="dir" mode="cycle" />
+  <!-- 分身位：#clone 槽（未提供时 fallback 默认槽，双份一致） -->
+  <template #clone>
+    <FormSortSwitch v-model="dir" mode="dual-arrow" />
+  </template>
+</ShadowClone>
+```
+
+- **两处各自独立组件实例**（v-model 绑同一 ref 即同源同步、交互可不同）——与默认槽双份渲染同属「状态全外置」边界
+- 未提供 `#clone` 时行为与旧版完全一致（分身位渲染默认槽内容）——**向后兼容，消费方可渐进升级**
+
+## 使用边界（[MUST] 消费方遵守）
+
+- 两份 vnode 树 = **两个独立组件实例**——只适合「无内部状态 / 状态全外置的受控组件」（v-model 绑同一 ref 即同源同步）；有内部状态组件会状态分叉
+- 静态固定 id 内容双份渲染会撞 id（随机 id 各自生成不撞）——消费方负责
+- 根类豁免（规则 17）：组件无根元素（零 DOM 输出是语义核心），无 `dc-` 根类
+
+## 依赖关系
+
+- **被依赖**：form 族 `FormSortSwitchGroup`（`shadowClone` per-option 影分身，分身位 `#clone` 独立 mode）——form 族 → display 族单向依赖
+- 内部件不导出：`use-shadow-target`（目标有效性判定 + MutationObserver 等待 hook）
+
+## 测试
+
+- 独立测试：`src/components/display/__tests__/ShadowClone.test.ts`（9 用例）——双渲染位 / 目标无效零 warn / MutationObserver 晚渲染自动激活 / disabled / Element 目标 / 空插槽 / **clone 槽 fallback 与独立内容**
+- 集成消费：`FormSortSwitchGroup.test.ts`（per-option 分身、分身位 `#clone` 独立 mode）
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `to` | `string \| Element`（必填） | — | 分身 teleport 目标（CSS 选择器 / DOM 元素） |
+| `disabled` | `boolean` | `false` | 关闭分身（仅就地渲染单处） |
+
+### Slots
+
+| name | 语义 |
+| --- | --- |
+| `default` | 分身内容（本体 + 分身双渲染） |
+| `clone` | 分身位**独立**内容（可选）——未提供时 fallback 渲染 `default` 槽（双份一致） |

package/src/components/form/README.md

@@ -1,6 +1,6 @@
 # form 表单族
 
-配置式表单核心（11 组件，最大族）：`list` 配置驱动渲染 / 校验 / 序列化，`data` 同引用绑定，generate / parse / stringify 三方法 round-trip。
+配置式表单核心（13 组件，最大族）：`list` 配置驱动渲染 / 校验 / 序列化，`data` 同引用绑定，generate / parse / stringify 三方法 round-trip。
 
 ## 组件文档（docs/）
 
@@ -10,7 +10,20 @@
 - [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 — 文档待补
+- [FormActiveFilter](./docs/README-FormActiveFilter.md) — 生效筛选条件条（chips + × 移除 + 清除全部，纯 UI；投影逻辑在消费方 hook）
+- [FormInput](./docs/README-FormInput.md) — 输入框原语（el-input 全透传 + password 自动填充治理；影分身版 FormInputShadowClone 表头漏斗）
+- [FormSelect](./docs/README-FormSelect.md) — 选择器（options/remoteMethod/getOptions；影分身版 FormSelectShadowClone 表头漏斗）
+- [FormSortSwitchGroup / FormSortSwitch](./docs/README-FormSortSwitchGroup.md) — 复合排序组 + 单字段排序切换器（group 有 key 视角 / switch 无 key；`mode` cycle 首击升序对齐主流 / dual-arrow 双三角；`textType` label/状态文字；`shadowClone` 影分身 per-option teleportTo；依赖 display 族 ShadowClone）
+- [FormUpload](./docs/README-FormUpload.md) — 上传原语（ElUpload 封装，先传拿 URL 表单只提交 URL；`uploadFn` 注入不焊后端；上传中经 FORM_ITEM_CHANGE_LOADING 拦提交；进度 ElUpload 内置）
+- [FormUploadImage](./docs/README-FormUploadImage.md) — 图片上传（薄封装：accept image/* + 方形缩略图卡片 + 点击直达放大 + 悬停删除）
+- [FormUploadVideo](./docs/README-FormUploadVideo.md) — 视频上传（薄封装：accept video/* + 封面/占位 + 播放图标 + VideoPreviewTrigger 播放决策链）
+- [FormUploadAudio](./docs/README-FormUploadAudio.md) — 音频上传（薄封装：accept audio/* + 内联 `<audio controls>` 播放条即时试听；**不建弹窗**——业界音频无 lightbox 形态）
+- FormRadioGroup / FormTree / FormVerifyImage / FormVerifyCode — 文档待补
+
+## 跨族依赖
+
+- form 族 → display 族（单向）：`FormSort` 依赖 `ShadowClone`（分身机制）、`FormActiveFilter` 依赖 `ActionBtn`（清除全部按钮）
+- form 族 → modal 族（单向）：`FormUploadImage` 依赖 `ImagePreviewTrigger`（点击直达放大）、`FormUploadVideo` 依赖 `VideoPreviewTrigger`（播放弹窗决策链）
 
 ## 关键类型与 helper
 

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

@@ -0,0 +1,57 @@
+# FormActiveFilter（生效筛选条件条）
+
+> 当前已生效查询条件的投影展示条：条件 chips + 单项 × 移除 + 清除全部（可选）。纯 UI 组件——投影 / value→label / 表单值同步清除等逻辑在消费方 hook（ListLayout 内 `use-active-filter`）完成，本组件只收数据 + 发事件。
+> 业界对标：SAP Fiori "Filter Feedback Bar" / react-admin `<FilterValue>` / MUI FilterChipBar。
+> 范式页：`apps/reference/src/pages/list-layout/active-filter/`（ListLayout 集成场景）；独立裸用见同页组件区。
+
+## 定位
+
+- **ListLayout 的生效条件展示位**：ListLayout 开 `formActiveFilter` 后，在表单卡片顶部一行渲染（条件条在上、表单在下），数据 = `use-active-filter` hook 从 query 投影的条目
+- **独立裸用当**：任何「已生效筛选条件展示 + 移除」场景（非 ListLayout 体系、条件数据自持的页面/组件）
+- **何时不用**：无生效条件概念的场景；仅需静态展示用 ElTag 直写
+
+## 快速上手（最小可用）
+
+```html
+<FormActiveFilter
+  :filters="filters"
+  :allow-clear="true"
+  @remove="onRemove"
+  @clear="onClearAll"
+/>
+```
+
+**要点**：
+
+- `filters` 条目形状 `FormActiveFilterEntry`：`{ field, label, displayValue }`——`field` 是 query 字段名（× 移除事件的载荷），`label` 展示名，`displayValue` 展示值（枚举类应传 options 匹配后的 label，取不到传原值）
+- × 移除 = `@remove(field)`；清除全部 = `@clear()`（仅 `allowClear` 开启时显示按钮）——事件是纯上抛，**同步清表单值 / 重查是消费方职责**
+- **空态恒展示**：`filters` 为空时渲染灰字「暂无生效筛选条件」占位（行高与单条 tag 一致，新增生效条件不跳动）；「清除全部」仅在至少一条生效条件时出现
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`filters` 一个 prop 即为完整条件条**（chips + 单项 ×）。以下按需开：
+- `allowClear`：默认关；仅当需要一键清空全部生效条件才开（通常与「清空后重查」配合）
+- 单项移除始终可用（chips 自带 closable ×）——`allowClear` 只额外加「清除全部」按钮
+- **value→label 不在组件内**：组件不持有表单字段 config（保持纯 UI）——投影逻辑放消费方 hook（ListLayout 的 `use-active-filter` 从 `config.props.options` 取 label，取不到原值兜底）
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `filters` | `FormActiveFilterEntry[]`（必填） | — | 生效条件条目（field / label / displayValue） |
+| `allowClear` | `boolean` | `false` | 显示「清除全部」按钮（一键清空全部生效条件） |
+
+### Emits
+
+| name | 载荷 | 语义 |
+| --- | --- | --- |
+| `remove` | `field: string` | 点击单项 × ——消费方应移除 query 该字段 + 同步清表单值 + 重查 |
+| `clear` | — | 点击清除全部——消费方应清空全部生效条件 + 重查 |
+
+## 相关
+
+- 投影与联动逻辑：`list-layout/use-active-filter.ts`（ListLayout 内部 hook，不导出）
+- 集成组件：`ListLayout.formActiveFilter` / `ListLayout.allowClear`（见 list-layout docs）

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

@@ -0,0 +1,66 @@
+# FormInput（输入框原语）
+
+> el-input 全透传包装 + password 形态浏览器自动填充治理（`passwordAutoComplete` prop）。除治理点外 props / slots 全量透传 el-input，零收窄。
+> 范式页：`apps/reference/src/pages/form/input/showcase/`（五形态对照 + 组合链路）。
+
+## 定位
+
+- **password 形态的浏览器自动填充治理点**：apiKey / 账号密码录入等非登录表单字段被 Chrome 误填时，用 `passwordAutoComplete` 治理
+- **独立裸用当**：需要密码形态且与浏览器密码管理器交互受控的输入框
+- **何时不用**：普通输入直接用 el-input；真登录页**接受**浏览器填充（用户主动保存 = 期望被填，拦它违背设计意图）
+
+## 快速上手（最小可用）
+
+```html
+<FormInput v-model="secret" type="password" password-auto-complete="api-key" />
+```
+
+**要点**：
+
+- 字符串值（`api-key` / `new-password` / `off`）→ 密码输入框 `autocomplete` 设为此值。**默认推荐 `api-key`**——规范外词条 Chrome 不识别，实测全程未触发直接填充；`off` 是 el-input 密码形态默认值、Chrome 有意无视（不可靠）；`new-password` 实测出现过直接填充
+- `number N` → 不设置 autocomplete；透传 el-input 的 type 初始 `text`（无密码语义不触发填充），延迟 N ms 后恢复 `password`（避开 Chrome 加载期 autofill 探测窗口；点击填充拦不住，属浏览器正常交互）。text 窗口内组件内部屏蔽 EP `show-password` 强制坑（EP `showPassword=true` 会强制 type=password，恢复后显隐照常）
+- 不传 → 不设置 autocomplete（保持 el-input 默认行为）
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`passwordAutoComplete` 不传即为普通 el-input 包装**。以下按需开：
+- `passwordAutoComplete="api-key"`：非登录表单密码字段防填充首选（规范外词条最可靠）
+- `passwordAutoComplete={N}`（number）：需要连「加载填充」也拦截时（api-key 词条已拦不住时）；N=0 即挂载即切
+- `show-password`：显隐切换照常透传（number 延迟窗口内被组件内部屏蔽、恢复后可用）
+- **影分身（表头漏斗）用 `FormInputShadowClone`**（本组件 + 影分身包装，薄包装纯粹性——影分身能力不内嵌本组件）：列表页表格头预埋容器内显示漏斗图标，点击 popover 弹输入框，同一 v-model 与本体同源同步（与 FormSelectShadowClone 统一漏斗语义；「表头漏斗 = 点这里筛选」）
+- 实测反模式（[MUST NOT] 重复踩）：`autocomplete="off"`（Chrome 有意无视）/ `new-password`（有过直接填充记录）/ text→mounted 立即切换（Chrome 异步 autofill 补填）/ trap input（Chrome 可见性检查穿透）——全部实测证伪，组件只提供上述两个可靠机制
+
+## 依赖关系
+
+- form 族内部组件，无跨族依赖（仅透传 el-input）；影分身版 `FormInputShadowClone` 依赖内部件 `FormShadowCloneDispatch` → display 族 `ShadowClone`（详见 README-FormShadowCloneDispatch.md）
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `type` | `string` | — | 透传 el-input（显式声明以判定密码形态） |
+| `showPassword` | `boolean` | — | 透传 el-input 显隐切换（同上） |
+| `passwordAutoComplete` | `"api-key" \| "new-password" \| "off" \| number` | — | 密码形态自动填充治理（见上） |
+| 其余 | — | — | 全量 `$attrs` 透传 el-input（v-model / placeholder / clearable / 插槽等） |
+
+### FormInputShadowClone（影分身版）
+
+> 内部经 `FormShadowCloneDispatch` 实现：default 与 clone 两插槽各写一份 `<FormInput v-model="同一值" />` 同源绑定驱动双处视图一致；高亮判定在**本组件内部**（默认规则 + `isHighlighted` 覆盖）→ 经 dispatch `highlighted` 展示在漏斗 + 插槽作用域暴露。
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number` | — | v-model（透传 FormInput；本体与分身弹层同源） |
+| `shadowClone` | `boolean` | `false` | 影分身开关（本体 + 分身 label+漏斗，点击 popover 弹输入框，同一 v-model 同源同步） |
+| `teleportTo` | `string \| Element` | — | 分身目标容器（表头预埋唯一选择器；`shadowClone` 时生效，未配置不分身） |
+| `label` | `string` | — | 分身位字段文字（表头列名；label + 漏斗整块展示、高亮整块——表格 headerRender 只需留 teleportTo 容器，列名由分身自带） |
+| `isHighlighted` | `(value: unknown) => boolean` | 默认判定 | 分身高亮判定方法（非必传），入参 modelValue；默认 = 非 `null` / 非 `undefined` / 非空字符串 → 高亮（label + 漏斗整块） |
+| 其余 | — | — | 全量 `$attrs` 透传 FormInput（密码治理等能力完整继承） |
+
+### Slots
+
+| name | 语义 |
+| --- | --- |
+| 全部 | 透传 el-input 插槽（prefix / suffix / prepend / append 等） |

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

@@ -0,0 +1,77 @@
+# FormSelect（选择器）
+
+> el-select 包装（本地 options / 远程搜索 remoteMethod / 异步 getOptions）+ option 插槽自定义渲染 + 影分身（`shadowClone` 表头漏斗，点击 popover 弹选择器，同一 v-model 同源同步）。
+> 范式页：`apps/reference/src/pages/list-layout/sort/`（状态列表头漏斗弹选择器）。
+
+## 定位
+
+- **配置化表单的选择字段**：FormMain / FormSearch 配置接入（`render: FormSelect`），options 业务注入
+- **远程搜索**：`remoteMethod` 传入即自动开 filterable + remote（输入触发远程查询）
+- **异步取选项**：`getOptions` 挂载后拉取
+- **何时不用**：静态小选项集用原生 el-select 即可
+
+## 快速上手（最小可用）
+
+```html
+<FormSelect v-model="status" :options="[{ label: '启用', value: 1 }, { label: '禁用', value: 0 }]" />
+```
+
+**要点**：
+
+- `options`（本地静态）/ `remoteMethod`（远程搜索）/ `getOptions`（异步拉取）三选一提供选项源
+- `modelValue` = `OptionItem["value"]`；选中项经 `detailChange` 上抛完整选项（immediate 首发）
+- `option` 插槽自定义选项渲染（`{ data }` 作用域）
+- 其余 props / 事件全量 `$attrs` 透传 el-select（placeholder / clearable / size 等）
+
+## 能力边界 / 按需使用
+
+- **默认即够用：options + v-model 即为完整选择器**。以下按需开：
+- `remoteMethod`：远程搜索（自动 filterable + remote，输入触发查询）
+- `getOptions`：挂载后异步拉取选项
+- `itemCls`：选项类名
+- **影分身（表头漏斗）用 `FormSelectShadowClone`**（本组件 + 影分身包装，薄包装纯粹性）：列表页表格头预埋容器内显示漏斗图标，点击 popover 弹选择器，同一 v-model 与本体同源同步（与 FormInputShadowClone 统一漏斗语义：「表头漏斗 = 点这里筛选」）
+
+## 依赖关系
+
+- form 族内部组件，无跨族依赖（仅透传 el-select）；影分身版 `FormSelectShadowClone` 依赖内部件 `FormShadowCloneDispatch` → display 族 `ShadowClone`（详见 README-FormShadowCloneDispatch.md）
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `modelValue` | `OptionItem["value"]` | — | v-model |
+| `options` | `OptionItem[]` | `[]` | 本地选项集 |
+| `remoteMethod` | `(query?) => Promise<OptionItem[]>` | — | 远程搜索（自动 filterable + remote） |
+| `itemCls` | `string` | — | 选项类名 |
+| `getOptions` | `() => Promise<OptionItem[]>` | — | 挂载后异步拉取选项 |
+| 其余 | — | — | 全量 `$attrs` 透传 el-select（placeholder / clearable / size 等） |
+
+### FormSelectShadowClone（影分身版）
+
+> 内部经 `FormShadowCloneDispatch` 实现：default 与 clone 两插槽各写一份 `<FormSelect v-model="同一值" />` 同源绑定驱动双处视图一致；高亮判定在**本组件内部**（默认规则 + `isHighlighted` 覆盖）→ 经 dispatch `highlighted` 展示在漏斗 + 插槽作用域暴露。
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `modelValue` | `OptionItem["value"]` | — | v-model（透传 FormSelect；本体与分身弹层同源） |
+| `shadowClone` | `boolean` | `false` | 影分身开关（本体 + 分身 label+漏斗，点击 popover 弹选择器，同一 v-model 同源同步） |
+| `teleportTo` | `string \| Element` | — | 分身目标容器（表头预埋唯一选择器；`shadowClone` 时生效，未配置不分身） |
+| `label` | `string` | — | 分身位字段文字（表头列名；label + 漏斗整块展示、高亮整块——表格 headerRender 只需留 teleportTo 容器，列名由分身自带） |
+| `isHighlighted` | `(value: unknown) => boolean` | 默认判定 | 分身高亮判定方法（非必传），入参 modelValue；默认 = 非 `null` / 非 `undefined` / 非空字符串 → 高亮（label + 漏斗整块） |
+| 其余 | — | — | 全量 `$attrs` 透传 FormSelect（options/remoteMethod/option 插槽等能力完整继承） |
+
+### Emits
+
+| name | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:modelValue` | `OptionItem["value"]` | v-model 上抛（本体与分身弹层同源） |
+| `detailChange` | `OptionItem \| undefined` | 选中项详情变更（immediate 首发） |
+| 其余 | el-select events | `$attrs` 透传（change / blur 等） |
+
+### Slots
+
+| name | 语义 |
+| --- | --- |
+| `option` | 选项自定义渲染（`{ data }` 作用域；本体与分身弹层内选择器共用） |

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

@@ -0,0 +1,65 @@
+# FormShadowCloneDispatch（form 族 · 影分身骨架：漏斗开关 + popup）
+
+## 定位
+
+form 族系**通用影分身骨架**——本体就地渲染（default 槽）+ 分身位（label 字段文字 + 漏斗按钮整块，表头筛选惯例入口，点击漏斗 popover 弹层）+ popup 内容（clone 槽）。
+
+**职责收敛**：双渲染位编排 + 漏斗展示（含高亮标识）+ popup 骨架。**零值逻辑**——不持有 v-model、不知道值本身；值由消费方插槽内容自己持有（同源绑定驱动双处视图一致）。
+
+漏斗只是「影分身触发 popover 的开关」，非筛选语义组件。
+
+## 快速上手（最小可用）
+
+```vue
+<FormShadowCloneDispatch
+  shadow-clone
+  teleport-to=".head-slot"
+  label="标题"
+  :highlighted="hasValue"
+>
+  <!-- 本体位：实际组件形态（消费方写死绑定，无需 scope） -->
+  <FormInput v-model="keyword" />
+  <!-- clone 槽（popup 内容）：不传即自动显示 default 同款 -->
+  <template #clone>
+    <FormInput v-model="keyword" size="small" />
+  </template>
+</FormShadowCloneDispatch>
+```
+
+## 能力边界 / 按需使用
+
+- **影分身**：`shadowClone` + `teleportTo` 开启 → 分身位 = **label（prop 传入）+ 漏斗按钮整块**（对齐排序 chip 形态：自带字段文字，表格 headerRender 只需留 teleportTo 容器、无需再写列名）；未开启/未配置 teleportTo 时仅渲染 default 槽（单份，零行为变化）
+- **高亮**：分身整块（label + 漏斗）按 `highlighted` 展示激活态（同 primary）；插槽作用域同步暴露 `{ highlighted }` 供消费方在插槽内**同级处理**（包外层/加提示等），不影响插槽内实际组件（FormInput/FormSelect）的纯粹性——判定逻辑上移消费方（默认规则 + `isHighlighted` 方法覆盖，见 FormInputShadowClone）
+- **晚渲染目标**：teleport 目标晚出现（表头在表单下方）由内部 ShadowClone（display 族）MutationObserver 等待自动激活，无需手控
+
+## 依赖关系
+
+- display 族 `ShadowClone`（影分身双渲染位机制，单向依赖）；form 族 `FormInputShadowClone` / `FormSelectShadowClone` 基于本组件实现
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `shadowClone` | `boolean` | `false` | 影分身开关（本体 default 槽 + 分身 label+漏斗双渲染位，点击漏斗 popover 弹层展示 clone 槽内容） |
+| `teleportTo` | `string \| Element` | — | 分身目标容器（表头预埋唯一选择器；`shadowClone` 时生效，未配置不分身） |
+| `label` | `string` | — | 分身位字段文字（表头列名；label + 漏斗整块展示、高亮整块——不传仅漏斗，向后兼容） |
+| `highlighted` | `boolean` | `false` | 分身整块高亮标识（外部判定后传入，如筛选有值；插槽作用域同步暴露） |
+| `popoverWidth` | `number \| string` | `220` | popover 弹层宽度（表头空间内弹层，默认容纳输入框/选择器） |
+
+### Emits
+
+无（零值逻辑：v-model 由消费方组件持有，经插槽同源绑定驱动双处视图一致）。
+
+### Slots
+
+| name | 作用域参数 | 语义 |
+| --- | --- | --- |
+| `default` | `{ highlighted: boolean }` | 本体位内容（实际组件形态；一般直接写死绑定，无需 scope——scope 仅在需要拿高亮标识做同级处理时用） |
+| `clone` | `{ highlighted: boolean }` | **popup 弹层内容**（漏斗点击后展示）；**默认 fallback = default 插槽内容**（不传即与本体同形态） |
+
+### Exposes
+
+无（内部 ShadowClone / ElPopover 实例不对外暴露）。

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

@@ -0,0 +1,131 @@
+# FormSortSwitchGroup（复合排序组）& FormSortSwitch（单字段排序切换器）
+
+> 两组件分工：**`FormSortSwitch`** = 单字段排序切换器（纯状态/展示件，v-model = 方向值 `"asc" | "desc" | undefined`，**无 key——不知道自己的字段**）；**`FormSortSwitchGroup`** = 多字段容器（**key 视角在 group**，v-model = 有序 `FormSortRule[]`，依赖 Switch 组装）。交互 `mode` 双模式；`shadowClone` 影分身（per-option `teleportTo`）；`textType` 展示文本模式（label / 状态文字）。
+> 范式页：`apps/reference/src/pages/form/sort/showcase/`（FormMain 配置化接入 + 影分身 + 两模式对照）。
+
+## 定位
+
+- **复合排序表单元素**：FormMain / FormSearch 配置化接入（`render: FormSortSwitchGroup`），序列化交给消费方 `stringify`（如 `field:dir` 逗号复合串）
+- **单字段排序开关**：直接裸用 `FormSortSwitch`（v-model 绑方向值，无需关心字段身份）
+- **何时不用**：单字段单选排序（后端单 key 排序）用 ElSelect / 原生排序即可
+
+## 快速上手（最小可用）
+
+```html
+<FormSortSwitchGroup :options="options" v-model="sortRules" />
+```
+
+**要点**：
+
+- `options` 业务注入（`{ field, label }[]`，条目可带非必传 `teleportTo`）——**组件不内置业务字段**
+- Group v-model 协议 = 有序 `FormSortRule[]`（`{ field, dir: "asc" | "desc" }`，顺序即优先级）；空数组 = 无排序
+- FormMain 接入时 `stringify` 序列化（如 `list.map(r => `${r.field}:${r.dir}`).join(",")`）；表单模型持有数组
+- 状态全外置（v-model），组件零内部状态 → 可安全影分身双渲染
+- **默认 `mode: "cycle"`**（首击升序，对齐主流）——零配置即主流交互
+
+## 组件分工（Switch / Group）
+
+| | `FormSortSwitch` | `FormSortSwitchGroup` |
+| --- | --- | --- |
+| 职责 | 单字段 chip：方向状态 + 交互 + 展示（label / 状态文字） | 多字段容器：options 拆包 → N 个 Switch + 按 field 重组 v-model 数组 |
+| v-model | 方向值 `"asc" \| "desc" \| undefined`（**无 key**，默认 `undefined`） | 有序 `FormSortRule[]`（**有 key**，顺序即优先级） |
+| 是否知道自己的字段 | **不知道**（直接作表单元素无需知道；作 group 的 item 由 group 知道） | 知道（key 视角持有者） |
+| 内部状态 | 零（状态全外置） | 零（组装逻辑纯派生） |
+
+## 交互模式（mode）
+
+| mode | 默认 | 交互语义 | 适用 |
+| --- | --- | --- | --- |
+| `"cycle"` | ✅ | **点击整块三态循环**：`undefined → 升序 → 降序 → 取消`（循环往复）。**首击升序对齐主流**（Ant / Element Plus / MUI / Syncfusion 均为 asc first） | 默认全覆盖；与主流表头排序交互同构，EP 生态用户零学习成本 |
+| `"dual-arrow"` | — | **上下双三角独立点击**：点 ↑ = 升序（升序态再点 = 取消）、点 ↓ = 降序（降序态再点 = 取消）；方向互斥切换（激活一侧时点另一侧切向，优先级不动）；点击 label 不触发 | 多字段复合排序、操作者需要「点一次即确定方向」的确定性交互场景 |
+
+**cycle 状态转换表（核心机制）**：每次点击 = `NEXT[当前值]` 查表取下一个，**绝不依赖点击次数 / 历史推断**——状态可能被外部（影分身另一处操作 / 双向 v-model 同步）改写，计数推断会失配：
+
+```ts
+const NEXT = {
+  undefined: "asc",  // 首击升序
+  asc: "desc",
+  desc: undefined,   // 取消
+};
+```
+
+例：cycle 点击第一下 = 升序；此时影分身（dual-arrow）关闭了升序（状态回 `undefined`）；cycle 再点一下 = **仍从 `undefined` 出发 = 升序**（非计数推断的 desc）。
+
+- 两模式 **v-model 协议完全一致**（方向值 / 规则数组），模式纯属 UI 交互层——切换 mode 对数据零影响、零迁移成本
+- **模式视觉辨识**（一眼可判当前交互）：dual-arrow 三角默认**中灰**（WCAG 1.4.11 对比度 ≥3:1 达标 + 「可点」信号）+ hover primary + 激活点亮对应三角；cycle 三角保持 placeholder 浅灰纯指示（整块 hover 变色是它的辨识信号）——两模式视觉语言分离
+- 三角尺寸 12px（对齐 [Fluent UI 排序箭头规格](https://github.com/microsoft/fluentui/issues/25706)）+ 伪元素透明热区扩展（命中面 > 视觉图标）
+- 激活视觉两模式一致：chip primary 高亮 + 优先级序号 + 方向指示（cycle 整块点亮、dual-arrow 点亮对应三角）
+
+## 展示文本模式（textType）
+
+chip 上的文本内容两选：
+
+| textType | 默认 | 展示内容 | 适用 |
+| --- | --- | --- | --- |
+| `"state"` | ✅ | 状态文字：「**默认**」（未排序）/「**升序**」/「**降序**」 | 独立作为表单元素（自身即状态展示）；`label` 可不传 |
+| `"label"` | — | 字段名（options 的 label） | **group 的 item 即此模式**（group 显式设置） |
+
+## 影分身（shadowClone，能力内聚在 FormSortSwitch）
+
+- **影分身是控件级通用能力，内聚在 `FormSortSwitch`**：任何排序开关（独立或 group 的 item）都可自带分身——`shadowClone` 开关 + `teleportTo` 目标 + `teleportMode` 分身交互模式
+- **group 纯编排**：`shadowClone` 总开关 + `teleportMode` 透传 + **`FormSortOption` 条目级 `teleportTo`**（非必传）透传——配置了目标的条目分身到该目标（ShadowClone 双处渲染、**同一 model 同源同步**，操作任一处同步）；**未配置 `teleportTo` 的条目不分身**（仅本体渲染）
+- `teleportTo` 目标不限于表头，看指向哪个元素（`string \| Element`）；表格体系可按列头容器逐列配置
+- **分身位交互模式独立于本体**：`teleportMode`（默认 `"dual-arrow"` = 点小箭头升/降序）；数据与本体同一 v-model，仅交互模式不同
+- 目标晚渲染（表头容器在表单下方）无需手控：ShadowClone 内置 MutationObserver 等待目标出现后自动激活分身（「合适的时机打出去」）
+- 优先级序号：chip 内右置小号 primary 数字（克制样式——不悬浮溢出 chip 外）
+
+## 依赖关系
+
+- **依赖**：display 族 `ShadowClone`（影分身机制，经 `FormSortSwitch` 内聚使用）——form 族 → display 族单向依赖
+- 内部组装：`FormSortSwitchGroup` 依赖 `FormSortSwitch`（同族基础件，对外导出、可独立使用）
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### FormSortSwitchGroup（复合排序组）
+
+#### Props
+
+| name | type | 默认 | 必填 | 语义 |
+| --- | --- | --- | --- | --- |
+| `options` | `FormSortOption[]` | — | ✅ | 排序字段选项（`{ field, label, teleportTo? }[]`，业务注入；`teleportTo` 为影分身目标，非必传） |
+| `modelValue` | `FormSortRule[]` | `[]` | — | 有序排序规则（v-model，顺序即优先级） |
+| `mode` | `"cycle" \| "dual-arrow"` | `"cycle"` | — | 本体 item 交互模式 |
+| `shadowClone` | `boolean` | `false` | — | 影分身开关（配置了 `teleportTo` 的条目分身到目标，同 model 同源同步） |
+| `teleportMode` | `"cycle" \| "dual-arrow"` | `"dual-arrow"` | — | 分身 item 交互模式（独立于本体；默认点小箭头升/降序） |
+
+#### Emits
+
+| name | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:modelValue` | `FormSortRule[]` | v-model 上抛（item 激活 / 切向 / 取消 → 按 field 重组后新数组） |
+
+#### Slots / Expose
+
+无（状态全外置，组装逻辑纯派生）。
+
+### FormSortSwitch（单字段排序切换器）
+
+#### Props
+
+| name | type | 默认 | 必填 | 语义 |
+| --- | --- | --- | --- | --- |
+| `modelValue` | `"asc" \| "desc" \| undefined` | `undefined` | — | v-model 方向值（三态：undefined=默认无排序 / asc / desc；**默认 undefined 非 null**） |
+| `mode` | `"cycle" \| "dual-arrow"` | `"cycle"` | — | 交互模式 |
+| `textType` | `"label" \| "state"` | `"state"` | — | 展示文本（state=「默认/升序/降序」状态文字 / label=字段名） |
+| `label` | `string` | — | 仅 `textType="label"` | 字段显示名（state 模式可不传） |
+| `showOrder` | `boolean` | `false` | — | 是否显示优先级序号（group 在 options>1 时传 true） |
+| `order` | `number` | — | — | 优先级序号值（1-based，`showOrder` 时显示） |
+| `shadowClone` | `boolean` | `false` | — | 影分身开关（本体就地 + 分身 teleport 到 `teleportTo`，同一 v-model 同源同步） |
+| `teleportTo` | `string \| Element` | — | `shadowClone` 时 | 分身目标容器（未配置不分身） |
+| `teleportMode` | `"cycle" \| "dual-arrow"` | `"dual-arrow"` | — | 分身位交互模式（独立于本体 mode） |
+
+#### Emits
+
+| name | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:modelValue` | `"asc" \| "desc" \| undefined` | v-model 上抛（cycle 查 NEXT 表 / dual-arrow 方向两态；`undefined`=取消） |
+
+#### Slots / Expose
+
+无（状态全外置，零内部状态 → 可安全影分身双渲染）。