# React

React est une bibliothèque JavaScript pour construire des interfaces. Son idée centrale : on décrit **ce que la page doit afficher pour un état donné**, et React se charge de mettre l'écran à jour quand l'état change.

:::info{title="Ce qu'il faut connaître avant"}

Ce cours suppose [HTML](/web/html), [CSS](/web/css) et quelques bases de JavaScript : variables, fonctions, tableaux, objets. Les notations propres à JavaScript sont rappelées au fur et à mesure.

:::

## Le problème

La page du classement est écrite à la main : les scores sont dans le fichier HTML. Pour afficher ceux de l'[API](/reseau/api), il faut du code qui demande `/scores`, attende la réponse, crée une ligne de tableau par score, et gère le cas où le serveur ne répond pas.

En JavaScript sans bibliothèque, cela veut dire modifier la page élément par élément : créer une ligne, la remplir, l'insérer, penser à vider le tableau avant de le remplir à nouveau. C'est le même défaut que dans le jeu : des fonctions qui modifient l'affichage un peu partout, et un écran qui finit par ne plus correspondre aux données.

## La notion

### L'interface est une fonction de l'état

<Mermaid
  chart={`flowchart LR
    state[État<br/>la liste des scores] --> comp[Composants<br/>des fonctions]
    comp --> ui[Ce qui est affiché]
    ui -- clic, réponse du serveur --> change[Changement d'état]
    change --> state`}
/>

On ne dit jamais à React « ajoute une ligne ». On change l'état, et React rappelle les fonctions pour recalculer l'affichage. Les données ne circulent que dans un sens.

C'est exactement ce que propose l'architecture cible décrite dans la documentation du jeu : un état, des commandes qui le modifient, un rendu qui se contente de le dessiner.

### Le composant

Un composant est une fonction qui renvoie ce qu'il faut afficher.

```jsx
function Title() {
  return <h2>Classement</h2>;
}
```

Ce qui ressemble à du HTML dans le code s'appelle **JSX**. Ce n'est pas du HTML : c'est une notation transformée en JavaScript avant d'arriver au navigateur.

| Différence avec HTML | Exemple |
| --- | --- |
| `class` s'écrit `className` | `<table className="scores">` |
| Les accolades insèrent une valeur JavaScript | `<td>{score.turns}</td>` |
| Toute balise doit être fermée | `<img />`, `<br />` |
| Un composant renvoie un seul élément racine | Tout envelopper dans une balise |
| Le nom d'un composant commence par une majuscule | `<Leaderboard />` |

Ces notations sont déjà dans le projet : les fichiers `.mdx` de cette documentation sont du Markdown dans lequel on peut écrire du JSX. `<Mermaid chart={...} />` est un composant React, et `chart` est une prop.

### Les props

Les props sont les paramètres d'un composant. Elles viennent du parent et ne se modifient pas.

```jsx
function ScoreRow({ rank, player, turns }) {
  return (
    <tr>
      <td>{rank}</td>
      <td>{player}</td>
      <td>{turns}</td>
    </tr>
  );
}
```

```jsx
<ScoreRow rank={1} player="Bob" turns={30} />
```

Les accolades dans les paramètres extraient les champs d'un objet : `{ rank, player, turns }` évite d'écrire `props.rank`, `props.player`, `props.turns`.

### L'état

L'état est ce dont un composant se souvient entre deux affichages.

```jsx
const [scores, setScores] = useState([]);
```

| Morceau | Rôle |
| --- | --- |
| `useState([])` | Crée un état, avec `[]` comme valeur de départ |
| `scores` | La valeur actuelle |
| `setScores` | La fonction qui la remplace, **et qui déclenche un nouvel affichage** |

On ne modifie jamais l'état directement. `scores.push(...)` ne déclenche rien : React ne sait pas que quelque chose a changé. On passe toujours par `setScores`, avec une nouvelle valeur.

### Les effets

Un composant doit seulement calculer un affichage. Tout ce qui touche à l'extérieur, un appel réseau, une minuterie, est un **effet** et se range dans `useEffect`.

```jsx
useEffect(() => {
  // code lancé après l'affichage
}, []);
```

Le tableau en second argument dit quand relancer l'effet. Vide, il signifie : une seule fois, à l'apparition du composant.

`useState` et `useEffect` sont des **hooks**. Ils s'appellent au début du composant, jamais dans un `if` ni dans une boucle.

