### Basic Next.js Setup with NextStepProvider

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/README.md

Set up NextStep.js in a Next.js application using the NextStepProvider and NextStep components. This example defines a simple onboarding tour.

```typescript
'use client';
import { NextStep, NextStepProvider } from 'nextstepjs';
import type { Tour } from 'nextstepjs';

const steps: Tour[] = [
  {
    tour: 'onboarding',
    steps: [
      {
        title: 'Welcome',
        content: 'This is the first step.',
        selector: '#step1',
        side: 'right',
        showControls: true,
      },
    ],
  },
];

export default function App() {
  return (
    <NextStepProvider>
      <NextStep steps={steps}>
        <YourApp />
      </NextStep>
    </NextStepProvider>
  );
}
```

--------------------------------

### Install NextStep.js and Motion

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/README.md

Install the necessary packages using npm.

```bash
npm install nextstepjs motion
```

--------------------------------

### Example Tour Configuration

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

An example of how to configure tours with multiple steps. Each step includes a title, content, and a selector for the element to highlight.

```typescript
const tours: Tour[] = [
  {
    tour: 'onboarding',
    steps: [
      { title: 'Welcome', content: 'Step 1', selector: '#step1' },
      { title: 'Features', content: 'Step 2', selector: '#step2' },
    ],
  },
];
```

--------------------------------

### Use NextStep Context Example

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Demonstrates how to access and use the NextStep context to get tour information and control tour progression.

```typescript
const context = useNextStep();
console.log(context.currentStep);  // 0
console.log(context.currentTour);  // 'onboarding'
context.setCurrentStep(2);
context.closeNextStep();
```

--------------------------------

### Install NextStep with bun

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Install the NextStep library and motion using bun. This command is for projects using the bun runtime and package manager.

```bash
bun add nextstepjs motion
```

--------------------------------

### Basic Setup with NextStepProvider

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStep.md

Demonstrates the essential setup for using NextStep, including importing necessary components and defining tour steps. Ensure NextStepProvider wraps your application to provide the necessary context.

```typescript
'use client';
import { NextStep, NextStepProvider } from 'nextstepjs';
import type { Tour } from 'nextstepjs';

const steps: Tour[] = [
  {
    tour: 'firstTour',
    steps: [
      {
        title: 'Welcome',
        content: 'This is the first step of your tour.',
        selector: '#step-1',
        side: 'right',
        showControls: true,
        showSkip: true,
      },
      {
        title: 'Next Feature',
        content: 'Learn about this feature.',
        selector: '#step-2',
        side: 'top',
        showControls: true,
      },
    ],
  },
];

export default function App() {
  return (
    <NextStepProvider>
      <NextStep steps={steps}>
        <YourApplicationContent />
      </NextStep>
    </NextStepProvider>
  );
}

```

--------------------------------

### Install NextStep with npm

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Install the NextStep library and motion using npm. This is the primary method for adding NextStep to your project.

```bash
npm i nextstepjs motion
```

--------------------------------

### Install NextStep with pnpm

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Install the NextStep library and motion using pnpm. This command is suitable for projects managed with pnpm.

```bash
pnpm add nextstepjs motion
```

--------------------------------

### Install NextStep with yarn

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Install the NextStep library and motion using yarn. Use this command if your project utilizes yarn for package management.

```bash
yarn add nextstepjs motion
```

--------------------------------

### Example Step Configuration

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Illustrates how to create a Step object with various configuration properties for an onboarding tour.

```typescript
const step: Step = {
  icon: '📍',
  title: 'Highlight Element',
  content: 'This is the element you need to focus on.',
  selector: '#my-element',
  side: 'top-right',
  showControls: true,
  showSkip: true,
  pointerPadding: 15,
  pointerRadius: 8,
  cardOffset: 30,
  scrollOffset: 20,
  selectorRetryAttempts: 3,
  selectorRetryDelay: 100,
  nextRoute: '/page2',
  viewportID: 'my-viewport',
};
```

--------------------------------

### Comprehensive Step Configuration Example

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/configuration.md

This example demonstrates how to configure a single step with a wide range of options, including highlighting a specific element, controlling card placement and visibility, and managing navigation.

```typescript
const step: Step = {
  icon: '🎯',
  title: 'Element Highlighting',
  content: 'This element is highlighted and explained.',
  selector: '#important-element',
  side: 'top-right',
  showControls: true,
  showSkip: true,
  blockKeyboardControl: false,
  disableInteraction: false,
  pointerPadding: 15,
  pointerRadius: 10,
  cardOffset: 30,
  scrollOffset: 20,
  selectorRetryAttempts: 5,
  selectorRetryDelay: 100,
  nextRoute: '/next-page',
  prevRoute: '/previous-page',
  viewportID: 'scrollable-container',
};
```

--------------------------------

### Auto-Start Tour on Mount Based on State

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStepProvider.md

