@massimo-cassandro/minimo 1.32.4 → 1.33.1

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

@@ -0,0 +1,107 @@
+/*! minimo - json-table: info section parts */
+
+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 */
+
+/**
+ * domBuilder item of the info text container (template slot `resultInfo`).
+ *
+ * Generated structure: `div.resultInfo[classes.resultInfo][aria-live=polite]`; the content is
+ * set by `update-info.js`. The element is stored in `elements.resultInfo`.
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * domBuilder([resultInfoPart(params, elements)], host);
+ * elements.resultInfo; // → HTMLElement
+ */
+export function resultInfoPart(params, elements) {
+  return {
+    className: classnames(styles.resultInfo, params.classes.resultInfo),
+    attrs: { 'aria-live': 'polite' },
+    callback: el => { elements.resultInfo = /** @type {HTMLElement} */ (el); }
+  };
+}
+
+
+/**
+ * domBuilder item of the search input (template slot `search`), rendered only when
+ * `params.search` is true.
+ *
+ * Generated structure: `div.search[classes.search] > input[type=search][classes.searchInput]`.
+ * The input is stored in `elements.searchInput`.
+ *
+ * TODO listener sull'input di ricerca: step 3
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * domBuilder([searchPart(params, elements)], host);
+ * elements.searchInput; // → HTMLInputElement (when params.search is true)
+ */
+export function searchPart(params, elements) {
+  return {
+    condition: params.search,
+    className: classnames(styles.search, params.classes.search),
+    children: [
+      {
+        tag: 'input',
+        className: classnames(params.classes.searchInput),
+        attrs: {
+          type: 'search',
+          title: params.labels.searchTitle,
+          placeholder: params.labels.searchPlaceholder,
+          'aria-label': params.labels.searchAriaLabel
+        },
+        callback: el => { elements.searchInput = /** @type {HTMLInputElement} */ (el); }
+      }
+    ]
+  };
+}
+
+
+/**
+ * domBuilder item of the whole info section (template slot `infoSection`): info text + search input.
+ *
+ * Generated structure:
+ * ```
+ * div.infoOuter[classes.infoOuter]
+ *   div.info[classes.info]
+ *     div.resultInfo                       ← resultInfoPart()
+ *     div.search > input[type=search]      ← searchPart(), only if `params.search` is true
+ * ```
+ *
+ * References to the generated elements are stored in `elements`
+ * (`infoOuter`, `info`, `resultInfo`, `searchInput`).
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * domBuilder([{ tag: 'section', children: [infoSectionPart(params, elements)] }], host);
+ * elements.info; // → HTMLElement
+ */
+export function infoSectionPart(params, elements) {
+  return {
+    className: classnames(styles.infoOuter, params.classes.infoOuter),
+    callback: el => { elements.infoOuter = /** @type {HTMLElement} */ (el); },
+    children: [
+      {
+        className: classnames(styles.info, params.classes.info),
+        callback: el => { elements.info = /** @type {HTMLElement} */ (el); },
+        children: [
+          resultInfoPart(params, elements),
+          searchPart(params, elements)
+        ]
+      }
+    ]
+  };
+}

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

