La wiki de TempWin

Esta página es de solo lectura. Puedes ver la fuente pero no puedes cambiarla. Pregunta a tu administrador si crees que esto es incorrecto.
====== Comunicación e interacción con el servidor ======

Notas del curso [[informatica:programacion:cursos:desarrollo_web_react_18|Desarrollo de aplicaciones web con React 18]]

Una interfaz bonita y altamente interactiva no sirve de nada si no puede cargar y guardar datos en un lugar más permanente. En el caso de una aplicación web, ese lugar sería un servidor o, más concretamente, el backend de la aplicación web.

<WRAP center round info 60%>
En el caso de una aplicación web totalmente independiente y sin conexión a ningún servidor, podríamos utilizar el ''localStorage'' del navegador como almacenamiento persistente. Su uso es muy simple y la metodología para integrar la carga y actualización de los datos en React/Redux sería muy similar a como lo haremos con un servidor. Aunque, claro, solo se mantendrían los datos en ese mismo navegador y sería conveniente facilitar una manera de exportarlos e importarlos con facilidad.
</WRAP>

A lo largo de este módulo, aprenderás cómo establecer una **comunicación entre la aplicación y un servidor** que presente una **API REST**. Esto lo haremos tanto con React, para aplicaciones simples, como utilizando **Redux Toolkit**, para aplicaciones más complejas como nuestro gestor de tareas kanban. Además, nos familiarizaremos con **otras técnicas** que harán la experiencia de usuario de nuestra aplicación más amigable y completa.

<WRAP center round info 60%>
Nuevamente, muchos de los conceptos y técnicas que vas a aprender en este módulo pueden resultarte algo complejos. No te preocupes, es normal. Redux es complicado. Procura ir adelante y atrás para repasar conceptos, comparar el código antes y después de los cambios, probar a crearlo por tu cuenta, etc. En definitiva, invertir tiempo en practicar, que es la única forma de asentar conocimientos. Y para cualquier duda que te surja tras haber hecho todo esto, contacta con el tutor en el foro (para que otros puedan sacar partido a las respuestas y participar) o por mensajería interna (si es una duda que no aporta a los demás o si es sobre una práctica).
</WRAP>

{{ :informatica:programacion:cursos:desarrollo_web_react_18:frontend-backend.svg |}}
===== Comunicación directa con la API - Ejemplo microblog =====

Puesto que React es únicamente una biblioteca para la creación de interfaces de usuario interactivas, en principio no impone ninguna restricción acerca de la metodología que debemos usar para cargar y enviar datos a fuentes externas. El único conflicto que podemos llegar a tener es el hecho de que las funciones que escribimos al construir los componentes deben ser puras y no pueden tener efectos secundarios. En particular, **realizar peticiones a servicios externos es un efecto secundario**.

En esta lección aprenderemos a indicar mediante el hook ''useEffect'' los efectos secundarios que queremos que ocurran en el contexto de un componente, de forma que React pueda controlar esos efectos y actualizar la interfaz convenientemente.

Con el objetivo de desarrollar un ejemplo autocontenido, vamos a construir un sistema de microblogging para un único usuario, con capacidad para cargar, editar y enviar publicaciones. Para ello, puedes crear un nuevo proyecto React con ''npm init vite'' y eliminar todos los archivos del directorio ''src'' salvo ''App.jsx'', ''index.css'' y ''main.jsx''.

==== Simulación de la API REST con json-server ====

Antes de comenzar a implementar esta aplicación, vamos a definir la fuente de datos que va a consumir. La biblioteca ''json-server'' nos aporta funcionalidad de sobra para este propósito, ya que es capaz de simular una API REST a partir de un archivo JSON de datos, e incluso permite algunas peticiones relativamente complejas para realizar diferentes búsquedas y consultas.

Para disponer de un servidor con esta biblioteca, puedes utilizar el archivo ''db.json'' que encontrarás en los archivos asociados a la lección, y del que se muestra un extracto a continuación:

<code javascript>
{
  "cuentas": [
    {
      "nombre": "Miguel",
      "id": 1
    }
  ],
  "posts": [
    {
      "contenido": "En un lugar de la Mancha, [...] partes de su hacienda.",
      "autoria": 1,
      "id": 12,
      "fecha": "1605-01-01T12:00:00Z"
    },
    {
      "contenido": "El resto della [...] tomaba la podadera.",
      "autoria": 1,
      "id": 13,
      "fecha": "1605-01-02T12:00:00Z"
    },
    {
      "contenido": "Frisaba la edad [...] de la caza.",
      "autoria": 1,
      "id": 14,
      "fecha": "1605-01-03T12:00:00Z"
    }
  ]
}
</code>

<WRAP center round important 60%>
Es importante que entiendas qué entidades de datos vamos a manejar y cómo se relacionan entre ellas, así que antes de continuar, dedica un tiempo a analizar el archivo ''db.json'' y a comprender su estructura.
</WRAP>

Para poder ejecutar el servidor, es necesario instalar ''json-server'' como dependencia e invocarlo desde la terminal con el comando ''json-server db.json''. Es muy posible que el ejecutable no se encuentre en el ''PATH'', así que lo más cómodo será añadir un script al archivo ''package.json'' de nuestra aplicación indicando:

<code javascript>
"server": "json-server --watch db.json"
</code>

De esta forma, podremos ejecutar ''npm run server'' y el gestor de paquetes se encargará de buscar el ejecutable de ''json-server'' que necesita para arrancar el servidor. Normalmente, este escuchará por defecto en el puerto 3000, pero se puede modificar si fuera necesario. En cualquier caso, ese puerto habrá que tenerlo en cuenta para que la aplicación React pueda enviar peticiones.

==== Obtención y manipulación de los datos ====

Como ya se ha mencionado, React no incorpora herramientas que sirvan expresamente para la interacción con fuentes externas. Por tanto, podemos implementar una interfaz para la API libremente. En este caso, puesto que se trata de un caso sencillo, vamos a recurrir directamente a las utilidades integradas en JavaScript: esencialmente, la función ''fetch'' y la gestión de promesas con ''then''.

Para simplificar el código posterior, vamos a crear una función que construya el esqueleto que van a tener todas nuestras peticiones al servidor. Recibirá como parámetros un ''endpoint'' (es decir, la ruta a consultar tras la URL base de la API), un método HTTP opcional (por defecto ''GET'') y un cuerpo de la petición opcional. Todas las peticiones se envían y reciben en formato JSON, por lo que hacemos uso de la cabecera HTTP correspondiente y las funcionalidades de JavaScript para convertir objetos a JSON y respuestas JSON a objetos.

<code javascript>
const API_BASEURL = "http://localhost:3000"
const api = (endpoint, method = "GET", body) => {
  return fetch(API_BASEURL + endpoint, {
    method,
    headers: {
      'Content-Type': 'application/json'
    },
    body: body ? JSON.stringify(body) : null
  }).then(r => r.json())
}
</code>

<WRAP center round important 60%>
Hay que notar que esta implementación no estaría completa en el caso de una aplicación para producción, ya que estamos haciendo caso omiso de los posibles errores que puedan producirse en las peticiones, y estamos asumiendo que todas se van a completar correctamente. Lo hacemos en pos de simplificar este ejemplo para centrarnos en lo importante para la formación: integrar la carga y envío de datos en React. Lo otro son cuestiones que cualquier desarrollador competente de JavaScript debe saber hacer.
</WRAP>

Habrás notado que la función ''api'' no solo envía la petición, sino que devuelve el resultado de llamar a la función ''fetch()''. Este es una promesa, lo cual nos permite encadenar acciones que se mantendrán a la espera de que se complete la petición, y se ejecutarán cuando esta termine. Por ejemplo, si obtenemos las publicaciones del blog, será interesante ordenarlas de forma que las más recientes aparezcan primero:

<code javascript>
const getBlog = () => api("/posts").then(ps =>
  ps.sort((a, b) => Date.parse(b.fecha) - Date.parse(a.fecha))
)
</code>

De forma similar, definimos funciones que ejecuten llamadas concretas a la API: la consulta de una cuenta de autor, así como la edición, creación y borrado de una publicación:

<code javascript>
const getAuthor = autorId => api(`/cuentas/${autorId}`)
const editPost = (id, contenido) => api(`/posts/${id}`, "PATCH", { contenido })
const saveNewPost = contenido => api("/posts", "POST", {
  contenido, autoria: 1, fecha: (new Date()).toISOString()
})
const deletePost = id => api(`/posts/${id}`, "DELETE")
</code>

Todas estas funciones nos permiten aislar los efectos secundarios que trataremos de que ocurran en la página web.

==== El hook useEffect ====

