@done-coding/admin-core 0.30.0 → 0.30.1-alpha.0

package/es/style.css

@@ -66,31 +66,35 @@
   justify-content: flex-end;
   gap: 8px;
 }
-.badge-mark[data-v-9eb89306] .el-badge__content.is-fixed {
+.badge-mark[data-v-64f0421b] .el-badge__content.is-fixed {
   right: 0;
   transform: translateY(-50%) translateX(calc(100% + 2px));
 }
-.badge-mark_middle[data-v-9eb89306] .el-badge__content.is-fixed {
+.badge-mark_middle[data-v-64f0421b] .el-badge__content.is-fixed {
   top: 50%;
 }
-.badge-mark[data-v-9eb89306] .badge-mark__icon {
-  display: block;
-  font-size: 1em;
-  line-height: 1;
+.badge-mark_hidden[data-v-64f0421b] .el-badge__content {
+  width: 0;
+  height: 0;
+  min-width: 0;
+  padding: 0;
+  border-width: 0;
+  overflow: hidden;
+  pointer-events: none;
 }
-.app-page[data-v-facaf577] {
-  --dc-page-content-viewport-top: var(--v14c1dc69);
-  --dc-page-content-viewport-bottom: var(--v6d1cb697);
-  --dc-page-content-viewport-left: var(--f914311a);
-  --dc-page-content-viewport-right: var(--v28c52fa0);
-  --dc-page-content-viewport-width: var(--v2838584c);
-  --dc-page-content-viewport-height: var(--v76c7ad93);
+.app-page[data-v-73e3d4a9] {
+  --dc-page-content-viewport-top: var(--v62d8191f);
+  --dc-page-content-viewport-bottom: var(--v7adfb621);
+  --dc-page-content-viewport-left: var(--v0fb17d06);
+  --dc-page-content-viewport-right: var(--v0d174f66);
+  --dc-page-content-viewport-width: var(--v0d5dbb10);
+  --dc-page-content-viewport-height: var(--f6eaa5c6);
 }
-.app-page-shim[data-v-facaf577] {
+.app-page-shim[data-v-73e3d4a9] {
   display: flow-root;
-  --app-viewport-max-height: var(--v9258c294);
+  --app-viewport-max-height: var(--v4ad30b28);
 }
-.app-page-slot-shim[data-v-facaf577] {
+.app-page-slot-shim[data-v-73e3d4a9] {
   box-sizing: border-box;
   width: 100%;
   height: 100%;
@@ -131,61 +135,91 @@ to {
   text-align: center;
   font-variant-numeric: tabular-nums;
 }
-.view-layout-header[data-v-3c6fd3fe] {
-  flex: 0 1 auto;
-  min-width: 0;
-  overflow: hidden;
-  color: var(--el-text-color-primary);
-  font-size: 16px;
-  font-weight: 600;
-  line-height: 1.4;
-  white-space: nowrap;
-  text-overflow: ellipsis;
-}
-.view-layout[data-v-3c6fd3fe] {
-  display: flex;
-  flex-direction: column;
-}
-.view-layout-toolbar[data-v-3c6fd3fe] {
+.view-layout-toolbar[data-v-99d466e9] {
   display: flex;
   justify-content: space-between;
   align-items: center;
-  padding: 0 var(--v72fb5e44) 0 var(--v7243a29e);
+  padding: 0 var(--v507b6fb2);
   position: relative;
   gap: 20px;
   background: color-mix(in srgb, var(--dc-core-surface, var(--el-bg-color)) 50%, var(--dc-core-ground, var(--el-bg-color-page)));
   border-radius: 0;
 }
-.view-layout-toolbar[data-v-3c6fd3fe]::before {
+.view-layout-toolbar[data-v-99d466e9]::before {
   content: "";
   position: absolute;
   top: 0;
-  bottom: 0;
   left: 0;
-  width: 3px;
+  width: calc(var(--v507b6fb2) * 3);
+  height: 3px;
   border-radius: 3px;
   background: var(--dc-core-primary-color, var(--el-color-primary));
 }
-.view-layout-toolbar__left[data-v-3c6fd3fe],
-.view-layout-toolbar__right[data-v-3c6fd3fe] {
+.view-layout-toolbar_app-bar[data-v-99d466e9] {
+  box-shadow: 0 2px 8px -4px var(--dc-core-border-color, var(--el-border-color));
+  min-height: 44px;
+}
+.view-layout-toolbar_app-bar[data-v-99d466e9]::before {
+  content: none;
+}
+.view-layout-toolbar__back[data-v-99d466e9],
+.view-layout-toolbar__more[data-v-99d466e9] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 44px;
+  height: 44px;
+  font-size: 18px;
+  color: var(--el-text-color-primary);
+  cursor: pointer;
+  user-select: none;
+}
+.view-layout-toolbar__back[data-v-99d466e9]:hover,
+.view-layout-toolbar__more[data-v-99d466e9]:hover {
+  color: var(--dc-core-primary-color, var(--el-color-primary));
+}
+.view-layout-toolbar__back[data-v-99d466e9] {
+  margin-left: -13px;
+}
+.view-layout-toolbar__more[data-v-99d466e9] {
+  margin-right: 0;
+}
+.view-layout-toolbar__left[data-v-99d466e9],
+.view-layout-toolbar__right[data-v-99d466e9] {
   display: flex;
   align-items: center;
   gap: 10px;
 }
-.view-layout-toolbar__left[data-v-3c6fd3fe] > *,
-.view-layout-toolbar__right[data-v-3c6fd3fe] > * {
+.view-layout-toolbar__left[data-v-99d466e9] > *,
+.view-layout-toolbar__right[data-v-99d466e9] > * {
   flex: none;
 }
-.view-layout-toolbar__left .view-layout-header[data-v-3c6fd3fe] {
+.view-layout-toolbar__left .view-layout-header[data-v-99d466e9] {
   flex: 1 1 auto;
 }
-.view-layout-toolbar__right[data-v-3c6fd3fe] {
+.view-layout-toolbar__right[data-v-99d466e9] {
   flex: none;
 }
-.view-layout-content[data-v-3c6fd3fe] {
+.view-layout-header[data-v-99d466e9] {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--el-text-color-primary);
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 1.4;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.view-layout[data-v-f386aec7] {
+  display: flex;
+  flex-direction: column;
+}
+.view-layout-content[data-v-f386aec7] {
   overflow: auto;
   box-sizing: border-box;
-  padding: var(--v72fb5e44) var(--v72fb5e44) var(--v72fb5e44) var(--v7243a29e);
+  padding: var(--v5975c734);
 }
 .dc-app-page-detail__title[data-v-1b784d3a] {
   padding-bottom: 12px;
@@ -194,17 +228,20 @@ to {
   line-height: 24px;
   color: var(--dc-core-text-color, var(--el-text-color-primary));
 }
-.dc-app-page-list-detail-split__list[data-v-7aa91bcb] {
+.dc-app-page-list-detail-split__list[data-v-68dc7b6b] {
   box-sizing: border-box;
+  width: 100%;
   height: 100%;
   overflow: hidden;
 }
-.form-item-tip[data-v-8b508d64] {
+.form-item-tip[data-v-940abdf9] {
+  width: 100%;
+  min-width: 0;
   text-align: left;
   line-height: 1.5;
   font-size: 12px;
 }
-.form-item-label-hide[data-v-8b508d64] .el-form-item__label-wrap {
+.form-item-label-hide[data-v-940abdf9] .el-form-item__label-wrap {
   display: none;
 }
 .drag-float[data-v-0ab49ed7] {
@@ -825,7 +862,9 @@ to {
 .app-layout_noAnimation[data-v-140fec15] .app-collapse-toggle {
   transition: none !important;
 }
-.form-group-title[data-v-c6148d68] {
+.form-group-title[data-v-ee226102] {
+  width: 100%;
+  min-width: 0;
   display: flex;
   align-items: center;
   gap: 4px;
@@ -835,16 +874,16 @@ to {
   color: var(--dc-core-base-color, var(--el-text-color-primary));
   user-select: none;
 }
-.form-group-title_collapsible[data-v-c6148d68] {
+.form-group-title_collapsible[data-v-ee226102] {
   cursor: pointer;
 }
-.form-group-title-arrow[data-v-c6148d68] {
+.form-group-title-arrow[data-v-ee226102] {
   font-size: 12px;
   color: var(--el-text-color-secondary);
   transform: rotate(90deg);
   transition: transform var(--dc-core-motion-duration, 0.2s) var(--dc-core-motion-easing, ease);
 }
-.form-group-title-arrow_collapsed[data-v-c6148d68] {
+.form-group-title-arrow_collapsed[data-v-ee226102] {
   transform: rotate(0deg);
 }
 .form-divider[data-v-66a37c1d] {
@@ -934,24 +973,24 @@ to {
     animation: none;
 }
 }
-.infinite-list-view_surface[data-v-a62d17f9] {
+.infinite-list-view_surface[data-v-4f0267ce] {
   box-sizing: border-box;
-  padding: var(--v9e087332);
+  padding: var(--v407ba190);
   border-radius: var(--dc-core-radius, var(--el-border-radius-base));
 }
-.infinite-list-view_surface-bg[data-v-a62d17f9] {
+.infinite-list-view_surface-bg[data-v-4f0267ce] {
   background: var(--el-bg-color);
 }
-.infinite-list-view[data-v-a62d17f9] {
+.infinite-list-view[data-v-4f0267ce] {
   width: 100%;
 }
-.infinite-list-view__viewport[data-v-a62d17f9] {
+.infinite-list-view__viewport[data-v-4f0267ce] {
   width: 100%;
 }
-.infinite-list-view__sentinel[data-v-a62d17f9] {
+.infinite-list-view__sentinel[data-v-4f0267ce] {
   height: 1px;
 }
-.infinite-list-view__footer[data-v-a62d17f9] {
+.infinite-list-view__footer[data-v-4f0267ce] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -959,17 +998,17 @@ to {
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
   font-size: 13px;
 }
-.infinite-list-view__json[data-v-a62d17f9] {
+.infinite-list-view__json[data-v-4f0267ce] {
   margin: 0;
   font-size: 12px;
   white-space: pre-wrap;
   word-break: break-all;
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.infinite-list-view__tip[data-v-a62d17f9] {
+.infinite-list-view__tip[data-v-4f0267ce] {
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.infinite-list-view__retry[data-v-a62d17f9] {
+.infinite-list-view__retry[data-v-4f0267ce] {
   border: none;
   background: transparent;
   color: var(--dc-core-primary-color, var(--el-color-primary));
@@ -977,10 +1016,10 @@ to {
   cursor: pointer;
   padding: 0;
 }
-.infinite-list-view__retry[data-v-a62d17f9]:hover {
+.infinite-list-view__retry[data-v-4f0267ce]:hover {
   opacity: 0.8;
 }
-.infinite-list-view__empty[data-v-a62d17f9] {
+.infinite-list-view__empty[data-v-4f0267ce] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -988,7 +1027,7 @@ to {
   min-height: 60px;
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.infinite-list-view__pull-indicator[data-v-a62d17f9] {
+.infinite-list-view__pull-indicator[data-v-4f0267ce] {
   display: flex;
   justify-content: center;
   align-items: flex-end;
@@ -997,56 +1036,56 @@ to {
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
   transition: height 0.2s;
 }
-.infinite-list-view__pull-indicator > span[data-v-a62d17f9] {
+.infinite-list-view__pull-indicator > span[data-v-4f0267ce] {
   padding-bottom: 6px;
 }
-.data-grid-view[data-v-136078cd] {
+.data-grid-view[data-v-b4c213bc] {
   width: 100%;
 }
-.data-grid-view_surface[data-v-136078cd] {
-  padding: var(--e2a8f6ae);
+.data-grid-view_surface[data-v-b4c213bc] {
+  padding: var(--v081d8ea3);
   border-radius: var(--dc-core-radius, var(--el-border-radius-base));
 }
-.data-grid-view_surface-bg[data-v-136078cd] {
+.data-grid-view_surface-bg[data-v-b4c213bc] {
   background: var(--el-bg-color);
 }
-.data-grid-view__grid[data-v-136078cd] {
+.data-grid-view__grid[data-v-b4c213bc] {
   display: grid;
 }
-.data-grid-view__cell.is-active[data-v-136078cd] {
+.data-grid-view__cell.is-active[data-v-b4c213bc] {
   /* stylelint-disable-next-line block-no-empty */
 }
-.data-grid-view__cell[data-v-136078cd] {
+.data-grid-view__cell[data-v-b4c213bc] {
   min-width: 0;
 }
-.data-grid-view__cell.is-card[data-v-136078cd] {
+.data-grid-view__cell.is-card[data-v-b4c213bc] {
   box-sizing: border-box;
   background: var(--el-bg-color);
   border: 1px solid var(--dc-core-border-color, var(--el-border-color-lighter));
   border-radius: var(--dc-core-radius, var(--el-border-radius-base));
 }
-.data-grid-view__card[data-v-136078cd] {
+.data-grid-view__card[data-v-b4c213bc] {
   height: 100%;
   box-sizing: border-box;
   overflow: hidden;
 }
-.data-grid-view__field[data-v-136078cd] {
+.data-grid-view__field[data-v-b4c213bc] {
   display: flex;
   gap: 6px;
   align-items: baseline;
   line-height: 1.6;
   font-size: 13px;
 }
-.data-grid-view__field-label[data-v-136078cd] {
+.data-grid-view__field-label[data-v-b4c213bc] {
   flex-shrink: 0;
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.data-grid-view__field-value[data-v-136078cd] {
+.data-grid-view__field-value[data-v-b4c213bc] {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
-.data-grid-view__empty-error[data-v-136078cd] {
+.data-grid-view__empty-error[data-v-b4c213bc] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -1075,16 +1114,18 @@ to {
   font-size: 13px;
   color: var(--el-text-color-placeholder);
 }
-.form-item-nest-form[data-v-46959572] {
+.form-item-nest-form[data-v-358d6905] {
   --dc-nest-indent: 16px;
 }
-.form-item-nest-form[data-v-46959572] {
+.form-item-nest-form[data-v-358d6905] {
   position: relative;
   background: var(--el-bg-color-page);
   border-radius: 8px;
+  width: 100%;
+  min-width: 0;
   padding: 0 0 0 var(--dc-nest-indent);
 }
-.form-item-nest-form[data-v-46959572]::before {
+.form-item-nest-form[data-v-358d6905]::before {
   content: "";
   position: absolute;
   top: 0;
@@ -1094,25 +1135,27 @@ to {
   background: var(--el-border-color-darker);
   border-radius: 3px;
 }
-html.dark .form-item-nest-form[data-v-46959572]::before {
+html.dark .form-item-nest-form[data-v-358d6905]::before {
   background: var(--dc-core-border-color, var(--el-border-color));
 }
-.form-item-nest-form-list[data-v-f9ac937e] {
+.form-item-nest-form-list[data-v-b6b79293] {
   padding: 12px;
   background: var(--el-bg-color-page);
   border-radius: 8px;
+  width: 100%;
+  min-width: 0;
 }
-.form-item-nest-form-list-row[data-v-f9ac937e] {
+.form-item-nest-form-list-row[data-v-b6b79293] {
   position: relative;
   margin-bottom: 8px;
 }
-.form-item-nest-form-list-row-body[data-v-f9ac937e] {
+.form-item-nest-form-list-row-body[data-v-b6b79293] {
   min-width: 0;
   padding: 32px 12px 8px;
   background: var(--el-bg-color);
   border-radius: 6px;
 }
-.form-item-nest-form-list-row[data-v-f9ac937e] .form-item-nest-form-list-row-remove {
+.form-item-nest-form-list-row[data-v-b6b79293] .form-item-nest-form-list-row-remove {
   position: absolute;
   top: 4px;
   right: 8px;
@@ -1190,6 +1233,10 @@ html.dark .form-item-nest-form[data-v-46959572]::before {
   display: inline-flex;
   vertical-align: middle;
 }
+.dc-form-tree[data-v-e64f6895] {
+  width: 100%;
+  min-width: 0;
+}
 .dc-form-upload-trigger[data-v-9fb0fb2a] {
   display: flex;
   align-items: center;
@@ -1209,7 +1256,11 @@ html.dark .form-item-nest-form[data-v-46959572]::before {
   padding: 0;
   color: var(--el-text-color-secondary);
 }
-.dc-form-upload__placeholder[data-v-9f186e75] {
+.dc-form-upload[data-v-1b155db4] {
+  width: 100%;
+  min-width: 0;
+}
+.dc-form-upload__placeholder[data-v-1b155db4] {
   margin-top: 4px;
   font-size: 12px;
   line-height: 1.5;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.30.0",
+  "version": "0.30.1-alpha.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -83,5 +83,5 @@
   "dependencies": {
     "@tanstack/vue-virtual": "^3.13.35"
   },
-  "gitHead": "3684244f709623c3e15acb3ba78d25ddb7cb9ac0"
+  "gitHead": "ce4ef5042019885e7557f09a8e03f09836c66ec8"
 }

package/src/bridge/docs/README.md

@@ -88,18 +88,29 @@ type BadgeEntry = {
   description?: string;
   /** 本条标的版本号（core 不消费，纯透传）；消费方据它做「版本化的已读记录」 */
   version?: string | number;
+  /**
+   * 角标显不显示；缺省 = 跟随全局默认（`defaultVisible`，本身缺省 `true`）。
+   * 🔴 `false` **只藏角标、留 DOM 挂点**（引导插件照常定位得到）——
+   * 与「压根没配这条 key」是两回事。遮挡档（`locked`）**拒绝隐藏**，dev 下会 warn。
+   */
+  visible?: boolean;
 } & (
   | { kind: "count";   value: number; max?: number }   // 数字角标
   | { kind: "new" }        // 新上线
-  | { kind: "updated" }    // 更新
-  | { kind: "beta" }       // 内测：能用，不稳定
+  | { kind: "updated" }    // 已更新
+  | { kind: "beta" }       // 内测中：能用，不稳定
   | { kind: "wip" }        // 开发中：仅提示，**不拦点击**
+  | { kind: "planned" }    // 规划中：还没开工
+  | { kind: "deprecated" } // 待下线
+  | { kind: "locked" }     // 未开通：**唯一拦点击、也唯一拒绝隐藏的档**
   | { kind: "custom";  text: string; type?: BadgeProps["type"] }
-  | { kind: "anchor" }     // 伪标：不渲染角标，只留 DOM 挂点供引导定位
+  | { kind: "anchor" }     // 伪标：恒隐藏角标，只留 DOM 挂点供引导定位
 );
 ```
 
-内置五档的文案与语义色由 core 统一定，保证跨 app 一致；`custom` 只在内置档不够用时用。
+内置七档的文案与语义色由 core 统一定，保证跨 app 一致；`custom` 只在内置档不够用时用。
+**七档一律走文字**（甲方 2026-09-19 撤回 v0.30 的图标态），详见
+[BadgeMark 文档](../../components/display/docs/README-BadgeMark.md)。
 
 **`version` 的用处**：消费方（如 `forge-plugin-guide`）把已读记录的 key 取成 `key@version`
 ⇒ **功能有实质更新时改一下版本号，引导 / 提示就对所有人重新出现一次**；不改则关过的人不再被打扰。
@@ -116,6 +127,25 @@ type BadgeEntry = {
 | `setAll(map)` | **整体替换** —— 轮询主路径，服务端本轮撤下的标随之消失 |
 | `set(key, entry)` | 单点写入 / 覆盖 |
 | `remove(key)` | 单点移除 |
+| `defaultVisible` | **全局默认显不显示**（响应式只读，缺省 `true`）；逐条 `entry.visible` 恒优先 |
+| `setDefaultVisible(v)` | 改全局默认；也可在 `createCoreBridge({ badge: { defaultVisible } })` 初始化时给 |
+
+### 展示开关（`visible` / `defaultVisible`）
+
+徽标当初是拿来做新手引导的；有了 `forge-plugin-guide` 之后徽标不再必须显示 ⇒ 两层开关：
+
+| 层 | 写法 | 缺省 |
+| --- | --- | --- |
+| 逐条 | `bridge.badge.set(key, { kind: "new", visible: false })` | `undefined` = 跟随全局 |
+| 全局 | `createCoreBridge({ badge: { defaultVisible: false } })` / `bridge.badge.setDefaultVisible(false)` | **`true`** |
+
+🔴 **「配置了但不展示」≠「没配置」**：前者照常渲染 `ElBadge` + `data-dc-badge-key` 挂点，
+引导插件**仍能定位**；后者渲染裸插槽、连挂点都没有。
+⇒ 隐藏走 `visible`，[MUST NOT] 用 `v-if` 把整条标掐掉。
+
+🔴 **遮挡档（`BADGE_MASK_KINDS`，现仅 `locked`）拒绝隐藏**：逐条 `visible:false` 与全局默认
+都不作用到它，dev 下 `console.warn` 一句。依据：遮挡是**功能**不是资讯，藏了会变成
+「点不动又没说明的按钮」或「未开通却能点」。
 
 ⚠️ [MUST NOT] 用 `bridge.update()` 维护徽标：它是 `Object.assign` **浅合并**，轮询场景下服务端已撤下的标会永远留在表里。徽标独立走 `bridge.badge`。
 

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

@@ -60,6 +60,7 @@
 | `nextViewportMaxHeight` | `string` | `var(--app-viewport-max-height)` | shim 内视口高变量覆写 |
 | `background` | `string` | 无 | 根盒背景（通栏，不受限宽影响） |
 | `contentCentered` | `boolean` | `false` | 默认 slot 内容限宽居中（超宽屏适配）；同步收窄对后代公布的内容几何（见下） |
+| `leftWidth` / `rightWidth` | `string?` | — | `#left` / `#right` 槽的**显式宽度**（CSS 长度串）。缺省不写 ⇒ 槽宽跟内容走（shrink-to-fit，老行为）。🔴 **槽内内容要用百分比宽时 [MUST] 改用本 prop**，见下 |
 | `contentMaxWidth` | `number` | `1200` | 限宽值（px），仅 `contentCentered` 开启时生效 |
 | `gap` | `number` | `8` | 间距基数 px（缺省读 bridge `APP_LAYOUT_GAP_CONFIG.size`）。**槽 ↔ 内容**与**槽 ↔ 槽**都取由它派生的「外圈档」（`基数 × 2`，随密度缩放），两处同式同源 |
 | `topBg` / `bottomBg` / `leftBg` / `rightBg` | `string` | `var(--el-bg-color)`（面色） | 各槽 shim 背景；传 `"transparent"` 可关。**shim 自带圆角**（`--dc-core-radius`，随主题；无 bg 的槽透明、圆角无视觉影响） |
@@ -161,13 +162,80 @@ paddingRight = 右槽让位量 + gutter
 
 无
 
+### 方位槽空壳检测（dev-only，每槽只报一次）
+
+四向槽是 **fixed 悬浮区**：槽一旦渲染，即使里面的东西「不占版面」，
+**槽本身**照样铺 padding + 背景、照样从默认内容里扣掉让位高度（实测一条 16px 空白带）。
+
+⇒ dev 下（`import.meta.env.DEV`）挂载时检查每个方位槽渲染出的内容：
+若**全是不占版面的节点**（注释 / teleport 锚点 / 空文本）⇒ 一条 `console.error`，
+**同一个槽只报一次**（不刷屏）：
+
+```
+[AppPage] #top 槽里没有占版面的内容，但槽本身照样渲染（fixed + padding + 背景）
+并从默认内容里扣掉让位高度 —— 白占一条。
+· 若放的是 ModalPorter：移到**默认槽**（page 架子就住在默认槽里，与 AppPage 并列同样够不到，evoke() 一样恒为 null）；
+· 若放的是自己 teleport 走、不需要 page 架子的弹窗：移到默认槽或与 AppPage 并列均可；
+· 若是 v-if 条件渲染的内容：此刻恰好为空，忽略本条。
+```
+
+| 情形 | 是否报 |
+| --- | --- |
+| 槽里只有 `ModalPorter` / 已 teleport 的弹窗 | ✅ 报（正是要防的） |
+| 槽里内容被 `v-if` 暂时关掉 | ⚠️ 会报 —— **合法动态状态**，靠 dev-only + 去重 + 文案给出口兜住，忽略即可 |
+| 槽里有正常内容 | ❌ 不报 |
+| 生产构建 | ❌ 不报（dev-only） |
+
+🔴 **只「报出来」，[MUST NOT] 顺手改成「空槽就不渲染」** —— 那是行为变更、会动已有页面布局，
+与检测是两件事；真要做得单独一版、走 migrations 说清楚。
+
+## 侧槽宽度：内容要用百分比时 [MUST] 用 `leftWidth` / `rightWidth`
+
+### 🔴 为什么槽内的百分比宽会留下死白
+
+`#left` / `#right` 是 **`position: fixed` 且只给了 `left` / `right`** ——
+没有 `width`、没有对边 ⇒ 宽度**跟内容走**（shrink-to-fit）。
+
+槽内内容若写百分比宽，浏览器两趟算下来自相矛盾：
+
+1. 算**内在尺寸**时百分比按 `auto` 处理 ⇒ 槽被撑到内容的 **max-content**；
+2. 之后百分比才解析，基数是**刚被内容撑出来的那个宽** ⇒ 解出来往往远小于槽；
+3. ⇒ **槽里剩一大片死白**，且**随内容变丰富而变大**。
+
+实测（1280 视口，列表详情 split 档，`width: clamp(280px, 28%, 420px)` 写在槽内内容上）：
+槽 **517** / 内容 **280** ⇒ 死白 **229px**。
+
+### 处置：把宽度放到**槽这一层**
+
+```vue
+<AppPage :leftWidth="listWidth">
+  <template #left>
+    <div style="width: 100%">…</div>   <!-- 内容只吃满槽 -->
+  </template>
+</AppPage>
+```
+
+槽是 `fixed` ⇒ 包含块是**视口**（初始包含块）⇒ 百分比有**稳定且不循环**的基数。
+实测 `28%` 在 1280 下精确得 **358px**，死白降到 **8px**（= shim padding），
+且**加长内容后不再恶化**。
+
+🔴 **[MUST NOT] 改用 `--dc-page-content-viewport-width` 当百分比基数**：
+那个变量是**内容区**宽（已扣掉左右槽），语义本就不对，而且**它本身就在循环链上**
+（内容区宽 ← 侧槽宽 ← 槽内内容宽）。
+
+⚠️ 写在这里的宽度照常被 `WatchSize` 量到、回写进内容区的让位 padding（实测跟得上），
+几何链不受影响。`#top` / `#bottom` 是**通栏**（`left` + `right` 双边定位），
+不存在这个问题、也没有对应 prop。
+
 ## 反模式 / 注意
 
 - **悬浮槽尺寸变化来自 CSS 过渡/异步撑开 → 必须开对应 `observeResize`**（onUpdated 只读渲染后瞬时值，过渡动画读起点漏最终）
 - 四向槽 fixed 定位——内容滚动时悬浮不动，属设计语义，勿误当普通 inline 槽
 - **运行时动态增减插槽（在槽模板上挂 `v-if`）不生效**——`hasTop/hasBottom/hasLeft/hasRight` 取 `!!slots.x`，`slots` 非响应式对象、computed 无依赖恒吃首次结果。插槽集 [MUST] 当静态结构写死；确需切换整套槽形态由调用方给 AppPage 换 `:key` 重挂载
+- **[MUST NOT] 把 `ModalPorter` / 弹窗放进方位槽**：方位槽是页面内置 `ModalShelf` 的**兄弟**不是后代，`provide` 够不到（`evoke()` 恒 null），且槽本身白占版面。两条检测都会在控制台点名（见上）
 - 槽尺寸/inset 几何由 `app-page-geometry` 纯函数计算导出，[MUST NOT] 手写自造
 - `listLayoutRecommended` 开 `customView` 后 [MUST] 配套 ListLayout `#custom-view-item`，否则窄栏卡片渲染为空
+- **在 `#left`/`#right` 槽内写百分比宽**：[MUST NOT]——槽是 shrink-to-fit，百分比没有稳定基数，会留下大片死白且随内容变大；宽度放 `leftWidth` / `rightWidth`
 - **列表 / 表格页开 `contentCentered`** —— 表格列本就挤，限宽后更挤；限宽只服务表单 / 详情 / 阅读型页
 - `contentMaxWidth` 传 CSS 字符串（`"80rem"`）—— 只收 `number`（px），字符串会让样式与公布几何脱钩
 - [MUST NOT] 在业务侧改写 `.app-page-shim` padding 自造限宽 —— 会与槽让位量打架且不同步 `APP_PAGE_CONTENT_INSET`；限宽一律走 `contentCentered`。子级确需破框全宽（full-bleed）时用负 margin 主动逃逸，属逃生舱