guide

npm install @apollovisionlabs/guide-core @apollovisionlabs/guide-mui

guide construit l’accueil des nouveaux utilisateurs dans une application : les visites guidées qui font faire le tour du produit, et la checklist de premiers pas qui leur survit. Un item de la checklist peut lancer la visite qui l’enseigne, et la visite terminée coche l’item. @apollovisionlabs/guide-core contient la logique et ne dépend que de React. @apollovisionlabs/guide-mui en assure le rendu avec Material UI. Les deux paquets sont sous licence MIT ; les versions publiées sont sur la page du paquet, qui ne se périme pas.

Ce qui change par rapport aux autres

Une étape vise une clé logique portée par un attribut data-guide, pas un sélecteur CSS : la visite ne casse pas quand le balisage change. Si la cible n’est pas encore à l’écran, la bibliothèque l’attend, puis applique une politique au choix : ignorer, attendre ou lever une erreur.

Une visite peut traverser plusieurs pages en appelant une fonction de navigation fournie par l’application, si bien que la bibliothèque ne dépend d’aucun routeur. La mise en évidence est un seul calque SVG, mesuré avant le rendu du navigateur, donc il ne retarde jamais un changement d’étape.

L’accessibilité vit dans la couche logique et non dans la couche de rendu : piège à focus, annonce au lecteur d’écran à chaque étape, et respect de la préférence « animations réduites ». Une étape marquée interactive n’est volontairement pas modale, pour qu’un utilisateur à qui l’on demande de cliquer quelque part puisse l’atteindre au clavier.

Pourquoi l’écrire plutôt que la prendre sur étagère

Les deux bibliothèques existantes les plus abouties sont sous des licences incompatibles avec un produit fermé, et aucune bibliothèque de visites maintenue ne fait de rendu natif en Material UI.

Un exemple

import { GuideProvider, type Tour } from '@apollovisionlabs/guide-core';
import { GuideTour } from '@apollovisionlabs/guide-mui';

const tour: Tour = {
  id: 'welcome',
  steps: [
    {
      target: 'sidebar.projects',
      title: 'Vos projets',
      body: 'Tout ce que vous créez est rangé dans un projet.',
    },
  ],
};

export function App() {
  return (
    <GuideProvider tours={[tour]}>
      <nav data-guide="sidebar.projects">Projets</nav>
      <GuideTour />
    </GuideProvider>
  );
}

Vérification

Les deux paquets sont couverts par des tests unitaires et par des scénarios de bout en bout joués dans un vrai navigateur, tous exigés avant publication. La publication se fait depuis l’intégration continue, sans jeton stocké, avec une attestation de provenance signée et vérifiable sur le registre.