@knotx/core 0.4.12 → 0.4.14

package/README.en.md

@@ -0,0 +1,738 @@
+# @knotx/core
+
+**English** | [中文](./README.md)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @knotx/core
+```
+
+```bash
+yarn add @knotx/core
+```
+
+```bash
+pnpm add @knotx/core
+```
+
+## 📖 Overview
+
+`@knotx/core` is the core package of the Knotx graph editor, providing the fundamental infrastructure needed to build visual graph editors. It includes engine management, plugin system, interaction management, element operations, layer rendering, and other core functionalities, offering developers powerful and flexible graph editing capabilities.
+
+## 🚀 Quick Start
+
+```typescript
+import { Engine } from '@knotx/core'
+
+// Create engine instance
+const engine = new Engine({
+  container: { width: 800, height: 600, direction: 'horizontal' },
+  nodes: [
+    { id: '1', position: { x: 100, y: 100 }, data: { label: 'Node 1' } },
+    { id: '2', position: { x: 300, y: 200 }, data: { label: 'Node 2' } }
+  ],
+  edges: [
+    { id: 'e1', source: '1', target: '2', data: {} }
+  ]
+})
+
+// Get nodes
+const nodes = engine.getNodes()
+console.log(nodes)
+```
+
+## 📚 Complete API Documentation
+
+### 🔧 Core Classes
+
+#### Engine Class
+
+The Engine is the core of Knotx, responsible for managing the entire graph editor's state and behavior.
+
+```typescript
+// Engine class type definition
+interface Engine<TRenderType extends RenderType = RenderType, TNode extends IRecord = IRecord, TEdge extends IRecord = IRecord> {
+  // Engine methods and properties
+}
+```
+
+**Properties:**
+- `runtime: IEngineRuntime` - Runtime configuration
+- `interaction: InteractionManager` - Interaction manager
+- `nodesManager: DataManager<Node<TNode>>` - Node data manager
+- `edgesManager: DataManager<Edge<TEdge>>` - Edge data manager
+- `container: Container` - Container configuration
+- `nodes: Node<TNode>[]` - Node array
+- `edges: Edge<TEdge>[]` - Edge array
+- `layers: Map<number, LayerComponent<TRenderType>[]>` - Layer component mapping
+- `plugins: IPlugin[]` - Plugin array
+
+**Methods:**
+- `getNodes(): Node<TNode>[]` - Get all nodes
+- `getEdges(): Edge<TEdge>[]` - Get all edges
+- `getNode({ id }): Node<TNode> | undefined` - Get node by ID
+- `getEdge({ id }): Edge<TEdge> | undefined` - Get edge by ID
+- `getNodeDraft({ id }): Node<TNode> | undefined` - Get node draft
+- `getEdgeDraft({ id }): Edge<TEdge> | undefined` - Get edge draft
+- `getPlugin<TPlugin>({ pluginName }): TPlugin | undefined` - Get plugin
+- `getNodeRenderer(type: string): NodeRenderType | undefined` - Get node renderer
+- `getEdgeRenderer(type: string): EdgeRender | undefined` - Get edge renderer
+- `getLayerComponents(layer: Layer): LayerComponent<TRenderType>[]` - Get layer components
+- `addNodePipe(pipe: DataOperationPipe<Node<TNode>>)` - Add node operation pipe
+- `addEdgePipe(pipe: DataOperationPipe<Edge<TEdge>>)` - Add edge operation pipe
+- `dispatchNodeOperation(operation: DataOperation<Node<TNode>>)` - Dispatch node operation
+- `dispatchEdgeOperation(operation: DataOperation<Edge<TEdge>>)` - Dispatch edge operation
+- `registerNodeRenderer(type: string, renderer: NodeRenderType): () => void` - Register node renderer
+- `registerEdgeRenderer(type: string, renderer: EdgeRenderType, config: Required<EdgeConfig>): () => void` - Register edge renderer
+- `registerPluginData<T, TP>(pluginName: T, property: TP, data: BehaviorSubject<PluginData[T][TP]>): void` - Register plugin data
+- `subscribePluginData<T, TP>(pluginName: T, property: TP, observer: (value: PluginData[T][TP]) => void): Subscription | null` - Subscribe to plugin data
+- `registerPluginTool<T, TP>(pluginName: T, property: TP, data: { description: string; parameters: Schema; func: PluginTools[T][TP] }): void` - Register plugin tool
+- `resetPluginData<T>(pluginName: T): void` - Reset plugin data
+- `resetPluginTool<T>(pluginName: T): void` - Reset plugin tool
+- `changePluginConfig({ pluginName, config }): void` - Change plugin configuration
+- `callTool: CallToolMethod` - Call tool method
+- `listPlugins(): IPluginInfo[]` - List all plugins
+- `listPluginTools({ pluginName }): IToolInfo[]` - List plugin tools
+- `listEngineTools(): IToolInfo[]` - List engine tools
+- `destroy()` - Destroy engine
+
+#### BasePlugin Class
+
+Base class for plugins, providing fundamental functionality for plugin development.
+
+```typescript
+// BasePlugin abstract class type definition
+abstract class BasePlugin<TPluginName extends string = string, TPluginConfig extends IRecord | undefined = undefined, TRenderType extends RenderType = RenderType> {
+  // Plugin abstract methods and properties
+}
+```
+
+**Properties:**
+- `abstract name: TPluginName` - Plugin name
+- `pluginId: string` - Plugin unique ID
+- `protected subscriptions: (SubscriptionLike | (() => void))[]` - Subscription collection
+- `protected callTool: Engine['callTool']` - Call tool method
+
+**Methods:**
+- `onInit?(config: TPluginConfig): void` - Initialization callback
+- `onConfigChange?(config: TPluginConfig): void` - Configuration change callback
+- `onDestroy?(): void` - Destroy callback
+
+#### InteractionManager Class
+
+Interaction manager responsible for managing user interaction priorities and states.
+
+```typescript
+// InteractionManager class type definition
+class InteractionManager {
+  // Interaction manager methods and properties
+}
+```
+
+**Properties:**
+- `active: Interaction | undefined` - Current active interaction
+
+**Methods:**
+- `canInteract(priority: InteractionPriority): boolean` - Check if can interact
+- `start(pluginId: string, type: string, priority: InteractionPriority): () => void` - Start interaction
+- `end(pluginId: string, type: string): void` - End interaction
+
+#### Runtime Class
+
+Runtime manager handling context execution and value processing.
+
+```typescript
+// Runtime class type definition
+class Runtime {
+  // Runtime methods and properties
+}
+```
+
+**Properties:**
+- `currentContext: { type: any; value: any } | undefined` - Current context
+
+**Methods:**
+- `runInContext<T>(type: any, handler: () => T, contextValue?: any): T` - Run in context
+- `getValue<T>(engine: Engine<any>, options: { paths: any[]; matcher?: (engine: Engine<any>) => BehaviorSubject<any>; selector?: (value: T, context?: any) => any }): any` - Get value
+- `static getInstance(): Runtime` - Get singleton instance
+- `static DEFAULT_VALUE_HANDLER: <T>(value: BehaviorSubject<T> | T, options: { paths: string[]; selector?: (value: T, context?: any) => any; context?: any }) => T` - Default value handler
+
+#### DataManager Class
+
+Data manager for managing CRUD operations and version control.
+
+```typescript
+// DataManager class type definition
+class DataManager<TData extends IData = IData, TTag extends string = any> {
+  // Data manager methods and properties
+}
+```
+
+**Properties:**
+- `readonly tag: TTag` - Tag
+- `readonly dataMap$: BehaviorSubject<Map<string, TData>>` - Data mapping
+- `readonly patchVersion$: BehaviorSubject<number>` - Patch version
+- `readonly mapVersion$: BehaviorSubject<number>` - Map version
+- `version: number` - Version number
+
+**Methods:**
+- `init(initialDataList: TData[]): void` - Initialize
+- `getDataList$(): Observable<TData[]>` - Get data list stream
+- `getDataList(): TData[]` - Get data list
+- `getData(id: string): TData | undefined` - Get data
+- `getOperations$(): Observable<DataOperation<TData>>` - Get operations stream
+- `dispatch(operation: DataOperation<TData>): void` - Dispatch operation
+- `getDraftDataList(draftId: string): TData[] | undefined` - Get draft data list
+
+#### DualRelation Class
+
+Dual relation manager for managing parent-child relationships.
+
+```typescript
+// DualRelation class type definition
+class DualRelation<P, C> {
+  // Dual relation manager methods and properties
+}
+```
+
+**Properties:**
+- `version: BehaviorSubject<number>` - Version number
+
+**Methods:**
+- `addRelation(parent: P, child: C): void` - Add relation
+- `removeRelation(parent: P, child: C): void` - Remove relation
+- `getChildren(parent: P): C[]` - Get children
+- `getParent(child: C): P | undefined` - Get parent
+- `clear(): void` - Clear relations
+
+#### Element Interface and DOMElement Class
+
+Element abstraction providing cross-platform element operation interfaces.
+
+```typescript
+interface Element {
+  classList: ElementClassList
+  attribute: ElementAttribute
+  uniqSelector: string | undefined
+  getRect: () => ElementRect
+  addEventListener: EventListenerDefinition
+  removeEventListener: EventListenerDefinition
+  query: (selector: string) => Element | null
+  queryAll: (selector: string) => Element[]
+}
+
+class DOMElement implements Element {
+  constructor(readonly dom: HTMLElement) {}
+  static fromDOM(dom: HTMLElement): DOMElement
+}
+```
+
+### 🎭 Type Definitions
+
+#### Basic Types
+```typescript
+type HorizontalAlignment = 'left' | 'right'
+type VerticalAlignment = 'top' | 'bottom'
+type Direction = 'horizontal' | 'vertical'
+type IRecord = Record<string, any>
+type Position = VerticalAlignment | HorizontalAlignment | `${HorizontalAlignment}-${VerticalAlignment}` | 'center'
+type RenderType = (...args: any[]) => any
+```
+
+#### Node Related Types
+```typescript
+interface NodePosition {
+  x: number
+  y: number
+}
+
+interface NodeMeasured {
+  width: number
+  height: number
+}
+
+interface Node<TData extends IRecord = IRecord> {
+  id: string
+  type?: string
+  position: NodePosition
+  measured?: NodeMeasured
+  data: TData
+}
+
+interface NodeProps<TData extends IRecord = IRecord> {
+  node: Node<TData>
+  renderVersion?: number
+}
+
+type NodeRenderType<TD extends IRecord = any, TR = any> = (props: NodeProps<TD>) => TR
+type NodeOperation<T extends IRecord = any> = DataOperation<Node<T>>
+type NodeOperationPipe<T extends IRecord = any> = DataOperationPipe<Node<T>>
+type NodeOperatorFunction<T extends IRecord = any, TArgs extends any[] = any[]> = (...args: TArgs) => NodeOperation<T>[]
+```
+
+#### Edge Related Types
+```typescript
+interface EdgeConfig {
+  sourcePosition?: Position
+  targetPosition?: Position
+  sourceYOffset?: string | number
+  sourceXOffset?: string | number
+  targetYOffset?: string | number
+  targetXOffset?: string | number
+}
+
+interface Edge<TData extends IRecord = IRecord> extends EdgeConfig {
+  id: string
+  source: string
+  target: string
+  type?: string
+  data?: TData
+}
+
+interface EdgeProps<TData extends IRecord = IRecord> {
+  edge: Edge<TData>
+  sourceX: number
+  sourceY: number
+  targetX: number
+  targetY: number
+  renderVersion?: number
+}
+
+type EdgeRenderType<TD extends IRecord = any, TR = any> = (props: EdgeProps<TD>) => TR
+
+interface EdgeRender<TD extends IRecord = any, TR = any> {
+  renderer: EdgeRenderType<TD, TR>
+  config: Required<EdgeConfig>
+}
+
+type EdgeOperation<T extends IRecord = any> = DataOperation<Edge<T>>
+type EdgeOperationPipe<T extends IRecord = any> = DataOperationPipe<Edge<T>>
+type EdgeOperatorFunction<T extends IRecord = any, TArgs extends any[] = any[]> = (...args: TArgs) => EdgeOperation<T>[]
+```
+
+#### Container Types
+```typescript
+interface Container {
+  width: number
+  height: number
+  direction: Direction
+}
+```
+
+#### Layer Types
+```typescript
+enum Layer {
+  Canvas = 0,
+  Background = 4,
+  Edges = 16,
+  Nodes = 64,
+  Foreground = 256,
+}
+
+interface LayerComponent<TRenderType> {
+  plugin: string
+  name: string
+  layer: Layer
+  render: TRenderType
+  offset?: number
+}
+```
+
+#### Plugin Types
+```typescript
+interface IPlugin<TPluginName extends string = string, TPluginConfig extends IRecord | undefined = any> {
+  name: TPluginName
+  pluginId: string
+  description?: string
+  onInit?: (config: TPluginConfig) => void
+  onConfigChange?: (config: TPluginConfig) => void
+  onDestroy?: () => void
+}
+
+type Plugin<TName extends string = string, TConfig extends IRecord | undefined = any, TRenderType extends RenderType = RenderType> = new (__: TConfig) => BasePlugin<TName, TConfig, TRenderType>
+
+interface PluginData {} // Module augmentation interface
+interface PluginTools {} // Module augmentation interface
+interface EngineTools {} // Module augmentation interface
+
+interface IPluginInfo {
+  name: string
+  description?: string
+}
+
+interface IToolInfo {
+  type: 'function'
+  name: string
+  description: string
+  parameters: Schema
+}
+```
+
+#### Data Operation Types
+```typescript
+interface IData {
+  id: string
+}
+
+interface DataAddOperation<T extends IData = IData> {
+  type: 'add'
+  data: T
+}
+
+interface DataRemoveOperation<_T extends IData = IData> {
+  type: 'remove'
+  id: string
+}
+
+interface DataUpdateOperation<T extends IData = IData> {
+  type: 'update'
+  id: string
+  data: T
+}
+
+interface DataBatchOperation<T extends IData = IData> {
+  type: 'batch'
+  operations: DataOperation<T>[]
+  isInit?: boolean
+}
+
+interface DataStartDraftOperation<T extends IData = IData> {
+  type: 'startDraft'
+  draftId: string
+  data: T
+}
+
+interface DataCommitDraftOperation<T extends IData = IData> {
+  type: 'commitDraft'
+  draftId: string
+  data: T
+}
+
+interface DataDiscardDraftOperation<T extends IData = IData> {
+  type: 'discardDraft'
+  draftId: string
+}
+
+interface DataDraftOperation<T extends IData = IData> {
+  type: 'draft'
+  draftId: string
+  operation: DataOperation<T>
+}
+
+type DataOperation<T extends IData = IData> = DataAddOperation<T> | DataRemoveOperation<T> | DataUpdateOperation<T> | DataBatchOperation<T> | DataStartDraftOperation<T> | DataCommitDraftOperation<T> | DataDiscardDraftOperation<T> | DataDraftOperation<T>
+
+interface DataOperationPipe<T extends IData = IData> {
+  transform?: (operations$: Subject<DataOperation<T>>) => OperatorFunction<DataOperation<T>, DataOperation<T>>
+  preOperation?: (operations$: Subject<DataOperation<T>>) => OperatorFunction<DataOperation<T>, DataOperation<T>>
+  postOperation?: (operations$: Subject<DataOperation<T>>) => OperatorFunction<{ dataMap: Map<string, T>, operations: DataOperation<T>[] }, { dataMap: Map<string, T>, operations: DataOperation<T>[] }>
+}
+```
+
+#### Interaction Types
+```typescript
+enum InteractionPriority {
+  InputActive = 2000,
+  EntityConnectDrag = 1930,
+  EntityMeasureDrag = 1920,
+  EntityPositionDrag = 1910,
+  ContinuousDrag = 1900,
+  ContextMenu = 1800,
+  KeyboardShortcut = 1700,
+  ClickSelection = 1600,
+  DoubleClickEdit = 1500,
+  MarqueeSelection = 1300,
+  LassoSelection = 1250,
+  LongPress = 1100,
+  HoverTooltip = 1000,
+  CanvasPan = 900,
+  CanvasZoom = 800,
+  CanvasContextMenu = 700,
+  CanvasClick = 600,
+  MultiTouchGesture = 500,
+}
+
+interface Interaction {
+  pluginId: string
+  type: string
+  priority: InteractionPriority
+  active?: boolean
+}
+```
+
+#### Element Types
+```typescript
+interface ElementClassList {
+  toString: () => string
+  add: (...tokens: string[]) => void
+  contains: (token: string) => boolean
+  remove: (...tokens: string[]) => void
+}
+
+interface ElementAttribute {
+  get: (name: string) => string | null
+  set: (name: string, value: string) => void
+  remove: (name: string) => void
+}
+
+interface ElementRect {
+  height: number
+  width: number
+  x: number
+  y: number
+}
+
+interface EventListenerDefinition<E = any> {
+  (type: string, listener: ((evt: E) => void) | EventListenerObject<E>, options?: boolean | AddEventListenerOptions): void
+}
+```
+
+#### Engine Types
+```typescript
+interface EngineOptions<TNode extends IRecord = IRecord, TEdge extends IRecord = IRecord> {
+  container: Container
+  plugins?: Plugin[]
+  pluginConfig?: IRecord
+  nodes?: Node<TNode>[]
+  edges?: Edge<TEdge>[]
+  runtime?: IEngineRuntime
+}
+
+interface IEngineRuntime {
+  render?: {
+    getValue: <T, R = T>(value: BehaviorSubject<T> | T, options: {
+      paths: string[]
+      selector?: (value: T, context?: any) => R
+      context?: any
+    }) => T | R
+  }
+}
+
+interface CallToolMethod {
+  <T extends keyof PluginTools, TP extends keyof PluginTools[T]>(pluginName: Extract<T, keyof PluginTools>, toolName: Extract<TP, keyof PluginTools[T]>, ...args: Parameters<PluginTools[T][TP]>): ReturnType<PluginTools[T][TP]>
+  <T extends keyof EngineTools>(engineToolName: Extract<T, keyof EngineTools>, ...args: Parameters<EngineTools[T]>): ReturnType<EngineTools[T]>
+}
+```
+
+### 🛠️ Utility Functions
+
+#### Hook Functions
+```typescript
+function use<T>(hook: () => T): T
+function use<T, TContext>(hook: () => { __contextRef__: T, __contextValue__: TContext }, context: TContext): T
+```
+
+#### Layer Functions
+```typescript
+function getLayerRenders<TRenderType extends RenderType = RenderType>(plugin: IPlugin): LayerComponent<TRenderType>[]
+```
+
+#### Utility Functions (from @knotx/utils)
+```typescript
+// BEM class name utilities
+function bem(block: string, element?: string, modifier?: string, prefix?: string): string
+function addBemModifier(className: string, modifier: string): string
+
+// Unique ID generation
+function generateId(): string
+
+// Symbol utilities
+function getSymbol<TName extends string>(name: TName): symbol & { __knotx__?: TName }
+
+// Data operation utilities
+function isInitOperation<T extends IData>(operation: DataOperation<T>): operation is DataInitBatchOperation<T>
+function isDraftOperation<T extends IData>(operation: DataOperation<T>): operation is Extract<DataOperation<T>, { draftId: string }>
+function isEmptyBatchOperation<T extends IData>(operation: DataOperation<T>): operation is DataEmptyBatchOperation<T>
+function flattenOperations<T extends IData>(operations: DataOperation<T>[]): DataOperation<T>[]
+function emptyOperation<T extends IData>(): DataEmptyBatchOperation<T>
+function buildDiffOperation<T extends IData>(previousDataMap: Map<string, T>, dataMap: Map<string, T>, compare?: (a: T | undefined, b: T | undefined) => boolean): DataBatchOperation<T>
+```
+
+### 📘 Usage Examples
+
+#### Basic Usage
+```typescript
+import { Engine } from '@knotx/core'
+
+// Create engine
+const engine = new Engine({
+  container: { width: 800, height: 600, direction: 'horizontal' },
+  nodes: [
+    { id: '1', position: { x: 100, y: 100 }, data: { label: 'Node 1' } }
+  ],
+  edges: []
+})
+
+// Get data
+const nodes = engine.getNodes()
+const node = engine.getNode({ id: '1' })
+```
+
+#### Plugin Development
+```typescript
+import { BasePlugin, Layer } from '@knotx/core'
+
+class MyPlugin extends BasePlugin<'my-plugin', { theme: string }> {
+  name = 'my-plugin' as const
+
+  onInit(config: { theme: string }) {
+    // Plugin initialization logic
+  }
+}
+```
+
+#### Data Operations
+```typescript
+import { DataManager } from '@knotx/core'
+
+const dataManager = new DataManager<Node>('nodes')
+dataManager.init([
+  { id: '1', position: { x: 0, y: 0 }, data: {} }
+])
+
+// Add data
+dataManager.dispatch({
+  type: 'add',
+  data: { id: '2', position: { x: 100, y: 100 }, data: {} }
+})
+```
+
+#### Interaction Management
+```typescript
+import { InteractionManager, InteractionPriority } from '@knotx/core'
+
+const interaction = new InteractionManager()
+const cancel = interaction.start('plugin-id', 'drag', InteractionPriority.EntityPositionDrag)
+
+// Check if can interact
+if (interaction.canInteract(InteractionPriority.ClickSelection)) {
+  // Execute interaction logic
+}
+
+// Cancel interaction
+cancel()
+```
+
+## 🗂️ File Directory Structure
+
+```
+packages/core/
+├── src/
+│   ├── index.ts           # Main export file
+│   ├── definition.ts      # Type definitions and interfaces
+│   ├── engine.ts          # Core engine implementation
+│   ├── element.ts         # Element abstraction layer
+│   ├── plugin.ts          # Plugin base class
+│   ├── interaction.ts     # Interaction manager
+│   ├── runtime.ts         # Runtime management
+│   ├── layer.tsx          # Layer rendering
+│   ├── use.ts             # Hook functions
+│   ├── data.ts            # Data management (re-export)
+│   └── utils.ts           # Utility functions (re-export)
+├── dist/                  # Build output directory
+├── package.json           # Package configuration
+├── tsconfig.json          # TypeScript configuration
+├── build.config.ts        # Build configuration
+└── README.md              # Project documentation
+```
+
+## 🔧 Advanced Usage
+
+### Custom Plugin Development
+
+```typescript
+import type { LayerComponent } from '@knotx/core'
+
+import { BasePlugin, Layer } from '@knotx/core'
+
+class CustomPlugin extends BasePlugin<'custom', { theme: string }> {
+  name = 'custom' as const
+
+  // Declare plugin data
+  declare pluginData: {
+    selectedNodes: string[]
+    highlightColor: string
+  }
+
+  // Declare plugin tools
+  declare pluginTools: {
+    selectNode: (nodeId: string) => void
+    clearSelection: () => void
+  }
+
+  onInit(config: { theme: string }) {
+    // Register plugin data
+    this.engine.registerPluginData('custom', 'selectedNodes', new BehaviorSubject([]))
+    this.engine.registerPluginData('custom', 'highlightColor', new BehaviorSubject('#blue'))
+
+    // Register plugin tools
+    this.engine.registerPluginTool('custom', 'selectNode', {
+      description: 'Select node',
+      parameters: { type: 'string' },
+      func: (nodeId: string) => {
+        // Implement selection logic
+        console.log('Selecting node:', nodeId)
+      }
+    })
+
+    // Register layer component
+    this.engine.registerLayerComponent({
+      plugin: this.name,
+      name: 'selection-layer',
+      layer: Layer.Foreground,
+      render: this.renderSelection.bind(this)
+    })
+  }
+
+  renderSelection() {
+    return '<div class="selection-overlay">Selection Layer</div>'
+  }
+}
+```
+
+### Data Operation Pipes
+
+```typescript
+import type { EdgeOperation, NodeOperation } from '@knotx/core'
+
+// Node operation pipe
+engine.addNodePipe((operations: NodeOperation[]) => {
+  return operations.map((op) => {
+    if (op.type === 'update') {
+      // Validate data before update
+      if (!validateNodeData(op.data)) {
+        throw new Error('Invalid node data')
+      }
+    }
+    return op
+  })
+})
+
+// Edge operation pipe
+engine.addEdgePipe((operations: EdgeOperation[]) => {
+  return operations.filter((op) => {
+    // Filter invalid edge operations
+    return op.source !== op.target
+  })
+})
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](../../LICENSE).
+
+---
+
+## 🔗 Related Links
+
+- [Homepage](https://github.com/boenfu/knotx)
+- [Issues](https://github.com/boenfu/knotx/issues)
+- [Contributing Guide](../../CONTRIBUTING.md)
+
+---
+
+Made with ❤️ by the Knotx team