Aller au contenu
English

Bases de React

  • Leçon 5
  • 75 min
  • Module 2 : Composants et structure de l'application

Où nous en sommes

Dans le module 1, nous avons construit la première page du bureau des billets et nous l'avons passée aux outils d'un vrai projet. Mais notre script modifie la page à la main : chaque fois que les données changent, il doit trouver et corriger chaque endroit qui en dépend. Dans cette leçon, nous transformons le bureau en interface React. Nous décrivons l'écran une fois, et React le garde à jour, comme un tableur qui met à jour son propre total.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Transformez le bureau des billets de soutien en interface React. Vous décrivez ce que l’écran affiche selon vos données. React garde la page à jour quand les données changent.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 75 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Node.js 24 (LTS) et le dossier de projet ticket-desk obtenu à la fin du module 1. Si votre copie est endommagée ou absente, téléchargez de nouveau l’instantané end-of-m01, comme dans Installer le bureau des tickets. Exécutez ensuite npm install dans ce dossier.
  • Deux terminaux dans le dossier du projet. Dans le premier, l’API simulée fonctionne : npm run api.
  • Environ 45 Mo d’espace disque libre pour les nouveaux paquets, et une connexion réseau pour les installations.

Testé avec Node.js 24.18.0, npm 11.16.0, React 19.3.0 et Vite 8.3.4 sur macOS (Apple silicon), dans Chromium. Sur Windows (PowerShell) et Linux, les commandes npm sont les mêmes; elles n’y ont pas été exécutées.

Pensez à un budget dans un tableur. La cellule B5 contient le total : =B1+B2+B3+B4. Quand vous changez le loyer dans B2, le total change aussi. Vous n’allez jamais dans B5 pour saisir vous-même le nouveau total. Vous avez décrit le total une fois, sous forme de règle, et le tableur le garde exact.

Imaginez maintenant le même budget sur papier. Chaque fois qu’un nombre change, vous devez trouver tous les endroits qui en dépendent et les corriger à la main. Si vous en oubliez un, le papier est incorrect, et rien ne vous avertit.

La page TypeScript du module 1 fonctionne comme le budget sur papier. Ouvrez src/main.ts. Ce fichier modifie la page à six endroits : deux appels à list.replaceChildren(...) et quatre lignes qui définissent answer.textContent. Chaque ligne fait une correction à la main, et chacune doit s’exécuter au bon moment.

src/main.ts (Module 1, part)
answer.textContent = 'Sending…';
// …
answer.textContent = `Saved as ${result.ticket_id}. AI work: ${result.state} (job ${result.job_id}).`;
form.reset();
void showTickets(); // the list must be loaded and drawn again, by hand

Grace veut bien plus que cette page : des filtres, une vue de billet et des erreurs avec un bouton Try again (réessayer). Elle veut aussi un brouillon qui apparaît mot par mot. Avec du code comme main.ts, chaque changement des données exige une mise à jour du DOM partout où elles s’affichent. Oubliez-en une, et l’écran affiche d’anciennes données. Teodor compte les besoins du module 4 seulement : un panneau de brouillon avec huit situations, de « waiting » (en attente) à « stopped » (arrêté) et « failed » (échec). « Je ne peux pas écrire toutes ces mises à jour à la main sans faire d’erreur », dit Teodor.

L’idée : décrire l’écran et laisser React le mettre à jour

Section intitulée « L’idée : décrire l’écran et laisser React le mettre à jour »

React est une bibliothèque JavaScript qui fonctionne comme le tableur. Vous écrivez une fonction qui décrit l’écran pour certaines données. Quand les données changent, React rappelle votre fonction et modifie la page seulement là où le résultat diffère. Vous n’écrivez plus replaceChildren ni textContent.

Cette fonction est un composant : une partie nommée de l’écran, écrite comme une fonction qui retourne ce qu’il faut afficher. Ses entrées sont les props (props, abréviation de propriétés) : les valeurs que son parent lui donne. Sa mémoire propre est l’état : des valeurs que le composant conserve entre les rendus et qui peuvent changer. Le texte dans un champ en est un exemple. Quand l’état change, React refait le rendu du composant. C’est l’origine de son nom : l’écran réagit aux données.

Voici le plus petit composant du bureau. Il affiche l’état d’un billet sous forme de libellé coloré :

src/StatusBadge.tsx
import type { Status } from './types';
const LABELS: Record<Status, string> = { open: 'Open', pending: 'Pending', resolved: 'Resolved', closed: 'Closed' };
/** A ticket's status as a small coloured label. The word is always visible, not only the colour. */
export function StatusBadge({ status }: { status: Status }) {
return <span className={`badge badge-${status}`}>{LABELS[status]}</span>;
}

