feat: Add Groups to composition APIs

Author: mirkobrombin

docs/articles/api/math.md

@@ -44,13 +44,6 @@ Use when performing 2D or 3D transformations in WebGL components.
 3. Combine them via `Mat4.Mul`.
 4. Convert the matrix to a typed array with `js.Float32Array().New(len(mvp))` and upload it via `Context.Call("uniformMatrix4fv", ...)`.
 
-### APIs used
-
-- `Vec2`, `Vec3`
-- `Mat4`, `Identity`, `Translation`, `Scale`, `Perspective`, `Orthographic`
-- `webgl.Context.Call`
-- `js.Float32Array`
-
 ### Notes and Limitations
 
 - Matrices are column-major and use `float32` precision.

docs/articles/api/webgl.md

@@ -120,16 +120,6 @@ if !ctx.Get("createVertexArray").IsUndefined() {
 ctx.DrawElements(webgl.TRIANGLES, 6, webgl.UNSIGNED_SHORT, 0)
 ```
 
-#### APIs used
-
-- `Context.Viewport`
-- `Context.Enable`
-- `Context.DepthFunc`
-- `Context.CreateVertexArray`
-- `Context.BindVertexArray`
-- `Context.DrawElements`
-- constants `ELEMENT_ARRAY_BUFFER`, `DEPTH_TEST`, `UNSIGNED_SHORT`, `NEVER`, `LESS`, `EQUAL`, `LEQUAL`, `GREATER`, `NOTEQUAL`, `GEQUAL`, `ALWAYS`
-
 #### Limitations
 
 - `Context.CreateVertexArray` and `Context.BindVertexArray` require WebGL2 or

docs/articles/essentials/composition.md

@@ -113,15 +113,7 @@ cmp.SetOnMount(func(*core.HTMLComponent) {
 })
 ```
 
-### APIs Used
-
-- `(*core.HTMLComponent).GetRef(name string) dom.Element`
-- `dom.Element.SetHTML(html string)`
-- `dom.Element.AppendChild(child dom.Element)`
-- `composition.Div() *divNode`
-- `(*divNode).Text(t string) *divNode`
-
-### End-to-End Example
+### Example
 
 ```go
 tpl := []byte("<root><div [greet]></div></root>")
@@ -142,6 +134,59 @@ cmp.SetOnMount(func(*core.HTMLComponent) {
 
 - [dom](../api/dom)
 
+## Element Groups
+
+### Context / Why
+
+Handling several nodes created via the composition builders often requires
+manual loops. `Group` collects those nodes and provides helpers to mutate all
+of them at once.
+
+### Prerequisites / When
+
+Use when multiple elements created with constructors need similar updates
+outside the template system.
+
+### How
+
+1. Create an empty group with `composition.NewGroup` or collect nodes with `composition.Group`.
+2. Build nodes with constructors like `Div()` and add them to groups via the `Group` method.
+3. Merge groups with `(composition.Elements).Group` when needed.
+4. Apply bulk operations such as `AddClass`, `SetAttr`, or iterate with `ForEach`.
+
+```go
+import (
+    "github.com/rfwlab/rfw/v1/composition"
+    "github.com/rfwlab/rfw/v1/dom"
+)
+
+cards := composition.Group(
+    composition.Div().Class("card"),
+    composition.Div().Class("card"),
+)
+cards.AddClass("active").SetStyle("color", "red")
+```
+
+### Example
+
+```go
+cards := composition.Group(
+    composition.Div().Text("A"),
+    composition.Div().Text("B"),
+)
+cards.AddClass("card").SetAttr("data-role", "item")
+```
+
+### Notes and Limitations
+
+- `Group` panics when called without nodes.
+- `ForEach` panics if the callback is nil.
+- Selectors and IDs are ignored; pass nodes explicitly.
+
+### Related Links
+
+- [dom](../api/dom)
+
 ## Stores and History
 
 ### Context / Why

docs/articles/guide/pathfinding.md

@@ -32,14 +32,6 @@ path := <-ch
 0 0 0
 ```
 
-### APIs used
-
-- `pathfinding.New`
-- `(*Pathfinder).RequestGridPath`
-- `(*Pathfinder).RequestNavMeshPath`
-- `(*Pathfinder).Cancel`
-- `math.Vec2`
-
 ## Example
 
 Request a navmesh path between polygons:

v1/composition/node.go

@@ -27,6 +27,106 @@ func (e elWrap) Append(nodes ...Node) {
 	}
 }
 
