@massimo-cassandro/minimo 1.19.0 → 1.19.1

package/design-tokens/README.md

@@ -0,0 +1,195 @@
+# Design Tokens
+
+<!-- TODO intro  -->
+
+## Using design tokens
+
+<!-- TODO modalità d'uso (da tokens penpots o figma, con o snza merge css ecc...) -->
+
+## Design Token Utilities
+
+<!-- TODO rivedere e semplificare -->
+
+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-/,        
+]
+```

package/design-tokens/tokens/src/components/unsplash-page/unsplash-page.minimo.tokens.jsonc

@@ -40,15 +40,23 @@
         "$value": "unset"
       }
     },
-    "credits": {
+    "h1": {
+      "color": {
+        "$type": "color",
+        "$value": "{uspg.text.color}"
+      },
       "font": {
         "size": {
           "$type": "dimension",
-          "$value": "{font.size.xs}"
+          "$value": "{font.size.xl}"
         },
         "weight": {
           "$type": "fontWeight",
-          "$value": "{font.weight.regular}"
+          "$value": "{font.weight.bold}"
+        },
+        "variation-settings": {
+          "$type": "string",
+          "$value": "unset"
         }
       },
       "line-height": {
@@ -56,23 +64,73 @@
         "$value": "{line-height.xs}"
       }
     },
-    "h1": {
+    "link": {
       "color": {
         "$type": "color",
-        "$value": "{uspg.text.color}"
+        "$value": "#fc0"
+      },
+      "decoration": {
+        "$type": "string",
+        "$value": "none"
+      },
+      "visited": {
+        "color": {
+          "$type": "color",
+          "$value": "#C711FF"
+        }
+      },
+      "hover": {
+        "color": {
+          "$type": "color",
+          "$value": "{uspg.bg.color}"
+        },
+        "background": {
+          "color": {
+            "$type": "color",
+            "$value": "transparent"
+          }
+        },
+        "decoration": {
+          "$type": "string",
+          "$value": "underline"
+        }
       },
+      "active": {
+        "color": {
+          "$type": "color",
+          "$value": "#F49C29"
+        }
+      },
+      "focus": {
+        "outline": {
+          "width": {
+            "$type": "dimension",
+            "$value": "2px"
+          },
+          "style": {
+            "$type": "string",
+            "$value": "solid"
+          },
+          "color": {
+            "$type": "color",
+            "$value": "{uspg.link.color}"
+          },
+          "offset": {
+            "$type": "dimension",
+            "$value": "2px"
+          }
+        }
+      }
+    },
+    "credits": {
       "font": {
         "size": {
           "$type": "dimension",
-          "$value": "{font.size.xl}"
+          "$value": "{font.size.xs}"
         },
         "weight": {
           "$type": "fontWeight",
-          "$value": "{font.weight.bold}"
-        },
-        "variation-settings": {
-          "$type": "string",
-          "$value": "unset"
+          "$value": "{font.weight.regular}"
         }
       },
       "line-height": {
@@ -102,26 +160,6 @@
         }
       }
     },
-    "link": {
-      "color": {
-        "$type": "color",
-        "$value": "#fc0"
-      },
-      "decoration": {
-        "$type": "string",
-        "$value": "none"
-      },
-      "hover": {
-        "color": {
-          "$type": "color",
-          "$value": "#fc0"
-        },
-        "decoration": {
-          "$type": "string",
-          "$value": "underline"
-        }
-      }
-    },
     "loader": {
       "color": {
         "$type": "color",

package/design-tokens/{utilities/tokens-config-sample.mjs → tokens-config-sample.mjs}

@@ -10,14 +10,10 @@
 // Path to the design token source files.
 // You can use an absolute path, a relative path, or build it programmatically.
 
-// Example using a local node_modules package (JS source files)
-const minimo_path = '../../node_modules/@massimo-cassandro/minimo/design-tokens-src';
 
-// Alternative: pre-built JSONC files from the same package
-// const minimo_path = '../../node_modules/@massimo-cassandro/minimo/design-tokens';
 
-// For local testing
-// const minimo_path = path.resolve(homedir(), 'Sites/minimo/src');
+// minimo package path in node_modules
+const minimo_path = '../../node_modules/@massimo-cassandro/minimo';
 
 const config = {
 
@@ -42,11 +38,15 @@ const config = {
   //   OK:  `${minimo_path}/**/*.{json,mjs}`
   //   NO:  path.join(minimo_path, '/**/*.{json,mjs}')
   source: [
-    `${minimo_path}/**/*.{jsonc,json,mjs}`,
-    './project-tokens/*.jsonc',
+    `${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/open-props/open-props.style-dictionary-tokens.json',
+
+    // your project tokens
+    './project-tokens/*.{js,mjs,jsonc,json}',
+
   ],
 
   // ---------------------------------------------------------------------------