La partie qui ressemble à du HTML est du JSX : des balises semblables au HTML dans du JavaScript. L’outil de construction les transforme en appels de fonctions. Deux détails diffèrent du HTML. Vous écrivez className plutôt que class, car class est un mot réservé en JavaScript. Les accolades {…} insèrent une valeur JavaScript dans les balises.

Suivez une utilisation, avec toutes les valeurs visibles. Un parent écrit <StatusBadge status="pending" /> :

Étape Valeur
La prop reçue status vaut "pending" (en attente)
`badge badge-${status}` "badge badge-pending"
LABELS[status] "Pending" (en attente)
Ce que React place dans la page <span class="badge badge-pending">Pending</span>

Le nom d’un composant commence par une majuscule. C’est ainsi que JSX distingue vos composants (<StatusBadge>) des balises HTML (<span>). Le nom du fichier se termine par .tsx, car il contient du TypeScript avec du JSX.

Les composants utilisent d’autres composants, comme les éléments HTML contiennent d’autres éléments. Une ligne de billet affiche son numéro, son objet, son client et son équipe. Elle utilise StatusBadge pour l’état :

src/TicketRow.tsx
import { StatusBadge } from './StatusBadge';
import type { TicketSummary } from './types';
/** One ticket in the list. */
export function TicketRow({ ticket }: { ticket: TicketSummary }) {
return (
<div className="row">
<span className="row-id">{ticket.ticket_id}</span>
<span className="row-subject">{ticket.subject}</span>
<span className="row-meta">
{ticket.customer_name} · {ticket.team}
</span>
<StatusBadge status={ticket.status} />
</div>
);
}

Le bureau entier forme un arbre de composants. App est la racine. Il affiche TicketList et NewTicketForm. La liste affiche les filtres et 50 lignes, et chaque ligne affiche un libellé. Les données descendent dans l’arbre sous forme de props. Quand on appuie sur une touche plus bas, l’enfant appelle une fonction que son parent lui a donnée : les événements remontent.

Un arbre de composants. App, au sommet, a deux enfants : TicketList et NewTicketForm. TicketList possède les valeurs d'état filter, tickets et failure, et a deux enfants : TicketFilters, qui reçoit value, onChange et onSearch, et TicketRow répété 50 fois, qui reçoit ticket. TicketRow a un enfant StatusBadge, qui reçoit status. NewTicketForm possède les valeurs d'état values, errors, sending, answer et failure. Une flèche pointillée remonte de TicketFilters vers TicketList : il appelle onChange(next) et onSearch(). TicketFilters et TicketRow ne possèdent aucun état.
Le bureau à la fin de cette leçon. Les props descendent; les événements remontent par les fonctions fournies par le parent. Seuls deux composants possèdent un état.
Description textuelle du diagramme

App est au sommet et ne possède rien. Il a deux enfants. TicketList possède trois valeurs d’état : le filtre, les billets chargés et un texte d’erreur. Il donne à TicketFilters le filtre (value) et deux fonctions (onChange et onSearch). Il donne aussi un billet à chacun des 50 composants TicketRow. Chaque ligne donne un état à son StatusBadge. NewTicketForm possède les valeurs du formulaire, les erreurs, l’état d’envoi, et la réponse ou l’échec de l’API. Quand vous tapez dans un filtre, TicketFilters appelle onChange, une fonction qui appartient à TicketList. L’événement remonte, et le nouveau filtre redescend sous forme de prop.

Un composant est une fonction, et une fonction oublie tout quand elle retourne un résultat. Alors, où se trouve le texte que vous avez tapé? Il se trouve dans l’état. Vous le demandez à React avec useState :

const [values, setValues] = useState<NewTicket>({ customer_id: '', subject: '', body: '' });

useState retourne deux choses : la valeur actuelle, values, et une fonction qui la modifie, setValues. React conserve la valeur pour ce composant entre les rendus. Vous ne modifiez jamais values directement. Vous appelez setValues avec la nouvelle valeur, puis React rappelle le composant avec cette valeur. Une fonction comme useState, dont le nom commence par use, est un hook (hook, fonction d’accès aux fonctionnalités de React). Elle permet à un composant d’utiliser une fonctionnalité de React. Appelez les hooks au début du composant, jamais dans un if ou une boucle. React retrouve la valeur de chaque hook selon son ordre.

Dans le module 1, vous avez écrit form.addEventListener('submit', …). En JSX, vous donnez le gestionnaire comme prop : onClick={…}, onChange={…} ou onSubmit={…}. React l’appelle quand l’événement se produit.

Un champ de formulaire peut maintenant tirer sa valeur de l’état. C’est un champ contrôlé : l’état est le seul endroit où le texte se trouve, et le champ l’affiche simplement.

<input id="new-customer_id" value={values.customer_id}
onChange={(e) => setValues({ ...values, customer_id: e.target.value })} />

