@done-coding/admin-core 0.19.0 → 0.20.0

package/src/components/README.md

@@ -1,8 +1,8 @@
 # components 组件族总引导
 
-core 共 11 个组件族，全部经顶层 barrel 导出（`import { FormMain } from "@done-coding/admin-core"`）。各族目录内均有 `README.md` 入口（组件清单 + 指向 `docs/` 组件详情文档，`README-<PascalName>.md`）。
+core 共 12 个组件族，全部经顶层 barrel 导出（`import { FormMain } from "@done-coding/admin-core"`）。各族目录内均有 `README.md` 入口（组件清单 + 指向 `docs/` 组件详情文档，`README-<PascalName>.md`）。
 
-**页面范式**：`AppPage`（页面容器）→ `ListPage`（列表）/ `FormMain`（表单）/ `ViewLayout`（详情展示，**后续迭代，未实现**）→ `TableMain` / `FormSearch` 子配置。⚠️ 存量 `PanelMain` 的页级展示一等公民地位已撤销、将废弃——新页面 [MUST NOT] 以 PanelMain 作页级展示根容器（详见 panel 族文档）。
+**页面范式**：`AppPage`（页面容器）→ `ListLayout`（列表）/ `FormMain`（表单）/ `ViewLayout`（展示）→ `TableMain` / `FormSearch` 子配置。⚠️ 存量 `PanelMain` 的页级展示一等公民地位已撤销、将废弃——新页面 [MUST NOT] 以 PanelMain 作页级展示根容器（详见 panel 族文档）。
 
 ## 配置化体系契约（设计引导）
 
@@ -19,14 +19,14 @@ core 共 11 个组件族，全部经顶层 barrel 导出（`import { FormMain }
 
 | 空间 | 一等公民（优先用） | 零件（底层，一般经一等公民使用） |
 | --- | --- | --- |
-| 列表 | `ListPage` | `TableMain`（表格侧）/ `FormSearch`（搜索侧） |
+| 列表 | `ListLayout` | `TableMain`（表格侧）/ `FormSearch`（搜索侧） |
 | 纯表单提交 | `FormSubmitPanel` | `FormMain`（底座）/ `FormSubmitBtn` |
 | 弹窗 CRUD / 表单 | `ModalDetail` / `ModalForm` | `ModalConfirm`（原语底座） |
 | 弹窗命令式 | `ModalPorter` + `ModalShelf`（app/page 内置） | — |
-| 详情展示 | `ViewLayout`（**后续迭代，未实现**）；存量 `PanelMain` 将废弃（仅表单预览 / 就地编辑场景保留） | `PanelItem` / `PanelEditSwitch` |
+| 展示 | `ViewLayout` | `PanelMain`（将废弃，仅表单预览 / 就地编辑保留）`PanelItem` / `PanelEditSwitch` |
 | 多 tab | `TabsMain` | `TabsRefineFlow` 等（内部件） |
 
-业务层 [MUST] 一等公民优先：能用 `TableMain` 处用 `ListPage`、能用 `FormMain` 处用 `FormSubmitPanel`；裸用仅限特例（详见各族文档定位段断言）。
+业务层 [MUST] 一等公民优先：能用 `TableMain` 处用 `ListLayout`、能用 `FormMain` 处用 `FormSubmitPanel`；裸用仅限特例（详见各族文档定位段断言）。
 
 ### 配置化字段归位四机制
 
@@ -51,7 +51,7 @@ core 共 11 个组件族，全部经顶层 barrel 导出（`import { FormMain }
 | 族 | 组件 | 入口 |
 | --- | --- | --- |
 | form 表单族 | FormMain / FormSearch / FormSubmitBtn / FormSubmitPanel / FormItemNestForm / FormItemNestFormList / FormSelect / FormRadioGroup / FormTree / FormVerifyImage / FormVerifyCode | [README](./form/README.md) |
-| list-page 列表族 | ListPage（FormSearch + TableMain 组合页） | [README](./list-page/README.md) |
+| list-layout 列表族 | ListLayout（FormSearch + TableMain 组合页） | [README](./list-layout/README.md) |
 | table 表格族 | TableMain | [README](./table/README.md) |
 | modal 弹窗族 | ModalConfirm / ModalForm / ModalDetail / ModalShelf / ModalPorter | [README](./modal/README.md) |
 | panel 面板族 | PanelMain / PanelItem / PanelEditSwitch / PanelItemNestPanel / PanelItemNestForm | [README](./panel/README.md) |
@@ -59,6 +59,7 @@ core 共 11 个组件族，全部经顶层 barrel 导出（`import { FormMain }
 | app-layout 布局族 | AppLayout / AppPage / AppBody / AppHeader / AppSidebar / AppAside / AppBreadcrumb / AppFooter / AppTheme / AppCollapseToggle（未导出） | [README](./app-layout/README.md) |
 | menu 菜单族 | MenuTree / MenuItemSub | [README](./menu/README.md) |
 | slot-layout 插槽布局族 | SlotLayoutTemplate / SlotLayoutFlowAside | [README](./slot-layout/README.md) |
+| view-layout 展示布局族 | ViewLayout | [README](./view-layout/README.md) |
 | data-view 数据视图族 | DataListView / DataListViewItem（TableMain 内部件，customView 模式；不进顶层 export） | [README](./data-view/README.md) |
 | misc 杂项族 | AutoRefresh / AutoRefreshGroup / SelectModule / TriggerAutoImport（@deprecated） | [README](./misc/README.md) |
 
@@ -66,7 +67,7 @@ core 共 11 个组件族，全部经顶层 barrel 导出（`import { FormMain }
 
 - 各族 `README.md` = 入口（组件清单 + 一句话），组件详情在 `docs/README-<PascalName>.md`
 - **快速上手 = 最小可用形态**（默认值即够用，5–20 行可直接抄的代码）——[MUST NOT] 把能力全开示例当快速上手（AI 会按示例最大化使用，全能力示例反而误导）
