chore: Refactor DOM API for typed wrappers

Author: mirkobrombin

docs/articles/api/dom.md

@@ -1,11 +1,26 @@
 # dom
 
 Low level DOM helpers used by the framework. Most applications interact
-with the DOM indirectly through components, but the following utilities
-are available for advanced use:
+with the DOM indirectly through components.
+
+## Context
+
+These helpers allow fine-grained control over the browser DOM without
+relying on `syscall/js` directly.
+
+## Prerequisites
+
+Use these APIs when components need to manipulate elements that are not
+handled by the template system.
+
+## API
+
+Both function helpers and typed wrappers are available. The functions
+delegate to the wrappers for backward compatibility:
 
 | Function | Description |
 | --- | --- |
+| `Doc()` | Returns the global `Document`. |
 | `CreateElement(tag)` | Returns a new element. |
 | `ByID(id)` | Fetches an element by id. |
 | `Query(sel)` | Returns the first element matching the CSS selector. |
@@ -17,8 +32,12 @@ are available for advanced use:
 | `SetText(el, text)` | Sets an element's text content. |
 | `Attr(el, name)` | Retrieves the value of an attribute. |
 | `SetAttr(el, name, value)` | Sets the value of an attribute. |
+| `SetStyle(el, prop, value)` | Sets an inline style property. |
+| `StyleInline(map)` | Builds a style string from CSS properties. |
 | `AddClass(el, name)` | Adds a class to an element. |
 | `RemoveClass(el, name)` | Removes a class from an element. |
+| `HasClass(el, name)` | Reports whether an element has a class. |
+| `ToggleClass(el, name)` | Toggles a class on an element. |
 | `ScheduleRender(id, html, delay)` | Updates a component after a delay. |
 | `UpdateDOM(id, html)` | Patches a component's DOM with raw HTML. |
 | `TemplateHook` | Callback invoked after `UpdateDOM`. |
@@ -38,14 +57,36 @@ Go functions to named DOM events.
 
 ### Selecting and modifying elements
 
-```go
-title := dom.Query("h1")
-dom.SetText(title, "Hello")
-dom.AddClass(title, "highlight")
-```
+1. Obtain the document wrapper.
+   ```go
+   doc := dom.Doc()
+   ```
+2. Query and update elements with typed methods.
+   ```go
+   title := doc.Query("h1")
+   title.SetText("Hello")
+   title.AddClass("highlight")
+   title.SetAttr("lang", "en")
+   title.SetStyle("color", "red")
+
+   box := doc.CreateElement("div")
+   box.SetAttr("style", dom.StyleInline(map[string]string{"display": "flex", "gap": "4px"}))
+
+   items := doc.QueryAll("li")
+   for i := 0; i < items.Length(); i++ {
+       items.Index(i).ToggleClass("active")
+   }
+   ```
 
 The snippet demonstrates direct DOM interactions.
 
+`QueryAll` returns a collection exposing `Length` and `Index` to walk matched elements.
+
+### Migration
+
+Legacy helpers such as `dom.Query` and `dom.SetText` continue to work and
+delegate to the new methods for compatibility.
+
 @include:ExampleFrame:{code:"/examples/components/event_component.go", uri:"/examples/event"}
 
 ### Delayed updates
@@ -76,16 +117,20 @@ directives. When building elements yourself, call the bind helpers
 explicitly:
 
 ```go
-import "github.com/rfwlab/rfw/v1/state"
+import (
+    "github.com/rfwlab/rfw/v1/dom"
+    "github.com/rfwlab/rfw/v1/state"
+)
 
-el := dom.CreateElement("div")
-dom.SetInnerHTML(el, `<input value="@store:user.name:w">`)
-dom.BindStoreInputs(el)
+doc := dom.Doc()
+el := doc.CreateElement("div")
+el.SetHTML(`<input value="@store:user.name:w">`)
+dom.BindStoreInputs(el.Value)
 
 nameSig := state.NewSignal("")
 dom.RegisterSignal("cmp", "name", nameSig)
-dom.SetInnerHTML(el, `<input value="@signal:name:w">`)
-dom.BindSignalInputs("cmp", el)
+el.SetHTML(`<input value="@signal:name:w">`)
+dom.BindSignalInputs("cmp", el.Value)
 ```
 
 ### Virtual lists
@@ -104,3 +149,12 @@ list := virtual.NewVirtualList("list", 1000, 24, func(i int) string {
 ```html
 <div id="list" style="height:200px; overflow-y:auto"></div>
 ```
+
+### Notes and limitations
+
+Only common operations are wrapped. For unsupported features, use the
+`dom` helpers or the lower level `js` package cautiously.
+
+### Related links
+
+- [js](js.md)

docs/articles/api/events.md

@@ -25,7 +25,8 @@ emit their own notifications – a separate mechanism from DOM events.
 `On` attaches a handler and provides a cleanup function:
 
 ```go
-stop := events.OnClick(dom.ByID("btn"), func(evt js.Value) {
+doc := dom.Doc()
+stop := events.OnClick(doc.ByID("btn").Value, func(evt js.Value) {
         js.Console().Call("log", "clicked")
 })
 // ...

docs/articles/api/webgl.md

@@ -81,8 +81,9 @@ ctx.UseProgram(prog)
 ### Loading a texture
 
 ```go
-img := dom.ByID("img")
-tex := ctx.LoadTexture2D(img)
+doc := dom.Doc()
+img := doc.ByID("img")
+tex := ctx.LoadTexture2D(img.Value)
 ctx.ActiveTexture(webgl.TEXTURE0)
 ctx.BindTexture(webgl.TEXTURE_2D, tex)
 ```
@@ -105,8 +106,9 @@ Use when drawing geometry that shares vertices or requires depth ordering.
 4. Render with `Context.DrawElements`.
 
 ```go
-canvas := dom.ByID("canvas")
-ctx := webgl.NewContextFrom(canvas)
+doc := dom.Doc()
+canvas := doc.ByID("canvas")
+ctx := webgl.NewContextFrom(canvas.Value)
 ctx.Viewport(0, 0, canvas.Get("width").Int(), canvas.Get("height").Int())
 ctx.Enable(webgl.DEPTH_TEST)
 ctx.DepthFunc(webgl.LEQUAL)

docs/articles/essentials/event-handling.md

@@ -44,7 +44,8 @@ Example:
 Handlers can also be registered from Go code using the `events` package:
 
 ```go
-stop := events.OnClick(dom.ByID("save"), func(evt js.Value) {
+doc := dom.Doc()
+stop := events.OnClick(doc.ByID("save").Value, func(evt js.Value) {
         // handle click
 })
 defer stop()