feat(live): add live UI helpers

Author: GaspardKirira

CMakeLists.txt

@@ -12,7 +12,7 @@ endif()
 set_property(GLOBAL PROPERTY VIX_UI_MODULE_ALREADY_INCLUDED TRUE)
 
 project(ui
-  VERSION 0.2.0
+  VERSION 0.5.0
   DESCRIPTION "Web-first UI and app shell primitives for Vix.cpp applications"
   LANGUAGES CXX
 )
@@ -143,6 +143,11 @@ set(UI_SOURCES
   src/forms/Field.cpp
   src/forms/Form.cpp
 
+  src/live/Fragment.cpp
+  src/live/LiveUpdate.cpp
+  src/live/FlashMessage.cpp
+  src/live/Toast.cpp
+
   src/platform/Platform.cpp
 
   src/shell/ShellConfig.cpp

README.md

@@ -3,24 +3,34 @@
 Web-first UI and app shell primitives for Vix.cpp applications.
 
 `vix::ui` is a small UI foundation layer built on top of the Vix template engine.
-It helps Vix.cpp applications describe views, render HTML responses, manage assets, build simple forms, and prepare future browser, desktop, and mobile app shells.
+It helps Vix.cpp applications describe views, render HTML responses, manage assets, build forms, create live UI fragments, and run server-rendered interfaces inside app shells.
 
 It is not a replacement for `vix::template_`.
 It is a higher-level layer that makes template-based web UI development cleaner.
 
+## Version
+
+Current module version:
+
+```txt
+0.5.0
+```
+
 ## Goals
 
-Vix UI starts with a simple direction:
+Vix UI follows a simple direction:
 
 - keep Vix web-first
 - reuse the existing Vix template engine
 - provide small UI primitives
+- support server-rendered UI first
 - avoid a heavy frontend framework
-- prepare desktop/mobile shells without forcing native UI complexity early
+- prepare desktop/mobile shells through WebView containers
+- make dashboards, admin panels and internal tools easier to build
 
 The first target is server-rendered web UI.
 
-Later, the same web UI foundation can be used by desktop or mobile shells through WebView-based app containers.
+The same UI foundation can then be used by desktop or mobile shells through WebView-based app containers.
 
 ## What it provides
 
@@ -39,9 +49,15 @@ Current primitives:
 - `vix::ui::Field`
 - `vix::ui::Form`
 - `vix::ui::ValidationError`
+- `vix::ui::Fragment`
+- `vix::ui::LiveUpdate`
+- `vix::ui::FlashMessage`
+- `vix::ui::Toast`
 - `vix::ui::Platform`
 - `vix::ui::ShellConfig`
 - `vix::ui::AppShell`
+- `vix::ui::ServerProcess`
+- `vix::ui::ServerReadiness`
 
 ## Basic view example
 
@@ -60,8 +76,7 @@ int main()
   loader->set(
       "home.html",
       "<h1>Hello {{ name }}</h1>"
-      "<p>{{ page_title }}</p>"
-  );
+      "<p>{{ page_title }}</p>");
 
   vix::template_::Engine engine(loader);
 
@@ -93,8 +108,7 @@ attrs.set("class", "card");
 std::string html = vix::ui::Html::tag(
     "div",
     vix::ui::Html::text("Hello <Vix>"),
-    attrs
-);
+    attrs);
 ```
 
 Output:
@@ -108,15 +122,17 @@ Output:
 ```cpp
 #include <vix/ui/html/HtmlResponse.hpp>
 
-vix::ui::HtmlResponse response = vix::ui::HtmlResponse::html("<h1>Hello</h1>", 200);
+vix::ui::HtmlResponse response =
+    vix::ui::HtmlResponse::html("<h1>Hello</h1>", 200);
 
 response.header_content_type(); // text/html; charset=utf-8
 response.body();                // <h1>Hello</h1>
 response.status_code();         // 200
 ```
 
 `HtmlResponse` is transport-neutral.
-It does not depend on a specific HTTP response type. Higher-level Vix integrations can copy its body, status and content type into a real HTTP response.
+
+It does not depend on a specific HTTP response type. Higher-level Vix integrations can copy its body, status, and content type into a real HTTP response.
 
 ## Assets
 
@@ -165,22 +181,120 @@ Validation errors can be attached to the form and to individual fields:
 form.add_error("email", "Email is required.");
 ```
 
