Diagram System

PinePaper’s Diagram System provides professional flowchart, UML, and network diagram capabilities with smart connectors, auto-layout, and diagram shapes.

Overview

The Diagram System is accessed via app.diagramSystem and includes:

• Shapes - Flowchart, UML, and network diagram shapes
• Ports - Connection points on shapes for attaching connectors
• Connectors - Smart lines that route between ports and update when shapes move
• Layouts - Automatic arrangement algorithms (hierarchical, force-directed, tree, radial, grid)

Beyond Standard Diagrams

While the system includes standard diagram shapes, connectors work with ANY canvas item:

• Images & SVGs - Import visual assets and connect them with stylish arrows
• Text Elements - Create visual sequences with connected text
• Custom Shapes - Use paths, circles, stars - anything you create
• Generator Output - Connect elements from procedural generators

This enables creative applications beyond traditional diagrams:

• Visual Storytelling - Connect scenes with animated transitions
• Infographics - Link data visualizations with flow arrows
• Process Flows - Show sequences using any visual elements
• Mind Maps - Connect ideas using images and text

Quick Start

// 1. Create some shapes
const start = app.diagramSystem.createShape('terminal', {
  position: new paper.Point(400, 100),
  label: 'Start'
});

const process = app.diagramSystem.createShape('process', {
  position: new paper.Point(400, 200),
  label: 'Process Data'
});

const decision = app.diagramSystem.createShape('decision', {
  position: new paper.Point(400, 320),
  label: 'Valid?'
});

// 2. Connect them
app.diagramSystem.connect(start, process);
app.diagramSystem.connect(process, decision);

// 3. Apply auto-layout
app.diagramSystem.applyLayout(null, 'hierarchical', {
  direction: 'TB',  // Top to Bottom
  levelSpacing: 100,
  nodeSpacing: 80
});

Activation & Modes

The diagram system can operate in different modes:

// Activate diagram mode (enables port visuals, grid, etc.)
app.diagramSystem.activate();

// Check if active
if (app.diagramSystem.isActive()) {
  console.log('Diagram mode is on');
}

// Deactivate
app.diagramSystem.deactivate();

// Toggle
app.diagramSystem.toggle();

Tool Modes

When diagram mode is active, you can switch between tools:

// Select mode - select and move shapes
app.diagramSystem.setMode('select');

// Connect mode - draw connections between ports
app.diagramSystem.setMode('connect');

// Shape mode - click to place shapes
app.diagramSystem.setMode('shape', { shapeType: 'process' });

// Pan mode - drag to pan the canvas
app.diagramSystem.setMode('pan');

Settings

Configure default connector and grid settings:

app.diagramSystem.updateSettings({
  // Connector defaults
  routing: 'orthogonal',      // 'direct', 'orthogonal', 'curved'
  lineColor: '#60a5fa',
  lineWidth: 3,
  headStyle: 'classic',       // 'classic', 'stealth', 'sharp', 'open', 'diamond', 'circle', 'none'
  headSize: 1.0,

  // Bolt animation
  boltEnabled: true,
  boltColor: '#fbbf24',
  boltSize: 2,
  boltSpeed: 1.0,

  // Grid
  snapToGrid: true,
  gridSize: 20,
  showGrid: true
});

Backward Compatibility

The Diagram System maintains full backward compatibility with the legacy ArrowSystem:

// Legacy arrow creation still works
app.diagramSystem.createArrow(
  [new paper.Point(100, 100), new paper.Point(300, 200)],
  { headStyle: 'classic', lineColor: '#3b82f6' }
);

// Legacy settings update
app.diagramSystem.updateArrowSettings({ lineWidth: 4 });

Subsystems

Serialization

Save and restore diagram state:

// Serialize current state
const diagramData = app.diagramSystem.serialize();
// Returns: { connectors: [...], ports: {...}, arrows: [...], settings: {...} }

// Restore state
app.diagramSystem.deserialize(diagramData);

// Clear all diagram elements
app.diagramSystem.clear();

Integration with Other Systems

The Diagram System integrates with:

• ItemRegistry - All shapes are registered for selection and queries
• HistoryManager - All operations support undo/redo
• ExportEngine - Connectors export to SVG with proper styling
• SceneManager - Diagram state is saved with scenes