+// Elements groups a collection of DOM elements for bulk operations.
+type Elements struct{ els []dom.Element }
+
+// NewGroup creates an empty Elements collection.
+func NewGroup() *Elements { return &Elements{} }
+
+// Group collects provided nodes into an Elements wrapper without relying on selectors.
+func Group(nodes ...Node) *Elements {
+	if len(nodes) == 0 {
+		panic("composition.Group: no nodes")
+	}
+	g := NewGroup()
+	g.add(nodes...)
+	return g
+}
+
+// Group merges the current group with other groups.
+func (g *Elements) Group(gs ...*Elements) *Elements {
+	for _, other := range gs {
+		if other != nil {
+			g.els = append(g.els, other.els...)
+		}
+	}
+	return g
+}
+
+// ForEach invokes fn for each element in the group.
+func (g *Elements) ForEach(fn func(dom.Element)) {
+	if fn == nil {
+		panic("composition.Elements.ForEach: nil fn")
+	}
+	for _, el := range g.els {
+		fn(el)
+	}
+}
+
+// AddClass adds a class to every element in the group.
+func (g *Elements) AddClass(name string) *Elements {
+	for _, el := range g.els {
+		el.AddClass(name)
+	}
+	return g
+}
+
+// RemoveClass removes a class from every element in the group.
+func (g *Elements) RemoveClass(name string) *Elements {
+	for _, el := range g.els {
+		el.RemoveClass(name)
+	}
+	return g
+}
+
+// ToggleClass toggles a class on every element in the group.
+func (g *Elements) ToggleClass(name string) *Elements {
+	for _, el := range g.els {
+		el.ToggleClass(name)
+	}
+	return g
+}
+
+// SetAttr sets an attribute on every element in the group.
+func (g *Elements) SetAttr(name, value string) *Elements {
+	for _, el := range g.els {
+		el.SetAttr(name, value)
+	}
+	return g
+}
+
+// SetStyle sets an inline style property on every element in the group.
+func (g *Elements) SetStyle(prop, value string) *Elements {
+	for _, el := range g.els {
+		el.SetStyle(prop, value)
+	}
+	return g
+}
+
+// SetText sets the text content of every element in the group.
+func (g *Elements) SetText(t string) *Elements {
+	for _, el := range g.els {
+		el.SetText(t)
+	}
+	return g
+}
+
+// SetHTML replaces the HTML of every element in the group.
+func (g *Elements) SetHTML(html string) *Elements {
+	for _, el := range g.els {
+		el.SetHTML(html)
+	}
+	return g
+}
+
+func (g *Elements) add(nodes ...Node) {
+	for _, n := range nodes {
+		if n != nil {
+			g.els = append(g.els, n.Element())
+		}
+	}
+}
+
 // BindEl invokes fn with a wrapper exposing Clear and Append helpers for the
 // provided element.
 func BindEl(el dom.Element, fn func(El)) {
@@ -111,3 +211,11 @@ func (d *divNode) Text(t string) *divNode {
 	d.el.SetText(t)
 	return d
 }
+
+// Group adds the node to the provided group.
+func (d *divNode) Group(g *Elements) *divNode {
+	if g != nil {
+		g.add(d)
+	}
+	return d
+}

v1/composition/node_test.go

@@ -59,6 +59,42 @@ func TestFor(t *testing.T) {
 	}
 }
 
+func TestGroupForEach(t *testing.T) {
+	cards := NewGroup()
+	Div().Text("a").Group(cards)
+	Div().Text("b").Group(cards)
+
+	var texts []string
+	cards.ForEach(func(el dom.Element) {
+		texts = append(texts, el.Text())
+	})
+
+	if len(texts) != 2 || texts[0] != "a" || texts[1] != "b" {
+		t.Fatalf("unexpected texts %v", texts)
+	}
+}
+
+func TestGroupMerge(t *testing.T) {
+	g1 := Group(Div().Text("a"))
+	g2 := Group(Div().Text("b"))
+	g1.Group(g2)
+
+	var texts []string
+	g1.ForEach(func(el dom.Element) {
+		texts = append(texts, el.Text())
+	})
+
+	if len(texts) != 2 || texts[0] != "a" || texts[1] != "b" {
+		t.Fatalf("unexpected texts %v", texts)
+	}
+}
+
+func TestGroupInvalidArgs(t *testing.T) {
+	assertPanics(t, func() { Group() })
+	cards := Group(Div())
+	assertPanics(t, func() { cards.ForEach(nil) })
+}
+
 func TestDivBuilder(t *testing.T) {
 	d := Div().Class("c").Style("color", "red").Text("hi")
 	el := d.Element()
@@ -72,3 +108,36 @@ func TestDivBuilder(t *testing.T) {
 		t.Fatalf("expected style color red, got %q", v)
 	}
 }
+
+func TestGroupMutators(t *testing.T) {
+	g := Group(Div(), Div())
+
+	g.SetText("hi")
+	g.ForEach(func(el dom.Element) {
+		if el.Text() != "hi" {
+			t.Fatalf("expected text hi")
+		}
+	})
+
+	g.SetHTML("<span>ok</span>")
+	g.AddClass("x").ToggleClass("y").RemoveClass("x")
+	g.SetAttr("data-x", "1").SetStyle("color", "red")
+
+	g.ForEach(func(el dom.Element) {
+		if el.HTML() != "<span>ok</span>" {
+			t.Fatalf("unexpected html %q", el.HTML())
+		}
+		if el.HasClass("x") {
+			t.Fatalf("class x should be removed")
+		}
+		if !el.HasClass("y") {
+			t.Fatalf("expected class y")
+		}
+		if v := el.Attr("data-x"); v != "1" {
+			t.Fatalf("expected attr data-x=1, got %q", v)
+		}
+		if v := el.Get("style").Call("getPropertyValue", "color").String(); v != "red" {
+			t.Fatalf("expected style color red, got %q", v)
+		}
+	})
+}