@massimo-cassandro/minimo 1.41.4 → 1.41.6

package/dev-tools/design-tokens-builder/build-tokens-src/light-dark.mjs

@@ -1,46 +1,50 @@
-// build-tokens-src/light-dark.mjs
-// Supports the `useLightDarkFunc` config option (see config.mjs): with a
-// sourceModes build (see build-source-modes.mjs) that defines both a `light`
-// and a `dark` mode, custom properties present in BOTH — matched by name —
-// are written once, as `--name: light-dark(<light-value>, <dark-value>);`,
-// instead of being split across the base mode's top-level `:root { ... }`
-// block and a `@media (prefers-color-scheme: dark) { ... }` block. If the two
-// values are identical, light-dark() would be redundant: the bare value is
-// written instead, e.g. `--name: <value>;`.
-//
-// Only `light` and `dark` are affected:
-//   - a third mode (e.g. a custom `high-contrast` key in sourceModes) is left
-//     completely untouched, still nested under its own
-//     `@media (prefers-color-scheme: <mode>) { ... }` rule
-//   - a property present in only one of `light`/`dark` is left in its own
-//     mode's block — still behind that mode's `@media` rule, unless that mode
-//     happens to be the configured base mode
-//
-// The shared `light-dark()` declarations always land in the configured base
-// mode's block (build-source-modes.mjs' `sourceModesBase`, whichever of
-// `light`, `dark`, or a third mode that is) — never specifically in `light`'s
-// or `dark`'s own block — since the light-dark() function resolves against
-// the effective `color-scheme`, regardless of whether the declaration itself
-// sits inside a `@media (prefers-color-scheme: ...)` rule or not.
-//
-// Interaction with `mergeCustomProps`: nothing special is needed here — the
-// per-mode merge with pre-existing custom properties (see ../merge-css.mjs)
-// already runs earlier, inside computeFinalProps() (formats/css.mjs), before
-// this module ever sees the props. So a pre-existing file written with the
-// classic `@media (prefers-color-scheme: dark)` split (i.e. built before
-// useLightDarkFunc was turned on) is reconciled into light-dark() calls just
-// like freshly generated values, matched by property name. As the values
-// merged in this way were never meant to be combined into light-dark() calls,
-// unexpected pre-existing content (e.g. a manually-added property whose name
-// happens to collide across modes) can produce an invalid combined value —
-// left for the user to fix, same as any other mergeCustomProps edge case.
+/*
+  build-tokens-src/light-dark.mjs
+  Supporta l'opzione di config `useLightDarkFunc` (vedi config.mjs): con una
+  build sourceModes (vedi build-source-modes.mjs) che definisce sia una modalità `light`
+  sia una `dark`, le custom properties presenti in ENTRAMBE — individuate per nome —
+  vengono scritte una sola volta, come `--name: light-dark(<valore-light>, <valore-dark>);`,
+  invece di essere divise tra il blocco `:root { ... }` di primo livello della modalità base
+  e un blocco `@media (prefers-color-scheme: dark) { ... }`. Se i due
+  valori sono identici, light-dark() sarebbe ridondante: viene scritto invece
+  il valore semplice, ad es. `--name: <valore>;`.
+
+  Sono interessate solo `light` e `dark`:
+    - una terza modalità (ad es. una chiave personalizzata `high-contrast` in sourceModes) resta
+      del tutto intatta, sempre annidata nella propria regola
+      `@media (prefers-color-scheme: <modalità>) { ... }`
+    - una proprietà presente in una sola tra `light`/`dark` resta nel blocco della
+      propria modalità — sempre dietro la regola `@media` di quella modalità, a meno che quella
+      modalità non sia la modalità base configurata
+
+  Le dichiarazioni `light-dark()` condivise finiscono sempre nel blocco della modalità
+  base configurata (il `sourceModesBase` di build-source-modes.mjs, qualunque sia tra
+  `light`, `dark` o una terza modalità) — mai specificamente nel blocco di `light`
+  o di `dark` — dato che la funzione light-dark() si risolve in base al
+  `color-scheme` effettivo, indipendentemente dal fatto che la dichiarazione stessa
+  si trovi dentro una regola `@media (prefers-color-scheme: ...)` o meno.
+
+  Interazione con `mergeCustomProps`: qui non serve nulla di speciale — il merge
+  per modalità con le custom properties preesistenti (vedi ../merge-css.mjs)
+  viene già eseguito prima, dentro computeFinalProps() (formats/css.mjs), prima che
+  questo modulo veda le proprietà. Quindi un file preesistente scritto con la
+  classica divisione `@media (prefers-color-scheme: dark)` (cioè generato prima che
+  useLightDarkFunc fosse attivato) viene riconciliato in chiamate light-dark()
+  come i valori appena generati, individuando le proprietà per nome. Poiché i valori
+  uniti in questo modo non erano mai stati pensati per essere combinati in chiamate light-dark(),
+  contenuti preesistenti inattesi (ad es. una proprietà aggiunta a mano il cui nome
+  collide per caso tra le modalità) possono produrre un valore combinato non valido —
+  da correggere a cura dell'utente, come ogni altro caso limite di mergeCustomProps.
+*/
 
 import { buildCssBlock } from './formats/css.mjs';
 
