{#
================================================================================
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, version_trigger=false) %}
{# 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 item_status = item?.page?.metadata?.status ?? item?.page?.params?.status ?? '' %}
{% 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 %}
{# Show the merged version switcher only on versioned, non-autodoc docs pages
   with more than one version — same guard the old version-selector used. When
   it does not hold, the root header renders exactly as before (byte-identical). #}
{% let vs_show =
     version_trigger
     and versioning_enabled
     and versions | length > 1
     and page?.version is not none
     and not (is_autodoc_page(page) if is_autodoc_page else false) %}
<div class="docs-nav-group docs-nav-group--root{{ ' is-in-trail' if is_in_trail else '' }}" data-depth="{{ depth }}">
  {% if vs_show %}
  {# ===== MERGED VERSION SWITCHER: the "Documentation" title IS the dropdown =====
     Native <details>/<summary> = the disclosure, so versions stay switchable
     with zero JS (each option is a real <a>); CSS rotates the caret via [open];
     version-selector.js only adds close-on-outside-click + Esc + arrow keys. #}
  {# Resolve the pill label/status from page.version + the versions list.
     Do not read current_version.label: on section-index pages current_version
     arrives as an unresolved LazyValue and attribute access on it throws
     K-RUN-001 (dropping the page) or falls back to site.latest_version
     ("Latest" on older-version pages). The menu already matches by page.version. #}
  {% let cur_version_id = page?.version %}
  {% let vlabel = site.latest_version?.label ?? 'Latest' %}
  {% let vstatus = 'current' %}
  {% for v in versions %}
  {% if cur_version_id is not none and cur_version_id == v.id %}
  {% let vlabel = v.label %}
  {% let vstatus = v.status or (v.deprecated and 'deprecated' or 'legacy') %}
  {% end %}
  {% end %}
  <details class="docs-nav-vswitch" data-version-switcher>
    <summary class="docs-nav-group-header docs-nav-vswitch__summary" title="Switch documentation version">
      {% if show_nav_icons %}
      {% spaceless %}
      <span class="docs-nav-icon" {{ ' data-default="true"' | safe if not item_icon else '' }}>
        {{ icon(item_icon ?? 'book', size=16) }}
      </span>
      {% end %}
      {% end %}
      <span class="docs-nav-group-title docs-nav-vswitch__title">
        <bdi class="docs-nav-vswitch__doc">{{ item_title }}</bdi>
        {% if vlabel %}
        <span class="docs-nav-vswitch__sep" aria-hidden="true">·</span>
        <span class="docs-nav-vswitch__pill" data-status="{{ vstatus }}">{{ vlabel }}</span>
        {% end %}
      </span>
      <span class="docs-nav-vswitch__caret" aria-hidden="true">{{ icon('caret-down', size=14) }}</span>
    </summary>

    <ul class="docs-nav-vswitch__menu" aria-label="Documentation versions">
      {% for v in versions %}
      {% let v_is_current = cur_version_id is not none and cur_version_id == v.id %}
      {% let v_status = v.status or (v.deprecated and 'deprecated' or 'legacy') %}
      <li class="docs-nav-vswitch__item{{ ' is-current' if v_is_current else '' }}{{ ' is-deprecated' if v.deprecated else '' }}">
        <a class="docs-nav-vswitch__link"
           href="{{ site.get_version_target_url(page, v) }}"
           {{ 'aria-current="true"' | safe if v_is_current else '' }}>
          <span class="docs-nav-vswitch__check" aria-hidden="true">{{ icon('check', size=14) if v_is_current else '' }}</span>
          <span class="docs-nav-vswitch__item-label"><bdi>{{ v.label }}</bdi></span>
          <span class="docs-nav-vswitch__item-hint" data-status="{{ v_status }}">
            {% if v.latest %}Latest{% elif v.status == 'preview' %}Preview{% elif v.deprecated %}deprecated{% else %}older{% end %}
          </span>
        </a>
      </li>
      {% end %}
    </ul>
  </details>
  {% else %}
  {# ===== Unchanged plain root header (non-versioned / autodoc / single version) ===== #}
  <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>
  {% end %}

  <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>
        {% if item_status %}
        <span class="docs-nav-status docs-nav-status--{{ item_status | lower }}">{{ item_status | capitalize }}</span>
        {% end %}
      </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 %}

    <bengal-docs-nav>
    <nav class="docs-nav" aria-label="Documentation pages">
      {# Navigation Tree - uses cached NavTree infrastructure #}
      <div class="docs-nav-tree">
        {% if root_section %}
        {# Scoped navigation: the root section header doubles as the version
           switcher (version_trigger=true), so the standalone selector is gone. #}
        {% let nav_context = get_nav_context(page, root_section=root_section) %}
        {% with nav_context?.root as root_item %}
        {{ nav_node(root_item, 0, version_trigger=true) }}
        {% end %}
        {% else %}
        {# Fallback (no section root): keep the standalone version selector,
           since there is no single root header to merge it into here. #}
        {% unless is_autodoc %}
        {% include 'partials/version-selector.html' %}
        {% end %}
        {# 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>
    </bengal-docs-nav>