ice-entity-designer 0.4.2 → 0.5.0

package/dist/types/designer/highlight.d.ts

@@ -0,0 +1,57 @@
+/** 一条高亮目标：图元 id + 它的**全局**包围盒（世界坐标）。 */
+export type DesignerHighlightEntry = {
+    id: string;
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+export type DesignerHighlightOptions = {
+    /** 描边色，默认取引擎主题的 `semantic.primary`。 */
+    color?: string;
+    /** 描边宽度，默认 3。 */
+    lineWidth?: number;
+    /** 相对图元包围盒的外扩量，默认 4（描边不贴着图形边）。 */
+    padding?: number;
+    /** 圆角半径，默认 6。 */
+    radius?: number;
+    /** 底色。`false`（默认）表示只描边；给了颜色则画在图元**之上**（见文件抬头）。 */
+    fill?: string | false;
+};
+/**
+ * 高亮层：持有工具层里的一个 `ICERect` 集合，按调用方给的包围盒摆放。
+ *
+ * 由 `FlowDesigner` 持有并对外暴露（`setHighlights` / `highlight` / `clearHighlights`），
+ * 应用层不需要直接用它。
+ */
+export default class DesignerHighlightLayer {
+    private ice;
+    /** id → 工具层里的那块矩形。空表示当前没有高亮。 */
+    private boxes;
+    private options;
+    constructor(ice: any);
+    /** 当前高亮的 id（调用顺序）。 */
+    get ids(): string[];
+    /**
+     * 用一批目标替换当前高亮（先摆位置、再清理不再需要的）。
+     *
+     * 传空数组等价于 `clear()` —— 高亮层会整个从工具层摘掉，
+     * 不给引擎留一块空图层（`toolNodes` 里本来就有一堆引擎自己的工具，
+     * 多留一块看不出来的空图层只会让"数自己的层有没有泄漏"变得不可能）。
+     */
+    set(entries: DesignerHighlightEntry[], options?: DesignerHighlightOptions): void;
+    /** 清掉全部高亮。 */
+    clear(): void;
+    /** 新建或就地更新某个 id 的高亮框。 */
+    private __place;
+    private __remove;
+    /** 一块不剩时把整层摘掉（不留在 toolNodes 里）。 */
+    private __destroy;
+    /**
+     * 描边色：显式给了就用，否则取引擎主题的主色（换主题跟着走）。
+     *
+     * 兜底值取自引擎的 `DEFAULT_THEME`（**不写死色值** —— 本仓有"写死色值只许减"的预算棘轮，
+     * 而且引擎换品牌基线时这里要跟着动）。
+     */
+    private __color;
+}

package/dist/types/flow/FlowDesigner.d.mts

@@ -1,6 +1,7 @@
 import type { ICE, SvgExportOptions } from 'ice-render';
 import type { FlowNodeKind } from './FlowNode.mjs';
 import type { FlowPort } from './FlowEdge.mjs';
+import type { DesignerHighlightOptions } from '../designer/highlight.mjs';
 /**
  * 流程图文档。
  *
@@ -58,6 +59,15 @@ export default class FlowDesigner {
     /** 画布拖拽节点时会话：BEFORE_MOVE 记一次历史，mouseup 结束会话 */
     private __moveSession;
     private __moveEmitQueued;
+    /**
+     * 程序化高亮层（见 `designer/highlight.ts`）。
+     *
+     * 它是**视图状态**：不进快照、不参与命中。图元在容器里（BPMN 池 / 泳道）也画得出来，
+     * 因为高亮框落在工具层。
+     */
+    private __highlight;
+    /** 上一次用过的样式，图元移动后重新摆位时要沿用同一份。 */
+    private __highlightOptions;
     /**
      * 节点在画布上被拖动（引擎 `setPosition()` → BEFORE_MOVE/AFTER_MOVE）。
      *
@@ -79,6 +89,41 @@ export default class FlowDesigner {
      */
     protected __flatten(): any[];
     get selected(): any;
+    /**
+     * **程序化高亮**：高亮一组图元（给"指着讲"/教程/演示用）。
+     *
+     * 为什么要有这个入口：设计器原先**没有任何"高亮某个图元"的公开手段** ——
+     * `ice.setSelection()` 只写选中集合（a11y / 插件读，不画）、`designer.select()` 只写字段、
+     * `chrome.selection` 只被"按 mousedown 弹出来"的控制面板消费。应用层只能自己给图元打
+     * style 补丁再手动置脏来模拟，既依赖组件内部实现，也要在图元改动时自己对表。
+     *
+     * 契约（三条都是"不这样就会被静默坑到"的）：
+     * - 高亮是**视图状态**：`serialize()` 里不会多出任何东西，载入快照也不会带回来；
+     * - 高亮框**不参与命中测试**，图元自己的交互、连线端点手柄照常（否则高亮会挡住被高亮的东西）；
+     * - 图元移动 / 增删后高亮框**自动跟随**（拖拽走 `AFTER_MOVE`，文档变更走 `__emitChange`）；
+     *   高亮中的图元被删掉，它的框也跟着消失。
+     *
+     * ```ts
+     * designer.highlight('pump-2');                        // 只高亮一个
+     * designer.setHighlights(['a', 'b', 'c']);             // 高亮一组
+     * designer.setHighlights(ids, { color: '#FFD400', fill: 'rgba(255,212,0,0.18)' });
+     * designer.clearHighlights();
+     * ```
+     *
+     * @param ids 图元 id 或位号（各域包自行把业务标识写进 `state.id`）；`null` 等价于清除
+     * @returns 真正落地的数量 —— 认不出的 id 会被忽略（不抛错：agent 给的标识经常对不上）
+     */
+    setHighlights(ids: string[] | string | null, options?: DesignerHighlightOptions): number;
+    /** 只高亮一个图元（先清掉其余的）；认不出这个 id 时返回 false，且**不动**现有高亮。 */
+    highlight(id: string | null, options?: DesignerHighlightOptions): boolean;
+    /** 清掉全部高亮。 */
+    clearHighlights(): void;
+    /** 当前高亮的图元 id。 */
+    getHighlightedIds(): string[];
+    /** 图元 id（或位号 `state.tag`）→ 高亮目标（全局包围盒）。 */
+    private __highlightEntry;
+    /** 图元动了 / 文档变了之后，把已高亮的那几只框重新摆到当前位置。 */
+    private __syncHighlights;
     /**
      * 订阅流程变更（增删改 / 连线 / 载入 / undo / redo 之后触发）。
      * 回调参数是当前流程的快照（与 serialize() 一致）。
@@ -104,7 +149,18 @@ export default class FlowDesigner {
     createEdge(props?: any): any;
     updateNode(id: string, patch: Record<string, any>): any;
     updateEdge(id: string, patch: Record<string, any>): any;
-    /** 删除节点（连带删除挂在它两端的连线）或删除一条连线 */
+    /**
+     * 删除节点（连带删除挂在它两端的连线）或删除一条连线。
+     *
+     * ⚠️ 级联只覆盖**引擎里那棵树**：挂在被删节点两端的连线会一起删掉，所以**画布**是干净的。
+     * 但宿主若另有一份"图的可序列化文档"（本设计器的 `state.diagram`、外部项目文件、
+     * 服务端那份副本），那份**不会跟着变** —— 设计器不知道外面还有几份副本，也不该去猜。
+     *
+     * 两份东西怎么同步是**宿主的责任**：要么在调 `remove()` 之前把外部文档里
+     * 相关的连线一起列出来删（本仓 `scenarios.ts` 的 `pipesTouching` 就是这么做的），
+     * 要么删完之后重新读一次引擎树再落盘 —— 但**不要**指望渲染层的级联副作用去补文档：
+     * `state` 的读者不止渲染层（模型下一轮会读它、`STATE_SNAPSHOT` 会重放它）。
+     */
     remove(id: string): void;
     clear(): void;
     serialize(): string;
@@ -141,8 +197,29 @@ export default class FlowDesigner {
      * 所以甘特把它改成 `start`（贴顶留白）。
      */
     protected fitViewportAlign: 'center' | 'start';
-    /** 把整个流程缩放到画布可视区内 */
+    /**
+     * 把整个流程缩放到画布可视区内。
+     *
+     * ⚠️ 视口尺寸取的是 **CSS 尺寸**，不是 `canvasWidth/canvasHeight` ——
+     * 后者是 **backing store** 尺寸（= css × dpr），而渲染视口还会再乘一次 dpr，
+     * 直接拿它算 scale 等于**多乘一次**：dpr = 2 时内容画成两倍大并被裁掉，
+     * 且**不报错**（普通屏完全正常，只在 retina 上复发）。见 `__viewportSize()`。
+     */
     fitViewport(padding?: number): void;
+    /**
+     * 取景用的视口尺寸（**CSS 像素**）。
+     *
+     * 两级口径，都对齐"渲染视口 = dpr · viewport"这条约定：
+     * ① 首选引擎的输入矩形（`getInputRect()`）—— 它是**内容盒**，与命中测试 / 坐标换算
+     *    同一口径，dpr 变化时它的数值不变；
+     * ② 没有布局信息的运行时（测试桩 / 小程序）退回 `canvasWidth / dpr`。
+     *
+     * 千万不要退回 `canvasWidth` 本身 —— 那正是这条 dpr 缺陷的来源。
+     */
+    protected __viewportSize(): {
+        width: number;
+        height: number;
+    };
     canUndo(): boolean;
     /**
      * 把当前流程图导出为 **SVG 矢量图**（打印、进设计工具、服务端出图都走它）。

package/dist/types/flow/FlowDesigner.d.ts

@@ -1,6 +1,7 @@
 import type { ICE, SvgExportOptions } from 'ice-render';
 import type { FlowNodeKind } from './FlowNode';
 import type { FlowPort } from './FlowEdge';
+import type { DesignerHighlightOptions } from '../designer/highlight';
 /**
  * 流程图文档。
  *
@@ -58,6 +59,15 @@ export default class FlowDesigner {
     /** 画布拖拽节点时会话：BEFORE_MOVE 记一次历史，mouseup 结束会话 */
     private __moveSession;
     private __moveEmitQueued;
+    /**
+     * 程序化高亮层（见 `designer/highlight.ts`）。
+     *
+     * 它是**视图状态**：不进快照、不参与命中。图元在容器里（BPMN 池 / 泳道）也画得出来，
+     * 因为高亮框落在工具层。
+     */
+    private __highlight;
+    /** 上一次用过的样式，图元移动后重新摆位时要沿用同一份。 */
+    private __highlightOptions;
     /**
      * 节点在画布上被拖动（引擎 `setPosition()` → BEFORE_MOVE/AFTER_MOVE）。
      *
@@ -79,6 +89,41 @@ export default class FlowDesigner {
      */
     protected __flatten(): any[];
     get selected(): any;
+    /**
+     * **程序化高亮**：高亮一组图元（给"指着讲"/教程/演示用）。
+     *
+     * 为什么要有这个入口：设计器原先**没有任何"高亮某个图元"的公开手段** ——
+     * `ice.setSelection()` 只写选中集合（a11y / 插件读，不画）、`designer.select()` 只写字段、
+     * `chrome.selection` 只被"按 mousedown 弹出来"的控制面板消费。应用层只能自己给图元打
+     * style 补丁再手动置脏来模拟，既依赖组件内部实现，也要在图元改动时自己对表。
+     *
+     * 契约（三条都是"不这样就会被静默坑到"的）：
+     * - 高亮是**视图状态**：`serialize()` 里不会多出任何东西，载入快照也不会带回来；
+     * - 高亮框**不参与命中测试**，图元自己的交互、连线端点手柄照常（否则高亮会挡住被高亮的东西）；
+     * - 图元移动 / 增删后高亮框**自动跟随**（拖拽走 `AFTER_MOVE`，文档变更走 `__emitChange`）；
+     *   高亮中的图元被删掉，它的框也跟着消失。
+     *
+     * ```ts
+     * designer.highlight('pump-2');                        // 只高亮一个
+     * designer.setHighlights(['a', 'b', 'c']);             // 高亮一组
+     * designer.setHighlights(ids, { color: '#FFD400', fill: 'rgba(255,212,0,0.18)' });
+     * designer.clearHighlights();
+     * ```
+     *
+     * @param ids 图元 id 或位号（各域包自行把业务标识写进 `state.id`）；`null` 等价于清除
+     * @returns 真正落地的数量 —— 认不出的 id 会被忽略（不抛错：agent 给的标识经常对不上）
+     */
+    setHighlights(ids: string[] | string | null, options?: DesignerHighlightOptions): number;
+    /** 只高亮一个图元（先清掉其余的）；认不出这个 id 时返回 false，且**不动**现有高亮。 */
+    highlight(id: string | null, options?: DesignerHighlightOptions): boolean;
+    /** 清掉全部高亮。 */
+    clearHighlights(): void;
+    /** 当前高亮的图元 id。 */
+    getHighlightedIds(): string[];
+    /** 图元 id（或位号 `state.tag`）→ 高亮目标（全局包围盒）。 */
+    private __highlightEntry;
+    /** 图元动了 / 文档变了之后，把已高亮的那几只框重新摆到当前位置。 */
+    private __syncHighlights;
     /**
      * 订阅流程变更（增删改 / 连线 / 载入 / undo / redo 之后触发）。
      * 回调参数是当前流程的快照（与 serialize() 一致）。
@@ -104,7 +149,18 @@ export default class FlowDesigner {
     createEdge(props?: any): any;
     updateNode(id: string, patch: Record<string, any>): any;
     updateEdge(id: string, patch: Record<string, any>): any;
-    /** 删除节点（连带删除挂在它两端的连线）或删除一条连线 */
+    /**
+     * 删除节点（连带删除挂在它两端的连线）或删除一条连线。
+     *
+     * ⚠️ 级联只覆盖**引擎里那棵树**：挂在被删节点两端的连线会一起删掉，所以**画布**是干净的。
+     * 但宿主若另有一份"图的可序列化文档"（本设计器的 `state.diagram`、外部项目文件、
+     * 服务端那份副本），那份**不会跟着变** —— 设计器不知道外面还有几份副本，也不该去猜。
+     *
+     * 两份东西怎么同步是**宿主的责任**：要么在调 `remove()` 之前把外部文档里
+     * 相关的连线一起列出来删（本仓 `scenarios.ts` 的 `pipesTouching` 就是这么做的），
+     * 要么删完之后重新读一次引擎树再落盘 —— 但**不要**指望渲染层的级联副作用去补文档：
+     * `state` 的读者不止渲染层（模型下一轮会读它、`STATE_SNAPSHOT` 会重放它）。
+     */
     remove(id: string): void;
     clear(): void;
     serialize(): string;
@@ -141,8 +197,29 @@ export default class FlowDesigner {
      * 所以甘特把它改成 `start`（贴顶留白）。
      */
     protected fitViewportAlign: 'center' | 'start';
-    /** 把整个流程缩放到画布可视区内 */
+    /**
+     * 把整个流程缩放到画布可视区内。
+     *
+     * ⚠️ 视口尺寸取的是 **CSS 尺寸**，不是 `canvasWidth/canvasHeight` ——
+     * 后者是 **backing store** 尺寸（= css × dpr），而渲染视口还会再乘一次 dpr，
+     * 直接拿它算 scale 等于**多乘一次**：dpr = 2 时内容画成两倍大并被裁掉，
+     * 且**不报错**（普通屏完全正常，只在 retina 上复发）。见 `__viewportSize()`。
+     */
     fitViewport(padding?: number): void;
+    /**
+     * 取景用的视口尺寸（**CSS 像素**）。
+     *
+     * 两级口径，都对齐"渲染视口 = dpr · viewport"这条约定：
+     * ① 首选引擎的输入矩形（`getInputRect()`）—— 它是**内容盒**，与命中测试 / 坐标换算
+     *    同一口径，dpr 变化时它的数值不变；
+     * ② 没有布局信息的运行时（测试桩 / 小程序）退回 `canvasWidth / dpr`。
+     *
+     * 千万不要退回 `canvasWidth` 本身 —— 那正是这条 dpr 缺陷的来源。
+     */
+    protected __viewportSize(): {
+        width: number;
+        height: number;
+    };
     canUndo(): boolean;
     /**
      * 把当前流程图导出为 **SVG 矢量图**（打印、进设计工具、服务端出图都走它）。

package/dist/types/theme/designerTheme.d.mts

@@ -39,6 +39,8 @@ export declare function designerChromeFromTheme(theme?: ICETheme | null): Partia
  * 调用位置：`BaseDesigner` 的构造里（所有编辑器子类都会走），所以无论应用层是直接
  * `new ICE()` 还是走 React 的 `createDesignerSession()`，外壳都是同一套。
  *
- * 宿主换过主题（`ice.setTheme(...)` / `ice.setChrome(...)`）之后再调一次即可重新对齐。
+ * 引擎 2.14 起写的是**命名补丁**（`ice.setThemePatch('ice-designer', …)`），并且本函数会订阅
+ * `ice.onThemeChange`：宿主换主题（基座变了）之后**自动重算**一次外壳，不需要调用方再调一遍。
+ * 老引擎（<2.14）退回 `ice.setChrome()`，行为与之前一致。
  */
 export declare function applyDesignerChrome(ice: any): any;

package/dist/types/theme/designerTheme.d.ts

@@ -39,6 +39,8 @@ export declare function designerChromeFromTheme(theme?: ICETheme | null): Partia
  * 调用位置：`BaseDesigner` 的构造里（所有编辑器子类都会走），所以无论应用层是直接
  * `new ICE()` 还是走 React 的 `createDesignerSession()`，外壳都是同一套。
  *
- * 宿主换过主题（`ice.setTheme(...)` / `ice.setChrome(...)`）之后再调一次即可重新对齐。
+ * 引擎 2.14 起写的是**命名补丁**（`ice.setThemePatch('ice-designer', …)`），并且本函数会订阅
+ * `ice.onThemeChange`：宿主换主题（基座变了）之后**自动重算**一次外壳，不需要调用方再调一遍。
+ * 老引擎（<2.14）退回 `ice.setChrome()`，行为与之前一致。
  */
 export declare function applyDesignerChrome(ice: any): any;

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-entity-designer",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "An entity designer based on ice-render.",
   "repository": {
     "type": "git",
@@ -59,7 +59,7 @@
     "types:watch": "npm run types:check -- --watch"
   },
   "peerDependencies": {
-    "ice-render": "^2.10.0",
+    "ice-render": "^2.14.1",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },
@@ -101,7 +101,7 @@
     "eslint-plugin-react-hooks": "4.6.0",
     "http-server": "14.1.1",
     "husky": "8.0.3",
-    "ice-render": "^2.11.2",
+    "ice-render": "^2.14.1",
     "jest": "29.7.0",
     "jest-environment-jsdom": "29.7.0",
     "lint-staged": "15.5.2",