Skip to content

10. Estudo de caso: o cliente React da aplicação RdvMedecins

10.1. O problema

A aplicação [RdvMedecins] permite agendar consultas em um consultório médico. O curso de [NestJS] a escreveu como uma aplicação HTML, em que o servidor gerava as páginas. Aqui, escrevemos a aplicação cliente [React]: as MESMAS páginas, geradas no navegador a partir dos dados JSON do servidor descrito no capítulo “O servidor RdvMedecins, uma caixa-preta”.

O cliente deve oferecer tudo o que a aplicação HTML oferecia:

  • uma página de login, protegida por um CAPTCHA, com a opção de criar uma conta de paciente;
  • a agenda de um médico para um dia determinado, com reserva de consultas (janela de seleção de paciente) e cancelamento;
  • para o administrador, o gerenciamento de médicos e clientes (listar, adicionar, editar, excluir);
  • para o paciente, um painel pessoal (mostrando as consultas futuras, que ele pode cancelar) e o gerenciamento da conta;
  • dois idiomas: francês e inglês;
  • URLs únicas ([/schedule?doctorId=1&day=...]), que podem ser recarregadas, adicionadas aos favoritos e percorridas com os botões Voltar/Avançar do navegador.

10.2. Instalação e execução

O servidor JSON deve estar instalado e em execução (veja o capítulo “O servidor RdvMedecins, uma caixa-preta”). Para usar o cliente em um navegador, você não precisa do modo de teste do CAPTCHA: pode deixar o campo [CAPTCHA_TEST] em branco no arquivo [.env] do servidor.

Em uma janela de console aberta na pasta [rdvmedecins-react]:

npm install
npm start

depois abra http://localhost:5173 em um navegador. As contas de demonstração são listadas na página de login (senha = login).

Os exemplos também usam a porta 5173: primeiro, pare o exemplo em execução ([Ctrl-C]). Você também pode iniciar o cliente em outra porta: [npm start -- --port 5174].

10.3. Usando a aplicação

10.3.1. A página de login

Image

Uma senha incorreta: a mensagem aparece na parte inferior da página, e uma nova imagem é exibida (cada imagem só pode ser usada uma vez):

Image

10.3.2. A agenda, vista pelo administrador e pelos médicos

Autenticado como [admin], você é levado à agenda:

Image

Selecione um médico e um dia e clique em “View schedule”. A URL passa a ser [/schedule?doctorId=1&day=2026-10-05]:

Image

“Book” abre a janela de reserva. A URL passa a ser [/schedule?doctorId=1&day=2026-10-05&book=3]: recarregar a página (F5) reabre a mesma janela.

Image

A consulta é salva:

Image

“Cancel” pede confirmação:

Image

Um médico é levado diretamente à SUA PRÓPRIA agenda do dia:

Image

10.3.3. O portal do paciente

Um paciente ([martin]) acessa “My area”:

Image

Em uma agenda, ele vê “Booked” junto aos horários de consulta de outros pacientes:

Image

Ele marca uma consulta para si mesmo sem selecionar um paciente:

Image

Sua consulta aparece sob o seu nome; o botão “Book” não está mais disponível (apenas uma consulta futura), e uma mensagem explica o motivo:

Image

Seu painel mostra isto:

Image

“Manage my account”: qualquer alteração exige a senha atual; os erros vêm do servidor:

Image

Se ele digitar o endereço /doctors, que é reservado ao administrador:

Image

10.3.4. Gerenciamento de médicos e clientes

Image

Um formulário preenchido incorretamente:

Image

Uma inclusão bem-sucedida:

Image

Um homônimo:

Image

O pedido de remoção de um médico que tem consultas é negado:

Image

10.3.5. Criação de uma conta

Na página de login, digite o CAPTCHA e clique em “Create a patient account”. O formulário foi preenchido incorretamente e foi rejeitado pelo servidor:

Image

Depois que a conta é criada, volte à página de login; os campos de login já vêm preenchidos:

Image

10.3.6. Em francês

Os botões FR / EN traduzem a página na hora, sem fazer nenhuma requisição ao servidor; o título da aba do navegador também é traduzido:

Image

10.3.7. Sessão expirada, endereço desconhecido

Se o token expira (ou se o cookie é apagado), a requisição seguinte recebe uma resposta 401; o cliente é redirecionado para a página de login:

Image

Um endereço desconhecido:

Image

10.4. Arquitetura do cliente

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

Image

A tabela a seguir compara a aplicação HTML do curso [NestJS] com este cliente:

Aplicação HTML (NestJS)
Cliente React
O servidor gera cada página ([res.render])
O servidor retorna JSON; os componentes de [src/pages/] geram as páginas
[views/layout.hbs] e suas views parciais
[Layout.tsx] e os componentes de [src/components/]
as rotas do controller ([@Controller('schedule')])
rotas do cliente ([routes.tsx]); o servidor tem apenas rotas /api/...
[JwtAuthGuard] e [RolesGuard] redirecionam para /login ou para uma página 403
guards do roteador; o servidor mantém seus próprios guards, que retornam 401 ou 403
mensagem flash em um cookie
mensagem flash em um store, [useMessages]
dicionários lidos pelo servidor, helper [{{t}}]
dicionários no cliente, [i18next]; o servidor retorna apenas chaves
idioma armazenado em um cookie
idioma armazenado no [localStorage]
formulário rejeitado: o servidor recarrega a página
formulário rejeitado: resposta 400/409; o cliente exibe os erros abaixo dos campos
Janela de confirmação: um pequeno script, [public/js/app.js]
um store e um componente, [ConfirmDialog]
A aplicação funciona sem JavaScript
A aplicação É JavaScript

Os clientes [Vue.js] e [Angular] das lições anteriores têm exatamente a mesma estrutura: os "stores" do [Pinia] e os serviços do [Angular] são aqui stores [Zustand]; os "composables" são os hooks, e as views são as páginas.

Todos os arquivos do cliente estão listados abaixo. Eles são amplamente comentados; seus comentários fazem parte do curso.

10.4.1. Configuração do projeto

10.4.1.1. package.json

{
  "name": "rdvmedecins-react",
  "private": true,
  "version": "1.0.0",
  "description": "React client of the medical appointment booking application [RdvMedecins] - client of the JSON server [rdvmedecins-nestjs-json]",
  "type": "module",
  "scripts": {
    "start": "vite",
    "build": "tsc --noEmit && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "@tanstack/react-query": "^5.104.0",
    "bootstrap": "^5.3.8",
    "i18next": "^26.4.2",
    "react": "^19.3.0",
    "react-dom": "^19.3.0",
    "react-i18next": "^17.0.15",
    "react-router": "^8.4.0",
    "zustand": "^5.0.15"
  },
  "devDependencies": {
    "@types/react": "^19.2.18",
    "@types/react-dom": "^19.2.7",
    "@vitejs/plugin-react": "^6.1.1",
    "typescript": "~6.0.2",
    "vite": "^8.3.0"
  }
}
  • Linhas 8–10: [npm start] inicia o servidor de desenvolvimento; [npm run build] verifica os tipos ([tsc --noEmit], veja abaixo) E ENTÃO gera a versão de produção; [npm run preview] serve a versão compilada para testes;
  • Linhas 12–21: as bibliotecas usadas pela aplicação: [React], [React Router], [TanStack Query], [Zustand], [i18next], [Bootstrap];
  • Linhas 22–28: ferramentas de desenvolvimento: [Vite] e sua extensão para [React], [TypeScript] e os tipos do [React].

Não há biblioteca de formulários ([React Hook Form], exemplo 08): como no exemplo 25, todas as regras de validação das entradas são verificadas pelo servidor, e o cliente se limita a exibir os resultados.

10.4.1.2. vite.config.ts

// =========================================================================
// vite.config.ts - a ferramenta de build do cliente
// -------------------------------------------------------------------------
//   - npm start      : o servidor de desenvolvimento (http://localhost:5173),
//                      que encaminha /api/... ao servidor JSON (porta 8080);
//   - npm run build  : a aplicação compilada, em dist/;
//   - npm run preview: serve dist/ (com o mesmo proxy), para experimentar.
// =========================================================================

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

// o proxy: páginas e API têm assim a MESMA origem (localhost:5173); o
// cookie httpOnly do token trafega sem nenhuma configuração, e sem CORS
const proxy = { '/api': 'http://localhost:8080' };

export default defineConfig({
  plugins: [react()],
  server: { port: 5173, proxy },
  preview: { port: 4173, proxy },
  // em produção: o código das bibliotecas (React, React Router,
  // i18next...) em UM arquivo separado, "libraries-XXXX.js". Ele raramente
  // muda: o navegador o mantém em cache de uma versão para a seguinte.
  build: {
    rolldownOptions: {
      output: { codeSplitting: { groups: [{ name: 'libraries', test: /node_modules/ }] } },
    },
  },
});
  • Linha 15: o proxy do Exemplo 22: as requisições /api/... são encaminhadas para o servidor JSON;
  • linha 19: o servidor de desenvolvimento;
  • linha 20: o servidor de [npm run preview], com o mesmo proxy;
  • linhas 24–28: em produção, o código das bibliotecas é armazenado em um arquivo separado (veja o capítulo “Implantação”).

10.4.1.3. tsconfig.json

{
  "compilerOptions": {
    "target": "ES2023",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["vite/client"],
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src", "vite.config.ts"]
}
  • linha 8: o JSX é compilado em chamadas a [jsx(...)], que são importadas automaticamente: não é necessário [import React] em cada arquivo;
  • linha 9: o modo estrito do [TypeScript];
  • linha 14: uma importação usada apenas para tipos é escrita como [import type]: ela desaparece durante a compilação;
  • linha 15: só é permitida a sintaxe [TypeScript] que pode simplesmente ser APAGADA para obter [JavaScript] (sem [enum], sem parâmetros de propriedade): é isso que o [Vite] faz, e ele não verifica tipos;
  • Linha 16: importação dos arquivos JSON (os dicionários);
  • linha 18: [TypeScript] não gera nenhum arquivo: ele apenas VERIFICA ([tsc --noEmit]); [Vite] é quem compila.

10.4.2. Inicialização da aplicação

10.4.2.1. index.html

<!doctype html>
<!--
  index.html - A página da aplicação (Single Page Application).
  O servidor nunca envia outra: todo o resto é construído no
  navegador pelo React, em <div id="root">. lang e title são atualizados
  pela aplicação conforme o idioma e a página exibida.
-->
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>RdvMedecins</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
</head>
<body>
  <div id="root"></div>
  <!-- sem JavaScript, uma aplicação React não consegue exibir nada: avisamos isso -->
  <noscript>RdvMedecins requires JavaScript. / RdvMedecins a besoin de JavaScript.</noscript>
  <script type="module" src="/src/main.tsx"></script>
</body>
</html>
  • linha 16: o elemento no qual o [React] exibe a aplicação;
  • linha 18: sem [JavaScript], uma aplicação [React] não consegue exibir nada: isso é informado;
  • linha 19: o ponto de entrada da aplicação. Durante o desenvolvimento, o [Vite] compila [main.tsx] sob demanda; em produção, essa linha é substituída pelo arquivo compilado (veja o capítulo “Implantação”).

10.4.2.2. src/main.tsx

// =========================================================================
// main.tsx - a inicialização da aplicação
// -------------------------------------------------------------------------
//   - as folhas de estilo (Bootstrap, styles.css);
//   - i18next (francês e inglês);
//   - TanStack Query, que lê os dados do servidor: suas requisições que falham
//     exibem sua mensagem no painel de erros, em UM só lugar
//     (exceto as que declaram tratar o próprio erro:
//     meta.errorHandled);
//   - o roteador, que exibe a página do endereço atual.
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryCache, QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { RouterProvider } from 'react-router/dom';
import 'bootstrap/dist/css/bootstrap.min.css';
import './styles.css';
import './i18n/i18n';
import { useMessages } from './stores/messages';
import { router } from './router';

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (!query.meta?.errorHandled) {
        useMessages.getState().showApiError(error);
      }
    },
  }),
  defaultOptions: {
    queries: {
      retry: false, // um erro é exibido imediatamente, sem nova tentativa
      refetchOnWindowFocus: false, // nenhuma releitura ao voltar para a aba
    },
  },
});

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  </StrictMode>,
);
  • linhas 17–19: as folhas de estilo, seguidas da configuração do [i18next], que é executada uma única vez, quando o módulo é carregado;
  • linhas 23–37: o cliente do [TanStack Query] (Exemplo 24), com dois ajustes:
    • linhas 24–30: [onError] é chamado para CADA requisição que falha: sua mensagem de erro é exibida na área de erros, em um único local. Uma consulta que trata seu próprio erro o declara em seus metadados: [meta: { errorHandled: true }];
    • linhas 33–34: por padrão, o [TanStack Query] repete três vezes uma requisição que falhou e recarrega os dados quando você volta à aba: aqui, um erro é exibido imediatamente, e os dados só mudam quando solicitados;
  • linha 42: o roteador (construído em [router.ts]) exibe a página correspondente ao endereço atual.

10.4.2.3. src/router.ts

// =========================================================================
// router.ts - o roteador da aplicação e o que depende dele
// -------------------------------------------------------------------------
// O roteador é criado aqui, fora de qualquer componente, para que dois
// mecanismos possam usá-lo:
//   1. a resposta 401 de uma requisição protegida (sessão expirada): o
//      usuário é esquecido, a mensagem é preparada e vamos para a
//      página de login (veja api/client.ts);
//   2. as mensagens "flash": ao final de CADA navegação, as mensagens
//      da página anterior desaparecem, as deixadas para a próxima
//      página aparecem (veja stores/messages.ts).
// =========================================================================

import { createBrowserRouter } from 'react-router';
import { routes } from './routes';
import { whenSessionExpired } from './api/client';
import { useSession } from './stores/session';
import { useMessages } from './stores/messages';

export const router = createBrowserRouter(routes);

// 1. a sessão expirada
whenSessionExpired(() => {
  useSession.getState().forget();
  useMessages.getState().flash('error', 'ERRORS.SESSION_EXPIRED');
  router.navigate('/login');
});

// 2. subscribe: a função é chamada a cada mudança do estado do
// roteador. Uma navegação está CONCLUÍDA quando não está mais em andamento
// (idle) e o endereço mudou (cada endereço visitado tem uma chave única,
// location.key - inclusive quando só os parâmetros mudam: /schedule?...)
let locationKey = router.state.location.key;
router.subscribe((state) => {
  if (state.navigation.state === 'idle' && state.location.key !== locationKey) {
    locationKey = state.location.key;
    useMessages.getState().newPage();
  }
});
  • linha 20: o roteador, no modo “data” (exemplo 17), é criado FORA de qualquer componente: um código que não é um componente pode, assim, usá-lo ([router.navigate]);
  • linhas 23–27: o que fazer quando uma requisição protegida recebe uma resposta 401 (veja [api/client.ts]): esquecer o usuário, preparar a mensagem para a próxima página, ir para a página de login;
  • linhas 33–39: [router.subscribe(function)]: a função é chamada sempre que o estado do roteador muda. Ao final de cada navegação, as mensagens da página anterior desaparecem e as mensagens “flash” aparecem (veja [stores/messages.ts]).

10.4.2.4. src/styles.css

/* =========================================================================
   styles.css - alguns ajustes sobre o Bootstrap
   (extraídos de public/css/styles.css da aplicação HTML)
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-panel: as mensagens de erro, na parte inferior da página, sobre um fundo
   rosa claro (veja components/ErrorPanel.tsx).
   position: sticky + bottom: se a página for mais alta que a janela, o
   painel permanece colado na parte inferior da janela em vez de desaparecer abaixo da
   dobra - sem nunca cobrir o conteúdo quando a página
   é curta. z-index: acima do fundo cinza dos diálogos modais.
   pointer-events: none: o painel não contém nada clicável; se ele
   se sobrepuser a um botão, o clique passa através dele.
   ------------------------------------------------------------------------- */
.error-panel {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  pointer-events: none;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* as duas opções principais da página "Minha área" do paciente */
.option-card {
  transition: border-color 0.15s, box-shadow 0.15s;
}

.option-card:hover {
  border-color: #0d6efd;
  box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}

/* a imagem do captcha (SVG de 150 x 50 pixels), inserida por dangerouslySetInnerHTML:
   um estilo da folha global, como todos os outros */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}

A folha de estilo da aplicação HTML, reproduzida quase literalmente. O único ponto a observar é a área de erros (linhas 24–35), posicionada na parte inferior da janela quando a página é alta.

10.4.3. A camada de acesso à API

10.4.3.1. src/api/types.ts

// =========================================================================
// api/types.ts - os objetos JSON trocados com o servidor
// -------------------------------------------------------------------------
// A tradução, em interfaces TypeScript, da API descrita no capítulo
// "O servidor, uma caixa-preta". O compilador verifica assim que o cliente
// só usa campos que realmente existem.
// =========================================================================

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; // nome de exibição: "Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string;
}

// um título, um nome, um sobrenome
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// um médico ou um cliente: GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
  id: number;
  version: number; // bloqueio otimista: a ser reenviado com uma atualização
  login?: string; // somente para o ADMIN
}

// o que é enviado para criar / atualizar uma pessoa (ADMIN)
export interface PersonData extends Identity {
  login: string; // '' = valor padrão (criação) ou inalterado (atualização)
  password: string; // idem
  version?: number;
}

