Getting Started

Installazione


title: Installazione description: Installazione e configurazione di @pzeta/vue-attivita — plugin Vue, opzioni baseUrl/repository, integrazione con altre librerie PZeta.

Installazione

npm install @pzeta/vue-attivita

Versione corrente: 1.0.0.

Rinomina pacchetto in v1.0.0: il package è stato rinominato da @pzeta/attivita a @pzeta/vue-attivita per coerenza con le altre librerie PZeta. Aggiorna package.json, gli import e il sub-export /style. La superficie API è rimasta invariata.

Peer dependencies

PacchettoVersione
vue^3.5.0
@pzeta/vue-components^1.4.0
@pzeta/vue-form^2.3.0
@pzeta/vue-i18n^1.0.2

@pzeta/vue-components deve essere già configurato (Toast, ConfirmDialog, Dialog) prima di registrare AttivitaPlugin. @pzeta/vue-form è usato dal form principale AttivitaForm (basato su DynamicFormDialog) e dai dialog CompletaDialog / AnnullaDialog / TipoAttivitaForm. @pzeta/vue-i18n fornisce le traduzioni di vue-form: registra I18nFormPlugin prima di VueFormPlugin.

Se nel tuo progetto hai già configurato @pzeta/vue-form, non devi rifare nulla — @pzeta/vue-attivita riutilizza i componenti registrati globalmente.

Registrazione plugin (default — backend PostgREST)

// main.ts
import { createApp } from 'vue'
import { AttivitaPlugin } from '@pzeta/vue-attivita'
import '@pzeta/vue-attivita/style'
import App from './App.vue'

const app = createApp(App)

app.use(AttivitaPlugin, {
  baseUrl: import.meta.env.VITE_ATTIVITA_API_URL,
  getToken: () => sessionStorage.getItem('jwt'),
  onEvent: (name, payload) => {
    console.log('attivita event:', name, payload)
  },
})

app.mount('#app')
Il sub-export del CSS è @pzeta/vue-attivita/style (non /style.css). Il bundle Vite genera un singolo file CSS che include tutti gli stili Tailwind compilati.

Opzioni plugin

interface AttivitaPluginOptions {
  /** Base URL schema attivita su PostgREST. Obbligatorio se non passi `repository`. */
  baseUrl?: string

  /** Getter token JWT corrente; default `() => null` (no auth). */
  getToken?: () => string | null

  /** Handler eventi cross-app. Default `() => {}` (eventi ignorati). */
  onEvent?: (name: string, payload?: unknown) => void

  /** Override URL base per endpoint Fastify (upload, firma). Default: `baseUrl`. */
  apiBaseUrl?: string

  /** HTTP client custom; sovrascrive `baseUrl` + `getToken` per il client PostgREST. */
  http?: IHttpClient

  /** Repository custom; ha priorità su `http`/`baseUrl`. Vedi sezione "Repository custom". */
  repository?: IAttivitaRepository
}
OpzioneTipoDefaultDescrizione
baseUrlstringRichiesto se non passi http o repository
getToken() => string | null() => nullGetter JWT per Authorization header
onEvent(name, payload?) => void() => {}Handler eventi cross-app (MFE / event bus)
apiBaseUrlstringbaseUrlURL base per endpoint Fastify (upload documento, firma)
httpIHttpClientClient HTTP @pzeta/postgrest custom
repositoryIAttivitaRepositoryRepository custom (test, backend non-PostgREST)
Senza baseUrl/http/repository il plugin lancia un errore al setup. Almeno uno dei tre va fornito. Se passi repository, gli altri due vengono ignorati e nessun client PostgREST viene istanziato.

AttivitaContext (provided)

Il plugin chiama app.provide(ATTIVITA_CONTEXT_KEY, context) rendendo disponibile il context a tutto l'albero dei componenti. Il context contiene:

CampoTipoNote
repositoryIAttivitaRepositoryPunto di accesso unico ai dati
serviceIAttivitaRepositoryAlias deprecato di repository
getToken() => string | nullJWT corrente
onEvent(name, payload?) => voidHandler eventi cross-app
apiBaseUrlstringURL base Fastify
refreshSignalRef<number>v1.0.0 — Signal per auto-refresh delle viste data-aware (vedi sotto)

Auto-refresh viste data-aware (v1.0.0)

refreshSignal è un Ref<number> reattivo che viene incrementato automaticamente:

  • da useAttivita dopo pianifica/completa/annulla/ripristina/elimina/segnaComeFatto/aggiungi-rimuoviAssegnatario
  • da AttivitaForm dopo POST/PATCH (sia handleSave sia handleSegnaComeFatto)

