@jfuente/widget-react
v1.0.0
Published
Wrapper React para el widget de IA embebible de TuCarpeta
Downloads
97
Readme
@jfuente/widget-react
Wrapper React para @jfuente/widget-core. Expone un componente de React que monta y gestiona el ciclo de vida del widget automaticamente.
Instalacion
npm install @jfuente/widget-core @jfuente/widget-reactRequiere: React 17 o superior.
Componente <TuAsistenteWidget />
import { TuAsistenteWidget } from '@jfuente/widget-react';Props
| Prop | Tipo | Requerido | Descripcion |
|------|------|-----------|-------------|
| apiUrl | string | Si | URL base del backend (ej: http://localhost:3100) |
| token | string | Si | JWT del usuario autenticado |
| contexto | ContextoWidget | No | Pantalla activa y datos del contexto |
| acciones | AccionesWidget | No | Funciones que el asistente puede ejecutar |
| tema | TemaWidget | No | Personalizacion de colores y fuente |
El componente no renderiza nada visible — monta el widget directamente en el <body> via el core.
Uso basico
import { TuAsistenteWidget } from '@jfuente/widget-react';
function App() {
const token = useAuth().token;
return (
<>
<MiApp />
<TuAsistenteWidget
apiUrl="http://localhost:3100"
token={token}
/>
</>
);
}Con contexto dinamico por ruta
El patron recomendado es definir el contexto en cada pagina/vista y pasarlo al componente desde el layout principal.
// Layout.tsx
import { TuAsistenteWidget } from '@jfuente/widget-react';
import { useWidgetContexto } from './hooks/useWidgetContexto';
export function Layout({ children }) {
const { contexto, acciones } = useWidgetContexto();
return (
<>
<main>{children}</main>
<TuAsistenteWidget
apiUrl={import.meta.env.VITE_API_IA_URL}
token={useAuth().token}
contexto={contexto}
acciones={acciones}
/>
</>
);
}// pages/Facturas.tsx
import { useWidgetContexto } from '../hooks/useWidgetContexto';
export function Facturas() {
const { setContexto, setAcciones } = useWidgetContexto();
const { data: facturas } = useFacturas();
const navigate = useNavigate();
useEffect(() => {
setContexto({
pantalla: 'lista-facturas',
descripcion: 'Lista de facturas electronicas',
datos: {
total: facturas?.length ?? 0,
pendientes: facturas?.filter(f => f.estado === 'pendiente').length ?? 0,
},
});
setAcciones({
'crear-factura': () => navigate('/facturas/nueva'),
'filtrar-pendiente': () => setFiltro('pendiente'),
});
}, [facturas]);
return <FacturasView />;
}Hook: useWidgetContexto
Ejemplo de implementacion de un contexto React para coordinar el estado del widget desde cualquier pagina:
// hooks/useWidgetContexto.ts
import { createContext, useContext, useState } from 'react';
import type { ContextoWidget, AccionesWidget } from '@jfuente/widget-react';
const WidgetCtx = createContext(null);
export function WidgetProvider({ children }) {
const [contexto, setContexto] = useState<ContextoWidget>({ pantalla: 'inicio' });
const [acciones, setAcciones] = useState<AccionesWidget>({});
return (
<WidgetCtx.Provider value={{ contexto, acciones, setContexto, setAcciones }}>
{children}
</WidgetCtx.Provider>
);
}
export const useWidgetContexto = () => useContext(WidgetCtx);Ciclo de vida
| Evento | Comportamiento del componente |
|--------|-------------------------------|
| Montaje (useEffect[]) | Crea la instancia de AsistenteWidget y llama montar() |
| Cambio en contexto | Llama actualizarContexto() — no reinicia el widget ni el historial |
| Cambio en acciones | Llama actualizarAcciones() — las nuevas acciones se registran encima |
| Desmontaje | Llama desmontar() — elimina el widget y los estilos del DOM |