@done-coding/admin-core 0.25.0 → 0.26.0

package/src/components/page-layout/docs/README-AppPageDetail.md

@@ -0,0 +1,57 @@
+# AppPageDetail（详情区 · 可独立成页）
+
+> 详情区组件：**默认自带 `AppPage`，可直接当一个详情路由页用**；`embedded` 开启后走透传态，供 `AppPageListDetailLayout` 内嵌。
+> 范式页：`apps/reference/src/pages/app-layout/list-detail/`
+
+## 两种用法
+
+**① 独立成页（默认 `embedded=false`）** —— 详情走独立路由时用：
+
+```vue
+<AppPageDetail
+  :id="route.params.id"
+  :detail-api="detailApi"
+  :detail-title="(d) => d?.name ?? ''"
+>
+  <template #detail="{ data }"><MyDetail :data="data" /></template>
+</AppPageDetail>
+```
+
+此时 `ctx` 不必传，**无序列导航**（`total=0`、上/下一条两端皆 false）——独立页本就没有「列表上下文」，这是正确语义而非缺失。
+
+**② 被门面内嵌（`embedded=true`）** —— 由 `AppPageListDetailLayout` 内部使用，宿主已有一层 `AppPage`，故透传不再套；门面下发完整 `ctx`（含序列导航句柄）。业务一般不直接这么用。
+
+## API
+
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `embedded` | `boolean` | `false` | `true` = 不套 `AppPage`（宿主已有一层）。⚠️ 内嵌态下本组件无宿主元素，`dc-app-page-detail` 根类与 `$attrs` 随之无落点 |
+| `ctx` | `Omit<AppPageListDetailDetailScope, "data" \| "loading">` | 无 | 完整详情上下文（含序列导航）。**门面内嵌时下发**；独立使用不传 |
+| `id` | `string \| number` | 无 | 独立使用时的当前项键（`ctx` 未传时生效；与 `ctx` 都无 → 落空态） |
+| `record` | `T` | 无 | 独立使用时的当前项数据（`ctx` 未传时生效），供 `detailTitle` / `#detail` 消费 |
+| `detailApi` | `(params?: { id }) => Promise<R>` | 无 | 传了则内置 `ViewLayout`（零配置拿到 `refreshToken` 接线 + 内置上/下一条导航）；不传则 `#detail` 原样渲染、本组件零请求 |
+| `detailTitle` | `string \| ((detailData, record) => string)` | 无 | 详情区标题，渲染在详情区顶部 |
+| `listEmpty` | `boolean` | `false` | 分流两种空态文案；独立使用时通常不关心 |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#detail` | `{ id, record, index, total, hasPrev, hasNext, goPrev, goNext, refreshList, data, loading }` | 详情内容。`data` / `loading` 仅在传了 `detailApi` 时有值；独立使用时序列字段为零值 |
+| `#empty` | `{ listEmpty }` | 无当前项时的占位 |
+
+## 反模式 / 注意
+
+- **独立使用时期待上/下一条** —— 没有列表就没有序列，导航句柄是空操作、两端恒 false。要导航就用门面 `AppPageListDetailLayout`
+- **业务外层再套 `AppPage`** —— 默认态它自己就是 `AppPage`，套了成两层
+- **`embedded=true` 还指望 `dc-app-page-detail` 根类 / `$attrs` 落地** —— 透传态无宿主元素
+- **照抄 `SlotLayoutTemplate :disabled` 的写法去做需要具名槽的组件** —— 透传态只渲染默认槽，具名槽会被整个丢掉
+
+## 关联
+
+- 族系标准与清单：[../README.md](../README.md)
+- 门面：[README-AppPageListDetailLayout.md](./README-AppPageListDetailLayout.md)

package/src/components/page-layout/docs/README-AppPageListDetailLayout.md