I composables (useAttivita, useAttivitaCalendario, useAttivitaDashboard) e i componenti data-aware (AttivitaTimeline, AttivitaBadge) lo watch-ano e ri-fetchano i propri dati. Risultato: tutte le 6 viste di dominio si auto-aggiornano senza che il consumer debba orchestrare un reload manuale, anche se montate in alberi diversi della UI.

Quando passi un repository custom (mock, GraphQL...), assicurati di non dimenticare di provvedere il campo refreshSignal: ref(0) nel provide manuale (es. test, Storybook). Se usi AttivitaPlugin, viene creato per te.

Repository custom

Per backend non-PostgREST (REST custom, GraphQL, store locale) o test, implementa l'interfaccia di dominio IAttivitaRepository:

import { AttivitaPlugin, type IAttivitaRepository } from '@pzeta/vue-attivita'

class MockAttivitaRepository implements IAttivitaRepository {
  async getAttivita() { return [] }
  async getRiepilogoEntita() { return null }
  // ... resto delle firme — vedi pagina concetti
}

app.use(AttivitaPlugin, {
  repository: new MockAttivitaRepository(),
  onEvent: (name, payload) => eventBus.emit(name, payload),
})

Quando repository è fornito ha priorità su baseUrl/http. L'implementazione canonica PostgrestAttivitaRepository è esportata pubblicamente per chi vuole estenderla/avvolgerla:

import {
  AttivitaPlugin,
  PostgrestAttivitaRepository,
  createPostgrestRepository,
  createFetchClient
} from '@pzeta/vue-attivita'

const http = createFetchClient('/attivita', () => sessionStorage.getItem('jwt'))
const repository = new PostgrestAttivitaRepository(http)
// oppure: const repository = createPostgrestRepository(http)

app.use(AttivitaPlugin, { repository })

Integrazione con @pzeta/vue-kanban

@pzeta/vue-kanban può usare @pzeta/vue-attivita per il dialog attività delle schede. Il wrapper DefaultActivityDialog (sub-export /dialogs) richiede comunque che il consumer abbia inizializzato AttivitaPlugin (oppure abbia fornito un provide(ATTIVITA_CONTEXT_KEY, ...) manuale a livello di app).

Vedi vue-kanban — Default dialog per il setup combinato.

Import individuali

// Plugin & contesto
import { AttivitaPlugin, ATTIVITA_CONTEXT_KEY } from '@pzeta/vue-attivita'
import type { AttivitaPluginOptions, AttivitaContext } from '@pzeta/vue-attivita'

// Wrapper data-aware
import {
  AttivitaListaEntita,
  AttivitaBadge,
  AttivitaConsolidata,
  AttivitaCalendario,
  AttivitaForm,
  AttivitaTimeline,
  RicorrenzaPanel,
  PartecipantiPanel,
  DocumentoPanel,
  FirmaPanel,
  CompletaDialog,
  AnnullaDialog,
} from '@pzeta/vue-attivita'

// View headless (no plugin richiesto)
import {
  AttivitaListaEntitaView,
  AttivitaBadgeView,
  AttivitaConsolidataView,
  AttivitaCalendarioView,
  AttivitaTimelineView,
  RicorrenzaPanelView,
  PartecipantiPanelView,
  DocumentoPanelView,
  FirmaPanelView,
} from '@pzeta/vue-attivita'

// Composables
import {
  useAttivitaContext,
  useAttivita,
  useAttivitaForm,
  useAttivitaDashboard,
  useAttivitaCalendario,
  useTipiAttivita,
  useConcatenamento,
  useRicorrenza,
  useDocumento,
  useRichiestafirma,
} from '@pzeta/vue-attivita'

// Repository pattern
import {
  type IAttivitaRepository,
  PostgrestAttivitaRepository,
  createPostgrestRepository,
  createFetchClient,
} from '@pzeta/vue-attivita'

// Tipi
import type {
  AttivitaView,
  AttivitaFilters,
  AttivitaRiepilogo,
  AttivitaUtente,
  ContatoreAttivita,
  TipoAttivita,
  Ricorrenza,
  AttivitaAssegnatario,
  AttivitaPartecipante,
  PianificaAttivitaRequest,
  PianificaAttivitaResponse,
  CompletaAttivitaRequest,
  CompletaAttivitaResponse,
  AnnullaAttivitaRequest,
  AnnullaAttivitaResponse,
} from '@pzeta/vue-attivita'

Variabili d'ambiente raccomandate

VariabileEsempioDescrizione
VITE_ATTIVITA_API_URL/api/attivitaURL base PostgREST schema attivita
VITE_API_BASE_URL/apiURL base Fastify per upload/firma (passato come apiBaseUrl)

In dev locale puoi usare un proxy Vite per evitare CORS verso il backend PostgREST.