@knotx/plugins-minimap 0.4.11 → 0.4.13

package/README.en.md

@@ -0,0 +1,406 @@
+# @knotx/plugins-minimap
+
+Minimap plugin that provides canvas navigation functionality for KnotX.
+
+## Installation
+
+```bash
+npm install @knotx/plugins-minimap
+```
+
+## Overview
+
+The Minimap plugin provides minimap functionality for KnotX, allowing users to quickly navigate in large canvases. This plugin is built on the `interactjs` library and provides zoom, pan, viewport control, and other features.
+
+## Implementation Principle
+
+The core implementation principles of the Minimap plugin:
+
+1. **Node Mapping**: Maps nodes on the canvas to the minimap scale
+2. **Viewport Synchronization**: Real-time synchronization of viewport state between main canvas and minimap
+3. **Interaction Control**: Supports dragging and clicking on the minimap for navigation
+4. **Zoom Control**: Provides zoom buttons and reset functionality
+
+## Dependencies
+
+### Core Dependencies
+- `@knotx/core`: Provides base plugin architecture
+- `@knotx/decorators`: Provides decorator support
+- `interactjs`: Provides interaction functionality
+- `@interactjs/actions`: InteractJS action modules
+- `@interactjs/core`: InteractJS core module
+- `@interactjs/modifiers`: InteractJS modifier modules
+- `@interactjs/types`: InteractJS type definitions
+- `rxjs`: Provides reactive programming support
+
+### Plugin Dependencies
+- `@knotx/plugins-canvas`: Retrieves canvas transform state and container information
+
+## API Documentation
+
+### Main Classes
+
+#### Minimap
+
+The main class of the Minimap plugin, extending `BasePlugin`.
+
+```typescript
+export class Minimap extends BasePlugin<'minimap', MinimapConfig> {
+  name = 'minimap' as const
+}
+```
+
+### Configuration Options
+
+#### MinimapConfig
+
+```typescript
+export interface MinimapConfig {
+  /** Minimap width */
+  width?: number
+  /** Minimap height */
+  height?: number
+  /** Node color */
+  nodeColor?: string | ((node: Node) => string)
+  /** Viewport area background color */
+  maskColor?: string
+  /** Viewport area border color */
+  viewBoxColor?: string
+  /** Show minimap control buttons */
+  showControls?: boolean
+  /** Whether zoomable */
+  zoomable?: boolean
+  /** Whether pannable */
+  pannable?: boolean
+  /** Padding from container */
+  padding?: number
+  /** Node border radius */
+  nodeBorderRadius?: number
+  /** Node stroke width */
+  nodeStrokeWidth?: number
+  /** Node stroke color */
+  nodeStrokeColor?: string | ((node: Node) => string)
+  /** Zoom step */
+  zoomStep?: number
+}
+```
+
+### Default Configuration
+
+```typescript
+const defaultProps: Required<Omit<MinimapConfig, 'nodeColor' | 'nodeStrokeColor'>> = {
+  width: 200,
+  height: 150,
+  maskColor: 'rgba(240, 240, 240, 0.6)',
+  viewBoxColor: '#4752E6',
+  showControls: true,
+  zoomable: true,
+  pannable: true,
+  padding: 12,
+  nodeBorderRadius: 2,
+  nodeStrokeWidth: 1,
+  zoomStep: 0.2,
+}
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { Minimap } from '@knotx/plugins-minimap'
+
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 200,
+      height: 150,
+    },
+  },
+})
+```
+
+### Custom Styling
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 250,
+      height: 180,
+      nodeColor: '#4A90E2',
+      maskColor: 'rgba(255, 255, 255, 0.8)',
+      viewBoxColor: '#FF6B6B',
+      nodeBorderRadius: 4,
+      nodeStrokeWidth: 2,
+      nodeStrokeColor: '#333',
+    },
+  },
+})
+```
+
+### Dynamic Node Colors
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      nodeColor: (node) => {
+        // Return different colors based on node type
+        switch (node.type) {
+          case 'start':
+            return '#4CAF50'
+          case 'end':
+            return '#F44336'
+          case 'process':
+            return '#2196F3'
+          default:
+            return '#9E9E9E'
+        }
+      },
+      nodeStrokeColor: (node) => {
+        return node.selected ? '#FF9800' : 'transparent'
+      },
+    },
+  },
+})
+```
+
+### Disable Control Buttons
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      showControls: false,
+      zoomable: false,
+      pannable: true,
+    },
+  },
+})
+```
+
+### Custom Size and Position
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 300,
+      height: 200,
+      padding: 20,
+      zoomStep: 0.3,
+    },
+  },
+})
+```
+
+## Advanced Features
+
+### Integration with Canvas Plugin
+
+```typescript
+import { Canvas } from '@knotx/plugins-canvas'
+import { Minimap } from '@knotx/plugins-minimap'
+
+const engine = new Engine({
+  plugins: [Canvas, Minimap],
+  pluginConfig: {
+    canvas: {
+      minScale: 0.1,
+      maxScale: 3,
+    },
+    minimap: {
+      width: 200,
+      height: 150,
+    },
+  },
+})
+```
+
+### Listening to Minimap Interactions
+
+```typescript
+class MinimapInteractionPlugin extends BasePlugin {
+  @inject.canvas.transform()
+  transform!: CanvasTransformState
+
+  @subscribe.canvas.transform()
+  onTransformChange(transform: CanvasTransformState) {
+    console.log('Canvas transform changed:', transform)
+    // Minimap will automatically sync transform state
+  }
+}
+```
+
+### Custom Minimap Behavior
+
+```typescript
+class CustomMinimapPlugin extends BasePlugin {
+  @inject.minimap.config()
+  minimapConfig!: MinimapConfig
+
+  @OnInit
+  init() {
+    // Dynamically adjust minimap configuration
+    this.minimapConfig.nodeColor = (node) => {
+      const isImportant = node.data?.important
+      return isImportant ? '#FF5722' : '#607D8B'
+    }
+  }
+}
+```
+
+## Style Customization
+
+### CSS Class Names
+
+The minimap provides the following CSS class names for style customization:
+
+```css
+.knotx-minimap {
+  /* Minimap container */
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  background: #fff;
+}
+
+.knotx-minimap__svg {
+  /* SVG container */
+  cursor: crosshair;
+}
+
+.knotx-minimap__controls {
+  /* Control buttons container */
+  display: flex;
+  gap: 4px;
+  margin-top: 8px;
+}
+
+.knotx-minimap__button {
+  /* Control buttons */
+  padding: 4px 8px;
+  border: 1px solid #ccc;
+  background: #f5f5f5;
+  cursor: pointer;
+}
+
+.knotx-minimap__button:hover {
+  background: #e0e0e0;
+}
+
+.knotx-minimap__button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+### Custom Style Example
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 200,
+      height: 150,
+      // Custom viewport color
+      viewBoxColor: '#FF6B6B',
+      // Custom mask color
+      maskColor: 'rgba(255, 107, 107, 0.1)',
+    },
+  },
+})
+```
+
+## Performance Optimization
+
+### Node Rendering Optimization
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      // Use fixed color to avoid function call overhead
+      nodeColor: '#4A90E2',
+      nodeStrokeColor: 'transparent',
+      // Reduce border radius for better rendering performance
+      nodeBorderRadius: 0,
+    },
+  },
+})
+```
+
+### Interaction Optimization
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      // Smaller zoom step for smoother experience
+      zoomStep: 0.1,
+      // Appropriate size balancing performance and usability
+      width: 180,
+      height: 120,
+    },
+  },
+})
+```
+
+## File Directory Structure
+
+```
+packages/plugins-minimap/
+├── src/
+│   ├── minimap.tsx             # Main implementation file
+│   └── index.ts               # Export file
+├── dist/                      # Build output directory
+├── package.json              # Package configuration
+├── build.config.ts           # Build configuration
+├── tsconfig.json             # TypeScript configuration
+├── eslint.config.mjs         # ESLint configuration
+└── CHANGELOG.md              # Changelog
+```
+
+### Core Files Description
+
+- **minimap.tsx**: Contains the main implementation of the Minimap plugin, including node mapping, viewport synchronization, and interaction control
+- **index.ts**: Exports the Minimap class and related type definitions
+
+## Best Practices
+
+### User Experience
+
+1. **Appropriate Size**: Choose suitable minimap size based on application layout
+2. **Clear Visual Feedback**: Use high-contrast colors to distinguish different elements
+3. **Smooth Interactions**: Configure zoom steps and animation effects appropriately
+
+### Performance Optimization
+
+1. **Fixed Colors**: Use fixed colors instead of dynamic functions for large numbers of nodes
+2. **Simplified Styles**: Reduce unnecessary visual effects to improve rendering performance
+3. **Reasonable Size**: Adjust minimap size based on node count
+
+### Development and Debugging
+
+1. **Monitor State Changes**: Listen to transform state changes during development
+2. **Test Interactions**: Ensure proper synchronization between minimap and main canvas
+3. **Verify Boundaries**: Test extreme zoom and pan scenarios
+
+## Notes
+
+1. **Dependencies**: Ensure Canvas plugin is loaded before Minimap plugin
+2. **Performance Considerations**: With many nodes, minimap rendering may impact performance
+3. **Responsive Design**: Consider minimap display on different screen sizes
+4. **Browser Compatibility**: Depends on SVG and modern JavaScript features
+
+## License
+
+MIT

