@butlerw/vellum 0.1.0

package/src/tui/components/common/VirtualizedList/types.ts

@@ -0,0 +1,107 @@
+/**
+ * VirtualizedList Types
+ *
+ * Type definitions for the virtualized list component.
+ * Ported from Gemini CLI with Vellum adaptations.
+ *
+ * @module tui/components/common/VirtualizedList/types
+ */
+
+import type React from "react";
+
+/**
+ * Sentinel value indicating scroll to the end of an item or the list.
+ */
+export const SCROLL_TO_ITEM_END = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Props for the VirtualizedList component.
+ * Generic type T represents the data item type.
+ */
+export interface VirtualizedListProps<T> {
+  /** Array of data items to render */
+  readonly data: readonly T[];
+
+  /** Render function for each item */
+  readonly renderItem: (info: { item: T; index: number }) => React.ReactElement;
+
+  /** Function to estimate item height before measurement */
+  readonly estimatedItemHeight: number | ((index: number) => number);
+
+  /** Function to extract a unique key for each item */
+  readonly keyExtractor: (item: T, index: number) => string;
+
+  /** Initial scroll index (use SCROLL_TO_ITEM_END for bottom) */
+  readonly initialScrollIndex?: number;
+
+  /** Initial offset within the scroll index */
+  readonly initialScrollOffsetInIndex?: number;
+
+  /** Color for the scrollbar thumb */
+  readonly scrollbarThumbColor?: string;
+
+  /** Callback when scroll position changes */
+  readonly onScrollTopChange?: (scrollTop: number) => void;
+
+  /** Callback when sticking to bottom state changes */
+  readonly onStickingToBottomChange?: (isSticking: boolean) => void;
+
+  /** Whether to align items to the bottom when content is shorter than the viewport */
+  readonly alignToBottom?: boolean;
+}
+
+/**
+ * Scroll anchor state - tracks position by index + offset
+ * for stability during content changes.
+ */
+export interface ScrollAnchor {
+  /** Index of the anchor item */
+  readonly index: number;
+  /** Pixel offset within the anchor item (or SCROLL_TO_ITEM_END) */
+  readonly offset: number;
+}
+
+/**
+ * Ref handle for controlling the VirtualizedList programmatically.
+ */
+export interface VirtualizedListRef<T> {
+  /** Scroll by a delta amount (positive = down, negative = up) */
+  scrollBy: (delta: number) => void;
+
+  /** Scroll to an absolute pixel offset */
+  scrollTo: (offset: number) => void;
+
+  /** Scroll to the end of the list */
+  scrollToEnd: () => void;
+
+  /** Scroll to a specific index with optional offset and position */
+  scrollToIndex: (params: { index: number; viewOffset?: number; viewPosition?: number }) => void;
+
+  /** Scroll to a specific item */
+  scrollToItem: (params: { item: T; viewOffset?: number; viewPosition?: number }) => void;
+
+  /** Get the current scroll anchor index */
+  getScrollIndex: () => number;
+
+  /** Get the current scroll state */
+  getScrollState: () => {
+    scrollTop: number;
+    scrollHeight: number;
+    innerHeight: number;
+  };
+
+  /** Check if currently sticking to bottom */
+  isAtBottom: () => boolean;
+}
+
+/**
+ * Internal state for height calculations.
+ */
+export interface HeightCache {
+  /** Cached heights indexed by item index */
+  readonly heights: readonly number[];
+  /** Cumulative offsets (offsets[i] = sum of heights[0..i-1]) */
+  readonly offsets: readonly number[];
+  /** Total height of all items */
+  readonly totalHeight: number;
+}

package/src/tui/components/common/__tests__/NewMessagesBadge.test.tsx

@@ -0,0 +1,74 @@
+/**
+ * NewMessagesBadge Component Tests
+ *
+ * @module tui/components/common/__tests__/NewMessagesBadge.test
+ */
+
+import { render } from "ink-testing-library";
+import { describe, expect, it } from "vitest";
+import { ThemeProvider } from "../../../theme/index.js";
+import { NewMessagesBadge } from "../NewMessagesBadge.js";
+
+/**
+ * Wrap component with ThemeProvider for testing.
+ */
+function renderWithTheme(ui: React.ReactElement) {
+  return render(<ThemeProvider>{ui}</ThemeProvider>);
+}
+
+describe("NewMessagesBadge", () => {
+  describe("visibility", () => {
+    it("does not render when count is 0", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={0} />);
+
+      expect(lastFrame()).toBe("");
+    });
+
+    it("does not render when count is negative", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={-5} />);
+
+      expect(lastFrame()).toBe("");
+    });
+
+    it("renders when count is positive", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={3} />);
+
+      expect(lastFrame()).toContain("new");
+    });
+  });
+
+  describe("message text", () => {
+    it("shows singular form for 1 message", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={1} />);
+
+      expect(lastFrame()).toContain("1 new message");
+      expect(lastFrame()).not.toContain("messages");
+    });
+
+    it("shows plural form for multiple messages", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={5} />);
+
+      expect(lastFrame()).toContain("5 new messages");
+    });
+
+    it("shows down arrow indicator", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={3} />);
+
+      expect(lastFrame()).toContain("↓");
+    });
+
+    it("shows keyboard hint", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={3} />);
+
+      expect(lastFrame()).toContain("press End");
+    });
+  });
+
+  describe("large counts", () => {
+    it("handles large message counts", () => {
+      const { lastFrame } = renderWithTheme(<NewMessagesBadge count={999} />);
+
+      expect(lastFrame()).toContain("999 new messages");
+    });
+  });
+});