export interface Slot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
}

// uma linha da agenda, com os DIREITOS do usuário logado
export interface ScheduleSlot extends Slot {
  free: boolean;
  patient: Identity | null; // null: livre, ou ocupado por outro paciente
  mine: boolean; // a consulta do paciente logado
  bookable: boolean;
  appointmentId: number | null; // preenchido se o usuário puder cancelar
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string; // "yyyy-MM-dd"
  slots: ScheduleSlot[];
  info: string | null; // chave de tradução (paciente que já tem uma consulta)
}

// GET /api/my-area
export interface MyArea {
  patient: Identity;
  appointments: { id: number; day: string; slot: Slot; doctor: Person }[];
}

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

// PUT /api/my-account
export interface MyAccountUpdate extends Identity {
  login: string;
  password: string; // '' = inalterado
  confirmation: string;
  currentPassword: string;
  version: number;
}

// POST /api/register
export interface Registration extends Identity {
  login: string;
  password: string;
  confirmation: string;
}

Os objetos JSON da API, descritos no capítulo “O servidor RdvMedecins: uma caixa-preta”, traduzidos em interfaces [TypeScript]:

  • linhas 25–29: um título, um nome, um sobrenome — o que médicos, clientes e pacientes têm em comum ao marcar consultas;
  • linhas 32–36: um médico ou um cliente. [version]: o bloqueio otimista do servidor; uma modificação devolve a versão lida: se alguém modificou o registro nesse meio tempo, o servidor recusa ([ERRORS.CONCURRENT_UPDATE]);
  • linhas 54–60: uma entrada da agenda. O servidor informa os DIREITOS do usuário logado: [bookable], [appointmentId] (preenchido se o usuário pode cancelar); o cliente não precisa recalculá-los;
  • Linha 67: uma chave de tradução, para pacientes que já têm uma consulta.

10.4.3.2. src/api/api-error.ts

// =========================================================================
// api/api-error.ts - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Retirado de common/api-error.ts dos exemplos. Qualquer erro de uma requisição
// (resposta 4xx / 5xx do servidor, servidor inacessível, resposta de um proxy)
// vira um ApiError, que carrega a CHAVE de tradução da mensagem, seus
// parâmetros e o erro de cada campo de um formulário rejeitado.
// =========================================================================

export class ApiError extends Error {
  readonly statusCode: number; // 0: o servidor não respondeu
  readonly key: string; // chave de tradução: 'ERRORS.LOGIN_TAKEN'
  readonly params: Record<string, string>;
  readonly fields: Record<string, string>; // erro de cada campo

  constructor(statusCode: number, key: string, params: Record<string, string> = {}, fields: Record<string, string> = {}) {
    super(key);
    this.name = 'ApiError';
    this.statusCode = statusCode;
    this.key = key;
    this.params = params;
    this.fields = fields;
  }
}

// uma resposta de erro (4xx, 5xx) -> um ApiError
export async function fromResponse(response: Response): Promise<ApiError> {
  let body: { key?: string; params?: Record<string, string>; fields?: Record<string, string> } = {};
  try {
    const json: unknown = await response.json();
    if (typeof json === 'object' && json !== null) {
      body = json;
    }
  } catch {
    // não é JSON: não foi o nosso servidor que respondeu
  }
  return new ApiError(
    response.status,
    // sem chave: não foi o nosso servidor que respondeu, mas um proxy
    // (Vite: 500 ou 502 sem corpo JSON; nginx: 502, 504...)
    body.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR'),
    body.params,
    body.fields,
  );
}

A classe [ApiError] do Exemplo 24, sem alterações: QUALQUER erro de requisição se torna um [ApiError], que contém a chave de tradução da mensagem, seus parâmetros e o erro de cada campo em um formulário rejeitado.

10.4.3.3. src/api/client.ts

// =========================================================================
// api/client.ts - TODAS as requisições à API passam por aqui
// -------------------------------------------------------------------------
// Retirado de common/api.ts dos exemplos, com uma novidade: o tratamento
// centralizado da resposta 401.
//
// Um 401 pode acontecer a qualquer momento: o token expirou (2 horas), a
// conta foi excluída, o servidor foi reiniciado com outra chave
// secreta... Em vez de tratar esse caso em cada componente, tratamos
// AQUI, uma única vez. Mas este arquivo não conhece nem o roteador nem as
// mensagens (não depende de nada): ele chama uma função que lhe foi dada
// na inicialização (whenSessionExpired, veja router.ts), que esquece
// o usuário e redireciona para a página de login.
//
// Algumas requisições tratam o próprio 401 (o login, GET
// /api/auth/me...): elas são "públicas" (veja rdvmedecins.api.ts).
// =========================================================================

import { fromResponse, ApiError } from './api-error';

// o que fazer quando o servidor responde 401 a uma requisição protegida
let sessionExpired: () => void = () => {};

export function whenSessionExpired(action: () => void): void {
  sessionExpired = action;
}

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

// isPublic: true para as rotas que tratam o próprio 401
export async function request<T>(method: Method, url: string, body?: unknown, isPublic = false): Promise<T> {
  let response: Response;
  try {
    response = await fetch(`/api${url}`, {
      method,
      headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
      body: body === undefined ? undefined : JSON.stringify(body),
    });
  } catch {
    // sem resposta: rede fora do ar, servidor parado
    throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
  }
  if (!response.ok) {
    const error = await fromResponse(response);
    if (error.statusCode === 401 && !isPublic) {
      sessionExpired();
    }
    throw error;
  }
  return (await response.json()) as T;
}

A função [request] do Exemplo 24, com uma novidade: a resposta 401.

  • Linhas 22–26: a função a ser chamada quando uma requisição protegida recebe uma resposta 401. Este arquivo não tem dependências (nem do roteador, nem das mensagens): [router.ts] atribui essa função a ele na inicialização. Isso evita uma dependência circular (o cliente importa o roteador, que importa as rotas, que importam as páginas, que importam o cliente...);
  • linha 31: algumas requisições tratam seus próprios erros 401: o login (senha incorreta: 401), [GET /api/auth/me] (ninguém está logado: 401)...;
  • Linhas 45–47: uma requisição protegida recebe um 401: a sessão expirou. Isso é sinalizado, ENTÃO a promise é rejeitada como em qualquer outro erro: o componente que aguarda a resposta não tem nenhuma ação específica a realizar.

10.4.3.4. src/api/rdvmedecins.api.ts

// =========================================================================
// api/rdvmedecins.api.ts - uma função por rota da API
// -------------------------------------------------------------------------
// A "camada de acesso a dados" do cliente: os componentes chamam estas
// funções tipadas, sem saber nada sobre URLs, fetch ou JSON. Se
// a API mudar, só este arquivo muda.
// Cada função retorna uma PROMISE: os componentes encadeiam as
// requisições com async / await. Em caso de falha, a promise é rejeitada
// com um ApiError (veja client.ts).
// =========================================================================

import { request } from './client';
import type {
  Schedule,
  Captcha,
  PersonData,
  Registration,
  MyAccountUpdate,
  MyAccount,
  MyArea,
  Person,
  User,
} from './types';

// /api/doctors ou /api/clients: ambos são gerenciados da mesma forma
export type PersonType = 'doctors' | 'clients';

type Empty = Record<string, never>;

export const api = {
  // ──────────────────────────────────────────────── login (rotas públicas)
  captcha: () => request<Captcha>('GET', '/captcha', undefined, true),
  me: () => request<User>('GET', '/auth/me', undefined, true),
  logIn: (login: string, password: string, captchaId: string, captcha: string) =>
    request<User>('POST', '/auth/login', { login, password, captchaId, captcha }, true),
  logOut: () => request<Empty>('POST', '/auth/logout', {}, true),

  // ──────────────────────────────────────────────── criação de conta (público)
  registrationAccess: (captchaId: string, captcha: string) =>
    request<Empty>('POST', '/register/access', { captchaId, captcha }, true),
  registrationAccessStatus: () => request<{ valid: boolean }>('GET', '/register/access', undefined, true),
  register: (data: Registration) => request<{ login: string }>('POST', '/register', data, true),

  // ──────────────────────────────────────────────── agenda e consultas
  // doctorId null: para um médico logado, a agenda DELE
  schedule(doctorId: number | null, day: string) {
    const params = new URLSearchParams({ day });
    if (doctorId !== null) {
      params.set('doctorId', String(doctorId));
    }
    return request<Schedule>('GET', `/schedule?${params}`);
  },
  book: (day: string, slotId: number, clientId: number | null) =>
    request<{ id: number }>('POST', '/appointments', { day, slotId, clientId: clientId ?? undefined }),
  cancelAppointment: (appointmentId: number) => request<Empty>('DELETE', `/appointments/${appointmentId}`),

  // ──────────────────────────────────────────────── médicos e clientes
  list: (type: PersonType) => request<Person[]>('GET', `/${type}`),
  read: (type: PersonType, id: number) => request<Person>('GET', `/${type}/${id}`),
  add: (type: PersonType, data: PersonData) => request<Person>('POST', `/${type}`, data),
  edit: (type: PersonType, id: number, data: PersonData) => request<Person>('PUT', `/${type}/${id}`, data),
  remove: (type: PersonType, id: number) => request<Empty>('DELETE', `/${type}/${id}`),

  // ──────────────────────────────────────────────── a área do paciente
  myArea: () => request<MyArea>('GET', '/my-area'),
  myAccount: () => request<MyAccount>('GET', '/my-account'),
  editMyAccount: (data: MyAccountUpdate) => request<User>('PUT', '/my-account', data),
  deleteMyAccount: (currentPassword: string) => request<Empty>('DELETE', '/my-account', { currentPassword }),
};

Uma função por rota da API, tipada: os componentes chamam [api.schedule(1, '2026-10-05')] sem saber nada sobre URL ou JSON. Se a API mudar, apenas este arquivo muda.

  • linhas 32–36: as rotas de conexão, que são públicas (último parâmetro de [request]: [true]);
  • linhas 39–42: a criação de conta, em duas etapas: resolver o CAPTCHA na página de login fornece um “passe” (um cookie), que a rota [POST /api/register] exige;
  • linhas 46–52: [URLSearchParams] gera os parâmetros do endereço (e os codifica). Para um médico logado, não há [doctorId]: o servidor retorna a agenda DELE;
  • linha 54: um paciente faz uma reserva para si mesmo: sem [clientId]. [JSON.stringify] omite as propriedades [undefined];
  • linhas 58–62: médicos e clientes são tratados da mesma forma: o tipo é um parâmetro;
  • linha 28: o tipo de um objeto vazio [{}], que algumas rotas retornam.

10.4.4. Idiomas

10.4.4.1. src/i18n/i18n.ts

// =========================================================================
// i18n/i18n.ts - francês e inglês (i18next, veja o exemplo 21)
// -------------------------------------------------------------------------
// Os dicionários fr.json e en.json são os do curso NestJS
// (i18n/*.json), completados com algumas chaves específicas do cliente
// (ERRORS.SERVER_UNREACHABLE...). O servidor JSON só retorna CHAVES
// ('ERRORS.LOGIN_TAKEN'): elas são as mesmas dos dicionários.
//
// O idioma escolhido é armazenado no localStorage (uma preferência, não um
// dado sensível); na falta dele, usa-se o idioma do navegador.
// =========================================================================

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';

export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
const STORAGE_KEY = 'rdvmedecins.language';

function initialLanguage(): Language {
  try {
    const stored = localStorage.getItem(STORAGE_KEY);
    if (stored === 'fr' || stored === 'en') {
      return stored;
    }
  } catch {
    // localStorage indisponível (navegação privada estrita...): tanto faz
  }
  return navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en';
}

// a cada troca de idioma: armazená-lo e atualizar o
// atributo lang da página (leitores de tela, corretores ortográficos, hifenização)
i18n.on('languageChanged', (language) => {
  document.documentElement.lang = language;
  try {
    localStorage.setItem(STORAGE_KEY, language);
  } catch {
    // sem importância
  }
});

i18n.use(initReactI18next).init({
  // os dicionários fazem parte do código da aplicação: nenhuma requisição
  resources: { fr: { translation: fr }, en: { translation: en } },
  lng: initialLanguage(),
  fallbackLng: 'en',
  interpolation: { escapeValue: false }, // o React já escapa tudo
});

export default i18n;

A configuração do Exemplo 21:

  • linhas 22–32: o idioma armazenado ou, na falta dele, o idioma do navegador. O acesso ao [localStorage] pode falhar (navegação privada estrita): [try / catch];
  • linhas 36–43: a cada mudança de idioma, ele é salvo e o atributo [lang] da página é atualizado;
  • linha 47: os dicionários, importados como módulos, fazem parte do código compilado e não exigem requisições adicionais;
  • linha 50: o [React] já escapa tudo o que exibe: não é preciso fazer isso duas vezes.

Não há equivalente à “estratégia de título” do [Angular]: cada página declara seu título com a tag [<title>], que o [React] 19 coloca no cabeçalho do documento (veja [components/PageTitle.tsx]).

10.4.4.2. Dicionários

Os dicionários [fr.json] e [en.json] são os da aplicação HTML do curso [NestJS], acrescidos de algumas chaves específicas do cliente ([ERRORS.SERVER_UNREACHABLE]...). A sintaxe de seus parâmetros, [{{min}}], é exatamente a mesma do [i18next]. O servidor JSON retorna as mesmas chaves.

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace",
    "LOADING": "Chargement...",
    "LANGUAGE": "Langue"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {{time}}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le médecin {{name}} a été modifié.",
    "DELETED": "Le médecin {{name}} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le client {{name}} a été modifié.",
    "DELETED": "Le client {{name}} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {{minutes}} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {{min}} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client ».",
    "AUTH_REQUIRED": "Connectez-vous pour accéder à cette page.",
    "JSON_REQUIRED": "Requête refusée : le serveur attend du JSON.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas. Réessayez plus tard."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {{min}} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {{login}}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {{name}}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area",
    "LOADING": "Loading...",
    "LANGUAGE": "Language"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {{time}}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {{name}} has been added (login: {{login}}).",
    "UPDATED": "Doctor {{name}} has been updated.",
    "DELETED": "Doctor {{name}} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {{name}} has been added (login: {{login}}).",
    "UPDATED": "Patient {{name}} has been updated.",
    "DELETED": "Patient {{name}} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
    "SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
    "CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
    "DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {{minutes}} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {{min}} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\".",
    "AUTH_REQUIRED": "Please log in to access this page.",
    "JSON_REQUIRED": "Request refused: the server expects JSON.",
    "SERVER_UNREACHABLE": "The server does not respond. Please try again later."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {{min}} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {{login}}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {{name}}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

10.4.5. Os stores

10.4.5.1. src/stores/session.ts

// =========================================================================
// stores/session.ts - QUEM está logado?
// -------------------------------------------------------------------------
// O usuário logado (ou null), em um store Zustand (veja o exemplo
// 20): legível pelos componentes (useSession) E pelo código que não é
// componente (os guards do roteador: useSession.getState()).
//
// O token JWT em si NÃO está aqui: ele está em um cookie httpOnly que
// só o navegador manipula. O store guarda apenas a DESCRIÇÃO do
// usuário, retornada pelo servidor ({ login, name, role }).
//
// Na inicialização (e após um F5), o store está vazio: check() pergunta
// ao servidor, uma única vez, quem está logado (GET /api/auth/me).
// =========================================================================

import { create } from 'zustand';
import { api } from '../api/rdvmedecins.api';
import type { Role, User } from '../api/types';

interface Session {
  user: User | null;
  check: () => Promise<void>;
  logIn: (login: string, password: string, captchaId: string, captcha: string) => Promise<void>;
  update: (u: User) => void;
  logOut: () => Promise<void>;
  forget: () => void;
}

// a pergunta "quem está logado?" já foi feita ao servidor?
// (uma variável do módulo: não precisa ser exibida)
let checking: Promise<void> | null = null;

export const useSession = create<Session>()((set, get) => ({
  user: null,

  // chamado pelo guard do roteador antes de CADA navegação; só pergunta
  // ao servidor na primeira vez (a promise é guardada e reutilizada)
  check() {
    checking ??= api
      .me()
      .then((u) => set({ user: u }))
      .catch(() => set({ user: null })); // 401: ninguém; ou servidor inacessível
    return checking;
  },

  async logIn(login, password, captchaId, captcha) {
    set({ user: await api.logIn(login, password, captchaId, captcha) });
  },

  // o usuário mudou de nome ou de login (PUT /api/my-account)
  update: (u) => set({ user: u }),

  async logOut() {
    try {
      await api.logOut();
    } finally {
      get().forget();
    }
  },

  // sem perguntar nada ao servidor: sessão expirada, conta excluída
  forget: () => set({ user: null }),
}));

// o que se deduz do usuário: funções comuns
export const role = (u: User | null): Role | null => u?.role ?? null;
export const isAdmin = (u: User | null) => role(u) === 'ADMIN';
export const isPatient = (u: User | null) => role(u) === 'USER';
// ADMIN e DOCTOR: reservam e cancelam as consultas de qualquer paciente
export const isManager = (u: User | null) => role(u) === 'ADMIN' || role(u) === 'DOCTOR';
// a página inicial de cada papel, logo após o login
export const homePage = (u: User | null) => (isPatient(u) ? '/my-area' : '/schedule');

