@done-coding/admin-core 0.18.0 → 0.19.0

package/types/components/display/use-tabs-query-sync.d.ts

@@ -1,12 +1,41 @@
 import { Ref } from 'vue';
 import { RouteLocationNormalizedLoaded, Router } from 'vue-router';
+/**
+ * TabsMain 激活 tab ↔ 路由 query 同步的工具（仅 TabsMain 消费）。
+ *
+ * 设计取向（甲方 2026-07-02 校准，避免过度设计）：
+ * - **读走激活生命周期**：TabsMain 用 `useActivated` 在每次激活（首次 mounted + keep-alive 缓存页
+ *   返回 activated）从 `route.query` 读一次作激活 tab，值合不合法交 TabsMain 既有 normalize watch
+ *   校准。用 useActivated 而非 onMounted → 覆盖「缓存页返回按新 query 重同步」（onMounted 不重跑会漏）。
+ * - **queryKey 可响应式**：读走激活回调 / 写走 getter，每次都读新鲜 `props.queryKey`，无需快照。
+ * - **持续同步只有一个方向：model → query**（`watchTabToQuery`）。反向由激活回调承担（激活时读 query），
+ *   非激活期外部改 query 不实时反切。
+ * - **初始化期不写 query**（`ready()` 闸）：init 期 seed 与 normalize 归一会产生 transient model 变更，
+ *   若逐个写 query 会触发多次 `router.replace` 竞速（真机曾见最终 URL 落在归一 transient）。故 seed 前
+ *   不写，seed 后开闸。写 watch 用 `flush:"post"` 读 settle 后的真实激活值（避 defineModel setter 只
+ *   emit、getter 同步返回旧 prop 的 masked 读）。
+ */
+/**
+ * 从 route.query 读取激活 tab 值（query 值可能是 string|null|数组，取首个字符串；无则 undefined）。
+ * 由 TabsMain 在每次激活（useActivated）时调用；queryKey 可响应式（每次读新鲜值）。
+ */
 export declare function getTabQuery(route: RouteLocationNormalizedLoaded | undefined, queryKey: string | undefined): string | undefined;
+/**
+ * 把激活值写回路由 query（单次）。`router.replace`（不压历史栈）、`{ ...route.query, [queryKey]:
+ * activeKey }` 只增删自己那个 key、保留其它 query；值与当前相同则跳过（防冗余导航）。
+ * 无 router / queryKey / activeKey → no-op。
+ */
 export declare function writeTabQuery(params: {
     activeKey: string | undefined;
     route: RouteLocationNormalizedLoaded | undefined;
     router: Router | undefined;
     queryKey: string | undefined;
 }): void;
