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

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

@@ -9,6 +9,20 @@ import { ElTableColumnProps, TableApiParams, TableApiResult, TableColumnDefaultS
  * 未配置的断点回落 ≤ 当前断点最近一档（el-col 心智），全无则用全局 span。
  */
 export type GridColumnsConfig = Partial<Record<Breakpoint, number>>;
+/**
+ * 流体列宽：列数由**容器宽**自然得出（`repeat(auto-fill, minmax(min px, 1fr))`），不需要断点表。
+ * 消费方 2026-09-02 拍板过「列数按容器宽流体、[MUST NOT] 钉死」。
+ *
+ * ⚠️ 仅**无虚拟化**的路径（`DataListView`）支持：`DataGridView` 要按列数把存量 chunk 成
+ * 等长的行做虚拟化，而本档的列数是浏览器算的、JS 拿不到 ⇒ 那条路径的 `gridColumns`
+ * [MUST NOT] 放开本形态。
+ */
+export interface DataViewFluidColumns {
+    /** 单列最小宽（px） */
+    min: number;
+}
+/** 卡片网格列数配置的全部形态（数字定列 / 断点表 / 流体） */
+export type DataViewGridColumns = number | GridColumnsConfig | DataViewFluidColumns;
 /**
  * DataListView 字段渲染作用域
  * ---
@@ -48,6 +62,36 @@ export interface DataListViewProps<T extends Record<string, any>, F extends Reco
     maxHeight?: number;
     /** 最小高度；传入时容器撑满至此高（配合 TableMain fillHeight 顶分页器到底），缺省不设 */
     minHeight?: number;
+    /**
+     * 卡片网格列数。**不传 = 不成网格**（单列流式，与本能力引入前逐字一致）。
+     * - `number`：定列数 `repeat(N, 1fr)`；
+     * - 对象断点表：el-col span 制 24 栅格（与 `DataGridView` **同语义同实现**，
+     *   未配档回落 ≤ 当前断点最近一档）；
+     * - `{ min: N }`：**流体列宽** `repeat(auto-fill, minmax(Npx, 1fr))`，列数由容器宽自然得出。
+     *
+     * 🔴 [MUST NOT] 在消费侧再手写 `:deep(.data-list-view){display:grid;…}` ——
+     * 本 prop 存在的理由正是收掉那 15 份重复。
+     */
+    gridColumns?: DataViewGridColumns;
+    /**
+     * item 间距（px）。缺省取间距阶梯的**模块档**（`gap.size × 密度 × 1`，默认 8）——
+     * grid 的 gap 是**卡与卡之间**，正是模块档的定义值。
+     * [MUST NOT] 在消费侧写死像素补偿（改 gap 基数 / 换密度档时会脱钩）。
+     */
+    gap?: number;
+    /**
+     * 内置卡壳（默认 `true`）：border + radius + padding，全走 token，落在
+     * `.data-list-view-item` 上（[MUST NOT] 另包一层，见该组件注释）。
+     * 自带卡片视觉时传 `false`，[MUST NOT] 在自己的卡上再画一层边框叠上去。
+     */
+    card?: boolean;
+    /**
+     * 瀑布流装箱（默认 `false`）。开启后卡片按实测高度跨行装箱，**顺序仍是行优先（横向）**。
+     * 🔴 默认关的依据是「需要 JS 就默认不开」—— 纯 CSS 三条路都死（`columns` 竖着填会打乱
+     * 排序、`masonry` 规范未定稿 Chrome 不支持、`grid-row: span` 仍要先知道像素高）。
+     * ⚠️ `DataGridView` **不提供**本能力：它按列数 chunk 成等高行做虚拟化，与瀑布流冲突。
+     */
+    masonry?: boolean;
     /** 是否启用选中能力，缺省关闭 */
     selectable?: boolean;
     /** 获取column 列 上下文 render参数 */
@@ -133,6 +177,14 @@ export interface InfiniteListViewProps<T extends Record<string, any> = Record<st
      * 详见 `hooks/use-surface.ts`。
      */
     surface?: boolean;
+    /**
+     * **项自己已经成卡**（面与面不叠，p4wrtn）。为真时容器**只撤面色、不撤呼吸与圆角** ——
+     * 呼吸计入高度账（与可用高扣减同源），撤了会连带改 refine 的 reserve。
+     *
+     * 🔴 判据 [MUST NOT] 收窄成「`card === true`」：`InfiniteListView` 没有 `card`
+     * （卡由消费方自画），那样写会整条漏掉它。
+     */
+    itemCard?: boolean;
     /** 传入时容器限高滚动（内部 overflowY: auto）；数字 = px，字符串 = CSS 长度（如 "100vh"） */
     maxHeight?: number | string;
     /** opt-in 触摸下拉刷新（默认关） */
@@ -167,12 +219,36 @@ export interface DataGridViewProps<T extends Record<string, any>, SQ extends Rec
      * （24 栅格，如 `{ xs: 24, sm: 12, md: 8, lg: 6, xl: 4 }`，列数 = 24 / span）。
      */
     gridColumns?: number | GridColumnsConfig;
+    /**
+     * item 间距（px，横纵同值）。缺省取间距阶梯的**模块档**（默认 8），与 `DataListView` 同源。
+     *
+     * ⚠️ **原先写死 `12`**（连同行间距的 `padding-bottom`）—— 那是**呼吸档**（卡片内边距）
+     * 的值，用在「卡与卡之间」是档位用错；归位到模块档后同时接上 density 缩放。
+     * 老页面观感会紧 4px，[MUST] 在 migrations 登记（显式传 `12` 可维持旧观感）。
+     */
+    gap?: number;
+    /**
+     * 内置卡壳（默认 `true`）：border + radius + padding，走 token。
+     *
+     * 🔴 **壳已从插槽 fallback 内移到 `.data-grid-view__cell`** —— 原实现只在
+     * 「没给 `#custom-view-item`」时才有壳，而真实业务几乎总要给插槽 ⇒ 一给插槽就没壳。
+     * 落在 cell 上后**给不给插槽都有壳**，且 DOM 层级恒定（消费方的 `:deep()` 不会跟着变）。
+     */
+    card?: boolean;
     /**
      * 自持面（默认 `true`）：面色 + 内呼吸 + 圆角，单独用也观感一致。
      * 置于 `ModalConfirm` 正文时经上下文自动取 `false`；显式传值恒优先。
      * 详见 `hooks/use-surface.ts`。
      */
     surface?: boolean;
+    /**
+     * **项自己已经成卡**（面与面不叠，p4wrtn）。为真时容器**只撤面色、不撤呼吸与圆角** ——
+     * 呼吸计入高度账（与可用高扣减同源），撤了会连带改 refine 的 reserve。
+     *
+     * 🔴 判据 [MUST NOT] 收窄成「`card === true`」：`InfiniteListView` 没有 `card`
+     * （卡由消费方自画），那样写会整条漏掉它。
+     */
+    itemCard?: boolean;
     /**
      * 数据区最大高度；与 refine 二选一作为高度基准。
      * 数字 = px；字符串 = CSS 长度（默认 "100vh" = 满视口高，等价视口高度限高，

package/types/components/data-view/use-grid-layout.d.ts

@@ -0,0 +1,42 @@
+import { ComputedRef, CSSProperties } from 'vue';
+import { DataViewGridColumns } from './types';
+/** {@link useDataViewGridLayout} 入参（全部惰性 getter，保持响应式） */
+export interface UseDataViewGridLayoutOptions {
+    /** 列数配置；`undefined` = 不成网格 */
+    gridColumns: () => DataViewGridColumns | undefined;
+    /** 显式间距（px）；`undefined` = 取间距阶梯模块档 */
+    gap: () => number | undefined;
+}
+/** {@link useDataViewGridLayout} 返回 */
+export interface UseDataViewGridLayoutReturn {
+    /** 生效间距（px）：显式 `gap` > 间距阶梯**模块档** */
+    gridGap: ComputedRef<number>;
+    /** `grid-template-columns` 值；`gridColumns` 未传 → `undefined` */
+    gridTemplateColumns: ComputedRef<string | undefined>;
+    /** 网格容器样式；不成网格时 `undefined`（调用方原样透给 `:style`） */
+    gridStyle: ComputedRef<CSSProperties | undefined>;
+    /**
+     * 内置卡壳的内呼吸（px）= 间距阶梯的**呼吸档**（×1.5，默认 12）。
+     * 🔴 [MUST NOT] 改读 `--dc-core-content-gap` —— 那是 huhyx7 明令废掉的第二来源，
+     * 与 gap 各随不同轴变动，最松密度档会出现「卡内 20 ≥ 外圈 20 > 卡间 8」的乱序。
+     * 与 `hooks/use-surface.ts` 同档同源（数据区自持面的内呼吸也是这一档）。
+     */
+    cardPad: ComputedRef<number>;
+}
+/**
+ * 卡片网格布局（两条卡片路径共用）——列数 + 间距的**唯一解析口**。
+ *
+ * 🔴 **存在的理由 = 两条路径的语义必须逐字一致**：`DataGridView`（存量累加）与
+ * `DataListView`（分页）都要「按断点算列数」，各写一份必然漂移 —— 同一个页面切
+ * viewMode 时列数会跳。断点换算复用 `resolveGridColumnsByBreakpoint`（el-col span 制
+ * 24 栅格），[MUST NOT] 在任一路径另造一套。
+ *
+ * **间距缺省取「模块档」（×1，默认 8）而非历史写死的 12**：`grid` 的 gap 是
+ * **卡与卡之间**，正是间距阶梯里模块档的定义；写死的 12 是**呼吸档**（卡片内边距）的值，
+ * 属档位用错。归位后同时接上 density 缩放（compact/cozy/comfortable ×0.75/×1/×1.5）。
+ *
+ * ⚠️ **流体档 `{ min }` 只该给无虚拟化的路径用**：它的列数由浏览器算、JS 拿不到，
+ * 而 `DataGridView` 要按列数把存量 chunk 成等长的行做虚拟化 ⇒ 那条路径 [MUST NOT] 放开它
+ * （类型层已在各自 props 上收窄，本函数只负责「给了就认」）。
+ */
+export declare const useDataViewGridLayout: (options: UseDataViewGridLayoutOptions) => UseDataViewGridLayoutReturn;

package/types/components/data-view/use-masonry.d.ts

@@ -0,0 +1,44 @@
+import { CSSProperties, Ref } from 'vue';
+/** {@link useDataViewMasonry} 入参（全部惰性 getter，保持响应式） */
+export interface UseDataViewMasonryOptions {
+    /** 开关（`props.masonry`）；关时本 hook 恒等于不存在 */
+    enabled: () => boolean;
+    /** 网格容器元素 */
+    container: () => HTMLElement | undefined;
+    /** 生效间距（px），与网格的 gap 同源 */
+    gap: () => number;
+    /** 数据引用（变了即重测——翻页 / 换筛选） */
+    data: () => unknown;
+}
+/** {@link useDataViewMasonry} 返回 */
+export interface UseDataViewMasonryReturn {
+    /** 各项跨度（按 DOM 序）；未测到的项为 `undefined`，由 CSS 兜底跨度接住 */
+    masonrySpans: Ref<(number | undefined)[]>;
+    /** 容器附加样式；关闭时 `undefined` */
+    masonryContainerStyle: Ref<CSSProperties | undefined>;
+}
+/**
+ * 瀑布流装箱（非主干增强，规则 22 同级 hook 收纳）——删除本功能 =
+ * 删本文件 + 组件里那行委托 + 模板挂点，主干零残留。
+ *
+ * **为什么是 JS**（条目已实证，[MUST NOT] 再判一遍）：`columns` 多列**竖着填**
+ * （1,2,3 落第一列），按时间 / 热度排序的列表会被打乱顺序；`masonry` 规范未定稿、
+ * Chrome 不支持；`grid-row: span N` 的跨度是整数行，仍要先知道卡片像素高。
+ * ⇒ 走 `grid-auto-rows: <单位>` + 每项 `grid-row-end: span N`，**顺序仍是行优先**。
+ *
+ * 🔴 **五个坑的守法**（全都不报错、只表现为「看着有点怪」）：
+ * 1. **重叠** —— 没拿到跨度的项默认只占 1 行。守法 = CSS 给**兜底跨度**（见组件样式），
+ *    本 hook 对未测到的项返回 `undefined`（不写 inline span）⇒ 退回那条兜底。
+ *    增强失败只该「不够好看」，[MUST NOT] 变成布局坏掉。
+ * 2. **跨度永远不写** —— 容器在数据到达前后被换成另一个元素，挂载时抓的 ref 成了游离节点。
+ *    守法 = 容器走 **getter 每次现读**，[MUST NOT] 在 setup 里把 el 存成常量。
+ * 3. **跨度写了不生效** —— 写在卡片上而网格项是外层盒。本仓内部实现**自己就持有网格项**
+ *    （`.data-list-view-item`），跨度直接写它身上 ⇒ 这条坑在此天然不存在。
+ * 4. **卡底多一截空白** —— 用「列宽 × 比例 + 文字区估值」算高会飘。守法 = **直接量**
+ *    项的实际高度。⚠️ 量的前提是项**不被拉伸**：组件在瀑布流态给项 `align-self: start`，
+ *    否则项盒会被撑满跨度区域、量出来的恒等于写进去的 ⇒ 自我循环、永不收敛。
+ * 5. **翻页后新卡全用兜底** —— 观察者挂上**之前**已插入的那批永远不会被报告。
+ *    守法 = 每次重测都**重新遍历当前子节点并重新 observe**（`observe` 对同一元素幂等），
+ *    且 `data` 变化后 `nextTick` 立刻补跑一次。
+ */
+export declare const useDataViewMasonry: (options: UseDataViewMasonryOptions) => UseDataViewMasonryReturn;

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

@@ -1,4 +1,4 @@
-import { ComponentPublicInstance } from 'vue';
+import { CSSProperties, ComponentPublicInstance } from 'vue';
 import { BadgeKeyInput } from './use-badge';
 type __VLS_Props = {
     /**
@@ -83,7 +83,7 @@ declare function __VLS_template(): {
                 value: string | number;
                 max: number;
                 showZero: boolean;
-                badgeStyle: string | false | import('vue').CSSProperties | import('vue').StyleValue[] | null;
+                badgeStyle: string | false | CSSProperties | import('vue').StyleValue[] | null;
             }, {}, string, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, import('vue').ComponentProvideOptions> & {
                 beforeCreate?: (() => void) | (() => void)[];
                 created?: (() => void) | (() => void)[];
@@ -110,7 +110,7 @@ declare function __VLS_template(): {
             value: string | number;
             max: number;
             showZero: boolean;
-            badgeStyle: string | false | import('vue').CSSProperties | import('vue').StyleValue[] | null;
+            badgeStyle: string | false | CSSProperties | import('vue').StyleValue[] | null;
         }> & Omit<Readonly<import('element-plus').BadgeProps> & Readonly<{}>, "offset" | "type" | "value" | "max" | "content" | "showZero" | "badgeStyle"> & {
             content: string;
         } & {} & import('vue').ComponentCustomProperties & {} & {
@@ -162,7 +162,7 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
             value: string | number;
             max: number;
             showZero: boolean;
-            badgeStyle: string | false | import('vue').CSSProperties | import('vue').StyleValue[] | null;
+            badgeStyle: string | false | CSSProperties | import('vue').StyleValue[] | null;
         }, {}, string, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, import('vue').ComponentProvideOptions> & {
             beforeCreate?: (() => void) | (() => void)[];
             created?: (() => void) | (() => void)[];
@@ -189,7 +189,7 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
         value: string | number;
         max: number;
         showZero: boolean;
-        badgeStyle: string | false | import('vue').CSSProperties | import('vue').StyleValue[] | null;
+        badgeStyle: string | false | CSSProperties | import('vue').StyleValue[] | null;
     }> & Omit<Readonly<import('element-plus').BadgeProps> & Readonly<{}>, "offset" | "type" | "value" | "max" | "content" | "showZero" | "badgeStyle"> & {
         content: string;
     } & {} & import('vue').ComponentCustomProperties & {} & {

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

@@ -6,6 +6,7 @@ declare function __VLS_template(): {
         default?(_: {
             viewportHeight: number;
         }): any;
+        footer?(_: {}): any;
     };
     refs: {};
     rootEl: any;

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

@@ -36,6 +36,12 @@ export interface BadgeResolved {
     icon?: Component;
     /** 完整文案——图标档的悬浮气泡用它把语义补回来 */
     label?: string;
+    /**
+     * 图标缩放（逐档可选，1 = 原尺寸）。
+     * 🔴 [MUST] 留在**预设的逐档字段**里，[MUST NOT] 提成全局常量或只给某一档打补丁 ——
+     * 七档全图标化之后，后续还会有别的档需要同样处理（甲方 2026-09-18 明示）。
+     */
+    iconScale?: number;
     /**
      * 纯锚点档（`kind: "anchor"`）：角标**不显示**，但 DOM 挂点照常渲染。
      *

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

@@ -31,9 +31,27 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     attrs: any;
     slots: Readonly<{
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /**
+         * 详情区**内部底边**（透到内置 `ViewLayout` 的 `#bottom`）：`refine` 开时钉在底、
+         * 不随内容滚 —— 放「提交 / 审核这一条」的固定操作条。scope 与 `#detail` 完全一致。
+         *
+         * 🔴 **前提是传了 `detailApi`**：本槽透到的是内置 `ViewLayout`，不传 `detailApi` 就没有
+         * 那个容器 ⇒ 本槽无落点（与 `viewLayoutProps` 同一条边界）。详情数据业务自持时，
+         * 底部条自己写在 `#detail` 末尾。
+         */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
     }> & {
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /**
+         * 详情区**内部底边**（透到内置 `ViewLayout` 的 `#bottom`）：`refine` 开时钉在底、
+         * 不随内容滚 —— 放「提交 / 审核这一条」的固定操作条。scope 与 `#detail` 完全一致。
+         *
+         * 🔴 **前提是传了 `detailApi`**：本槽透到的是内置 `ViewLayout`，不传 `detailApi` 就没有
+         * 那个容器 ⇒ 本槽无落点（与 `viewLayoutProps` 同一条边界）。详情数据业务自持时，
+         * 底部条自己写在 `#detail` 末尾。
+         */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
     };
     emit: {};

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

@@ -13,6 +13,16 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     slots: Readonly<{
         list?: (scope: AppPageListDetailListScope<T>) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /**
+         * 详情区**内部底边** —— 逐层透到内置 `ViewLayout` 的 `#bottom`：
+         * split 档钉在详情区底 / sheet 档钉在抽屉底，内容再长也不滚走。放「提交 / 审核**这一条**」
+         * 的固定操作条，scope 与 `#detail` 完全一致（含 `id` / `record` / 导航句柄）。
+         *
+         * 🔴 与下面的 `#bottom` **同名不同物**：那个挂在 `AppPage` 上、是**页面级**四向悬浮槽
+         * （覆盖整页底边，列表也在它上方）。判据：对「当前这一条」的操作放本槽，对整页的放 `#bottom`。
+         * 前提是传了 `detailApi`（本槽透到的是内置 `ViewLayout`，没有它就没有那个容器）。
+         */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;
@@ -20,6 +30,16 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     }> & {
         list?: (scope: AppPageListDetailListScope<T>) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /**
+         * 详情区**内部底边** —— 逐层透到内置 `ViewLayout` 的 `#bottom`：
+         * split 档钉在详情区底 / sheet 档钉在抽屉底，内容再长也不滚走。放「提交 / 审核**这一条**」
+         * 的固定操作条，scope 与 `#detail` 完全一致（含 `id` / `record` / 导航句柄）。
+         *
+         * 🔴 与下面的 `#bottom` **同名不同物**：那个挂在 `AppPage` 上、是**页面级**四向悬浮槽
+         * （覆盖整页底边，列表也在它上方）。判据：对「当前这一条」的操作放本槽，对整页的放 `#bottom`。
+         * 前提是传了 `detailApi`（本槽透到的是内置 `ViewLayout`，没有它就没有那个容器）。
+         */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;

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

@@ -19,6 +19,8 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     slots: Readonly<{
         list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /** 详情区内部底边（透到 `AppPageDetail` → `ViewLayout#bottom`）；scope 同 `#detail` */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;
@@ -26,6 +28,8 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     }> & {
         list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /** 详情区内部底边（透到 `AppPageDetail` → `ViewLayout#bottom`）；scope 同 `#detail` */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;

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

@@ -22,6 +22,8 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     slots: Readonly<{
         list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /** 详情区内部底边（透到 `AppPageDetail` → `ViewLayout#bottom`）；scope 同 `#detail` */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;
@@ -29,6 +31,8 @@ declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: No
     }> & {
         list?: (scope: Omit<AppPageListDetailListScope<T>, "resolvedMode">) => unknown;
         detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        /** 详情区内部底边（透到 `AppPageDetail` → `ViewLayout#bottom`）；scope 同 `#detail` */
+        detailBottom?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
         empty?: (scope: AppPageListDetailEmptyScope) => unknown;
         top?: () => unknown;
         bottom?: () => unknown;

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

@@ -200,6 +200,14 @@ F extends Record<string, any>> {
      * 暗色下二次成面会凹）；显式传值恒优先。
      */
     surface?: boolean;
+    /**
+     * **项自己已经成卡**（面与面不叠，p4wrtn）。为真时容器**只撤面色、不撤呼吸与圆角** ——
+     * 呼吸计入高度账（与可用高扣减同源），撤了会连带改 refine 的 reserve。
+     *
+     * 🔴 判据 [MUST NOT] 收窄成「`card === true`」：`InfiniteListView` 没有 `card`
+     * （卡由消费方自画），那样写会整条漏掉它。
+     */
+    itemCard?: boolean;
     /** 展示分页器 */
     showPager?: boolean;
     /**

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

@@ -19,6 +19,21 @@ declare const _default: <P extends Record<string, any> = Record<string, any>, R
             data: R | undefined;
             loading: boolean;
         }) => VNode[];
+        /**
+         * 底部区插槽；不传即完全不渲染（[MUST NOT] 留空盒占 reserve）。
+         * - `refine` 开 → 进 `HeightProvider` 的 `#footer` 槽：**固定在底部**，量高计入 reserve；
+         * - `refine` 关 → **平铺**在内容之后，按自身尺寸排布。
+         * scope = `{ data, loading, fetchSeq }`（三者都是本组件拉取的产物，setup 里取不到，
+         * [MUST] 由 scope 下发）。比 `#header` 多一个 `fetchSeq`：本槽是**放操作条**的地方，
+         * 提交后常要判「详情真的重拉成功了」（失败不递增，[MUST NOT] 用 `loading` 的
+         * `true→false` 代替）；也让 `AppPageListDetailLayout` 的 `#detailBottom` 能原样复用
+         * `#detail` 那份 scope，[MUST NOT] 为凑类型编一个恒 0 的假 `fetchSeq`。
+         */
+        bottom?: (scope: {
+            data: R | undefined;
+            loading: boolean;
+            fetchSeq: number;
+        }) => VNode[];
     }> & {
         default: (scope: ViewLayoutScope<R>) => VNode[];
         /**
@@ -30,6 +45,21 @@ declare const _default: <P extends Record<string, any> = Record<string, any>, R
             data: R | undefined;
             loading: boolean;
         }) => VNode[];
+        /**
+         * 底部区插槽；不传即完全不渲染（[MUST NOT] 留空盒占 reserve）。
+         * - `refine` 开 → 进 `HeightProvider` 的 `#footer` 槽：**固定在底部**，量高计入 reserve；
+         * - `refine` 关 → **平铺**在内容之后，按自身尺寸排布。
+         * scope = `{ data, loading, fetchSeq }`（三者都是本组件拉取的产物，setup 里取不到，
+         * [MUST] 由 scope 下发）。比 `#header` 多一个 `fetchSeq`：本槽是**放操作条**的地方，
+         * 提交后常要判「详情真的重拉成功了」（失败不递增，[MUST NOT] 用 `loading` 的
+         * `true→false` 代替）；也让 `AppPageListDetailLayout` 的 `#detailBottom` 能原样复用
+         * `#detail` 那份 scope，[MUST NOT] 为凑类型编一个恒 0 的假 `fetchSeq`。
+         */
+        bottom?: (scope: {
+            data: R | undefined;
+            loading: boolean;
+            fetchSeq: number;
+        }) => VNode[];
     };
     emit: (evt: "update:isAutoRefresh", value: boolean) => void;
 }>) => import('vue').VNode & {

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

@@ -87,6 +87,18 @@ export interface ViewLayoutProps<P = Record<string, any>, R = any> {
     parentChannel?: string;
     /** 内容区可用高兜底下限（px） */
     minHeight?: number;
+    /**
+     * 内容盒**撑满可用高**（默认 `false`，仅 `refine=true` 时有意义）。
+     *
+     * 关（默认）：内容盒只有 `max-height` 上限，内容多短盒子就多矮 —— 与本 prop 引入前逐字一致。
+     * 开：额外补一条同值 `min-height` ⇒ 上下界重合 = 定高。用途 = **让 `#bottom` 贴容器底**：
+     * 上限式下内容稀疏时底边只能跟在内容屁股后面浮在半空，定高后它恒落在预算下沿。
+     *
+     * 同名同义于 `TableMain.fillHeight`（那边是让分页器被顶到容器底），[MUST NOT] 另造名字。
+     * ⚠️ 代价是内容短时盒内留白 —— 这是定高的一体两面，故设计成 **opt-in**：
+     * [MUST NOT] 改成默认开 / 改写 `max-height` 为 `height`，那会波及所有 refine 页面。
+     */
+    fillHeight?: boolean;
     /** 是否显示自动刷新开关（默认 true） */
     showAutoRefresh?: boolean;
     /** 是否显示手动刷新按钮（默认 true） */

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

@@ -3,6 +3,16 @@ import { ComputedRef } from 'vue';
 export interface UseSurfaceReturn {
     /** 最终是否成面（显式 prop > 上下文推导 > 默认 true） */
     surfaceActive: ComputedRef<boolean>;
+    /**
+     * 是否**铺面色**（= 成面 且 项自己没成卡）。
+     *
+     * 🔴 **面与面不叠**（p4wrtn）：项自带卡片时容器再铺一层同色面，gap 漏出的就是与卡片
+     * **同一个色**，视觉上「一整片白 + 若干 1px 细框」，卡片不成其为卡片（实测两处
+     * `backgroundColor` 完全相同）。故项成卡时**只撤色、不撤呼吸** ——
+     * 🔴 [MUST NOT] 连 `surfacePad` 一起撤：呼吸计入高度账（与可用高扣减同源），
+     * 撤了会连带改 refine 的 reserve、整页溢出。
+     */
+    surfaceBgActive: ComputedRef<boolean>;
     /** 卡内呼吸数值（px）；关面时 0。样式与高度账**共用此一处** */
     surfacePad: ComputedRef<number>;
     /** 呼吸的 px 串（供 scoped CSS `v-bind`），与 {@link UseSurfaceReturn.surfacePad} 同源 */
@@ -31,4 +41,5 @@ export interface UseSurfaceReturn {
  */
 export declare const useSurface: <P extends {
     surface?: boolean;
+    itemCard?: boolean;
 }>(getProps: () => P) => UseSurfaceReturn;

package/types/index.d.ts

@@ -3,7 +3,6 @@ export { InfiniteListView, DataGridView } from './components/data-view';
 export type { DataGridViewInstance, DataGridViewPageInfo, DataGridViewProps, InfiniteListViewConfig, InfiniteListViewInstance, InfiniteListViewProps, } from './components/data-view';
 export * from './components/menu';
 export * from './components/display';
-export * from './components/icon';
 export * from './components/misc';
 export * from './components/modal';
 export * from './components/table';

package/types/injectInfo.json.d.ts

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

package/es/components/icon/IconHammer.vue.mjs

@@ -1,26 +0,0 @@
-import { defineComponent, openBlock, createElementBlock, createElementVNode } from "vue";
-const _hoisted_1 = {
-  class: "dc-icon-hammer icon-hammer",
-  viewBox: "0 0 16 16",
-  width: "1em",
-  height: "1em",
-  xmlns: "http://www.w3.org/2000/svg",
-  "aria-hidden": "true",
-  focusable: "false"
-};
-const _sfc_main = /* @__PURE__ */ defineComponent({
-  __name: "IconHammer",
-  setup(__props) {
-    return (_ctx, _cache) => {
-      return openBlock(), createElementBlock("svg", _hoisted_1, [..._cache[0] || (_cache[0] = [
-        createElementVNode("path", {
-          fill: "currentColor",
-          d: "M9.972 2.508a.5.5 0 0 0-.16-.556l-.178-.129a5 5 0 0 0-2.076-.783C6.215.862 4.504 1.229 2.84 3.133H1.786a.5.5 0 0 0-.354.147L.146 4.567a.5.5 0 0 0 0 .706l2.571 2.579a.5.5 0 0 0 .708 0l1.286-1.29a.5.5 0 0 0 .146-.353V5.57l8.387 8.873A.5.5 0 0 0 14 14.5l1.5-1.5a.5.5 0 0 0 .017-.689l-9.129-8.63c.747-.456 1.772-.839 3.112-.839a.5.5 0 0 0 .472-.334"
-        }, null, -1)
-      ])]);
-    };
-  }
-});
-export {
-  _sfc_main as default
-};

package/es/components/icon/IconHammer.vue2.mjs

@@ -1,4 +0,0 @@
-import _sfc_main from "./IconHammer.vue.mjs";
-export {
-  _sfc_main as default
-};

package/src/components/icon/README.md

@@ -1,38 +0,0 @@
-# components/icon — 图标族
-
-core 自带的图标组件族。**只收 element-plus 图标集缺失、且语义上非它不可的那几个**——
-[MUST NOT] 把 EP 已有的图标在这里再画一遍（那是纯重复，且两套观感会打架）。
-
-## 准入判据
-
-新增一个图标前 [MUST] 先答这两问：
-
-1. **EP 图标集里真的没有吗？** 全量清单见 `@element-plus/icons-vue`。有就直接用 EP 的。
-2. **换一个近似的 EP 图标真的不行吗？** 「近似但会被读错」才算不行（如 `Tools` 被读成设置），
-   「不够好看」不算。
-
-## 优先取开源图标集的形，[MUST NOT] 手画
-
-小尺寸图标的辨识度高度依赖剪影，手画的几何形在 12px 下几乎必然糊（实测：手画的轴对齐
-T 形锤被甲方判「太丑」，换成斜置羊角锤即可读）。故 [MUST] 先从成熟开源集（Bootstrap Icons /
-Lucide / Material Symbols 等，许可证需 MIT / ISC / Apache-2.0 一类）取被大量验证过的形，
-**只抄单条 path、[MUST NOT] 引整包依赖**（我们一次只要一个图标）。
-
-[MUST] 在组件注释里写明**来源 + 许可证 + 版权行**。风格上优先取 **fill 实心**版本——
-EP 图标是实心的，描边版（如 Lucide）在 12px 下偏细、与 EP 混排会打架。
-
-## 写作约定
-
-- **颜色 [MUST] 用 `fill="currentColor"`**：继承父级 `color`，天然随主题风格 / 亮暗 / 语义色档走。
-  [MUST NOT] 写死色值、[MUST NOT] 自造 CSS 变量（规则 14）。
-- **尺寸 [MUST] 用 `width/height="1em"`**：外面套 `ElIcon` 调 `font-size` 即可缩放，
-  [MUST NOT] 写死 px。`viewBox` **随图标源**，不强求与 EP 的 1024 一致——渲染尺寸由 1em 决定，
-  换算坐标只会徒增手抄出错的风险。
-- **根元素 [MUST] 带 `dc-<组件名-kebab>` 类**（规则 17），与内部裸类并存。
-- `aria-hidden="true"` + `focusable="false"`：图标是装饰，语义由宿主（或悬浮气泡）承担。
-
-## 清单
-
-| 组件 | 用途 | 为什么不用 EP 的 |
-|---|---|---|
-| `IconHammer` | 施工 / 开发中（`bridge.badge` 的 `wip` 档） | EP 无锤子；最接近的 `Tools` 是扳手+齿轮，被读成「设置」。取自 Bootstrap Icons `hammer`（MIT） |

package/types/components/icon/IconHammer.vue.d.ts

@@ -1,2 +0,0 @@
-declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, SVGSVGElement>;
-export default _default;

package/types/components/icon/index.d.ts

@@ -1,7 +0,0 @@
-import { default as IconHammer } from './IconHammer.vue';
-export { 
-/**
- * 锤子图标（施工 / 开发中）。EP 图标集无锤子，最接近的 `Tools` 会被读成「设置」。
- * `currentColor` + `1em`：颜色随父级、尺寸随字号，套 `ElIcon` 即可控。
- */
-IconHammer, };