Suivez un appui sur une touche. Le champ est vide, et vous tapez C :

Quatre étapes en boucle. 1 : vous tapez C dans Customer ID (identifiant du client). 2 : onChange appelle setValues avec customer_id à 'C'. 3 : React rappelle NewTicketForm, et values.customer_id vaut 'C'. 4 : React modifie la page, et le champ affiche C. Une flèche pointillée retourne de l'étape 4 à l'étape 1 : le prochain appui sur une touche recommence la boucle.
Un appui sur une touche dans un champ contrôlé. Le champ affiche l'état; il ne conserve jamais sa propre copie.
Description textuelle du diagramme

Étape 1 : vous tapez C dans le champ Customer ID. Étape 2 : le gestionnaire onChange appelle setValues avec customer_id: 'C'; l’objet et le message restent des chaînes vides. Étape 3 : React rappelle NewTicketForm, et cette fois, values.customer_id vaut 'C'. Étape 4 : React compare le nouveau résultat à la page et modifie seulement la valeur du champ, qui affiche maintenant C. Le prochain appui sur une touche suit la même boucle.

Pourquoi faire une boucle pour une seule lettre? Parce que votre code connaît maintenant toujours le texte. Le formulaire peut le vérifier, l’effacer après l’envoi ou le remplir depuis une autre source, avec un seul appel à setValues. { ...values, customer_id: … } crée un nouvel objet : une copie de values avec un champ modifié. React compare l’ancien objet au nouveau pour voir que quelque chose a changé. Donnez donc toujours un nouvel objet à setValues, et ne modifiez jamais l’ancien.

La liste produit une ligne par billet avec map, comme vous l’avez fait avec les tableaux dans le module 1 :

<ul className="rows">
{tickets.map((t) => (
<li key={t.ticket_id}>
<TicketRow ticket={t} />
</li>
))}
</ul>

Chaque élément reçoit une clé : une valeur unique dans la liste qui reste associée au même élément. Quand la liste change, React associe les éléments du nouveau rendu aux anciens grâce à leurs clés. Un billet déplacé vers le bas garde sa ligne; seuls les nouveaux billets reçoivent de nouvelles lignes. Le numéro du billet est une bonne clé. La position dans la liste (0, 1, 2…) en est une mauvaise. Quand un nouveau billet arrive au sommet, chaque position change, et React associe les mauvaises lignes.

Les filtres ont besoin d’un état : le texte de recherche, l’état du billet et l’équipe. Mais la liste a besoin des mêmes valeurs pour charger les bons billets. Deux composants ne peuvent pas posséder chacun une copie d’une même valeur, sinon les copies finissent par diverger. Le filtre se trouve donc dans leur parent commun le plus proche, TicketList. TicketFilters reçoit la valeur et les fonctions de modification et de recherche sous forme de props :

<TicketFilters value={filter} onChange={setFilter} onSearch={search} />

Ce déplacement a un nom : remonter l’état. TicketFilters ne possède aucun état; il affiche value et appelle onChange. Gardez une question en tête pour tout le module : pour chaque valeur qui peut changer, quel composant unique la possède?

