@done-coding/admin-core 0.21.0 → 0.22.0

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

@@ -0,0 +1,57 @@
+import { UploadFile } from 'element-plus';
+import { FormUploadProps } from './types';
+type __VLS_Props = FormUploadProps;
+type __VLS_PublicProps = {
+    modelValue?: string[] | undefined;
+} & __VLS_Props;
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+        tip?(_: {}): any;
+        file?(_: {
+            file: UploadFile;
+            index: number;
+            remove: () => void;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: string[] | undefined) => any;
+} & {
+    uploadSuccess: (payload: {
+        file: UploadFile;
+        url: string;
+    }) => any;
+    uploadError: (payload: {
+        file: UploadFile;
+        error: Error;
+    }) => any;
+    triggerChangeLink: (value: string[], attachInfo?: unknown) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: string[] | undefined) => any) | undefined;
+    onUploadSuccess?: ((payload: {
+        file: UploadFile;
+        url: string;
+    }) => any) | undefined;
+    onUploadError?: ((payload: {
+        file: UploadFile;
+        error: Error;
+    }) => any) | undefined;
+    onTriggerChangeLink?: ((value: string[], attachInfo?: unknown) => any) | undefined;
+}>, {
+    disabled: boolean;
+    drag: boolean;
+    showProgress: boolean;
+    maxCount: number;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,30 @@
+import { FormUploadProps } from './types';
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+        tip?(_: {}): any;
+        file?(_: {
+            file: import('element-plus').UploadFile;
+            index: number;
+            remove: () => void;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<FormUploadProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<FormUploadProps> & Readonly<{}>, {
+    disabled: boolean;
+    drag: boolean;
+    showProgress: boolean;
+    maxCount: number;
+    accept: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,24 @@
+import { UploadFile } from 'element-plus';
+type __VLS_Props = {
+    /** 当前文件条目（status/percentage 驱动遮罩与删除显隐） */
+    file: UploadFile;
+    /** 删除当前项（FormUpload 基座 remove scope） */
+    remove: () => void;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,10 @@
+import { UploadFile } from 'element-plus';
+/**
+ * 私有：媒体上传列表项信息列（文件名 + 大小/上传进度）——
+ * FormUploadVideo / FormUploadAudio 默认 #file 共用。不出桶导出。
+ */
+type __VLS_Props = {
+    file: UploadFile;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

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

@@ -0,0 +1,34 @@
+import { FormUploadProps } from './types';
+type __VLS_Props = FormUploadProps & {
+    listType?: string;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+        tip?(_: {}): any;
+        file?(_: {
+            file: import('element-plus').UploadFile;
+            index: number;
+            remove: () => void;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    disabled: boolean;
+    drag: boolean;
+    showProgress: boolean;
+    maxCount: number;
+    accept: string;
+    listType: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,11 @@
+type __VLS_Props = {
+    /** 触发区文案（text 形态） */
+    text?: string;
+    /** 卡片形态（picture-card 方形触发区，仅 "+" 图标） */
+    card?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    text: string;
+    card: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

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

@@ -0,0 +1,34 @@
+import { FormUploadProps } from './types';
+type __VLS_Props = FormUploadProps & {
+    listType?: string;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+        tip?(_: {}): any;
+        file?(_: {
+            file: import('element-plus').UploadFile;
+            index: number;
+            remove: () => void;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    disabled: boolean;
+    drag: boolean;
+    showProgress: boolean;
+    maxCount: number;
+    accept: string;
+    listType: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -1,7 +1,18 @@
+import { default as FormActiveFilter } from './FormActiveFilter.vue';
+import { default as FormShadowCloneDispatch } from './FormShadowCloneDispatch.vue';
+import { default as FormInput } from './FormInput.vue';
+import { default as FormInputShadowClone } from './FormInputShadowClone.vue';
 import { default as FormMain } from './FormMain.vue';
+import { default as FormSortSwitch } from './FormSortSwitch.vue';
+import { default as FormSortSwitchGroup } from './FormSortSwitchGroup.vue';
 import { default as FormSelect } from './FormSelect.vue';
+import { default as FormSelectShadowClone } from './FormSelectShadowClone.vue';
 import { default as FormRadioGroup } from './FormRadioGroup.vue';
 import { default as FormTree } from './FormTree.vue';
+import { default as FormUpload } from './FormUpload.vue';
+import { default as FormUploadImage } from './FormUploadImage.vue';
+import { default as FormUploadVideo } from './FormUploadVideo.vue';
+import { default as FormUploadAudio } from './FormUploadAudio.vue';
 import { default as FormSearch } from './FormSearch.vue';
 import { default as FormSubmitBtn } from './FormSubmitBtn.vue';
 import { default as FormSubmitPanel } from './FormSubmitPanel.vue';
@@ -17,4 +28,4 @@ export * from './nest-form-item';
 export * from './use-nest-form-list';
 export * from './nest-form-item-list';
 export * from './use-nest-layout-scale';
-export { FormMain, FormSelect, FormSearch, FormSubmitBtn, FormSubmitPanel, FormRadioGroup, FormTree, FormVerifyImage, FormVerifyCode, FormItemNestForm, FormItemNestFormList, };
+export { FormActiveFilter, FormShadowCloneDispatch, FormInput, FormInputShadowClone, FormMain, FormSortSwitch, FormSortSwitchGroup, FormSelect, FormSelectShadowClone, FormSearch, FormSubmitBtn, FormSubmitPanel, FormRadioGroup, FormTree, FormUpload, FormUploadImage, FormUploadVideo, FormUploadAudio, FormVerifyImage, FormVerifyCode, FormItemNestForm, FormItemNestFormList, };

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

@@ -77,6 +77,12 @@ SV extends PK extends keyof SO ? SO[PK] : PV = PK extends keyof SO ? SO[PK] : 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;
+    /**
+     * 本表单项 stringify 拆分出的 query 字段名（如 daterange → createdStart/createdEnd）。
+     * 视图层（生效条件条等）按**表单项维度**聚合展示 + 移除联动清值的映射桥——
+     * 数据层（query 拆分字段）与视图层（表单项）分离的显式声明，缺它拆分字段无法反查归属。
+     */
+    splitKeys?: string[];
     /**
      * 是否在初始化数据、解析数据、序列化数据时忽略处理
      */
@@ -357,4 +363,156 @@ export type FormSubmitPanelProps<PO extends Record<string, any>, SO extends Reco
      */
     rootClass?: string | string[] | Record<string, boolean>;
 };
+/** FormInput 密码自动填充治理取值
+ * ----
+ * 实测结论（2026-08-04，Chrome + 已存密码域名）：
+ * - 加载自动填充主触发 = `<form>` 包裹的「账号+密码」字段对；`autocomplete="off"` 被 Chrome 有意无视
+ * - 规范外自定义词条（"api-key"）实测全程未触发直接填充，最可靠；"new-password" 实测出现过直接填充
+ * - number = 时序方案（初始 text 避开加载期探测窗口后恢复 password），实测 3s 在加载填充场景有效
+ */
+export type FormInputPasswordAutoComplete = "api-key" | "new-password" | "off" | number;
+/** FormInput props
+ * ----
+ * 仅显式声明 type / showPassword / passwordAutoComplete（读密码形态 + 治理），
+ * 其余 el-input props / slots 全量经 $attrs 透传（v-model / placeholder / clearable / 插槽等）。
+ */
+export interface FormInputProps {
+    /** 透传 el-input 输入框类型（显式声明以判定密码形态） */
+    type?: string;
+    /** 透传 el-input 显隐切换（显式声明以判定密码形态） */
+    showPassword?: boolean;
+    /** 密码形态（type=password / show-password）下的浏览器自动填充治理：
+     * - 字符串 → 密码输入框 autocomplete 设为此值（"api-key" 规范外词条最可靠；"off" 是 el-input
+     *   密码形态默认值、Chrome 有意无视不可靠；"new-password" 有过直接填充记录——见类型上方实测结论）
+     * - number N → 不设置 autocomplete；透传 el-input 的 type 初始 "text"（无密码语义不触发填充），
+     *   延迟 N ms 后恢复 "password"（时序方案；点击填充拦不住，属浏览器正常交互）
+     * - 不传 → 不设置 autocomplete（保持 el-input 默认行为） */
+    passwordAutoComplete?: FormInputPasswordAutoComplete;
+}
+/** FormInputShadowClone 影分身版 props：完全兼容 FormInput（attrs 全透传）+ 额外影分身参数 +
+ * 漏斗高亮判定（实现经内部件 FormShadowCloneDispatch，高亮判定在本组件）。
+ * 影分身能力独立成组件而非内嵌原始 FormInput——保持原始薄包装组件的纯粹性（反模式规避） */
+export interface FormInputShadowCloneProps {
+    /** v-model（透传 FormInput；本体与分身弹层同源） */
+    modelValue?: string | number;
+    /** 影分身开关（本体 + 表头漏斗分身双渲染位，点击漏斗 popover 弹输入框，同一 v-model 同源同步） */
+    shadowClone?: boolean;
+    /** 分身目标容器（表头预埋唯一选择器；`shadowClone` 时生效，未配置不分身） */
+    teleportTo?: string | Element;
+    /** 分身位字段文字（表头列名；label + 漏斗整块展示、高亮整块——表格 headerRender 只需留 teleportTo 容器） */
+    label?: string;
+    /** 分身高亮判定方法（非必传），入参 modelValue；默认 = 非 null/undefined/空字符串 → 高亮（label + 漏斗整块） */
+    isHighlighted?: (value: unknown) => boolean;
+}
+/** FormSortSwitch 排序规则：字段 + 方向；有序数组的顺序即优先级（左 = 最高） */
+export interface FormSortRule {
+    field: string;
+    dir: "asc" | "desc";
+}
+/** FormSortSwitch 排序字段选项（业务侧注入，组件不内置业务字段）
+ * - `teleportTo`：影分身目标容器（非必传）——shadowClone 开启后本条目分身打到该目标；
+ *   未配置的条目不分身（仅本体渲染） */
+export interface FormSortOption {
+    field: string;
+    label: string;
+    teleportTo?: string | Element;
+}
+/** FormSortSwitch 交互模式：
+ * - `"cycle"`（默认，对齐主流）：点击整块三态循环——未激活 → 升序 → 降序 → 取消
+ *   （首击升序与 Element Plus / Ant Design 表头排序同构；点击 = `NEXT[当前值]` 查表，
+ *   不依赖点击次数——状态可能被影分身另一处/外部改写）
+ * - `"dual-arrow"`：上下双三角独立点击（点 ↑ = 升序/再点取消、点 ↓ = 降序/再点取消、
+ *   方向互斥切换）——「点一次即确定方向」的显式命令模式
+ * 两模式 v-model 协议一致，纯 UI 交互层差异，切换零迁移。 */
+export type FormSortMode = "cycle" | "dual-arrow";
+/** FormSortSwitch v-model 方向值：undefined = 默认无排序（非 null） */
+export type FormSortSwitchModelValue = "asc" | "desc" | undefined;
+/** FormSortSwitch 展示文本模式：
+ * - `"state"`（默认）：展示状态文字「默认 / 升序 / 降序」——独立作为表单元素（自身即状态展示）
+ * - `"label"`：展示字段名（options 的 label）——group 的 item 即此模式（group 显式设置） */
+export type FormSortTextType = "label" | "state";
+/** FormSortSwitch 单字段排序切换器 props（v-model: "asc" | "desc" | undefined，无 key——
+ * 不知道自己的字段；作 group 的 item 时 field 映射在 group 组装闭包内。
+ * 影分身能力内聚于本组件：独立使用也能分身（shadowClone + teleportTo），
+ * group 只是把 option.teleportTo 透传） */
+export interface FormSortSwitchProps {
+    /** v-model 方向值（三态：undefined=默认 / asc / desc；默认 undefined 非 null） */
+    modelValue?: FormSortSwitchModelValue;
+    /** 交互模式（默认 "cycle"；"dual-arrow" 双三角独立命令） */
+    mode?: FormSortMode;
+    /** 展示文本（默认 "state" 状态文字；"label" 字段名） */
+    textType?: FormSortTextType;
+    /** 字段显示名（仅 textType="label" 时需要） */
+    label?: string;
+    /** 是否显示优先级序号（group 在 options>1 时传 true） */
+    showOrder?: boolean;
+    /** 优先级序号值（1-based，showOrder 时显示） */
+    order?: number;
+    /** 影分身开关（ShadowClone 双渲染位：本体就地 + 分身 teleport 到 teleportTo，同一 v-model 同源同步）。
+     * 未配置 teleportTo 时分身无从打起（仅本体渲染） */
+    shadowClone?: boolean;
+    /** 分身目标容器（CSS 选择器 / DOM 元素；shadowClone 时生效） */
+    teleportTo?: string | Element;
+    /** 分身位交互模式（独立于本体 mode；默认 "dual-arrow" = 点小箭头升/降序） */
+    teleportMode?: FormSortMode;
+}
+/** FormSortSwitchGroup 复合排序组 props（v-model: 有序 FormSortRule[]，key 视角在 group；
+ * 依赖 FormSortSwitch 组装，自身零内部状态） */
+export interface FormSortSwitchGroupProps {
+    /** 排序字段选项集（业务注入；条目可带非必传 teleportTo 影分身目标） */
+    options: FormSortOption[];
+    /** 本体 item 交互模式（默认 "cycle"） */
+    mode?: FormSortMode;
+    /** 影分身开关：配置了 teleportTo 的条目分身到目标（同 model 同源同步）、未配置的不分身 */
+    shadowClone?: boolean;
+    /** 分身 item 交互模式（独立于本体；默认 "dual-arrow" = 点小箭头升/降序） */
+    teleportMode?: FormSortMode;
+}
+/** FormActiveFilter 生效条件条目：query 字段投影（× 移除事件载荷 = 整个条目）。
+ * 展示维度 = 表单配置项（拆分字段经 config.splitKeys 聚合回所属表单项，见 use-active-filter） */
+export interface FormActiveFilterEntry {
+    /** query 字段名（单字段条目）；聚合条为所属表单项 config.key */
+    field: string;
+    /** 聚合条的多个 query 字段（拆分字段合成一条时；单字段条目为空） */
+    fields?: string[];
+    /** 展示 label（表单字段 config.label，无直配 config 用字段名） */
+    label: string;
+    /** 展示值（枚举类应传 options 匹配后的 label，取不到原值兜底；聚合条为拆分值拼接） */
+    displayValue: string;
+}
+/** FormActiveFilter 生效筛选条件条 props（纯 UI——投影逻辑在消费方 hook） */
+export interface FormActiveFilterProps {
+    /** 生效条件条目（空数组不渲染） */
+    filters: FormActiveFilterEntry[];
+    /** 显示「清除全部」按钮（默认 false） */
+    allowClear?: boolean;
+}
+/** FormUpload 上传原语 props（媒体三组件 FormUploadImage / FormUploadVideo /
+ * FormUploadAudio 继承复用：覆写 accept 默认 + 追加专属 prop） */
+export interface FormUploadProps {
+    /** 上传接口注入：入参 File、返回 Promise<URL>（数据职责，不焊后端；[MUST] 必填）。
+     *  可选第二参 onProgress(percent) 驱动进度条（0–100；不调则进度条静态）——真实后端
+     *  经 XHR upload.onprogress 转发，mock 可分片模拟推进。 */
+    uploadFn: (file: File, onProgress?: (percent: number) => void) => Promise<string>;
+    /** 表单字段 key——上传期间经 FORM_ITEM_CHANGE_LOADING 拦提交（FormMain 配置化场景传；裸用可不传） */
+    loadingKey?: string;
+    /**
+     * 文件数量上限（默认 1 = 单文件替换语义；>1 = 多文件追加，兼数量上限——业界主流
+     * maxCount 即多文件判定）。v-model 恒为 `string[]`（单文件也是数组），配置表单
+     * 提交转换经 stringify/parse。
+     */
+    maxCount?: number;
+    /** 单文件大小上限（单位 MB；超限上传前校验 reject + 提示——EP 无原生 size 限制，本组件拓展） */
+    maxSize?: number;
+    /** 文件类型过滤（透传 ElUpload） */
+    accept?: string;
+    /** 拖拽上传（透传 ElUpload） */
+    drag?: boolean;
+    /** 禁用（透传 ElUpload） */
+    disabled?: boolean;
+    /** 上传进度条（ElUpload 内置 show-progress） */
+    showProgress?: boolean;
+    /** 空态提示文字（render 契约字段） */
+    placeholder?: string;
+}
 export {};

package/types/components/form/use-password-autofill.d.ts

@@ -0,0 +1,11 @@
+import { FormInputPasswordAutoComplete } from './types';
+export interface UsePasswordAutofillProps {
+    type?: string;
+    showPassword?: boolean;
+    passwordAutoComplete?: FormInputPasswordAutoComplete;
+}
+export declare function usePasswordAutofill(props: UsePasswordAutofillProps): {
+    inputType: import('vue').ComputedRef<string | undefined>;
+    autocompleteOut: import('vue').ComputedRef<"api-key" | "new-password" | "off" | undefined>;
+    showPasswordOut: import('vue').ComputedRef<boolean | undefined>;
+};

package/types/components/form/use-upload-state.d.ts

@@ -0,0 +1,29 @@
+import { Ref } from 'vue';
+import { UploadFile, UploadFiles, UploadRawFile, UploadRequestOptions } from 'element-plus';
+/** useUploadState 入参——组件的响应式接线点（getter 惰性读取，保留响应式） */
+export interface UseUploadStateOptions {
+    /** 文件数量上限（惰性读取 props.maxCount）：默认 1 = 单文件替换；>1 = 多文件追加兼数量上限 */
+    maxCount: () => number;
+    /** 单文件大小上限 MB（惰性读取 props.maxSize）：超限上传前校验 reject（EP 无原生 size 限制） */
+    maxSize: () => number | undefined;
+    /** 上传接口注入（惰性读取 props.uploadFn）：入参 File、返回 URL；可选 onProgress 驱动进度 */
+    uploadFn: () => (file: File, onProgress?: (percent: number) => void) => Promise<string>;
+    /** 表单字段 key（惰性读取 props.loadingKey）：上传期间拦提交；未传 → no-op */
+    loadingKey: () => string | undefined;
+    /** 单文件上传成功（URL 已入值） */
+    onUploadSuccess: (url: string, file: UploadRawFile) => void;
+    /** 单文件上传失败（值不变） */
+    onUploadError: (error: unknown, file: UploadRawFile) => void;
+}
+/** useUploadState 返回——FormUpload 内部受控面 */
+export interface UseUploadStateReturn {
+    /** ElUpload 受控文件列表（与 modelValue 双向同步） */
+    fileList: Ref<UploadFiles>;
+    /** 上传在途数（0→1 拦提交 / →0 放行，覆盖并发） */
+    uploadingCount: Ref<number>;
+    /** ElUpload http-request 内部固定实现：调 uploadFn 拿 URL → URL 入值 → 在途计数对称 */
+    handleUpload: (options: UploadRequestOptions) => Promise<string>;
+    /** 移除文件 → URL 出值（单文件清空 / 多文件过滤） */
+    handleRemove: (file: UploadFile) => void;
+}
+export declare function useUploadState(modelValue: Ref<string[] | undefined>, options: UseUploadStateOptions): UseUploadStateReturn;

package/types/components/list-layout/ListLayout.vue.d.ts

@@ -25,10 +25,13 @@ declare const _default: <T extends Record<string, any>, PO extends Record<string
         injectInfo?: F | undefined;
         beforeSearch?: ((data: import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>>, type: FormSearchSearchType) => import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>>) | undefined;
         clearTableFilterOnReset?: boolean;
+        initialSearch?: boolean;
         separateSearch?: boolean;
         separateSearchConfig?: Pick<import('../slot-layout').SlotLayoutFlowAsideProps, "type" | "gap" | "asideWidth">;
         searchSticky?: boolean;
         toolbarSticky?: boolean;
+        formActiveFilter?: boolean;
+        allowClear?: boolean;
         pagerSticky?: boolean;
         headerObserveResize?: boolean;
         operationObserveResize?: boolean;

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

@@ -34,6 +34,12 @@ F extends Record<string, any>> = Partial<Pick<FormSearchProps<PO, SO, {}>, FormS
     beforeSearch?: (data: ExtractFormStringifyFromObject<PO, SO>, type: FormSearchSearchType) => ExtractFormStringifyFromObject<PO, SO>;
     /** 在点击搜索重置按钮时，是否同时调用清空表格表头过滤 */
     clearTableFilterOnReset?: boolean;
+    /**
+     * 挂载后是否立即触发初始化查询（默认 true 查）。
+     * - false：进入页面不自动拉数——表格空态显示「欢迎触发查询」（TableMain 经 hasRequested
+     *   自判），KeepAlive 激活也不自动刷新，用户手动查询后恢复。
+     */
+    initialSearch?: boolean;
     /**
      * 搜索是否分离为侧栏。
      * - false（默认）：header/搜索/operation 纵向内联在表格上方（与旧版逐像素一致）。
@@ -58,6 +64,16 @@ F extends Record<string, any>> = Partial<Pick<FormSearchProps<PO, SO, {}>, FormS
      * 与 searchSticky 同开（非分离态）时自动叠钉在粘住的搜索区正下方。
      */
     toolbarSticky?: boolean;
+    /**
+     * 生效筛选条件条（Active Filter Bar）：表单卡片顶部一行显示当前已生效查询条件
+     * （query 投影，≠ 表单输入值），每条件 × 移除（同步清表单值防「删了又加回来」）。
+     * 默认 false 不渲染——存量页面 0 影响。业界对标 SAP Fiori Filter Feedback Bar。
+     */
+    formActiveFilter?: boolean;
+    /**
+     * 允许一键清空生效条件（仅 formActiveFilter 开启时有意义；默认 false 不展示「清除全部」）。
+     */
+    allowClear?: boolean;
     /**
      * 表格分页器粘性：容器/页面滚动时 TableMain 的分页器钉在滚动视口底部
      * （默认 false 不开启）。与 separateSearch 无关——分离与否表格都在主滚动流里。

package/types/components/list-layout/use-active-filter.d.ts

@@ -0,0 +1,27 @@
+import { FormActiveFilterEntry, FormItemConfigList } from '../form';
+/** 条件条单条（= FormActiveFilterEntry + 直配 config key，供表单值同步清除） */
+export interface ActiveFilterEntry extends FormActiveFilterEntry {
+    /** 所属 config key（可同步清表单值时；直配字段与聚合条都有，纯拆分无归属时 undefined） */
+    configKey?: string;
+}
+export interface UseActiveFilterOptions {
+    /** 开关 getter（ListLayout formActiveFilter prop）；false 时全短路零副作用 */
+    enabled: () => boolean;
+    /** 已生效条件投影（ListLayout query ref） */
+    query: {
+        value: Record<string, any>;
+    };
+    /** 表单字段 config（value→label 与表单值清除的依据） */
+    list: FormItemConfigList;
+    /** 表单数据模型（FormMain 同范式：外部持有响应式对象，直改属性即联动表单） */
+    formData: {
+        value: Record<string, any>;
+    };
+    /** 重查（query 变更后触发表格 reload） */
+    reload: () => void;
+}
+export declare function useActiveFilter(options: UseActiveFilterOptions): {
+    activeFilters: import('vue').ComputedRef<ActiveFilterEntry[]>;
+    remove: (entry: ActiveFilterEntry) => void;
+    clearAll: () => void;
+};

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

@@ -0,0 +1,41 @@
+/**
+ * ImagePreviewTrigger —— 图片预览触发原语（ElImage 落地 + 懒加载 + 占位兜底）。
+ * 点击直达：preview 开启时绑定 preview-src-list（= [previewSrc ?? src]）+
+ * preview-teleported——el-image-viewer 原生全屏放大，不经弹窗（两层嵌套已废弃）；
+ * 命令式开图走 ModalImagePreview（ElImageViewer 薄适配），两入口各司其职。
+ * $attrs 只落自身 ElImage（alt / fit / loading 等；width/height 无效——EP 2.13
+ * ElImage 未声明该 props，透传落根 div attribute 无渲染效果，尺寸走外层
+ * CSS / style + fit="cover"）。
+ * 详见 docs/README-ImagePreviewTrigger.md。
+ */
+type __VLS_Props = {
+    /** 缩略图路径（ElImage.src） */
+    src: string;
+    /** 原图路径（点击放大打开的大图）；缺省降级为 src */
+    previewSrc?: string;
+    /** 图片懒加载（ElImage.lazy，原生 loading 优先） */
+    lazy?: boolean;
+    /** 是否可点击放大（false = 纯展示缩略图，仍保留懒加载 + 占位兜底） */
+    preview?: boolean;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        placeholder?(_: {}): any;
+        error?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    lazy: boolean;
+    preview: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -78,7 +78,7 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
 }>, {
     reverse: boolean;
     width: number | string;
-    type: "" | "default" | "text" | "primary" | "success" | "warning" | "info" | "danger";
+    type: "" | "text" | "default" | "primary" | "success" | "warning" | "info" | "danger";
     direction: "rtl" | "ltr" | "ttb" | "btt";
     showClose: boolean;
     cancelText: string | (() => VNode);

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

@@ -0,0 +1,31 @@
+/**
+ * ModalImagePreview —— 图片预览弹窗·命令式入口（ElImageViewer 薄适配）。
+ * 注册形态（ModalShelf/Porter）：架子渲染只传 show/payload/closeFn/removeFn——
+ * payload/closeFn/removeFn 显式声明（不泄漏进 $attrs 落 viewer DOM），
+ * 业务值双输入源：`src` = `props.src ?? payload.src`（一行合并）。
+ * 多图经 $attrs 的 `url-list` 显式覆盖（透传面），否则单图 = [src]。
+ * 详见 docs/README-ModalImagePreview.md。
+ */
+type __VLS_Props = {
+    /** 图片地址（双输入源：props.src ?? payload.src）；单图 = url-list [src] */
+    src: string;
+    /** 注册形态注入（ModalShelf/Porter 渲染只传 payload；原语用法无需传） */
+    payload?: {
+        src?: string;
+    };
+    /** 注册形态注入的关闭出口（本组件不消费，仅声明避免泄漏进 $attrs） */
+    closeFn?: () => void;
+    /** 注册形态注入的移除出口（同上） */
+    removeFn?: () => void;
+    /** 关闭回调（ElImageViewer @close 触发） */
+    onClose?: (status?: boolean) => void;
+};
+type __VLS_PublicProps = {
+    "show": boolean;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:show": (value: boolean) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:show"?: ((value: boolean) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

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

@@ -1,6 +1,13 @@
 import { EvokeHandle, ModalShelfMap, RegisterEntry } from './modal-shelf-types';
 type __VLS_Props = {
     modalList: RegisterEntry[];
+    /**
+     * 专用模式标识（core 内部）：=== `APP_GLOBAL_MODAL_PORTER_SYMBOL` 时本 Porter 为
+     * AppLayout 内部全局弹窗专用——只接受 shelf:"app" 条目，非 app 条目 console.error +
+     * 过滤；配置经架子 `registerConfig` 推送（挂载进 globalModalRemote）。外部拿不到
+     * Symbol 即无法误用。[MUST NOT] 业务侧传入。
+     */
+    globalOnly?: symbol;
 };
 declare function evoke<K extends keyof ModalShelfMap>(key: K, payload: ModalShelfMap[K]): EvokeHandle | null;
 declare function __VLS_template(): {