Normalize hooks and write docs

docs/package.json

@@ -16,7 +16,7 @@
     "@types/react": "^18.0.21",
     "@types/react-dom": "^18.0.6",
     "astro": "^2.7.0",
-    "driver.js": "1.1.4-next.0",
+    "driver.js": "1.1.5-next.0",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "react-fast-marquee": "^1.6.0",

docs/pnpm-lock.yaml

@@ -24,8 +24,8 @@ dependencies:
     specifier: ^2.7.0
     version: 2.7.0
   driver.js:
-    specifier: 1.1.4-next.0
-    version: 1.1.4-next.0
+    specifier: 1.1.5-next.0
+    version: 1.1.5-next.0
   react:
     specifier: ^18.0.0
     version: 18.2.0
@@ -1376,8 +1376,8 @@ packages:
   /dlv@1.1.3:
     resolution: {integrity: sha512-+HlytyjlPKnIG8XuRG8WvmBP8xs8P71y+SKKS6ZXWoEgLuePxtDoUEiH7WkdePWrQ5JBpE6aoVqfZfJUQkjXwA==}
 
-  /driver.js@1.1.4-next.0:
-    resolution: {integrity: sha512-3pxb5HcBKbYKpJCsHxNU+dNwfds6iUTmI1H33l+r5EkMa/5Mb11B+jejvHL0gRvbzkwx/8d6VudCDIwyw4R9cg==}
+  /driver.js@1.1.5-next.0:
+    resolution: {integrity: sha512-/S8err9QIkEerXGj44kssnqR8iTioDQplmA5Foj5g6AMxWMGTu6FaAjMrRksm50jVJ1SkyOPw8N7QEGdND5IfQ==}
     dev: false
 
   /dset@3.1.2:

docs/src/components/CodeSample.tsx

@@ -0,0 +1,42 @@
+import type { Config, DriveStep } from "driver.js";
+import { driver } from "driver.js";
+import "driver.js/dist/driver.css";
+
+type CodeSampleProps = {
+  heading: string;
+
+  config?: Config;
+  highlight?: DriveStep;
+  tour?: DriveStep[];
+
+  id?: string;
+  className?: string;
+  children: any;
+};
+
+export function CodeSample(props: CodeSampleProps) {
+  const { heading, id, children, className, config, highlight, tour } = props;
+
+  function onClick() {
+    if (highlight) {
+      const driverObj = driver();
+      driverObj.highlight(highlight);
+    } else if (tour) {
+      const driverObj = driver({
+        ...config,
+        steps: tour,
+      });
+      driverObj.drive();
+    }
+  }
+
+  return (
+    <div id={id} className={className}>
+      <p className="text-lg -mt-0 font-medium text-black -mb-3 rounded-md">{ heading }</p>
+      <div className="-mb-4">{children}</div>
+      <button onClick={onClick} className="w-full rounded-md bg-black p-2 text-white">
+        Show me an Example
+      </button>
+    </div>
+  );
+}

docs/src/components/DocsHeader.astro

@@ -3,7 +3,7 @@ import { getFormattedStars } from "../lib/github";
 
 const starCount = await getFormattedStars('kamranahmedse/driver.js');
 ---
-<div class="border-b flex items-center justify-between">
+<div class="border-b flex items-center justify-between" docs-header>
   <div class="w-[300px] text-right flex justify-end">
     <a href="/" class="flex items-center py-4 pr-5 border-r">
       <img src="/driver-head.svg" alt="Astro" class="w-8 h-8 mr-2" />

docs/src/components/FeatureMarquee.tsx

