@yoltra/react 0.6.0 → 0.8.0

package/README.es.md

@@ -3,22 +3,24 @@
 # @yoltra/react
 
 > 👉 🇲🇽 Versión en Español  |
->  [ 🇺🇸 English Version](./README.md) 
+>  [ 🇺🇸 English Versión](./README.md) 
 
-![npm downloads](https://badgen.net/npm/dm/@yoltra/react)
-![License](https://badgen.net/npm/license/@yoltra/react)
+[![versión npm](https://img.shields.io/npm/v/@yoltra/react)](https://www.npmjs.com/package/@yoltra/react)
+[![descargas npm](https://img.shields.io/npm/dm/@yoltra/react)](https://www.npmjs.com/package/@yoltra/react)
+[![tipos](https://img.shields.io/npm/types/@yoltra/react)](https://www.npmjs.com/package/@yoltra/react)
+[![Licencia](https://img.shields.io/npm/l/@yoltra/react)](https://github.com/yoltra/yoltra/blob/main/LICENSE)
 
 **Hooks de React para [yoltra](../../README.md) con
 suscripciones de grano fino por ruta.**
 
-Suscribete a `"items.0.title"` o `"items.*.done"` -- el componente se re-renderiza solo cuando
-esa ruta exacta cambia. Sin selectores, sin memoizacion, sin optimizacion manual.
+Suscríbete a `"items.0.title"` o `"items.*.done"`. El componente se re-renderiza solo cuando
+esa ruta exacta cambia. Sin selectores, sin memoización, sin optimización manual.
 
-[Ver la comparacion de flamegraph (Redux vs yoltra).](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-react/redux-yoltra-profiler.md)
+[Ver la comparación de flamegraph (Redux vs yoltra).](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-react/redux-yoltra-profiler.md)
 
 ---
 
-## Instalacion
+## Instalación
 
 ```bash
 npm install @yoltra/core @yoltra/react
@@ -28,11 +30,11 @@ npm install @yoltra/core @yoltra/react
 
 ---
 
-## Configuracion con `createYoltra` (recomendado)
+## Configuración con `createYoltra` (recomendado)
 
-`createYoltra` crea el store **y** todos los hooks tipados en una sola llamada — sin archivo de
-context aparte, sin cableado de `createHooks`, sin provider obligatorio. Todos los parametros de
-tipo se infieren de tu reducer, asi que los componentes no necesitan generics explicitos.
+`createYoltra` crea el store **y** todos los hooks tipados en una sola llamada, sin archivo de
+context aparte, sin cableado de `createHooks`, sin provider obligatorio. Todos los parámetros de
+tipo se infieren de tu reducer, así que los componentes no necesitan generics explícitos.
 
 ### 1. Crea el store y los hooks
 
@@ -74,10 +76,10 @@ export const { store, useAtomicProp, useEmit, StoreProvider } = createYoltra({
 });
 ```
 
-### 2. Usa los hooks — sin provider
+### 2. Usa los hooks, sin provider
 
-Los hooks usan por defecto el store de arriba, asi que puedes renderizar componentes directamente.
-Suscribete con una spec **`{ reducer, property }`**: el `property` con puntos nombra la ruta exacta
+Los hooks usan por defecto el store de arriba, así que puedes renderizar componentes directamente.
+Suscríbete con una spec **`{ reducer, property }`**: el `property` con puntos nombra la ruta exacta
 a leer.
 
 ```tsx
@@ -85,7 +87,7 @@ a leer.
 import { useAtomicProp, useEmit } from "./yoltra";
 
 export function Counter() {
-  // Forma objeto — se re-renderiza solo cuando counter.value cambia. Sin selectores, sin memo.
+  // Forma objeto: se re-renderiza solo cuando counter.value cambia. Sin selectores, sin memo.
   const value = useAtomicProp({ reducer: "counter", property: "value" });
   const emit = useEmit();
 
@@ -101,13 +103,13 @@ export function Counter() {
 ```
 
 Un `<StoreProvider>` solo se necesita para acotar una instancia **diferente** del store a un
-subarbol (p. ej. un store nuevo por test) — `createYoltra` devuelve uno justo para eso.
+subarbol (p. ej. un store nuevo por test). `createYoltra` devuelve uno justo para eso.
 
 ---
 
 ## Avanzado: cableado manual con `createHooks`
 
-Cuando necesites un mismo conjunto de hooks compartido entre varias instancias de store a traves
+Cuando necesites un mismo conjunto de hooks compartido entre varias instancias de store a través
 de tu propio context de React, vinculalos tu mismo con `createHooks(context)`. `createYoltra` es
 este mismo cableado colapsado en una sola llamada.
 
@@ -135,7 +137,41 @@ export const {
 } = createHooks(AppStoreContext);
 ```
 
-Provee el store con `<AppStoreContext.Provider value={store}>` en tu raiz.
+Provee el store con `<AppStoreContext.Provider value={store}>` en tu raíz.
+
+---
+
+## Agregar a un store, con sus tipos
+
+Una librería puede montar una slice en un store que no creó, y los hooks crecen para conocerla.
+`withSlice`, `withMiddleware` y `withEffect` devuelven un `Yoltra` cuyos tipos se ampliaron.
+
+```tsx
+import { defineSlice } from "@yoltra/core";
+
+// Ámbito de módulo, una sola vez, antes del primer render.
+export const app = createYoltra({ name: "App", reducer: { counter } })
+  .withSlice("transfers", defineSlice<TransferEM>()({ ... }));
+
+export const { useAtomicProp, useEmit } = app;
+
+// Tipado, sobre una slice que la aplicación nunca declaró.
+const granted = useAtomicProp({ reducer: "transfers", property: "granted" });
+```
+
+Tres cosas que conviene saber:
+
+- **Ámbito de módulo, una vez, antes del primer render.** Cada llamada construye un conjunto
+  nuevo de hooks, porque `createHooks` asigna funciones nuevas. Llamarla dentro de un componente
+  le daría a React un `useAtomicProp` distinto en cada render.
+- **El store y el contexto son los mismos objetos.** Solo cambian los tipos, así que un
+  `<StoreProvider>` de cualquier vista de la cadena sirve a los hooks de todas las demás, y la
+  caché de Suspense se comparte.
+- **También existen las funciones libres**, para una librería que recibe un `Yoltra` que no creó:
+  `withSlice(yoltra, name, spec)`.
+
+El contrato completo, incluido qué hacer con la disposición, está en la
+[guía de decoración](https://github.com/yoltra/yoltra/blob/main/docs/es/DECORATION_GUIDE.md).
 
 ---
 
@@ -143,21 +179,21 @@ Provee el store con `<AppStoreContext.Provider value={store}>` en tu raiz.
 
 ### `useAtomicProp({ reducer, property }, map?, isEqual?)`
 
-Selector de ruta unica con grano fino. Se re-renderiza solo cuando la hoja especificada cambia. El
-`property` con puntos nombra la ruta exacta — incluyendo rutas dinamicas
+Selector de ruta única con grano fino. Se re-renderiza solo cuando la hoja especificada cambia. El
+`property` con puntos nombra la ruta exacta, incluyendo rutas dinámicas
 (`` `items.${id}.title` ``) y con comodines.
 
 ```tsx
-// Forma objeto (recomendada) — suscribete a la ruta exacta
+// Forma objeto (recomendada): suscribete a la ruta exacta
 const title = useAtomicProp({ reducer: "todos", property: "items.0.title" });
 
-// Ruta dinamica — interpola la clave
+// Ruta dinamica: interpola la clave
 const byId = useAtomicProp({ reducer: "todos", property: `items.${id}.title` });
 
-// Con mapper — derivar un valor de la ruta
+// Con mapper: derivar un valor de la ruta
 const count = useAtomicProp({ reducer: "todos", property: "items" }, (items) => items.length);
 
-// Patron wildcard — se re-renderiza cuando cualquier item cambia
+// Patron wildcard: se re-renderiza cuando cualquier item cambia
 const allTitles = useAtomicProp(
   { reducer: "todos", property: "items.**" },
   (state) => state.items.map((t) => t.title),
@@ -165,20 +201,20 @@ const allTitles = useAtomicProp(
 );
 ```
 
-> Tambien existe una sobrecarga con accessor tipado — `useAtomicProp("todos", (s) => s.items[0].title)`
-> — para rutas estaticas; autocompleta la forma del estado e infiere el tipo de retorno.
+> También existe una sobrecarga con accessor tipado, `useAtomicProp("todos", (s) => s.items[0].title)`,
+> para rutas estáticas; autocompleta la forma del estado e infiere el tipo de retorno.
 
 **Patrones soportados:**
 
-- `"items.0.title"` -- ruta exacta (incluyendo indices numericos de array)
-- `"items.*.title"` -- `*` coincide con un segmento
-- `"items.**"` -- `**` coincide con cero o mas segmentos
+- `"items.0.title"`: ruta exacta (incluyendo índices numéricos de array)
+- `"items.*.title"`: `*` coincide con un segmento
+- `"items.**"`: `**` coincide con cero o más segmentos
 
 ---
 
 ### `useAtomicProps(specs, selector, isEqual?)`
 
-Selector de multiples rutas. Se suscribe a varias rutas y recalcula cuando alguna cambia.
+Selector de múltiples rutas. Se suscribe a varias rutas y recalcula cuando alguna cambia.
 
 ```tsx
 const filtered = useAtomicProps(
@@ -193,18 +229,17 @@ const filtered = useAtomicProps(
 
 ---
 
-### `useEvent(channel, type, handler, phase?)`
+### `useEvent(channel, type, handler, phase?, options?)`
 
-Suscribete a eventos del store desde un componente. No afecta el flujo de eventos --
-fire-and-forget.
+Suscríbete a eventos del store desde un componente. No afecta el flujo de eventos. Es fire-and-forget.
 
 ```tsx
-// Eventos confirmados (por defecto) — eventos que pasaron el middleware
+// Eventos confirmados (por defecto): eventos que pasaron el middleware
 useEvent("ui", "save", (event) => {
   showToast("Saved!");
 });
 
-// Eventos no confirmados — eventos rechazados por el middleware
+// Eventos no confirmados: eventos rechazados por el middleware
 useEvent(
   "ui",
   "delete",
@@ -214,7 +249,7 @@ useEvent(
   "uncommitted",
 );
 
-// Todos los eventos — distinguir por fase
+// Todos los eventos: distinguir por fase
 useEvent(
   "ui",
   "action",
@@ -227,15 +262,26 @@ useEvent(
 
 **Fases:**
 
-- `'committed'` (por defecto) -- eventos que pasaron el middleware y llegaron a los reducers
-- `'uncommitted'` -- eventos rechazados por el middleware
-- `'all'` -- ambos, con parametro `phase` para distinguir
+- `'committed'` (por defecto): eventos que pasaron el middleware y llegaron a los reducers
+- `'uncommitted'`: eventos rechazados por el middleware
+- `'written'`: eventos que de verdad cambiaron el estado
+- `'all'`: committed y uncommitted, con parámetro `phase` para distinguir
+
+**Viaje en el tiempo.** Un handler **no** se ejecuta mientras DevTools está haciendo replay.
+Recorrer una línea de tiempo volvía a ejecutar cada handler igual que un evento real, lo que
+significaba volver a publicar, volver a escribir y volver a disparar analítica por eventos que no
+estaban ocurriendo de nuevo. Actívalo solo para un handler que derive estado de vista del flujo
+de eventos y no haga E/S:
+
+```tsx
+useEvent("ui", "save", handler, "committed", { duringReplay: true });
+```
 
 ---
 
 ### `useEmit()`
 
-Retorna la funcion `emit` tipada del store (referencia estable).
+Retorna la función `emit` tipada del store (referencia estable).
 
 ```tsx
 const emit = useEmit();
@@ -246,7 +292,7 @@ await emit("counter", "increment", 1);
 
 ### `useSelector(selector, isEqual?)`
 
-Selector de grano grueso via `useSyncExternalStore`. Se re-renderiza cuando el valor
+Selector de grano grueso vía `useSyncExternalStore`. Se re-renderiza cuando el valor
 seleccionado cambia.
 
 ```tsx
@@ -270,7 +316,7 @@ const value = store.getState().counter.value;
 ```
 
 `getState()` es una lectura, no una suscripción. Llamado durante el render, el componente se
-renderiza una vez con ese valor y nunca más — nada le avisó de que el valor cambió. Parece que
+renderiza una vez con ese valor y nunca más, porque nada le avisó de que el valor cambió. Parece que
 funciona hasta que el estado cambia y la pantalla no. Lee con `useAtomicProp` o `useSelector` lo
 que vayas a renderizar, y deja `getState()` para callbacks y efectos, que es para lo que es.
 
@@ -280,8 +326,8 @@ que vayas a renderizar, y deja `getState()` para callbacks y efectos, que es par
 
 ### `useSuspenseAtomicProp(spec, options)`
 
-Version compatible con Suspense de `useAtomicProp`. Lanza una promesa mientras carga, capturada
-por el boundary `<Suspense>` mas cercano.
+Versión compatible con Suspense de `useAtomicProp`. Lanza una promesa mientras carga, capturada
+por el boundary `<Suspense>` más cercano.
 
 ```tsx
 function UserName({ userId }: { userId: string }) {
@@ -303,7 +349,7 @@ function UserName({ userId }: { userId: string }) {
 
 ### `useSuspenseAtomicProps(specs, options)`
 
-Selector Suspense de multiples rutas.
+Selector Suspense de múltiples rutas.
 
 ```tsx
 const stats = useSuspenseAtomicProps(
@@ -318,11 +364,11 @@ const stats = useSuspenseAtomicProps(
 ### Importalos de tu conjunto de hooks, no del barrel
 
 `createYoltra` y `createHooks` devuelven estos dos junto con el resto, ligados al mismo contexto.
-Deliberadamente **no** se exportan desde el barrel del paquete: una copia a nivel de paquete seria
-identica en forma y aun asi lanzaria `useStore must be used inside <StoreProvider>` en tiempo de
-ejecucion cuando el contexto que lee nunca se lleno — un error que los tipos no podian atrapar.
+Deliberadamente **no** se exportan desde el barrel del paquete: una copia a nivel de paquete sería
+idéntica en forma y aun así lanzaría `[yoltra] No store in context` en tiempo de
+ejecución cuando el contexto que lee nunca se lleno, un error que los tipos no podian atrapar.
 Importarlos desde cualquier sitio que no sea el resultado de tu propio `createYoltra`/`createHooks`
-es ahora un error de compilacion, que es el mismo aviso llegando en el momento correcto.
+es ahora un error de compilación, que es el mismo aviso llegando en el momento correcto.
 
 ```tsx
 // store.ts
@@ -332,8 +378,8 @@ export const { store, useAtomicProp, useSuspenseAtomicProp } = createYoltra({ ..
 import { useSuspenseAtomicProp } from "./store";   // ✅ conoce el store
 ```
 
-Los valores en cache tienen alcance por store, asi que dos stores que compartan nombre de reducer
-y ruta mantienen entradas separadas; las utilidades de invalidacion de abajo reciben una ruta y la
+Los valores en cache tienen alcance por store, así que dos stores que compartan nombre de reducer
+y ruta mantienen entradas separadas; las utilidades de invalidación de abajo reciben una ruta y la
 limpian en todos los stores que la hayan cacheado.
 
 ### Utilidades de cache
@@ -359,7 +405,7 @@ clearSuspenseCache();
 
 ## `shallowEqual`
 
-Comparador de igualdad superficial de objetos. Usalo como argumento `isEqual` cuando tu valor
+Comparador de igualdad superficial de objetos. Úsalo como argumento `isEqual` cuando tu valor
 derivado es un objeto plano:
 
 ```tsx
@@ -372,7 +418,7 @@ const todos = useAtomicProp(
 
 ---
 
-## Rendimiento: Antes y Despues
+## Rendimiento: Antes y Después
 
 ### Antes (grano grueso)
 
@@ -384,7 +430,7 @@ function TodoList() {
 }
 ```
 
-### Despues (grano fino con yoltra)
+### Después (grano fino con yoltra)
 
 ```tsx
 // Cada TodoItem se re-renderiza SOLO cuando sus propios datos cambian
@@ -401,14 +447,14 @@ function TodoItem({ index }: { index: number }) {
 }
 ```
 
-[Ver la comparacion completa de flamegraph.](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-react/redux-yoltra-profiler.md)
+[Ver la comparación completa de flamegraph.](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-react/redux-yoltra-profiler.md)
 
 ---
 
 ## Compatibilidad con React 18+
 
 - **Concurrent Mode:** Totalmente compatible. Todos los hooks usan `useSyncExternalStore`.
-- **Strict Mode:** La deduplicacion de eventos previene el doble procesamiento.
+- **Strict Mode:** La deduplicación de eventos previene el doble procesamiento.
 - **Suspense:** `useSuspenseAtomicProp` y `useSuspenseAtomicProps` lanzan promesas para
   boundaries `<Suspense>`.
 
@@ -416,37 +462,37 @@ function TodoItem({ index }: { index: number }) {
 
 ## Ejemplos
 
-- **[App de Tareas con Profiler](../../examples/v0/yoltra-in-react)** -- CRUD completo con
-  comparacion de flamegraph · [▶ Abrir la demo en vivo](https://yoltra.dev/es/demos/in-react)
-- **[Logo Cinetico (3000 particulas)](../../examples/v0/yoltra-kinetic-logo)** -- Suscripciones
+- **[App de Tareas con Profiler](https://github.com/yoltra/yoltra/tree/main/examples/v0/yoltra-in-react)**: CRUD completo con
+  comparación de flamegraph · [▶ Abrir la demo en vivo](https://yoltra.dev/es/demos/in-react)
+- **[Logo Cinético (3000 particulas)](https://github.com/yoltra/yoltra/tree/main/examples/v0/yoltra-kinetic-logo)**: Suscripciones
   independientes por circulo SVG · [▶ Abrir la demo en vivo](https://yoltra.dev/es/demos/kinetic-logo)
-- **[Next.js (Pages Router)](../../examples/v0/yoltra-in-nextjs)** -- estado de cliente + cambio de tema · [▶ Abrir la demo en vivo](https://yoltra.dev/es/demos/in-nextjs)
+- **[Next.js (Pages Router)](https://github.com/yoltra/yoltra/tree/main/examples/v0/yoltra-in-nextjs)**: estado de cliente + cambio de tema · [▶ Abrir la demo en vivo](https://yoltra.dev/es/demos/in-nextjs)
 
 ---
 
-## Documentacion
+## Documentación
 
-- **[README raiz de yoltra](../../README.md)** --
-  Descripcion general y configuracion rapida
-- **[API de @yoltra/core](../core/README.md)**
-  -- Store, middleware, efectos, matchers `When`
-- **[Guia de Inicio Rapido](https://github.com/yoltra/yoltra/blob/main/docs/en/QUICK_START_GUIDE.md)**
-  -- Cinco pasos hacia una app funcional
-- **[Comparacion de Bibliotecas](https://github.com/yoltra/yoltra/blob/main/docs/en/design/state-management-library-comparison.md)**
-  -- Comparacion arquitectonica
+- **[README raíz de yoltra](../../README.md)**:
+  Descripción general y configuración rápida
+- **[API de @yoltra/core](../core/README.md)**:
+  Store, middleware, efectos, matchers `When`
+- **[Guia de Inicio Rápido](https://github.com/yoltra/yoltra/blob/main/docs/en/QUICK_START_GUIDE.md)**:
+  Cinco pasos hacia una app funcional
+- **[Comparación de Bibliotecas](https://github.com/yoltra/yoltra/blob/main/docs/en/design/state-management-library-comparison.md)**:
+  Comparación arquitectónica
 
 ---
 
 ## Contribuir
 
-- [Raiz del Monorepo](../../)
-- [Guia de Contribucion](../../CONTRIBUTING.md)
+- [Raíz del Monorepo](https://github.com/yoltra/yoltra)
+- [Guia de Contribución](../../CONTRIBUTING.md)
 
 ---
 
 ## Estado
 
-**Release Candidate** -- Las APIs son estables, usadas en produccion, cambios menores posibles
+**Release Candidate**. Las APIs son estables, usadas en producción, cambios menores posibles
 antes de v1.0.0.
 
 ---
@@ -454,7 +500,7 @@ antes de v1.0.0.
 ## Colecciones normalizadas
 
 `useEntityIds`, `useEntity` y `useEntityField` se emparejan con `createEntityAdapter` de
-`@yoltra/core`. Son envoltorios delgados sobre `useAtomicProp`; el valor esta en que la ruta viene
+`@yoltra/core`. Son envoltorios delgados sobre `useAtomicProp`; el valor está en que la ruta viene
 del adapter en vez de escribirse a mano en un componente, donde nada la verifica.
 
 ```tsx
@@ -472,4 +518,4 @@ function Row({ id }: { id: string }) {
 
 ## Licencia
 
-**MIT** -- Libre para usar en proyectos comerciales y de codigo abierto.
+**MIT**. Libre para usar en proyectos comerciales y de código abierto.