feat: support transitions

Author: JohananOppongAmoateng

docs/source/index.md

@@ -40,6 +40,7 @@ polling
 visibility
 messages
 pagination
+transitions
 ```
 
 ```{toctree}

docs/source/transitions.md

@@ -0,0 +1,52 @@
+# Transitions
+
+Transitions allow you to add CSS animations when elements are added to or removed from the DOM. This is particularly useful for modals, menus, and other UI elements that should fade or slide into place.
+
+`Unicorn` follows the same transition pattern as Vue and Alpine.js, using six lifecycle stages defined by data attributes.
+
+## Attributes
+
+There are six attributes that can be used to define a transition:
+
+- `u:transition:enter`: Classes applied during the entire entering phase.
+- `u:transition:enter-start`: Classes applied at the start of the entering phase. Removed after one frame.
+- `u:transition:enter-end`: Classes applied at the end of the entering phase.
+- `u:transition:leave`: Classes applied during the entire leaving phase.
+- `u:transition:leave-start`: Classes applied at the start of the leaving phase.
+- `u:transition:leave-end`: Classes applied at the end of the leaving phase.
+
+Alternatively, you can use the `unicorn:` prefix instead of `u:`.
+
+## Example
+
+The following example uses Tailwind CSS classes to create a fade and scale transition.
+
+```html
+<div>
+    <button unicorn:click="toggle">Toggle</button>
+    
+    {% if show %}
+    <div u:transition:enter="transition ease-out duration-300"
+         u:transition:enter-start="opacity-0 transform scale-90"
+         u:transition:enter-end="opacity-100 transform scale-100"
+         u:transition:leave="transition ease-in duration-300"
+         u:transition:leave-start="opacity-100 transform scale-100"
+         u:transition:leave-end="opacity-0 transform scale-90"
+         class="bg-gray-100 p-4 mt-2">
+        Transitional Content
+    </div>
+    {% endif %}
+</div>
+```
+
+## How it works
+
+When an element with a transition is added to the DOM:
+1. `u:transition:enter` and `u:transition:enter-start` classes are added.
+2. After one frame, `u:transition:enter-start` is removed and `u:transition:enter-end` is added.
+3. Once the transition finishes, `u:transition:enter` and `u:transition:enter-end` are removed.
+
+When an element with a transition is removed from the DOM:
+1. `u:transition:leave` and `u:transition:leave-start` classes are added.
+2. After one frame, `u:transition:leave-start` is removed and `u:transition:leave-end` is added.
+3. `Unicorn` waits for the transition to finish (`element.getAnimations()`) before finally removing the element from the DOM.

example/unicorn/components/transition.py

@@ -0,0 +1,7 @@
+from django_unicorn.components import UnicornView
+
+class TransitionView(UnicornView):
+    show = False
+
+    def toggle(self):
+        self.show = not self.show

example/unicorn/templates/unicorn/transition.html

@@ -0,0 +1,15 @@
+<div>
+    <button unicorn:click="toggle">Toggle</button>
+    
+    {% if show %}
+    <div u:transition:enter="transition ease-out duration-300"
+         u:transition:enter-start="opacity-0 transform scale-90"
+         u:transition:enter-end="opacity-100 transform scale-100"
+         u:transition:leave="transition ease-in duration-300"
+         u:transition:leave-start="opacity-100 transform scale-100"
+         u:transition:leave-end="opacity-0 transform scale-90"
+         style="background: #f0f0f0; padding: 20px; margin-top: 10px;">
+        Transitional Content
+    </div>
+    {% endif %}
+</div>

example/www/templates/www/base.html

@@ -20,7 +20,6 @@
     #menu li:first-child {
       border-left: none !important;
     }
-
   </style>
 
   <script defer src="https://unpkg.com/@alpinejs/morph@3.x.x/dist/cdn.min.js"></script>
@@ -48,11 +47,12 @@ <h1>django-unicorn</h1>
       <li><a href="{% url 'www:direct-view' %}">Direct View</a></li>
       <li><a href="{% url 'www:redirects' %}">Redirects</a></li>
       <li><a href="{% url 'www:template' 'wizard' %}">Wizard</a></li>
+      <li><a href="{% url 'www:template' 'transition' %}">Transitions</a></li>
     </ul>
 
     {% block content %}{% endblock content %}
 
   </main>
 </body>
 
-</html>
+</html>

example/www/templates/www/transition.html

@@ -0,0 +1,13 @@
+{% extends "www/base.html" %}
+{% load unicorn %}
+
+{% block content %}
+<div class="container">
+    <div class="row">
+        <div class="col">
+            <h1>Transitions</h1>
+            {% unicorn 'transition' %}
+        </div>
+    </div>
+</div>
+{% endblock %}

