"""Shared, brand-consistent HTML email layout.

Every outgoing Helix email should *look* like the rich Day-1 onboarding
welcome mail (PR #1522): a dark-navy header, a soft page background, a
white rounded card, an optional accent-bordered content card, a primary
CTA button and a quiet footer — all inline-styled, table-based and
email-client safe (no external assets, no ``<style>`` blocks, no
responsive media queries).

Historically only the onboarding email had this treatment; every other
template shipped as bare plain text. Rather than hand-author HTML for
~40 templates, :func:`render_email_shell` wraps any already-resolved
plain-text body in the branded shell. :mod:`app.notifications.service`
calls it once, at send time, for every email that does not already carry
an explicit ``body_html`` (so the onboarding mail and any admin-authored
HTML are left untouched).

The visual language (colors, paddings, header navy ``#0E2A47``, button
blue ``#2563EB``) is intentionally identical to
``app.hr_lifecycle.hire_day_service._render_onboarding_html`` so the two
read as one family. This module owns the *generic* shell + the inline
text→HTML conversion; it has **no** dependency on ``service`` (one-way
import only) and re-implements the tiny ``[r]``/``[b]``/``**`` markup so
the two never import each other.
"""

from __future__ import annotations

import html as _html
import re
from urllib.parse import urlsplit

from app.core.locale import DEFAULT_LANG, normalize_lang

# ── Brand palette (mirrors _render_onboarding_html) ──────────────────
_PAGE_BG = "#EEF1F6"
_HEADER_BG = "#0E2A47"
_KICKER = "#7FB0E6"
_CARD_BG = "#ffffff"
_BTN_BG = "#2563EB"
#: Inline anchor colour. Same blue as the CTA button so an in-prose link and
#: the button below it read as the same affordance.
_LINK_BLUE = "#2563EB"
_TEXT = "#334155"
_HEADING = "#0F172A"
_MUTED = "#94A3B8"
_RED = "#d4380d"

_FONT = (
    "-apple-system,'Segoe UI',Roboto,'Helvetica Neue',Arial,"
    "'PingFang SC','Microsoft YaHei',sans-serif"
)

# Default accent for the single content card. Domain callers may pass a
# different accent (e.g. red for breach/critical alerts) but the safe,
# neutral default is the brand blue.
_DEFAULT_ACCENT = "#3B82F6"
_DEFAULT_ACCENT_BG = "#F8FAFC"
_DEFAULT_ACCENT_BORDER = "#E6EBF2"

# Characters that start a bullet line in our plain-text templates.
# Deliberately excludes the em/en dash: templates sign off with
# "— Helix IT 平台", which must render as a normal line, not a bullet.
_BULLET_PREFIXES = ("▸", "•", "‣", "◦", "·", "- ")


# ``_is_en`` used to live here — "English/Japanese readers get the English
# chrome", which is precisely the conflation this shell no longer makes: a
# Japanese reader now gets Japanese chrome, keyed on ``normalize_lang``. It had
# no remaining caller and was removed rather than left as a trap for the next
# person who needs a language decision in this file.


def _replace_delimited(
    text: str,
    opening: str,
    closing: str,
    prefix: str,
    suffix: str,
) -> str:
    """Replace paired lightweight markup with a forward-only scan.

    ``re.sub`` with a lazy wildcard still retries from every unmatched opener,
    making inputs such as ``"[r]a" * N`` polynomial. This parser either
    consumes a complete non-empty pair or appends the unmatched remainder
    once. Requiring one content character preserves the former ``(.+?)``
    semantics for empty/adjacent markers without reintroducing backtracking.
    """
    chunks: list[str] = []
    cursor = 0
    while True:
        start = text.find(opening, cursor)
        if start < 0:
            chunks.append(text[cursor:])
            break
        content_start = start + len(opening)
        end = text.find(closing, content_start + 1)
        if end < 0:
            chunks.append(text[cursor:])
            break
        chunks.append(text[cursor:start])
        chunks.extend((prefix, text[content_start:end], suffix))
        cursor = end + len(closing)
    return "".join(chunks)


#: ``[文字](https://…)`` — an anchor whose text carries the link, the way a
#: human writes it. Feishu card markdown ALREADY renders this natively (that is
#: precisely why ``me_universe/urge.py`` strips ``[](){}`` out of user-supplied
#: titles before they reach a card), so before this the two channels disagreed:
#: the card showed a proper anchor and the email showed the literal
#: ``[文字](https://…)``. Templates worked around it by putting a bare URL in
#: prose, which is what produced the 2026-08-31 offboarding-letter defect —
#: the Feishu client autolinks a bare URL and swallows an adjacent ``)`` into
#: the href, so 「申请(https://…/my/requests),操作详情」 rendered as
#: 「申请(https://…/my/requests,操作详情」 with the closing paren gone.
_MD_LINK = re.compile(r"\[([^\]\n]{1,120})\]\((https?://[^)\s]{1,400})\)")