O usuário logado, em um store [Zustand] (exemplo 20). Um store pode ser lido pelos componentes ([useSession((s) => s.user)]) E por meio de código que não é um componente: [useSession.getState()] (os guards do roteador).

  • Linha 21: a DESCRIÇÃO do usuário ([{ login, name, role }]). O token JWT, por sua vez, fica no cookie httpOnly: o cliente nunca o vê;
  • Linhas 31–44: [check()] pergunta ao servidor quem está logado UMA ÚNICA VEZ: a promise é guardada e reutilizada ([??=]: atribuição se a variável for [null]). Os guards a chamam antes de cada navegação: apenas o primeiro realmente espera;
  • linhas 46–48: a conexão: o usuário retornado pelo servidor é armazenado no store;
  • linhas 53–59: logout. [finally]: mesmo que o servidor não responda, o cliente esquece o usuário;
  • linhas 66–72: o que se deduz sobre o usuário: funções comuns que recebem o usuário como parâmetro. Um componente escreve [isAdmin(user)] depois de ler [user] do store; ele é então reexibido quando o usuário muda.

10.4.5.2. src/stores/messages.ts

// =========================================================================
// stores/messages.ts - as mensagens exibidas ao usuário
// -------------------------------------------------------------------------
// Mesma apresentação da aplicação HTML:
//   - um SUCESSO é exibido no TOPO da página (faixa verde);
//   - um ERRO no RODAPÉ, sobre um fundo rosa claro (painel "sticky").
// Uma mensagem é uma CHAVE de tradução (+ seus parâmetros): ela é, portanto,
// traduzida novamente por conta própria se o usuário trocar de idioma.
//
// As mensagens "flash": uma ação que termina com uma troca de
// página (reserva, inclusão de médico...) deixa sua mensagem com flash();
// ela será exibida na PRÓXIMA página e depois desaparece na navegação
// seguinte. É o roteador que chama newPage() ao fim de cada
// navegação (veja router.ts). Esse era, no lado do servidor, o papel do
// cookie de curta duração "rdvmedecins_flash".
// =========================================================================

import { create } from 'zustand';
import { ApiError } from '../api/api-error';

export interface Message {
  key: string;
  params?: Record<string, string>;
}

interface Messages {
  success: Message | null;
  error: Message | null;
  // as mensagens a exibir na próxima página
  pending: { success: Message | null; error: Message | null } | null;
  showSuccess: (key: string, params?: Record<string, string>) => void;
  showError: (key: string, params?: Record<string, string>) => void;
  showApiError: (e: unknown) => void;
  clear: () => void;
  flash: (type: 'success' | 'error', key: string, params?: Record<string, string>) => void;
  newPage: () => void;
}

export const useMessages = create<Messages>()((set) => ({
  success: null,
  error: null,
  pending: null,

  showSuccess: (key, params) => set({ success: { key, params }, error: null }),
  showError: (key, params) => set({ error: { key, params }, success: null }),

  // um ApiError -> a mensagem da página; qualquer outro erro é um
  // bug do cliente, que é deixado passar (console do navegador)
  showApiError(e) {
    if (!(e instanceof ApiError)) {
      throw e;
    }
    set({ error: { key: e.key, params: e.params }, success: null });
  },

  clear: () => set({ success: null, error: null }),

  // para a PRÓXIMA página
  flash: (type, key, params) =>
    set((m) => ({ pending: { success: null, error: null, ...m.pending, [type]: { key, params } } })),

  // uma nova página: as mensagens da anterior desaparecem, as mensagens
  // flash aparecem
  newPage: () =>
    set((m) => ({ success: m.pending?.success ?? null, error: m.pending?.error ?? null, pending: null })),
}));

Mensagens exibidas ao usuário: uma mensagem de sucesso no topo da página, uma mensagem de erro na parte inferior.

  • Linhas 21–24: uma mensagem é uma CHAVE de tradução e seus parâmetros, não um texto simples: ela se retraduz automaticamente se o usuário trocar de idioma;
  • linhas 49–54: um [ApiError] se torna a mensagem de erro da página. Qualquer outro erro é um problema do lado do cliente (um erro de programação): ele é relançado para aparecer no console do navegador;
  • linhas 59–60: [flash] define uma mensagem para a PRÓXIMA página. Uma ação que termina com uma mudança de página (adicionar um médico, seguida de um retorno à lista) usa isso: uma mensagem exibida imediatamente desapareceria durante a navegação do usuário;
  • linhas 64–65: chamado pelo roteador ao final de cada navegação: as mensagens pendentes se tornam as mensagens da página.

10.4.5.3. src/stores/confirmation.ts

// =========================================================================
// stores/confirmation.ts - "Tem certeza?"
// -------------------------------------------------------------------------
// Retirado do exemplo 16, na forma de um store: confirm(key) abre
// o diálogo de confirmação (components/ConfirmDialog.tsx, colocado uma vez
// no layout) e retorna uma promise resolvida com true (Sim) ou
// false (Não). A mensagem é uma CHAVE de tradução: o diálogo a traduz
// para o idioma atual.
//
//     if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }
// =========================================================================

import { create } from 'zustand';
import { useMessages } from './messages';

interface Confirmation {
  messageKey: string | null; // null: diálogo fechado
  answer: (yes: boolean) => void;
}

// a função que resolverá a promise atual (nada a exibir: fora do estado)
let respond: ((yes: boolean) => void) | null = null;

export const useConfirmation = create<Confirmation>()((set) => ({
  messageKey: null,
  answer(yes) {
    set({ messageKey: null });
    const r = respond;
    respond = null;
    r?.(yes);
  },
}));

// uma função comum, utilizável em qualquer lugar
export function confirm(key: string): Promise<boolean> {
  respond?.(false); // uma pergunta ainda aberta? conta como "não"
  // uma nova pergunta: as mensagens da ação anterior estão desatualizadas
  useMessages.getState().clear();
  useConfirmation.setState({ messageKey: key });
  return new Promise<boolean>((resolve) => {
    respond = resolve;
  });
}

A janela de confirmação do Exemplo 16, implementada como um store e uma função comum:

  • linha 17: a pergunta feita (uma chave de tradução) ou [null]: a janela ([components/ConfirmDialog.tsx]) está fechada;
  • linha 22: a função que resolverá a promise da pergunta atual. Nada a exibir: isso não é um estado, mas uma variável de módulo;
  • linhas 35–43: [confirm] abre a janela e retorna uma promise, resolvida com [true] (Sim) ou [false] (Não) por [answer]. Uma página simplesmente escreve [if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }]. Nenhum contexto é necessário, como no Exemplo 16: o store é acessível em qualquer lugar.

10.4.6. Os hooks

10.4.6.1. src/hooks/useFormSubmit.ts

// =========================================================================
// hooks/useFormSubmit.ts - envio de um formulário ao servidor
// -------------------------------------------------------------------------
// Todos os formulários da aplicação seguem o mesmo padrão do
// exemplo 25: nenhuma regra é verificada no navegador (elas
// vivem em UM só lugar, o servidor), e quando o formulário é rejeitado:
//   - o erro de cada campo (ApiError.fields) é exibido sob o
//     campo, contornado de vermelho;
//   - a mensagem geral (ApiError.key) é exibida no rodapé da página.
// Este hook agrupa esses gestos. Uma página o chama uma vez por formulário:
//
//     const submission = useFormSubmit();
//     if (await submission.submit(() => api.register(form))) { ... }
//     <InputField ... error={submission.errors.lastName} />
// =========================================================================

import { useCallback, useState } from 'react';
import { ApiError } from '../api/api-error';
import { useMessages } from '../stores/messages';

export function useFormSubmit() {
  const showApiError = useMessages((m) => m.showApiError);
  // o erro de cada campo: uma CHAVE de tradução
  const [errors, setErrors] = useState<Record<string, string>>({});
  // os parâmetros das mensagens de erro ({min}...), retornados pelo servidor
  const [params, setParams] = useState<Record<string, string>>({});
  const [submitting, setSubmitting] = useState(false);

  // executa o envio; retorna true se teve sucesso. Em caso de ApiError, os
  // erros são exibidos e retorna-se false.
  const submit = useCallback(
    async (action: () => Promise<unknown>): Promise<boolean> => {
      setErrors({});
      setParams({});
      setSubmitting(true);
      try {
        await action();
        return true;
      } catch (e) {
        showApiError(e); // (relança qualquer erro que não seja um ApiError)
        const error = e as ApiError;
        setErrors(error.fields);
        setParams(error.params);
        return false;
      } finally {
        setSubmitting(false);
      }
    },
    [showApiError],
  );

  // o usuário modifica um campo: seu erro desaparece
  const clearError = useCallback((field: string) => {
    setErrors((e) => {
      if (!(field in e)) return e; // nada a limpar: o MESMO objeto (nenhuma nova renderização)
      const { [field]: _cleared, ...rest } = e;
      return rest;
    });
  }, []);

  return { errors, params, submitting, submit, clearError };
}

Todos os formulários da aplicação seguem o padrão mostrado no Exemplo 25: nenhuma regra de validação é verificada no navegador e, se o servidor rejeita o envio, o erro de cada campo é exibido abaixo do campo, com uma mensagem de erro geral na parte inferior da página. Este hook personalizado (Exemplo 15) cuida das seguintes ações:

  • linhas 24–27: seu estado: o erro de cada campo (uma chave de tradução), seus parâmetros e “enviando” (para desabilitar o botão);
  • linhas 31–50: [submit(action)] executa o envio e retorna [true] se ele tem sucesso. Se um [ApiError] é retornado, os erros são exibidos e a função retorna [false]. [useCallback]: a função permanece a MESMA de uma exibição para a seguinte;
  • Linhas 53–59: o usuário modifica um campo: o erro desaparece. Se o campo não tinha erro, o MESMO objeto é retornado; o [React] não reexibe nada. [const { [field]: _cleared, ...rest } = e]: [rest] é uma cópia de [e], sem a propriedade [field].

10.4.6.2. src/hooks/useCaptcha.ts

// =========================================================================
// hooks/useCaptcha.ts - uma imagem de CAPTCHA e o meio de trocá-la
// -------------------------------------------------------------------------
// Carrega um CAPTCHA (GET /api/captcha) quando o componente que o usa
// é exibido. reload() pede outro: ele é necessário após CADA
// tentativa, pois uma imagem só pode ser usada UMA vez (o servidor a esquece
// assim que a verifica). A página de login a usa com o componente
// CaptchaField, que exibe a imagem e o campo de entrada.
// =========================================================================

import { useCallback, useEffect, useState } from 'react';
import { api } from '../api/rdvmedecins.api';
import type { Captcha } from '../api/types';

export function useCaptcha() {
  const [captcha, setCaptcha] = useState<Captcha | null>(null);

  const reload = useCallback(async () => {
    try {
      setCaptcha(await api.captcha());
    } catch {
      setCaptcha(null); // servidor inacessível: o login falhará com uma mensagem clara
    }
  }, []);

  useEffect(() => {
    reload();
  }, [reload]);

  // captchaId: o identificador da imagem exibida, a enviar com a resposta
  return { svg: captcha?.svg ?? '', captchaId: captcha?.id ?? '', reload };
}

Uma imagem de CAPTCHA, carregada quando o componente é exibido, e [reload()] para solicitar outra: isso é necessário após CADA tentativa, porque o servidor descarta uma imagem assim que a verifica.

10.4.7. A formatação

10.4.7.1. src/formatting.ts

// =========================================================================
// formatting.ts - a exibição de pessoas, horários e dias
// -------------------------------------------------------------------------
// O servidor envia dados BRUTOS (startHour: 8, startMinute: 0; day:
// "2026-10-05"); a formatação, que depende do idioma, é assunto do
// cliente (veja o exemplo 09).
// =========================================================================

import type { Slot, Identity } from './api/types';

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

// "8:05" em vez de "8:5"
export function time(h: number, m: number): string {
  return `${h}:${String(m).padStart(2, '0')}`;
}

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

// a data de hoje, no formato "yyyy-MM-dd" (o de <input type="date"> e o da API)
export function today(): string {
  const d = new Date();
  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}

// true se [day] for uma data que existe, no formato yyyy-MM-dd
export function isValidDate(day: unknown): day is string {
  if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
    return false;
  }
  const date = new Date(`${day}T00:00:00Z`);
  return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}

// "lundi 5 octobre 2026" / "Monday 5 October 2026"
export function longDate(day: string, language: string): string {
  return new Intl.DateTimeFormat(language === 'en' ? 'en-GB' : 'fr-FR', {
    dateStyle: 'full',
    timeZone: 'UTC', // "2026-10-05T00:00:00Z" deve continuar sendo dia 5, qualquer que seja o fuso horário
  }).format(new Date(`${day}T00:00:00Z`));
}

O servidor envia dados brutos ([startHour: 8, startMinute: 0]; [day: "2026-10-05"]); a formatação é responsabilidade do cliente (exemplo 09). São funções comuns: o [React] não exige “pipes”, e uma expressão como o JSX pode chamar qualquer função ([{timeRange(c)}]).

  • Linhas 33–39: [day is string]: um predicado de tipo: se a função retorna [true], o [TypeScript] passa a saber que [day] é uma string. Uma data “que existe”: [2026-02-30] tem o formato correto, mas [new Date] a converte em 2 de março; a data resultante é então comparada com a string original;
  • linhas 42–47: o dia por extenso, no idioma do usuário, usando [Intl.DateTimeFormat]. [timeZone: 'UTC']: a data é construída à meia-noite (UTC); formatada no fuso horário da Martinica (UTC-4), ela ainda seria o dia anterior.

10.4.8. O roteador

10.4.8.1. src/routes.tsx

// =========================================================================
// routes.tsx - as páginas da aplicação e seus direitos de acesso
// -------------------------------------------------------------------------
// Os MESMOS endereços da aplicação HTML (/login, /schedule, /doctors,
// /my-area...), mas agora são rotas do CLIENTE. O
// navegador só envia uma requisição ao servidor para a primeiríssima
// página; depois disso, o roteador muda o endereço e o componente exibido.
//
// O reverso da moeda: se o usuário recarregar /schedule (F5), o
// navegador pede mesmo /schedule ao servidor, que então deve
// devolver index.html (o Vite faz isso em desenvolvimento; em produção,
// veja web/client-spa.ts do servidor JSON).
//
// Todas as páginas são FILHAS da rota raiz, cujo componente,
// Layout, as exibe em seu <Outlet />. A função page() descreve uma
// página: seu endereço, seu componente (carregado sob demanda para as páginas
// que nem sempre são visitadas) e o guard que verifica seus direitos.
// =========================================================================

import type { ComponentType } from 'react';
import { redirect, type MiddlewareFunction, type RouteObject } from 'react-router';
import type { PersonType } from './api/rdvmedecins.api';
import { guard, registrationGuard, type Rights } from './guards';
import Layout from './components/Layout';
import Login from './pages/Login';
import Schedule from './pages/Schedule';
import ErrorPage from './pages/ErrorPage';

// uma página: componente carregado de uma vez (Component) ou sob demanda
// (load); otherGuards: guards específicos da página, após o guard comum
interface Page {
  path: string;
  rights: Rights;
  Component?: ComponentType;
  load?: () => Promise<ComponentType>;
  otherGuards?: MiddlewareFunction[];
}

function page({ path, rights, Component, load, otherGuards = [] }: Page): RouteObject {
  return {
    path,
    // os guards são executados ANTES de a página ser carregada
    middleware: [guard(rights), ...otherGuards],
    ...(load ? { lazy: async () => ({ Component: await load() }) } : { Component }),
  };
}

// as páginas de gerenciamento dos médicos E dos clientes (ADMIN), no mesmo
// modelo; o componente recebe o tipo como prop
function personPages(type: PersonType): RouteObject[] {
  const rights: Rights = { roles: ['ADMIN'] };
  const list = async () => {
    const { default: Persons } = await import('./pages/Persons');
    return () => <Persons type={type} />;
  };
  const form = async () => {
    const { default: PersonForm } = await import('./pages/PersonForm');
    return () => <PersonForm type={type} />;
  };
  return [
    page({ path: type, rights, load: list }),
    page({ path: `${type}/add`, rights, load: form }),
    page({ path: `${type}/:id/edit`, rights, load: form }),
  ];
}

export const routes: RouteObject[] = [
  {
    path: '/',
    Component: Layout,
    // exibido durante a primeiríssima navegação (o tempo de perguntar ao
    // servidor quem está logado)
    HydrateFallback: () => null,
    children: [
      // "/": para /login, que por sua vez redireciona para a página inicial do papel se o usuário estiver logado
      // (um componente que não exibe nada: o redirecionamento acontece antes)
      { index: true, loader: () => redirect('/login'), Component: () => null },
      page({ path: 'login', rights: { public: true }, Component: Login }),
      page({ path: 'schedule', rights: {}, Component: Schedule }),
      ...personPages('doctors'),
      ...personPages('clients'),
      page({
        path: 'register',
        rights: { public: true },
        load: async () => (await import('./pages/Register')).default,
        otherGuards: [registrationGuard],
      }),
      page({ path: 'my-area', rights: { roles: ['USER'] }, load: async () => (await import('./pages/PatientArea')).default }),
      page({ path: 'my-account', rights: { roles: ['USER'] }, load: async () => (await import('./pages/MyAccount')).default }),
      page({ path: 'forbidden', rights: {}, Component: () => <ErrorPage code={403} /> }),
      page({ path: '*', rights: { public: true }, Component: () => <ErrorPage code={404} /> }),
    ],
  },
];

