@massimo-cassandro/minimo 1.33.0 → 1.33.1

package/src/web-components/json-table/src/cell-content.js

@@ -0,0 +1,136 @@
+/*! minimo - json-table: cell & footer content */
+
+import { getNestedValue, resolveMustache } from './content-utils.js';
+import { toNumber } from './data-types.js';
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./defaults.js').CellContent} CellContent */
+/** @typedef {import('./parse-cols.js').ParsedCol} ParsedCol */
+
+/**
+ * Computes the content of a body cell.
+ *
+ * Pipeline:
+ * 1. column `render`: function `(row, tr, td)` or mustache-like string (`[[key]]`); a function
+ *    returning `undefined` lets the pipeline go on (useful to only decorate `td`/`tr`), `null`
+ *    gives `renderNullAs`
+ * 2. `null`/`undefined` raw value → `renderNullAs`
+ * 3. data type `render(value, row, params)`
+ * 4. raw value
+ *
+ * @param {ParsedCol} col - Parsed column
+ * @param {Object} row - Row object
+ * @param {JsonTableParams} params - Resolved params
+ * @param {HTMLTableRowElement} [tr] - Row element, passed to the column `render`
+ * @param {HTMLTableCellElement} [td] - Cell element, passed to the column `render`
+ * @returns {CellContent}
+ *
+ * @example
+ * cellContent({ ...col, key: 'amount', _type: types.euro }, { amount: 12 }, params);   // → '12,00 €'
+ * cellContent({ ...col, key: 'amount', _type: types.euro }, { amount: null }, params); // → '—' (renderNullAs)
+ * cellContent({ ...col, render: '<b>[[name]]</b>' }, { name: 'Mario' }, params);      // → '<b>Mario</b>'
+ * cellContent({ ...col, render: (row, tr, td) => { td.title = row.name; } }, row, params, tr, td);
+ * // → data type / raw value (render returned undefined)
+ */
+export function cellContent(col, row, params, tr, td) {
+
+  const nullAs = params.renderNullAs ?? '';
+
+  if (col.render != null) {
+    const content = typeof col.render === 'function'
+      ? col.render(row, tr, td)
+      : resolveMustache(String(col.render), row, nullAs);
+
+    if (content !== undefined) {
+      return content ?? nullAs;
+    }
+  }
+
+  const value = getNestedValue(row, col.key);
+
+  if (value == null) {
+    return nullAs;
+  }
+
+  if (typeof col._type.render === 'function') {
+    return col._type.render(value, row, params) ?? nullAs;
+  }
+
+  return value;
+}
+
+
+/**
+ * Built-in footer aggregates (`tfootRender: '@sum'`, ...), computed on the numeric values
+ * of the column (non-numeric values are skipped).
+ * @type {Object<string, (nums: number[]) => number>}
+ */
+const aggregates = {
+  '@sum': nums => nums.reduce((acc, n) => acc + n, 0),
+  '@avg': nums => (nums.length ? nums.reduce((acc, n) => acc + n, 0) / nums.length : NaN),
+  '@min': nums => (nums.length ? Math.min(...nums) : NaN),
+  '@max': nums => (nums.length ? Math.max(...nums) : NaN),
+  '@count': nums => nums.length
+};
+
+
+/**
+ * Computes the content of a footer cell from the column `tfootRender`:
+ * - function `(rows, td) => content`
+ * - built-in aggregate `'@sum'`, `'@avg'`, `'@min'`, `'@max'` (formatted by the column data
+ *   type, e.g. as currency for `euro` columns) or `'@count'` (number of numeric values)
+ * - any other string: static content (e.g. a "Totale" label)
+ * - `null`: empty cell
+ *
+ * @param {ParsedCol} col - Parsed column
+ * @param {Array<Object>} rows - Rows to aggregate (filtered set or current page, see `updateFooterOnPageChange`)
+ * @param {JsonTableParams} params - Resolved params
+ * @param {HTMLTableCellElement} [td] - Footer cell element, passed to the `tfootRender` function
+ * @returns {CellContent}
+ *
+ * @example
+ * tfootContent({ ...col, key: 'amount', tfootRender: '@sum', _type: types.euro }, rows, params); // → '1.234,56 €'
+ * tfootContent({ ...col, tfootRender: 'Totale' }, rows, params);                                 // → 'Totale'
+ * tfootContent({ ...col, tfootRender: rows => `${rows.length} righe` }, rows, params);           // → '10 righe'
+ * tfootContent({ ...col, tfootRender: null }, rows, params);                                     // → ''
+ */
+export function tfootContent(col, rows, params, td) {
+
+  const renderer = col.tfootRender;
+
+  if (renderer == null) {
+    return '';
+  }
+
+  if (typeof renderer === 'function') {
+    return renderer(rows, td) ?? '';
+  }
+
+  const tpl = String(renderer);
+
+  if (tpl.startsWith('@')) {
+    const aggregate = aggregates[tpl];
+
+    if (!aggregate) {
+      // eslint-disable-next-line no-console
+      console.error(`[json-table] colonna \`${col.key}\`: aggregato \`${tpl}\` non riconosciuto (disponibili: ${Object.keys(aggregates).join(', ')})`);
+      return '';
+    }
+
+    const nums = rows
+      .map(row => toNumber(getNestedValue(row, col.key)))
+      .filter(n => !Number.isNaN(n));
+
+    const result = aggregate(nums);
+
+    if (tpl === '@count') {
+      return result.toLocaleString(params.locale);
+    }
+
+    return typeof col._type.render === 'function'
+      ? col._type.render(result, null, params)
+      : result.toLocaleString(params.locale, params.numbersLocaleOpts);
+  }
+
+  return tpl;
+}

