Composables

Data & Events

useWidgetData per dati reattivi e useWidgetEvent per emissione eventi tramite event bus.

Panoramica

I due composables formano il sistema di comunicazione tra widget e applicazione consumer:

useWidgetEvent — emette eventi da un widget (lato widget).
useWidgetData — reagisce agli eventi emessi e aggiorna in-place i props dei widget (lato consumer).

L'event bus interno e disaccoppiato e supporta sia fire-and-forget (emit) sia handler con risposta (emitAsync).

useWidgetEvent

import { useWidgetEvent } from '@pzeta/vue-widget'

const props = defineProps<{ widgetId: string; widgetType: string }>()
const { emit, emitAsync } = useWidgetEvent(props.widgetId, props.widgetType)

// Fire-and-forget
emit('periodChange', { period: '30d' })

// Con risposta dall'handler
const response = await emitAsync('alertDismiss', { alertId: 42 })
if (response?.feedback?.dismiss) {
  alerts.value = alerts.value.filter(a => a.id !== 42)
}

Tipi

Tipo	Descrizione
`WidgetEventName`	Union di nomi evento (oltre 30 valori: `periodChange`, `filterChange`, `itemClick`, `notificationRead`, `alertDismiss`, ecc.)
`WidgetEventPayload<T>`	`{ widgetId, widgetType, data: T }`
`EventFeedback`	Risposta handler con `type?`, `message?`, `dismiss?`, `markRead?`
`EventHandlerResponse`	`{ feedback?: EventFeedback, [key: string]: unknown }`

Gli eventi vengono prefissati automaticamente con widget: sul bus interno.

Crea una DashboardConfig reattiva che si aggiorna in-place in risposta agli eventi widget. Gli aggiornamenti modificano singole proprieta invece di sostituire interi oggetti, evitando re-render completi e reset dello scroll.

import { useWidgetData } from '@pzeta/vue-widget'

const { config, updateWidgetProps, addEventHandler, removeEventHandler } = useWidgetData(initialConfig, {
  eventHandlers: {
    periodChange: async (payload, currentProps) => {
      const newData = await fetchData(payload.data.period)
      return { ...currentProps, data: newData }
    },
    alertDismiss: (payload, currentProps) => {
      const alerts = (currentProps.alerts as Alert[]).filter(a => a.id !== payload.data.alertId)
      return { alerts }
    },
  },
  onPropsUpdate: (widgetId, props) => {
    console.log(`Widget ${widgetId} aggiornato`, props)
  },
})

<template>
  <PzetaDashboard :config="config" />
</template>

Opzioni — `UseWidgetDataOptions`

Opzione	Tipo	Descrizione
`eventHandlers`	`EventHandlerMap`	Mappa eventName → handler
`onPropsUpdate`	`(widgetId, newProps) => void`	Callback dopo ogni aggiornamento

Tipo handler

type WidgetEventHandler = (
  payload: WidgetEventPayload,
  currentProps: Record<string, unknown>
) => Record<string, unknown> | Promise<Record<string, unknown>> | undefined

L'handler riceve il payload e i props correnti; ritorna i nuovi props (parziali) o undefined per non modificare nulla.

API ritornata

Proprieta	Tipo	Descrizione
`config`	`DashboardConfig` (reactive)	Config reattiva da passare a `<PzetaDashboard>`
`isUpdating`	`ComputedRef<boolean>`	`true` durante esecuzione handler
`lastEvent`	`ComputedRef<WidgetEventPayload \| null>`	Ultimo evento ricevuto
`updateWidgetProps`	`(widgetId, newProps) => boolean`	Aggiorna manualmente props di un widget
`getWidgetProps`	`(widgetId) => Record \| undefined`	Legge props correnti
`addEventHandler`	`(eventType, handler) => void`	Aggiunge handler runtime
`removeEventHandler`	`(eventType) => void`	Rimuove handler

I listener vengono registrati al mount e puliti al unmount automaticamente.

Chart, Icon e i18n

useChartDefaults per Chart.js, useIcon per il registry icone e useI18n per localizzazione.

Formatting

useNumberFormat, useCurrency, useCounterAnimation e useTrend per formattazione e animazioni.