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

package/src/components/panel/docs/README-PanelMain.md

@@ -0,0 +1,149 @@
+# PanelMain（配置化面板）
+
+> 配置驱动的字段面板：`PanelItem` 逐项渲染，只读展示 + 就地编辑（`editorConfig` 内嵌表单提交 / `editorRender` 自管提交 / `nestPanelForm` 编辑态子表单 / `nestPanelItem` 只读子面板）全链路。
+> 范式页：`apps/reference/src/pages/panel/panel-main/showcase/`、`pages/panel/nest-panel/showcase/`
+
+## 定位
+
+- ⚠️ **将废弃（一等公民地位撤销）**：页级纯展示场景由 `ViewLayout`（展示布局，后续迭代）承接——PanelMain 定位为 ViewLayout 默认插槽内容；**表单预览 / 就地编辑场景保留**。新页面 [MUST NOT] 以 PanelMain 作页级展示根容器
+- **何时用（存量保留场景）**：表单预览 / 就地编辑（配置驱动逐项渲染，单开互斥）
+- **何时不用**：页级纯展示用未来 `ViewLayout`（其默认插槽内放 PanelMain）；纯表格用 `TableMain`；多字段整体录入表单用 `FormMain`；列表 + 录入用 `ListPage`
+- 内部组合：`ElRow` / `ElCol` 栅格承载逐项 `PanelItem`；编辑态**单开互斥**（打开一项自动清空其余）
+- 行为：`list` 变化时修剪 `editingMap`；卡片与裸排分别加 `panel-main-item-col-wrap_card` / `_plain` class
+
+## 快速上手（最小可用）
+
+只读详情面板零配置——两必传即得纯展示字段面板（`panel-main/showcase/Index.vue` 范式 A 摘要）：
+
+```vue
+<PanelMain :data="data" :list="list" />
+```
+
+**要点**：
+
+- 两必传：`data`（序列化 SO 形态数据源）、`list`（`PanelItemConfigList<PO,SO>` 配置项数组）
+- 默认只读展示：item 未配 `editable` 时纯展示，`render` 缺省纯文本 `data[key]`，默认栅格 `{span:24}` 裸 div 包裹
+
+## 能力边界 / 按需使用
+
+- ⚠️ **将废弃**：页级展示场景将由 `ViewLayout`（后续迭代）承接——新页面 [MUST NOT] 以 PanelMain 作页级展示根容器（纯展示场景：待 ViewLayout 落地后以 PanelMain 为其默认插槽内容）
+- **存量保留场景**：表单预览 / 就地编辑——只传 `data`/`list` 即得纯展示字段面板（`ViewLayout` 插槽内用法同此）。
+- `editable` + `editorConfig`：**仅当某项需要就地编辑时**配（内嵌 FormSubmitPanel，自带取消/重置/提交 + parse/stringify，提交成功自动退编辑并冒泡 `submitSuccess`）——且 [MUST] 同配 `submitFn`（editable 无 submitFn 提交会 throw）。
+- `editorRender`：优先级高于 editorConfig，**无内置按钮、消费方自管提交**——仅当编辑交互需完全自绘时用；与 `editorConfig` 互斥，同一 item [MUST NOT] 同配。
+- `nestPanelForm`/`nestPanelItem`：仅当详情面板需要嵌套子表单/子面板（复合数据结构）时用。
+- `itemCard`：默认不套卡片（裸 div `_plain`）；仅当需要每项卡片化展示时传对象/true。
+- `rowGutter`/`layout`/`layoutScale`：默认即够用；仅栅格/嵌套布局需求时配。
+- `refreshFn`：仅当 render/editorRender 内需要 `scope.refresh()` 旁路刷新时传（不承接 editorConfig 提交成功——那走 `submitSuccess`）。
+- **完整能力演示**（editorConfig 基础提交 + editorRender 自管 + 嵌套表单/面板 + 卡片化）：`apps/reference/src/pages/panel/panel-main/showcase/`、`apps/reference/src/pages/panel/nest-panel/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `PO` 解析 / `SO` 格式化）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `data` | `ExtractFormStringifyFromObject<PO, SO>`（必填） | — | 序列化（SO）形态的数据源，render/editable 回调的 scope.data |
+| `list` | `PanelItemConfigList<PO, SO>`（必填） | — | 配置项数组，逐项渲染 PanelItem |
+| `rowGutter` | `number` | `8` | 行水平间距（ElRow :gutter） |
+| `layout` | `Partial<ColProps>` | `() => ({ span: 24 })` | 缺省栅格，item 未配 layout 时继承；经 resolveFormLayout(layout, scale) 与 layoutScale 相乘 |
+| `layoutScale` | `number` | `1` | P3 嵌套布局 rebase 累乘因子；同时 provide NEST_LAYOUT_SCALE_KEY 给后代 |
+| `itemCard` | `boolean \| Partial<CardProps & { lastMarginBottom?: string }>` | 无默认 | 是否给每项包 ElCard；对象态可配 lastMarginBottom。⚠️ 旧默认 `{lastMarginBottom:'8px'}` 已移除（breaking，现在默认不套卡片） |
+| `refreshFn` | `(currentStringifyData: any, key: string) => Promise<unknown> \| void` | — | render/editorRender 内 scope.refresh() 的旁路刷新回调；不承接 editorConfig 提交成功（那走 submitSuccess） |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `submitSuccess` | `(currentStringifyData: FormDataInfo<PO,SO>["stringifyData"], key: string)` | 编辑提交成功（key 标识哪项） |
+
+### Slots
+
+无（直接内渲染 ElCol + PanelItem）
+
+### Expose
+
+无
+
+### PanelItem 关键配置（`PanelItemConfig<PO, SO>`）
+
+| 字段 | type | 语义 |
+| --- | --- | --- |
+| `key` | `string`（必填） | 数据键 |
+| `label` | `string?` | 标签文本 |
+| `labelHide` | `boolean?` | 展示态隐藏标签（编辑态 label 已由 PanelItem 层接管并强制 `labelHide: true`） |
+| `labelStyle` | `CSSProperties \| string?` | 标签元素样式 |
+| `labelPosition` | `"inline" \| "top"?` | 默认 inline；top = 上方 |
+| `layout` | `Partial<ColProps>?` | 栅格布局，缺省继承 PanelMain.layout |
+| `hide` | `boolean \| (scope: PanelScopeBase) => boolean?` | 隐藏（函数态入 scope） |
+| `render` | `string \| Record<string, any> \| ((scope: PanelRenderScope) => VNode[])?` | 只读渲染；缺省纯文本 data[key] |
+| `editable` | `boolean \| (scope: PanelScopeBase) => boolean?` | 是否可就地编辑 |
+| `editorRender` | 同 render | 编辑器渲染，优先级高于 editorConfig；此分支**无内置按钮**，消费方自管提交 |
+| `editorConfig` | `Omit<FormItemConfig<PO,SO>, "key"\|"label"\|"labelHide"\|"layout">?` | 编辑器表单配置，内嵌 FormSubmitPanel（自带取消/重置/提交 + parse/stringify），提交成功自动退编辑并冒泡 |
+| `submitFn` | `FormSubmitPanelProps["submitFn"]` | 单字段提交；draft = 深克隆副本 |
+
+作用域类型：`PanelScopeBase = { data, value: data[config.key], config }`；`PanelRenderScope` 扩展 `{ editing: boolean, refresh?: () => Promise<unknown>|void, closeEdit?: () => void }`。
+
+### PanelItem（单项容器）
+
+- props：`data`（必填）、`config: PanelItemConfig<PO, SO>`（必填）、`refreshFn: (currentStringifyData) => Promise<unknown> | void`（**无 key 参数**，key 由外层 PanelMain 注入）
+- model：`editing`（defineModel<boolean>，默认 false，支持 `v-model:editing`）
+- emits：`submitSuccess(data: stringifyData)`——注意是**合并后数据**（`{...props.data, ...data}`）
+- slots/expose：无（内部转发给 PanelEditSwitch 的 default/editor 槽）
+
+### PanelEditSwitch（编辑态切换核心）
+
+- props：`data`（必填）、`config`（`Omit<PanelItemConfig,"editorConfig"> & { editorConfig?: FormItemConfig }`，缺失 key/label 由 PanelItem 补齐）、`editable?: boolean`，另继承 `Partial<Pick<FormSubmitPanelProps, "submitFn">>`
+- model：`editing`（默认 false）
+- emits：`submitSuccess(data)`
+- slots：`default` + `#editor`（scope 均 `{ stringifyDraftData }`）
+- 行为：进编辑时 `_cloneDeep(data)` 生成草稿；`editable` 变 false 自动退编辑；`editable` 且无 `submitFn` 时提交会 throw（「可编辑 那么必须提供 submitFn」）
+
+### PanelItemNestPanel / PanelItemNestForm / Helper 函数
+
+- `PanelItemNestPanel`：内联 props `data`（必填）/ `list`（必填）/ `itemCard?` / `layout?` / `rowGutter?` / `parentSpan?`（父 item 代表 span，P3 算因子）/ `rebase?`（默认 true；false = 逆向逃生口，layout 原样直透）；无 emits/slots/expose；`inheritAttrs: false`；内部 useNestLayoutScale 叠本层因子作为子 PanelMain 的 layoutScale
+- `PanelItemNestForm`：内联 props `data`（必填，子 FormMain 数据 = 草稿嵌套对象）/ `list`（必填）/ `layout?` / `rowGutter?` / `submitText?`（默认「提交」）/ `cancelText?`（默认「取消」）/ `submit?: () => Promise<unknown> | unknown`（校验通过后的业务提交，返 Promise 自动 loading）/ `cancel?: () => void` / `parentSpan?` / `rebase?`（默认 true）；无 emits/slots/expose；`inheritAttrs: false`；提交先 `validateChild()`，reject 留在编辑态
+- `nestPanelItem(options: NestPanelItemOptions): PanelItemConfig` — 生成「父 item 内嵌子 PanelMain」的**只读**配置项。NestPanelItemOptions：`key`（必填）、`label?`、`list: PanelItemConfigList`（必填）、`layout?`、`itemCard?`、`rowGutter?`、`rebase?`（默认 true）。render 出口挂 PanelItemNestPanel，`scope.value ?? {}` 作子 data
+- `nestPanelForm(options: NestPanelFormOptions): PanelItemConfig` — 生成「编辑态挂子 FormMain」的配置项。NestPanelFormOptions：`key`（必填）、`label?`、`list: FormItemConfigList`（必填）、`layout?`、`rowGutter?`、`submitText?`、`cancelText?`、`editable?: boolean | fn`（默认 true）、`submitFn`（**必填**，校验通过后 submitFn(草稿) → closeEdit 回流）、`render?`（只读态回退）、`rebase?`（默认 true）。⚠️ 走 `editorRender` 分支——与 `editorConfig` 互斥，同一 item [MUST NOT] 同配
+
+C3 用例（`nest-panel/showcase/Index.vue`——编辑态挂子 FormMain + 内嵌 C1，多层校验闭环）：
+
+```ts
+nestPanelForm({
+  key: "address",
+  label: "地址（C3：编辑态挂子 FormMain + 内嵌 C1，多层校验闭环）",
+  list: addressFormList,
+  render: ({ value }) => {
+    const addr = value as DemoAddress | undefined;
+    return (
+      <span style="color:#409eff">
+        {addr?.province} / {addr?.city} · 联系人 {addr?.contact?.name}
+      </span>
+    );
+  },
+  submitFn: (draft) =>
+    new Promise<void>((resolve) => {
+      setTimeout(() => {
+        data.value = { ...(draft as unknown as DemoData) };
+        successCount.value += 1;
+        resolve();
+      }, 300);
+    }),
+}),
+```
+
+## 反模式 / 注意
+
+- **同 item 同配 `editorRender` 与 `editorConfig`**：[MUST NOT]——互斥（nestPanelForm 走 editorRender 分支）
+- **编辑态多开**：PanelMain 单编辑态互斥（打开一项清空其余），[MUST NOT] 试图手动多开
+- **动态改 list**：`list` 变化时 `editingMap` 会被修剪，进行中的编辑态可能被清
+- **itemCard 默认不套卡片**（breaking）：需卡片态显式传对象/true；裸排（undefined → `_plain` class）是默认
+- **refreshFn 与 submitSuccess 分工**：refreshFn 只承接 render/editorRender 内 scope.refresh() 的旁路刷新；editorConfig 提交成功走 submitSuccess，[MUST NOT] 期待 refreshFn 接收
+- **editable 无 submitFn**：提交会 throw——`editable` [MUST] 配 `submitFn`
+
+## 关联
+
+- 内部组件：`PanelItem` / `PanelEditSwitch` / `PanelItemNestPanel` / `PanelItemNestForm`（同族）
+- 表单引擎：`FormItemConfig`（form 族）、`FormSubmitPanel`（内嵌编辑器）
+- 嵌套布局：`layoutScale` / NEST_LAYOUT_SCALE_KEY（P3 嵌套布局 rebase 累乘链）
+- 范式页：`apps/reference/src/pages/panel/panel-main/showcase/`、`pages/panel/nest-panel/showcase/`

