@done-coding/admin-core 0.27.1-alpha.0 → 0.28.1-alpha.0

package/types/components/display/BadgeMark.vue.d.ts

@@ -1,10 +1,13 @@
 import { ComponentPublicInstance } from 'vue';
+import { BadgeKeyInput } from './use-badge';
 type __VLS_Props = {
     /**
      * 徽标键；命中 `bridge.badge` 注册表且未过期才渲染角标。
-     * 菜单侧传路由 `path`，`ActionBtn` 侧传显式 `badgeKey`。
+     *
+     * 也可传**候选列表**（依次查、先命中先用）：菜单侧传 `[路由 name, 路由 path]`
+     * 即 **name 优先、path 兜底**；`ActionBtn` 侧传业务自己的 `badgeKey`。
      */
-    badgeKey?: string;
+    badgeKey?: BadgeKeyInput;
     /**
      * 角标垂直锚点（两档均为**绝对定位**——[MUST] 保证角标的出现不改变宿主尺寸）：
      * - `"corner"` ＝ 右上角（EP 原生骑角，角标中心钉在**被包内容盒的顶边**）。

package/types/components/display/use-badge.d.ts

@@ -1,6 +1,29 @@
 import { ComputedRef, Component } from 'vue';
 import { BadgeProps } from 'element-plus';
 import { BadgeEntry } from '../../bridge';
+/**
+ * 徽标 key 入参 —— 单个 key，或**候选列表**（依次查、先命中先用）。
+ *
+ * 候选列表是为菜单准备的：菜单项同时有路由 `name` 与 `path`，传 `[name, path]` 即
+ * **name 优先、path 兜底**。留 path 兜底有两个理由：ⓐ vue-router 里 `name` 是可选的，
+ * 没配 name 的路由拿不到 key 就直接挂不上标；ⓑ 让「支持 name」这件事天然 additive ——
+ * 现有以 path 注册的一行都不用动。
+ *
+ * ⚠️ 数组里允许 `undefined`（`[menu.name, menu.path]` 的 name 可能没有），
+ * 查表时跳过，[MUST NOT] 让调用方先自己过滤。
+ */
+export type BadgeKeyInput = string | readonly (string | undefined)[] | undefined;
+/** 命中结果：**真正命中的那个 key** + 标本身 */
+export interface BadgeHit {
+    /**
+     * 命中的 key（候选列表时 = 先命中的那个）。
+     *
+     * 🔴 它是 `BadgeMark` 回写 `data-dc-badge-key` 的值，也就是外部（引导插件）
+     * 拿来 `querySelector` 的那个 —— [MUST NOT] 回写候选列表本身，那对不上。
+     */
+    key: string;
+    entry: BadgeEntry;
+}
 /** 徽标解析结果——已过滤过期项，直接可渲染 */
 export interface BadgeResolved {
     /** ElBadge value（数量标为数字，其余为文案） */
@@ -13,19 +36,29 @@ export interface BadgeResolved {
     icon?: Component;
     /** 完整文案——图标档的悬浮气泡用它把语义补回来 */
     label?: string;
+    /**
+     * 纯锚点档（`kind: "anchor"`）：角标**不显示**，但 DOM 挂点照常渲染。
+     *
+     * 🔴 [MUST NOT] 改成「返回 undefined 让它不渲染」—— `BadgeMark` 是 `v-if="resolved"`，
+     * 不渲染会连 `data-dc-badge-key` 一起没掉，消费方（guide）反而**定位不到**，
+     * 与本档的用途正好相反。故走 `ElBadge` 的 `hidden`：藏角标、留挂点。
+     */
+    hidden?: boolean;
 }
 /**
- * 按 key 解析出可渲染的徽标；无 key / 未 `app.use(bridge)` / 未命中 / 已过期 → `undefined`。
+ * 按 key（或候选列表）查 `bridge.badge` 注册表，返回**命中的 key + 标本身**。
+ *
+ * 🔴 **展示与遮挡共用这一条读表路径**：`BadgeMark` 拿它的 `entry` 渲染角标，
+ * `use-badge-mask` 拿同一个 `entry` 判 `kind` / 取 `onTrigger`。
+ * [MUST NOT] 为某一路另写一份查表 —— 两份会漂移成「标出来了却不挡」这种
+ * 比不显示更坏的半吊子状态。
  *
  * bridge 经 `CORE_BRIDGE_KEY`（app 级整实例）而非 `APP_LAYOUT_BRIDGE_KEY`（layout 窄切片）——
  * `ActionBtn` 可用在 AppLayout 之外的任何地方。**opt-in**：未 `app.use(bridge)` 时静默不显，
  * [MUST NOT] 抛错。
  */
+export declare function useBadgeHit(getKey: () => BadgeKeyInput): ComputedRef<BadgeHit | undefined>;
 /**
- * 按 key 取**原始标条目**（未命中 / 已过期 → `undefined`）。
- *
- * 与 {@link useBadgeResolved} 的分工：后者产「可渲染的展示数据」，本函数产「标本身」——
- * 遮挡功能要读 `kind` 判是否该挡、读 `onTrigger` 决定点击归宿，那些不是展示数据。
+ * 标 → 可渲染展示数据。纯函数（不碰 bridge / 不建响应式依赖），查表归 {@link useBadgeHit}。
  */
-export declare function useBadgeEntry(getKey: () => string | undefined): ComputedRef<BadgeEntry | undefined>;
-export declare function useBadgeResolved(getKey: () => string | undefined): ComputedRef<BadgeResolved | undefined>;
+export declare function badgeResolveDisplay(entry: BadgeEntry | undefined): BadgeResolved | undefined;

package/types/config/badge-attr.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 徽标 DOM 契约属性名（跨包共享的单一真源）。
+ *
+ * 与 {@link DC_SLOT_ATTR} 同性质：**运行期 DOM 上的约定**，core 内部消费之外，
+ * 外部包（如引导插件 `forge-plugin-guide`）也要按它 `querySelector` 定位锚点
+ * ⇒ [MUST NOT] 让任何一方硬编码字面量，改名时只该改这一处。
+ */
+/**
+ * 宿主声明属性 —— 调用点打在**可点击的那个元素**上（按钮 / 菜单项 / 模块条 / tile 卡片）。
+ *
+ * 宿主形态因调用点而异，core [MUST NOT] 硬编码一张选择器表去猜（EP 换版即碎），
+ * 故由调用点自报；`BadgeMark` 的遮挡 hook 与外部引导插件都靠向上 `closest` 找它。
+ * **无值属性**（`data-dc-badge-host`），存在即声明。
+ */
+export declare const BADGE_HOST_ATTR = "data-dc-badge-host";
+/**
+ * 徽标键回写属性 —— `BadgeMark` **命中标时**写在角标根元素上，值 = 该标的 key。
+ *
+ * 与 {@link BADGE_HOST_ATTR} 的分工：host 只回答「这是个宿主」，本属性回答
+ * 「**是哪个 key 的**」。外部引导插件据此把 `key → DOM` 打通：
+ * `[data-dc-badge-key="K"]` → `.closest([data-dc-badge-host])`（够不到则用角标自身）。
+ *
+ * 只在有标时存在（与角标同生命周期）——无标时不渲染角标，也就没有可导览的锚点，
+ * 这正是想要的语义，[MUST NOT] 改成「宿主恒挂 key」（会产出一堆指向空标的死锚点）。
+ */
+export declare const BADGE_KEY_ATTR = "data-dc-badge-key";

package/types/config/index.d.ts

@@ -1,3 +1,4 @@
+export * from './badge-attr';
 export * from './list-model';
 export * from './route';
 export * from './slot-region';

package/types/hooks/menus-dispatch.d.ts

@@ -12,6 +12,7 @@ export declare const useMenusDataDispatch: ({ getMenus, getMenuFlatList, getExtr
     headerMenus: import('vue').ComputedRef<{
         children: never[];
         path: string;
+        name?: string;
         title: string;
         routeLevel: number;
         redirectToFirstChildRoute: boolean;

package/types/injectInfo.json.d.ts

@@ -1,6 +1,6 @@
 declare const _default: {
   "name": "@done-coding/admin-core",
-  "version": "0.27.1-alpha.0",
+  "version": "0.28.1-alpha.0",
   "description": "内部前端库"
 };
 

package/types/types/route.d.ts

@@ -79,6 +79,14 @@ export interface GetRoutePermissionParams {
 export interface RouteMetaResolveRaw {
     /** 路由地址 */
     path: string;
+    /**
+     * 路由 `name`（vue-router 里是可选的，且允许 symbol —— 解析期只留 string，其余为 `undefined`）。
+     *
+     * 用途：跨层引用路由的**逻辑标识**。典型消费方是徽标注册表——服务端下发的动态标
+     * （待办数 / 未开通）不该知道前端的 URL 结构，`path` 一改（加前缀 / 挪模块 / 路径国际化）
+     * 那张 key 表就**静默失效**（标不显示而已，不报错）。
+     */
+    name?: string;
     /** 页面名称 */
     title: string;
     /** 路由级别 */

package/types/utils/dom.d.ts

@@ -25,11 +25,17 @@ export declare function domClosestStickyScrollport(el: HTMLElement | null | unde
 /** {@link domScrollIntoViewport} 选项 */
 export interface DomScrollIntoViewportOptions {
     /**
-     * 滚动行为。**默认 `"auto"`（瞬时）**，[MUST NOT] 改默认为 `"smooth"`。
+     * 滚动行为。**默认 `"smooth"`（平滑）**，甲方 2026-09-16 定 ——
+     * 突然跳位会让人丢失「我在哪」，平滑滚动把位移变成可跟随的过程。
      *
-     * 本仓踩过：`TabsTile` 自研 smooth 滚动被 **v-model 回流重渲染打断**
-     * （watcher 里异步读 y 恒 0，真机复现），最终弃用改走 `ElAnchor`。
-     * 「列表项聚焦跟随」属跟随而非导航，瞬时定位反而稳；要动效由调用方显式传。
+     * 🔴 **系统开了「减少动态效果」时自动降级为 `"auto"`**
+     * （`prefers-reduced-motion: reduce`，无障碍惯例）；显式传值恒优先。
+     *
+     * ⚠️ 历史注记：本默认值曾是 `"auto"`，理由是 `TabsTile` 的 **自研** smooth 滚动被
+     * v-model 回流重渲染打断（watcher 里异步读 y 恒 0，真机复现）。那条教训的适用边界是
+     * **自研滚动 + 滚动期间宿主重渲染**，与本函数（原生 `scrollIntoView` 薄封装）不同。
+     * 若将来某个调用点确实在滚动期间重渲染目标，[MUST] 在**该调用点**显式传 `"auto"`，
+     * [MUST NOT] 因个别场景把全局默认改回去。
      */
     behavior?: ScrollBehavior;
     /** 纵向对齐，默认 `"nearest"`（见函数注释） */