{#
  macros/helper.html - Utility macros for internal use across APEP macro files.
  Import with: {% from "apep/macros/helper.html" import alert %}

  Macros:
    alert(message, detail)
    test_keys(required_keys, delivered_keys)

  Author: sora7672
#}


{#
  Renders a dismissible dev-facing error alert inside a macro when required
  params are missing or invalid values are passed.
  Dismissed via helper.js - renders even when JS is not loaded yet,
  so it is always visible on misconfiguration.

  @param message {string} - short error summary shown as the alert title
  @param detail  {string} - longer explanation or usage hint, optional
#}
{% macro alert(message, detail=None) %}
<div class="apep-alert" role="alert" data-apep-alert>
    <div class="apep-alert-inner">
        <div class="apep-alert-header">
            <span class="apep-alert-icon" aria-hidden="true">⚠</span>
            <span class="apep-alert-title">{{ message }}</span>
            <button class="apep-alert-close" type="button" data-apep-alert-close aria-label="Dismiss">&#10005;</button>
        </div>
        {% if detail %}
        <p class="apep-alert-detail">{{ detail }}</p>
        {% endif %}
    </div>
</div>
<script>ApepLoader.register("helper.js", "defer");</script>
{% endmacro %}


{#
  Checks that all required template keys were delivered by the backend.
  Call at the top of every page template, before any content is rendered.
  Renders a visible alert per missing key when delivered_keys is incomplete.
  Renders a single alert when either param is not a list/iterable.

  @param required_keys  {list} - list of key name strings the page expects
  @param delivered_keys {list} - list of key name strings delivered by the backend
#}
{% macro test_keys(required_keys, delivered_keys) %}
    {% if required_keys is not iterable or required_keys is string %}
        {{ alert("test_keys: required_keys must be a list", "Pass a list of key name strings as the first argument.") }}
    {% elif delivered_keys is not iterable or delivered_keys is string %}
        {{ alert("test_keys: delivered_keys must be a list", "Pass a list of key name strings as the second argument. delivered_keys is provided globally by the backend.") }}
    {% else %}
        {% for key in required_keys %}
            {% if key not in delivered_keys %}
                {{ alert("Missing template variable: " ~ key, "This variable was not delivered by the backend. Check the PageBuilder context for this route.") }}
            {% endif %}
        {% endfor %}
    {% endif %}
{% endmacro %}