#: Hosts whose links may become real ``<a>`` anchors in an email body.
#:
#: Deliberately an allowlist, and deliberately NARROWER than the Feishu card's
#: behaviour. A template body is assembled from trusted copy PLUS ``context``
#: values, and some of those values are user-supplied (a request title, a typed
#: reason). On the card, a title like ``[紧急·点此](https://evil)`` is already a
#: live link unless the call site stripped it — a known hazard mitigated
#: per-call-site. Rendering every markdown link in email would import that
#: hazard into a second channel. Anchoring only these hosts means a smuggled
#: destination can never become clickable here: it falls through to the
#: escaped-literal path below, exactly as today.
_ANCHOR_HOSTS: frozenset[str] = frozenset({
    "helix.pingcap.net",
    "hris.app.unifyhrs.com",
    "learning.pingcap.com",
    "pingcap.feishu.cn",
})


def _anchor_allowed(url: str) -> bool:
    try:
        host = (urlsplit(url).hostname or "").lower()
    except ValueError:
        return False
    return host in _ANCHOR_HOSTS


#: Placeholder wrapper for an already-built anchor. NUL cannot occur in a
#: rendered template body (``html.escape`` has run and templates are text), so
#: it cannot collide with content the way any printable sentinel could.
_ANCHOR_SLOT = "\x00a{}\x00"
_ANCHOR_SLOT_RE = re.compile(r"\x00a(\d+)\x00")


def _extract_md_links(escaped: str) -> tuple[str, list[str]]:
    """Replace ``[text](url)`` with opaque slots; return (text, anchor html).

    Runs on ALREADY html-escaped text, so ``&`` in a query string is already
    ``&amp;`` (correct inside an ``href``) and the anchor text cannot inject
    markup. A non-allowlisted destination is left exactly as it arrived, which
    means the reader still sees the text and the URL rather than losing the
    destination silently.

    **Why slots and not a straight substitution.** The first cut emitted the
    ``<a href="…">`` inline and relied on "links are substituted first" to keep
    the href safe — which is not how it works: the later ``**`` / ``[b]`` passes
    still scan the whole string, so a URL containing ``**`` (a query parameter,
    a signed link) had ``<strong>`` spliced *into the href attribute* and the
    link broke. Caught by ``test_anchor_href_is_not_mangled_by_the_bold_markup``
    — running first protects nothing; being absent during those passes does.
    """
    anchors: list[str] = []

    def repl(m: re.Match[str]) -> str:
        label, url = m.group(1), m.group(2)
        if not _anchor_allowed(url) or '"' in url or "'" in url:
            return m.group(0)
        anchors.append(
            f'<a href="{url}" style="color:{_LINK_BLUE};'
            f'text-decoration:underline;">{label}</a>'
        )
        return _ANCHOR_SLOT.format(len(anchors) - 1)

    return _MD_LINK.sub(repl, escaped), anchors


def _restore_md_links(text: str, anchors: list[str]) -> str:
    if not anchors:
        return text
    return _ANCHOR_SLOT_RE.sub(lambda m: anchors[int(m.group(1))], text)


def _inline(text: str) -> str:
    """HTML-escape ``text`` then re-apply the lightweight inline markup
    used across templates:

    - ``[文字](url)`` → ``<a>`` anchor (allowlisted hosts, see ``_MD_LINK``)
    - ``[r]…[/r]`` → red + bold (money / overage / breach semantics)
    - ``[b]…[/b]`` → bold
    - ``[h]…[/h]`` → bold, one size up (the headline number of a card)
    - ``**…**``    → bold (markdown-ish, used in a few bodies)

    The markup tokens survive ``html.escape`` (they contain no escaped
    chars), so escaping first keeps any user/contextual content safe
    while the decoration is added afterwards.

    Anchors are lifted out into opaque slots BEFORE the emphasis passes and
    put back after — an ``href`` must never be scanned for ``**`` pairs, or a
    URL carrying two asterisks gets ``<strong>`` spliced into the attribute.
    """
    out = _html.escape(text)
    out, _anchors = _extract_md_links(out)
    out = _replace_delimited(
        out, "[r]", "[/r]", f'<strong style="color:{_RED};">', "</strong>",
    )
    out = _replace_delimited(out, "[b]", "[/b]", "<strong>", "</strong>")
    out = _replace_delimited(
        out, "[h]", "[/h]", '<strong style="font-size:1.3em;">', "</strong>",
    )
    out = _replace_delimited(out, "**", "**", "<strong>", "</strong>")
    return _restore_md_links(out, _anchors)


