Skip to content

11. Caso de estudio: el cliente Ionic de la aplicación RdvMedecins

11.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; los cursos de [Vue.js], [Angular] y [React] escribieron clientes web para ella, que generan las MISMAS páginas en el navegador a partir de los datos JSON del servidor descritos en el capítulo “El servidor RdvMedecins, una caja negra”; el curso de [Flutter] desarrolló un cliente móvil. Aquí desarrollamos el cliente [Ionic]: una aplicación móvil ([Android]), construida con [Angular] y [Capacitor], que TAMBIÉN es una aplicación web, sin hacer ningún cambio.

El cliente debe ofrecer todo lo que ofrecían los demás:

  • una pantalla 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 del 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 próximas, que puede cancelar) y la gestión de la cuenta;
  • dos idiomas: francés e inglés;
  • las mismas direcciones que los clientes web ([/schedule?doctorId=1&day=...]). En el teléfono son invisibles, pero organizan la aplicación; en la web, los usuarios pueden recargarlas, guardarlas como marcadores y navegar por la aplicación con los botones Atrás/Adelante del navegador.

Una aplicación móvil añade sus propios requisitos: una pantalla estrecha (sin tablas de cinco columnas), un teclado que oculta la mitad de la pantalla, un botón Atrás, un administrador de contraseñas y solicitudes HTTP que no provienen de una página web servida por el servidor (¿dónde se debe almacenar la cookie del token?).

Esta es una oportunidad para reunir todo lo que los ejemplos presentaron por separado: componentes y signals, formularios, el enrutador y las guardias, el estado compartido, las traducciones y la comunicación con el servidor.

11.2. Instalación y ejecución

El servidor JSON debe estar instalado y en ejecución (vea el capítulo “El servidor RdvMedecins: una caja negra”). El modo de prueba del CAPTCHA no es necesario: puede dejar el campo [CAPTCHA_TEST] vacío en el archivo [.env] del servidor.

En una ventana de consola abierta en la carpeta [rdvmedecins_ionic]:

npm install
npm start
  • línea 1: descarga los paquetes del proyecto (carpeta [node_modules]), descritos en [package.json];
  • línea 2: inicia [ng serve], el servidor de desarrollo de [Angular], en la dirección http://localhost:8100. Reenvía las solicitudes /api al servidor JSON (archivo [proxy.conf.json], como en los ejemplos 22 a 25). Abra esta URL en [Chrome], de preferencia con las herramientas de desarrollo (F12) en modo “dispositivo móvil” (Ctrl+Shift+M), con el tamaño de un teléfono.

Como en los ejemplos, cualquier cambio en un archivo fuente se compila y se recarga de inmediato en el navegador.

Para probarla en [Android] (requiere el SDK de [Android] y [Android Studio]; vea el capítulo “Configuración del entorno de desarrollo”):

1
2
3
4
npx cap add android
npx ng build
npx cap sync android
npx cap run android
  • Línea 1: solo una vez: crea el proyecto [Android Studio] (carpeta [android/]). Con el JDK de un [Android Studio] reciente ([Java] 25), luego se actualiza el proyecto a [Gradle] 9.1 (archivo [android/gradle/wrapper/gradle-wrapper.properties], vea el Ejemplo 01);
  • línea 2: compila la aplicación web en [dist/rdvmedecins_ionic/browser/];
  • línea 3: la copia al proyecto [Android];
  • línea 4: la ejecuta en el emulador o en un teléfono conectado por USB (el comando solicita elegir cuál). El emulador se conecta al servidor en la dirección [10.0.2.2:8080] (vea el ejemplo 22); para un teléfono real, indique la dirección de la computadora en la red Wi-Fi durante la compilación: [npx ng build --define "SERVER='http://192.168.1.20:8080'"] (vea [config.ts]). El capítulo “Despliegue” detalla estos pasos.

Las cuentas de demostración se enumeran en la pantalla de inicio de sesión (contraseña = login).

11.3. Uso de la aplicación

Las capturas de pantalla de esta sección provienen de un teléfono con una resolución de 1082 × 2342 píxeles (412 × 892 puntos). Fueron generadas por el programa [captures/captures.mjs] (vea el Ejemplo 01), que controla un navegador [Chromium] con esta resolución y ejecuta, para cada grupo de pantallas, un escenario de la carpeta [captures/scenarios/].

11.3.1. La pantalla de inicio de sesión

La pantalla de inicio de sesión; una contraseña incorrecta: el mensaje aparece en la parte inferior de la pantalla y se muestra una nueva imagen (cada imagen se usa una sola vez):

11.3.2. La agenda, vista por el administrador y los médicos

Con la sesión iniciada como [admin], se llega a la agenda. El botón ☰ abre el menú: las pantallas accesibles para el administrador y, en la parte superior, quién ha iniciado sesión:

Seleccione un médico y una fecha (la fecha en un calendario) y luego haga clic en “Ver agenda”. La URL cambia a [/schedule?doctorId=1&day=2026-10-13]. Al hacer clic en “Reservar” se abre la ventana de reserva; la URL cambia a [/schedule?doctorId=1&day=2026-10-13&book=2]:

La cita se guarda; “Cancelar” solicita confirmación:

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

Image

11.3.3. El panel del paciente

Un paciente ([martin]) accede a “Mi área”. En una agenda, ve “Reservado” junto a las franjas horarias de otros pacientes y reserva una cita para sí mismo sin seleccionar a un paciente específico:

Su cita aparece bajo su nombre; el botón “Reservar” ya no está disponible (solo una cita próxima). En la agenda de otro médico, donde no aparece su cita, un mensaje explicaría por qué no puede reservar. Su área muestra la cita:

“Administrar mi cuenta”: cualquier cambio requiere la contraseña actual; los errores provienen del servidor:

Image

El menú de un paciente no tiene una entrada “Médicos”. En la web, si escribe por sí mismo la dirección /doctors, la guardia del enrutador muestra una página de error 403 (vea [app.routes.ts]).

11.3.4. Gestión de médicos y clientes

La lista de médicos; una entrada completada incorrectamente:

Una adición exitosa; un homónimo; se rechaza la eliminación de un médico que tiene citas:

11.3.5. Creación de una cuenta

En la pantalla de inicio de sesión, ingrese el CAPTCHA y luego toque “Crear una cuenta de paciente”. El servidor rechaza el formulario; una vez creada la cuenta, se regresa a la pantalla de inicio de sesión con los datos de acceso ya rellenados:

11.3.6. En francés, en una pantalla grande

El menú FR / EN de la barra superior vuelve a representar la pantalla localmente, sin hacer ninguna solicitud al servidor, incluidas las fechas (“mardi 13 octobre 2026”). En una pantalla ancha (la web, una tableta), el menú permanece visible a la izquierda:

Image

Image

11.3.7. Sesión expirada

Si el token expira (o si se elimina la cookie), la siguiente solicitud recibe una respuesta 401; la aplicación redirige a la pantalla de inicio de sesión con un mensaje:

Image

11.4. Arquitectura del cliente

rdvmedecins_ionic/
├── package.json             the packages, the scripts
├── angular.json             the Angular project configuration
├── tsconfig.json            the TypeScript configuration
├── proxy.conf.json          the development server (/api relay)
├── capacitor.config.ts      the Capacitor configuration (Android)
├── android/                 the Android Studio project (after npx cap add android)
├── captures/                the making of the screenshots (Playwright)
├── public/
│   └── i18n/                the dictionaries fr.json, en.json
└── src/
    ├── index.html           the page that hosts the application
    ├── main.ts              the startup
    ├── styles.scss          the common styles
    └── app/
        ├── app.ts           the root component
        ├── back-button.ts   Android's Back button
        ├── app.routes.ts    the screens, their addresses, their access rights
        ├── config.ts        the address of the server
        ├── formatting.ts    the formatting of times and days
        ├── api/             the API access layer
        ├── i18n/            the languages
        ├── state/           session, messages, cache (signal-based services)
        ├── components/      the layout and the reusable components
        └── pages/           the screens

Esta es la estructura, archivo por archivo, del cliente [Flutter], con los nombres de archivo de [Angular] (en minúsculas, con las palabras separadas por guiones):

  • una capa de datos ([api/]): la única que conoce el cliente HTTP de [Angular], las URL y el formato JSON;
  • una capa de estado ([state/]): servicios basados en signals, provistos a toda la aplicación mediante inyección de dependencias, que las pantallas leen;
  • una capa de interfaz ([pages/], [components/]): componentes que muestran el estado y transmiten las acciones del usuario.

La siguiente tabla compara el cliente [Flutter] con este cliente:

Concepto
Cliente Flutter
Cliente Ionic
Pantallas
widgets
componentes de Angular e Ionic
los elementos que rodean las pantallas
[layout.dart], el widget de un [ShellRoute]
[layout.ts], que rodea a [ion-router-outlet]
el menú
[NavigationDrawer] / [NavigationRail]
[ion-menu] en [ion-split-pane]
las direcciones
[go_router]
el enrutador de Angular
derechos de acceso
la función [redirect] del enrutador
Una guardia: [CanActivateFn]
la cookie del token
un cliente HTTP que gestiona las cookies
el navegador (web), [CapacitorHttp] (Android)
la sesión expirada (401)
una función asignada a [ApiClient]
un interceptor, [HttpInterceptorFn]
el estado compartido
[ChangeNotifier] ([provider])
servicios de signals ([inject()])
datos asíncronos
[FutureBuilder]
[resource()]
datos ya leídos
[Cache] (unas pocas líneas)
[Cache] (unas pocas líneas)
el idioma almacenado
[shared_preferences]
[@capacitor/preferences]
formulario rechazado
errores debajo de los campos
igual

A continuación se enumeran todos los archivos del cliente. Están ampliamente comentados; estos comentarios forman parte del material del curso.

11.5. Configuración del proyecto

El proyecto se creó de la misma manera que los ejemplos (vea el Ejemplo 01): [ng new], seguido de la adición de los paquetes de [Ionic] y [Capacitor]. Los archivos [angular.json] y [tsconfig.json] son los generados por [ng new]; son idénticos a los de los ejemplos, con dos excepciones: en [angular.json], el puerto del servidor de desarrollo (8100) y el archivo de retransmisión ([proxyConfig]); en [tsconfig.json], las verificaciones estrictas ([strict], [strictTemplates]).

11.5.1. package.json

{
  "name": "rdvmedecins-ionic",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "android": "ng build && cap sync android && cap run android",
    "captures": "node captures/captures.mjs"
  },
  "private": true,
  "packageManager": "npm@10.9.4",
  "dependencies": {
    "@angular/common": "^22.2.0",
    "@angular/compiler": "^22.2.0",
    "@angular/core": "^22.2.0",
    "@angular/forms": "^22.2.0",
    "@angular/platform-browser": "^22.2.0",
    "@angular/router": "^22.2.0",
    "@capacitor/android": "^8.5.2",
    "@capacitor/app": "^8.1.2",
    "@capacitor/core": "^8.5.2",
    "@capacitor/preferences": "^8.0.1",
    "@ionic/angular": "^9.0.6",
    "ionicons": "^8.1.0",
    "rxjs": "~7.8.0",
    "tslib": "^2.3.0"
  },
  "devDependencies": {
    "@angular/build": "^22.2.1",
    "@angular/cli": "^22.2.1",
    "@angular/compiler-cli": "^22.2.0",
    "@capacitor/cli": "^8.5.2",
    "playwright": "^1.56.1",
    "prettier": "^3.8.1",
    "typescript": "~6.0.2"
  }
}
  • Líneas 4–11: los scripts: [npm start] inicia el servidor de desarrollo, [npm run build] compila la aplicación, [npm run android] la compila, la copia al proyecto [Android] y la ejecuta en el teléfono; [npm run captures] genera las capturas de pantalla;
  • líneas 14–29: los paquetes de la aplicación: [Angular] (sin [@angular/animations] ni [zone.js]: la aplicación es “zoneless”, vea el Ejemplo 01), [Capacitor] (su núcleo, la plataforma [Android], el complemento [App] que da acceso al botón Atrás, y el complemento [Preferences] que almacena el idioma), [Ionic] y sus íconos; [rxjs] es la biblioteca de los [Observable] del cliente HTTP;
  • líneas 30–38: herramientas de desarrollo: el compilador de [Angular], el comando [ng], el comando [cap] de [Capacitor], [Playwright] para las capturas de pantalla, [Prettier] para el formato del código, [TypeScript].

NO hay paquetes adicionales a los de los ejemplos: ninguna biblioteca de traducción, de gestión de estado ni de formularios. Todo lo que la aplicación necesita está en [Angular] y [Ionic], y en unos pocos archivos escritos aquí.

11.5.2. proxy.conf.json

1
2
3
4
5
6
7
8
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false,
    "changeOrigin": false,
    "logLevel": "warn"
  }
}

El del Ejemplo 22: en el desarrollo web, [ng serve] reenvía las solicitudes /api al servidor JSON. Para el navegador, la aplicación y la API tienen el MISMO origen (http://localhost:8100): no hay autenticación CORS, y la cookie del token se transmite.

11.5.3. capacitor.config.ts

// =========================================================================
// capacitor.config.ts - la configuración de Capacitor
// -------------------------------------------------------------------------
// Capacitor convierte la aplicación web (la carpeta producida por ng build)
// en una aplicación Android: la envuelve en un proyecto de Android Studio
// (carpeta android/), donde se muestra mediante un "WebView", el motor del
// navegador Chrome del teléfono. Comandos (véase el capítulo Despliegue):
//     npx cap add android       (una sola vez: crea la carpeta android/)
//     ng build                  (compila la aplicación web)
//     npx cap sync android      (la copia al proyecto Android)
//     npx cap run android       (la ejecuta en un emulador o un teléfono)
// =========================================================================

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  // el identificador único de la aplicación en el teléfono (y en Play Store)
  appId: 'fr.stahe.rdvmedecins',
  // el nombre que se muestra bajo el ícono
  appName: 'RdvMedecins',
  // la carpeta de la aplicación web compilada (ng build)
  webDir: 'dist/rdvmedecins_ionic/browser',
  server: {
    // permite solicitudes HTTP sin cifrar (http://10.0.2.2:8080) hacia
    // el servidor JSON de desarrollo (quitar en producción: HTTPS)
    cleartext: true,
  },
  plugins: {
    // CapacitorHttp: las solicitudes HTTP de la aplicación ya no las hace
    // el WebView sino el código nativo de Android. Consecuencias (véase
    // api/http-client.ts): sin verificación CORS (el servidor JSON no tiene nada que
    // permitir), y las cookies (la del token de autenticación) las
    // almacena Android y las reenvía automáticamente
    CapacitorHttp: {
      enabled: true,
    },
  },
};

export default config;

