npm package: @ghg/tourish
Description: Guide users through your app with a clean, modular tour experience.
Latest version: 0.1.1

# Tour Component Library

Guide users through your app with a clean, modular tour experience.

## Core Features

- Simple, step-based guidance
- Custom styling and theming
- Highlighting and drawing attention to specific UI elements

## Component Architecture

### Tour (Root)

**Purpose:** Controls overall visibility and step logic.
**Role:** Hosts the full tour lifecycle and connects to context.

- Show/hide state management
- Step tracking and transitions
- Global backdrop control

### TourContainer

**Purpose:** Wraps each step's visual content.
**Role:** Ensures consistent positioning and layout.

- Overlay backdrop styling
- Responsive positioning logic
- Custom layout options

### TourControls

**Purpose:** Lets users move forward, backward, or exit.
**Role:** Separates navigation from content.

- Previous and Next navigation
- Skip to any step
- End tour early
- Customizable labels and buttons

### TourStepContent

**Purpose:** Provides the specific text and visuals per step.
**Role:** Keeps presentation separate from navigation.

- Smooth animated step content
- Flexible title/body formatting
- Multiple paragraph support
- Scoped styling

## Navigation Methods

- **Sequential:** Move step-by-step using Next/Previous
- **Direct Skip:** Jump directly to a specific step
- **Early Exit:** Allow users to exit the tour at any time
- **Keyboard Navigation:** Use arrow keys or Escape to navigate

## Theming Options

- **Tailwind Classes:** Apply custom styles via `xClassName` props
- **Custom Rendering:** Replace or extend internal components

## Documentation

For detailed usage examples and API documentation, please refer to our [Storybook documentation](./src/stories/index.mdx).

## Getting Started

### Install dependencies

```sh
yarn
```

### Run Storybook

```sh
yarn storybook
```

## Multiple Tours Support

The library supports defining and running multiple tours within a single application:

- Define different tours for different features or user journeys
- Start specific tours by ID
- Maintain separate completion state for each tour

### Example:

```tsx
// Define multiple tours
const appTours = {
  onboarding: {
    steps: [
      { title: "Welcome", content: ["First-time user introduction"] },
      // more steps...
    ],
  },
  "new-feature": {
    steps: [
      { title: "New Feature", content: ["Introducing our latest feature"] },
      // more steps...
    ],
  },
};

// Set up the provider with multiple tours
<TourProvider
  tours={appTours}
  defaultTourId="onboarding"
  pathname={pathname}
  navigate={navigate}
>
  <AppContent />
  <TourManager />
</TourProvider>;

// Start a specific tour
const { startTour } = useTour();
startTour("new-feature");
```

## Tour Manager

The `TourManager` component connects to the tour context automatically, simplifying the implementation:

```tsx
// Instead of manually passing all tour state:
<Tour
  steps={tourContext.steps}
  currentStepIndex={tourContext.currentStepIndex}
  isOpen={tourContext.isOpen}
  // ...other props
/>

// Simply use the TourManager within a TourProvider:
<TourManager
  // Only styling props should be passed if needed
  backdropClassName="custom-backdrop"
  containerClassName="custom-container"
/>
```