@@ -0,0 +1,218 @@
+/*! 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 { defaults } from './defaults.js';
+import { infoSectionPart, resultInfoPart, searchPart } from './info-section.js';
+import { tablePart, tableFooterPart, captionPart, captionId } from './table-builder.js';
+import { paginationPart } from './pagination.js';
+
+/** @typedef {import('../json-table-component.js').JsonTable} JsonTable */
+/** @typedef {import('./defaults.js').TemplateItem} TemplateItem */
+/** @typedef {import('./defaults.js').TemplateSlot} TemplateSlot */
+
+/**
+ * Elements generated by the component, collected during the build.
+ * @typedef {Object} JsonTableElements
+ * @property {HTMLElement} [wrapper] - Main wrapper (`section`), contains the template parts
+ * @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
+ * @property {HTMLTableSectionElement} [thead] - The `<thead>` element
+ * @property {HTMLTableSectionElement} [tbody] - The `<tbody>` element
+ * @property {HTMLTableSectionElement} [tfoot] - The `<tfoot>` element (only when `tfoot` is true)
+ * @property {HTMLElement} [tableFooter] - Footer bar below the table (caption + pagination), when rendered
+ * @property {HTMLElement} [caption] - Caption container (only when `caption` is set)
+ * @property {HTMLElement} [pagination] - Pagination `<nav>` (only when `perPage` > 0)
+ */
+
+/**
+ * Whether a template item is a slot placeholder.
+ * @param {*} item
+ * @returns {item is { slot: TemplateSlot }}
+ */
+function isSlot(item) {
+  return item != null && typeof item === 'object' && !(item instanceof Node) && typeof item.slot === 'string';
+}
+
+
+/**
+ * Collects, recursively (`children` and array `content`), the names of the slots used by a template.
+ *
+ * @param {Array<TemplateItem|string|Node>} items - Template items
+ * @param {Set<string>} [found=new Set()] - Accumulator (default: new Set())
+ * @returns {Set<string>}
+ *
+ * @example
+ * collectSlots([{ slot: 'table' }, { children: [{ slot: 'pagination' }] }]); // → Set { 'table', 'pagination' }
+ */
+export function collectSlots(items, found = new Set()) {
+
+  items.forEach(item => {
+    if (isSlot(item)) {
+      found.add(item.slot);
+    } else if (item != null && typeof item === 'object' && !(item instanceof Node)) {
+      if (Array.isArray(item.children)) {
+        collectSlots(item.children, found);
+      }
+      if (Array.isArray(item.content)) {
+        collectSlots(/** @type {TemplateItem[]} */ (item.content), found);
+      }
+    }
+  });
+
+  return found;
+}
+
+
+/**
+ * Replaces, recursively (`children` and array `content`), every `{ slot: 'name' }` item of a
+ * template with the corresponding built-in part. Unknown slots are reported in the console
+ * and skipped. Non-slot items are shallow-copied, so the original template is never mutated.
+ *
+ * @param {Array<TemplateItem|string|Node>} items - Template items
+ * @param {Object<string, DomBuilderItem>} parts - Built-in parts, keyed by slot name
+ * @returns {Array<DomBuilderItem|string|Node>}
+ *
+ * @example
+ * expandSlots([{ className: 'row', children: [{ slot: 'search' }, { slot: 'resultInfo' }] }, { slot: 'table' }], parts);
+ * // → [{ className: 'row', children: [<search part>, <resultInfo part>] }, <table part>]
+ */
+export function expandSlots(items, parts) {
+
+  /** @type {Array<DomBuilderItem|string|Node>} */
+  const result = [];
+
+  items.forEach(item => {
+
+    if (item == null || typeof item !== 'object' || item instanceof Node) {
+      result.push(/** @type {string|Node} */ (item));
+      return;
+    }
+
+    if (isSlot(item)) {
+      const part = parts[item.slot];
+      if (!part) {
+        // eslint-disable-next-line no-console
+        console.error(`[json-table] template: slot \`${item.slot}\` non riconosciuto (disponibili: ${Object.keys(parts).join(', ')})`);
+        return;
+      }
+      result.push(part);
+      return;
+    }
+
+    /** @type {DomBuilderItem} */
+    const copy = /** @type {DomBuilderItem} */ ({ ...item });
+
+    if (Array.isArray(item.children)) {
+      copy.children = expandSlots(item.children, parts);
+    }
+    if (Array.isArray(item.content)) {
+      copy.content = /** @type {DomBuilderItem[]} */ (expandSlots(/** @type {TemplateItem[]} */ (item.content), parts));
+    }
+
+    result.push(copy);
+  });
+
+  return result;
+}
+
+
+/**
+ * Builds the whole component structure inside the host element (emptied first) via domBuilder:
+ * a fixed main wrapper whose content is defined by `params.template`.
+ *
+ * Available template slots (see `TemplateItem`):
+ * - `infoSection` → `infoSectionPart()` (info text + search input)
+ * - `resultInfo`  → `resultInfoPart()` (info text only)
+ * - `search`      → `searchPart()` (search input only)
+ * - `table`       → `tablePart()` (table wrapper + table with thead, tbody, tfoot, plus the footer bar)
+ * - `caption`     → `captionPart()` (caption container; part of the `table` footer bar unless placed explicitly)
+ * - `pagination`  → `paginationPart()` (pagination nav; idem)
+ *
+ * Generated structure with the default template (`[{ slot: 'infoSection' }, { slot: 'table' }]`):
+ * ```
+ * section.wrapper[classes.wrapper]
+ *   div.infoOuter[classes.infoOuter]
+ *     div.info[classes.info]
+ *       div.resultInfo
+ *       div.search > input[type=search]     (if `search`)
+ *   div.tableOuter
+ *     div.tableWrapper[classes.tableWrapper]
+ *       table#tableId.table[classes.table]
+ *         thead / tbody / tfoot             (tfoot if `tfoot`)
+ *     div.tableFooter[classes.tableFooter]  (if `caption` or `perPage` > 0)
+ *       div.caption                         (if `caption`)
+ *       nav.pagination                      (if `perPage` > 0)
+ * ```
+ *
+ * The `<tbody>`, `<tfoot>` and pagination are created empty: see `renderTbody()`, `renderTfoot()`
+ * and `renderPagination()`.
+ *
+ * @param {JsonTable} jt - The component instance (host element, `params`, `cols`)
+ * @returns {JsonTableElements} References to the generated elements
+ *
+ * @example
+ * jt.params.template = [
+ *   { className: 'flex gap-2', children: [{ slot: 'search' }, { slot: 'pagination' }] },
+ *   { slot: 'table' },   // footer bar with the caption only: the pagination is placed above
+ *   { slot: 'resultInfo' }
+ * ];
+ * const elements = mainBuilder(jt);
+ * elements.table; // → HTMLTableElement
+ */
+export function mainBuilder(jt) {
+
+  const { params } = jt;
+
+  /** @type {JsonTableElements} */
+  const elements = {};
+
+  const capId = captionId(params);
+  const captionItem = captionPart(jt, elements, capId);
+  const paginationItem = paginationPart(jt, elements);
+
+  // footer bar parts: removed below when the template places them elsewhere
+  /** @type {DomBuilderItem[]} */
+  const footerChildren = [captionItem, paginationItem];
+  const footerBar = tableFooterPart(jt, elements, footerChildren);
+
+  /** @type {Object<string, DomBuilderItem>} */
+  const parts = {
+    infoSection: infoSectionPart(params, elements),
+    resultInfo: resultInfoPart(params, elements),
+    search: searchPart(params, elements),
+    caption: captionItem,
+    pagination: paginationItem,
+    table: tablePart(jt, elements, footerBar, capId)
+  };
+
+  const template = typeof params.template === 'function'
+    ? params.template(parts, params)
+    : params.template;
+
+  const items = Array.isArray(template) ? template : /** @type {TemplateItem[]} */ (defaults.template);
+  const usedSlots = collectSlots(items);
+
+  ['caption', 'pagination'].forEach(slot => {
+    if (usedSlots.has(slot)) {
+      footerChildren.splice(footerChildren.indexOf(parts[slot]), 1);
+    }
+  });
+  footerBar.condition = footerChildren.some(item => item.condition !== false);
+
+  domBuilder([
+    {
+      tag: 'section',
+      className: classnames(styles.wrapper, params.classes.wrapper),
+      callback: el => { elements.wrapper = /** @type {HTMLElement} */ (el); },
+      children: expandSlots(items, parts)
+    }
+  ], jt, { emptyParent: true });
+
+  return elements;
+}

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

