Files
bakery-ia/frontend/src/tours/tours.ts
Claude d42eadacc6 Implement Phase 7: Spanish Translations & Phase 9: Guided Tours
This commit implements comprehensive Spanish translations for all new onboarding
components and creates a complete guided tour framework for post-setup feature
discovery.

## Phase 7: Spanish Translations

### Spanish Onboarding Translations Added

**BakeryTypeSelectionStep translations (onboarding.bakery_type):**
- Title and subtitle for bakery type selection
- Production bakery: features, examples, and selected info
- Retail bakery: features, examples, and selected info
- Mixed bakery: features, examples, and selected info
- Help text and continue button

**DataSourceChoiceStep translations (onboarding.data_source):**
- Title and subtitle for configuration method
- AI-assisted setup: benefits, ideal scenarios, estimated time
- Manual setup: benefits, ideal scenarios, estimated time
- Info panels for both options with detailed requirements

**ProductionProcessesStep translations (onboarding.processes):**
- Title and subtitle for production processes
- Process types: baking, decorating, finishing, assembly
- Form labels and placeholders
- Template section with quick start option
- Navigation buttons and help text

**Updated Wizard Steps:**
- Added all new step titles and descriptions
- Updated navigation labels
- Enhanced progress indicators

### Translation Coverage

Total new translation keys added: **150+ keys**
- bakery_type: 40+ keys
- data_source: 35+ keys
- processes: 25+ keys
- wizard updates: 15+ keys
- Comprehensive coverage for all user-facing text

## Phase 9: Guided Tours

### Tour Framework Created

**TourContext (`/frontend/src/contexts/TourContext.tsx`):**
- Complete state management for tours
- Tour step navigation (next, previous, skip, complete)
- localStorage persistence for completed/skipped tours
- beforeShow and afterShow hooks for each step
- Support for custom actions in tour steps

**Key Features:**
- Track which tours are completed or skipped
- Prevent showing tours that are already done
- Support async operations in step hooks
- Centralized tour state across the app

### Tour UI Components

**TourTooltip (`/frontend/src/components/ui/Tour/TourTooltip.tsx`):**
- Intelligent positioning (top, bottom, left, right)
- Auto-adjusts if tooltip goes off-screen
- Progress indicators with dots
- Navigation buttons (previous, next, finish)
- Close/skip button
- Arrow pointing to target element
- Responsive design with animations

**TourSpotlight (`/frontend/src/components/ui/Tour/TourSpotlight.tsx`):**
- SVG mask overlay to dim rest of page
- Highlighted border around target element
- Smooth animations (fade in, pulse)
- Auto-scroll target into view
- Adjusts on window resize/scroll

**Tour (`/frontend/src/components/ui/Tour/Tour.tsx`):**
- Main container component
- Portal rendering for overlay
- Disables body scroll during tour
- Combines tooltip and spotlight

**TourButton (`/frontend/src/components/ui/Tour/TourButton.tsx`):**
- Three variants: icon, button, menu
- Shows all available tours
- Displays completion status
- Dropdown menu with tour descriptions
- Number of steps for each tour

### Predefined Tours Created

**5 comprehensive tours defined (`/frontend/src/tours/tours.ts`):**

1. **Dashboard Tour** (5 steps):
   - Welcome and overview
   - Key statistics cards
   - AI forecast chart
   - Inventory alerts
   - Main navigation

2. **Inventory Tour** (5 steps):
   - Inventory management overview
   - Adding new ingredients
   - Search and filters
   - Inventory table view
   - Stock alerts

3. **Recipes Tour** (5 steps):
   - Recipe management intro
   - Creating recipes
   - Automatic cost calculation
   - Recipe yield settings
   - Batch multiplier

4. **Production Tour** (5 steps):
   - Production planning overview
   - Production schedule calendar
   - AI recommendations
   - Creating production batches
   - Batch status tracking

5. **Post-Onboarding Tour** (5 steps):
   - Congratulations message
   - Main navigation overview
   - Quick actions
   - Notifications
   - Help resources

### Tour Translations

**New Spanish locale: `/frontend/src/locales/es/tour.json`:**
- Navigation labels (previous, next, finish, skip)
- Progress indicators
- Tour trigger button text
- Completion messages
- Tour names and descriptions

### Technical Implementation

**Features:**
- `data-tour` attributes for targeting elements
- Portal rendering for proper z-index layering
- Smooth animations with CSS classes
- Responsive positioning algorithm
- Scroll handling for dynamic content
- Window resize listeners
- TypeScript interfaces for type safety

**Usage Pattern:**
```typescript
// In any component
import { useTour } from '../contexts/TourContext';
import { dashboardTour } from '../tours/tours';

const { startTour } = useTour();
startTour(dashboardTour);
```

## Files Added

**Translations:**
- frontend/src/locales/es/tour.json

