@done-coding/admin-core 0.18.0 → 0.19.0

package/src/components/data-view/docs/README-DataListView.md

@@ -0,0 +1,114 @@
+# DataListView（数据视图列表）
+
+> 卡片/自定义渲染的列表视图：外部传入数据与列配置，无请求、无分页；TableMain `customView` 模式的渲染载体。
+> 范式页：`apps/reference/src/pages/data-view/custom-view/Index.vue`
+> ⚠️ 内部件：仅供 TableMain 内部 import，[MUST NOT] 对外导出（不进 core 顶层 export）
+
+## 定位
+
+- **何时用**：`TableMain` 的 `customView` 模式——自定义卡片视图替代标准表格渲染
+- **何时不用**：标准表格用 `TableMain` / `ElTable`；DataListView 不直接对外消费
+- 泛型 `<T, F extends Record<string, any>>`：行类型 / 注入上下文类型
+- 数据契约：`data` 外部传入（当前页数据），组件无请求/分页逻辑
+- 接线：TableMain `customView.value ? markRaw(DataListView) : markRaw(ElTable)`；ListPage 转发 `#custom-view-item` 插槽（类型 `DataListViewItemScope<T>`）
+
+## 快速上手（最小可用）
+
+业务消费范式（经 TableMain `customView` 模式接入，`custom-view/Index.vue` 摘要）：
+
+```html
+<TableMain :customView="customView" :columns="columns" :api="api" rowKey="id">
+  <template #custom-view-item="{ fieldComponentMap, row, index, selected, toggleSelect }">
+    <component :is="fieldComponentMap['name']" :row="row" :index="index" />
+  </template>
+</TableMain>
+```
+
+**要点**：
+
+- `fieldComponentMap` 键规则：列 `prop` / `$type_index`（行号）/ `$type_selection`（选中框）；`type: "expand"` 跳过
+- 字段组件经 `markRaw(defineComponent)`（name `"DataViewField"`，props `row` / `index` / `selected` / `toggleSelect`）产稳定组件，跨渲染不 remount
+- 选中能力 `selectable` 开启后才有 `$type_selection` 键；选中变化走 `selectionChange`；`data` 引用变化（刷新）即清空选中
+
+## 能力边界 / 按需使用
+
+- **内部件不进顶层 export：仅供 TableMain 内部 import，[MUST NOT] 对外导出 / 全局注册 / install。** 业务 [MUST] 走 `TableMain` `customView` 模式消费——本组件无请求/分页，`data` 须外部传入（当前页数据），脱离 TableMain 直接消费没有数据来源。
+- **`maxHeight` / `minHeight`：默认 `undefined`（自然高度）即够用。** 仅当限高滚动（`maxHeight` 传入容器 `overflowY: auto`）或配合 TableMain `fillHeight` 顶分页器到底（`minHeight`）才设。
+- **`selectable`：默认 `false` 即够用。** 仅当卡片需要选中/批量操作能力才开——开启后才有 `$type_selection` 键。
+- **`rowKey` / `columns` / `getRenderCtxParams` 必填契约**：行唯一键、列配置、列 render 上下文缺一不可。
+- **完整能力演示**（选中框列 + 行号列 + 字段列 + 操作列全接线）：`apps/reference/src/pages/data-view/custom-view/Index.vue`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `data` | `T[]`（必填） | 无 | 当前页数据，外部传入，组件无请求/分页逻辑 |
+| `rowKey` | `Extract<keyof T, string> \| ((row: T) => string)`（必填） | 无 | 行唯一键：键名或函数，内部统一 String 化 |
+| `columns` | `DataViewColumn<T>[]`（必填） | 无 | 列配置（Pick 自 ElTableColumnProps 的 `prop` / `label` / `type` / `render`），内部归一为 `fieldComponentMap` |
+| `maxHeight` | `number` | `undefined` | 传入时容器 `overflowY: auto` 限高滚动 |
+| `minHeight` | `number` | `undefined` | 传入时撑满至此高（配合 TableMain `fillHeight` 顶分页器到底） |
+| `selectable` | `boolean` | `false` | 启用选中能力 |
+| `getRenderCtxParams` | `() => Pick<TableColumnDefaultScope<T, F>, "injectInfo" \| "exposeInfo">`（必填） | 无 | 列 render 上下文（必填契约） |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `selectionChange` | `rows: T[]` | 选中项变更 |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#item` | `DataListViewItemScope<T>`（`fieldComponentMap` / `row` / `index` / `selected` / `toggleSelect`） | 单项渲染（customView 卡片内容） |
+| `#empty` | 无 | 空态（默认 `<el-empty />`，消费方可覆写） |
+
+### Expose（`DataListViewInstance` = TableInstance 对齐）
+
+实际实现 5 个：`clearSelection` / `getSelectionRows` / `toggleRowSelection` / `toggleAllSelection` / `columns`。
+
+其余 10 个方法（`toggleRowExpansion` / `setCurrentRow` / `clearSort` / `clearFilter` / `doLayout` / `sort` / `scrollTo` / `setScrollTop` / `setScrollLeft` / `updateKeyChildren`）经 utils 填「not supported」抛错桩——调用即抛错，勿依赖。
+
+## 反模式 / 注意
+
+- **不对外导出**：本组件 [MUST NOT] 对外导出 / 全局注册 / 提供 install 插件；消费方 [MUST] 走 `TableMain` `customView` 模式
+- **无请求/分页**：`data` 须外部传入（当前页数据），勿期待组件内部取数
+- **刷新清选中**：`data` 引用变化即清空选中——跨页 / 刷新后选中状态不保留
+- **未实现方法抛错**：Expose 面与 TableInstance 对齐但 10 个方法为「not supported」桩（表格特有行为在自定义视图无意义）
+- **列键依赖归一规则**：消费 `fieldComponentMap` 只用 `prop` / `$type_index` / `$type_selection` 三系键，`type: "expand"` 列不产出
+
+## DataListViewItem（列表项容器）
+
+由 DataListView 内部 `v-for` 使用的列表项容器；消费方一般不直接使用。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `selected` | `boolean`（必填） | 无 | 是否选中（由 DataListView 传入） |
+
+### Emits / Expose
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 项内容 |
+
+### 定位注释（.vue 头）
+
+- 仅承载选中态 class 钩子（`.is-selected`）+ 项内容插槽
+- [MUST NOT] 写死视觉样式（卡片阴影 / 圆角归消费方）
+- [MUST NOT] 内置选中状态机
+
+## 关联
+
+- 宿主：`TableMain`（table 族，`customView` 模式）；`ListPage`（转发 `#custom-view-item`）
+- 内部件：`DataListViewItem`（本文件上文）
+- 类型：`DataViewColumn<T>` / `DataListViewItemScope<T>`（data-view types.ts）
+- 范式页：`apps/reference/src/pages/data-view/custom-view/Index.vue`