Dentro de la función que renderiza un componente, los efectos secundarios que queramos que tengan lugar independientemente de posibles eventos tendrán que hacerse a través de un hook denominado ''useEffect''. Esto quiere decir que **React ofrece dos ubicaciones para enviar y recibir datos externos**:

  * Las funciones manejadoras de eventos
  * Las funciones englobadas en ''useEffect''

Esto es así porque dichas funciones se ejecutan en un contexto diferente y no afectan de forma directa a la renderización del componente, que es lo que debe ser una operación pura.

El hook ''useEffect'' no devuelve nada y recibe dos parámetros:

  * ''setup'': debe ser una función que implemente los efectos que deben ocurrir cada vez que se ejecute el efecto. Opcionalmente, puede devolver una función de limpieza que se ejecutará antes de volver a ejecutar el efecto.
  * ''dependencies'': es un parámetro opcional que indica la lista de dependencias del efecto, es decir, qué datos son necesarios para computar dicho efecto de forma que cuando estos cambien, se vuelva a ejecutar de manera automática.

Un ejemplo simple podría ser una página de búsqueda en la que podemos filtrar las publicaciones por varios criterios, siendo uno de ellos el rango de fecha. El efecto principal sería cargar las publicaciones en ese rango y añadirlas a la interfaz. Cuando el intervalo de fechas elegido cambie, habría que limpiar la lista de publicaciones que se está mostrando y volver a cargarla otra vez con el nuevo rango:

<code javascript>
useEffect(() => {
  getPublicacionesEntre(fechaInicio, fechaFin).then(
    res => agregarPublicaciones(res)
  )
  return () => {
    limpiarPublicaciones()
  }
}, [fechaInicio, fechaFin])
</code>

Utilizando el parámetro ''dependencies'', los efectos se pueden configurar para que tengan lugar en tres casos posibles:

  * Una única vez en la primera renderización del componente: si indicamos un array vacío ''[]''.
  * Solamente cuando cambien datos concretos: si especificamos esos datos como un array de elementos, por ejemplo: ''[a, b]''. Esto también ejecuta el efecto en la primera renderización.
  * En cada renderización del componente, si no indicamos el parámetro.

<WRAP center round info 60%>
Los efectos que no deben ejecutarse en la primera renderización pero sí deben preceder a la siguiente invocación del efecto principal, irán en la función devuelta por la que pasemos como parámetro a ''useEffect''.
</WRAP>

==== El componente principal App ====

Una vez que conocemos las técnicas que tenemos a nuestra disposición para generar efectos secundarios, vamos a aplicarlos al caso de nuestra aplicación microblog para rellenar la interfaz con las publicaciones que alberga el servidor:

<code javascript>
function App() {
  const [blog, setBlog] = useState([])
  const [obsoleto, set, unset] = useFlag()
  useEffect(() => {
    getBlog().then(setBlog)
    return unset
  }, [obsoleto])
</code>

Con esas líneas estamos estableciendo ''blog'' como un dato con estado en el componente y la carga del blog al inicio de la aplicación y cada vez que la bandera ''obsoleto'' cambie de valor. Aquí, **''useFlag'' es un hook personalizado**:

<code javascript>
const useFlag = (valorDefecto = false) => {
  const [valor, setValor] = useState(valorDefecto)
  return [valor, () => setValor(true), () => setValor(false)]
}
</code>

Como ves, utiliza por debajo ''useState()'' y nos permite activar o desactivar un indicador (también llamado "flag" o "bandera" habitualmente) para avisar de algún cambio en el estado.

En la línea 6 del primer fragmento, antes de ejecutar el efecto principal donde cargamos y mostramos el blog, se devuelve el método unset, de modo que se desactiva la bandera para que los siguientes avisos tengan efecto.

<WRAP center round info 60%>
Recuerda que la función de setup que se le pasa a ''useEffect()'' puede devolver una función de limpieza, que se ejecutará antes de volver a ejecutar el efecto. Es justo lo que hacemos en este caso devolviendo ''set''.
</WRAP>

Además, vamos a permitir crear nuevas publicaciones, con lo que necesitaremos un formulario y una función para gestionarlo. Observa que, una vez que se crea la nueva publicación en el servidor, se activa la bandera para que el efecto que hemos creado antes se ejecute (con el ''then'' de la promesa):

<code javascript>
  const [postContent, setPostContent] = useState("")
  const addPost = event => {
    event.preventDefault()
    saveNewPost(postContent).then(set)
    setNewPost("")
  }
</code>

Por último, nos queda diseñar la interfaz web de la aplicación. Esta será sencilla, compuesta únicamente del formulario de creación de nuevas publicaciones y el recorrido por la lista de las actuales, creando una instanciación del componente ''Post'' para cada una:

<code javascript>
  return (
    <div className="App">
      <h1>Microblog personal</h1>
      <form onSubmit={handleSubmit} className='new'>
        <textarea value={postContent} placeholder="Nuevo post"
          onChange={(event) => setPostContent(event.target.value)} />
        <button type="submit">Publicar</button>
      </form>
      {blog.map(p => <Post {...p} key={p.id} onChange={set} /> )}
    </div>
  )
}
</code>

Observa que hemos indicado una propiedad ''onChange'' que utilizaremos dentro del componente para invocarla cuando la publicación sufra cualquier cambio (edición o borrado). En esos casos, se activa la bandera (''set()'') y por tanto se vuelve a cargar la lista de publicaciones al entrar en acción el efecto, que depende de la variable ''obsoleto'', establecida por ''set''.

==== El componente Post ====

El componente ''Post'' se encarga de mostrar el contenido de una publicación y permite editarlo y borrarlo. Además, asociado a cada uno tenemos el identificador de la cuenta que lo ha publicado, así que conviene obtener el nombre para poder incluirlo en los metadatos. Esto lo conseguimos con un efecto en el que solicitamos al servidor los datos de la cuenta referenciada por la propiedad ''autoria'' (revisa el archivo ''db.json'', que simula la base de datos con los datos de la aplicación de ejemplo):

<code javascript>
function Post({ id, autoria, contenido, fecha, onChange }) {
  const [nombre, setNombre] = useState("Anónimo")
  const [postContent, setPostContent] = useState(contenido)
  const fechaObj = new Date(fecha)
  const handleSubmit = event => {
    event.preventDefault()
    editPost(id, postContent).then(onChange)
  }
  useEffect(() => {
    getAuthor(autoria).then(n => setNombre(n?.nombre))
  }, [autoria])

  return (
    <div className="post">
      <div className="aut">{nombre}</div>
      <div className="date">{fechaObj.getDate()}/{fechaObj.getMonth()+1}/{fechaObj.getFullYear()}</div>
      <div className="text">{contenido}</div>
      <div className="opt">
        <button onClick={() => deletePost(id).then(onChange)}>Eliminar</button>
        <details>
          <summary>Editar...</summary>
          <form onSubmit={handleSubmit}>
            <textarea value={postContent} placeholder="Nuevo post"
              onChange={(event) => setPostContent(event.target.value)} />
            <button type="submit">Publicar edición</button>
          </form>
        </details>
      </div>
    </div>
  )
}
</code>

El resultado del código anterior, unido a algo de estilo CSS, lo podremos ver accediendo a nuestra aplicación arrancada con Vite, como en la captura siguiente:

{{ :informatica:programacion:cursos:desarrollo_web_react_18:010-microblog.png?nolink |}}

Como ves, podemos utilizar cualquier herramienta para comunicar una aplicación React con otros servicios. Lo único que debemos tener en cuenta es que cualquier cambio que afecte a la entrada y salida de datos de la aplicación habrá que efectuarlo en una función gestora de eventos o como un efecto con ''useEffect''.

Vamos a verlo en la práctica para acabar de asentar los conceptos. Eso sí, procura repetir por tu cuenta los pasos que vamos a seguir en el vídeo, antes de seguir con el resto del módulo....
===== Peticiones en aplicaciones con Redux: el asunc thunk =====

Si hemos desarrollado nuestra aplicación con Redux y queremos integrar **la carga y envío de datos** a una API externa, tenemos **dos vías para hacerlo**:

  - **Crear** una interfaz para comunicar con la API y establecer una serie de thunks que actúen de pasarela entre nuestro estado controlado por el almacén de Redux y el servidor. De esta forma, el almacén de Redux debe actuar como una caché de la información que hay almacenada en el servidor.
  - **Recurrir a una biblioteca** que automatice la mayor parte de las tareas necesarias para mantener una caché del estado del servidor en Redux: la gestión de los reducers, la invalidación de cachés, la repetición de peticiones únicamente cuando sean necesarias...

