@massimo-cassandro/minimo 0.3.6 → 0.4.1

package/design-tokens-utilities/build-tokens-src/platforms.mjs

@@ -0,0 +1,80 @@
+// build-tokens-src/platforms.mjs
+// Builds and returns the `platforms` object for the Style Dictionary config.
+//
+// The `penpot` platform is included only if penpotBuildPath is set.
+// Output format (json/jsonc) and file splitting are delegated to buildPenpotFiles().
+
+import { buildPenpotFiles } from './formats/penpot.mjs';
+
+// Transforms applied to the CSS platform
+const CSS_TRANSFORMS = [
+  'attribute/cti',
+  'name/kebab',
+  'time/seconds',
+  'asset/url',
+  'size/pxToRem-smart',
+  'color/css-modern',
+  'shadow/css',
+  'gradient/css',
+  'composite/css',
+  'typography/css',
+];
+
+// Transforms applied to the Penpot platform.
+// Kept minimal on purpose: Penpot expects original values (e.g. "16px" not "1rem")
+// and alias references ({...}) must be preserved to maintain token links.
+const PENPOT_TRANSFORMS = [
+  'attribute/cti',
+  'name/kebab',
+  'color/css-modern',
+];
+
+/**
+ * @param {object}          opts
+ * @param {string}          opts.buildPath           Absolute path for CSS output directory
+ * @param {string}          opts.destFile            CSS output filename (e.g. "tokens.css")
+ * @param {string|null}     opts.penpotBuildPath     Absolute path for Penpot output (null = disabled)
+ * @param {string|null}     opts.penpotDestFile      Base name for aggregated file; null = one file per source
+ * @param {'json'|'jsonc'}  opts.penpotFormat        Output format for Penpot files
+ * @param {string[]}        opts.concreteFilePaths   Concrete (expanded) source file paths for multi-file mode.
+ *                                                   Collected from sd.allTokens after SD initialisation.
+ *                                                   Ignored when penpotDestFile is set.
+ * @param {'keep'|'calc'|'resolve'} opts.penpotExpressions  How to handle math expressions in dimension tokens.
+ * @returns {object} platforms object ready for Style Dictionary config
+ */
+export const buildPlatforms = ({
+  buildPath,
+  destFile,
+  penpotBuildPath,
+  penpotDestFile,
+  penpotFormat,
+  penpotExpressions = 'keep',
+  concreteFilePaths = [],
+}) => {
+  const platforms = {
+    css: {
+      buildPath: buildPath + '/',
+      transforms: CSS_TRANSFORMS,
+      files: [
+        {
+          destination: destFile,
+          format: 'css/variables-sorted',
+          options: {
+            outputReferences: true,
+            showFileHeader: true,
+          },
+        },
+      ],
+    },
+  };
+
+  if (penpotBuildPath) {
+    platforms.penpot = {
+      buildPath: penpotBuildPath + '/',
+      transforms: PENPOT_TRANSFORMS,
+      files: buildPenpotFiles(concreteFilePaths, penpotDestFile, penpotFormat, penpotExpressions),
+    };
+  }
+
+  return platforms;
+};

package/design-tokens-utilities/build-tokens-src/transforms.mjs

