@massimo-cassandro/minimo 1.33.0 → 1.33.1

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

@@ -0,0 +1,111 @@
+/*! minimo - json-table: client-side sorting */
+
+/** @typedef {import('./parse-rows.js').ParsedRow} ParsedRow */
+/** @typedef {'asc'|'desc'} SortDir */
+
+/**
+ * Whether a sort value counts as "empty" (sorted last in both directions).
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isEmpty(value) {
+  return value == null || value === '' || (typeof value === 'number' && Number.isNaN(value));
+}
+
+/**
+ * Whether a value is a number or a numeric string.
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isNumeric(value) {
+  if (typeof value === 'number') {
+    return !Number.isNaN(value);
+  }
+  return typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value));
+}
+
+
+/**
+ * Compares two sort values in ascending order: empty values (`null`, `undefined`, `''`, `NaN`)
+ * always last, numbers (and numeric strings, when both are numeric) numerically, booleans as
+ * 0/1, everything else as strings via `localeCompare` (numeric collation, accent/case insensitive).
+ *
+ * @param {*} a
+ * @param {*} b
+ * @param {string} [locale] - Locale used by `localeCompare` (default: browser default)
+ * @returns {number} Negative when `a` comes first, positive when `b` comes first, 0 when equal
+ *
+ * @example
+ * compareValues(2, 10);                  // → negative
+ * compareValues('file10', 'file2');      // → positive (numeric collation)
+ * compareValues('à', 'b', 'it-IT');      // → negative
+ * compareValues(null, 'a');              // → positive (empty values last)
+ */
+export function compareValues(a, b, locale) {
+
+  const emptyA = isEmpty(a);
+  const emptyB = isEmpty(b);
+
+  if (emptyA || emptyB) {
+    return emptyA === emptyB ? 0 : (emptyA ? 1 : -1);
+  }
+
+  if (typeof a === 'boolean' && typeof b === 'boolean') {
+    return Number(a) - Number(b);
+  }
+
+  if (isNumeric(a) && isNumeric(b)) {
+    return Number(a) - Number(b);
+  }
+
+  return String(a).localeCompare(String(b), locale, { numeric: true, sensitivity: 'base' });
+}
+
+
+/**
+ * Returns a sorted copy of the parsed rows, by the precomputed `sortValues[key]` of every row.
+ * The sort is stable, so rows with equal values keep their original order.
+ *
+ * @param {ParsedRow[]} rows - Parsed rows (see `parse-rows.js`)
+ * @param {string} key - Column key
+ * @param {SortDir} dir - Direction
+ * @param {string} [locale] - Locale used to compare strings
+ * @returns {ParsedRow[]} A new array
+ *
+ * @example
+ * sortRows(state.rows, 'amount', 'desc', 'it-IT');
+ */
+export function sortRows(rows, key, dir, locale) {
+
+  const sign = dir === 'desc' ? -1 : 1;
+
+  return [...rows].sort((a, b) => {
+    const va = a.sortValues[key];
+    const vb = b.sortValues[key];
+    const cmp = compareValues(va, vb, locale);
+    // empty values stay last regardless of the direction
+    return (isEmpty(va) || isEmpty(vb)) ? cmp : cmp * sign;
+  });
+}
+
+
+/**
+ * Next direction in the sort cycle of a column button: none → `asc` → `desc` → none.
+ *
+ * @param {SortDir|null|undefined} current - Current direction of the column (null = not sorted)
+ * @returns {SortDir|null}
+ *
+ * @example
+ * nextSortDir(null);   // → 'asc'
+ * nextSortDir('asc');  // → 'desc'
+ * nextSortDir('desc'); // → null
+ */
+export function nextSortDir(current) {
+  if (current === 'asc') {
+    return 'desc';
+  }
+  if (current === 'desc') {
+    return null;
+  }
+  return 'asc';
+}

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

