@massimo-cassandro/minimo 1.36.2 → 1.37.0

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

@@ -61,6 +61,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))
 
 **Supported formats:**
 - `.json` / `.jsonc` — parsed directly as token data
@@ -70,6 +71,27 @@ The `source` array accepts any combination of:
 
 Known limitation: a legacy node that is at the same time a token (own `value`/`type`) *and* a group with further nested children (e.g. Open Props' `other.ease.out`, which has its own value plus `out.1` ... `out.5`) can't be represented in DTCG v5 — a node with `$value` is always a leaf, Style Dictionary doesn't descend into its children. Only the node's own value is converted; the nested children are silently lost.
 
+#### Source prefixes
+
+An entry of `source` (or of a `sourceModes` mode) can be an object `{ src, prefix }` instead of a string: every custom property generated from the files matched by `src` (a path, a glob or an array of them) is rendered with the given prefix. Useful to avoid name collisions with third-party token sets, or to make their origin explicit:
+
+```js
+source: [
+  './my-tokens/*.mjs',
+  { src: `${node_modules_path}/open-props/open-props.style-dictionary-tokens.json`, prefix: 'op' },
+],
+```
+
+With this config Open Props' `gray.0` becomes `--op-gray-0`. `prefix` accepts `'op'`, `'op-'` or `'--op-'` (all equivalent).
+
+- Only the custom property **name** changes, not the token path: `{references}` keep working, and a token of another source referencing `{gray.0}` is rendered as `var(--op-gray-0)`.
+- The JSON output (`jsonBuildPath`) is **not** prefixed: it keeps the original token tree.
+- `customPropsGroups` match the prefixed name, so a group can use `prefixes: ['op']`.
+- Giving two different prefixes to the same file fails the build with an error.
+- `check-unresolved-custom-props.mjs` understands the same syntax. Note that `extraCustomPropsFiles` entries are plain CSS files and are never prefixed.
+
+See `build-tokens-src/source-prefixes.mjs`.
+
 
 #### Token file format (JS example)
 

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

@@ -10,7 +10,7 @@
 
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { resolveSourcePaths } from './resolve-source-paths.mjs';
+import { splitSourceEntries } from './source-prefixes.mjs';
 
 // ---------------------------------------------------------------------------
 // Read the --config flag
@@ -126,14 +126,33 @@ export const customPropsGroups = Array.isArray(buildConfig.customPropsGroups)
 // properties split — see build-tokens-src/build-source-modes.mjs. When set
 // (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.
 // ---------------------------------------------------------------------------
 const sourceModesRaw = buildConfig.sourceModes ?? null;
 
+/** @type {import('./source-prefixes.mjs').PrefixedSource[]} */
+export const prefixedSources = [];
+
+/**
+ * @param {Parameters<typeof splitSourceEntries>[0]} entries
+ * @returns {string[]}
+ */
+const parseSourceEntries = (entries) => {
+  const { patterns, prefixed } = splitSourceEntries(entries, configDir);
+  prefixedSources.push(...prefixed);
+  return patterns;
+};
+
 export const sourceModes = sourceModesRaw
   ? Object.fromEntries(
     Object.entries(sourceModesRaw).map(([mode, modeSource]) => [
       mode,
-      resolveSourcePaths(modeSource, configDir),
+      parseSourceEntries(modeSource),
     ])
   )
   : null;
@@ -156,4 +175,4 @@ if (sourceModes && buildConfig.sourceModesBase && sourceModesBase !== buildConfi
   );
 }
 
-export const source = sourceModes ? null : resolveSourcePaths(buildConfig.source, configDir);
+export const source = sourceModes ? null : parseSourceEntries(buildConfig.source);

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

@@ -11,9 +11,10 @@ import { buildJsonFiles } from './formats/json.mjs';
 // Transforms applied to the CSS platform.
 // Exported so other scripts (e.g. check-unresolved-custom-props.mjs) can
 // build a Style Dictionary instance with matching transformed token names.
