@massimo-cassandro/minimo 1.32.4 → 1.33.0

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

@@ -0,0 +1,283 @@
+/*! minimo - json-table */
+
+import { defaults } from './src/defaults.js';
+import { resolveParams } from './src/resolve-params.js';
+import { getData } from './src/get-data.js';
+import { mainBuilder } from './src/main-builder.js';
+import { updateInfo } from './src/update-info.js';
+
+/** @typedef {import('./src/defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./src/main-builder.js').JsonTableElements} JsonTableElements */
+
+/**
+ * Project-wide defaults, set via `JsonTable.setDefaults()`.
+ * Module-level so they are shared by every instance.
+ * @type {Partial<JsonTableParams>}
+ */
+let projectDefaults = {};
+
+
+/**
+ * `<json-table>` – HTML table generator from JSON data (inline or fetched), light DOM custom element.
+ *
+ * WORK IN PROGRESS: at this stage only the outer structure is generated (info section, search
+ * input, empty table with caption). Columns, rows rendering, sorting, search and pagination
+ * are not implemented yet.
+ *
+ * Parameters (see `src/defaults.js` → `JsonTableParams`) can be set as HTML attributes or via
+ * `init()`; precedence: `init()` > HTML attribute > `JsonTable.setDefaults()` > built-in default.
+ *
+ * Events: `jt:ready` (bubbles) is dispatched on the element once the structure has been built;
+ * `event.detail.jsonTable` is the component instance.
+ *
+ * @example
+ * // markup only
+ * // <json-table jsonurl="/api/rows.json" caption="Utenti"></json-table>
+ *
+ * @example
+ * // script
+ * import { JsonTable } from '@massimo-cassandro/minimo/src/web-components/json-table/json-table-component.js';
+ *
+ * JsonTable.setDefaults({ tableClass: 'table' }); // optional, project-wide
+ *
+ * const el = document.querySelector('json-table');
+ * el.addEventListener('jt:ready', e => console.log(e.detail.jsonTable.data));
+ * el.init({
+ *   debug: false,                       // default: false
+ *   jsonUrl: '/api/rows.json',          // default: null
+ *   jsonDataField: 'data',              // default: 'data'
+ *   data: null,                         // default: null (takes precedence over jsonUrl when set)
+ *   caption: 'Utenti',                  // default: null
+ *   search: true,                       // default: true
+ *   searchInputClass: 'form-control',   // default: 'form-control'
+ *   tableId: null,                      // 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
+ *   infoText: (shown, total) => `${shown} / ${total}` // default: Italian "Visualizzate N righe su M"
+ * });
+ */
+export class JsonTable extends HTMLElement {
+
+  /**
+   * Sets project-wide defaults, shared by every instance created afterwards
+   * (instances already rendered are not updated). Call it once, before the instances
+   * are created, e.g. in a shared script. Values are merged with the previous ones.
+   *
+   * @param {Partial<JsonTableParams>} [newDefaults={}] - Parameters to override (default: {})
+   * @returns {void}
+   *
+   * @example
+   * JsonTable.setDefaults({
+   *   searchInputClass: 'form-control form-control-sm', // default: 'form-control'
+   *   tableClass: 'table',                              // default: 'table table-bordered'
+   *   infoText: (shown, total) => `${shown} di ${total}`
+   * });
+   */
+  static setDefaults(newDefaults = {}) {
+    projectDefaults = { ...projectDefaults, ...newDefaults };
+  }
+
+  /**
+   * Clears the project-wide defaults set via `setDefaults()`.
+   * @returns {void}
+   */
+  static resetDefaults() {
+    projectDefaults = {};
+  }
+
+  /**
+   * Returns the built-in defaults merged with the project-wide ones.
+   * @returns {JsonTableParams}
+   *
+   * @example
+   * JsonTable.getDefaults().tableWrapperClass; // → 'table-responsive'
+   */
+  static getDefaults() {
+    return { ...defaults, ...projectDefaults };
+  }
+
+
+  constructor() {
+    super();
+    // light DOM: no attachShadow
+
+    /** @type {Partial<JsonTableParams>|null} config passed via init()/reload() */
+    this._config = null;
+    this._initCalledProgrammatically = false;
+    this._isConnected = false;
+    this._loadStarted = false;
+    /** incremented on every init()/reload()/destroy(): a pending _load() whose generation is stale gives up */
+    this._loadGeneration = 0;
+
+    /** Resolved params, available after the first load. @type {JsonTableParams|null} */
+    this.params = null;
+
+    /** Raw rows, available after the first load. @type {Array<Object>|null} */
+    this.data = null;
+
+    /** Generated elements, available after the first load. @type {JsonTableElements} */
+    this.elements = {};
+  }
+
+
+  // ─── Lifecycle ──────────────────────────────────────────────────────────────
+
+  connectedCallback() {
+    this._isConnected = true;
+    if (!this._loadStarted) {
+      this._load();
+    }
+  }
+
+  disconnectedCallback() {
+    this._isConnected = false;
+  }
+
+
+  // ─── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Starts the component via script, passing the configuration as an object.
+   * Can be called before or after the element is attached to the DOM.
+   *
+   * Parameters not included in `config` are read from the corresponding HTML attribute
+   * (if present), then from the project defaults, then from the built-in defaults.
+   * To explicitly ignore an existing attribute pass `null` in the config.
+   *
+   * @param {Partial<JsonTableParams>} [config={}] - See `JsonTableParams` (default: {})
+   * @returns {void}
+   *
+   * @example
+   * // <json-table caption="Utenti" search="false"></json-table>
+   * el.init({ jsonUrl: '/api/rows.json' });   // jsonUrl from script, caption and search from attributes
+   * el.init({ jsonUrl: '/api/rows.json', search: null }); // search → default (true), the attribute is ignored
+   */
+  init(config = {}) {
+    this._config = config;
+    this._initCalledProgrammatically = true;
+
+    // an explicit init() must always restart, even if connectedCallback already
+    // ran a premature _load() (e.g. when domBuilder appends the element before init())
+    this._loadStarted = false;
+    this._loadGeneration++;
+
+    if (this._isConnected) {
+      this._load();
+    }
+  }
+
+  /**
+   * Empties the component and resets its state. `init()` can be called again afterwards
+   * to re-initialize it with new params, without recreating the element.
+   * @returns {void}
+   */
+  destroy() {
+    this._loadStarted = false;
+    this._loadGeneration++;
+    this.elements = {};
+    this.data = null;
+    this.innerHTML = '';
+  }
+
+  /**
+   * Reloads the data and rebuilds the structure, optionally overriding some params
+   * (merged with the config passed to `init()`, if any).
+   *
+   * @param {Partial<JsonTableParams>} [overrides={}] - Params to override (default: {})
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await el.reload();                                  // same source
+   * await el.reload({ jsonUrl: '/api/rows.json?y=2025' }); // new URL
+   * await el.reload({ data: [{ id: 1 }] });             // inline data (takes precedence over jsonUrl)
+   */
+  async reload(overrides = {}) {
+    this._config = { ...(this._config ?? {}), ...overrides };
+    this._loadStarted = false;
+    this._loadGeneration++;
+    await this._load();
+  }
+
+
+  // ─── Load & build ───────────────────────────────────────────────────────────
+
+  /**
+   * Resolves params, retrieves the data and builds the structure.
+   * Guarded against concurrent/stale calls via `_loadStarted` and `_loadGeneration`.
+   * @returns {Promise<void>}
+   */
+  async _load() {
+    if (this._loadStarted) {
+      return;
+    }
+    this._loadStarted = true;
+    const generation = this._loadGeneration;
+
+    const params = resolveParams(this, this._config, projectDefaults);
+    this.params = params;
+
+    // loading placeholder (minimo spinner)
+    this.innerHTML = '<div class="spinner"><span class="visually-hidden">Caricamento dati...</span></div>';
+
+    /** @type {Array<Object>|null} */
+    let rows = null;
+    let failed = false;
+
+    try {
+      rows = await getData(params);
+    } catch (err) {
+      failed = true;
+      // eslint-disable-next-line no-console
+      console.error(err);
+    }
+
+    // a newer init()/reload()/destroy() superseded this load
+    if (generation !== this._loadGeneration) {
+      return;
+    }
+
+    if (failed) {
+      this.innerHTML = '';
+      return;
+    }
+
+    if (rows === null) {
+      // no source: silent when created from markup without attributes (init() may follow)
+      if (this._initCalledProgrammatically) {
+        // eslint-disable-next-line no-console
+        console.error('[json-table] Nessuna sorgente dati: specificare `data` o `jsonUrl`.');
+      }
+      this.innerHTML = '';
+      return;
+    }
+
+    this.data = rows;
+    this.elements = mainBuilder(this, params);
+
+    // TODO `shown` dovrà riflettere righe filtrate/paginate quando ricerca e paginazione saranno implementate
+    updateInfo(this.elements, params, rows.length, rows.length);
+
+    if (params.debug) {
+      /* eslint-disable no-console */
+      console.groupCollapsed('[json-table] params, data & elements', this);
+      console.log('params', params);
+      console.log('data', rows);
+      console.log('elements', this.elements);
+      console.groupEnd();
+      /* eslint-enable no-console */
+    }
+
+    // dispatched in the next microtask so listeners registered right after init() still catch it
+    const event = new CustomEvent('jt:ready', { detail: { jsonTable: this }, bubbles: true });
+    Promise.resolve().then(() => this.dispatchEvent(event));
+  }
+
+} // end component
+
+
+if (!customElements.get('json-table')) {
+  customElements.define('json-table', JsonTable);
+}

