@done-coding/admin-core 0.17.1-alpha.0 → 0.18.1-alpha.0

package/src/components/modal/README.md

@@ -0,0 +1,21 @@
+# modal 弹窗族
+
+弹窗三原语 + 架子体系：命令式开窗走 `ModalShelf`（层级治理）+ `ModalPorter`（evoke），`ModalShelfMap` declare merge 全链类型化。
+
+## 组件文档（docs/）
+
+- [ModalConfirm](./docs/README-ModalConfirm.md) — 确认弹窗/抽屉原语（onXxx props 契约）
+- [ModalForm](./docs/README-ModalForm.md) — 弹窗 + 表单 + 校验提交
+- [ModalDetail](./docs/README-ModalDetail.md) — CRUD 预设薄壳（add / edit / read）
+- [ModalShelf](./docs/README-ModalShelf.md) — 弹窗架子（level: app/page/custom + 层级断言）
+- [ModalPorter](./docs/README-ModalPorter.md) — 弹窗搬运（modalList 注册表 + evoke + 卸载自动清理）
+
+## 关键类型与机制
+
+- 类型：`ModalLevel` / `ModalSameKeyStrategy` / `ModalShelfMap` / `ModalInjectedProps` / `EvokeHandle` / `RegisterEntry` / `ShelfController`（经 `./types` + `./modal-shelf-types` 导出）
+- ⚠️ deprecated 兼容别名：`ConfirmModal` / `FormModal` / `DetailModal`（指向新名，后续大版本移除）——**新代码 [MUST NOT] 用旧名**，仅存量迁移期过渡（readme API 表与范式页均用新名）
+- 内置挂载：AppLayout 内置 `level="app"`、AppPage 内置 `level="page"`（业务 [MUST NOT] 自声明）
+
+## 范式页（apps/reference）
+
+- `/modal/guide`（对接内置 page 架子）/ `/modal/porter/showcase`（三层自定义架子 + 5 场景）/ `/modal/confirm/showcase`（modal/drawer 双形态）/ `/modal/form-modal/showcase`（独立原语用法）

package/src/components/modal/docs/README-ModalConfirm.md

