@butlerw/vellum 0.1.0

package/src/tui/components/Banner/Banner.tsx

@@ -0,0 +1,355 @@
+/**
+ * Banner Component
+ *
+ * Main ASCII art banner with gradient colors and shimmer animation.
+ * Features ancient parchment/scroll styling for the Vellum brand.
+ *
+ * @module tui/components/Banner/Banner
+ */
+
+import { Box, Text, useStdout } from "ink";
+import Gradient from "ink-gradient";
+import type React from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useTheme } from "../../theme/index.js";
+import { selectAsciiArt } from "./AsciiArt.js";
+import { interpolateColor } from "./ShimmerText.js";
+import { TypeWriterGradient } from "./TypeWriterGradient.js";
+import { useShimmer } from "./useShimmer.js";
+
+// Note: useShimmer & interpolateColor still used by HeaderBanner
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the Banner component.
+ */
+export interface BannerProps {
+  /** Custom ASCII art override (uses responsive selection by default) */
+  readonly customArt?: string;
+  /** Whether to show version text */
+  readonly showVersion?: boolean;
+  /** Version string to display */
+  readonly version?: string;
+  /** Whether shimmer animation is enabled (default: true) */
+  readonly animated?: boolean;
+  /** Shimmer cycle duration in milliseconds (default: 3000) */
+  readonly cycleDuration?: number;
+  /** Shimmer update interval in milliseconds (default: 100) */
+  readonly updateInterval?: number;
+  /** Callback when banner fade-out completes */
+  readonly onComplete?: () => void;
+  /** Duration to display before fading (ms, default: 2000) */
+  readonly displayDuration?: number;
+  /** Whether to auto-hide after displayDuration */
+  readonly autoHide?: boolean;
+  /** Number of animation cycles before stopping (default: infinite) */
+  readonly cycles?: number;
+  /** Whether to show typewriter effect on startup (default: true) */
+  readonly typewriter?: boolean;
+  /** Typewriter speed: lines/sec for line mode, chars/sec for char mode (default: 50 lines/sec) */
+  readonly typewriterSpeed?: number;
+  /** Typewriter mode: 'line' reveals whole lines, 'char' reveals characters (default: 'line') */
+  readonly typewriterMode?: "line" | "char";
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Interpolated steps per gradient segment for smoother shimmer shifts. */
+const GRADIENT_STEPS_PER_SEGMENT = 12;
+
+/**
+ * Build gradient steps from theme brand colors.
+ * Used for shimmer animation in HeaderBanner.
+ */
+function buildGradientSteps(colors: readonly string[], stepsPerSegment: number): string[] {
+  if (colors.length === 0) return [];
+  if (colors.length === 1) return [colors[0] ?? "#000000"];
+
+  const steps: string[] = [];
+
+  for (let i = 0; i < colors.length - 1; i += 1) {
+    const start = colors[i] ?? "#000000";
+    const end = colors[i + 1] ?? start;
+    for (let step = 0; step < stepsPerSegment; step += 1) {
+      const t = step / stepsPerSegment;
+      steps.push(interpolateColor(start, end, t));
+    }
+  }
+
+  steps.push(colors[colors.length - 1] ?? "#000000");
+  return steps;
+}
+
+/**
+ * Get parchment gradient colors from theme brand.
+ * Returns a mutable array for compatibility with ink-gradient.
+ */
+function getParchmentGradient(brand: {
+  accent: string;
+  mid: string;
+  secondary: string;
+  primary: string;
+  highlight: string;
+  light: string;
+}): string[] {
+  return [
+    brand.accent, // Saddle Brown
+    brand.mid, // Sienna
+    brand.secondary, // Peru
+    brand.primary, // Goldenrod
+    brand.highlight, // Gold
+    brand.light, // Lemon Chiffon
+  ];
+}
+
+// =============================================================================
+// Sub-Components
+// =============================================================================
+
+/**
+ * Static version display.
+ */
+interface VersionDisplayProps {
+  readonly version: string;
+  readonly brand: {
+    accent: string;
+    secondary: string;
+    primary: string;
+  };
+}
+
+function VersionDisplay({ version, brand }: VersionDisplayProps): React.JSX.Element {
+  return (
+    <Box marginTop={1} justifyContent="center">
+      <Text color={brand.accent}>v{version}</Text>
+      <Text color={brand.secondary}> | </Text>
+      <Text color={brand.primary} italic>
+        AI-Powered Coding Assistant
+      </Text>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * Banner displays the Vellum ASCII art logo with gradient and shimmer effects.
+ *
+ * Features:
+ * - Responsive ASCII art selection based on terminal width
+ * - Smooth gradient colors (brown to gold parchment theme)
+ * - Animated shimmer sweep effect
+ * - Optional version display
+ * - Auto-hide capability with callback
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Banner />
+ *
+ * // With version and auto-hide
+ * <Banner
+ *   showVersion
+ *   version="1.0.0"
+ *   autoHide
+ *   displayDuration={3000}
+ *   onComplete={() => setShowBanner(false)}
+ * />
+ * ```
+ */
+export function Banner({
+  customArt,
+  showVersion = false,
+  version = "0.1.0",
+  // Note: animated, cycleDuration, updateInterval, cycles kept for API compat
+  // but shimmer effect is removed - typing goes directly to static gradient
+  onComplete,
+  displayDuration = 2000,
+  autoHide = false,
+  typewriter = true,
+  typewriterSpeed,
+  typewriterMode = "char",
+}: BannerProps): React.JSX.Element | null {
+  const { stdout } = useStdout();
+  const { theme } = useTheme();
+  const [visible, setVisible] = useState(true);
+  const [opacity, setOpacity] = useState(1);
+  const [typingComplete, setTypingComplete] = useState(!typewriter);
+
+  // Refs for nested timer cleanup
+  const step1Ref = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const step2Ref = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Get gradient colors from theme
+  const parchmentGradient = useMemo(() => getParchmentGradient(theme.brand), [theme.brand]);
+
+  // Get terminal dimensions for responsive art selection
+  const terminalWidth = stdout?.columns ?? 80;
+
+  // Select appropriate ASCII art
+  const asciiArt = useMemo(() => {
+    return customArt ?? selectAsciiArt(terminalWidth);
+  }, [customArt, terminalWidth]);
+
+  // Auto-calculate typewriter speed if not provided
+  // Target: typing completes at 80% of displayDuration for comfortable viewing
+  const autoTypewriterSpeed = useMemo(() => {
+    if (typewriterSpeed !== undefined) return typewriterSpeed;
+    const charCount = asciiArt.length;
+    const typingTimeMs = displayDuration * 0.8; // 80% of display time
+    const typingTimeSec = typingTimeMs / 1000;
+    // Calculate chars/sec, minimum 500 to avoid being too slow
+    return Math.max(500, Math.ceil(charCount / typingTimeSec));
+  }, [typewriterSpeed, asciiArt.length, displayDuration]);
+
+  // Auto-hide timer with smooth transition
+  useEffect(() => {
+    if (!autoHide) return;
+
+    // Use simple timeout - start hiding 300ms before end for quicker transition
+    const hideTimer = setTimeout(() => {
+      // Quick fade: 0.7 -> 0 in 300ms total
+      setOpacity(0.7);
+
+      step1Ref.current = setTimeout(() => {
+        setOpacity(0.3);
+      }, 100);
+
+      step2Ref.current = setTimeout(() => {
+        setOpacity(0);
+        setVisible(false);
+        onComplete?.();
+      }, 200);
+    }, displayDuration - 300);
+
+    return () => {
+      clearTimeout(hideTimer);
+      if (step1Ref.current) clearTimeout(step1Ref.current);
+      if (step2Ref.current) clearTimeout(step2Ref.current);
+    };
+  }, [autoHide, displayDuration, onComplete]);
+
+  if (!visible) return null;
+
+  // Determine which phase we're in: typing or static gradient (no shimmer)
+  const isTypingPhase = typewriter && !typingComplete;
+
+  return (
+    <Box
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      paddingX={1}
+      paddingY={1}
+    >
+      {isTypingPhase ? (
+        <TypeWriterGradient
+          text={asciiArt}
+          speed={autoTypewriterSpeed}
+          colors={parchmentGradient}
+          showCursor
+          mode={typewriterMode}
+          onComplete={() => setTypingComplete(true)}
+        />
+      ) : (
+        <Gradient colors={parchmentGradient}>{asciiArt}</Gradient>
+      )}
+
+      {showVersion && version ? <VersionDisplay version={version} brand={theme.brand} /> : null}
+
+      {/* Loading indicator - hide when fading out */}
+      {opacity >= 0.5 && (
+        <Box marginTop={1}>
+          <Text color={theme.brand.accent}>Initializing...</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * Compact banner for narrow terminals or inline use.
+ */
+export function CompactBanner(): React.JSX.Element {
+  const { theme } = useTheme();
+  const parchmentGradient = useMemo(() => getParchmentGradient(theme.brand), [theme.brand]);
+  return (
+    <Box>
+      <Gradient colors={parchmentGradient}>{"◇ VELLUM ◇"}</Gradient>
+    </Box>
+  );
+}
+
+/**
+ * Minimal text-only banner.
+ */
+export function MinimalBanner(): React.JSX.Element {
+  const { theme } = useTheme();
+  return (
+    <Text color={theme.brand.primary} bold>
+      VELLUM
+    </Text>
+  );
+}
+
+// =============================================================================
+// Header Banner (Compact CLI Header)
+// =============================================================================
+
+/**
+ * Props for the HeaderBanner component.
+ */
+export interface HeaderBannerProps {
+  /** Whether shimmer animation is enabled (default: true) */
+  readonly animated?: boolean;
+}
+
+/**
+ * Compact header banner with animated gradient for use at CLI top.
+ * Displays a single-line parchment-styled logo with continuous shimmer.
+ */
+export function HeaderBanner({ animated = true }: HeaderBannerProps): React.JSX.Element {
+  const { theme } = useTheme();
+  const { position } = useShimmer({
+    cycleDuration: 3000,
+    enabled: animated,
+  });
+
+  // Get gradient colors from theme
+  const parchmentGradient = useMemo(() => getParchmentGradient(theme.brand), [theme.brand]);
+
+  // Build gradient steps for shimmer animation
+  const gradientSteps = useMemo(
+    () => buildGradientSteps(parchmentGradient, GRADIENT_STEPS_PER_SEGMENT),
+    [parchmentGradient]
+  );
+
+  // Calculate discrete color shift to reduce re-computation
+  const colorShift = Math.floor(position * gradientSteps.length) % gradientSteps.length;
+
+  // Shift gradient colors based on discrete colorShift value
+  const shiftedColors = useMemo(() => {
+    if (colorShift === 0) return gradientSteps;
+    return [...gradientSteps.slice(colorShift), ...gradientSteps.slice(0, colorShift)];
+  }, [colorShift, gradientSteps]);
+
+  // Compact ASCII art for header (single line with decorations)
+  const headerArt = "═══╣ ◊ ╠═══  V E L L U M  ═══╣ ◊ ╠═══";
+
+  return (
+    <Box justifyContent="center" width="100%">
+      {animated ? (
+        <Gradient colors={shiftedColors}>{headerArt}</Gradient>
+      ) : (
+        <Gradient colors={parchmentGradient}>{headerArt}</Gradient>
+      )}
+    </Box>
+  );
+}

package/src/tui/components/Banner/ShimmerContext.tsx

@@ -0,0 +1,131 @@
+/**
+ * ShimmerContext - Shared shimmer state provider
+ *
+ * Provides a single shared shimmer timer for all consumers,
+ * eliminating multiple independent timers that can cause animation flickering.
+ *
+ * @module tui/components/Banner/ShimmerContext
+ */
+
+import { createContext, type ReactNode, useContext } from "react";
+import { type ShimmerState, useShimmer } from "./useShimmer.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Context value extends ShimmerState for shared shimmer state
+ */
+type ShimmerContextValue = ShimmerState;
+
+// =============================================================================
+// Context
+// =============================================================================
+
+/**
+ * Default shimmer context value (inactive state)
+ */
+const defaultShimmerValue: ShimmerContextValue = {
+  position: 0,
+  intensity: 0,
+  cycleCount: 0,
+  isComplete: false,
+  isActive: false,
+  pause: () => {},
+  resume: () => {},
+};
+
+const ShimmerContext = createContext<ShimmerContextValue>(defaultShimmerValue);
+
+// =============================================================================
+// Provider
+// =============================================================================
+
+/**
+ * Props for the ShimmerProvider component.
+ */
+export interface ShimmerProviderProps {
+  /** Child components that will share the shimmer state */
+  readonly children: ReactNode;
+  /** Whether shimmer animation is enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Maximum number of cycles before stopping (undefined = infinite) */
+  readonly maxCycles?: number;
+  /** Duration of one complete shimmer cycle in milliseconds (default: 3000) */
+  readonly cycleDuration?: number;
+  /** Update interval in milliseconds (default: 100 for smoother motion) */
+  readonly updateInterval?: number;
+  /** Callback when max cycles completed */
+  readonly onComplete?: () => void;
+}
+
+/**
+ * ShimmerProvider creates a single shared shimmer timer for all child components.
+ *
+ * Use this to wrap multiple shimmer-consuming components to ensure they all
+ * animate in sync and share a single timer instead of each running their own.
+ *
+ * @example
+ * ```tsx
+ * <ShimmerProvider enabled maxCycles={3} cycleDuration={3000}>
+ *   <Banner />
+ *   <HeaderBanner />
+ *   <Header />
+ * </ShimmerProvider>
+ * ```
+ */
+export function ShimmerProvider({
+  children,
+  enabled = true,
+  maxCycles,
+  cycleDuration = 3000,
+  updateInterval = 100,
+  onComplete,
+}: ShimmerProviderProps): React.JSX.Element {
+  const shimmer = useShimmer({
+    enabled,
+    maxCycles,
+    cycleDuration,
+    updateInterval,
+    onComplete,
+  });
+
+  return <ShimmerContext.Provider value={shimmer}>{children}</ShimmerContext.Provider>;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook to access shared shimmer state from ShimmerProvider.
+ *
+ * If used outside a ShimmerProvider, returns default inactive state.
+ * For standalone shimmer (not sharing timer), use useShimmer() directly instead.
+ *
+ * @example
+ * ```tsx
+ * function AnimatedComponent() {
+ *   const { position, intensity, isComplete } = useSharedShimmer();
+ *   // Use position (0-1) and intensity (0-1) for animation
+ * }
+ * ```
+ */
+export function useSharedShimmer(): ShimmerContextValue {
+  return useContext(ShimmerContext);
+}
+
+/**
+ * Hook to check if component is inside a ShimmerProvider.
+ * Useful for components that want to optionally use shared state.
+ */
+export function useIsInShimmerProvider(): boolean {
+  const context = useContext(ShimmerContext);
+  // Check if we have the actual shimmer functions (not default no-ops)
+  return (
+    context.isActive !== defaultShimmerValue.isActive ||
+    context.position !== defaultShimmerValue.position ||
+    context.cycleCount !== defaultShimmerValue.cycleCount
+  );
+}

package/src/tui/components/Banner/ShimmerText.tsx

@@ -0,0 +1,193 @@
+/**
+ * ShimmerText Component for Banner
+ *
+ * Renders text with a flowing shimmer/glow effect.
+ * Uses the useShimmer hook for animation state.
+ *
+ * @module tui/components/Banner/ShimmerText
+ */
+
+import { Text } from "ink";
+import React, { useMemo } from "react";
+import { calculateShimmerIntensity, type ShimmerConfig, useShimmer } from "./useShimmer.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the BannerShimmerText component.
+ */
+export interface BannerShimmerTextProps {
+  /** Text content to display with shimmer effect */
+  readonly children: string;
+  /** Base color (default: '#8B4513' - saddle brown) */
+  readonly baseColor?: string;
+  /** Highlight color for shimmer peak (default: '#FFD700' - gold) */
+  readonly highlightColor?: string;
+  /** Shimmer animation configuration */
+  readonly shimmerConfig?: ShimmerConfig;
+  /** Whether shimmer is enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Width of the shimmer effect (0-1, default: 0.15) */
+  readonly shimmerWidth?: number;
+  /** Whether text should be bold */
+  readonly bold?: boolean;
+}
+
+// =============================================================================
+// Color Interpolation
+// =============================================================================
+
+/**
+ * Parse hex color to RGB components.
+ */
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const cleaned = hex.replace("#", "");
+  const bigint = parseInt(cleaned, 16);
+  return {
+    r: (bigint >> 16) & 255,
+    g: (bigint >> 8) & 255,
+    b: bigint & 255,
+  };
+}
+
+/**
+ * Convert RGB to hex string.
+ */
+function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (n: number) => Math.round(n).toString(16).padStart(2, "0");
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+/**
+ * Interpolate between two colors based on intensity (0-1).
+ */
+export function interpolateColor(
+  baseColor: string,
+  highlightColor: string,
+  intensity: number
+): string {
+  const base = hexToRgb(baseColor);
+  const highlight = hexToRgb(highlightColor);
+
+  const r = base.r + (highlight.r - base.r) * intensity;
+  const g = base.g + (highlight.g - base.g) * intensity;
+  const b = base.b + (highlight.b - base.b) * intensity;
+
+  return rgbToHex(r, g, b);
+}
+
+// =============================================================================
+// Character-Level Shimmer Component
+// =============================================================================
+
+/**
+ * Single character with shimmer color applied.
+ * Memoized to prevent unnecessary re-renders.
+ */
+interface ShimmerCharProps {
+  readonly char: string;
+  readonly color: string;
+  readonly bold?: boolean;
+}
+
+const ShimmerChar = React.memo(function ShimmerChar({
+  char,
+  color,
+  bold,
+}: ShimmerCharProps): React.JSX.Element {
+  return (
+    <Text color={color} bold={bold}>
+      {char}
+    </Text>
+  );
+});
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * BannerShimmerText renders text with a flowing shimmer effect.
+ *
+ * The shimmer sweeps from left to right, creating a glow effect
+ * that transitions from the base color to the highlight color.
+ *
+ * @example
+ * ```tsx
+ * <BannerShimmerText
+ *   baseColor="#8B4513"
+ *   highlightColor="#FFD700"
+ * >
+ *   VELLUM
+ * </BannerShimmerText>
+ * ```
+ */
+export function BannerShimmerText({
+  children,
+  baseColor = "#8B4513",
+  highlightColor = "#FFD700",
+  shimmerConfig,
+  enabled = true,
+  shimmerWidth = 0.15,
+  bold = false,
+}: BannerShimmerTextProps): React.JSX.Element {
+  const { position } = useShimmer({
+    ...shimmerConfig,
+    enabled,
+  });
+
+  // Calculate color for each character based on shimmer position
+  const coloredChars = useMemo(() => {
+    const chars = children.split("");
+    const totalChars = chars.length;
+
+    return chars.map((char, index) => {
+      // Skip whitespace - render as-is
+      if (char === " " || char === "\n" || char === "\t") {
+        return { char, color: baseColor, isWhitespace: true };
+      }
+
+      const intensity = calculateShimmerIntensity(index, totalChars, position, shimmerWidth);
+
+      const color = interpolateColor(baseColor, highlightColor, intensity);
+      return { char, color, isWhitespace: false };
+    });
+  }, [children, position, baseColor, highlightColor, shimmerWidth]);
+
+  return (
+    <Text>
+      {coloredChars.map((item, index) => (
+        <ShimmerChar
+          key={`${index}-${item.char}`}
+          char={item.char}
+          color={item.isWhitespace ? baseColor : item.color}
+          bold={bold}
+        />
+      ))}
+    </Text>
+  );
+}
+
+/**
+ * Multi-line shimmer text that processes each line.
+ */
+export interface MultiLineShimmerProps extends Omit<BannerShimmerTextProps, "children"> {
+  /** Lines of text to render */
+  readonly lines: string[];
+}
+
+export function MultiLineShimmer({ lines, ...props }: MultiLineShimmerProps): React.JSX.Element {
+  return (
+    <>
+      {lines.map((line, index) => (
+        // Using index as key is acceptable here since lines array is static and order never changes
+        // biome-ignore lint/suspicious/noArrayIndexKey: lines are static banner content that never reorders
+        <BannerShimmerText key={index} {...props}>
+          {line}
+        </BannerShimmerText>
+      ))}
+    </>
+  );
+}