La configuración de [Capacitor] (vea el Ejemplo 01):

  • línea 18: el ID de la aplicación en el teléfono (y en la [Play Store]): el de la aplicación [Flutter]. Por lo tanto, no se pueden instalar las dos al mismo tiempo en el mismo teléfono; para compararlas, habría que cambiar una;
  • línea 22: la carpeta de la aplicación web compilada, que [npx cap sync] copia en el proyecto [Android];
  • línea 26: de forma predeterminada, [Android] rechaza las solicitudes HTTP sin cifrar; se permiten para conectarse al servidor de desarrollo ([http://10.0.2.2:8080]). En producción, el servidor debe configurarse con HTTPS;
  • líneas 34–36: el complemento [CapacitorHttp] (ejemplo 22): en el teléfono, las solicitudes HTTP ya no las realiza el [WebView] sino el código nativo de [Android]. Por lo tanto, el servidor no tiene reglas CORS que seguir, y las cookies las almacena y devuelve [Android] mismo. Esto es lo que permite que el cliente [Ionic] prescinda del cliente HTTP que “gestiona las cookies” del cliente [Flutter].

11.6. Inicio de la aplicación

11.6.1. src/app/config.ts

// =========================================================================
// src/app/config.ts - ¿DÓNDE está el servidor JSON?
// -------------------------------------------------------------------------
// La pregunta no se plantea para una aplicación web servida por el
// propio servidor: las solicitudes van al MISMO origen que la página
// (una dirección relativa, /api/...). Pero una aplicación MÓVIL no tiene un
// origen utilizable (en Android, la página es servida por Capacitor
// desde https://localhost): hay que darle la dirección completa del servidor.
//   - el emulador de Android ve la computadora que lo ejecuta en
//     la dirección 10.0.2.2 (localhost, para él, es el propio emulador);
//   - un teléfono real, conectado a la misma red Wi-Fi que la computadora, debe
//     usar la dirección de la computadora en esta red (192.168.1.20...):
//     se proporciona al compilar la aplicación:
//         ng build --define "SERVER='http://192.168.1.20:8080'"
//   - en desarrollo web (ng serve), el servidor de desarrollo de Angular
//     reenvía las solicitudes /api al servidor JSON (archivo
//     proxy.conf.json): basta una dirección relativa.
// =========================================================================

import { Capacitor } from '@capacitor/core';

// el valor dado por --define "SERVER='...'" al compilar
// (ng build, ng serve). La opción reemplaza, en el código compilado, la palabra
// SERVER por el valor dado. Sin ella, SERVER no existe: typeof
// permite comprobarlo sin provocar un error
declare const SERVER: string | undefined;
const forcedServer = typeof SERVER === 'string' ? SERVER : '';

export const config = {
  // Capacitor.isNativePlatform(): true en la aplicación Android (o iOS),
  // false en un navegador; Capacitor.getPlatform(): 'android', 'ios' o 'web'
  serverUrl:
    forcedServer !== ''
      ? forcedServer
      : !Capacitor.isNativePlatform()
        ? '' // la web: mismo origen, direcciones relativas
        : Capacitor.getPlatform() === 'android'
          ? 'http://10.0.2.2:8080'
          : 'http://localhost:8080',
};

La dirección del servidor, según la plataforma (vea el Ejemplo 22):

  • Línea 26: [declare const SERVER] declara al compilador [TypeScript] una constante que este no ve en ningún otro lugar; la proporciona el comando de compilación ([ng build --define "SERVER='...'"]). La opción [--define] REEMPLAZA, en el código compilado, la palabra [SERVER] por el valor indicado: la dirección queda escrita en la aplicación compilada, igual que con [--dart-define] de [Flutter];
  • línea 27: sin esta opción, [SERVER] no existe, e intentar leerla provocaría un error en tiempo de ejecución; [typeof] es el único operador que acepta un nombre desconocido (en ese caso devuelve “undefined”);
  • Líneas 32–39: de lo contrario, una dirección web relativa (el servidor de desarrollo y, en producción, el propio servidor JSON, sirven la página Y la API), [10.0.2.2] en [Android] (la computadora, vista desde el emulador), [localhost] en los demás casos. [Capacitor.isNativePlatform()] indica si la aplicación se ejecuta en el entorno nativo de [Capacitor] (en lugar de en un navegador), y [Capacitor.getPlatform()] precisa en qué sistema.

11.6.2. src/main.ts

// =========================================================================
// src/main.ts - el punto de entrada de la aplicación
// -------------------------------------------------------------------------
// Una aplicación Angular se inicia con bootstrapApplication: Angular crea
// el componente RAÍZ (App) y lo inserta en la etiqueta <app-root> de la
// página index.html. El segundo parámetro proporciona los "providers"
// de toda la aplicación: Ionic, el enrutador, el cliente HTTP y su
// interceptor, el título de las pantallas y la carga del idioma.
// Los servicios (sesión, mensajes, caché, traducciones, API) no necesitan
// declararse aquí: providedIn: 'root' los proporciona a toda la aplicación.
// =========================================================================

import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { inject, provideAppInitializer } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter, TitleStrategy, withComponentInputBinding } from '@angular/router';
import { provideIonicAngular } from '@ionic/angular';
import { apiInterceptor } from './app/api/http-client';
import { App } from './app/app';
import { routes } from './app/app.routes';
import { PageTitle } from './app/components/page-title';
import { Translations } from './app/i18n/translations';

bootstrapApplication(App, {
  providers: [
    // Ionic: modo 'md' (Material Design) = el aspecto de Android, incluso en
    // el navegador de una computadora
    provideIonicAngular({ mode: 'md' }),
    // el enrutador: la lista de rutas (app.routes.ts);
    // withComponentInputBinding: los parámetros de una ruta (:id, ?day=...,
    // data) se entregan a los inputs del componente de la pantalla
    provideRouter(routes, withComponentInputBinding()),
    // el cliente HTTP de Angular, cuyas solicitudes pasan todas por nuestro interceptor
    provideHttpClient(withInterceptors([apiInterceptor])),
    // los títulos de nuestras pantallas son claves de traducción (véase page-title.ts)
    { provide: TitleStrategy, useClass: PageTitle },
    // antes de la primera pantalla: el idioma (recordado, o el del dispositivo)
    // y su diccionario. Angular espera el fin de la Promise devuelta
    provideAppInitializer(() => inject(Translations).start()),
  ],
}).catch((err) => console.error(err));

Inicio. Aquí solo hay proveedores: los objetos compartidos (la sesión, los mensajes, la caché, las traducciones y la capa de acceso a la API) son servicios [providedIn: 'root'], creados por [Angular] en su primera inyección (vea el Ejemplo 14).

  • línea 28: [Ionic], en modo [md] (el aspecto de [Android]);
  • línea 32: el enrutador; [withComponentInputBinding()] proporciona los parámetros de la dirección ([?day=...], [:id]) y los datos de la ruta ([data]) a los inputs de los componentes de pantalla (vea el Ejemplo 17). De este modo, las pantallas nunca tienen que leer la dirección por sí mismas;
  • línea 34: el cliente HTTP y su interceptor (vea [api/http-client.ts]);
  • línea 36: la “estrategia de títulos” del enrutador se reemplaza por la nuestra, que traduce los títulos (vea [components/page-title.ts]);
  • línea 39: [provideAppInitializer]: una función que se ejecuta ANTES de mostrar la primera pantalla; si devuelve una [Promise], [Angular] espera a que termine. Aquí se carga el diccionario del idioma de origen: la primera pantalla se muestra directamente en el idioma correcto (es el [await translations.start()] colocado antes de [runApp] en el cliente [Flutter]).

11.6.3. src/app/app.ts

// =========================================================================
// src/app/app.ts - el componente RAÍZ de la aplicación
// -------------------------------------------------------------------------
// Muestra el layout (que contiene el lugar de las pantallas) y enlaza
// entre sí los servicios de la aplicación mediante dos mecanismos:
//   1. la sesión cambia (inicio, cierre, sesión expirada): los
//      datos leídos para el usuario anterior ya no sirven (se vacía el caché), y las guardias
//      del enrutador se reevalúan para
//      la pantalla actual: son ellas las que dejan la pantalla de inicio de sesión
//      tras iniciar sesión, o las que devuelven a ella tras un cierre de sesión;
//   2. los mensajes "flash": al final de CADA navegación, los mensajes
//      de la pantalla anterior desaparecen, los dejados para la siguiente
//      pantalla aparecen (véase state/messages.ts).
// La sesión EXPIRADA (respuesta 401) la trata el interceptor
// (api/http-client.ts): vacía la sesión, y el mecanismo 1 hace el resto.
// También conecta el botón Atrás de Android (véase back-button.ts).
// =========================================================================

import { Component, computed, effect, inject, untracked } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { NavigationEnd, Router } from '@angular/router';
import { IonApp, NavController } from '@ionic/angular';
import { filter } from 'rxjs';
import { handleBackButton } from './back-button';
import { Layout } from './components/layout';
import { Cache } from './state/cache';
import { Messages } from './state/messages';
import { Session } from './state/session';

@Component({
  selector: 'app-root',
  imports: [IonApp, Layout],
  template: `
    <ion-app>
      <app-layout />
    </ion-app>
  `,
})
export class App {
  private readonly session = inject(Session);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly navigation = inject(NavController);
  // el rol del usuario con sesión iniciada (null: nadie). Un nuevo nombre
  // (actualización de la cuenta) no cambia esta señal: solo iniciar sesión
  // y cerrarla la cambian
  private readonly role = computed(() => this.session.user()?.role ?? null);
  private url = '';

  constructor() {
    // el botón Atrás de Android
    handleBackButton();
    // 1a. la sesión cambia: se vacía el caché
    effect(() => {
      this.session.user();
      untracked(() => this.cache.clear());
    });
    // 1b. inicio, cierre de sesión: las guardias se reevalúan para la dirección
    // actual. navigateRoot: la pantalla mostrada reemplazará toda la pila de
    // pantallas de Ionic (las del usuario anterior desaparecen);
    // onSameUrlNavigation: 'reload': incluso hacia la dirección actual, la
    // navegación se realiza (y las guardias se ejecutan)
    effect(() => {
      this.role();
      untracked(() => {
        // no antes de la primera navegación: ella se encarga
        if (!this.router.navigated) return;
        void this.navigation.navigateRoot(this.router.url, { onSameUrlNavigation: 'reload', replaceUrl: true });
      });
    });
    // 2. en cada navegación completada (la dirección ha cambiado): página nueva
    this.router.events
      .pipe(
        filter((e) => e instanceof NavigationEnd),
        takeUntilDestroyed(),
      )
      .subscribe((e) => {
        if (e.urlAfterRedirects !== this.url) {
          this.url = e.urlAfterRedirects;
          this.messages.newPage();
        }
      });
  }
}

El componente raíz: muestra el diseño y enlaza entre sí los servicios de la aplicación, tal como lo hacía [main.dart]:

  • líneas 34–36: [ion-app], el contenedor de toda la aplicación [Ionic], y el diseño (vea [components/layout.ts]), que contiene los lugares de las pantallas;
  • línea 48: el rol del usuario con sesión iniciada, calculado a partir de la sesión. Un signal calculado ([computed]) solo notifica a los lectores si cambia su VALOR: cambiar su nombre (“Administrar mi cuenta”) cambia el usuario, pero no su rol;
  • línea 53: el botón Atrás de [Android], enlazado mediante la función de [back-button.ts] (más abajo);
  • Líneas 55–58: 1a. Cada vez que cambia el usuario, se borra la caché: los datos leídos para el usuario anterior no son pertinentes para el siguiente (un paciente no debe ver la agenda consultada por el administrador). Un efecto ([effect]) se vuelve a ejecutar cuando cambia un signal que ha leído: en este caso, [this.session.user()]. [untracked]: lo que sucede a continuación no es una dependencia del efecto;
  • líneas 64–71: 1b. En cada inicio o cierre de sesión, el sistema “navega de nuevo” a la dirección actual, lo que vuelve a ejecutar las guardias del enrutador (vea [app.routes.ts]): es la guardia la que saca de la pantalla de inicio de sesión tras un inicio exitoso, o vuelve a ella tras un cierre de sesión o una sesión expirada. Este es el [refreshListenable] de [go_router], creado manualmente. [navigateRoot] (de [NavController] de [Ionic]): la pantalla mostrada reemplaza TODA la pila de pantallas de [Ionic]; las pantallas del usuario anterior se destruyen. [onSameUrlNavigation: 'reload']: sin esta opción, el enrutador ignora la navegación a la dirección actual;
  • línea 68: al iniciar, el efecto se ejecuta antes de la primera navegación, que de todos modos ejecutará las verificaciones: no se realiza ninguna acción;
  • Líneas 73–83: 2. Mensajes flash. El enrutador publica sus eventos en un [Observable] ([router.events]); solo se conservan los eventos de fin de navegación ([filter]) y, si la dirección ha cambiado, el sistema pasa a una “nueva página”: los mensajes de la pantalla anterior desaparecen y aparecen los publicados para esta (vea [messages.ts]). El botón Atrás, que cierra la ventana de reserva, cambia la URL: también borra los mensajes. [takeUntilDestroyed()]: la suscripción termina con el componente (en este caso, con la aplicación).

11.6.4. src/app/back-button.ts

// =========================================================================
// src/app/back-button.ts - el botón Atrás de Android
// -------------------------------------------------------------------------
// En el teléfono, Capacitor recibe la pulsación del botón Atrás. Si no tiene
// ningún listener para este evento, simplemente retrocede en el historial del
// WebView, y luego cierra la aplicación: Ionic no sabe nada
// de ello (un diálogo abierto no se cierra, ni tampoco el menú lateral).
// El plugin @capacitor/app permite suscribirse: en cuanto hay un
// listener, Capacitor transmite la pulsación a Ionic, que llama al manejador
// con la mayor prioridad:
//   - 100: se cierra un diálogo abierto (alert, ion-modal...);
//   -  99: se cierra el menú lateral abierto;
//   -   1: (el nuestro) se vuelve a la pantalla anterior; si no hay ninguna,
//          se sale de la aplicación.
// En el navegador no hay botón Atrás: no se hace nada.
// =========================================================================

import { inject } from '@angular/core';
import { NavController, Platform } from '@ionic/angular';
import { App as CapacitorApp } from '@capacitor/app';
import { Capacitor } from '@capacitor/core';

// debe llamarse en el constructor del componente raíz (contexto de inyección)
export function handleBackButton(): void {
  if (!Capacitor.isNativePlatform()) return;
  const navigation = inject(NavController);
  // un listener (vacío): Capacitor transmite ahora la pulsación a Ionic
  void CapacitorApp.addListener('backButton', () => {});
  inject(Platform).backButton.subscribeWithPriority(1, async () => {
    // pop(): vuelve a la pantalla anterior de la pila de Ionic; false: la
    // pila solo contiene la pantalla mostrada, no queda nada atrás
    if (!(await navigation.pop())) {
      await CapacitorApp.exitApp();
    }
  });
}

El mismo archivo que en los ejemplos (vea el Ejemplo 01, “El botón Atrás de Android”). Aquí, asigna las siguientes funciones al botón Atrás del teléfono, en orden: cerrar una ventana abierta (la ventana de reserva, una solicitud de confirmación, la lista de médicos, el calendario), cerrar el menú lateral, volver a la pantalla anterior y, por último, salir de la aplicación desde la primera pantalla.

11.6.5. src/styles.scss

// =========================================================================
// src/styles.scss - los estilos de toda la aplicación
// -------------------------------------------------------------------------
// las hojas de estilo de Ionic: sin ellas, sus componentes no tienen
// su aspecto. core.css es indispensable; las demás son utilidades
// (márgenes, alineaciones, clases ion-padding, ion-text-center...).
// =========================================================================

@use '@ionic/angular/css/core.css';
@use '@ionic/angular/css/normalize.css';
@use '@ionic/angular/css/structure.css';
@use '@ionic/angular/css/typography.css';
@use '@ionic/angular/css/padding.css';
@use '@ionic/angular/css/float-elements.css';
@use '@ionic/angular/css/text-alignment.css';
@use '@ionic/angular/css/text-transformation.css';
@use '@ionic/angular/css/flex-utils.css';
@use '@ionic/angular/css/display.css';

// el color principal de la aplicación (botones, barra superior): un índigo,
// como en los ejemplos del curso. Ionic deriva de --ion-color-primary las
// variantes más clara (tint) y más oscura (shade)
:root {
  --ion-color-primary: #3f51b5;
  --ion-color-primary-rgb: 63, 81, 181;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #37479f;
  --ion-color-primary-tint: #5262bc;
}

// -------------------------------------------------------------------------
// los estilos comunes a las pantallas de RdvMedecins
// -------------------------------------------------------------------------

// el título de una pantalla
h1 {
  font-size: 26px;
  font-weight: 400;
  margin: 8px 0 12px;
}

// el título de una sección ("Cuenta de usuario")
h3 {
  font-size: 15px;
  font-weight: 500;
  margin: 16px 0 12px;
}

// un texto de ayuda, en gris
.help,
.intro {
  font-size: 14px;
  color: var(--ion-color-medium-shade);
}

// un pequeño espacio bajo cada lista desplegable
ion-select {
  margin-bottom: 12px;
}

// los botones de un formulario, lado a lado (uno bajo otro si no
// caben)
.buttons {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  margin-top: 12px;
}

// las cuentas de demostración de la pantalla de inicio de sesión
.demo {
  margin-top: 16px;
  font-size: 13px;
  color: var(--ion-color-medium-shade);

  code {
    font-family: 'Roboto Mono', monospace;
    font-size: 12px;
  }
}

// el cuadro de confirmación (AlertController, véase confirmation.ts): un poco
// más ancho, y su botón "Sí" en rojo
ion-alert.confirmation {
  --min-width: 310px;
  --max-width: 340px;
}

ion-alert.confirmation button.danger-button {
  background: #d32f2f;
  color: white;
  border-radius: 20px;
  padding: 0 16px;
}

// un diálogo (ion-modal) del tamaño de su contenido, en el centro de la pantalla,
// en lugar de sobre toda la pantalla (lo predeterminado en un teléfono)
ion-modal.dialog {
  --width: calc(100% - 48px);
  --max-width: 420px;
  --height: fit-content;
  --border-radius: 16px;
}

Estilos comunes a todas las pantallas:

  • líneas 9–18: las hojas de estilo de [Ionic] (vea el Ejemplo 01);
  • líneas 23–30: el color principal, índigo, y sus variantes;
  • líneas 37–60: títulos, texto de ayuda y el espacio debajo de las listas desplegables;
  • líneas 64–69: botones de formulario, uno al lado del otro, o uno debajo del otro si no caben ([Wrap] de [Flutter], en CSS: [flex-wrap: wrap]);
  • líneas 72–81: las cuentas de demostración en la pantalla de inicio de sesión, en letra pequeña; los nombres de usuario en una fuente monoespaciada;
  • líneas 85–95: el cuadro de confirmación, un poco más ancho que el de [Ionic] (“No, volver” y “Sí, confirmar” caben en una sola línea), y su botón rojo. Los cuadros creados por [AlertController] se agregan al final de la página, fuera de cualquier componente: solo una hoja de estilo global puede afectarlos;
  • Líneas 99–104: una ventana ([ion-modal]) de clase [dialog] adopta el tamaño de su contenido y se centra en la pantalla. En un teléfono, una ventana de [Ionic] ocupa toda la pantalla de forma predeterminada; las ventanas de reserva y de calendario se parecen así a los cuadros de diálogo de [Material]. [fit-content]: la altura del contenido.

11.7. La capa de acceso a la API

11.7.1. src/app/api/api-client.ts

// =========================================================================
// src/app/api/api-client.ts - TODAS las solicitudes a la API pasan por aquí
// -------------------------------------------------------------------------
// Tomado de la capa de API de los ejemplos (ejemplo 24): un solo método,
// request(), que construye la dirección completa (config.serverUrl + /api +
// url), envía el cuerpo como JSON y devuelve una Promise de la respuesta.
//
// El cliente HTTP de Angular (HttpClient) hace pasar cada solicitud por el
// INTERCEPTOR de la aplicación (http-client.ts), que convierte cualquier
// error en un ApiError y trata, en UN solo lugar, la respuesta 401
// (sesión expirada).
// Algunas solicitudes tratan ellas mismas su 401 (el inicio de sesión, GET
// /api/auth/me...): son "públicas"; esto se señala al
// interceptor mediante el CONTEXTO de la solicitud (HttpContext).
// =========================================================================

import { HttpClient, HttpContext, HttpContextToken } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { config } from '../config';

// una información adjunta a una solicitud, leída por el interceptor. Su
// valor por defecto (false): una solicitud protegida
export const PUBLIC = new HttpContextToken<boolean>(() => false);

export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

@Injectable({ providedIn: 'root' })
export class ApiClient {
  private readonly http = inject(HttpClient);

  // isPublic: true para las rutas que tratan ellas mismas el 401.
  // Si falla, la Promise se rechaza con un ApiError
  request<T>(method: Method, url: string, body?: unknown, isPublic = false): Promise<T> {
    // http.request devuelve un Observable; firstValueFrom lo convierte en
    // Promise (la solicitud se envía en ese momento). El objeto del cuerpo se envía
    // como JSON (encabezado content-type: application/json), la respuesta JSON se
    // decodifica (null si su cuerpo está vacío)
    return firstValueFrom(
      this.http.request<T>(method, `${config.serverUrl}/api${url}`, {
        body,
        context: new HttpContext().set(PUBLIC, isPublic),
      }),
    );
  }
}

Todas las solicitudes pasan por el método [request] (vea el Ejemplo 24):

  • línea 24: un “token de contexto”, información adjunta a una solicitud que el interceptor puede leer. Su valor predeterminado lo proporciona la función: [false], una solicitud protegida;
  • línea 34: un método genérico: [request<Person[]>(...)] devuelve una [Promise<Person[]>]. [isPublic = false]: un parámetro opcional, con su valor predeterminado;
  • líneas 39–44: [http.request] devuelve un [Observable] (ejemplo 22), que solo envía la solicitud cuando alguien se suscribe a él; [firstValueFrom] se suscribe y devuelve una [Promise] con su valor inicial (la respuesta). El cuerpo es un objeto [JavaScript]: el cliente HTTP lo envía como JSON, con el encabezado [Content-Type] adecuado; el JSON de la respuesta se decodifica (en UTF-8: los acentos permanecen intactos). El contexto de la solicitud lleva la información “pública”.

El cliente [Flutter] gestionaba aquí los errores y el código de estado 401; el cliente [Ionic] los delega en el interceptor.

11.7.2. src/app/api/http-client.ts

// =========================================================================
// src/app/api/http-client.ts - el INTERCEPTOR de las solicitudes HTTP
// -------------------------------------------------------------------------
// Un interceptor es una función por la que pasa TODA solicitud del cliente
// HTTP de Angular (se declara en main.ts:
// provideHttpClient(withInterceptors([apiInterceptor]))). Recibe la
// solicitud y el manejador "next" que la envía; puede modificar la primera y
// transformar la respuesta. El nuestro trata los ERRORES:
//   - todo error se convierte en un ApiError (véase api-error.ts);
//   - la respuesta 401 de una solicitud protegida (sesión expirada) se trata
//     AQUÍ, de una vez por todas: se olvida al usuario, se vacía el
//     caché, se prepara el mensaje para la pantalla de inicio de sesión. Las guardias
//     del enrutador, reevaluadas cuando la sesión cambia (véase app.ts),
//     devuelven entonces a la pantalla de inicio de sesión.
//
// ¿Y la COOKIE del token JWT? El servidor la coloca en una cookie
// (httpOnly). El código de la aplicación NO tiene NADA que hacer:
//   - en la web, es el navegador quien almacena la cookie y la reenvía;
//   - en Android, el plugin CapacitorHttp (habilitado en
//     capacitor.config.ts) envía las solicitudes mediante el código nativo
//     de Android, que almacena las cookies y también las reenvía (y
//     las conserva cuando la aplicación se detiene y se reinicia).
// =========================================================================

import { HttpErrorResponse, HttpInterceptorFn } from '@angular/common/http';
import { inject } from '@angular/core';
import { catchError, throwError } from 'rxjs';
import { Cache } from '../state/cache';
import { Messages } from '../state/messages';
import { Session } from '../state/session';
import { PUBLIC } from './api-client';
import { ApiError } from './api-error';

export const apiInterceptor: HttpInterceptorFn = (request, next) => {
  // inject(): solo aquí, al inicio de la función (más tarde, en
  // catchError, ya no estamos en un "contexto de inyección")
  const session = inject(Session);
  const cache = inject(Cache);
  const messages = inject(Messages);
  const isPublic = request.context.get(PUBLIC);

  // next(request): se envía la solicitud; pipe(catchError(...)): qué hacer
  // si falla (la respuesta exitosa pasa sin cambios)
  return next(request).pipe(
    catchError((e: unknown) => {
      // un error que no proviene del cliente HTTP: una anomalía, se deja pasar
      if (!(e instanceof HttpErrorResponse)) return throwError(() => e);
      const error = ApiError.fromResponse(e);
      if (error.statusCode === 401 && !isPublic) {
        session.forget();
        cache.clear();
        messages.flash({ success: false, key: 'ERRORS.SESSION_EXPIRED' });
        // la pantalla que espera la respuesta mostrará TAMBIÉN este mensaje
        return throwError(() => new ApiError(401, 'ERRORS.SESSION_EXPIRED'));
      }
      return throwError(() => error);
    }),
  );
};

El interceptor de solicitudes: gestiona, en un ÚNICO lugar, todos los errores y, en particular, la respuesta 401.

  • Línea 34: un interceptor es una función simple ([HttpInterceptorFn]), declarada en [main.ts]: recibe la solicitud y la función [next], que la reenvía (al servidor, o al siguiente interceptor si hay varios), y devuelve el [Observable] de la respuesta;
  • Líneas 37–39: los servicios que necesita el interceptor. [inject()] solo se permite al comienzo de la función, dentro del “contexto de inyección” en el que [Angular] la llama: más adelante, en [catchError], este contexto ya no existe;
  • Línea 40: ¿es pública la solicitud? (vea [api-client.ts]);
  • Líneas 44–58: [next(request)] envía la solicitud; [pipe(catchError(...))] procesa el [Observable] de la respuesta: una respuesta exitosa pasa sin cambios; un error es procesado por la función indicada, que devuelve un nuevo [Observable] (en este caso, de nuevo un error: [throwError]);
  • línea 47: un error que no proviene de una respuesta HTTP es una anomalía del cliente: se transmite tal cual;
  • línea 48: toda respuesta de error se convierte en un [ApiError] (vea [api-error.ts]);
  • Líneas 49–55: un 401 en una solicitud protegida significa que la sesión ha expirado: se olvida al usuario, se borra la caché y se prepara el mensaje para la siguiente pantalla. Sin embargo, la transición de pantalla la gestionan las guardias del enrutador, que se reevalúan cuando cambia la sesión (vea [app.ts]). Aun así se devuelve un error (la pantalla que esperaba la respuesta necesita saber que no llegó), con la clave [ERRORS.SESSION_EXPIRED]: si esa pantalla muestra el error, es el mismo mensaje.

¿Y la cookie del token? El cliente no necesita escribir NADA: en la web, el navegador la almacena y la devuelve; en [Android], [CapacitorHttp] hace pasar las solicitudes por el código nativo, que también la almacena y la reenvía, y la conserva cuando la aplicación se detiene y se vuelve a iniciar (vea el Ejemplo 23). Esta es la principal simplificación respecto del cliente [Flutter], que tenía que leer el encabezado [Set-Cookie] y escribir por sí mismo el encabezado [Cookie].

11.7.3. src/app/api/api-error.ts

// =========================================================================
// src/app/api/api-error.ts - UNA clase para todos los errores de la API
// -------------------------------------------------------------------------
// Todas las respuestas de error del servidor de RdvMedecins tienen la misma forma:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Pero una solicitud también puede fallar de OTRO modo: ninguna respuesta
// (red caída, servidor detenido, dirección incorrecta), o una respuesta que no
// proviene de nuestro servidor (una página de error de un proxy). Convertimos
// todo esto en UNA sola clase, ApiError, que lleva la clave de traducción
// enviada por el servidor (y, si los hay, sus parámetros y el error de
// cada campo).
// =========================================================================

import { HttpErrorResponse } from '@angular/common/http';

// un objeto { name: texto }
export type Texts = Record<string, string>;

// "extends Error": un error de JavaScript de pleno derecho (throw, catch, y
// la propiedad error() de un resource de Angular lo conserva tal cual)
export class ApiError extends Error {
  constructor(
    readonly statusCode: number, // 0: el servidor no respondió
    readonly key: string, // p. ej. 'ERRORS.LOGIN_TAKEN'
    readonly params: Texts = {},
    readonly fields: Texts = {},
  ) {
    super(`${statusCode} ${key}`);
    this.name = 'ApiError';
  }

  // una respuesta de error del cliente HTTP de Angular -> un ApiError
  static fromResponse(response: HttpErrorResponse): ApiError {
    // status 0: sin respuesta (red caída, servidor detenido, dirección incorrecta)
    if (response.status === 0) {
      return new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
    }
    // error: el cuerpo de la respuesta, ya decodificado si es JSON
    const body: unknown = response.error;
    if (isObject(body) && typeof body['key'] === 'string') {
      return new ApiError(response.status, body['key'], texts(body['params']), texts(body['fields']));
    }
    // sin key: el proxy o la red respondieron en su lugar
    return new ApiError(
      response.status,
      response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }
}

function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// un objeto JSON { "name": "ERRORS..." } -> Texts (vacío en caso contrario)
function texts(json: unknown): Texts {
  if (!isObject(json)) return {};
  return Object.fromEntries(Object.entries(json).map(([key, value]) => [key, String(value)]));
}

La del Ejemplo 24: toda solicitud que falla termina con un [ApiError], que contiene la clave de traducción del mensaje, sus parámetros y el error de cada campo.

  • Línea 21: [extends Error]: un error de pleno derecho de [JavaScript]. Esto es importante para los recursos de [Angular] ([resource()], que se verán más adelante): su signal [error()] conserva un [Error] tal cual, pero “envuelve” cualquier otro valor rechazado;
  • líneas 22–27: los parámetros del constructor precedidos por [readonly] se convierten en propiedades del objeto: es una notación abreviada de [TypeScript];
  • líneas 35–37: [status] es 0 cuando no se ha recibido ninguna respuesta (red caída, servidor caído, dirección incorrecta);
  • líneas 39–42: [response.error]: el cuerpo de la respuesta de error, ya decodificado por el cliente HTTP si es JSON. Su tipo es [unknown]: su formato se verifica ([isObject], una clave de tipo texto [key]) antes de usarlo;
  • líneas 44–47: sin clave: respondió el proxy o la red en lugar del servidor;
  • línea 51: [value is Record<string, unknown>]: una función “type guard”: cuando devuelve [true], [TypeScript] sabe, más adelante en el código, que el valor es un objeto;
  • líneas 56–59: un objeto JSON ([params], [fields]) como un objeto de texto.

11.7.4. src/app/api/types.ts

// =========================================================================
// src/app/api/types.ts - los objetos JSON intercambiados con el servidor
// -------------------------------------------------------------------------
// La traducción, a tipos de TypeScript, de la API descrita en el capítulo "El
// servidor, una caja negra". Son solo DESCRIPCIONES:
// desaparecen en tiempo de compilación y no comprueban nada durante la
// ejecución. Permiten que el compilador verifique que el código
// solo usa campos que existen, con el tipo correcto.
// =========================================================================

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 mostrado: "Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string; // la imagen, en formato SVG (texto)
}

// un título, un nombre, un apellido
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// "Mme Alice DURAND"
export function label(i: Identity): string {
  return `${i.title} ${i.firstName} ${i.lastName}`;
}

// un médico o un cliente: GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
  id: number;
  version: number; // bloqueo optimista: debe reenviarse con una actualización
  login?: string; // solo para el ADMIN
}

// una franja horaria
export interface Slot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
}

// una fila de la agenda, con los DERECHOS del usuario con sesión iniciada
export interface ScheduleSlot extends Slot {
  free: boolean;
  patient: Identity | null; // null: libre, u ocupada por otro paciente
  mine: boolean; // la cita del paciente con sesión iniciada
  bookable: boolean;
  appointmentId: number | null; // definido 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)
}

// una cita de GET /api/my-area
export interface Appointment {
  id: number;
  day: string;
  slot: Slot;
  doctor: Person;
}

// GET /api/my-area
export interface MyArea {
  patient: Identity;
  appointments: Appointment[];
}

// GET /api/my-account
export interface MyAccount extends Identity {
  login: string;
  version: number;
}

Los objetos JSON de la API, de tipo [TypeScript] (vea el Ejemplo 24). Son simples DESCRIPCIONES: desaparecen durante la compilación y no realizan ninguna verificación durante la ejecución (el cliente [Flutter], en cambio, verificaba el formato de cada respuesta mediante el filtrado de [Dart] 3). Permiten que el compilador y el editor verifiquen que el código solo usa campos que existen, con el tipo correcto.

  • Línea 11: un tipo de “unión de textos”: un rol solo puede ser una de estas tres cadenas, y el compilador lo verifica ([u.role === 'ADMNI'] sería un error de compilación);
  • Líneas 34–36: una función, ya que una interfaz no puede contener código: “Mme Alice DURAND”;
  • líneas 39–43: un médico o un cliente: una [Identity], más un identificador, una versión (el bloqueo optimista: se devolverá con una modificación) y un login, que solo recibe el ADMIN (de ahí el signo de interrogación: un campo opcional);
  • Líneas 55–61: una entrada de la agenda, que muestra los DERECHOS del usuario con sesión iniciada, calculados por el servidor: [patient] solo se muestra a quienes están autorizados a verlo, [bookable] indica si el usuario puede hacer una reserva; [appointmentId] solo se proporciona a quienes pueden cancelar;
  • Líneas 86–89: la cuenta del paciente con sesión iniciada: su identidad, su login y su versión.

11.7.5. src/app/api/rdvmedecins-api.ts

// =========================================================================
// src/app/api/rdvmedecins-api.ts - un método por ruta de la API
// -------------------------------------------------------------------------
// La "capa de acceso a datos" del cliente: las pantallas llaman a estos
// métodos tipados, sin saber nada de las URL, del cliente HTTP ni del JSON.
// Si la API cambia, solo cambia este archivo.
// Cada método devuelve una Promise; si falla, se rechaza
// con un ApiError (véase http-client.ts).
// Los datos enviados (formularios) son simples objetos Data:
// sus claves son los nombres de los campos esperados por el servidor, y
// los de los errores que devuelve (ApiError.fields).
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { ApiClient } from './api-client';
import { Schedule, Captcha, MyAccount, MyArea, Person, User } from './types';

// /api/doctors o /api/clients: ambos se tratan igual
export type PersonType = 'doctors' | 'clients';

export type Data = Record<string, unknown>;

@Injectable({ providedIn: 'root' })
export class RdvMedecinsApi {
  private readonly client = inject(ApiClient);

  private get<T>(url: string, isPublic = false): Promise<T> {
    return this.client.request<T>('GET', url, undefined, isPublic);
  }

  private post<T>(url: string, body: unknown, isPublic = false): Promise<T> {
    return this.client.request<T>('POST', url, body, isPublic);
  }

  // ==================================================== inicio de sesión (rutas públicas)
  captcha(): Promise<Captcha> {
    return this.get('/captcha', true);
  }

  me(): Promise<User> {
    return this.get('/auth/me', true);
  }

  logIn(login: string, password: string, captchaId: string, captcha: string): Promise<User> {
    return this.post('/auth/login', { login, password, captchaId, captcha }, true);
  }

  async logOut(): Promise<void> {
    await this.post('/auth/logout', {}, true);
  }

  // ==================================================== creación de cuenta (pública)
  async registrationAccess(captchaId: string, captcha: string): Promise<void> {
    await this.post('/register/access', { captchaId, captcha }, true);
  }

  async registrationAccessStatus(): Promise<boolean> {
    const response = await this.get<{ valid?: boolean }>('/register/access', true);
    return response?.valid === true;
  }

  async register(data: Data): Promise<string> {
    const response = await this.post<{ login: string }>('/register', data, true);
    return response.login;
  }

  // ==================================================== agenda y citas
  // doctorId undefined: para un médico con sesión iniciada, SU agenda
  schedule(doctorId: number | undefined, day: string): Promise<Schedule> {
    // URLSearchParams: "day=2026-10-05&doctorId=1", caracteres especiales codificados
    const params = new URLSearchParams({ day });
    if (doctorId !== undefined) params.set('doctorId', String(doctorId));
    return this.get(`/schedule?${params}`);
  }

  async book(day: string, slotId: number, clientId: number | undefined): Promise<void> {
    // clientId: undefined desaparece del JSON enviado
    await this.post('/appointments', { day, slotId, clientId });
  }

  async cancelAppointment(appointmentId: number): Promise<void> {
    await this.client.request('DELETE', `/appointments/${appointmentId}`);
  }

