@principal-ai/subsystems-react 0.17.0

package/src/utils/graphConverter.ts

@@ -0,0 +1,148 @@
+import { MarkerType, type Node, type Edge } from '@xyflow/react';
+import type {
+  NodeState,
+  EdgeState,
+  GraphConfiguration,
+  Violation,
+} from '@principal-ai/subsystems-core';
+import type { CustomNodeData } from '../nodes/CustomNode';
+import type { CustomEdgeData } from '../edges/CustomEdge';
+
+/**
+ * Convert our NodeState to xyflow Node format
+ */
+export function convertToXYFlowNodes(
+  nodes: NodeState[],
+  configuration: GraphConfiguration,
+  violations: Violation[] = []
+): Node<CustomNodeData>[] {
+  return nodes.map((node) => {
+    let typeDefinition = configuration.nodeTypes[node.type];
+
+    // Warn if node type is not defined in configuration
+    if (!typeDefinition) {
+      console.warn(`Node type "${node.type}" not found in configuration for node "${node.id}"`);
+      // Provide minimal typeDefinition with global states fallback to prevent undefined errors
+      typeDefinition = {
+        description: '',
+        shape: 'rectangle',
+        dataSchema: {},
+        states: configuration.states,
+      };
+    } else if (!typeDefinition.states && configuration.states) {
+      // If typeDefinition exists but has no states, use global states as fallback
+      typeDefinition = {
+        ...typeDefinition,
+        states: configuration.states,
+      };
+    }
+
+    const hasViolations = violations.some((v) => v.context?.nodeId === node.id);
+
+    // Groups should render behind other nodes and edges
+    const isGroup = node.data?.canvasType === 'group';
+
+    return {
+      id: node.id,
+      type: 'custom',
+      position: node.position || { x: 0, y: 0 },
+      // Groups have lower zIndex to render behind other nodes
+      // Use 1 for groups, 100 for regular nodes (positive values to avoid event handling issues)
+      zIndex: isGroup ? 1 : 100,
+      // Apply persisted dimensions if available
+      ...(node.width !== undefined ? { width: node.width } : {}),
+      ...(node.height !== undefined ? { height: node.height } : {}),
+      data: {
+        name: node.name || node.id,
+        typeDefinition,
+        state: node.state,
+        hasViolations,
+        data: node.data,
+      },
+    };
+  });
+}
+
+/** Extended edge state with optional handle information for ReactFlow */
+export interface EdgeStateWithHandles extends EdgeState {
+  sourceHandle?: string;
+  targetHandle?: string;
+}
+
+/**
+ * Map canvas side to source handle ID
+ * Source handles use '-out' suffix
+ */
+function sideToSourceHandle(side?: string): string | undefined {
+  if (!side) return undefined;
+  return `${side}-out`;
+}
+
+/**
+ * Map canvas side to target handle ID
+ * Target handles use the side name directly
+ */
+function sideToTargetHandle(side?: string): string | undefined {
+  return side;
+}
+
+/**
+ * Convert our EdgeState to xyflow Edge format
+ */
+export function convertToXYFlowEdges(
+  edges: (EdgeState | EdgeStateWithHandles)[],
+  configuration: GraphConfiguration,
+  violations: Violation[] = []
+): Edge<CustomEdgeData>[] {
+  return edges.map((edge) => {
+    const typeDefinition = configuration.edgeTypes[edge.type];
+
+    // Warn if edge type is not defined in configuration
+    if (!typeDefinition) {
+      console.warn(`Edge type "${edge.type}" not found in configuration for edge "${edge.id}"`);
+    }
+
+    const hasViolations = violations.some((v) => v.context?.edgeId === edge.id);
+    const edgeWithHandles = edge as EdgeStateWithHandles;
+
+    // Get handle IDs from edge data (fromSide/toSide) or explicit handles
+    // If no side specified, default to right->left for left-to-right flow
+    const fromSide = edge.data?.fromSide as string | undefined;
+    const toSide = edge.data?.toSide as string | undefined;
+    const sourceHandle = edgeWithHandles.sourceHandle || sideToSourceHandle(fromSide || 'right');
+    const targetHandle = edgeWithHandles.targetHandle || sideToTargetHandle(toSide || 'left');
+
+    // Add arrow marker if edge type is directed
+    // Color priority: edge data color > type definition color > default
+    const edgeColor = edge.data?.color as string | undefined;
+    const markerEnd =
+      typeDefinition?.directed !== false
+        ? {
+            type: MarkerType.ArrowClosed,
+            color: edgeColor || typeDefinition?.color || '#888',
+            width: 20,
+            height: 20,
+          }
+        : undefined;
+
+    return {
+      id: edge.id,
+      source: edge.from,
+      target: edge.to,
+      sourceHandle,
+      targetHandle,
+      type: 'custom',
+      // Edges should render above groups (zIndex: 1) but below regular nodes (zIndex: 100)
+      zIndex: 50,
+      animated: typeDefinition?.style === 'animated',
+      markerEnd,
+      data: {
+        typeDefinition,
+        hasViolations,
+        data: edge.data,
+        edgeType: edge.type,
+      },
+    };
+  });
+}
+