package/src/components/display/README.md

@@ -0,0 +1,23 @@
+# display 展示族
+
+展示与交互原语：TabsMain（Tab 容器）/ ActionBtn 系列（确认闸门 + 自动 loading）/ 尺寸与高度工具（WatchSize / HeightProvider）/ BooleanTag。
+
+## 组件文档（docs/）
+
+- [TabsMain](./docs/README-TabsMain.md) — Tab 容器（channel 嵌套 / tile 平铺 / query 同步）
+- [ActionBtn](./docs/README-ActionBtn.md) — ElButton 超集（confirm 闸门 + beforeOpen + 自动 loading）
+- [ActionBtnGroup](./docs/README-ActionBtnGroup.md) — 配置式按钮组（渲染三态）
+- [ActionConfirm](./docs/README-ActionConfirm.md) — 确认原语（扁平，submitFn 返 Promise 才关）
+- [WatchSize](./docs/README-WatchSize.md) — 尺寸监听容器（mode / observeResize / debounce）
+- [HeightProvider](./docs/README-HeightProvider.md) — 纯数值高度预算节点（available = viewportHeight − reserve）
+- [BooleanTag](./docs/README-BooleanTag.md) — boolean 只读彩色标签
+
+## 关键类型
+
+- `TabsMainProps` / `TabsMainItem` / `ActionBtnProps` / `ActionBtnConfirmConfig` / `ActionBtnConfigItem` / `ActionBtnGroupProps` / `ActionConfirmProps` / `BooleanTagProps`（经 `./types` 导出）
+- 内部件不导出：`TabsHeader` / `TabsTile` / `TabsRefineFlow` / `TabsNaturalFlow` / `use-tabs-query-sync`
+
+## 范式页（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 场景）

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

