utils.py

"""
Utility module for MultiAPI Dashboard.

Provides UI helpers including the ASCII banner, progress spinner,
ANSI color wrappers, input validation, number formatting, and
table display helpers.
"""

import itertools
import os
import sys
import threading
import time
from typing import Any, Dict, List, Optional

from config import Colors


# ============================================================
# ASCII Art Banner
# ============================================================

BANNER = f"""
{Colors.BRIGHT_CYAN}{Colors.BOLD}
╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║   ███╗   ███╗██╗   ██╗██╗  ████████╗██╗     █████╗ ██████╗  ║
║   ████╗ ████║██║   ██║██║  ╚══██╔══╝██║    ██╔══██╗██╔══██╗ ║
║   ██╔████╔██║██║   ██║██║     ██║   ██║    ███████║██████╔╝ ║
║   ██║╚██╔╝██║██║   ██║██║     ██║   ██║    ██╔══██║██╔═══╝  ║
║   ██║ ╚═╝ ██║╚██████╔╝███████╗██║   ██║    ██║  ██║██║      ║
║   ╚═╝     ╚═╝ ╚═════╝ ╚══════╝╚═╝   ╚═╝    ╚═╝  ╚═╝╚═╝      ║
║                                                              ║
║        ██████╗  █████╗ ███████╗██╗  ██╗██████╗  ██████╗      ║
║        ██╔══██╗██╔══██╗██╔════╝██║  ██║██╔══██╗██╔═══██╗     ║
║        ██║  ██║███████║███████╗███████║██████╔╝██║   ██║     ║
║        ██║  ██║██╔══██║╚════██║██╔══██║██╔══██╗██║   ██║     ║
║        ██████╔╝██║  ██║███████║██║  ██║██████╔╝╚██████╔╝     ║
║        ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝  ╚═════╝      ║
║                                                              ║
║  {Colors.BRIGHT_YELLOW}⚡  Weather  •  Crypto  •  News  •  All in One  ⚡{Colors.BRIGHT_CYAN}       ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝
{Colors.RESET}"""


def print_banner() -> None:
    """Display the application ASCII art banner."""
    clear_screen()
    print(BANNER)


# ============================================================
# Color Helpers
# ============================================================

def colorize(text: str, color: str) -> str:
    """
    Wrap text with ANSI color codes.

    Args:
        text: The text to colorize.
        color: ANSI color code from Colors class.

    Returns:
        Colorized string with reset appended.
    """
    return f"{color}{text}{Colors.RESET}"


def success(text: str) -> str:
    """Return text in bright green."""
    return colorize(text, Colors.BRIGHT_GREEN)


def error(text: str) -> str:
    """Return text in bright red."""
    return colorize(text, Colors.BRIGHT_RED)


def warning(text: str) -> str:
    """Return text in bright yellow."""
    return colorize(text, Colors.BRIGHT_YELLOW)


def info(text: str) -> str:
    """Return text in bright cyan."""
    return colorize(text, Colors.BRIGHT_CYAN)


def highlight(text: str) -> str:
    """Return text in bold bright white."""
    return colorize(text, f"{Colors.BOLD}{Colors.BRIGHT_WHITE}")


def dim(text: str) -> str:
    """Return text in dim gray."""
    return colorize(text, Colors.DIM)


# ============================================================
# Screen Utilities
# ============================================================

def clear_screen() -> None:
    """Clear the terminal screen."""
    os.system("cls" if os.name == "nt" else "clear")


def print_separator(char: str = "─", length: int = 60, color: str = Colors.DIM) -> None:
    """Print a decorative separator line."""
    print(colorize(char * length, color))


def print_header(title: str) -> None:
    """Print a styled section header."""
    print()
    print_separator("═", 60, Colors.BRIGHT_CYAN)
    print(colorize(f"  {title}", f"{Colors.BOLD}{Colors.BRIGHT_CYAN}"))
    print_separator("═", 60, Colors.BRIGHT_CYAN)
    print()


def print_subheader(title: str) -> None:
    """Print a smaller section header."""
    print()
    print_separator("─", 50, Colors.CYAN)
    print(colorize(f"  {title}", f"{Colors.BOLD}{Colors.CYAN}"))
    print_separator("─", 50, Colors.CYAN)


# ============================================================
# Progress Spinner
# ============================================================

class Spinner:
    """
    Threaded progress spinner for long-running operations.

    Usage:
        with Spinner("Fetching data"):
            # long operation here
            result = api.get(...)
    """

    FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]

    def __init__(self, message: str = "Loading", color: str = Colors.BRIGHT_CYAN):
        self.message = message
        self.color = color
        self._running = False
        self._thread: Optional[threading.Thread] = None

    def _spin(self) -> None:
        """Internal spinner animation loop."""
        spinner = itertools.cycle(self.FRAMES)
        while self._running:
            frame = next(spinner)
            sys.stdout.write(
                f"\r  {self.color}{frame}{Colors.RESET} {self.message}..."
            )
            sys.stdout.flush()
            time.sleep(0.08)
        # Clear the spinner line
        sys.stdout.write("\r" + " " * (len(self.message) + 10) + "\r")
        sys.stdout.flush()

    def start(self) -> None:
        """Start the spinner animation."""
        self._running = True
        self._thread = threading.Thread(target=self._spin, daemon=True)
        self._thread.start()

    def stop(self) -> None:
        """Stop the spinner animation."""
        self._running = False
        if self._thread:
            self._thread.join()

    def __enter__(self) -> "Spinner":
        self.start()
        return self

    def __exit__(self, *args: Any) -> None:
        self.stop()


