{#- chirp-ui: Layout primitives — container, grid (flow), frame (structural), stack, cluster, block.
    grid() = repeat(auto-fit, …) for wrapping siblings. frame() = explicit columns (hero, sidebar, …).
    See docs/LAYOUT-GRIDS-AND-FRAMES.md.
-#}
{% from "chirpui/surface.html" import surface %}
{% from "chirpui/breadcrumbs.html" import breadcrumbs %}

{% def container(max_width="72rem", padding=true, cls="") %}
<div class="chirpui-container{{ " " ~ cls if cls else "" }}"
     style="--chirpui-container-max: {{ max_width }}{% if not padding %}; padding-inline: 0{% end %}">
    {% slot %}
</div>
{% end %}

{#- grid(): flow — auto-fit columns; cols=2|3|4 scales --chirpui-grid-min. Fixed tracks: preset + aliases — docs/LAYOUT-PRESETS.md. detail_single only for detail-two | split-1-1.35. items=start|end|center. -#}
{% def grid(cols=none, gap=none, preset=none, items=none, detail_single=false, cls="") %}
{% set pn = preset %}
{% set _bento = pn == "bento-211" or pn == "split-2-1-1" %}
{% set _thirds = pn == "thirds" or pn == "split-thirds" or pn == "three-equal" %}
{% set _detail = pn == "detail-two" or pn == "split-1-1.35" %}
{% set _detail_one_col = pn == "detail-two-single" or pn == "split-1-1.35-single" %}
{% set _has_preset = _bento or _thirds or _detail or _detail_one_col %}
{% set _detail_single_on = detail_single or _detail_one_col %}
<div class="chirpui-grid{% if not _has_preset %}{% if cols == 2 %} chirpui-grid--cols-2{% elif cols == 3 %} chirpui-grid--cols-3{% elif cols == 4 %} chirpui-grid--cols-4{% end %}{% end %}{% if gap == "sm" %} chirpui-grid--gap-sm{% elif gap == "md" %} chirpui-grid--gap-md{% elif gap == "lg" %} chirpui-grid--gap-lg{% end %}{% if _bento %} chirpui-grid--preset-bento-211{% elif _thirds %} chirpui-grid--preset-thirds{% elif _detail or _detail_one_col %} chirpui-grid--preset-detail-two{% if _detail_single_on %} chirpui-grid--detail-two-single{% end %}{% end %}{% if items == "start" %} chirpui-grid--items-start{% elif items == "end" %} chirpui-grid--items-end{% elif items == "center" %} chirpui-grid--items-center{% end %}{{ " " ~ cls if cls else "" }}">
    {% slot %}
</div>
{% end %}

{#- frame(): structural regions with explicit tracks — two direct children by default.
    variant= balanced | hero | sidebar-end. Override columns via style="--chirpui-frame-hero-columns: …" on this element or a parent.
-#}
{% def frame(variant="balanced", gap=none, cls="") %}
<div class="chirpui-frame{% if variant == "hero" %} chirpui-frame--hero{% elif variant == "sidebar-end" %} chirpui-frame--sidebar-end{% else %} chirpui-frame--balanced{% end %}{% if gap == "sm" %} chirpui-frame--gap-sm{% elif gap == "md" %} chirpui-frame--gap-md{% elif gap == "lg" %} chirpui-frame--gap-lg{% end %}{{ " " ~ cls if cls else "" }}">
    {% slot %}
</div>
{% end %}

{% def stack(gap=none, cls="") %}
<div class="chirpui-stack{% if gap == "xs" %} chirpui-stack--xs{% elif gap == "sm" %} chirpui-stack--sm{% elif gap == "md" %} chirpui-stack--md{% elif gap == "lg" %} chirpui-stack--lg{% elif gap == "xl" %} chirpui-stack--xl{% end %}{{ " " ~ cls if cls else "" }}">
    {% slot %}
</div>
{% end %}

{% def cluster(gap=none, cls="") %}
<div class="chirpui-cluster{% if gap == "xs" %} chirpui-cluster--xs{% elif gap == "sm" %} chirpui-cluster--sm{% elif gap == "md" %} chirpui-cluster--md{% elif gap == "lg" %} chirpui-cluster--lg{% end %}{{ " " ~ cls if cls else "" }}">
    {% slot %}
</div>
{% end %}

{% def block(span=1, cls="") %}
<div class="chirpui-block{% if span == 2 %} chirpui-block--span-2{% elif span == 3 %} chirpui-block--span-3{% elif span == "full" %} chirpui-block--span-full{% end %}{{ " " ~ cls if cls else "" }}">
    {% slot %}
</div>
{% end %}

{#- page_header: title, subtitle, meta, breadcrumb_items, variant, actions slot -#}
{% def page_header(title, subtitle=none, meta=none, breadcrumb_items=none, variant="default", cls="") %}
{% set variant = variant | validate_variant_block("page_header", default="default") %}
{% set variant_class = " chirpui-page-header--" ~ variant if variant != "default" else "" %}
<header class="chirpui-stack chirpui-stack--sm chirpui-page-header{{ variant_class }}{{ " " ~ cls if cls else "" }}">
    <div class="chirpui-page-header__top">
        <div>
            {% if breadcrumb_items %}
            {{ breadcrumbs(breadcrumb_items, cls="chirpui-page-header__breadcrumbs") }}
            {% end %}
            <h1>{{ title }}</h1>
            {% if subtitle %}
            <p class="chirpui-text-muted chirpui-font-sm">{{ subtitle }}</p>
            {% end %}
            {% if meta %}
            <p class="chirpui-text-muted chirpui-font-sm chirpui-page-header__meta">{{ meta | safe }}</p>
            {% end %}
        </div>
        <div class="chirpui-page-header__actions">{% slot actions %}</div>
    </div>
</header>
{% end %}

{#- section_header: title, subtitle, icon, variant, actions slot -#}
{% def section_header(title, subtitle=none, icon=none, variant="default", cls="") %}
{% set variant = variant | validate_variant_block("section_header", default="default") %}
{% set variant_class = " chirpui-section-header--inline" if variant == "inline" else "" %}
<div class="chirpui-section-header{{ variant_class }}{{ " " ~ cls if cls else "" }}">
    <div class="chirpui-section-header__top">
        <div class="chirpui-section-header__title-block">
            {% if icon %}<span class="chirpui-section-header__icon">{{ icon | icon }}</span>{% end %}
            <div>
                <h2{% if variant == "inline" %} class="chirpui-section-header__title-inline"{% end %}>{{ title }}</h2>
                {% if subtitle and variant != "inline" %}
                <p class="chirpui-text-muted chirpui-font-sm">{{ subtitle }}</p>
                {% end %}
            </div>
        </div>
        <div class="chirpui-section-header__actions">{% slot actions %}</div>
    </div>
</div>
{% end %}

{#- section_header_inline: deprecated alias — use section_header(variant="inline") with {% slot actions %} -#}
{% def section_header_inline(title, icon=none, cls="") %}
{% call section_header(title, icon=icon, variant="inline", cls=cls) %}
{% slot actions %}{% slot %}{% end %}
{% end %}
{% end %}

{#- section: composite surface + section_header + content. Reduces boilerplate.
    Use {% slot actions %} for section-level buttons (Refresh, Auto-detect, etc.).
    full_width=true wraps in chirpui-blade for edge-to-edge blade-style sections.
    parallax=true adds subtle scroll-driven background motion (Chrome 115+). -#}
{% def section(title, subtitle=none, icon=none, surface_variant="muted", full_width=false, parallax=false, cls="") %}
{% set surface_variant = surface_variant | validate_variant_block("surface", default="muted") %}
{% if full_width %}
<div class="chirpui-blade{{ " chirpui-blade--parallax" if parallax else "" }}{{ " " ~ cls if cls else "" }}">
{% end %}
{% call surface(variant=surface_variant, full_width=full_width) %}
{% call section_header(title, subtitle, icon) %}
{% slot actions %}{% slot actions %}{% end %}
{% end %}
{% slot %}{% slot %}{% end %}
{% end %}
{% if full_width %}
</div>
{% end %}
{% end %}

{#- section_collapsible: details/summary with section_header as summary. For "Advanced" config. -#}
{% def section_collapsible(title, open=false, surface_variant="muted", cls="") %}
{% set surface_variant = surface_variant | validate_variant_block("surface", default="muted") %}
<details class="chirpui-section-collapsible{{ " " ~ cls if cls else "" }}"{% if open %} open{% end %}>
    <summary class="chirpui-section-collapsible__summary">
        {% call section_header_inline(title) %}{% end %}
    </summary>
    {% call surface(variant=surface_variant) %}
    {% slot %}
    {% end %}
    {% end %}
</details>
{% end %}