@massimo-cassandro/minimo 1.32.4 → 1.33.0

package/src/web-components/json-table/src/defaults.js

@@ -0,0 +1,105 @@
+/*! minimo - json-table: defaults */
+
+/**
+ * Function returning the text of the info area.
+ * @callback InfoTextFn
+ * @param {number} shown - Number of rows currently displayed
+ * @param {number} total - Total number of rows in the data set
+ * @returns {string|Node} Plain text, an HTML string or a DOM node
+ */
+
+/**
+ * `<json-table>` parameters.
+ *
+ * Every parameter can be set either as an HTML attribute of the `<json-table>` element
+ * (attribute names are case-insensitive, so `jsonurl="…"` and `jsonUrl="…"` are equivalent)
+ * or as a property of the object passed to `init()`. Values that are functions
+ * (e.g. `caption`, `infoText`) can only be set via `init()`.
+ *
+ * Precedence: `init()` > HTML attribute > `JsonTable.setDefaults()` > built-in default.
+ *
+ * TODO parametri `cols`, data-types, locale, icone, ordinamento, paginazione: da aggiungere negli step successivi
+ *
+ * @typedef {Object} JsonTableParams
+ * @property {boolean} [debug] - Logs resolved params and generated elements to the console (default: false)
+ * @property {string|null} [jsonUrl] - URL of the JSON to fetch. Ignored when `data` is set (default: null)
+ * @property {string|null} [jsonDataField] - Key of the fetched JSON holding the rows array (e.g. `{ data: [...] }`);
+ *   `null` or an empty string means the JSON root is the rows array itself (default: 'data')
+ * @property {Array<Object>|null} [data] - Inline rows (array of plain objects); takes precedence over `jsonUrl`.
+ *   As an HTML attribute it must be a JSON string, which is always treated as the rows array itself
+ *   (`jsonDataField` is ignored) (default: null)
+ * @property {string|Function|null} [caption] - Table caption: a string (plain text or HTML) or, via `init()` only,
+ *   a function returning a string or a Node (default: null)
+ * @property {boolean} [search] - Whether to render the search input (default: true)
+ * @property {string|null} [searchInputClass] - Class(es) of the search input, replacing the default one (default: 'form-control')
+ * @property {string} [searchInputTitle] - `title` attribute of the search input (default: 'Filtra record: inserisci un termine per eseguire la ricerca')
+ * @property {string} [searchInputPlaceholder] - Placeholder of the search input (default: 'Inserisci il termine da cercare')
+ * @property {string} [searchInputAriaLabel] - `aria-label` of the search input (default: 'Filtra risultati')
+ * @property {string|null} [tableId] - `id` attribute of the `<table>` element (default: null)
+ * @property {string|null} [tableWrapperClass] - Class(es) of the div wrapping the table, replacing the default one (default: 'table-responsive')
+ * @property {string|null} [tableClass] - Class(es) of the `<table>` element, replacing the default ones (default: 'table table-bordered')
+ * @property {string|null} [mainWrapperExtraClass] - Extra class(es) added to the main wrapper (info section + table) (default: null)
+ * @property {string|null} [outerInfoExtraClass] - Extra class(es) added to the outer info container (default: null)
+ * @property {string|null} [infoExtraClass] - Extra class(es) added to the info container (default: null)
+ * @property {InfoTextFn} [infoText] - Function returning the info text: plain text, an HTML string or a Node
+ *   (default: Italian text "Visualizzate N righe su M" / "Nessun record")
+ */
+
+/**
+ * Built-in defaults.
+ *
+ * @type {Required<JsonTableParams>}
+ *
+ * @example
+ * {
+ *   debug: false,
+ *   jsonUrl: null,
+ *   jsonDataField: 'data',
+ *   data: null,
+ *   caption: null,
+ *   search: true,
+ *   searchInputClass: 'form-control',
+ *   searchInputTitle: 'Filtra record: inserisci un termine per eseguire la ricerca',
+ *   searchInputPlaceholder: 'Inserisci il termine da cercare',
+ *   searchInputAriaLabel: 'Filtra risultati',
+ *   tableId: null,
+ *   tableWrapperClass: 'table-responsive',
+ *   tableClass: 'table table-bordered',
+ *   mainWrapperExtraClass: null,
+ *   outerInfoExtraClass: null,
+ *   infoExtraClass: null,
+ *   infoText: (shown, total) => '…'
+ * }
+ */
+export const defaults = {
+  debug: false,
+
+  jsonUrl: null,
+  jsonDataField: 'data',
+  data: null,
+
+  caption: null,
+
+  search: true,
+  searchInputClass: 'form-control',
+  searchInputTitle: 'Filtra record: inserisci un termine per eseguire la ricerca',
+  searchInputPlaceholder: 'Inserisci il termine da cercare',
+  searchInputAriaLabel: 'Filtra risultati',
+
+  tableId: null,
+  tableWrapperClass: 'table-responsive',
+  tableClass: 'table table-bordered',
+
+  mainWrapperExtraClass: null,
+  outerInfoExtraClass: null,
+  infoExtraClass: null,
+
+  infoText: (shown, total) => {
+    if (total === 0) {
+      return 'Nessun record';
+    }
+    return shown === 1
+      ? `Visualizzata <strong>${shown}</strong> riga su <strong>${total}</strong>`
+      : `Visualizzate <strong>${shown}</strong> righe su <strong>${total}</strong>`;
+  }
+};

