@massimo-cassandro/minimo 1.5.13 → 1.6.1

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

@@ -7,10 +7,17 @@ import * as styles from './modal-popup.module.css';
 // https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement
 
 
-// TODO testare la modalità iframe
+// TODO test iframe mode
 
-let dialogEl, dialogContentEl;
+/** @type {HTMLDialogElement | undefined} */
+let dialogEl;
+/** @type {HTMLElement | undefined} */
+let dialogContentEl;
 
+/**
+ * @param {HTMLDialogElement} el
+ * @returns {void}
+ */
 function closeDialog(el) {
   el.classList.remove(styles.on);
 
@@ -21,43 +28,55 @@ function closeDialog(el) {
 
 /**
  * modalPopup
- * Mostra un popup con il contenuto indicato
- * il contentuo può essere in forma di:
- *  - array domBuilder oppure plain text oppure HTML (parametro `content`)
- *  - contenuto caricato via Ajax  (parametri `ajaxUrl` e `ajaxCallback`)
- *  - iframe (parametro `iframeUrl`)
+ * Opens a popup dialog with the given content.
+ *
+ * Content can be provided as:
+ *  - a domBuilder array, plain text, or HTML (via `content`)
+ *  - content loaded via Ajax (via `ajaxUrl` and `ajaxCallback`)
+ *  - an iframe (via `iframeUrl`)
  *
- * in presenza di più impostazioni in conflitto, viene scelta la prima opzione utile
- * nell'ordine di priorità riportato nella lista precedente.
+ * 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 | null} [params.contentExtraClassName=null] - Extra class added to the content wrapper.
+ * @param {string | null} [params.iframeUrl=null] - URL to load in an iframe.
+ * @param {string | any[] | null} [params.content=null] - Plain text, HTML, or a domBuilder array.
+ * @param {string | null} [params.ajaxUrl=null] - URL for Ajax content loading.
+ * @param {((data: *, el: Element) => void) | null} [params.ajaxCallback=null] - Called with the Ajax response and the content element.
+ * @param {((el: HTMLDialogElement) => void) | null} [params.closeCallback=null] - Called with the dialog element just before it is removed.
+ * @param {boolean} [params.addScrollbarPadding=false] - Adds right padding to compensate for the scrollbar.
+ * @param {string | null} [params.headerContent=null] - Header content: plain text or HTML.
+ * @param {string | null} [params.footerContent=null] - Footer content: plain text or HTML.
+ * @returns {HTMLDialogElement} The dialog element.
  */
-
 export function modalPopup({
 
   /** dialog extra class */
   dialogExtraClassName = null,
 
-  /** extra classname added to  dialogInner */
+  /** extra classname added to dialogInner */
   contentExtraClassName = null,
 
   /** iframe url */
   iframeUrl = null,
 
-  /** content: plain text, html or  domBuilder array */
+  /** content: plain text, html or domBuilder array */
   content = null,
 
-  /** url ajax e relatuva funzione di callback.
-   * Quest'ultima viene invocata con argomenti i dati restituiti dalla chiamata ajax
-   * e con l''elemento contenitore (`ajaxCallback(data, dialogContentEl)`)
+  /** Ajax url and callback.
+   * The callback is invoked with the response data and the content container element
+   * (`ajaxCallback(data, dialogContentEl)`)
   */
   ajaxUrl = null,
   ajaxCallback = null,
 
-  /** eventuale callback da invocare alla chiusra del dialog
-   * Viene invocato con il le'elento dialog (`closeCallback(dialogEl)`)
-   * NB: `dialogEl` viene eliminato subito dopo
+  /** optional callback invoked when the dialog closes;
+   * receives the dialog element (`closeCallback(dialogEl)`)
+   * NB: `dialogEl` is removed immediately after
    */
   closeCallback = null,
-  addScrollbarPadding = false, // aggiunge un padding extra a destra per la barra di scorrimento
+  addScrollbarPadding = false, // adds extra right padding to compensate for the scrollbar
 
   /** header content: plain text or HTML */
   headerContent = null,
@@ -86,6 +105,9 @@ export function modalPopup({
     mode = 'iframe';
   }
 
+  // capture for use in the ajax callback closure (ajaxUrl is non-null when mode === 'ajax')
+  const safeAjaxUrl = /** @type {string} */ (ajaxUrl);
+
   domBuilder([
     {
       tag: 'dialog',
@@ -93,7 +115,7 @@ export function modalPopup({
       attrs: {
         'closedby': 'any'
       },
-      callback: el => dialogEl = el,
+      callback: el => { dialogEl = /** @type {HTMLDialogElement} */ (el); },
       children: [
         {
           tag: 'button',
@@ -121,7 +143,7 @@ export function modalPopup({
                   : null,
 
               children: [
-                ...(mode === 'domBuilder'? content : []),
+                ...(mode === 'domBuilder'? /** @type {any[]} */ (content) : []),
                 {
                   condition: mode === 'iframe',
                   className: styles.iframe,
@@ -138,15 +160,15 @@ export function modalPopup({
                   try {
 
                     (async () => {
-                      const response = await fetch(ajaxUrl),
+                      const response = await fetch(safeAjaxUrl),
                         data = await response.json();
                       el.innerHTML = '';
-                      ajaxCallback(data, dialogContentEl);
+                      ajaxCallback?.(data, dialogContentEl);
                     })();
 
                   } catch(err) {
                     /* eslint-disable no-console */
-                    console.error(ajaxUrl);
+                    console.error(safeAjaxUrl);
                     console.error(err);
                     /* eslint-enable no-console */
                   }
@@ -165,15 +187,15 @@ export function modalPopup({
     }
   ], document.body);
 
-  // snapshot: dialogEl potrebbe essere sovrascritto da una seconda chiamata a modalPopup
-  const thisDialog = dialogEl;
+  // snapshot: dialogEl could be overwritten by a subsequent modalPopup call
+  const thisDialog = /** @type {HTMLDialogElement} */ (dialogEl);
 
-  // listener sul pulsante di chiusura
-  thisDialog.querySelector(`.${styles.closeButton}`).addEventListener('click', () => {
+  // close button listener
+  thisDialog.querySelector(`.${styles.closeButton}`)?.addEventListener('click', () => {
     closeDialog(thisDialog);
   }, false);
 
-  // // Esc e clic sul backdrop
+  // // Esc and backdrop click
   // thisDialog.addEventListener('cancel', (e) => {
   //   e.preventDefault();
   //   closeDialog(thisDialog);

package/src/components/overlay/overlay.js

@@ -1,11 +1,23 @@
-import './overlay.css'; 
+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`.
+ * @returns {void}
+ */
 export function overlay(context = document.body, scroll_lock = false) {
   context.insertAdjacentHTML('beforeend', '<div class="overlay"/>');
   if(scroll_lock) {
     document.body.classList.add('overflow-hidden');
   }
 }
+
+/**
+ * Removes the overlay element from the given context and re-enables body scroll.
+ * @param {Element} [context=document.body]
+ * @returns {void}
+ */
 export function removeOverlay(context = document.body) {
   context.querySelector(':scope > .overlay')?.remove();
   document.body.classList.remove('overflow-hidden');

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

@@ -1,5 +1,15 @@
-// import './sf-macro.css'; // da importare nel progetto
-
+// import './sf-macro.css'; // import in the consuming project
+
+/**
+ * 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.
+ * @returns {void}
+ */
 export function sf_macro({
   wrapper_selector = '.sf-macro-wrapper',
   row_selector = '.sf-macro-riga',
@@ -9,19 +19,20 @@ export function sf_macro({
 }={}) {
 
   document.querySelectorAll(wrapper_selector).forEach(fset => {
-    const macro_container = fset.querySelector('.sf-macro-container')
-      ,macro_template = macro_container.dataset.template
-    ;
+    const macro_container = /** @type {HTMLElement | null} */ (fset.querySelector('.sf-macro-container'));
+    if (!macro_container) return;
+    const macro_template = macro_container.dataset.template ?? '';
 
-    // listeners
+    // event listeners
     fset.addEventListener('click', e => {
+      const target = /** @type {HTMLElement} */ (e.target);
 
-      if(e.target.closest('.sf-macro-riga-add')) {
+      if(target.closest('.sf-macro-riga-add')) {
 
         const righe_macro = macro_container.querySelectorAll(row_selector).length;
 
         macro_container.insertAdjacentHTML(insertAtTop? 'afterbegin' : 'beforeend',
-          macro_template.replace(/__indice\d?__/g, righe_macro + 1)
+          macro_template.replace(/__indice\d?__/g, String(righe_macro + 1))
         );
 
         if(add_callback && typeof add_callback === 'function') {
@@ -29,13 +40,13 @@ export function sf_macro({
             insertAtTop
               ? macro_container.querySelector('.sf-macro-riga:first-child')
               : macro_container.querySelector('.sf-macro-riga:last-child'),
-            e.target.closest('.sf-macro-riga-add')
+            target.closest('.sf-macro-riga-add')
           );
         }
 
 
-      } else if(e.target.closest('.sf-macro-close-btn')) {
-        e.target.closest(row_selector).remove();
+      } else if(target.closest('.sf-macro-close-btn')) {
+        target.closest(row_selector)?.remove();
 
         if(del_callback && typeof del_callback === 'function') {
           del_callback();
@@ -43,5 +54,5 @@ export function sf_macro({
       }
 
     }, false);
-  }); // end foreach wrapper_selector
+  });
 }

package/src/components/snackbar/snackbar.js

@@ -14,9 +14,19 @@ References
 */
 
 // TODO snackbar action
-// TODO gestione snackbar multiple (NO stacking)
-
-
+// TODO handle multiple simultaneous snackbars (no stacking)
+
+/**
+ * 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.
+ * @returns {{ close: function(): void }}
+ */
 export function snackbar(message, options = {}){
 
   options = {
@@ -31,20 +41,24 @@ export function snackbar(message, options = {}){
     ...options
   };
 
-  let _popover, _timeoutID, _isRemoving = false;
+  /** @type {HTMLElement | null} */
+  let _popover = null;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let _timeoutID;
+  let _isRemoving = false;
 
   const removePopover = () => {
     if (_isRemoving || !_popover?.matches(':popover-open')) return;
-    _isRemoving = true; // evita sovrapposizioni nel caso in cui removePopover sia chiamato più volte durante l'animazione di chiusura
+    _isRemoving = true; // prevents double-removal if called multiple times during the close animation
 
     if (_timeoutID) clearTimeout(_timeoutID);
 
-    _popover.classList.add(styles.isHiding);
+    _popover?.classList.add(styles.isHiding);
 
-    _popover.addEventListener('animationend', () => {
-      _popover.hidePopover();
-      _popover.remove();
-    }, { once: true }); // `once` già evita duplicati sul listener, ma il flag protegge prima
+    _popover?.addEventListener('animationend', () => {
+      _popover?.hidePopover();
+      _popover?.remove();
+    }, { once: true }); // 'once' prevents duplicate listeners; the flag guards against calls before animation ends
   };
 
   _popover = domBuilder([
@@ -52,7 +66,7 @@ export function snackbar(message, options = {}){
       className: classnames(styles.snackbarOuter, options.status? styles[`status-${options.status}`] : null),
       attrs: {
         popover: 'manual',
-        role: (options.action || ['danger','warning'].includes(options.status)) ? 'alert' : 'status'
+        role: (options.action || (options.status != null && ['danger','warning'].includes(options.status))) ? 'alert' : 'status'
       },
       children: [
         {
@@ -85,16 +99,17 @@ export function snackbar(message, options = {}){
     }
   ], document.body);
 
-  _popover.showPopover();
+  _popover?.showPopover();
 
 
   if(options.duration) {
-    _timeoutID = setTimeout(removePopover, options.duration);
+    const duration = options.duration; // const preserves narrowing inside closures
+    _timeoutID = setTimeout(removePopover, duration);
 
-    // mette in pausa il timeout sull'hover
-    _popover.addEventListener('mouseenter', () => clearTimeout(_timeoutID));
-    _popover.addEventListener('mouseleave', () => {
-      _timeoutID = setTimeout(removePopover, options.duration);
+    // pause the auto-close timeout on hover
+    _popover?.addEventListener('mouseenter', () => clearTimeout(_timeoutID));
+    _popover?.addEventListener('mouseleave', () => {
+      _timeoutID = setTimeout(removePopover, duration);
     });
 
   }

package/src/components/spinner/spinner.js

@@ -1,8 +1,12 @@
 import * as styles from './spinner.module.css';
 
-// NB la classe spinner è legata al tipo di spinner che si decide di usare, il cui file va incluso
-// TODO sistema per coinfigurare il tipo di spinner da utilizzare, per permettere l'uso di più tipi di spinner nello stesso progetto
+// The spinner class depends on the spinner type in use; the corresponding CSS file must be included.
+// TODO: system for configuring the spinner type to allow multiple spinner types in the same project
 
+/**
+ * Returns the HTML markup for a loading spinner.
+ * @returns {string}
+ */
 export function spinner() {
   return `<div class="${styles.spinnerWrapper}"><div class="spinner">Loading...</div></div>`;
 }

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

@@ -1,4 +1,25 @@
 
+/**
+ * @typedef {Object} UnsplashPhoto
+ * @property {string} id
+ * @property {string} color
+ * @property {number} width
+ * @property {number} height
+ * @property {string} alt_description
+ * @property {string} date
+ * @property {string} base_url
+ * @property {string} unsplash_url
+ * @property {string} author
+ * @property {string} author_profile
+ * @property {string} blur_hash
+ * @property {string} image_description
+ */
+
+/**
+ * Fetches and normalises Unsplash photo data from the given URL.
+ * @param {{ unsplash_data_url: string | null }} settings
+ * @returns {Promise<UnsplashPhoto | undefined>}
+ */
 export async function fetchUnsplashData(settings) {
 
   const default_settings = {
@@ -13,11 +34,13 @@ export async function fetchUnsplashData(settings) {
       throw new Error( 'Unsplash data url must be defined' );
     }
 
+    const url = settings.unsplash_data_url; // const preserves narrowing inside the IIFE closure
+
     const imgData = await (async () => {
-      const response = await fetch(settings.unsplash_data_url);
+      const response = await fetch(url);
       if (!response.ok) {
         /* eslint-disable no-console */
-        console.error('Ajax error on: ' + settings.unsplash_data_url);
+        console.error('Ajax error on: ' + url);
         console.error(response);
         /* eslint-enable no-console */
         throw new Error( `Loading error: ${response.status}` );

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

@@ -1,3 +1,14 @@
+/**
+ * @typedef {Object} Breakpoint
+ * @property {string} name - Breakpoint identifier.
+ * @property {string} mq - Media query string.
+ * @property {number} w - Image width in pixels.
+ * @property {number} h - Image height in pixels.
+ * @property {boolean} dpr2 - Whether to include a 2× DPR srcset entry.
+ * @property {string} [ar] - Aspect ratio (e.g. '16/9').
+ */
+
+/** @type {Breakpoint[]} */
 export const breakpoints = [
   {
     name: 'xxl',

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

@@ -4,6 +4,21 @@ import { breakpoints } from './img-breakpoints.js';
 import { fetchUnsplashData } from './fetch-unsplash-data.js';
 import { decode } from 'blurhash';
 
+/**
+ * Initialises an Unsplash full-page photo with blurhash placeholder, responsive picture element,
+ * 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.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 {Record<string, string> | null} [settings.cssModulesObj=null] - CSS Modules class map; when null, class names are used as-is.
+ * @returns {void}
+ */
 export function unsplashPageJS(settings) {
 
   const default_settings = {
@@ -24,22 +39,26 @@ export function unsplashPageJS(settings) {
 
   try {
 
+    const settingsMap = /** @type {Record<string, unknown>} */ (settings);
     if(required_settings
-      .map(i => settings[i])
+      .map(i => settingsMap[i])
       .filter(i => i !== null && i !== '').length !== required_settings.length) {
 
       throw new Error( `I parametri ${required_settings.map(i => `\`${i}\``).join(',')} sono obbligatori` );
     }
 
+    const targetElement = /** @type {HTMLElement} */ (settings.targetElement);
 
-    const cssClass = classname => settings.cssModulesObj? settings.cssModulesObj[classname] : classname;
+    const cssClass = /** @param {string} classname */ classname =>
+      settings.cssModulesObj? settings.cssModulesObj[classname] : classname;
 
-    settings.targetElement.innerHTML = `<div class="${cssClass('upContainer') + (settings.className? ` ${settings.className}` : '')}"></div>`;
-    const container = settings.targetElement.querySelector('.' + cssClass('upContainer'));
+    targetElement.innerHTML = `<div class="${cssClass('upContainer') + (settings.className? ` ${settings.className}` : '')}"></div>`;
+    const container = /** @type {HTMLElement} */ (targetElement.querySelector('.' + cssClass('upContainer')));
     container.innerHTML = `<div class="${cssClass('upLoaderWrapper')}"><div class="${cssClass('upLoader')}"></div></div>`;
 
     fetchUnsplashData({unsplash_data_url: settings.unsplashDataUrl})
       .then(photo => {
+        if (!photo) return;
 
         const pixels = decode(photo.blur_hash, container.offsetWidth, container.offsetHeight);
 
@@ -48,9 +67,11 @@ export function unsplashPageJS(settings) {
         canvas.width = container.offsetWidth;
         canvas.height = container.offsetHeight;
         const ctx = canvas.getContext('2d');
-        const imageData = ctx.createImageData(container.offsetWidth, container.offsetHeight);
-        imageData.data.set(pixels);
-        ctx.putImageData(imageData, 0, 0);
+        if (ctx) {
+          const imageData = ctx.createImageData(container.offsetWidth, container.offsetHeight);
+          imageData.data.set(pixels);
+          ctx.putImageData(imageData, 0, 0);
+        }
 
 
         container.insertAdjacentElement('afterbegin', canvas);
@@ -100,42 +121,45 @@ export function unsplashPageJS(settings) {
           '</picture>'
         ); // end insert <picture>
 
-        const img = container.querySelector('.' + cssClass('unsplashPhoto'));
-        img.onload = () => {
-          container.querySelector('.' + cssClass('upLoaderWrapper'))?.remove();
-          container.classList.add(cssClass('show'));
-
-          container.insertAdjacentHTML('beforeend', `<div class="${cssClass('upMessageBox')}">
-            <div class="${cssClass('upMessage')}">
-              <h1>${settings.title}</h1>
-              ${settings.text? `<p>${settings.text}</p>` : ''}
-              ${settings.backLink ? `<p class="${cssClass('upBackLink')}">${settings.backLink}</p>` : ''}
-
-              <div class="${cssClass('upArrowWrapper')}" role="button">
-                <img src="${arrowIcon}" alt="Icona freccia">
+        const img = /** @type {HTMLImageElement | null} */ (container.querySelector('.' + cssClass('unsplashPhoto')));
+        if (img) {
+          img.onload = () => {
+            container.querySelector('.' + cssClass('upLoaderWrapper'))?.remove();
+            container.classList.add(cssClass('show'));
+
+            container.insertAdjacentHTML('beforeend', `<div class="${cssClass('upMessageBox')}">
+              <div class="${cssClass('upMessage')}">
+                <h1>${settings.title}</h1>
+                ${settings.text? `<p>${settings.text}</p>` : ''}
+                ${settings.backLink ? `<p class="${cssClass('upBackLink')}">${settings.backLink}</p>` : ''}
+
+                <div class="${cssClass('upArrowWrapper')}" role="button">
+                  <img src="${arrowIcon}" alt="Icona freccia">
+                </div>
               </div>
-            </div>
 
-            <div class="${cssClass('upCredits')}">
-              <em>${photo.image_description}</em>
-              <span>Photo
-                <a href="${`${photo.author_profile}?utmSource=${settings.utmSource}&utm_medium=referral`}">
-                  ${photo.author} / Unsplash
-                </a>
-              </span>
+              <div class="${cssClass('upCredits')}">
+                <em>${photo.image_description}</em>
+                <span>Photo
+                  <a href="${`${photo.author_profile}?utmSource=${settings.utmSource}&utm_medium=referral`}">
+                    ${photo.author} / Unsplash
+                  </a>
+                </span>
+              </div>
             </div>
-          </div>
-          <div class="${cssClass('unsplashPhotoLink')}${settings.hidePhotoLink? ` ${cssClass('upShowOnHover')}` : ''}">
-            <a href="${`${photo.unsplash_url}?utm_source=${settings.utmSource}&utm_medium=referral`}" target="_blank" rel="noopener noreferrer">
-              <img src="${imageIcon}" alt="Icona immagine" />
-            </a>
-          </div>`);
-
-          container.querySelector('.' + cssClass('upArrowWrapper')).addEventListener('click', e => {
-            e.target.closest(`.${cssClass('upMessage')}`).classList.toggle(cssClass('hidden'));
-          }, false);
-
-        }; // end img.onload
+            <div class="${cssClass('unsplashPhotoLink')}${settings.hidePhotoLink? ` ${cssClass('upShowOnHover')}` : ''}">
+              <a href="${`${photo.unsplash_url}?utm_source=${settings.utmSource}&utm_medium=referral`}" target="_blank" rel="noopener noreferrer">
+                <img src="${imageIcon}" alt="Icona immagine" />
+              </a>
+            </div>`);
+
+            container.querySelector('.' + cssClass('upArrowWrapper'))?.addEventListener('click', e => {
+              const target = /** @type {HTMLElement} */ (e.target);
+              target.closest(`.${cssClass('upMessage')}`)?.classList.toggle(cssClass('hidden'));
+            }, false);
+
+          }; // end img.onload
+        }
 
       }); // end .then
 

package/src/components/unsplash-page/unsplash-page.module.css

@@ -1,6 +1,6 @@
 /*
   PERSONALIZZAZIONE
-  custom properties (valori di default, vedi /design-tokens-src/components/unsplash-page.minimo.tokens.mjs):
+  custom properties (valori di default, vedi /design-tokens/_src/components/unsplash-page.minimo.tokens.mjs):
 
   Basic props:
   --up-bg-color: hsl(0deg 0% 0% / .7);

package/src/css/forms/forms.css

@@ -148,6 +148,10 @@ input::-webkit-calendar-picker-trigger-icon { /* solo in chromium, non in safari
 textarea.form-control {
   flex: 1;
   min-height: calc(3.5lh + var(--form-control-padding-block) * 2);
+
+  &.autosize {
+    field-sizing: content;
+  }
 }
 
 

package/src/utilities/classnames.js

@@ -1,14 +1,27 @@
+/** @typedef {string | null | undefined | false | 0} ClassValue */
+
+/**
+ * Joins CSS class names, filtering out falsy and non-string values.
+ * Accepts strings, falsy values, and (nested) arrays of the same.
+ * @param {...(ClassValue | ClassValue[])} args
+ * @returns {string}
+ */
 export function classnames(...args) {
   return args.flat().filter(x => {
     if (x && typeof x !== 'string') {
       // eslint-disable-next-line no-console
-      console.error('[classnames] valore non stringa ignorato in ', ...args);
+      console.error('[classnames] non-string value ignored: ', ...args);
       return false;
     }
     return Boolean(x);
   }).join(' ');
 }
 
+/**
+ * Like {@link classnames}, but returns `null` when the result is an empty string.
+ * @param {...(ClassValue | ClassValue[])} args
+ * @returns {string | null}
+ */
 export function classnamesNull(...args) {
   return classnames(...args) || null;
 }

package/src/utilities/create-id.js

@@ -0,0 +1,19 @@
+import { stripTags } from './strip-tags.js';
+
+/**
+ * Creates an id from a string (useful for generating automatic anchors from tag content).
+ * Strips HTML tags, normalizes accented characters, punctuation, and whitespace.
+ * @param {string | null | undefined} str
+ * @returns {string}
+ */
+export function createId(str) {
+  return (stripTags(str) || '')
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[\p{P}\p{S}]+/gu, '') // strips all Unicode punctuation and symbols
+    .replace(/\s+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+}