Files
bakery-ia/frontend/src/tours/tours.ts

277 lines
8.5 KiB
TypeScript
Raw Normal View History

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
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;