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

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

@@ -12,7 +12,7 @@
 - **数据路径与 TableMain 不同构**：TableMain = 分页替换当前页；DataGridView = **存量累加**（滚动到底 append 下一页，直到 hasMore=false）。两者是两套数据状态机，故**不共存于同一组件内**——切换在 `ListLayout` 的 `viewMode` 层
 - 泛型三参：`T` 行 / `SQ` 静态查询参数 / `F` 注入对象类型；`query` 变化时清空存量从第 1 页重新累加
 - 内部结构：数据容器（本组件）→ InfiniteListView（IO 哨兵触发 + 虚拟化 + 底部三态）→ gridColumns 卡片网格
-- **瀑布流不在本组件**：虚拟化按列数 chunk 成**等高行**，与瀑布流「卡片不等高、跨行装箱」天然冲突 ⇒ 该能力落在分页路径 `DataListView`（无虚拟化）
+- **瀑布流本组件也有**（`masonry` + `estimateItemHeight` 同开同关）：虚拟化与瀑布流**不是天然冲突**（早期文档那个措辞偏强），两者共存**需要一个前提** —— **高度可预先计算**。给了逐项估高即走「算高 → 装箱 → 虚拟化」；不给则保持等高行。与 `DataListView`（分页路径、直接量高、零额外输入）是两套机制，见下「瀑布流」段
 
 ## 快速上手（最小可用）
 
@@ -139,8 +139,90 @@
 
 `refresh(silent?: boolean): Promise<unknown>`（清空存量重拉第 1 页）、`reload(silent?: boolean): Promise<unknown>`（回第 1 页重拉，同 refresh）、`getTableInstance(): TableInstance | undefined`（虚拟网格实例——选中/滚动能力对齐 TableInstance 子集，未实现方法为「not supported」抛错桩）。
 
+## 瀑布流（`masonry` + `estimateItemHeight`，opt-in）
+
+```vue
+<DataGridView
+  :api="api"
+  :grid-columns="4"
+  masonry
+  :estimate-item-height="(row, columnWidth) =>
+    columnWidth * (row.coverHeight / row.coverWidth) + 72"
+>
+  <template #custom-view-item="{ row }"><SocialCard :row="row" /></template>
+</DataGridView>
+```
+
+### 🔴 为什么要 `estimateItemHeight`（不是啰嗦）
+
+虚拟化与瀑布流各自的硬需求撞在一起：
+
+| | 硬需求 |
+| --- | --- |
+| 虚拟列表 | **不渲染**也要知道每项的位置与总高（撑滚动条、算视口渲染谁） |
+| 瀑布流 | 第 N 张的 y = 它所在列的**累计高度** ⇒ 取决于前面所有卡的高度 |
+
+⇒ 循环是「要装箱就得知道高度 → 要虚拟化就不能渲染 → 不渲染就量不到高度」。
+**这个循环能打破，只要高度是【算出来】的而不是【量出来】的**
+（masonic / Pinterest 走的都是这条）。
+`DataGridView` 是通用容器、不知道你插槽里塞了什么 ⇒ 这个「算」只能由**你**提供。
+
+⚠️ 早期文档说两者「天然冲突」，那个措辞**偏强了** ——
+准确说法是**需要「高度可预先计算」这一前提**。
+
+### 同开同关，[MUST NOT] 半开
+
+`masonry` 与 `estimateItemHeight` **两者都给**才生效；只给其一 ⇒ **保持等高行**
+（与本能力引入前逐字一致）。
+
+🔴 `gridColumns` 取 **`{ min }` 流体档时恒不生效** —— 那条的列数是浏览器算的、
+JS 拿不到，而装箱必须先知道列数。用**断点表**或**定列数**。
+
+### `columnWidth` 由组件回传
+
+`estimateItemHeight(row, columnWidth)` 的第二参是组件算好的**列宽**
+（`(容器内容宽 − (列数−1) × 间距) / 列数`）。
+🔴 断点解析在组件内部，**你算不出来** ⇒ [MUST NOT] 自己去猜容器宽。
+
+### 估不准会怎样（[MUST] 知情）
+
+估值只是**起点**：**渲染到的项会被量准**并替换掉估值
+（virtual-core 的 `measureElement` → `itemSizeCache`）⇒ **不会长期留白**。
+
+| | |
+| --- | --- |
+| ✅ 卡片**不会**在量准后跳到另一列 | 列归属按估值定下来就缓存住（`laneAssignmentMode: "estimate"`）——换列比一点留白刺眼得多 |
+| ⚠️ 视口**下方**未渲染项的位置会轻微浮动 | 上方项被量准后，同列后续项的 y 跟着微调。这是「估算 + 校准」的**固有代价**，[MUST NOT] 期待零跳动 |
+
+⚠️ **最容易估偏的不是图、是文字区**（标题 1～3 行浮动）——
+消费方实测栽过：估值偏大 ⇒ 每张卡底下多一截空白。
+封面给 `aspect-ratio` 能让图那部分在加载前就定高，文字区按**最常见行数**估即可。
+
+### 顺序仍是**行优先**
+
+前 N 项（N = 列数）按 `i % N` 铺满第一行 ⇒ 第 1、2、3 条就在第一行；
+之后每项落**当前最矮的那一列**。
+🔴 [MUST NOT] 期待 CSS `columns` 那种**竖向填充**（1,2,3 落第一列）——
+按时间 / 热度排序的列表会被打乱。
+
+### 与 `DataListView` 的瀑布流是两套机制
+
+| | `DataGridView`（本组件，滚动路径） | `DataListView`（分页路径） |
+| --- | --- | --- |
+| 虚拟化 | **有** | 无 |
+| 高度从哪来 | **消费方算**（`estimateItemHeight`）+ 渲染后校准 | **直接量**（RO 量卡片实际高） |
+| 消费方额外输入 | 需要 | **零** |
+
+⇒ 数据量不大、走分页就够的场景用 `DataListView` 更省事；
+要「上拉加载 + 瀑布流」两者兼得才用本条。
+
 ## 反模式 / 注意
 
