Aller au contenu
English

Interactions accessibles

  • Leçon 18
  • 55 min
  • Module 6 : Sécurité, accessibilité et remise du travail

Où nous en sommes

Dans la leçon précédente, nous avons sécurisé le bureau : le Markdown du brouillon ne peut pas exécuter de code, et aucun secret n'arrive au navigateur. Mais Camille utilise le clavier et un lecteur d'écran pendant une partie de la journée, et avec ces outils, le bureau perd le focus et ne dit rien du brouillon. Dans cette leçon, nous rendons la tâche principale utilisable au clavier et avec un lecteur d'écran, qui annonce chaque changement d'état une fois. Un bulletin de circulation à la radio montre l'idée.

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

Ce que vous saurez faire

Rendez la tâche principale du bureau utilisable au clavier et avec un lecteur d’écran. Le focus suit le travail, chaque commande a un nom et le texte offre assez de contraste. Un lecteur d’écran annonce chaque changement d’état une fois, jamais chaque morceau du brouillon reçu en flux continu.

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

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet après Limites de sécurité du navigateur, avec npm test à 27 et 46 vérifications réussies.
  • npm run api et npm run dev dans deux terminaux, et le bureau ouvert à http://localhost:5173/.
  • Facultatif : un lecteur d’écran. macOS offre VoiceOver (Cmd+F5); sur Windows, NVDA est gratuit.

L’équipe du cours a vérifié le bureau au clavier, avec l’arbre d’accessibilité du navigateur et Playwright dans Chromium, sur macOS. Elle ne l’a pas testé avec un vrai lecteur d’écran. Avant une vraie livraison, une personne qui en utilise un chaque jour devrait l’essayer.

Camille, qui travaille comme agent à Montréal, utilise le clavier et un lecteur d’écran pendant une partie de la journée. Pensez aux nouvelles de la circulation à la radio. Le bulletin dit « Le pont est fermé » quand quelque chose change. Il ne décrit pas chaque voiture qui traverse le pont. Un tel bulletin serait inutile : la phrase importante se perdrait parmi des centaines d’autres.

Imaginez maintenant une visiteuse dans un grand bureau. Un bon guide l’accompagne jusqu’à la salle de réunion et dit « C’est ici ». Un mauvais guide pointe vaguement vers le corridor et la laisse à la porte. Pour une personne qui utilise le clavier, le focus indique où elle se trouve. C’est l’élément sur lequel agit la prochaine touche.

Au début de ce module, l’équipe du cours a effectué la tâche principale de Camille au clavier seulement. Playwright a enregistré le déplacement du focus :

Action de Camille Destination du focus Ce que le lecteur d’écran annonce
Ouvre le bureau et appuie sur Tab Le lien Tickets (billets) dans l’en-tête Le lien : Camille doit parcourir l’en-tête sur chaque page
Appuie sur Enter sur T-80008 dans la liste Toujours la ligne dans la liste Rien : le billet de soutien s’est ouvert à droite, sans annonce
Appuie sur Write a draft (rédiger un brouillon), puis attend Le même bouton, maintenant Write a new draft (rédiger un nouveau brouillon) Rien : le panneau du brouillon a 0 région dynamique
Envoie un nouveau billet Aucun élément : le <body> Rien : « Saved as T-500001. » (enregistré sous T-500001) est du texte ordinaire

La dernière ligne est la pire. Pendant l’envoi du formulaire, son bouton est désactivé, et un bouton désactivé perd le focus. Le focus revient à la page elle-même. La prochaine pression de Camille sur Tab repart du haut de la page.

Tomás propose une solution au silence : « Fais du texte du brouillon une région dynamique. Camille entendra le brouillon à mesure qu’il arrive. » L’équipe du cours a essayé avec aria-live="polite" sur le texte reçu en flux continu. Elle a compté les changements de cette région pendant un brouillon :

  • aria-live sur le texte reçu en flux continu
  • un message d'état par changement d'état
La région dynamique de Tomás changeait à chaque morceau de texte : 30 fois pour T-64704 et 28 pour T-80008. Le message d'état du bureau change trois fois.
Description textuelle du graphique

