@invect/ui 0.0.1

package/src/utils/flowTransformations.ts

@@ -0,0 +1,137 @@
+import type { Node, Edge } from '@xyflow/react';
+import { InvectDefinition, FlowEdge, GraphNodeType, type MapperConfig } from '@invect/core/types';
+
+type NodeData = Record<string, unknown> & {
+  params?: Record<string, unknown>;
+  display_name?: string;
+  reference_id?: string;
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * Transform ReactFlow nodes and edges back to InvectDefinition format for saving
+ */
+export function transformToInvectDefinition(nodes: Node[], edges: Edge[]): InvectDefinition {
+  // Transform nodes: extract only the data needed for backend
+  const transformedNodes = nodes.map((node) => {
+    const data = (node.data || {}) as NodeData;
+    const params = data.params && typeof data.params === 'object' ? data.params : {};
+    const displayName =
+      typeof data.display_name === 'string' && data.display_name.trim().length > 0
+        ? data.display_name.trim()
+        : undefined;
+    const referenceId =
+      typeof data.reference_id === 'string' && data.reference_id.trim().length > 0
+        ? data.reference_id.trim()
+        : undefined;
+
+    const nodeType =
+      (node.type as GraphNodeType) || (data.type as GraphNodeType) || GraphNodeType.TEMPLATE_STRING;
+
+    const baseNode = {
+      id: node.id,
+      type: nodeType,
+      position: node.position ?? { x: 0, y: 0 },
+      params,
+    } as InvectDefinition['nodes'][number];
+
+    if (displayName) {
+      baseNode.label = displayName;
+    }
+
+    // Store reference_id for input mapping
+    if (referenceId) {
+      (baseNode as Record<string, unknown>).referenceId = referenceId;
+    }
+
+    // Preserve mapper configuration at node level
+    const mapperConfig = data.mapper as MapperConfig | undefined;
+    if (mapperConfig && mapperConfig.enabled) {
+      (baseNode as Record<string, unknown>).mapper = mapperConfig;
+    }
+
+    return baseNode;
+  });
+
+  // Transform edges: extract only core edge properties, handling null values
+  const transformedEdges: FlowEdge[] = edges.map((edge) => ({
+    id: edge.id,
+    source: edge.source,
+    target: edge.target,
+    sourceHandle: edge.sourceHandle || undefined,
+    targetHandle: edge.targetHandle || undefined,
+  }));
+
+  return {
+    nodes: transformedNodes,
+    edges: transformedEdges,
+  };
+}
+
+/**
+ * Compute a serialized snapshot of the flow definition for dirty-checking.
+ * Uses `transformToInvectDefinition` to strip ReactFlow-internal state
+ * (selected, measured, executionStatus, etc.), then JSON.stringify for
+ * cheap string equality comparison.
+ *
+ * This is only called inside Zustand store actions (on structural mutations
+ * and saves), NOT inside selectors — so it doesn't run on every render.
+ */
+export function computeSnapshot(nodes: Node[], edges: Edge[]): string {
+  const definition = transformToInvectDefinition(nodes, edges);
+  return JSON.stringify(definition);
+}
+
+/**
+ * Validate that a InvectDefinition has required fields
+ */
+function _validateInvectDefinition(definition: InvectDefinition): {
+  isValid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  if (!definition.nodes || definition.nodes.length === 0) {
+    errors.push('Flow must contain at least one node');
+  }
+
+  if (!definition.edges) {
+    errors.push('Flow must have an edges array (can be empty)');
+  }
+
+  // Validate each node has required fields
+  definition.nodes?.forEach((node, index) => {
+    if (!node.id) {
+      errors.push(`Node at index ${index} is missing an id`);
+    }
+    if (!node.type) {
+      errors.push(`Node at index ${index} is missing a type`);
+    }
+    if (!node.params) {
+      errors.push(`Node ${node.id} is missing params`);
+    }
+  });
+
+  // Validate edges reference existing nodes
+  const nodeIds = new Set(definition.nodes?.map((n) => n.id) || []);
+  definition.edges?.forEach((edge, index) => {
+    if (!edge.id) {
+      errors.push(`Edge at index ${index} is missing an id`);
+    }
+    if (!edge.source) {
+      errors.push(`Edge at index ${index} is missing a source`);
+    } else if (!nodeIds.has(edge.source)) {
+      errors.push(`Edge ${edge.id} references non-existent source node: ${edge.source}`);
+    }
+    if (!edge.target) {
+      errors.push(`Edge at index ${index} is missing a target`);
+    } else if (!nodeIds.has(edge.target)) {
+      errors.push(`Edge ${edge.id} references non-existent target node: ${edge.target}`);
+    }
+  });
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+}

package/src/utils/layoutUtils.ts

@@ -0,0 +1,127 @@
+// Layout utilities for automatically positioning nodes to avoid overlaps
+import type { Node, Edge } from '@xyflow/react';
+import {
+  applyDagreLayout as applyDagreLayoutFromPackage,
+  applyElkLayout as applyElkLayoutFromPackage,
+  type ElkLayoutNode,
+} from '@invect/layouts';
+
+export interface Position {
+  x: number;
+  y: number;
+}
+
+// Layout algorithm options
+export type LayoutAlgorithm = 'dagre' | 'elkjs';
+
+export interface LayoutOptions {
+  algorithm: LayoutAlgorithm;
+  direction?: 'TB' | 'BT' | 'LR' | 'RL'; // Top-Bottom, Bottom-Top, Left-Right, Right-Left
+  nodeSpacing?: number;
+  rankSpacing?: number;
+  /** Maximum width before wrapping to a new row (only applies to LR/RL layouts, 0 = no wrapping) */
+  maxWidth?: number;
+  /** Vertical spacing between wrapped rows */
+  rowSpacing?: number;
+}
+
+// Define default layout options if not already defined elsewhere
+// These values are examples; adjust them as needed.
+const defaultLayoutOptions = {
+  nodeWidth: 200,
+  nodeHeight: 60,
+  nodeSpacing: 70, // Default for dagre nodesep - increased for more vertical spacing
+  rankSpacing: 100, // Default for dagre ranksep
+  maxWidth: 2000, // Wrap to new row if layout exceeds this width
+  rowSpacing: 150, // Vertical spacing between wrapped rows
+};
+
+/**
+ * Derive explicit source handle ordering from node params.
+ * This ensures ELK gets deterministic port positions matching the rendered
+ * handle order, regardless of edge iteration order.
+ */
+function deriveSourceHandles(
+  node: Node,
+): Array<{ id: string; type: 'source'; position: 'right' }> | undefined {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const data = node.data as Record<string, any> | undefined;
+  const nodeType = data?.type ?? node.type;
+
+  if (nodeType === 'core.switch' && Array.isArray(data?.params?.cases)) {
+    const cases = data.params.cases as Array<{ slug: string }>;
+    return [
+      ...cases.map((c) => ({ id: c.slug, type: 'source' as const, position: 'right' as const })),
+      { id: 'default', type: 'source' as const, position: 'right' as const },
+    ];
+  }
+
+  if (nodeType === 'core.if_else') {
+    return [
+      { id: 'true_output', type: 'source' as const, position: 'right' as const },
+      { id: 'false_output', type: 'source' as const, position: 'right' as const },
+    ];
+  }
+
+  return undefined;
+}
+
+/**
+ * Main layout function that applies the selected algorithm
+ */
+export const applyLayout = async (
+  nodes: Node[],
+  edges: Edge[],
+  algorithm: LayoutAlgorithm,
+  direction: 'TB' | 'BT' | 'LR' | 'RL' = 'LR',
+  options?: LayoutOptions,
+): Promise<{ nodes: Node[]; edges: Edge[] }> => {
+  console.log(`Applying layout: ${algorithm}, Direction: ${direction}`);
+
+  switch (algorithm) {
+    case 'dagre': {
+      // Use shared layout utility from @invect/layouts
+      const layoutedNodes = applyDagreLayoutFromPackage(nodes, edges, {
+        direction,
+        nodeSpacing: options?.nodeSpacing ?? defaultLayoutOptions.nodeSpacing,
+        rankSpacing: options?.rankSpacing ?? defaultLayoutOptions.rankSpacing,
+        nodeWidth: defaultLayoutOptions.nodeWidth,
+        nodeHeight: defaultLayoutOptions.nodeHeight,
+        maxWidth: options?.maxWidth ?? defaultLayoutOptions.maxWidth,
+        rowSpacing: options?.rowSpacing ?? defaultLayoutOptions.rowSpacing,
+      });
+      return { nodes: layoutedNodes as Node[], edges };
+    }
+    case 'elkjs': {
+      // Enrich branching nodes with explicit source handle ordering so ELK
+      // places ports in the correct top-to-bottom order (matching the rendered handles).
+      const enrichedNodes = nodes.map((node) => {
+        const sourceHandles = deriveSourceHandles(node);
+        if (sourceHandles) {
+          return { ...node, sourceHandles } as ElkLayoutNode;
+        }
+        return node;
+      }) as ElkLayoutNode[];
+
+      // Use ElkJS layout with port/handle support for better edge routing
+      // Let the @invect/layouts package defaults handle spacing and wrapping
+      const elkDirection =
+        direction === 'LR'
+          ? 'RIGHT'
+          : direction === 'RL'
+            ? 'LEFT'
+            : direction === 'TB'
+              ? 'DOWN'
+              : 'UP';
+      const layoutedNodes = await applyElkLayoutFromPackage(enrichedNodes, edges, {
+        direction: elkDirection,
+        // Only pass nodeWidth/nodeHeight, let package defaults handle everything else
+        nodeWidth: defaultLayoutOptions.nodeWidth,
+        nodeHeight: defaultLayoutOptions.nodeHeight,
+      });
+      return { nodes: layoutedNodes as Node[], edges };
+    }
+    default:
+      return { nodes, edges }; // No layout applied
+  }
+};

package/src/utils/nodeReferenceUtils.ts

@@ -0,0 +1,135 @@
+/**
+ * Utilities for generating and managing node reference IDs
+ */
+
+const MAX_REFERENCE_ID_LENGTH = 22;
+
+/**
+ * Convert a display name to a snake_case reference ID
+ * Only allows alphanumeric characters and underscores
+ * Truncates to MAX_REFERENCE_ID_LENGTH chars
+ */
+export function toReferenceId(displayName: string): string {
+  const baseId = displayName
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, '') // Remove non-alphanumeric chars except spaces
+    .trim()
+    .replace(/\s+/g, '_'); // Replace spaces with underscores
+
+  return truncateReferenceId(baseId);
+}
+
+/**
+ * Truncate a reference ID to max length while preserving any numeric suffix
+ * e.g., "some_really_long_node_name_2" → "some_really_long_no_2"
+ */
+function truncateReferenceId(refId: string, suffix?: string): string {
+  const maxLen = MAX_REFERENCE_ID_LENGTH;
+
+  // If already within limit, return as-is
+  if (refId.length <= maxLen) {
+    return refId;
+  }
+
+  // If there's a suffix (like "_2"), ensure it fits
+  if (suffix) {
+    const suffixWithUnderscore = `_${suffix}`;
+    const availableForBase = maxLen - suffixWithUnderscore.length;
+    if (availableForBase <= 0) {
+      // Suffix itself is too long, just truncate the whole thing
+      return refId.substring(0, maxLen);
+    }
+    return refId.substring(0, availableForBase) + suffixWithUnderscore;
+  }
+
+  // No suffix, just truncate
+  return refId.substring(0, maxLen);
+}
+
+/**
+ * Generate a unique display name for a new node, avoiding conflicts
+ * Returns names like "AI Model", "AI Model 2", "AI Model 3", etc.
+ */
+export function generateUniqueDisplayName(
+  baseDisplayName: string,
+  existingNodes: { data?: { display_name?: string } }[],
+): string {
+  const existingNames = new Set(
+    existingNodes
+      .map((node) => node.data?.display_name)
+      .filter((name): name is string => typeof name === 'string'),
+  );
+
+  // If base name doesn't exist, use it
+  if (!existingNames.has(baseDisplayName)) {
+    return baseDisplayName;
+  }
+
+  // Try incrementing numbers until we find a unique name
+  let counter = 2;
+  while (true) {
+    const candidateName = `${baseDisplayName} ${counter}`;
+    if (!existingNames.has(candidateName)) {
+      return candidateName;
+    }
+    counter++;
+    // Safety limit to prevent infinite loops
+    if (counter > 1000) {
+      return `${baseDisplayName} ${Date.now()}`;
+    }
+  }
+}
+
+/**
+ * Generate a unique reference ID for a new node, avoiding conflicts
+ * Truncates to MAX_REFERENCE_ID_LENGTH while preserving the increment suffix
+ */
+export function generateUniqueReferenceId(
+  displayName: string,
+  existingNodes: { data?: { reference_id?: string } }[],
+): string {
+  const baseReferenceId = toReferenceId(displayName);
+
+  const existingReferenceIds = new Set(
+    existingNodes
+      .map((node) => node.data?.reference_id)
+      .filter((id): id is string => typeof id === 'string'),
+  );
+
+  // If base reference ID doesn't exist, use it (already truncated by toReferenceId)
+  if (!existingReferenceIds.has(baseReferenceId)) {
+    return baseReferenceId;
+  }
+
+  // Try incrementing numbers until we find a unique reference ID
+  let counter = 2;
+  while (true) {
+    // Truncate base to fit the counter suffix within max length
+    const suffix = String(counter);
+    const candidateId = truncateReferenceId(baseReferenceId, suffix);
+
+    if (!existingReferenceIds.has(candidateId)) {
+      return candidateId;
+    }
+    counter++;
+    // Safety limit to prevent infinite loops
+    if (counter > 1000) {
+      const timestampSuffix = String(Date.now()).slice(-6);
+      return truncateReferenceId(baseReferenceId, timestampSuffix);
+    }
+  }
+}
+
+/**
+ * Update reference ID when display name changes
+ * Ensures uniqueness among existing nodes
+ */
+export function updateReferenceIdForDisplayName(
+  newDisplayName: string,
+  currentNodeId: string,
+  existingNodes: { id: string; data?: { reference_id?: string } }[],
+): string {
+  // Filter out the current node when checking for conflicts
+  const otherNodes = existingNodes.filter((node) => node.id !== currentNodeId);
+  return generateUniqueReferenceId(newDisplayName, otherNodes);
+}

package/src/vendor.d.ts

@@ -0,0 +1,7 @@
+import 'react';
+
+declare module 'react' {
+  interface CSSProperties {
+    WebkitTextSecurity?: 'none' | 'circle' | 'disc' | 'square';
+  }
+}