@jzg223/design-runtime 0.0.0-stage → 0.0.1

package/dist/types/http.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 网络层契约（本库**不**依赖 axios / alova / fetch，只依赖这个接口）
+ *
+ * 为什么这么做：
+ * - 宿主（vben / 任意项目）已经有全站唯一的请求实例，token 头、clientid、401 跳登录、
+ *   刷新 token、baseURL、租户、日志、错误提示策略全在那里。本库若自己 `new axios`，
+ *   就会出现**第二套拦截器**：库里的请求不带 token ⇒ 一打开设计表格就 401，
+ *   而且宿主的"刷新 token / 踢回登录"逻辑对库的请求不生效。
+ * - 本库要能发到 npm 独立安装，所以不能 `import` 宿主模块（`#/utils/http` 之类）。
+ *   唯一合法的连接方式是**运行时注入**（见 host.ts 的 installDesignPlatform）。
+ *
+ * 返回口径：**resolve 业务数据**（宿主拦截器里已经把 `{code,data}` 剥掉了）。
+ * 库内不要再判断 `res.code === 200`，避免跟宿主两套口径打架。
+ */
+export interface DesignRequestOptions {
+    /** query 参数 */
+    params?: Record<string, any>;
+    headers?: Record<string, string | undefined>;
+    /** 取消（库内所有取数都应支持中途取消） */
+    signal?: AbortSignal;
+    /**
+     * 静默：不要弹成功/失败提示。
+     * 列表、树这类一次页面并发多条请求的场景必须传 true，否则一次操作弹十条 toast；
+     * 具体怎么提示交给调用方。
+     */
+    silent?: boolean;
+    timeout?: number;
+}
+export interface DesignHttp {
+    get: <T = any>(url: string, options?: DesignRequestOptions) => Promise<T>;
+    post: <T = any>(url: string, data?: any, options?: DesignRequestOptions) => Promise<T>;
+    /** 可选能力：宿主没提供时，导出/附件类功能降级（工具条按钮提示不可用） */
+    download?: (url: string, data?: any, options?: DesignRequestOptions) => Promise<Blob>;
+    /** 可选能力：宿主没提供时，上传类功能降级 */
+    upload?: <T = any>(url: string, form: FormData, options?: DesignRequestOptions & {
+        onProgress?: (percent: number) => void;
+    }) => Promise<T>;
+}
+/** 一次请求的形态（memory 实现与调试日志共用） */
+export interface DesignRequestRecord {
+    data?: any;
+    method: 'GET' | 'POST';
+    options?: DesignRequestOptions;
+    url: string;
+}
+/**
+ * 内存版 http：给**开发/演示/自测**用，不需要宿主后端。
+ *
+ * 用法：
+ * ```ts
+ * const http = createMemoryHttp((req) => {
+ *   if (req.url.endsWith('/find/pager')) return { records: [], total: 0 }
+ * })
+ * installDesignPlatform({ http })
+ * ```
+ */
+export declare function createMemoryHttp(handler: (req: DesignRequestRecord) => any): DesignHttp & {
+    readonly log: DesignRequestRecord[];
+};

