@jzg223/design-runtime 0.0.1 → 0.1.0-rc.2

package/dist/types/board-engine/data-hub.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 部件取数的统一入口（**相同查询合并 + 短 TTL 缓存**）。
+ *
+ * 为什么需要：一个大屏上经常有 5~10 个部件绑同一个数据集、同样的维度度量，
+ * 每个部件各打一次库既慢又浪费；这里按请求体指纹合并请求。
+ * TTL 很短（默认 1.5s），只用于合并同一轮渲染，**不影响"刷新"语义**（刷新走 `fetch(part, true)` + `clear()`）。
+ *
+ * 【框架中立】取数靠注入的 `fetchData`（运行端传 `requireHttp().post('/design/board/data/query')`），
+ * 引擎不知道 http 长什么样 —— 所以 design-ui（axios）与运行端（注入 http）能共用这一份。
+ *
+ * 缓存键 = 请求体的 `JSON.stringify`：键序由 {@link buildPartQuery} **逐个字段写死**，
+ * 所以同样的查询一定得到同样的字符串。别改成"把配置对象展开再 stringify"，键序不稳会导致缓存合并失效。
+ */
+import type { BoardDataQuery, BoardDataResult, BoardPart } from './types';
+/** 参数来源（`BoardParams.all()` 的形状；单独声明避免和 params.ts 循环引用） */
+export interface BoardParamSource {
+    all: () => Record<string, string>;
+}
+export interface BoardDataHubOptions {
+    /** 真正的取数函数；失败可 resolve(null) 或 throw（hub 会把 throw 收敛成 null） */
+    fetchData: (body: BoardDataQuery) => Promise<BoardDataResult | null | undefined>;
+    /** 看板级参数来源（缺省 = 无参数；用了 `createBoardParams` 就把实例传进来） */
+    params?: BoardParamSource;
+    /** 合并窗口（毫秒），默认 1500 */
+    ttl?: number;
+    /** 时钟（测试可注入） */
+    now?: () => number;
+}
+export interface BoardDataHubStats {
+    cacheSize: number;
+    inflightSize: number;
+}
+export interface BoardDataHub {
+    /** 部件配置 → 后端查询体（null 表示这个部件没绑数据） */
+    queryOf: (part: BoardPart) => BoardDataQuery | null;
+    /** 取数；失败/未绑定一律给 null（由调用方决定展示，绝不抛） */
+    fetch: (part: BoardPart, force?: boolean) => Promise<BoardDataResult | null>;
+    clear: () => void;
+    stats: () => BoardDataHubStats;
+}
+/**
+ * 由部件配置生成后端查询体（**纯函数**，单测直接打这个）。
+ *
+ * @param part   部件
+ * @param params 看板级参数（部件自身的 `data.params` 优先）
+ */
+export declare function buildPartQuery(part: BoardPart | null | undefined, params?: Record<string, string>): BoardDataQuery | null;
+export declare function createBoardDataHub(options: BoardDataHubOptions): BoardDataHub;

package/dist/types/board-engine/datav-meta.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DataV 边框 / 装饰的**元数据**（编号 → 中文名、推荐尺寸）。
+ *
+ * 【为什么单独一个文件】
+ * 25 个边框/装饰的**组件**在运行端要按 Vue3 实现（`@kjgl77/datav-vue3`，见 `board/datav-map.ts`），
+ * 而元数据是纯数据、与框架无关（设置面板下拉、选型脚本、单测都要用）。
+ * 拆开之后：运行端/设计端都只引本文件取元数据，组件各自的映射留在各自的视图层 ——
+ * 这样「编号 → 中文名/推荐尺寸」只有一份，不会两端口径不一致。
+ *
+ * 【推荐尺寸是怎么来的】（沿用 design-ui 的实测结论）
+ * 用「选型看板」把 13 个边框 + 12 个装饰按真实尺寸铺一页截图量的。DataV 的 decoration
+ * **不是都能随便拉伸**：
+ *   - 1/3/6/9：固定设计尺寸 + `transform:scale()` 撑满父容器 ⇒ 比例离谱时线段被拉粗/拉歪；
+ *   - 7：svg 写死 21×20 且不缩放 ⇒ 部件给大了只在左上角留一个小角标；
+ *   - 2/4/5/8/10/11/12：真按父容器尺寸画。
+ * 所以每个编号给一份推荐尺寸（同时也是"比例"建议：9/12 正方形、4 细高条）。
+ */
+/** 边框编号的中文名（取自各自画出来的样子） */
+export declare const DATAV_BORDER_META: Record<number, string>;
+/** 装饰编号 → 中文名 + 推荐尺寸 [w, h] */
+export declare const DATAV_DECORATION_META: Record<number, {
+    label: string;
+    size: [number, number];
+}>;
+/** 边框编号的默认值（设置面板里"选 DataV 边框"时的初值） */
+export declare const DATAV_BORDER_DEFAULT = 8;
+/** 装饰编号的默认值（部件类型默认就是这个；它的推荐尺寸也就是新部件的默认尺寸） */
+export declare const DATAV_DECORATION_DEFAULT = 5;
+/** 边框编号的中文名（未知编号回退成 `边框 N`） */
+export declare function datavBorderLabel(n: unknown): string;
+/** 装饰编号的中文名（未知编号回退成默认编号的名字） */
+export declare function datavDecorationLabel(n: unknown): string;
+/**
+ * 装饰的推荐尺寸 `[w, h]`。
+ * ⚠ 判断「用户有没有手动拉过」必须**宽高都比**：只比宽度会把用户拉过的框改回去。
+ */
+export declare function datavDecorationSizeOf(n: unknown): [number, number];