package/src/web-components/json-table/src/get-data.js

@@ -0,0 +1,57 @@
+/*! minimo - json-table: data acquisition */
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+
+/**
+ * Retrieves the rows array from the configured source.
+ *
+ * `data` takes precedence over `jsonUrl`. With `jsonUrl` the JSON is fetched and the rows are
+ * read from the `jsonDataField` key (`null`/`''` = the JSON root is the array itself).
+ * Returns `null` when no source is configured.
+ *
+ * @param {JsonTableParams} params - Resolved params (see `resolve-params.js`)
+ * @returns {Promise<Array<Object>|null>} The rows array, or `null` when neither `data` nor `jsonUrl` is set
+ * @throws {Error} When `data` is not an array, on HTTP/network errors, or when the fetched JSON
+ *   does not contain an array at `jsonDataField`
+ *
+ * @example
+ * // inline data (jsonUrl ignored)
+ * await getData({ ...params, data: [{ id: 1 }], jsonUrl: '/ignored.json' }); // → [{ id: 1 }]
+ *
+ * // fetched JSON: { data: [...] }  (jsonDataField default: 'data')
+ * await getData({ ...params, jsonUrl: '/api/rows.json' });
+ *
+ * // fetched JSON whose root is the array itself
+ * await getData({ ...params, jsonUrl: '/api/rows.json', jsonDataField: null });
+ */
+export async function getData(params) {
+
+  if (params.data != null) {
+    if (!Array.isArray(params.data)) {
+      throw new Error('[json-table] `data` deve essere un array di oggetti');
+    }
+    return params.data;
+  }
+
+  if (params.jsonUrl) {
+    const response = await fetch(params.jsonUrl);
+
+    if (!response.ok) {
+      throw new Error(`[json-table] ${params.jsonUrl}: risposta HTTP ${response.status}`);
+    }
+
+    const json = await response.json();
+    const field = params.jsonDataField;
+    const rows = (field == null || field === '') ? json : json?.[field];
+
+    if (!Array.isArray(rows)) {
+      throw new Error(
+        `[json-table] ${params.jsonUrl}: ` +
+        (field ? `il campo \`${field}\` non contiene un array` : 'la risposta non è un array')
+      );
+    }
+    return rows;
+  }
+
+  return null;
+}

package/src/web-components/json-table/src/info-section.js