package/dist/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 公开面（package.json 的 types/main 都指向这里）
+ *
+ * 原则：**只导出稳定的东西**。内部实现（组件内部的响应式状态、渲染细节）不从这里出去，
+ * 免得宿主依赖上不该依赖的细节，把库的版本升级空间锁死。
+ */
+import './styles/index.css';
+export { ApiSwitch, buildHostApi, DESIGN_POPUP_HOST_KEY, DesignTable, DesignTree, DesignTableFlowStatusCell, DesignTableInner, DesignComb, DesignDevModeToggle, DesignSearch, DesignDevStateButton, DesignForm, DesignFormInner, evalExpression, executeCommand, hostRequest, openComponent, pendingRowActionTypes, pendingToolTypes, platformMessage, resolveRowActionComponent, resolveToolComponent, rowActionComponentMap, rowActionTypes, setDevMode, useDevMode, toolComponentMap, toolTypes, usePopupHost, } from './components';
+export type { CommandContext, CommandHelpers, CommandNav, DesignHostApi, DesignHostSlot, DesignPopupHost, OpenComponentOptions, } from './components';
+export { checkDesignRuntimeCompat, satisfiesRange, SUPPORTED_VERSIONS, } from './compat';
+export type { CompatCheckItem, CompatReport } from './compat';
+export { getDesignHost, getHostDict, getHostPopup, getHostUi, getHostWorkflow, hostT, installDesignPlatform, requireHttp, requireVxeGrid, resetDesignHost, } from './host';
+export type { DesignAuthSnapshot, DesignHost, DesignHostUpload, DesignUploadOptions, DesignUploadResult, DesignHostDict, DesignHostMessage, DesignHostModal, DesignHostUi, DesignHostWorkflow, } from './host';
+export { createMemoryHttp } from './http';
+export type { DesignHttp, DesignRequestOptions, DesignRequestRecord, } from './http';
+export { buildComponentsManifest, clearDesignComponents, hasDesignComponent, listDesignComponents, registerComponents, requireDesignComponent, resolveDesignComponent, } from './registry';
+export type { DesignComponentEntry, DesignComponentLoader, DesignComponentMeta, } from './registry';
+export type { DesignMapping, DesignTableTool, PlatformCellStyle, PlatformColumn, PlatformCombConfig, PlatformCombItem, PlatformDerivedField, PlatformDictItem, PlatformFormCell, PlatformFormConfig, PlatformFormContent, PlatformSearchConfig, PlatformTableConfig, PlatformTreeMapping, PlatformTreeViewConfig, PlatformViewComponent, PlatformViewConfig, PlatformViewContent, RowAction, RowActionMapping, SearchFieldCell, SearchFormConfig, TableDataResponse, TreeNodeCountConfig, } from './types';
+export { clearDesignApiCache, fetchCombConfig, fetchCombData, fetchDataSetData, fetchDataSetListData, fetchDataSetMeta, fetchDataSetTreeAsync, fetchDataSetTreeSync, fetchDesignUiConfig, fetchFormConfig, fetchSearchConfig, fetchTableConfig, fetchTreeNodeCount, fetchTreeViewConfig, fetchViewConfig, } from './api';
+export type { DataSetMeta } from './api';
+export { designFlowRemove, designFlowStatus, designFlowSubmit, } from './flow';
+export type { DesignFlowQueryParams, DesignFlowStartResult, DesignFlowStatusVo, DesignFlowSubmitParams, } from './flow';
+export { buildCustomParams, buildNavigateQuery, buildQuerySearch, buildTableDataBody, createQueryDedupe, evaluateExpress, evaluateLoadGate, fetchTableData, parseConfigParams, transformTableConfig, } from './table';
+export type { FetchTableDataParams, LoadGateResult, QueryDedupe, QueryDedupeOptions, QueryDedupeStats, TransformHost, TransformTableResult, } from './table';
+export { DEFAULT_POPUP_WIDTH, resolvePopupWidth, toPopupWidth, } from './utils/popup-width';
+export { downloadByData } from './utils/download';
+export { buildExpressId, buildExtraParams, buildMappedParams, evaluateMappedExpress, isOwnRoutePage, } from './mapping';
+export { buildConditionScope, computeConditionDebug, evalCellCondition, isConditionHidden, isInjectableScopeKey, } from './form/cell-condition';
+export type { CellConditionDebugItem, CellConditionResult, } from './form/cell-condition';
+export { buildDerivedScope, computeDerivedFills, evalDerivedExpress, } from './form/derived-express';
+export { parsePrecision, roundToPrecision } from './form/number-precision';
+export { transformFormConfig } from './form/transformer';
+export type { FormGridConfig } from './form/transformer';
+export { hasCustomComponent, listCustomComponents, pendingFieldTypes, register, registerFields, resolveCellComponent, resolveComponent, } from './form/fields';
+export { deptChildren, deptInfo, deptList, getDeptSubTree } from './org/dept-api';
+export { attachChildren, createLazyDeptTree, normalizeParentId, toTreeNode, } from './org/dept-tree';
+export type { DeptNode, DeptTreeNode, DeptTreeSource, } from './org/dept-tree';
+export { createDeptTreeSource, normalizeDeptNode } from './org/dept-tree-source';
+export { buildSearchFormOptions, normalizeSearchCells } from './search/transformer';
+export type { DesignFormOptions, DesignFormSchema, } from './search/transformer';
+export { formatNow, resolveDefaultValue } from './utils/default-value';

package/dist/types/mapping.d.ts

@@ -0,0 +1,39 @@
+import type { DesignTableTool } from './types';
+/**
+ * 字段映射工具（从 vben 基座搬过来的真实实现，行为逐字保持一致）
+ *
+ * 统一模型：
+ * - 组件自身参数 extraParams = 路由参数（去 module/name）+ 上游 parentParams（推送优先）。
+ * - 渲染工具条时以组件自己的 extraParams 作为映射数据源（表达式写 `params.xxx`），
+ *   各组件可附加自有数据源（树形 `node`、表单/组合 `data`）。
+ * - 目标推送：navigate → 路由 query；add → 表单 extraParams（随保存下发后端）。
+ *
+ * 注意：表达式来自**设计端配置**，属于可信来源（与宿主同一口径），故用 `new Function` 动态求值。
+ */
+/** 执行映射表达式：以 scope 的键作为函数参数名求值（scope 为空 / 表达式为空返回 undefined） */
+export declare function evaluateMappedExpress(express: string | undefined, scope: Record<string, any>): any;
+/** 按 `tool.mappings` 求值生成目标参数；未配置映射返回空对象 */
+export declare function buildMappedParams(tool: DesignTableTool, scope: Record<string, any>): Record<string, any>;
+/**
+ * id 提取表达式求值（工具条「跳转/打开」目标组件需要 source-id 时用）：
+ * 与字段映射同作用域，结果为空则返回 undefined（调用方据此决定不传 id）。
+ */
+export declare function buildExpressId(tool: DesignTableTool, scope: Record<string, any>): any;
+/**
+ * 组装组件自身 extraParams：路由参数（去掉 module/name）+ 上游 parentParams（推送优先）。
+ *
+ * 这是「参数从哪来」的统一口径 —— 以前散在 vben 各组件里，抽包后集中在这里，
+ * 宿主只要按需传入 routeParams / parentParams。
+ */
+export declare function buildExtraParams(routeParams?: Record<string, any>, parentParams?: Record<string, any>): Record<string, any>;
+/**
+ * 判断组件是否位于自己的路由页：路由路径以 `/category/name` 结尾。
+ *
+ * 独立路由页（`/design/table/xxx/yyy` 或动态菜单 `.../table/xxx/yyy`）→ true，可并入路由参数；
+ * 被其他组件打开/内嵌（抽屉、弹窗、组合视图 Tab、树形关联目标）→ false，
+ * extraParams 只来自 parentParams。
+ *
+ * （宿主里这段叫 `isOwnRoutePage`，在 `design-tools/src/mapping.ts`——那份与本库 `mapping.ts`
+ * 是同一组函数，迁到本库后宿主那份就只是重复实现，见 TODO P2-9。）
+ */
+export declare function isOwnRoutePage(routePath: string, category?: string, name?: string): boolean;

