@butlerw/vellum 0.1.0

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

@@ -0,0 +1,193 @@
+/**
+ * HotkeyHelpModal Component (Chain 24)
+ *
+ * Modal overlay displaying available keyboard shortcuts.
+ * Helps users discover and learn hotkey bindings.
+ *
+ * @module tui/components/common/HotkeyHelpModal
+ */
+
+import { Box, Text, useInput } from "ink";
+import type React from "react";
+import { useMemo } from "react";
+import { useTheme } from "../../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * A single hotkey binding definition.
+ */
+export interface HotkeyBinding {
+  /** Key combination (e.g., "Ctrl+C", "?", "Esc") */
+  readonly key: string;
+  /** Description of what the hotkey does */
+  readonly description: string;
+  /** Optional scope/category (e.g., "Global", "Editor", "Navigation") */
+  readonly scope?: string;
+}
+
+/**
+ * Props for the HotkeyHelpModal component.
+ */
+export interface HotkeyHelpModalProps {
+  /** Whether the modal is visible */
+  readonly isVisible: boolean;
+  /** Callback when the modal should close */
+  readonly onClose: () => void;
+  /** List of hotkey bindings to display */
+  readonly hotkeys: readonly HotkeyBinding[];
+  /** Title for the modal (default: "Keyboard Shortcuts") */
+  readonly title?: string;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default hotkeys commonly available in the TUI */
+export const DEFAULT_HOTKEYS: HotkeyBinding[] = [
+  { key: "F1", description: "Show this help", scope: "Global" },
+  { key: "Ctrl+Shift+A", description: "Open approval queue", scope: "Global" },
+  { key: "Ctrl+C", description: "Exit application", scope: "Global" },
+  { key: "Ctrl+L", description: "Clear screen", scope: "Global" },
+  { key: "Esc", description: "Cancel / Close modal", scope: "Global" },
+  { key: "↑/↓", description: "Navigate history / options", scope: "Navigation" },
+  { key: "Tab", description: "Autocomplete / Next field", scope: "Input" },
+  { key: "Enter", description: "Submit / Confirm", scope: "Input" },
+  { key: "Ctrl+U", description: "Clear input line", scope: "Input" },
+];
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Group hotkeys by their scope.
+ */
+function groupHotkeysByScope(hotkeys: readonly HotkeyBinding[]): Map<string, HotkeyBinding[]> {
+  const grouped = new Map<string, HotkeyBinding[]>();
+
+  for (const hotkey of hotkeys) {
+    const scope = hotkey.scope ?? "General";
+    const existing = grouped.get(scope) ?? [];
+    grouped.set(scope, [...existing, hotkey]);
+  }
+
+  return grouped;
+}
+
+/**
+ * Calculate the maximum key width for alignment.
+ */
+function getMaxKeyWidth(hotkeys: readonly HotkeyBinding[]): number {
+  return Math.max(...hotkeys.map((h) => h.key.length), 8);
+}
+
+// =============================================================================
+// HotkeyHelpModal Component
+// =============================================================================
+
+/**
+ * HotkeyHelpModal - Modal overlay for keyboard shortcut help.
+ *
+ * Features:
+ * - Groups hotkeys by scope/category
+ * - Aligned key-description columns
+ * - Dismissible with Esc or ?
+ * - Themeable styling
+ *
+ * @example
+ * ```tsx
+ * const [showHelp, setShowHelp] = useState(false);
+ *
+ * <HotkeyHelpModal
+ *   isVisible={showHelp}
+ *   onClose={() => setShowHelp(false)}
+ *   hotkeys={[
+ *     { key: "Ctrl+S", description: "Save file", scope: "Editor" },
+ *     { key: "Ctrl+Z", description: "Undo", scope: "Editor" },
+ *   ]}
+ * />
+ * ```
+ */
+export function HotkeyHelpModal({
+  isVisible,
+  onClose,
+  hotkeys,
+  title = "Keyboard Shortcuts",
+}: HotkeyHelpModalProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+
+  // Handle keyboard input for closing
+  useInput(
+    (input, key) => {
+      if (key.escape || input === "q") {
+        onClose();
+      }
+    },
+    { isActive: isVisible }
+  );
+
+  // Group hotkeys by scope
+  const groupedHotkeys = useMemo(() => groupHotkeysByScope(hotkeys), [hotkeys]);
+  const maxKeyWidth = useMemo(() => getMaxKeyWidth(hotkeys), [hotkeys]);
+
+  // Don't render if not visible
+  if (!isVisible) {
+    return null;
+  }
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={theme.colors.primary}
+      paddingX={2}
+      paddingY={1}
+    >
+      {/* Title */}
+      <Box marginBottom={1}>
+        <Text color={theme.colors.primary} bold>
+          {title}
+        </Text>
+      </Box>
+
+      {/* Hotkey groups */}
+      {Array.from(groupedHotkeys.entries()).map(([scope, scopeHotkeys]) => (
+        <Box key={scope} flexDirection="column" marginBottom={1}>
+          {/* Scope header */}
+          <Box marginBottom={0}>
+            <Text color={theme.semantic.text.muted} underline>
+              {scope}
+            </Text>
+          </Box>
+
+          {/* Hotkeys in this scope */}
+          {scopeHotkeys.map((hotkey) => (
+            <Box key={hotkey.key}>
+              <Box width={maxKeyWidth + 2}>
+                <Text color={theme.colors.info} bold>
+                  {hotkey.key.padEnd(maxKeyWidth)}
+                </Text>
+              </Box>
+              <Text color={theme.semantic.text.secondary}>{hotkey.description}</Text>
+            </Box>
+          ))}
+        </Box>
+      ))}
+
+      {/* Close hint */}
+      <Box marginTop={1}>
+        <Text dimColor>Press Esc or q to close</Text>
+      </Box>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export default HotkeyHelpModal;

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

@@ -0,0 +1,70 @@
+/**
+ * HotkeyHints Component
+ *
+ * Small, reusable hint bar for displaying discoverable keybindings.
+ * Designed to be safe in narrow Ink layouts: single-line, dim, truncates.
+ *
+ * Memoized to prevent re-renders when parent context updates (e.g., message streaming).
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { memo } from "react";
+
+export type HotkeyHint = {
+  readonly keys: string;
+  readonly label: string;
+};
+
+export interface HotkeyHintsProps {
+  readonly hints: ReadonlyArray<HotkeyHint>;
+  /** Separator between items (default: " │ ") */
+  readonly separator?: string;
+}
+
+/**
+ * Compare two HotkeyHint arrays for equality.
+ */
+function hintsAreEqual(
+  prevHints: ReadonlyArray<HotkeyHint>,
+  nextHints: ReadonlyArray<HotkeyHint>
+): boolean {
+  if (prevHints.length !== nextHints.length) return false;
+  for (let i = 0; i < prevHints.length; i++) {
+    const prevHint = prevHints[i];
+    const nextHint = nextHints[i];
+    if (prevHint?.keys !== nextHint?.keys || prevHint?.label !== nextHint?.label) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Custom comparison for React.memo - only re-render when hints or separator actually change.
+ */
+function arePropsEqual(prev: HotkeyHintsProps, next: HotkeyHintsProps): boolean {
+  return prev.separator === next.separator && hintsAreEqual(prev.hints, next.hints);
+}
+
+function HotkeyHintsImpl({ hints, separator = " │ " }: HotkeyHintsProps): React.JSX.Element {
+  if (hints.length === 0) {
+    return <Box />;
+  }
+
+  return (
+    <Box>
+      <Text dimColor wrap="truncate">
+        {hints.map((hint, index) => (
+          <Text key={`${hint.keys}-${hint.label}`}>
+            {index > 0 ? separator : ""}
+            <Text bold>{hint.keys}</Text>
+            <Text> {hint.label}</Text>
+          </Text>
+        ))}
+      </Text>
+    </Box>
+  );
+}
+
+export const HotkeyHints = memo(HotkeyHintsImpl, arePropsEqual);

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

@@ -0,0 +1,354 @@
+/**
+ * MaxSizedBox Component
+ *
+ * A container component that limits content to a maximum size
+ * and shows a "Show More" indicator when content is truncated.
+ *
+ * This component is essential for preventing overflow in terminal UIs
+ * while maintaining a good user experience by indicating when content
+ * has been truncated.
+ *
+ * Ported from Gemini CLI for Vellum TUI.
+ *
+ * @module tui/components/common/MaxSizedBox
+ */
+
+import { Box, type DOMElement, Text } from "ink";
+import type React from "react";
+import { type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { useOverflowOptional } from "../../context/OverflowContext.js";
+import { useFlickerDetector } from "../../hooks/useFlickerDetector.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the MaxSizedBox component
+ */
+export interface MaxSizedBoxProps {
+  /** Content to render (will be truncated if exceeds maxHeight) */
+  readonly children: ReactNode;
+  /** Maximum height in rows/lines */
+  readonly maxHeight: number;
+  /** Minimum height in rows/lines (default: 1) */
+  readonly minHeight?: number;
+  /**
+   * Text to show when content is truncated.
+   * Set to null to hide the indicator.
+   * @default "... (more)"
+   */
+  readonly truncationIndicator?: string | null;
+  /**
+   * Color for the truncation indicator
+   * @default "dim"
+   */
+  readonly indicatorColor?: string;
+  /**
+   * Callback when expanded state changes
+   * @param expanded - Whether the content is now expanded
+   */
+  readonly onExpandChange?: (expanded: boolean) => void;
+  /**
+   * Callback when overflow state changes
+   * @param isOverflowing - Whether content is currently overflowing
+   */
+  readonly onOverflowChange?: (isOverflowing: boolean) => void;
+  /**
+   * Initial expanded state (default: false)
+   */
+  readonly initialExpanded?: boolean;
+  /**
+   * Allow expanding the content (default: false)
+   * When true, the truncation indicator becomes "Show More" / "Show Less"
+   */
+  readonly expandable?: boolean;
+  /**
+   * Unique ID for overflow tracking (auto-generated if not provided)
+   */
+  readonly id?: string;
+  /** Width of the box (default: 100%) */
+  readonly width?: number | string;
+  /** Padding within the box */
+  readonly padding?: number;
+  /** Horizontal padding */
+  readonly paddingX?: number;
+  /** Vertical padding */
+  readonly paddingY?: number;
+}
+
+/**
+ * State returned by the MaxSizedBox for external control
+ */
+export interface MaxSizedBoxState {
+  /** Whether content is currently overflowing */
+  readonly isOverflowing: boolean;
+  /** Whether content is currently expanded */
+  readonly isExpanded: boolean;
+  /** Measured content height */
+  readonly contentHeight: number;
+  /** Amount of overflow (0 if content fits) */
+  readonly overflowAmount: number;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default truncation indicator text */
+const DEFAULT_TRUNCATION_INDICATOR = "... (more)";
+
+/** Expandable show more text */
+const SHOW_MORE_TEXT = "▼ Show More";
+
+/** Expandable show less text */
+const SHOW_LESS_TEXT = "▲ Show Less";
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * MaxSizedBox limits content to a maximum height with optional truncation indicator.
+ *
+ * Features:
+ * - **Height limiting**: Prevents content from exceeding specified bounds
+ * - **Truncation indicator**: Shows when content is cut off
+ * - **Expandable mode**: Optional expand/collapse functionality
+ * - **Overflow tracking**: Integrates with OverflowContext
+ * - **Flicker prevention**: Uses debounced overflow detection
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - truncate at 10 rows
+ * <MaxSizedBox maxHeight={10}>
+ *   <Text>{longContent}</Text>
+ * </MaxSizedBox>
+ *
+ * // With expand functionality
+ * <MaxSizedBox
+ *   maxHeight={5}
+ *   expandable
+ *   onExpandChange={(expanded) => console.log('Expanded:', expanded)}
+ * >
+ *   <CodeBlock code={sourceCode} />
+ * </MaxSizedBox>
+ *
+ * // Custom truncation indicator
+ * <MaxSizedBox
+ *   maxHeight={20}
+ *   truncationIndicator="[Content truncated...]"
+ *   indicatorColor="yellow"
+ * >
+ *   <LogOutput logs={logs} />
+ * </MaxSizedBox>
+ *
+ * // Hide truncation indicator
+ * <MaxSizedBox maxHeight={10} truncationIndicator={null}>
+ *   <Content />
+ * </MaxSizedBox>
+ * ```
+ */
+export function MaxSizedBox({
+  children,
+  maxHeight,
+  minHeight = 1,
+  truncationIndicator = DEFAULT_TRUNCATION_INDICATOR,
+  indicatorColor = "dim",
+  onExpandChange,
+  onOverflowChange,
+  initialExpanded = false,
+  expandable = false,
+  id: providedId,
+  width = "100%",
+  padding,
+  paddingX,
+  paddingY,
+}: MaxSizedBoxProps): React.JSX.Element {
+  // Generate unique ID if not provided
+  const generatedId = useId();
+  const componentId = providedId ?? generatedId;
+
+  // Expansion state
+  const [isExpanded, setIsExpanded] = useState(initialExpanded);
+
+  // Content measurement
+  const contentRef = useRef<DOMElement | null>(null);
+  const [measuredHeight, setMeasuredHeight] = useState(0);
+
+  // Optional overflow context integration
+  const overflowContext = useOverflowOptional();
+
+  // Flicker detection for stable overflow state
+  const { isOverflowing, overflow } = useFlickerDetector({
+    contentHeight: measuredHeight,
+    containerHeight: maxHeight,
+    threshold: 0,
+    debounce: true,
+  });
+
+  /**
+   * Measure content height on mount and updates
+   */
+  const measureContent = useCallback(() => {
+    if (contentRef.current) {
+      // In Ink, we estimate height based on the rendered output
+      // This is a simplified measurement - actual implementation may
+      // need to parse ANSI output or use Ink's measurement APIs
+      const element = contentRef.current;
+      const yogaNode = element.yogaNode;
+      if (yogaNode) {
+        const computedHeight = yogaNode.getComputedHeight();
+        setMeasuredHeight(Math.ceil(computedHeight));
+      }
+    }
+  }, []);
+
+  /**
+   * Effect to measure content on mount.
+   * Measurement happens on every render since content could change.
+   * We call measureContent directly in the effect body which captures
+   * the current contentRef value.
+   */
+  useEffect(() => {
+    measureContent();
+  });
+
+  /**
+   * Effect to notify parent of overflow changes
+   */
+  useEffect(() => {
+    onOverflowChange?.(isOverflowing);
+  }, [isOverflowing, onOverflowChange]);
+
+  /**
+   * Effect to register/unregister with overflow context
+   */
+  useEffect(() => {
+    if (!overflowContext) return;
+
+    if (isOverflowing && !isExpanded) {
+      overflowContext.registerOverflow(componentId);
+    } else {
+      overflowContext.unregisterOverflow(componentId);
+    }
+
+    return () => {
+      overflowContext.unregisterOverflow(componentId);
+    };
+  }, [isOverflowing, isExpanded, componentId, overflowContext]);
+
+  /**
+   * Handle expand/collapse toggle.
+   * Reserved for future interactive functionality (keyboard/click handlers).
+   */
+  const _handleToggleExpand = useCallback(() => {
+    const newExpanded = !isExpanded;
+    setIsExpanded(newExpanded);
+    onExpandChange?.(newExpanded);
+  }, [isExpanded, onExpandChange]);
+
+  // Preserve reference for future use
+  void _handleToggleExpand;
+
+  /**
+   * Calculate effective height
+   */
+  const effectiveHeight = useMemo(() => {
+    if (isExpanded) {
+      // When expanded, use measured height (no limit)
+      return Math.max(minHeight, measuredHeight);
+    }
+    // When collapsed, limit to maxHeight
+    return Math.max(minHeight, Math.min(maxHeight, measuredHeight));
+  }, [isExpanded, maxHeight, minHeight, measuredHeight]);
+
+  /**
+   * Determine if truncation indicator should show
+   */
+  const showTruncationIndicator = useMemo(() => {
+    // Don't show if no indicator text
+    if (truncationIndicator === null) return false;
+    // Show if overflowing and not expanded
+    return isOverflowing && !isExpanded;
+  }, [truncationIndicator, isOverflowing, isExpanded]);
+
+  /**
+   * Get indicator text based on mode
+   */
+  const indicatorText = useMemo(() => {
+    if (expandable) {
+      return isExpanded ? SHOW_LESS_TEXT : SHOW_MORE_TEXT;
+    }
+    return truncationIndicator;
+  }, [expandable, isExpanded, truncationIndicator]);
+
+  /**
+   * Render the content with optional truncation
+   */
+  const resolvedHeight = measuredHeight > 0 ? effectiveHeight : undefined;
+
+  return (
+    <Box
+      flexDirection="column"
+      width={width}
+      height={resolvedHeight}
+      overflow="hidden"
+      padding={padding}
+      paddingX={paddingX}
+      paddingY={paddingY}
+    >
+      {/* Content container */}
+      <Box ref={contentRef} flexDirection="column" flexGrow={1} overflow="hidden">
+        {children}
+      </Box>
+
+      {/* Truncation indicator */}
+      {showTruncationIndicator && indicatorText && (
+        <Box>
+          <Text color={indicatorColor} dimColor={!expandable}>
+            {indicatorText}
+            {overflow > 0 && !expandable && ` (+${overflow} lines)`}
+          </Text>
+        </Box>
+      )}
+
+      {/* Show "Show Less" when expanded */}
+      {expandable && isExpanded && (
+        <Box>
+          <Text color={indicatorColor}>{SHOW_LESS_TEXT}</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+// =============================================================================
+// Convenience Hook
+// =============================================================================
+
+/**
+ * Hook to get MaxSizedBox-like overflow calculations without the component.
+ * Useful for custom implementations that need the same logic.
+ *
+ * @param contentHeight - Current content height
+ * @param maxHeight - Maximum allowed height
+ * @returns Overflow state and metrics
+ */
+export function useMaxSizedBox(contentHeight: number, maxHeight: number): MaxSizedBoxState {
+  const { isOverflowing, overflow } = useFlickerDetector({
+    contentHeight,
+    containerHeight: maxHeight,
+    threshold: 0,
+  });
+
+  return useMemo(
+    () => ({
+      isOverflowing,
+      isExpanded: false,
+      contentHeight,
+      overflowAmount: Math.max(0, overflow),
+    }),
+    [isOverflowing, contentHeight, overflow]
+  );
+}

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

@@ -0,0 +1,65 @@
+/**
+ * NewMessagesBadge Component
+ *
+ * Badge showing unread message count with scroll-to-bottom action.
+ * Displays "↓ N new messages" when user is in manual scroll mode.
+ *
+ * @module tui/components/common/NewMessagesBadge
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { useTheme } from "../../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for NewMessagesBadge component.
+ */
+export interface NewMessagesBadgeProps {
+  /** Number of new messages */
+  readonly count: number;
+  /** Callback when clicked/activated */
+  readonly onScrollToBottom?: () => void;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Badge showing unread message count with scroll-to-bottom hint.
+ *
+ * Displays "↓ N new messages (press End)" when count > 0.
+ * Hidden when count = 0 (no visual clutter).
+ *
+ * @example
+ * ```tsx
+ * <NewMessagesBadge
+ *   count={unreadCount}
+ *   onScrollToBottom={() => scrollController.resumeFollow()}
+ * />
+ * ```
+ */
+export function NewMessagesBadge({
+  count,
+  onScrollToBottom: _onScrollToBottom,
+}: NewMessagesBadgeProps): React.ReactElement | null {
+  const { theme } = useTheme();
+
+  // Don't render if no new messages
+  if (count <= 0) {
+    return null;
+  }
+
+  // Format message text
+  const messageText = count === 1 ? "1 new message" : `${count} new messages`;
+
+  return (
+    <Box justifyContent="center" paddingX={1}>
+      <Text color={theme.colors.info}>↓ {messageText} (press End)</Text>
+    </Box>
+  );
+}