@massimo-cassandro/minimo 1.6.0 → 1.7.0

package/index.js

@@ -1,15 +1,22 @@
 
 // utilities
+export { betterText } from './src/utilities/better-text.js';
 export { classnames, classnamesNull } from './src/utilities/classnames.js';
+export { createId } from './src/utilities/create-id.js';
 export { domBuilder } from './src/utilities/dom-builder/dom-builder.js';
 export { enableSubmitBtns } from './src/utilities/enable-submit-btns.js';
-export { titleCase } from './src/utilities/title-case.js';
+export { escapeHTML, unescapeHTML } from './src/utilities/escape-html.js';
+export { getCookie, setCookie } from './src/utilities/cookies.js';
+export { linkedDates } from './src/utilities/linked-dates.js';
+export { relativeDate } from './src/utilities/relative-date.js';
 export { sentenceCase } from './src/utilities/sentence-case.js';
-export { escapeHTML, unescapeHTML } from './src/utilities/escapeHTML.js';
+export { stripTags } from './src/utilities/strip-tags.js';
+export { titleCase } from './src/utilities/title-case.js';
+export { truncateString } from './src/utilities/truncate-string.js';
 export { ValidationError } from './src/utilities/validation-error-class.js';
 
 // components
-export { default as modalAlert } from './src/components/modal-alert/modal-alert.js';
+export { modalAlert } from './src/components/modal-alert/modal-alert.js';
 export { dismissAlerts } from './src/components/dismiss-alerts.js';
 export { formResetSubmit } from './src/components/form-reset-submit.js';
 export { innerNav } from './src/components/inner-nav/inner-nav.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",
@@ -28,7 +28,9 @@
     "npm-publish": "npm publish",
     "upd@m": "npx upd@m",
     "build-tokens": "node ./design-tokens/utilities/build-tokens.mjs --config ./design-tokens/tokens-config.mjs",
-    "check unresolved props": "node ./design-tokens/utilities/check-unresolved-custom-props.mjs --config ./design-tokens/tokens-config.mjs"
+    "check unresolved props": "node ./design-tokens/utilities/check-unresolved-custom-props.mjs --config ./design-tokens/tokens-config.mjs",
+    "checkJS": "npx tsc --noEmit -p jsconfig.json",
+    "checkJS ./src": "npx tsc --noEmit --allowJs --checkJs --target ES2023 --module ESNext --allowSyntheticDefaultImports --moduleResolution bundler declarations.d.ts src/**/*.js"
   },
   "license": "MIT",
   "author": "Massimo Cassandro",

package/src/components/autocomplete/autocomplete-engine.js

