{#
================================================================================
Function Member Macro (Kida-Native)
================================================================================

Renders a function as a collapsible card with status dot, param count, and return type.
Uses the unified autodoc design system.

USAGE:
{% from 'autodoc/partials/_macros/function-member.html' import function_member %}
{{ function_member(func, is_first=loop.first) }}

ARGS:
func: Function DocElement to render (required)
is_first: Whether this is the first item (to auto-open)

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

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

{% def function_member(func, is_first=false) %}
{# Pre-compute all values with null-safety #}
{% let
func_meta = func?.metadata ?? {},
func_params = func_meta?.args ?? func_meta?.parameters ?? [],
func_return = func_meta?.return_type ?? func_meta?.returns ?? '',
func_signature = func_meta?.signature ?? '',
is_async = func_meta?.is_async ?? false,
func_name = func?.name ?? 'unknown',
func_desc = func?.description ?? '',
func_raises = func_meta?.raises ?? [],
return_desc = func_meta?.return_description ?? ''
%}

<details class="autodoc-member" data-member="function" {% if is_first %}open{% end %}>
  <summary class="autodoc-member-header">
    {# Status dot (green for functions) #}
    <span class="autodoc-member-dot"></span>

    {# Content wrapper #}
    <div class="autodoc-member-content">
      <div class="autodoc-member-name-row">
        <code class="autodoc-member-name">{{ func_name }}</code>
        {# Parameter count badge #}
        <span class="autodoc-member-count"
          title="{{ func_params | length }} parameter{% if func_params | length != 1 %}s{% end %}">{{ func_params |
          length }}</span>
        {# Return type with arrow #}
        {% if func_return %}
        <span class="autodoc-member-return" title="Returns {{ func_return }}">
          <code>{{ func_return | truncate(25, True, '…') }}</code>
        </span>
        {% end %}
        {# Toggle indicator #}
        <span class="autodoc-member-toggle">▼</span>
      </div>
      {# Description preview (for scanning) #}
      {% if func_desc %}
      <span class="autodoc-member-desc-preview">{{ func_desc | striptags | truncate(80, True, '…') }}</span>
      {% end %}
    </div>

    {# Badges #}
    {% if is_async %}
    <span class="autodoc-member-badges">
      <span class="autodoc-badge" data-badge="async">async</span>
    </span>
    {% end %}
  </summary>

  <div class="autodoc-member-body">
    {# Signature (copy-paste ready) #}
    {% if func_signature %}
    <div class="autodoc-signature-section">
      <code class="autodoc-member-sig">{{ func_signature }}</code>
    </div>
    {% end %}

    {# Full description - only show if truncated in header #}
    {% set desc_stripped = func_desc | striptags | trim if func_desc else '' %}
    {% if func_desc and desc_stripped | length > 77 %}
    <div class="autodoc-member-desc prose">
      {{ func_desc | markdownify | safe }}
    </div>
    {% end %}

    {# Function parameters - args is a list of dicts with name, type, docstring, default #}
    {% if func_params | length > 0 %}
    <div class="autodoc-params-section">
      <h5 class="autodoc-params-title">Parameters</h5>
      <table class="autodoc-table autodoc-table--compact" data-table="parameters">
        <thead>
          <tr>
            <th>Name</th>
            <th>Type</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          {% for param in func_params %}
          {# Extract param properties with null-safety #}
          {% set param_name = param?.name ?? 'unknown' %}
          {% set param_type = param?.type ?? '' %}
          {% set param_desc = param?.docstring ?? '' %}
          {% set param_default = param?.default %}
          <tr>
            <td class="autodoc-cell-name"><code>{{ param_name }}</code></td>
            <td class="autodoc-cell-type"><code>{{ param_type if param_type else '—' }}</code></td>
            <td class="autodoc-cell-desc">
              {{ param_desc | markdownify | safe if param_desc else '' }}
              {% if param_default is not none and param_default != '' %}
              <span class="autodoc-param-default">Default: <code>{{ param_default }}</code></span>
              {% end %}
            </td>
          </tr>
          {% end %}
        </tbody>
      </table>
    </div>
    {% end %}

    {# Return type (detailed) - only show if has description OR non-trivial type #}
    {# Trivial types (None) are already visible in header badge + signature #}
    {% set is_nontrivial_return = func_return and func_return not in ('None', 'none', 'void', '') %}
    {% if return_desc or is_nontrivial_return %}
    <div class="autodoc-returns">
      <h5 class="autodoc-returns-title">Returns</h5>
      <code class="autodoc-returns-type">{{ func_return }}</code>
      {% if return_desc %}
      <span class="autodoc-returns-desc">{{ return_desc }}</span>
      {% end %}
    </div>
    {% end %}

    {# Raises #}
    {% if func_raises | length > 0 %}
    <dl class="autodoc-raises">
      {% for exc in func_raises %}
      <div class="autodoc-raise">
        <dt><code>{{ exc?.type ?? 'Exception' }}</code></dt>
        <dd>{{ exc?.description ?? '' }}</dd>
      </div>
      {% end %}
    </dl>
    {% end %}
  </div>
</details>
{% end %}