"""The written half of a category page: what the category is, before the prices.

The structure proposal treats this as the one editorial field a category page cannot do
without, "because a category page with no explanation is the definition of thin"
(`web/src/lib/structure.ts`, `p-category`). It is also the part most able to ruin the page:
a primer rendered as one block of prose puts a history of distillation between a reader and
the prices they came for, which is the recipe-page failure rian named for the airport
template.

So a guide is stored in parts rather than as prose. `summary` and `takeaway` are the two
that earn their place unprompted; the sections open on a click and carry the rest. The
renderer decides what it shows and where; nothing here is written to suit a layout.

Why in code rather than a table: it is a few paragraphs per category, changed a few times a
year, reviewed like the rest of the site's copy. Both renderers read it, the SPA through the
pairing page's payload and the crawler's body through `seo.category_primer_html`, so the two
pages cannot drift. The optional per-page note from the Professor is a different field and
stays where it is, an article row read by `routers/articles.py`.

Nothing here is guessed, and nothing is generated. A category with no entry simply has no
primer and the page renders without one; it must still look finished, because most
categories have none.

Provenance: the copy is the client's own category primers, kept sentence for sentence. The
grouping into sections and the one-line teasers are ours, which is the line the airport
profiles already drew: the writing binds the content, not the design. Where a clause could
not be published as written it was held back rather than rewritten into a new claim, and the
holdback is a question on the running list, never a silent edit.
"""

from app.models.hubs import CategoryGuide, CategorySection

#: Keyed by the taxonomy's category name (`services/taxonomy.py`), which is also what
#: `urls.CATEGORY_SLUGS` keys the address by, so a category's page and its primer can never
#: disagree about which category they are.
GUIDES: dict[str, CategoryGuide] = {
    "Whisky": CategoryGuide(
        summary=(
            "Whisky, at its simplest, is a spirit distilled from fermented grain mash, then "
            "aged in wooden barrels until the wood does most of the talking. Water, grain, "
            "yeast and time: that is the entire recipe, and yet those four ingredients "
            "produce wildly different results depending on where in the world you are "
            "standing."
        ),
        takeaway=(
            "Age statements and price tags matter less than grain, cask and climate. Read "
            "the label, not just the number."
        ),
        sections=[
            CategorySection(
                title="A short history",
                teaser="500 years, and an old argument",
                body=(
                    "The history stretches back roughly 500 years, to monks in Ireland and "
                    "Scotland who first applied distillation, a technique borrowed from "
                    "continental Europe, to their local grain surplus. Which country "
                    "invented whisky first is still a bar argument nobody has settled, and "
                    "probably never will."
                ),
            ),
            CategorySection(
                title="Scotland and Ireland",
                teaser="Peat, and two runs or three",
                body=(
                    "Irish and Scotch traditions diverged early. Scotch is typically "
                    "distilled twice and often uses peat-dried malt, giving Islay whiskies "
                    "their smoky, medicinal edge, while Speyside leans fruitier and Highland "
                    "whiskies split the difference. Irish whiskey, distilled a third time, "
                    "comes out smoother and lighter by comparison."
                ),
            ),
            CategorySection(
                title="The rest of the world",
                teaser="Corn, blends, precision, heat",
                body=(
                    "America took the tradition and adapted it to corn, the crop that was "
                    "actually growing in Kentucky and Tennessee. Bourbon, at least 51 per "
                    "cent corn, distilled anywhere in the United States and aged in a new "
                    "American white oak barrel that is only ever used once, comes out sweet "
                    "and caramel-forward; rye, its spicier cousin, has been having a real moment "
                    "over the last decade. Canadian whisky blends grains more freely and "
                    "tends toward a lighter, gentler profile. Japan borrowed Scotch technique "
                    "wholesale a century ago and then refined it, maturing inland rather than "
                    "beside the sea as its Scottish cousins do, into something more precise "
                    "and often more delicate. Warmer climates age a spirit faster still, so a "
                    "six-year-old whisky from Taiwan can taste as developed as something "
                    "twice its age from Scotland."
                ),
            ),
        ],
    ),
}


def guide_for(category: str | None) -> CategoryGuide | None:
    """The primer for one of our category names, or None where nobody has written one."""
    return GUIDES.get(category or "")