@massimo-cassandro/minimo 1.45.0 → 1.46.0

package/dev-tools/custom-media-builder/custom-media-builder.mjs

@@ -5,6 +5,7 @@ import fs from 'fs';
 import path from 'path';
 import process from 'process';
 import { pathToFileURL } from 'url';
+import { styleText } from 'util';
 
 /**
  * Genera il file css delle @custom-media.
@@ -30,6 +31,7 @@ export async function buildCustomMedia({
   const srcPath = path.resolve(src),
     destPath = path.resolve(dest ?? srcPath.replace(/\.m?js$/, '.css'));
 
+
   const { default: customMedia } = await import(pathToFileURL(srcPath).href);
 
   if (!customMedia || typeof customMedia !== 'object') {
@@ -44,7 +46,7 @@ export async function buildCustomMedia({
   });
 
   const content = '/* File generato da custom-media-builder.mjs a partire da ' +
-    `${path.basename(srcPath)}. Eventuali modifich andranno perdute */\n\n` +
+    `${path.basename(srcPath)}.\nEVENTUALI MODIFICHE ANDRANNO PERDUTE */\n\n` +
     rows.join('\n') + '\n';
 
   if (fs.existsSync(destPath) && fs.readFileSync(destPath, 'utf8') === content) {
@@ -56,7 +58,7 @@ export async function buildCustomMedia({
 }
 
 // esecuzione da riga di comando
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {
   const args = Object.fromEntries(
     process.argv.slice(2)
       .map(arg => arg.match(/^--(src|dest)=(.+)$/))
@@ -66,7 +68,9 @@ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.ar
 
   try {
     const written = await buildCustomMedia(args);
-    console.log(written ? 'custom media: file aggiornato' : 'custom media: nessuna modifica');
+
+    console.log(styleText('yellow', written ? 'custom media: file aggiornato' : 'custom media: nessuna modifica'));
+
   } catch (err) {
     console.error(err.message);
     process.exit(1);

package/dev-tools/starter-kit/source_files/_private/sf.md

@@ -8,5 +8,6 @@
 ## svuota cache
 ```bash
 cd /path/to/project/dir
