{#
  Reusable Component Macros for Bengal Themes

  These macros provide a cleaner, more ergonomic API for common UI components.
  Unlike includes, macros have explicit parameters and don't pollute scope.

  Usage:
    {% from 'partials/components.html' import reference_header %}
    {{ reference_header(icon='📦', title=page.title) }}
#}


{#
  Reference Documentation Header

  Unified header component for all reference documentation types (API, CLI, OpenAPI, etc.)

  Args:
    icon: Icon/emoji to display (e.g., '📦', '⌨️', '🔌')
    title: Page title
    description: Optional lead description (default: None)
    type: Reference type for CSS class ('api', 'cli', 'openapi', etc.)

  Example:
    {{ reference_header(
      icon='📦',
      title=page.title,
      description=page.metadata.get('description', ''),
      type='api'
    ) }}
#}
{% macro reference_header(icon, title, description=None, type='default') %}
<div class="reference-header">
  <span class="reference-icon">{{ icon }}</span>
  <h1>{{ title }}</h1>
</div>
{% if description %}
<p class="lead">{{ description }}</p>
{% endif %}
{% endmacro %}


{#
  Reference Metadata Box

  Displays metadata for reference documentation (module, source, etc.)

  Args:
    metadata: Dict of key-value pairs to display
    type: Reference type for CSS class (default: 'default')

  Example:
    {{ reference_metadata({
      'Module': page.metadata.get('module_path', ''),
      'Source': page.metadata.get('source_file', '')
    }) }}
#}
{% macro reference_metadata(metadata, type='default') %}
{% if metadata %}
<div class="reference-metadata">
  {% for label, value in metadata.items() %}
  {% if value %}
  <div class="reference-metadata-item">
    <strong>{{ label }}:</strong>
    <code>{{ value }}</code>
  </div>
  {% endif %}
  {% endfor %}
</div>
{% endif %}
{% endmacro %}


{#
  Breadcrumbs Component

  Displays breadcrumb navigation

  Args:
    items: List of breadcrumb items [{name, url}, ...]
    separator: Separator character (default: '/')

  Example:
    {{ breadcrumbs([
      {'name': 'Home', 'url': '/'},
      {'name': 'API', 'url': '/api/'},
      {'name': page.title, 'url': page.url}
    ]) }}
#}
{% macro breadcrumbs(items, separator='/') %}
<nav class="breadcrumbs" aria-label="Breadcrumb">
  <ol>
    {% for item in items %}
    <li>
      {% if item.url and not loop.last %}
      <a href="{{ item.url }}">{{ item.name }}</a>
      {% else %}
      <span>{{ item.name }}</span>
      {% endif %}
      {% if not loop.last %}
      <span class="separator">{{ separator }}</span>
      {% endif %}
    </li>
    {% endfor %}
  </ol>
</nav>
{% endmacro %}