Reference · Bus de eventos

El widget expone dos canales públicos sobre window:

1. CustomEvent que emite — el host se suscribe.
2. CustomEvent que escucha — el host emite.

No hay postMessage público. Los mensajes neuroon:setStyles / neuroon:setTheme / neuroon-preview-ready que ves en widget/src/index-preact.tsx:114-161 son internos de la preview admin del plugin de WordPress y no forman parte del contrato para integradores.

Resumen

Tipo	Dirección	Nombre	Payload
CustomEvent	widget → host	neuroon-theme-change	{ theme: 'light' | 'dark', containerId?: string }
CustomEvent	host → widget	neuroon:cart-update	(sin detail)

neuroon-theme-change (widget → host)

Disparado cuando el tema activo del widget cambia, sea porque el sistema cambió en theme="auto" o porque el host llamó widget.setTheme(...).

• Disparo automático: widget/src/index-preact.tsx:311 (cambio de prefers-color-scheme).
• Disparo programático: widget/src/context/WidgetContext.tsx:846 (acción setTheme).

type NeuroonThemeChangeDetail = {
  theme: 'light' | 'dark'
  containerId?: string  // sólo presente en cambios automáticos por sistema
}

window.addEventListener('neuroon-theme-change', (e) => {
  const { theme, containerId } = (e as CustomEvent<NeuroonThemeChangeDetail>).detail
  document.documentElement.dataset.theme = theme
  // Si tienes múltiples instancias del widget, filtra por containerId.
})

neuroon:cart-update (host → widget)

El host lo emite tras cualquier mutación del carrito fuera del widget (mini-cart, página de carrito, otro plugin). El widget escucha en widget/src/context/CartContext.tsx:165-191 y, al recibirlo:

1. Cancela si hay operaciones del propio widget en vuelo (no pisa el estado optimista).
2. Aplica debounce de 300 ms (algunos hosts emiten varios eventos seguidos: added_to_cart, wc_fragments_refreshed).
3. Llama a config.cart.onGetCart() y actualiza su estado.

// El listener ignora event.detail. Dispara sin payload.
window.dispatchEvent(new CustomEvent('neuroon:cart-update'))

El nombre del evento es configurable vía cart.externalUpdateEvent (default 'neuroon:cart-update').

Ejemplo: WordPress / WooCommerce

jQuery(document.body).on(
  'added_to_cart wc_fragments_refreshed removed_from_cart',
  () => window.dispatchEvent(new CustomEvent('neuroon:cart-update'))
)

El plugin oficial de WordPress ya wirea este puente automáticamente en su loader inline; ver Plugins → WordPress → Cart bridge.

Lo que el widget no emite (pero podrías esperar)

Los siguientes son callbacks de configuración, no CustomEvents. Se pasan en NeuroonWidgetConfig.callbacks:

Callback	Trigger
onSearch(query, results)	tras cada búsqueda exitosa
onResultClick(product)	click en un resultado del grid
onFilterChange(filters)	el usuario aplica/quita filtros
onError(error)	error en cualquier fase de la búsqueda

Ver Widget → Configuración para el contrato completo.

Próximas lecturas

• Widget → Eventos — versión narrativa con ejemplos.
• Widget → Integración de carrito.
• Widget → Theming.