@@ -0,0 +1,105 @@
+# ModalConfirm（配置化确认弹窗 / 抽屉）
+
+> 确认型弹层原语：modal / drawer 双形态一键切换，确认/取消走 Promise 契约（返回 false 不关、resolve 关）。
+> 范式页：`apps/reference/src/pages/modal/confirm/showcase/`（双形态 + $attrs 透传实证）
+
+## 定位
+
+- **何时用**：操作确认、轻量表单提交、任意「弹窗/抽屉外壳 + 自定义内容」场景
+- **何时不用**：复杂表单提交用 `ModalForm`；完整 CRUD 用 `ModalDetail`；「架子 + 注册表」命令式弹窗体系用 `ModalShelf` + `ModalPorter`
+- 关键机制：`onClose`/`onCancel`/`onConfirm` 是 **props 不是 emits**（onXxx props 约定），确认/取消回调返回 `Promise<boolean|void>` 时——返回 `false` 不关闭、reject 不关闭、resolve 关闭
+- `inheritAttrs: false` + 全量 `v-bind $attrs` 透传底层 ElDialog/ElDrawer：未声明 EP prop（如 `draggable` / `destroy-on-close`）直达底层
+
+## 快速上手（最小可用）
+
+常规确认弹窗零配置——默认 modal 形态 + 宽 420 + 自动关窗：
+
+```vue
+<ModalConfirm
+  v-model:show="show"
+  title="操作确认"
+  :on-confirm="onConfirm"     <!-- 异步 → 自动 loading 转圈，resolve 关窗 -->
+/>
+```
+
+**要点**：
+
+- `show` 必传（`v-model:show`）；关闭路径：点确认/取消/遮罩/ESC/右上角关闭 → 统一收敛到 `onClose(status)`，`status=true` 表示因确认关闭
+- 提交类确认让 `onConfirm` 返回 Promise 并配 `use-loading`：等待期按钮自动转圈，reject 不关窗（错误留在原地展示）、resolve 关窗
+
+## 能力边界 / 按需使用
+
+- **默认即够用：modal 居中 + 宽 420 + 确认/取消自动关窗**——绝大多数确认弹窗只传 `show`/`title`/`onConfirm`。
+- `layerType="drawer"`：仅当确认内容需要抽屉形态（侧滑、大尺寸自绘内容）时开；drawer 下 `width` 语义变为抽屉尺寸（size），`direction` 控制开合方向（仅 drawer 生效）。
+- `modalReserve`：默认 `200`（弹层可用高 = innerHeight − 200）即够用；仅当弹层内嵌表格/表单需要更高可用视口时调小（联动 TableMain 高度链）。
+- `use-loading`：仅当 `onConfirm` 返回 Promise 时配；同步确认无需。
+- `headerDivider`/`footerDivider`：默认随形态（drawer=true / modal=false）；仅需显式覆盖时传。
+- `#footer` 自绘操作区：仅当默认底部按钮不满足（需要自绘布局/额外内容）时用，scoped 提供 `{cancelHandler, confirmHandler, loading}`。
+- **完整能力演示**（双形态切换 + 异步确认 + 分割线 + $attrs 透传）：`apps/reference/src/pages/modal/confirm/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps，无 types.ts）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必传） | — | 可见性（v-model:show） |
+| `showClose` | `boolean` | `true` | 右上角关闭按钮 |
+| `onClose` | `(status?: boolean) => void` | — | 关闭回调，status = 是否因确认关闭 |
+| `onCancel` | `() => void \| Promise<boolean\|void>` | — | 取消回调；返回 false 则不关闭 |
+| `onConfirm` | `() => void \| Promise<boolean\|void>` | — | 确认回调；返回 false 不关闭、reject 不关闭，resolve 关闭并传 status=true |
+| `title` | `string \| (() => VNode\|VNode[])` | — | 标题 |
+| `content` | `string \| (() => VNode)` | — | 正文 |
+| `cancelText` | `string \| (() => VNode)` | `"取消"` | 取消按钮文案 |
+| `confirmText` | `string \| (() => VNode)` | `"确定"` | 确认按钮文案 |
+| `hiddenCancel` | `boolean` | `false` | 隐藏取消按钮 |
+| `width` | `number \| string` | `420` | modal = 弹窗宽度 / drawer = 抽屉尺寸（size） |
+| `reverse` | `boolean` | `false` | 反转按钮位置 |
+| `closeOnPressEscape` | `boolean` | `true` | ESC 关闭 |
+| `closeOnClickModal` | `boolean` | `true` | 点击遮罩关闭 |
+| `useLoading` | `boolean` | — | 确认按钮 loading（onConfirm 返回 Promise 时转圈） |
+| `type` | `ButtonProps["type"]` | `"primary"` | 确认按钮 type |
+| `layerType` | `"modal" \| "drawer"` | `"modal"` | modal = ElDialog 居中弹窗 / drawer = ElDrawer |
+| `direction` | `"rtl"\|"ltr"\|"ttb"\|"btt"` | `"rtl"` | drawer 方向（仅 drawer 生效） |
+| `headerDivider` | `boolean` | 按形态：drawer=true / modal=false | header 下分割线 |
+| `footerDivider` | `boolean` | 按形态：drawer=true / modal=false | footer 上分割线 |
+| `modalReserve` | `number` | `200` | modal 形态弹层体可用高视口预留 px（provide SCOPE_VIEWPORT_MAX_HEIGHT = innerHeight − modalReserve） |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:show` | `boolean` | 可见性同步（v-model） |
+
+⚠️ `onClose`/`onCancel`/`onConfirm` 是 props 不是 emits（onXxx props 约定）。
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| 默认 | 无 | 正文（content prop 之外的自绘内容区） |
+| `#title` | 无 | 标题 |
+| `#main-header` | 无 | 头部区域（含标题） |
+| `#main-footer` | 无 | 底部区域（含按钮） |
+| `#footer` | `{cancelHandler, confirmHandler, loading}` | 完全自绘操作区 |
+
+### Expose
+
+无。`inheritAttrs: false` + 全量 `v-bind $attrs` 透传底层 ElDialog/ElDrawer（未声明 EP prop 如 `draggable`/`destroy-on-close` 直达）；provide `BODY_CONTENT_VIEWPORT_HEIGHT`（老 key）+ `SCOPE_VIEWPORT_MAX_HEIGHT`（新 key）。
+
+## 反模式 / 注意
+
+- **关闭回调命名三件套是 props**：`onClose`/`onCancel`/`onConfirm` 走 props 传（`:on-confirm="..."`），不是 `@confirm`；emit 侧只有 `update:show`
+- **onConfirm 的 false / reject 语义**：返回 `false` 不关闭、reject 不关闭（错误留窗内展示）、resolve 关闭——三条路径别写混
+- **`closeOnClickModal` / `closeOnPressEscape` 默认开**：误触遮罩/ESC 即关，需要「不可轻易关闭」的强确认场景显式关掉
+- **`headerDivider` / `footerDivider` 默认随形态**：drawer=true / modal=false；直接不传会得到形态默认值，别以为「没传就是没有」
+- **`direction` 只在 drawer 生效**：modal 形态传了不报错也不生效
+- **老 key 并存**：`BODY_CONTENT_VIEWPORT_HEIGHT`（老）+ `SCOPE_VIEWPORT_MAX_HEIGHT`（新）双 provide，消费新 key 即可
+
+## 关联
+
+- 弹层族：`ModalForm`（组合 ModalConfirm + FormMain 做表单提交）、`ModalDetail`（CRUD 预设薄壳，内部委托 ModalForm）
+- 命令式弹窗体系：`ModalShelf`（架子 + level 层级）+ `ModalPorter`（modalList 注册表）
+- 视口可用高链：`modalReserve` → provide `SCOPE_VIEWPORT_MAX_HEIGHT`（新 key）/ `BODY_CONTENT_VIEWPORT_HEIGHT`（老 key），TableMain `viewportHeight`/`parentChannel` 同链消费
+- 范式页：`apps/reference/src/pages/modal/confirm/showcase/`

