Belake.ai Chat Component

Um componente de chat moderno e completo para React + TypeScript, pronto para publicação no NPM como belakeai-components-chat.

📋 Índice

• Instalação
• Uso Básico
• Funcionalidades
• API Reference
• Configuração
• Exemplos
• Desenvolvimento
• Testes
• Suporte
• Licença

🚀 Instalação

npm install belakeai-components-chat
# ou
yarn add belakeai-components-chat
# ou
pnpm add belakeai-components-chat

📖 Uso Básico

import React, { useState } from 'react';
import { Chat } from 'belakeai-components-chat';

const App = () => {
  const [chatTitle, setChatTitle] = useState("Minha Conversa");
  const [isEditingTitle, setIsEditingTitle] = useState(false);

  return (
    <div style={{ height: '600px' }}>
      <Chat
        url="/api/chat"
        token="your-auth-token"
        theme={{
          primary: "#0074f9",
          secondary: "#ffffff",
          tertiary: "#f9fafb"
        }}
        chatTitle={chatTitle}
        isEditingTitle={isEditingTitle}
        onChatTitleChange={(newTitle) => {
          setChatTitle(newTitle);
          setIsEditingTitle(false);
        }}
        onChatTitleEditStart={() => setIsEditingTitle(true)}
        onChatTitleEditCancel={() => setIsEditingTitle(false)}
        onMessageSent={(message) => console.log('Mensagem:', message)}
      />
    </div>
  );
};

✨ Funcionalidades

🎯 Funcionalidades Principais

• ✅ Envio de mensagens - Interface intuitiva para digitação e envio
• ✅ Anexos de arquivos - Suporte a drag-and-drop e seleção manual
• ✅ Markdown avançado - Renderização completa incluindo tabelas, código e links
• ✅ Edição de título - Título editável com interface suave
• ✅ Agentes múltiplos - Suporte a seleção de múltiplos agentes de IA
• ✅ Reações - Sistema de curtir/descurtir mensagens
• ✅ Exportação - Exportar conversas para Word/PDF
• ✅ Tema customizável - Suporte a modo escuro/claro
• ✅ Responsivo - Interface adaptável para mobile e desktop
• ✅ Acessibilidade - Totalmente acessível com ARIA labels

🎨 Recursos de Interface

• Animações suaves - Transições e feedbacks visuais
• Syntax highlighting - Destaque de código com múltiplas linguagens
• Tooltips informativos - Ajuda contextual em toda interface
• Estados de carregamento - Indicadores visuais para operações assíncronas
• Avatares de agentes - Personalização visual dos agentes de IA

📱 Recursos Mobile

• Touch gestures - Suporte a gestos de toque
• Layout responsivo - Adaptação automática para diferentes tamanhos
• Performance otimizada - Renderização eficiente em dispositivos móveis

📚 API Reference

Props Principais

Configuração Básica

| Prop | Tipo | Obrigatório | Descrição | |------|------|-------------|-----------| | url | string | ✅ | Endpoint da API do chat | | token | string | ✅ | Token de autenticação | | theme | Theme | ✅ | Objeto com cores do tema |

Configuração de Aparência

| Prop | Tipo | Padrão | Descrição | |------|------|--------|-----------| | language | 'pt' \| 'en' \| 'es' | 'pt' | Idioma da interface | | darkMode | boolean | false | Ativar modo escuro | | chatTitle | string | - | Título da conversa | | isEditingTitle | boolean | false | Estado de edição do título | | showTimestamps | boolean | true | Exibir timestamps nas mensagens | | showAgentAvatars | boolean | true | Exibir avatares dos agentes | | showAgentNames | boolean | true | Exibir nomes dos agentes |

Configuração de Funcionalidades

| Prop | Tipo | Padrão | Descrição | |------|------|--------|-----------| | allowFileAttachment | boolean | true | Permitir anexos de arquivo | | allowMultipleAgentSelection | boolean | true | Permitir seleção múltipla de agentes | | allowMarkdownFormatting | boolean | true | Habilitar renderização markdown | | enableReactions | boolean | true | Habilitar sistema de reações | | enableCopyMessages | boolean | true | Habilitar cópia de mensagens | | enableExportToWord | boolean | true | Habilitar exportação para Word | | maxFileSize | number | 10 | Tamanho máximo de arquivo (MB) | | maxMessageLength | number | 4000 | Tamanho máximo da mensagem |

Event Handlers

| Prop | Tipo | Descrição | |------|------|-----------| | onMessageSent | (message: string, agents: Agent[], attachments?: File[]) => void | Disparado ao enviar mensagem | | onChatTitleChange | (title: string) => void | Disparado ao alterar título | | onChatTitleEditStart | () => void | Disparado ao iniciar edição do título | | onChatTitleEditCancel | () => void | Disparado ao cancelar edição do título | | onAgentClick | (agent: Agent) => void | Disparado ao clicar em agente | | onCopyUserMessage | (messageId: string, content: string) => void | Disparado ao copiar mensagem do usuário | | onCopyAgentMessage | (messageId: string, content: string) => void | Disparado ao copiar mensagem do agente | | onShareAgentMessage | (messageId: string, content: string) => void | Disparado ao compartilhar mensagem | | onLikeAgentMessage | (messageId: string) => void | Disparado ao curtir mensagem | | onDislikeAgentMessage | (messageId: string) => void | Disparado ao descurtir mensagem |