-- **空间一等公民断言**：组合件（ListPage / FormSearch / FormSubmitPanel / ModalDetail 等）与零件（TableMain / FormMain / ModalConfirm / PanelItem 等）的文档 [MUST] 在定位段断言「优先经 <空间组件> 使用 + 直接使用仅当 <特例>」——配置化体系「空间一等公民优先」范式，[MUST NOT] 让 AI 把零件当默认起点。⚠️ `PanelMain` 已撤销一等公民地位（将废弃，待 `ViewLayout` 承接），文档 [MUST NOT] 再以 PanelMain 作详情展示组合件示例
+- **空间一等公民断言**：组合件（ListLayout / FormSearch / FormSubmitPanel / ModalDetail 等）与零件（TableMain / FormMain / ModalConfirm / PanelItem 等）的文档 [MUST] 在定位段断言「优先经 <空间组件> 使用 + 直接使用仅当 <特例>」——配置化体系「空间一等公民优先」范式，[MUST NOT] 让 AI 把零件当默认起点。⚠️ `PanelMain` 已撤销一等公民地位（将废弃，已由 `ViewLayout` 承接），文档 [MUST NOT] 再以 PanelMain 作详情展示组合件示例
 - **每篇必含「能力边界 / 按需使用」段**（快速上手之后）：逐条断言「默认关/默认即够用 + 仅当 X 场景才开（判据）」，末行给「完整能力演示」reference 指针——全能力代码不复制进文档正文（活代码在 reference showcase 页，零重复维护）
 - 新增/改造对外组件 [MUST] 同步补 `docs/README-<PascalName>.md`（随 `docs/specs/` 任务闭环）
 - API 段以 `types.ts` + 组件源码为真相源；与文档冲突时以源码为准

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

@@ -42,5 +42,5 @@
 ## 关联
 
 - 布局插件自供 shell 契约：`AppShellProps` / `AppShellSlots`（types.ts）
-- 页面级骨架（ListPage 等）以 `AppPage` 为宿主：`apps/reference/src/pages/app-layout/page-slots/`
+- 页面级骨架（ListLayout 等）以 `AppPage` 为宿主：`apps/reference/src/pages/app-layout/page-slots/`
 - 范式页：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/page-slots/`、`apps/reference/src/pages/app-layout/layout/`

package/src/components/app-layout/docs/README-AppPage.md

@@ -5,7 +5,7 @@
 
 ## 定位
 
-- **何时用**：每个路由页面的内容根——ListPage/FormMain 等页面骨架的宿主（`<AppPage><ListPage .../></AppPage>`）
+- **何时用**：每个路由页面的内容根——ListLayout/FormMain 等页面骨架的宿主（`<AppPage><ListLayout .../></AppPage>`）
 - **何时不用**：无需容器几何（纯组件局部）时直接用裸组件
 - 默认 slot 内容经 ModalShelf page 层包裹（弹层挂载点）
 - 四向悬浮插槽为 fixed 定位（z-index `APP_PAGE_SLOT_Z_INDEX`=1），top/bottom 通栏量高、left/right 量宽，尺寸几何由 `app-page-geometry` 纯函数计算
@@ -16,7 +16,7 @@
 
 ```vue
 <AppPage>
-  <ListPage ... />
+  <ListLayout ... />
 </AppPage>
 ```
 
@@ -24,7 +24,7 @@
 
 ```vue
 <AppPage fullViewport>
-  <ListPage ... />
+  <ListLayout ... />
 </AppPage>
 ```
 

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

@@ -15,5 +15,5 @@
 ## 内部件边界
 
 - **不进 core 顶层 export**：core 顶层 `index.ts` 无 data-view 导出行；两组件 [MUST NOT] 对外导出 / 全局注册 / 提供 install 插件
-- **消费入口**：走 `TableMain` `customView` prop + `#custom-view-item` 插槽（TableMain `customView.value ? markRaw(DataListView) : markRaw(ElTable)` 择一渲染；ListPage 已转发该插槽，类型 `DataListViewItemScope<T>`）
+- **消费入口**：走 `TableMain` `customView` prop + `#custom-view-item` 插槽（TableMain `customView.value ? markRaw(DataListView) : markRaw(ElTable)` 择一渲染；ListLayout 已转发该插槽，类型 `DataListViewItemScope<T>`）
 - **DataListViewItem**：由 DataListView 内部 `v-for` 使用，消费方不直接使用；[MUST NOT] 写死视觉样式（卡片阴影/圆角归消费方）、[MUST NOT] 内置选中状态机

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

@@ -10,7 +10,7 @@
 - **何时不用**：标准表格用 `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.value ? markRaw(DataListView) : markRaw(ElTable)`；ListLayout 转发 `#custom-view-item` 插槽（类型 `DataListViewItemScope<T>`）
 
 ## 快速上手（最小可用）
 
@@ -108,7 +108,7 @@
 
 ## 关联
 
-- 宿主：`TableMain`（table 族，`customView` 模式）；`ListPage`（转发 `#custom-view-item`）
+- 宿主：`TableMain`（table 族，`customView` 模式）；`ListLayout`（转发 `#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/docs/README-ActionBtnGroup.md

@@ -92,5 +92,5 @@
 ## 关联
 
 - 内部组件：`ActionBtn`（actionBtnProps 分支）
-- 上游：`ListPage.toolbar`（leftExtraButtons 即 ActionBtnGroup 配置形态）
+- 上游：`ListLayout.toolbar`（leftExtraButtons 即 ActionBtnGroup 配置形态）
 - 范式页：`apps/reference/src/pages/display/action-btn-group/showcase/`

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

@@ -28,8 +28,8 @@
 
 ## 能力边界 / 按需使用
 
-- **默认场景：被容器组件内嵌消费，业务 [MUST NOT] 手动组合。** `TabsMain` refine 精细流内部即包 HeightProvider、`ListPage` 已接管高度链——常规页签 / 列表页无需直用本组件。
-- **业务直用判据**：自定义容器需要「视口高 − 页头高 → 内容可用高」计算，且现有容器组件（TabsMain / ListPage）接不上时才直用——形态：有固定 `#header` 区 + `#default` 需精确撑满到视口底；`#header` 经 WatchSize 量高，header 高度变化自动回算。
+- **默认场景：被容器组件内嵌消费，业务 [MUST NOT] 手动组合。** `TabsMain` refine 精细流内部即包 HeightProvider、`ListLayout` 已接管高度链——常规页签 / 列表页无需直用本组件。
+- **业务直用判据**：自定义容器需要「视口高 − 页头高 → 内容可用高」计算，且现有容器组件（TabsMain / ListLayout）接不上时才直用——形态：有固定 `#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/`）。

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

@@ -7,7 +7,7 @@
 
 - **空间一等公民**：多 tab 空间首选（单层或嵌套 tab 链）
 - **何时用**：页签切换内容的容器（单层或嵌套 tab 链），需要可用高度计算 / 路由深链 / 平铺卡片列时
