White Library – Componente de Chat para React

Librería de componentes de chat en React con soporte de audio, escrita en TypeScript y lista para personalizar estilos y comportamiento sin depender de CSS externos.

Características

• 🎨 Temas 100% personalizables (colores, bordes, tipografías, layout)
• 🎤 Grabación y envío de audio (MediaRecorder) y reproducción
• 💬 Indicador de escritura y autodesplazamiento
• 🧩 API clara con tipos (TypeScript)
• ⚡ Empaquetado con Vite (ESM y UMD)
• 📦 Sin dependencias de CSS (estilos inline)

Instalación

npm install white-library
# o
yarn add white-library
# o
pnpm add white-library

Peer deps:

• React >= 18
• React DOM >= 18

Uso rápido

import React from 'react';
import { ChatPage, defaultChatTheme, defaultChatConfig } from 'white-library';

export default function App() {
  const config = {
    ...defaultChatConfig,
    agentUrl: 'https://tu-api-del-agente.com/webhook', // OBLIGATORIO
    texts: { headerTitle: 'Mi Asistente' }
  };

  return (
    <div style={{ width: 600, height: 600 }}>
      <ChatPage theme={defaultChatTheme} config={config} />
    </div>
  );
}

Importante: agentUrl es obligatorio para poder enviar mensajes al backend. Si no se configura, el envío producirá un error controlado.

Props principales

• ChatPage
  • theme?: ChatTheme – Personalización visual del contenedor, header, burbujas, input, etc.
  • config?: ChatConfig – Textos y comportamiento. Debe incluir agentUrl.
  • className?: string – Clase extra para el contenedor raíz.

Los tipos y valores por defecto están exportados desde la librería:

• defaultChatTheme, defaultChatConfig
• Tipos: ChatTheme, ChatConfig, BubbleStyle, HeaderConfig, BorderConfig, InputConfig

Configuración (ChatConfig)

Estructura relevante:

• agentUrl: string (obligatorio)
• texts?:
  • headerTitle, inputPlaceholder, recordingText, listeningText, sendButtonAlt, recordButtonAlt, stopButtonAlt, playButtonAlt, pauseButtonAlt, loadingMessage
• behavior?:
  • autoScroll (bool), showTypingIndicator (bool), enableAudio (bool), maxMessageLength (número), recordingTimeLimit (ms)

Temas (ChatTheme)

Áreas personalizables:

• container: ancho/alto, bordes, fondo (incluye gradients), sombra
• header: título, icono SVG, colores, tamaños, alineación
• bubbles: estilos de user, assistant y system (colores, bordes, radios, paddings, tipografías)
• input: colores, placeholder, foco, botones (send/record/stop/play/pause), tamaños
• messageList: padding, separación, colores, altura máxima
• loadingIndicator: color y tamaño

Ejemplo breve de tema:

import { ChatPage, defaultChatTheme } from 'white-library';

const theme = {
  ...defaultChatTheme,
  header: { ...defaultChatTheme.header, backgroundColor: '#2563eb', titleColor: '#fff' },
  bubbles: { 
    ...defaultChatTheme.bubbles,
    user: { ...defaultChatTheme.bubbles?.user, backgroundColor: '#2563eb', textColor: '#fff' }
  }
};

Flujo de mensajes y backend (agentUrl)

La librería envía las interacciones al endpoint indicado en config.agentUrl mediante el store interno. Formatos de solicitud:

• Texto (POST JSON):
  • headers: { 'Content-Type': 'application/json' }
  • body: { message: string, sessionId: string, type: 'text' }
• Audio (POST multipart/form-data):
  • formData: { audio: Blob(ogg), sessionId: string, type: 'audio' }

Formato de respuesta esperado (flexible):

• Objeto con múltiples campos string (p.ej. { Parte1: '...', Parte2: '...' }): se mostrarán como varios mensajes del assistant con un pequeño delay entre ellos.
• Objeto con campo Informe (string): se interpreta como estudio/resultado final y se notifica al usuario.
• Cualquier otro caso: se muestra un mensaje genérico de “Respuesta recibida”.

Gestión de sesión: el store genera y persiste un sessionId con expiración (por defecto 2h) y lo revalida automáticamente.

Componentes y Hooks exportados

• ChatPage: componente todo-en-uno listo para usar.
• ChatInput: input con envío de texto y grabación de audio.
  • Props clave: input, setInput, onSendMessage(message), onSendAudio(base64), isPlaying, setIsPlaying, audioRef, theme, config.
• ChatHeader: encabezado con título e icono SVG opcional.
• ChatMessage: burbuja de mensaje (para usos avanzados).
• Hooks: useChatConversationStore, useStaticAgentStore (gestión de mensajes, sesión y llamadas a agentUrl).

Desarrollo local

• Dev: npm run dev
• Lint: npm run lint
• Build de la librería: npm run build:lib

Licencia

MIT