Es importante que te familiarices con ambas formas ya que, incluso si la segunda resultara por lo general más cómoda, puede tener limitaciones que debamos resolver haciendo uso de técnicas aprendidas con la primera. Por ello, **en esta lección implementaremos la interacción** de nuestro gestor de tareas kanban **manualmente con thunks asíncronos**, y en la próxima lo haremos mediante RTK Query, que nos ayudará a simplificar gran parte del código.

==== Concepto de thunk asíncrono ====

Ya conoces el papel de un thunk en Redux: se trata de una función intermediaria que es capaz de lanzar diferentes acciones en función del estado actual y realizar otro tipo de tareas de entrada/salida que no se pueden llevar a cabo en reducers. En caso de que alguna de esas tareas conlleve realizar peticiones, lectura de ficheros u otras operaciones que en JavaScript se tratan de forma asíncrona, lo apropiado es crear un thunk asíncrono.

¿En qué se diferencian los thunks normales de los asíncronos? Principalmente, en que **devuelven promesas**, por lo que no podemos asumir que el resultado de la ejecución de uno de ellos estará disponible inmediatamente, sino cuando la promesa se complete.

Adicionalmente, Redux Toolkit ofrece una ayuda para escribir thunks asíncronos que se llama ''createAsyncThunk'' y que automáticamente lanza tres acciones en momentos distintos de la resolución de la operación asíncrona:

  * ''pending'': se despacha inmediatamente cuando se comienza a ejecutar.
  * ''fulfilled'': se activa si se completa la tarea con éxito y se obtiene la respuesta en ''action.payload''.
  * ''rejected'': en caso de que no se pueda completar la tarea o esta falle, incluyendo el error en ''action.error''.

Así, un posible ejemplo de thunk asíncrono creado con Redux Toolkit sería el siguiente, que obtiene los datos públicos acerca de una obra de arte del Museo Metropolitano de Arte (MET) de Nueva York utilizando [[https://metmuseum.github.io/|su API pública]]:

<code javascript>
const datosObra = createAsyncThunk(
  "obras/datosCargados",
  async (objectId, { dispatch, getState }) => {
    const response = await fetch(`https://collectionapi.metmuseum.org/public/collection/v1/objects/${objectId}`)
      .then(r => r.json())
    return response
  }
)
</code>

A la hora de invocarlo, trabajamos como con cualquier otro creador de acciones, llamando a la función ''datosObra()''. Debemos tener en cuenta que **este tipo de thunks solo admite un parámetro**, por lo que en el caso de que necesitemos pasar varios valores lo haremos por medio de un objeto:

<code javascript>
<button onClick="() => dispatch(datosObra(idObra))">
  Mostrar datos
</button>
</code>

Por sí solo, el thunk obtiene los datos de la obra de arte pero **no modifica el estado de Redux** para que se pueda acceder a ellos. Esto lo podemos conseguir escribiendo un reducer para la acción dada por ''datosObra.fulfilled'' (que tendrá tipo "''obras/datosCargados/fulfilled''"). Suponiendo que tengamos una slice para gestionar las obras de arte, el código podría tener el siguiente aspecto:

<code javascript>
const obrasSlice = createSlice({
  // ...
  extraReducers: builder => {
    builder.addCase(datosObra.fulfilled, (state, action) => {
      state.obra = action.payload
    }
  }
})
</code>

A continuación vamos a implementar este patrón en nuestra aplicación de gestión de tareas Kanban.

==== Implementación de thunks asíncronos en nuestro gestor de tareas ====

En los archivos asociados a esta lección encontrarás una base de datos ''db.json'' que podrás servir con JSON Server. Para ello, comprueba que lo tienes instalado en el proyecto del gestor de tareas y añade el script ''%%"server": "json-server --watch db.json"%%'' al archivo ''package.json''. Esto bastará para que puedas lanzar el servidor con el comando ''npm run server'' y realizar peticiones contra él desde la aplicación.

<WRAP center round info 60%>
Observa que la estructura de la base de datos no es idéntica a la del estado global que veníamos utilizando en Redux. En este caso, cada tarea tiene una propiedad "''lista''" que contiene el identificador de la lista a la que pertenece, en lugar de que las listas contengan un array de tareas. O sea, le hemos dado la vuelta a la relación de modo que una tarea solo puede estar en una lista al mismo tiempo.
</WRAP>

=== Preliminares: definición de la API ===

Para facilitar que escribamos código simple cuando vayamos a interactuar con Redux, conviene definir aparte los métodos que trabajen "a bajo nivel" con la API REST. En nuestro caso, como en la base de datos de JSON Server hemos creado dos rutas, tablero y tareas, vamos a implementar las operaciones CRUD (crear, leer, modificar y borrar) sobre ellas.

Esencialmente, vamos a disponer de un objeto ''cliente'' con dos propiedades, ''tareas'' y ''tablero'', que a su vez darán acceso a cuatro funciones cada uno: ''get()'', ''post()'', ''patch()'' y ''delete()''. Puesto que el esqueleto de la petición es siempre el mismo y solamente cambia la ruta, el método y el posible cuerpo, abstraemos todo este trabajo en una función ''req()'' que representa una petición genérica. La función ''api()'' crea las cuatro funciones mencionadas para una ruta (o ''endpoint'') dada:

<code javascript>
const API_BASEURL = "http://localhost:3000"

const api = endpoint => {
  const req = (id, method = "GET", body) =>
    fetch(API_BASEURL + endpoint + (id ? `/${id}` : ""), {
      method,
      headers: {
        'Content-Type': 'application/json'
      },
      body: body ? JSON.stringify(body) : null
    }).then(r => r.json())

  return {
    get: (id) => req(id),
    post: content => req(null, "POST", content),
    patch: (id, content) => req(id, "PATCH", content),
    delete: id => req(id, "DELETE")
  }
}

const cliente = {
  tareas: api("/tareas"),
  tablero: api("/tablero")
}

export default cliente
</code>

Este código simplifica mucho el uso de la API, segmentando las tareas en dos grupos y permitiendo que cada uno de ellos tenga sus propias funciones para interactuar con el servidor.

=== Thunks asíncronos para el gestor de tareas ===

Una vez que tenemos definida nuestra API que se comunica con el servidor, podemos importar ''cliente'' en los archivos dedicados a las slices del tablero y las tareas, y definir las operaciones que podemos realizar sobre el servidor en forma de thunks. Estas **van a sustituir a la mayoría de acciones** que declaramos en su momento en las opciones de ''createSlice'' y, en particular, denominaremos igual a las que vayan a reemplazar su función (para evitar modificar el código que lanza estas acciones en los componentes).

Primero, para cargar el tablero completo y permitir crear nuevas listas, tendremos los siguientes:

<code javascript>
// tableroSlice.js
export const cargarTablero = createAsyncThunk(
  'tablero/cargarTablero',
  async () => await cliente.tablero.get()
)
export const listaCreada = createAsyncThunk(
  'tablero/listaCreada',
  async nombre => await cliente.tablero.post({ nombre })
)
</code>

Como ves, al haber separado la creación de las peticiones HTTP en un módulo aparte, aquí basta con hacer uso de las funciones que hemos creado en el objeto ''cliente'', lo que simplifica notablemente el código de estos thunks.

<WRAP center round info 60%>
Aunque los thunks siempre reciben por defecto dos parámetros (el objeto que pasamos al crearlos y un objeto que contiene ''dispatch'' y ''getState''), los que no vayamos a utilizar podemos omitirlos en la signatura de la función, como se ha hecho en los del listado anterior.
</WRAP>

Asimismo, las tareas se podrán crear, cargar, eliminar, mover y renombrar. Estas dos últimas operaciones son de tipo patch cambiando la lista y el título de la tarea, respectivamente:

<code javascript>
// tareasSlice.js
export const tareasCargadas = createAsyncThunk(
  'tareas/tareasCargadas',
  async () => await cliente.tareas.get()
)
export const tareaCreada = createAsyncThunk(
  'tareas/creada',
  async ({titulo, lista}) => await cliente.tareas.post({ titulo, lista })
)
export const tareaEliminada = createAsyncThunk(
  'tareas/eliminada',
  async id => await cliente.tareas.delete(id)
)
export const tareaMovida = createAsyncThunk(
  'tareas/movida',
  async ({ id, lista }) => await cliente.tareas.patch(id, { lista })
)
export const tareaRenombrada = createAsyncThunk(
  'tareas/renombrada',
  async ({ id, titulo }) => await cliente.tareas.patch(id, { titulo })
)
</code>

Al igual que con el ejemplo del museo, para que los resultados de los thunks tengan efecto en la interfaz de la aplicación, tendremos que aplicar los cambios convenientes en función de los resultados de cada acción.

Un ejemplo completo de las actualizaciones que tienen lugar en el estado del tablero cuando se carga el tablero completo sería el siguiente: añadiremos una propiedad ''status'' al estado del tablero para indicar si se está cargando, ha tenido éxito o ha fallado. Los reducers asociados a las acciones ''pending'', ''fulfilled'' y ''rejected'' actualizarán esta propiedad, rellenando también el objeto de listas de tareas cuando la petición se complete correctamente.

<code javascript>
const tableroSlice = createSlice({
  name: "tablero",
  initialState: { status: 'LOADING', listas: {} }
  extraReducers: builder => {
    builder
      .addCase(cargarTablero.pending, state => {
        state.status = "LOADING"
      })
      .addCase(cargarTablero.fulfilled, (state, action) => {
        for (let lista of action.payload) {
          state.listas[lista.id] = lista
        }
        state.status = "SUCCESS"
      })
      .addCase(cargarTablero.rejected, state => {
        state.status = "FAILED"
      })
  }
})
</code>

<WRAP center round info 60%>
De forma similar, habremos implementado las actualizaciones del estado convenientes al menos para la acción ''fulfilled'' de todos los thunks asíncronos, para que el estado de Redux esté sincronizado con la base de datos siempre que sea posible. En los archivos asociados a la lección dispones de la implementación de todos los reducers.
</WRAP>

Esto nos permite ahora, en primer lugar, lanzar la carga de datos desde el componente ''Tablero'', mediante ''dispatch(cargarTablero())'':

<code javascript>
const Tablero = () => {
  const dispatch = useDispatch()
  useEffect(() => {
    dispatch(cargarTablero())
    .then(() => dispatch(tareasCargadas()))
  }, [])
</code>

Como ves, tenemos que englobar esta acción en un hook ''useEffect()'' (o en la función gestora de un evento) ya que provoca efectos secundarios y, en particular, modifica el estado de Redux.

A continuación, consultamos el ''status'' actual seleccionándolo desde el estado:

<code javascript>
  const { status, listas } = useSelector(
    state => state.tablero
  )
</code>

Los gestores de eventos que antes trabajaban con acciones de la slice deberían seguir funcionando con los nuevos thunks que se denominan igual:

<code javascript>
  const [nuevaLista, setNuevaLista] = useState("")
  const crearLista = (event) => {
    event.preventDefault()
    dispatch(listaCreada(nuevaLista))
    setNuevaLista("")
  }
</code>

Por último, podemos mostrar una interfaz u otra en función del momento en que se encuentre la solicitud haciendo uso del renderizado condicional:

<code javascript>
  if (status == "LOADING") return <p>Cargando tablero...</p>
  if (status == "FAILED") return <p>Error al cargar el tablero.</p>

  return (
    <div className="tablero">
      {Object.keys(listas).map(id => <ListaTareas key={id} id={id} />)}
      <div className="lista">
        <form onSubmit={crearLista}>
          <input type="text" placeholder="Nueva lista" value={nuevaLista} onChange={e => setNuevaLista(e.target.value)} />
          <p><Boton type="submit">Crear lista</Boton></p>
        </form>
      </div>
    </div>
  )
}
</code>

Trabajaremos de la misma forma con los componentes que sirven para mostrar cada lista de tareas. Estos únicamente requerirán pequeños cambios con respecto a los que estábamos utilizando hasta ahora. Por ejemplo, el componente ''ListaTareas'' renderizará un mensaje de carga mientras las tareas estén pendientes de cargar:

<code javascript>
const ListaTareas = ({ id: listaId }) => {
  const { nombre, lista: tareas } = useSelector(state =>
    state.tablero.listas[listaId] ?? { nombre: "", lista: [] })
  const status = useSelector(state => state.tareas.status)
  const tema = useContext(ContextoTema)

  return (
    <div className="lista" style={{background: tema.fondo, color: tema.texto}}>
      <h2>{nombre}</h2>
      {status == "LOADING" && <p>Cargando tareas...</p>}
      {status == "FAILED" && <p>Ocurrió un error</p>}
      {status == "SUCCESS" && (
        <ul>
          {tareas.map(id => <Tarea key={id} id={id} />)}
        </ul>
      )}
      <FormularioNueva listaId={listaId} />
    </div>
  )
}
</code>

Dicho mensaje puedes verlo en acción a continuación:

{{ :informatica:programacion:cursos:desarrollo_web_react_18:020-cargando.png?nolink |}}

===== Comunicación mediante RTK Query - Aplicación al gestor Kanban =====

**RTK Query** es una parte de Redux Toolkit que facilita la **comunicación con servicios externos en forma de APIs**.

RTK Query automatiza toda la gestión de los reducers de Redux, implementando multitud de **atajos para las tareas comunes y repetitivas**, pero dando acceso a las operaciones internas para poder manipularlas al mismo nivel de detalle que si las implementáramos a mano.

En las siguientes lecciones vamos a verlo con detalle, aplicándolo de paso a la aplicación del gestor Kanban que hemos estado utilizando a lo largo de la formación. Para ello, vamos a partir de la aplicación que ya teníamos, pero sin la comunicación con el servidor.

Una vez más, es un tema algo denso, así que vamos a ir paso a paso y tendrás que pararte bastante en los ejemplos, repitiéndolos, para asegurarte de que entiendes bien lo que está pasando.

¡Ánimo, ya queda menos!

==== Definición de la API con RTK Query ====

La principal función de RTK Query la encontraremos en el módulo "''@reduxjs/toolkit/query/react''" y se llama ''createApi()''. Es similar a la funcionalidad ''createSlice()'' en el sentido de que definiremos una serie de operaciones y nos generará funcionalidad que se pueda lanzar desde los componentes. Sin embargo, a diferencia de las slices, **esta función generará hooks**, evitándonos la necesidad de usar ''dispatch()'' y funciones selectoras.

Partiendo de la aplicación del gestor de tareas con el estado gestionado con Redux pero sin comunicación con el servidor, vamos a crear un fichero ''api/apiSlice.js''. Aquí, importaremos dos funciones de RTK Query y definiremos nuestra API:

<code javascript>
import { createApi, fetchBaseQuery } from "@reduxjs/toolkit/query/react"
const apiSlice = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: 'http://localhost:3000/' })
})
</code>

