@yarlisai/guides

Produktunabhängige Guided-Tour-Engine — deklarative Schritte, Plan-/Rollen-basiertes Zielgruppen-Targeting und Lifecycle-Events, mit driver.js- und Headless-Adaptern.

Installation

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

Warum

@yarlisai/guides folgt dem Port/Adapter-Vertrag: Konsumenten hängen vom GuideEngine-Port ab und instanziieren zur Laufzeit einen Adapter. Die Engine weiß nichts von React, i18n, Plänen oder Analytics — Texte werden über einen Resolver aufgelöst übergeben, das Zielgruppen-Targeting ist deklarative Daten, und jeder Lifecycle-Übergang (started, step_viewed, cta_clicked, completed, skipped) wird als GuideEvent emittiert, damit der Host ihn persistieren oder tracken kann.

Mit v1 werden zwei Adapter ausgeliefert:

• headless — DOM-freie Engine (aus dem Haupt-Barrel exportiert) für Tests, CLI-Walkthroughs oder servergesteuerte Touren.
• driverjs — browserbasierte Popovers auf Basis von driver.js. driver.js ist eine optionale Peer-Dependency, und der Adapter wird nur über den Unterpfad @yarlisai/guides/adapters/driverjs bereitgestellt, damit er nie in Bundles landet, die ihn nicht verwenden. Das CSS bleibt auf der Host-Seite (import 'driver.js/dist/driver.css') und wird über die konfigurierbare popoverClass gestaltet.

Verwendung

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),
})

Die README des Pakets enthält einen vollständigen Quickstart. mybotbox-platform selbst ist der Referenz-Konsument — apps/sat/lib/guides/ zeigt das Thin-Shim-Muster, und apps/sat/components/onboarding/ steuert die Produkttour über den Port.

Siehe auch

• Quellcode
• npm
• ADR 0007 — Port/Adapter-Vertrag