amb-ia-chat-widget

v1.6.0

Published

3 months ago

Widget de chat AMB-IA para integración en aplicaciones web. Componente React reutilizable con Shadow DOM para aislamiento completo de estilos. Se integra fácilmente con solo proporcionar una API key.

0High
0Medium
0Low

sebaspp00

react widget chat ai chatbot amb-ia catastro component ui shadow-dom style-isolation

AMB-IA Chat Widget

Widget de chat React reutilizable para integración en aplicaciones web. Componente autocontenido que se integra fácilmente proporcionando solo una API key.

📦 Instalación

npm install amb-ia-chat-widget

o con yarn:

yarn add amb-ia-chat-widget

🎯 Versiones Disponibles

El widget está disponible en dos versiones para máxima compatibilidad:

📦 Versión External (Recomendada para Apps React)

Tamaño: ~50 KB (minificado)
Requiere: React 18+ disponible globalmente o como dependencia
Ideal para: Aplicaciones React existentes, Next.js, Vite
Uso: Instalación via npm + import ESM

🌐 Versión Standalone (Recomendada para Sitios Web)

Tamaño: ~368 KB (minificado, incluye React + ReactDOM + CSS)
Requiere: Nada, completamente autónomo
Shadow DOM: Aislamiento total de estilos (los estilos de tu sitio no afectan al widget)
Ideal para: WordPress, Wix, Shopify, HTML puro, PHP
Uso: Un solo <script> tag desde CDN

❓ ¿Cuál usar?

| Tu Sitio | Versión Recomendada | |----------|--------------------| | App React con npm | ✅ External (ESM) | | Next.js / Remix | ✅ External (ESM) | | WordPress / Wix | ✅ Standalone (UMD) | | HTML puro | ✅ Standalone (UMD) | | Ya tienes React CDN | ⚠️ External (UMD) |

🚀 Uso Rápido

En una aplicación React

import React from 'react';
import ChatWidget from 'amb-ia-chat-widget';
import 'amb-ia-chat-widget/css';

function App() {
  return (
    <div>
      <h1>Mi Aplicación</h1>
      <ChatWidget apiKey="tu-api-key-aqui" />
    </div>
  );
}

export default App;

En HTML vanilla (UMD)

Opción A: Versión Standalone (Sin React - Recomendado)

Más simple - Un solo archivo:

<!DOCTYPE html>
<html>
<head>
  <title>Mi Aplicación</title>
  <!-- Los estilos se inyectan automáticamente en el Shadow DOM - No necesitas cargar CSS -->
</head>
<body>
  <div id="app">
    <h1>Mi Aplicación</h1>
  </div>
  
  <!-- Cargar el widget standalone (React incluido) -->
  <script src="https://cdn.jsdelivr.net/npm/amb-ia-chat-widget@latest/dist/chat-widget-standalone.umd.js"></script>
  
  <script>
    window.addEventListener('DOMContentLoaded', function() {
      ChatWidget.mount({ apiKey: 'tu-api-key-aqui' });
    });
  </script>
</body>
</html>

Características de la versión standalone:

✅ API simplificada: Usa ChatWidget.mount() en lugar de React.createElement()
✅ Contenedor automático: Si no existe #chat-widget-root, se crea automáticamente
✅ React incluido: No necesitas cargar React desde CDN
✅ Shadow DOM: Aislamiento completo de estilos - los CSS de tu sitio no afectan al widget
✅ CSS integrado: Los estilos se inyectan automáticamente, no necesitas <link> tags

Opción B: Versión External (Con React CDN)

Si ya tienes React en tu sitio:

<!DOCTYPE html>
<html>
<head>
  <title>Mi Aplicación</title>
  <!-- Cargar React desde CDN -->
  <script crossorigin src="https://cdn.jsdelivr.net/npm/[email protected]/umd/react.production.min.js"></script>
  <script crossorigin src="https://cdn.jsdelivr.net/npm/[email protected]/umd/react-dom.production.min.js"></script>
  
  <!-- Cargar estilos del widget -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/amb-ia-chat-widget@latest/dist/amb-ia-chat-widget.css">
</head>
<body>
  <div id="app">
    <h1>Mi Aplicación</h1>
  </div>
  
  <!-- Contenedor para el widget -->
  <div id="chat-widget-root"></div>
  
  <!-- Cargar el widget -->
  <script src="https://cdn.jsdelivr.net/npm/amb-ia-chat-widget@latest/dist/chat-widget.umd.js"></script>
  <script>
    window.addEventListener('DOMContentLoaded', function() {
      const ChatWidget = window.ChatWidget.default || window.ChatWidget;
      const container = document.getElementById('chat-widget-root');
      const root = ReactDOM.createRoot(container);
      
      root.render(
        React.createElement(ChatWidget, { 
          apiKey: 'tu-api-key-aqui' 
        })
      );
    });
  </script>
</body>
</html>

📖 API

Props

| Prop | Tipo | Requerido | Descripción | |------|------|-----------|-------------| | apiKey | string | ✅ REQUERIDO | API key para autenticación con el backend AMB-IA. No tiene valor por defecto, debe ser proporcionada siempre. |

[!IMPORTANT] La prop apiKey es obligatoria. El widget lanzará un error si no se proporciona.

Ejemplo completo

import ChatWidget from 'amb-ia-chat-widget';
import 'amb-ia-chat-widget/css';

function MyApp() {
  return (
    <div>
      <ChatWidget apiKey="one-sys-prod-tu-api-key-aqui" />
    </div>
  );
}

🎨 Estilos

El widget incluye sus propios estilos basados en Tailwind CSS. Debes importar el CSS para que se vea correctamente:

Con módulos ES6

import 'amb-ia-chat-widget/css';
// o
import 'amb-ia-chat-widget/styles';

Con UMD

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/amb-ia-chat-widget@latest/dist/amb-ia-chat-widget.css">

🔧 Requisitos

React: ^18.0.0 o ^19.0.0
React DOM: ^18.0.0 o ^19.0.0

Estas son dependencias peer, por lo que debes tenerlas instaladas en tu proyecto.

📝 Características

✅ Shadow DOM (Standalone) - Aislamiento total de estilos, sin conflictos con tu sitio
✅ API Key obligatoria - Seguridad mejorada sin valores por defecto
✅ Dual bundle - Versión standalone (React incluido) y external (React externalizado)
✅ Fácil integración - Solo una línea de código
✅ Componente autocontenido
✅ Soporte para React 18 y 19
✅ Formatos ESM y UMD
✅ Estilos incluidos con Tailwind CSS
✅ Chat en tiempo real con LLM
✅ Interfaz responsive y moderna
✅ Markdown en respuestas (con remark-gfm)
✅ Scroll automático inteligente
✅ TypeScript definitions incluidas

🛠️ Desarrollo

Si quieres contribuir o modificar el widget:

# Clonar el repositorio
git clone <repository-url>

# Instalar dependencias
npm install

# Modo desarrollo
npm run dev

# Build del widget (external + standalone)
npm run build:widget

# Build del widget external (React externalizado)
npm run build:external

# Build del widget standalone (funcionamiento autocontenido, sin React)
npm run build:standalone

# Preview
npm run preview

🤝 Soporte

Para reportar bugs o solicitar características, abre un issue en el repositorio.

📚 Ejemplos

Ver la carpeta examples/ para ejemplos de integración completos.

📄 Licencia de propiedad

Notice: this file is propietary and can not be copied and/or distributed without permission from One System SAS.