@@ -0,0 +1,200 @@
+// build-tokens-src/transforms.mjs
+// Registers all custom Style Dictionary transforms.
+// Imported once by build-tokens.mjs before buildAllPlatforms() is called.
+
+import StyleDictionary from 'style-dictionary';
+
+const BASE_FONT_SIZE = 16;
+
+// Converts a px value to rem. Returns the original string unchanged for
+// non-px values, and '0' for zero values regardless of unit.
+const toRem = (val) => {
+  if (val === undefined || val === null) return '0';
+  const str = String(val).trim();
+  const num = parseFloat(str);
+  if (isNaN(num)) return str;
+  if (num === 0) return '0';
+  if (str.endsWith('px')) return `${num / BASE_FONT_SIZE}rem`;
+  return str;
+};
+
+// ---------------------------------------------------------------------------
+// 1. Shadow
+// Converts shadow token objects (single or array) to a CSS box-shadow string.
+// px values are converted to rem. Alias references are resolved transitively.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'shadow/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'shadow' || token.type === 'shadow',
+  transform: (token) => {
+    const original = token.original?.$value ?? token.original?.value;
+
+    const value = (typeof original === 'string' && original.startsWith('{'))
+      ? (token.$value ?? token.value)
+      : (original ?? token.$value ?? token.value);
+
+    const shadows = Array.isArray(value) ? value : [value];
+
+    // Already a resolved CSS string (e.g. from an alias)
+    if (shadows.length === 1 && typeof shadows[0] === 'string') return shadows[0];
+
+    return shadows
+      .map((s) => {
+        const offsetX = toRem(s.offsetX ?? s.x);
+        const offsetY = toRem(s.offsetY ?? s.y);
+        const blur    = toRem(s.blur);
+        const spread  = toRem(s.spread);
+        const color   = s.color ?? 'transparent';
+        const inset   = s.inset ? 'inset ' : '';
+        return `${inset}${offsetX} ${offsetY} ${blur} ${spread} ${color}`;
+      })
+      .join(', ');
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 2. px → rem (dimension tokens only, skips values already in rem)
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'size/pxToRem-smart',
+  type: 'value',
+  filter: (token) => {
+    const value = token.$value || token.value;
+    return (token.$type === 'dimension' || token.type === 'dimension')
+      && typeof value === 'string'
+      && !value.endsWith('rem');
+  },
+  transform: (token) => {
+    const value      = token.$value || token.value;
+    const floatValue = parseFloat(value);
+    if (isNaN(floatValue)) return value;
+    return `${floatValue / BASE_FONT_SIZE}rem`;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 3. Color passthrough
+// Ensures the resolved value is returned as-is, supporting both $value and
+// legacy value fields and transitive alias resolution.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'color/css-modern',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'color' || token.type === 'color',
+  transform: (token) => token.$value ?? token.value,
+});
+
+// ---------------------------------------------------------------------------
+// 4. Gradient
+// Converts gradient token objects to CSS gradient functions.
+// Supports linear, radial and conic types. Alias references are resolved
+// transitively; already-resolved strings are returned unchanged.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'gradient/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'gradient' || token.type === 'gradient',
+  transform: (token) => {
+    const original = token.original?.$value ?? token.original?.value;
+
+    const value = (typeof original === 'string' && original.startsWith('{'))
+      ? (token.$value ?? token.value)
+      : (original ?? token.$value ?? token.value);
+
+    if (typeof value === 'string') return value;
+
+    const { type = 'linear', angle = 90, stops = [] } = value;
+
+    const stopsList = stops
+      .map((s) => {
+        let color = s.color ?? 'transparent';
+        if (s.alpha !== undefined) {
+          color = `color-mix(in srgb, ${color} ${s.alpha * 100}%, transparent)`;
+        }
+        const position = s.position !== undefined ? ` ${s.position * 100}%` : '';
+        return `${color}${position}`;
+      })
+      .join(', ');
+
+    if (type === 'linear') return `linear-gradient(${angle}deg, ${stopsList})`;
+    if (type === 'radial') return `radial-gradient(circle, ${stopsList})`;
+    if (type === 'conic')  return `conic-gradient(from ${angle}deg, ${stopsList})`;
+
+    return `linear-gradient(${angle}${typeof angle === 'number' ? 'deg' : ''}, ${stopsList})`;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 5. Composite (border, outline, transition, animation)
+// Converts composite token objects to their CSS shorthand equivalents.
+// Only applied to object values; strings pass through unchanged.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'composite/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => {
+    const type  = token.$type ?? token.type;
+    const value = token.$value ?? token.value;
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      !Array.isArray(value) &&
+      ['border', 'outline', 'transition', 'animation'].includes(type)
+    );
+  },
+  transform: (token) => {
+    const type = token.$type ?? token.type;
+    const v    = token.$value ?? token.value;
+
+    if (type === 'border') {
+      const parts = [v.width ?? '1px'];
+      if (v.style !== undefined && v.style !== null && v.style !== '') parts.push(v.style);
+      parts.push(v.color ?? 'transparent');
+      return parts.join(' ');
+    }
+
+    if (type === 'outline') {
+      return `${v.width ?? '1px'} ${v.style ?? 'solid'} ${v.color ?? 'transparent'}`;
+    }
+
+    if (type === 'transition') {
+      return [
+        v.duration       ?? '0s',
+        v.timingFunction ?? 'ease',
+        v.delay          ?? '0s',
+        v.property       ?? 'all',
+      ].join(' ');
+    }
+
+    if (type === 'animation') {
+      return [
+        v.duration       ?? '0s',
+        v.timingFunction ?? 'ease',
+        v.delay          ?? '0s',
+        v.iterationCount ?? '1',
+        v.direction      ?? 'normal',
+        v.fillMode       ?? 'none',
+        v.playState      ?? 'running',
+        v.name           ?? 'none',
+      ].join(' ');
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 6. Typography passthrough
+// Returns the token value as-is. The css/variables-sorted format is
+// responsible for exploding typography tokens into individual CSS properties.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'typography/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'typography' || token.type === 'typography',
+  transform: (token) => token.$value ?? token.value,
+});