def _bullet(html_text: str, mark: str) -> str:
    return (
        '<div style="margin:7px 0;color:#334155;font-size:14px;line-height:1.65;">'
        f'<span style="color:{mark};">▸</span>&nbsp; {html_text}</div>'
    )


def _strip_markup(text: str) -> str:
    """Drop ``[r]/[b]/[h]`` decoration (subjects render asterisks/tokens
    literally in most inbox previews)."""
    out = text
    for token in ("[r]", "[/r]", "[b]", "[/b]", "[h]", "[/h]"):
        out = out.replace(token, "")
    return _replace_delimited(out, "**", "**", "", "")


#: How much non-URL text a line may carry and still count as "just the CTA
#: link". Covers the shapes templates actually use — a bare URL, and the
#: ``{cta_line}`` family ("请尽快登录 Helix 完成交接。" + the URL, "Open in
#: Helix: <url>", 「Helix で確認する: <url>」) — while a real sentence that
#: happens to mention the destination stays well above it.
_BARE_CTA_RESIDUE_MAX = 40


def _is_bare_cta_line(stripped: str, drop_url: str) -> bool:
    """True when ``stripped`` exists only to carry ``drop_url``.

    2026-08-31 defect. The predicate was ``drop_url in stripped`` — a plain
    substring test — so ANY line mentioning the CTA URL was deleted from the
    email body. The offboarding letter's 「2. 公司资产归还」 paragraph names
    ``https://helix.pingcap.net/my/requests`` mid-sentence and that URL is also
    the letter's CTA target, so the whole instruction vanished and readers got a
    numbered heading with nothing under it. Five real leavers received that
    email. Nothing failed: the outbox row said ``delivered`` on both channels,
    because a delivery receipt proves the message ARRIVED, not that it was
    WHOLE.

    The card side already had the right shape (``_BARE_LINK_LINE_RE``, anchored
    on the full line). This is the email twin: keep the line unless removing the
    URL — and any ``[text](url)`` wrapper around it — leaves almost nothing
    behind.
    """
    if drop_url not in stripped:
        return False
    residue = stripped
    # A markdown-linked CTA ("[前往 Helix](https://…)") is still just the link.
    residue = _MD_LINK.sub(
        lambda m: "" if m.group(2) == drop_url else m.group(0), residue,
    )
    residue = residue.replace(drop_url, "")
    residue = residue.strip(" \t:：,,.。;;、-—>›|()()[]【】")
    return len(residue) <= _BARE_CTA_RESIDUE_MAX


def _render_body_html(body_text: str, accent: str, drop_url: str | None) -> str:
    """Turn a resolved plain-text body into HTML paragraphs + bullets.

    - blank line → paragraph break
    - line starting with ``▸ • · -`` etc. → styled bullet
    - a line that is *nothing but* the CTA link is omitted, since a dedicated
      button below carries the click-through (avoids the URL appearing twice).
      See :func:`_is_bare_cta_line` — this used to be ``drop_url in stripped``,
      a substring test that also deleted PROSE mentioning the CTA URL.
    """
    lines = body_text.replace("\r\n", "\n").split("\n")
    out: list[str] = []
    para: list[str] = []

    def flush_para() -> None:
        if para:
            out.append(
                '<div style="margin:10px 0;color:#334155;font-size:14px;'
                f'line-height:1.7;">{"<br>".join(para)}</div>'
            )
            para.clear()

    for raw in lines:
        stripped = raw.strip()
        if not stripped:
            flush_para()
            continue
        if drop_url and _is_bare_cta_line(stripped, drop_url):
            # The button replaces a bare CTA line ("请到 Helix 查看: <url>").
            continue
        is_bullet = any(stripped.startswith(p) for p in _BULLET_PREFIXES)
        if is_bullet and not stripped.startswith("**"):
            flush_para()
            # Strip the leading bullet glyph + following space.
            content = stripped[1:].lstrip(" \t") if stripped[0] in "▸•‣◦·" else stripped[2:]
            out.append(_bullet(_inline(content), accent))
        else:
            para.append(_inline(stripped))
    flush_para()
    return "".join(out)