+## Live UI fragments
+
+`Fragment` represents a small server-rendered HTML piece.
+
+It can be returned from a route, embedded in a template, or sent through a WebSocket-friendly update payload.
+
+```cpp
+#include <vix/ui/live/Fragment.hpp>
+
+vix::ui::Fragment stats =
+    vix::ui::Fragment::make("dashboard-stats")
+        .set_target("#stats-card")
+        .set_html("<strong>128</strong><span>active users</span>");
+
+std::string html = stats.render();
+std::string wrapped = stats.render_wrapped();
+```
+
+## Live updates
+
+`LiveUpdate` describes how a client should apply a server-rendered fragment.
+
+Supported actions:
+
+- `replace`
+- `append`
+- `prepend`
+- `before`
+- `after`
+- `remove`
+- `none`
+
+```cpp
+#include <vix/ui/live/Fragment.hpp>
+#include <vix/ui/live/LiveUpdate.hpp>
+
+vix::ui::Fragment row =
+    vix::ui::Fragment::make("user-row-42")
+        .set_html("<tr id=\"user-42\"><td>Gaspard</td><td>online</td></tr>");
+
+vix::ui::LiveUpdate update =
+    vix::ui::LiveUpdate::replace("#user-42", row)
+        .set_event("users.updated")
+        .set_id("update-42");
+
+std::string payload = update.to_json();
+```
+
+Example payload:
+
+```json
+{
+  "type": "ui.update",
+  "action": "replace",
+  "target": "#user-42",
+  "event": "users.updated",
+  "id": "update-42",
+  "fragment": "user-row-42",
+  "html": "<tr id=\"user-42\"><td>Gaspard</td><td>online</td></tr>"
+}
+```
+
+## Flash messages
+
+```cpp
+#include <vix/ui/live/FlashMessage.hpp>
+
+vix::ui::FlashMessage flash =
+    vix::ui::FlashMessage::success("Profile updated successfully.")
+        .set_title("Saved")
+        .set_dismissible(true);
+
+std::string html = flash.render();
+```
+
+## Toasts
+
+```cpp
+#include <chrono>
+#include <vix/ui/live/Toast.hpp>
+
+vix::ui::Toast toast =
+    vix::ui::Toast::info("Background sync completed.")
+        .set_title("Sync")
+        .set_position(vix::ui::ToastPosition::BottomRight)
+        .set_timeout(std::chrono::milliseconds(3000));
+
+std::string html = toast.render();
+```
+
 ## App shell
 
-`AppShell` is currently a lightweight shell descriptor.
+`AppShell` is the public shell facade for Vix UI applications.
 
-It stores configuration, validates the shell settings, tracks running/stopped state, and exposes the effective target URL.
+It stores configuration, validates shell settings, can start a local server process, wait for server readiness, and open the configured target URL through the selected backend.
 
 ```cpp
+#include <chrono>
+
 #include <vix/ui/shell/AppShell.hpp>
 #include <vix/ui/shell/ShellConfig.hpp>
 
 vix::ui::ShellConfig config;
 
 config.set_name("Vix Admin")
       .set_title("Vix Admin")
+      .set_app_id("com.vix.admin")
+      .set_app_version("0.5.0")
+      .set_vendor("Vix.cpp")
       .set_host("127.0.0.1")
       .set_port(8080)
+      .set_readiness_url("http://127.0.0.1:8080/health")
+      .set_startup_timeout(std::chrono::milliseconds(5000))
+      .set_wait_for_server(true)
       .set_width(1280)
       .set_height(720);
 
@@ -190,11 +304,11 @@ auto result = shell.start();
 
 if (result.is_ok())
 {
-  // shell.running() == true
+  // shell started
 }
 ```
 
