{#
    Reusable pagination navigation macro.

    Parameters:
        page (int): The current page number (1-based).
        total_pages (int): The total number of pages.
        page_urls (list[str]): Pre-computed list of page URLs, one per page
            (index 0 = page 1).  Produced by the generator and available as
            the ``pagination_page_urls`` context variable.

    Example usage (from a template):
        {% from '_pagination.html' import pagination %}
        {{ pagination(page, total_pages, pagination_page_urls) }}
#}
{% macro pagination(page, total_pages, page_urls) %}
{% if total_pages > 1 %}
<nav class="pagination" aria-label="Page navigation">
    {# Previous page link #}
    {% if page > 1 %}
    <a href="{{ page_urls[page - 2] }}" class="pagination-link pagination-prev">← Previous</a>
    {% endif %}

    {# Numbered page links with ellipsis for large ranges #}
    {% set ns = namespace(last_shown=0) %}
    {% for i in range(1, total_pages + 1) %}
        {% if i == 1 or i == total_pages or (i >= page - 2 and i <= page + 2) %}
            {% if ns.last_shown > 0 and i > ns.last_shown + 1 %}
    <span class="pagination-ellipsis">…</span>
            {% endif %}
            {% if i == page %}
    <span class="pagination-link pagination-number pagination-current" aria-current="page">{{ i }}</span>
            {% else %}
    <a href="{{ page_urls[i - 1] }}" class="pagination-link pagination-number">{{ i }}</a>
            {% endif %}
            {% set ns.last_shown = i %}
        {% endif %}
    {% endfor %}

    {# Next page link #}
    {% if page < total_pages %}
    <a href="{{ page_urls[page] }}" class="pagination-link pagination-next">Next →</a>
    {% endif %}
</nav>
{% endif %}
{% endmacro %}