**Tour Framework:**
- frontend/src/contexts/TourContext.tsx
- frontend/src/components/ui/Tour/Tour.tsx
- frontend/src/components/ui/Tour/TourTooltip.tsx
- frontend/src/components/ui/Tour/TourSpotlight.tsx
- frontend/src/components/ui/Tour/TourButton.tsx
- frontend/src/components/ui/Tour/index.ts
- frontend/src/tours/tours.ts

## Files Modified

- frontend/src/locales/es/onboarding.json (150+ new translation keys)

## Testing

 Build successful (23.12s)
 No TypeScript errors
 All translations properly structured
 Tour components render via portals
 Spanish locale complete for all new features

## Integration Requirements

To enable tours in the app:

1. Add TourProvider to app root (wrap with TourProvider)
2. Add Tour component to render active tours
3. Add TourButton where help is needed
4. Add data-tour attributes to tour target elements

Example:
```tsx
<TourProvider>
  <App />
  <Tour />
</TourProvider>
```

## Next Steps

- Add TourProvider to application root
- Add data-tour attributes to target elements in pages
- Integrate TourButton in navigation/help sections
- Auto-trigger post-onboarding tour after setup complete
- Track tour analytics (views, completions, skip rates)

## Benefits

**For Users:**
- Smooth onboarding experience in Spanish
- Interactive feature discovery
- Contextual help when needed
- Can skip or restart tours anytime
- Never see same tour twice (unless restarted)

**For Product:**
- Reduce support requests
- Increase feature adoption
- Improve user confidence
- Better user experience
- Track which features need improvement
2025-11-06 12:45:31 +00:00

277 lines
8.5 KiB
TypeScript

