@ranker/raxflow 0.2.0

package/src/tui/components/animations/Spinner.tsx

@@ -0,0 +1,54 @@
+import React, { memo, useMemo } from "react";
+import { Text } from "ink";
+import { useAnimation } from "../../hooks/useAnimation.js";
+import { tuiColors } from "../../styles/index.js";
+
+export type SpinnerType = "dots" | "circle" | "pulse" | "brackets" | "arrows" | "hamburger" | "grow";
+
+const SPINNER_FRAMES: Record<SpinnerType, string[]> = {
+  dots: ["⠋", "⠙", "⠹", "⠸", "⼸", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  circle: ["◐", "◓", "◑", "◒"],
+  pulse: ["●", "◐", "○", "◐"],
+  brackets: ["[          ]", "[=         ]", "[==        ]", "[===       ]", "[====      ]", "[=====     ]", "[======    ]", "[=======   ]", "[========  ]", "[========= ]", "[==========]", "[ =========]", "[  ========]", "[   =======]", "[    ======]", "[     =====]", "[      ====]", "[       ===]", "[        ==]", "[         =]"],
+  arrows: ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"],
+  hamburger: ["☰", "☱", "ěr", "☳", "☴", "pě", "☲", "☶"],
+  grow: ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█", "▇", "▆", "▅", "▄", "▃", "▂"],
+};
+
+const DEFAULT_INTERVALS: Record<SpinnerType, number> = {
+  dots: 100,
+  circle: 120,
+  pulse: 200,
+  brackets: 80,
+  arrows: 100,
+  hamburger: 150,
+  grow: 100,
+};
+
+interface SpinnerProps {
+  type?: SpinnerType;
+  interval?: number;
+  color?: string;
+  isAnimating?: boolean;
+}
+
+export const Spinner = memo(function Spinner({ 
+  type = "dots", 
+  interval, 
+  color = tuiColors.primary, 
+  isAnimating = true 
+}: SpinnerProps) {
+  const frames = SPINNER_FRAMES[type];
+  const actualInterval = interval ?? DEFAULT_INTERVALS[type];
+  const { frame } = useAnimation({ interval: actualInterval, loop: true, autoStart: isAnimating, maxFps: 20 });
+  const currentFrame = frames[frame % frames.length];
+
+  return <Text color={color}>{currentFrame}</Text>;
+});
+
+export function useSpinnerFrame(type: SpinnerType = "dots", tick: number): string {
+  const frames = SPINNER_FRAMES[type];
+  return frames[tick % frames.length];
+}
+
+export const spinnerTypes = Object.keys(SPINNER_FRAMES) as SpinnerType[];

package/src/tui/components/animations/StatusAnimator.tsx

@@ -0,0 +1,153 @@
+import React, { useState, useEffect, memo, useRef } from "react";
+import { Box, Text } from "ink";
+import { tuiColors, getStatusIndicator } from "../../styles/index.js";
+import { useAnimation } from "../../hooks/useAnimation.js";
+
+export type TransitionStatus = "entering" | "active" | "exiting" | "hidden";
+
+interface StatusAnimatorProps {
+  status: "pending" | "running" | "done" | "error" | "idle" | "queued";
+  label?: string;
+  showLabel?: boolean;
+  transitionDuration?: number;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  pending: tuiColors.textTertiary,
+  queued: tuiColors.warning,
+  running: tuiColors.primary,
+  done: tuiColors.success,
+  error: tuiColors.error,
+  idle: tuiColors.textQuaternary,
+};
+
+const RUNNING_FRAMES = ["◐", "◓", "◑", "◒"];
+const TRANSITION_FRAMES = ["○", "◐", "◓", "●"];
+const EXIT_FRAMES = ["●", "◑", "◒", "○"];
+
+const STATUS_ORDER = ["pending", "queued", "running", "done", "error", "idle"];
+
+function getStatusColor(status: string): string {
+  return STATUS_COLORS[status] || tuiColors.textTertiary;
+}
+
+export const StatusAnimator = memo(function StatusAnimator({
+  status,
+  label,
+  showLabel = true,
+  transitionDuration = 500,
+}: StatusAnimatorProps) {
+  const [displayStatus, setDisplayStatus] = useState(status);
+  const [isTransitioning, setIsTransitioning] = useState(false);
+  const [transitionFrame, setTransitionFrame] = useState(0);
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  const { frame } = useAnimation({ interval: 100, loop: true, maxFps: 15 });
+
+  useEffect(() => {
+    if (status !== displayStatus) {
+      setIsTransitioning(true);
+      timeoutRef.current = setTimeout(() => {
+        setDisplayStatus(status);
+        setIsTransitioning(false);
+      }, transitionDuration);
+      return () => {
+        if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      };
+    }
+  }, [status, displayStatus, transitionDuration]);
+
+  const getAnimatedIcon = (): string => {
+    if (status === "running") {
+      return RUNNING_FRAMES[frame % RUNNING_FRAMES.length];
+    }
+
+    if (isTransitioning) {
+      const frames = STATUS_ORDER.indexOf(status) > STATUS_ORDER.indexOf(displayStatus) 
+        ? TRANSITION_FRAMES 
+        : EXIT_FRAMES;
+      return frames[transitionFrame % frames.length];
+    }
+
+    const statusInfo = getStatusIndicator(displayStatus);
+    return statusInfo.icon;
+  };
+
+  const color = getStatusColor(status);
+
+  return (
+    <Box flexDirection="row">
+      <Text color={color}>{getAnimatedIcon()}</Text>
+      {showLabel && label && (
+        <Text color={color}> {label}</Text>
+      )}
+      {showLabel && !label && (
+        <Text color={tuiColors.textSecondary}> [{status.toUpperCase()}]</Text>
+      )}
+    </Box>
+  );
+});
+
+interface MetricPulseProps {
+  value: number | string;
+  label: string;
+  unit?: string;
+  threshold?: { warning: number; critical: number };
+  isHighlighted?: boolean;
+}
+
+export const MetricPulse = memo(function MetricPulse({ 
+  value, 
+  label, 
+  unit, 
+  threshold, 
+  isHighlighted 
+}: MetricPulseProps) {
+  const { frame } = useAnimation({ interval: 200, loop: true, maxFps: 10 });
+  const numValue = typeof value === "number" ? value : parseFloat(value) || 0;
+
+  let color = tuiColors.success;
+  if (threshold) {
+    if (numValue >= threshold.critical) color = tuiColors.error;
+    else if (numValue >= threshold.warning) color = tuiColors.warning;
+  }
+
+  return (
+    <Box flexDirection="row">
+      <Text color={tuiColors.textTertiary}>{label}:</Text>
+      <Text color={color} bold={isHighlighted}> {value}{unit || ""}</Text>
+    </Box>
+  );
+});
+
+interface FitnessAnimatorProps {
+  value: number;
+  previousValue?: number;
+}
+
+export const FitnessAnimator = memo(function FitnessAnimator({ value, previousValue }: FitnessAnimatorProps) {
+  const { frame } = useAnimation({ interval: 150, loop: true, maxFps: 12 });
+  const diff = previousValue !== undefined ? value - previousValue : 0;
+  const isImproving = diff > 0;
+  const isDeclining = diff < 0;
+
+  let color = tuiColors.success;
+  if (value >= 0.9) color = tuiColors.success;
+  else if (value >= 0.7) color = tuiColors.warning;
+  else color = tuiColors.error;
+
+  const frames = ["●", "◐", "●", "◐"];
+  const animFrame = (isImproving || isDeclining) ? frames[frame % frames.length] : "●";
+
+  const statusLabel = value >= 0.9 ? "OPTIMAL" : value >= 0.7 ? "GOOD" : "IMPROVING";
+
+  return (
+    <Box flexDirection="row">
+      <Text color={tuiColors.textTertiary}>Fitness:</Text>
+      <Text color={color} bold> {value.toFixed(2)}</Text>
+      <Text color={tuiColors.textTertiary}> [{statusLabel}]</Text>
+      {isImproving && <Text color={tuiColors.success}> ↑</Text>}
+      {isDeclining && <Text color={tuiColors.error}> ↓</Text>}
+    </Box>
+  );
+});

package/src/tui/components/animations/TypingEffect.tsx

@@ -0,0 +1,119 @@
+import React, { useState, useEffect, memo, useRef } from "react";
+import { Box, Text } from "ink";
+import { tuiColors } from "../../styles/index.js";
+import { Spinner } from "./Spinner.js";
+
+interface TypingEffectProps {
+  text: string;
+  speed?: number;
+  color?: string;
+  showCursor?: boolean;
+  cursorChar?: string;
+  onComplete?: () => void;
+  isAnimating?: boolean;
+  prefix?: string;
+}
+
+export const TypingEffect = memo(function TypingEffect({
+  text,
+  speed = 30,
+  color = tuiColors.textPrimary,
+  showCursor = true,
+  cursorChar = "█",
+  onComplete,
+  isAnimating = true,
+  prefix,
+}: TypingEffectProps) {
+  const [displayedChars, setDisplayedChars] = useState(0);
+  const [isComplete, setIsComplete] = useState(false);
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
+  useEffect(() => {
+    if (!isAnimating) {
+      setDisplayedChars(text.length);
+      setIsComplete(true);
+      return;
+    }
+
+    if (displayedChars >= text.length) {
+      if (!isComplete) {
+        setIsComplete(true);
+        onCompleteRef.current?.();
+      }
+      return;
+    }
+
+    timeoutRef.current = setTimeout(() => {
+      setDisplayedChars((prev) => prev + 1);
+    }, speed);
+
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, [displayedChars, text.length, speed, isComplete, isAnimating]);
+
+  const displayedText = text.slice(0, displayedChars);
+
+  return (
+    <Box flexDirection="row">
+      {prefix && <Text color={tuiColors.textTertiary}>{prefix}</Text>}
+      <Text color={color}>{displayedText}</Text>
+      {showCursor && !isComplete && <Text color={tuiColors.primary}>{cursorChar}</Text>}
+    </Box>
+  );
+});
+
+interface TypewriterMessageProps {
+  text: string;
+  speed?: number;
+  color?: string;
+  isComplete?: boolean;
+}
+
+export const TypewriterMessage = memo(function TypewriterMessage({ 
+  text, 
+  speed = 20, 
+  color = tuiColors.textPrimary, 
+  isComplete 
+}: TypewriterMessageProps) {
+  const [displayedChars, setDisplayedChars] = useState(0);
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    if (isComplete) {
+      setDisplayedChars(text.length);
+      return;
+    }
+
+    if (displayedChars >= text.length) return;
+
+    timeoutRef.current = setTimeout(() => {
+      setDisplayedChars((prev) => prev + 1);
+    }, speed);
+
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, [displayedChars, text.length, speed, isComplete]);
+
+  return <Text color={color}>{text.slice(0, displayedChars)}</Text>;
+});
+
+interface ProcessingIndicatorProps {
+  text?: string;
+  color?: string;
+}
+
+export const ProcessingIndicator = memo(function ProcessingIndicator({ 
+  text = "Processing", 
+  color = tuiColors.warning 
+}: ProcessingIndicatorProps) {
+  return (
+    <Box flexDirection="row">
+      <Spinner type="dots" color={color} />
+      <Text color={color}> {text}...</Text>
+    </Box>
+  );
+});

package/src/tui/components/animations/index.ts

@@ -0,0 +1,16 @@
+export { Spinner, useSpinnerFrame, spinnerTypes } from "./Spinner.js";
+export type { SpinnerType } from "./Spinner.js";
+
+export { Pulse, StatusPulse, usePulseFrame, usePulseIntensity } from "./Pulse.js";
+
+export { TypingEffect, TypewriterMessage, ProcessingIndicator } from "./TypingEffect.js";
+
+export { StatusAnimator, MetricPulse, FitnessAnimator } from "./StatusAnimator.js";
+export type { TransitionStatus } from "./StatusAnimator.js";
+
+export { 
+  AnimatedProgressBar, 
+  ProgressWithLabel, 
+  SegmentedProgress, 
+  WorkflowProgress 
+} from "./ProgressBar.js";

package/src/tui/hooks/useAnimation.ts

@@ -0,0 +1,290 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+
+export interface AnimationOptions {
+  interval?: number;
+  loop?: boolean;
+  autoStart?: boolean;
+  totalFrames?: number;
+  maxFps?: number;
+  pauseOnHidden?: boolean;
+}
+
+export interface AnimationState {
+  frame: number;
+  tick: number;
+  isAnimating: boolean;
+  progress: number;
+  start: () => void;
+  stop: () => void;
+  reset: () => void;
+  toggle: () => void;
+}
+
+const DEFAULT_FPS_LIMIT = 24;
+const FRAME_SKIP_THRESHOLD = 2;
+
+export function useAnimation(options: AnimationOptions = {}): AnimationState {
+  const {
+    interval = 100,
+    loop = true,
+    autoStart = true,
+    totalFrames = 100,
+    maxFps = DEFAULT_FPS_LIMIT,
+    pauseOnHidden = true,
+  } = options;
+
+  const [frame, setFrame] = useState(0);
+  const [isAnimating, setIsAnimating] = useState(autoStart);
+  const intervalRef = useRef<NodeJS.Timeout | null>(null);
+  const lastFrameTimeRef = useRef<number>(0);
+  const frameCountRef = useRef<number>(0);
+  const isHiddenRef = useRef<boolean>(false);
+
+  useEffect(() => {
+    if (!pauseOnHidden || typeof document === "undefined") return;
+    
+    const handleVisibility = () => {
+      isHiddenRef.current = document.hidden;
+    };
+    
+    document.addEventListener("visibilitychange", handleVisibility);
+    return () => document.removeEventListener("visibilitychange", handleVisibility);
+  }, [pauseOnHidden]);
+
+  const start = useCallback(() => {
+    setIsAnimating(true);
+  }, []);
+
+  const stop = useCallback(() => {
+    setIsAnimating(false);
+  }, []);
+
+  const reset = useCallback(() => {
+    setFrame(0);
+    frameCountRef.current = 0;
+    lastFrameTimeRef.current = 0;
+  }, []);
+
+  const toggle = useCallback(() => {
+    setIsAnimating((prev) => !prev);
+  }, []);
+
+  useEffect(() => {
+    if (!isAnimating) {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+      return;
+    }
+
+    const minFrameTime = 1000 / maxFps;
+    
+    intervalRef.current = setInterval(() => {
+      if (pauseOnHidden && isHiddenRef.current) return;
+      
+      const now = performance.now();
+      const elapsed = now - lastFrameTimeRef.current;
+      
+      if (elapsed < minFrameTime) return;
+      
+      const framesToSkip = Math.floor(elapsed / interval) - 1;
+      const shouldSkipFrame = framesToSkip > FRAME_SKIP_THRESHOLD;
+      
+      if (shouldSkipFrame) {
+        frameCountRef.current += framesToSkip;
+      }
+      
+      lastFrameTimeRef.current = now;
+      frameCountRef.current++;
+      
+      setFrame((prev) => {
+        if (loop) {
+          return prev + 1;
+        }
+        return prev >= totalFrames - 1 ? prev : prev + 1;
+      });
+    }, interval);
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    };
+  }, [isAnimating, interval, loop, totalFrames, maxFps, pauseOnHidden]);
+
+  const progress = totalFrames > 0 ? (frame % totalFrames) / totalFrames : 0;
+
+  return {
+    frame,
+    tick: frame,
+    isAnimating,
+    progress,
+    start,
+    stop,
+    reset,
+    toggle,
+  };
+}
+
+export function usePulse(interval: number = 2000): { intensity: number; frame: number } {
+  const { frame } = useAnimation({ interval: 100, loop: true, maxFps: 15 });
+  const intensity = 0.5 + Math.sin((frame * 100 / interval) * Math.PI * 2) * 0.5;
+  return { intensity, frame };
+}
+
+export function useTypewriter(
+  text: string,
+  speed: number = 50,
+  startDelay: number = 0
+): { displayedText: string; isComplete: boolean; restart: () => void } {
+  const [displayedChars, setDisplayedChars] = useState(0);
+  const [isStarted, setIsStarted] = useState(false);
+  const [isComplete, setIsComplete] = useState(false);
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  const restart = useCallback(() => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    setDisplayedChars(0);
+    setIsStarted(false);
+    setIsComplete(false);
+  }, []);
+
+  useEffect(() => {
+    restart();
+  }, [text, restart]);
+
+  useEffect(() => {
+    if (startDelay > 0 && !isStarted) {
+      const timeout = setTimeout(() => setIsStarted(true), startDelay);
+      return () => clearTimeout(timeout);
+    } else if (startDelay === 0) {
+      setIsStarted(true);
+    }
+  }, [startDelay, isStarted]);
+
+  useEffect(() => {
+    if (!isStarted || isComplete) return;
+
+    if (displayedChars >= text.length) {
+      setIsComplete(true);
+      return;
+    }
+
+    timeoutRef.current = setTimeout(() => {
+      setDisplayedChars((prev) => prev + 1);
+    }, speed);
+
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, [isStarted, displayedChars, text.length, speed, isComplete]);
+
+  return {
+    displayedText: text.slice(0, displayedChars),
+    isComplete,
+    restart,
+  };
+}
+
+export function useCountdown(
+  initialSeconds: number,
+  options: { autoStart?: boolean; onComplete?: () => void } = {}
+): { seconds: number; isRunning: boolean; start: () => void; pause: () => void; reset: () => void } {
+  const { autoStart = false, onComplete } = options;
+  const [seconds, setSeconds] = useState(initialSeconds);
+  const [isRunning, setIsRunning] = useState(autoStart);
+  const onCompleteRef = useRef(onComplete);
+  const intervalRef = useRef<NodeJS.Timeout | null>(null);
+  onCompleteRef.current = onComplete;
+
+  const start = useCallback(() => setIsRunning(true), []);
+  const pause = useCallback(() => setIsRunning(false), []);
+  const reset = useCallback(() => {
+    setSeconds(initialSeconds);
+    setIsRunning(false);
+  }, [initialSeconds]);
+
+  useEffect(() => {
+    if (!isRunning || seconds <= 0) {
+      if (seconds <= 0 && isRunning) {
+        setIsRunning(false);
+        onCompleteRef.current?.();
+      }
+      return;
+    }
+
+    intervalRef.current = setInterval(() => {
+      setSeconds((prev) => prev - 1);
+    }, 1000);
+
+    return () => {
+      if (intervalRef.current) clearInterval(intervalRef.current);
+    };
+  }, [isRunning, seconds]);
+
+  return { seconds, isRunning, start, pause, reset };
+}
+
+export function useFps(targetFps: number = 24): number {
+  const [frame, setFrame] = useState(0);
+  const frameRef = useRef(0);
+  const lastTimeRef = useRef(performance.now());
+  const rafIdRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    const interval = 1000 / targetFps;
+
+    const tick = () => {
+      const now = performance.now();
+      const delta = now - lastTimeRef.current;
+
+      if (delta >= interval) {
+        lastTimeRef.current = now - (delta % interval);
+        frameRef.current++;
+        setFrame(frameRef.current);
+      }
+
+      rafIdRef.current = requestAnimationFrame(tick);
+    };
+
+    rafIdRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafIdRef.current) cancelAnimationFrame(rafIdRef.current);
+    };
+  }, [targetFps]);
+
+  return frame;
+}
+
+export function useDebouncedCallback<T extends (...args: unknown[]) => void>(
+  callback: T,
+  delay: number
+): T {
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  return useCallback(((...args: Parameters<T>) => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    timeoutRef.current = setTimeout(() => callbackRef.current(...args), delay);
+  }) as T, [delay]);
+}
+
+export function useThrottledCallback<T extends (...args: unknown[]) => void>(
+  callback: T,
+  delay: number
+): T {
+  const lastCallRef = useRef<number>(0);
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  return useCallback(((...args: Parameters<T>) => {
+    const now = performance.now();
+    if (now - lastCallRef.current >= delay) {
+      lastCallRef.current = now;
+      callbackRef.current(...args);
+    }
+  }) as T, [delay]);
+}