@italyade/map

Mappe SVG delle Direzioni Provinciali dell'Agenzia delle Entrate: vista regionale con evidenziazione della provincia di competenza e vista di dettaglio con suddivisione comunale per le quattro province multi-DP (Torino, Milano, Roma, Napoli). React 19 + TypeScript.

• Zero <canvas>: SVG puro proiettato con d3-geo (nitido, stampabile, accessibile).
• Loader dei dati intercambiabili: fetch (default) o confini impacchettati (offline).
• Feature opt-in: ufficio territoriale con link a Google Maps, attivabile a piacere.
• Dati rigenerabili e automatizzati al bump di versione.
• Accessibilità: ruoli ARIA, navigazione da tastiera, prefers-reduced-motion.

Installazione

npm install @italyade/map

Peer dependencies

| Pacchetto | Versione | Obbligatorio | | --------------------- | ---------- | -------------------------- | | react / react-dom | >=18 <20 | sì | | react-bootstrap | >=2.10 | sì (pulsanti) | | bootstrap | >=5.3 | opzionale (stile pulsanti) | | bootstrap-icons | >=1.11 | opzionale (icone) |

d3-geo è una dipendenza diretta della libreria (deduplicata con la tua copia se presente).

Avvio rapido (loader fetch, raccomandato)

1. Genera i confini nella cartella statica della tua app (vedi Aggiornamento dati), così da servirli su /confini/regione-<N>.json, /confini/comuni-<provIstat>.json, ecc.
2. Usa il componente:

import { MappaUfficioAdE } from '@italyade/map';
import '@italyade/map/styles.css';

export function Esempio() {
  return (
    <MappaUfficioAdE
      codDirezioneProvinciale="T7F"
      codDirezioneRegionale="901"
      descrizioneUfficio="T7F - DIREZIONE PROVINCIALE II DI TORINO"
    />
  );
}

Il widget parte chiuso con il pulsante "Visualizza mappa"; aperto mostra la regione e, per le province multi-DP, la chip cliccabile che apre il dettaglio (con pulsante "Regione" per tornare indietro).

Variante offline (confini impacchettati)

Nessun file da servire: i confini viaggiano nel pacchetto e si caricano in lazy.

import { MappaUfficioAdE } from '@italyade/map';
import { caricatoreBundleDefault } from '@italyade/map/dati';
import '@italyade/map/styles.css';

<MappaUfficioAdE {...props} caricatori={caricatoreBundleDefault} />;

baseUrl personalizzato (fetch)

import { creaCaricatoreConfiniFetch } from '@italyade/map';

const caricatori = creaCaricatoreConfiniFetch({ baseUrl: '/assets/confini' });
<MappaUfficioAdE {...props} caricatori={caricatori} />;

Componenti

MappaUfficioAdE (orchestratore all-in-one)

| Prop | Tipo | Default | Note | | ---------------------------- | -------------------- | -------------------- | ------------------------------------------------- | | codDirezioneProvinciale | string? | — | Codice DP AdE (es. T7F). | | codDirezioneRegionale | string? | — | Codice DR AdE. | | descrizioneUfficio | string? | — | Descrizione (abilita il fallback di risoluzione). | | caricatori | SetCaricatori | fetch /confini | Set di loader dei confini. | | apertaDiDefault | boolean | false | Se true, la mappa è già visibile. | | etichettaVisualizza | string | 'Visualizza mappa' | Testo del pulsante di apertura. | | larghezza / altezza | number | 440 / 380 | Dimensioni del viewBox SVG. | | codUfficioTerritoriale | string? | — | Abilita (con il flag sotto) il blocco ufficio. | | mostraUfficioTerritoriale | boolean | false | Mostra il link all'ufficio territoriale. | | risolviUfficioTerritoriale | RisolutoreUfficio? | dati impacchettati | Override (es. back-end). |

MappaUfficioCompetente / MappaDirezioneProvinciale

Le due viste sono usabili anche singolarmente (vista regionale e dettaglio DP), con i rispettivi loader iniettabili. Vedi i tipi esportati MappaUfficioCompetenteProps e MappaDirezioneProvincialeProps.

LinkUfficioTerritoriale (feature opt-in, standalone)

import { LinkUfficioTerritoriale } from '@italyade/map';

// Dati impacchettati (caricati in lazy):
<LinkUfficioTerritoriale codUfficioTerritoriale="T7F" />

// Oppure con risolutore dal tuo back-end (i 408 uffici NON entrano nel bundle):
<LinkUfficioTerritoriale codUfficioTerritoriale="T7F" risolviUfficio={mioResolver} />

Aggiornamento dati (rigenerabile + automatizzato)

Tutti i dati derivati (confini regionali/comunali, anagrafica province, anagrafica uffici, registro bundle) sono rigenerabili dalla CLI inclusa, a partire dalle sorgenti in dati-sorgente/ (vedi dati-sorgente/LEGGIMI.md).

# Manuale:
npm run build:dati

# Automatico: parte al bump di versione (hook "version"):
npm version patch   # rigenera i dati, formatta, include tutto nel commit di versione

Sicurezza: ogni sorgente è facoltativa. Se manca, lo step viene saltato e il dato esistente (baseline deployato) resta intatto — la rigenerazione non azzera mai i dati.

Pubblicazione

npm run validate     # type-check + lint + format + test
npm run build        # dist/ (ESM + CJS + .d.ts) e dist/styles.css
npm publish          # pubblico (publishConfig.access = "public")

Per registry privato (Nexus/Artifactory) o GitHub Packages, configura .npmrc e publishConfig.registry come descritto nella guida alla distribuzione.

Accessibilità

Le mappe espongono role="img" con aria-label descrittiva; la chip di apertura del dettaglio è raggiungibile da tastiera (Enter/Spazio); lo scheletro di caricamento rispetta prefers-reduced-motion.

Licenza e attribuzione dati

Codice: MIT. I confini provengono da ISTAT — elaborazione openpolis (CC BY 4.0): l'attribuzione è già mostrata nelle didascalie delle mappe e va mantenuta.