## Créer le projet

[Vite](https://vite.dev) crée un projet React prêt à l'emploi. Il faut Node.js, voir [brew, apt, npm](/terminal/gestionnaires-de-paquets).

```bash
cd web
npm create vite@latest classement -- --template react
cd classement
npm install
npm run dev
```

Le site s'ouvre sur `http://localhost:5173`, et se recharge à chaque modification.

```text
web/classement/
├── index.html           la page, presque vide
├── package.json
└── src/
    ├── main.jsx         branche React sur la page
    ├── App.jsx          le composant racine
    └── index.css        le style
```

Le fichier `index.html` ne contient qu'un `<div id="root">`. Tout le reste est construit par React dans ce bloc.

## Le classement en composants

On découpe la page en composants, comme on découpe un programme en fonctions.

<Mermaid
  chart={`flowchart TB
    app[App<br/>la page] --> lb[Leaderboard<br/>demande les scores, garde l'état]
    lb --> r1[ScoreRow<br/>une ligne]
    lb --> r2[ScoreRow]
    lb --> r3[ScoreRow]`}
/>

### Une ligne

```jsx
// src/ScoreRow.jsx
export default function ScoreRow({ rank, player, turns }) {
  return (
    <tr className={rank === 1 ? "first" : ""}>
      <td>{rank}</td>
      <td>{player}</td>
      <td>{turns}</td>
    </tr>
  );
}
```

Ce composant n'a pas d'état et ne fait aucun appel : il reçoit des props et renvoie un affichage. C'est une [fonction pure](/python/bonnes-pratiques/fonctions). `condition ? a : b` vaut `a` si la condition est vraie, `b` sinon.

### Le tableau

```jsx
// src/Leaderboard.jsx
import { useEffect, useState } from "react";
import ScoreRow from "./ScoreRow.jsx";

const API_URL = "http://localhost:8000";

export default function Leaderboard() {
  const [scores, setScores] = useState([]);
  const [status, setStatus] = useState("loading");

  useEffect(() => {
    fetch(`${API_URL}/scores`)
      .then((response) => {
        if (!response.ok) {
          throw new Error(`Statut ${response.status}`);
        }
        return response.json();
      })
      .then((data) => {
        setScores(data);
        setStatus("ready");
      })
      .catch(() => setStatus("error"));
  }, []);

  if (status === "loading") {
    return <p>Chargement du classement…</p>;
  }
  if (status === "error") {
    return <p>Classement indisponible.</p>;
  }
  if (scores.length === 0) {
    return <p>Aucune partie enregistrée.</p>;
  }

  return (
    <table className="scores">
      <thead>
        <tr>
          <th>Rang</th>
          <th>Joueur</th>
          <th>Tours</th>
        </tr>
      </thead>
      <tbody>
        {scores.map((score, index) => (
          <ScoreRow
            key={score.player}
            rank={index + 1}
            player={score.player}
            turns={score.turns}
          />
        ))}
      </tbody>
    </table>
  );
}
```

Ce qu'il faut y lire :

- **Deux états.** `scores` pour les données, `status` pour savoir où en est la demande.
- **`fetch`** envoie la requête. La réponse n'arrive pas tout de suite : chaque `.then` reçoit le résultat de l'étape précédente quand il est prêt, et `.catch` attrape un échec à n'importe quelle étape.
- **Les quatre cas sont traités** : en cours, en échec, vide, rempli. C'est la précaution du cours API, côté navigateur : le réseau peut toujours échouer.
- **`scores.map(...)`** transforme chaque score en un composant `ScoreRow`. C'est l'équivalent d'une compréhension de liste en Python.
- **`key`** donne à chaque ligne un identifiant stable, dont React a besoin pour savoir quelle ligne est laquelle quand la liste change.

### La page

```jsx
// src/App.jsx
import Leaderboard from "./Leaderboard.jsx";

export default function App() {
  return (
    <main>
      <h1>BestGameOfTheYear</h1>
      <h2>Classement</h2>
      <Leaderboard />
    </main>
  );
}
```

Le style est celui du cours [CSS](/web/css) : on copie le contenu de `style.css` dans `src/index.css`.

## Autoriser la page à appeler l'API

Au premier essai, la page affiche « Classement indisponible », et la console du navigateur signale une erreur **CORS**.

La page vient de `localhost:5173`, l'API est sur `localhost:8000`. Pour le navigateur, ce sont deux **origines** différentes, et il refuse par défaut qu'une page lise la réponse d'une autre origine. C'est au serveur de dire quelles origines il accepte.

Dans `server/main.py`, juste après la création de `app` :

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_methods=["GET"],
)
```

Le serveur ajoute alors à ses réponses l'en-tête `access-control-allow-origin: http://localhost:5173`, et le navigateur laisse passer.

