diff --git a/docs/site-pages/litestar-guide.html b/docs/site-pages/litestar-guide.html index 8f14b0e..61d5a81 100644 --- a/docs/site-pages/litestar-guide.html +++ b/docs/site-pages/litestar-guide.html @@ -621,13 +621,16 @@

Wiring into Litestar

from litestar import Litestar
 from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.template import TemplateConfig
+from jinjax import Catalog
 from component_framework.adapters.litestar import component_endpoint
-from component_framework.adapters.jinjax_renderer import Jinja2Renderer
+from component_framework.adapters.jinjax_renderer import JinjaxRenderer
 from component_framework.core.component import Component
 
 import components  # registers CounterComponent via @registry.register
 
-Component.renderer = Jinja2Renderer("templates")
+catalog = Catalog()
+catalog.add_folder("templates")
+Component.renderer = JinjaxRenderer(catalog)
 
 app = Litestar(
     route_handlers=[component_endpoint],
@@ -881,11 +884,14 @@ 

Full Example App

component_stream_endpoint, component_websocket_endpoint, ) -from component_framework.adapters.jinjax_renderer import Jinja2Renderer +from jinjax import Catalog +from component_framework.adapters.jinjax_renderer import JinjaxRenderer from component_framework.core.component import Component # Point the renderer at the templates directory -Component.renderer = Jinja2Renderer(Path("examples/litestar_templates")) +catalog = Catalog() +catalog.add_folder(Path("examples/litestar_templates")) +Component.renderer = JinjaxRenderer(catalog) import examples.litestar_components # noqa: F401 — side-effect: registers all components @@ -943,7 +949,6 @@

Testing

