from __future__ import annotations

from typing import Any, Dict
import re
import unicodedata

# Support Unicode letters including CJK, Cyrillic, Arabic, etc.
# \w matches Unicode word characters (letters, digits, underscore)
ALLOWED = re.compile(r"[^\w' -]+", re.UNICODE)


def clean_name(value: str) -> Dict[str, Any]:
    """
    Clean and normalize person names while preserving international characters.

    Supports names in all scripts: Latin, CJK, Cyrillic, Arabic, Hebrew, etc.
    - Removes special characters but keeps letters, apostrophes, spaces, hyphens
    - Normalizes Unicode to NFKC form for consistency
    - Preserves non-Latin characters (e.g., 李明, Владимир, José)

    Examples:
        "José García" -> "José García"
        "李明" -> "李明"
        "Владимир Петров" -> "Владимир Петров"
        "François O'Brien-Smith" -> "François O'Brien-Smith"
    """
    # Normalize Unicode to canonical form
    s = unicodedata.normalize("NFKC", value or "").strip()

    # Remove special characters but preserve Unicode letters, apostrophes, spaces, hyphens
    s = ALLOWED.sub(" ", s)

    # Collapse multiple spaces
    s = " ".join(w for w in s.split())

    return {"value": s.title()}