import { Tour } from '../contexts/TourContext';
/**
* Dashboard Tour
* Guides users through the main dashboard features
*/
export const dashboardTour: Tour = {
id: 'dashboard-tour',
name: 'Tour del Dashboard',
steps: [
{
id: 'dashboard-welcome',
target: '[data-tour="dashboard-header"]',
title: '¡Bienvenido a tu Dashboard!',
content:
'Este es tu centro de control. Aquí verás un resumen de toda tu operación de panadería en tiempo real.',
placement: 'bottom',
},
{
id: 'dashboard-stats',
target: '[data-tour="stats-cards"]',
title: 'Estadísticas Clave',
content:
'Estas tarjetas muestran las métricas más importantes: ventas del día, inventario crítico, producción pendiente y alertas de calidad.',
placement: 'bottom',
},
{
id: 'dashboard-forecast',
target: '[data-tour="forecast-chart"]',
title: 'Pronóstico de Demanda con IA',
content:
'Nuestra IA analiza tus datos históricos para predecir la demanda futura. Úsalo para planificar tu producción.',
placement: 'top',
},
{
id: 'dashboard-inventory',
target: '[data-tour="inventory-alerts"]',
title: 'Alertas de Inventario',
content:
'Aquí verás alertas sobre ingredientes que están por agotarse o que han caducado. ¡Nunca te quedarás sin stock!',
placement: 'left',
},
{
id: 'dashboard-navigation',
target: '[data-tour="main-navigation"]',
title: 'Navegación Principal',
content:
'Usa este menú para acceder a todas las funciones: Inventario, Recetas, Producción, Ventas, Proveedores y más.',
placement: 'right',
},
],
};
/**
* Inventory Tour
* Guides users through inventory management features
*/
export const inventoryTour: Tour = {
id: 'inventory-tour',
name: 'Tour de Inventario',
steps: [
{
id: 'inventory-welcome',
target: '[data-tour="inventory-header"]',
title: 'Gestión de Inventario',
content:
'Aquí administras todos tus ingredientes y productos terminados. Mantén el control total de tu stock.',
placement: 'bottom',
},
{
id: 'inventory-add',
target: '[data-tour="add-item-button"]',
title: 'Agregar Ingredientes',
content:
'Haz clic aquí para agregar nuevos ingredientes. Puedes ingresar nombre, categoría, unidad de medida, precio y más.',
placement: 'left',
action: {
label: 'Ver formulario',
onClick: () => {
const button = document.querySelector('[data-tour="add-item-button"]') as HTMLButtonElement;
button?.click();
},
},
},
{
id: 'inventory-search',
target: '[data-tour="search-filter"]',
title: 'Buscar y Filtrar',
content:
'Usa la barra de búsqueda y filtros para encontrar rápidamente lo que necesitas. Filtra por categoría, estado de stock o proveedor.',
placement: 'bottom',
},
{
id: 'inventory-table',
target: '[data-tour="inventory-table"]',
title: 'Lista de Inventario',
content:
'Aquí ves todos tus ingredientes con stock actual, punto de reorden, costo y acciones rápidas para editar o eliminar.',
placement: 'top',
},
{
id: 'inventory-alerts',
target: '[data-tour="stock-alerts"]',
title: 'Alertas de Stock',
content:
'Los ingredientes con stock bajo aparecen resaltados. Configura puntos de reorden para recibir alertas automáticas.',
placement: 'left',
},
],
};
/**
* Recipes Tour
* Guides users through recipe management
*/
export const recipesTour: Tour = {
id: 'recipes-tour',
name: 'Tour de Recetas',
steps: [
{
id: 'recipes-welcome',
target: '[data-tour="recipes-header"]',
title: 'Gestión de Recetas',
content:
'Define tus recetas con ingredientes, cantidades y procesos. El sistema calculará costos automáticamente.',
placement: 'bottom',
},
{
id: 'recipes-add',
target: '[data-tour="add-recipe-button"]',
title: 'Crear Receta',
content:
'Haz clic para crear una nueva receta. Agrega ingredientes, define cantidades y establece el rendimiento esperado.',
placement: 'left',
},
{
id: 'recipes-cost',
target: '[data-tour="recipe-cost-column"]',
title: 'Cálculo de Costos',
content:
'El sistema calcula automáticamente el costo de cada receta basándose en los precios de los ingredientes.',
placement: 'top',
},
{
id: 'recipes-yield',
target: '[data-tour="recipe-yield"]',
title: 'Rendimiento de Receta',
content:
'Define cuántas unidades produce cada receta. Esto es crucial para planificar la producción correctamente.',
placement: 'bottom',
},
{
id: 'recipes-batch',
target: '[data-tour="batch-multiplier"]',
title: 'Multiplicador de Lote',
content:
'¿Necesitas hacer múltiples lotes? Usa el multiplicador para escalar automáticamente las cantidades de ingredientes.',
placement: 'left',
},
],
};
/**
* Production Tour
* Guides users through production planning
*/
export const productionTour: Tour = {
id: 'production-tour',
name: 'Tour de Producción',
steps: [
{
id: 'production-welcome',
target: '[data-tour="production-header"]',
title: 'Planificación de Producción',
content:
'Planifica qué y cuánto producir cada día. El sistema te ayudará basándose en el pronóstico de demanda.',
placement: 'bottom',
},
{
id: 'production-schedule',
target: '[data-tour="production-schedule"]',
title: 'Calendario de Producción',
content:
'Visualiza tu plan de producción por día, semana o mes. Arrastra y suelta para reorganizar fácilmente.',
placement: 'top',
},
{
id: 'production-forecast',
target: '[data-tour="production-forecast"]',
title: 'Recomendaciones de IA',
content:
'La IA sugiere cantidades óptimas basadas en el pronóstico de demanda, inventario actual y ventas históricas.',
placement: 'bottom',
},
{
id: 'production-batch',
target: '[data-tour="create-batch-button"]',
title: 'Crear Lote de Producción',
content:
'Crea un nuevo lote seleccionando la receta y cantidad. El sistema verificará que tengas suficiente inventario.',
placement: 'left',
},
{
id: 'production-status',
target: '[data-tour="production-status"]',
title: 'Estado de Lotes',
content:
'Rastrea el estado de cada lote: Planificado, En Proceso, Completado o Cancelado. Actualiza en tiempo real.',
placement: 'top',
},
],
};
/**
* Post-Onboarding Tour
* First tour shown after completing onboarding
*/
export const postOnboardingTour: Tour = {
id: 'post-onboarding-tour',
name: 'Primeros Pasos',
steps: [
{
id: 'welcome',
target: 'body',
title: '¡Configuración Completa! 🎉',
content:
'Tu panadería está lista. Ahora te mostraremos las funciones principales para que puedas empezar a trabajar.',
placement: 'bottom',
},
{
id: 'dashboard-overview',
target: '[data-tour="main-navigation"]',
title: 'Navegación Principal',
content:
'Desde aquí puedes acceder a todas las secciones: Dashboard, Inventario, Recetas, Producción, Ventas y más.',
placement: 'right',
},
{
id: 'quick-actions',
target: '[data-tour="quick-actions"]',
title: 'Acciones Rápidas',
content:
'Usa estos botones para acciones frecuentes: agregar ingrediente, crear receta, planificar producción.',
placement: 'bottom',
},
{
id: 'notifications',
target: '[data-tour="notifications-button"]',
title: 'Notificaciones',
content:
'Aquí verás alertas importantes: stock bajo, lotes pendientes, vencimientos próximos.',
placement: 'left',
},
{
id: 'help',
target: '[data-tour="help-button"]',
title: 'Ayuda Siempre Disponible',
content:
'Si necesitas ayuda, haz clic aquí para acceder a tutoriales, documentación o contactar soporte.',
placement: 'left',
},
],
};
/**
* All available tours
*/
export const allTours = {
dashboard: dashboardTour,
inventory: inventoryTour,
recipes: recipesTour,
production: productionTour,
postOnboarding: postOnboardingTour,
};
export default allTours;