@massimo-cassandro/minimo 1.18.3 → 1.19.0

package/README.md

@@ -31,6 +31,10 @@ rm -rf package
 
 ---
 
+## Design tokens
+
+Minimo comes with a set of design tokens and some utilities to manage them. See [Design Tokens readme](design-tokens/README.md).
+
 ## Dev Tools
 
 The [`dev-tools`](./dev-tools/README.md) directory contains a set of standalone Node.js CLI utilities for managing a web project — updating dependencies, bumping the version and changelog, and generating/optimizing SVG icons and favicons. They are published as part of the `minimo` package and exposed via the `bin` entries in `package.json` (`update-version`, `upd@m`, `svgIconsTools`, `create-favicons`); see the [Dev Tools README](./dev-tools/README.md) for the full list and usage.
@@ -38,7 +42,7 @@ The [`dev-tools`](./dev-tools/README.md) directory contains a set of standalone
 
 ## Docs & Demo
 
-[Docs](docs)
+[Docs](docs/README.md)
 
 [Demo](https://massimo-cassandro.github.io/minimo/) (in progress)
 

package/design-tokens/tokens/src/components/modal-popup/modal-popup.minimo.tokens.jsonc

@@ -16,7 +16,7 @@
     },
     "max-width": {
       "$type": "dimension",
-      "$value": "98dvw"
+      "$value": "70dvw"
     },
     "height": {
       "$type": "dimension",

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

@@ -75,6 +75,11 @@ export const penpotExpressions = VALID_EXPR_MODES.includes(buildConfig.penpotExp
   ? buildConfig.penpotExpressions
   : 'resolve';
 
+// mergeCustomProps: if true, custom properties already present in the CSS
+// destination file take priority over the ones generated by this build (see
+// build-tokens-src/merge-css.mjs). Default: false.
+export const mergeCustomProps = buildConfig.mergeCustomProps === true;
+
 // ---------------------------------------------------------------------------
 // Source: resolve patterns relative to the config directory and normalise to
 // forward-slash absolute paths (fast-glob, used internally by Style Dictionary,

package/design-tokens/utilities/build-tokens-src/formats/css.mjs

@@ -6,6 +6,7 @@
 //   - individual properties for letterSpacing, textTransform, textDecoration
 
 import StyleDictionary from 'style-dictionary';
+import { mergeCustomProps, parseCustomProps } from '../merge-css.mjs';
 
 const BASE_FONT_SIZE = 16;
 
@@ -224,7 +225,22 @@ StyleDictionary.registerFormat({
         return [`  --${token.name}: ${value};`];
       });
 
-    customPropsCount = lines.length;
-    return `${selector} {\n${lines.join('\n')}\n}\n`;
+    // Build a name → declaration-tail map from the declarations generated
+    // above, then merge with any pre-existing custom properties loaded via
+    // loadExistingCustomProps() (see ../merge-css.mjs). Pre-existing values
+    // (including trailing comments) take priority when both exist;
+    // pre-existing-only properties are kept.
+    const generatedProps = parseCustomProps(lines.join('\n'));
+    const finalProps = mergeCustomProps(generatedProps);
+
+    // Final output is always sorted alphabetically ascending by property
+    // name, regardless of merge — this also keeps pre-existing-only
+    // properties from merge-css.mjs in order instead of trailing at the end.
+    const outLines = Object.entries(finalProps)
+      .sort(([a], [b]) => a.localeCompare(b, 'en', { numeric: true, sensitivity: 'base' }))
+      .map(([name, tail]) => `  --${name}: ${tail}`);
+
+    customPropsCount = outLines.length;
+    return `${selector} {\n${outLines.join('\n')}\n}\n`;
   },
 });

package/design-tokens/utilities/build-tokens-src/merge-css.mjs

