add signals for lifecycle hooks

Author: JohananOppongAmoateng

docs/source/index.md

@@ -50,6 +50,7 @@ pagination
 javascript
 queue-requests
 custom-morphers
+signals
 ```
 
 ```{toctree}

docs/source/signals.md

@@ -0,0 +1,199 @@
+# Signals
+
+`Unicorn` emits [Django signals](https://docs.djangoproject.com/en/stable/topics/signals/)
+for each component lifecycle event.  You can connect receivers to observe component
+activity without monkey-patching internal methods — useful for debug toolbars, logging,
+analytics, or custom auditing.
+
+## Connecting to a signal
+
+```python
+from django.dispatch import receiver
+from django_unicorn.signals import component_rendered
+
+@receiver(component_rendered)
+def on_render(sender, component, html, **kwargs):
+    print(f"{component.component_name} rendered {len(html)} bytes")
+```
+
+`sender` is always the component **class** (not an instance).  Every signal also
+passes the live `component` instance as a keyword argument, plus any event-specific
+kwargs documented below.
+
+## Available signals
+
+All signals are importable from `django_unicorn.signals`.
+
+---
+
+### `component_mounted`
+
+Sent when a component is first created (mirrors the {meth}`mount` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+
+---
+
+### `component_hydrated`
+
+Sent when a component's data is hydrated (mirrors the {meth}`hydrate` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+
+---
+
+### `component_completed`
+
+Sent after all component actions have been executed (mirrors the {meth}`complete` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+
+---
+
+### `component_rendered`
+
+Sent after a component is rendered during an AJAX request (mirrors the {meth}`rendered`
+hook).  Not fired for the initial server-side page render via the template tag.
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+| `html` | `str` | The rendered HTML string |
+
+---
+
+### `component_parent_rendered`
+
+Sent after a child component's parent is rendered (mirrors the {meth}`parent_rendered`
+hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The **child** component instance |
+| `html` | `str` | The rendered parent HTML string |
+
+---
+
+### `component_property_updating`
+
+Sent before a component property is updated (mirrors the {meth}`updating` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+| `name` | `str` | Property name being updated |
+| `value` | `Any` | The incoming new value |
+
+---
+
+### `component_property_updated`
+
+Sent after a component property is updated (mirrors the {meth}`updated` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+| `name` | `str` | Property name that was updated |
+| `value` | `Any` | The new value |
+
+---
+
+### `component_property_resolved`
+
+Sent after a component property value is resolved (mirrors the {meth}`resolved` hook).
+Unlike `component_property_updating` / `component_property_updated`, this signal fires
+**only once** per sync cycle.
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+| `name` | `str` | Property name that was resolved |
+| `value` | `Any` | The resolved value |
+
+---
+
+### `component_method_calling`
+
+Sent before a component method is called (mirrors the {meth}`calling` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+| `name` | `str` | Method name about to be called |
+| `args` | `tuple` | Positional arguments |
+
+---
+
+### `component_method_called`
+
+Sent after a component method is invoked — on both **success and failure**.
+This signal includes the return value and exception info, making it more complete
+than the `called()` hook.
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+| `method_name` | `str` | Method name that was called |
+| `args` | `tuple` | Positional arguments |
+| `kwargs` | `dict` | Keyword arguments |
+| `result` | `Any` | Return value of the method, or `None` on failure |
+| `success` | `bool` | `True` if the method completed without raising an exception |
+| `error` | `Exception \| None` | The exception raised, or `None` on success |
+
+```python
+from django.dispatch import receiver
+from django_unicorn.signals import component_method_called
+
+@receiver(component_method_called)
+def log_method(sender, component, method_name, result, success, error, **kwargs):
+    if success:
+        print(f"[unicorn] {component.component_name}.{method_name}() → {result!r}")
+    else:
+        print(f"[unicorn] {component.component_name}.{method_name}() raised {error!r}")
+```
+
+---
+
+### `component_pre_parsed`
+
+Sent before the incoming request data is parsed and applied to the component
+(mirrors the {meth}`pre_parse` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+
+---
+
+### `component_post_parsed`
+
+Sent after the incoming request data is parsed and applied to the component
+(mirrors the {meth}`post_parse` hook).
+
+| kwarg | type | description |
+|-------|------|-------------|
+| `component` | `UnicornView` | The component instance |
+
+---
+
+## Overriding hooks vs. connecting signals
+
+The existing lifecycle hook methods (`mount`, `hydrate`, `rendered`, etc.) and signals
+serve different purposes:
+
+- **Hook methods** — override in your component subclass to run logic *inside* the
+  component (e.g. `def mount(self): self.items = Items.objects.all()`).
+- **Signals** — connect a receiver anywhere in your project to observe *any* component
+  without modifying component code.
+
+```{note}
+If you override a hook method in your component class and do **not** call
+``super()``, the corresponding signal will **not** fire because the default
+implementation (which sends the signal) is bypassed.
+```

src/django_unicorn/components/unicorn_template_response.py

@@ -16,6 +16,7 @@
     NoRootComponentElementError,
 )
 from django_unicorn.settings import get_minify_html_enabled
+from django_unicorn.signals import component_rendered
 from django_unicorn.utils import generate_checksum, html_element_to_string
 
 logger = logging.getLogger(__name__)
@@ -236,6 +237,7 @@ def render(self):
         rendered_template = html_element_to_string(root_element)
 
         self.component.rendered(rendered_template)
+        component_rendered.send(sender=self.component.__class__, component=self.component, html=rendered_template)
         response.content = rendered_template
 
         if get_minify_html_enabled():

src/django_unicorn/components/unicorn_view.py

@@ -28,6 +28,11 @@
     UnicornCacheError,
 )
 from django_unicorn.settings import get_setting
+from django_unicorn.signals import (
+    component_completed,
+    component_hydrated,
+    component_mounted,
+)
 from django_unicorn.typer import cast_attribute_value, get_type_hints
 from django_unicorn.utils import create_template, is_non_string_sequence
 
@@ -149,8 +154,11 @@ def construct_component(
     component.calls = []
 
     component._mount_result = component.mount()
+    component_mounted.send(sender=component.__class__, component=component)
     component.hydrate()
+    component_hydrated.send(sender=component.__class__, component=component)
     component.complete()
+    component_completed.send(sender=component.__class__, component=component)
     component._validate_called = False
 
     return component
@@ -342,73 +350,61 @@ def mount(self):
         """
         Hook that gets called when the component is first created.
         """
-        pass
 
     def hydrate(self):
         """
         Hook that gets called when the component's data is hydrated.
         """
-        pass
 
     def complete(self):
         """
         Hook that gets called after all component methods are executed.
         """
-        pass
 
     def rendered(self, html):
         """
         Hook that gets called after the component has been rendered.
         """
-        pass
 
     def parent_rendered(self, html):
         """
         Hook that gets called after the component's parent has been rendered.
         """
-        pass
 
     def updating(self, name, value):
         """
         Hook that gets called when a component's data is about to get updated.
         """
-        pass
 
     def updated(self, name, value):
         """
         Hook that gets called when a component's data is updated.
         """
-        pass
 
     def resolved(self, name, value):
         """
         Hook that gets called when a component's data is resolved.
         """
-        pass
 
     def calling(self, name, args):
         """
         Hook that gets called when a component's method is about to get called.
         """
-        pass
 
     def called(self, name, args):
         """
         Hook that gets called when a component's method is called.
         """
-        pass
 
     def pre_parse(self):
         """
         Hook that gets called before the data is parsed and applied to the component.
         """
-        pass
 
     def post_parse(self):
         """
         Hook that gets called after the data is parsed and applied to the component.
         """
-        pass
 
     @timed
     def render(self, *, init_js=False, extra_context=None, request=None, epoch=None) -> str:
@@ -456,10 +452,12 @@ def dispatch(self, request, *args, **kwargs):  # noqa: ARG002
         """
 
         self._mount_result = self.mount()
+        component_mounted.send(sender=self.__class__, component=self)
         if self._mount_result and isinstance(self._mount_result, HttpResponse):
             return self._mount_result
 
         self.hydrate()
+        component_hydrated.send(sender=self.__class__, component=self)
 
         return self.render_to_response(
             context=self.get_context_data(),
@@ -948,6 +946,7 @@ def _get_component_class(module_name: str, class_name: str) -> type[Component]:
 
             # Call hydrate because the component will be re-rendered
             cached_component.hydrate()
+            component_hydrated.send(sender=cached_component.__class__, component=cached_component)
 
             return cached_component
 

src/django_unicorn/signals.py

@@ -0,0 +1,40 @@
+"""
+Django signals for django-unicorn component lifecycle events.
+
+All signals are sent with ``sender=component.__class__`` and at minimum a
+``component`` kwarg containing the live ``UnicornView`` instance.  Connect a
+receiver to observe events without monkey-patching internal methods:
+
+    from django.dispatch import receiver
+    from django_unicorn.signals import component_rendered
+
+    @receiver(component_rendered)
+    def on_render(sender, component, html, **kwargs):
+        print(f"{component.component_name} rendered {len(html)} bytes")
+"""
+
+from django.dispatch import Signal
+
+component_mounted = Signal()
+
+component_hydrated = Signal()
+
+component_completed = Signal()
+
+component_rendered = Signal()
+
+component_parent_rendered = Signal()
+
+component_property_updating = Signal()
+
+component_property_updated = Signal()
+
+component_property_resolved = Signal()
+
+component_method_calling = Signal()
+
+component_method_called = Signal()
+
+component_pre_parsed = Signal()
+
+component_post_parsed = Signal()