  // ==================================================== médicos y clientes
  list(type: PersonType): Promise<Person[]> {
    return this.get(`/${type}`);
  }

  read(type: PersonType, id: number): Promise<Person> {
    return this.get(`/${type}/${id}`);
  }

  add(type: PersonType, data: Data): Promise<Person> {
    return this.post(`/${type}`, data);
  }

  edit(type: PersonType, id: number, data: Data): Promise<Person> {
    return this.client.request('PUT', `/${type}/${id}`, data);
  }

  async remove(type: PersonType, id: number): Promise<void> {
    await this.client.request('DELETE', `/${type}/${id}`);
  }

  // ==================================================== el área del paciente
  myArea(): Promise<MyArea> {
    return this.get('/my-area');
  }

  myAccount(): Promise<MyAccount> {
    return this.get('/my-account');
  }

  editMyAccount(data: Data): Promise<User> {
    return this.client.request('PUT', '/my-account', data);
  }

  async deleteMyAccount(currentPassword: string): Promise<void> {
    await this.client.request('DELETE', '/my-account', { currentPassword });
  }
}

Un método por ruta de la API: esta es la clase del Ejemplo 24, ampliada.

  • Línea 19: [/api/doctors] y [/api/clients] se tratan de la misma manera: el tipo, una unión de dos cadenas, es también el nombre de la ruta;
  • línea 21: datos de formulario: un objeto cuyas claves son cadenas y cuyos valores pueden ser cualquier cosa;
  • Líneas 23–25: un servicio provisto a toda la aplicación, que recibe el [ApiClient] mediante inyección;
  • líneas 35–50: las rutas públicas del inicio de sesión: un 401 tiene su propio significado específico (“nadie ha iniciado sesión”, “contraseña incorrecta”) y no significa que la sesión haya expirado;
  • líneas 48–50: un método [async] que no devuelve nada ([Promise<void>]): no nos interesa la respuesta del servidor; solo importa que tenga éxito;
  • líneas 57–60: ¿es válido el token de creación de cuenta? [response?.valid]: el operador [?.] devuelve [undefined] si la respuesta está vacía, en lugar de provocar un error;
  • líneas 69–74: los parámetros de la dirección, construidos por [URLSearchParams] (que los codifica). Un médico con sesión iniciada solicita la agenda sin [doctorId]: el servidor devuelve la agenda del propio médico;
  • línea 78: de igual modo, [clientId] se envía solo si se conoce (un paciente reserva para sí mismo): [JSON.stringify] omite las propiedades que corresponden a [undefined];
  • líneas 86–104: las cinco operaciones relativas a médicos o clientes: [/api/${type}];
  • líneas 107–121: el área del paciente. Eliminar la cuenta envía un cuerpo con una solicitud [DELETE] (la contraseña actual): esto lo permiten HTTP y [http.request].

11.8. Idiomas

11.8.1. src/app/i18n/translations.ts

// =========================================================================
// src/app/i18n/translations.ts - los diccionarios, el idioma actual
// -------------------------------------------------------------------------
// Tomado del ejemplo 21. Los diccionarios (public/i18n/fr.json, en.json)
// son los de los clientes Vue.js, Angular, React y Flutter: mismas claves,
// mismas convenciones ({{param}}, plurales _one / _other). El servidor solo
// devuelve CLAVES ("ERRORS.LOGIN_TAKEN"): es aquí donde
// se convierten en texto, en el idioma elegido por el usuario.
//   - t('KEY', { param: value }) : el texto del idioma actual;
//   - changeLanguage('fr')       : carga el otro diccionario, y
//                                  recuerda la elección en el dispositivo.
// El idioma y el diccionario son SEÑALES: t() las lee, por lo que toda
// plantilla que muestre t('...') se actualiza cuando cambia el idioma.
// =========================================================================

import { Injectable, signal } from '@angular/core';
import { Preferences } from '@capacitor/preferences';

export const languages = ['fr', 'en'] as const;
export type Language = (typeof languages)[number]; // 'fr' | 'en'

// un diccionario: textos, almacenados en secciones anidadas
interface Dictionary {
  [key: string]: string | Dictionary;
}

const LANGUAGE_KEY = 'rdvmedecins.language';

@Injectable({ providedIn: 'root' })
export class Translations {
  private readonly _language = signal<Language>('en');
  private readonly dictionary = signal<Dictionary>({});
  readonly language = this._language.asReadonly();

  // el idioma inicial: el recordado en el dispositivo; si no, el del
  // teléfono (si se conoce); si no, inglés. Se llama una sola vez,
  // antes de mostrar la primera pantalla (provideAppInitializer, main.ts)
  async start(): Promise<void> {
    // Preferences: un almacenamiento clave / valor en el dispositivo (el
    // localStorage del navegador en la web)
    const { value: stored } = await Preferences.get({ key: LANGUAGE_KEY });
    const device = navigator.language.slice(0, 2); // "en-US" -> "en"
    await this.changeLanguage(stored ?? device);
  }

  async changeLanguage(requested: string): Promise<void> {
    const language: Language = languages.find((l) => l === requested) ?? 'en';
    // fetch: los archivos de la carpeta public/ se incluyen con la aplicación
    // (también en Android: una dirección RELATIVA no pasa por CapacitorHttp)
    const response = await fetch(`i18n/${language}.json`);
    this.dictionary.set((await response.json()) as Dictionary);
    this._language.set(language);
    await Preferences.set({ key: LANGUAGE_KEY, value: language });
  }

  // "AREA.HELLO" -> dictionary['AREA']['HELLO']; undefined si falta
  private find(key: string): string | undefined {
    let node: string | Dictionary | undefined = this.dictionary();
    for (const part of key.split('.')) {
      node = typeof node === 'object' ? node[part] : undefined;
    }
    return typeof node === 'string' ? node : undefined;
  }

