ng-diagram

The ng-diagram API is organized into several functional categories to help you build and customize diagramming interfaces in Angular:

• Components: UI building blocks like NgDiagramComponent (the main container), NgDiagramMinimapComponent, and various node/edge decoration components.
• Directives: Behavior modifiers such as NgDiagramNodeSelectedDirective for handling selection states.
• Services: Core logic providers including NgDiagramService for general interaction, NgDiagramModelService for data management, and NgDiagramSelectionService for managing selected elements.
• Types: Comprehensive type definitions covering Configuration (e.g., NgDiagramConfig), Events (e.g., NodeDragEndedEvent), Model (e.g., Node, Edge), Geometry (e.g., Point, Rect), and Middleware.
• Utilities: Helper functions for setup, such as provideNgDiagram() for dependency injection and initializeModel() for data loading.

The ng-diagram roadmap tracks the development progress of the library, including completed features, work in progress, and upcoming tasks.

Completed Features (v1.0):

• Core Stability: Stable v1.0 release and Angular 18 support.
• Navigation & UI: Minimap (overview navigation widget), Box Selection (rectangular multi-select tool), and Grid Background (configurable grid pattern).
• Interaction: Touch & Trackpad input support, Shortcut Manager (centralized keyboard shortcuts), and Direct Node Connections (connecting nodes without explicit ports).
• Diagram Components: Port Labels, Default Edge Labels, and Lookup Helpers (e.g., getConnectedEdges).
• Integrations: MCP Server (Model Context Protocol for AI assistants).
• Events: Additional hooks such as model loaded and object removed.

In Progress:

• Templates: Electrical and AV (Audio-Video) demo templates.
• API Enhancements: Invalidate Measurements API to programmatically invalidate node/edge measurements.
• Feature Development: Edge Reshaping (interactive editing of edge paths and waypoints).

Upcoming:

• Collecting user feedback to shape future development.

ngDiagram is organized into several distinct layers that separate concerns:

• Components Layer: User-facing Angular components that render the diagram and handle interactions (e.g., ng-diagram, ng-diagram-port, ng-diagram-base-node-template).
• Service Layer: Specialized services providing control over state and functionality (e.g., NgDiagramService for middleware/routing, NgDiagramModelService for data access, NgDiagramSelectionService for selection state).
• Event Layer: Captures user interactions and translates them into commands via NgDiagramComponent outputs.
• Command System: Provides structured instructions (e.g., moveNode, addEdge) that act as the bridge between events and model updates.
• Middleware System: A plugin architecture that intercepts commands for validation, transformation, or side effects.
• Data Model: The foundation storing the state of Nodes, Edges, and Metadata using Angular signals for reactivity.

You can integrate external layout engines (such as ELK.js) to handle complex node positioning and edge routing.

When using an external library:

1. The library calculates and assigns a position to each node.
2. The library generates edge paths automatically.
3. To ensure the diagram respects these calculated paths, set the edges to manual mode using RoutingMode.manual. This prevents the built-in engine from overriding the custom layout points provided by the external library.

If a user manually moves a node, you should reset the edges back to auto mode to allow the built-in routing to recalculate based on the new positions.

// Conceptual workflow for external layout integration

// 1. Run external layout (e.g., ELK.js)
const layoutResult = await elk.layout(nodes, edges);

// 2. Update nodes with new positions
modelAdapter.updateNodes(layoutResult.nodes);

// 3. Set edges to manual mode to preserve external paths
modelAdapter.updateEdges(edges.map(edge => ({
  ...edge,
  routingMode: RoutingMode.manual
})));

// 4. Handle manual user movement
// Listen for selectionMoved to detect when a user drags a node
// and reset routing to auto
if (event.type === 'selectionMoved') {
  modelAdapter.updateEdges(edges.map(edge => ({
    ...edge,
    routingMode: RoutingMode.auto
  })));
}