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

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

@@ -1,4 +1,4 @@
-import { ComputedRef, Component } from 'vue';
+import { ComputedRef } from 'vue';
 import { BadgeProps } from 'element-plus';
 import { BadgeEntry } from '../../bridge';
 /**
@@ -32,22 +32,20 @@ export interface BadgeResolved {
     max?: number;
     /** ElBadge 语义色档 */
     type: BadgeProps["type"];
-    /** 图标（状态三档走图标而非文字）；有它则 `value` 不渲染、改由 `#content` 出图标 */
-    icon?: Component;
-    /** 完整文案——图标档的悬浮气泡用它把语义补回来 */
-    label?: string;
     /**
-     * 图标缩放（逐档可选，1 = 原尺寸）。
-     * 🔴 [MUST] 留在**预设的逐档字段**里，[MUST NOT] 提成全局常量或只给某一档打补丁 ——
-     * 七档全图标化之后，后续还会有别的档需要同样处理（甲方 2026-09-18 明示）。
-     */
-    iconScale?: number;
-    /**
-     * 纯锚点档（`kind: "anchor"`）：角标**不显示**，但 DOM 挂点照常渲染。
+     * 角标**藏起来**（挂点照常渲染）。两条来路，**同一套藏法**：
+     * ① `kind: "anchor"`（恒隐藏，「本来就没有标」）；
+     * ② `entry.visible === false` 或全局默认关（「有标，只是此刻不显示」）。
      *
      * 🔴 [MUST NOT] 改成「返回 undefined 让它不渲染」—— `BadgeMark` 是 `v-if="resolved"`，
      * 不渲染会连 `data-dc-badge-key` 一起没掉，消费方（guide）反而**定位不到**，
-     * 与本档的用途正好相反。故走 `ElBadge` 的 `hidden`：藏角标、留挂点。
+     * 与隐藏的用途正好相反。
+     *
+     * 🔴 藏法由甲方裁定：**0 尺寸 + `overflow:hidden` + 事件屏蔽**（落点在 `BadgeMark` 的
+     * scoped 样式），[MUST NOT] 用 `display:none`，也 [MUST NOT] 沿用 `ElBadge` 的
+     * `hidden` prop —— 后者内部就是把 sup 从布局里摘掉。理由是**仍然占位可测**：
+     * `display:none` 的元素 `getClientRects().length === 0`，而那正是
+     * `plugin-guide/src/anchor.ts` 的可见性判据所依赖的线。
      */
     hidden?: boolean;
 }
@@ -66,5 +64,15 @@ export interface BadgeResolved {
 export declare function useBadgeHit(getKey: () => BadgeKeyInput): ComputedRef<BadgeHit | undefined>;
 /**
  * 标 → 可渲染展示数据。纯函数（不碰 bridge / 不建响应式依赖），查表归 {@link useBadgeHit}。
+ *
+ * @param defaultVisible 全局默认显不显示（缺省 `true`，= `bridge.badge.defaultVisible`）
+ * @param onRefuseHide   遮挡档挡回隐藏请求时的回调（调用方决定要不要 warn）
+ */
+export declare function badgeResolveDisplay(entry: BadgeEntry | undefined, defaultVisible?: boolean, onRefuseHide?: () => void): BadgeResolved | undefined;
+/**
+ * 遮挡档挡回隐藏请求时的 dev 警告（按 key 去重，[MUST NOT] 静默 ——
+ * 静默忽略 = 消费方以为设了其实没设）。
+ *
+ * 调用方 [MUST] 自己先过 dev 闸（`useIsDev`）；本函数只管文案与去重。
  */
-export declare function badgeResolveDisplay(entry: BadgeEntry | undefined): BadgeResolved | undefined;
+export declare const badgeWarnHideRefused: (key: string, kind: string) => void;

package/types/components/modal/use-slot-misuse-warn.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ModalPorter 落错槽的运行期检测（**非主干功能**，规则 22：删掉本文件 + 组件里那一行
+ * 委托即零残留；[MUST NOT] 出桶导出）。
+ *
+ * 要防的错：把 Porter 放进 `AppPage` 的 `#top`/`#bottom`/`#left`/`#right`。
+ * 方位槽是页面内置 `ModalShelf` 的**兄弟节点**而非后代 ⇒ provide 够不到，
+ * `evoke()` 恒返回 `null`——表现为「点按钮毫无反应」，**不报错也不崩**。
+ *
+ * 🔴 为什么非报不可：此前只有 `evoke` 里那句「未找到 ModalShelf」，那说的是**症状**不是病因，
+ * 读的人不会想到是槽位问题。实证：消费方规范 + 守卫俱在，仍一次排查出 8 个页面犯同一条
+ * （理由都是「弹窗经弹层挂载、不占版面 ⇒ 放哪都行」——只对了一半，**槽本身**照样渲染）。
+ * ⇒ 这类错 [MUST] 由运行期报出来，[MUST NOT] 指望下一份规范写得更清楚。
+ *
+ * 机制同 `use-context-defaults`：挂载后读 `$el.parentElement` 上的 `DC_SLOT_ATTR`。
+ * ModalPorter 根是 `<slot/>`（fragment）⇒ `$el` 是锚点文本 / 注释节点，`parentElement`
+ * 照样是槽 shim，可用。
+ *
+ * **恒报不限 dev**：方位槽里出现 Porter **没有任何正当用法**，零误报
+ * （对照 AppPage 的空壳槽检测：那条有合法动态状态，故 dev-only + 去重）。
+ */
+export declare const useModalPorterSlotMisuseWarn: () => void;

package/types/components/view-layout/ViewLayout.vue.d.ts

@@ -34,6 +34,14 @@ declare const _default: <P extends Record<string, any> = Record<string, any>, R
             loading: boolean;
             fetchSeq: number;
         }) => VNode[];