+/**
+ * 持续同步：激活 tab（model）变更 → 写回 query。`ready()` 返回 false 时跳过（初始化期不写，
+ * 见上文竞速说明）。`queryKey` 取 getter，每次写读新鲜值（响应式）。`flush:"post"` 让回调在组件
+ * re-render、prop settle 后跑，读到真实激活值而非 defineModel masked 旧 prop。无 router → no-op。
+ */
 export declare function watchTabToQuery(params: {
     model: Ref<string | undefined>;
     route: RouteLocationNormalizedLoaded | undefined;

package/types/components/form/FormItemNestForm.vue.d.ts

@@ -1,12 +1,17 @@
 import { FormItemConfigList } from './types';
 import { ColProps } from 'element-plus';
 type __VLS_Props = {
+    /** 所属父 item key（注册到父 FormMain exposeMap 的索引） */
     nestKey: string;
+    /** 子表单配置列表 */
     list: FormItemConfigList;
     layout?: Partial<ColProps>;
     rowGutter?: number;
+    /** 联结组件外环阴影颜色；缺省走 CSS 变量主题自适配（亮/暗），仅显式传时内联覆盖 */
     shadowColor?: string;
+    /** 父 item 代表 span（P3 rebase 算因子用；helper 经 resolveLayoutSpan(layout) 传入） */
     parentSpan?: number;
+    /** 是否叠本层嵌套布局 rebase（缺省 true；false = 逆向逃生口，layout 原样直透） */
     rebase?: boolean;
 };
 type __VLS_PublicProps = {

package/types/components/form/FormItemNestFormList.vue.d.ts

@@ -8,29 +8,46 @@ declare const _default: <T extends Record<string, any>>(__VLS_props: NonNullable
     } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:modelValue"> & ({
         modelValue?: T[];
     } & {
+        /** 所属父 item key（注册到父 FormMain exposeMap 的索引） */
         nestKey: string;
+        /** 每行子表单配置列表 */
         list: FormItemConfigList;
+        /** 行稳定标识字段（指向 T 内稳定 id）；缺省走内部自增 rowId */
         rowKey?: string;
+        /** 新增行工厂；缺省 generateFormData(list) 产子默认对象 */
         itemFactory?: () => T;
+        /** 最少行数（删到 min 禁删；硬约束走父 item rules 长度校验） */
         min?: number;
+        /** 最多行数（达上限禁新增；硬约束走父 item rules 长度校验） */
         max?: number;
         layout?: Partial<ColProps>;
         rowGutter?: number;
         addText?: string;
         removeText?: string;
+        /** 顶部自定义渲染（render-fn prop，替代 template slot；label 由父 FormItem 渲染） */
         headerRender?: (scope: {
             count: number;
             max: number;
         }) => VNodeChild;
+        /** 底部自定义渲染；缺省 = 内置「新增」按钮 */
         footerRender?: (scope: {
             count: number;
             max: number;
             canAdd: boolean;
             add: () => void;
         }) => VNodeChild;
+        /** 联结组件外环 + 每行分割阴影颜色 */
         shadowColor?: string;
+        /** 父 item 代表 span（P3 rebase 算因子用；helper 经 resolveLayoutSpan(layout) 传入） */
         parentSpan?: number;
+        /** 是否叠本层嵌套布局 rebase（缺省 true；false = 逆向逃生口，layout 原样直透） */
         rebase?: boolean;
+        /**
+         * 行删除二次确认（破坏性操作防误删）：
+         * - `true`（默认）→ 默认 popconfirm「确认删除该项？」（danger）
+         * - `false` → 不弹确认，直删（回旧行为）
+         * - 对象 → 自定义 ActionBtnConfirmConfig
+         */
         removeConfirm?: boolean | ActionBtnConfirmConfig;
     }) & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;

package/types/components/form/FormVerifyCode.vue.d.ts

@@ -3,11 +3,20 @@ declare const _default: <P extends Record<string, any>>(__VLS_props: NonNullable
         readonly "onUpdate:modelValue"?: ((value: string) => any) | undefined;
     } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:modelValue"> & {
         modelValue: string;
+        /** 发送频率 */
         hz?: number;
         api: (params?: P) => Promise<void>;
+        /** 请求参数 */
         params?: P;
+        /** 重置标识
+         * 内部检测变化以重新计时
+         * @example  const resetKey = ref(1);
+         * 需要重置时 resetKey.value++;
+         *  */
         resetKey?: number;
+        /** 是否禁用 */
         disabled?: boolean;
+        /** 发送按钮文本 */
         btnText?: string;
     } & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;

package/types/components/form/FormVerifyImage.vue.d.ts

@@ -6,6 +6,7 @@ declare const _default: <P extends Record<string, any>>(__VLS_props: NonNullable
         imgWidth?: number;
         api: (params?: P) => Promise<string>;
         params?: P;
+        /** 是否自动销毁图片链接 */
         autoRevokeUrl?: boolean;
     } & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;

package/types/components/form/form-search-utils.d.ts

@@ -1,21 +1,55 @@
 import { ColProps } from 'element-plus';
 import { Breakpoint } from '../../hooks/use-breakpoint';
+/**
+ * 计算当前断点下单项的 span 档位（断点值优先于 span，镜像 ElCol 语义）。
+ */
 export declare const getCurrentSpan: (layout: Partial<ColProps> | undefined, breakpoint: Breakpoint) => number;
+/**
+ * 解析单项在指定断点下的实际占位格数（含 offset）。
+ * merged 应为「顶层 layout 与单项 layout 的合并结果」（与 FormMain.mergeLayout 同序），
+ * 保证几何模拟看到的 span 与 ElCol 实际渲染一致。结果 clamp 到 [1, 24]。
+ */
 export declare const resolveSearchItemOccupancy: (merged: Partial<ColProps>, breakpoint: Breakpoint) => number;
 export interface SearchGeometryOptions {
+    /** 可见项（hide !== true）在当前断点下的占位格数序列，顺序 = 渲染顺序 */
     spans: number[];
+    /** 按钮区与末行共存所需的最小格数（通常取当前断点单项 span 档位） */
     buttonMinSpan: number;
+    /** 收起态最大视觉行数（含操作区所在行）；<= 0 = 不折叠 */
     maxRows: number;
+    /** 当前是否处于收起态 */
     collapsed: boolean;
 }
 export interface SearchGeometry {
+    /** 实际渲染的可见项数（收起态 = 折叠后保留数；展开态 = 全量） */
     showCount: number;
+    /** 是否存在被折叠项（决定「展开更多/收起更多」按钮显隐） */
     needsFold: boolean;
+    /** 按钮区 ElCol 的 span（共行 = 末行剩余格数；独占行 = 24） */
     buttonSpan: number;
 }