Cette règle ne concerne que les navigateurs. `curl` et le jeu en Python n'y sont pas soumis, ce qui explique que l'API « marche avec curl » et pas depuis la page.

## Réagir à une action

Un bouton pour recharger le classement. On sort l'appel dans une fonction, pour le lancer à deux endroits.

```jsx
function loadScores() {
  setStatus("loading");
  fetch(`${API_URL}/scores`)
    .then((response) => response.json())
    .then((data) => {
      setScores(data);
      setStatus("ready");
    })
    .catch(() => setStatus("error"));
}

useEffect(() => {
  loadScores();
}, []);
```

```jsx
<button onClick={loadScores}>Actualiser</button>
```

`onClick` reçoit **la fonction**, sans parenthèses. Écrire `onClick={loadScores()}` l'appellerait pendant l'affichage, à chaque affichage.

## Les erreurs fréquentes

| Symptôme | Cause | Solution |
| --- | --- | --- |
| L'écran ne se met pas à jour | État modifié directement, avec `push` ou une affectation | Passer par la fonction `set`, avec une nouvelle valeur |
| Requêtes en boucle sans fin | `useEffect` sans tableau de dépendances, qui modifie l'état | Ajouter le tableau, `[]` pour une seule fois |
| Avertissement sur `key` dans la console | Liste affichée sans `key` | Un identifiant stable par élément |
| La requête part deux fois en développement | Le mode strict de React relance les effets pour repérer les bugs | Normal, et absent de la version construite |
| Erreur CORS dans la console | Le serveur n'autorise pas l'origine de la page | Le réglage ci-dessus |
| La page reste blanche | Erreur JavaScript | Lire la console du navigateur |

Les outils du navigateur servent ici aussi : l'onglet Console pour les erreurs, l'onglet Réseau pour voir chaque requête, son code de statut et sa réponse.

## Mettre en ligne

```bash
npm run build
```

Le dossier `dist/` contient des fichiers HTML, CSS et JavaScript ordinaires, que n'importe quel [serveur](/reseau/serveur) web peut distribuer. React n'a pas besoin de Node.js une fois le site construit.

## Dans le projet

| Idée de React | Équivalent proposé pour le jeu |
| --- | --- |
| L'affichage est calculé à partir de l'état | Le rendu lit `GameState`, sans le modifier |
| L'état ne change que par `setState` | L'état ne change que par des commandes |
| Un composant par morceau d'interface | Une classe par panneau, au lieu d'un `ui.py` de 1 440 lignes |
| Les props descendent du parent | Chaque élément reçoit ce dont il a besoin, au lieu d'aller le chercher dans `self.game` |

Pygame redessine déjà tout l'écran à chaque image : il ne manque au jeu que la discipline sur **qui a le droit de modifier l'état**.

## À retenir

- Un composant est une fonction qui renvoie un affichage.
- Les props entrent, l'état se souvient, les effets parlent à l'extérieur.
- On ne modifie jamais l'état directement.
- Tout appel réseau a quatre issues : en cours, échec, vide, rempli.
- Un navigateur n'appelle une autre origine que si le serveur l'autorise.

## Exercices

1. Créer le projet, écrire les trois composants, afficher le classement avec l'API lancée.
2. Arrêter l'API et recharger la page. Qu'affiche-t-elle ? Que montre l'onglet Réseau ?
3. Retirer le réglage CORS du serveur, recharger, lire la console. Le remettre.
4. Ajouter le bouton Actualiser.
5. Ajouter un champ de texte qui filtre le classement par nom de joueur. Il faut un troisième état.
6. Ajouter un formulaire qui envoie un score avec `POST`. Que faut-il changer côté serveur ? Indice : `allow_methods` et `allow_headers`.
7. Découper une page de cette documentation en composants, sur papier : lesquels reçoivent des props, lesquels ont un état ?