-// Splits a declaration tail (as produced by computeFinalProps(): value +
-// terminating `;` + optional trailing comment) into its bare CSS value and
-// its trailing comment, so the value can be embedded as a light-dark()
-// argument without dragging the `;`/comment along.
+/*
+  Divide la coda di una dichiarazione (come prodotta da computeFinalProps(): valore +
+  `;` finale + eventuale commento finale) nel suo valore CSS semplice e nel suo
+  commento finale, così che il valore possa essere inserito come argomento di light-dark()
+  senza trascinare con sé `;`/commento.
+*/
 /** @param {string} tail @returns {{value: string, comment: string}} */
 const splitTail = (tail) => {
   const match = /^(.*?);\s*(\/\*.*\*\/)?\s*$/.exec(tail.trim());
@@ -50,16 +54,16 @@ const splitTail = (tail) => {
 
 /**
  * @param {object} opts
- * @param {Record<string, Record<string,string>>} opts.modeFinalProps  mode → (name → declaration tail) map, one entry per sourceModes key — as captured from computeFinalProps()/lastFinalProps (see formats/css.mjs) right after each per-mode sd.formatPlatform('css') call in build-source-modes.mjs
- * @param {string[]} opts.modeNames  all sourceModes keys, in config order
- * @param {string}   opts.baseMode   mode whose block is printed as a top-level, unconditioned `:root` (or custom selector) — see sourceModesBase in config.mjs
- * @param {string}   [opts.selector] customPropsSelector — passed through unchanged to buildCssBlock() (default: ':root')
+ * @param {Record<string, Record<string,string>>} opts.modeFinalProps  mappa modalità → (nome → coda della dichiarazione), una voce per ogni chiave di sourceModes — come catturata da computeFinalProps()/lastFinalProps (vedi formats/css.mjs) subito dopo ogni chiamata per modalità a sd.formatPlatform('css') in build-source-modes.mjs
+ * @param {string[]} opts.modeNames  tutte le chiavi di sourceModes, nell'ordine della config
+ * @param {string}   opts.baseMode   modalità il cui blocco viene stampato come `:root` (o selettore personalizzato) di primo livello, senza condizioni — vedi sourceModesBase in config.mjs
+ * @param {string}   [opts.selector] customPropsSelector — passato invariato a buildCssBlock() (default: ':root')
  * @param {{name:string,prefixes:string[]}[]} [opts.customPropsGroups]
  * @returns {{blocks: Record<string,string>, counts: Record<string,number>}|null}
- *   Rebuilt CSS block text + custom-prop count, keyed by mode, for every mode
- *   touched by the reconciliation (`light`, `dark`, and `baseMode`, which may
- *   coincide) — or null when sourceModes does not define both `light` and
- *   `dark` (useLightDarkFunc then has no effect, see config.mjs)
+ *   Testo del blocco CSS ricostruito + conteggio delle custom props, indicizzato per modalità, per ogni modalità
+ *   toccata dalla riconciliazione (`light`, `dark` e `baseMode`, che possono
+ *   coincidere) — oppure null quando sourceModes non definisce sia `light` sia
+ *   `dark` (useLightDarkFunc non ha allora alcun effetto, vedi config.mjs)
  */
 export const applyLightDarkFunc = ({ modeFinalProps, modeNames, baseMode, selector, customPropsGroups }) => {
   if (!modeNames.includes('light') || !modeNames.includes('dark')) return null;
@@ -73,11 +77,11 @@ export const applyLightDarkFunc = ({ modeFinalProps, modeNames, baseMode, select
   for (const name of commonNames) {
     const light = splitTail(lightProps[name]);
     const dark = splitTail(darkProps[name]);
-    // Prefers the light-side trailing comment (e.g. a token $description);
-    // falls back to the dark-side one if light has none.
+    // Preferisce il commento finale lato light (ad es. una $description del token);
+    // ripiega su quello lato dark se light non ne ha.
     const comment = light.comment || dark.comment;
-    // Equal light/dark values: light-dark(x, x) would be redundant — use the
-    // bare value directly instead.
+    // Valori light/dark uguali: light-dark(x, x) sarebbe ridondante — usa
+    // direttamente il valore semplice.
     const value = light.value === dark.value
       ? light.value
       : `light-dark(${light.value}, ${dark.value})`;
@@ -94,24 +98,30 @@ export const applyLightDarkFunc = ({ modeFinalProps, modeNames, baseMode, select
   const updatedFinalProps = { ...modeFinalProps };
   updatedFinalProps.light = stripCommon(lightProps);
   updatedFinalProps.dark = stripCommon(darkProps);
-  // The shared declarations always land in the base mode's own map — adding
-  // them back in if the base mode happens to be `light` or `dark` itself
-  // (whose map was just stripped above), or into a third mode's map.
+  /*
+    Le dichiarazioni condivise finiscono sempre nella mappa della modalità base — reinserendole
+    se la modalità base è proprio `light` o `dark` (la cui mappa è appena stata ripulita
+    qui sopra), oppure nella mappa di una terza modalità.
+  */
   updatedFinalProps[baseMode] = { ...updatedFinalProps[baseMode], ...sharedProps };
 
-  // The base mode's `color-scheme` value is always normalised to read
-  // "light dark [...other modes]", with `light` before `dark`, regardless of
-  // the order sourceModes keys were declared in config or of which of the
-  // two is the configured base — light-dark() itself is positional
-  // (light-value first, dark-value second), so the accompanying
-  // `color-scheme` declaration follows the same, predictable reading. Modes
-  // other than light/dark, if any, are appended after, unaffected.
+  /*
+    Il valore `color-scheme` della modalità base viene sempre normalizzato in
+    "light dark [...altre modalità]", con `light` prima di `dark`, indipendentemente dall'
+    ordine in cui le chiavi di sourceModes sono dichiarate nella config o da quale delle
+    due sia la modalità base configurata — light-dark() stessa è posizionale
+    (prima il valore light, poi quello dark), quindi la dichiarazione
+    `color-scheme` che l'accompagna segue la stessa lettura prevedibile. Le modalità
+    diverse da light/dark, se presenti, vengono aggiunte dopo, senza modifiche.
+  */
   const restModes = modeNames.filter((mode) => mode !== 'light' && mode !== 'dark');
   const colorScheme = ['light', 'dark', ...restModes].join(' ');
 
-  // Only `light`, `dark`, and the base mode (which may be one of the two, or
-  // a third mode) need re-rendering: every other sourceModes key is
-  // untouched and keeps its already-built block (see build-source-modes.mjs).
+  /*
+    Solo `light`, `dark` e la modalità base (che può essere una delle due, oppure
+    una terza modalità) devono essere renderizzate di nuovo: ogni altra chiave di sourceModes
+    non viene toccata e conserva il blocco già costruito (vedi build-source-modes.mjs).
+  */
   const modesToRebuild = new Set(['light', 'dark', baseMode]);
 
   /** @type {Record<string,string>} */

package/dev-tools/design-tokens-builder/build-tokens-src/merge-css.mjs

@@ -1,59 +1,63 @@
-// build-tokens-src/merge-css.mjs
-// Supports the `mergeCustomProps` config option: pre-existing custom
-// properties in the CSS destination file take priority over the ones
-// generated by the current build (manual overrides/additions survive rebuilds).
-//
-// Usage (single `source` build):
-//   1. Call loadExistingCustomProps(absDestPath) BEFORE Style Dictionary runs,
-//      since it reads the file that is about to be overwritten.
-//   2. The css/variables-sorted format (see formats/css.mjs) calls
-//      mergeCustomProps(generatedMap) while building the output, right before
-//      serialising the final CSS text.
-//
-// `mergeCustomProps` may also be an array of strings/RegExps: in that case
-// only the generated properties whose token source file matches one of the
-// entries are merged (pre-existing value wins); the others are overwritten by
-// the generated value. Pre-existing properties that are no longer generated
-// (no token, hence no source file) are always kept. See matchesSource().
-//
-// Usage (sourceModes build, see build-source-modes.mjs):
-//   1. Call loadExistingCustomPropsScoped(absDestPath, baseMode) BEFORE any
-//      of the per-mode Style Dictionary instances run.
-//   2. The css/variables-sorted format calls mergeCustomProps(generatedMap, mode)
-//      once per mode. Declarations are matched only within the same mode's
-//      scope (the base `:root { ... }` block, or the `:root { ... }` nested
-//      inside that mode's `@media (prefers-color-scheme: <mode>) { ... }`),
-//      so the same custom property name defined with different values across
-//      modes is never mixed up.
+/*
+  build-tokens-src/merge-css.mjs
+  Supporta l'opzione di config `mergeCustomProps`: le custom properties preesistenti
+  nel file CSS di destinazione hanno priorità su quelle generate dalla build
+  corrente (override/aggiunte manuali sopravvivono alle build successive).
+
+  Utilizzo (build a `source` singolo):
+    1. Chiamare loadExistingCustomProps(absDestPath) PRIMA che Style Dictionary venga eseguito,
+       perché legge il file che sta per essere sovrascritto.
+    2. Il format css/variables-sorted (vedi formats/css.mjs) chiama
+       mergeCustomProps(generatedMap) mentre costruisce l'output, subito prima di
+       serializzare il testo CSS finale.
+
+  `mergeCustomProps` può essere anche un array di stringhe/RegExp: in tal caso
+  vengono unite solo le proprietà generate il cui file sorgente di token corrisponde a una
+  delle voci (vince il valore preesistente); le altre vengono sovrascritte dal
+  valore generato. Le proprietà preesistenti non più generate
+  (nessun token, quindi nessun file sorgente) vengono sempre mantenute. Vedi matchesSource().
+
+  Utilizzo (build sourceModes, vedi build-source-modes.mjs):
+    1. Chiamare loadExistingCustomPropsScoped(absDestPath, baseMode) PRIMA che venga eseguita
+       una qualsiasi delle istanze di Style Dictionary per modalità.
+    2. Il format css/variables-sorted chiama mergeCustomProps(generatedMap, mode)
+       una volta per modalità. Le dichiarazioni vengono confrontate solo nell'ambito della stessa
+       modalità (il blocco base `:root { ... }`, oppure il `:root { ... }` annidato
+       dentro il `@media (prefers-color-scheme: <modalità>) { ... }` di quella modalità),
+       così che lo stesso nome di custom property definito con valori diversi tra le
+       modalità non venga mai confuso.
+*/
 
 import { existsSync, readFileSync } from 'node:fs';
 
 const CUSTOM_PROP_RE = /^\s*--([\w-]+):\s*(.+)$/gm;
 
 /**
- * Parses `--name: <tail>` declarations out of a CSS text block. <tail> is
- * captured verbatim (value, terminating `;`, and anything else on the same
- * line, e.g. a trailing comment) so it round-trips unchanged through a merge.
- * Only single-line declarations are supported.
+ * Estrae le dichiarazioni `--name: <tail>` da un blocco di testo CSS. <tail> viene
+ * catturato così com'è (valore, `;` finale e qualsiasi altra cosa sulla stessa
+ * riga, ad es. un commento finale) così da attraversare un merge senza modifiche.
+ * Sono supportate solo le dichiarazioni su una riga.
  * @param {string} cssText
- * @returns {Record<string,string>} name → declaration-tail map, in first-seen order
+ * @returns {Record<string,string>} mappa nome → coda della dichiarazione, in ordine di prima comparsa
  */
 export const parseCustomProps = (cssText) => {
   /** @type {Record<string,string>} */
   const map = {};
   for (const match of cssText.matchAll(CUSTOM_PROP_RE)) {
     let tail = match[2].trim();
-    // A multi-line comment is cut at the end of the line (only single-line
-    // declarations are parsed): close it, or the resulting CSS would be invalid
+    // Un commento su più righe viene troncato a fine riga (vengono lette solo le dichiarazioni
+    // su una riga): va chiuso, altrimenti il CSS risultante non sarebbe valido
     if (tail.lastIndexOf('/*') > tail.lastIndexOf('*/')) tail += ' */';
     map[match[1]] = tail;
   }
   return map;
 };
 
-// Returns the index of the closing brace matching the `{` at openIndex, by
-// simple depth counting. Braces inside comments/strings are not special-cased
-// — not expected to occur in generated custom-properties CSS.
+/*
+  Restituisce l'indice della parentesi graffa di chiusura corrispondente alla `{` in openIndex, con un
+  semplice conteggio della profondità. Le graffe dentro commenti/stringhe non sono gestite in modo
+  speciale — non ci si aspetta che compaiano nel CSS delle custom properties generato.
+*/
 /** @param {string} text @param {number} openIndex */
 const matchBraces = (text, openIndex) => {
   let depth = 0;
@@ -67,23 +71,26 @@ const matchBraces = (text, openIndex) => {
   return -1;
 };
 
-// Escapes a string for literal use inside a RegExp — needed because
-// customPropsSelector (see config.mjs) can contain regex-special characters,
-// e.g. ':where(html)'.
+/*
+  Esegue l'escape di una stringa per l'uso letterale dentro una RegExp — necessario perché
+  customPropsSelector (vedi config.mjs) può contenere caratteri speciali delle regex,
+  ad es. ':where(html)'.
+*/
 /** @param {string} str */
 const escapeRegExp = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-// Finds every @media (prefers-color-scheme: <mode>) { ... } block in a
-// previously generated sourceModes CSS destFile, with absolute character
-// offsets into cssText. Used to split the file into per-mode scopes (see
-// splitModeScopes() below) and, by check-unresolved-custom-props.mjs, to
-// tell which mode a given custom property declaration belongs to.
-// An optional wrapping `@layer { ... }` (addLayer option) is transparent to
-// this search, since it only looks for the `@media (prefers-color-scheme: ...)`
-// pattern itself.
-// @param {string} cssText
-// @returns {{mode:string,start:number,end:number}[]} start/end are the
-//   indices of the block's outer `{`/matching `}` (inclusive)
+/*
+  Trova ogni blocco @media (prefers-color-scheme: <modalità>) { ... } in un file di
+  destinazione CSS sourceModes generato in precedenza, con offset assoluti dei caratteri in
+  cssText. Usato per dividere il file in ambiti per modalità (vedi
+  splitModeScopes() più sotto) e, da check-unresolved-custom-props.mjs, per
+  capire a quale modalità appartiene una data dichiarazione di custom property.
+  Un eventuale `@layer { ... }` che racchiude tutto (opzione addLayer) è trasparente per
+  questa ricerca, dato che cerca solo il pattern `@media (prefers-color-scheme: ...)` stesso.
+  @param {string} cssText
+  @returns {{mode:string,start:number,end:number}[]} start/end sono gli
+    indici della `{` esterna del blocco e della `}` corrispondente (inclusi)
+*/
 export const findMediaModeBlocks = (cssText) => {
   const MEDIA_RE = /@media\s*\(\s*prefers-color-scheme\s*:\s*([\w-]+)\s*\)\s*\{/g;
   /** @type {{mode:string,start:number,end:number}[]} */
@@ -97,23 +104,25 @@ export const findMediaModeBlocks = (cssText) => {
   return mediaBlocks;
 };
 
-// Splits a previously generated sourceModes CSS destFile into per-mode
-// scopes (see build-source-modes.mjs for the shape of the generated file):
-//   - the base scope is the top-level `<selector> { ... }` block, i.e. the
-//     one NOT nested inside a `@media (prefers-color-scheme: ...)` rule
-//   - every other scope is the `<selector> { ... }` block nested inside its
-//     own `@media (prefers-color-scheme: <mode>) { ... }` rule
-// @param {string} cssText
-// @param {string} [selector] the customPropsSelector the file was generated
-//   with (default: ':root' — see config.mjs)
-// @returns {Record<string,string>} mode → CSS body text (base mode keyed as '__base__')
+/*
+  Divide un file di destinazione CSS sourceModes generato in precedenza in ambiti
+  per modalità (vedi build-source-modes.mjs per la forma del file generato):
+    - l'ambito base è il blocco `<selector> { ... }` di primo livello, cioè
+      quello NON annidato dentro una regola `@media (prefers-color-scheme: ...)`
+    - ogni altro ambito è il blocco `<selector> { ... }` annidato dentro la propria
+      regola `@media (prefers-color-scheme: <modalità>) { ... }`
+  @param {string} cssText
+  @param {string} [selector] il customPropsSelector con cui è stato generato il file
+    (default: ':root' — vedi config.mjs)
+  @returns {Record<string,string>} modalità → testo del corpo CSS (la modalità base ha chiave '__base__')
+*/
 const splitModeScopes = (cssText, selector = ':root') => {
   /** @type {Record<string,string>} */
   const scopes = {};
   const selectorRe = new RegExp(`${escapeRegExp(selector)}\\s*\\{`);
 
-  // 1. Every @media (prefers-color-scheme: <mode>) { ... } block, and the
-  // <selector> { ... } body nested inside each one.
+  // 1. Ogni blocco @media (prefers-color-scheme: <modalità>) { ... } e il corpo
+  // <selector> { ... } annidato dentro ciascuno.
   const mediaBlocks = findMediaModeBlocks(cssText);
   for (const { mode, start, end } of mediaBlocks) {
     const body = cssText.slice(start + 1, end);
@@ -127,8 +136,8 @@ const splitModeScopes = (cssText, selector = ':root') => {
     }
   }
 
-  // 2. The base <selector> { ... } block: the first one not nested inside
-  // any of the media blocks found above.
+  // 2. Il blocco base <selector> { ... }: il primo non annidato dentro
+  // nessuno dei blocchi media trovati qui sopra.
   const ROOT_RE = new RegExp(`${escapeRegExp(selector)}\\s*\\{`, 'g');
   for (const match of cssText.matchAll(ROOT_RE)) {
     const openIdx = match.index + match[0].length - 1;
@@ -143,18 +152,20 @@ const splitModeScopes = (cssText, selector = ':root') => {
   return scopes;
 };
 
-// `true` = merge every source; an array = merge only the properties generated
-// by the token source files matching one of its entries. Set by the
-// loadExistingCustomProps*() functions.
+/*
+  `true` = unisce ogni sorgente; un array = unisce solo le proprietà generate
+  dai file sorgente di token che corrispondono a una delle sue voci. Impostato
+  dalle funzioni loadExistingCustomProps*().
+*/
 /** @type {true|(string|RegExp)[]} */
 let mergeSources = true;
 
 /**
- * Whether a token source file matches one of the `mergeCustomProps` array
- * entries: a string matches if it is contained in the file path (path
- * separators normalised to `/`), a RegExp if it tests true against it.
+ * Indica se un file sorgente di token corrisponde a una delle voci dell'array
+ * `mergeCustomProps`: una stringa corrisponde se è contenuta nel percorso del file
+ * (separatori di percorso normalizzati in `/`), una RegExp se il test è positivo.
  * @param {(string|RegExp)[]} sources
- * @param {string|undefined} filePath token source file path
+ * @param {string|undefined} filePath percorso del file sorgente del token
  * @returns {boolean}
  */
 const matchesSource = (sources, filePath) => {
@@ -169,21 +180,21 @@ const matchesSource = (sources, filePath) => {
   });
 };
 
-// null = merge disabled, or destination file not found yet (first build)
+// null = merge disattivato, oppure file di destinazione non ancora trovato (prima build)
 /** @type {Record<string,string>|null} */
 let existingCustomProps = null;
 
-// Per-mode equivalent of existingCustomProps, populated by
-// loadExistingCustomPropsScoped() for a sourceModes build.
+// Equivalente per modalità di existingCustomProps, popolato da
+// loadExistingCustomPropsScoped() per una build sourceModes.
 /** @type {Record<string, Record<string,string>>|null} */
 let scopedExistingCustomProps = null;
 
 /**
- * Reads the CSS destination file (if it exists) and stores a name → value
- * map of its current custom properties for later merging.
- * @param {string} absDestPath absolute path of the CSS file to read
- * @param {true|(string|RegExp)[]} [sources] `true` merges every source, an
- *   array only the token source files matching one of its entries (default: true)
+ * Legge il file CSS di destinazione (se esiste) e memorizza una mappa nome → valore
+ * delle sue custom properties attuali per il merge successivo.
+ * @param {string} absDestPath percorso assoluto del file CSS da leggere
+ * @param {true|(string|RegExp)[]} [sources] `true` unisce ogni sorgente, un
+ *   array solo i file sorgente dei token corrispondenti a una delle sue voci (default: true)
  * @returns {Record<string,string>|null}
  */
 export const loadExistingCustomProps = (absDestPath, sources = true) => {
@@ -195,17 +206,17 @@ export const loadExistingCustomProps = (absDestPath, sources = true) => {
 };
 
 /**
- * sourceModes equivalent of loadExistingCustomProps(): reads the CSS
- * destination file (if it exists) and stores a per-mode name → value map,
- * scoped to each mode's own `<selector> { ... }` block (see splitModeScopes()).
- * @param {string} absDestPath absolute path of the CSS file to read
- * @param {string} baseMode mode whose declarations live in the top-level,
- *   non-nested `<selector> { ... }` block (no default — always passed explicitly
- *   by build-source-modes.mjs, from the resolved sourceModesBase)
- * @param {true|(string|RegExp)[]} [sources] `true` merges every source, an
- *   array only the token source files matching one of its entries (default: true)
- * @param {string} [selector] the customPropsSelector the pre-existing file was
- *   generated with (default: ':root' — see config.mjs)
+ * Equivalente sourceModes di loadExistingCustomProps(): legge il file CSS di
+ * destinazione (se esiste) e memorizza una mappa nome → valore per modalità,
+ * limitata al blocco `<selector> { ... }` di ciascuna modalità (vedi splitModeScopes()).
+ * @param {string} absDestPath percorso assoluto del file CSS da leggere
+ * @param {string} baseMode modalità le cui dichiarazioni stanno nel blocco
+ *   `<selector> { ... }` di primo livello, non annidato (nessun default — sempre passata esplicitamente
+ *   da build-source-modes.mjs, a partire dal sourceModesBase risolto)
+ * @param {true|(string|RegExp)[]} [sources] `true` unisce ogni sorgente, un
+ *   array solo i file sorgente dei token corrispondenti a una delle sue voci (default: true)
+ * @param {string} [selector] il customPropsSelector con cui è stato generato il file
+ *   preesistente (default: ':root' — vedi config.mjs)
  * @returns {Record<string, Record<string,string>>|null}
  */
 export const loadExistingCustomPropsScoped = (absDestPath, baseMode, sources = true, selector = ':root') => {
@@ -227,17 +238,17 @@ export const loadExistingCustomPropsScoped = (absDestPath, baseMode, sources = t
 };
 
 /**
- * Merges freshly generated custom properties with the ones previously loaded
- * via loadExistingCustomProps() / loadExistingCustomPropsScoped(). Pre-existing
- * values take priority; custom properties found only in the pre-existing file
- * (no longer generated) are kept as well. When the merge is limited to some
- * token source files (array option), a generated property whose source file
- * does not match is not overridden by its pre-existing value.
- * @param {Record<string,string>} generated name → value map produced by this build
- * @param {string|null} [mode] when set (sourceModes build), looks up the
- *   pre-existing props scoped to this mode instead of the flat/global map (default: null)
- * @param {Record<string,string>} [sourceFileMap] property name → token source
- *   file path, used only when the merge is limited to some sources (default: {})
+ * Unisce le custom properties appena generate a quelle caricate in precedenza
+ * tramite loadExistingCustomProps() / loadExistingCustomPropsScoped(). I valori
+ * preesistenti hanno priorità; vengono mantenute anche le custom properties presenti
+ * solo nel file preesistente (non più generate). Quando il merge è limitato ad alcuni
+ * file sorgente dei token (opzione array), una proprietà generata il cui file sorgente
+ * non corrisponde non viene sovrascritta dal suo valore preesistente.
+ * @param {Record<string,string>} generated mappa nome → valore prodotta da questa build
+ * @param {string|null} [mode] se impostato (build sourceModes), cerca le props
+ *   preesistenti limitate a questa modalità invece della mappa piatta/globale (default: null)
+ * @param {Record<string,string>} [sourceFileMap] nome della proprietà → percorso del file
+ *   sorgente del token, usata solo quando il merge è limitato ad alcuni sorgenti (default: {})
  * @returns {Record<string,string>}
  */
 export const mergeCustomProps = (generated, mode = null, sourceFileMap = {}) => {