@logicflow/core 2.2.1 → 2.2.3

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

@@ -0,0 +1,95 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 插件简介
+order: 0
+toc: content
+---
+
+> LogicFlow最初的目标就是支持一个扩展性强的流程绘制工具，用来满足各种业务需求。为了让LogicFlow的拓展性足够强，LogicFlow将所有的非核心功能都使用插件的方式开发。
+>
+> 常见产品功能通常由 `@logicflow/extension` 提供，自动布局能力由 `@logicflow/layout` 提供。两类能力的使用文档都放在插件教程分组中。
+
+::::info{title=这页适合谁读}
+- 你已经知道如何创建 `LogicFlow` 实例，现在想按目标挑选现成插件
+- 你想知道全局安装插件和实例级安装插件有什么区别
+
+如果你还没有跑通过最小示例，建议先看 [快速上手](../get-started.zh.md)。
+::::
+
+## 插件地图
+
+可以先按目标选择，而不是逐个翻插件文件：
+
+- 编辑体验增强：控制面板、右键菜单、选区、多选等
+- 节点/边能力增强：节点缩放、分组、泳道、曲线边等
+- 数据导入导出：adapter、BPMN 相关能力
+- 布局与导出：自动布局、画布辅助能力
+- 领域方案：BPMN 元素和配套能力
+
+## 使用指南
+
+`@logicflow/extension`包中提供一些开箱即用的组件，快速支持产品中常见的功能，如控制面板、右键菜单等。
+
+```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) // 拖拽面板
+```
+
+### 安装全局插件
+
+npm方式
+
+```tsx | pure
+import { BpmnElement } from '@logicflow/extension';
+
+LogicFlow.use(BpmnElement);
+```
+
+cdn方式
+
+```tsx
+<!--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的插件支持单个引入，这里以菜单插件为例-->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/Menu.js"></script>
+<script>
+  LogicFlow.use(Menu); </script>
+```
+
+### 安装插件到实例上
+
+`v1.0.7` 新增
+
+当一个单页面应用存在多个使用LogicFlow的页面时，不同的页面使用的插件可能不一样。LogicFlow初始化的时候，将插件作为参数传入到构造函数中，此时插件会覆盖全局的插件。
+
+```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"; // 2.0版本前的引入方式
+import "@logicflow/extension/lib/style/index.css";
+
+const lf = new LogicFlow({
+  container: document.querySelector("#app"),
+  grid: true,
+  plugins: [DndPanel, SelectionSelect]
+});
+```
+
+## 下一步阅读
+
+1. 已经知道要用哪个插件：直接进入对应插件页面
+2. 想先理解实例和插件关系：查看 [API 导览](../../api/logicflow-instance/index.zh.md) 中的“插件系统”
+3. 想继续自定义节点或边：回到 [进阶节点](../advanced/node.zh.md) / [进阶-边](../advanced/edge.zh.md)

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