package/src/tui/components/common/__tests__/ScrollIndicator.test.tsx

@@ -0,0 +1,193 @@
+/**
+ * ScrollIndicator Component Tests (T3.3)
+ *
+ * @module tui/components/common/__tests__/ScrollIndicator.test
+ */
+
+import { render } from "ink-testing-library";
+import { describe, expect, it } from "vitest";
+import { ThemeProvider } from "../../../theme/index.js";
+import { ScrollIndicator } from "../ScrollIndicator.js";
+
+/**
+ * Wrap component with ThemeProvider for testing.
+ */
+function renderWithTheme(ui: React.ReactElement) {
+  return render(<ThemeProvider>{ui}</ThemeProvider>);
+}
+
+describe("ScrollIndicator", () => {
+  describe("visibility", () => {
+    it("does not show when content fits in viewport", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={10} offsetFromBottom={0} viewportHeight={20} />
+      );
+
+      // Should render nothing (or empty)
+      expect(lastFrame()).toBe("");
+    });
+
+    it("does not show when content equals viewport", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={20} offsetFromBottom={0} viewportHeight={20} />
+      );
+
+      expect(lastFrame()).toBe("");
+    });
+
+    it("shows when content exceeds viewport", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={100} offsetFromBottom={0} viewportHeight={20} />
+      );
+
+      // Should render scrollbar characters
+      expect(lastFrame()).toMatch(/[█│]/);
+    });
+
+    it("respects show=false override", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={100} offsetFromBottom={0} viewportHeight={20} show={false} />
+      );
+
+      expect(lastFrame()).toBe("");
+    });
+
+    it("respects show=true override when not scrollable", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={10} offsetFromBottom={0} viewportHeight={20} show={true} />
+      );
+
+      // Even with show=true, returns null when not scrollable (no metrics)
+      expect(lastFrame()).toBe("");
+    });
+  });
+
+  describe("thumb position", () => {
+    it("positions thumb at bottom when offsetFromBottom is 0", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={100} offsetFromBottom={0} viewportHeight={10} />
+      );
+
+      const frame = lastFrame() ?? "";
+      const lines = frame.split("\n").filter(Boolean);
+
+      // Thumb should be at the end (bottom)
+      // With 100 total, 10 viewport, thumb is ~1 line (10/100 = 10%)
+      // At offset 0, thumb is at bottom
+      const lastLine = lines[lines.length - 1];
+      expect(lastLine).toContain("█");
+    });
+
+    it("positions thumb at top when at max offset", () => {
+      const totalHeight = 100;
+      const viewportHeight = 10;
+      const maxOffset = totalHeight - viewportHeight; // 90
+
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator
+          totalHeight={totalHeight}
+          offsetFromBottom={maxOffset}
+          viewportHeight={viewportHeight}
+        />
+      );
+
+      const frame = lastFrame() ?? "";
+      const lines = frame.split("\n").filter(Boolean);
+
+      // Thumb should be at the start (top)
+      const firstLine = lines[0];
+      expect(firstLine).toContain("█");
+    });
+
+    it("positions thumb in middle when offset is half", () => {
+      const totalHeight = 100;
+      const viewportHeight = 10;
+      const halfOffset = Math.floor((totalHeight - viewportHeight) / 2); // 45
+
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator
+          totalHeight={totalHeight}
+          offsetFromBottom={halfOffset}
+          viewportHeight={viewportHeight}
+        />
+      );
+
+      const frame = lastFrame() ?? "";
+      const lines = frame.split("\n").filter(Boolean);
+
+      // Should have track characters at both top and bottom
+      expect(lines.length).toBeGreaterThan(0);
+      // Thumb should be somewhere in the middle
+      const thumbIndex = lines.findIndex((line) => line.includes("█"));
+      expect(thumbIndex).toBeGreaterThan(0);
+      expect(thumbIndex).toBeLessThan(lines.length - 1);
+    });
+  });
+
+  describe("thumb size", () => {
+    it("has larger thumb when viewport is large relative to content", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={20} offsetFromBottom={0} viewportHeight={10} />
+      );
+
+      const frame = lastFrame() ?? "";
+      const thumbCount = (frame.match(/█/g) || []).length;
+
+      // With 50% viewport ratio, thumb should be ~5 lines (half of 10)
+      expect(thumbCount).toBeGreaterThanOrEqual(4);
+    });
+
+    it("has smaller thumb when viewport is small relative to content", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={200} offsetFromBottom={0} viewportHeight={10} />
+      );
+
+      const frame = lastFrame() ?? "";
+      const thumbCount = (frame.match(/█/g) || []).length;
+
+      // With 5% viewport ratio, thumb should be ~1 line (minimum)
+      expect(thumbCount).toBeGreaterThanOrEqual(1);
+      expect(thumbCount).toBeLessThanOrEqual(2);
+    });
+
+    it("respects minimum thumb size of 1", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={1000} offsetFromBottom={0} viewportHeight={10} />
+      );
+
+      const frame = lastFrame() ?? "";
+      const thumbCount = (frame.match(/█/g) || []).length;
+
+      // Even with tiny ratio, should have at least 1 thumb character
+      expect(thumbCount).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles zero viewport height", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={100} offsetFromBottom={0} viewportHeight={0} />
+      );
+
+      expect(lastFrame()).toBe("");
+    });
+
+    it("handles zero total height", () => {
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={0} offsetFromBottom={0} viewportHeight={10} />
+      );
+
+      expect(lastFrame()).toBe("");
+    });
+
+    it("handles negative offset gracefully", () => {
+      // Should clamp to valid range
+      const { lastFrame } = renderWithTheme(
+        <ScrollIndicator totalHeight={100} offsetFromBottom={-10} viewportHeight={10} />
+      );
+
+      // Should still render
+      expect(lastFrame()).toMatch(/[█│]/);
+    });
+  });
+});

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

