@massimo-cassandro/minimo 1.41.5 → 1.41.7

package/src/web-components/json-table/readme.md

@@ -1,730 +1,6 @@
 # `<json-table>` – datatable da JSON
 
-**json-table** costruisce una tabella HTML da un array di dati JSON (inline o caricato via fetch), a partire da una definizione delle colonne (`cols`) e da un insieme di tipi di dato predefiniti ed estendibili, con ordinamento, ricerca e paginazione (lato client oppure, con `serverSide: true`, delegati al server). È un web component light DOM senza dipendenze esterne: può quindi essere stilizzato direttamente dal CSS del progetto in cui è utilizzato.
+**json-table** costruisce una tabella HTML da un array di dati JSON (inline o caricato via fetch), a partire da una definizione delle colonne (`cols`) e da un insieme di tipi di dato predefiniti ed estendibili, con ordinamento, ricerca e paginazione (lato client oppure, con `serverSide: true`, delegati al server). È un web component light DOM senza dipendenze esterne: può quindi essere personalizzato direttamente dal CSS del progetto in cui è utilizzato.
 
-## Installazione
-
-È sufficiente importare il file del componente (registra il custom element):
-
-```javascript
-// solo registrazione del tag
-import '@massimo-cassandro/minimo/json-table';
-
-// oppure, se necessario eseguire metodi della classe (es. `setDefaults`):
-import { JsonTable } from '@massimo-cassandro/minimo/json-table';
-```
-
-Il CSS (`json-table-component.module.css`) è importato dal componente stesso; le custom
-properties `--jt-*` sono definite in `json-table.minimo.tokens.mjs` e compilate in
-`custom-properties.css` da `build-tokens`. Le icone di default (booleani, ordinamento e
-paginazione) sono SVG di minimo importati con il suffisso `?inline` (gestito dalla configurazione
-webpack dello starter-kit).
-
-### Tipi per gli script consumer
-
-Il file `types/global.d.ts` di minimo dichiara il tipo globale `JsonTable` e registra il tag `json-table` in `HTMLElementTagNameMap`: aggiungendolo all'`include` del proprio `jsconfig.json`/`tsconfig.json` (`"node_modules/@massimo-cassandro/minimo/types/global.d.ts"`) si ottiene il completamento dei metodi senza cast né import di tipo:
-
-```javascript
-const el = document.querySelector('json-table'); // → JsonTable
-el.init({ ... });
-
-/** @type {JsonTable} */
-const other = document.createElement('json-table');
-```
-
-## Utilizzo da markup
-
-```html
-<json-table
-  jsonurl="/api/rows.json"
-  caption="Utenti"
-  perpage="10"
-  cols='[
-    { "key": "id", "dataType": "id" },
-    { "key": "name", "title": "Nome", "render": "<a href=\"/users/[[id]]\">[[name]]</a>" },
-    { "key": "amount", "title": "Importo", "dataType": "euro", "tfootRender": "@sum" },
-    { "key": "active", "title": "Attivo", "dataType": "bool" }
-  ]'
-  tfoot="true"
-  serverSide="true"
-></json-table>
-
-<!-- dati inline (JSON serializzato) al posto di jsonurl -->
-<json-table
-  data='[{"name":"Mario","city":"Roma"}, ...]'
-  cols='[{ "key": "name", "title": "Nome" }, { "key": "city", "title": "Città" }]'
-  search="false"
-></json-table>
-```
-
-I nomi degli attributi sono case-insensitive (`jsonurl` e `jsonUrl` sono equivalenti).
-Gli attributi booleani accettano i formati HTML idiomatici: `search` (presente senza valore),
-`search="true"`, `search="1"` → true; `search="false"`, `search="0"` → false. Gli attributi
-numerici (`perpage`, `paginationdelta`, `searchdebounce`) vengono convertiti in numero.
-I valori che iniziano con `[` o `{` vengono interpretati come JSON (un JSON malformato viene
-segnalato in console e ignorato).
-
-Da attributo non è possibile passare funzioni: per il rendering delle celle è disponibile la
-sintassi mustache-like `[[key]]` (vedi [`render`](#render)), per il footer gli aggregati
-predefiniti (`"@sum"`, ...).
-
-## Utilizzo da script
-
-```javascript
-const el = document.querySelector('json-table');
-// oppure: const el = document.createElement('json-table');
-
-el.init({
-  jsonUrl: '/api/rows.json',
-  caption: 'Utenti',
-  cols: [
-    { key: 'id', dataType: 'id' },
-    { key: 'name', title: 'Nome', render: row => `<a href="/users/${row.id}">${row.name}</a>` },
-    { key: 'amount', title: 'Importo', dataType: 'euro', tfootRender: '@sum' },
-    { key: 'active', title: 'Attivo', dataType: 'bool' }
-  ],
-  tfoot: true
-});
-
-// dati inline al posto di jsonUrl (se presenti entrambi, `data` prevale)
-el.init({
-  data: [{ name: 'Mario', city: 'Roma' }, ...],
-  cols: [...]
-});
-
-// se appena creato, appendere dopo init():
-document.body.appendChild(el);
-```
-
-### Con `domBuilder`
-
-```javascript
-domBuilder([
-  {
-    tag: 'json-table',
-    attrs: { caption: 'Utenti' },
-    callback: el => el.init({ jsonUrl: '/api/rows.json', cols: [...] })
-  }
-], container);
-```
-
-## Utilizzo misto – attributi HTML + script
-
-I parametri non inclusi in `init()` vengono letti dall'attributo HTML corrispondente:
-
-```html
-<json-table caption="Utenti" search="false" cols='[...]'></json-table>
-```
-
-```javascript
-el.init({ jsonUrl: '/api/rows.json' }); // jsonUrl da script, caption, search e cols da attributo
-```
-
-**Ordine di precedenza:** `init()` > attributo HTML > `JsonTable.setDefaults()` > default interno.
-
-Per ignorare esplicitamente un attributo e utilizzare il valore di default, utilizzare `null` nel config:
-
-```javascript
-el.init({ jsonUrl: '/api/rows.json', search: null }); // search == default (true)
-```
-
-I parametri oggetto `classes`, `labels`, `dataTypes` e `serverParams` vengono **uniti** ai default
-(merge a un livello), quindi ogni sorgente deve indicare solo le chiavi da sovrascrivere:
-
-```javascript
-el.init({ classes: { table: 'table' } }); // le altre classi restano quelle di default
-```
-
-## Default di progetto – `JsonTable.setDefaults()`
-
-Imposta valori validi per tutte le istanze create successivamente, evitando di ripetere gli
-stessi parametri. Da invocare una sola volta, in uno script condiviso eseguito prima degli altri.
-I valori vengono uniti a quelli impostati in chiamate precedenti.
-
-```javascript
-import { JsonTable } from '.../json-table-component.js';
-
-JsonTable.setDefaults({
-  perPage: 50,
-  classes: { searchInput: 'form-control', table: 'table' },
-  labels: { searchPlaceholder: 'Cerca…', noRows: 'Nessun elemento' },
-  infoText: (start, end, totRec, filteredRec) => `${filteredRec} di ${totRec} record`
-});
-
-JsonTable.getDefaults();   // default interni + default di progetto
-JsonTable.resetDefaults(); // azzera i default di progetto
-```
-
-## API dell'istanza
-
-| Metodo | Descrizione |
-|---|---|
-| `init(config)` | Avvia il componente (prima o dopo l'inserimento nel DOM) |
-| `reload(overrides)` | Ricarica i dati e ricostruisce la struttura, con eventuali parametri sovrascritti (`Promise`); ricerca, ordinamento e pagina vengono azzerati |
-| `destroy()` | Svuota il componente; `init()` può essere richiamato in seguito |
-| `goToPage(page)` | Mostra la pagina indicata (limitata all'intervallo disponibile) |
-| `setSort(key, dir)` | Ordina per la colonna `key` (`'asc'`, `'desc'`, oppure `null` per rimuovere l'ordinamento) e torna alla prima pagina |
-| `setSearch(term)` | Filtra le righe con il termine indicato (stringa vuota = nessun filtro) e torna alla prima pagina; l'input di ricerca viene aggiornato |
-
-In modalità server-side `goToPage`, `setSort` e `setSearch` generano una nuova richiesta.
-
-Proprietà disponibili dopo il caricamento:
-
-| Proprietà | Descrizione |
-|---|---|
-| `params` | parametri risolti |
-| `data` | righe grezze (array di oggetti; in modalità server-side solo quelle della pagina corrente) |
-| `cols` | colonne dopo il parsing (solo quelle visibili, con classi e tipo di dato risolti) |
-| `dataTypes` | mappa dei tipi di dato (predefiniti + personalizzati) |
-| `state` | stato del rendering: `totRec`, `filteredRec`, `rows`, `filtered`, `pageRows`, `searchTerm`, `sort` (`{ key, dir }` o `null`), `page`, `totPages` |
-| `elements` | elementi generati: `wrapper`, `infoOuter`, `info`, `resultInfo`, `searchInput`, `tableWrapper`, `table`, `thead`, `tbody`, `tfoot`, `tableFooter`, `caption`, `pagination` |
-
-```javascript
-await el.reload({ jsonUrl: '/api/rows.json?anno=2025' });
-await el.reload({ data: [...] });
-el.setSort('name', 'desc');
-el.goToPage(3);
-```
-
-## Eventi
-
-Entrambi vengono emessi sull'elemento con `bubbles: true`; `event.detail.jsonTable` è l'istanza.
-
-| Evento | Quando | `event.detail` |
-|---|---|---|
-| `jt:ready` | al termine della costruzione e del primo rendering (nel microtask successivo, quindi un listener registrato subito dopo `init()` lo intercetta comunque) | `{ jsonTable }` |
-| `jt:update` | dopo ogni cambio pagina, ordinamento o ricerca (anche via API) | `{ jsonTable, reason }` con `reason` = `'page'`, `'sort'` o `'search'` |
-
-```javascript
-el.addEventListener('jt:ready', e => console.log(e.detail.jsonTable.data));
-el.addEventListener('jt:update', e => console.log(e.detail.reason, e.detail.jsonTable.state.page));
-el.init({ jsonUrl: '/api/rows.json', cols: [...] });
-```
-
-## Parametri
-
-Tutti i parametri sono impostabili sia da attributo HTML che come oggetto in `init({...})`. I valori di tipo funzione solo da `init()`.
-
-| Parametro | Tipo / default | Descrizione |
-|---|---|---|
-| `debug` | boolean (`false`) | Log in console di parametri, colonne, dati, stato ed elementi generati |
-| `jsonUrl` | string (`null`) | URL del JSON da caricare. Ignorato se `data` è presente |
-| `jqDatatableMode` | boolean (`false`) | Se `true` imposta come default i valori compatibili con il formato server-side di jQuery DataTables: `jsonDataField: 'data'`, `totRecField: 'recordsTotal'`, `filteredRecField: 'recordsFiltered'`, `serverSide: true` e i `serverParams` indicati in "Modalità jQuery DataTables". Ogni valore resta sovrascrivibile |
-| `jsonDataField` | string o null (`'data'`) | Chiave del JSON che contiene l'array delle righe (es. `'data'` per `{ data: [...] }`); `null` o `''` = la root del JSON è l'array stesso |
-| `totRecField` | string (`'totRec'`) | Chiave del JSON con il totale dei record (numerico); se assente o non numerico il totale è la lunghezza dell'array |
-| `filteredRecField` | string (`'filteredRec'`) | Solo server-side: chiave del JSON con il numero di record che soddisfano la ricerca corrente; se assente vale `totRecField` |
-| `data` | Array&lt;Object&gt; (`null`) | Righe inline; prevale su `jsonUrl`. Da attributo va passato come stringa JSON ed è sempre inteso come array delle righe (`jsonDataField` ignorato) |
-| `cols` | ColDefinition[] | **OBBLIGATORIO**: definizione delle colonne (vedi sotto). Se assente o vuoto viene segnalato un errore in console e la tabella non viene generata |
-| `dataTypes` | Object (`{}`) | Tipi di dato personalizzati, uniti a quelli predefiniti (vedi sotto) |
-| `caption` | string o Function (`null`) | Caption della tabella (testo o HTML), oppure funzione che restituisce stringa o Node. Mostrata sotto la tabella (vedi "Caption e paginazione") |
-| `search` | boolean (`true`) | Genera l'input di ricerca |
-| `searchDebounce` | number (`300`) | Millisecondi di attesa dopo l'ultimo tasto prima di eseguire la ricerca |
-| `perPage` | number (`25`) | Righe per pagina; `0` = nessuna paginazione (tutte le righe, nessuna navigazione) |
-| `paginationDelta` | number (`2`) | Pulsanti pagina mostrati a ciascun lato della pagina corrente |
-| `serverSide` | boolean (`false`) | Paginazione, ordinamento e ricerca delegati al server (vedi "Modalità server-side"). Richiede `jsonUrl` |
-| `serverParams` | Object | Nomi dei parametri di query string in modalità server-side, uniti ai default (vedi sotto) |
-| `initialSort` | { key, dir } o null (`null`) | Ordinamento applicato al caricamento, es. `{ key: 'name', dir: 'asc' }` |
-| `tfoot` | boolean (`false`) | Genera il tfoot (vedi `tfootRender` delle colonne). Non disponibile in modalità server-side |
-| `updateFooterOnPageChange` | boolean (`false`) | Se `true` `tfootRender` riceve solo i record della pagina corrente (subtotali di pagina) e il footer si aggiorna a ogni cambio pagina; se `false` riceve l'intero set filtrato e si aggiorna solo al cambio filtro |
-| `infoText` | string, Function o null (`null`) | Contenuto dell'area info: stringa mustache-like con i segnaposto `{start}`, `{end}`, `{totRec}`, `{filteredRec}`, `{page}`, `{totPages}`, oppure funzione `(start, end, totRec, filteredRec, page, totPages) => string\|Node`. `null` = viene usato `labels.info` |
-| `template` | Array (`[{ slot: 'infoSection' }, { slot: 'table' }]`) | Layout del contenitore principale (vedi "Template") |
-| `locale` | string (`'it-IT'`) | Locale per numeri, date e confronto stringhe nell'ordinamento |
-| `currency` | string (`'EUR'`) | Codice ISO 4217 usato dal tipo `currency` |
-| `datesLocaleOpts` | Intl.DateTimeFormatOptions (`{ year: 'numeric', month: 'short', day: 'numeric' }`) | Parte data dei tipi date/datetime |
-| `timesLocaleOpts` | Intl.DateTimeFormatOptions (`{ hour12: false, hour: '2-digit', minute: '2-digit' }`) | Parte ora del tipo datetime |
-| `numbersLocaleOpts` | Intl.NumberFormatOptions (`{ maximumFractionDigits: 2 }`) | Tipo `num` |
-| `currPercLocaleOpts` | Intl.NumberFormatOptions (`{ minimumFractionDigits: 2, maximumFractionDigits: 2 }`) | Tipi currency/euro/perc/percDecimal |
-| `renderNullAs` | string o null (`'—'`) | Contenuto per i valori null/undefined |
-| `renderZeroAs` | string o null (`null`) | Se non null, contenuto per i valori numerici pari a zero |
-| `renderNaNAs` | string o null (`'—'`) | Contenuto per i valori non numerici nei tipi numerici |
-| `boolTrueIcon` | icona, vedi nota (icona `check-bold` di minimo (Phosphor)) | Icona per i valori `true` (tipo bool) |
-| `boolFalseIcon` | icona, vedi nota (icona `x-bold`) | Icona per i valori `false` |
-| `sortAscArrowIcon` | icona, vedi nota (icona `arrow-up`) | Icona del pulsante di ordinamento, ordinamento asc attivo |
-| `sortDescArrowIcon` | icona, vedi nota (icona `arrow-down`) | Icona del pulsante di ordinamento, ordinamento desc attivo |
-| `sortNoneArrowIcon` | icona, vedi nota (icona `arrows-down-up`) | Icona del pulsante di ordinamento, nessun ordinamento |
-| `paginationPrevIcon` | icona, vedi nota (icona `caret-left`) | Icona del pulsante "pagina precedente" |
-| `paginationNextIcon` | icona, vedi nota (icona `caret-right`) | Icona del pulsante "pagina successiva" |
-| `trCallback` | (tr, row, params) => void (`null`) | Callback invocata dopo il rendering di ogni riga del body |
-| `tableId` | string (`null`) | Id del tag `<table>` |
-| `classes` | Object | Classi consumer (vedi sotto), unite ai default |
-| `labels` | Object | Testi (vedi sotto), uniti ai default |
-
-**Nota sulle icone**: ogni icona può essere una stringa SVG/HTML (es. import `?inline`), un Node, un oggetto domBuilder o una funzione che restituisce uno di questi valori.
-
-### `classes`
-
-Nomi delle classi assegnate agli elementi generati. Le classi interne di layout (CSS module)
-vengono **sempre** applicate in aggiunta a queste; ogni valore sostituisce interamente il
-default della stessa chiave.
-
-```javascript
-classes: {
-  wrapper: null,                    // contenitore principale (<section>: info + tabella)
-  infoOuter: null,                  // contenitore esterno della sezione info
-  info: null,                       // sezione info (testo + ricerca)
-  resultInfo: null,                 // contenitore del testo info
-  search: null,                     // wrapper dell'input di ricerca
-  searchInput: 'form-control form-control-sm', // input di ricerca
-  tableWrapper: 'table-responsive', // div che racchiude la tabella
-  table: 'table table-bordered',    // tag <table>
-  tableFooter: null,                // barra sotto la tabella (caption + paginazione)
-  caption: null,                    // contenitore della caption
-  pagination: null,                 // <nav> della paginazione
-  paginationBtn: 'btn-reset',       // pulsanti della paginazione
-  sortBtn: 'btn-reset',             // pulsanti di ordinamento nei <th>
-  empty: null,                      // cella unica mostrata in assenza di righe
-  textStart: null,                  // allineamento inline-start (le celle minimo lo sono già)
-  textCenter: 'text-center',        // allineamento al centro
-  textEnd: 'text-end',              // allineamento inline-end
-  nowrap: 'text-nowrap',            // no-wrap
-  numeric: 'text-numeric',          // cifre tabulari (tipi numerici)
-  boolCell: null,                   // classe aggiuntiva per tutte le celle di tipo bool
-  boolTrue: null,                   // classe aggiuntiva per le celle bool con valore true
-  boolFalse: null                   // classe aggiuntiva per le celle bool con valore false
-}
-```
-
-Le classi di allineamento (`textEnd`, `textCenter`, `nowrap`, `numeric`) sono quelle usate dai
-tipi di dato predefiniti: modificandole si cambiano le classi di tutte le colonne di quel tipo.
-
-### `labels`
-
-```javascript
-labels: {
-  loading: 'Caricamento dati…',            // segnaposto di caricamento (visually hidden)
-  searchPlaceholder: 'Cerca...',           // placeholder dell'input di ricerca
-  searchTitle: 'Cerca nella tabella',      // attributo title dell'input
-  searchAriaLabel: 'Filtra risultati',     // aria-label dell'input
-  info: 'Stai visualizzando le righe da {start} a {end}, su un totale di {filteredRec} record trovati',
-                                           // template del testo info (vedi `infoText`)
-  noRows: 'Nessun record trovato',         // testo info e cella unica con set di dati vuoto
-  noResults: 'Nessun risultato per la ricerca', // idem, con ricerca senza risultati
-  sortAsc: 'Ordina questa colonna in senso ascendente (A → Z)',   // title/aria-label del
-  sortDesc: 'Ordina questa colonna in senso discendente (Z → A)', // pulsante di ordinamento:
-  sortNone: 'Rimuovi l’ordinamento a questa colonna',             // descrivono l'azione del
-                                                                  // prossimo click
-  paginationAriaLabel: 'Navigazione pagine', // aria-label del <nav>
-  prevPage: 'Pagina precedente',           // title/aria-label del pulsante precedente
-  nextPage: 'Pagina successiva',           // idem, successivo
-  pageTitle: 'Vai a pagina {page}',        // idem, pulsanti pagina
-  currentPage: 'Pagina {page}, corrente'   // idem, pagina corrente
-}
-```
-
-I segnaposto di `labels.info` / `infoText`:
-
-| Segnaposto | Valore |
-|---|---|
-| `{start}` | indice (da 1) del primo record della pagina corrente, nel set filtrato |
-| `{end}` | indice dell'ultimo record della pagina corrente |
-| `{totRec}` | totale dei record non filtrati (dal JSON, vedi `totRecField`, o lunghezza dei dati) |
-| `{filteredRec}` | totale dei record dopo il filtro |
-| `{page}` | pagina corrente |
-| `{totPages}` | numero di pagine |
-
-I numeri vengono formattati secondo `locale`.
-
-## Colonne – `cols`
-
-Parametro **obbligatorio**: array di oggetti, uno per colonna:
-
-```javascript
-cols: [
-  {
-    key,          // string – OBBLIGATORIO: chiave dell'oggetto riga (ammessa la notazione con
-                  // punto per valori annidati, es. 'owner.name')
-    title,        // contenuto del <th>: testo, HTML, Node, array domBuilder o funzione.
-                  // Nelle colonne ordinabili è il testo del pulsante. Default: la chiave
-    dataType,     // string – tipo di dato, una delle chiavi di `dataTypes`; `type` è un alias
-                  // equivalente. Default: 'string'
-    render,       // (row, tr, td) => contenuto | stringa mustache-like – vedi sotto. Default: null
-    tfootRender,  // (rows, td) => contenuto | aggregato '@…' | stringa statica – contenuto della
-                  // cella del tfoot (solo se `tfoot` è true). null = cella vuota. Default: null
-    rowHeading,   // boolean – se true la cella è un'intestazione di riga (th[scope=row]).
-                  // Default: false
-    searchable,   // boolean – abilita la ricerca sulla colonna. Default: true
-    sortable,     // boolean – abilita l'ordinamento sulla colonna. Default: true
-    sortValue,    // valore | row => valore – valore usato per l'ordinamento; prevale su quello
-                  // del tipo di dato. Default: non impostato (tipo di dato / valore grezzo)
-    searchValue,  // idem, per la ricerca. Default: non impostato
-    condition,    // boolean | params => boolean – se false la colonna non viene renderizzata.
-                  // Default: true
-    headerClass,  // string – classi del <th>, in sostituzione di quelle del tipo di dato
-    cellClass     // string – classi delle celle body/tfoot, in sostituzione di quelle del tipo.
-                  // Se solo una tra `headerClass` e `cellClass` è presente, l'altra assume lo
-                  // stesso valore. Default: null (classi del tipo di dato)
-  },
-  ...
-]
-```
-
-### `render`
-
-Funzione con argomenti posizionali, tutti facoltativi:
-
-```javascript
-render: (row, tr, td) => contenuto
-```
-
-- `row` – l'oggetto dati della riga
-- `tr` – l'elemento `<tr>` della riga
-- `td` – l'elemento della cella (`<td>` o `<th scope="row">`)
-
-Il valore restituito è il contenuto della cella: testo, stringa HTML, numero, Node o array
-domBuilder. Casi particolari:
-
-- `undefined` (nessun `return`): la cella viene renderizzata dal tipo di dato, come se `render`
-  non fosse definito. Utile per decorare soltanto `td`/`tr` (classi, attributi, `title`):
-
-  ```javascript
-  render: (row, tr, td) => { if (row.amount < 0) td.classList.add('text-danger'); }
-  ```
-
-- `null`: viene mostrato `renderNullAs`
-
-Da attributo HTML (o da script, per i casi semplici) `render` può essere una stringa
-mustache-like: ogni segnaposto `[[key]]` viene sostituito con il valore corrispondente della
-riga (chiavi annidate ammesse; i valori null diventano `renderNullAs`):
-
-```javascript
-render: '<a href="/users/[[id]]">[[owner.name]]</a>'
-```
-
-Le stringhe HTML vengono inserite tramite la Sanitizer API (`Element.setHTML`, dove supportata):
-script, attributi handler di eventi e URL `javascript:` vengono rimossi, mentre `class`, `id`,
-`style` e `data-*` sono conservati.
-
-### `tfootRender`
-
-Con `tfoot: true` ogni colonna produce una cella nel footer, il cui contenuto è dato da
-`tfootRender`:
-
-- funzione `(rows, td) => contenuto`, dove `rows` è l'intero set filtrato (oppure i soli record
-  della pagina corrente se `updateFooterOnPageChange` è true)
-- uno degli aggregati predefiniti (vedi sotto)
-- qualsiasi altra stringa: contenuto statico (es. l'etichetta `'Totale'`)
-- `null`: cella vuota
-
-Aggregati predefiniti, calcolati sui valori **numerici** della colonna (i valori non numerici
-vengono ignorati) e, tranne `@count`, formattati dal tipo di dato della colonna (es. come valuta
-per `euro`, con `%` per `perc`):
-
-| Aggregato | Valore |
-|---|---|
-| `'@sum'` | somma |
-| `'@avg'` | media aritmetica |
-| `'@min'` | minimo |
-| `'@max'` | massimo |
-| `'@count'` | numero di valori numerici (formattato con `locale`, senza il tipo di dato) |
-
-Un aggregato non riconosciuto viene segnalato in console e produce una cella vuota. Le celle del
-footer ricevono le stesse classi (`cellClass`) delle celle del body.
-
-Il `tfoot` non è disponibile in modalità server-side (il componente riceve solo la pagina
-corrente, gli aggregati sarebbero parziali): se richiesto viene ignorato con un avviso in console.
-
-## Tipi di dato – `dataTypes`
-
-Ogni colonna ha un tipo di dato (`dataType`, default `string`) che ne definisce classi, rendering
-e valori di ordinamento/ricerca. Tipi predefiniti:
-
-| Tipo | Descrizione | Classi delle celle |
-|---|---|---|
-| `string` | valore così com'è | – |
-| `num` | numero formattato con `numbersLocaleOpts` | `textEnd numeric nowrap` |
-| `id` | id numerico: valore grezzo, allineato a destra, non ricercabile | `textEnd numeric` |
-| `perc` | percentuale in scala 0–100, `currPercLocaleOpts` + `%` | `textEnd numeric nowrap` |
-| `percDecimal` | percentuale in scala 0–1 (moltiplicata per 100) | `textEnd numeric nowrap` |
-| `currency` | formato valuta `Intl` con `currency` | `textEnd numeric nowrap` |
-| `euro` | come `currency`, EUR forzato | `textEnd numeric nowrap` |
-| `date` | elemento `<time>`, `datesLocaleOpts`; accetta stringhe ISO, timestamp, `Date` e oggetti data Symfony | `textEnd nowrap` |
-| `datetime` | come `date`, con la parte ora (`timesLocaleOpts`): `<time><span class="[nowrap]">data</span> <small>ora</small></time>` | `textEnd nowrap` |
-| `bool` | icone `boolTrueIcon`/`boolFalseIcon` (accetta anche `1`/`0`, `'true'`/`'false'`); `null` → `renderNullAs`; non ordinabile né ricercabile | stili interni delle icone |
-| `email` | andate a capo facoltative attorno alla `@` | – |
-
-I tipi numerici applicano `renderNaNAs` ai valori non numerici e `renderZeroAs` (se impostato)
-agli zeri. Per tutti i tipi i valori `null`/`undefined` vengono resi come `renderNullAs`.
-
-### Tipi personalizzati
-
-Il parametro `dataTypes` è unito ai tipi predefiniti: una chiave già esistente sovrascrive solo
-le proprietà indicate, una chiave nuova può estendere un tipo esistente con `inheritsFrom`.
-
-```javascript
-dataTypes: {
-  // modifica solo le classi del tipo predefinito `num`
-  num: { cellClass: 'text-end fw-bold' },
-
-  // nuovo tipo basato su `num` (stesse classi, ordinamento, ricerca e gestione NaN/zero)
-  km: {
-    inheritsFrom: 'num',
-    render: (value, row, params) => `${value.toLocaleString(params.locale)} km`
-  }
-}
-```
-
-Proprietà di un tipo di dato (tutte facoltative):
-
-```javascript
-{
-  headerClass,        // string – classi di default del <th>
-  cellClass,          // string – classi di default delle celle
-  internalCellClass,  // (value, row, params) => string – classi aggiunte sempre alle celle,
-                      // indipendentemente da `cellClass` (usato dal tipo `bool` per le icone)
-  render,             // (value, row, params) => contenuto – non invocato per i valori null
-  sortValue,          // (value, row, params) => valore per l'ordinamento
-  searchValue,        // (value, row, params) => stringa per la ricerca
-  colDefaults,        // Object – default forzati per le colonne di questo tipo
-                      // (es. { sortable: false }), comunque sovrascrivibili nella colonna
-  inheritsFrom        // string – solo tipi nuovi: tipo predefinito da estendere
-}
-```
-
-A differenza del `render` di colonna (`(row, tr, td)`), il `render` del tipo di dato riceve per
-primo il **valore** della cella, perché il tipo è generico rispetto al campo.
-
-## Ordinamento
-
-Ogni colonna con `sortable: true` (default; i tipi `bool` lo disattivano) ha un pulsante nel
-`<th>` che cicla tra nessun ordinamento → ascendente → discendente → nessuno; l'attributo
-`aria-sort` del `<th>` e l'icona riflettono lo stato, `title`/`aria-label` del pulsante
-descrivono l'azione del click successivo (`labels.sortAsc/sortDesc/sortNone`). È attivo un solo
-ordinamento per volta; il cambio di ordinamento riporta alla prima pagina.
-
-Lato client il confronto usa i valori precalcolati per ogni riga (`sortValue` di colonna, poi del
-tipo di dato, poi il valore grezzo): i valori vuoti (`null`, `''`, `NaN`) vanno sempre in coda,
-i numeri sono confrontati numericamente, il resto con `localeCompare` (`locale`, collazione
-numerica, insensibile a maiuscole e accenti). L'ordinamento è stabile.
-
-`initialSort: { key, dir }` applica un ordinamento al caricamento; `setSort(key, dir)` lo cambia
-via script.
-
-## Ricerca
-
-L'input di ricerca (`search: true`) filtra le righe dopo `searchDebounce` ms dall'ultimo tasto:
-ogni parola del termine (separatore: spazi) deve essere contenuta nel testo di ricerca della riga,
-composto dai valori delle colonne `searchable` (`searchValue` di colonna, poi del tipo di dato,
-poi il valore grezzo), senza distinzione tra maiuscole e minuscole. La ricerca riporta alla prima
-pagina; `setSearch(term)` la imposta via script.
-
-## Paginazione
-
-Con `perPage` > 0 (default 25) le righe vengono suddivise in pagine e sotto la tabella compare la
-navigazione: pulsanti precedente/successivo (icone `paginationPrevIcon`/`paginationNextIcon`),
-la prima e l'ultima pagina e `paginationDelta` pagine per lato della corrente, con puntini di
-sospensione per le pagine omesse. La navigazione è nascosta quando c'è una sola pagina.
-`perPage: 0` disattiva la paginazione (tutte le righe in un'unica pagina).
-
-`goToPage(page)` cambia pagina via script; `state.page`/`state.totPages` riportano lo stato.
-
-### Caption e paginazione
-
-La caption è mostrata **sotto la tabella**, nella barra `tableFooter`, allineata a sinistra; a
-destra, nella stessa barra, la navigazione delle pagine. La caption non è un elemento
-`<caption>` (che dovrebbe stare dentro la tabella e non potrebbe ospitare la navigazione senza
-farla leggere come nome della tabella) ma un contenitore con id, collegato alla tabella tramite
-`aria-labelledby`: il nome accessibile della tabella è quindi lo stesso di una `<caption>`.
-Posizioni diverse si ottengono con gli slot `caption` e `pagination` del [template](#template).
-
-## Modalità server-side
-
-Con `serverSide: true` il componente non elabora i dati in locale: a ogni cambio pagina,
-ordinamento o ricerca invia una nuova richiesta GET a `jsonUrl`, aggiungendo alla query string i
-parametri definiti in `serverParams` (quelli già presenti in `jsonUrl` vengono conservati):
-
-```javascript
-serverParams: {
-  page: 'page',        // pagina richiesta (da 1)
-  start: 'start',      // indice (da 0) del primo record richiesto = (page - 1) * perPage,
-                       // comodo per `LIMIT start, perPage`
-  perPage: 'perPage',  // record per pagina
-  sort: 'sort',        // chiave della colonna ordinata (omesso senza ordinamento)
-  dir: 'dir',          // 'asc' | 'desc' (omesso senza ordinamento)
-  search: 'search'     // termine di ricerca (omesso se vuoto)
-}
-```
-
-Un valore `null` omette il parametro (es. `serverParams: { start: null }` per inviare solo `page`).
-Richiesta di esempio, seconda pagina ordinata per nome con ricerca attiva:
-
-```
-GET /api/rows.json?page=2&start=25&perPage=25&sort=name&dir=desc&search=mar
-```
-
-Il JSON di risposta deve contenere le **sole righe della pagina richiesta** in `jsonDataField`,
-il totale dei record in `totRecField` e il numero di record che soddisfano la ricerca in
-`filteredRecField` (se assente vale il totale):
-
-```json
-{ "data": [ ...25 righe... ], "totRec": 1500, "filteredRec": 40 }
-```
-
-Durante la richiesta il contenitore principale ha `aria-busy="true"` (la tabella viene resa
-semitrasparente); le risposte superate da una richiesta più recente vengono ignorate. Se la
-pagina richiesta non esiste più (il set di dati si è ridotto), viene richiesta l'ultima
-disponibile. In questa modalità `data`, `filtered` e `pageRows` dello stato contengono solo la
-pagina corrente e il `tfoot` non è disponibile. `serverSide` richiede `jsonUrl`: con `data` inline
-viene ignorato con un avviso in console.
-
-### Modalità jQuery DataTables
-
-Con `jqDatatableMode: true` (o l'attributo `jqdatatablemode="true"`) i default dei parametri server-side diventano quelli del formato di jQuery DataTables, utile per riutilizzare endpoint già esistenti:
-
-| Parametro | Default con `jqDatatableMode` |
-|---|---|
-| `jsonDataField` | `'data'` |
-| `totRecField` | `'recordsTotal'` |
-| `filteredRecField` | `'recordsFiltered'` |
-| `serverSide` | `true` |
-| `serverParams` | `{ page: null, start: 'start', perPage: 'length', sort: 'order[0][column]', dir: 'order[0][dir]', search: 'search[value]' }` |
-
-Precedenza: `init()` > attributo HTML > `JsonTable.setDefaults()` > modalità jQuery DataTables > default predefiniti. Ogni parametro può quindi essere sovrascritto singolarmente, e `serverParams` viene unito chiave per chiave.
-
-Oltre ai `serverParams`, in questa modalità vengono inviati anche `draw=1` e, per ogni colonna visualizzata, `columns[i][name]` (la `key`), `columns[i][searchable]` e `columns[i][orderable]`. `order[0][column]` riceve l'**indice** della colonna ordinata (tra quelle visualizzate), non la chiave. È previsto un solo criterio di ordinamento (`order[0]`).
-
-```html
-<json-table jsonurl="/api/rows" jqdatatablemode="true" cols='[{"key":"id"},{"key":"name"}]'></json-table>
-```
-
-```
-GET /api/rows?draw=1&columns[0][name]=id&columns[0][searchable]=true&columns[0][orderable]=true&columns[1][name]=name&…&start=25&length=25&order[0][column]=1&order[0][dir]=desc&search[value]=mar
-```
-
-## Template
-
-`template` definisce il contenuto del contenitore principale come array domBuilder, in cui gli
-elementi `{ slot: 'nome' }` vengono sostituiti dalle parti predefinite:
-
-| Slot | Contenuto |
-|---|---|
-| `infoSection` | sezione info completa (testo info + input di ricerca, in riga) |
-| `resultInfo` | solo il testo info |
-| `search` | solo l'input di ricerca (se `search` è true) |
-| `table` | wrapper + tabella (thead, tbody, tfoot) e barra `tableFooter` con caption e paginazione |
-| `caption` | solo la caption (se `caption` è impostata) |
-| `pagination` | solo la navigazione delle pagine (se `perPage` > 0) |
-
-`caption` e `pagination` fanno parte della barra sotto la tabella dello slot `table`; se il
-template li colloca esplicitamente altrove, vengono rimossi dalla barra (che sparisce se resta
-vuota).
-
-Il default `[{ slot: 'infoSection' }, { slot: 'table' }]` corrisponde alla struttura descritta
-in [Struttura generata](#struttura-generata). Esempio con ricerca e paginazione sopra la tabella
-e info sotto:
-
-```javascript
-template: [
-  { className: 'flex gap-2 mbe-sm', children: [{ slot: 'search' }, { slot: 'pagination' }] },
-  { slot: 'table' },   // barra sotto la tabella con la sola caption
-  { slot: 'resultInfo' }
-]
-```
-
-Da `init()` è accettata anche una funzione `(parts, params) => array`, dove `parts` contiene le
-parti predefinite (oggetti domBuilder) con le stesse chiavi degli slot. Gli slot non
-riconosciuti vengono segnalati in console e ignorati.
-
-## Struttura generata
-
-```html
-<json-table>
-  <section class="[wrapper] [classes.wrapper]">
-    <div class="[infoOuter] [classes.infoOuter]">
-      <div class="[info] [classes.info]">
-        <div class="[resultInfo] [classes.resultInfo]" aria-live="polite">Stai visualizzando le righe da 1 a 25, ...</div>
-        <div class="[search] [classes.search]">           <!-- solo se search: true -->
-          <input type="search" class="form-control form-control-sm" ...>
-        </div>
-      </div>
-    </div>
-    <div class="[tableOuter]">
-      <div class="[tableWrapper] table-responsive">        <!-- classes.tableWrapper -->
-        <table class="[table] table table-bordered" aria-labelledby="jt-1-caption">  <!-- classes.table; aria-labelledby solo se caption -->
-          <thead>
-            <tr>
-              <th scope="col" data-key="name" data-sortable="true" class="[sortable] ..." aria-sort="ascending">
-                <button type="button" class="[sortBtn] btn-reset" title="Ordina ..." aria-label="Nome: Ordina ...">
-                  <span class="[sortTitle]">Nome</span>
-                  <span class="[sortIcon]" aria-hidden="true"><svg ...></svg></span>
-                </button>
-              </th>
-              <th scope="col" data-key="active" class="text-center">Attivo</th>   <!-- non ordinabile -->
-            </tr>
-          </thead>
-          <tbody>
-            <tr data-jt-idx="0">
-              <th scope="row" data-key="id" class="text-end text-numeric">1</th>  <!-- rowHeading -->
-              <td data-key="name">Mario</td>
-              <td data-key="active" class="[boolCell] [boolTrue]"><svg ...></svg></td>
-            </tr>
-            <!-- oppure, senza righe: -->
-            <tr><td colspan="3" class="[empty] [classes.empty]">Nessun record trovato</td></tr>
-          </tbody>
-          <tfoot>                                          <!-- solo se tfoot: true -->
-            <tr><td data-key="id"></td><td data-key="name">Totale</td>...</tr>
-          </tfoot>
-        </table>
-      </div>
-      <div class="[tableFooter] [classes.tableFooter]">    <!-- solo se caption o perPage > 0 -->
-        <div class="[caption] [classes.caption]" id="jt-1-caption">Utenti</div>   <!-- solo se caption -->
-        <nav class="[pagination] [classes.pagination]" aria-label="Navigazione pagine">  <!-- solo se perPage > 0; hidden con una sola pagina -->
-          <ul class="[paginationList]">
-            <li class="[paginationItem]"><button type="button" class="[paginationBtn] btn-reset [paginationArrow]" data-page="prev" aria-label="Pagina precedente" disabled><svg ...></svg></button></li>
-            <li class="[paginationItem]"><button type="button" class="[paginationBtn] btn-reset" data-page="1" aria-current="page" aria-label="Pagina 1, corrente">1</button></li>
-            <li class="[paginationItem]"><button type="button" class="[paginationBtn] btn-reset" data-page="2" aria-label="Vai a pagina 2">2</button></li>
-            <li class="[paginationItem]"><span class="[paginationEllipsis]" aria-hidden="true">…</span></li>
-            <li class="[paginationItem]"><button type="button" class="[paginationBtn] btn-reset" data-page="10" aria-label="Vai a pagina 10">10</button></li>
-            <li class="[paginationItem]"><button type="button" class="[paginationBtn] btn-reset [paginationArrow]" data-page="next" aria-label="Pagina successiva"><svg ...></svg></button></li>
-          </ul>
-        </nav>
-      </div>
-    </div>
-  </section>
-</json-table>
-```
-
-Le classi tra parentesi quadre sono quelle interne del CSS module. Nei `<th>` ordinabili
-l'attributo `aria-sort` (`ascending`/`descending`) è presente solo sulla colonna ordinata;
-`title` e `aria-label` del pulsante descrivono l'azione del click successivo.
-
-## Custom properties CSS
-
-Definite in `json-table.minimo.tokens.mjs` (namespace `--jt-*`):
-
-| Proprietà | Default (token minimo) |
-|---|---|
-| `--jt-wrapper-margin-block` | `{size.md}` |
-| `--jt-busy-opacity` | `.5` |
-| `--jt-info-gap` | `{size.sm}` |
-| `--jt-info-font-size` | `{font.size.sm}` |
-| `--jt-info-color` | `{text.muted}` |
-| `--jt-info-outer-padding-block-end` | `{size.xs}` |
-| `--jt-search-max-width` | `20rem` |
-| `--jt-thead-hover-background-color` | `color-mix(in srgb, {table.thead.background.color} 90%, {accent})` |
-| `--jt-sort-btn-padding-block` | `{table.cell.padding.block}` |
-| `--jt-sort-btn-padding-inline` | `{table.cell.padding.inline}` |
-| `--jt-sort-btn-line-height` | `{table.cell.line-height}` |
-| `--jt-sort-icon-size` | `1em` |
-| `--jt-sort-icon-gap` | `.4em` |
-| `--jt-sort-icon-none-opacity` | `.4` |
-| `--jt-table-footer-padding-block-start` | `{size.xs}` |
-| `--jt-caption-font-size` | `{font.size.sm}` |
-| `--jt-caption-color` | `{text.muted}` |
-| `--jt-pagination-border-width` | `1px` |
-| `--jt-pagination-border-color` | `{table.border.color}` |
-| `--jt-pagination-radius` | `{radius.xxs}` |
-| `--jt-pagination-font-size` | `{font.size.sm}` |
-| `--jt-pagination-line-height` | `{table.cell.line-height}` |
-| `--jt-pagination-btn-min-width` | `2.2em` |
-| `--jt-pagination-btn-padding-block` | `{table.cell.padding.block}` |
-| `--jt-pagination-btn-padding-inline` | `{table.cell.padding.inline}` |
-| `--jt-pagination-icon-size` | `1em` |
-| `--jt-pagination-current-background-color` | `{table.thead.background.color}` |
-| `--jt-pagination-current-font-weight` | `{font.weight.semibold}` |
-| `--jt-pagination-hover-background-color` | `{table.body.tr.hover-bg-color}` |
-| `--jt-pagination-disabled-opacity` | `.5` |
-| `--jt-bool-icon-size` | `1.1em` |
-| `--jt-bool-true-color` | `{status.success.color}` |
-| `--jt-bool-false-color` | `{status.danger.color}` |
-| `--jt-empty-color` | `{text.muted}` |
-| `--jt-empty-padding-block` | `{size.sm}` |
+ 
+[Documentazione](jt-docs.md)