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

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

@@ -0,0 +1,81 @@
+# AppBody（内容主体·RouterView + KeepAlive + 面包屑 affix）
+
+> 页面内容渲染体：内置 RouterView（depth-0 KeepAlive）+ 内容区顶部面包屑 affix + #footer 槽 + 视口高度链 provide。
+> 范式页：`apps/reference/src/App.vue`（AppLayout 持 AppBody 塞进 shell 默认槽）、`apps/reference/src/pages/app-layout/layout/`（NoBreadcrumb/NoFooter/NoHeader/NoSidebar 显隐变体）
+
+## 定位
+
+- AppLayout 内部持有（喂 menuFlatList 守高度链），经 shell 默认槽塞入——消费方通常不直接挂载
+- 默认内容 = 内置 RouterView + KeepAlive（keepAliveMaxCount 读 `bridge.APP_ROUTER_CONFIG`）+ 面包屑 affix（showBreadcrumb 经 appStore 控制）
+- 高度链源头：provide `BODY_CONTENT_VIEWPORT_HEIGHT` / `SCOPE_VIEWPORT_MAX_HEIGHT`（新老 key 并列同源）/ `BODY_CONTENT_VIEWPORT_RECT` / `BODY_CONTENT_VIEWPORT_INSET`——后代页面（AppPage 等）消费
+- #footer 槽接 AppLayout 组装 shell 吐出的 Footer 组件（内置默认吐 AppFooter）
+
+## 快速上手（最小可用）
+
+AppBody 由 AppLayout 自动装配，无需手动挂载——总装配见 AppLayout 文档：
+
+```vue
+<AppLayout
+  :bridge="appCoreBridge"
+  :appStore="appStore"
+  :userStore="userStore"
+  :watermarkContent="watermarkContent"
+>
+  <template #brand><AppBrand /></template>
+  <template #userEntry><UserHeaderAction /></template>
+  <template #aside><ChatAsidePanel /></template>
+</AppLayout>
+```
+
+**要点**：
+
+- `menuFlatList` 扁平菜单：面包屑匹配（route.matched 逐项查 menuFlatList 出链）+ 子零件高度链
+- 路由级 keepAlive：路由 meta.keepAlive 开 + 「真叶子」判定（matched 链最深 component-bearing 记录）才进 KeepAlive；缓存数上限 `bridge.APP_ROUTER_CONFIG.keepAliveMaxCount`
+- 视口高重算：激活态绑 resize 监听重算（useActivated 绑解成对），KeepAlive 失活自动解绑
+- 面包屑：showBreadcrumb（appStore）开时内容区顶部 ElAffix 吸附，affix 高度经 `bridge.APP_LAYOUT_BREADCRUMB_CONFIG` 驱动（bridge.update 后跟随）
+
+## 能力边界 / 按需使用
+
+- **面包屑 affix 是自动行为，零配置**：AppBody 内嵌 ElAffix 面包屑——显隐由 `appStore.showBreadcrumb` 控制、高度经 `bridge.APP_LAYOUT_BREADCRUMB_CONFIG` 驱动，「有链时内容区自动让位 affix 高度」由内部承担。常规页面无需挂任何 prop。
+- **KeepAlive 承接是自动行为，零配置**：开不开缓存由路由 `meta.keepAlive` + 真叶子判定声明（缓存上限读 bridge config）——本组件无开关，页面按需声明即可。
+- `menuFlatList`：AppLayout 内部已喂入（守高度链）——消费方通常不需要自己传；仅直接挂载 AppBody（非经 AppLayout）时才需要。
+- `#footer` 槽：默认已由 AppLayout 组装 shell 吐出的 Footer 组件填好（内置吐 AppFooter）——仅自供 shell 时才需要接管。
+- **完整能力演示**（NoBreadcrumb/NoFooter/NoHeader/NoSidebar 显隐变体）：`apps/reference/src/pages/app-layout/layout/`
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `menuFlatList` | `RouteMetaResolveRaw[]` | `() => []` | 扁平菜单（面包屑匹配 + 子零件高度链） |
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#footer` | 无 | AppLayout 组装 shell 吐出的 Footer 组件落点 |
+
+默认内容 = 内置 RouterView + KeepAlive（keepAliveMaxCount 读 bridge.APP_ROUTER_CONFIG）——不提供可替换的默认 slot。
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **勿手写 RouterView 双分支**：keepAlive 判据（真叶子 + meta.keepAlive 合并语义）与渲染 key 策略（叶子按 route.path 按 params 隔离、壳按壳 record path 稳定单实例）由 `keep-alive.ts` 内部工具承担，[MUST NOT] 自造
+- 高度链几何真相由 AppBody 写、后代只读（readonly 包装）——裸 ref 下放后代一句 `.value=` 即反向污染（写只读视图 dev warn + no-op）
+- 面包屑高度经 bridge.APP_LAYOUT_BREADCRUMB_CONFIG 追踪，勿静态快照
+
+## 关联
+
+- 内部工具：`keep-alive.ts`（isKeepAliveRoute / keepAliveRouteKey，不导出）
+- 面包屑：`AppBreadcrumb`（affix 内嵌 + `@show` 让位）
+- 注入键：`APP_LAYOUT_APP_STORE_KEY` / `APP_LAYOUT_BRIDGE_KEY` / `BODY_CONTENT_VIEWPORT_HEIGHT` / `BODY_CONTENT_VIEWPORT_RECT` / `BODY_CONTENT_VIEWPORT_INSET` / `SCOPE_VIEWPORT_MAX_HEIGHT`
+- 范式页：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/layout/`

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

@@ -0,0 +1,71 @@
+# AppBreadcrumb（面包屑积木）
+
+> 面包屑积木：menuFlatList 扁平菜单匹配 route.matched 出链，ElBreadcrumb 渲染；emit show 报有链/无链。
+> 使用场景：内置 AppBody 已内嵌（ElAffix 顶部吸附）；自供 shell/自定义内容区可按需直引。
+
+## 定位
+
+- 链来源：route.matched 逐项在 menuFlatList 中按 path 命中 → 面包屑链（无链 = 空）
+- 高度由 `height` 指定（px），链路渲染 ElBreadcrumbItem（to = item.path）
+- `show` emit（immediate watch）：有链 true / 无链 false——宿主（AppBody）据此让出内容区高度（affix 高度）
+
+## 快速上手（最小可用）
+
+常规页面无需直引（见能力边界）；仅自供内容区直引时提供 `height` + `menuFlatList` 两必填 prop（形态同 AppBody 内嵌用法）：
+
+```vue
+<AppBreadcrumb
+  :height="24"
+  :menuFlatList="menuFlatList"
+  @show="onAffixShow"
+/>
+```
+
+**要点**：
+
+- 有链才渲染（v-show + show emit）；无链时高度让位由宿主处理
+- `show` emit 是 immediate watch——挂载即报当前状态
+- 匹配是 path 精确命中（route.matched 逐项 find）
+
+## 能力边界 / 按需使用
+
+- **常规页面零配置——勿重复直引**：AppBody 已内嵌 affix 面包屑（显隐 `appStore.showBreadcrumb`、高度 `bridge.APP_LAYOUT_BREADCRUMB_CONFIG`），常规页面 [MUST NOT] 再叠一层直引。
+- **仅自供内容区/自定义 shell 才直引**——判据：宿主不是 AppBody。直引时提供 `height` + `menuFlatList` 两必填 prop，并自行处理 `@show` 高度让位（内容区减去 height）。
+- 链路 = route.matched ∩ menuFlatList——中间页未登记进 menuFlatList 则不出现（可预期，无需处理）。
+- **完整能力演示**（NoBreadcrumb 变体）：`apps/reference/src/pages/app-layout/layout/`
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `height` | `number`（必填） | — | 面包屑高度 px |
+| `menuFlatList` | `RouteMetaResolveRaw[]`（必填） | — | 匹配 route.matched 出面包屑链 |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `show` | `status: boolean` | 有链 true / 无链 false（immediate watch） |
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- 链路 = route.matched ∩ menuFlatList——未登记进 menuFlatList 的中间页不出现（可预期）
+- 自身只报 show 状态，高度让位（内容区减去 height）由宿主（AppBody affix 逻辑）处理
+- 内置 AppBody 已内嵌——常规页面 [MUST NOT] 再叠一层直引面包屑
+
+## 关联
+
+- 宿主：`AppBody`（ElAffix 内嵌 + contentViewHeight 让位）
+- 配置：bridge.APP_LAYOUT_BREADCRUMB_CONFIG（高度，bridge.update 后跟随）
+- 范式页：`apps/reference/src/pages/app-layout/layout/`（NoBreadcrumb 变体）

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

@@ -0,0 +1,41 @@
+# AppFooter（底部状态条积木）
+
+> 底部状态条积木：零 props/emits/slots/expose——高度与样式完全由 `appStore.footerStyle` 驱动（inject APP_LAYOUT_APP_STORE_KEY 直取），随 store 变化 0.3s 过渡。
+> 使用场景：AppLayout 组装 shell 吐出的 Footer 组件引用，经 AppBody #footer 槽落位（内置默认 AppShell 吐 AppFooter）。
+
+## 定位
+
+AppFooter 是族内最薄的积木：自身无任何对外接口（无 props / emits / slots / expose），只做一件事——inject 应用 store 窄化实例（`APP_LAYOUT_APP_STORE_KEY`），把 `appStore.footerStyle` 绑到根盒 `:style` 上渲染底部状态条（高度/留白/阴影由 store 驱动，阴影走主题 var）。显隐与高度变化全部由 AppLayout/store 侧控制，消费方不直接挂载、也无可配置项。
+
+## 能力边界 / 按需使用
+
+- **零配置、零 props——样式与显隐全由 `appStore.footerStyle` 驱动**（随 store 变化 0.3s 过渡）：要改高度/显隐走 store（footerStyle），[MUST NOT] 给 AppFooter 加 props 透传；消费方不直接挂载（内置经典布局已经 shell → AppBody #footer 自动落位）。**完整能力演示**（NoFooter 变体）：`apps/reference/src/pages/app-layout/layout/`
+
+## API
+
+### Props
+
+无
+
+### Emits
+
+无
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **勿给 AppFooter 加 props 透传**：其样式是 store 真相源（footerStyle），不是 prop 驱动——要改高度/显隐走 store
+- 消费方不应直接挂载——内置经典布局已经 shell → AppBody #footer 自动落位
+
+## 关联
+
+- 落位链：AppLayout → AppShell 默认 scoped slot（`AppShellDefaultSlotScope`：`{ Footer: Component }`）→ AppBody #footer
+- store：`APP_LAYOUT_APP_STORE_KEY`（footerStyle 驱动）
+- 范式页：`apps/reference/src/pages/app-layout/layout/`（NoFooter 变体）

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

@@ -0,0 +1,73 @@
+# AppHeader（顶栏积木）
+
+> 顶栏布局积木：#left 品牌/业务入口 + 路由大模块菜单 + #right 操作区（userEntry/settings/themeSwitcher 落位）。
+> 范式页：`apps/reference/src/pages/app-layout/shell/`（自供 shell 积木直引）、`apps/reference/src/pages/app-layout/layout/`（NoHeader 显隐变体）
+
+## 定位
+
+- **何时用**：内置 AppShell 经典布局已直引；自供 shell 时按需复用
+- #left = 品牌/业务入口（AppLayout `#brand` 锚落位）；#right = userEntry/settings/themeSwitcher 操作区
+- 中间区 = 路由大模块菜单（menus 渲染，点击高亮 activeModulePath）
+- 整体显隐由 AppLayout 间接控制（store headerStyle.height=0 视觉收起 + dom 保留）
+
+## 快速上手（最小可用）
+
+经 AppLayout 内容锚填充后由 shell 落位（App.vue 范式——#brand/#userEntry 即 Header #left/#right 的内容来源）：
+
+```vue
+<AppLayout :bridge="appCoreBridge" :appStore="appStore" :userStore="userStore">
+  <template #brand><AppBrand /></template>
+  <template #userEntry><UserHeaderAction /></template>
+</AppLayout>
+```
+
+**要点**：
+
+- 自供 shell 直引积木时，把 AppLayout 内容锚转发到对应槽（见 AppSidebar 文档的 DemoCustomShell 槽转发范式）
+- `menus` 渲染路由大模块（带 menuIcon 时图标 + 标题）；`menuFlatList` 扁平菜单（必填）供内部匹配
+
+## 能力边界 / 按需使用
+
+- **`show` 勿用于显隐**：声明必填但模板未消费（仅预留未来定位子元素 v-if 接口）——整体显隐由 AppLayout 经 store 间接控制（`headerStyle.height=0` 视觉收起 + dom 保留），默认即够用，[MUST NOT] 自行传值。
+- **中间区模块菜单按需**：`menus` / `activeMenu` / `activeModuleMenu` 仅当需要「路由大模块菜单」时才填（默认空数组即无中间菜单区）；`menuFlatList` 必填（内部匹配）。
+- `#left` / `#right` 槽内容来自 AppLayout 内容锚转发（`#brand` → `#left`；`#userEntry` / `#settings` / `#themeSwitcher` → `#right`）——内置 shell 零配置；自供 shell 直引时按槽转发范式接住。
+- **完整能力演示**（自供 shell 积木直引 + NoHeader 变体）：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必填） | — | ⚠️ 模板内实际未消费（仅预留未来定位子元素 v-if 接口，源码注释口径） |
+| `menus` | `RouteMetaResolveRaw[]` | `() => []` | 模块菜单 |
+| `activeMenu?` | `RouteMetaResolveRaw` | 无 | 聚焦的路由菜单 |
+| `activeModuleMenu?` | `RouteMetaResolveRaw` | 无 | 聚焦的模块菜单 |
+| `menuFlatList` | `RouteMetaResolveRaw[]`（必填） | — | 扁平菜单 |
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#left` | 无 | 品牌/业务入口（AppLayout #brand 落位） |
+| `#right` | 无 | userEntry/settings/themeSwitcher 操作区 |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **`show` 勿用于显隐控制**：声明必填但模板未消费——整体显隐由 AppLayout 经 store 间接控制（headerStyle.height=0 视觉收起 + dom 保留）
+- 主题切换器不属 Header 私有：已解耦为 `AppTheme`，经 shell #right 注入（默认内容仍是 AppTheme，经典布局 1:1 镜像）
+
+## 关联
+
+- 内容锚：`#brand` → `#left`；`#userEntry` / `#settings` / `#themeSwitcher` → `#right`（落位见 AppLayout 文档）
+- 主题切换：`AppTheme`（themeSwitcher 默认内容）
+- 范式页：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`

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

@@ -0,0 +1,83 @@
+# AppLayout（应用布局总控·数据桥）
+
+> 应用壳顶层组件：bridge/appStore/userStore 三注入 provide 子树 + 5 个内容锚（brand/userEntry/settings/themeSwitcher/aside）+ 内置默认经典布局 shell（布局插件可自供 shell 替换）。
+> 范式页：`apps/reference/src/App.vue`（族总装配）、`apps/reference/src/pages/app-layout/shell/`（自供 shell）
+
+## 定位
+
+- **何时用**：应用根组件——任何页面级应用的最外层骨架（App.vue 直接挂载）
+- **何时不用**：布局形态深度定制时仍用它——通过布局插件自供 shell（AppShell 契约）替换内置默认，AppLayout 只承担数据桥/机制
+- 职责边界：数据桥（三注入）+ 内容锚转发 + 水印；布局形态（sidebar/header 落位、折叠策略）归 shell（内置默认 AppShell = 经典布局 1:1 镜像）
+- 页面内容**不经 AppLayout 默认 slot**——AppLayout 持 AppBody 塞进 shell 默认槽，AppBody 渲染 RouterView（见 AppBody 文档）
+
+## 快速上手（最小可用）
+
+App.vue 总装配——三个必填注入 + 两个必填内容锚即完整可跑：
+
+```vue
+<AppLayout :bridge="appCoreBridge" :appStore="appStore" :userStore="userStore">
+  <template #brand><AppBrand /></template>
+  <template #userEntry><UserHeaderAction /></template>
+</AppLayout>
+```
+
+**要点**：
+
+- `bridge` / `appStore` / `userStore` 三实例经 props 注入后 provide 子组件（`APP_LAYOUT_BRIDGE_KEY` / `APP_LAYOUT_APP_STORE_KEY` / `USER_STORE_KEY`）——主题切换、布局配置等跨层能力靠它们直读直写（见 AppTheme 文档）
+- 内容锚只填「业务语义」，**落位权归 shell**（经典布局落位：brand → Header #left；userEntry/settings/themeSwitcher → Header #right；aside → AppAside 默认槽）
+
+## 能力边界 / 按需使用
+
+- **内容锚按需填**：`#brand` / `#userEntry` 是应用根必填（品牌 + 用户入口，缺则 Header 落位区空）；`#settings` / `#themeSwitcher` / `#aside` 默认可缺省——没有对应能力（设置入口 / 主题切换 / 右侧面板）就不填，shell 对应落位区空渲染。
+- `watermarkContent`：默认不展示水印；仅需要页面水印时填内容（空数组/空串/undefined 即关闭；显隐走 content 切换，无独立开关 prop）。
+- `sidebarAboveHeader`：默认 `false` 即够用；仅当 sidebar 需要 z-index 盖住 header 悬浮时开。
+- **布局形态深度定制**：内置默认经典布局 shell 已可用（行为基线 [MUST NOT] 借重构改）；仅当落位/折叠策略不满足时才走布局插件自供 shell（AppShell 契约）——AppLayout 本身不动。
+- **完整能力演示**（五锚全填 + 水印 + 自供 shell）：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`——能力展示，非最小起点。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `bridge` | `AppLayoutBridgeSlice`（必填） | — | 布局桥窄化实例，注入后 provide 子组件（APP_LAYOUT_BRIDGE_KEY） |
+| `appStore` | `AppLayoutAppStoreSlice<UserInfo>`（必填） | — | 应用 store 窄化实例（APP_LAYOUT_APP_STORE_KEY） |
+| `userStore` | `AppLayoutUserStoreSlice<UserInfo>`（必填） | — | 用户 store 窄化实例（USER_STORE_KEY） |
+| `watermarkContent` | `WatermarkProps["content"]` | 无默认 | 水印内容；空数组/空串/undefined 则关闭水印 |
+| `sidebarAboveHeader` | `boolean` | `false` | sidebar z-index 高于 header |
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#brand` | 无 | 品牌/应用名（经 shell 落位 Header #left） |
+| `#userEntry` | 无 | 用户入口（登录态/用户下拉，经 shell 落位 Header #right） |
+| `#settings` | 无 | 设置入口（经 shell 落位 Header #right，紧随 userEntry） |
+| `#themeSwitcher` | `AppShellAnchorScope`（`{ Default?: Component }`，缺省 = 内置 AppTheme） | 主题切换（业务可覆盖默认内容） |
+| `#aside` | 无 | 右侧补充区内容（经 shell 落位 AppAside 默认槽） |
+
+**无默认 slot**——页面内容不经 AppLayout，而是经 shell 默认槽 → AppBody 渲染 RouterView。
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **别找 AppLayout 的默认 slot**：页面内容由 AppBody（内置 RouterView）渲染，AppLayout 只承接内容锚
+- **内容锚只填内容、不决定落位**：落位权归 shell；自供 shell 时按 AppShell 契约接住整组内容锚（v-for 透传）
+- **布局形态改动不动 AppLayout**：经典布局行为基线在内置 AppShell 模板（[MUST NOT] 借重构改其行为），定制布局走布局插件自供 shell
+- **水印显隐走 content 切换**，无独立开关 prop
+
+## 关联
+
+- 布局插件自供 shell 契约：`AppShellProps` / `AppShellEmits`（空）/ `AppShellDefaultSlotScope`（`{ Footer: Component }`）/ `AppShellAnchorScope` / `AppShellSlots`（types.ts）
+- 内部默认 shell：`AppShell`（经典布局 1:1 镜像，不导出）
+- 内容主体：`AppBody`（AppLayout 持之喂 menuFlatList 守高度链）；页面容器：`AppPage`
+- 主题切换：`AppTheme`（themeSwitcher 锚默认内容）
+- 范式页：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`

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

@@ -0,0 +1,80 @@
+# AppPage（页面容器·撑满视口 + 四向悬浮插槽）
+
+> 页面主体容器：默认 slot 按视口高变量撑满（min-height/height 双模式），#top/#bottom/#left/#right 四向 fixed 悬浮插槽（shim 呼吸 + gap 间距）。
+> 范式页：`apps/reference/src/pages/app-layout/page-slots/`（四向悬浮槽 + ChainReadout 高度链互动面板）
+
+## 定位
+
+- **何时用**：每个路由页面的内容根——ListPage/FormMain 等页面骨架的宿主（`<AppPage><ListPage .../></AppPage>`）
+- **何时不用**：无需容器几何（纯组件局部）时直接用裸组件
+- 默认 slot 内容经 ModalShelf page 层包裹（弹层挂载点）
+- 四向悬浮插槽为 fixed 定位（z-index `APP_PAGE_SLOT_Z_INDEX`=1），top/bottom 通栏量高、left/right 量宽，尺寸几何由 `app-page-geometry` 纯函数计算
+
+## 快速上手（最小可用）
+
+常规页面零配置——默认即最佳（撑满 + 页面主体 + ModalShelf page 层）：
+
+```vue
+<AppPage>
+  <ListPage ... />
+</AppPage>
+```
+
+需要视口高度硬撑满时（全屏页面/顶部自撑 tab 页）：
+
+```vue
+<AppPage fullViewport>
+  <ListPage ... />
+</AppPage>
+```
+
+## 能力边界 / 按需使用
+
+- **四向悬浮插槽（`#top`/`#bottom`/`#left`/`#right`）：默认全关、常规页面不需要。** 仅当页面需要「悬浮于内容之上的固定补充区」（通栏操作条 / 侧边抽屉 / 浮动提示）才开对应槽——判据：内容必须 fixed 悬浮且不参与文档流（top/bottom 通栏量高 → padding 让位，left/right 量宽）。列表/表单/详情常规页一律不开。
+- `topBg`/`bottomBg`/`leftBg`/`rightBg`：仅悬浮槽需要着色时设，默认无背景即够用。
+- `*ObserveResize`：仅当槽内内容有 CSS 过渡折叠 / 异步撑开（不触发重渲染的尺寸变化）才开对应 RO；普通槽内容（v-if/v-show/静态）不开。
+- `fullMode`：默认 `"min-height"` 即够用；`"height"` 仅当页面内子级依赖硬高撑满（如顶级自撑 TabsMain）时选。
+- **完整能力演示**（四槽全开 + 背景 + RO 互动面板）：`apps/reference/src/pages/app-layout/page-slots/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `fullViewport` | `boolean` | `false` | 撑满视口 |
+| `fullMode` | `"min-height" \| "height"` | `"min-height"` | 撑满方式 |
+| `nextViewportMaxHeight` | `string` | `var(--app-viewport-max-height)` | shim 内视口高变量覆写 |
+| `background` | `string` | 无 | 根盒背景 |
+| `gap` | `number` | `8` | 悬浮槽与内容间隔 px |
+| `topBg` / `bottomBg` / `leftBg` / `rightBg` | `string` | 无 | 各槽 shim 背景 |
+| `topObserveResize` / `bottomObserveResize` / `leftObserveResize` / `rightObserveResize` | `boolean` | 均 `false` | 逐槽 WatchSize RO 观测（CSS 过渡折叠等非重渲染尺寸变化时开） |
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `default` | 无 | 页面主体（ModalShelf page 层包裹） |
+| `#top` / `#bottom` | 无 | 通栏悬浮槽（量高 → padding-top/bottom） |
+| `#left` / `#right` | 无 | 侧向悬浮槽（量宽） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **悬浮槽尺寸变化来自 CSS 过渡/异步撑开 → 必须开对应 `observeResize`**（onUpdated 只读渲染后瞬时值，过渡动画读起点漏最终）
+- 四向槽 fixed 定位——内容滚动时悬浮不动，属设计语义，勿误当普通 inline 槽
+- 槽尺寸/inset 几何由 `app-page-geometry` 纯函数计算导出，[MUST NOT] 手写自造
+
+## 关联
+
+- 几何纯函数：`app-page-geometry.ts`（computeAppPageReducedViewportHeight/Width、computeAppPageContentInset、computeAppPageSlotStyles、computeAppPageSlotShimStyles + `APP_PAGE_SLOT_Z_INDEX`=1）
+- 高度链：AppBody provide 的 `BODY_CONTENT_VIEWPORT_HEIGHT` / `BODY_CONTENT_VIEWPORT_RECT` / `BODY_CONTENT_VIEWPORT_INSET` / `SCOPE_VIEWPORT_MAX_HEIGHT`
+- 范式页：`apps/reference/src/pages/app-layout/page-slots/`（含 ChainReadout 高度链互动面板）

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

