@knotx/plugins-bounding 0.4.11 → 0.4.13

package/README.en.md

@@ -0,0 +1,375 @@
+# @knotx/plugins-bounding
+
+Bounding plugin that provides resize and connection point functionality for nodes.
+
+## Installation
+
+```bash
+npm install @knotx/plugins-bounding
+```
+
+## Overview
+
+`@knotx/plugins-bounding` is a bounding plugin for the KnotX framework that provides resize and connection point functionality for nodes. It supports multiple resize handle positions, custom styles, minimum size constraints, and inertia effects.
+
+## Implementation Principles
+
+The plugin implements interactive functionality through InteractJS:
+
+1. **Resize Handles**: Provides draggable resize handles around nodes
+2. **Connection Points**: Provides connection points at node edges for inter-node connections
+3. **Bounding Box**: Shows bounding box for selected nodes
+4. **Interaction Handling**: Handles resize and connection drag interactions
+
+## Dependencies
+
+This plugin depends on the following packages:
+
+- `@knotx/core` - Core functionality
+- `@knotx/decorators` - Decorator support
+- `@knotx/plugins-canvas` - Canvas plugin (peer dependency)
+- `@knotx/jsx` - JSX support (peer dependency)
+- `@knotx/render` - Rendering utilities
+- `interactjs` - Interaction library
+- `rxjs` - Reactive programming
+
+## API Usage
+
+### Basic Usage
+
+```typescript
+import { Bounding } from '@knotx/plugins-bounding'
+
+// Create bounding plugin instance
+const bounding = new Bounding()
+
+// Register plugin in engine
+engine.use(bounding)
+```
+
+### Configuration Options
+
+```typescript
+const bounding = new Bounding().init({
+  features: {
+    resize: true,
+    connect: true,
+    boundingBox: true
+  },
+  sizes: {
+    resizeHandle: 6,
+    connectHandle: 8,
+    boundingBoxThreshold: 200
+  },
+  styles: {
+    resizeHandle: {
+      fill: '#3b82f6',
+      stroke: '#ffffff',
+      strokeWidth: 1
+    },
+    connectHandle: {
+      fill: '#10b981',
+      stroke: '#ffffff',
+      strokeWidth: 1,
+      shadowColor: '#000000',
+      shadowWidth: 1
+    },
+    boundingBox: {
+      stroke: '#3b82f6',
+      strokeWidth: 1
+    }
+  },
+  resize: {
+    minWidth: 50,
+    minHeight: 30,
+    inertia: false,
+    handles: ['top-left', 'top-right', 'bottom-left', 'bottom-right', 'left', 'right', 'top', 'bottom'],
+    nodesType: ['default', 'custom']
+  }
+})
+```
+
+### Custom Resize Handle Attributes
+
+```tsx
+const { getCustomResizeHandleAttributes } = useKnotX().bounding
+
+// Add resize handle to custom node
+function ResizableNode({ node }) {
+  return (
+    <div style={{ position: 'relative' }}>
+      <div>{node.data.label}</div>
+
+      {/* Bottom-right resize handle */}
+      <div
+        {...getCustomResizeHandleAttributes(node.id, 'bottom-right')}
+        style={{
+          position: 'absolute',
+          right: -3,
+          bottom: -3,
+          width: 6,
+          height: 6,
+          backgroundColor: '#3b82f6',
+          border: '1px solid #ffffff',
+          borderRadius: '50%',
+          cursor: 'nw-resize'
+        }}
+      />
+    </div>
+  )
+}
+```
+
+### Complete Example
+
+```typescript
+import { Engine } from '@knotx/core'
+import { Bounding } from '@knotx/plugins-bounding'
+import { Canvas } from '@knotx/plugins-canvas'
+
+const engine = new Engine()
+
+// Register dependency plugins
+engine.use(new Canvas())
+
+// Register bounding plugin
+engine.use(new Bounding().init({
+  features: {
+    resize: true,
+    connect: true,
+    boundingBox: true
+  },
+  sizes: {
+    resizeHandle: 8,
+    connectHandle: 10,
+    boundingBoxThreshold: 150
+  },
+  styles: {
+    resizeHandle: {
+      fill: '#ec4899',
+      stroke: '#ffffff',
+      strokeWidth: 2
+    },
+    connectHandle: {
+      fill: '#06b6d4',
+      stroke: '#ffffff',
+      strokeWidth: 2,
+      shadowColor: 'rgba(0, 0, 0, 0.2)',
+      shadowWidth: 2
+    },
+    boundingBox: {
+      stroke: '#ec4899',
+      strokeWidth: 2
+    }
+  },
+  resize: {
+    minWidth: 80,
+    minHeight: 50,
+    inertia: true,
+    handles: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
+    nodesType: ['default']
+  }
+}))
+
+// Create resizable node
+engine.dispatchNodeOperation({
+  type: 'add',
+  node: {
+    id: 'resizable-node',
+    type: 'default',
+    position: { x: 100, y: 100 },
+    measured: { width: 120, height: 80 },
+    data: { label: 'Resizable Node' }
+  }
+})
+```
+
+## Configuration Interface
+
+### BoundingConfig
+
+```typescript
+interface BoundingConfig {
+  // Feature switches
+  features?: {
+    resize?: boolean
+    connect?: boolean
+    boundingBox?: boolean
+  }
+  // Size configuration
+  sizes?: {
+    resizeHandle?: number
+    connectHandle?: number
+    boundingBoxThreshold?: number
+  }
+  // Style configuration
+  styles?: {
+    resizeHandle?: {
+      fill?: string
+      stroke?: string
+      strokeWidth?: number
+    }
+    connectHandle?: {
+      fill?: string
+      stroke?: string
+      strokeWidth?: number
+      shadowColor?: string
+      shadowWidth?: number
+    }
+    boundingBox?: {
+      stroke?: string
+      strokeWidth?: number
+    }
+  }
+  // Resize configuration
+  resize?: {
+    minWidth?: number
+    minHeight?: number
+    inertia?: boolean
+    handles?: ResizeHandlePosition[]
+    nodesType?: string[]
+  }
+}
+```
+
+### ResizeHandlePosition
+
+```typescript
+type ResizeHandlePosition =
+  | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  | 'left' | 'right' | 'top' | 'bottom'
+  | 'center'
+```
+
+### Plugin Data Interface
+
+```typescript
+declare module '@knotx/core' {
+  interface PluginData {
+    bounding: {
+      getCustomResizeHandleAttributes: (nodeId: string, position: ResizeHandlePosition) => Record<string, string>
+    }
+  }
+}
+```
+
+## Default Configuration
+
+```typescript
+const DEFAULT_RESIZE_HANDLES: ResizeHandlePosition[] = [
+  'top-left',
+  'top-right',
+  'bottom-left',
+  'bottom-right'
+]
+
+const DEFAULT_CONNECT_HANDLE_POSITIONS = [
+  { top: true },
+  { right: true },
+  { bottom: true },
+  { left: true }
+]
+
+const DEFAULT_CONFIG = {
+  features: {
+    resize: true,
+    connect: true,
+    boundingBox: true
+  },
+  sizes: {
+    resizeHandle: 6,
+    connectHandle: 8,
+    boundingBoxThreshold: 200
+  },
+  styles: {
+    resizeHandle: {
+      fill: '#3b82f6',
+      stroke: '#ffffff',
+      strokeWidth: 1
+    },
+    connectHandle: {
+      fill: '#10b981',
+      stroke: '#ffffff',
+      strokeWidth: 1,
+      shadowColor: '#000000',
+      shadowWidth: 1
+    },
+    boundingBox: {
+      stroke: '#3b82f6',
+      strokeWidth: 1
+    }
+  },
+  resize: {
+    minWidth: 50,
+    minHeight: 30,
+    inertia: false,
+    handles: DEFAULT_RESIZE_HANDLES,
+    nodesType: []
+  }
+}
+```
+
+## Interactive Features
+
+### Resize Functionality
+
+- **Multi-position Handles**: Supports resize handles in 8 directions
+- **Minimum Size**: Configurable minimum width and height for nodes
+- **Inertia Effect**: Support for enabling/disabling inertia effects
+- **Node Type Filtering**: Specify which node types can be resized
+
+### Connection Point Functionality
+
+- **Edge Connection Points**: Provides connection points at the four edges of nodes
+- **Custom Styling**: Support for custom connection point styles and shadow effects
+- **Dynamic Display**: Dynamically show/hide connection points based on interaction state
+
+### Bounding Box Functionality
+
+- **Selection Indicator**: Shows bounding box for selected nodes
+- **Size Threshold**: Only shows bounding box when node size exceeds threshold
+- **Custom Styling**: Support for custom bounding box styles
+
+## Event Handling
+
+### Resize Events
+
+```typescript
+interface ResizeEvent {
+  nodeId: string
+  startWidth: number
+  startHeight: number
+  startX: number
+  startY: number
+  position: string
+}
+```
+
+### Resize Data
+
+```typescript
+interface ResizeData {
+  nodeId: string
+  width: number
+  height: number
+}
+```
+
+## File Directory Structure
+
+```
+packages/plugins-bounding/
+├── src/
+│   ├── bounding.tsx         # Bounding 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,375 @@
+# @knotx/plugins-bounding
+
+边界框插件，为节点提供缩放和连接点功能。
+
+## 安装
+
+```bash
+npm install @knotx/plugins-bounding
+```
+
+## 基本概述
+
+`@knotx/plugins-bounding` 是 KnotX 框架的边界框插件，为节点提供缩放（resize）和连接点（connect handle）功能。支持多种缩放手柄位置、自定义样式、最小尺寸限制和惯性效果。
+
+## 实现原理
+
+该插件通过 InteractJS 实现交互功能：
+
+1. **缩放手柄**：在节点周围提供可拖拽的缩放手柄
+2. **连接点**：在节点边缘提供连接点，用于节点间连接
+3. **边界框**：为选中节点显示边界框
+4. **交互处理**：处理缩放和连接的拖拽交互
+
+## 依赖插件
+
+该插件依赖以下包：
+
+- `@knotx/core` - 核心功能
+- `@knotx/decorators` - 装饰器支持
+- `@knotx/plugins-canvas` - 画布插件（peer dependency）
+- `@knotx/jsx` - JSX 支持（peer dependency）
+- `@knotx/render` - 渲染工具
+- `interactjs` - 交互库
+- `rxjs` - 响应式编程
+
+## API 使用
+
+### 基本使用
+
+```typescript
+import { Bounding } from '@knotx/plugins-bounding'
+
+// 创建边界框插件实例
+const bounding = new Bounding()
+
+// 在引擎中注册插件
+engine.use(bounding)
+```
+
+### 配置选项
+
+```typescript
+const bounding = new Bounding().init({
+  features: {
+    resize: true,
+    connect: true,
+    boundingBox: true
+  },
+  sizes: {
+    resizeHandle: 6,
+    connectHandle: 8,
+    boundingBoxThreshold: 200
+  },
+  styles: {
+    resizeHandle: {
+      fill: '#3b82f6',
+      stroke: '#ffffff',
+      strokeWidth: 1
+    },
+    connectHandle: {
+      fill: '#10b981',
+      stroke: '#ffffff',
+      strokeWidth: 1,
+      shadowColor: '#000000',
+      shadowWidth: 1
+    },
+    boundingBox: {
+      stroke: '#3b82f6',
+      strokeWidth: 1
+    }
+  },
+  resize: {
+    minWidth: 50,
+    minHeight: 30,
+    inertia: false,
+    handles: ['top-left', 'top-right', 'bottom-left', 'bottom-right', 'left', 'right', 'top', 'bottom'],
+    nodesType: ['default', 'custom']
+  }
+})
+```
+
+### 自定义缩放手柄属性
+
+```tsx
+const { getCustomResizeHandleAttributes } = useKnotX().bounding
+
+// 为自定义节点添加缩放手柄
+function ResizableNode({ node }) {
+  return (
+    <div style={{ position: 'relative' }}>
+      <div>{node.data.label}</div>
+
+      {/* 右下角缩放手柄 */}
+      <div
+        {...getCustomResizeHandleAttributes(node.id, 'bottom-right')}
+        style={{
+          position: 'absolute',
+          right: -3,
+          bottom: -3,
+          width: 6,
+          height: 6,
+          backgroundColor: '#3b82f6',
+          border: '1px solid #ffffff',
+          borderRadius: '50%',
+          cursor: 'nw-resize'
+        }}
+      />
+    </div>
+  )
+}
+```
+
+### 完整示例
+
+```typescript
+import { Engine } from '@knotx/core'
+import { Bounding } from '@knotx/plugins-bounding'
+import { Canvas } from '@knotx/plugins-canvas'
+
+const engine = new Engine()
+
+// 注册依赖插件
+engine.use(new Canvas())
+
+// 注册边界框插件
+engine.use(new Bounding().init({
+  features: {
+    resize: true,
+    connect: true,
+    boundingBox: true
+  },
+  sizes: {
+    resizeHandle: 8,
+    connectHandle: 10,
+    boundingBoxThreshold: 150
+  },
+  styles: {
+    resizeHandle: {
+      fill: '#ec4899',
+      stroke: '#ffffff',
+      strokeWidth: 2
+    },
+    connectHandle: {
+      fill: '#06b6d4',
+      stroke: '#ffffff',
+      strokeWidth: 2,
+      shadowColor: 'rgba(0, 0, 0, 0.2)',
+      shadowWidth: 2
+    },
+    boundingBox: {
+      stroke: '#ec4899',
+      strokeWidth: 2
+    }
+  },
+  resize: {
+    minWidth: 80,
+    minHeight: 50,
+    inertia: true,
+    handles: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
+    nodesType: ['default']
+  }
+}))
+
+// 创建可缩放节点
+engine.dispatchNodeOperation({
+  type: 'add',
+  node: {
+    id: 'resizable-node',
+    type: 'default',
+    position: { x: 100, y: 100 },
+    measured: { width: 120, height: 80 },
+    data: { label: '可缩放节点' }
+  }
+})
+```
+
+## 配置接口
+
+### BoundingConfig
+
+```typescript
+interface BoundingConfig {
+  // 功能开关
+  features?: {
+    resize?: boolean
+    connect?: boolean
+    boundingBox?: boolean
+  }
+  // 尺寸配置
+  sizes?: {
+    resizeHandle?: number
+    connectHandle?: number
+    boundingBoxThreshold?: number
+  }
+  // 样式配置
+  styles?: {
+    resizeHandle?: {
+      fill?: string
+      stroke?: string
+      strokeWidth?: number
+    }
+    connectHandle?: {
+      fill?: string
+      stroke?: string
+      strokeWidth?: number
+      shadowColor?: string
+      shadowWidth?: number
+    }
+    boundingBox?: {
+      stroke?: string
+      strokeWidth?: number
+    }
+  }
+  // resize 配置
+  resize?: {
+    minWidth?: number
+    minHeight?: number
+    inertia?: boolean
+    handles?: ResizeHandlePosition[]
+    nodesType?: string[]
+  }
+}
+```
+
+### ResizeHandlePosition
+
+```typescript
+type ResizeHandlePosition =
+  | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  | 'left' | 'right' | 'top' | 'bottom'
+  | 'center'
+```
+
+### 插件数据接口
+
+```typescript
+declare module '@knotx/core' {
+  interface PluginData {
+    bounding: {
+      getCustomResizeHandleAttributes: (nodeId: string, position: ResizeHandlePosition) => Record<string, string>
+    }
+  }
+}
+```
+
+## 默认配置
+
+```typescript
+const DEFAULT_RESIZE_HANDLES: ResizeHandlePosition[] = [
+  'top-left',
+  'top-right',
+  'bottom-left',
+  'bottom-right'
+]
+
+const DEFAULT_CONNECT_HANDLE_POSITIONS = [
+  { top: true },
+  { right: true },
+  { bottom: true },
+  { left: true }
+]
+
+const DEFAULT_CONFIG = {
+  features: {
+    resize: true,
+    connect: true,
+    boundingBox: true
+  },
+  sizes: {
+    resizeHandle: 6,
+    connectHandle: 8,
+    boundingBoxThreshold: 200
+  },
+  styles: {
+    resizeHandle: {
+      fill: '#3b82f6',
+      stroke: '#ffffff',
+      strokeWidth: 1
+    },
+    connectHandle: {
+      fill: '#10b981',
+      stroke: '#ffffff',
+      strokeWidth: 1,
+      shadowColor: '#000000',
+      shadowWidth: 1
+    },
+    boundingBox: {
+      stroke: '#3b82f6',
+      strokeWidth: 1
+    }
+  },
+  resize: {
+    minWidth: 50,
+    minHeight: 30,
+    inertia: false,
+    handles: DEFAULT_RESIZE_HANDLES,
+    nodesType: []
+  }
+}
+```
+
+## 交互功能
+
+### 缩放功能
+
+- **多位置手柄**：支持 8 个方向的缩放手柄
+- **最小尺寸**：可配置节点的最小宽度和高度
+- **惯性效果**：支持启用/禁用惯性效果
+- **节点类型过滤**：可指定哪些节点类型可以缩放
+
+### 连接点功能
+
+- **边缘连接点**：在节点四个边缘提供连接点
+- **自定义样式**：支持自定义连接点的样式和阴影效果
+- **动态显示**：根据交互状态动态显示/隐藏连接点
+
+### 边界框功能
+
+- **选择指示**：为选中节点显示边界框
+- **尺寸阈值**：当节点尺寸超过阈值时才显示边界框
+- **自定义样式**：支持自定义边界框的样式
+
+## 事件处理
+
+### 缩放事件
+
+```typescript
+interface ResizeEvent {
+  nodeId: string
+  startWidth: number
+  startHeight: number
+  startX: number
+  startY: number
+  position: string
+}
+```
+
+### 缩放数据
+
+```typescript
+interface ResizeData {
+  nodeId: string
+  width: number
+  height: number
+}
+```
+
+## 文件目录结构
+
+```
+packages/plugins-bounding/
+├── src/
+│   ├── bounding.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-bounding",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Bounding Plugin for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -28,8 +28,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "@knotx/jsx": "0.4.11",
-    "@knotx/plugins-canvas": "0.4.11"
+    "@knotx/jsx": "0.4.13",
+    "@knotx/plugins-canvas": "0.4.13"
   },
   "dependencies": {
     "@interactjs/actions": "^1.10.27",
@@ -38,16 +38,16 @@
     "@interactjs/types": "^1.10.27",
     "interactjs": "^1.10.27",
     "rxjs": "^7.8.1",
-    "@knotx/core": "0.4.11",
-    "@knotx/decorators": "0.4.11",
-    "@knotx/render": "0.4.11"
+    "@knotx/core": "0.4.13",
+    "@knotx/decorators": "0.4.13",
+    "@knotx/render": "0.4.13"
   },
   "devDependencies": {
-    "@knotx/build-config": "0.4.11",
-    "@knotx/eslint-config": "0.4.11",
-    "@knotx/jsx": "0.4.11",
-    "@knotx/plugins-canvas": "0.4.11",
-    "@knotx/typescript-config": "0.4.11"
+    "@knotx/build-config": "0.4.13",
+    "@knotx/eslint-config": "0.4.13",
+    "@knotx/jsx": "0.4.13",
+    "@knotx/plugins-canvas": "0.4.13",
+    "@knotx/typescript-config": "0.4.13"
   },
   "scripts": {
     "build": "unbuild",