# 🧭 XD Tour – Usage Guide

---

## 🧩 Overview

**XD Tour** is a lightweight, professional **in-page tour system** for your HTML pages.
It highlights elements, displays tooltips with arrows, and allows **Next / Back / Skip** navigation.

The tour supports **two versions** within a single JS/CSS setup:

* **v1** – Define content directly in your HTML using `data-intro-title` and `data-intro-txt`.
* **v2** – Use only `data-intro-id` in HTML, and define the title/text in your JS configuration.

Additionally, the tour now supports **automatic next step progression** and **auto-scrolling**.

---

## 📦 Required Files

Include these in your HTML:

```html
<link rel="stylesheet" href="xd-tour.css">
<script src="xd-tour.js"></script>
```

*(If using jsDelivr CDN, you can replace these paths with your CDN URLs.)*

---

## 🧱 HTML Structure

### 🔹 v1 Example (HTML-defined)

Use `data-intro-id`, `data-intro-title`, and `data-intro-txt` directly on elements.

```html
<button data-intro-id="1" data-intro-title="Click me" data-intro-txt="This button does XYZ">
  Button
</button>
```

### 🔹 v2 Example (JS-defined)

Only use `data-intro-id` in HTML, and define the title/text later in JS.

```html
<button data-intro-id="1">Button</button>
```

---

## ⚙️ JavaScript Configuration

Initialize the tour using `XDTour.config()`
Start it with `XDTour.start()`.

### 🧭 v1 Configuration

```javascript
XDTour.config({
  version: "v1",
  isSkippable: true,
  isPreviousable: true,
  showOnce: true,
  autoNext: true,
  autoNextDelay: 3000,
  autoScroll: true
});
XDTour.start();
```

### 🧭 v2 Configuration

```javascript
XDTour.config({
  version: "v2",
  isSkippable: true,
  isPreviousable: true,
  showOnce: true,
  autoNext: true,
  autoNextDelay: 3000,
  autoScroll: true,
  v2Steps: {
    "1": { title: "Click me", text: "This button does XYZ" },
    "2": { title: "Settings", text: "Change app settings here" }
  }
});
XDTour.start();
```

#### 🧾 Configuration Options

| Option           | Type             | Description                                            |
| ---------------- | ---------------- | ------------------------------------------------------ |
| `version`        | `"v1"` or `"v2"` | Selects HTML-defined or JS-defined mode                |
| `isSkippable`    | `boolean`        | Enables Skip button                                    |
| `isPreviousable` | `boolean`        | Enables Back button                                    |
| `showOnce`       | `boolean`        | Shows tour only once per browser (uses `localStorage`) |
| `v2Steps`        | `object`         | Defines step content for v2 version                    |
| `autoNext`       | `boolean`        | Automatically moves to the next step                   |
| `autoNextDelay`  | `number`         | Delay in milliseconds before moving to next step       |
| `autoScroll`     | `boolean`        | Scrolls page to make highlighted element visible       |

---

## 🎨 Notes

* Tooltip arrows automatically position above or below depending on available space.
* Highlighted elements remain visible above the overlay.
* Buttons include click animations (no hover).
* Works seamlessly with responsive layouts.
* Auto-next steps and auto-scroll improve user flow on long pages.
* You can mix v1 and v2 elements, but version is globally set in `XDTour.config()`.

---

## 🚀 Example Flow (v2)

1. Add `data-intro-id` to all elements in your tour.
2. Define `v2Steps` in JS with `title` and `text` for each step.
3. Configure tour: `XDTour.config({ version: 'v2', ... })`.
4. Start the tour: `XDTour.start()`.
5. Users navigate via **Next**, **Back**, **Skip**, and **Finish** buttons.
6. Auto-next and auto-scroll work if enabled.

---

## 🎨 Recommended CSS Customization

| Class                        | Purpose                                      |
| ---------------------------- | -------------------------------------------- |
| `.xd-tour-tooltip`           | Tooltip styles (background, shadow, padding) |
| `.xd-tour-buttons button`    | Button colors and click effects              |
| `.xd-tour-overlay`           | Background dim overlay                       |
| `.arrow-top / .arrow-bottom` | Tooltip arrow positioning                    |

---

With **XD Tour**, you can create professional in-page guided tours — fully customizable, lightweight, with zero dependencies, and now with auto-next and auto-scroll functionality.