@massimo-cassandro/minimo 1.41.3 → 1.41.5

package/src/web-components/json-table/json-table.minimo.tokens.mjs

@@ -45,7 +45,7 @@ export default {
       }
     },
 
-    // sortable columns (thead)
+    // colonne ordinabili (thead)
     thead: {
       hover: {
         background: {
@@ -58,7 +58,7 @@ export default {
     },
 
     sort: {
-      // the sort button fills the whole th: same padding/line-height of minimo table cells
+      // il pulsante di ordinamento riempie l'intero th: stesso padding/line-height delle celle tabella di minimo
       btn: {
         padding: {
           block: {
@@ -84,7 +84,7 @@ export default {
           $type: 'dimension',
           $value: '.4em'
         },
-        // opacity of the icon when no sort is active
+        // opacità dell'icona quando non c'è alcun ordinamento attivo
         none: {
           opacity: {
             $type: 'number',
@@ -94,7 +94,7 @@ export default {
       }
     },
 
-    // boolean cells
+    // celle booleane
     bool: {
       icon: {
         size: {
@@ -116,7 +116,7 @@ export default {
       }
     },
 
-    // opacity of the table while a server-side request is in progress
+    // opacità della tabella mentre è in corso una richiesta server-side
     busy: {
       opacity: {
         $type: 'number',
@@ -124,7 +124,7 @@ export default {
       }
     },
 
-    // footer bar below the table (caption + pagination)
+    // barra del footer sotto la tabella (caption + paginazione)
     'table-footer': {
       padding: {
         block: {

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

@@ -1,20 +1,17 @@
 # `<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 stilizzato direttamente dal CSS del progetto in cui è utilizzato.
 
 ## Installazione
 
 È sufficiente importare il file del componente (registra il custom element):
 
 ```javascript
-import '@massimo-cassandro/minimo/src/web-components/json-table/json-table-component.js';
+// 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/src/web-components/json-table/json-table-component.js';
+import { JsonTable } from '@massimo-cassandro/minimo/json-table';
 ```
 
 Il CSS (`json-table-component.module.css`) è importato dal componente stesso; le custom
@@ -25,10 +22,7 @@ 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:
+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
@@ -52,6 +46,7 @@ const other = document.createElement('json-table');
     { "key": "active", "title": "Attivo", "dataType": "bool" }
   ]'
   tfoot="true"
+  serverSide="true"
 ></json-table>
 
 <!-- dati inline (JSON serializzato) al posto di jsonurl -->
@@ -208,106 +203,53 @@ el.init({ jsonUrl: '/api/rows.json', cols: [...] });
 
 ## Parametri
 
-Tutti i parametri sono impostabili sia da attributo HTML che da `init()`. I valori di tipo
-funzione solo da `init()`.
+Tutti i parametri sono impostabili sia da attributo HTML che come oggetto in `init({...})`. I valori di tipo funzione solo da `init()`.
 
-```javascript
-{
-  debug,                  // boolean – log in console di parametri, colonne, dati, stato ed
-                          // elementi generati. Default: false
-
-  jsonUrl,                // string – URL del JSON da caricare. Ignorato se `data` è presente.
-                          // Default: null
-  jsonDataField,          // string|null – chiave del JSON che contiene l'array delle righe
-                          // (es. 'data' per { data: [...] }); null o '' = la root del JSON è
-                          // l'array stesso. Default: 'data'
-  totRecField,            // string – chiave del JSON con il totale dei record (numerico); se
-                          // assente o non numerico il totale è la lunghezza dell'array.
-                          // Default: 'totRec'
-  filteredRecField,       // string – solo server-side: chiave del JSON con il numero di record
-                          // che soddisfano la ricerca corrente; se assente vale `totRecField`.
-                          // Default: 'filteredRec'
-  data,                   // Array<Object> – righe inline; prevale su `jsonUrl`. Da attributo va
-                          // passato come stringa JSON ed è sempre inteso come array delle righe
-                          // (`jsonDataField` ignorato). Default: null
-
-  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). Default: {}
-
-  caption,                // string|Function – caption della tabella (testo o HTML), oppure
-                          // funzione che restituisce stringa o Node. Mostrata sotto la tabella
-                          // (vedi "Caption e paginazione"). Default: null
-  search,                 // boolean – genera l'input di ricerca. Default: true
-  searchDebounce,         // number – ms di attesa dopo l'ultimo tasto prima di eseguire la
-                          // ricerca. Default: 300
-
-  perPage,                // number – righe per pagina; 0 = nessuna paginazione (tutte le righe,
-                          // nessuna navigazione). Default: 25
-  paginationDelta,        // number – pulsanti pagina mostrati a ciascun lato della pagina
-                          // corrente. Default: 2
-  serverSide,             // boolean – paginazione, ordinamento e ricerca delegati al server
-                          // (vedi "Modalità server-side"). Richiede `jsonUrl`. Default: false
-  serverParams,           // Object – nomi dei parametri di query string in modalità server-side,
-                          // uniti ai default (vedi sotto)
-  initialSort,            // { key, dir }|null – ordinamento applicato al caricamento, es.
-                          // { key: 'name', dir: 'asc' }. Default: null
-
-  tfoot,                  // boolean – genera il tfoot (vedi `tfootRender` delle colonne).
-                          // Non disponibile in modalità server-side. Default: false
-  updateFooterOnPageChange, // boolean – 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. Default: false
-  infoText,               // string|Function|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`. Default: null
-  template,               // Array – layout del contenitore principale (vedi "Template").
-                          // Default: [{ slot: 'infoSection' }, { slot: 'table' }]
-
-  locale,                 // string – locale per numeri, date e confronto stringhe
-                          // nell'ordinamento. Default: 'it-IT'
-  currency,               // string – codice ISO 4217 usato dal tipo `currency`. Default: 'EUR'
-  datesLocaleOpts,        // Intl.DateTimeFormatOptions – parte data dei tipi date/datetime.
-                          // Default: { year: 'numeric', month: 'short', day: 'numeric' }
-  timesLocaleOpts,        // Intl.DateTimeFormatOptions – parte ora del tipo datetime.
-                          // Default: { hour12: false, hour: '2-digit', minute: '2-digit' }
-  numbersLocaleOpts,      // Intl.NumberFormatOptions – tipo num.
-                          // Default: { maximumFractionDigits: 2 }
-  currPercLocaleOpts,     // Intl.NumberFormatOptions – tipi currency/euro/perc/percDecimal.
-                          // Default: { minimumFractionDigits: 2, maximumFractionDigits: 2 }
-
-  renderNullAs,           // string|null – contenuto per i valori null/undefined. Default: '—'
-  renderZeroAs,           // string|null – se non null, contenuto per i valori numerici pari a
-                          // zero. Default: null
-  renderNaNAs,            // string|null – contenuto per i valori non numerici nei tipi numerici.
-                          // Default: '—'
-
-  boolTrueIcon,           // icona per i valori true (tipo bool).
-                          // Default: icona `check-bold` di minimo (Phosphor)
-  boolFalseIcon,          // icona per i valori false. Default: icona `x-bold`
-  sortAscArrowIcon,       // icona del pulsante di ordinamento, ordinamento asc attivo.
-                          // Default: icona `arrow-up`
-  sortDescArrowIcon,      // idem, ordinamento desc attivo. Default: icona `arrow-down`
-  sortNoneArrowIcon,      // idem, nessun ordinamento. Default: icona `arrows-down-up`
-  paginationPrevIcon,     // icona del pulsante "pagina precedente". Default: icona `caret-left`
-  paginationNextIcon,     // icona del pulsante "pagina successiva". Default: icona `caret-right`
-                          // 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
-
-  trCallback,             // (tr, row, params) => void – callback invocata dopo il rendering di
-                          // ogni riga del body. Default: null
-  tableId,                // string – id del tag <table>. Default: null
-
-  classes,                // Object – classi consumer (vedi sotto), unite ai default
-  labels                  // Object – testi (vedi sotto), uniti ai default
-}
-```
+| 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`
 
@@ -624,6 +566,30 @@ disponibile. In questa modalità `data`, `filtered` e `pageRows` dello stato con
 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

package/src/web-components/json-table/src/cell-content.js

@@ -8,21 +8,21 @@ import { toNumber } from './data-types.js';
 /** @typedef {import('./parse-cols.js').ParsedCol} ParsedCol */
 
 /**
- * Computes the content of a body cell.
+ * Calcola il contenuto di una cella del body.
  *
  * Pipeline:
- * 1. column `render`: function `(row, tr, td)` or mustache-like string (`[[key]]`); a function
- *    returning `undefined` lets the pipeline go on (useful to only decorate `td`/`tr`), `null`
- *    gives `renderNullAs`
- * 2. `null`/`undefined` raw value → `renderNullAs`
- * 3. data type `render(value, row, params)`
- * 4. raw value
+ * 1. `render` della colonna: funzione `(row, tr, td)` o stringa in stile mustache (`[[key]]`); una funzione
+ *    che restituisce `undefined` lascia proseguire la pipeline (utile per decorare solo `td`/`tr`), `null`
+ *    dà `renderNullAs`
+ * 2. valore grezzo `null`/`undefined` → `renderNullAs`
+ * 3. `render(value, row, params)` del data type
+ * 4. valore grezzo
  *
- * @param {ParsedCol} col - Parsed column
- * @param {Object} row - Row object
- * @param {JsonTableParams} params - Resolved params
- * @param {HTMLTableRowElement} [tr] - Row element, passed to the column `render`
- * @param {HTMLTableCellElement} [td] - Cell element, passed to the column `render`
+ * @param {ParsedCol} col - Colonna analizzata
+ * @param {Object} row - Oggetto riga
+ * @param {JsonTableParams} params - Parametri risolti
+ * @param {HTMLTableRowElement} [tr] - Elemento riga, passato al `render` della colonna
+ * @param {HTMLTableCellElement} [td] - Elemento cella, passato al `render` della colonna
  * @returns {CellContent}
  *
  * @example
@@ -30,7 +30,7 @@ import { toNumber } from './data-types.js';
  * cellContent({ ...col, key: 'amount', _type: types.euro }, { amount: null }, params); // → '—' (renderNullAs)
  * cellContent({ ...col, render: '<b>[[name]]</b>' }, { name: 'Mario' }, params);      // → '<b>Mario</b>'
  * cellContent({ ...col, render: (row, tr, td) => { td.title = row.name; } }, row, params, tr, td);
- * // → data type / raw value (render returned undefined)
+ * // → data type / valore grezzo (render ha restituito undefined)
  */
 export function cellContent(col, row, params, tr, td) {
 
@@ -61,8 +61,8 @@ export function cellContent(col, row, params, tr, td) {
 
 
 /**
- * Built-in footer aggregates (`tfootRender: '@sum'`, ...), computed on the numeric values
- * of the column (non-numeric values are skipped).
+ * Aggregati predefiniti del footer (`tfootRender: '@sum'`, ...), calcolati sui valori numerici
+ * della colonna (i valori non numerici vengono saltati).
  * @type {Object<string, (nums: number[]) => number>}
  */
 const aggregates = {
@@ -75,17 +75,17 @@ const aggregates = {
 
 
 /**
- * Computes the content of a footer cell from the column `tfootRender`:
- * - function `(rows, td) => content`
- * - built-in aggregate `'@sum'`, `'@avg'`, `'@min'`, `'@max'` (formatted by the column data
- *   type, e.g. as currency for `euro` columns) or `'@count'` (number of numeric values)
- * - any other string: static content (e.g. a "Totale" label)
- * - `null`: empty cell
+ * Calcola il contenuto di una cella del footer dal `tfootRender` della colonna:
+ * - funzione `(rows, td) => content`
+ * - aggregato predefinito `'@sum'`, `'@avg'`, `'@min'`, `'@max'` (formattato dal data
+ *   type della colonna, ad es. come valuta per le colonne `euro`) oppure `'@count'` (numero di valori numerici)
+ * - qualsiasi altra stringa: contenuto statico (ad es. un'etichetta "Totale")
+ * - `null`: cella vuota
  *
- * @param {ParsedCol} col - Parsed column
- * @param {Array<Object>} rows - Rows to aggregate (filtered set or current page, see `updateFooterOnPageChange`)
- * @param {JsonTableParams} params - Resolved params
- * @param {HTMLTableCellElement} [td] - Footer cell element, passed to the `tfootRender` function
+ * @param {ParsedCol} col - Colonna analizzata
+ * @param {Array<Object>} rows - Righe da aggregare (insieme filtrato o pagina corrente, vedi `updateFooterOnPageChange`)
+ * @param {JsonTableParams} params - Parametri risolti
+ * @param {HTMLTableCellElement} [td] - Elemento cella del footer, passato alla funzione `tfootRender`
  * @returns {CellContent}
  *
  * @example

package/src/web-components/json-table/src/content-utils.js

@@ -5,17 +5,17 @@ import { domBuilder } from '../../../utilities/dom-builder/dom-builder.js';
 /** @typedef {import('./defaults.js').CellContent} CellContent */
 
 /**
- * Replaces the content of `el` with `content`, accepting every content form used by the
- * component (see `CellContent`): a Node is appended as-is, a domBuilder array is built inside
- * the element, a string/number is set as text or, when it contains `<`, as sanitized markup
- * (`Element.setHTML` where supported, `innerHTML` otherwise, consistently with domBuilder).
- * The empty sanitizer config passed to `setHTML` keeps `class`, `id`, `style` and `data-*`
- * attributes, which the browser default configuration removes, while unsafe content (scripts,
- * event handlers, `javascript:` URLs) is always stripped.
- * A function is invoked and its result used. `null`/`undefined` empty the element.
+ * Sostituisce il contenuto di `el` con `content`, accettando ogni forma di contenuto usata dal
+ * componente (vedi `CellContent`): un Node viene aggiunto così com'è, un array domBuilder viene costruito dentro
+ * l'elemento, una stringa/numero viene impostato come testo oppure, se contiene `<`, come markup sanificato
+ * (`Element.setHTML` dove supportato, altrimenti `innerHTML`, in modo coerente con domBuilder).
+ * La configurazione vuota del sanitizer passata a `setHTML` mantiene gli attributi `class`, `id`, `style` e `data-*`,
+ * che la configurazione predefinita del browser rimuove, mentre il contenuto non sicuro (script,
+ * gestori di eventi, URL `javascript:`) viene sempre eliminato.
+ * Una funzione viene invocata e il suo risultato usato. `null`/`undefined` svuotano l'elemento.
  *
- * @param {HTMLElement} el - Target element (emptied first)
- * @param {CellContent|(() => CellContent)} content - Content to set
+ * @param {HTMLElement} el - Elemento di destinazione (svuotato prima)
+ * @param {CellContent|(() => CellContent)} content - Contenuto da impostare
  * @returns {void}
  *
  * @example
@@ -24,7 +24,7 @@ import { domBuilder } from '../../../utilities/dom-builder/dom-builder.js';
  * setContent(td, 1234);
  * setContent(td, document.createElement('span'));
  * setContent(td, [{ tag: 'a', attrs: { href: '#' }, content: 'link' }]);
- * setContent(td, null); // → empty cell
+ * setContent(td, null); // → cella vuota
  */
 export function setContent(el, content) {
 
@@ -60,11 +60,11 @@ export function setContent(el, content) {
 
 
 /**
- * Reads a value from an object through a dot-separated key path.
- * Returns `undefined` when an intermediate key does not exist.
+ * Legge un valore da un oggetto tramite un percorso di chiavi separate da punti.
+ * Restituisce `undefined` quando una chiave intermedia non esiste.
  *
- * @param {Object|null|undefined} obj - Source object
- * @param {string} path - Key or dot-separated path
+ * @param {Object|null|undefined} obj - Oggetto sorgente
+ * @param {string} path - Chiave o percorso separato da punti
  * @returns {*}
  *
  * @example
@@ -81,13 +81,13 @@ export function getNestedValue(obj, path) {
 
 
 /**
- * Resolves a mustache-like template: every `[[key]]` placeholder is replaced with the
- * corresponding row value (nested keys allowed); placeholders resolving to `null`/`undefined`
- * are replaced with `nullAs`. Useful for the js-free configuration via HTML attributes.
+ * Risolve un template in stile mustache: ogni segnaposto `[[key]]` viene sostituito con il
+ * corrispondente valore della riga (chiavi annidate ammesse); i segnaposto che risultano `null`/`undefined`
+ * vengono sostituiti con `nullAs`. Utile per la configurazione senza JS tramite attributi HTML.
  *
- * @param {string} tpl - Template string
- * @param {Object} row - Row object
- * @param {string} [nullAs=''] - Replacement of null/undefined values (default: '')
+ * @param {string} tpl - Stringa del template
+ * @param {Object} row - Oggetto riga
+ * @param {string} [nullAs=''] - Sostituto dei valori null/undefined (default: '')
  * @returns {string}
  *
  * @example

package/src/web-components/json-table/src/data-types.js

@@ -8,7 +8,7 @@ import { iconContent } from './icons.js';
 /** @typedef {import('./defaults.js').DataTypeDefinition} DataTypeDefinition */
 
 /**
- * Converts a value to a number; empty strings and nullish values give `NaN`.
+ * Converte un valore in numero; le stringhe vuote e i valori nullish danno `NaN`.
  * @param {*} value
  * @returns {number}
  *
@@ -26,8 +26,8 @@ export function toNumber(value) {
 
 
 /**
- * Converts a boolean-like value (`true`/`false`, `1`/`0`, `'1'`/`'0'`, `'true'`/`'false'`)
- * to a boolean; every other value gives `null`, so that `null` can be told apart from `false`.
+ * Converte un valore simile a un booleano (`true`/`false`, `1`/`0`, `'1'`/`'0'`, `'true'`/`'false'`)
+ * in booleano; ogni altro valore dà `null`, così che `null` si distingua da `false`.
  * @param {*} value
  * @returns {boolean|null}
  *
@@ -49,11 +49,11 @@ export function toBool(value) {
 
 
 /**
- * Parses a date-like value: ISO string, timestamp, `Date` object or a Symfony-like object
+ * Analizza un valore simile a una data: stringa ISO, timestamp, oggetto `Date` o un oggetto in stile Symfony
  * (`{ date: '2022-12-02 06:18:55', timezone_type: 3, timezone: 'Europe/Berlin' }`).
  * TODO fuso orario degli oggetti Symfony non gestito (la stringa `date` è interpretata come ora locale)
  * @param {*} value
- * @returns {Date|null} `null` for empty or invalid values
+ * @returns {Date|null} `null` per i valori vuoti o non validi
  *
  * @example
  * parseDate('2024-01-31');                       // → Date
@@ -77,11 +77,11 @@ export function parseDate(value) {
 
 
 /**
- * Formats a numeric value, applying `renderNaNAs` and `renderZeroAs`.
- * @param {*} value - Raw value
- * @param {JsonTableParams} params - Resolved params
- * @param {Intl.NumberFormatOptions} formatOpts - `toLocaleString` options
- * @param {(formatted: string, num: number) => string} [wrap] - Optional decorator of the formatted string
+ * Formatta un valore numerico, applicando `renderNaNAs` e `renderZeroAs`.
+ * @param {*} value - Valore grezzo
+ * @param {JsonTableParams} params - Parametri risolti
+ * @param {Intl.NumberFormatOptions} formatOpts - Opzioni di `toLocaleString`
+ * @param {(formatted: string, num: number) => string} [wrap] - Decoratore opzionale della stringa formattata
  * @returns {string}
  *
  * @example
@@ -104,23 +104,23 @@ export function formatNumber(value, params, formatOpts, wrap) {
 
 
 /**
- * Built-in data types, built on the resolved params (class names, locale options, icons).
+ * Data type predefiniti, costruiti sui parametri risolti (nomi delle classi, opzioni locale, icone).
  *
- * | key           | description                                                     | cell classes            |
+ * | chiave        | descrizione                                                     | classi della cella      |
  * |---------------|-----------------------------------------------------------------|-------------------------|
- * | `string`      | default type, value as-is                                       | –                       |
- * | `num`         | number formatted with `numbersLocaleOpts`                       | textEnd numeric nowrap  |
- * | `id`          | numeric id: raw value, right aligned, not searchable            | textEnd numeric         |
- * | `perc`        | percentage already in 0–100 scale, `currPercLocaleOpts` + " %"  | textEnd numeric nowrap  |
- * | `percDecimal` | percentage in 0–1 scale (multiplied by 100)                     | textEnd numeric nowrap  |
- * | `currency`    | `Intl` currency format, `params.currency`                       | textEnd numeric nowrap  |
- * | `euro`        | as `currency`, EUR forced                                       | textEnd numeric nowrap  |
- * | `date`        | `<time>` element, `datesLocaleOpts`                             | textEnd nowrap          |
- * | `datetime`    | as `date`, plus time part (`timesLocaleOpts`)                   | textEnd nowrap          |
- * | `bool`        | `boolTrueIcon`/`boolFalseIcon`; not sortable/searchable         | (internal icon styles)  |
- * | `email`       | soft line breaks around `@`                                     | –                       |
+ * | `string`      | tipo predefinito, 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 già in scala 0–100, `currPercLocaleOpts` + " %"     | textEnd numeric nowrap  |
+ * | `percDecimal` | percentuale in scala 0–1 (moltiplicata per 100)                 | textEnd numeric nowrap  |
+ * | `currency`    | formato valuta `Intl`, `params.currency`                        | textEnd numeric nowrap  |
+ * | `euro`        | come `currency`, EUR forzato                                    | textEnd numeric nowrap  |
+ * | `date`        | elemento `<time>`, `datesLocaleOpts`                            | textEnd nowrap          |
+ * | `datetime`    | come `date`, più la parte oraria (`timesLocaleOpts`)            | textEnd nowrap          |
+ * | `bool`        | `boolTrueIcon`/`boolFalseIcon`; non ordinabile/ricercabile      | (stili interni delle icone) |
+ * | `email`       | a capo morbidi attorno a `@`                                    | –                       |
  *
- * @param {JsonTableParams} params - Resolved params
+ * @param {JsonTableParams} params - Parametri risolti
  * @returns {Object<string, DataTypeDefinition>}
  *
  * @example
@@ -237,21 +237,21 @@ export function builtInDataTypes(params) {
 
 
 /**
- * Merges the custom data types (`params.dataTypes`) with the built-in ones.
+ * Unisce i data type personalizzati (`params.dataTypes`) a quelli predefiniti.
  *
- * A custom key matching a built-in type overrides only the given properties; a new key can
- * extend a built-in type via `inheritsFrom`.
+ * Una chiave personalizzata che corrisponde a un tipo predefinito ne sovrascrive solo le proprietà indicate; una nuova chiave può
+ * estendere un tipo predefinito tramite `inheritsFrom`.
  *
- * @param {JsonTableParams} params - Resolved params
- * @returns {Object<string, DataTypeDefinition>} The complete data types map
- * @throws {Error} When `inheritsFrom` refers to an unknown type
+ * @param {JsonTableParams} params - Parametri risolti
+ * @returns {Object<string, DataTypeDefinition>} La mappa completa dei data type
+ * @throws {Error} Quando `inheritsFrom` si riferisce a un tipo sconosciuto
  *
  * @example
  * const types = buildDataTypes({
  *   ...params,
  *   dataTypes: {
- *     num: { cellClass: 'text-end fw-bold' },                 // overrides only `cellClass` of the built-in `num`
- *     km: { inheritsFrom: 'num', render: v => `${v} km` }     // new type based on `num`
+ *     num: { cellClass: 'text-end fw-bold' },                 // sovrascrive solo `cellClass` del `num` predefinito
+ *     km: { inheritsFrom: 'num', render: v => `${v} km` }     // nuovo tipo basato su `num`
  *   }
  * });
  */