@logicflow/core 2.2.1 → 2.2.2

package/dist/docs/tutorial/extension/proximity-connect.en.md

@@ -0,0 +1,104 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Progressive Connection
+order: 6
+toc: content
+---
+
+Progressive Connection is a dynamic interaction method in flowchart tools. Through dynamic interaction and intelligent adsorption, it helps users achieve accurate connection between nodes during the dragging process. It simplifies the operation and improves the efficiency and experience of complex process design.
+
+## Demo
+
+<code id="react-portal" src="@/src/tutorial/extension/proximity-connect"></code>
+
+## Functional introduction
+This plugin supports progressive connection in two scenarios:
+- Drag node connection: When the mouse drags the node to move, find the nearest connectable anchor point connection according to the current node position
+- Drag anchor point connection: When the mouse drags the node anchor point, find the nearest connectable anchor point connection according to the current mouse position
+
+The plugin will listen to the following events and take some actions
+| Event            | Plugin Behavior                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| node:dragstart   | Store the currently dragged node data in the plugin                                                                                                                                                                                                                                                                                                                                            |
+| node:drag        | 1. Traverse all nodes on the canvas, calculate the distance between each anchor point on each node and each anchor point on the currently dragged node, find the shortest distance and a group of connectable anchor points and store them<br/>2. Determine whether the current shortest distance is less than the threshold. If so, create a virtual edge to show the final connection effect |
+| node:drop        | Delete the virtual edge and create a real edge                                                                                                                                                                                                                                                                                                                                                 |
+| anchor:dragstart | Store the data of the currently dragged node and the trigger anchor point in the plug-in                                                                                                                                                                                                                                                                                                       |
+| anchor:drag      | 1. Traverse all nodes on the canvas, find an anchor point that is the shortest distance from the current mouse position and can be connected and store it in the plug-in<br/>2. Determine whether the current shortest distance is less than the threshold. If so, create a virtual edge to show the final connection effect                                                                   |
+| anchor:dragend   | Delete the virtual edge and create the real edge                                                                                                                                                                                                                                                                                                                                               |
+
+> Some Tips:
+> 1. Before finding the anchor point, it will first determine whether there is a connection with the same anchor point and direction on the current canvas. If so, no connection will be created;
+> 2. During the process of finding the anchor point, the anchor point data will be first obtained to determine whether the current set of anchor points can be connected. If not, no virtual edge will be generated;
+
+## Use plug-ins
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { ProximityConnect } from "@logicflow/extension";
+import "@logicflow/core/es/index.css";
+import "@logicflow/extension/lib/style/index.css";
+
+// Two ways of using
+// Import the plugin through the use method
+LogicFlow.use(ProximityConnect);
+
+// Or enable the plugin through the configuration item (you can configure the plugin properties)
+const lf = new LogicFlow({
+container: document.querySelector('#app'),
+plugins: [ProximityConnect],
+pluginsOptions: {
+proximityConnect: {
+// enable, // Whether the plugin is enabled
+// distance, // Progressive connection threshold
+// reverseDirection, // Connection direction
+// type, // Working mode: 'default' | 'node' | 'anchor'
+}
+},
+});
+```
+
+## Configuration items
+
+Each function in the menu can be represented by a configuration item. The specific fields are as follows:
+
+| Field            | Type    | Default value                                   | Required | Description                                                                                                                                                                                                               |
+| ---------------- | ------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| enable           | boolean | `true`                                          |          | Enable the plugin                                                                                                                                                                                                         |
+| distance         | number  | 100                                             |          | Gradual connection threshold                                                                                                                                                                                              |
+| reverseDirection | boolean | false                                           |          | Whether to create a reverse connection<br/>The default connection direction is that the currently dragged node points to the nearest node<br/>When set to true, the nearest node will point to the currently dragged node |
+| virtualEdgeStyle | object  | { strokeDasharray: '10,10', stroke: '#acacac' } |          | Virtual line style                                                                                                                                                                                                        |
+| type             | string  | 'default'                                       |          | Plugin working mode: `'default'`, `'node'`, or `'anchor'`. `default` supports both node drag and anchor drag; `node` works only during node dragging; `anchor` works only during anchor dragging.                         |
+
+## API
+### setThresholdDistance(distance)
+Used to modify the connection threshold
+
+```ts
+setThresholdDistance = (distance: number): void => {}
+```
+### setReverseDirection(reverse)
+Used to modify the direction of creating a connection
+
+```ts
+setReverseDirection = (reverse: boolean): void => {}
+```
+### setEnable(enable)
+Used to set the plug-in enable status
+
+```ts
+setEnable = (enable: boolean): void => {}
+```
+### setVirtualEdgeStyle(style)
+Set the virtual edge style
+
+```ts
+setVirtualEdgeStyle = (style: Record<string, unknown>): void => {}
+```
+
+## Notes
+
+- Deduplication: If a real edge with the same configuration (same source/target nodes and anchors, same direction) already exists on the canvas, the plugin will not create another virtual edge.
+- Anchor drag end special case: When anchor dragging ends, if the release position falls within a node’s anchor area, the plugin will not trigger progressive connection creation to avoid duplicate connections with built-in anchor linking (see issue 2140).

package/dist/docs/tutorial/extension/proximity-connect.zh.md

@@ -0,0 +1,107 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 渐进连线
+order: 6
+toc: content
+---
+
+渐进连线 是流程图工具中一种动态交互方式，通过动态交互和智能吸附，帮助用户在拖拽过程中实现节点之间的精准连接。简化了操作的同时还提升了复杂流程设计的效率和体验。
+
+## 演示
+
+<code id="react-portal" src="@/src/tutorial/extension/proximity-connect"></code>
+
+
+## 功能介绍
+本插件支持两种场景下的渐进连线：
+- 拖拽节点连线：鼠标拖拽节点移动过程中，根据当前节点的位置找距离最近的可连接的锚点连线
+- 拖拽锚点连线：鼠标拖拽节点锚点过程中，根据鼠标当前所在位置找到距离最近的可连接的锚点连线
+
+插件内部会监听以下几个事件，做一些动作
+| 事件             | 插件行为                                                                                                                                                                                            |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| node:dragstart   | 将当前拖拽的节点数据存储到插件中                                                                                                                                                                    |
+| node:drag        | 1. 遍历画布上所有节点，计算每个节点上每个锚点与当前拖拽节点上每个锚点的距离，找出距离最短且可以连线的一组锚点存储下来<br/>2. 判断当前最短距离是否小于阈值，是的话就创建一条虚拟边，展示最终连线效果 |
+| node:drop        | 删除虚拟边，创建真实边                                                                                                                                                                              |
+| anchor:dragstart | 将当前拖拽的节点和触发锚点的数据存储到插件中                                                                                                                                                        |
+| anchor:drag      | 1. 遍历画布上所有节点，找出距离当前鼠标所在位置最短且可以连线的一个锚点存储到插件中<br/>2. 判断当前最短距离是否小于阈值，是的话就创建一条虚拟边，展示最终连线效果                                   |
+| anchor:dragend   | 删除虚拟边，创建真实边                                                                                                                                                                              |
+
+> 一些Tip：
+> 1. 找锚点前会先判断目前画布上是否已有同锚点同方向的连线，如果有，不会再创建连线；
+> 2. 找锚点过程中会先取锚点数据判断当前的一组锚点是否可连线，如果不可连线不会生成虚拟边；
+
+## 使用插件
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { ProximityConnect } from "@logicflow/extension";
+import "@logicflow/core/es/index.css";
+import "@logicflow/extension/lib/style/index.css";
+
+// 两种使用方式
+// 通过 use 方法引入插件
+LogicFlow.use(ProximityConnect);
+
+// 或者通过配置项启用插件（可以配置插件属性）
+const lf = new LogicFlow({
+  container: document.querySelector('#app'),
+  plugins: [ProximityConnect],
+  pluginsOptions: {
+    proximityConnect: {
+      // enable, // 插件是否启用
+      // distance, // 渐进连线阈值
+      // reverseDirection, // 连线方向
+      // type, // 插件工作模式：'default' | 'node' | 'anchor'
+    }
+  },
+});
+```
+
+## 配置项
+
+菜单中的每一项功能，可以用一条配置进行表示。具体字段如下:
+
+| 字段             | 类型    | 默认值                                          | 是否必须 | 描述                                                                                                                                               |
+| ---------------- | ------- | ----------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| enable           | boolean | `true`                                          |          | 是否启用插件                                                                                                                                       |
+| distance         | number  | 100                                             |          | 渐进连线阈值                                                                                                                                       |
+| reverseDirection | boolean | false                                           |          | 是否创建反向连线<br/>默认连线方向是当前拖拽的节点指向最近的节点<br/>设置为true后会变为最近的节点指向当前拖拽节点                                   |
+| virtualEdgeStyle | object  | { strokeDasharray: '10,10', stroke: '#acacac' } |          | 虚拟线样式                                                                                                                                         |
+| type             | string  | 'default'                                       |          | 插件工作模式：可选 `'default'`、`'node'`、`'anchor'`。`default` 同时支持节点拖拽与锚点拖拽；`node` 仅在节点拖拽时生效；`anchor` 仅在锚点拖拽时生效 |
+
+
+
+## API
+### setThresholdDistance(distance)
+用于修改连线阈值
+
+```ts
+setThresholdDistance = (distance: number): void => {}
+```
+### setReverseDirection(reverse)
+用于修改创建连线的方向
+
+```ts
+setReverseDirection = (reverse: boolean): void => {}
+```
+### setEnable(enable)
+用于设置插件启用状态
+
+```ts
+setEnable = (enable: boolean): void => {}
+```
+### setVirtualEdgeStyle(style)
+设置虚拟边样式
+
+```ts
+setVirtualEdgeStyle = (style: Record<string, unknown>): void => {}
+```
+
+## 注意事项
+
+- 去重逻辑：当画布上已存在同配置的真实边（同起止节点与锚点、同方向）时，插件不会再创建虚拟边，避免重复连线。
+- 锚点拖拽结束的特殊处理：在锚点拖拽结束时，如果释放位置落在某个节点的锚点区域，将不触发插件的连线创建，以避免与内置锚点连线重复（参考 issue 2140）。

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

