@logicflow/core 2.2.1 → 2.2.3

package/dist/docs/tutorial/update.en.md

@@ -0,0 +1,213 @@
+---
+nav: 指南
+group:
+  title: 介绍
+  order: 0
+title: 升级到 2.0 版本
+order: 7
+toc: content
+---
+In the `2.0` version, we optimized multiple modules of project infrastructure, core functions, and plug-ins, and fixed a series of problems. There are several main areas that need to be adjusted:
+1. The CDN import path needs to be changed:
+```html | pure
+<!-- Original import path -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/logic-flow.js"></script>
+<link href="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/style/index.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/Menu.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/style/index.css" />
+
+<!-- Current import path -->
+<!-- When importing the old version, you need to add the version number after the package name and use the old path -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/core@1.2.27/dist/logic-flow.js"></script>
+<link href="https://cdn.jsdelivr.net/npm/@logicflow/core@1.2.27/dist/style/index.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension@1.2.27/lib/Menu.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension@1.2.27/lib/style/index.css" />
+<!-- If you want to directly import the latest version of 2.0, just copy the following code -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/index.min.js"></script>
+<link href="https://cdn.jsdelivr.net/npm/@logicflow/core/lib/style/index.min.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/dist/index.min.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/style/index.min.css" />
+
+```
+2. The style path of the LogicFlow core package needs to be changed when importing it through the package manager:
+```js
+
+// 1.x version import method
+import "@logicflow/core/dist/style/index.css";
+// How to import version 2.0
+import "@logicflow/core/lib/style/index.css";
+
+```
+
+1. The options of each plugin passed in by the pluginOptions parameter need to be separated according to the plugin name
+```js
+// Here, we take the configuration item showEdge to set whether the minimap displays the connection as an example
+// 1.x version
+new LogicFlow({
+pluginsOptions: {
+showEdge, // MiniMap can be displayed normally
+},
+})
+// 2.0 version
+new LogicFlow({
+pluginsOptions: {
+showEdge, // ❌MiniMap cannot be displayed normally
+MiniMap: {
+showEdge,// ✅MiniMap can be displayed normally
+},
+},
+})
+```
+Other changes theoretically have no impact on usage. Here is a list of changes:
+
+### Project infrastructure
+**Optimization**
+1. Supplement the type definitions of all components and methods in the project;
+2. preact -> preact/compat in the core package;
+3. Remove jest dependencies in dependencies, lodash -> lodash-es
+4. Improve README.md and CONTRIBUTING related documents;
+
+### Core
+
+#### Node
+**New capabilities**
+1. Added `node:resize`, `node:rotate` and `node:properties-change` events
+
+**Optimization**
+1. Shape component refactoring, some methods renamed
+1. `formateAnchorConnectValidateData` -> `formatAnchorConnectValidateData`;
+2. `setHoverON` -> `setHoverOn`;
+3. `setHoverOFF` -> `setHoverOff`;
+2. Remove the setting of y: y-1 under rectAttr in TextNode getBackground;
+3. fakerNode renamed to fakeNode;
+
+4. Node text style supports configuration through `properties.textStyle`
+
+**Bug fix**
+
+1. Solve the problem of abnormal polygon shape and border positioning by setting the origin in points and scaling based on the set width and height;
+
+#### Edge
+**New capabilities**
+
+1. Added adjustEdgeStart and adjustEdgeEnd, which can adjust the start point or end point separately;
+
+2. Edge text style supports configuration through `properties.textStyle`;
+
+**Bug fix**
+
+1. Fix the bug that graphModel.edgeType (default edge type) is not used to initialize the edge when the type in edgeConfig is not passed during initialization
+
+#### Grid
+**Optimization**
+
+1. The Grid class implements the initialization of grid configuration options by itself
+
+2. Modify the maximum radius calculation logic of the point in the dot grid and add relevant comments
+
+**Bug fix**
+
+1. Correct the problem of offset in the original grid
+
+2. Corrected the type declaration of grid configuration options
+
+#### Graph
+**Optimization**
+1. Optimized the logic of setting the canvas size during initialization: when adjusting the window, the canvas size can be updated synchronously;
+2. "Breaking Change" adjusted pluginOptions to only pass in the options data corresponding to the plugin (previously all data was passed in)
+
+**Bug fixes**
+1. Fixed the problem that the canvas cannot scroll when stopMoveGraph:true is set but stopScrollGraph:true is not set;
+2. Fixed the bug of the getAreaElement method in GraphModel;
+
+#### Tool
+**bigfix**
+Fixed the bug that TextEditTool is invalid, and the reason is noted later
+- When the TextEditTool component is updated, the original graphModel and LogicFlow props will not trigger the component update. The component update is triggered by passing in textEditElement
+- Removed the useless console in the code
+- Updated the dependency @babel/plugin-proposal-class-properties -> @babel/plugin-transform-class-properties
+- EventArgs related types are changed from unknown Changed to any
+
+### Extension
+
+#### Box selection plug-in
+**New capabilities**
+1. Add `selection:selected-area` event to return the box selection range;
+2. The default enabled state of the box selection plug-in is changed to disabled. If you need to enable the box selection during initialization, call the `lf.extension.selectionSelect.open()` method to enable the box selection after the LogicFlow instance is created;
+**Bug fixes**
+1. Fix the problem that the page scrolling event is blocked after the box selection is enabled;
+2. Fix the problem of calculating the box selection margin and outer border width after zooming;
+
+#### Minimap plug-in
+**New capabilities**
+1. Support configuration of the minimap display position;
+2. Support the selection of whether to render the connection, support setting during initialization or updating the setting through the `setShowEdge` method;
+3. Optimize the display content of the minimap. Currently, the canvas element and the viewport position will jointly determine the display content;
+4. Optimize the drag interaction experience of the minimap preview;
+5. Added the callback event `miniMap:close` for closing the minimap;
+**Problem fix**
+1. Optimized the update strategy of the minimap when the canvas moves to reduce performance consumption;
+2. Fixed the problem that clicking the minimap preview window triggers unexpected canvas movement;
+3. Fixed the problem that the minimap preview window cannot be dragged;
+
+#### NodeResize plug-in
+**Optimization**
+In version 1.x, the node scaling capability needs to be implemented by introducing the NodeResize plug-in. In version 2.0, we built the resize capability into the basic node; and also supported the configurable node rotation capability.
+1. Users can set whether all nodes in the current instance are scalable and rotatable through the global configuration items `allowResize` and `allowRotate`;
+2. You can also add `resizable` and `rotatable` parameters in the `properties` of the initial rendering incoming data to control whether a single node is rotatable and scalable(This will only take effect if `allowResize`/`allowRotate` is set to true globally.). Internally, the node's `resizable` and `rotatable` default to `true`;
+
+:::warning{title=Tip}
+After the scaling capability is built-in, the NodeResize plug-in will be gradually abandoned
+:::
+
+3. Unify the return values ​​of getResizeOutlineStyle fill and stroke in NodeResize;
+
+**Bug fix**
+1. Solve the problem of node repositioning after resize ends;
+2. Fix the bug that the outlineStyle fill of HtmlResize node defaults to black;
+
+#### Snapshot plug-in
+**Optimization**
+1. Optimize the export content of the bpmn plug-in;
+2. Support network images in the export node;
+3. Improve the snapshot usage, support custom export file name, file type, image width and height, background color, image quality and other attributes;
+
+**Bug fix**
+1. Fixed the problem of missing exported content after turning on local rendering;
+
+#### Group plugin
+In version 2.0, we rewrote the logic of the group plugin and upgraded the Group plugin to [Dynamic Group plugin](extension/dynamic-group.en.md)
+**New capabilities**
+1. Support the synchronous scaling and rotation of group nodes, and the internal elements will also scale and rotate synchronously;
+
+**Optimization**
+1. Reduce the range of ResizeControl 30 -> 15, because it will cover the small button of Group folding;
+
+2. Optimize the logic judgment of allowing text dragging -> nodeTextDraggable && draggable can only allow dragging;
+
+#### HighLight plugin
+**New capabilities**
+1. Support highlight neighbor node mode;
+2. Support external parameter configuration of highlight form;
+
+**Optimizations**
+1. Supplementary function introduction document [HighLight plugin](extension/highlight.en.md)
+
+#### 「New」Label plugin
+**New capabilities**
+In version 2.0, we added a new text display format: Label. The main differences between this format and the existing Text format are:
+1. Supports adding multiple texts to a node/edge, and can set the text direction;
+2. Comes with rich text editing capabilities, supports set local text style;
+3. Use the new position calculation algorithm to optimize the mobile experience of associated text when adjusting nodes and edges;
+Welcome everyone to use it, the function introduction portal: [Label plugin](extension/label.en.md)
+
+**Optimization**
+1. Optimize the assignment priority of text editable configuration items: textEdit (global) > nodeTextEdit/edgeTextEdit (category) > element itself editable;
+2. Add the textMode attribute to graphModel to identify the current text mode;
+3. Add the method to update textMode in BaseNodeModel, BaseEdgeModel and graphModel; `updateTextMode`;
+4. Add listenable events to the text module;
+
+### Engine
+**Optimization**
+1. Refactor the engine module code and use sandbox.js to solve the performance problem caused by frequent iframe appends
+2. @logicflow/engine uses the browser to execute code by default, and the node side also uses @nyariv/sandboxjs to execute code snippets to keep both ends consistent