+- **只给 `masonry` 不给 `estimateItemHeight`**：[MUST NOT] 指望它半开 —— 虚拟化路径缺了「不渲染也知道多高」这个前提就装不了箱，会保持等高行
+- **`gridColumns` 用 `{ min }` 流体档 + 瀑布流**：[MUST NOT]——流体档的列数是浏览器算的、JS 拿不到，装箱必须先知道列数
+- **在 `estimateItemHeight` 里自己猜容器宽**：[MUST NOT]——`columnWidth` 由组件回传，猜的必然与断点解析脱钩
+- **期待瀑布流零跳动**：[MUST NOT]——视口下方未渲染项会随上方项被量准而轻微浮动，这是「估算 + 校准」的固有代价（换来的是不会长期留白）
+
 - **非分页形态**：[MUST NOT] 期待分页器 / 页码跳转；数据到底即停，无"下一页"按钮
 - **批次固定**：`pageSizeInit` 运行期不改；`pageSizeChange` 不触发
 - **`currentPage` 语义**：`pageInfoChange` 的 `currentPage` = 已拉最大页，消费方勿当"当前展示第几页"

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

@@ -100,8 +100,11 @@ DOM 层级恒定 ⇒ 消费方写的 `:deep()` 选择器不会随 prop 变；瀑
 
 - **需要 JS ⇒ 默认关**（规则：需要 JS 就默认不开）。
 - 与 `gridColumns` 的 `{ min }` / 断点表都能叠。
-- `DataGridView` **不提供**本能力：它的虚拟化按列数 chunk 成**等高行**，而瀑布流要求
-  卡片不等高、跨行装箱，两者天然冲突。分页路径没有虚拟化，是它更自然的落点。
+- **与 `DataGridView` 的瀑布流是两套机制**（都提供，但前提不同）：
+  本条（分页路径）**没有虚拟化** ⇒ 可以**直接量**卡片实际高，消费方零额外输入；
+  `DataGridView`（滚动路径）是虚拟化的 ⇒ 必须**先算**，故要消费方给 `estimateItemHeight`。
+  ⚠️ 两者**不是「一个能一个不能」** —— 早期文档说「天然冲突」措辞偏强，
+  准确说法是后者**需要「高度可预先计算」这一前提**。
 - 量不到高度时每项退**兜底跨度**（CSS 给的），表现为「不够好看」而**不会重叠**——
   增强失败 [MUST NOT] 变成布局坏掉。
 

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

@@ -46,11 +46,13 @@ bridge.badge.set("/order/list", { kind: "new" });
 
 | 内置标 | 宽 | 逃逸 | 后果 |
 | --- | --- | --- | --- |
-| 新 | 26px | 13px | 落在间距里 |
-| 更新 / 内测 | 38px | 25px | 压进邻居 padding，**不压邻居文字** |
-| ~~开发中（3 字）~~ | ~~50px~~ | ~~37px~~ | ~~右缘顶到下一个按钮~~ → 已改「开发」 |
+| 新上线（3 字） | 50px | 37px | 右缘可能顶到水平相邻宿主 |
+| 已更新 / 内测中（3 字） | 50px | 37px | 同上 |
+| 开发中 / 规划中 / 待下线 / 未开通（3 字） | 50px | 37px | 同上 |
 