@@ -0,0 +1,70 @@
+# AppSidebar（侧边栏积木）
+
+> 左侧栏积木：折叠把手 + MenuTree 菜单渲染 + #top/#bottom 高度自撑插槽；可 aboveHeader 悬浮盖顶。
+> 范式页：`apps/reference/src/pages/app-layout/shell/`（DemoCustomShell 自供 shell 积木直引）、`apps/reference/src/pages/app-layout/layout/`（NoSidebar 显隐变体）
+
+## 定位
+
+- **何时用**：内置 AppShell 经典布局已直引；自供 shell 时按需复用（菜单/折叠把手/品牌位自由组合）
+- `show` 控制显隐（含折叠把手渲染开关）——false 即不渲染整栏
+- `aboveHeader` 时 z-index 2 盖 header（AppLayout 另有 `sidebarAboveHeader` prop 同源传递）
+- #top/#bottom 高度自撑（WatchSize 反推 shim 边界）——品牌区/挂件放 #top，底部操作放 #bottom
+
+## 快速上手（最小可用）
+
+内置 AppShell 经典布局已直引——自供 shell 需要菜单侧栏时最小直引（三必填 prop）：
+
+```vue
+<AppSidebar :show="showSidebar" :menus="sidebarMenus" :menuFlatList="menuFlatList" />
+```
+
+**要点**：
+
+- `show` / `menus`（MenuTree 渲染）/ `menuFlatList`（内部匹配）三必填
+- 折叠把手状态由族内共享（`AppCollapseToggle` 内部积木），折叠后仅把手占位——零配置
+
+## 能力边界 / 按需使用
+
+- **`#top` / `#bottom` 高度自撑插槽按需**：默认零配置即菜单栏可用；仅当需要品牌区/挂件（`#top`）或底部操作区（`#bottom`）才填——高度自撑（WatchSize 反推 shim 边界），放多少内容撑多高。
+- **`aboveHeader` 默认关**：仅当 sidebar 需要 z-index 2 盖住 header 悬浮时开（与 AppLayout `sidebarAboveHeader` 同源传递，自供 shell 时对齐）。
+- `show=false` 整栏不渲染（含折叠把手）——「收起但保留把手」场景走折叠态而非 `show=false`。
+- **完整能力演示**（DemoCustomShell 槽转发范式 + NoSidebar 变体）：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必填） | — | 显隐（含折叠把手渲染开关） |
+| `aboveHeader` | `boolean` | `false` | z-index 2 盖 header |
+| `menus` | `RouteMetaResolveRaw[]`（必填） | — | sidebar 区菜单（MenuTree 渲染） |
+| `menuFlatList` | `RouteMetaResolveRaw[]`（必填） | — | 扁平菜单 |
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#top` / `#bottom` | 无 | 高度自撑（WatchSize 反推 shim 边界）——品牌区/挂件 / 底部操作区 |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- `show=false` 时折叠把手也随整栏不渲染（把手渲染开关即 show）——「收起但保留把手」场景应走折叠态而非 show=false
+- `aboveHeader` 与 AppLayout `sidebarAboveHeader` 语义一致，自供 shell 时两者对齐（DemoCustomShell 透传范式）
+- 折叠/展开动画由族内积木承担，[MUST NOT] 自造折叠逻辑
+
+## 关联
+
+- 折叠积木：`AppCollapseToggle`（族内共享，AppSidebar/AppAside 内部使用，未导出）
+- 右侧对称积木：`AppAside`
+- 内容锚：`#brand` 等（落位见 AppLayout 文档）
+- 范式页：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`

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

@@ -0,0 +1,66 @@
+# AppTheme（主题切换器积木）
+
+> 主题切换 UI：bridge.theme 直读直写（架构反转——真相源在 bridge，不经 app store）——亮/暗/系统三态恒显 + 风格下拉条件显示。
+> 使用场景：AppLayout `#themeSwitcher` 内容锚默认内容；布局插件可复用作 scope.Default。
+
+## 定位
+
+- 架构反转：主题能力在 bridge——AppTheme 经 `inject(APP_LAYOUT_BRIDGE_KEY)` 拿布局桥窄化实例，直读 bridge 主题态、直写 bridge.theme 动作；store 仅为 isDarkTheme 旧消费方转发兜底，新 UI 走 bridge 直连
+- 亮/暗/系统三态 RadioGroup（icon + tooltip）**恒显**；风格下拉仅 `list.length > 1` 且 `bridge.showThemeStyleSwitcher !== false` 时显示——开关只管风格切换，不影响亮暗
+- 零 props：无对外配置项，行为全由 bridge 态决定
+
+## 快速上手（最小可用）
+
+无 props 可配，挂载即用——经 `#themeSwitcher` 锚由 shell 落位（缺省内容即内置 AppTheme，无需显式引用）：
+
+- 三态切换：亮色 / 暗色 / 跟随系统（icon + tooltip，恒显）
+- 风格切换：已注册风格 > 1 且 `showThemeStyleSwitcher !== false` 时显示下拉（`bridge.theme.labelOf(name)` 渲染显示名）
+
+## 能力边界 / 按需使用
+
+- **亮/暗/系统三态恒显**：挂载即用、无任何开关——默认即够用（`#themeSwitcher` 锚缺省内容即内置 AppTheme，业务不填锚即获得）。
+- **风格下拉条件显示**：仅当「已注册风格 > 1 且 `bridge.showThemeStyleSwitcher !== false`」才显示——只注册一种风格时自动隐藏，无需配置；`showThemeStyleSwitcher` 只管风格切换，不影响亮暗三态。
+- **业务覆盖锚内容时需自供等效切换 UI**：自供 `#themeSwitcher` 锚内容即失去默认切换器——须自供等效 UI 且走 bridge 直读直写（真相源在 bridge，[MUST NOT] 自造主题状态）。
+- **完整能力演示**（自供 shell）：`apps/reference/src/pages/app-layout/shell/`
+
+## bridge 直读直写语义
+
+| 方向 | 访问 | 语义 |
+| --- | --- | --- |
+| 读 | `bridge.themeMode.value` | 当前亮/暗/系统三态 |
+| 读 | `bridge.themeStyle.value` | 当前风格名 |
+| 读 | `bridge.theme.list.value` | 已注册风格名列表（length > 1 才显示风格下拉） |
+| 读 | `bridge.showThemeStyleSwitcher` | 是否显示风格下拉（bridge init 静态选项，缺省 true；亮暗切换不受此控、恒显） |
+| 读 | `bridge.theme.labelOf(name)` | 风格显示名 |
+| 写 | `bridge.theme.setMode(mode)` | 切亮/暗/系统 |
+| 写 | `bridge.theme.setStyle(name)` | 切风格 |
+
+## API
+
+### Props
+
+无
+
+### Emits
+
+无
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **勿绕过 bridge 自造主题状态**：真相源在 bridge，切换一律 `bridge.theme.setMode` / `bridge.theme.setStyle`，[MUST NOT] 手写类名/样式副作用造成双真相
+- 业务无视 themeSwitcher 默认内容时须自供等效切换 UI（声明驱动测试纪律）
+- 风格下拉显隐受 `showThemeStyleSwitcher` 控制；亮暗三态不受此控、恒显
+
+## 关联
+
+- 主题能力：`bridge/theme.ts`（createBridgeThemeHook：风格 map + setStyle/setDark + 持久化）
+- 落位：AppShell `#themeSwitcher` 锚（scope.Default = 内置 AppTheme；业务可覆盖），AppLayout 5 内容锚之一
+- 范式页：`apps/reference/src/pages/app-layout/shell/`

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

