django-cotton-bs5 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

cotton_bs5/fixtures.py

@@ -0,0 +1,217 @@
+"""Pytest fixtures for testing Django Cotton BS5 components."""
+
+import pytest
+from bs4 import BeautifulSoup
+from django.template import Context, Template
+from django.test import RequestFactory
+from django_cotton import render_component
+from django_cotton.compiler_regex import CottonCompiler
+
+compiler = CottonCompiler()
+
+@pytest.fixture
+def cotton_render():
+    """
+    Fixture that renders Django-Cotton components and returns raw HTML.
+
+    Automatically provides a request object to be DRY. Component variables
+    are passed as kwargs.
+
+    Usage:
+        def test_something(cotton_render):
+            html = cotton_render(
+                'cotton_bs5.alert',
+                message="Hello",
+                type="success"
+            )
+            assert 'alert-success' in html
+    """
+    factory = RequestFactory()
+
+    def _render(component_name, context=None, **kwargs):
+        """
+        Render a Cotton component with automatic request injection.
+
+        Args:
+            component_name: Component name in dotted notation (e.g., "cotton_bs5.alert")
+            context: Optional context dict to pass as component attributes
+            **kwargs: Component attributes (alternative to context dict)
+
+        Returns:
+            Rendered HTML string
+        """
+        request = factory.get("/")
+        return render_component(request, component_name, context, **kwargs)
+
+    return _render
+
+
+@pytest.fixture
+def cotton_render_soup():
+    """
+    Fixture that renders Django-Cotton components and returns BeautifulSoup parsed HTML.
+
+    Automatically provides a request object and parses the result for easy testing.
+    Component variables are passed as kwargs.
+
+    Usage:
+        def test_something(cotton_render_soup):
+            soup = cotton_render_soup(
+                'cotton_bs5.alert',
+                message="Hello",
+                type="success"
+            )
+            assert soup.find('div')['class'] == ['alert', 'alert-success']
+    """
+    factory = RequestFactory()
+
+    def _render(component_name, context=None, **kwargs):
+        """
+        Render a Cotton component with automatic request injection and parse with BeautifulSoup.
+
+        Args:
+            component_name: Component name in dotted notation (e.g., "cotton_bs5.alert")
+            context: Optional context dict to pass as component attributes
+            **kwargs: Component attributes (alternative to context dict)
+
+        Returns:
+            BeautifulSoup parsed HTML object
+        """
+        request = factory.get("/")
+        html = render_component(request, component_name, context, **kwargs)
+        return BeautifulSoup(html, "html.parser")
+
+    return _render
+
+
+@pytest.fixture
+def cotton_render_string():
+    """
+    Fixture that compiles and renders Django template strings containing Cotton component syntax.
+
+    This fixture takes a raw template string with Cotton components (e.g., <c-button>),
+    compiles it through django-cotton's compiler, then renders it through Django's
+    Template system. Useful for testing inline component markup without creating
+    separate template files.
+
+    Usage:
+        def test_button_in_template(cotton_render_string):
+            html = cotton_render_string("<c-button variant='primary'>Click me</c-button>")
+            assert 'btn-primary' in html
+
+        def test_with_context(cotton_render_string):
+            html = cotton_render_string(
+                "<c-alert>{{ message }}</c-alert>",
+                context={'message': 'Hello World'}
+            )
+            assert 'Hello World' in html
+
+    Returns:
+        A callable function that accepts:
+            - template_string (str): Django template string with Cotton component syntax
+            - context (dict, optional): Template context variables
+
+        The function returns the rendered HTML as a string.
+    """
+    factory = RequestFactory()
+
+    def _render(template_string, context=None):
+        """
+        Compile and render a template string with Cotton components.
+
+        Args:
+            template_string: The Django template string containing Cotton component syntax
+            context: Optional context dict for template variables
+
+        Returns:
+            Rendered HTML string
+        """
+        if context is None:
+            context = {}
+        request = factory.get("/")
+        context['request'] = request
+
+        # Compile Cotton component syntax into Django template syntax
+        compiled_template = compiler.process(template_string)
+
+        # Render through Django's Template system
+        django_template = Template(compiled_template)
+        django_context = Context(context)
+        return django_template.render(django_context)
+
+    return _render
+
+
+@pytest.fixture
+def cotton_render_string_soup():
+    """
+    Fixture that compiles and renders Django template strings with Cotton components,
+    returning BeautifulSoup parsed HTML.
+
+    This fixture combines the capabilities of cotton_render_string with BeautifulSoup
+    parsing for easier DOM traversal and assertions. Particularly useful for testing
+    multi-component features where you need to verify nested structure and relationships.
+
+    Usage:
+        def test_nested_list(cotton_render_string_soup):
+            soup = cotton_render_string_soup(
+                "<c-ul><c-li text='first' /><c-li text='second' /></c-ul>"
+            )
+            items = soup.find_all('li')
+            assert len(items) == 2
+            assert items[0].get_text() == 'first'
+            assert items[1].get_text() == 'second'
+
+        def test_complex_layout_with_context(cotton_render_string_soup):
+            template = '''
+                <c-card>
+                    <c-card.title>{{ title }}</c-card.title>
+                    <c-card.body>
+                        <c-button variant='primary'>{{ action }}</c-button>
+                    </c-card.body>
+                </c-card>
+            '''
+            soup = cotton_render_string_soup(template, context={
+                'title': 'My Card',
+                'action': 'Click Here'
+            })
+            assert soup.find('h5').get_text() == 'My Card'
+            assert 'btn-primary' in soup.find('button')['class']
+
+    Returns:
+        A callable function that accepts:
+            - template_string (str): Django template string with Cotton component syntax
+            - context (dict, optional): Template context variables
+
+        The function returns a BeautifulSoup parsed HTML object.
+    """
+    factory = RequestFactory()
+
+    def _render(template_string, context=None):
+        """
+        Compile, render, and parse a template string with Cotton components.
+
+        Args:
+            template_string: The Django template string containing Cotton component syntax
+            context: Optional context dict for template variables
+
+        Returns:
+            BeautifulSoup parsed HTML object
+        """
+        if context is None:
+            context = {}
+        request = factory.get("/")
+        context['request'] = request
+
+        # Compile Cotton component syntax into Django template syntax
+        compiled_template = compiler.process(template_string)
+
+        # Render through Django's Template system
+        django_template = Template(compiled_template)
+        django_context = Context(context)
+        html = django_template.render(django_context)
+
+        # Parse with BeautifulSoup for easy DOM traversal
+        return BeautifulSoup(html, "html.parser")
+
+    return _render