Conditionally start a tour using `startNextStep` within a `useEffect` hook. This example checks local storage to ensure the tour only runs once per user and avoids starting if the tour is already visible.

```typescript
import { useEffect } from 'react';
import { useNextStep } from 'nextstepjs';

export function AutoTourOnMount() {
  const { startNextStep, isNextStepVisible } = useNextStep();

  useEffect(() => {
    // Automatically start the onboarding tour on first mount
    const hasSeenTour = localStorage.getItem('tour-seen');
    if (!hasSeenTour && !isNextStepVisible) {
      startNextStep('firstTour');
      localStorage.setItem('tour-seen', 'true');
    }
  }, [startNextStep, isNextStepVisible]);

  return null;
}
```

--------------------------------

### Start a Tour Programmatically in a React Component

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/00-START-HERE.md

Use the useNextStep hook to get the startNextStep function, allowing you to trigger a tour from any component, typically in response to a user action like a button click. The tour must be defined elsewhere and accessible.

```typescript
import { useNextStep } from 'nextstepjs';

function MyComponent() {
  const { startNextStep } = useNextStep();
  
  return (
    <button onClick={() => startNextStep('onboarding')}> 
      Start Tour
    </button>
  );
}
```

--------------------------------

### NextStep Example with and without Custom Card

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Illustrates how to use the NextStep component. The first example shows usage without a custom card, allowing 'showControls'. The second example uses a custom card, where 'showControls' is disallowed by TypeScript.

```typescript
// Without cardComponent: showControls and showSkip are allowed
<NextStep steps={[{ tour: 'a', steps: [{ title: '...', showControls: true }] }]} />

// With cardComponent: showControls and showSkip are forbidden by TypeScript
<NextStep
  steps={[{ tour: 'a', steps: [{ title: '...' }] }]} 
  cardComponent={MyCard}
/>
// This would cause a TypeScript error:
// <NextStep steps={[{ tour: 'a', steps: [{ title: '...', showControls: true }] }]} cardComponent={MyCard} />
```

--------------------------------

### Install NextStep and Core Dependencies

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/configuration.md

Install the NextStep package along with its core peer dependencies using npm. This command includes `motion`, `react`, and `react-dom`.

```bash
npm install nextstepjs motion react react-dom
```

--------------------------------

### Custom Navigation Adapter Example

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Example of a custom navigation adapter implementation. Use this to define how NextStep interacts with your application's router.

```typescript
const useMyAdapter = (): NavigationAdapter => ({
  push: (path) => myRouter.navigate(path),
  getCurrentPath: () => myRouter.location.pathname,
});
```

--------------------------------

### Conditionally Triggering a Tour on First Visit

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/README.md

This example uses a useEffect hook to check local storage and start the 'onboarding' tour only if it hasn't been seen before, then marks it as seen.

```typescript
useEffect(() => {
  const hasSeenTour = localStorage.getItem('tour-seen');
  if (!hasSeenTour) {
    startNextStep('onboarding');
    localStorage.setItem('tour-seen', 'true');
  }
}, []);
```

--------------------------------

### Install React Router Optional Dependency

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/configuration.md

Install the optional peer dependency for React Router applications. This is required if you are using NextStep within a React Router setup.

```bash
# For React Router
npm install react-router
```

--------------------------------

### startNextStep

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

Start a tour by its name. This method initiates a specified tour, resetting it to the first step and making the tour overlay visible.

```APIDOC
## startNextStep

### Description
Start a tour by its name. Resets to step 0 and makes the overlay visible.

### Method
`startNextStep(tourName: string): void`

### Parameters
#### Path Parameters
- **tourName** (string) - Required - Unique name of the tour to start (must match the `tour` field in steps array). Case-sensitive.

### Request Example
```typescript
const { startNextStep } = useNextStep();

// Start the onboarding tour
startNextStep('onboarding');

// Start from a button
<button onClick={() => startNextStep('onboarding')}>Start Tour</button>
```

### Response
#### Success Response
- void

### Behavior
- Sets `currentTour` to the specified tour name
- Sets `currentStep` to 0 (starts at first step)
- Makes the overlay visible (`isNextStepVisible = true`)
- Triggers `onStart` callback
- Any previously active tour is closed
```

--------------------------------

### Full Component Configuration Example

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/configuration.md

Demonstrates how to configure the NextStep component with various props, including custom callbacks, styling, and components. This is useful for customizing the tour's appearance and behavior extensively.