package/dist/types/board-engine/i18n.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 多语（看板内容级）。
+ *
+ * 设计取舍（沿用 design-ui，勿改）：
+ * - **不做词条级翻译表**（那是"应用多语"，属于平台框架的事），只做**看板内容多语**：
+ *   同一个部件在不同语言下显示不同文案（标题、文本、按钮字、页签名…）。
+ * - 覆盖值按**点路径**存：`part.i18n['en-US'] = { 'view.content': 'Hello', name: 'Title' }`。
+ *   好处是不用改配置结构，未翻译的字段自动回落到中文原文。
+ * - 渲染时用 {@link localizePart} 生成一份「本地化副本」，**不改原对象** ——
+ *   设计器里编辑的始终是原文，运行时看到的是当前语言的版本。这条最容易写错，务必保持。
+ */
+import type { BoardPart } from './types';
+export interface BoardLocale {
+    code: string;
+    label: string;
+}
+/** 可翻译字段的描述 */
+export interface BoardTranslatableField {
+    /** 点路径，如 `view.title` */
+    path: string;
+    label: string;
+    /** 值是"每行一项"的数组（页签、图片…） */
+    multi?: boolean;
+    /** 数组元素里真正要翻译的子键（如 carousel 的 `title`） */
+    sub?: string;
+}
+export declare const LOCALES: BoardLocale[];
+export declare const DEFAULT_LOCALE = "zh-CHS";
+/** 各部件类型里"可翻译的字段"（点路径 + 中文名）。只列用户可见文案，不列颜色/尺寸 */
+export declare const TRANSLATABLE: Record<string, BoardTranslatableField[]>;
+/** 某个部件可翻译的字段清单（含通用项） */
+export declare function translatableFields(part: BoardPart): BoardTranslatableField[];
+/** 读某个部件在指定语言下的某个字段（无覆盖则返回原文） */
+export declare function fieldText(part: BoardPart, locale: string, path: string, sub?: string): string;
+/** 写覆盖值（值统一按"每行一项"的文本存，数组字段在渲染时还原） */
+export declare function setFieldText(part: BoardPart, locale: string, path: string, text: string, sub?: string): void;
+/**
+ * 生成「当前语言下」的部件副本（不改原对象）。
+ * 渲染层用它，编辑层用原文 —— 这是本方案最容易出错的地方，务必保持这个分工。
+ */
+export declare function localizePart(part: BoardPart, locale: string): BoardPart;
+/** 某个部件是否已经翻译过（用于设计器里给个标记） */
+export declare function translatedCount(part: BoardPart, locale: string): number;