@@ -0,0 +1,142 @@
+# AppPageListDetailLayout（列表 / 详情同页范式 · master-detail）
+
+> 把「列表 → 弹窗改 → 关闭 → 刷新」换成「列表选中 → 详情常驻」：一根 `activeId` / `activeData` 状态线打通列表与详情，宽屏并排 / 窄屏抽屉两形态按视口宽定档。
+> 范式页：`apps/reference/src/pages/app-layout/list-detail/`
+
+## 定位
+
+- **页面级组件**：内含 `AppPage`，**页面根即 `.app-page`**。业务页面根**二选一**——普通页用 `AppPage`，列表详情页用本组件；[MUST NOT] 再套一层 `AppPage`，也 [MUST NOT] 塞进弹窗 / Tab。
+- **何时用**：单条记录是主角的场景（工单、会话、任务、审核队列）——用户要在列表与单条之间反复横跳。
+- **何时不用**：纯批量操作（导入导出、批量改状态）——那里单条不是主角，常规 `AppPage` + `ListLayout` 更合适。
+
+## 层级
+
+```
+AppPageListDetailLayout          【L1 门面】无 DOM 输出：持状态 + 形态定档 + provide 上下文
+├─ split → AppPageListDetailSplit   【L2】AppPage：#left = 列表 · 默认槽 = 详情区
+└─ sheet → AppPageListDetailSheet   【L2】AppPage：默认槽 = 列表 · 抽屉 = 详情区
+                                     └─ AppPageListDetailPane 【L3】有当前项 → 详情；无 → 空态
+```
+
+三个实现件（Split / Sheet / Pane）**不对外导出**，是门面的实现细节。
+
+## 快速上手
+
+```vue
+<AppPageListDetailLayout
+  v-model:active-id="activeId"
+  v-model:active-data="activeData"
+  :detail-api="detailApi"
+>
+  <template #list="{ listProps }">
+    <!-- ⚠️ listProps [MUST] 整体 v-bind，少接一条对应能力即静默失效 -->
+    <ListLayout v-bind="listProps" :api="listApi" :columns="columns" row-key="id" />
+  </template>
+
+  <template #detail="{ data, record, refreshList }">
+    <MyDetail :detail="data" :record="record" @changed="refreshList" />
+  </template>
+
+  <template #empty="{ listEmpty }">
+    <ElEmpty :description="listEmpty ? '没有符合条件的数据' : '请从列表选择一条'" />
+  </template>
+</AppPageListDetailLayout>
+```
+
+## 核心不变式：先有列表，才有详情
+
+> **`activeId` 只能从列表内选择产生，[MUST NOT] 直接从链接取。**
+> `activeData` 是**列表数据 item**（不是详情数据），两者**同生同灭**。
+
+由此推出的行为（由列表族的 `useActiveRecord` 统一守，门面不重复接管）：
+
+| 触发 | 行为 |
+| --- | --- |
+| 用户点某项 | 两个 model 同时写 |
+| 列表刷新 | 按 id 在新数据内重查刷新 `activeData`；**查不到 → 两者一并清空**（详情自动关闭） |
+| 外部写不在列表内的 id | 忽略 + `console.warn`，**不清空既有选中** |
+| 写 `activeData`（导航切上/下一条走此路） | 按行反查键同步 `activeId`；行不在列表内同样忽略 + warn |
+
+**深链形态随之改变（[MUST] 照做）**：链接 [MUST NOT] 携带「详情 id」直达详情，而是把 id 带进**搜索条件** → 列表搜出结果 → `autoActiveFirst` 激活第一条。两个代价需知情：ⓐ 搜索表单 [MUST] 有按 id 精确筛的字段（可隐藏）；ⓑ 深链进入时列表通常只剩一条 → 上下条导航两端皆 false，清空搜索条件即恢复。
+
+## 详情 ↔ 列表：单向 `refreshList`，无回写
+
+**唯一机制**：详情侧判断「与列表 item 是否同步」，不同步则触发**列表刷新**，由列表接口出新数据。[MUST NOT] 由详情去写 `activeData`。
+
+```ts
+// 推荐用法（业务侧详情组件内）
+const isOutOfSync = computed(() => {
+  const d = props.detail, r = props.record;
+  if (!d || !r) return false;
+  // ⚠️ [MUST] 先确认「详情与当前 item 是同一条」再比字段 —— 切换当前项时详情尚未重拉回来，
+  // 旧详情 × 新 item 会被判成不同步，每切一次就误刷一次列表（实测踩坑）。
+  if (String(d.id) !== String(r.id)) return false;
+  return d.status !== r.status;
+});
+
+watch(isOutOfSync, (v) => v && refreshList());
+```
+
+- **判定 [MUST] 由业务自己写**（比业务关键字段）：组件不可能知道哪些字段算关键；全字段比对会被 `updatedAt` 一类字段搞成每次都触发。
+- **[MUST] 用 `watch` 的值变化语义**，[MUST NOT] 用 `watchEffect` 或在渲染期直接调 `refreshList()` —— 值变化语义正是止损点：刷新后对上了 `true→false` 收敛；仍对不上 `true→true` **值未变 → 不再触发**（「刷新了还是不同步就是接口的问题」，组件不重试）。
+- 新建 / 删除等结构性变更同样走 `refreshList`，机制统一。
+- ⚠️ 刷新后该记录可能因状态变化换了排序、跑出当前页 → 按不变式两值清空 → **详情自动关闭**。语义正确，但使用方需知情。
+
+## API
+
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### v-model
+
+| 名 | type | 语义 |
+| --- | --- | --- |
+| `activeId` | `string \| number \| undefined` | 当前项唯一键。`string` / `number` 两种都是一等公民，出口值保业务数据原始类型 |
+| `activeData` | `T \| undefined` | 当前项对应的**列表 item**（恒为列表接口原样） |
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `mode` | `"auto" \| "split" \| "sheet"` | `"auto"` | 形态；`auto` 按视口宽 `splitAt` 定档 |
+| `splitAt` | `number` | `1200` | `auto` 档切档阈值（px，**视口宽**）。iPad 竖屏 768 / Air 横屏 1180 落 sheet；Pro 12.9″ 横屏 1366 落 split |
+| `listWidth` | `string` | `clamp(280px, 28%, 420px)` | 分栏态列表列宽。[MUST NOT] 写死 px —— 侧边栏折叠会改内容区可用宽 |
+| `autoActiveFirst` | `boolean` | 跟随形态 | 列表出数后自动激活第一条。**split 默认 `true`**（宽屏右半屏不该空着）、**sheet 默认 `false`**（窄屏自动弹抽屉是打扰）。⚠️ 详情若有副作用（如「打开即标记已读」）[MUST] 显式关掉 |
+| `queryKey` | `string` | 无 | 传了才把 `activeId` 同步进 URL query（**`replace` 不 `push`**）。复原仍走不变式校验 |
+| `detailApi` | `(params?: { id }) => Promise<R>` | 无 | 传了则内置 `ViewLayout`（零配置拿到内置导航 + `refreshToken` 接线）；不传则 `#detail` 原样渲染、门面零请求 |
+| `detailTitle` | `string \| ((detailData, record) => string)` | 无 | 详情区标题。字符串固定 / 函数按数据算：`detailData` = 详情接口数据（**未传 `detailApi` 时恒 `undefined`**）、`record` = 当前项的列表 item（「详情即列表数据」形态靠它出标题）。⚠️ 渲染在**详情区顶部**（两形态一致），**不是** sheet 弹层的 header —— 详情数据只在详情区内部可得，弹层那层拿不到。不传则不渲染，业务照旧可在 `#detail` 自绘 |
+| `sheetLayerType` | `"drawer" \| "modal"` | `"drawer"` | sheet 形态的弹层承载：抽屉 / 居中弹窗。透传 `ModalConfirm.layerType` |
+| `sheetSize` | `string \| number` | `"70%"` | sheet 弹层尺寸（透传 `ModalConfirm.width`）：drawer 下是抽屉尺寸、modal 下是弹窗宽度 |
+
+**AppPage 的 props 靠 `$attrs` 自动穿透**（`gap` / 各 `*Bg` / `fullViewport` / `nextViewportMaxHeight` 等原样可用），无需白名单。
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#list` | `{ listProps }` | 列表。`listProps` [MUST] 整体 `v-bind` 到列表组件 |
+| `#detail` | `{ id, record, index, total, hasPrev, hasNext, goPrev, goNext, refreshList, data, loading }` | 详情。`data` / `loading` 仅在传了 `detailApi` 时有值 |
+| `#empty` | `{ listEmpty }` | 未选中占位。`listEmpty=true` 列表本身无数据 / `false` 有数据但未选中，**两种文案 [MUST] 分流** |
+| `#top` / `#bottom` / `#right` | 无 | 直通 `AppPage` 同名悬浮槽（**两形态都支持，`auto` 自动挡切档后依旧在**） |
+
+> **为什么 `#right` 可用、`#left` 不可用**：门面对 `AppPage` 槽的占用是——Split 用 `#left` 放列表、**默认槽**放详情；Sheet 用**默认槽**放列表、**抽屉**放详情。两形态都**没占 `#right`**，故它原样开放给业务；`#left` 则是 Split 自用，不开放。
+>
+> ⚠️ **Sheet 形态下详情打开时抽屉会盖住右栏**：抽屉是 EP 弹层（z-index 2000+ 档）且默认 70% 宽，而 AppPage 悬浮槽是 `APP_PAGE_SLOT_Z_INDEX`=1。这是形态固有结果、**不视为缺陷**——侧栏承载的本就是次要信息（说明 / 辅助入口一类），被临时遮住无妨；[MUST NOT] 为此加避让或降级逻辑。
+
+## 反模式 / 注意
+
+- **业务外层再套 `AppPage`** —— 页面根二选一，套了就成两层
+- **`#list` 里只 `v-bind` 一部分 `listProps`** —— 少接 `onDataChange` 则序列 / 自动激活失效、少接 `ref` 则 `refreshList` 失效，且**都不报错**
+- **自己给列表加 `:ref` 覆盖掉 `listProps.ref`** —— 需要自己也拿实例时 [MUST] 链式调用：`:ref="(el) => { myRef = el; listProps.ref(el) }"`
+- **运行时增删 `#top` / `#bottom` / `#right` / `#list`** —— `AppPage` 的槽集判定不响应运行时增删（既有限制），插槽集 [MUST] 当静态结构
+- **不传 `detailApi` 时期待内置上/下一条** —— 导航住在 `ViewLayout` 内；不内置 `ViewLayout` 就没有内置导航，用 `#detail` scope 的 `goPrev` / `goNext` 自绘
+- **删除 / 筛掉当前项后期待自动跳到下一条** —— 按不变式两值清空落空态（不自动重激活，避免自动触发详情副作用）
+- **sheet 态用 scoped `:deep` 调抽屉内样式** —— 抽屉 teleport 到 body，继承 class 但**不继承 scopeId**，`:deep` 恒失效；验收 [MUST] 量 computed style
+- **`activeId` 只从链接取** —— 违反不变式，见上「深链形态」
+
+## 关联
+
+- 内部件（不导出）：`AppPageListDetailSplit` / `AppPageListDetailSheet` / `AppPageListDetailPane` / `use-list-detail.ts`
+- 不变式内核：`hooks/use-active-record.ts`（`useActiveRecord`，列表族三家共用）
+- 上下文 key：`APP_PAGE_LIST_DETAIL_CONTEXT`（导航句柄 + `refreshList`，`ViewLayout` 可选 inject 探测）
+- 详情容器：`ViewLayout`（`refreshToken` 外部重拉口 + 内置导航 `showNavigation`）
+- spec：`docs/specs/2026-08-31-025041-moderate-列表详情同页范式AppPageListDetailLayout/spec.md`

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