Os MESMOS endereços que a aplicação HTML usa, mas que agora são rotas do CLIENTE:

  • linhas 31–37: a descrição de uma página: seu endereço, suas permissões de acesso e seu componente, fornecido imediatamente ([Component]) ou carregado sob demanda ([load]);
  • linhas 39–46: [page()] gera a rota correspondente:
    • linha 43: o guard comum, gerado com base nas permissões da página, seguido dos guards específicos da página. Eles são executados ANTES de a página ser carregada (Exemplo 18);
    • linha 44: [lazy]: o código da página é carregado na primeira visita (Exemplo 17). A página de login e a agenda, que todos podem ver, são carregadas imediatamente; as páginas do ADMIN e do paciente são carregadas sob demanda;
  • linhas 50–65: as três páginas de gerenciamento de médicos, seguidas das de clientes, usando o mesmo template. O componente é envolvido por um componente sem parâmetros, [() => <Persons type={type} />]: é assim que ele recebe o tipo como prop;
  • linhas 69–70: a rota raiz. Seu componente, [Layout], exibe a página atual em seu [<Outlet />];
  • linha 73: o que é exibido durante a primeira navegação, enquanto o guard pergunta ao servidor quem está conectado: nada;
  • linha 77: o endereço [/] redireciona para [/login], cujo guard, por sua vez, redireciona para a página inicial do papel se o usuário estiver logado;
  • linhas 78–79: [rights: { public: true }]: a página é acessível sem estar logado; [rights: {}]: é preciso estar logado, seja qual for o papel;
  • linhas 83–87: a criação de uma conta pública tem um segundo guard, [registrationGuard];
  • linhas 88–89: [roles: ['USER']]: as páginas do paciente;
  • linha 90: a página 403;
  • linha 91: a página 404: [*] refere-se a qualquer endereço que nenhuma outra rota reconheça.

Lembrete: se o usuário recarrega [/schedule] (F5), o navegador de fato solicita [/schedule] ao servidor, que deve então retornar [index.html]: é isso que o servidor de desenvolvimento do [Vite] faz e, em produção, o servidor JSON (veja o capítulo “Implantação”).

10.4.8.2. src/guards.ts

// =========================================================================
// guards.ts - os guards do roteador (middlewares, veja o exemplo 18)
// -------------------------------------------------------------------------
// guard(rights) CRIA o guard de uma página, a partir de seus direitos de acesso:
//   - public : acessível sem estar logado;
//   - roles  : os papéis permitidos (ausente = todos os papéis logados).
// Cada página declara os seus (veja routes.tsx). Antes de cada navegação
// para esta página, o guard:
//   1. na primeira vez (inicialização, F5), pergunta ao servidor quem está
//      logado (useSession.getState().check());
//   2. verifica os direitos da página e redireciona se necessário.
//
// LEMBRETE: essas verificações são apenas uma CONVENIÊNCIA (não exibir uma
// página inútil). A proteção dos dados é garantida pelo servidor, que
// verifica o token e o papel novamente a CADA requisição.
// =========================================================================

import { redirect, type MiddlewareFunction } from 'react-router';
import type { Role } from './api/types';
import { api } from './api/rdvmedecins.api';
import { homePage, useSession } from './stores/session';
import { useMessages } from './stores/messages';

export interface Rights {
  public?: boolean;
  roles?: Role[];
}

export function guard(rights: Rights): MiddlewareFunction {
  return async ({ request }) => {
    await useSession.getState().check();
    // getState(): o estado do store, lido FORA de um componente
    const user = useSession.getState().user;
    const url = new URL(request.url);

    if (rights.public) {
      // já logado: a página de login não faz mais sentido
      if (url.pathname === '/login' && user !== null) {
        throw redirect(homePage(user));
      }
      return;
    }
    if (user === null) {
      // a página solicitada é memorizada, para voltar a ela após o login
      throw redirect(`/login?redirect=${encodeURIComponent(url.pathname + url.search)}`);
    }
    if (rights.roles && !rights.roles.includes(user.role)) {
      throw redirect('/forbidden');
    }
  };
}

// um guard ESPECÍFICO da rota /register: sem um passe (CAPTCHA
// resolvido na página de login), volta para a página de login
export const registrationGuard: MiddlewareFunction = async () => {
  const { valid } = await api.registrationAccessStatus().catch(() => ({ valid: false }));
  if (!valid) {
    useMessages.getState().flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
    throw redirect('/login');
  }
};
  • linhas 24–27: os direitos de acesso de uma página;
  • linhas 29–51: [guard(rights)] CRIA um guard, ou seja, um middleware do roteador (exemplo 18):
    • linha 31: na primeira vez (inicialização, F5), pergunta-se ao servidor quem está logado; nas vezes seguintes, a resposta já está disponível;
    • linhas 36–42: uma página pública. Um usuário logado não precisa mais fazer nada na página de login: ele é redirecionado para sua página inicial;
    • linhas 43–46: ninguém está logado: redireciona para a página de login, guardando a página solicitada ([?redirect=...]), para voltar a ela após o login;
    • linhas 47–49: o papel não está autorizado: a página 403;
    • [throw redirect(...)]: um guard “dispara” um redirecionamento: a navegação atual é abandonada em favor do novo endereço;
  • linhas 55–61: o guard específico da página [/register]: sem um passe (o CAPTCHA resolvido na página de login), volta-se à página de login com uma mensagem. De qualquer forma, o servidor se recusaria a criar a conta.

Essas verificações são apenas uma COMODIDADE: não exibir uma página inútil. A proteção dos dados é garantida pelo servidor, que reverifica o token e o papel a CADA requisição.

10.4.9. Os componentes

10.4.9.1. src/components/Layout.tsx

// =========================================================================
// components/Layout.tsx - o LAYOUT comum a todas as páginas
// -------------------------------------------------------------------------
// O componente da rota raiz (veja routes.tsx), o equivalente de
// views/layout.hbs da aplicação HTML:
//   - a barra de navegação;
//   - uma mensagem de sucesso no TOPO;
//   - a página atual (<Outlet />);
//   - o painel de erros no RODAPÉ;
//   - o diálogo de confirmação, uma vez para toda a aplicação.
// =========================================================================

import { Outlet } from 'react-router';
import NavBar from './NavBar';
import SuccessMessage from './SuccessMessage';
import ErrorPanel from './ErrorPanel';
import ConfirmDialog from './ConfirmDialog';

export default function Layout() {
  return (
    <>
      <div className="container py-4">
        <NavBar />
        <SuccessMessage />
        <Outlet />
        <ErrorPanel />
      </div>
      <ConfirmDialog />
    </>
  );
}

O componente da rota raiz, equivalente a [views/layout.hbs] na aplicação HTML: a barra de navegação, a mensagem de sucesso no topo, a página atual ([<Outlet />]) e a área de erros na parte inferior. A janela de confirmação é colocada ali uma única vez para toda a aplicação.

10.4.9.2. src/components/PageTitle.tsx

// =========================================================================
// components/PageTitle.tsx - o título da aba, traduzido
// -------------------------------------------------------------------------
// O React 19 coloca no <head> da página qualquer elemento <title> renderizado por
// um componente (veja o exemplo 17). Cada página exibe <PageTitle titleKey="..." />
// com a chave de seu título: a aba exibe "Schedule - RdvMedecins", e
// é traduzida novamente quando o idioma muda.
// =========================================================================

import { useTranslation } from 'react-i18next';

export default function PageTitle({ titleKey }: { titleKey: string }) {
  const { t } = useTranslation();
  return <title>{`${t(titleKey)} - ${t('APP.TITLE')}`}</title>;
}

O [React] 19 coloca no cabeçalho da página ([<head>]) qualquer elemento [<title>] renderizado por um componente (exemplo 17). Cada página exibe [<PageTitle titleKey="SCHEDULE.PAGE_TITLE" />]: a aba exibe “Schedule - RdvMedecins” e é retraduzida quando o idioma muda.

10.4.9.3. src/components/NavBar.tsx

// =========================================================================
// components/NavBar.tsx - a barra de navegação
// -------------------------------------------------------------------------
// Mesmo conteúdo da aplicação HTML (views/partials/navbar.hbs):
// título, menus conforme o papel, FR / EN, papel, nome, logout.
// "Doctors" e "Patients" só aparecem para o ADMIN: uma simples
// conveniência de exibição, sendo a proteção real a do servidor.
// =========================================================================

import { NavLink, useNavigate } from 'react-router';
import { useTranslation } from 'react-i18next';
import { LANGUAGES } from '../i18n/i18n';
import { isAdmin, isPatient, useSession } from '../stores/session';

export default function NavBar() {
  const { t, i18n } = useTranslation();
  const user = useSession((s) => s.user);
  const logOut = useSession((s) => s.logOut);
  const navigate = useNavigate();

  async function onLogOut() {
    await logOut().catch(() => {}); // mesmo que o servidor não responda
    navigate('/login');
  }

  return (
    <nav className="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
      <span className="navbar-brand mb-0">{t('APP.TITLE')}</span>

      {user ? (
        <ul className="navbar-nav me-auto">
          {isPatient(user) && (
            <li className="nav-item">
              {/* NavLink define a classe "active" (Bootstrap) no menu da página exibida */}
              <NavLink className="nav-link" to="/my-area">{t('APP.MENU_MY_AREA')}</NavLink>
            </li>
          )}
          <li className="nav-item">
            <NavLink className="nav-link" to="/schedule">{t('APP.MENU_SCHEDULE')}</NavLink>
          </li>
          {isAdmin(user) && (
            <>
              <li className="nav-item">
                <NavLink className="nav-link" to="/doctors">{t('APP.MENU_DOCTORS')}</NavLink>
              </li>
              <li className="nav-item">
                <NavLink className="nav-link" to="/clients">{t('APP.MENU_PATIENTS')}</NavLink>
              </li>
            </>
          )}
        </ul>
      ) : (
        <div className="me-auto"></div>
      )}

      <div className="d-flex align-items-center gap-2">
        {/* FR / EN: nenhuma requisição ao servidor, a página é traduzida novamente no lugar */}
        <div className="btn-group btn-group-sm" role="group" aria-label={t('APP.LANGUAGE')}>
          {LANGUAGES.map((l) => (
            <button key={l} type="button" className={`btn ${i18n.language === l ? 'btn-light' : 'btn-outline-light'}`}
                    aria-pressed={i18n.language === l} onClick={() => i18n.changeLanguage(l)}>
              {l.toUpperCase()}
            </button>
          ))}
        </div>

        {user && (
          <>
            <span className="badge text-bg-light text-primary">{user.role}</span>
            <span className="text-white">{user.name}</span>
            <button type="button" className="btn btn-sm btn-outline-light" onClick={onLogOut}>{t('APP.LOGOUT')}</button>
          </>
        )}
      </div>
    </nav>
  );
}
  • linhas 17–18: o componente lê o usuário e a função de logout do store de sessão; ele é reexibido quando o usuário muda (login, logout, sessão expirada);
  • linhas 21–24: logout e, em seguida, a página de login. Mesmo que o servidor não responda, o cliente esquece o usuário (veja [stores/session.ts]): o erro é ignorado ([catch(() => {})]);
  • linhas 32–37: os menus dependem do papel;
  • linha 35: [NavLink] (exemplo 17) define a classe [active] do [Bootstrap] no menu da página exibida;
  • linhas 59–64: os botões FR / EN. [i18n.changeLanguage(l)]: nenhuma requisição é enviada ao servidor; a página inteira é renderizada novamente localmente. [aria-pressed]: um leitor de tela anuncia o botão do idioma atual como “pressionado”;
  • linhas 67–73: o papel, o nome e o botão de logout.

10.4.9.4. src/components/SuccessMessage.tsx e ErrorPanel.tsx

// =========================================================================
// components/SuccessMessage.tsx - a mensagem de SUCESSO, no topo da página
// (consulta salva, médico adicionado...) - veja stores/messages.ts.
// role="status": um leitor de tela a anuncia sem interromper o usuário.
// =========================================================================

import { useTranslation } from 'react-i18next';
import { useMessages } from '../stores/messages';

export default function SuccessMessage() {
  const { t } = useTranslation();
  const success = useMessages((m) => m.success);
  return success && <div className="alert alert-success" role="status">{t(success.key, success.params)}</div>;
}
// =========================================================================
// components/ErrorPanel.tsx - o painel de erros, no RODAPÉ de cada página, sobre
// um fundo rosa claro (classe .error-panel, veja styles.css) - como
// views/partials/errors.hbs da aplicação HTML.
// role="alert": um leitor de tela anuncia a mensagem assim que ela aparece.
// =========================================================================

import { useTranslation } from 'react-i18next';
import { useMessages } from '../stores/messages';

export default function ErrorPanel() {
  const { t } = useTranslation();
  const error = useMessages((m) => m.error);
  return error && <div className="error-panel" role="alert">{t(error.key, error.params)}</div>;
}

Dois pequenos componentes que exibem as mensagens do store [useMessages], traduzidas para o idioma atual. [role="status"] e [role="alert"]: um leitor de tela anuncia a mensagem assim que ela aparece — discretamente para um sucesso, imediatamente para um erro. Um componente pode retornar [null] (ou [false]): nesse caso, ele não exibe nada.

10.4.9.5. src/components/ConfirmDialog.tsx

// =========================================================================
// components/ConfirmDialog.tsx
// -------------------------------------------------------------------------
// O diálogo "Are you sure?" do exemplo 16, completado para o teclado
// como public/js/app.js da aplicação HTML:
//   - ao abrir, o foco vai para "No, go back": um toque distraído em
//     Enter não exclui nada;
//   - Escape fecha o diálogo (= Não);
//   - Tab e Shift+Tab permanecem DENTRO do diálogo (caso contrário o foco iria para
//     a página acinzentada, ao fundo);
//   - ao fechar, o foco volta para o elemento que o tinha (o
//     botão "Delete" clicado, por exemplo).
// "No, go back" em vez de "Cancel": a pergunta às vezes é "Cancel this
// appointment?", e um botão "Cancel" seria ambíguo nesse caso.
// O componente é colocado uma vez no layout; ele não exibe nada enquanto
// o store de confirmação não tiver nenhuma pergunta (veja stores/confirmation.ts).
// =========================================================================

import { useEffect, useRef, type KeyboardEvent, type MouseEvent } from 'react';
import { createPortal } from 'react-dom';
import { useTranslation } from 'react-i18next';
import { useConfirmation } from '../stores/confirmation';

export default function ConfirmDialog() {
  const { t } = useTranslation();
  const key = useConfirmation((c) => c.messageKey);
  const answer = useConfirmation((c) => c.answer);
  const dialog = useRef<HTMLDivElement>(null);
  const noButton = useRef<HTMLButtonElement>(null);

  // o diálogo abre: memorizamos o elemento que tem o foco e o damos ao
  // botão "No"; ele fecha (cleanup): devolvemos o foco
  const open = key !== null;
  useEffect(() => {
    if (!open) return;
    const previousFocus = document.activeElement as HTMLElement | null;
    noButton.current?.focus();
    return () => previousFocus?.focus();
  }, [open]);

  if (key === null) {
    return null; // diálogo fechado: nada a exibir
  }

  function onKeydown(e: KeyboardEvent<HTMLDivElement>) {
    if (e.key === 'Escape') {
      answer(false);
    } else if (e.key === 'Tab' && dialog.current) {
      const buttons = [...dialog.current.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last?.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first?.focus();
      }
    }
  }

  // um clique no fundo acinzentado (e não no próprio diálogo) = Não
  function onBackdropClick(e: MouseEvent<HTMLDivElement>) {
    if (e.target === e.currentTarget) {
      answer(false);
    }
  }

  return createPortal(
    <div onKeyDown={onKeydown}>
      <div className="modal-backdrop fade show"></div>
      <div ref={dialog} className="modal fade show d-block" tabIndex={-1} role="alertdialog" aria-modal="true"
           aria-labelledby="confirmation-title" aria-describedby="confirmation-message" onClick={onBackdropClick}>
        <div className="modal-dialog modal-dialog-centered">
          <div className="modal-content">
            <div className="modal-header">
              <h5 id="confirmation-title" className="modal-title">{t('CONFIRMATION.TITLE')}</h5>
              <button type="button" className="btn-close" aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} onClick={() => answer(false)}></button>
            </div>
            <div className="modal-body">
              <p id="confirmation-message" className="mb-0">{t(key)}</p>
            </div>
            <div className="modal-footer">
              <button ref={noButton} type="button" className="btn btn-secondary" onClick={() => answer(false)}>
                {t('CONFIRMATION.NO')}
              </button>
              <button type="button" className="btn btn-danger" onClick={() => answer(true)}>{t('CONFIRMATION.YES')}</button>
            </div>
          </div>
        </div>
      </div>
    </div>,
    document.body,
  );
}