Vous transformez la page TypeScript en bureau React. Les quatre fichiers de la page du module 1 (src/main.ts, src/api.ts, src/types.ts et src/api.test.ts) changent ou disparaissent.

  1. Dans le deuxième terminal, vérifiez que vous êtes dans le dossier du projet : ls (Windows : dir) affiche package.json et mock-api.

  2. Installez React, la bibliothèque qui fait le rendu des composants dans la page :

    Fenêtre de terminal
    npm install --save-exact react@19.3.0 react-dom@19.3.0
    added 3 packages, and audited 42 packages in 537ms
    12 packages are looking for funding
    run `npm fund` for details
    found 0 vulnerabilities

    react contient les composants et les hooks; react-dom les place dans une page du navigateur. --save-exact écrit la version exacte dans package.json, pour que chaque copie du projet utilise la même. Sur macOS, npm 11 peut aussi afficher npm warn allow-scripts (avertissement sur les scripts autorisés) à propos de fsevents. Vous n’avez rien à faire.

  3. Installez les outils dont vous seul, comme développeur, avez besoin : le module d’extension React de Vite, les types React pour TypeScript et les outils de test. C’est une seule longue ligne :

    Fenêtre de terminal
    npm install --save-dev --save-exact @vitejs/plugin-react@6.1.2 @types/react@19.3.0 @types/react-dom@19.3.0 jsdom@30.1.2 @testing-library/react@16.3.3 @testing-library/dom@10.4.2 @testing-library/jest-dom@7.0.1 @testing-library/user-event@14.6.7
    added 63 packages, and audited 105 packages in 5s
    21 packages are looking for funding
    run `npm fund` for details
    found 0 vulnerabilities

    node_modules passe de 64 Mo à 107 Mo.

  4. Ouvrez package.json. Remplacez "version": "0.1.0" par "version": "0.2.0" : c’est une nouvelle étape du projet.

  5. Ouvrez tsconfig.json. Dans compilerOptions, après la ligne "moduleResolution": "bundler",, ajoutez "jsx": "react-jsx",. Cela indique à TypeScript comment lire le JSX.

  6. Remplacez vite.config.ts par cette version. Le module d’extension React transforme le JSX en JavaScript. La partie consacrée aux tests les exécute dans jsdom, une page en mémoire, car les composants ont besoin d’un DOM.

    vite.config.ts
    import { defineConfig } from 'vitest/config';
    import react from '@vitejs/plugin-react';
    export default defineConfig({
    plugins: [react()],
    server: { port: 5173, strictPort: true },
    preview: { port: 4173, strictPort: true },
    test: {
    environment: 'jsdom',
    include: ['src/**/*.test.{ts,tsx}'],
    setupFiles: ['src/test/setup.ts'],
    },
    });
  7. Ouvrez index.html. Remplacez tout ce qui se trouve entre <body> et </body> par un élément vide et le nouveau script. React remplit l’élément.

    index.html (inside body)
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  8. Supprimez src/main.ts. Créez src/main.tsx :

    src/main.tsx
    import { StrictMode } from 'react';
    import { createRoot } from 'react-dom/client';
    import { App } from './App';
    import './styles.css';
    createRoot(document.getElementById('root')!).render(
    <StrictMode>
    <App />
    </StrictMode>,
    );

    createRoot relie React à <div id="root">. StrictMode ajoute des vérifications pendant le développement; Rendu et effets en présente une.

  9. Remplacez le contenu de src/types.ts par le fichier src/api/types.ts de l’instantané end-of-m02. Il ajoute les listes exactes des équipes et des états, le billet avec ses messages, et TicketFilter.

  10. Remplacez src/api.ts et src/api.test.ts par les versions dans l’encadré ci-dessous. loadTickets envoie maintenant les filtres. ticketLine disparaît, car les composants font maintenant le rendu des lignes.

  11. Créez les composants : src/StatusBadge.tsx et src/TicketRow.tsx (ci-dessus), puis src/TicketFilters.tsx, src/TicketList.tsx, src/NewTicketForm.tsx et src/App.tsx (dans l’encadré ci-dessous).

  12. Créez les fonctions utilitaires de test src/test/setup.ts et src/test/fakeApi.ts : copiez-les depuis l’instantané end-of-m02. Dans fakeApi.ts, changez l’importation pour from '../types'. Créez ensuite src/TicketList.test.tsx et src/NewTicketForm.test.tsx (dans l’encadré ci-dessous).

