{% extends "base.html" %}

{#
================================================================================
OpenAPI Reference Endpoint Template (Kida-Native v2)
================================================================================

Three-panel layout optimized for REST API documentation.
Uses the unified autodoc skeleton with OpenAPI-specific extensions.

This template receives:
- element: DocElement for the endpoint
- config: Autodoc configuration
- site: Site instance

KIDA FEATURES USED:
- {% let %} for scoped variable binding
- {% match %} for HTTP method dispatching and status code styling
- {% with %} for nil-resilient metadata access
- {% cache %} for expensive response table rendering
- Pipeline operators (|>) for clean filter chains
- {% spaceless %} for compact badge rendering
- Optional chaining (?.) and null coalescing (??)
================================================================================
#}

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

{# =============================================================================
HTTP METHOD STYLING DATA
Centralized for consistency and easy customization
============================================================================= #}
{% let HTTP_METHODS_WITH_BODY = ['POST', 'PUT', 'PATCH'] %}

{# =============================================================================
STATUS CODE HELPER MACRO
Returns semantic category for styling
============================================================================= #}
{% def status_category(code) %}
{% match code | string | first %}
{% case '2' %}success
{% case '3' %}redirect
{% case '4' %}client-error
{% case '5' %}server-error
{% case _ %}info
{% end %}
{% end %}

{% block content %}
{# Extract element metadata with nil-resilience #}
{% let meta = element?.metadata ?? {} %}
{% let http_method = meta?.method ?? 'GET' %}
{% let endpoint_path = meta?.path ?? '/' %}
{% let operation_id = meta?.operation_id %}
{% let is_deprecated = meta?.deprecated ?? false %}
{% let summary = meta?.summary ?? element?.description ?? '' %}

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

  {# Center: Endpoint Documentation #}
  <div class="docs-main">
    {# Breadcrumbs #}
    {{ breadcrumbs(page) }}

    {# Article Content - New autodoc skeleton #}
    <article data-autodoc data-type="openapi" data-element="endpoint" class="autodoc docs-content">

      {# Header with method badge - pattern matched styling #}
      <header class="autodoc-header">
        {% if is_deprecated %}
        <div class="autodoc-badges">
          <span class="autodoc-badge" data-badge="deprecated">Deprecated</span>
        </div>
        {% end %}

        <h1 class="autodoc-title">
          <span class="autodoc-method" data-method="{{ http_method |> lower }}">{{ http_method |> upper }}</span>
          <code>{{ endpoint_path }}</code>
        </h1>

        {% if summary %}
        <div class="autodoc-description">
          <p>{{ summary }}</p>
        </div>
        {% end %}

        {% if operation_id %}
        <div class="autodoc-stats">
          <span class="autodoc-stat">
            <span class="autodoc-stat-label">Operation ID:</span>
            <span class="autodoc-stat-value"><code>{{ operation_id }}</code></span>
          </span>
        </div>
        {% end %}
      </header>

      {# Parameters Section #}
      {% with meta?.parameters as api_params %}
      {% if api_params | length > 0 %}
      {% let params = api_params %}
      {% let title = 'Parameters' %}
      {% include 'autodoc/partials/params-table.html' %}
      {% end %}
      {% end %}

      {# Request Body Section #}
      {% with meta?.request_body as req_body %}
      {% if req_body %}
      <section class="autodoc-section" data-section="request-body">
        <h2 class="autodoc-section-title">Request Body</h2>
        {% if req_body?.description %}
        <div class="autodoc-description">
          <p>{{ req_body.description }}</p>
        </div>
        {% end %}
        {% with req_body?.content as content_types %}
        {% if content_types %}
        {% spaceless %}
        <div class="autodoc-badges">
          {% for content_type, schema in content_types |> items %}
          <span class="autodoc-badge">{{ content_type }}</span>
          {% end %}
        </div>
        {% end %}
        {% end %}
        {% end %}
      </section>
      {% end %}
      {% end %}

      {# Responses Section - with cache for complex rendering #}
      {% with meta?.responses as responses %}
      {% if responses | length > 0 %}
      <section class="autodoc-section" data-section="responses">
        <h2 class="autodoc-section-title">Responses</h2>
        {% cache 'openapi-responses-' ~ endpoint_path ~ '-' ~ http_method %}
        <table class="autodoc-table" data-table="responses">
          <thead>
            <tr>
              <th>Status</th>
              <th>Description</th>
              <th>Content Type</th>
            </tr>
          </thead>
          <tbody>
            {% for status_code, response in responses |> items %}
            {% let category = status_category(status_code) %}
            <tr data-status-category="{{ category }}">
              <td class="autodoc-cell-name" data-label="Status">
                <code class="status-{{ category }}">{{ status_code }}</code>
              </td>
              <td class="autodoc-cell-desc" data-label="Description">
                {{ response?.description ?? t('api.no_description', default='No description') }}
              </td>
              <td class="autodoc-cell-type" data-label="Content Type">
                {% with response?.content as content %}
                {% if content %}
                {% spaceless %}
                {% for content_type in content |> keys %}
                <code>{{ content_type }}</code>{% if not loop.last %}, {% end %}
                {% end %}
                {% end %}
                {% else %}
                <span class="text-muted">—</span>
                {% end %}
                {% end %}
              </td>
            </tr>
            {% end %}
          </tbody>
        </table>
        {% end %}
      </section>
      {% end %}
      {% end %}

      {# Tags #}
      {% with page?.tags as tags %}
      {% if tags | length > 0 %}
      <footer class="docs-footer">
        <span class="docs-footer-label">Tagged</span>
        {% from 'partials/components/tags.html' import tag_list %}
        {{ tag_list(tags) }}
      </footer>
      {% end %}
      {% end %}
    </article>

    {# Page navigation (prev/next) at bottom #}
    {{ page_navigation(page) }}
  </div>

  {# Right Panel: Code Examples #}
  <aside class="autodoc-examples-panel" id="autodoc-examples" role="complementary" aria-label="Code examples">
    <div class="autodoc-examples-panel-content">
      <h3 class="autodoc-examples-panel-title">{{ icon('code', size=16) }} Code Examples</h3>

      {# Request Example - method-aware body handling #}
      <div class="autodoc-example">
        <h4 class="autodoc-example-title">Request</h4>
        {% let method_upper = http_method |> upper %}
        {% let needs_body = method_upper in HTTP_METHODS_WITH_BODY %}
        <pre><code class="language-bash">curl -X {{ method_upper }} \
  "https://api.example.com{{ endpoint_path }}"{% if needs_body %} \
  -H "Content-Type: application/json" \
  -d '{}'{% end %}</code></pre>
      </div>

      {# Response Examples - show success responses #}
      {% with meta?.responses as responses %}
      {% if responses %}
      {% for status_code, response in responses |> items if (status_code |> string |> first) == '2' %}
      <div class="autodoc-example">
        <h4 class="autodoc-example-title">Response {{ status_code }}</h4>
        <pre><code class="language-json">{
  "status": "success"
}</code></pre>
      </div>
      {% end %}
      {% end %}
      {% end %}
    </div>
  </aside>
</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 %}