Improve the demo feature of the project
This commit is contained in:
Urtzi Alfaro
209
frontend/src/features/demo-onboarding/README.md
Normal file
209
frontend/src/features/demo-onboarding/README.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 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)
|
||||
|
||||
## 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. Intelligent Alerts
|
||||
4. Procurement Plans
|
||||
5. Production Management
|
||||
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
|
||||
- `real-time-alerts` - Alerts section
|
||||
- `procurement-plans` - Procurement section
|
||||
- `production-plans` - Production section
|
||||
- `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/)
|
||||
Reference in New Issue
Block a user