@moxa/graph 2.7.5 → 2.8.0

package/README.md

@@ -6,6 +6,7 @@
 - [Basic Usage](#basic-usage)
 - [Graph Control](#graph-control)
 - [Event Handling](#event-handling)
+- [Developer Guidelines](#developer-guidelines)
 
 ## Install
 
@@ -146,3 +147,175 @@ graph.events.nodeClick.once((e) => { ... });
 graph.events.beginCreateEdge.on((e) => { ... });
 graph.events.groupExpanded.off((e) => { ... });
 ```
+
+## Developer Guidelines
+
+This section provides guidelines for developers who want to contribute to or extend the Moxa Graph library.
+
+### Project Structure
+
+```
+libs/graph/
+├── src/
+│   ├── lib/             # Core functionality
+│   │   ├── behavior/    # Graph behaviors and interactions
+│   │   ├── edge/        # Edge definitions and renderers
+│   │   ├── graph/       # Main graph implementation
+│   │   ├── group/       # Node grouping functionality
+│   │   ├── layout/      # Layout algorithms
+│   │   ├── model/       # Data models and types
+│   │   ├── node/        # Node definitions and renderers
+│   │   ├── plugin/      # Plugin system
+│   │   ├── themes/      # Theming and styling
+│   │   └── utils/       # Utility functions
+│   ├── assets/          # Static assets
+│   ├── styles/          # Global styles
+│   └── stories/         # Storybook examples
+```
+
+### Development Workflow
+
+1. **Setup Development Environment**
+
+   ```bash
+   # Clone the repository
+   git clone <repository-url>
+
+   # Install dependencies
+   pnpm install
+
+   # Start development server
+   pnpm dev
+   ```
+
+2. **Building the Library**
+
+   ```bash
+   # Build the library
+   pnpm build:graph
+
+   # Run tests
+   pnpm test:graph
+   ```
+
+### Extending the Library
+
+#### Creating Custom Nodes
+
+Custom nodes can be created by extending the base node classes:
+
+```typescript
+import { BaseNode, NodeConfig } from '@moxa/graph';
+
+interface CustomNodeConfig extends NodeConfig {
+  customProperty: string;
+}
+
+class CustomNode extends BaseNode<CustomNodeConfig> {
+  render() {
+    // Implement custom rendering logic
+    const shape = this.createShape('circle', {
+      r: 20,
+      fill: this.config.customProperty === 'special' ? 'red' : 'blue',
+    });
+
+    return shape;
+  }
+}
+
+// Register custom node
+graph.registerNode('custom-node', CustomNode);
+```
+
+#### Creating Custom Layouts
+
+```typescript
+import { BaseLayout, LayoutConfig } from '@moxa/graph';
+
+class CustomLayout extends BaseLayout {
+  layout() {
+    // Implement custom layout algorithm
+    this.nodes.forEach((node, index) => {
+      // Position nodes in a circle
+      const angle = (index / this.nodes.length) * Math.PI * 2;
+      const radius = 200;
+
+      node.updatePosition({
+        x: Math.cos(angle) * radius + this.width / 2,
+        y: Math.sin(angle) * radius + this.height / 2,
+      });
+    });
+  }
+}
+
+// Apply custom layout
+graph.changeLayout('custom', {
+  /* layout options */
+});
+```
+
+#### Creating Plugins
+
+```typescript
+import { BasePlugin, PluginConfig } from '@moxa/graph';
+
+class CustomPlugin extends BasePlugin {
+  init() {
+    // Setup plugin
+    this.graph.events.nodeClick.on(this.handleNodeClick);
+  }
+
+  handleNodeClick = (e) => {
+    // Implement custom behavior
+    console.log('Node clicked:', e.node.id);
+  };
+
+  destroy() {
+    // Clean up
+    this.graph.events.nodeClick.off(this.handleNodeClick);
+  }
+}
+
+// Add plugin to graph
+graph.addPlugin('custom', new CustomPlugin());
+```
+
+### Best Practices
+
+1. **Performance Considerations**
+
+   - Use throttling and debouncing for event handlers on large graphs
+   - Implement pagination or virtualization for very large datasets
+   - Consider using WebGL renderer for graphs with thousands of elements
+
+2. **Accessibility**
+
+   - Ensure proper contrast ratios in your themes
+   - Add ARIA attributes to important interactive elements
+   - Support keyboard navigation for critical operations
+
+3. **Testing**
+   - Write unit tests for custom components
+   - Create visual regression tests for custom node renders
+   - Test across different browsers and device sizes
+
+### Troubleshooting
+
+Common issues and their solutions:
+
+1. **Graph not rendering properly**
+
+   - Check if container has proper dimensions
+   - Verify data format follows required schema
+   - Check browser console for errors
+
+2. **Performance issues with large graphs**
+
+   - Try different renderers (SVG vs Canvas vs WebGL)
+   - Simplify node/edge renderers
+   - Use appropriate layout algorithms
+
+3. **Events not firing**
+   - Verify event listeners are properly attached
+   - Check if event propagation is being stopped
+   - Ensure targets exist when attaching listeners