Tipos TypeScript

interface Theme {
  primary: string;    // Cor primária (ex: "#0074f9")
  secondary: string;  // Cor secundária (ex: "#ffffff")
  tertiary: string;   // Cor terciária (ex: "#f9fafb")
}

interface Agent {
  id: string;
  name: string;
  avatar?: string;
  status: 'online' | 'offline';
  color: string;
  knowledgeBases?: KnowledgeBase[];
}

interface Message {
  id: string;
  content: string;
  type: 'user' | 'ai';
  timestamp: Date;
  agent?: Agent;
  selectedAgents?: Agent[];
  attachments?: File[];
  likes?: number;
  dislikes?: number;
  userReaction?: 'like' | 'dislike' | null;
  hasChart?: boolean;
  chartData?: any;
  hasCode?: boolean;
  codeContent?: string;
  codeExplanation?: string;
}

interface KnowledgeBase {
  id: string;
  name: string;
  type: 'datasources' | 'files';
}

⚙️ Configuração

Tema Customizado

const customTheme = {
  primary: "#6366f1",      // Indigo
  secondary: "#f8fafc",    // Slate-50
  tertiary: "#f1f5f9"      // Slate-100
};

<Chat theme={customTheme} />

Agentes Personalizados

const agents = [
  {
    id: "agent-1",
    name: "Assistente Geral",
    avatar: "/avatar1.png",
    status: "online",
    color: "#10b981",
    knowledgeBases: [
      { id: "kb1", name: "Documentação", type: "files" }
    ]
  },
  {
    id: "agent-2",
    name: "Especialista Técnico",
    avatar: "/avatar2.png",
    status: "offline",
    color: "#3b82f6"
  }
];

<Chat agents={agents} />

Mensagens Iniciais

const initialMessages = [
  {
    id: "1",
    content: "Olá! Como posso ajudar você hoje?",
    type: "ai",
    timestamp: new Date(),
    agent: agents[0]
  }
];

<Chat initialMessages={initialMessages} />

🛠️ Desenvolvimento

Pré-requisitos

• Node.js 18+
• npm, yarn ou pnpm

Setup Local

# Clone o repositório
git clone https://github.com/belakeai/chat-component
cd chat-component

# Instale dependências
npm install

# Execute em modo desenvolvimento
npm run dev

# Execute testes
npm test

# Build para produção
npm run build

Estrutura do Projeto

src/
├── components/
│   └── Chat/
│       ├── Chat.tsx           # Componente principal
│       ├── types.ts           # Definições TypeScript
│       ├── translations.ts    # Traduções i18n
│       └── index.ts          # Exports
├── examples/                  # Exemplos de uso
└── tests/                    # Testes unitários

Scripts Disponíveis

npm run dev          # Desenvolvimento
npm run build        # Build produção
npm run test         # Executar testes
npm run test:watch   # Testes em modo watch
npm run test:coverage # Cobertura de testes
npm run lint         # Linting
npm run type-check   # Verificação TypeScript

🧪 Testes

O projeto possui cobertura de testes abrangente usando Vitest e React Testing Library.

Executar Testes

# Todos os testes
npm test

# Modo watch
npm run test:watch

# Com cobertura
npm run test:coverage

# Testes específicos
npm test -- Chat.test.tsx

Cobertura Atual

• Statements: 95%+
• Branches: 90%+
• Functions: 95%+
• Lines: 95%+

Tipos de Teste

Testes Unitários

• Renderização de componentes
• Manipulação de estado
• Event handlers
• Validação de props

Testes de Integração

• Fluxo completo de envio de mensagem
• Interação entre componentes
• Markdown rendering
• File upload

Testes de Acessibilidade

• ARIA labels
• Navegação por teclado
• Screen reader compatibility
• Color contrast

🐛 Troubleshooting

Problemas Comuns

1. Componente não renderiza

// ❌ Problema: Container sem altura definida
<div>
  <Chat {...props} />
</div>

// ✅ Solução: Definir altura do container
<div style={{ height: '600px' }}>
  <Chat {...props} />
</div>

2. Estilos não aplicados

// ❌ Problema: CSS não importado
import { Chat } from 'belakeai-components-chat';

// ✅ Solução: Importar CSS
import 'belakeai-components-chat/dist/style.css';
import { Chat } from 'belakeai-components-chat';

📞 Suporte

Documentação

• API Reference completa
• Guia de migração
• Troubleshooting

Comunidade

• Discord
• GitHub Issues
• Stack Overflow

Suporte Comercial

• Email: [email protected]

Contribuindo

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -m 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

📄 Licença

MIT License - veja LICENSE para detalhes.

Belake.ai Chat Component - Construído com ❤️ pela equipe Belake.ai