  // una función flecha: puede pasarse tal cual a los componentes
  // (readonly t = inject(Translations).t), conserva su "this"
  readonly t = (key: string, params: Record<string, unknown> = {}): string => {
    let text: string | undefined;
    const count = params['count'];
    if (typeof count === 'number') {
      // Intl.PluralRules: la forma del plural, según las reglas del
      // idioma ('zero', 'one', 'other'...); 0 es 'one' en francés
      const form = new Intl.PluralRules(this._language()).select(count);
      text = this.find(`${key}_${count === 0 ? 'zero' : form}`) ?? this.find(`${key}_${form}`);
    }
    text ??= this.find(key);
    // una clave desconocida se muestra tal cual: lo que falta se ve de inmediato
    if (text === undefined) return key;
    // {{name}} -> el valor del parámetro name
    return text.replace(/\{\{(\w+)\}\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
  };
}

La clase [Translations] del Ejemplo 21, ahora un servicio provisto a toda la aplicación y simplificado: los diccionarios siguen teniendo el mismo nombre ([public/i18n/fr.json]).

  • Línea 19: [as const]: el arreglo es fijo y su tipo es exactamente [readonly ['fr', 'en']]; la línea 20 infiere el tipo [Language], ['fr' | 'en']: agregar un idioma al arreglo lo agrega al tipo;
  • líneas 23–25: un diccionario: textos organizados en secciones anidadas (un tipo recursivo);
  • líneas 31–33: el idioma y el diccionario son SIGNALS. Todo lo que lee [t(...)] (una plantilla, un signal calculado, un efecto) también lee estos signals y, por lo tanto, se actualiza cuando cambia el idioma: es el [notifyListeners()] de [ChangeNotifier] de [Flutter], sin escribir nada. [asReadonly()]: el resto de la aplicación puede leer el idioma, pero solo este servicio puede cambiarlo;
  • líneas 38–44: el idioma predeterminado: el seleccionado en una sesión anterior, de lo contrario el idioma del teléfono si la aplicación lo conoce, de lo contrario inglés. [Preferences] (el complemento de [Capacitor], vea el Ejemplo 20) almacena pares clave-valor en el dispositivo; en un navegador, usa [localStorage]. [navigator.language]: el idioma del sistema (“en-US”);
  • Líneas 46–54: cambiar el idioma. El diccionario se lee con [fetch] de los archivos incluidos con la aplicación (la carpeta [public/], copiada tal cual por [ng build]). En [Android], una URL RELATIVA ([i18n/fr.json]) no es redirigida por [CapacitorHttp]: la sirve la propia aplicación. El idioma desconocido pasa a ser inglés;
  • líneas 57–63: “AREA.HELLO” → [dictionary['AREA']['HELLO']], avanzando sección por sección;
  • líneas 67–81: la traducción de una clave, incluidos los plurales ([_zero], [_one], [_other]) y los parámetros ([{{name}}]), siguiendo las convenciones de [i18next], que son las mismas que se usan en los diccionarios de los otros clientes. [Intl.PluralRules] conoce las reglas de plural de cada idioma (en francés, 0 y 1 son singular). [t] es una función flecha, no un método: conserva su [this] cuando se copia en un componente ([readonly t = inject(Translations).t]), lo que hacen todas las pantallas.

11.8.2. Diccionarios

Los diccionarios son los del cliente [Flutter], sin cambios (a su vez tomados del cliente [React], complementados con algunas claves propias de la aplicación móvil: el menú “Mi cuenta”, “Elija el día”, etc.). El comienzo del diccionario en francés, [public/i18n/fr.json]:

{
  "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",
    "MENU_ACCOUNT": "Mon compte",
    "CONNECTED_AS": "Connecté : {{name}}",
    "RETRY": "Réessayer"
  },
  "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",

Un archivo por idioma, con las mismas claves en cada uno; un grupo de claves por pantalla; las claves [ERRORS.*] son las que devuelve el servidor.

11.9. El estado compartido

Tres servicios de signals, provistos a toda la aplicación ([providedIn: 'root']), como el del Ejemplo 20.

11.9.1. src/app/state/session.ts

// =========================================================================
// src/app/state/session.ts - ¿QUIÉN ha iniciado sesión?
// -------------------------------------------------------------------------
// El usuario con sesión iniciada (o null), en un SERVICIO con señales proporcionado a
// toda la aplicación (providedIn: 'root', véase el ejemplo 20): legible por las
// pantallas Y por las guardias del enrutador, que se reevalúan cuando cambia
// (véase app.ts).
//
// El token JWT en sí NO está aquí: está en una cookie (gestionada por el
// navegador en la web, por el código nativo de Android en el teléfono). La
// sesión solo conserva la DESCRIPCIÓN del usuario ({ login, name, role }).
//
// Cuando la aplicación se inicia, la sesión está vacía: check() pregunta
// al servidor, una sola vez, quién ha iniciado sesión (GET /api/auth/me).
// =========================================================================

import { inject, Injectable, signal } from '@angular/core';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { User } from '../api/types';

@Injectable({ providedIn: 'root' })
export class Session {
  private readonly api = inject(RdvMedecinsApi);
  private readonly _user = signal<User | null>(null);
  // la versión de "solo lectura" de la señal, para el resto de la aplicación
  readonly user = this._user.asReadonly();
  // true tras un cierre de sesión DESEADO (botón, eliminación de la cuenta); false
  // tras una sesión expirada. Las guardias lo tienen en cuenta (véase app.routes.ts)
  private _voluntaryExit = false;
  // ¿ya se le ha hecho al servidor la pregunta "¿quién ha iniciado sesión?"?
  private checking?: Promise<void>;

  get voluntaryExit(): boolean {
    return this._voluntaryExit;
  }

  // solo consulta al servidor la primera vez (la Promise se conserva)
  check(): Promise<void> {
    this.checking ??= this.api.me().then(
      (u) => this.change(u),
      () => this.change(null), // 401: nadie; o servidor inaccesible
    );
    return this.checking;
  }

  async logIn(login: string, password: string, captchaId: string, captcha: string): Promise<void> {
    this.change(await this.api.logIn(login, password, captchaId, captcha));
  }

  // el usuario ha cambiado de nombre o de login (PUT /api/my-account)
  update(u: User): void {
    this.change(u);
  }

  async logOut(): Promise<void> {
    try {
      await this.api.logOut();
    } finally {
      this.forget(true);
    }
  }

  // sin preguntar nada al servidor: sesión expirada, cuenta eliminada
  forget(voluntary = false): void {
    this.change(null, voluntary);
  }

  // la señal cambia: todo lo que la lee (layout, guardias...) es notificado
  private change(u: User | null, voluntary = false): void {
    this._voluntaryExit = voluntary;
    this._user.set(u);
  }
}

// lo que se deduce del usuario (null: nadie ha iniciado sesión)
export const isAdmin = (u: User | null): boolean => u?.role === 'ADMIN';
export const isPatient = (u: User | null): boolean => u?.role === 'USER';
// ADMIN y DOCTOR: reservan y cancelan las citas de cualquier paciente
export const isManager = (u: User | null): boolean => u?.role === 'ADMIN' || u?.role === 'DOCTOR';
// la página de inicio de cada rol, justo después de iniciar sesión
export const homePage = (u: User | null): string => (isPatient(u) ? '/my-area' : '/schedule');

¿Quién ha iniciado sesión? La sesión almacena la DESCRIPCIÓN del usuario (login, nombre, rol), no el token, que permanece en la cookie del usuario.

  • Líneas 24–26: el usuario, en un signal privado y modificable ([_user]), y su versión de solo lectura, para el resto de la aplicación. El diseño (que muestra el nombre del usuario), [app.ts] (que borra la caché y reevalúa las guardias) y las pantallas leen esta información;
  • líneas 38–44: la pregunta “¿Quién ha iniciado sesión?”, enviada al servidor ([GET /api/auth/me]) se hace una SOLA vez, al iniciar: [??=] asigna [Promise] solo si [checking] es [undefined]. Las llamadas posteriores devuelven la misma [Promise], que ya está resuelta: la guardia del enrutador puede llamar a [check()] antes de cada navegación sin ningún costo. Al iniciar, si la cookie contiene un token que sigue siendo válido, el usuario permanece con la sesión iniciada. [then(success, failure)]: un 401 (nadie ha iniciado sesión) o un servidor inaccesible dan ambos una sesión vacía;
  • líneas 46–48: el inicio de sesión: si el servidor lo rechaza, [api.logIn] rechaza su [Promise] con un [ApiError], [await] lo vuelve a lanzar, y [change] no se llama;
  • líneas 55–61: cierre de sesión; el usuario se olvida aunque el servidor no responda ([finally]);
  • líneas 69–72: todos los cambios pasan por aquí. [_voluntaryExit] distingue entre un cierre de sesión intencional y una sesión expirada (véase [app.routes.ts]); se asigna ANTES de cambiar la señal, que es la que leen los guardias;
  • líneas 76–81: lo que se deduce del usuario, en términos de funciones (el cliente [Flutter] utilizaba una extensión de [Dart]). [u?.role]: [undefined] si no hay nadie con sesión iniciada ([null]), sin necesidad de una prueba previa.

11.9.2. src/app/state/messages.ts

// =========================================================================
// src/app/state/messages.ts - los mensajes mostrados al usuario
// -------------------------------------------------------------------------
// Misma presentación que los demás clientes de RdvMedecins:
//   - un ÉXITO se muestra en la parte SUPERIOR de la pantalla (banner verde);
//   - un ERROR en la parte INFERIOR (banner rosa), siempre visible.
// Un mensaje es una CLAVE de traducción (+ sus parámetros): por lo tanto
// se traduce de nuevo por sí solo si el usuario cambia de idioma.
//
// Los mensajes "flash": una acción que termina con un cambio de
// pantalla (reservar, agregar un médico...) deja su mensaje con
// flash(); se mostrará en la pantalla SIGUIENTE, y luego desaparecerá en la
// navegación posterior. Es app.ts quien llama a newPage() al final de
// cada navegación.
// =========================================================================

import { effect, inject, Injectable, Resource, signal, untracked } from '@angular/core';
import { ApiError, Texts } from '../api/api-error';

export interface Message {
  key: string;
  params: Texts;
}

@Injectable({ providedIn: 'root' })
export class Messages {
  readonly success = signal<Message | null>(null);
  readonly error = signal<Message | null>(null);
  // los mensajes por mostrar en la pantalla siguiente
  private pendingSuccess: Message | null = null;
  private pendingError: Message | null = null;

  showSuccess(key: string, params: Texts = {}): void {
    this.success.set({ key, params });
    this.error.set(null);
  }

  showError(key: string, params: Texts = {}): void {
    this.error.set({ key, params });
    this.success.set(null);
  }

  // un ApiError -> el mensaje de la pantalla; cualquier otro error es una
  // anomalía del cliente, que se deja pasar
  showApiError(e: unknown): void {
    if (!(e instanceof ApiError)) throw e;
    this.showError(e.key, e.params);
  }

  clear(): void {
    this.success.set(null);
    this.error.set(null);
  }

  // para la pantalla SIGUIENTE
  flash({ success = true, key, params = {} }: { success?: boolean; key: string; params?: Texts }): void {
    if (success) {
      this.pendingSuccess = { key, params };
    } else {
      this.pendingError = { key, params };
    }
  }

  // una pantalla nueva: los mensajes de la anterior desaparecen, los mensajes
  // flash aparecen
  newPage(): void {
    this.success.set(this.pendingSuccess);
    this.error.set(this.pendingError);
    this.pendingSuccess = null;
    this.pendingError = null;
  }
}

// para llamar en el constructor de una pantalla: el fallo al leer estos
// recursos (resource de Angular) muestra su mensaje en la parte inferior de la pantalla
export function reportErrors(...resources: Resource<unknown>[]): void {
  const messages = inject(Messages);
  for (const resource of resources) {
    // un efecto: una función que se vuelve a ejecutar cada vez que cambia una señal que
    // ha leído (aquí, el error del resource)
    effect(() => {
      const error = resource.error();
      // untracked: lo que sigue no debe convertirse en una dependencia del efecto
      if (error) untracked(() => messages.showApiError(error));
    });
  }
}

Mensajes de la aplicación: un mensaje de éxito en la parte superior de la pantalla y un mensaje de error en la parte inferior (véase [layout.html]).

  • Líneas 20–23: un mensaje consta de un código de traducción (KEY) y sus parámetros. Se traduce solo cuando se muestra; al cambiar el idioma, los mensajes mostrados se vuelven a traducir;
  • Líneas 27–28: los mensajes de éxito y de error mostrados: dos señales leídas por el diseño (layout);
  • líneas 45–48: un [ApiError] se convierte en el mensaje de error de la pantalla. Cualquier otra excepción es un problema del lado del cliente: se vuelve a lanzar para que aparezca en la consola durante el desarrollo, en lugar de ocultarse;
  • líneas 56–62: un mensaje para la SIGUIENTE pantalla: una acción que termina con un cambio de pantalla (una reserva, una adición, etc.) coloca aquí su mensaje. El parámetro es un objeto «desempaquetado»: [flash({ success: false, key: '...' })], con valores predeterminados; son los parámetros con nombre de [Dart];
  • líneas 66–71: se invoca cada vez que cambia la dirección (véase [app.ts]): los mensajes de la pantalla anterior desaparecen y aparecen los mensajes flash;
  • líneas 76–87: una función que se debe llamar en el constructor de una pantalla: si falla la lectura de sus recursos ([resource()], véase [schedule.ts]), su mensaje se muestra en la parte inferior de la pantalla. Para cada recurso, un efecto lee su señal [error()]: se vuelve a ejecutar con cada nuevo error. Un efecto solo se puede crear dentro de un contexto de inyección, como [inject()]: de ahí la exigencia de llamar a la función dentro de un constructor (o al inicializar un campo).

11.9.3. src/app/state/cache.ts

// =========================================================================
// src/app/state/cache.ts - los datos ya leídos del servidor
// -------------------------------------------------------------------------
// La lista de médicos casi nunca cambia: no hace falta leerla de nuevo en
// cada visita a la agenda. El caché conserva la Promise de cada lectura,
// bajo una CLAVE ('doctors', 'schedule/1/2026-10-05'...):
//
//     cache.read('doctors', () => api.list('doctors'))
//
// devuelve la Promise ya conservada, o inicia la lectura y la conserva.
// Tras un cambio, las claves afectadas se INVALIDAN (se
// leerán de nuevo en la siguiente solicitud): cache.invalidate('schedule').
// Una lectura fallida no se conserva: la siguiente volverá a intentarlo.
// Cada invalidación incrementa la señal version: una pantalla todavía
// viva (incluso oculta bajo otra en la pila de Ionic) puede así
// leer de nuevo sus datos (véase reloadAfterInvalidation, más abajo).
// Esto es, en pocas líneas, lo que hace la biblioteca TanStack Query del
// cliente React.
// =========================================================================

import { effect, inject, Injectable, signal, untracked, WritableResource } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class Cache {
  private readonly promises = new Map<string, Promise<unknown>>();
  private readonly _version = signal(0);
  readonly version = this._version.asReadonly();

  read<T>(key: string, load: () => Promise<T>): Promise<T> {
    let promise = this.promises.get(key) as Promise<T> | undefined;
    if (promise === undefined) {
      promise = load();
      this.promises.set(key, promise);
      // si falla, esta Promise se olvida (la siguiente solicitud volverá a intentarlo)
      promise.catch(() => this.promises.delete(key));
    }
    return promise;
  }

  // olvida todas las claves que empiezan con prefix, y notifica a las pantallas
  invalidate(prefix: string): void {
    for (const key of [...this.promises.keys()]) {
      if (key.startsWith(prefix)) this.promises.delete(key);
    }
    this._version.update((v) => v + 1);
  }

  // cambio de usuario: se olvida todo, SIN notificar (las pantallas del
  // usuario anterior están a punto de desaparecer, no deben leer nada)
  clear(): void {
    this.promises.clear();
  }
}

// para llamar en el constructor de una pantalla: sus resources se leen de nuevo
// (reload) después de cada invalidación del caché. reload() conserva el valor
// actual durante la nueva lectura: la pantalla no "parpadea"
export function reloadAfterInvalidation(...resources: WritableResource<unknown>[]): void {
  const cache = inject(Cache);
  const start = cache.version();
  effect(() => {
    // el efecto se ejecuta una primera vez al crearse: esperamos una
    // invalidación REAL
    if (cache.version() === start) return;
    untracked(() => resources.forEach((r) => r.reload()));
  });
}

Datos ya leídos del servidor: el equivalente, en pocas líneas, de [TanStack Query] en el cliente [React], y de [Cache] en el cliente [Flutter].

  • Línea 25: la caché almacena [Promise], no valores reales: dos pantallas que solicitan los mismos datos mientras estos están en tránsito reciben la MISMA [Promise], y se envía una sola solicitud;
  • Líneas 29–38: un método genérico: [read<Person[]>(...)] devuelve una [Promise<Person[]>] (el tipo [T] se infiere de la función [load]). Una lectura fallida se ignora ([catch]): la siguiente solicitud lo volverá a intentar;
  • líneas 41–46: después de una modificación, se descartan las claves afectadas y se incrementa la señal [version]: las pantallas que leen esta señal reciben la notificación;
  • líneas 50–52: cuando cambia el usuario, todo se borra sin notificar a nadie: las pantallas del usuario anterior desaparecerán; no tienen nada que volver a leer;
  • líneas 58–67: una función que se debe llamar en el constructor de una pantalla: sus recursos se vuelven a leer después de cada invalidación de la caché. El efecto lee [cache.version()]: se vuelve a ejecutar en cada invalidación y vuelve a leer los recursos ([reload()]). Las pantallas de [Ionic] permanecen activas, ocultas debajo de la pantalla mostrada (la pila del botón Atrás): después de un cambio, ya están actualizadas cuando se vuelve a ellas. [reload()] conserva el valor actual durante la nueva lectura: la pantalla no «parpadea».

11.10. Formato

11.10.1. src/app/formatting.ts

// =========================================================================
// src/app/formatting.ts - la visualización de horas y días
// -------------------------------------------------------------------------
// El servidor envía datos BRUTOS (startHour: 8, startMinute: 0; day:
// "2026-10-05"); el formato, que depende del idioma, es asunto
// del cliente (véase el ejemplo 09). Aquí usamos la API Intl de JavaScript,
// que conoce las reglas de todos los idiomas.
// =========================================================================

import { Slot } from './api/types';

const two = (n: number): string => n.toString().padStart(2, '0');

// "8:05" en lugar de "8:5"
export const time = (h: number, m: number): string => `${h}:${two(m)}`;

// "8:00 - 8:20"
export const timeRange = (s: Slot): string => `${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}`;

// una fecha -> "yyyy-MM-dd" (el formato de la API), en la zona horaria del dispositivo
export const toDay = (d: Date): string => `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;

export const today = (): string => toDay(new Date());

// "2026-10-05" -> 5 de octubre de 2026 a las 0:00, hora local (new Date("2026-10-05")
// daría las 0:00 en hora universal: la noche anterior, en otro continente)
export function toDate(day: string): Date {
  const [y, m, d] = day.split('-').map(Number);
  return new Date(y, m - 1, d);
}

// true si day es una fecha que existe, en el formato yyyy-MM-dd
export function isValidDate(day: string): boolean {
  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return false;
  return toDay(toDate(day)) === day; // 2026-02-30 -> 2026-03-02: rechazada
}

// "lundi 5 octobre 2026" / "Monday, October 5, 2026"
export function longDay(day: string, language: string): string {
  return new Intl.DateTimeFormat(language, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' }).format(
    toDate(day),
  );
}

Formato de los datos sin procesar del servidor (véase el ejemplo 09):

  • línea 21: una fecha en el formato de la API («2026-10-05»), en la zona horaria del dispositivo. [getMonth()] cuenta los meses a partir de 0;
  • líneas 27–30: lo inverso: «2026-10-05» → 5 de octubre a las 12:00 a. m., hora local. [new Date('2026-10-05')] indicaría la medianoche en el Tiempo Universal Coordinado (UTC), es decir, al oeste de Greenwich, la noche anterior;
  • líneas 33–36: ¿es válida la fecha de la dirección? [new Date(2026, 1, 30)] da como resultado el 2 de marzo: se verifica que se devuelva la misma cadena;
  • líneas 39–43: «lunes, 5 de octubre de 2026», según el idioma: [Intl.DateTimeFormat], la variante de formato de [JavaScript], admite todos los idiomas. El cliente [Flutter] requería el paquete [intl] para esto.

11.11. El enrutador

11.11.1. src/app/app.routes.ts

// =========================================================================
// src/app/app.routes.ts - las pantallas de la aplicación y sus derechos de acceso
// -------------------------------------------------------------------------
// Las MISMAS direcciones que los demás clientes (/login, /schedule, /doctors,
// /my-area...). En la web, se muestran en la barra de direcciones;
// en el teléfono, permanecen invisibles, pero organizan la aplicación
// igualmente (y la pila de pantallas del botón Atrás).
//
// Las GUARDIAS: la función guardia (una CanActivateFn) se llama antes de
// CADA navegación hacia cada pantalla. Es asíncrona: la primera
// vez (inicio de la aplicación, F5 en la web), espera la respuesta del servidor
// a la pregunta "¿quién ha iniciado sesión?" (session.check()). Luego
// verifica los derechos de la pantalla solicitada (accessOf), y redirige si
// es necesario. runGuardsAndResolvers: 'always': las guardias también se
// reevalúan cuando "navegamos de nuevo" a la dirección actual, lo que
// hace app.ts cuando la sesión cambia (inicio, cierre, expiración).
// RECORDATORIO: estas verificaciones son solo una COMODIDAD (no mostrar una pantalla
// inútil). La protección de los datos la asegura el servidor, que
// verifica de nuevo el token y el rol en CADA solicitud.
// =========================================================================

import { inject } from '@angular/core';
import { CanActivateFn, CanMatchFn, Router, Routes } from '@angular/router';
import { RdvMedecinsApi, PersonType } from './api/rdvmedecins-api';
import { Role } from './api/types';
import { Messages } from './state/messages';
import { homePage, Session } from './state/session';
import { keys } from './pages/persons-config';

// los derechos de acceso de una pantalla: pública (sin iniciar sesión), o reservada a
// ciertos roles (sin roles: todos los roles con sesión iniciada)
interface Access {
  public: boolean;
  roles?: Role[];
}

export function accessOf(path: string): Access {
  if (path === '/login' || path === '/register') return { public: true };
  if (path.startsWith('/doctors') || path.startsWith('/clients')) return { public: false, roles: ['ADMIN'] };
  if (path === '/my-area' || path === '/my-account') return { public: false, roles: ['USER'] };
  if (path === '/schedule' || path === '/forbidden' || path === '/') return { public: false };
  return { public: true }; // dirección desconocida: la página 404, para todos
}

// solo una ruta INTERNA ("/doctors"): nunca "//other-site.com"
export function internalPath(r: string | undefined): string | undefined {
  return r !== undefined && r.startsWith('/') && !r.startsWith('//') ? r : undefined;
}

// "3" -> 3; "", "abc", "-2", ausente (undefined) -> undefined
export function positiveInteger(value: string | undefined): number | undefined {
  if (value === undefined || !/^\d+$/.test(value)) return undefined;
  const n = Number(value);
  return n > 0 ? n : undefined;
}

// la guardia de TODAS las pantallas
export const guard: CanActivateFn = async (_route, state) => {
  // inject() primero: tras un await, ya no estamos en un contexto de inyección
  const session = inject(Session);
  const router = inject(Router);
  await session.check();
  const user = session.user();
  // state.url: la dirección solicitada, con sus parámetros ("/schedule?doctorId=1...")
  const url = router.parseUrl(state.url);
  const path = state.url.split(/[?#]/)[0];
  const access = accessOf(path);
  if (access.public) {
    // sesión iniciada: la pantalla de inicio de sesión ya no tiene sentido. Es AQUÍ donde
    // se sale de ella, justo después de iniciar sesión: la sesión ha cambiado, las guardias
    // se reevalúan. Se va a la pantalla solicitada antes de iniciar sesión
    // (?redirect=...), o si no a la página de inicio del rol
    if (path === '/login' && user !== null) {
      return router.parseUrl(internalPath(url.queryParams['redirect']) ?? homePage(user));
    }
    return true;
  }
  if (user === null) {
    // cierre de sesión deseado: la pantalla de inicio de sesión, simplemente
    if (session.voluntaryExit) return router.parseUrl('/login');
    // sesión expirada, dirección abierta sin haber iniciado sesión: se recuerda la pantalla
    // solicitada, para volver a ella tras iniciar sesión
    return router.createUrlTree(['/login'], { queryParams: { redirect: state.url } });
  }
  if (path === '/') return router.parseUrl(homePage(user));
  if (access.roles !== undefined && !access.roles.includes(user.role)) return router.parseUrl('/forbidden');
  // true: la navegación continúa; un UrlTree: se redirige
  return true;
};

// una guardia ESPECÍFICA de /register: sin un pase (captcha resuelto en
// la pantalla de inicio de sesión), de vuelta a la pantalla de inicio de sesión
const registrationGuard: CanActivateFn = async () => {
  const api = inject(RdvMedecinsApi);
  const messages = inject(Messages);
  const router = inject(Router);
  const valid = await api.registrationAccessStatus().catch(() => false);
  if (valid) return true;
  messages.flash({ success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
  return router.parseUrl('/login');
};

// /doctors/abc/edit: esta ruta no "coincide" (canMatch);
// el enrutador prueba las siguientes, hasta la página 404 (**)
const validId: CanMatchFn = (_route, segments) => positiveInteger(segments[1]?.path) !== undefined;

// las tres pantallas de gestión de los médicos O de los clientes (ADMIN);
// data: valores fijos, entregados a los inputs del componente (type)
function personRoutes(type: PersonType): Routes {
  const c = keys(type);
  const list = () => import('./pages/persons').then((m) => m.PersonsPage);
  const form = () => import('./pages/person-form').then((m) => m.PersonFormPage);
  return [
    { path: type, title: c.title, data: { type }, loadComponent: list },
    { path: `${type}/add`, title: c.add, data: { type }, loadComponent: form },
    {
      path: `${type}/:id/edit`,
      title: c.edit,
      data: { type },
      canMatch: [validId],
      loadComponent: form,
    },
  ];
}

// las pantallas, sin sus guardias; title: una CLAVE de traducción (véase
// components/page-title.ts); loadComponent: el código de la pantalla solo se
// carga en su primera visita (un archivo JavaScript aparte)
const screens: Routes = [
  // "/": siempre redirigida por la guardia (página de inicio del rol, o inicio de sesión)
  { path: '', pathMatch: 'full', children: [] },
  {
    path: 'login',
    title: 'LOGIN.TITLE',
    loadComponent: () => import('./pages/login').then((m) => m.LoginPage),
  },
  {
    path: 'schedule',
    title: 'SCHEDULE.PAGE_TITLE',
    loadComponent: () => import('./pages/schedule').then((m) => m.SchedulePage),
  },
  ...personRoutes('doctors'),
  ...personRoutes('clients'),
  {
    path: 'register',
    title: 'REGISTRATION.TITLE',
    canActivate: [registrationGuard],
    loadComponent: () => import('./pages/register').then((m) => m.RegisterPage),
  },
  {
    path: 'my-area',
    title: 'AREA.TITLE',
    loadComponent: () => import('./pages/patient-area').then((m) => m.PatientAreaPage),
  },
  {
    path: 'my-account',
    title: 'MY_ACCOUNT.TITLE',
    loadComponent: () => import('./pages/my-account').then((m) => m.MyAccountPage),
  },
  {
    path: 'forbidden',
    title: 'ERROR_PAGE.TITLE',
    data: { code: 403 },
    loadComponent: () => import('./pages/error-page').then((m) => m.ErrorPage),
  },
  // una dirección que ninguna ruta describe: la página 404
  {
    path: '**',
    title: 'ERROR_PAGE.TITLE',
    data: { code: 404 },
    loadComponent: () => import('./pages/error-page').then((m) => m.ErrorPage),
  },
];

// cada pantalla recibe la guardia común (antes de sus propias guardias)
export const routes: Routes = screens.map((r) => ({
  ...r,
  canActivate: [guard, ...(r.canActivate ?? [])],
  runGuardsAndResolvers: 'always',
}));

Las pantallas de la aplicación, sus direcciones y sus derechos de acceso (véanse los ejemplos 17 y 18).

  • líneas 32–35: los derechos de acceso de una pantalla: pública, o restringida a ciertos roles (si falta [roles] : todos los roles);
  • líneas 37–43: los permisos de cada dirección, en UN solo lugar;
  • líneas 46–48: la dirección [?redirect=] solo se sigue si es una ruta INTERNA: en la web, una dirección [/login?redirect=//pirate-site.com] enviada por correo electrónico no debe llevar al usuario a ningún otro sitio después de iniciar sesión;
  • líneas 51–55: los parámetros de una URL son cadenas de texto que cualquiera puede introducir (en la web): «abc» o «-2» se convierten en [undefined];
  • líneas 58–89: EL guardia, ejecutado antes de navegar a cualquier pantalla (véanse las líneas 176–180):
  • línea 62: la primera vez, el sistema espera la respuesta del servidor a la pregunta «¿quién está conectado?»; después, esta llamada no tiene costo. Un guardia puede ser asíncrono ([async]): el enrutador espera su respuesta;
  • líneas 65–67: [state.url]: la dirección solicitada, con sus parámetros; [router.parseUrl]: el desglose (su ruta, sus parámetros [queryParams]);
  • líneas 68–77: una pantalla pública es accesible para todos; sin embargo, un usuario con sesión iniciada no tiene nada que hacer en la pantalla de inicio de sesión: se le envía a la pantalla que solicitó antes de iniciar sesión, o a la pantalla de inicio de su rol. Así es como la aplicación sale de la pantalla de inicio de sesión tras un inicio de sesión exitoso: la propia pantalla de inicio de sesión no necesita navegar. Un guardia que devuelve un [UrlTree] (una dirección analizada) REDIRIGE la navegación;
  • líneas 78–84: nadie ha iniciado sesión: se pasa a la pantalla de inicio de sesión. Después de que una sesión expira, o si se abrió directamente una dirección protegida (en la web), se conserva la pantalla solicitada ([?redirect=]) para volver a ella tras iniciar sesión; tras un cierre de sesión intencional, no se conserva. [createUrlTree] construye la dirección codificando el parámetro;
  • líneas 85–88: [/] lleva a la página de inicio del rol; si el rol es insuficiente, lleva a una página 403; de lo contrario, [true]: la navegación continúa;
  • líneas 93–101: un guardia ESPECÍFICO de una ruta: la creación de una cuenta requiere un pase, que el servidor emite una vez que se ha introducido el CAPTCHA ([POST /api/register/access], véase la pantalla de inicio de sesión). Sin él, se devuelve al usuario a la pantalla de inicio de sesión con un mensaje;
  • línea 105: un guardia [CanMatchFn] no verifica si se tiene DERECHO a pasar a una pantalla, sino si la ruta COINCIDE con la dirección: [/doctors/abc/edit] no coincide con la ruta [doctors/:id/edit]; el enrutador prueba las rutas siguientes hasta llegar a la página 404;
  • líneas 109–124: una función que genera las tres rutas de los médicos O de los clientes: [/doctors], [/doctors/add], [/doctors/:id/edit]. [:id]: un parámetro de ruta, pasado a la entrada [id] del componente; [data: { type }]: un valor fijo, pasado a su entrada [type]. [title]: el título de la pantalla (una clave de traducción; véase [page-title.ts]);
  • líneas 111–112: [loadComponent]: el código de una pantalla se carga solo en la primera visita. [import()] carga un módulo bajo demanda; [ng build] almacena por tanto cada pantalla en un archivo [JavaScript] distinto, y la aplicación se inicia más rápido;
  • línea 131: [/]: una ruta sin pantalla ([children: []]), siempre redirigida por el guardia;
  • líneas 132–136: [/login?login=jbernard] (después de crear una cuenta) rellena previamente el campo de inicio de sesión: el parámetro [login] se asigna al campo de entrada del mismo nombre en la pantalla de inicio de sesión;
  • líneas 137–141: de forma similar, los tres parámetros de la agenda ([doctorId], [day], [book]) se asignan a los campos de la pantalla: toda la disposición de la pantalla está contenida en la dirección (véase [schedule.ts]);
  • líneas 160–172: la página 403 y, para cualquier dirección no descrita por ninguna ruta (la ruta «comodín», dos asteriscos), la página 404: la misma pantalla, con un código distinto ([data]);
  • líneas 176–180: cada ruta recibe el guardia común antes de sus propios guardias. [runGuardsAndResolvers: 'always']: los guardias se ejecutan en cada navegación, incluso hacia la dirección actual (de forma predeterminada, solo cuando cambia la ruta o sus parámetros). Esto es lo que permite a [app.ts] volver a evaluarlos cuando cambia la sesión.

Estas verificaciones son solo una COMODIDAD: evitan que se muestre una pantalla innecesaria. La protección de los datos la garantiza el servidor, que vuelve a verificar el token y el rol en cada solicitud.

11.12. Los componentes

11.12.1. src/app/components/layout.ts

// =========================================================================
// src/app/components/layout.ts - el LAYOUT común a todas las pantallas
// -------------------------------------------------------------------------
// El único componente del componente raíz (véase app.ts); rodea
// el lugar de las pantallas (<ion-router-outlet>):
//   - la barra superior: título, idioma (FR / EN), cierre de sesión;
//   - el menú lateral ("drawer", <ion-menu>), abierto con el botón ☰: las
//     pantallas permitidas para el rol del usuario. "Médicos" y "Pacientes"
//     solo aparecen para el ADMIN: una mera comodidad de visualización, siendo la
//     protección real la del servidor;
//   - un mensaje de éxito en la parte SUPERIOR;
//   - la pantalla actual (<ion-router-outlet>);
//   - la zona de errores en la parte INFERIOR.
// En una pantalla grande (web, tableta), el menú se muestra permanentemente
// a la izquierda: de eso se encarga <ion-split-pane>.
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { NavigationEnd, Router, RouterLink } from '@angular/router';
import {
  IonButton, IonButtons, IonChip, IonContent, IonFooter, IonHeader, IonIcon, IonItem, IonLabel, IonList,
  IonMenu, IonMenuButton, IonMenuToggle, IonPopover, IonRouterLink, IonRouterOutlet, IonSplitPane, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import {
  calendar, checkmarkCircle, close, alertCircle, home, logOutOutline, medkit, people, personCircle,
} from 'ionicons/icons';
import { filter, map } from 'rxjs';
import { User } from '../api/types';
import { Messages } from '../state/messages';
import { isAdmin, isPatient, Session } from '../state/session';
import { Language, languages, Translations } from '../i18n/translations';

// una entrada del menú: ruta, clave de la etiqueta, ícono
interface MenuEntry {
  path: string;
  key: string;
  icon: string;
}

export function menuEntries(u: User | null): MenuEntry[] {
  if (u === null) return [];
  return [
    ...(isPatient(u) ? [{ path: '/my-area', key: 'APP.MENU_MY_AREA', icon: 'home' }] : []),
    { path: '/schedule', key: 'APP.MENU_SCHEDULE', icon: 'calendar' },
    ...(isAdmin(u)
      ? [
          { path: '/doctors', key: 'APP.MENU_DOCTORS', icon: 'medkit' },
          { path: '/clients', key: 'APP.MENU_PATIENTS', icon: 'people' },
        ]
      : []),
    ...(isPatient(u) ? [{ path: '/my-account', key: 'APP.MENU_ACCOUNT', icon: 'person-circle' }] : []),
  ];
}

@Component({
  selector: 'app-layout',
  imports: [
    RouterLink, IonRouterLink, IonSplitPane, IonMenu, IonMenuToggle, IonMenuButton, IonHeader, IonToolbar, IonTitle,
    IonButtons, IonButton, IonIcon, IonContent, IonList, IonItem, IonLabel, IonChip, IonPopover, IonRouterOutlet,
    IonFooter,
  ],
  templateUrl: './layout.html',
  styleUrl: './layout.scss',
})
export class Layout {
  private readonly session = inject(Session);
  private readonly translations = inject(Translations);
  readonly messages = inject(Messages);
  readonly t = this.translations.t;
  readonly language = this.translations.language;
  readonly languages = languages;
  readonly user = this.session.user;
  readonly entries = computed(() => menuEntries(this.user()));

  // la dirección actual, sin sus parámetros: una señal construida a partir de
  // los eventos del enrutador (toSignal: Observable -> señal)
  private readonly path = toSignal(
    inject(Router).events.pipe(
      filter((e) => e instanceof NavigationEnd),
      map((e) => e.urlAfterRedirects.split('?')[0]),
    ),
    { initialValue: '' },
  );
  // el menú de idiomas: abierto o no, y bajo qué elemento
  readonly languagesOpen = signal(false);
  languagesEvent?: Event;

  constructor() {
    addIcons({ calendar, checkmarkCircle, close, alertCircle, home, logOutOutline, medkit, people, personCircle });
  }

  // la entrada del menú de la pantalla actual
  isActive(e: MenuEntry): boolean {
    return this.path().startsWith(e.path);
  }

  // el botón de idioma: el menú de idiomas se abre debajo de él
  openLanguages(event: Event): void {
    this.languagesEvent = event;
    this.languagesOpen.set(true);
  }

  // FR / EN: sin solicitud al servidor, la pantalla se traduce de nuevo al instante
  changeLanguage(l: Language): void {
    void this.translations.changeLanguage(l);
  }

  // la sesión se vacía; las guardias del enrutador, reevaluadas, muestran
  // la pantalla de inicio de sesión. catch: incluso si el servidor no responde
  logOut(): void {
    this.session.logOut().catch(() => undefined);
  }
}

El componente que rodea todas las pantallas: la barra superior, el menú y los mensajes. Es el equivalente del widget [ShellRoute] en el cliente [Flutter].

  • Líneas 37–41: una entrada del menú: una interfaz;
  • líneas 43–56: los elementos del menú permitidos para el rol del usuario. [...(condition ? [entries] : [])]: el operador de propagación inserta cero, uno o más elementos en el arreglo ([if] dentro de una lista de [Dart]);
  • líneas 69–76: los servicios y lo que muestra la plantilla: el idioma, el usuario y las entradas del menú (un valor calculado: cambia según el usuario);
  • líneas 80–86: la dirección actual, para marcar la entrada activa del menú. [toSignal] convierte un [Observable] (eventos del enrutador, reducidos a los de navegación) en una señal que la plantilla puede leer; se le debe dar un valor inicial;
  • líneas 88–89: el menú de idiomas: abierto o cerrado, y el evento (pulsación del botón) que lo abre;
  • línea 92: los íconos que usa la plantilla, registrados con [ionicons];
  • líneas 107–109: cambio de idioma: no se envía ninguna solicitud al servidor; cambia el diccionario y se actualiza todo lo que muestra una traducción;
  • líneas 113–115: cierre de sesión: se borra la sesión y los guardias, reevaluados (véase [app.ts]), muestran la pantalla de inicio de sesión. [catch]: aunque el servidor no responda, se considera que el usuario cerró la sesión.

11.12.2. src/app/components/layout.html

<!-- ======================================================================
     layout.html - el layout común a todas las pantallas
     ====================================================================== -->

<!-- ion-split-pane: a partir de 800 píxeles de ancho (when), el menú se
     muestra permanentemente a la izquierda del contenido; por debajo, es un menú lateral.
     contentId: el identificador del contenido principal. disabled: sin menú
     para un visitante que no ha iniciado sesión -->
<ion-split-pane contentId="main" when="(min-width: 800px)" [disabled]="!user()">
  <ion-menu contentId="main" [disabled]="!user()">
    <ion-content>
      @if (user(); as u) {
        <!-- el encabezado del menú: quién ha iniciado sesión -->
        <div class="who">
          <div class="name">{{ u.name }}</div>
          <ion-chip [outline]="true">{{ u.role }}</ion-chip>
        </div>
        <ion-list lines="none">
          @for (e of entries(); track e.path) {
            <!-- ion-menu-toggle: tocar la entrada cierra el menú lateral;
                 routerDirection="root": la pantalla elegida reemplaza toda la
                 pila de pantallas (no se puede volver a la pantalla anterior) -->
            <ion-menu-toggle [autoHide]="false">
              <ion-item
                [button]="true"
                [detail]="false"
                [routerLink]="e.path"
                routerDirection="root"
                [class.active]="isActive(e)"
              >
                <ion-icon slot="start" [name]="e.icon" />
                <ion-label>{{ t(e.key) }}</ion-label>
              </ion-item>
            </ion-menu-toggle>
          }
        </ion-list>
      }
    </ion-content>
  </ion-menu>

  <!-- el contenido principal: una "página" de Ionic (clase ion-page: en columna,
       a toda la altura) -->
  <div class="ion-page" id="main">
    <ion-header>
      <ion-toolbar color="primary">
        <!-- ion-menu-button: el botón ☰, que abre el menú lateral. Se oculta
             solo cuando el menú está deshabilitado o se muestra permanentemente -->
        <ion-buttons slot="start">
          <ion-menu-button />
        </ion-buttons>
        <ion-title>{{ t('APP.TITLE') }}</ion-title>
        <ion-buttons slot="end">
          <!-- el botón de idioma abre el popover declarado más abajo -->
          <ion-button id="language-button" [title]="t('APP.LANGUAGE')" (click)="openLanguages($event)">
            <strong>{{ language().toUpperCase() }}</strong>
          </ion-button>
          @if (user()) {
            <ion-button [title]="t('APP.LOGOUT')" (click)="logOut()">
              <ion-icon slot="icon-only" name="log-out-outline" />
            </ion-button>
          }
        </ion-buttons>
      </ion-toolbar>
    </ion-header>

    <!-- ion-popover: una ventana pequeña, abierta (isOpen) bajo el elemento
         tocado (event); dismissOnSelect: se cierra al elegir una opción;
         didDismiss: se ha cerrado (por una elección, o por un toque fuera de ella) -->
    <ion-popover
      [isOpen]="languagesOpen()"
      [event]="languagesEvent"
      [dismissOnSelect]="true"
      (didDismiss)="languagesOpen.set(false)"
    >
      <ng-template>
        <ion-list lines="none">
          @for (l of languages; track l) {
            <ion-item [button]="true" [detail]="false" (click)="changeLanguage(l)">
              <ion-label>{{ l.toUpperCase() }}</ion-label>
            </ion-item>
          }
        </ion-list>
      </ng-template>
    </ion-popover>

    <!-- el mensaje de éxito, en la parte superior -->
    @if (messages.success(); as success) {
      <ion-item class="message success" lines="none">
        <ion-icon slot="start" name="checkmark-circle" />
        <ion-label class="ion-text-wrap">{{ t(success.key, success.params) }}</ion-label>
        <ion-button slot="end" fill="clear" color="dark" (click)="messages.clear()">
          <ion-icon slot="icon-only" name="close" />
        </ion-button>
      </ion-item>
    }

    <!-- la pantalla actual -->
    <div class="screen">
      <ion-router-outlet />
    </div>

    <!-- el área de errores, en la parte inferior: siempre visible, aunque la pantalla se desplace.
         ion-footer: por encima de la barra de navegación del teléfono -->
    @if (messages.error(); as error) {
      <ion-footer>
        <ion-item class="message error" lines="none">
          <ion-icon slot="start" name="alert-circle" />
          <ion-label class="ion-text-wrap">{{ t(error.key, error.params) }}</ion-label>
          <ion-button slot="end" fill="clear" color="dark" (click)="messages.clear()">
            <ion-icon slot="icon-only" name="close" />
          </ion-button>
        </ion-item>
      </ion-footer>
    }
  </div>
</ion-split-pane>
  • línea 9: [ion-split-pane]: en una pantalla grande (aquí, de más de 800 píxeles de ancho: [when], una «media query» de CSS), el menú se muestra de forma PERMANENTE a la izquierda del contenido; en una pantalla pequeña, es un panel deslizable que se abre con el botón ☰. El diseño de [Flutter], creado aquí por [Ionic] mismo, hacía la elección entre [NavigationDrawer] y [NavigationRail]. [contentId]: el identificador del contenido principal (línea 43). No hay menú para un visitante que no ha iniciado sesión ([disabled]);
  • líneas 10–39: [ion-menu]: el menú; en la parte superior, para los usuarios con sesión iniciada (el nombre y el rol en una «viñeta», [ion-chip]);
  • líneas 23–34: un elemento del menú. [ion-menu-toggle] cierra el panel cuando se toca el elemento ([autoHide] en [false]: el elemento permanece visible cuando el menú se muestra de forma permanente). [routerLink]: la dirección de la pantalla (véase el ejemplo 17); [routerDirection="root"]: la pantalla seleccionada REEMPLAZA toda la pila de pantallas de [Ionic]: el botón Atrás no vuelve a la pantalla anterior (como con [context.go] y [go_router]). [class.active]: la clase CSS [active] se asigna a la entrada de la pantalla actual;
  • línea 43: el contenido principal: una «página» de [Ionic] (clase [ion-page]: en una columna, que ocupa toda la altura);
  • líneas 44–64: la barra superior: el botón ☰ ([ion-menu-button], que se oculta automáticamente cuando el menú está deshabilitado o se muestra de forma permanente), el título, el botón de idioma (su texto, «FR» o «EN») y el botón de cierre de sesión (solo para un usuario con sesión iniciada);
  • líneas 69–84: [ion-popover]: una ventana pequeña, abierta ([isOpen]) debajo del elemento tocado ([event]), que se cierra cuando ([dismissOnSelect]); [didDismiss]: se ha cerrado, ya sea por una selección o al tocar fuera de ella. Su contenido está en un [ng-template]: solo se construye al abrirse;
  • líneas 87–95: el mensaje de éxito, en la parte superior, si lo hay. [@if (messages.success(); as success)]: la condición y su valor almacenado en una variable de plantilla;
  • Líneas 98–100: la ubicación de las pantallas, [ion-router-outlet] (véase el ejemplo 17): el enrutador muestra allí la pantalla de la dirección actual. [Ionic] administra la transición entre pantallas y mantiene en memoria, ocultas, las pantallas anteriores: el botón Atrás vuelve a ellas sin volver a crearlas;
  • líneas 104–114: el área de errores en la parte inferior: [ion-footer], que permanece visible aunque la pantalla se desplace y está ubicada por encima de la barra de navegación del teléfono.

11.12.3. src/app/components/layout.scss

// =========================================================================
// layout.scss - los estilos del layout
// =========================================================================

// el encabezado del menú. En el teléfono, el menú lateral se extiende bajo la barra de
// estado de Android (la hora, la batería): su altura se suma en la parte superior
.who {
  padding: calc(16px + var(--ion-safe-area-top, 0px)) 16px 8px 20px;

  .name {
    font-size: 18px;
    font-weight: 500;
  }
}

// la entrada del menú de la pantalla actual: sobre un fondo de color, redondeado
ion-item.active {
  --background: rgba(var(--ion-color-primary-rgb), 0.14);
  --border-radius: 28px;
  margin: 0 8px;
  font-weight: 500;
}

ion-menu-toggle ion-item {
  margin: 0 8px;
}

// en una pantalla grande: el ancho del menú mostrado permanentemente
ion-split-pane {
  --side-width: 230px;
  --side-min-width: 230px;
  --side-max-width: 230px;
}

// el lugar de las pantallas: toda la altura restante. <ion-router-outlet>
// está posicionado "absolute": llena este contenedor "relative"
.screen {
  position: relative;
  flex: 1;
}

// los banners de mensajes
.message {
  font-size: 17px;
}

.success {
  --background: #e8f5e9;
  --color: #1b5e20;

  ion-icon[slot='start'] {
    color: #388e3c;
  }
}

.error {
  --background: #f8d7da;
  --color: #b71c1c;

  ion-icon[slot='start'] {
    color: #c62828;
  }
}

Los estilos del diseño. Se aplican solo a los elementos de [layout.html]: [Angular] «encapsula» los estilos de un componente.

  • Líneas 7–8: el encabezado del menú (el nombre y el rol del usuario). En el teléfono, la aplicación ocupa toda la pantalla, incluida la barra superior donde [Android] muestra la hora y el nivel de batería (la barra de estado): la barra de herramientas de [Ionic] ([ion-toolbar]) ajusta automáticamente su posición, pero este simple [div] no lo hace. La variable CSS [--ion-safe-area-top], proporcionada por [Ionic], indica la altura de esta barra (0 en un navegador): se suma al margen superior. Sin ella, el nombre se superpone con la hora;
  • líneas 17–22: el elemento activo del menú, sobre un fondo de color con esquinas redondeadas, como en un menú de [Material] 3. [rgba(var(--ion-color-primary-rgb), 0.14)]: el color principal, casi transparente;
  • líneas 29–33: el ancho del menú mostrado de forma permanente (de lo contrario, 270 píxeles);
  • líneas 37–40: [ion-router-outlet] se establece como «absoluto» (llena a su elemento padre): se coloca en un contenedor que ocupa toda la altura restante ([flex: 1]), entre los mensajes;
  • líneas 47–63: los banners de mensajes: verde para el éxito, rosa para un error y los colores de los demás clientes.

11.12.4. src/app/components/page-title.ts

// =========================================================================
// src/app/components/page-title.ts - el título de la pantalla, traducido
// -------------------------------------------------------------------------
// En la web: el título de la pestaña; en Android: el nombre de la aplicación
// en la lista de aplicaciones recientes. "Agenda - RdvMedecins"
//
// El enrutador de Angular puede dar un título a cada pantalla: la
// propiedad title de una ruta (véase app.routes.ts). Después de cada navegación,
// llama a la "estrategia de títulos" (TitleStrategy). Reemplazamos la de Angular
// (véase main.ts) por esta: nuestros títulos son CLAVES de
// traducción, y el título también debe cambiar cuando cambia el idioma.
// =========================================================================

import { effect, inject, Injectable, signal } from '@angular/core';
import { Title } from '@angular/platform-browser';
import { RouterStateSnapshot, TitleStrategy } from '@angular/router';
import { Translations } from '../i18n/translations';

@Injectable()
export class PageTitle extends TitleStrategy {
  private readonly title = inject(Title);
  private readonly t = inject(Translations).t;
  // la clave del título de la pantalla actual
  private readonly key = signal<string | undefined>(undefined);

  constructor() {
    super();
    // se vuelve a ejecutar cuando cambia la clave (navegación) O cuando cambia el idioma
    // (t lee el diccionario, una señal)
    effect(() => {
      const key = this.key();
      const application = this.t('APP.TITLE');
      this.title.setTitle(key ? `${this.t(key)} - ${application}` : application);
    });
  }

  // llamado por el enrutador después de cada navegación; buildTitle: la
  // propiedad title de la ruta mostrada
  override updateTitle(state: RouterStateSnapshot): void {
    this.key.set(this.buildTitle(state));
  }
}

El título de la pantalla, traducido: el título del documento, el título de la pestaña en la web. El enrutador de [Angular] sabe asignar un título a cada pantalla: la propiedad [title] de su ruta (véase [app.routes.ts]); después de cada navegación, llama a la «estrategia de título» ([TitleStrategy]), que [main.ts] reemplaza por esta.

  • línea 19: [@Injectable()] sin [providedIn]: el servicio lo proporciona [main.ts], en lugar del de [Angular];
  • Líneas 30–34: un efecto, que se vuelve a ejecutar cuando cambia la clave del título (un evento de navegación) O cuando cambia el idioma ([t] lee el diccionario, una señal). [Title]: el servicio de [Angular] que escribe el título de la página;
  • líneas 39–41: lo llama el enrutador después de cada navegación; [buildTitle] establece la propiedad [title] de la ruta mostrada.

El cliente [Flutter] envuelve cada pantalla en un widget [PageTitle]; aquí, los títulos se declaran junto con las rutas.

11.12.5. src/app/components/form-submission.ts

// =========================================================================
// src/app/components/form-submission.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 teléfono (residen en
// UN solo lugar, el servidor), y cuando se rechaza:
//   - el error de cada campo (ApiError.fields) se muestra bajo el campo;
//   - el mensaje general (ApiError.key) se muestra en la parte inferior de la pantalla.
// Esta clase agrupa estos pasos. No es un servicio: una pantalla
// crea una por formulario (new), con sus propias señales:
//
//     readonly submission = new FormSubmission(inject(Messages));
//     if (await this.submission.submit(() => api.register(form))) { ... }
//     <app-input-field ... [error]="submission.errors()['lastName']" />
// =========================================================================

import { signal } from '@angular/core';
import { ApiError, Texts } from '../api/api-error';
import { Messages } from '../state/messages';

export class FormSubmission {
  // el error de cada campo: una CLAVE de traducción
  readonly errors = signal<Texts>({});
  // los parámetros de los mensajes de error ({{min}}...), devueltos por el servidor
  readonly params = signal<Texts>({});
  readonly inProgress = signal(false);

  constructor(private readonly messages: Messages) {}

  // ejecuta el envío; devuelve true si tuvo éxito. Ante un ApiError, los
  // errores se muestran y se devuelve false
  async submit(action: () => Promise<unknown>): Promise<boolean> {
    if (this.inProgress()) return false; // sin doble envío
    this.errors.set({});
    this.params.set({});
    this.inProgress.set(true);
    try {
      await action();
      return true;
    } catch (e) {
      // cualquier otro error es una anomalía: showApiError lo lanza de nuevo
      this.messages.showApiError(e);
      const error = e as ApiError;
      this.errors.set(error.fields);
      this.params.set(error.params);
      return false;
    } finally {
      this.inProgress.set(false);
    }
  }

  // el usuario cambia un campo: su error desaparece
  clearError(field: string): void {
    if (field in this.errors()) {
      // un objeto NUEVO, sin este campo: la señal cambia de valor
      const { [field]: _removed, ...others } = this.errors();
      this.errors.set(others);
    }
  }
}

Envío de un formulario al servidor: el [Command] del ejemplo 23, complementado con errores de campo (ejemplo 25). No es un servicio: cada formulario crea el suyo ([new]), con sus propias señales.

  • Líneas 23–26: el error de cada campo (una clave de traducción), los parámetros del mensaje y el envío en curso (los botones se deshabilitan). Tres señales, que las plantillas leen;
  • línea 28: [private readonly messages]: un parámetro del constructor que se convierte en propiedad (véase [api-error.ts]);
  • Líneas 32–50: el envío: sin envíos duplicados; si se produce [ApiError], se muestran el mensaje general en la parte inferior de la pantalla y el error de cada campo. [finally] se ejecuta en todos los casos, incluso después de un [return];
  • Líneas 53–59: el usuario corrige un campo; el error desaparece. Se crea un objeto NUEVO, sin ese campo ([const { [field]: _removed, ...others } = ...]: una asignación por desestructuración, cuyo resto, [others], contiene todos los campos salvo ese): una señal solo notifica a sus oyentes si su valor cambia, y modificar el propio objeto no lo cambiaría.

11.12.6. src/app/components/input-field.ts

// =========================================================================
// src/app/components/input-field.ts - un campo de formulario completo
// -------------------------------------------------------------------------
// Etiqueta + campo + mensaje de ayuda O mensaje de error. Todos los
// formularios de la aplicación lo usan:
//
//   <app-input-field label="PERSONS.LASTNAME_LABEL" [maxLength]="20"
//       [value]="form().lastName" (valueChange)="update('lastName', $event)"
//       [error]="submission.errors()['lastName']" />
//
// Es un componente CONTROLADO (véase el ejemplo 11): el valor pertenece al
// formulario padre, que lo entrega (input value) y lo recibe en
// cada pulsación de tecla (output valueChange). label, help y error son
// CLAVES de traducción; params, los parámetros de sus mensajes ({{min}}...).
// =========================================================================

import { Component, inject, input, output } from '@angular/core';
import { InputCustomEvent, IonInput } from '@ionic/angular';
import type { AutocompleteTypes } from '@ionic/core';
import { Texts } from '../api/api-error';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-input-field',
  imports: [IonInput],
  templateUrl: './input-field.html',
  styles: `
    :host {
      display: block;
      margin-bottom: 8px;
    }
  `,
})
export class InputField {
  readonly t = inject(Translations).t;

  // input.required: un input obligatorio (error de compilación si el padre lo olvida)
  readonly label = input.required<string>();
  readonly value = input.required<string>();
  readonly error = input<string>();
  readonly help = input<string>();
  readonly params = input<Texts>({});
  readonly secret = input(false); // una contraseña: caracteres ocultos
  readonly maxLength = input<number>();
  // para el administrador de contraseñas del teléfono ('username', 'current-password'...)
  readonly autocomplete = input<AutocompleteTypes>('off');

  readonly valueChange = output<string>();

  // ionInput: en cada pulsación de tecla (ionChange: solo cuando el campo pierde el foco)
  change(event: InputCustomEvent): void {
    this.valueChange.emit(event.detail.value ?? '');
  }
}

Un campo de formulario completo: etiqueta, campo, texto de ayuda o mensaje de error. Todos los formularios lo usan.

  • líneas 38–46: las entradas (véase el ejemplo 10). La etiqueta, el texto de ayuda y el mensaje de error son CLAVES de traducción. [input.required]: una entrada obligatoria; si el padre la omite, provoca un error de compilación. [AutocompleteTypes]: el tipo, proporcionado por [Ionic], de los valores permitidos para el atributo HTML [autocomplete];
  • línea 48: la salida (véase el ejemplo 11): el nuevo valor, con cada pulsación de tecla. Un componente CONTROLADO: el valor pertenece al padre, que lo proporciona ([value]) y lo recibe ([valueChange]). Cuando el padre lo cambia por su cuenta (el CAPTCHA se borra tras un fallo), el campo lo sigue: no hay nada que escribir, a diferencia del [didUpdateWidget] del cliente de [Flutter];
  • líneas 51–53: [ionInput]: el evento de [ion-input] para cada pulsación de tecla ([ionChange] ocurre solo cuando el campo pierde el foco); [detail.value] puede ser [null] o [undefined]: en ese caso, se envía una cadena vacía.

11.12.7. src/app/components/input-field.html

<!-- ======================================================================
     input-field.html - la plantilla de un campo de formulario
     ====================================================================== -->

<!-- fill="outline": un campo enmarcado; labelPlacement="floating": la
     etiqueta está dentro del campo vacío y "flota" sobre el marco apenas tiene
     el foco o un valor;
     helperText / errorText: los mensajes bajo el campo. errorText solo se
     muestra (en rojo, en lugar de la ayuda) si el campo tiene las
     clases ion-invalid Y ion-touched -->
<ion-input
  [label]="t(label())"
  fill="outline"
  labelPlacement="floating"
  [type]="secret() ? 'password' : 'text'"
  [value]="value()"
  [maxlength]="maxLength()"
  [autocomplete]="autocomplete()"
  [autocorrect]="secret() ? 'off' : 'on'"
  [helperText]="help() ? t(help()!, params()) : undefined"
  [errorText]="error() ? t(error()!, params()) : undefined"
  [class.ion-invalid]="!!error()"
  [class.ion-touched]="!!error()"
  (ionInput)="change($event)"
/>
  • líneas 13–14: un campo enmarcado ([fill="outline"]), cuya etiqueta está en el campo vacío y «flota» sobre el marco en cuanto tiene el foco o un valor;
  • línea 15: una contraseña se oculta;
  • líneas 17–19: [maxlength] restringe la entrada; [autocomplete] le indica al administrador de contraseñas del teléfono lo que contiene el campo (un nombre de usuario, una contraseña o una contraseña nueva); el corrector ortográfico no revisa las contraseñas;
  • líneas 20–23: los mensajes de ayuda y de error aparecen debajo del campo. [ion-input] muestra el error (en rojo, en lugar del texto de ayuda) solo si el campo tiene las clases CSS [ion-invalid], y [ion-touched]: se asignan cuando hay un error. Estas clases las asignan normalmente los formularios de [Angular] (ejemplo 08); aquí es el SERVIDOR quien determina la validez. Lo que los ejemplos 07 y 11 desaconsejaban (asignar estas clases manualmente) funciona aquí: [Ionic] las elimina, en efecto, en la siguiente pulsación de tecla, pero esa pulsación también borra el error ([clearError]), que ya no debe mostrarse;
  • Línea 24: cada pulsación de tecla llama a [change].

11.12.8. src/app/components/person-fields.ts

// =========================================================================
// src/app/components/person-fields.ts - título, nombre, apellido
// -------------------------------------------------------------------------
// Los campos de identidad, comunes a tres formularios: médico / cliente del
// ADMIN, "Crear una cuenta de paciente" y "Administrar mi cuenta". El padre
// le pasa los valores, los errores, y recibe cada cambio:
//     <app-person-fields [values]="form()" [errors]="submission.errors()"
//         (fieldChange)="update($event.field, $event.value)" />
// =========================================================================

import { Component, inject, input, output } from '@angular/core';
import { IonSelect, IonSelectOption, SelectCustomEvent } from '@ionic/angular';
import { Texts } from '../api/api-error';
import { Data } from '../api/rdvmedecins-api';
import { Translations } from '../i18n/translations';
import { InputField } from './input-field';

export const titles = ['Mr', 'Mme', 'Melle'];

export interface FieldChange {
  field: string;
  value: string;
}

@Component({
  selector: 'app-person-fields',
  imports: [IonSelect, IonSelectOption, InputField],
  templateUrl: './person-fields.html',
})
export class PersonFields {
  readonly t = inject(Translations).t;
  readonly titles = titles;

  readonly values = input.required<Data>();
  readonly errors = input.required<Texts>();
  readonly fieldChange = output<FieldChange>();

  // el valor de un campo, como texto
  value(field: string): string {
    return String(this.values()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.fieldChange.emit({ field, value });
  }

  chooseTitle(event: SelectCustomEvent<string>): void {
    this.update('title', event.detail.value);
  }
}

Los campos de identidad (título, nombre, apellido), comunes a los formularios de ADMIN, al formulario de creación de cuenta y al formulario «Administrar mi cuenta».

  • líneas 34–36: el padre pasa los valores y los errores, y recibe UNA salida para cualquier campo: su nombre y su nuevo valor;
  • líneas 39–41: el valor de un campo, como texto (los valores de formulario son de tipo [unknown]);
  • líneas 47–49: el título seleccionado de la lista; [SelectCustomEvent<string>]: el evento de [ion-select], cuyo valor es texto.

11.12.9. src/app/components/person-fields.html

<!-- ======================================================================
     person-fields.html - tratamiento, nombre, apellido
     ====================================================================== -->

<!-- ion-select: una lista desplegable, con etiqueta y mensaje de error;
     interface="popover": la lista se abre bajo el campo -->
<ion-select
  [label]="t('PERSONS.TITLE_LABEL')"
  fill="outline"
  labelPlacement="floating"
  interface="popover"
  [value]="value('title')"
  [errorText]="errors()['title'] ? t(errors()['title']) : undefined"
  [class.ion-invalid]="!!errors()['title']"
  [class.ion-touched]="!!errors()['title']"
  (ionChange)="chooseTitle($event)"
>
  @for (title of titles; track title) {
    <ion-select-option [value]="title">{{ title }}</ion-select-option>
  }
</ion-select>

<app-input-field
  label="PERSONS.FIRSTNAME_LABEL"
  [maxLength]="20"
  [value]="value('firstName')"
  (valueChange)="update('firstName', $event)"
  [error]="errors()['firstName']"
/>
<app-input-field
  label="PERSONS.LASTNAME_LABEL"
  [maxLength]="20"
  [value]="value('lastName')"
  (valueChange)="update('lastName', $event)"
  [error]="errors()['lastName']"
/>
  • líneas 7–21: el título, en una lista desplegable ([ion-select], véase el ejemplo 05), con etiqueta y mensaje de error, como un campo de entrada; [interface="popover"]: la lista se abre debajo del campo (de forma predeterminada, en un cuadro de diálogo);
  • líneas 23–36: nombre y apellido: dos campos de entrada. Los mensajes de error aparecen debajo del nombre de campo que espera el servidor ([errors()['firstName']]).

11.12.10. src/app/components/captcha-field.ts

// =========================================================================
// src/app/components/captcha-field.ts - la imagen del captcha y el campo de entrada
// -------------------------------------------------------------------------
// Un componente de visualización: la imagen (svg), el botón "Otra imagen"
// (output reload), y el campo, CONTROLADO por el formulario padre
// (value, valueChange). La imagen y su identificador los solicita al
// servidor la página de inicio de sesión, que los necesita para enviar la respuesta.
// =========================================================================

import { Component, computed, inject, input, output } from '@angular/core';
import { IonButton, IonIcon } from '@ionic/angular';
import { addIcons } from 'ionicons';
import { refresh } from 'ionicons/icons';
import { Translations } from '../i18n/translations';
import { InputField } from './input-field';

@Component({
  selector: 'app-captcha-field',
  imports: [IonButton, IonIcon, InputField],
  templateUrl: './captcha-field.html',
  styles: `
    .label {
      font-size: 13px;
      color: var(--ion-color-step-700, #444);
    }
    .row {
      display: flex;
      align-items: center;
      gap: 8px;
    }
    .image {
      width: 160px;
      height: 54px;
      background: #f5f7fa;
      border: 1px solid #d0d0d0;
      border-radius: 6px;
      object-fit: contain;
    }
  `,
})
export class CaptchaField {
  readonly t = inject(Translations).t;

  readonly svg = input<string>();
  readonly value = input.required<string>();
  readonly error = input<string>();
  readonly valueChange = output<string>();
  readonly reload = output<void>();

  // la imagen SVG (texto) -> una dirección "data:" que una etiqueta <img> puede
  // mostrar. Una imagen no puede ejecutar ningún script: es segura
  readonly source = computed(() => {
    const svg = this.svg();
    return svg ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}` : undefined;
  });