@@ -0,0 +1,136 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Label
+order: 7
+toc: content
+---
+
+LogicFlow provides built-in node text and text editing capabilities, but sometimes we need richer text content, such as multi-line text or rich text. In such cases, you can use the `Label` plugin.
+
+## Demonstration
+
+<code id="react-portal" src="@/src/tutorial/extension/label"></code>
+
+## Using the Plugin
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Label } from "@logicflow/extension";
+import "@logicflow/extension/lib/style/index.css";
+
+// Two ways to use the plugin
+// Register the plugin using the use method
+LogicFlow.use(Label);
+
+// Or enable the plugin via configuration (you can configure plugin properties)
+const lf = new LogicFlow({
+  container: document.querySelector('#app'),
+  plugins: [Label],
+  pluginsOptions: {
+    label: {
+      // ...labelOptions
+    },
+  },
+});
+```
+
+## Configuration Options
+
+### Plugin-Level
+
+Each feature in the menu can be represented by a single configuration. The specific fields are as follows:
+
+| Field            | Type                                                    | Default Value | Required | Description                                                                   |
+| ---------------- | ------------------------------------------------------- | ------------- | -------- | ----------------------------------------------------------------------------- |
+| isMultiple       | boolean                                                 | `true`        |          | Whether a node or edge can have multiple Labels.                              |
+| maxCount         | number                                                  | `Infinity`    |          | When multiple Labels are allowed, the maximum number of Labels.               |
+| labelWidth       | number                                                  | -             |          | The width of each Label, can be uniformly set and used with textOverflowMode. |
+| textOverflowMode | 'ellipsis' \| 'wrap' \| 'clip' \| 'nowrap' \| 'default' | `default`     |          | Text overflow display mode, consistent with CSS configuration.                |
+
+### Element-Level
+
+When the Label plugin is enabled, you can also configure properties at the element level in two scenarios:
+
+1. By default, the Label is used for text rendering. During initialization, the `text` property in NodeConfig or EdgeConfig is used as the Label's text content.
+```ts
+const nodeConfig = {
+  id: '2',
+  type: 'circle',
+  x: 350,
+  y: 100,
+  properties: {},
+  text: {
+    x: 350,
+    y: 100,
+    value: 'Circle',
+  },
+}
+```
+2. Users can also initialize Labels directly with Label configuration.
+```ts
+export interface NodeConfig<P extends PropertiesType = PropertiesType> {
+  id?: string
+  type: string
+  x: number
+  y: number
+  text?: TextConfig | string
+  zIndex?: number
+  properties?: P
+  virtual?: boolean // Whether the node is virtual
+  rotate?: number
+
+  rotatable?: boolean // Whether the node is rotatable
+  resizable?: boolean // Whether the node is resizable
+
+  [key: string]: any
+}
+
+export type LabelConfig = {
+  id?: string // Unique identifier for the label
+  x: number
+  y: number
+  content?: string // Rich text content
+  value: string // Plain text content
+  rotate?: number // Rotation angle
+  // Style properties
+  style?: h.JSX.CSSProperties // Custom style for the label
+
+  // Edit state properties
+  editable?: boolean
+  draggable?: boolean
+  labelWidth?: number
+  textOverflowMode?: 'ellipsis' | 'wrap' | 'clip' | 'nowrap' | 'default'
+}
+
+export type LabelOption = {
+  // Whether multiple labels are supported
+  isMultiple: boolean
+  // Maximum number of labels allowed when multiple labels are supported
+  maxCount?: number
+}
+
+export type LabelNodeConfig = NodeConfig<{
+  _label?: string | LabelConfig | LabelConfig[]
+  _labelOptions?: LabelOption
+}>
+```
+In other words, by adding `_label` and `_labelOptions` fields in the properties of Node or Edge initialization data, you can configure the content and attributes of a single Label.
+
+:::info{title=Note:Plugin-includes-rich-text-editing-mode-by-default}
+- When double-clicking the text to enter edit mode, the selected text will display a rich text editor, allowing users to edit rich text content.
+- A switch will be added in the future to allow users to customize whether to enable rich text editing mode.
+:::
+
+## API
+
+### lf.extension.label.updateTextMode(mode)
+
+Updates whether to use Text or Label for displaying text.
+
+```ts
+// Update Label text display mode
+updateTextMode = (textMode: 'text' | 'label'): void => {}
+```

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

@@ -0,0 +1,135 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 富文本标签 (Label)
+order: 7
+toc: content
+---
+
+LogicFlow
+内部提供了节点文本以及文本编辑能力，但是有时候我们需要更加丰富的文本内容，比如支持多行文本、富文本等。这时候我们可以选择使用`Label`
+插件。
+
+## 演示
+
+<code id="react-portal" src="@/src/tutorial/extension/label"></code>
+
+## 使用插件
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Label } from "@logicflow/extension";
+import "@logicflow/extension/lib/style/index.css";
+
+// 两种使用方式
+// 通过 use 方法引入插件
+LogicFlow.use(Label);
+
+// 或者通过配置项启用插件（可以配置插件属性）
+const lf = new LogicFlow({
+  container: document.querySelector('#app'),
+  plugins: [Label],
+  pluginsOptions: {
+    label: {
+      // ...labelOptions
+    },
+  },
+});
+```
+
+## 配置项
+
+### 插件级
+
+Label插件支持一些初始化属性。具体字段如下:
+
+| 字段             | 类型                                                    | 默认值     | 是否必须 | 描述                                                         |
+| ---------------- | ------------------------------------------------------- | ---------- | -------- | ------------------------------------------------------------ |
+| isMultiple       | boolean                                                 | `true`     |          | 是否允许一个节点或边拥有多个 Label                           |
+| maxCount         | number                                                  | `Infinity` |          | 当允许多个 Label 时，限制 Label 的最大数量                   |
+| labelWidth       | number                                                  | -          |          | 每个 Label 的宽度，可以统一设置配合 textOverflowMode 使用    |
+| textOverflowMode | 'ellipsis' \| 'wrap' \| 'clip' \| 'nowrap' \| 'default' | `default`  |          | 文本溢出显示模式，配合 CSS 样式实现，与 CSS 配置项表现一致。 |
+
+### 元素级
+
+如果启用了 Label 插件，我们同时也支持元素级别的属性配置，有两种场景：
+1. 默认以 Label 为文本渲染模式，初始化时，使用 NodeConfig or EdgeConfig 中的 text 属性作为 Label 的文本内容。
+```ts
+const nodeConfig = {
+  id: '2',
+  type: 'circle',
+  x: 350,
+  y: 100,
+  properties: {},
+  text: {
+    x: 350,
+    y: 100,
+    value: '圆形',
+  },
+}
+```
+2. 我们也支持用户直接用 Label 配置初始化 Label
+```ts
+export interface NodeConfig<P extends PropertiesType = PropertiesType> {
+  id?: string
+  type: string
+  x: number
+  y: number
+  text?: TextConfig | string
+  zIndex?: number
+  properties?: P
+  virtual?: boolean // 是否虚拟节点
+  rotate?: number
+
+  rotatable?: boolean // 节点是否可旋转
+  resizable?: boolean // 节点是否可缩放
+
+  [key: string]: any
+}
+
+export type LabelConfig = {
+  id?: string // label唯一标识
+  x: number
+  y: number
+  content?: string // 富文本内容
+  value: string // 纯文本内容
+  rotate?: number // 旋转角度
+  // 样式属性
+  style?: h.JSX.CSSProperties // label自定义样式
+
+  // 编辑状态属性
+  editable?: boolean
+  draggable?: boolean
+  labelWidth?: number
+  textOverflowMode?: 'ellipsis' | 'wrap' | 'clip' | 'nowrap' | 'default'
+}
+
+export type LabelOption = {
+  // 是否支持多个 label
+  isMultiple: boolean
+  // 允许设置多个 label 时最大个数
+  maxCount?: number
+}
+
+export type LabelNodeConfig = NodeConfig<{
+  _label?: string | LabelConfig | LabelConfig[]
+  _labelOptions?: LabelOption
+}>
+```
+也就是说，在初始化 Node 或 Edge 的数据 properties 中添加 _label 和 _labelOptions 字段，即可配置单个 Label 的内容和属性。
+
+:::info{title=注意，插件默认内置了富文本编辑模式}
+- 双击文本进入编辑状态时，选中文本会弹出富文本编辑器，支持用户编辑富文本内容
+- 后续我们会增加开关，支持用户自定义是否启用富文本编辑模式
+:::
+
+## API
+### lf.extension.label.updateTextMode(mode)
+用于更新当前使用 Text 还是 Label 显示文本
+
+```ts
+// 更新 Label 文本显示模式
+updateTextMode = (textMode: 'text' | 'label'): void => {}
+```

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