@@ -0,0 +1,60 @@
+// build-tokens-src/merge-css.mjs
+// Supports the `mergeCustomProps` config option: pre-existing custom
+// properties in the CSS destination file take priority over the ones
+// generated by the current build (manual overrides/additions survive rebuilds).
+//
+// Usage:
+//   1. Call loadExistingCustomProps(absDestPath) BEFORE Style Dictionary runs,
+//      since it reads the file that is about to be overwritten.
+//   2. The css/variables-sorted format (see formats/css.mjs) calls
+//      mergeCustomProps(generatedMap) while building the output, right before
+//      serialising the final CSS text.
+
+import { existsSync, readFileSync } from 'node:fs';
+
+const CUSTOM_PROP_RE = /^\s*--([\w-]+):\s*(.+)$/gm;
+
+/**
+ * Parses `--name: <tail>` declarations out of a CSS text block. <tail> is
+ * captured verbatim (value, terminating `;`, and anything else on the same
+ * line, e.g. a trailing comment) so it round-trips unchanged through a merge.
+ * Only single-line declarations are supported.
+ * @param {string} cssText
+ * @returns {Record<string,string>} name → declaration-tail map, in first-seen order
+ */
+export const parseCustomProps = (cssText) => {
+  /** @type {Record<string,string>} */
+  const map = {};
+  for (const match of cssText.matchAll(CUSTOM_PROP_RE)) {
+    map[match[1]] = match[2].trim();
+  }
+  return map;
+};
+
+// null = merge disabled, or destination file not found yet (first build)
+/** @type {Record<string,string>|null} */
+let existingCustomProps = null;
+
+/**
+ * Reads the CSS destination file (if it exists) and stores a name → value
+ * map of its current custom properties for later merging.
+ * @param {string} absDestPath absolute path of the CSS file to read
+ * @returns {Record<string,string>|null}
+ */
+export const loadExistingCustomProps = (absDestPath) => {
+  existingCustomProps = existsSync(absDestPath)
+    ? parseCustomProps(readFileSync(absDestPath, 'utf8'))
+    : null;
+  return existingCustomProps;
+};
+
+/**
+ * Merges freshly generated custom properties with the ones previously loaded
+ * via loadExistingCustomProps(). Pre-existing values take priority; custom
+ * properties found only in the pre-existing file (no longer generated) are
+ * kept as well.
+ * @param {Record<string,string>} generated name → value map produced by this build
+ * @returns {Record<string,string>}
+ */
+export const mergeCustomProps = (generated) =>
+  existingCustomProps ? { ...generated, ...existingCustomProps } : generated;

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

@@ -31,6 +31,7 @@ import {
   penpotFormat,
   penpotExpressions,
   source,
+  mergeCustomProps,
 } from './build-tokens-src/config.mjs';
 
 // ── 2. Custom transforms ─────────────────────────────────────────────────────
@@ -38,7 +39,9 @@ import './build-tokens-src/transforms.mjs';
 
 // ── 3. CSS format ─────────────────────────────────────────────────────────────
 // customPropsCount is updated by the format at render time
+// loadExistingCustomProps supports the mergeCustomProps option (see below)
 import { customPropsCount } from './build-tokens-src/formats/css.mjs';
+import { loadExistingCustomProps } from './build-tokens-src/merge-css.mjs';
 
 // ── 4. Penpot format ──────────────────────────────────────────────────────────
 import { buildPenpotFiles, collectConcreteFilePaths } from './build-tokens-src/formats/penpot.mjs';
@@ -46,6 +49,15 @@ import { buildPenpotFiles, collectConcreteFilePaths } from './build-tokens-src/f
 // ── 5. Platforms builder ──────────────────────────────────────────────────────
 import { buildPlatforms } from './build-tokens-src/platforms.mjs';
 
+// ── 5b. Pre-existing custom properties (mergeCustomProps option) ────────────
+// Read before Style Dictionary runs, since it overwrites the destination
+// file. The css/variables-sorted format (formats/css.mjs) merges these
+// values in — pre-existing values take priority — right before serialising
+// the final CSS output. See merge-css.mjs.
+if (mergeCustomProps) {
+  loadExistingCustomProps(path.join(buildPath, destFile));
+}
+
 // ── 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