package/dist/types/board-engine/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 看板引擎（**设计端与运行端共用的纯逻辑层**）
+ *
+ * 铁律（改这里之前先读 `src/host.ts` 文件头的判断规则）：
+ * 1. **不许 import vue / echarts / antdv-next / @vben/***：本层必须能在 node 里裸跑（单测用）。
+ *    `npm run test:board` 会扫这个目录的 import 白名单，破了直接失败。
+ * 2. **不许碰全局**（`window._CONFIG` / `location` / `history`）：base url、http、locale 全部注入。
+ * 3. **不许有模块级可变单例**（参数 / 参数目录 / 主题令牌 / 取数缓存）：
+ *    一律 `create*()` 工厂；`default*` 实例只作为 design-ui 旧调用形态的兼容层存在。
+ *
+ * 边界：本层只算「配置 → 数据结构 / 样式值 / 请求体 / 图表 option」，不产出 DOM。
+ * 模板与 CSS 留在两端各自的视图层（Vue2 设计端 / Vue3 运行端）。
+ */
+export * from './asset';
+export * from './chart-option';
+export * from './data-hub';
+export * from './datav-meta';
+export * from './i18n';
+export * from './param-catalog';
+export * from './params';
+export * from './render-model';
+export * from './schema';
+export * from './theme-manifest';
+export * from './types';
+export * from './version';

package/dist/types/board-engine/param-catalog.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 看板级「参数目录」：把**数据集声明的参数**汇总成一份可查询的目录。
+ *
+ * 为什么要有它（沿用 design-ui 的结论，勿推翻）：
+ * 参数原来有**两套定义** —— 数据集那边声明 `paramCode/paramType/defaultValue/valueSource`，
+ * 筛选方案部件这边又手填一套 `paramCode/paramType/options`。同一个东西两处维护必然漂移
+ * （数据集把 period 的可选值改了，筛选部件的下拉还是老的；甚至筛选部件写的参数根本没有数据集声明，
+ * 点了没反应也不报错）。
+ *
+ * 现在的规则（**单一真源**）：
+ * - **数据集声明 = 真源**：参数存在与否、类型、默认值、可选值都以声明为准；
+ * - 筛选部件的 `paramType` / `options` 变成**可选的覆盖**：留空即跟随声明；
+ * - 老看板里手填过的那套仍然生效（向后兼容）；
+ * - 声明里没有的参数：设计器给警告；运行时就是什么都不会发生。
+ *
+ * 默认值不需要前端补种：后端 `BoardQueryBuilder` 已经会认声明里的 `defaultValue`。
+ *
+ * 【框架中立】取数靠注入的 `fetchParams`，响应解包（`{code,data}`）由调用方负责；
+ * 变化通知靠 `version` + `subscribe()`，不 import vue。
+ */
+import type { BoardParamDecl, BoardParamDeclEntry } from './types';
+export interface BoardParamCatalogState {
+    /** paramCode → 合并后的声明 */
+    byCode: Record<string, BoardParamDeclEntry>;
+    /** 已加载的数据集集合指纹（避免重复请求） */
+    loadedKey: string;
+    loading: boolean;
+    /** 任何变化 +1（视图层据此重算） */
+    version: number;
+}
+export interface BoardParamCatalogOptions {
+    /** 批量取多个数据集的参数声明；返回**已解包**的数组（不要 `{code,data}` 外壳） */
+    fetchParams?: (ids: string) => Promise<BoardParamDecl[] | null | undefined>;
+}
+/** 筛选部件"生效配置"（设计器与运行时共用，保证"设置里看到的"和"跑起来用的"一致） */
+export interface EffectiveFilter {
+    code: string;
+    declared: BoardParamDeclEntry | null;
+    /** 生效控件类型：部件覆盖 > 数据集声明 > 有手填选项当下拉 > 文本 */
+    type: string;
+    options: string[];
+    typeOverridden: boolean;
+    optionsOverridden: boolean;
+    /** 手填选项与声明不一致（设计器要提示） */
+    optionsMismatch: boolean;
+    typeMismatch: boolean;
+    /** 声明里只有"字典编码/机构类型"这类引用，本期不解析 */
+    reference: string;
+    /** 绑了一个没有任何数据集声明的参数 */
+    undeclared: boolean;
+}
+export interface BoardParamCatalog {
+    readonly state: BoardParamCatalogState;
+    /** 加载参数目录；`setIds` 是看板实际引用到的数据集 id（从 parts 的 data.setId 收集） */
+    load: (setIds: (string | number | undefined | null)[]) => Promise<BoardParamCatalogState>;
+    reset: () => void;
+    declared: (code: string) => BoardParamDeclEntry | null;
+    /** 目录里的全部参数（按编码排序，便于下拉展示） */
+    list: () => BoardParamDeclEntry[];
+    /** 用当前目录算某个筛选部件的生效配置 */
+    effectiveFilter: (view: Record<string, any> | undefined) => EffectiveFilter;
+    subscribe: (listener: (state: BoardParamCatalogState) => void) => () => void;
+}
+/** 从 `free,month,year` / 换行 / 分号 分隔的字符串里解析出可选值 */
+export declare function parseOptions(src: unknown): string[];
+/** 取值来源是"字典编码/机构类型"这类引用（无法就地解析）时返回它，否则返回 '' */
+export declare function valueSourceReference(src: unknown): string;
+/**
+ * 筛选部件的"生效配置"（纯函数）。
+ *
+ * 类型优先级：部件覆盖 > 数据集声明 > **有手填选项就当下拉**（老配置可能只填了 options 没填
+ * paramType，以前就是按 `options ⇒ 下拉` 渲染的，不能因为这次改动把它变成文本框）> 文本。
+ */
+export declare function effectiveFilterFor(view: Record<string, any> | undefined, declared: BoardParamDeclEntry | null): EffectiveFilter;
+export declare function createParamCatalog(options?: BoardParamCatalogOptions): BoardParamCatalog;
+/** 「一页一看板」的默认目录实例（兼容 design-ui 现有调用形态） */
+export declare const defaultParamCatalog: BoardParamCatalog;
+export declare const loadParamCatalog: (setIds: (string | number | undefined | null)[]) => Promise<BoardParamCatalogState>;
+export declare const resetParamCatalog: () => void;
+export declare const declaredParam: (code: string) => BoardParamDeclEntry | null;
+export declare const catalogList: () => BoardParamDeclEntry[];
+export declare const effectiveFilter: (view: Record<string, any> | undefined) => EffectiveFilter;

