@massimo-cassandro/minimo 1.35.1 → 1.36.0

package/dev-tools/design-tokens-builder/README.md

@@ -163,7 +163,7 @@ When set, each mode has its own `source` array, and the generated CSS composes a
 
 Tokens of a non-base mode can reference tokens defined in the base mode (e.g. a dark token using `{color.1}` defined in light, output as `var(--color-1)`). References to a non-base mode's tokens (from the base mode or from another non-base mode) fail with a "reference not defined" error, since the target would be undefined outside its own `@media` block.
 
-`customPropsGroups`, `mergeCustomProps`, `addLayer`, `pxToRem` etc. all apply the same way as with a single `source`. The JSON output (when `jsonBuildPath` is set) is produced once per mode, with the mode name appended to each filename (e.g. `tokens-light.jsonc` / `tokens-dark.jsonc`).
+`customPropsGroups`, `mergeCustomProps`, `addLayer`, `pxToRem` etc. all apply the same way as with a single `source` (`mergeCustomProps` set to an array of strings/RegExps matches the token files of every mode). The JSON output (when `jsonBuildPath` is set) is produced once per mode, with the mode name appended to each filename (e.g. `tokens-light.jsonc` / `tokens-dark.jsonc`).
 
 ---
 

package/dev-tools/design-tokens-builder/build-tokens-src/build-source-modes.mjs

@@ -44,7 +44,7 @@ import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
  * @param {{name:string,prefixes:string[]}[]} opts.customPropsGroups
  * @param {boolean}                opts.pxToRem
  * @param {string|null}            opts.addLayer
