Add sequence to data-bird-id attr and add component name data attr (#135)

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,9 +18,19 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- Added `data-bird-<component_name>` data attribute to the `attrs` template context variable for components when `ENABLE_BIRD_ATTRS` is enabled.
+
 ### Changed
 
 - **Internal**: Refactored component rendering by introducing a new `BoundComponent` class and moving some of the rendering logic from `Component` and `BirdNode` to this new class.
+- Renamed `ENABLE_BIRD_ID_ATTR` setting to `ENABLE_BIRD_ATTRS` to reflect its expanded functionality.
+- Moved setting the `data-bird-id` data attribute in the `attrs` template context variable to `BoundComponent` and added a sequence number to better uniquely identify multiple instances of the same component.
+
+### Deprecated
+
+- The `ENABLE_BIRD_ID_ATTR` setting is deprecated and will be removed in the next minor version (v0.13.0). Use `ENABLE_BIRD_ATTRS` instead.
 
 ### Removed
 

docs/configuration.md

@@ -12,7 +12,7 @@ from pathlib import Path
 DJANGO_BIRD = {
     "COMPONENT_DIRS": list[Path | str] = [],
     "ENABLE_AUTO_CONFIG": bool = True,
-    "ENABLE_BIRD_ID_ATTR": bool = True,
+    "ENABLE_BIRD_ATTRS": bool = True,
 }
 ```
 
@@ -112,8 +112,12 @@ TEMPLATES = [
 
 This configuration ensures that django-bird's templatetags are available globally and that its loader is used to compile bird component templates before the standard Django loaders.
 
-## `ENABLE_BIRD_ID_ATTR`
+## `ENABLE_BIRD_ATTRS`
 
-Controls whether components automatically receive a `data-bird-id` attribute containing a unique identifier. Defaults to `True`.
+Controls whether components automatically receive data attributes related to django-bird in its `attrs` template context variable. Defaults to `True`.
 
 See [Component ID Attribute](params.md#component-id-attribute) for more details on how this works.
+
+```{important}
+This setting was previously named `ENABLE_BIRD_ID_ATTRS`. It was renamed to reflect the expansion of the data attributes for a component, from just `data-bird-id` to include `data-bird-<component_name>`, as well as to allow for future expansion. As of v0.12.0, the `ENABLE_BIRD_ID_ATTRS` setting is deprecated and will be removed in v0.13.0.
+```

docs/params.md

@@ -87,7 +87,12 @@ This will render as:
 
 ### Component ID Attribute
 
-When the [`ENABLE_BIRD_ID_ATTR` setting](configuration.md#enable_bird_id_attr) is enabled (the default), django-bird automatically adds a `data-bird-id` attribute to your components, available via the `{{ attrs }}` context variable. This attribute contains a unique identifier that helps identify specific component instances in the DOM.
+When the [`ENABLE_BIRD_ATTRS` setting](configuration.md#enable_bird_attrs) is enabled (the default), django-bird automatically adds data attributes to your components, available via the `{{ attrs }}` context variable.
+
+The following attributes are included:
+
+- `data-bird-<component_name>`: This attribute will contain the name of the component. This is not unique across component instances in the DOM.
+- `data-bird-id`: This attribute contains a unique identifier that helps identify specific component instances in the DOM.
 
 For example, for a component template like this:
 
@@ -108,22 +113,50 @@ And used like this:
 It will be rendered as:
 
 ```html
-<button data-bird-id="abc1234" class="btn">
+<button class="btn" data-bird-button data-bird-id="abc1234-1">
     Click me
 </button>
 ```
 
-The ID is automatically generated from a hash of the component's name and template content.
+The ID is automatically generated from a hash of the component's name and template content. It also contains a sequence counter that will increment for any uses of a component across a single template.
+
+The above example button component template, used like this:
+
+```htmldjango
+{% bird button class="btn" %}
+    Click me once
+{% endbird %}
+{% bird button class="btn" %}
+    Click me twice
+{% endbird %}
+{% bird button class="btn" %}
+    Click me three times a lady
+{% endbird %}
+```
+
+Will be rendered like this, with the unique sequence numbers added to the component's hashed ID:
+
+```html
+<button class="btn" data-bird-button data-bird-id="abc1234-1">
+    Click me once
+</button>
+<button class="btn" data-bird-button data-bird-id="abc1234-2">
+    Click me twice
+</button>
+<button class="btn" data-bird-button data-bird-id="abc1234-3">
+    Click me three times a lady
+</button>
+```
 
-You can disable this feature globally by setting `ENABLE_BIRD_ID_ATTR = False` in your Django settings:
+You can disable this feature globally by setting `ENABLE_BIRD_ATTRS = False` in your Django settings:
 
 ```python
 DJANGO_BIRD = {
-    "ENABLE_BIRD_ID_ATTR": False,
+    "ENABLE_BIRD_ATTRS": False,
 }
 ```
 
-When disabled, no `data-bird-id` attribute will be added to your components.
+When disabled, no data attributes will be added to your components' `attrs` template context variable.
 
 ## Properties
 

src/django_bird/components.py

@@ -4,6 +4,7 @@
 from dataclasses import field
 from hashlib import md5
 from pathlib import Path
+from threading import Lock
 
 from cachetools import LRUCache
 from django.apps import apps
@@ -40,6 +41,10 @@ def get_bound_component(self, attrs: list[Param]):
         params = Params.with_attrs(attrs)
         return BoundComponent(component=self, params=params)
 
+    @property
+    def data_attribute_name(self):
+        return self.name.replace(".", "-")
+
     @property
     def id(self):
         normalized_source = "".join(self.source.split())
@@ -76,16 +81,45 @@ def from_name(cls, name: str):
         return cls(name=name, template=template, assets=frozenset(assets))
 
 
+class SequenceGenerator:
+    _instance: SequenceGenerator | None = None
+    _lock: Lock = Lock()
+    _counters: dict[str, int]
+
+    def __init__(self) -> None:
+        if not hasattr(self, "_counters"):
+            self._counters = {}
+
+    def __new__(cls) -> SequenceGenerator:
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def next(self, component: Component) -> int:
+        with self._lock:
+            current = self._counters.get(component.id, 0) + 1
+            self._counters[component.id] = current
+        return current
+
+
 @dataclass
 class BoundComponent:
     component: Component
     params: Params
+    _sequence: SequenceGenerator = field(default_factory=SequenceGenerator)
 
     def render(self, context: Context):
-        if app_settings.ENABLE_BIRD_ID_ATTR:
-            self.params.attrs.append(
-                Param("data_bird_id", Value(self.component.id, True))
-            )
+        if app_settings.ENABLE_BIRD_ATTRS:
+            data_attrs = [
+                Param(
+                    f"data-bird-{self.component.data_attribute_name}",
+                    Value(True, False),
+                ),
+                Param("data-bird-id", Value(f"{self.component.id}-{self.id}", True)),
+            ]
+            self.params.attrs.extend(data_attrs)
 
         props = self.params.render_props(self.component.nodelist, context)
         attrs = self.params.render_attrs(context)
@@ -98,6 +132,10 @@ def render(self, context: Context):
         ):
             return self.component.template.template.render(context)
 
+    @property
+    def id(self):
+        return str(self._sequence.next(self.component))
+
 
 class ComponentRegistry:
     def __init__(self, maxsize: int = 100):

src/django_bird/conf.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from contextlib import suppress
 from dataclasses import dataclass
 from dataclasses import field
@@ -18,10 +19,17 @@
 class AppSettings:
     COMPONENT_DIRS: list[Path | str] = field(default_factory=list)
     ENABLE_AUTO_CONFIG: bool = True
-    ENABLE_BIRD_ID_ATTR: bool = True
+    ENABLE_BIRD_ATTRS: bool = True
+    ENABLE_BIRD_ID_ATTR: bool | None = None
     _template_configurator: TemplateConfigurator = field(init=False)
 
     def __post_init__(self):
+        if self.ENABLE_BIRD_ID_ATTR is not None:
+            warnings.warn(
+                "ENABLE_BIRD_ID_ATTR is deprecated and will be removed in v0.13.0. Use ENABLE_BIRD_ATTRS instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self._template_configurator = TemplateConfigurator(self)
 
     @override

tests/conftest.py

@@ -109,15 +109,9 @@ def _override_app_settings(**kwargs):
 
 @pytest.fixture(autouse=True)
 def data_bird_attr_app_setting(override_app_settings, request):
-    from django_bird.conf import app_settings
+    enable = "default_app_settings" in request.keywords
 
-    enable = (
-        app_settings.ENABLE_BIRD_ID_ATTR
-        if "default_app_settings" in request.keywords
-        else False
-    )
-
-    with override_app_settings(ENABLE_BIRD_ID_ATTR=enable):
+    with override_app_settings(ENABLE_BIRD_ATTRS=enable, ENABLE_BIRD_ID_ATTR=enable):
         yield
 
 

tests/templatetags/test_bird.py

@@ -634,8 +634,22 @@ def test_error_handling(self, test_case, templates_dir, normalize_whitespace):
 
         assert normalize_whitespace(rendered) == test_case.expected
 
-    def test_data_bird_id(
-        self, override_app_settings, templates_dir, normalize_whitespace
+    @pytest.mark.parametrize(
+        "attr_app_setting,expected",
+        [
+            ({"ENABLE_BIRD_ATTRS": True, "ENABLE_BIRD_ID_ATTR": True}, True),
+            ({"ENABLE_BIRD_ATTRS": True, "ENABLE_BIRD_ID_ATTR": False}, True),
+            ({"ENABLE_BIRD_ATTRS": False, "ENABLE_BIRD_ID_ATTR": True}, False),
+            ({"ENABLE_BIRD_ATTRS": False, "ENABLE_BIRD_ID_ATTR": False}, False),
+        ],
+    )
+    def test_data_bird_attributes(
+        self,
+        attr_app_setting,
+        expected,
+        override_app_settings,
+        templates_dir,
+        normalize_whitespace,
     ):
         button = TestComponent(
             name="button",
@@ -648,12 +662,13 @@ def test_data_bird_id(
 
         template = Template("{% bird 'button' %}Click me{% endbird %}")
 
-        with override_app_settings(ENABLE_BIRD_ID_ATTR=True):
+        with override_app_settings(**attr_app_setting):
             rendered = template.render(Context({}))
 
         comp = Component.from_name(button.name)
 
-        assert comp.id in rendered
+        assert (f'data-bird-id="{comp.id}' in rendered) is expected
+        assert (f"data-bird-{comp.data_attribute_name}" in rendered) is expected
 
 
 class TestProperties:

tests/test_components.py

@@ -9,7 +9,8 @@
 from pathlib import Path
 
 import pytest
-from django.template.backends.django import Template
+from django.template import Template
+from django.template.backends.django import Template as DjangoTemplate
 from django.template.context import Context
 from django.template.exceptions import TemplateDoesNotExist
 from django.test import override_settings
@@ -33,7 +34,7 @@ def test_from_name_basic(self, templates_dir):
         comp = Component.from_name("button")
 
         assert comp.name == "button"
-        assert isinstance(comp.template, Template)
+        assert isinstance(comp.template, DjangoTemplate)
 
         bound = comp.get_bound_component([])
 
@@ -106,7 +107,7 @@ def test_from_name_custom_component_dir(self, templates_dir, override_app_settin
             comp = Component.from_name("button")
 
         assert comp.name == "button"
-        assert isinstance(comp.template, Template)
+        assert isinstance(comp.template, DjangoTemplate)
 
         bound = comp.get_bound_component([])
 
@@ -169,6 +170,80 @@ def test_id_formatting(self, templates_dir):
         assert len(comp.id) == 7
         assert all(c in "0123456789abcdef" for c in comp.id)
 
+    def test_data_attribute_name_basic(self, templates_dir):
+        button = TestComponent(
+            name="button", content="<button>Click me</button>"
+        ).create(templates_dir)
+
+        comp = Component.from_name(button.name)
+
+        assert comp.data_attribute_name == "button"
+
+    def test_data_attribute_name_nested(self, templates_dir):
+        button = TestComponent(
+            name="button",
+            content="<button>Nested</button>",
+            sub_dir="nested",
+        ).create(templates_dir)
+
+        comp = Component.from_name(f"{button.sub_dir}.{button.name}")
+
+        assert comp.data_attribute_name == "nested-button"
+
+
+class TestBoundComponent:
+    @pytest.mark.parametrize(
+        "attr_app_setting,expected",
+        [
+            ({"ENABLE_BIRD_ATTRS": True, "ENABLE_BIRD_ID_ATTR": True}, True),
+            ({"ENABLE_BIRD_ATTRS": True, "ENABLE_BIRD_ID_ATTR": False}, True),
+            ({"ENABLE_BIRD_ATTRS": False, "ENABLE_BIRD_ID_ATTR": True}, False),
+            ({"ENABLE_BIRD_ATTRS": False, "ENABLE_BIRD_ID_ATTR": False}, False),
+        ],
+    )
+    def test_id_sequence(
+        self,
+        attr_app_setting,
+        expected,
+        override_app_settings,
+        templates_dir,
+        normalize_whitespace,
+    ):
+        button = TestComponent(
+            name="button", content="<button {{ attrs }}>{{ slot }}</button>"
+        ).create(templates_dir)
+        comp = Component.from_name(button.name)
+
+        template = Template("""
+            {% bird button class="btn" %}
+                Click me once
+            {% endbird %}
+            {% bird button class="btn" %}
+                Click me twice
+            {% endbird %}
+            {% bird button class="btn" %}
+                Click me three times a lady
+            {% endbird %}
+        """)
+
+        with override_app_settings(**attr_app_setting):
+            rendered = template.render(Context({}))
+
+        assert (
+            normalize_whitespace(rendered)
+            == normalize_whitespace(f"""
+                <button class="btn" data-bird-button data-bird-id="{comp.id}-1">
+                    Click me once
+                </button>
+                <button class="btn" data-bird-button data-bird-id="{comp.id}-2">
+                    Click me twice
+                </button>
+                <button class="btn" data-bird-button data-bird-id="{comp.id}-3">
+                    Click me three times a lady
+                </button>
+            """)
+        ) is expected
+
 
 class TestComponentRegistryProject:
     def test_discover_components(self, templates_dir):