@principal-ai/principal-view-react 0.14.4 → 0.14.6

package/src/hooks/useElkLayout.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Tests for useElkLayout hook utilities
+ */
+
+import { describe, test, expect } from 'bun:test';
+import type { Edge } from '@xyflow/react';
+import { applyElkPathsToEdges } from './useElkLayout';
+
+describe('useElkLayout utilities', () => {
+  describe('applyElkPathsToEdges', () => {
+    const createEdge = (id: string, source: string, target: string): Edge => ({
+      id,
+      source,
+      target,
+    });
+
+    test('should return original edges when edgePaths is empty', () => {
+      const edges = [createEdge('e1', 'a', 'b')];
+      const edgePaths = new Map<string, string>();
+      const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result).toEqual(edges);
+      expect(result[0].data?.elkPath).toBeUndefined();
+    });
+
+    test('should inject elkPath into edge data', () => {
+      const edges = [createEdge('e1', 'a', 'b')];
+      const edgePaths = new Map([['e1', 'M 0 0 L 100 100']]);
+      const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result[0].data?.elkPath).toBe('M 0 0 L 100 100');
+    });
+
+    test('should inject elkLabelPosition into edge data', () => {
+      const edges = [createEdge('e1', 'a', 'b')];
+      const edgePaths = new Map([['e1', 'M 0 0 L 100 100']]);
+      const edgeLabelPositions = new Map([['e1', { x: 50, y: 50 }]]);
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result[0].data?.elkLabelPosition).toEqual({ x: 50, y: 50 });
+    });
+
+    test('should preserve existing edge data', () => {
+      const edges: Edge[] = [
+        {
+          id: 'e1',
+          source: 'a',
+          target: 'b',
+          data: { customField: 'value', edgeType: 'flow' },
+        },
+      ];
+      const edgePaths = new Map([['e1', 'M 0 0 L 100 100']]);
+      const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result[0].data?.customField).toBe('value');
+      expect(result[0].data?.edgeType).toBe('flow');
+      expect(result[0].data?.elkPath).toBe('M 0 0 L 100 100');
+    });
+
+    test('should only modify edges that have corresponding paths', () => {
+      const edges = [
+        createEdge('e1', 'a', 'b'),
+        createEdge('e2', 'b', 'c'),
+        createEdge('e3', 'c', 'd'),
+      ];
+      const edgePaths = new Map([
+        ['e1', 'M 0 0 L 100 0'],
+        ['e3', 'M 200 0 L 300 0'],
+        // e2 has no path
+      ]);
+      const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result[0].data?.elkPath).toBe('M 0 0 L 100 0');
+      expect(result[1].data?.elkPath).toBeUndefined();
+      expect(result[2].data?.elkPath).toBe('M 200 0 L 300 0');
+    });
+
+    test('should handle edges with undefined data', () => {
+      const edges: Edge[] = [
+        { id: 'e1', source: 'a', target: 'b', data: undefined },
+      ];
+      const edgePaths = new Map([['e1', 'M 0 0 L 100 100']]);
+      const edgeLabelPositions = new Map([['e1', { x: 50, y: 50 }]]);
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result[0].data?.elkPath).toBe('M 0 0 L 100 100');
+      expect(result[0].data?.elkLabelPosition).toEqual({ x: 50, y: 50 });
+    });
+
+    test('should return new array without mutating original', () => {
+      const edges = [createEdge('e1', 'a', 'b')];
+      const edgePaths = new Map([['e1', 'M 0 0 L 100 100']]);
+      const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      // Result should be a new array
+      expect(result).not.toBe(edges);
+      // Original edge should not be modified
+      expect(edges[0].data).toBeUndefined();
+    });
+
+    test('should handle complex path strings', () => {
+      const edges = [createEdge('e1', 'a', 'b')];
+      const complexPath = 'M 120 30 L 142 30 Q 150 30 150 38 L 150 72 Q 150 80 158 80 L 250 80';
+      const edgePaths = new Map([['e1', complexPath]]);
+      const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result[0].data?.elkPath).toBe(complexPath);
+    });
+
+    test('should handle empty edges array', () => {
+      const edges: Edge[] = [];
+      const edgePaths = new Map([['e1', 'M 0 0 L 100 100']]);
+      const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+
+      const result = applyElkPathsToEdges(edges, edgePaths, edgeLabelPositions);
+
+      expect(result).toEqual([]);
+    });
+  });
+});

package/src/hooks/useElkLayout.ts

