refactor(wiki-graph): polish code, remove comments, add readme

Author: AdrianRomanski

apps/wiki-graph/src/app/d3/README.md

@@ -0,0 +1,40 @@
+# D3 Graph Renderer
+
+This directory contains the D3.js interactive force-directed graph engine for the **Wiki Graph** application. It renders entities, concepts, and **sources** as an interactive node-edge network diagram.
+
+---
+
+## 💡 Key Features & Functionality
+
+- **Interactive Force-Directed Layout**
+  - Uses physics-based simulation (repulsion, link strength, collision avoidance).
+  - Drag-and-drop nodes to explore connections interactively.
+  - Dynamically sizes nodes based on their number of connections.
+
+- **Visual Encoding & Styling**
+  - **Color-coded by type**: Entities (`orange`), Concepts (`cyan`), and Sources (`green`).
+  - **Ghost nodes**: Displayed with dashed borders for uncreated or referenced entities.
+  - **Directed arrows**: Indicate clear reference directions between items.
+
+- **Navigation & Exploration**
+  - **Zoom & Pan**: Smooth viewport zooming (0.1x to 8x) and canvas panning.
+  - **Node Highlight & Focus**: Selecting a node highlights its direct connections while dimming unrelated elements.
+  - **Visibility Filtering**: Easily show or hide subsets of nodes without resetting the layout state.
+
+- **Accessibility**
+  - Full keyboard navigation support (`Enter` / `Space` to select nodes).
+  - ARIA attributes on SVG elements for screen readers.
+
+---
+
+## 📁 Module Summary
+
+| File | Primary Function |
+| --- | --- |
+| [`d3-force-renderer.ts`](./d3-force-renderer.ts) | Main entry class (`D3ForceRenderer`) coordinating rendering, simulation lifecycle, and updates. |
+| [`force-simulation.ts`](./force-simulation.ts) | Configures D3 force simulation (charge, collision, links) and drag controls. |
+| [`graph-svg.ts`](./graph-svg.ts) | Handles SVG DOM generation for nodes, edges, arrow markers, and zoom behaviors. |
+| [`graph-state.ts`](./graph-state.ts) | Manages selection highlights, dimming effect, and visibility state updates. |
+| [`graph-data.ts`](./graph-data.ts) | Filters raw graph data into renderable nodes and links. |
+| [`graph-style.ts`](./graph-style.ts) | Visual constants (type color schemes, radii limits, dimming opacity). |
+| [`renderer.types.ts`](./renderer.types.ts) | TypeScript type aliases for D3 selections and simulation objects. |

apps/wiki-graph/src/app/d3/d3-force-renderer.ts

@@ -1,263 +1,67 @@
 import * as d3 from 'd3';
-import type { GraphData, GraphNode, SimulationNode } from '../models/graph.models';
+import type { GraphData } from '../models/graph.models';
+import { createVisibleGraph } from './graph-data';
+import { attachNodeDrag, createSimulation, updateSimulationPositions } from './force-simulation';
+import {
+  attachSvgInteractions,
+  createZoom,
+  renderArrowMarker,
+  renderEdges,
+  renderNodes,
+} from './graph-svg';
+import { updateSelection, updateVisibility } from './graph-state';
+import type { ForceSimulation, RootSelection, SvgSelection } from './renderer.types';
 