Les fichiers des étapes 10 à 12
src/api.ts
// The requests to the ticket API. The page and the API are on different addresses
// (Vite on localhost:5173, the API on 127.0.0.1:8100), so every request uses the full address.
import type { NewTicket, TicketAccepted, TicketFilter, TicketPage, TicketSummary } from './types';
export const API_URL: string = import.meta.env.VITE_API_URL ?? 'http://127.0.0.1:8100';
/** Reads the first tickets that match the filter. */
export async function loadTickets(filter: TicketFilter, limit: number): Promise<TicketSummary[]> {
const query = new URLSearchParams({ limit: String(limit) });
if (filter.status) query.set('status', filter.status);
if (filter.team) query.set('team', filter.team);
if (filter.q.trim()) query.set('q', filter.q.trim());
const response = await fetch(`${API_URL}/v1/tickets?${query}`);
if (!response.ok) {
throw new Error(`The API answered ${response.status}`);
}
const page = (await response.json()) as TicketPage;
return page.items;
}
/** Sends a new ticket. The answer is the saved ticket, or the API's error in words. */
export async function sendTicket(ticket: NewTicket): Promise<TicketAccepted | string> {
const response = await fetch(`${API_URL}/v1/tickets`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(ticket),
});
const body = await response.json();
if (response.ok) return body as TicketAccepted;
const { error } = body as { error: { message: string; fields: string[] } };
return `Not saved: ${error.message} Fields: ${error.fields.join(', ')}`;
}
src/api.test.ts
// Tests for the requests, with a fake fetch: no API needs to run.
import { afterEach, expect, test, vi } from 'vitest';
import { loadTickets, sendTicket } from './api';
afterEach(() => vi.unstubAllGlobals());
const ticket = {
ticket_id: 'T-80008', customer_id: 'C-0022', customer_name: 'Ana Silva', subject: 'Parcel lost',
team: 'shipping', priority: 2, status: 'open', created_at: '2026-01-05T10:00:00Z',
};
test('loadTickets asks for one page with the filters that are set', async () => {
const fetch = vi.fn(async () => new Response(JSON.stringify({ items: [ticket], next: null })));
vi.stubGlobal('fetch', fetch);
expect(await loadTickets({ status: 'open', team: '', q: ' parcel ' }, 10)).toEqual([ticket]);
expect(fetch).toHaveBeenCalledWith('http://127.0.0.1:8100/v1/tickets?limit=10&status=open&q=parcel');
});
test('loadTickets fails with the status when the API answers an error', async () => {
vi.stubGlobal('fetch', async () => new Response('{}', { status: 503 }));
await expect(loadTickets({ status: '', team: '', q: '' }, 10)).rejects.toThrow('The API answered 503');
});
test('sendTicket gives back the API error in words', async () => {
const body = { error: { code: 'validation_error', message: 'The ticket is not valid.', request_id: 'r1', fields: ['customer_id'] } };
vi.stubGlobal('fetch', async () => new Response(JSON.stringify(body), { status: 422 }));
expect(await sendTicket({ customer_id: 'x', subject: 's', body: 'b' })).toBe('Not saved: The ticket is not valid. Fields: customer_id');
});
src/TicketFilters.tsx
import { STATUSES, TEAMS, type TicketFilter } from './types';
interface Props {
value: TicketFilter;
onChange: (next: TicketFilter) => void;
onSearch: () => void;
}
/** The filters above the list. The parent owns the values; this component only shows and changes them. */
export function TicketFilters({ value, onChange, onSearch }: Props) {
return (
<form
className="filters"
role="search"
onSubmit={(e) => {
e.preventDefault();
onSearch();
}}
>
<label>
Search
<input
type="search"
value={value.q}
onChange={(e) => onChange({ ...value, q: e.target.value })}
placeholder="Subject, ticket or customer"
/>
</label>
<label>
Status
<select value={value.status} onChange={(e) => onChange({ ...value, status: e.target.value as TicketFilter['status'] })}>
<option value="">All</option>
{STATUSES.map((s) => (
<option key={s} value={s}>
{s}
</option>
))}
</select>
</label>
<label>
Team
<select value={value.team} onChange={(e) => onChange({ ...value, team: e.target.value as TicketFilter['team'] })}>
<option value="">All</option>
{TEAMS.map((t) => (
<option key={t} value={t}>
{t}
</option>
))}
</select>
</label>
<button type="submit">Search</button>
</form>
);
}
src/TicketList.tsx
import { useState } from 'react';
import { loadTickets } from './api';
import { TicketFilters } from './TicketFilters';
import { TicketRow } from './TicketRow';
import type { TicketFilter, TicketSummary } from './types';
export const NO_FILTER: TicketFilter = { status: '', team: '', q: '' };
/** The first 50 tickets that match the filters. For now, it loads them when you press Search. */
export function TicketList() {
const [filter, setFilter] = useState<TicketFilter>(NO_FILTER);
const [tickets, setTickets] = useState<TicketSummary[] | null>(null);
const [failure, setFailure] = useState<string | null>(null);
async function search() {
setFailure(null);
try {
setTickets(await loadTickets(filter, 50));
} catch (error) {
setFailure(`Could not load the tickets. ${(error as Error).message}`);
}
}
return (
<section className="list" aria-labelledby="list-heading">
<h2 id="list-heading">Tickets</h2>
<TicketFilters value={filter} onChange={setFilter} onSearch={search} />
{failure && (
<p className="error" role="alert">
{failure}
</p>
)}
{tickets === null ? (
<p className="muted">Press Search to load the tickets.</p>
) : (
<>
<p className="muted">{tickets.length === 0 ? 'No ticket matches.' : `Showing ${tickets.length} tickets.`}</p>
<ul className="rows">
{tickets.map((t) => (
<li key={t.ticket_id}>
<TicketRow ticket={t} />
</li>
))}
</ul>
</>
)}
</section>
);
}
src/NewTicketForm.tsx
import { useState, type FormEvent } from 'react';
import { sendTicket } from './api';
import type { NewTicket, TicketAccepted } from './types';
const EMPTY: NewTicket = { customer_id: '', subject: '', body: '' };
/** The checks that the browser can do before it sends the form. The API checks again. */
export function validate(t: NewTicket): Partial<Record<keyof NewTicket, string>> {
const errors: Partial<Record<keyof NewTicket, string>> = {};
if (!/^C-\d{4,5}$/.test(t.customer_id.trim())) errors.customer_id = 'Write a customer ID such as C-0022.';
if (!t.subject.trim()) errors.subject = 'Write a subject.';
else if (t.subject.length > 120) errors.subject = 'Use 120 characters or fewer.';
if (!t.body.trim()) errors.body = 'Write the customer’s message.';
return errors;
}
/** A form for a ticket that came in by phone. Every input is controlled: React state owns its value. */
export function NewTicketForm() {
const [values, setValues] = useState<NewTicket>(EMPTY);
const [errors, setErrors] = useState<ReturnType<typeof validate>>({});
const [sending, setSending] = useState(false);
const [answer, setAnswer] = useState<TicketAccepted | null>(null);
const [failure, setFailure] = useState<string | null>(null);
async function onSubmit(event: FormEvent) {
event.preventDefault();
const found = validate(values);
setErrors(found);
if (Object.keys(found).length > 0) return;
setSending(true);
setFailure(null);
try {
const result = await sendTicket({ ...values, customer_id: values.customer_id.trim() });
if (typeof result === 'string') {
setFailure(result);
} else {
setAnswer(result);
setValues(EMPTY);
}
} catch {
setFailure('The ticket was not sent. Is the API running?');
} finally {
setSending(false);
}
}
const field = (name: keyof NewTicket) => ({
id: `new-${name}`,
value: values[name],
'aria-invalid': errors[name] ? true : undefined,
'aria-describedby': errors[name] ? `new-${name}-error` : undefined,
onChange: (e: { target: { value: string } }) => setValues({ ...values, [name]: e.target.value }),
});
const error = (name: keyof NewTicket) =>
errors[name] && (
<p className="field-error" id={`new-${name}-error`}>
{errors[name]}
</p>
);
return (
<section className="card" aria-labelledby="new-heading">
<h2 id="new-heading">New ticket</h2>
<form onSubmit={onSubmit} noValidate className="form">
<label htmlFor="new-customer_id">Customer ID</label>
<input {...field('customer_id')} placeholder="C-0022" />
{error('customer_id')}
<label htmlFor="new-subject">Subject</label>
<input {...field('subject')} />
{error('subject')}
<label htmlFor="new-body">Message</label>
<textarea {...field('body')} rows={4} />
{error('body')}
<button type="submit" disabled={sending}>
{sending ? 'Sending…' : 'Send ticket'}
</button>
</form>
{failure && (
<p className="error" role="alert">
{failure}
</p>
)}
{answer && (
<p role="status">
Saved as {answer.ticket_id}. The AI work is {answer.state} (job {answer.job_id}).
</p>
)}
</section>
);
}
src/App.tsx
import { NewTicketForm } from './NewTicketForm';
import { TicketList } from './TicketList';
/** The page: a header, the ticket list and the form for a new ticket. */
export function App() {
return (
<>
<header className="top">
<h1>Larkfield ticket desk</h1>
</header>
<main className="layout">
<TicketList />
<NewTicketForm />
</main>
</>
);
}
src/TicketList.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { expect, test } from 'vitest';
import { apiError, installFakeApi, json, ticket } from './test/fakeApi';
import { TicketList } from './TicketList';
test('shows the tickets after Search', async () => {
installFakeApi(() => json(200, { items: [ticket(1), ticket(2, { status: 'pending' })], next: null }));
render(<TicketList />);
await userEvent.click(screen.getByRole('button', { name: 'Search' }));
expect(await screen.findByText('Ticket number 1')).toBeInTheDocument();
expect(screen.getByText('Pending')).toBeInTheDocument();
});
test('says so when the API fails', async () => {
installFakeApi(() => apiError(503, 'unavailable', 'The ticket service is not available.'));
render(<TicketList />);
await userEvent.click(screen.getByRole('button', { name: 'Search' }));
expect(await screen.findByRole('alert')).toHaveTextContent('Could not load the tickets. The API answered 503');
});