package/src/components/slot-layout/README.md

@@ -0,0 +1,17 @@
+# slot-layout 插槽布局族
+
+以槽位驱动的轻量布局族：`SlotLayoutTemplate`（透明转发包裹器）+ `SlotLayoutFlowAside`（主区 / 侧栏流式布局，内部基于 SlotLayoutTemplate 组合）。
+
+## 组件文档（docs/）
+
+- [SlotLayoutTemplate](./docs/README-SlotLayoutTemplate.md) — 透明转发包裹器（tag 宿主 + 全槽转发 + disabled 透传）
+- [SlotLayoutFlowAside](./docs/README-SlotLayoutFlowAside.md) — 主区 + 侧栏布局（v-model:separate 分离态）
+
+## 关键类型
+
+- `SlotLayoutFlowAsideProps`（type / gap / asideWidth / asideMaxHeight 四键，types.ts 导出）
+- 内部不导出：无（SlotLayoutTemplate 零类型导出，props 直声明于组件）
+
+## 范式页（apps/reference）
+
+- `/slot-layout/showcase`（全 props + 双示例：单槽包裹 / 具名 + 作用域槽全转发）

package/src/components/slot-layout/docs/README-SlotLayoutFlowAside.md

@@ -0,0 +1,83 @@
+# SlotLayoutFlowAside（主区 + 侧栏流式布局）
+
+> 「主区 + 侧栏」双槽流式布局：默认槽为主区、`#aside` 为侧栏；`v-model:separate` 切换分离态（侧栏 absolute 定位 + 主区 padding 让位）。
+> 范式页：`apps/reference/src/pages/slot-layout/showcase/Index.vue`
+
+## 定位
+
+- **何时用**：页面 / 卡片内部需要「主区 + 侧栏」双区布局，且要求侧栏在分离态下绝对定位、主区自动让位
+- **何时不用**：整页级左右布局交给 app-layout 族（AppSidebar / AppAside）；只差一个静态侧栏时直接写两列 flex
+- 内部组合：基于 `SlotLayoutTemplate` 组合（两侧各一个实例），非分离态下不做 absolute、不占位让位
+- 分离态行为：`type` 决定侧栏贴左 / 贴右；`asideWidth` 控制侧栏宽；`asideMaxHeight` 限高、超出滚动；主区 padding 为侧栏让位（含 -1px 亚像素补偿）
+- 消费方：ListPage `separateSearch`（搜索 / header / 操作区整体移入侧栏）即基于本组件
+
+## 快速上手（最小可用）
+
+默认值即够用——侧栏贴右、240px 宽、常规文档流：
+
+```html
+<SlotLayoutFlowAside>
+  <template #aside>侧栏</template>
+  主区
+</SlotLayoutFlowAside>
+```
+
+需要分离态时 `v-model:separate` 切换：
+
+```html
+<SlotLayoutFlowAside v-model:separate="separate">
+  <template #aside>侧栏（absolute 定位）</template>
+  主区（padding 让位）
+</SlotLayoutFlowAside>
+```
+
+**要点**：
+
+- `v-model:separate`：true = 分离态（侧栏 absolute 定位 + 主区 padding 让位）；false = 常规文档流，无 absolute、无让位
+- `type` 决定侧栏贴左 / 贴右；侧栏宽由 `asideWidth` 控制
+
+## 能力边界 / 按需使用
+
+- **`v-model:separate`：默认 `false`（常规文档流）即够用。** 仅当侧栏需要「绝对定位脱离文档流 + 主区自动让位」才开分离态——判据：侧栏内容超高需独立滚动、且不挤占主区布局（ListPage `separateSearch` 把搜索 / header / 操作区整体移入侧栏即此场景）。
+- **`type` / `gap` / `asideWidth`：默认贴右 / `12px` / `240px` 即够用。** 仅当侧栏要贴左、间距或宽度与默认不同才显式传。
+- **`asideMaxHeight`：默认 `100vh` 即够用（容器内实际取 `min(100%, 100vh)`）。** 仅当容器超高、需要限高承接侧栏滚动才显式限高——判据：侧栏内容比容器高且要独立滚动（超高滚动依赖分离态 + `asideMaxHeight`，两者缺一不可）。
+- **完整能力演示**（全 props 分离态互动面板）：`apps/reference/src/pages/slot-layout/showcase/Index.vue`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（`SlotLayoutFlowAsideProps`，types.ts 导出）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `type` | `"left" \| "right"` | `"right"` | 侧栏所在侧 |
+| `gap` | `string` | `"12px"` | 主区与侧栏间距 |
+| `asideWidth` | `string` | `"240px"` | 侧栏宽度 |
+| `asideMaxHeight` | `string` | `"100vh"` | 侧栏最大高度（超出滚动） |
+
+### Emits
+
+无（`v-model:separate` 走 defineModel）
+
+### Slots
+
+| 槽 | 语义 |
+| --- | --- |
+| `default` | 主区 |
+| `#aside` | 侧栏 |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **非分离态下期待 absolute 行为**：`v-model:separate=false` 时侧栏与主区走常规文档流（垂直排布、无让位），绝对定位只在分离态生效
+- **容器级忘给 asideMaxHeight**：默认 `100vh` 在容器内实际取 `min(100%, 100vh)`，容器超高场景记得显式限高（如上例 `320px`）
+- **侧栏超高溢出**：超高滚动依赖分离态 + `asideMaxHeight`，两者缺一不可
+
+## 关联
+
+- 内部基石：`SlotLayoutTemplate`（slot-layout 族）
+- 消费方：`ListPage` `separateSearch`（list-page 族）
+- 范式页：`apps/reference/src/pages/slot-layout/showcase/Index.vue`

