@butlerw/vellum 0.1.0

package/src/tui/components/PhaseProgressIndicator.tsx

@@ -0,0 +1,270 @@
+/**
+ * PhaseProgressIndicator Component (T047)
+ *
+ * TUI component for displaying visual progress through spec mode phases.
+ * Shows a segmented progress bar with 6 phases and current phase highlight.
+ *
+ * @module tui/components/PhaseProgressIndicator
+ */
+
+import type { 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 PhaseProgressIndicator component.
+ */
+export interface PhaseProgressIndicatorProps {
+  /** Current phase number (1-6) */
+  readonly currentPhase: number;
+  /** Total number of phases (default: 6) */
+  readonly totalPhases?: number;
+  /** Whether to show phase names */
+  readonly showLabels?: boolean;
+  /** Whether to show percentage */
+  readonly showPercentage?: boolean;
+  /** Width of the progress bar in characters (default: 24, 4 per phase) */
+  readonly width?: number;
+  /** Display orientation */
+  readonly orientation?: "horizontal" | "vertical";
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default progress bar width (4 chars per 6 phases) */
+const DEFAULT_WIDTH = 24;
+
+/** Default total phases */
+const DEFAULT_TOTAL_PHASES = 6;
+
+/** Progress bar characters */
+const PROGRESS_CHARS = {
+  filled: "█",
+  current: "▓",
+  empty: "░",
+  separatorFilled: "│",
+  separatorEmpty: "┊",
+} as const;
+
+/**
+ * Get phase status icons using the icon system for proper Unicode/ASCII support.
+ */
+function getPhaseStatusIcons() {
+  const icons = getIcons();
+  return {
+    completed: icons.check,
+    current: icons.bullet,
+    pending: icons.pending,
+  } as const;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Get the display name for a 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;
+}
+
+/**
+ * Calculate completion percentage.
+ */
+function calculatePercentage(current: number, total: number): number {
+  if (total <= 0) return 0;
+  // Phase N is complete when we're at phase N+1
+  // So current phase means we've completed (current - 1) phases
+  const completed = Math.max(0, current - 1);
+  return Math.round((completed / total) * 100);
+}
+
+// =============================================================================
+// PhaseProgressIndicator Component
+// =============================================================================
+
+/**
+ * PhaseProgressIndicator - Visual progress display for spec mode phases.
+ *
+ * Features:
+ * - 6-segment progress bar
+ * - Color-coded segments (completed, current, pending)
+ * - Optional phase labels
+ * - Optional percentage display
+ * - Horizontal or vertical orientation
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <PhaseProgressIndicator currentPhase={3} />
+ *
+ * // With labels and percentage
+ * <PhaseProgressIndicator
+ *   currentPhase={4}
+ *   showLabels
+ *   showPercentage
+ * />
+ *
+ * // Vertical orientation
+ * <PhaseProgressIndicator
+ *   currentPhase={2}
+ *   orientation="vertical"
+ * />
+ * ```
+ */
+export function PhaseProgressIndicator({
+  currentPhase,
+  totalPhases = DEFAULT_TOTAL_PHASES,
+  showLabels = false,
+  showPercentage = false,
+  width = DEFAULT_WIDTH,
+  orientation = "horizontal",
+}: PhaseProgressIndicatorProps): React.ReactElement {
+  const { theme } = useTheme();
+
+  // Validate and clamp current phase
+  const validPhase = Math.max(1, Math.min(currentPhase, totalPhases));
+
+  // Calculate segment width
+  const segmentWidth = Math.max(1, Math.floor(width / totalPhases));
+
+  // Calculate completion percentage
+  const percentage = useMemo(
+    () => calculatePercentage(validPhase, totalPhases),
+    [validPhase, totalPhases]
+  );
+
+  // Build progress segments
+  const segments = useMemo(() => {
+    return Array.from({ length: totalPhases }, (_, index) => {
+      const phaseNumber = index + 1;
+      const isCompleted = phaseNumber < validPhase;
+      const isCurrent = phaseNumber === validPhase;
+      const phaseName = getPhaseName(phaseNumber);
+
+      return {
+        phaseNumber,
+        phaseName,
+        isCompleted,
+        isCurrent,
+        isPending: !isCompleted && !isCurrent,
+      };
+    });
+  }, [totalPhases, validPhase]);
+
+  // Render horizontal progress bar
+  if (orientation === "horizontal") {
+    return (
+      <Box flexDirection="column">
+        {/* Progress bar */}
+        <Box>
+          {segments.map((segment, index) => {
+            const char = segment.isCompleted
+              ? PROGRESS_CHARS.filled
+              : segment.isCurrent
+                ? PROGRESS_CHARS.current
+                : PROGRESS_CHARS.empty;
+
+            const color = segment.isCompleted
+              ? theme.colors.success
+              : segment.isCurrent
+                ? theme.colors.primary
+                : theme.semantic.text.muted;
+
+            const barSegment = char.repeat(segmentWidth);
+
+            return (
+              <Box key={segment.phaseNumber}>
+                <Text color={color}>{barSegment}</Text>
+                {/* Separator between segments (except last) */}
+                {index < segments.length - 1 && (
+                  <Text color={theme.semantic.text.muted}>
+                    {segment.isCompleted
+                      ? PROGRESS_CHARS.separatorFilled
+                      : PROGRESS_CHARS.separatorEmpty}
+                  </Text>
+                )}
+              </Box>
+            );
+          })}
+
+          {/* Percentage display */}
+          {showPercentage && <Text color={theme.semantic.text.secondary}> {percentage}%</Text>}
+        </Box>
+
+        {/* Phase labels */}
+        {showLabels && (
+          <Box marginTop={1}>
+            <Text color={theme.colors.primary} bold>
+              {getPhaseStatusIcons().current} {getPhaseName(validPhase)}
+            </Text>
+            <Text color={theme.semantic.text.muted}>
+              {" "}
+              ({validPhase}/{totalPhases})
+            </Text>
+          </Box>
+        )}
+      </Box>
+    );
+  }
+
+  // Get icons for vertical list
+  const phaseIcons = getPhaseStatusIcons();
+
+  // Render vertical progress list
+  return (
+    <Box flexDirection="column">
+      {segments.map((segment) => {
+        const icon = segment.isCompleted
+          ? phaseIcons.completed
+          : segment.isCurrent
+            ? phaseIcons.current
+            : phaseIcons.pending;
+
+        const color = segment.isCompleted
+          ? theme.colors.success
+          : segment.isCurrent
+            ? theme.colors.primary
+            : theme.semantic.text.muted;
+
+        return (
+          <Box key={segment.phaseNumber}>
+            <Text color={color}>
+              {icon} {segment.phaseNumber}. {segment.phaseName}
+            </Text>
+          </Box>
+        );
+      })}
+
+      {/* Progress summary */}
+      {showPercentage && (
+        <Box marginTop={1}>
+          <Text color={theme.semantic.text.secondary}>
+            Progress: {percentage}% ({validPhase - 1}/{totalPhases} completed)
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export type { SpecPhase };

package/src/tui/components/RateLimitIndicator.tsx

@@ -0,0 +1,82 @@
+/**
+ * Rate Limit Indicator Component
+ *
+ * Displays rate limit status and warnings in the TUI.
+ * Placeholder implementation - to be expanded.
+ *
+ * @module tui/components/RateLimitIndicator
+ */
+
+import { Text } from "ink";
+import type React from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface RateLimitIndicatorProps {
+  /** Whether rate limiting is active */
+  isLimited?: boolean;
+  /** Remaining requests */
+  remaining?: number;
+  /** Total limit */
+  limit?: number;
+  /** Time until reset (seconds) */
+  resetIn?: number;
+  /** Whether to show compact view */
+  compact?: boolean;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Displays rate limit status
+ */
+export function RateLimitIndicator({
+  isLimited = false,
+  remaining,
+  limit,
+  resetIn,
+  compact = false,
+}: RateLimitIndicatorProps): React.ReactElement | null {
+  // Don't render if not limited and no info to show
+  if (!isLimited && remaining === undefined) {
+    return null;
+  }
+
+  if (compact) {
+    if (isLimited) {
+      return <Text color="yellow">⚠ Rate limited</Text>;
+    }
+    if (remaining !== undefined && limit !== undefined) {
+      const percentage = (remaining / limit) * 100;
+      const color = percentage < 20 ? "yellow" : "green";
+      return (
+        <Text color={color}>
+          {remaining}/{limit}
+        </Text>
+      );
+    }
+    return null;
+  }
+
+  // Full view
+  if (isLimited) {
+    const resetText = resetIn !== undefined ? ` (resets in ${resetIn}s)` : "";
+    return <Text color="yellow">⚠ Rate limited{resetText}</Text>;
+  }
+
+  if (remaining !== undefined && limit !== undefined) {
+    return (
+      <Text dimColor>
+        Requests: {remaining}/{limit}
+      </Text>
+    );
+  }
+
+  return null;
+}
+
+export default RateLimitIndicator;

package/src/tui/components/ScreenReaderLayout.tsx

@@ -0,0 +1,295 @@
+/**
+ * ScreenReaderLayout Component (T045)
+ *
+ * Simplified layout for screen reader accessibility.
+ * Provides a linear, sequential display optimized for screen readers
+ * with automatic status announcements.
+ *
+ * Key features:
+ * - Linear/sequential message display (no complex grid layouts)
+ * - Clear section headings for navigation
+ * - Automatic status change announcements
+ * - Simplified visual presentation
+ *
+ * @module tui/components/ScreenReaderLayout
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { useEffect, useMemo, useRef } from "react";
+import {
+  formatForScreenReader,
+  type UseScreenReaderOptions,
+  useScreenReader,
+} from "../hooks/useScreenReader.js";
+import { useTheme } from "../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the ScreenReaderLayout component.
+ */
+export interface ScreenReaderLayoutProps {
+  /** Header content (rendered as first section) */
+  readonly header?: React.ReactNode;
+  /** Main content area */
+  readonly children: React.ReactNode;
+  /** Footer content (rendered as last section) */
+  readonly footer?: React.ReactNode;
+  /** Current status message to announce on change */
+  readonly status?: string;
+  /** Screen reader options */
+  readonly screenReaderOptions?: UseScreenReaderOptions;
+  /** Callback when screen reader mode changes */
+  readonly onScreenReaderChange?: (isEnabled: boolean) => void;
+}
+
+/**
+ * Status information for tracking changes.
+ */
+interface StatusInfo {
+  readonly message: string;
+  readonly timestamp: number;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Section separator for visual clarity */
+const SECTION_SEPARATOR = "────────────────────────────────────────";
+
+// =============================================================================
+// Sub-Components
+// =============================================================================
+
+/**
+ * Section header for screen reader navigation.
+ */
+interface SectionHeaderProps {
+  readonly title: string;
+  readonly level?: 1 | 2 | 3;
+}
+
+function SectionHeader({ title, level = 2 }: SectionHeaderProps): React.ReactElement {
+  const { theme } = useTheme();
+
+  // Use different prefixes for heading levels (helps screen readers)
+  const prefix = level === 1 ? "# " : level === 2 ? "## " : "### ";
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text color={theme.semantic.text.muted}>{SECTION_SEPARATOR}</Text>
+      <Text bold color={theme.semantic.text.primary}>
+        {prefix}
+        {title}
+      </Text>
+    </Box>
+  );
+}
+
+/**
+ * Simple message display for screen reader mode.
+ */
+interface SimpleMessageProps {
+  readonly children: React.ReactNode;
+}
+
+function SimpleMessage({ children }: SimpleMessageProps): React.ReactElement {
+  return (
+    <Box flexDirection="column" marginY={1}>
+      {children}
+    </Box>
+  );
+}
+
+/**
+ * Status display with clear labeling.
+ */
+interface StatusDisplayProps {
+  readonly status: string;
+}
+
+function StatusDisplay({ status }: StatusDisplayProps): React.ReactElement {
+  const { theme } = useTheme();
+
+  return (
+    <Box marginY={1}>
+      <Text>
+        <Text color={theme.semantic.text.secondary} bold>
+          Status:{" "}
+        </Text>
+        <Text>{status}</Text>
+      </Text>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * ScreenReaderLayout provides an accessible layout optimized for screen readers.
+ *
+ * Unlike the standard Layout component which uses complex grid arrangements,
+ * ScreenReaderLayout presents content in a simple, linear fashion that screen
+ * readers can navigate sequentially.
+ *
+ * @example
+ * ```tsx
+ * function AccessibleApp() {
+ *   return (
+ *     <ScreenReaderLayout
+ *       header={<Text>Vellum AI Assistant</Text>}
+ *       status="Ready for input"
+ *       footer={<Text>Press Ctrl+C to exit</Text>}
+ *     >
+ *       <MessageList messages={messages} />
+ *     </ScreenReaderLayout>
+ *   );
+ * }
+ * ```
+ */
+export function ScreenReaderLayout({
+  header,
+  children,
+  footer,
+  status,
+  screenReaderOptions,
+  onScreenReaderChange,
+}: ScreenReaderLayoutProps): React.ReactElement {
+  const { theme } = useTheme();
+  const { isEnabled, announce } = useScreenReader(screenReaderOptions);
+
+  // Track previous status to detect changes
+  const prevStatusRef = useRef<StatusInfo | null>(null);
+
+  // Notify parent of screen reader mode changes
+  useEffect(() => {
+    onScreenReaderChange?.(isEnabled);
+  }, [isEnabled, onScreenReaderChange]);
+
+  // Announce status changes
+  useEffect(() => {
+    if (!status || !isEnabled) return;
+
+    const prevStatus = prevStatusRef.current;
+    const statusChanged = !prevStatus || prevStatus.message !== status;
+
+    if (statusChanged) {
+      // Announce the new status
+      announce(formatForScreenReader(`Status: ${status}`), "polite");
+
+      // Update the ref
+      prevStatusRef.current = {
+        message: status,
+        timestamp: Date.now(),
+      };
+    }
+  }, [status, isEnabled, announce]);
+
+  // Announce initial state on mount
+  useEffect(() => {
+    if (isEnabled) {
+      announce("Vellum AI Assistant loaded. Screen reader mode active.", "polite");
+    }
+  }, [isEnabled, announce]);
+
+  // Memoize the layout structure
+  const layout = useMemo(() => {
+    return (
+      <Box flexDirection="column" padding={1}>
+        {/* Header Section */}
+        {header && (
+          <>
+            <SectionHeader title="Header" level={1} />
+            <SimpleMessage>{header}</SimpleMessage>
+          </>
+        )}
+
+        {/* Status Section */}
+        {status && (
+          <>
+            <SectionHeader title="Current Status" level={2} />
+            <StatusDisplay status={status} />
+          </>
+        )}
+
+        {/* Main Content Section */}
+        <SectionHeader title="Content" level={1} />
+        <SimpleMessage>{children}</SimpleMessage>
+
+        {/* Footer Section */}
+        {footer && (
+          <>
+            <SectionHeader title="Footer" level={2} />
+            <SimpleMessage>{footer}</SimpleMessage>
+          </>
+        )}
+
+        {/* Screen Reader Mode Indicator */}
+        <Box marginTop={1}>
+          <Text color={theme.semantic.text.muted} dimColor>
+            [Screen reader mode: {isEnabled ? "ON" : "OFF"}]
+          </Text>
+        </Box>
+      </Box>
+    );
+  }, [header, status, children, footer, isEnabled, theme.semantic.text.muted]);
+
+  return layout;
+}
+
+// =============================================================================
+// Utility Components
+// =============================================================================
+
+/**
+ * Wrapper to conditionally render ScreenReaderLayout or regular Layout.
+ */
+export interface AdaptiveLayoutProps extends Omit<ScreenReaderLayoutProps, "screenReaderOptions"> {
+  /** Regular layout to render when screen reader mode is off */
+  readonly regularLayout?: React.ReactElement;
+  /** Screen reader options */
+  readonly screenReaderOptions?: UseScreenReaderOptions;
+}
+
+/**
+ * AdaptiveLayout automatically switches between ScreenReaderLayout and a
+ * regular layout based on screen reader detection.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <AdaptiveLayout
+ *       regularLayout={<Layout>{content}</Layout>}
+ *       status={status}
+ *     >
+ *       {content}
+ *     </AdaptiveLayout>
+ *   );
+ * }
+ * ```
+ */
+export function AdaptiveLayout({
+  regularLayout,
+  screenReaderOptions,
+  ...screenReaderProps
+}: AdaptiveLayoutProps): React.ReactElement {
+  const { isEnabled } = useScreenReader(screenReaderOptions);
+
+  if (isEnabled) {
+    return <ScreenReaderLayout screenReaderOptions={screenReaderOptions} {...screenReaderProps} />;
+  }
+
+  // If no regular layout provided, use screen reader layout as fallback
+  if (!regularLayout) {
+    return <ScreenReaderLayout screenReaderOptions={screenReaderOptions} {...screenReaderProps} />;
+  }
+
+  return regularLayout;
+}