package/design-tokens/utilities/tokens-config-sample.mjs

@@ -75,6 +75,14 @@ const config = {
   //               e.g. {size.base} = 16px, "{size.base} * .25" -> "4px"
   penpotExpressions: 'resolve',
 
+  // If true, custom properties already present in the CSS destination file
+  // (destFile, from a previous build) take priority over the ones generated
+  // by this build. Properties found only in the pre-existing file (no longer
+  // generated) are kept too. Useful to preserve manual overrides/additions
+  // made directly in the compiled CSS across rebuilds. Ignored on the first
+  // build, when destFile does not exist yet. Default: false.
+  mergeCustomProps: false,
+
 
 
   // ---------------------------------------------------------------------------

package/dev-tools/README.md

@@ -34,6 +34,14 @@ zsh package/dev-tools/starter-kit/starter-install.sh
 rm -rf package
 ```
 
+To test the installation skipping all `npm install` commands, use the `--no-npm` parameter:
+
+```bash
+curl -sL "$(npm view @massimo-cassandro/minimo dist.tarball)" | tar xz package/dev-tools/starter-kit
+zsh package/dev-tools/starter-kit/starter-install.sh --no-npm
+rm -rf package
+```
+
 ## SVG adn favicons tools
 
 ```bash

package/dev-tools/starter-kit/starter-install.sh

@@ -18,6 +18,23 @@ if [ -z "$ZSH_VERSION" ]; then
   exit 1
 fi
 
+# --no-npm: salta le installazioni npm (utile per testare rapidamente lo script)
+SKIP_NPM=0
+for ARG in "$@"; do
+  if [ "$ARG" = "--no-npm" ]; then
+    SKIP_NPM=1
+  fi
+done
+
+# Wrapper: esegue "npm i ..." a meno che SKIP_NPM sia attivo
+npm_i() {
+  if [ "$SKIP_NPM" = "1" ]; then
+    echo "(--no-npm) skip: npm i $*"
+  else
+    npm i "$@"
+  fi
+}
+
 # Configurazione variabili
 # BASE_URL="https://raw.githubusercontent.com/massimo-cassandro/minimo/refs/heads/main"
 
@@ -139,28 +156,28 @@ fi
 
 
 echo -e "\n${GREEN}...eslint${NC}"
-npm i -D @massimo-cassandro/eslint-config
+npm_i -D @massimo-cassandro/eslint-config
 safe_cat "${TEMPLATES_DIR}/eslint.config.mjs" eslint.config.mjs new
 
 echo -e "\n${GREEN}...stylelint${NC}"
-npm i -D @massimo-cassandro/stylelint-config
+npm_i -D @massimo-cassandro/stylelint-config
 safe_cat "${TEMPLATES_DIR}/stylelint.config.mjs" stylelint.config.mjs new
 
 echo -e "\n${GREEN}...webpack${NC}"
-npm i -D webpack-cli webpack-dev-server webpack-manifest-plugin webpack
-npm i -D @babel/core @babel/preset-env babel-loader terser-webpack-plugin
-npm i -D webpack-remove-empty-scripts copy-webpack-plugin html-loader html-webpack-plugin
-npm i -D postcss autoprefixer postcss-custom-media @csstools/postcss-global-data postcss-loader postcss-preset-env
+npm_i -D webpack-cli webpack-dev-server webpack-manifest-plugin webpack
+npm_i -D @babel/core @babel/preset-env babel-loader terser-webpack-plugin
+npm_i -D webpack-remove-empty-scripts copy-webpack-plugin html-loader html-webpack-plugin
+npm_i -D postcss autoprefixer postcss-custom-media @csstools/postcss-global-data postcss-loader postcss-preset-env
 # NB: niente cssnano: la minificazione è di css-minimizer-webpack-plugin e cssnano
 # nel loader postcss eliminerebbe i commenti `purgecss ignore` prima di PurgeCSS
-npm i -D mini-css-extract-plugin style-loader css-loader css-minimizer-webpack-plugin
-npm i -D responsive-loader
-npm i -D process dotenv-webpack
-npm i -D svgo svg-url-loader svgo-loader svgo-add-viewbox mini-svg-data-uri
-npm i -D ejs-loader
-npm i -D purgecss-webpack-plugin glob
+npm_i -D mini-css-extract-plugin style-loader css-loader css-minimizer-webpack-plugin
+npm_i -D responsive-loader
+npm_i -D process dotenv-webpack
+npm_i -D svgo svg-url-loader svgo-loader svgo-add-viewbox mini-svg-data-uri
+npm_i -D ejs-loader
+npm_i -D purgecss-webpack-plugin glob
 
-npm i -D style-dictionary
+npm_i -D style-dictionary
 
 safe_cat "${WEBPACK_SOURCE_DIR}/webpack.config.mjs"   "${FRONTEND_INSTALL_PATH}/webpack.config.mjs"
 safe_cat "${WEBPACK_SOURCE_DIR}/webpack-template.ejs" "${FRONTEND_INSTALL_PATH}/webpack-template.ejs"
@@ -168,15 +185,6 @@ safe_cat "${WEBPACK_SOURCE_DIR}/webpack-template.ejs" "${FRONTEND_INSTALL_PATH}/
 # cartella webpack
 WEBPACK_LOCAL_DIR="${FRONTEND_INSTALL_PATH}/webpack-modules"
 WEBPACK_MODULES_REMOTE_URL="${WEBPACK_SOURCE_DIR}/webpack-modules"
-FILES=(
-  'css-rules.mjs'
-  'get-jsConfig-aliases.mjs'
-  'mini-svg-data-uri-loader.cjs'
-  'svg-rules.mjs'
-  'svgo.config.mjs'
-  'postcss.config.mjs'
-  'purgecss-variables-safelist.mjs'
-)
 
 # se la cartella esiste già, i moduli vengono copiati in NEW-webpack-modules
 # (da integrare manualmente o rimuovere)
@@ -188,18 +196,30 @@ fi
 
 mkdir -p "$WEBPACK_LOCAL_DIR"
 
-for FILE in "${FILES[@]}"; do
-  safe_cat "${WEBPACK_MODULES_REMOTE_URL}/${FILE}" "${WEBPACK_LOCAL_DIR}/${FILE}"
+# copia tutti i file presenti in webpack-modules,
+for FILE in "${WEBPACK_MODULES_REMOTE_URL}"/*; do
+  [ -f "$FILE" ] || continue
+  safe_cat "$FILE" "${WEBPACK_LOCAL_DIR}/$(basename "$FILE")"
 done
 
 echo -e "\n${GREEN}Creating a template of your frontend application's folder structured${NC}"
 
-TEMPLATE_DIR_NAME="__frontend_app_dir_template__"
+TEMPLATE_DIR_NAME="__frontend_dir__"
 mkdir -p "$TEMPLATE_DIR_NAME"
 cd "$TEMPLATE_DIR_NAME"
-mkdir -p error-pages imgs icons src src/css favicons design-tokens
+mkdir -p error-pages imgs icons src css favicons design-tokens
 cd ..
 
+# copia dei file css presenti nella root di minimo/src
+# (custom-properties.css, custom-media.css, fonts.css, minimo.css, ...):
+MINIMO_ROOT_CSS_DIR="${BASE_URL}/../../src"
+for FILE in "${MINIMO_ROOT_CSS_DIR}"/*.css; do
+  safe_cat "$FILE" "${TEMPLATE_DIR_NAME}/css/$(basename "$FILE")"
+done
+
+# copia tokens.config.mjs
+safe_cat "${BASE_URL}/../../design-tokens/tokens-config.mjs" "${TEMPLATE_DIR_NAME}/css/tokens-config.mjs"
+
 # template delle entry css (globale/di pagina e critical): ogni entry deve
 # importare direttamente custom-properties.css (vedi commenti nei file stessi)
 safe_cat "${TEMPLATES_DIR}/entry-tpl.css"          "${TEMPLATE_DIR_NAME}/src/entry-tpl.css"

package/package.json

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

package/src/components/modal-popup/modal-popup.minimo.tokens.mjs

@@ -11,7 +11,7 @@ export default {
     },
     'max-width': {
       $type: 'dimension',
-      $value: '98dvw',
+      $value: '70dvw',
     },
     height: {
       $type: 'dimension',

package/src/custom-properties.css

@@ -232,7 +232,7 @@
   --mpopup-header-padding: var(--size-xs);
   --mpopup-height: max-content;
   --mpopup-max-height: 5.625rem;
-  --mpopup-max-width: 6.125rem;
+  --mpopup-max-width: 4.375rem;
   --mpopup-min-height: 18.75rem;
   --mpopup-min-width: 25rem;
   --mpopup-width: max-content;

package/design-tokens/utilities/readme.md

@@ -1,185 +0,0 @@
-# Design Token Utilities
-
-A set of Node.js scripts for managing CSS design tokens in a project. Built on top of [Style Dictionary v5](https://styledictionary.com/).
-
-## Scripts
-
-| Script | Purpose |
-|---|---|
-| `build-tokens.mjs` | Generates a CSS custom properties file from design token source files |
-| `check-unresolved-custom-props.mjs` | Scans CSS files and reports any `var(--...)` references not found in the generated token file |
-
-Both scripts share the same config file, passed via `--config`.
-
-## Setup
-
-The scripts are intended to be used as npm scripts. Add them to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "build tokens": "npx buildTokens --config ./path/to/tokens-config.mjs",
-    "check unresolved props": "npx checkUnresolvedProps --config ./path/to/tokens-config.mjs"
-  }
-}
-```
-
-### Dependencies
-
-The following packages must be present in your project:
-
-```json
-{
-  "style-dictionary": "^5",
-  "stylelint": "^16"
-}
-```
-
-## Configuration file
-
-Both scripts read a shared config file passed with `--config`. Use `tokens-config-sample.mjs` as a starting point.
-
-Read comments inside the sample file for more info.
-
-
-## `build-tokens.mjs`
-
-Reads design token source files and generates:
-- A **CSS file** containing all tokens as custom properties inside `:root { ... }`
-- Optionally, one or more **W3C DTCG JSON/JSONC** files to import into Penpot/Figma (use in Figma requires a plugin).
-
-### Usage
-
-```sh
-npx buildTokens --config ./path/to/tokens-config.mjs
-```
-
-### Source files
-
-The `source` array accepts any combination of:
-- Concrete file paths: `'./tokens/colors.jsonc'`
-- Glob patterns: `'./tokens/**/*.{json,jsonc,mjs}'`
-
-**Supported formats:**
-- `.json` / `.jsonc` — parsed directly as token data
-- `.mjs` / `.js` — imported as ES modules; must export a W3C DTCG-compliant object as `default`
-
-
-### Token file format (JS example)
-
-When using `.mjs` source files, export a default object following the [W3C Design Token Community Group format](https://design-tokens.github.io/community-group/format/):
-
-```js
-// colors.tokens.mjs
-export default {
-  color: {
-    brand: {
-      primary: { $type: 'color', $value: '#0057FF' },
-      secondary: { $type: 'color', $value: '#FF6B00' },
-    },
-    neutral: {
-      '100': { $type: 'color', $value: '#F5F5F5' },
-      '900': { $type: 'color', $value: '#1A1A1A' },
-    },
-  },
-  semantic: {
-    color: {
-      text: {
-        primary: { $type: 'color', $value: '{color.neutral.900}' }, // alias
-      },
-    },
-  },
-};
-```
-
-The main advantage of `.mjs` over `.json` is the ability to use JavaScript variables, comments, and computed values within the token definition.
-
-Values can be expressions like `"{size.base} * .25"`, see `tokens-config-sample.mjs` for more info.
-
-### Custom transforms
-
-The following transforms are registered on top of Style Dictionary's built-ins:
-
-| Name | Type | Description |
-|---|---|---|
-| `shadow/css` | value | Converts shadow objects (single or array) to a `box-shadow` CSS string. px values are converted to rem. |
-| `size/pxToRem-smart` | value | Converts `dimension` token values from px to rem. Skips values already in rem. |
-| `color/css-modern` | value | Color passthrough with transitive alias support. |
-| `gradient/css` | value | Converts gradient objects to CSS `linear-gradient`, `radial-gradient` or `conic-gradient`. |
-| `composite/css` | value | Converts `border`, `outline`, `transition` and `animation` objects to their CSS shorthand. |
-| `typography/css` | value | Typography passthrough — the format handles exploding the value into individual properties. |
-
-### CSS output
-
-All tokens are output as CSS custom properties inside `:root`, sorted alphabetically.
-
-Typography tokens are expanded into multiple properties:
-- `--token-name-font` — a `font` shorthand (when both `fontSize` and `fontFamily` are present)
-- `--token-name-letter-spacing`, `--token-name-text-transform`, `--token-name-text-decoration` — individual properties
-
-The generated file is linted and auto-fixed with stylelint using the config specified in `stylelintConfigPath`.
-
-### Penpot output
-
-When `penpotBuildPath` is set, the script also generates W3C DTCG token files for import into Penpot via the [Design Tokens plugin](https://penpot.app/penpot-files/design-tokens).
-
-**Single file** (`penpotDestFile` is a string):
-```
-penpotBuildPath/tokens.jsonc   ← all tokens in one file
-```
-
-**One file per source** (`penpotDestFile` is `null` or omitted):
-```
-penpotBuildPath/colors.tokens.jsonc
-penpotBuildPath/spacing.tokens.jsonc
-penpotBuildPath/typography.tokens.jsonc
-```
-
-The `penpotFormat` option controls the output:
-
-| Value | Extension | Disclaimer header |
-|---|---|---|
-| `'jsonc'` | `.jsonc` | Yes |
-| `'json'` | `.json` | No |
-
-Alias references (`{color.brand.primary}`) are preserved in the output so Penpot maintains token links between primitive and semantic tokens.
-
-> Penpot token files intentionally use a minimal set of transforms (no px→rem conversion, no shorthand expansion) because Penpot expects original values and structured objects, not resolved CSS strings.
-
----
-
-## `check-unresolved-custom-props.mjs`
-
-Scans all `.css` files in `dir_to_check` (recursively) and reports any `var(--...)` references that are not defined in the generated token CSS file or in any `extra_custom_props_files`.
-
-Results are written to `unresolved-props.md` in the same directory as the config file.
-
-### Usage
-
-```sh
-npx checkUnresolvedProps --config ./path/to/tokens-config.mjs
-```
-
-### Output
-
-The script creates a `unresolved-props.md` file next to the config file. Each line links to the file and line number where the unresolved property is used:
-
-```markdown
-* [components.css :: 42](../src/components.css#L42) -> var(--color-action-hover)
-* [layout.css :: 17](../src/layout.css#L17) -> var(--spacing-missing)
-```
-
-In VS Code, Option/Alt-clicking on the URL opens the file at the required line.
-
-
-### Excluding properties
-
-Use `exclude_pattern` to suppress false positives — for example, internal/private custom properties that are defined dynamically or inline:
-
-```js
-// skips all custom props starting with `--_` or `--js-`
-exclude_pattern: [
-  /^--_/,          
-  /^--js-/,        
-]
-```