@@ -0,0 +1,110 @@
+/**
+ * Common TUI Components
+ *
+ * Shared utility components for the Vellum CLI terminal UI.
+ *
+ * @module tui/components/common
+ */
+
+// AutoApprovalStatus (Phase 35+ - Auto-Approval Limits)
+export {
+  type AutoApprovalSeverity,
+  AutoApprovalStatus,
+  type AutoApprovalStatusProps,
+} from "./AutoApprovalStatus.js";
+// CostWarning (Phase 35+ - Cost Limits)
+export {
+  CompactCostDisplay,
+  type CompactCostDisplayProps,
+  CostWarning,
+  type CostWarningProps,
+  type CostWarningSeverity,
+} from "./CostWarning.js";
+// DynamicShortcutHints (UX improvement - context-aware shortcuts)
+export {
+  DynamicShortcutHints,
+  type DynamicShortcutHintsProps,
+  type UIState,
+} from "./DynamicShortcutHints.js";
+// EnhancedLoadingIndicator (Enhanced loading with elapsed time & cancel hints)
+export {
+  EnhancedLoadingIndicator,
+  type EnhancedLoadingIndicatorProps,
+  formatDuration,
+  useDelayedVisibility,
+  useElapsedTime,
+} from "./EnhancedLoadingIndicator.js";
+// ErrorBoundary (Chain 20)
+export { ErrorBoundary, type ErrorBoundaryProps } from "./ErrorBoundary.js";
+// GradientText (Terminal gradient text component)
+export {
+  GRADIENT_PRESETS,
+  type GradientDirection,
+  type GradientPreset,
+  GradientText,
+  type GradientTextProps,
+} from "./GradientText.js";
+// HotkeyHelpModal (Chain 24)
+export {
+  DEFAULT_HOTKEYS,
+  type HotkeyBinding,
+  HotkeyHelpModal,
+  type HotkeyHelpModalProps,
+} from "./HotkeyHelpModal.js";
+// HotkeyHints (sidebar footer hints)
+export { type HotkeyHint, HotkeyHints, type HotkeyHintsProps } from "./HotkeyHints.js";
+// MaxSizedBox (Ported from Gemini CLI)
+export {
+  MaxSizedBox,
+  type MaxSizedBoxProps,
+  type MaxSizedBoxState,
+  useMaxSizedBox,
+} from "./MaxSizedBox.js";
+// NewMessagesBadge (Phase 3 - World-Class TUI)
+export { NewMessagesBadge, type NewMessagesBadgeProps } from "./NewMessagesBadge.js";
+// ProtectedFileLegend (Protected file indicator in listings)
+export {
+  formatProtectedFileName,
+  PROTECTED_INDICATOR,
+  ProtectedFileLegend,
+  type ProtectedFileLegendProps,
+} from "./ProtectedFileLegend.js";
+// ScrollIndicator (Phase 3 - World-Class TUI)
+export { ScrollIndicator, type ScrollIndicatorProps } from "./ScrollIndicator.js";
+// Spinner (Chain 21)
+export {
+  LoadingIndicator,
+  type LoadingIndicatorProps,
+  SPINNER_FRAMES,
+  SPINNER_STYLES,
+  Spinner,
+  type SpinnerProps,
+  type SpinnerType,
+} from "./Spinner.js";
+// StreamingIndicator (Context-aware streaming phase indicator)
+export {
+  PHASE_ICONS,
+  PHASE_LABELS,
+  PHASE_SPINNER_STYLES,
+  StreamingIndicator,
+  type StreamingIndicatorProps,
+  type StreamingPhase,
+  useStreamingPhase,
+} from "./StreamingIndicator.js";
+// VirtualizedList (Ported from Gemini CLI)
+export {
+  type HeightCache,
+  SCROLL_TO_ITEM_END,
+  type ScrollAnchor,
+  type UseBatchedScrollReturn,
+  type UseScrollAnchorProps,
+  type UseScrollAnchorReturn,
+  type UseVirtualizationProps,
+  type UseVirtualizationReturn,
+  useBatchedScroll,
+  useScrollAnchor,
+  useVirtualization,
+  VirtualizedList,
+  type VirtualizedListProps,
+  type VirtualizedListRef,
+} from "./VirtualizedList/index.js";

