@butlerw/vellum 0.1.0

package/src/tui/components/Messages/__tests__/StreamingText.test.tsx

@@ -0,0 +1,215 @@
+/**
+ * StreamingText Component Tests
+ *
+ * Tests for the StreamingText component which displays text with an animated
+ * blinking cursor while streaming.
+ *
+ * @module tui/components/Messages/__tests__/StreamingText.test
+ */
+
+import { render } from "ink-testing-library";
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AnimationProvider } from "../../../context/AnimationContext.js";
+import { StreamingText } from "../StreamingText.js";
+
+// =============================================================================
+// Test Setup
+// =============================================================================
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("StreamingText", () => {
+  describe("rendering", () => {
+    it("renders text content", () => {
+      const { lastFrame } = render(<StreamingText content="Hello world" isStreaming={false} />);
+
+      expect(lastFrame()).toContain("Hello world");
+    });
+
+    it("renders empty content", () => {
+      const { lastFrame } = render(<StreamingText content="" isStreaming={false} />);
+
+      // Should render without cursor when not streaming
+      expect(lastFrame()).toBe("");
+    });
+  });
+
+  describe("cursor behavior", () => {
+    it("shows cursor when streaming", () => {
+      // Disable typewriter effect for immediate content display test
+      const { lastFrame } = render(
+        <StreamingText content="Typing..." isStreaming={true} typewriterEffect={false} />
+      );
+
+      expect(lastFrame()).toContain("Typing...");
+      expect(lastFrame()).toContain("▊"); // Default cursor
+    });
+
+    it("hides cursor when not streaming", () => {
+      const { lastFrame } = render(<StreamingText content="Complete" isStreaming={false} />);
+
+      expect(lastFrame()).toContain("Complete");
+      expect(lastFrame()).not.toContain("▊");
+    });
+
+    it("uses custom cursor character", () => {
+      // Disable typewriter effect for immediate content display test
+      const { lastFrame } = render(
+        <StreamingText
+          content="Custom"
+          isStreaming={true}
+          cursorChar="_"
+          typewriterEffect={false}
+        />
+      );
+
+      expect(lastFrame()).toContain("Custom");
+      expect(lastFrame()).toContain("_");
+      expect(lastFrame()).not.toContain("▊");
+    });
+
+    it("blinks cursor when animation frames advance", async () => {
+      const { lastFrame } = render(
+        <AnimationProvider tickInterval={100}>
+          <StreamingText
+            content="Blinking"
+            isStreaming={true}
+            cursorBlink={true}
+            typewriterEffect={false}
+          />
+        </AnimationProvider>
+      );
+
+      // Initially cursor is visible
+      expect(lastFrame()).toContain("▊");
+
+      // After 4 ticks (frame=4), cursor should be hidden
+      await act(async () => {
+        vi.advanceTimersByTime(400);
+      });
+      expect(lastFrame()).not.toContain("▊");
+
+      // After 4 more ticks (frame=8), cursor should be visible again
+      await act(async () => {
+        vi.advanceTimersByTime(400);
+      });
+      expect(lastFrame()).toContain("▊");
+    });
+
+    it("does not blink cursor when cursorBlink is false", () => {
+      const { lastFrame } = render(
+        <AnimationProvider tickInterval={100}>
+          <StreamingText
+            content="No blink"
+            isStreaming={true}
+            cursorBlink={false}
+            typewriterEffect={false}
+          />
+        </AnimationProvider>
+      );
+
+      // Cursor is visible
+      expect(lastFrame()).toContain("▊");
+
+      // After 500ms, cursor should still be visible (no blinking)
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(lastFrame()).toContain("▊");
+
+      // After another 500ms, still visible
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(lastFrame()).toContain("▊");
+    });
+  });
+
+  describe("onComplete callback", () => {
+    it("calls onComplete when streaming changes from true to false", () => {
+      const onComplete = vi.fn();
+
+      const { rerender } = render(
+        <StreamingText content="Streaming..." isStreaming={true} onComplete={onComplete} />
+      );
+
+      // Not called while streaming
+      expect(onComplete).not.toHaveBeenCalled();
+
+      // Update to not streaming
+      act(() => {
+        rerender(<StreamingText content="Done!" isStreaming={false} onComplete={onComplete} />);
+      });
+
+      // Now onComplete should be called
+      expect(onComplete).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not call onComplete when initially not streaming", () => {
+      const onComplete = vi.fn();
+
+      render(<StreamingText content="Not streaming" isStreaming={false} onComplete={onComplete} />);
+
+      // Should not be called on initial render when not streaming
+      expect(onComplete).not.toHaveBeenCalled();
+    });
+
+    it("does not call onComplete when streaming remains true", () => {
+      const onComplete = vi.fn();
+
+      const { rerender } = render(
+        <StreamingText content="Still streaming..." isStreaming={true} onComplete={onComplete} />
+      );
+
+      // Update content but keep streaming
+      act(() => {
+        rerender(
+          <StreamingText content="More content..." isStreaming={true} onComplete={onComplete} />
+        );
+      });
+
+      expect(onComplete).not.toHaveBeenCalled();
+    });
+
+    it("works without onComplete callback", () => {
+      const { rerender } = render(<StreamingText content="Streaming..." isStreaming={true} />);
+
+      // Should not throw when onComplete is undefined
+      expect(() => {
+        act(() => {
+          rerender(<StreamingText content="Done!" isStreaming={false} />);
+        });
+      }).not.toThrow();
+    });
+  });
+
+  describe("animation cleanup", () => {
+    it("cleans up animation interval on unmount", () => {
+      const clearIntervalSpy = vi.spyOn(global, "clearInterval");
+
+      const { unmount } = render(
+        <AnimationProvider tickInterval={100}>
+          <StreamingText content="Test" isStreaming={true} cursorBlink={true} />
+        </AnimationProvider>
+      );
+
+      act(() => {
+        unmount();
+      });
+
+      expect(clearIntervalSpy).toHaveBeenCalled();
+      clearIntervalSpy.mockRestore();
+    });
+  });
+});

