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

{# =============================================================================
   HELPER FUNCTIONS
   ============================================================================= #}

{# Parse discover config with smart defaults #}
{% def parse_discover_config(discover_config, default_title, default_variant='compact', default_limit=5) %}
{% match discover_config %}
  {% case false %}
    {# Explicitly disabled #}
    {{ {'enabled': false, 'title': none, 'variant': none, 'limit': 0} }}
  {% case _ if discover_config is mapping %}
    {# Config object provided #}
    {{ {
      'enabled': true,
      'title': discover_config.title ?? default_title if discover_config.title is not sameas false else none,
      'variant': discover_config.variant ?? default_variant,
      'limit': discover_config.limit ?? default_limit
    } }}
  {% case _ if discover_config is number %}
    {# Just a limit number #}
    {{ {'enabled': true, 'title': default_title, 'variant': default_variant, 'limit': discover_config} }}
  {% case _ %}
    {# Default: enabled with defaults #}
    {{ {'enabled': true, 'title': default_title, 'variant': default_variant, 'limit': default_limit} }}
{% end %}
{% end %}

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

{% block content %}
{# Template-scoped configuration #}
{% let discover = params?.discover ?? {} %}
{% let children_config = parse_discover_config(discover?.children, 'In This Section', 'compact', 999) %}
{% let related_config = parse_discover_config(discover?.related, 'Related Pages', 'compact', 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">
  {# Left Sidebar: Navigation #}
  <aside class="docs-sidebar" id="docs-sidebar" role="navigation" aria-label="Documentation navigation">
    {% include 'partials/docs-nav.html' %}
  </aside>

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

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