```typescript
<NextStep
  steps={steps}
  showNextStep={true}
  shadowRgb="55, 48, 163"
  shadowOpacity="0.8"
  cardTransition={{ duration: 0.5, ease: 'easeInOut', type: 'spring' }}
  cardComponent={MyCustomCard}
  onStart={(tourName) => trackEvent('tour_start', { tour: tourName })}
  onStepChange={(step, tourName) => trackEvent('step_change', { step, tour: tourName })}
  onComplete={(tourName) => trackEvent('tour_complete', { tour: tourName })}
  onSkip={(step, tourName) => trackEvent('tour_skip', { step, tour: tourName })}
  displayArrow={true}
  clickThroughOverlay={false}
  navigationAdapter={useReactRouterAdapter}
  disableConsoleLogs={false}
  scrollToTop={true}
  noInViewScroll={false}
  overlayZIndex={1400}
  arrowComponent={MyCustomArrow}
  arrowStyle={{ color: '#ff0000', width: '20px' }}
>
  <YourAppContent />
</NextStep>
```

--------------------------------

### Start a Tour by Name

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

Initiate a tour using startNextStep, providing the tour's unique name. This resets the tour to the first step and makes the overlay visible.

```typescript
const { startNextStep } = useNextStep();

// Start the onboarding tour
startNextStep('onboarding');

// Start advanced features tour
startNextStep('advanced-features');

// Start from a button
<button onClick={() => startNextStep('onboarding')}>Start Tour</button>
```

--------------------------------

### Transition Example Usage

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Demonstrates how to create and use a Transition object with the NextStep component to configure card animations. This example sets a specific duration, easing function, and animation type.

```typescript
const transition: Transition = {
  duration: 0.5,
  ease: 'anticipate',
  type: 'spring',
};

<NextStep steps={steps} cardTransition={transition} />
```

--------------------------------

### Start Multiple Tours

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/00-START-HERE.md

Demonstrates how to initiate different tours by calling startNextStep with their respective tour names. Ensure each tour name corresponds to a defined tour.

```typescript
startNextStep('onboarding');     // Start one tour
startNextStep('advanced');        // Start a different tour
```

--------------------------------

### Install Remix Optional Dependency

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/configuration.md

Install the optional peer dependency for Remix applications. This is required if you are using NextStep within a Remix project.

```bash
# For Remix
npm install @remix-run/react
```

--------------------------------

### Using the useNextStep Hook

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/README.md

Demonstrates how to use the `useNextStep` hook to programmatically start a tour from a component. This is useful for triggering tours via user interactions.

```typescript
import { useNextStep } from 'nextstepjs';

function MyComponent() {
  const { startNextStep } = useNextStep();

  return (
    <button onClick={() => startNextStep('onboarding')}>
      Start Tour
    </button>
  );
}
```

--------------------------------

### NextStep Component Setup (Remix Adapter)

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/GENERATION_SUMMARY.txt

Configure NextStepReact to use the Remix adapter for navigation within a Remix application.

```javascript
import { useRemixAdapter } from 'nextstepjs/adapters/remix'
<NextStepReact navigationAdapter={useRemixAdapter} steps={steps}>{children}</NextStepReact>
```

--------------------------------

### Install Next.js Optional Dependency

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/configuration.md

Install the optional peer dependency for Next.js applications. This is required if you are using NextStep within a Next.js project.

```bash
# For Next.js
npm install next
```

--------------------------------

### NextStep Component Setup (Next.js)

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/GENERATION_SUMMARY.txt

Integrate the NextStep component within a Next.js application by wrapping it with NextStepProvider and passing the steps configuration.

```javascript
import { NextStep, NextStepProvider, useNextStep } from 'nextstepjs'
<NextStepProvider>
  <NextStep steps={steps}>{children}</NextStep>
</NextStepProvider>
```

--------------------------------

### Start a Tour from a Button

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStepProvider.md

Use the `startNextStep` function from `useNextStep` to initiate a tour when a button is clicked. Ensure `useNextStep` is called within a component wrapped by `NextStepProvider`.

```typescript
import { useNextStep } from 'nextstepjs';

export function TourButton() {
  const { startNextStep } = useNextStep();

  return (
    <button onClick={() => startNextStep('firstTour')}>
      Start Tour
    </button>
  );
}
```

--------------------------------

### NextStep Component Setup (Custom Adapter)

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/GENERATION_SUMMARY.txt

Configure NextStepReact to use a custom navigation adapter for flexible routing solutions.

```javascript
<NextStepReact navigationAdapter={useMyCustomAdapter} steps={steps}>{children}</NextStepReact>
```

--------------------------------

### Conditionally Start Tour on Mount

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

Use this snippet to automatically start a tour for first-time visitors when a component mounts. It checks local storage to prevent re-showing the tour.

```typescript
import { useEffect } from 'react';
import { useNextStep } from 'nextstepjs';

export function AutoTourOnMount() {
  const { startNextStep, isNextStepVisible } = useNextStep();

  useEffect(() => {
    // Check if user has seen the tour before
    const hasSeenTour = localStorage.getItem('tour-seen-onboarding');

    if (!hasSeenTour && !isNextStepVisible) {
      // Start tour for first-time visitors
      startNextStep('onboarding');
      localStorage.setItem('tour-seen-onboarding', 'true');
    }
  }, [startNextStep, isNextStepVisible]);

  return null;
}
```

