#  Copyright 2026 European Union
#  Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
#  SPDX-License-Identifier: EUPL-1.2
"""Utility helpers for creating the steering GUI actions without duplicating wiring.

:Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
:Description: Share QAction definitions so the menu wiring stays clean.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Callable

from PySide6.QtCore import QObject
from PySide6.QtGui import QAction, QKeySequence


@dataclass(frozen=True)
class ActionSpec:
    """Describe the metadata needed to build a menu action."""

    text: str
    """The label shown in the menu."""

    triggered: Callable[[], None]
    """Callback invoked when the user activates the action."""

    shortcut: QKeySequence.StandardKey | str | None = None
    """Optional :class:`QKeySequence.StandardKey` or str describing the shortcut."""

    status_tip: str | None = None
    """Optional text for the status bar."""

    enabled: bool = True
    """Initial enabled state for the action."""


def create_action(parent: QObject, spec: ActionSpec) -> QAction:
    """Instantiate a QAction from the provided :class:`ActionSpec`."""

    action = QAction(spec.text, parent)
    if spec.shortcut is not None:
        action.setShortcut(QKeySequence(spec.shortcut))
    if spec.status_tip is not None:
        action.setStatusTip(spec.status_tip)
    action.setEnabled(spec.enabled)
    action.triggered.connect(spec.triggered)
    return action
