Componente HelpChat

HelpChat (Container)
├── HelpChatUI (Presentational)
├── useHelpChat (UI Logic Hook)
├── useHelpChatActions (Business Logic Hook)
└── Services (API Integration)

User Input → useHelpChat → useHelpChatActions → API Service → State Update → UI Render

src/components/molecules/helpChat/
├── index.tsx                          # Componente principal (Container)
├── HelpChatUI.tsx                     # Componente de presentación
├── useHelpChat.tsx                    # Hook para lógica de UI
├── types.ts                           # Definiciones de tipos TypeScript
├── helpChat.module.scss               # Estilos CSS Modules
├── index.test.tsx                     # Tests del componente principal
├── HelpChatUI.test.tsx               # Tests del componente UI
├── useHelpChat.test.tsx              # Tests del hook UI
├── types.test.ts                     # Tests de tipos

src/modules/helpChat/
├── index.ts                          
├── hooks/
│   ├── useHelpChatActions.ts         # Hook para acciones del chat
│   └── useHelpChatActions.test.ts    # Tests del hook de acciones
└── services/
    ├── index.ts                      # Servicios de API
    └── index.test.ts                 # Tests de servicios

src/language/
└── help-chat.json                    # Traducciones del chat

export type ChatMessage = {
  id: string // Identificador único del mensaje
  type: 'question' | 'answer' | 'guide' // Tipo de mensaje
  content: string // Contenido del mensaje
  section: ChatSection // Sección del chat
  keywords?: string[] // Palabras clave (opcional)
  relatedActions?: ChatAction[] // Acciones relacionadas (opcional)
  isError?: boolean // Indica si es un mensaje de error
}

export type ChatAction = {
  id: string // Identificador único
  label: string // Etiqueta mostrada al usuario
  type: 'navigate' | 'modal' | 'external' // Tipo de acción
  action: string // Acción a ejecutar
  icon?: string // Icono (opcional)
}

export interface ChatRequest {
  message: string // Mensaje del usuario
}
 
export interface ChatResponse {
  response?: string // Respuesta del AI
  message?: string // Mensaje alternativo
  [key: string]: unknown // Campos adicionales
}

const chatState = {
  isOpen: boolean,      // Estado de apertura del chat
  isLoading: boolean    // Estado de carga
}

{
  chatState,           // Estado del chat
  chatHistory,         // Historial de mensajes
  languageSelect,      // Idioma seleccionado
  translations,        // Traducciones
  isAuthenticated,     // Estado de autenticación
  toggleChat,          // Alternar apertura del chat
  closeChat,           // Cerrar chat
  sendMessage,         // Enviar mensaje
  clearHistory         // Limpiar historial
}

1. onMutate: Agregar mensaje del usuario inmediatamente (Optimistic UI)
2. mutationFn: Enviar mensaje a API
3. onSuccess: Procesar respuesta y agregar mensaje del bot
4. onError: Mostrar mensaje de error

export const sendChatMessage = async (
  data: ChatRequest
): Promise<ChatResponse> =>
  globalfunctions<ChatResponse, ChatRequest>(`/agent`, 'POST', data)

interface ChatState {
  // Estado UI
  isOpen: boolean // Chat abierto/cerrado
  isLoading: boolean // Procesando mensaje
 
  // Datos
  chatHistory: ChatMessage[] // Historial de conversación
 
  // Contexto
  languageSelect: string // Idioma actual
  isAuthenticated: boolean // Estado de autenticación
}

const quickSuggestions = [
  'Crea un nuevo proyecto',
  'Crear una versión',
  'Agregar una pantalla',
]

export const LayoutClient = ({ children }: props) => {
  const { themeSelected } = useTheme()
 
  return (
    <QueryClientProvider client={client}>
      <AuthProvider>
        <ThemeProvider theme={themeSelected}>
          <AlertGlobal />
          <ModalGlobal />
          <HelpChat />  {/* 👈 Renderizado global */}
          {children}
        </ThemeProvider>
      </AuthProvider>
    </QueryClientProvider>
  )
}

QueryClientProvider
├── AuthProvider
    ├── ThemeProvider
        ├── AlertGlobal
        ├── ModalGlobal
        ├── HelpChat (z-index: 1300)
        └── {children} (páginas de la app)

$primary-orange: #ff8324; // Color principal (botones, acentos)
$light-orange: #fff7f0; // Fondo mensajes usuario
$error-red: #dc3f3f; // Mensajes de error
$background-white: #ffffff; // Fondo principal
$border-gray: #f3f3f3; // Bordes y separadores
$text-gray: #656565; // Texto secundario