src/NewTicketForm.test.tsx est le fichier src/features/jobs/NewTicketForm.test.tsx de l’instantané end-of-m02, avec l’importation changée pour from './test/fakeApi'.

Dans NewTicketForm, field('subject') retourne les props d’un champ : ses id, value, onChange, et deux attributs d’accessibilité en cas d’erreur. {...field('subject')} les répartit sur le champ. {failure && <p …>} affiche le paragraphe seulement quand failure a une valeur. noValidate désactive les messages du navigateur, car le formulaire affiche les siens.

Testing Library teste un composant comme une personne l’utilise. Cette bibliothèque trouve les éléments par leur rôle et leur libellé, puis elle tape et clique. Elle ne regarde jamais l’état du composant. Lisez le deuxième test de NewTicketForm.test.tsx :

render(<NewTicketForm />);
await userEvent.click(screen.getByRole('button', { name: 'Send ticket' }));
expect(screen.getByLabelText('Customer ID')).toHaveAttribute('aria-invalid', 'true');
expect(screen.getByText('Write a subject.')).toBeInTheDocument();
expect(fake).not.toHaveBeenCalled();

Il appuie sur Send ticket (envoyer le billet) dans un formulaire vide. Puis il vérifie ce qu’une personne verrait. Le champ Customer ID est marqué comme invalide, « Write a subject. » (écrivez un objet) apparaît à l’écran, et aucune requête n’a été envoyée. installFakeApi remplace fetch par une simulation, donc aucune API n’a besoin de fonctionner. Exécutez tous les tests :