  constructor() {
    addIcons({ refresh });
  }
}

La imagen del CAPTCHA, el botón «Otra imagen» y el campo de entrada. El componente no llama al servidor: la pantalla de inicio de sesión solicita la imagen porque necesita su identificador para enviar la respuesta.

  • Líneas 21–39: los estilos del componente, escritos dentro del propio componente ([styles]): son breves;
  • línea 48: una salida vacía ([output<void>()]): «el usuario quiere otra imagen»;
  • Líneas 52–55: la imagen SVG se recibe como texto (ejemplo 22). Se convierte en una URL «data:» (el contenido del archivo codificado dentro de la propia URL), que una etiqueta [img] puede mostrar. Esto es seguro: una imagen no puede ejecutar ningún script, mientras que un SVG insertado en la página mediante [innerHTML] sí podría ([Angular] lo rechazaría, a menos que se autorice explícitamente).

11.12.11. src/app/components/captcha-field.html

<!-- ======================================================================
     captcha-field.html - la imagen del captcha y el campo de entrada
     ====================================================================== -->

<div class="label">{{ t('CAPTCHA.LABEL') }}</div>
<div class="row">
  @if (source(); as source) {
    <!-- alt: lo que lee un lector de pantalla en lugar de la imagen -->
    <img class="image" [src]="source" [alt]="t('CAPTCHA.IMAGE_ALT')" />
  } @else {
    <div class="image"></div>
  }
  <ion-button fill="clear" (click)="reload.emit()">
    <ion-icon slot="start" name="refresh" />
    {{ t('CAPTCHA.NEW_IMAGE') }}
  </ion-button>
</div>
<app-input-field
  label="CAPTCHA.LABEL"
  help="CAPTCHA.HELP"
  [maxLength]="10"
  [value]="value()"
  (valueChange)="valueChange.emit($event)"
  [error]="error()"
/>
  • línea 9: [alt]: lo que lee un lector de pantalla ([TalkBack] de [Android]) en lugar de la imagen;
  • líneas 13–16: «Otra imagen» emite [reload];
  • líneas 18–25: el campo, que también es controlado por el padre: el componente transmite el valor y sus posibles cambios.

11.12.12. src/app/components/confirmation.ts

// =========================================================================
// src/app/components/confirmation.ts - "¿Está seguro?"
// -------------------------------------------------------------------------
// Tomado del ejemplo 16. Un servicio, que abre un cuadro de diálogo de Ionic
// (AlertController). El mensaje es una CLAVE de traducción:
//     if (await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM')) { ... }
// "No, volver" en lugar de "Cancelar": la pregunta es a veces "¿Cancelar esta
// cita?", y un botón "Cancelar" allí sería ambiguo.
// Una nueva pregunta borra los mensajes de la acción anterior.
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { AlertController } from '@ionic/angular';
import { Messages } from '../state/messages';
import { Translations } from '../i18n/translations';

@Injectable({ providedIn: 'root' })
export class Confirmation {
  private readonly alerts = inject(AlertController);
  private readonly messages = inject(Messages);
  private readonly t = inject(Translations).t;

  async ask(key: string): Promise<boolean> {
    this.messages.clear();
    const alert = await this.alerts.create({
      // una clase CSS para el cuadro: su ancho (véase styles.scss)
      cssClass: 'confirmation',
      header: this.t('CONFIRMATION.TITLE'),
      message: this.t(key),
      buttons: [
        // role 'cancel': el botón No; una pulsación fuera del diálogo o el botón
        // Atrás del teléfono dan el rol 'backdrop': solo 'confirm' significa sí
        { text: this.t('CONFIRMATION.NO'), role: 'cancel' },
        // cssClass: el botón rojo (véase styles.scss)
        { text: this.t('CONFIRMATION.YES'), role: 'confirm', cssClass: 'danger-button' },
      ],
    });
    await alert.present();
    // onDidDismiss: una Promise, resuelta al cerrar, con el rol del botón
    const { role } = await alert.onDidDismiss();
    return role === 'confirm';
  }
}

La ventana de confirmación del ejemplo 16, utilizada así: [if (await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM')) ...]. Es un servicio, ya que no tiene nada que mostrar por sí mismo: es el [AlertController] de [Ionic] el que crea el cuadro de diálogo.

  • Línea 24: una nueva pregunta borra los mensajes de la acción anterior;
  • línea 27: una clase CSS para el cuadro: su ancho (véase [styles.scss]);
  • Líneas 33–35: los botones. Tocar fuera del cuadro de diálogo, o presionar el botón Atrás del teléfono, cierra el cuadro de diálogo con el rol [backdrop] (véase el ejemplo 16): solo «Sí, confirmar» ([confirm]) confirma;
  • líneas 38–41: [present()] muestra el cuadro de diálogo; [onDidDismiss()] devuelve una [Promise], resuelta al cerrarse, con el rol del botón que se tocó.

11.12.13. src/app/components/booking-dialog.ts

// =========================================================================
// src/app/components/booking-dialog.ts - el contenido del diálogo para
// reservar una franja
// -------------------------------------------------------------------------
// El diálogo en sí es un <ion-modal> de la pantalla de la agenda, abierto
// cuando su DIRECCIÓN lo pide (/schedule?...&book=7, véase
// pages/schedule.ts): la dirección describe así toda la pantalla, diálogo incluido.
// Este componente es solo su CONTENIDO.
//
// No habla con el servidor: emite
//   - confirm, con el paciente elegido (undefined para un paciente que
//     reserva para sí mismo);
//   - close.
// Es la pantalla de la agenda la que decide qué hacer con ellos.
// =========================================================================

import { Component, inject, input, output, signal } from '@angular/core';
import { IonButton, IonSelect, IonSelectOption, SelectCustomEvent } from '@ionic/angular';
import { label, Person } from '../api/types';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-booking-dialog',
  imports: [IonButton, IonSelect, IonSelectOption],
  templateUrl: './booking-dialog.html',
  styles: `
    :host {
      display: block;
      padding: 20px;
    }
    h2 {
      margin-top: 0;
      font-size: 22px;
      font-weight: 400;
    }
    .buttons {
      display: flex;
      justify-content: flex-end;
      flex-wrap: wrap;
      gap: 8px;
      margin-top: 20px;
    }
  `,
})
export class BookingDialog {
  readonly t = inject(Translations).t;
  readonly label = label;

