doc and tests for auto layout hook

Author: AgusDropOut

src/core/hooks/useAutoLayout.ts

@@ -13,35 +13,51 @@ interface UseAutoLayoutProps {
 const NODE_WIDTH = 220; 
 const NODE_HEIGHT = 150;
 
+/**
+ * Automatically organizes the visual graph using the Dagre directed acyclic graph layout algorithm.
+ * Translates Dagre's center-based coordinates into React Flow's top-left based coordinates.
+ *
+ * @param props.nodes - The current array of nodes to be measured.
+ * @param props.edges - The current array of edges to determine layout hierarchy.
+ * @param props.setNodes - State setter to apply the newly calculated coordinates.
+ * @param props.takeSnapshot - History callback invoked before mutation to allow user undo.
+ */
 export function useAutoLayout({ nodes, edges, setNodes, takeSnapshot }: UseAutoLayoutProps) {
 
+    /**
+     * Executes the layout algorithm.
+     * @param direction - The flow direction of the graph. 'LR' (Left-to-Right) or 'TB' (Top-to-Bottom).
+     */
     const autoLayout = useCallback((direction = 'LR') => {
-       
+        
+        /* Captures state for the undo stack before overwriting coordinates */
         takeSnapshot();
 
-        
         const dagreGraph = new dagre.graphlib.Graph();
         dagreGraph.setDefaultEdgeLabel(() => ({}));
 
         dagreGraph.setGraph({ rankdir: direction, ranksep: 120, nodesep: 60 });
 
-      
+        /* Feeds the nodes and expected dimensions into the engine */
         nodes.forEach((node) => {
             dagreGraph.setNode(node.id, { width: NODE_WIDTH, height: NODE_HEIGHT });
         });
+        
+        /* Feeds the hierarchy/connections */
         edges.forEach((edge) => {
             dagreGraph.setEdge(edge.source, edge.target);
         });
 
-        
+        /* Executes the mathematical layout calculation */
         dagre.layout(dagreGraph);
 
-        
+        /* Translates the coordinates back to the React Flow format */
         const layoutedNodes = nodes.map((node) => {
             const nodeWithPosition = dagreGraph.node(node.id);
             return {
                 ...node,
                 position: {
+                    /* Dagre returns the exact center. React Flow requires the top-left corner. */
                     x: nodeWithPosition.x - NODE_WIDTH / 2,
                     y: nodeWithPosition.y - NODE_HEIGHT / 2,
                 },

tests/unit/useAutoLayout.spec.ts

@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+// tests/unit/useAutoLayout.spec.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useAutoLayout } from '../../src/core/hooks/useAutoLayout';
+import type { Node, Edge } from 'reactflow';
+
+/* Isolate the mathematical dependency. 
+ * We mock Dagre using an actual ES6 class so the `new` keyword works perfectly.
+ */
+const mockSetGraph = vi.fn();
+
+vi.mock('dagre', () => {
+    class MockGraph {
+        setDefaultEdgeLabel = vi.fn();
+        setGraph = mockSetGraph;
+        setNode = vi.fn();
+        setEdge = vi.fn();
+        node = vi.fn(() => ({ x: 500, y: 500 })); // Force predictable output
+    }
+
+    return {
+        default: {
+            graphlib: { Graph: MockGraph },
+            layout: vi.fn()
+        },
+        // Flat exports catch edge cases where the test runner drops the 'default' wrapper
+        graphlib: { Graph: MockGraph },
+        layout: vi.fn()
+    };
+});
+
+describe('useAutoLayout Hook', () => {
+    
+    const mockSetNodes = vi.fn();
+    const mockTakeSnapshot = vi.fn();
+
+    const mockNodes: Node[] = [
+        { id: 'n1', position: { x: 0, y: 0 }, data: {} },
+        { id: 'n2', position: { x: -100, y: -200 }, data: {} }
+    ];
+
+    const mockEdges: Edge[] = [
+        { id: 'e1', source: 'n1', target: 'n2' }
+    ];
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it('triggers a history snapshot prior to modifying node coordinates', () => {
+        const { result } = renderHook(() => useAutoLayout({
+            nodes: mockNodes,
+            edges: mockEdges,
+            setNodes: mockSetNodes,
+            takeSnapshot: mockTakeSnapshot
+        }));
+
+        act(() => {
+            result.current.autoLayout();
+        });
+
+        /* The history snapshot MUST fire before the nodes are updated */
+        expect(mockTakeSnapshot).toHaveBeenCalledTimes(1);
+        expect(mockSetNodes).toHaveBeenCalledTimes(1);
+        
+        /* Validates execution order: Snapshot -> Update */
+        const snapshotOrder = mockTakeSnapshot.mock.invocationCallOrder[0];
+        const updateOrder = mockSetNodes.mock.invocationCallOrder[0];
+        expect(snapshotOrder).toBeLessThan(updateOrder);
+    });
+
+    it('translates Dagre center coordinates to React Flow top-left coordinates', () => {
+        const { result } = renderHook(() => useAutoLayout({
+            nodes: mockNodes,
+            edges: mockEdges,
+            setNodes: mockSetNodes,
+            takeSnapshot: mockTakeSnapshot
+        }));
+
+        act(() => {
+            result.current.autoLayout();
+        });
+
+        const appliedNodes = mockSetNodes.mock.calls[0][0];
+        
+        /* Expected offset mathematics:
+         * Dagre Center: x: 500, y: 500
+         * Width (220) / 2 = 110. 500 - 110 = 390
+         * Height (150) / 2 = 75. 500 - 75 = 425
+         */
+        expect(appliedNodes[0].position.x).toBe(390);
+        expect(appliedNodes[0].position.y).toBe(425);
+        expect(appliedNodes[1].position.x).toBe(390);
+        expect(appliedNodes[1].position.y).toBe(425);
+    });
+
+    it('respects layout direction overrides', () => {
+        const { result } = renderHook(() => useAutoLayout({
+            nodes: mockNodes,
+            edges: mockEdges,
+            setNodes: mockSetNodes,
+            takeSnapshot: mockTakeSnapshot
+        }));
+
+        act(() => {
+            result.current.autoLayout('TB'); // Top-to-Bottom
+        });
+
+        expect(mockSetGraph).toHaveBeenCalledWith(
+            expect.objectContaining({ rankdir: 'TB' })
+        );
+    });
+});