@massimo-cassandro/minimo 1.33.0 → 1.33.1

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

@@ -1,74 +1,324 @@
 /*! minimo - json-table: defaults */
 
+import {
+  boolTrueIcon, boolFalseIcon, sortAscArrowIcon, sortDescArrowIcon, sortNoneArrowIcon,
+  paginationPrevIcon, paginationNextIcon
+} from './icons.js';
+
+/**
+ * Content accepted by every cell / heading / info area: plain text, HTML string, number,
+ * DOM node or domBuilder array. `null` is rendered as `renderNullAs`, `undefined` lets the
+ * default rendering pipeline go on (see `cell-content.js`).
+ * @typedef {string|number|Node|DomBuilderItem[]|null|undefined} CellContent
+ */
+
+/**
+ * Icon / markup used for booleans, sort and pagination buttons: an SVG/HTML string (e.g. an
+ * `.svg?inline` import), a DOM node, a domBuilder item, or a function returning one of them.
+ * @typedef {string|Node|DomBuilderItem|(() => string|Node|DomBuilderItem)} IconDef
+ */
+
+/**
+ * Column cell renderer. Arguments are positional (all optional) to keep the simplest
+ * case (`row => row.name`) as short as possible.
+ * @callback ColRender
+ * @param {Object} row - The data object of the current row
+ * @param {HTMLTableRowElement} [tr] - The `<tr>` element of the current row
+ * @param {HTMLTableCellElement} [td] - The cell element (`<td>` or `<th scope="row">`)
+ * @returns {CellContent|void} Cell content; `undefined` (no `return`) falls back to the data type rendering,
+ *   `null` to `renderNullAs`
+ */
+
+/**
+ * Footer cell renderer.
+ * @callback TfootRender
+ * @param {Object[]} rows - The whole filtered data set, or the current page only when `updateFooterOnPageChange` is true
+ * @param {HTMLTableCellElement} [td] - The footer cell element
+ * @returns {CellContent}
+ */
+
+/**
+ * Column definition (`cols` items).
+ *
+ * @typedef {Object} ColDefinition
+ * @property {string} key - REQUIRED: key of the row object (dot notation allowed for nested values, e.g. `owner.name`)
+ * @property {CellContent|(() => CellContent)} [title] - Heading content (text, HTML, Node, domBuilder array or function).
+ *   When the column is sortable it is the text of the sort button (default: the key itself)
+ * @property {string} [dataType] - Data type, one of the `dataTypes` keys. `type` is accepted as an alias (default: 'string')
+ * @property {string} [type] - Alias of `dataType`
+ * @property {ColRender|string|null} [render] - Cell renderer: a function `(row, tr, td) => content` or,
+ *   via HTML attribute too, a mustache-like string where `[[key]]` placeholders are replaced with the row
+ *   values (nested keys allowed). Overrides the data type rendering (default: null)
+ * @property {TfootRender|string|null} [tfootRender] - Footer cell content (only when `tfoot` is true): a function
+ *   `(rows, td) => content`, a static string, or one of the built-in aggregates `'@sum'`, `'@avg'`, `'@min'`,
+ *   `'@max'`, `'@count'` computed on the column values and formatted by the column data type.
+ *   `null` renders an empty cell (default: null)
+ * @property {boolean} [rowHeading] - When true the cell is a row heading (`<th scope="row">`) (default: false)
+ * @property {boolean} [searchable] - Enables the search on this column (default: true)
+ * @property {boolean} [sortable] - Enables the sorting on this column (default: true)
+ * @property {*|((row: Object) => *)} [sortValue] - Value used for sorting, or function `row => value`.
+ *   Overrides the data type `sortValue` (default: undefined = data type / raw value)
+ * @property {*|((row: Object) => *)} [searchValue] - Same as `sortValue`, for the search (default: undefined)
+ * @property {boolean|((params: JsonTableParams) => boolean)} [condition] - When false (or a function returning
+ *   false) the column is not rendered at all (default: true)
+ * @property {string|null} [headerClass] - Class(es) of the `<th>`, replacing the data type ones. When only one of
+ *   `headerClass`/`cellClass` is set, the other one takes the same value (default: null)
+ * @property {string|null} [cellClass] - Class(es) of the body/footer cells, replacing the data type ones (default: null)
+ */
+
+/**
+ * Data type definition (`dataTypes` values). Every function is optional.
+ *
+ * @typedef {Object} DataTypeDefinition
+ * @property {string|null} [headerClass] - Default class(es) of the `<th>` (overridable via `ColDefinition.headerClass`)
+ * @property {string|null} [cellClass] - Default class(es) of the cells (overridable via `ColDefinition.cellClass`)
+ * @property {((value: *, row: Object, params: JsonTableParams) => string|null)} [internalCellClass] - Class(es) always
+ *   added to the cells, regardless of `cellClass` (used by the built-in `bool` type for the icon styles)
+ * @property {(value: *, row: Object|null, params: JsonTableParams) => CellContent} [render] - Cell renderer; not invoked
+ *   for `null`/`undefined` values, which are rendered as `renderNullAs`. `row` is null when the function is
+ *   used to format a footer aggregate (`tfootRender: '@sum'`, ...)
+ * @property {(value: *, row: Object, params: JsonTableParams) => *} [sortValue] - Value used for sorting (default: raw value)
+ * @property {(value: *, row: Object, params: JsonTableParams) => string} [searchValue] - Value used for searching (default: `String(value)`)
+ * @property {Partial<ColDefinition>} [colDefaults] - Column defaults forced by this type (e.g. `{ sortable: false }`),
+ *   still overridable in the column definition
+ * @property {string} [inheritsFrom] - Custom types only: key of the built-in type to extend
+ */
+
+/**
+ * Consumer class names used by the generated structure. Internal layout classes (CSS module)
+ * are always applied in addition to these.
+ *
+ * @typedef {Object} JsonTableClasses
+ * @property {string|null} [wrapper] - Main wrapper (`<section>`: info section + table) (default: null)
+ * @property {string|null} [infoOuter] - Outer info container (default: null)
+ * @property {string|null} [info] - Info container (info text + search) (default: null)
+ * @property {string|null} [resultInfo] - Info text container (default: null)
+ * @property {string|null} [search] - Search input wrapper (default: null)
+ * @property {string|null} [searchInput] - Search input (default: 'form-control form-control-sm')
+ * @property {string|null} [tableWrapper] - Div wrapping the table (default: 'table-responsive')
+ * @property {string|null} [table] - `<table>` element (default: 'table table-bordered')
+ * @property {string|null} [tableFooter] - Bar below the table holding caption and pagination (default: null)
+ * @property {string|null} [caption] - Caption container inside the table footer bar (default: null)
+ * @property {string|null} [pagination] - Pagination `<nav>` (default: null)
+ * @property {string|null} [paginationBtn] - Pagination buttons (default: 'btn-reset')
+ * @property {string|null} [sortBtn] - Sort buttons inside the `<th>` (default: 'btn-reset')
+ * @property {string|null} [empty] - The single cell shown when there are no rows (default: null)
+ * @property {string|null} [textStart] - Inline-start alignment class (default: null, minimo cells are start-aligned by default)
+ * @property {string|null} [textCenter] - Center alignment class (default: 'text-center')
+ * @property {string|null} [textEnd] - Inline-end alignment class (default: 'text-end')
+ * @property {string|null} [nowrap] - No-wrap class (default: 'text-nowrap')
+ * @property {string|null} [numeric] - Tabular figures class, used by numeric types (default: 'text-numeric')
+ * @property {string|null} [boolCell] - Extra class of every `bool` cell (default: null)
+ * @property {string|null} [boolTrue] - Extra class of `bool` cells whose value is `true` (default: null)
+ * @property {string|null} [boolFalse] - Extra class of `bool` cells whose value is `false` (default: null)
+ */
+
+/**
+ * Texts used by the component. The `{page}` placeholder of the pagination labels is replaced
+ * with the page number.
+ *
+ * @typedef {Object} JsonTableLabels
+ * @property {string} [loading] - Loading placeholder (visually hidden) (default: 'Caricamento dati…')
+ * @property {string} [searchPlaceholder] - Search input placeholder (default: 'Cerca...')
+ * @property {string} [searchTitle] - Search input `title` (default: 'Cerca nella tabella')
+ * @property {string} [searchAriaLabel] - Search input `aria-label` (default: 'Filtra risultati')
+ * @property {string} [info] - Info text template, placeholders: `{start}`, `{end}`, `{totRec}`, `{filteredRec}`,
+ *   `{page}`, `{totPages}` (default: 'Stai visualizzando le righe da {start} a {end}, su un totale di {filteredRec} record trovati')
+ * @property {string} [noRows] - Info text and empty cell content when the data set is empty (default: 'Nessun record trovato')
+ * @property {string} [noResults] - Same as `noRows`, when a search returns nothing (default: 'Nessun risultato per la ricerca')
+ * @property {string} [sortAsc] - `aria-label`/`title` of the sort button when the next click sorts ascending
+ *   (default: 'Ordina questa colonna in senso ascendente (A → Z)')
+ * @property {string} [sortDesc] - Same, descending (default: 'Ordina questa colonna in senso discendente (Z → A)')
+ * @property {string} [sortNone] - Same, sorting removal (default: 'Rimuovi l’ordinamento a questa colonna')
+ * @property {string} [paginationAriaLabel] - `aria-label` of the pagination `<nav>` (default: 'Navigazione pagine')
+ * @property {string} [prevPage] - `aria-label`/`title` of the previous page button (default: 'Pagina precedente')
+ * @property {string} [nextPage] - Same, next page button (default: 'Pagina successiva')
+ * @property {string} [pageTitle] - `aria-label`/`title` of the page buttons (default: 'Vai a pagina {page}')
+ * @property {string} [currentPage] - `aria-label`/`title` of the current page button (default: 'Pagina {page}, corrente')
+ */
+
 /**
- * Function returning the text of the info area.
+ * Info text function.
  * @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
+ * @param {number} start - Index (1-based) of the first displayed row
+ * @param {number} end - Index of the last displayed row
+ * @param {number} totRec - Total number of records (unfiltered)
+ * @param {number} filteredRec - Number of records after filtering
+ * @param {number} page - Current page (1-based)
+ * @param {number} totPages - Total number of pages
+ * @returns {CellContent}
  */
 
 /**
- * `<json-table>` parameters.
+ * Names of the built-in template parts.
+ * @typedef {'infoSection'|'resultInfo'|'search'|'table'|'caption'|'pagination'} TemplateSlot
+ */
+
+/**
+ * Template item: a domBuilder item (whose `children`/`content` may hold other template items)
+ * or a slot placeholder `{ slot: 'name' }` replaced with one of the built-in parts.
+ * @typedef {(Omit<DomBuilderItem, 'children'|'content'> & {
+ *   children?: Array<TemplateItem|string|Node>,
+ *   content?: DomBuilderItem['content']|TemplateItem[]
+ * }) | { slot: TemplateSlot }} TemplateItem
+ */
+
+/**
+ * Sort state / initial sort definition.
+ * @typedef {Object} SortDef
+ * @property {string} key - Column key
+ * @property {'asc'|'desc'} dir - Direction
+ */
+
+/**
+ * Names of the query string parameters sent to `jsonUrl` in server-side mode (`serverSide: true`).
+ * A `null` value omits the parameter.
+ *
+ * @typedef {Object} ServerParams
+ * @property {string|null} [page] - Requested page, 1-based (default: 'page')
+ * @property {string|null} [start] - Index (0-based) of the first requested record, i.e. `(page - 1) * perPage`,
+ *   handy for `LIMIT start, perPage` queries (default: 'start')
+ * @property {string|null} [perPage] - Number of records per page (default: 'perPage')
+ * @property {string|null} [sort] - Key of the sorted column; omitted when no sort is active (default: 'sort')
+ * @property {string|null} [dir] - Sort direction, `asc`/`desc`; omitted when no sort is active (default: 'dir')
+ * @property {string|null} [search] - Search term; omitted when empty (default: 'search')
+ */
+
+/**
+ * `<json-table>` parameters (resolved: every key has a value, see `defaults`).
  *
  * 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()`.
+ * or as a property of the object passed to `init()`. Values that are functions can only be
+ * set via `init()`. Object parameters (`classes`, `labels`, `dataTypes`, `serverParams`) are
+ * merged with the defaults, so only the keys to override need to be passed.
  *
  * 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: [...] }`);
+ * @property {boolean} debug - Logs resolved params, columns, data 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`.
+ * @property {string} totRecField - Key of the fetched JSON holding the total number of records (numeric);
+ *   when missing or not numeric the total is the rows array length (default: 'totRec')
+ * @property {string} filteredRecField - Server-side mode only: key of the fetched JSON holding the number of
+ *   records matching the current search (numeric); when missing the value of `totRecField` is used (default: 'filteredRec')
+ * @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")
+ * @property {ColDefinition[]} cols - REQUIRED: columns definition (default: [])
+ * @property {Object<string, DataTypeDefinition>} dataTypes - Custom data types, merged with the built-in ones
+ *   (`string`, `num`, `id`, `perc`, `percDecimal`, `currency`, `euro`, `date`, `datetime`, `bool`, `email`).
+ *   A key matching a built-in type overrides only the given properties (default: {})
+ * @property {string|Function|null} caption - Table caption, shown below the table (start side of the footer bar)
+ *   and linked to the table via `aria-labelledby`: 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 {number} searchDebounce - Delay (ms) between the last keystroke and the search execution (default: 300)
+ * @property {number} perPage - Rows per page; `0` disables the pagination (every row in a single page, no
+ *   navigation) (default: 25)
+ * @property {number} paginationDelta - Number of page buttons shown on each side of the current page (default: 2)
+ * @property {boolean} serverSide - Server-side mode: pagination, sorting and search are delegated to the server.
+ *   Every change triggers a new request to `jsonUrl` (see `serverParams`) and the JSON is expected to hold the
+ *   rows of the requested page only, plus `totRecField` and `filteredRecField`. Requires `jsonUrl`; `tfoot` is
+ *   not available in this mode (default: false)
+ * @property {ServerParams} serverParams - Server-side mode only: names of the query string parameters (see `ServerParams`)
+ * @property {SortDef|null} initialSort - Sort applied on load, e.g. `{ key: 'name', dir: 'asc' }` (default: null)
+ * @property {boolean} tfoot - Whether to render the `<tfoot>` (see `ColDefinition.tfootRender`); ignored in
+ *   server-side mode (default: false)
+ * @property {boolean} updateFooterOnPageChange - When true, `tfootRender` receives the rows of the current page
+ *   only (page subtotals) and the footer is updated on every page change; when false it receives the whole
+ *   filtered set and is updated on filter changes only (default: false)
+ * @property {string|InfoTextFn|null} infoText - Info area content: a mustache-like string (placeholders
+ *   `{start}`, `{end}`, `{totRec}`, `{filteredRec}`, `{page}`, `{totPages}`) or a function
+ *   `(start, end, totRec, filteredRec, page, totPages) => content`. `null` uses `labels.info` (default: null)
+ * @property {TemplateItem[]|((parts: Object<string, DomBuilderItem>, params: JsonTableParams) => TemplateItem[])} template -
+ *   Layout of the main wrapper content, as a domBuilder array where `{ slot: 'name' }` items are replaced with the
+ *   built-in parts `infoSection` (info text + search), `resultInfo`, `search`, `table`, `caption`, `pagination`.
+ *   `caption` and `pagination` are included in the `table` part (footer bar) unless placed explicitly.
+ *   A function receiving the parts and returning the array is accepted too (`init()` only)
+ *   (default: [{ slot: 'infoSection' }, { slot: 'table' }])
+ * @property {string} locale - Locale used to format numbers and dates, and to compare strings when sorting (default: 'it-IT')
+ * @property {string} currency - ISO 4217 code used by the `currency` data type (default: 'EUR')
+ * @property {Intl.DateTimeFormatOptions} datesLocaleOpts - Options for the date part of `date`/`datetime`
+ *   (default: { year: 'numeric', month: 'short', day: 'numeric' })
+ * @property {Intl.DateTimeFormatOptions} timesLocaleOpts - Options for the time part of `datetime`
+ *   (default: { hour12: false, hour: '2-digit', minute: '2-digit' })
+ * @property {Intl.NumberFormatOptions} numbersLocaleOpts - Options for the `num` type (default: { maximumFractionDigits: 2 })
+ * @property {Intl.NumberFormatOptions} currPercLocaleOpts - Options for the `currency`/`euro`/`perc`/`percDecimal`
+ *   types (default: { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+ * @property {string|null} renderNullAs - Content shown for `null`/`undefined` values (default: '—')
+ * @property {string|null} renderZeroAs - When not null, content shown for numeric values equal to zero (default: null)
+ * @property {string|null} renderNaNAs - Content shown by numeric types for non-numeric values (default: '—')
+ * @property {IconDef} boolTrueIcon - Icon of `true` values in `bool` columns (default: minimo `check-bold` icon)
+ * @property {IconDef} boolFalseIcon - Icon of `false` values in `bool` columns (default: minimo `x-bold` icon)
+ * @property {IconDef} sortAscArrowIcon - Sort button icon, ascending sort active (default: minimo `arrow-up` icon)
+ * @property {IconDef} sortDescArrowIcon - Sort button icon, descending sort active (default: minimo `arrow-down` icon)
+ * @property {IconDef} sortNoneArrowIcon - Sort button icon, no sort active (default: minimo `arrows-down-up` icon)
+ * @property {IconDef} paginationPrevIcon - Previous page button icon (default: minimo `caret-left` icon)
+ * @property {IconDef} paginationNextIcon - Next page button icon (default: minimo `caret-right` icon)
+ * @property {((tr: HTMLTableRowElement, row: Object, params: JsonTableParams) => void)|null} trCallback - Callback
+ *   invoked after the rendering of every body row (default: null)
+ * @property {string|null} tableId - `id` attribute of the `<table>` element (default: null)
+ * @property {JsonTableClasses} classes - Consumer class names (see `JsonTableClasses`)
+ * @property {JsonTableLabels} labels - Texts (see `JsonTableLabels`)
  */
 