A janela do Exemplo 16, ligada ao store de confirmação e completada para o teclado:

  • linhas 26–27: a pergunta feita ([null]: janela fechada) e a função que a responde;
  • linhas 33–39: um efeito que depende de [open]: ao abrir, guarda-se o elemento que tem o foco (o botão “Delete” que foi clicado) e o foco é dado ao botão “No, go back”: um toque acidental em Enter não apaga nada. A limpeza do efeito, executada ao fechar, devolve o foco ao elemento guardado;
  • linhas 41–43: janela fechada: nada a exibir. Os hooks são chamados ANTES deste [return]: eles devem ser chamados cada vez que a janela é exibida, na mesma ordem;
  • linhas 45–60: Esc significa “Não”. Tab e Shift+Tab mantêm o foco DENTRO da janela: Tab passa do último botão para o primeiro, e vice-versa; caso contrário, o foco iria para a página acinzentada por trás;
  • linhas 63–67: um clique no fundo acinzentado é tratado como “Não”. [e.target] é o elemento clicado, e [e.currentTarget] é aquele que guarda o handler: eles são iguais se o clique ocorreu no próprio fundo, e não dentro da janela;
  • Linhas 69–94: [createPortal] (Exemplo 16) exibe a janela no final do [<body>], fora da página: nenhum estilo da página pode deformá-la;
  • linha 72: para um leitor de tela, uma janela que exige uma resposta urgente; [aria-labelledby] e [aria-describedby] referem-se ao seu título e à sua pergunta.

10.4.9.6. src/components/InputField.tsx

// =========================================================================
// components/InputField.tsx - um campo de formulário completo
// -------------------------------------------------------------------------
// Label + campo + mensagem de ajuda OU mensagem de erro. Todos os
// formulários da aplicação o utilizam:
//
//   <InputField fieldId="lastName" label="PERSONS.LASTNAME_LABEL" maxLength={20}
//               value={form.lastName} onChange={(v) => edit('lastName', v)} error={submission.errors.lastName} />
//
// É um componente CONTROLADO (veja o exemplo 11): o valor pertence ao
// formulário pai. O erro é o retornado pelo SERVIDOR (veja
// hooks/useFormSubmit.ts). label, help e error são CHAVES de
// tradução; params, os parâmetros de suas mensagens ({min}...).
// =========================================================================

import { useTranslation } from 'react-i18next';

interface Props {
  fieldId: string; // o id do <input>, vinculado ao <label>
  label: string;
  value: string;
  onChange: (value: string) => void;
  error?: string;
  help?: string;
  params?: Record<string, string>;
  type?: 'text' | 'password';
  maxLength?: number;
  autoComplete?: string;
  required?: boolean;
  autoFocus?: boolean;
  className?: string; // as classes do bloco (mb-3, col-sm-6...)
}

export default function InputField({
  fieldId, label, value, onChange, error, help, params = {}, type = 'text', maxLength,
  autoComplete = 'off', required = false, autoFocus = false, className = '',
}: Props) {
  const { t } = useTranslation();
  const messageId = `${fieldId}-message`;

  return (
    <div className={className}>
      <label className="form-label" htmlFor={fieldId}>{t(label)}</label>
      <input id={fieldId} type={type} className={`form-control ${error ? 'is-invalid' : ''}`} value={value}
             onChange={(e) => onChange(e.target.value)} maxLength={maxLength} autoComplete={autoComplete}
             required={required} autoFocus={autoFocus} aria-invalid={error ? true : undefined} aria-describedby={messageId} />
      {error ? (
        <div className="invalid-feedback" id={messageId}>{t(error, params)}</div>
      ) : (
        help && <div className="form-text" id={messageId}>{t(help, params)}</div>
      )}
    </div>
  );
}

Um campo de formulário completo: rótulo, campo, mensagem de ajuda OU mensagem de erro. Todos os formulários da aplicação o utilizam.

  • linhas 18–32: suas props; [label], [help] e [error] são props de tradução (CHAVES);
  • linhas 34–37: a desestruturação das props, com valores padrão ([type = 'text']);
  • linha 39: o identificador da mensagem de ajuda ou de erro, que o [aria-describedby] liga ao campo; um leitor de tela o lê junto com o campo;
  • linhas 44–46: um campo CONTROLADO (exemplo 05): seu valor pertence ao formulário pai, que o recebe por meio de [onChange]. [is-invalid]: a caixa vermelha do [Bootstrap];
  • linhas 47–51: o erro retornado pelo servidor ou, na falta dele, o texto de ajuda.

10.4.9.7. src/components/PersonFields.tsx

// =========================================================================
// components/PersonFields.tsx - título, nome, sobrenome
// -------------------------------------------------------------------------
// Os campos de identidade, comuns a três formulários: o formulário de médico / cliente
// do ADMIN, "Create a patient account" e "Manage my account" (o equivalente da
// partial views/partials/personFields.hbs). O pai lhe passa os
// valores, os erros e a função que modifica um campo:
//     <PersonFields values={form} errors={submission.errors} onChange={edit} />
// =========================================================================

import { useTranslation } from 'react-i18next';
import type { Identity } from '../api/types';
import InputField from './InputField';

const TITLES = ['Mr', 'Mme', 'Melle'];

interface Props {
  values: Identity;
  errors: Record<string, string>;
  onChange: (field: keyof Identity, value: string) => void;
}

export default function PersonFields({ values, errors, onChange }: Props) {
  const { t } = useTranslation();
  return (
    <>
      <div className="mb-3">
        <label className="form-label" htmlFor="title">{t('PERSONS.TITLE_LABEL')}</label>
        <select id="title" className={`form-select ${errors.title ? 'is-invalid' : ''}`} value={values.title}
                onChange={(e) => onChange('title', e.target.value)}>
          {TITLES.map((title) => <option key={title}>{title}</option>)}
        </select>
        {errors.title && <div className="invalid-feedback">{t(errors.title)}</div>}
      </div>
      <div className="row g-3 mb-3">
        <InputField className="col-sm-6" fieldId="firstName" label="PERSONS.FIRSTNAME_LABEL" maxLength={20} required
                    value={values.firstName} onChange={(v) => onChange('firstName', v)} error={errors.firstName} />
        <InputField className="col-sm-6" fieldId="lastName" label="PERSONS.LASTNAME_LABEL" maxLength={20} required
                    value={values.lastName} onChange={(v) => onChange('lastName', v)} error={errors.lastName} />
      </div>
    </>
  );
}

Título, nome e sobrenome: campos comuns a três formulários (médico ou cliente do ADMIN, criação de conta, gerenciamento de conta). O equivalente da view parcial [views/partials/personFields.hbs] da aplicação HTML.

  • Linha 20: [keyof Identity]: type ['title' | 'firstName' | 'lastName']; o compilador rejeita qualquer outro nome de campo;
  • linha 31: um [<option>] sem [value] tem seu texto como valor.

10.4.9.8. src/components/CaptchaField.tsx

// =========================================================================
// components/CaptchaField.tsx - a imagem do CAPTCHA e o campo de entrada
// -------------------------------------------------------------------------
// Um componente de exibição: a imagem (svg), o link "Another image"
// (onReload) e o campo, CONTROLADO pelo formulário pai (value,
// onChange). A imagem e seu identificador vêm do hook useCaptcha, que
// o pai chama (veja pages/Login.tsx): é o pai que precisa deles
// para enviar a resposta.
//
// dangerouslySetInnerHTML: a imagem SVG é inserida como está. Sem
// perigo AQUI porque ela é criada pelo nosso servidor (biblioteca
// svg-captcha) e não contém nada que venha de um usuário - veja o
// exemplo 22.
// =========================================================================

import { useTranslation } from 'react-i18next';

interface Props {
  svg: string;
  value: string;
  onChange: (value: string) => void;
  onReload: () => void;
  error?: string;
}

export default function CaptchaField({ svg, value, onChange, onReload, error }: Props) {
  const { t } = useTranslation();
  return (
    <div className="mb-3">
      <label className="form-label" htmlFor="captcha">{t('CAPTCHA.LABEL')}</label>
      <div className="d-flex align-items-center gap-3 mb-2">
        <div className="captcha-image" role="img" aria-label={t('CAPTCHA.IMAGE_ALT')} dangerouslySetInnerHTML={{ __html: svg }} />
        <button type="button" className="btn btn-link btn-sm p-0" onClick={onReload}>{t('CAPTCHA.NEW_IMAGE')}</button>
      </div>
      <input id="captcha" type="text" maxLength={10} autoComplete="off" autoCapitalize="off" spellCheck={false}
             className={`form-control ${error ? 'is-invalid' : ''}`} value={value} onChange={(e) => onChange(e.target.value)} />
      {error ? <div className="invalid-feedback">{t(error)}</div> : <div className="form-text">{t('CAPTCHA.HELP')}</div>}
    </div>
  );
}

Um componente de exibição: a imagem, o botão “Another image” e o campo, controlado pelo formulário pai. A imagem e seu identificador vêm do hook [useCaptcha], que a página chama: a página precisa dele para enviar a resposta.

  • Linha 32: a imagem SVG é inserida tal como está (Exemplo 22). Seguro AQUI: ela é gerada pelo nosso servidor e não contém nada fornecido por um usuário. [role="img"] e [aria-label]: para um leitor de tela, isso é uma imagem com sua descrição;
  • linha 35: [autoCapitalize="off"] e [spellCheck={false}]: sem capitalização automática (celulares) nem verificação ortográfica.

10.4.9.9. src/components/BookingDialog.tsx

// =========================================================================
// components/BookingDialog.tsx - o diálogo de reserva de um horário
// -------------------------------------------------------------------------
// Mesmo diálogo de views/partials/booking.hbs da aplicação HTML:
// as classes Bootstrap de um diálogo modal, exibido "fixo no código" (show
// d-block).
//
// O componente não conversa com o servidor: ele chama
//   - onConfirm, com o paciente escolhido (null para um paciente que reserva
//     para si mesmo);
//   - onClose.
// É a página da agenda que decide o que fazer com isso (pages/Schedule.tsx).
// =========================================================================

import { useEffect, useState, type FormEvent, type MouseEvent } from 'react';
import { createPortal } from 'react-dom';
import { useTranslation } from 'react-i18next';
import type { Person } from '../api/types';
import { label } from '../formatting';

interface Props {
  time: string; // "8:00 - 8:20"
  clients: readonly Person[]; // ADMIN / DOCTOR: os pacientes entre os quais escolher
  patient: string | null; // USER: o paciente é o próprio usuário
  submitting: boolean;
  onConfirm: (clientId: number | null) => void;
  onClose: () => void;
}

export default function BookingDialog({ time, clients, patient, submitting, onConfirm, onClose }: Props) {
  const { t } = useTranslation();
  const [clientId, setClientId] = useState<number | null>(null);

  // Escape, em qualquer lugar da página: fechamos
  useEffect(() => {
    const onKeydown = (e: globalThis.KeyboardEvent) => {
      if (e.key === 'Escape') onClose();
    };
    document.addEventListener('keydown', onKeydown);
    return () => document.removeEventListener('keydown', onKeydown);
  }, [onClose]);

  function confirm(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    onConfirm(clientId);
  }

  // um clique no fundo acinzentado (e não no próprio diálogo) fecha o diálogo
  function onBackdropClick(e: MouseEvent<HTMLDivElement>) {
    if (e.target === e.currentTarget) {
      onClose();
    }
  }

  return createPortal(
    <>
      <div className="modal-backdrop fade show"></div>
      <div className="modal fade show d-block" tabIndex={-1} role="dialog" aria-modal="true" aria-labelledby="booking-title"
           onClick={onBackdropClick}>
        <div className="modal-dialog modal-dialog-centered">
          <form className="modal-content" onSubmit={confirm}>
            <div className="modal-header">
              <h5 id="booking-title" className="modal-title">{t('BOOKING_DIALOG.TITLE')}</h5>
              <button type="button" className="btn-close" aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} onClick={onClose}></button>
            </div>

            <div className="modal-body">
              <p>{t('BOOKING_DIALOG.SLOT', { time })}</p>
              {/* um paciente que reserva para si mesmo: sem lista (e o servidor
                  ignoraria de qualquer forma um eventual clientId) */}
              {patient !== null ? (
                <p className="mb-0">{t('BOOKING_DIALOG.PATIENT_LABEL')}: <strong>{patient}</strong></p>
              ) : (
                <>
                  <label className="form-label" htmlFor="clientId">{t('BOOKING_DIALOG.PATIENT_LABEL')}</label>
                  {/* autoFocus: ao ser exibido, o foco fica na lista */}
                  <select id="clientId" className="form-select" autoFocus value={clientId ?? ''}
                          onChange={(e) => setClientId(e.target.value === '' ? null : Number(e.target.value))}>
                    <option value="">{t('BOOKING_DIALOG.CHOOSE_PATIENT')}</option>
                    {clients.map((c) => <option key={c.id} value={c.id}>{label(c)}</option>)}
                  </select>
                </>
              )}
            </div>

            <div className="modal-footer">
              <button type="button" className="btn btn-secondary" onClick={onClose}>{t('BOOKING_DIALOG.CANCEL')}</button>
              {/* sem lista, é o botão de confirmação que fica com o foco */}
              <button type="submit" className="btn btn-primary" autoFocus={patient !== null} disabled={submitting}>
                {t('BOOKING_DIALOG.CONFIRM')}
              </button>
            </div>
          </form>
        </div>
      </div>
    </>,
    document.body,
  );
}

A janela de reserva de consulta. Ela não se comunica com o servidor: chama [onConfirm] com o paciente selecionado ou [onClose]; a página da agenda decide o que fazer com isso.

  • Linhas 21–28: [clients]: a lista de pacientes, para o ADMIN e os médicos; [patient]: o nome do paciente que marca a consulta para si mesmo ([null] para o ADMIN e os médicos);
  • linha 32: o paciente selecionado na lista;
  • linhas 35–41: Esc, em qualquer lugar da página, fecha a janela. O efeito se inscreve no evento [keydown] do documento, e sua limpeza cancela a inscrição ao fechar. [globalThis.KeyboardEvent]: o evento do navegador, não o do [React], que tem o mesmo nome;
  • linhas 43–46: [preventDefault()] impede o navegador de enviar o formulário;
  • linhas 71–83: um paciente faz uma reserva para si mesmo: sem lista. De qualquer forma, o servidor ignoraria qualquer [clientId];
  • linha 78: o valor de um [<option>] é sempre uma string: ele é convertido em número;
  • linha 89: sem lista, o botão de confirmação recebe o foco.

10.4.10. As páginas

10.4.10.1. src/pages/Login.tsx

// =========================================================================
// pages/Login.tsx - a página de login (/login)
// -------------------------------------------------------------------------
// Mesma página de views/login.hbs da aplicação HTML: login, senha,
// CAPTCHA, e um segundo botão "Create a patient account" que verifica o
// MESMO CAPTCHA antes de abrir a criação de conta.
//
// /login?login=jbernard: o campo de login vem preenchido (logo após a
// criação de uma conta).
// /login?redirect=/doctors: após o login, esta página é aberta
// (deixada pelo guard do roteador) em vez da página inicial do papel.
// =========================================================================