package/design-tokens-utilities/build-tokens.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+// build-tokens.mjs
+// Entry point: imports modules, runs the build, lints the CSS output, prints the log.
+//
+// Project structure:
+//   build-tokens.mjs              <- this file
+//   build-tokens-src/config.mjs   <- reads --config flag and resolves all paths
+//   build-tokens-src/transforms.mjs  <- registers custom Style Dictionary transforms
+//   build-tokens-src/formats/css.mjs    <- registers the css/variables-sorted format
+//   build-tokens-src/formats/penpot.mjs <- registers the json/penpot format, exports helpers
+//   build-tokens-src/platforms.mjs      <- builds the platforms object (css + optional penpot)
+
+import StyleDictionary from 'style-dictionary';
+import path from 'path';
+import { styleText } from 'node:util';
+import { homedir } from 'os';
+import stylelint from 'stylelint';
+import { pathToFileURL } from 'url';
+
+// ── 1. Configuration (args + resolved paths) ────────────────────────────────
+import {
+  configAbsPath,
+  buildPath,
+  destFile,
+  stylelintConfigPath,
+  penpotBuildPath,
+  penpotDestFile,
+  penpotFormat,
+  penpotExpressions,
+  source,
+} from './build-tokens-src/config.mjs';
+
+// ── 2. Custom transforms ─────────────────────────────────────────────────────
+import './build-tokens-src/transforms.mjs';
+
+// ── 3. CSS format ─────────────────────────────────────────────────────────────
+// customPropsCount is updated by the format at render time
+import { customPropsCount } from './build-tokens-src/formats/css.mjs';
+
+// ── 4. Penpot format ──────────────────────────────────────────────────────────
+import { buildPenpotFiles, collectConcreteFilePaths } from './build-tokens-src/formats/penpot.mjs';
+
+// ── 5. Platforms builder ──────────────────────────────────────────────────────
+import { buildPlatforms } from './build-tokens-src/platforms.mjs';
+
+// ── 6. Collect concrete source file paths (multi-file Penpot mode only) ──────
+// Source entries may be glob patterns. SD expands them internally and stores
+// the concrete path in token.filePath. We need those concrete paths to build
+// the per-file descriptors for the penpot platform.
+//
+// SD v5 lazy-loads sources: `await sd.hasInitialized` triggers loading;
+// after that sd.allTokens is a plain synchronous array with filePath populated.
+//
+// In single-file mode (penpotDestFile is set) we skip this step entirely.
+let concreteFilePaths = [];
+
+if (penpotBuildPath && !penpotDestFile) {
+  const sdInit = new StyleDictionary({ source, log: { verbosity: 'silent' }, platforms: {} });
+  concreteFilePaths = await collectConcreteFilePaths(sdInit);
+}
+
+// ── 7. Build ──────────────────────────────────────────────────────────────────
+const sd = new StyleDictionary({
+  source,
+  log: { verbosity: 'verbose' },
+  platforms: buildPlatforms({
+    buildPath,
+    destFile,
+    penpotBuildPath,
+    penpotDestFile,
+    penpotFormat,
+    penpotExpressions,
+    concreteFilePaths,
+  }),
+});
+
+await sd.buildAllPlatforms();
+
+// ── 8. CSS lint ───────────────────────────────────────────────────────────────
+const stylelintConfig = await import(pathToFileURL(stylelintConfigPath)).then(m => m.default);
+
+await stylelint.lint({
+  config: stylelintConfig,
+  files: [path.join(buildPath, destFile)],
+  fix: true,
+});
+
+// ── 9. Log ────────────────────────────────────────────────────────────────────
+const short = (p) => p.replace(homedir(), '~');
+
+console.log(styleText(['yellow'], `[build-tokens] config file : ${short(configAbsPath)}`));
+console.log(styleText(['yellow'], `[build-tokens] source      : ${source.map(short)}`));
+console.log(styleText(['yellow'], `[build-tokens] dest file   : ${short(path.join(buildPath, destFile))}`));
+
+if (penpotBuildPath) {
+  const penpotFiles = buildPenpotFiles(concreteFilePaths, penpotDestFile, penpotFormat, penpotExpressions);
+  if (penpotFiles.length === 1) {
+    console.log(styleText(['yellow'],
+      `[build-tokens] penpot json : ${short(path.join(penpotBuildPath, penpotFiles[0].destination))}`
+    ));
+  } else {
+    console.log(styleText(['yellow'],
+      `[build-tokens] penpot json : ${penpotFiles.length} files in ${short(penpotBuildPath)}`
+    ));
+  }
+} else {
+  console.log(styleText(['yellow'],
+    `[build-tokens] penpot json : (disabled — penpotBuildPath not set)`
+  ));
+}
+
+console.log(styleText(['green'], `[build-tokens] ${customPropsCount} custom properties processed`));
+console.log(styleText(['green'], '**** DONE ****'));

