Merge branch 'main' of https://github.com/django-commons/django-unicorn into checksum-errors

Author: JohananOppongAmoateng

docs/source/index.md

@@ -22,6 +22,7 @@ templates
 actions
 child-components
 django-models
+
 ```
 
 ```{toctree}
@@ -60,6 +61,14 @@ cli
 settings
 ```
 
+```{toctree}
+:caption: Troubleshooting
+:maxdepth: 3
+:hidden:
+
+table-limitations
+```
+
 ```{toctree}
 :caption: Info
 :maxdepth: 3
@@ -93,6 +102,79 @@ Want to add some component-based magic to your front-end, but don't need the ove
   </a>
 </p>
 
+
+---
+
+## Incremental Adoption — No Full Migration Required
+
+```{important}
+You do **NOT** need to migrate your entire page or application to use Unicorn.
+```
+
+```{note}
+Unicorn is designed for **progressive enhancement**.  
+You can introduce it into an existing Django project one small component at a time.
+```
+
+```{warning}
+Many developers assume reactive component frameworks require:
+
+- Rewriting entire pages
+- Moving to an API-driven architecture
+- Converting everything into components
+- Adopting a SPA-style workflow
+
+**Unicorn requires none of that.**
+```
+
+Unicorn works alongside traditional Django views and templates. You can start
+with a single interactive element — such as:
+
+- A live-search input
+- A dropdown
+- A modal
+- A counter
+- A form with validation
+- A small dashboard widget
+
+while keeping the rest of your page completely unchanged.
+
+---
+
+### Example: Enhancing Just One Part of a Template
+
+Your existing Django template:
+
+```html
+<h1>Products</h1>
+
+{% for product in products %}
+  <p>{{ product.name }}</p>
+{% endfor %}
+```
+
+Now enhance just one piece with Unicorn:
+
+```html
+<h1>Products</h1>
+
+{% unicorn 'product-search' %}
+
+{% for product in products %}
+  <p>{{ product.name }}</p>
+{% endfor %}
+```
+
+That’s it.
+
+- No SPA  
+- No routing changes  
+- No large refactor  
+
+Unicorn allows gradual adoption. Start small and expand only where it makes sense.
+
+---
+
 Here are a few reasons to consider `Unicorn`.
 
 1. **Reactive Components**: With `Unicorn`, you can create reactive components that dynamically update the HTML DOM without the need for complex JavaScript. This makes it easier to build interactive web pages and enhances the user experience.

docs/source/javascript.md

@@ -30,6 +30,34 @@ class CallJavascriptView(UnicornView):
 
     def hello(self):
         self.call("hello", self.name)
+```
+
+## Remove a Component
+
+Call `self.remove()` from any view method to remove the component's root element from the DOM. This is useful for list-item components (e.g. table rows or list items) that need to delete themselves without requiring a parent component to manage re-rendering.
+
+```python
+# todo_item.py
+from django_unicorn.components import UnicornView
+
+class TodoItemView(UnicornView):
+    item_id: int = 0
+
+    def delete(self):
+        # perform any server-side cleanup here
+        TodoItem.objects.filter(pk=self.item_id).delete()
+        self.remove()
+```
+
+```html
+<!-- todo-item.html -->
+<li>
+  {{ item_id }}
+  <button unicorn:click="delete">Delete</button>
+</li>
+```
+
+Calling `self.remove()` is shorthand for `self.call("Unicorn.deleteComponent", self.component_id)`. After the server responds, the component's root element is removed from the DOM and cleaned up from the internal component store.
 
 ## Call Method on Other Component
 

docs/source/table-limitations.md

@@ -0,0 +1,138 @@
+# Table Rendering Limitations
+
+When using components inside HTML `<table>` elements, you must follow strict HTML structure rules. Failing to do so can cause reactivity issues that may look like state updates are not working.
+
+This is not a bug in **Django Unicorn**, but a consequence of how browsers handle table DOM structure.
+
+## Why This Happens
+
+HTML tables are **structurally strict**. Browsers automatically correct invalid markup inside table elements.
+
+Valid structure rules:
+* `<table>` may contain `<thead>`, `<tbody>`, `<tfoot>`
+* `<tbody>` may contain **only** `<tr>`
+* `<tr>` may contain **only** `<td>` or `<th>`
+* `<td>` may contain flow content (`<div>`, `<span>`, etc.)
+
+If a component rendered inside a `<tbody>` outputs something like:
+
+```html
+<tr>
+    <td>Row content</td>
+</tr>
+
+<div class="modal">...</div>
+```
+
+The `<div>` is **invalid inside `<tbody>`**, so the browser will automatically move it elsewhere in the DOM.
+
+When this happens:
+1. The browser modifies the DOM structure.
+2. Unicorn's DOM diffing no longer matches the expected structure.
+3. Reactive updates may silently fail or appear inconsistent.
+
+This commonly appears as:
+* A modal not showing reactively
+* Conditional blocks not updating
+* Child components not re-rendering properly
+
+## Example of Problematic Pattern
+
+Parent template:
+
+```html
+<tbody>
+    {% for item in items %}
+        {% unicorn 'row-component' item=item key=item.id %}
+    {% endfor %}
+</tbody>
+```
+
+Child component template:
+
+```html
+<tr>
+    <td>{{ item.name }}</td>
+    <td>
+        <button unicorn:click="show_modal">Delete</button>
+    </td>
+</tr>
+
+{% if modal_visible %}
+    <div class="modal">Are you sure?</div>
+{% endif %}
+```
+
+The `<div>` rendered after `<tr>` is invalid inside `<tbody>` and will be relocated by the browser.
+
+## Why It Works With `<div>`
+
+Replacing table tags with `<div>` works because `<div>` elements have no structural constraints. The browser does not auto-correct their placement, so Unicorn's DOM diffing remains stable.
+
+## Recommended Solutions
+
+### 1. Move Modals Outside the Table (Recommended)
+
+Control modal state from the parent component and render the modal outside the `<table>`.
+
+Child component:
+
+```python
+def request_delete(self):
+    self.parent.confirm_delete(self.item.id)
+```
+
+Parent component:
+
+```python
+selected_id = None
+show_modal = False
+
+def confirm_delete(self, item_id):
+    self.selected_id = item_id
+    self.show_modal = True
+```
+
+Render the modal below the table:
+
+```html
+</table>
+
+{% if show_modal %}
+    <div class="modal">...</div>
+{% endif %}
+```
+
+This keeps table markup valid and avoids DOM restructuring.
+
+### 2. Render Modal Inside a Valid `<td>`
+
+If you must render it within the table, wrap it inside a `<td colspan="...">`:
+
+```html
+{% if modal_visible %}
+<tr>
+    <td colspan="5">
+        <div class="modal">...</div>
+    </td>
+</tr>
+{% endif %}
+```
+
+This preserves valid table structure.
+
+### 3. Ensure Single Valid Root Per Component
+
+When rendering a component inside `<tbody>`, its root element must be a `<tr>`.
+When rendering inside `<tr>`, its root must be `<td>` or `<th>`.
+
+Avoid rendering sibling elements that break table hierarchy.
+
+## Key Takeaway
+
+If you experience reactivity issues inside tables:
+* Verify your component outputs valid HTML table structure.
+* Ensure no `<div>` or non-table elements are placed directly inside `<tbody>` or `<tr>`.
+* Prefer handling overlays and modals outside the table.
+
+Table elements are one of the strictest parts of HTML. Following valid structure rules ensures Unicorn's DOM diffing remains reliable and reactive updates function correctly.

docs/source/templates.md

@@ -5,6 +5,8 @@ Templates are normal Django HTML templates, so anything you could normally do in
 ```{warning}
 `Unicorn` requires there to be one root element that contains the component HTML. Valid HTML and a wrapper element is required for the DOM diffing algorithm to work correctly, so `Unicorn` will try to log a warning message if they seem invalid.
 