package/src/components/modal/docs/README-ModalDetail.md

@@ -0,0 +1,103 @@
+# ModalDetail（配置化 CRUD 弹窗 / 抽屉）
+
+> CRUD 预设薄壳：`type`（add/edit/read）决定标题前缀与提交分支，内部委托 ModalForm 渲染配置化表单。
+> 范式页：`apps/reference/src/pages/list-page/guide/`（DetailModalItem 作 ModalPorter item 的薄适配器）、`apps/reference/src/pages/modal/guide/`
+
+## 定位
+
+- **空间一等公民**：CRUD 弹窗空间首选（add / edit / read 语义内置），经 ModalPorter evoke 使用
+- **何时用**：新增/编辑/查看三态表单弹窗，一套 `list` 配置三态复用（标题自动带前缀）
+- **何时不用**：只有提交没有三态语义的单表单用 `ModalForm`；确认类用 `ModalConfirm`
+- 结构：CRUD 预设薄壳内部委托 ModalForm（强制 `headerDivider:false`/`footerDivider:false`），只留 add/edit 语义——`type` 决定标题前缀与提交走哪个 api
+- 泛型：`PO` 模型 / `SO` 序列化；提交分支在 `detailSubmitFn` 中——`type !== "add"` 都走 `editApi`
+
+## 快速上手（最小可用）
+
+作 ModalPorter item 的薄适配器（`list-page/guide/DetailModalItem.vue`——`show`/`closeFn`/`payload` 来自架子注入，add/edit 动态取自 payload）：
+
+```ts
+const modalProps = computed(() => ({
+  show: props.show,
+  type: props.payload.type,          // add / edit 动态取自 payload
+  data: props.payload.data,
+  list: userBaseFormList,            // 静态配置直接 import，不进 payload
+  addApi: addUserApi,
+  editApi: editUserApi,
+  "onUpdate:show": (v: boolean) => { if (!v) props.closeFn(); },
+  onAfterAdd: () => { props.payload.onDone?.(); props.closeFn(); },
+  onAfterEdit: () => { props.payload.onDone?.(); props.closeFn(); },
+}));
+```
+
+**要点**：
+
+- 四必传：`show`（v-model）、`data`、`list`、`type`（`"add"|"edit"|"read"`）
+- 标题自动态：不传 `title` 时回退「新增[subTitle] / 编辑[subTitle]」；传 `title`（`() => VNode[]`）则整体替换内置标题
+- 薄适配器模式（ModalPorter item）：架子注入的 `closeFn` 挂在 `onUpdate:show` 上（v 为 false 时关闭），`payload.onDone` 在 after* 里回调——业务 [MUST] 自己把「关窗 + 刷新」接上，壳不代劳
+
+## 能力边界 / 按需使用
+
+- **`type` 三态判据**：`"add"` 新增（标题「新增…」+ 走 `addApi`）/ `"edit"` 编辑（标题「编辑…」+ 走 `editApi`）/ `"read"` 只读（`type !== "add"` 都走 `editApi`——read 态建议 `editApi` 传空/同 edit，只读不应触发真实提交）。一套 `list` 配置三态复用。
+- `addApi`/`editApi`：不传也 resolve → 仍 emit after*——纯 UI 闭环（暂不接后端）可不传；真接后端时传，提交成功以真实响应为准。
+- `title`/`subTitle`：默认标题（新增/编辑 + 前缀）即够用；仅需定制标题（如带图标）时传。
+- `formLayout`/`labelWidth` 等布局 props：默认即够用；仅栅格/紧凑需求时配。
+- `layerType="drawer"`：仅当 CRUD 表单需要抽屉形态时开。
+- **完整能力演示**（薄适配器 + 自定义标题 + 提交闭环）：`apps/reference/src/pages/list-page/guide/`、`apps/reference/src/pages/modal/guide/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（类型 `ModalDetailProps<PO,SO>`）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必传） | — | 可见性 |
+| `data` | `PO`（必传） | — | 表单数据 |
+| `list` | `FormItemConfigList<PO,SO>`（必传） | — | 表单配置 |
+| `type` | `DetailType = "add"\|"edit"\|"read"`（必传） | — | 表单类型：决定标题前缀与用哪个 api |
+| `title` | `() => VNode[]` | — | 自定义标题整体替换内置标题；不传回退 新增[subTitle]/编辑[subTitle] |
+| `subTitle` | `string` | — | 标题后缀 |
+| `addApi` | `(data: ExtractFormStringifyFromObject<PO,SO>) => Promise<any>` | — | 新增 api；未传也 resolve → 仍 emit afterAdd |
+| `editApi` | `(data: ExtractFormStringifyFromObject<PO,SO>) => Promise<any>` | — | 编辑 api；未传也 resolve → 仍 emit afterEdit |
+| `width` | `number \| string` | `600` | 宽度 |
+| `formLayout` | `FormMainProps<PO,SO>["layout"]` | `{span:24}` | 表单布局 |
+| `formProps` | `Partial<FormProps>` | — | elForm 属性 |
+| `formRowGutter` | `number` | — | 行 gutter |
+| `labelWidth` | `string` | `"auto"` | label 宽度 |
+| `layerType` | `ModalLayerType` | `"modal"` | 弹层形态 |
+| `direction` | `ModalDirection` | `"rtl"` | drawer 方向 |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:show` | `boolean` | 可见性同步（v-model） |
+| `afterAdd` | 序列化数据 | 新增提交成功（addApi resolve 后） |
+| `afterEdit` | 序列化数据 | 编辑提交成功（editApi resolve 后） |
+
+### Slots
+
+| 槽 | 语义 |
+| --- | --- |
+| `#header` | 头部（映射到 ModalConfirm 的 main-header） |
+| `#footer` | 底部（映射到 ModalConfirm 的 main-footer） |
+
+### Expose
+
+无。
+
+## 反模式 / 注意
+
+- **`type="read"` 无独立提交语义**：`detailSubmitFn` 中 `type !== "add"` 都走 `editApi`——read 态建议 editApi 传空/同 edit（只读态不应触发真实提交分支）
+- **薄适配器要自己接关窗/刷新**：作 ModalPorter item 时，`closeFn` 挂 `onUpdate:show`、`payload.onDone` 挂 after*——壳不代劳「关窗 + 列表刷新」闭环
+- **addApi/editApi 未传也 resolve**：仍 emit after*——「未接 api 的假成功」可能掩盖接入遗漏，确认表单提交成功以真实响应为准
+- **`title` 传了就是整体替换**：自定义标题替换内置前缀标题，而不是追加；只想要后缀用 `subTitle`
+- **分割线强制关**：壳内部强制 `headerDivider:false`/`footerDivider:false`，外部传值不生效（无需传）
+
+## 关联
+
+- 委托链：`ModalDetail` → `ModalForm` → `ModalConfirm`（Promise 契约 / $attrs 透传 / 分割线语义同源）
+- 表单引擎：`FormMain`（form 族）
+- 命令式弹窗体系：`ModalShelf` + `ModalPorter`（薄适配器模式范式见 `list-page/guide/DetailModalItem.vue`）
+- 类型：`DetailType`、`ModalLayerType`、`ModalDirection`（modal/types.ts）
+- 范式页：`apps/reference/src/pages/list-page/guide/`、`apps/reference/src/pages/modal/guide/`

