{#
================================================================================
Autodoc Parameters Table Partial (Kida-Native)
================================================================================

Renders parameters/options/arguments as a table.
Works with CLI DocElements, OpenAPI raw dicts, and Python args.

TEMPLATE VARIABLES:
- params: list of DocElements or dicts - required
- title: str, table title (default: 'Parameters')
- param_type: str: 'option', 'argument', 'parameter' (default: 'parameter')

SUPPORTED SOURCES:
- CLI DocElements: param.metadata.type, param.description
- OpenAPI dicts: param.schema.type, param.description
- Python args: param.type, param.docstring

KIDA FEATURES USED:
- Optional chaining (?.) for safe attribute access
- Null coalescing (??) for defaults
- {% let %} for template-scoped caching

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

{% let
table_title = title ?? 'Parameters',
table_param_type = param_type ?? 'parameter'
%}

{% if params | length > 0 %}
<section class="autodoc-section" data-section="parameters">
  <h2 class="autodoc-section-title">{{ table_title }}</h2>

  <table class="autodoc-table" data-table="parameters">
    <thead>
      <tr>
        <th>Name</th>
        <th>Type</th>
        <th>Default</th>
        <th>Description</th>
      </tr>
    </thead>
    <tbody>
      {% for param in params %}
      {# Extract metadata with null-safety using {% let %} #}
      {% let meta = param?.metadata ?? {} %}
      {% let schema = param?.schema ?? {} %}

      {# Required: check metadata first, then param directly #}
      {% let is_required = meta?.required ?? param?.required ?? false %}

      {# Name: CLI opts array, or direct name #}
      {% let opts = meta?.opts ?? [] %}
      {% let param_name = opts | join(', ') if opts | length > 0 else param?.name ?? 'unknown' %}

      {# Type: CLI meta.type, OpenAPI schema.type, or Python type #}
      {% let param_type_val = meta?.type ?? schema?.type ?? param?.type ?? '' %}

      {# Default: CLI meta.default, OpenAPI schema.default, or Python default #}
      {% let param_default = meta?.default ?? schema?.default ?? param?.default %}

      {# Description: DocElement.description, dict.description, or dict.docstring #}
      {% let param_desc = param?.description ?? param?.docstring ?? meta?.docstring ?? '' %}

      <tr data-required="{{ 'true' if is_required else 'false' }}">
        <td class="autodoc-cell-name" data-label="Name"><code>{{ param_name }}</code></td>
        <td class="autodoc-cell-type" data-label="Type"><code>{{ param_type_val if param_type_val else '—' }}</code>
        </td>
        <td class="autodoc-cell-default" data-label="Default">
          {% if param_default %}
          <code>{{ param_default }}</code>
          {% else %}
          <span class="table-empty">—</span>
          {% end %}
        </td>
        <td class="autodoc-cell-desc" data-label="Description">{{ param_desc | markdownify | safe if param_desc else '—'
          }}</td>
      </tr>
      {% end %}
    </tbody>
  </table>
</section>
{% end %}