@massimo-cassandro/minimo 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",
@@ -31,6 +31,7 @@
     "url": "git+https://github.com/massimo-cassandro/minimo.git"
   },
   "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
     "UPD-version": "npx update-version  # --config=./dev-utilities.config.mjs",
     "npm-publish": "npm publish",
     "upd@m": "npx upd@m",
@@ -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/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.
  *
@@ -7,8 +15,9 @@
  *
  * Where:
  * * `tag` is the element name; defaults to `div` if omitted
- * * `#id` is the optional element id; must immediately follow the tag
+ * * `#id` is the optional element id, preceded by `#`
  * * `.class1, .class2...` are optional CSS classes, each preceded by `.`
+ * * `#id` and `.class` tokens can appear in any order and interleaved (e.g. `.class1#id.class2`)
  * * `(...)` 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
@@ -23,59 +32,33 @@
  * @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) {
 
-  // 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 + // classes
-  //   /(?<attrs>[([{].*?[)\]}])?/.source +          // attrs
-  //   /(?: +(?<content>.*))?$/.source               // content
-  // );
-
-
-// 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 (also accepts web component names)
-    /(?:#([a-zA-Z0-9_-]+))?/.source +     // id
-    /((?:\.[a-zA-Z0-9_-]+)*)?/.source +   // classes
-    /([([{].*?[)\]}])?/.source +          // attrs
-    /(?: +(.*))?$/.source                 // content
-  );
-
-  const matches = domString.match(regex);
+  const matches = domString.match(DOM_STRING_REGEX);
 
 
   if (!matches) {
     return null;
   }
 
-  // Capture group indices:
+  // Capture group indexes:
   // [0]: full match
   // [1]: tag
-  // [2]: id
-  // [3]: classes
-  // [4]: raw attributes
-  // [5]: content
+  // [2]: id and classes (e.g. "#id.class1.class2" or ".class1#id.class2")
+  // [3]: raw attributes
+  // [4]: content
+
+  const idAndClasses = matches[2] || '',
+    idMatch = idAndClasses.match(/#([a-zA-Z0-9_-]+)/),
+    classMatches = [...idAndClasses.matchAll(/\.([a-zA-Z0-9_-]+)/g)];
 
   const tag = (matches[1] || 'div').toLowerCase(),
-    id = matches[2]?.trim() || null,
-    classes = matches[3] ? matches[3].slice(1).split('.').map(c => c.trim()) : [],
-    rawAttrs = matches[4]?.trim() || null,
-    content =  matches[5]?.trim() || null
+    id = idMatch?.[1] || null,
+    classes = classMatches.map(m => m[1]),
+    rawAttrs = matches[3]?.trim() || null,
+    content =  matches[4]?.trim() || null
   ;
 
-  // 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()) : [],
-  //   rawAttrs = matches.groups.attrs?.trim() || null,
-  //   content =  matches.groups.content?.trim() || null
-  // ;
-
   /** @type {Record<string, string | true>} */
   const attrs = {};
   if (rawAttrs) {

package/src/utilities/validation-error-class.js

@@ -16,7 +16,7 @@ form.addEventListener('submit', e => {
   form.classList.add('was-validated');
   try {
     if( ... ) {
-      throw new ValidationError('__message__', [errorFields, ...] );
+      throw new ValidationError('__message__', [errorFields, ...] ); // errorFields is optional
     }
   } catch( error ) {
     e.preventDefault();
@@ -38,7 +38,7 @@ form.addEventListener('submit', e => {
         }, {once: true});
       });
 
-      error.fields[0]?.focus({preventScroll:false});
+      error.fields?.[0]?.focus({preventScroll:false});
     }
     mAlert({
       type  : 'error',