@logicflow/core 2.2.1 → 2.2.2

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

@@ -0,0 +1,319 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Menu
+order: 1
+toc: content
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+When using flowchart tools for editing, users' attention is often focused on the canvas area. Compared to frequently moving the mouse to click the top menu bar or using shortcut keys, right-clicking directly on nodes, edges, or blank areas is more efficient and intuitive. To better match users' operating habits, LogicFlow has built-in right-click menus, making common operations readily accessible and improving the overall editing experience.
+
+## Enable
+
+Import and enable the default menu
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Menu } from "@logicflow/extension";
+import "@logicflow/extension/lib/style/index.css";
+
+LogicFlow.use(Menu); // Global import
+
+const lf = new LogicFlow({
+  plugins: [Menu], // Local import
+})
+```
+
+By default, the menu plugin supports node menus, edge menus, and canvas menus, with the following built-in functions:
+
+- Node right-click menu (nodeMenu): Delete, Copy, Edit text
+- Edge right-click menu (edgeMenu): Delete, Edit text  
+- Canvas right-click menu (graphMenu): None
+
+Of course, supporting only these configuration items is far from enough, so we also support users to customize menu configuration items.
+
+## Menu configuration items
+
+Each function in the menu can be represented by a configuration entry. The specific fields are as follows:
+
+| Fields    | Type             | Role                                          | Required | Description                                                                                                                                                                                                                                                                                                                                                            |
+| --------- | ---------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| text      | string           | Text content                                  |          | Text displayed by the menu item                                                                                                                                                                                                                                                                                                                                        |
+| className | string           | Class name                                    |          | The default class for each item is lf-menu-item, set this field and class will add className to the original.                                                                                                                                                                                                                                                          |
+| icon      | boolean / string | Whether to create a span placeholder for icon |          | If simple text cannot richly represent the menu, you can add an icon. Set to `true` to create an empty icon container with class `lf-menu-icon`. Set to a string for various icon formats: image file paths (e.g., `./icon.png`), base64 image data (e.g., `data:image/png;base64,...`), CSS class names, or HTML content. Usually used in conjunction with className. |
+| disabled  | boolean          | Whether to disable menu item                  |          | When set to true, the menu item will be displayed in gray and cannot be clicked. This state can be dynamically modified using the `changeMenuItemDisableStatus` method.                                                                                                                                                                                                |
+| callback  | Function         | Callback executed after clicking              | ✅        | You can get node data/edge data/event information in the three menu callbacks respectively.                                                                                                                                                                                                                                                                            |
+
+Here's an example of writing a node right-click menu delete function:
+
+```tsx | pure
+// Define a menu item for node deletion
+const menuItem = {
+  className: "lf-menu-delete",
+  icon: true,
+  callback: (node) => {
+    // Delete the node and emit a custom-node:deleted event with the deleted node data.
+    lf.graphModel.deleteNode(node.id);
+    lf.graphModel.eventCenter.emit("custom-node:deleted", node);
+  },
+}
+```
+
+## Adding Menu Options
+
+You can use the `lf.extension.menu.addMenuConfig` method to add new options to the existing menu. The specific configuration example is as follows:
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Menu } from "@logicflow/extension";
+
+import NodeData = LogicFlow.NodeData;
+import EdgeData = LogicFlow.EdgeData;
+import Position = LogicFlow.Position;
+
+// Instantiate LogicFlow
+const lf = new LogicFlow({
+  container: document.getElementById("app"),
+  // Register plugins
+  plugins: [Menu],
+});
+// Add options to the menu
+// You can also call lf.extension.menu.addMenuConfig to set the menu, both have the same effect
+lf.addMenuConfig({
+  nodeMenu: [
+    {
+      text: 'Share',
+      callback() {
+        alert('Share Success!')
+      },
+    },
+    {
+      text: 'Properties',
+      callback(node: NodeData) {
+        alert(`
+              Node ID: ${node.id}
+              Node Type: ${node.type}
+              Node Position: (x: ${node.x}, y: ${node.y})
+            `)
+      },
+    },
+  ],
+  edgeMenu: [
+    {
+      text: 'Properties',
+      callback(edge: EdgeData) {
+        const {
+          id,
+          type,
+          startPoint,
+          endPoint,
+          sourceNodeId,
+          targetNodeId,
+        } = edge
+        alert(`
+              Edge ID: ${id}
+              Edge Type: ${type}
+              Start Point: (x: ${startPoint.x}, y: ${startPoint.y})
+              End Point: (x: ${endPoint.x}, y: ${endPoint.y})
+              Source Node ID: ${sourceNodeId}
+              Target Node ID: ${targetNodeId}
+            `)
+      },
+    },
+  ],
+  graphMenu: [
+    {
+      text: 'Share',
+      callback() {
+        alert('Share Success!')
+      },
+    },
+    {
+      text: 'Add Node',
+      callback(data: Position) {
+        lf.addNode({
+          type: 'rect',
+          x: data.x,
+          y: data.y,
+        })
+      },
+    },
+  ],
+})
+lf.render();
+```
+
+## Overwriting Menus
+
+If there are unwanted options in the default menu, or it doesn't meet the requirements, you can use `lf.setMenuConfig` to override the default menu and achieve a custom menu effect.
+
+```tsx | pure
+lf.setMenuConfig({
+  nodeMenu: [
+    {
+      text: "Delete",
+      callback(node) {
+        lf.deleteNode(node.id);
+      },
+    },
+  ], // Override the default node right-click menu
+  edgeMenu: false, // Remove the default edge right-click menu
+  graphMenu: [], // Override the default edge right-click menu, same behavior as false
+});
+```
+
+## Configuring Menus for Specified Element Types
+
+In addition to overwriting the entire menu above, you can also use `lf.setMenuByType` to set menus for elements of specified types.
+
+```tsx | pure
+lf.setMenuByType({
+  type: "bpmn:startEvent",
+  menu: [
+    {
+      text: "Share111",
+      callback() {
+        console.log("Share Success222!");
+      },
+    },
+  ],
+});
+```
+
+## Dynamic Enable/Disable Menu Items<Badge>New in 2.1.0</Badge>
+
+To provide more flexible interaction, version 2.1.0 adds functionality to dynamically control the disabled state of menu items, allowing you to dynamically disable or enable specific menu items based on business logic.
+
+### API
+
+```tsx | pure
+lf.changeMenuItemDisableStatus(menuKey, text, disabled)
+```
+
+Parameter description:
+- `menuKey`: Menu type, possible values are `'nodeMenu'` | `'edgeMenu'` | `'graphMenu'` | `'selectionMenu'`
+- `text`: Text of the menu item to operate on
+- `disabled`: Whether to disable, `true` to disable, `false` to enable
+
+### Usage Example
+
+```tsx | pure
+// Disable the "Delete" option in node menu
+lf.changeMenuItemDisableStatus('nodeMenu', 'Delete', true)
+
+// Enable the "Properties" option in edge menu
+lf.changeMenuItemDisableStatus('edgeMenu', 'Properties', false)
+
+// Disable the "Share" option in graph menu
+lf.changeMenuItemDisableStatus('graphMenu', 'Share', true)
+```
+
+### Setting Disabled State During Configuration
+
+You can also directly set certain menu items to disabled state when configuring the menu:
+
+```tsx | pure
+lf.addMenuConfig({
+  nodeMenu: [
+    {
+      text: 'Delete',
+      disabled: true, // Initially disabled
+      callback(node: NodeData) {
+        lf.deleteNode(node.id)
+      },
+    },
+    {
+      text: 'Copy',
+      disabled: false, // Initially enabled
+      callback(node: NodeData) {
+        lf.cloneNode(node.id)
+      },
+    },
+  ],
+})
+```
+
+## Selection Menu
+
+After using the selection plugin, the selection component will also display a menu. By default, the selection menu only has a delete operation.
+Like other menu items, you can call the methods provided by the Menu plugin to modify the selection menu configuration.
+
+```tsx | pure
+// Example: Set the selection menu to not display
+lf.setMenuByType({
+  type: "lf:defaultSelectionMenu",
+  menu: [],
+});
+```
+
+## Setting Menus for Custom Nodes
+
+In addition to setting menus for general canvas elements above, LogicFlow also supports setting menus for custom nodes:
+
+```tsx | pure
+
+// index.js
+import { RectNode, CustomeModel } from "./custom.ts";
+// Register custom node
+lf.register({
+  type: "custome_node",
+  view: RectNode,
+  model: CustomeModel,
+});
+// Set custom node menu
+lf.setMenuByType({
+  type: "custome_node",
+  menu: [
+    {
+      className: "lf-menu-delete",
+      icon: true,
+      callback: (node) => {
+        lf.graphModel.deleteNode(node.id);
+        lf.graphModel.eventCenter.emit("custom:event", node);
+      },
+    },
+    {
+      text: "edit",
+      className: "lf-menu-item",
+      callback: (node) => {
+        lf.graphModel.setElementStateById(node.id, 2);
+      },
+    },
+    {
+      text: "copy",
+      className: "lf-menu-item",
+      disabled: false, // Can set disabled state
+      callback: (node) => {
+        lf.graphModel.cloneNode(node.id);
+      },
+    }
+  ],
+});
+
+lf.on("custom:event", (node) => {
+  console.log(node);
+});
+```
+
+### Custom Menu Styles
+
+The Menu plugin sets a class for each DOM it displays. Users can override the original style based on the class in the menu structure and set styles that match the host's style.
+
+- Menu: lf-menu
+- Menu item: lf-menu-item, user-defined className
+- Menu item text: lf-menu-item-text
+- Menu item icon: lf-menu-item-icon, need to set the menu item configuration icon to true
+- Disabled menu item: lf-menu-item__disabled, this class is automatically added when a menu item is disabled
+
+By setting these classes, you can override the default style, beautify font color, set menu item icons, etc.
+
+## Effect
+<a href="https://codesandbox.io/embed/dazzling-hypatia-en8s9?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> Go to CodeSandbox for examples </a>

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