@@ -0,0 +1,109 @@
+/*! minimo - json-table: tbody rendering */
+
+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 { setContent, getNestedValue } from './content-utils.js';
+import { cellContent } from './cell-content.js';
+
+/** @typedef {import('../json-table-component.js').JsonTable} JsonTable */
+/** @typedef {import('./parse-rows.js').ParsedRow} ParsedRow */
+
+/**
+ * domBuilder item of a body row.
+ *
+ * Cells are created empty by domBuilder (tag, classes, attributes) and filled in the `<tr>`
+ * callback, so that the column `render` functions receive both the `tr` and the `td` elements.
+ * `trCallback` is invoked last.
+ *
+ * Generated structure:
+ * ```
+ * tr[data-jt-idx]
+ *   td[data-key][cellClass][internalCellClass]           ← cellContent()
+ *   th[scope=row][data-key]…                             ← when col.rowHeading is true
+ * ```
+ *
+ * @param {ParsedRow} parsed - Parsed row (see `parse-rows.js`)
+ * @param {JsonTable} jt - The component instance (`params`, `cols`)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * domBuilder([rowItem(parsedRow, jt)], tbody);
+ */
+export function rowItem(parsed, jt) {
+
+  const { params, cols } = jt;
+  const row = parsed.row;
+
+  return {
+    tag: 'tr',
+    attrs: { 'data-jt-idx': parsed.idx },
+    children: cols.map(col => ({
+      tag: col.rowHeading ? 'th' : 'td',
+      className: classnames(
+        col.cellClass,
+        typeof col._type.internalCellClass === 'function'
+          ? col._type.internalCellClass(getNestedValue(row, col.key), row, params)
+          : null
+      ),
+      attrs: {
+        scope: col.rowHeading ? 'row' : null,
+        'data-key': col.key
+      }
+    })),
+    callback: el => {
+      const tr = /** @type {HTMLTableRowElement} */ (el);
+      const cells = tr.cells;
+
+      cols.forEach((col, i) => {
+        const td = cells[i];
+        setContent(td, cellContent(col, row, params, tr, td));
+      });
+
+      if (typeof params.trCallback === 'function') {
+        params.trCallback(tr, row, params);
+      }
+    }
+  };
+}
+
+
+/**
+ * Renders the rows of the current page (`state.pageRows`) inside `elements.tbody`, replacing
+ * the previous content. When there are no rows, a single cell spanning every column shows
+ * `labels.noResults` (search active) or `labels.noRows`.
+ *
+ * @param {JsonTable} jt - The component instance
+ * @returns {void}
+ *
+ * @example
+ * renderTbody(jt); // after `jt.state` has been updated
+ */
+export function renderTbody(jt) {
+
+  const { params, elements, state, cols } = jt;
+  const tbody = elements.tbody;
+
+  if (!tbody) {
+    return;
+  }
+
+  if (!state.pageRows.length) {
+    domBuilder([
+      {
+        tag: 'tr',
+        children: [
+          {
+            tag: 'td',
+            className: classnames(styles.empty, params.classes.empty),
+            attrs: { colspan: Math.max(cols.length, 1) },
+            content: state.searchTerm ? params.labels.noResults : params.labels.noRows
+          }
+        ]
+      }
+    ], tbody, { emptyParent: true });
+    return;
+  }
+
+  domBuilder(state.pageRows.map(parsed => rowItem(parsed, jt)), tbody, { emptyParent: true });
+}

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

