@principal-ai/principal-view-react 0.15.3 → 0.15.5

package/src/components/SequenceDiagramRenderer.tsx

@@ -14,6 +14,7 @@ import {
   ReactFlowProvider,
   Panel,
   useViewport,
+  useStore,
   Handle,
   Position,
   BaseEdge,
@@ -361,6 +362,8 @@ interface SwimlaneLayerProps {
   totalHeight: number;
   onToggleCollapse?: (namespace: string) => void;
   stickyHeaders?: boolean;
+  /** When true, render lane and header backgrounds as transparent. */
+  transparent?: boolean;
 }
 
 /**
@@ -371,12 +374,15 @@ function SwimlaneLayer({
   laneWidth,
   headerHeight,
   totalHeight,
+  transparent = false,
 }: SwimlaneLayerProps) {
   const { x, y, zoom } = useViewport();
+  const viewportHeight = useStore((s) => s.height);
   const { theme } = useTheme();
 
-  // Add a small buffer to ensure lanes extend slightly beyond the last event
-  const extendedHeight = totalHeight + 20;
+  // Extend lanes to cover the viewport bottom even when content is short.
+  // In flow-coord space, the visible viewport is `viewportHeight / zoom` tall.
+  const extendedHeight = Math.max(totalHeight + 20, viewportHeight / zoom + 100);
 
   return (
     <div
@@ -393,6 +399,11 @@ function SwimlaneLayer({
       {/* Lane backgrounds */}
       {swimlanes.map((lane, index) => {
         const isEven = index % 2 === 0;
+        const laneBackground = transparent
+          ? 'transparent'
+          : isEven
+            ? theme.colors.muted
+            : theme.colors.background;
         return (
           <div
             key={`bg-${lane.namespace}`}
@@ -402,9 +413,7 @@ function SwimlaneLayer({
               top: 0,
               width: laneWidth,
               height: extendedHeight,
-              backgroundColor: isEven
-                ? theme.colors.muted
-                : theme.colors.background,
+              backgroundColor: laneBackground,
               borderRight: `1px solid ${theme.colors.border}`,
             }}
           />
@@ -439,6 +448,7 @@ function SwimlaneHeadersLayer({
   headerHeight,
   onToggleCollapse,
   stickyHeaders = true,
+  transparent = false,
 }: SwimlaneLayerProps) {
   const { x, y, zoom } = useViewport();
   const { theme } = useTheme();
@@ -474,7 +484,9 @@ function SwimlaneHeadersLayer({
               display: 'flex',
               alignItems: 'center',
               justifyContent: 'center',
-              backgroundColor: theme.colors.muted,
+              padding: '0 8px',
+              boxSizing: 'border-box',
+              backgroundColor: transparent ? 'transparent' : theme.colors.muted,
               borderBottom: `2px solid ${theme.colors.border}`,
               fontWeight: theme.fontWeights.semibold,
               fontSize: theme.fontSizes[2],
@@ -491,7 +503,17 @@ function SwimlaneHeadersLayer({
                 {lane.isCollapsed ? '▼' : '▶'}
               </span>
             )}
-            <span>{lane.label}</span>
+            <span
+              style={{
+                overflowWrap: 'anywhere',
+                wordBreak: 'break-word',
+                lineHeight: 1.2,
+                textAlign: 'center',
+              }}
+              title={lane.label}
+            >
+              {lane.label}
+            </span>
           </div>
         );
       })}
@@ -547,6 +569,14 @@ export interface SequenceDiagramRendererProps {
 
   /** Whether to show event labels on nodes (default: false, labels already shown on edges) */
   showEventLabels?: boolean;
+
+  /**
+   * When true, render the diagram chrome (canvas background, swimlane fills,
+   * header backgrounds) as transparent so the diagram can be composited over
+   * an arbitrary backdrop. Lifelines, borders, edges, and label pills keep
+   * their theme colors so the diagram stays legible. Defaults to `false`.
+   */
+  transparent?: boolean;
 }
 
 /**
@@ -565,11 +595,12 @@ function SequenceDiagramInner({
   stickyHeaders = true,
   selectedNodeId,
   showEventLabels = false, // Default to false - labels already shown on edges
+  transparent = false,
 }: SequenceDiagramRendererProps) {
   const { theme } = useTheme();
 
   // Extract layout params
-  const { laneWidth = 200, headerHeight = 60 } = layoutOptions;
+  const { laneWidth = 250, headerHeight = 60 } = layoutOptions;
 
   // Merge custom node/edge types with sequence defaults
   const nodeTypes = useMemo(
@@ -582,7 +613,7 @@ function SequenceDiagramInner({
   );
 
   // Compute layout
-  const { nodes: layoutNodes, edges, swimlanes, totalHeight } = useSequenceLayout(
+  const { nodes: layoutNodes, edges, swimlanes, totalWidth, totalHeight } = useSequenceLayout(
     events,
     sequenceEdges,
     layoutOptions
@@ -629,22 +660,19 @@ function SequenceDiagramInner({
     [onNodeClick]
   );
 
-  // When sticky headers are enabled, limit upward panning to prevent headers from disconnecting
-  // from swimlane backgrounds. Allow downward panning to see all content.
+  // Clamp horizontal and vertical panning to content bounds so swimlanes and
+  // headers stay in view. When sticky headers are disabled, allow a small
+  // negative top buffer for visual breathing room.
   const translateExtent = useMemo(() => {
-    if (!stickyHeaders) {
-      // No restrictions when sticky headers are disabled
-      return undefined;
-    }
-
-    // Prevent panning up past the header area (y >= 0)
-    // Allow panning down to see all content (y can be positive up to totalHeight)
-    // Allow full horizontal panning
+    const xMin = 0;
+    const xMax = totalWidth;
+    const yMin = stickyHeaders ? 0 : -20;
+    const yMax = stickyHeaders ? totalHeight + 1000 : totalHeight + 20;
     return [
-      [-Infinity, 0],
-      [Infinity, totalHeight + 1000],
+      [xMin, yMin],
+      [xMax, yMax],
     ] as [[number, number], [number, number]];
-  }, [stickyHeaders, totalHeight]);
+  }, [stickyHeaders, totalWidth, totalHeight]);
 
   // When sticky headers are enabled, use defaultViewport to ensure we start at y=0
   // This prevents the snap-to-position issue on initial load
@@ -684,7 +712,7 @@ function SequenceDiagramInner({
       panOnScroll
       zoomOnScroll
       translateExtent={translateExtent}
-      style={{ background: theme.colors.background }}
+      style={{ background: transparent ? 'transparent' : theme.colors.background }}
     >
       {/* SVG defs for arrow markers */}
       <svg style={{ position: 'absolute', width: 0, height: 0 }}>
@@ -733,6 +761,7 @@ function SequenceDiagramInner({
         laneWidth={laneWidth}
         headerHeight={headerHeight}
         totalHeight={totalHeight}
+        transparent={transparent}
       />
 
       {/* Swimlane headers layer - renders on top for clickability */}
@@ -743,6 +772,7 @@ function SequenceDiagramInner({
         totalHeight={totalHeight}
         onToggleCollapse={onToggleCollapse}
         stickyHeaders={stickyHeaders}
+        transparent={transparent}
       />
 
       {/* Collapse toggle panel (for namespaces with children) */}

package/src/components/WorkflowSequenceDiagram.tsx

@@ -48,6 +48,13 @@ export interface WorkflowSequenceDiagramProps {
 
   /** Whether to show event labels on nodes (default: false, labels already shown on edges) */
   showEventLabels?: boolean;
+
+  /**
+   * When true, render the diagram chrome (canvas background, swimlane fills,
+   * header backgrounds) as transparent so the diagram can be composited over
+   * an arbitrary backdrop. Defaults to `false`.
+   */
+  transparent?: boolean;
 }
 
 /**
@@ -131,19 +138,25 @@ function convertWorkflowToSequence(
 
   // Convert to SequenceEvent format
   const events: SequenceEvent[] = eventNames.map((eventName, index) => {
-    const scope = eventToScopeMap.get(eventName) || 'unknown';
+    const canvasScope = eventToScopeMap.get(eventName);
     const label = eventToLabelMap.get(eventName) || eventName.split('.').pop() || eventName;
 
     // Determine if this is a move event
     // Default to true unless explicitly marked as transform event in participant node
     const isMoveEvent = eventToMoveEventMap.get(eventName) ?? true;
 
+    // When the canvas provides a scope, prefix it so the event lands in that
+    // participant's lane. Otherwise, use the event name as-is so the layout's
+    // namespace strategy can derive the participant from the event name itself.
+    const name = canvasScope ? `${canvasScope}.${eventName}` : eventName;
+    const participant = canvasScope ?? eventName.split('.')[0] ?? eventName;
+
     return {
       id: `event-${index}`,
-      name: `${scope}.${eventName}`,
+      name,
       label,
       moveEvent: isMoveEvent,
-      participant: scope,
+      participant,
     };
   });
 
@@ -192,6 +205,7 @@ export function WorkflowSequenceDiagram({
   onEventIndexChange,
   selectedEventIndex,
   showEventLabels = false, // Default to false - labels already on edges
+  transparent = false,
 }: WorkflowSequenceDiagramProps) {
   // Convert workflow to sequence format
   const { events, edges } = useMemo(
@@ -253,6 +267,7 @@ export function WorkflowSequenceDiagram({
       onNodeClick={onEventIndexChange ? handleNodeClick : undefined}
       selectedNodeId={selectedNodeId}
       showEventLabels={showEventLabels}
+      transparent={transparent}
     />
   );
 }

package/src/hooks/useSequenceLayout.ts

@@ -23,6 +23,14 @@ export interface SequenceEvent {
   moveEvent?: boolean;
   /** Participant this event belongs to (for move events, this is the target) */
   participant?: string;
+  /**
+   * Optional source-file path this event originated from, expressed
+   * relative to the repository root (e.g.
+   * `auth-server/src/lib/auth-provider.ts`). Surfaced on the React Flow
+   * node `data` so downstream renderers (file-city overlays, jump-to-source,
+   * IDE bridges) can react to selection without reaching into `data`.
+   */
+  sourcePath?: string;
   /** Additional data to pass through to the node */
   data?: Record<string, unknown>;
 }
@@ -84,7 +92,7 @@ export interface UseSequenceLayoutOptions {
 
   /**
    * Width of each swimlane
-   * @default 200
+   * @default 250
    */
   laneWidth?: number;
 
@@ -210,8 +218,8 @@ export function useSequenceLayout(
 ): UseSequenceLayoutResult {
   const {
     namespaceStrategy = 'all-but-last',
-    laneWidth = 200,
-    laneGap = 10,
+    laneWidth = 250,
+    laneGap = 0,
     eventSpacing = 80,
     headerHeight = 60,
     collapsedNamespaces = [],
@@ -334,6 +342,7 @@ export function useSequenceLayout(
           visibleNamespace,
           timeLayer: i,
           isMoveEvent: event.moveEvent === true,
+          sourcePath: event.sourcePath,
           ...event.data,
         },
         style: {

package/src/stories/ValidationEventsCanvas.stories.tsx

@@ -6,7 +6,7 @@ import type { ExtendedCanvas } from '@principal-ai/principal-view-core';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 
 // Import the CLI events canvas
-import validationEventsCanvasUrl from '../../../../.principal-views/cli.events.canvas?url';
+import validationEventsCanvasUrl from '../../../../.principal-views/principal-view-cli.events.canvas?url';
 
 // Helper to load canvas from URL
 async function loadCanvas(url: string): Promise<ExtendedCanvas> {

package/src/stories/WorkflowSequenceDiagram.stories.tsx

@@ -45,7 +45,7 @@ participant metadata from a canvas.
   decorators: [
     (Story) => (
       <ThemeProvider theme={defaultEditorTheme}>
-        <div style={{ padding: 20, height: '100vh', boxSizing: 'border-box' }}>
+        <div style={{ height: '100vh' }}>
           <Story />
         </div>
       </ThemeProvider>
@@ -143,6 +143,27 @@ const errorHandlingScenario: WorkflowScenario = {
   },
 };
 
+/**
+ * Scenario with long namespace titles for stress-testing swimlane header rendering
+ */
+const longTitlesScenario: WorkflowScenario = {
+  id: 'long-titles',
+  name: 'Long Swimlane Titles',
+  description: 'Scenario designed to stress-test header rendering with long participant names',
+  template: {
+    events: {
+      'authenticationAndAuthorizationService.request.received': {},
+      'authenticationAndAuthorizationService.token.validated': {},
+      'distributedTransactionCoordinator.transaction.started': {},
+      'inventoryReservationAndAllocationManager.items.reserved': {},
+      'paymentProcessingAndFraudDetectionGateway.charge.authorized': {},
+      'paymentProcessingAndFraudDetectionGateway.charge.captured': {},
+      'distributedTransactionCoordinator.transaction.committed': {},
+      'notificationDispatchAndDeliveryService.confirmation.sent': {},
+    },
+  },
+};
+
 /**
  * Empty scenario for testing empty state
  */
@@ -273,7 +294,7 @@ export const ClickDiagnostic: Story = {
 export const BasicScenario: Story = {
   args: {
     scenario: simpleAuthScenario,
-    height: 500,
+    height: '100%',
     layoutOptions: {
       namespaceStrategy: 'first',
       eventSpacing: 80,
@@ -288,7 +309,7 @@ export const WithCanvasMetadata: Story = {
   args: {
     scenario: simpleAuthScenario,
     canvas: sampleCanvas,
-    height: 500,
+    height: '100%',
     layoutOptions: {
       namespaceStrategy: 'first',
       eventSpacing: 80,
@@ -302,7 +323,7 @@ export const WithCanvasMetadata: Story = {
 export const ComplexWorkflow: Story = {
   args: {
     scenario: orderProcessingScenario,
-    height: 700,
+    height: '100%',
     layoutOptions: {
       namespaceStrategy: 'first',
       laneWidth: 200,
@@ -317,7 +338,7 @@ export const ComplexWorkflow: Story = {
 export const MicroservicesPattern: Story = {
   args: {
     scenario: microservicesScenario,
-    height: 600,
+    height: '100%',
     layoutOptions: {
       namespaceStrategy: 'first',
       laneWidth: 220,
@@ -332,7 +353,7 @@ export const MicroservicesPattern: Story = {
 export const ErrorHandling: Story = {
   args: {
     scenario: errorHandlingScenario,
-    height: 500,
+    height: '100%',
     layoutOptions: {
       namespaceStrategy: 'first',
       eventSpacing: 80,
@@ -346,7 +367,23 @@ export const ErrorHandling: Story = {
 export const EmptyState: Story = {
   args: {
     scenario: emptyScenario,
-    height: 300,
+    height: '100%',
+  },
+};
+
+/**
+ * Long swimlane titles - stress-tests header rendering with very long participant names.
+ * Use this to verify text wrapping, truncation, and overflow behavior in lane headers.
+ */
+export const LongSwimlaneTitles: Story = {
+  args: {
+    scenario: longTitlesScenario,
+    height: '100%',
+    layoutOptions: {
+      namespaceStrategy: 'first',
+      eventSpacing: 80,
+      headerHeight: 100,
+    },
   },
 };
 
@@ -605,7 +642,7 @@ export const NamespaceStrategies: Story = {
 export const CompactLayout: Story = {
   args: {
     scenario: simpleAuthScenario,
-    height: 400,
+    height: '100%',
     layoutOptions: {
       namespaceStrategy: 'first',
       laneWidth: 150,
@@ -621,7 +658,7 @@ export const CompactLayout: Story = {
 export const SpaciousLayout: Story = {
   args: {
     scenario: simpleAuthScenario,
-    height: 600,
+    height: '100%',
     layoutOptions: {
       namespaceStrategy: 'first',
       laneWidth: 250,
@@ -637,7 +674,7 @@ export const SpaciousLayout: Story = {
 export const WithoutControls: Story = {
   args: {
     scenario: simpleAuthScenario,
-    height: 500,
+    height: '100%',
     showControls: false,
     layoutOptions: {
       namespaceStrategy: 'first',
@@ -652,7 +689,7 @@ export const WithoutControls: Story = {
 export const WithBackground: Story = {
   args: {
     scenario: simpleAuthScenario,
-    height: 500,
+    height: '100%',
     showBackground: true,
     layoutOptions: {
       namespaceStrategy: 'first',