@massimo-cassandro/minimo 1.35.0 → 1.36.0

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

@@ -161,7 +161,9 @@ When set, each mode has its own `source` array, and the generated CSS composes a
 - the base mode's props go in a top-level `:root { ... }` block, with `color-scheme: <all modes>;` prepended
 - every other mode's props go in `@media (prefers-color-scheme: <mode>) { :root { ... } }`, with `color-scheme: <mode>;` prepended
 
-`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`).
+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` (`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
@@ -80,7 +80,16 @@ export const buildSourceModes = async ({
   const jsonFilesByMode = {};
 
   for (const mode of modeNames) {
+    // Non-base modes may reference base-mode tokens (always defined, since
+    // the base block is the unconditional top-level `:root`). The base
+    // sources are passed as `include`: available for reference resolution
+    // but flagged isSource: false, and skipped by the css/json formats.
+    // Base-mode-only on purpose: a reference to a token that exists only in
+    // another `@media` block would build fine but be undefined at runtime.
+    const include = mode === baseMode ? [] : sourceModes[baseMode];
+
     const sd = new StyleDictionary({
+      include,
       source: sourceModes[mode],
       parsers: [LEGACY_TOKENS_PARSER_NAME],
       log: { verbosity: 'verbose' },
@@ -116,6 +125,7 @@ export const buildSourceModes = async ({
       const files = buildJsonFiles(concreteFilePaths, jsonDestFile, jsonFormat, jsonExpression, `-${mode}`);
 
       const jsonSd = new StyleDictionary({
+        include,
         source: sourceModes[mode],
         parsers: [LEGACY_TOKENS_PARSER_NAME],
         log: { verbosity: 'silent' },

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

@@ -189,8 +189,23 @@ StyleDictionary.registerFormat({
       return a.name.localeCompare(b.name, 'en', { numeric: true, sensitivity: 'base' });
     };
 
+    // 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
-      .slice()
+      .filter((token) => token.isSource !== false)
       // .sort((a, b) => a.name.localeCompare(b.name, 'en', {numeric: true, sensitivity: 'base'}))
       .sort((a, b) => sortFunction(a,b))
       .flatMap((token) => {
@@ -204,7 +219,7 @@ StyleDictionary.registerFormat({
             .split('\n')
             .map((line) => `${line}${commentSuffix}`)
             .join('\n');
-          return [typographyLines];
+          return trackSource(token, [typographyLines]);
         }
 
         let value;
@@ -247,7 +262,16 @@ StyleDictionary.registerFormat({
           value = String(token.$value ?? token.value);
         }
 
-        return [`  --${token.name}: ${value};${commentSuffix}`];
+        // Multi-line values (e.g. Open Props' linear() easings) are collapsed
+        // to a single line: declarations are parsed one line at a time (see
+        // parseCustomProps in ../merge-css.mjs), so a multi-line value would
+        // be truncated to its first line.
+        value = String(value)
+          .replace(/\s*\n\s*/g, ' ')
+          .replace(/\(\s+/g, '(')
+          .replace(/\s+\)/g, ')');
+
+        return trackSource(token, [`  --${token.name}: ${value};${commentSuffix}`]);
       });
 
     // Build a name → declaration-tail map from the declarations generated
@@ -259,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/formats/json.mjs

@@ -136,6 +136,10 @@ StyleDictionary.registerFormat({
     const tokenMap = (expressionMode === 'resolve') ? makeTokenMap(dictionary) : null;
 
     for (const token of dictionary.allTokens) {
+      // Tokens loaded via `include` (sourceModes: base-mode tokens made
+      // available to other modes for reference resolution) are not output.
+      if (token.isSource === false) continue;
+
       // Rebuild the nested tree from the token path
       let node = root;
       for (let i = 0; i < token.path.length - 1; i++) {
@@ -205,7 +209,7 @@ export const collectConcreteFilePaths = async (sd) => {
   await sd.hasInitialized;
   const paths = new Set();
   for (const token of sd.allTokens) {
-    if (token.filePath) paths.add(token.filePath);
+    if (token.filePath && token.isSource !== false) paths.add(token.filePath);
   }
   return [...paths].sort();
 };

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/check-unresolved-custom-props.mjs

@@ -202,14 +202,17 @@ async function run() {
     /** @type {Map<string, Map<string, string>>} */
     const sourceFileByPropByMode = new Map();
 
-    /** @param {string[]} sourcePatterns @returns {Promise<Map<string,string>>} */
-    const resolveSourceFileMap = async (sourcePatterns) => {
+    // includePatterns: base-mode sources, passed as `include` for non-base
+    // modes so cross-mode references resolve (same as build-source-modes.mjs).
+    /** @param {string[]} sourcePatterns @param {string[]} [includePatterns] @returns {Promise<Map<string,string>>} */
+    const resolveSourceFileMap = async (sourcePatterns, includePatterns = []) => {
       /** @type {Map<string, string>} */
       const map = new Map();
       const resolvedPaths = resolveSourcePaths(sourcePatterns, configDir);
       if (!resolvedPaths.length) return map;
       try {
         const sd = new StyleDictionary({
+          include: resolveSourcePaths(includePatterns, configDir),
           source: resolvedPaths,
           parsers: [LEGACY_TOKENS_PARSER_NAME],
           log: { verbosity: 'silent' },
@@ -217,7 +220,7 @@ async function run() {
         });
         const dictionary = await sd.getPlatformTokens('css');
         for (const token of dictionary.allTokens) {
-          if (token.filePath) map.set(`--${token.name}`, token.filePath);
+          if (token.filePath && token.isSource !== false) map.set(`--${token.name}`, token.filePath);
         }
       } catch {
         // Non-fatal: unused properties will be reported by name only.
@@ -227,7 +230,8 @@ async function run() {
 
     if (checkUnused && config.sourceModes) {
       for (const [mode, modeSource] of Object.entries(config.sourceModes)) {
-        sourceFileByPropByMode.set(mode, await resolveSourceFileMap(modeSource));
+        const includePatterns = mode === sourceModesBase ? [] : config.sourceModes[sourceModesBase];
+        sourceFileByPropByMode.set(mode, await resolveSourceFileMap(modeSource, includePatterns));
       }
     } else if (checkUnused && Array.isArray(config.source) && config.source.length) {
       const map = await resolveSourceFileMap(config.source);

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

@@ -77,6 +77,13 @@ const config = {
   // customPropsGroups, mergeCustomProps, addLayer, pxToRem etc. all apply
   // the same way as with a single `source`.
   //
+  // Cross-mode references: 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); it resolves to var(--color-1). The reverse (or between two
+  // non-base modes) is not supported and fails with a "reference not
+  // defined" error, since the target would be undefined outside its own
+  // @media block.
+  //
   // The JSON output (see JSON TOKENS OUTPUT below) is produced once per
   // mode, with the mode name appended to each filename, e.g. with
   // jsonDestFile: 'tokens' -> "tokens-light.jsonc", "tokens-dark.jsonc".
@@ -106,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,
@@ -195,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.0",
+  "version": "1.36.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",