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

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

@@ -0,0 +1,513 @@
+/**
+ * 看板配置的「schema 层」：**配置 → 部件 / 布局 / 样式值** 的全部纯计算。
+ *
+ * 来源：`design-ui/src/views/board/engine/schema.js`（1328 行）**逐字搬运**，
+ * 改动只有两类：文件头本注释 + 参数上的 `: any` 标注（纯打字，无行为改动）。
+ * 设计端与运行端因此共用同一份"配置语义"—— 这是 D2「引擎单源」的核心，
+ * 任何时候都**不要**在运行端再抄一份。
+ *
+ * ⚠ 类型状态（**技术债，已登记 TODO P6-48**）
+ * 原文件是 1300 行无类型 JS，80 个导出里大量 `(part, page)` 这种宽松参数。
+ * 本轮的取舍：**行为先对齐**，参数一律标 `any`（能过 strict），不手抄、不改逻辑。
+ * 类型的真正出口是 `render-model.ts`（新写、强类型），运行端只依赖它；
+ * 本文件的行为由 `scripts/test-board-engine.mjs` 的 fixture 锁住。
+ * 收紧顺序：先给 `parseConfig` / `partStyle` / `gridPartStyle` / `partVisible` 补真实类型，
+ * 其余按被调用频率逐步来，不要一次重写。
+ *
+ * ⚠ 改这个文件的规矩
+ * 1. 只做**定点补丁**（edit 工具 + 唯一锚点），不要整段重写；
+ * 2. 任何行为改动都要同步 design-ui 那份（`@board/engine/schema.js`）—— 两边不一致就是漂移；
+ * 3. 不许 import 任何东西（本层必须零依赖：这条现在靠"没有 import"保证）。
+ */
+/**
+ * 看板配置契约（前后端共用的一份 JSON 结构）
+ *
+ * {
+ *   version: 1,
+ *   page: { width, height, scaleMode, minScale, fontAdaptive, minFont,
+ *           theme, chartTheme, bgColor, bgImage, opacity,
+ *           grid:{show,size,snap}, guides, scroll, watermark,
+ *           layoutMode:'free'|'grid', gridCols, gridRowHeight, gridGap, gridAutoHeight },
+ *   parts: [ {
+ *     id, type, name, x, y, w, h, z, hidden, locked,
+ *     // 栅格定位（顶层栅格与容器内子栅格共用这三个字段，参照系不同）
+ *     col, colSpan, rowSpan,
+ *     // 容器嵌套：空串 = 顶层；tabIndex 只对 tab容器的子级有意义
+ *     parentId, tabIndex,
+ *     style: { bg, opacity, border:{width,style,color,radius}, shadow:{enable,color,blur,spread,x,y}, rotate },
+ *     text:  { fontFamily, fontSize, bold, italic, color, align },
+ *     data:  { setId, dims:[], measures:[{field,agg,alias}], filters:[], params:{}, sort:{field,dir}, limit },
+ *     view:  { ... 按 type 不同 ... }
+ *   } ]
+ * }
+ *
+ * 【为什么是"扁平数组 + parentId"而不是嵌套 children】
+ *  - 老配置没有 parentId ⇒ 全部当顶层，行为与从前完全一致（向后兼容，迁移不怕）。
+ *  - find/删除/复制/撤销快照/模板导入导出/多语写回 这些现有逻辑全都在扁平数组上跑，一行都不用改。
+ *  - 跨容器搬运 = 改一个字段；嵌套 children 则要在两棵子树上 splice，容易错。
+ *  - DOM 顺序仍与数组顺序一一对应（见下），设计器拖拽的下标映射不受影响。
+ *
+ * 【子级怎么定位】容器内部**永远**是一套 24 列子栅格（与整页 layoutMode 无关）：
+ * 列宽跟着容器宽度走，所以容器一变宽子级就重排；行高/间距/列数沿用 page 上的那三个数
+ * （不再给容器单独加一套数，避免"两处数字对不上"）。
+ * 顶层在 free 模式下用 x/y/w/h，进容器后改用 col/colSpan/rowSpan，进出容器时自动换算。
+ *
+ * 【DOM 顺序 = 数组顺序】这条不变式必须守住：一个容器在数组里紧跟它的子级（深度优先），
+ * 渲染出来的 .part 节点 document order 就与数组一致，拖拽/命中的下标映射才成立。
+ */
+export declare const PART_TYPES: {
+    type: string;
+    label: string;
+    icon: string;
+    group: string;
+    w: number;
+    h: number;
+}[];
+export declare const CHART_TYPES: {
+    value: string;
+    label: string;
+}[];
+export declare const DEFAULT_THEME = "tech-blue";
+/**
+ * 能装子部件的容器类型。
+ * 三个都是"一个盒子"，共用同一套子栅格渲染；区别只在盒子的外观与分页行为。
+ */
+export declare const CONTAINER_TYPES: string[];
+export declare const isContainer: (type: any) => boolean;
+/**
+ * 部件的显示条件（**看板参数驱动**）—— 导航切页的核心机制。
+ *
+ *   view.visibleWhen = { param: 'nav', in: ['overview'] }
+ *   view.visibleWhen = { param: 'nav', notIn: ['overview'] }
+ *
+ * 语义：
+ *   - 没写 visibleWhen（或没写 param）⇒ 永远显示
+ *   - in    ：参数值命中其一才显示（不填 = 不限制）
+ *   - notIn ：参数值命中其一就隐藏
+ *   - 参数未设/为空串 ⇒ 按 '' 比较；所以 `in: ['overview']` 的部件在"什么都没选"时不显示，
+ *     想让它在默认态也显示，就把 '' 或默认值写进 in。
+ *
+ * ⚠ 隐藏的部件**不创建组件** ⇒ 天然不会去取数（隐藏页不会白发请求）。
+ * ⚠ 设计器里不过滤（否则第 2 页的部件根本选不中）：PartNode 用 design 开关区分。
+ */
+export declare function partVisible(part: any, params: any): boolean;
+/**
+ * 部件类型徽标文案（**只在设计器画布上用**，运行时/预览页不显示）。
+ * 图表额外带上图型，因为"图表"和"环形图"在画布上看起来完全是两回事：
+ * chart·donut / chart·hbar / kpi / table / text / border / container …
+ * 用类型标识符而不是中文名，是为了让设计器与「部件设置」里的类型下拉、
+ * 以及配置 JSON 里的 `type` 字段能一一对上。
+ */
+export declare const partTypeBadge: (part: any) => string;
+/** 聚合的中文名（多度量时用来给数值列起个不歧义的表头） */
+export declare const AGG_LABELS: Record<string, string>;
+/**
+ * 度量列/系列该显示什么名字。
+ *  - 度量自己起了别名（alias ≠ field）→ 用别名
+ *  - 否则用"字段别名（聚合）"，例如「任务名称（计数）」
+ * 为什么不用裸的字段别名：明细表里"任务名称"既可能是维度列又可能是 count 出来的数值列，
+ * 两个同名列完全分不清（多度量上线后这个问题会立刻暴露）。
+ */
+export declare function measureLabel(measure: any, fieldAlias: any): any;
+/**
+ * 舞台底色（画布背后那一层）。
+ * ⚠️ 设计器与运行时**必须用同一个值**：早先只有运行时写死 `#0d131c`、设计器用 `page.bgColor`（大屏常常是空的），
+ * 结果设计器里深色看板"发白"——部件的底色都是半透明的，叠在浅色页面底上全部变浅、白字几乎看不见（实测踩到）。
+ */
+export declare const STAGE_BG = "#070c18";
+/**
+ * 部件缺省观感的**归属划分**（2026-09 与用户确认的规范）：
+ *
+ *  - **布局部件 = 容器**（自由容器 / tab容器 / 静态边框）拥有"面板"：底色渐变 + 圆角 + 投影
+ *    （再加上容器自己的装饰语言：四角切角 / 上沿高光 / 内侧微光）。
+ *  - **内容部件**（指标卡 / 图表 / 明细表 / 交叉表 / 进度 / 筛选）**不再自带底色与投影**，
+ *    只画自己的数据（坐标轴、扇形、表格……）⇒ 一个容器里放几块内容都只是在同一块面板上分区。
+ *
+ * 为什么反过来（之前的做法是内容部件自带卡片底）：容器包住内容部件时，
+ * 面板底缩在内框里、容器只剩一圈空框 ⇒ 看着像"空框里浮着一块牌子"，很怪异（用户截图指出）。
+ * 反过来之后：面板 = 容器的框，内容贴在面板上，这才是大屏里最常见的"模块"结构。
+ *
+ * 老配置里显式写了自己的 style 的，一切以配置为准（deepMerge 时配置值优先）。
+ */
+export declare const CARD_TYPES: string[];
+/** 内容部件缺省：透明（底色/投影都由容器负责）、**直角**（2026-09 用户要求：整套改成硬边/切角语言，先去掉圆角） */
+export declare const CARD_STYLE: {
+    bg: string;
+    border: {
+        width: number;
+        style: string;
+        color: string;
+        radius: number;
+    };
+    shadow: {
+        enable: boolean;
+        color: string;
+        blur: number;
+        spread: number;
+        x: number;
+        y: number;
+    };
+};
+/**
+ * 布局部件（容器）缺省：**不画底色、不画投影**（2026-09 用户："这种风格应该在主题里定义好，
+ * 不用每个部件再单独设置"）⇒ 面板底与投影由**主题 CSS** 给（`--brd-panel-bg` / `--brd-panel-shadow`，
+ * 见 public/theme/*.css 与 PartRenderer 的 .part-body.is-panel 规则）；
+ * 某个容器想跟主题不一样时，再在部件设置里显式配底色/投影（内联样式优先）。
+ * 圆角与描边同样默认 0/无，装饰由 CONTAINER_DECOR 那套负责。
+ */
+export declare const PANEL_STYLE: {
+    bg: string;
+    border: {
+        width: number;
+        style: string;
+        color: string;
+        radius: number;
+    };
+    shadow: {
+        enable: boolean;
+        color: string;
+        blur: number;
+        spread: number;
+        x: number;
+        y: number;
+    };
+};
+/**
+ * 容器类部件的**装饰语言**（默认值 + 读取函数）。
+ *
+ * 规范（2026-09 与用户确认）：
+ *  - "四角切角 / 上沿高光 / 内侧微光"是**框的语言** ⇒ 只给容器（自由容器 / tab容器 / 静态边框），
+ *    而且做成部件级可配 —— 同一个看板里"这块要框起来强调、那块只是分区"是版式的决定。
+ *  - 数据类部件（图表 / 交叉表 / 明细表 / 指标卡 / 进度 / 筛选）**不给这些配置、也不画这些装饰**：
+ *    它们本身就是"内容"，外面已经有卡片底 + 描边 + 圆角 + 投影，再加框就是两层框；
+ *    而且一屏 10 个部件 = 40 个角标，装饰一泛滥就变成贴纸，反而抢数据的注意力。
+ *  - 老配置没有 view.decor 字段 ⇒ 按默认值渲染（不用改配置）。
+ */
+export declare const CONTAINER_DECOR: {
+    corner: boolean;
+    glass: boolean;
+};
+/**
+ * 容器的**边框样式预设**（借 DataV 那套"大屏边框"的视觉语言，但零依赖、跟主题变色、跟尺寸自适应）。
+ *
+ *  - `corner`（默认）：四角 L 形括号 —— 最轻，适合"框住一组内容"
+ *  - `cut`           ：八角切角描边（四条边 + 四个 45° 斜切角）—— 最像 DataV 的 border-box，
+ *                      科技感强、又不会把内容压住（描边压在容器内沿 6px 处）
+ *  - `glow`          ：整圈细描边 + 沿上边缓慢流动的光带（CSS 动画，无 JS）
+ *  - `none`          ：不画框
+ * 老配置没有 view.borderPreset 字段 ⇒ 用 decor.corner 的开关（true→corner / false→none），行为不变。
+ */
+export declare const BORDER_PRESETS: {
+    value: string;
+    label: string;
+}[];
+/** 读取容器的边框样式（兼容老的 decor.corner 开关） */
+export declare function borderPresetOf(part: any): any;
+/** 读取某容器的装饰开关（缺字段用默认；数据类部件调用它也会得到默认值，但渲染时不使用） */
+export declare function decorOf(part: any): {
+    corner: boolean;
+    glass: boolean;
+};
+/**
+ * 主题色系：图表调色板 + 画布底色 + 观感令牌（卡片/提示框/发光/网格底纹）。
+ *
+ * 改版口径（2026-09）：从"平铺的深蓝玻璃卡片"改成**大屏科技感**——
+ * 底色不再是纯色而是"径向光晕 + 细网格"的舞台；卡片上沿有高光细线、四角有切角装饰、
+ * 描边带发光；指标数字有辉光；图表线/柱/扇形都带同色辉光。
+ * 所有令牌都**按主题给**，浅色主题（极光白）把发光换成轻投影，免得白底上一片糊。
+ */
+export declare const THEMES: Record<string, any>;
+/** 登记某个主题从 CSS 读到的令牌（null/undefined 的字段不覆盖内置值；只认内置主题里有的键） */
+export declare function setThemeTokens(code: any, tokens: any): void;
+/** 只给测试/调试用：清空覆盖 */
+export declare function resetThemeOverrides(): void;
+export declare function themeOf(code: any): any;
+/** 新建看板的默认整页配置 */
+export declare function defaultConfig(width?: number, height?: number): {
+    version: number;
+    page: {
+        width: number;
+        height: number;
+        layoutMode: string;
+        mobileMode: string;
+        gridCols: number;
+        gridRowHeight: number;
+        gridGap: number;
+        gridAutoHeight: boolean;
+        scaleMode: string;
+        minScale: number;
+        fontAdaptive: boolean;
+        minFont: number;
+        theme: string;
+        chartTheme: string;
+        bgColor: any;
+        bgImage: string;
+        opacity: number;
+        grid: {
+            show: boolean;
+            size: number;
+            snap: boolean;
+        };
+        guides: boolean;
+        scroll: boolean;
+        watermark: string;
+    };
+    parts: never[];
+};
+export declare function newPartId(): string;
+/** 部件的公共缺省形状（不含 id / name，供"补齐缺省字段"复用） */
+export declare function basePartShape(type: any): any;
+/**
+ * 补齐部件的缺省字段（就地返回合并后的新对象，由调用方决定怎么用）。
+ *
+ * 为什么需要：配置可能来自**模板导入 / 手写 JSON / 旧版本产物**，里面的部件往往只有
+ * 业务字段，没有 `style.border`、`style.shadow` 这些"从来没人改过"的嵌套对象。
+ * 而设置面板直接读 `part.style.border.width`、渲染器读 `part.view.xxx`，
+ * 少一层就抛 TypeError —— 更糟的是**生产构建下这个渲染异常是静默的**
+ * （部件设置面板整块空白、控制台干净），排查成本极高（实测踩到）。
+ * 所以统一在 parseConfig 的清洗阶段按类型补齐，缺什么补什么，已有值一律保留。
+ */
+export declare function fillPartDefaults(part: any): any;
+/**
+ * 去掉与"类型缺省值"完全相同的字段（保存前调用）。
+ *
+ * 【为什么必须做这一步】`fillPartDefaults()` 会在**读取配置时**把缺省值写进内存里的部件对象；
+ * 而设计器的保存是 `JSON.stringify(this.config)` —— 于是"当时的缺省值"就被固化进 config_json。
+ * 之后再去调缺省值（比如把内容性部件的卡片描边从 1px 改成 0），对那些配置**一律不生效**
+ * （显式值优先），表现为"代码改了、页面上没变"，非常费解（这次就踩了：用户在设计器里保存过一次）。
+ *
+ * 口径：只处理 `style / text / view / data` 四块里的字段，递归比较；与缺省值相等的键直接删掉。
+ * 用户改过的值一定与缺省值不同 ⇒ 不会被删。几何字段（x/y/w/h/col…）与 id/name 不处理。
+ */
+export declare function stripPartDefaults(part: any): any;
+/** 整份配置：保存前把每个部件里"等于缺省值"的字段剥掉（见 stripPartDefaults 的说明） */
+export declare function stripConfigDefaults(cfg: any): any;
+/** 按类型建一个部件（默认配置） */
+export declare function createPart(type: any, overrides?: {}): any;
+export declare function deepMerge(target: any, source: any): any;
+/** 解析后端返回的 config_json（字符串或对象都能吃） */
+export declare function parseConfig(raw: any, fallbackSize: any): any;
+/** 按 z 排序后的部件（渲染顺序） */
+export declare function sortedParts(parts: any): any[];
+/** 取某个容器的子级（可再按页签过滤） */
+export declare function childParts(parts: any, parentId: any, tabIndex: any): any;
+/** 某部件的全部后代 id（含自己），用于级联删除与防环 */
+export declare function descendantIds(parts: any, id: any): any[];
+/** 这个部件能否作为容器接收子级（任意层级的容器都可以） */
+export declare function canHostChildren(part: any): boolean;
+/**
+ * 容器内子级的定位方式。
+ *  - 'grid'（默认，兼容老配置）：容器内一套 24 列子栅格，子级跟着容器宽度重排
+ *  - 'free'：子级用 x/y 相对容器左上角绝对定位（自由摆放，不随容器宽度重排）
+ */
+export declare function childLayoutOf(container: any): any;
+/**
+ * 某个部件当前的"定位权威"：决定 x/y/w/h 与 col/colSpan/rowSpan 哪个说了算。
+ * 顶层看页面 layoutMode，子级看父容器的 childLayout。
+ */
+export declare function layoutAuthority(part: any, parentPart: any, page: any): any;
+/** 容器内部子栅格的几何：列数/行高/间距沿用 page，宽度取容器内框宽度 */
+export declare function containerGrid(page: any, innerWidth: any): {
+    gridCols: any;
+    gridRowHeight: any;
+    gridGap: any;
+    width: any;
+};
+/** 容器内边距默认值（**参与几何换算**，不只是外观：见 paddingOf 注释） */
+export declare const CONTAINER_PAD = 10;
+/** 内边距允许范围（设置面板里也用它做 min/max） */
+export declare const CONTAINER_PAD_MIN = 0;
+export declare const CONTAINER_PAD_MAX = 40;
+/**
+ * 容器的内边距（部件级可配，默认 {@link CONTAINER_PAD}）。
+ *
+ * ⚠️ 它**不只是样式**：容器内框宽度 = 盒子宽 - 边框×2 - padding×2，
+ * 子栅格的列宽、以及"拖进容器时按落点算起始列"都依赖它。
+ * 所以这个值必须由这里统一提供，别在渲染/设计器里再写死 10。
+ */
+export declare function paddingOf(part: any): number;
+/** 容器标题的样式：chip=胶囊骑在框线上（默认，老看板观感不变）/ bar=框内标题条 */
+export declare function titleStyleOf(part: any): "bar" | "chip";
+/**
+ * 容器内子栅格的行高方式：
+ *   'fixed'（默认，老行为）= minmax(行高, auto)，跨 N 行就是 N×行高+(N-1)×间距 —— 与整页同一套；
+ *   'fill'                = 行高按容器内区**均分**（minmax(0, 1fr)），子级跨满时正好填满内框。
+ *
+ * 为什么需要 'fill'：容器内区 = 容器高 - 2×内边距。用固定行高时**内边距会把子级挤出去**：
+ * 子级跨 R 行的高度是 R×行高+(R-1)×间距，比"内区"高出正好 2×内边距 ⇒ 容器内部出现滚动条、
+ * 子级底部被裁。而"1:1 把某个部件包进容器"这种场景，恰恰希望内外大小严丝合缝 —— 那就把内边距
+ * 当"留白"用、行高改成撑满（本模式）；子级会小一圈，但完整可见。
+ */
+export declare function childRowsOf(part: any): "fixed" | "fill";
+/** 标题条占用的高度（padding 之外额外让出的空间）；chip 骑在框线上时不占内容高度 */
+export declare const TITLE_BAR_HEIGHT = 34;
+/** 胶囊标题的近似高度（用于"标题挪进面板内"时给内容让位） */
+export declare const TITLE_CHIP_HEIGHT = 20;
+/** 标题上移默认值（px）：0 = 与面板上沿齐平（标题在面板内，让开左上角的切角标记） */
+export declare const TITLE_OFFSET_DEFAULT = 0;
+export declare const TITLE_OFFSET_MIN = -20;
+export declare const TITLE_OFFSET_MAX = 40;
+/** 标题左缩默认值（px）：相对"容器内边距"再多缩进一点（0 = 与内容左边缘完全对齐） */
+export declare const TITLE_INSET_DEFAULT = 8;
+export declare const TITLE_INSET_MIN = -20;
+export declare const TITLE_INSET_MAX = 120;
+/**
+ * 标题的横向位置：相对容器内边距的**额外缩进**（px）。
+ * 0 = 与内容左边缘对齐；默认 8 = 比内容再往右一点（贴着切角标记的外侧，看着更"入框"）。
+ */
+export declare function titleInsetOf(part: any): number;
+/**
+ * 标题相对**面板上沿**的偏移（px）：正值往上（骑在框线上），0 = 与上沿齐平，负值往下（进入面板内）。
+ * 默认 0：胶囊标题贴着面板上沿放在框内 —— 骑在框线上（11）会正好压住左上角的四角切角装饰。
+ */
+export declare function titleOffsetOf(part: any): number;
+/**
+ * 标题要占用的"面板内高度"（内容区顶部要额外让出的空间）。
+ *  - bar  样式：整条标题栏，恒定 34px；
+ *  - chip 样式：标题底边 = 20 - 偏移，内容从 padding 开始 ⇒ 让位 = max(0, 20 - 偏移 - padding)。
+ *    默认（偏移 0、padding 10）时让 10px，标题正好在内容上方不打架；
+ *    偏移 ≥ padding 差（老看板的 11）时让位为 0 ⇒ **老看板布局一字不变**。
+ */
+export declare function titleReserveOf(part: any): number;
+/** 兼容旧调用（bar 样式之外返回 0 的老语义已被 titleReserveOf 取代） */
+export declare function titleBarHeightOf(part: any): 0 | 34;
+/** 容器内框宽度 = 盒子宽 - 边框 - 内边距（与 PartRenderer 里 .part-children 的 padding 一致） */
+export declare function innerWidthFromBox(boxWidth: any, part: any): number;
+/**
+ * 容器内框宽度（按 part.w 估算）。
+ * ⚠️ 只对"自由布局里的容器"准确：栅格模式（或本身是别的容器的子级）时，
+ * 容器的实际宽度由栅格决定，part.w 是陈旧值（实测 300 vs 真实 775，算出的列宽差 240 倍）。
+ * 那种场景必须用 DOM 实测宽度调 innerWidthFromBox()，别用这个函数。
+ */
+export declare function containerInnerWidth(part: any): number;
+/**
+ * 把部件挂到某个容器下 / 提到顶层，并做防环把关。
+ * 多层嵌套与"容器放进容器"都是允许的（只有成环不行）。
+ * 返回 { ok, reason }；不改数组顺序（顺序由调用方按深度优先维护）。
+ */
+export declare function canReparent(parts: any, id: any, parentId: any): {
+    ok: boolean;
+    reason: string;
+    parent?: undefined;
+} | {
+    ok: boolean;
+    reason?: undefined;
+    parent?: undefined;
+} | {
+    ok: boolean;
+    parent: any;
+    reason?: undefined;
+};
+/**
+ * 把 parts 重排成"深度优先"顺序：容器后面紧跟它的子级。
+ * 老配置（全顶层）跑完顺序不变。
+ */
+export declare function reorderDepthFirst(parts: any): any[];
+/**
+ * 清洗配置：修好悬空 parentId、非法容器类型、多层嵌套（都提升为顶层），再按深度优先重排。
+ * 原则是"修"而不是"报错" —— 只有整份配置解析不了才该报错。
+ * 返回 { parts, fixed: [...] }，fixed 里是改过什么，便于日志/提示。
+ */
+export declare function normalizeParts(parts: any): {
+    parts: any[];
+    fixed: any[];
+};
+export declare const GRID_DEFAULTS: {
+    cols: number;
+    rowHeight: number;
+    gap: number;
+};
+/** 自由布局 → 栅格：按 x/w 反推列起与跨列，按 h 反推跨行 */
+export declare function freeToGrid(part: any, page: any): {
+    col: number;
+    colSpan: number;
+    rowSpan: number;
+};
+/**
+ * 栅格 → 自由：**整页**批量换算（切回 free 时用这个，别逐件按 z/下标铺 y）。
+ *
+ * 为什么不能逐件算 y 然后按数组下标堆叠：栅格里同一"行带"的部件跨行数往往远大于
+ * 行距（一行 4 个 KPI 各跨 2 行、旁边图表跨 5 行），按下标 × 行距 铺开必然互相压住
+ * —— 实测切回自由布局后出现 5 处重叠。
+ *
+ * 正确做法是复现栅格的"行带"（band）：按流式顺序扫描，列号回绕就另起一带，
+ * 带高取该带内最大跨行，带内部件顶对齐、各自保留真实宽高。既保住 2D 排布又不重叠。
+ */
+export declare function gridToFreeParts(parts: any, page: any): any;
+/** 栅格模式的行高取值：固定行高，或随内容自动增长（设计器与运行时共用，保证一致） */
+export declare function gridAutoRows(page: any): string;
+/** 容器内框的列宽（注意容器是 n-1 个 gap，与整页画布的 gap*(n+1) 不同） */
+export declare function containerColWidth(page: any, innerW: any): number;
+/**
+ * 容器子级：子栅格 → 绝对定位（按行带铺开，不重叠）。
+ * @param pad 容器自身的 padding（默认 CONTAINER_PAD；自由子级的坐标原点含这段内边距，见文件头说明）
+ */
+export declare function containerGridToFree(children: any, page: any, innerW: any, pad: any): any;
+/** 容器子级：绝对定位 → 子栅格（按 x/y 反推列与跨列跨行） */
+export declare function containerFreeToGrid(children: any, page: any, innerW: any, pad: any): any;
+/**
+ * 一个像素盒 → 容器子栅格的 col/colSpan/rowSpan。
+ * 与 freeToGrid 的区别：容器是 n-1 个列间 gap、且内框已扣掉 padding，
+ * 所以列宽公式是 (innerW - gap*(n-1))/n（freeToGrid 用的是整页画布的 gap*(n+1)）。
+ */
+export declare function freeToContainerGrid(box: any, page: any, innerW: any, pad: any): {
+    col: number;
+    colSpan: number;
+    rowSpan: number;
+};
+/**
+ * 把某一层（同一个 parentId）的部件按"先上后下、再先左后右"重排。
+ * 栅格的行由数组顺序决定，所以从自由定位切到子栅格前必须做这一步。
+ * 直接改扁平数组里这些兄弟占用的槽位，各自的子树跟着走；调用方随后跑 reorderDepthFirst。
+ */
+export declare function sortSiblingsByVisual(parts: any, parentId: any): any;
+/** 栅格的"跨列/跨行"换算成页面像素宽高（把部件从容器里拖到自由布局顶层时用） */
+export declare function gridSpanToSize(part: any, page: any): {
+    w: number;
+    h: number;
+};
+/** 栅格模式下部件的 CSS（grid-column / grid-row + 样式） */
+export declare function gridPartStyle(part: any, page: any): any;
+/** 部件样式的内联 style（设计器与运行时共用，保证"所见即所得"） */
+/**
+ * 部件的**定位盒**样式（写到 `.part` 这个外层盒子上的内联 style）。
+ *
+ * ⚠️ 这里**只放几何/层级/透明度/旋转**，不放任何"外观"（底色/描边/圆角/投影）。
+ * 规范（2026-09 用户）："part view-part 的背景色…我看是写在 style 里的" ⇒
+ * 外层 `.part`（运行时的 `.part.view-part`）的内联 style 里**不应该出现 background**；
+ * 面板外观由内层的**面板层**（`.part-body`，见 {@link partVisualStyle}）负责。
+ * 好处：外层只当"框"，想换面板画法（内缩、加内衬、贴图、发光层）都不用动定位逻辑。
+ */
+export declare function partStyle(part: any): any;
+/**
+ * 部件的**面板外观**样式（底色/圆角/描边/投影），写到内层面板 `.part-body` 上。
+ *
+ * 【为什么单独一个函数】① 外层 `.part` 只负责"框在哪、多大"；② 底色归属有规范：
+ * **只有布局部件（容器）才画底色**，内容部件一律透明 —— 所以非容器**忽略** style.bg
+ * （老看板配置里固化的那层卡片渐变不会再画出来；保存时也会被 stripPartDefaults 洗掉）。
+ */
+export declare function partVisualStyle(part: any): any;
+/** 部件文本样式 */
+export declare function textStyle(part: any, theme: any): {
+    fontFamily: any;
+    fontSize: string;
+    fontWeight: string;
+    fontStyle: string;
+    color: any;
+    textAlign: any;
+};
+/** 窄屏判定阈值（与 CSS 媒体查询里那档保持一致） */
+export declare const MOBILE_MAX_WIDTH = 768;
+/** 页面配置里的移动端模式（缺省 auto，老配置不加字段也能受益） */
+export declare function mobileModeOf(page: any): any;
+/**
+ * 当前是否"堆叠单列"。
+ * @param {object} page 页面配置
+ * @param {number} viewportWidth 视口宽度（px）
+ */
+export declare function isMobileStack(page: any, viewportWidth: any): boolean;
+/** 窄屏堆叠时该类型的最小高度（大屏上的矮部件在手机上会挤成一团） */
+export declare function stackMinHeight(type: any): number;
+export declare function stackPartStyle(part: any, childCount: any): any;
+/** 按视觉顺序（先上后下、再先左后右）排一份副本；堆叠显示时用，不改动配置里的数组顺序 */
+export declare function visualOrder(list: any): any[];

package/dist/types/board-engine/theme-manifest.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 主题清单的**纯解析**（`{themeBaseUrl}/index.json`）。
+ *
+ * 注意分工：
+ * - 本文件只做「清单 → 结构化」的纯函数（可单测、可在 node 里跑）；
+ * - **读 CSS / 插 `<link>` / 读计算样式** 属于 DOM 操作，放在运行端 `board/theme-host.ts`，
+ *   base url 由宿主注入（引擎层不许碰 window，见 `scripts/assert-board-engine.mjs`）。
+ *
+ * 清单只服务"设计器里的主题下拉"：运行端根本不需要它 —— 配置里写的就是主题 code，
+ * 直接按 `{themeBaseUrl}/{code}.css` 取即可。
+ */
+export interface BoardThemeEntry {
+    code: string;
+    name: string;
+    /** 文件名（缺省 = `<code>.css`） */
+    file: string;
+}
+/**
+ * 容错口径（沿用 design-ui，勿改）：非数组 → 空；没有 code 的条目丢掉；
+ * 重复 code 只留第一个；没写 file 就按约定用 `<code>.css`
+ * （这样加一个主题 = 一个 css + 一行清单）。
+ */
+export declare function parseManifest(raw: unknown): BoardThemeEntry[];