@@ -5,21 +5,20 @@ import autoComplete from '@tarekraafat/autocomplete.js';
 
 export const ac_default_params = {
   placeholder: 'Inserisci tre o più caratteri',
-  ac_url: null, // url di ricerca, deve avere slash iniziali e finali
+  ac_url: null, // search URL; must have leading and trailing slashes
 
-  // se true, non viene concatenata la stringa di ricerca all'url (utile se si usa un json)
+  // when true, the search query string is not appended to the URL (useful with a static JSON)
   test_mode: false,
 
   /*
-      funzione che riceve il risultato del fetch ajax e restituisce un array
-      di oggetti nella forma
+      Function that receives the fetch result and returns an array of objects in the form:
       {
-        id             <== id dell'elemento
-        val            <== valore da visualizzare come risultato della selezione
-        list_display   <== stringa visualizzata nell'elenco
+        id             <== element id
+        val            <== value shown as the selection result
+        list_display   <== string shown in the results list
       }
 
-      esempio:
+      example:
       data => data.map(item => {
         return {
           id: item.id,
@@ -27,86 +26,88 @@ export const ac_default_params = {
           list_display: `#${item.id} ${item.agenzia} (${item.network})`+
             (item.ragioneSociale? `<br><small>${item.ragioneSociale}</small>` : '—')
 
-          // opzionale:
-          __xxx__: item (o altri dati custom)
+          // optional:
+          __xxx__: item (or other custom data)
         };
       });
     */
+  // @ts-ignore — parameter type inferred from library callback
   fetch_result_function: data => data,
 
-  // elemento o funzione che restituisce l'elemento
+  // field element or function returning the element
   autocomplete_field: null,
 
-  // selettore dell'elemento contenitore di autocomplete_field e degli altri elementi
+  // selector of the container element that wraps autocomplete_field and related elements
   autocomplete_parent_selector: '.form-group',
 
-  // oggetto opzione di parametri da accodare all'url di ricerca in modalità get
-  // i valori delle chiavi possono essere singole stringhe o numeri oppure array
-  // es. {param1: 'val1', param2: ['val2'. 'val3']}
+  // extra query parameters to append to the search URL (GET mode)
+  // values can be a single string/number or an array
+  // e.g. {param1: 'val1', param2: ['val2', 'val3']}
   extra_query_params: {},
 
-  // name e id dell'elemento hidden su cui registrare l'id selezionato
-  // il `name` non viene utilizzato se l'elemento è già presente
-  // se nessuno tra hidden_id, hidden_field e select_id è presente, l'id del valore selezionato non viene gestito
+  // name and id of the hidden input that stores the selected id
+  // `name` is ignored if the element already exists
+  // if none of hidden_id, hidden_field, or select_id is set, the selected id is not managed
   hidden_name: null,
   hidden_id: null,
 
-  // elemento hidden; se impostato e se presenti, `hidden_name` e `hidden_id` non vengono presi in considerazione
+  // hidden field element; when set, `hidden_name` and `hidden_id` are ignored
   hidden_field: null,
 
-  // se presente utilizza l'elemento select (già esistente) indicato
-  // se impostato, `hidden_name` e `hidden_id` vengono ignorati
-  // l'elemento select è considerato di tipo `multiple` se `select_multiple == true`
-  // nel caso di select multiple non è possibile inserire due voci con lo stesso id
+  // uses an existing <select> element with the given id
+  // when set, `hidden_name` and `hidden_id` are ignored
+  // treated as multiple if `select_multiple === true`
+  // in multiple mode, duplicate ids are not allowed
   select_id: null,
   select_multiple: true,
 
-  // id dell'elemento in cui generare i badge delle opzioni selezionate
-  // Solo se `select_id` è impostato, per visualizzazione ed editing delle voci scelte.
-  // Se non presente, viene ignorato ma è necessario predisporre autonomanente
-  // la procedura di editing
-  // NB: solo per select multiple
+  // id of the element used to render selected-option badges
+  // only applies when `select_id` is set (multiple mode)
+  // if absent, badge rendering must be handled externally
   badges_container_id: null,
 
-  // callback invocato quando un badge viene rimosso
-  // viene invocato con argomenti l'id e la voce (il testo del badge) dell'elemento rimosso
+  // callback invoked when a badge is removed;
+  // receives the id and label text of the removed item
   badges_remove_callback: null,
 
-  // funzione personalizzata per la costruzione dei badge
-  // viene invocata con argomenti `event.detail.selection.value`, e l'oggetto `params`.
-  // Il primo corrisponde all'oggetto ritornato da `fetch_result_function`
-  // se `null`, viene utilizzato il markup di default
-  // NB: al momento, nel caso di elementi preregistrati, il primo argomento di badges_builder
-  // contiene solo gli elementi `id`, `val`
-  // NB: è necessario che il badge abbia classe `ac-badge` e attributo `data-id`.
-  // La funzione deve restituire il markup completo del badge
+  // custom function for building badge markup
+  // receives `event.detail.selection.value` and the `params` object
+  // if null, the default markup is used
+  // NB: for pre-registered items the first argument only contains `id` and `val`
+  // NB: the badge must have class `ac-badge` and attribute `data-id`; must return complete badge HTML
   badges_builder: null,
 
-  // classe assegnata allo span che contiene il testo del badge
+  // class assigned to the span containing the badge label
   badge_label_class: 'ac-badge-label',
 
-  // classe assegnata al pulsante di rimozione del badge
+  // class assigned to the badge remove button
   badge_btn_class: 'ac-badge-btn',
 
 
-  // callback autocomplete
-  // se presente viene invocato con 5 argomenti: id, val, autocomplete field element, list_display (outerHTML) e row
-  // NB: row viene istanziato solo dopo la selezione di un'opzione
+  // autocomplete callback
+  // when present, called with 5 arguments: id, val, autocomplete field element, list_display (outerHTML), and row
+  // NB: row is only available after an option has been selected
   callback: null,
 
-  // classe aggiuntiva opzionale per la lista dei risultati
+  // optional extra class for the results list
   resultList_extra_class: null,
 
-  // classe aggiuntiva opzionale per il wrapper esterno
+  // optional extra class for the outer wrapper
   wrapper_extra_class: null
 };
 