from litestar.testing import TestClient from litestar.testing import create_test_client from component_framework.adapters.litestar import component_endpoint -from component_framework.adapters.jinjax_renderer import Jinja2Renderer from component_framework.core.component import Component from tests.fixtures import MockRenderer diff --git a/pyproject.toml b/pyproject.toml index 75efd2c..af10fe2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,6 +39,7 @@ django = [ litestar = [ "litestar>=2.0", "jinja2>=3.1", + "jinjax>=0.41", ] flask = [ "flask>=3.0", diff --git a/src/component_framework/adapters/litestar.py b/src/component_framework/adapters/litestar.py index 2c24579..16ba9b4 100644 --- a/src/component_framework/adapters/litestar.py +++ b/src/component_framework/adapters/litestar.py @@ -70,6 +70,26 @@ def _extract_params(data: dict) -> tuple[dict, str | None, dict, dict | None]: return params, event, payload, state +def _wants_html_response(request: Request) -> bool: + """Return True when the request carries htmx's ``HX-Request`` header. + + This is the standard htmx convention for identifying requests made by + htmx itself, so plain ``hx-post``/``hx-swap`` usage can be served an + HTML fragment instead of the JSON envelope aimed at ``component-client.js``. + """ + return request.headers.get("HX-Request") is not None + + +def _format_html_sse_frame(html: str) -> str: + """Format an HTML fragment as an SSE ``data:`` frame for htmx's SSE extension. + + Per the SSE spec, multi-line data must be sent as one ``data:`` line per + line of content; htmx's ``sse-swap`` then concatenates them back together. + """ + lines = html.split("\n") + return "".join(f"data: {line}\n" for line in lines) + "\n" + + @post("/components/{name:str}") async def component_endpoint(name: str, request: Request) -> Response: """ @@ -101,6 +121,9 @@ async def component_endpoint(name: str, request: Request) -> Response: result["state"] = StateSerializer.serialize(result["state"]) + if _wants_html_response(request): + return Response(content=result["html"], media_type="text/html", status_code=200) + return Response(content=result, media_type="application/json", status_code=200) except HTTPException: @@ -134,13 +157,17 @@ async def stream_component_endpoint(name: str, request: Request) -> Stream: params, event, payload, state = _extract_params(data) component = component_cls(**params) + want_html = _wants_html_response(request) async def event_generator(): async for frame in component.async_stream_dispatch( event=event, payload=payload, state=state ): - frame["state"] = StateSerializer.serialize(frame["state"]) - yield format_sse_frame(frame) + if want_html: + yield _format_html_sse_frame(frame["html"]) + else: + frame["state"] = StateSerializer.serialize(frame["state"]) + yield format_sse_frame(frame) return Stream(event_generator(), media_type="text/event-stream", status_code=200) diff --git a/tests/test_litestar_adapter.py b/tests/test_litestar_adapter.py index ab73216..22485b4 100644 --- a/tests/test_litestar_adapter.py +++ b/tests/test_litestar_adapter.py @@ -146,6 +146,49 @@ def test_form_encoded_event(self, client): assert deserialized["count"] == 7 +# ---------- htmx content negotiation (HX-Request header) ---------- + + +class TestHtmxContentNegotiation: + def test_hx_request_returns_html_fragment(self, client): + """A request carrying HX-Request should get the raw HTML fragment.""" + response = client.post( + "/components/test_counter", + json={"params": {"initial": 5}}, + headers={"HX-Request": "true"}, + ) + assert response.status_code == 200 + assert response.headers["content-type"].startswith("text/html") + assert response.text.startswith("
") + + def test_hx_request_event_returns_html_fragment(self, client): + """HX-Request should also work for event dispatch, not just mount.""" + r1 = client.post("/components/test_counter", json={}) + state = r1.json()["state"] + + r2 = client.post( + "/components/test_counter", + json={"event": "increment", "payload": {"amount": 3}, "state": state}, + headers={"HX-Request": "true"}, + ) + assert r2.status_code == 200 + assert r2.headers["content-type"].startswith("text/html") + assert r2.text.startswith("
") + + def test_no_hx_request_header_keeps_json_envelope(self, client): + """Without HX-Request, the existing JSON envelope must be unchanged.""" + response = client.post( + "/components/test_counter", + json={"params": {"initial": 5}}, + ) + assert response.status_code == 200 + assert response.headers["content-type"].startswith("application/json") + data = response.json() + assert "html" in data + assert "state" in data + assert "component_id" in data + + # ---------- route registration ---------- diff --git a/tests/test_litestar_sse.py b/tests/test_litestar_sse.py index 334c4d0..b757de1 100644 --- a/tests/test_litestar_sse.py +++ b/tests/test_litestar_sse.py @@ -101,3 +101,35 @@ def test_stream_non_streaming_component(self, client): json={"event": "count_up"}, ) assert response.status_code == 400 + + +class TestHtmxStreamContentNegotiation: + def test_hx_request_stream_emits_html_not_json(self, client): + """With HX-Request, each SSE frame should carry raw HTML, not a JSON envelope.""" + response = client.post( + "/components/stream_counter/stream", + json={"event": "count_up", "payload": {"steps": 2}}, + headers={"HX-Request": "true"}, + ) + assert response.status_code == 200 + assert "text/event-stream" in response.headers["content-type"] + + lines = [ln for ln in response.text.strip("\n").split("\n") if ln.startswith("data: ")] + assert len(lines) >= 1 + payloads = [ln.removeprefix("data: ") for ln in lines] + assert any(p.startswith("
") for p in payloads) + # None of the frames should be the JSON envelope from the default path. + for p in payloads: + with pytest.raises((json.JSONDecodeError, AssertionError)): + parsed = json.loads(p) + assert "stream_done" in parsed + + def test_no_hx_request_stream_keeps_json_envelope(self, client): + """Without HX-Request, frames must remain the existing JSON envelope.""" + response = client.post( + "/components/stream_counter/stream", + json={"event": "count_up", "payload": {"steps": 2}}, + ) + lines = [ln for ln in response.text.strip("\n").split("\n") if ln.startswith("data: ")] + frames = [json.loads(ln.removeprefix("data: ")) for ln in lines] + assert all("stream_done" in frame for frame in frames)