feat: add async event handler support (async_dispatch / async_handle_event)

Closes #10 — async def on_* handlers are now properly awaited:
- Component.async_handle_event(): awaits coroutine handlers, works with sync too
- Component.async_dispatch(): async entry point for async adapters
- Component.handle_event(): now raises ComponentError if handler is async
- FastAPI, Litestar, and WebSocket adapters updated to use async_dispatch
- 11 new tests covering async handlers, sync fallback, and error propagation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fsecada01

src/component_framework/adapters/fastapi.py

@@ -58,9 +58,9 @@ async def component_endpoint(name: str, request: Request) -> JSONResponse:
             except Exception as e:
                 raise HTTPException(status_code=400, detail=f"Invalid state: {e}")
 
-        # Create and dispatch component
+        # Create and dispatch component (async to support async on_* handlers)
         component = component_cls(**params)
-        result = component.dispatch(event=event, payload=payload, state=state)
+        result = await component.async_dispatch(event=event, payload=payload, state=state)
 
         # Serialize state for response
         result["state"] = StateSerializer.serialize(result["state"])

src/component_framework/adapters/litestar.py

@@ -60,9 +60,9 @@ async def component_endpoint(name: str, request: Request) -> Response:
             except Exception as e:
                 raise HTTPException(status_code=400, detail=f"Invalid state: {e}")
 
-        # Create and dispatch component
+        # Create and dispatch component (async to support async on_* handlers)
         component = component_cls(**params)
-        result = component.dispatch(event=event, payload=payload, state=state)
+        result = await component.async_dispatch(event=event, payload=payload, state=state)
 
         # Serialize state for response
         result["state"] = StateSerializer.serialize(result["state"])

src/component_framework/core/component.py

@@ -1,5 +1,6 @@
 """Core component base class with lifecycle management."""
 
+import inspect
 import json
 import logging
 from typing import TYPE_CHECKING, Any, ClassVar
@@ -145,21 +146,31 @@ def get_optimistic_patch(self, event: str, payload: dict) -> dict | None:
 
     def handle_event(self, event: str, payload: dict):
         """
-        Route event to handler method.
+        Route event to a **synchronous** handler method.
+
+        For async handlers (``async def on_*``), use :meth:`async_handle_event`
+        instead.  Calling this method with an async handler will raise
+        :class:`ComponentError`.
 
         Args:
             event: Event name (e.g., "increment")
             payload: Event data
 
         Raises:
             EventNotFoundError: If handler not found
-            ComponentError: If handler raises exception
+            ComponentError: If handler raises exception or is async
         """
         handler = getattr(self, f"on_{event}", None)
 
         if not handler:
             raise EventNotFoundError(f"No handler for event: {event}")
 
+        if inspect.iscoroutinefunction(handler):
+            raise ComponentError(
+                f"Handler 'on_{event}' is async — use async_dispatch() or "
+                "async_handle_event() instead of the sync variants."
+            )
+
         try:
             handler(**payload)
         except TypeError as e:
@@ -168,6 +179,35 @@ def handle_event(self, event: str, payload: dict):
             logger.exception(f"Error handling {event} in {self.__class__.__name__}")
             raise ComponentError(f"Error handling {event}") from e
 
+    async def async_handle_event(self, event: str, payload: dict):
+        """
+        Route event to handler, awaiting if the handler is async.
+
+        Works with both ``def on_*`` and ``async def on_*`` handlers.
+
+        Args:
+            event: Event name (e.g., "increment")
+            payload: Event data
+
+        Raises:
+            EventNotFoundError: If handler not found
+            ComponentError: If handler raises exception
+        """
+        handler = getattr(self, f"on_{event}", None)
+
+        if not handler:
+            raise EventNotFoundError(f"No handler for event: {event}")
+
+        try:
+            result = handler(**payload)
+            if inspect.isawaitable(result):
+                await result
+        except TypeError as e:
+            raise ComponentError(f"Invalid payload for {event}: {e}") from e
+        except Exception as e:
+            logger.exception(f"Error handling {event} in {self.__class__.__name__}")
+            raise ComponentError(f"Error handling {event}") from e
+
     # ---------- Rendering ----------
 
     def get_context(self) -> dict:
