from functools import wraps
from typing import Optional

def menu_entry(
    label: str,
    icon: str = "",
    parent: Optional[str] = None,
    type: str = "main",
    position: Optional[int] = None,
    divider_before: bool = False,
    divider_after: bool = False,
    permission: Optional[str] = None,
    group: Optional[str] = None,
    badge: Optional[str] = None,
    badge_color: Optional[str] = None,
    badge_animate: bool = False,
):
    """
    Decorator to mark a route as a menu entry.

    Args:
        group: Section group name for sidebar rendering (e.g. "Overview", "System").
        badge: Badge text displayed on the menu item (e.g. "3", "NEW", "●").
        badge_color: CSS color class for the badge: "success", "danger", "warning", "info".
        badge_animate: If True, the badge blinks (useful for live indicators).

    Usage::

        @menu_entry(
            label="Dashboard",
            icon="fas fa-tachometer-alt",
            position=1,
            group="Overview",
        )
    """

    def decorator(func):
        func._menu_entry = {
            "label": label,
            "type": type,
            "icon": icon,
            "parent": parent,
            "position": position,
            "divider_before": divider_before,
            "divider_after": divider_after,
            "permission": permission,
            "group": group,
            "badge": badge,
            "badge_color": badge_color,
            "badge_animate": badge_animate,
        }

        @wraps(func)
        async def wrapper(*args, **kwargs):
            return await func(*args, **kwargs)

        return wrapper

    return decorator