@@ -0,0 +1,253 @@
+/*! minimo - json-table: pagination */
+
+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 { iconContent } from './icons.js';
+
+/** @typedef {import('../json-table-component.js').JsonTable} JsonTable */
+/** @typedef {import('./main-builder.js').JsonTableElements} JsonTableElements */
+
+/**
+ * Number of pages needed to show `count` rows, `perPage` per page (at least 1).
+ * `perPage` <= 0 means no pagination: a single page.
+ *
+ * @param {number} count - Number of rows
+ * @param {number} perPage - Rows per page
+ * @returns {number}
+ *
+ * @example
+ * calcTotPages(101, 25); // → 5
+ * calcTotPages(0, 25);   // → 1
+ * calcTotPages(101, 0);  // → 1
+ */
+export function calcTotPages(count, perPage) {
+  if (!(perPage > 0)) {
+    return 1;
+  }
+  return Math.max(1, Math.ceil(count / perPage));
+}
+
+
+/**
+ * Builds the list of page numbers to show in the navigation: the current page with `delta`
+ * pages on each side (the window is widened near the edges so that it keeps a constant size),
+ * plus the first and the last page; `null` marks a gap (ellipsis). When the gap would hide a
+ * single page, that page is shown instead of the ellipsis.
+ *
+ * @param {number} current - Current page (1-based)
+ * @param {number} totPages - Total number of pages
+ * @param {number} [delta=2] - Pages on each side of the current one (default: 2)
+ * @returns {Array<number|null>}
+ *
+ * @example
+ * pageList(1, 3);       // → [1, 2, 3]
+ * pageList(1, 10);      // → [1, 2, 3, 4, 5, null, 10]
+ * pageList(6, 12);      // → [1, null, 4, 5, 6, 7, 8, null, 12]
+ * pageList(5, 10);      // → [1, 2, 3, 4, 5, 6, 7, null, 10]  (page 2 shown instead of an ellipsis hiding it alone)
+ * pageList(10, 10);     // → [1, null, 6, 7, 8, 9, 10]
+ * pageList(4, 10, 1);   // → [1, 2, 3, 4, 5, null, 10]
+ */
+export function pageList(current, totPages, delta = 2) {
+
+  const side = Math.max(0, Math.floor(delta));
+  const width = side * 2 + 1;
+
+  if (totPages <= width + 2) {
+    return Array.from({ length: totPages }, (_, i) => i + 1);
+  }
+
+  let min = Math.max(1, current - side);
+  let max = Math.min(totPages, current + side);
+
+  // keep the window size constant near the edges
+  while (max - min + 1 < width) {
+    if (min > 1) {
+      min--;
+    } else if (max < totPages) {
+      max++;
+    } else {
+      break;
+    }
+  }
+
+  /** @type {Array<number|null>} */
+  const pages = Array.from({ length: max - min + 1 }, (_, i) => min + i);
+
+  if (min === 3) {
+    pages.unshift(1, 2);
+  } else if (min > 3) {
+    pages.unshift(1, null);
+  } else if (min === 2) {
+    pages.unshift(1);
+  }
+
+  if (max === totPages - 2) {
+    pages.push(totPages - 1, totPages);
+  } else if (max < totPages - 2) {
+    pages.push(null, totPages);
+  } else if (max === totPages - 1) {
+    pages.push(totPages);
+  }
+
+  return pages;
+}
+
+
+/**
+ * Replaces the `{page}` placeholder of a pagination label.
+ * @param {string|undefined} label
+ * @param {number} page
+ * @param {string} locale
+ * @returns {string}
+ */
+function pageLabel(label, page, locale) {
+  return String(label ?? '').replace(/\{page\}/g, page.toLocaleString(locale));
+}
+
+
+/**
+ * domBuilder item of the pagination `<nav>` (template slot `pagination`), rendered only when
+ * `params.perPage` is > 0. The `<nav>` is stored in `elements.pagination` and gets a delegated
+ * `click` listener on its buttons, which calls `jt.goToPage()`. The content (page list) is
+ * rendered by `renderPagination()` and the whole `<nav>` is hidden when there is a single page.
+ *
+ * Generated structure (see `renderPagination`):
+ * ```
+ * nav.pagination[classes.pagination][aria-label=labels.paginationAriaLabel]
+ *   ul.paginationList
+ *     li.paginationItem > button.paginationBtn[classes.paginationBtn][data-page=prev][aria-label][title] > icon
+ *     li.paginationItem > button.paginationBtn[data-page=1][aria-label="Vai a pagina 1"] 1
+ *     li.paginationItem > button.paginationBtn[data-page=2][aria-current=page] 2      ← current page
+ *     li.paginationItem > span.paginationEllipsis …
+ *     li.paginationItem > button.paginationBtn[data-page=next] > icon
+ * ```
+ *
+ * @param {JsonTable} jt - The component instance
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * domBuilder([paginationPart(jt, elements)], host);
+ * elements.pagination; // → HTMLElement (nav), when params.perPage > 0
+ */
+export function paginationPart(jt, elements) {
+
+  const { params } = jt;
+
+  return {
+    tag: 'nav',
+    condition: params.perPage > 0,
+    className: classnames(styles.pagination, params.classes.pagination),
+    attrs: { 'aria-label': params.labels.paginationAriaLabel, hidden: '' },
+    callback: el => {
+      const nav = /** @type {HTMLElement} */ (el);
+      elements.pagination = nav;
+
+      nav.addEventListener('click', e => {
+        const btn = /** @type {HTMLElement|null} */ (
+          /** @type {HTMLElement} */ (e.target).closest('button[data-page]')
+        );
+        if (!btn || btn.hasAttribute('disabled') || btn.getAttribute('aria-current') === 'page') {
+          return;
+        }
+        const target = btn.dataset.page;
+        const { page } = jt.state;
+        const requested = target === 'prev' ? page - 1 : (target === 'next' ? page + 1 : Number(target));
+        jt.goToPage(requested, target);
+      });
+    }
+  };
+}
+
+
+/**
+ * Renders the page list inside `elements.pagination` from the current state (`page`, `totPages`),
+ * replacing the previous content; the `<nav>` is hidden when there is a single page.
+ *
+ * When `focusTarget` is given (the `data-page` of the button that triggered the change:
+ * `'prev'`, `'next'` or a page number) the focus is moved to the corresponding new button, or
+ * to the current page button when that one is no longer available, so that keyboard users do
+ * not lose their position.
+ *
+ * @param {JsonTable} jt - The component instance
+ * @param {string|null} [focusTarget=null] - `data-page` of the button to focus after the rendering (default: null)
+ * @returns {void}
+ *
+ * @example
+ * renderPagination(jt);         // after `jt.state` has been updated
+ * renderPagination(jt, 'next'); // same, moving the focus to the "next" button
+ */
+export function renderPagination(jt, focusTarget = null) {
+
+  const { params, elements, state } = jt;
+  const nav = elements.pagination;
+
+  if (!nav) {
+    return;
+  }
+
+  if (state.totPages <= 1) {
+    nav.hidden = true;
+    nav.replaceChildren();
+    return;
+  }
+
+  nav.hidden = false;
+
+  const btnClass = classnames(styles.paginationBtn, params.classes.paginationBtn);
+  const { labels, locale } = params;
+
+  /** @type {(target: string, label: string, icon: import('./defaults.js').IconDef, disabled: boolean) => DomBuilderItem} */
+  const arrowBtn = (target, label, icon, disabled) => ({
+    tag: 'li',
+    className: styles.paginationItem,
+    children: [
+      {
+        tag: 'button',
+        className: classnames(btnClass, styles.paginationArrow),
+        attrs: { type: 'button', 'data-page': target, 'aria-label': label, title: label, disabled: disabled ? '' : null },
+        content: iconContent(icon)
+      }
+    ]
+  });
+
+  domBuilder([
+    {
+      tag: 'ul',
+      className: styles.paginationList,
+      children: [
+        arrowBtn('prev', labels.prevPage ?? '', params.paginationPrevIcon, state.page <= 1),
+
+        ...pageList(state.page, state.totPages, params.paginationDelta).map(page => ({
+          tag: 'li',
+          className: styles.paginationItem,
+          children: [
+            page === null
+              ? { tag: 'span', className: styles.paginationEllipsis, attrs: { 'aria-hidden': 'true' }, content: '…' }
+              : {
+                tag: 'button',
+                className: btnClass,
+                attrs: {
+                  type: 'button',
+                  'data-page': page,
+                  'aria-current': page === state.page ? 'page' : null,
+                  'aria-label': pageLabel(page === state.page ? labels.currentPage : labels.pageTitle, page, locale),
+                  title: pageLabel(page === state.page ? labels.currentPage : labels.pageTitle, page, locale)
+                },
+                content: page.toLocaleString(locale)
+              }
+          ]
+        })),
+
+        arrowBtn('next', labels.nextPage ?? '', params.paginationNextIcon, state.page >= state.totPages)
+      ]
+    }
+  ], nav, { emptyParent: true });
+
+  if (focusTarget != null) {
+    const wanted = /** @type {HTMLButtonElement|null} */ (nav.querySelector(`button[data-page="${focusTarget}"]:not([disabled])`));
+    const current = /** @type {HTMLButtonElement|null} */ (nav.querySelector('button[aria-current="page"]'));
+    (wanted ?? current)?.focus();
+  }
+}