--------------------------------

### Custom Tour Control Panel with useNextStep

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

Implement a custom UI to control tour progression, including starting, navigating steps, and closing the tour. Requires the `useNextStep` hook.

```typescript
import { useNextStep } from 'nextstepjs';

export function TourControlPanel() {
  const {
    currentStep,
    currentTour,
    isNextStepVisible,
    startNextStep,
    closeNextStep,
    setCurrentStep,
  } = useNextStep();

  if (!isNextStepVisible) {
    return (
      <div className="tour-panel">
        <h3>Start a Tour</h3>
        <button onClick={() => startNextStep('onboarding')}> 
          Onboarding
        </button>
        <button onClick={() => startNextStep('advanced-features')}> 
          Advanced Features
        </button>
      </div>
    );
  }

  return (
    <div className="tour-panel active">
      <h3>Tour: {currentTour}</h3>
      <p>Step {currentStep + 1}</p>

      <div className="controls">
        <button
          onClick={() => setCurrentStep(Math.max(0, currentStep - 1))}
          disabled={currentStep === 0}
        >
          Previous
        </button>

        <button onClick={() => setCurrentStep(currentStep + 1)}>
          Next
        </button>

        <button onClick={closeNextStep}>Close</button>
      </div>

      <div className="progress">
        <div className="bar" style={{ width: `${(currentStep + 1) * 20}%` }} />
      </div>
    </div>
  );
}
```

--------------------------------

### Defining a Multi-Page Tour

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/README.md

An example of a tour configuration object that includes `nextRoute` and `prevRoute` properties to enable navigation between pages during the tour.

```typescript
{
  tour: 'multiPage',
  steps: [
    { title: 'Step 1', content: '...', selector: '#elem1', nextRoute: '/page2' },
    { title: 'Step 2', content: '...', selector: '#elem2', prevRoute: '/page1' },
  ],
}
```

--------------------------------

### Example Tour Steps Configuration

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Defines an array of tour configurations, each containing an array of steps. Steps can include icons, titles, content, selectors, sides, controls, skip options, padding, radius, and routing information.

```tsx
[
  {
    tour: 'firsttour',
    steps: [
      {
        icon: <>👋</>,
        title: 'Tour 1, Step 1',
        content: <>First tour, first step</>,
        selector: '#tour1-step1',
        side: 'top',
        showControls: true,
        showSkip: true,
        pointerPadding: 10,
        pointerRadius: 10,
        nextRoute: '/foo',
        prevRoute: '/bar',
      },
      {
        icon: <>🎉</>,
        title: 'Tour 1, Step 2',
        content: <>First tour, second step</>,
        selector: '#tour1-step2',
        side: 'top',
        showControls: true,
        showSkip: true,
        pointerPadding: 10,
        pointerRadius: 10,
        viewportID: 'scrollable-viewport',
      },
    ],
  },
  {
    tour: 'secondtour',
    steps: [
      {
        icon: <>🚀</>,
        title: 'Second tour, Step 1',
        content: <>Second tour, first step!</>,
        selector: '#nextstep-step1',
        side: 'top',
        showControls: true,
        showSkip: true,
        pointerPadding: 10,
        pointerRadius: 10,
        nextRoute: '/foo',
        prevRoute: '/bar',
      },
    ],
  },
]
```

--------------------------------

### Implementing a Custom Card Component

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStep.md

Provides an example of creating a custom card component for tour steps by implementing the `CardComponentProps` interface. This allows for full control over the UI of the tour's step information.

```typescript
import type { CardComponentProps } from 'nextstepjs';

const CustomCard: React.FC<CardComponentProps> = ({
  step,
  currentStep,
  totalSteps,
  nextStep,
  prevStep,
  skipTour,
  arrow,
}) => (
  <div style={{ padding: '20px', background: '#fff' }}>
    <h2>{step.title}</h2>
    <p>{step.content}</p>
    <p>{currentStep + 1} of {totalSteps}</p>
    <button onClick={prevStep}>Back</button>
    <button onClick={nextStep}>Next</button>
    {arrow}
  </div>
);

<NextStep steps={steps} cardComponent={CustomCard}>
  <YourApplicationContent />
</NextStep>

```

--------------------------------

### NextStepReact with Custom Navigation Adapter

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStepReact.md

Implement a custom navigation logic for NextStepReact by providing your own NavigationAdapter. This example shows a basic custom adapter using window history.

```typescript
import type { NavigationAdapter } from 'nextstepjs';

const useCustomAdapter = (): NavigationAdapter => {
  return {
    push: (path: string) => {
      // Your custom navigation logic
      window.history.pushState({}, '', path);
    },
    getCurrentPath: () => window.location.pathname,
  };
};

<NextStepReact navigationAdapter={useCustomAdapter} steps={steps}>
  <YourContent />
</NextStepReact>
```

--------------------------------

