@massimo-cassandro/minimo 1.33.0 → 1.33.2

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

@@ -3,12 +3,50 @@
 import { defaults } from './src/defaults.js';
 import { resolveParams } from './src/resolve-params.js';
 import { getData } from './src/get-data.js';
+import { buildDataTypes } from './src/data-types.js';
+import { parseCols } from './src/parse-cols.js';
+import { parseRows } from './src/parse-rows.js';
 import { mainBuilder } from './src/main-builder.js';
+import { renderTbody } from './src/table-body.js';
+import { renderTfoot } from './src/table-tfoot.js';
 import { updateInfo } from './src/update-info.js';
+import { applySortState, setSortListener } from './src/table-thead.js';
+import { setSearchListener, filterRows } from './src/search.js';
+import { sortRows } from './src/sorting.js';
+import { calcTotPages, renderPagination } from './src/pagination.js';
+import { domBuilder } from '../../utilities/dom-builder/dom-builder.js';
 
 /** @typedef {import('./src/defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./src/defaults.js').DataTypeDefinition} DataTypeDefinition */
+/** @typedef {import('./src/defaults.js').SortDef} SortDef */
+/** @typedef {import('./src/parse-cols.js').ParsedCol} ParsedCol */
+/** @typedef {import('./src/parse-rows.js').ParsedRow} ParsedRow */
 /** @typedef {import('./src/main-builder.js').JsonTableElements} JsonTableElements */
 
+/**
+ * Rendering state.
+ *
+ * Client-side mode: `rows` holds every parsed row, `filtered` the rows after search and sort,
+ * `pageRows` the slice of the current page. Server-side mode: the three arrays hold the rows
+ * returned by the last request (the current page), `totRec`/`filteredRec` come from the JSON.
+ *
+ * @typedef {Object} JsonTableState
+ * @property {number} totRec - Total number of records (unfiltered, see `totRecField`)
+ * @property {number} filteredRec - Number of records matching the current search
+ * @property {ParsedRow[]} rows - All the parsed rows (current page only in server-side mode)
+ * @property {ParsedRow[]} filtered - Rows after search and sort
+ * @property {ParsedRow[]} pageRows - Rows of the current page
+ * @property {string} searchTerm - Active search term ('' = none)
+ * @property {SortDef|null} sort - Active sort (column key and direction), or null
+ * @property {number} page - Current page (1-based)
+ * @property {number} totPages - Total number of pages (1 when the pagination is disabled)
+ */
+
+/**
+ * Reason of a state update, passed in the `jt:update` event detail.
+ * @typedef {'page'|'sort'|'search'} UpdateReason
+ */
+
 /**
  * Project-wide defaults, set via `JsonTable.setDefaults()`.
  * Module-level so they are shared by every instance.
@@ -16,29 +54,37 @@ import { updateInfo } from './src/update-info.js';
  */
 let projectDefaults = {};
 
