"""ラベル解決プロトコル定義。

LabelResolver Protocol を提供する。上位パッケージが具体的な実装を注入する。
"""

from __future__ import annotations

from collections.abc import Sequence
from typing import Protocol, runtime_checkable

from xbrl_core._linkbase_utils import ROLE_LABEL
from xbrl_core.models.financial import LabelInfo

__all__ = ["LabelResolver"]


@runtime_checkable
class LabelResolver(Protocol):
    """ラベル解決プロトコル。

    concept QName からラベルテキストを解決する。
    上位パッケージ（edinet 等）が具体的な実装を提供する。
    """

    def resolve(
        self,
        concept_qname: str,
        lang: str,
        role: str = ROLE_LABEL,
    ) -> LabelInfo | None:
        """concept QName からラベルを解決する。

        Args:
            concept_qname: Clark notation の QName
                （例: ``"{http://...}NetSales"``）。
            lang: 言語コード（例: ``"ja"``, ``"en"``）。
            role: ラベルロール URI。

        Returns:
            解決された LabelInfo。見つからなければ None。
        """
        ...

    def resolve_batch(
        self,
        concept_qnames: Sequence[str],
        lang: str,
        role: str = ROLE_LABEL,
    ) -> dict[str, LabelInfo | None]:
        """複数の concept QName を一括解決する。

        デフォルト実装は ``resolve()`` を繰り返し呼び出す。
        パフォーマンスが重要な場合はサブクラスでオーバーライドする。

        Args:
            concept_qnames: Clark notation の QName のシーケンス。
            lang: 言語コード。
            role: ラベルロール URI。

        Returns:
            QName をキー、LabelInfo（または None）を値とする辞書。
        """
        ...
