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

package/types/components/list-layout/ListLayout.vue.d.ts

@@ -20,6 +20,7 @@ declare const _default: <T extends Record<string, any>, PO extends Record<string
         activeId?: ActiveRecordKey | undefined;
         activeData?: T | undefined;
     } & Partial<Pick<import('../form').FormSearchProps<PO, SO, {}>, "staticQuery">> & {
+        title?: string;
         formSearchProps?: Partial<Omit<import('../form').FormSearchProps<PO, SO, {}>, "staticQuery" | "compact" | "list">> | undefined;
     } & Pick<import('../table').TableMainProps<T, import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>> & SQ, ListLayoutInnerInjectInfo<PO, F>>, import('./types').TableMainRequiredKey> & Partial<Pick<import('../table').TableMainProps<T, import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>> & SQ, ListLayoutInnerInjectInfo<PO, F>>, import('./types').TableMainOptionsKey>> & {
         tableMainProps?: Partial<Omit<import('../table').TableMainProps<T, import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>> & SQ, ListLayoutInnerInjectInfo<PO, F>>, import('./types').TableMainOptionsKey | import('./types').TableMainRewriteKey>> | undefined;
@@ -30,6 +31,8 @@ declare const _default: <T extends Record<string, any>, PO extends Record<string
         injectInfo?: F | undefined;
         beforeSearch?: ((data: import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>>, type: FormSearchSearchType) => import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>>) | undefined;
         clearTableFilterOnReset?: boolean;
+        gap?: number;
+        moduleBg?: boolean | string;
         initialSearch?: boolean;
         separateSearch?: boolean;
         separateSearchConfig?: Pick<import('../slot-layout').SlotLayoutFlowAsideProps, "type" | "gap" | "asideWidth">;

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

@@ -21,6 +21,13 @@ SO extends Record<string, any>,
 SQ extends Record<string, any>, 
 /** 期望注入到表格列插槽上的额外内容 */
 F extends Record<string, any>> = Partial<Pick<FormSearchProps<PO, SO, {}>, FormSearchOptionsKey>> & {
+    /**
+     * 标题（默认渲染进 `header` 槽位）。
+     *
+     * 优先级：**`#header` 插槽 > `title` > 不渲染**。插槽是逃生口（复杂头部自行接管），
+     * 常见场景传 `title` 即可。与 `ViewLayout.title` 同口径 —— 列表页与详情页头部结构对齐。
+     */
+    title?: string;
     formSearchProps?: Partial<Omit<FormSearchProps<PO, SO, {}>, FormSearchOptionsKey | FormSearchRewriteKey | "compact">>;
 } & Pick<TableMainProps<T, ExtractFormStringifyFromObject<PO, SO> & SQ, ListLayoutInnerInjectInfo<PO, F>>, TableMainRequiredKey> & Partial<Pick<TableMainProps<T, ExtractFormStringifyFromObject<PO, SO> & SQ, ListLayoutInnerInjectInfo<PO, F>>, TableMainOptionsKey>> & {
     tableMainProps?: Partial<Omit<TableMainProps<T, ExtractFormStringifyFromObject<PO, SO> & SQ, ListLayoutInnerInjectInfo<PO, F>>, TableMainOptionsKey | TableMainOptionsKey | TableMainRewriteKey>>;
@@ -35,6 +42,27 @@ F extends Record<string, any>> = Partial<Pick<FormSearchProps<PO, SO, {}>, FormS
     beforeSearch?: (data: ExtractFormStringifyFromObject<PO, SO>, type: FormSearchSearchType) => ExtractFormStringifyFromObject<PO, SO>;
     /** 在点击搜索重置按钮时，是否同时调用清空表格表头过滤 */
     clearTableFilterOnReset?: boolean;
+    /**
+     * 模块间距（header / 搜索区 / 操作区各自的**下**间距，px）。
+     *
+     * 缺省跟随布局 gap 体系 —— 取 `bridge.APP_LAYOUT_GAP_CONFIG.size`（核内默认 8），
+     * 改布局 gap 时列表内部间距同步跟随；脱离 `AppLayout` 挂载（取不到 bridge）退 8。
+     * 只有该页要与全局不一样时才显式传。
+     *
+     * 数据区（表格 / 网格）是最后一块，**不带下间距**（下方没有兄弟模块要隔开）。
+     */
+    gap?: number;
+    /**
+     * @deprecated `akw76r` 起废弃 —— **三块 chrome 默认成面已覆盖它的用途**，无需再开。
+     *
+     * 它是**全开关**：一开就给搜索区 / 操作区 / **数据区**四块全上色 + 描边 + 圆角，
+     * 与本体系「辅助小块成面、**数据区恒透**」的分配直接冲突（数据区是主内容区，
+     * 给它上色会让「哪块是辅助、哪块是正文」的视觉层级塌掉）。
+     *
+     * 仍可用、行为不变（零 breaking），但 [MUST NOT] 用于新代码；移除走后续 breaking 窗口。
+     * 要改 chrome 三块的面色 → 改**主题的 `bodyColor`**（面由它直挂 `--el-bg-color`）。
+     */
+    moduleBg?: boolean | string;
     /**
      * 挂载后是否立即触发初始化查询（默认 true 查）。
      * - false：进入页面不自动拉数——表格空态显示「欢迎触发查询」（TableMain 经 hasRequested

package/types/components/modal/ModalConfirm.vue.d.ts

@@ -93,8 +93,8 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
     "onUpdate:show"?: ((value: boolean) => any) | undefined;
 }>, {
     reverse: boolean;
+    type: "" | "default" | "text" | "primary" | "success" | "warning" | "info" | "danger";
     width: number | string;
-    type: "" | "text" | "default" | "primary" | "success" | "warning" | "info" | "danger";
     direction: "rtl" | "ltr" | "ttb" | "btt";
     showClose: boolean;
     cancelText: string | (() => VNode);

package/types/components/modal/VideoPreviewTrigger.vue.d.ts

@@ -23,7 +23,7 @@ declare function __VLS_template(): {
     attrs: Partial<{}>;
     slots: {
         default?(_: {
-            open: () => void;
+            open: (event?: Event) => void;
         }): any;
         placeholder?(_: {}): any;
         error?(_: {}): any;

package/types/components/page-layout/AppPageDetail.vue.d.ts

@@ -1,12 +1,12 @@
 import { ActiveRecordKey } from '../../hooks/use-active-record';
-import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailProps } from './types';
+import { AppPageListDetailCtx, AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailProps } from './types';
 declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, never> & {
         /**
          * 完整详情上下文（含序列导航句柄）。**门面内嵌时下发**；
          * 独立使用时不传，改用下方 `id` / `record`。
          */
-        ctx?: Omit<AppPageListDetailDetailScope<T, R>, "data" | "loading">;
+        ctx?: AppPageListDetailCtx<T, R>;
         /** 独立使用时的当前项键（`ctx` 未传时生效；与 `ctx` 都无 → 落空态） */
         id?: ActiveRecordKey;
         /** 独立使用时的当前项数据（`ctx` 未传时生效），供 `detailTitle` / `#detail` 消费 */

package/types/components/page-layout/AppPageListDetailLayout.vue.d.ts

@@ -1,5 +1,5 @@
 import { ActiveRecordKey } from '../../hooks/use-active-record';
-import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailProps } from './types';
+import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListScope, AppPageListDetailProps } from './types';
 declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
         readonly "onUpdate:activeId"?: ((value: ActiveRecordKey | undefined) => any) | undefined;