package/src/web-components/json-table/src/content-utils.js

@@ -0,0 +1,103 @@
+/*! minimo - json-table: content utilities */
+
+import { domBuilder } from '../../../utilities/dom-builder/dom-builder.js';
+
+/** @typedef {import('./defaults.js').CellContent} CellContent */
+
+/**
+ * Replaces the content of `el` with `content`, accepting every content form used by the
+ * component (see `CellContent`): a Node is appended as-is, a domBuilder array is built inside
+ * the element, a string/number is set as text or, when it contains `<`, as sanitized markup
+ * (`Element.setHTML` where supported, `innerHTML` otherwise, consistently with domBuilder).
+ * The empty sanitizer config passed to `setHTML` keeps `class`, `id`, `style` and `data-*`
+ * attributes, which the browser default configuration removes, while unsafe content (scripts,
+ * event handlers, `javascript:` URLs) is always stripped.
+ * A function is invoked and its result used. `null`/`undefined` empty the element.
+ *
+ * @param {HTMLElement} el - Target element (emptied first)
+ * @param {CellContent|(() => CellContent)} content - Content to set
+ * @returns {void}
+ *
+ * @example
+ * setContent(td, 'plain text');
+ * setContent(td, 'a <strong>bold</strong> text');
+ * setContent(td, 1234);
+ * setContent(td, document.createElement('span'));
+ * setContent(td, [{ tag: 'a', attrs: { href: '#' }, content: 'link' }]);
+ * setContent(td, null); // → empty cell
+ */
+export function setContent(el, content) {
+
+  const resolved = typeof content === 'function' ? content() : content;
+
+  if (resolved == null) {
+    el.replaceChildren();
+    return;
+  }
+
+  if (resolved instanceof Node) {
+    el.replaceChildren(resolved);
+    return;
+  }
+
+  if (Array.isArray(resolved)) {
+    domBuilder(resolved, el, { emptyParent: true });
+    return;
+  }
+
+  const text = String(resolved);
+
+  if (!text.includes('<')) {
+    el.textContent = text;
+
+  } else if (typeof el.setHTML === 'function') {
+    el.setHTML(text, { sanitizer: {} });
+
+  } else {
+    el.innerHTML = text;
+  }
+}
+
+
+/**
+ * Reads a value from an object through a dot-separated key path.
+ * Returns `undefined` when an intermediate key does not exist.
+ *
+ * @param {Object|null|undefined} obj - Source object
+ * @param {string} path - Key or dot-separated path
+ * @returns {*}
+ *
+ * @example
+ * getNestedValue({ owner: { name: 'Mario' } }, 'owner.name'); // → 'Mario'
+ * getNestedValue({ name: 'Mario' }, 'name');                  // → 'Mario'
+ * getNestedValue({ name: 'Mario' }, 'owner.name');            // → undefined
+ */
+export function getNestedValue(obj, path) {
+  return path.split('.').reduce(
+    (acc, key) => (acc == null ? undefined : /** @type {Object<string, *>} */ (acc)[key]),
+    /** @type {*} */ (obj)
+  );
+}
+
+
+/**
+ * Resolves a mustache-like template: every `[[key]]` placeholder is replaced with the
+ * corresponding row value (nested keys allowed); placeholders resolving to `null`/`undefined`
+ * are replaced with `nullAs`. Useful for the js-free configuration via HTML attributes.
+ *
+ * @param {string} tpl - Template string
+ * @param {Object} row - Row object
+ * @param {string} [nullAs=''] - Replacement of null/undefined values (default: '')
+ * @returns {string}
+ *
+ * @example
+ * resolveMustache('<a href="/users/[[id]]">[[name]]</a>', { id: 12, name: 'Mario' });
+ * // → '<a href="/users/12">Mario</a>'
+ * resolveMustache('[[owner.name]]', { owner: null }, '—'); // → '—'
+ */
+export function resolveMustache(tpl, row, nullAs = '') {
+  return tpl.replace(/\[\[(.*?)\]\]/g, (_, key) => {
+    const value = getNestedValue(row, key.trim());
+    return value == null ? nullAs : String(value);
+  });
+}

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