+/**
+ * Empty state.
+ * @returns {JsonTableState}
+ */
+const emptyState = () => ({
+  totRec: 0, filteredRec: 0, rows: [], filtered: [], pageRows: [], searchTerm: '', sort: null, page: 1, totPages: 1
+});
+
 
 /**
- * `<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.
+ * `<json-table>` – HTML table generator from JSON data (inline or fetched), light DOM custom element,
+ * with sorting, search and pagination (client-side, or server-side via `serverSide: true`).
  *
  * 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.
+ * Events (both bubble, `event.detail.jsonTable` is the component instance):
+ * - `jt:ready`: dispatched once the structure has been built and the first data rendered
+ * - `jt:update`: dispatched after every page / sort / search change (`event.detail.reason`)
  *
  * @example
  * // markup only
- * // <json-table jsonurl="/api/rows.json" caption="Utenti"></json-table>
+ * // <json-table jsonurl="/api/rows.json" caption="Utenti" perpage="10"
+ * //   cols='[{"key":"id","dataType":"id"},{"key":"name","title":"Nome"},{"key":"amount","dataType":"euro"}]'
+ * // ></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
+ * JsonTable.setDefaults({ classes: { table: 'table' } }); // optional, project-wide
  *
  * const el = document.querySelector('json-table');
  * el.addEventListener('jt:ready', e => console.log(e.detail.jsonTable.data));
@@ -46,17 +92,37 @@ let projectDefaults = {};
  *   debug: false,                       // default: false
  *   jsonUrl: '/api/rows.json',          // default: null
  *   jsonDataField: 'data',              // default: 'data'
+ *   totRecField: 'totRec',              // default: 'totRec'
+ *   filteredRecField: 'filteredRec',    // default: 'filteredRec' (server-side mode)
  *   data: null,                         // default: null (takes precedence over jsonUrl when set)
+ *   cols: [                             // required
+ *     { key: 'id', dataType: 'id' },
+ *     { key: 'name', title: 'Nome', render: (row, tr, td) => `<a href="/users/${row.id}">${row.name}</a>` },
+ *     { key: 'amount', dataType: 'euro', tfootRender: '@sum' },
+ *     { key: 'active', dataType: 'bool' }
+ *   ],
+ *   dataTypes: {},                      // default: {} (custom types, merged with the built-in ones)
  *   caption: 'Utenti',                  // default: null
  *   search: true,                       // default: true
- *   searchInputClass: 'form-control',   // default: 'form-control'
+ *   searchDebounce: 300,                // default: 300 (ms)
+ *   perPage: 25,                        // default: 25 (0 = no pagination)
+ *   paginationDelta: 2,                 // default: 2
+ *   serverSide: false,                  // default: false
+ *   serverParams: { page: 'page', start: 'start', perPage: 'perPage', sort: 'sort', dir: 'dir', search: 'search' }, // default
+ *   initialSort: { key: 'name', dir: 'asc' }, // default: null
+ *   tfoot: true,                        // default: false (not available in server-side mode)
+ *   updateFooterOnPageChange: false,    // default: false
+ *   infoText: null,                     // default: null → labels.info
+ *   template: [{ slot: 'infoSection' }, { slot: 'table' }], // default
+ *   locale: 'it-IT',                    // default: 'it-IT'
+ *   currency: 'EUR',                    // default: 'EUR'
+ *   renderNullAs: '—',                  // default: '—'
+ *   renderZeroAs: null,                 // default: null
+ *   renderNaNAs: '—',                   // default: '—'
+ *   trCallback: null,                   // default: null
  *   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"
+ *   classes: { table: 'table' },        // merged with the defaults (see JsonTableClasses)
+ *   labels: { noRows: 'Nessun utente' } // merged with the defaults (see JsonTableLabels)
  * });
  */
 export class JsonTable extends HTMLElement {
@@ -71,9 +137,10 @@ export class JsonTable extends HTMLElement {
    *
    * @example
    * JsonTable.setDefaults({
-   *   searchInputClass: 'form-control form-control-sm', // default: 'form-control'
-   *   tableClass: 'table',                              // default: 'table table-bordered'
-   *   infoText: (shown, total) => `${shown} di ${total}`
+   *   perPage: 50,
+   *   classes: { searchInput: 'form-control', table: 'table' }, // merged with the built-in classes
+   *   labels: { searchPlaceholder: 'Cerca…' },                  // merged with the built-in labels
+   *   infoText: (start, end, totRec, filteredRec) => `${filteredRec} di ${totRec} record`
    * });
    */
   static setDefaults(newDefaults = {}) {
@@ -93,7 +160,7 @@ export class JsonTable extends HTMLElement {
    * @returns {JsonTableParams}
    *
    * @example
-   * JsonTable.getDefaults().tableWrapperClass; // → 'table-responsive'
+   * JsonTable.getDefaults().classes.tableWrapper; // → 'table-responsive'
    */
   static getDefaults() {
     return { ...defaults, ...projectDefaults };
@@ -111,13 +178,26 @@ export class JsonTable extends HTMLElement {
     this._loadStarted = false;
     /** incremented on every init()/reload()/destroy(): a pending _load() whose generation is stale gives up */
     this._loadGeneration = 0;
+    /** incremented on every server-side request: a stale response is ignored */
+    this._requestGeneration = 0;
+    /** pending search debounce timer (see `search.js`) @type {ReturnType<typeof setTimeout>|undefined} */
+    this._searchTimer = undefined;
 
-    /** Resolved params, available after the first load. @type {JsonTableParams|null} */
-    this.params = null;
+    /** Resolved params, available after the first load. @type {JsonTableParams} */
+    this.params = /** @type {JsonTableParams} */ ({ ...defaults });
 
-    /** Raw rows, available after the first load. @type {Array<Object>|null} */
+    /** Raw rows, available after the first load (current page only in server-side mode). @type {Array<Object>|null} */
     this.data = null;
 
+    /** Data types map (built-in + custom), available after the first load. @type {Object<string, DataTypeDefinition>} */
+    this.dataTypes = {};
+
+    /** Parsed visible columns, available after the first load. @type {ParsedCol[]} */
+    this.cols = [];
+
+    /** Rendering state, available after the first load. @type {JsonTableState} */
+    this.state = emptyState();
+
     /** Generated elements, available after the first load. @type {JsonTableElements} */
     this.elements = {};
   }
@@ -151,8 +231,8 @@ export class JsonTable extends HTMLElement {
    * @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
+   * // <json-table caption="Utenti" search="false" cols='[...]'></json-table>
+   * el.init({ jsonUrl: '/api/rows.json' });   // jsonUrl from script, caption, search and cols from attributes
    * el.init({ jsonUrl: '/api/rows.json', search: null }); // search → default (true), the attribute is ignored
    */
   init(config = {}) {
@@ -175,16 +255,20 @@ export class JsonTable extends HTMLElement {
    * @returns {void}
    */
   destroy() {
+    clearTimeout(this._searchTimer);
     this._loadStarted = false;
     this._loadGeneration++;
+    this._requestGeneration++;
     this.elements = {};
     this.data = null;
+    this.cols = [];
+    this.state = emptyState();
     this.innerHTML = '';
   }
 
   /**
    * Reloads the data and rebuilds the structure, optionally overriding some params
-   * (merged with the config passed to `init()`, if any).
+   * (merged with the config passed to `init()`, if any). Search, sort and page are reset.
    *
    * @param {Partial<JsonTableParams>} [overrides={}] - Params to override (default: {})
    * @returns {Promise<void>}
@@ -201,11 +285,84 @@ export class JsonTable extends HTMLElement {
     await this._load();
   }
 
+  /**
+   * Shows the given page (clamped to the available range). In server-side mode a new request
+   * is sent. Nothing happens when the page does not change.
+   *
+   * @param {number} page - Page number (1-based)
+   * @param {string|null} [focusTarget=null] - `data-page` of the pagination button to focus after the
+   *   rendering (used by the pagination buttons themselves) (default: null)
+   * @returns {void}
+   *
+   * @example
+   * el.goToPage(3);
+   */
+  goToPage(page, focusTarget = null) {
+    const requested = Math.min(Math.max(1, Math.floor(Number(page) || 1)), this.state.totPages);
+    if (requested === this.state.page) {
+      return;
+    }
+    this.state.page = requested;
+    this._update('page', focusTarget);
+  }
+
+  /**
+   * Sorts the rows by a column (`dir` null removes the sort) and goes back to the first page.
+   * The column must exist and be sortable, otherwise the call is ignored with a console error.
+   * In server-side mode a new request is sent.
+   *
+   * @param {string} key - Column key
+   * @param {'asc'|'desc'|null} dir - Direction, or null to remove the sort
+   * @returns {void}
+   *
+   * @example
+   * el.setSort('name', 'desc');
+   * el.setSort('name', null); // original order
+   */
+  setSort(key, dir) {
+    if (dir != null) {
+      const col = this.cols.find(c => c.key === key);
+      if (!col || !col.sortable) {
+        // eslint-disable-next-line no-console
+        console.error(`[json-table] setSort: colonna \`${key}\` inesistente o non ordinabile`);
+        return;
+      }
+    }
+    this.state.sort = dir == null ? null : { key, dir };
+    this.state.page = 1;
+    this._update('sort');
+  }
+
+  /**
+   * Filters the rows by a search term (every whitespace-separated word must match, case-insensitive)
+   * and goes back to the first page; an empty term removes the filter. The search input, when
+   * present, is kept in sync. In server-side mode a new request is sent.
+   *
+   * @param {string} term - Search term
+   * @returns {void}
+   *
+   * @example
+   * el.setSearch('mario');
+   * el.setSearch('');
+   */
+  setSearch(term) {
+    const value = String(term ?? '');
+    if (this.elements.searchInput && this.elements.searchInput.value !== value) {
+      this.elements.searchInput.value = value;
+    }
+    if (value.trim() === this.state.searchTerm) {
+      return;
+    }
+    this.state.searchTerm = value.trim();
+    this.state.page = 1;
+    this._update('search');
+  }
+
 
   // ─── Load & build ───────────────────────────────────────────────────────────
 
   /**
-   * Resolves params, retrieves the data and builds the structure.
+   * Resolves params, parses the columns, retrieves the data and builds the structure.
    * Guarded against concurrent/stale calls via `_loadStarted` and `_loadGeneration`.
    * @returns {Promise<void>}
    */
@@ -214,20 +371,51 @@ export class JsonTable extends HTMLElement {
       return;
     }
     this._loadStarted = true;
+    clearTimeout(this._searchTimer);
     const generation = this._loadGeneration;
 
     const params = resolveParams(this, this._config, projectDefaults);
     this.params = params;
+    this._validateParams(params);
 
     // loading placeholder (minimo spinner)
-    this.innerHTML = '<div class="spinner"><span class="visually-hidden">Caricamento dati...</span></div>';
+    domBuilder([
+      {
+        className: 'spinner',
+        children: [{ tag: 'span', className: 'visually-hidden', content: params.labels.loading }]
+      }
+    ], this, { emptyParent: true });
+
+    // columns parsing (configuration errors are reported and stop the rendering)
+    try {
+      this.dataTypes = buildDataTypes(params);
+      this.cols = parseCols(params.cols, this.dataTypes, params);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(err);
+      this.innerHTML = '';
+      return;
+    }
 
-    /** @type {Array<Object>|null} */
-    let rows = null;
+    // initial state
+    this.state = emptyState();
+    if (params.initialSort && typeof params.initialSort === 'object') {
+      const { key, dir } = params.initialSort;
+      const col = this.cols.find(c => c.key === key);
+      if (col && col.sortable && (dir === 'asc' || dir === 'desc')) {
+        this.state.sort = { key, dir };
+      } else {
+        // eslint-disable-next-line no-console
+        console.error(`[json-table] initialSort: colonna \`${key}\` inesistente o non ordinabile, oppure direzione non valida (${dir})`);
+      }
+    }
+
+    /** @type {import('./src/get-data.js').DataResult|null} */
+    let result = null;
     let failed = false;
 
     try {
-      rows = await getData(params);
+      result = await getData(params, params.serverSide ? this._serverRequest() : null);
     } catch (err) {
       failed = true;
       // eslint-disable-next-line no-console
@@ -244,7 +432,7 @@ export class JsonTable extends HTMLElement {
       return;
     }
 
-    if (rows === null) {
+    if (result === null) {
       // no source: silent when created from markup without attributes (init() may follow)
       if (this._initCalledProgrammatically) {
         // eslint-disable-next-line no-console
@@ -254,17 +442,23 @@ export class JsonTable extends HTMLElement {
       return;
     }
 
-    this.data = rows;
-    this.elements = mainBuilder(this, params);
+    this._setData(result);
+
+    this.elements = mainBuilder(this);
+    setSortListener(this);
+    setSearchListener(this);
 
-    // TODO `shown` dovrà riflettere righe filtrate/paginate quando ricerca e paginazione saranno implementate
-    updateInfo(this.elements, params, rows.length, rows.length);
+    this._computeState();
+    this._render();
 
     if (params.debug) {
       /* eslint-disable no-console */
-      console.groupCollapsed('[json-table] params, data & elements', this);
+      console.groupCollapsed('[json-table] params, cols, data, state & elements', this);
       console.log('params', params);
-      console.log('data', rows);
+      console.log('dataTypes', this.dataTypes);
+      console.log('cols', this.cols);
+      console.log('data', this.data);
+      console.log('state', this.state);
       console.log('elements', this.elements);
       console.groupEnd();
       /* eslint-enable no-console */
@@ -275,6 +469,161 @@ export class JsonTable extends HTMLElement {
     Promise.resolve().then(() => this.dispatchEvent(event));
   }
 
+  /**
+   * Normalizes the resolved params that depend on each other, reporting the inconsistencies:
+   * `perPage`/`paginationDelta` must be non-negative numbers, `serverSide` requires `jsonUrl`
+   * (ignored with inline `data`) and disables `tfoot` (the aggregates would be computed on the
+   * current page only).
+   * @param {JsonTableParams} params - Resolved params (mutated)
+   * @returns {void}
+   */
+  _validateParams(params) {
+    /* eslint-disable no-console */
+    const perPage = Number(params.perPage);
+    params.perPage = Number.isFinite(perPage) && perPage >= 0 ? Math.floor(perPage) : defaults.perPage;
+
+    const delta = Number(params.paginationDelta);
+    params.paginationDelta = Number.isFinite(delta) && delta >= 0 ? Math.floor(delta) : defaults.paginationDelta;
+
+    if (params.serverSide && (params.data != null || !params.jsonUrl)) {
+      console.warn('[json-table] `serverSide` richiede `jsonUrl` (senza `data`): modalità server-side ignorata');
+      params.serverSide = false;
+    }
+
+    if (params.serverSide && params.tfoot) {
+      console.warn('[json-table] `tfoot` non è disponibile in modalità server-side (i dati sono paginati dal server): tfoot ignorato');
+      params.tfoot = false;
+    }
+    /* eslint-enable no-console */
+  }
+
+  /**
+   * Current server-side request state (see `get-data.js` → `ServerRequest`).
+   * @returns {import('./src/get-data.js').ServerRequest}
+   */
+  _serverRequest() {
+    const { state, params } = this;
+    return {
+      page: state.page,
+      perPage: params.perPage > 0 ? params.perPage : 0,
+      sort: state.sort,
+      search: state.searchTerm
+    };
+  }
+
+  /**
+   * Stores a data result: raw rows, parsed rows and totals.
+   * @param {import('./src/get-data.js').DataResult} result
+   * @returns {void}
+   */
+  _setData(result) {
+    this.data = result.rows;
+    this.state.rows = parseRows(result.rows, this.cols, this.params);
+    this.state.totRec = result.totRec;
+    this.state.filteredRec = result.filteredRec;
+  }
+
+  /**
+   * Computes `filtered`, `pageRows`, `filteredRec`, `totPages` and clamps `page` from `rows`,
+   * `searchTerm`, `sort` and `page`.
+   *
+   * Client-side mode: search and sort are applied to `rows`, then the current page is sliced.
+   * Server-side mode: `rows` already is the requested page, `filteredRec` comes from the JSON.
+   * @returns {void}
+   */
+  _computeState() {
+    const { state, params } = this;
+
+    if (params.serverSide) {
+      state.filtered = state.rows;
+      state.pageRows = state.rows;
+      state.totPages = calcTotPages(state.filteredRec, params.perPage);
+      state.page = Math.min(Math.max(1, state.page), state.totPages);
+      return;
+    }
+
+    const filtered = filterRows(state.rows, state.searchTerm);
+    state.filtered = state.sort ? sortRows(filtered, state.sort.key, state.sort.dir, params.locale) : filtered;
+    state.filteredRec = state.filtered.length;
+    state.totPages = calcTotPages(state.filteredRec, params.perPage);
+    state.page = Math.min(Math.max(1, state.page), state.totPages);
+    state.pageRows = params.perPage > 0
+      ? state.filtered.slice((state.page - 1) * params.perPage, state.page * params.perPage)
+      : state.filtered;
+  }
+
+  /**
+   * Applies a state change (page, sort or search): recomputes the state and re-renders, or, in
+   * server-side mode, sends a new request (stale responses are ignored) and renders its result.
+   * Dispatches `jt:update` at the end.
+   *
+   * @param {UpdateReason} reason - What changed
+   * @param {string|null} [focusTarget=null] - Passed to `renderPagination()` (default: null)
+   * @returns {Promise<void>}
+   */
+  async _update(reason, focusTarget = null) {
+
+    if (this.params.serverSide) {
+      const generation = ++this._requestGeneration;
+      const loadGeneration = this._loadGeneration;
+      const requestedPage = this.state.page;
+      this.elements.wrapper?.setAttribute('aria-busy', 'true');
+
+      /** @type {import('./src/get-data.js').DataResult|null} */
+      let result = null;
+      try {
+        result = await getData(this.params, this._serverRequest());
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error(err);
+      }
+
+      if (generation !== this._requestGeneration || loadGeneration !== this._loadGeneration) {
+        return; // superseded by a newer request or by a reload/destroy
+      }
+      this.elements.wrapper?.removeAttribute('aria-busy');
+
+      if (!result) {
+        return;
+      }
+      this._setData(result);
+      this._computeState();
+
+      // the requested page no longer exists (the data set shrank since the last request):
+      // `_computeState` clamped the page, fetch the last available one
+      if (!this.state.rows.length && this.state.filteredRec > 0 && this.state.page !== requestedPage) {
+        this._update(reason, focusTarget);
+        return;
+      }
+
+    } else {
+      this._computeState();
+    }
+
+    this._render(reason, focusTarget);
+
+    this.dispatchEvent(new CustomEvent('jt:update', { detail: { jsonTable: this, reason }, bubbles: true }));
+  }
+
+  /**
+   * Renders the parts depending on the state: body rows, footer, sort indicators, pagination and
+   * info text. The footer is skipped on page changes when `updateFooterOnPageChange` is false
+   * (its content would not change).
+   *
+   * @param {UpdateReason|null} [reason=null] - What changed (null on the first rendering) (default: null)
+   * @param {string|null} [focusTarget=null] - Passed to `renderPagination()` (default: null)
+   * @returns {void}
+   */
+  _render(reason = null, focusTarget = null) {
+    renderTbody(this);
+    if (reason !== 'page' || this.params.updateFooterOnPageChange) {
+      renderTfoot(this);
+    }
+    applySortState(this);
+    renderPagination(this, focusTarget);
+    updateInfo(this);
+  }
+
 } // end component