add {% bird:prop %} templatetag (#54)

* add `{% bird:prop %}` templatetag

* fix types

* add tests for prop name

* update changelog

* update docs

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* tweak attrs distinction and add section about multiple props

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update params.py

* add tests for render props method

* adjust None test

---------

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
+
+- Created `{% bird:prop %}` tag for defining properties within components. These operate similarly to the `{{ attrs }}` template context variable, but allow for setting defaults. Any attributes passed to a component will override the prop's default value, and props defined in a component template are automatically removed from the component's `attrs`. Props are accessible in templates via the `props` context variable (e.g. `{{ props.id }}`)
+
 ## [0.2.0]
 
 🚨 This release contains a breaking change. See the Changed section for more information. 🚨

docs/attrs.md

@@ -12,7 +12,7 @@
 :hidden:
 :maxdepth: 3
 Naming <naming>
-attrs
+Attributes/Properties <params>
 slots
 Organization <organization>
 configuration

docs/index.md

@@ -0,0 +1,183 @@
+# Passing Parameters to Components
+
+django-bird provides two ways to pass parameters to your components: attributes and properties. While attributes and properties may look similar when using a component, they serve different purposes.
+
+Attributes are made available to your component template as a flattened string via the `{{ attrs }}` template context variable which can be used to apply HTML attributes to elements, while properties are accessible as individual values (e.g. `{{ props.variant }}`) that your component can use internally to control its rendering logic.
+
+Note that these parameters are distinct from [Slots](slots.md) - they are used to configured how your component behaves or renders, while slots define where content should be inserted into your component's template.
+
+For example, a button component might use properties to control its styling and attributes to set HTML attributes, while using slots to define its content:
+
+```htmldjango
+{% bird button variant="primary" data-analytics="signup" %}
+    Click here  {# This content will go in the default slot #}
+{% endbird %}
+```
+
+## Attributes
+
+Attributes (i.e. `attrs`) let you pass additional HTML attributes to your components. This feature provides flexibility and customization without modifying the component template.
+
+In your component template, the `{{ attrs }}` variable is a special variable that contains all the attributes passed to the component as a pre-rendered string. Unlike props which can be accessed individually, attributes are flattened into a single string ready to be inserted into an HTML element. The `{{ attrs }}` variable automatically handles both key-value attributes (like `class="btn"`) and boolean attributes (like `disabled`).
+
+### Basic Usage
+
+Here's a simple example of a button component that accepts attributes:
+
+```{code-block} htmldjango
+:caption: templates/bird/button.html
+
+<button {{ attrs }}>
+    {{ slot }}
+</button>
+```
+
+Use this component and pass attributes like this:
+
+```htmldjango
+{% bird button class="btn" %}
+    Click me!
+{% endbird %}
+```
+
+It will render as:
+
+```html
+<button class="btn">
+    Click me!
+</button>
+
+```
+
+### Multiple Attributes
+
+You can pass multiple attributes to a component:
+
+```htmldjango
+{% bird button class="btn btn-primary" id="submit-btn" disabled %}
+    Submit
+{% endbird %}
+```
+
+This will render as:
+
+```html
+<button class="btn btn-primary" id="submit-btn" disabled>
+    Submit
+</button>
+```
+
+## 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.
+
+In your component template, props are defined using the `{% bird:prop %}` tag and accessed via the `{{ props }}` context variable. You can define as many props as needed using separate `{% bird:prop %}` tags. When a prop is defined, any matching attribute passed to the component will be removed from `{{ attrs }}` and made available in `{{ props }}` instead.
+
+### Basic Usage
+
+Here's a simple example of a button component that uses props:
+
+```{code-block} htmldjango
+:caption: templates/bird/button.html
+
+{% bird:prop variant='primary' %}
+<button class="btn btn-{{ props.variant }}" {{ attrs }}>
+    {{ slot }}
+</button>
+```
+
+Use this component and override the default variant like this:
+
+```htmldjango
+{% bird button variant="secondary" id="secondary-button" %}
+    Click me!
+{% endbird %}
+```
+
+It will render as:
+
+```html
+<button class="btn btn-secondary" id="secondary-button">
+    Click me!
+</button>
+```
+
+Notice how this works:
+
+- The `variant` attribute is removed from `attrs` because it matches a defined prop
+- Its value "secondary" is made available as `props.variant`
+- The `id` attribute remains in `attrs` since it's not defined as a prop
+- The final HTML only includes `variant`'s value as part of the class name, while `id` appears as a direct attribute
+
+This separation allows you to use props to control your component's logic while still accepting arbitrary HTML attributes.
+
+### Multiple Props
+
+Components often need multiple props to control different aspects of their behavior. Each prop is defined with its own `{% bird:prop %}` tag:
+
+```{code-block} htmldjango
+:caption: templates/bird/button.html
+
+{% bird:prop variant='primary' %}
+{% bird:prop size='md' %}
+<button
+    class="btn btn-{{ props.variant }} btn-{{ props.size }}"
+    {{ attrs }}
+>
+    {{ slot }}
+</button>
+```
+
+Use the component by setting any combination of these props:
+
+```htmldjango
+{% bird button variant="secondary" size="lg" disabled=True %}
+    Click me!
+{% endbird %}
+```
+
+It will render as:
+
+```html
+<button class="btn btn-secondary btn-lg" disabled>
+    Click me!
+</button>
+```
+
+This approach of using separate tags for each prop makes it easier to expand the prop system in the future - for example, adding features like type validation or choice constraints while maintaining a clean syntax.
+
+### Props with Defaults
+
+Props can be defined with or without default values:
+
+```htmldjango
+{% bird:prop id %}                 {#  No default value  #}
+{% bird:prop variant='primary' %}  {# With default value #}
+<button
+    id="{{ props.id }}"
+    class="btn btn-{{ props.variant }}"
+    {{ attrs }}
+>
+    {{ slot }}
+</button>
+```
+
+When used, props will take their value from either the passed attribute or fall back to their default:
+
+```htmldjango
+{% bird button variant="secondary" %}
+    Submit
+{% endbird %}
+```
+
+This will render as:
+
+```html
+<button id="" class="btn btn-secondary">
+    Submit
+</button>
+```
+
+```{note}
+Props defined without a default value will render as an empty string if no value is provided when using the component. This behavior may change in a future version to either require default values or handle undefined props differently.
+```

docs/params.md

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from dataclasses import field
 
 from django import template
+from django.template.base import NodeList
 from django.template.context import Context
 from django.utils.safestring import SafeString
 from django.utils.safestring import mark_safe
@@ -39,7 +41,35 @@ def from_bit(cls, bit: str):
 
 @dataclass
 class Params:
-    attrs: list[Param]
+    attrs: list[Param] = field(default_factory=list)
+    props: list[Param] = field(default_factory=list)
+
+    def render_props(self, nodelist: NodeList | None, context: Context):
+        from django_bird.templatetags.tags.prop import PropNode
+
+        if nodelist is None:
+            return
+
+        attrs_to_remove = set()
+
+        for node in nodelist:
+            if not isinstance(node, PropNode):
+                continue
+
+            value: str | bool | None = node.default
+
+            for idx, attr in enumerate(self.attrs):
+                if node.name == attr.name:
+                    if attr.value:
+                        value = attr.value
+                    attrs_to_remove.add(idx)
+
+            self.props.append(Param(name=node.name, value=value))
+
+        for idx in sorted(attrs_to_remove, reverse=True):
+            self.attrs.pop(idx)
+
+        return {prop.name: prop.value for prop in self.props}
 
     def render_attrs(self, context: Context) -> SafeString:
         rendered = " ".join(attr.render(context) for attr in self.attrs)

src/django_bird/components/params.py

@@ -3,10 +3,12 @@
 from django import template
 
 from .tags import bird
+from .tags import prop
 from .tags import slot
 
 register = template.Library()
 
 
 register.tag(bird.TAG, bird.do_bird)
+register.tag(prop.TAG, prop.do_prop)
 register.tag(slot.TAG, slot.do_slot)

src/django_bird/templatetags/django_bird.py

@@ -1,9 +0,0 @@
-from __future__ import annotations
-
-from .bird import do_bird
-from .slot import do_slot
-
-__all__ = [
-    "do_bird",
-    "do_slot",
-]

src/django_bird/templatetags/tags/__init__.py

@@ -6,6 +6,7 @@
 from django import template
 from django.template.base import NodeList
 from django.template.base import Parser
+from django.template.base import Template
 from django.template.base import Token
 from django.template.context import Context
 from django.template.loader import select_template
@@ -61,9 +62,9 @@ def __init__(self, name: str, params: Params, nodelist: NodeList | None) -> None
     @override
     def render(self, context: Context) -> SafeString:
         component_name = self.get_component_name(context)
-        component_context = self.get_component_context_data(context)
         template_names = get_template_names(component_name)
         template = select_template(template_names)
+        component_context = self.get_component_context_data(template.template, context)
         return template.render(component_context)
 
     def get_component_name(self, context: Context) -> str:
@@ -73,12 +74,16 @@ def get_component_name(self, context: Context) -> str:
             name = self.name
         return name
 
-    def get_component_context_data(self, context: Context) -> dict[str, Any]:
+    def get_component_context_data(
+        self, template: Template, context: Context
+    ) -> dict[str, Any]:
+        props = self.params.render_props(template.nodelist, context)
         attrs = self.params.render_attrs(context)
         slots = Slots.collect(self.nodelist, context).render()
         default_slot = slots.get(DEFAULT_SLOT) or context.get("slot")
         return {
             "attrs": attrs,
+            "props": props,
             "slot": default_slot,
             "slots": slots,
         }