package/src/components/slot-layout/docs/README-SlotLayoutTemplate.md

@@ -0,0 +1,73 @@
+# SlotLayoutTemplate（透明转发包裹器）
+
+> 以 tag 为宿主包裹内容并「透明转发全部插槽」（默认 + 具名 + 作用域）到宿主的布局槽位模板；disabled 时宿主消失、只渲染默认槽内容。
+> 范式页：`apps/reference/src/pages/slot-layout/showcase/`（ⓑ 节单槽包裹 / ⓒ 节具名 + 作用域槽全转发）
+
+## 定位
+
+- **何时用**：需要一个「可开关的包裹宿主」——宿主在时把默认 / 具名 / 作用域槽整体转交给 tag 渲染，宿主不在时退化为纯内容渲染
+- **何时不用**：需要自定义插槽编排 / 命名转换时直接用普通 `<component :is>` + `<slot>`；需要「主区 + 侧栏」双区布局用 `SlotLayoutFlowAside`
+- 实现：Options API `defineComponent` + render 函数（`h(tag, attrs, slots)`）——render 直接把 slots 对象整体喂给 `h()`，绕开模板 slot 类型推断，转发更彻底（含具名 / 作用域槽）
+- 内部基石：`SlotLayoutFlowAside` 基于它组合（两侧各一个实例）
+
+## 快速上手（最小可用）
+
+默认 `tag="div"` 即够用——包裹 + 透明转发零配置：
+
+```html
+<SlotLayoutTemplate>
+  包裹内容
+</SlotLayoutTemplate>
+```
+
+需要「宿主可开关」时（核心场景）加 `disabled`：
+
+```html
+<SlotLayoutTemplate :disabled="tplDisabled">
+  宿主消失时这里的内容直接渲染
+</SlotLayoutTemplate>
+```
+
+**要点**：
+
+- 宿主 `tag` 可传原生标签名（`"div"`）/ 组件对象 / 函数式组件；懒加载组件 [MUST] 先经 `defineAsyncComponent` 包裹再传——裸异步工厂 `() => import("./X.vue")` 会被当函数式组件调用、不 resolve Promise
+- `inheritAttrs: false`：attrs 整包转发宿主 tag，不落在本组件根上
+
+## 能力边界 / 按需使用
+
+- **透明转发全部插槽（默认 + 具名 + 作用域）：默认即全量生效，是本组件的核心能力，零配置。** 组件存在的全部意义就是把 slots 对象整体交给宿主 tag 渲染——常规包裹使用不需要任何开关。
+- **`disabled`：默认 `false`（恒包裹）即够用。** 仅当「宿主存在与否需要运行时切换」（如工具栏按开关决定是否包布局根）才管理该值——判据：宿主在时套布局、宿主不在时退化为纯内容渲染，二者由同一个开关切换。注意 disabled 态只保默认槽（具名槽无落点，属透传语义固有边界）。
+- **完整能力演示**（单槽包裹 + 具名 + 作用域槽全转发）：`apps/reference/src/pages/slot-layout/showcase/`（ⓑ / ⓒ 节）——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `tag` | `String \| Object \| Function` | `"div"` | 包裹宿主：原生标签名 / 组件对象 / 函数式组件（懒加载组件须先经 `defineAsyncComponent` 包裹） |
+| `disabled` | `boolean` | `false` | true = 透传态（宿主消失、只渲染默认槽内容） |
+
+### Emits
+
+无
+
+### Slots
+
+透明转发全部插槽（默认 + 具名 + 作用域）到宿主 tag；disabled 时仅默认槽。
+
+### Expose
+
+无（`inheritAttrs: false`，attrs 转发宿主）
+
+## 反模式 / 注意
+
+- **裸异步工厂直传 tag**：`() => import("./X.vue")` 会被当函数式组件调用、不 resolve Promise，[MUST] 先 `defineAsyncComponent`
+- **disabled 态依赖具名槽**：宿主消失后具名槽无落点，disabled 态只保默认槽
+- **用模板实现透明转发**：模板内 v-for `$slots` + `<slot :name>` 会触发 vue-tsc TS7022 自指推断，须走 render 函数整体转发
+
+## 关联
+
+- 内部组合方：`SlotLayoutFlowAside`（slot-layout 族，基于本组件组合两侧）
+- 范式页：`apps/reference/src/pages/slot-layout/showcase/`（ⓑ / ⓒ 节）