@@ -11,18 +11,14 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
     attrs: any;
     slots: Readonly<{
-        list?: (scope: {
-            listProps: AppPageListDetailListProps<T>;
-        }) => unknown;
+        list?: (scope: AppPageListDetailListScope<T>) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;
         right?: () => unknown;
     }> & {
-        list?: (scope: {
-            listProps: AppPageListDetailListProps<T>;
-        }) => unknown;
+        list?: (scope: AppPageListDetailListScope<T>) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;

package/types/components/page-layout/AppPageListDetailSheet.vue.d.ts

@@ -1,10 +1,10 @@
-import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailProps } from './types';
+import { AppPageListDetailCtx, AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailListScope, AppPageListDetailProps } from './types';
 declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
         readonly onClose?: (() => any) | undefined;
     } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onClose"> & {
         listProps: AppPageListDetailListProps<T>;
-        ctx: Omit<AppPageListDetailDetailScope<T, R>, "data" | "loading">;
+        ctx: AppPageListDetailCtx<T, R>;
         listEmpty: boolean;
         sheetLayerType: "drawer" | "modal";
         sheetSize: string | number;
@@ -17,18 +17,14 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
     attrs: any;
     slots: Readonly<{
-        list?: (scope: {
-            listProps: AppPageListDetailListProps<T>;
-        }) => unknown;
+        list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;
         right?: () => unknown;
     }> & {
-        list?: (scope: {
-            listProps: AppPageListDetailListProps<T>;
-        }) => unknown;
+        list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;

package/types/components/page-layout/AppPageListDetailSplit.vue.d.ts

@@ -1,8 +1,8 @@
-import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailProps } from './types';
+import { AppPageListDetailCtx, AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailListScope, AppPageListDetailProps } from './types';
 declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, never> & {
         listProps: AppPageListDetailListProps<T>;
-        ctx: Omit<AppPageListDetailDetailScope<T, R>, "data" | "loading">;
+        ctx: AppPageListDetailCtx<T, R>;
         listEmpty: boolean;
         listWidth: string;
         /**
@@ -20,18 +20,14 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
     attrs: any;
     slots: Readonly<{
-        list?: (scope: {
-            listProps: AppPageListDetailListProps<T>;
-        }) => unknown;
+        list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;
         right?: () => unknown;
     }> & {
-        list?: (scope: {
-            listProps: AppPageListDetailListProps<T>;
-        }) => unknown;
+        list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;

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

@@ -1,8 +1,17 @@
+import { AppPageListLayoutRecommended } from '../app-layout';
 import { ViewLayoutProps } from '../view-layout';
 import { ActiveRecordKey } from '../../hooks/use-active-record';
 import { NoInferType } from '../../types';
 /** 形态：`auto` 按视口宽定档（默认）｜`split` 强制宽屏并排｜`sheet` 强制窄屏抽屉 */
 export type AppPageListDetailMode = "auto" | "split" | "sheet";
+/**
+ * **实际**档位（`mode` 入参解析后的结果）——`auto` 档下才有悬念，强制档恒等于入参。
+ *
+ * 与入参 `mode` 刻意不同名：`mode` 回答「我要什么」，本值回答「现在是什么」。
+ * 三个插槽 scope 都以 `resolvedMode` 下发，消费方 [MUST NOT] 自己再判一次视口宽
+ * （与门面的 `splitAt` 形成两个事实源，调用方改阈值时静默不一致）。
+ */
+export type AppPageListDetailResolvedMode = "split" | "sheet";
 /**
  * `#list` 插槽 scope 携带的「列表接线包」——业务 [MUST] 整体 `v-bind` 到列表组件上：
  *
@@ -43,11 +52,44 @@ export interface AppPageListDetailDetailScope<T = any, R = any> {
     data: R | undefined;
     /** 详情接口拉取中（未传 `detailApi` 时恒为 false） */
     loading: boolean;
+    /**
+     * 详情接口**成功**拉取次数（未传 `detailApi` 时恒 0）。详情里的懒加载下游块 `watch` 它即可
+     * 选择性重拉，无需把下游数据一起聚进 `detailApi`（那会把没打开的 tab 也拉了）。
+     *
+     * 🔴 失败不递增。[MUST NOT] 用 `loading` 的 `true→false` 代替，也 [MUST NOT] watch `data` 的对象身份。
+     */
+    fetchSeq: number;
+    /**
+     * 当前**实际**档位。**仅门面下发**；`AppPageDetail` 独立成页时为 `undefined`（无形态概念）。
+     */
+    resolvedMode?: AppPageListDetailResolvedMode;
+}
+/**
+ * 门面下发给形态件 / 详情区的上下文 = 详情 scope 去掉「由详情容器现场补齐」的三键
+ * （`data` / `loading` / `fetchSeq` 来自内置 `ViewLayout` 的插槽作用域，setup 里取不到）
+ * 与「由门面自己补的」`resolvedMode`。
+ */
+export type AppPageListDetailCtx<T = any, R = any> = Omit<AppPageListDetailDetailScope<T, R>, "data" | "loading" | "fetchSeq" | "resolvedMode">;
+/**
+ * `#list` 插槽 scope。
+ *
+ * `listLayoutRecommended` 是 `AppPage#left` 的窄栏推荐配置（split 档才有值）——它与
+ * `useContextDefaults` 的窄栏上下文默认**同源**（`APP_PAGE_LIST_LAYOUT_RECOMMENDED`），
+ * 是消费方在 `#list` 里包了包裹层、隐式上下文断链时的显式出路。
+ */
+export interface AppPageListDetailListScope<T = any> {
+    listProps: AppPageListDetailListProps<T>;
+    /** 窄栏推荐配置；**sheet 档为 `undefined`**（列表在默认槽，不是窄栏） */
+    listLayoutRecommended: AppPageListLayoutRecommended | undefined;
+    /** 当前**实际**档位 */
+    resolvedMode: AppPageListDetailResolvedMode;
 }
 /** `#empty` 插槽 scope */
 export interface AppPageListDetailEmptyScope {
     /** true = 列表本身无数据；false = 有数据但未选中。两种空态文案不同，由业务分流 */
     listEmpty: boolean;
+    /** 当前**实际**档位（仅门面下发；`AppPageDetail` 独立成页时 `undefined`） */
+    resolvedMode?: AppPageListDetailResolvedMode;
 }
 /**
  * 透传给内置 `ViewLayout` 的 props（`detailApi` 传了才有内置 ViewLayout，不传则本项无落点）。

package/types/components/panel/PanelItemNestForm.vue.d.ts

@@ -30,6 +30,8 @@ declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {
         generate: () => Record<string, any>;
         parse: (stringifyData: import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<Record<string, any>, Record<string, any>>>) => Record<string, any>;
         stringify: () => import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<Record<string, any>, Record<string, any>>>;
+        getAiSchema: () => Promise<import('../form').FormAiSchema>;
+        setValues: (partial: Partial<Record<string, any>>) => void;
     } | null;
 }, any>;
 export default _default;

package/types/components/table/types.d.ts

@@ -191,6 +191,15 @@ T extends Record<string, any>,
 SQ extends Record<string, any>, 
 /** 期望注入到表格列插槽上的额外内容 */
 F extends Record<string, any>> {
+    /**
+     * 自持面（默认 `true`）：面色 + 内呼吸 + 圆角，单独用也观感一致。
+     *
+     * 🔴 开启时自身 padding **计入数据区可用高**——样式与高度账在同一组件内闭环，
+     * [MUST NOT] 退回「外层经 `:deep()` 刷面、内层算高」（两边各管一半必漏）。
+     * 置于 `ModalConfirm` 正文时经上下文自动取 `false`（那儿已是一块面，
+     * 暗色下二次成面会凹）；显式传值恒优先。
+     */
+    surface?: boolean;
     /** 展示分页器 */
     showPager?: boolean;
     /**

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

@@ -10,8 +10,26 @@ declare const _default: <P extends Record<string, any> = Record<string, any>, R
     attrs: any;
     slots: Readonly<{
         default: (scope: ViewLayoutScope<R>) => VNode[];
+        /**
+         * 标题行插槽；传了即接管，`title` prop 不再渲染。
+         * 带 `data` / `loading` scope —— 标题常要跟着详情数据走（如 `{{ data?.name }}`），
+         * 而 `data` 在 setup 里取不到（它是本组件拉取的结果），故 [MUST] 由插槽 scope 下发。
+         */
+        header?: (scope: {
+            data: R | undefined;
+            loading: boolean;
+        }) => VNode[];
     }> & {
         default: (scope: ViewLayoutScope<R>) => VNode[];
+        /**
+         * 标题行插槽；传了即接管，`title` prop 不再渲染。
+         * 带 `data` / `loading` scope —— 标题常要跟着详情数据走（如 `{{ data?.name }}`），
+         * 而 `data` 在 setup 里取不到（它是本组件拉取的结果），故 [MUST] 由插槽 scope 下发。
+         */
+        header?: (scope: {
+            data: R | undefined;
+            loading: boolean;
+        }) => VNode[];
     };
     emit: (evt: "update:isAutoRefresh", value: boolean) => void;
 }>) => import('vue').VNode & {

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

@@ -26,6 +26,13 @@ export interface ViewLayoutScope<R = any> {
     refresh: () => Promise<void>;
     /** 内容区可用高度（refine 时 = 视口高 − toolbar reserve，超高内滚的 max-height 预算）；自然流 undefined */
     viewportHeight: number | undefined;
+    /**
+     * **成功**拉取计数（单调递增，首拉成功即 1）。供下游懒加载块判「详情整体刷新了、我该重拉」。
+     *
+     * 🔴 失败**不**递增——故 [MUST NOT] 用 `loading` 的 `true→false` 代替（失败也会落回 false，
+     * 下游会基于旧数据白拉一次）；也 [MUST NOT] watch `data` 的对象身份（「每次新引用」从不是承诺）。
+     */
+    fetchSeq: number;
 }
 /**
  * ViewLayout toolbar 按钮渲染上下文（对齐 TableToolbar 惯例，但只含展示布局句柄——不含表格能力）
@@ -84,6 +91,14 @@ export interface ViewLayoutProps<P = Record<string, any>, R = any> {
     showAutoRefresh?: boolean;
     /** 是否显示手动刷新按钮（默认 true） */
     showRefresh?: boolean;
+    /**
+     * 标题（渲染进 `#header` 行，位于操作条之上——与 `ListLayout` 的 header 槽结构对齐）。
+     *
+     * 优先级：**`#header` 插槽 > `title` > 不渲染**。插槽是逃生口，常见场景传 `title` 即可。
+     * 🔴 [MUST NOT] 把标题塞进内容插槽自画 —— 那样它成了「内容的第一行」而非
+     * 「容器的标题位」，主题 persona 也无从定向（`AppPageDetail` 原先即如此，已归位）。
+     */
+    title?: string;
     /**
      * 是否显示内置「上一条 / 下一条」导航（默认 true）。
      * ⚠️ **真正的显隐判据是可选 inject 探测**：只有置于 `AppPageListDetailLayout` 内

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

@@ -26,7 +26,16 @@ export declare enum SlotRegion {
     /** AppPage left 槽（侧向悬浮区） */
     AppPage_Left = 5,
     /** TabsMain 页签内容（tab item） */
-    TabsMain_Item = 6
+    TabsMain_Item = 6,
+    /**
+     * ModalConfirm 正文区（弹窗 / 抽屉的默认插槽直系父）。
+     *
+     * 用途：告诉后代「**你已经站在一块面上了**」—— 弹窗正文的底是
+     * `--el-bg-color-overlay`（抬升面），后代 [MUST NOT] 再刷一层面色，
+     * 否则暗色下 overlay `#1d1e1f` 上盖 `#141414` 会出现「弹窗里凹下去一块」
+     * （亮色两者都是 `#fff`，**看不出来** —— [MUST NOT] 只用亮色截图验收）。
+     */
+    ModalConfirm_Body = 7
 }
 /**
  * 读 DOM 槽位数字值并守卫：数字读回是字符串，[MUST] 经本函数 `Number()` 强转 + 枚举值校验；

package/types/hooks/use-surface.d.ts

@@ -0,0 +1,34 @@
+import { ComputedRef } from 'vue';
+/** {@link useSurface} 返回值 */
+export interface UseSurfaceReturn {
+    /** 最终是否成面（显式 prop > 上下文推导 > 默认 true） */
+    surfaceActive: ComputedRef<boolean>;
+    /** 卡内呼吸数值（px）；关面时 0。样式与高度账**共用此一处** */
+    surfacePad: ComputedRef<number>;
+    /** 呼吸的 px 串（供 scoped CSS `v-bind`），与 {@link UseSurfaceReturn.surfacePad} 同源 */
+    surfacePadCss: ComputedRef<string>;
+}
+/**
+ * 数据区组件的「自持面」——面色 + 内呼吸 + 圆角由组件**自己**持有。
+ *
+ * 🔴 **存在的理由 = 让样式与高度账在同一个组件内闭环**：内呼吸既用于渲染，
+ * 又要从数据区可用高里扣掉。此前 padding 由 `ListLayout` 经 `:deep()` 从外面刷、
+ * 可用高在 `TableMain` 里算，两个组件各管一半 ⇒ 每页恒漏一个 padding
+ * （甲方 2026-09-15 报障）。**[MUST NOT] 退回「外层刷面、内层算高」。**
+ *
+ * 用法：消费组件 [MUST] 把 `surfacePad` 计入自己的可用高扣减，
+ * 并把 `surfacePadCss` 经 `v-bind` 喂给 padding —— 两者同源，[MUST NOT] 各写各的。
+ *
+ * 弹窗正文（`SlotRegion.ModalConfirm_Body`）已经是一块面，经既有
+ * `useContextDefaults` + `data-dc-slot` 自动关闭，[MUST NOT] 新造 inject key。
+ * ⚠️ 只读**直系父** DOM：弹窗正文里隔了容器（如包着 `ListLayout`）就推导不到，
+ * 此时由使用方显式传 `surface={false}`。[MUST NOT] 改成向上遍历——那会让
+ * 「直系父」这条简单规则失效。
+ *
+ * 内部件：仅供 table / data-view 族复用，[MUST NOT] 桶导出进公共 API 面。
+ *
+ * @param getProps 惰性 getter，读 `props` 保持响应式（含可选 `surface`）
+ */
+export declare const useSurface: <P extends {
+    surface?: boolean;
+}>(getProps: () => P) => UseSurfaceReturn;

