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 @@
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)