package/src/components/table/README.md

@@ -0,0 +1,17 @@
+# table 表格族
+
+单组件族：`TableMain`——列配置 `ElTableColumnProps` 超集（render 三态）+ toolbar + refine 高度链 + 骨架屏 + fillHeight + customView 数据视图切换。
+
+## 组件文档（docs/）
+
+- [TableMain](./docs/README-TableMain.md) — 配置驱动表格（api / columns / toolbar / 高度链三选一）
+
+## 关键类型与常量
+
+- 类型：`ElTableColumnProps` / `TableToolbarConfig` / `ToolbarButtonConfig` / `TablePageInfo` / `TableApiParams` / `TableApiResult` / `TableMainInstance`（经 `./types` 导出）
+- 常量：`TABLE_COLUMN_KEY_OPERATE = "OPERATE"` / `TABLE_COLUMN_KEY_SELECTION = "SELECTION"`
+- 内部件不导出：`TableSkeleton` / `TableToolbar` / `ToolbarButtons`
+
+## 范式页（apps/reference）
+
+- `/table/toolbar`（toolbar 按钮 4 场景）/ `/table/skeleton`（骨架屏 + fillHeight）

package/src/components/table/docs/README-TableMain.md

@@ -0,0 +1,140 @@
+# TableMain（配置化数据表格）
+
+> 配置化表格：列配置（ElTableColumnProps 超集）驱动渲染 + 内置分页 / 工具栏 / 骨架屏 / 精细化布局高度链。
+> 范式页：`apps/reference/src/pages/table/toolbar/`（工具栏）、`apps/reference/src/pages/table/skeleton/`（骨架屏 + fillHeight）、`apps/reference/src/pages/list-page/guide/`（与 FormSearch 组合成列表页）
+
+## 定位
+
+- **空间一等公民是 `ListPage`**：常规列表页 [MUST] 走 `ListPage`（内部已组合 FormSearch + TableMain + 高度链 + 分页 + 粘性，常用配置提升为直属 prop；TableMain 恒收 `refine=false`）——**TableMain 一般不直接使用**
+- **直接使用仅当**：纯表格页（无搜索区）/ 嵌入卡片或面板的局部表格 / 特殊布局——此时取数/分页/工具栏/高度链全由自己负责
+- 纯展示静态表格用 ElTable 即可
+- 泛型三参：`T` 行数据类型 / `SQ` 静态查询参数 / `F` 注入对象类型；`query` 变化时重置到第 1 页重新拉取
+
+## 快速上手（最小可用）
+
+标准数据表格零配置——只传三必传即得「取数 + 分页 + 骨架屏 + 工具栏 + 布局」全默认（`table/toolbar/Index.vue`）：
+
+```vue
+<TableMain
+  ref="tableRef"
+  :api="api"
+  :columns="columns"
+  row-key="id"
+/>
+```
+
+需要工具栏按钮时配 `toolbar`（ActionBtn 配置驱动，context 消费选中列表）：
+
+```tsx
+const toolbarConfig: TableToolbarConfig<Row> = {
+  leftExtraButtons: [{ key: "batch-archive", label: "批量归档", actionBtnProps: (ctx) => ({ disabled: ctx.selectedList.length === 0, onClick: () => { /* ctx.selectedList 消费 */ } }) }],
+};
+```
+
+```vue
+<TableMain ref="tableRef" :api="api" :columns="columns" row-key="id" :toolbar="toolbarConfig" />
+```
+
+**要点**：
+
+- 三必传 `api`/`columns`/`rowKey`；`api` 收到的是 `query` 深合并 `page.page/page.pageSize` 后的参数（键名由 `APP_API_LIST_MODEL_KEY_CONFIG` 单源定义），返回 `TableApiResult<T>` 的 `items` + `page.totalRecord` 子集
+- 增删改后的刷新：`refresh()`（当前页重拉）或 `reload()`（回第 1 页重拉，已在第 1 页则等同 refresh）；keepAlive 返回刷新由 core 内置承担（onActivated 自动 refresh 留页码）——**[MUST NOT]** app 侧再手写刷新信号补偿
+
+## 能力边界 / 按需使用
+
+- **默认即够用：分页 + 骨架屏 + refine 布局 + 工具栏全开**——只传 `api`/`columns`/`rowKey` 即得标准数据表格。
+- **高度链三选一（判据）**：`refine` 默认开（按 viewport 高减 toolbar/pager 得出数据区高）即够用；`maxHeight` 显式定高仅当表格嵌定高容器（如固定高度卡片）时配；`viewportHeight` 显式指定视口可用高仅当 refine 计算不满足（嵌套弹层内消费外层 scope，优先级最高）时配。
+- `fillHeight`：默认关；仅当数据稀疏/为空时需要数据区撑满、分页器贴底（视觉稳定）时开——需已有 `maxHeight` 或 refine+viewportHeight 基准。
+- `skeleton`：默认开（冷启行数自适应 3~8）；热刷不出骨架属设计语义（外层遮罩盖旧数据），勿改。
+- `customView`（v-model）：默认关；仅当需要网格/卡片视图替代表格（DataListView）时开，且 [MUST] 配 `#custom-view-item` 插槽。
+- `query`：仅当有静态查询参数（固定过滤条件）时传；变化自动重置第 1 页重拉。
+- `showSwitchView`：默认关；仅当需要表格/网格视图切换按钮时开。
+- `tableProps`：仅当需透传 ElTable 事件（如 `onSelectionChange` 供工具栏选中联动）时配。
+- `showPager`/`pageSizeInit`/`pageSizeOptions`：仅分页形态不满足时调；常规列表不动。
+- **完整能力演示**（工具栏按钮组 + 骨架屏 + fillHeight + 网格视图）：`apps/reference/src/pages/table/toolbar/`、`apps/reference/src/pages/table/skeleton/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `T` 行 / `SQ` 静态 / `F` 注入）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `api` | `(params: TableApiParams<SQ>) => Promise<TableApiResult<T>>`（必传） | — | 列表请求；params = query 深合并 page.page/page.pageSize（键名由 APP_API_LIST_MODEL_KEY_CONFIG 定） |
+| `columns` | `ElTableColumnProps<T,F>[]`（必传） | — | 列配置数组 |
+| `rowKey` | `Extract<keyof T,string> \| ((row:T)=>string)`（必传） | — | 行主键 |
+| `query` | `SQ` | — | 静态查询参数；变化时重置到第 1 页重新拉取 |
+| `showPager` | `boolean` | `true` | 展示分页器 |
+| `pageSizeInit` | `number` | `20` | 初始每页条数 |
+| `pageSizeOptions` | `number[]` | `[10,20,30,40]` | 分页器每页条数选项 |
+| `pageLayout` | `string` | `"total, sizes, prev, pager, next, jumper"` | ElPagination layout |
+| `showSwitchView` | `boolean` | `false` | 显示切换视图按钮（表格/网格） |
+| `showToolbar` | `boolean` | `true` | toolbar 顶层开关 |
+| `toolbar` | `TableToolbarConfig<T,SQ,F>` | — | toolbar 配置（按钮 / 刷新 / 自动刷新 / 导出） |
+| `tableProps` | `Omit<TableProps<T>,"data"\|"maxHeight"\|"rowKey"> & Record<`on${...}`,fn>` | — | 透传 ElTable props + 事件（如 `{ onSelectionChange }`，内部与选中存储合并） |
+| `maxHeight` | `number` | — | 表格最大高度；与 refine 二选一作为高度基准 |
+| `headerColor` | `string` | `"rgb(240,240,240)"` | @deprecated，样式已注释无实际效果 |
+| `refine` | `boolean` | `true` | 精细化布局：无 maxHeight 时按 viewport 高减 toolbar/pager 得出数据区高 |
+| `refineReduceHeight` | `number` | `0` | refine 模式下预留高度减量 |
+| `injectInfo` | `F` | — | 注入列插槽 / DataListView 作用域的额外对象 |
+| `dataViewMaxHeightMinValue` | `number` | `500` | 数据视口最大高最小值 floor 兜底 |
+| `skeleton` | `boolean` | `true` | 冷启（首次无数据）骨架屏；热刷不出骨架（外层遮罩盖旧数据） |
+| `skeletonRows` | `number` | 自适应 3~8 | 骨架行数（table）/ 卡片数（grid） |
+| `fillHeight` | `boolean` | `false` | 数据滚动区 min-height 撑满可用高、稀疏/空数据时分页器顶到底；需有 maxHeight 或 refine+viewportHeight 基准 |
+| `viewportHeight` | `number` | — | 显式指定视口可用高（优先级最高）；缺省走 SCOPE_VIEWPORT_MAX_HEIGHT scope 链 + fallback 0（500 floor 兜底） |
+| `parentChannel` | `string` | — | 定向消费的祖先 scope 标识；setup 期快照，沿 scope 链找 scope === parentChannel 取高 |
+
+**v-model**：`isAutoRefresh`（boolean）、`refreshInterval`（number，秒）、`customView`（boolean，默认 false，显式切 DataListView 替代 ElTable，需配 `#custom-view-item` 插槽）
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `pageChange` | `number` | 页码变化 |
+| `pageSizeChange` | `number` | 每页条数变化 |
+| `dataChange` | `T[]` | 数据变更 |
+| `loadingChange` | `boolean` | 加载态变化 |
+| `pageInfoChange` | `TablePageInfo` | 分页信息（pageSize/currentPage/total） |
+
+### Slots
+
+无默认插槽。动态列插槽：
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#<column.prop>` | `TableColumnDefaultScope`：`{row, column, $index, injectInfo, exposeInfo}` | 覆盖列单元格 |
+| `#header-<column.prop>` | `TableColumnHeaderScope`：`{column, $index, injectInfo, exposeInfo}` | 覆盖列表头 |
+| `#custom-view-item` | `DataListViewItemScope<T>` | customView 模式单项渲染 |
+
+### Expose（`TableMainInstance`）
+
+`refresh(silent?: boolean): Promise<unknown>`（当前页重拉）、`reload(slice?: boolean): Promise<unknown>`（回第 1 页重拉，已在第 1 页则等同 refresh）、`getTableInstance(): TableInstance | undefined`（底层 el-table 实例）
+
+## 关键类型
+
+- `ElTableColumnProps<T,F>`：EP ElTableColumn 全量 props + `render`/`headerRender` 三态——string 全局组件名 / 组件对象 / functional `(props)=>VNode`
+- `TableColumnDefaultScope` / `TableColumnHeaderScope` / `TableColumnComponentProps`：组件 props 版把 `$index` 改 `_index`（`$` 开头属性 vue 报错）
+- `TableToolbarConfig<T,SQ,F>`：`showRefresh?`/`showAutoRefresh?`（默认均 true）、`exportByFe?`（默认 true，前端 fetchListAll + exportCSV）、`exportFn?`（exportByFe=false 时必传）、`exportColumns?`（ExportColumnConfig，不传则不显示导出按钮）、`leftExtraButtons?`/`rightExtraButtons?`（均默认 `[]`）
+- `ToolbarButtonConfig`：`ActionBtnConfigItem<ToolbarButtonContext>` 别名——`key`/`actionBtnProps`/`props`/`label`/`render`/`show`
+- `ToolbarButtonContext`：`{tableExpose, loading, exportContext, selectedList, pagination}`
+- `TableExportContext<T,SQ,F>`：`{columns(prop+label), selectedList, currentPageList, api, query?, total, hasSelection}`
+- `TablePageInfo`：`{pageSize, currentPage, total}`；`ExportType`：`"selected"|"current"|"all"`
+- `TableInstance`：el-table 实例 Pick 子集
+
+## 反模式 / 注意
+
+- **`headerColor` 勿用**：@deprecated，样式已注释无实际效果
+- **`fillHeight` 需高度基准**：必须已有 maxHeight 或 refine+viewportHeight 基准，否则撑高无据
+- **keepAlive 页返回刷新**：core 内置（onActivated refresh 留页码），app 侧 [MUST NOT] 补偿（双重请求反模式）
+- **`skeleton` 只覆盖冷启**：热刷不出骨架（外层遮罩盖旧数据），勿误判为骨架失效
+- **customView 需配套插槽**：`customView=true` 显式切 DataListView 时 [MUST] 配 `#custom-view-item` 插槽，否则无渲染
+- **组件 props 版列 scope 是 `_index`**：`$index` 仅插槽 scope 可用；组件 props 版 `$` 开头属性 vue 报错
+- **TableSkeleton / TableToolbar / ToolbarButtons 是内部件**：index.ts 不导出，[MUST NOT] 外部直接消费；对外只认 `TableMain` + types/constants
+
+## 关联
+
+- 组合页：`ListPage`（list-page 族，内部 FormSearch + TableMain，常用配置提升为直属 prop，TableMain 恒收 `refine=false`）
+- 列表接口模型：`APP_API_LIST_MODEL_KEY_CONFIG`（core config 单源，api 参数/结果类型由它推导）
+- 高度链：`refine` + `viewportHeight`/`parentChannel`（SCOPE_VIEWPORT_MAX_HEIGHT scope 链，见 modal 族 ModalConfirm 的 `modalReserve`）
+- 常量：`TABLE_COLUMN_KEY_OPERATE = "OPERATE"`、`TABLE_COLUMN_KEY_SELECTION = "SELECTION"`（index.ts 导出）
+- 范式页：`apps/reference/src/pages/table/toolbar/`、`apps/reference/src/pages/table/skeleton/`、`apps/reference/src/pages/list-page/guide/`