@@ -0,0 +1,152 @@
+/*! minimo - json-table: table part (table, caption and footer bar) */
+
+import * as styles from '../json-table-component.module.css';
+import { classnames } from '../../../utilities/classnames.js';
+import { theadPart } from './table-thead.js';
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('../json-table-component.js').JsonTable} JsonTable */
+/** @typedef {import('./main-builder.js').JsonTableElements} JsonTableElements */
+
+/** Counter used to generate unique caption ids */
+let captionUid = 0;
+
+/**
+ * Id of the caption element of a table (used by `aria-labelledby`): `<tableId>-caption`, or a
+ * generated unique id when `tableId` is not set.
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @returns {string}
+ *
+ * @example
+ * captionId({ ...params, tableId: 'users' }); // → 'users-caption'
+ * captionId(params);                          // → 'jt-1-caption'
+ */
+export function captionId(params) {
+  return params.tableId ? `${params.tableId}-caption` : `jt-${++captionUid}-caption`;
+}
+
+
+/**
+ * domBuilder item of the caption (template slot `caption`), rendered only when `params.caption`
+ * is set. It is a plain container placed below the table (footer bar) instead of a `<caption>`
+ * element: the table is linked to it through `aria-labelledby`, which gives the table the same
+ * accessible name a `<caption>` would.
+ *
+ * Generated structure: `div.caption[classes.caption]#<id>`; the element is stored in `elements.caption`.
+ *
+ * @param {JsonTable} jt - The component instance
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @param {string} id - Id of the element (see `captionId`)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * domBuilder([captionPart(jt, elements, 'users-caption')], host);
+ * elements.caption; // → HTMLElement (when params.caption is set)
+ */
+export function captionPart(jt, elements, id) {
+
+  const { params } = jt;
+
+  return {
+    id,
+    condition: params.caption != null,
+    className: classnames(styles.caption, params.classes.caption),
+    content: params.caption,
+    callback: el => { elements.caption = /** @type {HTMLElement} */ (el); }
+  };
+}
+
+
+/**
+ * domBuilder item of the footer bar below the table: caption (start side) and pagination (end
+ * side). Rendered only when `children` is not empty (see `mainBuilder`, which removes the parts
+ * placed elsewhere by the template).
+ *
+ * Generated structure: `div.tableFooter[classes.tableFooter] > [caption] [pagination]`; the element
+ * is stored in `elements.tableFooter`.
+ *
+ * @param {JsonTable} jt - The component instance
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @param {DomBuilderItem[]} children - Footer parts (caption and/or pagination items)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * const footer = tableFooterPart(jt, elements, [captionItem, paginationItem]);
+ * domBuilder([tablePart(jt, elements, footer)], host);
+ */
+export function tableFooterPart(jt, elements, children) {
+
+  const { params } = jt;
+
+  return {
+    condition: children.length > 0,
+    className: classnames(styles.tableFooter, params.classes.tableFooter),
+    children,
+    callback: el => { elements.tableFooter = /** @type {HTMLElement} */ (el); }
+  };
+}
+
+
+/**
+ * domBuilder item of the table (template slot `table`).
+ *
+ * Generated structure:
+ * ```
+ * div.tableWrapper[classes.tableWrapper]
+ *   table#tableId.table[classes.table][aria-labelledby=<caption id>]   (aria-labelledby if `caption`)
+ *     thead                     ← theadPart()
+ *     tbody                     ← filled by `renderTbody()`
+ *     tfoot                     (if `tfoot`) ← filled by `renderTfoot()`
+ * div.tableFooter               ← footerBar (caption + pagination), if given
+ * ```
+ *
+ * References to the generated elements are stored in `elements`
+ * (`tableWrapper`, `table`, `thead`, `tbody`, `tfoot`).
+ *
+ * @param {JsonTable} jt - The component instance (`params`, `cols`)
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @param {DomBuilderItem|null} [footerBar=null] - Footer bar item (see `tableFooterPart`) (default: null)
+ * @param {string|null} [captionElId=null] - Id of the caption element, for `aria-labelledby` (default: null)
+ * @returns {DomBuilderItem} A `div` wrapping the table wrapper and the footer bar
+ *
+ * @example
+ * domBuilder([tablePart(jt, elements, footerBar, 'users-caption')], host);
+ * elements.tbody; // → HTMLTableSectionElement (empty until renderTbody() is called)
+ */
+export function tablePart(jt, elements, footerBar = null, captionElId = null) {
+
+  const { params } = jt;
+
+  return {
+    className: styles.tableOuter,
+    children: [
+      {
+        className: classnames(styles.tableWrapper, params.classes.tableWrapper),
+        callback: el => { elements.tableWrapper = /** @type {HTMLElement} */ (el); },
+        children: [
+          {
+            tag: 'table',
+            id: params.tableId,
+            className: classnames(styles.table, params.classes.table),
+            attrs: { 'aria-labelledby': params.caption != null ? captionElId : null },
+            callback: el => { elements.table = /** @type {HTMLTableElement} */ (el); },
+            children: [
+              theadPart(jt, elements),
+              {
+                tag: 'tbody',
+                callback: el => { elements.tbody = /** @type {HTMLTableSectionElement} */ (el); }
+              },
+              {
+                tag: 'tfoot',
+                condition: params.tfoot,
+                callback: el => { elements.tfoot = /** @type {HTMLTableSectionElement} */ (el); }
+              }
+            ]
+          }
+        ]
+      },
+      ...(footerBar ? [footerBar] : [])
+    ]
+  };
+}

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

