add component id as data attribute to component attrs (#124)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,6 +18,10 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- Added `ENABLE_BIRD_ID_ATTR` setting (default: `True`) to control whether components receive an automatic `data-bird-id` attribute. This is to help with component identification in the DOM and for a future planned feature around JS/CSS asset scoping.
+
 ## [0.10.3]
 
 ### Fixed

docs/configuration.md

@@ -12,6 +12,7 @@ from pathlib import Path
 DJANGO_BIRD = {
     "COMPONENT_DIRS": list[Path | str] = [],
     "ENABLE_AUTO_CONFIG": bool = True,
+    "ENABLE_BIRD_ID_ATTR": bool = True,
 }
 ```
 
@@ -110,3 +111,9 @@ 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`
+
+Controls whether components automatically receive a `data-bird-id` attribute containing a unique identifier. Defaults to `True`.
+
+See [Component ID Attribute](params.md#component-id-attribute) for more details on how this works.

docs/params.md

@@ -85,6 +85,46 @@ This will render as:
 </button>
 ```
 
+### 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.
+
+For example, for a component template like this:
+
+```htmldjango
+<button {{ attrs }}>
+    {{ slot }}
+</button>
+```
+
+And used like this:
+
+```htmldjango
+{% bird button class="btn" %}
+    Click me
+{% endbird %}
+```
+
+It will be rendered as:
+
+```html
+<button data-bird-id="abc1234" class="btn">
+    Click me
+</button>
+```
+
+The ID is automatically generated from a hash of the component's name and template content.
+
+You can disable this feature globally by setting `ENABLE_BIRD_ID_ATTR = False` in your Django settings:
+
+```python
+DJANGO_BIRD = {
+    "ENABLE_BIRD_ID_ATTR": False,
+}
+```
+
+When disabled, no `data-bird-id` attribute will be added to your components.
+
 ## Properties
 
 Properties (i.e. `props`) allow you to define parameters that your component expects, with optional default values. Unlike attributes which are provided as a flattened string via `{{ attrs }}`, props are processed by the component and made available as individual values (e.g. `{{ props.variant }}`) that can be used to control rendering logic.

pyproject.toml

@@ -36,9 +36,7 @@ types = [
 ]
 
 [project]
-authors = [
-  {name = "Josh Thomas", email = "[email protected]"}
-]
+authors = [{name = "Josh Thomas", email = "[email protected]"}]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Framework :: Django",
@@ -56,10 +54,7 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: Implementation :: CPython"
 ]
-dependencies = [
-  "cachetools>=5.5.0",
-  "django>=4.2"
-]
+dependencies = ["cachetools>=5.5.0", "django>=4.2"]
 description = "High-flying components for perfectionists with deadlines"
 dynamic = ["version"]
 keywords = []
@@ -74,9 +69,7 @@ Issues = "https://github.com/joshuadavidthomas/django-bird/issues"
 Source = "https://github.com/joshuadavidthomas/django-bird"
 
 [tool.basedpyright]
-exclude = [
-  "**/__pycache__"
-]
+exclude = ["**/__pycache__"]
 include = ["src"]
 
 [[tool.basedpyright.executionEnvironments]]
@@ -102,15 +95,9 @@ tag = false
 version_pattern = "MAJOR.MINOR.PATCH[PYTAGNUM]"
 
 [tool.bumpver.file_patterns]
-".copier/package.yml" = [
-  'current_version: {version}'
-]
-"src/django_bird/__init__.py" = [
-  '__version__ = "{version}"'
-]
-"tests/test_version.py" = [
-  'assert __version__ == "{version}"'
-]
+".copier/package.yml" = ['current_version: {version}']
+"src/django_bird/__init__.py" = ['__version__ = "{version}"']
+"tests/test_version.py" = ['assert __version__ == "{version}"']
 
 [tool.coverage.paths]
 source = ["src"]
@@ -127,11 +114,7 @@ exclude_lines = [
 fail_under = 98
 
 [tool.coverage.run]
-omit = [
-  "src/django_bird/migrations/*",
-  "src/django_bird/_typing.py",
-  "tests/*"
-]
+omit = ["src/django_bird/migrations/*", "src/django_bird/_typing.py", "tests/*"]
 source = ["src/django_bird"]
 
 [tool.django-stubs]
@@ -147,10 +130,7 @@ indent = 2
 profile = "django"
 
 [tool.hatch.build]
-exclude = [
-  ".*",
-  "Justfile"
-]
+exclude = [".*", "Justfile"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/django_bird"]
@@ -160,37 +140,26 @@ path = "src/django_bird/__init__.py"
 
 [tool.mypy]
 check_untyped_defs = true
-exclude = [
-  "docs",
-  "tests",
-  "migrations",
-  "venv",
-  ".venv"
-]
+exclude = ["docs", "tests", "migrations", "venv", ".venv"]
 mypy_path = "src/"
 no_implicit_optional = true
-plugins = [
-  "mypy_django_plugin.main"
-]
+plugins = ["mypy_django_plugin.main"]
 warn_redundant_casts = true
 warn_unused_configs = true
 warn_unused_ignores = true
 
 [[tool.mypy.overrides]]
 ignore_errors = true
 ignore_missing_imports = true
-module = [
-  "*.migrations.*",
-  "docs.*",
-  "tests.*"
-]
+module = ["*.migrations.*", "docs.*", "tests.*"]
 
 [tool.mypy_django_plugin]
 ignore_missing_model_attributes = true
 
 [tool.pytest.ini_options]
 addopts = "--create-db -n auto --dist loadfile --doctest-modules"
 django_find_project = false
+markers = ["default_app_settings"]
 norecursedirs = ".* bin build dist *.egg htmlcov logs node_modules templates venv"
 python_files = "tests.py test_*.py *_tests.py"
 pythonpath = "src"

src/django_bird/conf.py

@@ -18,6 +18,7 @@
 class AppSettings:
     COMPONENT_DIRS: list[Path | str] = field(default_factory=list)
     ENABLE_AUTO_CONFIG: bool = True
+    ENABLE_BIRD_ID_ATTR: bool = True
     _template_configurator: TemplateConfigurator = field(init=False)
 
     def __post_init__(self):

src/django_bird/templatetags/tags/bird.py

@@ -13,8 +13,10 @@
 from django_bird._typing import override
 from django_bird.components import Component
 from django_bird.components import components
+from django_bird.conf import app_settings
 from django_bird.params import Param
 from django_bird.params import Params
+from django_bird.params import Value
 from django_bird.slots import DEFAULT_SLOT
 from django_bird.slots import Slots
 
@@ -27,6 +29,7 @@ def do_bird(parser: Parser, token: Token) -> BirdNode:
     if len(bits) == 1:
         msg = f"{TAG} tag requires at least one argument"
         raise template.TemplateSyntaxError(msg)
+
     name = bits[1]
     attrs = []
     only = False
@@ -87,10 +90,14 @@ def get_component_context_data(
         self, component: Component, context: Context
     ) -> dict[str, Any]:
         context_data: dict[str, Any] = {}
+
         if not self.only:
             flattened = context.flatten()
             context_data = {str(k): v for k, v in flattened.items()}
 
+        if app_settings.ENABLE_BIRD_ID_ATTR:
+            self.attrs.append(Param("data_bird_id", Value(component.id, True)))
+
         params = Params.with_attrs(self.attrs)
         props = params.render_props(component.nodelist, context)
         attrs = params.render_attrs(context)

tests/conftest.py

@@ -107,6 +107,20 @@ def _override_app_settings(**kwargs):
     return _override_app_settings
 
 
+@pytest.fixture(autouse=True)
+def data_bird_attr_app_setting(override_app_settings, request):
+    from django_bird.conf import app_settings
+
+    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):
+        yield
+
+
 @pytest.fixture
 def create_template():
     def _create_template(template_file: Path) -> DjangoTemplate:

tests/templatetags/test_bird.py

@@ -12,6 +12,7 @@
 from django.template.exceptions import TemplateDoesNotExist
 from django.template.exceptions import TemplateSyntaxError
 
+from django_bird.components import Component
 from django_bird.params import Param
 from django_bird.params import Value
 from django_bird.templatetags.tags.bird import END_TAG
@@ -633,6 +634,27 @@ 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
+    ):
+        button = TestComponent(
+            name="button",
+            content="""
+                <button {{ attrs }}>
+                    {{ slot }}
+                </button>
+            """,
+        ).create(templates_dir)
+
+        template = Template("{% bird 'button' %}Click me{% endbird %}")
+
+        with override_app_settings(ENABLE_BIRD_ID_ATTR=True):
+            rendered = template.render(Context({}))
+
+        comp = Component.from_name(button.name)
+
+        assert comp.id in rendered
+
 
 class TestProperties:
     @pytest.mark.parametrize(

tests/test_conf.py

@@ -9,8 +9,11 @@
 from django_bird.conf import app_settings
 
 
+@pytest.mark.default_app_settings
 def test_app_settings():
+    assert app_settings.COMPONENT_DIRS == []
     assert app_settings.ENABLE_AUTO_CONFIG is True
+    assert app_settings.ENABLE_BIRD_ID_ATTR is True
 
 
 @override_settings(