-- **何时不用**：无页签语义的纯内容高度计算用 `HeightProvider`；列表页场景直接用 `ListPage`
+- **何时不用**：无页签语义的纯内容高度计算用 `HeightProvider`；列表页场景直接用 `ListLayout`
 - 双流实现：refine=false 自然流（`TabsNaturalFlow`，不包 HeightProvider，scope viewportHeight 为 undefined）；refine=true 精细流（`TabsRefineFlow`，HeightProvider 精确扣 header reserve + padding）——均为内部实现，不导出
 - 内部实现（不导出）：`TabsHeader` / `TabsTile` / `TabsNaturalFlow` / `TabsRefineFlow` / `use-tabs-query-sync.ts`
 

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

@@ -28,7 +28,7 @@
 - **`observeResize`（ResizeObserver）：默认关。** 默认测量链（激活首测 + window resize + onUpdated）已覆盖「渲染驱动的尺寸变化」（v-if/v-show / 样式响应式）——普通场景即够用；仅当测「不触发自身重渲染的尺寸变化」（CSS 过渡折叠 / 异步撑开）才开——判据：尺寸变化过程中组件自身不重渲染、onUpdated 读不到最终值。
 - **`debounceTime`：默认 `16`ms 即够用。** 仅当变化频率极高（连续 resize / 连续折叠）需聚合事件流时才调大；⚠️ 只吃初始值，后续变化不更新。
 - **`mode`：默认 `"height"`。** 仅需横向尺寸（侧栏宽 / 横向布局）才设 `"width"` / `"both"`。
-- **优先复用容器内嵌，[MUST NOT] 重复造轮**：ListPage（header / 操作槽量高）、HeightProvider（#header 量高得 reserve）等已内嵌消费本组件；仅自定义容器需要自身盒尺寸时才直用。
+- **优先复用容器内嵌，[MUST NOT] 重复造轮**：ListLayout（header / 操作槽量高）、HeightProvider（#header 量高得 reserve）等已内嵌消费本组件；仅自定义容器需要自身盒尺寸时才直用。
 - **完整能力演示**：无独立范式页（组件级测量工具）——核心实证 `packages/core/src/components/display/__tests__/`。
 
 ## API

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

@@ -1,11 +1,11 @@
 # FormSearch（搜索表单）
 
 > FormMain 的搜索前缀：自带折叠（maxRows 按真实几何换行）+ 内置操作区（展开更多 / 重置 / 查询），search emit 自动并入静态参数。
-> 范式页：`apps/reference/src/pages/menu/showcase/`（独立裸用）；ListPage 内嵌场景见 `apps/reference/src/pages/list-page/guide/`
+> 范式页：`apps/reference/src/pages/menu/showcase/`（独立裸用）；ListLayout 内嵌场景见 `apps/reference/src/pages/list-layout/guide/`
 
 ## 定位
 
-- **空间一等公民是 `ListPage` 的搜索侧**：常规列表页 [MUST] 走 `ListPage`（内部即「FormSearch + TableMain」组合，搜索侧 props 双子扁平化、`staticQuery` 提升为直属 prop）——**FormSearch 一般不直接使用**
+- **空间一等公民是 `ListLayout` 的搜索侧**：常规列表页 [MUST] 走 `ListLayout`（内部即「FormSearch + TableMain」组合，搜索侧 props 双子扁平化、`staticQuery` 提升为直属 prop）——**FormSearch 一般不直接使用**
 - **独立裸用仅当**：纯搜索区页面/组件（无表格，配合外部触发查询）
 - **何时不用**：普通录入表单用 `FormMain`；带提交 / 取消操作区的用 `FormSubmitPanel`
 - 与 FormMain 的差异：`rowGutter` 默认 14（FormMain 为 8）、`layout` 默认 `{xs:24, sm:12, md:12, lg:8, xl:6}`、`maxRows` 折叠、内置操作区按钮、`staticQuery` 并入 emit、expose 增 trigger 与折叠控制
@@ -33,7 +33,7 @@
 - 具名槽 `#<config.key>`：默认关（单项由配置驱动）；仅当单项需要完全自定义渲染（复杂组合控件）才开。
 - `compact`：默认关；仅当搜索区落入受限窄栏（独立侧栏搜索）才开——窄栏场景优先容器断点系（`compact` / `layoutByContainer`），而非给单项 layout 写死 span。
 - `layoutByContainer`：默认关；仅当容器断点折叠几何需要切到容器档才开。
-- expose `triggerSearch()` / `triggerReset()` / `toggleCollapse()`：默认不需要（操作区按钮内置）；仅当外部需程序化触发（如 ListPage 列插槽注入）才用。
+- expose `triggerSearch()` / `triggerReset()` / `toggleCollapse()`：默认不需要（操作区按钮内置）；仅当外部需程序化触发（如 ListLayout 列插槽注入）才用。
 - **完整能力演示**（staticQuery + 多 slot 覆盖 + 折叠回调）：`apps/reference/src/pages/menu/showcase/`——能力展示，非推荐默认。
 
 ## API
@@ -76,7 +76,7 @@
 
 ## 反模式 / 注意
 
-- **用 `#default` 插自定义按钮**：默认槽被内置操作区占用，不会渲染——自定义操作走 expose 的 trigger 方法，或交给 ListPage / 外层编排
+- **用 `#default` 插自定义按钮**：默认槽被内置操作区占用，不会渲染——自定义操作走 expose 的 trigger 方法，或交给 ListLayout / 外层编排
 - **`@search` 后手工再并 staticQuery**：载荷已含静态参数，再拼一次会重复
 - **class 定向落点**：`inheritAttrs: false` + attrs 显式转发内层 FormMain——消费方 class 落在内层 ElForm，而非 `.form-search` 根（WatchSize 包裹）；定向样式按实际落点写选择器
 - **窄栏场景改 layout 硬撑**：`compact`（或 `layoutByContainer`）走容器断点几何，与 ElCol 的视口响应式不同源——窄栏挤崩场景优先容器断点系，而非给单项 layout 写死 span
@@ -84,6 +84,6 @@
 ## 关联
 
 - 表单族：`FormMain`（底座，本组件为其搜索前缀）、`FormSubmitPanel` / `FormSubmitBtn`（提交面）、`FormItemNestForm` / `FormItemNestFormList`（嵌套）
-- 组合页：`ListPage`（内部即「FormSearch + TableMain」，搜索侧 props 双子扁平化；`staticQuery` 被扁平提升为直属 prop，禁放 formSearchProps 内）
+- 组合页：`ListLayout`（内部即「FormSearch + TableMain」，搜索侧 props 双子扁平化；`staticQuery` 被扁平提升为直属 prop，禁放 formSearchProps 内）
 - 类型：`FormSearchSearchType` = `"search" \| "reset" \| FormItemSubmitType`；`FormSearchInstance<PO, SO>`