package/dist/types/org/dept-api.d.ts

@@ -0,0 +1,12 @@
+/** 部门列表（`parentId` 只取该父级下的直属子部门；`deptName` 为服务端过滤） */
+export declare function deptList(params?: {
+    deptName?: string;
+    parentId?: number | string;
+    status?: string;
+}): Promise<any[]>;
+/** 取某个父级下的**直属子部门**（一层一取；根层 parentId=0） */
+export declare function deptChildren(parentId?: number | string): Promise<any[]>;
+/** 部门详情（回显/拼全名路径用） */
+export declare function deptInfo(deptId: number | string): Promise<any>;
+/** 取某父级下的**整棵子树**（403 回退通道，见 dept-tree-source） */
+export declare function getDeptSubTree(parentId?: number | string): Promise<any[]>;

package/dist/types/org/dept-tree-source.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 部门树懒加载的「取数源」装配（搬自宿主 `#/utils/dept-tree-source.ts`）
+ *
+ * 为什么要有这一层：
+ *   - `/system/dept/list?parentId=<id>`：**真·只回一层**（最省），权限 `system:dept:list`；
+ *   - `/system/user/deptTree?parentId=<id>`：回该父级下的**整棵子树**（服务端不省），但权限是
+ *     `system:user:list` —— 与老「一次性取整棵树」的权限完全一致。
+ * 生产上角色权限不一定同时具备，所以优先用前者，**403 时自动回退**后者（只取返回子树的第一层），
+ * 避免「换了懒加载后某些角色看不到树」。回退会打 warn，便于发现权限没配好。
+ */
+import type { DeptNode, DeptTreeSource } from './dept-tree';
+/** 归一：`/system/dept/list`(deptId/deptName) 与 `/system/user/deptTree`(id/label) 两种形状都吃 */
+export declare function normalizeDeptNode(raw: any): DeptNode;
+/** 造懒加载取数源（带 403 回退；treeData 变深由调用方 attachChildren 处理） */
+export declare function createDeptTreeSource(): DeptTreeSource;