-sudo php bin/console cache:clear --env=prod
+sudo php bin/console cache:clear # solo cache dell'ambiente configurato
+sudo php bin/console cache:clear --env=prod # solo cache prod
 ```

package/dev-tools/starter-kit/source_files/root/_gitignore

@@ -14,6 +14,8 @@
 /config/reference.php
 /var/
 /vendor/
+/.phpunit.cache/
+.phpunit.result.cache
 ###< symfony/framework-bundle ###
 
 
@@ -24,3 +26,4 @@ _reports/**/*.html
 public/_dev
 unresolved-unused-props.md
 orphan-classes.md
+.symfony.*.y*ml

package/dev-tools/starter-kit/source_files/root/_symfony.local.yaml

@@ -0,0 +1,29 @@
+# .symfony.local.yaml
+#
+# Worker Messenger avviato insieme a `symfony serve`.
+# Si ferma con il server (Ctrl+C, oppure `symfony server:stop` se avviato con -d).
+#
+# SE IL WORKER RESTA ATTIVO DOPO LO SPEGNIMENTO DEL SERVER
+# (terminale chiuso bruscamente, `kill -9`, crash del server):
+#
+#   1. Verificare se esiste un processo orfano:
+#        ps aux | grep messenger:consume | grep -v grep
+#
+#   2. Fermarlo (SIGTERM: Messenger termina il messaggio in corso prima di uscire):
+#        pkill -f messenger:consume
+#
+#   3. Se dopo qualche secondo è ancora presente, forzare l'arresto:
+#        pkill -9 -f messenger:consume
+#
+# Fare il controllo anche prima di riavviare il server, per evitare due
+# consumer sulla stessa coda (quello vecchio non è più monitorato da `watch`
+# e userebbe codice non aggiornato).
+#
+# Per avviare il server senza worker: symfony serve --no-workers
+
+# workers:
+#     messenger:
+#         cmd: ['symfony', 'console', 'messenger:consume', 'async', '--time-limit=3600', '--memory-limit=256M', '-vv']
+#         watch: ['config', 'src', 'templates']
+    # webpack:
+    #     cmd: ['npm', 'run', 'webpack DEV']

package/dev-tools/starter-kit/source_files/root/eslint.config.mjs

@@ -12,20 +12,12 @@ export default [
   // })),
 
   ...eslint_config,
-  // {
-  //   files: ['src/**/*.js'],
-  //   ignores: [
-  //     'dist/',
-  //     'build/',
-  //     '**/vendor/'
-  //   ],
-  // }
-  // {
-  //   languageOptions: {
-  //     globals: {
-  //       jQuery: 'readonly',
-  //       $: 'readonly',
-  //     },
-  //   },
-  // },
+  {
+    files: ['app/**/*.js'],
+    languageOptions: {
+      globals: {
+        process: 'readonly'
+      }
+    }
+  }
 ];

package/dev-tools/starter-kit/source_files/root/webpack.config-tpl.mjs

@@ -20,7 +20,7 @@ import CopyWebpackPlugin from 'copy-webpack-plugin';
 import RemoveEmptyScriptsPlugin from 'webpack-remove-empty-scripts';
 // import HtmlWebpackInjectAttributesPlugin from 'html-webpack-inject-attributes-plugin';
 
-// NB: symfony -> decommentare WebpackManifestPlugin
+// SETUP symfony -> decommentare WebpackManifestPlugin
 // import { WebpackManifestPlugin } from 'webpack-manifest-plugin';
 
 import { cssRules } from './webpack-config-modules/css-rules.mjs';
@@ -506,7 +506,7 @@ const config = {
     // SETUP symfony (decommentare)
     // =>> plugins: WebpackManifestPlugin
     // new WebpackManifestPlugin({
-    //   fileName: path.join(output_dir, 'manifest.json'), // NB: symfony -> fileName: 'manifest.json', // scrive in output.path
+    //   fileName: path.join(output_dir, 'manifest.json'), // SETUP symfony -> fileName: 'manifest.json', // scrive in output.path
     //   // basePath: item.source_dirname
     //   // removeKeyHash: /\?.*$/, // /([a-f0-9]{32}\.?)/gi, // /(\?as_asset)$/,
     //   // rimuove dal manifest i font non woff2 (non necessari, rendono il file inutilmente grande);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./src/index.js",
@@ -83,7 +83,7 @@
     "!**/TODO*"
   ],
   "peerDependencies": {
-    "@svgdotjs/svg.js": "^3.2.7",
+    "@svgdotjs/svg.js": "^3.2.8",
     "blurhash": "^2.0.5",
     "simple-datatables": "^10.3.0",
     "style-dictionary": "^5.0.0"
@@ -104,27 +104,27 @@
   },
   "devDependencies": {
     "@massimo-cassandro/eslint-config": "^3.0.19",
-    "@types/node": "^26.2.0",
-    "jsdom": "^30.0.1",
-    "style-dictionary": "^5.5.1"
+    "@types/node": "^26.6.5",
+    "jsdom": "^30.1.3",
+    "style-dictionary": "^5.7.0"
   },
   "dependencies": {
-    "@inquirer/input": "^5.1.2",
-    "@inquirer/select": "^5.2.1",
+    "@inquirer/input": "^5.1.7",
+    "@inquirer/select": "^5.2.6",
     "@stylistic/stylelint-config": "^5.0.0",
-    "@stylistic/stylelint-plugin": "^5.3.0",
+    "@stylistic/stylelint-plugin": "^5.3.1",
     "clipboardy": "^5.3.2",
     "json5": "^2.2.3",
-    "sharp": "^0.35.3",
+    "sharp": "^0.35.5",
     "sharp-ico": "^0.1.5",
-    "stylelint": "^17.15.0",
+    "stylelint": "^17.16.0",
     "stylelint-config-css-modules": "^4.6.0",
     "stylelint-config-recess-order": "^7.8.0",
     "stylelint-config-standard": "^40.0.0",
     "stylelint-config-standard-scss": "^17.0.0",
-    "stylelint-order": "^8.1.1",
-    "stylelint-scss": "^7.2.0",
-    "svgo": "^4.0.2"
+    "stylelint-order": "^8.1.2",
+    "stylelint-scss": "^7.3.0",
+    "svgo": "^4.1.0"
   },
   "directories": {
     "doc": "docs",

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

@@ -1,13 +1,14 @@
 /*! minimo - DOM Builder */
 import { domBuilderBasicSetup } from './domBuilderBasicSetup.js';
 import { parseDomString } from './parseDomString.js';
+import { createDomElement, normalizeNamespace } from './resolveNamespace.js';
 
 // TODO sintassi stringa multi-riga in cui ogni riga corrisponde a un elemento
 // TODO come sopra, con nidificazione opzionale tramite indentazione
 
 /**
  * @typedef {Object} DomBuilderItem
- * @property {string | string[]} [tag='div'] - Nome del tag HTML o array di tag annidati (ciascuno è il genitore del successivo). Anche `tagName` (default: 'div')
+ * @property {string | string[]} [tag='div'] - Nome del tag o array di tag annidati (ciascuno è il genitore del successivo). Anche `tagName`. La grafia viene conservata, necessaria per i tag SVG come `linearGradient` (default: 'div')
  * @property {string | string[]} [tagName='div'] - Alias di `tag` (default: 'div')
  * @property {string | string[]} [className] - Classe/i CSS: una singola stringa o un array (i valori falsy vengono scartati).
  * @property {string | string[]} [class] - Alias di `className`.
@@ -20,12 +21,20 @@ import { parseDomString } from './parseDomString.js';
  *   (`Element.setHTML`) dove supportata, con ripiego su `innerHTML` grezzo nei browser che non la hanno.
  *   Un `Node` (un `Element`, un `DocumentFragment`, ...) viene aggiunto così com'è, direttamente o
  *   restituito da una funzione.
+ *   Il markup viene letto nel contesto dell'elemento: dentro un `svg` diventa SVG. Attenzione: la Sanitizer API
+ *   rimuove `<use>` anche con `sanitizer: {}` (fa parte della baseline di sicurezza del browser), quindi per le
+ *   icone SVG va usata la sintassi a oggetto (`{ tag: 'use', attrs: { href: '...' } }`), non una stringa di markup.
+ * @property {'html' | 'svg' | 'math' | string} [namespace] - Namespace dell'elemento: un alias (`'html'`, `'svg'`, `'math'`)
+ *   o un URI completo. Se presente ha la precedenza sulla risoluzione automatica; i figli lo ereditano tramite il
+ *   namespace del genitore. Con `tag` array si applica al primo elemento della catena (gli altri lo ereditano).
+ *   Un valore non valido produce un `console.error` e l'elemento viene creato in HTML.
+ *   Non disponibile nella sintassi abbreviata a stringa (default: assente, risoluzione automatica)
  * @property {string | number} [text] - Scorciatoia per un nodo di testo letterale: inserisce un nodo `Text` semplice (mai
  *   interpretato come markup) al posto di un elemento, così da poter essere fratello dei tag negli array
  *   `children`/`content`. Mutuamente esclusivo con `tag`/`content`/`children`: quando è impostato (e `tag` è assente),
  *   ogni altra proprietà tranne `condition` e `callback` viene ignorata.
  * @property {boolean} [condition=true] - Se false, l'elemento (o il nodo di testo) viene saltato (default: true)
- * @property {((el: HTMLElement|Text) => void) | null} [callback] - Callback invocata dopo la creazione dell'elemento (o del nodo di testo).
+ * @property {((el: Element|Text) => void) | null} [callback] - Callback invocata dopo la creazione dell'elemento (o del nodo di testo).
  * @property {Array<DomBuilderItem|string|Node>} [children] - Array di configurazione degli elementi figli. Accetta stringhe (scorciatoia secondo `parseDomString`), oggetti di configurazione e/o `Node` (un `Element`, un `DocumentFragment`, ...) inseriti così come sono.
  */
 
@@ -85,6 +94,23 @@ import { parseDomString } from './parseDomString.js';
  * Quando la stringa abbreviata e le proprietà a livello di oggetto sono in conflitto (classi, id o attributi),
  * le proprietà a livello di oggetto hanno la precedenza.
  *
+ * **Namespace (SVG / MathML)**
+ *
+ * Gli elementi vengono creati nel namespace corretto, così che SVG e MathML vengano disegnati dal browser.
+ * Per ogni elemento, nell'ordine:
+ * 1. `item.namespace`, se presente;
+ * 2. `svg` usa sempre il namespace SVG e `math` sempre quello MathML, qualunque sia il genitore;
+ * 3. gli altri elementi prendono il namespace del genitore effettivo (nessuna lista di tag: `a`, `title`, `script`,
+ *    `style` esistono sia in HTML sia in SVG e conta solo il contesto), tranne nei punti che riportano all'HTML:
+ *    figli di `foreignObject`, figli di `mi`/`mo`/`mn`/`ms`/`mtext` (tranne `mglyph` e `malignmark`) e figli di
+ *    `annotation-xml` con `encoding` `text/html` o `application/xhtml+xml`;
+ * 4. senza genitore, `options.namespace` se presente, altrimenti HTML.
+ *
+ * Il genitore effettivo è `parent` (con `insertMode` `before`/`after` è `parent.parentNode`), l'elemento precedente
+ * nella catena `tag: [...]` e l'elemento stesso per `children` e `content` array.
+ * Gli elementi HTML vengono creati con `document.createElement`, gli altri con `document.createElementNS`.
+ * La sintassi abbreviata a stringa non supporta `namespace`: usa solo la risoluzione automatica.
+ *
  * @function domBuilder
  * @param {Array<DomBuilderItem|string|Node>} [structureArray=[]] - Array di configurazione. Accetta stringhe (scorciatoia secondo `parseDomString`), oggetti di configurazione e/o `Node` (un `Element`, un `DocumentFragment`, ...) inseriti così come sono; ogni oggetto di configurazione supporta:
  * - `tag` / `tagName` {string | string[]} - Nome del tag HTML, o array di tag annidati (ciascuno è il genitore del successivo). Default `'div'`.
@@ -92,18 +118,59 @@ import { parseDomString } from './parseDomString.js';
  * - `id` {string | null} - ID univoco dell'elemento.
  * - `attrs` {[string, *] | [string, *][] | Object<string, *>} - Attributi: una coppia `[name, value]`, un array di coppie o un oggetto `{name: value}`.
  * - `content` {string | number | Function | Node | DomBuilderItem[] | null} - Contenuto dell'elemento. Una stringa/numero viene impostato come `textContent`, a meno che contenga `<`: in tal caso viene sanificato e inserito come markup (`Element.setHTML`, con ripiego su `innerHTML`). Un `Node` (`Element`, `DocumentFragment`, ...), passato direttamente o restituito da una funzione, viene aggiunto così com'è.
+ * - `namespace` {'html' | 'svg' | 'math' | string} - Namespace esplicito (alias o URI completo), con precedenza sulla risoluzione automatica; ereditato dai figli. Default: assente (risoluzione automatica).
  * - `text` {string | number} - Scorciatoia per un nodo di testo letterale: inserisce un nodo `Text` semplice (mai interpretato come markup) come fratello degli altri elementi, al posto di un elemento. Mutuamente esclusivo con `tag`/`content`/`children`.
  * - `condition` {boolean} - Se false, l'elemento (o il nodo di testo) viene saltato. Default `true`.
  * - `callback` {(function(HTMLElement|Text): void) | null} - Invocata dopo la creazione dell'elemento (o del nodo di testo).
  * - `children` {Array<DomBuilderItem|string|Node>} - Array di configurazione degli elementi figli (stesso formato, annidato; accetta anche `Node` inseriti così come sono).
  *
  * ID e classi possono essere indicati come chiavi di primo livello dell'oggetto o dentro `attrs`; le proprietà di primo livello hanno la precedenza (default: [])
- * @param {HTMLElement} [parent] - Elemento genitore a cui viene agganciata la struttura (vedi `options.insertMode`).
+ * @param {Element | null} [parent] - Elemento genitore a cui viene agganciata la struttura (vedi `options.insertMode`).
  * @param {Object} [options={}] - Opzioni di configurazione (default: {})
  * @param {boolean} [options.emptyParent=false] - Se true, l'elemento genitore viene svuotato prima della costruzione (default: false)
  * @param {'append'|'prepend'|'before'|'after'} [options.insertMode='append'] - Come ogni elemento radice di `structureArray` viene agganciato a `parent`: `append` lo inserisce come ultimo figlio (default), `prepend` come primo figlio, `before`/`after` lo inseriscono come fratello precedente/successivo di `parent`. In ogni modalità l'ordine di `structureArray` viene mantenuto. Si applica solo agli elementi prodotti da questa chiamata — le chiamate annidate a `domBuilder` (`content`, `children`) fanno sempre append (default: 'append')
  * @param {boolean} [options.debug=false] - Se true, scrive `structureArray` in console dopo che ogni elemento stringa è stato analizzato con `parseDomString` (cioè l'array elaborato effettivamente usato per costruire il DOM) (default: false)
- * @returns {HTMLElement|null} Il primo elemento creato, oppure null se non è stato creato nulla.
+ * @param {'html'|'svg'|'math'|string} [options.namespace] - Namespace iniziale (alias o URI completo) usato quando manca il genitore effettivo, ad esempio per costruire più fratelli SVG senza genitore. Non si applica quando il genitore c'è, né agli elementi `svg`/`math` o con `namespace` esplicito (default: assente, cioè HTML)
+ * @returns {HTMLElement|null} Il primo elemento creato, oppure null se non è stato creato nulla. Il tipo dichiarato è `HTMLElement` per comodità, ma per gli elementi SVG o MathML il valore restituito è un `SVGElement` o un `MathMLElement`.
+ *
+ * @example
+ * // riepilogo dei parametri con i valori di default
+ * domBuilder([
+ *   {
+ *     tag: 'div',             // default: 'div'
+ *     className: undefined,
+ *     id: undefined,
+ *     attrs: undefined,
+ *     content: undefined,
+ *     namespace: undefined,   // default: risoluzione automatica
+ *     condition: true,        // default: true
+ *     callback: undefined,
+ *     children: undefined
+ *   }
+ * ], parent, {
+ *   emptyParent: false,       // default: false
+ *   insertMode: 'append',     // default: 'append'
+ *   debug: false,             // default: false
+ *   namespace: undefined      // default: HTML in assenza di genitore
+ * });
+ *
+ * @example
+ * // icona SVG con `use`: `svg` è sempre nel namespace SVG, `title` e `use` lo ereditano
+ * domBuilder([{
+ *   tag: 'svg',
+ *   className: 'icon',
+ *   children: [
+ *     { tag: 'title', content: 'Carica' },
+ *     { tag: 'use', attrs: { href: 'icons.svg#cloud' } }
+ *   ]
+ * }], container);
+ *
+ * @example
+ * // frammento SVG senza genitore e senza `svg` come radice
+ * const use = domBuilder([{ tag: 'use', namespace: 'svg', attrs: { href: 'icons.svg#cloud' } }]);
+ *
+ * // più fratelli SVG senza genitore
+ * domBuilder(['path.a', 'circle.b'], null, { namespace: 'svg' });
  */
 
 
@@ -129,18 +196,27 @@ export function domBuilder(/** @type {Array<DomBuilderItem|string|Node>} */ stru
   */
   const useFragment = !!parent && (options.insertMode === 'append' || options.insertMode === 'prepend');
 
-  /** @type {HTMLElement | DocumentFragment | null} */
+  /** @type {Element | DocumentFragment | null} */
   let target = useFragment ? document.createDocumentFragment() : (parent ?? null);
 
-  /** @type {Map<HTMLElement | DocumentFragment, Node>} tiene traccia, per `insertMode: 'after'`, dell'ultimo fratello inserito per ogni nodo genitore */
+  /*
+    Genitore effettivo degli elementi radice, usato per risolverne il namespace: non `target`, che può essere
+    il DocumentFragment di raggruppamento (privo di namespace), ma `parent`, oppure il suo genitore con
+    `before`/`after`, dove gli elementi diventano fratelli di `parent`
+  */
+  const rootParent = !parent ? null
+    : (options.insertMode === 'before' || options.insertMode === 'after') ? parent.parentNode : parent;
+
+  // namespace iniziale in assenza di genitore effettivo
+  const fallbackNs = normalizeNamespace(options.namespace, 'options.namespace');
+
+  /** @type {Map<Element | DocumentFragment, Node>} tiene traccia, per `insertMode: 'after'`, dell'ultimo fratello inserito per ogni nodo genitore */
   const afterAnchors = new Map();
 
   /** @type {HTMLElement | null} */
   let mainElement = null;
   /** @type {HTMLElement} */
   let el;
-  /** @type {HTMLElement | DocumentFragment | null} */
-  let grand_parent = null;
 
   /** @type {Array<DomBuilderItem|null>} */
   const elaboratedStructureArray = [];
@@ -217,11 +293,22 @@ export function domBuilder(/** @type {Array<DomBuilderItem|string|Node>} */ stru
         return;
       }
 
+      // namespace esplicito dell'elemento (con `tag` array, del primo elemento della catena)
+      const itemNs = normalizeNamespace(safeItem.namespace, 'item.namespace');
+
+      /*
+        Con `tag` array: primo elemento della catena (inserito in `target` secondo `insertMode` al posto di `el`)
+        ed elemento che deve contenere `el`
+      */
+      /** @type {Element | null} */
+      let chainRoot = null;
+      /** @type {Element | null} */
+      let chainParent = null;
+
       // quando tag è un array, crea una serie di elementi annidati;
       // l'ultimo riceve le restanti proprietà dell'oggetto
       if (Array.isArray(safeItem.tag)) {
 
-        grand_parent = target;
         const tags = /** @type {string[]} */ (safeItem.tag);
 
         tags.forEach((tagItem, idx) => {
@@ -234,22 +321,34 @@ export function domBuilder(/** @type {Array<DomBuilderItem|string|Node>} */ stru
             safeItem.attrs = {...parsedItem.attrs ?? {}, ...safeItem.attrs ?? {}};
           }
           el = domBuilderBasicSetup(
-            document.createElement(parsedItem.tag || 'div'),
+            /** @type {HTMLElement} */ (createDomElement(
+              parsedItem.tag || 'div',
+              idx === 0 ? rootParent : chainParent,
+              idx === 0 ? itemNs : null,
+              fallbackNs
+            )),
             {...parsedItem, ...(isLast ? safeItem : {})}
           );
 
           if (!isLast) { // l'ultimo elemento viene gestito dal percorso standard qui sotto
-            if (target) {
-              target.appendChild(el);
+            if (chainParent) {
+              chainParent.appendChild(el);
+            } else {
+              chainRoot = el;
             }
-            target = el;
+            chainParent = el;
           }
 
         });
 
       } else {
         el = domBuilderBasicSetup(
-          document.createElement(/** @type {string} */ (safeItem.tag) ?? 'div'),
+          /** @type {HTMLElement} */ (createDomElement(
+            /** @type {string} */ (safeItem.tag) ?? 'div',
+            rootParent,
+            itemNs,
+            fallbackNs
+          )),
           safeItem
         );
       }
@@ -319,18 +418,24 @@ export function domBuilder(/** @type {Array<DomBuilderItem|string|Node>} */ stru
         mainElement = el;
       }
 
+      // con `tag` array, `el` va dentro la catena e in `target` viene inserito il primo elemento della catena
+      if (chainParent) {
+        chainParent.appendChild(el);
+      }
+      const rootNode = chainRoot ?? el;
+
       if (target) {
         if (options.insertMode === 'before') {
           const anchor = /** @type {HTMLElement} */ (target);
-          anchor.parentNode?.insertBefore(el, anchor);
+          anchor.parentNode?.insertBefore(rootNode, anchor);
 
         } else if (options.insertMode === 'after') {
           const anchor = afterAnchors.get(/** @type {HTMLElement} */ (target)) ?? /** @type {HTMLElement} */ (target);
-          anchor.parentNode?.insertBefore(el, anchor.nextSibling);
-          afterAnchors.set(/** @type {HTMLElement} */ (target), el);
+          anchor.parentNode?.insertBefore(rootNode, anchor.nextSibling);
+          afterAnchors.set(/** @type {HTMLElement} */ (target), rootNode);
 
         } else {
-          target.appendChild(el);
+          target.appendChild(rootNode);
         }
       }
 
@@ -338,10 +443,6 @@ export function domBuilder(/** @type {Array<DomBuilderItem|string|Node>} */ stru
       if (safeItem.callback && typeof safeItem.callback === 'function') {
         safeItem.callback(el);
       }
-
-      if (grand_parent) {
-        target = grand_parent;
-      }
     }
 
   });

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

@@ -34,7 +34,7 @@ const boolAttrs = new Set([
 
 /**
  * Applica a un elemento la configurazione di base di domBuilder: classi, id e attributi.
- * @param {HTMLElement} element - L'elemento da configurare.
+ * @param {HTMLElement} element - L'elemento da configurare (anche SVG o MathML).
  * @param {DomBuilderItem} domBuilderItem - L'oggetto di configurazione di domBuilder.
  * @returns {HTMLElement}
  */
@@ -64,13 +64,14 @@ export function domBuilderBasicSetup (element, domBuilderItem) {
   });
 
   // assegna classi e id dopo attrs così che le proprietà a livello di oggetto abbiano la precedenza
+  // setAttribute invece di `className`/`id`: sugli elementi SVG `className` è un SVGAnimatedString di sola lettura
   if(domBuilderItem.className) {
-    element.className = Array.isArray(domBuilderItem.className)
+    element.setAttribute('class', Array.isArray(domBuilderItem.className)
       ? domBuilderItem.className.filter(Boolean).join(' ')
-      : domBuilderItem.className;
+      : domBuilderItem.className);
   }
   if(domBuilderItem.id) {
-    element.id = domBuilderItem.id;
+    element.setAttribute('id', domBuilderItem.id);
   }
 
   return element;

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

@@ -14,7 +14,7 @@ const DOM_STRING_REGEX = new RegExp(
  * `tag#id.class1.class2.classN(attr1: val1, attr2=val2) text content`
  *
  * Dove:
- * * `tag` è il nome dell'elemento; se omesso vale `div`
+ * * `tag` è il nome dell'elemento, con la grafia originale (es. `linearGradient`); se omesso vale `div`
  * * `#id` è l'id opzionale dell'elemento, preceduto da `#`
  * * `.class1, .class2...` sono classi CSS opzionali, ciascuna preceduta da `.`
  * * i token `#id` e `.class` possono comparire in qualsiasi ordine e alternati (es. `.class1#id.class2`)
@@ -52,7 +52,7 @@ export function parseDomString(domString) {
     idMatch = idAndClasses.match(/#([a-zA-Z0-9_-]+)/),
     classMatches = [...idAndClasses.matchAll(/\.([a-zA-Z0-9_-]+)/g)];
 
-  const tag = (matches[1] || 'div').toLowerCase(),
+  const tag = matches[1] || 'div', // grafia conservata: createElementNS distingue maiuscole e minuscole (linearGradient, clipPath, ...)
     id = idMatch?.[1] || null,
     classes = classMatches.map(m => m[1]),
     rawAttrs = matches[3]?.trim() || null,

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

@@ -0,0 +1,147 @@
+/** URI dei namespace supportati tramite alias da domBuilder */
+export const NS = {
+  html: 'http://www.w3.org/1999/xhtml',
+  svg: 'http://www.w3.org/2000/svg',
+  math: 'http://www.w3.org/1998/Math/MathML'
+};
+
+// URI assoluto generico (schema seguito da `:`), per namespace diversi dai tre alias
+const URI_REGEX = /^[a-z][a-z0-9+.-]*:\S+$/i;
+
+// elementi MathML i cui figli tornano nel namespace HTML (text integration point)
+const MATHML_TEXT_INTEGRATION_POINTS = new Set(['mi', 'mo', 'mn', 'ms', 'mtext']);
+
+// eccezioni: dentro i text integration point MathML questi elementi restano MathML
+const MATHML_TEXT_INTEGRATION_EXCEPTIONS = new Set(['mglyph', 'malignmark']);
+
+// valori di `encoding` che rendono `annotation-xml` un punto di ritorno all'HTML
+const ANNOTATION_XML_HTML_ENCODINGS = new Set(['text/html', 'application/xhtml+xml']);
+
+/**
+ * Normalizza un valore di namespace (alias o URI completo).
+ *
+ * @param {string | null | undefined} value - Alias (`'html'`, `'svg'`, `'math'`) o URI completo
+ * @param {string} [source='namespace'] - Nome della proprietà da citare nel messaggio d'errore (default: 'namespace')
+ * @returns {string | null} L'URI del namespace, oppure null se il valore è assente o non valido
+ *   (in quest'ultimo caso viene scritto un `console.error`)
+ *
+ * @example
+ * normalizeNamespace('svg');                             // 'http://www.w3.org/2000/svg'
+ * normalizeNamespace('http://www.w3.org/2000/svg');      // 'http://www.w3.org/2000/svg'
+ * normalizeNamespace(undefined);                         // null
+ * normalizeNamespace('foo', 'item.namespace');           // null + console.error
+ */
+export function normalizeNamespace(value, source = 'namespace') {
+  if (value == null) {
+    return null;
+  }
+
+  if (typeof value === 'string') {
+    if (Object.hasOwn(NS, value)) {
+      return NS[/** @type {keyof typeof NS} */ (value)];
+    }
+    if (URI_REGEX.test(value)) {
+      return value;
+    }
+  }
+
+  // eslint-disable-next-line no-console
+  console.error(`[domBuilder]: \`${source}\` non valido (accettati 'html', 'svg', 'math' o un URI completo) → ` + value);
+  return null;
+}
+
+/**
+ * Determina il namespace in cui creare un elemento.
+ *
+ * Ordine di risoluzione:
+ * 1. `explicitNs` (da `item.namespace`), se presente;
+ * 2. `svg` → SVG e `math` → MathML, qualunque sia il genitore;
+ * 3. punti di ritorno all'HTML: figli di `foreignObject` (SVG), di `mi`/`mo`/`mn`/`ms`/`mtext` (MathML,
+ *    tranne `mglyph` e `malignmark`) e di `annotation-xml` con `encoding` `text/html` o `application/xhtml+xml`;
+ * 4. namespace del genitore effettivo;
+ * 5. `fallbackNs` (da `options.namespace`), quando il genitore manca o non ha namespace;
+ * 6. HTML.
+ *
+ * @param {string} tag - Nome del tag
+ * @param {Node | null} [effectiveParent] - Genitore effettivo dell'elemento (default: null)
+ * @param {string | null} [explicitNs] - URI già normalizzato da `item.namespace` (default: null)
+ * @param {string | null} [fallbackNs] - URI già normalizzato da `options.namespace` (default: null)
+ * @returns {string} L'URI del namespace
+ *
+ * @example
+ * resolveNamespace('svg');                          // NS.svg
+ * resolveNamespace('use', svgElement);              // NS.svg
+ * resolveNamespace('div', foreignObjectElement);    // NS.html
+ * resolveNamespace('use', null, null, NS.svg);      // NS.svg
+ * resolveNamespace('div');                          // NS.html
+ */
+export function resolveNamespace(tag, effectiveParent = null, explicitNs = null, fallbackNs = null) {
+
+  if (explicitNs) {
+    return explicitNs;
+  }
+
+  const lowerTag = tag.toLowerCase();
+  if (lowerTag === 'svg') {
+    return NS.svg;
+  }
+  if (lowerTag === 'math') {
+    return NS.math;
+  }
+
+  const parentEl = effectiveParent instanceof Element ? effectiveParent : null;
+
+  if (parentEl) {
+    const parentNs = parentEl.namespaceURI;
+    const parentName = parentEl.localName;
+
+    if (parentNs === NS.svg && parentName === 'foreignObject') {
+      return NS.html;
+    }
+
+    if (parentNs === NS.math) {
+      if (MATHML_TEXT_INTEGRATION_POINTS.has(parentName) && !MATHML_TEXT_INTEGRATION_EXCEPTIONS.has(tag)) {
+        return NS.html;
+      }
+      if (parentName === 'annotation-xml'
+        && ANNOTATION_XML_HTML_ENCODINGS.has((parentEl.getAttribute('encoding') ?? '').toLowerCase())) {
+        return NS.html;
+      }
+    }
+
+    if (parentNs) {
+      return parentNs;
+    }
+  }
+
+  return fallbackNs ?? NS.html;
+}
+
+/**
+ * Crea un elemento nel namespace risolto da `resolveNamespace`.
+ * Per l'HTML usa `document.createElement` (comportamento storico di domBuilder), per gli altri namespace
+ * `document.createElementNS`, che distingue maiuscole e minuscole (`linearGradient`, `clipPath`, ...).
+ *
+ * @param {string} tag - Nome del tag
+ * @param {Node | null} [effectiveParent] - Genitore effettivo dell'elemento (default: null)
+ * @param {string | null} [explicitNs] - URI già normalizzato da `item.namespace` (default: null)
+ * @param {string | null} [fallbackNs] - URI già normalizzato da `options.namespace` (default: null)
+ * @returns {Element}
+ *
+ * @example
+ * createDomElement('div');                       // HTMLDivElement
+ * createDomElement('svg');                       // SVGSVGElement
+ * createDomElement('linearGradient', svgEl);     // SVGLinearGradientElement
+ * createDomElement('use', null, NS.svg);         // SVGUseElement
+ */
+export function createDomElement(tag, effectiveParent = null, explicitNs = null, fallbackNs = null) {
+  const ns = resolveNamespace(tag, effectiveParent, explicitNs, fallbackNs);
+
+  if (ns === NS.html) {
+    return document.createElement(tag);
+  }
+
+  // `svg` e `math` vanno scritti in minuscolo per essere riconosciuti nei rispettivi namespace
+  const lowerTag = tag.toLowerCase();
+  return document.createElementNS(ns, lowerTag === 'svg' || lowerTag === 'math' ? lowerTag : tag);
+}