Fenêtre de terminal
npm test

La fin de la sortie :

ℹ tests 21
ℹ pass 21
ℹ fail 0
RUN v5.0.3 …/ticket-desk
Test Files 3 passed (3)
Tests 8 passed (8)

La première partie correspond aux 21 vérifications de l’API simulée, exécutées par l’outil de test intégré à Node.js. Ensuite, Vitest exécute les 8 tests dans src/ : 3 pour les requêtes, 2 pour la liste et 3 pour le formulaire.

  1. Vérifiez que l’API simulée fonctionne dans le premier terminal. Sinon, démarrez-la : npm run api.

  2. Dans le deuxième terminal, démarrez Vite : npm run dev. Il affiche Local: http://localhost:5173/ (adresse locale).

  3. Ouvrez http://localhost:5173/. Vous voyez Press Search to load the tickets. (appuyez sur Rechercher pour charger les billets) et le formulaire vide.

  4. Appuyez sur Search (rechercher). La liste affiche Showing 50 tickets. (50 billets affichés). La première ligne est T-80010, le billet d’exercice.

  5. Choisissez pending (en attente) dans Status (état), puis appuyez de nouveau sur Search. Chaque ligne porte maintenant l’étiquette Pending (en attente).

Le bureau des billets de Larkfield dans un navigateur. À gauche, la liste Tickets (billets) avec un champ de recherche, les menus Status (état) et Team (équipe), un bouton Search (rechercher), le texte Showing 50 tickets (50 billets affichés) et des lignes comme T-80010 Return label for my order LK-300210 (étiquette de retour pour ma commande LK-300210), Test Customer (client test), other (autre), avec une étiquette Open (ouvert). À droite, le formulaire New ticket (nouveau billet) avec Customer ID (identifiant du client), Subject (objet) et Message (message), ainsi qu'un bouton Send ticket (envoyer le billet).
Le bureau après avoir appuyé sur Search (rechercher) : deux composants côte à côte et 50 lignes affichées à partir d'un seul tableau. L’image est en anglais.

Appuyez maintenant sur Send ticket (envoyer le billet) avec le formulaire vide. Chaque champ affiche son propre message. Le terminal de l’API simulée n’affiche aucune nouvelle ligne POST : le formulaire n’a rien envoyé.

Le formulaire New ticket (nouveau billet) après avoir appuyé sur Send ticket (envoyer le billet) avec tous les champs vides. Sous Customer ID (identifiant du client) : Write a customer ID such as C-0022 (écrivez un identifiant de client comme C-0022). Sous Subject (objet) : Write a subject (écrivez un objet). Sous Message : Write the customer's message (écrivez le message du client).
validate() a trouvé trois erreurs, et React a affiché un message sous chaque champ. L’image est en anglais.

Saisissez C-0022, Parcel lost (colis perdu) et It did not arrive. (il n’est pas arrivé), puis appuyez sur Send ticket. Le formulaire se vide et une ligne indique Saved as T-500001. The AI work is queued (job 1). (enregistré sous T-500001; le travail de l’IA est en file d’attente, tâche 1). Les numéros augmentent de un pour chaque billet envoyé pendant que l’API simulée fonctionne.

Quand utiliser React, et ce qu’il coûte. Utilisez-le quand un écran comporte plusieurs parties qui dépendent de données changeantes : listes, filtres, formulaires et mises à jour en direct. Pour une page avec un seul formulaire qui ne change jamais, du HTML et quelques lignes de JavaScript suffisent. Le module 1 l’a montré. React a des coûts. Chaque visiteur le télécharge avant que le bureau puisse s’afficher. À lui seul, react-dom occupe 64,1 ko après compression, comme le montre Mesurer dans le navigateur. Il faut aussi une étape de construction et une nouvelle façon de penser : vous décrivez, et React met à jour.

Erreur courante

Un champ qui ne vous laisse pas saisir de texte

Symptôme : Teodor écrit le champ Subject (objet) ainsi : <input id="new-subject" value={values.subject} />. La page affiche le champ, mais la saisie ne fait rien : après avoir saisi Hello, le champ reste vide. La console du navigateur (Developer Tools › Console, soit outils de développement › console) affiche une erreur :

You provided a `value` prop to a form field without an `onChange` handler. This will render a read-only field. If the field should be mutable use `defaultValue`. Otherwise, set either `onChange` or `readOnly`.

Cause : le champ est contrôlé, car sa valeur vient de l’état. La saisie déclenche un événement de changement, mais rien n’appelle setValues. L’état reste donc '', et React affiche de nouveau ''.

