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

package/types/components/slot-layout/SlotLayoutTemplate.vue.d.ts

@@ -1,4 +1,19 @@
+/**
+ * 布局槽位模板：disabled 时透传（宿主消失、只渲染默认槽内容）；
+ * 否则以 tag 包裹并「透明转发全部插槽」（默认+具名+作用域）到宿主 tag。
+ *
+ * 用渲染函数而非模板：透明转发组件的自身 slots 类型天然递归
+ * （self.slots = 被转发的 self.slots），模板内 v-for $slots + <slot :name>
+ * 会触发 vue-tsc TS7022 自指推断；render 直接把 slots 对象整体喂给 h()，
+ * 绕开模板 slot 类型推断、转发也更彻底（含具名/作用域槽）。
+ */
 declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    /**
+     * 包裹宿主：原生标签名（"div"）/ 组件对象 / 函数式组件。
+     * 懒加载组件 [MUST] 先经 `defineAsyncComponent` 包裹再传——裸异步工厂
+     * `() => import('./X.vue')` 会被当函数式组件调用、不 resolve Promise（同
+     * `<component :is>` 原生语义，参 ModalShelf 同款约定）。
+     */
     tag: {
         type: () => any;
         default: string;
@@ -12,6 +27,12 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
 }> | import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
     [key: string]: any;
 }>[] | undefined, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    /**
+     * 包裹宿主：原生标签名（"div"）/ 组件对象 / 函数式组件。
+     * 懒加载组件 [MUST] 先经 `defineAsyncComponent` 包裹再传——裸异步工厂
+     * `() => import('./X.vue')` 会被当函数式组件调用、不 resolve Promise（同
+     * `<component :is>` 原生语义，参 ModalShelf 同款约定）。
+     */
     tag: {
         type: () => any;
         default: string;

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

@@ -1,6 +1,10 @@
 export interface SlotLayoutFlowAsideProps {
+    /** 侧栏所在侧 */
     type?: "left" | "right";
+    /** 主区与侧栏间距 */
     gap?: string;
+    /** 侧栏宽度 */
     asideWidth?: string;
+    /** 侧栏最大高度（超出滚动） */
     asideMaxHeight?: string;
 }

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

@@ -1,2 +1,10 @@
+/**
+ * table 族系约定 column key 常量（L1）。
+ *
+ * 仅作「标记字符串」供消费方在 columns 配置里固定填以被识别，不驱动任何渲染/行为。
+ * 命名空间 `TABLE_COLUMN_KEY_`（= 表格列的约定 key）+ 语义后缀，规则 9 合规。
+ */
+/** 操作列推荐 key（消费方在 columns 固定填以标记为操作列）。 */
 export declare const TABLE_COLUMN_KEY_OPERATE = "OPERATE";
+/** 选择列推荐 key（SELECTION 当前由 el-table `type:"selection"` 承载）。 */
 export declare const TABLE_COLUMN_KEY_SELECTION = "SELECTION";

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

@@ -5,53 +5,138 @@ import { ExportColumnConfig } from '../../utils';
 import { ExtractPropTypes, VNode } from 'vue';
 import { ActionBtnConfigItem } from '../display';
 import { AutoRefreshGroupProps } from '../misc';
+/** 表格实例 */
 export type TableInstance = Pick<ElTableInstance, "clearSelection" | "getSelectionRows" | "toggleRowSelection" | "toggleAllSelection" | "toggleRowExpansion" | "setCurrentRow" | "clearSort" | "clearFilter" | "doLayout" | "sort" | "scrollTo" | "setScrollTop" | "setScrollLeft" | "columns" | "updateKeyChildren">;
+/** 表格分页信息 */
 export interface TablePageInfo {
+    /** 每页数量 */
     pageSize: number;
+    /** 当前页码 */
     currentPage: number;
+    /** 数据总数（总记录数，非页数） */
     total: number;
 }
-export type TableApiParams<SQ extends Record<string, any> = Record<string, any>> = BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, SQ>;
+/**
+ * 表格请求参数
+ * ---
+ * 静态参数 SQ + KEY_CONFIG 推导出的 page.page / page.pageSize 嵌套
+ */
+export type TableApiParams<
+/** 静态参数 */
+SQ extends Record<string, any> = Record<string, any>> = BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, SQ>;
+/**
+ * 表格响应结果
+ * ---
+ * items 列表 + page.totalRecord 总数（仅 2 字段子集，不带 page.page / page.pageSize）
+ */
 export type TableApiResult<T extends Record<string, any> = Record<string, any>> = UnionToIntersection<DotToObject<typeof APP_API_LIST_MODEL_KEY_CONFIG.LIST_KEY, T[]> | DotToObject<typeof APP_API_LIST_MODEL_KEY_CONFIG.TOTAL_KEY, number>>;
 export interface TableMainInstance {
+    /** 如果关心是否结束（无论成功还是失败 甚至都未发起请求（比如某些状态机未满足）），那么可以await, 等待刷新调用给个结束  */
     refresh: (silent?: boolean) => Promise<unknown>;
+    /** 如果关心是否结束（无论成功还是失败 甚至都未发起请求（比如某些状态机未满足）），那么可以await, 等待刷新调用给个结束  */
     reload: (slice?: boolean) => Promise<unknown>;
     getTableInstance: () => TableInstance | undefined;
 }
+/** 导出类型 */
 export type ExportType = "selected" | "current" | "all";
-export interface TableExportContext<T extends Record<string, any> = Record<string, any>, SQ extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> {
+/** TableMain 传给 toolbar 的导出上下文 */
+export interface TableExportContext<T extends Record<string, any> = Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any> = Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> {
+    /** 可导出列 */
     columns: Pick<ElTableColumnProps<T, F>, "prop" | "label">[];
+    /** 选中行数据 */
     selectedList: T[];
+    /** 当前页数据 */
     currentPageList: T[];
+    /** 分页 API */
     api: (params: TableApiParams<SQ>) => Promise<TableApiResult<T>>;
+    /** 静态查询参数 */
     query?: SQ;
+    /** 当前数据总数 */
     total: number;
+    /** 是否包含 selection 列 */
     hasSelection: boolean;
 }
-export interface ToolbarButtonContext<T extends Record<string, any> = Record<string, any>, SQ extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> {
+/** toolbar 按钮渲染上下文 */
+export interface ToolbarButtonContext<T extends Record<string, any> = Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any> = Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> {
+    /** TableMain expose */
     tableExpose: TableMainInstance;
+    /** 表格是否加载中 */
     loading: boolean;
+    /** 导出上下文 */
     exportContext: TableExportContext<T, SQ, F>;
+    /** 当前选中行数据 */
     selectedList: T[];
+    /** 分页信息 */
     pagination: TablePageInfo;
 }
-export type ToolbarButtonConfig<T extends Record<string, any> = Record<string, any>, SQ extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> = ActionBtnConfigItem<ToolbarButtonContext<T, SQ, F>>;
-export interface TableToolbarPrivateProps<T extends Record<string, any> = Record<string, any>, SQ extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> {
+/**
+ * toolbar 额外按钮配置（BL-4 / 2026-05-26 重定义为 ActionBtnConfigItem 别名）
+ * ---
+ * 跨族迁移到 display/ActionBtnGroup 后,本类型沦为通用配置的 toolbar 特化别名;
+ * 字段集与 ActionBtnConfigItem 完全一致(key / actionBtnProps / props / label / render / show)。
+ * 旧的 VNode[] 返回函数字段已移除,render 三态(string | Component | functional)
+ * 对标 FormItem;升级路径见 MIGRATION.md BL-4 节。
+ */
+export type ToolbarButtonConfig<T extends Record<string, any> = Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any> = Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> = ActionBtnConfigItem<ToolbarButtonContext<T, SQ, F>>;
+/** toolbar (被TableMain) 内部提供的props */
+export interface TableToolbarPrivateProps<T extends Record<string, any> = Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any> = Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> {
+    /** TableMain expose */
     tableExpose: TableMainInstance;
+    /** 表格是否加载中 */
     loading: boolean;
+    /** 导出上下文 */
     exportContext: TableExportContext<T, SQ, F>;
+    /** 当前页码 */
     currentPage: number;
+    /** 每页行数 */
     pageSize: number;
+    /** 是否显示切换视图按钮，默认 false */
     showSwitchView?: boolean;
 }
-export interface TableToolbarProps<T extends Record<string, any> = Record<string, any>, SQ extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> extends TableToolbarPrivateProps<T, SQ, F>, Pick<AutoRefreshGroupProps, "showRefresh" | "showAutoRefresh"> {
+/** toolbar props */
+export interface TableToolbarProps<T extends Record<string, any> = Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any> = Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> extends TableToolbarPrivateProps<T, SQ, F>, Pick<AutoRefreshGroupProps, "showRefresh" | "showAutoRefresh"> {
+    /**
+     * 是否由前端导出，默认 true。
+     * - true：toolbar 内部调 fetchListAll + exportCSV 完成导出
+     * - false：走 exportFn 回调
+     */
     exportByFe?: boolean;
+    /** 导出方法。传入导出类型，返回 Promise。exportByFe 为 false 时必传 */
     exportFn?: (type: ExportType) => Promise<unknown>;
+    /** 导出列配置。不传则不显示导出按钮。支持 valueMap 自定义取值 */
     exportColumns?: ExportColumnConfig<T>[];
+    /** 左侧额外按钮 */
     leftExtraButtons?: ToolbarButtonConfig<T, SQ, F>[];
+    /** 右侧额外按钮 */
     rightExtraButtons?: ToolbarButtonConfig<T, SQ, F>[];
 }
-export type TableToolbarConfig<T extends Record<string, any> = Record<string, any>, SQ extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> = Omit<TableToolbarProps<T, SQ, F>, keyof TableToolbarPrivateProps<T, SQ, F>>;
+/** toolbar 可配置项（通过 TableMain 的 toolbar prop 传入） */
+export type TableToolbarConfig<T extends Record<string, any> = Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any> = Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> = Omit<TableToolbarProps<T, SQ, F>, keyof TableToolbarPrivateProps<T, SQ, F>>;
+/** 表格列默认作用域 */
 export interface TableColumnDefaultScope<T extends Record<string, any>, F extends Record<string, any>> {
     row: T;
     column: ElTableColumnProps<T, F>;
@@ -59,9 +144,11 @@ export interface TableColumnDefaultScope<T extends Record<string, any>, F extend
     injectInfo: F;
     exposeInfo: TableMainInstance;
 }
+/** 表格列组件props[$开头的属性vue报错] */
 export type TableColumnComponentProps<T extends Record<string, any>, F extends Record<string, any>> = Omit<TableColumnDefaultScope<T, F>, "$index"> & {
     _index: TableColumnDefaultScope<T, F>["$index"];
 };
+/** 表格列header作用域 */
 export interface TableColumnHeaderScope<T extends Record<string, any>, F extends Record<string, any>> {
     column: ElTableColumnProps<T, F>;
     $index: number;
@@ -69,7 +156,9 @@ export interface TableColumnHeaderScope<T extends Record<string, any>, F extends
     exposeInfo: TableMainInstance;
 }
 export type ExtractElTableColumnProps = ExtractPropTypes<typeof ETC>;
-export type ElTableColumnProps<T extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> = Omit<ExtractPropTypes<typeof ETC>, "prop" | "columnKey" | "type"> & Partial<{
+export type ElTableColumnProps<T extends Record<string, any> = Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> = Omit<ExtractPropTypes<typeof ETC>, "prop" | "columnKey" | "type"> & Partial<{
     prop: Exclude<Extract<keyof T, string>, "custom-view-item" | "item"> | `${Uppercase<string>}`;
     columnKey: ElTableColumnProps<T, F>["prop"];
     type: "default" | "selection" | "index" | "expand";
@@ -77,38 +166,80 @@ export type ElTableColumnProps<T extends Record<string, any> = Record<string, an
     align: "left" | "center" | "right";
     headerAlign: "left" | "center" | "right";
     filterPlacement: "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end";
+    /** 插槽render */
     render: string | Record<string, any> | ((props: TableColumnComponentProps<T, F>) => VNode);
+    /** 表头插槽render */
     headerRender: string | Record<string, any> | ((props: TableColumnHeaderScope<T, F>) => VNode);
 }>;
+/** 表格骨架屏 props（TableMain 内部件，不对外导出组件，仅类型复用） */
 export interface TableSkeletonProps {
+    /** 骨架形态：table=表格行列骨架 / grid=网格卡片骨架 */
     mode?: "table" | "grid";
+    /** 骨架行数（table）/ 卡片数（grid） */
     rows?: number;
+    /** 列数（仅 table 模式，取表格列数） */
     columns?: number;
+    /** 最大高度，与数据区同框限高 */
     maxHeight?: number;
+    /** 最小高度，配合 fillHeight 让冷启骨架也撑满、分页器不跳位 */
     minHeight?: number;
 }
-export interface TableMainProps<T extends Record<string, any>, SQ extends Record<string, any>, F extends Record<string, any>> {
+export interface TableMainProps<
+/** 行数据结构 */
+T extends Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any>> {
+    /** 展示分页器 */
     showPager?: boolean;
+    /** 是否显示切换视图按钮，默认 false */
     showSwitchView?: boolean;
+    /** 是否显示 toolbar（顶层开关，默认 true，优先级高于 toolbar.leftFeatures / rightFeatures） */
     showToolbar?: boolean;
+    /** toolbar 配置 */
     toolbar?: TableToolbarConfig<T, SQ, F>;
+    /** 参数 */
     query?: SQ;
+    /** 每页条数 */
     pageSizeInit?: number;
     pageSizeOptions?: number[];
     pageLayout?: string;
     rowKey: Extract<keyof T, string> | ((row: T) => string);
+    /** 请求api */
     api: (params: TableApiParams<SQ>) => Promise<TableApiResult<T>>;
     tableProps?: Omit<TableProps<T>, "data" | "maxHeight" | "rowKey"> & Record<`on${Capitalize<string>}`, (...args: any[]) => any>;
     columns: ElTableColumnProps<T, F>[];
+    /** 最大高度 */
     maxHeight?: number;
+    /** @deprecated 表头背景色
+     * ----
+     * 外部通过 --el-table-header-bg-color 自行设置 或者 通过同意修改主题色
+     */
     headerColor?: string;
+    /** 精细化布局 */
     refine?: boolean;
+    /** 精细化预留高度 */
     refineReduceHeight?: number;
+    /** 给插槽注入的方法 */
     injectInfo?: F;
+    /** 数据视口最大高度最小值 */
     dataViewMaxHeightMinValue?: number;
+    /**
+     * 冷启（首次无数据）加载时展示骨架屏，默认 true。
+     * 热刷（已有数据再加载）不出骨架——由外层遮罩（如 ListPage v-loading）盖旧数据负责。
+     */
     skeleton?: boolean;
+    /** 骨架行数（table）/ 卡片数（grid），缺省按可用高度自适应（3~8） */
     skeletonRows?: number;
+    /**
+     * 撑满可用高（默认 false）。开启后数据滚动区 min-height = 可用视口高，
+     * 稀疏 / 空数据时把分页器顶到容器底部，不悬在稀疏内容中间。
+     * 需有 maxHeight 或 refine+viewportHeight 基准方生效。
+     */
     fillHeight?: boolean;
+    /** 视口可用高度(显式指定,优先级最高);未传时回退 SCOPE_VIEWPORT_MAX_HEIGHT scope 链 + fallback 0(dataViewMaxHeightMinValue floor 兜底) */
     viewportHeight?: number;
+    /** 定向消费的祖先 scope 标识(setup 期快照,变更 console.error 忽略);沿 scope 链 parent 找 scope === parentChannel 取值 */
     parentChannel?: string;
 }

package/types/components/table/use-fill-height.d.ts

@@ -1,11 +1,25 @@
 import { ComputedRef } from 'vue';
+/**
+ * TableMain fillHeight 能力（非主流程 opt-in）：数据滚动区 min-height 撑满可用高，
+ * 让稀疏 / 空数据时分页器被顶到容器底部，不悬在稀疏内容中间。
+ *
+ * 取值 = 未经 dataViewMaxHeightMinValue 下界兜底的「原始可用高」（区别于 tableMaxHeight
+ * 的 `Math.max(raw, min)`）——小视口下用真实小高度，不被 500 抬高致溢出。
+ * 关（enabled=false）/ 无 viewport 基准 → 恒 undefined，删本 hook = 删文件 + 委托行
+ * + 模板/样式挂点，主干零残留（规则 22）。
+ */
 export interface UseFillHeightOptions {
+    /** 开关（prop.fillHeight） */
     enabled: () => boolean;
+    /** 原始可用高（未兜底），无 viewport 基准时 undefined */
     rawAvailableHeight: () => number | undefined;
 }
 export interface UseFillHeightReturn {
+    /** 是否生效（开关开 + 有正的可用高） */
     fillActive: ComputedRef<boolean>;
+    /** 撑满用 min-height（px 数值）；不生效为 undefined */
     fillMinHeight: ComputedRef<number | undefined>;
+    /** min-height 的 CSS 值（`${n}px`）；不生效为空串（供 scoped style v-bind） */
     fillMinHeightCss: ComputedRef<string>;
 }
 export declare const useFillHeight: (options: UseFillHeightOptions) => UseFillHeightReturn;

package/types/components/table/use-table-skeleton.d.ts

@@ -1,17 +1,33 @@
 import { ComputedRef } from 'vue';
+/**
+ * TableMain 冷启骨架屏派生逻辑（非主流程能力，抽离主体 setup）。
+ * 全 getter 入参、只读上游状态；关（enabled=false）时 showSkeleton 恒 false，删本 hook
+ * = 删文件 + TableMain 一行委托 + 模板挂点，主干零残留（规则 22）。
+ */
 export interface UseTableSkeletonOptions {
+    /** 骨架开关（prop.skeleton） */
     enabled: () => boolean;
+    /** 是否加载中 */
     loading: () => boolean;
+    /** 当前数据条数（0 = 冷启无数据） */
     dataLength: () => number;
+    /** 是否网格视图（决定骨架形态 table/grid） */
     isGrid: () => boolean;
+    /** 表格列数（table 骨架列数来源） */
     columnCount: () => number;
+    /** 显式骨架行数（prop.skeletonRows），0/空 = 按可用高度自适应 */
     skeletonRows: () => number | undefined;
+    /** 数据区可用高度（tableMaxHeight），用于行数自适应 */
     availableHeight: () => number | undefined;
 }
 export interface UseTableSkeletonReturn {
+    /** 是否展示骨架 = 开关开 + 加载中 + 冷启无数据（热刷有数据不出，交外层遮罩） */
     showSkeleton: ComputedRef<boolean>;
+    /** 骨架形态 */
     skeletonMode: ComputedRef<"table" | "grid">;
+    /** 骨架列数（夹到 [1,8]） */
     skeletonColumns: ComputedRef<number>;
+    /** 骨架行数（显式优先，否则按高度自适应夹到 [3,8]） */
     skeletonRowsFinal: ComputedRef<number>;
 }
 export declare const useTableSkeleton: (options: UseTableSkeletonOptions) => UseTableSkeletonReturn;

package/types/config/list-model.d.ts

@@ -1,20 +1,49 @@
 import { DotToObject, UnionToIntersection } from '../types';
+/**
+ * 列表 KEY 配置接口
+ * ---
+ * 约束消费方传入的 KEY_CONFIG 对象 shape，后续 BuildListModel / BuildListParams 工具基于本接口推导
+ */
 export interface ListModelKeyConfig {
     PAGE_SIZE_KEY: string;
     CURRENT_PAGE_KEY: string;
     TOTAL_KEY: string;
     LIST_KEY: string;
 }
+/**
+ * 基于 KEY_CONFIG 联合推导完整列表响应模型
+ * ---
+ * @example
+ *   BuildListModel<typeof APP_API_LIST_MODEL_KEY_CONFIG, User>
+ *     -> { items: User[]; page: { page: number; pageSize: number; totalRecord: number } }
+ */
 export type BuildListModel<KC extends ListModelKeyConfig, T> = UnionToIntersection<DotToObject<KC["LIST_KEY"], T[]> | DotToObject<KC["TOTAL_KEY"], number> | DotToObject<KC["CURRENT_PAGE_KEY"], number> | DotToObject<KC["PAGE_SIZE_KEY"], number>>;
+/**
+ * 基于 KEY_CONFIG 联合推导列表请求参数模型
+ * ---
+ * @example
+ *   BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, { keyword?: string }>
+ *     -> { keyword?: string } & { page: { page: number; pageSize: number } }
+ */
 export type BuildListParams<KC extends ListModelKeyConfig, P extends Record<string, any> = Record<string, any>> = P & UnionToIntersection<DotToObject<KC["CURRENT_PAGE_KEY"], number> | DotToObject<KC["PAGE_SIZE_KEY"], number>>;
+/** 应用接口列表模型配置（core 单一来源） */
 export declare const APP_API_LIST_MODEL_KEY_CONFIG: Readonly<{
+    /** 当前页码 key */
     CURRENT_PAGE_KEY: "page.page";
+    /** 每页条数 key */
     PAGE_SIZE_KEY: "page.pageSize";
+    /** 总数 key */
     TOTAL_KEY: "page.totalRecord";
+    /** 数据列表 key */
     LIST_KEY: "items";
 }>;
+/** 应用接口列表模型 */
 export type AppApiListModel<T = any> = BuildListModel<typeof APP_API_LIST_MODEL_KEY_CONFIG, T>;
+/** 应用接口列表分页参数 key */
 export type AppApiListPageParamsKey = typeof APP_API_LIST_MODEL_KEY_CONFIG.PAGE_SIZE_KEY | typeof APP_API_LIST_MODEL_KEY_CONFIG.CURRENT_PAGE_KEY;
+/** 应用接口列表 排除分页参数的 key */
 export type AppApiListNoPageParamsKey = Exclude<string, AppApiListPageParamsKey>;
+/** 应用接口列表请求参数模型 */
 export type AppApiListParamsModel<P extends Record<AppApiListNoPageParamsKey, any> = Record<AppApiListNoPageParamsKey, any>> = BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, Partial<P>>;
+/** 应用接口列表请求参数模型（排除分页参数） */
 export type AppApiListParamsNoPageParams<P extends BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG>> = Omit<AppApiListParamsModel<P>, keyof UnionToIntersection<DotToObject<(typeof APP_API_LIST_MODEL_KEY_CONFIG)["CURRENT_PAGE_KEY"], number> | DotToObject<(typeof APP_API_LIST_MODEL_KEY_CONFIG)["PAGE_SIZE_KEY"], number>>>;

package/types/config/route.d.ts

@@ -1,2 +1,4 @@
+/** 模块级别的路由 */
 export declare const ROUTE_MODULE_LEVEL = 1;
+/** TabsMain replaceQuery 同步到路由时的 query key */
 export declare const TabsMainReplaceQueryKey = "_tab";

package/types/helpers/form.d.ts

@@ -1,5 +1,10 @@
 import { FormItemRule } from 'element-plus';
+/**
+ * 密码规则
+ */
 export declare const passwordRule: FormItemRule;
 export declare const getConfirmPasswordRule: (getPassword: () => string) => FormItemRule;
+/** 选择框全选值 */
 export declare const FORM_CONFIG_SELECT_ALL_VALUE: string;
+/** 设置表单组件类型 */
 export declare const setFormComponentType: () => void;

package/types/helpers/list-helper.d.ts

@@ -1,9 +1,35 @@
 import { TableApiParams, TableApiResult } from '../components/table/types';
 export interface FetchListAllOptions {
+    /** 单页大小,默认 200,范围 [1, 1000] */
     pageSize?: number;
+    /** 累计抓取上限,默认 10000;totalRecord > limit 则 throw */
     limit?: number;
 }
+/**
+ * 全量翻页拉取(串行,提前终止)
+ * ---
+ * @param api  原始分页 api 函数(签名同 TableMain :api prop)
+ * @param baseParams 业务侧固定参数,会透传到每页 api 调用(不被改写)
+ * @param opts pageSize / limit 覆盖
+ * @returns 全量 items 数组
+ *
+ * 行为:
+ * - totalRecord = 0 → 直接 [] 返回(仅调 1 次)
+ * - 单页 items.length < pageSize → 视为末页提前终止
+ * - 任一页 reject → 整体 reject 透传原错误
+ * - totalRecord > limit → throw 兜底
+ */
 export declare function fetchListAll<T extends Record<string, any>, P extends Record<string, any> = {}>(api: (params: TableApiParams<P>) => Promise<TableApiResult<T>>, baseParams?: P, opts?: FetchListAllOptions): Promise<T[]>;
 export type ListApiSource<T> = T[] | (() => T[]) | (() => Promise<T[]>);
+/**
+ * 用本地数组 / 同步函数 / 异步函数生成符合 TableMain :api prop 签名的 api
+ * ---
+ * 内部识别 source 类型 + 分页切片;无缓存,每次调用 source 重新求值
+ */
 export declare function createListApi<T extends Record<string, any>>(source: ListApiSource<T>): (params: TableApiParams<{}>) => Promise<TableApiResult<T>>;
+/**
+ * countAll: 仅探测列表总记录数,不拉数据。
+ * 1 次 api 调用 page=1/pageSize=1,返回 totalRecord。
+ * 用于"探测是否有数据 / 数据计数 / 存在性判断"等场景,替代手工 pageSize: 9999 hack。
+ */
 export declare function countAll<P extends Record<string, any> = {}>(api: (params: TableApiParams<P>) => Promise<TableApiResult<any>>, baseParams?: P): Promise<number>;

package/types/helpers/types.d.ts

@@ -1,4 +1,15 @@
+/**
+ * 深度递归 Partial(函数类型保持不变,object 类型字段递归可选)
+ * ---
+ * 应用场景:SDK 请求参数嵌套结构的可选化(如 PagingInput)
+ */
 export type DeepPartial<T> = T extends (...args: any[]) => any ? T : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;
+/**
+ * 分页请求参数的可选包装
+ * ---
+ * 与 SDK 1.1.40 嵌套契约耦合:业务侧手包 list api wrapper 时
+ * 常以 PagingInput<RawApiParams> 作为入参类型,兜底字段缺失
+ */
 export type PagingInput<T> = DeepPartial<T>;

package/types/hooks/activated.d.ts

@@ -1,7 +1,22 @@
+/** 激活信息 */
 export interface ActivatedInfo {
     isActivated: boolean;
     triggerType: "mounted" | "activated" | "deactivated" | "unmounted";
 }
+/**
+ * 是否激活。
+ *
+ * 四个生命周期时机（mounted / activated / deactivated / unmounted）各在对应钩子里
+ * **直接派发 watchFn**——`activatedInfo` 这个 ref 也只在这四处被改，别无他源，故不再经
+ * `watch` 中转。移除 `watch(activatedInfo, …, { immediate: true })` 同时根治了两个 bug：
+ * - **卸载不派发（监听泄漏）**：`watch` 默认 `flush:'pre'` 是队列 job，真·卸载时 watcher 在
+ *   `scope.stop()` 后才轮到刷新、被跳过 → watchFn 收不到 `triggerType:"unmounted"`。直接派发即修。
+ * - **初始 false 陷阱**：`immediate` 种子（setup 期、isActivated=false、早于 onMounted）会让非幂等
+ *   副作用在激活前误触发一次。无 watch → 无种子 → 首次派发即 onMounted，陷阱消失（故无需 hasMounted）。
+ *
+ * 注：`useActivated((info) => …)` 里绑 window/document/matchMedia 等外部 target 监听的
+ * 「随激活态绑解」现在卸载会正常解绑，无需任何 opt-in。
+ */
 export declare const useActivated: (watchFn?: (info: ActivatedInfo) => void) => {
     isActivated: import('vue').ComputedRef<boolean>;
     activatedInfo: import('vue').ComputedRef<{
@@ -9,5 +24,13 @@ export declare const useActivated: (watchFn?: (info: ActivatedInfo) => void) =>
         readonly triggerType: "mounted" | "activated" | "deactivated" | "unmounted";
     }>;
 };
+/**
+ * @deprecated 请使用 useActivated 替代
+ * @example useActivated((info) => { info.isActivated && callback(info) })
+ * 激活时执行时间 */
 export declare const useActivatedExec: (callback: (info: ActivatedInfo) => void) => void;
+/**
+ * @deprecated 请使用 useActivated 替代
+ * @example useActivated((info) => { info.isActivated ? bind(info) : unbind(info) })
+ * 激活时监听事件 */
 export declare const useActivatedEvent: (bind: (info: ActivatedInfo) => void, unbind: (info: ActivatedInfo) => void) => void;

package/types/hooks/feel-size.d.ts

@@ -1,6 +1,8 @@
+/** 感知元素尺寸变化 */
 export declare const useFeelSize: () => {
     unwatchDom: () => void;
     watchDom: (dom: HTMLElement) => void;
+    /** 元素尺寸信息只读属性 */
     sizeInfo: import('vue').ComputedRef<{
         width: number;
         height: number;

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

@@ -1,7 +1,11 @@
 import { RouteMetaResolveRaw } from '../types';
+/** 应用菜单数据分发 */
 export declare const useMenusDataDispatch: ({ getMenus, getMenuFlatList, getExtractLevel1ToHeader, }: {
+    /** 菜单树 */
     getMenus: () => RouteMetaResolveRaw[];
+    /** 扁平化菜单列表 */
     getMenuFlatList: () => RouteMetaResolveRaw[];
+    /** 判断是否提取1级路由模块到HEADER */
     getExtractLevel1ToHeader: () => boolean;
 }) => {
     sidebarMenus: import('vue').ComputedRef<RouteMetaResolveRaw[]>;

package/types/hooks/timeout.d.ts

@@ -1,3 +1,7 @@
 export type ClearTimer = () => void;
 export type SetTimer = (handler: () => void, timeout: number) => void;
+/**
+ * 使用定时器
+ * @param autoClear 是否在生命周期结束前自动清除定时器
+ */
 export declare const useTimeout: (autoClear?: boolean) => [SetTimer, ClearTimer];

package/types/hooks/use-channel-viewport-height.d.ts

@@ -1,14 +1,22 @@
 import { ComputedRef } from 'vue';
 import { ScopeViewportMaxHeight } from '../inject';
+/** useChannelViewportHeight 第二参数 options */
 export interface UseChannelViewportHeightOptions {
+    /** scope 链未命中时的最终兜底,默认 0(脱离容器体系不假定具体高;组件自有 floor 各管各) */
     fallback?: number;
 }
+/** useChannelViewportHeight 入参对象形状(约定 reactive,props 即满足) */
 export interface UseChannelViewportHeightMaybeProps {
+    /** props.viewportHeight,显式指定,优先级最高 */
     viewportHeight?: number;
+    /** tabs 族 channel 父级标识——沿 scope 链找 `scope === parentChannel` 的祖先;setup 期快照,变更 console.error 忽略 */
     parentChannel?: string;
 }
+/** useChannelViewportHeight 返回值 */
 export interface UseChannelViewportHeightReturn {
+    /** 最终视口高度,链路 viewportHeight > scope 链(parentChannel 定向/就近) > fallback */
     viewportHeightFinal: ComputedRef<number>;
+    /** inject 到的最近 scope 对象(未命中 undefined)——供 provider 型消费方(TabsRefineFlow)作 `parent` 续链 */
     nearestScope: ScopeViewportMaxHeight | undefined;
 }
 export declare const useChannelViewportHeight: (maybeProps: UseChannelViewportHeightMaybeProps, options?: UseChannelViewportHeightOptions) => UseChannelViewportHeightReturn;

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

@@ -1,8 +1,27 @@
 import { ComponentPublicInstance } from 'vue';
 import { Breakpoint } from './use-breakpoint';
+/** 容器宽 → 断点 */
 export declare const resolveBreakpointByWidth: (width: number) => Breakpoint;
+/** elRef 可挂载的目标：原生元素 | 组件公共实例 */
 export type CustomBreakpointTarget = HTMLElement | ComponentPublicInstance | null | undefined;
+/**
+ * 从 elRef 值解析根 DOM 节点：
+ * - HTMLElement → 直接用；
+ * - 组件实例（有 $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>>;