package/src/hooks/README.md

@@ -0,0 +1,5 @@
+# hooks 模块
+
+激活态 / 尺寸 / 断点 / 视口高度链 / 主题挂值等 10 个组合函数，全部经顶层 barrel 导出。
+
+> 详情见 [docs/README.md](./docs/README.md)（hook 清单表 + useActivated 使用范式 + 高度链消费范式）

package/src/hooks/docs/README.md

@@ -0,0 +1,49 @@
+# hooks 模块引导
+
+全部经顶层 barrel 导出（`import { useActivated } from "@done-coding/admin-core"`）。命名空间前缀：`use<Feature>`。
+
+| hook | 职责 | 何时用 |
+| --- | --- | --- |
+| `useActivated` | 激活态 hook：mounted/activated/deactivated/unmounted 四时机**直接派发** watchFn（`activatedInfo.isActivated` 分流），卸载必派发 | **组件内「随激活态绑解」副作用一律用它**（绑解成对写一处，天然覆盖 KeepAlive 失活/卸载）；发布库组件 [MUST] 用它（无宿主假设） |
+| `useFeelSize` | 感知元素尺寸（ResizeObserver）：`watchDom(dom)` / `unwatchDom()` + `sizeInfo` | 需要感知某元素宽高变化 |
+| `useBreakpoint` | 视口断点：xs<768 / sm≥768 / md≥992 / lg≥1200 / xl≥1920（matchMedia，SSR 守护） | 响应式 span 默认走视口（与 ElCol 同引擎） |
+| `useCustomBreakpoint` | 容器宽断点：`useCustomBreakpoint()` + `resolveBreakpointByWidth(width)` + `resolveRootEl`（EP 栅格同源阈值） | **容器断点**（非视口）：FormMain `layoutByContainer`、compact 搜索等 |
+| `useObserveSize` | 激活态感知 RO 观测原语：`getTarget` / `onResize` / `enabled` / `debounce`（默认 100ms，leading+trailing） | 需要「捕获渲染后尺寸变化」（CSS 折叠/异步撑开），WatchSize `observeResize` 底层 |
+| `useChannelViewportHeight` | 视口可用最大高解析：`viewportHeight` > scope 链（parentChannel 定向/就近）> fallback；返回 `viewportHeightFinal` + `nearestScope` | 列表/表格/弹窗的高度计算核心消费契约 |
+| `useCoreThemeApply` | 主题挂值：JS → root CSS var（`--dc-core-*` + `--el-*` 双命名空间）+ `buildRhythmCss`（density/motion 节奏） | 由 AppLayout 启动；业务一般不直接调 |
+| `useCoreViewportApply` | viewport 边框 CSS var 挂值（`--dc-core-viewport-*` / `--dc-core-gap`） | 由 AppLayout 启动 |
+| `useMenusDataDispatch` | 菜单数据分发：`menus` / `menuFlatList` / `extractLevel1ToHeader` + 当前路由聚焦菜单 | AppHeader/AppSidebar 消费；业务接 meta.menu 树 |
+| `useTimeout` | 定时器 `[setTimer, clearTimer]`，`autoClear` 随激活态/卸载清理 | 组件内延时逻辑（替代裸 setTimeout，防泄漏） |
+
+## 使用范式
+
+**组件内副作用（最重要的一条）**：
+
+```ts
+// ✅ 绑解成对写一处（useActivated 四态直接派发，卸载自动解绑外部 target 监听）
+useActivated((info) => {
+  if (info.isActivated) {
+    window.addEventListener("resize", onResize);
+  } else {
+    window.removeEventListener("resize", onResize);
+  }
+});
+```
+
+```ts
+// ❌ 禁用：useActivatedExec / useActivatedEvent（已 deprecated，碎片化包装）
+// ❌ 组件内禁用 onScopeDispose（语义 ≈ onUnmounted 但不覆盖 KeepAlive 失活 → 观测/订阅泄漏）
+// ✅ 非组件 scope（hooks/store/裸 effectScope）才用 onScopeDispose
+```
+
+**视口高度链消费**（列表/表格高度）：
+
+```ts
+const { viewportHeightFinal } = useChannelViewportHeight({ scope: "my-scope" });
+// 或作为子定向消费祖先：useChannelViewportHeight({ scope: "my-scope", parentChannel: "parent-scope" })
+```
+
+## 关联
+
+- `useActivated` 详细语义见 `docs/specs/` 相关任务文档与 CLAUDE.md 规则 21
+- 断点体系：`useBreakpoint`（视口）与 `useCustomBreakpoint`（容器）双源，见 FormMain `layoutByContainer` 文档