  readonly timeRange = input.required<string>(); // "8:00 - 8:20"
  // ADMIN / DOCTOR: los pacientes entre los que elegir
  readonly clients = input<Person[]>([]);
  // USER: el paciente es el propio usuario
  readonly patient = input<string>();
  readonly submitting = input(false);
  readonly confirm = output<number | undefined>();
  readonly close = output<void>();

  // el paciente elegido en la lista
  readonly clientId = signal<number | undefined>(undefined);

  choose(event: SelectCustomEvent<number>): void {
    this.clientId.set(event.detail.value);
  }
}

El contenido de la ventana de reserva de citas. La ventana en sí es un [ion-modal] de la pantalla de la agenda, que se abre cuando su dirección lo solicita ([&book=7], véase [schedule.html]).

  • Líneas 49–56: el componente no se comunica con el servidor: recibe lo que muestra y emite dos respuestas, una para confirmar (con el paciente seleccionado) y otra para cerrar la ventana. Cuando un paciente reserva una cita para sí mismo, recibe su propio nombre ([patient]) y ninguna lista;
  • Línea 59: el paciente seleccionado de la lista: el estado de la ventana.

11.12.14. src/app/components/booking-dialog.html

<!-- ======================================================================
     booking-dialog.html - el contenido del diálogo de reserva
     ====================================================================== -->

<h2>{{ t('BOOKING_DIALOG.TITLE') }}</h2>
<p>{{ t('BOOKING_DIALOG.SLOT', { time: timeRange() }) }}</p>

<!-- un paciente reserva para sí mismo: sin lista (y el servidor
     ignoraría cualquier clientId de todos modos) -->
@if (patient(); as patient) {
  <p>{{ t('BOOKING_DIALOG.PATIENT_LABEL') }}: <strong>{{ patient }}</strong></p>
} @else {
  <!-- placeholder: el texto mostrado mientras no se haya elegido ningún paciente -->
  <ion-select
    [label]="t('BOOKING_DIALOG.PATIENT_LABEL')"
    fill="outline"
    labelPlacement="stacked"
    interface="popover"
    [placeholder]="t('BOOKING_DIALOG.CHOOSE_PATIENT')"
    [value]="clientId()"
    (ionChange)="choose($event)"
  >
    @for (c of clients(); track c.id) {
      <ion-select-option [value]="c.id">{{ label(c) }}</ion-select-option>
    }
  </ion-select>
}

<div class="buttons">
  <ion-button fill="clear" (click)="close.emit()">{{ t('BOOKING_DIALOG.CANCEL') }}</ion-button>
  <ion-button [disabled]="submitting()" (click)="confirm.emit(clientId())">
    {{ t('BOOKING_DIALOG.CONFIRM') }}
  </ion-button>
</div>
  • líneas 10–11: un paciente hace una reserva para sí mismo: su nombre, sin lista;
  • líneas 14–26: el ADMIN o el médico selecciona al paciente de una lista desplegable; [placeholder]: el texto que se muestra mientras no se haya seleccionado ningún paciente;
  • líneas 29–34: los botones, alineados a la derecha; «Confirmar» se deshabilita durante el envío.

11.13. Las pantallas

Cada pantalla es un componente, cargado bajo demanda por el enrutador (véase [app.routes.ts]), cuya plantilla comienza con [ion-content]: el área de desplazamiento, entre la barra superior y el área de errores del diseño.

11.13.1. src/app/pages/login.ts

// =========================================================================
// src/app/pages/login.ts - la pantalla de inicio de sesión (/login)
// -------------------------------------------------------------------------
// La misma pantalla que en los demás clientes: login, contraseña, captcha, y
// un segundo botón "Crear una cuenta de paciente" que verifica el MISMO captcha
// antes de abrir la creación de la cuenta.
//
// /login?login=jbernard: el campo login se rellena previamente (justo después de la
// creación de una cuenta).
// Tras un inicio de sesión exitoso, esta pantalla NO navega por sí misma: la
// sesión cambia, las guardias del enrutador se reevalúan (véase app.ts), y
// es la guardia la que sale de la pantalla de inicio de sesión (hacia ?redirect=... o
// la página de inicio del rol, véase app.routes.ts).
// =========================================================================

import { Component, inject, input, linkedSignal, signal } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent, ViewWillEnter } from '@ionic/angular';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { Captcha } from '../api/types';
import { CaptchaField } from '../components/captcha-field';
import { InputField } from '../components/input-field';
import { FormSubmission } from '../components/form-submission';
import { Messages } from '../state/messages';
import { Session } from '../state/session';
import { Translations } from '../i18n/translations';

// las cuentas de demostración
const demoAccounts = [
  { accounts: 'admin', key: 'LOGIN.DEMO_ADMIN' },
  { accounts: 'pelissier, tatou, dupont', key: 'LOGIN.DEMO_DOCTOR' },
  { accounts: 'martin, durand, bistrou, german', key: 'LOGIN.DEMO_USER' },
];

@Component({
  selector: 'app-login',
  imports: [IonContent, IonButton, InputField, CaptchaField],
  templateUrl: './login.html',
})
export class LoginPage implements ViewWillEnter {
  private readonly api = inject(RdvMedecinsApi);
  private readonly session = inject(Session);
  private readonly router = inject(Router);
  private readonly messages = inject(Messages);
  readonly t = inject(Translations).t;
  readonly submission = new FormSubmission(this.messages);
  readonly demoAccounts = demoAccounts;

  // el login de la dirección (?login=...), entregado por el enrutador
  // (withComponentInputBinding, véase main.ts)
  readonly login = input<string>();
  // el formulario: una señal ENLAZADA al input login. Empieza con él (30
  // caracteres como máximo), puede modificarse después, y vuelve a partir de él si
  // la dirección cambia
  readonly form = linkedSignal(() => ({ login: (this.login() ?? '').slice(0, 30), password: '', captcha: '' }));
  readonly captcha = signal<Captcha | null>(null);

  // ionViewWillEnter: llamado por Ionic cada vez que la pantalla está a punto de
  // mostrarse (la primera vez, y al volver a ella)
  ionViewWillEnter(): void {
    void this.reloadCaptcha();
  }

  // una imagen nueva: se necesita después de CADA intento, porque una imagen solo se
  // usa UNA vez (el servidor la olvida apenas la ha verificado)
  async reloadCaptcha(): Promise<void> {
    try {
      this.captcha.set(await this.api.captcha());
    } catch {
      this.captcha.set(null); // servidor inaccesible: el inicio de sesión fallará con un mensaje claro
    }
  }

  update(field: 'login' | 'password' | 'captcha', value: string): void {
    // un objeto NUEVO: la señal cambia de valor
    this.form.update((f) => ({ ...f, [field]: value }));
    this.submission.clearError(field);
  }

  // los dos botones comparten esta secuencia: envío y, si falla,
  // mensaje de error e imagen NUEVA
  private async attempt(action: () => Promise<void>): Promise<void> {
    this.messages.clear();
    const succeeded = await this.submission.submit(action);
    if (!succeeded) {
      this.form.update((f) => ({ ...f, captcha: '' }));
      await this.reloadCaptcha();
    }
  }

  // si tiene éxito, no hay nada más que hacer aquí: la guardia cambia la pantalla
  logIn(): Promise<void> {
    const f = this.form();
    return this.attempt(() => this.session.logIn(f.login.trim(), f.password, this.captcha()?.id ?? '', f.captcha));
  }

  createAccount(): Promise<void> {
    return this.attempt(async () => {
      await this.api.registrationAccess(this.captcha()?.id ?? '', this.form().captcha);
      await this.router.navigateByUrl('/register');
    });
  }
}

La pantalla de inicio de sesión.

  • líneas 29–33: las cuentas de demostración, mostradas debajo del formulario;
  • líneas 41–47: los servicios (recibidos mediante [inject()]), el envío del formulario y las cuentas de demostración;
  • línea 51: el inicio de sesión de la dirección ([/login?login=jbernard], tras crear una cuenta), asignado a esta entrada por el enrutador;
  • línea 55: la entrada: un objeto (nombre del campo → valor) en un [linkedSignal]: un valor modificable, pero VINCULADO a un cálculo. COMIENZA con el valor calculado (el inicio de sesión de la dirección, hasta 30 caracteres); se puede modificar después, y el cálculo se reinicia si cambia la entrada [login]. No se puede leer una entrada durante la inicialización de un campo (aún no ha recibido su valor): [linkedSignal] resuelve este problema;
  • línea 56: el CAPTCHA recibido (su ID y su imagen);
  • líneas 60–62: [ionViewWillEnter]: un método al que [Ionic] llama cada vez que la pantalla está a punto de mostrarse; la primera vez Y al volver a la pantalla (la pantalla, almacenada en memoria, no se vuelve a crear). Aquí se solicita una imagen nueva: la de la visita anterior puede haberse usado ya;
  • líneas 66–72: una imagen nueva, al abrir la pantalla, a petición del usuario y después de CADA intento (una imagen se usa una sola vez);
  • Líneas 74–78: un campo modificado: un objeto NUEVO ([{ ...f, [field]: value }]: una copia, en la que cambia un campo), y el error del campo desaparece. El parámetro [field] acepta solo los tres nombres de la entrada: un error tipográfico provocaría un error de compilación;
  • líneas 82–89: ambos botones siguen esta secuencia: envío y, si no tiene éxito, se borra el CAPTCHA y se muestra una imagen nueva;
  • líneas 92–95: el inicio de sesión. Si tiene éxito, la pantalla no hace nada más: la sesión cambia, los guardias se reevalúan y es el guardia quien saca al usuario de la pantalla de inicio de sesión (véase [app.routes.ts]);
  • líneas 97–102: «Crear una cuenta de paciente»: el servidor verifica el CAPTCHA y emite un token (una cookie); a continuación se abre la pantalla de creación de la cuenta.

11.13.2. src/app/pages/login.html

<!-- ======================================================================
     login.html - la pantalla de inicio de sesión
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t('LOGIN.TITLE') }}</h1>

  <!-- autocomplete: el administrador de contraseñas del teléfono puede
       completar el formulario -->
  <app-input-field
    label="LOGIN.LOGIN_LABEL"
    autocomplete="username"
    [value]="form().login"
    (valueChange)="update('login', $event)"
    [error]="submission.errors()['login']"
  />
  <app-input-field
    label="LOGIN.PASSWORD_LABEL"
    autocomplete="current-password"
    [secret]="true"
    [value]="form().password"
    (valueChange)="update('password', $event)"
    [error]="submission.errors()['password']"
  />
  <app-captcha-field
    [svg]="captcha()?.svg"
    [value]="form().captcha"
    (valueChange)="update('captcha', $event)"
    (reload)="reloadCaptcha()"
    [error]="submission.errors()['captcha']"
  />

  <!-- expand="block": el ancho completo -->
  <ion-button expand="block" shape="round" [disabled]="submission.inProgress()" (click)="logIn()">
    {{ t('LOGIN.SUBMIT') }}
  </ion-button>
  <ion-button expand="block" shape="round" fill="outline" [disabled]="submission.inProgress()" (click)="createAccount()">
    {{ t('LOGIN.CREATE_ACCOUNT') }}
  </ion-button>
  <p class="ion-text-center help">{{ t('LOGIN.CREATE_ACCOUNT_HELP') }}</p>

  <!-- las cuentas de demostración -->
  <div class="demo">
    <div>{{ t('LOGIN.DEMO_ACCOUNTS') }}</div>
    @for (d of demoAccounts; track d.key) {
      <div>• <code>{{ d.accounts }}</code> - {{ t(d.key) }}</div>
    }
  </div>
</ion-content>
  • líneas 10–24: el nombre de usuario y la contraseña. [autocomplete]: el administrador de contraseñas del teléfono los rellena y ofrece guardar la cuenta después de iniciar sesión;
  • líneas 25–31: el CAPTCHA; su imagen la envía el servidor después de que se muestra la pantalla: [captcha()?.svg] equivale a [undefined] hasta entonces;
  • líneas 34–39: los dos botones, que ocupan todo el ancho ([expand="block"]), se deshabilitan durante el envío;
  • líneas 43–48: las cuentas de demostración: un bucle [@for] (véase el ejemplo 03) sobre el arreglo [login.ts]; [track d.key]: que identifica cada elemento.

11.13.3. src/app/pages/schedule.ts

// =========================================================================
// src/app/pages/schedule.ts - la pantalla de la agenda (/schedule)
// -------------------------------------------------------------------------
// Tres bloques, como en los demás clientes:
//   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 para reservar una franja (un <ion-modal>).
//
// TODO el estado de la pantalla está en su DIRECCIÓN:
//     /schedule?doctorId=1&day=2026-10-05              la agenda
//     /schedule?doctorId=1&day=2026-10-05&book=7       + el diálogo de reserva
// El enrutador entrega estos tres parámetros a los inputs del componente
// (withComponentInputBinding); la pantalla DEDUCE de ellos lo que muestra (señales
// computed), y las acciones del usuario cambian la dirección.
// En la web, se puede por lo tanto recargar la página, guardarla como marcador,
// usar Atrás / Adelante; en el teléfono, el botón Atrás cierra
// el diálogo de reserva.
//
// Lo que cada uno ve y puede hacer lo decide el SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada franja): la pantalla se limita
// a mostrarlo. Un paciente ni siquiera recibe los nombres de los demás pacientes.
// =========================================================================

