@butlerw/vellum 0.1.0

package/src/tui/components/common/EnhancedLoadingIndicator.tsx

@@ -0,0 +1,305 @@
+/**
+ * Enhanced Loading Indicator Component
+ *
+ * Advanced loading indicator with elapsed time, cancel hints,
+ * and configurable show/hide delays. Inspired by Gemini CLI.
+ *
+ * @module tui/components/common/EnhancedLoadingIndicator
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useTheme } from "../../theme/index.js";
+import { Spinner } from "./Spinner.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the EnhancedLoadingIndicator component.
+ */
+export interface EnhancedLoadingIndicatorProps {
+  /** Whether the loading indicator is active */
+  readonly isLoading: boolean;
+  /** Label to display alongside the spinner */
+  readonly label?: string;
+  /** Whether to show elapsed time (default: true) */
+  readonly showElapsedTime?: boolean;
+  /** Whether to show cancel hint (default: true) */
+  readonly showCancelHint?: boolean;
+  /** Custom cancel hint text */
+  readonly cancelHint?: string;
+  /** Delay before showing the indicator in ms (default: 0) */
+  readonly showDelay?: number;
+  /** Delay before hiding the indicator in ms (default: 0) */
+  readonly hideDelay?: number;
+  /** Spinner animation frames */
+  readonly spinnerFrames?: readonly string[];
+  /** Spinner color */
+  readonly spinnerColor?: string;
+  /** Content to display on the right side */
+  readonly rightContent?: React.ReactNode;
+  /** Whether the indicator is in a narrow layout */
+  readonly narrow?: boolean;
+}
+
+// =============================================================================
+// Hooks
+// =============================================================================
+
+/**
+ * Hook to manage elapsed time with proper reset behavior.
+ *
+ * @param isActive - Whether the timer should be running
+ * @param resetKey - Key that triggers timer reset when changed
+ * @returns Elapsed time in seconds
+ */
+export function useElapsedTime(isActive: boolean, resetKey?: unknown): number {
+  const [elapsedTime, setElapsedTime] = useState(0);
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const prevResetKeyRef = useRef(resetKey);
+  const prevIsActiveRef = useRef(isActive);
+
+  useEffect(() => {
+    let shouldResetTime = false;
+
+    // Reset on key change
+    if (prevResetKeyRef.current !== resetKey) {
+      shouldResetTime = true;
+      prevResetKeyRef.current = resetKey;
+    }
+
+    // Reset on transition from inactive to active
+    if (!prevIsActiveRef.current && isActive) {
+      shouldResetTime = true;
+    }
+
+    if (shouldResetTime) {
+      setElapsedTime(0);
+    }
+    prevIsActiveRef.current = isActive;
+
+    // Manage interval
+    if (isActive) {
+      // Clear previous interval
+      if (timerRef.current) {
+        clearInterval(timerRef.current);
+      }
+      timerRef.current = setInterval(() => {
+        setElapsedTime((prev) => prev + 1);
+      }, 1000);
+    } else {
+      if (timerRef.current) {
+        clearInterval(timerRef.current);
+        timerRef.current = null;
+      }
+    }
+
+    return () => {
+      if (timerRef.current) {
+        clearInterval(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [isActive, resetKey]);
+
+  return elapsedTime;
+}
+
+/**
+ * Hook to manage show/hide delays for smooth transitions.
+ *
+ * @param isActive - Whether the element should be shown
+ * @param showDelay - Delay before showing in ms
+ * @param hideDelay - Delay before hiding in ms
+ * @returns Whether the element should be visible
+ */
+export function useDelayedVisibility(isActive: boolean, showDelay = 0, hideDelay = 0): boolean {
+  const [isVisible, setIsVisible] = useState(isActive && showDelay === 0);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    // Clear any pending timeout
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    if (isActive) {
+      if (showDelay > 0) {
+        timeoutRef.current = setTimeout(() => {
+          setIsVisible(true);
+        }, showDelay);
+      } else {
+        setIsVisible(true);
+      }
+    } else {
+      if (hideDelay > 0) {
+        timeoutRef.current = setTimeout(() => {
+          setIsVisible(false);
+        }, hideDelay);
+      } else {
+        setIsVisible(false);
+      }
+    }
+
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, [isActive, showDelay, hideDelay]);
+
+  return isVisible;
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Format duration in a human-readable way.
+ *
+ * @param seconds - Duration in seconds
+ * @returns Formatted duration string
+ */
+export function formatDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+
+  if (minutes < 60) {
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+
+  return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * EnhancedLoadingIndicator - Feature-rich loading indicator.
+ *
+ * Features:
+ * - Customizable spinner with label
+ * - Elapsed time display (auto-formatted)
+ * - Cancel hint with configurable text
+ * - Show/hide delays for smooth transitions
+ * - Responsive narrow layout support
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <EnhancedLoadingIndicator isLoading={true} label="Processing..." />
+ *
+ * // With all features
+ * <EnhancedLoadingIndicator
+ *   isLoading={isProcessing}
+ *   label="Generating response..."
+ *   showElapsedTime
+ *   showCancelHint
+ *   cancelHint="Press Esc to cancel"
+ *   showDelay={200}
+ * />
+ *
+ * // Narrow layout
+ * <EnhancedLoadingIndicator
+ *   isLoading={true}
+ *   label="Working..."
+ *   narrow
+ * />
+ * ```
+ */
+export function EnhancedLoadingIndicator({
+  isLoading,
+  label = "Loading...",
+  showElapsedTime = true,
+  showCancelHint = true,
+  cancelHint = "Esc to cancel",
+  showDelay = 0,
+  hideDelay = 0,
+  spinnerFrames,
+  spinnerColor,
+  rightContent,
+  narrow = false,
+}: EnhancedLoadingIndicatorProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+
+  // Manage visibility with delays
+  const isVisible = useDelayedVisibility(isLoading, showDelay, hideDelay);
+
+  // Track elapsed time
+  const elapsedTime = useElapsedTime(isLoading);
+
+  // Build the time and cancel hint text
+  const metaContent = useCallback(() => {
+    const parts: string[] = [];
+
+    if (showCancelHint && cancelHint) {
+      parts.push(cancelHint);
+    }
+
+    if (showElapsedTime) {
+      parts.push(`⏱ ${formatDuration(elapsedTime)}`);
+    }
+
+    return parts.length > 0 ? `(${parts.join(", ")})` : null;
+  }, [showCancelHint, cancelHint, showElapsedTime, elapsedTime]);
+
+  if (!isVisible) {
+    return null;
+  }
+
+  const meta = metaContent();
+
+  if (narrow) {
+    // Narrow layout: stack vertically
+    return (
+      <Box flexDirection="column">
+        <Box>
+          <Spinner color={spinnerColor ?? theme.colors.info} frames={spinnerFrames} />
+          <Text color={theme.colors.info}> {label}</Text>
+        </Box>
+        {meta && (
+          <Box>
+            <Text dimColor>{meta}</Text>
+          </Box>
+        )}
+        {rightContent && <Box>{rightContent}</Box>}
+      </Box>
+    );
+  }
+
+  // Normal layout: horizontal
+  return (
+    <Box flexDirection="row" alignItems="center">
+      <Spinner color={spinnerColor ?? theme.colors.info} frames={spinnerFrames} />
+      <Text color={theme.colors.info}> {label}</Text>
+      {meta && (
+        <>
+          <Text> </Text>
+          <Text dimColor>{meta}</Text>
+        </>
+      )}
+      {rightContent && (
+        <>
+          <Box flexGrow={1} />
+          {rightContent}
+        </>
+      )}
+    </Box>
+  );
+}
+
+export default EnhancedLoadingIndicator;

package/src/tui/components/common/ErrorBoundary.tsx

@@ -0,0 +1,140 @@
+/**
+ * ErrorBoundary Component (Chain 20)
+ *
+ * React error boundary for graceful error handling in the TUI.
+ * Catches errors in child components and displays a fallback UI.
+ *
+ * @module tui/components/common/ErrorBoundary
+ */
+
+import { Box, Text } from "ink";
+import { Component, type ReactNode } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the ErrorBoundary component.
+ */
+export interface ErrorBoundaryProps {
+  /** Child components to render */
+  readonly children: ReactNode;
+  /** Custom fallback UI to render on error */
+  readonly fallback?: ReactNode;
+  /** Callback when an error is caught */
+  readonly onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+  /** Whether to show error details */
+  readonly showDetails?: boolean;
+}
+
+/**
+ * Internal state for the ErrorBoundary.
+ */
+interface ErrorBoundaryState {
+  /** Whether an error has been caught */
+  hasError: boolean;
+  /** The caught error, if any */
+  error: Error | null;
+}
+
+// =============================================================================
+// ErrorBoundary Component
+// =============================================================================
+
+/**
+ * ErrorBoundary - Catches JavaScript errors in child components.
+ *
+ * Features:
+ * - Catches errors in render, lifecycle methods, and constructors
+ * - Displays customizable fallback UI
+ * - Supports error callback for logging
+ * - Provides reset functionality
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary onError={(err) => logError(err)}>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ *
+ * // With custom fallback
+ * <ErrorBoundary fallback={<Text>Something went wrong</Text>}>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = {
+    hasError: false,
+    error: null,
+  };
+
+  /**
+   * Update state when an error is caught.
+   * Called during the "render" phase.
+   */
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return {
+      hasError: true,
+      error,
+    };
+  }
+
+  /**
+   * Log error information.
+   * Called during the "commit" phase.
+   */
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    this.props.onError?.(error, errorInfo);
+  }
+
+  /**
+   * Reset the error state.
+   * Can be called externally via ref or exposed through context.
+   */
+  reset = (): void => {
+    this.setState({
+      hasError: false,
+      error: null,
+    });
+  };
+
+  render(): ReactNode {
+    const { hasError, error } = this.state;
+    const { children, fallback, showDetails = true } = this.props;
+
+    if (hasError) {
+      // Use custom fallback if provided
+      if (fallback) {
+        return fallback;
+      }
+
+      // Default error UI
+      return (
+        <Box flexDirection="column" padding={1} borderStyle="round" borderColor="red">
+          <Text color="red" bold>
+            ! Something went wrong
+          </Text>
+          {showDetails && error && (
+            <Box marginTop={1}>
+              <Text color="gray" wrap="wrap">
+                {error.message}
+              </Text>
+            </Box>
+          )}
+          <Box marginTop={1}>
+            <Text color="cyan">Press 'r' to retry or Ctrl+C to exit</Text>
+          </Box>
+        </Box>
+      );
+    }
+
+    return children;
+  }
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export default ErrorBoundary;

package/src/tui/components/common/GradientText.tsx

@@ -0,0 +1,224 @@
+/**
+ * GradientText Component
+ *
+ * Terminal-compatible gradient text implementation that applies
+ * color gradients by coloring each character segment individually.
+ *
+ * Uses theme brand colors by default for consistent Vellum styling.
+ *
+ * @module tui/components/common/GradientText
+ */
+
+import { Text } from "ink";
+import type React from "react";
+import { memo, useMemo } from "react";
+import { useTheme } from "../../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Gradient direction for text coloring.
+ * - horizontal: Left to right gradient across text
+ * - vertical: Top to bottom (simulated by alternating chars)
+ */
+export type GradientDirection = "horizontal" | "vertical";
+
+/**
+ * Props for the GradientText component.
+ */
+export interface GradientTextProps {
+  /** The text to display with gradient coloring */
+  readonly text: string;
+  /** Array of colors to use for the gradient (min 2 colors) */
+  readonly colors?: readonly string[];
+  /** Direction of the gradient (default: 'horizontal') */
+  readonly direction?: GradientDirection;
+  /** Whether to apply bold styling */
+  readonly bold?: boolean;
+  /** Whether to apply dim styling */
+  readonly dimColor?: boolean;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Split text into segments for gradient coloring.
+ * Each segment gets assigned a color from the gradient.
+ *
+ * @param text - The text to split
+ * @param colorCount - Number of colors in the gradient
+ * @returns Array of text segments
+ */
+function splitIntoSegments(text: string, colorCount: number): string[] {
+  if (!text || colorCount <= 0) {
+    return [text];
+  }
+
+  // For very short text, just assign one color per character
+  if (text.length <= colorCount) {
+    return [...text];
+  }
+
+  // Calculate segment size (distribute chars evenly across colors)
+  const baseSegmentSize = Math.floor(text.length / colorCount);
+  const remainder = text.length % colorCount;
+
+  const segments: string[] = [];
+  let currentIndex = 0;
+
+  for (let i = 0; i < colorCount; i++) {
+    // Add 1 extra char to first 'remainder' segments to distribute evenly
+    const segmentSize = baseSegmentSize + (i < remainder ? 1 : 0);
+    const segment = text.slice(currentIndex, currentIndex + segmentSize);
+    if (segment) {
+      segments.push(segment);
+    }
+    currentIndex += segmentSize;
+  }
+
+  return segments;
+}
+
+/**
+ * Get a subset of colors for vertical gradient simulation.
+ * Alternates between first and last colors.
+ *
+ * @param colors - Full color array
+ * @returns Colors for vertical effect
+ */
+function getVerticalColors(colors: readonly string[]): readonly string[] {
+  if (colors.length < 2) {
+    return colors;
+  }
+  // For vertical, alternate between start and end colors
+  return [colors[0]!, colors[colors.length - 1]!];
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * GradientText renders text with a color gradient effect.
+ *
+ * Terminal gradients work by coloring each character/segment individually.
+ * This component splits the text into segments and applies colors from
+ * the provided gradient array (or theme brand colors by default).
+ *
+ * @example
+ * ```tsx
+ * // Using theme brand colors (default)
+ * <GradientText text="VELLUM" />
+ *
+ * // Custom colors
+ * <GradientText
+ *   text="Hello World"
+ *   colors={['#ff0000', '#00ff00', '#0000ff']}
+ * />
+ *
+ * // Vertical gradient (alternating)
+ * <GradientText text="Status" direction="vertical" />
+ * ```
+ */
+function GradientTextImpl({
+  text,
+  colors,
+  direction = "horizontal",
+  bold = false,
+  dimColor = false,
+}: GradientTextProps): React.ReactElement {
+  const { theme } = useTheme();
+
+  // Use theme brand colors as default gradient
+  const gradientColors = useMemo((): readonly string[] => {
+    if (colors && colors.length >= 2) {
+      return colors;
+    }
+
+    // Default: theme brand gradient (goldenrod → peru → sienna)
+    return [
+      theme.brand.highlight, // Gold #FFD700
+      theme.brand.primary, // Goldenrod #DAA520
+      theme.brand.secondary, // Peru #CD853F
+      theme.brand.mid, // Sienna #A0522D
+    ] as const;
+  }, [colors, theme.brand]);
+
+  // Apply direction transformation
+  const effectiveColors = useMemo(() => {
+    return direction === "vertical" ? getVerticalColors(gradientColors) : gradientColors;
+  }, [direction, gradientColors]);
+
+  // Split text into gradient segments
+  const segments = useMemo(() => {
+    return splitIntoSegments(text, effectiveColors.length);
+  }, [text, effectiveColors.length]);
+
+  // Handle empty text
+  if (!text) {
+    return <Text>{""}</Text>;
+  }
+
+  // Render gradient segments
+  return (
+    <Text>
+      {segments.map((segment, index) => {
+        const color = effectiveColors[index % effectiveColors.length];
+        return (
+          <Text key={`${index}-${segment}`} color={color} bold={bold} dimColor={dimColor}>
+            {segment}
+          </Text>
+        );
+      })}
+    </Text>
+  );
+}
+
+/**
+ * Memoized GradientText component.
+ * Re-renders only when props actually change.
+ */
+export const GradientText = memo(GradientTextImpl);
+
+// =============================================================================
+// Preset Gradients
+// =============================================================================
+
+/**
+ * Preset gradient configurations for common use cases.
+ * Import and spread into GradientText props.
+ */
+export const GRADIENT_PRESETS = {
+  /** Warm gold/amber gradient (default brand) */
+  brand: undefined, // Uses default theme.brand colors
+
+  /** Success/positive gradient (green tones) */
+  success: ["#10b981", "#34d399", "#6ee7b7"] as const,
+
+  /** Warning gradient (amber/orange tones) */
+  warning: ["#f59e0b", "#fbbf24", "#fcd34d"] as const,
+
+  /** Error gradient (red tones) */
+  error: ["#ef4444", "#f87171", "#fca5a5"] as const,
+
+  /** Info gradient (blue tones) */
+  info: ["#3b82f6", "#60a5fa", "#93c5fd"] as const,
+
+  /** Purple/violet gradient (primary UI) */
+  primary: ["#7c3aed", "#8b5cf6", "#a78bfa"] as const,
+
+  /** Sunset gradient (warm spectrum) */
+  sunset: ["#f59e0b", "#ef4444", "#ec4899"] as const,
+
+  /** Ocean gradient (cool spectrum) */
+  ocean: ["#0ea5e9", "#3b82f6", "#6366f1"] as const,
+} as const;
+
+/**
+ * Type for preset gradient names.
+ */
+export type GradientPreset = keyof typeof GRADIENT_PRESETS;