@@ -209,7 +249,10 @@ def dispatch(
         state: dict | None = None,
     ) -> dict:
         """
-        Main entry point for component execution.
+        Synchronous entry point for component execution.
+
+        For components with ``async def on_*`` handlers, use
+        :meth:`async_dispatch` instead.
 
         Args:
             event: Event name to handle
@@ -244,6 +287,52 @@ def dispatch(
             logger.exception(f"Error in {self.__class__.__name__}.dispatch()")
             raise
 
+    async def async_dispatch(
+        self,
+        event: str | None = None,
+        payload: dict | None = None,
+        state: dict | None = None,
+    ) -> dict:
+        """
+        Async entry point for component execution.
+
+        Works with both sync and async event handlers.  Use this from async
+        adapters (FastAPI, Litestar, WebSocket) to support ``async def on_*``
+        handlers.
+
+        Args:
+            event: Event name to handle
+            payload: Event data
+            state: Serialized state to restore
+
+        Returns:
+            Dict with 'html' and 'state' keys
+        """
+        try:
+            # Lifecycle: mount or hydrate
+            if state:
+                self.hydrate(state)
+            else:
+                self.mount()
+
+            # Handle event if provided
+            if event:
+                await self.async_handle_event(event, payload or {})
+
+            # Render
+            html = self.render()
+
+            return {
+                "html": html,
+                "state": self.dehydrate(),
+                "component_id": self.id,
+                "slots": self.render_slots(),
+            }
+
+        except Exception:
+            logger.exception(f"Error in {self.__class__.__name__}.async_dispatch()")
+            raise
+
 
 class StateSerializer:
     """Handles safe serialization/deserialization of component state."""

src/component_framework/core/websocket.py

@@ -134,10 +134,10 @@ async def _handle_component_event(
             if state_str:
                 state = StateSerializer.deserialize(state_str)
 
-            # Create and dispatch component
+            # Create and dispatch component (async to support async on_* handlers)
             params = {"component_id": component_id}
             component = component_cls(**params)
-            result = component.dispatch(event=event, payload=payload, state=state)
+            result = await component.async_dispatch(event=event, payload=payload, state=state)
 
             # Serialize state
             result["state"] = StateSerializer.serialize(result["state"])

tests/test_component.py

@@ -37,6 +37,28 @@ def before_render(self):
         self.state["doubled"] = self.state.get("value", 0) * 2
 
 
+class AsyncSampleComponent(Component):
+    """Test component with async event handlers."""
+
+    template_name = "async_sample.html"
+
+    def mount(self):
+        super().mount()
+        self.state["value"] = self.params.get("initial", 0)
+
+    async def on_update(self, value: int):
+        self.state["value"] = value
+
+    async def on_failing_event(self):
+        raise ValueError("intentional async error")
+
+    def on_sync_event(self, value: int = 0):
+        self.state["value"] = value
+
+    def before_render(self):
+        self.state["doubled"] = self.state.get("value", 0) * 2
+
+
 # ---------- Component Lifecycle ----------
 
 
@@ -236,3 +258,95 @@ def test_serialize_non_json_types_uses_str(self):
     def test_deserialize_invalid_json_raises(self):
         with pytest.raises(Exception):
             StateSerializer.deserialize("not json")
+
+
+# ---------- Async Event Handling ----------
+
+
+class TestAsyncHandleEvent:
+    @pytest.mark.asyncio
+    async def test_async_handle_event_routes_to_async_handler(self):
+        Component.renderer = MockRenderer()
+        comp = AsyncSampleComponent()
+        comp.mount()
+        await comp.async_handle_event("update", {"value": 99})
+        assert comp.state["value"] == 99
+
+    @pytest.mark.asyncio
+    async def test_async_handle_event_works_with_sync_handler(self):
+        Component.renderer = MockRenderer()
+        comp = AsyncSampleComponent()
+        comp.mount()
+        await comp.async_handle_event("sync_event", {"value": 42})
+        assert comp.state["value"] == 42
+
+    @pytest.mark.asyncio
+    async def test_async_handle_event_missing_handler_raises(self):
+        comp = AsyncSampleComponent()
+        with pytest.raises(EventNotFoundError, match="No handler for event: nonexistent"):
+            await comp.async_handle_event("nonexistent", {})
+
+    @pytest.mark.asyncio
+    async def test_async_handle_event_invalid_payload_raises(self):
+        comp = AsyncSampleComponent()
+        comp.mount()
+        with pytest.raises(ComponentError, match="Invalid payload for update"):
+            await comp.async_handle_event("update", {"wrong_param": 1})
+
+    @pytest.mark.asyncio
+    async def test_async_handle_event_handler_exception_wrapped(self):
+        comp = AsyncSampleComponent()
+        comp.mount()
+        with pytest.raises(ComponentError, match="Error handling failing_event"):
+            await comp.async_handle_event("failing_event", {})
+
+    def test_sync_handle_event_rejects_async_handler(self):
+        comp = AsyncSampleComponent()
+        comp.mount()
+        with pytest.raises(ComponentError, match="is async"):
+            comp.handle_event("update", {"value": 1})
+
+
+# ---------- Async Dispatch ----------
+
+
+class TestAsyncDispatch:
+    def setup_method(self):
+        Component.renderer = MockRenderer()
+
+    @pytest.mark.asyncio
+    async def test_async_dispatch_mount_path(self):
+        comp = AsyncSampleComponent(initial=7)
+        result = await comp.async_dispatch()
+        assert result["state"]["value"] == 7
+        assert result["state"]["doubled"] == 14
+        assert "html" in result
+        assert "component_id" in result
+
+    @pytest.mark.asyncio
+    async def test_async_dispatch_hydrate_path(self):
+        comp = AsyncSampleComponent()
+        result = await comp.async_dispatch(state={"value": 20})
+        assert result["state"]["value"] == 20
+
+    @pytest.mark.asyncio
+    async def test_async_dispatch_with_async_event(self):
+        comp = AsyncSampleComponent()
+        result = await comp.async_dispatch(
+            event="update", payload={"value": 50}, state={"value": 0}
+        )
+        assert result["state"]["value"] == 50
+
+    @pytest.mark.asyncio
+    async def test_async_dispatch_with_sync_event(self):
+        comp = AsyncSampleComponent()
+        result = await comp.async_dispatch(
+            event="sync_event", payload={"value": 77}, state={"value": 0}
+        )
+        assert result["state"]["value"] == 77
+
+    @pytest.mark.asyncio
+    async def test_async_dispatch_event_error_propagates(self):
+        comp = AsyncSampleComponent()
+        with pytest.raises(ComponentError):
+            await comp.async_dispatch(event="nonexistent", state={"value": 0})