{% extends "base.html" %}

{#
================================================================================
API Reference Module Template (Kida-Native)
================================================================================

Renders a Python module's API documentation using the unified autodoc skeleton.
Extends base.html to inherit theme navigation, sidebars, and styling.

TEMPLATE VARIABLES:
- element: DocElement for the module (required)
- page: PageContext proxy with title, metadata, tags, _path
- config: Autodoc configuration
- site: Site instance
- section: Parent section (for navigation)

KIDA FEATURES USED:
- Optional chaining (?.) for safe attribute access
- Null coalescing (??) for defaults
- {% def %} macros for DRY component reuse
- {% match %} for element type dispatch
- {% let %} for template-scoped caching

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

{% from 'partials/navigation-components.html' import breadcrumbs, page_navigation, toc %}
{% from 'autodoc/partials/_macros/class-member.html' import class_member %}
{% from 'autodoc/partials/_macros/function-member.html' import function_member %}

{% block content %}
{# Template-scoped caching of computed values #}
{% let element_children = element?.children ?? [] %}
{% let classes = element_children | selectattr('element_type', 'eq', 'class') | list %}
{% let functions = element_children | selectattr('element_type', 'eq', 'function') | list %}
{% let page_tags = page?.tags ?? [] %}

{# 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.html' import hero_element %}
    {{ hero_element(element, page, config) }}

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

      {# Optional member summary table (autosummary-style) #}
      {% set show_summary = config?.autodoc?.python?.show_member_summary ?? false %}
      {% if show_summary and (classes | length + functions | length) > 0 %}
      <section class="autodoc-section autodoc-summary" data-section="summary">
        <h2 class="autodoc-section-title">Summary</h2>
        <table class="autodoc-summary-table">
          <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
          <tbody>
            {% for cls in classes %}
            <tr><td><a href="#{{ cls.name }}">{{ cls.name }}</a></td><td>class</td><td>{{ (cls.description ?? '') | first_sentence }}</td></tr>
            {% end %}
            {% for func in functions %}
            <tr><td><a href="#{{ func.name }}">{{ func.name }}</a></td><td>function</td><td>{{ (func.description ?? '') | first_sentence }}</td></tr>
            {% end %}
          </tbody>
        </table>
      </section>
      {% end %}

      {# Classes Section #}
      {% if classes | length > 0 %}
      <section class="autodoc-section" data-section="classes">
        <h2 class="autodoc-section-title">Classes</h2>
        {% for cls in classes %}
        {{ class_member(cls, is_first=loop.first) }}
        {% end %}
      </section>
      {% end %}

      {# Functions Section #}
      {% if functions | length > 0 %}
      <section class="autodoc-section" data-section="functions">
        <h2 class="autodoc-section-title">Functions</h2>
        {% for func in functions %}
        {{ function_member(func, is_first=loop.first) }}
        {% end %}
      </section>
      {% end %}

      {# Tags - with null-safe access #}
      {% if page_tags | length > 0 %}
      <footer class="docs-footer">
        <span class="docs-footer-label">Tagged</span>
        {% from 'partials/components/tags.html' import tag_list %}
        {{ tag_list(page_tags) }}
      </footer>
      {% 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 %}