package/src/components/modal/docs/README-ModalForm.md

@@ -0,0 +1,97 @@
+# ModalForm（配置化表单弹窗 / 抽屉）
+
+> 「ModalConfirm 外壳 + FormMain 表单」组合件：配置驱动渲染表单，提交走 Promise 契约（reject 不关窗 / resolve 关窗 + submitSuccess）。
+> 范式页：`apps/reference/src/pages/modal/form-modal/showcase/`（独立原语用法）
+
+## 定位
+
+- **空间一等公民**：弹窗表单空间首选（非 CRUD 的表单弹窗）
+- **何时用**：弹窗/抽屉内配置化表单提交（新增反馈、编辑资料等单表单场景）
+- **何时不用**：完整 CRUD 弹窗（新增/编辑/查看三态 + 双 api）用 `ModalDetail`；确认类交互用 `ModalConfirm`；纯弹窗体系管理用 `ModalShelf` + `ModalPorter`
+- 内部链路：`show` 变 true → FormMain `validate()` → `stringify()` → `submitFn(data)`；`show` 变 false 时 `clearValidate()`
+- 泛型：`PO` 模型 / `SO` 序列化——`submitFn` 收到的是 `ExtractFormStringifyFromObject<PO,SO>`（序列化后数据）
+
+## 快速上手（最小可用）
+
+单表单弹窗零配置——默认 modal 形态 + 宽 600 + 布局 `{span:24}`：
+
+```vue
+<ModalForm
+  v-model:show="show"
+  title="提交反馈"
+  :list="feedbackFormList"
+  :data="formData"
+  :submit-fn="submitFeedback"     <!-- resolve → 关窗 + submitSuccess -->
+  @submit-success="onSubmitSuccess"
+/>
+```
+
+**要点**：
+
+- 三必传：`show`（v-model）、`data`（表单模型数据）、`list`（form 族配置 `FormItemConfigList<PO,SO>`）
+- `submitFn` 走 ModalConfirm confirmHandler 契约：reject → 不关窗（错误留在原地展示）；resolve → 关窗 + emit `submitSuccess`（载荷 = 序列化结果）
+
+## 能力边界 / 按需使用
+
+- **默认即够用：modal 形态 + 宽 600 + 布局 `{span:24}` + 带分割线**——常规单表单弹窗（新增反馈/编辑资料）只传 `show`/`data`/`list`/`submitFn`。
+- `layerType="drawer"`：仅当表单需要抽屉形态（侧滑、大尺寸表单）时开；`direction` 仅 drawer 生效。
+- `formLayout`/`formRowGutter`/`labelWidth`/`formProps`：默认即够用；仅当表单需要栅格布局（span 分栏）、紧凑排列或 elForm 定制行为时配——均透传 FormMain。
+- `headerDivider`/`footerDivider`：ModalForm 族默认 `true`（带分割线，与 ModalConfirm 默认相反）；仅需关掉时显式传 `false`。
+- `#header`/`#footer` 插槽：仅当需要整体替换头部/底部区域时用。
+- **完整能力演示**（独立原语 + 双形态 + 分割线切换）：`apps/reference/src/pages/modal/form-modal/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（类型 `ModalFormProps<PO,SO>`）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必传） | — | 可见性 |
+| `data` | `PO`（必传） | — | 表单模型数据 |
+| `list` | `FormItemConfigList<PO,SO>`（必传） | — | 表单配置（form 族类型） |
+| `submitFn` | `(data: ExtractFormStringifyFromObject<PO,SO>) => Promise<any>\|any`（必传） | — | 提交方法；走 ModalConfirm confirmHandler 契约：reject → 不关窗 / resolve → 关窗 + emit submitSuccess |
+| `title` | `string \| (() => VNode[])` | — | 标题（透传 ModalConfirm） |
+| `width` | `number \| string` | `600` | 宽度 / drawer 尺寸 |
+| `layerType` | `ModalLayerType` | `"modal"` | 弹层形态 |
+| `direction` | `ModalDirection` | `"rtl"` | drawer 方向 |
+| `formLayout` | `FormMainProps<PO,SO>["layout"]` | `{span:24}` | 表单整体布局 |
+| `formProps` | `Partial<FormProps>` | — | elForm 其他属性 |
+| `formRowGutter` | `number` | — | 表单行 gutter |
+| `labelWidth` | `string` | `"auto"` | 表单 label 宽度 |
+| `headerDivider` | `boolean` | `true` | header 分割线（ModalForm 族默认带） |
+| `footerDivider` | `boolean` | `true` | footer 分割线 |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:show` | `boolean` | 可见性同步（v-model） |
+| `submitSuccess` | `data: FormMain 序列化结果` | 提交成功（submitFn resolve 后） |
+
+### Slots
+
+| 槽 | 语义 |
+| --- | --- |
+| `#header` | 头部（映射到 ModalConfirm 的 main-header） |
+| `#footer` | 底部（映射到 ModalConfirm 的 main-footer） |
+
+### Expose
+
+无。内部持有 FormMain 实例走 validate → stringify → submitFn；`show` 变 false 时 `clearValidate()`。
+
+## 反模式 / 注意
+
+- **submitFn 别忘 Promise 语义**：返回 `false` 或 reject 都会**不关窗**——写同步返回时注意别让 falsy 值意外吞掉关闭（走 ModalConfirm confirmHandler 契约）
+- **`data` / `list` 必传缺一即崩**：类型必传，运行时也依赖二者驱动 FormMain
+- **分割线默认与 ModalConfirm 相反**：ModalForm 族默认 `true`（带分割线）；想在 ModalConfirm 内自绘表单时注意两族默认不一致
+- **序列化后提交**：`submitFn` 收到的是 `ExtractFormStringifyFromObject<PO,SO>` 而非 PO 原形——日期/枚举等 stringify 转换先发生
+- **宽度默认 600 而非 420**：表单弹窗默认更宽，别按 ModalConfirm 默认想当然
+
+## 关联
+
+- 外壳：`ModalConfirm`（Promise 契约 / 分割线 / $attrs 透传语义同源）
+- 表单引擎：`FormMain`（form 族，`formLayout`/`formProps` 等均透传）
+- CRUD 预设：`ModalDetail`（内部强制 `headerDivider:false`/`footerDivider:false` 委托本组件）
+- 命令式弹窗体系：`ModalShelf` + `ModalPorter`（ModalForm 亦可作 modalList item）
+- 范式页：`apps/reference/src/pages/modal/form-modal/showcase/`

