@principal-ai/principal-view-react 0.14.21 → 0.14.23

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/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;

package/src/stories/CanvasEdgeTypes.stories.tsx

@@ -685,19 +685,17 @@ export const EdgeTypeDefinitions: Story = {
         story: `
 **Edge Type Definitions (PV Extension)**
 
-Define reusable edge types at the canvas level in \`pv.edgeTypes\`:
+Define reusable edge types at the canvas level in \`edgeTypes\`:
 
 \`\`\`json
 {
-  "pv": {
-    "edgeTypes": {
-      "depends-on": {
-        "label": "Dependency",
-        "style": "solid",
-        "color": "#ef4444",
-        "width": 2,
-        "directed": true
-      }
+  "edgeTypes": {
+    "depends-on": {
+      "label": "Dependency",
+      "style": "solid",
+      "color": "#ef4444",
+      "width": 2,
+      "directed": true
     }
   }
 }
@@ -917,23 +915,21 @@ const EdgeFieldsComparisonTemplate = () => {
       >
         <pre style={{ margin: 0 }}>
           {`{
-  "pv": {
-    "edgeTypes": {
-      "depends-on": {
-        "label": "Dependency",      // Display name
-        "style": "solid",           // solid | dashed | dotted | animated
-        "color": "#ef4444",         // Hex color
-        "width": 2,                 // Line width in pixels
-        "directed": true,           // Show arrow head
-        "animation": {              // Optional animation
-          "type": "flow",           // flow | pulse | particle | glow
-          "duration": 1000,         // Duration in ms
-          "color": "#ff0000"        // Animation color
-        },
-        "labelConfig": {            // Label positioning
-          "field": "weight",        // Data field to display
-          "position": "middle"      // start | middle | end
-        }
+  "edgeTypes": {
+    "depends-on": {
+      "label": "Dependency",      // Display name
+      "style": "solid",           // solid | dashed | dotted | animated
+      "color": "#ef4444",         // Hex color
+      "width": 2,                 // Line width in pixels
+      "directed": true,           // Show arrow head
+      "animation": {              // Optional animation
+        "type": "flow",           // flow | pulse | particle | glow
+        "duration": 1000,         // Duration in ms
+        "color": "#ff0000"        // Animation color
+      },
+      "labelConfig": {            // Label positioning
+        "field": "weight",        // Data field to display
+        "position": "middle"      // start | middle | end
       }
     }
   }