feat(tutorial): batch updates

- Multilanguage appendix
- Angular +19 updates
- Tutorial admonitions
- Dates appendix

Author: jofaval

docs/appendix/dates.md

@@ -0,0 +1,71 @@
+# Fechas
+
+Uno de los elementos más problemáticos en las aplicaciones son las fechas. Más concretamente, cómo las gestionamos.
+
+Pero podemos afrontarlo de una manera más clara. Vamos a empezar con unas definiciones básicas, veremos por qué hay problemas y la solución que proponemos para que no te supongan un problema en tus aplicaciones.
+
+## Definiciones básicas
+
+Antes de nada, vamos a definir unos conceptos básicos que nos ayudarán a entender mejor el problema.
+
+- **Fecha (Date)**: Una fecha es una representación de un día concreto en el calendario. Por ejemplo, "15 de junio de 2024".
+- **Hora (Time)**: La hora representa un momento específico dentro de un día. - **Zona horaria (Timezone)**: La zona horaria es una región geográfica que tiene la misma hora estándar. Por ejemplo, "CET" (Central European Time) o "GMT" (Greenwich Mean Time).
+- **Fecha y hora (DateTime)**: La combinación de fecha y hora representa un momento específico en el tiempo, incluyendo la zona horaria. Por ejemplo, "15 de junio de 2024 a las 14:30 CET".
+- **Timestamp**: Un timestamp es una representación numérica de un momento específico en el tiempo, generalmente expresado en segundos o milisegundos desde una fecha de referencia (por ejemplo, el 1 de enero de 1970, conocido como la "época Unix").
+
+## Problemas comunes
+
+Al trabajar con fechas y horas, pueden surgir varios problemas comunes:
+
+- **Conversión de zonas horarias**: Si una aplicación maneja usuarios en diferentes zonas horarias, es crucial convertir correctamente las fechas y horas para evitar confusiones.
+- **Formato inconsistente**: Diferentes regiones utilizan diferentes formatos de fecha y hora, lo que puede llevar a errores de interpretación. Ej. DD/MM/AAAA (Europa) vs MM/DD/AAAA (EE.UU.).
+- **Diferencias en el horario de verano**: Las fechas y horas pueden verse afectadas por el horario de verano, lo que puede causar confusiones si no se maneja correctamente.
+- **Errores de cálculo**: Al realizar cálculos con fechas y horas (por ejemplo, sumar días o restar horas), es fácil cometer errores si no se consideran todos los factores relevantes.
+- **Me quita un día**: Es la más común al principio, ¿por qué ocurre esto? La respuesta está en cómo se manejan las zonas horarias y el horario de verano. Cuando le pasamos una fecha, estamos indicándole un día sin zona horaria, por lo que se detecta nuestra zona horaria local y se aplica el desfase correspondiente. GMT+1 en horario estándar y GMT+2 en horario de verano.
+
+Lo importante es recordar que un día en una zona horaria puede no ser el mismo día en otra zona horaria. Por ejemplo, el 15 de junio de 2024 en CET puede ser el 14 de junio de 2024 en GMT, que es por lo que ocurre un descuento de día.
+
+## Solución propuesta
+
+Para evitar estos problemas, os proponemos adheriros al estándar ISO 8601 para representar fechas y horas en vuestras aplicaciones. Este estándar define un formato claro y consistente para las fechas y horas, que incluye la zona horaria.
+
+El formato ISO 8601 para una fecha y hora completa con zona horaria es el siguiente:
+
+```
+AAAA-MM-DDTHH:MM:SS.mmmZ±HH:MM
+```
+
+Por ejemplo, "2024-06-15T14:30:00.000Z+02:00" representa el 15 de junio de 2024 a las 14:30 en la zona horaria GMT+2.
+
+### Backend
+
+En Java, para manejar fechas con ISO 8601 de forma segura, recomendamos el uso de `Date`, así, siempre que le pasen una fecha en formato ISO 8601, se gestionará correctamente la zona horaria.
+
+```java
+import java.util.Date;
+
+// ...
+
+    private Date fecha;
+```
+
+### Frontend
+
+El uso de fechas lo gestionaremos con ISO Date
+
+```javascript
+// Para leer fechas en formato ISO 8601
+const fecha = new Date(`2024-06-15T14:30:00.000Z`);
+
+// Para enviar fechas en formato ISO 8601
+const fechaISO = fecha.toISOString();
+```
+
+## Buenas prácticas
+
+- Siempre utiliza el formato ISO 8601 para representar fechas y horas en tus aplicaciones.
+- Asegúrate de manejar correctamente las zonas horarias al mostrar fechas y horas a los usuarios.
+- Realiza pruebas exhaustivas para verificar que las fechas y horas se manejan correctamente en diferentes escenarios y zonas horarias.
+- Nunca elimines las horas ni la zona horaria al manejar fechas. Siempre trabaja con fechas completas en formato ISO 8601.
+
+Si te cuestionan por qué pasan un día y el servidor entiende otro, explícales que es por la zona horaria y que la solución es usar siempre ISO 8601. De esta manera la consistencia en los datos estará garantizada.

