@principal-ai/subsystems-react 0.17.0

package/src/components/MultiCanvasRenderer.tsx

@@ -0,0 +1,295 @@
+import { useMemo, useCallback, useRef, forwardRef } from 'react';
+import type { ExtendedCanvas, ExtendedCanvasNode, ExtendedCanvasEdge } from '@principal-ai/subsystems-core';
+import { GraphRenderer } from './GraphRenderer';
+import type { GraphRendererProps, GraphRendererHandle } from './GraphRenderer';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * A canvas placement with its position in the combined coordinate space
+ */
+export interface CanvasPlacement {
+  /** Unique identifier for this canvas */
+  canvasId: string;
+  /** The canvas to include */
+  canvas: ExtendedCanvas;
+  /** Position offset - all nodes in this canvas will be translated by this amount */
+  position: { x: number; y: number };
+  /** Optional label for the canvas (for future visual grouping) */
+  label?: string;
+}
+
+/**
+ * Layout configuration for multiple canvases on a single graph
+ */
+export interface MultiCanvasLayout {
+  /** Array of canvas placements with positions */
+  placements: CanvasPlacement[];
+}
+
+/**
+ * Props for the MultiCanvasRenderer component
+ */
+export interface MultiCanvasRendererProps
+  extends Omit<GraphRendererProps, 'canvas' | 'editable'> {
+  /** Layout configuration containing canvas placements */
+  layout: MultiCanvasLayout;
+  /** Callback when layout changes (canvas positions updated) */
+  onLayoutChange?: (layout: MultiCanvasLayout) => void;
+  /** Whether to show group borders around each canvas (default: true) */
+  showGroups?: boolean;
+}
+
+// ============================================================================
+// Canvas Merging Utilities
+// ============================================================================
+
+const DEFAULT_NODE_WIDTH = 200;
+const DEFAULT_NODE_HEIGHT = 100;
+const GROUP_PADDING = 40;
+
+/**
+ * Create a prefixed node ID to avoid collisions between canvases
+ */
+function prefixNodeId(canvasId: string, nodeId: string): string {
+  return `${canvasId}:${nodeId}`;
+}
+
+/**
+ * Calculate the bounding box of nodes in a canvas (relative to canvas origin)
+ */
+function calculateCanvasBounds(canvas: ExtendedCanvas): {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+} {
+  if (!canvas.nodes || canvas.nodes.length === 0) {
+    return { minX: 0, minY: 0, maxX: DEFAULT_NODE_WIDTH, maxY: DEFAULT_NODE_HEIGHT };
+  }
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (const node of canvas.nodes) {
+    const x = node.x ?? 0;
+    const y = node.y ?? 0;
+    const width = node.width ?? DEFAULT_NODE_WIDTH;
+    const height = node.height ?? DEFAULT_NODE_HEIGHT;
+
+    minX = Math.min(minX, x);
+    minY = Math.min(minY, y);
+    maxX = Math.max(maxX, x + width);
+    maxY = Math.max(maxY, y + height);
+  }
+
+  return { minX, minY, maxX, maxY };
+}
+
+/**
+ * Merge multiple canvases into a single canvas with position offsets applied.
+ * Each canvas gets a group node border with its name as a label.
+ * Node IDs are prefixed with canvasId to avoid collisions (format: "canvasId:nodeId").
+ * Original IDs can be recovered using parseNodeId().
+ */
+export function mergeCanvases(
+  placements: CanvasPlacement[],
+  options: { showGroups?: boolean } = {}
+): ExtendedCanvas {
+  const { showGroups = true } = options;
+  const groupNodes: ExtendedCanvasNode[] = [];
+  const mergedNodes: ExtendedCanvasNode[] = [];
+  const mergedEdges: ExtendedCanvasEdge[] = [];
+
+  for (const placement of placements) {
+    const { canvasId, canvas, position, label } = placement;
+
+    // Calculate bounds for this canvas to create a group node
+    if (showGroups && canvas.nodes && canvas.nodes.length > 0) {
+      const bounds = calculateCanvasBounds(canvas);
+      const groupNode: ExtendedCanvasNode = {
+        id: `${canvasId}:__group__`,
+        type: 'group',
+        label: label ?? canvas.pv?.name ?? canvasId,
+        x: position.x + bounds.minX - GROUP_PADDING,
+        y: position.y + bounds.minY - GROUP_PADDING,
+        width: bounds.maxX - bounds.minX + GROUP_PADDING * 2,
+        height: bounds.maxY - bounds.minY + GROUP_PADDING * 2,
+      };
+      groupNodes.push(groupNode);
+    }
+
+    // Process nodes - apply position offset and prefix IDs
+    if (canvas.nodes) {
+      for (const node of canvas.nodes) {
+        const mergedNode: ExtendedCanvasNode = {
+          ...node,
+          id: prefixNodeId(canvasId, node.id),
+          x: (node.x ?? 0) + position.x,
+          y: (node.y ?? 0) + position.y,
+        };
+        mergedNodes.push(mergedNode);
+      }
+    }
+
+    // Process edges - update node references with prefixed IDs
+    if (canvas.edges) {
+      for (const edge of canvas.edges) {
+        const mergedEdge: ExtendedCanvasEdge = {
+          ...edge,
+          id: prefixNodeId(canvasId, edge.id),
+          fromNode: prefixNodeId(canvasId, edge.fromNode),
+          toNode: prefixNodeId(canvasId, edge.toNode),
+        };
+        mergedEdges.push(mergedEdge);
+      }
+    }
+  }
+
+  // Create merged canvas - group nodes first so they render behind
+  const mergedCanvas: ExtendedCanvas = {
+    name: 'Multi-Canvas View',
+    nodes: [...groupNodes, ...mergedNodes],
+    edges: mergedEdges,
+  };
+
+  return mergedCanvas;
+}
+
+/**
+ * Extract the original canvas ID and node ID from a merged node ID
+ */
+export function parseNodeId(
+  mergedNodeId: string
+): { canvasId: string; nodeId: string } | null {
+  const colonIndex = mergedNodeId.indexOf(':');
+  if (colonIndex === -1) return null;
+  return {
+    canvasId: mergedNodeId.substring(0, colonIndex),
+    nodeId: mergedNodeId.substring(colonIndex + 1),
+  };
+}
+
+// ============================================================================
+// MultiCanvasRenderer Component
+// ============================================================================
+
+/**
+ * Renders multiple canvases merged into a single graph view.
+ *
+ * Each canvas is positioned at its specified offset, and all nodes/edges
+ * are combined into a unified viewport. Node IDs are prefixed with their
+ * source canvas ID to avoid collisions (format: "canvasId:nodeId").
+ *
+ * @example
+ * ```tsx
+ * <MultiCanvasRenderer
+ *   layout={{
+ *     placements: [
+ *       { canvasId: 'auth', canvas: authCanvas, position: { x: 0, y: 0 } },
+ *       { canvasId: 'data', canvas: dataCanvas, position: { x: 600, y: 0 } },
+ *     ],
+ *   }}
+ *   showControls
+ * />
+ * ```
+ */
+export const MultiCanvasRenderer = forwardRef<
+  GraphRendererHandle,
+  MultiCanvasRendererProps
+>(function MultiCanvasRenderer(
+  { layout, onLayoutChange, showGroups = true, ...graphRendererProps },
+  ref
+) {
+  // Track group positions at the start of drag to calculate deltas
+  const groupPositionsRef = useRef<Map<string, { x: number; y: number }>>(new Map());
+
+  // Merge all canvases into a single canvas
+  const mergedCanvas = useMemo(
+    () => mergeCanvases(layout.placements, { showGroups }),
+    [layout.placements, showGroups]
+  );
+
+  // Calculate group node IDs for dragging
+  const draggableNodeIds = useMemo(() => {
+    if (!showGroups) return undefined;
+    const ids = new Set<string>();
+    for (const placement of layout.placements) {
+      if (placement.canvas.nodes && placement.canvas.nodes.length > 0) {
+        ids.add(`${placement.canvasId}:__group__`);
+      }
+    }
+    return ids.size > 0 ? ids : undefined;
+  }, [layout.placements, showGroups]);
+
+  // Store initial group positions whenever layout changes
+  useMemo(() => {
+    groupPositionsRef.current.clear();
+    for (const placement of layout.placements) {
+      if (placement.canvas.nodes && placement.canvas.nodes.length > 0) {
+        const bounds = calculateCanvasBounds(placement.canvas);
+        // Group position = placement position + bounds offset - padding
+        groupPositionsRef.current.set(`${placement.canvasId}:__group__`, {
+          x: placement.position.x + bounds.minX - GROUP_PADDING,
+          y: placement.position.y + bounds.minY - GROUP_PADDING,
+        });
+      }
+    }
+  }, [layout.placements]);
+
+  // Handle group drag to update layout positions
+  const handleNodeDragStop = useCallback(
+    (nodeId: string, newPosition: { x: number; y: number }) => {
+      // Only handle group nodes
+      if (!nodeId.endsWith(':__group__')) return;
+      if (!onLayoutChange) return;
+
+      const parsed = parseNodeId(nodeId);
+      if (!parsed) return;
+      const { canvasId } = parsed;
+
+      // Get the original group position
+      const originalGroupPos = groupPositionsRef.current.get(nodeId);
+      if (!originalGroupPos) return;
+
+      // Calculate delta
+      const deltaX = newPosition.x - originalGroupPos.x;
+      const deltaY = newPosition.y - originalGroupPos.y;
+
+      // Skip if no significant movement
+      if (Math.abs(deltaX) < 1 && Math.abs(deltaY) < 1) return;
+
+      // Create updated layout with new position for this canvas
+      const updatedPlacements = layout.placements.map((placement) => {
+        if (placement.canvasId === canvasId) {
+          return {
+            ...placement,
+            position: {
+              x: placement.position.x + deltaX,
+              y: placement.position.y + deltaY,
+            },
+          };
+        }
+        return placement;
+      });
+
+      onLayoutChange({ placements: updatedPlacements });
+    },
+    [layout.placements, onLayoutChange]
+  );
+
+  return (
+    <GraphRenderer
+      ref={ref}
+      canvas={mergedCanvas}
+      editable={false}
+      draggableNodeIds={draggableNodeIds}
+      onNodeDragStop={handleNodeDragStop}
+      {...graphRendererProps}
+    />
+  );
+});

