{#
================================================================================
Navigation Components (Kida-Native)
================================================================================

Reusable macro-based navigation components for the Bengal default theme.

COMPONENTS:
- breadcrumbs(page): Hierarchical breadcrumb navigation
- pagination(current_page, total_pages, base_url): Page number controls
- page_navigation(page): Sequential prev/next page links
- section_navigation(page): Section statistics and subsection cards
- toc(toc_items, toc, page): Table of contents sidebar

KIDA FEATURES USED:
- {% def %} for reusable macros
- {% let %} for template-scoped variables
- Optional chaining (?.) for null-safe access
- Null coalescing (??) for smart defaults
- {% match %} for type dispatch
- {% spaceless %} for clean HTML output
- Pipeline operator (|>) for filter chains

USAGE:
{% from 'partials/navigation-components.html' import breadcrumbs, pagination %}
{{ breadcrumbs(page) }}
{{ pagination(current_page=2, total_pages=10, base_url='/blog/') }}
================================================================================
#}

{# =============================================================================
BREADCRUMBS COMPONENT

Displays hierarchical navigation showing the current page's location.

Note: URLs returned by get_breadcrumbs() are relative paths without baseurl.
For display in HTML href attributes, apply the | absolute_url filter.
============================================================================= #}
{% def breadcrumbs(page) %}
{% with get_breadcrumbs(page) as breadcrumb_items %}
<nav class="breadcrumbs" aria-label="Breadcrumb">
  <ol>
    {% for item in breadcrumb_items %}
    {% let is_current = item?.is_current ?? false %}
    <li{{ ' aria-current="page"' | safe if is_current else '' }}>
      {% if is_current %}
      {{ item.title }}
      {% else %}
      <a href="{{ item.href | absolute_url }}">{{ item.title }}</a>
      {% end %}
      </li>
      {% export last_breadcrumb_item = item %}
      {% end %}
  </ol>
</nav>
{% end %}
{% enddef %}

{# =============================================================================
PAGINATION ITEM HELPER

Renders a single pagination item (ellipsis, current page, or link).
============================================================================= #}
{% def pagination_item(item) %}
{% if item?.is_ellipsis %}
<span class="ellipsis">...</span>
{% elif item?.is_current %}
<span class="active" aria-current="page">{{ item.num }}</span>
{% else %}
<a href="{{ item.href }}" class="squeeze">{{ item.num }}</a>
{% end %}
{% end %}

{# =============================================================================
PAGINATION COMPONENT

Displays page number controls for paginated content with prev/next buttons.
============================================================================= #}
{% def pagination(current_page, total_pages, base_url) %}
{% if total_pages > 1 %}
{% let p = get_pagination_items(current_page, total_pages, base_url) %}

<nav class="pagination" role="navigation" aria-label="Pagination">
  <ul>
    {# Previous Button #}
    <li>
      {% if p?.prev %}
      <a href="{{ p.prev.href }}" class="squeeze" aria-label="Previous page">
        {{ icon('caret-left', size=20) }}
        Previous
      </a>
      {% else %}
      <span class="disabled">
        {{ icon('caret-left', size=20) }}
        Previous
      </span>
      {% end %}
    </li>

    {# Page Numbers #}
    {% for item in p?.pages ?? [] %}
    <li>
      {{ pagination_item(item) }}
    </li>
    {% end %}

    {# Next Button #}
    <li>
      {% if p?.next %}
      <a href="{{ p.next.href }}" class="squeeze" aria-label="Next page">
        Next
        {{ icon('caret-right', size=20) }}
      </a>
      {% else %}
      <span class="disabled">
        Next
        {{ icon('caret-right', size=20) }}
      </span>
      {% end %}
    </li>
  </ul>
</nav>
{% end %}
{% end %}

{# =============================================================================
PAGE NAVIGATION COMPONENT

Displays previous/next page links for sequential navigation.

Intelligently chooses navigation scope based on content type:
- doc, tutorial, autodoc-*, blog: Section-scoped (prev/next within section)
- page, others: Global (chronological order)
============================================================================= #}
{% def page_navigation(page) %}
{# Early return if page is null #}
{% if page %}
{# Check feature flag #}
{% let theme_features = theme?.features ?? [] %}
{% if 'navigation.prev_next' in theme_features %}
{# Determine navigation scope based on content type #}
{% let content_type = page?.metadata?.type ?? 'page' %}
{% let section_types = ['doc', 'tutorial', 'autodoc-python', 'autodoc-cli', 'autodoc-rest', 'changelog', 'blog'] %}
{% let use_section_nav = content_type in section_types %}

{# Get navigation links with null-safe access #}
{% let prev_link = page?.prev_in_section if use_section_nav else page?.prev %}
{% let next_link = page?.next_in_section if use_section_nav else page?.next %}

{% if prev_link or next_link %}
<nav class="page-navigation" aria-label="Page navigation">
  <div class="nav-links">
    {% with prev_link as prev %}
    <div class="nav-previous">
      <a href="{{ prev.href ?? prev._path }}" rel="prev">
        <span class="nav-subtitle"><span class="nav-arrow">←</span> Previous</span>
        <span class="nav-title"><bdi>{{ prev.title }}</bdi></span>
      </a>
    </div>
    {% end %}

    {% with next_link as next %}
    <div class="nav-next">
      <a href="{{ next.href ?? next._path }}" rel="next">
        <span class="nav-subtitle">Next <span class="nav-arrow">→</span></span>
        <span class="nav-title"><bdi>{{ next.title }}</bdi></span>
      </a>
    </div>
    {% end %}
  </div>
</nav>
{% end %}
{% end %}
{% end %}
{% enddef %}

{# =============================================================================
SECTION NAVIGATION COMPONENT

Displays statistics and subsection cards for exploring a section hierarchy.
============================================================================= #}
{% def section_navigation(page) %}
{% let regular_pages = page?.regular_pages ?? [] %}
{% let sections = page?.sections ?? [] %}
{% let recursive_pages = page?.regular_pages_recursive ?? [] %}

{% if regular_pages | length > 0 or sections | length > 0 %}
<div class="section-navigation">
  {# Section stats #}
  <div class="section-stats">
    <p class="stat">
      <strong>{{ regular_pages | length }}</strong> pages in this section
    </p>
    {% if sections | length > 0 %}
    <p class="stat">
      <strong>{{ sections | length }}</strong> subsections
    </p>
    {% end %}
    {% if recursive_pages | length > regular_pages | length %}
    <p class="stat">
      <strong>{{ recursive_pages | length }}</strong> total pages (including subsections)
    </p>
    {% end %}
  </div>

  {# Subsection cards #}
  {% if sections | length > 0 %}
  <div class="subsections">
    <h2>Subsections</h2>
    <div class="subsection-grid">
      {% for subsection in sections %}
      {% let sub_desc = subsection?.metadata?.description ?? '' %}
      {% let sub_pages = subsection?.regular_pages ?? [] %}
      <div class="subsection-card gradient-border fluid-combined">
        <h3>
          <a href="{{ subsection.href }}">{{ subsection.title }}</a>
        </h3>
        {% if sub_desc %}
        <p>{{ sub_desc }}</p>
        {% end %}
        <p class="subsection-meta">
          {{ sub_pages | length }} pages
        </p>
      </div>
      {% end %}
    </div>
  </div>
  {% end %}
</div>
{% end %}
{% end %}

{# =============================================================================
TABLE OF CONTENTS COMPONENT

Interactive TOC with progress tracking, collapsible sections, and metadata.
Uses recursive macros for optimal performance and arbitrary depth.
JS enhances with: active item tracking, auto-expand on scroll, progress.

KIDA FEATURES SHOWCASED:
- {% def %} recursive macros for tree traversal
- {% cache %} for expensive TOC rendering
- {% match %} for level-based styling
- {% unless %} for negative conditionals
- {% break %} for early loop termination (contributor limit)
============================================================================= #}

{# HELPER: Render a single TOC node (recursive)
   is_section: marks top-level section groups for track filtering (default false) #}
{% def toc_node(node, is_section=false) %}
{% let node_id = node?.id ?? '' %}
{% let node_title = node?.title ?? '' %}
{% let node_level = node?.level ?? 2 %}
{% let children = node?.children ?? [] %}
{% let has_children = children | length > 0 %}

{% if node_id %}
<li class="toc-item toc-level-{{ node_level }}" role="treeitem" data-level="{{ node_level }}">
  {% if has_children %}
  {# Auto-expand based on heading level using match #}
  {# Add data-toc-section for top-level groups (used by track filtering) #}
  {% match node_level %}
  {% case 1 %}<details class="toc-group" {{ 'data-toc-section' if is_section else '' }} open>
  {% case 2 %}<details class="toc-group" {{ 'data-toc-section' if is_section else '' }} open>
  {% case _ %}<details class="toc-group">
  {% end %}
    <summary class="toc-group-header">
      <a href="#{{ node_id }}" class="toc-link" data-toc-item="#{{ node_id }}">
        {{ node_title }}
      </a>
      {% spaceless %}
      <span class="toc-count-badge" title="{{ children | length }} subsections">
        <span class="toc-count">{{ children | length }}</span>
      </span>
      {% end %}
    </summary>
    <ul class="toc-subitems" role="group">
      {% for child in children %}
      {{ toc_node(child) }}
      {% end %}
    </ul>
  </details>
  {% else %}
  <a href="#{{ node_id }}" class="toc-link" data-toc-item="#{{ node_id }}">
    {{ node_title }}
  </a>
  {% end %}
</li>
{% end %}
{% enddef %}

{% def toc(toc_items=none, toc=none, page=none) %}
{# Cache TOC rendering per-page for performance #}
{% cache 'toc-' ~ (page?._path ?? 'unknown') %}
<div class="toc-sidebar" data-bengal="toc">
  {# Scroll Progress Indicator #}
  <div class="toc-progress" aria-hidden="true">
    <div class="toc-progress-bar"></div>
  </div>

  {# Table of Contents #}
  <nav class="toc-nav" aria-label="Table of contents" data-toc-mode="normal">
    {% if toc_items %}
    {# Build nested tree structure for proper children/count badge display #}
    {% let nested_items = build_toc_tree(toc_items) %}
    <div class="toc-scroll-container">
      <ul class="toc-items" role="tree">
        {% for item in nested_items %}
        {{ toc_node(item, is_section=true) }}
        {% end %}
      </ul>
    </div>
    {% elif toc %}
    {# Fallback to HTML TOC #}
    <div class="toc-content">
      {{ toc | safe }}
    </div>
    {% end %}
  </nav>

  {# Page Metadata Section #}
  {% if page %}
  {% let page_meta = page?.metadata ?? {} %}
  {% let contributors = page_meta?.contributors ?? [] %}
  {% let github_edit_base = config?.github_edit_base %}
  {% let source_path = page?.source_path %}

  <div class="toc-metadata">
    {# Last Updated #}
    {% with page.date as date %}
    <div class="toc-meta-item">
      {{ icon('clock', size=14) }}
      <div>
        <div class="toc-meta-label">{{ t('toc.last_updated', default='Last updated') }}</div>
        <time datetime="{{ date | date_iso }}" class="toc-meta-value">
          {{ date | time_ago }}
        </time>
      </div>
    </div>
    {% end %}

    {# Edit on GitHub #}
    {% with page_meta?.edit_url ?? (github_edit_base ~ source_path if github_edit_base and source_path) as edit_url %}
    <a href="{{ edit_url }}" class="toc-edit-link" target="_blank" rel="noopener noreferrer">
      {{ icon('pencil', size=14) }}
      <span>{{ t('toc.edit_page', default='Edit this page') }}</span>
    </a>
    {% end %}

    {# Contributors - limit display with loop control #}
    {% if contributors | length > 0 %}
    <div class="toc-meta-item">
      {{ icon('users', size=14) }}
      <div>
        <div class="toc-meta-label">{{ t('toc.contributors', default='Contributors') }}</div>
        <div class="toc-meta-value">
          {% let max_contributors = 5 %}
          {% let shown_contributors = contributors |> take(max_contributors) %}
          {{ shown_contributors | join(', ') }}
          {% if contributors | length > max_contributors %}
          <span class="toc-meta-more">+{{ contributors | length - max_contributors }} more</span>
          {% end %}
        </div>
      </div>
    </div>
    {% end %}
  </div>
  {% end %}
</div>
{% end %}{# End cache block #}
{% enddef %}