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

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

@@ -5,61 +5,132 @@ export type OnlyOneKey<T extends Record<string, any>> = {
         [P in K]?: T[P];
     } & Partial<Record<Exclude<keyof T, K>, never>>;
 }[keyof T];
+/** 额外扩展表单配置项 */
 export type FormItemConfigExtra = OnlyOneKey<{
+    /** 是输入类型 */
     isInput: boolean;
+    /** 是选择类型 */
     isSelect: boolean;
 }> & {
+    /** 回车提交 */
     enterSubmit?: boolean;
+    /** 失去焦点提交[isInput默认为true] */
     blurSubmit?: boolean;
+    /** 变化提交 [isSelect默认为true] */
     changeSubmit?: boolean;
 };
 interface WrapProps extends FormItemProps {
     [key: string]: any;
 }
+/** formItem联动配置 */
 interface FormItemLinkConfig<K extends string, BV, OV> {
+    /** 关联(该宿主配置)表单项的key */
     key: K;
+    /**
+     * 获取该项的值
+     * @param hostValue 宿主/依赖项的值
+     * @param ownValue 该(寄生/收集依赖)项的值
+     * @param attachInfo 附加信息，可用于表单渲染为自定义组件时触发事件triggerChangeLink, 此场景 寄生项的值内部会去拿
+     * @example emit('triggerChangeLink', hostValue, attachInfo)
+     */
     getValue: (hostValue: BV, ownValue: OV, attachInfo?: any) => void;
 }