@@ -0,0 +1,84 @@
+# ActionBtn（确认闸门按钮）
+
+> ElButton 超集：透传全部 ElButton props + 确认闸门（popconfirm / messageConfirm）+ beforeOpen 异步预取 + click handler 返 Promise 自动 loading + 重复点击防抖。
+> 范式页：`apps/reference/src/pages/display/action-btn/showcase/`
+
+## 定位
+
+- **何时用**：配置化体系下的**默认按钮原语**——需要 confirm / loading 中的任意能力，或按体系规则 11 替代 ElButton
+- **何时不用**：表格操作列 / 堆按钮用 `ActionBtnGroup`（配置驱动）；`loading` 对外不可设置，[MUST NOT] 自管 submitting ref + :loading
+- 内部：`confirmMode="messageConfirm"` 内嵌 ConfirmModal 居中模态；`"popconfirm"` 走 ElPopover
+
+## 快速上手（最小可用）
+
+普通按钮 + 异步 onClick 自动 loading——零配置即带 loading 与重复点击防抖：
+
+```html
+<ActionBtn type="danger" @click="handleDelete">删除</ActionBtn>
+```
+
+```ts
+const handleDelete = async () => {
+  await deleteUserApi(row.id);   // 返回 Promise → 自动 loading
+  ElMessage.success("已删除");
+};
+```
+
+**要点**：
+
+- 提交类按钮让 onClick 返回 Promise（async）即自动 loading——[MUST NOT] 自管 `submitting` ref + `:loading`（留着是死 prop）
+- `@click` 归 emits 不进 $attrs（防绕过闸门），由组件在确认通过后手动触发
+
+## 能力边界 / 按需使用
+
+- **确认闸门（`confirmConfig`）：默认无=普通按钮直通 click。** 仅当操作需要确认（删除 / 归档 / 批量操作等不可逆）才配；函数形态 `(data: T) => config` 仅当确认文案依赖点击时预取的数据时用（data 来自 `beforeOpen` 返回值，无 beforeOpen 时 T 默认 void、data=undefined）。
+- **`confirmMode`：默认 `"popconfirm"`（ElPopover 就近轻确认）即够用**；`"messageConfirm"`（内嵌 ConfirmModal 居中模态、强阻断）仅当操作风险高、需醒目居中确认时选。
+- **`beforeOpen`（异步预取）：默认不用。** 仅当确认内容需要点击时动态取数（如先取详情再拼删除文案）才配；reject 静默退出（不弹层不触发 click），调用方 [MUST] 内部 catch 反馈；⚠️ 与 confirmConfig 均消耗瞬时用户激活窗口，handler 内 [MUST NOT] 调 window.open / navigator.clipboard 等。
+- **自动 loading 与重复点击防抖：默认即带。** onClick 返 Promise 自动 loading，innerLoading / confirmVisible 置位时自动吞重复点击——无需任何配置。
+- **完整能力演示**（beforeOpen 预取 + 函数 confirmConfig + 动态删除各场景）：`apps/reference/src/pages/display/action-btn/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `T` = beforeOpen 返回类型）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| 全部 ElButton props | 透传 | type 默认 "default" | size/plain/bg/link/round/circle/color/dark/disabled/autofocus/nativeType/autoInsertSpace/tag/icon/loadingIcon 显式 pick 透传 + attrs 叠加 |
+| `loading` | ❌ 被 Omit | — | 对外不可设置，内部独占 innerLoading（对接异步 confirm / beforeOpen / click handler） |
+| `confirmMode` | `ActionConfirmMode?` | `"popconfirm"` | "popconfirm"\|"messageConfirm"（后者内嵌 ConfirmModal 居中模态） |
+| `confirmConfig` | `ActionBtnConfirmConfig \| ((data: T) => ActionBtnConfirmConfig)?` | 无=普通按钮 | 确认闸门；函数形态入参 data 来自 beforeOpen 返回值 |
+| `beforeOpen` | `() => Promise<T>?` | — | 点击后、弹层前异步预取；reject 静默退出（不弹层不触发 click，调用方 [MUST] 内部 catch 反馈）；期间按钮 loading。⚠️ confirmConfig/beforeOpen 均会消耗瞬时用户激活窗口，之后 handler [MUST NOT] 调 window.open/navigator.clipboard 等 |
+
+`ActionBtnConfirmConfig`：`title?` / `content?`（`ActionConfirmTextResolver` = string | (() => string | VNode[])）、`confirmText?`（默认「确定」）、`cancelText?`（默认「取消」）、`type?: ButtonProps["type"]`
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `click` | `MouseEvent` | 显式声明——父层 @click 归 emits 不进 $attrs（防绕过闸门）；由组件在确认通过后手动触发 |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 按钮内容 |
+
+### Expose
+
+无（`inheritAttrs: false`）
+
+## 反模式 / 注意
+
+- **自管 loading**：[MUST NOT] 自管 submitting ref + `:loading`——onClick 返 Promise 即自动 loading，外部 `:loading` 被忽略
+- **beforeOpen reject 反馈**：reject 静默退出，调用方 [MUST] 内部 catch 做错误反馈（如 ElMessage.error）
+- **用户激活窗口**：confirmConfig / beforeOpen 消耗瞬时用户激活窗口，handler 内 [MUST NOT] 调 window.open / navigator.clipboard 等（被浏览器拦截）
+- **无闸门语义**：confirmConfig 不传 = 普通按钮直通 click——需确认的操作 [MUST] 配 confirmConfig
+- **重复点击**：innerLoading || confirmVisible 置位时吞掉重复点击（防抖），无需外部再防
+
+## 关联
+
+- 上游：`ActionConfirm`（popconfirm / messageConfirm 两种确认弹层）
+- 下游：`ActionBtnGroup`（表格操作列 / 堆按钮配置驱动）
+- 体系规则：规则 11（配置化体系按钮默认 ActionBtn 替代 ElButton）
+- 范式页：`apps/reference/src/pages/display/action-btn/showcase/`

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

@@ -0,0 +1,96 @@
+# ActionBtnGroup（配置驱动按钮组）
+
+> 配置驱动按钮组：一个 configs 数组渲染一列按钮——`actionBtnProps` 走 ActionBtn（带确认闸门）或 `props` 走 ElButton（无闸门），`show` 控制显隐、`render` 自由接管。
+> 范式页：`apps/reference/src/pages/display/action-btn-group/showcase/`
+
+## 定位
+
+- **何时用**：表格操作列 / 工具栏堆按钮——按配置项数组驱动，多按钮零手写
+- **何时不用**：单按钮直接用 `ActionBtn`
+- 渲染三态（`ActionBtnConfigItem<Ctx>`）：`actionBtnProps`（走 ActionBtn，带 confirm/beforeOpen，与 props 二选一优先）/ `props`（走 ElButton，无闸门）/ `render`（对标 FormItem.render 三态，完全接管）
+
+## 快速上手（最小可用）
+
+挂载（`action-btn-group/showcase/Index.vue`）：
+
+```html
+<ActionBtnGroup :configs="scene1Configs" :ctx="row" />
+```
+
+单项配置（popconfirm 默认模式 + ctx 入参）：
+
+```ts
+{
+  key: "1a",
+  label: "1A：popconfirm（默认模式）",
+  actionBtnProps: (c) => ({
+    type: "warning",
+    confirmConfig: { title: `归档 ${c.row.name}?`, type: "warning" },
+    onClick: () => {
+      lastAction.value = `1A popconfirm 归档：${c.row.name}`;
+      ElMessage.success("已归档(popconfirm)");
+    },
+  }),
+},
+```
+
+**要点**：
+
+- `actionBtnProps` 与 `props` 二选一，`actionBtnProps` 优先（走 ActionBtn，带 confirm/beforeOpen）
+- `ctx` 透传给每项 actionBtnProps/props/render/show——函数态统一入口
+- Fragment 多根，[MUST NOT] 直接传 style attr（外层 [MUST] 包 div）
+
+## 能力边界 / 按需使用
+
+- **`actionBtnProps` 分支（走 ActionBtn，带闸门）：默认推荐。** 绝大多数操作按钮走它（confirm / beforeOpen / 自动 loading 白拿）；`props` 分支（裸 ElButton 无闸门）仅当按钮确实无需闸门且无需 ActionBtn 能力时才用——同项二选一（`actionBtnProps` 优先）。
+- **`render`（完全接管）：默认不用。** 仅当按钮内容 / 结构超出 props 表达（自定义复合内容、非按钮形态）才用——对标 FormItem.render 三态（string / Component / (props) => VNode）。
+- **`show`（显隐过滤）：默认全显（缺省 true）。** 仅当按钮需按上下文动态显隐（如选中行才出现的操作）才配 `(ctx) => boolean`。
+- **`defaultSize`：默认不强加。** 仅当整组按钮需统一基础 size 时传；业务侧显式 size 优先（spread 在后覆盖）。
+- **完整能力演示**（渲染三态 + show 过滤 + 多场景组合）：`apps/reference/src/pages/display/action-btn-group/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `Ctx` = 渲染上下文）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `configs` | `ActionBtnConfigItem<Ctx>[]?` | `[]` | 按钮配置列表 |
+| `ctx` | `Ctx`（必填） | — | 渲染上下文，透传给每项 actionBtnProps/props/render/show |
+| `defaultSize` | `ActionBtnSize?`（"large"\|"default"\|"small"） | 不传=不强加 | 基础 size 注入；业务侧返回对象内显式 size 优先（spread 在后覆盖） |
+
+**ActionBtnConfigItem\<Ctx\> 渲染三态**：
+
+| 字段 | type | 语义 |
+| --- | --- | --- |
+| `key` | `string`（必填） | 项唯一键 |
+| `actionBtnProps` | `(ctx) => Record<string, any>` | 走 ActionBtn，带 confirm/beforeOpen；与 props 二选一优先 |
+| `props` | `(ctx) => Record<string, any>` | 走 ElButton，无闸门 |
+| `label` | `string?` | render 缺省时回退文案 |
+| `render` | `string \| Component \| ((props: { ctx: Ctx }) => VNode)` | 对标 FormItem.render 三态，完全接管渲染 |
+| `show` | `(ctx) => boolean` | false 跳过，缺省 true |
+
+### Emits
+
+无
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **直接给 Fragment 传 style attr**：[MUST NOT]——多根 Fragment 无法落 style，外层包 div
+- **同项同配 actionBtnProps 与 props**：二选一（actionBtnProps 优先），语义混用易困惑
+- **defaultSize 覆盖**：业务侧显式 size 覆盖注入（spread 在后），无需担心注入污染
+- **无闸门语义**：`props` 分支是裸 ElButton——需要确认的按钮 [MUST] 走 actionBtnProps
+
+## 关联
+
+- 内部组件：`ActionBtn`（actionBtnProps 分支）
+- 上游：`ListPage.toolbar`（leftExtraButtons 即 ActionBtnGroup 配置形态）
+- 范式页：`apps/reference/src/pages/display/action-btn-group/showcase/`

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