package/types/bridge/config-hook.d.ts

@@ -1,31 +1,99 @@
 import { DeepReadonly } from 'vue';
 import { AppBaseInfo, AppLayoutHeaderConfig, AppLayoutFooterConfig, AppLayoutSidebarConfig, AppLayoutAsideConfig, AppLayoutBreadcrumbConfig, AppLayoutBodyConfig, AppLayoutViewportConfig, AppLayoutGapConfig, AppThemeConfig, AppLayoutConfig } from './index';
+/**
+ * 可 update 的响应式配置字段 key 联合（插件系统一期 7 个 + viewport 边框期补 1 = 8 个）。
+ *
+ * #插件系统一期：bridge 的布局/主题/基础信息字段下沉为 reactive 响应式，
+ * 经 `update(key, partial)` 单字段一级浅合并触发。viewport 边框期新增
+ * `APP_LAYOUT_VIEWPORT_CONFIG`（同属布局子，纳入本联合 + layoutAggregate）。
+ * 其余 init 字段（env / cache / router 族 / userInfoAccess）非响应式范围，[MUST NOT] 纳入本联合。
+ */
 export type UpdatableConfigKey = "APP_BASE_INFO" | "APP_LAYOUT_HEADER_CONFIG" | "APP_LAYOUT_FOOTER_CONFIG" | "APP_LAYOUT_SIDEBAR_CONFIG" | "APP_LAYOUT_ASIDE_CONFIG" | "APP_LAYOUT_BREADCRUMB_CONFIG" | "APP_LAYOUT_BODY_CONFIG" | "APP_LAYOUT_VIEWPORT_CONFIG" | "APP_LAYOUT_GAP_CONFIG" | "APP_THEME_CONFIG";