@@ -0,0 +1,191 @@
+/**
+ * React hook for ELK layout integration
+ *
+ * Provides automatic edge routing with circuit-board style paths.
+ */
+
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import type { Node, Edge } from '@xyflow/react';
+import { computeElkLayout, type ElkLayoutOptions } from '../utils/elkLayout';
+
+export interface UseElkLayoutOptions extends ElkLayoutOptions {
+  /**
+   * Whether ELK layout is enabled
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Debounce delay in ms before recomputing layout
+   * @default 100
+   */
+  debounceMs?: number;
+}
+
+export interface UseElkLayoutResult {
+  /** Edge paths computed by ELK, keyed by edge ID */
+  edgePaths: Map<string, string>;
+  /** Edge label positions computed by ELK, keyed by edge ID */
+  edgeLabelPositions: Map<string, { x: number; y: number }>;
+  /** Whether layout is currently being computed */
+  isLayouting: boolean;
+  /** Any error that occurred during layout */
+  error: Error | null;
+  /** Manually trigger a layout recomputation */
+  recomputeLayout: () => void;
+}
+
+/**
+ * Hook for computing ELK layout for edges
+ *
+ * @param nodes - xyflow nodes
+ * @param edges - xyflow edges
+ * @param options - Layout options
+ * @returns Layout result with edge paths
+ *
+ * @example
+ * ```tsx
+ * const { edgePaths, isLayouting } = useElkLayout(nodes, edges, {
+ *   routingStyle: 'orthogonal',
+ *   edgeSpacing: 15,
+ * });
+ * ```
+ */
+export function useElkLayout(
+  nodes: Node[],
+  edges: Edge[],
+  options: UseElkLayoutOptions = {}
+): UseElkLayoutResult {
+  const { enabled = true, debounceMs = 100, ...layoutOptions } = options;
+
+  const [edgePaths, setEdgePaths] = useState<Map<string, string>>(new Map());
+  const [edgeLabelPositions, setEdgeLabelPositions] = useState<Map<string, { x: number; y: number }>>(
+    new Map()
+  );
+  const [isLayouting, setIsLayouting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const abortRef = useRef<boolean>(false);
+  const hasComputedRef = useRef<string | null>(null);
+
+  // Create stable refs for nodes and edges
+  const nodesRef = useRef(nodes);
+  nodesRef.current = nodes;
+  const edgesRef = useRef(edges);
+  edgesRef.current = edges;
+
+  // Create a stable reference to layout options
+  const optionsRef = useRef(layoutOptions);
+  optionsRef.current = layoutOptions;
+
+  // Create a stable key based on node/edge structure
+  const layoutKey = useMemo(() => {
+    const nodeKey = nodes.map(n => `${n.id}:${n.position.x}:${n.position.y}:${n.width ?? 0}:${n.height ?? 0}`).join('|');
+    const edgeKey = edges.map(e => `${e.id}:${e.source}:${e.target}`).join('|');
+    return `${enabled}:${nodeKey}:${edgeKey}`;
+  }, [enabled, nodes, edges]);
+
+  // Compute layout when key changes
+  useEffect(() => {
+    // Skip if already computed for this key
+    if (hasComputedRef.current === layoutKey) {
+      return;
+    }
+
+    if (!enabled || nodesRef.current.length === 0) {
+      setEdgePaths(new Map());
+      setEdgeLabelPositions(new Map());
+      hasComputedRef.current = layoutKey;
+      return;
+    }
+
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+
+    abortRef.current = false;
+
+    timeoutRef.current = setTimeout(async () => {
+      setIsLayouting(true);
+      setError(null);
+
+      try {
+        const result = await computeElkLayout(nodesRef.current, edgesRef.current, optionsRef.current);
+
+        if (abortRef.current) return;
+
+        setEdgePaths(result.edgePaths);
+        setEdgeLabelPositions(result.edgeLabelPositions);
+        hasComputedRef.current = layoutKey;
+      } catch (err) {
+        if (!abortRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          console.error('ELK layout error:', err);
+        }
+      } finally {
+        if (!abortRef.current) {
+          setIsLayouting(false);
+        }
+      }
+    }, debounceMs);
+
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+      abortRef.current = true;
+    };
+  }, [layoutKey, enabled, debounceMs]);
+
+  const recomputeLayout = useCallback(() => {
+    hasComputedRef.current = null; // Force recompute
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    // Trigger effect by invalidating the key check
+    setIsLayouting(true);
+  }, []);
+
+  return {
+    edgePaths,
+    edgeLabelPositions,
+    isLayouting,
+    error,
+    recomputeLayout,
+  };
+}
+
+/**
+ * Apply ELK-computed paths to edges
+ *
+ * This utility injects the ELK path data into edge data so CustomEdge can use it.
+ *
+ * @param edges - Original edges
+ * @param edgePaths - ELK-computed paths
+ * @param edgeLabelPositions - ELK-computed label positions
+ * @returns Edges with ELK path data injected
+ */
+export function applyElkPathsToEdges<T extends Edge>(
+  edges: T[],
+  edgePaths: Map<string, string>,
+  edgeLabelPositions: Map<string, { x: number; y: number }>
+): T[] {
+  return edges.map((edge) => {
+    const elkPath = edgePaths.get(edge.id);
+    const elkLabelPosition = edgeLabelPositions.get(edge.id);
+
+    if (elkPath) {
+      return {
+        ...edge,
+        data: {
+          ...edge.data,
+          elkPath,
+          elkLabelPosition,
+        },
+      };
+    }
+
+    return edge;
+  });
+}

package/src/index.ts

@@ -96,3 +96,9 @@ export {
 } from './utils/orientationUtils';
 export { getCanvasBounds, getCanvasDisplaySize, calculateInitialViewport } from './utils/canvasBounds';
 export type { CanvasBounds, Viewport } from './utils/canvasBounds';
+
+// ELK layout utilities for circuit-board style edge routing
+export { computeElkLayout, createElkLayouter } from './utils/elkLayout';
+export type { ElkLayoutOptions, ElkLayoutResult, ElkRoutingStyle } from './utils/elkLayout';
+export { useElkLayout, applyElkPathsToEdges } from './hooks/useElkLayout';
+export type { UseElkLayoutOptions, UseElkLayoutResult } from './hooks/useElkLayout';

package/src/nodes/otel/OtelSpanConventionNode.tsx

@@ -144,9 +144,9 @@ export const OtelSpanConventionNode: React.FC<
   const stateDefinitions = nodeData.states || typeDefinition.states;
 
   // Workflow chips
-  const workflowChips = nodeData.workflowChips;
-  const onWorkflowChipClick = nodeData.onWorkflowChipClick;
-  const selectedWorkflowId = nodeData.selectedWorkflowId;
+  const workflowChips = nodeData?.workflowChips;
+  const onWorkflowChipClick = nodeData?.onWorkflowChipClick;
+  const selectedWorkflowId = nodeData?.selectedWorkflowId;
 
   // Animation class
   const getAnimationClass = () => {