-Native desktop/mobile WebView startup can be added later on top of this public surface.
+When Linux WebView support is enabled, the Linux backend can open the target URL inside a desktop WebView shell.
 
 ## Module structure
 
@@ -225,9 +339,17 @@ include/vix/ui/
     Field.hpp
     ValidationError.hpp
 
+  live/
+    Fragment.hpp
+    LiveUpdate.hpp
+    FlashMessage.hpp
+    Toast.hpp
+
   shell/
     AppShell.hpp
     ShellConfig.hpp
+    ServerProcess.hpp
+    ServerReadiness.hpp
 
   platform/
     Platform.hpp
@@ -239,7 +361,7 @@ include/vix/ui/
 
 ## Build
 
-From the repository root:
+From the module directory or repository workflow:
 
 ```bash
 vix build
@@ -257,6 +379,26 @@ Run examples:
 vix run examples/01_basic_view.cpp
 vix run examples/02_html_response.cpp
 vix run examples/03_assets.cpp
+vix run examples/04_forms.cpp
+vix run examples/06_fragment.cpp
+vix run examples/07_live_update.cpp
+vix run examples/08_flash_and_toast.cpp
+```
+
+Build benchmarks with CMake:
+
+```bash
+vix build --build-target all -v -DUI_BUILD_BENCHMARKS=ON
+```
+
+Run benchmarks:
+
+```bash
+./build-ninja/benchmarks/ui_html_benchmark
+./build-ninja/benchmarks/ui_assets_benchmark
+./build-ninja/benchmarks/ui_forms_benchmark
+./build-ninja/benchmarks/ui_live_benchmark
+./build-ninja/benchmarks/ui_view_context_benchmark
 ```
 
 ## Design direction
@@ -282,10 +424,31 @@ The UI module is responsible for:
 - HTML response data
 - asset helpers
 - form helpers
+- live UI fragments
+- WebSocket-friendly update payloads
+- flash and toast rendering helpers
 - platform/app shell primitives
+- server readiness helpers
 
 This keeps the architecture simple and avoids building a heavy UI framework too early.
 
+## Non-goals
+
+Vix UI is not trying to be:
+
+- a React clone
+- a Flutter clone
+- a Qt replacement
+- a native widget toolkit
+- a complex virtual DOM engine
+- a heavy frontend framework
+
+The direction is:
+
+- server-rendered UI first
+- WebView app shell later
+- native UI only if truly needed
+
 ## License
 
 MIT License.

benchmarks/CMakeLists.txt

@@ -0,0 +1,40 @@
+# ============================================================================
+# UI benchmarks
+# ============================================================================
+
+function(ui_add_benchmark target source)
+  add_executable(${target}
+    ${source}
+  )
+
+  target_compile_features(${target}
+    PRIVATE
+      cxx_std_20
+  )
+
+  target_link_libraries(${target}
+    PRIVATE
+      vix::ui
+      benchmark::benchmark
+      benchmark::benchmark_main
+  )
+
+  if(VIX_ENABLE_SANITIZERS AND NOT MSVC)
+    target_compile_options(${target}
+      PRIVATE
+        -fno-omit-frame-pointer
+        -fsanitize=address,undefined
+    )
+
+    target_link_options(${target}
+      PRIVATE
+        -fsanitize=address,undefined
+    )
+  endif()
+endfunction()
+
+ui_add_benchmark(ui_html_benchmark html_benchmark.cpp)
+ui_add_benchmark(ui_assets_benchmark assets_benchmark.cpp)
+ui_add_benchmark(ui_forms_benchmark forms_benchmark.cpp)
+ui_add_benchmark(ui_live_benchmark live_benchmark.cpp)
+ui_add_benchmark(ui_view_context_benchmark view_context_benchmark.cpp)