docs/appendix/multilanguage.md

@@ -0,0 +1,72 @@
+# Multidioma
+
+En las aplicaciones reales, un detalle de suma importancia es la capacidad de soportar múltiples idiomas para llegar a una audiencia más amplia. Afortunadamente, tanto en el frontend como en el backend, existen herramientas y bibliotecas que facilitan la implementación de esta funcionalidad.
+
+En especial nos centraremos en el frontend.
+
+## Backend
+
+La comunicación del backend ha de ser agnóstica al idioma del cliente (frontend). Para conseguir este resultado, nos comunicaremos con códigos de error (o éxito). Estableceremos un estándar de códigos que el frontend interpretará y mostrará el mensaje adecuado en función del idioma seleccionado por el usuario.
+
+Para cualquier información extra, por ejemplo, indicar el número máximo de juegos que pueden prestarse. Acordaremos un campo asociado al código de error que contendrá dicha información adicional.
+
+## Frontend
+
+Para el frontend, existen varias bibliotecas que facilitan la implementación de la funcionalidad multilingüe. Usaremos el estándar `i18n` de Angular, que permite definir archivos de traducción para cada idioma soportado. (Guía oficial de Internalización)[https://angular.dev/guide/i18n]
+
+Los términos que has de tener en cuenta en esta nueva etapa son:
+
+- `i18n`: Abreviatura de "internationalization" (internacionalización), donde 18 representa el número de letras entre la 'i' y la 'n'.
+- `locale`: Configuración regional que define el idioma y las convenciones culturales (formato de fecha, moneda, etc.) para una región específica. Ej. `es-ES` para español de España, `en-US` para inglés de Estados Unidos.
+
+### Material
+
+Angular Material también soporta la internacionalización. Para ello, es necesario importar los módulos de localización correspondientes y configurar el proveedor de localización en el módulo principal de la aplicación.
+
+```typescript
+import { MAT_DATE_LOCALE } from "@angular/material/core";
+@NgModule({
+  providers: [
+    { provide: MAT_DATE_LOCALE, useValue: "es-ES" }, // Cambia 'es-ES' por el locale deseado
+  ],
+})
+export class AppModule {}
+```
+
+Esto evitará que tengamos un `Items per page: 10` en inglés en las tablas de paginación de Angular Material.
+
+### Estructura de un fichero de traducciones
+
+Crearemos ficheros de traducciones que contendrán `keys` (los códigos de acceso) y sus correspondientes valores en cada idioma. Por ejemplo, podríamos tener un fichero `en.json` para inglés y otro `es.json` para español.
+
+- translations
+    - en.json
+    - es.json
+
+Aunque solemos preferir nombres más explícitos:
+
+- translations
+    - en-US.json
+    - es-ES.json
+
+Un fichero de traducciones en Angular suele tener la siguiente estructura:
+
+```json
+{
+  "VIEWS": {
+    "HOME": {
+      "TITLE": "Título de la aplicación",
+      "WELCOME_MESSAGE": "Bienvenido a nuestra aplicación",
+      "LOGIN": "Iniciar sesión",
+      "LOGOUT": "Cerrar sesión"
+    },
+    "DASHBOARD": {
+      "TITLE": "Panel de control",
+      "STATISTICS": "Estadísticas",
+      "SETTINGS": "Configuraciones"
+    }
+  }
+}
+```
+
+Ahora ya tienes todo lo necesario para crear aplicaciones multidioma. ¡Manos a la obra!

docs/develop/basic/angular17.md

@@ -55,10 +55,14 @@ Una vez añadida la dependencia, lo que queremos es crear una primera estructura
 
 Para agrupar los componentes comunes de nuestra aplicación vamos a crear una carpeta llamada "core" dentro de la carpeta "src", e iremos creando los componentes que necesitemos. Empecemos con el header. Desde la raíz de nuestro proyecto introducimos el siguiente comando:
 
+
 ```
 ng generate component core/header
 ```
 
+!!! info "Angular 19+"
+    A partir de Angular 19, los elementos se generan sin topología, es decir `*.component.html` -> `*.html`, `*.service.ts` -> `*.ts`, etc.
+
 ### Código de la pantalla
 
 Esto nos creará una carpeta con los ficheros del componente, donde tendremos que copiar el siguiente contenido:
@@ -154,7 +158,10 @@ Esto nos creará una carpeta con los ficheros del componente, donde tendremos qu
     }
     ```
 
-Al utilizar etiquetas de material como `mat-toolbar` o `mat-icon` y `routerLink` necesitaremos importar las dependencias. Al tratarse de un standalone component lo tendremos que hacer directamente en el atributo "imports" de nuestro component en el fichero `header.component.ts`
+Al utilizar etiquetas de material como `mat-toolbar` o `mat-icon` y `routerLink` necesitaremos importar las dependencias. Al tratarse de un standalone component lo tendremos que hacer directamente en el atributo "imports" de nuestro component en el fichero `header.component.ts`.
+
+!!! info "Angular 19+"
+    A partir de Angular 19, los componentes se crean por defecto como `standalone`, para que este no sea el caso debemos indicárselo con `--standalone false`.
 
 === "header.component.ts"
     ``` Typescript hl_lines="3 4 5 12 13 14"