-- 范式页：`apps/reference/src/pages/menu/showcase/`、`pages/list-page/guide/`
+- 范式页：`apps/reference/src/pages/menu/showcase/`、`pages/list-layout/guide/`

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

@@ -0,0 +1,16 @@
+# list-layout 列表族
+
+单组件族：`ListLayout` =「FormSearch + TableMain」组合页，一个组件承接搜索、列表、分页、工具栏、粘性吸附全链路；双子 props 扁平化 + 常用项提升直属。
+
+## 组件文档（docs/）
+
+- [ListLayout](./docs/README-ListLayout.md) — 列表页（表单侧 / 表格侧双子配置 + injectInfo 注入 + 三件套粘性）
+
+## 关键类型
+
+- `ListLayoutProps` / `ListLayoutInstance`（= FormSearchInstance + TableMainInstance + update）/ `ListLayoutInnerInjectInfo`（列插槽注入：triggerSearch / triggerReset / update）
+- 内部不导出：`use-sticky`
+
+## 范式页（apps/reference）
+
+- `/list-layout/guide`（最佳实践：搜索 + 弹窗 CRUD + 分离侧栏）/ `/list-layout/sticky`（三件套粘性）/ `/list-layout/module-demo`（keepAlive 模块组合）

package/src/components/{list-page/docs/README-ListPage.md → list-layout/docs/README-ListLayout.md}

@@ -1,7 +1,7 @@
-# ListPage（列表页）
+# ListLayout（列表页）
 
 > 「FormSearch + TableMain」组合页：一个组件承接搜索、列表、分页、工具栏、粘性吸附全链路。
-> 范式页：`apps/reference/src/pages/list-page/guide/`（最佳实践）、`pages/list-page/sticky/`（粘性）、`pages/list-page/module-demo/`（keepAlive 模块组合）
+> 范式页：`apps/reference/src/pages/list-layout/guide/`（最佳实践）、`pages/list-layout/sticky/`（粘性）、`pages/list-layout/module-demo/`（keepAlive 模块组合）
 
 ## 定位
 
@@ -9,6 +9,7 @@
 - **何时用**：标准列表页（搜索 + 表格 + 分页 + 操作列），是最常用页面骨架
 - **何时不用**：纯表格（无搜索）用 `TableMain`；纯搜索表单用 `FormSearch`
 - 内部组合：`FormSearch`（搜索区）+ `TableMain`（表格区），props 按「表单侧 / 表格侧」双子配置扁平化，常用项提升为直属 prop
+- ⚠️ 换名兼容：`ListPage` → `ListLayout`（v0.20.0 breaking）。旧名 `ListPage` / `ListPageProps` / `ListPageInstance` 保留为 deprecated 兼容别名，根容器旧类 `list-page` / `dc-list-page` 继续保留——新代码一律用新名（详见 `migrations/v0.20.0.md`）
 
 ## 快速上手（最小可用）
 