package/dist/types/board-engine/params.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 看板级参数（"筛选方案"部件写、各部件取数读）。
+ *
+ * 原理：筛选部件不直接改别的部件，而是写这里；取数时把这里的值合并进数据集参数
+ * （`{参数编码: 值}`，命中 SQL 里的 `#{Code}`）。改一次，所有用到该参数的部件一起刷新。
+ *
+ * 【为什么是工厂而不是模块级单例】（这是相对 design-ui 版本的**唯一实质改动**）
+ * design-ui 那边是模块级 `Vue.observable({...})`，一页只有一个看板，够用；
+ * 但运行端可能一页放两个看板（大屏里嵌套、页签并列）—— 单例会让两个看板串参数。
+ * 所以这里改成 `createBoardParams()`，每个看板实例一份；另外导出 `defaultBoardParams`
+ * 给"一页一看板"的旧调用形态兜底（design-ui 换包时行为不变）。
+ *
+ * 【框架中立】不 import vue：`state` 是普通对象，变化靠 `version` 计数 + `subscribe()`。
+ * 视图层自己决定怎么观察它（Vue3 `reactive` / Vue2 `Vue.observable` 都可以）。
+ */
+import type { BoardParamState } from './types';
+export interface BoardParams {
+    /** 普通对象（引用稳定，可直接交给 Vue.observable / reactive 包一层） */
+    readonly state: BoardParamState;
+    /** 写一个参数（重复写同一个值不 +version） */
+    set: (code: string, value: unknown) => void;
+    get: (code: string) => string | undefined;
+    /** 全部生效参数（值一律字符串） */
+    all: () => Record<string, string>;
+    /** 清空全部参数 */
+    reset: () => void;
+    /** 订阅变化，返回取消订阅函数 */
+    subscribe: (listener: (state: BoardParamState) => void) => () => void;
+}
+export declare function createBoardParams(initial?: Record<string, unknown>): BoardParams;
+/** 「一页一看板」的默认实例（兼容 design-ui 现有调用形态；多实例场景请自己 create） */
+export declare const defaultBoardParams: BoardParams;
+/** 同一个状态对象上的便捷函数（走默认实例） */
+export declare const setParam: (code: string, value: unknown) => void;
+export declare const getParam: (code: string) => string | undefined;
+export declare const allParams: () => Record<string, string>;
+export declare const resetParams: () => void;