@@ -61,12 +61,12 @@ const config = {
 
   // Output directory for the Penpot design token files.
   // Set to null (or omit) to disable json output entirely.
-  penpotBuildPath: './path/to/generated/design-tokens-dir',
+  penpotBuildPath: null || './path/to/generated/design-tokens-dir',
 
   // Base name (without extension) for the aggregated Penpot output file.
   // The extension is added automatically based on penpotFormat.
   // Set to null (or omit) to generate one file per .mjs source file instead.
-  penpotDestFile: 'tokens',
+  penpotDestFile: null || 'tokens',
 
   // How to handle math expressions in dimension token $values (e.g. "{size.base} * .25"):
   //   'keep'    write the expression unchanged

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

@@ -218,7 +218,7 @@ for FILE in "${MINIMO_ROOT_CSS_DIR}"/*.css; do
 done
 
 # copia tokens.config.mjs
-safe_cat "${BASE_URL}/../../design-tokens/tokens-config.mjs" "${TEMPLATE_DIR_NAME}/css/tokens-config.mjs"
+safe_cat "${BASE_URL}/../../design-tokens/tokens-config-sample.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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.19.0",
+  "version": "1.19.1",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",
@@ -56,12 +56,16 @@
   "files": [
     "./index.js",
     "src/**/*.{js,mjs,css,svg,md}",
+    "design-tokens/README.md",
+    "design-tokens/tokens-config-sample.mjs",
     "design-tokens/tokens/**/*.{tokens.json,tokens.jsonc}",
     "design-tokens/_src/**/*.{tokens.json,tokens.jsonc,mjs,js,md}",
     "design-tokens/utilities/**/*.{mjs,md}",
     "charts/**/*.{js,mjs,md}",
     "dev-tools/**/*",
-    "snippets/**/*"
+    "snippets/**/*",
+    "!**/TODO*/**",
+    "!**/TODO*"
   ],
   "peerDependencies": {
     "@svgdotjs/svg.js": "^3.2.7",

package/snippets/error-pages/error-pages.js

@@ -1,6 +1,7 @@
 
 
-import { unsplashPage } from '@massimo-cassandro/minimo/index.js';
+import { unsplashPage } from '@massimo-cassandro/minimo';
+// import './error-pages.css';
 
 const errCode = document.documentElement.dataset.errCode || '500',
   errText = document.documentElement.dataset.errText,
@@ -27,7 +28,7 @@ unsplashPage({
   targetElement    : document.getElementById('root'),
   className        : 'error-page',
   unsplashDataUrl  : url,
-  utmSource        : 'ictgovernance.bluvacanze.it',
+  utmSource        : 'marketing.bluvacanze.it',
   title            : errors[errCode]?.title ?? errText,
   text             : `(${errCode} ${errText})`,
   backLink         : errCode !== '503'? 'Torna alla <a href="/">Home</a>' : '',

package/src/components/unsplash-page/unsplash-page.minimo.tokens.mjs

@@ -37,49 +37,112 @@ export default {
       }
     }, // end base setup
 
-    // credit box
-    credits: {
+    // title
+    h1: {
+      color: {
+        $type: 'color',
+        $value: '{uspg.text.color}'
+      },
       font: {
         size: {
           $type: 'dimension',
-          $value: '{font.size.xs}'
+          $value: '{font.size.xl}'
         },
         weight: {
           $type: 'fontWeight',
-          $value: '{font.weight.regular}'
+          $value: '{font.weight.bold}'
         },
+        'variation-settings': {
+          $type: 'string',
+          $value: 'unset'
+        }
       },
       'line-height': {
         $type: 'number',
         $value: '{line-height.xs}'
       },
-    }, // end credits
+    }, // end h1
 
-    // title
-    h1: {
+
+    // links
+    link: {
       color: {
         $type: 'color',
-        $value: '{uspg.text.color}'
+        $value: '#fc0'
+      },
+      decoration: {
+        $type: 'string',
+        $value: 'none'
+      },
+      visited: {
+        color: {
+          $type: 'color',
+          $value: '#C711FF'
+        }
+      },
+      hover: {
+        color: {
+          $type: 'color',
+          $value: '{uspg.bg.color}'
+        },
+        background: {
+          color: {
+            $type: 'color',
+            $value: 'transparent'
+          }
+        },
+        decoration: {
+          $type: 'string',
+          $value: 'underline'
+        },
       },
+      active: {
+        color: {
+          $type: 'color',
+          $value: '#F49C29'
+        }
+      },
+      focus: {
+        outline: {
+          width: {
+            $value: '2px',
+            $type: 'dimension'
+          },
+          style: {
+            $value: 'solid',
+            $type: 'string'
+          },
+          color: {
+            $value: '{uspg.link.color}',
+            $type: 'color'
+          },
+          offset: {
+            $value: '2px',
+            $type: 'dimension'
+          },
+        }
+      }
+
+    },
+
+    // credit box
+    credits: {
       font: {
         size: {
           $type: 'dimension',
-          $value: '{font.size.xl}'
+          $value: '{font.size.xs}'
         },
         weight: {
           $type: 'fontWeight',
-          $value: '{font.weight.bold}'
+          $value: '{font.weight.regular}'
         },
-        'variation-settings': {
-          $type: 'string',
-          $value: 'unset'
-        }
       },
       'line-height': {
         $type: 'number',
         $value: '{line-height.xs}'
       },
-    }, // end h1
+    }, // end credits
+
 
     // icons
     icon: {
@@ -105,30 +168,6 @@ export default {
       }
     }, // end icons
 
-    // links
-    link: {
-      color: {
-        $type: 'color',
-        $value: '#fc0'
-      },
-      decoration: {
-        $type: 'string',
-        $value: 'none'
-      },
-      hover: {
-        color: {
-          $type: 'color',
-          $value: '#fc0'
-        },
-        decoration: {
-          $type: 'string',
-          $value: 'underline'
-        },
-
-      }
-
-    }, // end link
-
     // loader
     loader: {
       color: {

package/src/components/unsplash-page/unsplash-page.module.css

@@ -68,16 +68,33 @@ html, body {
 
   background-color: #333;
 
-  a:is(:link, :visited) {
-    color: var(--uspg-link-color, #fc0);
-    text-decoration: var(--uspg-link-decoration, none);
-
+  a {
+    &:is(:link, :visited) {
+      text-decoration: var(--uspg-link-decoration);
+    }
+    &:link {
+      color: var(--uspg-link-color);
+    }
+    &:visited {
+      color: var(--uspg-link-visited-color);
+    }
+    &:focus {
+      outline: none;
+    }
+    &:focus-visible {
+      outline: var(--uspg-link-focus-outline-width) var(--uspg-link-focus-outline-style) var(--uspg-link-focus-outline-color);
+      outline-offset: var(--uspg-link-focus-outline-offset);
+    }
     @media (hover: hover) {
       &:hover {
-        color: var(--uspg-link-hover-color, #fc0);
-        text-decoration: var(--uspg-link-hover-decoration, underline);
+        color: var(--uspg-link-hover-color);
+        text-decoration: var(--uspg-link-hover-decoration);
+        background-color: var(--uspg-link-hover-background-color);
       }
     }
+    &:active {
+      color: var(--uspg-link-active-color);
+    }
   }
 }
 
@@ -122,6 +139,8 @@ html, body {
   justify-content: center;
   width: 100%;
   overflow: hidden;
+
+
 }
 
 .message, .credits {

package/src/custom-properties.css

@@ -358,10 +358,17 @@
   --uspg-icon-fill-color: #333;
   --uspg-icon-hover-box-bg: #fff;
   --uspg-line-height: var(--line-height-sm);
+  --uspg-link-active-color: #f49c29;
   --uspg-link-color: #fc0;
   --uspg-link-decoration: none;
-  --uspg-link-hover-color: #fc0;
+  --uspg-link-focus-outline-color: var(--uspg-link-color);
+  --uspg-link-focus-outline-offset: .125rem;
+  --uspg-link-focus-outline-style: solid;
+  --uspg-link-focus-outline-width: .125rem;
+  --uspg-link-hover-background-color: transparent;
+  --uspg-link-hover-color: var(--uspg-bg-color);
   --uspg-link-hover-decoration: underline;
+  --uspg-link-visited-color: #c711ff;
   --uspg-loader-color: hsl(0deg 0% 100% / .6);
   --uspg-text-color: #fff;
   --z-index-overlay: 99;

package/src/minimo.css

@@ -1,7 +1,7 @@
 
 /* @import '@src/fonts.css'; */
 /* @import '@src/css/custom-media.css'; */ /* managed by postcss */
-@import '@src/custom-properties.css';
+/* @import '@src/custom-properties.css'; */ /* managed by postcss-jit-props */
 
 @import '@minimo/css/reset.css';
 @import '@minimo/css/layout-base.css';

package/src/web-components/s-datatable-component/s-datatable-component.js

@@ -1,4 +1,7 @@
 // @ts-nocheck
+
+/* global process */
+
 import { DataTable } from 'simple-datatables';
 
 import { parseCols } from './src/parse-cols.js';
@@ -219,7 +222,7 @@ class SimpleDatatableAdapter extends HTMLElement {
     super();
     // this.attachShadow({ mode: 'open' }); // commentare per light dom
 
-    if (!_deprecationWarned) {
+    if (!_deprecationWarned && process.env.NODE_ENV === 'development') {
       _deprecationWarned = true;
       // eslint-disable-next-line no-console
       console.warn('[s-datatable] componente deprecato');