"""Basic text normalization utilities.

This module provides Unicode text normalization functions that preserve
international characters while standardizing representation.
"""

from __future__ import annotations

import unicodedata


def normalize_text(s: str) -> str:
    """Normalize text while preserving international characters.

    Uses NFKC normalization which handles:
    - Composed/decomposed characters (é vs e + ´)
    - Full-width/half-width characters (Japanese)
    - Compatibility characters
    - Preserves CJK, Cyrillic, Arabic, Hebrew, and all Unicode scripts

    Args:
        s: Input string to normalize

    Returns:
        NFKC-normalized string, or empty string if input is empty/None
    """
    if not s:
        return ""
    return unicodedata.normalize("NFKC", s)


def normalize_for_comparison(s: str) -> str:
    """Normalize text for comparison/matching purposes.

    Applies NFKC normalization and converts to lowercase.
    Useful for case-insensitive matching while preserving
    international characters.

    Args:
        s: Input string to normalize

    Returns:
        Lowercase NFKC-normalized string
    """
    return normalize_text(s).lower()
