npm package: @motiadev/tutorial-driver
Description: A Tutorial Driver used by Motia
Author: Sergio Marcelino
Latest version: 1.0.1

# Motia Tutorial Driver

A lightweight Tutorial Driver used and built by Motia.

## Installation

```bash
pnpm add @motiadev/tutorial-driver
```

### Add the CSS to your project

Make sure you add the CSS to the root of your project.

```typescript
import '@motiadev/tutorial-driver/tutorial.css'
```

Or use it in your `index.css` file.

```css
@import '@motiadev/tutorial-driver/tutorial.css';
```

## Usage

```tsx
import { Tutorial, useTutorialEngine } from '@motiadev/tutorial-driver'

const steps: TutorialStepConfig[] = [
  {
    title: 'Test Tutorial',
    description: () => <div>This is a test tutorial</div>,
  },
]

export const TestTutorial = () => {
  const engine = useTutorialEngine({ steps })
  return <Tutorial engine={engine} />
}
```

## Properties on TutorialStepConfig

`TutorialStepConfig` defines the configuration for a single tutorial step in the tutorial sequence. Below are the properties you can use:

| Property      | Type                              | Required | Description                                                                                                                                   |
| ------------- | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | `string`                          | Yes      | The header text to show for this step.                                                                                                        |
| `description` | `React.FC<void>`                  | Yes      | A React functional component that renders the content of this tutorial step.                                                                  |
| `image`       | `{ height: number, src: string }` | No       | _(Optional)_ An image to display within the step. The object should contain `height` (in pixels) and `src` (URL string for the image source). |
| `link`        | `string`                          | No       | _(Optional)_ A URL to provide for additional information or a related action. Appears as a link in the step.                                  |
| `selector`    | `string` or `XPath`               | No       | _(Optional)_ An XPath or string selector pointing to the element this step is associated with or highlights.                                  |
| `before`      | `TutorialAction[]`                | No       | _(Optional)_ An array of actions (such as simulated clicks or custom callbacks) to perform before this step displays.                         |

### Example

```tsx
const steps: TutorialStepConfig[] = [
  {
    // this is going to show the title of the step
    title: 'Welcome',

    // this is going to show the content of the step
    description: () => <div>Start your journey!</div>,

    // this is going to show an image in the step
    image: { height: 120, src: '/images/tutorial-start.png' },

    // this is going to show a link to the tutorial documentation
    link: 'https://product-docs.example.com/tutorial',

    // this is going to highlight the button with the class 'start-tutorial'
    selector: xpath('button').attr('class', 'start-tutorial'),

    // this is going to click the button with the class 'show-intro' before the step is displayed
    before: [{ type: 'click', selector: xpath('button').attr('class', 'show-intro') }],
  },
  // ...more steps...
]
```

_See type definitions for [`TutorialAction`](#) and [`XPath`](#) for advanced usage._

## Selectors

This library uses XPath to select elements, but it
comes with a fluent API to make it easier to use for most cases.

Examples of selectors:

### Select tags by attribute

- `xpath('img').attr('class', 'logo')`
- `xpath('img').attr('class', 'logo react')`
- `xpath('button').attr('class', 'btn-counter')`
- `xpath('button').attr('data-testid', 'test-id')`

### Select tags by text

- `xpath('p').textContains('Click on the Vite and React logos to learn more')`

### Select tags by attribute containing

- `xpath('img').attrContains('class', 'logo')`
- `xpath('button').attrContains('class', 'btn')`

## Overriding Styles

You can override the styles of the tutorial by using the following CSS variables.

```css
:root {
  --tutorial-border-color: rgb(65, 65, 65);
  --tutorial-text-color: rgb(240, 240, 240, 0.8);
  --tutorial-code-bg: rgb(24, 24, 24, 0.4);
  --tutorial-code-text: rgb(240, 240, 240, 1);
  --tutorial-background: rgb(24, 24, 24, 1);

  --tutorial-accent-color: rgb(0, 115, 255);
  --tutorial-accent-color-hover: rgb(0, 145, 255);
  --tutorial-accent-color-text: rgb(255, 255, 255);
  --tutorial-accent-color-text-hover: rgb(255, 255, 255);

  --tutorial-muted-foreground: rgb(140, 140, 143);

  --tutorial-shadow: 0 10px 15px -3px var(--tw-shadow-color, #0000001a), 0 4px 6px -4px var(--tw-shadow-color, #0000001a);
  --base-font-size: 14px;
}
```