{% extends "base.html" %}

{#
================================================================================
Documentation Single Page Template (Kida-Native)
================================================================================

Three-column layout optimized for documentation pages.

LAYOUT:
- Left sidebar: Navigation tree
- Center: Content with track navigation
- Right sidebar: Contextual Graph + TOC + metadata

KIDA FEATURES USED:
- {% let %} for template-scoped variables
- Optional chaining (?.) for null-safe access
- Null coalescing (??) for defaults
- {% spaceless %} for clean HTML output
- {% cache %} for expensive computations

FEATURES:
- Version banner (warns about old/deprecated versions)
- Stale content banner (warns when page hasn't been updated)
- Page hero with breadcrumbs, title, description, metadata
- Track navigation support (learning paths)
- Contextual knowledge graph
- Table of contents with progress tracking
- Tag list in footer

USAGE:
Set `template: doc/single.html` in frontmatter
Or set `type: doc` to auto-select this template
================================================================================
#}

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

{% block content %}
{# Template-scoped variables #}
{% let page_tags = page?.tags ?? [] %}
{% let page_href = page?.href ?? '' %}
{% let css_class = params?.css_class ?? '' %}

{# Three-column documentation layout #}
<div class="docs-layout">
  {# Main Content #}
  <div class="docs-main">
    {# Version Banner - warns users when viewing old/deprecated versions #}
    {% include 'partials/version-banner.html' %}

    {# Stale Content Banner - warns when page hasn't been updated recently #}
    {% include 'partials/stale-content-banner.html' %}

    {# Page Hero: Breadcrumbs + Title + Description + Metadata #}
    {% include 'partials/page-hero.html' %}

    {# Article Content #}
    <article class="prose {{ css_class }}">
      {# Track Navigation (Top) - for learning paths #}
      {% include 'partials/track_nav.html' %}

      {# Main content #}
      <div class="docs-content">
        {{ content | safe }}
      </div>

      {# Tags #}
      {% if page_tags | length > 0 %}
      <footer class="docs-footer">
        <span class="docs-footer-label">{{ t('docs.tagged', default='Tagged') }}</span>
        {{ tag_list(page_tags) }}
      </footer>
      {% end %}
    </article>

    {# Track Navigation (Bottom) #}
    {% include 'partials/track_nav.html' %}

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

  {# Left Sidebar: Navigation #}
  <aside class="docs-sidebar" id="docs-sidebar" role="navigation" aria-label="Documentation navigation">
    {% include 'partials/docs-nav.html' %}
  </aside>

  {# Right Sidebar: Contextual Graph + TOC + Metadata #}
  {% if toc_items %}
  <aside class="docs-toc" role="complementary" aria-label="Table of contents">
    {# Contextual Graph Minimap - starts hidden, JS expands when data available #}
    {% set show_graph = theme.features is not defined or 'graph.contextual' in theme.features %}
    {% if show_graph %}
    <div class="graph-contextual" data-page-url="{{ page_href }}">
      <div class="graph-contextual-container graph-loading"></div>
    </div>
    {% end %}

    {# Table of Contents #}
    {{ toc(toc_items=toc_items, toc=toc, page=page) }}
  </aside>
  {% end %}
</div>

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

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