@massimo-cassandro/minimo 1.36.1 → 1.37.0

package/dev-tools/starter-kit/source_files/root/webpack-config-modules/custom-props-purgecss-plugin.mjs

@@ -0,0 +1,328 @@
+// webpack-config-modules/custom-props-purgecss-plugin.mjs
+// v.3
+import fs from 'fs';
+import postcss from 'postcss';
+import { globSync } from 'glob';
+
+/*
+  Plugin webpack per l'estrazione ottimizzata delle CSS custom properties.
+
+  Contesto: il file "master" (definitionsFile) contiene TUTTE le definizioni di
+  custom properties disponibili. I css compilati da webpack contengono invece
+  solo *usi* (`var(--nome)`), mai definizioni. Dopo la minificazione degli
+  asset, il plugin:
+  1. scansiona i css di ogni "set" per trovare le custom properties usate;
+  2. risolve le dipendenze transitive (`--a: calc(var(--b) * 2)` => anche
+     `--b`, fino al fixed point, fallback `var(--x, var(--y))` inclusi);
+  3. estrae dal master le sole definizioni necessarie, PRESERVANDO l'ordine
+     originale di dichiarazione;
+  4. le inietta all'inizio del file target del set (dopo l'eventuale banner
+     webpack, cioè un commento che inizia con `/*!`, o `@charset`), oppure le
+     emette come nuovo asset.
+
+  Rispetto a postcss-jit-props (che opera sul singolo file, prima del bundling)
+  lavora sugli asset finali e permette di decidere il raggruppamento
+  sources -> target.
+
+  Regole di scope del master:
+  - una prop è identificata dal nome: se `--x` è usata, TUTTE le sue
+    dichiarazioni nel master vengono portate con sé, anche quelle dentro
+    blocchi di override (`@media (prefers-color-scheme: dark)`,
+    `[data-theme="dark"]`, ecc.), altrimenti il tema alternativo si rompe
+    in silenzio; le var() presenti nei valori degli override entrano nella
+    risoluzione transitiva;
+  - le dichiarazioni non custom (es. `color-scheme`) sono mantenute solo nei
+    blocchi che conservano almeno una custom property;
+  - le props "locali" con prefisso `--_` non fanno parte del pool globale:
+    sono escluse dalla scansione degli usi e dalla risoluzione transitiva
+    (e ignorate nel master).
+
+  Stage: PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE, quindi dopo la minificazione
+  (CssMinimizerPlugin, OPTIMIZE_SIZE) e dopo PurgeCSSPlugin (ADDITIONAL), ma
+  prima del calcolo del contenthash reale (OPTIMIZE_HASH, `realContentHash`).
+  Il match degli usi avviene quindi sul css realmente servito e l'hash
+  riflette il contenuto finale.
+
+  Watch mode: il master è parsato una sola volta e ricaricato solo se cambia
+  (mtime); è comunque registrato come fileDependency. Il set di props usate
+  viene ricalcolato a ogni build.
+*/
+
+const PLUGIN_NAME = 'CustomPropsPurgeCssPlugin';
+
+const VAR_REFS_REGEX = /var\(\s*(--[A-Za-z0-9_-]+)/g;
+// banner webpack (commento `/*!`) e/o `@charset` iniziali, che devono restare in testa
+const LEADING_REGEX = /^(?:\s*(?:@charset\s+["'][^"']*["']\s*;|\/\*![\s\S]*?\*\/))*\s*/;
+
+// le props con prefisso `--_` sono locali: fuori dal pool globale
+const isGlobalCustomProp = (name) => name.startsWith('--') && !name.startsWith('--_');
+
+const varRefs = (text) => [...text.matchAll(VAR_REFS_REGEX)]
+  .map(m => m[1])
+  .filter(isGlobalCustomProp);
+
+// pattern asset: stringa con `*` come wildcard (es. 'index.*.css') o RegExp,
+// confrontati con il nome completo dell'asset (path relativo a output.path)
+const toMatcher = (pattern) => {
+  if (pattern instanceof RegExp) {
+    return (name) => pattern.test(name);
+  }
+  const regex = new RegExp(
+    '^' + pattern.split('*').map(s => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$'
+  );
+  return (name) => regex.test(name);
+};
+
+const hasCustomDecl = (node) => {
+  let found = false;
+  node.walkDecls(decl => {
+    if (isGlobalCustomProp(decl.prop)) {
+      found = true;
+    }
+  });
+  return found;
+};
+
+// rimuove commenti, custom props non incluse e blocchi rimasti senza custom props
+const prune = (container, keep) => {
+  container.each(node => {
+    if (node.type === 'comment') {
+      node.remove();
+    } else if (node.type === 'decl') {
+      if (isGlobalCustomProp(node.prop) ? !keep.has(node.prop) : node.prop.startsWith('--')) {
+        node.remove();
+      }
+    } else if (node.type === 'rule' || (node.type === 'atrule' && node.nodes)) {
+      prune(node, keep);
+      if (!hasCustomDecl(node)) {
+        node.remove();
+      }
+    } else {
+      // at-rule senza blocco (@import, @charset, @layer a, b;): non pertinenti
+      node.remove();
+    }
+  });
+};
+
+// serializzazione compatta (senza indentazioni) per gli asset minificati
+const compact = (root) => {
+  root.walk(node => {
+    node.raws.before = '';
+    if (node.type === 'decl') {
+      node.raws.between = ':';
+    } else {
+      node.raws.between = '';
+      node.raws.after = '';
+      node.raws.semicolon = false;
+      if (node.type === 'atrule') {
+        node.raws.afterName = ' ';
+      }
+    }
+  });
+  root.raws.after = '';
+};
+
+export class CustomPropsPurgeCssPlugin {
+
+  /**
+   * @param {object} options
+   * @param {string} options.definitionsFile - Percorso assoluto del file master con tutte
+   *   le definizioni di custom properties
+   * @param {{ sources: (string|RegExp)[], target?: (string|RegExp) }[]} options.sets - Set
+   *   di asset css da elaborare in modo indipendente. `sources`: nomi degli asset css
+   *   compilati (con l'hash nel nome), stringhe con `*` come wildcard (es. `'index.*.css'`)
+   *   o RegExp. `target`: asset in cui iniettare le definizioni (stesso formato; se il
+   *   pattern non corrisponde ad alcun asset e non contiene `*`, viene emesso come nuovo
+   *   asset con quel nome). Se omesso, è il primo asset che corrisponde a `sources`
+   * @param {string} [options.selector=':root'] - Selettore con cui sostituire i blocchi
+   *   `:root` del master (es. `':where(html)'`); gli altri selettori (temi, ecc.) restano invariati (default: ':root')
+   * @param {string[]} [options.extraUsageGlobs=[]] - Glob di file css i cui usi di var()
+   *   contano come usati in TUTTI i set: css caricati fuori dagli asset (shadow DOM dei
+   *   web components, import `?raw`) (default: [])
+   * @param {(string|RegExp)[]} [options.seeds=[]] - Props da includere comunque in tutti i
+   *   set (nomi esatti o pattern risolti sui nomi dichiarati nel master), es. override
+   *   consumati da un altro asset (default: [])
+   * @param {boolean} [options.minify=false] - Serializza le definizioni in forma compatta
+   *   (default: false)
+   *
+   * @example
+   * new CustomPropsPurgeCssPlugin({
+   *   definitionsFile: path.resolve(__dirname, './app/css/custom-properties.css'),
+   *   sets: [
+   *     // le definizioni vengono iniettate in layout.critical.*.css (inline nel template)
+   *     // e valgono anche per index.*.css
+   *     { sources: ['index.*.css', 'layout.critical.*.css'], target: 'layout.critical.*.css' },
+   *     // target omesso: definizioni iniettate nel primo asset del set
+   *     { sources: ['admin.*.css'] }
+   *   ],
+   *   selector: ':root',      // default
+   *   extraUsageGlobs: [],    // default
+   *   seeds: [],              // default
+   *   minify: !isDevelopment  // default: false
+   * })
+   */
+  constructor({
+    definitionsFile,
+    sets,
+    selector = ':root',
+    extraUsageGlobs = [],
+    seeds = [],
+    minify = false
+  }) {
+    if (!definitionsFile || !Array.isArray(sets)) {
+      throw new Error(`${PLUGIN_NAME}: 'definitionsFile' e 'sets' sono obbligatori`);
+    }
+    this.definitionsFile = definitionsFile;
+    this.sets = sets.map(set => ({
+      sources: set.sources.map(toMatcher),
+      target: set.target == null ? null : {
+        matcher: toMatcher(set.target),
+        // nome letterale, usato per emettere un nuovo asset se nessuno corrisponde
+        literal: typeof set.target === 'string' && !set.target.includes('*') ? set.target : null
+      }
+    }));
+    this.selector = selector;
+    this.extraUsageGlobs = extraUsageGlobs;
+    this.seeds = seeds;
+    this.minify = minify;
+
+    this.cache = { mtimeMs: null, root: null, declaredRefs: null };
+  }
+
+  // parsing (cachato) del master: root PostCSS + grafo nome -> Set(var() nei valori)
+  loadDefinitions() {
+    const { mtimeMs } = fs.statSync(this.definitionsFile);
+
+    if (this.cache.mtimeMs !== mtimeMs) {
+      const root = postcss.parse(fs.readFileSync(this.definitionsFile, 'utf8'), { from: this.definitionsFile });
+      const declaredRefs = new Map();
+
+      root.walkDecls(decl => {
+        if (!isGlobalCustomProp(decl.prop)) {
+          return;
+        }
+        if (!declaredRefs.has(decl.prop)) {
+          declaredRefs.set(decl.prop, new Set());
+        }
+        varRefs(decl.value).forEach(ref => declaredRefs.get(decl.prop).add(ref));
+      });
+
+      this.cache = { mtimeMs, root, declaredRefs };
+    }
+    return this.cache;
+  }
+
+  apply(compiler) {
+    const { Compilation, sources } = compiler.webpack;
+    const { RawSource, ReplaceSource } = sources;
+
+    compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+
+      compilation.hooks.processAssets.tap(
+        { name: PLUGIN_NAME, stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE },
+        () => {
+          compilation.fileDependencies.add(this.definitionsFile);
+
+          const { root: masterRoot, declaredRefs } = this.loadDefinitions();
+          const declaredNames = [...declaredRefs.keys()];
+
+          // usi comuni a tutti i set: file css fuori dagli asset + seeds
+          const commonUsages = new Set();
+          for (const file of globSync(this.extraUsageGlobs, { nodir: true, absolute: true })) {
+            compilation.fileDependencies.add(file);
+            varRefs(fs.readFileSync(file, 'utf8')).forEach(ref => commonUsages.add(ref));
+          }
+          for (const seed of this.seeds) {
+            (typeof seed === 'string' ? [seed] : declaredNames.filter(name => seed.test(name)))
+              .forEach(name => commonUsages.add(name));
+          }
+
+          const cssAssetNames = () => compilation.getAssets()
+            .map(asset => asset.name)
+            .filter(name => /\.css$/i.test(name));
+
+          for (const set of this.sets) {
+            const sourceNames = cssAssetNames().filter(name => set.sources.some(match => match(name)));
+
+            if (sourceNames.length === 0) {
+              continue;
+            }
+
+            // props usate nei css del set
+            const used = new Set(commonUsages);
+            for (const name of sourceNames) {
+              varRefs(compilation.getAsset(name).source.source().toString()).forEach(ref => used.add(ref));
+            }
+
+            // chiusura transitiva (solo props dichiarate nel master)
+            const keep = new Set();
+            const queue = [...used];
+            while (queue.length > 0) {
+              const name = queue.pop();
+              if (!keep.has(name) && declaredRefs.has(name)) {
+                keep.add(name);
+                queue.push(...declaredRefs.get(name));
+              }
+            }
+
+            if (keep.size === 0) {
+              continue;
+            }
+
+            // definizioni: si parte da una copia del master (l'ordine originale è preservato)
+            const definitionsRoot = masterRoot.clone();
+            prune(definitionsRoot, keep);
+            if (this.selector !== ':root') {
+              definitionsRoot.walkRules(rule => {
+                if (rule.selector.trim() === ':root') {
+                  rule.selector = this.selector;
+                }
+              });
+            }
+            if (this.minify) {
+              compact(definitionsRoot);
+            } else {
+              // primo nodo senza riga vuota iniziale
+              if (definitionsRoot.first) {
+                definitionsRoot.first.raws.before = '';
+              }
+            }
+            const definitions = definitionsRoot.toString().trim() + '\n';
+
+            // target
+            let targetName;
+            if (set.target == null) {
+              targetName = sourceNames[0];
+            } else {
+              const matching = cssAssetNames().filter(name => set.target.matcher(name));
+              if (matching.length > 0) {
+                targetName = matching[0];
+                if (matching.length > 1) {
+                  compilation.warnings.push(new compiler.webpack.WebpackError(
+                    `${PLUGIN_NAME}: il target del set corrisponde a più asset (${matching.join(', ')}), usato: ${targetName}`
+                  ));
+                }
+              } else if (set.target.literal) {
+                compilation.emitAsset(set.target.literal, new RawSource(definitions));
+                continue;
+              } else {
+                compilation.warnings.push(new compiler.webpack.WebpackError(
+                  `${PLUGIN_NAME}: nessun asset corrisponde al target del set (sources: ${sourceNames.join(', ')})`
+                ));
+                continue;
+              }
+            }
+
+            const original = compilation.getAsset(targetName).source;
+            const originalText = original.source().toString();
+            const position = originalText.match(LEADING_REGEX)[0].length;
+            const replaced = new ReplaceSource(original, PLUGIN_NAME);
+            // insert(pos) inserisce PRIMA del carattere in posizione `pos`
+            replaced.insert(position, definitions);
+            compilation.updateAsset(targetName, replaced);
+          }
+        }
+      );
+    });
+  }
+}

