@principal-ai/principal-view-react 0.16.21 → 0.16.23

package/src/subsystem/nodes.tsx

@@ -0,0 +1,353 @@
+/**
+ * Subsystem component/group node + edge renderers.
+ *
+ * Lightweight, purpose-built for the subsystem component graph: a component
+ * renders its name (kind-tagged, colored by package) plus its symbol/purpose
+ * and a click-to-open file chip. Groups render as package containers. Clicking
+ * a component calls `onSelect` (to open the entry point / file).
+ */
+
+import { useState } from 'react';
+import {
+  Handle,
+  Position,
+  type NodeProps,
+  type EdgeProps,
+} from '@xyflow/react';
+import { useTheme } from '@principal-ade/industry-theme';
+import {
+  KIND_COLOR,
+  MECHANISM_COLOR,
+  deriveNameFromSymbol,
+  type SubsystemGraphNode,
+  type SubsystemGraphEdge,
+} from './model';
+
+export const KIND_LABEL: Record<string, string> = {
+  class: 'class',
+  module: 'module',
+  script: 'script',
+  registry: 'registry',
+  service: 'service',
+  consumer: 'consumer',
+  function: 'function',
+  method: 'method',
+  type: 'type',
+  package: 'package',
+};
+
+/** Owning class of a method, derived from its `Symbol.Class.method` symbol. */
+function ownerClass(symbol?: string): string | undefined {
+  if (!symbol) return undefined;
+  const idx = symbol.lastIndexOf('.');
+  return idx > 0 ? symbol.slice(0, idx) : undefined;
+}
+
+/** Namespace/owner extracted from a PURL or npm scope. */
+function purlNamespace(purl?: string): string | undefined {
+  if (!purl) return undefined;
+  // pkg:github/owner/repo → owner
+  const hosted = purl.match(/^pkg:(github|gitlab|bitbucket)\/([^/]+)\//);
+  if (hosted) return hosted[2];
+  // pkg:npm/@scope/name → @scope
+  const scoped = purl.match(/^pkg:npm\/(@[^/]+)\//);
+  if (scoped) return scoped[1];
+  // pkg:generic/local/... → local
+  if (purl.startsWith('pkg:generic/local/')) return 'local';
+  // @scope/name → @scope (legacy npm)
+  if (purl.startsWith('@')) {
+    const idx = purl.indexOf('/');
+    return idx > 0 ? purl.slice(0, idx) : undefined;
+  }
+  return undefined;
+}
+
+/** Short label for the hosting platform of a PURL. */
+function purlRegistry(purl?: string): string {
+  if (!purl) return '';
+  if (purl.startsWith('pkg:github/')) return ' · github';
+  if (purl.startsWith('pkg:gitlab/')) return ' · gitlab';
+  if (purl.startsWith('pkg:bitbucket/')) return ' · bitbucket';
+  if (purl.startsWith('pkg:generic/local/')) return ' · local';
+  if (purl.startsWith('pkg:npm/')) return ' · npm';
+  if (purl.startsWith('@')) return ' · npm';
+  return '';
+}
+
+/** Insert zero-width spaces at identifier word boundaries so long names wrap
+ *  on naming conventions (snake_case `foo_`|`bar`, camelCase `foo`|`Bar`,
+ *  PascalCase `Foo`|`Bar`, acronym `ABC`|`Def`) instead of mid-character. */
+function breakWords(s: string): string {
+  const zwsp = '\u200b';
+  return s
+    // camelCase: lower/digit → Upper  (and the boundary before it holds)
+    .replace(/([a-z0-9])([A-Z])/g, `$1${zwsp}$2`)
+    // acronym → word: `ABC`|`Def` (two Uppercase then a lowercase)
+    .replace(/([A-Z])([A-Z][a-z])/g, `$1${zwsp}$2`)
+    // separators: break after `_`, `-`, `.`
+    .replace(/([_\-.])([^_\-.\u200b])/g, `$1${zwsp}$2`);
+}
+
+export interface SubsystemGraphCallbacks {
+  /** Click a component — open its file/entry point. */
+  onSelect?: (componentId: string) => void;
+  /** Click an edge (or its label) — select the relationship. */
+  onEdgeSelect?: (edgeId: string) => void;
+  /** Upper bound for node width; nodes grow with content up to this, then wrap. */
+  maxNodeWidth?: number;
+}
+
+/** Root callbacks carried through node data (injected by the graph component). */
+export const SUBSYSTEM_CALLBACKS: SubsystemGraphCallbacks = {};
+
+export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
+  const { theme } = useTheme();
+  const { data, selected, width: nodeWidth, height: nodeHeight } = props;
+  const c = data.component;
+  const color = KIND_COLOR[c.kind] ?? '#888';
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const [hover, setHover] = useState(false);
+  const isPackage = c.kind === 'package';
+  const configuredMax = SUBSYSTEM_CALLBACKS.maxNodeWidth;
+  const maxWidth = isPackage ? (configuredMax ?? 320) : (configuredMax ?? 300);
+  // `symbol` is the source of truth; `name` is derived from it consistently.
+  const displayName = deriveNameFromSymbol(c.symbol, c.kind, c.name, c.file);
+
+  return (
+    <div
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      onClick={(e) => {
+        e.stopPropagation();
+        SUBSYSTEM_CALLBACKS.onSelect?.(c.id);
+      }}
+      style={{
+        position: 'relative',
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'center',
+        alignItems: 'center',
+        boxSizing: 'border-box',
+        width: nodeWidth,
+        height: nodeHeight,
+        minWidth: isPackage ? 200 : 150,
+        maxWidth,
+        padding: isPackage ? '10px 12px' : '6px 10px',
+        borderRadius: isPackage ? 10 : 8,
+        background: theme.colors.backgroundSecondary ?? theme.colors.background,
+        border: `2px ${isPackage ? 'dashed' : 'solid'} ${selected ? theme.colors.primary : color}`,
+        boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+        cursor: 'pointer',
+        fontFamily: theme.fonts.body,
+      }}
+    >
+      {/* Kind + package tooltip, shown at the top on hover */}
+      {hover && (
+        <div
+          style={{
+            position: 'absolute',
+            top: -26,
+            left: 0,
+            zIndex: 1000,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 6,
+            whiteSpace: 'nowrap',
+            fontSize: theme.fontSizes[0] * 0.8,
+            fontFamily: theme.fonts.monospace,
+            textTransform: 'uppercase',
+            letterSpacing: 0.5,
+            color,
+            background: theme.colors.background,
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 4,
+            padding: '1px 6px',
+          }}
+        >
+          {KIND_LABEL[c.kind] ?? c.kind}
+          {/* For package nodes, show the registry instead of the (already shown)
+              package name; for other kinds, show the owning package. */}
+          {c.kind === 'package' ? purlRegistry(c.purl) : c.purl ? ` · ${c.purl}` : ''}
+          {c.capture && c.capture !== 'edited' ? ` · ${c.capture}` : ''}
+        </div>
+      )}
+
+      {/* Purpose tooltip, shown below the node on hover */}
+      {hover && c.purpose && (
+        <div
+          style={{
+            position: 'absolute',
+            top: '100%',
+            left: 0,
+            marginTop: 4,
+            zIndex: 1000,
+            maxWidth: 260,
+            fontSize: theme.fontSizes[0] * 0.85,
+            fontFamily: theme.fonts.body,
+            color: theme.colors.text,
+            background: theme.colors.background,
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 4,
+            padding: '4px 8px',
+            boxShadow: '0 2px 8px rgba(0,0,0,0.3)',
+            lineHeight: 1.4,
+          }}
+        >
+          {c.purpose}
+        </div>
+      )}
+
+      {/* Method nodes show their owning class above the method name. */}
+      {c.kind === 'method' && ownerClass(c.symbol) && (
+        <div
+          style={{
+            fontSize: theme.fontSizes[0] * 0.78,
+            fontFamily: theme.fonts.monospace,
+            color: muted,
+            textAlign: 'center',
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            maxWidth: '100%',
+            marginBottom: 1,
+          }}
+          title={ownerClass(c.symbol)}
+        >
+          {ownerClass(c.symbol)}
+        </div>
+      )}
+
+      {/* Package nodes show their namespace (@scope) above the package name. */}
+      {c.kind === 'package' && purlNamespace(c.purl) && (
+        <div
+          style={{
+            fontSize: theme.fontSizes[0] * 0.78,
+            fontFamily: theme.fonts.monospace,
+            color: muted,
+            textAlign: 'center',
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            maxWidth: '100%',
+            marginBottom: 1,
+          }}
+          title={c.purl}
+        >
+          {purlNamespace(c.purl)}
+        </div>
+      )}
+
+      <div
+        style={{
+          fontSize: theme.fontSizes[2],
+          fontWeight: 600,
+          color: theme.colors.text,
+          lineHeight: 1.2,
+          textAlign: 'center',
+          // Let long names wrap within the node's capped width (instead of
+          // truncating), but cap each line so the node doesn't grow unbounded.
+          whiteSpace: 'normal',
+          overflowWrap: 'anywhere',
+          maxWidth: '100%',
+          // Types get a serif name to distinguish them from runtime units.
+          fontFamily:
+            c.kind === 'type' ? 'Georgia, "Times New Roman", serif' : theme.fonts.body,
+        }}
+      >
+        {c.kind === 'method' ? `.${breakWords(displayName)}` : breakWords(displayName)}
+      </div>
+
+      {c.symbol && c.kind !== 'method' && c.kind !== 'package' && c.symbol !== displayName && (
+        <div
+          style={{
+            fontSize: theme.fontSizes[0] * 0.82,
+            fontFamily: theme.fonts.monospace,
+            color: color,
+            marginTop: 1,
+            textAlign: 'center',
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            maxWidth: '100%',
+          }}
+          title={c.symbol}
+        >
+          {c.symbol}
+        </div>
+      )}
+
+      {c.file && c.kind !== 'package' && (
+        <div
+          onClick={(e) => {
+            e.stopPropagation();
+            SUBSYSTEM_CALLBACKS.onSelect?.(c.id);
+          }}
+          style={{
+            alignSelf: 'center',
+            marginTop: 3,
+            fontSize: theme.fontSizes[0] * 0.78,
+            fontFamily: theme.fonts.monospace,
+            color: theme.colors.primary,
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 4,
+            padding: '1px 5px',
+            cursor: 'pointer',
+            maxWidth: '100%',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {c.file.split('/').pop()}
+        </div>
+      )}
+
+      <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
+      <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
+    </div>
+  );
+}
+
+/** Subsystem edge — SVG path only. The mechanism label is rendered as an
+ *  absolutely-positioned HTML overlay OUTSIDE the ReactFlow tree (by the
+ *  parent Inner component) so it sits above the pane and receives pointer
+ *  events. */
+export function SubsystemEdge({
+  data,
+  markerEnd,
+}: EdgeProps<SubsystemGraphEdge>) {
+  const path = data?.elkPath ?? '';
+  const mechanism = data?.mechanism ?? 'imports';
+  const color = MECHANISM_COLOR[mechanism] ?? '#888';
+  const isDashed = mechanism === 'registers-into';
+  const dimmed = data?.dimmed === true;
+  const opacity = dimmed ? 0.15 : 1;
+
+  return (
+    <>
+      {/* Invisible wide interaction path — React Flow's pane uses this for
+          hit-testing onEdgeClick. Must be pointer-events:stroke so the pane
+          delegates the click to onEdgeClick. */}
+      <path
+        d={path}
+        fill="none"
+        stroke="transparent"
+        strokeWidth={20}
+        className="react-flow__edge-interaction"
+      />
+      {/* Visible edge line — pointer-events:none so it never intercepts the
+          HTML label overlay rendered by the parent component. */}
+      <path
+        d={path}
+        fill="none"
+        stroke={color}
+        strokeWidth={1.5}
+        strokeDasharray={isDashed ? '6 4' : undefined}
+        opacity={opacity}
+        markerEnd={markerEnd}
+        style={{ pointerEvents: 'none' }}
+      />
+    </>
+  );
+}
+

package/src/utils/elkLayout.ts

@@ -47,6 +47,25 @@ export interface ElkLayoutOptions {
    */
   edgeNodeSpacing?: number;
 
+  /**
+   * Minimum horizontal distance between layers (node-to-node across layers).
+   * Controls the gap that prevents nodes in adjacent layers from overlapping.
+   * @default 0
+   */
+  interLayerSpacing?: number;
+
+  /**
+   * Reserve space along edges for inline labels so they don't overlap nodes
+   * or other edges. When enabled ELK places labels inline on the edge with the
+   * given margin model.
+   */
+  edgeLabels?: {
+    /** Whether to reserve label space in the layout. @default true */
+    enabled?: boolean;
+    /** Placement of inline labels. @default 'CENTER' */
+    placement?: 'CENTER' | 'TAIL' | 'HEAD';
+  };
+
   /**
    * Layout direction
    * @default 'RIGHT'
@@ -62,6 +81,8 @@ export interface ElkLayoutResult {
   edgePaths: Map<string, string>;
   /** Edge label positions, keyed by edge ID */
   edgeLabelPositions: Map<string, { x: number; y: number }>;
+  /** Raw ELK path points per edge (for debugging). */
+  edgePathPoints: Map<string, Point[]>;
 }
 
 /** Point in 2D space */
@@ -216,6 +237,8 @@ function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
     nodeSpacing = 50,
     edgeSpacing = 8,
     edgeNodeSpacing = 10,
+    interLayerSpacing = 0,
+    edgeLabels,
     direction = 'RIGHT',
   } = options;
 
@@ -228,6 +251,7 @@ function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
     'elk.spacing.edgeNode': String(edgeNodeSpacing),
     'elk.layered.spacing.edgeEdgeBetweenLayers': String(edgeSpacing),
     'elk.layered.spacing.edgeNodeBetweenLayers': String(edgeNodeSpacing),
+    'elk.layered.spacing.nodeNodeBetweenLayers': String(interLayerSpacing),
     // Port constraints - edges connect at specific sides
     'elk.portConstraints': 'FIXED_SIDE',
     // Improve orthogonal routing quality
@@ -239,6 +263,14 @@ function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
     'elk.layered.thoroughness': '50',
   };
 
+  // Reserve space for inline edge labels so they don't overlap nodes/edges.
+  if (edgeLabels?.enabled !== false) {
+    const placement = edgeLabels?.placement ?? 'CENTER';
+    baseOptions['elk.edgeLabels.inline'] = 'true';
+    baseOptions['elk.edgeLabels.inlinePlacement'] = placement;
+    baseOptions['elk.layered.edgeLabels.centerLabelPlacementStrategy'] = 'CENTER_LAYER';
+  }
+
   // Set edge routing style
   switch (routingStyle) {
     case 'orthogonal':
@@ -269,6 +301,8 @@ export async function computeElkLayout(
   options: ElkLayoutOptions = {}
 ): Promise<ElkLayoutResult> {
   const { preserveNodePositions = true } = options;
+  const edgeLabels = options.edgeLabels;
+  const direction = options.direction ?? 'RIGHT';
 
   // Build a map of original node positions BEFORE passing to ELK
   // (ELK mutates the input nodes in place, so we must save positions first)
@@ -282,6 +316,13 @@ export async function computeElkLayout(
     const width = node.measured?.width ?? node.width ?? 200;
     const height = node.measured?.height ?? node.height ?? 100;
 
+    // Optional explicit layout layer, read from node data (e.g. our subsystem
+    // components carry `data.component.layer`). Forces ELK to place the node in
+    // that layer so the graph reads as a pipeline rather than a guess.
+    let layer: number | undefined;
+    const nd = node.data as { component?: { layer?: number }; layer?: number } | undefined;
+    layer = nd?.layer ?? nd?.component?.layer;
+
     return {
       id: node.id,
       width,
@@ -297,6 +338,7 @@ export async function computeElkLayout(
       ],
       properties: {
         'portConstraints': 'FIXED_SIDE',
+        ...(layer !== undefined ? { 'layering.layer': String(layer) } : {}),
       },
     };
   });
@@ -332,7 +374,18 @@ export async function computeElkLayout(
       };
     }
 
-    // Fallback to position-based calculation
+    // When ELK repositions nodes (preserveNodePositions=false), the initial
+    // grid positions are unreliable — use the layout direction instead.
+    if (!preserveNodePositions) {
+      switch (direction) {
+        case 'RIGHT': return { sourcePort: `${sourceId}_right`, targetPort: `${targetId}_left` };
+        case 'LEFT':  return { sourcePort: `${sourceId}_left`,  targetPort: `${targetId}_right` };
+        case 'DOWN':  return { sourcePort: `${sourceId}_bottom`, targetPort: `${targetId}_top` };
+        case 'UP':    return { sourcePort: `${sourceId}_top`,    targetPort: `${targetId}_bottom` };
+      }
+    }
+
+    // Fallback to position-based calculation (for preserveNodePositions=true)
     const sourcePos = originalPositions.get(sourceId);
     const targetPos = originalPositions.get(targetId);
 
@@ -378,11 +431,20 @@ export async function computeElkLayout(
     const isHorizontalFirst = sourcePort.endsWith('_right') || sourcePort.endsWith('_left');
     edgeRoutingDirection.set(edge.id, isHorizontalFirst);
 
-    return {
+    const elkEdge: ElkExtendedEdge = {
       id: edge.id,
       sources: [sourcePort],
       targets: [targetPort],
     };
+    // Estimated label size so ELK reserves room to render the inline label
+    // without it overlapping nodes or sibling edges.
+    if (edgeLabels?.enabled !== false && typeof edge.label === 'string') {
+      const text = edge.label;
+      const labelWidth = Math.max(20, text.length * 7); // ~7px per mono char
+      const labelHeight = 14;
+      elkEdge.labels = [{ text, width: labelWidth, height: labelHeight }];
+    }
+    return elkEdge;
   });
 
   // Create ELK graph
@@ -407,6 +469,7 @@ export async function computeElkLayout(
   // Extract results
   const edgePaths = new Map<string, string>();
   const edgeLabelPositions = new Map<string, { x: number; y: number }>();
+  const edgePathPoints = new Map<string, Point[]>();
 
   // Process edges
   if (layoutedGraph.edges) {
@@ -462,9 +525,37 @@ export async function computeElkLayout(
           }
         }
 
-        // For orthogonal routing, rebuild the path with proper right-angle bends
-        // The transformation can distort ELK's bend points, so we compute fresh bends
-        if (options.routingStyle === 'orthogonal') {
+        // Use ELK's native label position (it accounts for node avoidance)
+        // and apply the same coordinate offset.
+        if (edge.labels && edge.labels.length > 0) {
+          const elkLabel = edge.labels[0];
+          // Raw ELK label position — no conversion.
+          let lx = elkLabel.x ?? 0;
+          let ly = elkLabel.y ?? 0;
+          if (preserveNodePositions && sourceOriginal && sourceElk && targetOriginal && targetElk) {
+            const sourceOffset = {
+              x: sourceOriginal.x - sourceElk.x,
+              y: sourceOriginal.y - sourceElk.y,
+            };
+            const targetOffset = {
+              x: targetOriginal.x - targetElk.x,
+              y: targetOriginal.y - targetElk.y,
+            };
+            // Interpolate offset based on label position along the edge
+            const startX = allPoints[0].x;
+            const endX = allPoints[allPoints.length - 1].x;
+            const rangeX = Math.abs(endX - startX) || 1;
+            const t = Math.min(1, Math.max(0, Math.abs(lx - startX) / rangeX));
+            lx += sourceOffset.x + (targetOffset.x - sourceOffset.x) * t;
+            ly += sourceOffset.y + (targetOffset.y - sourceOffset.y) * t;
+          }
+          edgeLabelPositions.set(edge.id, { x: lx, y: ly });
+        }
+
+        // For orthogonal routing with preserved positions, the offset can distort
+        // ELK's bend points, so we rebuild the path. Otherwise, use ELK's bends
+        // as-is since they already account for label placement and node avoidance.
+        if (options.routingStyle === 'orthogonal' && preserveNodePositions) {
           const start = allPoints[0];
           const end = allPoints[allPoints.length - 1];
           const dx = Math.abs(end.x - start.x);
@@ -502,10 +593,7 @@ export async function computeElkLayout(
             : pointsToPath(allPoints);
 
         edgePaths.set(edge.id, path);
-
-        // Calculate label position
-        const labelPos = calculatePathMidpoint(allPoints);
-        edgeLabelPositions.set(edge.id, labelPos);
+        edgePathPoints.set(edge.id, [...allPoints]);
       }
     }
   }
@@ -528,6 +616,7 @@ export async function computeElkLayout(
     nodes: resultNodes,
     edgePaths,
     edgeLabelPositions,
+    edgePathPoints,
   };
 }