+One common issue is when a component is a table row (`tr`). Since `tr` elements can only contain `td` or `th` elements, any other element (like a `div`) will be "foster parented" out of the table structure by the browser. This will cause the DOM diffing to fail since the element structure is not what `Unicorn` expects.
+
 For example, this is an **invalid** template:
 :::{code} html
 :force: true

docs/source/troubleshooting.md

@@ -81,3 +81,36 @@ MIDDLEWARE = [
   </body>
 </html>
 ```
+
+## Tables and invalid HTML
+
+Browsers are very strict about table structure (e.g. `<tr>` can only be a direct child of `<tbody>`, `<thead>`, `<tfoot>`, or `<table>`, and `<div>` is not allowed as a direct child of `<tr>`). If you have a component that renders a table row, unexpected behavior can occur because the browser will "foster parent" invalid elements out of the table structure before `Unicorn` can seemingly react to them.
+
+For example, this valid-looking component template will cause issues:
+
+```html
+<!-- invalid-table-row.html -->
+<tr>
+  <td>{{ name }}</td>
+  {% if show_modal %}
+    <div class="modal">...</div>
+  {% endif %}
+</tr>
+```
+
+The browser will move the `div` out of the `tr` (and likely out of the `table` entirely), so when `Unicorn` tries to update the component, it will be confused by the missing element.
+
+To fix this, ensure that all content is inside a valid table element, like a `td`:
+
+```html
+<!-- valid-table-row.html -->
+<tr>
+  <td>{{ name }}</td>
+  <td>
+    {% if show_modal %}
+      <div class="modal">...</div>
+    {% endif %}
+  </td>
+</tr>
+```
+

src/django_unicorn/components/unicorn_view.py

@@ -330,6 +330,14 @@ def call(self, function_name, *args):
         """
         self.calls.append({"fn": function_name, "args": args})
 
+    def remove(self):
+        """
+        Remove this component's root element from the DOM and delete it from the
+        internal component store. Equivalent to calling
+        ``self.call("Unicorn.deleteComponent", self.component_id)``.
+        """
+        self.call("Unicorn.deleteComponent", self.component_id)
+
     def mount(self):
         """
         Hook that gets called when the component is first created.
@@ -824,6 +832,7 @@ def _is_public(self, name: str) -> bool:
             "parent",
             "children",
             "call",
+            "remove",
             "calls",
             "component_cache_key",
             "component_kwargs",

src/django_unicorn/serializer.py

@@ -275,7 +275,17 @@ def _fix_floats(current: dict, data: dict | None = None, paths: list | None = No
             paths.append(key)
             _fix_floats(val, data, paths=paths)
             paths.pop()
-    elif isinstance(current, list):
+    elif isinstance(current, (list, tuple)):
+        if isinstance(current, tuple) and paths:
+            # Tuples are immutable; convert to list in the parent container so
+            # we can mutate float values inside it.
+            _piece = data
+            for idx, path in enumerate(paths):
+                if idx == len(paths) - 1:
+                    _piece[path] = list(current)
+                else:
+                    _piece = _piece[path]
+            current = _piece[paths[-1]]
         for idx, item in enumerate(current):
             paths.append(idx)
             _fix_floats(item, data, paths=paths)