package/src/tui/components/Messages/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Message Components
+ *
+ * Components for displaying messages and conversation history in the Vellum TUI.
+ */
+
+export { CodeBlock, type CodeBlockProps } from "./CodeBlock.js";
+export { DiffView, type DiffViewProps } from "./DiffView.js";
+export { MarkdownBlock, type MarkdownBlockProps, MarkdownBlockSync } from "./MarkdownBlock.js";
+export { MarkdownRenderer, type MarkdownRendererProps } from "./MarkdownRenderer.js";
+export { MessageBubble, type MessageBubbleProps } from "./MessageBubble.js";
+export { MessageList, type MessageListProps } from "./MessageList.js";
+export { StreamingText, type StreamingTextProps } from "./StreamingText.js";
+export {
+  CompactThinkingIndicator,
+  type CompactThinkingIndicatorProps,
+  ThinkingBlock,
+  type ThinkingBlockProps,
+} from "./ThinkingBlock.js";
+export {
+  SHELL_TOOL_MAX_LINES,
+  TOOL_RESULT_MAX_LINES,
+  ToolResultPreview,
+  type ToolResultPreviewProps,
+} from "./ToolResultPreview.js";

package/src/tui/components/ModeIndicator.tsx

@@ -0,0 +1,177 @@
+/**
+ * ModeIndicator Component (T043, T044)
+ *
+ * TUI component for displaying the current coding mode with visual styling.
+ * Shows mode icon, name, and optional spec phase progress.
+ *
+ * @module tui/components/ModeIndicator
+ */
+
+import type { CodingMode, SpecPhase } from "@vellum/core";
+import { SPEC_PHASE_CONFIG, SPEC_PHASES } from "@vellum/core";
+import { getIcons } from "@vellum/shared";
+import { Box, Text } from "ink";
+import type React from "react";
+import { useMemo } from "react";
+import { useTheme } from "../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the ModeIndicator component.
+ */
+export interface ModeIndicatorProps {
+  /** The current coding mode */
+  readonly mode: CodingMode;
+  /** Current spec phase (only for spec mode, 1-6) */
+  readonly specPhase?: number;
+  /** Whether to show in compact mode (icon only) */
+  readonly compact?: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Get mode icons for each coding mode.
+ * Uses centralized icon system with auto-detection.
+ */
+function getModeIcons(): Record<CodingMode, string> {
+  const icons = getIcons();
+  return {
+    vibe: icons.vibe,
+    plan: icons.plan,
+    spec: icons.spec,
+  };
+}
+
+/**
+ * Mode display names.
+ */
+const MODE_NAMES: Record<CodingMode, string> = {
+  vibe: "vibe",
+  plan: "plan",
+  spec: "spec",
+} as const;
+
+/**
+ * Mode colors mapped to theme semantic colors.
+ * - vibe: green (success) - fast, autonomous
+ * - plan: blue (info) - structured planning
+ * - spec: purple (primary) - detailed specification
+ */
+const MODE_COLOR_KEYS: Record<CodingMode, "success" | "info" | "primary"> = {
+  vibe: "success",
+  plan: "info",
+  spec: "primary",
+} as const;
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Get the color for a coding mode from the theme.
+ */
+function getModeColor(mode: CodingMode, theme: ReturnType<typeof useTheme>["theme"]): string {
+  const colorKey = MODE_COLOR_KEYS[mode];
+  return theme.colors[colorKey];
+}
+
+/**
+ * Get the phase name from phase number.
+ */
+function getPhaseName(phaseNumber: number): string {
+  const phase = SPEC_PHASES[phaseNumber - 1] as SpecPhase | undefined;
+  if (!phase) {
+    return `Phase ${phaseNumber}`;
+  }
+  return SPEC_PHASE_CONFIG[phase].name;
+}
+
+// =============================================================================
+// ModeIndicator Component
+// =============================================================================
+
+/**
+ * ModeIndicator - Displays the current coding mode with visual styling.
+ *
+ * Features:
+ * - Mode icon (using centralized icon system)
+ * - Color-coded mode name (green, blue, purple)
+ * - Spec phase progress indicator when in spec mode
+ * - Compact mode for space-constrained layouts
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ModeIndicator mode="vibe" />
+ *
+ * // With spec phase
+ * <ModeIndicator mode="spec" specPhase={3} />
+ *
+ * // Compact mode
+ * <ModeIndicator mode="plan" compact />
+ * ```
+ */
+export function ModeIndicator({
+  mode,
+  specPhase,
+  compact = false,
+}: ModeIndicatorProps): React.ReactElement {
+  const { theme } = useTheme();
+
+  // Get mode display properties
+  const modeIcons = getModeIcons();
+  const icon = modeIcons[mode];
+  const name = MODE_NAMES[mode];
+  const color = getModeColor(mode, theme);
+
+  // Build phase display for spec mode
+  const phaseDisplay = useMemo(() => {
+    if (mode !== "spec" || specPhase === undefined) {
+      return null;
+    }
+
+    const totalPhases = SPEC_PHASES.length;
+    const validPhase = Math.max(1, Math.min(specPhase, totalPhases));
+
+    if (compact) {
+      return ` (${validPhase}/${totalPhases})`;
+    }
+
+    const phaseName = getPhaseName(validPhase);
+    return ` (${validPhase}/${totalPhases}: ${phaseName})`;
+  }, [mode, specPhase, compact]);
+
+  // Compact mode: icon only with optional phase
+  if (compact) {
+    return (
+      <Box>
+        <Text color={color}>
+          {icon}
+          {phaseDisplay}
+        </Text>
+      </Box>
+    );
+  }
+
+  // Full mode: icon + name + phase
+  return (
+    <Box>
+      <Text color={color}>
+        {icon} {name}
+        {phaseDisplay}
+      </Text>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export type { CodingMode };

package/src/tui/components/ModeSelector.tsx

@@ -0,0 +1,216 @@
+/**
+ * ModeSelector Component (T045)
+ *
+ * TUI component for selecting coding modes with keyboard navigation.
+ * Renders three selectable options (vibe, plan, spec) with visual feedback.
+ *
+ * @module tui/components/ModeSelector
+ */
+
+import type { CodingMode } from "@vellum/core";
+import { BUILTIN_CODING_MODES, CODING_MODES } from "@vellum/core";
+import { getIcons } from "@vellum/shared";
+import { Box, Text, useInput } from "ink";
+import type React from "react";
+import { useCallback, useState } from "react";
+import { useTUITranslation } from "../i18n/index.js";
+import { useTheme } from "../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the ModeSelector component.
+ */
+export interface ModeSelectorProps {
+  /** The currently active mode */
+  readonly currentMode: CodingMode;
+  /** Callback when a mode is selected */
+  readonly onSelect: (mode: CodingMode) => void;
+  /** Whether the selector is focused/active */
+  readonly isActive?: boolean;
+  /** Whether to show mode descriptions */
+  readonly showDescriptions?: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Get mode icons for visual identification.
+ * Uses centralized icon system with auto-detection.
+ */
+function getModeIcons(): Record<CodingMode, string> {
+  const icons = getIcons();
+  return {
+    vibe: icons.vibe,
+    plan: icons.plan,
+    spec: icons.spec,
+  };
+}
+
+/**
+ * Keyboard shortcuts for quick mode selection.
+ */
+const MODE_SHORTCUTS: Record<CodingMode, string> = {
+  vibe: "1",
+  plan: "2",
+  spec: "3",
+} as const;
+
+/**
+ * Mode colors mapped to theme semantic colors.
+ */
+const MODE_COLOR_KEYS: Record<CodingMode, "success" | "info" | "primary"> = {
+  vibe: "success",
+  plan: "info",
+  spec: "primary",
+} as const;
+
+// =============================================================================
+// ModeSelector Component
+// =============================================================================
+
+/**
+ * ModeSelector - Interactive component for selecting coding modes.
+ *
+ * Features:
+ * - Arrow key navigation (up/down or j/k)
+ * - Number shortcuts (1, 2, 3)
+ * - Enter to confirm selection
+ * - Visual indication of current mode
+ * - Highlight of focused option
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const [mode, setMode] = useState<CodingMode>('vibe');
+ *
+ *   return (
+ *     <ModeSelector
+ *       currentMode={mode}
+ *       onSelect={setMode}
+ *       isActive
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function ModeSelector({
+  currentMode,
+  onSelect,
+  isActive = true,
+  showDescriptions = true,
+}: ModeSelectorProps): React.ReactElement {
+  const { theme } = useTheme();
+  const { t } = useTUITranslation();
+  const modes = CODING_MODES;
+
+  // Track focused index for keyboard navigation
+  const [focusedIndex, setFocusedIndex] = useState(() => modes.indexOf(currentMode));
+
+  // Handle keyboard input
+  useInput(
+    useCallback(
+      (input: string, key) => {
+        if (!isActive) return;
+
+        // Arrow navigation
+        if (key.upArrow || input === "k") {
+          setFocusedIndex((prev) => (prev > 0 ? prev - 1 : modes.length - 1));
+          return;
+        }
+
+        if (key.downArrow || input === "j") {
+          setFocusedIndex((prev) => (prev < modes.length - 1 ? prev + 1 : 0));
+          return;
+        }
+
+        // Confirm selection
+        if (key.return) {
+          const selectedMode = modes[focusedIndex];
+          if (selectedMode) {
+            onSelect(selectedMode);
+          }
+          return;
+        }
+
+        // Number shortcuts
+        const modeIndex = parseInt(input, 10) - 1;
+        if (modeIndex >= 0 && modeIndex < modes.length) {
+          const selectedMode = modes[modeIndex];
+          if (selectedMode) {
+            setFocusedIndex(modeIndex);
+            onSelect(selectedMode);
+          }
+        }
+      },
+      [isActive, focusedIndex, modes, onSelect]
+    ),
+    { isActive }
+  );
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Box marginBottom={1}>
+        <Text bold>{t("modeSelector.title")}</Text>
+      </Box>
+
+      {modes.map((mode, index) => {
+        const isFocused = index === focusedIndex && isActive;
+        const isCurrent = mode === currentMode;
+        const modeIcons = getModeIcons();
+        const icon = modeIcons[mode];
+        const shortcut = MODE_SHORTCUTS[mode];
+        const colorKey = MODE_COLOR_KEYS[mode];
+        const color = theme.colors[colorKey];
+        const config = BUILTIN_CODING_MODES[mode];
+
+        return (
+          <Box key={mode} flexDirection="column">
+            <Box>
+              {/* Focus indicator */}
+              <Text color={isFocused ? color : undefined}>{isFocused ? "❯ " : "  "}</Text>
+
+              {/* Shortcut key */}
+              <Text dimColor>[{shortcut}]</Text>
+              <Text> </Text>
+
+              {/* Mode icon and name */}
+              <Text color={color} bold={isCurrent}>
+                {icon} {mode}
+              </Text>
+
+              {/* Current indicator */}
+              {isCurrent && (
+                <Text color={theme.semantic.text.muted}> {t("modeSelector.current")}</Text>
+              )}
+            </Box>
+
+            {/* Description (when enabled) */}
+            {showDescriptions && (
+              <Box marginLeft={6}>
+                <Text dimColor wrap="truncate-end">
+                  {config.description}
+                </Text>
+              </Box>
+            )}
+          </Box>
+        );
+      })}
+
+      {/* Help text */}
+      <Box marginTop={1}>
+        <Text dimColor>{t("modeSelector.keybindings")}</Text>
+      </Box>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export type { CodingMode };