Le moteur

Précédemment. Un tuto est une donnée : des étapes qui désignent chacune un élément par son nom data-tour, et disent ce qui les fait passer.

Le moteur tient en trois pièces, chacune avec une responsabilité :

Un état qui traverse les pages 🧭#

Un tuto commence sur une page et finit sur une autre. Un useState dans un composant disparaît quand la page change ; un état global en mémoire, quand la page se recharge. L’état du tuto vit donc dans le sessionStorage du navigateur : propre à l’onglet (deux onglets, deux tutos), effacé à sa fermeture.

// ⚠ Fichier introuvable : apps/web/src/features/tours/tour.store.ts// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.

Le fournisseur, sur toutes les pages#

TourProvider est monté une fois, dans les fournisseurs de l’application : il enveloppe toutes les pages, et continue d’exister quand la page change.

// ⚠ Fichier introuvable : apps/web/src/features/tours/TourProvider.tsx// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.

L’overlay d’une étape#

Suivre une cible qui bouge#

La cible d’une étape peut ne pas encore exister (la page charge ses données), bouger (on fait défiler, on redimensionne la fenêtre), ou changer de valeur (on tape). L’overlay ne s’abonne pas à chacun de ces événements : il regarde la cible à chaque image, par requestAnimationFrame.

// ⚠ Fichier introuvable : apps/web/src/features/tours/TourOverlay.tsx// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.

Une cible n’est retenue que si elle a une position à l’écran. Un même nom peut en effet désigner deux éléments, dont un seul s’affiche selon la largeur de l’écran — la barre du header sur un ordinateur, le bouton du menu sur un téléphone (chapitre 1) :

Un élément masqué par display: none (la classe hidden, ou xl:hidden sur grand écran) n’a aucun rectangle : getClientRects() est vide. L’ancienne version prenait le premier élément du document, la barre masquée sur un téléphone, et perçait le voile sur un rectangle de taille nulle, en haut à gauche.

Un voile percé, et des clics bloqués#

Le voile est un SVG plein écran, percé par un masque à l’emplacement de la cible : la cible reste nette, le reste s’assombrit. Mais un voile dessiné ne bloque rien — le SVG laisse passer les clics (pointer-events-none). Ce sont quatre panneaux transparents, posés autour du trou, qui captent les clics partout ailleurs : un clic à côté ne déclenche rien, sauf sur la cible.

Pour une étape d’explication (next), un cinquième panneau couvre la cible elle-même : on la montre, on ne la manipule pas. Sans lui, un clic sur le bouton « Créer » pendant l’étape qui explique la date enverrait le formulaire, et le tuto serait perdu.

Reconnaître l’action#

Le clic est écouté sur tout le document, en phase de capture (true) : avant que l’élément cliqué ne le reçoive, et quoi qu’il en fasse — même un composant qui arrête la propagation ne le cache pas au tuto. L’étape passe ensuite, au tour suivant de la boucle d’événements (setTimeout(…, 0)) : l’élément a d’abord traité son clic (ouvert le formulaire, suivi le lien).

Au clavier#

Échap quitte à tout moment. Et le curseur clavier ne sort pas de l’étape : s’il arrive ailleurs (Tab vers un lien caché sous le voile), il est ramené sur la cible ou la bulle. Pour une étape d’explication, il n’entre même pas dans la cible : le panneau posé dessus arrête la souris, mais Tab jusqu’au bouton « Envoyer » montré, puis Entrée, l’aurait cliqué. Les bloqueurs arrêtent la souris ; ce garde arrête le clavier.

Reste Entrée dans un champ à remplir : dans un <form>, elle envoie le formulaire. Sur la page du mot de passe oublié, l’adresse tapée rend le bouton actif, et Entrée partait avec le lien de réinitialisation. Pendant toute étape qui n’attend ni clic ni page, l’overlay écoute donc l’évènement submit en capture sur le document et l’annule : l’évènement n’atteint jamais React. Les étapes click et route le laissent passer — l’enregistrement d’un post, qui attend justement la page de l’article créé, en a besoin. Avec le curseur placé sur la bonne cible à chaque étape (plus haut), le tuto se suit entièrement sans souris (partie « Interface transverse », chapitre « L’accessibilité »).

Une étape perdue#

Une cible introuvable après huit secondes — un composant renommé sans la garde, une page en erreur — ne laisse pas l’utilisateur devant un voile muet. (Une étape facultative, elle, s’efface bien avant : son absence est prévue.) La bulle dit « Élément introuvable », n’offre plus que « Quitter », et le voile couvre toute la page : on ne peut ni avancer, ni agir à l’aveugle.

Récapitulatif#

À suivre#

Le moteur déroule un tuto une fois lancé. Reste à le proposer au bon visiteur, au bon endroit — et à vérifier, de bout en bout, qu’il se suit vraiment.