{#
Bengal OpenAPI Endpoint Page (Hero Template)
=============================================

Full endpoint documentation with three-column explorer layout.
The primary template for individual REST API endpoints.

Context:
- element: DocElement with OpenAPIEndpointMetadata
- page: Page object
- section: Section for navigation
- site: Site instance
- config: Config instance

Kida Features:
- {% match %} for HTTP method and status code styling
- {% with %} for nil-resilient optional sections
- {% cache %} for expensive response rendering
- {% spaceless %} for compact badge output
- Optional chaining (?.) and null coalescing (??)
#}
{% extends 'autodoc/openapi/layouts/explorer.html' %}

{% from 'autodoc/openapi/_components.html' import endpoint_header, param_row, request_body as request_body_component, responses as responses_component, code_samples %}

{% let meta = element?.typed_metadata ?? element?.metadata ?? {} %}
{% let raw_meta = element?.metadata ?? {} %}
{% let http_method = meta?.method ?? 'GET' %}
{% let endpoint_path = meta?.path ?? '/' %}
{% let operation_id = meta?.operation_id %}
{% let summary = meta?.summary ?? element?.description ?? '' %}
{% let is_deprecated = meta?.deprecated ?? false %}
{% let parameters = meta?.parameters ?? () %}
{% let request_body = meta?.request_body %}
{% let sample_request_body = raw_meta?.request_body ?? request_body %}
{% let responses = meta?.responses ?? () %}
{% let raw_responses = raw_meta?.responses ?? responses %}
{% let security = meta?.security ?? () %}
{% let tags = meta?.tags ?? () %}

{# Group parameters by location #}
{% let path_params = parameters |> where('location', 'path') %}
{% let query_params = parameters |> where('location', 'query') %}
{% let header_params = parameters |> where('location', 'header') %}
{% let cookie_params = parameters |> where('location', 'cookie') %}

{% block api_left %}
{# Cross-endpoint sidebar (epic criterion 4): render the full API navigation
   grouped by tag with the current endpoint highlighted. sidebar-nav.html reads
   `section` (for subsection tag groups) and `current_page` (for active state)
   from context, so capture the endpoint's own tag section first, then shadow
   `section` with the API root (which carries all tag subsections) for the
   include. IMPORTANT: Kida {% let %} reassignment at block level leaks across
   sibling blocks (api_header reuses `section`), so restore `section` to the
   tag section immediately after the include. #}
{% let tag_section = section %}
{% let current_page = page %}
{% let section = section?.parent ?? section %}
{% include 'autodoc/openapi/partials/sidebar-nav.html' %}
{% let section = tag_section %}

{# In-page navigation for the current endpoint's sections. #}
<nav class="openapi-nav" aria-label="Endpoint sections" data-api-rail>
  <a href="{{ tag_section?.href ?? page?.href ?? '#' }}" class="openapi-nav__back">{{ icon('arrow-left', size=14) }} {{ tag_section?.title ?? 'Endpoints' }}</a>
  {% if parameters | length > 0 %}<a href="#parameters">Parameters</a>{% end %}
  {% if request_body %}<a href="#request-body">Request body</a>{% end %}
  {% if responses | length > 0 %}<a href="#responses">Responses</a>{% end %}
  {% if security | length > 0 %}<a href="#security">Authorization</a>{% end %}
</nav>
{% end %}

{% block api_header %}
<div class="openapi-operation-title">
  <span class="api-method api-method--{{ http_method |> lower }}">{{ http_method }}</span>
  <code>{{ endpoint_path | highlight_path_params | safe }}</code>
  <button type="button" class="api-copy-btn" data-copy="{{ endpoint_path }}" aria-label="Copy path {{ endpoint_path }}">{{ icon('copy', size=14) }}</button>
</div>
{{ endpoint_header(element, section) }}
{% end %}

{% block api_main %}
<div class="api-endpoint" data-autodoc="openapi" data-element="endpoint">

    {# Parameters Section #}
    {% if parameters | length > 0 %}
    <section class="api-endpoint__section autodoc-section" id="parameters" data-section="parameters">
        <h2 class="api-endpoint__section-title">Parameters</h2>

        {# Path Parameters #}
        {% if path_params | length > 0 %}
        <div class="api-endpoint__param-group">
            <h3 class="api-endpoint__param-group-title">
                {{ icon('link', size=14) }}
                Path Parameters
            </h3>
            <div class="api-endpoint__param-list">
                {% for p in path_params %}
                {{ param_row(p) }}
                {% end %}
            </div>
        </div>
        {% end %}

        {# Query Parameters #}
        {% if query_params | length > 0 %}
        <div class="api-endpoint__param-group">
            <h3 class="api-endpoint__param-group-title">
                {{ icon('filter', size=14) }}
                Query Parameters
            </h3>
            <div class="api-endpoint__param-list">
                {% for p in query_params %}
                {{ param_row(p) }}
                {% end %}
            </div>
        </div>
        {% end %}

        {# Header Parameters #}
        {% if header_params | length > 0 %}
        <div class="api-endpoint__param-group">
            <h3 class="api-endpoint__param-group-title">
                {{ icon('file-text', size=14) }}
                Header Parameters
            </h3>
            <div class="api-endpoint__param-list">
                {% for p in header_params %}
                {{ param_row(p) }}
                {% end %}
            </div>
        </div>
        {% end %}

        {# Cookie Parameters #}
        {% if cookie_params | length > 0 %}
        <div class="api-endpoint__param-group">
            <h3 class="api-endpoint__param-group-title">
                {{ icon('disc', size=14) }}
                Cookie Parameters
            </h3>
            <div class="api-endpoint__param-list">
                {% for p in cookie_params %}
                {{ param_row(p) }}
                {% end %}
            </div>
        </div>
        {% end %}
    </section>
    {% end %}

    {# Request Body #}
    {% with request_body as req_body %}
    {{ request_body_component(req_body) }}
    {% end %}

    {# Responses #}
    {% if responses | length > 0 %}
    {% cache 'openapi-responses-' ~ endpoint_path ~ '-' ~ http_method %}
    {{ responses_component(responses) }}
    {% end %}
    {% end %}

    {# Security Requirements #}
    {% if security | length > 0 %}
    <section class="api-endpoint__section autodoc-section" id="security" data-section="security">
        <h2 class="api-endpoint__section-title">{{ icon('lock', size=18) }} Authorization</h2>
        <div class="api-endpoint__security">
            {% for scheme in security %}
            <span class="badge badge--outline">
                {{ icon('key', size=12) }}
                {{ scheme }}
            </span>
            {% end %}
        </div>
    </section>
    {% end %}
</div>
{% end %}

{% block api_right %}
{# Code Samples Panel #}
<div class="openapi-side-panel">
<h2>{{ icon('code', size=14) }} Examples</h2>
{{ code_samples(http_method, endpoint_path, request_body=sample_request_body, response_example=get_response_example(raw_responses, '200'), parameters=parameters) }}
</div>
{% end %}