-**故内置标文案 [MUST] ≤ 2 个汉字。** 逃逸量最终由消费方的布局间距决定，core [MUST NOT] 声称能保证零重叠；`custom` 传长文本的后果由消费方自负。
+⚠️ **原「内置标文案 [MUST] ≤2 个汉字」那条约束已作废**（甲方 2026-09-19 明示「不用关心太长」）。
+逃逸量最终由消费方的布局间距决定，core [MUST NOT] 声称能保证零重叠；文案长度的后果由布局承担。
+[MUST NOT] 因为这张表回推「所以该用图标 / 该截断」—— 见下文「内置档一律文字」。
 
 ### 尺寸：固定 12px / 18px，不随 density 变
 
@@ -64,7 +66,7 @@ bridge.badge.set("/order/list", { kind: "new" });
 
 ⚠️ **不随主题 density 缩放**：core 的 `THEME_FIELD_SPECS` 只往 `:root` 挂变量且未映射任何 badge 变量，故 density 档（compact / cozy / comfortable）不改角标尺寸。这是刻意的——角标应恒为全局最小号，跟着 density 缩放可能小到不可读。消费方要改自行覆盖 `--el-badge-font-size` / `--el-badge-size`。
 
-### ⚠️ 换英文**不能**减宽（已实测，[MUST NOT] 再试）
+### ⚠️ 换英文**不能**减宽（已实测，[MUST NOT] 再试；本节留作依据备查）
 
 12px 字号 + pill 内 padding 实测：
 
@@ -75,7 +77,9 @@ bridge.badge.set("/order/list", { kind: "new" });
 | 内测 | 38 | BETA | 45 | **+7** |
 | 开发中 | 50 | WIP | 36 | −14 |
 
-汉字在小字号下表意密度远高于大写字母——除「开发中→WIP」外全部变宽。压宽度的正确手段是**减字数**，不是换语种。
+汉字在小字号下表意密度远高于大写字母——除「开发中→WIP」外全部变宽。
+⚠️ 原结论「压宽度的正确手段是减字数」**已不再适用**（甲方明示不用关心太长）；
+本节只保留一条仍然有效的结论：**[MUST NOT] 为「更短」而把内置文案改成英文**。
 
 ## API
 
@@ -102,53 +106,108 @@ bridge.badge.set("/order/list", { kind: "new" });
 
 文案与语义色由 core 统一定（跨 app 一致）；语义档解析到 `--el-color-*`，**主题风格 / 亮暗切换自动跟随**（规则 14，[MUST NOT] 写死色值）。
 