@@ -0,0 +1,72 @@
+/*! minimo - json-table: info section */
+
+import * as styles from '../json-table-component.module.css';
+import { classnames } from '../../../utilities/classnames.js';
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./main-builder.js').JsonTableElements} JsonTableElements */
+
+/**
+ * Builds the domBuilder configuration of the info section (info text + search input).
+ *
+ * Generated structure:
+ * ```
+ * div.infoOuter[outerInfoExtraClass]
+ *   div.info[infoExtraClass]
+ *     div.resultInfo                       ← info text (see `update-info.js`)
+ *     div.search > input[type=search]      ← only if `params.search` is true
+ * ```
+ *
+ * References to the generated elements are stored in `elements`
+ * (`infoOuter`, `info`, `resultInfo`, `searchInput`).
+ *
+ * TODO listener sull'input di ricerca: da impostare quando verrà implementata la ricerca
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @returns {DomBuilderItem[]} domBuilder items to be used as children of the main wrapper
+ *
+ * @example
+ * const elements = {};
+ * domBuilder([{ tag: 'section', children: [...infoSection(params, elements)] }], host);
+ * elements.searchInput; // → HTMLInputElement (when params.search is true)
+ */
+export function infoSection(params, elements) {
+
+  return [
+    {
+      className: classnames(styles.infoOuter, params.outerInfoExtraClass),
+      callback: el => { elements.infoOuter = /** @type {HTMLElement} */ (el); },
+      children: [
+        {
+          className: classnames(styles.info, params.infoExtraClass),
+          callback: el => { elements.info = /** @type {HTMLElement} */ (el); },
+          children: [
+            {
+              className: styles.resultInfo,
+              attrs: { 'aria-live': 'polite' },
+              callback: el => { elements.resultInfo = /** @type {HTMLElement} */ (el); }
+            },
+            {
+              condition: params.search,
+              className: styles.search,
+              children: [
+                {
+                  tag: 'input',
+                  className: classnames(params.searchInputClass),
+                  attrs: {
+                    type: 'search',
+                    title: params.searchInputTitle,
+                    placeholder: params.searchInputPlaceholder,
+                    'aria-label': params.searchInputAriaLabel
+                  },
+                  callback: el => { elements.searchInput = /** @type {HTMLInputElement} */ (el); }
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ];
+}

package/src/web-components/json-table/src/main-builder.js

@@ -0,0 +1,95 @@
+/*! minimo - json-table: main structure builder */
+
+import * as styles from '../json-table-component.module.css';
+import { domBuilder } from '../../../utilities/dom-builder/dom-builder.js';
+import { classnames } from '../../../utilities/classnames.js';
+import { infoSection } from './info-section.js';
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+
+/**
+ * Elements generated by the component, collected during the build.
+ * @typedef {Object} JsonTableElements
+ * @property {HTMLElement} [wrapper] - Main wrapper (`section`), contains info section and table
+ * @property {HTMLElement} [infoOuter] - Outer info container
+ * @property {HTMLElement} [info] - Info container (flex row: info text + search)
+ * @property {HTMLElement} [resultInfo] - Info text container
+ * @property {HTMLInputElement} [searchInput] - Search input (only when `search` is true)
+ * @property {HTMLElement} [tableWrapper] - Div wrapping the table (`table-responsive` by default)
+ * @property {HTMLTableElement} [table] - The `<table>` element
+ */
+
+/**
+ * Builds the whole component structure inside `host` (emptied first) via domBuilder.
+ *
+ * Generated structure:
+ * ```
+ * section.wrapper[mainWrapperExtraClass]
+ *   div.infoOuter[outerInfoExtraClass]
+ *     div.info[infoExtraClass]
+ *       div.resultInfo
+ *       div.search > input[type=search]     (if `search`)
+ *   div[tableWrapperClass]
+ *     table#tableId[tableClass]
+ *       caption                             (if `caption`)
+ * ```
+ *
+ * TODO thead / tbody / tfoot: step successivo (parametro `cols` e rendering delle righe)
+ *
+ * @param {HTMLElement} host - The `<json-table>` element
+ * @param {JsonTableParams} params - Resolved params
+ * @returns {JsonTableElements} References to the generated elements
+ *
+ * @example
+ * const elements = mainBuilder(el, {
+ *   ...defaults,
+ *   caption: 'Utenti',                  // default: null
+ *   search: true,                       // default: true
+ *   tableId: 'users-table',             // default: null
+ *   tableWrapperClass: 'table-responsive', // default: 'table-responsive'
+ *   tableClass: 'table table-bordered', // default: 'table table-bordered'
+ *   mainWrapperExtraClass: null,        // default: null
+ *   outerInfoExtraClass: null,          // default: null
+ *   infoExtraClass: null                // default: null
+ * });
+ * elements.table; // → HTMLTableElement
+ */
+export function mainBuilder(host, params) {
+
+  /** @type {JsonTableElements} */
+  const elements = {};
+
+  domBuilder([
+    {
+      tag: 'section',
+      className: classnames(styles.wrapper, params.mainWrapperExtraClass),
+      callback: el => { elements.wrapper = /** @type {HTMLElement} */ (el); },
+      children: [
+
+        ...infoSection(params, elements),
+
+        {
+          className: classnames(params.tableWrapperClass),
+          callback: el => { elements.tableWrapper = /** @type {HTMLElement} */ (el); },
+          children: [
+            {
+              tag: 'table',
+              id: params.tableId,
+              className: classnames(styles.table, params.tableClass),
+              callback: el => { elements.table = /** @type {HTMLTableElement} */ (el); },
+              children: [
+                {
+                  tag: 'caption',
+                  condition: params.caption != null,
+                  content: params.caption
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ], host, { emptyParent: true });
+
+  return elements;
+}

package/src/web-components/json-table/src/resolve-params.js

@@ -0,0 +1,96 @@
+/*! minimo - json-table: params resolution */
+
+import { defaults } from './defaults.js';
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+
+/**
+ * Resolves a single parameter, merging the four possible sources.
+ *
+ * Precedence (highest first):
+ * 1. `config` – value passed via `init()`/`reload()`. Present and `!== undefined` always wins;
+ *    pass `null` explicitly to skip the HTML attribute and fall back to the defaults.
+ * 2. HTML attribute – booleans are auto-parsed when the built-in default is a boolean
+ *    (`search`, `search="true"`, `search="1"` → true; `search="false"`, `search="0"` → false);
+ *    values starting with `[` or `{` are parsed as JSON (invalid JSON is reported in the
+ *    console and ignored, falling back to the defaults).
+ * 3. `projectDefaults` – values set via `JsonTable.setDefaults()`.
+ * 4. Built-in default (see `defaults.js`).
+ *
+ * @param {HTMLElement} el - The `<json-table>` element (source of the HTML attributes)
+ * @param {Partial<JsonTableParams>|null} config - Config passed via `init()` (default: null)
+ * @param {Partial<JsonTableParams>} projectDefaults - Project-wide defaults (default: {})
+ * @param {keyof JsonTableParams} name - Parameter name
+ * @returns {*} The resolved value
+ *
+ * @example
+ * // <json-table jsonurl="/api/rows.json" search="false"></json-table>
+ * getParam(el, { jsonUrl: '/api/other.json' }, {}, 'jsonUrl'); // → '/api/other.json' (config)
+ * getParam(el, null, {}, 'search');                             // → false (attribute)
+ * getParam(el, null, { tableClass: 'table' }, 'tableClass');    // → 'table' (project defaults)
+ * getParam(el, null, {}, 'tableWrapperClass');                  // → 'table-responsive' (built-in default)
+ */
+export function getParam(el, config = null, projectDefaults = {}, name) {
+
+  // 1. config from script (undefined = key not present → go down one level)
+  if (config && config[name] !== undefined) {
+    return config[name];
+  }
+
+  // 2. HTML attribute
+  const attr = el.getAttribute(name);
+  if (attr !== null) {
+    const trimmed = attr.trim();
+
+    if (typeof defaults[name] === 'boolean') {
+      const lower = trimmed.toLowerCase();
+      // empty string = attribute present without value → true (standard HTML)
+      return lower !== 'false' && lower !== '0';
+    }
+
+    if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+      try {
+        return JSON.parse(trimmed);
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error(`[json-table] attributo \`${name}\`: JSON non valido, valore ignorato (viene usato il default)`, err);
+        // fall through to the defaults
+      }
+    } else {
+      return attr;
+    }
+  }
+
+  // 3. project defaults
+  if (projectDefaults[name] !== undefined) {
+    return projectDefaults[name];
+  }
+
+  // 4. built-in default
+  return defaults[name];
+}
+
+
+/**
+ * Resolves every parameter defined in `defaults.js` (see `getParam` for the precedence rules).
+ *
+ * @param {HTMLElement} el - The `<json-table>` element
+ * @param {Partial<JsonTableParams>|null} [config=null] - Config passed via `init()` (default: null)
+ * @param {Partial<JsonTableParams>} [projectDefaults={}] - Project-wide defaults (default: {})
+ * @returns {JsonTableParams} The complete params object
+ *
+ * @example
+ * const params = resolveParams(el, { jsonUrl: '/api/rows.json', debug: true }, {});
+ * // → { debug: true, jsonUrl: '/api/rows.json', jsonDataField: 'data', data: null, ... }
+ */
+export function resolveParams(el, config = null, projectDefaults = {}) {
+
+  const params = Object.fromEntries(
+    Object.keys(defaults).map(name => [
+      name,
+      getParam(el, config, projectDefaults, /** @type {keyof JsonTableParams} */ (name))
+    ])
+  );
+
+  return /** @type {JsonTableParams} */ (params);
+}

package/src/web-components/json-table/src/update-info.js

@@ -0,0 +1,48 @@
+/*! minimo - json-table: info text update */
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./main-builder.js').JsonTableElements} JsonTableElements */
+
+/**
+ * Updates the info text (`elements.resultInfo`) using `params.infoText(shown, total)`.
+ *
+ * The returned value can be a Node (appended as-is), a plain string (set as `textContent`)
+ * or an HTML string (sanitized via `Element.setHTML` where supported, `innerHTML` otherwise,
+ * consistently with domBuilder).
+ *
+ * @param {JsonTableElements} elements - Generated elements (see `main-builder.js`)
+ * @param {JsonTableParams} params - Resolved params
+ * @param {number} shown - Number of rows currently displayed
+ * @param {number} total - Total number of rows in the data set
+ * @returns {void}
+ *
+ * @example
+ * updateInfo(elements, params, 25, 100);
+ * // with the default `infoText` → "Visualizzate <strong>25</strong> righe su <strong>100</strong>"
+ */
+export function updateInfo(elements, params, shown, total) {
+
+  const target = elements.resultInfo;
+  if (!target) {
+    return;
+  }
+
+  const content = params.infoText(shown, total);
+
+  if (content instanceof Node) {
+    target.replaceChildren(content);
+    return;
+  }
+
+  const text = String(content ?? '');
+
+  if (!text.includes('<')) {
+    target.textContent = text;
+
+  } else if (typeof target.setHTML === 'function') {
+    target.setHTML(text);
+
+  } else {
+    target.innerHTML = text;
+  }
+}

package/src/web-components/s-datatable-component/docs.md

@@ -176,6 +176,68 @@ document.dispatchEvent(new CustomEvent('datatable:search', {
 }));
 ```
 
+## Parametri/attributi
+
+Tutti i parametri sono leggibili sia da attributo HTML che da script (`init()`).
+Ordine di precedenza: config (script) > attributo HTML > default interno.
+
+### Parametri del componente
+
+```javascript
+{
+  json,          // URL da cui recuperare i dati (struttura attesa: { data: [...] }).
+                 // Ignorato se `data` è presente.
+
+  data,          // Dati inline, array di oggetti plain. Ha precedenza su `json`.
+                 // Utile in contesti SSR (Twig, Blade, ...) dove il JSON è già
+                 // disponibile server-side; per grandi dataset preferire `json`.
+
+  cols,          // Definizione delle colonne. Vedi "Parametro cols" più sotto.
+                 // Default: []
+
+  tableClass,    // Classi CSS del tag <table>, in sostituzione di 'table table-bordered'.
+                 // La classe interna styles.table (necessaria al layout) viene
+                 // comunque sempre applicata.
+                 // Default: 'table table-bordered'
+
+  renderNullAs,  // Stringa globale da mostrare al posto di valori null/undefined,
+                 // sovrascrivibile per singola colonna con `_renderNullAs`.
+                 // Default: '—' (em dash)
+
+  updateFooterOnPageChange, // Se true, `_footerRender` riceve solo i record della
+                 // pagina corrente (subtotale). Se false, l'intero set filtrato
+                 // (il footer si aggiorna solo al cambio filtro, non pagina).
+                 // Default: false
+
+  refs,          // string[] di percorsi URL da cui, se si proviene, la pagina
+                 // corrente viene ripristinata dal cookie di sessione 'sd-pag'.
+                 // Confronto su pathname (query string/hash ignorati): es. ['/utenti']
+                 // intercetta anche '/utenti/1234'.
+
+  topSlot,       // Elemento DOM o markup HTML nell'area in alto a sinistra.
+                 // Solo via init() (non leggibile da attributo HTML). Ignorato
+                 // se showInfoAtTop è true. Vedi sezione dedicata più sotto.
+
+  showInfoAtTop, // Replica il testo dell'area info anche in alto a sinistra.
+                 // Ha priorità su topSlot se true. Vedi sezione dedicata più sotto.
+                 // Default: true
+}
+```
+
+### Parametri nativi di simple-datatables
+
+```javascript
+{
+  perPage,       // Numero di righe per pagina, passato direttamente come opzione
+                 // nativa `perPage` del costruttore DataTable.
+                 // Default: 25
+}
+```
+
+Tutte le altre opzioni native di simple-datatables (`searchable`, `sortable`, `paging`,
+`pagerDelta`, `perPageSelect`, `locale`, `labels`, `classes`, `template`, ...) sono
+impostate internamente dal componente e **non** sono configurabili da attributo/script.
+
 ## Parametro `cols`
 
 Array di oggetti di configurazione delle colonne. Le chiavi con prefisso `_` sono