ice-entity-designer 0.0.22 → 0.0.24

package/README.md

@@ -205,6 +205,7 @@ flow.undo(); // 100 步历史
 | 样式 | 节点：`fillColor` / `strokeColor` / `textColor` / `fontSize`（`updateNode` 即时生效）；连线：`style.strokeStyle`（线色，同时作为箭头填充）/ `style.lineWidth`、`labelStyle.fillStyle`（标签颜色），全部随快照存取 |
 | 增删改查 | `nodes` / `edges` / `selected` / `select()` / `updateNode()` / `updateEdge()` / `remove()`（删节点级联删连线）/ `clear()` |
 | 历史与快照 | `undo()` / `redo()` / `canUndo()` / `canRedo()`、`serialize()` / `toSnapshot()` / `load()`（返回 `{ loaded, nodes, edges, skipped }`）。文档 **v2 直接复用引擎的序列化机制**：`{ version: 2, kind: 'flowchart', scene: <引擎 Serializer 产物> }`，因此自定义 `data` 与任何新增 state 字段自动往返；v1（`nodes`/`edges` 数组）仍可读，导出统一为 v2 |
+| 导出 | `toSvg(options)` —— 导出**矢量** SVG（放大不糊、可进设计工具/打印）；与画布同一口径 |
 | 视图与订阅 | `fitViewport(padding)`、`subscribe()`、`dispose()` |
 
 自定义形状（判定菱形 / 输入输出平行四边形）在 `src/flow/flow_shapes.ts`，走的是引擎的 `ICEPath` 子类机制。
@@ -252,6 +253,67 @@ const report = fromBpmnXml(xml, bpmn); // 导入并重建（含池 / 泳道容
 BPMN 节点同样是**复合组件**（形状 + 角标 + 标记由 state 派生），内部子组件不写进文档、载入时重建。
 AI Agent 生成 BPMN 的 JSON DSL（`kind: 'bpmn'`）见 `ice-entity-designer-dsl`。
 
+#### 5.4 导出：矢量 SVG（与画布同一口径）
+
+画布的 `toDataURL()` 是**光栅快照**（分辨率写死、放大就糊）。需要出图给文档、打印或设计工具时用
+**矢量导出** —— 它复用引擎的 `exportSvg()`，从组件树 + 路径命令流重新生成 SVG，与画布逐像素同一口径
+（绘制顺序、世界矩阵、样式合并、透明度、祖先裁剪、虚线、渐变、阴影、连线标签）：
+
+```js
+// 流程图 / BPMN（应用层，FlowDesigner 与 BpmnDesigner 都有）
+const svg = designer.toSvg();                                   // 内容自适应 + 透明背景
+const svg = designer.toSvg({ background: '#ffffff', padding: 16 });
+const svg = designer.toSvg({ area: 'viewport' });               // 当前视口所见即所导
+
+// 任何场景（ER / 流程图 / BPMN 都能用，含 `{ svg, width, height }` 版本）
+const svg = IED.exportSvg(ice, { scale: 2 });
+const { svg, width, height } = IED.exportSvgResult(ice, { padding: 12 });
+```
+
+`tests/bpmn-editor.html` 与 `tests/flowchart-editor.html` 上都有「导出 SVG」按钮，点一下即可下载
+（BPMN 案例导出的池/泳道/事件/网关/连线/标签都是矢量）。服务端出图见引擎的 `ICE.headless()`。
+
+限制（与引擎一致）：阴影用 `feDropShadow` 近似（模糊观感不会与画布逐像素相同）；SVG 与 canvas 的
+字形栅格化是两套实现，文字位置**对齐口径一致、逐像素允许微差**；导出的是**静态瞬间**（蚂蚁线动画
+只保留当前相位）。
+
+#### 5.5 UML 类图（域包示例）
+
+UML 是**域包（domain pack）**的第一个完整示例：形状 + 应用层 + 语义校验，其余（选择/增删改/连线/
+撤销重做/快照/适应视图/矢量导出）全部沿用引擎与 `FlowDesigner`。
+
+```js
+import { ICE, UmlDesigner } from 'ice-entity-designer';
+
+const ice = new ICE().init('canvas-1');
+const uml = new UmlDesigner(ice);
+
+const entity = uml.createClass({ kind: 'class', className: 'Entity', abstract: true, methods: ['+ save(): void'] });
+const user = uml.createClass({ className: 'User', attributes: ['- email: string'], methods: ['+ placeOrder(): Order'] });
+const payable = uml.createClass({ kind: 'interface', className: 'Payable', methods: ['+ pay(amount: number): void'] });
+
+uml.createRelation({ sourceId: user.state.id, targetId: entity.state.id, relationKind: 'inheritance' });
+uml.createRelation({ sourceId: payable.state.id, targetId: user.state.id, relationKind: 'realization' });
+
+uml.validateUml();  // 重名类 / 悬空关系 / 继承成环
+const svg = uml.toSvg({ background: '#ffffff', padding: 16 });
+```
+
+| 记法 | 线型 + 端点标记 |
+|---|---|
+| `inheritance` 继承 | 实线 + 空心三角（指向父类） |
+| `realization` 实现 | 虚线 + 空心三角（指向接口） |
+| `association` 关联 | 实线 |
+| `aggregation` 聚合 | 实线 + **空心菱形**（整体一侧） |
+| `composition` 组合 | 实线 + **实心菱形**（整体一侧） |
+| `dependency` 依赖 | 虚线 + 开放箭头 |
+
+类框是**三段式**（类名 / 属性 / 方法）：成员是自由文本（`- id: string`、`+ pay(): void`），
+可见性/静态/泛型都由文本表达 —— 与 PlantUML/Mermaid 的通行写法一致，AI 生成不必学另一套结构化语法；
+接口与枚举带构造型，抽象类标 «abstract»；**框高随成员自动增长**，成员不会被画到框外。
+
+可运行示例：`tests/uml-editor.html`（电商支付的类模型：继承 / 实现 / 组合 / 关联 / 依赖）。
+
 ## 6. 在 React 中使用
 
 包内置 React 绑定（子路径导出 `ice-entity-designer/react`），不需要自己写 ref / effect 胶水代码。
