{% extends "base.html" %}

{#
================================================================================
Documentation List Template (Kida-Native)
================================================================================

Three-column layout for documentation section index pages.

LAYOUT:
- Left sidebar: Navigation tree
- Center: Content + Content tiles (children + related)
- Right sidebar: Contextual Graph + TOC + metadata

KIDA FEATURES USED:
- {% let %} for template-scoped variables
- Optional chaining (?.) for null-safe access
- Null coalescing (??) for smart defaults
- Pipeline operator (|>) for filter chains
- {% def %} for reusable inline functions
- {% match %} for variant dispatch
- {% cache %} for computed content tiles

FRONTMATTER (discover: structure):
discover:
  children:
    title: "Custom Title"    # or false to hide
    variant: "cards"         # compact | cards | minimal
  children: false            # disable children entirely
  related:
    title: "Custom Title"
    limit: 5
  related: false             # disable related entirely

USAGE:
Set `template: doc/list.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 %}
{% from 'partials/components/tiles.html' import content_tiles %}

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

{% block content %}
{# Template-scoped configuration — discover config parsed inline (Kida defs return Markup) #}
{% let discover = params?.discover ?? {} %}

{% let _ch = discover?.children ?? none %}
{% let _ch_is_map = _ch is mapping %}
{% let _ch_is_num = _ch is number %}
{% let children_config = {
  'enabled': _ch is not sameas false,
  'title': (_ch.title ?? 'In This Section') if _ch_is_map else 'In This Section',
  'variant': (_ch.variant ?? 'compact') if _ch_is_map else 'compact',
  'limit': _ch if _ch_is_num else ((_ch.limit ?? 999) if _ch_is_map else 999)
} %}

{% let _rl = discover?.related ?? none %}
{% let _rl_is_map = _rl is mapping %}
{% let _rl_is_num = _rl is number %}
{% let related_config = {
  'enabled': _rl is not sameas false,
  'title': (_rl.title ?? 'Related Pages') if _rl_is_map else 'Related Pages',
  'variant': (_rl.variant ?? 'compact') if _rl_is_map else 'compact',
  'limit': _rl if _rl_is_num else ((_rl.limit ?? 5) if _rl_is_map else 5)
} %}

{# Feature flag check #}
{% let show_children_feature = 'content.children' in (theme?.features ?? []) %}
{% let show_children = children_config.enabled and show_children_feature %}
{% let show_related = related_config.enabled %}

{# Content availability #}
{% let has_children = (posts | length > 0) or (subsections | length > 0) %}
{% let related_posts = page?.related_posts ?? [] %}
{% let has_related = show_related and (related_posts | length > 0) %}

{# Three-column documentation layout #}
<div class="docs-layout">
  {# Main Content #}
  <div class="docs-main">
    {# Page Hero: List pages default to 'overview' variant #}
    {% let _list_hero_default = 'overview' %}
    {% include 'partials/page-hero.html' %}

    {# Article Content #}
    <article class="prose {{ params?.css_class ?? '' }}">
      {# Main content #}
      <div class="docs-content">
        {{ content | safe }}
      </div>

      {# Content tiles - children and related pages #}
      {% if show_children and (has_children or has_related) %}
      {% cache "doc-list-tiles-" ~ (page?.href ?? '') ~ "-" ~ (site?.build_id ?? '') %}
      <div class="docs-children">
        {{ content_tiles(
          title=children_config.title if has_children else none,
          children=posts if show_children else none,
          subsections=subsections if show_children else none,
          related=related_posts[:related_config.limit] if has_related else none,
          related_title=related_config.title,
          variant=children_config.variant,
          group_by='type' if has_children and has_related else none,
          page=page
        ) }}
      </div>
      {% endcache %}
      {% end %}

      {# Tags #}
      {% if page?.tags | length > 0 %}
      <footer class="docs-footer">
        {{ tag_list(page.tags) }}
      </footer>
      {% end %}
    </article>

    {# 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 #}
{% 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 %}