+// name/kebab-prefixed = name/kebab + per-source prefix (see source-prefixes.mjs).
 export const CSS_TRANSFORMS = [
   'attribute/cti',
-  'name/kebab',
+  'name/kebab-prefixed',
   'time/seconds',
   'asset/url',
   'size/pxToRem-smart',
@@ -27,7 +28,8 @@ export const CSS_TRANSFORMS = [
 // Transforms applied to the JSON platform.
 // Kept minimal on purpose: consuming tools expect original values (e.g. "16px"
 // not "1rem") and alias references ({...}) must be preserved to maintain
-// token links.
+// token links. Source prefixes are not applied here (plain name/kebab): the
+// JSON output keeps the original token tree.
 // Exported so build-source-modes.mjs can build a matching json platform per
 // sourceModes mode.
 export const JSON_TRANSFORMS = [

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

@@ -0,0 +1,129 @@
+// build-tokens-src/source-prefixes.mjs
+// Supports per-source custom property prefixes: an entry of `source` (or of a
+// `sourceModes` mode) can be an object `{ src, prefix }` instead of a plain
+// string, e.g.
+//
+//   { src: 'node_modules/open-props/open-props.style-dictionary-tokens.json', prefix: 'op' }
+//
+// so that every token defined by those files is rendered as `--op-<name>`.
+//
+// How it works: the prefix is applied to the token NAME only (see the
+// name/kebab-prefixed transform in transforms.mjs), never to its path.
+// {references} are resolved through the token path and rendered with the
+// already-prefixed name, so a token of another source referencing e.g.
+// {gray.5} becomes `var(--op-gray-5)` with no change to the token files. The
+// JSON output keeps the original (unprefixed) tree structure.
+//
+// The name transform only knows the concrete file a token comes from
+// (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.
+
+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';
+
+/**
+ * @typedef {object} PrefixedSource
+ * @property {string[]} src     Source paths/globs, already resolved (see resolveSourcePaths)
+ * @property {string}   prefix  Normalised prefix, without leading `--` or trailing `-`
+ */
+
+/** @type {Map<string, string>} */
+let prefixByFile = new Map();
+
+/**
+ * Normalises a user-provided prefix: 'op', 'op-' and '--op-' all become 'op'.
+ * @param {unknown} prefix
+ * @returns {string}
+ * @throws {Error} if the result is not a valid custom property name segment
+ */
+export const normalizePrefix = (prefix) => {
+  const value = String(prefix).trim().replace(/^-+/, '').replace(/-+$/, '');
+  if (!/^[a-z_][\w-]*$/i.test(value)) {
+    throw new Error(`[build-tokens] config: invalid source prefix "${prefix}"`);
+  }
+  return value;
+};
+
+/**
+ * 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
+ * @param {string} baseDir
+ * @returns {{patterns: string[], prefixed: PrefixedSource[]}}
+ */
+export const splitSourceEntries = (entries, baseDir) => {
+  /** @type {string[]} */
+  const patterns = [];
+  /** @type {PrefixedSource[]} */
+  const prefixed = [];
+
+  for (const entry of entries ?? []) {
+    if (typeof entry === 'string') {
+      patterns.push(...resolveSourcePaths([entry], baseDir));
+      continue;
+    }
+
+    const isObjectEntry = entry !== null && typeof entry === 'object'
+      && (typeof entry.src === 'string' || Array.isArray(entry.src));
+    if (!isObjectEntry) {
+      throw new Error(
+        `[build-tokens] config: invalid source entry ${JSON.stringify(entry)} `
+        + '(expected a string or an object { src, prefix })'
+      );
+    }
+
+    const src = resolveSourcePaths([].concat(entry.src), baseDir);
+    patterns.push(...src);
+
+    if (entry.prefix !== undefined && entry.prefix !== null && entry.prefix !== '') {
+      prefixed.push({ src, prefix: normalizePrefix(entry.prefix) });
+    }
+  }
+
+  return { patterns, prefixed };
+};
+
+/**
+ * Expands the `src` patterns of every prefixed entry into concrete file paths
+ * and stores the file path -> prefix map used by getSourcePrefix().
+ * Must be called after registerLegacyTokensParser() and before any build.
+ * @param {PrefixedSource[]} prefixedSources
+ * @returns {Promise<void>}
+ * @throws {Error} if the same file is given two different prefixes
+ */
+export const registerSourcePrefixes = async (prefixedSources) => {
+  /** @type {Map<string, string>} */
+  const map = new Map();
+
+  for (const { src, prefix } of prefixedSources) {
+    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);
+      if (existing !== undefined && existing !== prefix) {
+        throw new Error(
+          `[build-tokens] config: "${filePath}" has two different prefixes ("${existing}" and "${prefix}")`
+        );
+      }
+      map.set(filePath, prefix);
+    }
+  }
+
+  prefixByFile = map;
+};
+
+/**
+ * @param {string|undefined} filePath  token.filePath
+ * @returns {string|undefined} the prefix registered for that file, if any
+ */
+export const getSourcePrefix = (filePath) => (filePath ? prefixByFile.get(filePath) : undefined);

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

@@ -3,6 +3,7 @@
 // Imported once by build-tokens.mjs before buildAllPlatforms() is called.
 
 import StyleDictionary from 'style-dictionary';
+import { getSourcePrefix } from './source-prefixes.mjs';
 
 const BASE_FONT_SIZE = 16;
 
@@ -212,3 +213,22 @@ StyleDictionary.registerTransform({
   filter: (token) => token.$type === 'typography' || token.type === 'typography',
   transform: (token) => token.$value ?? token.value,
 });
+
+// ---------------------------------------------------------------------------
+// 7. Kebab-case name with per-source prefix
+// Same as the built-in name/kebab, but prepends the prefix registered for the
+// token's source file (`{ src, prefix }` entries of `source`/`sourceModes`, see
+// source-prefixes.mjs), e.g. Open Props' gray.0 with prefix 'op' -> op-gray-0.
+// Only the name changes: the token path is untouched, so {references} keep
+// resolving and are rendered as var(--<prefixed-name>). Files without a
+// prefix get exactly the built-in name/kebab result.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'name/kebab-prefixed',
+  type: 'name',
+  transform: (token, options) => {
+    const kebab = StyleDictionary.hooks.transforms['name/kebab'].transform;
+    const prefix = getSourcePrefix(token.filePath);
+    return kebab(prefix ? { ...token, path: [prefix, ...token.path] } : token, options);
+  },
+});

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

