212 lines
4.7 KiB
Markdown
212 lines
4.7 KiB
Markdown
# 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/)
|