@@ -86,7 +86,7 @@ const toolbarConfig: TableToolbarConfig<Row> = {
 | `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` 插槽）
+**v-model**：`isAutoRefresh`（boolean）、`refreshInterval`（number，秒）、`customView`（boolean，默认 false，显式切 DataListView 替代 ElTable，需配 `#custom-view-item` 插槽）、`activeId`（`string | number | undefined`）/ `activeData`（行对象 | undefined）—— **「当前项」双 model**（= 用户点击/激活的那一条，[MUST NOT] 与勾选 selection 混同）。两者**同生同灭**：`activeId` 有值 ⇒ `activeData` 必有值且恒为**列表数据原样**；列表刷新后当前项不在新数据内 → 两者一并清空；外部写入不在列表内的 id → 忽略 + `console.warn`（不清空既有选中）。⚠️ `activeId` 的 `string` / `number` **两种都是一等公民**：出口值**保业务数据里的原始类型**（`rowKey` 为字段名时即 `row[rowKey]`，数字 id 出数字）；外部用另一种类型写入（如 `"1"` 对数字 id）同样命中——比对时内部统一 `String()` 归一，且**保留调用方写入的原值**不回写覆盖。ElTable 态由本组件接管（命令式 `setCurrentRow` 同步高亮——EP 的 `current-row-key` 置空不清高亮，故不用它）；`customView` 态让位内层 `DataListView`
 
 ### Emits
 

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

@@ -63,6 +63,7 @@
 | --- | --- | --- | --- |
 | `api` | `(params?: P) => Promise<R>`（必填） | — | 数据拉取函数；每次拉取（激活 / 手动刷新 / 自动刷新）传入 props.params（未传收 undefined） |
 | `params` | `P?` | — | 拉取参数；响应式变化不自动重拉（调 `scope.refresh()`） |
+| `refreshToken` | `string \| number?` | — | **外部重拉触发口**：值变化即重拉一次，且不进 `params`（不发给后端）。变为 `undefined` 不触发；挂载时已有值也不额外拉（首拉由激活态承担）。默认不传 = 老行为逐字节不变 |
 | `refine` | `boolean?` | 上下文默认 | 精细流：包 HeightProvider 精确扣 toolbar reserve（WatchSize 量高），内容区可用高 + scope viewportHeight；false=自然流。默认由 `useContextDefaults` 按直系父解析：AppPage `#default` / TabsMain 页签内容内 `true`，否则 `false`；显式传值优先 |
 | `viewportHeight` | `number?` | — | 显式视口高，优先级最高；未传降级 inject SCOPE_VIEWPORT_MAX_HEIGHT scope 链 |
 | `channel` | `string?` | — | 作为父时的 scope 标识。⚠️ 与 parentChannel 均 [MUST NOT] 响应式变更（setup 期快照）；且仅 refine=true 路径生效 |
@@ -70,6 +71,7 @@
 | `minHeight` | `number?` | `100` | 内容区可用高兜底下限（对齐 ListLayout/TabsMain 惯例） |
 | `showAutoRefresh` | `boolean?` | `true` | 是否显示自动刷新开关（透传 AutoRefreshGroup） |
 | `showRefresh` | `boolean?` | `true` | 是否显示手动刷新按钮（透传 AutoRefreshGroup） |
+| `showNavigation` | `boolean?` | `true` | 是否显示内置「上一条 / 下一条」导航。⚠️ **真正的显隐判据是可选 inject 探测**：只有置于 `AppPageListDetailLayout` 内才渲染，单独使用 ViewLayout 时无论本值为何都不渲染（老用法零变化）；本 prop 用于在门面内显式关掉 |
 | `leftExtraButtons` | `ViewLayoutButtonConfig[]` | `[]` | 左侧额外按钮（`ActionBtnGroup` 配置，ctx = `{ loading, refresh }`，`default-size="small"` 对齐 table-toolbar） |
 | `rightExtraButtons` | `ViewLayoutButtonConfig[]` | `[]` | 右侧额外按钮（置于 AutoRefreshGroup 之前） |
 
@@ -79,6 +81,15 @@
 | --- | --- | --- |
 | 默认 | `{ data, loading, refresh, viewportHeight }`（`ViewLayoutScope<R>`） | 展示内容；PanelMain 或自由编排皆可；viewportHeight refine 时给可用高、自然流 undefined |
 
+### 内置上/下一条导航（仅列表详情范式内出现）
+
+置于 `AppPageListDetailLayout` 内时，toolbar 右侧自动出现「上一条 / 下一条」+「第 N / M 条」读数。
+
+- 位置 = **`rightExtraButtons` 之前（最靠左）**，`AutoRefreshGroup` 恒最右 —— 导航是**位置指示**不是业务动作，与业务按钮分档。
+- 显隐 = **可选 inject 探测**（注入到才渲染）；单独使用 ViewLayout 时完全不渲染，`hasToolbarContent` 判定也不受影响。
+- 已纳入 `hasToolbarContent`：「只有上下条、其余全关」的页面 toolbar 仍可见。
+- `ViewLayoutButtonContext` 同步扩展导航句柄（`hasPrev` / `hasNext` / `index` / `total` / `goPrev` / `goNext` / `refreshList`，**门面外恒为 `undefined`**），业务自定义按钮可据此做「保存并下一条」等组合动作。
+
 ### Expose
 
 无
@@ -88,6 +99,9 @@
 - **纯展示套 PanelMain 作页级根**：PanelMain 已废弃页级展示场景（见 panel 族文档）——纯展示在插槽内自由编排
 - **channel / parentChannel 响应式变更**：[MUST NOT]——setup 期快照，后续变更无效；缺 refine 的 channel 链静默失效
 - **api 抛错不吞**：api 内部自行处理错误（ViewLayout 只保证 loading 复位，不拦截异常）
+- **要重拉不要改 `params` 指望它自动生效**：`params` 响应式变化**刻意**不重拉（防请求风暴的既有设计）。「换了参数要重拉」= 改 `params` **并**动 `refreshToken`（或调 `scope.refresh()`）
+- **[MUST NOT] 把触发值塞进 `params` 当刷新开关**：那会把纯前端的令牌发给后端、污染 API 契约——这正是 `refreshToken` 独立成 prop 的原因
+- **[MUST NOT] 用 `:key="token"` 重建来实现重拉**：会连 toolbar / 按钮一起重建，连续切换时闪烁，且语义错位（chrome 不该随内容重建）——用 `refreshToken`
 - **toolbar 不含表格能力全集**：对齐的是 table-toolbar 的**结构与视觉惯例**（左右分栏 + extra 按钮 + AutoRefreshGroup），[MUST NOT] 期待导出 / 批量下载 / 视图切换等表格特有能力出现在 ViewLayout——需要表格能力用 `ListLayout` / `TableMain`
 
 ## 关联

package/types/components/app-layout/AppPage.vue.d.ts

@@ -30,6 +30,18 @@ type __VLS_Props = {
     leftObserveResize?: boolean;
     /** right 插槽 RO 观测开关 */
     rightObserveResize?: boolean;
+    /**
+     * 超宽屏适配：默认 slot 内容限宽居中（默认关）。开启后内容盒宽收敛到 `contentMaxWidth`
+     * 并居中于「两侧槽之间的可用区」，同时同步收窄对后代公布的内容几何（inset / viewport-width）。
+     * 窄屏（可用宽 ≤ contentMaxWidth）留白为 0、与关闭态一致，无需断点判断。
+     * 适用表单 / 详情 / 阅读型页；列表 / 表格页 [MUST NOT] 开（列本就挤）。
+     */
+    contentCentered?: boolean;
+    /**
+     * 限宽值（px，仅 `contentCentered` 开启时生效）。
+     * [MUST] 为 number——几何链三处出口需其参与数值运算，CSS 串会让样式与公布几何脱钩。
+     */
+    contentMaxWidth?: number;
 };
 declare function __VLS_template(): {
     attrs: Partial<{}>;
@@ -59,6 +71,8 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
     bottomObserveResize: boolean;
     leftObserveResize: boolean;
     rightObserveResize: boolean;
+    contentCentered: boolean;
+    contentMaxWidth: number;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     appPageRef: HTMLDivElement;
 }, HTMLDivElement>;

package/types/components/app-layout/use-content-box.d.ts

@@ -0,0 +1,31 @@
+import { ComputedRef } from 'vue';
+/**
+ * 超宽屏内容限宽留白（单侧 px，纯函数，钳非负）。
+ *
+ * `availableWidth`（内容可用宽 = AppPage 盒宽扣四向槽让位）超出 `maxWidth` 时，超出部分两侧均分；
+ * 未超出（窄屏 / 常规屏）恒 0 —— 关闭态与开启态在窄屏下逐字节一致，无需断点判断。
+ */
+export declare function computeAppPageContentGutter(availableWidth: number, maxWidth: number): number;
+/**
+ * AppPage 超宽屏内容限宽居中（非主干功能，默认关；规则 22 同级 hook 收纳，**[MUST NOT] 出桶导出**）。
+ *
+ * 只出一个数 `contentGutter`（单侧留白 px，关闭态恒 0），主干三处消费即闭环：
+ * ⓐ `.app-page-shim` 左右 padding 各 `+ gutter`（内容盒宽收敛到 `maxWidth` 且精确居中）；
+ * ⓑ `APP_PAGE_CONTENT_INSET` 的 `left`/`right` 各 `+ gutter`（后代 fixed / 悬浮贴真实内容列边）；
+ * ⓒ `--dc-page-content-viewport-width` 减 `2 × gutter`（对后代公布的可用宽与实际同步）。
+ *
+ * **刻意不套限宽容器**：`.app-page-shim` 挂着 `data-dc-slot`（默认槽区域标记），`useContextDefaults`
+ * 读的是**直系父 DOM**——中间插一层容器会让 ListLayout 窄栏默认、ViewLayout/TabsMain `refine` 上下文
+ * 默认静默失效。padding 方案与套容器行为等价（居中基准同为「两侧槽之间的可用区」），且零 DOM 变更。
+ *
+ * @param options.enabled        开关（`contentCentered`），关闭恒出 0
+ * @param options.maxWidth       限宽值 px（`contentMaxWidth`）
+ * @param options.availableWidth 内容可用宽 px（AppPage 盒宽扣四向槽让位 = `computeAppPageReducedViewportWidth`）
+ */
+export declare function useAppPageContentBox(options: {
+    enabled: () => boolean;
+    maxWidth: () => number;
+    availableWidth: () => number;
+}): {
+    contentGutter: ComputedRef<number>;
+};

package/types/components/data-view/DataGridView.vue.d.ts

@@ -1,18 +1,23 @@
 import { TableMainInstance, TablePageInfo } from '../table';
 import { DataGridViewProps } from './types';
+import { ActiveRecordKey } from '../../hooks/use-active-record';
 declare const _default: <T extends Record<string, any>, SQ extends Record<string, any>, F extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
         readonly "onUpdate:isAutoRefresh"?: ((value: boolean) => any) | undefined;
         readonly onLoadingChange?: ((value: boolean) => any) | undefined;
         readonly "onUpdate:refreshInterval"?: ((value: number) => any) | undefined;
+        readonly "onUpdate:activeId"?: ((value: ActiveRecordKey | undefined) => any) | undefined;
+        readonly "onUpdate:activeData"?: ((value: T | undefined) => any) | undefined;
         readonly onPageChange?: ((page: number) => any) | undefined;
         readonly onPageSizeChange?: ((page: number) => any) | undefined;
         readonly onDataChange?: ((payload: T[]) => any) | undefined;
         readonly onPageInfoChange?: ((info: TablePageInfo) => any) | undefined;
         readonly onSelectionChange?: ((payload: T[]) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh" | "onLoadingChange" | "onUpdate:refreshInterval" | "onPageChange" | "onPageSizeChange" | "onDataChange" | "onPageInfoChange" | "onSelectionChange"> & ({
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh" | "onLoadingChange" | "onUpdate:refreshInterval" | "onUpdate:activeId" | "onUpdate:activeData" | "onPageChange" | "onPageSizeChange" | "onDataChange" | "onPageInfoChange" | "onSelectionChange"> & ({
         isAutoRefresh?: boolean;
         refreshInterval?: number;
+        activeId?: ActiveRecordKey | undefined;
+        activeData?: T | undefined;
     } & DataGridViewProps<T, SQ, F>) & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<TableMainInstance>): void;
     attrs: any;