<WRAP center round important 60%>
Presta atención a la fuente desde la que importas ''createApi'', ya que también existe en el módulo "''@reduxjs/toolkit/query''" pero este es independiente de React, por lo que no nos generaría los hooks correspondientes.
</WRAP>

Por ahora, hemos especificado dos opciones como parámetros de ''createApi()'':

  * ''reducerPath'': es opcional y sirve para indicar un nombre para la propiedad del almacén de Redux donde queremos albergar la información transmitida por el servidor.
  * ''baseQuery'': nos permite establecer una plantilla que seguirán todas las peticiones de esta API; en nuestro caso, que el URL base será ''%%http://localhost:3000%%''.

Lo siguiente será proporcionar la opción ''endpoints'', que debe ser una función que toma como parámetro un ''builder'', y que **devolverá un objeto** en el que iremos definiendo cada una de las operaciones que se pueden realizar en el servidor. **Existen dos tipos de peticiones: consultas (query) y mutaciones (mutation)**. Las consultas son aquellas con las que vamos a leer información, y las mutaciones nos servirán para modificarla o añadir nuevos datos.

Crear consultas es muy sencillo, basta con utilizar el método ''query()'' del objeto ''builder'' y proporcionarle la opción ''query'', que a su vez será una función que devuelva el resto de la ruta que se concatenará al URL base:

<code javascript>
  endpoints: builder => ({
    getTablero: builder.query({
      query: () => "/tablero"
    }),
  })
</code>

<WRAP center round info 60%>
Observa que los paréntesis que engloban el objeto devuelto por la función ''endpoints'' son obligatorios ya que, de lo contrario, el parser entendería que las llaves corresponden con el cuerpo de la función, no con la definición de un literal de objeto.
</WRAP>

De la misma forma, crearemos consultas para todas las tareas y para obtener únicamente las tareas cuya lista coincida con un identificador dado:

<code javascript>
    getTareas: builder.query({
      query: () => "/tareas"
    }),
    getListaTareas: builder.query({
      query: (id) => `/tareas/?lista=${id}`
    }),
</code>

En cuanto a las mutaciones, se crearán con el método ''mutation()'' y será necesario que incluyamos **más información en la opción ''query''**, además de la ruta: **el método HTTP** y, opcionalmente, **un cuerpo** de la petición. Por ejemplo, para crear una nueva lista de tareas, necesitaremos su nombre e invocaremos el método POST sobre la ruta ''/tablero'':

