10. Caso de estudio: el cliente React de la aplicación RdvMedecins
10.1. El problema
La aplicación [RdvMedecins] permite programar citas en un consultorio médico. El curso de [NestJS] la escribió como una aplicación HTML, en la que el servidor generaba las páginas. Aquí escribimos la aplicación cliente [React]: las MISMAS páginas, generadas en el navegador a partir de los datos JSON del servidor descrito en el capítulo “El servidor RdvMedecins, una caja negra”.
El cliente debe ofrecer todo lo que ofrecía la aplicación HTML:
- una página de inicio de sesión, protegida por un CAPTCHA, con la opción de crear una cuenta de paciente;
- la agenda de un médico para un día determinado, con reserva de citas (ventana de selección de paciente) y cancelación;
- para el administrador, la gestión de médicos y clientes (listar, agregar, editar, eliminar);
- para el paciente, un panel personal (que muestra las citas futuras, que puede cancelar) y la gestión de su cuenta;
- dos idiomas: francés e inglés;
- URL únicas ([/schedule?doctorId=1&day=...]), que se pueden recargar, guardar en marcadores y recorrer con los botones Atrás/Adelante del navegador.
10.2. Instalación y ejecución
El servidor JSON debe estar instalado y en ejecución (véase el capítulo “El servidor RdvMedecins, una caja negra”). Para usar el cliente en un navegador, no se necesita el modo de prueba del CAPTCHA: se puede dejar el campo [CAPTCHA_TEST] vacío en el archivo [.env] del servidor.
En una ventana de consola abierta en la carpeta [rdvmedecins-react]:
luego abra http://localhost:5173 en un navegador. Las cuentas de demostración aparecen en la página de inicio de sesión (contraseña = login).
Los ejemplos también usan el puerto 5173: primero, detenga el ejemplo que esté en ejecución ([Ctrl-C]). También se puede iniciar el cliente en otro puerto: [npm start -- --port 5174].
10.3. Uso de la aplicación
10.3.1. La página de inicio de sesión

Una contraseña incorrecta: el mensaje aparece al pie de la página y se muestra una nueva imagen (cada imagen solo se puede usar una vez):

10.3.2. La agenda, vista por el administrador y los médicos
Con la sesión iniciada como [admin], se llega a la agenda:

Seleccione un médico y un día, y luego haga clic en “View schedule”. La URL pasa a ser [/schedule?doctorId=1&day=2026-10-05]:

“Book” abre la ventana de reserva. La URL pasa a ser [/schedule?doctorId=1&day=2026-10-05&book=3]: al recargar la página (F5) se vuelve a abrir la misma ventana.

La cita se guarda:

“Cancel” pide confirmación:

Un médico accede directamente a SU PROPIA agenda del día:

10.3.3. El portal del paciente
Un paciente ([martin]) accede a “My area”:

En una agenda, ve “Booked” junto a las franjas de citas de otros pacientes:

Reserva una cita para sí mismo sin seleccionar un paciente:

Su cita aparece bajo su nombre; el botón “Book” ya no está disponible (solo una cita futura), y un mensaje explica el motivo:

Su panel muestra lo siguiente:

“Manage my account”: cualquier cambio requiere la contraseña actual; los errores provienen del servidor:

Si ingresa la dirección /doctors, reservada al administrador:

10.3.4. Gestión de médicos y clientes

Una entrada completada incorrectamente:

Una incorporación exitosa:

Un homónimo:

Se rechaza la solicitud de eliminar a un médico que tiene citas:

10.3.5. Creación de una cuenta
En la página de inicio de sesión, ingrese el CAPTCHA y luego haga clic en “Create a patient account”. El formulario se llenó de forma incorrecta y el servidor lo rechazó:

Una vez creada la cuenta, vuelva a la página de inicio de sesión; los campos de inicio de sesión aparecen ya rellenados:

10.3.6. En francés
Los botones FR / EN traducen la página al instante, sin enviar ninguna solicitud al servidor; el título de la pestaña del navegador también se traduce:

10.3.7. Sesión expirada, dirección desconocida
Si el token expira (o si se elimina la cookie), la siguiente solicitud recibe una respuesta 401; el cliente es redirigido a la página de inicio de sesión:

Una dirección desconocida:

10.4. Arquitectura del cliente
| rdvmedecins-react/
├── package.json, vite.config.ts, tsconfig.json
├── index.html THE page of the application
├── public/favicon.svg the tab icon
└── src/
├── main.tsx the startup
├── router.ts the router, the expired session, the flash messages
├── routes.tsx the pages and their access rights
├── guards.ts the router guards
├── styles.css
├── formatting.ts the formatting
├── api/ the API access layer
├── i18n/ the languages
├── stores/ session, messages, confirmation (Zustand)
├── hooks/ form submission, the captcha
├── components/ the layout and the reusable components
└── pages/ the pages
|