package/src/web-components/json-table/src/parse-cols.js

@@ -0,0 +1,113 @@
+/*! minimo - json-table: columns parsing */
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./defaults.js').ColDefinition} ColDefinition */
+/** @typedef {import('./defaults.js').DataTypeDefinition} DataTypeDefinition */
+
+/**
+ * Column definition after parsing: every property has a value, `condition` is resolved to a
+ * boolean, `headerClass`/`cellClass` are the final class strings and `_type` is the data type object.
+ * @typedef {Required<Omit<ColDefinition, 'type'|'condition'|'sortValue'|'searchValue'>> & {
+ *   condition: boolean,
+ *   sortValue: *,
+ *   searchValue: *,
+ *   _type: DataTypeDefinition
+ * }} ParsedCol
+ */
+
+/**
+ * Column defaults.
+ * @type {Omit<Required<ColDefinition>, 'type'|'sortValue'|'searchValue'> & { sortValue: *, searchValue: * }}
+ */
+export const colDefaults = {
+  key: '',
+  title: null,
+  dataType: 'string',
+  render: null,
+  tfootRender: null,
+  rowHeading: false,
+  searchable: true,
+  sortable: true,
+  sortValue: undefined,
+  searchValue: undefined,
+  condition: true,
+  headerClass: null,
+  cellClass: null
+};
+
+
+/**
+ * Normalizes the `cols` param: applies the column defaults and the data type `colDefaults`,
+ * resolves the `type`/`dataType` alias, the `condition` and the `headerClass`/`cellClass`
+ * fallbacks, and drops the columns whose `condition` is false.
+ *
+ * `cols` is required: an empty or missing definition throws.
+ *
+ * Merge order (lowest first): `colDefaults` ← data type `colDefaults` ← column definition.
+ * Class resolution: `headerClass` = column `headerClass` ?? column `cellClass` ?? type `headerClass`;
+ * `cellClass` = column `cellClass` ?? column `headerClass` ?? type `cellClass`.
+ *
+ * @param {ColDefinition[]|null|undefined} cols - Columns definition (`params.cols`)
+ * @param {Object<string, DataTypeDefinition>} dataTypes - Data types map (see `buildDataTypes`)
+ * @param {JsonTableParams} params - Resolved params (passed to `condition` functions)
+ * @returns {ParsedCol[]} Visible columns only
+ * @throws {Error} On missing/empty `cols`, missing `key` or unknown data type
+ *
+ * @example
+ * parseCols([
+ *   { key: 'id', dataType: 'id' },                       // title: 'id' (default: key)
+ *   { key: 'name', title: 'Nome', cellClass: 'fw-bold' }, // headerClass: 'fw-bold' (default: cellClass)
+ *   { key: 'amount', type: 'euro', tfootRender: '@sum' }, // `type` alias of `dataType`
+ *   { key: 'notes', condition: false }                     // dropped
+ * ], dataTypes, params);
+ */
+export function parseCols(cols, dataTypes, params) {
+
+  if (!Array.isArray(cols) || !cols.length) {
+    throw new Error('[json-table] parametro `cols` mancante o vuoto: la definizione delle colonne è obbligatoria');
+  }
+
+  return cols
+    .map((col, idx) => {
+
+      if (col == null || typeof col !== 'object') {
+        throw new Error(`[json-table] colonna #${idx}: definizione non valida`);
+      }
+
+      const dataType = col.dataType ?? col.type ?? 'string';
+      const type = dataTypes[dataType];
+
+      if (!type) {
+        throw new Error(`[json-table] colonna #${idx} (${col.key}): dataType \`${dataType}\` non definito`);
+      }
+
+      // `type` is only an alias of `dataType`: dropped from the merged definition
+      const colProps = { ...col };
+      delete colProps.type;
+
+      const merged = {
+        ...colDefaults,
+        ...(type.colDefaults ?? {}),
+        ...colProps,
+        dataType
+      };
+
+      if (!merged.key || typeof merged.key !== 'string') {
+        throw new Error(`[json-table] colonna #${idx}: parametro \`key\` mancante`);
+      }
+
+      const condition = typeof merged.condition === 'function'
+        ? merged.condition(params)
+        : (merged.condition ?? true);
+
+      return /** @type {ParsedCol} */ ({
+        ...merged,
+        title: merged.title ?? merged.key,
+        condition: Boolean(condition),
+        headerClass: merged.headerClass ?? merged.cellClass ?? type.headerClass ?? null,
+        cellClass: merged.cellClass ?? merged.headerClass ?? type.cellClass ?? null,
+        _type: type
+      });
+    })
+    .filter(col => col.condition);
+}