@@ -27,12 +28,12 @@ const listPageConfig = {
 挂载 + 注入触发（`module-demo/list/Index.vue` 最小闭环）：
 
 ```ts
-import { ListPage } from "@done-coding/admin-core";
-import type { ListPageInstance } from "@done-coding/admin-core";
-const listPage = ref<ListPageInstance>();
+import { ListLayout } from "@done-coding/admin-core";
+import type { ListLayoutInstance } from "@done-coding/admin-core";
+const listPage = ref<ListLayoutInstance>();
 const { listPageConfig } = useSpaceConfig({
   goDetail: (id?: number) =>
-    router.push({ path: "/list-page/module-demo/detail",
+    router.push({ path: "/list-layout/module-demo/detail",
       query: id === undefined ? {} : { id: String(id) } }),
   reloadList: () => listPage.value?.reload(),   // 增删改成功后触发
 });
@@ -40,7 +41,7 @@ const { listPageConfig } = useSpaceConfig({
 
 ```html
 <AppPage>
-  <ListPage ref="listPage" v-bind="listPageConfig" />
+  <ListLayout ref="listPage" v-bind="listPageConfig" />
 </AppPage>
 ```
 
@@ -56,8 +57,8 @@ const { listPageConfig } = useSpaceConfig({
 - **`searchSticky` / `toolbarSticky` / `pagerSticky`（三件套粘性）：默认全关。** 仅当页面长滚时需搜索 / 工具栏 / 分页吸附才按需开（toolbarSticky 叠钉搜索区下方）。
 - **`showSwitchView`（双视图切换）：默认关（表格单一视图）。** 仅当需要「列表 / 卡片」双视图切换才开（配 `#custom-view-item` 卡片渲染）。
 - **`isAutoRefresh` / `refreshInterval`：默认关（不自动刷新）。** 仅当列表需轮询刷新（任务态实时变化等）才开。
-- **高度链 prop（`refine` / `viewportHeight` / `parentChannel`）：默认 ListPage 内部已接管**（refine 默认 true）——常规无需干预，仅特殊高度场景覆写。
-- **完整能力演示**（toolbar 全形态 + 粘性三件套 + keepAlive 组合）：`apps/reference/src/pages/list-page/guide/`（最佳实践）、`pages/list-page/sticky/`（粘性）、`pages/list-page/module-demo/`（keepAlive 模块组合）——能力展示，非推荐默认。
+- **高度链 prop（`refine` / `viewportHeight` / `parentChannel`）：默认 ListLayout 内部已接管**（refine 默认 true）——常规无需干预，仅特殊高度场景覆写。
+- **完整能力演示**（toolbar 全形态 + 粘性三件套 + keepAlive 组合）：`apps/reference/src/pages/list-layout/guide/`（最佳实践）、`pages/list-layout/sticky/`（粘性）、`pages/list-layout/module-demo/`（keepAlive 模块组合）——能力展示，非推荐默认。
 
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
@@ -68,8 +69,8 @@ const { listPageConfig } = useSpaceConfig({
 
 | name | type | 默认 | 语义 |
 | --- | --- | --- | --- |
-| `list` | `FormItemConfigList<PO, SO>` | `[]` | 搜索表单配置（ListPage 据此推 PO/SO，data 内部生成） |
-| `staticQuery` | `SQ` | `{}` | 静态参数（扁平顶到 ListPage，禁放 formSearchProps 内） |
+| `list` | `FormItemConfigList<PO, SO>` | `[]` | 搜索表单配置（ListLayout 据此推 PO/SO，data 内部生成） |
+| `staticQuery` | `SQ` | `{}` | 静态参数（扁平顶到 ListLayout，禁放 formSearchProps 内） |
 | `formSearchProps` | `Partial<Omit<FormSearchProps<PO,SO,{}>, "staticQuery"\|"list"\|"compact">>` | 未设 | FormSearch 透传袋（compact 由内部 separateSearch 驱动，外部 [MUST NOT] 覆盖） |
 
 **表格侧（TableMain 双子）**
@@ -79,7 +80,7 @@ const { listPageConfig } = useSpaceConfig({
 | `columns` | `TableMainProps["columns"]`（必填） | — | 列配置（扁平等级） |
 | `rowKey` | `Extract<keyof T, string> \| ((row:T)=>string)`（必填） | — | 行键 |
 | `api` | `(params: TableApiParams<ExtractFormStringifyFromObject<PO,SO> & SQ>) => Promise<TableApiResult<T>>`（必填） | — | 列表取数 |
-| `refine` / `refineReduceHeight` / `viewportHeight` / `parentChannel` / `toolbar` / `showSwitchView` | 同 TableMain | refine `true`、refineReduceHeight `0` | 常用配置提升为直属扁平 prop（内部自行消化视口高度链；TableMain 恒收 `:refine="false"`，高度计算由 ListPage 接管） |
+| `refine` / `refineReduceHeight` / `viewportHeight` / `parentChannel` / `toolbar` / `showSwitchView` | 同 TableMain | refine `true`、refineReduceHeight `0` | 常用配置提升为直属扁平 prop（内部自行消化视口高度链；TableMain 恒收 `:refine="false"`，高度计算由 ListLayout 接管） |
 | `tableMainProps` | `Partial<Omit<TableMainProps, 上述 6 键 \| "api" \| "query" \| "injectInfo">>` | 未设 | TableMain 透传袋 |
 
 **直属行为 props**
@@ -111,14 +112,14 @@ const { listPageConfig } = useSpaceConfig({
 | `#header` / `#operation` | 无 | 搜索区上下扩展 |
 | `#custom-view-item` | `DataListViewItemScope<T>` | customView 模式单项卡片渲染 |
 | `#form-<key>` | `FormScope` | 覆盖搜索表单单项 |
-| `#table-<prop>` | `TableColumnDefaultScope<T, ListPageInnerInjectInfo<PO,F>>` | 覆盖列单元格 |
+| `#table-<prop>` | `TableColumnDefaultScope<T, ListLayoutInnerInjectInfo<PO,F>>` | 覆盖列单元格 |
 | `#table-header-<prop>` | `TableColumnHeaderScope & { searchFormData: PO; triggerSearch?: () => void }` | 覆盖列表头（可联动搜索） |
 
-### Expose（`ListPageInstance` = FormSearchInstance + TableMainInstance + update）
+### Expose（`ListLayoutInstance` = FormSearchInstance + TableMainInstance + update）
 
 `refresh(silent?)` / `reload(silent?)` / `getTableInstance()` / `validate()` / `resetFields()` / `clearValidate(key?)` / `triggerReset()` / `triggerSearch()` / `toggleCollapse(next?)` / `isCollapsed` / `update(key, value)`（改内部表单数据）
 
-**注入机制**：`injectInfoAdjust` 把 `triggerReset` / `triggerSearch` / `update` 合并进 TableMain `:injectInfo` —— 列插槽 `scope.injectInfo` 可直接 `triggerSearch()` / `triggerReset()` / `update(key, value)`（类型 `ListPageInnerInjectInfo<PO,F>`）。
+**注入机制**：`injectInfoAdjust` 把 `triggerReset` / `triggerSearch` / `update` 合并进 TableMain `:injectInfo` —— 列插槽 `scope.injectInfo` 可直接 `triggerSearch()` / `triggerReset()` / `update(key, value)`（类型 `ListLayoutInnerInjectInfo<PO,F>`）。
 
 ## 反模式 / 注意
 
@@ -126,11 +127,11 @@ const { listPageConfig } = useSpaceConfig({
 - **`query` prop 勿用**：声明未消费（疑似历史残留）
 - **keepAlive 页返回刷新**：core 内置（onActivated refresh 留页码），app 侧 [MUST NOT] 补偿
 - **formSearchProps 塞 staticQuery/compact**：类型已 Omit，编译即拦
-- 搜索/表格的双子 props 与 TableMain 直属 prop 重复时，**以 ListPage 直属为准**（TableMain 恒收 refine=false）
+- 搜索/表格的双子 props 与 TableMain 直属 prop 重复时，**以 ListLayout 直属为准**（TableMain 恒收 refine=false）
 
 ## 关联
 
 - 内部组件：`FormSearch`（form 族）、`TableMain`（table 族）
 - 列表接口模型：`APP_API_LIST_MODEL_KEY_CONFIG`（core config 单源，api 参数/结果类型由它推导）
 - 高度链：`refine` + `viewportHeight`/`parentChannel`（见 TableMain 文档）
-- 范式页：`apps/reference/src/pages/list-page/guide/`、`pages/list-page/sticky/`、`pages/list-page/module-demo/`
+- 范式页：`apps/reference/src/pages/list-layout/guide/`、`pages/list-layout/sticky/`、`pages/list-layout/module-demo/`

package/src/components/misc/docs/README-AutoRefreshGroup.md

@@ -1,7 +1,7 @@
 # AutoRefreshGroup（工具栏自动刷新组）
 
 > 「自动刷新开关 + 手动刷新按钮」组合组：loading 联动、布局根可选，表格工具栏自动刷新能力即此组件。
-> 消费范式：`packages/core/src/components/table/TableToolbar.vue`（内部代表消费）；列表页经 TableMain/ListPage 工具栏生效。
+> 消费范式：`packages/core/src/components/table/TableToolbar.vue`（内部代表消费）；列表页经 TableMain/ListLayout 工具栏生效。
 
 ## 定位
 

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

@@ -1,7 +1,7 @@
 # ModalDetail（配置化 CRUD 弹窗 / 抽屉）
 
 > CRUD 预设薄壳：`type`（add/edit/read）决定标题前缀与提交分支，内部委托 ModalForm 渲染配置化表单。
-> 范式页：`apps/reference/src/pages/list-page/guide/`（DetailModalItem 作 ModalPorter item 的薄适配器）、`apps/reference/src/pages/modal/guide/`
+> 范式页：`apps/reference/src/pages/list-layout/guide/`（DetailModalItem 作 ModalPorter item 的薄适配器）、`apps/reference/src/pages/modal/guide/`
 
 ## 定位
 
@@ -13,7 +13,7 @@
 
 ## 快速上手（最小可用）
 
-作 ModalPorter item 的薄适配器（`list-page/guide/DetailModalItem.vue`——`show`/`closeFn`/`payload` 来自架子注入，add/edit 动态取自 payload）：
+作 ModalPorter item 的薄适配器（`list-layout/guide/DetailModalItem.vue`——`show`/`closeFn`/`payload` 来自架子注入，add/edit 动态取自 payload）：
 
 ```ts
 const modalProps = computed(() => ({
@@ -42,7 +42,7 @@ const modalProps = computed(() => ({
 - `title`/`subTitle`：默认标题（新增/编辑 + 前缀）即够用；仅需定制标题（如带图标）时传。
 - `formLayout`/`labelWidth` 等布局 props：默认即够用；仅栅格/紧凑需求时配。
 - `layerType="drawer"`：仅当 CRUD 表单需要抽屉形态时开。
-- **完整能力演示**（薄适配器 + 自定义标题 + 提交闭环）：`apps/reference/src/pages/list-page/guide/`、`apps/reference/src/pages/modal/guide/`——能力展示，非推荐默认。
+- **完整能力演示**（薄适配器 + 自定义标题 + 提交闭环）：`apps/reference/src/pages/list-layout/guide/`、`apps/reference/src/pages/modal/guide/`——能力展示，非推荐默认。
 
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
@@ -98,6 +98,6 @@ const modalProps = computed(() => ({
 
 - 委托链：`ModalDetail` → `ModalForm` → `ModalConfirm`（Promise 契约 / $attrs 透传 / 分割线语义同源）
 - 表单引擎：`FormMain`（form 族）
-- 命令式弹窗体系：`ModalShelf` + `ModalPorter`（薄适配器模式范式见 `list-page/guide/DetailModalItem.vue`）
+- 命令式弹窗体系：`ModalShelf` + `ModalPorter`（薄适配器模式范式见 `list-layout/guide/DetailModalItem.vue`）
 - 类型：`DetailType`、`ModalLayerType`、`ModalDirection`（modal/types.ts）
-- 范式页：`apps/reference/src/pages/list-page/guide/`、`apps/reference/src/pages/modal/guide/`
+- 范式页：`apps/reference/src/pages/list-layout/guide/`、`apps/reference/src/pages/modal/guide/`

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

@@ -87,6 +87,6 @@ const modalList: RegisterEntry[] = [
 - 架子宿主：`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/`）
+- 弹窗组件族：`ModalConfirm` / `ModalForm` / `ModalDetail`（作注册表 item；DetailModalItem 薄适配器范式见 `list-layout/guide/`）
 - 类型：`RegisterEntry<K>`、`ModalSameKeyStrategy`（"recreate" 默认 / "update" 整体替换 props 不 remount）
 - 范式页：`apps/reference/src/pages/modal/porter/showcase/`、`apps/reference/src/pages/modal/guide/`

package/src/components/panel/README.md

@@ -2,7 +2,7 @@
 
 配置驱动详情面板：`PanelMain` 消费 `PanelItemConfig` 列表，只读渲染 + 就地编辑（editorConfig / editorRender 三分支）+ 嵌套（C2 / C3）。
 
-> ⚠️ **`PanelMain` 一等公民地位撤销 · 将废弃**：页级纯展示场景将由 `ViewLayout`（展示布局组件，后续迭代）承接——PanelMain 定位为 ViewLayout 默认插槽内容 / 表单预览与就地编辑场景保留。新页面 [MUST NOT] 以 PanelMain 作页级展示根容器；存量页面仅预览/编辑态保留使用。
+> ⚠️ **`PanelMain` 一等公民地位撤销 · 将废弃**：页级纯展示场景将由 `ViewLayout`（展示布局组件）承接——PanelMain 定位为 ViewLayout 默认插槽内容 / 表单预览与就地编辑场景保留。新页面 [MUST NOT] 以 PanelMain 作页级展示根容器；存量页面仅预览/编辑态保留使用。
 
 ## 组件文档（docs/）
 

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

@@ -5,9 +5,9 @@
 
 ## 定位
 
-- ⚠️ **将废弃（一等公民地位撤销）**：页级纯展示场景由 `ViewLayout`（展示布局，后续迭代）承接——PanelMain 定位为 ViewLayout 默认插槽内容；**表单预览 / 就地编辑场景保留**。新页面 [MUST NOT] 以 PanelMain 作页级展示根容器
+- ⚠️ **将废弃（一等公民地位撤销）**：页级纯展示场景由 `ViewLayout`（展示布局）承接——PanelMain 定位为 ViewLayout 默认插槽内容；**表单预览 / 就地编辑场景保留**。新页面 [MUST NOT] 以 PanelMain 作页级展示根容器
 - **何时用（存量保留场景）**：表单预览 / 就地编辑（配置驱动逐项渲染，单开互斥）
-- **何时不用**：页级纯展示用未来 `ViewLayout`（其默认插槽内放 PanelMain）；纯表格用 `TableMain`；多字段整体录入表单用 `FormMain`；列表 + 录入用 `ListPage`
+- **何时不用**：页级纯展示用 `ViewLayout`（其默认插槽内放 PanelMain）；纯表格用 `TableMain`；多字段整体录入表单用 `FormMain`；列表 + 录入用 `ListLayout`
 - 内部组合：`ElRow` / `ElCol` 栅格承载逐项 `PanelItem`；编辑态**单开互斥**（打开一项自动清空其余）
 - 行为：`list` 变化时修剪 `editingMap`；卡片与裸排分别加 `panel-main-item-col-wrap_card` / `_plain` class
 
@@ -26,12 +26,12 @@
 
 ## 能力边界 / 按需使用
 
-- ⚠️ **将废弃**：页级展示场景将由 `ViewLayout`（后续迭代）承接——新页面 [MUST NOT] 以 PanelMain 作页级展示根容器（纯展示场景：待 ViewLayout 落地后以 PanelMain 为其默认插槽内容）
+- ⚠️ **将废弃**：页级展示场景由 `ViewLayout` 承接——新页面 [MUST NOT] 以 PanelMain 作页级展示根容器（纯展示场景：以 PanelMain 为其默认插槽内容（ViewLayout 已落地））
 - **存量保留场景**：表单预览 / 就地编辑——只传 `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。
+- `itemCard`：默认不套卡片（裸 div `_plain`）；仅当需要每项卡片化展示时传对象/true。卡片模式每项底部默认 `margin-bottom: 10px`（防多行卡片咬在一起，末项不加）；`lastMarginBottom` 显式对象态覆盖（含空字符串 = 取消间距）。
 - `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/`——能力展示，非推荐默认。
@@ -48,7 +48,7 @@
 | `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，现在默认不套卡片） |
+| `itemCard` | `boolean \| Partial<CardProps & { lastMarginBottom?: string }>` | 无默认 | 是否给每项包 ElCard；卡片模式每项底部默认 `margin-bottom: 10px`（末项不加），`lastMarginBottom` 对象态覆盖（含空字符串 = 取消间距）。⚠️ 旧默认 `{lastMarginBottom:'8px'}` 已移除（breaking，现在默认不套卡片） |
 | `refreshFn` | `(currentStringifyData: any, key: string) => Promise<unknown> \| void` | — | render/editorRender 内 scope.refresh() 的旁路刷新回调；不承接 editorConfig 提交成功（那走 submitSuccess） |
 
 ### Emits

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

@@ -9,7 +9,7 @@
 - **何时不用**：整页级左右布局交给 app-layout 族（AppSidebar / AppAside）；只差一个静态侧栏时直接写两列 flex
 - 内部组合：基于 `SlotLayoutTemplate` 组合（两侧各一个实例），非分离态下不做 absolute、不占位让位
 - 分离态行为：`type` 决定侧栏贴左 / 贴右；`asideWidth` 控制侧栏宽；`asideMaxHeight` 限高、超出滚动；主区 padding 为侧栏让位（含 -1px 亚像素补偿）
-- 消费方：ListPage `separateSearch`（搜索 / header / 操作区整体移入侧栏）即基于本组件
+- 消费方：ListLayout `separateSearch`（搜索 / header / 操作区整体移入侧栏）即基于本组件
 
 ## 快速上手（最小可用）
 
@@ -38,7 +38,7 @@
 
 ## 能力边界 / 按需使用
 
-- **`v-model:separate`：默认 `false`（常规文档流）即够用。** 仅当侧栏需要「绝对定位脱离文档流 + 主区自动让位」才开分离态——判据：侧栏内容超高需独立滚动、且不挤占主区布局（ListPage `separateSearch` 把搜索 / header / 操作区整体移入侧栏即此场景）。
+- **`v-model:separate`：默认 `false`（常规文档流）即够用。** 仅当侧栏需要「绝对定位脱离文档流 + 主区自动让位」才开分离态——判据：侧栏内容超高需独立滚动、且不挤占主区布局（ListLayout `separateSearch` 把搜索 / header / 操作区整体移入侧栏即此场景）。
 - **`type` / `gap` / `asideWidth`：默认贴右 / `12px` / `240px` 即够用。** 仅当侧栏要贴左、间距或宽度与默认不同才显式传。
 - **`asideMaxHeight`：默认 `100vh` 即够用（容器内实际取 `min(100%, 100vh)`）。** 仅当容器超高、需要限高承接侧栏滚动才显式限高——判据：侧栏内容比容器高且要独立滚动（超高滚动依赖分离态 + `asideMaxHeight`，两者缺一不可）。
 - **完整能力演示**（全 props 分离态互动面板）：`apps/reference/src/pages/slot-layout/showcase/Index.vue`——能力展示，非推荐默认。
@@ -79,5 +79,5 @@
 ## 关联
 
 - 内部基石：`SlotLayoutTemplate`（slot-layout 族）
-- 消费方：`ListPage` `separateSearch`（list-page 族）
+- 消费方：`ListLayout` `separateSearch`（list-layout 族）
 - 范式页：`apps/reference/src/pages/slot-layout/showcase/Index.vue`

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

@@ -1,11 +1,11 @@
 # TableMain（配置化数据表格）
 
 > 配置化表格：列配置（ElTableColumnProps 超集）驱动渲染 + 内置分页 / 工具栏 / 骨架屏 / 精细化布局高度链。
-> 范式页：`apps/reference/src/pages/table/toolbar/`（工具栏）、`apps/reference/src/pages/table/skeleton/`（骨架屏 + fillHeight）、`apps/reference/src/pages/list-page/guide/`（与 FormSearch 组合成列表页）
+> 范式页：`apps/reference/src/pages/table/toolbar/`（工具栏）、`apps/reference/src/pages/table/skeleton/`（骨架屏 + fillHeight）、`apps/reference/src/pages/list-layout/guide/`（与 FormSearch 组合成列表页）
 
 ## 定位
 
-- **空间一等公民是 `ListPage`**：常规列表页 [MUST] 走 `ListPage`（内部已组合 FormSearch + TableMain + 高度链 + 分页 + 粘性，常用配置提升为直属 prop；TableMain 恒收 `refine=false`）——**TableMain 一般不直接使用**
+- **空间一等公民是 `ListLayout`**：常规列表页 [MUST] 走 `ListLayout`（内部已组合 FormSearch + TableMain + 高度链 + 分页 + 粘性，常用配置提升为直属 prop；TableMain 恒收 `refine=false`）——**TableMain 一般不直接使用**
 - **直接使用仅当**：纯表格页（无搜索区）/ 嵌入卡片或面板的局部表格 / 特殊布局——此时取数/分页/工具栏/高度链全由自己负责
 - 纯展示静态表格用 ElTable 即可
 - 泛型三参：`T` 行数据类型 / `SQ` 静态查询参数 / `F` 注入对象类型；`query` 变化时重置到第 1 页重新拉取
@@ -133,8 +133,8 @@ const toolbarConfig: TableToolbarConfig<Row> = {
 
 ## 关联
 
-- 组合页：`ListPage`（list-page 族，内部 FormSearch + TableMain，常用配置提升为直属 prop，TableMain 恒收 `refine=false`）
+- 组合页：`ListLayout`（list-layout 族，内部 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/`
+- 范式页：`apps/reference/src/pages/table/toolbar/`、`apps/reference/src/pages/table/skeleton/`、`apps/reference/src/pages/list-layout/guide/`

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

@@ -0,0 +1,11 @@
+# view-layout 展示布局族
+
+展示空间布局壳：`ViewLayout` 消费 `props.api`（内部 `useActivated` 激活拉取）+ 右上角 `AutoRefreshGroup`（自动刷新 / 手动刷新）+ 默认插槽自由内容。
+
+## 组件文档（docs/）
+
+- [ViewLayout](./docs/README-ViewLayout.md) — 展示布局（api 拉取 + 自动刷新 + 自由内容插槽）
+
+## 范式页（apps/reference）
+
+- `/view-layout/guide`（api + 插槽内容自由编排，可放 PanelMain 或直接写）

package/src/components/view-layout/docs/README-ViewLayout.md

@@ -0,0 +1,81 @@
+# ViewLayout（展示布局）
+
+> 展示空间布局壳：`props.api` 数据拉取（内部 `useActivated` 激活拉取）+ 右上角 `AutoRefreshGroup`（自动刷新 / 手动刷新）+ 默认插槽自由内容 + 精细流高度链（refine 默认开）。
+> 范式页：`apps/reference/src/pages/view-layout/guide/`
+
+## 定位
+
+- **空间一等公民**：展示空间布局首选（页级数据展示的布局壳）——承接 PanelMain 废弃的页级展示场景
+- **何时用**：页级数据展示（详情 / 预览 / 摘要展示）——api 拉数 + 自动刷新 + 内容自由编排
+- **何时不用**：结构化详情字段面板用 `PanelMain`（仅表单预览 / 就地编辑保留场景）；列表用 `ListLayout`
+- 内部组合：`AutoRefreshGroup`（右上角，refreshFn=api 拉取，经 `HeightProvider` #header 槽 WatchSize 量高）+ 默认插槽（`{ data, loading, refresh, viewportHeight }` 注入）
+
+## 快速上手（最小可用）
+
+```vue
+<ViewLayout :api="fetchDetail">
+  <template #default="{ data, loading, refresh, viewportHeight }">
+    <div v-loading="loading" :style="{ maxHeight: viewportHeight + 'px' }">
+      <!-- 纯展示自由编排：PanelMain 或直接写内容均可；超高内容内滚 -->
+      <pre>{{ data }}</pre>
+    </div>
+  </template>
+</ViewLayout>
+```
+
+**要点**：
+
+- `api` 必传：`(params?: P) => Promise<R>`，params 来自 `props.params`（不传则 api 收 undefined）
+- 激活即拉取：首访 mounted / KeepAlive 重新激活自动拉取，失活不拉（数据保留）
+- 右上角 AutoRefreshGroup 自动接管刷新按钮 / 自动刷新开关（`showAutoRefresh` / `showRefresh` 控制显隐）
+- **refine 默认开**：内容区可用高 = 视口高 − toolbar 高（`scope.viewportHeight` + 容器 max-height 双出口）——超高内滚
+
+## 能力边界 / 按需使用
+
+- **默认即够用**：`api` + 默认插槽即得完整展示布局——refine 精细流 + 自动刷新开关/刷新按钮默认开。
+- **refine（精细流）：默认 `true` 即够用。** 仅当展示内容无需视口高度预算（按自身尺寸渲染即可）才关 `refine`——关闭后 scope viewportHeight 为 undefined。
+- `viewportHeight` / `channel` / `parentChannel`：默认不用。仅当 ViewLayout 需要参与可用高 scope 链（显式视口高 / 作为父提供 scope / 作为子定向消费祖先 scope）才配；⚠️ 每级 [MUST] 显式 `refine`、channel 名 [MUST NOT] 响应式变更。
+- `params`：仅当 api 需要拉取参数时传；⚠️ **响应式变化不自动重拉**（需要时调 `scope.refresh()`）。
+- `showAutoRefresh` / `showRefresh`：仅当不需要自动刷新或手动刷新时关。
+- **插槽内容自由编排**：纯展示 [MUST NOT] 套 PanelMain 作页级根（已废弃场景）；需要结构化字段面板时在插槽内用 PanelMain，自由内容直接写。
+- **完整能力演示**：`apps/reference/src/pages/view-layout/guide/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `P` 拉取参数 / `R` 数据）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `api` | `(params?: P) => Promise<R>`（必填） | — | 数据拉取函数；每次拉取（激活 / 手动刷新 / 自动刷新）传入 props.params（未传收 undefined） |
+| `params` | `P?` | — | 拉取参数；响应式变化不自动重拉（调 `scope.refresh()`） |
+| `refine` | `boolean?` | `true` | 精细流：包 HeightProvider 精确扣 toolbar reserve（WatchSize 量高），内容区可用高 + scope viewportHeight；false=自然流 |
+| `viewportHeight` | `number?` | — | 显式视口高，优先级最高；未传降级 inject SCOPE_VIEWPORT_MAX_HEIGHT scope 链 |
+| `channel` | `string?` | — | 作为父时的 scope 标识。⚠️ 与 parentChannel 均 [MUST NOT] 响应式变更（setup 期快照）；且仅 refine=true 路径生效 |
+| `parentChannel` | `string?` | — | 作为子时定向消费的祖先 scope 标识（沿对象链 parent 找匹配） |
+| `minHeight` | `number?` | `100` | 内容区可用高兜底下限（对齐 ListLayout/TabsMain 惯例） |
+| `showAutoRefresh` | `boolean?` | `true` | 是否显示自动刷新开关（透传 AutoRefreshGroup） |
+| `showRefresh` | `boolean?` | `true` | 是否显示手动刷新按钮（透传 AutoRefreshGroup） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| 默认 | `{ data, loading, refresh, viewportHeight }`（`ViewLayoutScope<R>`） | 展示内容；PanelMain 或自由编排皆可；viewportHeight refine 时给可用高、自然流 undefined |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **纯展示套 PanelMain 作页级根**：PanelMain 已废弃页级展示场景（见 panel 族文档）——纯展示在插槽内自由编排
+- **channel / parentChannel 响应式变更**：[MUST NOT]——setup 期快照，后续变更无效；缺 refine 的 channel 链静默失效
+- **api 抛错不吞**：api 内部自行处理错误（ViewLayout 只保证 loading 复位，不拦截异常）
+
+## 关联
+
+- 内部组合：`AutoRefreshGroup`（misc 族）/ `HeightProvider` + `WatchSize`（display 族）/ `useActivated` / `useChannelViewportHeight`（hooks 桶）
+- 高度链：`SCOPE_VIEWPORT_MAX_HEIGHT` scope 链（viewportHeight / parentChannel 消费侧）
+- 定位衔接：PanelMain 一等公民撤销（将废弃）——ViewLayout 承接页级展示
+- 范式页：`apps/reference/src/pages/view-layout/guide/`

package/types/components/app-layout/app-page-geometry.d.ts

@@ -30,7 +30,7 @@ export interface AppPageSlotSizes {
 /**
  * 扣掉 top/bottom 槽后的内容视口可用高（纯函数，钳非负）。
  *
- * `useChannelViewportHeight` 消费方（ListPage / TableMain / TabsRefineFlow / TabsTile refine）兜底都取
+ * `useChannelViewportHeight` 消费方（ListLayout / TableMain / TabsRefineFlow / TabsTile refine）兜底都取
  * `BODY_CONTENT_VIEWPORT_HEIGHT`，而 AppBody 给的高不含 AppPage 四槽 → 有 top/bottom 槽时会多算、内容压槽。
  * AppPage（四槽 owner）据此扣槽后**同键重 provide**，四家一次修好。左右槽只减宽、不影响高，故只扣 top/bottom；
  * 扣减量与 shim padding 同式（见 {@link appPageSlotInset}）以与内容内缩一致。