@principal-ai/subsystems-react 0.17.0 → 0.18.0

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

@@ -1,261 +0,0 @@
-/**
- * State View Types
- *
- * A state-based visualization system where:
- * - Telemetry events are processed into state changes
- * - State has a defined shape
- * - State changes trigger animations/transitions
- */
-
-// =============================================================================
-// Core Event Types
-// =============================================================================
-
-/**
- * A state event extracted from telemetry (OTEL spans, etc.)
- */
-export interface StateEvent<TPayload = Record<string, unknown>> {
-  /** Event type identifier */
-  type: string;
-  /** When this event occurred */
-  timestamp: number;
-  /** Event-specific data */
-  payload: TPayload;
-  /** Optional trace correlation */
-  traceId?: string;
-  spanId?: string;
-}
-
-/**
- * Source of events - can be live (IPC/WebSocket) or replay (from storage)
- */
-export interface EventSource<TEvent extends StateEvent = StateEvent> {
-  /** Subscribe to events, returns unsubscribe function */
-  subscribe(handler: (event: TEvent) => void): () => void;
-  /** Optional: current mode */
-  mode?: 'live' | 'replay';
-}
-
-// =============================================================================
-// State Types
-// =============================================================================
-
-/**
- * A reducer that applies events to state
- */
-export type StateReducer<TState, TEvent extends StateEvent> = (
-  state: TState,
-  event: TEvent
-) => TState;
-
-/**
- * Describes what changed between two states (for animations)
- */
-export interface StateDiff<TState> {
-  /** Previous state */
-  prev: TState;
-  /** New state */
-  next: TState;
-  /** Which paths changed (dot notation) */
-  changedPaths: string[];
-  /** The event that caused this change */
-  event: StateEvent;
-}
-
-// =============================================================================
-// Animation/Transition Types
-// =============================================================================
-
-export type AnimationType =
-  | 'pulse'
-  | 'glow'
-  | 'flash'
-  | 'shake'
-  | 'slide-in'
-  | 'slide-out'
-  | 'fade-in'
-  | 'fade-out'
-  | 'particle-flow'
-  | 'increment'
-  | 'decrement'
-  | 'bar-change';
-
-export interface TransitionDefinition {
-  /** Condition: which state path to watch */
-  watch: string;
-  /** Condition type */
-  condition: 'changed' | 'increased' | 'decreased' | 'added' | 'removed';
-  /** Animation to trigger */
-  animate: AnimationType;
-  /** Target element (CSS selector or element ID) */
-  target?: string;
-  /** Duration in ms */
-  duration?: number;
-  /** Additional params */
-  params?: Record<string, unknown>;
-}
-
-export interface ActiveAnimation {
-  id: string;
-  type: AnimationType;
-  target: string;
-  startTime: number;
-  duration: number;
-  params?: Record<string, unknown>;
-}
-
-// =============================================================================
-// Replay Types
-// =============================================================================
-
-export interface ReplayControls {
-  /** Current playback state */
-  state: 'playing' | 'paused' | 'stopped';
-  /** Playback speed multiplier */
-  speed: number;
-  /** Current replay time (event time, not wall time) */
-  currentTime: number;
-  /** Start of replay range */
-  startTime: number;
-  /** End of replay range */
-  endTime: number;
-  /** Control methods */
-  play: () => void;
-  pause: () => void;
-  stop: () => void;
-  seek: (time: number) => void;
-  setSpeed: (speed: number) => void;
-}
-
-// =============================================================================
-// Pipeline View Specific Types (Case Study 1)
-// =============================================================================
-
-export interface PipelineStage {
-  id: string;
-  label: string;
-  lastEventTime: number | null;
-  isActive: boolean;
-  count?: number;
-}
-
-export interface PipelineRepoState {
-  path: string;
-  lastEventTime: number;
-  lastEventType: string;
-}
-
-export interface PipelineState {
-  stages: Record<string, PipelineStage>;
-  repos: Map<string, PipelineRepoState>;
-  totalEvents: number;
-}
-
-export type PipelineEventType =
-  | 'FS_CHANGE'
-  | 'WATCH_DETECTED'
-  | 'CACHE_REBUILD'
-  | 'CACHE_HIT'
-  | 'EVENT_BROADCAST';
-
-export interface PipelineEvent extends StateEvent {
-  type: PipelineEventType;
-  payload: {
-    repo?: string;
-    stage?: string;
-    slice?: string;
-    eventType?: string;
-  };
-}
-
-// =============================================================================
-// Activity View Specific Types (Case Study 2)
-// =============================================================================
-
-export interface RoomState {
-  id: string;
-  userCount: number;
-  users: Set<string>;
-}
-
-export interface ActivityState {
-  rooms: Map<string, RoomState>;
-  totalUsers: number;
-  syncRatePerMinute: number;
-  recentSyncs: number[];
-}
-
-export type ActivityEventType =
-  | 'ROOM_JOIN'
-  | 'ROOM_LEAVE'
-  | 'SYNC_BROADCAST';
-
-export interface ActivityEvent extends StateEvent {
-  type: ActivityEventType;
-  payload: {
-    roomId?: string;
-    userId?: string;
-    userLogin?: string;
-    syncType?: string;
-  };
-}
-
-// =============================================================================
-// Quota View Specific Types (Case Study 3)
-// =============================================================================
-
-export interface UserQuotaState {
-  userId: number;
-  userLogin: string;
-  remaining: number;
-  limit: number;
-  resetTime: number;
-  callsThisHour: number;
-  cacheHits: number;
-  byOperation: Map<string, { total: number; apiCalls: number }>;
-  byRepo: Map<string, { total: number; apiCalls: number }>;
-}
-
-export interface QuotaDistributionState {
-  users: Map<number, UserQuotaState>;
-  serverRemaining: number;
-  serverResetTime: number;
-}
-
-export type QuotaEventType = 'GITHUB_REQUEST';
-
-export interface QuotaEvent extends StateEvent {
-  type: QuotaEventType;
-  payload: {
-    userId?: number;
-    userLogin?: string;
-    tokenType: 'user' | 'server';
-    operation: string;
-    repoOwner?: string;
-    repoName?: string;
-    cacheHit: boolean;
-    cacheTier?: string;
-    ratelimitRemaining?: number;
-    ratelimitLimit?: number;
-    ratelimitReset?: number;
-  };
-}
-
-// =============================================================================
-// View Definition (Schema)
-// =============================================================================
-
-export interface StateViewDefinition<TState, TEvent extends StateEvent> {
-  id: string;
-  name: string;
-  description?: string;
-
-  /** Initial state */
-  initialState: TState;
-
-  /** Reducer function or reference */
-  reducer: StateReducer<TState, TEvent>;
-
-  /** Transition definitions for animations */
-  transitions?: TransitionDefinition[];
-}

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