package/src/components/modal/docs/README-ModalPorter.md

@@ -0,0 +1,92 @@
+# ModalPorter（弹窗注册表·命令式拉起）
+
+> 弹窗注册表：`modalList` 声明 key → 组件 → 架子，`evoke(key, payload)` 命令式拉起；nsKey 命名空间 + 失活/卸载自动清理。
+> 范式页：`apps/reference/src/pages/modal/porter/showcase/`（三层自定义架子 + 触发按钮组）、`apps/reference/src/pages/modal/guide/`（对接内置 page 架子）
+
+## 定位
+
+- **何时用**：代码任意位置需要命令式拉起弹窗（列表行操作、深层组件内触发），且弹窗有「开弹窗」层级诉求时
+- **何时不用**：模板内直接挂载的弹窗（`v-model:show` 声明式）不需要 Porter；无嵌套的单层弹窗直接用 ModalConfirm/ModalForm/ModalDetail
+- 职责边界：Porter 是「注册表 + 拉手」——`modalList` 把 key 与弹窗组件/懒工厂/架子绑定，`evoke` 沿 key 查表拉起并把 payload 注入弹窗 props；弹窗实例落在 ModalShelf 架子上
+- 命名空间：每个 Porter 实例的注册 key 会被包装为 `p{porterUid}:{key}`——多 Porter 实例同 key 不互踩
+
+## 快速上手（最小可用）
+
+对接内置 page 架子（`modal/guide/config.tsx`——`shelf` 传字符串 `"page"` 即指 AppPage 内置架子）：
+
+```ts
+const modalList: RegisterEntry[] = [
+  { key: "standardDetailSpace", component: () => import("./modal/Index.vue"), shelf: "page" },
+];
+```
+
+**要点**：
+
+- `modalList` 注册项：`{key, component | 懒工厂, shelf, sameKeyStrategy?}`——`shelf` 传 `"app"`/`"page"` 字符串寻址内置架子，custom 级传 `ShelfInstance`（ref 的架子实例）
+- `evoke(key, payload)`：key 必须在 `ModalShelfMap` 声明合并中注册（类型化），payload 形状全链推导；未配置的 key 或找不到架子 → `console.error` + 返回 `null`
+- 弹窗组件侧声明 `ModalInjectedProps<P>`：`{show, closeFn, removeFn, payload}`——show 受架子控，closeFn 挂 `onUpdate:show` 即可命令式关闭
+- 生命周期：Porter 失活/卸载时自动 remove 本 porter 注册的全部 nsKey（useActivated 统一收口）——**[MUST NOT]** 手动补偿清理
+
+## 能力边界 / 按需使用
+
+- **默认即够用：对接内置 page 架子**——列表行操作/深层组件内命令式拉起，`shelf: "page"` 即指 AppPage 内置架子，零自定义架子。
+- **懒工厂按需**：`component: () => import(...)` 按需加载（推荐默认）；仅当弹窗必须随页面首屏就位时才直接传组件对象。
+- `sameKeyStrategy`：默认 `"recreate"`（同 key 再 evoke 关旧重建）即够用；`"update"`（已开则整体替换 props 不 remount）仅当同 key 弹窗需要原位刷新数据时选。
+- `shelf: "custom"`：仅当 app/page 两层不够（第三层以上）时才传 `ShelfInstance` 自建 custom 架子（判据见 ModalShelf 能力边界）。
+- **完整能力演示**（三层自定义架子 + 触发按钮组 + 多 key 注册）：`apps/reference/src/pages/modal/porter/showcase/`、`apps/reference/src/pages/modal/guide/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `modalList` | `RegisterEntry[]`（必传） | — | 弹窗注册表（key → component/懒工厂 → shelf → sameKeyStrategy） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| 默认 | 无 | 页面内容透传 |
+
+### Expose
+
+| 成员 | 签名 | 语义 |
+| --- | --- | --- |
+| `evoke` | `<K extends keyof ModalShelfMap>(key: K, payload: ModalShelfMap[K]) => EvokeHandle \| null` | 按 key 拉起弹窗（payload 类型全链推导）；未配置/找不到架子 → console.error + null |
+
+## 机制
+
+### modalList 注册表寻址
+
+`RegisterEntry<K>`：`{key, component | 懒工厂, shelf: "app"|"page"|ShelfInstance, sameKeyStrategy?}`——setup 期同步 inject app/page 控制器并缓存；`shelf:"app"`/`"page"` 字符串寻址内置架子，custom 经 `ShelfInstance` ref 直取。懒工厂写法 `() => import("./modal/Index.vue")` 按需加载。
+
+### nsKey 命名空间
+
+每个 Porter 实例把注册 key 包装为 `p{porterUid}:{key}`——多 Porter 实例（多页面/多架子）同 key 不互踩；evoke/remove 都以命名空间后的 nsKey 寻址，业务无需感知。
+
+### 卸载自动清理
+
+失活/卸载时自动 remove 本 porter 注册的全部 nsKey（useActivated 统一收口）——Porter 销毁即弹窗实例随架清理，**[MUST NOT]** 手动补偿清理。
+
+### 注入给弹窗的 props（`ModalInjectedProps<P>`）
+
+架子把 `{show, closeFn, removeFn, payload: P}` 注入弹窗组件（见 ModalShelf 文档）。
+
+## 反模式 / 注意
+
+- **未注册 key 是静默失败面**：`evoke` 返回 null + console.error——消费侧 [MUST] 判空（`evoke(...)?.close()` 或先判 null），别假设一定成功
+- **shelf 字符串只认 "app"/"page"**：custom 架子必须传 `ShelfInstance`（ref 实例），传字符串进 custom 寻址不通
+- **key 类型必须声明合并**：evoke 的 key 泛型约束 `keyof ModalShelfMap`——业务 [MUST] 在 `.d.ts` 里 declare module 扩展 `ModalShelfMap`（见 ModalShelf 文档），否则 key 不在 map 上 TS 直接拦截
+- **自动清理别补偿**：Porter 失活/卸载已自动 remove 全部 nsKey，手写 `onUnmounted` 清理是重复劳动（也可能提前清掉活跃弹窗）
+- **弹窗 UI 不在 Porter 插槽里写**：Porter 只是注册表宿主，弹窗经 evoke 落在架子上渲染——插槽只放页面内容
+
+## 关联
+
+- 架子宿主：`ModalShelf`（level 层级 + ModalShelfMap declare merge + evoke/remove/close + sameKeyStrategy）
+- 注入契约：`ModalInjectedProps<P>`（show/closeFn/removeFn/payload，架子注入弹窗组件）
+- 句柄：`EvokeHandle`（close / update 增量合并，不 remount）
+- 弹窗组件族：`ModalConfirm` / `ModalForm` / `ModalDetail`（作注册表 item；DetailModalItem 薄适配器范式见 `list-page/guide/`）
+- 类型：`RegisterEntry<K>`、`ModalSameKeyStrategy`（"recreate" 默认 / "update" 整体替换 props 不 remount）
+- 范式页：`apps/reference/src/pages/modal/porter/showcase/`、`apps/reference/src/pages/modal/guide/`

package/src/components/modal/docs/README-ModalShelf.md

@@ -0,0 +1,115 @@
+# ModalShelf（弹窗架子·层级治理）
+
+> 弹窗架子：`level` 声明结构性身份（app/page/custom），沿 DOM 收集祖先并断言层级合法，为 ModalPorter 提供命令式注册表宿主。
+> 范式页：`apps/reference/src/pages/modal/porter/showcase/`（三层自定义嵌套架子 + ModalPorter）、`apps/reference/src/pages/modal/guide/`（对接内置 page 架子）
+
+## 定位
+
+- **何时用**：应用出现「弹窗开弹窗」的层级诉求时，用架子显式声明弹层寄居层级——AppLayout/AppPage 已内置 app/page 两层，业务只在需要第三层以上或自定义作用域时手挂 `level="custom"` 架子
+- **何时不用**：单层弹窗（无嵌套）不需要架子——直接用 ModalConfirm/ModalForm/ModalDetail；也不需要在 AppLayout/AppPage 内再挂 app/page 级架子（内置，业务 [MUST NOT] 自声明）
+- 职责边界：架子只管「身份 + 层级合法性 + 实例注册表宿主」，**不渲染弹窗 UI**——弹窗由 ModalPorter 的 modalList 注册表经 `evoke` 命令式拉起，页面内容走默认插槽透传
+
+## 快速上手（最小可用）
+
+对接内置 page 架子——普通业务**零架子起步**，页面只放 Porter 注册表（`modal/guide/`）：
+
+```vue
+<AppPage>
+  <!-- ...页面内容... -->
+  <ModalPorter :modalList="modalList" />   <!-- modalList 项 shelf: "page" 即指本架子 -->
+</AppPage>
+```
+
+**要点**：
+
+- 内置挂载（业务 [MUST NOT] 自声明）：AppLayout.vue 内置 `level="app"`、AppPage.vue 内置 `level="page"`——单层/双层弹窗零架子
+- 控制器：`evoke(nsKey, component, {payload, sameKeyStrategy?})` 拉起 / `remove(nsKey|string[])` 移除 / `close(item)` 关闭——经 `ShelfController` expose 暴露，ModalPorter 内部自动对接
+- `level` 是**架子结构性身份**：挂载后不变（setup 期快照非响应式），传给控制器 / 注册表寻址用
+
+## 能力边界 / 按需使用
+
+- **默认即够用：内置 app/page 两层架子**——普通业务零架子起步；单层弹窗（无嵌套）连架子都不需要，直接用 ModalConfirm/ModalForm/ModalDetail。
+- `level="custom"`：**仅当需要第三层以上或自定义作用域的弹窗层级时**才手挂（判据：app/page 两层装不下「弹窗开弹窗开弹窗」）。custom 可任意嵌套，业务一般一层够用。
+- 业务 [MUST NOT] 在 AppLayout/AppPage 内再挂 app/page 级架子（内置，重复挂载是层级污染）；page 上禁挂 custom（非法挂法，开发期 console.error）。
+- 层级合法性只在开发期校验：非法挂法只警告不崩，但生产仍会弹窗乱叠——守合法挂法是业务责任。
+- **完整能力演示**（三层自定义嵌套架子 + Porter 触发按钮组）：`apps/reference/src/pages/modal/porter/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `level` | `ModalLevel = "app"\|"page"\|"custom"`（必传） | — | 架子结构性身份，挂载后不变（setup 期快照非响应式） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| 默认 | 无 | 页面内容透传 |
+
+### Expose（`ShelfController`）
+
+| 成员 | 签名 | 语义 |
+| --- | --- | --- |
+| `level` | `ModalLevel` | 架子层级 |
+| `evoke` | `(nsKey, component, {payload, sameKeyStrategy?}) => EvokeHandle` | 命令式拉起弹窗（nsKey 定位 / component 注册 / payload 注入） |
+| `remove` | `(nsKey \| string[]) => void` | 按 nsKey 移除一个/多个实例 |
+| `close` | `(item: ShelfItem) => void` | 关闭指定活跃实例 |
+
+> ⚠️ expose 实际另含 `items: Ref<ShelfItem[]>`（内部渲染用活跃实例列表；公开类型 `ShelfController` 不含——按公开类型使用）
+
+## 机制
+
+### level 层级与合法性断言
+
+`provide(getModalShelfInjectionKey(level), controller)`；onMounted 沿 `["app","page","custom"]` 收集祖先并 `assertLevelHierarchy`：
+
+- `app` 必最顶层
+- `page` 上仅禁 `custom`（允许 page 套 page）
+- `custom` 可任意嵌套
+
+非法挂法仅开发期 `console.error`，不阻断运行。
+
+### ModalShelfMap declare merge（全链类型化）
+
+业务侧在 `.d.ts` 里对 `@done-coding/admin-core` 的 `ModalShelfMap` 空 interface 做声明合并扩展，evoke 与弹窗 props 全链类型化（`apps/reference/src/types/standard-modal.d.ts`）：
+
+```ts
+declare module "@done-coding/admin-core" {
+  interface ModalShelfMap {
+    /** 范式 A 列表弹窗式 CRUD：DetailModal 作 modalList item 的 payload */
+    standardListDetail: { type: DetailType; data: UserPO; onDone?: () => void };
+    standardDetailSpace: { id: number; onDone?: () => void };
+    standardTabListDetail: { type: DetailType; data: UserPO; subTitle: string; onDone?: () => void };
+  }
+}
+```
+
+每个 key 的值类型 = 该弹窗的 payload 形状（注入给弹窗组件的 `payload` prop 全类型化）。
+
+### 注入给弹窗的 props（`ModalInjectedProps<P>`）
+
+架子把 `{show, closeFn, removeFn, payload: P}` 注入弹窗组件——弹窗组件声明接收，`show` 由架子受控、`closeFn`/`removeFn` 是命令式关闭出口、`payload` 为业务数据。
+
+### 命令式句柄（`EvokeHandle`）
+
+`evoke` 返回 `EvokeHandle`：`close()` 关闭、`update(partialPayload)` 增量合并更新 payload（不 remount）。
+
+## 反模式 / 注意
+
+- **业务 [MUST NOT] 自声明 app/page 架子**：AppLayout/AppPage 已内置，重复挂载是层级污染
+- **`level` 快照非响应式**：挂载后改 level 不生效——架子身份在挂载时刻定死，需要不同层级另起架子
+- **架子不渲染弹窗 UI**：只是宿主，弹窗实例由 ModalPorter evoke 拉起——别在架子插槽里手写 `<ModalConfirm>` 混编（破坏注册表寻址）
+- **`sameKeyStrategy` 语义别与 EvokeHandle.update 混淆**：`"recreate"`（同 key 再 evoke 关旧重建，默认）vs `"update"`（已开则整体替换 props 不 remount）；而 `EvokeHandle.update` 是**增量合并**（partialPayload）——三条路径语义各不相同
+- **page 上禁挂 custom**：page 架子内嵌 custom 架子属非法挂法（开发期报错）；要三层以上请自建 custom 链
+- **层级合法性只在开发期校验**：生产不报错，但挂法错误导致的弹窗乱叠仍会存在——守合法挂法是业务责任
+
+## 关联
+
+- 注册表入口：`ModalPorter`（modalList 注册表，内部自动对接 app/page 控制器并缓存）
+- 层级机制：`modal-shelf-hierarchy.ts`（assertLevelHierarchy 合法挂法断言）、`modal-shelf-core.ts`（实例注册表）、`modal-shelf-types.ts`（ModalLevel / ModalSameKeyStrategy / ShelfController / ShelfItem / ShelfInstance / EvokeHandle / RegisterEntry）
+- 内置挂载点：`AppLayout.vue`（level="app"）、`AppPage.vue`（level="page"）
+- 弹窗组件族：`ModalConfirm` / `ModalForm` / `ModalDetail`（可作架子注入的弹窗组件）
+- 范式页：`apps/reference/src/pages/modal/porter/showcase/`、`apps/reference/src/pages/modal/guide/`