<code javascript>
    createLista: builder.mutation({
      query: (nombre) => ({
        url: "/tablero",
        method: "POST",
        body: { nombre }
      })
    }),
</code>

Procediendo de forma similar, podremos crear, modificar y borrar tareas con los métodos HTTP apropiados:

<code javascript>
    createTarea: builder.mutation({
      query: ({ titulo, lista }) => ({
        url: "/tareas",
        method: "POST",
        body: { titulo, lista }
      }),
    }),
    updateTarea: builder.mutation({
      query: ({ id, ...patch }) => ({
        url: `/tareas/${id}`,
        method: "PATCH",
        body: patch
      }),
    }),
    deleteTarea: builder.mutation({
      query: (id) => ({
        url: `/tareas/${id}`,
        method: "DELETE"
      }),
    })
</code>

La ejecución de ''createApi'' **generará un hook por cada consulta o mutación** que definamos. El esqueleto del nombre del hook será: ''use'' + el nombre de la operación comenzando por mayúscula + ''Query'' o ''Mutation'' al final en función del tipo. Así, los elementos exportados por nuestra API serán:

<code javascript>
export const {
  useGetTableroQuery,
  useGetTareasQuery,
  useGetListaTareasQuery,
  useCreateListaMutation,
  useCreateTareaMutation,
  useUpdateTareaMutation,
  useDeleteTareaMutation
} = apiSlice

export default apiSlice
</code>

Observa que, además de exportar los hooks generados por la slice, también hemos exportado la propia ''apiSlice''. Esto se debe a que toda la funcionalidad para consultar datos e iniciar peticiones está también contenida en dicho objeto, y nos permite utilizarla en lugares donde no podamos llamar a los hooks, es decir, desde cualquier función que no sea un componente.

==== Preparación del almacén ====

Antes de lanzar ninguna petición, es fundamental que el almacén sea capaz de almacenar los datos de la API. Para poner al almacén en conocimiento de esta información, ''createApi'' genera además un reducer principal que podemos incluir en el objeto ''reducer''. Además de esto, será muy conveniente incluir el middleware de RTK Query, que habilitará algunos mecanismos útiles como la gestión de cachés o el sondeo (polling):

<code javascript>
// app/store.js
import api from "../features/api/apiSlice";

export const store = configureStore({
  reducer: {
    [api.reducerPath]: api.reducer
  },
  middleware: getDefaultMiddleware =>
    getDefaultMiddleware().concat(api.middleware)
})
</code>

Abre el código de ambas y compara esto con la versión anterior de la aplicación. Puedes observar que **hemos eliminado los reducers** de tareas y tablero. Esto es porque, al obtener esos datos mediante la API, utilizar las slices sería duplicar la información en el almacén. Por tanto, **las slices de tareas y tablero dejan de tener sentido**, y podemos eliminar los ficheros ''tableroSlice.js'' y ''tareasSlice.js''. A continuación, sustituiremos todas las interacciones con las acciones y selectores del almacén por hooks para ejecución de consultas y mutaciones, simplificando así el código de los componentes.

==== Uso de las consultas en la aplicación ====

Hasta ahora, en nuestra API hemos definido dos tipos de operaciones: consultas y mutaciones. El propósito es que podamos utilizarlas de formas apropiadas en los componentes. Por un lado, las consultas se encargarán de recuperar los datos, bien del servidor o bien de la caché en el almacén de Redux, al invocar el hook correspondiente. Por otro, las mutaciones nos proporcionarán una función que podremos llamar cuando se deba alterar alguna información en el servidor.

Veamos primero un ejemplo de cómo utilizaremos el hook asociado a la consulta ''getTablero'':

<code javascript>
// Tablero.jsx
const Tablero = () => {
  const {
    data: listas,
    isLoading,
    isSuccess,
    isError,
    error,
    refetch
  } = useGetTableroQuery()
  // ...
</code>

El valor de retorno de ''useGetTableroQuery()'' es un objeto con la respuesta de la petición en el campo ''data'', que en este caso se le asigna a la constante ''listas'' mediante desestructuración. Y además obtenemos varias propiedades que nos indicarán en qué momento de la petición nos encontramos:

  * ''isLoading'' es un valor booleano que será verdadero cuando la aplicación está esperando una respuesta por primera vez.
  * ''isFetching'' será también verdadero cada vez que se repita la petición y se esté esperando una respuesta.
  * ''isSuccess'' será verdadero cuando se complete la petición con éxito
  * ''isError'' se establecerá a true cuando la petición termine con un error. La información de dicho error la encontraremos en ese caso en el campo ''error''.
  * ''refetch'' será una función que podremos invocar para forzar una repetición de la consulta.

Un cambio en el estado de la petición conllevará una renderización del componente, por lo que utilizaremos los valores de los datos que hemos obtenido para renderizarlo en cada momento, y no necesitamos hacer nada más para que la interfaz siempre se muestre con la información más reciente.

La interfaz en JSX del tablero de listas podría quedar como sigue, utilizando todas estas propiedades:

<code javascript>
  return (
    <div className="tablero">
      {isSuccess &&
        <>
          {listas.map((val) =>
              <ListaTareas key={val.id} id={val.id} nombre={val.nombre} />
          )}
          <FormNuevaLista/>
        </>
      }
      {isLoading && <p>Cargando tu tablero...</p>}
      {isError && <p>Ocurrió un error al cargar el tablero: {error.error}
        <button onClick={refetch}>¿Intentar de nuevo?</button></p>}
    </div>
  )
}
</code>

En este caso, hemos utilizado la consulta sin pasar ningún parámetro, pero **cada uno de los hooks** asociados a consultas **acepta dos parámetros**: ''queryArg'' y ''queryOptions''.

El argumento ''queryArg'' se proporcionará, tal cual, a la función ''query'' que hayamos definido. Por ejemplo, la consulta ''getListaTareas'' acepta un identificador de lista de forma que solo recupera las tareas cuya ''lista'' coincida con este, y que le pasaremos en este primer parámetro. Así, cada instanciación del componente ''ListaTareas'' solo se volverá a renderizar si alguna de sus tareas se ve modificada:

