# LiveJoyride

A guided tour component for Phoenix LiveView applications. Create interactive step-by-step tours to onboard users or highlight features.

## Features

- Pure Elixir/LiveView implementation - no external JS dependencies
- Customizable styling via Tailwind CSS classes
- Spotlight effect highlights target elements
- Responsive tooltip positioning
- Progress tracking (step X of Y)
- Back/Next/Done navigation

## Installation

Add `live_joyride` to your dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:live_joyride, "~> 0.1.0"}
  ]
end
```

Then add the JavaScript hook to your `app.js`:

```javascript
import { Joyride } from "live_joyride"

let liveSocket = new LiveSocket("/live", Socket, {
  hooks: { Joyride, ...otherHooks }
})
```

If you installed via Hex, the JS is at:
```javascript
import { Joyride } from "../deps/live_joyride/assets/js"
```

## Usage

### 1. Mark target elements

Add `data-joyride` attributes to elements you want to highlight:

```heex
<div data-joyride="welcome-section">
  Welcome to our app!
</div>

<button data-joyride="submit-btn">Submit</button>
```

### 2. Add the component to your LiveView

```heex
<.live_component
  module={LiveJoyride.Component}
  id="tour"
  steps={[
    %{target: "welcome-section", title: "Welcome!", content: "This is where we greet you."},
    %{target: "submit-btn", title: "Submit", content: "Click here when you're done."}
  ]}
  run={@show_tour}
/>
```

### 3. Handle tour completion

```elixir
def handle_info({:tour_complete, "tour"}, socket) do
  {:noreply, assign(socket, show_tour: false)}
end
```

## Customization

Override default styles by passing a `classes` map:

```heex
<.live_component
  module={LiveJoyride.Component}
  id="tour"
  steps={@steps}
  run={@show_tour}
  classes={%{
    overlay: "bg-black/50",
    spotlight: "border-4 border-blue-500 rounded-lg",
    tooltip: "bg-white border border-gray-200 rounded-xl shadow-xl p-0",
    titlebar: "",  # Empty string hides the titlebar
    title: "text-lg font-bold text-gray-900",
    content: "text-sm text-gray-600",
    footer: "border-t border-gray-200 pt-3 mt-4",
    progress: "text-sm text-gray-500",
    button: "px-4 py-2 rounded border",
    button_primary: "bg-blue-500 text-white border-blue-500",
    button_back: "bg-white text-gray-700 border-gray-300",
    close: "w-4 h-4 rounded-full bg-red-500"
  }}
/>
```

### Available class keys

| Key | Description |
|-----|-------------|
| `overlay` | Dark backdrop behind spotlight |
| `spotlight` | Border around highlighted element |
| `tooltip` | Tooltip container |
| `titlebar` | Title bar (set to "" to hide) |
| `title` | Step title text |
| `content` | Step description text |
| `footer` | Footer with progress and buttons |
| `progress` | "1 of 6" text |
| `button` | Base button styles |
| `button_primary` | Next/Done button |
| `button_back` | Back button |
| `close` | Close button |

## Default Style

The default styling is inspired by classic Mac OS - a retro look with black borders and gradient backgrounds. Override with modern Tailwind classes as shown above.

## License

MIT License - see LICENSE file.