@massimo-cassandro/minimo 1.25.0 → 1.27.0

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

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/index.js

@@ -20,7 +20,7 @@ export { ValidationError } from './src/utilities/validation-error-class.js';
 
 // domBuilder helpers
 export { buildPictureTag } from './src/utilities/dom-builder-helpers/picture-tag.js';
-export { buildInput, buildCheckbox, buildTextarea, buildFakeField, buildSelect } from './src/utilities/dom-builder-helpers/form-tags.js';
+export { buildInput, buildCheckbox, buildTextarea, buildFakeField, buildSelect, buildButton } from './src/utilities/dom-builder-helpers/form-tags.js';
 
 // components
 export { dismissAlerts } from './src/components/dismiss-alerts.js';

package/package.json

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

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

@@ -25,7 +25,7 @@ import { parseDomString } from './parseDomString.js';
  *   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.
  */
 
 /**
@@ -85,7 +85,7 @@ 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.
@@ -94,7 +94,7 @@ import { parseDomString } from './parseDomString.js';
  * - `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`).
@@ -106,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,
@@ -144,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 !== '') {

package/src/utilities/dom-builder-helpers/form-tags.js

@@ -50,10 +50,12 @@ function buildFormGroup({
  * @param {string | number | null} args.value - input `value` attribute.
  * @param {string | null} [args.type='text'] - input `type` attribute.
  * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
- * @param {string | null} [args.className=null] - optional class to be added to the `input`.
+ * @param {string | null} [args.class=null] - optional class to be added to the `input`.
+ * @param {string | null} [args.classname=null] - Alias for `class`.
+ * @param {string | null} [args.className=null] - Alias for `class`.
  * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
  * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement): void) | null} args.callback - Optional callback function.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
  * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object.
  * @returns {DomBuilderItem|null} The `input` domBuilder item, or `null` when `condition` is false.
  */
