@butlerw/vellum 0.1.0

package/src/tui/hooks/useFileSuggestions.ts

@@ -0,0 +1,284 @@
+/**
+ * useFileSuggestions Hook
+ *
+ * Provides file and folder suggestions for @ mention autocomplete.
+ * Scans the file system and returns matching suggestions based on partial path input.
+ *
+ * @module tui/hooks/useFileSuggestions
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { useCallback, useEffect, useState } from "react";
+import type { FileSuggestion } from "../components/Input/MentionAutocomplete.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for file suggestions.
+ */
+export interface UseFileSuggestionsOptions {
+  /** Working directory for resolving paths */
+  readonly cwd: string;
+  /** Whether to include files (default: true) */
+  readonly includeFiles?: boolean;
+  /** Whether to include directories (default: true) */
+  readonly includeDirectories?: boolean;
+  /** File extensions to filter (e.g., ['.ts', '.tsx']) */
+  readonly extensions?: readonly string[];
+  /** Maximum number of suggestions */
+  readonly maxSuggestions?: number;
+  /** Debounce delay in ms */
+  readonly debounceMs?: number;
+}
+
+/**
+ * Result of the useFileSuggestions hook.
+ */
+export interface UseFileSuggestionsResult {
+  /** Current file/folder suggestions */
+  readonly suggestions: readonly FileSuggestion[];
+  /** Whether suggestions are loading */
+  readonly loading: boolean;
+  /** Error message if scan failed */
+  readonly error: string | null;
+  /** Refresh suggestions manually */
+  readonly refresh: () => void;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Directories to skip when scanning */
+const SKIP_DIRECTORIES = new Set([
+  "node_modules",
+  ".git",
+  ".svn",
+  ".hg",
+  "__pycache__",
+  ".cache",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".output",
+  "target",
+  "vendor",
+]);
+
+/** Default options */
+const DEFAULT_OPTIONS: Required<Omit<UseFileSuggestionsOptions, "cwd">> = {
+  includeFiles: true,
+  includeDirectories: true,
+  extensions: [],
+  maxSuggestions: 50,
+  debounceMs: 100,
+};
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook to provide file/folder suggestions for a partial path.
+ *
+ * @param partialPath - The partial path entered by the user
+ * @param options - Configuration options
+ * @returns File suggestions, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * const { suggestions, loading } = useFileSuggestions("./src/", {
+ *   cwd: "/project",
+ *   includeFiles: true,
+ *   includeDirectories: true,
+ * });
+ * ```
+ */
+export function useFileSuggestions(
+  partialPath: string,
+  options: UseFileSuggestionsOptions
+): UseFileSuggestionsResult {
+  const [suggestions, setSuggestions] = useState<FileSuggestion[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [refreshTrigger, setRefreshTrigger] = useState(0);
+
+  // Memoize options to avoid recreating object on each render
+  const cwd = options.cwd;
+  const includeFiles = options.includeFiles ?? DEFAULT_OPTIONS.includeFiles;
+  const includeDirectories = options.includeDirectories ?? DEFAULT_OPTIONS.includeDirectories;
+  const extensions = options.extensions ?? DEFAULT_OPTIONS.extensions;
+  const maxSuggestions = options.maxSuggestions ?? DEFAULT_OPTIONS.maxSuggestions;
+  const debounceMs = options.debounceMs ?? DEFAULT_OPTIONS.debounceMs;
+
+  const refresh = useCallback(() => {
+    setRefreshTrigger((prev) => prev + 1);
+  }, []);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: refreshTrigger enables manual refresh
+  useEffect(() => {
+    let cancelled = false;
+    const opts: Required<UseFileSuggestionsOptions> = {
+      cwd,
+      includeFiles,
+      includeDirectories,
+      extensions,
+      maxSuggestions,
+      debounceMs,
+    };
+
+    const timeoutId = setTimeout(async () => {
+      if (cancelled) return;
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await scanForSuggestions(partialPath, opts);
+        if (!cancelled) {
+          setSuggestions(result);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError((err as Error).message);
+          setSuggestions([]);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }, debounceMs);
+
+    return () => {
+      cancelled = true;
+      clearTimeout(timeoutId);
+    };
+  }, [
+    partialPath,
+    cwd,
+    includeFiles,
+    includeDirectories,
+    extensions,
+    maxSuggestions,
+    debounceMs,
+    refreshTrigger,
+  ]);
+
+  return { suggestions, loading, error, refresh };
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/** Parse partial path into scan directory and match prefix */
+function parsePartialPath(partialPath: string): { scanDir: string; matchPrefix: string } {
+  const normalizedPartial = partialPath.replace(/\\/g, "/");
+
+  if (normalizedPartial.endsWith("/") || normalizedPartial === "") {
+    return { scanDir: normalizedPartial || ".", matchPrefix: "" };
+  }
+
+  const lastSlash = normalizedPartial.lastIndexOf("/");
+  if (lastSlash === -1) {
+    return { scanDir: ".", matchPrefix: normalizedPartial };
+  }
+
+  return {
+    scanDir: normalizedPartial.slice(0, lastSlash + 1) || ".",
+    matchPrefix: normalizedPartial.slice(lastSlash + 1),
+  };
+}
+
+/** Check if entry should be included based on filters */
+function shouldIncludeEntry(
+  entry: { name: string; isDirectory: () => boolean },
+  matchPrefix: string,
+  includeFiles: boolean,
+  includeDirectories: boolean,
+  extensions: readonly string[]
+): boolean {
+  const isDir = entry.isDirectory();
+  const lowerName = entry.name.toLowerCase();
+  const lowerPrefix = matchPrefix.toLowerCase();
+
+  // Skip hidden files unless searching for them
+  if (entry.name.startsWith(".") && !matchPrefix.startsWith(".")) return false;
+
+  // Skip ignored directories
+  if (isDir && SKIP_DIRECTORIES.has(entry.name)) return false;
+
+  // Check prefix match
+  if (lowerPrefix && !lowerName.startsWith(lowerPrefix)) return false;
+
+  // Filter by type
+  if (isDir && !includeDirectories) return false;
+  if (!isDir && !includeFiles) return false;
+
+  // Filter by extension (only for files)
+  if (!isDir && extensions.length > 0) {
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!extensions.includes(ext)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Scan for file/folder suggestions based on partial path.
+ */
+async function scanForSuggestions(
+  partialPath: string,
+  options: Required<UseFileSuggestionsOptions>
+): Promise<FileSuggestion[]> {
+  const { cwd, includeFiles, includeDirectories, extensions, maxSuggestions } = options;
+
+  const { scanDir, matchPrefix } = parsePartialPath(partialPath);
+  const fullScanDir = path.resolve(cwd, scanDir);
+
+  // Check if directory exists
+  try {
+    const stats = await fs.stat(fullScanDir);
+    if (!stats.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+
+  // Read and filter directory contents
+  const entries = await fs.readdir(fullScanDir, { withFileTypes: true });
+  const suggestions: FileSuggestion[] = [];
+
+  for (const entry of entries) {
+    if (!shouldIncludeEntry(entry, matchPrefix, includeFiles, includeDirectories, extensions)) {
+      continue;
+    }
+
+    const isDirectory = entry.isDirectory();
+    const fullPath = scanDir === "." ? entry.name : `${scanDir}${entry.name}`;
+
+    suggestions.push({
+      name: entry.name,
+      path: fullPath,
+      isDirectory,
+      extension: isDirectory ? undefined : path.extname(entry.name).slice(1),
+    });
+
+    if (suggestions.length >= maxSuggestions) break;
+  }
+
+  // Sort: directories first, then alphabetically
+  suggestions.sort((a, b) => {
+    if (a.isDirectory !== b.isDirectory) {
+      return a.isDirectory ? -1 : 1;
+    }
+    return a.name.localeCompare(b.name);
+  });
+
+  return suggestions;
+}

package/src/tui/hooks/useFlickerDetector.ts

@@ -0,0 +1,250 @@
+/**
+ * Flicker Detector Hook
+ *
+ * Detects when content exceeds container bounds, which can cause
+ * visual flickering or rendering artifacts in terminal UIs.
+ *
+ * This hook is essential for preventing TUI rendering issues by
+ * detecting overflow conditions before they cause visual problems.
+ *
+ * Ported from Gemini CLI for Vellum TUI.
+ *
+ * @module tui/hooks/useFlickerDetector
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for the flicker detector hook
+ */
+export interface UseFlickerDetectorOptions {
+  /** Height of the content in rows/lines */
+  readonly contentHeight: number;
+  /** Height of the container in rows/lines */
+  readonly containerHeight: number;
+  /**
+   * Threshold in rows before considering content as overflowing.
+   * A small threshold helps prevent edge-case flickering.
+   * @default 0
+   */
+  readonly threshold?: number;
+  /**
+   * Enable debouncing to prevent rapid state changes.
+   * Useful when content height changes frequently.
+   * @default true
+   */
+  readonly debounce?: boolean;
+  /**
+   * Debounce delay in milliseconds.
+   * @default 50
+   */
+  readonly debounceDelay?: number;
+}
+
+/**
+ * Result from the flicker detector hook
+ */
+export interface FlickerDetectorResult {
+  /** Whether the content is overflowing the container */
+  readonly isOverflowing: boolean;
+  /** Amount of overflow in rows (negative if content fits) */
+  readonly overflow: number;
+  /** Percentage of container filled (can exceed 100%) */
+  readonly fillPercentage: number;
+  /** Whether overflow state recently changed (indicates potential flicker) */
+  readonly isTransitioning: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default debounce delay in milliseconds */
+const DEFAULT_DEBOUNCE_DELAY = 50;
+
+/** Transition window for detecting rapid state changes (ms) */
+const TRANSITION_WINDOW = 100;
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook to detect content overflow that may cause visual flickering.
+ *
+ * Terminal UIs can flicker when content rapidly alternates between
+ * fitting and overflowing the visible area. This hook provides:
+ *
+ * 1. **Overflow detection**: Know when content exceeds bounds
+ * 2. **Transition tracking**: Detect rapid state changes
+ * 3. **Debouncing**: Prevent jittery state updates
+ *
+ * @param options - Configuration for overflow detection
+ * @returns Overflow state and metrics
+ *
+ * @example
+ * ```tsx
+ * function MessageList({ messages, containerHeight }) {
+ *   const contentHeight = messages.length * 3; // Estimate 3 rows per message
+ *
+ *   const { isOverflowing, overflow, isTransitioning } = useFlickerDetector({
+ *     contentHeight,
+ *     containerHeight,
+ *     threshold: 2, // Allow 2-row buffer
+ *   });
+ *
+ *   if (isOverflowing) {
+ *     // Enable virtualization or truncation
+ *     return <VirtualizedList data={messages} />;
+ *   }
+ *
+ *   // Render all messages directly
+ *   return messages.map(msg => <Message key={msg.id} {...msg} />);
+ * }
+ * ```
+ */
+export function useFlickerDetector(options: UseFlickerDetectorOptions): FlickerDetectorResult {
+  const {
+    contentHeight,
+    containerHeight,
+    threshold = 0,
+    debounce = true,
+    debounceDelay = DEFAULT_DEBOUNCE_DELAY,
+  } = options;
+
+  // Track the raw overflow state
+  const [debouncedOverflow, setDebouncedOverflow] = useState(() => {
+    return contentHeight - containerHeight > threshold;
+  });
+
+  // Track rapid transitions
+  const [isTransitioning, setIsTransitioning] = useState(false);
+  const lastChangeTime = useRef<number>(0);
+  const transitionTimeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  /**
+   * Calculate raw overflow state (not debounced)
+   */
+  const rawOverflow = useMemo(() => {
+    return contentHeight - containerHeight;
+  }, [contentHeight, containerHeight]);
+
+  const rawIsOverflowing = rawOverflow > threshold;
+
+  /**
+   * Calculate fill percentage
+   */
+  const fillPercentage = useMemo(() => {
+    if (containerHeight <= 0) return 0;
+    return (contentHeight / containerHeight) * 100;
+  }, [contentHeight, containerHeight]);
+
+  /**
+   * Handle state transitions with optional debouncing
+   */
+  const updateOverflowState = useCallback((newState: boolean) => {
+    const now = Date.now();
+    const timeSinceLastChange = now - lastChangeTime.current;
+
+    // Detect rapid transitions (potential flicker source)
+    if (timeSinceLastChange < TRANSITION_WINDOW) {
+      setIsTransitioning(true);
+
+      // Clear existing timeout
+      if (transitionTimeout.current) {
+        clearTimeout(transitionTimeout.current);
+      }
+
+      // Clear transition flag after window
+      transitionTimeout.current = setTimeout(() => {
+        setIsTransitioning(false);
+      }, TRANSITION_WINDOW);
+    }
+
+    lastChangeTime.current = now;
+    setDebouncedOverflow(newState);
+  }, []);
+
+  /**
+   * Effect to update overflow state with optional debouncing
+   */
+  useEffect(() => {
+    if (!debounce) {
+      // No debouncing - update immediately
+      if (rawIsOverflowing !== debouncedOverflow) {
+        updateOverflowState(rawIsOverflowing);
+      }
+      return;
+    }
+
+    // Debounced update
+    const timeoutId = setTimeout(() => {
+      if (rawIsOverflowing !== debouncedOverflow) {
+        updateOverflowState(rawIsOverflowing);
+      }
+    }, debounceDelay);
+
+    return () => {
+      clearTimeout(timeoutId);
+    };
+  }, [rawIsOverflowing, debouncedOverflow, debounce, debounceDelay, updateOverflowState]);
+
+  /**
+   * Cleanup transition timeout on unmount
+   */
+  useEffect(() => {
+    return () => {
+      if (transitionTimeout.current) {
+        clearTimeout(transitionTimeout.current);
+      }
+    };
+  }, []);
+
+  /**
+   * Return memoized result
+   */
+  return useMemo<FlickerDetectorResult>(
+    () => ({
+      isOverflowing: debounce ? debouncedOverflow : rawIsOverflowing,
+      overflow: rawOverflow,
+      fillPercentage,
+      isTransitioning,
+    }),
+    [debounce, debouncedOverflow, rawIsOverflowing, rawOverflow, fillPercentage, isTransitioning]
+  );
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Simple overflow check without the full hook (for one-off calculations).
+ *
+ * @param contentHeight - Height of the content
+ * @param containerHeight - Height of the container
+ * @param threshold - Buffer threshold (default: 0)
+ * @returns Whether content is overflowing
+ */
+export function isContentOverflowing(
+  contentHeight: number,
+  containerHeight: number,
+  threshold = 0
+): boolean {
+  return contentHeight - containerHeight > threshold;
+}
+
+/**
+ * Calculate recommended container height to fit content with buffer.
+ *
+ * @param contentHeight - Height of the content
+ * @param bufferRows - Additional buffer rows (default: 2)
+ * @returns Recommended container height
+ */
+export function calculateSafeContainerHeight(contentHeight: number, bufferRows = 2): number {
+  return contentHeight + bufferRows;
+}