npm package: @ruc-lib/tour-guide
Description: A component for creating a tour guide that provides information and guidance about a specific feature or functionality to the user.
Latest version: 4.0.0

# ruclib-tour-guide

A component for creating a tour guide that provides information and guidance about a specific feature or functionality to the user.

# Installation guide

To use the Tour Guide component, you can install the entire RUC library or just this specific component.

### Install the Entire Library
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

If you only need the TourGuide component:

**For Angular 15:**
```bash
npm install @ruc-lib/tour-guide@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/tour-guide@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/tour-guide@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/tour-guide@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/tour-guide@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/tour-guide@4.0.0
```

> **Note:** When installing in Angular 15-19 apps, you must specify the matching `@angular/material` and `@angular/cdk` versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

### 📦 Version Compatibility
 
Please ensure you install the correct version of `@ruc-lib/tour-guide` based on your Angular version.
 
| Angular Version    | Compatible `@ruc-lib/tour-guide` Version     |
|--------------------|----------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/tour-guide@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/tour-guide@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/tour-guide@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/tour-guide@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/tour-guide@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/tour-guide@^4.0.0`     |


## Usage
### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibTourGuideComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibTourGuideComponent } from '@uxpractice/ruc-lib/tour-guide';

// For Individual Package
import { RuclibTourGuideComponent } from '@ruc-lib/tour-guide';

@Component({
  selector: 'app-root',
  imports: [RuclibTourGuideComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-tour-guide>` selector and pass the configuration object to the `rucInputData` input and the data array to the `dataSource` input.

```html
<uxp-ruclib-tour-guide 
    [rucInputData]="tourGuideConfig"
    [customTheme]="customTheme" 
    (rucEvent)="passEvent($event)" 
    [dataSource]="tourGuideData">
</uxp-ruclib-tour-guide>
```

## API Reference

### Component Inputs

| Input          | Type               | Description                                       |
|----------------|--------------------|---------------------------------------------------|
| `rucInputData` | `TourGuideConfig`  | The main configuration object for the tour guide. |
| `customTheme`  | `string`           | An optional CSS class for custom theming.         |
| `dataSource`   | `TourGuideData`    | Data for the tour guide.                          |

### Component Outputs

| Output    | Type      | Description                                       |
|-----------|-----------|---------------------------------------------------|
| `rucEvent`| `any`     | Emits events related to tour guide actions (e.g., 'skip', 'next', 'finish'). |

### `TourGuideConfig`
This is the main configuration object for the Tour Guide component.

| Property                 | Type                                                                | Description                                                           |
|--------------------------|---------------------------------------------------------------------|-----------------------------------------------------------------------|
| `type`                   | `'simple' \| 'advance'`                                             | Type of tour guide (e.g., 'simple', 'advance').                       |
| `showSkipButton`         | `boolean`                                                           | To toggle the visibility of the skip button.                          |
| `buttonsFontSize`        | `string`                                                            | Configure the font size of buttons.                                   |
| `titleFontSize`          | `string`                                                            | Configure the font size of the title.                                 |
| `contentFontSize`        | `string`                                                            | Configure the font size of the main content.                          |
| `buttonsAlignment`       | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around'` | Change the alignment of buttons.                                      |
| `stepCountAlignment`     | `'start' | 'center' | 'end'`                                        | Change the alignment of step count.                                   |
| `stepCountStartText`     | `string`                                                            | Text to display at the start of the step count (e.g., 'Step').        |
| `stepCountMiddleText`    | `string`                                                            | Text to display in the middle of the step count (e.g., 'of').         |
| `skipButtonText`         | `string`                                                            | Text for the skip button.                                             |
| `prevButtonText`         | `string`                                                            | Text for the previous button.                                         |
| `nextButtonText`         | `string`                                                            | Text for the next button.                                             |
| `finishButtonText`       | `string`                                                            | Text for the finish button.                                           |
| `highlightBorderColor`   | `string`                                                            | Color of the highlight border around the guided element.              |
| `highlightBorderWidth`   | `string`                                                            | Width of the highlight border around the guided element.              |
| `defaultPopupWidth`      | `string`                                                            | Default width of the tour guide popup.                                |

### `TourGuideData`
This array of objects defines the content for each step of the tour guide.

| Property   | Type                                                        | Description                                                           |
|------------|-------------------------------------------------------------|-----------------------------------------------------------------------|
| `title`    | `string`                                                    | Title of the tour guide step.                                         |
| `content`  | `string`                                                    | Main content/description for the tour guide step.                     |
| `selector` | `string` (Only for `'advance'` type)                        | CSS selector for the element to highlight in 'advance' mode.          |
| `position` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'auto'`          | Position of the popup relative to the highlighted element.            |
| `shape`    | `'' \| 'rounded' \| 'rectangle' \| 'circle'`                | Shape of the description popup.                                       |
| `width`    | `string`                                                    | Custom width for the popup of the current step.                       |

## Example Configuration

Here's an example of how to configure the Tour Guide component in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { TourGuideConfig, TourGuideData } from '@uxpractice/ruc-lib/tour-guide';

// For Individual package
import { TourGuideConfig, TourGuideData } from '@ruc-lib/tour-guide';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
    tourGuideConfig: TourGuideConfig = {
    type: 'advance',
    showSkipButton: true,
    buttonsFontSize: '14px',
    titleFontSize: '18px',
    contentFontSize: '14px',
    buttonsAlignment: 'end',
    stepCountAlignment: 'center',
    stepCountStartText: 'Step',
    stepCountMiddleText: 'of',
    skipButtonText: 'Skip Tour',
    prevButtonText: 'Previous',
    nextButtonText: 'Next',
    finishButtonText: 'Finish',
    highlightBorderColor: '#007bff',
    highlightBorderWidth: '3px',
    defaultPopupWidth: '300px'
  };

  tourGuideData: TourGuideData[] = [
    {
      title: 'Welcome to Our App!',
      content: 'This tour will guide you through the main features.',
      selector: '', // No specific selector for the first step
      position: 'auto',
      shape: 'rounded',
      width: '350px'
    },
    {
      title: 'Navigation Bar',
      content: 'This is where you can navigate to different sections of the application.',
      selector: '#navbar', // Replace with your actual selector
      position: 'bottom',
      shape: 'rectangle',
      width: '300px'
    },
    {
      title: 'User Profile',
      content: 'Click here to view and manage your profile settings.',
      selector: '#user-profile-icon', // Replace with your actual selector
      position: 'left',
      shape: 'circle',
      width: '280px'
    },
    {
      title: 'Main Content Area',
      content: 'All your important data and features are displayed here.',
      selector: '#main-content', // Replace with your actual selector
      position: 'top',
      shape: 'rounded',
      width: '400px'
    },
    {
      title: 'Notifications',
      content: 'Stay updated with the latest notifications.',
      selector: '#notifications-bell', // Replace with your actual selector
      position: 'right',
      shape: 'rectangle',
      width: '250px'
    }
  ];

  passEvent(event: any) {
    console.log('Tour Guide Event:', event);
  }
}
```

> ⚠️ **IMPORTANT: Custom Theme Usage in Angular Material**

When implementing **custom themes**, such as:

```scss
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}
```

## Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

## Acknowledgements

Thank you for choosing the Tour Guide component. If you have any feedback or suggestions, please let us know!