@@ -0,0 +1,77 @@
+# ActionConfirm（独立确认弹层）
+
+> 独立确认弹层：popconfirm（ElPopover 宽 240）或 messageConfirm（内嵌 ConfirmModal 居中模态）两种模式，submitFn 返 Promise → 确认按钮 loading + 弹层不关，仅 fulfill 才关闭。
+> 范式页：`apps/reference/src/pages/display/action-btn/showcase/`（场景 12 独立用法）
+
+## 定位
+
+- **何时用**：需要外部独立控制确认弹层显隐（`v-model:show`）的场景——ActionBtn 的确认闸门底层即本组件
+- **何时不用**：按钮确认直接走 `ActionBtn` 的 `confirmConfig`（本组件已内嵌，无需手动组合）
+- 触发元素由 `#default` 槽提供；弹层显隐由外部 `v-model:show` 控制
+
+## 快速上手（最小可用）
+
+独立用法（`action-btn/showcase/Index.vue` 场景 12）：
+
+```html
+<ActionConfirm v-model:show="standaloneVisible" mode="popconfirm" title=... content=... type="danger" :submit-fn="standaloneSubmit">
+  <!-- 触发元素由默认 slot 提供 -->
+</ActionConfirm>
+```
+
+**要点**：
+
+- submitFn 返 Promise → 确认按钮 loading + 弹层不关，仅 fulfill 才关闭；reject/throw 保持打开（错误由 submitFn 内部 catch 反馈）
+- 弹层关闭（确认或取消）都会 emit `close(confirmed: boolean)`
+- messageConfirm 模式 show=true→true 重入安全
+
+## 能力边界 / 按需使用
+
+- **`mode` 两种形态判据（必填）**：`"popconfirm"`（ElPopover 宽 240、就近轻确认）为常规推荐；`"messageConfirm"`（内嵌 ConfirmModal 居中模态、强阻断 + 自定义弹层）仅当操作风险高、需醒目居中确认时选。
+- **`submitFn` 返 Promise：所有确认场景建议返 Promise**——确认按钮自动 loading + 弹层不关、仅 fulfill 才关闭（防重复提交）；reject/throw 保持打开，错误在 submitFn 内部 catch 反馈。
+- **`v-model:show` 外部控制：仅独立弹层场景需要。** 按钮确认一律走 `ActionBtn` 的 `confirmConfig`（本组件已内嵌，无需手动组合）；仅当弹层显隐由外部业务逻辑独立驱动（非按钮触发）时才直用本组件。
+- **触发元素由 `#default` 槽提供**：[MUST NOT] 留空（弹层无内置触发点）。
+- **完整能力演示**（独立用法）：`apps/reference/src/pages/display/action-btn/showcase/` 场景 12——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `mode` | `"popconfirm" \| "messageConfirm"`（必填） | — | 弹层形态（popconfirm = ElPopover 宽 240；messageConfirm = 内嵌 ConfirmModal） |
+| `title` / `content` | 同 ActionBtnConfirmConfig | — | 标题 / 内容文本 |
+| `confirmText` | `string?` | 「确定」 | 确认按钮文案 |
+| `cancelText` | `string?` | 「取消」 | 取消按钮文案 |
+| `type` | `ButtonProps["type"]?` | — | 按钮类型（如 danger） |
+| `submitFn` | `() => void \| Promise<void>`（必填） | — | 确认提交逻辑 |
+
+**v-model**：`show`（`v-model:show`，默认 false）
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `close` | `confirmed: boolean` | 弹层关闭（确认 true / 取消 false） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 触发元素 |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **submitFn 吞错误再 resolve**：[MUST NOT] 把失败当成功关闭弹层——reject/throw 保持打开，错误在 submitFn 内部 catch 反馈（如 ElMessage.error）
+- **默认槽留空**：popconfirm 触发元素由默认槽提供，[MUST NOT] 留空
+
+## 关联
+
+- 内部组件：`ConfirmModal`（messageConfirm 模式）
+- 上游：`ActionBtn`（confirmConfig 内部即本组件）
+- 范式页：`apps/reference/src/pages/display/action-btn/showcase/`（场景 12）

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