package/README.md

@@ -1,11 +1,406 @@
-Install
+# @knotx/plugins-minimap
+
+小地图插件，为 KnotX 提供画布导航功能。
+
+## 安装
 
 ```bash
-pnpm add interactjs @knotx/plugins-canvas @knotx/core @knotx/decorators @knotx/utils
+npm install @knotx/plugins-minimap
+```
+
+## 概述
+
+Minimap 插件为 KnotX 提供了小地图功能，允许用户在大型画布中快速导航。该插件基于 `interactjs` 库实现，提供了缩放、平移、视窗控制等功能。
+
+## 实现原理
+
+Minimap 插件的核心实现原理：
+
+1. **节点映射**：将画布上的节点映射到小地图的比例尺中
+2. **视窗同步**：实时同步主画布和小地图的视窗状态
+3. **交互控制**：支持在小地图上拖拽和点击进行导航
+4. **缩放控制**：提供缩放按钮和重置功能
+
+## 依赖关系
+
+### 核心依赖
+- `@knotx/core`：提供基础插件架构
+- `@knotx/decorators`：提供装饰器支持
+- `interactjs`：提供交互功能
+- `@interactjs/actions`：InteractJS 动作模块
+- `@interactjs/core`：InteractJS 核心模块
+- `@interactjs/modifiers`：InteractJS 修饰器模块
+- `@interactjs/types`：InteractJS 类型定义
+- `rxjs`：提供响应式编程支持
+
+### 插件依赖
+- `@knotx/plugins-canvas`：获取画布变换状态和容器信息
+
+## API 文档
+
+### 主要类
+
+#### Minimap
+
+小地图插件的主要类，继承自 `BasePlugin`。
+
+```typescript
+export class Minimap extends BasePlugin<'minimap', MinimapConfig> {
+  name = 'minimap' as const
+}
+```
+
+### 配置选项
+
+#### MinimapConfig
+
+```typescript
+export interface MinimapConfig {
+  /** 小地图宽度 */
+  width?: number
+  /** 小地图高度 */
+  height?: number
+  /** 节点颜色 */
+  nodeColor?: string | ((node: Node) => string)
+  /** 视图区域背景颜色 */
+  maskColor?: string
+  /** 视图区域边框颜色 */
+  viewBoxColor?: string
+  /** 显示小地图控制按钮 */
+  showControls?: boolean
+  /** 是否可缩放 */
+  zoomable?: boolean
+  /** 是否可平移 */
+  pannable?: boolean
+  /** 与容器的内边距 */
+  padding?: number
+  /** 节点圆角 */
+  nodeBorderRadius?: number
+  /** 节点描边宽度 */
+  nodeStrokeWidth?: number
+  /** 节点描边颜色 */
+  nodeStrokeColor?: string | ((node: Node) => string)
+  /** 缩放步长 */
+  zoomStep?: number
+}
+```
+
+### 默认配置
+
+```typescript
+const defaultProps: Required<Omit<MinimapConfig, 'nodeColor' | 'nodeStrokeColor'>> = {
+  width: 200,
+  height: 150,
+  maskColor: 'rgba(240, 240, 240, 0.6)',
+  viewBoxColor: '#4752E6',
+  showControls: true,
+  zoomable: true,
+  pannable: true,
+  padding: 12,
+  nodeBorderRadius: 2,
+  nodeStrokeWidth: 1,
+  zoomStep: 0.2,
+}
+```
+
+## 使用示例
+
+### 基本用法
+
+```typescript
+import { Minimap } from '@knotx/plugins-minimap'
+
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 200,
+      height: 150,
+    },
+  },
+})
+```
+
+### 自定义样式
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 250,
+      height: 180,
+      nodeColor: '#4A90E2',
+      maskColor: 'rgba(255, 255, 255, 0.8)',
+      viewBoxColor: '#FF6B6B',
+      nodeBorderRadius: 4,
+      nodeStrokeWidth: 2,
+      nodeStrokeColor: '#333',
+    },
+  },
+})
+```
+
+### 动态节点颜色
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      nodeColor: (node) => {
+        // 根据节点类型返回不同颜色
+        switch (node.type) {
+          case 'start':
+            return '#4CAF50'
+          case 'end':
+            return '#F44336'
+          case 'process':
+            return '#2196F3'
+          default:
+            return '#9E9E9E'
+        }
+      },
+      nodeStrokeColor: (node) => {
+        return node.selected ? '#FF9800' : 'transparent'
+      },
+    },
+  },
+})
+```
+
+### 禁用控制按钮
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      showControls: false,
+      zoomable: false,
+      pannable: true,
+    },
+  },
+})
 ```
 
-Usage
+### 自定义尺寸和位置
 
-```tsx
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 300,
+      height: 200,
+      padding: 20,
+      zoomStep: 0.3,
+    },
+  },
+})
+```
+
+## 高级功能
+
+### 与 Canvas 插件集成
+
+```typescript
+import { Canvas } from '@knotx/plugins-canvas'
 import { Minimap } from '@knotx/plugins-minimap'
