@massimo-cassandro/minimo 1.41.4 → 1.41.6

package/src/utilities/dom-builder-helpers/form-tags.js

@@ -3,17 +3,17 @@ import { randomId } from '../random-id.js';
 
 
 /**
- * Shared `.form-group` wrapper for the tag builders below: handles the
- * `condition` guard, `wrapperClass`, optional help text and `callback` in
- * one place, so each builder only needs to provide its own `children`
- * (typically the label + control).
+ * Wrapper `.form-group` condiviso dai builder di tag qui sotto: gestisce il controllo
+ * `condition`, `wrapperClass`, il testo di aiuto opzionale e `callback` in
+ * un unico punto, così che ogni builder debba fornire solo i propri `children`
+ * (tipicamente label + controllo).
  *
  * @param {Object} args
- * @param {boolean} [args.condition=true] - When false, returns `null` without building anything. (default: true)
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper. (default: null)
- * @param {string | HTMLElement | null} [args.help=null] - Optional help text. (default: null)
- * @param {Array<Object>} args.children - domBuilder children to render inside the `.form-group` (before the help text).
- * @returns {DomBuilderItem|null} The `.form-group` domBuilder item, or `null` when `condition` is false.
+ * @param {boolean} [args.condition=true] - Se false, restituisce `null` senza costruire nulla (default: true)
+ * @param {string | null} [args.wrapperClass=null] - classe opzionale da aggiungere al wrapper `.form-group` (default: null)
+ * @param {string | HTMLElement | null} [args.help=null] - Testo di aiuto opzionale (default: null)
+ * @param {Array<Object>} args.children - figli domBuilder da renderizzare dentro il `.form-group` (prima del testo di aiuto).
+ * @returns {DomBuilderItem|null} L'elemento domBuilder `.form-group`, oppure `null` quando `condition` è false.
  */
 function buildFormGroup({
   condition = true,
@@ -41,23 +41,23 @@ function buildFormGroup({
 
 
 /**
- * Input tag builder
+ * Builder del tag input
  *
  * @param {Object} args
- * @param {string} args.label - input label.
- * @param {string | null} args.name - input `name` attribute.
- * @param {string | null} args.id - `id` attribute.
- * @param {string | number | null} args.value - input `value` attribute.
- * @param {string | null} [args.type='text'] - input `type` attribute. (default: 'text')
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper. (default: null)
- * @param {string | null} [args.class=null] - optional class to be added to the `input`. (default: null)
- * @param {string | null} [args.classname=null] - Alias for `class`. (default: null)
- * @param {string | null} [args.className=null] - Alias for `class`. (default: null)
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything. (default: true)
- * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
- * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
- * @returns {DomBuilderItem|null} The `input` domBuilder item, or `null` when `condition` is false.
+ * @param {string} args.label - label dell'input.
+ * @param {string | null} args.name - attributo `name` dell'input.
+ * @param {string | null} args.id - attributo `id`.
+ * @param {string | number | null} args.value - attributo `value` dell'input.
+ * @param {string | null} [args.type='text'] - attributo `type` dell'input (default: 'text')
+ * @param {string | null} [args.wrapperClass=null] - classe opzionale da aggiungere al wrapper `.form-group` (default: null)
+ * @param {string | null} [args.class=null] - classe opzionale da aggiungere all'`input` (default: null)
+ * @param {string | null} [args.classname=null] - Alias di `class` (default: null)
+ * @param {string | null} [args.className=null] - Alias di `class` (default: null)
+ * @param {boolean} [args.condition=true] - Se false, la funzione restituisce `null` senza costruire nulla (default: true)
+ * @param {string | HTMLElement | null} args.help - Testo di aiuto opzionale.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Funzione callback opzionale.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Oggetto di attributi opzionale (default: {})
+ * @returns {DomBuilderItem|null} L'elemento domBuilder `input`, oppure `null` quando `condition` è false.
  */
 export function buildInput({
   label,
@@ -102,27 +102,27 @@ export function buildInput({
 }
 
 /**
- * select tag builder
+ * Builder del tag select
  *
  * @param {Object} args
- * @param {string} args.label - select label.
- * @param {string | null} args.name - select `name` attribute.
- * @param {string | null} args.id - `id` attribute.
- * @param {string | number | null} args.selectedValue - selected value (note: checked against 'options' values using loose equality '=='):
+ * @param {string} args.label - label della select.
+ * @param {string | null} args.name - attributo `name` della select.
+ * @param {string | null} args.id - attributo `id`.
+ * @param {string | number | null} args.selectedValue - valore selezionato (nota: confrontato con i valori di 'options' tramite uguaglianza debole '=='):
  * @param {Array<[string|number, string]> | Array<Record<string, string>> | Record<string, string> | null} args.options -
- *    options value/text pairs, as an array of two-element `[[value, text], ...]` arrays,
- *    as an array of objects `[{somekey: value, somekey2: text},...]` objects, or as a single `{value: text, ...}` object
- * @param {boolean} [args.addEmptyOption=true] - When true, and empty option tag is added at top (default: true)
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper. (default: null)
- * @param {string | null} [args.class=null] - optional class to be added to the `input`. (default: null)
- * @param {string | null} [args.classname=null] - Alias for `class`. (default: null)
- * @param {string | null} [args.className=null] - Alias for `class`. (default: null)
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything. (default: true)
- * @param {boolean} [args.useBsClass=false] - When true, uses BS5 class (`form-select`) instead of `form-control` (default: false)
- * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
- * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
- * @returns {DomBuilderItem|null} The `input` domBuilder item, or `null` when `condition` is false.
+ *    coppie valore/testo delle opzioni, come array di array a due elementi `[[value, text], ...]`,
+ *    come array di oggetti `[{somekey: value, somekey2: text},...]`, oppure come singolo oggetto `{value: text, ...}`
+ * @param {boolean} [args.addEmptyOption=true] - Se true, viene aggiunto in cima un tag option vuoto (default: true)
+ * @param {string | null} [args.wrapperClass=null] - classe opzionale da aggiungere al wrapper `.form-group` (default: null)
+ * @param {string | null} [args.class=null] - classe opzionale da aggiungere all'`input` (default: null)
+ * @param {string | null} [args.classname=null] - Alias di `class` (default: null)
+ * @param {string | null} [args.className=null] - Alias di `class` (default: null)
+ * @param {boolean} [args.condition=true] - Se false, la funzione restituisce `null` senza costruire nulla (default: true)
+ * @param {boolean} [args.useBsClass=false] - Se true, usa la classe BS5 (`form-select`) al posto di `form-control` (default: false)
+ * @param {string | HTMLElement | null} args.help - Testo di aiuto opzionale.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Funzione callback opzionale.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Oggetto di attributi opzionale (default: {})
+ * @returns {DomBuilderItem|null} L'elemento domBuilder `input`, oppure `null` quando `condition` è false.
  */
 export function buildSelect({
   label,
@@ -146,7 +146,7 @@ export function buildSelect({
 
   id = id || randomId();
 
-  // normalizing options as an array of [value, text] pairs
+  // normalizza le opzioni come array di coppie [value, text]
   /** @type {Array<[string|number, string]>} */
   let optionsList = [];
 
@@ -198,23 +198,23 @@ export function buildSelect({
 
 
 /**
- * Checkbox tag builder
+ * Builder del tag checkbox
  *
  * @param {Object} args
- * @param {string} args.label - checkbox label.
- * @param {string | null} args.name - checkbox `name` attribute.
- * @param {string | null} args.id - `id` attribute.
- * @param {string | number | null} [args.value=1] - checkbox `value` attribute. (default: 1)
- * @param {boolean} [args.checked=false] - checkbox `checked` attribute. (default: false)
- * @param {boolean} [args.switch=false] - When true, the checkbox is rendered as a switch
- *    (`.form-switch` wrapper, `role="switch"` and the native `switch` attribute). (default: false)
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper (used only when `addFormGroup` is true). (default: null)
- * @param {boolean} [args.addFormGroup=true] - When true, wraps the checkbox in a `.form-group` element. (default: true)
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything. (default: true)
- * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
- * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
- * @returns {DomBuilderItem|null} The `.form-check` (or `.form-group`-wrapped) domBuilder item, or `null` when `condition` is false.
+ * @param {string} args.label - label della checkbox.
+ * @param {string | null} args.name - attributo `name` della checkbox.
+ * @param {string | null} args.id - attributo `id`.
+ * @param {string | number | null} [args.value=1] - attributo `value` della checkbox (default: 1)
+ * @param {boolean} [args.checked=false] - attributo `checked` della checkbox (default: false)
+ * @param {boolean} [args.switch=false] - Se true, la checkbox viene resa come switch
+ *    (wrapper `.form-switch`, `role="switch"` e attributo nativo `switch`) (default: false)
+ * @param {string | null} [args.wrapperClass=null] - classe opzionale da aggiungere al wrapper `.form-group` (usata solo quando `addFormGroup` è true) (default: null)
+ * @param {boolean} [args.addFormGroup=true] - Se true, racchiude la checkbox in un elemento `.form-group` (default: true)
+ * @param {boolean} [args.condition=true] - Se false, la funzione restituisce `null` senza costruire nulla (default: true)
+ * @param {string | HTMLElement | null} args.help - Testo di aiuto opzionale.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Funzione callback opzionale.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Oggetto di attributi opzionale (default: {})
+ * @returns {DomBuilderItem|null} L'elemento domBuilder `.form-check` (o racchiuso in `.form-group`), oppure `null` quando `condition` è false.
  */
 export function buildCheckbox({
   label,
@@ -236,14 +236,14 @@ export function buildCheckbox({
   }
 
   /*
-  <div class="form-group"> <- optional
+  <div class="form-group"> <- opzionale
     <div class="form-check">
       <input type="checkbox" id="..." name="..." class="form-check-input" value="1">
       <label for="..." class="form-label">...</label>
     </div>
   </div>
 
-  <div class="form-group"> <- optional
+  <div class="form-group"> <- opzionale
     <div class="form-check form-switch">
       <input class="form-check-input" type="checkbox" role="switch" switch id="my-switch">
       <label class="form-label" for="my-switch">My label</label>
@@ -265,7 +265,7 @@ export function buildCheckbox({
           value: value,
           name: name,
           checked: checked,
-          // native switch control (WebKit only for now), with the css fallback elsewhere
+          // controllo switch nativo (per ora solo WebKit), con ripiego css altrove
           ...(isSwitch? {role: 'switch', switch: ''} : {})
         },
         callback: callback
@@ -289,23 +289,23 @@ export function buildCheckbox({
 
 
 /**
- * Textarea tag builder
+ * Builder del tag textarea
  *
  * @param {Object} args
- * @param {string} args.label - textarea label.
- * @param {string | null} args.name - textarea `name` attribute.
- * @param {string | null} args.id - `id` attribute.
- * @param {string | number | null} args.value - textarea content.
- * @param {boolean} [args.autosize=true] - adds `autosize` class (default: true)
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper. (default: null)
- * @param {string | null} [args.class=null] - optional class to be added to the textarea element. (default: null)
- * @param {string | null} [args.classname=null] - Alias for `class`. (default: null)
- * @param {string | null} [args.className=null] - Alias for `class`. (default: null)
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything. (default: true)
- * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
- * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
- * @returns {DomBuilderItem|null} The `textarea` domBuilder item, or `null` when `condition` is false.
+ * @param {string} args.label - label della textarea.
+ * @param {string | null} args.name - attributo `name` della textarea.
+ * @param {string | null} args.id - attributo `id`.
+ * @param {string | number | null} args.value - contenuto della textarea.
+ * @param {boolean} [args.autosize=true] - aggiunge la classe `autosize` (default: true)
+ * @param {string | null} [args.wrapperClass=null] - classe opzionale da aggiungere al wrapper `.form-group` (default: null)
+ * @param {string | null} [args.class=null] - classe opzionale da aggiungere all'elemento textarea (default: null)
+ * @param {string | null} [args.classname=null] - Alias di `class` (default: null)
+ * @param {string | null} [args.className=null] - Alias di `class` (default: null)
+ * @param {boolean} [args.condition=true] - Se false, la funzione restituisce `null` senza costruire nulla (default: true)
+ * @param {string | HTMLElement | null} args.help - Testo di aiuto opzionale.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Funzione callback opzionale.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Oggetto di attributi opzionale (default: {})
+ * @returns {DomBuilderItem|null} L'elemento domBuilder `textarea`, oppure `null` quando `condition` è false.
  */
 export function buildTextarea({
   label,
@@ -349,21 +349,21 @@ export function buildTextarea({
 }
 
 /**
- * Fake field (plain text showed as an input field)
+ * Campo finto (testo semplice mostrato come campo input)
  *
  * @param {Object} args
  * @param {string} args.label - label.
- * @param {string | number | null} args.value - text content.
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper. (default: null)
- * @param {boolean} [args.noBorder=true] - adds `no-border` class. (default: true)
- * @param {string | null} [args.class=null] - optional class to be added to the fake field. (default: null)
- * @param {string | null} [args.classname=null] - Alias for `class`. (default: null)
- * @param {string | null} [args.className=null] - Alias for `class`. (default: null)
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything. (default: true)
- * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
- * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
- * @returns {DomBuilderItem|null} The fake field domBuilder item, or `null` when `condition` is false.
+ * @param {string | number | null} args.value - contenuto testuale.
+ * @param {string | null} [args.wrapperClass=null] - classe opzionale da aggiungere al wrapper `.form-group` (default: null)
+ * @param {boolean} [args.noBorder=true] - aggiunge la classe `no-border` (default: true)
+ * @param {string | null} [args.class=null] - classe opzionale da aggiungere al campo finto (default: null)
+ * @param {string | null} [args.classname=null] - Alias di `class` (default: null)
+ * @param {string | null} [args.className=null] - Alias di `class` (default: null)
+ * @param {boolean} [args.condition=true] - Se false, la funzione restituisce `null` senza costruire nulla (default: true)
+ * @param {string | HTMLElement | null} args.help - Testo di aiuto opzionale.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Funzione callback opzionale.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Oggetto di attributi opzionale (default: {})
+ * @returns {DomBuilderItem|null} L'elemento domBuilder del campo finto, oppure `null` quando `condition` è false.
  */
 export function buildFakeField({
   label,
@@ -402,20 +402,20 @@ export function buildFakeField({
 
 
 /**
- * button tag builder
+ * Builder del tag button
  *
  * @param {Object} args
- * @param {string|HTMLElement|Array<DomBuilderItem>} args.content - button content. When an array of
- *   domBuilder items is passed, it is rendered via `children` instead of `content`.
- * @param {string} [args.type=button] - button type. (default: 'button')
- * @param {string | null} args.id - `id` attribute.
- * @param {string | null} [args.class=null] - optional class to be added to the button element. (default: null)
- * @param {string | null} [args.classname=null] - Alias for `class`. (default: null)
- * @param {string | null} [args.className=null] - Alias for `class`. (default: null)
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything. (default: true)
- * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
- * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
- * @returns {DomBuilderItem|null} The `button` domBuilder item, or `null` when `condition` is false.
+ * @param {string|HTMLElement|Array<DomBuilderItem>} args.content - contenuto del button. Quando viene passato un array di
+ *   elementi domBuilder, viene renderizzato tramite `children` invece di `content`.
+ * @param {string} [args.type=button] - tipo del button (default: 'button')
+ * @param {string | null} args.id - attributo `id`.
+ * @param {string | null} [args.class=null] - classe opzionale da aggiungere all'elemento button (default: null)
+ * @param {string | null} [args.classname=null] - Alias di `class` (default: null)
+ * @param {string | null} [args.className=null] - Alias di `class` (default: null)
+ * @param {boolean} [args.condition=true] - Se false, la funzione restituisce `null` senza costruire nulla (default: true)
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Funzione callback opzionale.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Oggetto di attributi opzionale (default: {})
+ * @returns {DomBuilderItem|null} L'elemento domBuilder `button`, oppure `null` quando `condition` è false.
  */
 export function buildButton({
   content,

package/src/utilities/dom-builder-helpers/picture-tag.js

@@ -3,8 +3,8 @@ import { classnames } from '../classnames.js';
 
 /**
  * @typedef {Object} PictureSizeEntry
- * @property {number} [from] - Breakpoint (px) the size applies from (`width >=` media condition); omitted in the (single) mobile-first default entry.
- * @property {number | [number, number]} size - Rendered width (px, height computed with `ratio`, if set) or explicit `[width, height]` pair (px).
+ * @property {number} [from] - Breakpoint (px) da cui si applica la size (condizione media `width >=`); omesso nell'(unica) entry predefinita mobile-first.
+ * @property {number | [number, number]} size - Larghezza renderizzata (px, altezza calcolata con `ratio`, se impostato) oppure coppia esplicita `[width, height]` (px).
  */
 
 // TODO aggiungere compatibilità con immagini Unsplash basate su imgix
@@ -13,25 +13,25 @@ import { classnames } from '../classnames.js';
 // per altri servizi con parametri diversi (es. imgix/Unsplash)
 
 /**
- * Creates a `picture` domBuilder item for an image rendered through the viewer.
+ * Crea un elemento domBuilder `picture` per un'immagine servita tramite il viewer.
  *
- * Every `source`/`img` `srcset` is built with width descriptors (`w`): for each entry
- * of `sizes`, a candidate is generated for every integer density from 1 to `dpr`.
- * The `sizes` attribute is built mobile-first: the entry without `from` is the
- * default, and every other entry applies from its `from` breakpoint up, as a
- * `(width >= …)` media condition (range syntax).
+ * Ogni `srcset` di `source`/`img` è costruito con descrittori di larghezza (`w`): per ogni entry
+ * di `sizes` viene generato un candidato per ogni densità intera da 1 a `dpr`.
+ * L'attributo `sizes` è costruito in modalità mobile-first: l'entry senza `from` è il
+ * default e ogni altra entry si applica dal proprio breakpoint `from` in su, come
+ * condizione media `(width >= …)` (sintassi range).
  *
  * @example
- * // fixed-width thumb (250px, 1x and 2x candidates); with no `ratio` nor explicit
- * // heights, the viewer gets a width-only resize (bb=250x) and the `img` has no
- * // `height` attribute
- * buildPictureTag({ baseSrc: 'https://img-viewer.example.com/abc123', alt: '…' });
+ * // thumb a larghezza fissa (250px, candidati 1x e 2x); senza `ratio` né altezze
+ * // esplicite, il viewer riceve un resize solo in larghezza (bb=250x) e l'`img` non ha
+ * // l'attributo `height`
+ * buildPictureTag({ baseSrc: 'https://img-viewer.example.com/abc123', alt: '...' });
  * // sizes="250px", srcset="… 250w, … 500w"
  *
  * @example
- * // responsive image: 250px by default, 500px from 576px, 800px from 992px.
- * // NB: the entry without `from` is the mobile-first default (exactly one is
- * // expected); a bare number or [width, height] pair is a shorthand for it
+ * // immagine responsive: 250px di default, 500px da 576px, 800px da 992px.
+ * // NB: l'entry senza `from` è il default mobile-first (ne è attesa esattamente
+ * // una); un numero semplice o una coppia [width, height] ne è la scorciatoia
  * buildPictureTag({
  *   baseSrc,
  *   sizes: [250, { from: 576, size: 500 }, { from: 992, size: 800 }],
@@ -39,7 +39,7 @@ import { classnames } from '../classnames.js';
  * // sizes="(width >= 992px) 800px, (width >= 576px) 500px, 250px"
  *
  * @example
- * // custom ratio for numeric sizes and candidates up to 3x
+ * // ratio personalizzato per le size numeriche e candidati fino a 3x
  * buildPictureTag({
  *   baseSrc,
  *   sizes: [250, { from: 768, size: 500 }],
@@ -48,19 +48,19 @@ import { classnames } from '../classnames.js';
  * });
  *
  * @example
- * // different aspect ratio per breakpoint: explicit [width, height] pairs
- * // (can be mixed with numeric sizes, which use `ratio`)
+ * // aspect ratio diverso per breakpoint: coppie [width, height] esplicite
+ * // (si possono mescolare con size numeriche, che usano `ratio`)
  * buildPictureTag({
  *   baseSrc,
- *   sizes: [[250, 250], { from: 576, size: [800, 450] }], // square on mobile, 16:9 on desktop
+ *   sizes: [[250, 250], { from: 576, size: [800, 450] }], // quadrato su mobile, 16:9 su desktop
  * });
  *
  * @example
- * // dev environment (no avif) and above-the-fold img (no loading="lazy")
+ * // ambiente di sviluppo (senza avif) e img above-the-fold (senza loading="lazy")
  * buildPictureTag({ baseSrc, devMode: true, lazy: false });
  *
  * @example
- * // onLoad callback: reveal the image once it has finished loading
+ * // callback onLoad: mostra l'immagine al termine del caricamento
  * buildPictureTag({
  *   baseSrc,
  *   imgExtraClass: 'img-loading',
@@ -68,24 +68,24 @@ import { classnames } from '../classnames.js';
  * });
  *
  * @param {Object} args
- * @param {string} args.baseSrc - Image base URL (viewer endpoint); its query params are preserved.
- * @param {(number | [number, number] | PictureSizeEntry)[]} [args.sizes=[250]] - Rendered image sizes, in any order. Each entry is a `{from, size}` object (see {@link PictureSizeEntry}); a bare number or `[width, height]` pair is a shorthand for the mobile-first default entry (the one without `from`), expected exactly once. (default: [250])
- * @param {number|null} [args.ratio=null] - Default aspect ratio (width / height, as in the CSS `aspect-ratio` property) used to compute the height of numeric sizes. When null, no height is computed: the height-related output (`height` attribute, height in the `bb` param) is omitted and the viewer preserves the image's own ratio. (default: null)
- * @param {number} [args.dpr=2] - Maximum pixel density (integer): `srcset` candidates are generated for every density from 1 to `dpr`. (default: 2)
- * @param {[string, string|number][]} [args.img_params=[['q','60']]] - Query params (`[name, value]` pairs) added to every generated URL. (default: [['q','60']])
- * @param {string[]} [args.formats=['avif','webp','pjpg']] - Image formats: the last one is used for the `img` fallback element, the others for the `source` elements. (default: ['avif','webp','pjpg'])
- * @param {boolean} [args.devMode=false] - When true, `avif` is excluded from `formats` (not supported by the local dev environment). (default: false)
- * @param {boolean} [args.lazy=true] - When true, the `img` element gets `loading="lazy"`. (default: true)
- * @param {'high'|'low'|null} [args.fetchpriority=null] - `fetchpriority` attribute for the `img` element: use `high` for the LCP/above-the-fold image (typically with `lazy: false`). When null the attribute is omitted (browser default `auto`). (default: null)
- * @param {((img: HTMLImageElement) => void) | null} [args.onLoad=null] - Called once the image has finished loading, receiving the `img` element (called immediately if the image is already complete). (default: null)
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything. (default: true)
- * @param {boolean} [args.legacyMediaSyntax=false] - When true, the `sizes` media conditions use `(min-width: …)` instead of the range syntax `(width >= …)`, for older browsers (pre Chrome/Edge 104, Firefox 102, Safari 16.4). (default: false)
- * @param {string|null} [args.pictureExtraClass=null] - Extra class(es) for the `picture` element. (default: null)
- * @param {Object<string, *>} [args.pictureExtraAttrs={}] - Extra attributes for the `picture` element. (default: {})
- * @param {string|null} [args.imgExtraClass=null] - Extra class(es) for the `img` element. (default: null)
- * @param {Object<string, *>} [args.imgExtraAttrs={}] - Extra attributes for the `img` element. (default: {})
- * @param {string} [args.alt=''] - `alt` text for the `img` element. (default: '')
- * @returns {DomBuilderItem|null} The `picture` domBuilder item, or `null` when `baseSrc` is missing or `condition` is false.
+ * @param {string} args.baseSrc - URL base dell'immagine (endpoint del viewer); i suoi parametri di query vengono conservati.
+ * @param {(number | [number, number] | PictureSizeEntry)[]} [args.sizes=[250]] - Dimensioni renderizzate dell'immagine, in qualsiasi ordine. Ogni entry è un oggetto `{from, size}` (vedi {@link PictureSizeEntry}); un numero semplice o una coppia `[width, height]` è la scorciatoia per l'entry predefinita mobile-first (quella senza `from`), attesa esattamente una volta (default: [250])
+ * @param {number|null} [args.ratio=null] - Aspect ratio predefinito (larghezza / altezza, come nella proprietà CSS `aspect-ratio`) usato per calcolare l'altezza delle size numeriche. Se null, l'altezza non viene calcolata: gli output legati all'altezza (attributo `height`, altezza nel parametro `bb`) vengono omessi e il viewer mantiene il ratio originale dell'immagine (default: null)
+ * @param {number} [args.dpr=2] - Densità di pixel massima (intero): i candidati di `srcset` vengono generati per ogni densità da 1 a `dpr` (default: 2)
+ * @param {[string, string|number][]} [args.img_params=[['q','60']]] - Parametri di query (coppie `[name, value]`) aggiunti a ogni URL generato (default: [['q','60']])
+ * @param {string[]} [args.formats=['avif','webp','pjpg']] - Formati dell'immagine: l'ultimo viene usato per l'elemento `img` di fallback, gli altri per gli elementi `source` (default: ['avif','webp','pjpg'])
+ * @param {boolean} [args.devMode=false] - Se true, `avif` viene escluso da `formats` (non supportato dall'ambiente di sviluppo locale) (default: false)
+ * @param {boolean} [args.lazy=true] - Se true, l'elemento `img` riceve `loading="lazy"` (default: true)
+ * @param {'high'|'low'|null} [args.fetchpriority=null] - Attributo `fetchpriority` per l'elemento `img`: usare `high` per l'immagine LCP/above-the-fold (tipicamente con `lazy: false`). Se null l'attributo viene omesso (default del browser `auto`) (default: null)
+ * @param {((img: HTMLImageElement) => void) | null} [args.onLoad=null] - Chiamata al termine del caricamento dell'immagine, riceve l'elemento `img` (chiamata subito se l'immagine è già completa) (default: null)
+ * @param {boolean} [args.condition=true] - Se false, la funzione restituisce `null` senza costruire nulla (default: true)
+ * @param {boolean} [args.legacyMediaSyntax=false] - Se true, le condizioni media di `sizes` usano `(min-width: …)` invece della sintassi range `(width >= …)`, per i browser più vecchi (precedenti a Chrome/Edge 104, Firefox 102, Safari 16.4) (default: false)
+ * @param {string|null} [args.pictureExtraClass=null] - Classe/i extra per l'elemento `picture`. (default: null)
+ * @param {Object<string, *>} [args.pictureExtraAttrs={}] - Attributi extra per l'elemento `picture`. (default: {})
+ * @param {string|null} [args.imgExtraClass=null] - Classe/i extra per l'elemento `img`. (default: null)
+ * @param {Object<string, *>} [args.imgExtraAttrs={}] - Attributi extra per l'elemento `img`. (default: {})
+ * @param {string} [args.alt=''] - Testo `alt` per l'elemento `img`. (default: '')
+ * @returns {DomBuilderItem|null} L'elemento domBuilder `picture`, oppure `null` quando `baseSrc` manca o `condition` è false.
  */
 export function buildPictureTag({
   baseSrc,

package/src/utilities/enable-submit-btns.js

@@ -1,6 +1,6 @@
 /*! minimo - Enable Submit Buttons */
 /**
- * Re-enables all submit and non-disabled button elements within the given context.
+ * Riabilita tutti i pulsanti submit e i pulsanti non disabilitati all'interno del contesto indicato.
  * @param {Document | Element} [context=document] (default: document)
  * @returns {void}
  */

package/src/utilities/escape-html.js

@@ -14,14 +14,14 @@ const ESCAPE_RE = /[&"'<>]/g;
 const UNESCAPE_RE = /&amp;|&quot;|&#039;|&lt;|&gt;/g;
 
 /**
- * Escapes special HTML characters in a string.
+ * Esegue l'escape dei caratteri HTML speciali di una stringa.
  * @param {string | null | undefined} str
  * @returns {string}
  */
 export const escapeHTML = str => str?.replace(ESCAPE_RE, m => ESCAPE_MAP[m]) ?? '';
 
 /**
- * Unescapes HTML entities back to their original characters.
+ * Riconverte le entità HTML nei caratteri originali.
  * @param {string | null | undefined} str
  * @returns {string}
  */

package/src/utilities/generate-pwd.js

@@ -1,10 +1,10 @@
 /*! minimo - Generate Password */
 /**
- * Generates a random password using uppercase letters and digits,
- * excluding visually ambiguous characters (O, I, 0).
+ * Genera una password casuale con lettere maiuscole e cifre,
+ * escludendo i caratteri visivamente ambigui (O, I, 0).
  *
- * @param {number} [min_length=8] - Minimum password length (matches `minlength` attribute). (default: 8)
- * @returns {string} The generated password.
+ * @param {number} [min_length=8] - Lunghezza minima della password (corrisponde all'attributo `minlength`) (default: 8)
+ * @returns {string} La password generata.
  */
 export function generatePwd(min_length = 8) {
 

package/src/utilities/linked-dates.js

@@ -2,23 +2,23 @@
 /*! minimo - Linked Dates */
 
 /**
- * Links date/datetime-local input fields so that one field constrains
- * the min/max of another.
+ * Collega i campi input date/datetime-local in modo che un campo vincoli
+ * il min/max di un altro.
  *
- * The `data-max` attribute on a date field must contain the `id` of the field
- * whose value sets the `max` constraint of the current field (start date).
- * The `data-min` attribute on a date field must contain the `id` of the field
- * whose value sets the `min` constraint of the current field (end date).
+ * L'attributo `data-max` di un campo data deve contenere l'`id` del campo
+ * il cui valore imposta il vincolo `max` del campo corrente (data di inizio).
+ * L'attributo `data-min` di un campo data deve contenere l'`id` del campo
+ * il cui valore imposta il vincolo `min` del campo corrente (data di fine).
  *
- * If the linked field is disabled, the constraint is removed on focus
- * and restored when the linked field is re-enabled.
+ * Se il campo collegato è disabilitato, il vincolo viene rimosso al focus
+ * e ripristinato quando il campo collegato viene riabilitato.
  *
- * @param {Document|Element} context - root element to search within (default: document)
+ * @param {Document|Element} context - elemento radice in cui cercare (default: document)
  * @returns {void}
  */
 export function linkedDates(context = document) {
 
-  // start date fields: constrained by a max value from a linked field
+  // campi data di inizio: vincolati da un valore max proveniente da un campo collegato
   context.querySelectorAll('input[type="date"][data-max], input[type="datetime-local"][data-max]').forEach(el => {
     const maxId = /** @type {HTMLInputElement} */ (el).dataset.max;
     let linked_field = maxId ? document.getElementById(maxId) : null;
@@ -30,7 +30,7 @@ export function linkedDates(context = document) {
         el.setAttribute('max', /** @type {HTMLInputElement} */ (linked_field).value);
       });
 
-      // remove max if the linked field is disabled; restore it when re-focused enabled
+      // rimuove max se il campo collegato è disabilitato; lo ripristina quando riceve di nuovo il focus da abilitato
       el.addEventListener('focus', () => {
         if(/** @type {HTMLInputElement} */ (linked_field).disabled) {
           el.removeAttribute('max');
@@ -41,7 +41,7 @@ export function linkedDates(context = document) {
     }
   });
 
-  // end date fields: constrained by a min value from a linked field
+  // campi data di fine: vincolati da un valore min proveniente da un campo collegato
   context.querySelectorAll('input[type="date"][data-min], input[type="datetime-local"][data-min]').forEach(el => {
     const minId = /** @type {HTMLInputElement} */ (el).dataset.min;
     let linked_field = minId ? document.getElementById(minId) : null;
@@ -51,7 +51,7 @@ export function linkedDates(context = document) {
         el.setAttribute('min', /** @type {HTMLInputElement} */ (linked_field).value);
       });
 
-      // remove min if the linked field is disabled; restore it when re-focused enabled
+      // rimuove min se il campo collegato è disabilitato; lo ripristina quando riceve di nuovo il focus da abilitato
       el.addEventListener('focus', () => {
         if(/** @type {HTMLInputElement} */ (linked_field).disabled) {
           el.removeAttribute('min');

package/src/utilities/parse-file-size.js

@@ -2,16 +2,16 @@
 /*! minimo - Parse File Size */
 
 /**
- * Converts a file size in bytes to a human readable string,
- * using the most appropriate unit (bytes, KB, MB or GB).
+ * Converte una dimensione di file in byte in una stringa leggibile,
+ * usando l'unità più appropriata (bytes, KB, MB o GB).
  *
  * @example
  * parseFileSize(1536);      // "1.5 KB"
  * parseFileSize(10485760);  // "10 MB"
  *
- * @param {number} bytes - file size in bytes
- * @param {number} [decimals=1] - max number of decimal digits (default: 1)
- * @returns {string} formatted size (e.g. "1.5 MB")
+ * @param {number} bytes - dimensione del file in byte
+ * @param {number} [decimals=1] - numero massimo di cifre decimali (default: 1)
+ * @returns {string} dimensione formattata (es. "1.5 MB")
  */
 export function parseFileSize(bytes, decimals = 1) {
 
@@ -28,6 +28,6 @@ export function parseFileSize(bytes, decimals = 1) {
 
   const value = bytes / Math.pow(k, exp);
 
-  // \u202f = narrow no-break space
+  // \u202f = narrow no-break space (spazio sottile non separabile)
   return `${parseFloat(value.toFixed(decimals))}\u202f${units[exp]}`;
 }

package/src/utilities/random-id.js

@@ -2,13 +2,13 @@
 /*! minimo - Random Id */
 
 /**
- * Generates a random ID string.
- * @returns {string} Base64-encoded random string
+ * Genera una stringa ID casuale.
+ * @returns {string} Stringa casuale codificata in Base64
  */
 export function randomId() {
   const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_';
   const bytes = crypto.getRandomValues(new Uint8Array(12));
-  return chars[bytes[0] % 52] // first item is from first 52 chars (A-Za-z)
+  return chars[bytes[0] % 52] // il primo carattere proviene dai primi 52 (A-Za-z)
     + Array.from(bytes.slice(1), b => chars[b % 63]).join('');
 }