{# ============================================
   Help System Macros
   Reusable tooltip and help panel components
   ============================================ #}

{# ---------------------------------------------
   TOOLTIP MACRO
   Wraps text with hover tooltip

   Parameters:
   - label: The visible text to display
   - tip: The tooltip text shown on hover
   - position: 'top' (default), 'right', 'left', 'bottom'
   --------------------------------------------- #}
{% macro tooltip(label, tip, position='top') %}
<span class="ldr-help-tooltip{% if position != 'top' %} ldr-help-tooltip--{{ position }}{% endif %}"
      data-tooltip="{{ tip }}"
      tabindex="0"
      role="tooltip"
      aria-label="{{ tip }}">{{ label }}</span>
{%- endmacro %}

{# ---------------------------------------------
   LABEL WITH TOOLTIP MACRO
   Renders a label where the text itself has a tooltip

   Parameters:
   - label_text: The label text (will have tooltip on hover)
   - tooltip_text: The tooltip text shown on hover
   - for_id: The ID of the input (for label's 'for' attribute)
   - position: Tooltip position
   --------------------------------------------- #}
{% macro label_with_tooltip(label_text, tooltip_text, for_id=none, position='top') %}
<label{% if for_id %} for="{{ for_id }}"{% endif %}>{{ tooltip(label_text, tooltip_text, position) }}</label>
{%- endmacro %}

{# ---------------------------------------------
   HELP PANEL MACRO
   Renders a collapsible help panel

   Parameters:
   - panel_id: Unique ID for the panel
   - title: Panel title
   - icon: FontAwesome icon (default: 'question-circle')
   - collapsed: Start collapsed (default: true)
   - dismissible: Show "don't show again" option (default: false)

   Usage:
   {% call help_panel('research-how', 'How Research Works') %}
     <p>Your content here...</p>
   {% endcall %}
   --------------------------------------------- #}
{% macro help_panel(panel_id, title, icon='question-circle', collapsed=true, dismissible=false) %}
<div class="ldr-help-panel{% if collapsed %} collapsed{% endif %}"
     id="help-panel-{{ panel_id }}"
     data-panel-id="{{ panel_id }}">
    <div class="ldr-help-panel-header"
         role="button"
         tabindex="0"
         aria-expanded="{{ 'false' if collapsed else 'true' }}"
         aria-controls="help-panel-content-{{ panel_id }}"
         onclick="HelpService.togglePanel('{{ panel_id }}')"
         onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();HelpService.togglePanel('{{ panel_id }}');}">
        <div class="ldr-help-panel-title">
            <i class="{{ 'fas fa-' ~ icon }}" aria-hidden="true"></i>
            <span>{{ title }}</span>
        </div>
        <i aria-hidden="true" class="fas fa-chevron-down ldr-help-panel-toggle" ></i>
    </div>
    <div class="ldr-help-panel-content" id="help-panel-content-{{ panel_id }}">
        {{ caller() }}
        {% if dismissible %}
        <div class="ldr-help-panel-dismiss">
            <label>
                <input type="checkbox"
                       onchange="HelpService.dismissPanel('{{ panel_id }}')"
                       aria-label="Don't show this help panel again">
                <span>Don't show this again</span>
            </label>
        </div>
        {% endif %}
    </div>
</div>
{%- endmacro %}

{# ---------------------------------------------
   HELP STEP MACRO
   Renders a numbered step in a help panel

   Parameters:
   - num: Step number
   - title: Step title
   - description: Step description
   --------------------------------------------- #}
{% macro help_step(num, title, description) %}
<div class="ldr-help-step">
    <span class="ldr-help-step-num">{{ num }}</span>
    <div class="ldr-help-step-content">
        <strong>{{ title }}</strong>
        <p>{{ description }}</p>
    </div>
</div>
{%- endmacro %}

{# ---------------------------------------------
   HELP TIP MACRO
   Renders a tip/note callout

   Parameters:
   - text: The tip text (can include HTML)
   - variant: 'info' (default), 'warning'
   --------------------------------------------- #}
{% macro help_tip(text, variant='info') %}
<div class="ldr-help-tip{% if variant == 'warning' %} ldr-help-tip--warning{% endif %}">
    <i aria-hidden="true" class="fas fa-{% if variant == 'warning' %}exclamation-triangle{% else %}lightbulb{% endif %}" ></i>
    <span>{{ text|safe }}</span>
</div>
{%- endmacro %}

{# ---------------------------------------------
   HELP CARD MACRO
   Renders a help card (for storage modes, etc.)

   Parameters:
   - title: Card title
   - description: Card description
   - icon: FontAwesome icon
   - variant: 'success', 'warning', 'neutral', 'info'
   --------------------------------------------- #}
{% macro help_card(title, description, icon='circle', variant='neutral') %}
<div class="ldr-help-card ldr-help-card--{{ variant }}">
    <div class="ldr-help-card-title">
        <i class="{{ 'fas fa-' ~ icon }}" aria-hidden="true"></i>
        <span>{{ title }}</span>
    </div>
    <p class="ldr-help-card-desc">{{ description }}</p>
</div>
{%- endmacro %}

{# ---------------------------------------------
   PRIVACY NOTE MACRO
   Renders a privacy assurance note

   Parameters:
   - text: The privacy note text
   --------------------------------------------- #}
{% macro privacy_note(text='All data is stored locally on your device only.') %}
<div class="ldr-privacy-note">
    <i aria-hidden="true" class="fas fa-shield-alt" ></i>
    <span>{{ text }}</span>
</div>
{%- endmacro %}

{# ---------------------------------------------
   GLOSSARY TERM MACRO
   Renders an inline term with tooltip definition

   Parameters:
   - term: The term to display
   - definition: The definition to show in tooltip
   --------------------------------------------- #}
{% macro glossary_term(term, definition) %}
<span class="ldr-glossary-term ldr-help-tooltip"
      data-tooltip="{{ definition }}"
      tabindex="0">{{ term }}</span>
{%- endmacro %}

{# ---------------------------------------------
   KEYBOARD HINT MACRO
   Renders a keyboard shortcut hint

   Parameters:
   - keys: List of keys, e.g., ['Ctrl', 'Enter']
   - description: What the shortcut does
   --------------------------------------------- #}
{% macro keyboard_hint(keys, description='') %}
<span class="ldr-keyboard-hint">
    {% for key in keys %}
    <kbd>{{ key }}</kbd>{% if not loop.last %}+{% endif %}
    {% endfor %}
    {% if description %}<span class="ldr-keyboard-hint-desc"> {{ description }}</span>{% endif %}
</span>
{%- endmacro %}