{#
Bengal OpenAPI Home Page
========================

API landing page showing:
- API title and description
- Version and server information
- Authentication schemes
- Tag/endpoint category overview

Context:
- section: Section with metadata containing API overview data
  - section.metadata.version: API version
  - section.metadata.servers: Server URLs
  - section.metadata.security_schemes: Auth schemes
  - section.metadata.tags: API categories
- page: Page object
- site: Site instance
- config: Config instance

The `endpoints` and `schemas` filters normalize access to endpoint/schema data
regardless of whether the source is DocElements or Pages.

Note: For section index pages, `element` is None. Use section.metadata instead.

Kida Features:
- {% with %} for nil-resilient optional sections
- {% spaceless %} for compact badge output
- Optional chaining (?.) and null coalescing (??)
#}
{% extends 'autodoc/openapi/layouts/reference.html' %}

{# Access metadata from section (set by section_builders.py) #}
{% let sec_meta = section?.metadata ?? {} %}
{% let api_title = section?.title ?? page?.title ?? 'API Reference' %}
{% let api_version = sec_meta?.version ?? '1.0.0' %}
{% let servers = sec_meta?.servers ?? () %}
{% let security_schemes = sec_meta?.security_schemes ?? {} %}
{% let tags = sec_meta?.tags ?? () %}
{% let description = sec_meta?.description ?? '' %}

{# Use filters for normalized access #}
{% let eps = section | endpoints %}
{% let schs = section | schemas %}

{% block header %}
<h1 class="api-home__title">{{ api_title }}</h1>

{% if api_version %}
<div class="api-home__version">
  <span class="badge badge--outline">v{{ api_version }}</span>
</div>
{% end %}

{% if description %}
<div class="api-home__description prose">
  {{ description | markdownify | safe }}
</div>
{% end %}
{% end %}

{% block content_main %}
<div class="api-home" data-autodoc="openapi" data-element="home">
  {# Quick Stats #}
  {% let endpoint_count = eps | length %}
  {% let schema_count = schs | length %}
  {% let tag_count = tags | length %}

  {% if endpoint_count > 0 or schema_count > 0 %}
  <div class="api-home__stats">
    {% if endpoint_count > 0 %}
    <div class="api-home__stat">
      <span class="api-home__stat-value">{{ endpoint_count }}</span>
      <span class="api-home__stat-label">Endpoints</span>
    </div>
    {% end %}
    {% if schema_count > 0 %}
    <div class="api-home__stat">
      <span class="api-home__stat-value">{{ schema_count }}</span>
      <span class="api-home__stat-label">Schemas</span>
    </div>
    {% end %}
    {% if tag_count > 0 %}
    <div class="api-home__stat">
      <span class="api-home__stat-value">{{ tag_count }}</span>
      <span class="api-home__stat-label">Categories</span>
    </div>
    {% end %}
  </div>
  {% end %}

  {# Base URLs / Servers #}
  {% if servers | length > 0 %}
  <section class="api-home__servers autodoc-section">
    <h2 class="api-home__section-title">{{ icon('server', size=18) }} Base URLs</h2>
    <div class="api-home__server-list">
      {% for server in servers %}
      {% let server_url = server if server is string else server?.url ?? server %}
      {% let server_desc = '' if server is string else server?.description ?? '' %}
      <div class="api-home__server card">
        <code class="api-home__server-url">{{ server_url }}</code>
        {% if server_desc %}
        <span class="api-home__server-desc text-muted">{{ server_desc }}</span>
        {% end %}
        <button class="api-home__server-copy" data-copy="{{ server_url }}" aria-label="Copy URL">
          {{ icon('copy', size=14) }}
        </button>
      </div>
      {% end %}
    </div>
  </section>
  {% end %}

  {# Authentication #}
  {% if security_schemes | length > 0 %}
  <section class="api-home__auth autodoc-section">
    <h2 class="api-home__section-title">{{ icon('lock', size=18) }} Authentication</h2>
    <div class="api-home__auth-schemes">
      {% for name, scheme in security_schemes |> items %}
      {% if scheme %}
      {% let scheme_type = scheme?.type ?? 'apiKey' %}
      {% let scheme_desc = scheme?.description ?? '' %}
      {% let scheme_in = scheme.get('in', 'header') %}
      {% let scheme_name = scheme?.name ?? 'Authorization' %}

      <div class="api-home__auth-scheme card">
        <header class="api-home__auth-header">
          <h3 class="api-home__auth-name">
            {{ icon('key', size=14) }}
            {{ name }}
          </h3>
          <span class="badge badge--outline badge--sm">{{ scheme_type }}</span>
        </header>

        {% if scheme_desc %}
        <p class="api-home__auth-description">{{ scheme_desc }}</p>
        {% end %}

        {% match scheme_type %}
        {% case 'apiKey' %}
        <code class="api-home__auth-example">{{ scheme_name }}: YOUR_API_KEY</code>
        {% case 'http' %}
        {% if scheme?.scheme == 'bearer' %}
        <code class="api-home__auth-example">Authorization: Bearer YOUR_TOKEN</code>
        {% else %}
        <code class="api-home__auth-example">Authorization: Basic BASE64_CREDENTIALS</code>
        {% end %}
        {% case 'oauth2' %}
        <code class="api-home__auth-example">Authorization: Bearer ACCESS_TOKEN</code>
        {% case _ %}
        <code class="api-home__auth-example">{{ scheme_name }}: YOUR_CREDENTIALS</code>
        {% end %}
      </div>
      {% end %}
      {% end %}
    </div>
  </section>
  {% end %}

  {# Endpoint Categories (Tags) - Quick Jump Navigation #}
  {% let subsections = section?.subsections ?? () %}
  {% if subsections | length > 0 %}
  <section class="api-home__tags autodoc-section">
    <h2 class="api-home__section-title">{{ icon('folder', size=18) }} Categories</h2>
    <div class="api-home__tag-grid">
      {% for subsec in subsections %}
      {% let tag_name = subsec?.title ?? 'Endpoints' %}
      {% let tag_desc = subsec?.metadata?.description ?? '' %}
      {% let tag_endpoints = subsec | endpoints %}

      <a href="#{{ tag_name | slugify }}" class="api-home__tag-card card card--hoverable">
        <header class="api-home__tag-header">
          <h3 class="api-home__tag-name">{{ tag_name }}</h3>
          <span class="badge badge--outline badge--sm">{{ tag_endpoints | length }}</span>
        </header>
        {% if tag_desc %}
        <p class="api-home__tag-description">{{ tag_desc | truncate(100) }}</p>
        {% end %}
      </a>
      {% end %}
    </div>
  </section>
  {% end %}

  {# Endpoints Grouped by Tag - with anchor IDs matching category tiles #}
  {% if subsections | length > 0 %}
  {% for subsec in subsections %}
  {% let tag_name = subsec?.title ?? 'Endpoints' %}
  {% let tag_desc = subsec?.metadata?.description ?? '' %}
  {% let tag_endpoints = subsec | endpoints %}

  {% if tag_endpoints | length > 0 %}
  <section id="{{ tag_name | slugify }}" class="api-home__tag-section autodoc-section">
    <header class="api-home__tag-section-header">
      <h2 class="api-home__section-title">{{ icon('tag', size=18) }} {{ tag_name }}</h2>
      {% if tag_desc %}
      <p class="api-home__tag-section-desc text-muted">{{ tag_desc }}</p>
      {% end %}
    </header>
    <div class="autodoc-cards">
      {% for ep in tag_endpoints %}
      <a href="{{ ep.href }}" class="autodoc-card{% if ep.deprecated %} autodoc-card--deprecated{% end %}">
        <div class="autodoc-card-header">
          {% spaceless %}
          <span class="api-method api-method--sm api-method--{{ ep.method |> lower }}">{{ ep.method }}</span>
          {% end %}
          <code class="autodoc-card-name">{{ ep.path }}</code>
        </div>
        {% if ep.summary %}
        <p class="autodoc-card-desc">{{ ep.summary | truncate(80) }}</p>
        {% end %}
        {% if ep.deprecated %}
        <span class="autodoc-badge" data-badge="deprecated">Deprecated</span>
        {% end %}
      </a>
      {% end %}
    </div>
  </section>
  {% end %}
  {% end %}
  {% end %}

  {# All Endpoints (only if no subsections/tags exist) #}
  {% if subsections | length == 0 and eps | length > 0 %}
  <section class="api-home__endpoints autodoc-section">
    <h2 class="api-home__section-title">{{ icon('list', size=18) }} Endpoints</h2>
    <div class="autodoc-cards">
      {% for ep in eps %}
      <a href="{{ ep.href }}" class="autodoc-card{% if ep.deprecated %} autodoc-card--deprecated{% end %}">
        <div class="autodoc-card-header">
          {% spaceless %}
          <span class="api-method api-method--sm api-method--{{ ep.method |> lower }}">{{ ep.method }}</span>
          {% end %}
          <code class="autodoc-card-name">{{ ep.path }}</code>
        </div>
        {% if ep.summary %}
        <p class="autodoc-card-desc">{{ ep.summary | truncate(80) }}</p>
        {% end %}
        {% if ep.deprecated %}
        <span class="autodoc-badge" data-badge="deprecated">Deprecated</span>
        {% end %}
      </a>
      {% end %}
    </div>
  </section>
  {% end %}

  {# Schemas #}
  {% if schs | length > 0 %}
  <section class="api-home__schemas autodoc-section">
    <h2 class="api-home__section-title">{{ icon('database', size=18) }} Schemas</h2>
    <div class="autodoc-cards">
      {% for schema in schs %}
      <a href="{{ schema.href }}" class="autodoc-card">
        <div class="autodoc-card-header">
          <code class="autodoc-card-name">{{ schema.name }}</code>
          <span class="badge badge--outline badge--sm">{{ schema.schema_type }}</span>
        </div>
        {% if schema.description %}
        <p class="autodoc-card-desc">{{ schema.description | truncate(80) }}</p>
        {% end %}
      </a>
      {% end %}
    </div>
  </section>
  {% end %}
</div>
{% end %}