@massimo-cassandro/minimo 1.27.2 → 1.27.4

package/charts/src/helpers/chart-utils.js

@@ -5,7 +5,7 @@
 /**
  * Tronca un numero a un numero specifico di decimali.
  * @param {number} number - Il numero da troncare.
- * @param {number} [decimals=4] - Il numero di decimali da mantenere.
+ * @param {number} [decimals=4] - Il numero di decimali da mantenere. (default: 4)
  * @returns {number} Il numero troncato.
  */
 export function truncateDecimal(number, decimals = 4) {
@@ -50,14 +50,14 @@ export function polarToCartesianString(degrees_angle, cx, cy, circleRadius) {
  * Lo `start_angle` è il punto di inizio e `percentage` è la lunghezza percentuale dell'arco rispetto a `max_angle`.
  *
  * @param {Object} options - Opzioni di configurazione.
- * @param {number} [options.start_angle=0] - Angolo di partenza in gradi.
+ * @param {number} [options.start_angle=0] - Angolo di partenza in gradi. (default: 0)
  * @param {number|null} options.percentage - Lunghezza dell'arco in percentuale (da 0 a 1).
- * @param {number} [options.max_arc=360] - L'estensione massima dell'arco in gradi.
+ * @param {number} [options.max_arc=360] - L'estensione massima dell'arco in gradi. (default: 360)
  * @param {Object} options.center - Coordinate del centro.
  * @param {number|null} options.center.x - Coordinata X del centro.
  * @param {number|null} options.center.y - Coordinata Y del centro.
  * @param {number|null} options.radius - Raggio dell'arco.
- * @param {boolean} [options.clockwise=true] - Direzione oraria se true.
+ * @param {boolean} [options.clockwise=true] - Direzione oraria se true. (default: true)
  * @returns {{arc_length: number, start: {x: number, y: number}, end: {x: number, y: number}}} Coordinate di inizio, fine e lunghezza.
  */
 export function calcArcCoords(options) {
@@ -141,9 +141,9 @@ export function getElementFromContainer(container) {
 /**
  * Analizza il contenitore e restituisce informazioni sulle sue dimensioni, eseguendo alcune azioni di base.
  * @param {Object} params - Parametri di input.
- * @param {string|Element|null} [params.container=null] - Il contenitore del grafico.
- * @param {number|null} [params.width=null] - Larghezza predefinita (opzionale).
- * @param {number|null} [params.height=null] - Altezza predefinita (opzionale).
+ * @param {string|Element|null} [params.container=null] - Il contenitore del grafico. (default: null)
+ * @param {number|null} [params.width=null] - Larghezza predefinita (opzionale). (default: null)
+ * @param {number|null} [params.height=null] - Altezza predefinita (opzionale). (default: null)
  * @returns {[Element|null, number|null, number|null]} Un array contenente l'elemento, la larghezza e l'altezza.
  */
 export function parseContainer({ container = null, width = null, height = null }) {

package/charts/src/rating-display/index.js

@@ -15,115 +15,115 @@ import { rad30, getDisplayBackgroundPath, calcolaPuntoInterno, normalizeAngle, i
 export async function ratingDisplay({
 
   /**
-   * @param {boolean} [debug=false] - Modalità debug: se attiva mostra i riferimenti grafici (centri di rotazione, angoli) e i metadati data-debug-info.
+   * @param {boolean} [debug=false] - Modalità debug: se attiva mostra i riferimenti grafici (centri di rotazione, angoli) e i metadati data-debug-info. (default: false)
    */
   debug = false,
 
   /**
-   * @param {HTMLElement|string|null} [container=null] - Elemento DOM o selettore CSS dove iniettare il grafico. Se null, la funzione restituisce l'SVG come stringa.
+   * @param {HTMLElement|string|null} [container=null] - Elemento DOM o selettore CSS dove iniettare il grafico. Se null, la funzione restituisce l'SVG come stringa. (default: null)
    */
   container = null,
 
   /**
-   * @param {number|null} [width=null] - Larghezza del documento SVG. Obbligatoria se eseguito in ambiente Node.
+   * @param {number|null} [width=null] - Larghezza del documento SVG. Obbligatoria se eseguito in ambiente Node. (default: null)
    */
   width = null,
 
   /**
    * @param {number|function} [centerGap=r=>r/8] - Distanza tra il centro della circonferenza esterna e ciascuna delle circonferenze interne (*dA* e *dB* nella documentzione).
-   * Numero o funzione del raggio dato.
+   * Numero o funzione del raggio dato. (default: r => r/9)
    */
   centerGap = r => r/9,
 
   /**
    * @param {number|function} [scaleEndThickness=r=>r/8] - Spessore finale della scala (indicato con *s* nella documentazione).
-   * Numero o funzione del raggio dato.
+   * Numero o funzione del raggio dato. (default: r => r/5)
    */
   scaleEndThickness = r => r/5,
 
   /**
-   * @param {number} [portions=5] - Numero di porzioni (sezioni di colore) in cui è diviso il tachimetro.
+   * @param {number} [portions=5] - Numero di porzioni (sezioni di colore) in cui è diviso il tachimetro. (default: 5)
    */
   portions = 5,
 
   /**
    * @param {number} [portionGap=10] - Distanza tra una porzione e la successiva.
    * Corrisponde all'angolo in gradi tra le due semirette passanti per il centro della circonferenza esterna e i segmenti laterali delle porzioni.
-   * Indicato con *gamma* nella documentazione
+   * Indicato con *gamma* nella documentazione (default: 2)
    */
   portionGap = 2,
 
   /**
-   * @param {Object} [svgAttrs={}] - Attributi aggiuntivi (es. class, id) da applicare al tag SVG radice.
+   * @param {Object} [svgAttrs={}] - Attributi aggiuntivi (es. class, id) da applicare al tag SVG radice. (default: {})
    */
   svgAttrs = {},
 
   /**
-   * @param {Object} [displayBackgroundAttrs] - Attributi grafici (fill, stroke) per l'arco di sfondo esterno.
+   * @param {Object} [displayBackgroundAttrs] - Attributi grafici (fill, stroke) per l'arco di sfondo esterno. (default: { fill: 'none' })
    */
   displayBackgroundAttrs = {
     fill: 'none',
   },
 
   /**
-   * @param {number} [displayPadding=10] - Spazio tra il bordo del background e gli elementi interni del display.
+   * @param {number} [displayPadding=10] - Spazio tra il bordo del background e gli elementi interni del display. (default: 10)
    */
   displayPadding = 10,
 
   /**
-   * @param {number} [scaleStartValue=0] - Valore minimo della scala numerica da cui parte il calcolo della posizione.
+   * @param {number} [scaleStartValue=0] - Valore minimo della scala numerica da cui parte il calcolo della posizione. (default: 0)
    */
   scaleStartValue = 0,
 
   /**
-   * @param {boolean} [rodPositionForceCenter=false] - Se true, l'asticella punta sempre al centro della fascia; se false, segue la proporzione del valore esatto.
+   * @param {boolean} [rodPositionForceCenter=false] - Se true, l'asticella punta sempre al centro della fascia; se false, segue la proporzione del valore esatto. (default: false)
    */
   rodPositionForceCenter = false,
 
 
   /**
-   * @param {number|null} [value=null] - Valore numerico da rappresentare. Determina il colore e la posizione dell'asticella.
+   * @param {number|null} [value=null] - Valore numerico da rappresentare. Determina il colore e la posizione dell'asticella. (default: null)
    */
   value = null,
 
   /**
-   * @param {string[]|null} [scaleColors=null] - Array di colori per le porzioni della scala. Se null, usa i colori di default della chartInstance.
+   * @param {string[]|null} [scaleColors=null] - Array di colori per le porzioni della scala. Se null, usa i colori di default della chartInstance. (default: null)
    */
   scaleColors = null,
 
-  /** * @param {Object|null} [scaleAttrs=null] - Attributi SVG aggiuntivi applicati ai percorsi (path) delle porzioni della scala.
+  /** * @param {Object|null} [scaleAttrs=null] - Attributi SVG aggiuntivi applicati ai percorsi (path) delle porzioni della scala. (default: null)
    */
   scaleAttrs = null,
 
   /**
-   * @param {string|null} [scaleTicksColor=null] - Colore dei segni di separazione tra le porzioni. Se null, usa lo stesso colore della porzione adiacente.
+   * @param {string|null} [scaleTicksColor=null] - Colore dei segni di separazione tra le porzioni. Se null, usa lo stesso colore della porzione adiacente. (default: null)
    */
   scaleTicksColor = null,
 
   /**
-   * @param {Object} [rodAttrs] - Attributi per l'asticella indicatrice e il suo anello centrale.
+   * @param {Object} [rodAttrs] - Attributi per l'asticella indicatrice e il suo anello centrale. (default: { fill: '#000' })
    */
   rodAttrs = {
     fill: '#000'
   },
 
   /**
-   * @param {Object[]|null} [displayLabel=null] - Testo centrale sotto l'asticella. Array di max 2 oggetti: {label, font, fill, fontFilePath}.
+   * @param {Object[]|null} [displayLabel=null] - Testo centrale sotto l'asticella. Array di max 2 oggetti: {label, font, fill, fontFilePath}. (default: null)
    */
   displayLabel = null,
 
   /**
-   * @param {number} [displayLabelTopMargin=4] - Distanza verticale tra l'anello dell'asticella e la prima riga dell'etichetta.
+   * @param {number} [displayLabelTopMargin=4] - Distanza verticale tra l'anello dell'asticella e la prima riga dell'etichetta. (default: 4)
    */
   displayLabelTopMargin = 4,
 
   /**
-   * @param {number} [displayLabelRowGap=2] - Spazio verticale tra la prima e la seconda riga dell'etichetta principale.
+   * @param {number} [displayLabelRowGap=2] - Spazio verticale tra la prima e la seconda riga dell'etichetta principale. (default: 2)
    */
   displayLabelRowGap = 2,
 
   /**
-   * @param {Object[]|null} [miniDisplay=null] - Configurazione mini display secondari (max 2). Srray di uno o due oggetti
+   * @param {Object[]|null} [miniDisplay=null] - Configurazione mini display secondari (max 2). Srray di uno o due oggetti (default: null)
    * @param {string} miniDisplay[].position - Posizione: 'sx' | 'dx' (alias: 'left' | 'right').
    * @param {number} miniDisplay[].value - Valore numerico da rappresentare.
    * @param {string} miniDisplay[].type - Tipo di visualizzazione: 'gauge' (tachimetro) o 'value' (testo di `value`).
@@ -135,22 +135,22 @@ export async function ratingDisplay({
   miniDisplay = null,
 
   /**
-    * @param {number} [miniDisplayTopMargin=0] - Distanza verticale tra la base del display principale e l'inizio dei mini display.
+    * @param {number} [miniDisplayTopMargin=0] - Distanza verticale tra la base del display principale e l'inizio dei mini display. (default: 0)
    */
   miniDisplayTopMargin = 0,
 
   /**
-    * @param {number} [miniDisplayLabelTopMargin=0] - Distanza verticale tra la base dell'arco del mini display e le sue etichette.
+    * @param {number} [miniDisplayLabelTopMargin=0] - Distanza verticale tra la base dell'arco del mini display e le sue etichette. (default: 0)
    */
   miniDisplayLabelTopMargin = 0,
 
   /**
-   * @param {number} [miniDisplayLabelRowGap=2] - Distanza tra le righe di testo (mdLabel) del mini display.
+   * @param {number} [miniDisplayLabelRowGap=2] - Distanza tra le righe di testo (mdLabel) del mini display. (default: 2)
    */
   miniDisplayLabelRowGap = 2,
 
   /**
-   * @param {boolean} [animation=false] - Se true, abilita l'animazione dell'asticella (richiede implementazione specifica).
+   * @param {boolean} [animation=false] - Se true, abilita l'animazione dell'asticella (richiede implementazione specifica). (default: false)
    */
   animation = false,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.27.2",
+  "version": "1.27.4",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",

package/src/components/autocomplete/autocomplete-engine.js

@@ -98,7 +98,7 @@ export const ac_default_params = {
 
 /**
  * Initialises an autocomplete field using @tarekraafat/autocomplete.js.
- * @param {Record<string, any>} [params={}]
+ * @param {Record<string, any>} [params={}] (default: {})
  * @returns {void}
  */
 export default function (params = {}) {
@@ -284,8 +284,7 @@ export default function (params = {}) {
         }
       }); // end autoComplete
 
-      // TODO[epic=autocomplete]
-      // improve and make the callback invocation more efficient
+      // TODO improve and make the callback invocation more efficient
 
       // reset hidden field when the autocomplete value is cleared or mismatched
       const check_ac = () => {

package/src/components/modal-alert/modal-alert.js

@@ -100,26 +100,26 @@ const defaults = {
  * @typedef {Object} ModalAlertParams
  * @property {string} [type] - Dialog type: `success`, `error`, `warning`, `info`, or `confirm`.
  * @property {string | null} [title] - title text
- * @property {string | null} [mes] - text message (plain or html)
- * @property {((arg?: *) => void) | null} [callback] - optional callback dialog after user choice
- * @property {number | null} [timer] - timer for autoclose (ms). `null` for disable
- * @property {(() => void) | null} [onOpen] - optional callback on dialog open
- * @property {(() => void) | null} [onClose] - optional callback on dialog close
- * @property {string | null} [extraClass] - optional dialog extra class
- * @property {string} [okBtnText] - text for 'ok' button
+ * @property {string | null} [mes] - text message (plain or html) (default: null)
+ * @property {((arg?: *) => void) | null} [callback] - optional callback dialog after user choice (default: null)
+ * @property {number | null} [timer] - timer for autoclose (ms). `null` for disable (default: null, except type 'success' which defaults to 4000)
+ * @property {(() => void) | null} [onOpen] - optional callback on dialog open (default: null)
+ * @property {(() => void) | null} [onClose] - optional callback on dialog close (default: null)
+ * @property {string | null} [extraClass] - optional dialog extra class (default: null)
+ * @property {string} [okBtnText] - text for 'ok' button (default: 'OK')
  * @property {string} [okBtnClass] - alternative class for 'ok' button. It replaces the default one
- * @property {string} [cancelBtnText] - text for 'cancel' button
+ * @property {string} [cancelBtnText] - text for 'cancel' button (default: 'Annulla', type 'confirm' only)
  * @property {string} [cancelBtnClass] - alternative class for 'cancel' button. It replaces the default one
- * @property {boolean} [cancelBtnFocus] - true if the cancel button should be focused when the dialog box opens. It has no effect if an extraBtn is set
- * @property {string | null} [headingClass] - optional extra class for heading
- * @property {DomBuilderItem | null} [extraBtn] - optional extra button (as domBuilder object)
- * @property {boolean} [extraBtnFocus] - true if the extra button should be focused when the dialog box opens (overrides any focus assigned to the 'cancel' button)
- * @property {boolean} [animation] - if true, dialog will be animated
- * @property {boolean} [showMarks] - if true, mark iconswill be showed
- * @property {string | null} [textClass] - optional extra class for text
+ * @property {boolean} [cancelBtnFocus] - true if the cancel button should be focused when the dialog box opens. It has no effect if an extraBtn is set (default: true, type 'confirm' only)
+ * @property {string | null} [headingClass] - optional extra class for heading (default: null)
+ * @property {DomBuilderItem | null} [extraBtn] - optional extra button (as domBuilder object) (default: null)
+ * @property {boolean} [extraBtnFocus] - true if the extra button should be focused when the dialog box opens (overrides any focus assigned to the 'cancel' button) (default: true)
+ * @property {boolean} [animation] - if true, dialog will be animated (default: true)
+ * @property {boolean} [showMarks] - if true, mark iconswill be showed (default: true)
+ * @property {string | null} [textClass] - optional extra class for text (default: null)
  * @property {string | null} [icon] - Icon markup used for the dialog; defaults to the type's icon.
  * @property {string | null} [altIcon] - Alternate icon markup, used instead of `icon` when `useAltIcon` is `true`.
- * @property {boolean} [useAltIcon] - When `true`, uses `altIcon` instead of `icon` (e.g. the `danger` icon on a `warning` dialog, or the `warning` icon on a `confirm` dialog).
+ * @property {boolean} [useAltIcon] - When `true`, uses `altIcon` instead of `icon` (e.g. the `danger` icon on a `warning` dialog, or the `warning` icon on a `confirm` dialog). (default: false)
  */
 
 /**
@@ -133,29 +133,29 @@ const defaults = {
  * The base param type below is intentionally `object` (not `ModalAlertParams`): TypeScript only
  * expands dotted `@param` properties (needed for editor IntelliSense to list each property) when
  * the base type is the literal `object`; a named typedef there would error (TS8032).
- * @param {object} [params] - Dialog parameters (merged with defaults by type).
+ * @param {object} [params] - Dialog parameters (merged with defaults by type). (default: {})
  * @param {string} [params.type] - Dialog type: `success`, `error`, `warning`, `info`, or `confirm`.
- * @param {string | null} [params.extraClass] - optional dialog extra class
- * @param {(() => void) | null} [params.onOpen] - optional callback on dialog open
- * @param {(() => void) | null} [params.onClose] - optional callback on dialog close
- * @param {boolean} [params.animation] - if true, dialog will be animated
- * @param {boolean} [params.showMarks] - if true, mark icons will be showed
- * @param {((arg?: *) => void) | null} [params.callback] - optional callback dialog after user choice
- * @param {number | null} [params.timer] - timer for autoclose (ms). `null` for disable
+ * @param {string | null} [params.extraClass] - optional dialog extra class (default: null)
+ * @param {(() => void) | null} [params.onOpen] - optional callback on dialog open (default: null)
+ * @param {(() => void) | null} [params.onClose] - optional callback on dialog close (default: null)
+ * @param {boolean} [params.animation] - if true, dialog will be animated (default: true)
+ * @param {boolean} [params.showMarks] - if true, mark icons will be showed (default: true)
+ * @param {((arg?: *) => void) | null} [params.callback] - optional callback dialog after user choice (default: null)
+ * @param {number | null} [params.timer] - timer for autoclose (ms). `null` for disable (default: null, except type 'success' which defaults to 4000)
  * @param {string | null} [params.title] - title text
- * @param {string | null} [params.mes] - text message (plain or html)
- * @param {string | null} [params.headingClass] - optional extra class for heading
- * @param {string | null} [params.textClass] - optional extra class for text
+ * @param {string | null} [params.mes] - text message (plain or html) (default: null)
+ * @param {string | null} [params.headingClass] - optional extra class for heading (default: null)
+ * @param {string | null} [params.textClass] - optional extra class for text (default: null)
  * @param {string | null} [params.icon] - Icon markup used for the dialog; defaults to the type's icon.
  * @param {string | null} [params.altIcon] - Alternate icon markup, used instead of `icon` when `useAltIcon` is `true`.
- * @param {boolean} [params.useAltIcon] - When `true`, uses `altIcon` instead of `icon` (e.g. the `danger` icon on a `warning` dialog, or the `warning` icon on a `confirm` dialog).
- * @param {DomBuilderItem | null} [params.extraBtn] - optional extra button (as domBuilder object)
- * @param {boolean} [params.extraBtnFocus] - true if the extra button should be focused when the dialog box opens (overrides any focus assigned to the 'cancel' button)
- * @param {string} [params.okBtnText] - text for 'ok' button
+ * @param {boolean} [params.useAltIcon] - When `true`, uses `altIcon` instead of `icon` (e.g. the `danger` icon on a `warning` dialog, or the `warning` icon on a `confirm` dialog). (default: false)
+ * @param {DomBuilderItem | null} [params.extraBtn] - optional extra button (as domBuilder object) (default: null)
+ * @param {boolean} [params.extraBtnFocus] - true if the extra button should be focused when the dialog box opens (overrides any focus assigned to the 'cancel' button) (default: true)
+ * @param {string} [params.okBtnText] - text for 'ok' button (default: 'OK')
  * @param {string} [params.okBtnClass] - alternative class for 'ok' button. It replaces the default one
- * @param {string} [params.cancelBtnText] - text for 'cancel' button
+ * @param {string} [params.cancelBtnText] - text for 'cancel' button (default: 'Annulla', type 'confirm' only)
  * @param {string} [params.cancelBtnClass] - alternative class for 'cancel' button. It replaces the default one
- * @param {boolean} [params.cancelBtnFocus] - true if the cancel button should be focused when the dialog box opens. It has no effect if an extraBtn is set
+ * @param {boolean} [params.cancelBtnFocus] - true if the cancel button should be focused when the dialog box opens. It has no effect if an extraBtn is set (default: true, type 'confirm' only)
  * @returns {Promise<string | boolean | undefined>} Resolves when the dialog closes. If the
  *   dismissing button has a `data-malert-result` attribute, that string is used; otherwise, for
  *   `confirm` dialogs, resolves `true`/`false` for the OK/Cancel button; otherwise `undefined`.
@@ -311,7 +311,7 @@ export function modalAlert(params = {}) {
       let timeoutID;
 
       /**
-       * @param {HTMLElement | null} [btn]
+       * @param {HTMLElement | null} [btn] (default: null)
        * @returns {void}
        */
       const dialogDismiss = (btn = null) => {

package/src/components/modal-popup/modal-popup.js

@@ -39,27 +39,27 @@ function closeDialog(el) {
  * When multiple options conflict, the first applicable one in the list above takes precedence.
  *
  * @param {Object} params
- * @param {string | null} [params.dialogExtraClassName=null] - Extra class added to the dialog element.
- * @param {string | DomBuilderItem[] | null} [params.content=null] - Plain text, HTML, or a domBuilder array.
- * @param {string | null} [params.contentExtraClassName=null] - Extra class added to the content wrapper.
- * @param {HTMLElement | null} [params.triggerElement=null] - Optional element that triggered the popup; when set, `aria-haspopup`, `aria-controls` and `aria-expanded` are managed on it.
- * @param {boolean} [params.addFocus=true] - if true, dialog receives focus after opening
- * @param {string | null} [params.headerExtraClassName=null] - Extra class added to the header wrapper.
- * @param {string | null} [params.footerExtraClassName=null] - Extra class added to the footer wrapper.
- * @param {string | number | null} [params.dialogWidth=null] - optional dialog width value - if set, overrides main css custom prop
- * @param {string | number | null} [params.dialogMinWidth=null] - optional dialog min-width value - if set, overrides main css custom prop
- * @param {string | number | null} [params.dialogMaxWidth=null] - optional dialog max-width value - if set, overrides main css custom prop
- * @param {string | number | null} [params.dialogHeight=null] - optional dialog height value - if set, overrides main css custom prop
- * @param {string | number | null} [params.dialogMinHeight=null] - optional dialog min-height value - if set, overrides main css custom prop
- * @param {string | number | null} [params.dialogMaxHeight=null] - optional dialog max-height value - if set, overrides main css custom prop
- * @param {string | null} [params.iframeUrl=null] - URL to load in an iframe.
- * @param {string | null} [params.ajaxUrl=null] - URL for Ajax content loading.
- * @param {((el: HTMLDialogElement) => void) | null} [params.openCallback=null] - Called with the dialog element after opening, receives the dialog element (`openCallback(dialogEl)`).
- * @param {((el: HTMLDialogElement) => void) | null} [params.closeCallback=null] - Called with the dialog element just before it is removed, receives the dialog element (`closeCallback(dialogEl)`). NB: `dialogEl` is removed immediately after closing.
- * @param {((data: *, el: Element) => void) | null} [params.ajaxCallback=null] - Called with the Ajax response and the content element.
- * @param {boolean} [params.addScrollbarPadding=false] - Adds right padding to compensate for the scrollbar.
- * @param {string | DomBuilderItem[] | null} [params.headerContent=null] - Header content: plain text, HTML, or a domBuilder array.
- * @param {string | DomBuilderItem[] | null} [params.footerContent=null] - Footer content: plain text, HTML, or a domBuilder array.
+ * @param {string | null} [params.dialogExtraClassName=null] - Extra class added to the dialog element. (default: null)
+ * @param {string | DomBuilderItem[] | null} [params.content=null] - Plain text, HTML, or a domBuilder array. (default: null)
+ * @param {string | null} [params.contentExtraClassName=null] - Extra class added to the content wrapper. (default: null)
+ * @param {HTMLElement | null} [params.triggerElement=null] - Optional element that triggered the popup; when set, `aria-haspopup`, `aria-controls` and `aria-expanded` are managed on it. (default: null)
+ * @param {boolean} [params.addFocus=true] - if true, dialog receives focus after opening (default: true)
+ * @param {string | null} [params.headerExtraClassName=null] - Extra class added to the header wrapper. (default: null)
+ * @param {string | null} [params.footerExtraClassName=null] - Extra class added to the footer wrapper. (default: null)
+ * @param {string | number | null} [params.dialogWidth=null] - optional dialog width value - if set, overrides main css custom prop (default: null)
+ * @param {string | number | null} [params.dialogMinWidth=null] - optional dialog min-width value - if set, overrides main css custom prop (default: null)
+ * @param {string | number | null} [params.dialogMaxWidth=null] - optional dialog max-width value - if set, overrides main css custom prop (default: null)
+ * @param {string | number | null} [params.dialogHeight=null] - optional dialog height value - if set, overrides main css custom prop (default: null)
+ * @param {string | number | null} [params.dialogMinHeight=null] - optional dialog min-height value - if set, overrides main css custom prop (default: null)
+ * @param {string | number | null} [params.dialogMaxHeight=null] - optional dialog max-height value - if set, overrides main css custom prop (default: null)
+ * @param {string | null} [params.iframeUrl=null] - URL to load in an iframe. (default: null)
+ * @param {string | null} [params.ajaxUrl=null] - URL for Ajax content loading. (default: null)
+ * @param {((el: HTMLDialogElement) => void) | null} [params.openCallback=null] - Called with the dialog element after opening, receives the dialog element (`openCallback(dialogEl)`). (default: null)
+ * @param {((el: HTMLDialogElement) => void) | null} [params.closeCallback=null] - Called with the dialog element just before it is removed, receives the dialog element (`closeCallback(dialogEl)`). NB: `dialogEl` is removed immediately after closing. (default: null)
+ * @param {((data: *, el: Element) => void) | null} [params.ajaxCallback=null] - Called with the Ajax response and the content element. (default: null)
+ * @param {boolean} [params.addScrollbarPadding=false] - Adds right padding to compensate for the scrollbar. (default: false)
+ * @param {string | DomBuilderItem[] | null} [params.headerContent=null] - Header content: plain text, HTML, or a domBuilder array. (default: null)
+ * @param {string | DomBuilderItem[] | null} [params.footerContent=null] - Footer content: plain text, HTML, or a domBuilder array. (default: null)
  * @returns {HTMLDialogElement} The dialog element.
  */
 

package/src/components/overlay/overlay.js

@@ -3,8 +3,8 @@ import './overlay.css';
 
 /**
  * Appends an overlay `div` to the given context element.
- * @param {Element} [context=document.body]
- * @param {boolean} [scroll_lock=false] - When true, locks body scroll via `overflow-hidden`.
+ * @param {Element} [context=document.body] (default: document.body)
+ * @param {boolean} [scroll_lock=false] - When true, locks body scroll via `overflow-hidden`. (default: false)
  * @returns {void}
  */
 export function overlay(context = document.body, scroll_lock = false) {
@@ -16,7 +16,7 @@ export function overlay(context = document.body, scroll_lock = false) {
 
 /**
  * Removes the overlay element from the given context and re-enables body scroll.
- * @param {Element} [context=document.body]
+ * @param {Element} [context=document.body] (default: document.body)
  * @returns {void}
  */
 export function removeOverlay(context = document.body) {

package/src/components/sf-macro/sf-macro.js

@@ -1,19 +1,34 @@
 /*! minimo - Symfony Macro Manager */
 import './sf-macro.css';
 
+// TODO[epic=v2] in una v. 2 di minimo, rinominare wrapper_selector e row_selector in
+// wrapperClass e rowClass (NB: classi, non selettori, per uniformità con closeBtnClass/addBtnClass/containerClass
+// aggiunti sotto) e rendere tutti i parametri camelCase.
+// TODO[epic=v2] valutare se rendere opzionale, tramite parametro, l'importazione statica
+// di sf-macro.css qui sopra (questione lasciata in sospeso).
+
 /**
  * Initialises Symfony macro collection fields (repeatable fieldsets).
- * @param {Object} [options={}]
- * @param {string} [options.wrapper_selector='.sf-macro-wrapper'] - Selector for the outer wrapper element.
- * @param {string} [options.row_selector='.sf-macro-riga'] - Selector for each repeatable row.
- * @param {((newRow: Element | null, addBtn: Element | null) => void) | null} [options.add_callback=null] - Called after a row is added; receives the new row and the add button.
- * @param {(() => void) | null} [options.del_callback=null] - Called after a row is removed.
- * @param {boolean} [options.insertAtTop=false] - When true, new rows are inserted at the top.
+ * @param {Object} [options={}] (default: {})
+ * @param {string} [options.wrapper_selector='.sf-macro-wrapper'] - Selector for the outer wrapper element. (default: '.sf-macro-wrapper')
+ * @param {string} [options.row_selector='.sf-macro-riga'] - Selector for each repeatable row. (default: '.sf-macro-riga')
+ * @param {string} [options.closeBtnClass='sf-macro-close-btn'] - Class name of the row-remove button. (default: 'sf-macro-close-btn')
+ * @param {string} [options.addBtnClass='sf-macro-riga-add'] - Class name of the row-add button. (default: 'sf-macro-riga-add')
+ * @param {string} [options.containerClass='sf-macro-container'] - Class name of the rows container. (default: 'sf-macro-container')
+ * @param {((newRow: Element | null, addBtn: Element | null) => void) | null} [options.add_callback=null] - Called after a row is added; receives the new row and the add button. (default: null)
+ * @param {(() => void) | null} [options.del_callback=null] - Called after a row is removed. (default: null)
+ * @param {boolean} [options.insertAtTop=false] - When true, new rows are inserted at the top. (default: false)
  * @returns {void}
  */
 export function sf_macro({
   wrapper_selector = '.sf-macro-wrapper',
   row_selector = '.sf-macro-riga',
+  // Change closeBtnClass/addBtnClass/containerClass only if you don't want to use
+  // the default sf-macro.css: unused default classes are not stripped by this
+  // component, that cleanup is delegated to PurgeCSS (or equivalent) downstream.
+  closeBtnClass = 'sf-macro-close-btn',
+  addBtnClass = 'sf-macro-riga-add',
+  containerClass = 'sf-macro-container',
   add_callback = null,
   del_callback = null,
   insertAtTop = false
@@ -30,17 +45,17 @@ export function sf_macro({
     const target = /** @type {HTMLElement} */ (e.target);
 
     const action_btn = /** @type {HTMLElement | null} */ (
-      target.closest('.sf-macro-riga-add, .sf-macro-close-btn')
+      target.closest(`.${addBtnClass}, .${closeBtnClass}`)
     );
     if (!action_btn) return;
 
     const fset = /** @type {HTMLElement | null} */ (target.closest(wrapper_selector));
     if (!fset) return;
 
-    const macro_container = /** @type {HTMLElement | null} */ (fset.querySelector('.sf-macro-container'));
+    const macro_container = /** @type {HTMLElement | null} */ (fset.querySelector(`.${containerClass}`));
     if (!macro_container) return;
 
-    if(action_btn.matches('.sf-macro-riga-add')) {
+    if(action_btn.matches(`.${addBtnClass}`)) {
 
       const macro_template = macro_container.dataset.template ?? '';
       const righe_macro = macro_container.querySelectorAll(row_selector).length;

package/src/components/slide-up-down-toggle/slide-up-down-toggle.js

@@ -199,10 +199,10 @@ export function disposeSliding(target) {
  * CSS animates height to 0, then snaps display to none.
  *
  * @param {HTMLElement} target
- * @param {object} [options]
- * @param {boolean} [options.wrap=true] - auto-generates a wrapper `<div class="slide">` around `target` (see module docs above); when `false`, the `.slide` class is added directly to `target`.
+ * @param {object} [options] (default: {})
+ * @param {boolean} [options.wrap=true] - auto-generates a wrapper `<div class="slide">` around `target` (see module docs above); when `false`, the `.slide` class is added directly to `target`. (default: true)
  * @param {number} [options.duration] - overrides the `--slide-duration` CSS var (ms); if omitted, the CSS value is used.
- * @param {(() => void) | null} [options.callback] - invoked after the transition ends.
+ * @param {(() => void) | null} [options.callback] - invoked after the transition ends. (default: null)
  * @returns {Promise<void>}
  */
 export async function slideUp(target, options = {}) {
@@ -218,10 +218,10 @@ export async function slideUp(target, options = {}) {
  * display snaps to block, then CSS animates height from 0 (via @starting-style) to auto.
  *
  * @param {HTMLElement} target
- * @param {object} [options]
- * @param {boolean} [options.wrap=true] - auto-generates a wrapper `<div class="slide">` around `target` (see module docs above); when `false`, the `.slide` class is added directly to `target`.
+ * @param {object} [options] (default: {})
+ * @param {boolean} [options.wrap=true] - auto-generates a wrapper `<div class="slide">` around `target` (see module docs above); when `false`, the `.slide` class is added directly to `target`. (default: true)
  * @param {number} [options.duration] - overrides the `--slide-duration` CSS var (ms); if omitted, the CSS value is used.
- * @param {(() => void) | null} [options.callback] - invoked after the transition ends.
+ * @param {(() => void) | null} [options.callback] - invoked after the transition ends. (default: null)
  * @returns {Promise<void>}
  */
 export async function slideDown(target, options = {}) {
@@ -237,10 +237,10 @@ export async function slideDown(target, options = {}) {
  * Reads the current data-slide value on the slide element to decide direction.
  *
  * @param {HTMLElement} target
- * @param {object} [options]
- * @param {boolean} [options.wrap=true] - auto-generates a wrapper `<div class="slide">` around `target` (see module docs above); when `false`, the `.slide` class is added directly to `target`.
+ * @param {object} [options] (default: {})
+ * @param {boolean} [options.wrap=true] - auto-generates a wrapper `<div class="slide">` around `target` (see module docs above); when `false`, the `.slide` class is added directly to `target`. (default: true)
  * @param {number} [options.duration] - overrides the `--slide-duration` CSS var (ms); if omitted, the CSS value is used.
- * @param {(() => void) | null} [options.callback] - invoked after the transition ends.
+ * @param {(() => void) | null} [options.callback] - invoked after the transition ends. (default: null)
  * @returns {Promise<void>}
  */
 export async function slideToggle(target, options = {}) {

package/src/components/snackbar/snackbar.js

@@ -21,12 +21,12 @@ References
 /**
  * Displays a snackbar / toast notification using the Popover API.
  * @param {string} message - The message to display.
- * @param {Object} [options={}]
- * @param {string | null} [options.status=null] - Status variant: `danger`, `warning`, `info`, or `success`.
- * @param {number | false | null} [options.duration=4000] - Auto-close delay in ms; `false` or `null` disables auto-close.
- * @param {boolean} [options.close_btn=true] - Whether to show the close button.
- * @param {Function | null} [options.action=null] - Action callback.
- * @param {string | null} [options.action_text=null] - Label for the action button.
+ * @param {Object} [options={}] (default: {})
+ * @param {string | null} [options.status=null] - Status variant: `danger`, `warning`, `info`, or `success`. (default: null)
+ * @param {number | false | null} [options.duration=4000] - Auto-close delay in ms; `false` or `null` disables auto-close. (default: 4000)
+ * @param {boolean} [options.close_btn=true] - Whether to show the close button. (default: true)
+ * @param {Function | null} [options.action=null] - Action callback. (default: null)
+ * @param {string | null} [options.action_text=null] - Label for the action button. (default: null)
  * @returns {{ close: function(): void }}
  */
 export function snackbar(message, options = {}){

package/src/components/unsplash-page/unsplash-page.js

@@ -13,13 +13,13 @@ import * as styles from './unsplash-page.module.css';
  * and attribution overlay.
  * @param {Object} settings
  * @param {HTMLElement | null} settings.targetElement - Container element where the photo will be rendered.
- * @param {string | null} [settings.className=null] - Extra class added to the container.
+ * @param {string | null} [settings.className=null] - Extra class added to the container. (default: null)
  * @param {string | null} settings.unsplashDataUrl - URL returning Unsplash photo JSON.
  * @param {string | null} settings.utmSource - UTM source value for attribution links.
  * @param {string | null} settings.title - Main heading text.
- * @param {string | null} [settings.text=null] - Optional body text.
- * @param {string | null} [settings.backLink=null] - Optional back-link HTML.
- * @param {boolean} [settings.hidePhotoLink=true] - When true, the Unsplash link is shown only on hover.
+ * @param {string | null} [settings.text=null] - Optional body text. (default: null)
+ * @param {string | null} [settings.backLink=null] - Optional back-link HTML. (default: null)
+ * @param {boolean} [settings.hidePhotoLink=true] - When true, the Unsplash link is shown only on hover. (default: true)
  * @returns {Promise<void>}
  */
 

package/src/utilities/better-text.js

@@ -43,7 +43,7 @@ const PARTICLE_CASING_MAP = new Map(PARTICELLE.map(term => [term.toLowerCase(),
  * and optionally enforcing the exact casing of custom words.
  *
  * @param {string} str - input string to process
- * @param {string[]} custom_words - list of words whose exact casing must be preserved (e.g. `['iPhone', 'macOS']`)
+ * @param {string[]} [custom_words] - list of words whose exact casing must be preserved (e.g. `['iPhone', 'macOS']`) (default: [])
  * @returns {string} processed string, or empty string if input is falsy
  */
 export function betterText(str, custom_words = []) {

package/src/utilities/cookies.js

@@ -5,7 +5,7 @@
  * Returns the value of a cookie by name.
  * @param {string} name
  * @param {object} [options]
- * @param {boolean} [options.parseJson=false] - If true, JSON-parses the value and returns an object instead of a string.
+ * @param {boolean} [options.parseJson=false] - If true, JSON-parses the value and returns an object instead of a string. (default: false)
  * @returns {string | object | null}
  */
 export function getCookie(name, {parseJson = false} = {}) {
@@ -25,8 +25,8 @@ export function getCookie(name, {parseJson = false} = {}) {
  * @param {object} params
  * @param {string} params.name
  * @param {string} params.value
- * @param {string|null} [params.path=null]
- * @param {number|null} [params.expire=null] - Max-Age in seconds
+ * @param {string|null} [params.path=null] (default: null)
+ * @param {number|null} [params.expire=null] - Max-Age in seconds (default: null)
  * @example
  * // Cookie scoped to the current page only, lasting 15 days
  * setCookie({

package/src/utilities/dom-builder/dom-builder.js

@@ -7,8 +7,8 @@ import { parseDomString } from './parseDomString.js';
 
 /**
  * @typedef {Object} DomBuilderItem
- * @property {string | string[]} [tag='div'] - HTML tag name or array of nested tags (each is parent of the next). Also `tagName`.
- * @property {string | string[]} [tagName='div'] - Alias for `tag`.
+ * @property {string | string[]} [tag='div'] - HTML tag name or array of nested tags (each is parent of the next). Also `tagName`. (default: 'div')
+ * @property {string | string[]} [tagName='div'] - Alias for `tag`. (default: 'div')
  * @property {string | string[]} [className] - CSS class(es): a single string or an array (falsy values filtered out).
  * @property {string | string[]} [class] - Alias for `className`.
  * @property {string | string[]} [classname] - Alias for `className`.
@@ -23,7 +23,7 @@ import { parseDomString } from './parseDomString.js';
  *   parsed as markup) in place of an element, so it can sit as a sibling of tags within `children`/`content`
  *   arrays. Mutually exclusive with `tag`/`content`/`children`: when set (and `tag` is absent), every other
  *   property except `condition` and `callback` is ignored.
- * @property {boolean} [condition=true] - When false, the element (or text node) is skipped.
+ * @property {boolean} [condition=true] - When false, the element (or text node) is skipped. (default: true)
  * @property {(function(HTMLElement|Text): void) | null} [callback] - Callback invoked after the element (or text node) is created.
  * @property {Array<DomBuilderItem|string|Node>} [children] - Configuration array for child elements. Accepts strings (shorthand per `parseDomString`), configuration objects, and/or `Node`s (an `Element`, a `DocumentFragment`, ...) inserted as-is.
  */
@@ -96,12 +96,12 @@ import { parseDomString } from './parseDomString.js';
  * - `callback` {(function(HTMLElement|Text): void) | null} - Invoked after the element (or text node) is created.
  * - `children` {Array<DomBuilderItem|string|Node>} - Configuration array for child elements (same format, nested; also accepts `Node`s inserted as-is).
  *
- * IDs and classes can be specified either as top-level object keys or inside `attrs`; top-level properties take precedence.
+ * IDs and classes can be specified either as top-level object keys or inside `attrs`; top-level properties take precedence. (default: [])
  * @param {HTMLElement} [parent] - Parent element the structure is attached to (see `options.insertMode`).
- * @param {Object} [options={}] - Configuration options.
- * @param {boolean} [options.emptyParent=false] - When true, the parent element is emptied before building.
- * @param {'append'|'before'|'after'} [options.insertMode='append'] - How each root element of `structureArray` is attached to `parent`: `append` inserts it as a child (default), `before`/`after` insert it as a previous/next sibling of `parent`, preserving `structureArray` order. Only applies to the elements produced by this call — nested `domBuilder` calls (`content`, `children`) always append.
- * @param {boolean} [options.debug=false] - When true, logs `structureArray` to the console after each string item has been parsed via `parseDomString` (i.e. the elaborated array actually used to build the DOM).
+ * @param {Object} [options={}] - Configuration options. (default: {})
+ * @param {boolean} [options.emptyParent=false] - When true, the parent element is emptied before building. (default: false)
+ * @param {'append'|'before'|'after'} [options.insertMode='append'] - How each root element of `structureArray` is attached to `parent`: `append` inserts it as a child (default), `before`/`after` insert it as a previous/next sibling of `parent`, preserving `structureArray` order. Only applies to the elements produced by this call — nested `domBuilder` calls (`content`, `children`) always append. (default: 'append')
+ * @param {boolean} [options.debug=false] - When true, logs `structureArray` to the console after each string item has been parsed via `parseDomString` (i.e. the elaborated array actually used to build the DOM). (default: false)
  * @returns {HTMLElement|null} The first created element, or null if nothing was created.
  */
 

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

@@ -9,9 +9,9 @@ import { randomId } from '../random-id.js';
  * (typically the label + control).
  *
  * @param {Object} args
- * @param {boolean} [args.condition=true] - When false, returns `null` without building anything.
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
- * @param {string | HTMLElement | null} [args.help=null] - Optional help text.
+ * @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.
  */
@@ -48,15 +48,15 @@ function buildFormGroup({
  * @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.
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
- * @param {string | null} [args.class=null] - optional class to be added to the `input`.
- * @param {string | null} [args.classname=null] - Alias for `class`.
- * @param {string | null} [args.className=null] - Alias for `class`.
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
+ * @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.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
  * @returns {DomBuilderItem|null} The `input` domBuilder item, or `null` when `condition` is false.
  */
 export function buildInput({
@@ -112,16 +112,16 @@ export function buildInput({
  * @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
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
- * @param {string | null} [args.class=null] - optional class to be added to the `input`.
- * @param {string | null} [args.classname=null] - Alias for `class`.
- * @param {string | null} [args.className=null] - Alias for `class`.
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
- * @param {boolean} [args.useBsClass=false] - When true, uses BS5 class (`form-select`) instead of `form-control`
+ * @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.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
  * @returns {DomBuilderItem|null} The `input` domBuilder item, or `null` when `condition` is false.
  */
 export function buildSelect({
@@ -204,16 +204,16 @@ export function buildSelect({
  * @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.
- * @param {boolean} [args.checked=false] - checkbox `checked` 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).
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper (used only when `addFormGroup` is true).
- * @param {boolean} [args.addFormGroup=true] - When true, wraps the checkbox in a `.form-group` element.
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
+ *    (`.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.
+ * @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.
  */
 export function buildCheckbox({
@@ -296,15 +296,15 @@ export function buildCheckbox({
  * @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
- * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
- * @param {string | null} [args.class=null] - optional class to be added to the textarea element.
- * @param {string | null} [args.classname=null] - Alias for `class`.
- * @param {string | null} [args.className=null] - Alias for `class`.
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
+ * @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.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
  * @returns {DomBuilderItem|null} The `textarea` domBuilder item, or `null` when `condition` is false.
  */
 export function buildTextarea({
@@ -354,15 +354,15 @@ export function buildTextarea({
  * @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.
- * @param {boolean} [args.noBorder=true] - adds `no-border` class.
- * @param {string | null} [args.class=null] - optional class to be added to the fake field.
- * @param {string | null} [args.classname=null] - Alias for `class`.
- * @param {string | null} [args.className=null] - Alias for `class`.
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
+ * @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.
+ * @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.
  */
 export function buildFakeField({
@@ -407,14 +407,14 @@ export function buildFakeField({
  * @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.
+ * @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.
- * @param {string | null} [args.classname=null] - Alias for `class`.
- * @param {string | null} [args.className=null] - Alias for `class`.
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
+ * @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.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object. (default: {})
  * @returns {DomBuilderItem|null} The `button` domBuilder item, or `null` when `condition` is false.
  */
 export function buildButton({

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

@@ -69,22 +69,22 @@ 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.
- * @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.
- * @param {number} [args.dpr=2] - Maximum pixel density (integer): `srcset` candidates are generated for every density from 1 to `dpr`.
- * @param {[string, string|number][]} [args.img_params=[['q','60']]] - Query params (`[name, value]` pairs) added to every generated URL.
- * @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.
- * @param {boolean} [args.devMode=false] - When true, `avif` is excluded from `formats` (not supported by the local dev environment).
- * @param {boolean} [args.lazy=true] - When true, the `img` element gets `loading="lazy"`.
- * @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`).
- * @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).
- * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
- * @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).
- * @param {string|null} [args.pictureExtraClass=null] - Extra class(es) for the `picture` element.
- * @param {Object<string, *>} [args.pictureExtraAttrs={}] - Extra attributes for the `picture` element.
- * @param {string|null} [args.imgExtraClass=null] - Extra class(es) for the `img` element.
- * @param {Object<string, *>} [args.imgExtraAttrs={}] - Extra attributes for the `img` element.
- * @param {string} [args.alt=''] - `alt` text for the `img` element.
+ * @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.
  */
 export function buildPictureTag({

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

@@ -1,7 +1,7 @@
 /*! minimo - Enable Submit Buttons */
 /**
  * Re-enables all submit and non-disabled button elements within the given context.
- * @param {Document | Element} [context=document]
+ * @param {Document | Element} [context=document] (default: document)
  * @returns {void}
  */
 export function enableSubmitBtns(context = document) {

package/src/utilities/generate-pwd.js

@@ -3,7 +3,7 @@
  * Generates a random password using uppercase letters and digits,
  * excluding visually ambiguous characters (O, I, 0).
  *
- * @param {number} [min_length=8] - Minimum password length (matches `minlength` attribute).
+ * @param {number} [min_length=8] - Minimum password length (matches `minlength` attribute). (default: 8)
  * @returns {string} The generated password.
  */
 export function generatePwd(min_length = 8) {

package/src/utilities/linked-dates.js

@@ -13,7 +13,7 @@
  * If the linked field is disabled, the constraint is removed on focus
  * and restored when the linked field is re-enabled.
  *
- * @param {Document|Element} context - root element to search within (defaults to `document`)
+ * @param {Document|Element} context - root element to search within (default: document)
  * @returns {void}
  */
 export function linkedDates(context = document) {

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

@@ -10,7 +10,7 @@
  * parseFileSize(10485760);  // "10 MB"
  *
  * @param {number} bytes - file size in bytes
- * @param {number} [decimals=1] - max number of decimal digits
+ * @param {number} [decimals=1] - max number of decimal digits (default: 1)
  * @returns {string} formatted size (e.g. "1.5 MB")
  */
 export function parseFileSize(bytes, decimals = 1) {

package/src/utilities/relative-date.js

@@ -6,17 +6,17 @@
 
 /**
  * @typedef {object} RelativeDateOptions
- * @property {boolean} [useRelativeTime=true] - Show times near the date as "in xx minutes" (before) or "now" (within `relativeTimeMinutesAfter`)
- * @property {string} [nowString] - String to display when the date is right now
- * @property {number} [relativeTimeMinutesBefore] - Minutes before the date within which to show "in xx minutes"
- * @property {number} [relativeTimeMinutesAfter] - Minutes after the date within which to show the now string
- * @property {boolean} [relativeTimeShowTime] - Show the actual time alongside relative date labels
- * @property {string} [relativeTimeShowTimeMarkup] - HTML markup for the time portion; `@@time@@` is replaced with the localized time string
- * @property {boolean} [firstLetterUpperCase] - Capitalize the first letter of the returned string
- * @property {Intl.DateTimeFormatOptions} [dateFormat] - Format for non-relative dates (beyond day after tomorrow)
- * @property {Intl.DateTimeFormatOptions} [timeFormat] - Format for time displayed in relative date labels
- * @property {string[]} [relativeStrings] - Labels for yesterday / today / tomorrow / day after tomorrow (in chronological order)
- * @property {string} [locale] - Locale string for date/time formatting
+ * @property {boolean} [useRelativeTime=true] - Show times near the date as "in xx minutes" (before) or "now" (within `relativeTimeMinutesAfter`) (default: true)
+ * @property {string} [nowString] - String to display when the date is right now (default: 'adesso')
+ * @property {number} [relativeTimeMinutesBefore] - Minutes before the date within which to show "in xx minutes" (default: 30)
+ * @property {number} [relativeTimeMinutesAfter] - Minutes after the date within which to show the now string (default: 30)
+ * @property {boolean} [relativeTimeShowTime] - Show the actual time alongside relative date labels (default: true)
+ * @property {string} [relativeTimeShowTimeMarkup] - HTML markup for the time portion; `@@time@@` is replaced with the localized time string (default: ' <span class="time-info">(alle @@time@@)</span>')
+ * @property {boolean} [firstLetterUpperCase] - Capitalize the first letter of the returned string (default: true)
+ * @property {Intl.DateTimeFormatOptions} [dateFormat] - Format for non-relative dates (beyond day after tomorrow) (default: { weekday: 'short', year: 'numeric', month: 'short', day: 'numeric', hour12: false, hour: '2-digit', minute: '2-digit' })
+ * @property {Intl.DateTimeFormatOptions} [timeFormat] - Format for time displayed in relative date labels (default: { hour12: false, hour: '2-digit', minute: '2-digit' })
+ * @property {string[]} [relativeStrings] - Labels for yesterday / today / tomorrow / day after tomorrow (in chronological order) (default: ['ieri alle', 'oggi alle', 'domani alle', 'dopodomani alle'])
+ * @property {string} [locale] - Locale string for date/time formatting (default: 'it-IT')
  */
 
 /**
@@ -27,18 +27,18 @@
  * expands dotted `@param` properties (needed for editor IntelliSense to list each property) when
  * the base type is the literal `object`; a named typedef there would error (TS8032).
  * @param {Date | string} date - Date to display (Date object or ISO string)
- * @param {object} [options={}]
- * @param {boolean} [options.useRelativeTime=true] - Show times near the date as "in xx minutes" (before) or "now" (within `relativeTimeMinutesAfter`)
- * @param {string} [options.nowString] - String to display when the date is right now
- * @param {number} [options.relativeTimeMinutesBefore] - Minutes before the date within which to show "in xx minutes"
- * @param {number} [options.relativeTimeMinutesAfter] - Minutes after the date within which to show the now string
- * @param {boolean} [options.relativeTimeShowTime] - Show the actual time alongside relative date labels
- * @param {string} [options.relativeTimeShowTimeMarkup] - HTML markup for the time portion; `@@time@@` is replaced with the localized time string
- * @param {boolean} [options.firstLetterUpperCase] - Capitalize the first letter of the returned string
- * @param {Intl.DateTimeFormatOptions} [options.dateFormat] - Format for non-relative dates (beyond day after tomorrow)
- * @param {Intl.DateTimeFormatOptions} [options.timeFormat] - Format for time displayed in relative date labels
- * @param {string[]} [options.relativeStrings] - Labels for yesterday / today / tomorrow / day after tomorrow (in chronological order)
- * @param {string} [options.locale] - Locale string for date/time formatting
+ * @param {object} [options={}] (default: {})
+ * @param {boolean} [options.useRelativeTime=true] - Show times near the date as "in xx minutes" (before) or "now" (within `relativeTimeMinutesAfter`) (default: true)
+ * @param {string} [options.nowString] - String to display when the date is right now (default: 'adesso')
+ * @param {number} [options.relativeTimeMinutesBefore] - Minutes before the date within which to show "in xx minutes" (default: 30)
+ * @param {number} [options.relativeTimeMinutesAfter] - Minutes after the date within which to show the now string (default: 30)
+ * @param {boolean} [options.relativeTimeShowTime] - Show the actual time alongside relative date labels (default: true)
+ * @param {string} [options.relativeTimeShowTimeMarkup] - HTML markup for the time portion; `@@time@@` is replaced with the localized time string (default: ' <span class="time-info">(alle @@time@@)</span>')
+ * @param {boolean} [options.firstLetterUpperCase] - Capitalize the first letter of the returned string (default: true)
+ * @param {Intl.DateTimeFormatOptions} [options.dateFormat] - Format for non-relative dates (beyond day after tomorrow) (default: { weekday: 'short', year: 'numeric', month: 'short', day: 'numeric', hour12: false, hour: '2-digit', minute: '2-digit' })
+ * @param {Intl.DateTimeFormatOptions} [options.timeFormat] - Format for time displayed in relative date labels (default: { hour12: false, hour: '2-digit', minute: '2-digit' })
+ * @param {string[]} [options.relativeStrings] - Labels for yesterday / today / tomorrow / day after tomorrow (in chronological order) (default: ['ieri alle', 'oggi alle', 'domani alle', 'dopodomani alle'])
+ * @param {string} [options.locale] - Locale string for date/time formatting (default: 'it-IT')
  * @returns {string} HTML `<time>` element as a string
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat
@@ -83,7 +83,7 @@ export function relativeDate(date, options = {}) {
 
   /**
    * @param {Date | string} dateInput
-   * @param {RelativeDateOptions} [overrideOptions={}]
+   * @param {RelativeDateOptions} [overrideOptions={}] (default: {})
    * @returns {string}
    */
   const parseDate = (dateInput, overrideOptions = {}) => {

package/src/utilities/truncate-string.js

@@ -8,7 +8,7 @@
  *
  * @param {string} str - string yo be truncated
  * @param {number} maxLength - truncated string max length
- * @param {string} suffix
+ * @param {string} suffix (default: '…')
  * @returns {string|undefined} truncated string, or undefined if str is falsy
  *
  */

package/src/web-components/s-datatable-component/s-datatable-component.js

@@ -73,7 +73,7 @@ import caretRightIcon from '../../icons/caret-right.svg?inline';
  * @property {string}  [_renderNullAs]       Stringa da mostrare al posto di valori null/undefined.
  *                                           Default: `'—'` (trattino em).
  *                                           Applicato al valore della cella e ai segnaposto
- *                                           di `_cellRender` che si risolvono a null.
+ *                                           di `_cellRender` che si risolvono a null. (default: '—')
  * @property {'id'|'email'|'sf_datetime'} [_renderMode]
  *                                           Modalità di visualizzazione predefinita:
  *                                           - `id`          – colonna numerica, non ricercabile, allineata a destra
@@ -96,22 +96,22 @@ import caretRightIcon from '../../icons/caret-right.svg?inline';
  * @param {ColDefinition[]} cols     Definizione delle colonne. Le chiavi con prefisso `_` sono
  *                                  proprietà di questo componente; le restanti vengono passate
  *                                  direttamente a simple-datatables (es. `sortable`, `searchable`).
- *                                  Default: `[]`
+ *                                  Default: `[]` (default: [])
  *
  * @param {number}        perPage          Numero di righe per pagina.
- *                                           Default: `25`
+ *                                           Default: `25` (default: 25)
  *
  * @param {string}        renderNullAs     Stringa globale da mostrare al posto di valori null/undefined
  *                                           in tutte le colonne. Può essere sovrascritto per singola
  *                                           colonna con `_renderNullAs`.
- *                                           Default: `\u2014` (em dash)
+ *                                           Default: `\u2014` (em dash) (default: '\u2014')
  *
  * @param {boolean}       updateFooterOnPageChange     Se true, la callback `_footerRender` riceve i soli record
  *                                           della pagina corrente (subtotale di pagina). Se false
  *                                           (default), riceve l'intero set filtrato indipendentemente
  *                                           dalla paginazione (totale complessivo).
  *                                           Quando è false il footer si aggiorna solo al cambio di
- *                                           filtro, non al cambio pagina.
+ *                                           filtro, non al cambio pagina. (default: false)
  *
  * @param {string[]}      refs  Elenco di percorsi URL da cui, se si proviene,
  *                                           la pagina corrente viene ripristinata dal cookie
@@ -166,7 +166,7 @@ function getNestedValue(obj, path) {
  *
  * @param {string|Function|Node} tpl      Template da risolvere.
  * @param {object|null}     row           Oggetto riga corrente (null per le intestazioni).
- * @param {object}          [opts]        Opzioni aggiuntive.
+ * @param {object}          [opts]        Opzioni aggiuntive. (default: {})
  * @param {string}          [opts.nullAs] Stringa da usare come fallback per i segnaposto
  *                                        che si risolvono a null (default: `''`).
  *                                        Se non fornita i segnaposto non trovati diventano ''.
@@ -380,7 +380,7 @@ class SimpleDatatableAdapter extends HTMLElement {
    * Ricarica i dati (eventualmente da un nuovo URL e/o con nuove colonne),
    * con possibilità di applicare un filtro contestuale al termine del fetch.
    *
-   * @param {object} [overrides]
+   * @param {object} [overrides] (default: {})
    * @param {string} [overrides.json]    Nuovo URL dati (ignorato se `data` è presente)
    * @param {Array}  [overrides.data]    Dati inline (array di oggetti); ha precedenza su `json`
    * @param {Array}  [overrides.cols]    Nuove colonne

package/src/web-components/s-datatable-component/src/search-method.js

@@ -23,13 +23,13 @@ const PUNCTUATION_RX = /[.,/#!$%^&*;:{}=\-_`~()]/g;
  * troverebbe "S.p.A.".
  *
  * @param {*} str Valore da normalizzare (convertito con String()).
- * @param {object} [opts]
+ * @param {object} [opts] (default: {})
  * @param {'base'|'accent'|'case'|'variant'} [opts.sensitivity='base']
  *        'base'    → ignora maiuscole/minuscole e diacritici
  *        'accent'  → ignora maiuscole/minuscole, mantiene i diacritici
  *        'case'    → distingue maiuscole/minuscole, ignora i diacritici
- *        'variant' → distingue tutto
- * @param {boolean} [opts.ignorePunctuation=true]
+ *        'variant' → distingue tutto (default: 'base')
+ * @param {boolean} [opts.ignorePunctuation=true] (default: true)
  * @returns {string}
  */
 export function normalizeSearchString(str, opts = {}) {
@@ -63,7 +63,7 @@ export function normalizeSearchString(str, opts = {}) {
  * Comportamento AND: tutti i termini devono essere presenti
  * (come nella demo https://fiduswriter.github.io/simple-datatables/demos/22-and-search/).
  *
- * @param {object} [colSettings] Definizione della colonna (per `sensitivity` / `ignorePunctuation`).
+ * @param {object} [colSettings] Definizione della colonna (per `sensitivity` / `ignorePunctuation`). (default: {})
  * @returns {(terms: string[], cell: object) => boolean}
  */
 export function makeSearchMethod(colSettings = {}) {