@massimo-cassandro/minimo 1.24.12 → 1.26.0

package/README.md

@@ -25,7 +25,7 @@ To bootstrap a project **before** installing the whole package, download only th
 
 ```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
+zsh package/dev-tools/starter-kit/starter-install.sh
 rm -rf package
 ```
 

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

@@ -81,6 +81,10 @@ const config = {
       name: 'LAYOUT',
       prefixes: ['body', 'layout'],
     },
+    {
+      name: 'UI',
+      prefixes: ['ui'],
+    },
   ],
 
 

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

@@ -139,6 +139,7 @@ safe_cat "${TEMPLATES_DIR}/_editorconfig"              .editorconfig new
 safe_cat "${TEMPLATES_DIR}/_prettierrc"                .prettierrc new
 safe_cat "${TEMPLATES_DIR}/_root_htaccess"             "${FRONTEND_INSTALL_PATH}/_root_htaccess"
 safe_cat "${TEMPLATES_DIR}/_root_robots.txt"           "${FRONTEND_INSTALL_PATH}/_root_robots.txt"
+safe_cat "${TEMPLATES_DIR}/CLAUDE-frontend.md"         "${FRONTEND_INSTALL_PATH}/CLAUDE.md"
 
 # jsconfig.json: sta SEMPRE nella root del progetto (è anche il file di
 # riferimento di vscode). I suoi path sono quindi relativi alla root: il
@@ -278,9 +279,9 @@ else
   safe_cat "${MINIMO_PKG_DIR}/dev-tools/create-favicons/src/default-params.mjs" "${FRONTEND_INSTALL_PATH}/favicons/create-favicons-cfg.mjs"
 fi
 
-# entry css critical (inlinata nei template html) e entry js, sulla root di
+# entry css critical (inline nei template html) e entry js, sulla root di
 # installazione accanto a index.css
-safe_cat "${TEMPLATES_DIR}/index-critical.css" "${FRONTEND_INSTALL_PATH}/index-critical.css"
+safe_cat "${TEMPLATES_DIR}/layout-critical.css" "${FRONTEND_INSTALL_PATH}/src/css/layout-critical.css"
 safe_cat "${TEMPLATES_DIR}/app_index.js"       "${FRONTEND_INSTALL_PATH}/index.js"
 
 # favicons: istruzioni d'uso di `npx create-favicons`

package/dev-tools/starter-kit/templates/CLAUDE-frontend.md

@@ -0,0 +1,13 @@
+# CLAUDE.md - frontend
+
+## Contesto di dominio
+
+
+
+## Stile di lavoro
+
+- Conferma la comprensione prima di agire su richieste ambigue
+- Il progetto usa ES modules (import/export), evitare sioluzioni che utilizzano commonJs
+- In linea di massima non proporre soluzioni che richiedano modifiche alla parte back-end, a meno che non sia esplicitamente richiesto
+- nella chat evitare neologismi come parsare, committare ecc., usare i termini corrispondi in italiano o il termine originale in inglese dove non sia possibile un equivalente in italiano
+- nei commenti su più righe preferire `/* ... */` piuttosto che ripetere `//` ad igni inizio riga

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

@@ -252,6 +252,19 @@ const config = {
       directory: path.join(__dirname, '/'),
       serveIndex: true
     },
+    /*
+    proxy: [
+      {
+        // /login, /logout (redirect Google) e /api/... (fetch AJAX) vanno
+        // inoltrati al server PHP reale (npm run "php server", vedi
+        // package.json e app/router.php), che webpack-dev-server non può
+        // eseguire da solo.
+        context: ['/api', '/login', '/logout'],
+        target: process.env.PHP_BASE_URL || 'http://localhost:8000'
+      }
+    ],
+    static: false,
+    */
     open: { app: { name: 'Google Chrome' } },
     compress: true,
     hot: true,

package/package.json

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

package/src/utilities/dom-builder/dom-builder.js