package/src/components/NodeTooltip.tsx

@@ -0,0 +1,279 @@
+import React, { useEffect, useState, useContext } from 'react';
+import { createPortal } from 'react-dom';
+import { useTheme } from '@principal-ade/industry-theme';
+import { IndustryMarkdownSlide } from 'themed-markdown';
+import { TooltipPortalContext } from '../contexts/TooltipPortalContext';
+
+export interface OtelInfo {
+  kind: 'type' | 'service' | 'instance';
+  category?: string;
+  scope?: string;
+  files?: string[];
+}
+
+export interface NodeTooltipProps {
+  description?: string;
+  otel?: OtelInfo;
+  /** @deprecated Use otel.files instead */
+  sources?: string[];
+  /** External references (packages, documentation links) */
+  references?: string[];
+  visible: boolean;
+  /** Reference to the node element for positioning */
+  nodeRef?: React.RefObject<HTMLDivElement>;
+}
+
+/**
+ * Tooltip component for displaying node information on hover
+ * Uses a portal to render above all other elements
+ */
+export const NodeTooltip: React.FC<NodeTooltipProps> = ({
+  description,
+  otel,
+  sources,
+  references,
+  visible,
+  nodeRef,
+}) => {
+  const { theme } = useTheme();
+  const portalTarget = useContext(TooltipPortalContext);
+  const [position, setPosition] = useState<{ top: number; left: number } | null>(null);
+
+  useEffect(() => {
+    if (visible && nodeRef?.current && portalTarget) {
+      const nodeRect = nodeRef.current.getBoundingClientRect();
+      const containerRect = portalTarget.getBoundingClientRect();
+      // Position relative to the container, not the viewport
+      setPosition({
+        top: nodeRect.bottom - containerRect.top + 8, // 8px below the node
+        left: nodeRect.left - containerRect.left + nodeRect.width / 2, // centered horizontally
+      });
+    } else if (visible && nodeRef?.current && !portalTarget) {
+      // Fallback to viewport positioning if no portal target
+      const rect = nodeRef.current.getBoundingClientRect();
+      setPosition({
+        top: rect.bottom + 8,
+        left: rect.left + rect.width / 2,
+      });
+    } else if (!nodeRef) {
+      // No ref provided - will use relative positioning (for storybook demos)
+      setPosition({ top: 0, left: 0 });
+    }
+  }, [visible, nodeRef, portalTarget]);
+
+  if (!visible) return null;
+
+  // If no nodeRef, render inline (for storybook demos)
+  const usePortal = Boolean(nodeRef);
+
+  const getKindLabel = (kind: string) => {
+    switch (kind) {
+      case 'type':
+        return 'Type';
+      case 'service':
+        return 'Service';
+      case 'instance':
+        return 'Instance';
+      default:
+        return kind;
+    }
+  };
+
+  const getKindColor = (kind: string) => {
+    switch (kind) {
+      case 'type':
+        return '#4A90E2'; // Blue
+      case 'service':
+        return '#7ED321'; // Green
+      case 'instance':
+        return '#9B59B6'; // Purple
+      default:
+        return '#888';
+    }
+  };
+
+  const renderTooltipContent = (): React.JSX.Element => (
+    <div
+      style={{
+        // Use absolute positioning relative to portal target container
+        position: usePortal ? 'absolute' : 'absolute',
+        top: usePortal ? position?.top ?? 0 : '100%',
+        left: usePortal ? position?.left ?? 0 : '50%',
+        transform: 'translateX(-50%)',
+        marginTop: usePortal ? 0 : '8px',
+        padding: '8px 12px',
+        backgroundColor: 'rgba(0, 0, 0, 0.9)',
+        color: 'white',
+        borderRadius: '6px',
+        fontSize: theme.fontSizes[0],
+        fontFamily: theme.fonts.body,
+        maxWidth: '400px',
+        maxHeight: '500px',
+        zIndex: 99999,
+        pointerEvents: 'none',
+        boxShadow: '0 4px 12px rgba(0,0,0,0.4)',
+        whiteSpace: 'normal',
+        opacity: usePortal ? (position ? 1 : 0) : 1,
+        overflow: 'auto',
+      }}
+    >
+      {/* Arrow */}
+      <div
+        style={{
+          position: 'absolute',
+          top: '-6px',
+          left: '50%',
+          transform: 'translateX(-50%)',
+          width: 0,
+          height: 0,
+          borderLeft: '6px solid transparent',
+          borderRight: '6px solid transparent',
+          borderBottom: '6px solid rgba(0, 0, 0, 0.9)',
+        }}
+      />
+
+      {/* OTEL Badge */}
+      {otel && (
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '6px',
+            marginBottom: description || otel.scope ? '6px' : 0,
+          }}
+        >
+          <span
+            style={{
+              backgroundColor: getKindColor(otel.kind),
+              color: 'white',
+              padding: '2px 6px',
+              borderRadius: '3px',
+              fontSize: theme.fontSizes[0],
+              fontWeight: theme.fontWeights.semibold,
+              fontFamily: theme.fonts.body,
+              textTransform: 'uppercase',
+            }}
+          >
+            {getKindLabel(otel.kind)}
+          </span>
+          {otel.category && (
+            <span style={{ color: 'rgba(255,255,255,0.7)', fontSize: theme.fontSizes[0], fontFamily: theme.fonts.body }}>
+              {otel.category}
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Scope */}
+      {otel?.scope && (
+        <div style={{
+          marginBottom: description ? '6px' : 0,
+          fontSize: theme.fontSizes[0],
+          fontFamily: theme.fonts.body,
+          color: 'rgba(255,255,255,0.8)'
+        }}>
+          <span style={{
+            color: 'rgba(255,255,255,0.6)',
+            fontWeight: theme.fontWeights.semibold
+          }}>
+            Scope:
+          </span>{' '}
+          <span style={{ fontFamily: 'monospace' }}>{otel.scope}</span>
+        </div>
+      )}
+
+      {/* Description - rendered as markdown */}
+      {description ? (
+        <div style={{ lineHeight: '1.4', color: 'rgba(255,255,255,0.9)' }}>
+          <IndustryMarkdownSlide
+            content={description}
+            slideIdPrefix="tooltip"
+            slideIndex={0}
+            isVisible={true}
+            theme={{
+              ...theme,
+              colors: {
+                ...theme.colors,
+                background: 'transparent',
+                text: 'rgba(255,255,255,0.9)',
+              },
+            }}
+            transparentBackground={true}
+            disableScroll={true}
+            fontSizeScale={0.85}
+            enableKeyboardScrolling={false}
+            autoFocusOnVisible={false}
+          />
+        </div>
+      ) : (
+        <div style={{ lineHeight: '1.4', color: 'rgba(255,255,255,0.5)' }}>
+          No description
+        </div>
+      )}
+
+      {/* Source Files - from otel.files or deprecated sources */}
+      {(() => {
+        const sourceFiles = otel?.files || sources;
+        if (!sourceFiles || sourceFiles.length === 0) return null;
+        return (
+          <div style={{ marginTop: '8px', borderTop: '1px solid rgba(255,255,255,0.2)', paddingTop: '6px' }}>
+            <div style={{
+              fontSize: theme.fontSizes[0],
+              fontWeight: theme.fontWeights.semibold,
+              color: 'rgba(255,255,255,0.7)',
+              marginBottom: '4px'
+            }}>
+              Source Files:
+            </div>
+            <div style={{ fontSize: theme.fontSizes[0], color: 'rgba(255,255,255,0.8)' }}>
+              {sourceFiles.map((file, index) => (
+                <div key={index} style={{
+                  fontFamily: 'monospace',
+                  fontSize: theme.fontSizes[0],
+                  marginTop: index > 0 ? '2px' : 0,
+                  wordBreak: 'break-all'
+                }}>
+                  {file}
+                </div>
+              ))}
+            </div>
+          </div>
+        );
+      })()}
+
+      {/* References - external packages/documentation */}
+      {references && references.length > 0 && (
+        <div style={{ marginTop: '8px', borderTop: '1px solid rgba(255,255,255,0.2)', paddingTop: '6px' }}>
+          <div style={{
+            fontSize: theme.fontSizes[0],
+            fontWeight: theme.fontWeights.semibold,
+            color: 'rgba(255,255,255,0.7)',
+            marginBottom: '4px'
+          }}>
+            References:
+          </div>
+          <div style={{ fontSize: theme.fontSizes[0], color: 'rgba(255,255,255,0.8)' }}>
+            {references.map((ref, index) => (
+              <div key={index} style={{
+                fontFamily: 'monospace',
+                fontSize: theme.fontSizes[0],
+                marginTop: index > 0 ? '2px' : 0,
+                wordBreak: 'break-all'
+              }}>
+                {ref}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+
+  // Use portal to render in the graph container when available, otherwise render inline
+  if (usePortal) {
+    // Portal to graph container (hides with tab) or fallback to body
+    const target = portalTarget || document.body;
+    return createPortal(renderTooltipContent(), target);
+  }
+  return renderTooltipContent();
+};