@massimo-cassandro/minimo 1.6.0 → 1.7.0

package/src/utilities/better-text.js

@@ -0,0 +1,80 @@
+// @ts-check
+
+/**
+ * Improves a text string by fixing punctuation spacing, multiple spaces,
+ * typographic quotes, non-breaking spaces after Italian particles/articles,
+ * 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']`)
+ * @returns {string} processed string, or empty string if input is falsy
+ */
+export function betterText(str, custom_words = []) {
+
+  const particelle = [
+    'e', 'ed',
+    'di', 'a', 'da', 'in', 'per', 'con', 'su', 'per', 'tra', 'fra',
+    'il', 'lo', 'la', 'i', 'gli', 'le',
+    'un', 'uno', 'una',
+    'del', 'dello', 'della', 'dei', 'degli', 'delle',
+    'al', 'allo', 'alla', 'ai', 'agli', 'alle',
+    'dal', 'dallo', 'dalla', 'dai', 'dagli', 'dalle',
+    'nel', 'nello', 'nella', 'nei', 'negli', 'nelle',
+    'col', 'collo', 'colla', 'con', 'coi', 'cogli', 'colle',
+    'sul', 'sullo', 'sulla', 'sui', 'sugli', 'sulle',
+
+    // topographic terms
+    'C.so', 'Corso', 'Via', 'P.za', 'Piazza', 'L.go', 'Largo', 'V.le', 'Viale',
+    'De', 'San', 'c/o', 'Loc.',
+
+    // English
+    'the', 'a', 'an', 'at', 'out', 'of',
+
+    // words used in geonames
+    'isola', 'isole'
+  ];
+
+  if(str) {
+    str = str.trim();
+
+    // punctuation: remove space before, ensure single space after
+    // NOTE: must run before any HTML entity replacements to avoid conflicts with `;`
+    // (?!$): negative lookahead to skip punctuation at end of string
+    str = str.replace(/ +(,|;|\.|:|!|\?)/g, '$1');
+    str = str.replace(/(,|;|\.|:|!|\?)(?!$) +/g, '$1 ');
+
+    // collapse multiple spaces and tabs (including non-breaking spaces)
+    str = str.replace(/[ \t\u00A0]+/g, ' ');
+
+    // typographic quotes
+    str = str.replace(/(^| )"/g, '$1“')   // opening double quotes
+      .replace(/"/g, '”')                  // remaining double quotes → closing
+      .replace(/(^| )'/g, '$1‘')           // opening single quotes
+      .replace(/'/g, '’')                  // remaining single quotes and apostrophes
+    ;
+
+    // remove space after apostrophe preceded by elided articles (l', un', d', all', ...)
+    str = str.replace(/((^| )(l|un|d|all|dell|nell|sull)('|')) /gi, '$1' );
+
+    // replace regular spaces with non-breaking spaces after Italian particles/articles
+    var re = new RegExp('\\b(' + particelle.join('|') + ')\\b +', 'gmi');
+    str = str.replace(re, function (match) {
+      return match.replace(/ +/g, '\u00A0');
+    });
+
+    // enforce exact casing of each particle
+    particelle.forEach(term => {
+      const re = new RegExp('\\b(' + term + ')\\b', 'gmi');
+      str = str.replace(re, term);
+    });
+
+    if(custom_words.length) {
+      custom_words.forEach(item => {
+        str = str.replace(new RegExp(`\\b${item}\\b`, 'gi'), item);
+      });
+    }
+  } else {
+    str = '';
+  }
+  return str;
+}

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/cookies.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * Returns the value of a cookie by name.
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+export function getCookie(name) {
+  const value = `; ${document.cookie}`;
+  const parts = value.split(`; ${name}=`);
+  if (parts.length === 2) return parts.pop()?.split(';').shift();
+}
+
+
+/**
+ * Sets a cookie.
+ * @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
+ */
+export function setCookie({name, value, path = null, expire = null}) {
+  document.cookie = `${name}=${value}` +
+    (path ? `; path=${path}` : '') +
+    '; SameSite=Lax' +
+    (expire ? `; Max-Age=${expire}` : '');
+}

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, '');
+}

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

@@ -1,26 +1,38 @@
 import { domBuilderBasicSetup } from './domBuilderBasicSetup.js';
 import { parseDomString } from './parseDomString.js';
 
-// TODO sintassi stringa su più righe in cui ogni riga corrisponde ad un elemento
-// TODO sintassi stringa come il precedente, ma con possibilità di indicare una nidificazione (indent?)
+// TODO multi-line string syntax where each line maps to an element
+// TODO same as above with optional nesting via indentation
+
+/**
+ * @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[]} [className] - CSS class(es): a single string or an array (falsy values filtered out).
+ * @property {string | string[]} [class] - Alias for `className`.
+ * @property {string | null} [id] - Unique element ID.
+ * @property {[string, *] | [string, *][] | Object<string, *>} [attrs] - Attributes: a `[name, value]` pair, array of pairs, or `{name: value}` object.
+ * @property {string | number | Function | Element | DomBuilderItem[] | null} [content] - Element content.
+ * @property {boolean} [condition=true] - When false, the element is skipped.
+ * @property {function(HTMLElement): void} [callback] - Callback invoked after the element is created.
+ * @property {DomBuilderItem[]} [children] - Configuration array for child elements.
+ */
 
 /**
  * domBuilder
- * Costruisce una struttura DOM a partire da un array di configurazione.
+ * Builds a DOM structure from a configuration array.
  *
- * La funzione analizza un array di oggetti di configurazione per creare elementi HTML.
+ * Parses an array of configuration objects to create HTML elements.
  *
- * **Formato della Struttura di Configurazione (structureArray):**
- *
- * L'array `structureArray` può contenere stringhe (con sintassi abbreviata) e/o oggetti di configurazione:
+ * **Configuration structure format (structureArray):**
  *
  * ```javascript
  * structure = [
  *   '#mainContainer.container',
  *   'p#main-info.info.active{data-id:123,role=button} Lorem ipsum',
  *   {
- *     tag: 'div' | ['.divClass', 'h2#id', 'table.class1', 'thead', 'tr.class2.class3(attr1: attrValue)'], // anche tagName
- *     className: 'xxx' | ['class1', 'class2'], // anche `class`
+ *     tag: 'div' | ['.divClass', 'h2#id', 'table.class1', 'thead', 'tr.class2.class3(attr1: attrValue)'], // also tagName
+ *     className: 'xxx' | ['class1', 'class2'], // also `class`
  *     id: 'element-id',
  *     attrs: [attr_name, attr_value] | [[...], [...]] | {name: value},
  *     content: 'xxx' | 123 | domBuilder Array | function | Element,
@@ -30,45 +42,33 @@ import { parseDomString } from './parseDomString.js';
  *   },
  *   'div.class[data-xxx: value]',
  *   '.another-div',
- *   'p#paragraph''
+ *   'p#paragraph',
  *   '...',
  *   { ... }
  * ]
  * ```
  *
- * id e classi possono essere specificati sia chiave dell'oggetto di configurazione che all'interno dell'oggetto `attrs`
- * In caso di conflitto, prevalgono quelli indicati al livello principale.
+ * IDs and classes can be specified either as top-level object keys or inside the `attrs` object.
+ * When both are present, top-level properties take precedence.
  *
- * È inoltre possibile utilizzare una versione "abbreviata" utilizzando una stringa costruita secondo la sintassi di `parseDomString`.
- * Vedi `parseDomString` per altre in.formazioni.
+ * A shorthand string syntax is also available, built according to `parseDomString` conventions.
+ * See `parseDomString` for details.
  *
- * Questo tipo di sintassi non prevede la possibilità di definire `content`, `callback`, `condition` e `children`: in questi casi è necessario utilizzare la sintassi di base.
+ * The shorthand syntax does not support `content`, `callback`, `condition`, or `children`; use the object syntax for those.
  *
- * La sintassi abbreviata può essere utilizzata anche con l'elemento `tag` della sintassi ad oggetti.
- * È possibile definirlo come array in cui ogni elemento corrisponde al genitore del successivo. Eventuali altre proprietà dell'oggetto
- * (className, callback, ecc.) vengono applicate solo all'ultimo elemento dell'array.
- * In caso di conflitto tra classi, id o attributi indicati nella stringa e quelli indicati nell'oggetto
- * prevalgono questi ultimi.
+ * The shorthand can also be used for the `tag` property in object syntax.
+ * When `tag` is an array, each element becomes the parent of the next one. Any other object properties
+ * (className, callback, etc.) are applied only to the last element in the array.
+ * When shorthand string and object-level properties conflict (classes, id, or attributes),
+ * object-level properties take precedence.
  *
  * @function domBuilder
- * @param {Array<Object|string>} [structureArray=[]] - Array di configurazione degli elementi. Può contenere stringhe (con sintassi abbreviata secondo `parseDomString`) e/o oggetti di configurazione.
- * @param {string|Array<string>} [structureArray[].tag='div'] - Nome del tag HTML (es. 'div', 'p') o array di tag nidificati (es. ['div.container', 'section', 'article']).
- * @param {string|Array<string>} [structureArray[].tagName='div'] - Alias di tag
- * @param {string|Array<string>} [structureArray[].className] - Classe/i CSS: stringa singola o array di classi, in quest'ultimo caso, i valori *falsy* vengopno rimossi.
- * @param {string|Array<string>} [structureArray[].class] - Alias di className.
- * @param {string} [structureArray[].id] - ID univoco dell'elemento.
- * @param {Array<[string, *]>|Array<Array<[string, *]>>|Object<string, *>} [structureArray[].attrs] - Attributi: coppia `[name, value]`, array di coppie o oggetto `{name: value}`.
- * @param {string|number|Function|Element} [structureArray[].content] - Contenuto dell'elemento: stringa, numero, funzione che restituisce contenuto, o HTMLElement.
- * @param {boolean} [structureArray[].condition=true] - Se false, l'elemento non viene generato.
- * @param {Function} [structureArray[].callback] - Callback invocata quando l'elemento viene creato; riceve l'elemento come argomento.
- * @param {Array<Object>} [structureArray[].children] - Array di configurazione per elementi figlio.
- * @param {HTMLElement} [parent] - Elemento genitore al quale appendere la struttura.
- * @param {Object} [options={}] - Opzioni di configurazione.
- * @param {boolean} [options.emptyParent=true] - Se true, l'element parent indicato viene svuotato prima di procedere con ciclo builder
- * @returns {HTMLElement|null} Il primo elemento creato, o null se nessun elemento è stato creato.
+ * @param {Array<DomBuilderItem|string>} [structureArray=[]] - Configuration array. Accepts strings (shorthand per `parseDomString`) and/or configuration objects.
+ * @param {HTMLElement} [parent] - Parent element to append the structure to.
+ * @param {Object} [options={}] - Configuration options.
+ * @param {boolean} [options.emptyParent=false] - When true, the parent element is emptied before building.
+ * @returns {HTMLElement|null} The first created element, or null if nothing was created.
  */
-
-
 export function domBuilder(structureArray = [], parent, options = {}) {
 
   options = {
@@ -76,45 +76,55 @@ export function domBuilder(structureArray = [], parent, options = {}) {
     ...options
   };
 
-  let mainElement = null, el, grand_parent = null;
+  /** @type {HTMLElement | null} */
+  let mainElement = null;
+  /** @type {HTMLElement} */
+  let el;
+  /** @type {HTMLElement | null} */
+  let grand_parent = null;
 
   if(parent && options.emptyParent) {
     parent.innerHTML = '';
   }
 
-  structureArray.forEach(item => {
+  structureArray.forEach(inputItem => {
 
-    if(item != null && typeof item === 'string' && item !== '') {
-      item = parseDomString(item);
+    /** @type {DomBuilderItem | null} */
+    let item;
+    if (inputItem != null && typeof inputItem === 'string' && inputItem !== '') {
+      item = parseDomString(inputItem);
+    } else {
+      item = /** @type {DomBuilderItem} */ (inputItem);
     }
 
     // console.log(item);
 
     if (item != null && (item.condition ?? true)) {
 
+      const safeItem = item; // const binding so TypeScript tracks non-null type in nested closures
 
-      // se tag è un array, vengono creati una serie di elementi nidificati
-      // l'ultimo è quello a cui vengono applicate le altre proprietà dell'oggetto in esame
-      if (Array.isArray(item.tag)) {
+      // when tag is an array, create a series of nested elements;
+      // the last one receives the remaining object properties
+      if (Array.isArray(safeItem.tag)) {
 
-        grand_parent = parent;
+        grand_parent = parent ?? null;
+        const tags = /** @type {string[]} */ (safeItem.tag);
 
-        item.tag.forEach((tagItem, idx) => {
+        tags.forEach((tagItem, idx) => {
 
-          const isLast = idx === item.tag.length - 1;
-          const parsedItem = parseDomString(tagItem);
+          const isLast = idx === tags.length - 1;
+          const parsedItem = parseDomString(tagItem) ?? { tag: 'div', id: undefined, className: '', attrs: {}, content: undefined };
 
-          // nel caso dell'ultimo elemento, merge con le opzioni dell'oggetto
-          // con precedenza alle proprietà di quest'ultimo
+          // for the last element, merge with the object's own options; object-level properties take precedence
           if(isLast) {
-            item.attrs = {...parsedItem.attrs??{}, ...item.attrs??{}};
+            safeItem.attrs = {...parsedItem.attrs ?? {}, ...safeItem.attrs ?? {}};
           }
           el = domBuilderBasicSetup(
             document.createElement(parsedItem.tag || 'div'),
-            {...parsedItem, ...(isLast? item??{} : {})}
+            {...parsedItem, ...(isLast ? safeItem : {})}
           );
 
-          if (!isLast) { // l'ultimo elemento è gestito dalla procedura "standard"
+          if (!isLast) { // the last element is handled by the standard path below
             if (parent) {
               parent.appendChild(el);
             }
@@ -125,40 +135,41 @@ export function domBuilder(structureArray = [], parent, options = {}) {
 
       } else {
         el = domBuilderBasicSetup(
-          document.createElement(item.tag ?? 'div'),
-          item
+          document.createElement(/** @type {string} */ (safeItem.tag) ?? 'div'),
+          safeItem
         );
       }
 
 
-      if (item.content != null) {
+      if (safeItem.content != null) {
 
-        let content = '';
-        if (typeof item.content === 'function') {
-          content = item.content();
+        /** @type {string | Element | null} */
+        let content = null;
+        if (typeof safeItem.content === 'function') {
+          content = safeItem.content();
 
-        } else if (Array.isArray(item.content)) {
-          content = domBuilder(item.content);
+        } else if (Array.isArray(safeItem.content)) {
+          content = domBuilder(safeItem.content);
 
-        } else if (item.content != null) {
-          content = String(item.content);
+        } else if (safeItem.content != null) {
+          content = String(safeItem.content);
         }
 
         if (content instanceof Element) {
           el.appendChild(content);
 
-        } else {
+        } else if (content != null) {
           el.innerHTML = content;
         }
       }
 
 
-      if (item.children != null && !Array.isArray(item.children)) {
+      if (safeItem.children != null && !Array.isArray(safeItem.children)) {
         // eslint-disable-next-line no-console
-        console.error('Error: `item.children` must be an array → ' + item.children);
+        console.error('Error: `item.children` must be an array → ' + safeItem.children);
       }
-      if (item.children && Array.isArray(item.children)) {
-        domBuilder(item.children, el, {emptyParent: false});
+      if (safeItem.children && Array.isArray(safeItem.children)) {
+        domBuilder(safeItem.children, el, {emptyParent: false});
       }
 
       if (mainElement == null) {
@@ -169,19 +180,17 @@ export function domBuilder(structureArray = [], parent, options = {}) {
         parent.appendChild(el);
       }
 
-      // TODO callback che includano azioni relatuvi ai children dell'elemento potrebbero bìnon essere eseguiti in assenza di parent
-      if (item.callback && typeof item.callback === 'function') {
-        item.callback(el);
+      // TODO callbacks that act on the element's children may not run when no parent is set
+      if (safeItem.callback && typeof safeItem.callback === 'function') {
+        safeItem.callback(el);
       }
 
       if (grand_parent) {
         parent = grand_parent;
       }
-    } // end if ((item.condition ?? true) && item != null)
+    }
 
-  }); // end forEach
+  });
 
   return mainElement;
 }
-
-

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

@@ -1,26 +1,29 @@
 
+/** @typedef {import('./dom-builder.js').DomBuilderItem} DomBuilderItem */
+
 /**
- * Esegue le operazione di base del domBuilder: assegnazione classi, id ecc...
+ * Applies basic domBuilder configuration to an element: classes, id, and attributes.
+ * @param {HTMLElement} element - The element to configure.
+ * @param {DomBuilderItem} domBuilderItem - The domBuilder configuration object.
+ * @returns {HTMLElement}
  */
 export function domBuilderBasicSetup (element, domBuilderItem) {
 
-  // classi
-  // possibili denominazioni: class o className
-  // se presente className, class viene ignorato
+  // class aliases: accept both `class` and `className`; `className` takes precedence
   if (domBuilderItem.class && !domBuilderItem.className) {
     domBuilderItem.className = domBuilderItem.class;
   }
 
-  // se item.attrs è un array singolo viene trattato come singolo elemento
+  // normalize attrs: a single flat array is treated as a single [name, value] pair
   if (domBuilderItem.attrs && Array.isArray(domBuilderItem.attrs) && !Array.isArray(domBuilderItem.attrs[0])) {
     domBuilderItem.attrs = [ domBuilderItem.attrs ];
 
-  // item.attrs può essere un oggetto del tipo {attr_name: attr_value}
+  // attrs can also be a plain object: {attr_name: attr_value}
   } else if (typeof domBuilderItem.attrs === 'object' && !Array.isArray(domBuilderItem.attrs) && domBuilderItem.attrs !== null) {
     domBuilderItem.attrs = Object.entries(domBuilderItem.attrs);
   }
 
-  // gli attributi booleani non vengono aggiunti se il loro valore è false
+  // boolean attributes are omitted when their value is explicitly false
   const boolAttrs = [
     'allowfullscreen',
     'async',
@@ -54,13 +57,13 @@ export function domBuilderBasicSetup (element, domBuilderItem) {
 
 
 
-  (domBuilderItem.attrs ?? []).forEach(attr => {
+  (/** @type {[string, unknown][]} */ (domBuilderItem.attrs ?? [])).forEach(attr => {
     if (attr[1] != null && !(boolAttrs.includes(attr[0]) && attr[1]=== false)) {
       element.setAttribute(attr[0], String(attr[1]));
     }
   });
 
-  // assegnazioen classi e id (dopo attrs in modo che le proprietà a livello di oggetto prevalgano)
+  // assign classes and id after attrs so object-level properties take precedence
   if(domBuilderItem.className) {
     element.className = Array.isArray(domBuilderItem.className)
       ? domBuilderItem.className.filter(Boolean).join(' ')

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

@@ -1,48 +1,47 @@
 /**
- * Analizza una stringa per estrarre il nome del tag, l'ID, le classi e gli attributi.
+ * Parses a string to extract tag name, ID, classes, and attributes.
  *
- * * Il formato della stringa atteso è:
+ * Expected string format:
  *
- * `tag#id.classe1.classe2.classeN(attributo1: valore1, attributo2=valore2) Lorem ipsum`
+ * `tag#id.class1.class2.classN(attr1: val1, attr2=val2) text content`
  *
- * In cui:
- * * `tag` è il nome dell'elemento, se non specificato si assume che sia un `div`
- * * `id` è l'id, facoltativo, da assegnare all'elemento, deve essere preeceduto da `#` e deve essere posizionato subito dopo il tag
- * * `classe1, classe2...` sono le classi, facoltative, devono essere precedute da `.`
- * * `(...)` è il blocco degli attributi, facoltativo. Oltre che dalle parentesi tonde, questa parte può essere delimitata dalle quadre e dalle graffe.
- *   Ogni coppia _nome-valore_ va separata con `:` o `=`. Se presente solo il nome, si assume che il valore sia `true`.
- * * `Lorem ipsum` indica un eventuale contenuto testuale, separato dal blocco precedente da uno spazio
+ * Where:
+ * * `tag` is the element name; defaults to `div` if omitted
+ * * `#id` is the optional element id; must immediately follow the tag
+ * * `.class1, .class2...` are optional CSS classes, each preceded by `.`
+ * * `(...)` is the optional attribute block; can also use `[...]` or `{...}`.
+ *   Each name–value pair is separated by `:` or `=`. A bare name (no value) defaults to `true`.
+ * * Text content follows after a space
  *
- * Restituisce un oggetto *child* domBuilder
+ * Returns a domBuilder child object.
  *
- * Esempio:
+ * Examples:
  * > p#main-info.info.active{data-id:123,role=button} text content
  *
- * oppure
  * > input#search-field[type=text,disabled]
  *
- * @param {string} domString La stringa DOM Builder da analizzare.
- * @returns {{tagName: string, id: string, classes: string[], attributes: {[key: string]: string}}}
+ * @param {string} domString - The domBuilder string to parse.
+ * @returns {{tag: string, id: string|null, className: string, attrs: Object<string, string|true>, content: string|null}|null}
  */
 
 export function parseDomString(domString) {
 
-  // versione con groups
+  // version using named capture groups (kept for reference)
   // const regex = new RegExp(
   //   /^(?<tag>[a-zA-Z][a-zA-Z0-9-]*)?/.source +    // tag
   //   /(?:#(?<id>[a-zA-Z0-9_-]+))?/.source +        // id
-  //   /(?<classes>(?:\.[a-zA-Z0-9_-]+)*)?/.source + // classi
+  //   /(?<classes>(?:\.[a-zA-Z0-9_-]+)*)?/.source + // classes
   //   /(?<attrs>[([{].*?[)\]}])?/.source +          // attrs
   //   /(?: +(?<content>.*))?$/.source               // content
   // );
 
 
-// FIX non funziona se la stringa contine id e classi in quest'ordine: <TAG>.<CLASSE>#<ID>, se l'id è prima della classe, funziona
+// FIX: does not work when id follows classes: <TAG>.<CLASS>#<ID>; id must precede classes
 
   const regex = new RegExp(
-    /^([a-zA-Z][a-zA-Z0-9-]*)?/.source +  // tag (accetta anche nomi di web components)
+    /^([a-zA-Z][a-zA-Z0-9-]*)?/.source +  // tag (also accepts web component names)
     /(?:#([a-zA-Z0-9_-]+))?/.source +     // id
-    /((?:\.[a-zA-Z0-9_-]+)*)?/.source +   // classi
+    /((?:\.[a-zA-Z0-9_-]+)*)?/.source +   // classes
     /([([{].*?[)\]}])?/.source +          // attrs
     /(?: +(.*))?$/.source                 // content
   );
@@ -54,12 +53,12 @@ export function parseDomString(domString) {
     return null;
   }
 
-  // Nuovi gruppi di cattura (match array):
-  // [0]: intera stringa
-  // [1]: Tag
-  // [2]: ID
-  // [3]: Classi
-  // [4]: Attributi (raw)
+  // Capture group indices:
+  // [0]: full match
+  // [1]: tag
+  // [2]: id
+  // [3]: classes
+  // [4]: raw attributes
   // [5]: content
 
   const tag = (matches[1] || 'div').toLowerCase(),
@@ -69,7 +68,7 @@ export function parseDomString(domString) {
     content =  matches[5]?.trim() || null
   ;
 
-  // versione con uso di `groups`
+  // version using named capture groups (kept for reference)
   // const tag = (matches.groups.tag || 'div').toLowerCase(),
   //   id = matches.groups.id?.trim() || null,
   //   classes = matches.groups.classes? matches[3].slice(1).split('.').map(c => c.trim()) : [],
@@ -77,6 +76,7 @@ export function parseDomString(domString) {
   //   content =  matches.groups.content?.trim() || null
   // ;
 
+  /** @type {Record<string, string | true>} */
   const attrs = {};
   if (rawAttrs) {
     const attrsContent = rawAttrs.substring(1, rawAttrs.length - 1);
@@ -86,10 +86,12 @@ export function parseDomString(domString) {
       if (!pair) return;
       if (pair.includes('=') || pair.includes(':')) {
         const parts = pair.split(/[:=]/, 2),
-          name = parts[0]?.trim(),
+          name = parts[0]?.trim() ?? '',
           value = parts[1] != null ? parts[1].trim() : true;
 
-        attrs[name] = value;
+        if (name) {
+          attrs[name] = value;
+        }
 
       } else {
 

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

@@ -1,5 +1,11 @@
+/**
+ * Re-enables all submit and non-disabled button elements within the given context.
+ * @param {Document | Element} [context=document]
+ * @returns {void}
+ */
 export function enableSubmitBtns(context = document) {
   context.querySelectorAll('[type=submit], [type=button]:not([data-disabled])').forEach(btn => {
-    btn.disabled = false;
+    const button = /** @type {HTMLButtonElement | HTMLInputElement} */ (btn);
+    button.disabled = false;
   });
 }

package/src/utilities/{escapeHTML.js → escape-html.js}

@@ -1,3 +1,4 @@
+/** @type {Record<string, string>} */
 const ESCAPE_MAP = {
   '&'  : '&amp;',
   '"'  : '&quot;',
@@ -5,10 +6,22 @@ const ESCAPE_MAP = {
   '<'  : '&lt;',
   '>'  : '&gt;'
 };
+/** @type {Record<string, string>} */
 const UNESCAPE_MAP = Object.fromEntries(Object.entries(ESCAPE_MAP).map(([k, v]) => [v, k]));
 
 const ESCAPE_RE = /[&"'<>]/g;
 const UNESCAPE_RE = /&amp;|&quot;|&#039;|&lt;|&gt;/g;
 
+/**
+ * Escapes special HTML characters in a string.
+ * @param {string | null | undefined} str
+ * @returns {string}
+ */
 export const escapeHTML = str => str?.replace(ESCAPE_RE, m => ESCAPE_MAP[m]) ?? '';
+
+/**
+ * Unescapes HTML entities back to their original characters.
+ * @param {string | null | undefined} str
+ * @returns {string}
+ */
 export const unescapeHTML = str => str?.replace(UNESCAPE_RE, m => UNESCAPE_MAP[m]) ?? '';