A Shared UI Convention for Clojure (Part 3)
Expressing a UI as a function of state is a familiar and useful pattern. But it doesn’t prescribe how controls connect to state, how events are represented, or how changes make it into the next render. Frameworks such as Datastar, Replicant, and Reagent offer different mental models and APIs for these interactions. Moving a UI between them requires rethinking and rewriting the event wiring and state management, especially when moving between server and browser rendering.
What if we could describe those interactions using a shared convention, leaving an adapter to translate them for each framework?
This is part 3 of the Uije experiments (see uije2 for the server-side Datastar version).
An input’s :name identifies its state key; a button’s :name identifies its transient click event. A Hiccup element’s :state can declare changes to carry into the next render. An adapter connects these declarations to the framework’s event and state mechanisms, allowing the same UI convention to work across architectures.
Example: greeting
A tiny example with named inputs and a button:
^:kind/hiccup
[:div {:id "greet"} "Loading..."]Try entering two names and clicking Swap. Each input’s :name binds it to its corresponding state key. The button’s :name becomes the transient :click event; greet-event uses it to swap the values, and greet-ui returns the updated state with its Hiccup tree.
Here is the ClojureScript code for the greet example app:
uije3_example.cljs
(ns scicloj.clay.ideas.uije3-example
(:require [scicloj.clay.ideas.uije3 :as uj]))
(defn greet-ui [{:keys [a b] :as state}]
[:col {:state state}
[:strong (str "Hello: " a ", " b)]
[:row
[:input {:name :a}]
[:input {:name :b}]
[:button {:name :c} "Swap"]]])
(defn greet-event [{:keys [a b click] :as state}]
(cond-> state
(= click :c) (assoc :a b :b a)))
(def greet (comp greet-ui greet-event))
(uj/uije #'greet)For example, with Alice and Bob entered, clicking Swap passes {:a "Alice" :b "Bob" :click :c} to greet-event. It swaps :a and :b, and greet-ui includes the resulting state in the returned Hiccup’s :state attribute. The adapter carries the swapped values forward and consumes :click, so the event is not repeated on the next render.
In the real-world-data meeting, a concern about the earlier Datastar example was that state handling and rendering were not separated. Here, greet composes greet-event, which computes the updated state, with greet-ui, which renders it and includes it in the returned Hiccup. The convention supports this separation, but also allows a single function to handle both when that is more convenient.
The convention
- Named values: an input’s
:namebinds its value to a state key. - Named events: a button’s
:nameidentifies a transient event (for example a:click).
The UI describes these bindings without spelling out framework-specific event wiring. The adapter translates control interactions into state updates and exposes transient events to the UI function.
Describing state changes
To declare a state change, put a map in a Hiccup element’s :state attribute. The adapter collects these maps throughout the tree and merges them into the current state, in tree order, carrying the result into the next render. The UI can therefore declare state changes in the tree it returns, while the adapter handles framework-specific event wiring and carries updates forward.
Updates are partial: keys not mentioned are left unchanged. To reset a key, explicitly associate its new value. Transient entries such as :click are consumed after rendering, even if they appear in a :state patch.
The earlier Datastar example in uije2 uses :data-signals for updates. This prototype uses :state instead, so the convention does not overwrite a valid Datastar attribute. The two examples explore the same idea, but the Datastar adapter would need to move :state to :data-signals.
Everything in this Replicant example runs in the browser, with no server required (unlike uije2).
Example: sine wave
A richer UI with buttons and sliders:
^:kind/hiccup
[:div {:id "sine-wave"} "Loading..."]The ClojureScript code:
uije3_sine_wave.cljs
(ns scicloj.clay.ideas.uije3-sine-wave
(:require [scicloj.clay.ideas.uije3 :as uj]))
(def width 400)
(def height 200)
(def default-state {:amplitude 1 :frequency 2 :phase 0})
(defn wave-path [{:keys [amplitude frequency phase]}]
(let [n 200
points (for [i (range (inc n))]
(let [t (/ i n)
y (* amplitude (Math/sin (+ (* 2 Math/PI frequency t) phase)))]
(str (* t width) "," (* (/ height 2) (- 1 (* 0.9 y))))))]
(str "M" (apply str (interpose " L" points)))))
(defn sine-ui [{:keys [amplitude frequency phase] :as state}]
[:col {:state state}
[:svg {:viewBox (str "0 0 " width " " height)
:style {:width "100%"
:height :auto
:border "1px solid #ccc"}}
[:line {:x1 0 :y1 (/ height 2) :x2 width :y2 (/ height 2) :stroke "#999"}]
[:path {:d (wave-path state) :fill "none" :stroke "#2a7ae2" :stroke-width 2}]]
[:input {:name :amplitude
:type "range" :min 0 :max 1 :step 0.01
:label (str "Amplitude: " amplitude)}]
[:input {:name :frequency
:type "range" :min 1 :max 10 :step 0.1
:label (str "Frequency: " frequency)}]
[:input {:name :phase
:type "range" :min 0 :max 20 :step 0.2
:label (str "Phase: " phase)}]
[:button {:name :reset} "Reset"]])
(defn sine-event [{:keys [click] :as state}]
(if (= click :reset)
default-state
(merge default-state state)))
(def sine-wave (comp sine-ui sine-event))
(uj/uije #'sine-wave)Each slider’s :name binds it to a state key, so changing a slider updates the value used to draw the wave. Reset sends a one-shot event; the UI responds with the default state, which is carried into the next render. The adapter reads range and number inputs as numbers when valid; an empty or invalid number input retains its string value. Text inputs remain strings.
Implementation notes
The translation to Replicant lives in uije3.cljs. It maps named controls and :state declarations onto Replicant’s event and rendering mechanisms; another adapter could connect the same convention to a different framework or architecture.
We need to have replicant loaded in, and to load the cljs files.
^:kind/hiccup
[:div
[:script {:src "https://cdn.jsdelivr.net/npm/scittle-kitchen/dist/dev/scittle.js"}]
[:script {:src "https://cdn.jsdelivr.net/npm/scittle-kitchen/dist/dev/scittle.cljs-devtools.js"}]
[:script {:src "https://cdn.jsdelivr.net/npm/scittle-kitchen/dist/dev/scittle.replicant.js"}]
[:script {:src "uije3.cljs" :type "application/x-scittle"}]
[:script {:src "uije3_example.cljs" :type "application/x-scittle"}]
[:script {:src "uije3_sine_wave.cljs" :type "application/x-scittle"}]]It would be useful to provide a Clojure helper that sets up the target div and the script statements. For now, we are loading them like this to show the concept works.
What this prototype shows
This prototype shows that the convention works in the browser with Replicant. Together with the earlier Datastar example, it explores the same idea in client- and server-rendered settings: a UI declares its bindings and state changes, while an adapter handles the framework-specific wiring.
source: src/scicloj/clay/ideas/uije3.clj