🧭 DriverTourGuide

A framework-agnostic guided tour adapter built on top of driver.js, designed to work seamlessly with the TourGuide abstraction from @schorts/shared-kernel. Compose onboarding flows with type-safe steps and launch interactive UI tours with minimal setup.

🚀 Installation

npm install --save @schorts/driver-tour-guide

📦 Usage

1. Import styles

driver.js requires its CSS to be loaded. You can import it directly from this package:

import "@schorts/driver-tour-guide/driver-styles";

Or inject it dynamically (optional):

import { injectDriverStyles } from "@schorts/driver-tour-guide"

injectDriverStyles();

2. Create and start a tour

import { DriverTourGuide } from "@schorts/driver-tour-guide";
import { TourStep } from "@schorts/shared-kernel";

const steps: TourStep[] = [
  {
    title: "Welcome",
    description: "This is the starting point",
    side: "bottom",
    align: "center",
  },
  {
    element: "#next-button",
    title: "Next Step",
    description: "Click here to continue",
    side: "right",
    align: "start",
  },
];

const tour = new DriverTourGuide();

tour.setSteps(steps);

await tour.start();

🧱 API

DriverTourGuide

Implements the TourGuide interface from @schorts/shared-kernel.

Methods

setSteps(steps: TourStep[]): void — Sets all tour steps.

addStep(step: TourStep): void — Adds a single step to the tour.

start(): Promise<void> — Launches the tour using driver.js.

next(): Promise<void> — Advances to the next step.

previous(): Promise<void> — Goes to the previous step.

exit(): void — Exits the tour immediately.

Event Listeners

onStart(callback: () => void): void — Called when the tour starts.

onEnd(callback: () => void): void — Called when the tour ends.

onStepChange(callback: (step: TourStep, index: number) => void): void — Called when the tour moves to a new step.

🧩 TourStep

Defined in @schorts/shared-kernel:

type TourStep = {
  element?: string;
  title: string;
  description: string;
  side?: "top" | "right" | "bottom" | "left";
  align?: "start" | "center" | "end";
  onBeforeShow?: () => void | Promise<void>;
  onAfterShow?: () => void | Promise<void>;
  onHide?: () => void | Promise<void>;
}

🧠 Philosophy

• Type-safe: Built on strongly typed abstractions.
• Composable: Chainable API for fluent tour composition.
• Framework-agnostic: Works with React, Svelte, Vue, or vanilla JS.
• Extensible: Swap out Driver.js or customize behavior without changing your domain model.

📜 License

LGPL