<code javascript>
const ListaTareas = ({ id: listaId, nombre }) => {
  const { data: tareas, isLoading, isSuccess, isError, error } = useGetListaTareasQuery(listaId)
  // ...
</code>

**El objeto de opciones ''queryOptions''** admite [[https://redux-toolkit.js.org/rtk-query/usage/queries#query-hook-options|varias propiedades]] para controlar el comportamiento de las solicitudes.

Una de ellas, especialmente útil, es ''selectFromResult'', que acepta una función para extraer datos de la respuesta de la API, optimizando el renderizado del componente para que solo ocurra si dicho subconjunto de datos cambia. Esto, por ejemplo, nos será útil en el componente ''Cabecera'', que únicamente necesita el número de tareas y no la lista completa:

<code javascript>
const Cabecera = () => {
  const { tareas } = useGetTareasQuery(undefined, {
    // Es importante usar el operador de acceso "?." en este caso
    // porque si los datos aún no están cargados provocará un error
    selectFromResult: ({ data }) => ({ tareas: data?.length })
  })
  // El resto del componente no cambia
</code>

<WRAP center round info 60%>
Observa que, como en este caso no necesitamos pasar ningún parámetro a la consulta pero queremos pasar el segundo argumento con las opciones, hemos utilizado ''undefined'' como primer argumento de ''useGetTareasQuery()''.
</WRAP>

==== Activación de mutaciones ====

Si hasta ahora hemos limpiado el código de selectores y acciones para sustituirlos por consultas y mutaciones, utilizando las primeras adecuadamente ya deberíamos conseguir que la aplicación muestre la información obtenida desde el servidor en la interfaz. Sin embargo, ningún botón ni formulario que interaccione con el estado será funcional aún. Para lograrlo, vamos a **incorporar los hooks generados por las mutaciones** que hemos definido en la API.

Cada uno de estos hooks **devuelve una tupla con dos elementos**:

  * **Una función** que realiza la petición al llamarla
  * **Un objeto** similar al que devuelve el hook de una consulta, que contiene información acerca del momento en el que se encuentra una solicitud (''isLoading'', ''isSuccess'', ''isError'', etc.).

El caso más simple de mutación en nuestra aplicación es el de la creación de una nueva lista: basta con proporcionar el nombre de la lista y la API hará lo demás. En el nuevo componente ''FormNuevaLista'', controlamos de la manera convencional un campo con el dato ''nuevaLista'' y gestionamos el envío del formulario, llamando aquí a la función ''crearLista'' asociada a la mutación, obtenida de la tupla devuelta por el hook ''useCreateListaMutation()'':

<code javascript>
const FormNuevaLista = () => {
  const [nuevaLista, setNuevaLista] = useState("")
  const [crearLista, resultado] = useCreateListaMutation()

  const handleSubmit = event => {
    event.preventDefault()
    crearLista(nuevaLista)
  }
  // ...
</code>

El resto de operaciones con las tareas se harán de forma muy similar, por ejemplo, la eliminación y la modificación 
del título de una tarea:

<code javascript>
const Tarea = ({ id, titulo: initialTitulo }) => {
  const [titulo, setTitulo] = useState(initialTitulo)
  const [renombrarTarea, resultado] = useUpdateTareaMutation()
  const [eliminarTarea, resultado2] = useDeleteTareaMutation()

  const handleChange = event => {
    setTitulo(event.target.value)
    renombrarTarea({id, titulo: event.target.value})
  }

  return (
    <li>
      <input type="text" value={titulo} onChange={handleChange} />
      <Boton onClick={() => eliminarTarea(id)}>×</Boton>
    </li>
  )
}
</code>

<WRAP center round info 60%>
Fíjate en que, al renombrar la tarea, enviamos el titulo indicado por ''event.target.value'' y no ''titulo'', ya que ''titulo'' tendrá el contenido previo al disparo del evento ''onChange''.
</WRAP>

=== Cancelación de peticiones ===

Un detalle que puede pasar inadvertido mientras desarrollamos, pero que es muy importante, es que en un entorno de producción seguramente no sería conveniente actualizar el nombre de la tarea en el servidor cada vez que cambie el valor del input (como estamos haciendo). Si se introducen muchos caracteres de manera rápida, se lanzarían múltiples actualizaciones asíncronas.

Para no saturar el servidor enviando demasiadas peticiones seguidas, podemos cancelar todas las peticiones en curso salvo la última. La función que nos proporciona la mutación devuelve una promesa, que a su vez tiene un método ''abort()'' que podemos utilizar cuando sepamos que hay un nuevo cambio del título y que, por tanto, se puede desechar la petición actual.

Para ello, sin embargo, hay que ajustar un poco el código utilizando la mutación en ''useEffect()'' para poder acceder a la promesa justo antes de que se vuelva a redefinir la constante:

<code javascript>
  useEffect(() => {
    const peticionRenombrado = renombrarTarea({id, titulo})
    return () => { peticionRenombrado?.abort() }
  }, [titulo])

  const handleChange = event => {
    setTitulo(event.target.value)
  }
</code>

Hemos movido la llamada a ''renombrarTarea()'' a un efecto que se ejecuta cada vez que cambia el título (el efecto tiene una dependencia en titulo). Como resultado del efecto hemos devuelto una función que, como recordarás, se ejecutará cuando el componente se desmonte. Esta función cancela la petición en curso, si la hay, utilizando el método ''abort()'' de la promesa devuelta por ''renombrarTarea()''. Gracias a esto conseguimos el efecto deseado.

==== Interacción de thunks con la API ====

Las APIs definidas con RTK Query ofrecen dos formas de interactuar con las consultas y las mutaciones que hemos definido. Por un lado, están los hooks que acabamos de utilizar. Por otro, tenemos **las propiedades de ''apiSlice.endpoints''**, que nos permiten tanto acceder a los datos almacenados para cada operación como lanzar nuevas peticiones. El objeto ''endpoints'' que incluye la API tiene la siguiente estructura:

  * ''endpoints''
    * ''getTablero'': un objeto asociado a la consulta ''getTablero'' que definimos antes
      * ''select()'': un método que devuelve una función, que sirve para **obtener** del estado global de Redux los **datos resultantes de una petición previa** de ''getTablero''. Si no se ha realizado ninguna petición previa, el método ''select()'' devolverá ''undefined''
      * ''initiate()'': un creador de thunks para enviar una consulta de tipo ''getTablero''.
      * Otros métodos...
    * ''updateTarea'': un objeto asociado a la mutación ''updateTarea''
      * ''select()'': permite recuperar los datos resultantes de una petición previa
      * ''initiate()'': permite enviar una nueva petición para modificar una tarea
      * Otros métodos...
    * Otras consultas y mutaciones siguendo el mismo esquema...

Esta posibilidad existe para permitir el uso de la API en lugares del código donde no se pueden utilizar hooks, como pueden ser, entre otros, los thunks.

<WRAP center round tip 60%>
Cuando la operación que queremos ofrecer en la interfaz de usuario no se corresponde exactamente con las que podemos pedir al servidor, es muy posible que tengamos que escribir un thunk que utilice la API de manera directa.
</WRAP>

Un ejemplo de esto son los botones para mover tareas a la izquierda y derecha, ya que en el servidor solo podemos ajustar el identificador de la ''lista'' de una tarea. Previamente, este cambio lo podíamos conseguir directamente despachando acciones sobre el estado global desde el thunk, pero ahora el estado se debe guardar de forma persistente en el servidor.

Por tanto, ahora implementaremos un thunk de tipo asíncrono y recurriremos directamente a la interfaz de la ''apiSlice''. Esta nos permite obtener el estado actual del tablero de listas llamando al método ''select()'' del endpoint ''getTablero'', y efectuar una modificación de la tarea llamando a ''initiate()'' sobre el endpoint ''updateTarea'':

<code javascript>
// api/apiSlice.js
export const tareaMovidaIzquierda = createAsyncThunk(
  'tareas/movidaIzq',
  async ({ id, lista }, { dispatch, getState }) => {
    // Consultar manualmente el tablero cargado por la API en el estado actual
    const { data: tablero } = apiSlice.endpoints.getTablero.select()(getState())
    // Averiguar la lista anterior a la actual
    const fromIdx = tablero.findIndex(v => v.id === lista)
    const toIdx = fromIdx - 1

    if (toIdx >= 0) {
      // Lanzar manualmente una actualización de la tarea para modificar su lista
      await dispatch(apiSlice.endpoints.updateTarea.initiate({ id, lista: tablero[toIdx].id }))
    }
  }
)
</code>

Fíjate en que, como **primer argumento del thunk asíncrono**, recibimos un objeto con los parámetros que necesitamos para realizar la operación (en este caso, el identificador de la tarea y la lista de procedencia). El **segundo argumento** es un objeto con dos propiedades: ''dispatch'' y ''getState''. La primera es la función ''dispatch'' de Redux, que nos permite lanzar acciones y thunks, y la utilizamos para iniciar una petición de modificación de la tarea. La segunda es una función que nos permite obtener el estado actual de la aplicación, que en este caso nos interesa para extraer el tablero de listas cargado por la API mediante el método ''select()'' del endpoint ''getTablero''.

<WRAP center round tip 60%>
No te olvides de que Redux es, en esencia, una caché global de datos. Si utilizas frecuentemente esta forma de lanzar peticiones con el método ''initiate()'', debes tener en cuenta que RTK Query contará cada petición como una suscripción a los datos obtenidos, de forma que no liberará cachés innecesarias incluso cuando ya no estemos accediendo a ellos. Para prevenir esto, podemos llamar al método ''unsubscribe()'' sobre la acción despachada. Por ejemplo, para deshacer la suscripción a la petición de modificar la tarea que acabamos de escribir, ejecutaríamos lo siguiente:

<code javascript>
    const result = dispatch(apiSlice.endpoints.updateTarea.initiate({ id, lista: tablero[toIdx].id }))
    result.unsubscribe()
    await result
</code>

Hablaremos más de cachés y de su invalidación en la siguiente lección.
</WRAP>

==== Invalidación de cachés ====

Aunque ya tengamos una aplicación capaz de recuperar información del servidor y enviar actualizaciones, estas alteraciones de datos en el servidor no se ven reflejadas en la interfaz de la aplicación. Esto es porque, aunque en cada renderización de los componentes ''Tablero'' y ''ListaTareas'' se llama a las consultas de la API, **RTK Query dispone de una caché para no provocar solicitudes innecesarias y repetidas**. Necesitamos entonces un mecanismo para notificar que esa caché está obsoleta.

Por suerte, las consultas y mutaciones que creamos en la opción ''endpoints'' admiten unos **parámetros** adicionales que **automatizarán la gestión e invalidación de la caché**.

Por un lado, la propiedad ''providesTags'' de las queries se encarga de asociar una o más etiquetas a una consulta. A partir de ellas, podemos indicar cualesquiera de estas etiquetas en la propiedad ''invalidatesTags'' de una mutación, de forma que cuando se invoque dicha mutación, se volverá a cargar la información correspondiente a las etiquetas que se hayan invalidado.

Veamos un ejemplo para entenderlo mejor...

Cuando creamos una nueva lista de tareas, debe recargarse el componente ''Tablero'' que obtiene su información de la consulta ''getTablero''. Por tanto, le asociaremos una etiqueta (el nombre no es relevante pero usaremos ''Tablero'' por consistencia) mediante ''providesTags'', y la invalidaremos en la mutación que crea listas:

<code javascript>
    getTablero: builder.query({
      query: () => "/tablero",
      providesTags: ["Tablero"]
    }),
    // ...
    createLista: builder.mutation({
      query: (nombre) => ({
        url: "/tablero",
        method: "POST",
        body: { nombre }
      }),
      invalidatesTags: ["Tablero"]
    }),
</code>

Podemos ir más allá y especificar, además de un tipo de etiqueta, **un identificador único** para los casos en que haya más de un componente que obtenga información diferente mediante la misma consulta. Por ejemplo, en nuestro caso, cada lista de tareas recupera su propia información, al igual que el contador de la cabecera. Aunque ambos usan la misma consulta ''getListaTareas'', no queremos que al cambiar simplemente el texto de una tarea se recargue el contador de la cabecera, ya que el número de tareas no habrá variado.

Para controlar cuál de estos componentes queda invalidado (y no volver a cargar más información de la cuenta), proporcionamos las tareas en el formato ''{ type, id }'' como sigue:

<code javascript>
    getTareas: builder.query({
      query: () => "/tareas",
      providesTags: [{ type: "Lista", id: "TODAS" }]
    }),
    getListaTareas: builder.query({
      query: (id) => `/tareas/?lista=${id}`,
      providesTags: (result, error, id) => [{ type: "Lista", id }]
    }),
    // ...
    createTarea: builder.mutation({
      query: ({ titulo, lista }) => ({
        url: "/tareas",
        method: "POST",
        body: { titulo, lista }
      }),
      invalidatesTags: (result, error, { lista }) => [{ type: "Lista", id: lista }, { type: "Lista", id: "TODAS" }]
    }),
</code>

Como puedes ver en el listado anterior, podemos proporcionar las etiquetas en forma de función para computarlas en base al resultado de la petición o al argumento que se le haya proporcionado. En este caso, asociamos el identificador de la lista a la etiqueta para únicamente invalidar la lista que se haya modificado al crear una tarea, así como el contador de tareas (identificador "''TODAS''").

Alternativamente, si queremos invalidar todas las etiquetas de un tipo, podemos simplemente devolver el tipo de la etiqueta:

<code javascript>
    updateTarea: builder.mutation({
      query: ({ id, ...patch }) => ({
        url: `/tareas/${id}`,
        method: "PATCH",
        body: patch
      }),
      invalidatesTags: ["Lista"]
    }),
</code>

A partir de este momento, cada consulta será notificada cuando se invalide la etiqueta asociada con sus datos en la caché, de forma que se repetirá para obtener la información más reciente desde el servidor y desencadenará una renderización de los componentes que lo necesiten.
===== Estilos con Tailwind CSS =====

En una aplicación compleja es habitual que los estilos CSS vayan almacenados en una hoja de estilo aparte, asociados a clases que asignamos a los elementos HTML. Sin embargo, cuando construimos una aplicación con una biblioteca para componentes como React, por lo general solo tendremos que escribir cada componente una sola vez y lo reutilizaremos tantas veces como convenga. Esto resta relevancia al concepto de clases CSS, ya que son un mecanismo para reutilizar estilo que es muy probable que apenas aprovechemos.

En su lugar, la popular biblioteca [[https://tailwindcss.com/|Tailwind CSS]] introduce el concepto de clases de utilidad (//utility classes//), que son atajos para definir propiedades de estilo con valores concretos. Por ejemplo, la clase ''mb-1'' asigna al elemento la propiedad ''margin-bottom: 0.25rem'', y ''rounded'' le asocia la propiedad ''border-radius: 0.25rem''. Esto nos permite, en gran medida, limitar la cantidad de código CSS a escribir, a la vez que integramos el estilo de un componente en su propia definición.

<WRAP center round info 60%>
Este concepto tan sencillo unido a la popularidad de React y otras bibliotecas para crear componentes, es lo que ha hecho que Tailwind CSS se haya convertido en una de las bibliotecas de estilos más populares en los últimos años, y que haya sido adoptada por grandes empresas como Amazon, Microsoft o GitHub.
</WRAP>


Un patrón común al utilizar React y Tailwind es construir algunos componentes que envuelvan elementos HTML simples, añadiéndoles el estilo necesario para que sea consistente con la estética de la aplicación. Estos componentes, que están orientados a su reutilización y son independientes de la sección de la página en que se vayan a renderizar, los podemos incluir en un fichero auxiliar ''utils/ui.jsx''.

A lo largo de esta lección estudiaremos varias formas de decorar y envolver componentes.

==== Instalación y configuración de Tailwind CSS con React ====

<WRAP center round important 60%>
 Importante: el conocimiento de Tailwind CSS no es objeto de este curso, que está centrado en React. Por ello, esta lección solo pretende darte una idea general de cómo funciona y cómo se utiliza. Tailwind no es imprescindible para seguir el curso, pero sí es recomendable, ya que es una biblioteca muy popular y es probable que te la encuentres en otros proyectos. Además, es muy sencillo de aprender y de utilizar, por lo que no te llevará mucho tiempo familiarizarte con ella. Si quieres profundizar en su uso, puedes consultar la [[https://tailwindcss.com/docs|documentación oficial]].
</WRAP>

=== 1.- Instalar TailWind CSS ===

Para utilizar Tailwind en tu proyecto, antes de nada debes **instalarlo**. Para ello ejecuta el comando:

<code bash>
npm install -D tailwindcss postcss autoprefixer
</code>

en la carpeta del proyecto para añadirlo como **dependencia de desarrollo** a ''package.json'', así como sus dependencias [[https://postcss.org/|PostCSS]] (un preprocesador avanzado de CSS muy popular) y [[https://github.com/postcss/autoprefixer|autoprefixer]] (un plugin de PostCSS para añadir automáticamente a ciertas propiedades los prefijos especiales de cada navegador si fuera necesario).

=== 2.- Configurar TailWind CSS ===

A continuación, crea un fichero de configuración de Tailwind (''tailwind.config.js'') con el comando:

<code bash>
npx tailwindcss init -p
</code>

El modificador ''-p'' indica que se debe crear también un fichero ''postcss.config.js'' con la configuración de PostCSS por defecto. Este fichero es necesario para que PostCSS funcione correctamente, pero en principio no le tocaremos por nuestra parte.

Abre el archivo de configuración de Tailwind recién creado (''tailwind.config.js'') y asegúrate de que la sección ''content'' del mismo está apuntando a la página principal y a la carpeta ''src'' con el código fuente de tu proyecto, así:

<code javascript>
module.exports = {
  content: ["./index.html", "./src/**/*.{html,js,jsx}"],
  // ...
}
</code>

<WRAP center round info 60%>
Nota: por si acaso no las conoces... Las expresiones de tipo ''%%"./src/**/*.{html,js,jsx}"%%'' que se usan para especificar rutas se denominan "globs" y vienen del mundo UNIX, en los años '70, y se utilizan mucho en Node.js y herramientas implementadas en esta plataforma, como Tailwind CSS. Son muy sencillas de usar e interpretar, solo hay que saber el significado de los símbolos:

  * ''*'' coincide con cualquier carácter cero o más veces, excepto ''/''. Tampoco coincide con los archivos con punto. al comienzo de su nombre.
  * ''%%**%%'' coincide con cualquier carácter cero o más veces, incluido ''/'', por eso se utiliza para indicar "en cualquier subcarpeta".
  * ''?'' coincide con cualquier carácter una vez, pero no coincide con un nombre de archivo con un punto inicial
  * ''[abc]'' coincide con alguno de los caracteres especificados dentro de los corchetes, como en las expresiones regulares.
  * ''{uno,dos,tres}'' coincide con alguno de los patrones especificados entre llaves.

Así es muy fácil ver que ''%%"./src/**/*.{html,js,jsx}"%%'' coincide con cualquier archivo con extensión ''.html'', ''.js'' o ''.jsx'' que esté en cualquier subcarpeta de ''src''.

</WRAP>

=== 3.- Referenciar los estilos de Tailwind CSS ===

Por último, **debes referenciar los estilos de Tailwind** en tu aplicación. Para ello, añade las siguientes líneas al principio de tu archivo CSS principal, generalmente ubicado en ''/src/index.css'':

<code css>
@tailwind base;
@tailwind components;
@tailwind utilities;
</code>

Estas líneas hacen que, a la hora de compilar el proyecto, PostCSS importe los estilos base, los componentes y las utilidades de Tailwind CSS, respectivamente. Si no las incluyes, Tailwind no funcionará.

A partir de este momento tienes Tailwind CSS instalado y configurado en tu proyecto. Cada vez que ejecutes los comandos ''dev'', ''build'' o ''preview'' con ''npm run'' para trabajar con el proyecto, se compilarán los estilos de Tailwind CSS y se incluirán en el resultado final, por lo que ya puedes utilizar sus clases en cualquier componente de tu aplicación.

<WRAP center round tip 60%>
Si abres el ''index.css'' del proyecto de ejemplo que acompaña a esta lección verás que además se están utilizando las directivas [[https://developer.mozilla.org/en-US/docs/Web/CSS/@layer|@layer]] y [[https://developer.mozilla.org/en-US/docs/Web/CSS/@media|@media]] de CSS. Estas son directivas estándar del lenguaje y no tienen nada que ver con Tailwind CSS. Se utilizan respectivamente para cambiar el orden de precedencia de las reglas CSS y para aplicar estilos en determinados dispositivos, en este caso para cambiar el color en función del tema. Eso sí, dentro de ellas se emplea la directiva ''@apply'' que sí que es específica de TailWind CSS y sirve para [[https://tailwindcss.com/docs/reusing-styles#extracting-classes-with-apply|extraer las propiedades de las clases indicadas]] a continuación para reutilizarlas. De este modo reutilizamos clases de Tailwind CSS en nuestros propios estilos. Lo verás utilizado muy a menudo, por eso lo hemos incluido también.
</WRAP>

==== Sintaxis de las clases de Tailwind ====

Las clases de Tailwind están pensadas para ser rápidas de escribir y compactas, por lo que las propiedades CSS más comunes tienen clases equivalente con nombres o prefijos más cortos. Algunas propiedades se pueden aplicar indicando únicamente el nombre del valor.

Algunas de las categorías más comunes de propiedades están resumidas a continuación:

  * **Propiedades con valor con nombre**: en algunas se omite el nombre de la propiedad (por ejemplo, ''block'' para ''display: block'') o se acorta (por ejemplo, ''items-start'' para ''align-items: flex-start'').
  * **Propiedades de tamaño**: utilizan un prefijo ''w'', ''h'', ''p'' o ''m'' para ancho, alto, margen interior y margen exterior respectivamente. Los dos últimos se pueden combinar con las letras ''x''. ''y'', ''t'', ''r'', ''b'', ''l'' para indicar el lado o los lados donde aplicarlos (eje longitudinal, eje transversal, arriba, derecha, abajo, izquierda). Los valores numéricos predeterminados siguen una secuencia que aumenta en 0.25rem a cada paso. Por ejemplo, ''w-10'' especifica un ancho de 2.5rem y ''px-3'' un margen interior horizontal de 0.75rem.
  * **Propiedades de color**: se prefijan con ''bg-'', ''text-'', ''border-'', ''shadow-'', etc. y llevan un tono y un valor de intensidad (cuanto mayor, más oscuro). Por ejemplo, ''bg-gray-500'' equivale a asignar ''background-color: rgb(107 114 128)'', y ''text-pink-800'' aplica ''color: rgb(157 23 77)''.
  * **Propiedades condicionadas**: se puede prefijar cualquier clase con ''dark:'' para aplicarla únicamente cuando el navegador informe que prefiere el tema oscuro, o ''sm:'', ''md:'', ''lg:'', ''xl:'' y ''2xl'' para que se aplique cuando el tamaño de la ventana sea al de menor ancho (640px), mediano (>768px), grande (>1024px), muy grande (>1280px) y extra grande (>1536px). De la misma forma, los prefijos ''hover:'' y ''focus:'' aplican una clase cuando se coloca el cursor por encima del elemento o se enfoca con el teclado, respectivamente. Existe una amplia gama de condiciones que cubren todo tipo de situaciones.

Cuando queremos establecer una propiedad a un valor que no está asociado a una clase de Tailwind, podemos utilizar corchetes para proporcionar el valor literal y el preprocesador de Tailwind se encargará de crear la clase necesaria. Por ejemplo, con ''max-w-[600px]'' asignaríamos la propiedad ''max-width: 600px'' a un elemento.

<WRAP center round info 60%>
Existe [[https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss|una extensión oficial para Visual Studio Code]] que amplía el intellisense del editor para sugerir las clases de Tailwind y sus valores a medida que escribimos, facilitándonos mucho su uso. Solo es necesario buscarla en el apartado de Extensiones de la barra lateral de VSCode.

</WRAP>

===== Componentes con ranuras para elementos =====

Como ya sabes, en React, los elementos hijos de un componente se proporcionan automáticamente en la propiedad ''children'', pero esto no nos impide proporcionar elementos en otras propiedades. Por ejemplo, para construir una barra superior para la aplicación podemos recibir elementos en dos propiedades, ''izq'' y ''dcha'', para las opciones que tengan que aparecer en cada lado de la barra:

<code javascript>
export const BarraMenu = ({ izq, dcha, secundaria, children, ...props }) => (
  <div className={`sticky left-0 w-[100vw] px-6 py-2 flex flex-row gap-3 flex-wrap
    justify-between items-baseline
    ${secundaria ? "bg-gray-200 dark:bg-gray-700" : "bg-gray-100 dark:bg-gray-800"}`} {...props}>
    <div className="grow min-w-max">{ izq }</div>
    <div className="grow flex flex-row flex-wrap gap-3 justify-evenly sm:justify-end items-baseline">{ dcha }</div>
  </div>
)
</code>

En el listado anterior puedes observar que estamos utilizando clases de Tailwind para posicionamiento (''sticky'', ''left-0'', ''flex''), tamaño (''px-6'' para el margen interior horizontal, ''py-2'' para el vertical, ''w-[100vw]'' para que el ancho ocupe toda la pantalla) y colores (como ''bg-gray-200'' y ''dark:bg-gray-700'' para el color de fondo según si el tema oscuro está activado). Además, podemos añadir clases condicionalmente, en este caso, utilizando la propiedad ''secundaria'' para decidir el color de fondo de la barra. Cuando utilicemos el componente ''BarraMenu'', podemos dar propiedades adicionales al elemento ''%%<div>%%'' principal simplemente proporcionándolas al componente, que las captura en el objeto ''props'' y las pasa a su vez al ''%%<div>%%'' con la sintaxis ''{...props}''.

De forma similar, para nuestras listas de tareas construiremos un componente ''Tarjeta'' que represente una tarjeta con una cabecera superior, una región inferior y elementos hijos en forma de lista:

<code javascript>
export const Tarjeta = ({ top, bottom, children, className, ...props }) => (
  <div className={`md:basis-80 md:grow-0 flex flex-col border
    border-gray-600 rounded overflow-hidden bg-gray-100 dark:bg-gray-800
    ${className ?? ""}`} {...props}>
    <span className="p-3 bg-cyan-100 dark:bg-cyan-900 dark:text-white">{ top }</span>
    <ul className="p-3 m-0 list-outside list-none flex-grow">
      { children }
    </ul>
    <span className="p-3">{ bottom }</span>
  </div>
)
</code>

En este caso, permitimos que al utilizar el componente ''Tarjeta'' se añadan clases adicionales, capturando la propiedad ''className'' e insertando su valor, si existe, en la cadena de caracteres que da valor al ''className'' del elemento ''%%<div>%%'' principal.

Cada uno de los elementos hijos, idealmente, será un ''Item'' con un contenido principal y una serie de opciones:

<code javascript>
export const Item = ({ principal, opciones, ...props }) => (
  <li className="flex flex-col bg-gray-200 dark:bg-gray-700 border border-gray-300
    dark:border-gray-600 pl-3 pt-3 mb-3" {...props}>
    <span className="pr-3">{ principal }</span>
    <div className="text-right">
      { opciones }
    </div>
  </li>
)
</code>
===== Composición de componentes y componentes de orden superior =====

===== Prácticas propuestas para el módulo =====

===== Recursos =====

  * [[https://redux-toolkit.js.org/rtk-query/api/created-api/hooks#usequery|Lista completa de propiedades devueltas por useQuery]]
  * [[https://redux-toolkit.js.org/rtk-query/api/created-api/hooks#usemutation|Lista completa de propiedades devueltas por useMutation]]
  * [[https://redux-toolkit.js.org/rtk-query/usage/polling|Cómo funciona el polling en RTK Query]]
  * [[https://redux-toolkit.js.org/rtk-query/usage/automated-refetching|Refresco automático de datos en RTK Query]]q