@@ -0,0 +1,377 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 右键菜单 (Menu)
+order: 1
+toc: content
+---
+
+在使用流程图工具进行编辑时，用户的注意力往往集中在画布区域。相比频繁移动鼠标去点击顶部菜单栏或使用快捷键，直接在节点、边或空白区域右键操作会更高效、符合直觉。为了更好地贴合用户的操作习惯，LogicFlow内置了右键菜单，让常用操作触手可及，提升整体编辑体验。
+
+## 启用
+
+引入并启用默认菜单
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Menu } from "@logicflow/extension";
+import "@logicflow/extension/lib/style/index.css";
+
+LogicFlow.use(Menu); // 全局引入
+
+const lf = new LogicFlow({
+  plugins: [Menu], // 局部引入
+})
+```
+
+默认情况下，菜单插件支持节点菜单、边菜单、画布菜单，并内置了以下功能：
+
+- 节点右键菜单(nodeMenu)： 删除、复制、编辑文案
+- 边右键菜单(edgeMenu)：删除、编辑文案
+- 画布右键菜单(graphMenu)：无
+
+当然，只支持这些配置项是远远不够的，因此我们还支持用户定制菜单配置项。
+
+## 菜单配置项
+
+菜单中的每一项功能，可以用一条配置进行表示。具体字段如下:
+
+| 字段      | 类型             | 作用                       | 是否必须 | 描述                                                                                                                                                                                                                                                                                          |
+| --------- | ---------------- | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| text      | string           | 文案                       |          | 菜单项展示的文案                                                                                                                                                                                                                                                                              |
+| className | string           | class 名称                 |          | 每一项默认 class 为 lf-menu-item，设置了此字段，class 会在原来的基础上添加 className。                                                                                                                                                                                                        |
+| icon      | boolean / string | 是否创建 icon 的 span 展位 |          | 如果简单的文案不能丰富表示菜单，可以加个 icon。设置为 `true` 时会创建一个 class 为 `lf-menu-icon` 的空图标容器。<br/>`2.1.0`版本开始，支持多种图标格式：图片文件路径（如 `./icon.png`）、base64 图片数据（如 `data:image/png;base64,...`）、CSS 类名或 HTML 内容。一般与 className 配合使用。 |
+| disabled  | boolean          | 是否禁用菜单项             |          | 设置为 true 时，菜单项会显示为灰色且无法点击。可以通过 `changeMenuItemDisableStatus` 方法动态修改此状态。                                                                                                                                                                                     |
+| callback  | Function         | 点击后执行的回调           | ✅        | 三种菜单回调中分别可以拿到节点数据/边数据/事件信息。                                                                                                                                                                                                                                          |
+
+这里以节点右键菜单删除功能的写法为例：
+
+```tsx | pure
+// 定义一个做节点删除动作的菜单项
+const menuItem = {
+  className: "lf-menu-delete",
+  icon: true,
+  callback: (node) => {
+    // 删除节点，并触发一个自定义事件 custom-node:deleted，把当前删除的节点信息抛出去
+    lf.graphModel.deleteNode(node.id);
+    lf.graphModel.eventCenter.emit("custom-node:deleted", node);
+  },
+}
+```
+
+## API
+
+### addMenuConfig
+
+通过`addMenuConfig`方法可以在原有菜单的基础上追加新的选项，具体配置示例如下：
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import { Menu } from '@logicflow/extension'
+
+import NodeData = LogicFlow.NodeData
+import EdgeData = LogicFlow.EdgeData
+import Position = LogicFlow.Position
+
+// 实例化 LogicFlow
+const lf = new LogicFlow({
+  container: document.getElementById('app'),
+  // 注册插件
+  plugins: [Menu],
+})
+// 为菜单追加选项
+// 也可以通过调用 lf.extension.menu.addMenuConfig 设置菜单，二者效果是相同的
+lf.addMenuConfig({
+  nodeMenu: [
+    {
+      text: '分享',
+      callback() {
+        alert('分享成功！')
+      },
+    },
+    {
+      text: '属性',
+      callback(node: NodeData) {
+        alert(`
+              节点id：${node.id}
+              节点类型：${node.type}
+              节点坐标：(x: ${node.x}, y: ${node.y})
+            `)
+      },
+    },
+  ],
+  edgeMenu: [
+    {
+      text: '属性',
+      callback(edge: EdgeData) {
+        const {
+          id,
+          type,
+          startPoint,
+          endPoint,
+          sourceNodeId,
+          targetNodeId,
+        } = edge
+        alert(`
+              边id：${id}
+              边类型：${type}
+              边起点坐标：(startPoint: [${startPoint.x}, ${startPoint.y}])
+              边终点坐标：(endPoint: [${endPoint.x}, ${endPoint.y}])
+              源节点id：${sourceNodeId}
+              目标节点id：${targetNodeId}
+            `)
+      },
+    },
+  ],
+  graphMenu: [
+    {
+      text: '分享',
+      callback() {
+        alert('分享成功！')
+      },
+    },
+    {
+      text: '添加节点',
+      callback(data: Position) {
+        lf.addNode({
+          type: 'rect',
+          x: data.x,
+          y: data.y,
+        })
+      },
+    },
+  ],
+})
+lf.render()
+```
+
+### setMenuConfig
+
+如果默认菜单中存在不需要的选项，或者无法满足需求，可以通过`lf.setMenuConfig`覆盖默认菜单，实现自定义菜单的效果。
+
+```tsx | pure
+lf.setMenuConfig({
+  nodeMenu: [
+    {
+      text: "删除",
+      callback(node) {
+        lf.deleteNode(node.id);
+      },
+    },
+  ], // 覆盖默认的节点右键菜单
+  edgeMenu: false, // 删除默认的边右键菜单
+  graphMenu: [], // 覆盖默认的边右键菜单，与false表现一样
+});
+```
+
+### setMenuByType
+
+除了上面的复写整个菜单外，还可以使用`lf.setMenuByType`为指定类型的元素设置菜单。
+
+```tsx | pure
+lf.setMenuByType({
+  type: "bpmn:startEvent",
+  menu: [
+    {
+      text: "分享111",
+      callback() {
+        console.log("分享成功222！");
+      },
+    },
+  ],
+});
+```
+
+### changeMenuItemDisableStatus<Badge>2.1.0新增</Badge>
+
+为了提供更灵活的交互，在2.1.0版本新增提供了动态控制菜单项禁用状态的功能，可以根据业务逻辑动态地禁用或启用特定的菜单项。
+
+```tsx | pure
+lf.changeMenuItemDisableStatus(menuKey, text, disabled)
+```
+
+参数说明：
+- `menuKey`: 菜单类型，可选值为 `'nodeMenu'` | `'edgeMenu'` | `'graphMenu'` | `'selectionMenu'`
+- `text`: 要操作的菜单项文本
+- `disabled`: 是否禁用，`true` 为禁用，`false` 为启用
+
+#### 使用示例
+
+```tsx | pure
+// 禁用节点菜单中的"删除"选项
+lf.changeMenuItemDisableStatus('nodeMenu', '删除', true)
+
+// 启用边菜单中的"属性"选项
+lf.changeMenuItemDisableStatus('edgeMenu', '属性', false)
+
+// 禁用画布菜单中的"分享"选项
+lf.changeMenuItemDisableStatus('graphMenu', '分享', true)
+```
+
+#### 配置时设置禁用状态
+
+也可以在配置菜单时直接设置某些菜单项为禁用状态：
+
+```tsx | pure
+lf.addMenuConfig({
+  nodeMenu: [
+    {
+      text: '删除',
+      disabled: true, // 初始状态为禁用
+      callback(node: NodeData) {
+        lf.deleteNode(node.id)
+      },
+    },
+    {
+      text: '复制',
+      disabled: false, // 初始状态为启用
+      callback(node: NodeData) {
+        lf.cloneNode(node.id)
+      },
+    },
+  ],
+})
+```
+
+## 选区菜单
+
+在使用了选区插件后，选区插件也会出现菜单，默认情况下选区菜单只有删除操作。
+和其他菜单项一样，可以调用Menu插件提供的方法对选区菜单配置进行修改。
+
+```tsx | pure
+// 一个🌰：设置选区菜单不展示
+lf.setMenuByType({
+  type: "lf:defaultSelectionMenu",
+  menu: [],
+});
+```
+
+## 为自定义节点设置菜单
+
+除了上面的为画布通用元素设置菜单外，LogicFlow还支持为自定义节点设置菜单：
+
+```tsx | pure
+
+// index.js
+import { RectNode, CustomeModel } from "./custom.ts";
+// 注册自定义节点
+lf.register({
+  type: "custome_node",
+  view: RectNode,
+  model: CustomeModel,
+});
+// 设置自定义节点菜单
+lf.setMenuByType({
+  type: "custome_node",
+  menu: [
+    {
+      className: "lf-menu-delete",
+      icon: true,
+      callback: (node) => {
+        lf.graphModel.deleteNode(node.id);
+        lf.graphModel.eventCenter.emit("custom:event", node);
+      },
+    },
+    {
+      text: "edit",
+      className: "lf-menu-item",
+      callback: (node) => {
+        this.lf.graphModel.setElementStateById(node.id, 2);
+      },
+    },
+    {
+      text: "copy",
+      className: "lf-menu-item",
+      disabled: false, // 可以设置禁用状态
+      callback: (node) => {
+        this.lf.graphModel.cloneNode(node.id);
+      },
+    }
+  ],
+});
+
+lf.on("custom:event", (node) => {
+  console.log(node);
+});
+```
+
+## 自定义菜单样式
+
+Menu插件为其展示的每个DOM都设置了 class ，用户可以根据菜单结构中的 class 覆盖原有样式，设置符合宿主风格的样式。
+
+- 菜单：lf-menu
+- 菜单项：lf-menu-item、用户自定义的 className
+- 菜单项-文案：lf-menu-item-text
+- 菜单项-图标：lf-menu-item-icon,需要将菜单项配置 icon 设置为 true
+- 禁用菜单项：lf-menu-item__disabled，菜单项被禁用时会自动添加此 class
+
+通过设置这些 class，可以覆盖默认样式，美化字体颜色，设置菜单项 icon 等。
+
+## 自定义菜单Icon<Badge>2.1.0新增</Badge>
+菜单组件现在支持多种图标配置方式，可以通过 `MenuItem` 的 `icon` 字段来设置图标，目前支持以下几种Icon设置方式：
+
+#### 1. 布尔值（兼容老逻辑）
+```typescript
+{
+  text: '删除',
+  icon: true, // 创建空的图标容器
+  callback: (node) => { /* ... */ }
+}
+```
+
+#### 2. CSS类名（单个类名）
+```typescript
+{
+  text: '删除',
+  icon: 'fa-trash', // 添加多个类名
+  callback: (node) => { /* ... */ }
+}
+
+// 或者使用点开头
+{
+  text: '删除',  
+  icon: '.fa .fa-trash', // 添加多个类名
+  callback: (node) => { /* ... */ }
+}
+```
+
+#### 3. 图片文件路径
+
+:::warning{title=Tip}
+目前只支持 `png` `jpg` `jpeg` `gif` `svg` `webp` `ico` `bmp` 格式的图片
+:::
+
+```typescript
+{
+  text: '删除',
+  icon: './assets/icons/delete.png', // 本地图片文件
+  callback: (node) => { /* ... */ }
+}
+
+{
+  text: '复制',
+  icon: 'https://example.com/icons/copy.png', // 远程图片
+  callback: (node) => { /* ... */ }
+}
+```
+
+#### 5. HTML内容
+```typescript
+{
+  text: '删除',
+  icon: '<i class="fa fa-trash"></i>', // 直接插入HTML
+  callback: (node) => { /* ... */ }
+}
+
+// SVG图标
+{
+  text: '编辑',
+  icon: '<svg width="16" height="16"><path d="..."/></svg>',
+  callback: (node) => { /* ... */ }
+}
+```
+
+## 功能演示
+<code id="react-portal" src="@/src/tutorial/extension/menu"></code>