@@ -0,0 +1,166 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: SelectionSelect
+order: 5
+toc: content
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+The SelectionSelect plugin in LogicFlow allows users to select multiple graphical elements by dragging the mouse to draw a rectangular box, facilitating batch operations or editing.
+
+## Demonstration
+
+<code id="react-portal" src="@/src/tutorial/extension/selection-select"></code>
+
+## Updates
+
+### Exclusive Selection Mode
+In version <Badge>2.0.13</Badge>, an exclusive selection mode was added. When enabled, users can only perform selection actions, and in turn, users can select multiple elements in batches. Already selected elements will be deselected when selected again.
+Users can set whether to enable exclusive selection mode by default by passing the `exclusiveMode` parameter when creating an instance:
+``` ts
+const lf = new LogicFlow({
+  // ...config, // other configurations
+  plugins: [SelectionSelect],
+  pluginsOptions: {
+    selectionSelect: {
+      exclusiveMode: false,
+    },
+  },
+});
+```
+You can also dynamically modify the exclusive mode status by calling the [`setExclusiveMode`](#setexclusivemode) method below.
+
+## Usage
+
+### Registration
+
+There are two registration methods: global registration and local registration. The difference is that global registration allows every `lf` instance to use it.
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { SelectionSelect } from "@logicflow/extension";
+
+// Global registration
+LogicFlow.use(SelectionSelect);
+
+// Local registration
+const lf = new LogicFlow({
+  ...config,
+  plugins: [SelectionSelect]
+});
+```
+
+After registering the plugin, the following methods will be added during initialization:
+
+## API
+
+### openSelectionSelect
+
+Enable selection selection.
+
+```tsx | pure
+lf.openSelectionSelect();
+
+// Added in 1.1.0
+lf.extension.selectionSelect.openSelectionSelect();
+```
+
+### closeSelectionSelect
+
+Disable selection selection.
+
+```tsx | pure
+lf.closeSelectionSelect();
+
+// Added in 1.1.0
+lf.extension.selectionSelect.closeSelectionSelect();
+```
+
+### setSelectionSense
+
+Set selection sensitivity.
+
+- By default, the entire node must be within the selection box to be selected.
+- By default, both the start and end points of the edge must be within the selection box to be selected.
+
+You can call the `setSelectionSense` method to reconfigure this.
+
+| Parameter   | Default Value | Description                                                                                        |
+| ----------- | ------------- | -------------------------------------------------------------------------------------------------- |
+| isWholeEdge | true          | Whether both the start and end points of the edge must be within the selection area to be selected |
+| isWholeNode | true          | Whether the entire node must be within the selection area to be selected                           |
+
+Usage:
+
+```tsx | pure
+lf.extension.selectionSelect.setSelectionSense(false, true);
+```
+
+### setExclusiveMode
+
+Set the status of exclusive selection mode.
+
+- Exclusive mode is disabled by default
+
+You can call the plugin method `setExclusiveMode` to reconfigure
+
+| Parameter | Default Value | Description                      |
+| --------- | ------------- | -------------------------------- |
+| status    | false         | Whether to enable exclusive mode |
+
+Usage:
+
+```tsx | pure
+lf.extension.selectionSelect.setExclusiveMode(true);
+
+// You can also use the runtime shortcut mounted on the lf instance.
+// Note: this method is not typed in the current public types, so TypeScript projects should prefer the plugin instance method above.
+lf.setSelectionSelectMode(true);
+```
+
+## Events
+
+The selection plugin provides several events that you can listen to:
+
+| Event Name            | Description                             | Event Object          |
+| :-------------------- | :-------------------------------------- | :-------------------- |
+| selection:selected    | Triggered after selection box selection | All selected elements |
+| selection:mousedown   | Mouse pressed on selection area         | e                     |
+| selection:dragstart   | Start dragging selection area           | e                     |
+| selection:drag        | Selection area being dragged            | e                     |
+| selection:drop        | Selection area drag released            | e                     |
+| selection:mousemove   | Mouse moving in selection area          | e, position           |
+| selection:mouseup     | Mouse released in selection area        | e                     |
+| selection:contextmenu | Right-click in selection area           | e                     |
+
+The event object contains:
+
+| Property | Type       | Description                                                                                                            |
+| :------- | :--------- | :--------------------------------------------------------------------------------------------------------------------- |
+| e        | MouseEvent | Native mouse event object                                                                                              |
+| position | Object     | Mouse trigger point coordinates in canvas (See [getPointByClient](./detail/index.en.md#getpointbyclient) return value) |
+
+## Default State
+
+The default state of the selection functionality is influenced by whether the canvas dragging is allowed on the page. The canvas can either be dragged or have the selection box, but not both simultaneously.
+
+```tsx | pure
+const lf = new LogicFlow({
+  container: document.querySelector("#app"),
+  stopMoveGraph: true,
+});
+```
+
+If `stopMoveGraph` is true, meaning canvas dragging is not allowed, then selection is enabled by default.
+
+If `stopMoveGraph` is false, meaning canvas dragging is allowed, then selection is disabled by default.
+
+In most cases, we expect to allow canvas dragging and only enable selection when the user clicks and drags the panel. Please refer to the [Drag-and-Drop Panel Plugin](dnd-panel.en.md).

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

@@ -0,0 +1,150 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 框选 (SelectionSelect)
+order: 5
+toc: content
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+LogicFlow 的框选插件允许用户通过拖动鼠标绘制矩形框来选择多个图形元素，方便进行批量操作或编辑。
+
+
+## 演示
+
+<code id="react-portal" src="@/src/tutorial/extension/selection-select"></code>
+
+## 更新
+
+### 框选独占模式
+在<Badge>2.0.13</Badge>版本新增了框选独占模式，开启后用户只能做框选动作，相对的用户可以分批框选多个元素，已框选的元素二次框选会被取消选中。
+用户可以通过在创建实例时通过传入`exclusiveMode`参数用来设置是否默认开启独占框选模式
+``` ts
+const lf = new LogicFlow({
+  // ...config, // 其他配置
+  plugins: [SelectionSelect],
+  pluginsOptions: {
+    selectionSelect: {
+      exclusiveMode: false,
+    },
+  },
+});
+```
+也可以通过调用下方的[`setExclusiveMode`](#setexclusivemode)方法动态修改独占模式的启用状态。
+
+## 使用
+
+### 注册
+
+两种注册方式，全局注册和局部注册，区别是全局注册每一个 `lf` 实例都可以使用。
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { SelectionSelect } from "@logicflow/extension";
+
+// 全局注册
+LogicFlow.use(SelectionSelect);
+
+// 局部注册
+const lf = new LogicFlow({
+  ...config,
+  plugins: [SelectionSelect]
+});
+
+```
+
+注册插件后，插件会在初始化时增加下述方法：
+
+## API
+
+### openSelectionSelect
+
+开启框选。
+
+```tsx | pure
+
+lf.openSelectionSelect();
+
+// 1.1.0新增用法
+lf.extension.selectionSelect.openSelectionSelect();
+
+```
+
+### closeSelectionSelect
+
+关闭框选。
+
+```tsx  | pure
+
+lf.closeSelectionSelect()
+
+// 1.1.0新增用法
+lf.extension.selectionSelect.closeSelectionSelect()
+
+```
+
+### setSelectionSense
+
+设置选区灵敏度。
+
+- 默认需要框选整个节点才选中节点
+- 默认需要框选边的起点、终点才选中边
+
+可以调用插件方法`setSelectionSense`来重新设置
+
+| 参数        | 默认值 | 描述                                   |
+| ----------- | ------ | -------------------------------------- |
+| isWholeEdge | true   | 是否要边的起点终点都在选区范围才算选中 |
+| isWholeNode | true   | 是否要节点的全部点都在选区范围才算选中 |
+
+用法：
+
+```tsx | pure
+lf.extension.selectionSelect.setSelectionSense(false, true);
+```
+
+### setExclusiveMode
+
+设置框选独占模式的启用状态
+
+- 默认不启用独占模式
+
+可以调用插件实例方法 `setExclusiveMode` 来重新设置。
+
+| 参数   | 默认值 | 描述             |
+| ------ | ------ | ---------------- |
+| status | false  | 是否启用独占模式 |
+
+用法：
+
+```tsx | pure
+lf.extension.selectionSelect.setExclusiveMode(true);
+
+// 也可以使用运行时挂载在 lf 实例上的快捷方法。
+// 注意：该方法当前公开类型里没有类型提示，TypeScript 项目中更推荐使用上面的插件实例方法。
+lf.setSelectionSelectMode(true);
+```
+
+## 默认状态
+
+默认是否开启框选功能，受到页面是否允许拖动画布影响。画布可以拖动与选区不能同时存在。
+
+```tsx | pure
+const lf = new LogicFlow({
+  container: document.querySelector("#app"),
+  stopMoveGraph: true,
+});
+```
+
+如果`stopMoveGraph`为 true，也就是不允许拖动画布，那么默认则可以进行框选。
+
+如果`stopMoveGraph`不为 true, 也就是允许拖动画布，那么默认则不可以进行框选。
+
+大多数情况下，我们期望允许拖动画布，当用户点击拖拽面板后才开启选区。请参考[拖拽面板插件](dnd-panel.zh.md)