+/**
+ * 搜索表单几何解算（异构 span 装箱模型）。
+ *
+ * maxRows 语义 = 收起态下整个表单最多渲染的**真实视觉行数，含操作区所在行**；
+ * 行由逐行装箱模拟得出（单项 span 可异构），非「maxRows × 每行项数」的均匀网格折算。
+ * 装不下的项折叠进「展开更多」，操作区恒为流的末尾 + 贴右。
+ */
 export declare const computeSearchGeometry: ({ spans, buttonMinSpan, maxRows, collapsed, }: SearchGeometryOptions) => SearchGeometry;
+/**
+ * compact 生效时按**容器断点**把布局解算成定值 `{ span }`（ElCol 定 span 无媒体查询、
+ * 恒生效，规避响应式 span 认视口误判档位）；否则用外部响应式 layout。
+ * span 取 `getCurrentSpan(layout, breakpoint)` = 复用用户配的档位语义（如容器 xs→layout.xs）。
+ */
 export declare const resolveSearchLayout: (compact: boolean, layout: Partial<ColProps> | undefined, breakpoint: Breakpoint) => Partial<ColProps> | undefined;
+/** compact 生效则 label 顶部（窄列吃满宽），否则用外部 labelPosition */
 export declare const resolveSearchLabelPosition: <T extends "right" | "left" | "top" | undefined>(compact: boolean, labelPosition: T) => T | "top";
