{#- chirp-ui: Layout primitives — container, grid (flow), frame (structural), stack, cluster, layer (overlap deck), 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 %}
{% set _cls = [c for c in [
    "chirpui-grid",
    "chirpui-grid--cols-" ~ cols if cols and not _has_preset else "",
    "chirpui-grid--gap-" ~ gap if gap else "",
    "chirpui-grid--preset-bento-211" if _bento else "chirpui-grid--preset-thirds" if _thirds else "chirpui-grid--preset-detail-two" if _detail or _detail_one_col else "",
    "chirpui-grid--detail-two-single" if _detail_single_on and (_detail or _detail_one_col) else "",
    "chirpui-grid--items-" ~ items if items else "",
    cls
] if c] %}
<div class="{{ _cls | join(' ') }}">
    {% slot %}
</div>
{% end %}

{#- frame(): structural regions with explicit tracks — two direct children by default.
    variant= balanced | hero | sidebar-start | sidebar-end. Override columns via frame tokens on this element or a parent.
-#}
{% def frame(variant="balanced", gap=none, cls="") %}
{% set _cls = [c for c in [
    "chirpui-frame",
    "chirpui-frame--" ~ variant if variant else "chirpui-frame--balanced",
    "chirpui-frame--gap-" ~ gap if gap else "",
    cls
] if c] %}
<div class="{{ _cls | join(' ') }}">
    {% slot %}
</div>
{% end %}

{% def stack(gap=none, cls="") %}
{% set _cls = [c for c in ["chirpui-stack", "chirpui-stack--" ~ gap if gap else "", cls] if c] %}
<div class="{{ _cls | join(' ') }}">
    {% slot %}
</div>
{% end %}

{% def cluster(gap=none, cls="") %}
{% set _cls = [c for c in ["chirpui-cluster", "chirpui-cluster--" ~ gap if gap else "", cls] if c] %}
<div class="{{ _cls | join(' ') }}">
    {% slot %}
</div>
{% end %}

{#- layer(): overlapping card deck — children overlap with negative margin + rotation, hover straightens and elevates.
    direction= left | center | right. overlap= sm | md | lg. angle= none | subtle | moderate. hover=true adds hover-to-front. -#}
{% def layer(direction="left", overlap="md", angle="subtle", hover=true, cls="") %}
{% set _cls = [c for c in [
    "chirpui-layer",
    "chirpui-layer--" ~ direction if direction else "chirpui-layer--left",
    "chirpui-layer--overlap-" ~ overlap if overlap else "",
    "chirpui-layer--angle-" ~ angle if angle else "",
    "chirpui-layer--hover" if hover else "",
    cls
] if c] %}
<div class="{{ _cls | join(' ') }}">
    {% slot %}
</div>
{% end %}

{% def block(span=1, cls="") %}
{% set _cls = [c for c in ["chirpui-block", "chirpui-block--span-" ~ span if span != 1 else "", cls] if c] %}
<div class="{{ _cls | join(' ') }}">
    {% 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="", 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(reason="trusted meta markup") }}</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="", 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 %}{% yield %}{% 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 %}{% yield actions %}{% end %}
{% end %}
{% yield %}
{% 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 %}