@@ -64,13 +66,17 @@ export function buildInput({
   value = null,
   type = 'text',
   wrapperClass = null,
-  className = null,
+  class: classArg = null,
+  classname: classnameArg = null,
+  className: classNameArg = null,
   condition = true,
   help = null,
   attrs = {},
   callback = null
 }){
 
+  const className = classArg ?? classnameArg ?? classNameArg;
+
   id = id || randomId();
 
   return buildFormGroup({
@@ -108,11 +114,13 @@ export function buildInput({
  *    as an array of objects `[{somekey: value, somekey2: text},...]` objects, or as a single `{value: text, ...}` object
  * @param {boolean} [args.addEmptyOption=true] - When true, and empty option tag is added at top
  * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
- * @param {string | null} [args.className=null] - optional class to be added to the `input`.
+ * @param {string | null} [args.class=null] - optional class to be added to the `input`.
+ * @param {string | null} [args.classname=null] - Alias for `class`.
+ * @param {string | null} [args.className=null] - Alias for `class`.
  * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
  * @param {boolean} [args.useBsClass=false] - When true, uses BS5 class (`form-select`) instead of `form-control`
  * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement): void) | null} args.callback - Optional callback function.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
  * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object.
  * @returns {DomBuilderItem|null} The `input` domBuilder item, or `null` when `condition` is false.
  */
@@ -124,7 +132,9 @@ export function buildSelect({
   options = null,
   addEmptyOption = true,
   wrapperClass = null,
-  className = null,
+  class: classArg = null,
+  classname: classnameArg = null,
+  className: classNameArg = null,
   useBsClass = false,
   condition = true,
   help = null,
@@ -132,6 +142,8 @@ export function buildSelect({
   callback = null
 }){
 
+  const className = classArg ?? classnameArg ?? classNameArg;
+
   id = id || randomId();
 
   // normalizing options as an array of [value, text] pairs
@@ -200,7 +212,7 @@ export function buildSelect({
  * @param {boolean} [args.addFormGroup=true] - When true, wraps the checkbox in a `.form-group` element.
  * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
  * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement): void) | null} args.callback - Optional callback function.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
  * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object.
  * @returns {DomBuilderItem|null} The `.form-check` (or `.form-group`-wrapped) domBuilder item, or `null` when `condition` is false.
  */
@@ -286,10 +298,12 @@ export function buildCheckbox({
  * @param {string | number | null} args.value - textarea content.
  * @param {boolean} [args.autosize=true] - adds `autosize` class
  * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
- * @param {string | null} [args.className=null] - optional class to be added to the textarea element.
+ * @param {string | null} [args.class=null] - optional class to be added to the textarea element.
+ * @param {string | null} [args.classname=null] - Alias for `class`.
+ * @param {string | null} [args.className=null] - Alias for `class`.
  * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
  * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement): void) | null} args.callback - Optional callback function.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
  * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object.
  * @returns {DomBuilderItem|null} The `textarea` domBuilder item, or `null` when `condition` is false.
  */
@@ -299,7 +313,9 @@ export function buildTextarea({
   id = null,
   value = null,
   wrapperClass = null,
-  className = null,
+  class: classArg = null,
+  classname: classnameArg = null,
+  className: classNameArg = null,
   condition = true,
   help = null,
   callback = null,
@@ -307,6 +323,8 @@ export function buildTextarea({
   autosize = true
 }) {
 
+  const className = classArg ?? classnameArg ?? classNameArg;
+
   id = id || randomId();
 
   return buildFormGroup({
@@ -338,10 +356,12 @@ export function buildTextarea({
  * @param {string | number | null} args.value - text content.
  * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper.
  * @param {boolean} [args.noBorder=true] - adds `no-border` class.
- * @param {string | null} [args.className=null] - optional class to be added to the fake field.
+ * @param {string | null} [args.class=null] - optional class to be added to the fake field.
+ * @param {string | null} [args.classname=null] - Alias for `class`.
+ * @param {string | null} [args.className=null] - Alias for `class`.
  * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
  * @param {string | HTMLElement | null} args.help - Optional help text.
- * @param {(function(HTMLElement): void) | null} args.callback - Optional callback function.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
  * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object.
  * @returns {DomBuilderItem|null} The fake field domBuilder item, or `null` when `condition` is false.
  */
@@ -349,7 +369,9 @@ export function buildFakeField({
   label,
   value = null,
   wrapperClass = null,
-  className = null,
+  class: classArg = null,
+  classname: classnameArg = null,
+  className: classNameArg = null,
   condition = true,
   help = null,
   callback = null,
@@ -357,6 +379,7 @@ export function buildFakeField({
   noBorder = true
 }) {
 
+  const className = classArg ?? classnameArg ?? classNameArg;
 
   return buildFormGroup({
     condition,
@@ -368,7 +391,6 @@ export function buildFakeField({
         className: classnames('form-control-static', className, attrs?.class, noBorder && 'no-border'),
         attrs: {
           ...(attrs??{}),
-          name: name,
         },
         content: value,
         callback: callback
@@ -376,3 +398,55 @@ export function buildFakeField({
     ]
   });
 }
+
+
+
+/**
+ * button tag builder
+ *
+ * @param {Object} args
+ * @param {string|HTMLElement|Array<DomBuilderItem>} args.content - button content. When an array of
+ *   domBuilder items is passed, it is rendered via `children` instead of `content`.
+ * @param {string} [args.type=button] - button type.
+ * @param {string | null} args.id - `id` attribute.
+ * @param {string | number | null} [args.value=null] - button `value` attribute.
+ * @param {string | null} [args.class=null] - optional class to be added to the button element.
+ * @param {string | null} [args.classname=null] - Alias for `class`.
+ * @param {string | null} [args.className=null] - Alias for `class`.
+ * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
+ * @param {(function(HTMLElement|Text): void) | null} args.callback - Optional callback function.
+ * @param {Record<string, any> | null}  [args.attrs={}] - Optional attributes object.
+ * @returns {DomBuilderItem|null} The `button` domBuilder item, or `null` when `condition` is false.
+ */
+export function buildButton({
+  content,
+  type = 'button',
+  id = null,
+  value = null,
+  class: classArg = null,
+  classname: classnameArg = null,
+  className: classNameArg = null,
+  condition = true,
+  callback = null,
+  attrs = {},
+}) {
+
+  const className = classArg ?? classnameArg ?? classNameArg;
+
+  return {
+    condition: condition,
+    tag: 'button',
+    className: classnames(className, attrs?.class),
+    id: id,
+    attrs: {
+      ...(attrs??{}),
+      type: type,
+      value: value
+    },
+    ...(Array.isArray(content)
+      ? { children: content }
+      : { content: content }
+    ),
+    callback: callback
+  };
+}