@@ -591,6 +598,9 @@ Si refrescamos el navegador y pulsamos el botón `Nueva categoría`, veremos com
 
 Ahora vamos a darle forma al formulario de editar y crear. Para ello vamos al html, ts y css del componente y pegamos el siguiente contenido:
 
+!!!tip "Errores de validación"
+    Os recomendamos seguir el siguiente formato para los errores de validación en formularios (`ngModel`, `mat-error`)
+
 === "category-edit.component.html"
     ``` HTML
     <div class="container">

docs/exercise.md

@@ -4,6 +4,9 @@ Ahora vamos a ver si has comprendido bien el tutorial. Voy a poner dos ejercicio
 
 Nuestro amigo *Ernesto Esvida* ya tiene disponible su web para gestionar su catálogo de juegos, autores y categorías, pero todavía le falta un poco más para poder hacer buen uso de su ludoteca. Así que nos ha pedido dos funcionalidades extra.
 
+!!!tip "Ten en cuenta"
+	Solo te pedimos que realices las funcionalidades que se indican en los requisitos. No es necesario que completes los anexos antes de que revisemos los resultados.
+
 ## Gestión de clientes
 
 ### Requisitos
@@ -40,6 +43,9 @@ Nos ha pasado el siguiente boceto y requisitos:
 
 ![exercise_3](./assets/images/exercise_3.png)
 
+!!!warning "Atención"
+	Aunque no aparezca en el boceto, como en todas las listas que hemos visto, esperamos que puedan **editarse** los registros. El botón de "Filtrar" tendrá el mismo aspecto visual que el botón de "Nuevo préstamo".
+
 La pantalla tendrá dos zonas:
 
 - Una zona de filtrado donde se permitirá filtrar por:
@@ -83,6 +89,8 @@ Para empezar te daré unos consejos:
 	- Si hiciste el backend en Springboot recuerda revisar [Baeldung](https://www.baeldung.com/spring-data-jpa-query) por si tienes dudas sobre las queries y recuerda que las `Specifications` son muy útiles, pero en este caso deberás implementar otro tipo de operaciones, no te sirve solo con la operación de igualdad `:`, que ya vimos en el tutorial.
 - Implementa la pantalla de alta de préstamo, sin ninguna validación.
 - Cuando ya te funcione, intenta ir añadiendo una a una las validaciones. Algunas de ellas pueden hacerse en frontend, mientras que otras deberán validarse en backend
+- Os recordamos que han de poder crearse y editarse préstamos según las reglas de validación indicadas anteriormente. Aplican las mismas reglas para ambas operaciones.
+- El Backend ha de validar siempre, independientemente de que el Frontend ya lo haya validado. Nunca confíes de manera exclusiva en terceras partes (Frontend o en otro Backend).
 
 
 

mkdocs.yml

@@ -63,6 +63,8 @@ nav:
       - Practiquemos: appendix/docker/traindocker.md
       - Resumen: appendix/docker/summary.md
     - AWS CLI: appendix/aws.md
+    - Multidioma: appendix/multilanguage.md
+    - Fechas: appendix/dates.md
 theme:
     name: material
     language: es