import { Location } from '@angular/common';
import { Component, computed, effect, inject, input, linkedSignal, resource, signal } from '@angular/core';
import { Router } from '@angular/router';
import {
  DatetimeCustomEvent, IonButton, IonCard, IonCardContent, IonCardHeader, IonCardSubtitle, IonCardTitle, IonContent,
  IonDatetime, IonIcon, IonItem, IonLabel, IonList, IonModal, IonSelect, IonSelectOption, IonSpinner,
  SelectCustomEvent,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { calendarOutline } from 'ionicons/icons';
import { ApiError } from '../api/api-error';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { ScheduleSlot, label } from '../api/types';
import { positiveInteger } from '../app.routes';
import { Confirmation } from '../components/confirmation';
import { BookingDialog } from '../components/booking-dialog';
import { Cache, reloadAfterInvalidation } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { isManager, isPatient, Session } from '../state/session';
import { today, isValidDate, timeRange, longDay } from '../formatting';
import { Translations } from '../i18n/translations';

// la dirección de la agenda (sin el diálogo de reserva, o con él)
export function scheduleUrl(doctorId: number | undefined, day: string, book?: number): string {
  const params = new URLSearchParams({ doctorId: String(doctorId ?? ''), day });
  if (book !== undefined) params.set('book', String(book));
  return `/schedule?${params}`;
}

@Component({
  selector: 'app-schedule',
  imports: [
    IonContent, IonCard, IonCardContent, IonCardHeader, IonCardTitle, IonCardSubtitle, IonSelect, IonSelectOption,
    IonItem, IonLabel, IonIcon, IonButton, IonList, IonSpinner, IonModal, IonDatetime, BookingDialog,
  ],
  templateUrl: './schedule.html',
  styleUrl: './schedule.scss',
})
export class SchedulePage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly location = inject(Location);
  private readonly confirmation = inject(Confirmation);
  private readonly translations = inject(Translations);
  readonly t = this.translations.t;
  readonly user = inject(Session).user;
  readonly timeRange = timeRange;
  readonly label = label;

  // los parámetros de la dirección, tal cual (textos, posiblemente inválidos)
  readonly doctorId = input<string>();
  readonly day = input<string>();
  readonly book = input<string>();

  // lo que se deduce de ellos: señales COMPUTED (computed), recalculadas cuando
  // la dirección cambia
  readonly urlDoctorId = computed(() => positiveInteger(this.doctorId()));
  private readonly bookId = computed(() => positiveInteger(this.book()));
  // el día: el de la dirección si es válido, si no el de hoy
  readonly invalidDay = computed(() => {
    const day = this.day();
    return day !== undefined && !isValidDate(day);
  });
  readonly shownDay = computed(() => (this.invalidDay() ? today() : (this.day() ?? today())));

  // ==================================================== los datos
  // resource: una lectura asíncrona, descrita mediante señales. loader se
  // llama de nuevo cada vez que params cambia; un params undefined: nada que leer
  readonly doctors = resource({
    loader: () => this.cache.read('doctors', () => this.api.list('doctors')),
  });
  // los pacientes: solo para quienes tienen derecho a leerlos (diálogo de reserva)
  readonly clients = resource({
    params: () => (isManager(this.user()) ? true : undefined),
    loader: () => this.cache.read('clients', () => this.api.list('clients')),
  });
  // sin médico en la dirección, un DOCTOR ve SU agenda (el servidor
  // la encuentra a partir del token); los demás no ven nada
  readonly schedule = resource({
    params: () => {
      const id = this.urlDoctorId();
      if (this.invalidDay() || (id === undefined && this.user()?.role !== 'DOCTOR')) return undefined;
      return { id, day: this.shownDay() };
    },
    loader: ({ params: { id, day } }) => this.cache.read(`schedule/${id}/${day}`, () => this.api.schedule(id, day)),
  });

  // la agenda recibida (undefined: aún no llegó, falló, o no hay agenda)
  readonly s = computed(() => (this.schedule.hasValue() ? this.schedule.value() : undefined));
  // el médico mostrado: el de la dirección, o el de la agenda recibida (DOCTOR)
  readonly shownDoctorId = computed(() => this.urlDoctorId() ?? this.s()?.doctor.id);
  // la franja cuyo diálogo de reserva está abierto (&book=7),
  // solo si este usuario puede reservarla
  readonly toBook = computed(() => this.s()?.slots.find((c) => c.id === this.bookId() && c.bookable));
  // paciente que ya tiene una cita próxima: por qué no hay botón
  // "Reservar"; inútil en la agenda que contiene esta cita
  readonly info = computed(() => {
    const s = this.s();
    return s?.info && !s.slots.some((c) => c.mine) ? s.info : undefined;
  });
  // USER: el nombre del paciente, mostrado en el diálogo de reserva
  readonly patient = computed(() => {
    const u = this.user();
    return isPatient(u) ? u?.name : undefined;
  });

  // ==================================================== 1. la elección del médico y del día
  // un pequeño formulario, cuyo estado solo se usa antes de enviar. linkedSignal:
  // EMPIEZA con los valores de la dirección, y vuelve a ellos cuando esta cambia
  readonly doctorChoice = linkedSignal(() => this.shownDoctorId());
  readonly dayChoice = linkedSignal(() => this.shownDay());
  readonly calendarOpen = signal(false);
  // el idioma del calendario (ion-datetime): 'fr-FR' o 'en-US'
  readonly locale = computed(() => (this.translations.language() === 'fr' ? 'fr-FR' : 'en-US'));
  // el médico elegido debe estar en la lista (si no: ninguno)
  readonly knownId = computed(() => {
    const id = this.doctorChoice();
    const list = this.doctors.hasValue() ? this.doctors.value() : [];
    return list.some((d) => d.id === id) ? id : undefined;
  });

  readonly submitting = signal(false);
  // true si el diálogo se abrió con el botón "Reservar" de esta pantalla
  private openedHere = false;

  constructor() {
    addIcons({ calendarOutline });
    // datos invalidados (reserva, cancelación): se leen de nuevo
    reloadAfterInvalidation(this.doctors, this.clients, this.schedule);
    // una lectura fallida: su mensaje, en la parte inferior de la pantalla
    reportErrors(this.doctors, this.clients, this.schedule);
    // un día inválido en la dirección: un mensaje, mostrado DESPUÉS del fin de
    // la navegación en curso (setTimeout), que borra los mensajes de
    // la pantalla anterior (véase app.ts)
    effect(() => {
      if (this.invalidDay()) setTimeout(() => this.messages.showError('ERRORS.INVALID_DATE'));
    });
  }

  longDay(day: string): string {
    return longDay(day, this.translations.language());
  }

  chooseDoctor(event: SelectCustomEvent<number>): void {
    this.doctorChoice.set(event.detail.value);
  }

  // el calendario: "2026-10-05" (o "2026-10-05T00:00:00") -> "2026-10-05"
  chooseDay(event: DatetimeCustomEvent): void {
    const value = event.detail.value;
    if (typeof value === 'string') this.dayChoice.set(value.slice(0, 10));
    this.calendarOpen.set(false);
  }

  // "Ver agenda" cambia la dirección; el enrutador REUTILIZA este componente
  // (misma ruta): solo cambian sus inputs, y todo se recalcula
  view(): void {
    void this.router.navigateByUrl(scheduleUrl(this.knownId(), this.dayChoice()));
  }

  // "Reservar" cambia la DIRECCIÓN (&book=...): se abre el diálogo
  openBooking(c: ScheduleSlot): void {
    this.openedHere = true;
    void this.router.navigateByUrl(scheduleUrl(this.shownDoctorId(), this.shownDay(), c.id));
  }

  // cierre del diálogo: volver a la dirección anterior
  closeBooking(): void {
    // la dirección ya no tiene &book= (botón Atrás del navegador): nada que hacer
    if (this.bookId() === undefined) return;
    if (this.openedHere) {
      // como el botón Atrás: la dirección con &book= se quita del historial
      this.openedHere = false;
      this.location.back();
    } else {
      // pantalla abierta directamente en esta dirección: se reemplaza
      void this.router.navigateByUrl(scheduleUrl(this.shownDoctorId(), this.shownDay()), { replaceUrl: true });
    }
  }

  // el servidor es la referencia: tras cada acción, la agenda se lee de nuevo
  // (y el área del paciente, que muestra su cita). La invalidación
  // notifica a todas las pantallas de agenda vivas, incluida esta
  private reload(): void {
    this.cache.invalidate('my-area');
    this.cache.invalidate('schedule');
  }

  async confirmBooking(slot: ScheduleSlot, clientId: number | undefined): Promise<void> {
    const manager = isManager(this.user());
    this.submitting.set(true);
    try {
      await this.api.book(this.shownDay(), slot.id, manager ? clientId : undefined);
      this.messages.flash({ key: 'SCHEDULE.BOOKED' });
    } catch (e) {
      if (!(e instanceof ApiError)) throw e;
      if (e.key === 'ERRORS.CHOOSE_PATIENT') {
        // ningún paciente elegido: el diálogo permanece abierto
        this.messages.showError(e.key);
        return; // (finally se ejecuta de todos modos)
      }
      // franja ocupada mientras tanto, paciente que ya tiene una cita...: el
      // mensaje se mostrará en la agenda, con el diálogo cerrado
      this.messages.flash({ success: false, key: e.key, params: e.params });
    } finally {
      this.submitting.set(false);
    }
    this.closeBooking();
    this.reload();
  }

  async cancel(c: ScheduleSlot): Promise<void> {
    if (c.appointmentId === null || !(await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM'))) return;
    try {
      await this.api.cancelAppointment(c.appointmentId);
      this.messages.showSuccess('SCHEDULE.CANCELLED');
    } catch (e) {
      this.messages.showApiError(e);
    }
    this.reload();
  }

  goToMyArea(): void {
    void this.router.navigateByUrl('/my-area');
  }
}

La pantalla con más funciones: selección de un médico y un día, la agenda y la ventana de reserva.

  • líneas 47–51: la dirección de la agenda. TODO el estado de la pantalla está contenido en su dirección; las acciones del usuario la cambian, y la pantalla determina qué mostrar a partir de ella;
  • líneas 76–78: los tres parámetros de la dirección, proporcionados a las entradas por el enrutador. Son cadenas de texto, tal cual: pueden faltar o ser inválidos;
  • líneas 82–89: lo que se deriva de ellos: señales CALCULADAS, que se recalculan cuando cambia la dirección. La fecha de la dirección, si es válida; de lo contrario, la de hoy;
  • líneas 94–96: [resource()]: una lectura asíncrona, descrita mediante señales (es el [FutureBuilder] de [Flutter], pero mejor). Su función [loader] devuelve una [Promise]; el recurso expone señales: [value()], [isLoading()], [error()], [status()]... Los médicos se leen de la caché: una sola vez para toda la sesión;
  • Líneas 98–101: [params]: un cálculo del que depende el recurso. Cada vez que cambia su valor, se llama a [loader] con ese nuevo valor; si es igual a [undefined], no hay nada que leer. Aquí: los pacientes, solo si el usuario tiene permiso para verlos (para la ventana de citas);
  • líneas 104–111: la agenda; sus parámetros son el médico y el día de la cita. «Ver agenda» cambia la dirección; el enrutador REUTILIZA la pantalla (la misma ruta) con nuevas entradas; [params] cambia y la agenda se vuelve a leer, sin escribir nada más (el cliente [Flutter] necesitaba [didUpdateWidget]). Si no hay ningún médico en la dirección, un médico con sesión iniciada ve SU agenda (el servidor la obtiene mediante el token); los demás no ven nada;
  • línea 114: la agenda recibida. Primero [hasValue()]: leer [value()] de un recurso fallido provocaría un error;
  • línea 119: el horario de la ventana de reserva es el de la dirección ([&book=7]), solo si POR ESTE USUARIO es reservable (un horario ocupado entretanto, una dirección creada manualmente: no hay ventana de reserva);
  • líneas 122–125: el servidor envía este mensaje ([info]) junto con TODAS las agendas para un paciente que ya tiene una cita próxima; pero en la agenda que contiene esa cita (un horario [mine]), es innecesario, e incluso engañoso, inmediatamente después de una reserva: el paciente ve su cita, listada bajo su nombre, con un botón «Cancelar». Por lo tanto, solo se muestra en las demás agendas. [some]: verdadero si al menos un elemento del arreglo cumple la condición;
  • líneas 135–136: selección del médico y del día: un pequeño formulario, cuyo estado COMIENZA con los valores de la dirección y VUELVE a ellos cuando la dirección cambia (botón Atrás del navegador): dos [linkedSignal]. El cliente [Flutter] lograba esto volviendo a crear el widget (su clave cambiaba con la dirección);
  • línea 139: el idioma de la agenda, en el formato que espera [ion-datetime];
  • líneas 141–145: el médico seleccionado debe estar en la lista (de lo contrario: ninguno, y «Ver agenda» se deshabilita);
  • líneas 154–156: datos invalidados (reserva, cancelación): los tres recursos se vuelven a leer; si falla una operación de lectura, aparece un mensaje en la parte inferior de la pantalla (véanse [cache.ts] y [messages.ts]);
  • líneas 160–162: una fecha inválida en la dirección: un mensaje. Se muestra DESPUÉS del final de la navegación en curso ([setTimeout]: cuando todo el bloque de código actual y el que le sigue han terminado de ejecutarse); de lo contrario, el paso a la «nueva página» (véase [app.ts]) lo borraría de inmediato;
  • líneas 174–178: el día seleccionado en la agenda; [ion-datetime] devuelve una fecha en formato ISO («2026-10-05», a veces seguida de la hora);
  • líneas 182–184: «Ver agenda» cambia la dirección;
  • líneas 187–190: «Reservar» también cambia la dirección ([&book=...]): se agrega una entrada NUEVA al historial de navegación; la ventana de reserva se abre porque la dirección lo exige. [openedHere] registra que esta pantalla la abrió;
  • líneas 193–204: cerrar la ventana: volver a la dirección anterior. Si esta pantalla la abrió, se retrocede en el historial ([location.back()]), igual que con el botón Atrás de un teléfono o el botón Atrás de un navegador. Si la pantalla se abrió directamente en esta dirección (en la web), no hay nada detrás: se reemplaza la dirección por la de la agenda ([replaceUrl]). Si la dirección ya no contiene [&book=] (se acaba de retroceder), no hay nada que hacer;
  • líneas 209–212: después de una reserva o una cancelación, prevalecen los datos del servidor: se invalidan la agenda (y el área del paciente); la caché notifica a las pantallas de agenda, que se recargan;
  • líneas 214–235: la reserva. Si no se ha seleccionado ningún paciente, la ventana permanece abierta y muestra el mensaje. Cualquier otra acción cierra la ventana, y el mensaje (de éxito o de error, como un horario ocupado entretanto...) es un mensaje emergente que aparece cuando la dirección vuelve a la de la agenda;
  • líneas 237–246: la cancelación, después de una confirmación.

11.13.4. src/app/pages/schedule.html

<!-- ======================================================================
     schedule.html - la pantalla de la agenda
     ====================================================================== -->

<ion-content class="ion-padding">
  <!-- 1. la elección del médico y del día -->
  <ion-card class="picker">
    <ion-card-content>
      <ion-select
        [label]="t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')"
        fill="outline"
        labelPlacement="stacked"
        interface="popover"
        [placeholder]="t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')"
        [value]="knownId()"
        (ionChange)="chooseDoctor($event)"
      >
        @if (doctors.hasValue()) {
          @for (d of doctors.value(); track d.id) {
            <ion-select-option [value]="d.id">{{ label(d) }}</ion-select-option>
          }
        }
      </ion-select>
      <!-- el día: una fila que se toca para abrir el calendario -->
      <ion-item class="day" [button]="true" [detail]="false" lines="full" (click)="calendarOpen.set(true)">
        <ion-label>
          <p>{{ t('DOCTOR_DAY_PICKER.DAY_LABEL') }}</p>
          <h3>{{ longDay(dayChoice()) }}</h3>
        </ion-label>
        <ion-icon slot="end" name="calendar-outline" [attr.aria-label]="t('DOCTOR_DAY_PICKER.CHOOSE_DAY')" />
      </ion-item>
      <ion-button expand="block" shape="round" [disabled]="knownId() === undefined" (click)="view()">
        {{ t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE') }}
      </ion-button>
    </ion-card-content>
  </ion-card>

  <!-- el calendario, en un diálogo; locale: el idioma de los nombres de los
       días y de los meses; showDefaultButtons: los botones Cancelar / OK -->
  <ion-modal class="dialog" [isOpen]="calendarOpen()" (didDismiss)="calendarOpen.set(false)">
    <ng-template>
      <ion-datetime
        presentation="date"
        [value]="dayChoice()"
        [locale]="locale()"
        [firstDayOfWeek]="1"
        min="2020-01-01"
        max="2035-12-31"
        [showDefaultButtons]="true"
        [cancelText]="t('BOOKING_DIALOG.CANCEL')"
        doneText="OK"
        (ionChange)="chooseDay($event)"
      />
    </ng-template>
  </ion-modal>

  <!-- paciente que ya tiene una cita próxima: por qué no hay botón "Reservar" -->
  @if (info(); as info) {
    <ion-card class="info">
      <ion-item lines="none" color="none">
        <ion-label class="ion-text-wrap">{{ t(info) }}</ion-label>
        <ion-button slot="end" fill="clear" (click)="goToMyArea()">{{ t('APP.MENU_MY_AREA') }}</ion-button>
      </ion-item>
    </ion-card>
  }

  <!-- 2. la agenda -->
  @if (s(); as s) {
    <ion-card class="schedule">
      <ion-card-header>
        <ion-card-title>{{ t('SCHEDULE.TITLE_PREFIX') }} {{ longDay(s.day) }}</ion-card-title>
        <ion-card-subtitle>{{ label(s.doctor) }}</ion-card-subtitle>
      </ion-card-header>
      @if (s.slots.length === 0) {
        <ion-card-content>{{ t('SCHEDULE.NO_SLOTS') }}</ion-card-content>
      }
      <ion-list lines="full">
        @for (c of s.slots; track c.id) {
          <!-- las franjas reservables están ligeramente coloreadas -->
          <ion-item [class.bookable]="c.bookable">
            <div slot="start" class="time-range">{{ timeRange(c) }}</div>
            <ion-label>
              @if (c.free) {
                <span class="tag free">{{ t('SCHEDULE.FREE') }}</span>
              } @else if (c.patient) {
                <span class="tag" [class.mine]="c.mine">{{ label(c.patient) }}</span>
              } @else {
                <span class="tag">{{ t('SCHEDULE.BOOKED_BY_OTHER') }}</span>
              }
            </ion-label>
            <!-- los botones permitidos por el SERVIDOR (bookable, appointmentId) -->
            @if (c.bookable) {
              <ion-button slot="end" fill="outline" shape="round" (click)="openBooking(c)">
                {{ t('SCHEDULE.BOOK') }}
              </ion-button>
            } @else if (c.appointmentId !== null) {
              <ion-button slot="end" fill="outline" shape="round" color="danger" (click)="cancel(c)">
                {{ t('SCHEDULE.CANCEL_APPOINTMENT') }}
              </ion-button>
            }
          </ion-item>
        }
      </ion-list>
    </ion-card>
  } @else if (schedule.isLoading()) {
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  } @else if (schedule.status() === 'idle') {
    <p class="empty">{{ t('SCHEDULE.EMPTY_STATE') }}</p>
  }

  <!-- 3. el diálogo de reserva, abierto solo si la dirección contiene
       &book=...; se cierra (botón Atrás, toque fuera de él...):
       didDismiss -->
  <ion-modal class="dialog" [isOpen]="toBook() !== undefined" (didDismiss)="closeBooking()">
    <ng-template>
      @if (toBook(); as slot) {
        <app-booking-dialog
          [timeRange]="timeRange(slot)"
          [clients]="clients.hasValue() ? clients.value() : []"
          [patient]="patient()"
          [submitting]="submitting()"
          (confirm)="confirmBooking(slot, $event)"
          (close)="closeBooking()"
        />
      }
    </ng-template>
  </ion-modal>
</ion-content>
  • líneas 9–23: la lista de médicos; [labelPlacement="stacked"]: la etiqueta permanece sobre el campo, de modo que el texto «-- choose a doctor --» ([placeholder]) sea visible mientras no se haya seleccionado ningún médico. Las opciones esperan la lista: [@if (doctors.hasValue())];
  • líneas 25–31: el día se muestra como un campo (con su etiqueta encima, la fecha escrita completa y un ícono de calendario), en un [ion-item] que se toca para abrir el calendario;
  • líneas 32–34: «Ver agenda», deshabilitado hasta que se selecciona un médico conocido;
  • líneas 40–55: el calendario, [ion-datetime], en una ventana ([ion-modal]) abierta por la señal [calendarOpen]. [presentation="date"]: solo la fecha, sin la hora; [locale]: el idioma de los nombres de días y meses; [firstDayOfWeek]: la semana comienza el lunes; [showDefaultButtons]: los botones Cancelar / OK. «OK» emite [ionChange] con la fecha seleccionada y luego cierra la ventana; [didDismiss]: la ventana se ha cerrado (OK, Cancelar, toque fuera de ella, botón Atrás);
  • líneas 58–65: un paciente que ya tiene una cita próxima: por qué no hay botón «Reservar» (véase [info], arriba);
  • líneas 68–104: la agenda. Una línea por horario: la hora, una etiqueta (disponible, el nombre del paciente o «Reservado» para otro paciente) y el botón habilitado por el SERVIDOR ([bookable], [appointmentId]). [@else if]: la continuación de los casos de un [@if];
  • líneas 105–109: la agenda de citas se está cargando: una rueda giratoria ([ion-spinner]); no hay agenda que mostrar (el recurso está inactivo, [idle]): un mensaje que invita a seleccionar un médico y una fecha;
  • líneas 114–127: la ventana de reserva, abierta ([isOpen]) solo si la dirección corresponde a un horario reservable. También puede cerrarse por sí sola: con el botón Atrás del teléfono o con un toque a un lado; [didDismiss] llama entonces a [closeBooking], que valida la dirección. Su contenido es un [ng-template]: se crea solo al abrirse y se destruye al cerrarse (el paciente seleccionado se olvida).

El cliente [Flutter] dibujaba por sí mismo la ventana de reserva (un [Stack], un fondo gris, una tarjeta); [ion-modal] proporciona todo esto, junto con la animación de apertura y el manejo del botón Atrás.

11.13.5. src/app/pages/schedule.scss

// =========================================================================
// schedule.scss - los estilos de la pantalla de la agenda
// =========================================================================

ion-card {
  margin: 0 0 12px;
}

// el día: una fila que se parece a los campos de entrada
ion-item.day {
  --padding-start: 0;
  --inner-padding-end: 0;
  margin-bottom: 12px;

  p {
    font-size: 13px;
  }

  h3 {
    font-size: 16px;
  }
}

// la información destinada al paciente
ion-card.info {
  --background: #e1f5fe;
}

ion-card.schedule ion-card-title {
  font-size: 19px;
}

// las franjas reservables: un fondo verde pálido
ion-item.bookable {
  --background: #e8f5e9;
}

.time-range {
  width: 96px;
  font-size: 14px;
  font-weight: 500;
}

// una etiqueta de color (el "badge" de los demás clientes); gris por defecto
.tag {
  display: inline-block;
  padding: 3px 8px;
  border-radius: 6px;
  color: white;
  background: #757575;
  font-size: 13px;
  font-weight: bold;
  white-space: normal;

  &.free {
    background: #388e3c;
  }

  &.mine {
    background: var(--ion-color-primary);
  }
}

.empty {
  padding: 0 16px;
  color: var(--ion-color-medium-shade);
}

Estilos de la pantalla: vista del día, información del paciente (fondo azul claro), horarios reservables (fondo verde claro), agenda y etiquetas de colores (líneas 45–62: gris de forma predeterminada, verde para un horario disponible, índigo para la cita del paciente con sesión iniciada).

11.13.6. src/app/pages/persons-config.ts

// =========================================================================
// src/app/pages/persons-config.ts - ¿médicos o clientes?
// -------------------------------------------------------------------------
// Las pantallas de gestión de los médicos y de los clientes son IDÉNTICAS: la misma
// lista, el mismo formulario. Se escriben UNA sola vez (persons.ts,
// person-form.ts); solo cambian la dirección de la API y las
// claves de las etiquetas, descritas aquí. El enrutador pasa el tipo a cada pantalla.
// =========================================================================

import { PersonType } from '../api/rdvmedecins-api';
import { Person } from '../api/types';

export interface PersonKeys {
  title: string; // "Médicos"
  add: string; // "Agregar un médico"
  edit: string; // "Editar un médico"
  empty: string; // "Ningún médico."
  confirmDelete: string;
  added: string; // "Se agregó al médico {{name}} (login: {{login}})."
  edited: string;
  deleted: string;
  notFound: string; // el registro ha sido eliminado mientras tanto
}

// Record<PersonType, ...>: un objeto que tiene EXACTAMENTE una propiedad por
// tipo (el compilador verifica que no se olvide ninguna)
const allKeys: 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',
    notFound: 'ERRORS.DOCTOR_NOT_FOUND',
  },
  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',
    notFound: 'ERRORS.PATIENT_NOT_FOUND',
  },
};

export const keys = (type: PersonType): PersonKeys => allKeys[type];

// {{name}} y {{login}} de los mensajes de "agregado / editado / eliminado"
export const messageParams = (p: Person): Record<string, string> => ({
  name: `${p.firstName} ${p.lastName}`,
  login: p.login ?? '',
});

Las pantallas de médicos y clientes son idénticas; solo difieren las claves de las etiquetas, que se describen aquí.

  • líneas 13–23: las claves de un tipo de «persona», descritas mediante una interfaz;
  • líneas 27–50: [Record<PersonType, PersonKeys>]: un objeto que tiene EXACTAMENTE una propiedad por tipo de persona. Agregar un valor a [PersonType] provocaría aquí un error de compilación, mientras no se definan sus claves;
  • líneas 55–58: los parámetros de los mensajes «agregado», «modificado» y «eliminado».

11.13.7. src/app/pages/persons.ts

// =========================================================================
// src/app/pages/persons.ts - la lista de los médicos O de los clientes (ADMIN)
// -------------------------------------------------------------------------
// Una sola pantalla para ambos: el tipo (médicos o clientes) llega como un
// input (la propiedad data de la ruta, véase app.routes.ts); las etiquetas
// específicas de cada uno están en persons-config.ts.
// En un teléfono, una tabla de cinco columnas no cabe: una fila de lista
// por persona (nombre, login), con sus dos botones; el botón redondo
// "+" (<ion-fab>) agrega una persona.
// =========================================================================

import { Component, computed, inject, input, resource } from '@angular/core';
import { Router } from '@angular/router';
import {
  IonButton, IonCard, IonContent, IonFab, IonIcon, IonItem, IonLabel, IonSpinner,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { add, createOutline, trashOutline } from 'ionicons/icons';
import { RdvMedecinsApi, PersonType } from '../api/rdvmedecins-api';
import { label, Person } from '../api/types';
import { Confirmation } from '../components/confirmation';
import { Cache, reloadAfterInvalidation } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { Translations } from '../i18n/translations';
import { keys, messageParams } from './persons-config';

@Component({
  selector: 'app-persons',
  imports: [IonContent, IonCard, IonItem, IonLabel, IonButton, IonIcon, IonFab, IonSpinner],
  templateUrl: './persons.html',
  styleUrl: './persons.scss',
})
export class PersonsPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly confirmation = inject(Confirmation);
  readonly t = inject(Translations).t;
  readonly label = label;

  readonly type = input.required<PersonType>();
  readonly c = computed(() => keys(this.type()));

  // la lista, desde el caché; params: el tipo (el enrutador podría
  // reutilizar la pantalla para el otro tipo, /doctors -> /clients)
  readonly list = resource({
    params: () => this.type(),
    loader: ({ params: type }) => this.cache.read(type, () => this.api.list(type)),
  });

  constructor() {
    addIcons({ add, createOutline, trashOutline });
    reloadAfterInvalidation(this.list);
    reportErrors(this.list);
  }

  // "Mme Marie PELISSIER" -> "MP"
  initials(p: Person): string {
    return `${p.firstName.charAt(0)}${p.lastName.charAt(0)}`;
  }

  add(): void {
    void this.router.navigateByUrl(`/${this.type()}/add`);
  }

  edit(p: Person): void {
    void this.router.navigateByUrl(`/${this.type()}/${p.id}/edit`);
  }

  async remove(p: Person): Promise<void> {
    const c = this.c();
    if (!(await this.confirmation.ask(c.confirmDelete))) return;
    try {
      await this.api.remove(this.type(), p.id);
      this.messages.showSuccess(c.deleted, messageParams(p));
    } catch (e) {
      // un médico que todavía tiene citas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
      this.messages.showApiError(e);
    }
    // la lista se lee de nuevo (reloadAfterInvalidation)
    this.cache.invalidate(this.type());
  }
}

La lista de médicos o de clientes.

  • línea 42: el tipo (médicos o clientes): la propiedad [data] de la ruta, asignada a esta entrada;
  • líneas 47–50: la lista, tomada de la caché. Si el enrutador reutilizara la pantalla para el otro tipo, [params] cambiaría y se leería la otra lista;
  • líneas 63–69: agregar y editar abren el formulario mediante su dirección;
  • líneas 71–83: eliminación, después de una confirmación. El servidor rechaza a un médico con citas existentes (409 [DOCTOR_HAS_APPOINTMENTS]). En todos los casos, la lista se invalida y se vuelve a leer.

11.13.8. src/app/pages/persons.html

<!-- ======================================================================
     persons.html - la lista de médicos o de clientes
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t(c().title) }}</h1>

  @if (list.hasValue()) {
    @for (p of list.value(); track p.id) {
      <ion-card>
        <ion-item lines="none">
          <!-- las iniciales, en un círculo -->
          <div slot="start" class="initials">{{ initials(p) }}</div>
          <ion-label>
            <h2>{{ label(p) }}</h2>
            <p class="login">{{ p.login }}</p>
          </ion-label>
          <ion-button slot="end" fill="clear" color="medium" [title]="t('PERSONS.EDIT')" (click)="edit(p)">
            <ion-icon slot="icon-only" name="create-outline" />
          </ion-button>
          <ion-button slot="end" fill="clear" color="danger" [title]="t('PERSONS.DELETE')" (click)="remove(p)">
            <ion-icon slot="icon-only" name="trash-outline" />
          </ion-button>
        </ion-item>
      </ion-card>
    } @empty {
      <p>{{ t(c().empty) }}</p>
    }
  } @else if (list.isLoading()) {
    <!-- aún no cargada (o la carga falló: el mensaje está en la parte inferior de la pantalla) -->
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  }

  <!-- ion-fab: un botón flotante, fijo (slot="fixed") en la parte inferior derecha,
       sobre la lista que se desplaza -->
  <ion-fab slot="fixed" vertical="bottom" horizontal="end">
    <ion-button shape="round" size="large" class="extended-fab" (click)="add()">
      <ion-icon slot="start" name="add" />
      {{ t(c().add) }}
    </ion-button>
  </ion-fab>
</ion-content>
  • líneas 9–28: una tarjeta por persona: sus iniciales en un círculo, su nombre, su inicio de sesión y sus dos botones. Una tabla de cinco columnas, como la de los clientes web, no cabría en un teléfono. [@empty]: lo que un [@for] muestra cuando la tabla está vacía;
  • líneas 36–41: [ion-fab]: un botón flotante, anclado en la parte inferior derecha ([slot="fixed"]: no se desplaza con la lista), «+ Agregar un médico». El [FloatingActionButton.extended] de [Flutter] (un ícono y texto) no tiene un equivalente listo para usar en [Ionic] ([ion-fab-button] es redondo, solo para un ícono): se coloca un botón redondeado estándar dentro de [ion-fab].

11.13.9. src/app/pages/persons.scss

// =========================================================================
// persons.scss - los estilos de la lista de los médicos o los clientes
// =========================================================================

ion-card {
  margin: 0 0 10px;
}

// las iniciales, en un círculo de color
.initials {
  width: 44px;
  height: 44px;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #dde3fb;
  color: var(--ion-color-primary);
  font-weight: 500;
}

.login {
  font-family: 'Roboto Mono', monospace;
}

// algo de espacio en la parte inferior, para no ocultar la última fila bajo el botón flotante
ion-content {
  --padding-bottom: 96px;
}

// un botón flotante "extendido": ícono y texto, sobre un fondo claro
.extended-fab {
  --background: #dde3fb;
  --color: var(--ion-color-primary);
  --border-radius: 16px;
  text-transform: none;
}

Las iniciales en un círculo, el texto del inicio de sesión en una fuente monoespaciada, espacio debajo de la lista (líneas 27–29: de lo contrario, el botón flotante ocultaría la última tarjeta) y el botón flotante «extendido».

11.13.10. src/app/pages/person-form.ts

// =========================================================================
// src/app/pages/person-form.ts - creación O actualización de un
// médico o un cliente (ADMIN)
// -------------------------------------------------------------------------
//     /doctors/add               -> creación (sin id)
//     /doctors/3/edit            -> actualización (id = 3)
// (y las mismas direcciones bajo /clients).
//
// Para una actualización, la pantalla primero lee el registro; el formulario solo se
// muestra una vez leído el registro, y EMPIEZA con sus valores (un
// linkedSignal, sin tener que copiarlos después).
// Aquí no se verifica ninguna regla: el servidor valida todo, y sus errores
// se muestran bajo los campos (véase components/form-submission.ts).
// La VERSIÓN leída con el registro se reenvía con la actualización: si otro
// ADMIN lo ha modificado mientras tanto, el servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================

import { Component, computed, effect, inject, input, linkedSignal, resource, untracked } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent, IonSpinner } from '@ionic/angular';
import { ApiError } from '../api/api-error';
import { Data, RdvMedecinsApi, PersonType } from '../api/rdvmedecins-api';
import { positiveInteger } from '../app.routes';
import { InputField } from '../components/input-field';
import { PersonFields } from '../components/person-fields';
import { FormSubmission } from '../components/form-submission';
import { Cache } from '../state/cache';
import { Messages } from '../state/messages';
import { Translations } from '../i18n/translations';
import { keys, messageParams } from './persons-config';

const empty: Data = { title: 'Mr', firstName: '', lastName: '', login: '', password: '' };

@Component({
  selector: 'app-person-form',
  imports: [IonContent, IonButton, IonSpinner, InputField, PersonFields],
  templateUrl: './person-form.html',
})
export class PersonFormPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  readonly t = inject(Translations).t;
  readonly submission = new FormSubmission(this.messages);

  // el tipo: la propiedad data de la ruta; el id: el parámetro :id de
  // la dirección (ausente en una creación; su validez la verifica la ruta)
  readonly type = input.required<PersonType>();
  readonly id = input<string>();
  readonly recordId = computed(() => positiveInteger(this.id()));
  readonly creating = computed(() => this.recordId() === undefined);
  readonly c = computed(() => keys(this.type()));

  // actualización: el registro se lee (incluida su versión), SIN caché:
  // debe estar al día (de lo contrario el formulario empezaría con una versión
  // desactualizada: 409 CONCURRENT_UPDATE)
  readonly record = resource({
    params: () => {
      const id = this.recordId();
      return id === undefined ? undefined : { type: this.type(), id };
    },
    loader: ({ params: { type, id } }) => this.api.read(type, id),
  });

  // una COPIA modificable de los valores iniciales (el registro leído, o vacío)
  readonly form = linkedSignal<Data>(() => {
    if (!this.record.hasValue()) return { ...empty };
    const p = this.record.value();
    return { title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', password: '', version: p.version };
  });

  // el formulario se muestra para una creación, o una vez leído el registro
  readonly ready = computed(() => this.creating() || this.record.hasValue());

  constructor() {
    // registro que no existe (eliminado mientras tanto...): de vuelta a la lista
    effect(() => {
      const e = this.record.error();
      if (e instanceof ApiError) {
        untracked(() => {
          this.messages.flash({ success: false, key: e.key, params: e.params });
          void this.router.navigateByUrl(`/${this.type()}`);
        });
      }
    });
  }

  text(field: string): string {
    return String(this.form()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.form.update((f) => ({ ...f, [field]: value }));
    this.submission.clearError(field);
  }

  back(): void {
    void this.router.navigateByUrl(`/${this.type()}`);
  }

  async save(): Promise<void> {
    const type = this.type();
    const c = this.c();
    const id = this.recordId();
    const succeeded = await this.submission.submit(async () => {
      const p = id === undefined
        ? await this.api.add(type, this.form())
        : await this.api.edit(type, id, this.form());
      this.messages.flash({ key: this.creating() ? c.added : c.edited, params: messageParams(p) });
    });
    const key = this.messages.error()?.key;
    if (succeeded) {
      this.cache.invalidate(type); // la lista ha cambiado
      this.back();
    } else if (key === c.notFound) {
      // eliminado mientras tanto por otro ADMIN: de vuelta a la lista
      this.messages.flash({ success: false, key });
      this.back();
    }
  }
}

Agregar o editar un médico o un cliente.

  • líneas 49–53: el tipo ([data] de la ruta) y el identificador (el parámetro [:id] de la dirección, que está ausente en una adición);
  • líneas 58–64: en una modificación, el registro se lee SIN la caché: debe estar actualizado. En una adición, [params] es igual a [undefined]: no hay nada que leer;
  • líneas 67–71: la entrada COMIENZA con los valores del registro (o con valores vacíos) una vez que se ha leído el registro: otro [linkedSignal]. El cliente [Flutter] lograba esto con dos widgets (el segundo creado después de leer el registro);
  • línea 74: el formulario se muestra solo durante la creación o después de haber leído el registro;
  • líneas 78–86: un registro no encontrado (eliminado entretanto): se vuelve a la lista, con un mensaje;
  • líneas 102–121: guardado del registro: [POST] o [PUT], según haya o no un ID. El mensaje de éxito es un mensaje emergente: aparecerá en la lista. Si otro ADMIN eliminó entretanto un registro: se vuelve a la lista.

11.13.11. src/app/pages/person-form.html

<!-- ======================================================================
     person-form.html - creación o actualización de una persona
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t(creating() ? c().add : c().edit) }}</h1>

  @if (ready()) {
    <app-person-fields
      [values]="form()"
      [errors]="submission.errors()"
      (fieldChange)="update($event.field, $event.value)"
    />

    <h3>{{ t('PERSONS.ACCOUNT_SECTION') }}</h3>
    <app-input-field
      label="PERSONS.LOGIN_LABEL"
      [maxLength]="30"
      [value]="text('login')"
      (valueChange)="update('login', $event)"
      [error]="submission.errors()['login']"
      [help]="creating() ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'"
    />
    <!-- nunca rellenado previamente: la contraseña nunca regresa del servidor -->
    <app-input-field
      label="PERSONS.PASSWORD_LABEL"
      [secret]="true"
      [maxLength]="72"
      [value]="text('password')"
      (valueChange)="update('password', $event)"
      [error]="submission.errors()['password']"
      [params]="submission.params()"
      [help]="creating() ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT'"
    />

    <div class="buttons">
      <ion-button shape="round" [disabled]="submission.inProgress()" (click)="save()">
        {{ t('PERSONS.SAVE') }}
      </ion-button>
      <ion-button shape="round" fill="outline" (click)="back()">{{ t('PERSONS.BACK') }}</ion-button>
    </div>
  } @else {
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  }
</ion-content>
  • líneas 9–13: los campos de identidad (véase [person-fields.ts]);
  • líneas 16–34: el nombre de usuario y la contraseña, con indicaciones distintas para la creación y la modificación (dejar en blanco el campo de la contraseña no la cambia). La contraseña nunca se rellena previamente: el servidor nunca la devuelve. [params]: parámetros del mensaje de error de la contraseña ([{{min}}]...).