Un graphique à quatre colonnes. Pour le billet T-64704, la région dynamique du texte reçu a changé 30 fois, et le message d’état, 3 fois. Pour le billet T-80008, le texte reçu a changé 28 fois, et le message d’état, 3 fois. Les trois messages d’état étaient : Demande de brouillon en cours, Rédaction du brouillon en cours et Brouillon terminé.

Chaque changement demande une annonce au lecteur d’écran : « Je suis », puis « Je suis désolé », puis « Je suis désolé que », et ainsi de suite. Cela arrive 30 fois en moins d’une seconde. Les lecteurs d’écran ne lisent pas tous la même chose à chaque changement, mais aucun ne rend cette expérience agréable. Pire encore, la phrase importante, « Une personne doit traiter ce billet », se perd parmi les morceaux. C’est la radio qui décrit chaque voiture.

Mesurer dans le navigateur a montré qu’afficher chaque morceau coûte à React moins de 0,01 ms par brouillon. Le processeur n’est donc pas la raison d’éviter de réagir à chaque morceau. C’est Camille.

L’accessibilité permet aux personnes ayant des capacités et des outils différents d’effectuer les mêmes tâches. Pour une interface, cinq vérifications couvrent l’essentiel du travail :

  1. Parcours au clavier. Tab parcourt les commandes dans l’ordre du HTML de la page. Chaque action fonctionne avec Enter ou Space. Un lien d’évitement, première commande de la page, saute l’en-tête pour atteindre le contenu principal.
  2. Focus. Le focus reste toujours visible : le bureau trace un contour de 3 pixels avec :focus-visible. Quand la personne demande un nouveau contenu, le code y déplace le focus. Un élément qui disparaît emporte le focus avec lui. Le focus ne doit donc jamais rester sur un tel élément.
  3. Noms. Chaque commande a un nom accessible : le texte d’un bouton ou le <label> d’un champ. Un texte indicatif n’est pas un nom, car il disparaît quand vous tapez.
  4. Contraste. Le texte doit se distinguer de son arrière-plan : au moins 4,5 pour 1 pour le texte normal. Il faut 3 pour 1 pour le grand texte et les contours.
  5. Annonces. Une région dynamique est un élément dont le lecteur d’écran lit les changements sans déplacer le focus. Utilisez-en une pour les courts changements d’état. role="status" (annonce polie) attend que le lecteur d’écran se taise; role="alert" interrompt. Réservez donc ce dernier aux erreurs qui exigent une action immédiate.

Le navigateur conserve une deuxième version de la page pour ces outils : l’arbre d’accessibilité. Chaque élément y possède un rôle (bouton, titre, état), un nom et un état. Un lecteur d’écran lit cet arbre, pas les pixels. Dans Chrome, ouvrez le panneau Elements (éléments) et choisissez l’onglet Accessibility (accessibilité) pour voir l’arbre d’un élément.

Playwright peut afficher l’arbre d’accessibilité d’un élément sous forme de texte : locator.ariaSnapshot(). Voici le panneau du brouillon de T-80008 après un brouillon terminé, au début de ce module. Le texte du brouillon est abrégé :

- region "AI draft":
- heading "AI draft" [level=3]
- paragraph: Draft finished. Check it before you use it.
- text: I’m sorry you haven’t received a delivery date for your garden shed. …
- paragraph: "Why: The customer is asking for a delivery date for an order that has shipped."
- paragraph: This draft has no sources. Check every fact in it yourself.
- button "Write a new draft"
- button "Use this draft"
- button "Discard"

Chaque bouton a un nom, ce qui est bien. Mais « Draft finished » (brouillon terminé) est un simple paragraphe. Camille l’entend seulement en s’y déplaçant, sans que rien n’indique de le faire. Après cette leçon, le même arbre contient un élément status (état) :

- region "AI draft":
- heading "AI draft" [level=3]
- status: Draft finished. No sources.
- paragraph: I’m sorry you haven’t received a delivery date for your garden shed. …