-export interface FormItemConfig<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>, PK extends Extract<keyof PO, string> = Extract<keyof PO, string>, PV extends PO[PK] = PO[PK], SV extends PK extends keyof SO ? SO[PK] : PV = PK extends keyof SO ? SO[PK] : PV> {
+/** formItem配置 */
+export interface FormItemConfig<PO extends Record<string, any> = Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any> = Record<string, any>, 
+/** 解析的模型的key */
+PK extends Extract<keyof PO, string> = Extract<keyof PO, string>, 
+/** 解析的模型的值 */
+PV extends PO[PK] = PO[PK], 
+/** 需要格式化的模型的值 */
+SV extends PK extends keyof SO ? SO[PK] : PV = PK extends keyof SO ? SO[PK] : PV> {
+    /** 表单项key __大写视为忽略 等价于 ignore = true */
     key: PK;
+    /** 表单项label */
     label: string;
+    /**
+     * 隐藏 label 且不占位（label-wrap 整体 display:none，表单元素顶满整行）。
+     * 仅当 label 有值时生效——无 label 时 element-plus 会给 content 加 margin-left 留白，需改用 labelWidth:0。
+     */
     labelHide?: boolean;
+    /** 提示信息 */
     tip?: string | (() => VNode);
+    /** 表单布局 优先级高于FormMain同名属性 */
     layout?: Partial<ColProps>;
+    /** 表单外FormItem属性 */
     wrapProps?: Partial<WrapProps> | ((scope: FormScope<PO, SO, PK, PV, SV>) => Partial<WrapProps>);
+    /** 表单主体属性 */
     props?: Record<string, any> | ((scope: FormScope<PO, SO, PK, PV, SV>) => Record<string, any>);
+    /** 表单渲染函数/渲染标签/组件 */
     render?: string | Record<string, any> | ((props: {
         modelValue: PV;
         ["onUpdate:modelValue"]: (value: PV) => void;
         placeholder?: string;
         ["onTriggerChangeLink"]?: (value: SV, attachInfo?: any) => void;
     } & Record<string, any>) => VNode);
+    /** 表单校验规则 */
     rules?: FormItemRule[] | ((scope: FormScope<PO, SO, PK, PV, SV>) => FormItemRule[]);
+    /** 表单初始值 */
     init?: (() => PV) | PV;
+    /** 表单回显解析处理 */
     parse?: (value: any, parseData: Partial<PO>, originData: ExtractFormStringifyFromObject<PO, SO>) => PV | void;
+    /** 表单序列化处理 */
     stringify?: (value: any, stringifyData: Partial<ExtractFormStringifyFromObject<PO, SO>>, originData: PO) => SV | void;
+    /**
+     * 是否在初始化数据、解析数据、序列化数据时忽略处理
+     */
     ignore?: boolean;
+    /**
+     * 是否在表单中隐藏
+     */
     hide?: boolean | ((scope: FormScope<PO, SO, PK, PV, SV> & {
         getInitValue: () => PV;
     }) => boolean);
+    /**
+     * 被关联配置
+     * 1. 不要配置当前表单项的key
+     * 2. 最好不要循环关联
+     * 3. 必须循环关联时，避免循环引用
+     */
     beLink?: FormItemLinkConfig<PK, PV, any> | FormItemLinkConfig<PK, PV, any>[];
+    /**
+     * 额外一些配置
+     */
     extra?: FormItemConfigExtra;
 }
+/** form配置 */
 export type FormItemConfigList<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> = FormItemConfig<PO, SO>[];
-export type FormModel<L> = L extends FormItemConfigList<infer PO, any> ? PO : Record<string, any>;
+/** 表单数据 */ export type FormModel<L> = L extends FormItemConfigList<infer PO, any> ? PO : Record<string, any>;
+/** 提取格式化原始对象 */
 export type ExtractFormStringifyRawFromObject<PO extends Record<string, any>, SO extends Record<string, any>> = {
     [K in keyof PO | keyof SO]: K extends keyof SO ? SO[K] extends never ? never : SO[K] extends undefined ? K extends keyof PO ? PO[K] : never : SO[K] : K extends keyof PO ? PO[K] : never;
 };
+/** 表单序列化数据原始 */
 export type ExtractFormStringifyRawFromList<L> = L extends FormItemConfigList<infer PO, infer SO> ? PO extends Record<string, any> ? SO extends Record<string, any> ? ExtractFormStringifyFromObject<PO, SO> : Record<string, any> : Record<string, any> : Record<string, any>;
+/** 提取除never以外的属性值 */
 export type ExcludeNeverProperties<T> = {
     [K in keyof T as T[K] extends never ? never : K]: T[K];
 };
 export type ExtractFormStringifyFromObject<PO extends Record<string, any>, SO extends Record<string, any>> = ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>;
+/** 表单序列化数据 */
 export type ExtractFormStringifyFromList<L> = ExcludeNeverProperties<ExtractFormStringifyRawFromList<L>>;
-export interface FormScope<PO extends Record<string, any>, SO extends Record<string, any>, PK extends Extract<keyof PO, string>, PV extends PO[PK], SV extends PK extends keyof SO ? SO[PK] : PV> {
+/** form作用域数据 */
+export interface FormScope<
+/** 解析的模型 */
+PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>, 
+/** 解析的模型的key */
+PK extends Extract<keyof PO, string>, 
+/** 解析的模型的值 */
+PV extends PO[PK], 
+/** 需要格式化的模型的值 */
+SV extends PK extends keyof SO ? SO[PK] : PV> {
     data: PO;
     config: FormItemConfig<PO, SO, PK, PV, SV>;
 }
+/** FormMain expose类型 */
 export interface FormMainInstance<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> {
     validate: () => Promise<void>;
     resetFields: () => void;
@@ -68,46 +139,83 @@ export interface FormMainInstance<PO extends Record<string, any> = Record<string
     parse: (stringifyData: ExtractFormStringifyFromObject<PO, SO>) => PO;
     stringify: () => ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>;
 }
+/** FormSearch expose类型 */
 export interface FormSearchInstance<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> extends Omit<FormMainInstance<PO, SO>, "generate" | "parse" | "stringify"> {
+    /** 触发搜索 */
     triggerSearch: () => void;
+    /** 触发重置 */
     triggerReset: () => void;
+    /** 切换折叠状态 */
     toggleCollapse: (nextValue?: boolean) => void;
+    /** 当前折叠状态 */
     isCollapsed: ComputedRef<boolean>;
 }
+/** FormItem props */
 export interface FormMainItemProps {
     config: FormItemConfig<Record<string, any>, Record<string, any>>;
     data: Record<string, any>;
 }
+/** FormMain props */
 export interface FormMainProps<PO extends Record<string, any>, SO extends Record<string, any>> {
     list: FormItemConfigList<PO, SO>;
     data: PO;
     layout?: Partial<ColProps>;
     rowGutter?: number;
+    /** P3 嵌套 rebase 累乘因子（缺省 1 = 顶级行为不变，向后兼容）。由联结薄壳算出后传子 FormMain */
     layoutScale?: number;
+    /**
+     * 布局按**容器断点**校准（默认 false = 与现状零差异）。
+     * ElCol 响应式 span（xs/sm/md/lg/xl）默认按 window 宽的 CSS 媒体查询解析——
+     * 表单被塞进窄容器（弹窗/分栏/侧栏）时 window 是 lg 而容器只有 sm 宽，`lg:6`
+     * 仍生效致单行挤爆。开启后以 FormMain 根自身宽（= 直接父容器内容宽）定档，
+     * 把响应式配置解析成该档**定值 span**（剥除断点键，window 媒体查询不再参与）。
+     * FormSearch 同名 prop 会把折叠几何引擎断点源一并切到容器档（两引擎同源），
+     * 并透传本 prop 给内部 FormMain；ListPage 经 `formSearchProps` 透传。
+     * 嵌套子表单（FormNest 等联结组件）是独立 FormMain 实例，需各自开启。
+     */
     layoutByContainer?: boolean;
 }
+/** FormSearch props */
 export interface FormSearchProps<PO extends Record<string, any>, SO extends Record<string, any>, SQ extends Record<string, any>> extends FormMainProps<PO, SO> {
     labelPosition?: "right" | "left" | "top";
     labelWidth?: string;
+    /** 静态参数(非表单 非分页参数) */
     staticQuery?: SQ;
+    /**
+     * 收起态最多渲染的视觉行数（**含操作区所在行**），0 = 不折叠全展开。默认 2。
+     * 行数按真实几何换行计算（支持单项异构 span 混排）：装不下的项折叠进「展开更多」，
+     * 操作区（重置/查询）恒在最后一行贴右下。
+     */
     maxRows?: number;
+    /**
+     * 受限空间（窄侧栏）模式——只校准布局，忽略容器盲的窗口断点：
+     * - 每项 layout（含单项自定义 layout）统一强制单列 span 24；
+     * - labelPosition→"top"（窄列右对齐+auto 宽挤，改顶部让输入吃满宽）。
+     * maxRows（折叠）不受 compact 干预、始终外部可控：单列下操作区独占一行，
+     * maxRows=2 即「1 项 + 操作区行（含展开更多）」，想全展开传 maxRows:0。
+     * 缺省 false = 行为不变（零回归）。
+     */
     compact?: boolean;
 }
+/** form item loading 信息 */
 export interface FormItemLoadingInfo {
     key: string;
     label: string;
     message: string;
 }
+/** form item 加载状态信息 */
 export type FormItemLoadingChangeFunc = (data: {
     key: string;
     message?: string;
 }) => void;
+/** 选项类型 */
 export interface OptionItem extends Record<string, any> {
     label: string | number;
     value: string | number;
     disabled?: boolean;
     [key: string]: any;
 }
+/** form tree 单项类型 */
 export interface FormTreeItem {
     id: string | number;
     label: string;
@@ -115,46 +223,138 @@ export interface FormTreeItem {
     disabled?: boolean;
     [key: string]: any;
 }
+/** form单项表单提交类型 */
 export type FormItemSubmitType = "blur" | "change" | "enter";
+/** 表单搜索搜索类型 */
 export type FormSearchSearchType = "search" | "reset" | FormItemSubmitType;
+/**
+ * ElDatePicker 原生 `shortcuts` 项（时间段快捷）。
+ * 直接传给 `<ElDatePicker :shortcuts="...">`，由 ElDatePicker 自身的
+ * pick 管线按其 value-format 归一化输出，无需额外格式化依赖。
+ */
 export interface DatePickerShortcut {
     text: string;
     value: () => [Date, Date];
 }
-export type FormItemConfigSwiftOptionsCommon<PO extends Record<string, any>, SO extends Record<string, any>> = Omit<FormItemConfig<PO, SO>, "rules"> & {
+export type FormItemConfigSwiftOptionsCommon<PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>> = Omit<FormItemConfig<PO, SO>, "rules"> & {
+    /** label */
+    /**
+     *  表单类型
+     * ----
+     *  input: 会补齐 extra.isInput = true 最终表现在组件会默认设置placeholder `请输入${label}`,同时如果设置了required 会自动添加一条校验规则 提示信息同 placeholder;
+     *
+     *  select: 会补齐 extra.isSelect = true 最终表现在组件会默认设置placeholder `请选择${label}`,同时如果设置了required 会自动添加一条校验规则 提示信息同 placeholder;
+     *  如果不设置此项 不会补齐 extra
+     */
     type?: "input" | "select";
 };
-export interface FormItemConfigSwiftOptionsRequired<PO extends Record<string, any>, SO extends Record<string, any>> extends FormItemConfigSwiftOptionsCommon<PO, SO> {
+/** 表单配置项快捷生成类型 - 设置required */
+export interface FormItemConfigSwiftOptionsRequired<PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>> extends FormItemConfigSwiftOptionsCommon<PO, SO> {
+    /**
+     * 是否必填
+     * -----
+     * 设置了此项 不能设置 rules, 如果校验规则只是验证必填 使用此选项更方便
+     */
     required?: true;
 }
-export interface FormItemConfigSwiftOptionsRules<PO extends Record<string, any>, SO extends Record<string, any>> extends FormItemConfigSwiftOptionsCommon<PO, SO> {
+/** 表单配置项快捷生成类型 - 设置rules */
+export interface FormItemConfigSwiftOptionsRules<PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>> extends FormItemConfigSwiftOptionsCommon<PO, SO> {
+    /**
+     * 校验规则
+     * ---
+     * 设置了此项 不能直接设置 required, 如果校验规则特殊 或者 要基于数据值动态校验 请使用 rules
+     */
     rules?: FormItemConfig["rules"];
 }
-export interface FormDataInfo<PO extends Record<string, any>, SO extends Record<string, any>> {
+/** 表单数据信息 */
+export interface FormDataInfo<PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>> {
+    /** 表单模型数据 */
     parseData: PO;
+    /** 表单序列化数据 */
     stringifyData: ExtractFormStringifyFromObject<PO, SO>;
 }
-export type FormItemConfigSwiftOptions<PO extends Record<string, any>, SO extends Record<string, any>> = FormItemConfigSwiftOptionsRequired<PO, SO> | FormItemConfigSwiftOptionsRules<PO, SO>;
+/** 表单配置项快捷生成类型 */
+export type FormItemConfigSwiftOptions<PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>> = FormItemConfigSwiftOptionsRequired<PO, SO> | FormItemConfigSwiftOptionsRules<PO, SO>;
+/** 表单提交按钮 */
 export type FormSubmitBtnProps<PO extends Record<string, any>, SO extends Record<string, any>> = Omit<ButtonProps, "loading"> & {
+    /** form main expose */
     formMainInstance: FormMainInstance<PO, SO>;
+    /** 提交按钮文本 */
     submitText?: string;
+    /** 提交方法 */
     submitFn: (stringifyData: ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>) => Promise<unknown>;
+    /** 提交入口旁路（点击意图，validate 前同步调；不受校验成败影响） */
     onSubmitStart?: () => void;
 };
+/** 表单提交按钮扁平属性 */
 export type FormSubmitPanelFlatProps = Extract<keyof FormSubmitBtnProps<Record<string, any>, Record<string, any>>, "submitText" | "submitFn">;
+/**
+ * 表单提交面板 props——= FormMain props 透传 + 提交相关。
+ * 容器内编排 FormMain + FormSubmitBtn（formMainInstance 内部自动接线），对称 FormSearch。
+ */
 export type FormSubmitPanelProps<PO extends Record<string, any>, SO extends Record<string, any>> = Omit<FormMainProps<PO, SO>, "data"> & {
+    /**
+     * 序列化的数据
+     * -----
+     * 此属性不为空 那么优先使用此字段转换为PO数据模型， 否则内部会基于表单配置化 生成初始化 PO 数据模型
+     */
     stringifyData?: ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>;
 } & Pick<FormSubmitBtnProps<PO, SO>, FormSubmitPanelFlatProps> & {
     submitBtnProps?: Omit<FormSubmitBtnProps<PO, SO>, FormSubmitPanelFlatProps | "formMainInstance">;
 } & {
     labelPosition?: "right" | "left" | "top";
     labelWidth?: string;
+    /**
+     * 取消按钮
+     * -----
+     * 同名插槽优先级高于props,如果是props则只是取消按钮的文字 为空则不展示
+     * ----
+     * 默认的cancelBtn插槽的按钮点击后触发 cancel 事件
+     */
     cancelBtn?: string;
+    /** 重置按钮
+     * -----
+     * 同名插槽优先级高于props,如果是props则只是重置按钮的文字 为空则不展示
+     * ----
+     * 默认的resetBtn插槽的按钮点击后重置内部 parseData，并通过 parseDataChange 通知外部
+     */
     resetBtn?: string;
+    /** 操作区位置
+     * ----
+     * 默认值 bottom-center
+     */
     operationPosition?: "bottom-center" | "bottom-right" | "top-right";
+    /** 操作区是否做图钉
+     * ----
+     * 默认值 false
+     */
     operationAffix?: boolean | AffixProps;
+    /** 操作区分隔线（含外侧圆角）
+     * ----
+     * 默认值 true；置 false 去掉分隔线 + 圆角（极简 / 单按钮场景）
+     */
     divider?: boolean;
+    /** 操作区无内边距（bare）
+     * ----
+     * 默认 false；置 true 去掉操作区 padding（嵌入 / 极简场景）。
+     * 与 divider 正交：divider 管边框+圆角，bare 管 padding，可叠加全 flush。
+     */
     bare?: boolean;
+    /** 根面板自定义 class（显式根出口）
+     * ----
+     * inheritAttrs:false 下消费方 `class` 经 v-bind 转发内层 FormMain（对标 FormSearch），
+     * 根面板 `.form-submit-panel` 拿不到。需给根面板加类时用本 prop。
+     */
     rootClass?: string | string[] | Record<string, boolean>;
 };
 export {};

package/types/components/form/use-form-submit.d.ts

@@ -1,14 +1,27 @@
 import { Ref } from 'vue';
 import { FormMainInstance, FormSubmitBtnProps, FormDataInfo } from './types';
+/** useFormSubmit 入参——提交管线的 4 个外部接线点 */
 export interface UseFormSubmitOptions<PO extends Record<string, any>, SO extends Record<string, any>> {
+    /** 惰性取 FormMain 实例（首渲染 undefined 容忍，click 时才用） */
     getFormMainInstance: () => FormMainInstance<PO, SO>;
+    /** 提交方法（每次调用时读取，保留响应式） */
     submitFn: FormSubmitBtnProps<PO, SO>["submitFn"];
+    /** 提交入口旁路（点击意图，validate 前同步调；不受校验成败影响） */
     onSubmitStart?: () => void;
+    /** 成功回调（载荷 = stringifyData） */
     onSuccess?: (data: FormDataInfo<PO, SO>["stringifyData"]) => void;
+    /** 失败回调（校验未过 / submitFn reject） */
     onFail?: (error: unknown) => void;
 }
+/** useFormSubmit 返回——loading 态 + 提交触发器 */
 export interface UseFormSubmitReturn {
+    /** 提交中 loading 态 */
     submitting: Ref<boolean>;
+    /** 触发提交：validate → stringify → submitFn → onSuccess / onFail */
     submit: () => Promise<void>;
 }
+/**
+ * 表单提交管线 composable——validate→stringify→submitFn 全程接管 loading。
+ * FormSubmitBtn 与 FormSubmitPanel(#submitBtn slot) 共用，单一事实源。
+ */
 export declare function useFormSubmit<PO extends Record<string, any>, SO extends Record<string, any>>(options: UseFormSubmitOptions<PO, SO>): UseFormSubmitReturn;

package/types/components/form/use-layout-by-container.d.ts

@@ -1,11 +1,34 @@
 import { Breakpoint } from '../../hooks';
 import { ColProps, FormInstance } from 'element-plus';
+/**
+ * 把（已经 `resolveFormLayout` 合并/回填/缩放后的）layout 按**指定断点**解析成
+ * 定值列配置：取 `merged[breakpoint]`（number → 定值 span / 对象型 → 整体展开覆盖
+ * base 的 span/offset 等 / undefined → 保留 base），并**剥除五断点键**——输出定值
+ * 后若保留响应式键，ElCol 的 window 媒体查询类会与定值打架。
+ * ---
+ * 档位取值语义与 FormSearch 几何引擎（`getCurrentSpan` / `resolveSearchItemOccupancy`：
+ * 断点直取 + base span 兜底）同构——`resolveFormLayout` 已把 span 回填到五断点，
+ * 直取即命中；[MUST NOT] 另造级联语义分裂两引擎。
+ */
 export declare const resolveFormLayoutAtBreakpoint: (merged: Partial<ColProps>, breakpoint: Breakpoint) => Partial<ColProps>;
+/**
+ * useFormLayoutByContainer 入参——容器断点校准对主体 setup 的全部接线点
+ * （getter 保留响应式）。只读不写：校准是布局数据路径的纯下游变换。
+ */
 export interface UseFormLayoutByContainerOptions {
+    /** layoutByContainer prop：容器断点校准开关 */
     enabled: () => boolean;
+    /** ElForm 实例（容器档挂靶目标 = 表单根，块级恒等于直接父容器内容宽） */
     getForm: () => FormInstance | undefined;
 }
+/** useFormLayoutByContainer 返回——mergeLayout 尾部的单点委托变换 */
 export interface UseFormLayoutByContainerReturn {
+    /** 开启时按容器档把 layout 解析成定值（剥五断点键）；关闭时恒等返回（原路径零改） */
     resolveLayoutByContainer: (merged: Partial<ColProps>) => Partial<ColProps>;
 }
+/**
+ * FormMain 容器断点校准（layoutByContainer）专属 composable——RO 挂靶 / 容器档
+ * 解析等机制全收于此，主体 setup 只留一行委托 + mergeLayout 尾部单点变换；
+ * 后续删除该功能 = 删本文件 + 组件内委托行 + prop（+ FormSearch 同源切换行），分界明确。
+ */
 export declare function useFormLayoutByContainer(options: UseFormLayoutByContainerOptions): UseFormLayoutByContainerReturn;

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

@@ -1,7 +1,20 @@
 import { MaybeRefOrGetter } from 'vue';
 import { FormMainInstance } from './types';
 export interface UseNestFormListOptions {
+    /** 当前存活行子 FormMain 实例（getter，每次取最新存活集合） */
     rowInstances: () => FormMainInstance[];
+    /**
+     * 父 item key——注册到父 FormMain exposeMap 的索引（C4 必传）；
+     * 无父 FormMain registry（脱离嵌套上下文）时 inject 返回 null → 跳过注册。
+     */
     key?: MaybeRefOrGetter<string | undefined>;
 }
+/**
+ * 数组子表单聚合注册 composable（C4 配套，ADR-1/2）
+ * ----
+ * 向最近祖先 FormMain registry 注册【1 个聚合 expose】（key = 本 item key），方法体
+ * fan-out 遍历当前存活 N 行子 FormMain：validate=Promise.all、clearValidate/resetFields=forEach。
+ * → 父 registry 仍「1 item 1 entry」，父 validate 的 hideKeyList 过滤按 item key 命中（守 ADR-8）。
+ * 职责收窄：仅聚合注册 + 摘除，[MUST NOT] 碰值贯通 / 增删（组件自管）。
+ */
 export declare function useNestFormList(options: UseNestFormListOptions): void;

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

@@ -1,9 +1,24 @@
 import { MaybeRefOrGetter, Ref } from 'vue';
 import { FormMainInstance } from './types';
 export interface UseNestFormOptions {
+    /** 子 FormMain 实例 ref（联结组件内 FormMain 的 defineExpose） */
     childRef: Ref<FormMainInstance | undefined>;
+    /**
+     * 所属父 item key——注册到父 FormMain exposeMap 时必传（C1 form 族，作 map 索引）；
+     * panel 上下文（C3）无父 FormMain exposeMap，可省（inject 返回 null → 跳过注册）。
+     * 接受 ref/getter，挂载/摘除时经 toValue 取值（避免 setup 根作用域读 props 失响应式）。
+     */
     key?: MaybeRefOrGetter<string | undefined>;
 }
+/**
+ * 嵌套联结组件子表单接线 composable
+ * ----
+ * 职责（ADR-7，刻意收窄）：
+ * 1. 代理子 FormMain 的 validate / clearValidate / resetFields；
+ * 2. context 自适应注册——inject 到最近祖先 FormMain 的 exposeMap 则按 key 写入（onMounted）+
+ *    删除（onBeforeUnmount）；无（panel 上下文）则跳过。
+ * [MUST NOT] 在此处理值贯通——值语义 form/panel 两族不同（ADR-5），由各联结组件自管。
+ */
 export declare function useNestForm(options: UseNestFormOptions): {
     validateChild: () => Promise<void>;
     clearChild: (k?: string) => void;

package/types/components/form/use-nest-layout-scale.d.ts

@@ -1,5 +1,17 @@
 import { MaybeRefOrGetter, ComputedRef } from 'vue';
+/**
+ * 联结薄壳计算子 Form/PanelMain 的嵌套布局 rebase 因子（P3，4 薄壳共用）。
+ * ----
+ * `childScale = parentScale × (24 / parentSpan)`：
+ * - parentScale 经 inject 从最近祖先 Form/PanelMain 取（顶级 / 未嵌套 → 缺省 1）；
+ * - parentSpan = 父 item 实际分配的代表 span（薄壳由 helper 经 props 传入，缺省 24 = 本层不缩）；
+ * - `rebase === false`（逆向逃生口）→ 不叠本层因子（= parentScale），layout 原样直透子层。
+ * ----
+ * 返回 ComputedRef，薄壳作 `layoutScale` 传子 FormMain/PanelMain（其再 resolveFormLayout 取整到档集）。
+ */
 export declare function useNestLayoutScale(options: {
+    /** 父 item 代表 span（来自 helper 的 resolveLayoutSpan(layout)） */
     parentSpan: MaybeRefOrGetter<number | undefined>;
+    /** 是否叠本层 rebase 因子（缺省 true；false = 逆向逃生口） */
     rebase: MaybeRefOrGetter<boolean | undefined>;
 }): ComputedRef<number>;

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

@@ -1,32 +1,87 @@
 import { DatePickerShortcut, FormItemConfig, FormItemConfigList, ExtractFormStringifyFromObject, FormItemConfigSwiftOptions } from './types';
 import { ColProps } from 'element-plus';
+/**
+ * 嵌套布局 rebase 的栅格档集（P3）。
+ * ---
+ * FormMain/PanelMain 配置化 `span` 约定用 24 的约数 {6,8,12,24}（admin 常用档）；
+ * 子层 rebase（×scale）后 ceil 到这组档，避免非约数（18/16/7）致行铺不满 ragged。
+ */
 export declare const NEST_LAYOUT_TIERS: readonly [6, 8, 12, 24];
+/**
+ * 把数值 ceil 到档集中 ≥ value 的最近一档（偏宽取向）。
+ * ---
+ * - value ≤ 下限 → 取下限；value ≥ 上限 → 封顶上限。
+ * - 落档间 → 抬到上一档（如 16 → 24，非更近的 12），合「容器窄字段更宽」意图。
+ */
 export declare const ceilToTier: (value: number, tiers?: readonly number[]) => number;
+/**
+ * 从 layout 解析父 item 实际分配的代表 span（P3 rebase 算因子用）。
+ * ---
+ * span 优先；无 span 时取 lg→md→sm→xl→xs 首个数值断点代表；都无 → 24（本层不缩）。
+ */
 export declare const resolveLayoutSpan: (layout?: Partial<ColProps>) => number;
+/**
+ * 将 layout 解析为各屏幕尺寸的显式值：
+ * - 配置 span: xxx 时，xs/sm/md/lg/xl 默认全部视为 xxx
+ * - 单独设置某个尺寸则该尺寸覆盖 span 推导值
+ * ---
+ * **P3 嵌套 rebase**：可选第 2 参 `scale`（嵌套累乘因子，缺省 1）。
+ * - `scale === 1` → 现状行为不变（非档值原样透传，[MUST NOT] ceil，向后兼容关键）。
+ * - `scale !== 1` → span 及各断点数值 `× scale` 后经 `ceilToTier` 取整到档集，
+ *   维持子层字段绝对宽与顶级一致（容器变窄 → span 变大）。
+ */
 export declare const resolveFormLayout: (layout?: Partial<ColProps>, scale?: number) => Partial<ColProps>;
+/**
+ * 生成 ElDatePicker 原生 `shortcuts` 的默认时间段快捷值：今日、昨日、近7日。
+ * 直接用于 `<ElDatePicker :shortcuts="getDatePickerShortcuts()">`——
+ * 由 ElDatePicker 自身 pick 管线按其 value-format 归一化输出，
+ * 与手动选日期完全同源，无需任何额外格式化依赖。
+ */
 export declare const getDatePickerShortcuts: () => DatePickerShortcut[];
+/**
+ * 生成表单数据
+ */
 export declare const generateFormData: <PO extends Record<string, any>, SO extends Record<string, any>>(list: FormItemConfigList<PO, SO>) => PO;
+/**
+ * 解析表单数据
+ */
 export declare const parseFormData: <PO extends Record<string, any>, SO extends Record<string, any>>(data: ExtractFormStringifyFromObject<PO, SO>, list: FormItemConfigList<PO, SO>) => PO;
+/**
+ * 序列化表单数据
+ */
 export declare const stringifyFormData: <PO extends Record<string, any>, SO extends Record<string, any>>(data: PO, list: FormItemConfigList<PO, SO>) => import('./types').ExcludeNeverProperties<import('./types').ExtractFormStringifyRawFromObject<PO, SO>>;
+/**
+ * 获取v-model语法糖配置
+ */
 export declare const getVModelSugar: <PO extends Record<string, any>, SO extends Record<string, any>, PK extends Extract<keyof PO, string>, MK extends string>({ modelValueKey, config, data, updateData, }: {
     modelValueKey?: MK;
     config: FormItemConfig<PO, SO>;
     data: PO;
     updateData?: (val: PO[PK]) => void;
 }) => { [P in MK]: PO[PK]; } & { [E in string as `onUpdate:${MK}`]: (val: PO[PK]) => void; };
+/** 获取placeholder */
 export declare const getPlaceholder: <PO extends Record<string, any>, SO extends Record<string, any>>(config: FormItemConfig<PO, SO>) => {
     placeholder?: string;
 };
+/** 获取回车提交 */
 export declare const getEnterSubmit: <PO extends Record<string, any>, SO extends Record<string, any>>(config: FormItemConfig<PO, SO>, handler: () => void) => {
     onKeyup: (e: KeyboardEvent) => void;
 } | undefined;
+/** 获取失去焦点提交 */
 export declare const getBlurSubmit: <PO extends Record<string, any>, SO extends Record<string, any>>(config: FormItemConfig<PO, SO>, handler: () => void) => {
     onBlur: () => void;
 } | undefined;
+/** 获取变化提交 */
 export declare const getChangeSubmit: <PO extends Record<string, any>, SO extends Record<string, any>>(config: FormItemConfig<PO, SO>, handler: () => void) => {
     onChange: () => void;
 } | undefined;
+/** form item 更改loading状态 */
 export declare const FORM_ITEM_CHANGE_LOADING: unique symbol;
+/** 设置输入类型组件 */
 export declare const setInputComponent: (components: any[]) => void;
+/** 设置选择类型组件 */
 export declare const setSelectComponent: (components: any[]) => void;
-export declare const swiftFormItemConfig: <PO extends Record<string, any>, SO extends Record<string, any>>(options: FormItemConfigSwiftOptions<PO, SO>) => FormItemConfig<PO, SO>;
+/** 快捷配置表单项 */
+export declare const swiftFormItemConfig: <PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>>(options: FormItemConfigSwiftOptions<PO, SO>) => FormItemConfig<PO, SO>;

package/types/components/list-page/ListPage.vue.d.ts

@@ -36,15 +36,21 @@ declare const _default: <T extends Record<string, any>, PO extends Record<string
     expose(exposed: import('vue').ShallowUnwrapRef<ListPageInstance<PO, Record<string, any>>>): void;
     attrs: any;
     slots: Readonly<{
+        /** 头部插槽（无 scope） */
         header?: () => VNode[];
+        /** 操作区插槽（无 scope） */
         operation?: () => VNode[];
+        /** 自定义视图项插槽 */
         "custom-view-item"?: (scope: DataListViewItemScope<T>) => VNode[];
     } & { [K in `form-${Extract<keyof PO, string>}`]?: ((scope: FormScope<PO, SO, Extract<keyof PO, string>, any, any>) => VNode[]) | undefined; } & { [K_1 in `table-${Uppercase<string>}` | `table-${Exclude<Extract<keyof T, string>, "item" | "custom-view-item"> & {}}`]?: ((scope: TableColumnDefaultScope<T, ListPageInnerInjectInfo<PO, F>>) => VNode[]) | undefined; } & { [K_2 in `table-header-${Uppercase<string>}` | `table-header-${Exclude<Extract<keyof T, string>, "item" | "custom-view-item"> & {}}`]?: ((scope: TableColumnHeaderScope<T, ListPageInnerInjectInfo<PO, F>> & {
         searchFormData: PO;
         triggerSearch: (() => void) | undefined;
     }) => VNode[]) | undefined; }> & {
+        /** 头部插槽（无 scope） */
         header?: () => VNode[];
+        /** 操作区插槽（无 scope） */
         operation?: () => VNode[];
+        /** 自定义视图项插槽 */
         "custom-view-item"?: (scope: DataListViewItemScope<T>) => VNode[];
     } & { [K in `form-${Extract<keyof PO, string>}`]?: ((scope: FormScope<PO, SO, Extract<keyof PO, string>, any, any>) => VNode[]) | undefined; } & { [K_1 in `table-${Uppercase<string>}` | `table-${Exclude<Extract<keyof T, string>, "item" | "custom-view-item"> & {}}`]?: ((scope: TableColumnDefaultScope<T, ListPageInnerInjectInfo<PO, F>>) => VNode[]) | undefined; } & { [K_2 in `table-header-${Uppercase<string>}` | `table-header-${Exclude<Extract<keyof T, string>, "item" | "custom-view-item"> & {}}`]?: ((scope: TableColumnHeaderScope<T, ListPageInnerInjectInfo<PO, F>> & {
         searchFormData: PO;