package/src/web-components/json-table/json-table-component.module.css

@@ -0,0 +1,57 @@
+/*! minimo - json-table */
+
+/* Custom properties (`--jt-*`) are defined in `json-table.minimo.tokens.mjs`
+   and compiled into minimo's custom-properties.css by build-tokens */
+
+/* purgecss start ignore */
+
+json-table {
+  display: block;
+}
+
+.wrapper {
+  position: relative;
+  display: block;
+  margin-block: var(--jt-wrapper-margin-block);
+}
+
+.infoOuter {
+  padding-block-end: var(--jt-info-outer-padding-block-end);
+}
+
+.info {
+  display: flex;
+  flex-flow: column wrap;
+  gap: var(--jt-info-gap);
+  justify-content: stretch;
+}
+
+.resultInfo {
+  font-size: var(--jt-info-font-size);
+  color: var(--jt-info-color);
+  text-align: center;
+}
+
+@media (--media-medium-viewport-up) {
+  .info {
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  .resultInfo {
+    flex: 1;
+    text-align: start;
+  }
+
+  .search {
+    flex: 0 1 var(--jt-search-max-width);
+  }
+}
+
+.table {
+  /* vertical spacing is handled by the wrapper */
+  margin-block: 0;
+}
+
+/* purgecss end ignore */

package/src/web-components/json-table/json-table.minimo.tokens.mjs

@@ -0,0 +1,48 @@
+export default {
+  jt: {
+    wrapper: {
+      margin: {
+        block: {
+          $type: 'dimension',
+          $value: '{size.md}'
+        }
+      }
+    },
+
+    info: {
+      gap: {
+        $type: 'dimension',
+        $value: '{size.sm}'
+      },
+      font: {
+        size: {
+          $type: 'dimension',
+          $value: '{font.size.sm}'
+        }
+      },
+      color: {
+        $type: 'color',
+        $value: '{text.muted}'
+      },
+      outer: {
+        padding: {
+          block: {
+            end: {
+              $type: 'dimension',
+              $value: '{size.xs}'
+            }
+          }
+        }
+      }
+    },
+
+    search: {
+      max: {
+        width: {
+          $type: 'dimension',
+          $value: '20rem'
+        }
+      }
+    }
+  }
+};

package/src/web-components/json-table/readme.md

@@ -0,0 +1,243 @@
+# `<json-table>` – tabelle HTML da dati JSON
+
+> **Work in progress.** In questa fase il componente genera solo la **struttura esterna**
+> (sezione info, input di ricerca, wrapper con `<table>` vuota e caption). Colonne (`cols`),
+> rendering delle righe, ordinamento, ricerca e paginazione **non sono ancora implementati**.
+> Il piano di sviluppo è in `src/web-components/TODO json-table/TODO.md`.
+
+Sostituisce `s-datatable-component`: nessuna dipendenza esterna, custom element
+light DOM (`<json-table>`).
+
+## Installazione
+
+Nessuna peer dependency. Basta importare il file del componente (registra il custom element):
+
+```javascript
+import '@massimo-cassandro/minimo/src/web-components/json-table/json-table-component.js';
+// oppure, se serve la classe (es. per setDefaults):
+import { JsonTable } from '@massimo-cassandro/minimo/src/web-components/json-table/json-table-component.js';
+```
+
+Il CSS (`json-table-component.module.css`) è importato dal componente stesso; le custom
+properties `--jt-*` sono definite in `json-table.minimo.tokens.mjs` e compilate in
+`custom-properties.css` da `build-tokens`.
+
+## Utilizzo da markup
+
+```html
+<json-table
+  jsonurl="/api/rows.json"
+  caption="Utenti"
+></json-table>
+
+<!-- dati inline (JSON serializzato, utile in contesti SSR: Twig, Blade, ...) -->
+<json-table
+  data='[{"name":"Mario","city":"Roma"}, ...]'
+  search="false"
+></json-table>
+```
+
+I nomi degli attributi sono case-insensitive (`jsonurl` e `jsonUrl` sono equivalenti).
+Gli attributi booleani accettano i formati HTML idiomatici: `search` (presente senza valore),
+`search="true"`, `search="1"` → true; `search="false"`, `search="0"` → false.
+I valori che iniziano con `[` o `{` vengono interpretati come JSON (un JSON malformato viene
+segnalato in console e ignorato).
+
+## Utilizzo da script
+
+```javascript
+const el = document.querySelector('json-table');
+// oppure: const el = document.createElement('json-table');
+
+el.init({
+  jsonUrl: '/api/rows.json',
+  caption: 'Utenti'
+});
+
+// dati inline al posto di jsonUrl (se presenti entrambi, `data` prevale)
+el.init({
+  data: [{ name: 'Mario', city: 'Roma' }, ...]
+});
+
+// se appena creato, appendere dopo init():
+document.body.appendChild(el);
+```
+
+### Con `domBuilder`
+
+```javascript
+domBuilder([
+  {
+    tag: 'json-table',
+    attrs: { caption: 'Utenti' },
+    callback: el => el.init({ jsonUrl: '/api/rows.json' })
+  }
+], container);
+```
+
+## Utilizzo misto – attributi HTML + script
+
+I parametri non inclusi in `init()` vengono letti dall'attributo HTML corrispondente:
+
+```html
+<json-table caption="Utenti" search="false"></json-table>
+```
+
+```javascript
+el.init({ jsonUrl: '/api/rows.json' }); // jsonUrl da script, caption e search da attributo
+```
+
+**Ordine di precedenza:** `init()` > attributo HTML > `JsonTable.setDefaults()` > default interno.
+
+Per ignorare esplicitamente un attributo e ricadere sui default, passare `null` nel config:
+
+```javascript
+el.init({ jsonUrl: '/api/rows.json', search: null }); // search → default (true)
+```
+
+## Default di progetto – `JsonTable.setDefaults()`
+
+Imposta valori validi per tutte le istanze create successivamente, evitando di ripetere gli
+stessi parametri. Da invocare una sola volta, in uno script condiviso eseguito prima degli altri.
+I valori vengono uniti a quelli impostati in chiamate precedenti.
+
+```javascript
+import { JsonTable } from '.../json-table-component.js';
+
+JsonTable.setDefaults({
+  searchInputClass: 'form-control form-control-sm',
+  tableClass: 'table',
+  infoText: (shown, total) => `${shown} di ${total} record`
+});
+
+JsonTable.getDefaults();   // default interni + default di progetto
+JsonTable.resetDefaults(); // azzera i default di progetto
+```
+
+## API dell'istanza
+
+| Metodo | Descrizione |
+|---|---|
+| `init(config)` | Avvia il componente (prima o dopo l'inserimento nel DOM) |
+| `reload(overrides)` | Ricarica i dati e ricostruisce la struttura, con eventuali parametri sovrascritti (`Promise`) |
+| `destroy()` | Svuota il componente; `init()` può essere richiamato in seguito |
+
+Proprietà disponibili dopo il caricamento: `params` (parametri risolti), `data` (righe grezze),
+`elements` (elementi generati: `wrapper`, `infoOuter`, `info`, `resultInfo`, `searchInput`,
+`tableWrapper`, `table`).
+
+```javascript
+await el.reload({ jsonUrl: '/api/rows.json?anno=2025' });
+await el.reload({ data: [...] });
+```
+
+## Evento `jt:ready`
+
+Emesso sull'elemento (con `bubbles`) al termine della costruzione; `event.detail.jsonTable`
+è l'istanza. Viene emesso nel microtask successivo, quindi un listener registrato subito dopo
+`init()` lo intercetta comunque.
+
+```javascript
+el.addEventListener('jt:ready', e => {
+  console.log(e.detail.jsonTable.data);
+});
+el.init({ jsonUrl: '/api/rows.json' });
+```
+
+## Parametri
+
+Tutti i parametri sono impostabili sia da attributo HTML che da `init()`. I valori di tipo
+funzione (`caption`, `infoText`) solo da `init()`.
+
+```javascript
+{
+  debug,                  // boolean – log in console di parametri, dati ed elementi generati.
+                          // Default: false
+
+  jsonUrl,                // string – URL del JSON da caricare. Ignorato se `data` è presente.
+                          // Default: null
+
+  jsonDataField,          // string|null – chiave del JSON che contiene l'array delle righe
+                          // (es. 'data' per { data: [...] }); null o '' = la root del JSON è
+                          // l'array stesso. Default: 'data'
+
+  data,                   // Array<Object> – righe inline; prevale su `jsonUrl`. Da attributo va
+                          // passato come stringa JSON ed è sempre inteso come array delle righe
+                          // (`jsonDataField` ignorato). Default: null
+
+  caption,                // string|Function – caption della tabella (testo o HTML), oppure
+                          // funzione che restituisce stringa o Node. Default: null
+
+  search,                 // boolean – genera l'input di ricerca. Default: true
+  searchInputClass,       // string – classi dell'input di ricerca (sostituisce il default).
+                          // Default: 'form-control'
+  searchInputTitle,       // string – attributo title dell'input.
+                          // Default: 'Filtra record: inserisci un termine per eseguire la ricerca'
+  searchInputPlaceholder, // string – placeholder dell'input.
+                          // Default: 'Inserisci il termine da cercare'
+  searchInputAriaLabel,   // string – aria-label dell'input. Default: 'Filtra risultati'
+
+  tableId,                // string – id del tag <table>. Default: null
+  tableWrapperClass,      // string – classi del div che racchiude la tabella (sostituisce il
+                          // default). Default: 'table-responsive'
+  tableClass,             // string – classi del tag <table> (sostituisce il default).
+                          // Default: 'table table-bordered'
+
+  mainWrapperExtraClass,  // string – classi aggiuntive per il contenitore principale
+                          // (info + tabella). Default: null
+  outerInfoExtraClass,    // string – classi aggiuntive per il contenitore esterno della
+                          // sezione info. Default: null
+  infoExtraClass,         // string – classi aggiuntive per la sezione info. Default: null
+
+  infoText,               // (shown, total) => string|Node – testo dell'area info (testo,
+                          // stringa HTML o Node).
+                          // Default: "Visualizzate N righe su M" / "Nessun record"
+}
+```
+
+I parametri `*ExtraClass` si **aggiungono** alle classi interne di layout; i parametri
+`*Class` (`searchInputClass`, `tableWrapperClass`, `tableClass`) **sostituiscono** interamente
+il valore di default, ferme restando le eventuali classi interne di layout del componente.
+
+### In sviluppo
+
+`cols`, data-types, `locale` e opzioni di formattazione, icone (booleani e ordinamento),
+ordinamento, ricerca, paginazione, `trCallback`, `footerRender`, `refs`: vedi il TODO del componente.
+
+## Struttura generata
+
+```html
+<json-table>
+  <section class="[wrapper] [mainWrapperExtraClass]">
+    <div class="[infoOuter] [outerInfoExtraClass]">
+      <div class="[info] [infoExtraClass]">
+        <div class="[resultInfo]" aria-live="polite">Visualizzate <strong>N</strong> righe su <strong>M</strong></div>
+        <div class="[search]">                       <!-- solo se search: true -->
+          <input type="search" class="form-control" ...>
+        </div>
+      </div>
+    </div>
+    <div class="table-responsive">                   <!-- tableWrapperClass -->
+      <table class="[table] table table-bordered">   <!-- tableClass -->
+        <caption>...</caption>                       <!-- solo se caption -->
+        <!-- thead / tbody / tfoot: in sviluppo -->
+      </table>
+    </div>
+  </section>
+</json-table>
+```
+
+Le classi tra parentesi quadre sono quelle interne del CSS module.
+
+## Custom properties CSS
+
+Definite in `json-table.minimo.tokens.mjs` (namespace `--jt-*`):
+
+| Proprietà | Default (token minimo) |
+|---|---|
+| `--jt-wrapper-margin-block` | `{size.md}` |
+| `--jt-info-gap` | `{size.sm}` |
+| `--jt-info-font-size` | `{font.size.sm}` |
+| `--jt-info-color` | `{text.muted}` |
+| `--jt-info-outer-padding-block-end` | `{size.xs}` |
+| `--jt-search-max-width` | `20rem` |