La ligne « Draft finished. Check it before you use it. » reste visible à l’écran. Elle signifie « Brouillon terminé. Vérifiez-le avant de l’utiliser. » Mais aria-hidden="true" la cache dans l’arbre. Sinon, Camille recevrait la même nouvelle deux fois. L’état donne l’information nécessaire en une phrase : le brouillon est prêt et n’a aucune source. Pour certains billets, il ajoute qu’une personne doit les traiter. Une fonction choisit la phrase pour chaque état :

État du brouillon Message d’état
connecting Demande de brouillon en cours…
streaming Rédaction du brouillon en cours… (une fois, jamais à chaque morceau)
done Brouillon terminé. Aucune source. (ou 1 source., 2 sources.), et A person must handle this ticket. (une personne doit traiter ce billet) au besoin
stopped Vous avez arrêté le brouillon. Le texte ci-dessous est incomplet.
interrupted La connexion a pris fin avant la fin du brouillon. Le texte ci-dessous est incomplet.
failed Aucun brouillon. et l’erreur en mots, par exemple : Le service d’IA ne répond plus. Votre travail est conservé. Réessayez.
invalid Le brouillon n’a pas réussi les vérifications. Ne l’utilisez pas. et la raison

Ce diagramme présente le parcours complet, avec le focus et les mots de chaque étape :

