docs: improve api documentation

Author: mirkobrombin

docs/articles/api/animation.md

@@ -6,3 +6,20 @@ Helpers for driving simple animations without the Web Animations API.
 - `Fade(sel, from, to, dur)` adjusts opacity.
 - `Scale(sel, from, to, dur)` scales elements.
 - `ColorCycle(sel, colors, dur)` cycles background colors.
+
+## 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.
+
+## Example
+
+```go
+dom.RegisterHandlerFunc("animateFade", func() {
+        anim.Fade("#fadeBox", 1, 0, 500*time.Millisecond)
+})
+```
+
+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.

docs/articles/api/core.md

@@ -23,3 +23,24 @@ mounted with `app.Mount(component)`.
 
 `core.NewComponent(name, tpl, props)` returns an initialized `*core.HTMLComponent` with the provided template and props.
 For structs embedding `*core.HTMLComponent`, use `core.NewComponentWith(name, tpl, props, self)` to bind lifecycle hooks without manual setup.
+
+## Usage
+
+Components are created with `core.NewComponent` by passing a name, template
+and initial properties. Dependencies are added with `AddDependency`.
+
+## Example
+
+```go
+c := core.NewComponent("MainComponent", mainComponentTpl, nil)
+headerComponent := NewHeaderComponent(map[string]any{
+        "title": "Main Component",
+})
+c.AddDependency("header", headerComponent)
+```
+
+1. `core.NewComponent` instantiates the component with its template.
+2. `NewHeaderComponent` creates a dependency to inject into the main
+   component.
+3. `AddDependency` makes the dependency available in the template under the
+   name `header`.

docs/articles/api/dom.md

@@ -9,3 +9,23 @@ are available for advanced use:
 | `CreateElement(tag)` | Returns a new element. |
 | `ByID(id)` | Fetches an element by id. |
 | `SetInnerHTML(el, html)` | Replaces an element's children with raw HTML. |
+
+## Usage
+
+Besides the methods shown, the package exposes `RegisterHandlerFunc` to bind
+Go functions to named DOM events.
+
+## Example
+
+```go
+dom.RegisterHandlerFunc("increment", func() {
+        if val, ok := c.Store.Get("count").(int); ok {
+                c.Store.Set("count", val+1)
+        }
+})
+```
+
+1. `dom.RegisterHandlerFunc` associates the `increment` identifier with a
+   function.
+2. When called from the DOM, the function reads `count` from the store and
+   increments it.

docs/articles/api/events.md

@@ -11,3 +11,29 @@ Utilities for observing browser events and DOM mutations.
 `Listen` converts native DOM events into Go channels. For application
 state changes use reactive stores which emit their own notifications – a
 separate mechanism from DOM events.
+
+## Usage
+
+`Listen` turns browser events into Go channels. You can range over the
+channel to react to events concurrently.
+
+## Example
+
+```go
+btn := js.Document().Call("getElementById", "clickBtn")
+ch := events.Listen("click", btn)
+go func() {
+        for range ch {
+                switch v := cmp.Store.Get("clicks").(type) {
+                case float64:
+                        cmp.Store.Set("clicks", v+1)
+                case int:
+                        cmp.Store.Set("clicks", float64(v)+1)
+                }
+        }
+}()
+```
+
+1. Obtain the button from the DOM.
+2. `events.Listen` creates a channel that receives clicks on the button.
+3. A goroutine increments the store whenever an event arrives.

docs/articles/api/plugins.md

@@ -13,3 +13,24 @@ type Plugin interface {
 Plugins are registered with `app.Use(...)` before compiling the WASM
 bundle. During `Setup` they can register components, add routes or inject
 scripts.
+
+## Usage
+
+Plugins must be registered before the application starts using
+`core.RegisterPlugin` or `app.Use`. During `Setup` they can modify the app or
+add features.
+
+## Example
+
+```go
+core.RegisterPlugin(logger.New())
+core.RegisterPlugin(i18n.New(map[string]map[string]string{
+        "en": {"hello": "Hello"},
+        "it": {"hello": "Ciao"},
+}))
+core.RegisterPlugin(mon.New())
+```
+
+1. Multiple plugins are registered before the app starts.
+2. The `logger` plugin intercepts logs while `i18n` provides translations.
+3. `mon.New()` installs an additional monitoring plugin.

docs/articles/api/router.md

@@ -5,3 +5,21 @@ Client-side router with lazy loaded components and guards.
 - `RegisterRoute(Route)` adds a route definition.
 - `Navigate(path)` programmatically changes the URL.
 - Guards: `Guard` functions run before navigation and can cancel by returning `false`.
+
+## Usage
+
+Routes are defined with `router.RegisterRoute` by specifying the path and the
+component to mount. `router.InitRouter` starts the router.
+
+## Example
+
+```go
+router.RegisterRoute(router.Route{
+        Path: "/",
+        Component: func() core.Component { return components.NewMainComponent() },
+})
+router.InitRouter()
+```
+
+1. `RegisterRoute` associates the root path with the main component.
+2. `InitRouter` listens for URL changes and renders the current route.

docs/articles/api/state.md

@@ -13,3 +13,32 @@ Centralized reactive data stores.
 Stores are the primary mechanism for application state. They emit
 notifications to any component that reads their values, keeping most apps
 free of handwritten JavaScript.
+
+## Usage
+
+Stores are created with `state.NewStore` and read or updated via `Get` and
+`Set`. Derived values can be defined with `RegisterComputed`.
+
+## Example
+
+```go
+if store.Get("double") == nil {
+        store.RegisterComputed(state.NewComputed("double", []string{"count"}, func(m map[string]any) any {
+                if v, ok := m["count"].(int); ok {
+                        return v * 2
+                }
+                return 0
+        }))
+}
+
+func (c *StateManagementComponent) Increment() {
+        if v, ok := c.Store.Get("count").(int); ok {
+                c.Store.Set("count", v+1)
+        }
+}
+```
+
+1. `RegisterComputed` defines the derived value `double` based on `count`.
+2. The `Increment` function reads `count` and updates it with `Set`.
+3. Each change automatically updates parts of the UI that depend on these
+   values.