feat: improve animations

Author: mirkobrombin

docs/articles/api/animation.md

@@ -1,25 +1,40 @@
 # animation
 
-Helpers for driving simple animations without the Web Animations API.
+Helpers for driving simple animations and for leveraging the Web Animations API.
 
 - `Translate(sel, from, to, dur)` moves elements.
 - `Fade(sel, from, to, dur)` adjusts opacity.
 - `Scale(sel, from, to, dur)` scales elements.
 - `ColorCycle(sel, colors, dur)` cycles background colors.
+- `Keyframes(sel, frames, opts)` runs a Web Animations API sequence and
+  returns the underlying `Animation` object.
 
 ## Usage
 
 Call the animation helpers with a CSS selector, starting and ending values,
 and a duration. They can be invoked from event handlers registered in the DOM.
+`Keyframes` accepts arrays of frame definitions and option maps that are
+passed directly to the browser's `Element.animate` API.
 
 ## Example
 
 ```go
 dom.RegisterHandlerFunc("animateFade", func() {
         anim.Fade("#fadeBox", 1, 0, 500*time.Millisecond)
 })
+
+dom.RegisterHandlerFunc("animateSpin", func() {
+        frames := []map[string]any{
+                {"transform": "rotate(0deg)"},
+                {"transform": "rotate(360deg)"},
+        }
+        opts := map[string]any{"duration": 500, "iterations": 1}
+        anim.Keyframes("#spinBox", frames, opts)
+})
 ```
 
 1. `dom.RegisterHandlerFunc` links the `animateFade` ID to a Go function.
 2. When triggered, `anim.Fade` fades `#fadeBox` from opaque to transparent
    over half a second.
+3. `anim.Keyframes` delegates to the Web Animations API to spin `#spinBox`
+   once around its center.

example/components/animation_component.go

@@ -35,6 +35,17 @@ func NewAnimationComponent() *core.HTMLComponent {
 		colors := []string{"red", "orange", "yellow", "green", "blue", "indigo", "violet"}
 		anim.ColorCycle("#rainbowBox", colors, 700*time.Millisecond)
 	})
+	dom.RegisterHandlerFunc("animateKeyframes", func() {
+		frames := []map[string]any{
+			{"transform": "rotate(0deg)"},
+			{"transform": "rotate(360deg)"},
+		}
+		opts := map[string]any{
+			"duration":   700,
+			"iterations": 1,
+		}
+		anim.Keyframes("#keyframesBox", frames, opts)
+	})
 
 	return c
 }

example/components/templates/animation_component.rtml

@@ -21,5 +21,10 @@
             <div id="rainbowBox" class="w-16 h-16 bg-purple-500"></div>
             <button class="mt-2 bg-purple-500 text-white px-3 py-1 rounded" @click:animateRainbow>Color Cycle</button>
         </div>
+        <div>
+            <h2 class="text-lg font-semibold mb-2">Web Animations API</h2>
+            <div id="keyframesBox" class="w-16 h-16 bg-yellow-500"></div>
+            <button class="mt-2 bg-yellow-500 text-white px-3 py-1 rounded" @click:animateKeyframes>Spin</button>
+        </div>
     </div>
 </root>

v1/animation/animation.go

@@ -38,6 +38,34 @@ func animate(el jst.Value, duration time.Duration, step func(p float64)) {
 	js.RequestAnimationFrame(cb)
 }
 
+// Keyframes leverages the Web Animations API to animate the selected element
+// using the provided keyframes and options. The returned value is the
+// underlying Animation object, allowing further control if needed.
+func Keyframes(sel string, keyframes []map[string]any, options map[string]any) jst.Value {
+        el := query(sel)
+
+        frames := make([]any, len(keyframes))
+        for i, f := range keyframes {
+                frames[i] = f
+        }
+
+        opts := make(map[string]any, len(options))
+        for k, v := range options {
+                switch n := v.(type) {
+                case int:
+                        opts[k] = float64(n)
+                case int32:
+                        opts[k] = float64(n)
+                case int64:
+                        opts[k] = float64(n)
+                default:
+                        opts[k] = v
+                }
+        }
+
+        return el.Call("animate", frames, opts)
+}
+
 // Translate moves the element selected by sel from the starting coordinates
 // to the destination using a translate transform.
 func Translate(sel string, fromX, fromY, toX, toY float64, duration time.Duration) {