+/**
+ * Initialises an autocomplete field using @tarekraafat/autocomplete.js.
+ * @param {Record<string, any>} [params={}]
+ * @returns {void}
+ */
 export default function (params = {}) {
 
   try {
 
     params = {...ac_default_params, ...params};
 
+    // @ts-ignore — circular reference: bparams defaults to params
     params.badges_builder ??= (result_obj, bparams = params) => `<span class="ac-badge badge rounded-pill text-bg-secondary" data-id="${result_obj.id}">` +
       `<span class="${bparams.badge_label_class}">${result_obj.val}</span>` +
         `<button type="button" class="${bparams.badge_btn_class}">&times;</button>` +
@@ -119,7 +120,7 @@ export default function (params = {}) {
         params.autocomplete_field = params.autocomplete_field();
       }
 
-      // impostazione attributi autocomplete
+      // set autocomplete field attributes
       params.autocomplete_field.type = 'search';
       ['spellcheck=false', 'autocorrect=off', 'autocomplete=off', 'autocapitalize=off'].forEach(item => {
         const [attr, val] = item.split('=');
@@ -137,6 +138,7 @@ export default function (params = {}) {
       let extra_query_params = [];
       for(const i in params.extra_query_params) {
         if(Array.isArray(params.extra_query_params[i])) {
+          // @ts-ignore — extra_query_params values are untyped (string, number, or array)
           params.extra_query_params[i].forEach(item => {
             extra_query_params.push(`${i}[]=${item}`);
           });
@@ -158,8 +160,7 @@ export default function (params = {}) {
         }
 
       } else {
-        // campo hidden
-        // se non presente, viene generato
+        // hidden field — created if not already present
         if(params.hidden_field) {
           hidden_field = params.hidden_field;
 
@@ -180,6 +181,7 @@ export default function (params = {}) {
         diacritics: true,
         threshold: 3,
         data: {
+          // @ts-ignore — library callback; query type defined by autoComplete.js
           src: async (query) => {
             const ac_url = params.ac_url +
               (params.test_mode? '' : encodeURIComponent(query)) + extra_query_params_string;
@@ -205,6 +207,7 @@ export default function (params = {}) {
           class: params.resultList_extra_class,
 
           destination: '#' + params.autocomplete_field.id,
+          // @ts-ignore — library callback; types defined by autoComplete.js
           element: (list, data) => {
             if (!data.results.length) {
               // Create "No Results" message element
@@ -225,6 +228,7 @@ export default function (params = {}) {
         events: {
 
           input: {
+            // @ts-ignore — library event; type defined by autoComplete.js
             selection: (event) => {
               // console.log(event.detail.selection.value);
 
@@ -237,7 +241,7 @@ export default function (params = {}) {
                 const option_element = new Option(selected_text, selected_id, true, true);
 
                 if(params.select_multiple) {
-                  // impedisce i doppioni
+                  // prevent duplicate entries
                   const registered_option = select_field.querySelector(`option[value="${selected_id}"]`),
                     new_badge = params.badges_builder(event.detail.selection.value, params);
 
@@ -250,18 +254,18 @@ export default function (params = {}) {
                       badges_container.insertAdjacentHTML('beforeend', new_badge);
                     }
 
-                  // replace del badge per avere sempre la versione più recente
+                  // replace the existing badge to always show the latest version
                   } else {
                     registered_option.replaceWith(option_element);
                     if(badges_container) {
                       const prev_badge = badges_container.querySelector(`.ac-badge[data-id="${selected_id}"]`);
-                      prev_badge.replaceWith(
+                      prev_badge?.replaceWith(
                         new DOMParser().parseFromString(new_badge, 'text/html').body.childNodes[0]
                       );
                     }
                   }
 
-                } else { // select singolo
+                } else { // single select
                   select_field.innerHTML = '';
                   select_field.appendChild(option_element);
                 }
@@ -281,9 +285,9 @@ export default function (params = {}) {
       }); // end autoComplete
 
       // TODO[epic=autocomplete]
-      // migliorare, rendere più efficiente la chiamata del callback
+      // improve and make the callback invocation more efficient
 
-      // reset hidden
+      // reset hidden field when the autocomplete value is cleared or mismatched
       const check_ac = () => {
         if(params.autocomplete_field.value === '' ||
           (params.autocomplete_field.dataset.sel !== undefined &&
@@ -314,16 +318,18 @@ export default function (params = {}) {
         check_ac();
       }, false);
 
-      // listener su badges
+      // badge click listener
       badges_container?.addEventListener('click', e => {
-        const btn = e.target.closest(`.${params.badge_btn_class}`);
+        const target = /** @type {HTMLElement} */ (e.target);
+        const btn = target.closest(`.${params.badge_btn_class}`);
 
         if(btn) {
-          const badge = btn.closest('.ac-badge'),
-            item_id = badge.dataset.id,
-            item_text = badge.querySelector(':scope > span').innerText;
+          const badge = /** @type {HTMLElement | null} */ (btn.closest('.ac-badge'));
+          if (!badge) return;
+          const item_id = badge.dataset.id,
+            item_text = /** @type {HTMLElement | null} */ (badge.querySelector(':scope > span'))?.innerText ?? '';
           badge.remove();
-          select_field.querySelector(`option[value="${item_id}"]`).remove();
+          select_field?.querySelector(`option[value="${item_id}"]`)?.remove();
 
           if(params.badges_remove_callback && typeof params.badges_remove_callback === 'function') {
 
@@ -332,17 +338,17 @@ export default function (params = {}) {
         }
       }, false);
 
-      // aggiunta voci o badges di eventuali valori preregistrati
+      // render badges for any pre-registered select options
       if(select_field) {
 
         if(params.select_multiple && badges_container) {
-          // eventuali attributi data dell'option vengono aggiunti
-          // alla funzione `badges_builder`, con chiave `dataset`
+          // any data attributes on the option are forwarded to `badges_builder` under the `dataset` key
 
           select_field.querySelectorAll('option[selected]').forEach(option => {
+            const opt = /** @type {HTMLOptionElement} */ (option);
             badges_container.insertAdjacentHTML('beforeend',
 
-              params.badges_builder({id: option.value, val: option.innerHTML, dataset: {...option.dataset}}, params)
+              params.badges_builder({id: opt.value, val: opt.innerHTML, dataset: {...opt.dataset}}, params)
             );
           });
         } else {

package/src/components/autocomplete/check-autocomplete.js

@@ -1,7 +1,15 @@
-// TODO trigger ac selection?
+// TODO trigger ac selection
+
+/**
+ * Resets both the autocomplete and hidden fields when the current value does not match
+ * the last confirmed selection.
+ * @param {HTMLInputElement | null | undefined} autocomplete_field
+ * @param {HTMLInputElement | null | undefined} hidden_field
+ * @returns {void}
+ */
 export function checkAutocomplete(autocomplete_field, hidden_field) {
   if(autocomplete_field && hidden_field) {
-    if(autocomplete_field.value === '' || autocomplete_field.value.toLowerCase() !== autocomplete_field.dataset.sel.toLowerCase()) {
+    if(autocomplete_field.value === '' || autocomplete_field.value.toLowerCase() !== (autocomplete_field.dataset.sel ?? '').toLowerCase()) {
       autocomplete_field.value = '';
       hidden_field.value = '';
     }

package/src/components/dismiss-alerts.js

@@ -1,7 +1,14 @@
+/**
+ * Adds click listeners to all `[data-dismiss]` elements to remove their closest ancestor
+ * that matches the class specified in the `data-dismiss` attribute.
+ * Typically used to remove alert boxes.
+ * @returns {void}
+ */
 export function dismissAlerts(){
   document.querySelectorAll('[data-dismiss]').forEach(item => {
-    item.addEventListener('click', () => {
-      item.closest('.' + item.dataset.dismiss).remove();
+    const el = /** @type {HTMLElement} */ (item);
+    el.addEventListener('click', () => {
+      el.closest('.' + el.dataset.dismiss)?.remove();
     }, false);
   });
 }

package/src/components/form-reset-submit.js

@@ -1,6 +1,13 @@
-// import './form.css'; //incorporato nel css principale
+// import './form.css'; // included in the main CSS entry point
 import { enableSubmitBtns } from '../../index.js';
 
+/**
+ * Wires up submit validation and button-disabling behaviour on all forms.
+ * - Adds `was-validated` class on submit (unless `data-no-was-validated` is present).
+ * - Clears `.is-invalid` / `.is-valid` classes before each submission attempt.
+ * - Disables submit buttons on valid submission (unless `data-no-disabling` is present).
+ * @returns {void}
+ */
 export function formResetSubmit(){
 
   document.querySelectorAll('form').forEach( form => {
@@ -26,13 +33,14 @@ export function formResetSubmit(){
         enableSubmitBtns();
 
       } else {
-        if(!form.hasAttribute('data-no-disabling') && !form.hasAttribute('data-disable-submit')) { /* 'data-disable-submit' per compatibilitò con verioni precedenti */
+        // 'data-disable-submit' kept for backwards compatibility
+        if(!form.hasAttribute('data-no-disabling') && !form.hasAttribute('data-disable-submit')) {
           form.querySelectorAll('[type="submit"]').forEach(btn => {
-            btn.disabled = true;
+            const button = /** @type {HTMLButtonElement} */ (btn);
+            button.disabled = true;
           });
         }
       }
     }, false);
   });
 }
-

package/src/components/inner-nav/inner-nav.js

@@ -1,4 +1,4 @@
-// navigazione scheda / elenco
+// tab / list navigation — copies the primary nav markup into all `.inner-nav` containers
 /*
 <p class="inner-nav-main">...</p>
 ...
@@ -7,6 +7,10 @@
 
 import './inner-nav.css';
 
+/**
+ * Copies the inner HTML of `.inner-nav-main` into every `.inner-nav` element on the page.
+ * @returns {void}
+ */
 export function innerNav(){
 
   const nav_primary = document.querySelector('.inner-nav-main');

package/src/components/modal-alert/customization-templates/custom-modal-alert.js

@@ -80,6 +80,10 @@ const marks = {
   confirm: confirmIcon
 };
 
+/**
+ * @param {Record<string, *>} params
+ * @returns {void}
+ */
 export function mAlert(params) {
   modalAlert(params, custom_defaults, marks);
 }

package/src/components/modal-alert/defaults.js

@@ -1,7 +1,10 @@
+/**
+ * Default configuration for all modal-alert dialog types.
+ * Type-specific blocks can override any `globals` setting.
+ */
 export const defaults = {
 
-  // settings to be applied to all dialog types
-  // can be reassigned on single types
+  // settings applied to all dialog types; can be overridden per type
   globals: {
     extra_class: null,
     onOpen: null,
@@ -44,7 +47,7 @@ export const defaults = {
   },
   confirm: {
     title: 'Confermi?',
-    use_warning_icon: false, // se true usa l'icona warning
+    use_warning_icon: false, // when true, uses the warning icon instead of the confirm icon
     ok_btn_text: 'OK',
     cancel_btn_text: 'Annulla',
     cancel_focus: true, // false to give focus to the ok button

package/src/components/modal-alert/modal-alert.js

@@ -4,28 +4,62 @@ import {defaults} from './defaults.js';
 // https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement
 
 // TODO rewrite as async
-// TODO rivedere completamente, riscrivere con domBuilder
-
-export default function (params, custom_defaults = {}, marks = default_marks) {
+// TODO refactor entirely, rewrite using domBuilder
+
+/**
+ * @typedef {Object} ModalAlertParams
+ * @property {string} type - Dialog type: `success`, `error`, `warning`, `info`, or `confirm`.
+ * @property {string | null} [extra_class]
+ * @property {(() => void) | null} [onOpen]
+ * @property {(() => void) | null} [onClose]
+ * @property {string | null} [cssFile]
+ * @property {boolean} [animation]
+ * @property {boolean} [showMarks]
+ * @property {((arg?: *) => void) | null} [callback]
+ * @property {number | null} [timer]
+ * @property {string | null} [mes]
+ * @property {string | null} [heading_class]
+ * @property {string | null} [text_class]
+ * @property {string | null} [extra_btn]
+ * @property {string | null} [extra_btn_selector]
+ * @property {boolean} [extra_btn_focus]
+ * @property {string | null} [title]
+ * @property {string} [ok_btn_text]
+ * @property {string} [ok_btn_class]
+ * @property {string} [cancel_btn_text]
+ * @property {string} [cancel_btn_class]
+ * @property {boolean} [cancel_focus]
+ * @property {boolean} [use_warning_icon]
+ */
+
+/**
+ * Renders and opens a modal alert dialog.
+ * @param {ModalAlertParams} params - Dialog parameters (merged with defaults by type).
+ * @param {Record<string, any>} [custom_defaults={}] - Per-project overrides for the default settings.
+ * @param {Record<string, string>} [marks=default_marks] - SVG icon map keyed by dialog type.
+ * @returns {void}
+ */
+
+//TODO refactoring
+
+export function modalAlert(params, custom_defaults = {}, marks = default_marks) {
 
   try {
 
     // garbage collection
-    let dialog = document.querySelector('.modal-alert');
-    if(dialog) {
-      dialog.remove();
-    }
+    document.querySelector('.modal-alert')?.remove();
 
+    const typedDefaults = /** @type {Record<string, any>} */ (defaults);
 
-    params = {
-      ...(defaults.globals?? {}),
-      ...(custom_defaults.globals?? {}),
-      ...(defaults[params.type]?? {}),
-      ...(custom_defaults[params.type]?? {}),
+    params = /** @type {ModalAlertParams} */ ({
+      ...(typedDefaults.globals ?? {}),
+      ...(custom_defaults.globals ?? {}),
+      ...(typedDefaults[params.type] ?? {}),
+      ...(custom_defaults[params.type] ?? {}),
       ...params
-    };
+    });
 
-    // per compatibilità
+    // backwards compatibility: 'danger' is an alias for 'error'
     if(params.type === 'danger') {
       params.type = 'error';
     }
@@ -53,7 +87,7 @@ export default function (params, custom_defaults = {}, marks = default_marks) {
       );
     }
 
-    // icona warning opzionale per confirm
+    // confirm type can optionally use the warning icon instead of the confirm icon
     let icon = marks[params.type];
     if(params.type === 'confirm' && params.use_warning_icon) {
       icon = marks.warning;
@@ -88,14 +122,16 @@ export default function (params, custom_defaults = {}, marks = default_marks) {
       </dialog>`
     );
 
-    dialog = document.querySelector('.modal-alert');
+    const dialog = /** @type {HTMLDialogElement} */ (document.querySelector('.modal-alert'));
 
     dialog.showModal();
 
-    // btn focus
-    const ok_btn = dialog.querySelector('.malert-ok'),
-      cancel_btn = dialog.querySelector('.malert-cancel'),
-      extra_btn = (params.extra_btn && params.extra_btn_selector)? dialog.querySelector(params.extra_btn_selector) : null;
+    // button focus
+    const ok_btn = /** @type {HTMLElement | null} */ (dialog.querySelector('.malert-ok')),
+      cancel_btn = /** @type {HTMLElement | null} */ (dialog.querySelector('.malert-cancel')),
+      extra_btn = /** @type {HTMLElement | null} */ (
+        (params.extra_btn && params.extra_btn_selector)? dialog.querySelector(params.extra_btn_selector) : null
+      );
 
     if(extra_btn && params.extra_btn_focus) {
       extra_btn.focus();
@@ -111,9 +147,14 @@ export default function (params, custom_defaults = {}, marks = default_marks) {
       params.onOpen();
     }
 
+    /** @type {number | undefined} */
     let timeoutID;
 
-    const dialogDismiss = (btn) => {
+    /**
+     * @param {HTMLElement | null} [btn]
+     * @returns {void}
+     */
+    const dialogDismiss = (btn = null) => {
       dialog.remove();
 
       if(params.onClose && typeof params.onClose === 'function') {