@knotx/plugins-history 0.4.12 → 0.4.13

package/README.en.md

@@ -0,0 +1,378 @@
+# @knotx/plugins-history
+
+History plugin that provides undo/redo functionality for KnotX.
+
+## Installation
+
+```bash
+npm install @knotx/plugins-history
+```
+
+## Overview
+
+The History plugin provides complete history management functionality for KnotX, including undo, redo, state tagging, and more. This plugin tracks all data changes and provides convenient history operation interfaces.
+
+## Implementation Principle
+
+The core implementation principles of the History plugin:
+
+1. **Operation Interception**: Intercepts all data manager operations and records states before and after changes
+2. **Buffering Mechanism**: Uses debouncing to batch operations and avoid frequent history record creation
+3. **Reverse Operations**: Generates reverse operations for each operation to enable undo functionality
+4. **State Tagging**: Supports tagging specific states for quick return to designated history points
+
+## Dependencies
+
+### Core Dependencies
+- `@knotx/core`: Provides base plugin architecture and data management
+- `@knotx/decorators`: Provides decorator support
+- `rxjs`: Provides reactive programming support
+
+### Automatic Dependencies
+- `nodesManager` and `edgesManager` from `@knotx/core`: Automatically registered to the history system
+
+## API Documentation
+
+### Main Classes
+
+#### History
+
+The main class of the History plugin, extending `BasePlugin`.
+
+```typescript
+export class History<T extends Record<string, IData> = Record<string, any>> extends BasePlugin<'history', HistoryConfig> {
+  name = 'history' as const
+}
+```
+
+### Configuration Options
+
+#### HistoryConfig
+
+```typescript
+export interface HistoryConfig {
+  /** Maximum number of history records */
+  maxHistory?: number
+  /** Debounce time (milliseconds) */
+  debounceTime?: number
+}
+```
+
+### Plugin Data (PluginData)
+
+The History plugin provides the following data:
+
+```typescript
+interface PluginData {
+  history: {
+    ref: IHistory
+    canUndo: boolean
+    canRedo: boolean
+    registerDataManager: (dataManager: DataManager<any>) => (() => void)
+  }
+}
+```
+
+### Interface Definitions
+
+#### IHistory
+
+```typescript
+export interface IHistory {
+  isUndoRedo: boolean
+  undo: () => void
+  redo: () => void
+  addTag: (tag: string) => void
+  removeTag: (tag: string) => void
+  toTag: (tag: string) => void
+  clearTags: () => void
+}
+```
+
+#### HistoryState
+
+```typescript
+export interface HistoryState<T extends Record<string, IData> = Record<string, any>> {
+  value: {
+    [key: string]: HistoryOperation<T>[]
+  }
+  timestamp: number
+}
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { History } from '@knotx/plugins-history'
+
+const engine = new Engine({
+  plugins: [History],
+  pluginConfig: {
+    history: {
+      maxHistory: 50,
+      debounceTime: 100,
+    },
+  },
+})
+```
+
+### Undo and Redo Operations
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+})
+
+const historyData = engine.getPluginData('history')
+
+// Undo operation
+if (historyData.canUndo) {
+  historyData.ref.undo()
+}
+
+// Redo operation
+if (historyData.canRedo) {
+  historyData.ref.redo()
+}
+```
+
+### Listening to History State
+
+```tsx
+class HistoryUIPlugin extends BasePlugin {
+  @inject.history.canUndo()
+  canUndo!: boolean
+
+  @inject.history.canRedo()
+  canRedo!: boolean
+
+  @inject.history.ref()
+  history!: IHistory
+
+  @panel('bottom')
+  render() {
+    return (
+      <div>
+        <button
+          disabled={!this.canUndo}
+          onClick={() => this.history.undo()}
+        >
+          Undo
+        </button>
+        <button
+          disabled={!this.canRedo}
+          onClick={() => this.history.redo()}
+        >
+          Redo
+        </button>
+      </div>
+    )
+  }
+}
+```
+
+### State Tagging Functionality
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+})
+
+const historyData = engine.getPluginData('history')
+
+// Tag current state
+historyData.ref.addTag('checkpoint-1')
+
+// After performing a series of operations...
+// Return to tagged state
+historyData.ref.toTag('checkpoint-1')
+
+// Remove tag
+historyData.ref.removeTag('checkpoint-1')
+
+// Clear all tags
+historyData.ref.clearTags()
+```
+
+### Custom Data Manager Integration
+
+```typescript
+class CustomDataManager extends DataManager<MyData> {
+  constructor() {
+    super('custom')
+  }
+}
+
+const engine = new Engine({
+  plugins: [History],
+})
+
+const historyData = engine.getPluginData('history')
+const customManager = new CustomDataManager()
+
+// Register custom data manager
+const unregister = historyData.registerDataManager(customManager)
+
+// Unregister
+unregister()
+```
+
+## Advanced Features
+
+### Batch Operation Optimization
+
+```typescript
+class BatchHistoryPlugin extends BasePlugin {
+  @inject.history.ref()
+  history!: IHistory
+
+  performBatchOperation() {
+    // Batch operations are automatically debounced
+    engine.dispatchNodeOperation({
+      type: 'add',
+      data: { id: 'node1', /* ... */ },
+    })
+
+    engine.dispatchNodeOperation({
+      type: 'add',
+      data: { id: 'node2', /* ... */ },
+    })
+
+    // These operations will be merged into a single history entry
+  }
+}
+```
+
+### Conditional History Recording
+
+```typescript
+class ConditionalHistoryPlugin extends BasePlugin {
+  @inject.history.ref()
+  history!: IHistory
+
+  @inject.nodesManager()
+  nodesManager!: DataManager<Node>
+
+  performTemporaryOperation() {
+    // Check if in undo/redo process
+    if (this.history.isUndoRedo) {
+      // Avoid creating new history records during undo/redo
+      return
+    }
+
+    // Normal operation
+    this.nodesManager.dispatch({
+      type: 'update',
+      data: { id: 'node1', /* ... */ },
+    })
+  }
+}
+```
+
+### History State Monitoring
+
+```typescript
+class HistoryMonitorPlugin extends BasePlugin {
+  @inject.history.ref()
+  history!: IHistory
+
+  @subscribe.history.canUndo()
+  onCanUndoChange(canUndo: boolean) {
+    console.log('Can undo:', canUndo)
+  }
+
+  @subscribe.history.canRedo()
+  onCanRedoChange(canRedo: boolean) {
+    console.log('Can redo:', canRedo)
+  }
+
+  // Custom history record monitoring
+  @OnInit
+  init() {
+    // Listen to history changes
+    this.history.onHistoryChange?.subscribe((state) => {
+      console.log('History changed:', state)
+    })
+  }
+}
+```
+
+## Performance Optimization
+
+### Debounce Configuration
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+  pluginConfig: {
+    history: {
+      debounceTime: 200, // Increase debounce time to reduce history entries
+    },
+  },
+})
+```
+
+### History Record Limits
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+  pluginConfig: {
+    history: {
+      maxHistory: 20, // Reduce maximum history records to save memory
+    },
+  },
+})
+```
+
+## File Directory Structure
+
+```
+packages/plugins-history/
+├── src/
+│   ├── history.ts              # 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
+
+- **history.ts**: Contains the main implementation of the History plugin, including operation interception, history management, and state tagging functionality
+- **index.ts**: Exports the History class and related type definitions
+
+## Best Practices
+
+### Memory Management
+
+1. **Set Reasonable History Count**: Configure appropriate `maxHistory` value based on application needs
+2. **Clean Up Tags Timely**: Remove state tags that are no longer needed
+3. **Avoid Excessive Debouncing**: Too long debounce time may affect user experience
+
+### User Experience
+
+1. **Provide Undo/Redo Buttons**: Offer clear undo/redo operation entry points in the UI
+2. **Display Operation Status**: Enable/disable buttons based on `canUndo` and `canRedo` states
+3. **Keyboard Shortcuts**: Support `Ctrl+Z` and `Ctrl+Y` shortcuts
+
+### Development and Debugging
+
+1. **Monitor History State**: Listen to history changes during development for debugging
+2. **Use State Tags**: Set state tags at key operation points for testing and debugging
+
+## Notes
+
+1. **Performance with Large Data**: History records consume memory; consider performance optimization with large datasets
+2. **Asynchronous Operations**: Async operations may cause history order confusion; requires special attention
+3. **Data Consistency**: Ensure undo/redo operations don't break data consistency
+4. **Circular References**: Avoid creating circular references during history record processing
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,378 @@
+# @knotx/plugins-history
+
+历史记录插件，为 KnotX 提供撤销/重做功能。
+
+## 安装
+
+```bash
+npm install @knotx/plugins-history
+```
+
+## 概述
+
+History 插件为 KnotX 提供了完整的历史记录管理功能，包括撤销、重做、标记状态等。该插件能够跟踪所有数据变化，并提供便捷的历史记录操作接口。
+
+## 实现原理
+
+History 插件的核心实现原理：
+
+1. **操作拦截**：拦截所有数据管理器的操作，记录变化前后的状态
+2. **缓冲机制**：使用防抖机制批量处理操作，避免频繁的历史记录创建
+3. **反向操作**：为每个操作生成反向操作，实现撤销功能
+4. **状态标记**：支持标记特定状态，快速回到指定的历史点
+
+## 依赖关系
+
+### 核心依赖
+- `@knotx/core`：提供基础插件架构和数据管理
+- `@knotx/decorators`：提供装饰器支持
+- `rxjs`：提供响应式编程支持
+
+### 自动依赖
+- `@knotx/core` 中的 `nodesManager` 和 `edgesManager`：自动注册到历史记录系统
+
+## API 文档
+
+### 主要类
+
+#### History
+
+历史记录插件的主要类，继承自 `BasePlugin`。
+
+```typescript
+export class History<T extends Record<string, IData> = Record<string, any>> extends BasePlugin<'history', HistoryConfig> {
+  name = 'history' as const
+}
+```
+
+### 配置选项
+
+#### HistoryConfig
+
+```typescript
+export interface HistoryConfig {
+  /** 最大历史记录数量 */
+  maxHistory?: number
+  /** 防抖时间（毫秒） */
+  debounceTime?: number
+}
+```
+
+### 插件数据 (PluginData)
+
+History 插件提供以下数据：
+
+```typescript
+interface PluginData {
+  history: {
+    ref: IHistory
+    canUndo: boolean
+    canRedo: boolean
+    registerDataManager: (dataManager: DataManager<any>) => (() => void)
+  }
+}
+```
+
+### 接口定义
+
+#### IHistory
+
+```typescript
+export interface IHistory {
+  isUndoRedo: boolean
+  undo: () => void
+  redo: () => void
+  addTag: (tag: string) => void
+  removeTag: (tag: string) => void
+  toTag: (tag: string) => void
+  clearTags: () => void
+}
+```
+
+#### HistoryState
+
+```typescript
+export interface HistoryState<T extends Record<string, IData> = Record<string, any>> {
+  value: {
+    [key: string]: HistoryOperation<T>[]
+  }
+  timestamp: number
+}
+```
+
+## 使用示例
+
+### 基本用法
+
+```typescript
+import { History } from '@knotx/plugins-history'
+
+const engine = new Engine({
+  plugins: [History],
+  pluginConfig: {
+    history: {
+      maxHistory: 50,
+      debounceTime: 100,
+    },
+  },
+})
+```
+
+### 撤销和重做操作
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+})
+
+const historyData = engine.getPluginData('history')
+
+// 撤销操作
+if (historyData.canUndo) {
+  historyData.ref.undo()
+}
+
+// 重做操作
+if (historyData.canRedo) {
+  historyData.ref.redo()
+}
+```
+
+### 监听历史记录状态
+
+```tsx
+class HistoryUIPlugin extends BasePlugin {
+  @inject.history.canUndo()
+  canUndo!: boolean
+
+  @inject.history.canRedo()
+  canRedo!: boolean
+
+  @inject.history.ref()
+  history!: IHistory
+
+  @panel('bottom')
+  render() {
+    return (
+      <div>
+        <button
+          disabled={!this.canUndo}
+          onClick={() => this.history.undo()}
+        >
+          撤销
+        </button>
+        <button
+          disabled={!this.canRedo}
+          onClick={() => this.history.redo()}
+        >
+          重做
+        </button>
+      </div>
+    )
+  }
+}
+```
+
+### 状态标记功能
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+})
+
+const historyData = engine.getPluginData('history')
+
+// 标记当前状态
+historyData.ref.addTag('checkpoint-1')
+
+// 在进行一系列操作后...
+// 回到标记的状态
+historyData.ref.toTag('checkpoint-1')
+
+// 移除标记
+historyData.ref.removeTag('checkpoint-1')
+
+// 清空所有标记
+historyData.ref.clearTags()
+```
+
+### 自定义数据管理器集成
+
+```typescript
+class CustomDataManager extends DataManager<MyData> {
+  constructor() {
+    super('custom')
+  }
+}
+
+const engine = new Engine({
+  plugins: [History],
+})
+
+const historyData = engine.getPluginData('history')
+const customManager = new CustomDataManager()
+
+// 注册自定义数据管理器
+const unregister = historyData.registerDataManager(customManager)
+
+// 取消注册
+unregister()
+```
+
+## 高级功能
+
+### 批量操作优化
+
+```typescript
+class BatchHistoryPlugin extends BasePlugin {
+  @inject.history.ref()
+  history!: IHistory
+
+  performBatchOperation() {
+    // 批量操作会自动被防抖处理
+    engine.dispatchNodeOperation({
+      type: 'add',
+      data: { id: 'node1', /* ... */ },
+    })
+
+    engine.dispatchNodeOperation({
+      type: 'add',
+      data: { id: 'node2', /* ... */ },
+    })
+
+    // 这些操作会被合并为一个历史记录条目
+  }
+}
+```
+
+### 条件性历史记录
+
+```typescript
+class ConditionalHistoryPlugin extends BasePlugin {
+  @inject.history.ref()
+  history!: IHistory
+
+  @inject.nodesManager()
+  nodesManager!: DataManager<Node>
+
+  performTemporaryOperation() {
+    // 检查是否在撤销/重做过程中
+    if (this.history.isUndoRedo) {
+      // 在撤销/重做过程中，避免创建新的历史记录
+      return
+    }
+
+    // 正常操作
+    this.nodesManager.dispatch({
+      type: 'update',
+      data: { id: 'node1', /* ... */ },
+    })
+  }
+}
+```
+
+### 历史记录状态监听
+
+```typescript
+class HistoryMonitorPlugin extends BasePlugin {
+  @inject.history.ref()
+  history!: IHistory
+
+  @subscribe.history.canUndo()
+  onCanUndoChange(canUndo: boolean) {
+    console.log('Can undo:', canUndo)
+  }
+
+  @subscribe.history.canRedo()
+  onCanRedoChange(canRedo: boolean) {
+    console.log('Can redo:', canRedo)
+  }
+
+  // 自定义历史记录监听
+  @OnInit
+  init() {
+    // 监听历史记录变化
+    this.history.onHistoryChange?.subscribe((state) => {
+      console.log('History changed:', state)
+    })
+  }
+}
+```
+
+## 性能优化
+
+### 防抖配置
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+  pluginConfig: {
+    history: {
+      debounceTime: 200, // 增加防抖时间以减少历史记录条目
+    },
+  },
+})
+```
+
+### 历史记录限制
+
+```typescript
+const engine = new Engine({
+  plugins: [History],
+  pluginConfig: {
+    history: {
+      maxHistory: 20, // 减少最大历史记录数量以节省内存
+    },
+  },
+})
+```
+
+## 文件目录结构
+
+```
+packages/plugins-history/
+├── src/
+│   ├── history.ts              # 主要实现文件
+│   └── index.ts               # 导出文件
+├── dist/                      # 构建输出目录
+├── package.json              # 包配置文件
+├── build.config.ts           # 构建配置
+├── tsconfig.json             # TypeScript 配置
+├── eslint.config.mjs         # ESLint 配置
+└── CHANGELOG.md              # 更新日志
+```
+
+### 核心文件说明
+
+- **history.ts**：包含 History 插件的主要实现，包括操作拦截、历史记录管理和状态标记功能
+- **index.ts**：导出 History 类和相关类型定义
+
+## 最佳实践
+
+### 内存管理
+
+1. **合理设置历史记录数量**：根据应用需求设置合适的 `maxHistory` 值
+2. **及时清理标记**：不再需要的状态标记应及时清理
+3. **避免过度防抖**：过长的防抖时间可能影响用户体验
+
+### 用户体验
+
+1. **提供撤销/重做按钮**：在 UI 中提供清晰的撤销/重做操作入口
+2. **显示操作状态**：根据 `canUndo` 和 `canRedo` 状态禁用/启用按钮
+3. **键盘快捷键**：支持 `Ctrl+Z` 和 `Ctrl+Y` 快捷键
+
+### 开发调试
+
+1. **监听历史记录状态**：在开发阶段监听历史记录变化以便调试
+2. **使用状态标记**：在关键操作点设置状态标记，方便测试和调试
+
+## 注意事项
+
+1. **大量数据性能**：历史记录会占用内存，大量数据时注意性能优化
+2. **异步操作**：异步操作可能导致历史记录顺序混乱，需要特别注意
+3. **数据一致性**：确保撤销/重做操作不会破坏数据的一致性
+4. **循环引用**：避免在历史记录处理过程中创建循环引用
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knotx/plugins-history",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "History Plugin for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -29,13 +29,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/typescript-config": "0.4.12"
+    "@knotx/build-config": "0.4.13",
+    "@knotx/eslint-config": "0.4.13",
+    "@knotx/typescript-config": "0.4.13"
   },
   "scripts": {
     "build": "unbuild",