+/**
+ * Names of the object params whose value is shallow-merged across the sources
+ * (built-in default ← `setDefaults()` ← HTML attribute ← `init()`) instead of being replaced.
+ * @type {ReadonlyArray<keyof JsonTableParams>}
+ */
+export const mergedParams = ['classes', 'labels', 'dataTypes', 'serverParams'];
+
 /**
  * Built-in defaults.
  *
- * @type {Required<JsonTableParams>}
+ * @type {JsonTableParams}
  *
  * @example
  * {
  *   debug: false,
  *   jsonUrl: null,
  *   jsonDataField: 'data',
+ *   totRecField: 'totRec',
+ *   filteredRecField: 'filteredRec',
  *   data: null,
+ *   cols: [],                          // required
+ *   dataTypes: {},
  *   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',
+ *   searchDebounce: 300,
+ *   perPage: 25,                       // 0 = no pagination
+ *   paginationDelta: 2,
+ *   serverSide: false,
+ *   serverParams: { page: 'page', start: 'start', perPage: 'perPage', sort: 'sort', dir: 'dir', search: 'search' },
+ *   initialSort: null,                 // e.g. { key: 'name', dir: 'asc' }
+ *   tfoot: false,
+ *   updateFooterOnPageChange: false,
+ *   infoText: null,                    // → labels.info
+ *   template: [{ slot: 'infoSection' }, { slot: 'table' }],
+ *   locale: 'it-IT',
+ *   currency: 'EUR',
+ *   datesLocaleOpts: { year: 'numeric', month: 'short', day: 'numeric' },
+ *   timesLocaleOpts: { hour12: false, hour: '2-digit', minute: '2-digit' },
+ *   numbersLocaleOpts: { maximumFractionDigits: 2 },
+ *   currPercLocaleOpts: { minimumFractionDigits: 2, maximumFractionDigits: 2 },
+ *   renderNullAs: '—',
+ *   renderZeroAs: null,
+ *   renderNaNAs: '—',
+ *   boolTrueIcon: '<svg …>',           // minimo check-bold
+ *   boolFalseIcon: '<svg …>',          // minimo x-bold
+ *   sortAscArrowIcon: '<svg …>',       // minimo arrow-up
+ *   sortDescArrowIcon: '<svg …>',      // minimo arrow-down
+ *   sortNoneArrowIcon: '<svg …>',      // minimo arrows-down-up
+ *   paginationPrevIcon: '<svg …>',     // minimo caret-left
+ *   paginationNextIcon: '<svg …>',     // minimo caret-right
+ *   trCallback: null,
  *   tableId: null,
- *   tableWrapperClass: 'table-responsive',
- *   tableClass: 'table table-bordered',
- *   mainWrapperExtraClass: null,
- *   outerInfoExtraClass: null,
- *   infoExtraClass: null,
- *   infoText: (shown, total) => '…'
+ *   classes: { … },                    // see JsonTableClasses
+ *   labels: { … }                      // see JsonTableLabels
  * }
  */
 export const defaults = {
@@ -76,30 +326,99 @@ export const defaults = {
 
   jsonUrl: null,
   jsonDataField: 'data',
+  totRecField: 'totRec',
+  filteredRecField: 'filteredRec',
   data: null,
 
-  caption: null,
+  cols: [],
+  dataTypes: {},
 
+  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',
+  searchDebounce: 300,
+
+  perPage: 25,
+  paginationDelta: 2,
+  serverSide: false,
+  serverParams: {
+    page: 'page',
+    start: 'start',
+    perPage: 'perPage',
+    sort: 'sort',
+    dir: 'dir',
+    search: 'search'
+  },
+  initialSort: null,
+
+  tfoot: false,
+  updateFooterOnPageChange: false,
+  infoText: null,
+
+  template: [{ slot: 'infoSection' }, { slot: 'table' }],
+
+  locale: 'it-IT',
+  currency: 'EUR',
+  datesLocaleOpts: { year: 'numeric', month: 'short', day: 'numeric' },
+  timesLocaleOpts: { hour12: false, hour: '2-digit', minute: '2-digit' },
+  numbersLocaleOpts: { maximumFractionDigits: 2 },
+  currPercLocaleOpts: { minimumFractionDigits: 2, maximumFractionDigits: 2 },
+
+  renderNullAs: '—',
+  renderZeroAs: null,
+  renderNaNAs: '—',
+
+  boolTrueIcon,
+  boolFalseIcon,
+  sortAscArrowIcon,
+  sortDescArrowIcon,
+  sortNoneArrowIcon,
+  paginationPrevIcon,
+  paginationNextIcon,
+
+  trCallback: null,
 
   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>`;
+
+  classes: {
+    wrapper: null,
+    infoOuter: null,
+    info: null,
+    resultInfo: null,
+    search: null,
+    searchInput: 'form-control form-control-sm',
+    tableWrapper: 'table-responsive',
+    table: 'table table-bordered',
+    tableFooter: null,
+    caption: null,
+    pagination: null,
+    paginationBtn: 'btn-reset',
+    sortBtn: 'btn-reset',
+    empty: null,
+    textStart: null,
+    textCenter: 'text-center',
+    textEnd: 'text-end',
+    nowrap: 'text-nowrap',
+    numeric: 'text-numeric',
+    boolCell: null,
+    boolTrue: null,
+    boolFalse: null
+  },
+
+  labels: {
+    loading: 'Caricamento dati…',
+    searchPlaceholder: 'Cerca...',
+    searchTitle: 'Cerca nella tabella',
+    searchAriaLabel: 'Filtra risultati',
+    info: 'Stai visualizzando le righe da {start} a {end}, su un totale di {filteredRec} record trovati',
+    noRows: 'Nessun record trovato',
+    noResults: 'Nessun risultato per la ricerca',
+    sortAsc: 'Ordina questa colonna in senso ascendente (A → Z)',
+    sortDesc: 'Ordina questa colonna in senso discendente (Z → A)',
+    sortNone: 'Rimuovi l’ordinamento a questa colonna',
+    paginationAriaLabel: 'Navigazione pagine',
+    prevPage: 'Pagina precedente',
+    nextPage: 'Pagina successiva',
+    pageTitle: 'Vai a pagina {page}',
+    currentPage: 'Pagina {page}, corrente'
   }
 };

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

@@ -1,43 +1,129 @@
 /*! minimo - json-table: data acquisition */
 
 /** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./defaults.js').SortDef} SortDef */
+
+/**
+ * Result of `getData()`.
+ * @typedef {Object} DataResult
+ * @property {Array<Object>} rows - The rows array (the requested page only, in server-side mode)
+ * @property {number} totRec - Total number of records: the numeric value of `params.totRecField` in the
+ *   fetched JSON, `rows.length` otherwise
+ * @property {number} filteredRec - Number of records matching the current search: the numeric value of
+ *   `params.filteredRecField` in the fetched JSON (server-side mode), `totRec` otherwise
+ */
+
+/**
+ * State of the request in server-side mode.
+ * @typedef {Object} ServerRequest
+ * @property {number} page - Requested page (1-based)
+ * @property {number} perPage - Rows per page
+ * @property {SortDef|null} sort - Active sort, or null
+ * @property {string} search - Search term ('' = none)
+ */
+
+/**
+ * Reads a numeric field of the fetched JSON; `undefined` when missing or not numeric.
+ * @param {*} json - Fetched JSON
+ * @param {string|null|undefined} field - Key to read
+ * @returns {number|undefined}
+ */
+function numericField(json, field) {
+  if (!field || json == null || typeof json !== 'object') {
+    return undefined;
+  }
+  const raw = json[field];
+  const num = Number(raw);
+  return (raw != null && raw !== '' && Number.isFinite(num)) ? num : undefined;
+}
+
+
+/**
+ * Builds the URL of a server-side request: `params.jsonUrl` plus the query string parameters
+ * named in `params.serverParams` (parameters set to `null` are omitted; `sort`/`dir` are sent
+ * only when a sort is active, `search` only when not empty). Existing query string parameters
+ * of `jsonUrl` are preserved.
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @param {ServerRequest} request - Request state
+ * @returns {string}
+ *
+ * @example
+ * buildServerUrl(
+ *   { ...params, jsonUrl: '/api/rows.json?year=2025' },
+ *   { page: 3, perPage: 25, sort: { key: 'name', dir: 'desc' }, search: 'mar' }
+ * );
+ * // → '/api/rows.json?year=2025&page=3&start=50&perPage=25&sort=name&dir=desc&search=mar'
+ */
+export function buildServerUrl(params, request) {
+
+  const url = new URL(String(params.jsonUrl), document.baseURI);
+  const names = params.serverParams ?? {};
+
+  /** @type {(name: string|null|undefined, value: string|number|null|undefined) => void} */
+  const set = (name, value) => {
+    if (name && value != null && value !== '') {
+      url.searchParams.set(name, String(value));
+    }
+  };
+
+  set(names.page, request.page);
+  set(names.start, (request.page - 1) * request.perPage);
+  set(names.perPage, request.perPage);
+  set(names.sort, request.sort?.key);
+  set(names.dir, request.sort ? request.sort.dir : null);
+  set(names.search, request.search);
+
+  return url.toString();
+}
+
 
 /**
  * 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).
+ * read from the `jsonDataField` key (`null`/`''` = the JSON root is the array itself); when the
+ * JSON also holds a numeric `totRecField` key, it is returned as `totRec`, otherwise `totRec` is
+ * the rows array length. In server-side mode (`request` given) the URL carries the pagination /
+ * sort / search parameters (see `buildServerUrl`) and `filteredRecField` is read too.
  * 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
+ * @param {ServerRequest|null} [request=null] - Server-side request state; `null` for a plain request (default: null)
+ * @returns {Promise<DataResult|null>} Rows and totals, 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 }]
+ * await getData({ ...params, data: [{ id: 1 }], jsonUrl: '/ignored.json' });
+ * // → { rows: [{ id: 1 }], totRec: 1, filteredRec: 1 }
  *
- * // fetched JSON: { data: [...] }  (jsonDataField default: 'data')
+ * // fetched JSON: { data: [...], totRec: 1500 }  (jsonDataField default: 'data', totRecField default: 'totRec')
  * await getData({ ...params, jsonUrl: '/api/rows.json' });
  *
  * // fetched JSON whose root is the array itself
  * await getData({ ...params, jsonUrl: '/api/rows.json', jsonDataField: null });
+ *
+ * // server-side: GET /api/rows.json?page=2&start=25&perPage=25&search=mar
+ * // expected JSON: { data: [...25 rows], totRec: 1500, filteredRec: 40 }
+ * await getData({ ...params, jsonUrl: '/api/rows.json', serverSide: true }, { page: 2, perPage: 25, sort: null, search: 'mar' });
  */
-export async function getData(params) {
+export async function getData(params, request = null) {
 
   if (params.data != null) {
     if (!Array.isArray(params.data)) {
       throw new Error('[json-table] `data` deve essere un array di oggetti');
     }
-    return params.data;
+    return { rows: params.data, totRec: params.data.length, filteredRec: params.data.length };
   }
 
   if (params.jsonUrl) {
-    const response = await fetch(params.jsonUrl);
+    const url = request ? buildServerUrl(params, request) : params.jsonUrl;
+    const response = await fetch(url);
 
     if (!response.ok) {
-      throw new Error(`[json-table] ${params.jsonUrl}: risposta HTTP ${response.status}`);
+      throw new Error(`[json-table] ${url}: risposta HTTP ${response.status}`);
     }
 
     const json = await response.json();
@@ -46,11 +132,20 @@ export async function getData(params) {
 
     if (!Array.isArray(rows)) {
       throw new Error(
-        `[json-table] ${params.jsonUrl}: ` +
+        `[json-table] ${url}: ` +
         (field ? `il campo \`${field}\` non contiene un array` : 'la risposta non è un array')
       );
     }
-    return rows;
+
+    const hasFields = field != null && field !== '';
+    const totRec = hasFields ? numericField(json, params.totRecField) : undefined;
+    const filteredRec = hasFields ? numericField(json, params.filteredRecField) : undefined;
+
+    return {
+      rows,
+      totRec: totRec ?? rows.length,
+      filteredRec: filteredRec ?? totRec ?? rows.length
+    };
   }
 
   return null;