-| kind | 气泡文案 | 图标（轮廓原型） | 语义色 | 为什么 |
+| kind | 文案 | 语义色 | 为什么 |
+| --- | --- | --- | --- |
+| `count` | **数字** | `danger` 红 | 待办数量要人行动，未读红点是全行业最强共识 |
+| `new` | 新上线 | `success` 绿 | 正面资讯。[MUST NOT] 复用红——会与 `count` 撞色 |
+| `updated` | 已更新 | `primary` 主色 | 中性被动通知，不喧宾夺主 |
+| `beta` | 内测中 | `warning` 橙 | 能用但不稳定需谨慎 |
+| `wip` | 开发中 | `info` 灰 | 尚不完善，中性、不引导点击。**仅提示，不拦点击** |
+| `planned` | 规划中 | `info` 灰 | 还没开工，比 `wip` 更靠前。**不进遮挡档** |
+| `deprecated` | 待下线 | `danger` 红 | 「要迁走」需要用户采取行动 |
+| `locked` | 未开通 | `warning` 橙 | 权限边界，**唯一拦点击的档**；也是唯一**拒绝隐藏**的档 |
+| `custom` | 自定义文案 | 缺省 `primary` | 内置档不够用时才用；`type` 只收语义档 |
+| `anchor` | —— | —— | **伪标 / 纯锚点**：恒隐藏角标，只留 DOM 挂点供引导等消费方定位 |
+
+### 🔴 内置档**一律文字**，[MUST NOT] 再改图标
+
+甲方 2026-09-19（附菜单实拍图）：**「badge 的图标撤掉，还是直接展示文字，两个字就是两个字、
+三个字就是三个字（不用关心太长）」**。图标态在真实菜单里是一排看不懂的小圈。
+
+**原「≤2 汉字」的宽度约束随之作废** —— 它当初的依据是「三字宽 50px、逃逸 36px 会压到水平
+相邻宿主」，而甲方**明确说不用关心太长**。⇒ 实施方 [MUST NOT] 拿那条依据回推「所以还是该用
+图标」，也 [MUST NOT] 自行折中（截断 / 省略号 / tooltip 代文字）—— 那是用没被授权的方案
+绕过已下达的决定。逃逸的代价由消费方的布局间距承担，core 照旧不声称能保证零重叠。
+
+⚠️ 这**不是「把 v0.30 revert 掉」**：状态四档（`wip` / `planned` / `deprecated` / `locked`）
+在 ≤v0.29 时本来就是图标，本次是它们**首次**以文字出现。三档是新的一致态：
+
+| 版本 | 资讯三档 `new`/`updated`/`beta` | 状态四档 `wip`/`planned`/`deprecated`/`locked` |
+| --- | --- | --- |
+| ≤ v0.29 | 文字 | 图标 |
+| v0.30 | 图标 | 图标 |
+| **本版** | **文字** | **文字** |
+
+图标是**全族退场**：`ElIcon` / `ElTooltip` / 预设的 `icon` 与 `iconScale` 字段一并删除。
+悬浮气泡随之去掉 —— 它当初存在只为「语义随文字消失后补回来」，文字回来了它就是重复。
+
+## 展示开关：逐条 `visible` + 全局默认
+
+徽标当初是拿来做新手引导的；有了 `forge-plugin-guide` 之后，**徽标不再必须显示**。
+
+| 层 | 写法 | 默认 |
+| --- | --- | --- |
+| 逐条 | `bridge.badge.set(key, { kind: "new", visible: false })` | `undefined` = 跟随全局 |
+| 全局 | `createCoreBridge({ badge: { defaultVisible: false } })` 或 `bridge.badge.setDefaultVisible(false)` | **`true`（展示）** |
+
+**逐条显式值恒优先于全局默认**（与本仓所有 config-hook 同口径）。
+全局默认取 `true` 是为了不改变现有下游观感；把它关成不展示是消费方的选择。
+
+### 🔴 「配置了但不展示」与「没配置」是两回事
+
+| | 注册表 | DOM | `data-dc-badge-key` | 引导能否定位 |
 | --- | --- | --- | --- | --- |
-| `count` | —— | **数字**（唯一非图标档） | `danger` 红 | 待办数量要人行动，未读红点是全行业最强共识 |
-| `new` | 新上线 | `Sunny`（中心圆 + 放射，**团**） | `success` 绿 | 正面资讯。[MUST NOT] 复用红——会与 `count` 撞色 |
-| `updated` | 已更新 | `RefreshRight`（闭合**环** + 箭头） | `primary` 主色 | 中性被动通知，不喧宾夺主 |
-| `beta` | 内测中 | `Opportunity`（钟形**灯泡**） | `warning` 橙 | 能用但不稳定需谨慎 |
-| `wip` | 开发中 | `MoonNight`（**月牙**，`iconScale` 0.8） | `info` 灰 | 尚不完善，中性、不引导点击。**仅提示，不拦点击** |
-| `planned` | 规划中 | `Calendar`（**方框 + 两耳**） | `info` 灰 | 还没开工，比 `wip` 更靠前。**不进遮挡档** |
-| `deprecated` | 待下线 | `Warning`（**三角**） | `danger` 红 | 「要迁走」需要用户采取行动 |
-| `locked` | 未开通 | `Lock`（**拱 + 方体**） | `warning` 橙 | 权限边界，**唯一拦点击的档** |
-| `custom` | —— | 自定义文案 | 缺省 `primary` | 内置档不够用时才用；`type` 只收语义档 |
-| `anchor` | —— | —— | —— | **伪标 / 纯锚点**：不渲染角标，只留 DOM 挂点供引导等消费方定位 |
+| **没配置** | 无 entry | 渲染**裸插槽**（无 `ElBadge`） | ❌ 无 | ❌ |
+| **配置了但不展示** | 有 entry | 渲染 `ElBadge`，角标被藏 | ✅ 在 | ✅ |
 
-### 🔴 内置档**一律图标 + 悬浮气泡**（新增 kind 前先读这条）
+⇒ 隐藏 [MUST NOT] 用 `v-if` 掉整个 `ElBadge` —— 那会连挂点一起没掉，
+`forge-plugin-guide` 当场失去锚点。**把徽标全部设为不展示时，引导仍能正常串出并定位。**
 