package/dist/types/org/dept-tree.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 部门树「异步加载」共享内核（纯逻辑，不 import 任何 api/组件，便于单测）。
+ *
+ * 背景：`/system/user/deptTree` 一次性返回整棵树（生产库 1000+ 节点），
+ * 系统页左树 / 低代码表单的组织选择器打开即全量渲染会有明显卡顿，改为**按层懒加载**：
+ *   - 一层一取：`/system/dept/list?parentId=<id>`（后端已支持 parentId 过滤）
+ *   - 回显：只有 id 时用 `/system/dept/{id}` 逐级向上拼「A / B / C」全名（带缓存）
+ *   - 搜索：本地没有全量树，改由调用方用服务端 `deptName` 过滤后交进来做平铺展示
+ *
+ * 注意（依赖后端数据约定）：根节点 `sys_dept.parent_id` 必须是 **0**（不能用 NULL），
+ * 否则第一层（parentId=0）就是空的 —— 2026-09-28 排查的 deptTree 返回 [] 正是这个原因。
+ */
+/** 后端部门节点最小字段（SysDeptVo 的子集，允许带业务扩展字段） */
+export interface DeptNode {
+    deptId: number | string;
+    deptName: string;
+    parentId: number | string | null;
+    [key: string]: any;
+}
+/** 异步取数接口（由调用方注入，便于测试与复用） */
+export interface DeptTreeSource {
+    /** 取某父级下的直属子部门；根层 parentId=0 */
+    loadChildren: (parentId: number | string) => Promise<DeptNode[]>;
+    /** 取单个部门（回显/拼全名路径用）；取不到返回 undefined */
+    loadNode: (deptId: number | string) => Promise<DeptNode | undefined>;
+}
+/** 树节点（antd Tree 消费的形态） */
+export interface DeptTreeNode {
+    key: string;
+    title: string;
+    /** 已知没有子节点时置 true（未取过则 undefined：保留展开箭头，取回空列表后由缓存纠偏） */
+    isLeaf?: boolean;
+    children?: DeptTreeNode[];
+    /** 原始部门数据（选中时取 id / 派生取值用） */
+    raw: DeptNode;
+}
+/** parentId 归一：null/''/'0'/0 → '0'（RuoYi 根层口径） */
+export declare function normalizeParentId(parentId: null | number | string | undefined): string;
+export declare function toTreeNode(dept: DeptNode, isLeaf?: boolean): DeptTreeNode;
+/**
+ * 不可变地把 children 挂到指定 key 的节点上（antd Tree 懒加载用；返回新数组触发响应式）
+ * 找不到该 key 时原样返回（不改引用）。
+ */
+export declare function attachChildren(nodes: DeptTreeNode[] | undefined, key: number | string, children: DeptTreeNode[]): DeptTreeNode[];
+/**
+ * 懒加载部门树：一层一取 + 缓存 + 在途请求合并 + 全名路径解析。
+ * 同一个 parentId 重复调用不会重复请求（除非 force）。
+ */
+export declare function createLazyDeptTree(source: DeptTreeSource): {
+    childrenOf: (parentId: number | string, force?: boolean) => Promise<DeptNode[]>;
+    treeNodesOf: (parentId: number | string, force?: boolean) => Promise<DeptTreeNode[]>;
+    nodeOf: (deptId: number | string) => Promise<DeptNode | undefined>;
+    pathOf: (deptId: number | string) => Promise<{
+        chain: DeptNode[];
+        fullName: string;
+        node?: DeptNode;
+    }>;
+    searchNodes: (list: DeptNode[]) => Promise<DeptTreeNode[]>;
+    cachedLeaf: (parentId: number | string) => boolean | undefined;
+    clear: () => void;
+    readonly size: number;
+};

package/dist/types/registry.d.ts

@@ -0,0 +1,79 @@
+import type { Component } from 'vue';
+/**
+ * 自定义组件注册表（宿主注入）
+ *
+ * 背景：设计端配置里，自定义组件是用 **comname 字符串**引用的
+ * （`edit.type === 'hcm'`、`tool.type === 'hcm-tool'`、行操作 `action.comname`、表单 `type: 'my'`）。
+ * 这些组件属于**业务项目**，不能长在本库里，所以：
+ *
+ *   宿主启动时 `registerComponents({ comname: loader })` → 本库用 comname 查表渲染。
+ *
+ * 三个刻意的设计决定：
+ * 1. **键就是配置里的 comname，一个字都不能变**（数据库里存的是它）；
+ * 2. 值是**懒加载器**，本库统一用 `defineAsyncComponent` 包一层 —— 组件本体不进首屏 bundle，
+ *    且加载中有占位、加载失败有明确提示（不是空白一片，现场最好排查）；
+ * 3. 只有 `comname` 一条路，**不再支持按源码路径找组件**（旧 `import.meta.glob('/src/**')` 已废弃：
+ *    它把配置绑死在宿主的源码结构上，一重构就全废；线上发布快照里也没有这种用法）。
+ */
+/** 组件元信息（也用于「设计端可选项清单」与诊断页） */
+export interface DesignComponentMeta {
+    /** comname（注册表键，与设计端配置里的一致） */
+    name: string;
+    /** 给人看的名字（设计端下拉、诊断页用） */
+    title?: string;
+    /** 适用的宿主插槽，如 ['form-field'] / ['row-action'] / ['table-cell'] / ['toolbar'] / ['views'] */
+    slots?: string[];
+    /** 弹窗类组件的默认宽度（px），省得业务组件里再写一遍 */
+    modalWidth?: number | string;
+}
+/** 懒加载器：`() => import('...')` */
+export type DesignComponentLoader = () => Promise<any> | any;
+export interface DesignComponentEntry extends Omit<DesignComponentMeta, 'name'> {
+    loader: DesignComponentLoader;
+}
+/**
+ * 注册（可多次调用、支持增量）。同 comname 后注册的覆盖先前的。
+ *
+ * ```ts
+ * registerComponents({
+ *   'employee-select': () => import('./form-field/employee-select/index.vue'),
+ *   'salary-issue': {
+ *     loader: () => import('./row-action/salary-issue/index.vue'),
+ *     title: '薪资发放',
+ *     slots: ['row-action'],
+ *     modalWidth: 1000,
+ *   },
+ * })
+ * ```
+ */
+export declare function registerComponents(map: Record<string, DesignComponentEntry | DesignComponentLoader>): void;
+/** 是否已注册 */
+export declare function hasDesignComponent(name: string): boolean;
+/**
+ * 按 comname 取组件（异步包装过）。未注册返回 undefined ——
+ * 需要"必须存在"语义时用 `requireDesignComponent()`。
+ */
+export declare function resolveDesignComponent(name: string): Component | undefined;
+/**
+ * 按 comname 取组件，未注册直接抛错（错误信息里带插槽名，便于定位是哪种配置写错了）。
+ * 五类插槽（表单单元格 / 自定义列 / 工具条 / 行操作弹窗 / 整页）都走它，
+ * 保证"没注册"这件事在控制台和页面上是同一个说法。
+ */
+export declare function requireDesignComponent(name: string, slot?: string): Component;
+/** 已注册清单（诊断 / 启动日志用；不是设计端的选项来源，见 buildComponentsManifest 说明） */
+export declare function listDesignComponents(): DesignComponentMeta[];
+/**
+ * 生成「已注册组件」的清单（JSON 可序列化，诊断 / 自检用）。
+ *
+ * ⚠ 2026-10-27 拍板：**不再用清单给设计端下发**（原方案是宿主落成
+ * `public/ext-components.json` 或后端 `GET /design/extComponents`，design-ui 读它）。
+ * 现在设计端的 comname 是**手填**，真源是宿主工程的注册表文件本身
+ * （见工作区 `documents/comname-contract.md`）。本函数只用于诊断页、启动日志与自检，
+ * 不要拿它当"设计端选项来源"。
+ */
+export declare function buildComponentsManifest(): {
+    components: DesignComponentMeta[];
+    version: 1;
+};
+/** 仅测试用 */
+export declare function clearDesignComponents(): void;

