@knotx/react 0.4.12 → 0.4.13

package/README.en.md

@@ -0,0 +1,722 @@
+# @knotx/react
+
+[![npm version](https://img.shields.io/npm/v/@knotx/react.svg)](https://www.npmjs.com/package/@knotx/react)
+[![license](https://img.shields.io/npm/l/@knotx/react.svg)](https://github.com/boenfu/knotx/blob/main/LICENSE)
+
+> 🚀 A powerful React node editor component supporting visual flowcharts, organizational charts, mind maps, and more
+
+## 📦 Installation
+
+```bash
+npm install @knotx/react
+```
+
+```bash
+yarn add @knotx/react
+```
+
+```bash
+pnpm add @knotx/react
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```json
+{
+  "react": ">=17.0.0",
+  "react-dom": ">=17.0.0"
+}
+```
+
+## 🎯 Overview
+
+`@knotx/react` is the React adapter for the Knotx ecosystem, providing a powerful and flexible node editor component. It supports:
+
+- 🎨 **Visual Node Editing** - Drag, zoom, and connect nodes
+- 🔧 **Plugin System** - Highly extensible plugin architecture
+- 🎭 **Custom Rendering** - Fully customizable node and edge rendering
+- 📱 **Responsive Design** - Adapts to different screen sizes
+- ⚡ **High Performance** - Reactive state management based on RxJS
+- 🎪 **Rich Interactions** - Selection, dragging, zooming, minimap, and more
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```tsx
+import type { Edge, Node } from '@knotx/core'
+
+import { Knotx } from '@knotx/react'
+import React from 'react'
+
+function App() {
+  const initialNodes: Node[] = [
+    {
+      id: '1',
+      type: 'basic',
+      position: { x: 300, y: 300 },
+      measured: { width: 160, height: 60 },
+      data: { label: 'Node 1' }
+    },
+    {
+      id: '2',
+      type: 'basic',
+      position: { x: 600, y: 300 },
+      measured: { width: 160, height: 60 },
+      data: { label: 'Node 2' }
+    }
+  ]
+
+  const initialEdges: Edge[] = [
+    {
+      id: '1-2',
+      type: 'bezier',
+      source: '1',
+      target: '2',
+      data: {}
+    }
+  ]
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Knotx
+        initialNodes={initialNodes}
+        initialEdges={initialEdges}
+        plugins={[]} // Plugin list
+      />
+    </div>
+  )
+}
+
+export default App
+```
+
+### Custom Node Rendering
+
+```tsx
+import type { Node } from '@knotx/core'
+
+import { BasePlugin } from '@knotx/core'
+import { nodeType } from '@knotx/decorators'
+import { Knotx } from '@knotx/react'
+import React from 'react'
+
+// Create custom node plugin
+class CustomNodePlugin extends BasePlugin<'customNode'> {
+  name = 'customNode' as const
+
+  @nodeType('custom')
+  renderCustomNode({ node }: { node: Node }) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          background: '#f0f0f0',
+          border: '2px solid #ccc',
+          borderRadius: '8px',
+          padding: '12px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          fontSize: '14px',
+          fontWeight: 'bold'
+        }}
+      >
+        {node.data?.label || node.id}
+      </div>
+    )
+  }
+}
+
+function App() {
+  const nodes: Node[] = [
+    {
+      id: '1',
+      type: 'custom',
+      position: { x: 300, y: 300 },
+      measured: { width: 200, height: 80 },
+      data: { label: 'Custom Node' }
+    }
+  ]
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Knotx
+        initialNodes={nodes}
+        plugins={[CustomNodePlugin]}
+      />
+    </div>
+  )
+}
+```
+
+### Controlled Component Mode
+
+```tsx
+import type { Edge, Node, ReactEngine } from '@knotx/react'
+
+import { Knotx } from '@knotx/react'
+import React, { useState } from 'react'
+
+function App() {
+  const [nodes, setNodes] = useState<Node[]>([
+    {
+      id: '1',
+      type: 'basic',
+      position: { x: 300, y: 300 },
+      measured: { width: 160, height: 60 },
+      data: { label: 'Node 1' }
+    }
+  ])
+
+  const [edges, setEdges] = useState<Edge[]>([])
+
+  const handleInit = (engine: ReactEngine) => {
+    console.log('Engine initialized:', engine)
+
+    // Listen to node changes
+    engine.nodesManager.dataMap$.subscribe((nodesMap) => {
+      setNodes(Array.from(nodesMap.values()))
+    })
+
+    // Listen to edge changes
+    engine.edgesManager.dataMap$.subscribe((edgesMap) => {
+      setEdges(Array.from(edgesMap.values()))
+    })
+  }
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Knotx
+        nodes={nodes}
+        edges={edges}
+        onInit={handleInit}
+        plugins={[]}
+      />
+    </div>
+  )
+}
+```
+
+## 🔧 API Reference
+
+### Knotx Component
+
+`Knotx` is the main React component for rendering the node editor.
+
+#### Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `className` | `string` | - | CSS class name for the container |
+| `style` | `CSSProperties` | - | Inline styles for the container |
+| `getContainerStyle` | `(engine: ReactEngine) => CSSProperties` | - | Function to get container styles |
+| `initialNodes` | `Node[]` | `[]` | Initial node data |
+| `initialEdges` | `Edge[]` | `[]` | Initial edge data |
+| `nodes` | `Node[]` | - | Controlled node data |
+| `edges` | `Edge[]` | - | Controlled edge data |
+| `plugins` | `Plugin[]` | `[]` | Plugin list |
+| `pluginConfig` | `PluginConfig` | `{}` | Plugin configuration |
+| `disablePresetPlugins` | `boolean` | `false` | Disable preset plugins |
+| `onInit` | `(engine: ReactEngine) => void` | - | Engine initialization callback |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
+| `ref` | `Ref<KnotxInstance>` | - | Component reference |
+
+#### Example
+
+```tsx
+import type { KnotxInstance, ReactEngine } from '@knotx/react'
+
+import { Knotx } from '@knotx/react'
+import React, { useRef } from 'react'
+
+function App() {
+  const knotxRef = useRef<KnotxInstance>(null)
+
+  const handleInit = (engine: ReactEngine) => {
+    console.log('Engine initialized')
+  }
+
+  const handleRerender = () => {
+    knotxRef.current?.rerender()
+  }
+
+  return (
+    <div>
+      <button onClick={handleRerender}>Rerender</button>
+      <Knotx
+        ref={knotxRef}
+        className="my-knotx"
+        style={{ border: '1px solid #ccc' }}
+        initialNodes={[]}
+        initialEdges={[]}
+        plugins={[]}
+        direction="horizontal"
+        onInit={handleInit}
+        getContainerStyle={engine => ({
+          backgroundColor: '#f5f5f5'
+        })}
+      />
+    </div>
+  )
+}
+```
+
+### KnotxInstance Interface
+
+The component instance interface obtained through `ref`.
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `engineRef` | `MutableRefObject<ReactEngine \| null>` | Engine instance reference |
+| `rerender` | `() => void` | Force rerender the component |
+
+#### Example
+
+```tsx
+import type { KnotxInstance } from '@knotx/react'
+
+import { Knotx } from '@knotx/react'
+import React, { useEffect, useRef } from 'react'
+
+function App() {
+  const knotxRef = useRef<KnotxInstance>(null)
+
+  useEffect(() => {
+    if (knotxRef.current) {
+      const engine = knotxRef.current.engineRef.current
+      if (engine) {
+        // Use engine API
+        console.log('Current node count:', engine.nodesManager.dataMap$.value.size)
+      }
+    }
+  }, [])
+
+  return (
+    <Knotx
+      ref={knotxRef}
+      initialNodes={[]}
+      initialEdges={[]}
+      plugins={[]}
+    />
+  )
+}
+```
+
+### ReactEngine Type
+
+Extended from `@knotx/core`'s `Engine` type, specifically for React environment.
+
+#### Main Methods
+
+| Method | Description |
+|--------|-------------|
+| `dispatchNodeOperation(operation: NodeOperation)` | Dispatch node operation |
+| `dispatchEdgeOperation(operation: EdgeOperation)` | Dispatch edge operation |
+| `getLayerComponents(layer: number)` | Get layer components |
+| `destroy()` | Destroy engine instance |
+
+### Plugin Configuration
+
+#### Plugin Configuration Type
+
+```typescript
+interface PluginConfig {
+  [pluginName: string]: any
+}
+```
+
+#### Example
+
+```tsx
+import { Canvas } from '@knotx/plugins-canvas'
+import { Drag } from '@knotx/plugins-drag'
+import { Knotx } from '@knotx/react'
+import React from 'react'
+
+function App() {
+  const pluginConfig = {
+    canvas: {
+      minScale: 0.1,
+      maxScale: 2.0,
+      wheel: {
+        step: 0.1,
+        wheelDisabled: false
+      }
+    },
+    drag: {
+      allowDrag: true,
+      dragThreshold: 5
+    }
+  }
+
+  return (
+    <Knotx
+      initialNodes={[]}
+      initialEdges={[]}
+      plugins={[Canvas, Drag]}
+      pluginConfig={pluginConfig}
+    />
+  )
+}
+```
+
+## 🧩 Plugin System
+
+### Common Plugins
+
+Here are some commonly used plugins:
+
+- `@knotx/plugins-canvas` - Canvas functionality (zoom, pan)
+- `@knotx/plugins-drag` - Drag functionality
+- `@knotx/plugins-selection` - Selection functionality
+- `@knotx/plugins-minimap` - Minimap
+- `@knotx/plugins-background` - Background
+- `@knotx/plugins-bounding` - Boundary adjustment
+- `@knotx/plugins-connection-line` - Connection lines
+- `@knotx/plugins-group` - Grouping
+- `@knotx/plugins-history` - History management
+
+### Creating Custom Plugins
+
+```tsx
+import type { EdgeProps, Node } from '@knotx/core'
+
+import { BasePlugin } from '@knotx/core'
+import { edgeType, nodeType } from '@knotx/decorators'
+
+class MyPlugin extends BasePlugin<'myPlugin'> {
+  name = 'myPlugin' as const
+
+  @nodeType('myNode')
+  renderMyNode({ node }: { node: Node }) {
+    return (
+      <div style={{ padding: '10px', border: '1px solid #ccc' }}>
+        Custom Node:
+        {' '}
+        {node.id}
+      </div>
+    )
+  }
+
+  @edgeType('myEdge')
+  renderMyEdge(props: EdgeProps) {
+    return (
+      <path
+        d={props.path}
+        stroke="#ff0000"
+        strokeWidth={2}
+        fill="none"
+      />
+    )
+  }
+}
+
+// Using the plugin
+function App() {
+  return (
+    <Knotx
+      initialNodes={[
+        {
+          id: '1',
+          type: 'myNode',
+          position: { x: 100, y: 100 },
+          measured: { width: 120, height: 60 },
+          data: {}
+        }
+      ]}
+      initialEdges={[]}
+      plugins={[MyPlugin]}
+    />
+  )
+}
+```
+
+## 📂 Directory Structure
+
+```
+packages/react/
+├── src/
+│   ├── components/           # React components
+│   │   ├── content.tsx      # Layer content component
+│   │   └── index.ts         # Component exports
+│   ├── hooks/               # React Hooks
+│   │   ├── container.ts     # Container reference Hook
+│   │   ├── data.ts          # Data update Hook
+│   │   ├── engine.ts        # Engine management Hook
+│   │   ├── plugin.ts        # Plugin management Hook
+│   │   └── index.ts         # Hooks exports
+│   ├── definition.ts        # Type definitions
+│   ├── engine.ts            # React engine initialization
+│   ├── index.ts             # Main entry point
+│   ├── knotx.tsx            # Main Knotx component
+│   └── layer.tsx            # Layer rendering component
+├── dist/                    # Build output directory
+├── CHANGELOG.md             # Changelog
+├── package.json             # Package configuration
+├── README.md                # Chinese documentation
+├── README.en.md             # English documentation
+└── tsconfig.json            # TypeScript configuration
+```
+
+### Core File Descriptions
+
+| File | Description |
+|------|-------------|
+| `knotx.tsx` | Main Knotx React component implementation |
+| `definition.ts` | TypeScript type definitions and interfaces |
+| `engine.ts` | React engine initialization and runtime configuration |
+| `layer.tsx` | Layer rendering logic |
+| `components/content.tsx` | Layer content rendering component |
+| `hooks/container.ts` | Container size monitoring Hook |
+| `hooks/data.ts` | Data diff update Hook |
+| `hooks/engine.ts` | Engine lifecycle management Hook |
+| `hooks/plugin.ts` | Plugin merging and configuration update Hook |
+
+## 🔗 Type Exports
+
+This package re-exports all types from `@knotx/core` for convenience:
+
+```typescript
+import type {
+  // Others
+  Direction,
+  Edge,
+  EdgeOperation,
+  EdgeProps,
+
+  Engine,
+  EngineOptions,
+
+  IData,
+  IPlugin,
+
+  KnotxInstance,
+  KnotxProps,
+
+  Layer,
+  // Core types
+  Node,
+
+  // Operation types
+  NodeOperation,
+  NodePosition,
+  // Property types
+  NodeProps,
+  Plugin,
+
+  // Configuration types
+  PluginConfigs,
+  // Position types
+  Position,
+  // React-specific types
+  ReactEngine
+} from '@knotx/react'
+```
+
+## 🎨 Best Practices
+
+### 1. Performance Optimization
+
+```tsx
+import { Knotx } from '@knotx/react'
+import React, { memo, useMemo } from 'react'
+
+const MyKnotx = memo(({ data }: { data: any }) => {
+  // Use useMemo to cache node and edge data
+  const nodes = useMemo(() => {
+    return data.nodes || []
+  }, [data.nodes])
+
+  const edges = useMemo(() => {
+    return data.edges || []
+  }, [data.edges])
+
+  return (
+    <Knotx
+      nodes={nodes}
+      edges={edges}
+      plugins={[]}
+    />
+  )
+})
+```
+
+### 2. Error Handling
+
+```tsx
+import { Knotx } from '@knotx/react'
+import React, { ErrorBoundary } from 'react'
+
+class KnotxErrorBoundary extends React.Component {
+  constructor(props: any) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    // Handle error: log error and return error state
+    console.error('React Error Boundary:', error)
+    return { hasError: true }
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    // Handle error: log error information
+    console.error('Knotx Error:', error, errorInfo)
+
+    // You can add error reporting logic here
+    // For example: this.reportError(error, errorInfo)
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <div>Something went wrong with Knotx.</div>
+    }
+
+    return this.props.children
+  }
+}
+
+function App() {
+  return (
+    <KnotxErrorBoundary>
+      <Knotx
+        initialNodes={[]}
+        initialEdges={[]}
+        plugins={[]}
+      />
+    </KnotxErrorBoundary>
+  )
+}
+```
+
+### 3. Theme Customization
+
+```tsx
+import { BasePlugin } from '@knotx/core'
+import { layer } from '@knotx/decorators'
+import { Knotx } from '@knotx/react'
+import React from 'react'
+
+class ThemePlugin extends BasePlugin<'theme'> {
+  name = 'theme' as const
+
+  @layer(100)
+  renderTheme() {
+    return (
+      <style>
+        {`
+          .knotx-container {
+            --node-bg: #ffffff;
+            --node-border: #e1e4e8;
+            --edge-stroke: #586069;
+            --selection-bg: rgba(0, 123, 255, 0.1);
+            --selection-border: #007bff;
+          }
+
+          .dark-theme .knotx-container {
+            --node-bg: #2d3748;
+            --node-border: #4a5568;
+            --edge-stroke: #a0aec0;
+            --selection-bg: rgba(66, 153, 225, 0.1);
+            --selection-border: #4299e1;
+          }
+        `}
+      </style>
+    )
+  }
+}
+
+function App() {
+  return (
+    <div className="dark-theme">
+      <Knotx
+        initialNodes={[]}
+        initialEdges={[]}
+        plugins={[ThemePlugin]}
+      />
+    </div>
+  )
+}
+```
+
+## 📝 FAQ
+
+### Q: How to handle performance issues with large numbers of nodes?
+
+A: Use virtualization techniques to render only visible nodes:
+
+```tsx
+import { BasePlugin } from '@knotx/core'
+import { Knotx } from '@knotx/react'
+import React from 'react'
+
+// Implement virtualization plugin
+class VirtualizationPlugin extends BasePlugin<'virtualization'> {
+  name = 'virtualization' as const
+
+  // Implement virtualization logic
+  // ...
+}
+```
+
+### Q: How to implement custom connection points for nodes?
+
+A: Use the `@knotx/plugins-connection-line` plugin:
+
+```tsx
+import { ConnectionLine } from '@knotx/plugins-connection-line'
+
+// Add connection points in nodes
+function CustomNode({ node }) {
+  return (
+    <div>
+      <div
+        className="connection-handle"
+        data-handle-position="top"
+      />
+      Node content
+    </div>
+  )
+}
+```
+
+### Q: How to save and restore canvas state?
+
+A: Use the engine's data managers:
+
+```tsx
+function saveState(engine: ReactEngine) {
+  const state = {
+    nodes: Array.from(engine.nodesManager.dataMap$.value.values()),
+    edges: Array.from(engine.edgesManager.dataMap$.value.values()),
+    viewport: engine.container
+  }
+  localStorage.setItem('knotx-state', JSON.stringify(state))
+}
+
+function loadState(engine: ReactEngine) {
+  const state = JSON.parse(localStorage.getItem('knotx-state') || '{}')
+  // Restore state logic
+}
+```
+
+## 📄 License
+
+MIT License - See [LICENSE](https://github.com/boenfu/knotx/blob/main/LICENSE) file for details
+
+## 🤝 Contributing
+
+Pull requests and issues are welcome!
+
+## 🔗 Related Links
+
+- [GitHub Repository](https://github.com/boenfu/knotx)
+- [Online Examples](https://knotx.dev)
+- [API Documentation](https://knotx.dev/docs)
+- [Changelog](./CHANGELOG.md)