@massimo-cassandro/minimo 1.10.1 → 1.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",
@@ -36,6 +36,7 @@
     "upd@m": "npx upd@m",
     "build-tokens": "node ./design-tokens/utilities/build-tokens.mjs --config ./design-tokens/tokens-config.mjs",
     "check unresolved props": "node ./design-tokens/utilities/check-unresolved-custom-props.mjs --config ./design-tokens/tokens-config.mjs",
+    "test": "node --test \"test/**/*.test.mjs\"",
     "checkJS": "npx tsc --noEmit -p jsconfig.json",
     "checkJS ./src": "npx tsc --noEmit --allowJs --checkJs --target ES2023 --module ESNext --allowSyntheticDefaultImports --moduleResolution bundler declarations.d.ts src/**/*.js"
   },
@@ -68,6 +69,7 @@
   "devDependencies": {
     "@massimo-cassandro/eslint-config": "^3.0.11",
     "@massimo-cassandro/stylelint-config": "^2.3.11",
+    "jsdom": "^29.1.1",
     "style-dictionary": "^5.5.0"
   },
   "dependencies": {

package/src/components/form-reset-submit.js

@@ -1,5 +1,5 @@
 // import './form.css'; // included in the main CSS entry point
-import { enableSubmitBtns } from '../../index.js';
+import { enableSubmitBtns } from '../utilities/enable-submit-btns.js';
 
 /**
  * Wires up submit validation and button-disabling behaviour on all forms.

package/src/utilities/better-text.js

@@ -1,5 +1,41 @@
 // @ts-check
 
+// Italian particles/articles (plus a few English and topographic terms) whose casing is
+// enforced and after which spaces are turned into non-breaking spaces. Hoisted to module
+// scope with the regexes/lookup built from it below, since none of this depends on the
+// function's arguments and was previously rebuilt on every single betterText() call.
+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'
+];
+
+// matches a particle followed by one-or-more spaces, to be turned into non-breaking spaces
+const NBSP_AFTER_PARTICLE_REGEX = new RegExp('\\b(' + PARTICELLE.join('|') + ')\\b +', 'gmi');
+
+// matches any particle regardless of case, to enforce its exact casing in a single pass
+const PARTICLE_CASING_REGEX = new RegExp('\\b(' + PARTICELLE.join('|') + ')\\b', 'gmi');
+
+// lowercased particle → its exact casing, for the replacer used with PARTICLE_CASING_REGEX
+const PARTICLE_CASING_MAP = new Map(PARTICELLE.map(term => [term.toLowerCase(), term]));
+
 /**
  * Improves a text string by fixing punctuation spacing, multiple spaces,
  * typographic quotes, non-breaking spaces after Italian particles/articles,
@@ -11,29 +47,6 @@
  */
 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();
 
@@ -57,16 +70,12 @@ export function betterText(str, custom_words = []) {
     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) {
+    str = str.replace(NBSP_AFTER_PARTICLE_REGEX, 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);
-    });
+    // enforce exact casing of every particle in a single pass
+    str = str.replace(PARTICLE_CASING_REGEX, match => PARTICLE_CASING_MAP.get(match.toLowerCase()) ?? match);
 
     if(custom_words.length) {
       custom_words.forEach(item => {

package/src/utilities/cookies.js

@@ -19,6 +19,14 @@ export function getCookie(name) {
  * @param {string} params.value
  * @param {string|null} [params.path=null]
  * @param {number|null} [params.expire=null] - Max-Age in seconds
+ * @example
+ * // Cookie scoped to the current page only, lasting 15 days
+ * setCookie({
+ *   name: 'cookieName',
+ *   value: 'cookieValue',
+ *   path: window.location.pathname,
+ *   expire: 15 * 24 * 60 * 60 // 15 days
+ * });
  */
 export function setCookie({name, value, path = null, expire = null}) {
   document.cookie = `${name}=${value}` +

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

@@ -13,6 +13,9 @@ import { parseDomString } from './parseDomString.js';
  * @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.
+ *   A string or number is set as plain text (`textContent`) unless it contains `<`, in which case it is
+ *   treated as markup: sanitized and inserted via the native Sanitizer API (`Element.setHTML`) where
+ *   supported, falling back to raw `innerHTML` on browsers without it.
  * @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.
@@ -35,7 +38,7 @@ import { parseDomString } from './parseDomString.js';
  *     className: 'xxx' | ['class1', 'class2'], // also `class`
  *     id: 'element-id',
  *     attrs: [attr_name, attr_value] | [[...], [...]] | {name: value},
- *     content: 'xxx' | 123 | domBuilder Array | function | Element,
+ *     content: 'xxx' | 'xxx <strong>yyy</strong>' | 123 | domBuilder Array | function | Element, // see DomBuilderItem.content above
  *     condition: true | false,
  *     callback: el => ...,
  *     children: [...]
@@ -78,20 +81,30 @@ export function domBuilder(structureArray = [], parent, options = {}) {
     ...options
   };
 
-  /** @type {Map<HTMLElement, HTMLElement>} tracks, for `insertMode: 'after'`, the last inserted sibling per parent node */
+  if(parent && options.emptyParent) {
+    parent.innerHTML = '';
+  }
+
+  // For the default 'append' insert mode, root-level siblings are accumulated into a
+  // DocumentFragment and attached to `parent` with a single appendChild at the end,
+  // instead of one appendChild per sibling. 'before'/'after' modes need `target` to stay
+  // the real, live parent node throughout the loop for anchor resolution (see afterAnchors
+  // below), so batching is skipped for those.
+  const useFragment = !!parent && options.insertMode === 'append';
+
+  /** @type {HTMLElement | DocumentFragment | null} */
+  let target = useFragment ? document.createDocumentFragment() : (parent ?? null);
+
+  /** @type {Map<HTMLElement | DocumentFragment, HTMLElement>} tracks, for `insertMode: 'after'`, the last inserted sibling per parent node */
   const afterAnchors = new Map();
 
   /** @type {HTMLElement | null} */
   let mainElement = null;
   /** @type {HTMLElement} */
   let el;
-  /** @type {HTMLElement | null} */
+  /** @type {HTMLElement | DocumentFragment | null} */
   let grand_parent = null;
 
-  if(parent && options.emptyParent) {
-    parent.innerHTML = '';
-  }
-
   structureArray.forEach(inputItem => {
 
     /** @type {DomBuilderItem | null} */
@@ -112,7 +125,7 @@ export function domBuilder(structureArray = [], parent, options = {}) {
       // the last one receives the remaining object properties
       if (Array.isArray(safeItem.tag)) {
 
-        grand_parent = parent ?? null;
+        grand_parent = target;
         const tags = /** @type {string[]} */ (safeItem.tag);
 
         tags.forEach((tagItem, idx) => {
@@ -130,10 +143,10 @@ export function domBuilder(structureArray = [], parent, options = {}) {
           );
 
           if (!isLast) { // the last element is handled by the standard path below
-            if (parent) {
-              parent.appendChild(el);
+            if (target) {
+              target.appendChild(el);
             }
-            parent = el;
+            target = el;
           }
 
         });
@@ -148,23 +161,43 @@ export function domBuilder(structureArray = [], parent, options = {}) {
 
       if (safeItem.content != null) {
 
-        /** @type {string | Element | null} */
-        let content = null;
-        if (typeof safeItem.content === 'function') {
-          content = safeItem.content();
+        if (Array.isArray(safeItem.content)) {
+          // build directly into `el` (instead of passing no parent) so that every item of
+          // the array is actually inserted, not just the first one returned as `mainElement`
+          domBuilder(safeItem.content, el);
 
-        } else if (Array.isArray(safeItem.content)) {
-          content = domBuilder(safeItem.content);
+        } else {
 
-        } else if (safeItem.content != null) {
-          content = String(safeItem.content);
-        }
+          /** @type {string | Element | null} */
+          let content = null;
+          if (typeof safeItem.content === 'function') {
+            content = safeItem.content();
+
+          } else if (safeItem.content != null) {
+            content = String(safeItem.content);
+          }
+
+          if (content instanceof Element) {
+            el.appendChild(content);
+
+          } else if (content != null) {
 
-        if (content instanceof Element) {
-          el.appendChild(content);
+            if (!content.includes('<')) {
+              // plain text: no HTML parsing needed, textContent is faster and safe by construction
+              el.textContent = content;
 
-        } else if (content != null) {
-          el.innerHTML = content;
+            } else if (typeof el.setHTML === 'function') {
+              // markup: sanitize via the native Sanitizer API, stripping <script>, event handler
+              // attributes, javascript: URLs, etc. while still allowing harmless formatting tags
+              // (<strong>, <em>, <a>, ...)
+              el.setHTML(content);
+
+            } else {
+              // Sanitizer API not supported by this browser: fall back to the historical,
+              // unsanitized behavior
+              el.innerHTML = content;
+            }
+          }
         }
       }
 
@@ -181,17 +214,18 @@ export function domBuilder(structureArray = [], parent, options = {}) {
         mainElement = el;
       }
 
-      if (parent) {
+      if (target) {
         if (options.insertMode === 'before') {
-          parent.parentNode?.insertBefore(el, parent);
+          const anchor = /** @type {HTMLElement} */ (target);
+          anchor.parentNode?.insertBefore(el, anchor);
 
         } else if (options.insertMode === 'after') {
-          const anchor = afterAnchors.get(parent) ?? parent;
+          const anchor = afterAnchors.get(/** @type {HTMLElement} */ (target)) ?? /** @type {HTMLElement} */ (target);
           anchor.parentNode?.insertBefore(el, anchor.nextSibling);
-          afterAnchors.set(parent, el);
+          afterAnchors.set(/** @type {HTMLElement} */ (target), el);
 
         } else {
-          parent.appendChild(el);
+          target.appendChild(el);
         }
       }
 
@@ -201,11 +235,15 @@ export function domBuilder(structureArray = [], parent, options = {}) {
       }
 
       if (grand_parent) {
-        parent = grand_parent;
+        target = grand_parent;
       }
     }
 
   });
 
+  if (useFragment && parent && target) {
+    parent.appendChild(target);
+  }
+
   return mainElement;
 }

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

@@ -1,6 +1,39 @@
 
 /** @typedef {import('./dom-builder.js').DomBuilderItem} DomBuilderItem */
 
+// boolean attributes are omitted when their value is explicitly false;
+// declared once at module level (Set for O(1) lookup) since the list never changes between calls
+const boolAttrs = new Set([
+  'allowfullscreen',
+  'async',
+  'autocomplete',
+  'autofocus',
+  'autoplay',
+  'border',
+  'checked',
+  'compact',
+  'contenteditable',
+  'controls',
+  'default',
+  'loop',
+  'defer',
+  'disabled',
+  'formnovalidate',
+  'hidden',
+  'inert',
+  'ismap',
+  'multiple',
+  'muted',
+  'novalidate',
+  'open',
+  'readonly',
+  'required',
+  'reversed',
+  'selected',
+  'spellcheck',
+  'translate'
+]);
+
 /**
  * Applies basic domBuilder configuration to an element: classes, id, and attributes.
  * @param {HTMLElement} element - The element to configure.
@@ -23,42 +56,8 @@ export function domBuilderBasicSetup (element, domBuilderItem) {
     domBuilderItem.attrs = Object.entries(domBuilderItem.attrs);
   }
 
-  // boolean attributes are omitted when their value is explicitly false
-  const boolAttrs = [
-    'allowfullscreen',
-    'async',
-    'autocomplete',
-    'autofocus',
-    'autoplay',
-    'border',
-    'checked',
-    'compact',
-    'contenteditable',
-    'controls',
-    'default',
-    'loop',
-    'defer',
-    'disabled',
-    'formnovalidate',
-    'hidden',
-    'inert',
-    'ismap',
-    'multiple',
-    'muted',
-    'novalidate',
-    'open',
-    'readonly',
-    'required',
-    'reversed',
-    'selected',
-    'spellcheck',
-    'translate'
-  ];
-
-
-
   (/** @type {[string, unknown][]} */ (domBuilderItem.attrs ?? [])).forEach(attr => {
-    if (attr[1] != null && !(boolAttrs.includes(attr[0]) && attr[1]=== false)) {
+    if (attr[1] != null && !(boolAttrs.has(attr[0]) && attr[1] === false)) {
       element.setAttribute(attr[0], String(attr[1]));
     }
   });

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

@@ -1,3 +1,11 @@
+// compiled once at module load, since the pattern never changes between calls
+const DOM_STRING_REGEX = new RegExp(
+  /^([a-zA-Z][a-zA-Z0-9-]*)?/.source +    // tag (also accepts web component names)
+  /((?:[#.][a-zA-Z0-9_-]+)*)?/.source +   // id and classes, in any order
+  /([([{].*?[)\]}])?/.source +            // attrs
+  /(?: +(.*))?$/.source                   // content
+);
+
 /**
  * Parses a string to extract tag name, ID, classes, and attributes.
  *
@@ -24,17 +32,9 @@
  * @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) {
 
-  const regex = new RegExp(
-    /^([a-zA-Z][a-zA-Z0-9-]*)?/.source +    // tag (also accepts web component names)
-    /((?:[#.][a-zA-Z0-9_-]+)*)?/.source +   // id and classes, in any order
-    /([([{].*?[)\]}])?/.source +            // attrs
-    /(?: +(.*))?$/.source                   // content
-  );
-
-  const matches = domString.match(regex);
+  const matches = domString.match(DOM_STRING_REGEX);
 
 
   if (!matches) {