package/dist/types/search/design-search.vue.d.ts

@@ -0,0 +1,46 @@
+import type { SearchFieldCell, SearchFormConfig } from '../types';
+type __VLS_Props = {
+    /** 模块分类 */
+    category?: string;
+    /** 配置名称 */
+    name?: string;
+    /** 直接传入配置（可选，跳过 API 请求），{cells:[[]]} 或二维数组 */
+    config?: SearchFormConfig | SearchFieldCell[][] | null;
+    /** label 宽度：'auto' 或像素值 */
+    labelWidth?: string | number;
+    /** 查询时是否过滤空值 */
+    filterEmpty?: boolean;
+    /** 是否显示查询/重置按钮 */
+    showActions?: boolean;
+    /** dev 悬浮按钮距容器顶部距离(px)；嵌套在其它设计组件内时下移，避免与父组件按钮重叠 */
+    devButtonTop?: number;
+};
+declare function getValues(): Record<string, any>;
+declare function getQueryValues(): Record<string, any>;
+declare function setValues(values: Record<string, any>): void;
+declare function handleQuery(): void;
+declare function handleReset(): void;
+declare const _default: import("vue").DefineComponent<__VLS_Props, {
+    getQueryValues: typeof getQueryValues;
+    getValues: typeof getValues;
+    handleQuery: typeof handleQuery;
+    handleReset: typeof handleReset;
+    setValues: typeof setValues;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (values: Record<string, any>) => any;
+    reset: () => any;
+    query: (values: Record<string, any>) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onChange?: ((values: Record<string, any>) => any) | undefined;
+    onReset?: (() => any) | undefined;
+    onQuery?: ((values: Record<string, any>) => any) | undefined;
+}>, {
+    name: string;
+    config: SearchFormConfig | SearchFieldCell[][] | null;
+    labelWidth: string | number;
+    category: string;
+    devButtonTop: number;
+    filterEmpty: boolean;
+    showActions: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/types/search/transformer.d.ts

@@ -0,0 +1,36 @@
+import type { SearchFieldCell } from '../types';
+/**
+ * 查询表单配置 → 表单 schema（搬自宿主 `design-search/src/transformer.ts`）
+ *
+ * 迁移时只改类型：`VbenFormSchema` / `VbenFormProps` 来自 `#/adapter/form` 与 `@vben/common-ui`，
+ * 都是 vben 源码导出（不能进 .d.ts，见 host.ts 文件头）⇒ 这里用结构化宽类型。
+ * 产出的对象形状与 vben 的 `VbenFormProps` 一致，宿主原样丢给表单组件即可。
+ */
+/** vben 表单字段 schema 的**最小结构**（只声明我们真正产出的字段，其余交给宿主类型） */
+export interface DesignFormSchema {
+    component: string;
+    componentProps?: Record<string, any>;
+    defaultValue?: any;
+    fieldName: string;
+    label: string;
+    [key: string]: any;
+}
+/** vben 表单配置的最小结构 */
+export interface DesignFormOptions {
+    commonConfig?: Record<string, any>;
+    schema: DesignFormSchema[];
+    wrapperClass?: string;
+    [key: string]: any;
+}
+/**
+ * 兼容多种后端返回结构：
+ * - `{cells: [[...]]}`（sform 接口）
+ * - 直接二维数组 `[[...]]`
+ * - 扁平数组 `[...]`（包装成单行）
+ */
+export declare function normalizeSearchCells(resp: any): SearchFieldCell[][];
+/**
+ * 将查询表单配置转换为 vben 查询表单配置（与角色管理等标准列表页风格一致）。
+ * 接受 sform 接口原始响应或二维数组。
+ */
+export declare function buildSearchFormOptions(resp: any): DesignFormOptions;

package/dist/types/table/data.d.ts

@@ -0,0 +1,30 @@
+import type { TableDataResponse } from '../types';
+/**
+ * 表格取数（从宿主 `components/design/api.ts` 的 `fetchTableData` 搬入）
+ *
+ * 与宿主的差别只有一处：宿主直接用自己的 alova 实例，这里走**注入的 http**
+ * （见 http.ts 顶部说明：库里绝不能自建请求实例，否则没有登录态、也没宿主的 401 处理）。
+ *
+ * 请求体契约（后端 `SelectBean`）见 `buildTableDataBody`：
+ * - `search` = 查询表单/查询页传进来的值（**只供动作条件 `${search.x}` 取值，后端不再自动按列过滤**）
+ * - `params` = 表达式 env = 组件自身参数（extraParams）+ 列表「查询参数」
+ * - `pageNo` 后端真正读的分页字段（`pageNum` 仅为兼容保留）
+ *
+ * `silent: true` 是硬要求：表格一次翻页会并发多条取数，让宿主每条都弹一次 toast 是不可接受的
+ * （见 documents/TODO.md 里 DesignRequestOptions.silent 的约定）。
+ */
+export interface FetchTableDataParams {
+    /** 列表基本信息里配的「查询参数」：只并入请求体 params（见 buildTableDataBody） */
+    configParams?: Record<string, any>;
+    /**
+     * 组件自身参数（路由参数 + 上游 parentParams）→ 只并入请求体 `params`（表达式 env），
+     * **不进 `search`**（2026-09-29 口径修正：进去会按列别名意外过滤，详见 buildQuerySearch）
+     */
+    envParams?: Record<string, any>;
+    pageNum: number;
+    pageSize: number;
+    search?: Record<string, any>;
+    /** 取消（翻页/换页签时应当中断上一次取数） */
+    signal?: AbortSignal;
+}
+export declare function fetchTableData(url: string, params: FetchTableDataParams): Promise<TableDataResponse>;

package/dist/types/table/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 表格（design-table）纯逻辑层
+ *
+ * 为什么先搬这些而不是先搬 `.vue`：
+ * - 这些是「配置 → 请求体 / vxe 配置」的转换规则，是设计端与后端之间的**契约实现**，
+ *   最容易在复制粘贴中悄悄漂移，也最容易单测（见 scripts/test-table-logic.mjs）；
+ * - 组件层（design-table.vue 等）依赖宿主的 vxe 适配、路由、图标、弹窗，迁移成本高一个量级，
+ *   见 documents/TODO.md 的 P2-9。
+ */
+export { fetchTableData } from './data';
+export type { FetchTableDataParams } from './data';
+export { buildQuerySearch } from './query-search';
+export { buildTableDataBody, parseConfigParams } from './query-body';
+export { evaluateLoadGate } from './load-gate';
+export type { LoadGateResult } from './load-gate';
+export { createQueryDedupe } from './query-dedupe';
+export type { QueryDedupe, QueryDedupeOptions, QueryDedupeStats, } from './query-dedupe';
+export { buildCustomParams, buildNavigateQuery, evaluateExpress, } from './row-action-mapping';
+export { transformTableConfig } from './transformer';
+export type { TransformHost, TransformTableResult } from './transformer';

package/dist/types/table/load-gate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 列表「数据加载条件」求值（搬自宿主 `components/design/design-runtime/load-gate.ts`）
+ *
+ * 配置位置：列表 `extra_config` 的 `query.when`（字符串表达式），作用域只有两个：
+ *   - `search`：查询表单当前值（第一次加载时是默认值）
+ *   - `params`：组件自身参数（含配置的查询参数）
+ *
+ * 与行操作 mappings 用同一套 JS 表达式写法（`new Function`），只是这里结果按布尔用。
+ *
+ * 求值策略（刻意这么定）：
+ *   - 表达式为空 → 视为「不门禁」，放行；
+ *   - 求值抛错（语法错/引用了不存在的变量导致异常）→ **拦截**，并返回错误信息。
+ *     放行会变成「静默加载全量数据」，比不加载更危险；拦截至少看得见提示。
+ */
+export interface LoadGateResult {
+    /** 表达式本身有问题时的原因（调用方可以展示出来，便于设计者排查） */
+    error?: string;
+    /** 是否允许加载 */
+    ok: boolean;
+}
+export declare function evaluateLoadGate(expression: null | string | undefined, scope: {
+    params?: Record<string, any>;
+    search?: Record<string, any>;
+}): LoadGateResult;

package/dist/types/table/query-body.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 表格取数请求体的组装（纯函数、无三方依赖 —— 便于单测，见 scripts/test-table-logic.mjs）。
+ *
+ * 后端契约（`ruoyi-vue-plus-5-demo`，权威）：
+ * 表格的 url 由 `ModuleGenerater` 固定生成为 `{module}/{code}/pager`，
+ * 对应 `DesignDataController` 的 `POST /{moduleName}/{code}/pager`，
+ * 用 `@RequestBody org.dromara.design.bean.SelectBean` 绑定。字段含义：
+ *
+ * - `search`  —— **查询表单/查询页传进来的值**：后端**不再**拿它自动按列别名拼 WHERE
+ *   （2026-09-29 口径修正：`ListProcesser`/`PagerProcesser` 里那段自动过滤已删除 —— 设计者没配过的键
+ *    也会静默多出一个过滤条件，实测把查询页传的 `name=1` 变成 `and name = ?`、数据被意外过滤）。
+ *   它现在**只**作为表达式 env（见下）供**动作条件**取值，如 `jobClass = search.code`。
+ * - `params`  —— **表达式 env**：`envs.put("params", ...)`，给配置里 `${params.x}` 这类条件用。
+ *   （与 search 是两套语义，不要混为一谈）
+ * - `pageNo` / `pageSize` —— 分页：`PagerProcesser` / `ListProcesser` 走 `buildPageSql(..., getPageNo(), getPageSize())`。
+ * - `id`      —— 单条语义（本接口的列表取数不用）。
+ */
+/**
+ * 组装表格取数请求体。
+ *
+ * 分页字段**同时下发 `pageNo` 与 `pageNum`**：
+ * - `pageNo` 是 SelectBean 的字段，后端真正读它；
+ *   此前只发 `pageNum` ⇒ `pageNo` 恒为默认值 1 ⇒ **翻页被忽略，第 2 页仍返回第 1 页数据**。
+ * - `pageNum` 一并保留：兼容 url 被手工改成标准 RuoYi 分页接口（`PageQuery` 读 `pageNum`）的配置。
+ *
+ * `configParams`（列表基本信息里配的「查询参数」）**只并入 `params`**、不进 `search`：
+ * 设计者写的是表达式环境的常量（如 `{"deptId":100}`），不是要拼进 WHERE 的条件；
+ * 同名键**以配置为准**（配置是设计者写死的强制约束），运行时参数排在后面被覆盖。
+ *
+ * 【2026-09-29 口径修正】**`search` 与 `params` 彻底分开**：
+ *   search = 查询条件（页面 search + 查询表单值，见 buildQuerySearch）
+ *   params = 表达式 env（组件自身参数 envParams + 配置的 configParams）
+ * 旧实现把整份 search 也并进了 params ⇒ 「查询表单的值」会出现在 params 里（语义混淆，
+ * 且上游参数被塞进 search 造成意外过滤）。现在两者各走各的，需要 `${params.x}` 取查询表单值的配置
+ * 应改为「按列别名的 search 过滤」，或把该值作为组件参数/「查询参数」下发。
+ */
+export declare function buildTableDataBody(pageNum: number, pageSize: number, search?: Record<string, any> | null, configParams?: Record<string, any> | null, envParams?: Record<string, any> | null): Record<string, any>;
+/**
+ * 解析列表配置里的「查询参数」为对象（config.queryParams，后端 query_params）。
+ *
+ * 容错口径（设计端/发布健康检查已各拦一道，这里只兜底，不抛错打断取数）：
+ * - 空白 / null / undefined → `{}`
+ * - 已是对象（后端若直接反序列化成 Map 也能接）→ 原样返回（浅拷贝）
+ * - 字符串 → JSON.parse；解析失败、或结果不是对象（数组/数字/字符串/null）→ `{}` + console.warn
+ */
+export declare function parseConfigParams(raw: null | Record<string, any> | string | undefined): Record<string, any>;

package/dist/types/table/query-dedupe.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 自动重建后的重复取数抑制（纯逻辑，便于单测，见 scripts/test-table-logic.mjs）。
+ *
+ * 背景：design-table 在「配置替换 / 表格高度实测 / 流程列追加」时会自增 gridKey，
+ * 让 vxe-grid 重建（列原地重排会触发 insertBefore，必须重建）。新实例挂载时
+ * proxyConfig 会再自动取一次同参数数据 —— 表现为点开一个页签后
+ * pager 请求两次、flowData/status 也两次。
+ *
+ * 方案：重建前 markRebuild()，重建后到来的同 key 查询直接复用上一次结果：
+ * - 上一次请求仍在进行中 → 共享同一个 Promise（flowData/status 也只发一次）
+ * - 上一次请求已完成 → 复用其结果对象
+ * 另外，任何时刻的「同 key 并发请求」都合并（同参数读接口重复请求恒为冗余）。
+ * 窗口期外、或 key 不同（翻页/排序/查询条件变了）则照常发请求。
+ * 用户显式刷新（工具条刷新按钮 / 外部 reload）前调用 reset() 可强制真实请求。
+ */
+export interface QueryDedupeOptions {
+    /** 重建后多久内到来的同参查询视为重复，默认 1500ms */
+    now?: () => number;
+    /** 可注入时钟（测试用），默认 Date.now */
+    windowMs?: number;
+}
+export interface QueryDedupeStats {
+    /** 实际发起请求的次数 */
+    fetched: number;
+    /** 命中进行中请求并共享 Promise 的次数 */
+    merged: number;
+    /** 命中已完成结果并复用数据的次数 */
+    reused: number;
+}
+export interface QueryDedupe {
+    /** 计数快照（开发面板可读） */
+    getStats: () => QueryDedupeStats;
+    /** 当前是否处在「自动重建后的去重窗口」内 */
+    isDedupeWindow: () => boolean;
+    /** gridKey 自增前调用：标记发生了一次自动重建 */
+    markRebuild: () => void;
+    /** 显式刷新前调用：关闭去重窗口，保证真实请求 */
+    reset: () => void;
+    /** 执行一次查询：命中重复则复用，否则调用 factory */
+    run: <T>(key: string, factory: () => Promise<T>) => Promise<T>;
+}
+export declare function createQueryDedupe(options?: QueryDedupeOptions): QueryDedupe;

package/dist/types/table/query-search.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 表格取数**查询条件**的组装（纯函数，无组件/三方依赖 —— 便于单测，
+ * 见 scripts/test-table-logic.mjs）。
+ *
+ * 产出交给 `fetchTableData` 作为请求体的 `search`。**注意后端口径（2026-09-29 修正）**：
+ * `search` 不再被自动按列别名拼成 WHERE，它只是**动作条件的取值来源**（`${search.x}`，如 `jobClass = search.code`）；
+ * 要不要过滤、过滤哪一列，由设计者在动作条件里显式写。请求体的 `params`（表达式 env）不在这里产出，
+ * 见 query-body.ts 的 buildTableDataBody。
+ */
+/**
+ * 组装取数用的 `search`（查询表单/查询页的值）。
+ *
+ * 优先级（后者覆盖前者，同名键）：
+ *   1. pageSearch   页面显式传入的查询条件（如 DesignSearch 点「查询」后的值）
+ *   2. formValues   表格自身绑定的查询表单值（config.searchForm，vben 代理查询注入）
+ *
+ * 【2026-09-29 口径修正】**不再并入组件自身参数（extraParams）**：
+ * 它是**页面上下文**（自己的路由参数 + 上游 parentParams），混进来会让请求体里出现设计者没打算要的键；
+ * extraParams 现在只进请求体的 `params`（表达式 env）。
+ */
+export declare function buildQuerySearch(pageSearch?: null | Record<string, any>, formValues?: null | Record<string, any>): Record<string, any>;

package/dist/types/table/row-action-mapping.d.ts

@@ -0,0 +1,36 @@
+import type { RowActionMapping } from '../types';
+/**
+ * 行操作「跳转 / 弹窗」动作的映射工具（从宿主 design-table/src/row-actions/mapping.ts 搬入）。
+ *
+ * `mappings: [{ paramName, express }]`，表示式作用域为 `{ params, row }`：
+ * - params：当前表格参数（外部注入的 extraParams / 路由 query）
+ * - row：当前行数据
+ *
+ * 表达式求值复用 `mapping.ts` 的 `evaluateMappedExpress`（同一套 `new Function` 口径，
+ * 作用域就是 `{ params, row }` 两个键 ⇒ 与旧实现的 `new Function('params','row', …)` 等价）。
+ */
+/** 执行映射表达式（字符串 JS 表达式），作用域注入 params、row。 */
+export declare function evaluateExpress(express: string | undefined, params: Record<string, any>, row: Record<string, any>): any;
+/**
+ * 「弹窗自定义组件」用的参数映射（2026-10-21）
+ *
+ * 与 {@link buildNavigateQuery} 的区别：那是**路由 query**，值必须字符串化（`String(val)`）；
+ * 这里是直接交给扩展包组件的 `params`，要**保留原值** —— 设计者配 `表达式=row` 时，
+ * 组件应该拿到整个对象，而不是 `"[object Object]"`。
+ *
+ * 同样没有兜底：没配 mappings 就返回 `{}`，不自动塞 row / id。
+ */
+export declare function buildCustomParams(mappings: RowActionMapping[] | undefined, params: Record<string, any>, row: Record<string, any>): Record<string, any>;
+/**
+ * 根据 mappings 生成跳转 query 参数。
+ *
+ * **没有任何兜底**（2026-10-21 用户口径："没配 mappings 时不需要任何参数，不要有兜底"）：
+ * - 配了 mappings → 按 express 求值映射为 paramName 参数；
+ * - 没配 mappings → 返回 `{}`，目标视图一个参数都收不到。
+ *
+ * 以前这里在 mappings 为空时回退成 `{ id: row[pfield] }`，结果「跳转到列表」这类动作凭空带上
+ * `id=33333`，目标页把它当 extraParams 塞进请求体 —— 属于设计者没配的参数。
+ * 现在要传行 id 就在设计端显式配一条映射（paramName=id / express=row.id）；
+ * 「跳转表单 / 弹窗表单」同理：不配 id 映射就打开一张新表单，不再隐式按行 id 打开记录。
+ */
+export declare function buildNavigateQuery(mappings: RowActionMapping[] | undefined, params: Record<string, any>, row: Record<string, any>, _pfield?: string): Record<string, string>;