@knotx/plugins-group 0.4.12 → 0.4.13

package/README.en.md

@@ -0,0 +1,288 @@
+# @knotx/plugins-group
+
+Group plugin that provides node grouping management functionality.
+
+## Installation
+
+```bash
+npm install @knotx/plugins-group
+```
+
+## Overview
+
+`@knotx/plugins-group` is a grouping plugin for the KnotX framework that provides node grouping management functionality. It supports creating, dissolving, and deleting groups, as well as adding or removing nodes from groups. Group nodes can automatically calculate boundaries and support layered rendering and style customization.
+
+## Implementation Principles
+
+The plugin implements grouping functionality through bidirectional relationship management:
+
+1. **Group Relationship Management**: Uses `DualRelation` to maintain parent-child node relationships
+2. **Boundary Calculation**: Automatically calculates group boundaries with support for custom padding
+3. **Layered Rendering**: Integrates node level getter to ensure group nodes are rendered at the correct level
+4. **Operation Pipeline**: Handles group-related node operations through operation pipeline
+
+## Dependencies
+
+This plugin depends on the following packages:
+
+- `@knotx/core` - Core functionality
+- `@knotx/decorators` - Decorator support
+- `@knotx/plugins-base-render` - Base render plugin (peer dependency)
+- `@knotx/jsx` - JSX support (peer dependency)
+- `rxjs` - Reactive programming
+
+## API Usage
+
+### Basic Usage
+
+```typescript
+import { Group } from '@knotx/plugins-group'
+
+// Create group plugin instance
+const group = new Group()
+
+// Register plugin in engine
+engine.use(group)
+```
+
+### Create Group
+
+```typescript
+const { createGroup } = useKnotX().group
+
+// Create basic group
+const groupId = createGroup({
+  id: 'group-1',
+  nodeIds: ['node-1', 'node-2', 'node-3'],
+  data: { label: 'My Group' }
+})
+
+// Create group with configuration
+const groupId = createGroup({
+  id: 'group-2',
+  nodeIds: ['node-4', 'node-5'],
+  config: {
+    autoBounds: true,
+    padding: 20,
+    style: {
+      backgroundColor: 'rgba(59, 130, 246, 0.1)',
+      borderColor: '#3b82f6',
+      borderWidth: 2,
+      borderStyle: 'dashed',
+      borderRadius: 8
+    }
+  },
+  data: { label: 'Custom Group' }
+})
+```
+
+### Group Operations
+
+```typescript
+const { dissolveGroup, deleteGroup, addNodesToGroup, removeNodesFromGroup, moveGroup } = useKnotX().group
+
+// Dissolve group
+dissolveGroup('group-1')
+
+// Delete group
+deleteGroup('group-1')
+
+// Add nodes to group
+addNodesToGroup('group-1', ['node-6', 'node-7'])
+
+// Remove nodes from group
+removeNodesFromGroup('group-1', ['node-1'])
+
+// Move group
+moveGroup('group-1', { x: 100, y: 100 })
+
+// Move group with delta
+moveGroup('group-1', { x: 50, y: 50 }, true)
+```
+
+### Complete Example
+
+```typescript
+import { Engine } from '@knotx/core'
+import { BaseRender } from '@knotx/plugins-base-render'
+import { Group } from '@knotx/plugins-group'
+
+const engine = new Engine()
+
+// Register dependency plugins
+engine.use(new BaseRender())
+
+// Register group plugin
+engine.use(new Group())
+
+// Create nodes
+engine.dispatchNodeOperation({
+  type: 'batch',
+  operations: [
+    { type: 'add', node: { id: 'node-1', type: 'default', position: { x: 100, y: 100 }, data: { label: 'Node 1' } } },
+    { type: 'add', node: { id: 'node-2', type: 'default', position: { x: 200, y: 100 }, data: { label: 'Node 2' } } },
+    { type: 'add', node: { id: 'node-3', type: 'default', position: { x: 150, y: 200 }, data: { label: 'Node 3' } } }
+  ]
+})
+
+// Create group
+const groupPlugin = engine.getPlugin('group')
+const groupId = groupPlugin.createGroup({
+  id: 'my-group',
+  nodeIds: ['node-1', 'node-2', 'node-3'],
+  config: {
+    autoBounds: true,
+    padding: 15,
+    style: {
+      backgroundColor: 'rgba(34, 197, 94, 0.1)',
+      borderColor: '#22c55e',
+      borderWidth: 1,
+      borderStyle: 'solid',
+      borderRadius: 6
+    }
+  },
+  data: { label: 'My Group' }
+})
+```
+
+## Configuration Interface
+
+### GroupConfig
+
+```typescript
+interface GroupConfig {
+  /**
+   * Whether to automatically calculate boundaries
+   * @default true
+   */
+  autoBounds?: boolean
+  /**
+   * Padding
+   * @default 10
+   */
+  padding?: number
+  /**
+   * Group style
+   */
+  style?: GroupStyle
+}
+```
+
+### GroupStyle
+
+```typescript
+interface GroupStyle {
+  /**
+   * Background color
+   */
+  backgroundColor?: string
+  /**
+   * Border color
+   */
+  borderColor?: string
+  /**
+   * Border width
+   */
+  borderWidth?: number
+  /**
+   * Border style
+   */
+  borderStyle?: string
+  /**
+   * Border radius
+   */
+  borderRadius?: number
+}
+```
+
+### GroupAPI
+
+```typescript
+interface GroupAPI {
+  createGroup: (params: {
+    id: string
+    nodeIds: string[]
+    config?: GroupConfig
+    data?: Record<string, any>
+  }) => string
+  dissolveGroup: (groupId: string, recursive?: boolean) => boolean
+  deleteGroup: (groupId: string) => boolean
+  addNodesToGroup: (groupId: string, nodeIds: string[]) => boolean
+  removeNodesFromGroup: (groupId: string, nodeIds: string[]) => boolean
+  moveGroup: (groupId: string, position: NodePosition, isDelta?: boolean) => boolean
+}
+```
+
+## Node Type Extension
+
+```typescript
+declare module '@knotx/core' {
+  interface Node {
+    /**
+     * The group this node belongs to
+     */
+    group?: string
+    /**
+     * Current group configuration when type='group'
+     */
+    groupConfig?: GroupConfig
+  }
+}
+```
+
+## Default Configuration
+
+```typescript
+const DEFAULT_GROUP_PADDING = 10
+const DEFAULT_GROUP_STYLE = {
+  backgroundColor: 'rgba(100, 100, 100, 0.1)',
+  borderColor: '#666',
+  borderWidth: 1,
+  borderStyle: 'solid',
+  borderRadius: 4
+}
+```
+
+## Group Rendering
+
+The plugin provides a default group renderer that supports:
+
+- Automatic boundary calculation
+- Custom styling
+- Recursive group support
+- Layered rendering
+
+```tsx
+// Group nodes automatically use 'group' type
+function GroupNode({ node }) {
+  // Automatically render group boundaries and styles
+  return <div className="group-node">{/* group content */}</div>
+}
+```
+
+## Level Management
+
+The plugin automatically integrates level management functionality:
+
+- Group nodes are rendered behind child nodes
+- Supports correct levels for nested groups
+- Automatically calculates node levels
+
+## File Directory Structure
+
+```
+packages/plugins-group/
+├── src/
+│   ├── group.tsx            # Group 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,288 @@
+# @knotx/plugins-group
+
+分组插件，提供节点分组管理功能。
+
+## 安装
+
+```bash
+npm install @knotx/plugins-group
+```
+
+## 基本概述
+
+`@knotx/plugins-group` 是 KnotX 框架的分组插件，提供节点分组管理功能。支持创建、解散、删除分组，以及向分组中添加或移除节点。分组节点可以自动计算边界，支持分层渲染和样式定制。
+
+## 实现原理
+
+该插件通过双向关系管理实现分组功能：
+
+1. **分组关系管理**：使用 `DualRelation` 维护父子节点关系
+2. **边界计算**：自动计算分组边界并支持自定义内边距
+3. **分层渲染**：集成节点层级获取器，确保分组节点在正确的层级渲染
+4. **操作管道**：通过操作管道处理分组相关的节点操作
+
+## 依赖插件
+
+该插件依赖以下包：
+
+- `@knotx/core` - 核心功能
+- `@knotx/decorators` - 装饰器支持
+- `@knotx/plugins-base-render` - 基础渲染插件（peer dependency）
+- `@knotx/jsx` - JSX 支持（peer dependency）
+- `rxjs` - 响应式编程
+
+## API 使用
+
+### 基本使用
+
+```typescript
+import { Group } from '@knotx/plugins-group'
+
+// 创建分组插件实例
+const group = new Group()
+
+// 在引擎中注册插件
+engine.use(group)
+```
+
+### 创建分组
+
+```typescript
+const { createGroup } = useKnotX().group
+
+// 创建基础分组
+const groupId = createGroup({
+  id: 'group-1',
+  nodeIds: ['node-1', 'node-2', 'node-3'],
+  data: { label: '我的分组' }
+})
+
+// 创建带配置的分组
+const groupId = createGroup({
+  id: 'group-2',
+  nodeIds: ['node-4', 'node-5'],
+  config: {
+    autoBounds: true,
+    padding: 20,
+    style: {
+      backgroundColor: 'rgba(59, 130, 246, 0.1)',
+      borderColor: '#3b82f6',
+      borderWidth: 2,
+      borderStyle: 'dashed',
+      borderRadius: 8
+    }
+  },
+  data: { label: '自定义分组' }
+})
+```
+
+### 分组操作
+
+```typescript
+const { dissolveGroup, deleteGroup, addNodesToGroup, removeNodesFromGroup, moveGroup } = useKnotX().group
+
+// 解散分组
+dissolveGroup('group-1')
+
+// 删除分组
+deleteGroup('group-1')
+
+// 向分组添加节点
+addNodesToGroup('group-1', ['node-6', 'node-7'])
+
+// 从分组移除节点
+removeNodesFromGroup('group-1', ['node-1'])
+
+// 移动分组
+moveGroup('group-1', { x: 100, y: 100 })
+
+// 增量移动分组
+moveGroup('group-1', { x: 50, y: 50 }, true)
+```
+
+### 完整示例
+
+```typescript
+import { Engine } from '@knotx/core'
+import { BaseRender } from '@knotx/plugins-base-render'
+import { Group } from '@knotx/plugins-group'
+
+const engine = new Engine()
+
+// 注册依赖插件
+engine.use(new BaseRender())
+
+// 注册分组插件
+engine.use(new Group())
+
+// 创建节点
+engine.dispatchNodeOperation({
+  type: 'batch',
+  operations: [
+    { type: 'add', node: { id: 'node-1', type: 'default', position: { x: 100, y: 100 }, data: { label: '节点1' } } },
+    { type: 'add', node: { id: 'node-2', type: 'default', position: { x: 200, y: 100 }, data: { label: '节点2' } } },
+    { type: 'add', node: { id: 'node-3', type: 'default', position: { x: 150, y: 200 }, data: { label: '节点3' } } }
+  ]
+})
+
+// 创建分组
+const groupPlugin = engine.getPlugin('group')
+const groupId = groupPlugin.createGroup({
+  id: 'my-group',
+  nodeIds: ['node-1', 'node-2', 'node-3'],
+  config: {
+    autoBounds: true,
+    padding: 15,
+    style: {
+      backgroundColor: 'rgba(34, 197, 94, 0.1)',
+      borderColor: '#22c55e',
+      borderWidth: 1,
+      borderStyle: 'solid',
+      borderRadius: 6
+    }
+  },
+  data: { label: '我的分组' }
+})
+```
+
+## 配置接口
+
+### GroupConfig
+
+```typescript
+interface GroupConfig {
+  /**
+   * 是否自动计算边界
+   * @default true
+   */
+  autoBounds?: boolean
+  /**
+   * 内边距
+   * @default 10
+   */
+  padding?: number
+  /**
+   * 分组样式
+   */
+  style?: GroupStyle
+}
+```
+
+### GroupStyle
+
+```typescript
+interface GroupStyle {
+  /**
+   * 背景颜色
+   */
+  backgroundColor?: string
+  /**
+   * 边框颜色
+   */
+  borderColor?: string
+  /**
+   * 边框宽度
+   */
+  borderWidth?: number
+  /**
+   * 边框样式
+   */
+  borderStyle?: string
+  /**
+   * 边框圆角
+   */
+  borderRadius?: number
+}
+```
+
+### GroupAPI
+
+```typescript
+interface GroupAPI {
+  createGroup: (params: {
+    id: string
+    nodeIds: string[]
+    config?: GroupConfig
+    data?: Record<string, any>
+  }) => string
+  dissolveGroup: (groupId: string, recursive?: boolean) => boolean
+  deleteGroup: (groupId: string) => boolean
+  addNodesToGroup: (groupId: string, nodeIds: string[]) => boolean
+  removeNodesFromGroup: (groupId: string, nodeIds: string[]) => boolean
+  moveGroup: (groupId: string, position: NodePosition, isDelta?: boolean) => boolean
+}
+```
+
+## 节点类型扩展
+
+```typescript
+declare module '@knotx/core' {
+  interface Node {
+    /**
+     * 所处的组
+     */
+    group?: string
+    /**
+     * type='group' 时，当前组配置
+     */
+    groupConfig?: GroupConfig
+  }
+}
+```
+
+## 默认配置
+
+```typescript
+const DEFAULT_GROUP_PADDING = 10
+const DEFAULT_GROUP_STYLE = {
+  backgroundColor: 'rgba(100, 100, 100, 0.1)',
+  borderColor: '#666',
+  borderWidth: 1,
+  borderStyle: 'solid',
+  borderRadius: 4
+}
+```
+
+## 分组渲染
+
+插件提供了默认的分组渲染器，支持：
+
+- 自动边界计算
+- 自定义样式
+- 递归分组支持
+- 分层渲染
+
+```tsx
+// 分组节点会自动使用 'group' 类型
+function GroupNode({ node }) {
+  // 自动渲染分组边界和样式
+  return <div className="group-node">{/* 分组内容 */}</div>
+}
+```
+
+## 层级管理
+
+插件自动集成了层级管理功能：
+
+- 分组节点渲染在子节点后面
+- 支持嵌套分组的正确层级
+- 自动计算节点层级
+
+## 文件目录结构
+
+```
+packages/plugins-group/
+├── src/
+│   ├── group.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-group",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "Group Plugin for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -28,20 +28,20 @@
     "dist"
   ],
   "peerDependencies": {
-    "@knotx/jsx": "0.4.12",
-    "@knotx/plugins-base-render": "0.4.12"
+    "@knotx/jsx": "0.4.13",
+    "@knotx/plugins-base-render": "0.4.13"
   },
   "dependencies": {
     "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": {
-    "@knotx/build-config": "0.4.12",
-    "@knotx/eslint-config": "0.4.12",
-    "@knotx/jsx": "0.4.12",
-    "@knotx/plugins-base-render": "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-base-render": "0.4.13",
+    "@knotx/typescript-config": "0.4.13"
   },
   "scripts": {
     "build": "unbuild",