#: Email-shell copy, in every language Helix ships. Kept beside each other so
#: adding a language is one dict entry per constant rather than a hunt through
#: three inline conditionals.
_SHELL_SUBJECT: dict[str, str] = {
    "zh": "Helix 通知",
    "en": "Helix notification",
    "ja": "Helix からのお知らせ",
}
_SHELL_CTA: dict[str, str] = {
    "zh": "前往 Helix 查看 →",
    "en": "Open in Helix →",
    "ja": "Helix で確認する →",
}
_SHELL_FOOTER: dict[str, str] = {
    "zh": (
        "本邮件由 {company} IT 团队通过 Helix 平台发送。"
        "有问题可直接回复,或在飞书 / Helix 服务台联系我们。<br>"
        "— {company} IT 团队"
    ),
    "en": (
        "Sent by the {company} IT team via the Helix platform. "
        "Reply anytime, or reach us at the Feishu / Helix service desk.<br>"
        "— The {company} IT team"
    ),
    "ja": (
        "このメールは {company} IT チームが Helix プラットフォームから送信しています。"
        "ご不明な点はこのまま返信いただくか、Feishu / Helix のサービスデスクまでご連絡ください。<br>"
        "— {company} IT チーム"
    ),
}


def render_email_shell(
    *,
    subject: str,
    body_text: str,
    cta_url: str | None = None,
    cta_label: str | None = None,
    lang: str | None = None,
    accent: str = _DEFAULT_ACCENT,
    accent_bg: str = _DEFAULT_ACCENT_BG,
    accent_border: str = _DEFAULT_ACCENT_BORDER,
    company_name: str = "PingCAP",
) -> str:
    """Render ``body_text`` inside the branded Helix HTML shell.

    ``subject`` becomes the header headline. ``body_text`` is the
    already-resolved (placeholders substituted) plain-text body; it is
    escaped and lightly formatted (paragraphs/bullets/inline-bold). When
    ``cta_url`` is given, a primary button is rendered and any plain-text
    line repeating that URL is suppressed.

    Returns a complete, self-contained HTML document fragment suitable
    for the ``text/html`` MIME alternative.
    """
    # The email SHELL — subject fallback, button label, sign-off — was a
    # two-way ``en / else`` split, so a Japanese reader got a Japanese body
    # wrapped in Chinese chrome. Three-way now, keyed on the same resolver
    # every other surface uses.
    target = normalize_lang(lang) or DEFAULT_LANG
    company_e = _html.escape(company_name)
    headline = _inline(_strip_markup(subject or _SHELL_SUBJECT[target]))
    kicker = f"{company_e.upper()} IT &middot; HELIX"

    label = cta_label or _SHELL_CTA[target]
    footer = _SHELL_FOOTER[target].format(company=company_e)

    body_html = _render_body_html(body_text or "", accent, cta_url)
    content_card = (
        '<table role="presentation" width="100%" cellpadding="0" cellspacing="0" '
        'style="margin:4px 0 0;border-collapse:separate;"><tr>'
        f'<td style="background:{accent_bg};border:1px solid {accent_border};'
        f'border-left:4px solid {accent};border-radius:12px;padding:18px 22px;">'
        f"{body_html}</td></tr></table>"
    )

    button = ""
    if cta_url:
        safe_url = _html.escape(cta_url, quote=True)
        button = (
            '<table role="presentation" align="center" cellpadding="0" cellspacing="0" '
            'style="margin:24px auto 8px;"><tr>'
            f'<td bgcolor="{_BTN_BG}" style="background:{_BTN_BG};border-radius:10px;">'
            f'<a href="{safe_url}" style="display:inline-block;padding:14px 34px;'
            'color:#ffffff;font-size:15px;font-weight:700;text-decoration:none;">'
            f"{_html.escape(label)}</a></td></tr></table>"
        )

    return (
        f'<div style="background:{_PAGE_BG};padding:28px 12px;font-family:{_FONT};">'
        '<table role="presentation" align="center" width="600" cellpadding="0" cellspacing="0" '
        f'style="width:600px;max-width:600px;margin:0 auto;background:{_CARD_BG};'
        'border-radius:16px;overflow:hidden;box-shadow:0 2px 10px rgba(15,23,42,.10);">'
        f'<tr><td bgcolor="{_HEADER_BG}" style="background:{_HEADER_BG};padding:30px 36px 26px;">'
        f'<div style="font-size:12px;letter-spacing:2.5px;color:{_KICKER};font-weight:700;">{kicker}</div>'
        f'<div style="font-size:23px;font-weight:800;color:#ffffff;margin:10px 0 0;line-height:1.3;">{headline}</div>'
        "</td></tr>"
        '<tr><td style="padding:24px 36px 4px;">'
        f"{content_card}{button}"
        "</td></tr>"
        '<tr><td style="padding:18px 36px 28px;border-top:1px solid #EEF1F6;">'
        f'<div style="font-size:12px;color:{_MUTED};line-height:1.7;">{footer}</div>'
        "</td></tr>"
        "</table></div>"
    )


__all__ = ["render_email_shell"]