npm package: @jfuente/widget-react
Description: Wrapper React para el widget de IA embebible de TuCarpeta
Latest version: 1.0.0

# @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

```bash
npm install @jfuente/widget-core @jfuente/widget-react
```

**Requiere:** React 17 o superior.

---

## Componente `<TuAsistenteWidget />`

```tsx
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

```tsx
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.

```tsx
// 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}
      />
    </>
  );
}
```

```tsx
// 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:

```typescript
// 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 |