### NextStep Component Setup (React Router Adapter)

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/GENERATION_SUMMARY.txt

Configure NextStepReact to use the React Router adapter for navigation within a React application.

```javascript
import { useReactRouterAdapter } from 'nextstepjs/adapters/react-router'
<NextStepReact navigationAdapter={useReactRouterAdapter} steps={steps}>{children}</NextStepReact>
```

--------------------------------

### Next.js Default Adapter Setup

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Integrate NextStep with your Next.js application using the default adapter. Ensure NextStepProvider and NextStep components are set up in your layout or app file.

```tsx
import { NextStep, NextStepProvider } from 'nextstepjs';

export default function Layout({ children }) {
  return (
    <NextStepProvider>
      <NextStep steps={steps}>{children}</NextStep>
    </NextStepProvider>
  );
}
```

--------------------------------

### Dynamically Advance Tour Step After Data Load

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

This example shows how to advance a tour step automatically once data has finished loading. It uses a delay to ensure the DOM is ready for the next step.

```typescript
import { useEffect } from 'react';
import { useNextStep } from 'nextstepjs';

export function DynamicTourProgression() {
  const { currentStep, setCurrentStep, currentTour } = useNextStep();
  const { data, isLoading } = useData(); // Your data hook

  useEffect(() => {
    // After data loads, advance to the next relevant step
    if (!isLoading && data && currentTour === 'dataTour') {
      // Delay to ensure new elements are rendered
      setCurrentStep(currentStep + 1, 500);
    }
  }, [isLoading, data, currentTour, currentStep, setCurrentStep]);

  return null;
}
```

--------------------------------

### Custom Arrow Component Example

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Example of a custom arrow component using ArrowComponentProps. Spread the computed styles into your element's style to position it correctly.

```typescript
const MyCustomArrow: React.FC<ArrowComponentProps> = ({ side, style }) => (
  <div
    style={{
      ...style,
      fontSize: '24px',
      color: 'blue',
    }}
    data-side={side}
  >
    ◆
  </div>
);
```

--------------------------------

### Custom Card Component Example

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

An example of a custom React card component implementing the CardComponentProps interface. This component displays step information and provides navigation buttons.

```typescript
const MyCustomCard: React.FC<CardComponentProps> = ({
  step,
  currentStep,
  totalSteps,
  nextStep,
  prevStep,
  skipTour,
  arrow,
}) => (
  <div style={{ padding: '20px', background: 'white' }}>
    <h2>{step.title}</h2>
    <p>{step.content}</p>
    <p>{currentStep + 1} / {totalSteps}</p>
    <button onClick={prevStep}>Back</button>
    <button onClick={nextStep}>Next</button>
    <button onClick={skipTour}>Skip</button>
    {arrow}
  </div>
);
```

--------------------------------

### Main Entry Point Exports

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/modules.md

Lists the components, context, hooks, and types exported from the main entry point of the NextStep library.

```APIDOC
## Module: `nextstepjs`

### Description
This module serves as the main entry point for the NextStep library, exporting core components, context, hooks, and types for building onboarding tours.

### Exports

#### Components
- `NextStep`: Next.js-specific onboarding component with a built-in adapter.
- `NextStepReact`: Framework-agnostic onboarding component.
- `NextStepViewport`: Wrapper component for scrollable content areas.

#### Context & Hooks
- `NextStepProvider`: Context provider for managing tour state.
- `useNextStep`: Hook to access tour state and control methods.

#### Types
- `NextStepProps`: Union of component prop types.
- `Tour`: Type representing a tour container with steps.
- `Step`: Type for individual step configuration.
- `NextStepContextType`: Interface for the context.
- `CardComponentProps`: Props for custom card components.
- `ArrowComponentProps`: Props for custom arrow components.
- `NavigationAdapter`: Interface for router adapters.
```

--------------------------------

### NextStep Callback Hooks

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/configuration.md

Integrate tours with analytics or custom logic using callbacks for start, step change, completion, and skipping events.

```typescript
<NextStep
  steps={steps}
  onStart={(tourName) => {
    // Fired when tour starts
    console.log(`Tour "${tourName}" started`);
    analytics.track('tour_started', { tour: tourName });
  }}
  onStepChange={(step, tourName) => {
    // Fired on every step change
    console.log(`Tour "${tourName}" step ${step}`);
    analytics.track('tour_step_changed', { tour: tourName, step });
  }}
  onComplete={(tourName) => {
    // Fired when last step is completed (or Next clicked on last step)
    console.log(`Tour "${tourName}" completed`);
    analytics.track('tour_completed', { tour: tourName });
  }}
  onSkip={(step, tourName) => {
    // Fired when user clicks Skip
    console.log(`Tour "${tourName}" skipped at step ${step}`);
    analytics.track('tour_skipped', { tour: tourName, step });
  }}
>
  {/* ... */}
</NextStep>
```

--------------------------------

