@done-coding/admin-core 0.25.0 → 0.26.0

package/es/style.css

@@ -1,11 +1,11 @@
-.confirm-modal__title[data-v-fca575ec] {
+.confirm-modal__title[data-v-7ef0be5c] {
   font-size: 16px;
   font-weight: 600;
   line-height: 24px;
   color: var(--el-text-color-primary);
   text-align: left;
 }
-.confirm-modal__content[data-v-fca575ec] {
+.confirm-modal__content[data-v-7ef0be5c] {
   overflow-x: hidden;
   overflow-y: auto;
   max-height: calc(100vh - 200px);
@@ -15,20 +15,20 @@
   text-align: left;
   word-break: break-word;
 }
-.confirm-modal__content_drawer[data-v-fca575ec] {
+.confirm-modal__content_drawer[data-v-7ef0be5c] {
   max-height: none;
   height: 100%;
 }
-.confirm-modal__footer[data-v-fca575ec] {
+.confirm-modal__footer[data-v-7ef0be5c] {
   display: flex;
   justify-content: flex-end;
   align-items: center;
   gap: 8px;
 }
-.confirm-modal__footer[data-v-fca575ec] .el-button {
+.confirm-modal__footer[data-v-7ef0be5c] .el-button {
   min-width: 72px;
 }
-.confirm-modal__footer[reverse="true"][data-v-fca575ec] {
+.confirm-modal__footer[reverse="true"][data-v-7ef0be5c] {
   flex-direction: row-reverse;
 }
 .dc-confirm-modal.el-drawer .el-drawer__header {
@@ -42,6 +42,9 @@
 .dc-confirm-modal.el-drawer .el-drawer__footer {
   padding: 12px 20px;
 }
+.dc-confirm-modal.confirm-modal_hidden-header .el-dialog__header {
+  display: none;
+}
 .dc-confirm-modal.confirm-modal_header-divider .el-drawer__header,
 .dc-confirm-modal.confirm-modal_header-divider .el-dialog__header {
   border-bottom: 1px solid var(--el-border-color-lighter);
@@ -70,6 +73,90 @@
 .badge-mark_middle[data-v-12868883] .el-badge__content.is-fixed {
   top: 50%;
 }
+.app-page[data-v-3ef165a7] {
+  --dc-page-content-viewport-top: var(--v6b53f4c2);
+  --dc-page-content-viewport-bottom: var(--v1c770cbe);
+  --dc-page-content-viewport-left: var(--ff323606);
+  --dc-page-content-viewport-right: var(--e667c834);
+  --dc-page-content-viewport-width: var(--e5daf0e0);
+  --dc-page-content-viewport-height: var(--v09211ec6);
+}
+.app-page-shim[data-v-3ef165a7] {
+  --app-viewport-max-height: var(--v0bd4b228);
+}
+.app-page-slot-shim[data-v-3ef165a7] {
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+}
+[data-v-64f355fe] .auto-refresh-label {
+  display: flex;
+  font-size: 13px;
+  color: var(--el-text-color-regular);
+  margin-bottom: 8px;
+}
+/* 有根节点时（needRootNode）按钮组横向排列 + 间距（参照 TableToolbar 按钮组内 gap:10px） */
+.auto-refresh-group-root[data-v-0ebeb4c7] {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+.auto-refresh-group-icon--rotating[data-v-0ebeb4c7] {
+  animation: auto-refresh-rotating-0ebeb4c7 1s linear infinite;
+}
+@keyframes auto-refresh-rotating-0ebeb4c7 {
+from {
+    transform: rotate(0deg);
+}
+to {
+    transform: rotate(360deg);
+}
+}
+.view-layout-navigation[data-v-2fcd4cb2] {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.view-layout-navigation__index[data-v-2fcd4cb2] {
+  min-width: 44px;
+  color: var(--el-text-color-secondary);
+  font-size: 12px;
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+}
+.view-layout[data-v-8eb550ba] {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.view-layout-toolbar[data-v-8eb550ba] {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding-bottom: 8px;
+  gap: 20px;
+}
+.view-layout-toolbar__left[data-v-8eb550ba],
+.view-layout-toolbar__right[data-v-8eb550ba] {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+.view-layout-content[data-v-8eb550ba] {
+  overflow: auto;
+}
+.dc-app-page-detail__title[data-v-8de03183] {
+  padding-bottom: 12px;
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 24px;
+  color: var(--dc-core-text-color, var(--el-text-color-primary));
+}
+.dc-app-page-list-detail-split__list[data-v-19f0f56d] {
+  box-sizing: border-box;
+  height: 100%;
+  overflow: hidden;
+}
 .form-item-tip[data-v-8b508d64] {
   text-align: left;
   line-height: 1.5;
@@ -149,20 +236,20 @@
 .form-submit-panel_bare .form-submit-panel-operation-inner[data-v-1505775a] {
   padding: 0;
 }
-.panel-edit-switch[data-v-65f056ab] {
+.panel-edit-switch[data-v-17f3b3db] {
   position: relative;
 }
-.panel-edit-switch:hover .panel-edit-switch-edit-btn[data-v-65f056ab] {
+.panel-edit-switch:hover .panel-edit-switch-edit-btn[data-v-17f3b3db] {
   display: block;
 }
-.panel-edit-switch-edit-btn[data-v-65f056ab] {
+.panel-edit-switch-edit-btn[data-v-17f3b3db] {
   position: absolute;
   top: 0;
   right: 0;
   z-index: 1;
   display: none;
 }
-.panel-edit-switch-actions[data-v-65f056ab] {
+.panel-edit-switch-actions[data-v-17f3b3db] {
   display: flex;
   justify-content: flex-end;
   gap: 8px;
@@ -617,45 +704,6 @@
 .app-layout_noAnimation[data-v-b68520cd] .app-collapse-toggle {
   transition: none !important;
 }
-.app-page[data-v-2359c6df] {
-  --dc-page-content-viewport-top: var(--v55181597);
-  --dc-page-content-viewport-bottom: var(--v5f04c6a9);
-  --dc-page-content-viewport-left: var(--v4de6d405);
-  --dc-page-content-viewport-right: var(--v6f4a0dde);
-  --dc-page-content-viewport-width: var(--v6f907988);
-  --dc-page-content-viewport-height: var(--v68afbda5);
-}
-.app-page-shim[data-v-2359c6df] {
-  --app-viewport-max-height: var(--v2e2782e4);
-}
-.app-page-slot-shim[data-v-2359c6df] {
-  box-sizing: border-box;
-  width: 100%;
-  height: 100%;
-}
-[data-v-64f355fe] .auto-refresh-label {
-  display: flex;
-  font-size: 13px;
-  color: var(--el-text-color-regular);
-  margin-bottom: 8px;
-}
-/* 有根节点时（needRootNode）按钮组横向排列 + 间距（参照 TableToolbar 按钮组内 gap:10px） */
-.auto-refresh-group-root[data-v-0ebeb4c7] {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-}
-.auto-refresh-group-icon--rotating[data-v-0ebeb4c7] {
-  animation: auto-refresh-rotating-0ebeb4c7 1s linear infinite;
-}
-@keyframes auto-refresh-rotating-0ebeb4c7 {
-from {
-    transform: rotate(0deg);
-}
-to {
-    transform: rotate(360deg);
-}
-}
 .table-toolbar[data-v-0220e327] {
   display: flex;
   justify-content: space-between;
@@ -798,18 +846,21 @@ to {
 .infinite-list-view__pull-indicator > span[data-v-e597453f] {
   padding-bottom: 6px;
 }
-.data-grid-view[data-v-d9e5439d] {
+.data-grid-view[data-v-16f88920] {
   width: 100%;
 }
-.data-grid-view__grid[data-v-d9e5439d] {
+.data-grid-view__grid[data-v-16f88920] {
   display: grid;
   gap: 12px;
   padding-bottom: 12px;
 }
-.data-grid-view__cell[data-v-d9e5439d] {
+.data-grid-view__cell.is-active[data-v-16f88920] {
+  /* stylelint-disable-next-line block-no-empty */
+}
+.data-grid-view__cell[data-v-16f88920] {
   min-width: 0;
 }
-.data-grid-view__card[data-v-d9e5439d] {
+.data-grid-view__card[data-v-16f88920] {
   border: 1px solid var(--dc-core-border-color, var(--el-border-color-lighter));
   border-radius: var(--dc-core-radius, 4px);
   padding: 10px 12px;
@@ -817,23 +868,23 @@ to {
   box-sizing: border-box;
   overflow: hidden;
 }
-.data-grid-view__field[data-v-d9e5439d] {
+.data-grid-view__field[data-v-16f88920] {
   display: flex;
   gap: 6px;
   align-items: baseline;
   line-height: 1.6;
   font-size: 13px;
 }
-.data-grid-view__field-label[data-v-d9e5439d] {
+.data-grid-view__field-label[data-v-16f88920] {
   flex-shrink: 0;
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.data-grid-view__field-value[data-v-d9e5439d] {
+.data-grid-view__field-value[data-v-16f88920] {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
-.data-grid-view__empty-error[data-v-d9e5439d] {
+.data-grid-view__empty-error[data-v-16f88920] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -1191,13 +1242,16 @@ to {
 .dc-form-upload-video__thumb_empty[data-v-5eac98bc] {
   background: var(--el-fill-color-light);
 }
-.data-list-view-item.is-selected[data-v-d9b5d5ca] {
-  /* 选中态钩子，具体视觉由消费方覆写 */
+.data-list-view-item.is-selected[data-v-c2a6c6be] {
+  /* 选中（勾选）态钩子，具体视觉由消费方覆写 */
+}
+.data-list-view-item.is-active[data-v-c2a6c6be] {
+  /* 当前项（active）态钩子，具体视觉由消费方覆写 */
 }
-.data-list-view[data-v-ce0bb05b] {
+.data-list-view[data-v-467a86a8] {
   width: 100%;
 }
-.data-list-view-empty[data-v-ce0bb05b] {
+.data-list-view-empty[data-v-467a86a8] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -1205,13 +1259,13 @@ to {
   min-height: 60px;
   grid-column: 1 / -1;
 }
-.table-main-pagination[data-v-6a8d4637] {
+.table-main-pagination[data-v-ab2d031c] {
   margin-top: 10px;
   display: flex;
   justify-content: flex-end;
 }
-.table-main_fill[data-v-6a8d4637] .el-table__body-wrapper {
-  min-height: var(--ed56f300);
+.table-main_fill[data-v-ab2d031c] .el-table__body-wrapper {
+  min-height: var(--v4d2ea4ab);
 }
 .dc-slot-layout-flow-aside_separate[data-v-5c6ef74b] {
   position: relative;
@@ -1241,40 +1295,40 @@ to {
 .dc-slot-layout-flow-aside-main[data-v-5c6ef74b] {
   width: var(--v7e1d11ca);
 }
-.list-layout[data-v-a47ec619] {
-  min-height: var(--v37fdcdf2);
+.list-layout[data-v-84c13797] {
+  min-height: var(--d1ae0a92);
 }
-.list-layout-header[data-v-a47ec619] {
+.list-layout-header[data-v-84c13797] {
   margin-bottom: 10px;
 }
-.list-layout-operation[data-v-a47ec619] {
+.list-layout-operation[data-v-84c13797] {
   margin-bottom: 10px;
 }
-.list-layout_search-sticky[data-v-a47ec619] .form-search {
+.list-layout_search-sticky[data-v-84c13797] .form-search {
   position: sticky;
-  top: var(--v5bcb0a52);
+  top: var(--e3e22ffc);
   z-index: 10;
   background: var(--dc-core-surface, var(--el-bg-color));
   box-shadow: 0 1px 0 0 var(--dc-core-border-color, var(--el-border-color-lighter));
 }
-.list-layout_toolbar-sticky[data-v-a47ec619] .dc-table-main__toolbar {
+.list-layout_toolbar-sticky[data-v-84c13797] .dc-table-main__toolbar {
   position: sticky;
-  top: var(--v489faec3);
+  top: var(--v5ed78713);
   z-index: 9;
   padding-top: 10px;
   background: var(--dc-core-surface, var(--el-bg-color));
   box-shadow: 0 1px 0 0 var(--dc-core-border-color, var(--el-border-color-lighter));
 }
-.list-layout_pager-sticky[data-v-a47ec619] .dc-table-main__pagination {
+.list-layout_pager-sticky[data-v-84c13797] .dc-table-main__pagination {
   position: sticky;
-  bottom: var(--v17e649c5);
+  bottom: var(--v6ead0916);
   z-index: 9;
   margin-top: 0;
   padding-top: 10px;
   background: var(--dc-core-surface, var(--el-bg-color));
   box-shadow: 0 -1px 0 0 var(--dc-core-border-color, var(--el-border-color-lighter));
 }
-.list-layout[data-v-a47ec619] .el-loading-mask {
+.list-layout[data-v-84c13797] .el-loading-mask {
   left: -10px;
   top: -10px;
   right: -10px;
@@ -1286,24 +1340,3 @@ to {
   gap: 8px;
   margin-top: 8px;
 }
-.view-layout[data-v-c8a1cb2d] {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-.view-layout-toolbar[data-v-c8a1cb2d] {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  padding-bottom: 8px;
-  gap: 20px;
-}
-.view-layout-toolbar__left[data-v-c8a1cb2d],
-.view-layout-toolbar__right[data-v-c8a1cb2d] {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-}
-.view-layout-content[data-v-c8a1cb2d] {
-  overflow: auto;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -83,5 +83,5 @@
   "dependencies": {
     "@tanstack/vue-virtual": "^3.13.35"
   },
-  "gitHead": "bb7ff7c309925c6b9738383a60e3a62a80ee99b4"
+  "gitHead": "57af30147986e57cbf53b07e1470448ddfc13661"
 }

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

@@ -8,7 +8,7 @@
 | 组件 | 一句话 | 核心 props | 文档 |
 | --- | --- | --- | --- |
 | `AppLayout` | 应用布局总控：bridge/appStore/userStore 三注入 + 5 内容锚 + 内置默认经典布局 shell | `bridge`（必填）`appStore`（必填）`userStore`（必填）`watermarkContent` `sidebarAboveHeader` | [README-AppLayout.md](./docs/README-AppLayout.md) |
-| `AppPage` | 页面主体容器：撑满视口 + 四向悬浮 fixed 插槽 | `fullViewport` `fullMode` `gap` `topBg`/`bottomBg`/`leftBg`/`rightBg` `nextViewportMaxHeight` | [README-AppPage.md](./docs/README-AppPage.md) |
+| `AppPage` | 页面主体容器：撑满视口 + 四向悬浮 fixed 插槽 + 超宽屏内容限宽居中 | `fullViewport` `fullMode` `gap` `contentCentered`/`contentMaxWidth` `topBg`/`bottomBg`/`leftBg`/`rightBg` `nextViewportMaxHeight` | [README-AppPage.md](./docs/README-AppPage.md) |
 | `AppBody` | 内容主体：内置 RouterView + KeepAlive + 面包屑 affix + #footer 槽 | `menuFlatList` | [README-AppBody.md](./docs/README-AppBody.md) |
 | `AppHeader` | 顶栏积木：#left 品牌 + 路由模块菜单（按 path 查 bridge.badge 显徽标）+ #right 操作区 | `menus` `menuFlatList`（必填）`show`（未消费） | [README-AppHeader.md](./docs/README-AppHeader.md) |
 | `AppSidebar` | 侧边栏积木：折叠把手 + MenuTree 菜单（树形/分组双形态）+ #top/#bottom 高度自撑 | `show` `menus`（必填）`menuFlatList`（必填）`aboveHeader`；菜单形态读 bridge `APP_LAYOUT_SIDEBAR_CONFIG.menuGroupMode`（分组态无折叠把手） | [README-AppSidebar.md](./docs/README-AppSidebar.md) |
@@ -39,6 +39,13 @@
 
 9 组件 + `export * from "./types"` + `./viewport`（`CORE_VIEWPORT_DECOR_ZINDEX_BELOW`=800 弹窗下档 / `CORE_VIEWPORT_DECOR_ZINDEX_ABOVE`=10000 弹窗上档）+ `./app-page-geometry`（`computeAppPageReducedViewportHeight`/`computeAppPageReducedViewportWidth`、`computeAppPageContentInset`、`computeAppPageSlotStyles`、`computeAppPageSlotShimStyles` + `APP_PAGE_SLOT_Z_INDEX`=1）
 
+## 相邻族
+
+- **`page-layout`**（同级新族）：一整页级别的编排组件，准入标准 = **DOM 根节点是 `AppPage`**。
+  列表 / 详情同页范式（`AppPageListDetailLayout` / `AppPageDetail`）已迁至该族，见
+  [`../page-layout/README.md`](../page-layout/README.md)。`AppPage` 本身留在本族——它是**被**
+  那个族使用的页面原语。
+
 ## 关联
 
 - 布局插件自供 shell 契约：`AppShellProps` / `AppShellSlots`（types.ts）

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

@@ -1,6 +1,6 @@
 # AppPage（页面容器·撑满视口 + 四向悬浮插槽）
 
-> 页面主体容器：默认 slot 按视口高变量撑满（min-height/height 双模式），#top/#bottom/#left/#right 四向 fixed 悬浮插槽（shim 呼吸 + gap 间距）。
+> 页面主体容器：默认 slot 按视口高变量撑满（min-height/height 双模式），#top/#bottom/#left/#right 四向 fixed 悬浮插槽（shim 呼吸 + gap 间距），超宽屏内容限宽居中。
 > 范式页：`apps/reference/src/pages/app-layout/page-slots/`（四向悬浮槽 + ChainReadout 高度链互动面板）
 
 ## 定位
@@ -9,6 +9,7 @@
 - **何时不用**：无需容器几何（纯组件局部）时直接用裸组件
 - 默认 slot 内容经 ModalShelf page 层包裹（弹层挂载点）
 - 四向悬浮插槽为 fixed 定位（z-index `APP_PAGE_SLOT_Z_INDEX`=1），top/bottom 通栏量高、left/right 量宽，尺寸几何由 `app-page-geometry` 纯函数计算
+- `contentCentered` 开启后默认 slot 内容限宽居中（超宽屏适配，默认 1200px）——**四向悬浮槽与 `background` 仍通栏**（chrome / 底色通栏、只有内容列限宽，超宽下两侧留白露出页面底色）
 
 ## 快速上手（最小可用）
 
@@ -28,9 +29,18 @@
 </AppPage>
 ```
 
+超宽屏（2K / 4K）下内容限宽居中（默认 1200px，窄屏自动无感）：
+
+```vue
+<AppPage content-centered>
+  <FormMain ... />
+</AppPage>
+```
+
 ## 能力边界 / 按需使用
 
 - **四向悬浮插槽（`#top`/`#bottom`/`#left`/`#right`）：默认全关、常规页面不需要。** 仅当页面需要「悬浮于内容之上的固定补充区」（通栏操作条 / 侧边抽屉 / 浮动提示）才开对应槽——判据：内容必须 fixed 悬浮且不参与文档流（top/bottom 通栏量高 → padding 让位，left/right 量宽）。列表/表单/详情常规页一律不开。**`#left`/`#right` 内放列表时用 scope 的 `listLayoutRecommended`（见 API）拿窄栏推荐配置，[MUST NOT] 自行拍脑袋配窄栏列表形态。**
+- **`contentCentered`（超宽屏限宽居中）：默认关，按页面类型开。** 表单页 / 详情页 / 阅读型页开（超宽屏下内容整行铺满，label↔控件、行首↔行尾视线跨度过长）；**列表 / 表格页 [MUST NOT] 开**——表格列本就挤，限宽后更挤（业界同解：GitHub 对 diff / 表格页保留全宽）。`contentMaxWidth` 仅在需要非 1200 时设。
 - `topBg`/`bottomBg`/`leftBg`/`rightBg`：仅悬浮槽需要着色时设，默认无背景即够用。
 - `*ObserveResize`：仅当槽内内容有 CSS 过渡折叠 / 异步撑开（不触发重渲染的尺寸变化）才开对应 RO；普通槽内容（v-if/v-show/静态）不开。
 - `fullMode`：默认 `"min-height"` 即够用；`"height"` 仅当页面内子级依赖硬高撑满（如顶级自撑 TabsMain）时选。
@@ -46,7 +56,9 @@
 | `fullViewport` | `boolean` | `false` | 撑满视口 |
 | `fullMode` | `"min-height" \| "height"` | `"min-height"` | 撑满方式 |
 | `nextViewportMaxHeight` | `string` | `var(--app-viewport-max-height)` | shim 内视口高变量覆写 |
-| `background` | `string` | 无 | 根盒背景 |
+| `background` | `string` | 无 | 根盒背景（通栏，不受限宽影响） |
+| `contentCentered` | `boolean` | `false` | 默认 slot 内容限宽居中（超宽屏适配）；同步收窄对后代公布的内容几何（见下） |
+| `contentMaxWidth` | `number` | `1200` | 限宽值（px），仅 `contentCentered` 开启时生效 |
 | `gap` | `number` | `8` | 悬浮槽与内容间隔 px |
 | `topBg` / `bottomBg` / `leftBg` / `rightBg` | `string` | 无 | 各槽 shim 背景 |
 | `topObserveResize` / `bottomObserveResize` / `leftObserveResize` / `rightObserveResize` | `boolean` | 均 `false` | 逐槽 WatchSize RO 观测（CSS 过渡折叠等非重渲染尺寸变化时开） |
@@ -100,6 +112,34 @@
 
 **类型**：`AppPageListLayoutRecommended`（`app-layout/types.ts` 导出，非泛型——与 ListLayout 泛型 props 无关的平铺子集）。
 
+### `contentCentered` / `contentMaxWidth`（超宽屏内容限宽居中）
+
+**意图**：超宽屏（2K / 4K / 带鱼屏）下默认 slot 内容整行铺满会让视线跨度过长（表单 label↔控件、正文行首↔行尾），开启后内容列限宽居中、两侧留白露出页面底色。窄屏（可用宽 ≤ `contentMaxWidth`）留白为 0，**与关闭态逐字节一致**，无需断点判断。
+
+**机制**：**不新增 DOM 节点**——在既有 `.app-page-shim` 的左右 padding 上各叠一份「超宽留白」`gutter`：
+
+```
+gutter = max(0, (内容可用宽 − contentMaxWidth) / 2)
+paddingLeft  = 左槽让位量 + gutter
+paddingRight = 右槽让位量 + gutter
+```
+
+「内容可用宽」= AppPage 盒宽扣四向槽让位（即 `computeAppPageReducedViewportWidth`）。因此**居中基准是「两个侧槽之间那段区域」而非整个窗口**——`#left`/`#right` 只开单侧时内容仍精确居中于剩余可用区，不会被槽压偏。
+
+> 选型：本能力**刻意不套限宽容器**。`.app-page-shim` 上挂着 `data-dc-slot`（默认槽区域标记），`useContextDefaults` 读的是**直系父 DOM**——中间插一层容器会让 ListLayout 窄栏默认、ViewLayout/TabsMain `refine` 上下文默认静默失效。padding 方案与套容器行为等价，且零 DOM 变更、零失效风险。
+
+**对后代公布的几何同步收窄**（开启后下列三者一致，下游零改动即对）：
+
+| 出口 | 开启后 |
+| --- | --- |
+| `.app-page-shim` 左右 padding | 各 `+ gutter`（内容盒宽 = `contentMaxWidth`） |
+| `APP_PAGE_CONTENT_INSET` 的 `left`/`right` | 各 `+ gutter`（fixed / 悬浮元素贴真实内容列边，而非页面边） |
+| `--dc-page-content-viewport-width` | `min(原值, contentMaxWidth)` |
+
+高度链（`SCOPE_VIEWPORT_MAX_HEIGHT` / `BODY_CONTENT_VIEWPORT_HEIGHT`）、四向悬浮槽几何、`background` 均**不受影响**——限宽是纯横向能力，chrome 与底色通栏。
+
+**`contentMaxWidth` 只接受 `number`（px）**：几何链三处出口都要拿它参与数值运算（gutter 求差、`min` 比较），CSS 字符串（`80rem` / `50%`）无法参与，会让样式与公布几何脱钩。需要相对单位请自行换算成 px 传入。
+
 ### Expose
 
 无
@@ -108,13 +148,19 @@
 
 - **悬浮槽尺寸变化来自 CSS 过渡/异步撑开 → 必须开对应 `observeResize`**（onUpdated 只读渲染后瞬时值，过渡动画读起点漏最终）
 - 四向槽 fixed 定位——内容滚动时悬浮不动，属设计语义，勿误当普通 inline 槽
+- **运行时动态增减插槽（在槽模板上挂 `v-if`）不生效**——`hasTop/hasBottom/hasLeft/hasRight` 取 `!!slots.x`，`slots` 非响应式对象、computed 无依赖恒吃首次结果。插槽集 [MUST] 当静态结构写死；确需切换整套槽形态由调用方给 AppPage 换 `:key` 重挂载
 - 槽尺寸/inset 几何由 `app-page-geometry` 纯函数计算导出，[MUST NOT] 手写自造
 - `listLayoutRecommended` 开 `customView` 后 [MUST] 配套 ListLayout `#custom-view-item`，否则窄栏卡片渲染为空
+- **列表 / 表格页开 `contentCentered`** —— 表格列本就挤，限宽后更挤；限宽只服务表单 / 详情 / 阅读型页
+- `contentMaxWidth` 传 CSS 字符串（`"80rem"`）—— 只收 `number`（px），字符串会让样式与公布几何脱钩
+- [MUST NOT] 在业务侧改写 `.app-page-shim` padding 自造限宽 —— 会与槽让位量打架且不同步 `APP_PAGE_CONTENT_INSET`；限宽一律走 `contentCentered`。子级确需破框全宽（full-bleed）时用负 margin 主动逃逸，属逃生舱
 - `listLayoutRecommended` 是 AppPage → ListLayout 的**定向耦合**（AppPage 持有 ListLayout prop 形状子集），属本能力设计使然；若 ListLayout 该子集发生 breaking，[MUST] 同步更新 `app-layout/types.ts` 与本 README
 
 ## 关联
 
+- 超宽限宽留白：`use-content-box.ts`（`useAppPageContentBox` → `contentGutter`，core 内部组合函数不出桶）
 - 几何纯函数：`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 高度链互动面板）
+- 超宽限宽范式页：`apps/reference/src/pages/app-layout/content-box/`（开关 / 限宽值 / 槽组合 + 公布几何实时读数）
 - 窄栏列表范式：`apps/reference/src/pages/app-layout/narrow-list/`（#left/#right 放 ListLayout + `listLayoutRecommended`，与裸用对照）

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

@@ -97,7 +97,8 @@
 | `toolbar` | `TableToolbarConfig<T,SQ,F>` | — | toolbar 配置（按钮 / 刷新 / 自动刷新 / 导出） |
 | `infiniteListProps` | `InfiniteListViewConfig` | — | InfiniteListView 配置透传（distance/endText/errorText/pullRefresh/estimateSize/overscan） |
 
-**v-model**：`isAutoRefresh`（boolean）、`refreshInterval`（number，秒）。
+**v-model**：`isAutoRefresh`（boolean）、`refreshInterval`（number，秒）、`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()` 归一，且**保留调用方写入的原值**不回写覆盖。点击卡片即设为当前项，卡片容器挂 `.is-active` 钩子类（视觉由消费方覆写）。⚠️ 该能力**止步于本组件**，[MUST NOT] 下沉 `InfiniteListView`——它的「一项」是网格**整行**（多张卡片），粒度是可滚动单元而非业务记录。
+
 
 ### Emits
 

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

@@ -53,17 +53,24 @@
 | `selectable` | `boolean` | `false` | 启用选中能力 |
 | `getRenderCtxParams` | `() => Pick<TableColumnDefaultScope<T, F>, "injectInfo" \| "exposeInfo">`（必填） | 无 | 列 render 上下文（必填契约） |
 
+### v-model
+
+| 名 | type | 语义 |
+| --- | --- | --- |
+| `activeId` | `string \| number \| undefined` | **「当前项」唯一键**（= 用户点击/激活的那一条；[MUST NOT] 与勾选 `selected` 混同）。点击任一项即写入。`string` / `number` 两种都是一等公民：出口值**保原始类型**（`rowKey` 为字段名时即 `row[rowKey]`，数字 id 出数字），外部用另一种类型写入也命中（比对内部 `String()` 归一，且保留调用方原值） |
+| `activeData` | `T \| undefined` | 当前项对应的**列表数据原样**。与 `activeId` **同生同灭**：`activeId` 有值 ⇒ 本值必有值；`data` 刷新后当前项不在新数据内 → 两者一并清空；外部写入不在 `data` 内的 id → 忽略 + `console.warn`（不清空既有选中） |
+
 ### Emits
 
 | 事件 | 载荷 | 语义 |
 | --- | --- | --- |
-| `selectionChange` | `rows: T[]` | 选中项变更 |
+| `selectionChange` | `rows: T[]` | 选中项变更（勾选语义，与 active 无关） |
 
 ### Slots
 
 | 槽 | scope | 语义 |
 | --- | --- | --- |
-| `#item` | `DataListViewItemScope<T>`（`fieldComponentMap` / `row` / `index` / `selected` / `toggleSelect`） | 单项渲染（customView 卡片内容） |
+| `#item` | `DataListViewItemScope<T>`（`fieldComponentMap` / `row` / `index` / `selected` / `toggleSelect` / `active` / `setActive`） | 单项渲染（customView 卡片内容）。`active` = 是否当前项、`setActive()` = 设为当前项（等价点击该项） |
 | `#empty` | 无 | 空态（默认 `<el-empty />`，消费方可覆写） |
 
 ### Expose（`DataListViewInstance` = TableInstance 对齐）
@@ -77,7 +84,8 @@
 - **不对外导出**：本组件 [MUST NOT] 对外导出 / 全局注册 / 提供 install 插件；消费方 [MUST] 走 `TableMain` `customView` 模式
 - **无请求/分页**：`data` 须外部传入（当前页数据），勿期待组件内部取数
 - **刷新清选中**：`data` 引用变化即清空选中——跨页 / 刷新后选中状态不保留
-- **未实现方法抛错**：Expose 面与 TableInstance 对齐但 10 个方法为「not supported」桩（表格特有行为在自定义视图无意义）
+- **未实现方法抛错**：Expose 面与 TableInstance 对齐但 10 个方法为「not supported」桩（表格特有行为在自定义视图无意义）——含 `setCurrentRow`，故 TableMain 在 `customView` 态 [MUST NOT] 调它同步高亮（active 由本组件自持）
+- **`.is-active` / `.is-selected` 是空钩子类**：本族 [MUST NOT] 写死卡片视觉，选中 / 当前项的样式由消费方覆写
 - **列键依赖归一规则**：消费 `fieldComponentMap` 只用 `prop` / `$type_index` / `$type_selection` 三系键，`type: "expand"` 列不产出
 
 ## DataListViewItem（列表项容器）
@@ -88,7 +96,8 @@
 
 | name | type | 默认 | 语义 |
 | --- | --- | --- | --- |
-| `selected` | `boolean`（必填） | 无 | 是否选中（由 DataListView 传入） |
+| `selected` | `boolean`（必填） | 无 | 是否选中（勾选语义，由 DataListView 传入）→ `.is-selected` |
+| `active` | `boolean` | `false` | 是否为「当前项」（active，与勾选无关）→ `.is-active` |
 
 ### Emits / Expose
 

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

@@ -109,7 +109,7 @@ const { listPageConfig } = useSpaceConfig({
 | `headerObserveResize` / `operationObserveResize` | `boolean` | 均 `false` | header/操作槽量高 ResizeObserver |
 | `initialSearch` | `boolean` | `true` | 挂载后是否立即触发初始化查询（默认查）；关闭后表格空态显示「欢迎触发查询」、KeepAlive 激活不自动刷新（TableMain 经「已发生过查询」自判，见 table docs） |
 
-**v-model**：`isAutoRefresh`、`refreshInterval`、`customView`（配合 `#custom-view-item` 卡片渲染）
+**v-model**：`isAutoRefresh`、`refreshInterval`、`customView`（配合 `#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()` 归一，且**保留调用方写入的原值**不回写覆盖。本组件是**纯透传层**，状态机在下游（table 态 → TableMain / DataListView；grid 态 → DataGridView）；⚠️ `viewMode` 切换会换载下游组件 → 当前项随之丢失（既有换载语义）
 
 ### Emits
 

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

@@ -54,6 +54,8 @@
 | `cancelText` | `string \| (() => VNode)` | `"取消"` | 取消按钮文案 |
 | `confirmText` | `string \| (() => VNode)` | `"确定"` | 确认按钮文案 |
 | `hiddenCancel` | `boolean` | `false` | 隐藏取消按钮 |
+| `hiddenFooter` | `boolean` | `false` | **整块隐藏 footer**（操作区容器一并不渲染）。用于「只要弹层容器、不要确认-取消」的场景（如列表详情范式的详情抽屉）。EP 的 dialog / drawer 都按 footer 插槽存在与否渲染容器，故这里是**真不渲染**；[MUST NOT] 改用「传空 `#footer` 插槽」绕——那会留一条带 padding 的空条（drawer 实测 56px） |
+| `hiddenHeader` | `boolean` | `false` | **整块隐藏 header**（标题区 + 关闭按钮）。两形态实现不同（EP 使然）：`drawer` 走 EP 原生 `with-header=false` → 节点真不渲染；`modal` 的 `el-dialog__header` **无条件渲染**，只能由 `dc-confirm-modal_hidden-header` 类 `display:none` 兜。⚠️ 隐藏后失去关闭按钮，[MUST] 自备关闭入口（遮罩 / ESC / 自绘） |
 | `width` | `number \| string` | `420` | modal = 弹窗宽度 / drawer = 抽屉尺寸（size） |
 | `reverse` | `boolean` | `false` | 反转按钮位置 |
 | `closeOnPressEscape` | `boolean` | `true` | ESC 关闭 |

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

@@ -0,0 +1,47 @@
+# page-layout（页面布局族）
+
+> **准入标准：组件的 DOM 根节点是 `AppPage`。** 想进本族的组件 [MUST] 满足它。
+> 标准由 `__tests__/family-contract.test.ts` 守卫（逐个挂载断言根元素带 `.app-page`，
+> 并校验族内每个 `.vue` 都在清单里，防漏登记绕过）。
+
+## 这个族是什么
+
+「**一整页**」级别的编排组件：使用方把它当路由页的根来用，页面的四向 chrome、内容视口几何、
+弹层挂载点等由它内含的 `AppPage` 统一提供。故本族组件与 `AppPage` 是**二选一**关系
+——[MUST NOT] 出现「业务写 `AppPage` 再套本族组件」的嵌套。
+
+**`AppPage` 自己不在本族**：它是**被**本族使用的页面原语（留在 `app-layout`，与 `AppLayout` /
+`AppBody` 同族）。本族是「用 AppPage 搭出来的成品页型」。
+
+## 组件清单
+
+| 组件 | 对外 | 一句话 |
+| --- | --- | --- |
+| `AppPageListDetailLayout` | ✅ | 列表 / 详情同页范式（master-detail）门面：一根 `activeId` 状态线打通列表与详情，宽屏并排 / 窄屏叠加两形态按视口宽定档 |
+| `AppPageDetail` | ✅ | 详情区。默认自带 `AppPage`、可**独立成详情页**；`embedded` 开启后走透传态供门面内嵌 |
+| `AppPageListDetailSplit` | ✗ | 宽屏并排形态（门面实现细节） |
+| `AppPageListDetailSheet` | ✗ | 窄屏叠加形态（抽屉 / 弹窗，门面实现细节） |
+
+两个形态件与 `use-list-detail.ts` [MUST NOT] 出桶——换承载体不算 breaking。
+
+## 标准的唯一例外
+
+`AppPageDetail` 的 **`embedded=true`** 是**显式 opt-out**：宿主（Split / Sheet）已经有一层
+`AppPage`，再套就成两层，故内嵌态走 `SlotLayoutTemplate` 透传、不产生宿主元素。
+守卫测试单独锁住了这条语义（开了就不该有 `.app-page`）。
+
+⚠️ 用 `SlotLayoutTemplate :disabled` 做透传是**有前提**的：它的透传态只渲染默认槽、
+**具名槽无落点**。`AppPageDetail` 只用 `AppPage` 的默认槽，故成立；两个形态件要用
+`#left` / `#right` 等具名槽，[MUST NOT] 照抄。
+
+## 文档
+
+- [README-AppPageListDetailLayout.md](./docs/README-AppPageListDetailLayout.md)
+- [README-AppPageDetail.md](./docs/README-AppPageDetail.md)
+
+## 关联
+
+- 页面原语：`AppPage`（app-layout 族）
+- 不变式内核：`hooks/use-active-record.ts`
+- 上下文 key：`APP_PAGE_LIST_DETAIL_CONTEXT`
+- spec：`docs/specs/2026-08-31-025041-moderate-列表详情同页范式AppPageListDetailLayout/spec.md`