@yarlisai/guides

Motor de visitas guiadas independiente del producto — pasos declarativos, segmentación por plan/rol, y eventos de ciclo de vida, con adaptadores driver.js y headless.

Instalación

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

Por qué

@yarlisai/guides sigue el contrato port/adapter: los consumidores dependen del puerto GuideEngine e instancian un adaptador en tiempo de ejecución. El motor no sabe nada sobre React, i18n, planes ni analíticas — el contenido llega resuelto a través de un resolver, la segmentación por audiencia es datos declarativos, y cada transición del ciclo de vida (started, step_viewed, cta_clicked, completed, skipped) se emite como un GuideEvent para que el host lo persista o rastree.

En la v1 se incluyen dos adaptadores:

• headless — motor sin DOM (exportado desde el barrel principal) para pruebas, recorridos por CLI o visitas guiadas impulsadas por el servidor.
• driverjs — popovers de navegador respaldados por driver.js. driver.js es una dependencia de pares opcional, y el adaptador se expone únicamente a través del subpath @yarlisai/guides/adapters/driverjs para que nunca acabe en bundles que no lo utilicen. El CSS permanece en el lado del host (import 'driver.js/dist/driver.css'), personalizado mediante el popoverClass configurable.

Uso

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

El README del paquete incluye una guía de inicio rápido completa. mybotbox-platform en sí es el consumidor de referencia — apps/sat/lib/guides/ muestra el patrón thin-shim y apps/sat/components/onboarding/ impulsa el tour del producto a través del puerto.

Ver también

• Fuente
• npm
• ADR 0007 — Contrato port/adapter