package/dist/docs/tutorial/update.zh.md

@@ -0,0 +1,212 @@
+---
+nav: 指南
+group:
+  title: 介绍
+  order: 0
+title: 升级到 2.0 版本
+order: 7
+toc: content
+---
+在`2.0`版本中，我们对项目基建、核心功能、插件的多个模块进行了优化，修复了一系列问题，主要有几个需要调整的地方：
+1. CDN引入路径需要变更：
+```html | pure
+<!-- 原引入路径 -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/logic-flow.js"></script>
+<link href="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/style/index.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/Menu.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/style/index.css" />
+
+<!-- 现引入路径 -->
+<!-- 旧版本引入时，需要在包名后面加上版本号、路径也需要使用老的 -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/core@1.2.27/dist/logic-flow.js"></script>
+<link href="https://cdn.jsdelivr.net/npm/@logicflow/core@1.2.27/dist/style/index.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension@1.2.27/lib/Menu.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension@1.2.27/lib/style/index.css" />
+<!-- 如果想直接引入2.0最新的版本，只需要复制下面这段代码即可 -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/index.min.js"></script>
+<link href="https://cdn.jsdelivr.net/npm/@logicflow/core/lib/style/index.min.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/dist/index.min.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/style/index.min.css" />
+
+```
+2. 通过包管理器方式引入LogicFlow core包样式路径需要变更：
+```js
+
+// 1.x版本的引入方式
+import "@logicflow/core/dist/style/index.css";
+// 2.0版本的引入方式
+import "@logicflow/core/lib/style/index.css";
+
+```
+
+3. pluginOptions参数传入的各插件的options需要根据插件名分割开
+```js
+// 这里以设置小地图是否显示连线配置项：showEdge为例
+// 1.x版本
+new LogicFlow({
+  pluginsOptions: {
+    showEdge, // MiniMap能正常显示
+  },
+})
+// 2.0版本
+new LogicFlow({
+  pluginsOptions: {
+    showEdge, // ❌MiniMap不能正常显示
+    MiniMap: {
+      showEdge,// ✅MiniMap能正常显示
+    },
+  },
+})
+```
+
+4. Group插件提供的isAllowMoveTo方法和isInRange方法的参数名调整:
+```
+x1 → minX
+y1 → minY
+x2 → maxX
+y2 → maxY
+```
+其他改动理论上对使用没有影响，以下是改动内容一览：
+
+### 项目基建
+**优化**
+1. 补充项目中所有组件、方法的类型定义;
+2. core 包中 preact -> preact/compat;
+3. 移除dependences中的 jest 依赖， lodash -> lodash-es
+4. 完善 README.md 以及 CONTRIBUTING 相关文档;
+
+### Core
+
+#### Node
+**新能力**
+1. 新增`node:resize`、`node:rotate` 和 `node:properties-change`事件
+
+**优化**
+1. 形状组件重构，一些方法进行了重命名
+   1. `formateAnchorConnectValidateData` -> `formatAnchorConnectValidateData`;
+   2. `setHoverON` -> `setHoverOn`;
+   3. `setHoverOFF` -> `setHoverOff`;
+2. 移除 TextNode getBackground 中 rectAttr下 y: y-1 的设置;
+3. fakerNode 重命名为 fakeNode;
+4. 节点文本样式支持通过`properties.textStyle`配置
+
+**问题修复**
+1. 通过 points 置原点并基于设定的 width 和 height 缩放的方法，解决多边形形状与边框定位异常的问题;
+
+#### Edge
+**新能力**
+1. 新增 adjustEdgeStart 和 adjustEdgeEnd，可单独控制调整起始点或结束点;
+2. 边文本支样式持通过`properties.textStyle`配置;
+
+**问题修复**
+1. 修复初始化时 edgeConfig 中 type 未传值场景下，未使用 graphModel.edgeType(默认边类型) 初始化边的 bug
+
+#### Grid
+**优化**
+1. 由 Grid 类自行实现网格配置选项的初始化
+2. 修改点状网格中点的最大半径计算逻辑，并增加相关注释
+
+**问题修复**
+1. 修正原有网格存在偏移的问题
+2. 修正网格配置选项的类型声明
+
+#### Graph
+**优化**
+1. 优化初始化时设置画布大小的逻辑：调整视窗时，画布大小可以同步更新;
+2. 「Breaking Change」调整 pluginOptions 只传入插件对应的 options 数据（之前是全量传入）
+
+**问题修复**
+1. 修复 设置stopMoveGraph:true但没有设置stopScrollGraph:true，画布无法滚动 的问题;
+2. 修复 GraphModel 中 getAreaElement 方法的 bug;
+
+#### Tool
+**bigfix**
+修复 TextEditTool 无效的 bug，后注原因
+   - TextEditTool 组件更新时，原先的 graphModel 和 LogicFlow props 不会触发组件的更新，通过将 textEditElement 传入触发组件更新
+   - 移除代码中无用的 console
+   - 更新依赖 @babel/plugin-proposal-class-properties -> @babel/plugin-transform-class-properties
+   - EventArgs 相关类型由 unknown 改为 any
+
+### Extension
+
+#### 框选插件
+**新能力**
+1. 增加`selection:selected-area`事件，返回框选范围;
+2. 框选插件默认启用状态改为不启用，如需初始化时就启用框选，在LogicFlow实例创建后调用`lf.extension.selectionSelect.open()`方法开启框选;
+**问题修复**
+1. 修复框选启用后，页面滚动事件被阻塞的问题;
+2. 修复缩放后，框选边距与外边框宽度计算问题;
+
+#### 小地图插件
+**新能力**
+1. 支持配置小地图展示位置;
+2. 支持选择是否渲染连线，支持初始化时设置或通过`setShowEdge`方法更新设置;
+3. 小地图显示内容优化，目前会有画布元素与视口位置共同决定展示内容;
+4. 优化小地图预览实况的拖拽交互体验;
+5. 增加小地图关闭的回调事件`miniMap:close`;
+**问题修复**
+1. 优化画布移动时，小地图的更新策略，减少性能消耗;
+2. 修复点击小地图预览视窗会触发不可预期的画布移动的问题;
+3. 修复小地图的预览视窗无法拖拽的问题;
+
+#### NodeResize插件
+**优化**
+在1.x版本中，节点缩放能力需要通过引入NodeResize插件实现，在2.0版本中，我们将resize能力内置到基础节点上;同时还支持了节点旋转能力可配置。
+1. 用户可以通过全局配置项`allowResize`、`allowRotate`设置当前实例中所有节点是否可缩放、可旋转;
+2. 也可以在初始化渲染传入数据的`properties`中增加`resizable`（需要全局配置`allowResize`为true才会生效）、`rotatable`参数控制单个节点是否可旋转可缩放（需要全局配置`allowRotate`为true才会生效），在内部，节点的`resizable`和`rotatable`默认为`true`;
+
+:::warning{title=Tip}
+  缩放能力内置后，NodeResize插件会逐步废弃
+:::
+
+3. 统一 NodeResize 中 getResizeOutlineStyle fill 和 stroke 的返回值;
+
+**问题修复**
+1. 解决resize 结束后节点重新定位的问题;
+2. 修复 HtmlResize 节点 outlineStyle fill 默认为 黑色的 bug;
+
+#### Snapshot插件
+**优化**
+1. 优化 bpmn 插件的导出内容;
+2. 支持导出节点中的网络图片;
+3. 完善snapshot使用方式，支持自定义导出的文件名、文件类型、图片宽高、背景颜色、图片质量等属性;
+
+**问题修复**
+1. 修复开启局部渲染后导出内容缺失问题;
+
+#### Group插件
+在2.0版本里，我们重写了分组插件相关逻辑，将 Group 插件升级为 [Dynamic Group 插件](extension/dynamic-group.zh.md)
+**新能力**
+1. 支持分组节点缩放旋转时，内部元素也随之同步缩放旋转;
+
+**优化**
+1. 调小 ResizeControl 的范围 30 -> 15，原因是会盖住 Group 折叠的小按钮;
+2. 优化允许文本拖动的逻辑判断 -> nodeTextDraggable && draggable 才可以允许拖动;
+
+#### HighLight插件
+**新能力**
+1. 支持高亮邻居节点模式;
+2. 支持外部传参配置高亮形式;
+
+**Optimizations**
+1. 补充功能介绍文档[HighLight 插件](extension/highlight.zh.md)
+
+#### 「New」Label插件
+**新能力**
+在2.0版本里，我们新增了一种文本展现形式：Label，这种形式与现有Text形式文本之间的主要区别点在于：
+1. 支持一个节点/一条边 上可以添加多个文本，且可以设置文本朝向;
+2. 自带富文本编辑能力，支持设置局部文本样式;
+3. 使用新的位置计算算法，优化节点和边调整时，关联文本的移动体验;
+欢迎大家使用，功能介绍传送门：[Label 插件](extension/label.zh.md)
+
+**优化**
+1. 优化文本可编辑配置项的赋值优先级：textEdit(全局) > nodeTextEdit/edgeTextEdit(分类) > 元素本身 editable;
+2. graphModel 中增加 textMode 属性，用于标识当前使用什么文本模式;
+3. BaseNodeModel、 BaseEdgeModel 以及 graphModel 中增加 更新 textMode 的方法;`updateTextMode`;
+4. 为文本模块增加可监听的事件;
+
+
+### Engine
+**优化**
+1. 重构 engine 模块代码，使用 sandbox.js 解决 iframe 频繁 append 导致的性能问题
+2. @logicflow/engine 默认使用 browser 执行代码，node 端也使用 @nyariv/sandboxjs 执行代码片段，保持两端一致

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicflow/core",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "LogicFlow, help you quickly create flowcharts",
   "main": "lib/index.js",
   "module": "es/index.js",