package/types/inject/key.d.ts

@@ -174,6 +174,16 @@ export declare const APP_LAYOUT_BRIDGE_KEY: InjectionKey<AppLayoutBridgeSlice>;
  * Symbol.for 保证跨包/跨 chunk/跨 ESM 实例唯一（同 APP_LAYOUT_BRIDGE_KEY，规则 8）。
  */
 export declare const CORE_BRIDGE_KEY: InjectionKey<CoreBridge>;
+/**
+ * FormMain 本轮校验的**错误字段 key 列表** inject key。
+ *
+ * 用途：折叠分组（`swiftFormItemGroup`）的标题组件据此判断「错误是否落在本组」，
+ * 命中则**自动展开 + 滚动到错误项** —— 折叠 ≠ 隐藏，折叠区照常校验，
+ * 但 [MUST NOT] 让使用者面对「看不见错在哪、却提交不了」。
+ *
+ * 由 `FormMain` provide（每次 `validate()` 结算时写入，成功写空数组）。
+ */
+export declare const FORM_VALIDATE_ERROR_KEYS: InjectionKey<Readonly<Ref<string[]>>>;
 /**
  * 嵌套子 FormMain exposeMap inject key（配置化嵌套联结组件 Nest 三件套挂载）。
  * ---

package/types/injectInfo.json.d.ts

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

package/types/store/app.d.ts

@@ -51,6 +51,7 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         readonly blur?: string | undefined;
         readonly focusRing?: string | undefined;
         readonly surface?: string | undefined;
+        readonly ground?: string | undefined;
     }>;
     showHeader: import('vue').ComputedRef<boolean>;
     showFooter: import('vue').ComputedRef<boolean>;
@@ -111,6 +112,7 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         readonly blur?: string | undefined;
         readonly focusRing?: string | undefined;
         readonly surface?: string | undefined;
+        readonly ground?: string | undefined;
     }>;
     showHeader: import('vue').ComputedRef<boolean>;
     showFooter: import('vue').ComputedRef<boolean>;
@@ -171,6 +173,7 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         readonly blur?: string | undefined;
         readonly focusRing?: string | undefined;
         readonly surface?: string | undefined;
+        readonly ground?: string | undefined;
     }>;
     showHeader: import('vue').ComputedRef<boolean>;
     showFooter: import('vue').ComputedRef<boolean>;

package/types/utils/dom.d.ts

@@ -22,3 +22,34 @@ export declare function domClosestScrollableAncestor(el: HTMLElement | null | un
  * 而 CSS 仍以该容器为 scrollport → 粘住顶距错位（弹窗内实测踩坑）。
  */
 export declare function domClosestStickyScrollport(el: HTMLElement | null | undefined): HTMLElement | undefined;
