@principal-ai/principal-view-react 0.14.30 → 0.14.32

package/src/components/SequenceDiagramRenderer.tsx

@@ -36,42 +36,74 @@ import {
 
 /**
  * Minimal marker node for arrow-centric sequence diagrams
- * Invisible - just used for positioning, all rendering done by edges
- * Shows a visual indicator when selected
+ * Invisible - just used for positioning, selection is shown on edge labels
+ * Can optionally show a label for better clickability
  */
 function SequenceMarkerNode({ data, selected }: NodeProps) {
   const { theme } = useTheme();
+  const showLabel = data.showEventLabels === true; // Only show if explicitly enabled
+  const label = data.label as string | undefined;
 
+  // If labels are shown on nodes, render them
+  if (showLabel && label) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          position: 'relative',
+          cursor: 'pointer',
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+        title={data.fullName as string}
+      >
+        <div
+          style={{
+            padding: '6px 12px',
+            background: selected ? theme.colors.primary : theme.colors.background,
+            color: selected ? theme.colors.background : theme.colors.text,
+            border: `2px solid ${selected ? theme.colors.primary : theme.colors.border}`,
+            borderRadius: 4,
+            fontSize: theme.fontSizes[1],
+            fontWeight: selected ? theme.fontWeights.bold : theme.fontWeights.medium,
+            fontFamily: theme.fonts.body,
+            whiteSpace: 'nowrap',
+            pointerEvents: 'none',
+            userSelect: 'none',
+            transition: 'all 0.2s ease',
+            boxShadow: selected ? `0 2px 8px ${theme.colors.primary}40` : 'none',
+          }}
+        >
+          {label}
+        </div>
+        <Handle
+          type="target"
+          position={Position.Top}
+          style={{ visibility: 'hidden' }}
+        />
+        <Handle
+          type="source"
+          position={Position.Bottom}
+          style={{ visibility: 'hidden' }}
+        />
+      </div>
+    );
+  }
+
+  // Default: invisible node (selection shown on edge labels)
   return (
     <div
       style={{
         width: '100%',
         height: '100%',
         opacity: 0,
-        position: 'relative',
+        cursor: 'pointer',
       }}
       title={data.fullName as string}
     >
-      {/* Show indicator when selected */}
-      {selected && (
-        <div
-          style={{
-            position: 'absolute',
-            top: '50%',
-            left: '50%',
-            transform: 'translate(-50%, -50%)',
-            width: '12px',
-            height: '12px',
-            borderRadius: '50%',
-            backgroundColor: theme.colors.primary,
-            border: `2px solid ${theme.colors.background}`,
-            boxShadow: `0 0 0 2px ${theme.colors.primary}40`,
-            opacity: 1,
-            zIndex: 10,
-            pointerEvents: 'none',
-          }}
-        />
-      )}
       <Handle
         type="target"
         position={Position.Top}
@@ -104,6 +136,7 @@ function SequenceArrowEdge({
 
   // Use a straight line for same-lane, bezier for cross-lane
   const isSameLane = !data?.crossesLanes;
+  const isSourceSelected = data?.isSourceSelected === true;
 
   const [edgePath, labelX, labelY] = getBezierPath({
     sourceX,
@@ -132,16 +165,19 @@ function SequenceArrowEdge({
             style={{
               position: 'absolute',
               transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
-              background: theme.colors.background,
-              padding: '2px 8px',
+              background: isSourceSelected ? theme.colors.primary : theme.colors.background,
+              padding: isSourceSelected ? '4px 10px' : '2px 8px',
               borderRadius: 4,
               fontSize: theme.fontSizes[0],
-              fontWeight: theme.fontWeights.medium,
+              fontWeight: isSourceSelected ? theme.fontWeights.bold : theme.fontWeights.medium,
               fontFamily: theme.fonts.body,
-              color: theme.colors.text,
-              border: `1px solid ${theme.colors.border}`,
+              color: isSourceSelected ? theme.colors.background : theme.colors.text,
+              border: `${isSourceSelected ? 2 : 1}px solid ${isSourceSelected ? theme.colors.primary : theme.colors.border}`,
               pointerEvents: 'all',
               whiteSpace: 'nowrap',
+              cursor: 'pointer',
+              transition: 'all 0.2s ease',
+              boxShadow: isSourceSelected ? `0 2px 8px ${theme.colors.primary}60` : 'none',
             }}
             className="nodrag nopan"
           >
@@ -178,6 +214,7 @@ function SequenceArrowParticipantEdge({
 
   // Style based on whether it's a move event (IPC) or transform event (internal)
   const isMoveEvent = data?.isMoveEvent === true;
+  const isSourceSelected = data?.isSourceSelected === true;
   const strokeColor = isMoveEvent ? (theme.colors.accent || '#f48771') : theme.colors.primary;
 
   // Same lane: render as activation bar
@@ -224,16 +261,19 @@ function SequenceArrowParticipantEdge({
               style={{
                 position: 'absolute',
                 transform: `translate(0, -50%) translate(${sourceX + 15}px,${barY + barHeight / 2}px)`,
-                background: theme.colors.background,
-                padding: '2px 8px',
+                background: isSourceSelected ? strokeColor : theme.colors.background,
+                padding: isSourceSelected ? '4px 10px' : '2px 8px',
                 borderRadius: 4,
                 fontSize: theme.fontSizes[0],
-                fontWeight: theme.fontWeights.medium,
+                fontWeight: isSourceSelected ? theme.fontWeights.bold : theme.fontWeights.medium,
                 fontFamily: theme.fonts.body,
-                color: strokeColor,
-                border: `1px solid ${strokeColor}`,
+                color: isSourceSelected ? theme.colors.background : strokeColor,
+                border: `${isSourceSelected ? 2 : 1}px solid ${strokeColor}`,
                 pointerEvents: 'all',
                 whiteSpace: 'nowrap',
+                cursor: 'pointer',
+                transition: 'all 0.2s ease',
+                boxShadow: isSourceSelected ? `0 2px 8px ${strokeColor}60` : 'none',
               }}
               className="nodrag nopan"
             >
@@ -272,16 +312,19 @@ function SequenceArrowParticipantEdge({
             style={{
               position: 'absolute',
               transform: `translate(-50%, -50%) translate(${labelX}px,${labelY - 12}px)`,
-              background: theme.colors.background,
-              padding: isMoveEvent ? '3px 10px' : '2px 8px',
+              background: isSourceSelected ? strokeColor : theme.colors.background,
+              padding: isSourceSelected ? '5px 12px' : (isMoveEvent ? '3px 10px' : '2px 8px'),
               borderRadius: 4,
               fontSize: theme.fontSizes[0],
-              fontWeight: isMoveEvent ? theme.fontWeights.bold : theme.fontWeights.medium,
+              fontWeight: isSourceSelected ? theme.fontWeights.bold : (isMoveEvent ? theme.fontWeights.bold : theme.fontWeights.medium),
               fontFamily: theme.fonts.body,
-              color: strokeColor,
-              border: isMoveEvent ? `2px solid ${strokeColor}` : `1px solid ${strokeColor}`,
+              color: isSourceSelected ? theme.colors.background : strokeColor,
+              border: `${isSourceSelected ? 3 : (isMoveEvent ? 2 : 1)}px solid ${strokeColor}`,
               pointerEvents: 'all',
               whiteSpace: 'nowrap',
+              cursor: 'pointer',
+              transition: 'all 0.2s ease',
+              boxShadow: isSourceSelected ? `0 4px 12px ${strokeColor}60` : 'none',
             }}
             className="nodrag nopan"
           >
@@ -501,6 +544,9 @@ export interface SequenceDiagramRendererProps {
 
   /** Whether swimlane headers should stick to the top when scrolling vertically (default: true) */
   stickyHeaders?: boolean;
+
+  /** Whether to show event labels on nodes (default: false, labels already shown on edges) */
+  showEventLabels?: boolean;
 }
 
 /**
@@ -518,6 +564,7 @@ function SequenceDiagramInner({
   showBackground = false, // Default to false since swimlanes provide visual structure
   stickyHeaders = true,
   selectedNodeId,
+  showEventLabels = false, // Default to false - labels already shown on edges
 }: SequenceDiagramRendererProps) {
   const { theme } = useTheme();
 
@@ -541,15 +588,28 @@ function SequenceDiagramInner({
     layoutOptions
   );
 
-  // Mark selected node
+  // Mark selected node and add showEventLabels to node data
   const nodes = useMemo(() => {
-    if (!selectedNodeId) return layoutNodes;
-
     return layoutNodes.map(node => ({
       ...node,
       selected: node.id === selectedNodeId,
+      data: {
+        ...node.data,
+        showEventLabels,
+      },
+    }));
+  }, [layoutNodes, selectedNodeId, showEventLabels]);
+
+  // Add selectedNodeId to edge data so edges can highlight their labels
+  const edgesWithSelection = useMemo(() => {
+    return edges.map(edge => ({
+      ...edge,
+      data: {
+        ...edge.data,
+        isSourceSelected: edge.source === selectedNodeId,
+      },
     }));
-  }, [layoutNodes, selectedNodeId]);
+  }, [edges, selectedNodeId]);
 
   // Handle node click
   const handleNodeClick = useCallback(
@@ -559,6 +619,16 @@ function SequenceDiagramInner({
     [onNodeClick]
   );
 
+  // Handle edge click - extract source event from edge and trigger node selection
+  const handleEdgeClick = useCallback(
+    (_event: React.MouseEvent, edge: { id: string; source: string; target: string }) => {
+      // When clicking an edge, select the source event (the label describes the source)
+      // The edge label comes from the source event, so clicking it should select that event
+      onNodeClick?.(edge.source, _event);
+    },
+    [onNodeClick]
+  );
+
   // When sticky headers are enabled, limit upward panning to prevent headers from disconnecting
   // from swimlane backgrounds. Allow downward panning to see all content.
   const translateExtent = useMemo(() => {
@@ -600,10 +670,11 @@ function SequenceDiagramInner({
   return (
     <ReactFlow
       nodes={nodes}
-      edges={edges}
+      edges={edgesWithSelection}
       nodeTypes={nodeTypes}
       edgeTypes={edgeTypes}
       onNodeClick={handleNodeClick}
+      onEdgeClick={handleEdgeClick}
       {...viewportConfig}
       minZoom={0.1}
       maxZoom={2}

package/src/components/WorkflowSequenceDiagram.tsx

@@ -45,6 +45,9 @@ export interface WorkflowSequenceDiagramProps {
 
   /** Currently selected event index (0-based) for visual highlighting */
   selectedEventIndex?: number;
+
+  /** Whether to show event labels on nodes (default: false, labels already shown on edges) */
+  showEventLabels?: boolean;
 }
 
 /**
@@ -188,6 +191,7 @@ export function WorkflowSequenceDiagram({
   className,
   onEventIndexChange,
   selectedEventIndex,
+  showEventLabels = false, // Default to false - labels already on edges
 }: WorkflowSequenceDiagramProps) {
   // Convert workflow to sequence format
   const { events, edges } = useMemo(
@@ -248,6 +252,7 @@ export function WorkflowSequenceDiagram({
       className={className}
       onNodeClick={onEventIndexChange ? handleNodeClick : undefined}
       selectedNodeId={selectedNodeId}
+      showEventLabels={showEventLabels}
     />
   );
 }

package/src/nodes/otel/OtelEventNode.tsx

@@ -99,9 +99,11 @@ export const OtelEventNode: React.FC<NodeProps<Node<OtelEventNodeData>>> = ({
   // Color resolution
   const scopeColor = nodeData.scopeColor as string | undefined;
   const spanColor = nodeData.spanColor as string | undefined;
-  const nodeDataColor = nodeData.color as string | undefined;
-  // Fill color priority: explicit color > scope color > type definition color > default blue
-  const baseFillColor = nodeDataColor || scopeColor || typeDefinition.color || '#3b82f6';
+
+  // OTEL nodes use scope-based coloring exclusively
+  // Priority: scopeColor (from library.yaml) → typeDefinition.color → default
+  // Note: node.fill and node.color fields are intentionally ignored (validation enforces this)
+  const baseFillColor = scopeColor || typeDefinition.color || '#3b82f6';
   const fillColor = baseFillColor;
   // Stroke color priority: explicit stroke > span color (workflow context) > fill color
   const nodeDataStroke = nodeData.stroke as string | undefined;

package/src/stories/ValidationEventsCanvas.stories.tsx

@@ -0,0 +1,209 @@
+import React, { useState, useEffect } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '@xyflow/react/dist/style.css';
+import { GraphRenderer } from '../components/GraphRenderer';
+import type { ExtendedCanvas } from '@principal-ai/principal-view-core';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+
+// Import the validation events canvas
+import validationEventsCanvasUrl from '../../../../.principal-views/validation/validation.events.canvas?url';
+
+// Helper to load canvas from URL
+async function loadCanvas(url: string): Promise<ExtendedCanvas> {
+  const response = await fetch(url);
+  return await response.json();
+}
+
+// Wrapper component that loads canvas data
+function CanvasLoader({ url, children }: { url: string; children: (canvas: ExtendedCanvas) => React.ReactNode }) {
+  const [canvas, setCanvas] = useState<ExtendedCanvas | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadCanvas(url)
+      .then(setCanvas)
+      .catch((err) => setError(err.message));
+  }, [url]);
+
+  if (error) {
+    return <div style={{ padding: 20, color: 'red' }}>Error loading canvas: {error}</div>;
+  }
+
+  if (!canvas) {
+    return <div style={{ padding: 20 }}>Loading canvas...</div>;
+  }
+
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      {children(canvas)}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Validation/Event Namespace Canvas',
+  component: GraphRenderer,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ width: '100vw', height: '100vh' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof GraphRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Validation Event Namespace Canvas
+ *
+ * File: .principal-views/validation/validation.events.canvas
+ * Type: event-namespace nodes
+ * Purpose: Shows the vocabulary of events emitted during validation workflows
+ */
+export const EventNamespaceVocabulary: Story = {
+  render: () => (
+    <CanvasLoader url={validationEventsCanvasUrl}>
+      {(canvas) => <GraphRenderer canvas={canvas} showBackground={false} editable={true} />}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Renders the **validation.events.canvas** file - an event namespace vocabulary canvas.
+
+## Event Namespace Canvas Concept
+
+Unlike span canvases (which show user workflows) or OTEL event canvases (which show individual events),
+this canvas shows the **vocabulary of event namespaces** and their adjacency relationships.
+
+### Structure
+
+**Nodes = Event Namespaces**
+- \`analysis\` - Analysis pipeline lifecycle events
+- \`validation\` - Validation lifecycle events (started, complete, error)
+- \`file\` - File parsing events
+- \`type\` - Type detection events
+- etc.
+
+Each namespace node documents all events within that namespace with their attributes.
+
+**Edges = Adjacency**
+- Edges represent when events from one namespace appear adjacent to events from another namespace in workflow scenarios
+- Example: \`analysis → filetree\` because \`analysis.started → filetree.built\` in scenarios
+- Example: \`file → validation\` because \`file.parsed → validation.error\` in scenarios
+
+### Purpose
+
+This canvas serves as:
+1. **Event vocabulary documentation** - What events can be emitted
+2. **Flow visualization** - How events from different namespaces connect
+3. **Implementation guide** - What attributes each event requires
+4. **Validation source** - Canvas edges must match actual workflow scenario adjacencies
+
+### Conventions
+
+As defined in \`.principal-views/architecture.events.md\`:
+- Events follow \`{namespace}.{action}.{detail}\` naming
+- Edges represent direct adjacency only (not transitive)
+- Canvas is validated against workflow scenario files
+- Namespaces group code-level implementation events (vs user-level workflow spans)
+
+**Use this to:**
+- Preview event namespace canvas rendering
+- Understand event flow architecture
+- Document which events your code emits
+- Validate event relationships match actual code
+        `,
+      },
+    },
+  },
+};
+
+/**
+ * Event Namespace Canvas with Annotations
+ *
+ * Shows the canvas with additional context about what each namespace contains
+ */
+export const WithNamespaceDetails: Story = {
+  render: () => (
+    <CanvasLoader url={validationEventsCanvasUrl}>
+      {(canvas) => (
+        <div style={{ display: 'flex', height: '100vh' }}>
+          <div style={{ flex: 1 }}>
+            <GraphRenderer canvas={canvas} showBackground={false} editable={true} />
+          </div>
+          <div style={{
+            width: '350px',
+            padding: '20px',
+            backgroundColor: '#f5f5f5',
+            overflowY: 'auto',
+            fontFamily: 'system-ui, -apple-system, sans-serif'
+          }}>
+            <h2 style={{ marginTop: 0, fontSize: '18px' }}>Event Namespaces</h2>
+            <p style={{ fontSize: '14px', color: '#666' }}>
+              Each node represents a namespace grouping related events.
+            </p>
+
+            <div style={{ marginTop: '20px' }}>
+              <h3 style={{ fontSize: '14px', marginBottom: '8px' }}>Discovery Phase</h3>
+              <ul style={{ fontSize: '13px', lineHeight: '1.6', paddingLeft: '20px' }}>
+                <li><strong>analysis</strong> - Pipeline start</li>
+                <li><strong>filetree</strong> - Repository scanning</li>
+                <li><strong>packages</strong> - Package discovery</li>
+                <li><strong>canvases</strong> - Canvas file discovery</li>
+                <li><strong>executions</strong> - Execution file discovery</li>
+                <li><strong>library</strong> - Component library loading</li>
+                <li><strong>discovery</strong> - Phase completion</li>
+              </ul>
+            </div>
+
+            <div style={{ marginTop: '20px' }}>
+              <h3 style={{ fontSize: '14px', marginBottom: '8px' }}>Validation Phase</h3>
+              <ul style={{ fontSize: '13px', lineHeight: '1.6', paddingLeft: '20px' }}>
+                <li><strong>validation</strong> - Lifecycle (started, complete, error)</li>
+                <li><strong>file</strong> - Parsing operations</li>
+                <li><strong>type</strong> - Type detection</li>
+                <li><strong>canvas</strong> - Canvas validation</li>
+                <li><strong>workflow</strong> - Workflow validation</li>
+                <li><strong>execution</strong> - Execution validation</li>
+                <li><strong>rules</strong> - Lint rule execution</li>
+                <li><strong>results</strong> - Result aggregation</li>
+              </ul>
+            </div>
+
+            <div style={{ marginTop: '20px', padding: '12px', backgroundColor: '#fff3cd', borderRadius: '4px' }}>
+              <h4 style={{ fontSize: '13px', marginTop: 0 }}>Adjacency Edges</h4>
+              <p style={{ fontSize: '12px', margin: 0, color: '#856404' }}>
+                Edges show when events from one namespace appear next to events from another namespace
+                in workflow scenarios. These are validated against actual execution traces.
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Same canvas with a side panel showing namespace details and explanations.
+
+This view helps:
+- Understand what each namespace contains
+- See the phase groupings (discovery vs validation)
+- Learn the event namespace canvas concept
+        `,
+      },
+    },
+  },
+};