@massimo-cassandro/minimo 1.36.2 → 1.38.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/build-source-modes.mjs

@@ -4,18 +4,25 @@
 // light/dark custom-properties split.
 //
 // For each mode, a separate StyleDictionary instance is built from that
-// mode's own `source` array. The generated `:root { ... }` CSS blocks are
-// then composed into a single destFile:
-//   - the base mode's block stays as a plain `:root { ... }` rule, with a
-//     `color-scheme: <all modes joined>;` declaration prepended
-//     (e.g. "light dark")
+// mode's own `source` array. The generated `<selector> { ... }` CSS blocks
+// (selector: customPropsSelector, default ':root' — see config.mjs) are then
+// composed into a single destFile:
+//   - the base mode's block stays as a plain `<selector> { ... }` rule, with
+//     a `color-scheme: <all modes joined>;` declaration prepended (e.g.
+//     "light dark")
 //   - every other mode's block is wrapped in
-//     `@media (prefers-color-scheme: <mode>) { :root { ... } }`, with a
+//     `@media (prefers-color-scheme: <mode>) { <selector> { ... } }`, with a
 //     `color-scheme: <mode>;` declaration prepended
 // customPropsGroups, mergeCustomProps and pxToRem apply per mode, exactly as
 // in the single-source build. addLayer (if set) wraps the whole composed
 // result in a single `@layer`, rather than one per mode.
 //
+// When sourceModes defines both a `light` and a `dark` key and
+// useLightDarkFunc is true (default), custom properties shared by both are
+// reconciled into a single `light-dark()` declaration instead of being split
+// across the base block and a `@media (prefers-color-scheme: dark)` rule —
+// see light-dark.mjs.
+//
 // JSON tokens (if jsonBuildPath is set) are produced per mode: one set of
 // files per mode, with `-<mode>` appended to each filename (see
 // buildJsonFiles() in formats/json.mjs), e.g. "tokens-light.jsonc" /
@@ -26,15 +33,16 @@ import StyleDictionary from 'style-dictionary';
 import * as path from 'node:path';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { CSS_TRANSFORMS, JSON_TRANSFORMS } from './platforms.mjs';
