react-spotlight-tour-cct/README.md

A lightweight and customizable React component for creating guided tours in your web applications. Highlight elements and display step-by-step instructions to guide users through your app's features.

# React Tour Guide

A lightweight and customizable React component for creating guided tours in your web applications. Highlight elements and display step-by-step instructions to guide users through your app's features.

---

## Features

- Highlight elements on the page.
- Step-by-step instructions with navigation.
- Keyboard navigation support.
- Customizable styles and positions.
- Progress bar and restart functionality.

---
## Requirements

- Node.js: `v16.0.0` or higher
- npm: `v7.0.0` or higher

## Installation

Install the package using npm:

```bash
npm install react-spotlight-tour-cct
# or
yarn add react-spotlight-tour-cct
```

## Usage

This package provides a `REACT-TOUR-GUIDE` component that you can use to guide the novice user with unique features of our website.

### Example

```tsx
import React from "react";
import { TourGuidePopup } from "react-spotlight-tour-cct";
//import "react-spotlight-tour-cct/dist/react-spotlight-tour-cct.css"; // (Optional)

const App = () => {
  const steps = [
    { id: "step1", content: "This is the first step of the tour." },
    { id: "step2", content: "Highlight another feature in this step." },
    { id: "step3", content: "Final step of the tour!" },
  ];

  return (
    <div>
      <h1 id="step1">Welcome to the App</h1>
      <p id="step2">This paragraph is part of the tour.</p>
      <button id="step3">Click me to finish the tour!</button>

      <TourGuidePopup steps={steps} />
    </div>
  );
};

export default App;
```

Keyboard Shortcuts
 -- Right Arrow: Navigate to the next step.
 -- Left Arrow: Navigate to the previous step.
 -- Escape: Close the tour.

 ## Props

### `TourGuidePopup` Component

| Prop      | Type        | Description                                                    | Required |
|-----------|-------------|----------------------------------------------------------------|----------|
| `steps`   | `TourStep[]`| An array of tour steps with `id` and `content`.                | Yes      |

### `TourStep` Interface

```tsx
interface TourStep {
  id: string;      // The ID of the element to highlight.
  content: string; // The content to display in the popup for this step.
}

```

 ### CSS Classes

Below are the CSS classes used in the component and their descriptions:

| Class                | Description                                 |
|----------------------|---------------------------------------------|
| `button-restart`     | Styles the "Restart Tour" button.           |
| `tour-guide-popup`   | Styles the main popup container.            |
| `popup-arrow`        | Styles the arrow pointing to the target.    |
| `progress-container` | Styles the progress bar container.          |
| `progress-bar`       | Styles the progress bar itself.             |
| `button-close`       | Styles the close button inside the popup.   |

### Minimul style of Restart Button
```.button-restart {
  position: fixed;
  top: 10px;
  right: 10px;
  background-color: #007bff;
  color: #fff;
  border: none;
  border-radius: 5px;
  padding: 5px 10px;
  font-size: 12px;
  cursor: pointer;
  z-index: 1002;
}
```
### Highlight Component
This component highlights a specific element during the tour by adding a highlighted class to the element identified by its targetId prop.
```
import React, { useEffect } from "react";
import "./Highlight.css";

interface HighlightProps {
  targetId: string;
}

export const Highlight: React.FC<HighlightProps> = ({ targetId }) => {
  useEffect(() => {
    const targetElement = document.getElementById(targetId);
    if (targetElement) {
      targetElement.classList.add("highlighted");
    }

    return () => {
      const targetElement = document.getElementById(targetId);
      if (targetElement) {
        targetElement.classList.remove("highlighted");
      }
    };
  }, [targetId]);

  return null;
};
```
Example of highlight element :
![Screenshot 2025-01-13 173047](https://github.com/user-attachments/assets/72e32e9a-6ed0-4a0e-b8df-49ed6f0a1567)

### `Highlight` Component

| Prop      | Type     | Description                                 | Required |
|-----------|----------|---------------------------------------------|----------|
| `targetId`| `string` | The `id` of the element to highlight.       | Yes      |

### `TourGuideButtons` Component

This component renders the navigation buttons for the tour, allowing users to move between steps, skip the tour, or finish it. It provides "Previous", "Skip", "Next", and "Finish" buttons based on the current step.

#### Props

| Prop         | Type     | Description                                     | Required |
|--------------|----------|-------------------------------------------------|----------|
| `currentStep`| `number` | The current step index in the tour.             | Yes      |
| `totalSteps` | `number` | The total number of steps in the tour.          | Yes      |
| `onPrevious` | `function`| Function to handle moving to the previous step. | Yes      |
| `onNext`     | `function`| Function to handle moving to the next step.     | Yes      |
| `onClose`    | `function`| Function to handle closing the tour.            | Yes      |

#### Example Usage

```tsx
import React, { useState } from "react";
import { TourGuideButtons } from "react-spotlight-tour-cct";

const TourComponent = () => {
  const [currentStep, setCurrentStep] = useState(0);
  const totalSteps = 3;

  const handlePrevious = () => setCurrentStep((prev) => Math.max(prev - 1, 0));
  const handleNext = () => setCurrentStep((prev) => Math.min(prev + 1, totalSteps - 1));
  const handleClose = () => setCurrentStep(0); // or perform other closing actions

  return (
    <div>
      <h1>Tour Step {currentStep + 1}</h1>
      <TourGuideButtons
        currentStep={currentStep}
        totalSteps={totalSteps}
        onPrevious={handlePrevious}
        onNext={handleNext}
        onClose={handleClose}
      />
    </div>
  );
};

export default TourComponent;
```

### Contributing
Feel free to submit issues or pull requests to improve the package. Contributions are always welcome!