package/src/utils/iconResolver.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import * as LucideIcons from 'lucide-react';
+
+/**
+ * Icon Resolver
+ *
+ * Resolves icon strings to React components. Supports:
+ * 1. Lucide icon names (e.g., "Database", "Settings", "Package")
+ * 2. Emoji/Unicode strings (e.g., "⚙️", "💾", "📦")
+ *
+ * This keeps configurations JSON-serializable while supporting icon libraries.
+ */
+
+export interface IconProps {
+  icon?: string;
+  size?: number;
+  className?: string;
+}
+
+/**
+ * Resolves an icon string to a React element
+ *
+ * @param icon - Icon name (Lucide) or emoji/text string
+ * @param size - Icon size in pixels (default: 20)
+ * @param className - Optional CSS class
+ * @returns React element or null
+ */
+export function resolveIcon(icon?: string, size: number = 20, className?: string): React.ReactNode {
+  if (!icon) return null;
+
+  // Try to resolve as Lucide icon first
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const LucideIcon = (LucideIcons as any)[icon];
+
+  // Check if it's a valid React component (function or object with $$typeof)
+  if (LucideIcon && (typeof LucideIcon === 'function' || typeof LucideIcon === 'object')) {
+    return <LucideIcon size={size} className={className} />;
+  }
+
+  // Fall back to rendering as text (emoji or unicode)
+  return (
+    <span className={className} style={{ fontSize: `${size}px` }}>
+      {icon}
+    </span>
+  );
+}
+
+/**
+ * Icon component that resolves icon strings
+ */
+export const Icon: React.FC<IconProps> = ({ icon, size = 20, className }) => {
+  return <>{resolveIcon(icon, size, className)}</>;
+};

package/src/utils/orientationUtils.ts

@@ -0,0 +1,73 @@
+import type { NodeState, EdgeState, CanvasSide } from '@principal-ai/subsystems-core';
+
+/**
+ * Swaps the orientation of a graph from horizontal to vertical or vice versa.
+ * This swaps x/y coordinates and adjusts edge connection sides accordingly.
+ */
+export function swapGraphOrientation(
+  nodes: NodeState[],
+  edges: EdgeState[]
+): { nodes: NodeState[]; edges: EdgeState[] } {
+  return {
+    nodes: swapNodePositions(nodes),
+    edges: swapEdgeSides(edges),
+  };
+}
+
+/**
+ * Swaps x and y positions for all nodes
+ */
+export function swapNodePositions(nodes: NodeState[]): NodeState[] {
+  return nodes.map(node => ({
+    ...node,
+    position: node.position ? {
+      x: node.position.y,
+      y: node.position.x,
+    } : undefined,
+  }));
+}
+
+/**
+ * Swaps edge connection sides to match the new orientation
+ * Both sides rotate clockwise: top → right → bottom → left → top
+ */
+export function swapEdgeSides(edges: EdgeState[]): EdgeState[] {
+  return edges.map(edge => {
+    const data = edge.data as Record<string, unknown> | undefined;
+    const fromSide = data?.fromSide as CanvasSide | undefined;
+    const toSide = data?.toSide as CanvasSide | undefined;
+
+    const rotatedFromSide = rotateClockwise(fromSide);
+    const rotatedToSide = rotateClockwise(toSide);
+
+    // Only include fromSide/toSide if they have defined values (not undefined)
+    const newData = { ...edge.data } as Record<string, unknown>;
+    if (rotatedFromSide !== undefined) {
+      newData.fromSide = rotatedFromSide;
+    }
+    if (rotatedToSide !== undefined) {
+      newData.toSide = rotatedToSide;
+    }
+
+    return {
+      ...edge,
+      data: newData as EdgeState['data'],
+    };
+  });
+}
+
+/**
+ * Rotates a side clockwise: top → right → bottom → left → top
+ */
+function rotateClockwise(side?: CanvasSide): CanvasSide | undefined {
+  if (!side) return undefined;
+
+  const clockwiseMap: Record<CanvasSide, CanvasSide> = {
+    top: 'right',
+    right: 'bottom',
+    bottom: 'left',
+    left: 'top',
+  };
+
+  return clockwiseMap[side];
+}