docs: (WIP) merge examples and docs projects

Author: mirkobrombin

docs/articles/api/animation.md

@@ -16,25 +16,6 @@ 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
+The following example animates elements using these helpers.
 
-```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.
+@include:ExampleFrame:{code:"/examples/components/animation_component.go", uri:"/examples/animations"}

docs/articles/api/core.md

@@ -29,18 +29,6 @@ For structs embedding `*core.HTMLComponent`, use `core.NewComponentWith(name, tp
 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`.
+The example below shows how core components are composed.
+
+@include:ExampleFrame:{code:"/examples/components/parent_component.go", uri:"/examples/parent"}

docs/articles/api/dom.md

@@ -15,17 +15,6 @@ are available for advanced use:
 Besides the methods shown, the package exposes `RegisterHandlerFunc` to bind
 Go functions to named DOM events.
 
-## Example
+The snippet demonstrates direct DOM interactions.
 
-```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.
+@include:ExampleFrame:{code:"/examples/components/event_component.go", uri:"/examples/event"}

docs/articles/api/events.md

@@ -17,23 +17,6 @@ separate mechanism from DOM events.
 `Listen` turns browser events into Go channels. You can range over the
 channel to react to events concurrently.
 
-## Example
+This example listens for browser events and reacts in Go.
 
-```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.
+@include:ExampleFrame:{code:"/examples/components/event_listener_component.go", uri:"/examples/event/listener"}

docs/articles/api/plugins.md

@@ -20,17 +20,6 @@ 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
+Plugins can hook into the app lifecycle as illustrated here.
 
-```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.
+@include:ExampleFrame:{code:"/examples/plugins/plugins_component.go", uri:"/examples/plugins"}

docs/articles/api/router.md

@@ -11,15 +11,6 @@ Client-side router with lazy loaded components and guards.
 Routes are defined with `router.RegisterRoute` by specifying the path and the
 component to mount. `router.InitRouter` starts the router.
 
-## Example
+Routing parameters are handled as in the following component.
 
-```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.
+@include:ExampleFrame:{code:"/examples/components/another_component.go", uri:"/examples/user/jane"}

docs/articles/api/state.md

@@ -22,50 +22,6 @@ Stores are created with `state.NewStore` and read or updated via `Get` and
 `Set`. Derived values can be defined with `RegisterComputed` or convenience
 helpers like `Map` and `Map2`.
 
-## Example
+State stores drive UI updates in this example.
 
-```go
-if store.Get("double") == nil {
-        state.Map(store, "double", "count", func(v int) int {
-                return v * 2
-        })
-}
-
-func (c *StateManagementComponent) Increment() {
-        if v, ok := c.Store.Get("count").(int); ok {
-                c.Store.Set("count", v+1)
-        }
-}
-```
-
-1. `Map` 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.
-
-### Advanced computed values
-
-`RegisterComputed` provides full control for deriving data from multiple
-dependencies. It accepts a `Computed` definition listing the keys to watch
-and a function that receives their current values in a map. Use it when the
-`Map` helpers are insufficient:
-
-```go
-import "fmt"
-
-if store.Get("profile") == nil {
-        store.RegisterComputed(state.NewComputed(
-                "profile",
-                []string{"first", "last", "age"},
-                func(m map[string]any) any {
-                        first, _ := m["first"].(string)
-                        last, _ := m["last"].(string)
-                        age, _ := m["age"].(int)
-                        return fmt.Sprintf("%s %s (%d)", first, last, age)
-                },
-        ))
-}
-```
-
-This example combines three fields into a single formatted string, but the
-function can perform any transformation and return any type.
+@include:ExampleFrame:{code:"/examples/components/state_management_component.go", uri:"/examples/state"}

docs/articles/guide/animation.md

@@ -7,3 +7,6 @@ anim.Translate("#box", anim.Point{X:0, Y:0}, anim.Point{X:100, Y:0}, time.Second
 ```
 
 Helpers like `Fade`, `Scale` and `ColorCycle` operate on elements selected by CSS selectors.
+This demo animates boxes with helper functions.
+
+@include:ExampleFrame:{code:"/examples/components/animation_component.go", uri:"/examples/animations"}

docs/articles/guide/api-integration.md

@@ -14,3 +14,6 @@ go func() {
 The accompanying example component triggers a fetch to a public API when a button is
 clicked, performing the request in a goroutine so the event loop stays responsive,
 and displays the received data once available.
+It fetches data from an API and renders the result.
+
+@include:ExampleFrame:{code:"/examples/components/api_integration_component.go", uri:"/examples/api"}

docs/articles/guide/complex-routing.md

@@ -13,3 +13,6 @@ router.RegisterRoute(router.Route{
 
 Navigating to `/complex/alice/settings` renders the component with the
 route parameters injected as props, enabling deep links and hierarchies.
+It shows routing with multiple parameters.
+
+@include:ExampleFrame:{code:"/examples/components/complex_routing_component.go", uri:"/examples/complex/jane/profile"}