@butlerw/vellum 0.1.0

package/src/tui/hooks/useInputHighlight.ts

@@ -0,0 +1,145 @@
+/**
+ * useInputHighlight Hook (T009-HL)
+ *
+ * React hook that memoizes input text highlighting transformations.
+ * Provides efficient highlight parsing with caching.
+ *
+ * @module tui/hooks/useInputHighlight
+ */
+
+import { useMemo, useRef } from "react";
+import {
+  findSegmentAtCursor,
+  type HighlightResult,
+  type HighlightSegment,
+  parseHighlights,
+} from "../components/Input/highlight.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for the useInputHighlight hook.
+ */
+export interface UseInputHighlightOptions {
+  /** The input text to highlight */
+  readonly text: string;
+  /** Whether highlighting is enabled */
+  readonly enabled?: boolean;
+  /** Current cursor position (optional) */
+  readonly cursorPosition?: number;
+}
+
+/**
+ * Return value from useInputHighlight hook.
+ */
+export interface UseInputHighlightReturn {
+  /** Parsed highlight result */
+  readonly result: HighlightResult;
+  /** Whether any highlights were found */
+  readonly hasHighlights: boolean;
+  /** The segment containing the cursor (if any) */
+  readonly cursorSegment: HighlightSegment | undefined;
+  /** Whether highlighting is active */
+  readonly isHighlighting: boolean;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook for memoized input text highlighting.
+ *
+ * Caches the highlight parsing result and only recomputes when text changes.
+ * Also provides cursor-aware segment information.
+ *
+ * @param options - Hook configuration
+ * @returns Highlight result and metadata
+ *
+ * @example
+ * ```tsx
+ * function MyInput({ value, cursorPosition }) {
+ *   const { result, hasHighlights, cursorSegment } = useInputHighlight({
+ *     text: value,
+ *     enabled: true,
+ *     cursorPosition,
+ *   });
+ *
+ *   return (
+ *     <HighlightedText
+ *       text={value}
+ *       highlightResult={result}
+ *       cursorPosition={cursorPosition}
+ *       showCursor
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useInputHighlight({
+  text,
+  enabled = true,
+  cursorPosition,
+}: UseInputHighlightOptions): UseInputHighlightReturn {
+  // Cache for avoiding reparse on cursor-only changes
+  const cacheRef = useRef<{ text: string; result: HighlightResult } | null>(null);
+
+  // Parse highlights (memoized by text)
+  const result = useMemo(() => {
+    // Return empty result if disabled
+    if (!enabled) {
+      return { segments: [], hasHighlights: false };
+    }
+
+    // Check cache first
+    if (cacheRef.current?.text === text) {
+      return cacheRef.current.result;
+    }
+
+    // Parse and cache
+    const parsed = parseHighlights(text);
+    cacheRef.current = { text, result: parsed };
+    return parsed;
+  }, [text, enabled]);
+
+  // Find cursor segment (memoized by cursor position and segments)
+  const cursorSegment = useMemo(() => {
+    if (cursorPosition === undefined || !result.hasHighlights) {
+      return undefined;
+    }
+    return findSegmentAtCursor(result.segments, cursorPosition);
+  }, [result.segments, cursorPosition, result.hasHighlights]);
+
+  return {
+    result,
+    hasHighlights: result.hasHighlights,
+    cursorSegment,
+    isHighlighting: enabled && result.hasHighlights,
+  };
+}
+
+// =============================================================================
+// Utility Hooks
+// =============================================================================
+
+/**
+ * Hook for multiline input highlighting.
+ * Parses each line separately for better performance with large inputs.
+ *
+ * @param lines - Array of line strings
+ * @param enabled - Whether highlighting is enabled
+ * @returns Array of highlight results, one per line
+ */
+export function useMultilineHighlight(
+  lines: readonly string[],
+  enabled = true
+): readonly HighlightResult[] {
+  return useMemo(() => {
+    if (!enabled) {
+      return lines.map(() => ({ segments: [], hasHighlights: false }));
+    }
+    return lines.map((line) => parseHighlights(line));
+  }, [lines, enabled]);
+}

package/src/tui/hooks/useInputHistory.ts

@@ -0,0 +1,246 @@
+/**
+ * useInputHistory Hook (T012)
+ *
+ * React hook for managing input history with navigation.
+ * Supports navigating through previous entries and optional persistence.
+ *
+ * @module @vellum/cli
+ */
+
+import { useCallback, useRef, useState } from "react";
+
+/**
+ * Options for the useInputHistory hook.
+ */
+export interface UseInputHistoryOptions {
+  /** Maximum number of history entries to keep (default: 100) */
+  maxItems?: number;
+  /** localStorage key for persistence (if provided, history will be persisted) */
+  persistKey?: string;
+}
+
+/**
+ * Return value of useInputHistory hook.
+ */
+export interface UseInputHistoryReturn {
+  /** Read-only array of history entries (newest last) */
+  history: readonly string[];
+  /** Current navigation index (-1 when not navigating) */
+  currentIndex: number;
+  /** Add a new entry to history */
+  addToHistory: (entry: string) => void;
+  /** Navigate up (older) or down (newer) through history */
+  navigateHistory: (direction: "up" | "down") => string | null;
+  /** Clear all history entries */
+  clearHistory: () => void;
+  /** Get the current entry at navigation index */
+  getCurrentEntry: () => string | null;
+}
+
+/**
+ * Load history from storage.
+ */
+function loadFromStorage(key: string): string[] {
+  try {
+    if (typeof globalThis.localStorage !== "undefined") {
+      const stored = globalThis.localStorage.getItem(key);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        if (Array.isArray(parsed)) {
+          return parsed.filter((item): item is string => typeof item === "string");
+        }
+      }
+    }
+  } catch {
+    // Ignore storage errors
+  }
+  return [];
+}
+
+/**
+ * Save history to storage.
+ */
+function saveToStorage(key: string, history: string[]): void {
+  try {
+    if (typeof globalThis.localStorage !== "undefined") {
+      globalThis.localStorage.setItem(key, JSON.stringify(history));
+    }
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+/**
+ * Hook for managing input history with navigation.
+ *
+ * Provides functionality for storing command history, navigating through
+ * previous entries with up/down arrows, and optional persistence.
+ *
+ * @param options - Configuration options
+ * @returns History state and manipulation functions
+ *
+ * @example
+ * ```tsx
+ * function InputComponent() {
+ *   const [input, setInput] = useState('');
+ *   const { navigateHistory, addToHistory } = useInputHistory({ maxItems: 50 });
+ *
+ *   const handleKeyDown = (key: string) => {
+ *     if (key === 'up') {
+ *       const prev = navigateHistory('up');
+ *       if (prev !== null) setInput(prev);
+ *     } else if (key === 'down') {
+ *       const next = navigateHistory('down');
+ *       if (next !== null) setInput(next);
+ *     }
+ *   };
+ *
+ *   const handleSubmit = () => {
+ *     if (input.trim()) {
+ *       addToHistory(input);
+ *       // process input...
+ *       setInput('');
+ *     }
+ *   };
+ *
+ *   return <TextInput value={input} onSubmit={handleSubmit} />;
+ * }
+ * ```
+ */
+export function useInputHistory(options: UseInputHistoryOptions = {}): UseInputHistoryReturn {
+  const { maxItems = 100, persistKey } = options;
+
+  // Initialize history from storage if persistKey provided
+  const [history, setHistory] = useState<string[]>(() => {
+    if (persistKey) {
+      return loadFromStorage(persistKey);
+    }
+    return [];
+  });
+
+  // Current navigation index: -1 means not navigating (at the "new entry" position)
+  const [currentIndex, setCurrentIndex] = useState(-1);
+
+  // Ref to track the temp entry when user starts navigating
+  const tempEntryRef = useRef<string>("");
+
+  /**
+   * Add a new entry to history.
+   * Skips if entry is empty or same as the last entry (no consecutive duplicates).
+   * Resets navigation index.
+   */
+  const addToHistory = useCallback(
+    (entry: string) => {
+      const trimmed = entry.trim();
+      if (!trimmed) {
+        return;
+      }
+
+      setHistory((prev) => {
+        // Skip if same as last entry (no consecutive duplicates)
+        if (prev.length > 0 && prev[prev.length - 1] === trimmed) {
+          return prev;
+        }
+
+        const newHistory = [...prev, trimmed];
+
+        // Trim to maxItems if exceeded
+        const trimmedHistory =
+          newHistory.length > maxItems ? newHistory.slice(-maxItems) : newHistory;
+
+        // Persist if key provided
+        if (persistKey) {
+          saveToStorage(persistKey, trimmedHistory);
+        }
+
+        return trimmedHistory;
+      });
+
+      // Reset navigation index
+      setCurrentIndex(-1);
+      tempEntryRef.current = "";
+    },
+    [maxItems, persistKey]
+  );
+
+  /**
+   * Navigate through history.
+   * 'up' moves to older entries, 'down' moves to newer entries.
+   * Returns the entry at the new position, or null if at boundary.
+   */
+  const navigateHistory = useCallback(
+    (direction: "up" | "down"): string | null => {
+      if (history.length === 0) {
+        return null;
+      }
+
+      let newIndex: number;
+
+      if (direction === "up") {
+        // Moving to older entries
+        if (currentIndex === -1) {
+          // Start navigating from the most recent entry
+          newIndex = history.length - 1;
+        } else if (currentIndex > 0) {
+          // Move to older entry
+          newIndex = currentIndex - 1;
+        } else {
+          // Already at the oldest entry
+          return null;
+        }
+      } else {
+        // direction === 'down'
+        // Moving to newer entries
+        if (currentIndex === -1) {
+          // Not navigating, nothing to do
+          return null;
+        }
+        if (currentIndex < history.length - 1) {
+          // Move to newer entry
+          newIndex = currentIndex + 1;
+        } else {
+          // At the newest entry, return to "new entry" position
+          setCurrentIndex(-1);
+          return tempEntryRef.current || null;
+        }
+      }
+
+      setCurrentIndex(newIndex);
+      return history[newIndex] ?? null;
+    },
+    [history, currentIndex]
+  );
+
+  /**
+   * Clear all history entries.
+   */
+  const clearHistory = useCallback(() => {
+    setHistory([]);
+    setCurrentIndex(-1);
+    tempEntryRef.current = "";
+
+    if (persistKey) {
+      saveToStorage(persistKey, []);
+    }
+  }, [persistKey]);
+
+  /**
+   * Get the current entry at navigation index.
+   * Returns null if not navigating or history is empty.
+   */
+  const getCurrentEntry = useCallback((): string | null => {
+    if (currentIndex === -1 || history.length === 0) {
+      return null;
+    }
+    return history[currentIndex] ?? null;
+  }, [history, currentIndex]);
+
+  return {
+    history,
+    currentIndex,
+    addToHistory,
+    navigateHistory,
+    clearHistory,
+    getCurrentEntry,
+  };
+}

package/src/tui/hooks/useKeyboardScroll.ts

@@ -0,0 +1,209 @@
+/**
+ * Keyboard Scroll Hook
+ *
+ * Handles keyboard events for scrolling in the TUI.
+ * Integrates with useScrollController to provide intuitive keyboard navigation.
+ *
+ * Supported keys:
+ * - PageUp / Ctrl+U: Scroll up half viewport
+ * - PageDown / Ctrl+D: Scroll down half viewport
+ * - Home / Ctrl+Home: Jump to top
+ * - End / Ctrl+End: Jump to bottom (follow mode)
+ * - ↑ / k: Scroll up one line
+ * - ↓ / j: Scroll down one line
+ *
+ * @module tui/hooks/useKeyboardScroll
+ */
+
+import type { Key } from "ink";
+import { useInput } from "ink";
+import { useMemo } from "react";
+import { isEndKey, isHomeKey } from "../types/ink-extended.js";
+import type { ViewportScrollActions, ViewportScrollState } from "./useScrollController.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for useKeyboardScroll hook
+ */
+export interface UseKeyboardScrollOptions {
+  /** Current scroll state from useScrollController */
+  readonly state: ViewportScrollState;
+  /** Scroll actions from useScrollController */
+  readonly actions: ViewportScrollActions;
+  /** Whether keyboard handling is enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Enable vim-style keys (j/k for up/down) (default: true) */
+  readonly vimKeys?: boolean;
+  /** Custom lines per single step (default: 1) */
+  readonly stepLines?: number;
+  /** Custom lines per half-page (default: viewportHeight / 2) */
+  readonly halfPageLines?: number;
+}
+
+/**
+ * Return value of useKeyboardScroll hook
+ */
+export interface UseKeyboardScrollReturn {
+  /** Manual key handler for custom input handling */
+  readonly handleKey: (input: string, key: Key) => boolean;
+  /** Shortcut definitions for help display */
+  readonly shortcuts: ReadonlyArray<KeyboardScrollShortcut>;
+}
+
+/**
+ * Shortcut definition for display
+ */
+export interface KeyboardScrollShortcut {
+  /** Key combination (e.g., "PageUp", "Ctrl+U") */
+  readonly key: string;
+  /** Description of the action */
+  readonly description: string;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Standard shortcuts for help display
+ */
+const SCROLL_SHORTCUTS: ReadonlyArray<KeyboardScrollShortcut> = [
+  { key: "↑/k", description: "Scroll up one line" },
+  { key: "↓/j", description: "Scroll down one line" },
+  { key: "PageUp/Ctrl+U", description: "Scroll up half page" },
+  { key: "PageDown/Ctrl+D", description: "Scroll down half page" },
+  { key: "Home", description: "Jump to top" },
+  { key: "End", description: "Jump to bottom (follow mode)" },
+];
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * useKeyboardScroll - Handles keyboard events for scrolling
+ *
+ * Automatically registers keyboard handlers with useInput when enabled.
+ * Also provides a manual handleKey function for custom input handling.
+ *
+ * @example
+ * ```tsx
+ * const [scrollState, scrollActions] = useScrollController({ viewportHeight: 20 });
+ *
+ * // Automatic keyboard handling
+ * useKeyboardScroll({
+ *   state: scrollState,
+ *   actions: scrollActions,
+ *   enabled: isFocused,
+ * });
+ *
+ * // Or manual handling in existing useInput
+ * const { handleKey } = useKeyboardScroll({
+ *   state: scrollState,
+ *   actions: scrollActions,
+ *   enabled: false, // Don't auto-register
+ * });
+ *
+ * useInput((input, key) => {
+ *   if (handleKey(input, key)) return; // Handled by scroll
+ *   // ... other handlers
+ * });
+ * ```
+ *
+ * @param options - Configuration options
+ * @returns Scroll handling utilities
+ */
+export function useKeyboardScroll(options: UseKeyboardScrollOptions): UseKeyboardScrollReturn {
+  const { state, actions, enabled = true, vimKeys = true, stepLines = 1, halfPageLines } = options;
+
+  // Calculate half-page lines (default to half viewport)
+  const computedHalfPage = halfPageLines ?? Math.max(1, Math.floor(state.viewportHeight / 2));
+
+  // Maximum offset for jump to top
+  const maxOffset = Math.max(0, state.totalHeight - state.viewportHeight);
+
+  /**
+   * Handle a keyboard input, returning true if handled
+   */
+  const handleKey = useMemo(() => {
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Keyboard handler needs many key combinations
+    return (input: string, key: Key): boolean => {
+      // Arrow up or vim 'k'
+      if (key.upArrow || (vimKeys && input === "k")) {
+        actions.scrollUp(stepLines);
+        return true;
+      }
+
+      // Arrow down or vim 'j'
+      if (key.downArrow || (vimKeys && input === "j")) {
+        actions.scrollDown(stepLines);
+        return true;
+      }
+
+      // PageUp (Ink provides this as key.pageUp in some versions)
+      // Also handle Ctrl+U
+      if (key.pageUp || (key.ctrl && input === "u")) {
+        actions.scrollUp(computedHalfPage);
+        return true;
+      }
+
+      // PageDown
+      // Also handle Ctrl+D
+      if (key.pageDown || (key.ctrl && input === "d")) {
+        actions.scrollDown(computedHalfPage);
+        return true;
+      }
+
+      // Home - jump to top
+      if (isHomeKey(input)) {
+        actions.jumpTo(maxOffset);
+        return true;
+      }
+
+      // End - jump to bottom (follow mode)
+      if (isEndKey(input)) {
+        actions.scrollToBottom();
+        return true;
+      }
+
+      return false;
+    };
+  }, [actions, vimKeys, stepLines, computedHalfPage, maxOffset]);
+
+  // Auto-register with useInput when enabled
+  useInput(
+    (input, key) => {
+      handleKey(input, key);
+    },
+    { isActive: enabled }
+  );
+
+  return {
+    handleKey,
+    shortcuts: SCROLL_SHORTCUTS,
+  };
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Format shortcuts for display in help
+ */
+export function formatScrollShortcuts(): string {
+  return SCROLL_SHORTCUTS.map((s) => `${s.key}: ${s.description}`).join("\n");
+}
+
+/**
+ * Get shortcuts without vim keys
+ */
+export function getScrollShortcutsNoVim(): ReadonlyArray<KeyboardScrollShortcut> {
+  return SCROLL_SHORTCUTS.map((shortcut) => ({
+    ...shortcut,
+    key: shortcut.key.replace("/k", "").replace("/j", ""),
+  }));
+}