@yarlisai/guides

Moteur de visite guidée indépendant du produit — étapes déclaratives, ciblage d'audience par plan/rôle, et événements de cycle de vie, avec les adaptateurs driver.js + headless.

Installation

npm install @yarlisai/guides
# for the driver.js adapter:
npm install driver.js

Pourquoi

@yarlisai/guides suit le contrat port/adaptateur : les consommateurs dépendent du port GuideEngine et instancient un adaptateur à l'exécution. Le moteur ne sait rien de React, de l'i18n, des plans ou des analytics — le contenu arrive résolu via un resolver, le ciblage d'audience est une donnée déclarative, et chaque transition de cycle de vie (started, step_viewed, cta_clicked, completed, skipped) est émise sous forme de GuideEvent pour que l'hôte puisse la persister ou la suivre.

Deux adaptateurs sont fournis en v1 :

• headless — moteur sans DOM (exporté depuis le barrel principal) pour les tests, les walkthroughs en CLI, ou les visites pilotées côté serveur.
• driverjs — popovers navigateur basés sur driver.js. driver.js est une dépendance pair optionnelle, et l'adaptateur est exposé uniquement via le sous-chemin @yarlisai/guides/adapters/driverjs afin de ne jamais se retrouver dans les bundles qui ne l'utilisent pas. Le CSS reste côté hôte (import 'driver.js/dist/driver.css'), thématisé via la popoverClass configurable.

Utilisation

import { createGuideEngine, registerGuide, getGuide } from '@yarlisai/guides'

registerGuide({
  id: 'onboarding:build_agent',
  version: '2026.06',
  steps: [
    { id: 'canvas', anchor: 'canvas', i18nKey: 'tour.canvas' },
    {
      id: 'deploy',
      anchor: 'deploy-button',
      i18nKey: 'tour.deploy',
      audience: { roles: ['admin', 'editor'] },
    },
  ],
})

// Adapter selection is config — the chosen module is dynamic-imported.
const engine = await createGuideEngine('driverjs')

engine.start(getGuide('onboarding:build_agent')!, {
  copy: (step) => ({ title: t(`${step.i18nKey}.title`), body: t(`${step.i18nKey}.body`) }),
  labels: { next: t('next'), previous: t('back'), done: t('done'), progress: '{{current}}/{{total}}' },
  context: { plan: 'free', role: 'admin' },
  onEvent: (event) => analytics.track(event),
})

Le README du package fournit un démarrage rapide complet. mybotbox-platform lui-même est le consommateur de référence — apps/sat/lib/guides/ illustre le pattern thin-shim et apps/sat/components/onboarding/ pilote la visite produit via le port.

Voir aussi

• Source
• npm
• ADR 0007 — Contrat port/adaptateur