@tokentop/ttop 0.2.2

package/src/tui/hooks/useEntranceAnimation.ts

@@ -0,0 +1,62 @@
+import { useState, useEffect, useRef } from 'react';
+
+export interface UseEntranceAnimationOptions {
+  durationMs?: number;
+  fps?: number;
+}
+
+/**
+ * Hook that provides a fade-in animation when a component mounts.
+ * Returns an intensity from 0 (just appeared) to 1 (fully visible).
+ * Use this to fade in new items in a list.
+ */
+export function useEntranceAnimation(options: UseEntranceAnimationOptions = {}): number {
+  const { durationMs = 400, fps = 30 } = options;
+  const mountTime = useRef(Date.now());
+  const [intensity, setIntensity] = useState(0);
+
+  useEffect(() => {
+    const intervalMs = 1000 / fps;
+    
+    const tick = () => {
+      const elapsed = Date.now() - mountTime.current;
+      const progress = Math.min(1, elapsed / durationMs);
+      const eased = 1 - Math.pow(1 - progress, 2);
+      setIntensity(eased);
+      
+      if (progress < 1) {
+        setTimeout(tick, intervalMs);
+      }
+    };
+    
+    tick();
+  }, [durationMs, fps]);
+
+  return intensity;
+}
+
+/**
+ * Apply entrance fade to a color - starts dim and brightens to full color.
+ */
+export function applyEntranceFade(intensity: number, color: string, dimColor: string): string {
+  if (intensity >= 1) return color;
+  if (intensity <= 0) return dimColor;
+  
+  const parseHex = (hex: string): [number, number, number] => {
+    const clean = hex.replace('#', '');
+    return [
+      parseInt(clean.slice(0, 2), 16),
+      parseInt(clean.slice(2, 4), 16),
+      parseInt(clean.slice(4, 6), 16),
+    ];
+  };
+  
+  const [r1, g1, b1] = parseHex(dimColor);
+  const [r2, g2, b2] = parseHex(color);
+  
+  const r = Math.round(r1 + (r2 - r1) * intensity);
+  const g = Math.round(g1 + (g2 - g1) * intensity);
+  const b = Math.round(b1 + (b2 - b1) * intensity);
+  
+  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+}

package/src/tui/hooks/useExitAnimation.ts

@@ -0,0 +1,137 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export interface ExitAnimationItem<T> {
+  item: T;
+  isExiting: boolean;
+  exitIntensity: number;
+}
+
+export interface UseExitAnimationOptions<T> {
+  durationMs?: number;
+  fps?: number;
+  getKey: (item: T) => string;
+  /** Absolute number of changed items to trigger a bulk skip (default 10) */
+  bulkThreshold?: number;
+}
+
+export interface UseExitAnimationResult<T> {
+  items: ExitAnimationItem<T>[];
+  /** True when a bulk change just happened (skip entrance animations) */
+  isBulkChange: boolean;
+}
+
+interface ExitingEntry<T> {
+  item: T;
+  startTime: number;
+}
+
+export function useExitAnimation<T>(
+  items: T[],
+  options: UseExitAnimationOptions<T>
+): UseExitAnimationResult<T> {
+  const { durationMs = 500, fps = 30, getKey, bulkThreshold = 10 } = options;
+  const prevKeysRef = useRef<Set<string>>(new Set());
+  const prevItemsRef = useRef<Map<string, T>>(new Map());
+  const exitingRef = useRef<Map<string, ExitingEntry<T>>>(new Map());
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [, forceUpdate] = useState(0);
+
+  const tick = useCallback(() => {
+    const now = Date.now();
+    let anyActive = false;
+
+    for (const [key, entry] of exitingRef.current) {
+      if (now - entry.startTime >= durationMs) {
+        exitingRef.current.delete(key);
+      } else {
+        anyActive = true;
+      }
+    }
+
+    forceUpdate((c: number) => c + 1);
+
+    if (anyActive) {
+      timerRef.current = setTimeout(tick, 1000 / fps);
+    } else {
+      timerRef.current = null;
+    }
+  }, [durationMs, fps]);
+
+  // Diff runs synchronously during render so isBulkChange is available
+  // in the same pass that mounts new rows (effects run too late).
+  const currentKeys = new Set(items.map(getKey));
+  const prevKeys = prevKeysRef.current;
+
+  let removedCount = 0;
+  for (const key of prevKeys) {
+    if (!currentKeys.has(key)) removedCount++;
+  }
+  let addedCount = 0;
+  for (const key of currentKeys) {
+    if (!prevKeys.has(key)) addedCount++;
+  }
+
+  const totalAffected = removedCount + addedCount;
+  const isBulkChange = prevKeys.size > 0 && totalAffected >= bulkThreshold;
+
+  // Queue exiting items during render so they appear in the same frame
+  // they leave `items` — avoids a one-frame gap (flash).
+  if (isBulkChange) {
+    exitingRef.current.clear();
+  } else {
+    const prevItems = prevItemsRef.current;
+    for (const [key, item] of prevItems) {
+      if (!currentKeys.has(key) && !exitingRef.current.has(key)) {
+        exitingRef.current.set(key, { item, startTime: Date.now() });
+      }
+    }
+  }
+
+  useEffect(() => {
+    if (isBulkChange && timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    } else if (exitingRef.current.size > 0 && timerRef.current === null) {
+      timerRef.current = setTimeout(tick, 1000 / fps);
+    }
+
+    prevKeysRef.current = currentKeys;
+    const newPrevItems = new Map<string, T>();
+    for (const item of items) {
+      newPrevItems.set(getKey(item), item);
+    }
+    prevItemsRef.current = newPrevItems;
+  }, [items, getKey, tick, fps, isBulkChange, currentKeys]);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, []);
+
+  const now = Date.now();
+  const result: ExitAnimationItem<T>[] = [];
+
+  for (const item of items) {
+    result.push({ item, isExiting: false, exitIntensity: 1 });
+  }
+
+  if (!isBulkChange) {
+    for (const [, entry] of exitingRef.current) {
+      const elapsed = now - entry.startTime;
+      const progress = Math.min(1, elapsed / durationMs);
+      const eased = Math.pow(progress, 2);
+
+      result.push({
+        item: entry.item,
+        isExiting: true,
+        exitIntensity: Math.max(0, 1 - eased),
+      });
+    }
+  }
+
+  return { items: result, isBulkChange };
+}