+        /**
+         * `appBar` 形态右侧「更多」位的内容（默认 `MoreFilled` ⋮）。**仅 `appBar` 开启时渲染**。
+         *
+         * ⚠️ 点击绑在**外层 `span`** 上 ⇒ 本槽内容 [MUST] 按「哑内容」设计（图标 / 文字）。
+         * 塞进带点击的组件（如 `ActionBtn`）时其事件会冒泡到外层、与 `onMore` / 菜单**双触发**；
+         * 要自己接管点击就别传回调，或在槽内 `@click.stop`。
+         */
+        more?: () => VNode[];
     }> & {
         default: (scope: ViewLayoutScope<R>) => VNode[];
         /**
@@ -60,6 +68,14 @@ declare const _default: <P extends Record<string, any> = Record<string, any>, R
             loading: boolean;
             fetchSeq: number;
         }) => VNode[];
+        /**
+         * `appBar` 形态右侧「更多」位的内容（默认 `MoreFilled` ⋮）。**仅 `appBar` 开启时渲染**。
+         *
+         * ⚠️ 点击绑在**外层 `span`** 上 ⇒ 本槽内容 [MUST] 按「哑内容」设计（图标 / 文字）。
+         * 塞进带点击的组件（如 `ActionBtn`）时其事件会冒泡到外层、与 `onMore` / 菜单**双触发**；
+         * 要自己接管点击就别传回调，或在槽内 `@click.stop`。
+         */
+        more?: () => VNode[];
     };
     emit: (evt: "update:isAutoRefresh", value: boolean) => void;
 }>) => import('vue').VNode & {

package/types/components/view-layout/ViewLayoutToolbar.vue.d.ts

@@ -0,0 +1,52 @@
+import { AppPageListDetailNavigationContext, ViewLayoutButtonConfig, ViewLayoutButtonContext, ViewLayoutMoreOption } from './types';
+type __VLS_Props = {
+    /** v-show 判据（父算好传入：有工具条内容或有标题） */
+    visible: boolean;
+    /** 是否渲染标题块 */
+    hasHeader: boolean;
+    /** 按钮渲染上下文（loading + refresh + 导航句柄） */
+    ctx: ViewLayoutButtonContext;
+    leftExtraButtons: ViewLayoutButtonConfig[];
+    rightExtraButtons: ViewLayoutButtonConfig[];
+    /** 内置上/下一条导航：父已做完「可选 inject 探测 + prop」的与运算 */
+    showNavigation: boolean;
+    navigationCtx?: AppPageListDetailNavigationContext;
+    /** 与 `AutoRefreshGroup` 的 v-model 对齐（`defineModel<boolean>()` ⇒ 可空） */
+    isAutoRefresh?: boolean;
+    /** 刷新动作（透传 AutoRefreshGroup，其契约是返回 Promise） */
+    refreshFn: () => Promise<unknown>;
+    loading: boolean;
+    showAutoRefresh: boolean;
+    showRefresh: boolean;
+    /** 横向内边距（左右同值，gap 阶梯派生，父算好传入；[MUST NOT] 在本组件重算） */
+    padXPx: string;
+    /** 移动端 app bar 形态（四项 gate 的总闸） */
+    appBar?: boolean;
+    back?: () => void;
+    moreOptions?: ViewLayoutMoreOption[];
+    onMoreSelect?: (item: ViewLayoutMoreOption) => void;
+    onMore?: () => void;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        header?(_: {}): any;
+        more?(_: {}): any;
+        more?(_: {}): any;
+    };
+    refs: {};
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:isAutoRefresh": (value: boolean | undefined) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:isAutoRefresh"?: ((value: boolean | undefined) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -61,6 +61,15 @@ export type ViewLayoutButtonConfig = ActionBtnConfigItem<ViewLayoutButtonContext
 /**
  * ViewLayout 展示布局 props
  */
+/**
+ * `appBar` 形态下右侧「更多」菜单的一项（规则 9：桶内符号带 `ViewLayout` 命名空间前缀）。
+ */
+export interface ViewLayoutMoreOption {
+    /** 菜单项展示文案 */
+    label: string;
+    /** 菜单项值（业务据它分发；回调入参是**整条配置**而非本值） */
+    value: string | number;
+}
 export interface ViewLayoutProps<P = Record<string, any>, R = any> {
     /** 数据拉取函数：params 来自 props.params（未传则收 undefined），每次拉取（激活 / 手动刷新 / 自动刷新）传入 */
     api: (params?: P) => Promise<R>;
@@ -122,4 +131,51 @@ export interface ViewLayoutProps<P = Record<string, any>, R = any> {
     leftExtraButtons?: ViewLayoutButtonConfig[];
     /** 右侧额外按钮（置于 AutoRefreshGroup 之前） */
     rightExtraButtons?: ViewLayoutButtonConfig[];
+    /**
+     * **移动端 app bar 形态**（默认关，opt-in）。
+     *
+     * 开启后 toolbar 变成移动端 header 的样子：去掉左缘 3px 主色条 · 下边缘加投影 ·
+     * `min-height: 44px`，并**解锁** {@link back} 与右侧「更多」位。
+     *
+     * 🔴 **四项能力全部由本开关 gate**（甲方 2026-09-19：「左侧的 back、右侧的三个点、
+     * chrome 最小高度 44、无圆角，**都是通过 props 开启移动端模式才有的**」）——
+     * 不开启时传了 `back` / `moreOptions` 也**不渲染**，高度不加 44 下限。
+     * [MUST NOT] 实现成「传了就生效」：那在默认形态下只是多出一个按钮、不报错，
+     * 是最容易漏掉又最难发现的一类偏差。
+     *
+     * 🔴 **只由消费方显式开启，[MUST NOT] 自动检测**（甲方：「是**开启**，不是检测是移动端」）。
+     * [MUST NOT] 用 `matchMedia` / UA / 视口宽 / 容器断点自动切 —— 同一套 core 服务多形态应用，
+     * 「窄就是移动端」不成立（分栏详情 / 侧栏 / 弹窗里都窄），自动切会让消费方在完全
+     * 没配置的情况下突然换一套 chrome。
+     *
+     * ⚠️ 命名避开 `header`：本组件**已有 `#header` 插槽**（标题槽），
+     * 叫 `headerMode` 会让「header 模式」与「#header 槽」在文档与代码里天天打架。
+     */
+    appBar?: boolean;
+    /**
+     * 返回回调；给了才渲染左侧返回箭头，**且仅 `appBar` 开启时**。
+     *
+     * 箭头的点击热区靠外层 padding 撑到 ≥44×44（移动端触控下限），
+     * [MUST NOT] 只放大图标本身 —— 那只是看着大、点不准。
+     */
+    back?: () => void;
+    /**
+     * `appBar` 右侧「更多」菜单项；配了（非空）即点击开 `ElDropdown` 菜单。
+     * **仅 `appBar` 开启时生效**。
+     */
+    moreOptions?: ViewLayoutMoreOption[];
+    /**
+     * 选中「更多」菜单项。**入参恒是整条 item 配置**（不是 `value`）。
+     *
+     * 仅在**配了** {@link moreOptions} 时可能触发；没配菜单时走 {@link onMore}。
+     * 🔴 两个回调**各自单义、由配置互斥**，[MUST NOT] 合并成「一个回调 + 可选参数」——
+     * 消费方**静态就知道**自己配没配菜单，可选参数会强迫他处理一个在他那份配置里
+     * 根本不可能发生的分支，而文档只能靠脚注补救。需要脚注解释的签名通常是该拆了。
+     */
+    onMoreSelect?: (item: ViewLayoutMoreOption) => void;
+    /**
+     * **没配** {@link moreOptions} 时，点击「更多」位**直接触发**（不出菜单）。
+     * 仅 `appBar` 开启时生效；与 {@link onMoreSelect} 由配置互斥。
+     */
+    onMore?: () => void;
 }

package/types/config/slot-region.d.ts

@@ -42,3 +42,15 @@ export declare enum SlotRegion {
  * 缺失 / 非法 → `undefined`（未命中 region = 不处理，由消费 hook 决定原样透传）。
  */
 export declare const parseSlotRegion: (raw: string | null | undefined) => SlotRegion | undefined;
+/** `AppPage` 四向方位槽名（= 插槽名，报错文案直接拼 `#${name}`）。 */
+export type AppPageSlotName = "top" | "right" | "bottom" | "left";
+/** `AppPage` 四向方位槽名清单（**不含默认槽**——默认槽是正确落点）。 */
+export declare const APP_PAGE_SIDE_SLOTS: readonly AppPageSlotName[];
+/**
+ * `AppPage` 四向方位槽 region → 槽名；默认槽 / 非 AppPage region / 未命中 → `undefined`。
+ *
+ * 用途 = **误用检测的公共判据**（ModalPorter 落错槽 / AppPage 空壳槽），两处同源一份映射，
+ * [MUST NOT] 各写一份 switch。
+ * 🔴 [MUST NOT] 把 `AppPage_Default` 算进来——默认槽是**正确**落点，不是方位槽。
+ */
+export declare const resolveAppPageSlotName: (region: SlotRegion | undefined) => AppPageSlotName | undefined;

package/types/hooks/use-custom-breakpoint.d.ts

@@ -10,19 +10,8 @@ export type CustomBreakpointTarget = HTMLElement | ComponentPublicInstance | nul
  * - 组件实例（有 $el）→ 取 $el；$el 非 Element（多根组件 / 注释锚点）→ dev warn + null（不猜测）。
  */
 export declare const resolveRootEl: (target: CustomBreakpointTarget) => HTMLElement | null;
-/**
- * 容器断点 hook：按**目标自身宽度**（非视口）判定响应式断点。
- * 反转接口——hook 导出 `elRef`，调用方经 `ref="elRef"` 挂到目标原生元素或组件上；
- * hook 内部解析根节点 + ResizeObserver 观测宽度 → activeBreakpoint。
- *
- * 与视口 `useBreakpoint` 互补：视口版（matchMedia）用于与 ElCol 的 CSS 媒体查询对齐；
- * 本版用于组件被塞进窄容器（如侧栏）时按容器宽自校准。
- *
- * 约束：仅支持根节点**稳定**的原生元素 / 组件（elRef 值身份变化才重解析）。
- * 若目标组件根节点在**同一实例内**从注释锚点（如 v-if 关）切到元素，elRef 身份不变、
- * 不会自动重挂观测——需保证挂载目标为稳定单根（如本项目 WatchSize 恒为单 div 根）。
- */
 export declare const useCustomBreakpoint: () => {
     elRef: import('vue').ShallowRef<CustomBreakpointTarget, CustomBreakpointTarget>;
     activeBreakpoint: Readonly<import('vue').Ref<Breakpoint, Breakpoint>>;
+    measured: Readonly<import('vue').Ref<boolean, boolean>>;
 };

package/types/hooks/use-is-dev.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 「现在是不是开发环境」的判据 —— **证明不了是生产环境就报**（fail-loud）。
+ *
+ * core 是 npm 发布包，**构建期常量在这里一律不可用**。两条已被实测证伪的写法，
+ * [MUST NOT] 回头再用：
+ *
+ * | 写法 | 为什么不行 |
+ * | --- | --- |
+ * | `import.meta.env.DEV` | **构建期**常量 —— Vite 在 **core 自己 build 时**就把它替换成 `false` 并把整段摇掉，下游永远看不到 |
+ * | 单用 `process.env.NODE_ENV !== "production"` | Vite **dev** 下源码侧根本没有 `process` 全局（真浏览器实测 `typeof process === "undefined"`）⇒ 恰好在最该报的 dev 里哑火，与 prod 行为正好反了 |
+ *
+ * ⇒ 三档依次取：
+ *
+ * ⓐ **整 bridge 的 `APP_ENV_INFO.isDev`**（精确，常态）：由**下游 app 自己**从它的
+ *    `import.meta.env` 推出来再交给 core，是唯一不受 core 构建期影响的真信号。
+ *    要求下游 `app.use(coreBridge)`（本仓标准装法）。
+ * ⓑ 无 bridge 时退 `process.env.NODE_ENV`（webpack / Vite **build** 都会替换它）。
+ * ⓒ 两者都取不到 ⇒ **当作 dev**。诊断类输出宁可多一条，也 [MUST NOT] 默认静默 ——
+ *    「检测静默失效」的症状与「压根没写」一模一样。
+ *
+ * **[MUST NOT] 出桶导出**（规则 22，`hooks/index.ts` 已锁面）：它是 core 内部诊断设施，
+ * 不是给下游的 API。[MUST] 在 setup 期调用（内部 `inject`），返回的是 getter。
+ */
+export declare const useIsDev: () => (() => boolean);

package/types/injectInfo.json.d.ts

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