package/src/tui/components/index.ts

@@ -0,0 +1,79 @@
+/**
+ * TUI Components
+ *
+ * React Ink components for the Vellum CLI terminal UI.
+ */
+
+// AgentProgress (T046)
+export { AgentProgress, type AgentProgressProps } from "./AgentProgress.js";
+// Banner (ASCII Art with shimmer animation)
+export * from "./Banner/index.js";
+// Backtrack controls
+export * from "./backtrack/index.js";
+// Checkpoint (Snapshot-based file state) components
+export * from "./Checkpoint/index.js";
+// Cost Display (Phase 35)
+export {
+  CostBadge,
+  type CostBadgeProps,
+  CostDisplay,
+  type CostDisplayProps,
+} from "./CostDisplay.js";
+// Common components
+export * from "./common/index.js";
+// Init Error Banner
+export { InitErrorBanner, type InitErrorBannerProps } from "./InitErrorBanner.js";
+// Component subdirectories
+export * from "./Input/index.js";
+// Layout
+export { Layout, type LayoutProps, useTerminalSize } from "./Layout.js";
+// MCP Panel
+export { McpPanel, type McpPanelProps } from "./McpPanel.js";
+// Memory Panel (Phase 31)
+export { MemoryPanel, type MemoryPanelProps } from "./MemoryPanel.js";
+export * from "./Messages/index.js";
+// Mode components (T043-T047)
+export { ModeIndicator, type ModeIndicatorProps } from "./ModeIndicator.js";
+// Model selector (Chain 22)
+export { ModelSelector, type ModelSelectorProps } from "./ModelSelector.js";
+export { ModeSelector, type ModeSelectorProps } from "./ModeSelector.js";
+// Onboarding Wizard (Phase 38)
+export { OnboardingWizard, type OnboardingWizardProps } from "./OnboardingWizard.js";
+export {
+  PhaseProgressIndicator,
+  type PhaseProgressIndicatorProps,
+} from "./PhaseProgressIndicator.js";
+export {
+  AdaptiveLayout,
+  type AdaptiveLayoutProps,
+  ScreenReaderLayout,
+  type ScreenReaderLayoutProps,
+} from "./ScreenReaderLayout.js";
+// Settings Panel (Settings System)
+export {
+  type SettingCategory,
+  type SettingItem,
+  SettingsPanel,
+  type SettingsPanelProps,
+} from "./SettingsPanel.js";
+// Sidebar components
+export * from "./Sidebar/index.js";
+// Status components (provider health)
+export * from "./Status/index.js";
+export * from "./StatusBar/index.js";
+export * from "./session/index.js";
+// Tip Banner
+export { TipBanner, type TipBannerProps } from "./TipBanner.js";
+// Todo Panel (Phase 26)
+export { TodoItem, type TodoItemData, type TodoItemProps, type TodoStatus } from "./TodoItem.js";
+export { type TodoFilterStatus, TodoPanel, type TodoPanelProps } from "./TodoPanel.js";
+export * from "./Tools/index.js";
+// Update Banner (Phase 39)
+export {
+  UpdateBanner,
+  UpdateBannerInline,
+  type UpdateBannerInlineProps,
+  type UpdateBannerProps,
+} from "./UpdateBanner.js";
+// Vim mode indicator (T041)
+export { VimModeIndicator, type VimModeIndicatorProps } from "./VimModeIndicator.js";