Sept lignes, une par étape de la tâche principale au clavier. Chaque ligne indique la touche utilisée, l'emplacement du focus et l'annonce du lecteur d'écran. 1, Tab : le lien d'évitement Aller au contenu principal. 2, taper abri de jardin dans Rechercher : le champ de recherche; annonce Affichage de 50 billets (d'autres sur le serveur); autre parcours : la liste échoue, une alerte indique que le service de billets est occupé, avec Réessayer. 3, Tab jusqu'à T-80008 et Enter : le titre du billet, où le code déplace le focus; annonce du titre Bonjour, où est ma commande LK-581106. 4, Enter sur Rédiger un brouillon : le même bouton, maintenant nommé Arrêter; annonce Demande de brouillon en cours, puis Rédaction du brouillon en cours. 5, attendre : le même bouton, maintenant Rédiger un nouveau brouillon; annonce Brouillon terminé, Aucune source; autre parcours : Arrêter, une connexion perdue ou une erreur, chacun avec sa propre phrase. 6, Enter sur Utiliser ce brouillon : le champ de réponse contenant le brouillon. 7, Enter sur Envoyer la réponse : le focus revient à la page, une limite connue; annonce Envoyé. Une ligne rouge au bas : jamais les 28 morceaux du brouillon, un par un.
La tâche principale au clavier : le focus à chaque étape et ce que les régions dynamiques et l'arbre d'accessibilité transmettent au lecteur d'écran. Jamais chaque morceau du brouillon.
Description textuelle du diagramme

Le diagramme comporte sept lignes, une par étape de la tâche principale, et quatre colonnes. Elles indiquent la touche utilisée par Camille, l’emplacement du focus, l’annonce du lecteur d’écran et les autres parcours avec d’autres mots. Ligne 1 : Tab place le focus sur le lien d’évitement Aller au contenu principal. Ligne 2 : Camille tape abri de jardin dans le champ nommé Rechercher. La région dynamique de la liste annonce Affichage de 50 billets (d’autres sur le serveur). Si la liste échoue, une alerte annonce Le service de billets est occupé, avec un bouton Réessayer. Ligne 3 : Tab jusqu’à la ligne T-80008, puis Enter; le code déplace le focus vers le titre du billet, Bonjour, où est ma commande LK-581106. Ligne 4 : Enter sur Rédiger un brouillon; le même bouton porte maintenant le nom Arrêter. L’état annonce Demande de brouillon en cours, puis Rédaction du brouillon en cours. Ligne 5 : à la fin du brouillon, le même bouton affiche Rédiger un nouveau brouillon. L’état annonce Brouillon terminé. Aucune source. Autre parcours : Arrêter, une connexion perdue ou une erreur ont chacun leur phrase. Par exemple : Vous avez arrêté le brouillon, La connexion a pris fin, ou Aucun brouillon, Le service d’IA ne répond plus. Ligne 6 : Enter sur Utiliser ce brouillon remplit le champ Répondre au client. Ligne 7 : Enter sur Envoyer la réponse; l’état annonce Envoyé., mais le focus revient à la page, une limite connue. Une ligne rouge au bas indique : jamais les 28 morceaux du brouillon, un par un, à mesure qu’ils arrivent.

  1. Créez src/ui/LiveRegion.tsx. C’est un élément d’état que seuls les lecteurs d’écran voient. La classe visually-hidden se trouve déjà dans src/styles.css :

    src/ui/LiveRegion.tsx
    /**
    * A short message for screen readers, read when it changes ("polite": after what the user hears
    * now). It is for changes of state only; never put every streamed piece of text here.
    */
    export function LiveRegion({ message }: { message: string }) {
    return (
    <p className="visually-hidden" role="status" aria-live="polite" aria-atomic="true">
    {message}
    </p>
    );
    }

    aria-atomic="true" demande au lecteur d’écran de lire le message entier, pas seulement les mots modifiés. L’élément reste dans la page, même quand le message est vide. Certains lecteurs d’écran ignorent une région dynamique qui apparaît en même temps que son texte.

  2. Dans src/features/draft/DraftPanel.tsx, ajoutez l’importation import { LiveRegion } from '../../ui/LiveRegion'; et remplacez l’importation de types par import type { DraftState, DraftStatus } from './draftMachine';. Ajoutez ensuite la fonction qui choisit la phrase, après STATUS_TEXT :

    src/features/draft/DraftPanel.tsx (after STATUS_TEXT)
    /** What a screen reader hears: one sentence when the state changes, never the streamed text. */
    export function announcement(s: DraftState): string {
    if (s.status === 'done' && s.draft) {
    const sources = s.draft.citations.length;
    return [
    'Draft finished.',
    sources ? `${sources} ${sources === 1 ? 'source' : 'sources'}.` : 'No sources.',
    s.draft.needs_human ? 'A person must handle this ticket.' : '',
    ].join(' ').trim();
    }
    if (s.status === 'failed' || s.status === 'invalid') return `${STATUS_TEXT[s.status]} ${s.problem ?? ''}`.trim();
    if (s.status === 'idle') return '';
    return STATUS_TEXT[s.status];
    }
  3. Dans le même fichier, remplacez la ligne d’état visible et le paragraphe d’erreur par ces quatre lignes :

    src/features/draft/DraftPanel.tsx (under the h3)
    <p className="draft-state" aria-hidden="true">
    {STATUS_TEXT[state.status]}
    </p>
    <LiveRegion message={announcement(state)} />
    {state.problem && <p className="error">{state.problem}</p>}

    L’erreur perd son role="alert" : l’état l’annonce déjà, et deux régions dynamiques l’annonceraient deux fois.

  4. Dans la branche du brouillon en texte brut, marquez le texte comme occupé pendant sa réception en flux continu. aria-busy indique aux outils d’assistance que ce contenu change encore :

    src/features/draft/DraftPanel.tsx (the streamed text)
    state.text && (
    <div className={unfinished ? 'draft-text muted' : 'draft-text'} aria-busy={running}>
    {state.text}
    </div>
    )
  5. Remplacez les deux boutons Stop (arrêter) et Write a draft (rédiger un brouillon) par un seul bouton dont le libellé change :

    src/features/draft/DraftPanel.tsx (the toolbar)
    {/* One button that changes its label: the keyboard focus stays on it when the stream
    starts and ends. Two different buttons would drop the focus to the top of the page. */}
    <button type="button" onClick={running ? stop : start}>
    {running ? 'Stop' : state.status === 'idle' ? 'Write a draft' : 'Write a new draft'}
    </button>
  6. Exécutez npm test. Quatre tests du panneau de brouillon échouent. La section Erreurs courantes ci-dessous explique pourquoi; corrigez-les comme elle l’indique.

  7. Dans src/features/tickets/TicketView.tsx, placez le focus sur le titre du billet de soutien quand un billet s’ouvre. Remplacez la première importation par import { useEffect, useRef, useState } from 'react';, puis ajoutez ceci après l’état prefill :

    src/features/tickets/TicketView.tsx (after the prefill state)
    // When a ticket opens, the focus moves to its heading: a keyboard or screen reader user is
    // taken to the new content, not left in the list.
    const heading = useRef<HTMLHeadingElement>(null);
    const loaded = ticket.isSuccess;
    useEffect(() => {
    if (loaded) heading.current?.focus();
    }, [loaded, ticketId]);

    Donnez ensuite au titre la référence et tabIndex={-1} : <h2 id="ticket-heading" ref={heading} tabIndex={-1}>. Un titre ne peut pas recevoir le focus par lui-même. tabIndex={-1} permet au code de lui donner le focus, sans l’ajouter à l’ordre de navigation avec Tab.

  8. Dans src/features/jobs/NewTicketForm.tsx, faites la même chose pour le résultat. Importez aussi useEffect et useRef, puis ajoutez ceci après l’état idempotencyKey :

    src/features/jobs/NewTicketForm.tsx (after the idempotencyKey state)
    // After sending, the focus moves to the result, so that a keyboard user is not left in an empty form.
    const saved = useRef<HTMLParagraphElement>(null);
    useEffect(() => {
    if (answer) saved.current?.focus();
    }, [answer]);

    Remplacez ensuite la ligne du résultat par <p className="success" ref={saved} tabIndex={-1}>.

  9. Dans src/App.tsx, ajoutez le lien d’évitement comme premier élément du fragment. Donnez à <main> un id et tabIndex={-1} :

    src/App.tsx (the start of the page)
    {/* The address after # is our router's, so the link moves the focus itself. */}
    <a
    className="skip-link"
    href="#main"
    onClick={(e) => {
    e.preventDefault();
    document.getElementById('main')?.focus();
    }}
    >
    Skip to the main content
    </a>
    src/App.tsx (the main element)
    <main className="layout" id="main" tabIndex={-1}>

    Le routeur du bureau lit la partie de l’adresse après #. Sans preventDefault(), le lien changerait l’adresse pour #main. Le routeur l’interpréterait comme la liste sans billet : {"page":"tickets","ticketId":null}. Le billet ouvert se fermerait.

  10. Exécutez npm test. La sortie se termine par ℹ pass 27 et Tests 48 passed (48) (48 tests réussis).

Répétez maintenant la tâche de Camille au clavier dans le navigateur. Rechargez la page et appuyez une fois sur Tab :

Le haut du bureau. Dans le coin supérieur gauche, au-dessus de l'en-tête, une boîte blanche au contour bleu affiche le lien Skip to the main content (aller au contenu principal).
Le premier appui sur Tab affiche le lien d'évitement. Entrée place le focus sur le contenu principal, après l'en-tête. L’image est en anglais.

Tapez garden shed dans Search (rechercher). Appuyez sur Tab jusqu’à ce que la ligne T-80008 ait le focus, puis sur Entrée. Le billet s’ouvre et son titre reçoit le focus. Appuyez sur Tab jusqu’à ce que Write a draft ait le focus, puis sur Entrée :

Le panneau de brouillon juste après un appui sur Entrée sur Write a draft. La ligne d'état indique Asking for a draft (demande d'un brouillon), et le bouton bleu Stop porte un contour de focus bleu.
Pendant la demande du brouillon et sa réception en flux continu, le focus reste sur le même bouton, maintenant nommé Stop. Entrée arrête le brouillon. L’image est en anglais.

