@massimo-cassandro/minimo 1.38.3 → 1.38.5

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

@@ -69,7 +69,7 @@ The `source` array accepts any combination of:
 
 **Legacy token syntax (auto-detected, `.json` only):** `.json` source files written in the older, non-DTCG Style Dictionary syntax (`value`/`type` instead of `$value`/`$type`, references as `{group.token.value}` instead of `{group.token}` — e.g. a file exported from [Open Props](https://open-props.style/)) are converted to DTCG v5 syntax automatically at parse time, node by node. Files already using `$value`/`$type` are left untouched, so no config flag or file list is needed — mixing legacy and DTCG sources in the same `source` array just works. `.jsonc` is not covered (reserved for hand-authored DTCG sources, parsed by Style Dictionary's own loader) and these `.json` files are parsed with plain `JSON.parse` (no comments, no trailing commas). See `build-tokens-src/legacy-tokens-parser.mjs`.
 
-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.
+A legacy node that is at the same time a token (own `value`/`type`) *and* a group with 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, where a node with `$value` is always a leaf. Its own value is moved to a child token named `default` (`other.ease.out.default`, i.e. `--other-ease-out-default`), or `base` if a `default` child already exists; if both exist the build fails with an explicit error. References to such a node from the same file are rewritten accordingly; from other files they must use the child name explicitly.
 
 #### Source prefixes
 

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

@@ -25,6 +25,12 @@
 // the parser is a safe no-op for files that don't need conversion — no
 // config flag or file list is required, detection is fully automatic.
 //
+// "Hybrid" nodes (a token with its own value that is also a group with
+// nested children, e.g. Open Props' other.ease.out) can't be represented in
+// DTCG v5, where a node with $value is a leaf. The own value is moved to a
+// child token named `default` (or `base` if `default` is already a child
+// name; the build fails if both are taken) — see collectHybridNodes().
+//
 // Limitation: `.json` files handled by this parser are parsed with plain
 // JSON.parse (no comments, no trailing commas), unlike Style Dictionary's
 // own built-in loader (which uses JSON5 for .json/.jsonc/.json5). This keeps
@@ -39,58 +45,127 @@ export const LEGACY_TOKENS_PARSER_NAME = 'minimo/legacy-tokens';
 // Matches "{some.token.path.value}" -> captures "some.token.path"
 const LEGACY_REF = /\{([^}]+)\.value\}/g;
 
-/** @param {unknown} value @returns {unknown} */
-const convertLegacyRefs = (value) => {
+// Name of the child token that receives the own value of a "hybrid" node
+// (see collectHybridNodes()); FALLBACK_LEAF is used when a child with the
+// preferred name already exists.
+const PREFERRED_LEAF = 'default';
+const FALLBACK_LEAF = 'base';
+
+/** @param {unknown} node @returns {node is Record<string, unknown>} */
+const isPlainObject = (node) => node !== null && typeof node === 'object' && !Array.isArray(node);
+
+// True if the node is (or contains, at any depth) a token, legacy or DTCG.
+/** @param {unknown} node @returns {boolean} */
+const hasTokenDescendant = (node) => isPlainObject(node)
+  && (Object.hasOwn(node, 'value') || Object.hasOwn(node, '$value')
+    || Object.values(node).some(hasTokenDescendant));
+
+/*
+ * A "hybrid" legacy node is a token (own `value`) that is also a group, i.e.
+ * has children that are tokens or groups of tokens (e.g. Open Props'
+ * other.ease.out, with its own value plus out.1 ... out.5). The own value is
+ * moved to a child token: `default`, or `base` if `default` is already a
+ * child name. If both are taken the build fails. Returns a map
+ * dot.path -> chosen child name, used to convert the node itself and to
+ * rewrite references pointing to it (references are only rewritten within
+ * the same file: a reference from another file to a hybrid node must use the
+ * child name explicitly).
+ */
+/**
+ * @param {unknown} node
+ * @param {string[]} path
+ * @param {string} filePath
+ * @param {Map<string,string>} [hybrids]
+ * @returns {Map<string,string>}
+ */
+const collectHybridNodes = (node, path, filePath, hybrids = new Map()) => {
+  if (!isPlainObject(node) || Object.hasOwn(node, '$value')) return hybrids;
+
+  if (Object.hasOwn(node, 'value')
+    && Object.entries(node).some(([key, child]) => key !== 'value' && hasTokenDescendant(child))) {
+    const leaf = [PREFERRED_LEAF, FALLBACK_LEAF].find((name) => !Object.hasOwn(node, name));
+    if (!leaf) {
+      throw new Error(
+        `[build-tokens] legacy tokens: node "${path.join('.')}" in ${filePath} has its own value and children, `
+        + `but both "${PREFERRED_LEAF}" and "${FALLBACK_LEAF}" child names are already taken`
+      );
+    }
+    hybrids.set(path.join('.'), leaf);
+  }
+
+  for (const [key, child] of Object.entries(node)) {
+    collectHybridNodes(child, [...path, key], filePath, hybrids);
+  }
+  return hybrids;
+};
+
+/**
+ * @param {unknown} value
+ * @param {Map<string,string>} hybrids
+ * @returns {unknown}
+ */
+const convertLegacyRefs = (value, hybrids) => {
   if (typeof value === 'string') {
-    return value.replace(LEGACY_REF, '{$1}');
+    return value.replace(LEGACY_REF, (_, ref) => (
+      hybrids.has(ref) ? `{${ref}.${hybrids.get(ref)}}` : `{${ref}}`
+    ));
   }
   if (Array.isArray(value)) {
-    return value.map(convertLegacyRefs);
+    return value.map((v) => convertLegacyRefs(v, hybrids));
   }
   if (value !== null && typeof value === 'object') {
     return Object.fromEntries(
-      Object.entries(value).map(([key, v]) => [key, convertLegacyRefs(v)])
+      Object.entries(value).map(([key, v]) => [key, convertLegacyRefs(v, hybrids)])
     );
   }
   return value;
 };
 
-/** @param {unknown} node @returns {node is Record<string, unknown>} */
-const isPlainObject = (node) => node !== null && typeof node === 'object' && !Array.isArray(node);
-
-/** @param {unknown} node @returns {unknown} */
-const convertLegacyNode = (node) => {
+/**
+ * @param {unknown} node
+ * @param {string[]} path
+ * @param {Map<string,string>} hybrids
+ * @returns {unknown}
+ */
+const convertLegacyNode = (node, path, hybrids) => {
   if (!isPlainObject(node)) return node;
 
   // Already DTCG v5 syntax: leave untouched.
   if (Object.hasOwn(node, '$value')) return node;
 
   if (Object.hasOwn(node, 'value')) {
-    // Legacy token leaf. Some legacy files (e.g. Open Props) also attach
-    // sibling numbered/named children to a node that carries its own
-    // `value`/`type` (a group that is also a default token) — those
-    // children are converted too, even though Style Dictionary itself
-    // cannot represent "group + own $value" ambiguity natively.
     const { value, type, comment, description, ...rest } = node;
-    const convertedRest = Object.fromEntries(
-      Object.entries(rest).map(([key, child]) => [key, convertLegacyNode(child)])
-    );
     const desc = comment ?? description;
-
-    return {
-      ...convertedRest,
-      $value: convertLegacyRefs(value),
+    const token = {
+      $value: convertLegacyRefs(value, hybrids),
       ...(type !== undefined ? { $type: type } : {}),
       ...(desc !== undefined ? { $description: desc } : {}),
     };
+
+    const hybridLeaf = hybrids.get(path.join('.'));
+    if (hybridLeaf === undefined) return token;
+
+    // Hybrid node: becomes a group, its own value moves to a child token.
+    return {
+      ...Object.fromEntries(
+        Object.entries(rest).map(([key, child]) => [key, convertLegacyNode(child, [...path, key], hybrids)])
+      ),
+      [hybridLeaf]: token,
+    };
   }
 
   // Group node: recurse into children.
   return Object.fromEntries(
-    Object.entries(node).map(([key, child]) => [key, convertLegacyNode(child)])
+    Object.entries(node).map(([key, child]) => [key, convertLegacyNode(child, [...path, key], hybrids)])
   );
 };
 
+/** @param {string} contents @param {string} filePath @returns {unknown} */
+const parseLegacyFile = (contents, filePath) => {
+  const tree = JSON.parse(contents);
+  return convertLegacyNode(tree, [], collectHybridNodes(tree, [], filePath));
+};
+
 // Registers the parser globally on the StyleDictionary class. To actually
 // run it, a Style Dictionary instance must also opt in via
 // `parsers: [LEGACY_TOKENS_PARSER_NAME]` in its config (registering alone
@@ -100,6 +175,6 @@ export const registerLegacyTokensParser = () => {
   StyleDictionary.registerParser({
     name: LEGACY_TOKENS_PARSER_NAME,
     pattern: /\.json$/,
-    parser: ({ contents }) => convertLegacyNode(JSON.parse(contents)),
+    parser: ({ contents, filePath }) => parseLegacyFile(contents, filePath ?? ''),
   });
 };

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

@@ -4,7 +4,9 @@
 // and a `dark` mode, custom properties present in BOTH — matched by name —
 // are written once, as `--name: light-dark(<light-value>, <dark-value>);`,
 // instead of being split across the base mode's top-level `:root { ... }`
-// block and a `@media (prefers-color-scheme: dark) { ... }` block.
+// block and a `@media (prefers-color-scheme: dark) { ... }` block. If the two
+// values are identical, light-dark() would be redundant: the bare value is
+// written instead, e.g. `--name: <value>;`.
 //
 // Only `light` and `dark` are affected:
 //   - a third mode (e.g. a custom `high-contrast` key in sourceModes) is left
@@ -74,7 +76,12 @@ export const applyLightDarkFunc = ({ modeFinalProps, modeNames, baseMode, select
     // Prefers the light-side trailing comment (e.g. a token $description);
     // falls back to the dark-side one if light has none.
     const comment = light.comment || dark.comment;
-    sharedProps[name] = `light-dark(${light.value}, ${dark.value});${comment ? ` ${comment}` : ''}`;
+    // Equal light/dark values: light-dark(x, x) would be redundant — use the
+    // bare value directly instead.
+    const value = light.value === dark.value
+      ? light.value
+      : `light-dark(${light.value}, ${dark.value})`;
+    sharedProps[name] = `${value};${comment ? ` ${comment}` : ''}`;
   }
 
   const stripCommon = (props) => {

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

@@ -83,14 +83,17 @@ import { buildSourceModes } from './build-tokens-src/build-source-modes.mjs';
 // untouched. Files are written flat in jsonBuildPath (no subdirectories), so
 // only its top level is scanned. Runs regardless of sourceModes.
 if (jsonBuildPath) {
+  // Local const: narrowing of the imported `jsonBuildPath` binding is lost
+  // inside the .map() callback below.
+  const jsonDir = jsonBuildPath;
   const { readdir, rm, mkdir } = await import('fs/promises');
-  const existingEntries = await readdir(jsonBuildPath, { withFileTypes: true }).catch(() => []);
+  const existingEntries = await readdir(jsonDir, { withFileTypes: true }).catch(() => []);
   await Promise.all(
     existingEntries
       .filter((entry) => entry.isFile() && /\.jsonc?$/.test(entry.name))
-      .map((entry) => rm(path.join(jsonBuildPath, entry.name)))
+      .map((entry) => rm(path.join(jsonDir, entry.name)))
   );
-  await mkdir(jsonBuildPath, { recursive: true });
+  await mkdir(jsonDir, { recursive: true });
 }
 
 // ── 7. Build ──────────────────────────────────────────────────────────────────

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

@@ -58,7 +58,6 @@ async function run() {
 
     // Path of the generated CSS file containing all custom property definitions
     const custom_prop_file_path = path.resolve(configDir, path.join(config.buildPath, config.destFile));
-    const custom_prop_filename  = path.basename(custom_prop_file_path);
 
     // Directory to scan for CSS files
     const checkdir = path.resolve(configDir, config.dirToCheck);
@@ -69,7 +68,7 @@ async function run() {
 
     // Collect all .css files in the scan directory, excluding any file under a
     // directory whose name starts with "TODO" (work-in-progress folders).
-    // The token file itself (custom_prop_filename) is intentionally included:
+    // The token file itself (custom_prop_file_path) is intentionally included:
     // custom properties are often composed from other custom properties
     // (e.g. `--malert-box-shadow: ... var(--malert-box-shadow-color) ...`)
     // and those internal var() references must count as usage, otherwise the

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

@@ -40,12 +40,14 @@ const config = {
   // .jsonc, reserved for hand-authored DTCG sources. These .json files are
   // parsed with plain JSON.parse (no comments, no trailing commas).
   //
-  // 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) cannot be
-  // represented in DTCG v5 — a node with $value is always a leaf, Style
-  // Dictionary does not descend into its children. In that case only the
-  // node's own value is converted; the nested children are silently lost.
+  // A legacy node that is at the same time a token (own value/type) AND a
+  // group with nested children (e.g. Open Props' other.ease.out, which has
+  // its own value plus out.1 ... out.5) cannot be represented in DTCG v5 —
+  // a node with $value is always a leaf. Its own value is moved to a child
+  // token named `default` (other.ease.out.default, i.e. --other-ease-out-default),
+  // or `base` if a `default` child already exists; if both exist the build
+  // fails. References to such a node from the same file are rewritten
+  // accordingly; from other files they must use the child name explicitly.
   //
   // WARNING: do not use path.join() to build glob patterns — it may corrupt
   // the pattern syntax. Use template literals instead:

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

@@ -138,7 +138,7 @@ const { CustomPropsPurgeCssPlugin } = runCustomPropsPlugin
 // NB: PurgeCSS elabora ogni asset css singolarmente, quindi i @keyframes
 // definiti nello `shared.css` ma usati solo in un altro asset (es. un css di
 // progetto che usa una animation di minimo) verrebbero rimossi: in tal caso
-// aggiungerli a `safelist.keyframes` o impostare `keyframes: false` in
+// aggiungerli a 'safelist.keyframes' o impostare `keyframes: false` in
 // `purgeCSSOptions`
 const shared_chunk_paths = (module) => {
 
@@ -146,7 +146,6 @@ const shared_chunk_paths = (module) => {
   const sep = '[\\\\/]'; // stringa che produce [\\/] nel pattern
   const pathsRegexp = new RegExp([
     'node_modules',
-    'app/src',
     'app/src/js',
     'app/src/web-components',
     'app/src/components',
@@ -411,8 +410,7 @@ const config = {
     //   fileName: path.join(output_dir, 'manifest.json'),
     // sf: fileName: 'manifest.json', // scrive in output.path
     //   // basePath: item.source_dirname
-    //   // removeKeyHash: /(^(_assets\/(?!(fonts\/))))|((\?as_asset)$)/,
-    //   removeKeyHash: true, // /([a-f0-9]{32}\.?)/gi, // /(\?as_asset)$/,
+    //   // removeKeyHash: /\?.*$/, // /([a-f0-9]{32}\.?)/gi, // /(\?as_asset)$/,
     //   // rimuove i font dal manifest. Non necessari, rendono il file inutilmente grande
     //   filter: isDevelopment? undefined : (FileDescriptor) => {
     //     return /fonts/.test(FileDescriptor.path)? false : true;

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

@@ -8,6 +8,10 @@ Le versioni precedenti sono conservate in `archived/webpack-config-v2/` del repo
 
 ---
 
+## Fix da verificare sempre
+* WebpackManifestPlugin: impostare `removeKeyHash: /\?.*$/, // /([a-f0-9]{32}\.?)/gi, // /(\?as_asset)$/,`, sostituendo eventuali impostazione `removeKeyHash: true` se presente
+
+
 ## Da v2 a v3
 
 Novità della v3: le definizioni delle custom properties non sono più gestite da PurgeCSS (`variables`) né da postcss-jit-props, ma da un plugin webpack dedicato, `custom-props-purgecss-plugin.mjs`, che opera sugli asset CSS finali (dopo la minificazione) e inietta solo le custom properties effettivamente usate (dipendenze transitive incluse), partendo dal file master `app/css/custom-properties.css`. Il plugin è attivabile con un flag, indipendente da `usePurgeCss`.

package/package.json

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