refactor(website): Improve documentation clarity and update state management examples

Author: CarLeonDev

website/public/opengraph.png

@@ -49,7 +49,7 @@ la cual encapsula los datos y el comportamiento de un estado particular, y propo
 
 ### Metodos del estado
 
-<HT>[`RtState`](/reactter/api/classes/rt_state)</HT> clase proporciona algunos métodos para la gestión de estados. Conozcámoslos:
+La clase <HT>[`RtState`](/reactter/api/classes/rt_state)</HT> proporciona algunos métodos para la gestión de estados. Conozcámoslos:
 
 <StateMethods />
 

website/src/content/docs/es/core_concepts/state_management.mdx

@@ -0,0 +1,156 @@
+---
+title: Vinculación del estado a la dependencia
+description: Aprende a vincular un estado a una dependencia en Reactter para una gestión de estado más eficiente y reactiva.
+---
+
+import { Code } from "@astrojs/starlight/components";
+import { HE, HK, HM, HN, HS, HT } from '@/components/Highlight';
+
+:::tip
+Este guía asume que ya has leído sobre [Inyección de dependencias](/reactter/es/core_concepts/dependency_injection) y [Gestión del estado](/reactter/es/core_concepts/state_management).
+Se recomienda leer eso primero si eres nuevo en Reactter.
+:::
+
+Un estado de Reactter(<HT>[`RtState`](/reactter/es/core_concepts/state_management/#state)</HT>) como <HT>[`Signal`](/reactter/es/api/classes/signal)</HT> o cualquier <HT>[`Hooks`](/reactter/es/core_concepts/hooks)</HT> puede ser vinculado a la dependencia, permitiendo que el estado sea manipulado directamente desde la dependencia y notificar a sus oyentes sobre cualquier cambio.
+Además, asegura que el estado se elimine automáticamente cuando la dependencia ya no sea necesaria.
+
+Al integrar el estado directamente dentro de las dependencias, se beneficia de un **código más limpio** y **mantenible**.
+El manejo automático por parte de Reactter significa **menos código repetitivo** y **menos errores* relacionados con la gestión manual del estado, lo que conduce a un proceso de desarrollo más eficiente.
+Este enfoque **simplifica** la sincronización entre el estado y su dependencia asociada, **mejorando la capacidad de respuesta** y la **fiabilidad** general de su aplicación.
+
+### Vinculación automática
+
+Para que esto suceda automáticamente, el estado debe declararse como propiedad o dentro del constructor de la dependencia.
+Cuando se hace esto, Reactter se encarga automáticamente de vincular el estado a la dependencia, asegurando una gestión y reactividad del estado sin problemas, por ejemplo:
+
+```dart title="count_controller.dart" "UseState" "UseEffect"
+import "package:reactter/reactter.dart";
+
+class CountController {
+  // Estado declarado como propiedad
+  final uCount = UseState(0);
+
+  CountController() {
+    // Estado declarado dentro del constructor
+    UseEffect(() {
+      print("Count: ${uCount.value}");
+    }, [uCount]);
+  }
+}
+```
+
+En el ejemplo anterior, el estado `uCount` se declara como propiedad de la clase <HT>`CountController`</HT> y el hook <HT>`UseEffect`</HT> se utiliza dentro del constructor para reaccionar a los cambios en el estado `uCount`, imprimiendo su valor cada vez que cambia.
+Esto vincula automáticamente el estado `uCount` y el hook <HT>`UseEffect`</HT> a la instancia de <HT>`CountController`</HT>, demostrando cómo Reactter maneja la vinculación y reactividad de forma transparente.
+
+:::caution
+Si el estado se declara de forma perezosa (por ejemplo, utilizando la palabra clave <HK>`late`</HK>), no se vinculará automáticamente a la dependencia.
+En tales casos, debes usar el método <HT>`Rt.lazyState`</HT> para vincular el estado a la dependencia(Ver [vinculación perezoso](#vinculación-perezosa)).
+:::
+
+### Vinculación perezosa
+
+Cuando un estado se declara de forma perezosa, no se vincula automáticamente a la dependencia.
+En tales casos, puedes usar el método <HT>[`Rt.lazyState`](/reactter/es/api/methods/state_management_methods/#rtlazy_state)</HT> para vincular el estado a la dependencia, por ejemplo:
+
+```dart title="count_controller.dart" "UseState" "Rt.lazyState"
+import "package:reactter/reactter.dart";
+
+class CountController {
+  final int initialCount;
+
+  late final uCount = Rt.lazyState(
+    () => UseState(this.initialCount),
+    this,
+  );
+
+  CountController([this.initialCount = 0]) {
+    UseEffect(() {
+      print("Count: ${uCount.value}");
+    }, [uCount]);
+  }
+}
+```
+
+En el ejemplo anterior, el estado `uCount` se declara de forma perezosa utilizando la palabra clave <HK>`late`</HK>.
+Para vincular el estado a la instancia de <HT>`CountController`</HT>, se utiliza el método <HT>[`Rt.lazyState`](/reactter/es/api/methods/state_management_methods/#rtlazy_state)</HT>, pasando la función de creación del estado y la instancia de la dependencia como argumentos.
+Esto asegura que cuando se accede a `uCount`, se vinculará automáticamente a la instancia de <HT>`CountController`</HT>.
+
+### Vinculación manual
+
+Si bien la vinculación automática simplifica la gestión del estado, puede haber escenarios en los que necesites vincular manualmente el estado a una dependencia.
+La vinculación manual proporciona un mayor control sobre cómo y cuándo se asocia el estado con la dependencia.
+
+Para vincular manualmente un estado a una dependencia, debes vincular explícitamente el estado dentro de la dependencia utilizando el método <HM>`bind`</HM> del estado, por ejemplo:
+
+```dart title="count_controller.dart" "UseState" "bind"
+class CountController {
+  late final uCount = UseState(this.initialCount);
+
+  final int initialCount;
+
+  CountController([this.initialCount = 0]) {
+    count.bind(this);
+  }
+}
+```
+
+En el ejemplo anterior, el estado `uCount` se declara de forma perezosa utilizando la palabra clave <HK>`late`</HK>.
+Para vincular el estado a la instancia de <HT>`CountController`</HT>, se utiliza el método <HM>`bind`</HM> del estado, pasando la instancia de la dependencia como argumento.
+Esto asegura que el estado `uCount` esté asociado a la instancia de <HT>`CountController`</HT>, lo que permite que la dependencia actualice reactivamente en función de los cambios en el estado.
+
+:::note
+La [vinculación manual](#vinculación-manual) y [vinculación perezosa](#vinculación-perezosa) tienen propositos diferentes.
+La vinculación manual es útil cuando se necesita un control preciso sobre el proceso de vinculación de estados, mientras que la **vinculación perezosa** es adecuada cuando se desea que el estado se inicialice sólo cuando se accede a él por primera vez.
+Elige el método adecuado en función de tus necesidades específicas.
+:::
+
+### Desvinculación automática
+
+Cuando se elimina una dependencia, el estado asociado se elimina automáticamente.
+Este mecanismo de desvinculación automática simplifica la gestión de estados y reduce el riesgo de fugas de memoria o desperdicio de recursos.
+
+En el ejemplo siguiente, el estado `uCount` se elimina automáticamente cuando se borra la instancia <HT>`CountController`</HT>, lo que garantiza que los recursos se liberan de forma eficiente:
+
+```dart title="main.dart" "Rt.create" "Rt.delete"
+import "./count_controller.dart";
+
+void main() {
+  final controller = Rt.create(() => CountController(10));
+  controller.uCount.value += 2; // Count: 12
+  Rt.delete<CountController>();
+  controller.uCount.value += 3; // Error: "Can't update when it's been disposed"
+}
+```
+
+### Desvinculación manual
+
+En algunos casos, puede que necesites desvincular manualmente un estado de una dependencia.
+La desvinculación manual proporciona un mayor control sobre cuándo se libera el estado y puede ser útil en escenarios en los que se desea desvincular el estado de forma temporal o permanente.
+
+Para desvincular manualmente un estado de una dependencia, puedes utilizar el método <HM>`unbind`</HM> del estado, por ejemplo:
+
+```dart title="count_controller.dart" "UseState" "unbind"
+class CountController {
+  late final uCount = UseState(this.initialCount);
+
+  final int initialCount;
+
+  CountController([this.initialCount = 0]) {
+    count.bind(this);
+  }
+
+  void dispose() {
+    count.unbind(this);
+  }
+}
+```
+
+:::caution
+Aunque la desvinculación manual proporciona un mayor control, un uso inadecuado puede provocar problemas de gestión de memoria y aumentar el riesgo de errores.
+Se recomienda utilizar la [desvinculación automática](#desvinculación-automática) siempre que sea posible, ya que simplifica el proceso y reduce la probabilidad de introducir fugas de memoria o de no liberar los recursos correctamente.
+
+La desvinculación manual debe utilizarse con precaución y sólo cuando sea absolutamente necesario.
+Además, los desarrolladores deben asegurarse de realizar un seguimiento del proceso de desvinculación para evitar dejar estados no utilizados en memoria, lo que podría afectar negativamente al rendimiento y la utilización de recursos.
+:::
+
+

website/src/content/docs/es/extra_topics/binding_state_to_dependency.mdx

@@ -0,0 +1,169 @@
+---
+title: Actualizar objectos en estado
+description: Aprende a actualizar objectos en estado de Reactter.
+---
+import { HM, HN, HS, HT } from '@/components/Highlight';
+
+Un estado de Reactter(<HT>`RtState`</HT>) como <HT>`Signal`</HT>, <HT>`UseState`</HT>, <HT>`UseAsyncState`</HT>, <HT>`UseReducer`</HT> y <HT>`UseCompute`</HT> pueden contener cualquier tipo de valor de Dart, incluidos objetos.
+Sin embargo, no debes modificar los objetos contenidos en el estado de Reactter directamente.
+
+En esta guía, aprenderás cómo actualizar objetos de forma segura y efectiva en un estado Reactter.
+
+## ¿Qué es una mutación?
+
+Puedes almacenar cualquier tipo de valor de Dart en el estado.
+
+```dart showLineNumbers=false
+final count = Signal(0);
+```
+
+Hasta ahora has estado trabajando con números, cadenas y booleanos.
+Estos tipos de valores de Dart son _**inmutables**_, lo que significa que no se pueden cambiar o son _**de solo lectura**_.
+Puedes desencadenar una nueva representación para reemplazar un valor:
+
+```dart showLineNumbers=false
+count.value = 2;
+```
+
+El estado `count` cambió de <HN>`0`</HN> a <HN>`2`</HN>, pero el número <HN>`0`</HN> en sí mismo no cambió.
+No es posible realizar cambios en los valores primitivos incorporados como números, cadenas y booleanos en Dart.
+
+Ahora considera un objeto en un estado:
+
+```dart showLineNumbers=false collapse={1-7}
+class User {
+  String name;
+  int age;
+
+  User({required this.name, required this.age});
+}
+
+final user = Signal(User(name: "Jane Doe", age: 25));
+```
+
+Tecnicamente, es posible cambiar el contenido del objeto en sí. Esto se llama una **mutación**:
+
+```dart showLineNumbers=false
+user.value.name = "John Doe";
+```
+
+Sin embargo, aunque los objetos en el estado de Reactter son técnicamente mutables, debes tratarlos como si fueran inmutables, como números, booleanos y cadenas.
+En lugar de mutarlos, siempre debes reemplazarlos.
+
+## Tratar el estado como de solo lectura
+
+En otras palabras, debes tratar cualquier objeto de Dart que pongas en el estado como de solo lectura.
+
+El siguiente ejemplo mantiene un objeto en el estado para representar al usuario.
+El nombre del usuario se cambia de <HS>`"Jane Doe"`</HS> a <HS>`"John Doe"`</HS> cuando haces clic en el botón,
+pero el nombre del usuario sigue siendo el mismo.
+
+```dart title="main.dart" "Signal" "User" "RtSignalWatcher" "user.value.name" "user.value.age" "user" mark={31}
+import 'package:flutter/material.dart';
+import 'package:reactter/reactter.dart';
+
+void main() {
+  runApp(MyApp());
+}
+
+class User {
+  String name;
+  int age;
+
+  User({required this.name, required this.age});
+}
+
+final user = Signal(User(name: "Jane Doe", age: 25));
+
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(title: Text("Inmutable state example")),
+        body: Center(
+          child: RtSignalWatcher((){
+            return Column(
+              children: [
+                Text('Name: ${user.value.name}'),
+                Text('Age: ${user.value.age}'),
+                ElevatedButton(
+                  onPressed: () {
+                    user.value.name = "John Doe";
+                  },
+                  child: Text("Change Name"),
+                ),
+              ],
+            );
+          }),
+        ),
+      ),
+    );
+  }
+}
+```
+
+El problema está en este fragmento de código.
+
+```dart startLineNumber=24
+user.value.name = "John Doe";
+```
+
+Este código modifica el objeto asignado a un nuevo `name` cuando se hace clic en el botón
+pero no desencadena un nuevo renderizado porque el objeto en sí no ha cambiado.
+La propiedad `name` del objeto ha cambiado, pero el objeto en sí no lo ha hecho.
+Y Reactter no sabe que el objeto ha cambiado porque sigue siendo el mismo objeto.
+Aunque la mutación del estado puede funcionar en algunos casos, no lo recomendamos.
+Debes tratar el valor de estado al que tienes acceso como de solo lectura.
+
+Para desencadenar un nuevo renderizado en este caso, crea un nuevo objeto y pásalo a la función de configuración del estado:
+
+```dart startLineNumber=24
+user.value = User(name: "John Doe", age: user.value.age);
+```
+
+Cunado `value` se establece en un nuevo objeto, Reactter sabe que el estado ha cambiado y desencadena un nuevo renderizado.
+
+## Copiar objetos
+
+En el ejemplo anterior, creaste un nuevo objeto con el mismo `age` y un `name` diferente.
+Pero ¿qué pasa si quieres cambiar el `age` y mantener el `name` igual?. También puedes hacerlo:
+
+```dart showLineNumbers=false
+user.value = User(name: user.value.name, age: 30);
+```
+
+Esto es un patrón común cuando trabajas con objetos en el estado.
+Sin embargo, crear un nuevo objeto cada vez que quieras cambiar una propiedad puede ser tedioso.
+Para simplificar este proceso, puedes agregar el siguiente método(<HM>`copyWith`</HM>) a la clase <HT>`User`</HT>:
+
+```dart collapse={2-6} ins="final" ins={7-13} mark={2-3} mark="copyWith"
+class User {
+  final String name;
+  final int age;
+
+  const User({required this.name, required this.age});
+
+  User copyWith({String? name, int? age}) {
+    return User(
+      name: name ?? this.name,
+      age: age ?? this.age,
+    );
+  }
+}
+```
+
+Este método crea un nuevo objeto con las mismas propiedades que el objeto original, excepto por las propiedades que especifiques.
+Puedes usar este método para crear un nuevo objeto con el mismo `name` y un `age` diferente:
+
+```dart showLineNumbers=false ".copyWith"
+user.value = user.value.copyWith(age: 30);
+```
+
+## Resumen
+
+- Trata los objetos en el estado como de solo lectura.
+- Cuando necesites actualizar un objeto, crea uno nuevo o haz una copia del objeto existente, y luego establece el estado para usar este nuevo o copiado objeto.
+- Evita mutar objetos en el estado directamente.
+- Crea un nuevo objeto y pásalo a la función de configuración del estado para desencadenar un nuevo renderizado.
+- Usa el método <HM>`copyWith`</HM> para crear un nuevo objeto con las mismas propiedades que el objeto original, excepto por las propiedades que especifiques.

website/src/content/docs/es/extra_topics/updating_objects_in_state.mdx

@@ -11,7 +11,7 @@ Esto ha dado lugar a una amplia variedad de paquetes de gestión de estado, cada
 
 **Reactter** nació del deseo de crear algo diferente, una solución de gestión de estados que no se limita a resolver problemas, sino que eleva toda la experiencia de desarrollo.
 Inspirado en la simplicidad y reactividad de ReactJS, Reactter aporta un enfoque fresco y moderno al desarrollo con Dart y Flutter.
-No es sólo otro paquete de gestión de estado, es un framework completo, diseñado para hacer su aplicación más rápida, su código más limpio y su vida como desarrollador más fácil.
+No es sólo otro paquete de gestión de estado, es una herramienta potente, diseñado para hacer su aplicación más rápida, su código más limpio y su vida como desarrollador más fácil.
 
 ¿Qué diferencia a Reactter? Mientras que otros paquetes se centran únicamente en la gestión de estados, Reactter va más allá integrando a la perfección **inyección de dependencias**, **manejo de eventos** y **control de renderizado** en un único framework cohesionado.
 Es ligero pero potente, sencillo pero flexible, y está diseñado para funcionar a la perfección con cualquier arquitectura o patrón.

website/src/content/docs/es/overview.mdx

@@ -11,7 +11,7 @@ Cuando se invoca, emite dos eventos [lifecycle](/reactter/es/core_concepts/lifec
 A diferencia de <HM>`update`</HM>, sólo emite el evento <HE>`Lifecycle.didUpdate`</HE>, ya que no implica ningún paso previo a la notificación.
 - <HM>**`bind`**</HM>: Establece una conexión entre el estado y una instancia específica.
 Esta conexión permite a la instancia actualizarse de forma reactiva en función de los cambios en el estado.
-Al vincular el estado, la instancia se da cuenta de los cambios en el estado y puede reflejar adecuadamente esos cambios en su comportamiento.
+Al vincular el estado, la instancia es notificado de los cambios en el estado y puede reflejar adecuadamente esos cambios en su comportamiento.
 - <HM>**`unbind`**</HM>: Libera la conexión entre el estado y la instancia.
 Al desvincularse, la instancia dejará de recibir actualizaciones del estado.
 Esto puede ser útil cuando una instancia ya no está utilizando activamente el estado o cuando necesita desvincularse del estado temporal o permanentemente.
@@ -20,5 +20,5 @@ Disponer del estado garantiza que se libere correctamente y que ya no consuma me
 
 :::note
 Mientras que los métodos <HM>`bind`</HM>, <HM>`unbind`</HM> y <HM>`dispose`</HM> se utilizan normalmente para gestionar el [ciclo de vida](/reactter/es/core_concepts/lifecycle) de un estado,
-Reactter maneja esto automáticamente, cuando el estado es declarado dentro de una instancia que existe dentro del contexto de Reactter vía [dependecy injection](/reactter/es/core_concepts/dependency_injection/), por lo que no necesitas preocuparte por ello(Learn more about [Binding State to Dependency](/reactter/es/extra_topics/binding_state_to_dependency/)).
+Reactter maneja esto automáticamente, cuando el estado es declarado dentro de una instancia que existe dentro del contexto de Reactter vía [dependecy injection](/reactter/es/core_concepts/dependency_injection/), por lo que no necesitas preocuparte por ello(Apendas más acerca de la [vinculación del estado a la dependencia](/reactter/es/extra_topics/binding_state_to_dependency/)).
 :::