- * @param {boolean}                opts.mergeCustomProps
+ * @param {boolean|(string|RegExp)[]} opts.mergeCustomProps  true = merge all sources, array = only the matching token source files
  * @returns {Promise<{cssDestPath: string, totalCustomProps: number, jsonFilesByMode: Record<string, object[]>}>}
  */
 export const buildSourceModes = async ({
@@ -66,7 +66,7 @@ export const buildSourceModes = async ({
   // Read the pre-existing destFile (if any) BEFORE any Style Dictionary
   // instance runs, since the first one to write would overwrite it.
   if (mergeCustomProps) {
-    loadExistingCustomPropsScoped(path.join(buildPath, destFile), baseMode);
+    loadExistingCustomPropsScoped(path.join(buildPath, destFile), baseMode, mergeCustomProps);
   }
 
   const cssTransforms = pxToRem

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

@@ -84,8 +84,19 @@ export const pxToRem = buildConfig.pxToRem !== false;
 
 // mergeCustomProps: if true, custom properties already present in the CSS
 // destination file take priority over the ones generated by this build (see
-// build-tokens-src/merge-css.mjs). Default: false.
-export const mergeCustomProps = buildConfig.mergeCustomProps === true;
+// build-tokens-src/merge-css.mjs). It can also be an array of strings/RegExps:
+// only the properties generated by the token source files matching one of its
+// entries are merged. An empty or invalid value means false. Default: false.
+/** @type {boolean|(string|RegExp)[]} */
+export const mergeCustomProps = (() => {
+  const value = buildConfig.mergeCustomProps;
+  if (value === true) return true;
+  if (Array.isArray(value)) {
+    const entries = value.filter((entry) => typeof entry === 'string' || entry instanceof RegExp);
+    return entries.length ? entries : false;
+  }
+  return false;
+})();
 
 // addLayer: wraps the generated custom properties inside a CSS `@layer`
 // at-rule (see formats/css.mjs), e.g. `@layer project { :root { ... } }`.

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

@@ -192,6 +192,18 @@ StyleDictionary.registerFormat({
     // Tokens loaded via `include` (sourceModes: base-mode tokens made
     // available to other modes) stay in tokenByPath, so references to them
     // resolve to var(--name), but are not declared in this mode's block.
+    // property name → token source file, used by mergeCustomProps when the
+    // merge is limited to some source files (a token may generate several
+    // properties, e.g. typography)
+    /** @type {Record<string,string>} */
+    const sourceFileMap = {};
+    const trackSource = (token, tokenLines) => {
+      for (const name of Object.keys(parseCustomProps(tokenLines.join('\n')))) {
+        sourceFileMap[name] = token.filePath;
+      }
+      return tokenLines;
+    };
+
     const lines = dictionary.allTokens
       .filter((token) => token.isSource !== false)
       // .sort((a, b) => a.name.localeCompare(b.name, 'en', {numeric: true, sensitivity: 'base'}))
@@ -207,7 +219,7 @@ StyleDictionary.registerFormat({
             .split('\n')
             .map((line) => `${line}${commentSuffix}`)
             .join('\n');
-          return [typographyLines];
+          return trackSource(token, [typographyLines]);
         }
 
         let value;
@@ -259,7 +271,7 @@ StyleDictionary.registerFormat({
           .replace(/\(\s+/g, '(')
           .replace(/\s+\)/g, ')');
 
-        return [`  --${token.name}: ${value};${commentSuffix}`];
+        return trackSource(token, [`  --${token.name}: ${value};${commentSuffix}`]);
       });
 
     // Build a name → declaration-tail map from the declarations generated
@@ -271,7 +283,7 @@ StyleDictionary.registerFormat({
     // scopes the merge to that mode, so same-named props with different
     // values across modes are never mixed up.
     const generatedProps = parseCustomProps(lines.join('\n'));
-    const finalProps = mergeCustomProps(generatedProps, options.mode ?? null);
+    const finalProps = mergeCustomProps(generatedProps, options.mode ?? null, sourceFileMap);
 
     // Final output is always sorted alphabetically ascending by property
     // name, regardless of merge — this also keeps pre-existing-only

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

@@ -10,6 +10,12 @@
 //      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.
@@ -36,7 +42,11 @@ export const parseCustomProps = (cssText) => {
   /** @type {Record<string,string>} */
   const map = {};
   for (const match of cssText.matchAll(CUSTOM_PROP_RE)) {
-    map[match[1]] = match[2].trim();
+    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
+    if (tail.lastIndexOf('/*') > tail.lastIndexOf('*/')) tail += ' */';
+    map[match[1]] = tail;
   }
   return map;
 };
@@ -124,6 +134,32 @@ const splitModeScopes = (cssText) => {
   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.
+/** @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.
+ * @param {(string|RegExp)[]} sources
+ * @param {string|undefined} filePath token source file path
+ * @returns {boolean}
+ */
+const matchesSource = (sources, filePath) => {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, '/');
+  return sources.some((entry) => {
+    if (entry instanceof RegExp) {
+      entry.lastIndex = 0;
+      return entry.test(normalized);
+    }
+    return normalized.includes(entry.replace(/\\/g, '/'));
+  });
+};
+
 // null = merge disabled, or destination file not found yet (first build)
 /** @type {Record<string,string>|null} */
 let existingCustomProps = null;
@@ -137,9 +173,12 @@ 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)
  * @returns {Record<string,string>|null}
  */
-export const loadExistingCustomProps = (absDestPath) => {
+export const loadExistingCustomProps = (absDestPath, sources = true) => {
+  mergeSources = sources;
   existingCustomProps = existsSync(absDestPath)
     ? parseCustomProps(readFileSync(absDestPath, 'utf8'))
     : null;
@@ -154,9 +193,12 @@ export const loadExistingCustomProps = (absDestPath) => {
  * @param {string} baseMode mode whose declarations live in the top-level,
  *   non-nested `:root { ... }` 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)
  * @returns {Record<string, Record<string,string>>|null}
  */
-export const loadExistingCustomPropsScoped = (absDestPath, baseMode) => {
+export const loadExistingCustomPropsScoped = (absDestPath, baseMode, sources = true) => {
+  mergeSources = sources;
   if (!existsSync(absDestPath)) {
     scopedExistingCustomProps = null;
     return scopedExistingCustomProps;
@@ -177,16 +219,26 @@ export const loadExistingCustomPropsScoped = (absDestPath, baseMode) => {
  * 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.
+ * (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: {})
  * @returns {Record<string,string>}
  */
-export const mergeCustomProps = (generated, mode = null) => {
-  if (mode !== null) {
-    const existing = scopedExistingCustomProps?.[mode];
-    return existing ? { ...generated, ...existing } : generated;
+export const mergeCustomProps = (generated, mode = null, sourceFileMap = {}) => {
+  const existing = mode !== null ? scopedExistingCustomProps?.[mode] : existingCustomProps;
+  if (!existing) return generated;
+  if (mergeSources === true) return { ...generated, ...existing };
+
+  const merged = { ...generated };
+  for (const [name, tail] of Object.entries(existing)) {
+    if (!(name in generated) || matchesSource(mergeSources, sourceFileMap[name])) {
+      merged[name] = tail;
+    }
   }
-  return existingCustomProps ? { ...generated, ...existingCustomProps } : generated;
+  return merged;
 };

package/dev-tools/design-tokens-builder/build-tokens.mjs

@@ -116,7 +116,7 @@ if (sourceModes) {
   // pre-existing values take priority — right before serialising the final
   // CSS output. See merge-css.mjs.
   if (mergeCustomProps) {
-    loadExistingCustomProps(path.join(buildPath, destFile));
+    loadExistingCustomProps(path.join(buildPath, destFile), mergeCustomProps);
   }
 
   // Collect concrete source file paths (multi-file JSON mode only). Source

package/dev-tools/design-tokens-builder/tokens-config-sample.mjs

@@ -113,13 +113,25 @@ const config = {
   // are never touched regardless of this option.
   pxToRem: false,
 
-  // If true, custom properties already present in the CSS destination file
-  // (destFile, from a previous build) take priority over the ones generated
-  // by this build. Properties found only in the pre-existing file (no longer
-  // generated) are kept too. Useful to preserve manual overrides/additions
-  // made directly in the compiled CSS across rebuilds. Ignored on the first
-  // build, when destFile does not exist yet. Default: false.
-  // Comments at the end of custom properties are preserved, while full-line ones will be lost.
+  // Preserves custom properties already present in the CSS destination file
+  // (destFile, from a previous build) across rebuilds: their values take
+  // priority over the ones generated by this build. Useful to keep manual
+  // overrides/additions made directly in the compiled CSS. Ignored on the
+  // first build, when destFile does not exist yet. Accepted values:
+  //   false (default) - no merge: the destination file is fully regenerated
+  //   true            - merge all the sources
+  //   array           - strings and/or RegExps matched against the path of the
+  //                     token source files (those in `source` or `sourceModes`):
+  //                     only the properties generated by a matching file are
+  //                     merged, the others are overwritten by the generated value.
+  //                     A string matches if contained in the file path.
+  //                     An empty array is treated as false.
+  //                     e.g. ['/theme.minimo.tokens', /colors\.tokens\.(mjs|jsonc?)$/]
+  // With true or an array, properties found only in the pre-existing file (no
+  // longer generated, e.g. added by hand) are always kept.
+  // Comments at the end of a custom property line are preserved; full-line
+  // comments are lost, and a multi-line comment is cut at the end of its first
+  // line (and closed, to keep the CSS valid).
   mergeCustomProps: false,
 
   // Wraps the generated custom properties inside a CSS `@layer` at-rule,
@@ -202,11 +214,11 @@ const config = {
   // Additional CSS files that define custom properties used in the project
   // but not generated by build-tokens (e.g. third-party libraries)
   extraCustomPropsFiles: [
-    // '../../node_modules/open-props/open-props.min.css'
+    // `${node_modules_path}/open-props/open-props.min.css`
   ],
 
   // Directory containing the CSS files to scan for unresolved custom properties
-  dirToCheck: '../src',
+  dirToCheck: '../../app',
 
   // Regular expressions for custom property names to exclude from the check.
   // Useful for intentionally private/internal props (e.g. prefixed with --_).

package/package.json

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