### Using the useNextStep Hook

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Import and use the useNextStep hook to programmatically control tours from anywhere in your application. Use startNextStep to initiate a tour by its name.

```tsx
import { useNextStep } from 'nextstepjs';
....

const { startNextStep, closeNextStep } = useNextStep();

const onClickHandler = (tourName: string) => {
  startNextStep(tourName);
};
```

--------------------------------

### Modal Onboarding with NextStepViewport

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStepViewport.md

Integrate NextStepViewport within a modal dialog for onboarding. This allows tour steps to be confined to the modal's content area.

```typescript
import { NextStepViewport } from 'nextstepjs';
import { Dialog } from '@headlessui/react';

export function OnboardingModal({ isOpen, onClose }) {
  return (
    <Dialog open={isOpen} onClose={onClose}>
      <Dialog.Panel>
        <NextStepViewport id="modal-viewport">
          <h2 id="modal-title">Welcome</h2>
          <div id="modal-content">
            <p>Explore our features...</p>
          </div>
          <button id="modal-action">Get Started</button>
        </NextStepViewport>
      </Dialog.Panel>
    </Dialog>
  );
}

const steps: Tour[] = [
  {
    tour: 'modalOnboarding',
    steps: [
      {
        title: 'Welcome',
        content: 'Learn about our product.',
        selector: '#modal-title',
        viewportID: 'modal-viewport',
        side: 'bottom',
      },
      {
        title: 'Take Action',
        content: 'Click here to get started.',
        selector: '#modal-action',
        viewportID: 'modal-viewport',
        side: 'top',
      },
    ],
  },
];
```

--------------------------------

### Get Current Step Index

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

Retrieve the zero-based index of the current step in an active tour. Use this to display progress or conditionally render content.

```typescript
const { currentStep } = useNextStep();

console.log(currentStep); // 0, 1, 2, etc.

// Display step number (1-based for UI)
<span>Step {currentStep + 1}</span>
```

--------------------------------

### Step Interface Definition

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Defines the structure for an individual onboarding step, including content, positioning, visibility, and routing options.

```typescript
interface Step {
  // Content
  icon?: React.ReactNode | string | null;
  title: string;
  content: React.ReactNode;
  selector?: string;

  // Positioning
  side?: 'top' | 'bottom' | 'left' | 'right' |
         'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' |
         'left-top' | 'left-bottom' | 'right-top' | 'right-bottom';

  // Visibility & Interaction
  showControls?: boolean;
  showSkip?: boolean;
  blockKeyboardControl?: boolean;
  disableInteraction?: boolean;

  // Sizing & Spacing
  pointerPadding?: number;
  pointerRadius?: number;
  cardOffset?: number;
  scrollOffset?: number;

  // Async Elements
  selectorRetryAttempts?: number;
  selectorRetryDelay?: number;

  // Routing
  nextRoute?: string;
  prevRoute?: string;

  // Viewport
  viewportID?: string;
}
```

--------------------------------

### Close the Tour Overlay

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

Use closeNextStep to hide the tour overlay and reset the tour's state. This is useful for dismissing the tour or preparing to start a new one.

```typescript
const { closeNextStep } = useNextStep();

// Close the tour
closeNextStep();

// Close from a button
<button onClick={closeNextStep}>Close</button>
```

--------------------------------

### Remix Adapter Integration

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Set up NextStep with the Remix adapter by importing `useRemixAdapter` and providing it to the `NextStepReact` component.

```tsx
import { NextStepProvider, NextStepReact } from 'nextstepjs';
import { useRemixAdapter } from 'nextstepjs/adapters/remix';

export default function App() {
  return (
    <NextStepProvider>
      <NextStepReact navigationAdapter={useRemixAdapter} steps={steps}> 
        <Outlet />
      </NextStepReact>
    </NextStepProvider>
  );
}
```

--------------------------------

### Get Current Tour Name

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/ContextMethods.md

Retrieve the name of the currently active tour. Returns null if no tour is running. Useful for rendering tour-specific UI or tracking analytics.

```typescript
const { currentTour } = useNextStep();

console.log(currentTour); // 'onboarding', 'advanced', etc., or null

// Conditionally render tour-specific UI
{currentTour === 'onboarding' && <OnboardingHelp />}

// Display active tour name
{currentTour ? <span>Tour: {currentTour}</span> : <span>No tour active</span>}
```

--------------------------------

### Define and Render a Simple 3-Step Tour in Next.js

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/00-START-HERE.md

This snippet shows how to define a tour with multiple steps and integrate it into a Next.js application using NextStepProvider and NextStep components. Ensure you have elements with IDs 'step1' and 'step2' in your application for the selectors to work.