package/src/components/panel/README.md

@@ -0,0 +1,19 @@
+# panel 面板族
+
+配置驱动详情面板：`PanelMain` 消费 `PanelItemConfig` 列表，只读渲染 + 就地编辑（editorConfig / editorRender 三分支）+ 嵌套（C2 / C3）。
+
+> ⚠️ **`PanelMain` 一等公民地位撤销 · 将废弃**：页级纯展示场景将由 `ViewLayout`（展示布局组件，后续迭代）承接——PanelMain 定位为 ViewLayout 默认插槽内容 / 表单预览与就地编辑场景保留。新页面 [MUST NOT] 以 PanelMain 作页级展示根容器；存量页面仅预览/编辑态保留使用。
+
+## 组件文档（docs/）
+
+- [PanelMain](./docs/README-PanelMain.md) — 详情面板（含 PanelItem 关键配置 PanelItemConfig 与编辑态三分支）
+
+## 关键类型与 helper
+
+- 类型：`PanelMainProps` / `PanelItemConfig` / `PanelScopeBase` / `PanelRenderScope`（经 `./types` 导出）
+- helper：`nestPanelItem`（C2）/ `nestPanelForm`（C3）——与 editorConfig 互斥，同一 item [MUST NOT] 同配
+- ⚠️ `itemCard` 默认不套卡片（旧默认已移除，breaking）
+
+## 范式页（apps/reference）
+
+- `/panel/panel-main/showcase`（editorConfig / editorRender / scope.refresh）/ `/panel/nest-panel/showcase`（C2/C3）/ `/panel/nest-layout-rebase`（P3 rebase）