# ============================================================
# Input Helpers
# ============================================================

def get_input(prompt: str, allow_empty: bool = False) -> str:
    """
    Get validated user input with styled prompt.

    Args:
        prompt: The prompt message to display.
        allow_empty: Whether to accept empty input.

    Returns:
        Stripped user input string.
    """
    while True:
        try:
            user_input = input(
                f"  {Colors.BRIGHT_YELLOW}▶{Colors.RESET} {prompt}: "
            ).strip()

            if not user_input and not allow_empty:
                print(f"  {error('⚠ Please enter a value.')}")
                continue

            return user_input

        except EOFError:
            return ""


def get_menu_choice(max_option: int) -> int:
    """
    Get a valid numeric menu choice from the user.

    Args:
        max_option: Maximum valid menu option number.

    Returns:
        Selected option as integer, or -1 for invalid input.
    """
    try:
        choice_str = input(
            f"\n  {Colors.BRIGHT_YELLOW}▶{Colors.RESET} Enter your choice "
            f"{dim(f'[1-{max_option}]')}: "
        ).strip()

        choice = int(choice_str)
        if 1 <= choice <= max_option:
            return choice

        print(f"  {error(f'⚠ Please enter a number between 1 and {max_option}.')}")
        return -1

    except (ValueError, EOFError):
        print(f"  {error('⚠ Invalid input. Please enter a number.')}")
        return -1


def confirm(prompt: str) -> bool:
    """
    Ask user for yes/no confirmation.

    Args:
        prompt: Question to ask.

    Returns:
        True if user confirms, False otherwise.
    """
    response = input(
        f"  {Colors.BRIGHT_YELLOW}?{Colors.RESET} {prompt} "
        f"{dim('[y/N]')}: "
    ).strip().lower()
    return response in ("y", "yes")


# ============================================================
# Formatting Helpers
# ============================================================

def format_number(num: float, decimals: int = 2) -> str:
    """
    Format a number with commas and specified decimal places.

    Args:
        num: Number to format.
        decimals: Number of decimal places.

    Returns:
        Formatted string (e.g., "1,234,567.89").
    """
    if num is None:
        return "N/A"
    try:
        return f"{num:,.{decimals}f}"
    except (TypeError, ValueError):
        return str(num)


def format_currency(amount: float, symbol: str = "$") -> str:
    """
    Format a number as currency.

    Args:
        amount: Amount to format.
        symbol: Currency symbol.

    Returns:
        Formatted currency string (e.g., "$1,234.56").
    """
    if amount is None:
        return "N/A"
    return f"{symbol}{format_number(amount)}"


def format_percentage(value: float) -> str:
    """
    Format a number as percentage with color (green/red).

    Args:
        value: Percentage value.

    Returns:
        Colored percentage string.
    """
    if value is None:
        return "N/A"
    sign = "+" if value > 0 else ""
    color = Colors.BRIGHT_GREEN if value >= 0 else Colors.BRIGHT_RED
    return colorize(f"{sign}{value:.2f}%", color)


def format_large_number(num: float) -> str:
    """
    Format large numbers with K/M/B/T suffixes.

    Args:
        num: Number to format.

    Returns:
        Abbreviated string (e.g., "1.23B").
    """
    if num is None:
        return "N/A"
    try:
        abs_num = abs(num)
        if abs_num >= 1_000_000_000_000:
            return f"${num / 1_000_000_000_000:.2f}T"
        if abs_num >= 1_000_000_000:
            return f"${num / 1_000_000_000:.2f}B"
        if abs_num >= 1_000_000:
            return f"${num / 1_000_000:.2f}M"
        if abs_num >= 1_000:
            return f"${num / 1_000:.2f}K"
        return f"${num:.2f}"
    except (TypeError, ValueError):
        return str(num)


def truncate(text: str, max_length: int = 200) -> str:
    """
    Truncate text to max length with ellipsis.

    Args:
        text: Text to truncate.
        max_length: Maximum character length.

    Returns:
        Truncated text or original if shorter.
    """
    if not text:
        return "N/A"
    if len(text) <= max_length:
        return text
    return text[:max_length - 3] + "..."


# ============================================================
# Table Display
# ============================================================

def print_key_value(key: str, value: str, key_width: int = 20) -> None:
    """
    Print a styled key-value pair.

    Args:
        key: Label text.
        value: Value text.
        key_width: Width for the key column.
    """
    print(
        f"  {Colors.BRIGHT_WHITE}{key:<{key_width}}{Colors.RESET}"
        f" {Colors.DIM}│{Colors.RESET} {value}"
    )


def print_table_row(columns: List[str], widths: List[int]) -> None:
    """
    Print a table row with specified column widths.

    Args:
        columns: List of column values.
        widths: List of column widths.
    """
    row = "  "
    for col, width in zip(columns, widths):
        row += f"{str(col):<{width}} "
    print(row)


def press_enter_to_continue() -> None:
    """Pause and wait for user to press Enter."""
    print()
    input(f"  {dim('Press Enter to continue...')}")