@@ -0,0 +1,76 @@
+# BooleanTag（布尔状态标签）
+
+> 布尔值 → ElTag 状态标签：value 派生 type（true → activeTagType 默认 success，false → inactiveTagType 默认 info），文案可配。
+> 范式页：无独立范式页（典型消费：`apps/reference/src/pages/_shared/user-form.config.tsx` 表单列 render）
+
+## 定位
+
+- **何时用**：把 boolean 渲染为「是/否」「启用/禁用」等状态标签（表格列 / 表单只读渲染）
+- **何时不用**：多态枚举标签用 `ElTag` 自配 type；纯文本用普通 span
+- `inheritAttrs: false`——attrs（size/effect/round 等）透传 ElTag，但 `:type` 被 value 派生覆盖（消费方无法覆盖 type）
+
+## 快速上手（最小可用）
+
+典型消费（`_shared/user-form.config.tsx`——枚举→boolean 在调用点一行映射）：
+
+```tsx
+{
+  key: "status",
+  label: "状态",
+  render: (scope) => (
+    <BooleanTag
+      value={scope.value === "enabled"}
+      activeText="启用"
+      inactiveText="禁用"
+    />
+  ),
+},
+```
+
+**要点**：
+
+- 枚举 → boolean 的映射在调用点一行完成（如上 `scope.value === "enabled"`）
+- 默认「是/否」+ success/info 即可覆盖大多数场景，文案/type 按需覆盖
+
+## 能力边界 / 按需使用
+
+- **默认即够用**：默认「是/否」文案 + success/info 双态配色覆盖大多数场景（启用/禁用、上线/下线等）——零配置使用，典型消费仅一行 render 映射。
+- **`activeText` / `inactiveText` / `activeTagType` / `inactiveTagType`：仅当默认文案 / 配色不符合业务语义才覆盖**（如「启用 / 禁用」、状态需醒目色）；均为按需单项覆盖，无需成套配。
+- **attrs 透传（size / effect / round 等）：默认不加。** 仅视觉微调按需透传；⚠️ `:type` 被 value 派生独占，消费方 [MUST NOT] 覆盖。
+- **适用范围：只吃 boolean。** 三态及以上枚举标签用 `ElTag` 自配 type；纯文本直接用 span。
+- **完整能力演示**：典型消费 `apps/reference/src/pages/_shared/user-form.config.tsx`（表单列 render 一行映射）。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `value` | `boolean`（必填） | — | 布尔值 |
+| `activeText` | `string?` | 「是」 | true 文案 |
+| `inactiveText` | `string?` | 「否」 | false 文案 |
+| `activeTagType` | 同 ElTag type | `"success"` | true 的标签 type |
+| `inactiveTagType` | 同 ElTag type | `"info"` | false 的标签 type |
+
+### Emits
+
+无
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **覆盖 :type**：[MUST NOT]——type 由 value 派生独占，消费方无法覆盖（attrs 只透传 size/effect/round 等）
+- **三态枚举**：只吃 boolean——三态及以上用 ElTag 自管
+
+## 关联
+
+- 基础：`ElTag`（element-plus）
+- 典型消费：`apps/reference/src/pages/_shared/user-form.config.tsx`

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