-/** Internal edge type used by the D3 simulation — uses source/target node references. */
-interface SimEdge extends d3.SimulationLinkDatum<SimulationNode> {
-  source: SimulationNode;
-  target: SimulationNode;
-}
-
-/** Fill colors per node type — Requirement 2.3 */
-const TYPE_COLORS: Record<string, string> = {
-  entity: '#F5A623',  // warm amber
-  concept: '#00BCD4', // vivid cyan
-  source: '#50C878',  // medium green (unchanged)
-};
-
-const BASE_RADIUS = 6;
-const MAX_RADIUS = 24;
-const DIM_OPACITY = 0.15;
-
-/**
- * Plain TypeScript class that owns all D3 logic.
- * Angular components never manipulate SVG nodes directly.
- * Requirements: 2.1–2.9, 3.1, 3.3
- */
 export class D3ForceRenderer {
-  private readonly svg: d3.Selection<SVGSVGElement, unknown, null, undefined>;
-  private readonly root: d3.Selection<SVGGElement, unknown, null, undefined>;
-  private simulation: d3.Simulation<SimulationNode, SimEdge> | null = null;
-  private zoom: d3.ZoomBehavior<SVGSVGElement, unknown>;
+  private readonly svg: SvgSelection;
+  private readonly root: RootSelection;
+  private readonly zoom: d3.ZoomBehavior<SVGSVGElement, unknown>;
+  private simulation: ForceSimulation | null = null;
 
   constructor(
     private readonly svgElement: SVGSVGElement,
-    private readonly onNodeClick: (id: string | null) => void
+    private readonly onNodeClick: (id: string | null) => void,
   ) {
     this.svg = d3.select(svgElement);
-
-    // Root group — all graph elements live here so zoom/pan transforms apply
     this.root = this.svg.append('g').attr('class', 'graph-root');
-
-    // Zoom & pan — Requirements 2.7, 2.8
-    this.zoom = d3.zoom<SVGSVGElement, unknown>()
-      .scaleExtent([0.1, 8])
-      .on('zoom', (event: d3.D3ZoomEvent<SVGSVGElement, unknown>) => {
-        this.root.attr('transform', event.transform.toString());
-      });
-
-    this.svg
-      .call(this.zoom)
-      // Background click deselects — Requirement 3.4
-      .on('click', (event: MouseEvent) => {
-        if (event.target === svgElement || (event.target as Element).tagName === 'svg') {
-          this.onNodeClick(null);
-        }
-      });
+    this.zoom = createZoom(this.root);
+    attachSvgInteractions(this.svg, svgElement, this.zoom, onNodeClick);
   }
 
-  /**
-   * (Re)renders the graph with the given data and visibility set.
-   * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.9
-   */
   render(data: GraphData, visibleNodeIds: Set<string>): void {
-    // Stop any running simulation
     this.simulation?.stop();
-
-    // Clear previous render
     this.root.selectAll('*').remove();
 
     const width = this.svgElement.clientWidth || 800;
     const height = this.svgElement.clientHeight || 600;
-
-    const allNodes = Array.from(data.nodes.values()) as SimulationNode[];
-    const visibleNodes = allNodes.filter(n => visibleNodeIds.size === 0 || visibleNodeIds.has(n.id));
-
-    const visibleIds = new Set(visibleNodes.map(n => n.id));
-    const visibleEdges = data.edges.filter(
-      e => visibleIds.has(e.sourceId) && visibleIds.has(e.targetId)
+    const graph = createVisibleGraph(data, visibleNodeIds);
+    const edges = renderEdges(this.root, graph.edges);
+    renderArrowMarker(this.svg);
+    const nodes = renderNodes(this.root, graph.nodes, this.onNodeClick);
+
+    attachNodeDrag(nodes, () => this.simulation);
+    this.simulation = createSimulation(
+      graph.nodes,
+      graph.edges,
+      width,
+      height,
+      () => updateSimulationPositions(edges, nodes),
     );
-
-    // Build edge objects D3 can use (source/target as node references)
-    const nodeById = new Map(visibleNodes.map(n => [n.id, n]));
-    const simEdges: SimEdge[] = visibleEdges
-      .map(e => ({ source: nodeById.get(e.sourceId)!, target: nodeById.get(e.targetId)! }))
-      .filter((e): e is SimEdge => !!e.source && !!e.target);
-
-    // Edges layer
-    const edgeGroup = this.root.append('g').attr('class', 'edges');
-    const edgeSel = edgeGroup
-      .selectAll<SVGLineElement, SimEdge>('line')
-      .data(simEdges)
-      .join('line')
-      .attr('class', 'edge')
-      .attr('stroke', '#585b70')
-      .attr('stroke-width', 1)
-      .attr('stroke-opacity', 0.6)
-      .attr('marker-end', 'url(#arrow)');
-
-    // Arrow marker
-    this.svg.select('defs').remove();
-    this.svg.append('defs').append('marker')
-      .attr('id', 'arrow')
-      .attr('viewBox', '0 -5 10 10')
-      .attr('refX', 18)
-      .attr('refY', 0)
-      .attr('markerWidth', 6)
-      .attr('markerHeight', 6)
-      .attr('orient', 'auto')
-      .append('path')
-      .attr('d', 'M0,-5L10,0L0,5')
-      .attr('fill', '#585b70');
-
-    // Nodes layer
-    const nodeGroup = this.root.append('g').attr('class', 'nodes');
-    const nodeSel = nodeGroup
-      .selectAll<SVGGElement, SimulationNode>('g.node')
-      .data(visibleNodes, d => d.id)
-      .join('g')
-      .attr('class', 'node')
-      .attr('role', 'button')
-      .attr('tabindex', '0')
-      .attr('aria-label', d => `${d.title} (${d.type})`)
-      .style('cursor', 'pointer');
-
-    // Circle — Requirement 2.3, 2.4, 2.9
-    nodeSel.append('circle')
-      .attr('r', d => this.nodeRadius(d))
-      .attr('fill', d => d.isGhost ? 'none' : (TYPE_COLORS[d.type] ?? '#888'))
-      .attr('stroke', d => d.isGhost ? (TYPE_COLORS[d.type] ?? '#888') : 'none')
-      .attr('stroke-width', d => d.isGhost ? 2 : 0)
-      .attr('stroke-dasharray', d => d.isGhost ? '4 2' : 'none')
-      .attr('opacity', d => d.isGhost ? 0.4 : 1);
-
-    // Label — Requirement 2.5
-    nodeSel.append('text')
-      .attr('dy', d => this.nodeRadius(d) + 12)
-      .attr('text-anchor', 'middle')
-      .attr('font-size', '10px')
-      .attr('fill', '#a6adc8')
-      .attr('pointer-events', 'none')
-      .text(d => d.title.length > 20 ? d.title.slice(0, 18) + '…' : d.title);
-
-    // Click handler — Requirement 3.1
-    nodeSel.on('click', (event: MouseEvent, d: SimulationNode) => {
-      event.stopPropagation();
-      this.onNodeClick(d.id);
-    });
-
-    // Keyboard activation
-    nodeSel.on('keydown', (event: KeyboardEvent, d: SimulationNode) => {
-      if (event.key === 'Enter' || event.key === ' ') {
-        event.preventDefault();
-        this.onNodeClick(d.id);
-      }
-    });
-
-    // Drag — Requirement 2.6
-    const drag = d3.drag<SVGGElement, SimulationNode>()
-      .on('start', (event, d) => {
-        if (!event.active) this.simulation?.alphaTarget(0.3).restart();
-        d.fx = d.x;
-        d.fy = d.y;
-      })
-      .on('drag', (event, d) => {
-        d.fx = event.x;
-        d.fy = event.y;
-      })
-      .on('end', (event, d) => {
-        if (!event.active) this.simulation?.alphaTarget(0);
-        d.fx = null;
-        d.fy = null;
-      });
-
-    nodeSel.call(drag);
-
-    // Force simulation — Requirement 2.1
-    this.simulation = d3.forceSimulation<SimulationNode, SimEdge>(visibleNodes)
-      .force('link', d3.forceLink<SimulationNode, SimEdge>(simEdges)
-        .id(d => d.id)
-        .distance(80))
-      .force('charge', d3.forceManyBody().strength(-200))
-      .force('center', d3.forceCenter(width / 2, height / 2))
-      .force('collision', d3.forceCollide<SimulationNode>().radius(d => this.nodeRadius(d) + 4))
-      .on('tick', () => {
-        edgeSel
-          .attr('x1', d => d.source.x ?? 0)
-          .attr('y1', d => d.source.y ?? 0)
-          .attr('x2', d => d.target.x ?? 0)
-          .attr('y2', d => d.target.y ?? 0);
-
-        nodeSel.attr('transform', d => `translate(${d.x ?? 0},${d.y ?? 0})`);
-      });
   }
 
-  /**
-   * Highlights the selected node and dims unconnected nodes/edges.
-   * Requirement 3.1, 3.3
-   */
   updateSelection(selectedId: string | null): void {
-    if (!selectedId) {
-      // Restore default state
-      this.root.selectAll<SVGGElement, SimulationNode>('g.node')
-        .style('opacity', null);
-      this.root.selectAll<SVGLineElement, SimEdge>('line.edge')
-        .style('opacity', null)
-        .attr('stroke', '#585b70');
-      this.root.selectAll<SVGCircleElement, SimulationNode>('g.node circle')
-        .attr('stroke', d => d.isGhost ? (TYPE_COLORS[d.type] ?? '#888') : 'none')
-        .attr('stroke-width', d => d.isGhost ? 2 : 0);
-      return;
-    }
-
-    // Collect connected node ids
-    const connectedIds = new Set<string>([selectedId]);
-    this.root.selectAll<SVGLineElement, SimEdge>('line.edge')
-      .each(d => {
-        if (d.source.id === selectedId) connectedIds.add(d.target.id);
-        if (d.target.id === selectedId) connectedIds.add(d.source.id);
-      });
-
-    // Dim unconnected nodes
-    this.root.selectAll<SVGGElement, SimulationNode>('g.node')
-      .style('opacity', d => connectedIds.has(d.id) ? null : String(DIM_OPACITY));
-
-    // Dim unconnected edges
-    this.root.selectAll<SVGLineElement, SimEdge>('line.edge')
-      .style('opacity', d =>
-        d.source.id === selectedId || d.target.id === selectedId ? null : String(DIM_OPACITY)
-      );
-
-    // Selection ring on selected node
-    this.root.selectAll<SVGCircleElement, SimulationNode>('g.node circle')
-      .attr('stroke', d => d.id === selectedId ? '#f5c2e7' : (d.isGhost ? (TYPE_COLORS[d.type] ?? '#888') : 'none'))
-      .attr('stroke-width', d => d.id === selectedId ? 3 : (d.isGhost ? 2 : 0));
+    updateSelection(this.root, selectedId);
   }
 
-  /**
-   * Shows/hides nodes and their connected edges based on the visibility set.
-   * Requirement 4.2
-   */
   updateVisibility(visibleNodeIds: Set<string>): void {
-    this.root.selectAll<SVGGElement, SimulationNode>('g.node')
-      .style('display', d => visibleNodeIds.has(d.id) ? null : 'none');
-
-    this.root.selectAll<SVGLineElement, SimEdge>('line.edge')
-      .style('display', d =>
-        visibleNodeIds.has(d.source.id) && visibleNodeIds.has(d.target.id) ? null : 'none'
-      );
+    updateVisibility(this.root, visibleNodeIds);
   }
 
-  /** Stops simulation and removes all event listeners. */
   destroy(): void {
     this.simulation?.stop();
     this.simulation = null;
     this.svg.on('.zoom', null);
     this.svg.on('click', null);
     this.root.selectAll('*').remove();
   }
-
-  private nodeRadius(node: GraphNode): number {
-    const connections = node.inDegree + node.outDegree;
-    return Math.min(MAX_RADIUS, BASE_RADIUS + Math.sqrt(connections) * 2);
-  }
 }