@massimo-cassandro/minimo 1.36.1 → 1.37.0

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

@@ -1,4 +1,5 @@
 // webpack.config.mjs __project_name__
+// v.3
 import path from 'path';
 import { fileURLToPath } from 'url';
 import webpack from 'webpack';
@@ -41,6 +42,11 @@ const isDevelopment = process.env.NODE_ENV === 'development'
   ,devServerPort = [[port5700]]
   ,apiPort = [[port8000]] // eslint-disable-line no-unused-vars
   ,useSass = false
+
+  // css in dev: true = iniettato con style-loader (veloce, nessun asset css);
+  // false = estratto in asset con MiniCssExtractPlugin (come in produzione).
+  // NB: con `purgeCssInDev: true` (vedi sotto) viene comunque forzato a false,
+  // perché il purge e il plugin delle custom properties lavorano sugli asset css
   ,inlineCssInDevMode = true
   // sf: inlineCssInDevMode = false
   ,useSvgo = true
@@ -76,36 +82,65 @@ const isDevelopment = process.env.NODE_ENV === 'development'
 
   ,usePurgeCss = true // false per disattivare PurgeCSS (debug rapido di problemi legati al purge)
   ,purgeCSSOptions = {
-    variables: false, // rimuove le custom properties non usate (sostituisce jit-props)
     keyframes: true, // rimuove i @keyframes non referenziati
     debug: false // true per loggare i selettori rimossi da PurgeCSS a fine build
   }
+
+  // plugin per l'estrazione ottimizzata delle custom properties (vedi
+  // webpack-config-modules/custom-props-purgecss-plugin.mjs): dopo la
+  // minificazione inietta nei css compilati SOLO le definizioni di custom
+  // properties effettivamente usate, prese dal file master. I css del progetto
+  // contengono quindi solo usi `var(--nome)`, mai definizioni (custom-properties.css
+  // NON va importato nelle entry css). Se false il plugin non viene nemmeno
+  // caricato e la gestione delle custom properties resta a carico del progetto
+  ,useCustomPropsPlugin = true
+  // file master con TUTTE le definizioni di custom properties disponibili
+  // (copiato da minimo da starter-install.sh, generato da `npm run 'build tokens'`)
+  ,customPropsFile = path.resolve(__dirname, './app/css/custom-properties.css')
+
+  // PurgeCSS e plugin custom properties lavorano sugli asset css finali:
+  // in dev, con `false`, sono entrambi disattivati (build più veloce, css
+  // iniettato con style-loader; se `useCustomPropsPlugin` è true le definizioni
+  // vengono aggiunte per intero alle entry, vedi `entries`).
+  // Con `true` (a scopo di test) sono attivi come in produzione (secondo i
+  // rispettivi flag `usePurgeCss` / `useCustomPropsPlugin`) e `inlineCssInDevMode`
+  // viene forzato a false
+  ,purgeCssInDev = false
+  ,inlineCssInDev = inlineCssInDevMode && !purgeCssInDev // valore effettivo passato a cssRules
+  ,runPurgeCss = usePurgeCss && (!isDevelopment || purgeCssInDev)
+  ,runCustomPropsPlugin = useCustomPropsPlugin && (!isDevelopment || purgeCssInDev)
   // ,manifest_shared_seed = {}
 ;
 
-// test del cacheGroup `shared` (splitChunks): i css restano SEMPRE FUORI dal
-// chunk condiviso e nel chunk della entry che li importa, così ogni asset css
-// resta autosufficiente (`variables: true` funziona per singolo asset, e i
-// critical css inline nei template devono restare autosufficienti). I
-// template (twig/altro) linkano solo il css della propria entry (e gli
-// eventuali `.critical.css`), MAI uno shared.css: se i css finissero nel
-// chunk condiviso, quella parte di stili sparirebbe silenziosamente dalla
-// pagina.
+const { CustomPropsPurgeCssPlugin } = runCustomPropsPlugin
+  ? await import('./webpack-config-modules/custom-props-purgecss-plugin.mjs')
+  : {};
+
+// cacheGroup `shared` (splitChunks): raccoglie in `shared.js` / `shared.css` i
+// moduli js e css provenienti da node_modules e dalle directory condivise del
+// progetto (vedi `pathsRegexp` sotto), così non vengono duplicati in ogni entry.
+//
+// Dalla v3 anche i css finiscono nello `shared.css` (in v2 restavano sempre nel
+// css della entry, duplicati, per due limiti di PurgeCSS che operava sul singolo
+// asset con `variables: true`): le custom properties sono ora gestite dal plugin
+// CustomPropsPurgeCssPlugin, che lavora sugli asset finali e le cui definizioni
+// vengono iniettate nello `shared.css` (vedi `sets` nei `plugins`).
 //