package/src/tui/hooks/usePulse.ts

@@ -0,0 +1,138 @@
+import { useState, useEffect } from 'react';
+
+/**
+ * Options for the usePulse hook.
+ */
+export interface UsePulseOptions {
+  /** Whether the pulse animation is enabled */
+  enabled: boolean;
+  /** Interval between steps in milliseconds (default: 200) */
+  intervalMs?: number;
+  /** Number of steps in the pulse cycle (default: 12) */
+  steps?: number;
+}
+
+/**
+ * Parses a hex color string to RGB components.
+ * Supports both 3-digit (#RGB) and 6-digit (#RRGGBB) formats.
+ *
+ * @param hex - Hex color string (e.g., "#ff0000" or "#f00")
+ * @returns RGB tuple [r, g, b] or null if invalid
+ */
+function parseHexColor(hex: string): [number, number, number] | null {
+  const cleanHex = hex.startsWith('#') ? hex.slice(1) : hex;
+
+  let expandedHex: string;
+
+  if (cleanHex.length === 3) {
+    const c0 = cleanHex.slice(0, 1);
+    const c1 = cleanHex.slice(1, 2);
+    const c2 = cleanHex.slice(2, 3);
+    expandedHex = c0 + c0 + c1 + c1 + c2 + c2;
+  } else if (cleanHex.length === 6) {
+    expandedHex = cleanHex;
+  } else {
+    return null;
+  }
+
+  const r = parseInt(expandedHex.slice(0, 2), 16);
+  const g = parseInt(expandedHex.slice(2, 4), 16);
+  const b = parseInt(expandedHex.slice(4, 6), 16);
+
+  if (isNaN(r) || isNaN(g) || isNaN(b)) {
+    return null;
+  }
+
+  return [r, g, b];
+}
+
+/**
+ * Converts RGB components to a hex color string.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Hex color string (e.g., "#ff0000")
+ */
+function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (n: number) => {
+    const clamped = Math.max(0, Math.min(255, Math.round(n)));
+    return clamped.toString(16).padStart(2, '0');
+  };
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+/**
+ * Interpolates between two colors based on a pulse step.
+ * Uses sine wave for smooth pulsing effect.
+ *
+ * @param step - Current pulse step (0 to steps-1)
+ * @param baseColor - Base color hex string (e.g., "#333333")
+ * @param peakColor - Peak color hex string (e.g., "#ff0000")
+ * @param steps - Total number of steps in the pulse cycle (default: 12)
+ * @returns Interpolated hex color string
+ *
+ * @example
+ * ```ts
+ * const color = getPulseColor(3, "#333333", "#ff0000", 12);
+ * ```
+ */
+export function getPulseColor(
+  step: number,
+  baseColor: string,
+  peakColor: string,
+  steps: number = 12
+): string {
+  const baseRgb = parseHexColor(baseColor);
+  const peakRgb = parseHexColor(peakColor);
+
+  if (!baseRgb || !peakRgb) {
+    return baseColor;
+  }
+
+  const t = Math.sin((step / steps) * Math.PI);
+
+  const r = baseRgb[0] + (peakRgb[0] - baseRgb[0]) * t;
+  const g = baseRgb[1] + (peakRgb[1] - baseRgb[1]) * t;
+  const b = baseRgb[2] + (peakRgb[2] - baseRgb[2]) * t;
+
+  return rgbToHex(r, g, b);
+}
+
+/**
+ * Hook for creating pulse animations.
+ * Returns the current step in the pulse cycle, which can be used
+ * with getPulseColor to create smooth color transitions.
+ *
+ * @param options - Configuration options for the pulse animation
+ * @returns Current step in the pulse cycle (0 to steps-1), or 0 when disabled
+ *
+ * @example
+ * ```tsx
+ * function WarningIndicator({ isWarning }: { isWarning: boolean }) {
+ *   const step = usePulse({ enabled: isWarning, intervalMs: 150, steps: 12 });
+ *   const color = getPulseColor(step, "#333333", "#ff6600", 12);
+ *
+ *   return <Box borderColor={color}>Warning!</Box>;
+ * }
+ * ```
+ */
+export function usePulse(options: UsePulseOptions): number {
+  const { enabled, intervalMs = 200, steps = 12 } = options;
+  const [step, setStep] = useState(0);
+
+  useEffect(() => {
+    if (!enabled) {
+      setStep(0);
+      return;
+    }
+
+    const interval = setInterval(() => {
+      setStep((prev) => (prev + 1) % steps);
+    }, intervalMs);
+
+    return () => clearInterval(interval);
+  }, [enabled, intervalMs, steps]);
+
+  return step;
+}