Après les changements, l’essai de l’équipe du cours a donné ces résultats :

Action de Camille Destination du focus Ce que le lecteur d’écran annonce
Appuie sur Tab dans une nouvelle page Skip to the main content Le lien
Appuie sur Entrée sur T-80008 Le titre « Hello, where is my order LK-581106? » (bonjour, où est ma commande LK-581106?) Le titre
Appuie sur Write a draft, puis attend Le même bouton : Stop, puis Write a new draft (rédiger un nouveau brouillon) Asking for a draft… / Writing the draft… / Draft finished. No sources. (Demande d’un brouillon… / Rédaction du brouillon… / Brouillon terminé. Aucune source.)
Envoie un nouveau billet « Saved as T-500001. » (enregistré sous T-500001.) Le message; la progression de la tâche suit dans son propre état
La carte New ticket (nouveau billet) après l'envoi. Sous le formulaire vide, une boîte verte Saved as T-500001 porte un contour de focus bleu. En dessous, l'état de la tâche indique The AI work is done (le travail de l'IA est terminé), avec l'équipe shipping (expédition).
Après l'envoi, le focus passe au résultat. Le prochain appui sur Tab poursuit la navigation à partir de là, pas du haut de la page. L’image est en anglais.

Il reste une lacune. Après Send reply (envoyer la réponse), l’équipe du cours a retrouvé le focus sur <body> pendant son essai. Ce bouton est aussi désactivé pendant l’envoi. Un lecteur d’écran entend toujours « Sent. » (envoyé.), car ce message est un état. Le document de remise de la prochaine leçon l’indique comme une limite connue. La corriger de la même façon serait un bon premier changement pour la prochaine personne qui développera l’application.

Pourquoi un seul bouton, si le focus restait déjà en place?

Section intitulée « Pourquoi un seul bouton, si le focus restait déjà en place? »

Regardez de nouveau le premier tableau : au début du module, le focus restait déjà sur le bouton. Pourquoi? React comparait les deux versions de la barre d’outils et voyait un <button> au même endroit dans les deux. Il gardait donc le même élément et changeait seulement son texte et son gestionnaire de clic. C’était un hasard, pas un choix de conception. L’équipe du cours a donné aux deux boutons des key différentes, key="stop" et key="start". React créait alors un nouvel élément chaque fois. Le focus passait à <body> au début du brouillon, puis à sa fin. Un seul bouton au libellé changeant rend le bon comportement explicite, et le test de l’étape 6 le préserve.

Les couleurs du bureau sont des jetons dans src/styles.css. L’équipe du cours a calculé le contraste de chaque paire utilisée par le bureau. Elle a utilisé la formule des Règles pour l’accessibilité des contenus Web (WCAG) :

Texte et arrière-plan Contraste Texte normal (4,5:1)
Texte #1d2733 sur une carte #ffffff 15,11:1 conforme
Texte gris #56616d (identifiants des billets, indications) sur une carte 6,31:1 conforme
Texte gris #56616d sur la page #f4f6f8 5,83:1 conforme
Liens et contour de focus #1f5fa8 sur une carte 6,44:1 conforme
Texte du bouton #ffffff sur le bouton bleu 6,44:1 conforme
Texte d’erreur #a32020 sur l’arrière-plan d’erreur #fdeeee 6,69:1 conforme
Exemple construit : le gris plus clair de Tomás #9aa4ae sur une carte 2,53:1 non conforme

Tomás préfère un gris plus clair pour les indications : « Ça paraît plus calme. » À 2,53:1, il n’est pas conforme. Sous une lumière vive, même les personnes sans déficience visuelle ne peuvent pas le lire. Chrome affiche le contraste de n’importe quel texte. Dans le panneau Elements (éléments), cliquez sur une couleur dans le volet Styles (styles).

Quand utiliser chaque outil, et ce qu’il coûte. Déplacez le focus seulement quand l’utilisateur a demandé le nouveau contenu : un billet ouvert, un formulaire envoyé. Une tâche qui se termine en arrière-plan ne doit pas prendre le focus; elle reçoit un message d’état. Utilisez role="status" pour les changements d’état et role="alert" seulement pour les erreurs qui exigent une action immédiate. Ne placez jamais un texte qui change plusieurs fois par seconde dans une région dynamique. Le coût en code est faible, mais celui des tests est réel. Les vérifications au clavier prennent quelques minutes. Un test de bout en bout peut les répéter, comme dans la prochaine leçon. Un vrai test avec un lecteur d’écran demande du temps et, idéalement, une personne qui l’utilise chaque jour.

announcement() est une fonction ordinaire; vous pouvez donc la tester sans navigateur. Écrivez src/features/draft/announcement.test.ts avec ces cas. Prédisez d’abord la phrase pour chacun :

  • un brouillon terminé avec deux sources et needs_human: true;
  • un brouillon arrêté;
  • un brouillon qui a échoué, avec le problème « The AI service stopped answering. Your work is safe. Try again. » (le service d’IA ne répond plus. Votre travail est préservé. Réessayez.);
  • l’état initial, avant tout brouillon.

Utilisez fullDraft de src/test/stream.ts et initialDraft de draftMachine.ts.

Afficher la réponse
src/features/draft/announcement.test.ts
import { expect, test } from 'vitest';
import { fullDraft } from '../../test/stream';
import { announcement } from './DraftPanel';
import { initialDraft } from './draftMachine';
test('what a screen reader is told when a draft ends', () => {
const twoSources = { ...fullDraft, needs_human: true, citations: [fullDraft.citations[0], fullDraft.citations[0]] };
expect(announcement({ ...initialDraft, status: 'done', text: 'x', draft: twoSources })).toBe(
'Draft finished. 2 sources. A person must handle this ticket.',
);
expect(announcement({ ...initialDraft, status: 'stopped', text: 'Your refund' })).toBe(
'You stopped the draft. The text below is not complete.',
);
const problem = 'The AI service stopped answering. Your work is safe. Try again.';
expect(announcement({ ...initialDraft, status: 'failed', problem })).toBe(`No draft. ${problem}`);
expect(announcement(initialDraft)).toBe('');
});

Avec ce fichier, npx vitest run indique Tests 49 passed (49) (49 tests réussis). L’état initial donne volontairement une chaîne vide. Il n’y a rien à annoncer, et la région dynamique silencieuse attend le premier changement.

Erreur courante

Found multiple elements with the text (plusieurs éléments contenant ce texte ont été trouvés)

Symptôme : après l’étape 5, npm test affiche Tests 4 failed | 42 passed (46) (4 tests échoués et 42 réussis sur 46). Deux tests indiquent :

TestingLibraryElementError: Found multiple elements with the text: /You stopped the draft/

et deux autres indiquent :

TestingLibraryElementError: Unable to find role="alert"

Cause : les tests ont été écrits pour l’ancien panneau. Chaque phrase d’état se trouve maintenant deux fois dans la page. Une copie est visible, mais cachée de l’arbre d’accessibilité; l’autre est dans l’état destiné aux lecteurs d’écran. getByText trouve les deux. Et les erreurs n’ont plus de role="alert".

Correction : testez ce que reçoit un lecteur d’écran : l’état. Dans src/features/draft/DraftPanel.test.tsx, importez waitFor de @testing-library/react, puis modifiez les quatre vérifications :

expect(screen.getByRole('status')).toHaveTextContent('You stopped the draft.');
await waitFor(() => expect(screen.getByRole('status')).toHaveTextContent(/The connection ended before the draft was finished/));
expect(await screen.findByRole('status')).toHaveTextContent('No draft. The AI service stopped answering');
expect(await screen.findByRole('status')).toHaveTextContent('Write the reply yourself');

Dans le premier test, vérifiez aussi l’état : await waitFor(() => expect(screen.getByRole('status')).toHaveTextContent('Draft finished. 1 source.'));. Dans le test d’un brouillon refusé, utilisez await waitFor(() => expect(screen.getByRole('status')).toHaveTextContent('The draft did not pass the checks. Do not use it.'));. Ajoutez ensuite deux tests qui préservent les promesses de cette leçon :

test('a screen reader hears the changes of state, never the streamed text', async () => {
installFakeApi((_url, init) => openStream(tokens, init.signal));
render(<DraftPanel ticketId="T-64979" onUse={() => {}} />);
await userEvent.click(screen.getByRole('button', { name: 'Write a draft' }));
expect(await screen.findByText('Your refund is on its way.')).toBeInTheDocument();
expect(screen.getByRole('status')).toHaveTextContent(/^Writing the draft…$/);
});
test('the keyboard focus stays on the button when the stream starts and stops', async () => {
installFakeApi((_url, init) => openStream(tokens, init.signal));
render(<DraftPanel ticketId="T-64979" onUse={() => {}} />);
screen.getByRole('button', { name: 'Write a draft' }).focus();
await userEvent.keyboard('{Enter}');
const stop = await screen.findByRole('button', { name: 'Stop' });
expect(stop).toHaveFocus();
await userEvent.keyboard('{Enter}');
expect(screen.getByRole('button', { name: 'Write a new draft' })).toHaveFocus();
expect(screen.getByRole('status')).toHaveTextContent('You stopped the draft.');
});

Le fichier complet se trouve dans l’instantané end-of-m06.

Vérifiez votre compréhension

Tomás veut placer le texte du brouillon reçu en flux continu dans une région dynamique. Camille pourrait ainsi l'entendre à mesure qu'il arrive. Qu'a mesuré l'équipe du cours, et que fait le bureau à la place?

Afficher la réponse

Avec aria-live sur le texte reçu en flux continu, la région changeait une fois par fragment. Cela donnait 30 changements pour T-64704 et 28 pour T-80008. Chaque changement demande une nouvelle annonce. La seule phrase importante, comme « Une personne doit traiter ce billet », se perd parmi les autres. Le bureau garde un seul élément d’état qui change seulement avec l’état : « Asking for a draft… », « Writing the draft… », « Draft finished. No sources. ». Cela fait trois changements par brouillon. Camille lit le texte terminé au moment de son choix.

Vérifiez votre compréhension

Prédisez : les boutons Stop et Write a draft sont deux éléments différents, par exemple avec des clés différentes. Camille appuie sur Entrée sur Write a draft. Où est le focus pendant la réception du brouillon en flux continu, et pourquoi?

Afficher la réponse

Sur <body>, la page elle-même. Le bouton qui avait le focus est retiré, et un élément retiré emporte le focus avec lui. L’équipe du cours l’a mesuré avec deux boutons ayant des clés différentes. Le focus était sur body pendant la réception en flux continu, puis à la fin. Au début du module, React réutilisait par hasard le même élément <button>, donc le focus restait en place. Le bureau utilise maintenant un seul bouton au libellé changeant, et un test vérifie que le focus y reste.

Vérifiez votre compréhension

Vérification pratique : au clavier seulement, ouvrez T-80008 depuis la liste, rédigez un brouillon et arrêtez-le. Où doit être le focus après chaque étape, et que doit annoncer l'état à la fin?

Afficher la réponse

Après Entrée sur la ligne : sur le titre du billet « Hello, where is my order LK-581106? ». Après Entrée sur Write a draft : sur le même bouton, maintenant nommé Stop. Après Entrée sur Stop : sur le même bouton, maintenant nommé Write a new draft. L’état indique « You stopped the draft. The text below is not complete. » (vous avez arrêté le brouillon. Le texte ci-dessous est incomplet.). Dans le volet Accessibility (accessibilité) de Chrome, l’élément d’état a le rôle status et ce texte.

Récapitulatif

  • Cinq vérifications pour chaque tâche : navigation au clavier, focus visible qui suit le travail, noms pour chaque commande, contraste d’au moins 4,5:1 et courtes annonces des changements d’état.
  • Au début du module, ouvrir un billet laissait le focus dans la liste, et envoyer un billet le faisait passer à <body>. Le panneau de brouillon n’avait pas de région dynamique. Maintenant, le code place le focus sur le titre et sur le résultat, et un lien d’évitement vient en premier.
  • Une région dynamique sur le texte reçu en flux continu changeait 30 fois par brouillon. L’état du bureau change trois fois : demande, rédaction, fin, avec le nombre de sources et la nécessité d’une intervention humaine.
  • Un seul bouton au libellé changeant garde le focus; deux éléments le feraient passer à <body>, comme l’équipe du cours l’a mesuré.
  • Les tests ont été faits au clavier, avec l’arbre d’accessibilité et avec Playwright dans Chromium. Un vrai test avec un lecteur d’écran reste nécessaire avant la livraison.

Ensuite, vous testez tout le bureau, des composants à un parcours dans un vrai navigateur, et vous préparez sa remise.

Leçon suivante : Tester et livrer