{% extends "base.html" %}

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

Individual tutorial page optimized for step-by-step learning.

KIDA FEATURES USED:
- {% let %} for template-scoped variables
- Optional chaining (?.) for null-safe access
- Null coalescing (??) for smart defaults
- {% def %} for reusable card components

USAGE:
Set `type: tutorial` in frontmatter or use cascade from section
================================================================================
#}

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

{# Scroll-synced step progress (mirrors track pattern) #}
{% def tutorial_progress_indicator(total_steps, current_step=1) %}
<div class="tutorial-progress" role="progressbar" aria-valuenow="{{ current_step }}" aria-valuemin="1" aria-valuemax="{{ total_steps }}">
  <div class="tutorial-progress__steps">
    {% let step = 1 %}
    {% while step <= total_steps %}
      {% let is_complete = step < current_step %}
      {% let is_current = step == current_step %}
      {% let step_class = 'tutorial-progress__step' %}
      {% if is_complete %}{% let step_class = step_class ~ ' tutorial-progress__step--complete' %}{% end %}
      {% if is_current %}{% let step_class = step_class ~ ' tutorial-progress__step--current' %}{% end %}
      <div class="{{ step_class }}" data-step="{{ step }}">
        <span class="tutorial-progress__number">{% if is_complete %}✓{% else %}{{ step }}{% end %}</span>
      </div>
      {% if step < total_steps %}
      <div class="tutorial-progress__connector{{ ' tutorial-progress__connector--complete' if is_complete else '' }}"></div>
      {% end %}
      {% let step = step + 1 %}
    {% end %}
  </div>
  <div class="tutorial-progress__label">Step {{ current_step }} of {{ total_steps }}</div>
  <div class="tutorial-progress__bar" aria-hidden="true">
    <div class="tutorial-progress__fill" id="tutorial-progress-bar"></div>
  </div>
</div>
{% end %}

{# =============================================================================
   RELATED TUTORIAL CARD
   ============================================================================= #}
{% def related_tutorial_card(tutorial) %}
{% let tut_meta = tutorial?.metadata ?? {} %}
{% let tut_title = tutorial?.title ?? 'Tutorial' %}
{% let tut_href = tutorial?.href ?? '#' %}
{% let tut_icon = tut_meta?.icon ?? 'book' %}
{% let tut_desc = tut_meta?.description ?? '' %}
{% let tut_difficulty = tut_meta?.difficulty ?? '' %}

<article class="tutorial-card gradient-border fluid-combined">
  <div class="tutorial-card-header">
    <span class="tutorial-icon">{{ tut_icon }}</span>
    <h3 class="tutorial-title">
      <a href="{{ tut_href }}">{{ tut_title }}</a>
    </h3>
  </div>
  <div class="tutorial-card-content">
    {% if tut_desc %}
    <p class="tutorial-description">{{ tut_desc | truncate(100) }}</p>
    {% end %}
    {% if tut_difficulty %}
    <span class="tutorial-badge tutorial-badge-{{ tut_difficulty }}">
      {{ tut_difficulty | capitalize }}
    </span>
    {% end %}
  </div>
</article>
{% end %}

{# =============================================================================
   MAIN TEMPLATE
   ============================================================================= #}

{% block content %}
{# Template-scoped variables #}
{% let page_title = page?.title ?? 'Tutorial' %}
{% let page_date = page?.date %}
{% let page_tags = page?.tags ?? [] %}
{% let css_class = params?.css_class ?? '' %}

{# Tutorial metadata #}
{% let tut_icon = params?.icon ?? '' %}
{% let tut_desc = params?.description ?? '' %}
{% let tut_difficulty = params?.difficulty ?? '' %}
{% let tut_time = params?.time ?? params?.duration ?? '' %}
{% let tut_prereqs = params?.prerequisites ?? [] %}
{% let tut_objectives = params?.learning_objectives ?? params?.objectives ?? [] %}
{% let tut_next_steps = params?.next_steps ?? [] %}
{% let tut_further_reading = params?.further_reading ?? [] %}
{% let toc_items_list = toc_items ?? [] %}
{% let tutorial_step_count = toc_items_list | length %}
{% let tutorial_id = page?.slug ?? page?._path ?? '' %}

<div class="container">
  <div class="tutorial-page-layout{{ ' tutorial-with-toc' if toc else '' }}">
    <article class="tutorial-page prose {{ css_class }}">
      {% include 'partials/page-hero.html' %}

      <div class="tutorial-page-extras">
        {# Tutorial Icon #}
        {% if tut_icon %}
        <div class="tutorial-page-icon">{{ tut_icon }}</div>
        {% end %}

        {# Tutorial Metadata Bar #}
        <div class="tutorial-page-meta">
          {# Difficulty #}
          {% if tut_difficulty %}
          <span class="tutorial-badge tutorial-badge-{{ tut_difficulty }}">
            {{ tut_difficulty | capitalize }}
          </span>
          {% end %}

          {# Time Estimate #}
          {% if tut_time %}
          <span class="tutorial-meta-item">
            {{ icon('clock', size=16) }} {{ tut_time }}
          </span>
          {% end %}

          {# Last Updated #}
          {% if page_date %}
          <span class="tutorial-meta-item">
            {{ icon('calendar', size=16) }} Updated {{ page_date | time_ago }}
          </span>
          {% end %}
        </div>

        {# Scroll-driven progress — updated by tutorials.js #}
        {% if tutorial_step_count >= 2 %}
        <div class="tutorial-progress-host" id="tutorial-header-progress" data-tutorial-total="{{ tutorial_step_count }}">
          {{ tutorial_progress_indicator(tutorial_step_count, 1) }}
        </div>
        {% end %}

        {# Prerequisites #}
        {% if tut_prereqs | length > 0 %}
        <div class="tutorial-prerequisites">
          <h4>{{ t('tutorial.prerequisites', default='Prerequisites') }}</h4>
          <ul>
            {% for prereq in tut_prereqs %}
            <li>
              {% if prereq is string %}
              {% let prereq_page = doc(prereq, site?.indexes?.crossref) if site?.indexes?.crossref else none %}
              {% if prereq_page %}
              <a href="{{ prereq_page.href }}" class="tutorial-prereq-link">{{ prereq_page.title }}</a>
              {% else %}
              {% let prereq_ref = ref(prereq, site?.indexes?.crossref) if site?.indexes?.crossref else none %}
              {% if prereq_ref and '<a' in prereq_ref %}{{ prereq_ref | safe }}{% else %}{{ prereq }}{% end %}
              {% end %}
              {% else %}
              {{ prereq }}
              {% end %}
            </li>
            {% end %}
          </ul>
        </div>
        {% end %}

        {# What You'll Learn #}
        {% if tut_objectives | length > 0 %}
        <div class="tutorial-objectives">
          <h4>{{ t('tutorial.what_you_will_learn', default="What you'll learn") }}</h4>
          <ul>
            {% for objective in tut_objectives %}
            <li>{{ objective }}</li>
            {% end %}
          </ul>
        </div>
        {% end %}
      </div>

      {# Main Tutorial Content #}
      <div class="tutorial-content">
        {{ content | safe }}
      </div>

      {# What's Next / Further Reading #}
      {% if tut_next_steps | length > 0 or tut_further_reading | length > 0 %}
      <footer class="tutorial-footer">
        {% if tut_next_steps | length > 0 %}
        <div class="tutorial-next-steps">
          <h3>{{ t('tutorial.whats_next', default="What's Next?") }}</h3>
          <ul>
            {% for step in tut_next_steps %}
            <li>{{ step }}</li>
            {% end %}
          </ul>
        </div>
        {% end %}

        {% if tut_further_reading | length > 0 %}
        <div class="tutorial-further-reading">
          <h3>{{ t('tutorial.further_reading', default='Further Reading') }}</h3>
          <ul>
            {% for resource in tut_further_reading %}
            <li>{{ resource }}</li>
            {% end %}
          </ul>
        </div>
        {% end %}
      </footer>
      {% end %}
    </article>

    {# Right Sidebar: TOC + scroll-synced step nav #}
    {% if toc %}
    <bengal-tutorial-progress data-tutorial-id="{{ tutorial_id }}">
    <aside class="tutorial-sidebar">
      <nav class="toc" aria-label="Table of contents">
        <h2 class="toc-title">Tutorial Steps</h2>
        <div class="toc-content">
          {{ toc | safe }}
        </div>
      </nav>
    </aside>
    </bengal-tutorial-progress>
    {% end %}
  </div>
</div>

{# Prominent Prev/Next Navigation #}
<div class="tutorial-navigation">
  {{ page_navigation(page) }}
</div>

{# Related Tutorials #}
{% if page_tags | length > 0 %}
{% let related = page?.related_posts ?? [] %}
{% let related_tutorials = related[:3] %}
{% if related_tutorials | length > 0 %}
<aside class="related-tutorials">
  <div class="container">
    <h2>{{ t('tutorial.related', default='Related Tutorials') }}</h2>
    <div class="tutorial-grid">
      {% for tutorial in related_tutorials %}
      {{ related_tutorial_card(tutorial) }}
      {% end %}
    </div>
  </div>
</aside>
{% end %}
{% end %}
{% end %}