APOLLO VISION LABS

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.

La 0.3.0 ajoute les hotspots et permet à une étape d’avancer sur un clic de sa cible, et corrige un clignotement dans les rendus de la checklist et des hotspots pendant que leur lecture initiale du stockage est en vol. Rien ici ne casse à l’exécution. Si vous utilisez TypeScript et annotez StepPopoverLabels comme un objet complet, une ligne est à ajouter pour que cela recompile.

pnpm up @apollovisionlabs/guide-core @apollovisionlabs/guide-mui

guide-core passe de 0.2.0 à 0.3.0 et guide-mui de 0.3.0 à 0.4.0. Ils sont publiés ensemble, donc cette page couvre les deux à la fois.

Ce qu’on peut ignorer

Les visites, les checklists et la persistance fonctionnent exactement comme avant. Tour, Step, GuideProvider, GuideTour, useTour, useGuideStep, Checklist, ChecklistProvider, ChecklistLauncher, useChecklist, GuideStorage, createMemoryStorage et createBrowserStorage sont inchangés. Les événements de visite et de checklist sont inchangés, et les deux nouveaux événements de hotspot sont des ajouts à l’union GuideEvent, pas des remplacements.

Les hotspots sont facultatifs. Ne pas monter HotspotProvider laisse votre application exactement où elle était.

La seule chose à vérifier : StepPopoverLabels a un nouveau membre requis

StepPopoverLabels, exporté par @apollovisionlabs/guide-mui, a gagné un membre requis, awaitingAction : le texte affiché à la place du bouton Suivant pendant qu’une étape attend que l’utilisateur clique sa cible, via le nouveau advanceOn: 'click'.

interface StepPopoverLabels {
  next: string;
  previous: string;
  finish: string;
  close: string;
  awaitingAction: string; // nouveau, requis
}

La prop labels de GuideTour est un Partial<StepPopoverLabels>, donc passer des labels en ligne n’est pas affecté :

// Compile toujours, fonctionne toujours, rien à changer.
<GuideTour labels={{ next: 'Suivant', previous: 'Retour' }} />

Ce qui cesse de compiler, c’est une constante annotée comme un StepPopoverLabels complet :

// Avant la 0.3.0, ceci compilait.
const labels: StepPopoverLabels = {
  next: 'Suivant',
  previous: 'Retour',
  finish: 'Terminer',
  close: 'Fermer',
};

Ajoutez le nouveau membre et cela recompile :

const labels: StepPopoverLabels = {
  next: 'Suivant',
  previous: 'Retour',
  finish: 'Terminer',
  close: 'Fermer',
  awaitingAction: 'Cliquez sur l’élément mis en évidence pour continuer.',
};

Rien de tout cela ne change le comportement à l’exécution : un projet qui ne pose jamais advanceOn sur une étape n’affiche jamais ce texte, et un projet qui passe labels comme un Partial n’était jamais tenu de le fournir. C’est un changement au niveau des types pour un motif précis, pas une rupture de l’API publiée.

Changement de comportement : checklists et hotspots attendent leur lecture initiale du stockage

ChecklistProvider et HotspotProvider lisent la progression persistée de façon asynchrone. Avant la 0.3.0, Checklist, ChecklistLauncher et tout rendu maison dessinaient depuis l’état initial vide pendant que cette lecture était encore en vol, si bien qu’une checklist fermée depuis longtemps pouvait faire clignoter son lanceur à l’écran avant de disparaître, et qu’une checklist avec trois éléments sur quatre déjà faits pouvait afficher « 0 sur 4 » avant de sauter à « 3 sur 4 », à chaque chargement de page.

useChecklist gagne un membre restored, stabilisé par checklist : true immédiatement quand aucune prop storage n’a été fournie, et true une fois que la lecture propre à cette checklist se résout ou échoue dans les autres cas. useHotspots gagne le même membre restored, stabilisé une fois pour tout le provider, selon les mêmes règles. Checklist, ChecklistLauncher et Hotspots attendent tous cette valeur avant de dessiner quoi que ce soit.

Le seul effet visible : avec un stockage lent, une checklist ou un marqueur de hotspot apparaît maintenant un peu plus tard qu’avant, plutôt que d’apparaître d’un coup puis de sauter ou de clignoter un état périmé. Rien à changer dans votre code, sauf si vous avez construit votre propre rendu sur useChecklist ou useHotspots et voulez qu’il attende aussi restored.

Dans l’ordre

  1. Passez les deux paquets à leur version courante.
  2. Si vous annotez une constante StepPopoverLabels en entier plutôt que de passer des labels en ligne, ajoutez awaitingAction. Lancez le typecheck : rien d’autre n’a changé dans les types publics de l’un ou l’autre paquet.
  3. Éventuellement, ajoutez les hotspots. HotspotProvider et Hotspots sont nouveaux, et HotspotProvider peut partager l’instance de storage que vous passez déjà à GuideProvider et ChecklistProvider.

Pour aller plus loin