@@ -0,0 +1,156 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Automatic Layout
+order: 7
+toc: content
+tag: Enhancement
+---
+
+In complex flowcharts, manually placing nodes and adjusting edges is time-consuming and often messy.
+
+The auto layout plugin can:
+- Automatically compute node positions and rank order from edge relationships
+- Support layout directions (LR/TB/BT/RL) and alignment
+- Configure node spacing, rank spacing, edge spacing, and canvas margins
+- Plan edge routes to reduce crossings and keep a consistent overall flow
+- Optionally adjust edge endpoints based on default anchors
+
+It typically produces a structured layout with clear hierarchy, consistent spacing, and fewer edge crossings, making it ideal for an initial layout that you can fine-tune.
+
+The Layout plugin is currently based on Dagre, and its scope is:
+- Covered: automatic calculation of node positions, hierarchy, spacing, and basic edge routing
+- Not covered: business rule validation, node/edge styling, and complex interaction logic (handled separately)
+
+## Live Demonstration
+
+### Default Anchors
+
+If nodes use LogicFlow's default anchors (i.e., top, bottom, left, and right anchors), and anchor information doesn't carry business meaning, you can set isDefaultAnchor to true to adjust connection start and end anchor positions during layout.
+
+<code id="react-portal-1" src="@/src/tutorial/extension/layout"></code>
+
+### Custom Anchors
+
+If nodes use custom anchors, or if anchors have actual business meaning, isDefaultAnchor is false by default, which means the layout will not adjust the connection's start and end anchors.
+
+<code id="react-portal-2" src="@/src/tutorial/extension/layout/custom"></code>
+
+## Installation
+
+```shell
+# npm
+npm install @logicflow/layout
+
+# yarn
+yarn add @logicflow/layout
+
+# pnpm
+pnpm add @logicflow/layout
+```
+
+### UMD Usage
+
+You can also use the UMD bundle directly via CDN:
+
+```html
+<!-- Include LogicFlow Core UMD -->
+<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">
+<!-- Include Layout UMD -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/layout/dist/index.min.js"></script>
+
+<script>
+  // Access Dagre plugin through global variable Layout
+  const { Dagre } = Layout;
+  
+  // Create LogicFlow instance and register plugin
+  const lf = new LogicFlow.default({
+    container: document.getElementById('container'),
+    plugins: [Dagre]
+  });
+  
+  // Use layout functionality
+  lf.dagre.layout({
+    rankdir: 'LR',
+    nodesep: 50,
+    ranksep: 100
+  });
+</script>
+```
+
+## Basic Usage
+
+### Register the Plugin
+
+Like other LogicFlow plugins, Layout supports both global and local registration:
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Dagre } from "@logicflow/layout";
+
+// Global registration
+LogicFlow.use(Dagre);
+
+// Local registration
+const lf = new LogicFlow({
+  container: document.getElementById('app'),
+  plugins: [Dagre]
+});
+```
+
+### Apply Layout
+
+After registration, you can access the dagre plugin through the LogicFlow instance's extension property:
+
+```tsx | pure
+// Use default configuration
+lf.extension.dagre.layout();
+
+// Use custom configuration
+lf.extension.dagre.layout({
+  rankdir: 'TB',   // Top-to-bottom layout direction
+  align: 'UL',     // Upper-left alignment
+  nodesep: 60,     // Node spacing
+  ranksep: 70      // Rank spacing
+});
+```
+
+## Layout Configuration Options
+
+You can customize the appearance and behavior of the layout through various options:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| rankdir | string | 'LR' | Layout direction: 'LR'(left to right), 'TB'(top to bottom), 'BT'(bottom to top), 'RL'(right to left) |
+| align | string | 'UL' | Node alignment: 'UL'(upper left), 'UR'(upper right), 'DL'(down left), 'DR'(down right) |
+| nodesep | number | 100 | Horizontal spacing between nodes (pixels) |
+| ranksep | number | 150 | Vertical spacing between ranks (pixels) |
+| marginx | number | 120 | Horizontal margin of the graph (pixels) |
+| marginy | number | 120 | Vertical margin of the graph (pixels) |
+| ranker | string | 'tight-tree' | Ranking algorithm: 'network-simplex', 'tight-tree', 'longest-path' |
+| edgesep | number | 10 | Horizontal spacing between edges (pixels) |
+| acyclicer | string | undefined | If set to 'greedy', uses a greedy heuristic for finding a feedback arc set for making the graph acyclic |
+| isDefaultAnchor | boolean | false | Whether to use default anchors: when true, automatically adjusts edge anchors and calculates edge paths based on layout direction |
+
+## Advanced Features
+
+### Auto-fit View After Layout
+
+After adjusting the layout, you may need to adjust the view to show all nodes:
+
+```tsx | pure
+// First apply the layout
+lf.extension.dagre.layout();
+// Then fit the view
+lf.fitView();
+```
+
+## Usage Recommendations
+
+1. **Complex Graphs**: For large or complex flowcharts, use automatic layout to generate an initial arrangement, then make manual adjustments
+2. **Dynamic Updates**: Apply layout after adding/removing nodes to keep the graph tidy
+3. **Direction Selection**: Choose a suitable layout direction based on the actual meaning of your business process
+4. **Parameter Adjustment**: Find the layout that best suits your diagram by adjusting node spacing and rank spacing

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

@@ -0,0 +1,156 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 自动布局 (Layout)
+order: 7
+toc: content
+---
+
+在复杂流程图中，手动摆放节点与调整连线既耗时又容易混乱。
+
+自动布局插件可以：
+- 根据连线关系自动计算节点位置与层级顺序
+- 支持布局方向（LR/TB/BT/RL）与对齐方式
+- 支持节点间距、层级间距、边间距与画布边距配置
+- 规划连线路径，减少交叉并保持整体走向一致
+- 可选使用默认锚点自动调整连线起终点位置
+
+使用后通常能获得层级清晰、间距统一、连线更少交叉的结构化布局，适合作为初始排版，再进行少量手动微调。
+
+当前 Layout 插件基于 Dagre，能力范围如下：
+- 会处理的内容：节点位置、层级与间距的自动计算，连线走向的基础规划
+- 不会处理的内容：业务规则校验、节点/边样式、复杂交互逻辑（需自行处理）
+
+## 效果演示
+
+### 默认锚点
+
+如果节点是LogicFlow的默认锚点（即上下左右4个锚点），且锚点信息并不具备业务含义。那么通过设置isDefaultAnchor 为true，就可以在布局中调整连线起终点锚点的位置。
+
+<code id="react-portal-1" src="@/src/tutorial/extension/layout"></code>
+
+### 自定义锚点
+
+如果节点的锚点是自定义的，或者锚点是具备实际业务含义的，isDefaultAnchor 默认为false，那么布局中就不会调整连线的起终点锚点。
+
+<code id="react-portal-2" src="@/src/tutorial/extension/layout/custom"></code>
+
+## 安装
+
+```shell
+# npm
+npm install @logicflow/layout
+
+# yarn
+yarn add @logicflow/layout
+
+# pnpm
+pnpm add @logicflow/layout
+```
+
+### UMD 方式使用
+
+您也可以通过 CDN 直接引入 UMD 包：
+
+```html
+<!-- 引入 LogicFlow Core UMD -->
+<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">
+<!-- 引入 Layout UMD -->
+<script src="https://cdn.jsdelivr.net/npm/@logicflow/layout/dist/index.min.js"></script>
+
+<script>
+  // 通过全局变量 Layout 访问 Dagre 插件
+  const { Dagre } = Layout;
+  
+  // 创建 LogicFlow 实例并注册插件
+  const lf = new LogicFlow.default({
+    container: document.getElementById('container'),
+    plugins: [Dagre]
+  });
+  
+  // 使用布局功能
+  lf.dagre.layout({
+    rankdir: 'LR',
+    nodesep: 50,
+    ranksep: 100
+  });
+</script>
+```
+
+## 基本使用
+
+### 注册插件
+
+与其他 LogicFlow 插件一样，Layout 支持全局和局部两种注册方式：
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Dagre } from "@logicflow/layout";
+
+// 全局注册
+LogicFlow.use(Dagre);
+
+// 局部注册
+const lf = new LogicFlow({
+  container: document.getElementById('app'),
+  plugins: [Dagre]
+});
+```
+
+### 应用布局
+
+注册完成后，您可以通过 LogicFlow 实例的 extension 属性访问 dagre 插件：
+
+```tsx | pure
+// 使用默认配置
+lf.extension.dagre.layout();
+
+// 使用自定义配置
+lf.extension.dagre.layout({
+  rankdir: 'TB',   // 从上到下的布局方向
+  align: 'UL',     // 上左对齐
+  nodesep: 60,     // 节点间距
+  ranksep: 70      // 层级间距
+});
+```
+
+## 布局配置选项
+
+通过配置不同的选项，您可以自定义布局的外观和行为。以下是支持的选项：
+
+| 参数名          | 类型    | 默认值       | 说明                                                                   |
+| --------------- | ------- | ------------ | ---------------------------------------------------------------------- |
+| rankdir         | string  | 'LR'         | 布局方向，'LR'(左到右), 'TB'(上到下), 'BT'(下到上), 'RL'(右到左)       |
+| align           | string  | 'UL'         | 节点对齐方式，'UL'(上左), 'UR'(上右), 'DL'(下左), 'DR'(下右)           |
+| nodesep         | number  | 100          | 节点间的水平间距(像素)                                                 |
+| ranksep         | number  | 150          | 层级间的垂直间距(像素)                                                 |
+| marginx         | number  | 120          | 图的水平边距(像素)                                                     |
+| marginy         | number  | 120          | 图的垂直边距(像素)                                                     |
+| ranker          | string  | 'tight-tree' | 排名算法，'network-simplex', 'tight-tree', 'longest-path'              |
+| edgesep         | number  | 10           | 边之间的水平间距(像素)                                                 |
+| acyclicer       | string  | undefined    | 如果设置为'greedy'，使用贪心算法查找反馈弧集，用于使图变为无环图       |
+| isDefaultAnchor | boolean | false        | 是否使用默认锚点：true表示会自动调整连线锚点，根据布局方向计算边的路径 |
+
+## 高级功能
+
+### 应用布局后自动适配视图
+
+布局调整后，您可能需要调整视图以显示所有节点：
+
+```tsx | pure
+// 先应用布局
+lf.extension.dagre.layout();
+// 然后适配视图
+lf.fitView();
+```
+
+
+## 使用建议
+
+1. **复杂图形**：对于大型或复杂的流程图，先使用自动布局生成初始排列，然后进行手动微调
+2. **动态更新**：在添加/删除节点后应用布局，使图形保持整洁
+3. **方向选择**：根据业务流程的实际含义选择合适的布局方向
+4. **参数调整**：通过调整节点间距和层级间距，找到最适合您图表的布局