+/** {@link domScrollIntoViewport} 选项 */
+export interface DomScrollIntoViewportOptions {
+    /**
+     * 滚动行为。**默认 `"auto"`（瞬时）**，[MUST NOT] 改默认为 `"smooth"`。
+     *
+     * 本仓踩过：`TabsTile` 自研 smooth 滚动被 **v-model 回流重渲染打断**
+     * （watcher 里异步读 y 恒 0，真机复现），最终弃用改走 `ElAnchor`。
+     * 「列表项聚焦跟随」属跟随而非导航，瞬时定位反而稳；要动效由调用方显式传。
+     */
+    behavior?: ScrollBehavior;
+    /** 纵向对齐，默认 `"nearest"`（见函数注释） */
+    block?: ScrollLogicalPosition;
+    /** 横向对齐，默认 `"nearest"` */
+    inline?: ScrollLogicalPosition;
+}
+/**
+ * 把目标元素滚进**最近的滚动视口**（薄封装 `Element.scrollIntoView`）。
+ *
+ * 🔴 **默认 `block/inline: "nearest"`**，这是本函数存在的理由：
+ * - 原生默认 `"start"` 会「**越级滚动**」—— 子元素调用却把整个 `body` 滚了
+ *   （本仓 `AppHeader` 曾是裸 `scrollIntoView({behavior:"smooth"})`，即此写法）；
+ * - `"nearest"` 同时意味着**已在视口内则零动作**，天生具备
+ *   `scrollIntoViewIfNeeded`（非标准 API）的语义，无需引库。
+ *
+ * `target` 允许 `null | undefined`（调用方常从 ref / `querySelector` 取），静默返回。
+ * SSR / 无 DOM 环境同样静默。
+ *
+ * [MUST NOT] 为此引 `scroll-into-view-if-needed`（~3KB）：它的价值在多层嵌套容器 +
+ * 自定义边距，当前用不到；本函数 API 形状与之对齐，真需要时可平替。
+ */
+export declare function domScrollIntoViewport(target: Element | null | undefined, options?: DomScrollIntoViewportOptions): void;

