@butlerw/vellum 0.1.0

package/src/tui/context/OverflowContext.tsx

@@ -0,0 +1,213 @@
+/**
+ * Overflow Context
+ *
+ * Tracks which components are currently overflowing their containers.
+ * This enables smart truncation and "Show More" functionality.
+ *
+ * Ported from Gemini CLI for Vellum TUI.
+ *
+ * @module tui/context/OverflowContext
+ */
+
+import React, {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * State tracking which component IDs are currently overflowing
+ */
+export interface OverflowState {
+  /** Set of component IDs that are currently overflowing */
+  readonly overflowingIds: ReadonlySet<string>;
+}
+
+/**
+ * Context value providing overflow state and management functions
+ */
+export interface OverflowContextValue {
+  /** Current overflow state */
+  readonly state: OverflowState;
+  /**
+   * Register a component as overflowing
+   * @param id - Unique identifier for the component
+   */
+  readonly registerOverflow: (id: string) => void;
+  /**
+   * Unregister a component from the overflow set
+   * @param id - Unique identifier for the component
+   */
+  readonly unregisterOverflow: (id: string) => void;
+  /**
+   * Check if a specific component is overflowing
+   * @param id - Unique identifier for the component
+   * @returns true if the component is currently overflowing
+   */
+  readonly isOverflowing: (id: string) => boolean;
+}
+
+/**
+ * Props for the OverflowProvider component
+ */
+export interface OverflowProviderProps {
+  /** Children to render within the overflow context */
+  readonly children: ReactNode;
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+/**
+ * Initial overflow state
+ */
+const initialState: OverflowState = {
+  overflowingIds: new Set<string>(),
+};
+
+/**
+ * React context for overflow state management
+ */
+export const OverflowContext = createContext<OverflowContextValue | null>(null);
+
+// Set display name for debugging
+OverflowContext.displayName = "OverflowContext";
+
+// =============================================================================
+// Provider Component
+// =============================================================================
+
+/**
+ * OverflowProvider manages tracking of overflowing components.
+ *
+ * Components can register themselves as overflowing when their content
+ * exceeds their container bounds, enabling parent components to respond
+ * appropriately (e.g., showing truncation indicators or "Show More" buttons).
+ *
+ * @example
+ * ```tsx
+ * <OverflowProvider>
+ *   <App />
+ * </OverflowProvider>
+ *
+ * // In a child component:
+ * const { registerOverflow, unregisterOverflow, isOverflowing } = useOverflow();
+ *
+ * useEffect(() => {
+ *   if (contentHeight > containerHeight) {
+ *     registerOverflow('my-component-id');
+ *   } else {
+ *     unregisterOverflow('my-component-id');
+ *   }
+ * }, [contentHeight, containerHeight]);
+ * ```
+ */
+export function OverflowProvider({ children }: OverflowProviderProps): React.JSX.Element {
+  const [overflowingIds, setOverflowingIds] = useState<ReadonlySet<string>>(
+    initialState.overflowingIds
+  );
+
+  /**
+   * Register a component as overflowing
+   */
+  const registerOverflow = useCallback((id: string) => {
+    setOverflowingIds((prev) => {
+      if (prev.has(id)) {
+        return prev;
+      }
+      const next = new Set(prev);
+      next.add(id);
+      return next;
+    });
+  }, []);
+
+  /**
+   * Unregister a component from the overflow set
+   */
+  const unregisterOverflow = useCallback((id: string) => {
+    setOverflowingIds((prev) => {
+      if (!prev.has(id)) {
+        return prev;
+      }
+      const next = new Set(prev);
+      next.delete(id);
+      return next;
+    });
+  }, []);
+
+  /**
+   * Check if a specific component is overflowing
+   */
+  const isOverflowing = useCallback(
+    (id: string): boolean => {
+      return overflowingIds.has(id);
+    },
+    [overflowingIds]
+  );
+
+  /**
+   * Memoized context value to prevent unnecessary re-renders
+   */
+  const contextValue = useMemo<OverflowContextValue>(
+    () => ({
+      state: { overflowingIds },
+      registerOverflow,
+      unregisterOverflow,
+      isOverflowing,
+    }),
+    [overflowingIds, registerOverflow, unregisterOverflow, isOverflowing]
+  );
+
+  return <OverflowContext.Provider value={contextValue}>{children}</OverflowContext.Provider>;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook to access the overflow context.
+ *
+ * @returns The overflow context value
+ * @throws Error if used outside of an OverflowProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { registerOverflow, isOverflowing } = useOverflow();
+ *
+ *   if (isOverflowing('my-id')) {
+ *     return <Text>Content is overflowing!</Text>;
+ *   }
+ *
+ *   return <Text>Content fits</Text>;
+ * }
+ * ```
+ */
+export function useOverflow(): OverflowContextValue {
+  const context = useContext(OverflowContext);
+
+  if (context === null) {
+    throw new Error("useOverflow must be used within an OverflowProvider");
+  }
+
+  return context;
+}
+
+/**
+ * Optional hook that returns null instead of throwing when used outside provider.
+ * Useful for components that may be used with or without overflow tracking.
+ *
+ * @returns The overflow context value or null if not within a provider
+ */
+export function useOverflowOptional(): OverflowContextValue | null {
+  return useContext(OverflowContext);
+}

package/src/tui/context/RateLimitContext.tsx

@@ -0,0 +1,108 @@
+/**
+ * Rate Limit Context
+ *
+ * Provides rate limiting state and notifications for the TUI.
+ *
+ * @module tui/context/RateLimitContext
+ */
+
+import type { EventBus, RateLimiterConfig } from "@vellum/core";
+import type { JSX } from "react";
+import { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from "react";
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface RateLimitState {
+  /** Whether rate limiting is currently active */
+  isRateLimited: boolean;
+  /** Current retry delay in milliseconds */
+  retryAfterMs?: number;
+  /** Number of retries performed */
+  retryCount: number;
+  /** Last rate limit error message */
+  lastError?: string;
+}
+
+export interface RateLimitContextValue {
+  /** Current rate limit state */
+  state: RateLimitState;
+  /** Set rate limited state */
+  setRateLimited: (limited: boolean, retryAfterMs?: number) => void;
+  /** Increment retry count */
+  incrementRetry: () => void;
+  /** Reset rate limit state */
+  reset: () => void;
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const defaultState: RateLimitState = {
+  isRateLimited: false,
+  retryCount: 0,
+};
+
+const RateLimitContext = createContext<RateLimitContextValue | null>(null);
+
+// =============================================================================
+// Provider
+// =============================================================================
+
+export interface RateLimitProviderProps {
+  children: ReactNode;
+  config?: RateLimiterConfig;
+  eventBus?: EventBus;
+}
+
+export function RateLimitProvider({
+  children,
+  config: _config,
+  eventBus: _eventBus,
+}: RateLimitProviderProps): JSX.Element {
+  const [state, setState] = useState<RateLimitState>(defaultState);
+
+  const setRateLimited = useCallback((limited: boolean, retryAfterMs?: number) => {
+    setState((prev) => ({
+      ...prev,
+      isRateLimited: limited,
+      retryAfterMs: limited ? retryAfterMs : undefined,
+    }));
+  }, []);
+
+  const incrementRetry = useCallback(() => {
+    setState((prev) => ({
+      ...prev,
+      retryCount: prev.retryCount + 1,
+    }));
+  }, []);
+
+  const reset = useCallback(() => {
+    setState(defaultState);
+  }, []);
+
+  const value = useMemo<RateLimitContextValue>(
+    () => ({
+      state,
+      setRateLimited,
+      incrementRetry,
+      reset,
+    }),
+    [state, setRateLimited, incrementRetry, reset]
+  );
+
+  return <RateLimitContext.Provider value={value}>{children}</RateLimitContext.Provider>;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useRateLimit(): RateLimitContextValue {
+  const context = useContext(RateLimitContext);
+  if (!context) {
+    throw new Error("useRateLimit must be used within a RateLimitProvider");
+  }
+  return context;
+}

package/src/tui/context/ResilienceContext.tsx

@@ -0,0 +1,275 @@
+/**
+ * Resilience Context
+ *
+ * React context for subscribing to resilience events (rate limiting, retry)
+ * and displaying feedback in the TUI.
+ *
+ * @module tui/context/ResilienceContext
+ */
+
+import {
+  getResilienceEventBus,
+  type RateLimitThrottleEvent,
+  type ResilienceEventBus,
+  type RetryAttemptEvent,
+} from "@vellum/core";
+import React, {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Active resilience status to display in UI
+ */
+export interface ResilienceStatus {
+  /** Type of resilience event */
+  readonly type: "rate-limit" | "retry" | "idle";
+  /** Status message to display */
+  readonly message: string;
+  /** Wait time in seconds (if applicable) */
+  readonly waitSeconds?: number;
+  /** Current attempt (for retry) */
+  readonly attempt?: number;
+  /** Max attempts (for retry) */
+  readonly maxAttempts?: number;
+  /** Timestamp when status was set */
+  readonly timestamp: number;
+}
+
+/**
+ * Resilience context state
+ */
+export interface ResilienceContextState {
+  /** Current resilience status */
+  readonly status: ResilienceStatus;
+  /** Whether feedback is enabled */
+  readonly feedbackEnabled: boolean;
+  /** Enable/disable feedback */
+  readonly setFeedbackEnabled: (enabled: boolean) => void;
+  /** Clear current status */
+  readonly clearStatus: () => void;
+  /** Event bus instance (for advanced usage) */
+  readonly eventBus: ResilienceEventBus;
+}
+
+/**
+ * Props for ResilienceProvider
+ */
+export interface ResilienceProviderProps {
+  /** Child components */
+  readonly children: ReactNode;
+  /** Whether feedback is initially enabled (default: true) */
+  readonly initialEnabled?: boolean;
+  /** Custom event bus instance (optional, uses global by default) */
+  readonly eventBus?: ResilienceEventBus;
+  /** Auto-clear timeout in milliseconds (default: 5000) */
+  readonly autoClearMs?: number;
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const ResilienceContext = createContext<ResilienceContextState | null>(null);
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default idle status */
+const IDLE_STATUS: ResilienceStatus = {
+  type: "idle",
+  message: "",
+  timestamp: 0,
+};
+
+/** Default auto-clear timeout */
+const DEFAULT_AUTO_CLEAR_MS = 5000;
+
+// =============================================================================
+// Provider Component
+// =============================================================================
+
+/**
+ * Resilience provider component.
+ *
+ * Subscribes to resilience events and provides status to child components.
+ *
+ * @example
+ * ```tsx
+ * <ResilienceProvider>
+ *   <App />
+ * </ResilienceProvider>
+ * ```
+ */
+export function ResilienceProvider({
+  children,
+  initialEnabled = true,
+  eventBus: customEventBus,
+  autoClearMs = DEFAULT_AUTO_CLEAR_MS,
+}: ResilienceProviderProps): React.JSX.Element {
+  const [status, setStatus] = useState<ResilienceStatus>(IDLE_STATUS);
+  const [feedbackEnabled, setFeedbackEnabled] = useState(initialEnabled);
+
+  // Get event bus (custom or global)
+  const eventBus = useMemo(() => customEventBus ?? getResilienceEventBus(), [customEventBus]);
+
+  // Clear status function
+  const clearStatus = useCallback(() => {
+    setStatus(IDLE_STATUS);
+  }, []);
+
+  // Auto-clear timer
+  useEffect(() => {
+    if (status.type === "idle" || !feedbackEnabled) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      setStatus(IDLE_STATUS);
+    }, autoClearMs);
+
+    return () => clearTimeout(timer);
+  }, [status, feedbackEnabled, autoClearMs]);
+
+  // Subscribe to rate limit events
+  useEffect(() => {
+    if (!feedbackEnabled) {
+      return;
+    }
+
+    const unsubThrottle = eventBus.on("rateLimitThrottle", (event: RateLimitThrottleEvent) => {
+      const waitSeconds = Math.ceil(event.waitTimeMs / 1000);
+      setStatus({
+        type: "rate-limit",
+        message: `Rate limited, waiting ${waitSeconds}s...`,
+        waitSeconds,
+        timestamp: event.timestamp,
+      });
+    });
+
+    const unsubExceeded = eventBus.on("rateLimitExceeded", (event) => {
+      const waitSeconds = Math.ceil(event.waitTimeMs / 1000);
+      const reason = event.reason === "max_wait" ? "max wait exceeded" : "limit exceeded";
+      setStatus({
+        type: "rate-limit",
+        message: `Rate limit ${reason} (${waitSeconds}s)`,
+        waitSeconds,
+        timestamp: event.timestamp,
+      });
+    });
+
+    return () => {
+      unsubThrottle();
+      unsubExceeded();
+    };
+  }, [eventBus, feedbackEnabled]);
+
+  // Subscribe to retry events
+  useEffect(() => {
+    if (!feedbackEnabled) {
+      return;
+    }
+
+    const unsubAttempt = eventBus.on("retryAttempt", (event: RetryAttemptEvent) => {
+      const waitSeconds = Math.ceil(event.delayMs / 1000);
+      setStatus({
+        type: "retry",
+        message: `Retry ${event.attempt}/${event.maxAttempts}, waiting ${waitSeconds}s...`,
+        waitSeconds,
+        attempt: event.attempt,
+        maxAttempts: event.maxAttempts,
+        timestamp: event.timestamp,
+      });
+    });
+
+    const unsubCompleted = eventBus.on("retryCompleted", (event) => {
+      if (event.success) {
+        // Clear on success
+        setStatus(IDLE_STATUS);
+      } else {
+        // Show failure briefly
+        setStatus({
+          type: "retry",
+          message: `Retry failed after ${event.totalAttempts} attempts`,
+          timestamp: event.timestamp,
+        });
+      }
+    });
+
+    return () => {
+      unsubAttempt();
+      unsubCompleted();
+    };
+  }, [eventBus, feedbackEnabled]);
+
+  // Build context value
+  const value = useMemo<ResilienceContextState>(
+    () => ({
+      status,
+      feedbackEnabled,
+      setFeedbackEnabled,
+      clearStatus,
+      eventBus,
+    }),
+    [status, feedbackEnabled, clearStatus, eventBus]
+  );
+
+  return <ResilienceContext.Provider value={value}>{children}</ResilienceContext.Provider>;
+}
+
+// =============================================================================
+// Hooks
+// =============================================================================
+
+/**
+ * Hook to access resilience context.
+ *
+ * @throws Error if used outside ResilienceProvider
+ * @returns ResilienceContextState
+ */
+export function useResilience(): ResilienceContextState {
+  const context = useContext(ResilienceContext);
+  if (!context) {
+    throw new Error("useResilience must be used within a ResilienceProvider");
+  }
+  return context;
+}
+
+/**
+ * Hook to access resilience context optionally.
+ *
+ * @returns ResilienceContextState or null if outside provider
+ */
+export function useResilienceOptional(): ResilienceContextState | null {
+  return useContext(ResilienceContext);
+}
+
+/**
+ * Hook to get current resilience status.
+ *
+ * @returns Current ResilienceStatus
+ */
+export function useResilienceStatus(): ResilienceStatus {
+  const context = useResilience();
+  return context.status;
+}
+
+/**
+ * Hook to check if any resilience event is active.
+ *
+ * @returns true if rate limiting or retry is in progress
+ */
+export function useIsResilienceActive(): boolean {
+  const context = useResilienceOptional();
+  return context?.status.type !== "idle" && context?.status.type !== undefined;
+}