# SLeeLa `lib/gui` — events, DHTML-style DOM, and scripting
**Revision:** 0.1 · **Family:** `gui`
This is the **backing API** for dynamic SleelaUI interfaces: action callbacks /
`onClick`, a browser-DOM-style document model with live manipulation, and a
small scripting engine that drives it. It extends the original `lib/gui`
integration layer (window / action / 1..14 document watch) without changing its
posture: **SLeeLa owns the meaning of events and owns the document; the host
raises activations and mirrors the DOM onto real SleelaUI widgets.**
## The three sub-layers
### 1. Events & callbacks
| Class | Role |
|---|---|
| `SLGuiEventType` | The event catalogue (`click`, `input`, `change`, `keydown`, `pointerdown`, `submit`, `toggle`, `custom`, …) with stable ordinals and canonical names. |
| `SLGuiEvent` | One dispatched event: type, target id, value/key/pointer payload, plus `preventDefault()` and `stopPropagation()` (exactly like a browser event). |
| `SLGuiHandler` | One registered callback: `(type, target, operation)`, with `once`/`capture`, and the take-the-latch activation `SLGuiAction` uses. |
| `SLGuiEventBus` | The dispatcher: `addListener`/`removeListener`, phase-ordered `dispatch` (capture → target/bubble), `stopPropagation` honoring, `once` sweeping. |
### 2. DHTML-style DOM
| Class | Role |
|---|---|
| `SLGuiNode` | A DOM element: `tag`, `id`, text, parent/children, an attribute map, an inline **style** map, visibility/enabled, and an optional live widget handle. |
| `SLGuiDom` | The document: `createElement`, `getElementById`, `appendChild`, `removeChild`, `setText`/`setAttribute`/`setStyle`, `show`/`hide`, `getElementsByTag`, `querySelectorByAttr`, and `addEventListener` + `onClick`/`onInput`/`onChange`/`onKeyDown`/`onSubmit`. Owns an `SLGuiEventBus`. |
### 3. Scripting
| Class | Role |
|---|---|
| `SLGuiScriptCommand` | One instruction: a verb (`create`, `append`, `text`, `attr`, `style`, `show`, `hide`, `enable`, `on`, `fire`, `call`, `remove`, `nop`) + up to four operands. |
| `SLGuiScript` | The engine: an ordered command list run against an `SLGuiDom`, with the `call` verb crossing the native boundary via `SLGuiBridge`. **Deliberately not a general interpreter** — a bounded, auditable verb list that can do no more than the DOM API already allows. |
## How a callback flows
```
host raises activation ─▶ SLGuiEvent(type, target, value)
│
▼
SLGuiDom.dispatchEvent ─▶ SLGuiEventBus.dispatch
│ (capture → target/bubble, stopPropagation-aware)
▼
matching SLGuiHandlers fire ─▶ bound SLeeLa operation
│
▼
SLeeLa mutates the DOM (setText / setStyle / hide / …)
│
▼
host walks dirty SLGuiNodes ─▶ updates live SleelaUI widgets
```
## Minimal usage
```sleela
SLGuiDom dom = new SLGuiDom(); dom.init();
dom.createRoot("window", "app");
SLGuiNode save = dom.appendElement("app", "button", "save");
save.setText("Save");
dom.onClick("save", "doSave"); // bind a callback
dom.fire(SLGuiEventType.CLICK, "save", ""); // host raises; dispatcher routes it
```
Scripted equivalent:
```sleela
SLGuiScript s = new SLGuiScript(); s.init(dom);
s.create("button", "save", "app");
s.text("save", "Save");
s.on("save", "click", "doSave");
s.fire("save", "click", "");
s.run();
```
A runnable walkthrough of all three sub-layers is
[`lib/gui/version-mual/gui-events-demo.sleela`](lib/gui/version-mual/gui-events-demo.sleela)
(the GUI `.sleela` impl moved to `lib/gui/version-mual/`, copied to `lib/gui/version-gual/`).
## The support structure (DOM ↔ toolkit wiring)
The event/DOM/scripting layer is SLeeLa-owned and host-agnostic. The **support
structure** is the concrete wiring that projects it onto real
[`/lib/user-interface`](../user-interface/) widgets and feeds interactions back:
| Class | Role |
|---|---|
| `SLGuiWidgetFactory` | The one place that maps a node `tag` → a SleelaUI constructor (`uiBox`/`uiButton`/`uiLabel`/`uiEntry`/…) and says which tags are interactive and what event they raise. |
| `SLGuiMount` | The **reconciler**: mounts the DOM depth-first (parent before child), keeps an `id → widget-handle` map, and on each pass applies every **dirty** node's text/visibility/sensitivity/accent/size to its widget, then clears the flag. The SLeeLa→toolkit half. |
| `SLGuiHostAdapter` | Polls each mounted interactive widget's activation latch (`uiWidgetTakeActivated`) and raises the matching `SLGuiEvent` (CLICK/SUBMIT/TOGGLE, carrying the widget's live value) into the bus. The toolkit→SLeeLa half. |
| `SLGuiApp` | The top-level object: opens the app + window, owns the DOM + mount + host adapter + script engine, and runs the loop (**pump → poll activations → mount new nodes → reconcile**). |
```
SLeeLa-owned host / toolkit
┌───────────────┐ reconcile (dirty) ┌──────────────────┐
│ SLGuiDom │ ───── SLGuiMount ───▶ │ SleelaUI widgets │
│ (SLGuiNode) │ │ (ui* built-ins) │
│ SLGuiEventBus │ ◀─── SLGuiHostAdapter ─ (uiWidgetTake- │
└───────────────┘ dispatch events │ Activated) │
▲ └──────────────────┘
│ SLGuiApp owns + runs the loop
```
### Minimal support-structure usage
```sleela
SLGuiApp app = new SLGuiApp();
if (app.boot("com.mearvk.App", "App", 640, 420)) {
SLGuiNode save = app.add("root", "button", "save");
save.setText("Save");
app.onClick("save", "doSave"); // bind a callback
app.run(); // mount, show, loop (poll + reconcile)
}
```
A runnable walkthrough is
[`lib/gui/version-mual/gui-app-demo.sleela`](lib/gui/version-mual/gui-app-demo.sleela).
## Relationship to the toolkit
The DOM nodes name SleelaUI concepts (`window`, `box`, `button`, `label`,
`entry`, …). `SLGuiMount` mounts each node onto the matching
[`/lib/user-interface`](../user-interface/) widget and pushes dirty-node changes
to it; `SLGuiHostAdapter` raises `SLGuiEvent`s when the user interacts. The
event bus and DOM stay the single SLeeLa-owned source of truth, consistent with
the `lib/gui` division of authority.
**SLeeLa — MEARVK LLC — 2026**