"""Shared formatting utilities for export modules."""

import html as html_module
from datetime import datetime

from noteflow.config.constants import SECONDS_PER_HOUR


def escape_html(text: str) -> str:
    """Escape HTML special characters.

    Args:
        text: Raw text to escape.

    Returns:
        HTML-safe text with special characters converted to entities.
    """
    return html_module.escape(text) if text else text


def format_timestamp(seconds: float) -> str:
    """Format seconds as MM:SS or HH:MM:SS.

    Args:
        seconds: Time in seconds.

    Returns:
        Formatted time string.
    """
    total_seconds = int(seconds)
    hours, remainder = divmod(total_seconds, int(SECONDS_PER_HOUR))
    minutes, secs = divmod(remainder, 60)

    if hours > 0:
        return f"{hours:d}:{minutes:02d}:{secs:02d}"
    return f"{minutes:d}:{secs:02d}"


def format_datetime(dt: datetime | None) -> str:
    """Format datetime for display.

    Args:
        dt: Datetime to format.

    Returns:
        Formatted datetime string or empty string.
    """
    return "" if dt is None else dt.strftime("%Y-%m-%d %H:%M:%S")