@@ -0,0 +1,56 @@
+/*! minimo - json-table: tfoot rendering */
+
+import { domBuilder } from '../../../utilities/dom-builder/dom-builder.js';
+import { classnames } from '../../../utilities/classnames.js';
+import { setContent } from './content-utils.js';
+import { tfootContent } from './cell-content.js';
+
+/** @typedef {import('../json-table-component.js').JsonTable} JsonTable */
+
+/**
+ * Renders the footer row inside `elements.tfoot` (present only when `params.tfoot` is true),
+ * replacing the previous content. Every column produces a cell whose content comes from
+ * `tfootContent()` (column `tfootRender`); the footer is emptied when there are no rows.
+ *
+ * The rows passed to `tfootRender` are the whole filtered set, or the current page only when
+ * `updateFooterOnPageChange` is true.
+ *
+ * Generated structure: `tr > td[data-key][cellClass]…`
+ *
+ * @param {JsonTable} jt - The component instance
+ * @returns {void}
+ *
+ * @example
+ * renderTfoot(jt); // after `jt.state` has been updated
+ */
+export function renderTfoot(jt) {
+
+  const { params, elements, state, cols } = jt;
+  const tfoot = elements.tfoot;
+
+  if (!tfoot) {
+    return;
+  }
+
+  if (!state.filtered.length) {
+    tfoot.replaceChildren();
+    return;
+  }
+
+  const rows = (params.updateFooterOnPageChange ? state.pageRows : state.filtered).map(parsed => parsed.row);
+
+  domBuilder([
+    {
+      tag: 'tr',
+      children: cols.map(col => ({
+        tag: 'td',
+        className: classnames(col.cellClass),
+        attrs: { 'data-key': col.key },
+        callback: el => {
+          const td = /** @type {HTMLTableCellElement} */ (el);
+          setContent(td, tfootContent(col, rows, params, td));
+        }
+      }))
+    }
+  ], tfoot, { emptyParent: true });
+}

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