package/dev-tools/starter-kit/source_files/root/webpack-config-modules/get-jsConfig-aliases.mjs

@@ -1,3 +1,4 @@
+// v.3
 import path from 'path';
 import fs from 'fs';
 

package/dev-tools/starter-kit/source_files/root/webpack-config-modules/inline-critical-css.mjs

@@ -1,4 +1,5 @@
 /* plugins/inline-critical-css.mjs */
+// v.3
 import HtmlWebpackPlugin from 'html-webpack-plugin';
 
 export class InlineCriticalCssPlugin {

package/dev-tools/starter-kit/source_files/root/webpack-config-modules/mini-svg-data-uri-loader.cjs

@@ -1,4 +1,5 @@
 // ./loaders/mini-svg-data-uri-loader.cjs
+// v.3
 // Questo file USA la libreria 'mini-svg-data-uri', ma è un wrapper specifico per Webpack.
 
 /* eslint-env node */

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

@@ -1,18 +1,21 @@
 // webpack-modules/postcss.config.mjs
+// v.3
 import path from 'path';
 import { fileURLToPath } from 'url';
 import globalData from '@csstools/postcss-global-data';
 import customMedia from 'postcss-custom-media';
 import autoprefixer from 'autoprefixer';
 // import jitProps from 'postcss-jit-props';
+// import OpenProps from 'open-props';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // NB: le custom properties NON sono gestite qui (postcss-jit-props rimosso):
-// ogni entry css importa direttamente custom-properties.css e le props
-// non utilizzate vengono rimosse in build da PurgeCSS (`variables: true`,
-// vedi webpack.config.mjs)
+// i css del progetto contengono solo usi `var(--nome)` e le definizioni
+// (solo quelle usate) sono iniettate a fine build dal plugin
+// custom-props-purgecss-plugin.mjs, che parte dal file master
+// custom-properties.css (vedi `useCustomPropsPlugin` in webpack.config.mjs)
 
 // NB: la minificazione è gestita da CssMinimizerPlugin (webpack.config.mjs):
 // cssnano NON va aggiunto qui, oltre a duplicare la minificazione
@@ -25,8 +28,8 @@ export default (loaderContext) => {
   const plugins = [
     // rende disponibili le @custom-media a tutti i file css
     // (il contenuto iniettato viene rimosso a fine elaborazione;
-    // NON aggiungere qui custom-properties.css: duplicherebbe le props
-    // in ogni asset e interferirebbe con il purge, vedi sopra)
+    // NON aggiungere qui custom-properties.css: le definizioni sono
+    // gestite dal plugin delle custom properties, vedi sopra)
     globalData({
       files: [
         path.resolve(__dirname, '../app/css/custom-media.css'),
@@ -34,6 +37,7 @@ export default (loaderContext) => {
     }),
 
     // jitProps({
+    //   ...OpenProps,
     //   files: [
     //     path.resolve(__dirname, '../app/css/custom-properties.css'),
     //   ]

package/dev-tools/starter-kit/source_files/root/webpack-config-modules/purgecss-setup.mjs

@@ -1,7 +1,7 @@
 // webpack-modules/purgecss-setup.mjs
+// v.3
 import { PurgeCSSPlugin } from 'purgecss-webpack-plugin';
 import { globSync } from 'glob';
-import { purgecssVariablesSafelist } from './purgecss-variables-safelist.mjs';
 
 /*
   Istanzia i plugin PurgeCSS del progetto: un passaggio stretto sui css
@@ -9,37 +9,39 @@ import { purgecssVariablesSafelist } from './purgecss-variables-safelist.mjs';
   passaggio generale su tutti gli altri asset (il purge è idempotente: il
   secondo passaggio sui critical non rimuove altro).
 
-  NB: il plugin elabora ogni asset css SINGOLARMENTE, quindi con `variables: true`
-  una custom property viene mantenuta solo se definita e usata nello stesso asset.
-  Per questo, lato progetto:
-  - ogni entry css importa direttamente custom-properties.css (che sostituisce
-    jit-props: le props non usate vengono rimosse qui)
-  - il chunk `shared` deve contenere solo js (il css estratto resta nel chunk
-    dell'entry che lo importa)
-  - le props dichiarate in un asset ma consumate altrove (override di tema,
-    shadow DOM dei web components) vanno indicate tramite `variablesSafelist`
-    (vedi purgecss-variables-safelist.mjs)
+  NB: PurgeCSS gestisce SOLO classi/id/tag e @keyframes. Le custom properties
+  NON sono gestite qui (`variables` è sempre false): le definizioni vengono
+  iniettate, solo per quelle usate, da custom-props-purgecss-plugin.mjs, che
+  opera sugli asset css già finalizzati (dopo questo purge e dopo la
+  minificazione), quindi vede anche gli usi di var() nei blocchi
+  `purgecss start/end ignore`, che PurgeCSS mantiene.
+  Il purge lavora sul singolo asset css: i @keyframes definiti in un asset
+  (es. `shared.css`) ma usati solo in un altro vengono rimossi (vedi
+  `safelist.keyframes` / `keyframes: false`).
 */
 
 /**
  * @param {object} params
  * @param {string[]} params.contentGlobs file da scansionare per le classi/id usati
  *   (twig, php, js...); i file di stile vengono comunque scartati dal plugin
- * @param {object} params.safelist { standard, deep, greedy } — selettori sempre
+ * @param {object} params.safelist { standard, deep, greedy, keyframes } — selettori sempre
  *   mantenuti, indipendentemente dal contenuto scansionato
- * @param {object} params.variablesSafelist opzioni per purgecssVariablesSafelist
- *   ({ declarationGlobs, shadowGlobs, seeds })
- * @param {boolean} [params.variables=true] rimuove le custom properties non usate
- * @param {boolean} [params.keyframes=true] rimuove i @keyframes non referenziati
- * @param {boolean} [params.debug=false] logga i selettori rimossi a fine build
+ * @param {boolean} [params.keyframes=true] rimuove i @keyframes non referenziati (default: true)
+ * @param {boolean} [params.debug=false] logga i selettori rimossi a fine build (default: false)
  * @returns {object[]} plugin webpack da inserire in `plugins`
  *   (critical + generale, più il logger di debug se `debug: true`)
+ *
+ * @example
+ * createPurgeCSSPlugins({
+ *   contentGlobs: [path.resolve(__dirname, './app/src/**\/*.{js,mjs}')],
+ *   safelist: { standard: [/^alert-/], deep: [/^m_/], greedy: [/^&$/] },
+ *   keyframes: true, // default
+ *   debug: false     // default
+ * })
  */
 export function createPurgeCSSPlugins({
   contentGlobs,
   safelist,
-  variablesSafelist,
-  variables = true,
   keyframes = true,
   debug = false
 }) {
@@ -49,7 +51,7 @@ export function createPurgeCSSPlugins({
     // extractor di default (/[A-Za-z0-9_-]+/g): adeguato alle classi/tag/id del progetto,
     // non servono extractors custom
 
-    variables,
+    variables: false, // vedi sopra: custom properties gestite da custom-props-purgecss-plugin.mjs
     keyframes,
     // fontFace resta false (default): i font sono referenziati solo tramite
     // var(--font-family) e purgecss non risolve le custom properties nei valori
@@ -65,13 +67,7 @@ export function createPurgeCSSPlugins({
 
   const pluginMain = new PurgeCSSPlugin({
     ...commonOptions,
-    safelist: {
-      ...safelist,
-      // elenco generato: usi di var() nei blocchi `purgecss ignore` e nei css
-      // shadow-DOM/`?raw`, override cross-asset (seeds), con chiusura transitiva
-      // delle dipendenze (vedi purgecss-variables-safelist.mjs)
-      variables: purgecssVariablesSafelist(variablesSafelist)
-    }
+    safelist
   });
 
   return [

package/dev-tools/starter-kit/source_files/root/webpack-config-modules/svg-rules.mjs

@@ -1,3 +1,4 @@
+// v.3
 /**
  * Funzione per definire le regole per SVG
  * @returns {import('webpack').RuleSetRule[]}

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

@@ -1,4 +1,5 @@
 // svgo.config.js
+// v.3
 import addViewBox from 'svgo-add-viewbox';
 
 // https://svgo.dev/docs/plugins/