@@ -23,6 +28,8 @@ declare const _default: <T extends Record<string, any>, SQ extends Record<string
             index: number;
             selected: boolean;
             toggleSelect: () => void;
+            active: boolean;
+            setActive: () => void;
         }): any;
     };
     emit: {
@@ -30,7 +37,7 @@ declare const _default: <T extends Record<string, any>, SQ extends Record<string
         (e: "dataChange" | "selectionChange", payload: T[]): void;
         (e: "loadingChange", value: boolean): void;
         (e: "pageInfoChange", info: TablePageInfo): void;
-    } & (((evt: "update:isAutoRefresh", value: boolean) => void) & ((evt: "update:refreshInterval", value: number) => void));
+    } & (((evt: "update:isAutoRefresh", value: boolean) => void) & ((evt: "update:refreshInterval", value: number) => void) & ((evt: "update:activeId", value: ActiveRecordKey | undefined) => void) & ((evt: "update:activeData", value: T | undefined) => void));
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/types/components/data-view/DataListView.vue.d.ts

@@ -1,8 +1,14 @@
 import { DataListViewProps } from './types';
+import { ActiveRecordKey } from '../../hooks/use-active-record';
 declare const _default: <T extends Record<string, any>, F extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly "onUpdate:activeId"?: ((value: ActiveRecordKey | undefined) => any) | undefined;
