@done-coding/admin-core 0.17.1-alpha.0 → 0.18.1-alpha.0

package/types/components/app-layout/AppSidebar.vue.d.ts

@@ -1,6 +1,8 @@
 import { RouteMetaResolveRaw } from '../../types';
 type __VLS_Props = {
+    /** 整体不用管 AppLayout 控制 用在定位出去的子元素的显隐 */
     show: boolean;
+    /** 层级是否高于 header（#7.5 期；true 时 z-index 提升盖住 header） */
     aboveHeader?: boolean;
     menus: RouteMetaResolveRaw[];
     menuFlatList: RouteMetaResolveRaw[];

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

@@ -1,31 +1,79 @@
 import { CSSProperties } from 'vue';
+/** AppPage 四向悬浮插槽：内容矩形（app-body-shim 外框）四边 viewport inset（calc 字符串） */
 export interface AppPageRectInset {
     top: string;
     left: string;
     right: string;
     bottom: string;
 }
+/** AppPage 四区 fixed 样式集 */
 export interface AppPageSlotStyles {
     top: CSSProperties;
     bottom: CSSProperties;
     left: CSSProperties;
     right: CSSProperties;
 }
+/** AppPage 固定 chrome 四边内衬（px，窗口坐标）——`APP_PAGE_CONTENT_INSET` 的值形状 */
 export interface AppPageContentInset {
     top: number;
     bottom: number;
     left: number;
     right: number;
 }
+/** AppPage 四区量得尺寸（含 shim 边距；未渲染为 0），用于扣槽 / 让位 / inset 合成 */
 export interface AppPageSlotSizes {
     topH: number;
     bottomH: number;
     leftW: number;
     rightW: number;
 }
+/**
+ * 扣掉 top/bottom 槽后的内容视口可用高（纯函数，钳非负）。
+ *
+ * `useChannelViewportHeight` 消费方（ListPage / TableMain / TabsRefineFlow / TabsTile refine）兜底都取
+ * `BODY_CONTENT_VIEWPORT_HEIGHT`，而 AppBody 给的高不含 AppPage 四槽 → 有 top/bottom 槽时会多算、内容压槽。
+ * AppPage（四槽 owner）据此扣槽后**同键重 provide**，四家一次修好。左右槽只减宽、不影响高，故只扣 top/bottom；
+ * 扣减量与 shim padding 同式（见 {@link appPageSlotInset}）以与内容内缩一致。
+ */
 export declare function computeAppPageReducedViewportHeight(bodyViewportHeight: number, slotSizes: AppPageSlotSizes, shimPadding: number): number;
+/**
+ * 扣掉 left/right 槽后的内容视口可用宽（纯函数，钳非负）——「撑满且不出横向滚动条」的最大宽。
+ *
+ * `pageBoxWidth` 取 AppPage 自身盒宽（流内块级元素，宽度天然 = body 内容区宽、**已排除纵向滚动条**——
+ * [MUST NOT] 用 `calc(100vw − …)` 推：100vw 含滚动条宽，有纵向滚动条时按其撑满会横向溢出）。
+ * 扣减量与 {@link computeAppPageReducedViewportHeight} 同式（{@link appPageSlotInset}，与 shim padding 回写一致）。
+ */
 export declare function computeAppPageReducedViewportWidth(pageBoxWidth: number, slotSizes: AppPageSlotSizes, shimPadding: number): number;
+/**
+ * 合成「固定 chrome 四边内衬」（px, 窗口坐标，纯函数）= app 级 chrome inset + 对应悬浮槽（含 gap，仅槽存在时计）。
+ * 供 tile 等自然流 window 滚动定位不被固定 chrome 遮（`APP_PAGE_CONTENT_INSET`）。
+ *
+ * @param appInset app 级 chrome 四边 inset px（AppBody 的 `BODY_CONTENT_VIEWPORT_INSET`，store 纯数值算好）。
+ */
 export declare function computeAppPageContentInset(appInset: AppPageContentInset, slotSizes: AppPageSlotSizes, gap: number): AppPageContentInset;
+/** 四区 z-index（内容之上、远低于 el 弹窗 2000、不抢 app chrome 0/1/2；设计 §2.2 / REQ-08） */
 export declare const APP_PAGE_SLOT_Z_INDEX = 1;
+/**
+ * AppPage 四向悬浮插槽 fixed 几何（纯函数，design §2.2）。
+ *
+ * 四区贴「内容矩形」（app-body-shim 外框）四边：
+ * - top/bottom：给 `left`+`right` inset 通栏吃左右角；分别贴 `top` / `bottom` inset。
+ * - left/right：夹中缝，竖向用 `top`+`bottom` inset 定跨度——`top = rect.top + topH`
+ *   （让过 top 区）、`bottom = rect.bottom + bottomH`（让过 bottom 区）；top/bottom 区
+ *   未渲染时对应 H=0 即自动贴满。
+ * 全 viewport 坐标、scroll 不变；调用方传响应式快照即随 chrome 跟。
+ *
+ * @param topH/bottomH top/bottom 区量得高（含其 shim 边距；未渲染为 0），用于 left/right 让位。
+ */
 export declare function computeAppPageSlotStyles(rect: AppPageRectInset, topH: number, bottomH: number): AppPageSlotStyles;
+/**
+ * AppPage 四区内层 shim 的四边 padding（纯函数）。
+ *
+ * 朝 chrome 的外侧边留 `sp`（= app-body-shim 内边距，复刻原呼吸）、朝内容的内侧边留
+ * `gap`（AppPage 级控距）；left/right 的上下边为 0（竖向间隔由 top/bottom 区的 `gap` 边管）。
+ * `padding` 简写按 上/右/下/左。
+ *
+ * @param sp  app-body-shim 内边距（朝 chrome 侧呼吸）
+ * @param gap AppPage gap（朝内容侧间隔）
+ */
 export declare function computeAppPageSlotShimStyles(sp: number, gap: number): AppPageSlotStyles;

package/types/components/app-layout/keep-alive.d.ts

@@ -1,14 +1,31 @@
+/**
+ * AppBody depth-0 KeepAlive 缓存判据（内部工具，不入公共 barrel）。
+ * 只缓存 AppBody 实际渲染的「真叶子」（matched 链最深的 component-bearing 记录）且其 keepAlive 开；
+ * 渲染的是壳（更深处还有 component）则不缓存——根治嵌套组壳被 KeepAlive 误缓存的泄漏。
+ * 详见 spec 2026-07-16 组壳泄漏根治。
+ */
 interface KeepAliveMatchedLike {
     path: string;
     components?: Record<string, unknown> | null;
 }
 interface KeepAliveRouteLike {
+    /** resolved 完整路径（含 params，如 /detail/123） */
     path: string;
+    /** vue-router 合并后的 meta（叶子覆盖父）——keepAlive 判定沿用其合并语义 */
     meta?: {
         keepAlive?: boolean;
     };
     matched?: KeepAliveMatchedLike[];
 }
+/**
+ * 可进 KeepAlive = 渲染真叶子 且 keepAlive 开（读合并 meta，保留 vue-router「父默认、叶子覆盖」语义）。
+ * 壳（渲染的不是叶子）一律不缓存 —— 根治嵌套组壳泄漏。
+ */
 export declare const isKeepAliveRoute: (route: KeepAliveRouteLike) => boolean;
+/**
+ * 缓存 / 渲染 key：
+ * - 渲染叶子 → resolved `route.path`（按 params 隔离，如 /detail/123 ≠ /detail/456，沿用旧行为）；
+ * - 渲染壳 → 壳 record path（跨子路由稳定单实例，内嵌 RouterView 自行切子）。
+ */
 export declare const keepAliveRouteKey: (route: KeepAliveRouteLike) => string;
 export {};

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

@@ -2,31 +2,156 @@ import { Component, VNode } from 'vue';
 import { createAppStore, createUserStore } from '../../store';
 import { CoreBridge } from '../../bridge';
 import { RouteMetaResolveRaw } from '../../types';
+/**
+ * AppLayout 族 app store 消费契约（props/inject 切面）。
+ *
+ * 调用方通过 props 注入 store 实例，AppLayout 集中 provide，子组件
+ * （AppBody / AppHeader / AppSidebar / AppFooter）经 `APP_LAYOUT_APP_STORE_KEY`
+ * inject 自取——废除原 AppLayout → 子组件 `:style` / `:showBreadcrumb` props 透传链。
+ *
+ * 类型由 `createAppStore` 工厂 ReturnType 推导（store 实例完整类型），自动跟随
+ * 工厂演化、零手维护字段清单——放弃 narrow 换取 0 维护成本。`UserInfo` /
+ * `LoginParams` 泛型未显式实例化时走工厂 default `Record<string, any>` /
+ * `unknown`（D-a 原则——core 不锁 UserInfo 具体 shape）。
+ *
+ * app-layout 族下沉 core 后此 slice 仍是 props/inject 契约——core 端无法直接
+ * `useAppStore()`，必须由业务侧通过 props 注入。
+ */
 export type AppLayoutAppStoreSlice<UserInfo = Record<string, any>> = ReturnType<ReturnType<typeof createAppStore<UserInfo>>>;
+/**
+ * AppLayout 族 user store 消费契约（props/inject 切面）。
+ *
+ * 调用方通过 props 注入，AppLayout 集中 provide，子组件（AppHeader）经
+ * `APP_LAYOUT_USER_STORE_KEY` inject 自取。
+ *
+ * 类型由 `createUserStore` 工厂 ReturnType 推导。`UserInfo` 走工厂 default
+ * `Record<string, any>`（D-a 原则——core 不锁 UserInfo 具体 shape），业务侧
+ * （如 AppLayout watermark content / AppHeader user dropdown）按需 cast 为本应用
+ * 具体 shape。
+ */
 export type AppLayoutUserStoreSlice<UserInfo = Record<string, any>> = ReturnType<ReturnType<typeof createUserStore<UserInfo>>>;
+/**
+ * AppLayout 族 bridge 消费契约（props/inject 切面，#7.6 期挂载）。
+ *
+ * AppLayout 通过 `props.bridge` 注入 + `provide(APP_LAYOUT_BRIDGE_KEY, ...)`，
+ * 子组件（AppBody / AppHeader / AppSidebar / AppLayout 自身菜单派生）inject 自取——
+ * 与 `AppLayoutAppStoreSlice` / `AppLayoutUserStoreSlice` 完全对称范式。
+ *
+ * 仅暴露 layout 子组件实际读取的字段：12 readonly 配置属性 + 2 派生方法
+ * （getRoutes / generateRouteMetaRawTree）。loginApi / refreshToken 等 auth
+ * 面不通过本 slice 暴露（业务侧通过 appBridge 直读）。
+ */
 export type AppLayoutBridgeSlice = Pick<CoreBridge, "APP_BASE_INFO" | "APP_ENV_INFO" | "APP_CACHE_CONFIG" | "APP_LAYOUT_HEADER_CONFIG" | "APP_LAYOUT_FOOTER_CONFIG" | "APP_LAYOUT_SIDEBAR_CONFIG" | "APP_LAYOUT_ASIDE_CONFIG" | "APP_LAYOUT_BREADCRUMB_CONFIG" | "APP_LAYOUT_BODY_CONFIG" | "APP_LAYOUT_VIEWPORT_CONFIG" | "APP_LAYOUT_GAP_CONFIG" | "APP_LAYOUT_CONFIG" | "APP_ROUTER_META_DEFAULT_CONFIG" | "APP_ROUTER_CONFIG" | "APP_ROUTER_PATHS_CONFIG" | "APP_THEME_CONFIG" | "theme" | "themeStyle" | "themeMode" | "themeIsDark" | "themeLayout" | "themeDensity" | "themeMotion" | "themeColors" | "showThemeStyleSwitcher" | "getRoutes" | "generateRouteMetaRawTree">;
+/**
+ * 内容锚 slot 名集（焊缝契约 ③，纯功能语义；P1' 去布局化重做）。
+ *
+ * 业务 slot 为**内容锚**（描述「是什么功能」非「放哪」）——同一份业务原料，落位权归
+ * AppShell：不同 AppShell 把同一内容锚渲染到不同区域 = 不同布局人格。AppLayout 用
+ * `v-for` 整组动态透传给 AppShell（[MUST NOT] 在 AppLayout 写死任一内容锚落位）。
+ *
+ * - `brand`：品牌 / logo / 应用名入口
+ * - `userEntry`：用户下拉 / 登录按钮 / 用户态入口
+ * - `settings`：设置 / 配置入口
+ * - `themeSwitcher`：主题（风格 + 亮暗）切换器（scope 传内置 AppTheme 默认内容）
+ * - `aside`（P4 加）：右侧补充区内容中转锚 → 喂进 `AppAside` 默认 slot。
+ *   **与 sidebar 同构：全局单实例 + 应用层切入**——App.vue 填一次 `#aside`（同
+ *   `#brand` / `#userEntry` 范式），`showAside=true`（路由 `meta.layout.aside` 派生）
+ *   的页面都显示这同一份；宽度 / 位置 / 容器归主题（`preset.layout.aside.width` +
+ *   AppAside 积木）。per-page 内容随页变化 = **业务页面开发自决**（如自往 `#aside` 塞
+ *   `<RouterView name="aside" />`），**不属本布局体系范围**，core 不建 per-route 投递机制。
+ *
+ * 去 `nav*` 位置锚：菜单走数据流（`menuFlatList`），渲染成何种导航由 AppShell 自由
+ * （复用导出积木 `MenuTree` / `AppSidebar` 或自 DIY）。
+ * 内置默认 AppShell 的落位映射（1:1 镜像经典布局）见 `AppShell.vue` 注释。
+ */
 export type AppShellContentAnchor = "brand" | "userEntry" | "settings" | "themeSwitcher" | "aside";
+/**
+ * AppShell 扁平注入面 props（焊缝契约 ①-props）。
+ *
+ * 原分喂 AppHeader / AppSidebar 的 props **扁平合并为一份**，三处零件由 AppShell
+ * 内部自行分发。样式 / themeColors / 折叠态 / changeSidebarCollapseStatus 走
+ * **inject**（`APP_LAYOUT_APP_STORE_KEY` / `APP_LAYOUT_BRIDGE_KEY`，AppLayout 已 provide），
+ * 不进 props——AppShell setup 内自取（同内置 AppHeader/AppSidebar 既有范式）。
+ */
 export interface AppShellProps {
+    /** 完整菜单树（经权限 / menuShow 过滤、排序） */
     menus: RouteMetaResolveRaw[];
+    /** 扁平菜单列表（喂 AppBody / 子零件高度链 + 路由匹配） */
     menuFlatList: RouteMetaResolveRaw[];
+    /** sidebar 区菜单（分流后） */
     sidebarMenus: RouteMetaResolveRaw[];
+    /** header 区菜单（分流后；extractLevel1ToHeader=true 时为 1 级模块） */
     headerMenus: RouteMetaResolveRaw[];
+    /** 当前聚焦菜单 */
     activeMenu?: RouteMetaResolveRaw;
+    /** 当前聚焦模块菜单（header 模块高亮） */
     activeModuleMenu?: RouteMetaResolveRaw;
+    /**
+     * 是否展示 header（路由 meta.layout 基线意图）。AppShell 自解读：决定喂给哪个区域的
+     * `show`（内置默认 shell 喂 AppHeader）。
+     */
     showHeader: boolean;
+    /**
+     * 是否展示 sidebar（路由 meta.layout 基线意图）。语义同 `showHeader`——
+     * 内置默认 shell 喂 AppSidebar 的 `show`。
+     */
     showSidebar: boolean;
+    /**
+     * 是否展示右侧 aside 补充区（路由 meta.layout 基线意图，additive，默认 false）。
+     * 内置经典 shell 不渲染 aside（经典无右栏）；自定义 shell 据此渲染右侧区。
+     */
     showAside: boolean;
+    /**
+     * sidebar 层级是否高于 header（透传内置 AppSidebar.aboveHeader）。
+     * 默认 false；自定义 shell 可忽略。
+     */
     sidebarAboveHeader: boolean;
 }
+/**
+ * AppShell emits（焊缝契约 ①-emits）。
+ *
+ * 当前空——作为统一预留通道。后续 AppShell 需向 AppLayout 反向通知（如布局态变更）
+ * 时在此扩展，[MUST NOT] 自造平行回调 props。
+ */
 export interface AppShellEmits {
 }
+/**
+ * AppShell 默认 scoped slot 作用域参数（焊缝契约 ①-slots，default slot）。
+ *
+ * AppShell 在「主体该出现的位置」吐出本作用域 → AppLayout 接住后：
+ * 用 `Footer` 组件引用组装进 `AppBody #footer`，并把 AppBody（持有 menuFlatList、
+ * 守高度链）塞回该默认 slot 位置。这绕过「父传子 slot 是父作用域 vnode、子无法
+ * 反向注入子 slot」的 Vue 约束（footer 走「AppShell 吐组件引用 → AppLayout 组装」）。
+ */
 export interface AppShellDefaultSlotScope {
+    /**
+     * AppShell 选定的 footer 组件引用（默认 = `componentFallBack.AppFooter`；
+     * 自定义 shell 可吐自定义 footer）。AppLayout 用 `<component :is="Footer" />`
+     * 渲染进 `AppBody #footer`。
+     */
     Footer: Component;
 }
+/**
+ * 功能锚 scoped slot 作用域参数（焊缝契约 ①-slots，内容锚 scope）。
+ *
+ * AppShell 经各功能锚 slot 的 scope 传「内置默认内容组件引用」给布局，布局可用可无视：
+ * - `themeSwitcher` 锚 `Default` = 内置 `AppTheme`（保证主题切换功能以某形式可达；布局
+ *   无视默认内容时须自供等效切换 UI，否则违约——见声明驱动测试纪律）。
+ * - `brand` / `userEntry` / `settings` / `aside` 锚 `Default` = `undefined`（不预设未遇到的需求，随时可扩）。
+ */
 export interface AppShellAnchorScope {
+    /** 该功能锚的内置默认内容组件引用（仅 themeSwitcher 提供，markRaw）；其余 undefined */
     Default?: Component;
 }
+/**
+ * AppShell slots 契约（焊缝契约 ①-slots 全集）。
+ *
+ * - `default`：作用域 = {@link AppShellDefaultSlotScope}，AppLayout 在此塞 AppBody（持高度链）。
+ * - 各内容锚（{@link AppShellContentAnchor}）：scoped slot（scope = {@link AppShellAnchorScope}），
+ *   AppLayout `v-for` 整组转发业务侧填的同名 slot；AppShell 自行决定每个内容锚落到哪个区域。
+ */
 export type AppShellSlots = {
+    /** 默认 slot：AppLayout 在此塞 AppBody（scoped，拿 Footer 组件引用组装 #footer） */
     default: (scope: AppShellDefaultSlotScope) => VNode[];
 } & {
     [K in AppShellContentAnchor]?: (scope: AppShellAnchorScope) => VNode[];

package/types/components/app-layout/viewport.d.ts

@@ -1,2 +1,30 @@
+/**
+ * viewport 镂空 SVG 装饰边框基础设施常量（焊缝契约 ⑤，P1 冻结）。
+ *
+ * 把 viewport 那圈留白（`APP_LAYOUT_VIEWPORT_CONFIG` 四边 padding 让出的边距）
+ * 从消极留白变积极画布：AppShell 可 teleport 一个铺满视口的大 SVG 到 body、
+ * 镂空出内容区，在边框圈里画渐变 / 动画 / 填充色。
+ *
+ * - **叠加非替代**：现有 `useCoreViewportApply` 的 padding 留白机制保留；SVG 只在
+ *   让出的那圈里画装饰。镂空矩形尺寸 = AppShell 经 inject 读 `APP_LAYOUT_VIEWPORT_CONFIG`
+ *   四边算（响应式）。
+ * - **teleport + pointer-events:none**：teleport 到 body（避开层叠上下文 / overflow
+ *   裁切），`pointer-events: none` 绝不挡交互。
+ *
+ * z-index 双档（core 导出常量，AppShell / 主题资产按需选档）：
+ * 业务自造 z-index 字面量会与 el 弹窗（2000 起动态自增）打架——故 core 冻结两档安全值。
+ */
+/**
+ * viewport 装饰 z-index——**弹窗下档**（默认，绝对安全）。
+ *
+ * `800 < 2000`（el 弹窗 base z-index）→ 装饰永远在弹窗下，绝不盖住 dialog / message。
+ * 大多数边框装饰用此档（装饰是背景氛围，不该盖业务弹窗）。
+ */
 export declare const CORE_VIEWPORT_DECOR_ZINDEX_BELOW = 800;
+/**
+ * viewport 装饰 z-index——**弹窗上档**（盖住弹窗，慎用）。
+ *
+ * el z-index 自 2000 动态自增（每开一层 +N），`10000` 实践绝对安全盖住弹窗档。
+ * 仅当装饰需覆盖弹窗（如全屏切换动画遮罩 / 边框需压住一切）时用此档。
+ */
 export declare const CORE_VIEWPORT_DECOR_ZINDEX_ABOVE = 10000;

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

@@ -1,4 +1,12 @@
+/**
+ * DataListView 单项容器
+ * ---
+ * 仅承载选中态 class 钩子 + 项内容插槽，由 DataListView 内部 v-for 使用。
+ * [MUST NOT] 写死视觉样式（卡片阴影/圆角等归消费方）；
+ * [MUST NOT] 内置选中状态机（状态机在 DataListView）。
+ */
 type __VLS_Props = {
+    /** 当前项是否选中（由 DataListView 传入） */
     selected: boolean;
 };
 declare function __VLS_template(): {

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

@@ -1,4 +1,8 @@
 import { default as DataListView } from './DataListView.vue';
 import { default as DataListViewItem } from './DataListViewItem.vue';
 export * from './types';
+/**
+ * data-view 是 table 的内部衍生品：仅供 TableMain 内部 import，
+ * [MUST NOT] 对外导出 / 全局注册 / 提供 install 插件（不进 core 顶层 export）。
+ */
 export { DataListView, DataListViewItem };

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

@@ -1,24 +1,66 @@
 import { Component } from 'vue';
 import { ElTableColumnProps, TableColumnDefaultScope, TableInstance } from '../table';
+/**
+ * DataListView 字段渲染作用域
+ * ---
+ * 喂给 FieldColumn.render 的作用域；布局无关，仅含行数据与索引。
+ */
 export interface DataListViewRenderScope<T extends Record<string, any> = Record<string, any>> {
+    /** 当前行数据 */
     row: T;
+    /** 当前行索引 */
     index: number;
 }
+/**
+ * DataListView 列配置（table 的内部衍生品：从 ElTableColumnProps Pick 复用子集，
+ * ElTableColumnProps 零触碰；本类型不对外导出，仅 table 内部消费）
+ */
 export type DataViewColumn<T extends Record<string, any> = Record<string, any>> = Partial<Pick<ElTableColumnProps<T, any>, "prop" | "label" | "type" | "render">>;
+/**
+ * DataListView props
+ * ---
+ * 布局无关的数据项容器：分页数据由外部传入，一行几个由消费方在 #item
+ * 外层用 CSS 决定，本组件不内置任何列数 / 布局。
+ */
 export interface DataListViewProps<T extends Record<string, any>, F extends Record<string, any>> {
+    /** 当前页数据（外部传入，组件不持有请求 / 分页逻辑） */
     data: T[];
+    /** 行唯一键：行数据键名 或 取键函数（内部统一 String 化） */
     rowKey: Extract<keyof T, string> | ((row: T) => string);
+    /** 列配置，内部归一为 fieldComponentMap 喂 #item */
     columns: DataViewColumn<T>[];
+    /** 最大高度；传入时容器超出内容出现垂直滚动条，缺省不限高 */
     maxHeight?: number;
+    /** 最小高度；传入时容器撑满至此高（配合 TableMain fillHeight 顶分页器到底），缺省不设 */
     minHeight?: number;
+    /** 是否启用选中能力，缺省关闭 */
     selectable?: boolean;
+    /** 获取column 列 上下文 render参数 */
     getRenderCtxParams: () => Pick<TableColumnDefaultScope<T, F>, "injectInfo" | "exposeInfo">;
 }
+/**
+ * DataListView 对外实例方法 对齐 elTableInstance
+ * -----
+ * 未实现的会抛错
+ */
 export type DataListViewInstance = TableInstance;
+/**
+ * #item 作用域插槽 props
+ * ---
+ * fieldComponentMap：列 key（prop / $type_index / $type_selection）→ 稳定字段组件
+ * （标识跨渲染稳定，对齐 FormItem 范式）。消费方：
+ * `<component :is="fieldComponentMap['x']" :row="row" :index="index"
+ *   :selected="selected" :toggle-select="toggleSelect" />`（数据走 props）。
+ */
 export interface DataListViewItemScope<T extends Record<string, any> = Record<string, any>> {
+    /** 列 key → 稳定字段组件（props: row/index/selected/toggleSelect） */
     fieldComponentMap: Record<string, Component>;
+    /** 当前行数据 */
     row: T;
+    /** 当前行索引 */
     index: number;
+    /** 当前行是否选中 */
     selected: boolean;
+    /** 翻转当前行选中态 */
     toggleSelect: () => void;
 }

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

@@ -1,2 +1,5 @@
 import { DataListViewInstance } from './types';
+/**
+ * 创建 DataListView 实例
+ */
 export declare const createDataListViewInstance: (mainMethods: Pick<DataListViewInstance, "clearSelection" | "getSelectionRows" | "toggleRowSelection" | "toggleAllSelection" | "columns">) => DataListViewInstance;

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

@@ -1,7 +1,9 @@
 import { TabsHeaderVariant, TabsMainItem } from './types';
 type __VLS_Props = {
     tabs: TabsMainItem[];
+    /** 视觉嵌套层级,只控字号(1=16 / 2=14 / 3=12 / 4+=12,超 4 钳到 4) */
     level?: number;
+    /** 视觉风格变体;不传按 level 推导默认 */
     variant?: TabsHeaderVariant;
 };
 type __VLS_PublicProps = {

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

@@ -1,11 +1,13 @@
 import { VNode } from 'vue';
 import { TabsMainItem, TabsMainProps } from './types';
 type __VLS_Props = TabsMainProps;
+/** 内容插槽 #{key} 的 scope（TabPane 渲染时注入；key = tab.key） */
 interface TabsMainContentScope {
     tab?: TabsMainItem;
     active: boolean;
     viewportHeight?: number;
 }
+/** 标题插槽 #header-{key} 的 scope（中转 TabsHeader 的 #{key}） */
 interface TabsMainHeaderScope {
     tab: TabsMainItem;
     active: boolean;

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

@@ -5,6 +5,7 @@ interface TabsRefineFlowProps {
     channel?: string;
     parentChannel?: string;
     padding?: TabsMainPadding;
+    /** 精细化预留高度(px),从 viewportHeightFinal 中预扣(在 padding 扣减与 HeightProvider header reserve 扣减之外) */
     refineReduceHeight?: number;
 }
 declare function __VLS_template(): {