# Demo Onboarding Tour

Interactive onboarding tour system for BakeryIA demo sessions using Driver.js.

## Quick Start

```typescript
import { useDemoTour } from '@/features/demo-onboarding';

function MyComponent() {
  const { startTour, resumeTour, tourState } = useDemoTour();

  return (
    <button onClick={() => startTour()}>
      Start Tour
    </button>
  );
}
```

## Features

- ✅ **12-step desktop tour** in Spanish
- ✅ **8-step mobile tour** optimized for small screens
- ✅ **State persistence** with auto-resume
- ✅ **Analytics tracking** (Google Analytics, Plausible)
- ✅ **Conversion CTAs** throughout experience
- ✅ **Responsive design** across all devices
- ✅ **Accessibility** (ARIA, keyboard navigation)
- ✅ **Demo banner** with session status and time remaining countdown
- ✅ **Exit modal** with benefits reminder and conversion messaging

## Project Structure

```
demo-onboarding/
├── index.ts              # Public API exports
├── types.ts              # TypeScript interfaces
├── styles.css            # Driver.js custom theme
├── config/               # Configuration
│   ├── driver-config.ts  # Driver.js setup
│   └── tour-steps.ts     # Tour step definitions
├── hooks/                # React hooks
│   └── useDemoTour.ts    # Main tour hook
└── utils/                # Utilities
    ├── tour-state.ts     # State management (sessionStorage)
    └── tour-analytics.ts # Analytics tracking
```

## API Reference

### `useDemoTour()`

Main hook for controlling the tour.

**Returns:**
```typescript
{
  startTour: (fromStep?: number) => void;
  resumeTour: () => void;
  resetTour: () => void;
  tourActive: boolean;
  tourState: TourState | null;
}
```

### `getTourState()`

Get current tour state from sessionStorage.

**Returns:** `TourState | null`

### `saveTourState(state: Partial<TourState>)`

Save tour state to sessionStorage.

### `clearTourState()`

Clear tour state from sessionStorage.

### `shouldStartTour()`

Check if tour should auto-start.

**Returns:** `boolean`

### `trackTourEvent(event: TourAnalyticsEvent)`

Track tour analytics event.

## Tour Steps

### Desktop (12 steps)
1. Welcome to Demo Session
2. Real-time Metrics Dashboard
3. Pending Approvals
4. System Actions Log
5. Daily Production Plan
6. Database Navigation (Sidebar)
7. Daily Operations (Sidebar)
8. Analytics & AI (Sidebar)
9. Multi-Bakery Selector (Header)
10. Demo Limitations
11. Final CTA

### Mobile (8 steps)
Optimized version with navigation-heavy steps removed.

## State Management

Tour state is stored in `sessionStorage`:

```typescript
interface TourState {
  currentStep: number;
  completed: boolean;
  dismissed: boolean;
  lastUpdated: number;
  tourVersion: string;
}
```

## Analytics Events

Tracked events:
- `tour_started`
- `tour_step_completed`
- `tour_dismissed`
- `tour_completed`
- `conversion_cta_clicked`

Events are sent to Google Analytics and Plausible (if available).

## Styling

The tour uses a custom theme that matches BakeryIA's design system:
- CSS variables for colors
- Smooth animations
- Dark mode support
- Responsive breakpoints

## Data Attributes

The tour targets elements with `data-tour` attributes:

```tsx
<div data-tour="dashboard-stats">
  {/* Tour will highlight this element */}
</div>
```

**Available tour targets:**
- `demo-banner` - Demo banner
- `demo-banner-actions` - Banner action buttons
- `dashboard-stats` - Metrics grid
- `pending-po-approvals` - Approval requests
- `real-time-alerts` - System actions log
- `today-production` - Daily production plan
- `sidebar-database` - Database navigation
- `sidebar-operations` - Operations navigation
- `sidebar-analytics` - Analytics navigation
- `sidebar-menu-toggle` - Mobile menu button
- `header-tenant-selector` - Tenant switcher

## Integration

### Auto-start on Demo Login

```typescript
// DemoPage.tsx
import { markTourAsStartPending } from '@/features/demo-onboarding';

// After creating demo session
markTourAsStartPending();
navigate('/app/dashboard');
```

### Dashboard Auto-start

```typescript
// DashboardPage.tsx
import { useDemoTour, shouldStartTour } from '@/features/demo-onboarding';

const { startTour } = useDemoTour();
const isDemoMode = localStorage.getItem('demo_mode') === 'true';

useEffect(() => {
  if (isDemoMode && shouldStartTour()) {
    setTimeout(() => startTour(), 1500);
  }
}, [isDemoMode, startTour]);
```

## Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
- Mobile browsers

## Performance

- **Bundle Size**: +5KB gzipped (Driver.js)
- **Runtime**: Negligible
- **Load Time**: No impact (lazy loaded)

## See Also

- [DEMO_ONBOARDING_TOUR.md](../../../../../DEMO_ONBOARDING_TOUR.md) - Full implementation guide
- [Driver.js Documentation](https://driverjs.com/)