Merge branch 'main' into css-transitions

Author: JohananOppongAmoateng

.github/workflows/publish.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - "*.*.*"
+  workflow_dispatch:
 
 permissions:
   contents: read

DEVELOPING.md

@@ -39,7 +39,7 @@
 1. Update `docs/source/changelog.md`
 1. Update version in `pyproject.toml`
 1. Commit changes
-1. Tag the release: `git tag 0.65.0`
+1. Tag the release: `git tag #.##.#`
 1. Push the tag: `git push origin --tags`
 1. The GitHub Action will automatically:
     - Build the JavaScript assets with the correct version

docs/source/changelog.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.66.0
+
+**Features**
+- Implement `unicorn:dirty` targeting support.
+- Add signals for lifecycle hooks.
+- Implement script tag loading from newly added child components.
+- Implement popstate support for history navigation.
+- Implement a timestamp-based (epoch) tracking mechanism to identify and discard stale responses on the frontend.
+
+**Fixes**
+- Surface broken import errors when loading components.
+- Handle nested method calls in `parse_call_method_name`.
+- Restore float values in nested `tuple[dict]` fields.
+- Fix: `u:loading` on child elements no longer disables parent `u:click`.
+- Fix: Trigger loading states for actions called via `Unicorn.call()`.
+- Fix: Include child component JavaScript calls in response.
+- Fix `ValueError` when deserializing `ForeignKey` fields on models loaded outside `mount`.
+
+**Refactors**
+- Consolidate component metadata (checksum, hash, epoch) into 'meta' identifier.
+- Remove redundant per-component script tags and enable global DOM scanning.
+
+**Documentation**
+- Add tutorial documentation covering inputs, actions, and polling.
+- Add guide on table structure limitations.
+- Clarify Unicorn can be adopted incrementally.
+- Add Context Processors and Component Re-rendering section.
+- Improve Installation Tutorial and Add Pagination Documentation.
+
 ## 0.65.0
 
 - Properly escape single quotes in Unicorn.call() arguments [#773](https://github.com/adamghill/django-unicorn/pull/773) by [JohananOppongAmoateng](https://github.com/JohananOppongAmoateng).

docs/source/templates.md

@@ -65,6 +65,113 @@ class HelloWorldView(UnicornView):
 [Django models](django-models.md) has many more details about using Django models in `Unicorn`.
 ```
 
+## Models inside `{% for %}` loops
+
+When iterating over a list with a Django `{% for %}` loop, the loop variable is **not** the same as the component attribute that holds the list. Unicorn syncs `<input>` values by looking up the `unicorn:model` name in the component's serialised data, so the model name must use the **component attribute path** (e.g. `items.0.name`), not the loop variable name (e.g. `item.name`).
+
+Use `{{ forloop.counter0 }}` to build the correct index-based path:
+
+```python
+# line_items.py
+from django_unicorn.components import UnicornView
+
+class LineItemsView(UnicornView):
+    items: list = []
+
+    def mount(self):
+        self.items = [{"name": "Widget", "qty": 1}, {"name": "Gadget", "qty": 3}]
+
+    def add_item(self):
+        self.items.append({"name": "", "qty": 0})
+```
+
+```html
+<!-- unicorn/line-items.html -->
+<div>
+  {% for item in items %}
+  <div>
+    <input
+      unicorn:model="items.{{ forloop.counter0 }}.name"
+      type="text"
+    />
+    <input
+      unicorn:model="items.{{ forloop.counter0 }}.qty"
+      type="number"
+    />
+  </div>
+  {% endfor %}
+  <button unicorn:click="add_item">Add row</button>
+</div>
+```
+
+The key is `items.{{ forloop.counter0 }}.name` this renders to `items.0.name`, `items.1.name`, etc., which Unicorn can resolve directly against the component data.
+
+```{warning}
+Using the **loop variable name** in `unicorn:model` (e.g. `unicorn:model="item.name"`)
+will **not** work correctly after a re-render.  When the component re-renders,
+Unicorn tries to look up `item` in the component's data, but `item` is only a
+Django template loop variable — it has no corresponding key in the serialised
+component state.  As a result morphdom will clear the input's value.
+
+Use `items.{{ forloop.counter0 }}.name` instead.
+```
+
+## Rendering choice fields
+
+Django models often use `TextChoices` (or `IntegerChoices`) to constrain a field to a fixed set of values. To render a reactive `<select>` that is bound to a Unicorn component field, expose the choices list as a component attribute and exclude it from the JavaScript context (since the choices are static and do not need to be reactive).
+
+```python
+# new_course.py
+from django_unicorn.components import UnicornView
+from curriculum.models import Course
+
+
+class NewCourseView(UnicornView):
+    grade_level = Course.GradeLevel.UNDEFINED
+    subject = Course.Subject.UNDEFINED
+
+    # Static choices — kept out of the JSON state sent to the browser
+    grade_level_choices = Course.GradeLevel.choices
+    subject_choices = Course.Subject.choices
+
+    class Meta:
+        javascript_exclude = ("grade_level_choices", "subject_choices")
+
+    def save(self):
+        Course.objects.create(
+            grade_level=self.grade_level,
+            subject=self.subject,
+        )
+```
+
+```html
+<!-- unicorn/new-course.html -->
+<div>
+  <select unicorn:model="grade_level">
+    {% for value, label in grade_level_choices %}
+    <option value="{{ value }}">{{ label }}</option>
+    {% endfor %}
+  </select>
+
+  <select unicorn:model="subject">
+    {% for value, label in subject_choices %}
+    <option value="{{ value }}">{{ label }}</option>
+    {% endfor %}
+  </select>
+
+  <button unicorn:click="save">Save</button>
+</div>
+```
+
+Adding the choices to [`Meta.javascript_exclude`](views.md#javascript_exclude) keeps them in the Django template context (so the `{% for %}` loop works) without serialising them into the `unicorn:data` JSON attribute on every render. The `grade_level` and `subject` fields remain fully reactive — Unicorn syncs the selected value back to the component on each change.
+
+```{note}
+If you also need validation, set `form_class` on the component to a Django `ModelForm` or `Form`.
+Unicorn will validate `grade_level` and `subject` against the form's field definitions when
+`$validate` is called or when an action method calls `self.validate()`. See
+[validation](validation.md) for details.
+```
+
 ## Model modifiers
 
 ### Lazy

docs/source/views.md

@@ -195,6 +195,45 @@ class HelloKwargView(UnicornView):
       assert self.component_kwargs["hello"] == "World"
 ```
 
+### Passing a Django Form
+
+A Django `Form` (or `ModelForm`) instance can be passed directly from a template into a unicorn component as a keyword argument. The form will be available in the component's template context for rendering, but it is automatically excluded from the JSON state sent to the browser (since forms cannot be serialized to JSON).
+
+```html
+<!-- index.html -->
+{% unicorn 'my-form-component' form=my_django_form %}
+```
+
+```python
+# my_form_component.py
+from django_unicorn.components import UnicornView
+
+class MyFormComponentView(UnicornView):
+    form = None  # will hold the passed-in form instance
+
+    def mount(self):
+        # self.form is available here on the initial render
+        pass
+```
+
+```html
+<!-- unicorn/my-form-component.html -->
+<div>
+  <form method="POST">
+    {% csrf_token %}
+    {{ form.as_p }}
+    <button unicorn:click="submit">Submit</button>
+  </form>
+</div>
+```
+
+```{note}
+Because forms cannot be pickled, `self.form` will be `None` on subsequent AJAX
+interactions (after the initial page load). If you need to process submitted form
+data reactively, declare a `form_class` on the component and use
+[component validation](validation.md) instead.
+```
+
 ### request
 
 The current `request`.
@@ -392,7 +431,12 @@ class HelloStateView(UnicornView):
 
 ### javascript_exclude
 
-To allow an attribute to be included in the the context to be used by a Django template, but not exposed to JavaScript, add it to the `Meta` class's `javascript_exclude` tuple.
+To allow an attribute to be included in the context to be used by a Django template, but not exposed to JavaScript, add it to the `Meta` class's `javascript_exclude` tuple.
+
+```{note}
+Django `Form` and `ModelForm` instances are **automatically** excluded from the
+JavaScript context — you do not need to add them to `javascript_exclude`.
+```
 
 ```html
 <!-- hello-state.html -->
@@ -465,4 +509,12 @@ Do not store unpickleable objects (e.g. generators) on the component instance.
 
 If you need to use an unpickleable object, either convert it to a pickleable type (e.g. convert a generator to a list) or re-initialize it within the method that needs it without storing it on `self`.
 
+```{note}
+Django `Form` and `ModelForm` instances are handled automatically — they are stripped
+from the component before pickling and restored afterwards, so passing a form as a
+template kwarg (see [Passing a Django Form](#passing-a-django-form)) will not cause
+pickling errors. The form will be `None` after a cache restore (i.e. on subsequent
+AJAX requests).
+```
+