@teddy-dev/frontend 1.0.1

package/res/mc-shopify.js

@@ -0,0 +1,439 @@
+import '../res/mc-events.js';
+await loadComponent('./res/mc-utils.js', false);
+
+class McShopify {
+
+  // elenco di storage keys usati da McShopify
+  static STORAGE = {
+    COOKIE_CONSENT: 'cookie_consent',       // Key usata per salvare le preferenze dei cookie
+  };
+  
+  // Carica le customerPrivacy di Shopify. Da chiamare subito sempre, quando c'è un cookie banner
+  static loadCustomerPrivacy = (callback) => {
+    window.Shopify.loadFeatures(
+      [
+        {
+          name: 'consent-tracking-api',
+          version: '0.1',
+        },
+      ],
+      error => {
+        if (error) {
+          throw new Error(error);
+        }
+        if (typeof callback === 'function') callback();
+      }
+    );
+  }
+
+  // Da chiamare nel cookie banner di iubenda per settare i consensi. Pubblica l'evento COOKIE_CONSENT
+  static iubendaIntegration = (preferences) => {
+    const isPrefEmpty = !preferences || Object.keys(preferences).length === 0;
+    const consent = isPrefEmpty ? _iub.cs.api.getPreferences() : preferences;
+    const shopifyPurposes = {
+      "analytics": [4, 's'],
+      "marketing": [5, 'adv'],
+      "preferences": [2, 3],
+      "sale_of_data": ['s', 'sh'],
+    }
+    const expressedConsent = {};
+    Object.keys(shopifyPurposes).forEach(function(purposeItem) {
+      var purposeExpressed = null
+      shopifyPurposes[purposeItem].forEach(item => {
+        if (consent.purposes && typeof consent.purposes[item] === 'boolean') {
+          purposeExpressed = consent.purposes[item];
+        }
+        if (consent.uspr && typeof consent.uspr[item] === 'boolean' && purposeExpressed !== false) {
+          purposeExpressed = consent.uspr[item];
+        }
+      })
+
+      if (typeof purposeExpressed === 'boolean') {
+        expressedConsent[purposeItem] = purposeExpressed;
+      }
+    });
+    localStorage.setItem(McShopify.STORAGE.COOKIE_CONSENT, JSON.stringify(expressedConsent));
+    window.Shopify.customerPrivacy.setTrackingConsent(expressedConsent);
+    McShopify.customEvent(MCEVENTS.COOKIE_CONSENT, expressedConsent);
+  }
+
+  // Pubblica un evento su window e per le analitycs di Shopify
+  static customEvent = (eventName, data, element) => {
+    if(!eventName || typeof eventName !== 'string') {
+      console.error('McShopify.customEvent: Il primo parametro deve essere una stringa valida per il nome dell\'evento');
+      return;
+    }
+    if(data && typeof data !== 'object') {
+      console.error('McShopify.customEvent: Il secondo parametro deve essere un oggetto o undefined');
+      return;
+    }
+    if(element && !(element instanceof HTMLElement)) {
+      console.error('McShopify.customEvent: Il terzo parametro, se fornito, deve essere un elemento HTML valido');
+      return;
+    }
+    const e = new CustomEvent(eventName, {
+      detail: data
+    });
+    if(element){
+      element.dispatchEvent(e);
+    } else {
+      window.dispatchEvent(e);
+    }
+    if(data != undefined && McUtils.isJSONObject(data)){
+      Shopify.analytics.publish(eventName, data);
+    }
+  }
+
+  // Controlla se i cookie di preferenza sono stati accettati
+  static isPreferencesAllowed = () => {
+    if(!Shopify.customerPrivacy) {
+      McShopify.loadCustomerPrivacy();
+      return;
+    }
+    const consent = JSON.parse(localStorage.getItem(McShopify.STORAGE.COOKIE_CONSENT));
+    return (consent && consent.preferences) || Shopify.customerPrivacy.preferencesProcessingAllowed();
+  }
+
+  // Controlla se i cookie di marketing sono stati accettati
+  static isMarketingAllowed = () => {
+    if(!Shopify.customerPrivacy) {
+      McShopify.loadCustomerPrivacy();
+      return;
+    }
+    const consent = JSON.parse(localStorage.getItem(McShopify.STORAGE.COOKIE_CONSENT));
+    return (consent && consent.marketing) || Shopify.customerPrivacy.marketingAllowed();
+  }
+
+  // Controlla se i cookie di analisi sono stati accettati
+  static isAnalyticsAllowed = () => {
+    if(!Shopify.customerPrivacy) {
+      McShopify.loadCustomerPrivacy();
+      return;
+    }
+    const consent = JSON.parse(localStorage.getItem(McShopify.STORAGE.COOKIE_CONSENT));
+    return (consent && consent.analytics) || Shopify.customerPrivacy.analyticsProcessingAllowed();
+  }
+
+  // Aggiunge uno o più prodotti al carrello e pubblica l'evento CART_ADDED. Tutti i parametri sono facoltativi ma ne va passato almeno uno
+  static addToCart = ({
+    form,     // Form html da cui prendere i dati
+    formData, // Oggetto FormData da inviare
+    items,     // Array di oggetti da inviare
+    onSuccess,     // Funzione da chiamare in caso di successo
+    onError, // Funzione da chiamare in caso di errore
+    onComplete     // Funzione da chiamare al termine della richiesta
+  }) => {
+    if(!form && !formData && !items) { console.error('McShopify.addToCart: Devi passare almeno uno dei parametri form, formData o items'); return; }
+    if(form && !(form instanceof HTMLFormElement)) { console.error('McShopify.addToCart: Il parametro form deve essere un elemento HTMLFormElement valido'); return; }
+    if(formData && !(formData instanceof FormData)) { console.error('McShopify.addToCart: Il parametro formData deve essere un oggetto FormData valido'); return; }
+    if(items && !Array.isArray(items)) { console.error('McShopify.addToCart: Il parametro items deve essere un array di oggetti'); return; }
+    if(items && items.length === 0) { console.error('McShopify.addToCart: L\'array items non può essere vuoto'); return; }
+
+    const config = {
+      url: `${Shopify.routes.root}cart/add.js`,
+      method: 'post'
+    };
+    
+    if(form)
+      config.data = new FormData(form);
+    else if(formData)
+      config.data = formData;
+    else if(items) {
+      config.data = { items: items };
+      config.headers = {
+        'content-type': 'application/json'
+      };
+    }
+
+    if((form || formData) && !config.data.get('id')) { console.error('McShopify.addToCart: Devi specificare almeno un prodotto da aggiungere al carrello, usando il campo id contenente l\'id della variante'); return;}
+    if((form || formData) && !config.data.get('quantity')) { console.error('McShopify.addToCart: Devi specificare almeno un prodotto da aggiungere al carrello, usando il campo quantity contenente la quantità del prodotto'); return;}
+
+    axios(config).then(r => {
+      McShopify.customEvent(MCEVENTS.CART_UPDATED, r.data);
+      McShopify.customEvent(MCEVENTS.CART_ADDED, r.data);
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      McShopify.customEvent(MCEVENTS.CART_ERROR, e);
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+
+  // Modifica una linea del carrello e pubblica l'evento CART_UPDATED. Se un prodotto è stato aumentato di quantità pubblica anche CART_ADDED, se invece è stato diminuito o rimosso pubblica CART_REMOVED
+  static updateCartLine = ({
+    id,       // ID della linea del carrello da modificare
+    quantity, // Nuova quantità del prodotto
+    line,    // Numero della linea del carrello da modificare (opzionale, se non specificato usa l'id)
+    properties, // Oggetto con le proprietà del prodotto da modificare (opzionale)
+    selling_plan,
+    onSuccess, // Funzione da chiamare in caso di successo
+    onError,   // Funzione da chiamare in caso di errore
+    onComplete // Funzione da chiamare al termine della richiesta
+  }) => {
+    if(!id && !line) { console.error('McShopify.updateCartLine: Devi passare almeno uno dei parametri id o line'); return; }
+    if(quantity === undefined || quantity === null) { console.error('McShopify.updateCartLine: Devi passare il parametro quantity'); return; }
+    if(properties && typeof properties !== 'object') { console.error('McShopify.updateCartLine: Il parametro properties deve essere un oggetto'); return; }
+    
+    const qty = Number(quantity);
+    if(isNaN(qty) || qty < 0) { console.error('McShopify.updateCartLine: Il parametro quantity deve essere un numero maggiore o uguale a 0'); return; }
+
+    const data = {id, quantity, line, properties, selling_plan};
+
+    const config = {
+      url: `${Shopify.routes.root}cart/change.js`,
+      method: 'post',
+      data: data,
+      headers: {
+        'content-type': 'application/json'
+      }
+    };
+
+    axios(config).then(r => {
+      McShopify.customEvent(MCEVENTS.CART_UPDATED, r.data);
+      if(r.data.items_removed.length > 0){ //se ci sono elementi rimossi
+        McShopify.customEvent(MCEVENTS.CART_REMOVED, r.data);
+      }
+      if(r.data.items_added.length > 0){ //se ci sono elementi aggiunti
+        McShopify.customEvent(MCEVENTS.CART_ADDED, r.data);
+      }
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      McShopify.customEvent(MCEVENTS.CART_ERROR, e);
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+
+  // Modifica il carrello, utile per note e attributi. Pubblica l'evento CART_UPDATED. Se un prodotto è stato aumentato di quantità pubblica anche CART_ADDED, se invece è stato diminuito o rimosso pubblica CART_REMOVED. Solo uno dei parametri è necessario. 
+  static updateCart = ({
+    form,       // Form html da cui prendere i dati
+    formData,   // Oggetto FormData da inviare
+    data,       // Oggetto con i dati da inviare (opzionale, se non specificato usa form o formData)
+    onSuccess,  // Funzione da chiamare in caso di successo
+    onError,    // Funzione da chiamare in caso di errore
+    onComplete  // Funzione da chiamare al termine della richiesta
+  }) => {
+    if(!form && !formData && !data) { console.error('McShopify.updateCart: Devi passare almeno uno dei parametri form, formData o data'); return; }
+    if(form && !(form instanceof HTMLFormElement)) { console.error('McShopify.updateCart: Il parametro form deve essere un elemento HTMLFormElement valido'); return; }
+    if(formData && !(formData instanceof FormData)) { console.error('McShopify.updateCart: Il parametro formData deve essere un oggetto FormData valido'); return; }
+    if(data && typeof data !== 'object') { console.error('McShopify.updateCart: Il parametro data deve essere un oggetto'); return; }
+
+    const config = {
+      url: `${Shopify.routes.root}cart/update.js`,
+      method: 'post'
+    };
+    
+    if(form)
+      config.data = new FormData(form);
+    else if(formData)
+      config.data = formData;
+    else{
+      config.data = data;
+      config.headers = {
+        'content-type': 'application/json'
+      };
+    }
+
+    axios(config).then(r => {
+      McShopify.customEvent(MCEVENTS.CART_UPDATED, r.data);
+      if(r.data.items_changelog?.added?.length > 0){ //se ci sono elementi rimossi
+        McShopify.customEvent(MCEVENTS.CART_REMOVED, r.data);
+      }
+      if(r.data.items_changelog?.removed?.length > 0){ //se ci sono elementi aggiunti
+        McShopify.customEvent(MCEVENTS.CART_ADDED, r.data);
+      }
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      McShopify.customEvent(MCEVENTS.CART_ERROR, e);
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+
+  // Ottiene il carrello ed esegue il callback al success
+  static getCart = ({
+    onSuccess, // Funzione da chiamare in caso di successo
+    onError,   // Funzione da chiamare in caso di errore
+    onComplete // Funzione da chiamare al termine della richiesta
+  }) => {
+    axios({
+        url: `${Shopify.routes.root}cart.js`,
+        method: 'get'
+    }).then(r => {
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+
+  // Svuota il carrello ed esegue il callback. Pubblica l'evento CART_UPDATED
+  static clearCart = ({
+    onSuccess, // Funzione da chiamare in caso di successo
+    onError,   // Funzione da chiamare in caso di errore
+    onComplete // Funzione da chiamare al termine della richiesta
+  }) => {
+    axios({
+        url: `${Shopify.routes.root}cart/clear.js`,
+        method: 'get'
+    }).then(r => {
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+  
+  // Ottiene i dati di un prodotto tramite il suo handle ed esegue callback
+  static getProduct = ({
+    handle, // Handle del prodotto da cercare
+    onSuccess, // Funzione da chiamare in caso di successo
+    onError,   // Funzione da chiamare in caso di errore
+    onComplete // Funzione da chiamare al termine della richiesta
+  }) => {
+    if(!handle || typeof handle !== 'string') { console.error('McShopify.getProduct: Devi passare un handle valido del prodotto'); return; }
+    if(handle.includes('/')) { console.error('McShopify.getProduct: L\'handle non può contenere il carattere /'); return; }
+    
+    axios({
+      url: `${Shopify.routes.root}products/${handle}.js`,
+      method: 'get'
+    }).then(r => {
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+
+  // Ottiene i prodotti raccomandati per un prodotto in base ai settaggi dell'app search and discovery ed esegue il callback
+  static getRecommendations = ({
+    product_id, // ID del prodotto per cui ottenere le raccomandazioni
+    section_id, // ID della sezione per cui ottenere le raccomandazioni (opzionale)
+    limit=10,   // Numero massimo di prodotti da restituire (max 10)
+    intent='related', // Intento della raccomandazione (related | complementary)
+    onSuccess, onError, onComplete
+  }) => {
+    if(!product_id) { console.error('McShopify.getRecommendations: Devi passare un ID prodotto valido'); return; }
+    if(section_id && typeof section_id !== 'string') { console.error('McShopify.getRecommendations: Il parametro section_id deve essere una stringa'); return; }
+    if(intent && !['related', 'complementary'].includes(intent)) { console.error('McShopify.getRecommendations: Il parametro intent deve essere "related" o "complementary"'); return; }
+
+    const l = parseInt(limit);
+    if(isNaN(l) || l < 1 || l > 10) { console.error('McShopify.getRecommendations: Il parametro limit deve essere un numero compreso tra 1 e 10'); return; }
+
+    const data = {product_id, limit: l, intent};
+    const filename = section_id ? 'products' : 'products.json';
+    if(section_id){
+      data.section_id = section_id;
+    }
+
+    const queryString = new URLSearchParams(data).toString();
+
+    axios({
+      url: `${Shopify.routes.root}recommendations/${filename}?${queryString}`,
+      method: 'get',
+      headers: {
+        'content-type': 'application/json'
+      }
+    }).then(r => {
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+
+  // Avvia una ricerca predittiva ed esegue il callback
+  static search = ({
+    q, // Termini di ricerca
+    type='product,article,page,collection,query', // Tipo di risorsa da cercare (opzionale, può essere 'product', 'article', 'page', 'collection' o 'query')
+    limit=10, // Numero massimo di risultati da restituire (da 1 a 10)
+    limit_scope='each', // Ambito del limite (each | all)
+    unavailable_products='last', // show: mostra normalmente i prodotti non disponibili, hide: nasconde i prodotti non disponibili, last: mostra i prodotti non disponibili alla fine della lista
+    fields, // Campi nei quali cercare (opzionale, può essere 'author', 'body', 'product_type', 'tag', 'title', 'variants.barcode', 'variants.sku', 'variants.title', 'vendor')
+    section_id, // ID della sezione opzionale
+    onSuccess, // Funzione da chiamare in caso di successo
+    onError,   // Funzione da chiamare in caso di errore
+    onComplete // Funzione da chiamare al termine della richiesta
+  }) => {
+    if(!q || typeof q !== 'string') { console.error('McShopify.search: Devi passare una stringa valida per il parametro q'); return; }
+    if(type && type.split(',').some(t => !['product', 'article', 'page', 'collection', 'query'].includes(t))) { console.error('McShopify.search: Il parametro type deve essere uno tra "product", "article", "page", "collection" o "query"'); return; }
+    if(limit_scope && !['each', 'all'].includes(limit_scope)) { console.error('McShopify.search: Il parametro limit_scope deve essere "each" o "all"'); return; }
+    if(unavailable_products && !['show', 'hide', 'last'].includes(unavailable_products)) { console.error('McShopify.search: Il parametro unavailable_products deve essere "show", "hide" o "last"'); return; }
+    if(fields && fields.split(',').some(f => !['author', 'body', 'product_type', 'tag', 'title', 'variants.barcode', 'variants.sku', 'variants.title', 'vendor'].includes(f))) { console.error('McShopify.search: Il parametro fields deve essere uno tra "author", "body", "product_type", "tag", "title", "variants.barcode", "variants.sku", "variants.title" o "vendor"'); return; }
+
+    const l = parseInt(limit);
+    if(isNaN(l) || l < 1 || l > 10) { console.error('McShopify.search: Il parametro limit deve essere un numero compreso tra 1 e 10'); return; }
+    
+    const params = new URLSearchParams();
+    params.append('q', q);
+    if(type) params.append('resources[type]', type);
+    if(limit) params.append('resources[limit]', l);
+    if(limit_scope) params.append('resources[limit_scope]', limit_scope);
+    if(unavailable_products) params.append('resources[options][unavailable_products]', unavailable_products);
+    if(fields) params.append('resources[options][fields]', fields);
+
+    const filename = section_id ? 'suggest' : 'suggest.json';
+
+    axios({
+      url: `${Shopify.routes.root}search/${filename}?${params.toString()}`,
+      method: 'get',
+      headers: {
+        'content-type': 'application/json'
+      }
+    }).then(r => {
+      McShopify.customEvent(MCEVENTS.SEARCH, r.data);
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      McShopify.customEvent(MCEVENTS.SEARCH_ERROR, e);
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+  
+  static section = ({
+    path, // URL della sezione da caricare
+    section_id, // ID della sezione da caricare (opzionale, se non specificato usa l'url)
+    sections, // Array di sezioni da caricare (opzionale, se non specificato usa l'url)
+    onSuccess, // Funzione da chiamare in caso di successo
+    onError,   // Funzione da chiamare in caso di errore
+    onComplete // Funzione da chiamare al termine della richiesta
+  }) => {
+    if(!path) { console.error('McShopify.section: Devi passare path'); return; }
+    if(!section_id && !sections) { console.error('McShopify.section: Devi passare almeno uno dei parametri section_id o sections'); return; }
+    if(path && typeof path !== 'string') { console.error('McShopify.section: Il parametro path deve essere una stringa'); return; }
+    if(section_id && typeof section_id !== 'string') { console.error('McShopify.section: Il parametro section_id deve essere una stringa'); return; }
+    if(sections && !Array.isArray(sections)) { console.error('McShopify.section: Il parametro sections deve essere un array di sezioni'); return; }
+
+    const params = new URLSearchParams();
+    if(sections?.length > 0)
+      params.append('sections', sections.join(','));
+    else
+      params.append('section_id', section_id);
+
+    const config = {
+      url: `${path}?${params.toString()}`,
+      method: 'get',
+      headers: {
+        'content-type': 'application/json'
+      },
+    };
+
+    axios(config).then(r => {
+      if(typeof onSuccess === 'function') { onSuccess(r.data); }
+    }).catch(e => {
+      if(typeof onError === 'function') { onError(e); }
+    }).finally(() => {
+      if(typeof onComplete === 'function') { onComplete(); }
+    });
+  }
+}
+window.McShopify = McShopify;
+export default McShopify;

package/res/mc-utils.js

@@ -0,0 +1,119 @@
+// Questa classe `McUtils` raccoglie utility generiche riutilizzabili per la gestione di formattazione valuta, parsing HTML, logging avanzato e aggiornamento dinamico di elementi HTML.
+// Non richiede data attributes o elementi HTML specifici: tutte le funzioni sono statiche e possono essere richiamate direttamente tramite `McUtils`.
+
+class McUtils {
+
+  static VERSION = '2.0.4';
+
+  // Formatta un importo numerico in formato valuta secondo il formato definito in window.theme.moneyFormat
+  // Esempio: 123456 -> "1 234,56 €" (a seconda del formato configurato)
+  static money = (amount) => {
+    const n = Number(amount);
+    if(isNaN(n)) { console.error('McUtils.money: Il valore passato non è un numero valido:', amount); return ''; }
+
+    // Divide per 100, fissa a 2 decimali, usa la virgola come separatore decimale e lo spazio per le migliaia
+    const a = parseFloat(n/100).toFixed(2).replace('.', ',').replace(/\B(?=(\d{3})+(?!\d))/g, " ");
+    if(window.theme?.moneyFormat === undefined) { console.warn('McUtils.money: La formattazione della valuta non è definita in window.theme.moneyFormat'); return a; }
+    
+    return window.theme.moneyFormat.replace('{{amount}}', a).replace('{{amount_with_comma_separator}}', a);
+  }
+
+  // Ottiene un oggetto Document a partire da una stringa HTML
+  static getDocument = (html) => {
+    if(typeof html !== 'string') { console.error('McUtils.getDocument: il primo parametro deve essere una stringa HTML'); return; }
+    const parser = new DOMParser();
+    return parser.parseFromString(html, 'text/html');
+  }
+
+  // Converte una stringa in uno slug "handle" (come la funzione handleize di Liquid)
+  // Esempio: "Ciao Mondo!" -> "ciao-mondo"
+  static handleize = (str) => {
+    return str.toString().toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]+/g, '');
+  }
+
+  // Log avanzato: mostra il chiamante e i parametri solo in ambiente di sviluppo o debug
+  static log = (...args) => {
+    if(Shopify.theme.role == 'development' || window.theme.debug) {
+      try {
+          const err = new Error();
+          const stack = err.stack || '';
+          const stackLines = stack.split('\n');
+          const callerLine = stackLines[2] || '';
+          let caller = 'unknown';
+          // Estrae il nome della funzione chiamante dallo stack trace
+          const matchFunction = callerLine.match(/at\s+([\w.$<>]+)\s*\(/);
+          if (matchFunction && matchFunction[1]) {
+              caller = matchFunction[1];
+          } else {
+              const matchFile = callerLine.match(/at\s+(.+:\d+:\d+)/);
+              if (matchFile && matchFile[1]) {
+                  caller = matchFile[1];
+              }
+          }
+          // Log con chiamante + argomenti
+          console.log('🌝', `[${caller}]`, ...args);
+      } catch (e) {
+          // Fallback in caso di errore estrazione del chiamante
+          console.log('🌝', ...args);
+      }
+    }
+  }
+
+  // Aggiorna dinamicamente il contenuto di un elemento HTML con quello di un nuovo elemento estratto da una stringa HTML
+  // html: stringa HTML sorgente
+  // elementToReload: elemento da aggiornare
+  // selectorOfNewElement: selettore CSS dell'elemento da cui prendere il nuovo contenuto
+  static reloadElement = (html, elementToReload, selectorOfNewElement) => {
+    if(!html || !elementToReload || !selectorOfNewElement) { console.error('reloadElement: parametri mancanti o non validi'); return; }
+    if(typeof html !== 'string') { console.error('reloadElement: il primo parametro deve essere una stringa HTML'); return; }
+    if(!(elementToReload instanceof HTMLElement)) { console.error('reloadElement: il secondo parametro deve essere un elemento HTML'); return; }
+    if(typeof selectorOfNewElement !== 'string') { console.error('reloadElement: il terzo parametro deve essere una stringa CSS selector'); return; }
+
+    const newDocument = McUtils.getDocument(html);
+    const newElement = newDocument.querySelector(selectorOfNewElement);
+    if(!newElement) { console.error('reloadElement: Elemento non trovato nella risposta:', selectorOfNewElement); return; }
+    
+    elementToReload.innerHTML = newElement.innerHTML;
+  }
+
+  static addCss = (url) => {
+    if (!url || typeof url !== 'string') { console.error('McElement.addCss: Il parametro "url" deve essere una stringa valida.'); return; }
+    const element = document.querySelector(`link[href="${url}"]`);
+    if (element) { console.warn(`McElement.addCss: Il CSS "${url}" è già stato aggiunto.`, element); return; }
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = url;
+    document.head.appendChild(link);
+  }
+
+  static isJSONObject = (value) =>{
+    function isJSONValue(v){
+      if (
+        typeof v === 'string' ||
+        typeof v === 'number' ||
+        typeof v === 'boolean' ||
+        v === null
+      ) return true;
+
+      if (Array.isArray(v)) return v.every(isJSONValue);
+
+      if (typeof v === 'object') {
+        // Solo plain object, no Date/Map/DOM ecc.
+        if (Object.getPrototypeOf(v) !== Object.prototype) return false;
+        return Object.values(v).every(isJSONValue);
+      }
+      return false;
+    }
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      !Array.isArray(value) &&
+      Object.getPrototypeOf(value) === Object.prototype &&
+      Object.values(value).every(isJSONValue)
+    );
+  }
+}
+
+// Esporta la classe McUtils come globale e come modulo
+window.McUtils = McUtils;
+export default McUtils;