@principal-ai/principal-view-react 0.14.22 → 0.14.24

package/src/components/state-view/useStateView.ts

@@ -0,0 +1,205 @@
+/**
+ * useStateView Hook
+ *
+ * Manages state accumulation from events and provides replay controls.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import type {
+  StateEvent,
+  EventSource,
+  StateReducer,
+  StateDiff,
+  ReplayControls,
+  ActiveAnimation,
+  TransitionDefinition,
+} from './types';
+
+export interface UseStateViewOptions<TState, TEvent extends StateEvent> {
+  /** Initial state */
+  initialState: TState;
+  /** Reducer to apply events */
+  reducer: StateReducer<TState, TEvent>;
+  /** Event source (live or replay) */
+  eventSource: EventSource<TEvent>;
+  /** Transition definitions for animations */
+  transitions?: TransitionDefinition[];
+  /** Callback when state changes */
+  onStateChange?: (diff: StateDiff<TState>) => void;
+}
+
+export interface UseStateViewResult<TState> {
+  /** Current state */
+  state: TState;
+  /** Active animations */
+  animations: ActiveAnimation[];
+  /** Whether we're in replay mode */
+  isReplay: boolean;
+  /** Replay controls (if in replay mode) */
+  replayControls?: ReplayControls;
+  /** Reset state to initial */
+  reset: () => void;
+}
+
+/**
+ * Get changed paths between two objects (shallow comparison)
+ */
+function getChangedPaths(prev: unknown, next: unknown, prefix = ''): string[] {
+  const paths: string[] = [];
+
+  if (prev === next) return paths;
+
+  if (
+    typeof prev !== 'object' ||
+    typeof next !== 'object' ||
+    prev === null ||
+    next === null
+  ) {
+    return prefix ? [prefix] : [];
+  }
+
+  const prevObj = prev as Record<string, unknown>;
+  const nextObj = next as Record<string, unknown>;
+
+  const allKeys = new Set([...Object.keys(prevObj), ...Object.keys(nextObj)]);
+
+  for (const key of allKeys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (prevObj[key] !== nextObj[key]) {
+      paths.push(path);
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Check if a transition should fire based on state change
+ */
+function shouldTriggerTransition(
+  transition: TransitionDefinition,
+  prev: unknown,
+  next: unknown,
+  changedPaths: string[]
+): boolean {
+  // Check if the watched path changed
+  if (!changedPaths.some((p) => p.startsWith(transition.watch))) {
+    return false;
+  }
+
+  const prevValue = getValueAtPath(prev, transition.watch);
+  const nextValue = getValueAtPath(next, transition.watch);
+
+  switch (transition.condition) {
+    case 'changed':
+      return prevValue !== nextValue;
+    case 'increased':
+      return typeof nextValue === 'number' && typeof prevValue === 'number' && nextValue > prevValue;
+    case 'decreased':
+      return typeof nextValue === 'number' && typeof prevValue === 'number' && nextValue < prevValue;
+    case 'added':
+      return prevValue === undefined && nextValue !== undefined;
+    case 'removed':
+      return prevValue !== undefined && nextValue === undefined;
+    default:
+      return false;
+  }
+}
+
+function getValueAtPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+export function useStateView<TState, TEvent extends StateEvent>({
+  initialState,
+  reducer,
+  eventSource,
+  transitions = [],
+  onStateChange,
+}: UseStateViewOptions<TState, TEvent>): UseStateViewResult<TState> {
+  const [state, setState] = useState<TState>(initialState);
+  const [animations, setAnimations] = useState<ActiveAnimation[]>([]);
+  const prevStateRef = useRef<TState>(initialState);
+  const animationIdRef = useRef(0);
+
+  const triggerAnimation = useCallback(
+    (transition: TransitionDefinition, _event: StateEvent) => {
+      const id = `anim-${++animationIdRef.current}`;
+      const duration = transition.duration ?? 500;
+
+      const animation: ActiveAnimation = {
+        id,
+        type: transition.animate,
+        target: transition.target ?? transition.watch,
+        startTime: Date.now(),
+        duration,
+        params: transition.params,
+      };
+
+      setAnimations((prev) => [...prev, animation]);
+
+      // Auto-remove after duration
+      setTimeout(() => {
+        setAnimations((prev) => prev.filter((a) => a.id !== id));
+      }, duration);
+    },
+    []
+  );
+
+  const handleEvent = useCallback(
+    (event: TEvent) => {
+      setState((prevState) => {
+        const nextState = reducer(prevState, event);
+        const changedPaths = getChangedPaths(prevState, nextState);
+
+        // Trigger animations based on transitions
+        for (const transition of transitions) {
+          if (shouldTriggerTransition(transition, prevState, nextState, changedPaths)) {
+            triggerAnimation(transition, event);
+          }
+        }
+
+        // Notify listener
+        if (onStateChange && changedPaths.length > 0) {
+          onStateChange({
+            prev: prevState,
+            next: nextState,
+            changedPaths,
+            event,
+          });
+        }
+
+        prevStateRef.current = nextState;
+        return nextState;
+      });
+    },
+    [reducer, transitions, onStateChange, triggerAnimation]
+  );
+
+  // Subscribe to event source
+  useEffect(() => {
+    const unsubscribe = eventSource.subscribe(handleEvent);
+    return unsubscribe;
+  }, [eventSource, handleEvent]);
+
+  const reset = useCallback(() => {
+    setState(initialState);
+    setAnimations([]);
+    prevStateRef.current = initialState;
+  }, [initialState]);
+
+  const isReplay = eventSource.mode === 'replay';
+
+  return {
+    state,
+    animations,
+    isReplay,
+    reset,
+  };
+}

package/src/hooks/useSequenceLayout.ts

@@ -86,7 +86,7 @@ export interface UseSequenceLayoutOptions {
 
   /**
    * Gap between swimlanes
-   * @default 50
+   * @default 10
    */
   laneGap?: number;
 
@@ -207,7 +207,7 @@ export function useSequenceLayout(
   const {
     namespaceStrategy = 'all-but-last',
     laneWidth = 200,
-    laneGap = 50,
+    laneGap = 10,
     eventSpacing = 80,
     headerHeight = 60,
     collapsedNamespaces = [],
@@ -316,7 +316,8 @@ export function useSequenceLayout(
       const lane = swimlaneByNamespace.get(visibleNamespace)!;
 
       // Global Y position based on event order (time layer)
-      const y = headerHeight + i * eventSpacing;
+      // Start first event closer to header with small offset
+      const y = headerHeight + 40 + i * eventSpacing;
 
       nodes.push({
         id: event.id,
@@ -369,9 +370,37 @@ export function useSequenceLayout(
 
     // Step 6: Compute total dimensions
     const totalWidth =
-      swimlanes.length * (laneWidth + laneGap) - laneGap + laneWidth;
+      swimlanes.length * laneWidth + (swimlanes.length - 1) * laneGap;
     // Total height based on number of events (time layers)
-    const totalHeight = headerHeight + events.length * eventSpacing + eventSpacing;
+    const totalHeight = headerHeight + 40 + events.length * eventSpacing;
+
+    // Step 7: Add invisible boundary nodes to ensure fitView includes full diagram width
+    if (swimlanes.length > 0) {
+      const leftmostLane = swimlanes[0];
+      const rightmostLane = swimlanes[swimlanes.length - 1];
+
+      // Add boundary nodes at the corners
+      nodes.push(
+        {
+          id: '__boundary_left__',
+          type: 'default',
+          position: { x: leftmostLane.x - laneWidth / 2, y: 0 },
+          data: {},
+          style: { width: 1, height: 1, opacity: 0 },
+          draggable: false,
+          selectable: false,
+        },
+        {
+          id: '__boundary_right__',
+          type: 'default',
+          position: { x: rightmostLane.x + laneWidth / 2, y: totalHeight },
+          data: {},
+          style: { width: 1, height: 1, opacity: 0 },
+          draggable: false,
+          selectable: false,
+        }
+      );
+    }
 
     return {
       nodes,

package/src/index.ts

@@ -164,3 +164,39 @@ export type {
   SourceLinkProps,
   TimeRangeSelectorProps,
 } from './components/dashboard';
+
+// State View components for event-driven state visualization
+export { PipelineView, useStateView } from './components/state-view';
+export type {
+  // Core types
+  StateEvent,
+  EventSource,
+  StateReducer,
+  StateDiff,
+  TransitionDefinition,
+  ActiveAnimation,
+  AnimationType,
+  ReplayControls,
+  StateViewDefinition,
+  // Pipeline view types
+  PipelineState,
+  PipelineStage,
+  PipelineRepoState,
+  PipelineEvent,
+  PipelineEventType,
+  // Activity view types
+  ActivityState,
+  RoomState,
+  ActivityEvent,
+  ActivityEventType,
+  // Quota view types
+  QuotaDistributionState,
+  UserQuotaState,
+  QuotaEvent,
+  QuotaEventType,
+  // Hook types
+  UseStateViewOptions,
+  UseStateViewResult,
+  // Component props
+  PipelineViewProps,
+} from './components/state-view';

package/src/nodes/CustomNode.tsx

@@ -442,8 +442,8 @@ export const CustomNode: React.FC<NodeProps<Node<CustomNodeData>>> = (props) =>
   }
 
   // Color Contract:
-  // - scopeColor: Used as BORDER color (from library.yaml owned-scopes)
-  // - spanColor: Used as FILL color (from .spans.canvas based on workflow context)
+  // - scopeColor: Used as FILL/background color (from library.yaml scopes)
+  // - spanColor: Used as BORDER color in workflow context (from .spans.canvas)
   // - For non-event canvases, falls back to legacy behavior (node color or type color)
 
   // Get colors from node data (injected by GraphRenderer)
@@ -458,15 +458,15 @@ export const CustomNode: React.FC<NodeProps<Node<CustomNodeData>>> = (props) =>
   const stateColor =
     state && (nodeDataStates?.[state]?.color || typeDefinition.states?.[state]?.color);
 
-  // Fill color priority: state color > span color > node data color > type definition color > default
-  // spanColor is the new primary source for fill (from .spans.canvas)
-  const baseFillColor = spanColor || nodeDataColor || typeDefinition.color || '#888';
+  // Fill color priority: state color > node data color > scope color > type definition color > default
+  // scopeColor provides background color from the scope definition in library.yaml
+  const baseFillColor = nodeDataColor || scopeColor || typeDefinition.color || '#888';
   const fillColor = stateColor || baseFillColor;
 
-  // Stroke/border color priority: explicit stroke > scope color > fill color
-  // scopeColor is now the primary source for border (from library.yaml owned-scopes)
+  // Stroke/border color priority: explicit stroke > span color (workflow context) > fill color
+  // spanColor provides border color in workflow context (from .spans.canvas)
   const nodeDataStroke = nodeData.stroke as string | undefined;
-  const baseStrokeColor = nodeDataStroke || scopeColor || fillColor;
+  const baseStrokeColor = nodeDataStroke || spanColor || fillColor;
 
   // Apply status-based border styling
   const status = nodeData?.status as 'draft' | 'approved' | 'implemented' | undefined;

package/src/nodes/otel/OtelBoundaryNode.tsx

@@ -97,13 +97,15 @@ export const OtelBoundaryNode: React.FC<NodeProps<Node<OtelBoundaryNodeData>>> =
   const nodeOpacity = isHidden ? 0.4 : isActive ? 1 : 0.1;
 
   // Color resolution
+  const scopeColor = nodeData.scopeColor as string | undefined;
   const spanColor = nodeData.spanColor as string | undefined;
   const nodeDataColor = nodeData.color as string | undefined;
-  const baseFillColor = spanColor || nodeDataColor || typeDefinition.color || '#06b6d4';
+  // Fill color priority: explicit color > scope color > type definition color > default cyan
+  const baseFillColor = nodeDataColor || scopeColor || typeDefinition.color || '#06b6d4';
   const fillColor = baseFillColor;
-  const scopeColor = nodeData.scopeColor as string | undefined;
+  // Stroke color priority: explicit stroke > span color (workflow context) > fill color
   const nodeDataStroke = nodeData.stroke as string | undefined;
-  const strokeColor = nodeDataStroke || scopeColor || fillColor;
+  const strokeColor = nodeDataStroke || spanColor || fillColor;
 
   // Display info
   const displayName = nodeProps.name;

package/src/nodes/otel/OtelEventNode.tsx

@@ -97,13 +97,15 @@ export const OtelEventNode: React.FC<NodeProps<Node<OtelEventNodeData>>> = ({
   const nodeOpacity = isHidden ? 0.4 : isActive ? 1 : 0.1;
 
   // Color resolution
+  const scopeColor = nodeData.scopeColor as string | undefined;
   const spanColor = nodeData.spanColor as string | undefined;
   const nodeDataColor = nodeData.color as string | undefined;
-  const baseFillColor = spanColor || nodeDataColor || typeDefinition.color || '#3b82f6';
+  // Fill color priority: explicit color > scope color > type definition color > default blue
+  const baseFillColor = nodeDataColor || scopeColor || typeDefinition.color || '#3b82f6';
   const fillColor = baseFillColor;
-  const scopeColor = nodeData.scopeColor as string | undefined;
+  // Stroke color priority: explicit stroke > span color (workflow context) > fill color
   const nodeDataStroke = nodeData.stroke as string | undefined;
-  const strokeColor = nodeDataStroke || scopeColor || fillColor;
+  const strokeColor = nodeDataStroke || spanColor || fillColor;
 
   // Display info
   const displayName = nodeProps.name;

package/src/nodes/otel/OtelResourceNode.tsx

@@ -97,13 +97,15 @@ export const OtelResourceNode: React.FC<NodeProps<Node<OtelResourceNodeData>>> =
   const nodeOpacity = isHidden ? 0.4 : isActive ? 1 : 0.1;
 
   // Color resolution
+  const scopeColor = nodeData.scopeColor as string | undefined;
   const spanColor = nodeData.spanColor as string | undefined;
   const nodeDataColor = nodeData.color as string | undefined;
-  const baseFillColor = spanColor || nodeDataColor || typeDefinition.color || '#f97316';
+  // Fill color priority: explicit color > scope color > type definition color > default orange
+  const baseFillColor = nodeDataColor || scopeColor || typeDefinition.color || '#f97316';
   const fillColor = baseFillColor;
-  const scopeColor = nodeData.scopeColor as string | undefined;
+  // Stroke color priority: explicit stroke > span color (workflow context) > fill color
   const nodeDataStroke = nodeData.stroke as string | undefined;
-  const strokeColor = nodeDataStroke || scopeColor || fillColor;
+  const strokeColor = nodeDataStroke || spanColor || fillColor;
 
   // Display info
   const displayName = nodeProps.name;

package/src/nodes/otel/OtelScopeNode.tsx

@@ -94,13 +94,15 @@ export const OtelScopeNode: React.FC<NodeProps<Node<OtelScopeNodeData>>> = ({
   const nodeOpacity = isHidden ? 0.4 : isActive ? 1 : 0.1;
 
   // Color resolution
+  const scopeColor = nodeData.scopeColor as string | undefined;
   const spanColor = nodeData.spanColor as string | undefined;
   const nodeDataColor = nodeData.color as string | undefined;
-  const baseFillColor = spanColor || nodeDataColor || typeDefinition.color || '#22c55e';
+  // Fill color priority: explicit color > scope color > type definition color > default green
+  const baseFillColor = nodeDataColor || scopeColor || typeDefinition.color || '#22c55e';
   const fillColor = baseFillColor;
-  const scopeColor = nodeData.scopeColor as string | undefined;
+  // Stroke color priority: explicit stroke > span color (workflow context) > fill color
   const nodeDataStroke = nodeData.stroke as string | undefined;
-  const strokeColor = nodeDataStroke || scopeColor || fillColor;
+  const strokeColor = nodeDataStroke || spanColor || fillColor;
 
   // Display info
   const displayName = nodeProps.name;

package/src/nodes/otel/OtelSpanConventionNode.tsx

@@ -113,14 +113,15 @@ export const OtelSpanConventionNode: React.FC<
   const nodeOpacity = isHidden ? 0.4 : isActive ? 1 : 0.1;
 
   // Color resolution
+  const scopeColor = nodeData.scopeColor as string | undefined;
   const spanColor = nodeData.spanColor as string | undefined;
   const nodeDataColor = nodeData.color as string | undefined;
-  const baseFillColor = spanColor || nodeDataColor || typeDefinition.color || '#8b5cf6';
+  // Fill color priority: explicit color > scope color > type definition color > default purple
+  const baseFillColor = nodeDataColor || scopeColor || typeDefinition.color || '#8b5cf6';
   const fillColor = baseFillColor;
-
-  const scopeColor = nodeData.scopeColor as string | undefined;
+  // Stroke color priority: explicit stroke > span color (workflow context) > fill color
   const nodeDataStroke = nodeData.stroke as string | undefined;
-  const strokeColor = nodeDataStroke || scopeColor || fillColor;
+  const strokeColor = nodeDataStroke || spanColor || fillColor;
 
   // Get display info
   const displayName = nodeProps.name;