{#-
Navigation and Cross-Reference Macros

Provides consistent navigation, linking, and cross-reference patterns
across all documentation types.
-#}

{% from 'macros/safe_macros.md.jinja2' import safe_attr, safe_var %}

{#- Generate safe anchor links -#}
{% macro safe_anchor(text) %}
{%- if text -%}
{{ text | lower | replace(' ', '-') | replace('.', '-') | replace('_', '-') | replace('(', '') | replace(')', '') }}
{%- endif -%}
{% endmacro %}

{#- Internal documentation link -#}
{% macro doc_link(target, text=None, anchor=None) %}
{%- set link_text = text or target -%}
{%- if anchor -%}
[{{ link_text }}]({{ target }}#{{ safe_anchor(anchor) }})
{%- else -%}
[{{ link_text }}]({{ target }})
{%- endif -%}
{% endmacro %}

{#- Cross-reference to another element -#}
{% macro xref(element_name, element_type="", text=None) %}
{%- set link_text = text or element_name -%}
{%- if element_type == "class" -%}
{{ doc_link("/api/" + element_name.lower().replace('.', '/') + "/", link_text) }}
{%- elif element_type == "function" -%}
{{ doc_link("/api/" + element_name.lower().replace('.', '/') + "/", link_text) }}
{%- elif element_type == "command" -%}
{{ doc_link("/cli/" + element_name.lower().replace(' ', '/') + "/", link_text) }}
{%- else -%}
`{{ link_text }}`
{%- endif -%}
{% endmacro %}

{#- Source code link -#}
{% macro source_link(source_file, line_number=None, text="View source") %}
{% if source_file %}
{%- set github_repo = none -%}
{%- set branch = 'main' -%}

{#- 1. Check autodoc_config first (available during markdown generation) -#}
{%- if autodoc_config is defined -%}
  {%- if 'github_repo' in autodoc_config -%}
    {%- set github_repo = autodoc_config['github_repo'] -%}
  {%- endif -%}
  {%- if 'github_branch' in autodoc_config -%}
    {%- set branch = autodoc_config['github_branch'] -%}
  {%- endif -%}
{%- endif -%}

{#- 2. Check config.autodoc (site build time) -#}
{%- if not github_repo and config is defined -%}
  {%- if 'autodoc' in config -%}
    {%- set autodoc_section = config['autodoc'] -%}
    {%- if 'github_repo' in autodoc_section -%}
      {%- set github_repo = autodoc_section['github_repo'] -%}
    {%- endif -%}
    {%- if 'github_branch' in autodoc_section -%}
      {%- set branch = autodoc_section['github_branch'] -%}
    {%- endif -%}
  {%- endif -%}
  
  {#- 3. Fallback: check top-level config for backward compatibility -#}
  {%- if not github_repo and 'github_repo' in config -%}
    {%- set github_repo = config['github_repo'] -%}
  {%- endif -%}
  {%- if (not branch or branch == 'main') and 'github_branch' in config -%}
    {%- set branch = config['github_branch'] -%}
  {%- endif -%}
{%- endif -%}

{%- if github_repo -%}
  {%- set clean_path = source_file | project_relative -%}
  {%- set source_url = 'https://github.com/' + github_repo + '/blob/' + branch + '/' + clean_path -%}
  {%- if line_number -%}
    {%- set source_url = source_url + '#L' + line_number|string -%}
  {%- endif -%}
  [{{ text }}]({{ source_url }})
{%- else -%}
  {%- set clean_path = source_file | project_relative -%}
  {%- if line_number -%}
    [{{ text }}]({{ clean_path }}#L{{ line_number }})
  {%- else -%}
    [{{ text }}]({{ clean_path }})
  {%- endif -%}
{%- endif -%}
{% endif %}
{% endmacro %}

{#- Breadcrumb navigation -#}
{% macro breadcrumbs(element) %}
{% if element and element.qualified_name %}
{%- set parts = element.qualified_name.split('.') -%}
{% if parts|length > 1 %}
**Navigation:**
{% for part in parts %}
{%- if loop.last -%}
{{ part }}
{%- else -%}
{{ doc_link("/api/" + (parts[:loop.index]|join('/')|lower) + "/", part) }} ›
{%- endif -%}
{% endfor %}
{% endif %}
{% endif %}
{% endmacro %}

{#- Table of contents for long pages -#}
{% macro table_of_contents(sections, title="Contents") %}
{% if sections and sections|length > 1 %}

**{{ title }}:**

{% for section in sections %}
- [{{ section.title }}](#{{ safe_anchor(section.title) }})
{% if section.subsections %}
{% for subsection in section.subsections %}
  - [{{ subsection.title }}](#{{ safe_anchor(subsection.title) }})
{% endfor %}
{% endif %}
{% endfor %}

{% endif %}
{% endmacro %}

{#- Related links section -#}
{% macro related_links(links, title="See Also") %}
{% if links and links|length > 0 %}

## {{ title }}

{% for link in links %}
{% if link is string %}
- {{ link }}
{% else %}
{%- if link.description -%}
- {{ doc_link(safe_attr(link, 'url', ''), safe_attr(link, 'title', 'Related')) }} - {{ link.description }}
{%- else -%}
- {{ doc_link(safe_attr(link, 'url', ''), safe_attr(link, 'title', 'Related')) }}
{%- endif -%}
{% endif %}
{% endfor %}

{% endif %}
{% endmacro %}

{#- Inheritance chain for classes -#}
{% macro inheritance_chain(bases, title="Inheritance") %}
{% if bases and bases|length > 0 %}

**{{ title }}:**
{% for base in bases %}
{%- if not loop.last -%}
{{ xref(base, "class") }} →
{%- else -%}
{{ xref(base, "class") }}
{%- endif -%}
{% endfor %}

{% endif %}
{% endmacro %}

{#- Method/function signatures with links -#}
{% macro signature_with_links(signature, element) %}
{% if signature %}
```python
{{ signature }}
```
{% if element and element.source_file %}

{{ source_link(element.source_file, element.line_number if element.line_number else None) }}
{% endif %}
{% endif %}
{% endmacro %}

{#- API endpoint navigation -#}
{% macro api_endpoint_nav(method, path, title=None) %}
{%- set display_title = title or (method.upper() + " " + path) -%}
**{{ display_title }}**

`{{ method.upper() }} {{ path }}`
{% endmacro %}

{#- CLI command navigation -#}
{% macro cli_command_nav(command_path, description=None) %}
**Command:** `{{ command_path }}`
{% if description %}

{{ description }}
{% endif %}
{% endmacro %}

{#- Back to parent navigation -#}
{% macro back_to_parent(parent_name, parent_url, parent_type="module") %}

---

← Back to {{ doc_link(parent_url, parent_name + " " + parent_type) }}
{% endmacro %}

{#- External link with icon -#}
{% macro external_link(url, text, description=None) %}
{%- if description -%}
[{{ text }} ↗]({{ url }}) - {{ description }}
{%- else -%}
[{{ text }} ↗]({{ url }})
{%- endif -%}
{% endmacro %}
