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

# @jfuente/widget-angular

Wrapper Angular para `@jfuente/widget-core`. Expone un modulo, un componente y un servicio para integrar el asistente en cualquier aplicacion Angular 15+.

---

## Instalacion

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

**Requiere:** Angular 15 o superior.

---

## Integracion rapida

### 1. Importar el modulo

```typescript
// app.module.ts
import { AsistenteModule } from '@jfuente/widget-angular';

@NgModule({
  imports: [
    BrowserModule,
    AsistenteModule,
    // ...
  ],
})
export class AppModule {}
```

### 2. Agregar el componente al template

```html
<!-- app.component.html -->
<router-outlet></router-outlet>

<tu-asistente
  [apiUrl]="apiUrl"
  [token]="token"
  [contexto]="contexto"
  [acciones]="acciones"
/>
```

### 3. Definir las propiedades en el componente

```typescript
// app.component.ts
import { Component } from '@angular/core';
import type { ContextoWidget, AccionesWidget } from '@jfuente/widget-angular';
import { Router } from '@angular/router';

@Component({ selector: 'app-root', templateUrl: './app.component.html' })
export class AppComponent {
  apiUrl = 'http://localhost:3100';
  token = localStorage.getItem('token') ?? '';

  contexto: ContextoWidget = { pantalla: 'inicio' };
  acciones: AccionesWidget = {};

  constructor(private router: Router) {}
}
```

---

## Componente `<tu-asistente>`

### Inputs

| Input | Tipo | Requerido | Descripcion |
|-------|------|-----------|-------------|
| `apiUrl` | `string` | Si | URL base del backend |
| `token` | `string` | Si | JWT del usuario |
| `contexto` | `ContextoWidget` | No | Pantalla activa y datos |
| `acciones` | `AccionesWidget` | No | Funciones invocables por el asistente |
| `tema` | `TemaWidget` | No | Personalizacion visual |

El componente no tiene template propio — monta el widget en el `<body>` via el core.

---

## Actualizacion de contexto por ruta

El patron recomendado es actualizar el contexto desde cada componente de pagina via `AsistenteService`:

```typescript
// facturas.component.ts
import { Component, OnInit } from '@angular/core';
import { AsistenteService } from '@jfuente/widget-angular';
import { Router } from '@angular/router';

@Component({ selector: 'app-facturas', templateUrl: './facturas.component.html' })
export class FacturasComponent implements OnInit {
  constructor(
    private asistente: AsistenteService,
    private router: Router,
  ) {}

  ngOnInit(): void {
    this.asistente.actualizarContexto({
      pantalla: 'lista-facturas',
      descripcion: 'Lista de facturas electronicas',
      datos: {
        pendientes: this.facturasPendientes.length,
        totalMes: this.totalDelMes,
      },
    });

    this.asistente.actualizarAcciones({
      'crear-factura':     () => this.router.navigate(['/facturas/nueva']),
      'filtrar-pendiente': () => this.aplicarFiltro('pendiente'),
      'exportar-excel':    () => this.exportar(),
    });
  }
}
```

---

## `AsistenteService`

Servicio `providedIn: 'root'` que envuelve la instancia del widget. Se puede inyectar en cualquier componente o servicio.

```typescript
import { AsistenteService } from '@jfuente/widget-angular';
```

### Metodos

| Metodo | Descripcion |
|--------|-------------|
| `init(config: ConfigWidget)` | Inicializa y monta el widget. Llamado automaticamente por `AsistenteComponent` |
| `actualizarContexto(ctx: Partial<ContextoWidget>)` | Actualiza el contexto sin reiniciar el widget |
| `actualizarAcciones(acc: AccionesWidget)` | Registra o reemplaza acciones disponibles |
| `destruir()` | Desmonta el widget y limpia el DOM |

---

## Uso avanzado: solo el servicio (sin componente)

Si prefieres controlar el ciclo de vida manualmente:

```typescript
// app.component.ts
export class AppComponent implements OnInit, OnDestroy {
  constructor(private asistente: AsistenteService, private auth: AuthService) {}

  ngOnInit(): void {
    this.auth.token$.subscribe(token => {
      if (token) {
        this.asistente.init({
          apiUrl: environment.apiIaUrl,
          token,
          contexto: { pantalla: 'inicio' },
        });
      }
    });
  }

  ngOnDestroy(): void {
    this.asistente.destruir();
  }
}
```

---

## Ciclo de vida del componente

| Evento Angular | Comportamiento |
|---------------|----------------|
| `ngOnInit` | Llama `AsistenteService.init()` con la config inicial |
| `ngOnChanges` (contexto) | Llama `actualizarContexto()` |
| `ngOnChanges` (acciones) | Llama `actualizarAcciones()` |
| `ngOnDestroy` | Llama `AsistenteService.destruir()` |