@principal-ai/subsystems-react 0.17.0

package/src/graphify/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Graphify graph.json schema types.
+ *
+ * Mirrors the graphify data model (graphify/validate.py, graphify/export.py)
+ * so graphify output can be consumed by this library in a type-compatible way.
+ */
+
+/** Any JSON-serializable value carried in node/edge metadata. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** Node classification (graphify/validate.py VALID_FILE_TYPES). */
+export type GraphifyFileType = 'code' | 'document' | 'paper' | 'image' | 'rationale' | 'concept';
+
+/** Edge provenance tag (graphify/validate.py VALID_CONFIDENCES). */
+export type GraphifyConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+/** Optional semantic kind carried on nodes (e.g. `module`, `namespace`). */
+export type GraphifyNodeType = 'module' | 'namespace' | string;
+
+/** Canonical relation verbs emitted by graphify extractors and resolvers. */
+export type GraphifyRelation =
+  | 'calls'
+  | 'imports'
+  | 'imports_from'
+  | 're_exports'
+  | 'references'
+  | 'inherits'
+  | 'implements'
+  | 'mixes_in'
+  | 'uses'
+  | 'contains'
+  | 'defines'
+  | 'method'
+  | 'decorator'
+  | 'rationale_for'
+  | 'semantically_similar_to'
+  | string;
+
+/**
+ * A graphify node.
+ *
+ * Required fields are enforced by graphify/validate.py:
+ * `id`, `label`, `file_type`, `source_file`. The rest are populated by the
+ * extractors (`source_location`, optional `type`/`metadata`) and by the build
+ * writer (`community`, `community_name`, `norm_label`).
+ */
+export interface GraphifyNode {
+  /** Stable identifier: repo-relative path + symbol names (make_id slug). */
+  id: string;
+  /** Human-readable name. */
+  label: string;
+  /** Classification used as the primary node kind. */
+  file_type: GraphifyFileType;
+  /** Repo-relative path of the source file this node came from. */
+  source_file: string;
+  /** `L<line>` location, or `''` for sourceless stub nodes. */
+  source_location?: string | null;
+  /** Optional semantic kind (e.g. `module`, `namespace`). */
+  type?: GraphifyNodeType;
+  /** Node state / extra node definitions. */
+  state?: string;
+  /** Arbitrary per-extractor metadata (e.g. `{ kind: "csharp_namespace" }`). */
+  metadata?: Record<string, JsonValue>;
+  /** Leiden community id, stamped at build time. */
+  community?: number | null;
+  /** Human-readable community label, stamped at build time. */
+  community_name?: string;
+  /** Diacritic-stripped lowercased label, stamped at build time. */
+  norm_label?: string;
+  /** Extra fields tolerated for forward compatibility. */
+  [key: string]: unknown;
+}
+
+/**
+ * A graphify edge.
+ *
+ * Required fields: `source`, `target`, `relation`, `confidence`, `source_file`.
+ * `context` is populated for `references` edges (e.g. `type`, `return_type`,
+ * `field`, `generic_arg`).
+ */
+export interface GraphifyEdge {
+  /** Source node id. */
+  source: string;
+  /** Target node id. */
+  target: string;
+  /** Canonical relation verb. */
+  relation: GraphifyRelation;
+  /** Provenance: read directly from source vs. resolved by graphify. */
+  confidence: GraphifyConfidence;
+  /** Float 0.0-1.0; 1.0 for EXTRACTED, discrete rubric for INFERRED. */
+  confidence_score?: number;
+  /** Repo-relative path where the relationship was found. */
+  source_file: string;
+  /** `L<line>` location of the relationship. */
+  source_location?: string | null;
+  /** Edge weight. */
+  weight?: number;
+  /** Reference context for `references` edges. */
+  context?: string;
+  /** Arbitrary per-extractor metadata. */
+  metadata?: Record<string, JsonValue>;
+  /** Extra fields tolerated for forward compatibility. */
+  [key: string]: unknown;
+}
+
+/**
+ * A graphify hyperedge — a group relationship connecting 3+ nodes.
+ *
+ * Member list is canonical on `nodes` (aliases `members`/`node_ids` are folded
+ * by graphify/export.py build normalization).
+ */
+export interface GraphifyHyperedge {
+  /** Stable identifier. */
+  id: string;
+  /** Human-readable label. */
+  label?: string;
+  /** Member node ids (canonical key). */
+  nodes: string[];
+  /** Group relation verb (e.g. `participate_in`, `implement`, `form`). */
+  relation?: GraphifyRelation;
+  /** Provenance tag. */
+  confidence?: GraphifyConfidence;
+  /** Float 0.0-1.0. */
+  confidence_score?: number;
+  /** Repo-relative path where the relationship was found. */
+  source_file?: string;
+  /** Extra fields tolerated for forward compatibility. */
+  [key: string]: unknown;
+}
+
+/** Graph-level metadata stored on the graph (`graph` key). */
+export interface GraphifyGraphMetadata {
+  directed?: boolean;
+  multigraph?: boolean;
+  /** Edges may be serialized under `links` (NetworkX node-link) or `edges`. */
+  hyperedges?: GraphifyHyperedge[];
+  [key: string]: unknown;
+}
+
+/**
+ * The full graph.json document.
+ *
+ * graphify writes NetworkX node-link format: nodes under `nodes`, edges under
+ * `links`. Older/legacy payloads may use `edges` instead of `links`.
+ */
+export interface GraphifyGraph {
+  /** Graph nodes. */
+  nodes: GraphifyNode[];
+  /** Graph edges (NetworkX node-link key). */
+  links?: GraphifyEdge[];
+  /** Legacy alias for `links`. */
+  edges?: GraphifyEdge[];
+  /** Group relationships connecting 3+ nodes. */
+  hyperedges?: GraphifyHyperedge[];
+  /** Graph-level metadata (directed, multigraph, hyperedges). */
+  graph?: GraphifyGraphMetadata;
+  /** Top-level directed flag (NetworkX). */
+  directed?: boolean;
+  /** Top-level multigraph flag (NetworkX). */
+  multigraph?: boolean;
+  /** Git HEAD the graph was built against, when available. */
+  built_at_commit?: string;
+  [key: string]: unknown;
+}

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/hooks/usePathBasedEvents.ts

