p2ns/plugin-sites/peer.visualize/VIS_NETWORK_MIGRATION.md

Migration Guide: D3.js to vis-network

Quick Migration Steps

1. Add vis-network to HTML

In plugin-sites/peer.visualize/www/index.html, replace or add:

<!-- Remove or comment out D3.js -->
<!-- <script src="https://d3js.org/d3.v7.min.js"></script> -->

<!-- Add vis-network -->
<script type="text/javascript" src="https://unpkg.com/vis-network@latest/standalone/umd/vis-network.min.js"></script>

2. Replace ForceGraph Implementation

Replace plugin-sites/peer.visualize/www/js/visualization/force-graph.js with the example in force-graph-vis-network-example.js.

3. Key Differences

D3.js Approach:

• Manual SVG manipulation
• Manual force simulation management
• Manual drag handlers
• Manual position tracking

vis-network Approach:

• Automatic rendering and updates
• Built-in physics engine
• Built-in drag/zoom/pan
• Automatic position preservation on updates

4. Benefits of vis-network

1. No Freezing Issues: vis-network handles updates smoothly without interfering with drag operations
2. Better Performance: Optimized for large networks
3. Less Code: ~200 lines vs ~350 lines
4. Built-in Features:
   • Smooth animations
   • Automatic stabilization
   • Better drag handling
   • Built-in zoom/pan

5. Configuration Options

The example includes basic configuration. You can customize:

const options = {
  physics: {
    barnesHut: {
      gravitationalConstant: -300,  // Node repulsion
      springLength: 150,              // Link length
      springConstant: 0.04,           // Link stiffness
      damping: 0.09                   // Movement damping
    }
  },
  nodes: {
    size: 16,                         // Node size
    font: { size: 11 },               // Label size
    shape: 'dot'                      // 'dot', 'circle', 'box', etc.
  }
};

6. Testing

After migration:

1. Test node dragging - should be smooth
2. Test WebSocket updates - should not freeze
3. Test zoom/pan - should work smoothly
4. Test node clicks - should open profile modal

7. Optional: Add vis-network CSS

For better styling, you can add:

<link href="https://unpkg.com/vis-network@latest/styles/vis-network.min.css" rel="stylesheet" type="text/css" />

But it's optional - the example works without it.

Example Usage

The API remains the same:

const graph = new ForceGraph(container);
graph.updateData(data);
graph.updateTopology(data);
graph.updatePeerProperties(peers);
graph.applyFilters(filters);

Migration Checklist

• Add vis-network script to index.html
• Replace force-graph.js with vis-network version
• Test node dragging
• Test WebSocket updates
• Test zoom/pan
• Test node clicks
• Remove D3.js dependency (if not used elsewhere)
• Update domain-map.js if needed (can use same approach)