{% extends "base.html" %}

{#
================================================================================
CLI Reference Command Group Template (Kida-Native)
================================================================================

Renders a CLI command group's documentation showing nested commands and groups.
Extends base.html to inherit theme navigation, sidebars, and styling.

TEMPLATE VARIABLES:
  - element: DocElement for the command group (required)
  - page: PageContext proxy with title, metadata, tags, _path
  - config: Autodoc configuration
  - site: Site instance
  - section: Parent section (for navigation)

Uses the `commands` filter to normalize access to subcommands,
providing a consistent API via CommandView:
  - name, description, usage, href
  - is_group, is_hidden, option_count, argument_count, subcommand_count

================================================================================
#}

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

{% block content %}
{# Use commands filter for normalized access - returns list of CommandView #}
{% let subcommands = element | commands %}
{% let qualified_name = element?.qualified_name ?? '' %}
{% let page_tags = page?.tags ?? [] %}

{# Three-column documentation layout #}
<div class="docs-layout">
  {# Left Sidebar: Navigation #}
  <aside class="docs-sidebar" id="docs-sidebar" role="navigation" aria-label="CLI navigation">
    {% include 'partials/docs-nav.html' %}
  </aside>

  {# Main Content #}
  <div class="docs-main">
    {# Page Hero: Use direct macro call with explicit context #}
    {% from 'partials/page-hero.html' import hero_element %}
    {{ hero_element(element, page, config) }}

    {# Article Content - Unified autodoc skeleton #}
    <article data-autodoc data-type="cli" data-element="command-group" class="autodoc docs-content">

      {# Usage - CLI uses spaces, not dots #}
      {% if qualified_name %}
      {% let cli_usage = qualified_name | replace('.', ' ') %}
      <div class="autodoc-usage">
        <h2 class="autodoc-label">Usage</h2>
        <pre><code class="language-bash">{{ cli_usage }} [COMMAND] [OPTIONS]</code></pre>
      </div>
      {% end %}

      {# Commands and Sub-groups - using CommandView properties #}
      {% if subcommands | length > 0 %}
      <section class="autodoc-section" data-section="subcommands">
        <h2 class="autodoc-section-title">Commands</h2>
        <div class="autodoc-cards">
          {% for cmd in subcommands %}
          {% if not cmd.is_hidden %}
          <a href="{{ cmd.href }}" class="autodoc-card" data-card="{{ 'command-group' if cmd.is_group else 'command' }}">
            <code class="autodoc-card-name">{{ cmd.name }}</code>
            {% if cmd.description %}
            <span class="autodoc-card-desc">{{ cmd.description | truncate(100) }}</span>
            {% elif cmd.is_group %}
            <span class="autodoc-card-desc">{{ cmd.subcommand_count }} {{ cmd.subcommand_count | pluralize('command') }}</span>
            {% else %}
            <span class="autodoc-card-desc">{{ cmd.option_count }} options</span>
            {% end %}
          </a>
          {% end %}
          {% end %}
        </div>
      </section>
      {% end %}

      {# Tags - with null-safe access #}
      {% if page_tags | length > 0 %}
      <footer class="docs-footer">
        <span class="docs-footer-label">Tagged</span>
        {% from 'partials/components/tags.html' import tag_list %}
        {{ tag_list(page_tags) }}
      </footer>
      {% end %}
    </article>

    {# Page navigation (prev/next) at bottom - null-safe #}
    {% if page %}
    {{ page_navigation(page) }}
    {% end %}
  </div>

  {# Right Sidebar: Contextual Graph + TOC + Metadata #}
  {% include 'partials/docs-toc-sidebar.html' %}
</div>

{# Mobile sidebar toggle button #}
<button class="docs-sidebar-toggle" aria-label="Toggle navigation sidebar" aria-expanded="false"
  aria-controls="docs-sidebar">
  {{ icon('list', size=20) }}
</button>

{# Sidebar overlay for mobile #}
<div class="docs-sidebar-overlay" aria-hidden="true"></div>
{% end %}