-import { customPropsCount } from './formats/css.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';
 
 /**
  * @param {object}                 opts
  * @param {Record<string,string[]>} opts.sourceModes    Resolved source paths per mode (see config.mjs)
- * @param {string}                 opts.baseMode        Mode whose block stays a top-level `:root { ... }` rule
+ * @param {string}                 opts.baseMode        Mode whose block stays a top-level `<selector> { ... }` rule
  * @param {string}                 opts.buildPath        Absolute path for CSS output directory
  * @param {string}                 opts.destFile         CSS output filename
  * @param {string|null}            opts.jsonBuildPath    Absolute path for JSON output (null = disabled)
@@ -45,6 +53,8 @@ import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
  * @param {boolean}                opts.pxToRem
  * @param {string|null}            opts.addLayer
  * @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)
  * @returns {Promise<{cssDestPath: string, totalCustomProps: number, jsonFilesByMode: Record<string, object[]>}>}
  */
 export const buildSourceModes = async ({
@@ -60,13 +70,15 @@ export const buildSourceModes = async ({
   pxToRem,
   addLayer,
   mergeCustomProps,
+  useLightDarkFunc,
+  customPropsSelector,
 }) => {
   const modeNames = Object.keys(sourceModes);
 
   // 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, mergeCustomProps);
+    loadExistingCustomPropsScoped(path.join(buildPath, destFile), baseMode, mergeCustomProps, customPropsSelector);
   }
 
   const cssTransforms = pxToRem
@@ -75,13 +87,22 @@ export const buildSourceModes = async ({
 
   /** @type {Record<string,string>} */
   const modeBlocks = {};
-  let totalCustomProps = 0;
+  // Per-mode custom-prop count and structured (name -> tail) props map,
+  // captured right after each per-mode format call (customPropsCount and
+  // lastFinalProps are live bindings, updated synchronously by the format
+  // function — see formats/css.mjs). Kept per mode (rather than summed on
+  // the fly) so applyLightDarkFunc() can later overwrite just the entries it
+  // actually touches (light, dark, and the base mode).
+  /** @type {Record<string,number>} */
+  const modeCounts = {};
+  /** @type {Record<string, Record<string,string>>} */
+  const modeFinalProps = {};
   /** @type {Record<string, object[]>} */
   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
+    // the base block is the unconditional top-level `<selector>`). 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
@@ -102,6 +123,7 @@ export const buildSourceModes = async ({
               format: 'css/variables-sorted',
               options: {
                 outputReferences: true,
+                selector: customPropsSelector,
                 customPropsGroups,
                 mode,
                 colorScheme: mode === baseMode ? modeNames.join(' ') : mode,
@@ -116,9 +138,10 @@ export const buildSourceModes = async ({
     // the composed multi-mode file is written once, at the end, below.
     const [formatted] = await sd.formatPlatform('css');
     modeBlocks[mode] = /** @type {string} */ (formatted.output);
-    // customPropsCount is a live binding, updated synchronously by the
-    // format function called above (see formats/css.mjs).
-    totalCustomProps += customPropsCount;
+    // customPropsCount / lastFinalProps are live bindings, updated
+    // synchronously by the format function called above (see formats/css.mjs).
+    modeCounts[mode] = customPropsCount;
+    modeFinalProps[mode] = lastFinalProps;
 
     if (jsonBuildPath) {
       const concreteFilePaths = jsonDestFile ? [] : await collectConcreteFilePaths(sd);
@@ -142,6 +165,26 @@ export const buildSourceModes = async ({
     }
   }
 
+  // ── light-dark() reconciliation (light/dark modes only) ──────────────────
+  // Rebuilds just the `light`, `dark` and base-mode blocks from the adjusted
+  // props maps — see light-dark.mjs. No-op (returns null) unless sourceModes
+  // defines both a `light` and a `dark` key.
+  if (useLightDarkFunc) {
+    const reconciled = applyLightDarkFunc({
+      modeFinalProps,
+      modeNames,
+      baseMode,
+      selector: customPropsSelector,
+      customPropsGroups,
+    });
+    if (reconciled) {
+      Object.assign(modeBlocks, reconciled.blocks);
+      Object.assign(modeCounts, reconciled.counts);
+    }
+  }
+
+  const totalCustomProps = Object.values(modeCounts).reduce((sum, n) => sum + n, 0);
+
   // ── Compose the final CSS ────────────────────────────────────────────────
   const otherModes = modeNames.filter((mode) => mode !== baseMode);
 

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
@@ -103,6 +103,26 @@ export const mergeCustomProps = (() => {
 // Set to null, undefined or false (default) to emit no layer.
 export const addLayer = buildConfig.addLayer ? String(buildConfig.addLayer).trim() : null;
 
+// customPropsSelector: CSS selector wrapping the generated custom properties
+// block(s) (see formats/css.mjs buildCssBlock()), instead of the default
+// `:root`. Applies uniformly to a single-source build and to a sourceModes
+// build (the base mode's top-level block and every other mode's block
+// nested under its own `@media (prefers-color-scheme: <mode>)` rule all use
+// the same selector). Falsy or blank values fall back to ':root'.
+export const customPropsSelector = typeof buildConfig.customPropsSelector === 'string'
+  && buildConfig.customPropsSelector.trim()
+  ? buildConfig.customPropsSelector.trim()
+  : ':root';
+
+// useLightDarkFunc: with sourceModes set (see below) and defining both a
+// `light` and a `dark` key, custom properties present in both are written
+// once as `--name: light-dark(<light>, <dark>);` instead of being split
+// across the base mode's block and a
+// `@media (prefers-color-scheme: dark) { ... }` rule (see light-dark.mjs).
+// Ignored when sourceModes is not set, or does not define both a light and a
+// dark mode. Default: true.
+export const useLightDarkFunc = buildConfig.useLightDarkFunc !== false;
+
 // customPropsGroups: custom properties whose first hyphen-separated name
 // segment matches one of a group's prefixes are pulled out, labelled with
 // that group's name and moved to the beginning of the generated CSS file, in
@@ -126,14 +146,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 +195,4 @@ if (sourceModes && buildConfig.sourceModesBase && sourceModesBase !== buildConfi
   );
 }
 
-export const source = sourceModes ? null : resolveSourcePaths(buildConfig.source, configDir);
+export const source = sourceModes ? null : parseSourceEntries(buildConfig.source);