```typescript
'use client';
import { NextStep, NextStepProvider } from 'nextstepjs';
import type { Tour } from 'nextstepjs';

const steps: Tour[] = [
  {
    tour: 'onboarding',
    steps: [
      {
        title: 'Welcome',
        content: 'This is your first step.',
        selector: '#step1',
        side: 'right',
        showControls: true,
      },
      {
        title: 'Next Feature',
        content: 'Click next to continue.',
        selector: '#step2',
        side: 'top',
        showControls: true,
      },
    ],
  },
];

export default function App() {
  return (
    <NextStepProvider>
      <NextStep steps={steps}>
        <YourApp />
      </NextStep>
    </NextStepProvider>
  );
}
```

--------------------------------

### Define Tour Interface

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Represents a container for a set of onboarding steps, identified by a unique tour name. The 'tour' field is a case-sensitive identifier used with `startNextStep(tourName)`, and 'steps' is an array of individual step configurations.

```typescript
interface Tour {
  tour: string;
  steps: Step[];
}
```

--------------------------------

### Integrating Analytics with NextStep Events

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/README.md

Shows how to integrate analytics tracking by passing callback functions to NextStep props for tour start, step change, completion, and skipping events.

```typescript
<NextStep
  steps={steps}
  onStart={(tour) => analytics.track('tour_started', { tour })}
  onStepChange={(step, tour) => analytics.track('tour_step_changed', { step, tour })}
  onComplete={(tour) => analytics.track('tour_completed', { tour })}
  onSkip={(step, tour) => analytics.track('tour_skipped', { step, tour })} 
>
  {/* ... */}
</NextStep>
```

--------------------------------

### Tour

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/types.md

Container for a set of onboarding steps, identified by a unique tour name.

```APIDOC
## Tour

### Description
Container for a set of onboarding steps, identified by a unique tour name.

### Type Definition
```typescript
interface Tour {
  tour: string;
  steps: Step[];
}
```

### Fields
- **`tour`** (string) - Yes - Unique identifier for this tour. Must be case-sensitive and unique within the steps array. Used with `startNextStep(tourName)`.
- **`steps`** (Step[]) - Yes - Array of individual step configurations for this tour. Can contain 1 or more steps.

### Used By
- `NextStepProps.steps` (when using default card)
- `useNextStep().startNextStep(tourName)`

### Example
```typescript
const tours: Tour[] = [
  {
    tour: 'onboarding',
    steps: [
      { title: 'Welcome', content: 'Step 1', selector: '#step1' },
      { title: 'Features', content: 'Step 2', selector: '#step2' },
    ],
  },
];
```
```

--------------------------------

### useNextStep Hook

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStepProvider.md

The useNextStep hook provides access to the NextStep context, allowing child components to interact with and control the tour state, such as navigating steps, closing tours, or starting new ones.

```APIDOC
## useNextStep Hook

### Description
A React hook to access and control the NextStep tour state within components.

### Return Type
```typescript
interface NextStepContextType {
  currentStep: number;
  currentTour: string | null;
  setCurrentStep: (step: number, delay?: number) => void;
  closeNextStep: () => void;
  startNextStep: (tourName: string) => void;
  isNextStepVisible: boolean;
}
```

### Return Values
- **currentStep** (`number`) - Zero-based index of the current step in the active tour. Read-only.
- **currentTour** (`string | null`) - Name of the currently active tour, or `null` if no tour is running. Read-only.
- **setCurrentStep** (`(step: number, delay?: number) => void`) - Jump to a specific step index. Optional `delay` parameter (ms) defers the update.
- **closeNextStep** (`() => void`) - Close/hide the tour overlay and reset state.
- **startNextStep** (`(tourName: string) => void`) - Start a tour by name. Sets step to 0 and makes the overlay visible.
- **isNextStepVisible** (`boolean`) - Whether the tour overlay is currently visible. Read-only.

### Throws/Errors
- **Error:** `"useNextStep must be used within a NextStepProvider"` - Thrown if hook is called outside of a `NextStepProvider`.
```

--------------------------------

### Implementing a Custom Arrow Component

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStep.md

Demonstrates how to create a custom arrow component for navigating between tour steps by implementing the `ArrowComponentProps` interface. This allows for custom styling and behavior of the navigation arrows.

```typescript
import type { ArrowComponentProps } from 'nextstepjs';

const CustomArrow: React.FC<ArrowComponentProps> = ({ side, style }) => (
  <div
    style={{
      ...style,
      fontSize: '24px',
    }}
    data-side={side}
  >
    ◆
  </div>
);

<NextStep steps={steps} arrowComponent={CustomArrow}>
  <YourApplicationContent />
</NextStep>

```

--------------------------------

### NextStepReact with Custom Card and Events

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStepReact.md

Configure NextStepReact with a custom card component and event handlers for tour lifecycle events like start, step change, completion, and skip. Customizes shadow appearance.