+/**
+ * 7 个可 update 字段 key → 值类型映射。
+ *
+ * `update<K>(key, partial)` 的 `partial` 类型经 `Partial<UpdatableConfigMap[K]>`
+ * 推导；`createBridgeConfigHook` 的 init 入参亦以本映射约束（见 `BridgeConfigInit`）。
+ */
 export interface UpdatableConfigMap {
+    /** 应用基础信息 */
     APP_BASE_INFO: AppBaseInfo;
+    /** 应用布局-header 配置 */
     APP_LAYOUT_HEADER_CONFIG: AppLayoutHeaderConfig;
+    /** 应用布局-footer 配置 */
     APP_LAYOUT_FOOTER_CONFIG: AppLayoutFooterConfig;
+    /** 应用布局-sidebar 配置 */
     APP_LAYOUT_SIDEBAR_CONFIG: AppLayoutSidebarConfig;
+    /** 应用布局-aside 右侧补充区配置（P1' additive） */
     APP_LAYOUT_ASIDE_CONFIG: AppLayoutAsideConfig;
+    /** 应用布局-面包屑配置 */
     APP_LAYOUT_BREADCRUMB_CONFIG: AppLayoutBreadcrumbConfig;
+    /** 应用布局-页面主体配置 */
     APP_LAYOUT_BODY_CONFIG: AppLayoutBodyConfig;
+    /** 应用布局-视口边框配置 */
     APP_LAYOUT_VIEWPORT_CONFIG: AppLayoutViewportConfig;
+    /** 应用布局-模块间距配置（内缝 gap） */
     APP_LAYOUT_GAP_CONFIG: AppLayoutGapConfig;
+    /** 应用主题配置 */
     APP_THEME_CONFIG: AppThemeConfig;
 }