-// NB: non è la soluzione migliore, perché rinuncia alla deduplicazione dei
-// css tra entry — ma è la più pratica al momento vista la duplicazione ancora
-// limitata tra le pagine. Da rivedere in futuro se la duplicazione dovesse
-// crescere.
+// - le entry `.critical` sono escluse dal chunk condiviso (`chunks` sotto):
+//   il loro css è inline nei template e deve restare autosufficiente
+// - `enforce: true` garantisce che `shared.js` e `shared.css` siano sempre
+//   generati (senza, splitChunks non crea il chunk se i moduli sono sotto la
+//   soglia `minSize`, e il link nel template punterebbe a un file inesistente)
+// - i template (twig/altro) devono linkare (preload + link) sia `shared.css` che il
+//   css della propria entry, con `shared.css` PRIMA del css della entry per
+//   rispettare l'ordine della cascata (vedi _sf/templates/_main-tpl.html.twig)
 //
-// TODO: shared.css -> attualmente non generato, ma se in futuro la duplicazione di css tra le pagine dovesse crescere
-// e se si risolve un problema con purgeCSS
-// (componenti importati dal js di più entry), valutare un cacheGroup `shared`
-// dedicato ai css condivisi: andranno escluse le entry `.critical` (devono
-// restare autosufficienti), gestite in safelist.variables le custom properties
-// definite/consumate tra asset diversi (vedi purgecss-variables-safelist.mjs),
-// e i template dovranno linkare esplicitamente lo shared.css generato
+// NB: PurgeCSS elabora ogni asset css singolarmente, quindi i @keyframes
+// definiti nello `shared.css` ma usati solo in un altro asset (es. un css di
+// progetto che usa una animation di minimo) verrebbero rimossi: in tal caso
+// aggiungerli a `safelist.keyframes` o impostare `keyframes: false` in
+// `purgeCSSOptions`
 const shared_chunk_paths = (module) => {
-  if (module.type === 'css/mini-extract') return false;
 
   // path delle directory da utilizzare nel chunk `shared`
   const sep = '[\\\\/]'; // stringa che produce [\\/] nel pattern
@@ -180,7 +215,7 @@ const CopyWebpackPluginPatterns = [
 
 // =>> entries
 // NB: percorsi dalla root del progetto
-const entries = {
+const projectEntries = {
   'index': './app/index.js',
 
   // css critici da includere inline nei template html: il suffisso `.critical` nel nome
@@ -190,6 +225,18 @@ const entries = {
 
 };
 
+// dev senza plugin custom properties (`purgeCssInDev: false`, css iniettato con
+// style-loader, quindi nessun asset css in cui il plugin possa inserire le
+// definizioni): il file master con TUTTE le custom properties viene aggiunto come
+// primo modulo di ogni entry (escluse le `.critical`). Non serve nessuna
+// modifica ai template
+const entries = (useCustomPropsPlugin && isDevelopment && !purgeCssInDev)
+  ? Object.fromEntries(Object.entries(projectEntries).map(([name, entry]) => [
+    name,
+    /\.critical/.test(name) ? entry : [customPropsFile, ...[entry].flat()]
+  ]))
+  : projectEntries;
+
 
 const config = {
   mode: isDevelopment ? 'development' : 'production',
@@ -240,10 +287,11 @@ const config = {
   optimization: {
     minimize: !isDevelopment,
     // di default true solo se minimize:true (quindi false in dev): esplicito qui perché
-    // PurgeCSSPlugin modifica gli asset css dopo il calcolo dell'hash "veloce" — senza
-    // questo, in dev il contenthash non riflette le modifiche di PurgeCSS e il browser
-    // può servire dalla cache una versione stale pur avendo rigenerato la build
-    // realContentHash: true,
+    // PurgeCSSPlugin e il plugin delle custom properties modificano gli asset css
+    // dopo il calcolo dell'hash "veloce" — senza questo, in dev con `purgeCssInDev`
+    // il contenthash non riflette le loro modifiche e il browser può servire dalla
+    // cache una versione stale pur avendo rigenerato la build
+    realContentHash: !isDevelopment || purgeCssInDev,
     minimizer: [
       new CssMinimizerPlugin(),
       new TerserPlugin({
@@ -261,10 +309,11 @@ const config = {
 
         shared: {
           // vedi shared_chunk_paths sopra per la logica completa del test
-          // (path match + esclusione sempre dei css)
           test: shared_chunk_paths,
           name: 'shared',
-          chunks: 'all'
+          enforce: true,
+          // le entry `.critical` restano autosufficienti (css inline nei template)
+          chunks: (chunk) => !/\.critical/.test(chunk.name)
         }
       }
     },
@@ -359,7 +408,8 @@ const config = {
 
     // =>> plugins: WebpackManifestPlugin
     // new WebpackManifestPlugin({
-    //   fileName: path.join(output_dir, 'manifest.json'), // sf: fileName: 'manifest.json', // scrive in output.path
+    //   fileName: path.join(output_dir, 'manifest.json'),
+    // sf: fileName: 'manifest.json', // scrive in output.path
     //   // basePath: item.source_dirname
     //   // removeKeyHash: /(^(_assets\/(?!(fonts\/))))|((\?as_asset)$)/,
     //   removeKeyHash: true, // /([a-f0-9]{32}\.?)/gi, // /(\?as_asset)$/,
@@ -462,29 +512,27 @@ const config = {
       exclude: /\.critical/ // chunk name
     }),
 
-    // =>> plugins: PurgeCSSPlugin (per ultimo, attivo anche in dev)
+    // =>> plugins: PurgeCSSPlugin (solo classi/keyframes, le custom properties sono
+    // gestite dal plugin successivo)
     // https://github.com/FullHuman/purgecss/tree/main/packages/purgecss-webpack-plugin
     // https://purgecss.com/configuration.html
     // istanze e opzioni in webpack-config-modules/purgecss-setup.mjs (qui solo flag/dati progetto)
     // `usePurgeCss: false` disattiva il purge per intero (utile per isolare rapidamente
-    // eventuali problemi legati ad esso); `purgeCSSOptions` (variables/keyframes/debug,
+    // eventuali problemi legati ad esso); `purgeCSSOptions` (keyframes/debug,
     // vedi sopra) si applica solo quando è attivo
-    // NB: il purge è attivo anche in dev, per far emergere subito eventuali
-    // rimozioni errate. In watch mode i template twig NON sono osservati da
-    // webpack: dopo aver aggiunto una classe solo in un twig occorre rilanciare
-    // la build (o toccare un file js/css) per aggiornare il purge
-    ...(usePurgeCss
+    // NB: in dev il purge è attivo solo con `purgeCssInDev: true` (vedi sopra). In
+    // watch mode i template twig NON sono osservati da webpack: dopo aver
+    // aggiunto una classe solo in un twig occorre rilanciare la build (o toccare
+    // un file js/css) per aggiornare il purge
+    ...(runPurgeCss
       ? createPurgeCSSPlugins({
 
         // SOLO file che generano markup o classi (twig, php, js);
         // i file di stile vengono comunque scartati dal plugin
         contentGlobs: [
-          // progetti symfony: template twig e classi generate lato php
-          // (percorsi relativi alla root del progetto: adattare il `../` se
-          // webpack.config.mjs NON è in una sottodirectory)
-          // path.resolve(__dirname, './templates/**/*.twig'),
-          // path.resolve(__dirname, './app/**/*.php'),
-          path.resolve(__dirname, './app/index.js'), // entry js di default (vedi starter-install.sh)
+          path.resolve(__dirname, './templates/**/*.twig'),
+          path.resolve(__dirname, './app/**/*.php'),
+          path.resolve(__dirname, './app/index.js'), // entry js di default
           path.resolve(__dirname, './app/src/**/*.{js,mjs,jsx}'),
           path.resolve(__dirname, './app/src/**/*.ejs'), // template html di webpack
           path.resolve(__dirname, './app/error-pages/**/*.js'),
@@ -519,31 +567,55 @@ const config = {
           ]
         },
 
-        // 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 webpack-config-modules/purgecss-variables-safelist.mjs)
-        variablesSafelist: {
-          declarationGlobs: [
-            path.resolve(__dirname, './app/index.css'), // entry css di default (vedi starter-install.sh)
-            path.resolve(__dirname, './app/index-critical.css'),
-            path.resolve(__dirname, './app/src/**/*.css'),
-            path.resolve(__dirname, './app/error-pages/**/*.css'),
-            `${minimo_path}/src/**/*.css`,
-          ],
-          shadowGlobs: [
-            path.resolve(__dirname, './app/src/web-components/**/*.css'),
-            `${minimo_path}/src/web-components/**/*.css`,
-          ],
-          seeds: [
-            // override di .login-group (login.css) consumati dai buttons minimo (css globale)
-            /^--btn-secondary-/
-          ]
-        },
-
         // fontFace resta false (default): i font sono referenziati solo tramite
         // var(--font-family) e purgecss non risolve le custom properties nei valori
         ...purgeCSSOptions
       })
+      : []),
+
+    // =>> plugins: CustomPropsPurgeCssPlugin (dopo PurgeCSS e dopo la minificazione)
+    // estrazione ottimizzata delle custom properties: vedi il commento in testa a
+    // webpack-config-modules/custom-props-purgecss-plugin.mjs e i flag
+    // `useCustomPropsPlugin` / `purgeCssInDev` sopra
+    ...(runCustomPropsPlugin
+      ? [new CustomPropsPurgeCssPlugin({
+
+        // file master con tutte le definizioni disponibili
+        definitionsFile: customPropsFile,
+
+        // set di asset css elaborati in modo indipendente: `sources` sono i nomi
+        // degli asset compilati (con l'hash nel nome: usare `*`, oppure una
+        // RegExp), `target` l'asset in cui iniettare le definizioni (se omesso
+        // è il primo asset del set; se non corrisponde ad alcun asset e non ha
+        // `*` viene emesso come nuovo asset, che va poi linkato nei template).
+        // NB: `*` corrisponde a qualsiasi carattere: 'layout.*.css' corrisponde
+        // anche a 'layout.critical.<hash>.css'
+        sets: [
+          // il critical css è inline nei template: deve restare autosufficiente
+          { sources: ['layout.critical.*.css'] },
+
+          // shared.css è linkato in tutte le pagine: contiene le definizioni
+          // per tutti i css delle entry (le definizioni non sono duplicate
+          // negli altri asset). Ogni css delle entry va elencato qui
+          { sources: ['shared.*.css', 'index.*.css'], target: 'shared.*.css' },
+        ],
+
+        // css usati fuori dagli asset purgati (shadow DOM dei web components,
+        // import `?raw`): tutti i loro usi di var() contano per tutti i set
+        extraUsageGlobs: [
+          path.resolve(__dirname, './app/src/web-components/**/*.css'),
+          `${minimo_path}/src/web-components/**/*.css`,
+        ],
+
+        // props da includere comunque in tutti i set (nomi esatti o RegExp),
+        // es. override consumati da un altro asset
+        // seeds: [/^--btn-secondary-/],
+
+        // selettore dei blocchi `:root` del master (default: ':root')
+        // selector: ':where(html)',
+
+        minify: !isDevelopment
+      })]
       : [])
   ], // end plugins
 
@@ -562,7 +634,7 @@ const config = {
         test: /\.jsx?$/,
         oneOf: [
           {
-            resourceQuery: /as_lib/, // utilizzo come libreria
+            resourceQuery: /as_(?:lib|asset)/, // utilizzo come libreria / asset
             type: 'asset/resource',
             generator: {
               filename: 'libs/[name].[contenthash][ext]'
@@ -692,7 +764,7 @@ const config = {
       },
 
       // =>> rules: css / scss
-      ...cssRules({isDevelopment: isDevelopment, useSass: useSass, inlineCssInDevMode: inlineCssInDevMode, postcssConfig_path: postcssConfig_path})
+      ...cssRules({isDevelopment: isDevelopment, useSass: useSass, inlineCssInDevMode: inlineCssInDev, postcssConfig_path: postcssConfig_path})
     ] // end rules
   }, // end module
 

package/dev-tools/starter-kit/starter-install.sh

@@ -77,7 +77,8 @@ optionalPackages=(
   "simple-datatables                                 |     | richiesto da s-datatable-component"
   "style-dictionary                                  | dev | richiesto da dev-tools/design-tokens-builder (build-tokens)"
   "@cybozu/eslint-config                             | dev | utilizzato da eslint per il check dei file css"
-  "postcss-cli postcss-import postcss-nested cssnano | dev | per css email"
+  "sass                                              | dev | per email (scss)"
+  "postcss postcss-cli postcss-import postcss-nested postcss-custom-properties autoprefixer cssnano | dev | per email (postcss)"
 )
 
 # Rimuove spazi iniziali/finali da una stringa (usata per i campi estratti

package/dev-tools/starter-kit/webpack-config-upg.md

@@ -0,0 +1,147 @@
+# Aggiornamento della configurazione webpack
+
+La versione della configurazione in uso è indicata dal commento `// v.N` alla riga 2 di `webpack.config.mjs` e di ogni file in `webpack-config-modules/`.
+
+Le versioni precedenti sono conservate in `archived/webpack-config-v2/` del repository di minimo.
+
+> **Alternativa rapida:** rilanciare `starter-install.sh` (è idempotente): i file diversi dai sorgenti vengono rinominati `OLD-<nome>` e sostituiti dalla nuova versione. Poi si riportano nel nuovo `webpack.config.mjs` le personalizzazioni del progetto (entry, glob dei contenuti, safelist, template html, regole custom) copiandole da `OLD-webpack.config.mjs`. Le istruzioni seguenti servono per aggiornare a mano un progetto già esistente.
+
+---
+
+## Da v2 a v3
+
+Novità della v3: le definizioni delle custom properties non sono più gestite da PurgeCSS (`variables`) né da postcss-jit-props, ma da un plugin webpack dedicato, `custom-props-purgecss-plugin.mjs`, che opera sugli asset CSS finali (dopo la minificazione) e inietta solo le custom properties effettivamente usate (dipendenze transitive incluse), partendo dal file master `app/css/custom-properties.css`. Il plugin è attivabile con un flag, indipendente da `usePurgeCss`.
+
+Conseguenza: i css non devono più restare autosufficienti (con le definizioni ripetute in ogni asset), quindi **anche i css condivisi finiscono nel chunk `shared`** (`shared.css`) invece di essere duplicati nel css di ogni entry. Le entry `.critical` restano autosufficienti. I template devono linkare `shared.css`.
+
+Riepilogo delle modifiche:
+
+| Cosa | Dove |
+|---|---|
+| Nuovo plugin custom properties (`useCustomPropsPlugin`) | `webpack-config-modules/custom-props-purgecss-plugin.mjs`, `webpack.config.mjs` |
+| Flag `purgeCssInDev` (purge e plugin in dev on-demand) | `webpack.config.mjs` |
+| PurgeCSS senza `variables` / `variablesSafelist` | `purgecss-setup.mjs`, `webpack.config.mjs` |
+| `shared.css` generato (css condivisi non più duplicati) | `webpack.config.mjs` (cacheGroup `shared`) |
+| Link a `shared.css` nei template | `_sf/templates/_main-tpl.html.twig` e template del progetto |
+
+### 1. Moduli in `webpack-config-modules/`
+
+- **Aggiungere** `custom-props-purgecss-plugin.mjs`.
+- **Sostituire** `purgecss-setup.mjs` con la versione v3 (non gestisce più `variables` né `variablesSafelist`; la firma di `createPurgeCSSPlugins` non accetta più `variablesSafelist` e `variables`).
+- **Eliminare** `purgecss-variables-safelist.mjs` (sostituito dal plugin).
+- **Aggiornare** `postcss.config.mjs` (cambiano solo i commenti sulla gestione delle custom properties; il comportamento è invariato).
+- Negli altri file (`css-rules.mjs`, `get-jsConfig-aliases.mjs`, `inline-critical-css.mjs`, `mini-svg-data-uri-loader.cjs`, `svg-rules.mjs`, `svgo.config.mjs`) **cambia solo** la riga `// v.2` in `// v.3`. Il contenuto è identico alla v2 e possono essere lasciati invariati.
+
+Non servono nuovi pacchetti npm: il plugin usa `postcss` e `glob`, già presenti tra le devDependencies dello starter. Se `postcss-jit-props` non è usato per altro, può essere disinstallato.
+
+### 2. Modifiche a `webpack.config.mjs`
+
+1. Riga 2: `// v.2` → `// v.3`.
+2. Nel blocco delle costanti di configurazione, dopo `usePurgeCss`, **rimuovere** `variables` da `purgeCSSOptions`:
+
+   ```js
+   ,purgeCSSOptions = {
+     keyframes: true,
+     debug: false
+   }
+   ```
+
+3. **Aggiungere** i nuovi flag e le costanti derivate (dopo `purgeCSSOptions`):
+
+   ```js
+   ,useCustomPropsPlugin = true // false: il plugin non viene caricato, le custom properties restano a carico del progetto
+   ,customPropsFile = path.resolve(__dirname, './app/css/custom-properties.css')
+   ,purgeCssInDev = false // true (solo per test): purge e plugin attivi anche in dev
+   ,inlineCssInDev = inlineCssInDevMode && !purgeCssInDev
+   ,runPurgeCss = usePurgeCss && (!isDevelopment || purgeCssInDev)
+   ,runCustomPropsPlugin = useCustomPropsPlugin && (!isDevelopment || purgeCssInDev)
+   ```
+
+4. **Aggiungere**, subito dopo la chiusura del blocco `const`, l'import dinamico del plugin:
+
+   ```js
+   const { CustomPropsPurgeCssPlugin } = runCustomPropsPlugin
+     ? await import('./webpack-config-modules/custom-props-purgecss-plugin.mjs')
+     : {};
+   ```
+
+5. **Entry**: rinominare l'oggetto `entries` in `projectEntries` e aggiungere subito sotto il nuovo `entries` derivato (in dev senza plugin, il master con tutte le custom properties viene aggiunto come primo modulo delle entry non `.critical`):
+
+   ```js
+   const entries = (useCustomPropsPlugin && isDevelopment && !purgeCssInDev)
+     ? Object.fromEntries(Object.entries(projectEntries).map(([name, entry]) => [
+       name,
+       /\.critical/.test(name) ? entry : [customPropsFile, ...[entry].flat()]
+     ]))
+     : projectEntries;
+   ```
+
+6. **`optimization`**: sostituire il commento `// realContentHash: true,` con `realContentHash: !isDevelopment || purgeCssInDev,`.
+7. **PurgeCSS**: la condizione `...(usePurgeCss ? createPurgeCSSPlugins({...}) : [])` diventa `...(runPurgeCss ? ... : [])`, e nella chiamata a `createPurgeCSSPlugins` va **rimosso** il blocco `variablesSafelist: { declarationGlobs, shadowGlobs, seeds }`. I glob `shadowGlobs` e `seeds` si spostano nel plugin (punto seguente, come `extraUsageGlobs` e `seeds`).
+8. **Chunk `shared` anche per i css** (in v2 i css restavano nel css di ogni entry, duplicati). Nel commento e nella funzione `shared_chunk_paths` **rimuovere** la riga `if (module.type === 'css/mini-extract') return false;` (e il vecchio commento/`TODO` che spiegava perché i css restavano fuori dallo `shared`), e nel cacheGroup `shared` (`optimization.splitChunks.cacheGroups`) sostituire `chunks: 'all'` con:
+
+   ```js
+   enforce: true, // shared.js e shared.css sempre generati, anche sotto la soglia minSize
+   chunks: (chunk) => !/\.critical/.test(chunk.name) // le entry `.critical` restano autosufficienti
+   ```
+
+   Ora viene generato anche `shared.css`, che va linkato nei template (vedi la sezione 3, "Template") e le cui definizioni delle custom properties vengono iniettate dal plugin (punto successivo, `sets`). Il purge dei `@keyframes` lavora sul singolo asset: se un `@keyframes` definito in `shared.css` è usato solo in un altro css, va aggiunto a `safelist.keyframes` (oppure `keyframes: false` in `purgeCSSOptions`).
+9. **Aggiungere in fondo all'array `plugins`** (dopo PurgeCSS, che deve restare prima):
+
+   ```js
+   ...(runCustomPropsPlugin
+     ? [new CustomPropsPurgeCssPlugin({
+       definitionsFile: customPropsFile,
+       sets: [
+         // il critical css è inline nei template: deve restare autosufficiente
+         { sources: ['layout.critical.*.css'] },
+         // shared.css è linkato in tutte le pagine e contiene le definizioni per tutti i css delle entry
+         { sources: ['shared.*.css', 'index.*.css'], target: 'shared.*.css' },
+       ],
+       extraUsageGlobs: [ // ex `shadowGlobs`
+         path.resolve(__dirname, './app/src/web-components/**/*.css'),
+         `${minimo_path}/src/web-components/**/*.css`,
+       ],
+       // seeds: [/^--btn-secondary-/], // ex `seeds` di variablesSafelist, se ancora necessari
+       minify: !isDevelopment
+     })]
+     : [])
+   ```
+
+   I `sets` vanno adattati alle entry del progetto: `sources` è l'elenco dei nomi degli asset CSS compilati (con l'hash nel nome, si usa `*`, oppure una RegExp) e `target` (opzionale) l'asset in cui iniettare le definizioni; se omesso è il primo asset del set. Ogni entry con un proprio css deve comparire in un set, altrimenti l'uso di custom properties in quel css non viene rilevato e le definizioni corrispondenti mancano.
+10. **`cssRules`**: passare `inlineCssInDevMode: inlineCssInDev` (non più `inlineCssInDevMode`).
+11. Aggiornare, se presenti, i commenti che citano `variables: true`, `safelist.variables` o `purgecss-variables-safelist.mjs`.
+
+### 3. Template
+
+Nel template di riferimento dello starter (`_sf/templates/_main-tpl.html.twig`) preload e link a `shared.css` sono già presenti. Nei template del progetto (twig/altro) che linkano gli asset a mano aggiungere preload e link a `shared.css`, **prima** di quelli del css della entry (vedi `_sf/templates/_main-tpl.html.twig`):
+
+```twig
+<link rel="preload" href="{{ asset('shared.css') }}" as="style">
+<link rel="preload" href="{{ asset('index.css') }}" as="style">
+<link rel="stylesheet" href="{{ asset('shared.css') }}" type="text/css" media="all">
+<link rel="stylesheet" href="{{ asset('index.css') }}" type="text/css" media="all">
+```
+
+Con `HtmlWebpackPlugin` (`inject`) `shared.css` è inserito automaticamente. Se il progetto ha entry aggiuntive con un proprio css (es. `admin`), aggiungere `shared.css` anche ai loro template e il css della entry ai `sets` del plugin.
+
+### 4. File CSS del progetto
+
+- Verificare che `app/css/custom-properties.css` esista (è il master, copiato da `starter-install.sh` da minimo). Non importarlo nelle entry CSS (in `app/css/index.css` l'`@import` deve restare commentato o assente): i css compilati devono contenere solo usi `var(--nome)`, altrimenti le definizioni sarebbero duplicate.
+- Se `postcss.config.mjs` usa `postcss-jit-props`, eliminarlo (o lasciarlo commentato): non deve essere usato insieme al plugin.
+
+### 5. Cambiamenti di comportamento
+
+- **`shared.css`:** con `enforce: true` viene sempre generato (se esiste almeno un modulo css in `node_modules` o nelle directory di `shared_chunk_paths`). I template devono linkarlo prima del css della entry. In v2 non esisteva e nessun template lo linkava.
+- **Dev con css iniettato da style-loader** (`inlineCssInDevMode = true`, il default dello starter): non viene generato nessun asset css, quindi neanche `shared.css`, e un `link` a `shared.css` nel template darebbe 404. Per i progetti con template server-side (es. Symfony) impostare `inlineCssInDevMode = false` (già previsto nei commenti `sf:` della config); con `HtmlWebpackPlugin` il link è inserito solo se il file esiste.
+- **Dev:** con `purgeCssInDev: false` (default) né PurgeCSS né il plugin girano in dev, e il css resta iniettato con style-loader. In v2 il purge era sempre attivo anche in dev. Per verificare il purge o il plugin in dev impostare `purgeCssInDev = true`: `inlineCssInDevMode` viene forzato a `false` e `realContentHash` attivato.
+- **Prod:** PurgeCSS non rimuove più le custom properties (`variables` è sempre `false`); le definizioni sono iniettate all'inizio del css target di ogni set, dopo il banner webpack, in ordine di dichiarazione del master. Le props con prefisso `--_` sono considerate locali e ignorate.
+- Se un target non corrisponde ad alcun asset viene emesso un warning di webpack. Un target con nome letterale (senza `*`) che non corrisponde ad alcun asset viene invece emesso come nuovo asset, che va poi linkato nei template.
+
+### 6. Verifica dopo l'aggiornamento
+
+1. `NODE_ENV=production npx webpack --config ./webpack.config.mjs --stats minimal`: nessun errore o warning del plugin.
+2. Nei css di output (`build/`) le custom properties usate sono definite nell'asset target del set (dopo il banner), quelle non usate sono assenti, e non compaiono duplicazioni tra critical e css principale.
+3. In `build/` esiste `shared.<hash>.css` (con le definizioni delle custom properties), le pagine lo linkano prima del css della entry senza 404, i css delle entry non duplicano gli stili condivisi e la entry `.critical` resta autosufficiente.
+4. `NODE_ENV=development` (con `webpack serve`): le pagine mostrano stili e colori corretti; il master viene caricato per intero come primo modulo delle entry.
+5. Se qualche componente perde stili solo in produzione, provare `useCustomPropsPlugin = false` per isolare il problema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.36.1",
+  "version": "1.37.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",

package/src/css/forms/form-group.css

@@ -2,7 +2,6 @@
   display: flex;
   flex-flow: column nowrap;
   gap: var(--size-xxs);
-  align-content: flex-start; /* multiline container */
   align-items: flex-start;
   justify-content: stretch;
   padding-block: var(--form-group-padding-block);

package/src/minimo.css

@@ -5,53 +5,53 @@
 /* @import '@css/custom-media.css'; */ /* managed by postcss */
 /* @import '@css/custom-properties.css' layer('base'); */ /* managed by postcss-jit-props */
 
-@import '@minimo/css/reset.css';
-@import '@minimo/css/layout-base.css';
-@import '@minimo/css/container.css';
-
-@import '@minimo/css/forms/forms.css';
-@import '@minimo/css/forms/fieldset.css';
-@import '@minimo/css/forms/form-collections.css';
-@import '@minimo/css/forms/form-group.css';
-@import '@minimo/css/forms/input-group.css';
-@import '@minimo/css/forms/form-disabled-readonly.css';
-@import '@minimo/css/forms/validation.css';
-@import '@minimo/css/forms/form-utilities.css';
-@import '@minimo/css/forms/switch.css';
-
-@import '@minimo/css/buttons/buttons.css';
-@import '@minimo/css/buttons/buttons-primary.css';
-@import '@minimo/css/buttons/buttons-secondary.css';
-@import '@minimo/css/buttons/status-buttons.css';
-@import '@minimo/css/buttons/btn-close.css';
-
-@import '@minimo/css/badge.css';
-@import '@minimo/css/text.css';
-@import '@minimo/css/links.css';
-@import '@minimo/css/headings.css';
-@import '@minimo/css/alerts.css';
-@import '@minimo/css/icons.css';
-@import '@minimo/css/svg.css';
-@import '@minimo/css/table.css';
-@import '@minimo/css/flex.css';
-@import '@minimo/css/grid.css';
-@import '@minimo/css/details.css';
-
-@import '@minimo/css/sizes.css';
-@import '@minimo/css/display.css';
-@import '@minimo/css/margin-padding.css';
-/* @import '@minimo/css/margin-padding-media.css';  responsive version */
+@import '@minimoSrc/css/reset.css';
+@import '@minimoSrc/css/layout-base.css';
+@import '@minimoSrc/css/container.css';
+
+@import '@minimoSrc/css/forms/forms.css';
+@import '@minimoSrc/css/forms/fieldset.css';
+@import '@minimoSrc/css/forms/form-collections.css';
+@import '@minimoSrc/css/forms/form-group.css';
+@import '@minimoSrc/css/forms/input-group.css';
+@import '@minimoSrc/css/forms/form-disabled-readonly.css';
+@import '@minimoSrc/css/forms/validation.css';
+@import '@minimoSrc/css/forms/form-utilities.css';
+@import '@minimoSrc/css/forms/switch.css';
+
+@import '@minimoSrc/css/buttons/buttons.css';
+@import '@minimoSrc/css/buttons/buttons-primary.css';
+@import '@minimoSrc/css/buttons/buttons-secondary.css';
+@import '@minimoSrc/css/buttons/status-buttons.css';
+@import '@minimoSrc/css/buttons/btn-close.css';
+
+@import '@minimoSrc/css/badge.css';
+@import '@minimoSrc/css/text.css';
+@import '@minimoSrc/css/links.css';
+@import '@minimoSrc/css/headings.css';
+@import '@minimoSrc/css/alerts.css';
+@import '@minimoSrc/css/icons.css';
+@import '@minimoSrc/css/svg.css';
+@import '@minimoSrc/css/table.css';
+@import '@minimoSrc/css/flex.css';
+@import '@minimoSrc/css/grid.css';
+@import '@minimoSrc/css/details.css';
+
+@import '@minimoSrc/css/sizes.css';
+@import '@minimoSrc/css/display.css';
+@import '@minimoSrc/css/margin-padding.css';
+/* @import '@minimoSrc/css/margin-padding-media.css';  responsive version */
 /* alternative boostrap naming
-@import '@minimo/css/margin-padding-bootstrap.css';
-@import '@minimo/css/margin-padding-bootsrap-media.css';
+@import '@minimoSrc/css/margin-padding-bootstrap.css';
+@import '@minimoSrc/css/margin-padding-bootsrap-media.css';
 */
-@import '@minimo/css/overflow.css';
-@import '@minimo/css/position.css';
-@import '@minimo/css/visibility.css';
+@import '@minimoSrc/css/overflow.css';
+@import '@minimoSrc/css/position.css';
+@import '@minimoSrc/css/visibility.css';
 
 
 /* spinner: include the css of the choosen spinner only */
-@import '@minimo/components/spinner/spinner-circle-basic.css';
+@import '@minimoSrc/components/spinner/spinner-circle-basic.css';
 
 
 /* @import '@css/layout.css'; */

package/dev-tools/starter-kit/source_files/root/sf_templates/email/css/mail-embed.css

@@ -1 +0,0 @@
- a,body, p, table, td{-webkit-text-size-adjust:100%;-moz-text-size-adjust:100%;text-size-adjust:100%}.content.body a{font-weight:700;color:#036;text-decoration:underline;cursor:pointer}.content.body a:hover{color:#010112}@media only screen and (max-width:640px){body[class="yahoo-fix"] .device-width{width:440px!important}.content.columns-wrapper td.column-spacer{height:0!important} .content.columns-wrapper td.column-spacer,.content.columns-wrapper td.column-width{display:block!important;width:100%!important}.content.columns-wrapper .column-content td h2{font-size:24px!important}.content.columns-wrapper .column-content td .text{font-size:18px!important}.content.columns-wrapper .column-content td .buttons{font-size:21px!important}}@media only screen and (max-width:479px){body[class="yahoo-fix"] .device-width{width:280px!important}}

package/dev-tools/starter-kit/source_files/root/sf_templates/email/css/mail-inline.css

@@ -1 +0,0 @@
-body{width:100%;padding:0;margin:0;font-family:helvetica,arial,sans-serif;font-style:normal;font-weight:400;line-height:1.5;color:#333;background-color:#efefef;-webkit-font-smoothing:antialiased}body .device-width{width:600px;padding:0}table{border-collapse:collapse}p{mso-table-lspace:0;mso-table-rspace:0;margin-top:12px;margin-bottom:12px}#wrapper{width:100%;margin:0 auto;border:none}#wrapper > tbody > tr > td{width:100%;padding:10px 10px 20px;background-color:#efefef;border:none}.content{margin:0 auto}.content.header > tbody > tr > td{padding:10px;text-align:center;background:#efefef}.content.header > tbody > tr > td > img{display:inline-block;max-width:100%;height:auto}.content.header .logo{padding-top:10px;padding-bottom:10px}.content.body > tbody > tr > td{padding:20px 30px;vertical-align:top;color:#333;background-color:#fff}.content.body > tbody > tr > td a{font-weight:700;color:#036;text-decoration:underline;cursor:pointer}.content.body > tbody > tr > td a:hover{color:#010112}.content.body > tbody > tr > td h1{margin-top:0;margin-bottom:24px;font-size:28px;font-weight:700}.content.body > tbody > tr > td p{font-size:21px}.content.body > tbody > tr > td img{max-width:100%;height:auto}.content.footer td{padding-top:10px;padding-bottom:10px;font-size:80%;color:#373737;text-align:center;background:#efefef}.logo-network{display:inline-block;padding:5px;margin:10px auto;background-color:#efefef}.network-info{font-size:13px;font-style:italic;color:#888}.text-center{text-align:center}.text-right{text-align:right}.text-left{text-align:left}.small, small{font-size:13px}.margin-top{margin-top:24px}.margin-bottom{margin-bottom:24px}.text-monospace{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace}.text-muted{color:#666}em, i{font-style:italic} b,strong{font-weight:700}.table{width:100%;margin:12px 0 24px;border-collapse:collapse} .table td,.table th{padding:6px 10px;vertical-align:top;text-align:left;border-bottom:1px solid #4b4a4a}.table th{font-weight:600}.table thead th{border-bottom-width:2px}