create CSS and JS asset templatetags (#47)

joshuadavidthomas · web-flow · commit 5d73b5f2a85d · 2024-12-03T16:10:17.000-06:00
* create `{% bird:css %}` and `{% bird:js %}` tags for handling component assets

* use loader to register components in template and use for asset tags

* add tests for coverage

* swap regex of extends for scanning nodelist

* update changelog

* update docs
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,10 +20,14 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ### Added
 
-- Component assets (CSS/JS) are now automatically discovered and associated with components
+- New `{% bird:css %}` and `{% bird:js %}` template tags to automatically include component assets
+- Component assets are automatically discovered from matching CSS/JS files next to component templates
 
 ### Changed
 
+- **Internal**: Extended `BirdLoader` to track component usage and their assets during template rendering
+- **Internal**: Assets are now stored as frozensets for immutability
+- **Internal**: Added `ComponentAssetRegistry` to manage component assets during template rendering
 - **Internal**: Refactored `AssetType` to use string values and file extensions
 
 ### Removed
diff --git a/docs/assets.md b/docs/assets.md
@@ -0,0 +1,110 @@
+# CSS and JavaScript Assets
+
+django-bird automatically discovers and manages CSS and JavaScript assets for your components.
+
+## Asset Discovery
+
+Assets are discovered based on file names matching your component template:
+
+```bash
+templates/bird/
+├── button.css
+├── button.html
+└── button.js
+```
+
+The library looks for `.css` and `.js` files with the same name as your component template.
+
+You can also organize components in their own directories. The library will find assets as long as they match the component name and are in the same directory as the template:
+
+```bash
+templates/bird/button/
+├── button.css
+├── button.html
+└── button.js
+```
+
+This organization can be particularly useful when components have multiple related files or when you want to keep component code isolated. See [Template Resolution](naming.md#template-resolution) for more information and [Organization](organization.md) for different ways to structure your components and their assets.
+
+## Using Assets
+
+django-bird provides two templatetags for automatically loading your CSS and Javascript assets into your project's templates:
+
+- `{% bird:css %}`
+- `{% bird:js %}`
+
+To include component assets in your templates, add the templatetags to your base template:
+
+```htmldjango
+<!DOCTYPE html>
+<html>
+    <head>
+        {% bird:css %}  {# Includes CSS from all components used in template #}
+    </head>
+    <body>
+        {% block content %}{% endblock %}
+        {% bird:js %}   {# Includes JavaScript from all components used in template #}
+    </body>
+</html>
+```
+
+The asset tags will automatically:
+
+- Find all components used in the template (including extends and includes)
+- Collect their associated assets
+- Output the appropriate HTML tags
+
+For example, if your template uses components with associated assets:
+
+```htmldjango
+{% bird button %}Click me{% endbird %}
+{% bird alert %}Warning!{% endbird %}
+```
+
+The asset tags will render:
+
+```html
+{# {% bird:css %} renders: #}
+<link rel="stylesheet" href="/static/templates/bird/button.css">
+<link rel="stylesheet" href="/static/templates/bird/alert.css">
+
+{# {% bird:js %} renders: #}
+<script src="/static/templates/bird/button.js"></script>
+<script src="/static/templates/bird/alert.js"></script>
+```
+
+Assets are automatically deduplicated, so each component's assets are included only once even if the component is used multiple times in your templates. Only assets from components actually used in the template (or its parent templates) will be included - unused components' assets won't be loaded, keeping your pages lean.
+
+## Template Inheritance
+
+Assets are collected from all components used in your template hierarchy:
+
+```{code-block} htmldjango
+:caption: base.html
+
+<!DOCTYPE html>
+<html>
+    <head>
+        {% bird:css %}  {# Gets CSS from both nav and content components #}
+    </head>
+    <body>
+        {% bird nav %}{% endbird %}
+        {% block content %}{% endblock %}
+        {% bird:js %}
+    </body>
+</html>
+```
+
+```{code-block} htmldjango
+:caption: page.html
+
+{% extends "base.html" %}
+
+{% block content %}
+    {% bird content %}
+        Page content here
+    {% endbird %}
+{% endblock %}
+```
+
+The `{% bird:css %}` tag will include CSS and the `[% bird:js %}` tag will include JavaScript from both the `nav` and `content` components.
diff --git a/docs/index.md b/docs/index.md
@@ -14,6 +14,7 @@
 Naming <naming>
 Attributes/Properties <params>
 slots
+Assets <assets>
 Organization <organization>
 configuration
 ```
diff --git a/src/django_bird/components.py b/src/django_bird/components.py
@@ -5,7 +5,7 @@
 from typing import Any
 
 from cachetools import LRUCache
-from django.template.backends.django import Template
+from django.template.backends.django import Template as DjangoTemplate
 from django.template.loader import select_template
 
 from django_bird.staticfiles import Asset
@@ -17,8 +17,8 @@
 @dataclass(frozen=True, slots=True)
 class Component:
     name: str
-    template: Template
-    assets: set[Asset] = field(default_factory=set)
+    template: DjangoTemplate
+    assets: frozenset[Asset] = field(default_factory=frozenset)
 
     def render(self, context: dict[str, Any]):
         return self.template.render(context)
diff --git a/src/django_bird/loader.py b/src/django_bird/loader.py
@@ -1,30 +1,70 @@
 from __future__ import annotations
 
 import hashlib
+import re
 
 from django.core.cache import cache
+from django.template.base import Node
 from django.template.base import Origin
+from django.template.base import Template
+from django.template.context import Context
 from django.template.engine import Engine
+from django.template.loader_tags import ExtendsNode
+from django.template.loader_tags import IncludeNode
 from django.template.loaders.filesystem import Loader as FileSystemLoader
 
 from ._typing import override
-from .compiler import BIRD_PATTERN
 from .compiler import Compiler
+from .components import components
+from .staticfiles import ComponentAssetRegistry
+from .templatetags.tags.bird import TAG
+from .templatetags.tags.bird import BirdNode
+
+BIRD_TAG_PATTERN = re.compile(rf"{{%\s*{TAG}\s+([^\s%}}]+)")
 
 
 class BirdLoader(FileSystemLoader):
     def __init__(self, engine: Engine):
         super().__init__(engine)
         self.compiler = Compiler()
+        self.asset_registry = ComponentAssetRegistry()
 
     @override
     def get_contents(self, origin: Origin) -> str:
         contents = super().get_contents(origin)
-        if not BIRD_PATTERN.search(contents):
+
+        if not BIRD_TAG_PATTERN.search(contents):
             return contents
+
+        template = Template(contents, origin=origin, engine=self.engine)
+        context = Context()
+        with context.bind_template(template):
+            self._scan_for_components(template, context)
+
         cache_key = f"bird_component_{hashlib.md5(contents.encode()).hexdigest()}"
-        compiled = cache.get(cache_key)  # pyright: ignore[reportAny]
+        compiled = cache.get(cache_key)
         if compiled is None:
             compiled = self.compiler.compile(contents)
             cache.set(cache_key, compiled, timeout=None)
         return compiled
+
+    def _scan_for_components(self, template: Template | Node, context: Context) -> None:
+        if not hasattr(template, "nodelist"):
+            return
+
+        for node in template.nodelist:
+            if isinstance(node, BirdNode):
+                component = components.get_component(node.name)
+                self.asset_registry.register(component)
+
+            if isinstance(node, ExtendsNode):
+                parent_template = node.get_parent(context)
+                self._scan_for_components(parent_template, context)
+
+            if isinstance(node, IncludeNode):
+                template_name = node.template.token.strip("'\"")
+                included_template = self.engine.get_template(template_name)
+                self._scan_for_components(included_template, context)
+
+            if hasattr(node, "nodelist"):
+                self._scan_for_components(node, context)
diff --git a/src/django_bird/staticfiles.py b/src/django_bird/staticfiles.py
@@ -1,13 +1,18 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from dataclasses import field
 from enum import Enum
 from pathlib import Path
+from typing import TYPE_CHECKING
 
-from django.template.backends.django import Template
+from django.template.backends.django import Template as DjangoTemplate
 
 from ._typing import override
 
+if TYPE_CHECKING:
+    from django_bird.components import Component
+
 
 class AssetType(Enum):
     CSS = "css"
@@ -42,12 +47,26 @@ def from_path(cls, path: Path) -> Asset:
         return cls(path=path, type=asset_type)
 
 
-def get_template_assets(template: Template):
+def get_template_assets(template: DjangoTemplate):
     assets: set[Asset] = set()
     template_path = Path(template.template.origin.name)
     for asset_type in AssetType:
         asset_path = template_path.with_suffix(asset_type.ext)
         if asset_path.exists():
             asset = Asset.from_path(asset_path)
             assets.add(asset)
-    return assets
+    return frozenset(assets)
+
+
+@dataclass
+class ComponentAssetRegistry:
+    components: set[Component] = field(default_factory=set)
+
+    def register(self, component: Component) -> None:
+        self.components.add(component)
+
+    def get_assets(self, asset_type: AssetType) -> set[Asset]:
+        assets: set[Asset] = set()
+        for component in self.components:
+            assets.update(a for a in component.assets if a.type == asset_type)
+        return assets
diff --git a/src/django_bird/templatetags/django_bird.py b/src/django_bird/templatetags/django_bird.py
@@ -2,13 +2,16 @@
 
 from django import template
 
+from .tags import asset
 from .tags import bird
 from .tags import prop
 from .tags import slot
 
 register = template.Library()
 
 
+register.tag(asset.CSS_TAG, asset.do_asset)
+register.tag(asset.JS_TAG, asset.do_asset)
 register.tag(bird.TAG, bird.do_bird)
 register.tag(prop.TAG, prop.do_prop)
 register.tag(slot.TAG, slot.do_slot)
diff --git a/src/django_bird/templatetags/tags/asset.py b/src/django_bird/templatetags/tags/asset.py
@@ -0,0 +1,77 @@
+# pyright: reportAny=false
+from __future__ import annotations
+
+from django import template
+from django.template.base import Parser
+from django.template.base import Token
+from django.template.context import Context
+
+from django_bird._typing import TagBits
+from django_bird._typing import override
+from django_bird.loader import BirdLoader
+from django_bird.staticfiles import Asset
+from django_bird.staticfiles import AssetType
+
+CSS_TAG = "bird:css"
+JS_TAG = "bird:js"
+
+
+def do_asset(parser: Parser, token: Token) -> AssetNode:
+    bits = token.split_contents()
+    asset_type = parse_asset_type(bits)
+    return AssetNode(asset_type)
+
+
+def parse_asset_type(bits: TagBits) -> AssetType:
+    if len(bits) < 1:
+        msg = "bird:assets tag requires at least one argument"
+        raise template.TemplateSyntaxError(msg)
+
+    tag_name = bits[0]
+
+    try:
+        asset_type = tag_name.split(":")[1]
+        match asset_type:
+            case "css":
+                return AssetType.CSS
+            case "js":
+                return AssetType.JS
+            case _:
+                raise ValueError(f"Unknown asset type: {asset_type}")
+    except IndexError as e:
+        raise ValueError(f"Invalid tag name: {tag_name}") from e
+
+
+class AssetNode(template.Node):
+    def __init__(self, asset_type: AssetType):
+        self.asset_type = asset_type
+
+    @override
+    def render(self, context: Context) -> str:
+        template = context.template
+        if template is None:
+            return ""
+        loaders = template.engine.template_loaders
+        for loader in loaders:
+            if isinstance(loader, BirdLoader):
+                assets = loader.asset_registry.get_assets(self.asset_type)
+                return self._render_assets(assets)
+
+        raise RuntimeError("BirdLoader not found in template loaders")
+
+    def _render_assets(self, assets: set[Asset]) -> str:
+        if not assets:
+            return ""
+
+        if self.asset_type == AssetType.CSS:
+            tags = (
+                f'<link rel="stylesheet" href="{asset.path}">'
+                for asset in sorted(assets, key=lambda a: a.path)
+            )
+        else:  # JS
+            tags = (
+                f'<script src="{asset.path}"></script>'
+                for asset in sorted(assets, key=lambda a: a.path)
+            )
+
+        return "\n".join(tags)
diff --git a/tests/conftest.py b/tests/conftest.py
diff --git a/tests/templatetags/test_asset.py b/tests/templatetags/test_asset.py
diff --git a/tests/test_loader.py b/tests/test_loader.py