-依据是**角标逃逸量**：绝对定位下逃逸 = 角标宽 − 13px。文字档三字词宽 ≈50px、逃逸 36px
-**会压到水平相邻的宿主**（实测右缘顶到下一个按钮）；图标档角标宽 ≈24px、逃逸 ≈11px，
-只压进邻居的 padding。资讯三档当初留文字是**容忍**（2 字逃逸 24px 在安全线内）不是偏好 ⇒
-v6odvs 起一并图标化，更安全。
+### 藏法 = 0 尺寸 + `overflow:hidden` + 事件屏蔽（甲方裁定）
+
+```less
+width: 0; height: 0; min-width: 0; padding: 0; border-width: 0;
+overflow: hidden; pointer-events: none;
+```
 
-**代价 [MUST] 知情**：三档从「扫一眼就懂」退成「要悬浮才懂」——
-故 `label` 气泡 [MUST NOT] 省，语义不能随文字一起消失。
+文字仍在 DOM 里但被裁掉，故 [MUST] 同时给 `aria-hidden="true"`（0 尺寸只是**视觉**裁掉，
+读屏照念）。
 
-#### 选图标的第一判据是**轮廓原型**，不是像不像
+🔴 **[MUST NOT] 用 `display: none`，也 [MUST NOT] 沿用 `ElBadge` 的 `hidden` prop**
+（它内部就是把 sup 从布局里摘掉）。理由**不是**「保住锚点」—— 那是错的因果：
+`data-dc-badge-key` 挂在 `ElBadge` **根元素**（包着宿主内容的 wrapper，有真实尺寸）上，
+不是那个十几 px 的 pill，两种藏法都不断锚。
 
-镂空态下图标是语义色线条，**没有面、没有色差**可借 ⇒ 区分度只剩形状；12px 的尺度下笔画
-细节根本不成立。⇒ 七档 [MUST] 落在**七个不同的轮廓原型**上（团 / 环 / 灯泡 / 月牙 /
-方框耳 / 三角 / 拱方），[MUST] 并排截图看，[MUST NOT] 只看单档。
+**真正的理由是「仍然占位可测」**：`display:none` 的元素 `getClientRects().length === 0`，
+而这正是 `plugin-guide/src/anchor.ts` 的可见性判据（以及 `kq2m8w` 引导整页卡死 P0 的成因）
+所依赖的那条线。保持「0 尺寸但仍在布局里」，可以让**任何**按 rect 判可见性的下游逻辑
+不被隐藏态坑到。
 
-两处刻意避开的撞车，[MUST NOT] 改回去：
-- `new` **不取 `Star`** —— `wip` 的 `MoonNight` 自带小星星，12px 下会互相干扰；
-- `beta` **不取 `Aim`（靶心）** —— 同心圆与 `Sunny` 同属「圆团」，七档里会出现两个团。
+### 🔴 遮挡档（`locked`）**拒绝隐藏**
 
-#### `iconScale`（预设里的**逐档**字段）
+`BADGE_MASK_KINDS`（现仅 `locked`）**不接受隐藏**：逐条 `visible: false` 对它无效，
+全局默认的「不展示」也不作用到它；dev 下会 `console.warn` 一句（静默忽略 = 消费方
+以为设了其实没设）。
 
-`MoonNight` 视觉重量比其余档满 ⇒ 取 `0.8`。走 `font-size`（`ElIcon` 尺寸本就是 `1em`，
-缩字号即等比缩，且不动角标盒的布局尺寸）。
-🔴 [MUST NOT] 提成全局常量或只给某一档打补丁 —— 全图标化之后后续还会有别的档要同样处理。
+依据：**遮挡是功能不是资讯**。藏了会落进两种更坏的形态之一 ——
+「隐藏了但仍然挡」⇒ 用户看到一个点不动又没有任何说明的按钮；
+「隐藏了就不挡」⇒ 未开通的功能变成可点，功能性回退。
 
 ### `anchor`：只要挂点、不要角标
 
 想给某个菜单项 / 按钮做新手引导，但它本身没有「新 / 更新」之类的标要显示时用它。
 [MUST NOT] 为此硬挂一个 `new` —— 那会在界面上多出一个用户看不懂的角标。
 
-🔴 实现上走 `ElBadge` 的 `hidden`（藏角标、留挂点），**[MUST NOT] 改成「不渲染」**：
-本组件是 `v-if="resolved"`，不渲染会连 `data-dc-badge-key` 一起没掉，
-消费方反而**定位不到**，与这档的用途正好相反。
+**与 `visible: false` 的关系（[MUST] 按此口径，[MUST NOT] 留两套说法）：两者都保留，语义不同。**
+
+| | 语义 | 藏法 |
+| --- | --- | --- |
+| `kind: "anchor"` | 「这里**本来就没有标**」—— `kind` 无资讯语义 + 恒隐藏 | 同一套 |
+| `visible: false` | 「**有标**（new / beta / …），只是此刻不显示」 | 同一套 |
+
+⇒ `anchor` **不是**新开关的语法糖：它已是发布契约，且语义是「无标」而非「有标先不显示」。
+两者**共用同一套藏法**（0 尺寸 + `overflow:hidden` + 事件屏蔽），
+[MUST NOT] 让它继续走 `ElBadge` 的 `hidden` —— 那就是「两种隐藏机制」。
 
 ## 遮挡：只有 `locked` 一档拦点击
 