+/**
+ * 结算最终渲染 list：compact 时每项 layout 强制为 itemLayout（容器定值 `{ span }`，
+ * 覆盖单项自定义 layout，够得着外层盖不到的项）；collapsing 时**前 threshold 个
+ * 可见项之外**的可见项 hide 覆写 true（threshold = 保留的可见项数，按可见序计数）。
+ * 二者皆不触发时原样返回（保持引用，零回归）。
+ */
 export declare const packSearchFormList: <T extends Record<string, any>>(list: T[], options: {
     compact: boolean;
     itemLayout: Partial<ColProps>;

package/types/components/form/nest-form-item-list.d.ts

@@ -3,33 +3,61 @@ import { ColProps } from 'element-plus';
 import { FormItemConfig, FormItemConfigList } from './types';
 import { ActionBtnConfirmConfig } from '../display';
 export interface NestFormItemListOptions {
+    /** 父 item key */
     key: string;
+    /** 父 item label */
     label: string;
+    /** 每行子表单配置列表 */
     list: FormItemConfigList;
+    /** 行稳定标识字段（指向行对象内稳定 id）；缺省走内部自增 rowId */
     rowKey?: string;
+    /** 新增行工厂；缺省 generateFormData(list) */
     itemFactory?: () => Record<string, any>;
+    /** 最少行数 */
     min?: number;
+    /** 最多行数 */
     max?: number;
+    /** 父 item 栅格布局 */
     layout?: Partial<ColProps>;
+    /** 每行子表单行间距 */
     rowGutter?: number;
+    /** 新增 / 删除按钮文案 */
     addText?: string;
     removeText?: string;
+    /** 顶部自定义渲染（render-fn；label 由父 FormItem 渲染，本组件不出 title） */
     headerRender?: (scope: {
         count: number;
         max: number;
     }) => VNodeChild;
+    /** 底部自定义渲染；缺省 = 内置「新增」按钮 */
     footerRender?: (scope: {
         count: number;
         max: number;
         canAdd: boolean;
         add: () => void;
     }) => VNodeChild;
+    /** 联结组件外环 + 每行分割阴影颜色 */
     shadowColor?: string;
+    /** 业务校验规则；与自动织入的 min/max 长度规则合并（长度规则在前） */
     rules?: FormItemConfig["rules"];
+    /** 覆盖默认 init（缺省 = 空数组 []，[MUST NOT] 改初始值补 min；min/max 走校验） */
     init?: FormItemConfig["init"];
+    /** 覆盖默认 stringify（缺省 = 数组逐项 `stringifyFormData(t, list)`） */
     stringify?: FormItemConfig["stringify"];
+    /** 覆盖默认 parse（缺省 = 数组逐项 `parseFormData(t, list)`） */
     parse?: FormItemConfig["parse"];
+    /** 是否叠本层嵌套布局 rebase（P3，缺省 true；false = 逆向逃生口，子层 layout 原样直透） */
     rebase?: boolean;
+    /** 行删除二次确认（缺省 true=默认 popconfirm「确认删除该项？」；false=直删；对象=自定义） */
     removeConfirm?: boolean | ActionBtnConfirmConfig;
 }
+/**
+ * 生成「父 item 内嵌数组子表单（N 行 FormMain）」的 FormItemConfig（C4 配套 helper）
+ * ----
+ * render 出口挂 FormItemNestFormList（值贯通数组 in-place + 增删 + 聚合校验穿透自动接线）。
+ * ----
+ * **序列化 pack（ADR-6，对齐 §34）**：自动织入 init/stringify/parse —— 父 FormMain 的
+ * generate()/stringify()/parse() 逐项命中即对数组逐项递归（行内若再嵌 nestFormItem /
+ * nestFormItemList → 逐层组合）。业务传 init/stringify/parse 则以业务为准。
+ */
 export declare function nestFormItemList(options: NestFormItemListOptions): FormItemConfig;

package/types/components/form/nest-form-item.d.ts

@@ -1,15 +1,36 @@
 import { ColProps } from 'element-plus';
 import { FormItemConfig, FormItemConfigList } from './types';
 export interface NestFormItemOptions {
+    /** 父 item key */
     key: string;
+    /** 父 item label */
     label: string;
+    /** 子表单配置列表 */
     list: FormItemConfigList;
+    /** 父 item 栅格布局 */
     layout?: Partial<ColProps>;
+    /** 子表单行间距 */
     rowGutter?: number;
+    /** 联结组件外环阴影颜色 */
     shadowColor?: string;
+    /** 覆盖默认 init（缺省 = `generateFormData(list)`，产子默认对象） */
     init?: FormItemConfig["init"];
+    /** 覆盖默认 stringify（缺省 = 递归 `stringifyFormData(value, list)`） */
     stringify?: FormItemConfig["stringify"];
+    /** 覆盖默认 parse（缺省 = 递归 `parseFormData(value, list)`） */
     parse?: FormItemConfig["parse"];
+    /** 是否叠本层嵌套布局 rebase（P3，缺省 true；false = 逆向逃生口，子层 layout 原样直透） */
     rebase?: boolean;
 }
+/**
+ * 生成「父 item 内嵌子 FormMain」的 FormItemConfig（C1 配套 helper）
+ * ----
+ * 降低业务方手写 h(FormItemNestForm) 噪音：传 key/label/子 list 即得一个满足 FormItemConfig
+ * 的配置项，渲染出口挂 FormItemNestForm（值贯通 + 校验级联自动接线）。
+ * ----
+ * **stringify/parse/init 自动 pack**：FormItemConfig 的 per-item `init`/`stringify`/`parse`
+ * 钩子 + 纯 list 驱动 util（generate/stringify/parseFormData）→ 自动织入「递归进子 list」，
+ * 父 FormMain 的 `generate()`/`stringify()`/`parse()` 逐项命中即递归序列化/回显嵌套子表单，
+ * 多层自然组合（孙 nestFormItem 的钩子同理逐层）。业务传 init/stringify/parse 则以业务为准。
+ */
 export declare function nestFormItem(options: NestFormItemOptions): FormItemConfig;

package/types/components/form/nest-registry.d.ts

@@ -1,8 +1,22 @@
 import { FormMainInstance } from './types';
+/**
+ * 嵌套子 FormMain 级联 expose 子集
+ * ----
+ * 联结组件（FormItemNestForm）把所持子 FormMain 的级联方法注册进父 FormMain 的 exposeMap，
+ * 使父顶层 validate/clearValidate/resetFields 可级联到子。
+ */
 export interface NestFormExpose {
     validate: FormMainInstance["validate"];
     clearValidate: FormMainInstance["clearValidate"];
     resetFields: FormMainInstance["resetFields"];
 }
+/**
+ * 嵌套子表单 exposeMap
+ * ----
+ * key = 联结组件所属父 item 的 key（天然唯一，供父 FormMain 对齐 hideKeyList：隐藏 item 不级联 validate）。
+ * 用 `shallowReactive`：顶层 key 增删响应式（注册/摘除可被响应式消费），value（expose 对象）保持 raw
+ * 不深代理——既规避 expose 引用循环，又留响应式消费口。每个 FormMain 经工厂在闭包内 new 一份，零模块级单例。
+ */
 export type NestFormExposeMap = Record<string, NestFormExpose>;
+/** 创建一个嵌套子表单 exposeMap（shallowReactive） */
 export declare function createNestFormExposeMap(): NestFormExposeMap;