@@ -14,6 +14,7 @@
 //   build-tokens-src/platforms.mjs      <- builds the platforms object (css + optional json)
 //   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
 
 import StyleDictionary from 'style-dictionary';
 import * as path from 'node:path';
@@ -35,6 +36,7 @@ import {
   source,
   sourceModes,
   sourceModesBase,
+  prefixedSources,
   mergeCustomProps,
   customPropsGroups,
   pxToRem,
@@ -50,6 +52,13 @@ import './build-tokens-src/transforms.mjs';
 import { LEGACY_TOKENS_PARSER_NAME, registerLegacyTokensParser } from './build-tokens-src/legacy-tokens-parser.mjs';
 registerLegacyTokensParser();
 
+// ── 2c. Per-source custom property prefixes ──────────────────────────────────
+// Expands the `{ src, prefix }` entries of source/sourceModes into the file ->
+// prefix map read by the name/kebab-prefixed transform (needs the legacy
+// parser above, to load legacy .json sources) — see source-prefixes.mjs.
+import { registerSourcePrefixes } from './build-tokens-src/source-prefixes.mjs';
+await registerSourcePrefixes(prefixedSources);
+
 // ── 3. CSS format ─────────────────────────────────────────────────────────────
 // customPropsCount is updated by the format at render time
 // loadExistingCustomProps supports the mergeCustomProps option (see below)

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

@@ -24,7 +24,7 @@ import { styleText } from 'node:util';
 import StyleDictionary from 'style-dictionary';
 import './build-tokens-src/transforms.mjs';
 import { CSS_TRANSFORMS } from './build-tokens-src/platforms.mjs';
-import { resolveSourcePaths } from './build-tokens-src/resolve-source-paths.mjs';
+import { splitSourceEntries, registerSourcePrefixes } from './build-tokens-src/source-prefixes.mjs';
 import { findMediaModeBlocks } from './build-tokens-src/merge-css.mjs';
 import { LEGACY_TOKENS_PARSER_NAME, registerLegacyTokensParser } from './build-tokens-src/legacy-tokens-parser.mjs';
 
@@ -202,17 +202,22 @@ async function run() {
     /** @type {Map<string, Map<string, string>>} */
     const sourceFileByPropByMode = new Map();
 
-    // includePatterns: base-mode sources, passed as `include` for non-base
+    // includeEntries: 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 = []) => {
+    /** @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.
+    const resolveSourceFileMap = async (sourceEntries, includeEntries = []) => {
       /** @type {Map<string, string>} */
       const map = new Map();
-      const resolvedPaths = resolveSourcePaths(sourcePatterns, configDir);
+      const { patterns: resolvedPaths, prefixed } = splitSourceEntries(sourceEntries, configDir);
+      const { patterns: includePaths, prefixed: includePrefixed } = splitSourceEntries(includeEntries, configDir);
       if (!resolvedPaths.length) return map;
       try {
+        await registerSourcePrefixes([...prefixed, ...includePrefixed]);
         const sd = new StyleDictionary({
-          include: resolveSourcePaths(includePatterns, configDir),
+          include: includePaths,
           source: resolvedPaths,
           parsers: [LEGACY_TOKENS_PARSER_NAME],
           log: { verbosity: 'silent' },
@@ -230,8 +235,8 @@ async function run() {
 
     if (checkUnused && config.sourceModes) {
       for (const [mode, modeSource] of Object.entries(config.sourceModes)) {
-        const includePatterns = mode === sourceModesBase ? [] : config.sourceModes[sourceModesBase];
-        sourceFileByPropByMode.set(mode, await resolveSourceFileMap(modeSource, includePatterns));
+        const includeEntries = mode === sourceModesBase ? [] : config.sourceModes[sourceModesBase];
+        sourceFileByPropByMode.set(mode, await resolveSourceFileMap(modeSource, includeEntries));
       }
     } 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

@@ -51,12 +51,21 @@ const config = {
   // the pattern syntax. Use template literals instead:
   //   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.
   source: [
     `${minimo_path}/design-tokens/_src/**/*.tokens.{mjs,jsonc}`, // main tokens
     `${minimo_path}/src/**/*.tokens.{mjs,jsonc}`, // components tokens
 
     // optional extra token source (in this example, openProps, https://open-props.style/)
-    // `${node_modules_path}/open-props/open-props.style-dictionary-tokens.json`,
+    // { src: `${node_modules_path}/open-props/open-props.style-dictionary-tokens.json`, prefix: 'op' },
 
     // your project tokens
     './project-tokens/*.{js,mjs,jsonc,json}',

package/package.json

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