package/types/utils/gap-scale.d.ts

@@ -0,0 +1,46 @@
+import { CoreThemeDensity } from '../bridge';
+/**
+ * 间距阶梯：**一个基数派生四档**（huhyx7）。
+ *
+ * 基数 = `bridge.APP_LAYOUT_GAP_CONFIG.size`（默认 8）。四档按**语义**取倍率，
+ * [MUST NOT] 处处取同值 —— 全等会让「页面级分隔」与「卡内分段」一样重、层级读不出来。
+ *
+ * ```
+ * 外圈   ×2    内容 ↔ chrome / viewport 边 / 悬浮插槽 ↔ 默认内容
+ * 呼吸   ×1.5  卡片内边距
+ * 模块   ×1    chrome 模块彼此、卡 ↔ 卡
+ * 分段   ×0.5  同一张卡内的段与段
+ * ```
+ *
+ * 🔴 **倍率是实现细节不是配置项**：[MUST NOT] 为此新开 `innerGap` / `outerGap` 之类的
+ * bridge 字段 —— 那会退回多旋钮，而单旋钮正是本阶梯的全部价值。
+ *
+ * 基数取 8 的依据：4px 基准网格 ×2 —— Material 8dp grid / AntD 8 的倍数 /
+ * Tailwind `spacing-2` 同档，且**它已在用**，基线不动。
+ */
+export declare const GAP_SCALE_RUNG: {
+    /** 外圈：内容 ↔ chrome、内容 ↔ viewport 边、悬浮插槽 ↔ 默认内容 */
+    readonly outer: 2;
+    /** 卡片内边距（呼吸） */
+    readonly breath: 1.5;
+    /** 模块 / 卡之间 */
+    readonly module: 1;
+    /** 同一张卡内的分段 */
+    readonly section: 0.5;
+};
+/** 间距档位名 */
+export type GapScaleRung = keyof typeof GAP_SCALE_RUNG;
+/**
+ * 按密度档缩放间距基数（四舍五入到整 px —— 半像素会让相邻块出现 1px 缝隙差）。
+ *
+ * 默认 `cozy` ⇒ 原样返回。非法 / 缺省密度档退 `cozy`（不崩、不静默变形）。
+ */
+export declare const gapScaleBase: (size: number, density?: CoreThemeDensity) => number;
+/**
+ * 取某一档的间距值（px 数值）。
+ *
+ * @param size    基数（`APP_LAYOUT_GAP_CONFIG.size`）
+ * @param rung    档位
+ * @param density 密度档（缺省 `cozy`）
+ */
+export declare const gapScaleValue: (size: number, rung: GapScaleRung, density?: CoreThemeDensity) => number;