11.13.12. src/app/pages/register.ts

// =========================================================================
// src/app/pages/register.ts - "Crear una cuenta de paciente" (/register)
// -------------------------------------------------------------------------
// Solo se llega aquí después de copiar el captcha de la pantalla de inicio de sesión
// (botón "Crear una cuenta de paciente"): el servidor ha emitido entonces un
// pase (una cookie), que la guardia de la ruta ha verificado (véase
// app.routes.ts). Los mismos campos que el formulario del ADMIN, pero el login
// y la contraseña son obligatorios, con confirmación.
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent } from '@ionic/angular';
import { Data, RdvMedecinsApi } from '../api/rdvmedecins-api';
import { InputField } from '../components/input-field';
import { PersonFields } from '../components/person-fields';
import { FormSubmission } from '../components/form-submission';
import { Messages } from '../state/messages';
import { Translations } from '../i18n/translations';

// longitud mínima de una contraseña elegida por un paciente: el mismo valor
// que en el servidor (que también devuelve {min} con el error PASSWORD_TOO_SHORT)
const minPassword = '6';

@Component({
  selector: 'app-register',
  imports: [IonContent, IonButton, InputField, PersonFields],
  templateUrl: './register.html',
})
export class RegisterPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  readonly t = inject(Translations).t;
  readonly submission = new FormSubmission(this.messages);

  readonly form = signal<Data>({
    title: 'Mr',
    firstName: '',
    lastName: '',
    login: '',
    password: '',
    confirmation: '',
  });

  // los parámetros del mensaje de ayuda Y de los errores de contraseña
  readonly passwordParams = computed(() => ({ min: minPassword, ...this.submission.params() }));

  text(field: string): string {
    return String(this.form()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.form.update((f) => ({ ...f, [field]: value }));
    this.submission.clearError(field);
  }

  backToLogin(): void {
    void this.router.navigateByUrl('/login');
  }

  async create(): Promise<void> {
    let login = '';
    const succeeded = await this.submission.submit(async () => {
      login = await this.api.register(this.form());
    });
    if (succeeded) {
      // de vuelta a la pantalla de inicio de sesión, con el login rellenado previamente
      this.messages.flash({ key: 'REGISTRATION.DONE', params: { login } });
      void this.router.navigate(['/login'], { queryParams: { login } });
    } else if (this.messages.error()?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
      // pase expirado (15 minutos): de vuelta al captcha
      this.messages.flash({ success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
      this.backToLogin();
    }
  }
}

Creación de una cuenta de paciente, accesible con el pase emitido por la pantalla de inicio de sesión (véase [registrationGuard] en [app.routes.ts]).

  • línea 23: la longitud mínima de la contraseña; para el mensaje de ayuda: el mismo valor que el servidor (que también lo devuelve con el error [PASSWORD_TOO_SHORT]);
  • Línea 47: los parámetros del mensaje de ayuda y del error de la contraseña ([{{min}}]): los parámetros del servidor, si los hay, tienen prioridad;
  • Líneas 62–76: la creación. Si tiene éxito: vuelve a la pantalla de inicio de sesión, con el nombre de usuario rellenado previamente ([/login?login=...]: [queryParams] construye el parámetro), junto con un mensaje emergente. Si falla porque el pase ha expirado (15 minutos): vuelve al CAPTCHA. Cualquier otro error permanece mostrado debajo de los campos.

11.13.13. src/app/pages/register.html

<!-- ======================================================================
     register.html - "Create a patient account"
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t('REGISTRATION.TITLE') }}</h1>
  <p class="intro">{{ t('REGISTRATION.INTRO') }}</p>

  <app-person-fields
    [values]="form()"
    [errors]="submission.errors()"
    (fieldChange)="update($event.field, $event.value)"
  />

  <h3>{{ t('PERSONS.ACCOUNT_SECTION') }}</h3>
  <app-input-field
    label="PERSONS.LOGIN_LABEL"
    autocomplete="username"
    [maxLength]="30"
    [value]="text('login')"
    (valueChange)="update('login', $event)"
    [error]="submission.errors()['login']"
    help="REGISTRATION.LOGIN_HELP"
  />
  <app-input-field
    label="PERSONS.PASSWORD_LABEL"
    autocomplete="new-password"
    [secret]="true"
    [maxLength]="72"
    [value]="text('password')"
    (valueChange)="update('password', $event)"
    [error]="submission.errors()['password']"
    [params]="passwordParams()"
    help="REGISTRATION.PASSWORD_HELP"
  />
  <app-input-field
    label="ACCOUNT.CONFIRMATION_LABEL"
    autocomplete="new-password"
    [secret]="true"
    [maxLength]="72"
    [value]="text('confirmation')"
    (valueChange)="update('confirmation', $event)"
    [error]="submission.errors()['confirmation']"
  />

  <div class="buttons">
    <ion-button shape="round" [disabled]="submission.inProgress()" (click)="create()">
      {{ t('REGISTRATION.SUBMIT') }}
    </ion-button>
    <ion-button shape="round" fill="outline" (click)="backToLogin()">
      {{ t('REGISTRATION.BACK_TO_LOGIN') }}
    </ion-button>
  </div>
</ion-content>
  • líneas 16–44: una cuenta NUEVA: [autocomplete="new-password"] indica al administrador de contraseñas que sugiera una contraseña segura y la guarde.

11.13.14. src/app/pages/patient-area.ts

// =========================================================================
// src/app/pages/patient-area.ts - "Mi área" (/my-area, rol USER)
// -------------------------------------------------------------------------
// La pantalla de inicio del paciente, justo después de iniciar sesión:
//   - dos opciones: [Administrar mi cuenta] y [Ver una agenda];
//   - su próxima cita, si la hay, con los medios para cancelarla.
// =========================================================================

import { Component, inject, resource } from '@angular/core';
import { Router } from '@angular/router';
import {
  IonButton, IonCard, IonCardContent, IonCardHeader, IonCardTitle, IonContent, IonIcon, IonItem, IonLabel,
  IonSpinner,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { calendar, personCircle } from 'ionicons/icons';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { label, Appointment } from '../api/types';
import { Confirmation } from '../components/confirmation';
import { Cache, reloadAfterInvalidation } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { timeRange, longDay } from '../formatting';
import { Translations } from '../i18n/translations';
import { scheduleUrl } from './schedule';

@Component({
  selector: 'app-patient-area',
  imports: [
    IonContent, IonCard, IonCardHeader, IonCardTitle, IonCardContent, IonItem, IonLabel, IonIcon, IonButton,
    IonSpinner,
  ],
  templateUrl: './patient-area.html',
  styleUrl: './patient-area.scss',
})
export class PatientAreaPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly confirmation = inject(Confirmation);
  private readonly translations = inject(Translations);
  readonly t = this.translations.t;
  readonly label = label;
  readonly timeRange = timeRange;

  readonly area = resource({
    loader: () => this.cache.read('my-area', () => this.api.myArea()),
  });

  constructor() {
    addIcons({ calendar, personCircle });
    reloadAfterInvalidation(this.area);
    reportErrors(this.area);
  }

  // "Monday, October 5, 2026, 8:00 - 8:20"
  when(a: Appointment): string {
    return `${longDay(a.day, this.translations.language())}, ${timeRange(a.slot)}`;
  }

  goTo(url: string): void {
    void this.router.navigateByUrl(url);
  }

  // la agenda del médico en ese día: el paciente ve su nombre en ella
  seeInSchedule(a: Appointment): void {
    this.goTo(scheduleUrl(a.doctor.id, a.day));
  }

  async cancel(appointmentId: number): Promise<void> {
    if (!(await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM'))) return;
    try {
      await this.api.cancelAppointment(appointmentId);
      this.messages.showSuccess('SCHEDULE.CANCELLED');
    } catch (e) {
      this.messages.showApiError(e);
    }
    // el área Y las agendas han cambiado (el área se lee de nuevo: reloadAfterInvalidation)
    this.cache.invalidate('my-area');
    this.cache.invalidate('schedule');
  }
}

El área del paciente: dos opciones y su próxima cita.

  • líneas 46–48: el panel del paciente, tomado de la caché;
  • líneas 57–59: «martes, 13 de octubre de 2026, 8:00–8:20»;
  • líneas 66–68: la agenda del médico para ese día: el paciente ve allí su nombre;
  • líneas 70–81: cancelación de la cita del paciente: el área Y las agendas han cambiado.

11.13.15. src/app/pages/patient-area.html

<!-- ======================================================================
     patient-area.html - "My area"
     ====================================================================== -->

<ion-content class="ion-padding">
  @if (area.hasValue()) {
    @let e = area.value();
    <h1>{{ t('AREA.HELLO', { name: label(e.patient) }) }}</h1>

    <!-- dos "tarjetas" de opciones, que se tocan para abrir una pantalla;
         detail: el chevrón > a la derecha -->
    <ion-card>
      <ion-item [button]="true" [detail]="true" lines="none" (click)="goTo('/my-account')">
        <ion-icon slot="start" name="person-circle" color="primary" />
        <ion-label class="ion-text-wrap">
          <h2>{{ t('AREA.MANAGE_ACCOUNT') }}</h2>
          <p>{{ t('AREA.MANAGE_ACCOUNT_HELP') }}</p>
        </ion-label>
      </ion-item>
    </ion-card>
    <ion-card>
      <ion-item [button]="true" [detail]="true" lines="none" (click)="goTo('/schedule')">
        <ion-icon slot="start" name="calendar" color="primary" />
        <ion-label class="ion-text-wrap">
          <h2>{{ t('AREA.VIEW_SCHEDULE') }}</h2>
          <p>{{ t('AREA.VIEW_SCHEDULE_HELP') }}</p>
        </ion-label>
      </ion-item>
    </ion-card>

    <ion-card>
      <ion-card-header>
        <ion-card-title>{{ t('AREA.MY_APPOINTMENT') }}</ion-card-title>
      </ion-card-header>
      <ion-card-content>
        <!-- normalmente solo una (regla "una cita próxima a la vez"),
             pero la pantalla puede mostrar varias -->
        @for (a of e.appointments; track a.id) {
          <div class="when">{{ when(a) }}</div>
          <div>{{ label(a.doctor) }}</div>
          <div class="buttons">
            <ion-button fill="clear" (click)="seeInSchedule(a)">{{ t('AREA.SEE_IN_SCHEDULE') }}</ion-button>
            <ion-button fill="outline" shape="round" color="danger" (click)="cancel(a.id)">
              {{ t('AREA.CANCEL_APPOINTMENT') }}
            </ion-button>
          </div>
        } @empty {
          <p class="none">{{ t('AREA.NO_APPOINTMENT') }}</p>
        }
      </ion-card-content>
    </ion-card>
  } @else if (area.isLoading()) {
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  }
</ion-content>
  • línea 7: [@let]: una variable de plantilla, para evitar repetir [area.value()];
  • líneas 12–29: dos opciones: tarjetas que se tocan para abrir una pantalla. [ion-item] y [button] responden al tacto; [detail] agrega la flecha > a la derecha;
  • líneas 38–49: la cita y dos botones: ver la agenda del médico para ese día, cancelar; o, si no hay ninguna cita ([@empty]), un mensaje.

11.13.16. src/app/pages/patient-area.scss

// =========================================================================
// patient-area.scss - los estilos de "Mi área"
// =========================================================================

ion-card {
  margin: 0 0 12px;
}

// los íconos de las opciones, más grandes
ion-item ion-icon[slot='start'] {
  font-size: 32px;
}

ion-item h2 {
  font-weight: 500;
}

ion-card-title {
  font-size: 19px;
}

.when {
  font-weight: 600;
  color: var(--ion-text-color, #000);
}

.none {
  color: var(--ion-color-medium);
}

Tarjetas sin márgenes laterales (la pantalla ya tiene los suyos), íconos más grandes para las opciones y la fecha de la cita en negrita.

11.13.17. src/app/pages/my-account.ts

// =========================================================================
// src/app/pages/my-account.ts - "Administrar mi cuenta" (/my-account, rol USER)
// -------------------------------------------------------------------------
// Dos formularios independientes:
//   1. la actualización (identidad, login, nueva contraseña opcional);
//   2. la eliminación de la cuenta, que también cancela sus citas.
// Ambos exigen la contraseña ACTUAL (verificada por el servidor).
// Dos formularios, por lo tanto dos FormSubmission (dos conjuntos de errores). Como
// para el formulario de personas, la actualización solo se muestra una vez
// leída la cuenta, y empieza con sus valores.
// =========================================================================

import { Component, inject, linkedSignal, resource, signal } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonCard, IonCardContent, IonContent, IonSpinner } from '@ionic/angular';
import { Data, RdvMedecinsApi } from '../api/rdvmedecins-api';
import { InputField } from '../components/input-field';
import { PersonFields } from '../components/person-fields';
import { Confirmation } from '../components/confirmation';
import { FormSubmission } from '../components/form-submission';
import { Cache } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { Session } from '../state/session';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-my-account',
  imports: [IonContent, IonCard, IonCardContent, IonButton, IonSpinner, InputField, PersonFields],
  templateUrl: './my-account.html',
  styleUrl: './my-account.scss',
})
export class MyAccountPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly session = inject(Session);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly confirmation = inject(Confirmation);
  readonly t = inject(Translations).t;

  // ==================================================== 1. la actualización
  // se lee de nuevo en cada visita, sin caché: su versión debe estar al día
  readonly account = resource({ loader: () => this.api.myAccount() });
  readonly editing = new FormSubmission(this.messages);
  readonly form = linkedSignal<Data>(() => {
    if (!this.account.hasValue()) return {};
    const a = this.account.value();
    return {
      title: a.title,
      firstName: a.firstName,
      lastName: a.lastName,
      login: a.login,
      password: '',
      confirmation: '',
      currentPassword: '',
      version: a.version,
    };
  });

  // ==================================================== 2. la eliminación
  readonly deletion = new FormSubmission(this.messages);
  readonly deletePassword = signal('');

  constructor() {
    reportErrors(this.account);
  }

  text(field: string): string {
    return String(this.form()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.form.update((f) => ({ ...f, [field]: value }));
    this.editing.clearError(field);
  }

  back(): void {
    void this.router.navigateByUrl('/my-area');
  }

  async save(): Promise<void> {
    const succeeded = await this.editing.submit(async () => {
      // el servidor ha emitido un token NUEVO (nombre, login): la barra superior debe seguirlo
      this.session.update(await this.api.editMyAccount(this.form()));
      this.messages.flash({ key: 'MY_ACCOUNT.UPDATED' });
    });
    if (succeeded) {
      this.cache.invalidate('my-area');
      this.back();
    } else {
      // nunca una contraseña dejada en el campo tras un envío rechazado;
      // el valor se cambia SIN pasar por update(), para no borrar
      // el error que el servidor acaba de asociarle
      this.form.update((f) => ({ ...f, currentPassword: '' }));
    }
  }

  changeDeletePassword(value: string): void {
    this.deletePassword.set(value);
    this.deletion.clearError('currentPassword');
  }

  async deleteAccount(): Promise<void> {
    if (!(await this.confirmation.ask('MY_ACCOUNT.DELETE_CONFIRM'))) return;
    const succeeded = await this.deletion.submit(() => this.api.deleteMyAccount(this.deletePassword()));
    if (succeeded) {
      // primero el mensaje: se mostrará en la pantalla de inicio de sesión, adonde
      // las guardias nos llevan apenas la sesión queda vacía
      this.messages.flash({ key: 'MY_ACCOUNT.DELETED' });
      this.session.forget(true); // el servidor ha eliminado la cookie del token
    }
  }
}

«Administrar mi cuenta»: dos formularios independientes, cada uno con su propio [FormSubmission].

  • Línea 43: la cuenta, que se vuelve a leer en cada visita, sin caché (su versión debe estar actualizada);
  • Líneas 45–58: la entrada de datos comienza con los valores de la cuenta, una vez que se ha leído la cuenta;
  • líneas 81–96: la edición. El servidor devuelve al usuario con la información actualizada (y un nuevo token en su cookie): la sesión se actualiza y el nombre que se muestra en el menú se actualiza en consecuencia. Tras un intento fallido de inicio de sesión, la contraseña actual se borra del campo, sin borrar el mensaje de error que el servidor acaba de asociarle;
  • líneas 103–112: eliminación de la cuenta, después de una confirmación. Primero, el mensaje (un mensaje emergente); luego se borra la sesión y los guardias muestran la pantalla de inicio de sesión, junto con el mensaje.

11.13.18. src/app/pages/my-account.html

<!-- ======================================================================
     my-account.html - "Manage my account"
     ====================================================================== -->

<ion-content class="ion-padding">
  <!-- 1. la actualización -->
  <ion-card>
    <ion-card-content>
      <h1>{{ t('MY_ACCOUNT.TITLE') }}</h1>
      @if (account.hasValue()) {
        <app-person-fields
          [values]="form()"
          [errors]="editing.errors()"
          (fieldChange)="update($event.field, $event.value)"
        />
        <h3>{{ t('PERSONS.ACCOUNT_SECTION') }}</h3>
        <app-input-field
          label="PERSONS.LOGIN_LABEL"
          autocomplete="username"
          [maxLength]="30"
          [value]="text('login')"
          (valueChange)="update('login', $event)"
          [error]="editing.errors()['login']"
        />
        <app-input-field
          label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
          autocomplete="new-password"
          [secret]="true"
          [maxLength]="72"
          [value]="text('password')"
          (valueChange)="update('password', $event)"
          [error]="editing.errors()['password']"
          [params]="editing.params()"
          help="PERSONS.PASSWORD_HELP_EDIT"
        />
        <app-input-field
          label="ACCOUNT.CONFIRMATION_LABEL"
          autocomplete="new-password"
          [secret]="true"
          [maxLength]="72"
          [value]="text('confirmation')"
          (valueChange)="update('confirmation', $event)"
          [error]="editing.errors()['confirmation']"
        />
        <app-input-field
          label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
          autocomplete="current-password"
          [secret]="true"
          [maxLength]="72"
          [value]="text('currentPassword')"
          (valueChange)="update('currentPassword', $event)"
          [error]="editing.errors()['currentPassword']"
          help="MY_ACCOUNT.CURRENT_PASSWORD_HELP"
        />
        <div class="buttons">
          <ion-button shape="round" [disabled]="editing.inProgress()" (click)="save()">
            {{ t('PERSONS.SAVE') }}
          </ion-button>
          <ion-button shape="round" fill="outline" (click)="back()">{{ t('MY_ACCOUNT.BACK') }}</ion-button>
        </div>
      } @else {
        <div class="ion-text-center ion-padding"><ion-spinner /></div>
      }
    </ion-card-content>
  </ion-card>

  <!-- 2. la eliminación: un formulario con un solo campo -->
  <ion-card class="danger">
    <ion-card-content>
      <h1>{{ t('MY_ACCOUNT.DELETE_TITLE') }}</h1>
      <p class="help">{{ t('MY_ACCOUNT.DELETE_HELP') }}</p>
      <app-input-field
        label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
        autocomplete="current-password"
        [secret]="true"
        [maxLength]="72"
        [value]="deletePassword()"
        (valueChange)="changeDeletePassword($event)"
        [error]="deletion.errors()['currentPassword']"
      />
      <ion-button shape="round" color="danger" [disabled]="deletion.inProgress()" (click)="deleteAccount()">
        {{ t('MY_ACCOUNT.DELETE_SUBMIT') }}
      </ion-button>
    </ion-card-content>
  </ion-card>
</ion-content>
  • líneas 7–65: la edición, en una tarjeta; el formulario aparece solo después de haber leído la cuenta;
  • líneas 68–85: la eliminación, en una tarjeta con borde rojo: un formulario de un solo campo.

11.13.19. src/app/pages/my-account.scss

// =========================================================================
// my-account.scss - los estilos de "Administrar mi cuenta"
// =========================================================================

ion-card {
  margin: 0 0 12px;
}

ion-card-content {
  color: var(--ion-text-color, #000);

  // los títulos, como en los demás lugares (Ionic les da otros márgenes en una tarjeta)
  h1 {
    font-size: 26px;
    margin: 8px 0 16px;
  }

  h3 {
    font-size: 15px;
    font-weight: 500;
    margin: 16px 0 12px;
  }
}

// la tarjeta de eliminación: un marco rojo, un título rojo
ion-card.danger {
  border: 1px solid #e57373;

  h1 {
    color: #d32f2f;
  }
}

Los títulos de las tarjetas ([Ionic] les da tamaños y márgenes distintos dentro de un [ion-card-content]) y el borde rojo para la eliminación.

11.13.20. src/app/pages/error-page.ts

// =========================================================================
// src/app/pages/error-page.ts - la pantalla de error: 404 (dirección desconocida)
// o 403 (rol insuficiente, véase app.routes.ts)
// -------------------------------------------------------------------------
// El código (403 o 404) lo da la propiedad data de la ruta.
// =========================================================================

import { Component, inject, input } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent } from '@ionic/angular';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-error-page',
  imports: [IonContent, IonButton],
  templateUrl: './error-page.html',
  styles: `
    .error {
      color: #d32f2f;
    }
  `,
})
export class ErrorPage {
  private readonly router = inject(Router);
  readonly t = inject(Translations).t;
  readonly code = input(404);

  // "/": la guardia redirige a la página de inicio del rol (o al inicio de sesión)
  home(): void {
    void this.router.navigateByUrl('/');
  }
}
1
2
3
4
5
6
7
8
9
<!-- ======================================================================
     error-page.html - la pantalla de error (403, 404)
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1 class="error">{{ t('ERROR_PAGE.TITLE') }} {{ code() }}</h1>
  <p>{{ t(code() === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND') }}</p>
  <ion-button shape="round" (click)="home()">{{ t('ERROR_PAGE.BACK') }}</ion-button>
</ion-content>

La página de error: 404 (dirección desconocida) o 403 (permisos insuficientes). El código es la propiedad [data] de la ruta, asignada a la entrada [code] (línea 26 de [error-page.ts]). «Volver a la página de inicio» lleva a [/], que el guardia redirige a la página de inicio del rol.

11.14. Flutter e Ionic: una comparación

Ambos clientes hacen exactamente lo mismo, con la misma arquitectura, archivo por archivo. Vale la pena señalar algunas diferencias:

  • la cookie del token: el cliente [Flutter] tuvo que administrarla por sí mismo en el teléfono (un cliente HTTP que lee [Set-Cookie] y escribe [Cookie]); el cliente [Ionic] se apoya en el navegador web y en el código nativo de [Android] ([CapacitorHttp]) en el teléfono;
  • Estado y actualizaciones: los [ChangeNotifier] de [Flutter] notifican a sus oyentes ([notifyListeners()]) y los widgets se reconstruyen; las señales de [Angular] saben QUIÉN las lee y actualizan solo lo que depende de ellas. Las señales calculadas ([computed]), las señales vinculadas ([linkedSignal]) y los recursos ([resource]) sustituyen una gran parte de [initState], [didUpdateWidget] y [FutureBuilder];
  • Dirección: en ambos casos, todo el estado de la pantalla está contenido en la dirección; el enrutador de [Angular] la pasa directamente a las entradas del componente ([withComponentInputBinding]);
  • componentes prediseñados: [Ionic] proporciona el menú permanente en la pantalla grande ([ion-split-pane]), las ventanas ([ion-modal], [ion-popover], [AlertController]) y el calendario ([ion-datetime]); [Flutter] proporciona los suyos ([NavigationRail], [showDatePicker]...), pero allí la ventana de reserva vinculada a la dirección se dibujó a mano;
  • La web: el cliente [Ionic] ES una aplicación web (basada en HTML, unos cientos de kilobytes); el cliente [Flutter], compilado para la web, dibuja cada píxel en un lienzo (canvas) y primero descarga su motor de renderizado (unos megabytes). En cambio, en el teléfono, la aplicación [Flutter] se compila a código máquina, mientras que la aplicación [Ionic] se ejecuta dentro del [WebView], el motor del navegador.