// Títulos
font-weight: 700;
font-size: 20px;
color: #1d2734;
 
// Subtítulos
font-weight: 300;
font-size: 13px;
 
// Mensajes
font-weight: 300;
font-size: 14px;
line-height: 1.6;

<Fab
  sx={{
    background: 'linear-gradient(135deg, #ff8324, #ff6b1a)',
    '&:hover': {
      transform: 'scale(1.05)',
      boxShadow: '0 6px 24px rgba(0, 0, 0, 0.2)',
    }
  }}
>

// Entrada del chat
@keyframes slideLeft {
  from {
    opacity: 0;
    transform: translateX(40px);
  }
  to {
    opacity: 1;
    transform: translateX(0);
  }
}
 
// Hover effects
transition: all 0.3s ease-in-out;

const { languageSelect, translations } = useLanguageContext()

{
  "help-chat.key": {
    "es": "Texto en español",
    "en": "Text in English"
  }
}

onError: (error) => {
  const errorMessage: ChatMessage = {
    id: `error-${Date.now()}`,
    type: 'answer',
    content: `Error de conexión: ${error.message}`,
    isError: true,
  }
  setChatHistory((prev) => [...prev, errorMessage])
}

if (!auth.user?.access_token) {
  // Mostrar mensaje de error de autenticación
  return
}

if (!message.trim()) {
  // No enviar mensaje vacío
  return
}

// Mensaje de error con estilos especiales
{message.isError ? (
  <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
    <WarningIcon sx={{ color: '#DC3F3F' }} />
    <Typography sx={{ color: '#DC3F3F' }}>
      {message.content}
    </Typography>
  </Box>
) : (
  <Typography>{message.content}</Typography>
)}

const placeholderText =
  translations?.helpChat?.['help-chat.input-placeholder']?.[languageSelect] ||
  'Texto por defecto'

// Ejemplo de test
import { render, screen, fireEvent } from '@testing-library/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import HelpChat from './index'
 
describe('HelpChat Component', () => {
  test('should open chat when FAB is clicked', () => {
    render(<HelpChat />)
    const fab = screen.getByLabelText(/abrir chat/i)
    fireEvent.click(fab)
    expect(screen.getByText(/centro de ayuda/i)).toBeInTheDocument()
  })
})

// Mock del servicio de chat
jest.mock('../services', () => ({
  sendChatMessage: jest.fn(() =>
    Promise.resolve({ response: 'Mocked response' })
  ),
}))

const { mutate: sendMessage, isPending: isLoading } = useMutation({
  mutationFn: sendChatMessage,
  mutationKey: ['sendChatMessage'],
  // Cache automático de respuestas
})

const toggleChat = useCallback(() => {
  setIsOpen((prev) => !prev)
}, [])
 
const closeChat = useCallback(() => {
  setIsOpen(false)
}, [])

onMutate: (variables) => {
  // Actualización inmediata de UI antes de respuesta del servidor
  const userMessage = {
    /* ... */
  }
  setChatHistory((prev) => [...prev, userMessage])
}

// El chat solo se renderiza cuando está abierto
if (!chatState.isOpen) {
  return <Fab onClick={toggleChat} />
}

const scrollToBottom = () => {
  messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
}
 
// Debounced scroll
useEffect(() => {
  setTimeout(scrollToBottom, 100)
}, [chatState.isOpen, chatHistory.length])

{
  "@mui/material": "^5.x.x",
  "@mui/icons-material": "^5.x.x",
  "@tanstack/react-query": "^5.x.x",
  "react-oidc-context": "^2.x.x",
  "sass": "^1.x.x"
}

# Desarrollo
npm run dev
 
# Build de producción
npm run build
 
# Testing
npm test

// En types.ts
export type ChatMessage = {
  // ... propiedades existentes
  newProperty?: NewType // Agregar nueva propiedad
}

// En help-chat.json
{
  "help-chat.new-key": {
    "es": "Nuevo texto",
    "en": "New text"
  }
}

// En helpChat.module.scss
.helpChat {
  &__newElement {
    // Nuevos estilos
  }
}

// En useHelpChatActions.ts
const newFeature = useCallback(() => {
  // Implementación
}, [dependencies])
 
return {
  // ... propiedades existentes
  newFeature,
}

// Debug condicional
if (process.env.NODE_ENV === 'development') {
  console.log('Chat state:', chatState)
}