@@ -0,0 +1,19 @@
+# data-view 数据视图族
+
+> `DataListView` / `DataListViewItem`：table 的内部衍生品——**仅供 TableMain 内部 import，[MUST NOT] 对外导出 / 全局注册 / 提供 install 插件**（不进 core 顶层 export）。
+> 对外入口：经 `TableMain` 的 `customView` 模式消费（范式页 `apps/reference/src/pages/data-view/custom-view/`）。
+
+## 组件清单
+
+| 组件 | 一句话 | 文档 |
+| --- | --- | --- |
+| `DataListView` | 数据视图列表（卡片/自定义渲染，el-table 形态替代），TableMain `customView` 模式渲染载体 | [README-DataListView](./docs/README-DataListView.md) |
+| `DataListViewItem` | 列表项容器：仅承载选中态 class 钩子（`.is-selected`）+ 项内容插槽 | 并入 README-DataListView 小节 |
+
+族 index.ts 导出 `{ DataListView, DataListViewItem }` + `export * from "./types"`（5 个类型，含 `DataViewColumn<T>` / `DataListViewItemScope<T>`）。
+
+## 内部件边界
+
+- **不进 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>`）
+- **DataListViewItem**：由 DataListView 内部 `v-for` 使用，消费方不直接使用；[MUST NOT] 写死视觉样式（卡片阴影/圆角归消费方）、[MUST NOT] 内置选中状态机