@@ -2,18 +2,18 @@ import React from "react";
 import Marquee from "react-fast-marquee";
 
 const featureList = [
-  "Open Source",
-  "Written in TypeScript",
-  "No dependencies",
-  "Vanilla JavaScript",
+  "Supports all Major Browsers",
+  "Works on Mobile Devices",
+  "Highly Customizable",
   "Light-weight",
+  "No dependencies",
   "Feature Rich",
-  "Highly Customizable",
-  "Supports all Major Browsers",
+  "MIT Licensed",
+  "Written in TypeScript",
+  "Vanilla JavaScript",
   "Easy to use",
   "Accessible",
   "Frameworks Ready",
-  "MIT Licensed",
 ];
 
 export function FeatureMarquee() {

docs/src/components/examples/SimpleHighlight.tsx

@@ -1,11 +1,11 @@
 import { useEffect } from "react";
 import { Config, driver } from "driver.js";
-import "driver.js/dist/driver.js.css";
+import "driver.js/dist/driver.css";
 
 import type { DriveStep } from "driver.js";
 
 type SimpleHighlightProps = {
-  config: Config;
+  config?: Config;
   step: DriveStep;
 };
 

docs/src/content/guides/basic-usage.mdx

@@ -4,29 +4,65 @@ groupTitle: "Introduction"
 sort: 2
 ---
 
-import { SimpleHighlight } from "../../components/examples/SimpleHighlight.tsx";
+import { CodeSample } from "../../components/CodeSample.tsx";
 
 Once installed, you can import and start using the library. Given below is a simple example of how to highlight a single element.
 
-<div id="simple-example">
-  ```js
-  import Driver from 'driver.js';
-  import 'driver.js/dist/driver.js.css';
-
-  const driver = new Driver();
-  driver.highlight({
-    element: '#some-element',
-    popover: {
-      title: 'Title for the Popover',
-      description: 'Description for it',
-    },
+<CodeSample heading='Highlighting a simple Element' id={"some-element"} highlight={{
+  element: '#some-element',
+  popover: {
+    title: 'Title for the Popover',
+    description: 'Description for it',
+  },
+}} client:load>
+```js
+import { driver } from "driver.js";
+import "driver.js/dist/driver.css";
+
+const driverObj = driver();
+driverObj.highlight({
+  element: '#some-element',
+  popover: {
+    title: 'Title for the Popover',
+    description: 'Description for it',
+  },
 });
-  ```
-  <SimpleHighlight step={{
-    element: "#simple-example",
-    popover: {
-      title: "Title for the Popover",
-      description: "Description for it",
-    },
-  }} client:load />
-</div>
+```
+</CodeSample>
+
+There are many different options to customize the highlight e.g. change position, change overlay color, control interactions, change buttons etc. You can find more details about the options in the [API Reference](/api-reference).
+
+The same configuration passed to the `highlight` method can be used to create a tour. Given below is a simple example of how to create a tour with a single step.
+
+<CodeSample
+  heading={'Basic Tour Example'}
+  config={{
+    showProgress: true,
+  }}
+  tour={[
+    { element: '#tour-example', popover: { title: 'Highlight Anything', description: 'You can highlight anything on the page.' }},
+    { element: '#tour-example pre', popover: { title: 'Control with Keyboard', description: 'You can use your keyboard to highlight elements.' }},
+    { popover: { title: 'Control with Keyboard', description: 'You can use your keyboard to highlight elements.' }},
+    { element: '#tour-example code .line:first-child', popover: { title: 'Control with Code', description: 'You can use the code to highlight elements.' }},
+    { element: '#tour-example code .line:nth-child(2)', popover: { title: 'Control with Code', description: 'You can use the code to highlight elements.', side: "bottom", align: 'start' }},
+  ]}
+  id={"tour-example"}
+  client:load
+>
+```js
+import { driver } from "driver.js";
+import "driver.js/dist/driver.css";
+
+const driverObj = driver({
+  showProgress: true,
+  steps: [
+    { elment: '.page-header', popover: { title: 'Title', description: 'Description' } },
+    { element: '.top-nav', popover: { title: 'Title', description: 'Description' } },
+    { element: '.sidebar', popover: { title: 'Title', description: 'Description' } },
+    { element: '.footer', popover: { title: 'Title', description: 'Description' } },
+  ]
+});
+
+driver.drive();
+```
+</CodeSample>

docs/src/content/guides/configuration.mdx

@@ -0,0 +1,79 @@
+---
+title: "Configuration"
+groupTitle: "Introduction"
+sort: 3
+---
+
+import { CodeSample } from "../../components/CodeSample.tsx";
+
+Driver.js is built to be highly configurable. You can configure the driver globally, or per step. You can also configure the driver on the fly, while it's running.
+
+> Driver.js is written in TypeScript. Configuration options are mostly self-explanatory. Also, if you're using an IDE like WebStorm or VSCode, you'll get autocomplete and documentation for all the configuration options.
+
+## Popover Configuration
+
+The popover is the main UI element of Driver.js. It's the element that highlights the target element, and shows the step content. You can configure the popover globally, or per step. Given below are some of the available configuration options.
+
+```typescript
+type Popover = {
+  // Title and descriptions shown in the popover.
+  // You can use HTML in these. Also, you can
+  // omit one of these to show only the other.
+  title?: string;
+  description?: string;
+
+  // The position and alignment of the popover
+  // relative to the target element.
+  side?: "top" | "right" | "bottom" | "left";
+  align?: "start" | "center" | "end";
+
+  // Array of buttons to show in the popover.
+  // When highlighting a single element, there
+  // are no buttons by default. When showing
+  // a tour, the default buttons are "next",
+  // "previous" and "close".
+  showButtons?: ("next" | "previous" | "close")[];
+  // An array of buttons to disable. This is
+  // useful when you want to show some of the
+  // buttons, but disable some of them.
+  disableButtons?: ("next" | "previous" | "close")[];
+
+  // Text to show in the buttons. `doneBtnText`
+  // is used on the last step of a tour.
+  nextBtnText?: string;
+  prevBtnText?: string;
+  doneBtnText?: string;
+
+  // Whether to show the progress text in popover.
+  showProgress?: boolean;
+  // Template for the progress text. You can use
+  // the following placeholders in the template:
+  //   - {{current}}: The current step number
+  //   - {{total}}: Total number of steps
+  // Defaults to following if `showProgress` is true:
+  //   - "{{current}} of {{total}}"
+  progressText?: string;
+
+  // Custom class to add to the popover element.
+  // This can be used to style the popover.
+  popoverClass?: string;
+
+  // Hook to run after the popover is rendered.
+  // You can modify the popover element here.
+  // Parameter is an object with references to
+  // the popover DOM elements such as buttons
+  // title, descriptions, body, etc.
+  onPopoverRendered?: (popover: PopoverDOM) => void;
+
+  // Callbacks for button clicks. You can use
+  // these to add custom behavior to the buttons.
+  // Each callback receives the following parameters:
+  //   - element: The target DOM element of the step
+  //   - step: The step object configured for the step
+  //   - options.config: The current configuration options
+  //   - options.state: The current state of the driver
+  onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
+  onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
+  onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
+}
+```

docs/src/content/guides/installation.mdx

@@ -23,18 +23,18 @@ Alternatively, you can use CDN and include the script in your HTML file:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/driver.js@1.1.1-next.0/dist/driver.js.iife.js"></script>
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/driver.js@1.1.1-next.0/dist/style.css"/>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/driver.js@1.1.1-next.0/dist/driver.css"/>
 ```
 
 ## Start Using
 Once installed, you can import the package in your project. The following example shows how to highlight an element:
 
 ```js
-import Driver from "driver.js";
+import driver from "driver.js";
 import "driver.js/dist/driver.css";
 
-const driver = new Driver();
-driver.highlight({
+const driverObj = driver();
+driverObj.highlight({
   element: "#some-element",
   popover: {
     title: "Title",
@@ -48,9 +48,9 @@ driver.highlight({
 If you are using the CDN, you will have to use the package from the `window` object:
 
 ```js
-const Driver = window.driver.js.driver;
+const driver = window.driver.js.driver;
 
-const driver = new Driver();
+const driverObj = driver();
 driver.highlight({
   element: "#some-element",
   popover: {

src/config.ts

@@ -2,7 +2,7 @@ import { DriveStep } from "./driver";
 import { AllowedButtons, PopoverDOM } from "./popover";
 import { State } from "./state";
 
-type DriverHook = (element: Element | undefined, step: DriveStep, opts: { config: Config; state: State }) => void;
+export type DriverHook = (element: Element | undefined, step: DriveStep, opts: { config: Config; state: State }) => void;
 
 export type Config = {
   steps?: DriveStep[];

src/driver.ts

@@ -1,7 +1,7 @@
 import { AllowedButtons, destroyPopover, Popover } from "./popover";
 import { destroyStage } from "./stage";
 import { destroyEvents, initEvents, requireRefresh } from "./events";
-import { Config, configure, getConfig } from "./config";
+import { Config, configure, DriverHook, getConfig } from "./config";
 import { destroyHighlight, highlight } from "./highlight";
 import { destroyEmitter, listen } from "./emitter";
 import { getState, resetState, setState } from "./state";
@@ -9,7 +9,7 @@ import "./driver.css";
 
 export type DriveStep = {
   element?: string | Element;
-  onDeselected?: (element: Element | undefined, step: DriveStep) => void;
+  onDeselected?: DriverHook;
   popover?: Popover;
 };
 

src/popover.ts

@@ -1,5 +1,5 @@
 import { bringInView } from "./utils";
-import { getConfig } from "./config";
+import { DriverHook, getConfig } from "./config";
 import { getState, setState } from "./state";
 import { DriveStep } from "./driver";
 import { onDriverClick } from "./events";
@@ -31,9 +31,9 @@ export type Popover = {
   onPopoverRendered?: (popover: PopoverDOM) => void;
 
   // Button callbacks
-  onNextClick?: (element: Element | undefined, step: DriveStep) => void;
-  onPrevClick?: (element: Element | undefined, step: DriveStep) => void;
-  onCloseClick?: (element: Element | undefined, step: DriveStep) => void;
+  onNextClick?: DriverHook;
+  onPrevClick?: DriverHook;
+  onCloseClick?: DriverHook;
 };
 
 export type PopoverDOM = {