@@ -40,7 +40,8 @@
   "files": [
     "dist",
     "es",
-    "lib"
+    "lib",
+    "scripts"
   ],
   "scripts": {
     "clean:turbo": "rss",
@@ -56,6 +57,7 @@
     "build:watch:cjs": "rss",
     "build": "rss",
     "prebuild": "rss",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "postinstall": "node scripts/postinstall-ai-prompt.js"
   }
 }

package/scripts/postinstall-ai-prompt.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+const RESET = '\x1b[0m'
+const REMINDER_STYLE = '\x1b[1m\x1b[43m\x1b[30m' // bold, yellow bg, black fg
+
+const AGENT_RULES = `<!-- BEGIN:logicflow-agent-rules -->
+# LogicFlow Agent Rules
+
+LogicFlow documentation is available at:
+
+- \`node_modules/@logicflow/core/dist/docs/\`
+
+Package roles:
+
+- \`@logicflow/core\`: core graph editor runtime, including canvas, nodes, edges, models, events, rendering, themes, and basic interactions.
+- \`@logicflow/extension\`: official plugins for common product features.
+- \`@logicflow/layout\`: official layout plugins for automatic graph layout.
+
+The docs for \`@logicflow/extension\` and \`@logicflow/layout\` are included under:
+
+- \`node_modules/@logicflow/core/dist/docs/tutorial/extension/\`
+
+Before implementing any LogicFlow feature, check the local docs first to see whether LogicFlow already provides a built-in, extension, or layout capability. If it does, prefer the documented official capability instead of reimplementing it from scratch.
+
+If an official package is needed but not installed, ask the user before installing it.
+<!-- END:logicflow-agent-rules -->`
+
+const REMINDER_LINES = [
+  '请将下方的规则复制给你的 AI Agent，让 AI Agent 可以更了解 LogicFlow。',
+  '您还可以在 README 和官网的 AI 编程章节找到此规则',
+]
+
+function shouldUseAnsi() {
+  if (!process.stdout.isTTY) return false
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '')
+    return false
+  if (process.env.TERM === 'dumb') return false
+  if (process.env.CI === 'true' && !process.env.FORCE_COLOR) return false
+  return true
+}
+
+function dividerWidth() {
+  const c = process.stdout.columns
+  if (typeof c === 'number' && Number.isFinite(c) && c > 0) {
+    return Math.min(c, 120)
+  }
+  return 80
+}
+
+function dividerLine() {
+  return '─'.repeat(dividerWidth())
+}
+
+function printReminder() {
+  const useAnsi = shouldUseAnsi()
+  for (const line of REMINDER_LINES) {
+    if (useAnsi) {
+      process.stdout.write(`${REMINDER_STYLE}${line}${RESET}\n`)
+    } else {
+      process.stdout.write(`${line}\n`)
+    }
+  }
+}
+
+printReminder()
+console.log(dividerLine())
+console.log(AGENT_RULES)