@@ -14,17 +14,18 @@ import { parseDomString } from './parseDomString.js';
  * @property {string | string[]} [classname] - Alias for `className`.
  * @property {string | null} [id] - Unique element ID.
  * @property {[string, *] | [string, *][] | Object<string, *>} [attrs] - Attributes: a `[name, value]` pair, array of pairs, or `{name: value}` object.
- * @property {string | number | Function | Element | DomBuilderItem[] | null} [content] - Element content.
+ * @property {string | number | Function | Node | DomBuilderItem[] | null} [content] - Element content.
  *   A string or number is set as plain text (`textContent`) unless it contains `<`, in which case it is
  *   treated as markup: sanitized and inserted via the native Sanitizer API (`Element.setHTML`) where
- *   supported, falling back to raw `innerHTML` on browsers without it.
+ *   supported, falling back to raw `innerHTML` on browsers without it. A `Node` (an `Element`, a
+ *   `DocumentFragment`, ...) is appended as-is, either directly or returned from a function.
  * @property {string | number} [text] - Literal text node shorthand: inserts a plain `Text` node (never
  *   parsed as markup) in place of an element, so it can sit as a sibling of tags within `children`/`content`
  *   arrays. Mutually exclusive with `tag`/`content`/`children`: when set (and `tag` is absent), every other
  *   property except `condition` and `callback` is ignored.
  * @property {boolean} [condition=true] - When false, the element (or text node) is skipped.
  * @property {(function(HTMLElement|Text): void) | null} [callback] - Callback invoked after the element (or text node) is created.
- * @property {Array<DomBuilderItem|string>} [children] - Configuration array for child elements. Accepts strings (shorthand per `parseDomString`) and/or configuration objects.
+ * @property {Array<DomBuilderItem|string|Node>} [children] - Configuration array for child elements. Accepts strings (shorthand per `parseDomString`), configuration objects, and/or `Node`s (an `Element`, a `DocumentFragment`, ...) inserted as-is.
  */
 
 /**
@@ -44,7 +45,7 @@ import { parseDomString } from './parseDomString.js';
  *     className: 'xxx' | ['class1', 'class2'], // also `class`
  *     id: 'element-id',
  *     attrs: [attr_name, attr_value] | [[...], [...]] | {name: value},
- *     content: 'xxx' | 'xxx <strong>yyy</strong>' | 123 | domBuilder Array | function | Element, // see DomBuilderItem.content above
+ *     content: 'xxx' | 'xxx <strong>yyy</strong>' | 123 | domBuilder Array | function | Node, // see DomBuilderItem.content above
  *     condition: true | false,
  *     callback: el => ...,
  *     children: [...]
@@ -84,16 +85,16 @@ import { parseDomString } from './parseDomString.js';
  * object-level properties take precedence.
  *
  * @function domBuilder
- * @param {Array<DomBuilderItem|string>} [structureArray=[]] - Configuration array. Accepts strings (shorthand per `parseDomString`) and/or configuration objects, each supporting:
+ * @param {Array<DomBuilderItem|string|Node>} [structureArray=[]] - Configuration array. Accepts strings (shorthand per `parseDomString`), configuration objects, and/or `Node`s (an `Element`, a `DocumentFragment`, ...) inserted as-is; each configuration object supports:
  * - `tag` / `tagName` {string | string[]} - HTML tag name, or array of nested tags (each is parent of the next). Default `'div'`.
  * - `className` / `class` / `classname` {string | string[]} - CSS class(es): a single string or an array (falsy values filtered out).
  * - `id` {string | null} - Unique element ID.
  * - `attrs` {[string, *] | [string, *][] | Object<string, *>} - Attributes: a `[name, value]` pair, array of pairs, or `{name: value}` object.
- * - `content` {string | number | Function | Element | DomBuilderItem[] | null} - Element content. A string/number is set as `textContent` unless it contains `<`, in which case it's sanitized and inserted as markup (`Element.setHTML`, falling back to `innerHTML`).
+ * - `content` {string | number | Function | Node | DomBuilderItem[] | null} - Element content. A string/number is set as `textContent` unless it contains `<`, in which case it's sanitized and inserted as markup (`Element.setHTML`, falling back to `innerHTML`). A `Node` (`Element`, `DocumentFragment`, ...), passed directly or returned from a function, is appended as-is.
  * - `text` {string | number} - Literal text node shorthand: inserts a plain `Text` node (never parsed as markup) as a sibling of other items, in place of an element. Mutually exclusive with `tag`/`content`/`children`.
  * - `condition` {boolean} - When false, the element (or text node) is skipped. Default `true`.
  * - `callback` {(function(HTMLElement|Text): void) | null} - Invoked after the element (or text node) is created.
- * - `children` {Array<DomBuilderItem|string>} - Configuration array for child elements (same format, nested).
+ * - `children` {Array<DomBuilderItem|string|Node>} - Configuration array for child elements (same format, nested; also accepts `Node`s inserted as-is).
  *
  * IDs and classes can be specified either as top-level object keys or inside `attrs`; top-level properties take precedence.
  * @param {HTMLElement} [parent] - Parent element the structure is attached to (see `options.insertMode`).
@@ -105,7 +106,7 @@ import { parseDomString } from './parseDomString.js';
  */
 
 
