@logicflow/core 2.2.0 → 2.2.2

package/dist/docs/tutorial/extension/group.en.md

@@ -0,0 +1,217 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Group
+order: 15
+toc: content
+tag: Deprecated
+---
+
+LogicFlow supports grouping. Grouping is a custom node built-in in LogicFlow, so developers can
+customize more scenarios based on grouping by referring to the custom node.
+
+## Default Grouping
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import '@logicflow/core/lib/style/index.css'
+import { Group } from '@logicflow/extension'
+import '@logicflow/extension/lib/style/index.css'
+
+const lf = new LogicFlow({
+  // ...
+  plugins: [Group],
+})
+lf.render({
+  nodes: [
+    {
+      type: 'group',
+      x: 300,
+      y: 300,
+    },
+  ],
+})
+```
+
+## Data format of group
+
+A `group` is a special kind of node for LogicFlow, so its data format is still basically the same as
+that of a node. However, a `group` node has an additional `children` attribute to store its child
+ids.
+
+```tsx | pure
+lf.render({
+  nodes: [
+    {
+      type: "group",
+      x: 400,
+      y: 400,
+      children: ["rect_2"],
+    },
+    {
+      id: "rect_2",
+      type: "circle",
+      x: 400,
+      y: 400,
+    },
+  ],
+});
+```
+
+## Custom Grouping
+
+In practice, we recommend that, as with custom nodes, developers customize groups based on their own
+business, and then give the groups a name that matches their business. For example, for a subgroup
+in bpmn, name it `subProcess` and then customize the style of the grouping node.
+
+```tsx | pure
+import { GroupNode } from "@logicflow/extension";
+
+class MyGroup extends GroupNode.view {
+}
+
+class MyGroupModel extends GroupNode.model {
+  getNodeStyle() {
+    const style = super.getNodeStyle();
+    style.stroke = "#AEAFAE";
+    style.strokeDasharray = "3 3";
+    style.strokeWidth = 1;
+    return style;
+  }
+}
+
+lf.register({
+  type: "my-group",
+  model: MyGroupModel,
+  view: MyGroup,
+});
+```
+
+## Attributes and methods of groupModel
+
+In addition to the properties of the node itself, there are some special properties of the group. We
+can control these properties to achieve various effects of grouping when customizing. The properties
+and methods of the node itself are shown in [nodeModel](../../api/runtime-model/nodeModel.en.md)。
+
+### State Properties
+
+| Name         | Type    | Description                                                                                        |
+|:-------------|:--------|:---------------------------------------------------------------------------------------------------|
+| isRestrict   | boolean | Whether or not to restrict grouped child nodes from being dragged out of the group, default false. |
+| resizable    | boolean | Whether the group supports manual resizing, default false.                                         |
+| foldable     | boolean | If or not the group displays the expand and collapse buttons, default false.                       |
+| width        | number  | Grouping width                                                                                     |
+| height       | number  | Grouping height                                                                                    |
+| foldedWidth  | number  | Width after grouping and folding                                                                   |
+| foldedHeight | number  | Height after folding in groups                                                                     |
+| isFolded     | boolean | Read-only, indicates whether the grouping is collapsed or not.                                     |
+| isGroup      | boolean | Read-only, always true, used to identify `model` as a `group`.                                     |
+
+Attributes of a group are set in the same way as nodes, either in the `initNodeData`
+or `setAttributes` methods of the `groupModel`.
+
+```tsx | pure
+class MyGroupModel extends GroupNode.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.isRestrict = true;
+    this.resizable = true;
+    this.foldable = true;
+    this.width = 500;
+    this.height = 300;
+    this.foldedWidth = 50;
+    this.foldedHeight = 50;
+  }
+}
+```
+
+### addChild
+
+Sets a node as a child of the grouping. Note that this method will only add relationships, it will
+not automatically move the node inside the grouping.
+
+```tsx | pure
+const groupModel = lf.getNodeModelById("group_id");
+const node = lf.addNode({
+  type: "rect",
+  x: groupModel.x,
+  y: groupModel.y,
+});
+groupModel.addChild(node.id);
+```
+
+### removeChild
+
+Removes a child node from the grouping.
+
+```tsx | pure
+const groupModel = lf.getNodeModelById("group_id");
+groupModel.removeChild("node_id_1");
+```
+
+### foldGroup
+
+Group up, `true` means group up, false means group down.
+
+```tsx | pure
+const groupModel = lf.getNodeModelById("group_id");
+groupModel.foldGroup(true);
+```
+
+### isAllowAppendIn(nodeData)
+
+Checks if incoming nodes are allowed to be added to this group, by default all nodes are allowed.
+
+```tsx | pure
+class MyGroupModel extends GroupNode.model {
+  isAllowAppendIn(nodeData) {
+    // Set to only allow custom-rect nodes to be added to this group.
+    return nodeData.type === "custom-rect";
+  }
+}
+```
+
+:::info
+When a node is not allowed to be added to a group, the node will still show up where the user put
+it, it's just that the node isn't belong to the group. If you want the added node to be removed,
+you can listen to the `group:not-allowed` event and then manually remove the node.
+:::
+
+### getAddableOutlineStyle
+
+Sets the alert effect style for group highlighting when dragging a node onto a group.
+
+```tsx | pure
+class MyGroupModel extends GroupNode.model {
+  getAddableOutlineStyle() {
+    const style = super.getAddableOutlineStyle();
+    style.stroke = "#AEAFAE";
+    style.strokeDasharray = "3 3";
+    return style;
+  }
+}
+```
+
+:::info
+How to prevent a node from connecting to a grouping?
+
+Grouping is a special kind of node, so it is still possible to disallow nodes and grouping to be
+directly connected by [custom connection rule check](../advanced/node.en.md#connection-rules). But
+please don't set the number of anchors of the grouping to 0, because when the grouping is collapsed,
+the relationship between the nodes inside the grouping and the nodes outside the grouping will be
+indicated by the anchors of the grouping being connected to the outside nodes.
+:::
+
+## example
+
+<a href="https://codesandbox.io/embed/bold-moore-vgvpf?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> Go to CodeSandbox for examples </a>
+
+:::info
+About swimlanes.
+
+The grouping function is not a swim lane and needs to be implemented by developers on the basis of
+grouping. LogicFlow will provide full-featured Bpmn support to support BPMN swimlane. You are
+welcome to PR us if you have implemented it yourself.
+:::

package/dist/docs/tutorial/extension/group.zh.md

@@ -0,0 +1,209 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 分组 (Group)
+order: 15
+toc: content
+tag: 废弃
+---
+
+::::warning{title=废弃说明}
+`Group` 已进入废弃状态，不再推荐用于新项目。
+
+如果你正在新建或维护分组能力，请优先使用 [动态分组（Dynamic Group）](./dynamic-group.zh.md)。
+::::
+
+保留本页仅用于历史项目兼容与迁移参考。
+
+## 默认分组
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import '@logicflow/core/es/style/index.css'
+import { Group } from '@logicflow/extension'
+import '@logicflow/extension/es/style/index.css'
+
+const lf = new LogicFlow({
+  // ...
+  plugins: [Group],
+})
+lf.render({
+  nodes: [
+    {
+      type: 'group',
+      x: 300,
+      y: 300,
+    },
+  ],
+})
+```
+
+## group 的数据格式
+
+`group`对 LogicFlow
+来说是一种特殊的节点，所以其数据格式仍然和节点基本一致。但是相对于普通的节点，`group`
+节点多了一个`children`属性，用来存储其子节点 Id.
+
+```tsx | pure
+lf.render({
+  nodes: [
+    {
+      type: "group",
+      x: 400,
+      y: 400,
+      children: ["rect_2"],
+    },
+    {
+      id: "rect_2",
+      type: "circle",
+      x: 400,
+      y: 400,
+    },
+  ],
+});
+```
+
+## 自定义分组
+
+在实际业务中，我们建议和自定义节点一样，开发者基于自己的业务自定义分组，然后给分组取个符合自己业务的名字。例如在
+bpmn 中的子分组，取名叫做`subProcess`，然后自定义分组节点的样式。
+
+```tsx | pure
+import { GroupNode } from "@logicflow/extension";
+
+class MyGroup extends GroupNode.view {
+}
+
+class MyGroupModel extends GroupNode.model {
+  getNodeStyle() {
+    const style = super.getNodeStyle();
+    style.stroke = "#AEAFAE";
+    style.strokeDasharray = "3 3";
+    style.strokeWidth = 1;
+    return style;
+  }
+}
+
+lf.register({
+  type: "my-group",
+  model: MyGroupModel,
+  view: MyGroup,
+});
+```
+
+## groupModel 的属性和方法
+
+分组节点除了节点本身的属性以外，还有一些属于分组的特殊属性。我们可以在自定义的时候，控制这些属性来实现各种效果的分组。节点本身的属性和方法见 [nodeModel](../../api/runtime-model/nodeModel.zh.md)。
+
+### 状态属性
+
+| 名称           | 类型      | 描述                                |
+|:-------------|:--------|:----------------------------------|
+| isRestrict   | boolean | 是否限制分组子节点拖出分组，默认 false            |
+| resizable    | boolean | 分组是否支持手动调整大小，默认 false             |
+| foldable     | boolean | 分组是否显示展开收起按钮，默认 false             |
+| width        | number  | 分组宽度                              |
+| height       | number  | 分组高度                              |
+| foldedWidth  | number  | 分组折叠后的宽度                          |
+| foldedHeight | number  | 分组折叠后的高度                          |
+| isFolded     | boolean | 只读，表示分组是否被折叠。                     |
+| isGroup      | boolean | 只读，永远为 true, 用于识别`model`为`group`。 |
+
+group 的属性设置方式和节点一样，可以在`groupModel`的`initNodeData`或`setAttributes`方法中设置。
+
+```tsx | pure
+class MyGroupModel extends GroupNode.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.isRestrict = true;
+    this.resizable = true;
+    this.foldable = true;
+    this.width = 500;
+    this.height = 300;
+    this.foldedWidth = 50;
+    this.foldedHeight = 50;
+  }
+}
+```
+
+### addChild
+
+将某个节点设置为分组的子节点。注意，此方法只会添加关系，不会自动将节点移动到分组里面。
+
+```tsx | pure
+const groupModel = lf.getNodeModelById("group_id");
+const node = lf.addNode({
+  type: "rect",
+  x: groupModel.x,
+  y: groupModel.y,
+});
+groupModel.addChild(node.id);
+```
+
+### removeChild
+
+从分组中移除某个子节点。
+
+```tsx | pure
+const groupModel = lf.getNodeModelById("group_id");
+groupModel.removeChild("node_id_1");
+```
+
+### foldGroup
+
+收起分组, 参数为`true`表示收起分组、false 表示展开分组
+
+```tsx | pure
+const groupModel = lf.getNodeModelById("group_id");
+groupModel.foldGroup(true);
+```
+
+### isAllowAppendIn(nodeData)
+
+校验是否允许传入节点添加到此分组中，默认所有的节点都可以。
+
+```tsx | pure
+class MyGroupModel extends GroupNode.model {
+  isAllowAppendIn(nodeData) {
+    // 设置只允许custom-rect节点被添加到此分组中
+    return nodeData.type === "custom-rect";
+  }
+}
+```
+
+:::info{title=提示}
+在节点不被允许添加到分组中时，节点仍然会显示在用户放的位置，只是这个节点不属于分组。如果你希望添加的节点被删除，可以监听`group:not-allowed`
+事件，然后手动删除这个节点。
+:::
+
+### getAddableOutlineStyle
+
+设置拖动节点到分组上时，分组高亮的提示效果样式。
+
+```tsx | pure
+class MyGroupModel extends GroupNode.model {
+  getAddableOutlineStyle() {
+    const style = super.getAddableOutlineStyle();
+    style.stroke = "#AEAFAE";
+    style.strokeDasharray = "3 3";
+    return style;
+  }
+}
+```
+
+:::info{title=如何阻止节点连接到分组上?}
+分组是一种特殊的节点，所以仍然可以通过[自定义连接规则校验](../advanced/node.zh.md#连接规则)
+来实现不允许节点和分组直接相连。但是请不要将分组的锚点数量设置为
+0，因为在分组被折叠时，会通过分组的锚点与外部节点相连来表示分组内部节点与外部节点的关系。
+:::
+
+## 示例
+
+<a href="https://codesandbox.io/embed/bold-moore-vgvpf?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> 去 CodeSandbox 查看示例</a>
+
+:::info{title=关于泳道}
+分组功能不是泳道，需要开发者在分组的基础上自己实现。后续 LogicFlow 提供的 Bpmn 全功能支持会支持 BPMN
+泳道。也欢迎自己实现了的同学给我们 PR。
+:::

package/dist/docs/tutorial/extension/highlight.en.md

@@ -0,0 +1,50 @@
+---
+nav: guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Highlight
+order: 12
+toc: content
+---
+
+When the number of elements on a canvas gradually increases, it becomes more difficult to quickly identify which node is currently in focus. How many lines are connected to it and which nodes are connected to it will gradually increase. In order to facilitate the user to quickly see clearly the currently focused node. We provide a highlighting function for the associated information of the focal node.
+
+## Enable
+
+```tsx | pure
+
+import LogicFlow from '@logicflow/core'
+import { Highlight } from '@logicflow/extension'
+import '@logicflow/extension/es/index.css'
+
+LogicFlow.use(Highlight)
+
+```
+
+## Configuration items
+
+| Field  | Type    | Function                                                     | Required | Description                                                                                                                                                                                                                                                                         |
+|--------|---------|--------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| mode   | string  | Highlight type, used to control the highlight display effect |          | This configuration item supports three values: <br/>1. 'single': Highlight the current node/edge<br/>2. 'path': Highlight all edges and nodes on the path of the current node/edge<br/>3. 'neighbour': Highlight all edges and nodes directly associated with the current node/edge |
+| enable | boolean | Whether to enable highlighting                               |          | This configuration item is used to control whether to display the highlighting effect                                                                                                                                                                                               |
+
+## Default state
+By default, the highlight plug-in is enabled, using the mode of highlighting all edges and nodes on the path of the current node/edge. It will take effect when the mouse moves into the node.
+
+## API
+The Highlight plug-in provides an API for modifying the state:
+
+### setMode
+Set the highlighting mode, usage:
+```tsx | pure
+lf.extension.highlight.setMode('single');
+
+```
+### setEnable
+Set the enable state, usage:
+```tsx | pure
+// Set to disable highlighting
+lf.extension.highlight.setEnable(false);
+
+```

package/dist/docs/tutorial/extension/highlight.zh.md

@@ -0,0 +1,50 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 高亮 (Highlight)
+order: 12
+toc: content
+---
+
+当一张画布上的元素逐渐增多时，快速分辨出当前获焦的节点是谁，都连了几条线，连到了哪些节点上的难度也会逐渐增大，为了方便用户快速看清当前获焦节点的关联信息，我们提供了高亮功能。
+
+## 启用
+```tsx | pure
+
+import LogicFlow from '@logicflow/core'
+import { Highlight } from '@logicflow/extension'
+import '@logicflow/extension/es/index.css'
+
+LogicFlow.use(Highlight)
+```
+
+## 配置项
+| 字段   | 类型    | 作用                           | 是否必须 | 描述                                                                                                                                                                       |
+| ------ | ------- | ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| mode   | string  | 高亮类型，用于控制高亮展示效果 |          | 该配置项支持传入三个值：<br/>1. 'single': 高亮当前节点/边<br/>2. 'path': 高亮当前节点/边所在路径上所有的边和节点<br/>3. 'neighbour': 高亮当前节点/边直接关联的所有边和节点 |
+| enable | boolean | 是否启用高亮                   |          | 该配置项用于控制是否展示高亮效果                                                                                                                                           |
+
+## 默认状态
+默认情况下，高亮插件处于启用状态，使用的是 高亮当前节点/边所在路径上所有的边和节点 模式，鼠标移入节点内部就会生效。
+
+## API
+Highlight插件对外提供了修改状态的API:
+
+### setMode
+设置高亮方式，用法：
+
+```tsx | pure
+lf.extension.highlight.setMode('single');
+
+```
+
+### setEnable
+设置启用状态，用法：
+
+```tsx | pure
+// 设置不启用高亮
+lf.extension.highlight.setEnable(false);
+
+```

package/dist/docs/tutorial/extension/insert-node-in-polyline.en.md

@@ -0,0 +1,52 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: InsertNodeInPolyline
+order: 9
+toc: content
+---
+
+## Function
+
+Drag a node to the center of an edge, it will automatically become the point in the center of the
+edge.
+Example: There is a line E from node A to node B, drag a node N to the line E, release the mouse
+when the center of node N is exactly on the path of the line E, then node N becomes the middle node
+between A and B, the original edge E is deleted, and two new lines are generated, respectively A to
+N and N to B. The examples are as follows.
+
+<!-- TODO -->
+<a href="https://examples.logic-flow.cn/demo/dist/examples/#/extension/InserNodeInPolyline?from=doc" target="_blank"> Go to CodeSandbox for examples </a>
+
+## Support
+
+Currently only the fold line is supported
+
+## Use
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import '@logicflow/core/lib/style/index.css'
+import { InsertNodeInPolyline } from '@logicflow/extension'
+import '@logicflow/extension/lib/style/index.css'
+
+LogicFlow.use(InsertNodeInPolyline)
+```
+
+## Personalized Configuration
+
+There are 2 types of node drag and drop:
+
+- The first one is dragging and dropping nodes from the control panel to the canvas, calling Dnd's
+  Api to add nodes, which is supported by this plugin by default. Disable this function as follows:
+  ```tsx | pure
+  InsertNodeInPolyline.dndAdd = false;
+  ```
+- The second is the free node in the canvas, i.e. the node that has no edges with other nodes, drag
+  and drop to adjust the position to the edges, which is supported by this plugin by default.
+  Disable this function as follows:
+  ```tsx | pure
+  InsertNodeInPolyline.dropAdd = false;
+  ```

package/dist/docs/tutorial/extension/insert-node-in-polyline.zh.md

@@ -0,0 +1,47 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 边上插入节点 (InsertNodeInPolyline)
+order: 9
+toc: content
+---
+
+## 功能
+
+拖动节点到边中间，自动成为边中间的点。
+举例：存在一条节点 A 到节点 B 的折线 E，拖拽一个节点 N 到折线 E 上，当节点 N 的中心点恰好在折线 E
+的路径上时松开鼠标，这时节点 N 就成为 A 与 B 的中间节点，原来的边 E 被删除，生成两条新的折线，分别是 A 到
+N，N 到 B。示例如下。
+
+<!-- TODO -->
+<a href="https://examples.logic-flow.cn/demo/dist/examples/#/extension/InserNodeInPolyline?from=doc" target="_blank"> 去 CodeSandbox 查看示例</a>
+
+## 支持
+
+目前仅支持折线
+
+## 使用
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import '@logicflow/core/lib/style/index.css'
+import { InsertNodeInPolyline } from '@logicflow/extension'
+import '@logicflow/extension/lib/style/index.css'
+
+LogicFlow.use(InsertNodeInPolyline)
+```
+
+## 个性化配置
+
+节点拖拽分为 2 种情况：
+
+- 第一种是从控制面板拖拽到画布中，调用 Dnd 的 Api 进行节点添加，本插件默认支持。关闭此功能设置如下：
+  ```tsx | pure
+  InsertNodeInPolyline.dndAdd = false;
+  ```
+- 第二种是画布中的游离节点，即与其他节点没有边的节点，拖拽调整位置到边上，本插件默认支持。关闭此功能设置如下：
+  ```tsx | pure
+  InsertNodeInPolyline.dropAdd = false;
+  ```

package/dist/docs/tutorial/extension/intro.en.md

@@ -0,0 +1,72 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Plug-in Introduction
+order: 0
+toc: content
+---
+
+> LogicFlow's original goal was to support an extensible flowchart editor that can meet a wide range of business needs. To keep LogicFlow extensible, non-core features are provided through plugins.
+>
+> Common product features are usually provided by `@logicflow/extension`, while automatic layout is provided by `@logicflow/layout`. Docs for both kinds of capabilities are included in this plugin tutorial group.
+
+## Usage Guidelines
+
+The `@logicflow/extension` package provides a number of out-of-the-box components that quickly support common features in the product, such as the control panel, right-click menus, and more.
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import { Control, Menu, DndPanel } from '@logicflow/extension'
+import '@logicflow/extension/lib/style/index.css'
+
+LogicFlow.use(Control)
+LogicFlow.use(Menu)
+LogicFlow.use(DndPanel)
+```
+
+
+### Installation of global plug-ins
+
+npm:
+```tsx | pure
+import { BpmnElement } from '@logicflow/extension'
+
+LogicFlow.use(BpmnElement)
+```
+
+cdn:
+```tsx | pure
+<!--LogicFlow core-css-->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/style/index.css" />
+<!--LogicFlow extension-css-->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/style/index.css" />
+<!--LogicFlow core-js-->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/logic-flow.js"></script>
+<!--LogicFlow's plug-ins support individual introductions, here's an example of a menu plug-in-->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/Menu.js"></script>
+<script>
+  LogicFlow.use(Menu);
+</script>
+```
+
+### Installing plugins on instances
+
+`v1.0.7` Added
+
+When a single-page application has multiple pages that use LogicFlow, different pages may use different plugins.LogicFlow is initialized by passing the plugin as a parameter to the constructor, at which point the plugin overrides the global plugin.
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { DndPanel, SelectionSelect } from "@logicflow/extension";
+import "@logicflow/core/lib/style/index.css";
+// import "@logicflow/core/dist/style/index.css"; // Introduced before version 2.0
+import "@logicflow/extension/lib/style/index.css";
+
+const lf = new LogicFlow({
+  container: document.querySelector("#app"),
+  grid: true,
+  plugins: [DndPanel, SelectionSelect]
+});
+```