Correction : donnez à chaque champ contrôlé value et onChange, comme le fait la fonction utilitaire field(). Si un champ n’a pas besoin d’état, omettez value et lisez le champ à l’envoi du formulaire. Le module 1 le faisait avec FormData.

Conséquence dans le travail avec l’IA : plus tard dans le cours, un bouton Use the draft (utiliser le brouillon) insère le brouillon de l’IA dans un champ de réponse. Cela fonctionne seulement si le champ est contrôlé. Un champ qui garde sa propre copie du texte n’affiche pas le brouillon.

Erreur courante

Une liste sans clés

Symptôme : Tomás retire key={t.ticket_id}, parce que « la liste fonctionne sans ça ». Les lignes apparaissent, mais la console affiche une erreur :

Each child in a list should have a unique "key" prop.
Check the render method of `TicketList`. See https://react.dev/link/warning-keys for more information.

Cause : sans clés, React associe les lignes de deux rendus selon leur position. Quand un nouveau billet arrive en haut, toutes les positions changent. Tout ce qu’une ligne garde en mémoire reste alors associé au mauvais billet.

Correction : donnez à chaque élément une clé unique dans la liste et propre à cet élément : le numéro du billet. N’utilisez pas la position (index). N’utilisez pas non plus Math.random() : il crée une nouvelle clé à chaque rendu. React doit donc recréer chaque ligne à chaque rendu.

Vérifiez votre compréhension

Quelle est la différence entre une prop et l'état? Donnez un exemple de chacun dans le bureau.

Afficher la réponse

Une prop (propriété) est une valeur que le parent donne à un composant; le composant ne fait que la lire. TicketRow reçoit ticket comme prop, et StatusBadge reçoit status. L’état est une valeur qui appartient à un composant et qu’il peut modifier avec sa fonction de mise à jour. Un changement amène React à refaire le rendu du composant. TicketList possède filter et tickets, et NewTicketForm possède values. La même valeur peut être un état dans un composant et une prop dans son enfant. filter est un état dans TicketList et la prop value dans TicketFilters.

Vérifiez votre compréhension

Prédisez : le champ Customer ID (identifiant du client) est vide, et vous saisissez C. Quelles fonctions s'exécutent, dans quel ordre, et que contient values après l'appui sur la touche?

Afficher la réponse

Le gestionnaire onChange du champ s’exécute et appelle setValues({ ...values, customer_id: 'C' }). React appelle ensuite de nouveau NewTicketForm. Dans ce rendu, values vaut { customer_id: 'C', subject: '', body: '' }. React compare le résultat à la page et modifie seulement le champ, qui affiche maintenant C. Rien n’est envoyé à l’API : cela se produit seulement dans onSubmit.

Vérifiez votre compréhension

Pourquoi le filtre se trouve-t-il dans TicketList et non dans TicketFilters? Quel problème surviendrait si les deux en gardaient une copie?

Afficher la réponse

Deux composants ont besoin du filtre : TicketFilters l’affiche et le modifie, et TicketList l’envoie avec la requête. Une valeur a un seul propriétaire, le parent commun le plus proche. Ainsi, TicketList possède le filtre et le transmet avec onChange : c’est remonter l’état. Avec deux copies, l’une changerait pendant la saisie, mais pas l’autre. La recherche enverrait alors un ancien filtre. L’écran afficherait une chose, tandis que la requête en utiliserait une autre.

Récapitulatif

  • Un composant est une fonction qui retourne ce qu’une partie de l’écran affiche. Ses props viennent de son parent. Son état est sa propre mémoire, modifiée seulement avec la fonction de mise à jour. Quand l’état change, React appelle de nouveau le composant et met à jour la page.
  • JSX est un ensemble de balises semblables au HTML dans TypeScript (className, et {…} pour les valeurs). Un fichier contenant du JSX se termine par .tsx.
  • Les événements sont des props comme onClick, onChange et onSubmit. Les données descendent dans l’arbre; les événements remontent par les fonctions fournies par le parent.
  • Un champ contrôlé affiche l’état et le modifie dans onChange, pour garder le texte à un seul endroit.
  • Chaque élément d’une liste a besoin d’une clé stable et unique, comme le numéro du billet.
  • Quand deux composants ont besoin de la même valeur, remontez l’état jusqu’à leur parent commun le plus proche.
  • Testing Library teste un composant comme une personne l’utilise : par les rôles, les étiquettes, la saisie et les clics.

Le bureau fonctionne, mais tous ses fichiers se trouvent côte à côte dans src/. Deux composants gèrent chacun les erreurs de l’API à leur façon. Ensuite, vous organisez le code par responsabilité. Vous verrez pourquoi c’est important dès la première requête qui échoue.

Leçon suivante : Organiser par responsabilité