{% extends "base.html" %}

{#
================================================================================
Docs Home Template (Kida-Native)
================================================================================

Optimized home page template for documentation sites.

FEATURES:
- Hero section with title and description
- Auto-discovered documentation sections
- Custom quick links support
- Clean, focused layout (no action bar)

KIDA FEATURES USED:
- {% let %} for template-scoped variables
- Optional chaining (?.) for null-safe attribute access
- Null coalescing (??) for defaults
- Pipeline operator (|>) for readable filter chains
- {% def %} for reusable template functions
- {% match %} for type dispatch
- {% spaceless %} for clean HTML output

USAGE:
Set `type: doc` on home page to auto-select
Or set `template: doc/home.html` in frontmatter
================================================================================
#}

{# =============================================================================
HELPER FUNCTIONS
============================================================================= #}

{# Render a section card with icon, title, description, and page count #}
{% def section_card(section) %}
{% let section_title = section?.title ?? 'Untitled' %}
{% let section_desc = section?.metadata?.description ?? '' %}
{% let section_pages = section?.pages ?? [] %}
{% let page_count = section_pages | length %}
<a href="{{ section.href ?? section._path }}" class="docs-home-section-card gradient-border fluid-combined">
    <h3 class="docs-home-section-title">{{ section_title }}</h3>
    {% if section_desc %}
    <p class="docs-home-section-description">{{ section_desc }}</p>
    {% end %}
    {% if page_count > 0 %}
    <span class="docs-home-section-count">
        {{ page_count }} page{{ 's' if page_count != 1 else '' }}
    </span>
    {% end %}
</a>
{% end %}

{# Render a quick link card #}
{% def quick_link_card(link) %}
{% let link_url = link?.href ?? link?.url ?? '#' %}
{% let link_title = link?.title ?? 'Link' %}
{% let link_desc = link?.description ?? '' %}
{% let link_icon = link?.icon %}
<a href="{{ link_url }}" class="docs-home-quick-link-card gradient-border">
    {% if link_icon %}
    <div class="docs-home-quick-link-icon">{{ link_icon }}</div>
    {% end %}
    <h3>{{ link_title }}</h3>
    {% if link_desc %}
    <p>{{ link_desc }}</p>
    {% end %}
</a>
{% end %}

{# =============================================================================
MAIN TEMPLATE
============================================================================= #}

{% block content %}
{# Template-scoped variables with safe defaults #}
{% let page_title = page?.title ?? config?.title ?? 'Documentation' %}
{% let page_desc = params?.description ?? '' %}
{% let show_quick_links = params?.show_quick_links ?? true %}
{% let custom_quick_links = params?.quick_links ?? [] %}

<div class="docs-home">
    {# Hero Section #}
    <header class="docs-home-hero">
        <div class="docs-home-hero-content">
            <h1 class="docs-home-title">{{ page_title }}</h1>
            {% if page_desc %}
            <p class="docs-home-subtitle">{{ page_desc }}</p>
            {% end %}
        </div>
    </header>

    {# Main Content (if any) #}
    {% if content and content.strip() %}
    <div class="docs-home-content prose">
        {{ content | safe }}
    </div>
    {% end %}

    {# Documentation Sections - Auto-discovered #}
    {% if show_quick_links %}
    {% cache "doc-home-sections-" ~ (site?.build_id ?? '') %}
    {#
    Find documentation sections by type or common names.
    Uses pipeline operator for readable left-to-right flow.
    #}
    {% let site_sections = site?.sections ?? [] %}

    {# First try: sections explicitly marked as type: doc #}
    {% let doc_sections = site_sections
    |> selectattr('metadata.type', 'eq', 'doc')
    |> list %}

    {# Fallback: try content_type: doc #}
    {% if doc_sections | length == 0 %}
    {% let doc_sections = site_sections
    |> selectattr('metadata.content_type', 'eq', 'doc')
    |> list %}
    {% end %}

    {# Second fallback: common section names #}
    {% if doc_sections | length == 0 %}
    {% let common_names = ['getting-started', 'guides', 'concepts', 'api', 'docs', 'documentation'] %}
    {% let doc_sections = [] %}
    {% for name in common_names %}
    {% let candidates = site_sections |> selectattr('name', 'eq', name) |> list %}
    {% if candidates | length > 0 %}
    {% set _ = doc_sections.append(candidates[0]) %}
    {% end %}
    {% end %}
    {% end %}

    {# Render section cards if we found any #}
    {% if doc_sections | length > 0 %}
    {# Sort by weight, then take top 6 (sections must have metadata.weight) #}
    {% let sorted_sections = doc_sections
    |> sort(attribute='metadata.weight')
    |> take(6) %}

    <section class="docs-home-sections">
        <h2 class="docs-home-sections-title">Documentation Sections</h2>
        <div class="docs-home-sections-grid">
            {% for section in sorted_sections %}
            {{ section_card(section) }}
            {% end %}
        </div>
    </section>
    {% end %}
    {% endcache %}
    {% end %}

    {# Custom Quick Links from Frontmatter #}
    {% if custom_quick_links | length > 0 %}
    <section class="docs-home-quick-links">
        <h2 class="docs-home-quick-links-title">Quick Links</h2>
        <div class="docs-home-quick-links-grid">
            {% for link in custom_quick_links %}
            {{ quick_link_card(link) }}
            {% end %}
        </div>
    </section>
    {% end %}
</div>
{% end %}