package/design-tokens-utilities/check-unresolved-custom-props.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-console */
+
+// check-unresolved-custom-props.mjs
+// Scans CSS files in the configured directory and reports any custom property
+// references (var(--...)) that are not defined in the generated token file.
+//
+// Usage: node check-unresolved-custom-props.mjs --config ./path/to/config.mjs
+
+import path from 'path';
+import fs from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname } from 'path';
+import { glob } from 'node:fs/promises';
+import { styleText, parseArgs } from 'node:util';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// 1. Parse flags
+// ---------------------------------------------------------------------------
+const options = {
+  config: {
+    type: 'string',
+    short: 'c',
+  },
+};
+
+const { values } = parseArgs({ options });
+
+if (!values.config) {
+  console.error(styleText(['red'], 'Error: you must provide the config path with --config or -c'));
+  console.log('Example: node check-unresolved-custom-props.mjs --config ./config.mjs');
+  process.exit(1);
+}
+
+const absoluteConfigPath = path.resolve(process.cwd(), values.config);
+const configDir = path.dirname(absoluteConfigPath);
+
+// ---------------------------------------------------------------------------
+// 2. Main
+// ---------------------------------------------------------------------------
+async function run() {
+  try {
+    const { default: config } = await import(pathToFileURL(absoluteConfigPath).href);
+
+    // 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.dir_to_check);
+
+    // Patterns for custom properties to exclude from the unresolved check
+    const exclude = config.exclude_pattern ?? [];
+
+    // Collect all .css files in the scan directory, excluding the token file itself
+    const files = [];
+    for await (const entry of glob(path.join(checkdir, '/**/*.css'))) {
+      if (!entry.endsWith(custom_prop_filename)) {
+        files.push(entry);
+      }
+    }
+
+    if (!fs.existsSync(custom_prop_file_path)) {
+      throw new Error(`Token CSS file not found: ${custom_prop_file_path}`);
+    }
+
+    // ---------------------------------------------------------------------------
+    // 3. Build the list of defined custom properties
+    // ---------------------------------------------------------------------------
+    const cssContent = fs.readFileSync(custom_prop_file_path, 'utf-8');
+    const definitionRegex = /--([a-z0-9-]+)(?=\s*:)/g;
+    const propertyNamesList = [...cssContent.matchAll(definitionRegex)].map(m => `--${m[1]}`);
+
+    // Also include any extra CSS files declared in extra_custom_props_files
+    for (const extraFile of (config.extra_custom_props_files ?? [])) {
+      const extraContent = fs.readFileSync(path.resolve(configDir, extraFile), 'utf-8');
+      const extraMatches = [...extraContent.matchAll(definitionRegex)].map(m => `--${m[1]}`);
+      propertyNamesList.push(...extraMatches);
+    }
+
+    // ---------------------------------------------------------------------------
+    // 4. Scan files for unresolved var() references
+    // ---------------------------------------------------------------------------
+    const usageRegex = /var\(\s*(--[a-z0-9-]+)\s*(,.*?)?\)/g;
+    const unresolved_props = [];
+
+    files.forEach(file => {
+      const fileContent = fs.readFileSync(file, 'utf-8');
+      const filename    = path.relative(configDir, file);
+      const matches     = [...fileContent.matchAll(usageRegex)];
+
+      matches.forEach(match => {
+        const cprop      = match[1];
+        const isExcluded = exclude.some(exRegex => exRegex.test(cprop));
+        const isDefined  = propertyNamesList.includes(cprop);
+        const lineNumber = fileContent.substring(0, match.index).split('\n').length;
+
+        if (!isExcluded && !isDefined) {
+          unresolved_props.push({ file: filename, line: lineNumber, prop: cprop });
+        }
+      });
+    });
+
+    unresolved_props.sort((a, b) => a.file.localeCompare(b.file));
+
+    // ---------------------------------------------------------------------------
+    // 5. Write the report
+    // ---------------------------------------------------------------------------
+    const result_file = path.resolve(configDir, 'unresolved-props.md');
+
+    console.log(styleText(['green'],
+      `${unresolved_props.length} unresolved custom properties found -> ${path.relative(process.cwd(), result_file)}`
+    ));
+
+    fs.writeFileSync(
+      result_file,
+      unresolved_props
+        .map(item =>
+          `* [${path.basename(item.file)} :: ${item.line}](${item.file}#L${item.line}) -> var(${item.prop})`
+        )
+        .join('\n'),
+      'utf-8'
+    );
+
+    console.log(styleText(['green'], '**** DONE ****'));
+
+  } catch (err) {
+    console.log(styleText(['redBright'], err.stack));
+    process.exit(1);
+  }
+}
+
+run();