package/src/tui/hooks/useSafeRenderer.ts

@@ -0,0 +1,24 @@
+import type { CliRenderer } from '@opentui/core';
+import { useRenderer } from '@opentui/react';
+import { createContext, useContext } from 'react';
+
+/**
+ * Context to signal we're in test/headless mode where renderer may not be available.
+ * When TestModeContext is true, useSafeRenderer returns null instead of throwing.
+ */
+export const TestModeContext = createContext<boolean>(false);
+
+/**
+ * Hook that safely gets the renderer, returning null in test mode.
+ * Use this instead of useRenderer() directly when the component needs to work
+ * in both production (real renderer) and test/headless mode (no renderer).
+ */
+export function useSafeRenderer(): CliRenderer | null {
+  const isTestMode = useContext(TestModeContext);
+  
+  if (isTestMode) {
+    return null;
+  }
+  
+  return useRenderer();
+}

package/src/tui/hooks/useValueFlash.ts

@@ -0,0 +1,111 @@
+import { useState, useEffect, useRef } from 'react';
+
+export interface UseValueFlashOptions {
+  durationMs?: number;
+  increaseOnly?: boolean;
+  threshold?: number;
+}
+
+export interface UseValueFlashResult {
+  isFlashing: boolean;
+  intensity: number;
+  step: number;
+}
+
+export function useValueFlash(
+  value: number,
+  options: UseValueFlashOptions = {}
+): UseValueFlashResult {
+  const { durationMs = 600, increaseOnly = true, threshold = 0 } = options;
+  
+  const prevValueRef = useRef<number>(value);
+  const [isFlashing, setIsFlashing] = useState(false);
+  const [step, setStep] = useState(0);
+  const flashTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const animationIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const steps = 18;
+  const stepDuration = durationMs / steps;
+
+  useEffect(() => {
+    const prevValue = prevValueRef.current;
+    const delta = value - prevValue;
+    
+    const shouldFlash = increaseOnly 
+      ? delta > threshold 
+      : Math.abs(delta) > threshold;
+
+    if (shouldFlash && prevValue !== value) {
+      if (flashTimeoutRef.current) {
+        clearTimeout(flashTimeoutRef.current);
+      }
+      if (animationIntervalRef.current) {
+        clearInterval(animationIntervalRef.current);
+      }
+
+      setIsFlashing(true);
+      setStep(0);
+
+      let currentStep = 0;
+      animationIntervalRef.current = setInterval(() => {
+        currentStep++;
+        if (currentStep >= steps) {
+          if (animationIntervalRef.current) {
+            clearInterval(animationIntervalRef.current);
+            animationIntervalRef.current = null;
+          }
+          setIsFlashing(false);
+          setStep(0);
+        } else {
+          setStep(currentStep);
+        }
+      }, stepDuration);
+    }
+
+    prevValueRef.current = value;
+
+    return () => {
+      if (flashTimeoutRef.current) {
+        clearTimeout(flashTimeoutRef.current);
+      }
+      if (animationIntervalRef.current) {
+        clearInterval(animationIntervalRef.current);
+      }
+    };
+  }, [value, durationMs, increaseOnly, threshold, steps, stepDuration]);
+
+  const intensity = isFlashing 
+    ? Math.sin((step / steps) * Math.PI) 
+    : 0;
+
+  return { isFlashing, intensity, step };
+}
+
+export function interpolateColor(factor: number, colorA: string, colorB: string): string {
+  const parseHex = (hex: string): [number, number, number] | null => {
+    const clean = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (clean.length === 3) {
+      const [r, g, b] = clean.split('').map(c => parseInt(c + c, 16));
+      return [r!, g!, b!];
+    }
+    if (clean.length === 6) {
+      return [
+        parseInt(clean.slice(0, 2), 16),
+        parseInt(clean.slice(2, 4), 16),
+        parseInt(clean.slice(4, 6), 16),
+      ];
+    }
+    return null;
+  };
+
+  const a = parseHex(colorA);
+  const b = parseHex(colorB);
+  
+  if (!a || !b) return colorA;
+
+  const r = Math.round(a[0] + (b[0] - a[0]) * factor);
+  const g = Math.round(a[1] + (b[1] - a[1]) * factor);
+  const bl = Math.round(a[2] + (b[2] - a[2]) * factor);
+
+  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${bl.toString(16).padStart(2, '0')}`;
+}

package/src/tui/index.tsx

@@ -0,0 +1,50 @@
+import { createCliRenderer } from '@opentui/core';
+import { createRoot } from '@opentui/react';
+import { createAppElement, type CreateAppOptions } from './createApp.tsx';
+import type { DemoPreset } from '@/demo/simulator.ts';
+
+export interface TuiOptions {
+  refreshInterval?: number;
+  debug?: boolean;
+  demo?: boolean;
+  demoSeed?: number;
+  demoPreset?: DemoPreset;
+  cliPlugins?: string[];
+}
+
+export async function startTui(options: TuiOptions = {}) {
+  const renderer = await createCliRenderer({
+    exitOnCtrlC: false,
+    autoFocus: true,
+  });
+
+  const root = createRoot(renderer);
+
+  const appOptions: CreateAppOptions = {};
+
+  if (options.refreshInterval !== undefined) {
+    appOptions.refreshInterval = options.refreshInterval;
+  }
+  if (options.debug !== undefined) {
+    appOptions.debug = options.debug;
+  }
+  if (options.demo !== undefined) {
+    appOptions.demoMode = options.demo;
+  }
+  if (options.demoSeed !== undefined) {
+    appOptions.demoSeed = options.demoSeed;
+  }
+  if (options.demoPreset !== undefined) {
+    appOptions.demoPreset = options.demoPreset;
+  }
+  if (options.cliPlugins !== undefined) {
+    appOptions.cliPlugins = options.cliPlugins;
+  }
+
+  root.render(createAppElement(appOptions));
+
+  return renderer;
+}
+
+export { App } from './App.tsx';
+export { createAppElement, type CreateAppOptions } from './createApp.tsx';

package/src/tui/utils/providerColor.ts

@@ -0,0 +1,32 @@
+import type { ProviderState } from '../contexts/PluginContext.tsx';
+
+let cachedAliases: Map<string, string> | null = null;
+let cachedProviderRef: Map<string, ProviderState> | null = null;
+
+function getAliasIndex(providers: Map<string, ProviderState>): Map<string, string> {
+  if (cachedAliases && cachedProviderRef === providers) return cachedAliases;
+
+  const aliases = new Map<string, string>();
+  for (const [id, state] of providers) {
+    for (const alias of state.plugin.meta?.providerAliases ?? []) {
+      aliases.set(alias, id);
+    }
+  }
+  cachedAliases = aliases;
+  cachedProviderRef = providers;
+  return aliases;
+}
+
+export function getProviderColor(
+  providerId: string,
+  providers: Map<string, ProviderState>,
+  fallback: string,
+): string {
+  const direct = providers.get(providerId);
+  if (direct) return direct.plugin.meta?.brandColor ?? fallback;
+
+  const aliasTarget = getAliasIndex(providers).get(providerId);
+  if (aliasTarget) return providers.get(aliasTarget)?.plugin.meta?.brandColor ?? fallback;
+
+  return fallback;
+}