@numaris-microfront/widget-dev-harness

Un "Shell" de mentira para desarrollar un widget de la plataforma Numaris sin tener el Shell real corriendo al lado y sin clonar ningún repo. Si ya tenés tu widget escrito y querés probarlo — con una sesión de mentira, el tema de marca aplicado, y una forma de disparar a mano los eventos que otro widget te mandaría — este es el paquete que instalás.

Por qué existe

Podés hacer andar tu widget con un main.tsx casero: montarlo a mano en un div, pasarle una sesión inventada, listo. Eso alcanza para ver que renderiza. Lo que NO resuelve es la parte más difícil de probar un widget de esta plataforma: cómo reacciona a un evento que otro widget le mandaría por el Event Bus. Sin ese otro widget corriendo al lado, no hay forma de ver qué hace el tuyo cuando le llega, por ejemplo, una selección hecha en otra pantalla.

Este paquete resuelve eso con un panel donde emitís cualquier evento a mano y ves el historial de lo que pasó.

Instalación

npm install --save-dev @numaris-microfront/widget-dev-harness

Es una herramienta de desarrollo — --save-dev a propósito. Nunca se importa desde el componente que tu build de producción expone; solo desde tu entry point de desarrollo (ver más abajo).

Uso

Reemplazá tu entry point de desarrollo (el main.tsx/dev-main.tsx que monta tu widget fuera de cualquier host) por:

import { mountDevHarness } from '@numaris-microfront/widget-dev-harness';

import manifest from '../manifest.json';
import { mount } from './mount.js'; // el MISMO mount que tu build expone al host

mountDevHarness(mount, { manifest });

Le pasás tu mount, no un componente. Es el mismo contrato que usa el host real (WidgetMount de @numaris-microfront/contracts: recibe un HTMLElement y las props de montaje, y devuelve su desmontaje), y eso tiene dos consecuencias buenas:

• Sirva cual sea tu framework. El harness está escrito en React, pero lo que cruza la frontera es un nodo del DOM: un widget de Vue, de Angular o de TypeScript puro se monta igual.
• Probás lo mismo que va a correr en producción. Si tu widget anda acá y falla en el host, el problema es del host y no de una segunda forma de montarlo que solo existía en desarrollo.

Nunca importes este paquete desde mount.tsx: es una herramienta de desarrollo y no forma parte de lo que un host real monta.

Si venís de 0.2.x

Antes esta función recibía tu componente de React. Lo sigue aceptando —avisando por consola— para no romper los proyectos ya generados, pero es un puente con fecha de vencimiento. La migración es cambiar una línea:

-import Widget from './widget.js';
-mountDevHarness(Widget, { manifest });
+import { mount } from './mount.js';
+mountDevHarness(mount, { manifest });

Lo que obtenés al levantar tu dev server

• Tu widget renderizado con una sesión de mentira (organizationId, userLabel, getToken() configurables) y el tema de marca de Numaris aplicado.
• Una barra superior con la identidad de esa sesión y, si pasaste manifest, su id/versión.
• Un panel Event Bus inspector al costado: un formulario para escribir un nombre de evento y un payload en JSON y emitirlo, más un historial en vivo de todo lo que pasa por el bus —incluidos los eventos que tu PROPIO widget emite— para confirmar que tu widget provee y consume lo que tu manifiesto dice.

Sesión personalizada

mountDevHarness(mount, {
  session: {
    organizationId: 'mi-organizacion-de-prueba',
    userLabel: 'Equipo Externo',
    // Un token real de Cognito, si ya estás integrando contra datos reales
    // (ver @numaris-microfront/graphql-client para cómo conseguirlo):
    getToken: () => Promise.resolve(miTokenReal),
  },
});

getToken es una función — nunca guardes un token capturado una sola vez. Los tokens de Cognito expiran, y un getToken que siempre devuelve el mismo string viejo produce un widget que anda al principio y empieza a fallar con 401 después de una hora, sin que cambies nada de tu código.

El inspector de eventos no es el catálogo oficial

La lista de nombres de evento que sugiere el autocompletar del panel es solo eso — una sugerencia. El contrato real de eventos de la plataforma vive en @numaris-microfront/contracts (NumarisEventMap, documentado en su README). El panel acepta cualquier nombre que escribas, esté o no en la lista de sugerencias — así podés probar tanto los eventos ya documentados como uno que estés por proponer.

Qué NO hace (todavía)

• No consigue un token real de Cognito por vos. Le pasás uno si lo tenés (ver la sección de sesión personalizada); conseguirlo hoy es un proceso manual — pedile a tu contacto en Numaris las credenciales de un entorno de prueba.
• No imita el layout de varias zonas del Shell real. Monta tu widget solo, con el panel de diagnóstico al lado. Si necesitás ver cómo interactúan DOS widgets tuyos a la vez, todavía no hay una forma de montarlos juntos con este paquete — usá el inspector para simular lo que el otro widget emitiría.