@@ -169,16 +228,18 @@ v6odvs 起一并图标化，更安全。
 - **包纯文字却用默认 `corner`**：角标会悬在文字上方并溢出相邻行
 - **指望它做聚合**：本组件只按 key 查表渲染，core [MUST NOT] 把子级的标上卷到父级；聚合由 app 自算后往父级 key 写 entry
 - **以为角标是实心底白字**：**已改镂空**（见下节）。旧描述作废，[MUST NOT] 照旧假设
+- **以为内置档是图标 + 气泡**：v0.30 那一版的形态，**本版已全档改回文字**，气泡随之去掉
+- **拿 `v-if` 藏徽标**：会连 `data-dc-badge-key` 挂点一起没掉，引导插件当场定位不到；隐藏一律走 `visible`
+- **给 `locked` 配 `visible: false`**：**无效**（遮挡是功能不是资讯），dev 下有 `console.warn`
 
 ## 镂空（outline）观感
 
-角标走**镂空**：浅底 + 语义色 1px 边框 + 语义色文字 / 图标（原先是语义色实心底 + 白字）。
+角标走**镂空**：浅底 + 语义色 1px 边框 + 语义色文字（原先是语义色实心底 + 白字）。
 
 - 落点在 `use-theme-apply` 的 `EP_STRUCTURAL_CSS`（与其余 EP 结构性修正同源）——
   角标由 `ElBadge` 渲染在它自己的 DOM 上，[MUST NOT] 在 `BadgeMark.vue` 写 scoped（打不中）。
 - 颜色全走 `--el-color-<档>` / `--dc-core-*` 双源（规则 14），[MUST NOT] 写死。
 - **底不是纯透明**：角标叠在宿主内容上，全透会透出下面的字 ⇒ 用 `--el-bg-color`（面色）打底。
-- 图标档随之从白色变**语义色线条**（`currentColor`）。
 
 要退回实心：在消费方侧覆盖 `.el-badge__content`（`background-color` / `color` / `border`）。
 [MUST NOT] 指望有 prop 开关 —— 观感是全局一致口径，不做成逐处可调。
@@ -186,5 +247,5 @@ v6odvs 起一并图标化，更安全。
 ## 关联
 
 - 数据真源：`bridge.badge`（`bridge/badge.ts`）
-- 内部 hook：`use-badge`（同级、不出桶；查表 + `expireAt` 判定 + 全 app 共享 tick）
+- 内部 hook：`use-badge`（同级、不出桶；查表 + `expireAt` 判定 + 展示开关解析 + 全 app 共享 tick）
 - 已接入的生产驱动点：`MenuTree` / `MenuItemSub` / `AppHeader` 模块条 / `ActionBtn`

package/src/components/form/README.md