@@ -0,0 +1,280 @@
+/*! minimo - json-table: data types */
+
+import * as styles from '../json-table-component.module.css';
+import { classnames } from '../../../utilities/classnames.js';
+import { iconContent } from './icons.js';
+
+/** @typedef {import('./defaults.js').JsonTableParams} JsonTableParams */
+/** @typedef {import('./defaults.js').DataTypeDefinition} DataTypeDefinition */
+
+/**
+ * Converts a value to a number; empty strings and nullish values give `NaN`.
+ * @param {*} value
+ * @returns {number}
+ *
+ * @example
+ * toNumber('12.5'); // → 12.5
+ * toNumber('');     // → NaN
+ * toNumber(null);   // → NaN
+ */
+export function toNumber(value) {
+  if (value == null || value === '' || typeof value === 'boolean') {
+    return NaN;
+  }
+  return typeof value === 'number' ? value : Number(value);
+}
+
+
+/**
+ * Converts a boolean-like value (`true`/`false`, `1`/`0`, `'1'`/`'0'`, `'true'`/`'false'`)
+ * to a boolean; every other value gives `null`, so that `null` can be told apart from `false`.
+ * @param {*} value
+ * @returns {boolean|null}
+ *
+ * @example
+ * toBool(1);       // → true
+ * toBool('false'); // → false
+ * toBool(null);    // → null
+ * toBool('abc');   // → null
+ */
+export function toBool(value) {
+  if (value === true || value === 1 || value === '1' || value === 'true') {
+    return true;
+  }
+  if (value === false || value === 0 || value === '0' || value === 'false') {
+    return false;
+  }
+  return null;
+}
+
+
+/**
+ * Parses a date-like value: ISO string, timestamp, `Date` object or a Symfony-like object
+ * (`{ date: '2022-12-02 06:18:55', timezone_type: 3, timezone: 'Europe/Berlin' }`).
+ * TODO fuso orario degli oggetti Symfony non gestito (la stringa `date` è interpretata come ora locale)
+ * @param {*} value
+ * @returns {Date|null} `null` for empty or invalid values
+ *
+ * @example
+ * parseDate('2024-01-31');                       // → Date
+ * parseDate({ date: '2024-01-31 01:33:10' });    // → Date
+ * parseDate('');                                 // → null
+ */
+export function parseDate(value) {
+  if (value == null || value === '') {
+    return null;
+  }
+  let date;
+  if (value instanceof Date) {
+    date = value;
+  } else if (typeof value === 'object' && Object.hasOwn(value, 'date')) {
+    date = new Date(String(value.date).replace(' ', 'T'));
+  } else {
+    date = new Date(value);
+  }
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+
+/**
+ * Formats a numeric value, applying `renderNaNAs` and `renderZeroAs`.
+ * @param {*} value - Raw value
+ * @param {JsonTableParams} params - Resolved params
+ * @param {Intl.NumberFormatOptions} formatOpts - `toLocaleString` options
+ * @param {(formatted: string, num: number) => string} [wrap] - Optional decorator of the formatted string
+ * @returns {string}
+ *
+ * @example
+ * formatNumber(1529.42, params, { maximumFractionDigits: 2 });            // → '1.529,42' (it-IT)
+ * formatNumber('abc', params, {});                                        // → params.renderNaNAs ('—')
+ * formatNumber(0, { ...params, renderZeroAs: '-' }, {});                  // → '-'
+ * formatNumber(4.63, params, {}, s => `${s}\u202F<small>%</small>`);      // → '4,63 <small>%</small>'
+ */
+export function formatNumber(value, params, formatOpts, wrap) {
+  const num = toNumber(value);
+  if (Number.isNaN(num)) {
+    return params.renderNaNAs ?? '';
+  }
+  if (num === 0 && params.renderZeroAs != null) {
+    return params.renderZeroAs;
+  }
+  const formatted = num.toLocaleString(params.locale, formatOpts);
+  return wrap ? wrap(formatted, num) : formatted;
+}
+
+
+/**
+ * Built-in data types, built on the resolved params (class names, locale options, icons).
+ *
+ * | key           | description                                                     | cell classes            |
+ * |---------------|-----------------------------------------------------------------|-------------------------|
+ * | `string`      | default type, value as-is                                       | –                       |
+ * | `num`         | number formatted with `numbersLocaleOpts`                       | textEnd numeric nowrap  |
+ * | `id`          | numeric id: raw value, right aligned, not searchable            | textEnd numeric         |
+ * | `perc`        | percentage already in 0–100 scale, `currPercLocaleOpts` + " %"  | textEnd numeric nowrap  |
+ * | `percDecimal` | percentage in 0–1 scale (multiplied by 100)                     | textEnd numeric nowrap  |
+ * | `currency`    | `Intl` currency format, `params.currency`                       | textEnd numeric nowrap  |
+ * | `euro`        | as `currency`, EUR forced                                       | textEnd numeric nowrap  |
+ * | `date`        | `<time>` element, `datesLocaleOpts`                             | textEnd nowrap          |
+ * | `datetime`    | as `date`, plus time part (`timesLocaleOpts`)                   | textEnd nowrap          |
+ * | `bool`        | `boolTrueIcon`/`boolFalseIcon`; not sortable/searchable         | (internal icon styles)  |
+ * | `email`       | soft line breaks around `@`                                     | –                       |
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @returns {Object<string, DataTypeDefinition>}
+ *
+ * @example
+ * const types = builtInDataTypes(params);
+ * types.num.render(1529.42, row, params); // → '1.529,42'
+ */
+export function builtInDataTypes(params) {
+
+  const c = params.classes;
+  const numericClass = classnames(c.textEnd, c.numeric, c.nowrap);
+  const dateClass = classnames(c.textEnd, c.nowrap);
+
+  /** @type {(formatOpts: Intl.NumberFormatOptions, wrap?: (formatted: string, num: number) => string) => DataTypeDefinition} */
+  const numericType = (formatOpts, wrap) => ({
+    headerClass: numericClass,
+    cellClass: numericClass,
+    render: (value, row, p) => formatNumber(value, p, formatOpts, wrap),
+    sortValue: value => toNumber(value),
+    searchValue: (value, row, p) => {
+      const num = toNumber(value);
+      return Number.isNaN(num) ? '' : num.toLocaleString(p.locale, formatOpts);
+    }
+  });
+
+  // TODO implementare sfTime / sfDatetime (??)
+  /** @type {(withTime: boolean) => DataTypeDefinition} */
+  const dateType = withTime => ({
+    headerClass: dateClass,
+    cellClass: dateClass,
+    render: (value, row, p) => {
+      const date = parseDate(value);
+      if (!date) {
+        return p.renderNaNAs ?? '';
+      }
+      const iso = date.toISOString();
+      return `<time datetime="${withTime ? iso : iso.substring(0, 10)}">` +
+        `<span class="${c.nowrap}">` + date.toLocaleString(p.locale, p.datesLocaleOpts) + '</span>' +
+        (withTime ? ' <small>' + date.toLocaleString(p.locale, p.timesLocaleOpts) + '</small>' : '') +
+        '</time>';
+    },
+    sortValue: value => parseDate(value)?.getTime() ?? null,
+    searchValue: (value, row, p) => {
+      const date = parseDate(value);
+      return date
+        ? date.toLocaleString(p.locale, { ...p.datesLocaleOpts, ...(withTime ? p.timesLocaleOpts : {}) })
+        : '';
+    }
+  });
+
+  const percWrap = /** @type {(formatted: string) => string} */ (formatted => `${formatted}\u202F<small>%</small>`);
+
+  return {
+
+    string: {},
+
+    num: numericType(params.numbersLocaleOpts),
+
+    id: {
+      headerClass: classnames(c.textEnd, c.numeric),
+      cellClass: classnames(c.textEnd, c.numeric),
+      sortValue: value => toNumber(value),
+      colDefaults: { searchable: false }
+    },
+
+    perc: numericType(params.currPercLocaleOpts, percWrap),
+
+    percDecimal: {
+      ...numericType(params.currPercLocaleOpts, percWrap),
+      render: (value, row, p) => formatNumber(toNumber(value) * 100, p, p.currPercLocaleOpts, percWrap)
+    },
+
+    currency: numericType({ style: 'currency', currency: params.currency, ...params.currPercLocaleOpts }),
+
+    euro: numericType({ style: 'currency', currency: 'EUR', ...params.currPercLocaleOpts }),
+
+    date: dateType(false),
+
+    datetime: dateType(true),
+
+    bool: {
+      headerClass: c.textCenter,
+      cellClass: null,
+      internalCellClass: value => {
+        const bool = toBool(value);
+        return classnames(
+          styles.boolCell, c.boolCell,
+          bool === true && [styles.boolTrue, c.boolTrue],
+          bool === false && [styles.boolFalse, c.boolFalse]
+        );
+      },
+      render: (value, row, p) => {
+        const bool = toBool(value);
+        if (bool === true) {
+          return iconContent(p.boolTrueIcon);
+        }
+        if (bool === false) {
+          return iconContent(p.boolFalseIcon);
+        }
+        return p.renderNullAs ?? '';
+      },
+      sortValue: value => {
+        const bool = toBool(value);
+        return bool === null ? -1 : (bool ? 1 : 0);
+      },
+      searchValue: () => '',
+      colDefaults: { sortable: false, searchable: false }
+    },
+
+    email: {
+      render: value => String(value).replace('@', '<wbr>@<wbr>')
+    }
+  };
+}
+
+
+/**
+ * Merges the custom data types (`params.dataTypes`) with the built-in ones.
+ *
+ * A custom key matching a built-in type overrides only the given properties; a new key can
+ * extend a built-in type via `inheritsFrom`.
+ *
+ * @param {JsonTableParams} params - Resolved params
+ * @returns {Object<string, DataTypeDefinition>} The complete data types map
+ * @throws {Error} When `inheritsFrom` refers to an unknown type
+ *
+ * @example
+ * const types = buildDataTypes({
+ *   ...params,
+ *   dataTypes: {
+ *     num: { cellClass: 'text-end fw-bold' },                 // overrides only `cellClass` of the built-in `num`
+ *     km: { inheritsFrom: 'num', render: v => `${v} km` }     // new type based on `num`
+ *   }
+ * });
+ */
+export function buildDataTypes(params) {
+
+  const builtIn = builtInDataTypes(params);
+  const result = { ...builtIn };
+
+  for (const [key, def] of Object.entries(params.dataTypes ?? {})) {
+
+    if (def == null || typeof def !== 'object') {
+      continue;
+    }
+
+    const baseKey = builtIn[key] ? key : def.inheritsFrom;
+    const base = baseKey ? result[baseKey] : null;
+
+    if (def.inheritsFrom && !base) {
+      throw new Error(`[json-table] dataType \`${key}\`: \`inheritsFrom\` fa riferimento a un tipo inesistente (${def.inheritsFrom})`);
+    }
+
+    result[key] = { ...(base ?? {}), ...def };
+  }
+
+  return result;
+}