+
+const engine = new Engine({
+  plugins: [Canvas, Minimap],
+  pluginConfig: {
+    canvas: {
+      minScale: 0.1,
+      maxScale: 3,
+    },
+    minimap: {
+      width: 200,
+      height: 150,
+    },
+  },
+})
+```
+
+### 监听小地图交互
+
+```typescript
+class MinimapInteractionPlugin extends BasePlugin {
+  @inject.canvas.transform()
+  transform!: CanvasTransformState
+
+  @subscribe.canvas.transform()
+  onTransformChange(transform: CanvasTransformState) {
+    console.log('Canvas transform changed:', transform)
+    // 小地图会自动同步变换状态
+  }
+}
+```
+
+### 自定义小地图行为
+
+```typescript
+class CustomMinimapPlugin extends BasePlugin {
+  @inject.minimap.config()
+  minimapConfig!: MinimapConfig
+
+  @OnInit
+  init() {
+    // 动态调整小地图配置
+    this.minimapConfig.nodeColor = (node) => {
+      const isImportant = node.data?.important
+      return isImportant ? '#FF5722' : '#607D8B'
+    }
+  }
+}
+```
+
+## 样式自定义
+
+### CSS 类名
+
+小地图提供了以下 CSS 类名用于样式自定义：
+
+```css
+.knotx-minimap {
+  /* 小地图容器 */
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  background: #fff;
+}
+
+.knotx-minimap__svg {
+  /* SVG 容器 */
+  cursor: crosshair;
+}
+
+.knotx-minimap__controls {
+  /* 控制按钮容器 */
+  display: flex;
+  gap: 4px;
+  margin-top: 8px;
+}
+
+.knotx-minimap__button {
+  /* 控制按钮 */
+  padding: 4px 8px;
+  border: 1px solid #ccc;
+  background: #f5f5f5;
+  cursor: pointer;
+}
+
+.knotx-minimap__button:hover {
+  background: #e0e0e0;
+}
+
+.knotx-minimap__button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+### 自定义样式示例
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      width: 200,
+      height: 150,
+      // 自定义视窗颜色
+      viewBoxColor: '#FF6B6B',
+      // 自定义蒙版颜色
+      maskColor: 'rgba(255, 107, 107, 0.1)',
+    },
+  },
+})
+```
+
+## 性能优化
+
+### 节点渲染优化
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      // 使用固定颜色避免函数调用开销
+      nodeColor: '#4A90E2',
+      nodeStrokeColor: 'transparent',
+      // 减少圆角以提高渲染性能
+      nodeBorderRadius: 0,
+    },
+  },
+})
+```
+
+### 交互优化
+
+```typescript
+const engine = new Engine({
+  plugins: [Minimap],
+  pluginConfig: {
+    minimap: {
+      // 较小的缩放步长提供更平滑的体验
+      zoomStep: 0.1,
+      // 合适的尺寸平衡性能和可用性
+      width: 180,
+      height: 120,
+    },
+  },
+})
 ```