import { useState, type FormEvent } from 'react';
import { useNavigate, useSearchParams } from 'react-router';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import { homePage, useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import { useCaptcha } from '../hooks/useCaptcha';
import CaptchaField from '../components/CaptchaField';
import PageTitle from '../components/PageTitle';

export default function Login() {
  const { t } = useTranslation();
  const [params] = useSearchParams();
  const navigate = useNavigate();
  const logIn = useSession((s) => s.logIn);
  const clearMessages = useMessages((m) => m.clear);
  const submission = useFormSubmit();
  const captcha = useCaptcha();

  // o login da URL, se houver: o valor INICIAL do campo
  const urlLogin = (params.get('login') ?? '').slice(0, 30);
  const [form, setForm] = useState({ login: urlLogin, password: '', captcha: '' });

  function edit(field: keyof typeof form, value: string) {
    setForm((f) => ({ ...f, [field]: value }));
    submission.clearError(field);
  }

  // os dois botões compartilham esta sequência: envio e, em caso de falha,
  // mensagem de erro e NOVA imagem (cada uma só pode ser usada uma vez)
  async function attempt(action: () => Promise<unknown>): Promise<void> {
    clearMessages();
    const succeeded = await submission.submit(action);
    if (!succeeded) {
      setForm((f) => ({ ...f, captcha: '' }));
      await captcha.reload();
    }
  }

  async function onLogIn(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    await attempt(async () => {
      await logIn(form.login.trim(), form.password, captcha.captchaId, form.captcha);
      const redirect = params.get('redirect');
      // apenas um caminho INTERNO: nunca um redirecionamento para outro site
      const internal = redirect !== null && redirect.startsWith('/') && !redirect.startsWith('//');
      await navigate(internal ? redirect : homePage(useSession.getState().user));
    });
  }

  async function createAccount() {
    await attempt(async () => {
      await api.registrationAccess(captcha.captchaId, form.captcha);
      await navigate('/register');
    });
  }

  return (
    <div className="row justify-content-center">
      <PageTitle titleKey="LOGIN.TITLE" />
      <div className="col-sm-8 col-md-6 col-lg-5">
        <div className="card p-4">
          <h5 className="card-title mb-3">{t('LOGIN.TITLE')}</h5>

          <form onSubmit={onLogIn}>
            <div className="mb-3">
              <label className="form-label" htmlFor="login">{t('LOGIN.LOGIN_LABEL')}</label>
              {/* required: o navegador recusa enviar o formulário enquanto o campo estiver vazio.
                  autoFocus: o foco no login... ou na senha se o login já estiver preenchido */}
              <input id="login" type="text" className="form-control" autoComplete="username" required
                     autoFocus={urlLogin === ''} value={form.login} onChange={(e) => edit('login', e.target.value)} />
            </div>
            <div className="mb-3">
              <label className="form-label" htmlFor="password">{t('LOGIN.PASSWORD_LABEL')}</label>
              <input id="password" type="password" className="form-control" autoComplete="current-password" required
                     autoFocus={urlLogin !== ''} value={form.password} onChange={(e) => edit('password', e.target.value)} />
            </div>

            <CaptchaField svg={captcha.svg} value={form.captcha} onChange={(v) => edit('captcha', v)}
                          onReload={captcha.reload} error={submission.errors.captcha} />

            {/* type="submit": Enter em um campo aciona "Log in" */}
            <button type="submit" className="btn btn-primary w-100" disabled={submission.submitting}>{t('LOGIN.SUBMIT')}</button>

            {/* type="button": este botão não envia o formulário (e portanto
                ignora os campos required, inútil aqui) */}
            <button type="button" className="btn btn-outline-primary w-100 mt-3" disabled={submission.submitting} onClick={createAccount}>
              {t('LOGIN.CREATE_ACCOUNT')}
            </button>
            <div className="form-text text-center">{t('LOGIN.CREATE_ACCOUNT_HELP')}</div>
          </form>

          <div className="text-muted small mt-3">
            {t('LOGIN.DEMO_ACCOUNTS')}
            <ul className="mb-0 mt-1">
              <li><code>admin</code> - {t('LOGIN.DEMO_ADMIN')}</li>
              <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {t('LOGIN.DEMO_DOCTOR')}</li>
              <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {t('LOGIN.DEMO_USER')}</li>
            </ul>
          </div>
        </div>
      </div>
    </div>
  );
}

A página [views/login.hbs] da aplicação HTML: login, senha, CAPTCHA e um segundo botão "Create a patient account" que verifica o MESMO CAPTCHA antes de permitir o início do processo de criação da conta.

  • Linhas 29–32: o que a página precisa: login (armazenamento da sessão), limpeza das mensagens, envio do formulário e o CAPTCHA (nossos dois hooks);
  • Linhas 35–36: [/login?login=jbernard]: imediatamente após a criação de uma conta, o nome de usuário vem preenchido. [slice(0, 30)]: não recuperamos mais do que o comprimento máximo de um nome de usuário. A URL fornece apenas o valor INICIAL do campo;
  • linhas 38–41: quando um campo é digitado, seu novo valor aparece e qualquer mensagem de erro desaparece. [[field]: value]: uma propriedade cujo nome é calculado;
  • linhas 45–52: os dois botões seguem a mesma sequência: enviar e, se isso falhar, limpar o CAPTCHA e carregar uma NOVA imagem; cada uma é usada uma única vez;
  • linhas 54–63: login e, em seguida, a próxima página:
    • linha 58: a página solicitada antes do login, guardada pelo roteador ([/login?redirect=/doctors]);
    • linha 60: SOMENTE um caminho interno: [/doctors], mas não [https://malicious-site.com] nem [//malicious-site.com] (um endereço “sem protocolo”, que aponta para outro site). Caso contrário, um link malicioso como [/login?redirect=https://...] enviaria o usuário — que acabou de fazer login — para outro site: essa é a chamada vulnerabilidade de “redirecionamento aberto”;
    • linha 61: caso contrário, a página inicial do papel. [useSession.getState()]: o usuário ACABOU de ser armazenado no store; a variável de um componente, porém, só mudará no próximo carregamento da página;
  • linhas 65–70: o segundo botão: o CAPTCHA é verificado pelo servidor, que retorna um token (um cookie) para a página [/register];
  • linhas 84–85: [required]: o navegador se recusa a enviar o formulário enquanto o campo estiver vazio. Essa é a única validação feita no navegador — é apenas uma comodidade. [autoFocus]: o foco fica no campo de nome de usuário ou, se ele já estiver preenchido, no campo de senha (linha 90);
  • linha 97: [type="submit"]: digitar em um campo aciona o botão “Log in”;
  • linha 101: [type="button"]: este botão não envia o formulário e, portanto, ignora os campos [required], que aqui são desnecessários.

10.4.10.2. src/pages/Schedule.tsx

A página mais rica em funcionalidades da aplicação. Como na aplicação HTML, TODO o seu estado está na URL:

/schedule?doctorId=1&day=2026-10-05              the schedule
/schedule?doctorId=1&day=2026-10-05&book=7       + the booking dialog

A página SEGUE a URL: ela lê seus parâmetros e os usa para determinar o que exibir; as ações do usuário, por sua vez, modificam a URL. Isso permite recarregar a página, adicioná-la aos favoritos e usar os botões Voltar e Avançar do navegador.

// =========================================================================
// pages/Schedule.tsx - a página da agenda (/schedule)
// -------------------------------------------------------------------------
// Três blocos, como views/schedule.hbs da aplicação HTML:
//   1. a escolha do médico e do dia;
//   2. a agenda desse médico nesse dia;
//   3. o diálogo de reserva de um horário.
//
// Como na aplicação HTML, TODO o estado da página está em sua URL:
//     /schedule?doctorId=1&day=2026-10-05             a agenda
//     /schedule?doctorId=1&day=2026-10-05&book=7      + o diálogo de reserva
// A página pode, portanto, ser recarregada, favoritada, e os botões Voltar /
// Avançar do navegador funcionam. A página SEGUE sua URL: ela lê seus
// três parâmetros (useSearchParams) e deduz deles o que exibe;
// a agenda é uma query do TanStack Query cuja chave contém o médico
// e o dia (veja o exemplo 24); as ações do usuário, por sua vez,
// mudam a URL (navigate).
//
// O que cada usuário vê e pode fazer é decidido pelo SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada horário): a página apenas
// o exibe. Um paciente nem sequer recebe os nomes dos outros pacientes.
// =========================================================================

import { useCallback, useEffect, useState, type FormEvent } from 'react';
import { Link, useNavigate, useSearchParams } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { ApiError } from '../api/api-error';
import { api } from '../api/rdvmedecins.api';
import type { ScheduleSlot, Person } from '../api/types';
import { today, isValidDate, timeRange, longDate, label } from '../formatting';
import { isManager, isPatient, useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import BookingDialog from '../components/BookingDialog';
import PageTitle from '../components/PageTitle';

// "3" -> 3; "", "abc", "-2", ausente (null) -> null
function positiveInteger(value: string | null): number | null {
  const n = Number(value);
  return value !== null && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}

// o endereço da agenda (sem o diálogo de reserva, ou com ele)
function scheduleUrl(doctorId: number | null, day: string, book?: number): string {
  const params = new URLSearchParams({ doctorId: String(doctorId ?? ''), day });
  if (book !== undefined) {
    params.set('book', String(book));
  }
  return `/schedule?${params}`;
}

// -------------------------------------------------------------------------
// 1. a escolha do médico e do dia: um pequeno formulário, cujo estado só
// é usado antes do envio. Ele COMEÇA com os valores da URL; a página lhe dá
// uma key que muda com eles: o React então o recria, e ele
// recomeça a partir dos novos valores (botão Voltar...).
// -------------------------------------------------------------------------
interface PickerProps {
  doctors: Person[];
  doctorId: number | null;
  day: string;
  onView: (doctorId: number | null, day: string) => void;
}

function DoctorDayPicker({ doctors, doctorId, day, onView }: PickerProps) {
  const { t } = useTranslation();
  const [chosenDoctor, setChosenDoctor] = useState(doctorId);
  const [chosenDay, setChosenDay] = useState(day);

  function view(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    onView(chosenDoctor, chosenDay);
  }

  return (
    <form className="card p-3 mb-3" onSubmit={view}>
      <div className="row g-2 align-items-end">
        <div className="col-sm-5">
          <label className="form-label" htmlFor="doctorId">{t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')}</label>
          <select id="doctorId" className="form-select" required value={chosenDoctor ?? ''}
                  onChange={(e) => setChosenDoctor(positiveInteger(e.target.value))}>
            <option value="">{t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')}</option>
            {doctors.map((d) => <option key={d.id} value={d.id}>{label(d)}</option>)}
          </select>
        </div>
        <div className="col-sm-4">
          <label className="form-label" htmlFor="day">{t('DOCTOR_DAY_PICKER.DAY_LABEL')}</label>
          <input id="day" type="date" className="form-control" required value={chosenDay}
                 onChange={(e) => setChosenDay(e.target.value)} />
        </div>
        <div className="col-sm-3">
          <button type="submit" className="btn btn-primary w-100">{t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')}</button>
        </div>
      </div>
    </form>
  );
}

// -------------------------------------------------------------------------
// a página
// -------------------------------------------------------------------------
export default function Schedule() {
  const { t, i18n } = useTranslation();
  const navigate = useNavigate();
  const queryClient = useQueryClient();
  const user = useSession((s) => s.user);
  // as ações do store de mensagens: funções que nunca
  // mudam; getState() as fornece sem inscrever a página nas mensagens
  const { showSuccess, showError, showApiError, flash } = useMessages.getState();
  const [submitting, setSubmitting] = useState(false);

  // os parâmetros da URL
  const [params] = useSearchParams();
  const urlDoctorId = positiveInteger(params.get('doctorId'));
  const urlDay = params.get('day');
  const bookId = positiveInteger(params.get('book'));
  // o dia: o da URL se for válido, caso contrário hoje
  const invalidDay = urlDay !== null && !isValidDate(urlDay);
  const day = urlDay !== null && !invalidDay ? urlDay : today();

  // as listas: os médicos para todos; os pacientes só para quem
  // pode lê-los (ADMIN, DOCTOR: diálogo de reserva)
  const doctors = useQuery({ queryKey: ['doctors'], queryFn: () => api.list('doctors') });
  const clients = useQuery({
    queryKey: ['clients'],
    queryFn: () => api.list('clients'),
    enabled: isManager(user),
  });

  // a agenda: sem médico na URL, um DOCTOR vê a agenda DELE (o
  // servidor a encontra a partir do token); os demais não veem nada
  const withSchedule = !invalidDay && (urlDoctorId !== null || user?.role === 'DOCTOR');
  const schedule = useQuery({
    queryKey: ['schedule', urlDoctorId, day],
    queryFn: () => api.schedule(urlDoctorId, day),
    enabled: withSchedule,
  });
  const s = withSchedule ? schedule.data : undefined;
  // o médico exibido: o da URL, ou o da agenda recebida (DOCTOR)
  const doctorId = urlDoctorId ?? s?.doctor.id ?? null;

  // uma data inválida na URL: uma mensagem (um EFEITO: ele age sobre o
  // store de mensagens, não sobre a renderização deste componente)
  useEffect(() => {
    if (invalidDay) {
      showError('ERRORS.INVALID_DATE');
    }
  }, [invalidDay, showError]);

  // o horário cujo diálogo de reserva está aberto (?book=7),
  // somente se puder ser reservado por este usuário
  const slotToBook = s?.slots.find((c) => c.id === bookId && c.bookable) ?? null;
  // o nome do paciente logado (USER), ou null para ADMIN e DOCTOR
  const patient = isPatient(user) ? (user?.name ?? '') : null;

  // -----------------------------------------------------------------------
  // ações
  // -----------------------------------------------------------------------

  // "View schedule": mudamos a URL, a página a segue
  function viewSchedule(chosenDoctorId: number | null, chosenDay: string) {
    navigate(scheduleUrl(chosenDoctorId, chosenDay));
  }

  // useCallback: a MESMA função de uma renderização para a outra (o diálogo
  // de reserva a usa nas dependências de um efeito)
  const closeBooking = useCallback(() => navigate(scheduleUrl(doctorId, day)), [navigate, doctorId, day]);

  // o servidor é a referência: após cada ação, a agenda é lida novamente
  // (e a área do paciente, que mostra sua consulta)
  const reload = () =>
    Promise.all([queryClient.invalidateQueries({ queryKey: ['schedule'] }), queryClient.invalidateQueries({ queryKey: ['my-area'] })]);

  async function confirmBooking(clientId: number | null) {
    if (slotToBook === null) {
      return;
    }
    setSubmitting(true);
    try {
      await api.book(day, slotToBook.id, isManager(user) ? clientId : null);
      flash('success', 'SCHEDULE.BOOKED');
    } catch (e) {
      if (e instanceof ApiError && e.key === 'ERRORS.CHOOSE_PATIENT') {
        // nenhum paciente escolhido: o diálogo permanece aberto
        showError(e.key);
        return; // (o finally é executado de qualquer jeito)
      }
      if (!(e instanceof ApiError)) {
        throw e;
      }
      // horário ocupado nesse meio-tempo, paciente que já tem uma consulta...:
      // a mensagem será exibida na agenda, com o diálogo fechado
      flash('error', e.key, e.params);
    } finally {
      setSubmitting(false);
    }
    await closeBooking();
    await reload();
  }

  async function cancel(c: ScheduleSlot) {
    if (c.appointmentId === null || !(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
      return;
    }
    try {
      await api.cancelAppointment(c.appointmentId);
      showSuccess('SCHEDULE.CANCELLED');
    } catch (e) {
      showApiError(e);
    }
    await reload();
  }

  // -----------------------------------------------------------------------
  // renderização
  // -----------------------------------------------------------------------
  let content;
  if (schedule.isLoading && !s) {
    content = <p className="text-muted">{t('APP.LOADING')}</p>;
  } else if (s) {
    content = (
      <div className="card p-3">
        <h5>{t('SCHEDULE.TITLE_PREFIX')} {longDate(s.day, i18n.language)} - {label(s.doctor)}</h5>
        {s.slots.length > 0 ? (
          <table className="table table-hover align-middle">
            <thead>
              <tr>
                <th>{t('SCHEDULE.COLUMN_SLOT')}</th>
                <th>{t('SCHEDULE.COLUMN_STATUS')}</th>
                <th></th>
              </tr>
            </thead>
            <tbody>
              {s.slots.map((c) => (
                <tr key={c.id} className={c.bookable ? 'free-slot' : ''}>
                  <td>{timeRange(c)}</td>
                  <td>
                    {c.free ? (
                      <span className="badge text-bg-success">{t('SCHEDULE.FREE')}</span>
                    ) : c.patient ? (
                      <span className={`badge ${c.mine ? 'text-bg-primary' : 'text-bg-secondary'}`}>{label(c.patient)}</span>
                    ) : (
                      <span className="badge text-bg-secondary">{t('SCHEDULE.BOOKED_BY_OTHER')}</span>
                    )}
                  </td>
                  <td className="text-end">
                    {/* "Book" é um LINK: ele acrescenta &book=... à URL, o que
                        abre o diálogo de reserva */}
                    {c.bookable && (
                      <Link className="btn btn-sm btn-outline-success" to={scheduleUrl(doctorId, day, c.id)}>
                        {t('SCHEDULE.BOOK')}
                      </Link>
                    )}
                    {c.appointmentId !== null && (
                      <button type="button" className="btn btn-sm btn-outline-danger" onClick={() => cancel(c)}>
                        {t('SCHEDULE.CANCEL_APPOINTMENT')}
                      </button>
                    )}
                  </td>
                </tr>
              ))}
            </tbody>
          </table>
        ) : (
          <p className="text-muted mb-0">{t('SCHEDULE.NO_SLOTS')}</p>
        )}
      </div>
    );
  } else {
    content = <p className="text-muted">{t('SCHEDULE.EMPTY_STATE')}</p>;
  }

  return (
    <>
      <PageTitle titleKey="SCHEDULE.PAGE_TITLE" />
      <DoctorDayPicker key={`${doctorId}|${day}`} doctors={doctors.data ?? []} doctorId={doctorId} day={day}
                       onView={viewSchedule} />

      {/* paciente que já tem uma consulta futura: por isso não há botão "Book" */}
      {s?.info && (
        <div className="alert alert-info">
          {t(s.info)} <Link to="/my-area" className="alert-link">{t('APP.MENU_MY_AREA')}</Link>
        </div>
      )}

      {content}

      {/* 3. o diálogo de reserva, somente se a URL contiver &book=... */}
      {slotToBook && (
        <BookingDialog time={timeRange(slotToBook)} clients={clients.data ?? []} patient={patient}
                       submitting={submitting} onConfirm={confirmBooking} onClose={closeBooking} />
      )}
    </>
  );
}
  • linhas 39–42: um parâmetro da URL é uma string digitada por qualquer pessoa; apenas um inteiro positivo é aceito;
  • linhas 45–51: a URL da agenda, com ou sem janela de reserva;
  • linhas 66–98: o formulário de seleção de médico e data, um componente do mesmo arquivo. Seu estado só é usado antes do envio: ele é preenchido com os valores da URL (linhas 68–69). No entanto, [useState(value)] só usa seu valor durante a exibição: se a URL mudar (pelo botão “Voltar”), o formulário manteria a seleção anterior. Daí a key que a página lhe atribui, mais abaixo;
  • linhas 114–120: os parâmetros da URL. O dia: o dia da URL, se for válido, ou o dia de hoje;
  • linhas 124–129: as listas, com o [TanStack Query] (exemplo 24). A chave [['doctors']] refere-se aos dados no cache: outra página que solicite a mesma chave os recebe sem nova requisição. [enabled]: pacientes, apenas para quem está autorizado a vê-los (ADMIN e médicos, para a janela de consulta); para um paciente, a requisição não é enviada;
  • linhas 133–138: a agenda. Sua chave contém o médico e o dia: quando a URL muda, a chave muda e o [TanStack Query] envia a nova requisição por conta própria. Se não há médico na URL, um médico logado vê a SUA PRÓPRIA agenda; os demais não veem nada;
  • linha 141: o médico exibido: o da URL ou, na falta dele, o da agenda recebida;
  • linhas 145–149: uma data inválida na URL: uma mensagem. Isso é um EFEITO: atuamos sobre o store de mensagens, não sobre a exibição deste componente. Nunca modificamos outro estado enquanto a exibição está ativa;
  • linha 153: o horário cuja janela de reserva está aberta ([?book=7]), somente se puder ser reservado por este usuário: uma URL criada manualmente não abre nada;
  • linhas 162–164: “View schedule” muda a URL; a página se atualiza de acordo;
  • linha 168: fechar a janela leva de volta à URL da agenda. [useCallback]: a MESMA função de uma exibição para a seguinte, porque a janela de reserva a usa nas dependências de um efeito (veja [BookingDialog.tsx]): uma nova função a cada exibição acionaria o efeito todas as vezes;
  • Linhas 172–173: os dados do servidor têm precedência: após cada ação, a agenda (e a área do paciente, que exibe sua consulta) é atualizada. [TanStack Query] relê imediatamente os dados exibidos; os dados que não estão exibidos serão relidos na próxima vez que forem usados;
  • linhas 175–200: a reserva:
    • linha 181: o ADMIN e os médicos enviam o paciente selecionado; um paciente faz a reserva para si mesmo;
    • Linha 182: a mensagem aparecerá após a ação de navegação que fecha a janela;
    • Linhas 184–188: nenhum paciente selecionado: a janela permanece aberta, exibindo a mensagem. [return] dentro de um [try]: o bloco [finally] é executado de qualquer maneira;
    • linha 194: os demais erros (horário já ocupado, paciente que já tem uma consulta etc.) serão exibidos na agenda, com a janela fechada;
  • linhas 202–213: o cancelamento, após confirmação: [await confirm(...)] espera a resposta do usuário (veja [stores/confirmation.ts]);
  • linhas 218–272: o conteúdo principal, calculado antes do JSX: uma mensagem de espera, a agenda ou um convite para selecionar um médico. Um [if / else] comum costuma ser mais legível do que uma cascata de [? :] dentro do JSX;
  • linhas 239–245: o status do horário: disponível, o nome do paciente (em azul se for o paciente logado) ou “Booked”: um paciente NÃO recebe os nomes dos outros pacientes; o servidor não os envia;
  • linhas 250–254: “Book” é um LINK, [<Link>]: ele acrescenta [&book=...] à URL, o que abre a janela de reserva;
  • linha 255: “Cancel”, se o servidor indicou que o usuário pode cancelar esta consulta;
  • linha 277: a key do formulário contém o médico e o dia. Quando eles mudam, a key muda: o [React] destrói o formulário e cria um novo, que começa com os novos valores. É assim que o [React] “reinicia” um componente;
  • Linhas 281–285: um paciente que já tem uma consulta futura: isso explica por que não há botão “Book”;
  • linhas 290–293: a janela de reserva aparece apenas se a URL contiver [&book=...].

10.4.10.3. src/pages/persons.config.ts

// =========================================================================
// pages/persons.config.ts - médicos ou clientes?
// -------------------------------------------------------------------------
// As páginas de gerenciamento dos médicos e dos clientes são IDÊNTICAS: mesma
// lista, mesmo formulário. Como na aplicação HTML (classe abstrata
// PersonsController), elas são escritas UMA vez (Persons.tsx,
// PersonForm.tsx); apenas o endereço da API e as
// chaves dos rótulos mudam, descritos aqui. O roteador passa o tipo a cada página
// (veja routes.tsx).
// =========================================================================

import type { PersonType } from '../api/rdvmedecins.api';

export interface PersonKeys {
  title: string; // "Doctors"
  add: string; // "Add a doctor"
  edit: string; // "Edit a doctor"
  empty: string; // "No doctor."
  confirmDelete: string;
  added: string; // "Doctor {name} has been added (login: {login})."
  edited: string;
  deleted: string;
}

export const PERSON_KEYS: Record<PersonType, PersonKeys> = {
  doctors: {
    title: 'DOCTORS.TITLE',
    add: 'DOCTORS.ADD',
    edit: 'DOCTORS.EDIT',
    empty: 'DOCTORS.EMPTY',
    confirmDelete: 'DOCTORS.DELETE_CONFIRM',
    added: 'DOCTORS.ADDED',
    edited: 'DOCTORS.UPDATED',
    deleted: 'DOCTORS.DELETED',
  },
  clients: {
    title: 'CLIENTS.TITLE',
    add: 'CLIENTS.ADD',
    edit: 'CLIENTS.EDIT',
    empty: 'CLIENTS.EMPTY',
    confirmDelete: 'CLIENTS.DELETE_CONFIRM',
    added: 'CLIENTS.ADDED',
    edited: 'CLIENTS.UPDATED',
    deleted: 'CLIENTS.DELETED',
  },
};

// {name} e {login} das mensagens "added / updated / deleted"
export function messageParams(p: { firstName: string; lastName: string; login?: string }): Record<string, string> {
  return { name: `${p.firstName} ${p.lastName}`, login: p.login ?? '' };
}

As páginas de gerenciamento de médicos e de clientes são IDÊNTICAS: mesma lista, mesmo formulário. Como na aplicação HTML (classe abstrata [PersonsController]), elas são escritas UMA ÚNICA VEZ; as únicas coisas que mudam são o endereço da API (o tipo, ['doctors'] ou ['clients']) e as chaves dos rótulos, descritas aqui.

  • linhas 14–23: as chaves de tradução específicas de cada tipo;
  • linha 25: [Record<PersonType, PersonKeys>]: um objeto que tem exatamente uma propriedade por tipo; [doctors] e [clients]: o compilador acusa um elemento ausente;
  • linhas 49–51: os parâmetros [{{name}}] e [{{login}}] das mensagens de “adicionado / modificado / excluído”.

10.4.10.4. src/pages/Persons.tsx

// =========================================================================
// pages/Persons.tsx - a lista dos médicos OU dos clientes (ADMIN)
// -------------------------------------------------------------------------
// Uma única página para ambos: o tipo ('doctors' ou 'clients') chega
// como prop (veja routes.tsx); os rótulos específicos de cada um estão em
// persons.config.ts. Equivalente de views/persons/list.hbs da
// aplicação HTML.
// =========================================================================

import { Link } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api, type PersonType } from '../api/rdvmedecins.api';
import type { Person } from '../api/types';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import PageTitle from '../components/PageTitle';
import { PERSON_KEYS, messageParams } from './persons.config';

export default function Persons({ type }: { type: PersonType }) {
  const { t } = useTranslation();
  const queryClient = useQueryClient();
  const keys = PERSON_KEYS[type];
  // a lista; a key contém o tipo: médicos e clientes têm cada um a sua
  const persons = useQuery({ queryKey: [type], queryFn: () => api.list(type) });

  async function remove(p: Person) {
    if (!(await confirm(keys.confirmDelete))) {
      return;
    }
    const messages = useMessages.getState();
    try {
      await api.remove(type, p.id);
      messages.showSuccess(keys.deleted, messageParams(p));
    } catch (e) {
      // um médico que ainda tem consultas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
      messages.showApiError(e);
    }
    await queryClient.invalidateQueries({ queryKey: [type] });
  }

  const list = persons.data;
  let content;
  if (list === undefined) {
    // ainda não carregado (ou o carregamento falhou: a mensagem está no rodapé da página)
    content = <p className="text-muted mb-0">{t('APP.LOADING')}</p>;
  } else if (list.length === 0) {
    content = <p className="text-muted mb-0">{t(keys.empty)}</p>;
  } else {
    content = (
      <table className="table table-hover align-middle mb-0">
        <thead>
          <tr>
            <th>{t('PERSONS.COLUMN_TITLE')}</th>
            <th>{t('PERSONS.COLUMN_FIRSTNAME')}</th>
            <th>{t('PERSONS.COLUMN_LASTNAME')}</th>
            <th>{t('PERSONS.COLUMN_LOGIN')}</th>
            <th></th>
          </tr>
        </thead>
        <tbody>
          {list.map((p) => (
            <tr key={p.id}>
              <td>{p.title}</td>
              <td>{p.firstName}</td>
              <td>{p.lastName}</td>
              <td><code>{p.login}</code></td>
              <td className="text-end">
                <div className="d-inline-flex gap-2">
                  <Link className="btn btn-sm btn-outline-primary" to={`/${type}/${p.id}/edit`}>{t('PERSONS.EDIT')}</Link>
                  <button type="button" className="btn btn-sm btn-outline-danger" onClick={() => remove(p)}>
                    {t('PERSONS.DELETE')}
                  </button>
                </div>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    );
  }

  return (
    <>
      <PageTitle titleKey={keys.title} />
      <div className="d-flex justify-content-between align-items-center mb-3">
        <h4 className="mb-0">{t(keys.title)}</h4>
        <Link className="btn btn-primary" to={`/${type}/add`}>{t(keys.add)}</Link>
      </div>
      <div className="card p-3">{content}</div>
    </>
  );
}

A lista de médicos ou de clientes. O tipo é passado como propriedade (veja [routes.tsx]).

  • Linha 25: a lista. Sua chave é o tipo: médicos e clientes têm cada um a sua. A lista de médicos são os MESMOS dados, assim como a lista da agenda (chave [['doctors']]): ambas se beneficiam do cache;
  • Linhas 27–40: exclusão, após confirmação, seguida do recarregamento da lista. Um médico que ainda tem consultas não pode ser excluído: o servidor retorna uma resposta 409 e uma mensagem é exibida na parte inferior da página;
  • linha 31: [getState()] fornece os recursos do store sem inscrever a página nas mensagens: ela não precisa ser recarregada quando uma mensagem muda;
  • linhas 44–81: o conteúdo: “Loading…”, “No doctors” ou a tabela;
  • linha 70: “Edit” é um link para a página do formulário.

10.4.10.5. src/pages/PersonForm.tsx

// =========================================================================
// pages/PersonForm.tsx - criação OU atualização de um médico ou
// de um cliente (ADMIN)
// -------------------------------------------------------------------------
//     /doctors/add               -> criação (sem parâmetro id)
//     /doctors/3/edit            -> atualização (parâmetro id = "3")
// (e os mesmos endereços sob /clients). Equivalente de
// views/persons/form.hbs da aplicação HTML.
//
// Dois componentes:
//   - PersonForm lê o registro a atualizar (se houver);
//   - Form só é exibido depois que o registro foi lido: ele COMEÇA com
//     seus valores (estado inicial), sem precisar copiá-los depois.
// Nenhuma regra é verificada aqui: o servidor valida tudo, e seus erros
// são exibidos sob os campos (veja hooks/useFormSubmit.ts).
// A VERSÃO lida com o registro volta com a atualização: se outro
// ADMIN a modificou nesse meio-tempo, o servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================

import { useEffect, useState, type FormEvent } from 'react';
import { Link, useNavigate, useParams } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { ApiError } from '../api/api-error';
import { api, type PersonType } from '../api/rdvmedecins.api';
import type { PersonData } from '../api/types';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';
import ErrorPage from './ErrorPage';
import { PERSON_KEYS, messageParams } from './persons.config';

const EMPTY: PersonData = { title: 'Mr', firstName: '', lastName: '', login: '', password: '' };

// -------------------------------------------------------------------------
// o formulário em si
// -------------------------------------------------------------------------
interface FormProps {
  type: PersonType;
  id: number | null; // null: criação
  initial: PersonData;
}

function Form({ type, id, initial }: FormProps) {
  const { t } = useTranslation();
  const navigate = useNavigate();
  const queryClient = useQueryClient();
  const submission = useFormSubmit();
  const [form, setForm] = useState(initial);
  const keys = PERSON_KEYS[type];
  const creating = id === null;

  function edit(field: keyof PersonData, value: string) {
    setForm((f) => ({ ...f, [field]: value }));
    submission.clearError(field);
  }

  async function save(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const messages = useMessages.getState();
    const succeeded = await submission.submit(async () => {
      const p = id === null ? await api.add(type, form) : await api.edit(type, id, form);
      messages.flash('success', creating ? keys.added : keys.edited, messageParams(p));
    });
    const key = useMessages.getState().error?.key;
    if (succeeded) {
      await queryClient.invalidateQueries({ queryKey: [type] }); // a lista mudou
      navigate(`/${type}`);
    } else if (key === 'ERRORS.DOCTOR_NOT_FOUND' || key === 'ERRORS.PATIENT_NOT_FOUND') {
      // excluído nesse meio-tempo por outro ADMIN: volta para a lista
      messages.flash('error', key);
      navigate(`/${type}`);
    }
  }

  return (
    <div className="row justify-content-center">
      <div className="col-md-8 col-lg-6">
        <div className="card p-4">
          <h5 className="card-title mb-3">{t(creating ? keys.add : keys.edit)}</h5>
          {/* noValidate: é o SERVIDOR que valida (ele é a referência) */}
          <form noValidate onSubmit={save}>
            <PersonFields values={form} errors={submission.errors} onChange={edit} />

            <h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
            <InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30}
                        value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login}
                        help={creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'} />
            {/* nunca preenchida previamente: a senha nunca volta do servidor */}
            <InputField className="mb-4" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" maxLength={72}
                        autoComplete="new-password" value={form.password} onChange={(v) => edit('password', v)}
                        error={submission.errors.password} params={submission.params}
                        help={creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT'} />

            <div className="d-flex gap-2">
              <button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('PERSONS.SAVE')}</button>
              <Link className="btn btn-secondary" to={`/${type}`}>{t('PERSONS.BACK')}</Link>
            </div>
          </form>
        </div>
      </div>
    </div>
  );
}

// -------------------------------------------------------------------------
// a página: criação, ou leitura do registro a atualizar
// -------------------------------------------------------------------------
export default function PersonForm({ type }: { type: PersonType }) {
  const { id: urlId } = useParams(); // undefined para uma criação
  const navigate = useNavigate();
  const keys = PERSON_KEYS[type];
  const validId = urlId === undefined || /^\d+$/.test(urlId);
  const id = urlId === undefined || !validId ? null : Number(urlId);

  // atualização: o registro é lido (incluindo sua versão)
  //   - gcTime: 0: o registro não é mantido no cache após a visita; a
  //     próxima visita o lerá novamente, sempre atualizado (caso contrário o formulário
  //     começaria com uma versão desatualizada: 409 CONCURRENT_UPDATE);
  //   - meta.errorHandled: um erro de leitura é tratado AQUI, e não
  //     pelo tratador de erros comum (veja main.tsx)
  const details = useQuery({
    queryKey: [type, id],
    queryFn: () => api.read(type, id!),
    enabled: id !== null,
    gcTime: 0,
    meta: { errorHandled: true },
  });

  // registro que não existe (excluído nesse meio-tempo...): volta para a lista
  useEffect(() => {
    if (details.error instanceof ApiError) {
      useMessages.getState().flash('error', details.error.key, details.error.params);
      navigate(`/${type}`);
    }
  }, [details.error, navigate, type]);

  // /doctors/abc/edit: este endereço não existe
  if (!validId) {
    return <ErrorPage code={404} />;
  }

  const p = details.data;
  return (
    <>
      <PageTitle titleKey={id === null ? keys.add : keys.edit} />
      {id === null ? (
        <Form type={type} id={null} initial={EMPTY} />
      ) : (
        p && (
          <Form type={type} id={id}
                initial={{ title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', password: '', version: p.version }} />
        )
      )}
    </>
  );
}

Uma única página para criação ([/doctors/add]) e edição ([/doctors/3/edit]), composta por dois componentes:

  • linhas 46–106: o formulário em si. Ele só é exibido depois que o registro foi lido e COMEÇA com seus valores ([useState(initial)]): não há necessidade de copiá-los depois, em um efeito, quando o registro chega:
    • linhas 55–58: digitar em um campo faz seu erro desaparecer;
    • linhas 60–76: a operação de salvar. Em uma atualização, [form] contém a VERSÃO lida junto com o registro: se outro ADMIN o modificou nesse meio tempo, o servidor responde com um 409 [ERRORS.CONCURRENT_UPDATE];
    • linhas 68–70: em caso de sucesso, a lista mudou: ela é invalidada e, em seguida, o programa volta a ela com a mensagem;
    • linhas 71–75: o registro foi excluído nesse meio tempo: volta-se à lista. Os demais erros permanecem exibidos no formulário;
    • linha 84: [noValidate]: o navegador não valida os campos [required]; quem valida é o SERVIDOR, e é essa validação que conta;
    • Linha 91: o campo de senha nunca vem preenchido: a senha nunca é retornada pelo servidor;
  • Linhas 111–159: a página:
    • linha 112: o parâmetro de rota [:id], que está ausente em uma nova criação;
    • linhas 124–130: leitura do registro para uma edição. [gcTime: 0]: o registro não é mantido em cache após a visita; a próxima visita o relerá, mantendo-o atualizado (caso contrário, o formulário começaria com uma versão desatualizada). [meta: { errorHandled: true }]: um erro de leitura é tratado aqui, e não pelo handler comum (veja [main.tsx]);
    • linhas 133–138: o registro não existe (excluído nesse meio tempo, endereço digitado manualmente...): volta-se à lista, com uma mensagem;
    • linhas 141–143: [/doctors/abc/edit]: este endereço não existe;
    • linhas 149–156: uma nova entrada: o formulário vazio; uma edição: o formulário, depois que o registro foi lido. [login: p.login ?? '']: o login de uma pessoa só é enviado ao ADMIN; ele é opcional no tipo [Person].

10.4.10.6. src/pages/Register.tsx

// =========================================================================
// pages/Register.tsx - "Create a patient account" (/register)
// -------------------------------------------------------------------------
// Só se chega aqui depois de copiar o CAPTCHA da página de login
// (botão "Create a patient account"): o servidor então emitiu um
// passe, que o guard da rota verificou (veja guards.ts).
// Mesmos campos do formulário do ADMIN, mas o login e a
// senha são obrigatórios, com confirmação. Equivalente de
// views/account/registration.hbs da aplicação HTML.
// =========================================================================

import { useState, type FormEvent } from 'react';
import { Link, useNavigate } from 'react-router';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import type { Registration } from '../api/types';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';

// tamanho mínimo de uma senha escolhida por um paciente: mesmo valor
// do servidor (que também retorna {min} com o erro PASSWORD_TOO_SHORT)
const PASSWORD_MIN = '6';

export default function Register() {
  const { t } = useTranslation();
  const navigate = useNavigate();
  const submission = useFormSubmit();
  const [form, setForm] = useState<Registration>({
    title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '',
  });
  // os parâmetros da mensagem de ajuda E dos erros de senha
  const passwordParams = { min: PASSWORD_MIN, ...submission.params };

  function edit(field: keyof Registration, value: string) {
    setForm((f) => ({ ...f, [field]: value }));
    submission.clearError(field);
  }

  async function create(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    let login = '';
    const succeeded = await submission.submit(async () => {
      login = (await api.register(form)).login;
    });
    const messages = useMessages.getState();
    if (succeeded) {
      // volta para a página de login, com o login preenchido
      messages.flash('success', 'REGISTRATION.DONE', { login });
      navigate(`/login?login=${encodeURIComponent(login)}`);
    } else if (messages.error?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
      // passe expirado (15 minutos): volta para o CAPTCHA
      messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
      navigate('/login');
    }
  }

  return (
    <div className="row justify-content-center">
      <PageTitle titleKey="REGISTRATION.TITLE" />
      <div className="col-md-8 col-lg-6">
        <div className="card p-4">
          <h5 className="card-title mb-1">{t('REGISTRATION.TITLE')}</h5>
          <p className="text-muted small mb-3">{t('REGISTRATION.INTRO')}</p>
          <form noValidate onSubmit={create}>
            <PersonFields values={form} errors={submission.errors} onChange={edit} />

            <h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
            <InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30} autoComplete="username"
                        required value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login}
                        help="REGISTRATION.LOGIN_HELP" />
            <div className="row g-3 mb-3">
              <InputField className="col-sm-6" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" maxLength={72}
                          autoComplete="new-password" required value={form.password} onChange={(v) => edit('password', v)}
                          error={submission.errors.password} params={passwordParams} help="REGISTRATION.PASSWORD_HELP" />
              <InputField className="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
                          maxLength={72} autoComplete="new-password" required value={form.confirmation}
                          onChange={(v) => edit('confirmation', v)} error={submission.errors.confirmation} />
            </div>
            <div className="d-flex gap-2">
              <button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('REGISTRATION.SUBMIT')}</button>
              <Link className="btn btn-secondary" to="/login">{t('REGISTRATION.BACK_TO_LOGIN')}</Link>
            </div>
          </form>
        </div>
      </div>
    </div>
  );
}

Criação de uma conta de paciente. Só é possível chegar aqui depois de digitar o CAPTCHA da página de login: o servidor emitiu um passe, que o guard verificou.

  • linha 25: o comprimento mínimo da senha, para a mensagem de ajuda (“At least 6 characters.”). O servidor também o retorna com o erro [ERRORS.PASSWORD_TOO_SHORT];
  • linha 35: os parâmetros da mensagem de ajuda E dos erros de senha: os parâmetros do servidor, se houver, têm precedência;
  • linhas 42–58: criação da conta:
    • linha 52: em caso de sucesso, volta-se à página de login com o nome de usuário preenchido;
    • linhas 53–57: o token expirou (15 minutos): volta-se à página de login para um novo CAPTCHA.

10.4.10.7. src/pages/PatientArea.tsx

// =========================================================================
// pages/PatientArea.tsx - "My area" (/my-area, papel USER)
// -------------------------------------------------------------------------
// A página inicial do paciente, logo após o login:
//   - duas opções: [Manage my account] e [View a schedule];
//   - sua consulta futura, se tiver uma, com o meio de cancelá-la.
// Equivalente de views/patient/area.hbs da aplicação HTML.
// =========================================================================

import { Link } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import { timeRange, longDate, label } from '../formatting';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import PageTitle from '../components/PageTitle';

export default function PatientArea() {
  const { t, i18n } = useTranslation();
  const queryClient = useQueryClient();
  const area = useQuery({ queryKey: ['my-area'], queryFn: api.myArea });

  async function cancel(appointmentId: number) {
    if (!(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
      return;
    }
    const messages = useMessages.getState();
    try {
      await api.cancelAppointment(appointmentId);
      messages.showSuccess('SCHEDULE.CANCELLED');
    } catch (e) {
      messages.showApiError(e);
    }
    // a área E as agendas mudaram
    await queryClient.invalidateQueries({ queryKey: ['my-area'] });
    await queryClient.invalidateQueries({ queryKey: ['schedule'] });
  }

  const a = area.data;
  if (!a) {
    return (
      <>
        <PageTitle titleKey="AREA.TITLE" />
        <p className="text-muted">{t('APP.LOADING')}</p>
      </>
    );
  }
  return (
    <>
      <PageTitle titleKey="AREA.TITLE" />
      <h4 className="mb-3">{t('AREA.HELLO', { name: label(a.patient) })}</h4>
      <div className="row g-3 mb-4">
        <div className="col-sm-6">
          <Link className="card p-4 h-100 text-decoration-none option-card" to="/my-account">
            <h5 className="mb-1">{t('AREA.MANAGE_ACCOUNT')}</h5>
            <span className="text-muted">{t('AREA.MANAGE_ACCOUNT_HELP')}</span>
          </Link>
        </div>
        <div className="col-sm-6">
          <Link className="card p-4 h-100 text-decoration-none option-card" to="/schedule">
            <h5 className="mb-1">{t('AREA.VIEW_SCHEDULE')}</h5>
            <span className="text-muted">{t('AREA.VIEW_SCHEDULE_HELP')}</span>
          </Link>
        </div>
      </div>

      <div className="card p-3">
        <h5>{t('AREA.MY_APPOINTMENT')}</h5>
        {/* normalmente apenas uma (regra "uma consulta futura por vez"),
            mas a página pode exibir várias */}
        {a.appointments.map((appointment, i) => (
          <div key={appointment.id} className={`d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 ${i < a.appointments.length - 1 ? 'border-bottom' : ''}`}>
            <div>
              <div className="fw-semibold">{longDate(appointment.day, i18n.language)}, {timeRange(appointment.slot)}</div>
              <div className="text-muted">
                {label(appointment.doctor)} -{' '}
                {/* a agenda do médico nesse dia: o paciente vê nela o seu nome */}
                <Link to={`/schedule?${new URLSearchParams({ doctorId: String(appointment.doctor.id), day: appointment.day })}`}>
                  {t('AREA.SEE_IN_SCHEDULE')}
                </Link>
              </div>
            </div>
            <button type="button" className="btn btn-outline-danger" onClick={() => cancel(appointment.id)}>{t('AREA.CANCEL_APPOINTMENT')}</button>
          </div>
        ))}
        {a.appointments.length === 0 && <p className="text-muted mb-0">{t('AREA.NO_APPOINTMENT')}</p>}
      </div>
    </>
  );
}

A página inicial do paciente: duas opções, “Manage my account” e “View a schedule”, e sua próxima consulta, que ele pode cancelar.

  • linha 22: a área do paciente. [queryFn: api.myArea]: a própria função, sem envolvê-la em uma arrow function; ela não tem parâmetros;
  • Linhas 24–38: cancelamento, após confirmação. A área E as agendas mudaram: ambas são invalidadas;
  • linhas 41–48: enquanto a área não foi lida, “Loading…”;
  • linhas 55–58: todo um card do [Bootstrap] é um link: [<Link>] aceita qualquer conteúdo;
  • linhas 72–86: a próxima consulta. Normalmente apenas uma (a regra de “uma consulta futura por vez”), mas a página pode exibir várias;
  • linha 79: um link para a agenda do médico naquele dia, em que o paciente vê seu nome.

10.4.10.8. src/pages/MyAccount.tsx

// =========================================================================
// pages/MyAccount.tsx - "Manage my account" (/my-account, papel USER)
// -------------------------------------------------------------------------
// Dois formulários independentes, como views/patient/account.hbs:
//   1. a atualização (identidade, login, nova senha opcional);
//   2. a exclusão da conta - que também cancela suas consultas.
// Ambos exigem a senha ATUAL (verificada pelo servidor).
// Dois formulários, portanto dois estados e dois useFormSubmit (dois conjuntos
// de erros). Como no PersonForm, o formulário de atualização só é
// exibido depois que a conta foi lida, e começa com seus valores.
// =========================================================================

import { useState, type FormEvent } from 'react';
import { Link, useNavigate } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import type { MyAccountUpdate, MyAccount as Account } from '../api/types';
import { useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';

// -------------------------------------------------------------------------
// 1. a atualização
// -------------------------------------------------------------------------
function Update({ account }: { account: Account }) {
  const { t } = useTranslation();
  const navigate = useNavigate();
  const queryClient = useQueryClient();
  const submission = useFormSubmit();
  const [form, setForm] = useState<MyAccountUpdate>({ ...account, password: '', confirmation: '', currentPassword: '' });

  function edit(field: keyof MyAccountUpdate, value: string) {
    setForm((f) => ({ ...f, [field]: value }));
    submission.clearError(field);
  }

  async function save(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const succeeded = await submission.submit(async () => {
      // o servidor emitiu um NOVO token (nome, login): a barra de
      // navegação deve acompanhar
      useSession.getState().update(await api.editMyAccount(form));
      useMessages.getState().flash('success', 'MY_ACCOUNT.UPDATED');
    });
    if (succeeded) {
      await queryClient.invalidateQueries({ queryKey: ['my-area'] });
      navigate('/my-area');
    } else {
      // nunca uma senha deixada no campo após um envio rejeitado;
      // o valor é alterado SEM passar por edit(), para não apagar
      // o erro que o servidor acabou de associar a ele
      setForm((f) => ({ ...f, currentPassword: '' }));
    }
  }

  return (
    <div className="card p-4 mb-4">
      <h5 className="card-title mb-3">{t('MY_ACCOUNT.TITLE')}</h5>
      <form noValidate onSubmit={save}>
        <PersonFields values={form} errors={submission.errors} onChange={edit} />

        <h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
        <InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30} autoComplete="username"
                    required value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login} />
        <div className="row g-3 mb-3">
          <InputField className="col-sm-6" fieldId="password" type="password" label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
                      maxLength={72} autoComplete="new-password" value={form.password}
                      onChange={(v) => edit('password', v)} error={submission.errors.password} params={submission.params}
                      help="PERSONS.PASSWORD_HELP_EDIT" />
          <InputField className="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
                      maxLength={72} autoComplete="new-password" value={form.confirmation}
                      onChange={(v) => edit('confirmation', v)} error={submission.errors.confirmation} />
        </div>
        <InputField className="mb-4" fieldId="currentPassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
                    maxLength={72} autoComplete="current-password" required value={form.currentPassword}
                    onChange={(v) => edit('currentPassword', v)} error={submission.errors.currentPassword}
                    help="MY_ACCOUNT.CURRENT_PASSWORD_HELP" />
        <div className="d-flex gap-2">
          <button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('PERSONS.SAVE')}</button>
          <Link className="btn btn-secondary" to="/my-area">{t('MY_ACCOUNT.BACK')}</Link>
        </div>
      </form>
    </div>
  );
}

// -------------------------------------------------------------------------
// 2. a exclusão: um formulário com um único campo
// -------------------------------------------------------------------------
function Deletion() {
  const { t } = useTranslation();
  const navigate = useNavigate();
  const submission = useFormSubmit();
  const [currentPassword, setCurrentPassword] = useState('');

  async function remove(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    if (!(await confirm('MY_ACCOUNT.DELETE_CONFIRM'))) {
      return;
    }
    const succeeded = await submission.submit(() => api.deleteMyAccount(currentPassword));
    if (succeeded) {
      useSession.getState().forget(); // o servidor apagou o cookie do token
      useMessages.getState().flash('success', 'MY_ACCOUNT.DELETED');
      navigate('/login');
    }
  }

  return (
    <div className="card p-4 border-danger">
      <h5 className="card-title text-danger mb-1">{t('MY_ACCOUNT.DELETE_TITLE')}</h5>
      <p className="text-muted small">{t('MY_ACCOUNT.DELETE_HELP')}</p>
      <form className="d-flex flex-wrap gap-2 align-items-end" noValidate onSubmit={remove}>
        <InputField className="flex-grow-1" fieldId="deletePassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
                    maxLength={72} autoComplete="current-password" required value={currentPassword}
                    onChange={(v) => {
                      setCurrentPassword(v);
                      submission.clearError('currentPassword');
                    }}
                    error={submission.errors.currentPassword} />
        <button type="submit" className="btn btn-danger" disabled={submission.submitting}>{t('MY_ACCOUNT.DELETE_SUBMIT')}</button>
      </form>
    </div>
  );
}

// -------------------------------------------------------------------------
// a página
// -------------------------------------------------------------------------
export default function MyAccount() {
  const { t } = useTranslation();
  // gcTime: 0: lida novamente a cada visita (sua versão deve estar atualizada)
  const account = useQuery({ queryKey: ['my-account'], queryFn: api.myAccount, gcTime: 0 });

  return (
    <div className="row justify-content-center">
      <PageTitle titleKey="MY_ACCOUNT.TITLE" />
      <div className="col-md-8 col-lg-6">
        {account.data ? <Update account={account.data} /> : <p className="text-muted">{t('APP.LOADING')}</p>}
        <Deletion />
      </div>
    </div>
  );
}

Dois formulários independentes e, portanto, dois componentes, cada um com seu próprio estado e seu próprio [useFormSubmit] (dois conjuntos de erros):

  • linhas 30–90: modificação da identidade, do login e, opcionalmente, da senha:
    • linha 35: o formulário começa com os valores da conta (incluindo sua versão), com os campos de senha vazios;
    • linha 47: o servidor emitiu um NOVO token, com o novo nome e o novo login, e redireciona o usuário: ele é armazenado no store de sessão, e a barra de navegação é atualizada de acordo;
    • linhas 53–58: um envio foi rejeitado: uma senha nunca deve ficar em um campo. Alteramos o valor SEM passar por [edit()], para não apagar o erro que o servidor acabou de associar ao campo;
  • linhas 95–130: exclusão da conta, que também cancela suas consultas:
    • linha 99: um formulário com um único campo: uma única string;
    • linhas 107–111: a conta é excluída e o servidor apagou o cookie do token: o cliente esquece o usuário e, em seguida, vai para a página de login, junto com a mensagem;
  • linhas 135–149: a página. [gcTime: 0]: a conta é relida a cada visita; sua versão deve estar atualizada. A exclusão é exibida imediatamente; a modificação, depois que a conta foi lida.

10.4.10.9. src/pages/ErrorPage.tsx

// =========================================================================
// pages/ErrorPage.tsx - a página de erro: 404 (endereço desconhecido) ou 403
// (papel insuficiente, veja guards.ts). Equivalente de views/error.hbs.
// =========================================================================

import { Link } from 'react-router';
import { useTranslation } from 'react-i18next';
import PageTitle from '../components/PageTitle';

export default function ErrorPage({ code }: { code: 403 | 404 }) {
  const { t } = useTranslation();
  return (
    <div className="card p-4">
      <PageTitle titleKey="ERROR_PAGE.TITLE" />
      <h4 className="text-danger">{t('ERROR_PAGE.TITLE')} {code}</h4>
      <p>{t(code === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND')}</p>
      <Link to="/" className="btn btn-primary align-self-start">{t('ERROR_PAGE.BACK')}</Link>
    </div>
  );
}

Página de erro: 404 (endereço desconhecido) ou 403 (permissões insuficientes). [code: 403 | 404]: esta propriedade só pode assumir esses dois valores.