@massimo-cassandro/minimo 1.38.5 → 1.39.0

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

@@ -4,6 +4,16 @@
 
 A set of Node.js scripts for managing CSS design tokens in a project. Built on top of [Style Dictionary v5](https://styledictionary.com/).
 
+### Purpose
+
+The purpose of this builder is to merge minimo's own design tokens with the tokens used in a project — typically coming from Figma or Penpot — and produce the custom properties used during development.
+
+The goal is to keep the project's token naming as close as possible to minimo's own, so that minimo's components can be customized without any further intervention.
+
+The best strategy is to name variables in Figma/Penpot after minimo's own names from the start, so that overriding a value stays a transparent, automatic process.
+
+In a preexisting project, though, some names may not match (e.g. the project's base color is named `primary`, while minimo's equivalent is `primary.100`). Rather than fixing the generated custom properties by hand after every build, a source entry can carry a `transform` option (see [Source token renaming](#source-token-renaming-transform) below) that remaps token names to minimo's own naming before they are even handed to Style Dictionary.
+
 ### Scripts
 
 | Script | Purpose |
@@ -61,7 +71,7 @@ npx buildTokens --config ./path/to/tokens-config.mjs
 The `source` array accepts any combination of:
 - Concrete file paths: `'./tokens/colors.jsonc'`
 - Glob patterns: `'./tokens/**/*.{json,jsonc,mjs}'`
-- `{ src, prefix }` objects, to add a prefix to the custom properties of those files (see [Source prefixes](#source-prefixes))
+- `{ src, prefix, transform }` objects, to add a prefix to the custom properties of those files (see [Source prefixes](#source-prefixes)) and/or to rename token nodes within those files (see [Source token renaming](#source-token-renaming-transform))
 
 **Supported formats:**
 - `.json` / `.jsonc` — parsed directly as token data
@@ -92,6 +102,31 @@ With this config Open Props' `gray.0` becomes `--op-gray-0`. `prefix` accepts `'
 
 See `build-tokens-src/source-prefixes.mjs`.
 
+#### Source token renaming (`transform`)
+
+An entry of `source` (or of a `sourceModes` mode) can also carry a `transform` object: a token found at a given dot-path in those files is moved to another dot-path, **before** Style Dictionary resolves `{references}` or builds the CSS/JSON output — unlike `prefix` above, which is a purely cosmetic CSS name change applied after the fact.
+
+Typical use case: a preexisting project (e.g. driven by Figma/Penpot) names its own base color `primary`, while minimo's own tokens reference `{primary.100}`. Instead of renaming the generated custom property by hand after every build, or hunting down every minimo reference to change it, `transform` fixes the token's own path once, in config:
+
+```js
+source: [
+  './my-tokens/*.mjs',
+  { src: './project-tokens/*.jsonc', transform: { primary: 'primary.100' } },
+],
+```
+
+With this config, whatever is defined at dot-path `primary` in the matched files is moved to `primary.100` — so it becomes `--primary-100` in the generated CSS, and every existing minimo reference to `{primary.100}` resolves correctly.
+
+- **Notation:** both sides of the map use Style Dictionary's own dot-path notation (`'primary.100'`), not the hyphen-joined custom-property notation (`'primary-100'`). Token name segments in this project can themselves contain hyphens (e.g. `btn-close`), so a hyphen can't reliably tell a path separator from a literal part of a segment name — a dot can, since it's already reserved by Style Dictionary as the `{reference}` path separator.
+- **References are rewritten automatically:** once every source file is merged, any `{reference}` to the token's *old* path — in the same file or a completely different one — is rewritten tree-wide to the *new* path (e.g. every `{primary}` in the build becomes `{primary.100}`). This is safe because Style Dictionary resolves `{references}` against the single merged token tree by absolute path: if `primary` existed exactly once, every `{primary}` anywhere unambiguously pointed at that one node.
+  - **Exception:** if the *same* source key (e.g. `primary`) is given a *different* destination in two different files' `transform` maps, each rename still works on its own, but the bare reference `{primary}` becomes ambiguous — which destination should it point to? In that case the automatic rewrite is skipped for that key (a warning is logged), and every `{primary}` reference must be fixed by hand to point at the correct one of the two new paths.
+- A source key not found in the file only logs a warning; it does not fail the build.
+- Applies to **both** the CSS and the JSON output (see [JSON output](#json-output) below), since both are rebuilt from the token's path, by then already renamed — no separate handling is needed.
+- Two entries giving different destinations for the same source key in the same file fail the build with an error.
+- `check-unresolved-custom-props.mjs` understands the same syntax.
+
+See `build-tokens-src/source-transforms.mjs` and `build-tokens-src/token-rename-parser.mjs`.
+
 
 #### Token file format (JS example)
 

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

@@ -36,7 +36,6 @@ import { CSS_TRANSFORMS, JSON_TRANSFORMS } from './platforms.mjs';
 import { customPropsCount, lastFinalProps } from './formats/css.mjs';
 import { buildJsonFiles, collectConcreteFilePaths } from './formats/json.mjs';
 import { loadExistingCustomPropsScoped } from './merge-css.mjs';
-import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
 import { applyLightDarkFunc } from './light-dark.mjs';
 
 /**
@@ -55,6 +54,8 @@ import { applyLightDarkFunc } from './light-dark.mjs';
  * @param {boolean|(string|RegExp)[]} opts.mergeCustomProps  true = merge all sources, array = only the matching token source files
  * @param {boolean}                opts.useLightDarkFunc  reconcile shared `light`/`dark` properties into `light-dark()` calls (default: true — see config.mjs and light-dark.mjs). Ignored unless sourceModes defines both a `light` and a `dark` key.
  * @param {string}                 opts.customPropsSelector  CSS selector wrapping the generated block(s) (default: ':root' — see config.mjs)
+ * @param {string[]}               opts.parserNames  Style Dictionary parser names to opt every instance into (legacy bridge, plus the token-rename parser when at least one source has a `transform` — see build-tokens.mjs)
+ * @param {string[]}               opts.preprocessorNames  Style Dictionary preprocessor names to opt every instance into (the token-rename reference rewriter, when at least one source has a `transform` — see build-tokens.mjs)
  * @returns {Promise<{cssDestPath: string, totalCustomProps: number, jsonFilesByMode: Record<string, object[]>}>}
  */
 export const buildSourceModes = async ({
@@ -72,6 +73,8 @@ export const buildSourceModes = async ({
   mergeCustomProps,
   useLightDarkFunc,
   customPropsSelector,
+  parserNames,
+  preprocessorNames,
 }) => {
   const modeNames = Object.keys(sourceModes);
 
@@ -112,7 +115,8 @@ export const buildSourceModes = async ({
     const sd = new StyleDictionary({
       include,
       source: sourceModes[mode],
-      parsers: [LEGACY_TOKENS_PARSER_NAME],
+      parsers: parserNames,
+      preprocessors: preprocessorNames,
       log: { verbosity: 'verbose' },
       platforms: {
         css: {
@@ -150,7 +154,8 @@ export const buildSourceModes = async ({
       const jsonSd = new StyleDictionary({
         include,
         source: sourceModes[mode],
-        parsers: [LEGACY_TOKENS_PARSER_NAME],
+        parsers: parserNames,
+        preprocessors: preprocessorNames,
         log: { verbosity: 'silent' },
         platforms: {
           json: {

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

@@ -150,24 +150,30 @@ export const customPropsGroups = Array.isArray(buildConfig.customPropsGroups)
 // (buildConfig.sourceModes is a non-null object), `source` is ignored and
 // each mode's own array of source patterns is resolved the same way.
 //
-// Entries of `source` / of each mode can also be `{ src, prefix }` objects,
-// to render the custom properties of those files with a prefix (see
-// source-prefixes.mjs). They are flattened here into plain patterns for
-// Style Dictionary; the prefixed ones are also collected in
-// `prefixedSources`, to be registered by build-tokens.mjs.
+// Entries of `source` / of each mode can also be `{ src, prefix, transform }`
+// objects, to render the custom properties of those files with a prefix
+// (see source-prefixes.mjs) and/or to rename token nodes within those files
+// (see source-transforms.mjs). They are flattened here into plain patterns
+// for Style Dictionary; the prefixed/transformed ones are also collected in
+// `prefixedSources`/`transformedSources`, to be registered by
+// build-tokens.mjs.
 // ---------------------------------------------------------------------------
 const sourceModesRaw = buildConfig.sourceModes ?? null;
 
 /** @type {import('./source-prefixes.mjs').PrefixedSource[]} */
 export const prefixedSources = [];
 
+/** @type {import('./source-prefixes.mjs').TransformedSource[]} */
+export const transformedSources = [];
+
 /**
  * @param {Parameters<typeof splitSourceEntries>[0]} entries
  * @returns {string[]}
  */
 const parseSourceEntries = (entries) => {
-  const { patterns, prefixed } = splitSourceEntries(entries, configDir);
+  const { patterns, prefixed, transformed } = splitSourceEntries(entries, configDir);
   prefixedSources.push(...prefixed);
+  transformedSources.push(...transformed);
   return patterns;
 };
 

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

@@ -160,8 +160,11 @@ const convertLegacyNode = (node, path, hybrids) => {
   );
 };
 
+// Exported for reuse by token-rename-parser.mjs, which needs the same
+// legacy-or-DTCG .json loading (hybrid-node handling included) for the
+// subset of files that also have a `transform` rename map registered.
 /** @param {string} contents @param {string} filePath @returns {unknown} */
-const parseLegacyFile = (contents, filePath) => {
+export const parseLegacyFile = (contents, filePath) => {
   const tree = JSON.parse(contents);
   return convertLegacyNode(tree, [], collectHybridNodes(tree, [], filePath));
 };

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

@@ -18,11 +18,18 @@
 // (token.filePath), while `src` may contain glob patterns: registerSourcePrefixes()
 // expands them (through Style Dictionary itself, so the result matches
 // token.filePath exactly) into a file path -> prefix map.
+//
+// The same entry object can also carry a `transform` map (renaming/moving
+// token nodes within the file's tree, e.g. { primary: 'primary.100' }) — see
+// source-transforms.mjs / token-rename-parser.mjs. splitSourceEntries() below
+// extracts both `prefix` and `transform` from the same `{ src, ... }` shape,
+// since they share the same source-matching syntax.
 
 import StyleDictionary from 'style-dictionary';
 import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
 import { resolveSourcePaths } from './resolve-source-paths.mjs';
 import { collectConcreteFilePaths } from './formats/json.mjs';
+import { normalizeTransformMap } from './source-transforms.mjs';
 
 /**
  * @typedef {object} PrefixedSource
@@ -47,20 +54,29 @@ export const normalizePrefix = (prefix) => {
   return value;
 };
 
+/**
+ * @typedef {object} TransformedSource
+ * @property {string[]} src               Source paths/globs, already resolved
+ * @property {Record<string,string>} transform  Validated rename map (see source-transforms.mjs)
+ */
+
 /**
  * Splits a `source` (or `sourceModes[mode]`) array, whose entries can be
- * strings or `{ src, prefix }` objects, into the flat list of patterns to pass
- * to Style Dictionary and the list of the prefixed entries. Patterns are
- * resolved relative to baseDir (see resolveSourcePaths).
- * @param {(string|{src: string|string[], prefix?: string})[]} entries
+ * strings or `{ src, prefix, transform }` objects, into the flat list of
+ * patterns to pass to Style Dictionary, the list of the prefixed entries and
+ * the list of the transformed (renamed) entries. Patterns are resolved
+ * relative to baseDir (see resolveSourcePaths).
+ * @param {(string|{src: string|string[], prefix?: string, transform?: Record<string,string>})[]} entries
  * @param {string} baseDir
- * @returns {{patterns: string[], prefixed: PrefixedSource[]}}
+ * @returns {{patterns: string[], prefixed: PrefixedSource[], transformed: TransformedSource[]}}
  */
 export const splitSourceEntries = (entries, baseDir) => {
   /** @type {string[]} */
   const patterns = [];
   /** @type {PrefixedSource[]} */
   const prefixed = [];
+  /** @type {TransformedSource[]} */
+  const transformed = [];
 
   for (const entry of entries ?? []) {
     if (typeof entry === 'string') {
@@ -73,7 +89,7 @@ export const splitSourceEntries = (entries, baseDir) => {
     if (!isObjectEntry) {
       throw new Error(
         `[build-tokens] config: invalid source entry ${JSON.stringify(entry)} `
-        + '(expected a string or an object { src, prefix })'
+        + '(expected a string or an object { src, prefix, transform })'
       );
     }
 
@@ -83,9 +99,13 @@ export const splitSourceEntries = (entries, baseDir) => {
     if (entry.prefix !== undefined && entry.prefix !== null && entry.prefix !== '') {
       prefixed.push({ src, prefix: normalizePrefix(entry.prefix) });
     }
+
+    if (entry.transform !== undefined && entry.transform !== null) {
+      transformed.push({ src, transform: normalizeTransformMap(entry.transform) });
+    }
   }
 
-  return { patterns, prefixed };
+  return { patterns, prefixed, transformed };
 };
 
 /**

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

@@ -0,0 +1,195 @@
+// build-tokens-src/source-transforms.mjs
+// Supports per-source token renaming: an entry of `source` (or of a
+// `sourceModes` mode) can carry a `transform` object next to (or instead of)
+// `prefix` — see splitSourceEntries() in source-prefixes.mjs — e.g.
+//
+//   { src: './project-tokens/*.jsonc', transform: { primary: 'primary.100' } }
+//
+// so that the token found at dot-path `primary` in those files is moved to
+// dot-path `primary.100` before Style Dictionary ever sees it, i.e. before
+// {references} are resolved and before the CSS/JSON output is built.
+//
+// Typical use case: a preexisting project defines its tokens (e.g. exported
+// from Figma/Penpot) under names that don't match minimo's own naming (e.g.
+// the project's base color is `primary`, minimo's equivalent is
+// `primary.100`). Without this feature every custom property generated from
+// the project's tokens would have to be renamed by hand after each build, or
+// every minimo reference to `{primary.100}` would have to be tracked down and
+// changed instead. `transform` fixes the token's OWN path once, in config.
+//
+// Notation: both sides of the map use Style Dictionary's own dot-path
+// notation (e.g. 'primary.100'), NOT the hyphen-joined custom-property
+// notation (e.g. 'primary-100'). Token name segments in this project can
+// themselves contain hyphens (e.g. btn-close, status-buttons), so a hyphen
+// can't reliably tell a path separator from a literal part of a segment name;
+// a dot can, since Style Dictionary already reserves it as the path
+// separator in {references} and never allows it inside a single segment
+// name.
+//
+// Moving a node would otherwise leave every {reference} to its OLD path
+// dangling (in the same file or a completely different one) — so this module
+// also collects a flat, file-independent from -> to map (getAllRenames()),
+// used by the token-rename PREPROCESSOR (see token-rename-parser.mjs) to
+// rewrite every such {reference} tree-wide, once all files are merged. This
+// is safe to do because Style Dictionary resolves {references} against the
+// single merged token tree by absolute path: if `primary` existed exactly
+// once before the rename, every {primary} anywhere in the build
+// unambiguously pointed at that one node, so every one of them must now
+// become {primary.100} — there is no risk of rewriting an unrelated
+// reference. The one case this can't disambiguate is the same "from" key
+// renamed to a DIFFERENT destination in a different file (each valid on its
+// own, per-file); see registerSourceTransforms() below — that key is
+// excluded from the tree-wide rewrite (with a console warning), and its
+// {references} are left for the user to fix by hand.
+//
+// How it works: unlike `prefix` (a purely cosmetic CSS name transform, see
+// source-prefixes.mjs, which never touches the token tree), `transform`
+// restructures the actual parsed token tree of the source file, via a
+// dedicated Style Dictionary parser (see token-rename-parser.mjs) that runs
+// at parse time, before files are merged and before reference resolution.
+// Since both the CSS and JSON output formats rebuild their tree from
+// token.path (by then already renamed), no separate handling is needed to
+// make the JSON output reflect the renamed structure too.
+
+import StyleDictionary from 'style-dictionary';
+import { collectConcreteFilePaths } from './formats/json.mjs';
+import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
+
+/** @type {Map<string, Record<string,string>>} */
+let transformByFile = new Map();
+
+// Flat, file-independent from -> to map, used by the token-rename
+// preprocessor (see token-rename-parser.mjs) to rewrite any {reference}
+// pointing to a renamed token's OLD path, anywhere in the build (same file or
+// another one) — references are resolved by Style Dictionary against the
+// single merged token tree, by absolute path, so a bare dot-path is
+// unambiguous UNLESS the same "from" key was given a different destination
+// in a different file (each valid on its own — see registerSourceTransforms
+// below), in which case that key is excluded here (with a warning) and its
+// {references} are left for the user to fix by hand, same as before this
+// preprocessor existed.
+/** @type {Map<string, string>} */
+let globalRenames = new Map();
+
+const DOT_PATH = /^[^.\s][\w-]*(\.[^.\s][\w-]*)*$/;
+
+/**
+ * Validates a `transform` map: every key/value must be a non-empty
+ * Style-Dictionary dot-path string (e.g. 'primary.100'), not a
+ * hyphen-joined custom-property name (e.g. 'primary-100') — see the notation
+ * rationale above.
+ * @param {unknown} map
+ * @returns {Record<string,string>}
+ * @throws {Error} if the map is not a plain object, or a key/value is invalid
+ */
+export const normalizeTransformMap = (map) => {
+  if (map === null || typeof map !== 'object' || Array.isArray(map)) {
+    throw new Error(
+      `[build-tokens] config: invalid "transform" value ${JSON.stringify(map)} (expected an object)`
+    );
+  }
+
+  for (const [from, to] of Object.entries(map)) {
+    if (!DOT_PATH.test(from) || !DOT_PATH.test(String(to))) {
+      throw new Error(
+        `[build-tokens] config: invalid "transform" entry "${from}": "${to}" `
+        + '(expected Style Dictionary dot-path strings, e.g. { "primary": "primary.100" })'
+      );
+    }
+  }
+
+  return map;
+};
+
+/**
+ * Expands the `transform` entries' `src` patterns into concrete file paths
+ * and stores the file path -> rename map used by getSourceTransform(). Must
+ * be called after registerLegacyTokensParser() and before any real build.
+ * Maps from different entries touching the same file are merged; the build
+ * fails only if two entries disagree on the destination of the same source
+ * key.
+ * @param {import('./source-prefixes.mjs').TransformedSource[]} transformedSources
+ * @returns {Promise<void>}
+ * @throws {Error} if the same file gets two conflicting destinations for the same key
+ */
+export const registerSourceTransforms = async (transformedSources) => {
+  /** @type {Map<string, Record<string,string>>} */
+  const map = new Map();
+  // Every destination seen for a given "from" key, across all files — used
+  // below to build globalRenames, and to detect the cross-file ambiguous
+  // case (same "from" key, different destination in a different file).
+  /** @type {Map<string, Set<string>>} */
+  const destinationsByFrom = new Map();
+
+  for (const { src, transform } of transformedSources) {
+    const sd = new StyleDictionary({
+      source: src,
+      parsers: [LEGACY_TOKENS_PARSER_NAME],
+      log: { verbosity: 'silent' },
+      platforms: {},
+    });
+
+    for (const filePath of await collectConcreteFilePaths(sd)) {
+      const existing = map.get(filePath) ?? {};
+      for (const [from, to] of Object.entries(transform)) {
+        if (existing[from] !== undefined && existing[from] !== to) {
+          throw new Error(
+            `[build-tokens] config: "${filePath}" has two different transform destinations `
+            + `for "${from}" ("${existing[from]}" and "${to}")`
+          );
+        }
+        existing[from] = to;
+
+        if (!destinationsByFrom.has(from)) destinationsByFrom.set(from, new Set());
+        destinationsByFrom.get(from).add(to);
+      }
+      map.set(filePath, existing);
+    }
+  }
+
+  transformByFile = map;
+
+  const global = new Map();
+  for (const [from, destinations] of destinationsByFrom) {
+    if (destinations.size > 1) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[build-tokens] transform: "${from}" is renamed to different destinations in different `
+        + `files (${[...destinations].join(', ')}) — {${from}} references will NOT be `
+        + 'auto-rewritten; update them by hand.'
+      );
+      continue;
+    }
+    global.set(from, [...destinations][0]);
+  }
+  globalRenames = global;
+};
+
+/**
+ * @returns {Map<string, string>} the flat from -> to map used to rewrite
+ * {references} across the whole build (see token-rename-parser.mjs)
+ */
+export const getAllRenames = () => globalRenames;
+
+/**
+ * @param {string|undefined} filePath  token.filePath
+ * @returns {Record<string,string>|undefined} the rename map registered for that file, if any
+ */
+export const getSourceTransform = (filePath) => (filePath ? transformByFile.get(filePath) : undefined);
+
+/** @returns {boolean} true if at least one file has a registered transform */
+export const hasRegisteredTransforms = () => transformByFile.size > 0;
+
+/**
+ * Builds the RegExp matching exactly the concrete files that have a
+ * registered transform, for the Style Dictionary parser `pattern` (see
+ * token-rename-parser.mjs). Returns null if no file has one.
+ * @returns {RegExp|null}
+ */
+export const transformedFilesPattern = () => {
+  const files = [...transformByFile.keys()];
+  if (files.length === 0) return null;
+
+  const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^(${files.map(escapeRegExp).join('|')})$`);
+};

package/dev-tools/design-tokens-builder/build-tokens-src/token-rename-parser.mjs

@@ -0,0 +1,257 @@
+// build-tokens-src/token-rename-parser.mjs
+// Implements the `transform` feature end-to-end (see source-transforms.mjs):
+//
+// 1. A Style Dictionary PARSER that moves/renames token nodes within a
+//    source file's own tree, according to the `transform` map registered for
+//    that file, BEFORE Style Dictionary merges files together and resolves
+//    {references}.
+// 2. A Style Dictionary PREPROCESSOR that, once every file has been parsed
+//    and merged into a single tree (but still before {references} are
+//    resolved), rewrites every {reference} in the WHOLE tree that points to
+//    one of the renamed tokens' OLD path, to its NEW path — so a reference
+//    doesn't have to be hunted down and updated by hand just because the
+//    token it points to was moved (in the same file or a completely
+//    different one; see getAllRenames() in source-transforms.mjs for why
+//    this is safe to do tree-wide).
+//
+// Only the exact concrete files that declare a `transform` are matched by
+// the parser (the `pattern` built by transformedFilesPattern() in
+// source-transforms.mjs); every other file is untouched by it and falls
+// through to Style Dictionary's own built-in loader, or to the legacy bridge
+// parser (legacy-tokens-parser.mjs) for plain .json sources. The
+// preprocessor, instead, always runs over the entire merged tree once
+// registered — it just has nothing to rewrite where no reference matches a
+// renamed path.
+//
+// Style Dictionary's combineJSON always reads a source file's `contents` as
+// raw text and hands it to whichever parser(s) match, regardless of
+// extension (see node_modules/style-dictionary/lib/utils/combineJSON.js) — a
+// custom parser never receives an already-executed .mjs module or an
+// already-JSON5-parsed object. The parser therefore has to load the file
+// itself the same way Style Dictionary's own loader (loadFile.js) would:
+// dynamic `import()` for .mjs/.js, JSON5 for .jsonc/.json5, and the existing
+// legacy-or-DTCG bridge (parseLegacyFile, reused as-is so hybrid-node
+// handling stays consistent) for .json.
+
+import StyleDictionary from 'style-dictionary';
+import JSON5 from 'json5';
+import * as path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { parseLegacyFile } from './legacy-tokens-parser.mjs';
+import { getSourceTransform, getAllRenames } from './source-transforms.mjs';
+
+export const TOKEN_RENAME_PARSER_NAME = 'minimo/token-rename';
+export const TOKEN_RENAME_PREPROCESSOR_NAME = 'minimo/token-rename-refs';
+
+/** @param {unknown} node @returns {node is Record<string, unknown>} */
+const isPlainObject = (node) => node !== null && typeof node === 'object' && !Array.isArray(node);
+
+/** @param {unknown} tree @param {string[]} pathSegments @returns {unknown} */
+const getAtPath = (tree, pathSegments) => pathSegments.reduce(
+  (node, segment) => (isPlainObject(node) ? node[segment] : undefined),
+  tree
+);
+
+// Removes the node at pathSegments (mutates tree), pruning parent groups left
+// empty by the removal (innermost first), so a fully-emptied group doesn't
+// linger as `{}` in the output tree.
+/** @param {Record<string, unknown>} tree @param {string[]} pathSegments */
+const deleteAtPath = (tree, pathSegments) => {
+  if (pathSegments.length === 0) return;
+
+  /** @type {Record<string, unknown>[]} */
+  const parents = [];
+  let node = /** @type {unknown} */ (tree);
+  for (let i = 0; i < pathSegments.length - 1; i++) {
+    if (!isPlainObject(node)) return;
+    parents.push(node);
+    node = node[pathSegments[i]];
+  }
+  if (!isPlainObject(node)) return;
+
+  delete node[pathSegments[pathSegments.length - 1]];
+
+  for (let i = pathSegments.length - 2; i >= 0; i--) {
+    const parent = parents[i];
+    const key = pathSegments[i];
+    if (isPlainObject(parent[key]) && Object.keys(parent[key]).length === 0) {
+      delete parent[key];
+    }
+  }
+};
+
+// Inserts `value` at pathSegments (mutates tree), creating intermediate
+// group objects as needed.
+/** @param {Record<string, unknown>} tree @param {string[]} pathSegments @param {unknown} value */
+const setAtPath = (tree, pathSegments, value) => {
+  let node = tree;
+  for (let i = 0; i < pathSegments.length - 1; i++) {
+    const segment = pathSegments[i];
+    if (!isPlainObject(node[segment])) node[segment] = {};
+    node = /** @type {Record<string, unknown>} */ (node[segment]);
+  }
+  node[pathSegments[pathSegments.length - 1]] = value;
+};
+
+// A build can create several StyleDictionary instances over the same source
+// file (e.g. one throwaway pass to enumerate concrete file paths, one for the
+// real build — see build-tokens.mjs), each re-running this parser. Tracked so
+// a missing source key is only ever warned about once per process, instead of
+// once per pass.
+/** @type {Set<string>} */
+const warnedMissingKeys = new Set();
+
+/**
+ * Applies a rename map to a parsed DTCG tree: moves each mapped source path's
+ * node to its destination path. Two phases (collect+delete, then insert) so
+ * that a destination path used by one entry and a source path used by
+ * another never interfere with each other depending on map order. A source
+ * key not found in the tree only produces a console warning — it does not
+ * fail the build, since a project config may target a key that's only
+ * sometimes present.
+ * @param {unknown} tree
+ * @param {Record<string,string>} renameMap  dot-path -> dot-path
+ * @param {string} filePath  only used for the warning message
+ * @returns {unknown}
+ */
+export const applyTokenRenameMap = (tree, renameMap, filePath) => {
+  if (!isPlainObject(tree)) return tree;
+
+  /** @type {{fromPath: string[], toPath: string[], node: unknown}[]} */
+  const moves = [];
+
+  for (const [from, to] of Object.entries(renameMap)) {
+    const fromPath = from.split('.');
+    const node = getAtPath(tree, fromPath);
+    if (node === undefined) {
+      const warnKey = `${filePath}::${from}`;
+      if (!warnedMissingKeys.has(warnKey)) {
+        warnedMissingKeys.add(warnKey);
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[build-tokens] transform: source token "${from}" not found in ${filePath} — skipped`
+        );
+      }
+      continue;
+    }
+    moves.push({ fromPath, toPath: to.split('.'), node });
+  }
+
+  for (const { fromPath } of moves) deleteAtPath(tree, fromPath);
+  for (const { toPath, node } of moves) setAtPath(tree, toPath, node);
+
+  return tree;
+};
+
+/** @param {string} filePath @returns {Promise<unknown>} */
+const loadTree = async (filePath) => {
+  const ext = path.extname(filePath);
+
+  if (ext === '.mjs' || ext === '.js') {
+    const mod = await import(pathToFileURL(filePath).href);
+    try {
+      return structuredClone(mod.default);
+    } catch {
+      // Cloning may fail for content with non-cloneable values (e.g.
+      // functions) — fall back to the live module object, same as Style
+      // Dictionary's own loadFile.js.
+      return mod.default;
+    }
+  }
+
+  const contents = await readFile(filePath, 'utf-8');
+
+  if (ext === '.json') {
+    // Reuses the legacy-or-DTCG bridge so hybrid-node conversion stays
+    // consistent with every other .json source in the project.
+    return parseLegacyFile(contents, filePath);
+  }
+
+  // .jsonc, .json5, or anything else: the same JSON5 parsing Style
+  // Dictionary's own built-in loader uses for these extensions.
+  return JSON5.parse(contents);
+};
+
+// Registers the parser globally on the StyleDictionary class. To actually
+// run it, a Style Dictionary instance must also opt in via
+// `parsers: [..., TOKEN_RENAME_PARSER_NAME]` (see build-tokens.mjs,
+// build-source-modes.mjs, check-unresolved-custom-props.mjs) — same
+// activation model as the legacy bridge parser.
+/** @param {RegExp} pattern  from transformedFilesPattern() in source-transforms.mjs */
+export const registerTokenRenameParser = (pattern) => {
+  StyleDictionary.registerParser({
+    name: TOKEN_RENAME_PARSER_NAME,
+    pattern,
+    parser: async ({ filePath }) => {
+      const tree = await loadTree(filePath ?? '');
+      const renameMap = getSourceTransform(filePath);
+      return renameMap ? applyTokenRenameMap(tree, renameMap, filePath ?? '') : tree;
+    },
+  });
+};
+
+// ── Reference rewriting (preprocessor) ──────────────────────────────────────
+//
+// Matches a bare {reference} (not a CSS function containing one, e.g.
+// "color-mix(in srgb, {primary} 60%, #000)" still matches the {primary} part
+// only) — same pattern style as LEGACY_REF in legacy-tokens-parser.mjs.
+const REF = /\{([^}]+)\}/g;
+
+/**
+ * Replaces every {reference} in `value` (a token's $value, possibly nested —
+ * composite/shadow/gradient objects, arrays) whose dot-path exactly matches a
+ * "from" key of `renames`, with `{<to>}`. References that don't match any
+ * renamed key (including partial/longer paths, e.g. {primary.200} when only
+ * "primary" was renamed) are left untouched.
+ * @param {unknown} value
+ * @param {Map<string,string>} renames
+ * @returns {unknown}
+ */
+const rewriteRefs = (value, renames) => {
+  if (typeof value === 'string') {
+    return value.replace(REF, (match, ref) => (renames.has(ref) ? `{${renames.get(ref)}}` : match));
+  }
+  if (Array.isArray(value)) return value.map((v) => rewriteRefs(v, renames));
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, rewriteRefs(v, renames)]));
+  }
+  return value;
+};
+
+/**
+ * Walks the merged token tree (every source file, already combined by Style
+ * Dictionary — see StyleDictionary.js's `preprocess()` call site) and, for
+ * every leaf token (a node with `$value`), rewrites {references} in its
+ * `$value` only — never touching `$type`, `filePath`, `isSource` or any other
+ * metadata Style Dictionary attaches to the node.
+ * @param {unknown} node
+ * @param {Map<string,string>} renames
+ * @returns {unknown}
+ */
+const rewriteTreeRefs = (node, renames) => {
+  if (!isPlainObject(node)) return node;
+  if (Object.hasOwn(node, '$value')) {
+    return { ...node, $value: rewriteRefs(node.$value, renames) };
+  }
+  return Object.fromEntries(
+    Object.entries(node).map(([key, child]) => [key, rewriteTreeRefs(child, renames)])
+  );
+};
+
+// Registers the preprocessor globally. To actually run it, a Style
+// Dictionary instance must also opt in via
+// `preprocessors: [TOKEN_RENAME_PREPROCESSOR_NAME]` (see build-tokens.mjs,
+// build-source-modes.mjs, check-unresolved-custom-props.mjs). A no-op
+// (returns the tree unchanged) when getAllRenames() is empty — e.g. every
+// registered transform turned out to be file-ambiguous (see
+// registerSourceTransforms() in source-transforms.mjs).
+export const registerTokenRenamePreprocessor = () => {
+  StyleDictionary.registerPreprocessor({
+    name: TOKEN_RENAME_PREPROCESSOR_NAME,
+    preprocessor: (dictionary) => {
+      const renames = getAllRenames();
+      return renames.size ? rewriteTreeRefs(dictionary, renames) : dictionary;
+    },
+  });
+};

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

@@ -15,6 +15,8 @@
 //   build-tokens-src/build-source-modes.mjs  <- alternative build path used when sourceModes is set
 //   build-tokens-src/merge-css.mjs      <- supports the mergeCustomProps option (flat and per-mode)
 //   build-tokens-src/source-prefixes.mjs <- supports `{ src, prefix }` entries in source/sourceModes
+//   build-tokens-src/source-transforms.mjs <- supports `{ src, transform }` entries in source/sourceModes
+//   build-tokens-src/token-rename-parser.mjs <- parser applying the `transform` rename maps
 
 import StyleDictionary from 'style-dictionary';
 import * as path from 'node:path';
@@ -37,6 +39,7 @@ import {
   sourceModes,
   sourceModesBase,
   prefixedSources,
+  transformedSources,
   mergeCustomProps,
   customPropsGroups,
   pxToRem,
@@ -61,6 +64,29 @@ registerLegacyTokensParser();
 import { registerSourcePrefixes } from './build-tokens-src/source-prefixes.mjs';
 await registerSourcePrefixes(prefixedSources);
 
+// ── 2d. Per-source token rename maps ─────────────────────────────────────────
+// Expands the `{ src, transform }` entries of source/sourceModes into the
+// file -> rename-map read by the token-rename parser, and registers that
+// parser (only if at least one file actually has a transform) — see
+// source-transforms.mjs / token-rename-parser.mjs. `parserNames` is reused
+// below and passed down to buildSourceModes() so every Style Dictionary
+// instance opts in consistently.
+import { registerSourceTransforms, transformedFilesPattern, hasRegisteredTransforms } from './build-tokens-src/source-transforms.mjs';
+import {
+  TOKEN_RENAME_PARSER_NAME,
+  registerTokenRenameParser,
+  TOKEN_RENAME_PREPROCESSOR_NAME,
+  registerTokenRenamePreprocessor,
+} from './build-tokens-src/token-rename-parser.mjs';
+await registerSourceTransforms(transformedSources);
+const tokenRenamePattern = transformedFilesPattern();
+if (tokenRenamePattern) registerTokenRenameParser(tokenRenamePattern);
+registerTokenRenamePreprocessor();
+const parserNames = [LEGACY_TOKENS_PARSER_NAME, ...(hasRegisteredTransforms() ? [TOKEN_RENAME_PARSER_NAME] : [])];
+// Rewrites {references} to any renamed token's OLD path, tree-wide, once all
+// files are merged (see registerTokenRenamePreprocessor() above).
+const preprocessorNames = hasRegisteredTransforms() ? [TOKEN_RENAME_PREPROCESSOR_NAME] : [];
+
 // ── 3. CSS format ─────────────────────────────────────────────────────────────
 // customPropsCount is updated by the format at render time
 // loadExistingCustomProps supports the mergeCustomProps option (see below)
@@ -121,6 +147,8 @@ if (sourceModes) {
     mergeCustomProps,
     useLightDarkFunc,
     customPropsSelector,
+    parserNames,
+    preprocessorNames,
   });
 
 } else {
@@ -151,7 +179,8 @@ if (sourceModes) {
   if (jsonBuildPath && !jsonDestFile) {
     const sdInit = new StyleDictionary({
       source: singleSource,
-      parsers: [LEGACY_TOKENS_PARSER_NAME],
+      parsers: parserNames,
+      preprocessors: preprocessorNames,
       log: { verbosity: 'silent' },
       platforms: {},
     });
@@ -160,7 +189,8 @@ if (sourceModes) {
 
   const sd = new StyleDictionary({
     source: singleSource,
-    parsers: [LEGACY_TOKENS_PARSER_NAME],
+    parsers: parserNames,
+    preprocessors: preprocessorNames,
     log: { verbosity: 'verbose' },
     platforms: buildPlatforms({
       buildPath,

package/dev-tools/design-tokens-builder/check-unresolved-custom-props.mjs

@@ -25,10 +25,18 @@ import StyleDictionary from 'style-dictionary';
 import './build-tokens-src/transforms.mjs';
 import { CSS_TRANSFORMS } from './build-tokens-src/platforms.mjs';
 import { splitSourceEntries, registerSourcePrefixes } from './build-tokens-src/source-prefixes.mjs';
+import { registerSourceTransforms, transformedFilesPattern, hasRegisteredTransforms } from './build-tokens-src/source-transforms.mjs';
+import {
+  TOKEN_RENAME_PARSER_NAME,
+  registerTokenRenameParser,
+  TOKEN_RENAME_PREPROCESSOR_NAME,
+  registerTokenRenamePreprocessor,
+} from './build-tokens-src/token-rename-parser.mjs';
 import { findMediaModeBlocks } from './build-tokens-src/merge-css.mjs';
 import { LEGACY_TOKENS_PARSER_NAME, registerLegacyTokensParser } from './build-tokens-src/legacy-tokens-parser.mjs';
 
 registerLegacyTokensParser();
+registerTokenRenamePreprocessor();
 
 // const __filename = fileURLToPath(import.meta.url);
 // const __dirname  = dirname(__filename);
@@ -204,21 +212,29 @@ async function run() {
     // includeEntries: base-mode sources, passed as `include` for non-base
     // modes so cross-mode references resolve (same as build-source-modes.mjs).
     /** @param {Parameters<typeof splitSourceEntries>[0]} sourceEntries @param {Parameters<typeof splitSourceEntries>[0]} [includeEntries] @returns {Promise<Map<string,string>>} */
-    // Entries can be strings or `{ src, prefix }` objects (see
-    // build-tokens-src/source-prefixes.mjs): the prefixes are registered
-    // before the transform pipeline runs, so token names match the CSS.
+    // Entries can be strings or `{ src, prefix, transform }` objects (see
+    // build-tokens-src/source-prefixes.mjs): both are registered before the
+    // transform pipeline runs, so token names match the generated CSS.
     const resolveSourceFileMap = async (sourceEntries, includeEntries = []) => {
       /** @type {Map<string, string>} */
       const map = new Map();
-      const { patterns: resolvedPaths, prefixed } = splitSourceEntries(sourceEntries, configDir);
-      const { patterns: includePaths, prefixed: includePrefixed } = splitSourceEntries(includeEntries, configDir);
+      const { patterns: resolvedPaths, prefixed, transformed } = splitSourceEntries(sourceEntries, configDir);
+      const { patterns: includePaths, prefixed: includePrefixed, transformed: includeTransformed } = splitSourceEntries(includeEntries, configDir);
       if (!resolvedPaths.length) return map;
       try {
         await registerSourcePrefixes([...prefixed, ...includePrefixed]);
+
+        await registerSourceTransforms([...transformed, ...includeTransformed]);
+        const tokenRenamePattern = transformedFilesPattern();
+        if (tokenRenamePattern) registerTokenRenameParser(tokenRenamePattern);
+        const parserNames = [LEGACY_TOKENS_PARSER_NAME, ...(hasRegisteredTransforms() ? [TOKEN_RENAME_PARSER_NAME] : [])];
+        const preprocessorNames = hasRegisteredTransforms() ? [TOKEN_RENAME_PREPROCESSOR_NAME] : [];
+
         const sd = new StyleDictionary({
           include: includePaths,
           source: resolvedPaths,
-          parsers: [LEGACY_TOKENS_PARSER_NAME],
+          parsers: parserNames,
+          preprocessors: preprocessorNames,
           log: { verbosity: 'silent' },
           platforms: { css: { transforms: CSS_TRANSFORMS } },
         });

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

@@ -54,14 +54,56 @@ const config = {
   //   OK:  `${minimo_path}/**/*.{json,mjs}`
   //   NO:  path.join(minimo_path, '/**/*.{json,mjs}')
   //
-  // An entry can also be an object `{ src, prefix }` (src: string or array of
-  // strings/globs), to render the custom properties of those files with a
-  // prefix: e.g. { src: '...open-props...json', prefix: 'op' } turns Open
-  // Props' gray.0 into --op-gray-0. Only the property name changes:
-  // {references} to those tokens are rendered as var(--op-gray-0), and the JSON
-  // output stays unprefixed. 'op', 'op-' and '--op-' are equivalent. The same
-  // syntax works inside sourceModes. Two different prefixes for the same file
-  // make the build fail.
+  // An entry can also be an object `{ src, prefix, transform }` (src: string
+  // or array of strings/globs).
+  //
+  // `prefix`: renders the custom properties of those files with a prefix,
+  // e.g. { src: '...open-props...json', prefix: 'op' } turns Open Props'
+  // gray.0 into --op-gray-0. Only the property name changes: {references} to
+  // those tokens are rendered as var(--op-gray-0), and the JSON output stays
+  // unprefixed. 'op', 'op-' and '--op-' are equivalent. Two different
+  // prefixes for the same file make the build fail.
+  //
+  // `transform`: moves/renames token nodes within those files' own tree —
+  // e.g. { primary: 'primary.100' } takes whatever is defined at dot-path
+  // `primary` and moves it to `primary.100`, BEFORE Style Dictionary resolves
+  // {references} or builds the CSS/JSON output (unlike `prefix`, which is a
+  // purely cosmetic CSS name change applied after the fact — see
+  // build-tokens-src/source-transforms.mjs). Typical use case: a preexisting
+  // project (e.g. driven by Figma/Penpot) names its own base color `primary`,
+  // while minimo's own tokens reference `{primary.100}` — instead of
+  // renaming the property by hand after every build, or hunting down every
+  // minimo reference to change it, `transform` fixes the token's own path
+  // once, here.
+  //   - Both sides of the map use Style Dictionary's own DOT-PATH notation
+  //     ('primary.100'), NOT the hyphen-joined custom-property notation
+  //     ('primary-100'): token name segments in this project can themselves
+  //     contain hyphens (e.g. btn-close), so a hyphen can't reliably tell a
+  //     path separator from a literal part of a segment name — a dot can,
+  //     since it's already reserved by Style Dictionary as the {reference}
+  //     path separator.
+  //   - {References} to the OLD path — in the same file or a completely
+  //     different one — are rewritten automatically, tree-wide, to the NEW
+  //     path once all sources are merged: e.g. every {primary} in the whole
+  //     build becomes {primary.100}, whether minimo's own tokens already
+  //     wrote {primary.100} directly (no-op) or something else in the
+  //     project still says {primary}.
+  //   - WARNING: this rewrite is by design file-independent (a bare
+  //     {reference} doesn't know which file it "belongs" to) — so if the
+  //     SAME source key (e.g. "primary") is given a DIFFERENT destination in
+  //     two different files' `transform` maps, each rename itself still
+  //     works fine, but {primary} becomes ambiguous: which destination should
+  //     it be rewritten to? In that case the automatic rewrite is skipped
+  //     for that key (a warning is logged), and every {primary} reference
+  //     must be fixed by hand to point at the right one of the two new
+  //     paths.
+  //   - A source key not found in the file only logs a warning, it does not
+  //     fail the build.
+  //   - Applies to both the CSS and the JSON output (see JSON TOKENS OUTPUT
+  //     below), since both are rebuilt from the token's path, by then already
+  //     renamed.
+  //
+  // Both options work the same way inside sourceModes.
   source: [
     `${minimo_path}/design-tokens/_src/**/*.tokens.{mjs,jsonc}`, // main tokens
     `${minimo_path}/src/**/*.tokens.{mjs,jsonc}`, // components tokens
@@ -69,8 +111,13 @@ const config = {
     // optional extra token source (in this example, openProps, https://open-props.style/)
     // { src: `${node_modules_path}/open-props/open-props.style-dictionary-tokens.json`, prefix: 'op' },
 
-    // your project tokens
-    {src: './project-tokens/*.{js,mjs,jsonc,json}', prefix: 'my-project'}
+    // your project tokens — e.g. remaps a Figma/Penpot-exported `primary`
+    // color to minimo's own `primary.100` naming
+    {
+      src: './project-tokens/*.{js,mjs,jsonc,json}',
+      prefix: 'my-project',
+      transform: { primary: 'primary.100' },
+    }
   ],
 
   // Optional light/dark (or other) custom properties split — alternative to

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

@@ -59,6 +59,15 @@ export function cssRules({
       sideEffects: true,
       oneOf: [
 
+        {
+          // `import url from './file.css?as_url'`: the file is emitted as is and its URL is returned
+          resourceQuery: /as_url/,
+          type: 'asset/resource',
+          generator: {
+            filename: 'css/[name].[contenthash][ext]'
+          }
+        },
+
         // raw content per web-components
         {
           resourceQuery: /raw/,

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

@@ -8,7 +8,7 @@ Le versioni precedenti sono conservate in `archived/webpack-config-v2/` del repo
 
 ---
 
-## Fix da verificare sempre
+## Fix e upg da verificare e applicare a tutte le versioni
 * WebpackManifestPlugin: impostare `removeKeyHash: /\?.*$/, // /([a-f0-9]{32}\.?)/gi, // /(\?as_asset)$/,`, sostituendo eventuali impostazione `removeKeyHash: true` se presente
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.38.5",
+  "version": "1.39.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",
@@ -103,6 +103,7 @@
     "@stylistic/stylelint-config": "^5.0.0",
     "@stylistic/stylelint-plugin": "^5.3.0",
     "clipboardy": "^5.3.2",
+    "json5": "^2.2.3",
     "sharp": "^0.35.3",
     "sharp-ico": "^0.1.5",
     "stylelint": "^17.15.0",