-export function domBuilder(structureArray = [], parent, options = {}) {
+export function domBuilder(/** @type {Array<DomBuilderItem|string|Node>} */ structureArray = [], parent, options = {}) {
 
   options = {
     emptyParent: false,
@@ -143,6 +144,34 @@ export function domBuilder(structureArray = [], parent, options = {}) {
 
   structureArray.forEach(inputItem => {
 
+    // A DOM Node (Element, DocumentFragment, ...) passed directly: inserted as-is,
+    // bypassing element creation and config parsing entirely.
+    if (inputItem instanceof Node) {
+
+      elaboratedStructureArray.push(/** @type {DomBuilderItem} */ (/** @type {unknown} */ (inputItem)));
+
+      if (target) {
+        if (options.insertMode === 'before') {
+          const anchor = /** @type {HTMLElement} */ (target);
+          anchor.parentNode?.insertBefore(inputItem, anchor);
+
+        } else if (options.insertMode === 'after') {
+          const anchor = afterAnchors.get(/** @type {HTMLElement} */ (target)) ?? /** @type {HTMLElement} */ (target);
+          anchor.parentNode?.insertBefore(inputItem, anchor.nextSibling);
+          afterAnchors.set(/** @type {HTMLElement} */ (target), inputItem);
+
+        } else {
+          target.appendChild(inputItem);
+        }
+      }
+
+      if (mainElement == null && inputItem instanceof Element) {
+        mainElement = /** @type {HTMLElement} */ (inputItem);
+      }
+
+      return;
+    }
+
     /** @type {DomBuilderItem | null} */
     let item;
     if (inputItem != null && typeof inputItem === 'string' && inputItem !== '') {
@@ -232,16 +261,21 @@ export function domBuilder(structureArray = [], parent, options = {}) {
 
         } else {
 
-          /** @type {string | Element | null} */
+          /** @type {string | Node | null} */
           let content = null;
           if (typeof safeItem.content === 'function') {
             content = safeItem.content();
 
+          } else if (safeItem.content instanceof Node) {
+            content = safeItem.content;
+
           } else if (safeItem.content != null) {
             content = String(safeItem.content);
           }
 
-          if (content instanceof Element) {
+          if (content instanceof Node) {
+            // Element, DocumentFragment, Text, ... appended as-is (a DocumentFragment's
+            // children are moved into `el`, emptying the fragment, per native DOM behavior)
             el.appendChild(content);
 
           } else if (content != null) {