@massimo-cassandro/minimo 1.42.4 → 1.43.0

package/README.md

@@ -2,6 +2,8 @@
 
 Il mio framework leggero + utilità
 
+Demo: <https://massimo-cassandro.github.io/minimo/>
+
 ## Installazione
 
 ```bash

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

@@ -39,6 +39,21 @@ if [ -z "$ZSH_VERSION" ]; then
   exit 1
 fi
 
+# Package manager da utilizzare per l'installazione dei pacchetti: 1 = pnpm
+# (default), 2 = npm. Il valore viene usato più sotto (sezione NODE MODULES)
+# per scegliere il comando di installazione.
+read "PM_INPUT?Package manager da utilizzare (1 = pnpm, 2 = npm) [1]: "
+PM_INPUT=${PM_INPUT:-1}
+case "$PM_INPUT" in
+  1) PKG_MANAGER="pnpm" ;;
+  2) PKG_MANAGER="npm" ;;
+  *)
+    printf "${RED}Errore: inserire 1 (pnpm) oppure 2 (npm).${NC}\n" >&2
+    exit 1
+    ;;
+esac
+echo -e "${DIM}Package manager: ${PKG_MANAGER}${NC}"
+
 # Porta da utilizzare: l'utente inserisce un numero da 0 a 99 (default 0), che
 # viene normalizzato a due cifre e usato come suffisso delle porte 80xx e 57xx.
 # I valori sostituiscono i segnaposto [[port8000]] e [[port5700]] presenti in
@@ -65,9 +80,10 @@ echo -e "${DIM}Porte: ${PORT_8000} (server), ${PORT_5700} (webpack dev server)${
 # La colonna <pacchetto> può contenere più pacchetti separati da spazio: in tal
 # caso vengono proposti con un'unica domanda e, se confermati, installati tutti
 # (uno per uno) con la stessa modalità indicata dalla colonna <dev>.
-# La colonna <dev> vale "dev" se il pacchetto va installato con `npm i -D`
-# (devDependency), stringa vuota se va installato con `npm i -S` (dependency
-# vera, es. peer dependency di minimo usata a runtime).
+# La colonna <dev> vale "dev" se il pacchetto va installato come
+# devDependency (`npm i -D` / `pnpm add -D`), stringa vuota se va installato
+# come dependency vera (`npm i -S` / `pnpm add`, es. peer dependency di minimo
+# usata a runtime).
 optionalPackages=(
   "dotenv-webpack                                    | dev | gestione variabili d'ambiente (.env) nel bundle webpack"
   "@principalstudio/html-webpack-inject-preload      | dev | injection dei tag <link rel=preload> nell'html generato"
@@ -286,7 +302,7 @@ echo -e "${GREEN}Files will be installed in: '${FRONTEND_INSTALL_PATH}'${NC}"
 
 
 # package.json va creato dal template PRIMA di installare qualunque pacchetto:
-# se non esistesse ancora, i comandi `npm i` più sotto ne genererebbero uno
+# se non esistesse ancora, i comandi di installazione più sotto ne genererebbero uno
 # "al volo" privo di scripts/metadati del template, e le dipendenze verrebbero
 # registrate lì; alla successiva install_tree su source_files/root (più sotto)
 # quel package.json risulterebbe diverso dal template e verrebbe spostato in
@@ -352,14 +368,24 @@ if [ "$DEBUG" = "TRUE" ]; then
   devDependencies=()
 fi
 
+# comandi di installazione in base al package manager scelto a inizio script:
+# pnpm add -D / pnpm add (dependency), npm i -D / npm i -S
+if [ "$PKG_MANAGER" = "pnpm" ]; then
+  INSTALL_DEV_CMD=(pnpm add -D)
+  INSTALL_DEP_CMD=(pnpm add)
+else
+  INSTALL_DEV_CMD=(npm i -D)
+  INSTALL_DEP_CMD=(npm i -S)
+fi
+
 for pkg in "${devDependencies[@]}"; do
   echo -e "${DIM}...installing "$pkg"${NC}"
-  npm i -D "$pkg"
+  "${INSTALL_DEV_CMD[@]}" "$pkg"
 done
 
 for pkg in "${dependencies[@]}"; do
   echo -e "${DIM}...installing "$pkg"${NC}"
-  npm i -S "$pkg"
+  "${INSTALL_DEP_CMD[@]}" "$pkg"
 done
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.42.4",
+  "version": "1.43.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./src/index.js",
@@ -22,6 +22,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "workspaces": [
+    "demo",
+    "dev-tools-web-apps"
+  ],
   "bin": {
     "buildTokens": "dev-tools/design-tokens-builder/build-tokens.mjs",
     "checkUnresolvedProps": "dev-tools/design-tokens-builder/check-unresolved-custom-props.mjs",
@@ -48,9 +52,9 @@
     "test sideEffects tree-shaking": "node ./test/sideEffects-tree-shaking/run-test.mjs",
     "checkJS": "npx tsc --noEmit -p jsconfig.json",
     "checkJS ./src": "npx tsc --noEmit --allowJs --checkJs --target ES2023 --module ESNext --allowSyntheticDefaultImports --moduleResolution bundler declarations.d.ts types/global.d.ts src/**/*.js",
-    "npm outdated": "echo '*** ROOT ***' && npm outdated --omit=peer && echo '*** DEMO ***' && npm --prefix ./demo outdated && echo '*** END ***'",
+    "npm outdated": "npm outdated --omit=peer",
     "upd@m": "npx upd@m",
-    "npm upd": "echo '*** ROOT ***' && npm update && echo '*** DEMO ***' && npm --prefix ./demo update && echo '*** END ***'"
+    "npm upd": "npm update"
   },
   "license": "MIT",
   "author": "Massimo Cassandro",
@@ -97,7 +101,7 @@
     }
   },
   "devDependencies": {
-    "@massimo-cassandro/eslint-config": "^3.0.18",
+    "@massimo-cassandro/eslint-config": "^3.0.19",
     "@types/node": "^26.2.0",
     "jsdom": "^30.0.1",
     "style-dictionary": "^5.5.1"
@@ -124,5 +128,7 @@
     "doc": "docs",
     "test": "test"
   },
-  "keywords": []
+  "allowScripts": {
+    "fsevents@2.3.3": true
+  }
 }

package/src/index.js

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

package/src/utilities/dom-builder-helpers/table-tag.js

@@ -0,0 +1,259 @@
+
+/**
+ * @typedef {string | number | Node | Function | DomBuilderItem | DomBuilderItem[] | null} TableCellContent
+ * Contenuto di una cella: testo, stringa html, `Node`, funzione che restituisce una stringa o un `Node`,
+ * singolo oggetto domBuilder o array di oggetti domBuilder.
+ */
+
+/**
+ * @typedef {Object} TableCell
+ * @property {string | string[] | null} [class=null] - Classname della cella (default: null)
+ * @property {TableCellContent} [content=null] - Contenuto della cella: testo, html, `Node`, funzione, oggetto o array domBuilder (default: null)
+ * @property {boolean} [heading=false] - La cella è un th? (NB: parametro ignorato nel thead, dove è sempre true) (default: false)
+ * @property {Record<string, any>} [attrs] - Attributi opzionali della cella (default: null)
+ */
+
+/**
+ * @typedef {string | number | Node | Function | DomBuilderItem[] | TableCell | null} TableCellInput
+ * Cella in forma abbreviata o estesa: stringa, numero, `Node`, funzione o array domBuilder sono interpretati come
+ * `content`; un oggetto semplice è un `TableCell` esteso. Per usare un singolo oggetto domBuilder come contenuto
+ * indicarlo in forma estesa: `{ content: { tag: ... } }`.
+ */
+
+/**
+ * @typedef {Object} TableRow
+ * @property {string | string[] | null} [class=null] - Classname del tr (default: null)
+ * @property {Record<string, any>} [attrs] - Attributi opzionali del tr (default: null)
+ * @property {TableCellInput[]} cells - Celle della riga.
+ */
+
+/**
+ * @typedef {TableCellInput[] | TableRow} TableRowInput
+ * Riga in forma abbreviata (array di celle) o estesa (oggetto `TableRow`).
+ */
+
+/**
+ * @typedef {Object} TableSection
+ * @property {string | string[] | null} [class=null] - Classname della sezione (thead, tbody o tfoot) (default: null)
+ * @property {Record<string, any>} [attrs] - Attributi opzionali della sezione (default: null)
+ * @property {TableRowInput[]} [rows] - Righe della sezione.
+ * @property {TableCellInput[]} [cells] - Scorciatoia per una sezione con una sola riga (ignorata se è presente `rows`).
+ */
+
+/**
+ * @typedef {TableCellInput[] | TableRowInput[] | TableSection} TableSectionInput
+ * Sezione in forma abbreviata o estesa:
+ * - array piatto di celle → una sola riga
+ * - array di righe (ogni riga è un array di celle o un oggetto `{ cells }`)
+ * - oggetto `TableSection` con `rows` oppure `cells`
+ *
+ * NB: un array è interpretato come array di righe se il primo elemento è a sua volta un array
+ * o un oggetto con la proprietà `cells`. Per una singola riga il cui primo contenuto è un array domBuilder
+ * usare la forma estesa `{ content: [...] }`.
+ */
+
+
+/**
+ * Normalizza il contenuto di una cella: un singolo oggetto domBuilder viene racchiuso in un array,
+ * dato che `domBuilder` accetta come `content` solo stringhe, numeri, `Node`, funzioni e array.
+ *
+ * @param {TableCellContent} [content]
+ * @returns {string | number | Node | Function | DomBuilderItem[] | null}
+ */
+function normalizeCellContent(content = null) {
+  if (content != null && typeof content === 'object' && !Array.isArray(content) && !(content instanceof Node)) {
+    return [content];
+  }
+  return content ?? null;
+}
+
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} `true` per un oggetto semplice (non `null`, non array, non `Node`).
+ */
+function isPlainObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Node);
+}
+
+
+/**
+ * Porta una cella in forma estesa.
+ *
+ * @param {TableCellInput} cell
+ * @returns {TableCell}
+ */
+function normalizeCell(cell) {
+  return isPlainObject(cell)
+    ? /** @type {TableCell} */ (cell)
+    : { content: /** @type {TableCellContent} */ (cell) };
+}
+
+
+/**
+ * Porta una riga in forma estesa.
+ *
+ * @param {TableRowInput} row
+ * @returns {TableRow}
+ */
+function normalizeRow(row) {
+  return Array.isArray(row)
+    ? { cells: row }
+    : row;
+}
+
+
+/**
+ * Porta una sezione in forma estesa (`{ class, attrs, rows: [{ cells }] }`).
+ *
+ * @param {TableSectionInput} section
+ * @returns {{ class?: string | string[] | null, attrs?: Record<string, any>, rows: TableRow[] }}
+ */
+function normalizeSection(section) {
+
+  if (Array.isArray(section)) {
+    const first = section[0];
+    const isRowsArray = Array.isArray(first) || (isPlainObject(first) && 'cells' in /** @type {object} */ (first));
+
+    return {
+      rows: isRowsArray
+        ? /** @type {TableRowInput[]} */ (section).map(normalizeRow)
+        : [{ cells: /** @type {TableCellInput[]} */ (section) }]
+    };
+  }
+
+  const { rows, cells, ...rest } = section;
+
+  return {
+    ...rest,
+    rows: (rows ?? (cells ? [{ cells }] : [])).map(normalizeRow)
+  };
+}
+
+
+/**
+ * Costruisce l'item domBuilder di una sezione della tabella (thead, tbody o tfoot).
+ *
+ * @param {'thead' | 'tbody' | 'tfoot'} tag
+ * @param {TableSectionInput | null} sectionInput
+ * @returns {DomBuilderItem | null} `null` se la sezione non è definita.
+ */
+function buildSection(tag, sectionInput) {
+
+  if (sectionInput == null) {
+    return null;
+  }
+
+  const section = normalizeSection(sectionInput);
+  const isHead = tag === 'thead';
+
+  return {
+    tag,
+    class: section.class ?? undefined,
+    attrs: section.attrs,
+    children: section.rows.map(row => ({
+      tag: 'tr',
+      class: row.class ?? undefined,
+      attrs: row.attrs,
+      children: (row.cells ?? []).map(cellInput => {
+
+        const cell = normalizeCell(cellInput);
+        const isTh = isHead || cell.heading === true;
+
+        return {
+          tag: isTh ? 'th' : 'td',
+          class: cell.class ?? undefined,
+          attrs: {
+            // scope: sempre `col` nel thead, `row` per i th di tbody/tfoot (sovrascrivibile da `attrs`)
+            ...(isTh && !isHead ? { scope: 'row' } : {}),
+            ...(cell.attrs ?? {}),
+            ...(isHead ? { scope: 'col' } : {})
+          },
+          content: normalizeCellContent(cell.content)
+        };
+      })
+    }))
+  };
+}
+
+
+/**
+ * Table builder
+ * Restituisce un oggetto domBuilder per una tabella.
+ *
+ * Ogni sezione (`thead`, `tbody`, `tfoot`) accetta sia una forma abbreviata sia una estesa:
+ * - cella: stringa, numero, `Node`, funzione o array domBuilder (= `content`), oppure oggetto `{ content, class, attrs, heading }`
+ * - riga: array di celle, oppure oggetto `{ cells, class, attrs }`
+ * - sezione: array piatto di celle (una sola riga), array di righe, oppure oggetto `{ rows | cells, class, attrs }`
+ *
+ * @param {Object} args
+ * @param {string | string[]} [args.classname='table'] - Classe del tag table (default: 'table')
+ * @param {Record<string, any>} [args.attrs] - Oggetto opzionale di attributi del tag table (default: null)
+ * @param {TableSectionInput | null} [args.thead=null] - Oggetto opzionale per il tag thead (default: null)
+ * @param {TableSectionInput | null} [args.tbody=null] - Oggetto opzionale per il tag tbody (default: null)
+ * @param {TableSectionInput | null} [args.tfoot=null] - Oggetto opzionale per il tag tfoot (default: null)
+ *
+ * @example
+ * buildTableTag({
+ *   classname: 'table', // default: 'table'
+ *   attrs: { id: 'my-table' }, // default: null
+ *
+ *   // array piatto di celle: una sola riga (caso più comune)
+ *   thead: ['Nome', 'Email', { content: 'Importo', class: 'text-end' }],
+ *
+ *   // array di righe; ogni riga è un array di celle o un oggetto { cells }
+ *   tbody: [
+ *     [
+ *       { content: 'Mario', heading: true }, // th scope="row"
+ *       'mario@x.it', // testo
+ *       { content: '<strong>10</strong>', class: 'text-end' }, // html
+ *       { content: { tag: 'a', attrs: { href: '#' }, content: 'dettagli' } } // singolo oggetto domBuilder
+ *     ],
+ *     {
+ *       class: 'is-selected',
+ *       attrs: { 'data-id': 2 },
+ *       cells: [
+ *         'Anna',
+ *         'anna@x.it',
+ *         '12',
+ *         [{ tag: 'em', content: 'a' }, { tag: 'em', content: 'b' }] // array domBuilder
+ *       ]
+ *     }
+ *   ],
+ *
+ *   // forma estesa della sezione: { class, attrs, rows | cells }
+ *   tfoot: { class: 'table-light', cells: ['Totale', '', '', { content: '22', class: 'text-end' }] }
+ *   // oppure: tfoot: null (default)
+ * });
+ *
+ * @example
+ * // thead con più righe (es. colspan nella prima)
+ * buildTableTag({
+ *   thead: [
+ *     [{ content: 'Contatti', attrs: { colspan: 2 } }, 'Importo'],
+ *     ['Nome', 'Email', 'Importo']
+ *   ]
+ * });
+ *
+ * @returns {DomBuilderItem} L'item domBuilder del tag `table`.
+ */
+export function buildTableTag({
+  classname = 'table',
+  attrs,
+  thead = null,
+  tbody = null,
+  tfoot = null
+} = {}) {
+
+  return {
+    tag: 'table',
+    class: classname,
+    attrs: attrs,
+    children: [
+      buildSection('thead', thead),
+      buildSection('tbody', tbody),
+      buildSection('tfoot', tfoot)
+    ].filter(/** @returns {item is DomBuilderItem} */ item => item != null)
+  };
+
+}