+/**
+ * `createBridgeConfigHook` 入参类型——7 个本期响应式字段的初值（= `UpdatableConfigMap`）。
+ *
+ * 由 `createCoreBridge` 闭包内从 `options` 的对应 7 字段直传；入参字段对象将被
+ * 直接 `reactive()` 化（方案 A，[MUST NOT] 浅拷贝），故 [MUST] 为去 freeze 后的非
+ * frozen 裸对象（app 端去字段级 freeze 保证）。
+ */
 export type BridgeConfigInit = UpdatableConfigMap;
+/**
+ * configHook 内部返回契约——`update` 方法 + 8 个对外 readonly 视图。
+ *
+ * **不对外 export**：`createBridgeConfigHook` / 本 interface / 上述类型符号 [MUST NOT]
+ * 在 `bridge/index.ts` re-export（守封装边界）。`bridge/index.ts` 仅内部 import 工厂，
+ * 把 `update` 与各 `roXxx` 视图组装进 `CoreBridge` 公开面。
+ *
+ * 7 个 readonly 视图各为对应 reactive 子配置的 `readonly()` 深只读包装；`roLayout`
+ * 为 5 布局子的 `reactive({...})` 聚合的 readonly 包装——5 字段指向各 reactive 子配置，
+ * 任一布局子 `update` 原地改经叶子代理同步跟随（Vue reactive 深度转换保留嵌套响应式），零拷贝。
+ */
 export interface BridgeConfigHook {
+    /** 单字段一级浅合并 update（`Object.assign` 派发到对应 reactive 子配置） */
     update: <K extends UpdatableConfigKey>(key: K, partial: Partial<UpdatableConfigMap[K]>) => void;
+    /** 应用基础信息对外只读视图 */
     roBaseInfo: DeepReadonly<AppBaseInfo>;
+    /** 应用布局-header 配置对外只读视图 */
     roHeader: DeepReadonly<AppLayoutHeaderConfig>;
+    /** 应用布局-footer 配置对外只读视图 */
     roFooter: DeepReadonly<AppLayoutFooterConfig>;
+    /** 应用布局-sidebar 配置对外只读视图 */
     roSidebar: DeepReadonly<AppLayoutSidebarConfig>;
+    /** 应用布局-aside 右侧补充区配置对外只读视图（P1' additive） */
     roAside: DeepReadonly<AppLayoutAsideConfig>;
+    /** 应用布局-面包屑配置对外只读视图 */
     roBreadcrumb: DeepReadonly<AppLayoutBreadcrumbConfig>;
+    /** 应用布局-页面主体配置对外只读视图 */
     roBody: DeepReadonly<AppLayoutBodyConfig>;
+    /** 应用布局-视口边框配置对外只读视图 */
     roViewport: DeepReadonly<AppLayoutViewportConfig>;
+    /** 应用布局-模块间距配置对外只读视图（内缝 gap） */
     roGap: DeepReadonly<AppLayoutGapConfig>;
+    /** 应用主题配置对外只读视图 */
     roTheme: DeepReadonly<AppThemeConfig>;
+    /**
+     * 应用布局聚合配置只读视图（5 布局子 reactive 聚合的 readonly 包装）。
+     *
+     * `reactive({header: reactiveHeader, ...})` 5 字段指向各 reactive 子配置，任一布局子
+     * update 原地改经叶子代理同步跟随（Vue reactive 深度转换保留嵌套响应式），零拷贝。
+     */
     roLayout: DeepReadonly<AppLayoutConfig>;
 }
+/**
+ * bridge 响应式配置 hook 工厂。
+ *
+ * 接收 7 个本期字段初值，逐字段 `reactive()` 化（方案 A：直接 reactive 入参对象，
+ * [MUST NOT] 浅拷贝），内部把 5 布局子聚合为 `layoutAggregate = reactive({...})`，
+ * 对外返回 `update`（单字段一级浅合并 `Object.assign`，[MUST NOT] 深合并 / merge / clone）+
+ * 7 个 `readonly()` 视图 + 1 个 `roLayout`（readonly 聚合视图）。每次 `createCoreBridge`
+ * 调用各自闭包内构造一份，零模块级单例（守实例隔离）。
+ */
 export declare function createBridgeConfigHook(init: BridgeConfigInit): BridgeConfigHook;