cotton_bs5/templates/cotton/accordion/index.html

@@ -1,4 +1,4 @@
-<c-vars flush parent class />
+<c-vars flush parent class id="something" />
 <div id="{{ id }}"
      class="accordion{% if flush %} accordion-flush{% endif %} {{ class }}"
      {{ attrs }}>

cotton_bs5/templates/cotton/accordion/item.html

@@ -1,8 +1,14 @@
-<c-vars id text target parent header class />
+{% load cotton_bs5 %}
+<c-vars id text target header class show />
+{% cotton_parent as parent %}
+{% genid "accordion-item" as uid %}
+{% firstof id uid as target %}
 <div class="accordion-item {{ class }}" {{ attrs }}>
-  {% if text %}<c-accordion.header :attrs="attrs" />{% endif %}
+  {% if text %}<c-accordion.header target="{{ target }}" :attrs="attrs" />{% endif %}
   {{ header }}
-  <c-accordion.body id="{{ target }}" :attrs="attrs">
+  <c-accordion.body id="{{ target }}"
+                    parent="{{ parent.id }}"
+                    :attrs="attrs">
     {{ slot }}
   </c-accordion.body>
 </div>

cotton_bs5/templates/cotton/breadcrumbs/index.html

@@ -1,5 +1,5 @@
 {% load i18n %}
-<c-vars ol_class divider="/" items class />
+<c-vars ol_class divider="/" items />
 <nav aria-label="{% trans "breadcrumb" %}"
      style="--bs-breadcrumb-divider: '{{ divider }}'"
      {{ attrs }}>

cotton_bs5/templates/cotton/breadcrumbs/item.html

