{% extends "base.html" %}

{#
================================================================================
API Reference Section Index Template (Kida-Native)
================================================================================

Renders an API section index page showing subsections and modules
using a card-based layout. Extends base.html to inherit theme navigation.

TEMPLATE VARIABLES:
  - section: Section object for the API section (required)
  - page: PageContext proxy with title, metadata, _path
  - config: Autodoc configuration
  - site: Site instance

KIDA FEATURES USED:
  - Optional chaining (?.) for safe attribute access on nullable objects
  - Null coalescing (??) for providing defaults
  - {% let %} for template-scoped computed values
  - {% match %} for element type icon dispatch
  - Pipeline-friendly filtering

================================================================================
#}

{% from 'partials/navigation-components.html' import breadcrumbs, page_navigation, toc %}

{% block content %}
{# Template-scoped caching of computed values #}
{% let section_subsections = section?.sorted_subsections ?? [] %}
{% let section_pages = section?.sorted_pages ?? [] %}

{#
Build module pages list (non-index pages only)
Use list comprehension style via filters for Kida
#}
{% let module_pages = section_pages
    | rejectattr('source_path', 'match', '.*_index.*')
    | reject('eq', section?.index_page)
    | list %}

{# Three-column documentation layout #}
<div class="docs-layout">
  {# Left Sidebar: Navigation #}
  <aside class="docs-sidebar" id="docs-sidebar" role="navigation" aria-label="API navigation">
    {% include 'partials/docs-nav.html' %}
  </aside>

  {# Main Content #}
  <div class="docs-main">
    {# Page Hero: Use direct macro call with explicit context #}
    {% from 'partials/page-hero/_macros.html' import hero_section %}
    {{ hero_section(section, page, {}) }}

    {# Article Content - autodoc skeleton #}
    <article data-autodoc data-type="python" data-element="section-index" class="autodoc docs-content">

      {# Subsections (Packages) - Card Grid #}
      {% if section_subsections | length > 0 %}
      <section class="autodoc-section" data-section="packages">
        <h2 class="autodoc-section-title">Packages</h2>

        <div class="autodoc-cards">
          {% for subsection in section_subsections %}
          {% set subsection_name = subsection?.name ?? '' %}
          {% if subsection_name %}
          {% set desc = (subsection?.metadata?.description ?? '') | first_sentence %}
          {% set child_count = ((subsection?.subsections ?? []) | length) + ((subsection?.pages ?? []) | length) %}
          <a href="{{ subsection.href }}" class="autodoc-card" data-card="package">
            <div class="autodoc-card-header">
              <span class="autodoc-card-icon">{{ icon("folder", size=20, css_class="icon-muted") }}</span>
              <span class="autodoc-card-name">{{ subsection_name | title }}</span>
            </div>
            <div class="autodoc-card-body">
              <p class="autodoc-card-desc">{{ desc if desc else subsection_name ~ ' package' | title }}</p>
            </div>
            <div class="autodoc-card-footer">
              <span class="autodoc-card-meta">
                {{ child_count }} item{{ 's' if child_count != 1 else '' }}
              </span>
            </div>
          </a>
          {% end %}
          {% end %}
        </div>
      </section>
      {% end %}

      {# Module Pages - Card Grid #}
      {% if module_pages | length > 0 %}
      <section class="autodoc-section" data-section="modules">
        <h2 class="autodoc-section-title">Modules</h2>

        <div class="autodoc-cards">
          {% for mod_page in module_pages %}
          {% set desc = (mod_page?.metadata?.description ?? '') | first_sentence %}
          {% set elem_type = mod_page?.metadata?.element_type ?? 'module' %}
          <a href="{{ mod_page.href }}" class="autodoc-card" data-card="{{ elem_type }}">
            <div class="autodoc-card-header">
              <span class="autodoc-card-icon">
                {% match elem_type %}
                  {% case 'class' %}
                    {{ icon("layers", size=16, css_class="icon-info") }}
                  {% case 'function' %}
                    {{ icon("zap", size=16, css_class="icon-success") }}
                  {% case _ %}
                    {{ icon("code", size=16, css_class="icon-muted") }}
                {% end %}
              </span>
              <span class="autodoc-card-name">{{ mod_page.title }}</span>
              {% if elem_type != 'module' %}
              <span class="autodoc-badge" data-badge="{{ elem_type }}">{{ elem_type }}</span>
              {% end %}
            </div>
            <div class="autodoc-card-body">
              <p class="autodoc-card-desc">{{ desc if desc else 'No description available' }}</p>
            </div>
          </a>
          {% end %}
        </div>
      </section>
      {% end %}

      {# Empty State #}
      {% if section_subsections | length == 0 and module_pages | length == 0 %}
      <div class="autodoc-empty-state">
        <div class="autodoc-empty-state-icon">{{ icon("file-text", size=48, css_class="icon-muted") }}</div>
        <p class="autodoc-empty-state-text">No documentation available in this section yet.</p>
      </div>
      {% end %}

    </article>

    {# Page navigation (prev/next) at bottom - null-safe #}
    {% if page %}
    {{ page_navigation(page) }}
    {% end %}
  </div>

  {# Right Sidebar: Contextual Graph + TOC + Metadata #}
  {% include 'partials/docs-toc-sidebar.html' %}
</div>

{# Mobile sidebar toggle button #}
<button class="docs-sidebar-toggle" aria-label="Toggle navigation sidebar" aria-expanded="false"
  aria-controls="docs-sidebar">
  {{ icon('list', size=20) }}
</button>

{# Sidebar overlay for mobile #}
<div class="docs-sidebar-overlay" aria-hidden="true"></div>
{% end %}