{#
Bengal OpenAPI Schema Component Library (Kida)
==============================================

Recursive {% def %} component for displaying JSON Schema / OpenAPI schema
objects. Migrated from partials/schema-viewer.html (kept as a reference/fallback)
to an explicit, importable component with no ambient {% let %} context.

Usage:
  {% from 'autodoc/openapi/_schema.html' import schema_viewer %}
  {{ schema_viewer(schema, name=schema_name, depth=0) }}

Parameters:
- schema: OpenAPISchemaMetadata or dict (schema_type/type, properties, required,
  enum, example, items, description, and — for advanced specs — oneOf/anyOf/allOf,
  discriminator, additionalProperties, and per-property constraints/flags).
- name: Schema name for display (optional, default none)
- depth: Nesting depth for indentation + recursion guard (default 0)

Advanced rendering (#285) is driven by template-function filters so the same
recursion handles top-level schemas and nested raw property schemas:
  schema_composition / schema_constraints / schema_flags /
  schema_additional_properties. Each returns an empty/None result when its
  construct is absent, so simple schemas render exactly as before.

Kida Features (confirmed against installed kida-templates):
- {% def name(param=default) %} with recursive self-invocation
- {% cache %} for expensive recursive rendering
- {% with %} for nil-safe optional sections
- Optional chaining (?.) and null coalescing (??)
#}
{% def schema_viewer(schema, name=none, depth=0) %}
{% let schema_name = name | default('') %}
{% let schema_type = schema?.schema_type ?? schema?.type ?? 'object' %}
{% let properties = schema?.properties ?? {} %}
{% let required_props = schema?.required ?? () %}
{% let enum_vals = schema?.enum ?? none %}
{% let items_schema = schema?.items ?? none %}
{% let description = schema?.description ?? '' %}
{% let current_depth = depth ?? 0 %}
{% let max_depth = 4 %}
{% let composition = schema | schema_composition %}
{% let constraints = schema | schema_constraints %}
{% let flags = schema | schema_flags %}
{% let additional = schema | schema_additional_properties %}
{% let ref_name = schema | schema_ref %}

{# Distinct cache namespace ('oa-schema-def-') so this {% def %} never collides
   with the legacy partials/schema-viewer.html {% include %} (key prefix
   'schema-viewer-') that list/responses/request-body still use. The legacy
   partial keys only on (name, depth); sharing that namespace caused anonymous
   nested schemas to return each other's cached fragments. #}
{% cache 'oa-schema-def-' ~ (schema_name or 'anon') ~ '-' ~ current_depth %}
{% if ref_name is not none %}
{# Cyclic $ref left by the extractor: show a readable indicator, not an empty box. #}
<div class="api-schema-viewer api-schema-viewer--ref" data-schema-type="$ref">
    <span class="api-schema-viewer__truncated">&#8635; {{ ref_name }} (circular reference)</span>
</div>
{% else %}
<div class="api-schema-viewer api-schema-viewer--depth-{{ current_depth }}" data-schema-type="{{ schema_type }}">
    {# Schema Header #}
    {% if schema_name %}
    <div class="api-schema-viewer__header">
        <code class="api-schema-viewer__name">{{ schema_name }}</code>
        <span class="api-schema-viewer__type">{{ schema_type }}</span>
        {% if flags?.nullable %}<span class="autodoc-badge" data-badge="nullable">nullable</span>{% end %}
        {% if flags?.deprecated %}<span class="autodoc-badge" data-badge="deprecated">deprecated</span>{% end %}
    </div>
    {% end %}

    {# Description #}
    {% if description %}
    <div class="api-schema-viewer__description prose-sm">
        {{ description | markdownify | safe }}
    </div>
    {% end %}

    {# Validation constraints on a primitive / leaf schema #}
    {% if constraints | length > 0 %}
    <div class="api-schema-viewer__constraints">
        {% for clabel, cvalue in constraints |> items %}
        <code class="api-schema-viewer__constraint" data-constraint="{{ clabel }}">{{ clabel }}{% if cvalue %}: {{ cvalue }}{% end %}</code>
        {% end %}
    </div>
    {% end %}

    {# Composition: oneOf / anyOf / allOf (+ discriminator) #}
    {% if composition is not none %}
    <div class="api-schema-composition" data-composition="{{ composition.kind }}">
        <div class="api-schema-composition__title">
            {% if composition.kind == 'oneOf' %}One of{% elif composition.kind == 'anyOf' %}Any of{% else %}All of{% end %}
        </div>
        {% if composition.discriminator %}
        <div class="api-schema-composition__discriminator">
            <span class="api-schema-composition__discriminator-label">Discriminated by</span>
            <code class="api-schema-composition__discriminator-prop">{{ composition.discriminator.property_name }}</code>
            {% if composition.discriminator.mapping | length > 0 %}
            <ul class="api-schema-composition__mapping">
                {% for row in composition.discriminator.mapping %}
                <li><code class="api-schema-composition__mapping-value">{{ row.value }}</code> <span class="api-schema-composition__mapping-arrow" aria-hidden="true">&rarr;</span> <span class="api-schema-composition__mapping-target">{{ row.target }}</span></li>
                {% end %}
            </ul>
            {% end %}
        </div>
        {% end %}
        <div class="api-schema-composition__branches">
            {% for branch in composition.branches %}
            {% if composition.kind == 'allOf' %}
            <span class="api-schema-composition__branch"><code>{{ branch.label }}</code> <span class="api-schema-composition__branch-type">{{ branch.schema_type }}</span></span>
            {% elif current_depth < max_depth %}
            <div class="api-schema-composition__variant">{{ schema_viewer(branch.schema, name=branch.label, depth=current_depth + 1) }}</div>
            {% else %}
            <span class="api-schema-viewer__truncated">{{ branch.label }} ({{ branch.schema_type }})&hellip;</span>
            {% end %}
            {% end %}
        </div>
    </div>
    {% end %}

    {# Object Properties #}
    {% if schema_type == 'object' and properties | length > 0 %}
    <div class="api-schema-viewer__properties">
        {% for prop_name, prop_schema in properties |> items %}
        {% let is_required = prop_name in required_props %}
        {% let prop_type = prop_schema?.type ?? prop_schema?.schema_type ?? 'any' %}
        {% let prop_desc = prop_schema?.description ?? '' %}
        {% let prop_enum = prop_schema?.enum %}
        {% let prop_default = prop_schema?.default %}
        {% let prop_flags = prop_schema | schema_flags %}
        {% let prop_constraints = prop_schema | schema_constraints %}
        {% let prop_composition = prop_schema | schema_composition %}
        {% let prop_additional = prop_schema | schema_additional_properties %}
        {% let prop_structural = prop_schema?.properties or prop_composition is not none or prop_additional is not none %}

        <div class="api-schema-viewer__property{% if is_required %} api-schema-viewer__property--required{% end %}">
            <div class="api-schema-viewer__property-header">
                <code class="api-schema-viewer__property-name">{{ prop_name }}</code>
                <span class="api-schema-viewer__property-type">{{ prop_type }}</span>
                {% if is_required %}<span class="badge badge--danger-subtle badge--xs">required</span>{% end %}
                {% if prop_flags?.nullable %}<span class="autodoc-badge" data-badge="nullable">nullable</span>{% end %}
                {% if prop_flags?.readOnly %}<span class="autodoc-badge" data-badge="readonly">read-only</span>{% end %}
                {% if prop_flags?.writeOnly %}<span class="autodoc-badge" data-badge="writeonly">write-only</span>{% end %}
                {% if prop_flags?.deprecated %}<span class="autodoc-badge" data-badge="deprecated">deprecated</span>{% end %}
            </div>

            {% if prop_desc %}
            <div class="api-schema-viewer__property-desc">{{ prop_desc }}</div>
            {% end %}

            {# Per-property validation constraints (format, pattern, min/max, ...) #}
            {% if prop_constraints | length > 0 %}
            <div class="api-schema-viewer__constraints">
                {% for clabel, cvalue in prop_constraints |> items %}
                <code class="api-schema-viewer__constraint" data-constraint="{{ clabel }}">{{ clabel }}{% if cvalue %}: {{ cvalue }}{% end %}</code>
                {% end %}
            </div>
            {% end %}

            {# Structural property: nested object, composition (oneOf/anyOf/allOf),
               or a typed/open map (additionalProperties). Recurse into the full
               viewer so inline compositions and maps render, not just top-level
               component schemas. Depth-bounded with a truncation marker. #}
            {% if prop_structural %}
            {% if current_depth < max_depth %}{{ schema_viewer(prop_schema, name=prop_name, depth=current_depth + 1) }}{% else %}<span class="api-schema-viewer__truncated">{{ prop_name }} (nested {{ prop_type }})&hellip;</span>{% end %}
            {% end %}

            {# Array items #}
            {% if prop_type == 'array' and prop_schema?.items %}
            <div class="api-schema-viewer__array-items">
                <span class="api-schema-viewer__label">Items:</span>
                {% if current_depth < max_depth %}{{ schema_viewer(prop_schema.items, name=prop_name ~ ' items', depth=current_depth + 1) }}{% else %}<span class="api-schema-viewer__truncated">{{ prop_schema.items?.type ?? prop_schema.items?.schema_type ?? 'item' }}&hellip;</span>{% end %}
            </div>
            {% end %}

            {# Property enum #}
            {% with prop_enum as enums %}
            {% if enums | length > 0 %}
            <div class="api-schema-viewer__enum">
                <span class="api-schema-viewer__enum-label">Allowed:</span>
                {% for val in enums %}
                <code class="api-schema-viewer__enum-value">{{ val }}</code>
                {% end %}
            </div>
            {% end %}
            {% end %}

            {# Property default #}
            {% with prop_default as default %}
            <div class="api-schema-viewer__default">
                <span class="api-schema-viewer__label">Default:</span>
                <code>{{ default }}</code>
            </div>
            {% end %}
        </div>
        {% end %}
    </div>
    {% end %}

    {# Additional properties (typed maps / open objects) #}
    {% if additional is not none %}
    <div class="api-schema-viewer__additional">
        {% if additional?.value_schema %}
        <span class="api-schema-viewer__label">Additional properties</span>
        {% if current_depth < max_depth %}{{ schema_viewer(additional.value_schema, name='(values)', depth=current_depth + 1) }}{% else %}<code class="api-schema-viewer__property-type">{{ additional.schema_type }}</code>{% end %}
        {% elif additional?.allowed %}
        <span class="api-schema-viewer__note">Allows additional properties</span>
        {% else %}
        <span class="api-schema-viewer__note">No additional properties</span>
        {% end %}
    </div>
    {% end %}

    {# Array Items Schema (top-level array) #}
    {% if schema_type == 'array' and items_schema %}
    <div class="api-schema-viewer__array">
        <span class="api-schema-viewer__label">Array of:</span>
        {% if current_depth < max_depth %}{{ schema_viewer(items_schema, name=schema_name ~ ' items', depth=current_depth + 1) }}{% else %}<span class="api-schema-viewer__truncated">{{ items_schema?.type ?? items_schema?.schema_type ?? 'item' }}&hellip;</span>{% end %}
    </div>
    {% end %}

    {# Enum Values (top-level) #}
    {% with enum_vals as enums %}
    {% if enums | length > 0 %}
    <div class="api-schema-viewer__enum">
        <span class="api-schema-viewer__enum-label">Allowed values:</span>
        {% for val in enums %}
        <code class="api-schema-viewer__enum-value">{{ val }}</code>
        {% end %}
    </div>
    {% end %}
    {% end %}

    {# Examples: a singular `example`, a 3.1 `examples` list, or a named
       `examples` map are all normalized to a uniform tuple and rendered here. #}
    {% for ex in (schema | schema_examples) %}
    <div class="api-schema-viewer__example">
        <span class="api-schema-viewer__example-label">{% if ex.name %}{{ ex.name }}{% else %}Example{% end %}</span>
        {% if ex.summary %}<span class="api-schema-viewer__example-summary">{{ ex.summary }}</span>{% end %}
        <pre
            class="api-schema-viewer__example-code"><code class="language-json">{{ ex.value | tojson(indent=2) }}</code></pre>
    </div>
    {% end %}
</div>
{% end %}
{% end %}
{% end %}