# retoor <retoor@molodetz.nl>

from __future__ import annotations

from .spec import Action, Param


def arg(
    name: str, description: str, required: bool = False, kind: str = "string"
) -> Param:
    return Param(
        name=name,
        location="body",
        description=description,
        required=required,
        type=kind,
    )


SCOPE = (
    "Either 'global' (applies to every page of the site for this user) or a page-type string "
    "as returned by get_page_context.pageType (e.g. '/posts/{slug}'), which applies to every "
    "page of that type."
)

CUSTOMIZATION_ACTIONS: tuple[Action, ...] = (
    Action(
        name="customize_list",
        method="LOCAL",
        path="",
        summary="List the user's saved CSS/JS customizations (scopes, languages, sizes)",
        description=(
            "Returns every stored customization for the current user (or guest session), with its "
            "scope, language, enabled flag and a short preview of the code."
        ),
        handler="customization",
        requires_auth=False,
        read_only=True,
    ),
    Action(
        name="customize_get",
        method="LOCAL",
        path="",
        summary="Read the full saved CSS or JS code for one scope",
        description="Use this before editing so you build on existing customization rather than overwriting it.",
        handler="customization",
        requires_auth=False,
        read_only=True,
        params=(
            arg("scope", SCOPE, required=True),
            arg("lang", "Which code to read: 'css' or 'js'.", required=True),
        ),
    ),
    Action(
        name="customize_set_css",
        method="LOCAL",
        path="",
        summary="Permanently save custom CSS for a page type or the whole site",
        description=(
            "Persists custom CSS for the current user. Before calling, ask the user whether it should "
            "apply to the current page TYPE or to the whole site (global). The CSS is the final, full "
            "stylesheet for that scope and replaces any previously saved CSS for it."
        ),
        handler="customization",
        requires_auth=False,
        params=(
            arg("scope", SCOPE, required=True),
            arg("css", "The full CSS source to save for this scope.", required=True),
            arg(
                "confirm",
                "Must be true after the user has confirmed the scope.",
                required=True,
                kind="boolean",
            ),
        ),
    ),
    Action(
        name="customize_set_js",
        method="LOCAL",
        path="",
        summary="Permanently save custom JavaScript for a page type or the whole site",
        description=(
            "Persists custom JavaScript for the current user. Before calling, ask the user whether it "
            "should apply to the current page TYPE or to the whole site (global). The code runs after "
            "the application boots, with access to window, document and the global 'app'. It is the "
            "final, full script for that scope and replaces any previously saved JS for it."
        ),
        handler="customization",
        requires_auth=False,
        params=(
            arg("scope", SCOPE, required=True),
            arg(
                "js",
                "The full JavaScript source to save for this scope.",
                required=True,
            ),
            arg(
                "confirm",
                "Must be true after the user has confirmed the scope.",
                required=True,
                kind="boolean",
            ),
        ),
    ),
    Action(
        name="customize_reset",
        method="LOCAL",
        path="",
        summary="Delete saved customizations, restoring the default look and behaviour",
        description=(
            "Removes saved customizations. Omit lang to remove both CSS and JS for the scope. Pass "
            "scope='all' to remove every customization for this user. This cannot be undone."
        ),
        handler="customization",
        requires_auth=False,
        params=(
            arg(
                "scope",
                SCOPE + " Use 'all' to remove every customization.",
                required=True,
            ),
            arg(
                "lang",
                "Optional: limit the reset to 'css' or 'js'. Omit to remove both.",
            ),
            arg(
                "confirm",
                "Must be true after the user has confirmed the deletion.",
                required=True,
                kind="boolean",
            ),
        ),
    ),
    Action(
        name="customize_set_enabled",
        method="LOCAL",
        path="",
        summary="Show or suppress the user's customizations without deleting them",
        description=(
            "Toggles whether the user's saved customizations render, keeping the stored code intact. "
            "category='global' controls the site-wide customizations; category='pagetype' controls every "
            "per-page-type customization at once. enabled=false hides them; enabled=true shows them again. "
            "Mirrors the toggle buttons on the user's profile page."
        ),
        handler="customization",
        requires_auth=True,
        params=(
            arg(
                "category",
                "Which set to toggle: 'global' (whole site) or 'pagetype' (all per-page customizations).",
                required=True,
            ),
            arg(
                "enabled",
                "true to show the customizations, false to suppress them.",
                required=True,
                kind="boolean",
            ),
        ),
    ),
)