@@ -1,205 +0,0 @@
-/**
- * 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/contexts/GraphEditContext.tsx

@@ -1,27 +0,0 @@
-import React, { createContext, useContext } from 'react';
-
-export interface GraphEditContextValue {
-  /** Called when a node resize operation completes */
-  onNodeResizeEnd?: (nodeId: string, dimensions: { width: number; height: number }) => void;
-  /** Called when node text is edited (for text and group nodes) */
-  onNodeTextChange?: (nodeId: string, text: string) => void;
-  /** Called to toggle node hidden state (Cmd/Ctrl+click) */
-  onToggleNodeHidden?: (nodeId: string) => void;
-  /** Called to hide all nodes not directly connected to the given node (Cmd/Ctrl+Shift+click) */
-  onHideUnconnectedNodes?: (nodeId: string) => void;
-}
-
-const GraphEditContext = createContext<GraphEditContextValue>({});
-
-export const GraphEditProvider: React.FC<{
-  children: React.ReactNode;
-  value: GraphEditContextValue;
-}> = ({ children, value }) => {
-  return (
-    <GraphEditContext.Provider value={value}>
-      {children}
-    </GraphEditContext.Provider>
-  );
-};
-
-export const useGraphEdit = () => useContext(GraphEditContext);

package/src/contexts/TooltipPortalContext.ts

@@ -1,8 +0,0 @@
-import { createContext } from 'react';
-
-/**
- * Context for providing a portal target for tooltips.
- * This allows tooltips to be rendered within the graph container
- * instead of document.body, so they hide properly when tabs switch.
- */
-export const TooltipPortalContext = createContext<HTMLElement | null>(null);