+
+## 文件目录结构
+
+```
+packages/plugins-minimap/
+├── src/
+│   ├── minimap.tsx             # 主要实现文件
+│   └── index.ts               # 导出文件
+├── dist/                      # 构建输出目录
+├── package.json              # 包配置文件
+├── build.config.ts           # 构建配置
+├── tsconfig.json             # TypeScript 配置
+├── eslint.config.mjs         # ESLint 配置
+└── CHANGELOG.md              # 更新日志
+```
+
+### 核心文件说明
+
+- **minimap.tsx**：包含 Minimap 插件的主要实现，包括节点映射、视窗同步和交互控制
+- **index.ts**：导出 Minimap 类和相关类型定义
+
+## 最佳实践
+
+### 用户体验
+
+1. **合适的尺寸**：根据应用布局选择合适的小地图尺寸
+2. **清晰的视觉反馈**：使用对比度高的颜色区分不同元素
+3. **平滑的交互**：合理配置缩放步长和动画效果
+
+### 性能优化
+
+1. **固定颜色**：对于大量节点，使用固定颜色而非动态函数
+2. **简化样式**：减少不必要的视觉效果以提高渲染性能
+3. **合理尺寸**：根据节点数量调整小地图尺寸
+
+### 开发调试
+
+1. **监听状态变化**：在开发阶段监听变换状态变化
+2. **测试交互**：确保小地图与主画布的同步正常
+3. **验证边界**：测试极端缩放和平移情况
+
+## 注意事项
+
+1. **依赖关系**：确保 Canvas 插件在 Minimap 插件之前加载
+2. **性能考虑**：大量节点时，小地图的渲染可能影响性能
+3. **响应式设计**：考虑在不同屏幕尺寸下的小地图显示
+4. **浏览器兼容性**：依赖 SVG 和现代 JavaScript 特性
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knotx/plugins-minimap",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Minimap Plugin for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -29,8 +29,8 @@
   ],
   "peerDependencies": {
     "interactjs": "^1.10.27",
-    "@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/modifiers": "^1.10.27",
     "@interactjs/types": "^1.10.27",
     "rxjs": "^7.8.1",
-    "@knotx/core": "0.4.11",
-    "@knotx/decorators": "0.4.11"
+    "@knotx/core": "0.4.13",
+    "@knotx/decorators": "0.4.13"
   },
   "devDependencies": {
     "interactjs": "^1.10.27",
-    "@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",