@@ -0,0 +1,192 @@
+/**
+ * Hook for processing path-based events and mapping them to animations
+ *
+ * Handles ComponentActivityEvent and ComponentActionEvent from
+ * PathBasedEventProcessor (Milestone 1 & 2)
+ */
+
+import { useEffect, useCallback } from 'react';
+import type {
+  ComponentActivityEvent,
+  ComponentActionEvent,
+  EdgeAnimationEvent,
+  PathBasedEvent,
+} from '@principal-ai/subsystems-core';
+import {
+  logLevelToNodeAnimation,
+  actionToNodeAnimation,
+  actionToEdgeAnimation,
+  type NodeAnimation,
+  type EdgeAnimation,
+} from '../utils/animationMapping';
+
+/**
+ * Animation update callbacks
+ */
+export interface AnimationCallbacks {
+  onNodeAnimation: (nodeId: string, animation: NodeAnimation & { timestamp: number }) => void;
+  onEdgeAnimation: (edgeId: string, animation: EdgeAnimation & { timestamp: number }) => void;
+}
+
+/**
+ * Hook options
+ */
+export interface UsePathBasedEventsOptions {
+  /** Path-based events to process */
+  events: PathBasedEvent[];
+
+  /** Callbacks for triggering animations */
+  callbacks: AnimationCallbacks;
+
+  /** Optional callback when event is processed */
+  onEventProcessed?: (event: PathBasedEvent) => void;
+
+  /** Minimum log level to trigger animations (default: 'info') */
+  minLogLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+
+/**
+ * Process path-based events and trigger appropriate animations
+ */
+export function usePathBasedEvents({
+  events,
+  callbacks,
+  onEventProcessed,
+  minLogLevel = 'info',
+}: UsePathBasedEventsOptions): void {
+  const { onNodeAnimation, onEdgeAnimation } = callbacks;
+
+  // Process component activity events (Milestone 1)
+  const processActivityEvent = useCallback(
+    (event: ComponentActivityEvent) => {
+      // Map log level to animation
+      const animation = logLevelToNodeAnimation(event.level);
+
+      // Trigger node animation
+      onNodeAnimation(event.componentId, {
+        ...animation,
+        timestamp: event.timestamp,
+      });
+
+      onEventProcessed?.(event);
+    },
+    [onNodeAnimation, onEventProcessed]
+  );
+
+  // Process component action events (Milestone 2)
+  const processActionEvent = useCallback(
+    (event: ComponentActionEvent) => {
+      // Map action/state to animation
+      const animation = actionToNodeAnimation(event.action, event.state);
+
+      // Trigger node animation
+      onNodeAnimation(event.componentId, {
+        ...animation,
+        timestamp: event.timestamp,
+      });
+
+      onEventProcessed?.(event);
+    },
+    [onNodeAnimation, onEventProcessed]
+  );
+
+  // Process edge animation events (Milestone 2)
+  const processEdgeAnimationEvent = useCallback(
+    (event: EdgeAnimationEvent) => {
+      const animation = actionToEdgeAnimation(event.triggeredBy?.action || 'unknown', {
+        type: event.animation,
+        duration: event.duration,
+        direction: event.direction,
+      });
+
+      onEdgeAnimation(event.edgeId, {
+        ...animation,
+        timestamp: event.timestamp,
+      });
+
+      onEventProcessed?.(event);
+    },
+    [onEdgeAnimation, onEventProcessed]
+  );
+
+  // Process events when they change
+  useEffect(() => {
+    if (events.length === 0) return;
+
+    // Process the latest event
+    const latestEvent = events[events.length - 1];
+
+    switch (latestEvent.type) {
+      case 'component-activity': {
+        // Milestone 1: Component activity from log
+        // Check if log level is high enough to trigger animation
+        const levels = ['debug', 'info', 'warn', 'error'];
+        if (levels.indexOf(latestEvent.level) >= levels.indexOf(minLogLevel)) {
+          processActivityEvent(latestEvent);
+        }
+        break;
+      }
+
+      case 'component-action':
+        // Milestone 2: Specific action from pattern match
+        processActionEvent(latestEvent);
+        break;
+
+      case 'edge-animation':
+        // Milestone 2: Edge activation from action trigger
+        processEdgeAnimationEvent(latestEvent);
+        break;
+    }
+  }, [events, processActivityEvent, processActionEvent, processEdgeAnimationEvent, minLogLevel]);
+}
+
+/**
+ * Process a batch of path-based events
+ * Useful for processing historical logs or bulk updates
+ */
+export function processBatchEvents(
+  events: PathBasedEvent[],
+  callbacks: AnimationCallbacks,
+  minLogLevel: 'debug' | 'info' | 'warn' | 'error' = 'info'
+): void {
+  const levels = ['debug', 'info', 'warn', 'error'];
+  const minLevelIndex = levels.indexOf(minLogLevel);
+
+  for (const event of events) {
+    switch (event.type) {
+      case 'component-activity':
+        if (levels.indexOf(event.level) >= minLevelIndex) {
+          const animation = logLevelToNodeAnimation(event.level);
+          callbacks.onNodeAnimation(event.componentId, {
+            ...animation,
+            timestamp: event.timestamp,
+          });
+        }
+        break;
+
+      case 'component-action':
+        {
+          const animation = actionToNodeAnimation(event.action, event.state);
+          callbacks.onNodeAnimation(event.componentId, {
+            ...animation,
+            timestamp: event.timestamp,
+          });
+        }
+        break;
+
+      case 'edge-animation':
+        {
+          const animation = actionToEdgeAnimation(event.triggeredBy?.action || 'unknown', {
+            type: event.animation,
+            duration: event.duration,
+            direction: event.direction,
+          });
+          callbacks.onEdgeAnimation(event.edgeId, {
+            ...animation,
+            timestamp: event.timestamp,
+          });
+        }
+        break;
+    }
+  }
+}