```typescript
<NextStepReact
  steps={steps}
  cardComponent={CustomCard}
  navigationAdapter={useReactRouterAdapter}
  onStart={(tourName) => analytics.trackTourStart(tourName)}
  onStepChange={(step, tourName) => analytics.trackStepChange(step, tourName)}
  onComplete={(tourName) => analytics.trackTourComplete(tourName)}
  onSkip={(step, tourName) => analytics.trackTourSkip(step, tourName)}
  shadowRgb="55, 48, 163"
  shadowOpacity="0.8"
>
  <YourContent />
</NextStepReact>
```

--------------------------------

### Vite Configuration for React Router/Remix

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NavigationAdapters.md

Configure Vite to alias 'next/navigation' to a mock implementation when using React Router or Remix. This setup is necessary for non-Next.js applications to use NextStep's navigation features.

```typescript
import path from 'node:path';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  ssr: {
    noExternal: ['nextstepjs', 'motion'],
  },
  resolve: {
    alias: {
      // Mock Next.js navigation for non-Next.js apps
      'next/navigation': path.join(process.cwd(), 'src/mocks/next-navigation.ts'),
    },
  },
});
```

--------------------------------

### NextStep.js Main Entry Point Exports

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/modules.md

This snippet shows the main exports from the `nextstepjs` module, including components, context providers, hooks, and various types for configuring tours and steps.

```typescript
// Components
export { default as NextStep } from './NextStep';
export { default as NextStepReact } from './NextStepReact';
export { default as NextStepViewport } from './NextStepViewport';

// Context & Hooks
export { NextStepProvider, useNextStep } from './NextStepContext';

// Types
export type {
  NextStepProps,
  Tour,
  Step,
  NextStepContextType,
  CardComponentProps,
  ArrowComponentProps,
} from './types';
export type { NavigationAdapter } from './types/navigation';
```

--------------------------------

### Mocking Next.js Navigation for Vite

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Create mock implementations for Next.js navigation hooks (`useRouter`, `usePathname`, `useSearchParams`, `useParams`) to avoid build errors in Vite environments when using NextStep.

```typescript
// Mock for Next.js navigation to prevent build errors with nextstepjs
// This file is used to mock Next.js imports when using nextstepjs in a Vite app

export const useRouter = () => {
  return {
    push: () => {},
    replace: () => {},
    prefetch: () => {},
    back: () => {},
    forward: () => {},
    refresh: () => {},
  };
};

export const usePathname = () => {
  return '';
};

export const useSearchParams = () => {
  return new URLSearchParams();
};

export const useParams = () => {
  return {};
};
```

--------------------------------

### NextStep Component Tree

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/README.md

Illustrates the basic component hierarchy for NextStep, showing the provider, main component, and optional viewport.

```plaintext
NextStepProvider (establishes context)
└── NextStep or NextStepReact (renders overlay and tour logic)
    └── Your App Content
        └── NextStepViewport (optional, for scrollable areas)
            └── Elements with id selectors
```

--------------------------------

### Complex Tour Control Component

Source: https://github.com/enszrlu/nextstep/blob/main/_autodocs/api-reference/NextStepProvider.md

A comprehensive component that manages tour visibility, allows starting different tours, displays current tour status, and provides navigation controls (previous, next, close). It conditionally renders UI based on whether a tour is active.

```typescript
import { useNextStep } from 'nextstepjs';

export function TourControl() {
  const {
    currentStep,
    currentTour,
    isNextStepVisible,
    startNextStep,
    closeNextStep,
    setCurrentStep,
  } = useNextStep();

  return (
    <div>
      {!isNextStepVisible ? (
        <div>
          <button onClick={() => startNextStep('introduction')}>
            Start Introduction
          </button>
          <button onClick={() => startNextStep('advanced')}>
            Start Advanced Tour
          </button>
        </div>
      ) : (
        <div>
          <p>
            {currentTour}: Step {currentStep}
          </p>
          <button onClick={() => setCurrentStep(currentStep - 1)}>
            Previous
          </button>
          <button onClick={() => setCurrentStep(currentStep + 1)}>
            Next
          </button>
          <button onClick={closeNextStep}>Close</button>
        </div>
      )}
    </div>
  );
}
```

--------------------------------

### Using the NextStep Component

Source: https://github.com/enszrlu/nextstep/blob/main/README.md

Render the NextStep component to display tours. Customize its appearance and behavior using props. Ensure overlayZIndex is set higher for compatibility with UI libraries like MUI.

```tsx
<NextStep
  steps={steps}
  showNextStep={true}
  shadowRgb="55,48,163"
  shadowOpacity="0.8"
  cardComponent={CustomCard}
  cardTransition={{ duration: 0.5, type: 'spring' }}
  onStepChange={(step, tourName) => console.log(`Step changed to ${step} in ${tourName}`)}
  onComplete={(tourName) => console.log(`Tour completed: ${tourName}`)}
  onSkip={(step, tourName) => console.log(`Tour skipped: ${step} in ${tourName}`)}
  clickThroughOverlay={false}
  overlayZIndex={1400} // Set higher for MUI compatibility (MUI dialogs use 1300)
>
  {children}
</NextStep>
```