"""通用文本工具函数。"""
from __future__ import annotations

import re
from typing import Optional

_ANSI_RE = re.compile(r"\x1b\[[0-9;?]*[A-Za-z]")


def strip_ansi(text: str) -> str:
    """去除字符串中的 ANSI 转义序列（颜色/光标控制）。"""
    if not text:
        return text
    return _ANSI_RE.sub("", text)


def ansi_len(text: str) -> int:
    """计算去除 ANSI 转义后的可视长度（不处理 CJK/EastAsian，适合 ASCII 标签宽度计算）。"""
    return len(strip_ansi(text))


def pad_ansi(text: str, width: int, fillchar: str = " ") -> str:
    """按可视宽度右填充文本（保证对齐时忽略 ANSI 长度膨胀）。"""
    pad = width - ansi_len(text)
    if pad <= 0:
        return text
    return text + fillchar * pad


def hhmmss(dt: Optional[str] = None) -> str:
    """返回 HH:MM:SS 字符串。dt=None 时取当前本地时间。"""
    import datetime as _dt

    t = _dt.datetime.now().strftime("%H:%M:%S") if dt is None else dt
    return t
