"""Pure calendar utility functions (no ORM dependencies).

Extracted from events/bp/calendar/services/calendar_view.py so that
blog admin (and any other app) can use them without cross-app imports.
"""
from __future__ import annotations

import calendar as pycalendar
from datetime import datetime, timezone

from quart import request


def parse_int_arg(name: str, default: int | None = None) -> int | None:
    """Parse an integer query parameter from the request."""
    val = request.args.get(name, "").strip()
    if not val:
        return default
    try:
        return int(val)
    except ValueError:
        return default


def add_months(year: int, month: int, delta: int) -> tuple[int, int]:
    """Add (or subtract) months to a given year/month, handling year overflow."""
    new_month = month + delta
    new_year = year + (new_month - 1) // 12
    new_month = ((new_month - 1) % 12) + 1
    return new_year, new_month


def build_calendar_weeks(year: int, month: int) -> list[list[dict]]:
    """Build a calendar grid for the given year and month.

    Returns a list of weeks, where each week is a list of 7 day dicts.
    """
    today = datetime.now(timezone.utc).date()
    cal = pycalendar.Calendar(firstweekday=0)  # 0 = Monday
    weeks: list[list[dict]] = []

    for week in cal.monthdatescalendar(year, month):
        week_days = []
        for d in week:
            week_days.append(
                {
                    "date": d,
                    "in_month": (d.month == month),
                    "is_today": (d == today),
                }
            )
        weeks.append(week_days)

    return weeks