La siguiente tabla compara la aplicación HTML del curso [NestJS] con este cliente:
Aplicación HTML (NestJS) | Cliente React |
El servidor genera cada página ([res.render]) | El servidor devuelve JSON; los componentes de [src/pages/] generan las páginas |
[views/layout.hbs] y sus vistas parciales | [Layout.tsx] y los componentes de [src/components/] |
las rutas del controlador ([@Controller('schedule')]) | rutas del cliente ([routes.tsx]); el servidor solo tiene rutas /api/... |
[JwtAuthGuard] y [RolesGuard] redirigen a /login o a una página 403 | guardias del enrutador; el servidor mantiene sus propios guardias, que devuelven 401 o 403 |
mensaje flash en una cookie | mensaje flash en un store, [useMessages] |
diccionarios leídos por el servidor, helper [{{t}}] | diccionarios en el cliente, [i18next]; el servidor devuelve solo claves |
idioma almacenado en una cookie | idioma almacenado en [localStorage] |
formulario rechazado: el servidor recarga la página | formulario rechazado: respuesta 400/409; el cliente muestra los errores debajo de los campos |
Ventana de confirmación: un pequeño script, [public/js/app.js] | un store y un componente, [ConfirmDialog] |
La aplicación funciona sin JavaScript | La aplicación ES JavaScript |
Los clientes [Vue.js] y [Angular] de las lecciones anteriores tienen exactamente la misma estructura: los "stores" de [Pinia] y los servicios de [Angular] son aquí stores de [Zustand]; los "composables" son los hooks y las vistas son las páginas.
A continuación se enumeran todos los archivos del cliente. Están ampliamente comentados; sus comentarios forman parte del curso.
10.4.1. Configuración del proyecto
10.4.1.1. package.json
| {
"name": "rdvmedecins-react",
"private": true,
"version": "1.0.0",
"description": "React client of the medical appointment booking application [RdvMedecins] - client of the JSON server [rdvmedecins-nestjs-json]",
"type": "module",
"scripts": {
"start": "vite",
"build": "tsc --noEmit && vite build",
"preview": "vite preview"
},
"dependencies": {
"@tanstack/react-query": "^5.104.0",
"bootstrap": "^5.3.8",
"i18next": "^26.4.2",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"react-i18next": "^17.0.15",
"react-router": "^8.4.0",
"zustand": "^5.0.15"
},
"devDependencies": {
"@types/react": "^19.2.18",
"@types/react-dom": "^19.2.7",
"@vitejs/plugin-react": "^6.1.1",
"typescript": "~6.0.2",
"vite": "^8.3.0"
}
}
|
- Líneas 8–10: [npm start] inicia el servidor de desarrollo; [npm run build] verifica los tipos ([tsc --noEmit], véase más adelante) Y LUEGO construye la versión de producción; [npm run preview] sirve la versión construida para probarla;
- Líneas 12–21: las bibliotecas que usa la aplicación: [React], [React Router], [TanStack Query], [Zustand], [i18next], [Bootstrap];
- Líneas 22–28: herramientas de desarrollo: [Vite] y su extensión para [React], [TypeScript] y los tipos de [React].
No hay ninguna biblioteca de formularios ([React Hook Form], ejemplo 08): como en el ejemplo 25, todas las reglas de validación de las entradas las verifica el servidor y el cliente se limita a mostrar los resultados.
10.4.1.2. vite.config.ts
| // =========================================================================
// vite.config.ts - la herramienta de compilación del cliente
// -------------------------------------------------------------------------
// - npm start : el servidor de desarrollo (http://localhost:5173),
// que reenvía /api/... al servidor JSON (puerto 8080);
// - npm run build : la aplicación compilada, en dist/;
// - npm run preview: sirve dist/ (con el mismo proxy), para probarla.
// =========================================================================
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
// el proxy: páginas y API tienen así el MISMO origen (localhost:5173); la
// cookie httpOnly del token circula sin ninguna configuración, y sin CORS
const proxy = { '/api': 'http://localhost:8080' };
export default defineConfig({
plugins: [react()],
server: { port: 5173, proxy },
preview: { port: 4173, proxy },
// en producción: el código de las bibliotecas (React, React Router,
// i18next...) en UN archivo aparte, "libraries-XXXX.js". Rara vez
// cambia: el navegador lo conserva en su caché de una versión a la siguiente.
build: {
rolldownOptions: {
output: { codeSplitting: { groups: [{ name: 'libraries', test: /node_modules/ }] } },
},
},
});
|
- Línea 15: el proxy del ejemplo 22: las solicitudes /api/... se reenvían al servidor JSON;
- línea 19: el servidor de desarrollo;
- línea 20: el servidor de [npm run preview], con el mismo proxy;
- líneas 24–28: en producción, el código de las bibliotecas se guarda en un archivo aparte (véase el capítulo “Despliegue”).
10.4.1.3. tsconfig.json
| {
"compilerOptions": {
"target": "ES2023",
"lib": ["ES2023", "DOM", "DOM.Iterable"],
"module": "ESNext",
"moduleResolution": "bundler",
"types": ["vite/client"],
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noImplicitReturns": true,
"verbatimModuleSyntax": true,
"erasableSyntaxOnly": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"noEmit": true
},
"include": ["src", "vite.config.ts"]
}
|
- línea 8: JSX se compila en llamadas a [jsx(...)], que se importan automáticamente: no es necesario [import React] en cada archivo;
- línea 9: el modo estricto de [TypeScript];
- línea 14: una importación usada solo para tipos se escribe como [import type]: desaparece durante la compilación;
- línea 15: solo se permite la sintaxis de [TypeScript] que simplemente se puede ELIMINAR para obtener [JavaScript] (sin [enum], sin parámetros de propiedad): esto es lo que hace [Vite], que no verifica los tipos;
- Línea 16: importación de los archivos JSON (los diccionarios);
- línea 18: [TypeScript] no genera ningún archivo: solo VERIFICA ([tsc --noEmit]); [Vite] es quien compila.
10.4.2. Inicio de la aplicación
10.4.2.1. index.html
| <!doctype html>
<!--
index.html - LA página de la aplicación (Single Page Application).
El servidor nunca envía otra: todo lo demás lo construye React en el
navegador, dentro de <div id="root">. lang y title los actualiza
la aplicación según el idioma y la página mostrada.
-->
<html lang="en">
<head>
<meta charset="utf-8">
<title>RdvMedecins</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
</head>
<body>
<div id="root"></div>
<!-- sin JavaScript, una aplicación React no puede mostrar nada: lo indicamos -->
<noscript>RdvMedecins requires JavaScript. / RdvMedecins a besoin de JavaScript.</noscript>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
|
- línea 16: el elemento donde [React] muestra la aplicación;
- línea 18: sin [JavaScript], una aplicación [React] no puede mostrar nada: así se indica;
- línea 19: el punto de entrada de la aplicación. Durante el desarrollo, [Vite] compila [main.tsx] bajo demanda; en producción, esta línea se reemplaza por el archivo compilado (véase el capítulo “Despliegue”).
10.4.2.2. src/main.tsx
| // =========================================================================
// main.tsx - el arranque de la aplicación
// -------------------------------------------------------------------------
// - las hojas de estilo (Bootstrap, styles.css);
// - i18next (francés e inglés);
// - TanStack Query, que lee los datos del servidor: sus solicitudes fallidas
// muestran su mensaje en el panel de errores, en UN solo lugar
// (excepto las que declaran manejar ellas mismas su error:
// meta.errorHandled);
// - el enrutador, que muestra la página de la dirección actual.
// =========================================================================
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryCache, QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { RouterProvider } from 'react-router/dom';
import 'bootstrap/dist/css/bootstrap.min.css';
import './styles.css';
import './i18n/i18n';
import { useMessages } from './stores/messages';
import { router } from './router';
const queryClient = new QueryClient({
queryCache: new QueryCache({
onError: (error, query) => {
if (!query.meta?.errorHandled) {
useMessages.getState().showApiError(error);
}
},
}),
defaultOptions: {
queries: {
retry: false, // un error se muestra de inmediato, sin un nuevo intento
refetchOnWindowFocus: false, // sin nueva lectura al volver a la pestaña
},
},
});
createRoot(document.getElementById('root')!).render(
<StrictMode>
<QueryClientProvider client={queryClient}>
<RouterProvider router={router} />
</QueryClientProvider>
</StrictMode>,
);
|
- líneas 17–19: las hojas de estilo, seguidas de la configuración de [i18next], que se ejecuta una sola vez al cargar el módulo;
- líneas 23–37: el cliente de [TanStack Query] (ejemplo 24), con dos ajustes:
- líneas 24–30: [onError] se invoca para CADA solicitud fallida: su mensaje de error se muestra en el área de errores, en un único lugar. Una consulta que maneja su propio error lo declara en sus metadatos: [meta: { errorHandled: true }];
- Líneas 33–34: por defecto, [TanStack Query] reintenta tres veces una solicitud fallida y recarga los datos al volver a la pestaña: aquí, un error se muestra de inmediato y los datos cambian solo cuando se solicita;
- línea 42: el enrutador (construido en [router.ts]) muestra la página correspondiente a la dirección actual.
10.4.2.3. src/router.ts
| // =========================================================================
// router.ts - el enrutador de la aplicación y lo que depende de él
// -------------------------------------------------------------------------
// El enrutador se crea aquí, fuera de cualquier componente, para que dos
// mecanismos puedan usarlo:
// 1. la respuesta 401 de una solicitud protegida (sesión expirada): se
// olvida al usuario, se prepara el mensaje y se va a la
// página de inicio de sesión (ver api/client.ts);
// 2. los mensajes "flash": al final de CADA navegación, los mensajes
// de la página anterior desaparecen y aparecen los dejados para la siguiente
// página (ver stores/messages.ts).
// =========================================================================
import { createBrowserRouter } from 'react-router';
import { routes } from './routes';
import { whenSessionExpired } from './api/client';
import { useSession } from './stores/session';
import { useMessages } from './stores/messages';
export const router = createBrowserRouter(routes);
// 1. la sesión expirada
whenSessionExpired(() => {
useSession.getState().forget();
useMessages.getState().flash('error', 'ERRORS.SESSION_EXPIRED');
router.navigate('/login');
});
// 2. subscribe: la función se llama en cada cambio del estado del
// enrutador. Una navegación ha TERMINADO cuando ya no está en curso
// (idle) y la dirección ha cambiado (cada dirección visitada tiene una clave única,
// location.key - incluso cuando solo cambian los parámetros: /schedule?...)
let locationKey = router.state.location.key;
router.subscribe((state) => {
if (state.navigation.state === 'idle' && state.location.key !== locationKey) {
locationKey = state.location.key;
useMessages.getState().newPage();
}
});
|
- línea 20: el enrutador, en modo “data” (ejemplo 17), se crea FUERA de cualquier componente: el código que no es un componente puede así usarlo ([router.navigate]);
- líneas 23–27: qué hacer cuando una solicitud protegida recibe una respuesta 401 (véase [api/client.ts]): olvidar al usuario, preparar el mensaje para la página siguiente, ir a la página de inicio de sesión;
- líneas 33–39: [router.subscribe(function)]: la función se invoca cada vez que cambia el estado del enrutador. Al final de cada navegación, desaparecen los mensajes de la página anterior y aparecen los mensajes “flash” (véase [stores/messages.ts]).
10.4.2.4. src/styles.css
| /* =========================================================================
styles.css - algunos ajustes sobre Bootstrap
(tomados de public/css/styles.css de la aplicación HTML)
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* -------------------------------------------------------------------------
.error-panel: los mensajes de error, al pie de la página, sobre un fondo
rosa claro (ver components/ErrorPanel.tsx).
position: sticky + bottom: si la página es más alta que la ventana, el
panel queda pegado al pie de la ventana en lugar de desaparecer debajo del
pliegue, sin cubrir nunca el contenido cuando la página
es corta. z-index: por encima del fondo gris de los diálogos modales.
pointer-events: none: el panel no contiene nada en lo que se pueda hacer clic; si
se superpone a un botón, el clic lo atraviesa.
------------------------------------------------------------------------- */
.error-panel {
position: sticky;
bottom: 1rem;
z-index: 1060;
pointer-events: none;
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef; /* rosa claro */
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
/* las dos opciones principales de la página "Mi área" del paciente */
.option-card {
transition: border-color 0.15s, box-shadow 0.15s;
}
.option-card:hover {
border-color: #0d6efd;
box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}
/* la imagen del captcha (SVG de 150 x 50 píxeles), insertada mediante dangerouslySetInnerHTML:
un estilo de la hoja global, como todos los demás */
.captcha-image svg {
display: block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
|
La hoja de estilo de la aplicación HTML, reproducida casi textualmente. El único punto a destacar es el área de errores (líneas 24–35), que se coloca en la parte inferior de la ventana cuando la página es alta.
10.4.3. La capa de acceso a la API
10.4.3.1. src/api/types.ts
| // =========================================================================
// api/types.ts - los objetos JSON intercambiados con el servidor
// -------------------------------------------------------------------------
// La traducción, a interfaces de TypeScript, de la API descrita en el capítulo
// "El servidor, una caja negra". El compilador verifica así que el cliente
// solo use campos que realmente existen.
// =========================================================================
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';
// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
export interface User {
login: string;
name: string; // nombre para mostrar: "Marie PELISSIER"
role: Role;
}
// GET /api/captcha
export interface Captcha {
id: string;
svg: string;
}
// un título, un nombre, un apellido
export interface Identity {
title: string;
firstName: string;
lastName: string;
}
// un médico o un cliente: GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
id: number;
version: number; // bloqueo optimista: se reenvía con una actualización
login?: string; // solo para el ADMIN
}
// lo que se envía para crear / actualizar una persona (ADMIN)
export interface PersonData extends Identity {
login: string; // '' = valor por defecto (creación) o sin cambios (actualización)
password: string; // igual
version?: number;
}
export interface Slot {
id: number;
startHour: number;
startMinute: number;
endHour: number;
endMinute: number;
}
// una fila de la agenda, con los DERECHOS del usuario conectado
export interface ScheduleSlot extends Slot {
free: boolean;
patient: Identity | null; // null: libre, u ocupada por otro paciente
mine: boolean; // la cita del paciente conectado
bookable: boolean;
appointmentId: number | null; // se completa si el usuario puede cancelar
}
// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
doctor: Person;
day: string; // "yyyy-MM-dd"
slots: ScheduleSlot[];
info: string | null; // clave de traducción (paciente que ya tiene una cita)
}
// GET /api/my-area
export interface MyArea {
patient: Identity;
appointments: { id: number; day: string; slot: Slot; doctor: Person }[];
}
// GET /api/my-account
export interface MyAccount extends Identity {
login: string;
version: number;
}
// PUT /api/my-account
export interface MyAccountUpdate extends Identity {
login: string;
password: string; // '' = sin cambios
confirmation: string;
currentPassword: string;
version: number;
}
// POST /api/register
export interface Registration extends Identity {
login: string;
password: string;
confirmation: string;
}
|
Los objetos JSON de la API, descritos en el capítulo “El servidor RdvMedecins: una caja negra”, traducidos a interfaces de [TypeScript]:
- líneas 25–29: un título, un nombre, un apellido: lo que tienen en común los médicos, los clientes y los pacientes al pedir citas;
- líneas 32–36: un médico o un cliente. [version]: el bloqueo optimista del servidor; una modificación devuelve la versión leída: si alguien modificó el registro mientras tanto, el servidor la rechaza ([ERRORS.CONCURRENT_UPDATE]);
- líneas 54–60: una entrada de la agenda. El servidor indica los DERECHOS del usuario conectado: [bookable], [appointmentId] (se rellena si el usuario puede cancelar); el cliente no necesita recalcularlos;
- Línea 67: una clave de traducción, para los pacientes que ya tienen una cita.
10.4.3.2. src/api/api-error.ts
| // =========================================================================
// api/api-error.ts - UNA sola clase para todos los errores de la API
// -------------------------------------------------------------------------
// Tomado de common/api-error.ts de los ejemplos. Todo error de una solicitud
// (respuesta 4xx / 5xx del servidor, servidor inaccesible, respuesta de un proxy)
// se convierte en un ApiError, que lleva la CLAVE de traducción del mensaje, sus
// parámetros y el error de cada campo de un formulario rechazado.
// =========================================================================
export class ApiError extends Error {
readonly statusCode: number; // 0: el servidor no respondió
readonly key: string; // clave de traducción: 'ERRORS.LOGIN_TAKEN'
readonly params: Record<string, string>;
readonly fields: Record<string, string>; // error de cada campo
constructor(statusCode: number, key: string, params: Record<string, string> = {}, fields: Record<string, string> = {}) {
super(key);
this.name = 'ApiError';
this.statusCode = statusCode;
this.key = key;
this.params = params;
this.fields = fields;
}
}
// una respuesta de error (4xx, 5xx) -> un ApiError
export async function fromResponse(response: Response): Promise<ApiError> {
let body: { key?: string; params?: Record<string, string>; fields?: Record<string, string> } = {};
try {
const json: unknown = await response.json();
if (typeof json === 'object' && json !== null) {
body = json;
}
} catch {
// no es JSON: no fue nuestro servidor quien respondió
}
return new ApiError(
response.status,
// sin clave: no fue nuestro servidor quien respondió, sino un proxy
// (Vite: 500 o 502 sin cuerpo JSON; nginx: 502, 504...)
body.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR'),
body.params,
body.fields,
);
}
|
La clase [ApiError] del ejemplo 24, sin cambios: CUALQUIER error de solicitud se convierte en un [ApiError], que contiene la clave de traducción del mensaje, sus parámetros y el error de cada campo en un formulario rechazado.
10.4.3.3. src/api/client.ts
| // =========================================================================
// api/client.ts - TODAS las solicitudes a la API pasan por aquí
// -------------------------------------------------------------------------
// Tomado de common/api.ts de los ejemplos, con una novedad: el manejo
// centralizado de la respuesta 401.
//
// Un 401 puede ocurrir en cualquier momento: el token ha expirado (2 horas), la
// cuenta ha sido eliminada, el servidor se ha reiniciado con otra clave
// secreta... En lugar de manejar este caso en cada componente, lo manejamos
// AQUÍ, una sola vez. Pero este archivo no conoce ni el enrutador ni los
// mensajes (no depende de nada): llama a una función que se le entregó
// al arrancar (whenSessionExpired, ver router.ts), que olvida
// al usuario y redirige a la página de inicio de sesión.
//
// Algunas solicitudes manejan su 401 por sí mismas (el inicio de sesión, GET
// /api/auth/me...): son "public" (ver rdvmedecins.api.ts).
// =========================================================================
import { fromResponse, ApiError } from './api-error';
// qué hacer cuando el servidor responde 401 a una solicitud protegida
let sessionExpired: () => void = () => {};
export function whenSessionExpired(action: () => void): void {
sessionExpired = action;
}
export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
// isPublic: true para las rutas que manejan el 401 por sí mismas
export async function request<T>(method: Method, url: string, body?: unknown, isPublic = false): Promise<T> {
let response: Response;
try {
response = await fetch(`/api${url}`, {
method,
headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
body: body === undefined ? undefined : JSON.stringify(body),
});
} catch {
// sin respuesta: red caída, servidor detenido
throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
}
if (!response.ok) {
const error = await fromResponse(response);
if (error.statusCode === 401 && !isPublic) {
sessionExpired();
}
throw error;
}
return (await response.json()) as T;
}
|
La función [request] del ejemplo 24, con una novedad: la respuesta 401.
- Líneas 22–26: la función que se debe invocar cuando una solicitud protegida recibe una respuesta 401. Este archivo no tiene dependencias (ni del enrutador ni de los mensajes): [router.ts] le asigna esta función al iniciar. Así se evita una dependencia circular (el cliente importa el enrutador, que importa las rutas, que importan las páginas, que importan el cliente...);
- línea 31: algunas solicitudes manejan sus propios errores 401: el inicio de sesión (contraseña incorrecta: 401), [GET /api/auth/me] (nadie ha iniciado sesión: 401)...;
- Líneas 45–47: una solicitud protegida recibe un 401: la sesión ha expirado. Esto se notifica, LUEGO se rechaza la promesa como con cualquier otro error: el componente que espera la respuesta no tiene ninguna acción específica que realizar.
10.4.3.4. src/api/rdvmedecins.api.ts
| // =========================================================================
// api/rdvmedecins.api.ts - una función por ruta de la API
// -------------------------------------------------------------------------
// La "data access layer" del cliente: los componentes llaman a estas
// funciones tipadas, sin saber nada de URL, fetch ni JSON. Si
// la API cambia, solo cambia este archivo.
// Cada función devuelve una PROMESA: los componentes encadenan las
// solicitudes con async / await. En caso de fallo, la promesa se rechaza
// con un ApiError (ver client.ts).
// =========================================================================
import { request } from './client';
import type {
Schedule,
Captcha,
PersonData,
Registration,
MyAccountUpdate,
MyAccount,
MyArea,
Person,
User,
} from './types';
// /api/doctors o /api/clients: ambos se manejan de la misma manera
export type PersonType = 'doctors' | 'clients';
type Empty = Record<string, never>;
export const api = {
// ------------------------------------------------ inicio de sesión (rutas públicas)
captcha: () => request<Captcha>('GET', '/captcha', undefined, true),
me: () => request<User>('GET', '/auth/me', undefined, true),
logIn: (login: string, password: string, captchaId: string, captcha: string) =>
request<User>('POST', '/auth/login', { login, password, captchaId, captcha }, true),
logOut: () => request<Empty>('POST', '/auth/logout', {}, true),
// ------------------------------------------------ creación de cuenta (pública)
registrationAccess: (captchaId: string, captcha: string) =>
request<Empty>('POST', '/register/access', { captchaId, captcha }, true),
registrationAccessStatus: () => request<{ valid: boolean }>('GET', '/register/access', undefined, true),
register: (data: Registration) => request<{ login: string }>('POST', '/register', data, true),
// ------------------------------------------------ agenda y citas
// doctorId null: para un médico conectado, SU agenda
schedule(doctorId: number | null, day: string) {
const params = new URLSearchParams({ day });
if (doctorId !== null) {
params.set('doctorId', String(doctorId));
}
return request<Schedule>('GET', `/schedule?${params}`);
},
book: (day: string, slotId: number, clientId: number | null) =>
request<{ id: number }>('POST', '/appointments', { day, slotId, clientId: clientId ?? undefined }),
cancelAppointment: (appointmentId: number) => request<Empty>('DELETE', `/appointments/${appointmentId}`),
// ------------------------------------------------ médicos y clientes
list: (type: PersonType) => request<Person[]>('GET', `/${type}`),
read: (type: PersonType, id: number) => request<Person>('GET', `/${type}/${id}`),
add: (type: PersonType, data: PersonData) => request<Person>('POST', `/${type}`, data),
edit: (type: PersonType, id: number, data: PersonData) => request<Person>('PUT', `/${type}/${id}`, data),
remove: (type: PersonType, id: number) => request<Empty>('DELETE', `/${type}/${id}`),
// ------------------------------------------------ el área del paciente
myArea: () => request<MyArea>('GET', '/my-area'),
myAccount: () => request<MyAccount>('GET', '/my-account'),
editMyAccount: (data: MyAccountUpdate) => request<User>('PUT', '/my-account', data),
deleteMyAccount: (currentPassword: string) => request<Empty>('DELETE', '/my-account', { currentPassword }),
};
|
Una función por cada ruta de la API, tipada: los componentes invocan [api.schedule(1, '2026-10-05')] sin saber nada de la URL ni del JSON. Si la API cambia, solo cambia este archivo.
- líneas 32–36: las rutas de conexión, que son públicas (último parámetro de [request]: [true]);
- líneas 39–42: la creación de la cuenta, en dos pasos: resolver el CAPTCHA en la página de inicio de sesión proporciona un “pase” (una cookie), que la ruta [POST /api/register] exige;
- líneas 46–52: [URLSearchParams] genera los parámetros de la dirección (y los codifica). Para un médico conectado, no hay [doctorId]: el servidor devuelve SU agenda;
- línea 54: un paciente reserva para sí mismo: sin [clientId]. [JSON.stringify] omite las propiedades [undefined];
- líneas 58–62: los médicos y los clientes se manejan de la misma manera: el tipo es un parámetro;
- línea 28: el tipo de un objeto vacío [{}], que devuelven algunas rutas.
10.4.4. Idiomas
10.4.4.1. src/i18n/i18n.ts
| // =========================================================================
// i18n/i18n.ts - francés e inglés (i18next, ver ejemplo 21)
// -------------------------------------------------------------------------
// Los diccionarios fr.json y en.json son los del curso de NestJS
// (i18n/*.json), completados con algunas claves específicas del cliente
// (ERRORS.SERVER_UNREACHABLE...). El servidor JSON solo devuelve CLAVES
// ('ERRORS.LOGIN_TAKEN'): son las mismas que las de los diccionarios.
//
// El idioma elegido se guarda en localStorage (una preferencia, no un dato
// sensible); en su defecto, se usa el idioma del navegador.
// =========================================================================
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';
export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
const STORAGE_KEY = 'rdvmedecins.language';
function initialLanguage(): Language {
try {
const stored = localStorage.getItem(STORAGE_KEY);
if (stored === 'fr' || stored === 'en') {
return stored;
}
} catch {
// localStorage no disponible (navegación privada estricta...): no importa
}
return navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en';
}
// en cada cambio de idioma: se guarda y se actualiza el atributo
// lang de la página (lectores de pantalla, correctores ortográficos, separación silábica)
i18n.on('languageChanged', (language) => {
document.documentElement.lang = language;
try {
localStorage.setItem(STORAGE_KEY, language);
} catch {
// sin importancia
}
});
i18n.use(initReactI18next).init({
// los diccionarios forman parte del código de la aplicación: sin solicitud
resources: { fr: { translation: fr }, en: { translation: en } },
lng: initialLanguage(),
fallbackLng: 'en',
interpolation: { escapeValue: false }, // React ya escapa todo
});
export default i18n;
|
La configuración del ejemplo 21:
- líneas 22–32: el idioma almacenado y, si no hay, el idioma del navegador. El acceso a [localStorage] puede fallar (navegación privada estricta): [try / catch];
- líneas 36–43: cada vez que cambia el idioma, se guarda y se actualiza el atributo [lang] de la página;
- línea 47: los diccionarios, importados como módulos, forman parte del código compilado y no requieren solicitudes adicionales;
- línea 50: [React] ya escapa todo lo que muestra: no hace falta hacerlo dos veces.
No existe un equivalente de la “estrategia de título” de [Angular]: cada página declara su título con la etiqueta [<title>], que [React] 19 coloca en el encabezado del documento (véase [components/PageTitle.tsx]).
10.4.4.2. Diccionarios
Los diccionarios [fr.json] y [en.json] son los de la aplicación HTML del curso [NestJS], complementados con algunas claves propias del cliente ([ERRORS.SERVER_UNREACHABLE]...). Su sintaxis de parámetros, [{{min}}], es exactamente la misma que la de [i18next]. El servidor JSON devuelve las mismas claves.
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace",
"LOADING": "Chargement...",
"LANGUAGE": "Langue"
},
"LOGIN": {
"TITLE": "Connexion",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"SUBMIT": "Se connecter",
"ERROR": "Login ou mot de passe incorrect.",
"DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
"DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
"DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
"DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
"CREATE_ACCOUNT": "Créer un compte client",
"CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Médecin",
"CHOOSE_DOCTOR": "-- choisir un médecin --",
"DAY_LABEL": "Jour",
"VIEW_SCHEDULE": "Voir l'agenda"
},
"SCHEDULE": {
"PAGE_TITLE": "Agenda",
"TITLE_PREFIX": "Agenda du",
"COLUMN_SLOT": "Créneau",
"COLUMN_STATUS": "Statut",
"FREE": "Libre",
"BOOK": "Réserver",
"CANCEL_APPOINTMENT": "Annuler",
"CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
"EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
"NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
"BOOKED": "Rendez-vous enregistré.",
"CANCELLED": "Rendez-vous annulé.",
"BOOKED_BY_OTHER": "Réservé",
"ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
},
"BOOKING_DIALOG": {
"TITLE": "Réserver ce créneau",
"CLOSE_ARIA": "Fermer",
"SLOT": "Créneau de {{time}}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choisir un patient --",
"CANCEL": "Annuler",
"CONFIRM": "Confirmer"
},
"PERSONS": {
"COLUMN_TITLE": "Titre",
"COLUMN_FIRSTNAME": "Prénom",
"COLUMN_LASTNAME": "Nom",
"COLUMN_LOGIN": "Login",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"SAVE": "Enregistrer",
"BACK": "Retour à la liste",
"TITLE_LABEL": "Titre",
"FIRSTNAME_LABEL": "Prénom",
"LASTNAME_LABEL": "Nom",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
"LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
"PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"ACCOUNT_SECTION": "Compte utilisateur"
},
"DOCTORS": {
"TITLE": "Médecins",
"ADD": "Ajouter un médecin",
"EDIT": "Modifier un médecin",
"EMPTY": "Aucun médecin.",
"DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
"ADDED": "Le médecin {{name}} a été ajouté (login : {{login}}).",
"UPDATED": "Le médecin {{name}} a été modifié.",
"DELETED": "Le médecin {{name}} a été supprimé."
},
"CLIENTS": {
"TITLE": "Clients",
"ADD": "Ajouter un client",
"EDIT": "Modifier un client",
"EMPTY": "Aucun client.",
"DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
"ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
"UPDATED": "Le client {{name}} a été modifié.",
"DELETED": "Le client {{name}} a été supprimé."
},
"ERROR_PAGE": {
"TITLE": "Erreur",
"BACK": "Retour à l'accueil"
},
"ERRORS": {
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
"SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
"DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
"APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
"INVALID_DATE": "La date demandée n'est pas valide.",
"CHOOSE_PATIENT": "Choisissez un patient.",
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"BAD_REQUEST": "La requête est invalide.",
"FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
"NOT_FOUND": "Cette page n'existe pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
"TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s).",
"WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
"TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {{minutes}} minute(s).",
"LOGIN_REQUIRED": "Le login est obligatoire.",
"PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
"PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {{min}} caractères.",
"CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
"PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
"CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
"WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
"PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
"CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client ».",
"AUTH_REQUIRED": "Connectez-vous pour accéder à cette page.",
"JSON_REQUIRED": "Requête refusée : le serveur attend du JSON.",
"SERVER_UNREACHABLE": "Le serveur ne répond pas. Réessayez plus tard."
},
"CAPTCHA": {
"LABEL": "Recopiez les caractères de l'image",
"IMAGE_ALT": "Image de vérification anti-robots",
"NEW_IMAGE": "Autre image",
"HELP": "Majuscules ou minuscules, peu importe."
},
"REGISTRATION": {
"TITLE": "Créer un compte client",
"INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
"LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_HELP": "Au moins {{min}} caractères.",
"SUBMIT": "Créer mon compte",
"BACK_TO_LOGIN": "Retour à la connexion",
"DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {{login}}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirmation du mot de passe"
},
"AREA": {
"TITLE": "Mon espace",
"HELLO": "Bonjour {{name}}",
"MANAGE_ACCOUNT": "Gérer mon compte",
"MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
"VIEW_SCHEDULE": "Voir un agenda",
"VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
"MY_APPOINTMENT": "Mon rendez-vous",
"SEE_IN_SCHEDULE": "voir dans l'agenda",
"CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
"NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
},
"MY_ACCOUNT": {
"TITLE": "Gérer mon compte",
"NEW_PASSWORD_LABEL": "Nouveau mot de passe",
"CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
"CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
"BACK": "Retour à mon espace",
"DELETE_TITLE": "Supprimer mon compte",
"DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
"DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
"DELETE_SUBMIT": "Supprimer mon compte",
"UPDATED": "Votre compte a été modifié.",
"DELETED": "Votre compte a été supprimé."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "Non, revenir",
"YES": "Oui, confirmer"
}
}
|
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Log out",
"MENU_SCHEDULE": "Schedule",
"MENU_DOCTORS": "Doctors",
"MENU_PATIENTS": "Patients",
"MENU_MY_AREA": "My area",
"LOADING": "Loading...",
"LANGUAGE": "Language"
},
"LOGIN": {
"TITLE": "Login",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"SUBMIT": "Log in",
"ERROR": "Incorrect login or password.",
"DEMO_ACCOUNTS": "Demo accounts (password = login):",
"DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
"DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
"DEMO_USER": "USER role (patients): booking for themselves, managing their account",
"CREATE_ACCOUNT": "Create a patient account",
"CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Doctor",
"CHOOSE_DOCTOR": "-- choose a doctor --",
"DAY_LABEL": "Day",
"VIEW_SCHEDULE": "View schedule"
},
"SCHEDULE": {
"PAGE_TITLE": "Schedule",
"TITLE_PREFIX": "Schedule for",
"COLUMN_SLOT": "Slot",
"COLUMN_STATUS": "Status",
"FREE": "Free",
"BOOK": "Book",
"CANCEL_APPOINTMENT": "Cancel",
"CANCEL_CONFIRM": "Cancel this appointment?",
"EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
"NO_SLOTS": "This doctor has no time slots.",
"BOOKED": "Appointment booked.",
"CANCELLED": "Appointment cancelled.",
"BOOKED_BY_OTHER": "Booked",
"ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
},
"BOOKING_DIALOG": {
"TITLE": "Book this slot",
"CLOSE_ARIA": "Close",
"SLOT": "Slot {{time}}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choose a patient --",
"CANCEL": "Cancel",
"CONFIRM": "Confirm"
},
"PERSONS": {
"COLUMN_TITLE": "Title",
"COLUMN_FIRSTNAME": "First name",
"COLUMN_LASTNAME": "Last name",
"COLUMN_LOGIN": "Login",
"EDIT": "Edit",
"DELETE": "Delete",
"SAVE": "Save",
"BACK": "Back to the list",
"TITLE_LABEL": "Title",
"FIRSTNAME_LABEL": "First name",
"LASTNAME_LABEL": "Last name",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
"LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
"PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
"PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
"ACCOUNT_SECTION": "User account"
},
"DOCTORS": {
"TITLE": "Doctors",
"ADD": "Add a doctor",
"EDIT": "Edit a doctor",
"EMPTY": "No doctors.",
"DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
"ADDED": "Doctor {{name}} has been added (login: {{login}}).",
"UPDATED": "Doctor {{name}} has been updated.",
"DELETED": "Doctor {{name}} has been deleted."
},
"CLIENTS": {
"TITLE": "Patients",
"ADD": "Add a patient",
"EDIT": "Edit a patient",
"EMPTY": "No patients.",
"DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
"ADDED": "Patient {{name}} has been added (login: {{login}}).",
"UPDATED": "Patient {{name}} has been updated.",
"DELETED": "Patient {{name}} has been deleted."
},
"ERROR_PAGE": {
"TITLE": "Error",
"BACK": "Back to the home page"
},
"ERRORS": {
"LOGIN_TAKEN": "This login is already used by another account.",
"DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
"PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
"DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
"SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
"CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
"DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
"PATIENT_NOT_FOUND": "This patient does not exist (any more).",
"SLOT_NOT_FOUND": "This slot does not exist (any more).",
"APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
"INVALID_DATE": "The requested date is not valid.",
"CHOOSE_PATIENT": "Choose a patient.",
"INVALID_FORM": "The form contains errors.",
"INVALID_TITLE": "Choose a title from the list.",
"FIRSTNAME_REQUIRED": "The first name is required.",
"FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
"LASTNAME_REQUIRED": "The last name is required.",
"LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
"INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
"SESSION_EXPIRED": "Your session has expired: please log in again.",
"BAD_REQUEST": "The request is invalid.",
"FORBIDDEN": "Your role does not allow you to access this page.",
"NOT_FOUND": "This page does not exist.",
"SERVER_ERROR": "An unexpected error occurred. Please try again later.",
"TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s).",
"WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
"TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {{minutes}} minute(s).",
"LOGIN_REQUIRED": "The login is required.",
"PASSWORD_REQUIRED": "The password is required.",
"PASSWORD_TOO_SHORT": "The password must be at least {{min}} characters long.",
"CONFIRMATION_REQUIRED": "Please confirm the password.",
"PASSWORDS_DIFFER": "The confirmation does not match the password.",
"CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
"WRONG_CURRENT_PASSWORD": "Incorrect current password.",
"PAST_DATE": "Appointments cannot be booked for a past date.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
"CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\".",
"AUTH_REQUIRED": "Please log in to access this page.",
"JSON_REQUIRED": "Request refused: the server expects JSON.",
"SERVER_UNREACHABLE": "The server does not respond. Please try again later."
},
"CAPTCHA": {
"LABEL": "Type the characters shown in the image",
"IMAGE_ALT": "Anti-robot verification image",
"NEW_IMAGE": "Another image",
"HELP": "Upper or lower case, it does not matter."
},
"REGISTRATION": {
"TITLE": "Create a patient account",
"INTRO": "With this account you can book your own appointments.",
"LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_HELP": "At least {{min}} characters.",
"SUBMIT": "Create my account",
"BACK_TO_LOGIN": "Back to login",
"DONE": "Your account has been created. You can now log in with the login {{login}}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirm password"
},
"AREA": {
"TITLE": "My area",
"HELLO": "Hello {{name}}",
"MANAGE_ACCOUNT": "Manage my account",
"MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
"VIEW_SCHEDULE": "View a schedule",
"VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
"MY_APPOINTMENT": "My appointment",
"SEE_IN_SCHEDULE": "see in the schedule",
"CANCEL_APPOINTMENT": "Cancel this appointment",
"NO_APPOINTMENT": "You have no upcoming appointment."
},
"MY_ACCOUNT": {
"TITLE": "Manage my account",
"NEW_PASSWORD_LABEL": "New password",
"CURRENT_PASSWORD_LABEL": "Current password",
"CURRENT_PASSWORD_HELP": "Required to save any change.",
"BACK": "Back to my area",
"DELETE_TITLE": "Delete my account",
"DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
"DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
"DELETE_SUBMIT": "Delete my account",
"UPDATED": "Your account has been updated.",
"DELETED": "Your account has been deleted."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "No, go back",
"YES": "Yes, confirm"
}
}
|
10.4.5. Los stores
10.4.5.1. src/stores/session.ts
| // =========================================================================
// stores/session.ts - ¿QUIÉN está conectado?
// -------------------------------------------------------------------------
// El usuario conectado (o null), en un store de Zustand (ver ejemplo
// 20): legible por los componentes (useSession) Y por el código que
// no es un componente (las guardias del enrutador: useSession.getState()).
//
// El token JWT en sí NO está aquí: está en una cookie httpOnly que
// solo el navegador maneja. El store solo guarda la DESCRIPCIÓN del
// usuario, devuelta por el servidor ({ login, name, role }).
//
// Al arrancar (y tras un F5), el store está vacío: check() pregunta
// al servidor, una sola vez, quién está conectado (GET /api/auth/me).
// =========================================================================
import { create } from 'zustand';
import { api } from '../api/rdvmedecins.api';
import type { Role, User } from '../api/types';
interface Session {
user: User | null;
check: () => Promise<void>;
logIn: (login: string, password: string, captchaId: string, captcha: string) => Promise<void>;
update: (u: User) => void;
logOut: () => Promise<void>;
forget: () => void;
}
// ¿ya se le hizo al servidor la pregunta "who is logged in?"?
// (una variable de módulo: no tiene que mostrarse)
let checking: Promise<void> | null = null;
export const useSession = create<Session>()((set, get) => ({
user: null,
// lo llama la guardia del enrutador antes de CADA navegación; solo pregunta
// al servidor la primera vez (la promesa se conserva y se reutiliza)
check() {
checking ??= api
.me()
.then((u) => set({ user: u }))
.catch(() => set({ user: null })); // 401: nadie; o servidor inaccesible
return checking;
},
async logIn(login, password, captchaId, captcha) {
set({ user: await api.logIn(login, password, captchaId, captcha) });
},
// el usuario ha cambiado su nombre o su login (PUT /api/my-account)
update: (u) => set({ user: u }),
async logOut() {
try {
await api.logOut();
} finally {
get().forget();
}
},
// sin preguntar nada al servidor: sesión expirada, cuenta eliminada
forget: () => set({ user: null }),
}));
// lo que se deduce del usuario: funciones ordinarias
export const role = (u: User | null): Role | null => u?.role ?? null;
export const isAdmin = (u: User | null) => role(u) === 'ADMIN';
export const isPatient = (u: User | null) => role(u) === 'USER';
// ADMIN y DOCTOR: reservan y cancelan las citas de cualquier paciente
export const isManager = (u: User | null) => role(u) === 'ADMIN' || role(u) === 'DOCTOR';
// la página de inicio de cada rol, justo después de iniciar sesión
export const homePage = (u: User | null) => (isPatient(u) ? '/my-area' : '/schedule');
|
El usuario conectado, en un store de [Zustand] (ejemplo 20). Un store puede ser leído por los componentes ([useSession((s) => s.user)]) Y también mediante el código que no es un componente: [useSession.getState()] (los guardias del enrutador).
- Línea 21: la DESCRIPCIÓN del usuario ([{ login, name, role }]). El token JWT, en cambio, está en la cookie httpOnly: el cliente nunca lo ve;
- Líneas 31–44: [check()] pregunta al servidor quién está conectado UNA SOLA VEZ: la promesa se conserva y se reutiliza ([??=]: asignación si la variable es [null]). Los guardias la invocan antes de cada navegación: solo el primero espera realmente;
- líneas 46–48: la conexión: el usuario devuelto por el servidor se guarda en el store;
- líneas 53–59: el cierre de sesión. [finally]: aunque el servidor no responda, el cliente olvida al usuario;
- líneas 66–72: lo que se deduce del usuario: funciones ordinarias que reciben al usuario como parámetro. Un componente escribe [isAdmin(user)] después de leer [user] del store; luego se vuelve a mostrar cuando el usuario cambia.
10.4.5.2. src/stores/messages.ts
| // =========================================================================
// stores/messages.ts - los mensajes que se muestran al usuario
// -------------------------------------------------------------------------
// Misma presentación que la aplicación HTML:
// - un ÉXITO se muestra en la parte SUPERIOR de la página (banner verde);
// - un ERROR en la parte INFERIOR, sobre un fondo rosa claro (panel "sticky").
// Un mensaje es una CLAVE de traducción (+ sus parámetros): por lo tanto,
// se vuelve a traducir por sí solo si el usuario cambia de idioma.
//
// Los mensajes "flash": una acción que termina con un cambio de
// página (reserva, alta de un médico...) deja su mensaje con flash();
// se mostrará en la página SIGUIENTE y luego desaparecerá en la navegación
// posterior. Es el enrutador quien llama a newPage() al final de cada
// navegación (ver router.ts). Ese era, en el lado del servidor, el papel de la
// cookie efímera "rdvmedecins_flash".
// =========================================================================
import { create } from 'zustand';
import { ApiError } from '../api/api-error';
export interface Message {
key: string;
params?: Record<string, string>;
}
interface Messages {
success: Message | null;
error: Message | null;
// los mensajes que se mostrarán en la página siguiente
pending: { success: Message | null; error: Message | null } | null;
showSuccess: (key: string, params?: Record<string, string>) => void;
showError: (key: string, params?: Record<string, string>) => void;
showApiError: (e: unknown) => void;
clear: () => void;
flash: (type: 'success' | 'error', key: string, params?: Record<string, string>) => void;
newPage: () => void;
}
export const useMessages = create<Messages>()((set) => ({
success: null,
error: null,
pending: null,
showSuccess: (key, params) => set({ success: { key, params }, error: null }),
showError: (key, params) => set({ error: { key, params }, success: null }),
// un ApiError -> el mensaje de la página; cualquier otro error es un
// bug del cliente, que se deja pasar (consola del navegador)
showApiError(e) {
if (!(e instanceof ApiError)) {
throw e;
}
set({ error: { key: e.key, params: e.params }, success: null });
},
clear: () => set({ success: null, error: null }),
// para la página SIGUIENTE
flash: (type, key, params) =>
set((m) => ({ pending: { success: null, error: null, ...m.pending, [type]: { key, params } } })),
// una página nueva: los mensajes de la anterior desaparecen, los mensajes
// flash aparecen
newPage: () =>
set((m) => ({ success: m.pending?.success ?? null, error: m.pending?.error ?? null, pending: null })),
}));
|
Mensajes mostrados al usuario: un mensaje de éxito en la parte superior de la página y un mensaje de error en la parte inferior.
- Líneas 21–24: un mensaje es una CLAVE de traducción y sus parámetros, no texto plano: se vuelve a traducir automáticamente si el usuario cambia de idioma;
- líneas 49–54: un [ApiError] se convierte en el mensaje de error de la página. Cualquier otro error es un problema del lado del cliente (un error de programación): se vuelve a lanzar para que aparezca en la consola del navegador;
- líneas 59–60: [flash] establece un mensaje para la página SIGUIENTE. Una acción que termina con un cambio de página (agregar un médico, seguido de un regreso a la lista) usa este mecanismo: un mensaje mostrado de inmediato desaparecería al navegar el usuario;
- líneas 64–65: invocado por el enrutador al final de cada navegación: los mensajes pendientes pasan a ser los mensajes de la página.
10.4.5.3. src/stores/confirmation.ts
| // =========================================================================
// stores/confirmation.ts - "Are you sure?"
// -------------------------------------------------------------------------
// Tomado del ejemplo 16, en forma de store: confirm(key) abre
// el diálogo de confirmación (components/ConfirmDialog.tsx, colocado una vez
// en el layout) y devuelve una promesa resuelta a true (Yes) o
// false (No). El mensaje es una CLAVE de traducción: el diálogo la traduce
// al idioma actual.
//
// if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }
// =========================================================================
import { create } from 'zustand';
import { useMessages } from './messages';
interface Confirmation {
messageKey: string | null; // null: diálogo cerrado
answer: (yes: boolean) => void;
}
// la función que resolverá la promesa actual (nada que mostrar: fuera del estado)
let respond: ((yes: boolean) => void) | null = null;
export const useConfirmation = create<Confirmation>()((set) => ({
messageKey: null,
answer(yes) {
set({ messageKey: null });
const r = respond;
respond = null;
r?.(yes);
},
}));
// una función ordinaria, utilizable en todas partes
export function confirm(key: string): Promise<boolean> {
respond?.(false); // ¿una pregunta aún abierta? cuenta como "no"
// una pregunta nueva: los mensajes de la acción anterior quedan obsoletos
useMessages.getState().clear();
useConfirmation.setState({ messageKey: key });
return new Promise<boolean>((resolve) => {
respond = resolve;
});
}
|
La ventana de confirmación del ejemplo 16, implementada como un store y una función ordinaria:
- línea 17: la pregunta formulada (una clave de traducción) o [null]: la ventana ([components/ConfirmDialog.tsx]) está cerrada;
- línea 22: la función que resolverá la promesa de la pregunta actual. No hay nada que mostrar: esto no es un estado, sino una variable de módulo;
- líneas 35–43: [confirm] abre la ventana y devuelve una promesa, resuelta como [true] (Sí) o [false] (No) por [answer]. Una página simplemente escribe [if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }]. No se necesita ningún contexto, como en el ejemplo 16: el store es accesible desde cualquier lugar.
10.4.6. Los hooks
| // =========================================================================
// hooks/useFormSubmit.ts - envío de un formulario al servidor
// -------------------------------------------------------------------------
// Todos los formularios de la aplicación siguen el mismo patrón que el
// ejemplo 25: ninguna regla se verifica en el navegador (viven
// en un solo lugar, el servidor), y cuando se rechaza el formulario:
// - el error de cada campo (ApiError.fields) se muestra debajo del
// campo, enmarcado en rojo;
// - el mensaje general (ApiError.key) se muestra en la parte inferior de la página.
// Este hook agrupa estas acciones. Una página lo llama una vez por formulario:
//
// const submission = useFormSubmit();
// if (await submission.submit(() => api.register(form))) { ... }
// <InputField ... error={submission.errors.lastName} />
// =========================================================================
import { useCallback, useState } from 'react';
import { ApiError } from '../api/api-error';
import { useMessages } from '../stores/messages';
export function useFormSubmit() {
const showApiError = useMessages((m) => m.showApiError);
// el error de cada campo: una CLAVE de traducción
const [errors, setErrors] = useState<Record<string, string>>({});
// los parámetros de los mensajes de error ({min}...), devueltos por el servidor
const [params, setParams] = useState<Record<string, string>>({});
const [submitting, setSubmitting] = useState(false);
// ejecuta el envío; devuelve true si tuvo éxito. Ante un ApiError,
// se muestran los errores y se devuelve false.
const submit = useCallback(
async (action: () => Promise<unknown>): Promise<boolean> => {
setErrors({});
setParams({});
setSubmitting(true);
try {
await action();
return true;
} catch (e) {
showApiError(e); // (relanza todo error que no sea un ApiError)
const error = e as ApiError;
setErrors(error.fields);
setParams(error.params);
return false;
} finally {
setSubmitting(false);
}
},
[showApiError],
);
// el usuario modifica un campo: su error desaparece
const clearError = useCallback((field: string) => {
setErrors((e) => {
if (!(field in e)) return e; // nada que borrar: el MISMO objeto (sin nuevo renderizado)
const { [field]: _cleared, ...rest } = e;
return rest;
});
}, []);
return { errors, params, submitting, submit, clearError };
}
|
Todos los formularios de la aplicación siguen el patrón mostrado en el ejemplo 25: no se verifica ninguna regla de validación en el navegador y, si el servidor rechaza el envío, el error de cada campo se muestra debajo del campo, con un mensaje de error general al pie de la página. Este hook personalizado (ejemplo 15) se encarga de las siguientes acciones:
- líneas 24–27: su estado: el error de cada campo (una clave de traducción), sus parámetros y “enviando” (para deshabilitar el botón);
- líneas 31–50: [submit(action)] ejecuta el envío y devuelve [true] si tiene éxito. Si se devuelve un [ApiError], se muestran los errores y la función devuelve [false]. [useCallback]: la función sigue siendo la MISMA de una visualización a la siguiente;
- Líneas 53–59: el usuario modifica un campo: el error desaparece. Si el campo no tenía un error, se devuelve el MISMO objeto; [React] no vuelve a mostrar nada. [const { [field]: _cleared, ...rest } = e]: [rest] es una copia de [e], sin la propiedad [field].
10.4.6.2. src/hooks/useCaptcha.ts
| // =========================================================================
// hooks/useCaptcha.ts - una imagen CAPTCHA y el medio para cambiarla
// -------------------------------------------------------------------------
// Carga un CAPTCHA (GET /api/captcha) cuando se muestra el componente que
// lo usa. reload() pide otro: es necesario después de CADA
// intento, porque una imagen solo puede usarse UNA vez (el servidor la olvida
// en cuanto la ha verificado). La página de inicio de sesión lo usa con el componente
// CaptchaField, que muestra la imagen y el campo de entrada.
// =========================================================================
import { useCallback, useEffect, useState } from 'react';
import { api } from '../api/rdvmedecins.api';
import type { Captcha } from '../api/types';
export function useCaptcha() {
const [captcha, setCaptcha] = useState<Captcha | null>(null);
const reload = useCallback(async () => {
try {
setCaptcha(await api.captcha());
} catch {
setCaptcha(null); // servidor inaccesible: el inicio de sesión fallará con un mensaje claro
}
}, []);
useEffect(() => {
reload();
}, [reload]);
// captchaId: el identificador de la imagen mostrada, para enviarlo con la respuesta
return { svg: captcha?.svg ?? '', captchaId: captcha?.id ?? '', reload };
}
|
Una imagen CAPTCHA, cargada cuando se muestra el componente, y [reload()] para solicitar otra: esto es necesario después de CADA intento, porque el servidor descarta una imagen apenas la ha verificado.
| // =========================================================================
// formatting.ts - la presentación de personas, horas y días
// -------------------------------------------------------------------------
// El servidor envía datos SIN PROCESAR (startHour: 8, startMinute: 0; day:
// "2026-10-05"); el formateo, que depende del idioma, es asunto del
// cliente (ver ejemplo 09).
// =========================================================================
import type { Slot, Identity } from './api/types';
// "Mme Alice DURAND"
export function label(p: Identity): string {
return `${p.title} ${p.firstName} ${p.lastName}`;
}
// "8:05" en lugar de "8:5"
export function time(h: number, m: number): string {
return `${h}:${String(m).padStart(2, '0')}`;
}
// "8:00 - 8:20"
export function timeRange(s: Slot): string {
return `${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}`;
}
// la fecha de hoy, en el formato "yyyy-MM-dd" (el de <input type="date"> y el de la API)
export function today(): string {
const d = new Date();
return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}
// true si [day] es una fecha que existe, en el formato yyyy-MM-dd
export function isValidDate(day: unknown): day is string {
if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
return false;
}
const date = new Date(`${day}T00:00:00Z`);
return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}
// "lundi 5 octobre 2026" / "Monday 5 October 2026"
export function longDate(day: string, language: string): string {
return new Intl.DateTimeFormat(language === 'en' ? 'en-GB' : 'fr-FR', {
dateStyle: 'full',
timeZone: 'UTC', // "2026-10-05T00:00:00Z" debe seguir siendo el 5, sea cual sea la zona horaria
}).format(new Date(`${day}T00:00:00Z`));
}
|
El servidor envía datos sin procesar ([startHour: 8, startMinute: 0]; [day: "2026-10-05"]); el formateo es responsabilidad del cliente (ejemplo 09). Son funciones ordinarias: [React] no exige “pipes”, y una expresión como JSX puede invocar cualquier función ([{timeRange(c)}]).
- Líneas 33–39: [day is string]: un predicado de tipo: si la función devuelve [true], [TypeScript] sabe entonces que [day] es una cadena. Una fecha “que existe”: [2026-02-30] tiene el formato correcto, pero [new Date] la convierte en el 2 de marzo; la fecha resultante se compara entonces con la cadena original;
- líneas 42–47: el día escrito completo, en el idioma del usuario, mediante [Intl.DateTimeFormat]. [timeZone: 'UTC']: la fecha se construye a medianoche (UTC); formateada en la zona horaria de Martinica (UTC-4), seguiría siendo el día anterior.
10.4.8. El enrutador
10.4.8.1. src/routes.tsx
| // =========================================================================
// routes.tsx - las páginas de la aplicación y sus derechos de acceso
// -------------------------------------------------------------------------
// Las MISMAS direcciones que la aplicación HTML (/login, /schedule, /doctors,
// /my-area...), pero ahora son rutas del CLIENTE. El
// navegador solo envía una solicitud al servidor para la primera
// página; después, el enrutador cambia la dirección y el componente mostrado.
//
// La otra cara de la moneda: si el usuario recarga /schedule (F5), el
// navegador sí solicita /schedule al servidor, que entonces debe
// devolver index.html (Vite lo hace en desarrollo; en producción,
// ver web/client-spa.ts del servidor JSON).
//
// Todas las páginas son HIJAS de la ruta raíz, cuyo componente,
// Layout, las muestra en su <Outlet />. La función page() describe una
// página: su dirección, su componente (cargado bajo demanda para las páginas
// que no se visitan siempre) y la guardia que verifica sus derechos.
// =========================================================================
import type { ComponentType } from 'react';
import { redirect, type MiddlewareFunction, type RouteObject } from 'react-router';
import type { PersonType } from './api/rdvmedecins.api';
import { guard, registrationGuard, type Rights } from './guards';
import Layout from './components/Layout';
import Login from './pages/Login';
import Schedule from './pages/Schedule';
import ErrorPage from './pages/ErrorPage';
// una página: componente cargado de una vez (Component) o bajo demanda
// (load); otherGuards: guardias específicas de la página, después de la guardia común
interface Page {
path: string;
rights: Rights;
Component?: ComponentType;
load?: () => Promise<ComponentType>;
otherGuards?: MiddlewareFunction[];
}
function page({ path, rights, Component, load, otherGuards = [] }: Page): RouteObject {
return {
path,
// las guardias se ejecutan ANTES de cargar la página
middleware: [guard(rights), ...otherGuards],
...(load ? { lazy: async () => ({ Component: await load() }) } : { Component }),
};
}
// las páginas de administración de los médicos Y de los clientes (ADMIN), sobre el mismo
// modelo; el componente recibe el tipo como prop
function personPages(type: PersonType): RouteObject[] {
const rights: Rights = { roles: ['ADMIN'] };
const list = async () => {
const { default: Persons } = await import('./pages/Persons');
return () => <Persons type={type} />;
};
const form = async () => {
const { default: PersonForm } = await import('./pages/PersonForm');
return () => <PersonForm type={type} />;
};
return [
page({ path: type, rights, load: list }),
page({ path: `${type}/add`, rights, load: form }),
page({ path: `${type}/:id/edit`, rights, load: form }),
];
}
export const routes: RouteObject[] = [
{
path: '/',
Component: Layout,
// se muestra durante la primera navegación (el tiempo de preguntar al
// servidor quién está conectado)
HydrateFallback: () => null,
children: [
// "/": hacia /login, que a su vez redirige a la página de inicio del rol si el usuario está conectado
// (un componente que no muestra nada: la redirección ocurre antes)
{ index: true, loader: () => redirect('/login'), Component: () => null },
page({ path: 'login', rights: { public: true }, Component: Login }),
page({ path: 'schedule', rights: {}, Component: Schedule }),
...personPages('doctors'),
...personPages('clients'),
page({
path: 'register',
rights: { public: true },
load: async () => (await import('./pages/Register')).default,
otherGuards: [registrationGuard],
}),
page({ path: 'my-area', rights: { roles: ['USER'] }, load: async () => (await import('./pages/PatientArea')).default }),
page({ path: 'my-account', rights: { roles: ['USER'] }, load: async () => (await import('./pages/MyAccount')).default }),
page({ path: 'forbidden', rights: {}, Component: () => <ErrorPage code={403} /> }),
page({ path: '*', rights: { public: true }, Component: () => <ErrorPage code={404} /> }),
],
},
];
|
Las MISMAS direcciones que usa la aplicación HTML, pero que ahora son rutas del CLIENTE:
- líneas 31–37: la descripción de una página: su dirección, sus permisos de acceso y su componente, ya sea proporcionado de inmediato ([Component]) o cargado bajo demanda ([load]);
- líneas 39–46: [page()] genera la ruta correspondiente:
- línea 43: el guardia común, generado según los permisos de la página, seguido de los guardias propios de la página. Se ejecutan ANTES de que se cargue la página (ejemplo 18);
- línea 44: [lazy]: el código de la página se carga en la primera visita (ejemplo 17). La página de inicio de sesión y la agenda, que todos pueden ver, se cargan de inmediato; las páginas de ADMIN y de pacientes se cargan bajo demanda;
- líneas 50–65: las tres páginas para administrar médicos, seguidas de las de clientes, con la misma plantilla. El componente se envuelve en un componente sin parámetros, [() => <Persons type={type} />]: así es como recibe el tipo como prop;
- líneas 69–70: la ruta raíz. Su componente, [Layout], muestra la página actual en su [<Outlet />];
- línea 73: lo que se muestra durante la primerísima navegación, mientras el guardia pregunta al servidor quién está conectado: nada;
- línea 77: la dirección [/] redirige a [/login], cuyo guardia redirige a su vez a la página de inicio del rol si el usuario ha iniciado sesión;
- líneas 78–79: [rights: { public: true }]: la página es accesible sin haber iniciado sesión; [rights: {}]: es necesario haber iniciado sesión, sea cual sea el rol;
- líneas 83–87: la creación de una cuenta pública tiene un segundo guardia, [registrationGuard];
- líneas 88–89: [roles: ['USER']]: las páginas del paciente;
- línea 90: la página 403;
- línea 91: la página 404: [*] designa cualquier dirección que ninguna otra ruta reconozca.
Recordatorio: si el usuario recarga [/schedule] (F5), el navegador solicita efectivamente [/schedule] al servidor, que debe entonces devolver [index.html]: esto es lo que hace el servidor de desarrollo de [Vite] y, en producción, el servidor JSON (véase el capítulo “Despliegue”).
10.4.8.2. src/guards.ts
| // =========================================================================
// guards.ts - las guardias del enrutador (middlewares, ver ejemplo 18)
// -------------------------------------------------------------------------
// guard(rights) CREA la guardia de una página, a partir de sus derechos de acceso:
// - public : accesible sin haber iniciado sesión;
// - roles : los roles permitidos (ausente = todos los roles conectados).
// Cada página declara los suyos (ver routes.tsx). Antes de cada navegación
// a esta página, la guardia:
// 1. la primera vez (arranque, F5), pregunta al servidor quién está
// conectado (useSession.getState().check());
// 2. verifica los derechos de la página y redirige si es necesario.
//
// RECORDATORIO: estas verificaciones son solo una COMODIDAD (no mostrar una
// página inútil). La protección de los datos la garantiza el servidor, que
// verifica el token y el rol de nuevo en CADA solicitud.
// =========================================================================
import { redirect, type MiddlewareFunction } from 'react-router';
import type { Role } from './api/types';
import { api } from './api/rdvmedecins.api';
import { homePage, useSession } from './stores/session';
import { useMessages } from './stores/messages';
export interface Rights {
public?: boolean;
roles?: Role[];
}
export function guard(rights: Rights): MiddlewareFunction {
return async ({ request }) => {
await useSession.getState().check();
// getState(): el estado del store, leído FUERA de un componente
const user = useSession.getState().user;
const url = new URL(request.url);
if (rights.public) {
// ya conectado: la página de inicio de sesión ya no tiene sentido
if (url.pathname === '/login' && user !== null) {
throw redirect(homePage(user));
}
return;
}
if (user === null) {
// se recuerda la página solicitada, para volver a ella después de iniciar sesión
throw redirect(`/login?redirect=${encodeURIComponent(url.pathname + url.search)}`);
}
if (rights.roles && !rights.roles.includes(user.role)) {
throw redirect('/forbidden');
}
};
}
// una guardia ESPECÍFICA de la ruta /register: sin un pase (CAPTCHA
// resuelto en la página de inicio de sesión), de vuelta a la página de inicio de sesión
export const registrationGuard: MiddlewareFunction = async () => {
const { valid } = await api.registrationAccessStatus().catch(() => ({ valid: false }));
if (!valid) {
useMessages.getState().flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
throw redirect('/login');
}
};
|
- líneas 24–27: los derechos de acceso de una página;
- líneas 29–51: [guard(rights)] CREA un guardia, es decir, un middleware del enrutador (ejemplo 18):
- línea 31: la primera vez (inicio, F5) se pregunta al servidor quién ha iniciado sesión; en las siguientes ocasiones, la respuesta ya está disponible;
- líneas 36–42: una página pública. Un usuario conectado ya no tiene nada que hacer en la página de inicio de sesión: se le redirige a su página de inicio;
- líneas 43–46: nadie ha iniciado sesión: redirección a la página de inicio de sesión, conservando la página solicitada ([?redirect=...]), para volver a ella después de iniciar sesión;
- líneas 47–49: el rol no está autorizado: la página 403;
- [throw redirect(...)]: un guardia “lanza” una redirección: la navegación actual se abandona en favor de la nueva dirección;
- líneas 55–61: el guardia propio de la página [/register]: sin un pase (el CAPTCHA resuelto en la página de inicio de sesión), se vuelve a la página de inicio de sesión con un mensaje. De todos modos, el servidor se negaría a crear la cuenta.
Estas verificaciones son simplemente una COMODIDAD: evitar mostrar una página inútil. La protección de los datos la garantiza el servidor, que vuelve a verificar el token y el rol en CADA solicitud.
10.4.9. Los componentes
10.4.9.1. src/components/Layout.tsx
| // =========================================================================
// components/Layout.tsx - el LAYOUT común a todas las páginas
// -------------------------------------------------------------------------
// El componente de la ruta raíz (ver routes.tsx), el equivalente de
// views/layout.hbs de la aplicación HTML:
// - la barra de navegación;
// - un mensaje de éxito en la parte SUPERIOR;
// - la página actual (<Outlet />);
// - el panel de errores en la parte INFERIOR;
// - el diálogo de confirmación, una vez para toda la aplicación.
// =========================================================================
import { Outlet } from 'react-router';
import NavBar from './NavBar';
import SuccessMessage from './SuccessMessage';
import ErrorPanel from './ErrorPanel';
import ConfirmDialog from './ConfirmDialog';
export default function Layout() {
return (
<>
<div className="container py-4">
<NavBar />
<SuccessMessage />
<Outlet />
<ErrorPanel />
</div>
<ConfirmDialog />
</>
);
}
|
El componente de la ruta raíz, el equivalente de [views/layout.hbs] en la aplicación HTML: la barra de navegación, el mensaje de éxito en la parte superior, la página actual ([<Outlet />]) y el área de errores en la parte inferior. La ventana de confirmación se coloca allí una sola vez para toda la aplicación.
10.4.9.2. src/components/PageTitle.tsx
| // =========================================================================
// components/PageTitle.tsx - el título de la pestaña, traducido
// -------------------------------------------------------------------------
// React 19 coloca en el <head> de la página todo elemento <title> renderizado por
// un componente (ver ejemplo 17). Cada página muestra <PageTitle titleKey="..." />
// con la clave de su título: la pestaña muestra "Schedule - RdvMedecins", y
// se traduce de nuevo cuando cambia el idioma.
// =========================================================================
import { useTranslation } from 'react-i18next';
export default function PageTitle({ titleKey }: { titleKey: string }) {
const { t } = useTranslation();
return <title>{`${t(titleKey)} - ${t('APP.TITLE')}`}</title>;
}
|
[React] 19 coloca en el encabezado de la página ([<head>]) cualquier elemento [<title>] renderizado por un componente (ejemplo 17). Cada página muestra [<PageTitle titleKey="SCHEDULE.PAGE_TITLE" />]: la pestaña muestra “Schedule - RdvMedecins” y se vuelve a traducir cuando cambia el idioma.
10.4.9.3. src/components/NavBar.tsx
| // =========================================================================
// components/NavBar.tsx - la barra de navegación
// -------------------------------------------------------------------------
// Mismo contenido que el de la aplicación HTML (views/partials/navbar.hbs):
// título, menús según el rol, FR / EN, rol, nombre, cierre de sesión.
// "Doctors" y "Patients" solo aparecen para el ADMIN: una simple
// comodidad de presentación, siendo la protección real la del servidor.
// =========================================================================
import { NavLink, useNavigate } from 'react-router';
import { useTranslation } from 'react-i18next';
import { LANGUAGES } from '../i18n/i18n';
import { isAdmin, isPatient, useSession } from '../stores/session';
export default function NavBar() {
const { t, i18n } = useTranslation();
const user = useSession((s) => s.user);
const logOut = useSession((s) => s.logOut);
const navigate = useNavigate();
async function onLogOut() {
await logOut().catch(() => {}); // incluso si el servidor no responde
navigate('/login');
}
return (
<nav className="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span className="navbar-brand mb-0">{t('APP.TITLE')}</span>
{user ? (
<ul className="navbar-nav me-auto">
{isPatient(user) && (
<li className="nav-item">
{/* NavLink pone la clase "active" (Bootstrap) en el menú de la página mostrada */}
<NavLink className="nav-link" to="/my-area">{t('APP.MENU_MY_AREA')}</NavLink>
</li>
)}
<li className="nav-item">
<NavLink className="nav-link" to="/schedule">{t('APP.MENU_SCHEDULE')}</NavLink>
</li>
{isAdmin(user) && (
<>
<li className="nav-item">
<NavLink className="nav-link" to="/doctors">{t('APP.MENU_DOCTORS')}</NavLink>
</li>
<li className="nav-item">
<NavLink className="nav-link" to="/clients">{t('APP.MENU_PATIENTS')}</NavLink>
</li>
</>
)}
</ul>
) : (
<div className="me-auto"></div>
)}
<div className="d-flex align-items-center gap-2">
{/* FR / EN: sin solicitud al servidor, la página se traduce de nuevo en el lugar */}
<div className="btn-group btn-group-sm" role="group" aria-label={t('APP.LANGUAGE')}>
{LANGUAGES.map((l) => (
<button key={l} type="button" className={`btn ${i18n.language === l ? 'btn-light' : 'btn-outline-light'}`}
aria-pressed={i18n.language === l} onClick={() => i18n.changeLanguage(l)}>
{l.toUpperCase()}
</button>
))}
</div>
{user && (
<>
<span className="badge text-bg-light text-primary">{user.role}</span>
<span className="text-white">{user.name}</span>
<button type="button" className="btn btn-sm btn-outline-light" onClick={onLogOut}>{t('APP.LOGOUT')}</button>
</>
)}
</div>
</nav>
);
}
|
- líneas 17–18: el componente lee al usuario y la función de cierre de sesión del store de sesión; se vuelve a mostrar cuando el usuario cambia (inicio de sesión, cierre de sesión, sesión expirada);
- líneas 21–24: cierre de sesión y luego la página de inicio de sesión. Aunque el servidor no responda, el cliente olvida al usuario (véase [stores/session.ts]): el error se ignora ([catch(() => {})]);
- líneas 32–37: los menús dependen del rol;
- línea 35: [NavLink] (ejemplo 17) asigna la clase [active] de [Bootstrap] al menú de la página mostrada;
- líneas 59–64: los botones FR / EN. [i18n.changeLanguage(l)]: no se envía ninguna solicitud al servidor; toda la página se vuelve a renderizar localmente. [aria-pressed]: un lector de pantalla anuncia el botón del idioma actual como “presionado”;
- líneas 67–73: el rol, el nombre y el botón de cierre de sesión.
10.4.9.4. src/components/SuccessMessage.tsx y ErrorPanel.tsx
| // =========================================================================
// components/SuccessMessage.tsx - el mensaje de ÉXITO, en la parte superior de la página
// (cita guardada, médico agregado...) - ver stores/messages.ts.
// role="status": un lector de pantalla lo anuncia sin interrumpir al usuario.
// =========================================================================
import { useTranslation } from 'react-i18next';
import { useMessages } from '../stores/messages';
export default function SuccessMessage() {
const { t } = useTranslation();
const success = useMessages((m) => m.success);
return success && <div className="alert alert-success" role="status">{t(success.key, success.params)}</div>;
}
|
| // =========================================================================
// components/ErrorPanel.tsx - el panel de errores, en la parte INFERIOR de cada página, sobre
// un fondo rosa claro (clase .error-panel, ver styles.css) - como
// views/partials/errors.hbs de la aplicación HTML.
// role="alert": un lector de pantalla anuncia el mensaje en cuanto aparece.
// =========================================================================
import { useTranslation } from 'react-i18next';
import { useMessages } from '../stores/messages';
export default function ErrorPanel() {
const { t } = useTranslation();
const error = useMessages((m) => m.error);
return error && <div className="error-panel" role="alert">{t(error.key, error.params)}</div>;
}
|
Dos pequeños componentes que muestran los mensajes del store [useMessages], traducidos al idioma actual. [role="status"] y [role="alert"]: un lector de pantalla anuncia el mensaje apenas aparece, de forma discreta si es un éxito e inmediata si es un error. Un componente puede devolver [null] (o [false]): en ese caso, no muestra nada.
10.4.9.5. src/components/ConfirmDialog.tsx
| // =========================================================================
// components/ConfirmDialog.tsx
// -------------------------------------------------------------------------
// El diálogo "Are you sure?" del ejemplo 16, completado para el teclado
// como public/js/app.js de la aplicación HTML:
// - al abrirse, el foco va a "No, go back": una pulsación distraída de
// Enter no elimina nada;
// - Escape cierra el diálogo (= No);
// - Tab y Shift+Tab se quedan DENTRO del diálogo (de lo contrario el foco iría a
// la página atenuada, detrás);
// - al cerrarse, el foco vuelve al elemento que lo tenía (el
// botón "Delete" pulsado, por ejemplo).
// "No, go back" en lugar de "Cancel": la pregunta a veces es "Cancel this
// appointment?", y un botón "Cancel" sería ambiguo ahí.
// El componente se coloca una vez en el layout; no muestra nada mientras
// el store de confirmación no tenga ninguna pregunta (ver stores/confirmation.ts).
// =========================================================================
import { useEffect, useRef, type KeyboardEvent, type MouseEvent } from 'react';
import { createPortal } from 'react-dom';
import { useTranslation } from 'react-i18next';
import { useConfirmation } from '../stores/confirmation';
export default function ConfirmDialog() {
const { t } = useTranslation();
const key = useConfirmation((c) => c.messageKey);
const answer = useConfirmation((c) => c.answer);
const dialog = useRef<HTMLDivElement>(null);
const noButton = useRef<HTMLButtonElement>(null);
// se abre el diálogo: recordamos el elemento que tiene el foco y se lo damos
// al botón "No"; se cierra (limpieza): devolvemos el foco
const open = key !== null;
useEffect(() => {
if (!open) return;
const previousFocus = document.activeElement as HTMLElement | null;
noButton.current?.focus();
return () => previousFocus?.focus();
}, [open]);
if (key === null) {
return null; // diálogo cerrado: nada que mostrar
}
function onKeydown(e: KeyboardEvent<HTMLDivElement>) {
if (e.key === 'Escape') {
answer(false);
} else if (e.key === 'Tab' && dialog.current) {
const buttons = [...dialog.current.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (e.shiftKey && document.activeElement === first) {
e.preventDefault();
last?.focus();
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault();
first?.focus();
}
}
}
// un clic en el fondo atenuado (y no en el diálogo en sí) = No
function onBackdropClick(e: MouseEvent<HTMLDivElement>) {
if (e.target === e.currentTarget) {
answer(false);
}
}
return createPortal(
<div onKeyDown={onKeydown}>
<div className="modal-backdrop fade show"></div>
<div ref={dialog} className="modal fade show d-block" tabIndex={-1} role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-title" aria-describedby="confirmation-message" onClick={onBackdropClick}>
<div className="modal-dialog modal-dialog-centered">
<div className="modal-content">
<div className="modal-header">
<h5 id="confirmation-title" className="modal-title">{t('CONFIRMATION.TITLE')}</h5>
<button type="button" className="btn-close" aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} onClick={() => answer(false)}></button>
</div>
<div className="modal-body">
<p id="confirmation-message" className="mb-0">{t(key)}</p>
</div>
<div className="modal-footer">
<button ref={noButton} type="button" className="btn btn-secondary" onClick={() => answer(false)}>
{t('CONFIRMATION.NO')}
</button>
<button type="button" className="btn btn-danger" onClick={() => answer(true)}>{t('CONFIRMATION.YES')}</button>
</div>
</div>
</div>
</div>
</div>,
document.body,
);
}
|
La ventana del ejemplo 16, vinculada al store de confirmación y completada para el teclado:
- líneas 26–27: la pregunta formulada ([null]: ventana cerrada) y la función que la responde;
- líneas 33–39: un efecto que depende de [open]: al abrirse, se conserva el elemento que tiene el foco (el botón “Delete” en el que se hizo clic) y se da el foco al botón “No, go back”: una pulsación accidental de Enter no elimina nada. La limpieza del efecto, realizada al cerrarse, devuelve el foco al elemento conservado;
- líneas 41–43: ventana cerrada: no hay nada que mostrar. Los hooks se invocan ANTES de este [return]: deben invocarse cada vez que se muestra la ventana, en el mismo orden;
- líneas 45–60: Esc significa “No”. Tab y Shift+Tab mantienen el foco DENTRO de la ventana: Tab pasa del último botón al primero, y viceversa; de lo contrario, el foco pasaría a la página atenuada que está detrás;
- líneas 63–67: un clic en el fondo atenuado se trata como “No”. [e.target] es el elemento en el que se hizo clic y [e.currentTarget] es el que tiene el manejador: son iguales si el clic se produjo en el fondo mismo y no dentro de la ventana;
- Líneas 69–94: [createPortal] (ejemplo 16) muestra la ventana al final de [<body>], fuera de la página: ningún estilo de la página puede deformarla;
- línea 72: para un lector de pantalla, una ventana que solicita una respuesta urgente; [aria-labelledby] y [aria-describedby] remiten a su título y a su pregunta.
| // =========================================================================
// components/InputField.tsx - un campo de formulario completo
// -------------------------------------------------------------------------
// Etiqueta + campo + mensaje de ayuda O mensaje de error. Todos los
// formularios de la aplicación lo usan:
//
// <InputField fieldId="lastName" label="PERSONS.LASTNAME_LABEL" maxLength={20}
// value={form.lastName} onChange={(v) => edit('lastName', v)} error={submission.errors.lastName} />
//
// Es un componente CONTROLADO (ver ejemplo 11): el valor pertenece al
// formulario padre. El error es el devuelto por el SERVIDOR (ver
// hooks/useFormSubmit.ts). label, help y error son CLAVES de
// traducción; params, los parámetros de sus mensajes ({min}...).
// =========================================================================
import { useTranslation } from 'react-i18next';
interface Props {
fieldId: string; // el id del <input>, vinculado al <label>
label: string;
value: string;
onChange: (value: string) => void;
error?: string;
help?: string;
params?: Record<string, string>;
type?: 'text' | 'password';
maxLength?: number;
autoComplete?: string;
required?: boolean;
autoFocus?: boolean;
className?: string; // las clases del bloque (mb-3, col-sm-6...)
}
export default function InputField({
fieldId, label, value, onChange, error, help, params = {}, type = 'text', maxLength,
autoComplete = 'off', required = false, autoFocus = false, className = '',
}: Props) {
const { t } = useTranslation();
const messageId = `${fieldId}-message`;
return (
<div className={className}>
<label className="form-label" htmlFor={fieldId}>{t(label)}</label>
<input id={fieldId} type={type} className={`form-control ${error ? 'is-invalid' : ''}`} value={value}
onChange={(e) => onChange(e.target.value)} maxLength={maxLength} autoComplete={autoComplete}
required={required} autoFocus={autoFocus} aria-invalid={error ? true : undefined} aria-describedby={messageId} />
{error ? (
<div className="invalid-feedback" id={messageId}>{t(error, params)}</div>
) : (
help && <div className="form-text" id={messageId}>{t(help, params)}</div>
)}
</div>
);
}
|
Un campo de formulario completo: etiqueta, campo y mensaje de ayuda O mensaje de error. Todos los formularios de la aplicación lo usan.
- líneas 18–32: sus props; [label], [help] y [error] son props de traducción (CLAVES);
- líneas 34–37: la desestructuración de las props, con valores por defecto ([type = 'text']);
- línea 39: el identificador del mensaje de ayuda o de error, que [aria-describedby] vincula con el campo; un lector de pantalla lo lee junto con el campo;
- líneas 44–46: un campo CONTROLADO (ejemplo 05): su valor pertenece al formulario padre, que lo recibe mediante [onChange]. [is-invalid]: el recuadro rojo de [Bootstrap];
- líneas 47–51: el error devuelto por el servidor y, si no hay, el texto de ayuda.
10.4.9.7. src/components/PersonFields.tsx
| // =========================================================================
// components/PersonFields.tsx - título, nombre, apellido
// -------------------------------------------------------------------------
// Los campos de identidad, comunes a tres formularios: el formulario de médico / cliente
// del ADMIN, "Create a patient account" y "Manage my account" (el equivalente del
// parcial views/partials/personFields.hbs). El padre le pasa los
// valores, los errores y la función que modifica un campo:
// <PersonFields values={form} errors={submission.errors} onChange={edit} />
// =========================================================================
import { useTranslation } from 'react-i18next';
import type { Identity } from '../api/types';
import InputField from './InputField';
const TITLES = ['Mr', 'Mme', 'Melle'];
interface Props {
values: Identity;
errors: Record<string, string>;
onChange: (field: keyof Identity, value: string) => void;
}
export default function PersonFields({ values, errors, onChange }: Props) {
const { t } = useTranslation();
return (
<>
<div className="mb-3">
<label className="form-label" htmlFor="title">{t('PERSONS.TITLE_LABEL')}</label>
<select id="title" className={`form-select ${errors.title ? 'is-invalid' : ''}`} value={values.title}
onChange={(e) => onChange('title', e.target.value)}>
{TITLES.map((title) => <option key={title}>{title}</option>)}
</select>
{errors.title && <div className="invalid-feedback">{t(errors.title)}</div>}
</div>
<div className="row g-3 mb-3">
<InputField className="col-sm-6" fieldId="firstName" label="PERSONS.FIRSTNAME_LABEL" maxLength={20} required
value={values.firstName} onChange={(v) => onChange('firstName', v)} error={errors.firstName} />
<InputField className="col-sm-6" fieldId="lastName" label="PERSONS.LASTNAME_LABEL" maxLength={20} required
value={values.lastName} onChange={(v) => onChange('lastName', v)} error={errors.lastName} />
</div>
</>
);
}
|
Título, nombre y apellido: campos comunes a tres formularios (médico o cliente de ADMIN, creación de cuenta, administración de la cuenta). El equivalente de la vista parcial [views/partials/personFields.hbs] de la aplicación HTML.
- Línea 20: [keyof Identity]: type ['title' | 'firstName' | 'lastName']; el compilador rechaza cualquier otro nombre de campo;
- línea 31: una [<option>] sin un [value] tiene su texto como valor.
10.4.9.8. src/components/CaptchaField.tsx
| // =========================================================================
// components/CaptchaField.tsx - la imagen CAPTCHA y el campo de entrada
// -------------------------------------------------------------------------
// Un componente de presentación: la imagen (svg), el enlace "Another image"
// (onReload) y el campo, CONTROLADO por el formulario padre (value,
// onChange). La imagen y su identificador provienen del hook useCaptcha, que
// el padre llama (ver pages/Login.tsx): es el padre quien los necesita
// para enviar la respuesta.
//
// dangerouslySetInnerHTML: la imagen SVG se inserta tal cual. Sin
// peligro AQUÍ porque la crea nuestro servidor (biblioteca
// svg-captcha) y no contiene nada que provenga de un usuario - ver
// ejemplo 22.
// =========================================================================
import { useTranslation } from 'react-i18next';
interface Props {
svg: string;
value: string;
onChange: (value: string) => void;
onReload: () => void;
error?: string;
}
export default function CaptchaField({ svg, value, onChange, onReload, error }: Props) {
const { t } = useTranslation();
return (
<div className="mb-3">
<label className="form-label" htmlFor="captcha">{t('CAPTCHA.LABEL')}</label>
<div className="d-flex align-items-center gap-3 mb-2">
<div className="captcha-image" role="img" aria-label={t('CAPTCHA.IMAGE_ALT')} dangerouslySetInnerHTML={{ __html: svg }} />
<button type="button" className="btn btn-link btn-sm p-0" onClick={onReload}>{t('CAPTCHA.NEW_IMAGE')}</button>
</div>
<input id="captcha" type="text" maxLength={10} autoComplete="off" autoCapitalize="off" spellCheck={false}
className={`form-control ${error ? 'is-invalid' : ''}`} value={value} onChange={(e) => onChange(e.target.value)} />
{error ? <div className="invalid-feedback">{t(error)}</div> : <div className="form-text">{t('CAPTCHA.HELP')}</div>}
</div>
);
}
|
Un componente de visualización: la imagen, el botón “Another image” y el campo, controlado por el formulario padre. La imagen y su identificador provienen del hook [useCaptcha], que la página invoca: la página lo necesita para enviar la respuesta.
- Línea 32: la imagen SVG se inserta tal cual (ejemplo 22). Es segura AQUÍ: la genera nuestro servidor y no contiene nada proporcionado por un usuario. [role="img"] y [aria-label]: para un lector de pantalla, se trata de una imagen con su descripción;
- línea 35: [autoCapitalize="off"] y [spellCheck={false}]: sin mayúsculas automáticas (teléfonos) ni corrección ortográfica.
10.4.9.9. src/components/BookingDialog.tsx
| // =========================================================================
// components/BookingDialog.tsx - el diálogo de reserva de un horario
// -------------------------------------------------------------------------
// El mismo diálogo que views/partials/booking.hbs de la aplicación HTML:
// las clases Bootstrap de un diálogo modal, mostrado "hard-coded" (show
// d-block).
//
// El componente no habla con el servidor: llama a
// - onConfirm, con el paciente elegido (null para un paciente que reserva
// para sí mismo);
// - onClose.
// Es la página de la agenda quien decide qué hacer con ello (pages/Schedule.tsx).
// =========================================================================
import { useEffect, useState, type FormEvent, type MouseEvent } from 'react';
import { createPortal } from 'react-dom';
import { useTranslation } from 'react-i18next';
import type { Person } from '../api/types';
import { label } from '../formatting';
interface Props {
time: string; // "8:00 - 8:20"
clients: readonly Person[]; // ADMIN / DOCTOR: los pacientes entre los que elegir
patient: string | null; // USER: el paciente es el propio usuario
submitting: boolean;
onConfirm: (clientId: number | null) => void;
onClose: () => void;
}
export default function BookingDialog({ time, clients, patient, submitting, onConfirm, onClose }: Props) {
const { t } = useTranslation();
const [clientId, setClientId] = useState<number | null>(null);
// Escape, en cualquier lugar de la página: cerramos
useEffect(() => {
const onKeydown = (e: globalThis.KeyboardEvent) => {
if (e.key === 'Escape') onClose();
};
document.addEventListener('keydown', onKeydown);
return () => document.removeEventListener('keydown', onKeydown);
}, [onClose]);
function confirm(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
onConfirm(clientId);
}
// un clic en el fondo atenuado (y no en el diálogo en sí) cierra el diálogo
function onBackdropClick(e: MouseEvent<HTMLDivElement>) {
if (e.target === e.currentTarget) {
onClose();
}
}
return createPortal(
<>
<div className="modal-backdrop fade show"></div>
<div className="modal fade show d-block" tabIndex={-1} role="dialog" aria-modal="true" aria-labelledby="booking-title"
onClick={onBackdropClick}>
<div className="modal-dialog modal-dialog-centered">
<form className="modal-content" onSubmit={confirm}>
<div className="modal-header">
<h5 id="booking-title" className="modal-title">{t('BOOKING_DIALOG.TITLE')}</h5>
<button type="button" className="btn-close" aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} onClick={onClose}></button>
</div>
<div className="modal-body">
<p>{t('BOOKING_DIALOG.SLOT', { time })}</p>
{/* un paciente reserva para sí mismo: sin lista (y el servidor
ignoraría de todos modos un posible clientId) */}
{patient !== null ? (
<p className="mb-0">{t('BOOKING_DIALOG.PATIENT_LABEL')}: <strong>{patient}</strong></p>
) : (
<>
<label className="form-label" htmlFor="clientId">{t('BOOKING_DIALOG.PATIENT_LABEL')}</label>
{/* autoFocus: al mostrarse, el foco está en la lista */}
<select id="clientId" className="form-select" autoFocus value={clientId ?? ''}
onChange={(e) => setClientId(e.target.value === '' ? null : Number(e.target.value))}>
<option value="">{t('BOOKING_DIALOG.CHOOSE_PATIENT')}</option>
{clients.map((c) => <option key={c.id} value={c.id}>{label(c)}</option>)}
</select>
</>
)}
</div>
<div className="modal-footer">
<button type="button" className="btn btn-secondary" onClick={onClose}>{t('BOOKING_DIALOG.CANCEL')}</button>
{/* sin lista, es el botón de confirmación el que tiene el foco */}
<button type="submit" className="btn btn-primary" autoFocus={patient !== null} disabled={submitting}>
{t('BOOKING_DIALOG.CONFIRM')}
</button>
</div>
</form>
</div>
</div>
</>,
document.body,
);
}
|
La ventana de reserva de citas. No se comunica con el servidor: invoca [onConfirm] con el paciente seleccionado, o [onClose]; la página de la agenda decide qué hacer con ello.
- Líneas 21–28: [clients]: la lista de pacientes, para ADMIN y los médicos; [patient]: el nombre del paciente que pide la cita para sí mismo ([null] para ADMIN y los médicos);
- línea 32: el paciente seleccionado en la lista;
- líneas 35–41: Esc, en cualquier parte de la página, cierra la ventana. El efecto se suscribe al evento [keydown] del documento y su limpieza cancela la suscripción al cerrarse. [globalThis.KeyboardEvent]: el evento del navegador, no el de [React], que tiene el mismo nombre;
- líneas 43–46: [preventDefault()] impide que el navegador envíe el formulario;
- líneas 71–83: un paciente reserva para sí mismo: sin lista. De todos modos, el servidor ignoraría cualquier [clientId];
- línea 78: el valor de una [<option>] es siempre una cadena: se convierte en un número;
- línea 89: sin lista, el botón de confirmación recibe el foco.
10.4.10. Las páginas
10.4.10.1. src/pages/Login.tsx
| // =========================================================================
// pages/Login.tsx - la página de inicio de sesión (/login)
// -------------------------------------------------------------------------
// La misma página que views/login.hbs de la aplicación HTML: login, contraseña,
// CAPTCHA, y un segundo botón "Create a patient account" que verifica el
// MISMO CAPTCHA antes de abrir la creación de cuenta.
//
// /login?login=jbernard: el campo de login viene prellenado (justo después de la
// creación de una cuenta).
// /login?redirect=/doctors: después de iniciar sesión, se abre esta página
// (dejada por la guardia del enrutador) en lugar de la página de inicio del rol.
// =========================================================================
import { useState, type FormEvent } from 'react';
import { useNavigate, useSearchParams } from 'react-router';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import { homePage, useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import { useCaptcha } from '../hooks/useCaptcha';
import CaptchaField from '../components/CaptchaField';
import PageTitle from '../components/PageTitle';
export default function Login() {
const { t } = useTranslation();
const [params] = useSearchParams();
const navigate = useNavigate();
const logIn = useSession((s) => s.logIn);
const clearMessages = useMessages((m) => m.clear);
const submission = useFormSubmit();
const captcha = useCaptcha();
// el login de la URL, si lo hay: el valor INICIAL del campo
const urlLogin = (params.get('login') ?? '').slice(0, 30);
const [form, setForm] = useState({ login: urlLogin, password: '', captcha: '' });
function edit(field: keyof typeof form, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
// los dos botones comparten esta secuencia: envío y, en caso de fallo,
// mensaje de error e imagen NUEVA (cada una solo puede usarse una vez)
async function attempt(action: () => Promise<unknown>): Promise<void> {
clearMessages();
const succeeded = await submission.submit(action);
if (!succeeded) {
setForm((f) => ({ ...f, captcha: '' }));
await captcha.reload();
}
}
async function onLogIn(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
await attempt(async () => {
await logIn(form.login.trim(), form.password, captcha.captchaId, form.captcha);
const redirect = params.get('redirect');
// solo una ruta INTERNA: nunca una redirección a otro sitio
const internal = redirect !== null && redirect.startsWith('/') && !redirect.startsWith('//');
await navigate(internal ? redirect : homePage(useSession.getState().user));
});
}
async function createAccount() {
await attempt(async () => {
await api.registrationAccess(captcha.captchaId, form.captcha);
await navigate('/register');
});
}
return (
<div className="row justify-content-center">
<PageTitle titleKey="LOGIN.TITLE" />
<div className="col-sm-8 col-md-6 col-lg-5">
<div className="card p-4">
<h5 className="card-title mb-3">{t('LOGIN.TITLE')}</h5>
<form onSubmit={onLogIn}>
<div className="mb-3">
<label className="form-label" htmlFor="login">{t('LOGIN.LOGIN_LABEL')}</label>
{/* required: el navegador se niega a enviar el formulario mientras el campo esté vacío.
autoFocus: el foco en el login... o en la contraseña si el login ya está completo */}
<input id="login" type="text" className="form-control" autoComplete="username" required
autoFocus={urlLogin === ''} value={form.login} onChange={(e) => edit('login', e.target.value)} />
</div>
<div className="mb-3">
<label className="form-label" htmlFor="password">{t('LOGIN.PASSWORD_LABEL')}</label>
<input id="password" type="password" className="form-control" autoComplete="current-password" required
autoFocus={urlLogin !== ''} value={form.password} onChange={(e) => edit('password', e.target.value)} />
</div>
<CaptchaField svg={captcha.svg} value={form.captcha} onChange={(v) => edit('captcha', v)}
onReload={captcha.reload} error={submission.errors.captcha} />
{/* type="submit": Enter en un campo activa "Log in" */}
<button type="submit" className="btn btn-primary w-100" disabled={submission.submitting}>{t('LOGIN.SUBMIT')}</button>
{/* type="button": este botón no envía el formulario (y por lo tanto
ignora los campos required, inútiles aquí) */}
<button type="button" className="btn btn-outline-primary w-100 mt-3" disabled={submission.submitting} onClick={createAccount}>
{t('LOGIN.CREATE_ACCOUNT')}
</button>
<div className="form-text text-center">{t('LOGIN.CREATE_ACCOUNT_HELP')}</div>
</form>
<div className="text-muted small mt-3">
{t('LOGIN.DEMO_ACCOUNTS')}
<ul className="mb-0 mt-1">
<li><code>admin</code> - {t('LOGIN.DEMO_ADMIN')}</li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {t('LOGIN.DEMO_DOCTOR')}</li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {t('LOGIN.DEMO_USER')}</li>
</ul>
</div>
</div>
</div>
</div>
);
}
|
La página [views/login.hbs] de la aplicación HTML: usuario, contraseña, CAPTCHA y un segundo botón "Create a patient account" que verifica el MISMO CAPTCHA antes de permitir que comience el proceso de creación de la cuenta.
- Líneas 29–32: lo que necesita la página: el inicio de sesión (almacenamiento de la sesión), la eliminación de mensajes, el envío del formulario y el CAPTCHA (nuestros dos hooks);
- Líneas 35–36: [/login?login=jbernard]: inmediatamente después de crear una cuenta, el nombre de usuario aparece rellenado. [slice(0, 30)]: no se toma más que la longitud máxima de un nombre de usuario. La URL solo proporciona el valor INICIAL del campo;
- líneas 38–41: cuando se escribe en un campo, aparece su nuevo valor y desaparece cualquier mensaje de error. [[field]: value]: una propiedad cuyo nombre se calcula;
- líneas 45–52: ambos botones siguen la misma secuencia: enviar y, si falla, borrar el CAPTCHA y cargar una imagen NUEVA; cada una se usa una sola vez;
- líneas 54–63: inicio de sesión y luego la página siguiente:
- línea 58: la página solicitada antes del inicio de sesión, conservada por el enrutador ([/login?redirect=/doctors]);
- línea 60: SOLO una ruta interna: [/doctors], pero no [https://malicious-site.com] ni [//malicious-site.com] (una dirección “sin protocolo”, que apunta a otro sitio). De lo contrario, un enlace malicioso como [/login?redirect=https://...] enviaría al usuario, que acaba de iniciar sesión, a otro sitio: es la llamada vulnerabilidad de “redirección abierta”;
- línea 61: de lo contrario, la página de inicio del rol. [useSession.getState()]: el usuario ACABA de guardarse en el store; en cambio, la variable de un componente no cambiará hasta la siguiente carga de la página;
- líneas 65–70: el segundo botón: el servidor verifica el CAPTCHA y devuelve un token (una cookie) para la página [/register];
- líneas 84–85: [required]: el navegador se niega a enviar el formulario mientras el campo esté vacío. Es la única validación que se realiza en el navegador: es simplemente una comodidad. [autoFocus]: el foco está en el campo del nombre de usuario o en el de la contraseña si el nombre de usuario ya está rellenado (línea 90);
- línea 97: [type="submit"]: presionar Enter en un campo activa el botón “Log in”;
- línea 101: [type="button"]: este botón no envía el formulario y, por lo tanto, ignora los campos [required], que aquí no son necesarios.
10.4.10.2. src/pages/Schedule.tsx
La página más completa de la aplicación. Al igual que en la aplicación HTML, TODO su estado está en la URL:
| /schedule?doctorId=1&day=2026-10-05 the schedule
/schedule?doctorId=1&day=2026-10-05&book=7 + the booking dialog
|
La página SIGUE a la URL: lee sus parámetros y los usa para determinar qué mostrar; las acciones del usuario, a su vez, modifican la URL. Esto permite recargar la página, guardarla como marcador y usar los botones Atrás y Adelante del navegador.
| // =========================================================================
// pages/Schedule.tsx - la página de la agenda (/schedule)
// -------------------------------------------------------------------------
// Tres bloques, como views/schedule.hbs de la aplicación HTML:
// 1. la elección del médico y del día;
// 2. la agenda de este médico en ese día;
// 3. el diálogo de reserva de un horario.
//
// Como en la aplicación HTML, TODO el estado de la página está en su URL:
// /schedule?doctorId=1&day=2026-10-05 la agenda
// /schedule?doctorId=1&day=2026-10-05&book=7 + el diálogo de reserva
// Por lo tanto, la página puede recargarse, guardarse como marcador, y los botones
// Atrás / Adelante del navegador funcionan. La página SIGUE su URL: lee sus
// tres parámetros (useSearchParams) y deduce de ellos lo que muestra;
// la agenda es una consulta de TanStack Query cuya clave contiene al médico
// y el día (ver ejemplo 24); las acciones del usuario, en cambio,
// cambian la URL (navigate).
//
// Lo que cada usuario ve y puede hacer lo decide el SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada horario): la página solo
// lo muestra. Un paciente ni siquiera recibe los nombres de los otros pacientes.
// =========================================================================
import { useCallback, useEffect, useState, type FormEvent } from 'react';
import { Link, useNavigate, useSearchParams } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { ApiError } from '../api/api-error';
import { api } from '../api/rdvmedecins.api';
import type { ScheduleSlot, Person } from '../api/types';
import { today, isValidDate, timeRange, longDate, label } from '../formatting';
import { isManager, isPatient, useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import BookingDialog from '../components/BookingDialog';
import PageTitle from '../components/PageTitle';
// "3" -> 3; "", "abc", "-2", ausente (null) -> null
function positiveInteger(value: string | null): number | null {
const n = Number(value);
return value !== null && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}
// la dirección de la agenda (sin el diálogo de reserva, o con él)
function scheduleUrl(doctorId: number | null, day: string, book?: number): string {
const params = new URLSearchParams({ doctorId: String(doctorId ?? ''), day });
if (book !== undefined) {
params.set('book', String(book));
}
return `/schedule?${params}`;
}
// -------------------------------------------------------------------------
// 1. la elección del médico y del día: un pequeño formulario, cuyo estado
// solo se usa antes de enviarlo. EMPIEZA con los valores de la URL; la página le da
// una clave que cambia con ellos: React entonces lo vuelve a crear, y
// empieza de nuevo desde los nuevos valores (botón Atrás...).
// -------------------------------------------------------------------------
interface PickerProps {
doctors: Person[];
doctorId: number | null;
day: string;
onView: (doctorId: number | null, day: string) => void;
}
function DoctorDayPicker({ doctors, doctorId, day, onView }: PickerProps) {
const { t } = useTranslation();
const [chosenDoctor, setChosenDoctor] = useState(doctorId);
const [chosenDay, setChosenDay] = useState(day);
function view(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
onView(chosenDoctor, chosenDay);
}
return (
<form className="card p-3 mb-3" onSubmit={view}>
<div className="row g-2 align-items-end">
<div className="col-sm-5">
<label className="form-label" htmlFor="doctorId">{t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')}</label>
<select id="doctorId" className="form-select" required value={chosenDoctor ?? ''}
onChange={(e) => setChosenDoctor(positiveInteger(e.target.value))}>
<option value="">{t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')}</option>
{doctors.map((d) => <option key={d.id} value={d.id}>{label(d)}</option>)}
</select>
</div>
<div className="col-sm-4">
<label className="form-label" htmlFor="day">{t('DOCTOR_DAY_PICKER.DAY_LABEL')}</label>
<input id="day" type="date" className="form-control" required value={chosenDay}
onChange={(e) => setChosenDay(e.target.value)} />
</div>
<div className="col-sm-3">
<button type="submit" className="btn btn-primary w-100">{t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')}</button>
</div>
</div>
</form>
);
}
// -------------------------------------------------------------------------
// la página
// -------------------------------------------------------------------------
export default function Schedule() {
const { t, i18n } = useTranslation();
const navigate = useNavigate();
const queryClient = useQueryClient();
const user = useSession((s) => s.user);
// las acciones del store de mensajes: funciones que nunca
// cambian; getState() las entrega sin suscribir la página a los mensajes
const { showSuccess, showError, showApiError, flash } = useMessages.getState();
const [submitting, setSubmitting] = useState(false);
// los parámetros de la URL
const [params] = useSearchParams();
const urlDoctorId = positiveInteger(params.get('doctorId'));
const urlDay = params.get('day');
const bookId = positiveInteger(params.get('book'));
// el día: el de la URL si es válido; de lo contrario, hoy
const invalidDay = urlDay !== null && !isValidDate(urlDay);
const day = urlDay !== null && !invalidDay ? urlDay : today();
// las listas: los médicos para todos; los pacientes solo para quienes
// tienen permiso de leerlos (ADMIN, DOCTOR: diálogo de reserva)
const doctors = useQuery({ queryKey: ['doctors'], queryFn: () => api.list('doctors') });
const clients = useQuery({
queryKey: ['clients'],
queryFn: () => api.list('clients'),
enabled: isManager(user),
});
// la agenda: sin médico en la URL, un DOCTOR ve SU agenda (el
// servidor la encuentra a partir del token); los demás no ven nada
const withSchedule = !invalidDay && (urlDoctorId !== null || user?.role === 'DOCTOR');
const schedule = useQuery({
queryKey: ['schedule', urlDoctorId, day],
queryFn: () => api.schedule(urlDoctorId, day),
enabled: withSchedule,
});
const s = withSchedule ? schedule.data : undefined;
// el médico mostrado: el de la URL, o el de la agenda recibida (DOCTOR)
const doctorId = urlDoctorId ?? s?.doctor.id ?? null;
// una fecha inválida en la URL: un mensaje (un EFECTO: actúa sobre el
// store de mensajes, no sobre el renderizado de este componente)
useEffect(() => {
if (invalidDay) {
showError('ERRORS.INVALID_DATE');
}
}, [invalidDay, showError]);
// el horario cuyo diálogo de reserva está abierto (?book=7),
// solo si este usuario puede reservarlo
const slotToBook = s?.slots.find((c) => c.id === bookId && c.bookable) ?? null;
// el nombre del paciente conectado (USER), o null para ADMIN y DOCTOR
const patient = isPatient(user) ? (user?.name ?? '') : null;
// -----------------------------------------------------------------------
// acciones
// -----------------------------------------------------------------------
// "View schedule": cambiamos la URL, la página la sigue
function viewSchedule(chosenDoctorId: number | null, chosenDay: string) {
navigate(scheduleUrl(chosenDoctorId, chosenDay));
}
// useCallback: la MISMA función de un renderizado al siguiente (el diálogo
// de reserva la usa en las dependencias de un efecto)
const closeBooking = useCallback(() => navigate(scheduleUrl(doctorId, day)), [navigate, doctorId, day]);
// el servidor es la referencia: después de cada acción, se vuelve a leer la agenda
// (y el área del paciente, que muestra su cita)
const reload = () =>
Promise.all([queryClient.invalidateQueries({ queryKey: ['schedule'] }), queryClient.invalidateQueries({ queryKey: ['my-area'] })]);
async function confirmBooking(clientId: number | null) {
if (slotToBook === null) {
return;
}
setSubmitting(true);
try {
await api.book(day, slotToBook.id, isManager(user) ? clientId : null);
flash('success', 'SCHEDULE.BOOKED');
} catch (e) {
if (e instanceof ApiError && e.key === 'ERRORS.CHOOSE_PATIENT') {
// ningún paciente elegido: el diálogo permanece abierto
showError(e.key);
return; // (finally se ejecuta de todos modos)
}
if (!(e instanceof ApiError)) {
throw e;
}
// horario ocupado entretanto, paciente que ya tiene una cita...:
// el mensaje se mostrará en la agenda, con el diálogo cerrado
flash('error', e.key, e.params);
} finally {
setSubmitting(false);
}
await closeBooking();
await reload();
}
async function cancel(c: ScheduleSlot) {
if (c.appointmentId === null || !(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
return;
}
try {
await api.cancelAppointment(c.appointmentId);
showSuccess('SCHEDULE.CANCELLED');
} catch (e) {
showApiError(e);
}
await reload();
}
// -----------------------------------------------------------------------
// renderizado
// -----------------------------------------------------------------------
let content;
if (schedule.isLoading && !s) {
content = <p className="text-muted">{t('APP.LOADING')}</p>;
} else if (s) {
content = (
<div className="card p-3">
<h5>{t('SCHEDULE.TITLE_PREFIX')} {longDate(s.day, i18n.language)} - {label(s.doctor)}</h5>
{s.slots.length > 0 ? (
<table className="table table-hover align-middle">
<thead>
<tr>
<th>{t('SCHEDULE.COLUMN_SLOT')}</th>
<th>{t('SCHEDULE.COLUMN_STATUS')}</th>
<th></th>
</tr>
</thead>
<tbody>
{s.slots.map((c) => (
<tr key={c.id} className={c.bookable ? 'free-slot' : ''}>
<td>{timeRange(c)}</td>
<td>
{c.free ? (
<span className="badge text-bg-success">{t('SCHEDULE.FREE')}</span>
) : c.patient ? (
<span className={`badge ${c.mine ? 'text-bg-primary' : 'text-bg-secondary'}`}>{label(c.patient)}</span>
) : (
<span className="badge text-bg-secondary">{t('SCHEDULE.BOOKED_BY_OTHER')}</span>
)}
</td>
<td className="text-end">
{/* "Book" es un ENLACE: agrega &book=... a la URL, que
abre el diálogo de reserva */}
{c.bookable && (
<Link className="btn btn-sm btn-outline-success" to={scheduleUrl(doctorId, day, c.id)}>
{t('SCHEDULE.BOOK')}
</Link>
)}
{c.appointmentId !== null && (
<button type="button" className="btn btn-sm btn-outline-danger" onClick={() => cancel(c)}>
{t('SCHEDULE.CANCEL_APPOINTMENT')}
</button>
)}
</td>
</tr>
))}
</tbody>
</table>
) : (
<p className="text-muted mb-0">{t('SCHEDULE.NO_SLOTS')}</p>
)}
</div>
);
} else {
content = <p className="text-muted">{t('SCHEDULE.EMPTY_STATE')}</p>;
}
return (
<>
<PageTitle titleKey="SCHEDULE.PAGE_TITLE" />
<DoctorDayPicker key={`${doctorId}|${day}`} doctors={doctors.data ?? []} doctorId={doctorId} day={day}
onView={viewSchedule} />
{/* paciente que ya tiene una cita próxima: por qué no hay botón "Book" */}
{s?.info && (
<div className="alert alert-info">
{t(s.info)} <Link to="/my-area" className="alert-link">{t('APP.MENU_MY_AREA')}</Link>
</div>
)}
{content}
{/* 3. el diálogo de reserva, solo si la URL contiene &book=... */}
{slotToBook && (
<BookingDialog time={timeRange(slotToBook)} clients={clients.data ?? []} patient={patient}
submitting={submitting} onConfirm={confirmBooking} onClose={closeBooking} />
)}
</>
);
}
|
- líneas 39–42: un parámetro de la URL es una cadena escrita por cualquiera; solo se conserva un entero positivo;
- líneas 45–51: la URL de la agenda, con o sin ventana de reserva;
- líneas 66–98: el formulario de selección de médico y fecha, un componente del mismo archivo. Su estado solo se usa antes del envío: se rellena con los valores de la URL (líneas 68–69). Sin embargo, [useState(value)] solo usa su valor durante la primera visualización: si la URL cambia (con el botón “Atrás”), el formulario conservaría la selección anterior. De ahí la clave que le asigna la página, más abajo;
- líneas 114–120: los parámetros de la URL. El día: el día de la URL si es válido y, si no, hoy;
- líneas 124–129: las listas, con [TanStack Query] (ejemplo 24). La clave [['doctors']] remite a los datos en la caché: otra página que solicite la misma clave los recibe sin una nueva solicitud. [enabled]: pacientes, solo para quienes están autorizados a verlos (ADMIN y médicos, para la ventana de citas); para un paciente, la solicitud no se envía;
- líneas 133–138: la agenda. Su clave contiene al médico y el día: cuando la URL cambia, la clave cambia y [TanStack Query] envía por sí mismo la nueva solicitud. Si no hay médico en la URL, un médico conectado ve SU PROPIA agenda; los demás no ven nada;
- línea 141: el médico mostrado: el de la URL y, si no hay, el de la agenda recibida;
- líneas 145–149: una fecha no válida en la URL: un mensaje. Esto es un EFECTO: se actúa sobre el store de mensajes, no sobre la visualización de este componente. Nunca se modifica otro estado mientras la visualización está activa;
- línea 153: el horario cuya ventana de reserva está abierta ([?book=7]), solo si este usuario puede reservarlo: una URL creada manualmente no abre nada;
- líneas 162–164: “View schedule” cambia la URL; la página se actualiza en consecuencia;
- línea 168: cerrar la ventana devuelve a la URL de la agenda. [useCallback]: la MISMA función de una visualización a la siguiente, porque la ventana de reserva la usa entre las dependencias de un efecto (véase [BookingDialog.tsx]): una función nueva en cada visualización activaría el efecto cada vez;
- Líneas 172–173: los datos del servidor tienen prioridad: después de cada acción, se actualiza la agenda (y el espacio del paciente, que muestra su cita). [TanStack Query] vuelve a leer de inmediato los datos mostrados; los datos que no se muestran se volverán a leer la próxima vez que se usen;
- líneas 175–200: la reserva:
- línea 181: ADMIN y los médicos envían el paciente seleccionado; un paciente reserva para sí mismo;
- Línea 182: el mensaje aparecerá después de la acción de navegación que cierra la ventana;
- Líneas 184–188: ningún paciente seleccionado: la ventana permanece abierta y muestra el mensaje. [return] dentro de un [try]: el bloque [finally] se ejecuta de todos modos;
- línea 194: los demás errores (horario ya ocupado, paciente que ya tiene una cita, etc.) se mostrarán en la agenda, con la ventana cerrada;
- líneas 202–213: la cancelación, tras la confirmación: [await confirm(...)] espera la respuesta del usuario (véase [stores/confirmation.ts]);
- líneas 218–272: el contenido principal, calculado antes del JSX: un mensaje de espera, la agenda o una invitación a seleccionar un médico. Un [if / else] estándar suele ser más legible que una cascada de [? :] dentro del JSX;
- líneas 239–245: el estado del horario: disponible, el nombre del paciente (en azul si es el paciente conectado) o “Booked”: un paciente NO recibe los nombres de los demás pacientes; el servidor no se los envía;
- líneas 250–254: “Book” es un ENLACE, [<Link>]: agrega [&book=...] a la URL, lo que abre la ventana de reserva;
- línea 255: “Cancel”, si el servidor ha indicado que el usuario puede cancelar esta cita;
- línea 277: la clave del formulario contiene al médico y el día. Cuando estos cambian, la clave cambia: [React] destruye el formulario y crea uno nuevo, que parte de los nuevos valores. Así es como [React] “reinicia” un componente;
- Líneas 281–285: un paciente que ya tiene una cita próxima: esto explica por qué no hay botón “Book”;
- líneas 290–293: la ventana de reserva aparece solo si la URL contiene [&book=...].
10.4.10.3. src/pages/persons.config.ts
| // =========================================================================
// pages/persons.config.ts - ¿médicos o clientes?
// -------------------------------------------------------------------------
// Las páginas de administración de los médicos y de los clientes son IDÉNTICAS: la misma
// lista, el mismo formulario. Como en la aplicación HTML (clase abstracta
// PersonsController), se escriben UNA sola vez (Persons.tsx,
// PersonForm.tsx); solo cambian la dirección de la API y las
// claves de las etiquetas, descritas aquí. El enrutador pasa el tipo a cada página
// (ver routes.tsx).
// =========================================================================
import type { PersonType } from '../api/rdvmedecins.api';
export interface PersonKeys {
title: string; // "Doctors"
add: string; // "Add a doctor"
edit: string; // "Edit a doctor"
empty: string; // "No doctor."
confirmDelete: string;
added: string; // "Doctor {name} has been added (login: {login})."
edited: string;
deleted: string;
}
export const PERSON_KEYS: Record<PersonType, PersonKeys> = {
doctors: {
title: 'DOCTORS.TITLE',
add: 'DOCTORS.ADD',
edit: 'DOCTORS.EDIT',
empty: 'DOCTORS.EMPTY',
confirmDelete: 'DOCTORS.DELETE_CONFIRM',
added: 'DOCTORS.ADDED',
edited: 'DOCTORS.UPDATED',
deleted: 'DOCTORS.DELETED',
},
clients: {
title: 'CLIENTS.TITLE',
add: 'CLIENTS.ADD',
edit: 'CLIENTS.EDIT',
empty: 'CLIENTS.EMPTY',
confirmDelete: 'CLIENTS.DELETE_CONFIRM',
added: 'CLIENTS.ADDED',
edited: 'CLIENTS.UPDATED',
deleted: 'CLIENTS.DELETED',
},
};
// {name} y {login} de los mensajes "added / updated / deleted"
export function messageParams(p: { firstName: string; lastName: string; login?: string }): Record<string, string> {
return { name: `${p.firstName} ${p.lastName}`, login: p.login ?? '' };
}
|
Las páginas de administración de médicos y de clientes son IDÉNTICAS: misma lista, mismo formulario. Como en la aplicación HTML (clase abstracta [PersonsController]), se escriben UNA SOLA VEZ; lo único que cambia es la dirección de la API (el tipo, ['doctors'] o ['clients']) y las claves de las etiquetas, que se describen aquí.
- líneas 14–23: las claves de traducción específicas de cada tipo;
- línea 25: [Record<PersonType, PersonKeys>]: un objeto que tiene exactamente una propiedad por tipo; [doctors] y [clients]: el compilador señala un elemento faltante;
- líneas 49–51: los parámetros [{{name}}] y [{{login}}] de los mensajes “agregado / modificado / eliminado”.
10.4.10.4. src/pages/Persons.tsx
| // =========================================================================
// pages/Persons.tsx - la lista de los médicos O de los clientes (ADMIN)
// -------------------------------------------------------------------------
// Una sola página para ambos: el tipo ('doctors' o 'clients') llega
// como prop (ver routes.tsx); las etiquetas específicas de cada uno están en
// persons.config.ts. Equivalente de views/persons/list.hbs de
// la aplicación HTML.
// =========================================================================
import { Link } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api, type PersonType } from '../api/rdvmedecins.api';
import type { Person } from '../api/types';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import PageTitle from '../components/PageTitle';
import { PERSON_KEYS, messageParams } from './persons.config';
export default function Persons({ type }: { type: PersonType }) {
const { t } = useTranslation();
const queryClient = useQueryClient();
const keys = PERSON_KEYS[type];
// la lista; la clave contiene el tipo: médicos y clientes tienen cada uno la suya
const persons = useQuery({ queryKey: [type], queryFn: () => api.list(type) });
async function remove(p: Person) {
if (!(await confirm(keys.confirmDelete))) {
return;
}
const messages = useMessages.getState();
try {
await api.remove(type, p.id);
messages.showSuccess(keys.deleted, messageParams(p));
} catch (e) {
// un médico que todavía tiene citas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
messages.showApiError(e);
}
await queryClient.invalidateQueries({ queryKey: [type] });
}
const list = persons.data;
let content;
if (list === undefined) {
// aún no cargado (o la carga falló: el mensaje está en la parte inferior de la página)
content = <p className="text-muted mb-0">{t('APP.LOADING')}</p>;
} else if (list.length === 0) {
content = <p className="text-muted mb-0">{t(keys.empty)}</p>;
} else {
content = (
<table className="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{t('PERSONS.COLUMN_TITLE')}</th>
<th>{t('PERSONS.COLUMN_FIRSTNAME')}</th>
<th>{t('PERSONS.COLUMN_LASTNAME')}</th>
<th>{t('PERSONS.COLUMN_LOGIN')}</th>
<th></th>
</tr>
</thead>
<tbody>
{list.map((p) => (
<tr key={p.id}>
<td>{p.title}</td>
<td>{p.firstName}</td>
<td>{p.lastName}</td>
<td><code>{p.login}</code></td>
<td className="text-end">
<div className="d-inline-flex gap-2">
<Link className="btn btn-sm btn-outline-primary" to={`/${type}/${p.id}/edit`}>{t('PERSONS.EDIT')}</Link>
<button type="button" className="btn btn-sm btn-outline-danger" onClick={() => remove(p)}>
{t('PERSONS.DELETE')}
</button>
</div>
</td>
</tr>
))}
</tbody>
</table>
);
}
return (
<>
<PageTitle titleKey={keys.title} />
<div className="d-flex justify-content-between align-items-center mb-3">
<h4 className="mb-0">{t(keys.title)}</h4>
<Link className="btn btn-primary" to={`/${type}/add`}>{t(keys.add)}</Link>
</div>
<div className="card p-3">{content}</div>
</>
);
}
|
La lista de médicos o de clientes. El tipo se pasa como una propiedad (véase [routes.tsx]).
- Línea 25: la lista. Su clave es el tipo: los médicos y los clientes tienen cada uno la suya. La lista de médicos son los MISMOS datos que la lista de la agenda (clave [['doctors']]): ambas aprovechan la caché;
- Líneas 27–40: eliminación, tras la confirmación, seguida de la recarga de la lista. Un médico que todavía tiene citas no se puede eliminar: el servidor devuelve una respuesta 409 y se muestra un mensaje al pie de la página;
- línea 31: [getState()] proporciona las funciones del store sin suscribir la página a los mensajes: no necesita volver a mostrarse cuando cambia un mensaje;
- líneas 44–81: el contenido: “Loading…”, “No doctors” o la tabla;
- línea 70: “Edit” es un enlace a la página del formulario.
10.4.10.5. src/pages/PersonForm.tsx
| // =========================================================================
// pages/PersonForm.tsx - creación O actualización de un médico o
// de un cliente (ADMIN)
// -------------------------------------------------------------------------
// /doctors/add -> creación (sin parámetro id)
// /doctors/3/edit -> actualización (parámetro id = "3")
// (y las mismas direcciones bajo /clients). Equivalente de
// views/persons/form.hbs de la aplicación HTML.
//
// Dos componentes:
// - PersonForm lee el registro a actualizar (si lo hay);
// - Form solo se muestra una vez leído el registro: EMPIEZA con
// sus valores (estado inicial), sin tener que copiarlos después.
// Aquí no se verifica ninguna regla: el servidor valida todo, y sus errores
// se muestran debajo de los campos (ver hooks/useFormSubmit.ts).
// La VERSIÓN leída con el registro vuelve con la actualización: si otro
// ADMIN la ha modificado entretanto, el servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================
import { useEffect, useState, type FormEvent } from 'react';
import { Link, useNavigate, useParams } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { ApiError } from '../api/api-error';
import { api, type PersonType } from '../api/rdvmedecins.api';
import type { PersonData } from '../api/types';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';
import ErrorPage from './ErrorPage';
import { PERSON_KEYS, messageParams } from './persons.config';
const EMPTY: PersonData = { title: 'Mr', firstName: '', lastName: '', login: '', password: '' };
// -------------------------------------------------------------------------
// el formulario en sí
// -------------------------------------------------------------------------
interface FormProps {
type: PersonType;
id: number | null; // null: creación
initial: PersonData;
}
function Form({ type, id, initial }: FormProps) {
const { t } = useTranslation();
const navigate = useNavigate();
const queryClient = useQueryClient();
const submission = useFormSubmit();
const [form, setForm] = useState(initial);
const keys = PERSON_KEYS[type];
const creating = id === null;
function edit(field: keyof PersonData, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
async function save(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
const messages = useMessages.getState();
const succeeded = await submission.submit(async () => {
const p = id === null ? await api.add(type, form) : await api.edit(type, id, form);
messages.flash('success', creating ? keys.added : keys.edited, messageParams(p));
});
const key = useMessages.getState().error?.key;
if (succeeded) {
await queryClient.invalidateQueries({ queryKey: [type] }); // la lista ha cambiado
navigate(`/${type}`);
} else if (key === 'ERRORS.DOCTOR_NOT_FOUND' || key === 'ERRORS.PATIENT_NOT_FOUND') {
// eliminado entretanto por otro ADMIN: de vuelta a la lista
messages.flash('error', key);
navigate(`/${type}`);
}
}
return (
<div className="row justify-content-center">
<div className="col-md-8 col-lg-6">
<div className="card p-4">
<h5 className="card-title mb-3">{t(creating ? keys.add : keys.edit)}</h5>
{/* noValidate: es el SERVIDOR quien valida (es la referencia) */}
<form noValidate onSubmit={save}>
<PersonFields values={form} errors={submission.errors} onChange={edit} />
<h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
<InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30}
value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login}
help={creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'} />
{/* nunca prellenada: la contraseña nunca vuelve del servidor */}
<InputField className="mb-4" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" maxLength={72}
autoComplete="new-password" value={form.password} onChange={(v) => edit('password', v)}
error={submission.errors.password} params={submission.params}
help={creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT'} />
<div className="d-flex gap-2">
<button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('PERSONS.SAVE')}</button>
<Link className="btn btn-secondary" to={`/${type}`}>{t('PERSONS.BACK')}</Link>
</div>
</form>
</div>
</div>
</div>
);
}
// -------------------------------------------------------------------------
// la página: creación, o lectura del registro a actualizar
// -------------------------------------------------------------------------
export default function PersonForm({ type }: { type: PersonType }) {
const { id: urlId } = useParams(); // undefined para una creación
const navigate = useNavigate();
const keys = PERSON_KEYS[type];
const validId = urlId === undefined || /^\d+$/.test(urlId);
const id = urlId === undefined || !validId ? null : Number(urlId);
// actualización: se lee el registro (incluida su versión)
// - gcTime: 0: el registro no se conserva en el caché tras la visita; la
// siguiente visita lo leerá de nuevo, siempre actualizado (de lo contrario el formulario
// empezaría con una versión obsoleta: 409 CONCURRENT_UPDATE);
// - meta.errorHandled: un error de lectura se maneja AQUÍ, y no
// por el manejador de errores común (ver main.tsx)
const details = useQuery({
queryKey: [type, id],
queryFn: () => api.read(type, id!),
enabled: id !== null,
gcTime: 0,
meta: { errorHandled: true },
});
// registro que no existe (eliminado entretanto...): de vuelta a la lista
useEffect(() => {
if (details.error instanceof ApiError) {
useMessages.getState().flash('error', details.error.key, details.error.params);
navigate(`/${type}`);
}
}, [details.error, navigate, type]);
// /doctors/abc/edit: esta dirección no existe
if (!validId) {
return <ErrorPage code={404} />;
}
const p = details.data;
return (
<>
<PageTitle titleKey={id === null ? keys.add : keys.edit} />
{id === null ? (
<Form type={type} id={null} initial={EMPTY} />
) : (
p && (
<Form type={type} id={id}
initial={{ title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', password: '', version: p.version }} />
)
)}
</>
);
}
|
Una sola página para la creación ([/doctors/add]) y la edición ([/doctors/3/edit]), compuesta por dos componentes:
- líneas 46–106: el formulario propiamente dicho. Se muestra solo después de haber leído el registro y PARTE de sus valores ([useState(initial)]): no es necesario copiarlos después, en un efecto, cuando llega el registro:
- líneas 55–58: se escribe en un campo y su error desaparece;
- líneas 60–76: la operación de guardado. En una actualización, [form] contiene la VERSIÓN leída junto con el registro: si otro ADMIN lo modificó mientras tanto, el servidor responde con un 409 [ERRORS.CONCURRENT_UPDATE];
- líneas 68–70: si tiene éxito, la lista ha cambiado: se invalida y luego el programa vuelve a ella con el mensaje;
- líneas 71–75: el registro se eliminó mientras tanto: se vuelve a la lista. Los demás errores permanecen mostrados en el formulario;
- línea 84: [noValidate]: el navegador no valida los campos [required]; es el SERVIDOR quien valida, y es el que cuenta;
- Línea 91: el campo de contraseña nunca se rellena previamente: la contraseña nunca se devuelve desde el servidor;
- Líneas 111–159: la página:
- línea 112: el parámetro de ruta [:id], que está ausente en una creación nueva;
- líneas 124–130: lectura del registro para una edición. [gcTime: 0]: el registro no se guarda en la caché después de la visita; la siguiente visita lo volverá a leer, manteniéndolo actualizado (de lo contrario, el formulario partiría de una versión desactualizada). [meta: { errorHandled: true }]: un error de lectura se maneja aquí, y no en el manejador común (véase [main.tsx]);
- líneas 133–138: el registro no existe (eliminado mientras tanto, dirección escrita manualmente...): se vuelve a la lista, con un mensaje;
- líneas 141–143: [/doctors/abc/edit]: esta dirección no existe;
- líneas 149–156: una alta nueva: el formulario vacío; una edición: el formulario, una vez leído el registro. [login: p.login ?? '']: el login de una persona se envía solo a ADMIN; es opcional en el tipo [Person].
10.4.10.6. src/pages/Register.tsx
| // =========================================================================
// pages/Register.tsx - "Create a patient account" (/register)
// -------------------------------------------------------------------------
// Solo se llega aquí después de copiar el CAPTCHA de la página de inicio de sesión
// (botón "Create a patient account"): el servidor ha emitido entonces un
// pase, que la guardia de la ruta ha verificado (ver guards.ts).
// Los mismos campos que el formulario del ADMIN, pero el login y la
// contraseña son obligatorios, con confirmación. Equivalente de
// views/account/registration.hbs de la aplicación HTML.
// =========================================================================
import { useState, type FormEvent } from 'react';
import { Link, useNavigate } from 'react-router';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import type { Registration } from '../api/types';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';
// longitud mínima de una contraseña elegida por un paciente: el mismo valor
// que el servidor (que también devuelve {min} con el error PASSWORD_TOO_SHORT)
const PASSWORD_MIN = '6';
export default function Register() {
const { t } = useTranslation();
const navigate = useNavigate();
const submission = useFormSubmit();
const [form, setForm] = useState<Registration>({
title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '',
});
// los parámetros del mensaje de ayuda Y de los errores de contraseña
const passwordParams = { min: PASSWORD_MIN, ...submission.params };
function edit(field: keyof Registration, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
async function create(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
let login = '';
const succeeded = await submission.submit(async () => {
login = (await api.register(form)).login;
});
const messages = useMessages.getState();
if (succeeded) {
// de vuelta a la página de inicio de sesión, con el login prellenado
messages.flash('success', 'REGISTRATION.DONE', { login });
navigate(`/login?login=${encodeURIComponent(login)}`);
} else if (messages.error?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
// pase expirado (15 minutos): de vuelta al CAPTCHA
messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
navigate('/login');
}
}
return (
<div className="row justify-content-center">
<PageTitle titleKey="REGISTRATION.TITLE" />
<div className="col-md-8 col-lg-6">
<div className="card p-4">
<h5 className="card-title mb-1">{t('REGISTRATION.TITLE')}</h5>
<p className="text-muted small mb-3">{t('REGISTRATION.INTRO')}</p>
<form noValidate onSubmit={create}>
<PersonFields values={form} errors={submission.errors} onChange={edit} />
<h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
<InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30} autoComplete="username"
required value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login}
help="REGISTRATION.LOGIN_HELP" />
<div className="row g-3 mb-3">
<InputField className="col-sm-6" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" maxLength={72}
autoComplete="new-password" required value={form.password} onChange={(v) => edit('password', v)}
error={submission.errors.password} params={passwordParams} help="REGISTRATION.PASSWORD_HELP" />
<InputField className="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
maxLength={72} autoComplete="new-password" required value={form.confirmation}
onChange={(v) => edit('confirmation', v)} error={submission.errors.confirmation} />
</div>
<div className="d-flex gap-2">
<button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('REGISTRATION.SUBMIT')}</button>
<Link className="btn btn-secondary" to="/login">{t('REGISTRATION.BACK_TO_LOGIN')}</Link>
</div>
</form>
</div>
</div>
</div>
);
}
|
Creación de una cuenta de paciente. Solo se puede llegar aquí después de ingresar el CAPTCHA de la página de inicio de sesión: el servidor ha emitido un pase, que el guardián ha verificado.
- línea 25: la longitud mínima de la contraseña, para el mensaje de ayuda (“Al menos 6 caracteres.”). El servidor también la devuelve con el error [ERRORS.PASSWORD_TOO_SHORT];
- línea 35: los parámetros del mensaje de ayuda Y de los errores de contraseña: los parámetros del servidor, si los hay, tienen prioridad;
- líneas 42–58: la creación de la cuenta:
- línea 52: si tiene éxito, se vuelve a la página de inicio de sesión con el nombre de usuario rellenado;
- líneas 53–57: el token ha expirado (15 minutos): se vuelve a la página de inicio de sesión para obtener un nuevo CAPTCHA.
10.4.10.7. src/pages/PatientArea.tsx
| // =========================================================================
// pages/PatientArea.tsx - "My area" (/my-area, rol USER)
// -------------------------------------------------------------------------
// La página de inicio del paciente, justo después de iniciar sesión:
// - dos opciones: [Manage my account] y [View a schedule];
// - su próxima cita, si tiene una, con el medio para cancelarla.
// Equivalente de views/patient/area.hbs de la aplicación HTML.
// =========================================================================
import { Link } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import { timeRange, longDate, label } from '../formatting';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import PageTitle from '../components/PageTitle';
export default function PatientArea() {
const { t, i18n } = useTranslation();
const queryClient = useQueryClient();
const area = useQuery({ queryKey: ['my-area'], queryFn: api.myArea });
async function cancel(appointmentId: number) {
if (!(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
return;
}
const messages = useMessages.getState();
try {
await api.cancelAppointment(appointmentId);
messages.showSuccess('SCHEDULE.CANCELLED');
} catch (e) {
messages.showApiError(e);
}
// el área Y las agendas han cambiado
await queryClient.invalidateQueries({ queryKey: ['my-area'] });
await queryClient.invalidateQueries({ queryKey: ['schedule'] });
}
const a = area.data;
if (!a) {
return (
<>
<PageTitle titleKey="AREA.TITLE" />
<p className="text-muted">{t('APP.LOADING')}</p>
</>
);
}
return (
<>
<PageTitle titleKey="AREA.TITLE" />
<h4 className="mb-3">{t('AREA.HELLO', { name: label(a.patient) })}</h4>
<div className="row g-3 mb-4">
<div className="col-sm-6">
<Link className="card p-4 h-100 text-decoration-none option-card" to="/my-account">
<h5 className="mb-1">{t('AREA.MANAGE_ACCOUNT')}</h5>
<span className="text-muted">{t('AREA.MANAGE_ACCOUNT_HELP')}</span>
</Link>
</div>
<div className="col-sm-6">
<Link className="card p-4 h-100 text-decoration-none option-card" to="/schedule">
<h5 className="mb-1">{t('AREA.VIEW_SCHEDULE')}</h5>
<span className="text-muted">{t('AREA.VIEW_SCHEDULE_HELP')}</span>
</Link>
</div>
</div>
<div className="card p-3">
<h5>{t('AREA.MY_APPOINTMENT')}</h5>
{/* normalmente solo una (regla "una cita próxima a la vez"),
pero la página puede mostrar varias */}
{a.appointments.map((appointment, i) => (
<div key={appointment.id} className={`d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 ${i < a.appointments.length - 1 ? 'border-bottom' : ''}`}>
<div>
<div className="fw-semibold">{longDate(appointment.day, i18n.language)}, {timeRange(appointment.slot)}</div>
<div className="text-muted">
{label(appointment.doctor)} -{' '}
{/* la agenda del médico en ese día: el paciente ve su nombre en ella */}
<Link to={`/schedule?${new URLSearchParams({ doctorId: String(appointment.doctor.id), day: appointment.day })}`}>
{t('AREA.SEE_IN_SCHEDULE')}
</Link>
</div>
</div>
<button type="button" className="btn btn-outline-danger" onClick={() => cancel(appointment.id)}>{t('AREA.CANCEL_APPOINTMENT')}</button>
</div>
))}
{a.appointments.length === 0 && <p className="text-muted mb-0">{t('AREA.NO_APPOINTMENT')}</p>}
</div>
</>
);
}
|
La página de inicio del paciente: dos opciones, “Manage my account” y “View a schedule”, y su próxima cita, que puede cancelar.
- línea 22: el espacio del paciente. [queryFn: api.myArea]: la función misma, sin envolverla en una función flecha; no tiene parámetros;
- Líneas 24–38: la cancelación, tras la confirmación. El espacio Y las agendas han cambiado: ambos se invalidan;
- líneas 41–48: mientras no se haya leído el espacio, “Loading…”;
- líneas 55–58: toda una tarjeta de [Bootstrap] es un enlace: [<Link>] acepta cualquier contenido;
- líneas 72–86: la próxima cita. Normalmente solo una (la regla de “una cita próxima a la vez”), pero la página puede mostrar varias;
- línea 79: un enlace a la agenda del médico para ese día, donde el paciente ve su nombre.
10.4.10.8. src/pages/MyAccount.tsx
| // =========================================================================
// pages/MyAccount.tsx - "Manage my account" (/my-account, rol USER)
// -------------------------------------------------------------------------
// Dos formularios independientes, como views/patient/account.hbs:
// 1. la actualización (identidad, login, nueva contraseña opcional);
// 2. la eliminación de la cuenta - que también cancela sus citas.
// Ambos requieren la contraseña ACTUAL (verificada por el servidor).
// Dos formularios, por lo tanto dos estados y dos useFormSubmit (dos conjuntos
// de errores). Como en PersonForm, el formulario de actualización solo se
// muestra una vez leída la cuenta, y empieza con sus valores.
// =========================================================================
import { useState, type FormEvent } from 'react';
import { Link, useNavigate } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import type { MyAccountUpdate, MyAccount as Account } from '../api/types';
import { useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';
// -------------------------------------------------------------------------
// 1. la actualización
// -------------------------------------------------------------------------
function Update({ account }: { account: Account }) {
const { t } = useTranslation();
const navigate = useNavigate();
const queryClient = useQueryClient();
const submission = useFormSubmit();
const [form, setForm] = useState<MyAccountUpdate>({ ...account, password: '', confirmation: '', currentPassword: '' });
function edit(field: keyof MyAccountUpdate, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
async function save(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
const succeeded = await submission.submit(async () => {
// el servidor ha emitido un token NUEVO (nombre, login): la barra de
// navegación debe seguirlo
useSession.getState().update(await api.editMyAccount(form));
useMessages.getState().flash('success', 'MY_ACCOUNT.UPDATED');
});
if (succeeded) {
await queryClient.invalidateQueries({ queryKey: ['my-area'] });
navigate('/my-area');
} else {
// nunca una contraseña dejada en el campo tras un envío rechazado;
// el valor se cambia SIN pasar por edit(), para no borrar el error
// que el servidor acaba de asociarle
setForm((f) => ({ ...f, currentPassword: '' }));
}
}
return (
<div className="card p-4 mb-4">
<h5 className="card-title mb-3">{t('MY_ACCOUNT.TITLE')}</h5>
<form noValidate onSubmit={save}>
<PersonFields values={form} errors={submission.errors} onChange={edit} />
<h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
<InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30} autoComplete="username"
required value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login} />
<div className="row g-3 mb-3">
<InputField className="col-sm-6" fieldId="password" type="password" label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
maxLength={72} autoComplete="new-password" value={form.password}
onChange={(v) => edit('password', v)} error={submission.errors.password} params={submission.params}
help="PERSONS.PASSWORD_HELP_EDIT" />
<InputField className="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
maxLength={72} autoComplete="new-password" value={form.confirmation}
onChange={(v) => edit('confirmation', v)} error={submission.errors.confirmation} />
</div>
<InputField className="mb-4" fieldId="currentPassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
maxLength={72} autoComplete="current-password" required value={form.currentPassword}
onChange={(v) => edit('currentPassword', v)} error={submission.errors.currentPassword}
help="MY_ACCOUNT.CURRENT_PASSWORD_HELP" />
<div className="d-flex gap-2">
<button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('PERSONS.SAVE')}</button>
<Link className="btn btn-secondary" to="/my-area">{t('MY_ACCOUNT.BACK')}</Link>
</div>
</form>
</div>
);
}
// -------------------------------------------------------------------------
// 2. la eliminación: un formulario con un solo campo
// -------------------------------------------------------------------------
function Deletion() {
const { t } = useTranslation();
const navigate = useNavigate();
const submission = useFormSubmit();
const [currentPassword, setCurrentPassword] = useState('');
async function remove(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
if (!(await confirm('MY_ACCOUNT.DELETE_CONFIRM'))) {
return;
}
const succeeded = await submission.submit(() => api.deleteMyAccount(currentPassword));
if (succeeded) {
useSession.getState().forget(); // el servidor ha borrado la cookie del token
useMessages.getState().flash('success', 'MY_ACCOUNT.DELETED');
navigate('/login');
}
}
return (
<div className="card p-4 border-danger">
<h5 className="card-title text-danger mb-1">{t('MY_ACCOUNT.DELETE_TITLE')}</h5>
<p className="text-muted small">{t('MY_ACCOUNT.DELETE_HELP')}</p>
<form className="d-flex flex-wrap gap-2 align-items-end" noValidate onSubmit={remove}>
<InputField className="flex-grow-1" fieldId="deletePassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
maxLength={72} autoComplete="current-password" required value={currentPassword}
onChange={(v) => {
setCurrentPassword(v);
submission.clearError('currentPassword');
}}
error={submission.errors.currentPassword} />
<button type="submit" className="btn btn-danger" disabled={submission.submitting}>{t('MY_ACCOUNT.DELETE_SUBMIT')}</button>
</form>
</div>
);
}
// -------------------------------------------------------------------------
// la página
// -------------------------------------------------------------------------
export default function MyAccount() {
const { t } = useTranslation();
// gcTime: 0: se vuelve a leer en cada visita (su versión debe estar actualizada)
const account = useQuery({ queryKey: ['my-account'], queryFn: api.myAccount, gcTime: 0 });
return (
<div className="row justify-content-center">
<PageTitle titleKey="MY_ACCOUNT.TITLE" />
<div className="col-md-8 col-lg-6">
{account.data ? <Update account={account.data} /> : <p className="text-muted">{t('APP.LOADING')}</p>}
<Deletion />
</div>
</div>
);
}
|
Dos formularios independientes y, por lo tanto, dos componentes, cada uno con su propio estado y su propio [useFormSubmit] (dos conjuntos de errores):
- líneas 30–90: modificación de la identidad, del login y, opcionalmente, de la contraseña:
- línea 35: el formulario parte de los valores de la cuenta (incluida su versión), con los campos de contraseña vacíos;
- línea 47: el servidor ha emitido un token NUEVO, con el nuevo nombre y el nuevo login, y redirige al usuario: se guarda en el store de sesión y la barra de navegación se actualiza en consecuencia;
- líneas 53–58: se rechazó un envío: una contraseña nunca debe quedar en un campo. Se cambia el valor SIN pasar por [edit()], para no borrar el error que el servidor acaba de asociar al campo;
- líneas 95–130: eliminación de la cuenta, lo que también cancela sus citas:
- línea 99: un formulario con un solo campo: una sola cadena;
- líneas 107–111: la cuenta se elimina y el servidor ha borrado la cookie del token: el cliente olvida al usuario y luego va a la página de inicio de sesión, junto con el mensaje;
- líneas 135–149: la página. [gcTime: 0]: la cuenta se vuelve a leer en cada visita; su versión debe estar actualizada. La eliminación se muestra de inmediato; la modificación, una vez leída la cuenta.
10.4.10.9. src/pages/ErrorPage.tsx
| // =========================================================================
// pages/ErrorPage.tsx - la página de error: 404 (dirección desconocida) o 403
// (rol insuficiente, ver guards.ts). Equivalente de views/error.hbs.
// =========================================================================
import { Link } from 'react-router';
import { useTranslation } from 'react-i18next';
import PageTitle from '../components/PageTitle';
export default function ErrorPage({ code }: { code: 403 | 404 }) {
const { t } = useTranslation();
return (
<div className="card p-4">
<PageTitle titleKey="ERROR_PAGE.TITLE" />
<h4 className="text-danger">{t('ERROR_PAGE.TITLE')} {code}</h4>
<p>{t(code === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND')}</p>
<Link to="/" className="btn btn-primary align-self-start">{t('ERROR_PAGE.BACK')}</Link>
</div>
);
}
|
Página de error: 404 (dirección desconocida) o 403 (permisos insuficientes). [code: 403 | 404]: esta propiedad solo puede tomar estos dos valores.