package/dist/types/board-engine/render-model.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 看板部件的**渲染契约**（引擎 → 视图层的唯一出口）
+ *
+ * 为什么要有这一层（这是"漂移治理"的 L2 抓手，见方案文档 §3.1）：
+ * 设计端（Vue2）与运行端（Vue3）是两套模板，但**布局与样式值必须由同一处算出来**。
+ * 两边模板只做"把模型铺进 DOM"这件事：
+ *
+ * ```
+ * <div :class="m.classes" :style="m.outerStyle">      ← 外层：定位（free/grid/stack）
+ *   <div class="part-body" :style="m.panelStyle">     ← 内层：底色/圆角/描边/投影
+ *     <div class="part-head" v-if="m.title">…</div>   ← 标题（chip/bar + 让位）
+ *     内容区（pad = m.pad）
+ *   </div>
+ * </div>
+ * ```
+ *
+ * 谁要算样式，就调这里；**不要在模板里再写一套**（写一套 = 多一个漂移源）。
+ * 类型是真的（本文件是强类型门面），底下 `schema.ts` 是搬来的宽松实现。
+ */
+import type { BoardPage, BoardPart } from './types';
+/** 三种布局：自由定位（大屏）/ 栅格（门户）/ 堆叠（手机单列） */
+export type BoardRenderLayout = 'free' | 'grid' | 'stack';
+export interface BoardPartTitleModel {
+    /** chip = 胶囊骑在框线上（默认）；bar = 框内标题条 */
+    style: 'chip' | 'bar';
+    text: string;
+    /** 相对面板上沿的偏移（正=上移，0=齐平，负=进入面板内） */
+    offset: number;
+    /** 相对内边距的额外左缩进 */
+    inset: number;
+    /** 内容区顶部要**额外**让出的高度（px） */
+    reserve: number;
+}
+export interface BoardPartDecorModel {
+    /** DataV 边框编号（13 种，见 datav-meta） */
+    border: unknown;
+    /** DataV 装饰编号（12 种） */
+    decoration: unknown;
+    /** 容器的边框预设：none / corner / cut / glow / datav */
+    borderPreset: string;
+    /** 四角切角开关 */
+    corner: boolean;
+    /** 内侧微光开关 */
+    glass: boolean;
+}
+export interface BoardPartRenderModel {
+    id: string;
+    type: string;
+    layout: BoardRenderLayout;
+    /** 布局部件（容器 / tab 容器 / 静态边框） */
+    isContainer: boolean;
+    /** 内容性部件（有卡片底的：kpi/chart/table/crossTable/progress/filter） */
+    isCard: boolean;
+    /** 外层定位样式（free：absolute + px；grid：grid-column/row；stack：流式） */
+    outerStyle: Record<string, any>;
+    /** 内层面板外观（底色/圆角/描边/投影），写到 `.part-body` */
+    panelStyle: Record<string, any>;
+    /** 内边距（**不只是外观**：容器几何换算也用它） */
+    pad: number;
+    /** 没有标题就给 null（模板据此不渲染标题条，也不占高度） */
+    title: BoardPartTitleModel | null;
+    decor: BoardPartDecorModel;
+    /** 容器内子级布局：grid / free */
+    childLayout: string;
+    /** 能不能装子级（容器类） */
+    canHostChildren: boolean;
+    /** 渲染层照加的类名（顺序稳定，便于两端 CSS 命中同一套选择器） */
+    classes: string[];
+}
+export interface BoardPartRenderOptions {
+    /** 覆盖布局（正常情况下由 page.layoutMode 决定；手机堆叠时传 'stack'） */
+    layout?: BoardRenderLayout;
+    /** 栈布局下容器的高度要按子级数量决定 */
+    childCount?: number;
+}
+/** 页面布局模式 → 渲染布局（`grid` 以外都算自由定位，与 design-ui 一致） */
+export declare function resolveLayout(page?: BoardPage | null, override?: BoardRenderLayout): BoardRenderLayout;
+/**
+ * 部件渲染模型。
+ *
+ * @param part    部件（已做过 `localizePart` 的话就是当前语言下的副本）
+ * @param page    页面配置（布局模式/栅格参数）
+ * @param options 覆盖项（堆叠布局、子级数量）
+ */
+export declare function partRenderModel(part: BoardPart, page?: BoardPage | null, options?: BoardPartRenderOptions): BoardPartRenderModel;
+/** 容器的子级栅格声明（外层 `display:grid` 用；容器与页面共用一套换算） */
+export declare function containerChildrenStyle(part: BoardPart, page?: BoardPage | null, innerWidth?: number): Record<string, any>;