@@ -1,13 +1,10 @@
-<c-vars href text class />
-<li class="breadcrumb-item{% if not href %} active{% endif %} {{ class }}"
-    {% if not href %}aria-current="page"{% endif %}>
-  {% if href %}
-    <a href="{{ href }}"
-       class="link-underline link-underline-opacity-0 link-underline-opacity-75-hover"
-       {{ attrs }}>
-      {{ text }}{{ slot }}
-    </a>
-  {% else %}
-    {{ text }}{{ slot }}
-  {% endif %}
+<c-vars text class />
+{% with element=href|yesno:"a,span" %}
+  {# djlint:off #}
+<li class="breadcrumb-item{% if element == 'span' %} active{% endif %} {{ class }}"{% if element == 'span' %} aria-current="page"{% endif %}>
+  <{{ element }}{% if href %} class="link-underline link-underline-opacity-0 link-underline-opacity-75-hover"{% endif %} {{ attrs }}>
+  {{ text }}{{ slot }}
+  </{{ element }}>
 </li>
+  {# djlint:on #}
+{% endwith %}

cotton_bs5/templates/cotton/button/index.html

@@ -1,15 +1,8 @@
 <c-vars variant="primary" size="" outline="" text class />
 {# djlint:off #}
-<{% if href %}a{% else %}button{% endif %}
-  class="btn {% if outline %} btn-outline-{{ variant }}{% else %} btn-{{ variant }}{% endif %}
-  {% if size %}btn-{{ size }}{% endif %}
-  {{ class }}" {{ attrs }}>
-{# djlint:on #}
-{% if slot %}
-  {{ slot }}
-{% else %}
-  {{ text }}
-{% endif %}
-{# djlint:off #}
-</{% if href %}a{% else %}button{% endif %}>
+{% with element=href|yesno:"a,button" %}
+<{{ element }} class="btn{% if outline %} btn-outline-{{ variant }}{% else %} btn-{{ variant }}{% endif %}{% if size %} btn-{{ size }}{% endif %} {{ class }}" {{ attrs }}>
+  {{ slot }} {{ text }}
+</{{ element }}>
+{% endwith %}
 {# djlint:on #}

cotton_bs5/templates/cotton/cotton_bs5/document.html

@@ -0,0 +1,8 @@
+{% load cotton_bs5 %}
+<section id="{{ title|slugify }}">
+  <h2>{{ title }}</h2>
+  <p>{{ help }}</p>
+  {% show_code %}
+    {{ slot }}
+  {% endshow_code %}
+</section>

cotton_bs5/templates/cotton/dropdown/item.html

@@ -1,15 +1,6 @@
-<c-vars href text active disabled class />
-{% if href %}
-  <a class="dropdown-item{% if active %} active{% endif %}{% if disabled %} disabled{% endif %} {{ class }}"
-     {% if disabled %}tabindex="-1" aria-disabled="true"{% endif %}
-     {{ attrs }}>
-    {{ text }} {{ slot }}
-  </a>
-{% else %}
-  <button class="dropdown-item{% if active %} active{% endif %}{% if disabled %} disabled{% endif %} {{ class }}"
-          type="button"
-          {% if disabled %}disabled{% endif %}
-          {{ attrs }}>
-    {{ text }} {{ slot }}
-  </button>
-{% endif %}
+<c-vars text active disabled class />
+{% with element=href|yesno:"a,button" %}
+  {# djlint:off #}
+<{{ element }} class="dropdown-item{% if active %} active{% endif %}{% if disabled %} disabled{% endif %}{% if class %} {{ class }}{% endif %}"{% if element == "button" %} type="button"{% endif %}{% if disabled %}{% if element == "a" %} tabindex="-1" aria-disabled="true"{% else %} disabled{% endif %}{% endif %} {{ attrs }}>{{ text }}{{ slot }}</{{ element }}>
+  {# djlint:on #}
+{% endwith %}

cotton_bs5/templates/cotton/grid/col.html

@@ -1,5 +1,5 @@
-<c-vars width="" :responsive="{}" offset="" class />
-<div class="{% if width %}col-{{ width }} {% else %} col {% endif %} {% for bp, width in responsive.items %}col-{{ bp }}-{{ width }}{% endfor %} {{ class }}"
+<c-vars width="" :responsive="{}" offset="" gap=0 class />
+<div class="{% if width %}col-{{ width }}{% else %}col{% endif %}{% for bp, width in responsive.items %} col-{{ bp }}-{{ width }}{% endfor %} gap-{{ gap }} {{ class }}"
      {{ attrs }}>
         {{ slot }}
 </div>

cotton_bs5/templates/cotton/grid/index.html

@@ -1,5 +1,6 @@
-<c-vars cols="" gap="1" :responsive="{}" class />
-<div class="row{% if cols %} row-cols-{{ cols }}{% endif %}{% if gap %} g-{{ gap }}{% endif %}{% for bp,cols in responsive.items %} row-cols-{{ bp }}-{{ cols }}{% endfor %} {{ class }}"
+<c-vars cols=1 gap="1" sm md lg xl xxl class />
+<div class="row{% if cols %} row-cols-{{ cols }}{% endif %}{% if gap %} g-{{ gap }}{% endif %}{% if sm %} row-cols-sm-{{ sm }}{% endif %}{% if md %} row-cols-md-{{ sm }}{% endif %}{% if lg %} row-cols-lg-{{ lg }}{% endif %}{% if xl %} row-cols-xl-{{ xl }}{% endif %}{% if xl %} row-cols-xl-{{ xl }}{% endif %}{% if xxl %} row-cols-xxl-{{ xxl }}{% endif %}{{ class }}"
      {{ attrs }}>
   {{ slot }}
 </div>
+

cotton_bs5/templates/cotton/hstack.html

@@ -0,0 +1,4 @@
+<c-vars gap=1 class />
+<div class="hstack gap-{{ gap }} {{ class }}"
+     {{ attrs }}>{{ slot }}
+</div>

cotton_bs5/templates/cotton/list_group/index.html

@@ -3,9 +3,11 @@
         :horizontal="False"
         class />
 {# djlint:off #}
-<{% if numbered %}ol{% else %}ul{% endif %}
-class="list-group{% if flush %} list-group-flush{% endif %}{% if horizontal %} list-group-horizontal{% if horizontal != True %}-{{ horizontal }}{% endif %}{% endif %}{{ class }}"
+{% with numbered|yesno:"ol,ul" as element %}
+<{{ element }}
+class="list-group{% if flush %} list-group-flush{% endif %}{% if horizontal %} list-group-horizontal{% if horizontal != True %}-{{ horizontal }}{% endif %}{% endif %} {{ class }}"
 {{ attrs }}>
 {{ slot }}
-</{% if numbered %}ol{% else %}ul{% endif %}>
+</{{ element }}>
+{% endwith %}
 {# djlint:on #}

cotton_bs5/templates/cotton/list_group/item.html

@@ -1,9 +1,8 @@
-<c-vars text active disabled variant href tag="li" class />
+<c-vars text active disabled variant class />
 {# djlint:off #}
-<{% if href %}a href="{{ href }}"{% else %}{{ tag }}{% endif %}
-class="list-group-item{% if href %} list-group-item-action{% endif %}{% if active %} active{% elif disabled %} disabled{% endif %}{% if variant %} list-group-item-{{ variant }}{% endif %} {{ class }}"
-{% if active %}aria-current="true"{% elif disabled %}aria-disabled="true"{% endif %}
-{{ attrs }}>
-{{ text }} {{ slot }}
-</{% if href %}a{% else %}{{ tag }}{% endif %}>
+{% with element=href|yesno:"a,li" %}
+<{{ element }} class="list-group-item{% if href %} list-group-item-action{% endif %}{% if active %} active{% elif disabled %} disabled{% endif %}{% if variant %} list-group-item-{{ variant }}{% endif %} {{ class }}"{% if active %} aria-current="true"{% elif disabled %} aria-disabled="true"{% endif %} {{ attrs }}>
+  {{ text }}{{ slot }}
+</{{ element }}>
+{% endwith %}
 {# djlint:on #}

cotton_bs5/templates/cotton/nav/item.html

@@ -0,0 +1,4 @@
+<c-vars class link_class />
+<li class="nav-item {{ class }}">
+  <c-nav.link :attrs="attrs" class="{{ link_class }}" />
+</li>

cotton_bs5/templates/cotton/vstack.html

@@ -0,0 +1,4 @@
+<c-vars gap=1 class />
+<div class="vstack gap-{{ gap }} {{ class }}"
+     {{ attrs }}>{{ slot }}
+</div>

cotton_bs5/templates/cotton_bs5/document_component.html

@@ -0,0 +1,101 @@
+{% load cotton_bs5 %}
+<div class="card component-demo-card">
+  <!-- Rendered Component Preview -->
+  <div class="demo-preview border-bottom p-4">{{ rendered }}</div>
+  <!-- Code Tabs Navigation -->
+  <div class="border-bottom">
+    <div role="tablist"
+         class="nav nav-tabs border-0 px-3 pt-2">
+      {% genid "syntax-tab" as syntax_tab_id %}
+      <button type="button"
+              class="nav-link active"
+              id="{{ syntax_tab_id }}"
+              data-bs-toggle="tab"
+              data-bs-target="#{{ syntax_tab_id }}-pane"
+              role="tab"
+              aria-controls="{{ syntax_tab_id }}-pane"
+              aria-selected="true">
+        <svg xmlns="http://www.w3.org/2000/svg"
+             width="14"
+             height="14"
+             fill="currentColor"
+             class="bi bi-code-slash me-1"
+             viewBox="0 0 16 16">
+          <path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z" />
+        </svg>
+        Cotton Syntax
+      </button>
+      {% genid "html-tab" as html_tab_id %}
+      <button type="button"
+              class="nav-link"
+              id="{{ html_tab_id }}"
+              data-bs-toggle="tab"
+              data-bs-target="#{{ html_tab_id }}-pane"
+              role="tab"
+              aria-controls="{{ html_tab_id }}-pane"
+              aria-selected="false">
+        <svg xmlns="http://www.w3.org/2000/svg"
+             width="14"
+             height="14"
+             fill="currentColor"
+             class="bi bi-file-code me-1"
+             viewBox="0 0 16 16">
+          <path d="M6.646 5.646a.5.5 0 1 1 .708.708L5.707 8l1.647 1.646a.5.5 0 0 1-.708.708l-2-2a.5.5 0 0 1 0-.708l2-2zm2.708 0a.5.5 0 1 0-.708.708L10.293 8 8.646 9.646a.5.5 0 0 0 .708.708l2-2a.5.5 0 0 0 0-.708l-2-2z" />
+          <path d="M2 2a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V2zm10-1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1z" />
+        </svg>
+        HTML Output
+      </button>
+    </div>
+  </div>
+  <!-- Code Tabs Content -->
+  <div class="tab-content">
+    <div class="tab-pane fade show active"
+         id="{{ syntax_tab_id }}-pane"
+         role="tabpanel"
+         aria-labelledby="{{ syntax_tab_id }}"
+         tabindex="0">
+      <div class="position-relative">
+        <button class="btn btn-sm btn-outline-secondary position-absolute top-0 end-0 m-3 copy-btn"
+                data-copy-target="{{ syntax_tab_id }}-code"
+                aria-label="Copy Cotton syntax to clipboard"
+                title="Copy code">
+          <svg xmlns="http://www.w3.org/2000/svg"
+               width="14"
+               height="14"
+               fill="currentColor"
+               class="bi bi-clipboard"
+               viewBox="0 0 16 16">
+            <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z" />
+            <path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z" />
+          </svg>
+          Copy
+        </button>
+        <pre class="mb-0 p-3"><code id="{{ syntax_tab_id }}-code" class="language-html">{{ code }}</code></pre>
+      </div>
+    </div>
+    <div class="tab-pane fade"
+         id="{{ html_tab_id }}-pane"
+         role="tabpanel"
+         aria-labelledby="{{ html_tab_id }}"
+         tabindex="0">
+      <div class="position-relative">
+        <button class="btn btn-sm btn-outline-secondary position-absolute top-0 end-0 m-3 copy-btn"
+                data-copy-target="{{ html_tab_id }}-code"
+                aria-label="Copy HTML output to clipboard"
+                title="Copy code">
+          <svg xmlns="http://www.w3.org/2000/svg"
+               width="14"
+               height="14"
+               fill="currentColor"
+               class="bi bi-clipboard"
+               viewBox="0 0 16 16">
+            <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z" />
+            <path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z" />
+          </svg>
+          Copy
+        </button>
+        <pre class="mb-0 p-3"><code id="{{ html_tab_id }}-code" class="language-html">{{ html }}</code></pre>
+      </div>
+    </div>
+  </div>
+</div>

cotton_bs5/templatetags/cotton_bs5.py

@@ -0,0 +1,267 @@
+"""Template tags and filters for MVP navbar widgets."""
+
+import secrets
+import string
+import textwrap
+
+from django import template
+from django.template.loader import render_to_string
+from django.utils.html import escape
+from django.utils.safestring import mark_safe
+from django_cotton.compiler_regex import CottonCompiler
+
+# Conditional import for BeautifulSoup
+try:
+    from bs4 import BeautifulSoup
+
+    HAS_BEAUTIFULSOUP = True
+except ImportError:
+    HAS_BEAUTIFULSOUP = False
+
+register = template.Library()
+
+compiler = CottonCompiler()
+
+
+@register.filter
+def slot_is_empty(slot):
+    """Check if a template slot is empty after stripping whitespace.
+
+    Django Cotton slots may contain strings with unwanted whitespace or newlines,
+    making direct template checks unreliable. This filter properly handles these
+    cases by stripping whitespace before comparison.
+
+    Args:
+        slot: The slot content to check (typically a string, but may be other types).
+
+    Returns:
+        bool: True if slot is a string with only whitespace or is empty, False otherwise.
+              Returns None implicitly if slot is not a string type.
+
+    Example:
+        {% if slot_content|slot_is_empty %}
+            <p>No content provided</p>
+        {% else %}
+            {{ slot_content }}
+        {% endif %}
+    """
+    if isinstance(slot, str):
+        return slot.strip() == ""
+
+
+@register.filter
+def beautify_html(html):
+    """Clean up and format unformatted HTML with proper indentation.
+
+    Removes common leading whitespace and strips leading/trailing blank lines
+    to produce clean, readable HTML.
+
+    Args:
+        html (str): Unformatted HTML string
+
+    Returns:
+        str: Formatted HTML with normalized indentation
+
+    Example:
+        Input:  "    <div>\n        <p>Hello</p>\n    </div>"
+        Output: "<div>\n    <p>Hello</p>\n</div>"
+    """
+    return textwrap.dedent(html).strip("\n")
+
+
+@register.simple_tag
+def genid(prefix="", length=6):
+    """Generate a unique random ID for use in HTML attributes.
+
+    Produces a short random string suitable for use as unique HTML element IDs.
+    Can optionally include a prefix for semantic naming.
+
+    Args:
+        prefix (str): Optional prefix to prepend to the random string.
+                     If provided, the format is "{prefix}-{random_string}".
+                     Defaults to empty string (no prefix).
+        length (int): Length of the random string to generate.
+                     Defaults to 6 characters.
+
+    Returns:
+        str: Generated ID. If prefix is provided, returns "{prefix}-{random_string}",
+             otherwise returns just the random string.
+
+    Example:
+        {% genid %}                              # Returns something like "a3b2c1"
+        {% genid "tab" %}                        # Returns something like "tab-a3b2c1"
+        {% genid "modal" 8 %}                    # Returns something like "modal-a3b2c1d9"
+        {% genid prefix="button" length=10 %}   # Returns something like "button-a3b2c1d9e7"
+    """
+    random_str = "".join(
+        secrets.choice(string.ascii_lowercase + string.digits) for _ in range(length)
+    )
+    if prefix:
+        return f"{prefix}-{random_str}"
+    return random_str
+
+
+@register.simple_tag(takes_context=True)
+def cotton_parent(context):
+    cotton_data = context.get("cotton_data", {})
+    if not cotton_data:
+        return None
+    stack = cotton_data.get("stack", [])
+    if not stack:
+        return None
+
+    stack_length = len(stack)
+
+    parent_idx = stack_length - 2  # Get the index of the parent element
+
+    # this will ONLY return attrs declared on the component itself, not c-vars
+    return stack[parent_idx]["attrs"]
+
+
+@register.simple_tag(takes_context=True)
+def responsive(context, root: str):
+    """Generate responsive Bootstrap grid classes from context variables.
+
+    This tag generates responsive variants of a root class name (e.g., 'col')
+    by combining it with responsive breakpoint suffixes (xs, sm, md, lg, xl, xxl).
+    Context variables for each breakpoint determine whether the suffix is included
+    and its value.
+
+    Args:
+        context (dict): Django template context, expected to contain optional keys:
+            - xs (str): Extra small breakpoint value
+            - sm (str): Small breakpoint value
+            - md (str): Medium breakpoint value
+            - lg (str): Large breakpoint value
+            - xl (str): Extra large breakpoint value
+            - xxl (str): Extra extra large breakpoint value
+        root (str): Base class name to which responsive variants are appended
+                    (e.g., 'col', 'offset', 'gutter')
+
+    Returns:
+        str: Space-separated responsive class names. For each breakpoint variable
+             present in context, returns "{root}-{breakpoint}-{value}".
+             Returns empty string if no breakpoint variables are defined.
+
+    Example:
+        Context: {'md': '6', 'lg': '4', 'xl': '3'}
+        Tag:     {% responsive 'col' %}
+        Output:  'col-md-6 col-lg-4 col-xl-3'
+    """
+    # The idea is to take a root class name (e.g., "col") and
+    # and generate responsive variants based on context variables xs, sm, md, lg, xl, xxl).
+    # If a context variable is present, the value should be added to root along with the responsive
+    # name (e.g., "col-md-6").
+
+    responsive_values = {
+        responsive: context.get(responsive)
+        for responsive in ["xs", "sm", "md", "lg", "xl", "xxl"]
+    }
+
+    return " ".join(
+        f"{root}-{key}-{value}"
+        for key, value in responsive_values.items()
+        if value is not None
+    )
+
+
+@register.tag(name="show_code")
+def show_code(parser, token):
+    """Parse the show_code block tag.
+
+    Collects the template content between {% show_code %} and {% endshow_code %} tags
+    for processing and rendering.
+
+    Args:
+        parser: Django template parser
+        token: Template token with tag name
+
+    Returns:
+        ShowCodeNode: Node instance that will handle rendering
+    """
+    nodelist = parser.parse(("endshow_code",))
+    parser.delete_first_token()
+    return ShowCodeNode(nodelist)
+
+
+class ShowCodeNode(template.Node):
+    """Template node for the show_code tag.
+
+    Processes template content to display both executable code and its rendered output.
+    Handles indentation normalization, HTML escaping, Cotton template compilation,
+    and HTML rendering.
+
+    Attributes:
+        nodelist (NodeList): Template nodes between show_code block start and end tags
+    """
+
+    def __init__(self, nodelist):
+        """Initialize the node with template content.
+
+        Args:
+            nodelist: Template node list from parser between block tags
+        """
+        self.nodelist = nodelist
+
+    def render(self, context):
+        """Render the code block with normalized formatting and display.
+
+        Processes the captured template content through the following steps:
+        1. Render the template content to raw text
+        2. Normalize indentation (remove common leading whitespace)
+        3. Remove leading/trailing blank lines
+        4. Escape HTML special characters for safe display
+        5. Compile Cotton template syntax
+        6. Execute the compiled template
+        7. Display both formatted code and rendered output side-by-side
+
+        Args:
+            context: Django template context for rendering
+
+        Returns:
+            str: HTML markup displaying the code and its rendered result
+        """
+        raw = self.nodelist.render(context)
+
+        # Beautifulsoup does annoying things to the Cotton syntax, so we'll skip that step and clean ourselves
+        # soup = BeautifulSoup(raw, "html.parser")
+        # cleaned = soup.prettify(formatter="html5")
+
+        cleaned = textwrap.dedent(raw).strip("\n")
+
+        # 3. Escape Cotton syntax for HTML display in code tag
+        code = escape(cleaned)
+
+        # 4. Compile Cotton syntax
+        compiled = compiler.process(cleaned)
+
+        # 5. Render the compiled template
+        t = template.Template(compiled)
+        rendered_raw = t.render(context)
+
+        # 6. Clean the rendered HTML using BeautifulSoup for proper formatting
+        if not HAS_BEAUTIFULSOUP:
+            raise ImportError(
+                "BeautifulSoup4 is required for the show_code template tag. "
+                "Install it with: pip install beautifulsoup4"
+            )
+
+        soup = BeautifulSoup(rendered_raw, "html.parser")
+        rendered_cleaned = soup.prettify()
+
+        # rendered_cleaned = textwrap.dedent(rendered_raw).strip("\n")
+        # rendered_cleaned = re.sub(r'\n\s*\n(\s*\n)+', '\n\n', rendered_cleaned)
+
+        # Remove excessive blank lines (more than one consecutive blank line)
+        # rendered_cleaned = rendered_cleaned.strip()
+
+        # 7. Mark safe for actual rendering on page
+        rendered = mark_safe(rendered_cleaned)
+
+        # 8. Escape cleaned HTML for display in code tag
+        html = escape(rendered_cleaned)
+
+        return render_to_string(
+            "cotton_bs5/document_component.html",
+            {"code": code, "rendered": rendered, "html": html},
+        )

{django_cotton_bs5-0.5.0.dist-info → django_cotton_bs5-0.6.0.dist-info}/METADATA

@@ -1,20 +1,21 @@
 Metadata-Version: 2.1
 Name: django-cotton-bs5
-Version: 0.5.0
+Version: 0.6.0
 Summary: Bootstrap 5 components for use with Django Cotton.
 License: MIT
 Author: Sam
 Author-email: samuel.scott.jennings@gmail.com
-Requires-Python: >=3.10,<4.0
+Requires-Python: >=3.12,<4.00
+Classifier: Framework :: Django
+Classifier: Framework :: Pytest
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Provides-Extra: django-compressor
+Requires-Dist: beautifulsoup4 (>=4.14.3,<5.0.0)
 Requires-Dist: django-compressor (>=4.5.1,<5.0.0) ; extra == "django-compressor"
-Requires-Dist: django-cotton (>=2.3.1)
-Requires-Dist: django-libsass (>=0.9,<0.10)
+Requires-Dist: django-cotton (>=2.6.1,<3.0.0)
+Requires-Dist: django-libsass (>=0.9,<0.10) ; extra == "django-compressor"
 Description-Content-Type: text/markdown
 
 # Django Cotton BS5
@@ -62,6 +63,90 @@ The following Bootstrap 5 components are currently available as Django Cotton co
 
 More components are planned. Please request additional Bootstrap 5 components or features via the [issue tracker](https://github.com/SamuelJennings/cotton-bs5/issues).
 
+## Testing Components
+
+This package provides four pytest fixtures for testing Django Cotton components:
+
+### `cotton_render` Fixture
+
+Renders a component and returns the raw HTML as a string.
+
+```python
+def test_alert_component(cotton_render):
+    html = cotton_render(
+        'cotton_bs5.alert',
+        message="Hello World",
+        variant="success"
+    )
+    assert 'alert-success' in html
+    assert 'Hello World' in html
+```
+
+### `cotton_render_soup` Fixture
+
+Renders a component and returns a BeautifulSoup parsed HTML object for easier DOM traversal and assertions.
+
+```python
+def test_alert_component(cotton_render_soup):
+    soup = cotton_render_soup(
+        'cotton_bs5.alert',
+        message="Hello World",
+        variant="success"
+    )
+    alert_div = soup.find('div', class_='alert')
+    assert 'alert-success' in alert_div['class']
+    assert alert_div.get_text() == 'Hello World'
+```
+
+### `cotton_render_string` Fixture
+
+Compiles and renders template strings containing Cotton component syntax. Useful for testing multi-component markup and complex layouts inline without creating separate template files.
+
+```python
+def test_button_inline(cotton_render_string):
+    html = cotton_render_string("<c-button variant='primary'>Click me</c-button>")
+    assert 'btn-primary' in html
+
+def test_nested_components(cotton_render_string):
+    html = cotton_render_string(
+        "<c-ul><c-li text='first' /><c-li text='second' /></c-ul>"
+    )
+    assert 'first' in html
+    assert 'second' in html
+```
+
+### `cotton_render_string_soup` Fixture
+
+Combines `cotton_render_string` with BeautifulSoup parsing for easier DOM traversal and assertions on multi-component structures.
+
+```python
+def test_nested_list(cotton_render_string_soup):
+    soup = cotton_render_string_soup(
+        "<c-ul><c-li text='first' /><c-li text='second' /></c-ul>"
+    )
+    items = soup.find_all('li')
+    assert len(items) == 2
+    assert items[0].get_text() == 'first'
+
+def test_complex_layout(cotton_render_string_soup):
+    template = '''
+        <c-card>
+            <c-card.title>{{ title }}</c-card.title>
+            <c-card.body>
+                <c-button variant='primary'>{{ action }}</c-button>
+            </c-card.body>
+        </c-card>
+    '''
+    soup = cotton_render_string_soup(template, context={
+        'title': 'My Card',
+        'action': 'Click Here'
+    })
+    assert soup.find('h5').get_text() == 'My Card'
+    assert 'btn-primary' in soup.find('button')['class']
+```
+
+All fixtures automatically inject a request object, so you don't need to create one manually.
+
 ## Contributing
 
 This library follows django-cotton conventions and Bootstrap 5 standards. When adding new components:

{django_cotton_bs5-0.5.0.dist-info → django_cotton_bs5-0.6.0.dist-info}/RECORD

@@ -1,5 +1,6 @@
 cotton_bs5/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cotton_bs5/apps.py,sha256=IwPyZAgGWygK8LpsA2_Yz4lUjyYhzEYaBL_-KVR9KK8,94
+cotton_bs5/fixtures.py,sha256=XrUKC2p-_HoTHW-YNAoO24aYNd9pAh-hzPFcmeI5-GE,7502
 cotton_bs5/static/_variables.scss,sha256=B5jORYuNv-a6xxsnnqj5u_JgS_qjEWySneZCInancy4,1906
 cotton_bs5/static/bs5/_accordion.scss,sha256=-puTNym6ujT9oyWBBCKJx4xrE4Vm7Dknay6zlbgqyOw,5077
 cotton_bs5/static/bs5/_alert.scss,sha256=3Cl_x0tBd-YWCTzPJnjhzzzxWBUTdj8yq5WV80VLD94,2073
@@ -96,14 +97,14 @@ cotton_bs5/static/bs5/vendor/_rfs.scss,sha256=JsQPrGMGFQNZ-LCv25Rv_rWHI_fX1koYba
 cotton_bs5/static/stylesheet.scss,sha256=8czc7O81g7KUDSG4hVfcz_5YdYDOhEurn1uqgeQ-sLI,2529
 cotton_bs5/templates/cotton/accordion/body.html,sha256=Y-lw1saKRb31k8s1kLyCarKNWMcVp7eCjHsV8qtRGW4,219
 cotton_bs5/templates/cotton/accordion/header.html,sha256=B38j90UQ_Q5PXKRduFfCToOV08gFPVTK8EbF4DUNyKw,442
-cotton_bs5/templates/cotton/accordion/index.html,sha256=JDmnwJLGYcbDOqUSVP9EvONiQVbjwnJJ69btdxUkf9c,163
-cotton_bs5/templates/cotton/accordion/item.html,sha256=lsaDkKDGA5bfgb0ER7Z9nsS5M43dKyg-ip-01z8SE7E,276
+cotton_bs5/templates/cotton/accordion/index.html,sha256=a-QTsbHCiHeEXA_HzN5z7oYRMejlNVCGc7zwhuHqTTI,178
+cotton_bs5/templates/cotton/accordion/item.html,sha256=IbRIfpcLTTimI5tPAhXjkM0jlLh_B5ICYqLjvSNG6OE,480
 cotton_bs5/templates/cotton/alert.html,sha256=PfRSBUW4cFvx6lmTXzpP8R0JDGvPX7k1i5jMjD1YiuY,386
 cotton_bs5/templates/cotton/badge.html,sha256=7B84yZIZWhtjdNsoeM6-FMiZEsTyTtauzIzMSws3fXU,303
-cotton_bs5/templates/cotton/breadcrumbs/index.html,sha256=Z4UHmU84mu121otLHUy7GBasmgvryG_ioBrEB9E-lMw,376
-cotton_bs5/templates/cotton/breadcrumbs/item.html,sha256=h0_RmjgC35XQ-3cJ3MgPcVCRwUN6ors2UzJX--JwjxE,397
+cotton_bs5/templates/cotton/breadcrumbs/index.html,sha256=P4Q1TaGXoXOCoK-vtWmZqPAp31UTSmN6D50gN1IJFLs,370
+cotton_bs5/templates/cotton/breadcrumbs/item.html,sha256=aeIl7FUOyoEEcs9oNNtI3eDf7aFmr8HgAk7TLCj1EOQ,436
 cotton_bs5/templates/cotton/button/dismiss.html,sha256=Q1pBNnh8mFACc73XmQzLD9TgmPToZ374sW26SNALnCI,253
-cotton_bs5/templates/cotton/button/index.html,sha256=bW8yrGFxJk-lkbla9RgM3vaUyxyDnwWVoMiZncBPQv4,440
+cotton_bs5/templates/cotton/button/index.html,sha256=ASta4ny_ZQWCctdmW3Qh4B0aJ4Sgwx-PG9AJFGqRfQ4,360
 cotton_bs5/templates/cotton/button_group.html,sha256=HuS7PDniLkVCXovonzRqFVQrGqYfezyQfq0ihTVbwM0,429
 cotton_bs5/templates/cotton/card/body.html,sha256=V7_erMPFbYfCWeMeI9BCtiqrKpr4Qr2LGd4uxrQhkA4,162
 cotton_bs5/templates/cotton/card/footer.html,sha256=5wop-wWc-Pj5HU8cZLNY4L7t-cEXskyz6WiECAKvOs8,87
@@ -116,21 +117,24 @@ cotton_bs5/templates/cotton/carousel/caption.html,sha256=BD4Vgdrho5T0mvvvKmtbQYI
 cotton_bs5/templates/cotton/carousel/index.html,sha256=MhulHDibT3e9B4KFW-tCpLYz0ORCfjG8kfe9zBmSXYA,452
 cotton_bs5/templates/cotton/carousel/item.html,sha256=Q_kpQa7_uyi0_0BUxTH5_tuqzF-4PHs8WnH9WpHdfkQ,142
 cotton_bs5/templates/cotton/collapse.html,sha256=N9lcZgBa9OxcgCHgNolmU17CM5uTbxkx6kNcY-BGvlc,344
+cotton_bs5/templates/cotton/cotton_bs5/document.html,sha256=nc71O-Ex8F3qlIhhFjdqObkaLmK7CArL9IIi-8UiDOI,165
 cotton_bs5/templates/cotton/dropdown/divider.html,sha256=EuKZtrn23FJSIXy1VNb96Ft1aZTNzAzEoSrehZsiGtI,32
 cotton_bs5/templates/cotton/dropdown/header.html,sha256=vi27RD2jKOvJCdLqceQtB1PaJLDkrRoikpkue0DGA-A,83
 cotton_bs5/templates/cotton/dropdown/index.html,sha256=tana4NotkE2h3Q0tRNS94TMc8NcgDlLMO5EdgyyH9FI,290
-cotton_bs5/templates/cotton/dropdown/item.html,sha256=8hVy3gl_ZPkO4r07NjQKQ9T0NdKJjIDpw7wLAgjCysM,554
+cotton_bs5/templates/cotton/dropdown/item.html,sha256=a3_iPn7MixG8N47743RLofMKzvacBfCwsYxUaAuMhuo,492
 cotton_bs5/templates/cotton/dropdown/toggle.html,sha256=cZDrs80yuwyMk3bCV2hGn5XycyC1WT6k7NeMYxxi0Mk,447
-cotton_bs5/templates/cotton/grid/col.html,sha256=nIcLePAN8BJs7rlz5UJdCknIxEq2uOFpZbKSlPlI47s,255
-cotton_bs5/templates/cotton/grid/index.html,sha256=8D9xxCJ9Vu4IeX2AzYdeYYpIZSUU2WxImOJxc9Anxu0,274
-cotton_bs5/templates/cotton/list_group/index.html,sha256=OBqm8NHIjMMWxx_PNFMH3c2HLJgrTnQritCmpfVFacw,420
-cotton_bs5/templates/cotton/list_group/item.html,sha256=jBPbBUlzvDKuz_ltD4xLNVO_DbFB4J2S5fNDmi1t63U,526
+cotton_bs5/templates/cotton/grid/col.html,sha256=DvrOJ71hts9IktSiy8R_4HHb4vFlbAtZnfnaX7RJEJ0,272
+cotton_bs5/templates/cotton/grid/index.html,sha256=KbcZR4i63BSdpXzSfv4B7jbKF8lbcfnAcGJx24Cj8io,455
+cotton_bs5/templates/cotton/hstack.html,sha256=1NxBx5ccVoPEHWc1PDsraQYL0yd9z6zNF0MX_xtugBU,104
+cotton_bs5/templates/cotton/list_group/index.html,sha256=vQ8XCi9gKtPfBBlrDTgcEXEOwyt0jPZydaQ62c4gveg,422
+cotton_bs5/templates/cotton/list_group/item.html,sha256=uZXDWpKBynWeC5bD4HDygETj0rXlU_jB7YUgXn44r4M,485
 cotton_bs5/templates/cotton/modal/body.html,sha256=ANNl7-edJij4ECMcjnX5Ms464yXIhgC8jEKIb1TbTYE,41
 cotton_bs5/templates/cotton/modal/footer.html,sha256=Oxg9w02dcmPAmgGnqk1AfVsSk7LRqZigsClNAktP3_U,85
 cotton_bs5/templates/cotton/modal/header.html,sha256=lMEqRfpR8soBRhRAG-6i4gVBCuftTnoe9GmJObwPStU,246
 cotton_bs5/templates/cotton/modal/index.html,sha256=c_GZQV83gjJjv969GpKyxqXDoNKRVeQARdCQcA2qstw,652
 cotton_bs5/templates/cotton/modal/title.html,sha256=lVPJDKK0Zk2U5VxL_jisnzPrCwgcVtcuTbIPDNQv690,138
 cotton_bs5/templates/cotton/nav/index.html,sha256=9OczfhoKQGdQr6d52dODR6WxWymFhdbEXNIB4xXI6fw,262
+cotton_bs5/templates/cotton/nav/item.html,sha256=iu34dEiR3ID-27PjVPCpEhmBiAumNQYAHzSInrtPb9Q,125
 cotton_bs5/templates/cotton/nav/link.html,sha256=TyTdMfv6I1hhVhTNv84hAqMdebj2Glx7sjp28cPyn_o,262
 cotton_bs5/templates/cotton/navbar/index.html,sha256=Xtk6dg_lg05kAyajRIxZIBSgWQhPDWCC84LDkytbG78,872
 cotton_bs5/templates/cotton/navbar/link.html,sha256=fPtVWCZCFbMWvJW04I7N2A9L8Mk_-Yqfxw8Tv4_nu3s,364
@@ -156,7 +160,12 @@ cotton_bs5/templates/cotton/toast/activate.html,sha256=D-qh8lfEWoJWMKdUG0PT4jdNA
 cotton_bs5/templates/cotton/toast/body.html,sha256=cneCr26QtF48gYR7kW5wa_QO0Qv5nGJDlXR6PjVueMU,71
 cotton_bs5/templates/cotton/toast/header.html,sha256=izlXp-D5cKEIeIj297pma9XYgGNo6lkrgvHw1QscOR8,115
 cotton_bs5/templates/cotton/toast/index.html,sha256=av7EWcLGcB90KUBCru6qwtl78PkM228n5OxuJewc4OI,304
-django_cotton_bs5-0.5.0.dist-info/LICENSE,sha256=jAcYHTznehUzk6dbbjLdSq9Xo2S_OmscgUKA94hUoMo,1072
-django_cotton_bs5-0.5.0.dist-info/METADATA,sha256=mG0iOvYWEuJHeFQWKpmHhT9dNO1RWtBJ838DXu0qAcU,3223
-django_cotton_bs5-0.5.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-django_cotton_bs5-0.5.0.dist-info/RECORD,,
+cotton_bs5/templates/cotton/vstack.html,sha256=okGz8WD93e0PUR-FFI9p20r_PP5FQ9Ql8obVLMLtm64,104
+cotton_bs5/templates/cotton_bs5/document_component.html,sha256=SLyce5I7CpBfMhuiEnkLU-O9OYbTQbi5fEjQ-_tvYzU,4826
+cotton_bs5/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cotton_bs5/templatetags/cotton_bs5.py,sha256=4UreJ8ZW2_L2Xfd3EKLUKlP7tHh53TH6VZ6TwDmCYNA,9128
+django_cotton_bs5-0.6.0.dist-info/LICENSE,sha256=jAcYHTznehUzk6dbbjLdSq9Xo2S_OmscgUKA94hUoMo,1072
+django_cotton_bs5-0.6.0.dist-info/METADATA,sha256=FK2Ob4-rLyvSM6Ss-wdc7DYgLYRxzbPpJitnFZez2QU,5853
+django_cotton_bs5-0.6.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+django_cotton_bs5-0.6.0.dist-info/entry_points.txt,sha256=5FA9XkZ8EBll5jE94vwF1gp7xD1F9HTdhdKutznbTSU,43
+django_cotton_bs5-0.6.0.dist-info/RECORD,,

django_cotton_bs5-0.6.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+cotton_bs5=cotton_bs5.fixtures
+