@@ -394,6 +456,25 @@ React 里可沿用 `createFlowSession` 的模式自建一层封装。
 
 ## 7. 项目结构
 
+### 7.1 一个「域包（domain pack）」由什么组成
+
+域包 = **一个领域的记法 + 应用层 + 语义校验**，跑在同一套引擎与同一套应用层机制上。已落地的三个
+域（ER / 流程图 / BPMN）再加 UML，边际成本主要在「记法本身」，不在编辑器：
+
+| 组成 | 复用什么 | 以 UML 为例 |
+|---|---|---|
+| 形状 | 引擎的复合组件（`hasDerivedChildren`）：内部子组件按 state 派生、不进文档 | `UmlClass`：三段式类框 |
+| 连线 | 引擎折线（插槽吸附 / 正交·贝塞尔路由 / 标签 / 跟随宿主）；**端点标记进路径点集**，因此描边、填充、导出都自动带上 | `UmlRelation`：六种关系 = 线型 + 三角/菱形/开放箭头 |
+| 应用层 | `FlowDesigner`（选择 / 增删改 / 连线 / 撤销重做 / 快照 / 适应视图 / 订阅 / `toSvg`） | `UmlDesigner` 只重写「建什么图元 + 类型过滤」 |
+| 语义校验 | 结构校验之外的部分自写，规则直白 | `validateUml()`：重名类 / 悬空关系 / 继承成环 |
+| 文档格式 | 引擎序列化（typeId 注册表 + `hasDerivedChildren`），零登记 | 类与关系统统自动往返 |
+| 互操作 | 有标准格式的域就做（BPMN 2.0 XML 已有） | UML 的 XMI / PlantUML 互操作待补 |
+| 交付物 | 示例页 + e2e + README + （可选）JSON DSL 与技能 | `tests/uml-editor.html` + `e2e/uml-editor.spec.ts` |
+
+新开一个域包时，按这张表从上往下填即可；**不要**在域包里另造序列化、另造选择/历史、另造导出。
+
+### 7.2 目录一览
+
 ```
 src/
 ├── designer/EntityDesigner.ts     # 应用层：选择 / 增删改 / 连接 / 校验 / 历史 / 项目存取 / 变更订阅
@@ -402,6 +483,10 @@ src/
 │   ├── FlowNode.ts                # 节点：四类预设（起止 / 处理 / 判定 / 输入输出）+ 居中标题
 │   ├── FlowEdge.ts                # 连线：正交 / 贝塞尔 + 箭头 + 分支标签，插槽吸附
 │   └── FlowDesigner.ts            # 应用层：建节点/连线、选择、增删改、历史、快照存取、适应视图
+├── uml/                           # UML 类图（domain pack：三段式类框 + 六种关系 + 语义校验）
+│   ├── UmlClass.ts                # 复合组件：类名 / 属性 / 方法三段，构造型，框高随成员增长
+│   ├── UmlRelation.ts             # 六种关系 = 线型 + 端点标记（三角/菱形/开放箭头，标记进路径点集）
+│   └── UmlDesigner.ts             # FlowDesigner 薄扩展：建 UML 图元 + 类型过滤 + validateUml()
 ├── bpmn/                          # BPMN 2.0（FlowDesigner 之上的业务记法）
 │   ├── bpmn_shapes.ts             # 形状：事件圆 / 网关菱形 / 任务角标 / 子流程标记 / 数据对象 / 注释 / 池泳道
 │   ├── BpmnDesigner.ts            # 应用层：容器真嵌套（池→泳道→节点）、条件与默认流标记、语义校验