{#
================================================================================
Documentation Navigation Component (Kida-Native)
================================================================================

Hierarchical sidebar navigation for documentation sites.
Uses pre-computed NavTree for optimal performance.

KIDA FEATURES USED:
- {% def %} for recursive macro (3x faster than {% include %})
- {% let %} for template-scoped variables
- Optional chaining (?.) for null-safe access
- Null coalescing (??) for smart defaults
- {% match %} for node type dispatch
- {% spaceless %} for clean HTML output

FEATURES:
- Hierarchical tree structure via NavTree API
- Active page highlighting (automatic via NavNodeProxy)
- Active trail marking (automatic via NavTreeContext)
- Version-aware filtering (automatic via NavTreeCache)
- Keyboard accessible
- Section icons from frontmatter

USAGE:
{% include 'partials/docs-nav.html' %}
================================================================================
#}

{# Control icon visibility - defaults to true if not passed in context #}
{% let show_nav_icons = show_nav_icons ?? true %}

{# =============================================================================
NAV NODE MACRO - Recursive navigation node renderer

Replaces the previous docs-nav-node.html include pattern.
Macros are compiled once and called as functions, eliminating the
per-call overhead of {% include %} (context copy, template lookup).
============================================================================= #}

{% def nav_node(item, depth=0) %}
{# Extract values once with null-safe access #}
{% let item_title = item?.title ?? 'Untitled' %}
{% let item_icon = item?.icon ?? '' %}
{% let item_href = item?.href ?? '' %}
{% let item_children = item?.children ?? [] %}
{% let is_current = item?.is_current ?? false %}
{% let is_in_trail = item?.is_in_trail ?? false %}
{% let is_section = item?.is_section ?? false %}
{% let has_children = item_children | length > 0 %}

{% match has_children, depth %}
{# ===== ROOT NODE (depth 0) - Static header, no toggle ===== #}
{% case true, 0 %}
<div class="docs-nav-group docs-nav-group--root{{ ' is-in-trail' if is_in_trail else '' }}" data-depth="{{ depth }}">
  <div class="docs-nav-group-header">
    {% if show_nav_icons %}
    {% spaceless %}
    <span class="docs-nav-icon" {{ ' data-default="true"' | safe if not item_icon else '' }}>
      {{ icon(item_icon ?? 'folder', size=16) }}
    </span>
    {% end %}
    {% end %}

    {% if item_href %}
    <a href="{{ item_href | absolute_url }}" class="docs-nav-group-title{{ ' active' if is_current else '' }}" {{ 'aria-current="page"'
      | safe if is_current else '' }}>
      <bdi>{{ item_title }}</bdi>
    </a>
    {% else %}
    <span class="docs-nav-group-title"><bdi>{{ item_title }}</bdi></span>
    {% end %}
  </div>

  <div class="docs-nav-group-items is-expanded expanded">
    {% for child in item_children %}
    {{ nav_node(child, depth + 1) }}
    {% end %}
  </div>
</div>

{# ===== EXPANDABLE NODE (depth > 0) - CSS-only accessible toggle ===== #}
    {# Uses <details>/<summary> for native toggle + CSS :has() to control sibling visibility.
       The <a> link is OUTSIDE <summary> (as a sibling), avoiding nested interactive elements.
       CSS Grid arranges: [toggle] [icon] [link] on first row, [items] spanning full width below. #}
    {% case true, _ %}
    <div class="docs-nav-group{{ ' is-in-trail' if is_in_trail else '' }}" data-depth="{{ depth }}">
      <details class="docs-nav-details" {{ 'open' | safe if is_in_trail else '' }}>
        <summary class="docs-nav-toggle" aria-label="Toggle {{ item_title }} section">
          <span class="docs-nav-caret">
            {{ icon('caret-right', size=14) }}
          </span>
        </summary>
      </details>

      {% if show_nav_icons %}
      {% spaceless %}
      <span class="docs-nav-icon" {{ ' data-default="true"' | safe if not item_icon else '' }}>
        {{ icon(item_icon ?? 'folder', size=16) }}
      </span>
      {% end %}
      {% end %}

      {% if item_href %}
      <a href="{{ item_href | absolute_url }}" class="docs-nav-group-link{{ ' active' if is_current else '' }}"
        {{ 'aria-current="page"' | safe if is_current else '' }}>
        <bdi>{{ item_title }}</bdi>
      </a>
      {% else %}
      <span class="docs-nav-group-link"><bdi>{{ item_title }}</bdi></span>
      {% end %}

      <div class="docs-nav-group-items">
        {% for child in item_children %}
        {{ nav_node(child, depth + 1) }}
        {% end %}
      </div>
    </div>

    {# ===== LEAF NODE (no children) ===== #}
    {% case false, _ %}
    <div class="docs-nav-group docs-nav-group--leaf" data-depth="{{ depth }}">
      {% if item_href %}
      <a href="{{ item_href | absolute_url }}"
        class="docs-nav-link{{ ' docs-nav-link--section' if is_section else '' }}{{ ' active' if is_current else '' }}"
        {{ 'aria-current="page"' | safe if is_current else '' }}>
        {% if show_nav_icons and is_section %}
        {% spaceless %}
        <span class="docs-nav-icon docs-nav-icon--section" {{ ' data-default="true"' | safe if not item_icon else '' }}>
          {{ icon(item_icon ?? 'folder', size=14) }}
        </span>
        {% end %}
        {% end %}
        <span class="docs-nav-link-text"><bdi>{{ item_title }}</bdi></span>
      </a>
      {% else %}
      <span class="docs-nav-link{{ ' docs-nav-link--section' if is_section else '' }}">
        {% if show_nav_icons and is_section %}
        {% spaceless %}
        <span class="docs-nav-icon docs-nav-icon--section" {{ ' data-default="true"' | safe if not item_icon else '' }}>
          {{ icon(item_icon ?? 'folder', size=14) }}
        </span>
        {% end %}
        {% end %}
        <span class="docs-nav-link-text"><bdi>{{ item_title }}</bdi></span>
      </span>
      {% end %}
    </div>
    {% end %}
    {% end %}

    {# =============================================================================
    MAIN NAVIGATION COMPONENT
    ============================================================================= #}

    {# Check if page is autodoc - autodoc pages should use scoped navigation #}
    {% let is_autodoc = is_autodoc_page(page) if is_autodoc_page is defined else false %}

    {#
    Always scope docs navigation to the page's section root.
    The docs-nav template is only used by doc-type pages, so scoped navigation
    is the expected behavior - docs sidebar should show docs content only,
    not sibling top-level sections like releases or tracks.

    nav_root: true metadata can still be used to create navigation boundaries
    within a section (e.g., /api/python/ stops at itself, not /api/).
    #}
    {% let page_section = page?._section %}
    {% let root_section = page_section?.root ?? none %}

    <nav class="docs-nav" aria-label="Documentation pages" data-bengal="docs-nav">
      {# Version Selector - only show if page is versioned (not autodoc) #}
      {% unless is_autodoc %}
      {% include 'partials/version-selector.html' %}
      {% end %}

      {# Navigation Tree - uses cached NavTree infrastructure #}
      <div class="docs-nav-tree">
        {% if root_section %}
        {# Scoped navigation: include root section as header #}
        {% let nav_context = get_nav_context(page, root_section=root_section) %}
        {% with nav_context?.root as root_item %}
        {{ nav_node(root_item, 0) }}
        {% end %}
        {% else %}
        {# Regular navigation: render all top-level items #}
        {% let nav_items = get_nav_tree(page) ?? [] %}
        {% for item in nav_items %}
        {{ nav_node(item, 0) }}
        {% end %}
        {% end %}
      </div>
    </nav>