@knotx/plugins-connection-line 0.4.12 → 0.4.13

package/README.en.md

@@ -0,0 +1,287 @@
+# @knotx/plugins-connection-line
+
+Connection line plugin that provides drag-and-drop connection functionality between nodes.
+
+## Installation
+
+```bash
+npm install @knotx/plugins-connection-line
+```
+
+## Overview
+
+`@knotx/plugins-connection-line` is a connection line plugin for the KnotX framework that provides drag-and-drop connection functionality between nodes. Users can drag connection lines from node connection points to connect to other nodes or create new nodes in blank areas. It supports multi-selection simultaneous connections, custom connection line styles, and node creators.
+
+## Implementation Principles
+
+The plugin implements drag interaction through InteractJS:
+
+1. **Connection Point Recognition**: Automatically recognizes connection points (source/target) on nodes
+2. **Drag Handling**: Handles connection line drag interactions and visual feedback
+3. **Connection Creation**: Supports connecting to other nodes or creating new nodes in blank areas
+4. **Multi-selection Support**: Supports dragging connection lines from multiple selected nodes simultaneously
+5. **Custom Creators**: Supports registering custom node and edge creators
+
+## Dependencies
+
+This plugin depends on the following packages:
+
+- `@knotx/core` - Core functionality
+- `@knotx/decorators` - Decorator support
+- `@knotx/plugins-canvas` - Canvas plugin (peer dependency)
+- `@knotx/plugins-selection` - Selection plugin (peer dependency)
+- `@knotx/jsx` - JSX support (peer dependency)
+- `interactjs` - Interaction library (peer dependency)
+- `lodash-es` - Utility library
+- `rxjs` - Reactive programming
+
+## API Usage
+
+### Basic Usage
+
+```typescript
+import { ConnectionLine } from '@knotx/plugins-connection-line'
+
+// Create connection line plugin instance
+const connectionLine = new ConnectionLine()
+
+// Register plugin in engine
+engine.use(connectionLine)
+```
+
+### Configuration Options
+
+```typescript
+const connectionLine = new ConnectionLine().init({
+  allowCreateNodeOnBlankArea: true,
+  edgeType: 'bezier',
+  connectionLineClassName: 'custom-connection-line',
+  connectionLineSVGAttributes: {
+    stroke: '#2563eb',
+    strokeWidth: '2',
+    strokeDasharray: '5,5'
+  },
+  allowMultiDrag: true
+})
+```
+
+### Connection Point Attributes
+
+```tsx
+// Add connection points to nodes
+function ConnectableNode({ node }) {
+  const { getConnectHandleAttributes } = useKnotX().connectionLine
+
+  return (
+    <div>
+      <div>{node.data.label}</div>
+      <div
+        {...getConnectHandleAttributes({
+          nodeId: node.id,
+          type: 'source',
+          index: 0,
+          className: 'my-connect-handle'
+        })}
+        style={{
+          position: 'absolute',
+          right: -5,
+          top: '50%',
+          transform: 'translateY(-50%)',
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          backgroundColor: '#2563eb'
+        }}
+      />
+      <div
+        {...getConnectHandleAttributes({
+          nodeId: node.id,
+          type: 'target',
+          index: 0
+        })}
+        style={{
+          position: 'absolute',
+          left: -5,
+          top: '50%',
+          transform: 'translateY(-50%)',
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          backgroundColor: '#dc2626'
+        }}
+      />
+    </div>
+  )
+}
+```
+
+### Register Custom Creator
+
+```typescript
+// Register custom node and edge creator
+const unregister = connectionLine.registerCreator(({ sourceNodeIds, targetPosition }) => {
+  if (targetPosition) {
+    // Create new node in blank area
+    const newNode = {
+      id: generateId(),
+      type: 'default',
+      position: targetPosition,
+      data: { label: 'New Node' }
+    }
+
+    const newEdges = sourceNodeIds.map(sourceId => ({
+      id: generateId(),
+      type: 'bezier',
+      source: sourceId,
+      target: newNode.id
+    }))
+
+    return {
+      nodes: [newNode],
+      edges: newEdges
+    }
+  }
+
+  // Return undefined to use default creation logic
+  return undefined
+})
+
+// Unregister
+unregister()
+```
+
+### Complete Example
+
+```typescript
+import { Engine } from '@knotx/core'
+import { Canvas } from '@knotx/plugins-canvas'
+import { ConnectionLine } from '@knotx/plugins-connection-line'
+import { Selection } from '@knotx/plugins-selection'
+
+const engine = new Engine()
+
+// Register dependency plugins
+engine.use(new Canvas())
+engine.use(new Selection())
+
+// Register connection line plugin
+engine.use(new ConnectionLine().init({
+  allowCreateNodeOnBlankArea: true,
+  edgeType: 'bezier',
+  connectionLineClassName: 'custom-connection-line',
+  connectionLineSVGAttributes: {
+    stroke: '#2563eb',
+    strokeWidth: '2',
+    strokeDasharray: '5,5',
+    markerEnd: 'url(#arrowhead)'
+  },
+  allowMultiDrag: true
+}))
+
+// Register custom creator
+const connectionLinePlugin = engine.getPlugin('connectionLine')
+connectionLinePlugin.registerCreator(({ sourceNodeIds, targetPosition }) => {
+  // Custom creation logic
+  return {
+    nodes: [/* new nodes */],
+    edges: [/* new edges */]
+  }
+})
+```
+
+## Configuration Interface
+
+### ConnectionLineConfig
+
+```typescript
+interface ConnectionLineConfig {
+  /**
+   * Whether to allow connecting to blank canvas area and create new nodes
+   * @default false
+   */
+  allowCreateNodeOnBlankArea?: boolean
+  /**
+   * Type of newly created edges
+   * @default 'bezier'
+   */
+  edgeType?: string
+  /**
+   * Class name for temporary connection line
+   */
+  connectionLineClassName?: string
+  /**
+   * SVG attributes for temporary connection line
+   */
+  connectionLineSVGAttributes?: Record<string, string>
+  /**
+   * Whether to support dragging connection lines from multiple selected nodes simultaneously
+   * @default true
+   */
+  allowMultiDrag?: boolean
+}
+```
+
+### Plugin Data Interface
+
+```typescript
+declare module '@knotx/core' {
+  interface PluginData {
+    connectionLine: {
+      isDragging: boolean
+      registerCreator: (creator: (params: {
+        sourceNodeIds: string[]
+        targetPosition: { x: number, y: number } | undefined
+      }) => ({
+        nodes: Node[]
+        edges: Edge[]
+      }) | undefined | false) => () => void
+      getConnectHandleAttributes: (params: {
+        nodeId: string
+        type: 'source' | 'target'
+        index?: number
+        className?: string
+      }) => Record<string, string>
+    }
+  }
+}
+```
+
+## Interactive Features
+
+### Connection Line Dragging
+
+- Start dragging from node connection points
+- Real-time connection line preview
+- Support for multi-selection simultaneous connections
+- Automatic edge scrolling
+
+### Connection Target Recognition
+
+- Automatically recognizes valid connection targets
+- Connection point highlighting
+- Support for connecting to blank areas to create new nodes
+
+### Connection Line Styling
+
+- Support for custom connection line styles
+- Support for SVG attribute configuration
+- Support for custom CSS class names
+
+## File Directory Structure
+
+```
+packages/plugins-connection-line/
+├── src/
+│   ├── connection-line.tsx   # Connection line plugin main file
+│   └── index.ts             # Export file
+├── dist/                    # Build output directory
+├── CHANGELOG.md            # Change log
+├── package.json            # Package configuration
+├── build.config.ts         # Build configuration
+├── eslint.config.mjs       # ESLint configuration
+└── tsconfig.json           # TypeScript configuration
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,287 @@
+# @knotx/plugins-connection-line
+
+连接线插件，为节点间连接提供拖拽式连接线功能。
+
+## 安装
+
+```bash
+npm install @knotx/plugins-connection-line
+```
+
+## 基本概述
+
+`@knotx/plugins-connection-line` 是 KnotX 框架的连接线插件，提供节点间的拖拽式连接功能。用户可以从节点的连接点拖拽出连接线，连接到其他节点或空白区域创建新节点。支持多选节点同时连接、自定义连接线样式和节点创建器。
+
+## 实现原理
+
+该插件通过 InteractJS 实现拖拽交互：
+
+1. **连接点识别**：自动识别节点上的连接点（source/target）
+2. **拖拽处理**：处理连接线的拖拽交互和视觉反馈
+3. **连接创建**：支持连接到其他节点或空白区域创建新节点
+4. **多选支持**：支持从多个选中节点同时拖拽连接线
+5. **自定义创建器**：支持注册自定义的节点和边创建器
+
+## 依赖插件
+
+该插件依赖以下包：
+
+- `@knotx/core` - 核心功能
+- `@knotx/decorators` - 装饰器支持
+- `@knotx/plugins-canvas` - 画布插件（peer dependency）
+- `@knotx/plugins-selection` - 选择插件（peer dependency）
+- `@knotx/jsx` - JSX 支持（peer dependency）
+- `interactjs` - 交互库（peer dependency）
+- `lodash-es` - 工具库
+- `rxjs` - 响应式编程
+
+## API 使用
+
+### 基本使用
+
+```typescript
+import { ConnectionLine } from '@knotx/plugins-connection-line'
+
+// 创建连接线插件实例
+const connectionLine = new ConnectionLine()
+
+// 在引擎中注册插件
+engine.use(connectionLine)
+```
+
+### 配置选项
+
+```typescript
+const connectionLine = new ConnectionLine().init({
+  allowCreateNodeOnBlankArea: true,
+  edgeType: 'bezier',
+  connectionLineClassName: 'custom-connection-line',
+  connectionLineSVGAttributes: {
+    stroke: '#2563eb',
+    strokeWidth: '2',
+    strokeDasharray: '5,5'
+  },
+  allowMultiDrag: true
+})
+```
+
+### 连接点属性
+
+```tsx
+// 为节点添加连接点
+function ConnectableNode({ node }) {
+  const { getConnectHandleAttributes } = useKnotX().connectionLine
+
+  return (
+    <div>
+      <div>{node.data.label}</div>
+      <div
+        {...getConnectHandleAttributes({
+          nodeId: node.id,
+          type: 'source',
+          index: 0,
+          className: 'my-connect-handle'
+        })}
+        style={{
+          position: 'absolute',
+          right: -5,
+          top: '50%',
+          transform: 'translateY(-50%)',
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          backgroundColor: '#2563eb'
+        }}
+      />
+      <div
+        {...getConnectHandleAttributes({
+          nodeId: node.id,
+          type: 'target',
+          index: 0
+        })}
+        style={{
+          position: 'absolute',
+          left: -5,
+          top: '50%',
+          transform: 'translateY(-50%)',
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          backgroundColor: '#dc2626'
+        }}
+      />
+    </div>
+  )
+}
+```
+
+### 注册自定义创建器
+
+```typescript
+// 注册自定义节点和边创建器
+const unregister = connectionLine.registerCreator(({ sourceNodeIds, targetPosition }) => {
+  if (targetPosition) {
+    // 在空白区域创建新节点
+    const newNode = {
+      id: generateId(),
+      type: 'default',
+      position: targetPosition,
+      data: { label: '新节点' }
+    }
+
+    const newEdges = sourceNodeIds.map(sourceId => ({
+      id: generateId(),
+      type: 'bezier',
+      source: sourceId,
+      target: newNode.id
+    }))
+
+    return {
+      nodes: [newNode],
+      edges: newEdges
+    }
+  }
+
+  // 返回 undefined 使用默认创建逻辑
+  return undefined
+})
+
+// 取消注册
+unregister()
+```
+
+### 完整示例
+
+```typescript
+import { Engine } from '@knotx/core'
+import { Canvas } from '@knotx/plugins-canvas'
+import { ConnectionLine } from '@knotx/plugins-connection-line'
+import { Selection } from '@knotx/plugins-selection'
+
+const engine = new Engine()
+
+// 注册依赖插件
+engine.use(new Canvas())
+engine.use(new Selection())
+
+// 注册连接线插件
+engine.use(new ConnectionLine().init({
+  allowCreateNodeOnBlankArea: true,
+  edgeType: 'bezier',
+  connectionLineClassName: 'custom-connection-line',
+  connectionLineSVGAttributes: {
+    stroke: '#2563eb',
+    strokeWidth: '2',
+    strokeDasharray: '5,5',
+    markerEnd: 'url(#arrowhead)'
+  },
+  allowMultiDrag: true
+}))
+
+// 注册自定义创建器
+const connectionLinePlugin = engine.getPlugin('connectionLine')
+connectionLinePlugin.registerCreator(({ sourceNodeIds, targetPosition }) => {
+  // 自定义创建逻辑
+  return {
+    nodes: [/* 新节点 */],
+    edges: [/* 新边 */]
+  }
+})
+```
+
+## 配置接口
+
+### ConnectionLineConfig
+
+```typescript
+interface ConnectionLineConfig {
+  /**
+   * 是否允许连接到画布空白处并创建新节点
+   * @default false
+   */
+  allowCreateNodeOnBlankArea?: boolean
+  /**
+   * 新创建的边的类型
+   * @default 'bezier'
+   */
+  edgeType?: string
+  /**
+   * 临时连接线的类名
+   */
+  connectionLineClassName?: string
+  /**
+   * 临时连接线的SVG属性
+   */
+  connectionLineSVGAttributes?: Record<string, string>
+  /**
+   * 是否支持从多个选中节点同时拖拽连接线
+   * @default true
+   */
+  allowMultiDrag?: boolean
+}
+```
+
+### 插件数据接口
+
+```typescript
+declare module '@knotx/core' {
+  interface PluginData {
+    connectionLine: {
+      isDragging: boolean
+      registerCreator: (creator: (params: {
+        sourceNodeIds: string[]
+        targetPosition: { x: number, y: number } | undefined
+      }) => ({
+        nodes: Node[]
+        edges: Edge[]
+      }) | undefined | false) => () => void
+      getConnectHandleAttributes: (params: {
+        nodeId: string
+        type: 'source' | 'target'
+        index?: number
+        className?: string
+      }) => Record<string, string>
+    }
+  }
+}
+```
+
+## 交互功能
+
+### 连接线拖拽
+
+- 从节点连接点开始拖拽
+- 实时显示连接线预览
+- 支持多选节点同时连接
+- 自动边缘滚动
+
+### 连接目标识别
+
+- 自动识别有效的连接目标
+- 连接点高亮显示
+- 支持连接到空白区域创建新节点
+
+### 连接线样式
+
+- 支持自定义连接线样式
+- 支持 SVG 属性配置
+- 支持自定义 CSS 类名
+
+## 文件目录结构
+
+```
+packages/plugins-connection-line/
+├── src/
+│   ├── connection-line.tsx   # 连接线插件主文件
+│   └── index.ts             # 导出文件
+├── dist/                    # 编译输出目录
+├── CHANGELOG.md            # 变更日志
+├── package.json            # 包配置
+├── build.config.ts         # 构建配置
+├── eslint.config.mjs       # ESLint 配置
+└── tsconfig.json           # TypeScript 配置
+```
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knotx/plugins-connection-line",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "Connectionline Plugin for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -33,15 +33,15 @@
     "@interactjs/modifiers": "^1.10.27",
     "@interactjs/types": "^1.10.27",
     "interactjs": "^1.10.27",
-    "@knotx/jsx": "0.4.12",
-    "@knotx/plugins-canvas": "0.4.12",
-    "@knotx/plugins-selection": "0.4.12"
+    "@knotx/jsx": "0.4.13",
+    "@knotx/plugins-canvas": "0.4.13",
+    "@knotx/plugins-selection": "0.4.13"
   },
   "dependencies": {
     "lodash-es": "^4.17.21",
     "rxjs": "^7.8.1",
-    "@knotx/core": "0.4.12",
-    "@knotx/decorators": "0.4.12"
+    "@knotx/core": "0.4.13",
+    "@knotx/decorators": "0.4.13"
   },
   "devDependencies": {
     "@interactjs/actions": "^1.10.27",
@@ -50,12 +50,12 @@
     "@interactjs/types": "^1.10.27",
     "@types/lodash-es": "^4.17.12",
     "interactjs": "^1.10.27",
-    "@knotx/build-config": "0.4.12",
-    "@knotx/eslint-config": "0.4.12",
-    "@knotx/jsx": "0.4.12",
-    "@knotx/plugins-canvas": "0.4.12",
-    "@knotx/plugins-selection": "0.4.12",
-    "@knotx/typescript-config": "0.4.12"
+    "@knotx/build-config": "0.4.13",
+    "@knotx/eslint-config": "0.4.13",
+    "@knotx/jsx": "0.4.13",
+    "@knotx/plugins-canvas": "0.4.13",
+    "@knotx/plugins-selection": "0.4.13",
+    "@knotx/typescript-config": "0.4.13"
   },
   "scripts": {
     "build": "unbuild",