+        readonly "onUpdate:activeData"?: ((value: T | undefined) => any) | undefined;
         readonly onSelectionChange?: ((rows: T[]) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onSelectionChange"> & DataListViewProps<T, F> & Partial<{}>> & import('vue').PublicProps;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:activeId" | "onUpdate:activeData" | "onSelectionChange"> & ({
+        activeId?: ActiveRecordKey | undefined;
+        activeData?: T | undefined;
+    } & DataListViewProps<T, F>) & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<import('../table').TableInstance>): void;
     attrs: any;
     slots: {
@@ -12,10 +18,12 @@ declare const _default: <T extends Record<string, any>, F extends Record<string,
             index: number;
             selected: boolean;
             toggleSelect: () => void;
+            active: boolean;
+            setActive: () => void;
         }): any;
         empty?(_: {}): any;
     };
-    emit: (e: "selectionChange", rows: T[]) => void;
+    emit: ((e: "selectionChange", rows: T[]) => void) & (((evt: "update:activeId", value: ActiveRecordKey | undefined) => void) & ((evt: "update:activeData", value: T | undefined) => void));
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/types/components/data-view/DataListViewItem.vue.d.ts

@@ -1,13 +1,15 @@
 /**
  * DataListView 单项容器
  * ---
- * 仅承载选中态 class 钩子 + 项内容插槽，由 DataListView 内部 v-for 使用。
+ * 仅承载选中（勾选）/ 当前项（active）两个 class 钩子 + 项内容插槽，由 DataListView 内部 v-for 使用。
  * [MUST NOT] 写死视觉样式（卡片阴影/圆角等归消费方）；
  * [MUST NOT] 内置选中状态机（状态机在 DataListView）。
  */
 type __VLS_Props = {
-    /** 当前项是否选中（由 DataListView 传入） */
+    /** 当前项是否选中（勾选语义，由 DataListView 传入） */
     selected: boolean;
+    /** 当前项是否为「当前项」（active = 用户点击/激活的那一条，与勾选无关） */
+    active?: boolean;
 };
 declare function __VLS_template(): {
     attrs: Partial<{}>;

package/types/components/data-view/types.d.ts

@@ -68,10 +68,14 @@ export interface DataListViewItemScope<T extends Record<string, any> = Record<st
     row: T;
     /** 当前行索引 */
     index: number;
-    /** 当前行是否选中 */
+    /** 当前行是否选中（勾选语义，与 active 无关） */
     selected: boolean;
     /** 翻转当前行选中态 */
     toggleSelect: () => void;
+    /** 当前行是否为「当前项」（active，= 用户点击/激活的那一条；与勾选 selected 是两回事） */
+    active: boolean;
+    /** 把当前行设为「当前项」（等价于点击该项） */
+    setActive: () => void;
 }
 /** InfiniteListView 配置（经 DataGridView.infiniteListProps 透传） */
 export interface InfiniteListViewConfig {

package/types/components/list-layout/ListLayout.vue.d.ts

@@ -1,5 +1,6 @@
 import { FormItemConfigList, FormScope, FormSearchSearchType } from '../form';
 import { TableColumnDefaultScope, TableColumnHeaderScope, TablePageInfo } from '../table';
+import { ActiveRecordKey } from '../../hooks/use-active-record';
 import { ListLayoutInnerInjectInfo, ListLayoutInstance } from './types';
 import { VNode } from 'vue';
 import { DataListViewItemScope } from '../data-view';
@@ -8,12 +9,16 @@ declare const _default: <T extends Record<string, any>, PO extends Record<string
         readonly "onUpdate:isAutoRefresh"?: ((value: boolean) => any) | undefined;
         readonly "onUpdate:refreshInterval"?: ((value: number) => any) | undefined;
         readonly "onUpdate:customView"?: ((value: boolean) => any) | undefined;
+        readonly "onUpdate:activeId"?: ((value: ActiveRecordKey | undefined) => any) | undefined;
+        readonly "onUpdate:activeData"?: ((value: T | undefined) => any) | undefined;
         readonly onDataChange?: ((data: T[]) => any) | undefined;
         readonly onPageInfoChange?: ((info: TablePageInfo) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh" | "onUpdate:refreshInterval" | "onUpdate:customView" | "onDataChange" | "onPageInfoChange"> & ({
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh" | "onUpdate:refreshInterval" | "onUpdate:customView" | "onUpdate:activeId" | "onUpdate:activeData" | "onDataChange" | "onPageInfoChange"> & ({
         isAutoRefresh?: boolean;
         refreshInterval?: number;
         customView?: boolean;
+        activeId?: ActiveRecordKey | undefined;
+        activeData?: T | undefined;
     } & Partial<Pick<import('../form').FormSearchProps<PO, SO, {}>, "staticQuery">> & {
         formSearchProps?: Partial<Omit<import('../form').FormSearchProps<PO, SO, {}>, "staticQuery" | "compact" | "list">> | undefined;
     } & Pick<import('../table').TableMainProps<T, import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>> & SQ, ListLayoutInnerInjectInfo<PO, F>>, import('./types').TableMainRequiredKey> & Partial<Pick<import('../table').TableMainProps<T, import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>> & SQ, ListLayoutInnerInjectInfo<PO, F>>, import('./types').TableMainOptionsKey>> & {
@@ -66,7 +71,7 @@ declare const _default: <T extends Record<string, any>, PO extends Record<string
     emit: {
         (e: "dataChange", data: T[]): void;
         (e: "pageInfoChange", info: TablePageInfo): void;
-    } & (((evt: "update:isAutoRefresh", value: boolean) => void) & ((evt: "update:refreshInterval", value: number) => void) & ((evt: "update:customView", value: boolean) => void));
+    } & (((evt: "update:isAutoRefresh", value: boolean) => void) & ((evt: "update:refreshInterval", value: number) => void) & ((evt: "update:customView", value: boolean) => void) & ((evt: "update:activeId", value: ActiveRecordKey | undefined) => void) & ((evt: "update:activeData", value: T | undefined) => void));
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/types/components/modal/ModalConfirm.vue.d.ts

@@ -12,6 +12,22 @@ type __VLS_Props = {
     confirmText?: string | (() => VNode);
     /** 是否隐藏取消按钮 */
     hiddenCancel?: boolean;
+    /**
+     * 整块隐藏 header（标题区 + 关闭按钮），默认 false。
+     * 两形态的实现不同（EP 使然，非本组件选择）：
+     * - drawer：走 EP 的 `with-header=false` → **节点真不渲染**；
+     * - modal：EP 的 `el-dialog__header` **无条件渲染**（`dialog-content` 里 `createElementVNode("header")`
+     *   不带任何条件），故只能由 `dc-confirm-modal_hidden-header` 类 `display:none` 兜。
+     * ⚠️ 隐藏 header 同时失去关闭按钮 —— [MUST] 自行提供关闭入口（遮罩 / ESC / 自绘按钮）。
+     */
+    hiddenHeader?: boolean;
+    /**
+     * 整块隐藏 footer（操作区），默认 false。用于「只要弹层容器、不要确认-取消」的场景
+     * （如列表详情范式的详情抽屉）。
+     * dialog / drawer 都是按 footer 插槽存在与否渲染容器，故此处 **v-if 省掉插槽 = 真不渲染**，
+     * [MUST NOT] 改用「传空 #footer 插槽」绕 —— 那会留一条带 padding 的空条（drawer 实测 56px）。
+     */
+    hiddenFooter?: boolean;
     width?: number | string;
     /** 反转按钮位置 */
     reverse?: boolean;
@@ -84,6 +100,8 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
     cancelText: string | (() => VNode);
     confirmText: string | (() => VNode);
     hiddenCancel: boolean;
+    hiddenHeader: boolean;
+    hiddenFooter: boolean;
     closeOnPressEscape: boolean;
     closeOnClickModal: boolean;
     layerType: "modal" | "drawer";

package/types/components/page-layout/AppPageDetail.vue.d.ts

@@ -0,0 +1,40 @@
+import { ActiveRecordKey } from '../../hooks/use-active-record';
+import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailProps } from './types';
+declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, never> & {
+        /**
+         * 完整详情上下文（含序列导航句柄）。**门面内嵌时下发**；
+         * 独立使用时不传，改用下方 `id` / `record`。
+         */
+        ctx?: Omit<AppPageListDetailDetailScope<T, R>, "data" | "loading">;
+        /** 独立使用时的当前项键（`ctx` 未传时生效；与 `ctx` 都无 → 落空态） */
+        id?: ActiveRecordKey;
+        /** 独立使用时的当前项数据（`ctx` 未传时生效），供 `detailTitle` / `#detail` 消费 */
+        record?: T;
+        /** 列表是否为空（分流两种空态文案）；独立使用时通常不关心 */
+        listEmpty?: boolean;
+        /**
+         * 内嵌态：`true` 则不套 `AppPage`（宿主已有一层）。默认 `false` = 自带 `AppPage`、可独立成页。
+         * ⚠️ 内嵌态下本组件无宿主元素，`dc-app-page-detail` 根类与 `$attrs` 随之无落点。
+         */
+        embedded?: boolean;
+        detailApi?: AppPageListDetailProps<R>["detailApi"];
+        detailTitle?: AppPageListDetailProps<R>["detailTitle"];
+    } & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
+    slots: Readonly<{
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+    }> & {
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+    };
+    emit: {};
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/types/components/page-layout/AppPageListDetailLayout.vue.d.ts

@@ -0,0 +1,39 @@
+import { ActiveRecordKey } from '../../hooks/use-active-record';
+import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailProps } from './types';
+declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly "onUpdate:activeId"?: ((value: ActiveRecordKey | undefined) => any) | undefined;
+        readonly "onUpdate:activeData"?: ((value: T | undefined) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:activeId" | "onUpdate:activeData"> & ({
+        activeId?: ActiveRecordKey | undefined;
+        activeData?: T | undefined;
+    } & AppPageListDetailProps<R>) & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
+    slots: Readonly<{
+        list?: (scope: {
+            listProps: AppPageListDetailListProps<T>;
+        }) => unknown;
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+        top?: () => unknown;
+        bottom?: () => unknown;
+        right?: () => unknown;
+    }> & {
+        list?: (scope: {
+            listProps: AppPageListDetailListProps<T>;
+        }) => unknown;
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+        top?: () => unknown;
+        bottom?: () => unknown;
+        right?: () => unknown;
+    };
+    emit: ((evt: "update:activeId", value: ActiveRecordKey | undefined) => void) & ((evt: "update:activeData", value: T | undefined) => void);
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/types/components/page-layout/AppPageListDetailSheet.vue.d.ts

@@ -0,0 +1,44 @@
+import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailProps } from './types';
+declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onClose?: (() => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onClose"> & {
+        listProps: AppPageListDetailListProps<T>;
+        ctx: Omit<AppPageListDetailDetailScope<T, R>, "data" | "loading">;
+        listEmpty: boolean;
+        sheetLayerType: "drawer" | "modal";
+        sheetSize: string | number;
+        /** 本形态不消费，但 [MUST] 声明（理由同 Split 的 `sheetSize`：防 attr 泄漏成 DOM 属性） */
+        listWidth?: string;
+        detailApi?: AppPageListDetailProps<R>["detailApi"];
+        detailTitle?: AppPageListDetailProps<R>["detailTitle"];
+    } & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
+    slots: Readonly<{
+        list?: (scope: {
+            listProps: AppPageListDetailListProps<T>;
+        }) => unknown;
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+        top?: () => unknown;
+        bottom?: () => unknown;
+        right?: () => unknown;
+    }> & {
+        list?: (scope: {
+            listProps: AppPageListDetailListProps<T>;
+        }) => unknown;
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+        top?: () => unknown;
+        bottom?: () => unknown;
+        right?: () => unknown;
+    };
+    emit: (e: "close") => void;
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};