@@ -20,6 +20,20 @@
 - [FormUploadAudio](./docs/README-FormUploadAudio.md) — 音频上传（薄封装：accept audio/* + 内联 `<audio controls>` 播放条即时试听；**不建弹窗**——业界音频无 lightbox 形态）
 - FormRadioGroup / FormTree / FormVerifyImage / FormVerifyCode — 文档待补
 
+## 表单项内容的宽度约定（族级硬约定）
+
+EP 的 `.el-form-item__content` 是 **flex 容器**（`display:flex; flex-wrap:wrap; flex:1; align-items:center; min-width:0`）。
+⇒ **凡要当表单项内容渲染的组件，其根盒 [MUST] 显式声明宽度行为**，
+[MUST NOT] 依赖「块级元素会自己撑满」——**那条规则在 flex 容器里不成立**，
+根盒会按 `flex:0 1 auto` 收缩到内容宽。
+
+- 想占整行 → 根盒 `width:100%` + **`min-width:0`**（flex item 的 `min-width` 默认 `auto`，长文本 / 宽表格会把它顶出容器，两条 [MUST] 成对给）
+- 想按内容宽（chip / 按钮组 / 单选组）→ 显式 `display:inline-flex` 之类，**也算声明**
+- 本族现状：`FormItemNestForm` / `FormItemNestFormList` / `FormUpload` / `FormGroupTitle` / `FormTree` 走 `width:100%`；
+  `FormRadioGroup`（EP `inline-flex`）、`FormSortSwitch(Group)` 按内容宽；`FormInput` / `FormSelect` / `FormDivider` 由 EP 自带 `width:100%`
+- ⚠️ **内容宽的地方坏了也看不出来**：一行里只要有个 `el-input`，收缩的根盒照样撑满——
+  自查 / 守卫 [MUST] 用**窄内容**样例（如 148px 方卡）
+
 ## 跨族依赖
 
 - form 族 → display 族（单向）：`FormSort` 依赖 `ShadowClone`（分身机制）、`FormActiveFilter` 依赖 `ActionBtn`（清除全部按钮）

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

@@ -75,6 +75,9 @@ const data = ref(generateFormData(list));
 
 ## 反模式 / 注意
 
+- **根盒恒占整行**（`width:100%` + `min-width:0`）：它落在 EP 的 `.el-form-item__content` flex 容器里，不显式给宽会收缩到内容宽 —— 行内只有窄内容（如 148px 方卡）时右边会留一大片空白。[MUST NOT] 在消费方用 `wrapProps` 补 `width:100%`（已由组件自带）
+
+
 - **手写嵌套子表单配置**：直接手写 render 挂子 FormMain 会绕过注册机制，级联校验断裂——[MUST] 用 `nestFormItem` / 本组件
 - **nestKey 与父 key 不一致**：nestKey 是父 item key，注册索引对不上则级联失效
 - **shadowColor 显式传才内联覆盖**：默认零投影（去框化，层级靠背景明度差）；除非确需跨主题固定投影，别传

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

@@ -86,6 +86,9 @@ const data = ref(generateFormData(list));
 
 ## 反模式 / 注意
 
+- **根盒恒占整行**（`width:100%` + `min-width:0`）：它落在 EP 的 `.el-form-item__content` flex 容器里，不显式给宽会收缩到内容宽 —— 行内只有窄内容（如 148px 方卡）时右边会留一大片空白。[MUST NOT] 在消费方用 `wrapProps` 补 `width:100%`（已由组件自带）
+
+
 - **手写行子表单配置**：绕过注册机制则多行级联校验断裂——[MUST] 用 `nestFormItemList` / 本组件
 - **只靠 min / max 交互约束**：禁删 / 禁新增是交互层防线，长度硬校验走父 item `rules`——需要提交时兜底校验（如绕过 UI 直接改数据）必须配 `rules`
 - **headerRender / footerRender 是 render-fn 不是 slot**：在配置内以函数形式提供，不能当插槽模板使用

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

@@ -169,6 +169,9 @@ EP 以 `uid` 作 key ⇒ **重复 key**、列表渲染紊乱（实测 DOM 闪出
 
 ## 反模式 / 注意
 
+- **根盒恒占整行**（`width:100%` + `min-width:0`）：作 `.el-form-item__content` 的 flex item，不显式给宽会收缩到内容宽 —— picture-card 形态下卡片网格的可用宽会随卡片数变化、拖拽区也跟着缩
+
+
 - **值 = URL 不是 File**：`modelValue` 语义是「已上传文件的 URL」——外部塞 File 对象进值是错误用法（表单 stringify 提交的是 URL）；上传动作经 `uploadFn` 发生
 - **`loadingKey` 不传则上传中不拦提交**：裸用可接受（无 FormMain 环境）；FormMain 配置化场景忘传 = 上传中能提交（半成品 URL 进库）——配置时 [MUST] 传
 - **进度不自造**：ElUpload 内置进度条（on-progress → percent → 自动显示）——「把 onprogress 数据传给 getProgress 方法」是自造轮子；只有自定义进度呈现才需要自己拿 `event.percent`

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

@@ -83,6 +83,30 @@ AppLayout 在调用内置 app 级 ModalShelf 的**子元素最前**位置调用
 
 架子把 `{show, closeFn, removeFn, payload: P}` 注入弹窗组件（见 ModalShelf 文档）。
 
+### 放进 `AppPage` 方位槽 ⇒ 挂载时一条指名道姓的 `console.error`
+
+`AppPage` 的 `#top` / `#bottom` / `#left` / `#right` 是**方位槽**（fixed 悬浮区），
+它们是页面内置 `ModalShelf` 的**兄弟节点**而不是后代 ⇒ `provide` 够不到，
+`evoke()` 恒返回 `null`（表现为「点按钮毫无反应」，不报错也不崩）。
+
+Porter 挂载时读直系父的 `data-dc-slot`，命中方位槽即报：
+
+```
+[ModalPorter] 它被放在 AppPage 的 #top 槽里 —— 方位槽是 ModalShelf 的兄弟节点，
+provide 够不到，evoke() 恒为 null（表现为「点按钮毫无反应」，不报错不崩）。
+[MUST] 移到**默认槽**（page 架子就住在默认槽里；与 AppPage 并列同样够不到）。
+Porter 自身零 DOM 输出，放默认槽里不占任何版面。
+```
+
+- **方位槽里放 Porter 没有任何正当用法** ⇒ 这条恒报（不限 dev），且零误报
+- 默认槽 / 脱离 `AppPage` 单用 ⇒ **零输出**
+- 🔴 出口是**默认槽**，[MUST NOT] 顺手改成「与 `AppPage` 并列」—— page 架子
+  （`ModalShelf level="page"`）就住在 AppPage 的默认槽里，并列**同样够不到**，
+  `evoke()` 一样恒为 null。「与 AppPage 并列」只对**不需要 page 架子**的东西成立
+  （声明式挂载、自己 teleport 走的弹窗组件）
+- 「弹窗经弹层挂载、不占版面 ⇒ 放哪都行」是**只对了一半**的推理：弹窗自身 teleport 走了，
+  但**槽本身**照样渲染（fixed + padding + 背景），白占一条高度 —— 见 `AppPage` 文档的空壳槽检测
+
 ## 反模式 / 注意
 
 - **未注册 key 是静默失败面**：`evoke` 返回 null + console.error——消费侧 [MUST] 判空（`evoke(...)?.close()` 或先判 null），别假设一定成功
@@ -90,6 +114,8 @@ AppLayout 在调用内置 app 级 ModalShelf 的**子元素最前**位置调用
 - **key 类型必须声明合并**：evoke 的 key 泛型约束 `keyof ModalShelfMap`——业务 [MUST] 在 `.d.ts` 里 declare module 扩展 `ModalShelfMap`（见 ModalShelf 文档），否则 key 不在 map 上 TS 直接拦截
 - **自动清理别补偿**：Porter 失活/卸载已自动 remove 全部 nsKey，手写 `onUnmounted` 清理是重复劳动（也可能提前清掉活跃弹窗）
 - **页面级 Porter [MUST NOT] 配 `shelf:"app"` 条目**：页面卸载后弹窗仍挂在常驻 app 架子上 → 孤儿弹窗（唤起句柄已死、只剩弹窗自身 closeFn）；app 级弹窗唯一正道 = AppLayout `globalModalConfig` + 内部专用 Porter + `globalModalRemote` 遥控
+- **[MUST NOT] 把 Porter 放进 `AppPage` 的 `#top`/`#bottom`/`#left`/`#right`**：方位槽够不到 page 架子（`evoke()` 恒 null），且槽本身白占版面；挂载时会有一条点名报错。出口是**默认槽**（Porter 零 DOM 输出，放那里不占任何版面）——
+  [MUST NOT] 改成「与 `AppPage` 并列」，page 架子就在默认槽里、并列同样够不到
 - **弹窗 UI 不在 Porter 插槽里写**：Porter 只是注册表宿主，弹窗经 evoke 落在架子上渲染——插槽只放页面内容
 
 ## 关联

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

@@ -99,7 +99,7 @@ watch(isOutOfSync, (v) => v && refreshList());
 | ----------------- | ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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 —— 侧边栏折叠会改内容区可用宽                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `listWidth`       | `string`                                                     | `clamp(280px, 28%, 420px)` | 分栏态列表列宽。**落在 `AppPage` 的 `#left` 槽上**（不是列表盒）⇒ 百分比按**视口**解析、基数稳定不循环。定值 / 百分比 / clamp 三种写法都不产生死白（实测死白恒 = shim padding）。[MUST NOT] 把它搬回列表盒 —— 槽是 shrink-to-fit，百分比在那一层没有基数（vr8kd2） |
 | `autoActiveFirst` | `boolean`                                                    | 跟随形态                   | 列表出数后自动激活第一条。**split 默认 `true`**（宽屏右半屏不该空着）、**sheet 默认 `false`**（窄屏自动弹抽屉是打扰）。⚠️ 详情若有副作用（如「打开即标记已读」）[MUST] 显式关掉                                                                                                                                                                                                                                                                                                             |
 | `queryKey`        | `string`                                                     | 无                         | 传了才把 `activeId` 同步进 URL query（**`replace` 不 `push`**）。复原仍走不变式校验                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `detailApi`       | `(params?: { id }) => Promise<R>`                            | 无                         | 传了则内置 `ViewLayout`（零配置拿到内置导航 + `refreshToken` 接线）；不传则 `#detail` 原样渲染、门面零请求                                                                                                                                                                                                                                                                                                                                                                                  |