@done-coding/admin-core 0.18.0 → 0.19.0

package/types/utils/dom.d.ts

@@ -1,2 +1,24 @@
+/**
+ * 向上查找最近的「可滚祖先」：computed `overflow-y` 为 auto/scroll/overlay **且**
+ * 当前真实溢出（scrollHeight > clientHeight）。到 body / documentElement 为止；
+ * 无命中 → `undefined`（调用方按 window 滚动处理）。
+ *
+ * 双条件缺一不可：只看 overflow 会误吸「auto 但不限高、从不产生滚动」的装饰容器
+ * （真滚动在 window，对它 scrollTop 无效）；只看溢出会把 `overflow: hidden` 的
+ * 裁剪容器当滚动容器。SSR / 无 DOM 环境传 null 返回 undefined。
+ */
 export declare function domClosestScrollableAncestor(el: HTMLElement | null | undefined): HTMLElement | undefined;
+/**
+ * 向上查找 CSS `position: sticky` 的「滚动口祖先」：computed `overflow-y` 为
+ * auto/scroll/overlay/hidden 的最近祖先（hidden 也是滚动容器，可编程滚动；clip 不是）。
+ * 与 CSS 粘性语义同构——sticky 以最近非 visible/clip 溢出祖先为 scrollport，
+ * **不看当下是否真溢出**（内容后到才溢出时 scrollport 归属不变）。
+ * 到 body / documentElement 为止；无命中 → `undefined`（scrollport = 视口，
+ * 调用方按 window 滚动处理）。SSR / 无 DOM 环境传 null 返回 undefined。
+ *
+ * 与 `domClosestScrollableAncestor` 的分工：后者服务「现在就要滚过去」
+ * （scrollTo / scrollspy），必须真溢出；本函数服务 sticky offset 的坐标系归属，
+ * 判据必须与 CSS 一致——若沿用真溢出条件，容器尚未溢出时会误判 window 滚，
+ * 而 CSS 仍以该容器为 scrollport → 粘住顶距错位（弹窗内实测踩坑）。
+ */
 export declare function domClosestStickyScrollport(el: HTMLElement | null | undefined): HTMLElement | undefined;

package/types/utils/export.d.ts

@@ -1,16 +1,31 @@
 import { ElTableColumnProps } from '../components/table/types';
+/** 操作列标记 prop。消费方以此值标记操作列，导出时自动过滤 */
 export declare const OPERATE_COLUMN_PROP = "OPERATE";
+/** 前端导出最大行数 */
 export declare const EXPORT_MAX_LIMIT = 10000;
-export type ExportColumn<T extends Record<string, any>, F extends Record<string, any> = {}> = Pick<ElTableColumnProps<T, F>, "prop" | "label" | "type">;
+/** 导出列：从 ElTableColumnProps 中提取 prop、label、type */
+export type ExportColumn<T extends Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any> = {}> = Pick<ElTableColumnProps<T, F>, "prop" | "label" | "type">;
+/** 导出列配置：支持 valueMap 自定义取值 */
 export interface ExportColumnConfig<T extends Record<string, any>> {
     prop: keyof T;
     label: string;
+    /** 自定义取值，不传则取 row[prop] */
     valueMap?: (row: Record<keyof T, any>) => unknown;
 }
+/** 导出参数 */
 export interface ExportOptions<T extends Record<string, any>> {
     columns: ExportColumnConfig<T>[];
     list: T[];
     filename?: string;
 }
+/**
+ * 从表格列配置中提取可导出列
+ * ---
+ * 过滤规则：排除 type 为 selection / index / expand 的列（除 default 外均排除），
+ * 排除 prop 为 OPERATE_COLUMN_PROP 的列，排除无 prop 的列
+ */
 export declare const pickExportColumns: <T extends Record<string, any>, F extends Record<string, any>>(columns: ElTableColumnProps<T, F>[]) => ExportColumn<T, F>[];
+/** 导出 CSV 文件 */
 export declare const exportCSV: <T extends Record<string, any>>({ columns, list, filename, }: ExportOptions<T>) => void;

package/types/utils/id.d.ts

@@ -1 +1,2 @@
+/** 获取不重复的值[单次生命周期中] */
 export declare const getId: (prefix?: string) => string;

package/types/utils/router.d.ts

@@ -1,5 +1,7 @@
 import { GetRoutePermissionParams } from '../types';
+/** 获取路由权限key */
 export declare const getRoutePermissionKey: ({ path, permission: permissionConfig, }: GetRoutePermissionParams) => string | number | undefined;
+/** 扁平化路由元信息解析raw */
 export declare const flatRouteMetaResolveRaw: <T extends {
     children: T[];
 }>(list: T[], arr?: T[]) => T[];

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

@@ -1,5 +1,15 @@
+/**
+ * 主题色阶派生（模式感知，复刻 Element Plus 的 SCSS `mix` 算法）。
+ *
+ * core 挂值时对 6 个语义色（primary/success/warning/danger/info + error）
+ * 由基色派生 EP 7 档（base 自身 + light-3/5/7/8/9 + dark-2），亮/暗模式各用
+ * 不同的混入色，使派生结果与 EP 原生色阶一致。
+ */
+/** 主题明暗模式（决定色阶向哪一端混合） */
 export type ThemeScaleMode = "light" | "dark";
+/** 一个语义色的 EP 7 档色阶（key 与 `--el-color-*-light-#` / `-dark-2` 对齐） */
 export interface ThemeColorScale {
+    /** 基色自身 */
     base: string;
     "light-3": string;
     "light-5": string;
@@ -8,7 +18,28 @@ export interface ThemeColorScale {
     "light-9": string;
     "dark-2": string;
 }
+/** `#rgb` / `#rrggbb` → [r,g,b]；非法格式返回 null */
 export declare const themeScaleParseHex: (hex: string) => [number, number, number] | null;
+/**
+ * 混色：`c1` 占 `w1`、`c2` 占 `1-w1`，各通道线性混合后四舍五入
+ * （复刻 EP/SCSS `mix(c1, c2, w1)` 语义，w1 为 c1 的权重 [0,1]）。
+ * 任一入参非 hex（如 `var(...)` / `rgba(...)`）→ 返回 `c2` 兜底，不崩。
+ */
 export declare const themeScaleMix: (c1: string, c2: string, w1: number) => string;
+/**
+ * `#rgb` / `#rrggbb` + alpha → `rgba(r, g, b, a)`。
+ *
+ * 供吃不了 CSS `var()` 的 JS / canvas 消费方（如 ElWatermark `font.color`）按主题
+ * 真实色值 + 透明度生成可绘制色串。`alpha` 自动裁剪到 [0,1]。
+ * 非 hex 入参（`var(...)` / `rgba(...)`）→ 原样返回（不崩、不强转）。
+ */
 export declare const themeScaleToRgba: (hex: string, alpha: number) => string;
+/**
+ * 按 EP 算法 + 模式感知派生一个语义色的 7 档色阶。
+ *
+ * - light：`light-i = mix(#fff, base, i*10%)`，`dark-2 = mix(#000, base, 20%)`
+ * - dark： `light-i = mix(#141414, base, i*10%)`，`dark-2 = mix(#fff, base, 20%)`
+ *
+ * `base` 非 hex 时各档兜底返回 `base` 原值（保持可挂载、不崩）。
+ */
 export declare const themeScaleDerive: (base: string, mode: ThemeScaleMode) => ThemeColorScale;

package/types/utils/time.d.ts

@@ -1 +1,2 @@
+/** 倒计时 */
 export declare const timeCountDown: (time: number, handler: (t: number) => void, endHandler: () => void) => () => void;