@@ -0,0 +1,74 @@
+# HeightProvider（视口高度供给）
+
+> 视口高度供给：传入 viewportHeight，按 #header 实际高度（WatchSize 测高）扣减 reserve，向 #default 插槽提供 available 高度——页面容器高度链的源头。
+> 范式页：无独立范式页（内嵌于 TabsMain refine 精细流等容器；核心实证：`packages/core/src/components/display/__tests__/HeightProvider.test.ts`）
+
+## 定位
+
+- **何时用**：需要「视口高 − 页头高 → 内容可用高」计算的容器源头
+- **何时不用**：页签容器直接用 `TabsMain`（内部已接 HeightProvider，无需手动组合）
+- 不 inject/provide；Fragment 双根（header + default 并行渲染）
+
+## 快速上手（最小可用）
+
+核心实证（`__tests__/HeightProvider.test.ts`）：
+
+```html
+<HeightProvider :viewportHeight="480">
+  <template #header>...</template>
+  <template #default="{ viewportHeight }">...</template>
+</HeightProvider>
+```
+
+**要点**：
+
+- `#default` scope `{ viewportHeight: available }`，available = max(viewportHeight - reserve, minHeight ?? 0)
+- `#header` 经 WatchSize 测高得 reserve——header 高度变化自动回算
+- [MUST NOT] 给 WatchSize 设 min-height: available（reserve↔available 反馈环 → 首帧震荡）
+
+## 能力边界 / 按需使用
+
+- **默认场景：被容器组件内嵌消费，业务 [MUST NOT] 手动组合。** `TabsMain` refine 精细流内部即包 HeightProvider、`ListPage` 已接管高度链——常规页签 / 列表页无需直用本组件。
+- **业务直用判据**：自定义容器需要「视口高 − 页头高 → 内容可用高」计算，且现有容器组件（TabsMain / ListPage）接不上时才直用——形态：有固定 `#header` 区 + `#default` 需精确撑满到视口底；`#header` 经 WatchSize 量高，header 高度变化自动回算。
+- **`minHeight`：默认 `0` 即够用。** 仅当内容需要保底高度才设；⚠️ 超 viewportHeight 会撑破父容器——有意设计，[MUST NOT] 当 bug 修。
+- **`viewportHeight` 必填**：由父级传入（AppBody 高度链 / 显式值），本组件不 inject/provide。
+- **完整能力演示**：无独立范式页——核心实证 `packages/core/src/components/display/__tests__/HeightProvider.test.ts` + `TabsMain` refine 精细流消费（`apps/reference/src/pages/display/tabs/`）。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `viewportHeight` | `number`（必填） | — | 视口可用高度（父级传入） |
+| `minHeight` | `number?` | `0` | 兜底下限；超 viewportHeight 会撑破父容器——有意设计 |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `childViewportHeightChange` | `value: number` | 可用高度变化（immediate 首发） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | `{ viewportHeight: available }` | 内容区（available = max(viewportHeight - reserve, minHeight ?? 0)） |
+| `#header` | 无 | 页头区（经 WatchSize 测高得 reserve） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **WatchSize min-height: available 反馈环**：[MUST NOT]——reserve↔available 互算 → 首帧震荡
+- **minHeight 超 viewportHeight**：会撑破父容器——有意设计，[MUST NOT] 当 bug 修
+- **Fragment 双根**：不能直接作为单根子组件传 class/style 到外部
+
+## 关联
+
+- 内部：`WatchSize`（#header 量高）
+- 下游：`TabsMain`（refine 精细流内部包 HeightProvider）
+- 核心实证：`packages/core/src/components/display/__tests__/HeightProvider.test.ts`

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