@@ -0,0 +1,183 @@
+/*! minimo - json-table: thead */
+
+import * as styles from '../json-table-component.module.css';
+import { classnames } from '../../../utilities/classnames.js';
+import { setContent } from './content-utils.js';
+import { iconContent } from './icons.js';
+import { nextSortDir } from './sorting.js';
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('../json-table-component.js').JsonTable} JsonTable */
+/** @typedef {import('./main-builder.js').JsonTableElements} JsonTableElements */
+
+/** @typedef {'none'|'ascending'|'descending'} SortState */
+
+/**
+ * Updates the sort state of a sortable `<th>`: `aria-sort` attribute (removed when `none`),
+ * icon and `title`/`aria-label` of the sort button (both describing the action of the next
+ * click, e.g. "sort descending" when the ascending sort is active).
+ *
+ * @param {HTMLTableCellElement} th - The `<th>` generated by `theadPart()`
+ * @param {SortState} state - Sort state to apply
+ * @param {JsonTableParams} params - Resolved params (icons and labels)
+ * @returns {void}
+ *
+ * @example
+ * setSortState(th, 'ascending', params);
+ * // th[aria-sort=ascending], icon → params.sortAscArrowIcon, button title → params.labels.sortDesc
+ */
+export function setSortState(th, state, params) {
+
+  const btn = th.querySelector('button');
+  const icon = th.querySelector('[data-jt-sort-icon]');
+
+  if (state === 'none') {
+    th.removeAttribute('aria-sort');
+  } else {
+    th.setAttribute('aria-sort', state);
+  }
+
+  const nextLabel = state === 'none'
+    ? params.labels.sortAsc
+    : (state === 'ascending' ? params.labels.sortDesc : params.labels.sortNone);
+
+  if (btn) {
+    const titleText = (th.querySelector('[data-jt-sort-title]')?.textContent ?? '').trim();
+    btn.title = nextLabel ?? '';
+    btn.setAttribute('aria-label', titleText ? `${titleText}: ${nextLabel}` : (nextLabel ?? ''));
+  }
+
+  if (icon) {
+    const iconDef = state === 'none'
+      ? params.sortNoneArrowIcon
+      : (state === 'ascending' ? params.sortAscArrowIcon : params.sortDescArrowIcon);
+    setContent(/** @type {HTMLElement} */ (icon), iconContent(iconDef));
+  }
+}
+
+
+/**
+ * Applies the current sort (`jt.state.sort`) to every sortable `<th>` of the thead: the sorted
+ * column gets `aria-sort` and the matching icon, the others are reset to `none`.
+ *
+ * @param {JsonTable} jt - The component instance
+ * @returns {void}
+ *
+ * @example
+ * jt.state.sort = { key: 'name', dir: 'desc' };
+ * applySortState(jt); // th[data-key=name][aria-sort=descending], the other th without aria-sort
+ */
+export function applySortState(jt) {
+
+  const { elements, params, state } = jt;
+
+  if (!elements.thead) {
+    return;
+  }
+
+  elements.thead.querySelectorAll('th[data-sortable]').forEach(el => {
+    const th = /** @type {HTMLTableCellElement} */ (el);
+    const isSorted = state.sort != null && th.dataset.key === state.sort.key;
+    setSortState(th, isSorted ? (state.sort?.dir === 'desc' ? 'descending' : 'ascending') : 'none', params);
+  });
+}
+
+
+/**
+ * Attaches the delegated `click` listener to the thead: a click on a sort button cycles the
+ * column sort (none → asc → desc → none, see `nextSortDir`) through `jt.setSort()`.
+ * The thead is not rebuilt on sort, so the focus stays on the clicked button.
+ *
+ * @param {JsonTable} jt - The component instance
+ * @returns {void}
+ *
+ * @example
+ * setSortListener(jt); // after mainBuilder(jt)
+ */
+export function setSortListener(jt) {
+
+  const thead = jt.elements.thead;
+
+  if (!thead) {
+    return;
+  }
+
+  thead.addEventListener('click', e => {
+    const btn = /** @type {HTMLElement|null} */ (
+      /** @type {HTMLElement} */ (e.target).closest('button[data-key]')
+    );
+    if (!btn) {
+      return;
+    }
+    const key = btn.dataset.key ?? '';
+    const current = jt.state.sort?.key === key ? jt.state.sort.dir : null;
+    jt.setSort(key, nextSortDir(current));
+  });
+}
+
+
+/**
+ * domBuilder item of the `<thead>`.
+ *
+ * Generated structure:
+ * ```
+ * thead > tr
+ *   th[scope=col][data-key][headerClass]                                   ← not sortable: content = col.title
+ *   th.sortable[scope=col][data-key][data-sortable=true][headerClass]      ← sortable
+ *     button.sortBtn[classes.sortBtn][type=button][data-key][title][aria-label]
+ *       span.sortTitle[data-jt-sort-title]  ← col.title
+ *       span.sortIcon[data-jt-sort-icon]    ← sort icon (see `setSortState`)
+ * ```
+ *
+ * The `<thead>` is stored in `elements.thead`; the sort listener is attached by `setSortListener()`.
+ *
+ * @param {JsonTable} jt - The component instance (`params`, `cols`)
+ * @param {JsonTableElements} elements - Object collecting the generated elements (mutated)
+ * @returns {DomBuilderItem}
+ *
+ * @example
+ * domBuilder([{ tag: 'table', children: [theadPart(jt, elements)] }], host);
+ * elements.thead; // → HTMLTableSectionElement
+ */
+export function theadPart(jt, elements) {
+
+  const { params, cols } = jt;
+
+  return {
+    tag: 'thead',
+    callback: el => { elements.thead = /** @type {HTMLTableSectionElement} */ (el); },
+    children: [
+      {
+        tag: 'tr',
+        children: cols.map(col => ({
+          tag: 'th',
+          className: classnames(col.headerClass, col.sortable && styles.sortable),
+          attrs: {
+            scope: 'col',
+            'data-key': col.key,
+            'data-sortable': col.sortable ? 'true' : null
+          },
+          content: col.sortable ? null : col.title,
+          children: col.sortable
+            ? [
+              {
+                tag: 'button',
+                className: classnames(styles.sortBtn, params.classes.sortBtn),
+                attrs: { type: 'button', 'data-key': col.key },
+                children: [
+                  { tag: 'span', className: styles.sortTitle, attrs: { 'data-jt-sort-title': '' }, content: col.title },
+                  { tag: 'span', className: styles.sortIcon, attrs: { 'data-jt-sort-icon': '', 'aria-hidden': 'true' } }
+                ]
+              }
+            ]
+            : [],
+          callback: el => {
+            if (col.sortable) {
+              setSortState(/** @type {HTMLTableCellElement} */ (el), 'none', params);
+            }
+          }
+        }))
+      }
+    ]
+  };
+}