src/django_unicorn/static/unicorn/js/attribute.js

@@ -20,6 +20,7 @@ export class Attribute {
     this.isError = false;
     this.modifiers = {};
     this.eventType = null;
+    this.isTransition = false
 
     this.init();
   }
@@ -52,6 +53,8 @@ export class Attribute {
         this.isKey = true;
       } else if (contains(this.name, ":error:")) {
         this.isError = true;
+      } else if (contains(this.name, ":transition")) {
+        this.isTransition = true;
       } else {
         const actionEventType = this.name
           .replace("unicorn:", "")

src/django_unicorn/static/unicorn/js/element.js

@@ -35,6 +35,7 @@ export class Element {
     this.key = null;
     this.events = [];
     this.errors = [];
+    this.transitions = {};
 
     if (!this.el.attributes) {
       return;
@@ -156,6 +157,17 @@ export class Element {
         this.key = attribute.value;
       }
 
+      if (attribute.isTransition) {
+        let transitionType = attribute.name.replace("unicorn:transition:", "").replace("u:transition:", "");
+
+        // If no type is specified, default to "enter" (though usually it's explicitly specified)
+        if (transitionType === "unicorn:transition" || transitionType === "u:transition") {
+          transitionType = "enter";
+        }
+
+        this.transitions[transitionType] = attribute.value;
+      }
+
       if (attribute.isError) {
         const code = attribute.name.replace("unicorn:error:", "");
         this.errors.push({ code, message: attribute.value });

src/django_unicorn/static/unicorn/js/morphers/morphdom.js

@@ -1,4 +1,6 @@
 import morphdom from "../morphdom/2.6.1/morphdom.js";
+import { Transition } from "../transition.js";
+import { Element as UnicornElement } from "../element.js";
 
 export class MorphdomMorpher {
   constructor(options) {
@@ -57,6 +59,10 @@ export class MorphdomMorpher {
         return true;
       },
       onNodeAdded(node) {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+          Transition.enter(node);
+        }
+
         if (reloadScriptElements) {
           if (node.nodeName === "SCRIPT") {
             // https://github.com/patrick-steele-idem/morphdom/issues/178#issuecomment-652562769
@@ -71,6 +77,21 @@ export class MorphdomMorpher {
           }
         }
       },
+      onBeforeNodeDiscarded(node) {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+          const element = new UnicornElement(node);
+
+          if (element.transitions.leave) {
+            Transition.leave(node).then(() => {
+              node.remove();
+            });
+
+            return false;
+          }
+        }
+
+        return true;
+      },
     };
   }
 }

src/django_unicorn/static/unicorn/js/transition.js

@@ -0,0 +1,71 @@
+import { Element as UnicornElement } from "./element.js";
+
+/**
+ * Handles CSS transitions for an element.
+ */
+export class Transition {
+  /**
+   * Run the enter transition.
+   * @param {Element} el DOM element
+   */
+  static async enter(el) {
+    await this.run(el, "enter");
+  }
+
+  /**
+   * Run the leave transition.
+   * @param {Element} el DOM element
+   */
+  static async leave(el) {
+    await this.run(el, "leave");
+  }
+
+  /**
+   * Run a transition for a given stage (enter or leave).
+   */
+  static async run(el, stage) {
+    const element = new UnicornElement(el);
+    const transitions = element.transitions;
+
+    const classes = (transitions[stage] || "").split(" ").filter(Boolean);
+    const startClasses = (transitions[`${stage}-start`] || "").split(" ").filter(Boolean);
+    const endClasses = (transitions[`${stage}-end`] || "").split(" ").filter(Boolean);
+
+    if (classes.length === 0 && startClasses.length === 0 && endClasses.length === 0) {
+      return;
+    }
+
+    // Prepare transition
+    el.classList.add(...classes);
+    el.classList.add(...startClasses);
+
+    // Wait for a frame to ensure classes are applied
+    await nextFrame();
+
+    el.classList.remove(...startClasses);
+    el.classList.add(...endClasses);
+
+    await afterTransition(el);
+
+    el.classList.remove(...classes);
+    el.classList.remove(...endClasses);
+  }
+}
+
+/**
+ * Wait for the next animation frame.
+ */
+function nextFrame() {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(resolve);
+    });
+  });
+}
+
+/**
+ * Wait for a transition or animation to finish.
+ */
+function afterTransition(el) {
+  return Promise.all(el.getAnimations().map((animation) => animation.finished));
+}