Add server realtime

Author: apiad

examples/server_realtime.py

@@ -0,0 +1,37 @@
+from violetear import App, Document
+
+app = App(title="Realtime Fire-and-Forget")
+
+# 1. Server-Side Realtime Handler
+# Receives the message from the client (no return value sent back)
+@app.server.realtime
+async def log_on_server(msg: str):
+    print(f"🔥 SERVER RECEIVED: {msg}")
+
+# 2. Client-Side Callback
+# Must use @app.client.callback to be valid for .on() binding
+@app.client.callback
+async def on_click_ping(event):
+    print("Client: Sending ping to server...")
+
+    # Fire-and-forget call to the server
+    await log_on_server("Hello from the Browser!")
+
+# 3. View with Fluent Syntax + Explicit Event Binding
+@app.view("/")
+def index():
+    doc = Document(title="Realtime Test")
+
+    # Use the context manager to get the ElementBuilder 'e'
+    with doc.body as e:
+        e.h1("Realtime Test")
+        e.p("Open your server terminal to see the logs.")
+
+        # Create the button and chain .on() to bind the event
+        # This passes the function object 'on_click_ping' directly
+        e.button("Send Ping").on("click", on_click_ping)
+
+    return doc
+
+if __name__ == "__main__":
+    app.run()

violetear/app.py

@@ -357,9 +357,33 @@ async def websocket_endpoint(websocket: WebSocket, client_id: str):
             await self.socket_manager.connect(client_id, websocket)
             try:
                 while True:
-                    # Keep the connection alive.
-                    # We can also listen for client-to-server messages here if needed later.
-                    await websocket.receive()
+                    # Listen for messages from the client
+                    message = await websocket.receive_text()
+
+                    try:
+                        data = json.loads(message)
+                    except json.JSONDecodeError:
+                        print(f"[Violetear] ⚠️ Received invalid JSON from client {client_id}")
+                        continue
+
+                    # Dispatch 'realtime' function calls
+                    if data.get("type") == "realtime":
+                        func_name = data.get("func")
+                        args = data.get("args", [])
+                        kwargs = data.get("kwargs", {})
+
+                        if func_name in self.server.realtime_functions:
+                            func = self.server.realtime_functions[func_name]
+
+                            # Execute the function (Fire-and-forget from client perspective)
+                            # We await it here so the server processes it safely within this connection's loop
+                            try:
+                                await func(*args, **kwargs)
+                            except Exception as e:
+                                print(f"[Violetear] ❌ Error executing realtime function '{func_name}': {e}")
+                        else:
+                            print(f"[Violetear] ⚠️ Warning: Client {client_id} tried to call unknown realtime function '{func_name}'")
+
             except (WebSocketDisconnect, RuntimeError):
                 await self.socket_manager.disconnect(client_id)
 

violetear/markup.py

@@ -61,12 +61,82 @@ def _write_line(self, fp, value, indent=0):
         fp.write(value)
 
 
+class ElementBuilder:
+    """
+    Helper class returned by the 'with element as e:' context manager.
+    It allows creating siblings attached to the parent element using a fluent syntax.
+    """
+    def __init__(self, parent: Element):
+        self._parent = parent
+
+        # Register common HTML tags as methods on this instance
+        # This allows: e.div(...), e.h1(...)
+        self.div = self._factory("div")
+        self.section = self._factory("section")
+        self.header = self._factory("header")
+        self.footer = self._factory("footer")
+        self.main = self._factory("main")
+        self.nav = self._factory("nav")
+
+        self.h1 = self._factory("h1")
+        self.h2 = self._factory("h2")
+        self.h3 = self._factory("h3")
+        self.h4 = self._factory("h4")
+        self.h5 = self._factory("h5")
+        self.h6 = self._factory("h6")
+
+        self.p = self._factory("p")
+        self.span = self._factory("span")
+        self.a = self._factory("a")
+        self.img = self._factory("img")
+
+        self.ul = self._factory("ul")
+        self.ol = self._factory("ol")
+        self.li = self._factory("li")
+
+        self.table = self._factory("table")
+        self.thead = self._factory("thead")
+        self.tbody = self._factory("tbody")
+        self.tr = self._factory("tr")
+        self.td = self._factory("td")
+        self.th = self._factory("th")
+
+        self.form = self._factory("form")
+        self.input = self._factory("input")
+        self.button = self._factory("button")
+        self.label = self._factory("label")
+        self.select = self._factory("select")
+        self.option = self._factory("option")
+        self.textarea = self._factory("textarea")
+
+    def tag(self, name: str, *content, **kwargs) -> Element:
+        """
+        Explicitly create a tag that isn't pre-defined.
+        Usage: e.tag("my-custom-component", ...)
+        """
+        el = Element(name, *content, **kwargs)
+        self._parent.add(el)
+        return el
+
+    def _factory(self, tag_name: str):
+        """
+        Internal helper that returns a function to create a specific tag.
+        """
+        def wrapper(*content, **kwargs) -> Element:
+            return self.tag(tag_name, *content, **kwargs)
+
+        # improved debugging representation
+        wrapper.__name__ = tag_name
+        wrapper.__qualname__ = f"ElementBuilder.{tag_name}"
+        return wrapper
+
+
 class Element(Markup):
     def __init__(
         self,
         tag: str,
-        *content: Element,
         text: str | None = None,
+        *content: Element,
         classes: str | List[str] | None = None,
         id: str | None = None,
         style: Style | None = None,
@@ -89,6 +159,20 @@ def __init__(
         self._parent = parent
         self._attrs = attrs
 
+    def __enter__(self) -> ElementBuilder:
+        """
+        Enables the syntax:
+        with doc.body as e:
+            e.h1("Title")
+        """
+        return ElementBuilder(self)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Standard context manager exit.
+        """
+        return False  # Propagate exceptions if they occur
+
     def id(self, id: str) -> Self:
         self._id = id
         return self