{% extends "base.html" %}

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

Renders an aggregating section showing all API documentation types.

KIDA FEATURES USED:
- {% let %} for template-scoped variables
- Optional chaining (?.) for null-safe access
- Null coalescing (??) for smart defaults
- {% match %} for type-based rendering

USAGE:
Used for sections with type="api-hub"
================================================================================
#}

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

{# =============================================================================
   API CARD COMPONENT
   ============================================================================= #}
{% def api_card(subsection) %}
{% let sub_type = subsection?.params?.type ?? 'python-reference' %}
{% let sub_title = subsection?.title ?? 'API' %}
{% let sub_href = subsection?.href ?? '#' %}
{% let sub_desc = (subsection?.params?.description ?? '') | first_sentence %}
{% let sub_subsections = subsection?.subsections ?? [] %}
{% let sub_pages = subsection?.pages ?? [] %}
{% let child_count = (sub_subsections | length) + (sub_pages | length) %}

<a href="{{ sub_href }}" class="autodoc-card autodoc-card--hub" data-card="{{ sub_type }}">
  <div class="autodoc-card-header">
    <span class="autodoc-card-icon">
      {% match sub_type %}
      {% case _ if 'python' in sub_type %}
      {{ icon("code", size=32, css_class="icon-python") }}
      {% case _ if 'openapi' in sub_type %}
      {{ icon("globe", size=32, css_class="icon-openapi") }}
      {% case _ if 'cli' in sub_type %}
      {{ icon("terminal", size=32, css_class="icon-cli") }}
      {% case _ %}
      {{ icon("book", size=32, css_class="icon-default") }}
      {% end %}
    </span>
  </div>

  <div class="autodoc-card-body">
    <h3 class="autodoc-card-name">{{ sub_title }}</h3>
    <p class="autodoc-card-desc">
      {% if sub_desc %}
      {{ sub_desc }}
      {% else %}
      {% match sub_type %}
      {% case _ if 'python' in sub_type %}
      Browse Python packages, modules, and classes.
      {% case _ if 'openapi' in sub_type %}
      Explore REST API endpoints and schemas.
      {% case _ if 'cli' in sub_type %}
      Command-line tools and options.
      {% case _ %}
      API documentation.
      {% end %}
      {% end %}
    </p>
  </div>

  <div class="autodoc-card-footer">
    <span class="autodoc-card-meta">
      {% match sub_type %}
      {% case _ if 'python' in sub_type %}
      {{ child_count }} {{ 'module' if child_count == 1 else 'modules' }}
      {% case _ if 'openapi' in sub_type %}
      {{ child_count }} {{ 'endpoint' if child_count == 1 else 'endpoints' }}
      {% case _ if 'cli' in sub_type %}
      {{ child_count }} {{ 'command' if child_count == 1 else 'commands' }}
      {% case _ %}
      {{ child_count }} {{ 'item' if child_count == 1 else 'items' }}
      {% end %}
    </span>
    <span class="autodoc-badge" data-badge="{{ sub_type }}">
      {% match sub_type %}
      {% case _ if 'python' in sub_type %}Python
      {% case _ if 'openapi' in sub_type %}REST
      {% case _ if 'cli' in sub_type %}CLI
      {% case _ %}API
      {% end %}
    </span>
  </div>
</a>
{% enddef %}

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

{% block content %}
{# Template-scoped variables #}
{% let hub_section = section %}
{% let hub_title = section?.title ?? 'API Documentation' %}
{% let hub_desc = section?.params?.description ?? '' %}
{% let subsections = section?.sorted_subsections ?? [] %}
{% let page_href = page?.href ?? '/' %}

{# 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 #}
    <div class="page-hero">
      {% if page_href != '/' %}
      <nav class="page-hero__breadcrumbs" aria-label="Breadcrumb">
        {{ breadcrumbs(page) }}
      </nav>
      {% end %}

      <h1 class="page-hero__title">{{ hub_title }}</h1>

      {% if hub_desc %}
      <div class="page-hero__description page-hero__description--prose">
        {{ hub_desc | markdownify | safe }}
      </div>
      {% else %}
      <p class="page-hero__description">Browse all API documentation for this project.</p>
      {% end %}

      {% if subsections | length > 0 %}
      <div class="page-hero__footer">
        <div class="page-hero__stats">
          <span class="page-hero__stat">
            <span class="page-hero__stat-value">{{ subsections | length }}</span>
            <span class="page-hero__stat-label">{{ 'API' if subsections | length == 1 else 'APIs' }}</span>
          </span>
        </div>
      </div>
      {% end %}
    </div>

    {# Article Content #}
    <article data-autodoc data-type="hub" data-element="section-index" class="autodoc docs-content">
      {% if content and content.strip() %}
      <div class="autodoc-custom-content">
        {{ content | safe }}
      </div>
      {% end %}

      {# API Hub Card Grid #}
      {% if subsections | length > 0 %}
      <div class="autodoc-cards autodoc-cards--hub">
        {% for subsection in subsections %}
        {{ api_card(subsection) }}
        {% end %}
      </div>
      {% else %}
      <div class="autodoc-empty-state">
        <div class="autodoc-empty-state-icon">{{ icon("book-open", size=48, css_class="icon-muted") }}</div>
        <p class="autodoc-empty-state-text">No API documentation available yet.</p>
        <p class="autodoc-empty-state-hint">Enable Python, OpenAPI, or CLI autodoc in your configuration.</p>
      </div>
      {% end %}
    </article>

    {{ page_navigation(page) }}
  </div>

  {# Right Sidebar #}
  {% include 'partials/docs-toc-sidebar.html' %}
</div>

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

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