guide
Des visites guidées et une checklist de premiers pas pour React, avec un rendu Material UI.
npm install @apollovisionlabs/guide-core @apollovisionlabs/guide-muiDémonstration
L'application ci-dessous est fictive et tourne dans cette page : lancez la visite, elle changera d'écran toute seule.
En pratique
Cible par attribut data-guide
Une étape vise une clé portée par un attribut data-guide, et la bibliothèque attend la cible si elle n'est pas encore à l'écran.
Visites sur plusieurs pages
Une visite change de page en appelant la fonction de navigation fournie par l'application, sans dépendre d'un routeur.
Checklist persistée
Un item de checklist peut lancer la visite qui l'enseigne, et les deux partagent un seul contrat de stockage.
Accessibilité dans la couche logique
Piège de focus, annonce lecteur d'écran à chaque étape, et respect du mouvement réduit.
Documentation
9 pagesLe paquet en détail : installation, concepts, référence et migration.
- Démarrer
Installer les deux paquets, lancer une première visite, puis brancher le provider sur une vraie application.
- Visites
La forme d'une visite et de ses étapes, la politique de cible absente, les visites multipages, les étapes interactives, l'avancée sur un clic et le pilotage manuel.
- Checklist
Une liste de premiers pas, ce qui coche vraiment un élément, son lien avec les visites, et les deux composants qui l'affichent.
- Hotspots
Un marqueur sur un élément qui ouvre une courte explication et peut lancer une visite, ce qui le retire pour de bon, et quand il ne dessine plus rien du tout.
- Persistance
Comment guide conserve la progression des visites, des checklists et des hotspots, ce qu'exige le contrat GuideStorage, et ce qui se passe quand une lecture est lente.
- Accessibilité
Ce que guide fait pour un utilisateur au clavier et pour un lecteur d'écran, et les exceptions assumées.
- Référence de l'API
Tous les symboles exportés par guide-core et guide-mui, avec leur signature et ce qu'ils font.
- Migrer vers 0.2.0
Ce qui change pour une application en 0.1.x, dans l'ordre, et ce qui ne demande aucune attention.
- Migrer vers 0.3.0
Ce qui change pour une application en guide-core 0.2.0 et guide-mui 0.3.0, dans l'ordre, et la seule chose qui demande attention.
guide construit des visites guidées dans une application : le parcours qui montre son chemin à un nouvel utilisateur. La logique tient dans un paquet qui ne dépend que de React, le rendu Material UI dans un second.
Installation
npm install @apollovisionlabs/guide-core @apollovisionlabs/guide-muiExemple
import { GuideProvider, type Tour } from '@apollovisionlabs/guide-core';
import { GuideTour } from '@apollovisionlabs/guide-mui';
const tour: Tour = {
id: 'welcome',
steps: [
{
target: 'sidebar.projects',
title: 'Your projects',
body: 'Everything you create is grouped under a project.',
},
],
};
export function App() {
return (
<GuideProvider tours={[tour]}>
<nav data-guide="sidebar.projects">Projects</nav>
<GuideTour />
</GuideProvider>
);
}Ce que fait la bibliothèque
Une clé logique, pas un sélecteur CSS
Une étape vise une clé portée par un attribut data-guide, donc une visite
survit à un changement de balisage. Si la cible manque, la bibliothèque
l’attend, puis applique une politique au choix : ignorer, attendre ou échouer.
Plusieurs écrans, aucun routeur imposé
Une visite traverse les pages en appelant une fonction de navigation fournie par l’application. La bibliothèque ne dépend d’aucun routeur.
Un seul calque SVG
La mise en avant est un calque SVG unique, mesuré avant que le navigateur ne peigne.
L’accessibilité dans la couche logique
Piège de focus, annonce lecteur d’écran à chaque étape, respect du mouvement réduit. Une étape marquée interactive n’est volontairement pas modale, pour qu’un utilisateur au clavier atteigne l’élément qu’on lui demande de cliquer.
Une checklist à côté de la visite
Une visite enseigne un parcours. Une checklist est ce qui survit à la première session : une courte liste de premiers pas qui persiste, montre où l’on en est, et donne un endroit où revenir. Un item peut porter une visite, donc l’activer lance la visite qui l’enseigne, et la visite terminée coche l’item.
Les deux fonctionnalités partagent un seul contrat de stockage, donc une application qui persiste la progression d’une visite dans son propre serveur persiste la checklist par le même code.
Pourquoi l’avoir écrite
Les deux bibliothèques existantes les plus abouties sont sous des licences incompatibles avec un produit fermé, et aucune bibliothèque de visite guidée maintenue ne rend nativement avec Material UI.