@done-coding/admin-core 0.18.0 → 0.19.0

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

@@ -6,27 +6,75 @@ export type FormSearchRewriteKey = "list";
 export type TableMainOptionsKey = "refine" | "refineReduceHeight" | "viewportHeight" | "parentChannel" | "toolbar" | "showSwitchView";
 export type TableMainRequiredKey = "columns" | "rowKey";
 export type TableMainRewriteKey = "api" | "query" | "injectInfo";
-export type ListPageInnerInjectInfo<PO extends Record<string, any>, F extends Record<string, any>> = Pick<ListPageInstance<PO>, "triggerReset" | "triggerSearch" | "update"> & F;
-export type ListPageProps<T extends Record<string, any>, PO extends Record<string, any>, SO extends Record<string, any>, SQ extends Record<string, any>, F extends Record<string, any>> = Partial<Pick<FormSearchProps<PO, SO, {}>, FormSearchOptionsKey>> & {
+export type ListPageInnerInjectInfo<PO extends Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any>> = Pick<ListPageInstance<PO>, "triggerReset" | "triggerSearch" | "update"> & F;
+export type ListPageProps<
+/** 行数据结构 */
+T extends Record<string, any>, 
+/** 表单标准结构模型 */
+PO extends Record<string, any>, 
+/** 表单需转换的部分结构模型 */
+SO extends Record<string, any>, 
+/** 静态参数 */
+SQ extends Record<string, any>, 
+/** 期望注入到表格列插槽上的额外内容 */
+F extends Record<string, any>> = Partial<Pick<FormSearchProps<PO, SO, {}>, FormSearchOptionsKey>> & {
     formSearchProps?: Partial<Omit<FormSearchProps<PO, SO, {}>, FormSearchOptionsKey | FormSearchRewriteKey | "compact">>;
 } & Pick<TableMainProps<T, ExtractFormStringifyFromObject<PO, SO> & SQ, ListPageInnerInjectInfo<PO, F>>, TableMainRequiredKey> & Partial<Pick<TableMainProps<T, ExtractFormStringifyFromObject<PO, SO> & SQ, ListPageInnerInjectInfo<PO, F>>, TableMainOptionsKey>> & {
     tableMainProps?: Partial<Omit<TableMainProps<T, ExtractFormStringifyFromObject<PO, SO> & SQ, ListPageInnerInjectInfo<PO, F>>, TableMainOptionsKey | TableMainOptionsKey | TableMainRewriteKey>>;
 } & {
     list?: FormItemConfigList<PO, SO>;
+    /** api */
     api: (params: TableApiParams<ExtractFormStringifyFromObject<PO, SO> & SQ>) => Promise<TableApiResult<T>>;
+    /** 静态参数 */
     query?: SQ;
     injectInfo?: F;
+    /** 搜索前的回调[同步] */
     beforeSearch?: (data: ExtractFormStringifyFromObject<PO, SO>, type: FormSearchSearchType) => ExtractFormStringifyFromObject<PO, SO>;
+    /** 在点击搜索重置按钮时，是否同时调用清空表格表头过滤 */
     clearTableFilterOnReset?: boolean;
+    /**
+     * 搜索是否分离为侧栏。
+     * - false（默认）：header/搜索/operation 纵向内联在表格上方（与旧版逐像素一致）。
+     * - true：header/搜索/operation 整体移入侧栏，主区只余表格。
+     */
     separateSearch?: boolean;
+    /**
+     * 分离侧栏布局配置（透传 SlotLayoutFlowAside 的 type/gap/asideWidth）。
+     * asideMaxHeight 不在此列——由 ListPage 内部按 viewport 高度消化后自动提供。
+     */
     separateSearchConfig?: Pick<SlotLayoutFlowAsideProps, "type" | "gap" | "asideWidth">;
+    /**
+     * FormSearch 粘性：容器/页面滚动时搜索区钉在滚动视口顶部（默认 false 不开启）。
+     * 典型场景：refine 计算可用高低于表格下界（dataViewMaxHeightMinValue）被顶破出滚动条时，
+     * 下滚看表格搜索区不滚走。只粘搜索区（header 槽随流滚走、operation 滚上来被盖过）。
+     * 分离态（separateSearch=true）搜索在自滚侧栏内、粘性无意义——该开关被完全无视。
+     */
     searchSticky?: boolean;
+    /**
+     * 表格 toolbar 粘性：容器/页面滚动时 TableMain 的 toolbar 钉在滚动视口顶部
+     * （默认 false 不开启）。与 separateSearch 无关——分离与否表格都在主滚动流里。
+     * 与 searchSticky 同开（非分离态）时自动叠钉在粘住的搜索区正下方。
+     */
     toolbarSticky?: boolean;
+    /**
+     * 表格分页器粘性：容器/页面滚动时 TableMain 的分页器钉在滚动视口底部
+     * （默认 false 不开启）。与 separateSearch 无关——分离与否表格都在主滚动流里。
+     */
     pagerSticky?: boolean;
+    /**
+     * header 插槽量高是否启用 ResizeObserver（透传 WatchSize observeResize，默认 false）。
+     * 默认时机（激活首测 + window resize + onUpdated）覆盖重渲染驱动的高度变化；槽内有
+     * **异步撑高 / CSS 过渡 / 后代自更新** 等不触发重渲染的变化（如无固定高的图片加载完成）
+     * 时开启，否则表格可用高扣减停在旧值。
+     */
     headerObserveResize?: boolean;
+    /** operation 插槽量高是否启用 ResizeObserver（语义同 headerObserveResize，默认 false）。 */
     operationObserveResize?: boolean;
 };
 export interface ListPageInstance<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> extends FormSearchInstance<PO, SO>, TableMainInstance {
+    /** 更新表单数据 */
     update: (key: Extract<keyof PO, string>, value: any) => void;
 }
 export type ListApiParams<L, SQ extends Record<string, any>> = TableApiParams<ExtractFormStringifyFromList<L> & SQ>;

package/types/components/list-page/use-sticky.d.ts

@@ -1,19 +1,42 @@
 import { ComponentPublicInstance, ComputedRef, ShallowRef } from 'vue';
+/**
+ * useListPageSticky 入参——吸附功能对主体 setup 的全部接线点（getter 保留响应式）。
+ * 只读不写：吸附是主体状态的纯下游，删除功能不影响任何主体逻辑。
+ */
 export interface UseListPageStickyOptions {
+    /** searchSticky prop：搜索区粘顶开关 */
     searchSticky: () => boolean;
+    /** toolbarSticky prop：表格 toolbar 悬浮开关 */
     toolbarSticky: () => boolean;
+    /** pagerSticky prop：分页器底吸开关 */
     pagerSticky: () => boolean;
+    /** separateSearch prop：分离态搜索在自滚侧栏内、粘性无意义（开关被完全无视） */
     separateSearch: () => boolean;
+    /** 搜索区实测盒高（主体 WatchSize 链维护，兼喂高度扣减，非吸附专属故传入不搬移） */
     searchHeight: () => number;
+    /** 搜索区显隐（主体状态） */
     showSearch: () => boolean;
 }
+/** useListPageSticky 返回——模板类绑定 + scoped 样式 v-bind 的全部吸附输出 */
 export interface UseListPageStickyReturn {
+    /** ListPage 根（SlotLayoutFlowAside 根 div）模板 ref——粘性滚动语境的探测锚点 */
     layoutRoot: ShallowRef<ComponentPublicInstance | undefined>;
+    /** 搜索区粘顶生效态（根条件类 list-page_search-sticky） */
     searchStickyActive: ComputedRef<boolean>;
+    /** toolbar 悬浮生效态（根条件类 list-page_toolbar-sticky） */
     toolbarStickyActive: ComputedRef<boolean>;
+    /** 分页器底吸生效态（根条件类 list-page_pager-sticky） */
     pagerStickyActive: ComputedRef<boolean>;
+    /** 搜索区粘住顶距（喂 scoped 样式 v-bind） */
     searchStickyTop: ComputedRef<string>;
+    /** toolbar 粘住顶距（基准 + 搜索叠钉补偿，喂 v-bind） */
     toolbarStickyTop: ComputedRef<string>;
+    /** 分页器粘住底距（喂 v-bind） */
     pagerStickyBottom: ComputedRef<string>;
 }
+/**
+ * ListPage 吸附三件套（searchSticky 粘顶 / toolbarSticky 悬浮 / pagerSticky 底吸）
+ * 专属 composable——服务吸附的探测 / computed / 生命周期全收于此，主体 setup 只留
+ * 一行委托；后续删除该功能 = 删本文件 + 组件内委托行 + 模板类绑定与对应样式块，分界明确。
+ */
 export declare function useListPageSticky(options: UseListPageStickyOptions): UseListPageStickyReturn;

package/types/components/misc/index.d.ts

@@ -3,4 +3,9 @@ import { default as AutoRefresh } from './AutoRefresh.vue';
 import { default as AutoRefreshGroup } from './AutoRefreshGroup.vue';
 import { default as SelectModule } from './SelectModule.vue';
 export * from './types';
-export { TriggerAutoImport, AutoRefresh, AutoRefreshGroup, SelectModule, };
+export { 
+/**
+ * @deprecated 全局样式引入后已无用——main.ts `import "element-plus/dist/index.css"`
+ * + ElementPlusResolver `importStyle: false` 即可，无需本组件触发按需样式。下个 MAJOR 删除。
+ */
+TriggerAutoImport, AutoRefresh, AutoRefreshGroup, SelectModule, };

package/types/components/misc/types.d.ts

@@ -1,10 +1,17 @@
+/** AutoRefresh 组件 props */
 export interface AutoRefreshProps {
+    /** 刷新方法，返回 Promise。失败不影响下轮定时 */
     refreshFn: () => Promise<unknown>;
+    /** 是否不允许自动刷新。true 时清 timer 且不排下轮 */
     disabled?: boolean;
 }
 export interface AutoRefreshGroupProps extends Omit<AutoRefreshProps, "disabled"> {
+    /** 是否显示自动刷新开关 */
     showAutoRefresh?: boolean;
+    /** 是否显示刷新按钮 */
     showRefresh?: boolean;
+    /** 加载是否正在进行中 */
     loading?: boolean;
+    /** 是否需要根节点 */
     needRootNode?: boolean;
 }

package/types/components/modal/ModalConfirm.vue.d.ts

@@ -10,17 +10,46 @@ type __VLS_Props = {
     content?: string | (() => VNode);
     cancelText?: string | (() => VNode);
     confirmText?: string | (() => VNode);
+    /** 是否隐藏取消按钮 */
     hiddenCancel?: boolean;
     width?: number | string;
+    /** 反转按钮位置 */
     reverse?: boolean;
+    /** 按下 ESC 是否关闭 */
     closeOnPressEscape?: boolean;
+    /** 点击遮罩是否关闭 */
     closeOnClickModal?: boolean;
+    /** 是否使用确认按钮loading */
     useLoading?: boolean;
+    /**
+     * 确认按钮 type（对齐 element-plus ElButton type）。
+     * 默认 'primary'；danger / warning / success / info 全枚举均支持,
+     * 与 ActionConfirm popconfirm 模式按钮颜色行为对齐。
+     */
     type?: ButtonProps["type"];
+    /** 弹层形态：'modal'=ElDialog（居中弹窗，默认）｜'drawer'=ElDrawer（抽屉） */
     layerType?: "modal" | "drawer";
+    /**
+     * drawer 形态弹出方向（仅 layerType='drawer' 生效），默认 'rtl'（右侧滑出）。
+     * width 在 drawer 下复用为抽屉尺寸（size），modal 下为弹窗宽度。
+     */
     direction?: "rtl" | "ltr" | "ttb" | "btt";
+    /**
+     * header（标题区）下分割线。缺省按形态取默认：drawer=true / modal=false
+     * （modal 形态默认无分割线，保持既有观感）；显式传值则两形态均生效。
+     */
     headerDivider?: boolean;
+    /**
+     * footer（按钮操作区）上分割线。缺省按形态取默认：drawer=true / modal=false；
+     * 显式传值则两形态均生效。
+     */
     footerDivider?: boolean;
+    /**
+     * modal 形态弹层体可用高的视口预留(px)：向后代 provide 的可用最大高 =
+     * `window.innerHeight - modalReserve`，避免弹窗内有界内容顶天顶底。
+     * 默认 200——与内容区既有上限 `max-height: calc(100vh - 200px)` 同构。
+     * 仅 layerType='modal' 生效（drawer 体高由抽屉尺寸实测）。
+     */
     modalReserve?: number;
 };
 declare function __VLS_template(): {

package/types/components/modal/index.d.ts

@@ -5,4 +5,10 @@ import { default as ModalShelf } from './ModalShelf.vue';
 import { default as ModalPorter } from './ModalPorter.vue';
 export * from './types';
 export * from './modal-shelf-types';
-export { ModalConfirm, ModalForm, ModalDetail, ModalShelf, ModalPorter, ModalConfirm as ConfirmModal, ModalForm as FormModal, ModalDetail as DetailModal, };
+export { ModalConfirm, ModalForm, ModalDetail, ModalShelf, ModalPorter, 
+/** @deprecated 改用 `ModalConfirm`（modal 族统一前缀） */
+ModalConfirm as ConfirmModal, 
+/** @deprecated 改用 `ModalForm`（modal 族统一前缀） */
+ModalForm as FormModal, 
+/** @deprecated 改用 `ModalDetail`（modal 族统一前缀） */
+ModalDetail as DetailModal, };

package/types/components/modal/modal-shelf-core.d.ts

@@ -1,6 +1,9 @@
 import { Ref } from 'vue';
 import { ModalLevel, ShelfController, ShelfItem } from './modal-shelf-types';
+/** ShelfController 内部扩展：额外暴露渲染用活跃实例列表 */
 export interface ShelfControllerInternal extends ShelfController {
+    /** 渲染用：当前活跃实例列表（多例数组） */
     items: Ref<ShelfItem[]>;
 }
+/** 创建一个架子逻辑控制器（纯逻辑，无 DOM 依赖，可单测） */
 export declare function createShelfController(level: ModalLevel): ShelfControllerInternal;

package/types/components/modal/modal-shelf-hierarchy.d.ts

@@ -1,2 +1,6 @@
 import { ModalLevel } from './modal-shelf-types';
+/**
+ * 层级合法性：app 必最顶层；page 祖先允许 app/page（父子页面嵌套场景），仅禁止 custom；custom 可嵌套任何（含 custom 套 custom）。
+ * 非法仅开发期 console.error，不抛、不静默。
+ */
 export declare function assertLevelHierarchy(level: ModalLevel, ancestorLevels: ModalLevel[]): void;

package/types/components/modal/modal-shelf-types.d.ts

@@ -1,39 +1,73 @@
 import { Component } from 'vue';
+/** 架子层级 */
 export type ModalLevel = "app" | "page" | "custom";
+/** 同 key 再 evoke 策略：recreate=关旧重建(默认)；update=已开则整体替换 props 不 remount */
 export type ModalSameKeyStrategy = "recreate" | "update";
+/**
+ * 业务侧 declare merge 扩展此接口声明每个弹窗的业务 props 契约。
+ * 例：declare module "@done-coding/admin-core" {
+ *   interface ModalShelfMap { detail: { id: string; onConfirm?: (r: unknown) => void } }
+ * }
+ */
 export interface ModalShelfMap {
 }
+/** 架子注入给弹窗组件的契约（业务 payload 经单 payload 对象传入） */
 export interface ModalInjectedProps<P = Record<string, unknown>> {
+    /** v-model:show 受控可见性 */
     show: boolean;
+    /** 优雅关闭（隐藏→等动画→移除），=== EvokeHandle.close */
     closeFn: () => void;
+    /** 立即移除（无动画） */
     removeFn: () => void;
+    /** 业务 payload（ModalShelfMap[key]） */
     payload: P;
 }
+/** evoke 返回的命令式句柄；只绑稳定 nsKey，调用时现查当前实例（不闭包 id） */
 export interface EvokeHandle {
+    /** 优雅关闭该 nsKey 当前实例；无则 no-op */
     close: () => void;
+    /** 对该 nsKey 当前实例受控增量合并 payload（不 remount）；无则 no-op */
     update: (partialPayload: Record<string, unknown>) => void;
 }
+/** 注册项（扁平，无 options 包裹，无 isSingle——v1 仅多例） */
 export interface RegisterEntry<K extends keyof ModalShelfMap = keyof ModalShelfMap> {
+    /** 弹窗逻辑 key */
     key: K;
+    /** 组件或懒工厂（() => import()） */
     component: Component | (() => Promise<Component>);
+    /** 目标架子：app/page 名称代指，或直接持 ShelfInstance */
     shelf: "app" | "page" | ShelfInstance;
+    /** 同 key 再 evoke 策略，缺省 "recreate" */
     sameKeyStrategy?: ModalSameKeyStrategy;
 }
+/** 架子内部一条活跃实例 */
 export interface ShelfItem {
+    /** 架子内部自增唯一 id，用作渲染 :key */
     id: number;
+    /** porter 命名空间后的注册键 p{porterUid}:{key} */
     nsKey: string;
+    /** 组件或懒工厂 */
     component: Component | (() => Promise<Component>);
+    /** 业务 payload */
     payload: Record<string, unknown>;
+    /** v-model:show */
     show: boolean;
+    /** close 排定的关闭动画定时器句柄；remove 立即移除前 [MUST] clearTimeout 它 */
     timer?: ReturnType<typeof setTimeout>;
 }
+/** ModalShelf 实例 expose === 它 provide 的 controller */
 export interface ShelfController {
+    /** 本架子层级 */
     level: ModalLevel;
+    /** 唤起一条；同 nsKey 先 remove(立即) 旧再新建 */
     evoke: (nsKey: string, component: Component | (() => Promise<Component>), options: {
         payload: Record<string, unknown>;
         sameKeyStrategy?: ModalSameKeyStrategy;
     }) => EvokeHandle;
+    /** 立即移除（不等动画），支持单个或批量 */
     remove: (nsKey: string | string[]) => void;
+    /** 优雅关闭某条（触发隐藏 → 动画结束 → 移除） */
     close: (item: ShelfItem) => void;
 }
+/** ModalShelf 实例引用类型别名（用于 RegisterEntry.shelf 直接持实例定位 custom 架子） */
 export type ShelfInstance = ShelfController;

package/types/components/modal/types.d.ts

@@ -1,41 +1,102 @@
 import { VNode } from 'vue';
 import { ExtractFormStringifyFromObject, FormItemConfigList, FormMainProps } from '../form';
 import { FormProps } from 'element-plus';
+/** 详情页类型 */
 export type DetailType = "add" | "edit" | "read";
+/** 弹层形态：'modal'=居中弹窗（默认）｜'drawer'=抽屉 */
 export type ModalLayerType = "modal" | "drawer";
+/** drawer 弹出方向（仅 layerType='drawer' 生效） */
 export type ModalDirection = "rtl" | "ltr" | "ttb" | "btt";
-export interface ModalFormProps<PO extends Record<string, any>, SO extends Record<string, any>> {
+/**
+ * ModalForm —— 通用"弹窗 + 表单 + 校验提交"原语（modal 族，可独立使用）。
+ * ModalDetail 是它的 CRUD 预设薄壳（内部委托 ModalForm）；本原语无 add/edit 语义。
+ * 长表单超高时内容区自动滚动（继承 ModalConfirm __content 的 overflow）。
+ */
+export interface ModalFormProps<
+/** 表单标准结构模型 */
+PO extends Record<string, any>, 
+/** 表单需转换的部分结构模型 */
+SO extends Record<string, any>> {
     show: boolean;
+    /** 表单数据（模型） */
     data: PO;
+    /** 表单配置 */
     list: FormItemConfigList<PO, SO>;
+    /**
+     * 提交方法：入参 = FormMain 序列化后的数据（校验通过后调用）。
+     * 返回 Promise——reject 则弹窗不关闭（沿用 ModalConfirm confirmHandler 契约）、
+     * resolve 则关窗并 emit submitSuccess。
+     */
     submitFn: (data: ExtractFormStringifyFromObject<PO, SO>) => Promise<any> | any;
+    /**
+     * 标题（非必传）。字符串或返回 VNode[] 的渲染函数；透传 ModalConfirm。
+     * 未传则标题区为空（消费方也可用 #header 插槽自绘）。
+     */
     title?: string | (() => VNode[]);
+    /** 弹窗宽度（drawer 形态复用为抽屉尺寸 size） */
     width?: number | string;
+    /** 弹层形态：modal 居中弹窗（默认）/ drawer 抽屉；透传 ModalConfirm */
     layerType?: ModalLayerType;
+    /** drawer 弹出方向（仅 layerType='drawer' 生效），默认 rtl */
     direction?: ModalDirection;
+    /** 表单整体布局 */
     formLayout?: FormMainProps<PO, SO>["layout"];
+    /** elForm 其他属性 */
     formProps?: Partial<FormProps>;
+    /** 表单行 gutter，透传给 FormMain */
     formRowGutter?: number;
+    /** 表单 label 宽度 */
     labelWidth?: string;
+    /** header（标题区）下分割线，默认 true（ModalForm 族默认带分割线，区别于裸 ModalConfirm） */
     headerDivider?: boolean;
+    /** footer（操作区）上分割线，默认 true */
     footerDivider?: boolean;
 }
+/** @deprecated 改用 {@link ModalFormProps}（modal 族统一前缀）；老名保留兼容，后续大版本移除 */
 export type FormModalProps<PO extends Record<string, any>, SO extends Record<string, any>> = ModalFormProps<PO, SO>;
-export interface ModalDetailProps<PO extends Record<string, any>, SO extends Record<string, any>> {
+/**
+ * ModalDetail —— CRUD 预设薄壳（内部委托 ModalForm，只保留 add/edit 语义）。
+ */
+export interface ModalDetailProps<
+/** 表单标准结构模型 */
+PO extends Record<string, any>, 
+/** 表单需转换的部分结构模型 */
+SO extends Record<string, any>> {
+    /** 表单数据 */
     data: PO;
+    /** 表单配置 */
     list: FormItemConfigList<PO, SO>;
+    /** 表单类型 */
     type: DetailType;
+    /**
+     * 自定义标题渲染（非必传）。设置后优先使用，返回的 VNode[] 整体替换内置标题；
+     * 未设置则回退到内置 `titleFinal`（新增[subTitle] / 编辑[subTitle]）。
+     */
     title?: () => VNode[];
+    /**
+     * 标题
+     * 最终表现为：新增[标题]、编辑[标题]
+     */
     subTitle?: string;
     show: boolean;
+    /** 新增api */
     addApi?: (data: ExtractFormStringifyFromObject<PO, SO>) => Promise<any>;
+    /** 编辑api */
     editApi?: (data: ExtractFormStringifyFromObject<PO, SO>) => Promise<any>;
+    /** 弹窗宽度 */
     width?: number | string;
+    /** 表单整体布局 */
     formLayout?: FormMainProps<PO, SO>["layout"];
+    /** elForm其他属性 */
     formProps?: Partial<FormProps>;
+    /** 表单行 gutter，透传给 FormMain */
     formRowGutter?: number;
+    /** 表单 label 宽度 */
     labelWidth?: string;
+    /** 弹层形态：modal 居中弹窗（默认）/ drawer 抽屉；透传 ModalForm → ModalConfirm */
     layerType?: ModalLayerType;
+    /** drawer 弹出方向（仅 layerType='drawer' 生效），默认 rtl */
     direction?: ModalDirection;
 }
+/** @deprecated 改用 {@link ModalDetailProps}（modal 族统一前缀）；老名保留兼容，后续大版本移除 */
 export type DetailModalProps<PO extends Record<string, any>, SO extends Record<string, any>> = ModalDetailProps<PO, SO>;

package/types/components/panel/PanelItemNestForm.vue.d.ts

@@ -1,15 +1,21 @@
 import { ColProps } from 'element-plus';
 import { FormItemConfigList } from '../form';
 type __VLS_Props = {
+    /** 子 FormMain 数据（= 父 item 草稿的嵌套对象，子 in-place 改草稿） */
     data: Record<string, any>;
+    /** 子表单配置列表 */
     list: FormItemConfigList;
     layout?: Partial<ColProps>;
     rowGutter?: number;
     submitText?: string;
     cancelText?: string;
+    /** 校验通过后的业务提交（helper 内 wire submitFn(草稿) → closeEdit）；返回 Promise 自动 loading */
     submit?: () => Promise<unknown> | unknown;
+    /** 取消编辑（helper 内 wire closeEdit） */
     cancel?: () => void;
+    /** 父 item 代表 span（P3 rebase 算因子用；helper 经 resolveLayoutSpan(layout) 传入） */
     parentSpan?: number;
+    /** 是否叠本层嵌套布局 rebase（缺省 true；false = 逆向逃生口，layout 原样直透） */
     rebase?: boolean;
 };
 declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {

package/types/components/panel/PanelItemNestPanel.vue.d.ts

@@ -1,14 +1,19 @@
 import { PanelItemConfigList } from './types';
 import { ColProps, CardProps } from 'element-plus';
 type __VLS_Props = {
+    /** 子 PanelMain 数据（= 父 item value，嵌套对象） */
     data: Record<string, any>;
+    /** 子 PanelMain 配置列表 */
     list: PanelItemConfigList;
+    /** 子项是否包 Card，缺省继承 PanelMain 默认 */
     itemCard?: boolean | Partial<CardProps & {
         lastMarginBottom?: string;
     }>;
     layout?: Partial<ColProps>;
     rowGutter?: number;
+    /** 父 item 代表 span（P3 rebase 算因子用；helper 经 resolveLayoutSpan(layout) 传入） */
     parentSpan?: number;
+    /** 是否叠本层嵌套布局 rebase（缺省 true；false = 逆向逃生口，layout 原样直透） */
     rebase?: boolean;
 };
 declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {

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

@@ -2,16 +2,37 @@ import { ColProps } from 'element-plus';
 import { PanelItemConfig, PanelScopeBase } from './types';
 import { FormItemConfigList } from '../form';
 export interface NestPanelFormOptions {
+    /** 父 item key */
     key: string;
+    /** 父 item label */
     label?: string;
+    /** 子 FormMain 配置列表（吃嵌套子对象） */
     list: FormItemConfigList;
+    /** 父 item 栅格布局 */
     layout?: Partial<ColProps>;
+    /** 子表单行间距 */
     rowGutter?: number;
+    /** 提交按钮文案 */
     submitText?: string;
+    /** 取消按钮文案 */
     cancelText?: string;
+    /** 是否可编辑，缺省 true */
     editable?: boolean | ((scope: PanelScopeBase) => boolean);
+    /** 单字段提交：校验通过后回流草稿到父数据（panel 既有 submitFn 语义） */
     submitFn: PanelItemConfig["submitFn"];
+    /** 只读态展示渲染；缺省走 PanelItem 默认（纯文本 data[key]） */
     render?: PanelItemConfig["render"];
+    /** 是否叠本层嵌套布局 rebase（P3，缺省 true；false = 逆向逃生口，子层 layout 原样直透） */
     rebase?: boolean;
 }
+/**
+ * 生成「父 panel item 编辑态内嵌子 FormMain」的 PanelItemConfig（C3 配套 helper）
+ * ----
+ * 走 editorRender（优先级高于 editorConfig，panel/types.ts L65-77）挂 PanelItemNestForm：
+ * - 编辑态：PanelEditSwitch 进编辑时深克隆草稿（scope.data），子 FormMain 绑草稿嵌套对象
+ *   in-place 编辑（不穿透真实 data，ADR-5 panel 分支）；
+ * - 提交：组件内 validateChild 通过 → 本 helper wire 的 submit（`submitFn(草稿) → closeEdit`）回流；
+ * - 取消：closeEdit 关编辑态，草稿丢弃，下次进编辑重新克隆。
+ * editorConfig 与 editorRender 互斥——C3 用 editorRender，同一 item [MUST NOT] 再配 editorConfig。
+ */
 export declare function nestPanelForm(options: NestPanelFormOptions): PanelItemConfig;

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

@@ -1,14 +1,28 @@
 import { ColProps, CardProps } from 'element-plus';
 import { PanelItemConfig, PanelItemConfigList } from './types';
 export interface NestPanelItemOptions {
+    /** 父 item key */
     key: string;
+    /** 父 item label */
     label?: string;
+    /** 子 PanelMain 配置列表（吃嵌套子对象） */
     list: PanelItemConfigList;
+    /** 父 item 栅格布局 */
     layout?: Partial<ColProps>;
+    /** 子 PanelMain 子项是否包 Card */
     itemCard?: boolean | Partial<CardProps & {
         lastMarginBottom?: string;
     }>;
+    /** 子 PanelMain 行间距 */
     rowGutter?: number;
+    /** 是否叠本层嵌套布局 rebase（P3，缺省 true；false = 逆向逃生口，子层 layout 原样直透） */
     rebase?: boolean;
 }
+/**
+ * 生成「父 panel item 内嵌子 PanelMain」的 PanelItemConfig（C2 配套 helper）
+ * ----
+ * 降低业务方手写 h(PanelItemNestPanel) 噪音：传 key/label/子 list 即得一个满足
+ * PanelItemConfig 的纯展示配置项，render 出口挂 PanelItemNestPanel（嵌套对象只读展示）。
+ * 值贯通：render scope.value（= data[key] 嵌套对象）作子 PanelMain.data。
+ */
 export declare function nestPanelItem(options: NestPanelItemOptions): PanelItemConfig;

package/types/components/panel/types.d.ts

@@ -1,51 +1,102 @@
 import { CSSProperties, VNode } from 'vue';
 import { ColProps, CardProps } from 'element-plus';
 import { ExtractFormStringifyFromObject, FormDataInfo, FormItemConfig, FormSubmitPanelProps } from '../form';
+/**
+ * 通用作用于
+ * -----
+ * 用于 render 、editorRender 及 判断
+ */
 export interface PanelScopeBase<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> {
+    /** 原始数据（只读消费，[MUST NOT] 在 render 内修改） */
     data: ExtractFormStringifyFromObject<PO, SO>;
+    /** data[config.key] */
     value: any;
+    /** 配置项 */
     config: PanelItemConfig<PO, SO>;
 }
+/**
+ * Panel render 作用域
+ * -----
+ * 应用于 render \ editorRender
+ */
 export interface PanelRenderScope<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> extends PanelScopeBase<PO, SO> {
+    /** 是否编辑态 */
     editing: boolean;
+    /** 请求 PanelMain 调用 refreshFn；仅用于 render/editorRender 自管刷新，不处理 editorConfig 提交成功 */
     refresh?: () => Promise<unknown> | void;
+    /** 结束编辑态 */
     closeEdit?: () => void;
 }
+/** Panel 配置项 */
 export interface PanelItemConfig<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> {
+    /** 数据键 */
     key: string;
+    /** 标签，非必填 */
     label?: string;
+    /** 隐藏标签；展示态 label 不渲染（编辑态走 editorConfig 时 label 已由 PanelItem 层接管并 labelHide，此项不影响编辑态） */
     labelHide?: boolean;
+    /** 标签样式（挂载到 PanelItem 外层 label 元素） */
     labelStyle?: CSSProperties | string;
+    /** 标签位置；默认 inline（label 在值左侧），top = label 在值上方 */
     labelPosition?: "inline" | "top";
+    /** 栅格布局，复用 resolveFormLayout 语义；缺省继承 PanelMain.layout */
     layout?: Partial<ColProps>;
+    /** 隐藏 */
     hide?: boolean | ((scope: PanelScopeBase<PO, SO>) => boolean);
+    /** 只读渲染；缺省=纯文本 data[key] */
     render?: string | Record<string, any> | ((scope: PanelRenderScope<PO, SO>) => VNode[]);
+    /** 是否可就地编辑 */
     editable?: boolean | ((scope: PanelScopeBase<PO, SO>) => boolean);
+    /** 编辑器渲染；仅 editable 时需要
+     * ----
+     * 使用优先级高于 editorConfig
+     */
     editorRender?: string | Record<string, any> | ((scope: PanelRenderScope<PO, SO>) => VNode[]);
+    /** 编辑器表单配置；仅 editable 时需要
+     * ----
+     * 使用优先级次于 editorRender
+     * 但是优先级高于 render 即编辑态时使用render
+     */
     editorConfig?: Omit<FormItemConfig<PO, SO>, "key" | "label" | "labelHide" | "layout">;
+    /** 单字段提交；仅 editable 时需要。draft = 深克隆副本 */
     submitFn?: FormSubmitPanelProps<PO, SO>["submitFn"];
 }
+/** Panel 配置项列表 */
 export type PanelItemConfigList<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> = PanelItemConfig<PO, SO>[];
+/** PanelMain props */
 export interface PanelMainProps<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> {
     data: ExtractFormStringifyFromObject<PO, SO>;
+    /** 行水平间距 */
     rowGutter?: number;
     layout?: Partial<ColProps>;
+    /** P3 嵌套 rebase 累乘因子（缺省 1 = 顶级行为不变，向后兼容）。由联结薄壳算出后传子 PanelMain */
     layoutScale?: number;
     list: PanelItemConfigList<PO, SO>;
+    /** item是否包括Card */
     itemCard?: boolean | Partial<CardProps & {
+        /** 最后一个 margin bottom */
         lastMarginBottom?: string;
     }>;
-    refreshFn?: (currentStringifyData: any, key: string) => Promise<unknown> | void;
+    /** render/editorRender 内 scope.refresh 的回调；editorConfig 提交成功请监听 submitSuccess */
+    refreshFn?: (currentStringifyData: any, 
+    /** 当前的key */
+    key: string) => Promise<unknown> | void;
 }
+/** PanelItem props */
 export interface PanelItemProps<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> {
     data: ExtractFormStringifyFromObject<PO, SO>;
     config: PanelItemConfig<PO, SO>;
+    /** render/editorRender 内 scope.refresh 的回调；不承接 submitSuccess */
     refreshFn?: (currentStringifyData: FormDataInfo<PO, SO>["stringifyData"]) => Promise<unknown> | void;
 }
+/** PanelEditSwitch props */
 export interface PanelEditSwitchProps<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> extends Partial<Pick<FormSubmitPanelProps<PO, SO>, "submitFn">> {
     data: ExtractFormStringifyFromObject<PO, SO>;
+    /** panel 配置项 */
     config: Omit<PanelItemConfig<PO, SO>, "editorConfig"> & {
+        /** 缺失的key label 由 PanelItem补齐 */
         editorConfig?: FormItemConfig<PO, SO>;
     };
+    /** 是否可编辑 */
     editable?: boolean;
 }