package/types/utils/index.d.ts

@@ -4,3 +4,4 @@ export * from './dom';
 export * from './router';
 export * from './export';
 export * from './theme-scale';
+export * from './gap-scale';

package/types/utils/theme-scale.d.ts

@@ -34,6 +34,29 @@ export declare const themeScaleMix: (c1: string, c2: string, w1: number) => stri
  * 非 hex 入参（`var(...)` / `rgba(...)`）→ 原样返回（不崩、不强转）。
  */
 export declare const themeScaleToRgba: (hex: string, alpha: number) => string;
+/**
+ * 布局底（page 档）派生：bodyColor（面）向黑压一步，混黑权重
+ * `k = min(0.5, 18/maxCh)`——最亮通道恒降 ≈18（暗色 `#141414` 命中 REL 上限 0.5
+ * 恰为 EP 暗 page `#0a0a0a`；亮色 `#fff` 得 `#ededed`，比 EP/AntD 的 `#f5f5f5` 深一档，
+ * 见 {@link PAGE_STEP_CH} 的取值理由）。
+ * 公式与明暗无关（对当前模式的 bodyColor 直接适用）。
+ * 非 hex（var/rgba/渐变）→ 原样返回（调用方按原值直用，行为不变）。
+ *
+ * ⚠️ **两个已知退化点**（实际色差 `Δ = min(0.5×maxCh, 18)`）：
+ * - `maxCh` 太小（近黑）→ Δ 塌向 0（`#000` 得 Δ=0、底 = 面）⇒ 由 {@link themeScaleIsNearBlack}
+ *   判出后翻转基准兜底（见 use-theme-apply `buildElevationDecls`）；
+ * - 非 hex → 原样返回、底 = 面。
+ *
+ * 两者的**正解都是显式给 `AppThemeColor.ground`**，翻转只是没给时的兜底。
+ */
+export declare const themeScalePageColor: (bodyColor: string) => string;
+/**
+ * 抬升面（overlay 档）派生：暗色 = bodyColor（面）向白提一步，混白权重
+ * `k = min(0.5, 10/(255-maxCh))`——最亮通道恒升 ≈10（`#141414→#1e1e1e`，
+ * ≈ EP 暗 overlay `#1d1e1f`）；亮色 = bodyColor 原值（EP 亮 overlay 即 `#fff`=面，
+ * 亮色层级靠投影/蒙层表达，不再提亮）。非 hex → 原样返回。
+ */
+export declare const themeScaleSurfaceColor: (bodyColor: string, mode: ThemeScaleMode) => string;
 /**
  * 按 EP 算法 + 模式感知派生一个语义色的 7 档色阶。
  *
@@ -43,3 +66,13 @@ export declare const themeScaleToRgba: (hex: string, alpha: number) => string;
  * `base` 非 hex 时各档兜底返回 `base` 原值（保持可挂载、不崩）。
  */
 export declare const themeScaleDerive: (base: string, mode: ThemeScaleMode) => ThemeColorScale;
+/**
+ * 近黑判定：`bodyColor` 是否已暗到「压不动」，需要翻转基准（底取原值、面向白提）。
+ *
+ * 🔴 **判据用「余量」不用「亮 / 暗」**：后者要外部告知 `isDark`（本 util 拿不到、
+ * 强行传参会把一个纯函数变成要看模式的函数），且会在「深灰但不算暗色」的主题上判错
+ * ——余量是从色值本身就能算出来的，不依赖任何外部状态。
+ *
+ * 非 hex → `false`（判不了就不翻；那种情况的正解是显式给 `ground`）。
+ */
+export declare const themeScaleIsNearBlack: (bodyColor: string) => boolean;