@@ -0,0 +1,99 @@
+# TabsMain（配置化页签容器）
+
+> 配置驱动的页签容器：v-model 激活 + 动态命名槽 / 组件渲染 + 视口高度链（refine 精细流 / 自然流）+ 路由 query 双向同步 + 平铺 tile 模式（卡片列 + 角落 nav + scrollspy）。
+> 范式页：`apps/reference/src/pages/display/tabs/showcase/`（基础 + queryKey）、`pages/display/tabs/nested-channel/`（channel 嵌套链）、`pages/display/tabs/tile/`（平铺）
+
+## 定位
+
+- **空间一等公民**：多 tab 空间首选（单层或嵌套 tab 链）
+- **何时用**：页签切换内容的容器（单层或嵌套 tab 链），需要可用高度计算 / 路由深链 / 平铺卡片列时
+- **何时不用**：无页签语义的纯内容高度计算用 `HeightProvider`；列表页场景直接用 `ListPage`
+- 双流实现：refine=false 自然流（`TabsNaturalFlow`，不包 HeightProvider，scope viewportHeight 为 undefined）；refine=true 精细流（`TabsRefineFlow`，HeightProvider 精确扣 header reserve + padding）——均为内部实现，不导出
+- 内部实现（不导出）：`TabsHeader` / `TabsTile` / `TabsNaturalFlow` / `TabsRefineFlow` / `use-tabs-query-sync.ts`
+
+## 快速上手（最小可用）
+
+最常用基础 tab 形态——默认配置即够用（自然流，不依赖 queryKey / channel / tile）：
+
+```ts
+const active = ref<string>();
+const tabs = [
+  { key: "overview", title: "概览" },
+  { key: "editor", title: "编辑器", component: markRaw(EditorPane) },
+];
+```
+
+```html
+<TabsMain v-model="active" :tabs="tabs">
+  <template #overview="{ tab, active: a }"> ... </template>
+</TabsMain>
+```
+
+**要点**：
+
+- `#<key>` 动态槽优先于 `tab.component` 回退；槽 scope `{ tab, active, viewportHeight }`（refine 精细流给可用高度、自然流 undefined）
+- `component` [MUST] 用 `markRaw` 包裹，[MUST NOT] 直接放响应式组件对象
+- 槽内角标用 opacity 切换勿用 v-if——会改标题宽度致下划线动画错位
+
+## 能力边界 / 按需使用
+
+- **refine（精细流）：默认 `false`（自然流）即够用。** 自然流不包 HeightProvider（scope viewportHeight 为 undefined），页签内容按自身尺寸渲染即可；仅当 tab 内容需要精确撑满到视口底（页签头内滚、内容区借可用高度）才开 `refine`——判据：内容高度必须由「视口高 − header reserve − padding」计算，且随 header 变化回算。
+- **queryKey（路由深链）：默认不传=不同步。** 仅当激活 tab 需要可被 URL 深链 / 刷新 / 前进后退恢复（分享链接 / 回到原 tab）才传 `queryKey`；此时 active 初值留空由 query 恢复（防 replace 竞速覆盖深链）；无 vue-router 环境静默失效。
+- **channel / parentChannel（嵌套链）：默认不用。** 仅当 tab 内容里还有更深的页签链、需要逐级扣高（L1 页签内容再嵌 L2 页签，且 L2 需撑满 L1 剩余高度）才配；⚠️ 每级 [MUST] 显式 `refine`、每级 TabsMain [MUST] 是父 tab 内容**直接根**、channel 名 [MUST NOT] 响应式变更——缺任一链路静默失效。
+- **tile（平铺模式）：默认关（tab-bar 页签形态）。** 仅当所有 item 需铺成卡片列 + 角落 nav + scrollspy（长文档式阅读、内容即卡片）才开 `tile`；`navPosition` / `navMode` / `navOffset` 仅在 tile 下有意义。
+- **variant：默认按 level 推导（1-4 级依次 card / indicator / indicator-compact / plain）即够用**，仅特殊视觉需求显式覆盖。
+- **完整能力演示**（基础 + queryKey + 嵌套链 + 平铺各态）：`apps/reference/src/pages/display/tabs/showcase/`、`pages/display/tabs/nested-channel/`、`pages/display/tabs/tile/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `tabs` | `TabsMainItem[]`（必填） | — | tab 配置列表 |
+| `viewportHeight` | `number?` | — | 显式视口高度，优先级最高；未传降级 inject SCOPE_VIEWPORT_MAX_HEIGHT scope 链 |
+| `minHeight` | `number?` | `100` | 内容区高度兜底下限 |
+| `channel` | `string?` | — | 作为父时的 scope 标识。⚠️ 与 parentChannel 均 [MUST NOT] 响应式变更（setup 期快照）；且仅 refine=true 路径生效 |
+| `parentChannel` | `string?` | — | 作为子时定向消费的祖先 scope 标识（沿对象链 parent 找匹配） |
+| `padding` | `TabsMainPadding`（= [top,right,bottom,left] px） | `[10,10,0,10]` | 默认插槽容器内置 padding（withDefaults 实证）；top+bottom 同步从 slot scope / channel viewportHeight 扣减 |
+| `refine` | `boolean?` | `false` | false=自然流（TabsNaturalFlow，不包 HeightProvider，scope viewportHeight 为 undefined）；true=精细流（TabsRefineFlow，HeightProvider 精确扣 header reserve + padding） |
+| `refineReduceHeight` | `number?` | `0` | 从 viewportHeightFinal 预扣的高度（refine=false 时同样生效） |
+| `variant` | `TabsHeaderVariant?` | 按 level 推导 | "card"\|"indicator"\|"indicator-compact"\|"plain"；level 1-4 默认依次 card/indicator/indicator-compact/plain。字号始终跟 level（inject TABS_MAIN_VISUAL_LEVEL +1 每层） |
+| `queryKey` | `string?` | 不传=不同步 | 激活 tab ↔ 路由 query 双向同步的 key：切 tab → router.replace `?{queryKey}={key}`（不压栈）；激活/刷新/前进后退读 query 反向恢复；无 vue-router 环境静默失效 |
+| `tile` | `boolean?` | `false` | 平铺模式：所有 item 铺成卡片列（各裹 ElCard）、隐藏 tab-bar、角落 nav 导航 + scrollspy 反写激活 |
+| `navPosition` | `TabsMainTileNavPosition?` | `"bottom-right"` | 平铺角落 nav 落角（四角） |
+| `navMode` | `TabsMainTileNavMode?` | `"auto"` | "auto"\|"absolute"\|"sticky"\|"fixed"；auto = refine→absolute / 自然流→sticky |
+| `navOffset` | `number?` | `12` | 平铺角落 nav 距角像素 |
+
+**v-model**：`v-model`（string，激活 tab key；非法值归一回写 tabs[0].key，tabs 空不回写）
+
+### Emits
+
+无显式 defineEmits（仅 model）
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#<key>` | `{ tab, active, viewportHeight }` | 优先于 tab.component 回退；viewportHeight 精细流给可用高度、自然流 undefined（⚠️ tile 模式槽 scope 仅 `{ tab, active }`，无 viewportHeight） |
+| `#header-<key>` | `{ tab, active }` | 覆盖页签头，优先于 tab.title |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **channel / parentChannel 响应式变更**：[MUST NOT]——setup 期快照，后续变更无效
+- **缺 refine 的 channel 链**：链路静默失效——每级 [MUST] 显式 refine
+- **TabsMain 非父 tab 内容直接根**：[MUST NOT]——外层再包 div 会让高度链错位
+- **槽内角标用 v-if**：会改标题宽度致下划线动画错位，用 opacity 切换
+- **queryKey 深链初值**：active 初值留空由 query 恢复（防 replace 竞速覆盖深链）
+- **tab.component 裸放响应式组件对象**：用 markRaw
+
+## 关联
+
+- 内部实现：`TabsNaturalFlow` / `TabsRefineFlow` / `TabsHeader` / `TabsTile` / `use-tabs-query-sync.ts`（均不导出）
+- 高度链：`SCOPE_VIEWPORT_MAX_HEIGHT` scope 链（viewportHeight / parentChannel 消费侧）
+- 范式页：`apps/reference/src/pages/display/tabs/showcase/`、`pages/display/tabs/nested-channel/`、`pages/display/tabs/tile/`