@massimo-cassandro/minimo 1.6.1 → 1.7.1

package/index.js

@@ -1,17 +1,24 @@
 
 // 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 { disableBtnsOnSubmit } from './src/utilities/disable-btns-on-submit.js';
 export { domBuilder } from './src/utilities/dom-builder/dom-builder.js';
 export { enableSubmitBtns } from './src/utilities/enable-submit-btns.js';
-export { escapeHTML, unescapeHTML } from './src/utilities/escapeHTML.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 { randomId } from './src/utilities/random-id.js';
+export { relativeDate } from './src/utilities/relative-date.js';
 export { sentenceCase } from './src/utilities/sentence-case.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.1",
+  "version": "1.7.1",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",

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

@@ -39,7 +39,10 @@ import {defaults} from './defaults.js';
  * @param {Record<string, string>} [marks=default_marks] - SVG icon map keyed by dialog type.
  * @returns {void}
  */
-export default function (params, custom_defaults = {}, marks = default_marks) {
+
+//TODO refactoring
+
+export function modalAlert(params, custom_defaults = {}, marks = default_marks) {
 
   try {
 

package/src/utilities/better-text.js

@@ -0,0 +1,80 @@
+// @ts-check
+
+/**
+ * Improves a text string by fixing punctuation spacing, multiple spaces,
+ * typographic quotes, non-breaking spaces after Italian particles/articles,
+ * and optionally enforcing the exact casing of custom words.
+ *
+ * @param {string} str - input string to process
+ * @param {string[]} custom_words - list of words whose exact casing must be preserved (e.g. `['iPhone', 'macOS']`)
+ * @returns {string} processed string, or empty string if input is falsy
+ */
+export function betterText(str, custom_words = []) {
+
+  const particelle = [
+    'e', 'ed',
+    'di', 'a', 'da', 'in', 'per', 'con', 'su', 'per', 'tra', 'fra',
+    'il', 'lo', 'la', 'i', 'gli', 'le',
+    'un', 'uno', 'una',
+    'del', 'dello', 'della', 'dei', 'degli', 'delle',
+    'al', 'allo', 'alla', 'ai', 'agli', 'alle',
+    'dal', 'dallo', 'dalla', 'dai', 'dagli', 'dalle',
+    'nel', 'nello', 'nella', 'nei', 'negli', 'nelle',
+    'col', 'collo', 'colla', 'con', 'coi', 'cogli', 'colle',
+    'sul', 'sullo', 'sulla', 'sui', 'sugli', 'sulle',
+
+    // topographic terms
+    'C.so', 'Corso', 'Via', 'P.za', 'Piazza', 'L.go', 'Largo', 'V.le', 'Viale',
+    'De', 'San', 'c/o', 'Loc.',
+
+    // English
+    'the', 'a', 'an', 'at', 'out', 'of',
+
+    // words used in geonames
+    'isola', 'isole'
+  ];
+
+  if(str) {
+    str = str.trim();
+
+    // punctuation: remove space before, ensure single space after
+    // NOTE: must run before any HTML entity replacements to avoid conflicts with `;`
+    // (?!$): negative lookahead to skip punctuation at end of string
+    str = str.replace(/ +(,|;|\.|:|!|\?)/g, '$1');
+    str = str.replace(/(,|;|\.|:|!|\?)(?!$) +/g, '$1 ');
+
+    // collapse multiple spaces and tabs (including non-breaking spaces)
+    str = str.replace(/[ \t\u00A0]+/g, ' ');
+
+    // typographic quotes
+    str = str.replace(/(^| )"/g, '$1“')   // opening double quotes
+      .replace(/"/g, '”')                  // remaining double quotes → closing
+      .replace(/(^| )'/g, '$1‘')           // opening single quotes
+      .replace(/'/g, '’')                  // remaining single quotes and apostrophes
+    ;
+
+    // remove space after apostrophe preceded by elided articles (l', un', d', all', ...)
+    str = str.replace(/((^| )(l|un|d|all|dell|nell|sull)('|')) /gi, '$1' );
+
+    // replace regular spaces with non-breaking spaces after Italian particles/articles
+    var re = new RegExp('\\b(' + particelle.join('|') + ')\\b +', 'gmi');
+    str = str.replace(re, function (match) {
+      return match.replace(/ +/g, '\u00A0');
+    });
+
+    // enforce exact casing of each particle
+    particelle.forEach(term => {
+      const re = new RegExp('\\b(' + term + ')\\b', 'gmi');
+      str = str.replace(re, term);
+    });
+
+    if(custom_words.length) {
+      custom_words.forEach(item => {
+        str = str.replace(new RegExp(`\\b${item}\\b`, 'gi'), item);
+      });
+    }
+  } else {
+    str = '';
+  }
+  return str;
+}

package/src/utilities/cookies.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * Returns the value of a cookie by name.
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+export function getCookie(name) {
+  const value = `; ${document.cookie}`;
+  const parts = value.split(`; ${name}=`);
+  if (parts.length === 2) return parts.pop()?.split(';').shift();
+}
+
+
+/**
+ * Sets a cookie.
+ * @param {object} params
+ * @param {string} params.name
+ * @param {string} params.value
+ * @param {string|null} [params.path=null]
+ * @param {number|null} [params.expire=null] - Max-Age in seconds
+ */
+export function setCookie({name, value, path = null, expire = null}) {
+  document.cookie = `${name}=${value}` +
+    (path ? `; path=${path}` : '') +
+    '; SameSite=Lax' +
+    (expire ? `; Max-Age=${expire}` : '');
+}

package/src/utilities/disable-btns-on-submit.js

@@ -0,0 +1,19 @@
+/**
+ * Disables all `[type=submit]` and `[type=button]` buttons on form submit.
+ *
+ * Applies to all `<form>` elements in the document except those with
+ * `data-disable-submit="false"`.
+ *
+ * @returns {void}
+ */
+export function disableBtnsOnSubmit() {
+  document.querySelectorAll('form:not([data-disable-submit=false])').forEach( el => {
+    el.addEventListener('submit', () => {
+      /** @type {NodeListOf<HTMLButtonElement|HTMLInputElement>} */
+      const btns = el.querySelectorAll('[type=submit], [type=button]');
+      btns.forEach(btn => {
+        btn.disabled = true;
+      });
+    });
+  });
+}

package/src/utilities/linked-dates.js

@@ -0,0 +1,64 @@
+// @ts-check
+
+/**
+ * Links date/datetime-local input fields so that one field constrains
+ * the min/max of another.
+ *
+ * The `data-max` attribute on a date field must contain the `id` of the field
+ * whose value sets the `max` constraint of the current field (start date).
+ * The `data-min` attribute on a date field must contain the `id` of the field
+ * whose value sets the `min` constraint of the current field (end date).
+ *
+ * If the linked field is disabled, the constraint is removed on focus
+ * and restored when the linked field is re-enabled.
+ *
+ * @param {Document|Element} context - root element to search within (defaults to `document`)
+ * @returns {void}
+ */
+export function linkedDates(context = document) {
+
+  // start date fields: constrained by a max value from a linked field
+  context.querySelectorAll('input[type="date"][data-max], input[type="datetime-local"][data-max]').forEach(el => {
+    const maxId = /** @type {HTMLInputElement} */ (el).dataset.max;
+    let linked_field = maxId ? document.getElementById(maxId) : null;
+
+    if(linked_field) {
+      el.setAttribute('max', /** @type {HTMLInputElement} */ (linked_field).value);
+
+      linked_field.addEventListener('change', () => {
+        el.setAttribute('max', /** @type {HTMLInputElement} */ (linked_field).value);
+      });
+
+      // remove max if the linked field is disabled; restore it when re-focused enabled
+      el.addEventListener('focus', () => {
+        if(/** @type {HTMLInputElement} */ (linked_field).disabled) {
+          el.removeAttribute('max');
+        } else {
+          el.setAttribute('max', /** @type {HTMLInputElement} */ (linked_field).value);
+        }
+      }, false);
+    }
+  });
+
+  // end date fields: constrained by a min value from a linked field
+  context.querySelectorAll('input[type="date"][data-min], input[type="datetime-local"][data-min]').forEach(el => {
+    const minId = /** @type {HTMLInputElement} */ (el).dataset.min;
+    let linked_field = minId ? document.getElementById(minId) : null;
+
+    if(linked_field) {
+      linked_field.addEventListener('change', () => {
+        el.setAttribute('min', /** @type {HTMLInputElement} */ (linked_field).value);
+      });
+
+      // remove min if the linked field is disabled; restore it when re-focused enabled
+      el.addEventListener('focus', () => {
+        if(/** @type {HTMLInputElement} */ (linked_field).disabled) {
+          el.removeAttribute('min');
+        } else {
+          el.setAttribute('min', /** @type {HTMLInputElement} */ (linked_field).value);
+        }
+      }, false);
+    }
+  });
+
+}

package/src/utilities/random-id.js

@@ -0,0 +1,13 @@
+// @ts-check
+
+/**
+ * Generates a random ID string.
+ * @returns {string} Base64-encoded random string
+ */
+export function randomId() {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_';
+  const bytes = crypto.getRandomValues(new Uint8Array(12));
+  return chars[bytes[0] % 52] // first item is from first 52 chars (A-Za-z)
+    + Array.from(bytes.slice(1), b => chars[b % 63]).join('');
+}
+

package/src/utilities/relative-date.js

@@ -0,0 +1,153 @@
+// @ts-check
+
+// Displays a date in relative form to the current date if within the set limits.
+// Relative dates are automatically updated every minute.
+
+/**
+ * @typedef {object} RelativeDateOptions
+ * @property {boolean} [useRelativeTime=true] - Show times near the date as "in xx minutes" (before) or "now" (within `relativeTimeMinutesAfter`)
+ * @property {string} [nowString] - String to display when the date is right now
+ * @property {number} [relativeTimeMinutesBefore] - Minutes before the date within which to show "in xx minutes"
+ * @property {number} [relativeTimeMinutesAfter] - Minutes after the date within which to show the now string
+ * @property {boolean} [relativeTimeShowTime] - Show the actual time alongside relative date labels
+ * @property {string} [relativeTimeShowTimeMarkup] - HTML markup for the time portion; `@@time@@` is replaced with the localized time string
+ * @property {boolean} [firstLetterUpperCase] - Capitalize the first letter of the returned string
+ * @property {Intl.DateTimeFormatOptions} [dateFormat] - Format for non-relative dates (beyond day after tomorrow)
+ * @property {Intl.DateTimeFormatOptions} [timeFormat] - Format for time displayed in relative date labels
+ * @property {string[]} [relativeStrings] - Labels for yesterday / today / tomorrow / day after tomorrow (in chronological order)
+ * @property {string} [locale] - Locale string for date/time formatting
+ */
+
+/**
+ * Returns an HTML `<time>` element string displaying the date in relative or absolute form.
+ * Relative dates are auto-refreshed every minute via a shared `setInterval`.
+ *
+ * @param {Date | string} date - Date to display (Date object or ISO string)
+ * @param {RelativeDateOptions} [options={}]
+ * @returns {string} HTML `<time>` element as a string
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat
+ */
+
+// TODO: Add option to include start time in relative dates
+// TODO: alternative solution in place of `@@time@@` placeholder
+// TODO reconsider and evaluate the use of Intl.RelativeTimeFormat Intl.RelativeTimeFormat
+
+export function relativeDate(date, options = {}) {
+
+  /** @type {Required<RelativeDateOptions>} */
+  const default_options = {
+    useRelativeTime: true,
+    nowString: 'adesso',
+    relativeTimeMinutesBefore: 30,
+    relativeTimeMinutesAfter: 30,
+    relativeTimeShowTime: true,
+    relativeTimeShowTimeMarkup: ' <span class="time-info">(alle @@time@@)</span>',
+    firstLetterUpperCase: true,
+    dateFormat: {
+      weekday: 'short',
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+      hour12: false,
+      hour: '2-digit',
+      minute: '2-digit'
+    },
+    timeFormat: {
+      hour12: false,
+      hour: '2-digit',
+      minute: '2-digit'
+    },
+    relativeStrings: [ // NB: in chronological order
+      'ieri alle', 'oggi alle', 'domani alle', 'dopodomani alle'
+    ],
+    locale: 'it-IT'
+  };
+
+  let isRelative = false;
+
+  /**
+   * @param {Date | string} dateInput
+   * @param {RelativeDateOptions} [overrideOptions={}]
+   * @returns {string}
+   */
+  const parseDate = (dateInput, overrideOptions = {}) => {
+
+    const opts = { ...default_options, ...overrideOptions };
+
+    const d = typeof dateInput === 'string' ? new Date(dateInput) : dateInput
+      , now = new Date()
+      , minutesDiff = (d.getTime() - now.getTime()) / 60000 // difference between the two dates in minutes
+      , daysDiff = (
+        new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0).getTime() -
+        new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0).getTime()
+      ) / 86400000
+      , rtf = new Intl.RelativeTimeFormat('it', { style: 'long' })
+    ;
+
+    /** @type {string} */
+    let result;
+
+    if (opts.useRelativeTime && Math.floor(Math.abs(minutesDiff)) === 0) {
+
+      result = opts.nowString;
+      isRelative = true;
+
+    } else if (opts.useRelativeTime && (
+      (Math.abs(minutesDiff) <= opts.relativeTimeMinutesAfter && minutesDiff < 0) ||
+      (minutesDiff > 0 && minutesDiff <= opts.relativeTimeMinutesBefore)
+    )) {
+
+      // formatToParts + reduce needed to strip decimal fractions from the value
+      const parts = rtf.formatToParts(minutesDiff, 'minute').reduce((acc, curr) => {
+        if (curr.type !== 'decimal') { // decimal separator
+          if (curr.type === 'fraction') { // fractional part
+            const intPart = acc.find(i => i.type === 'integer');
+            if (intPart) intPart.value += `.${curr.value}`;
+          } else {
+            acc.push(curr);
+          }
+        }
+        return acc;
+      }, /** @type {Intl.RelativeTimeFormatPart[]} */ ([]));
+
+      result = parts.map(i => i.type !== 'literal' ? Math.round(+i.value) : i.value).join('') +
+        (opts.relativeTimeShowTime ? opts.relativeTimeShowTimeMarkup?.replace('@@time@@', d.toLocaleString(opts.locale, opts.timeFormat)) : '');
+
+      isRelative = true;
+
+    // between -1 day and +2 days
+    } else if (daysDiff >= -1 && daysDiff <= 2) {
+
+      result = opts.relativeStrings[daysDiff + 1] + ' ' + d.toLocaleString(opts.locale, opts.timeFormat);
+      isRelative = daysDiff === 0;
+
+    } else {
+      result = d.toLocaleString(opts.locale, opts.dateFormat);
+    }
+
+    if (opts.firstLetterUpperCase && result) {
+      result = result.charAt(0).toUpperCase() + result.slice(1).toLowerCase();
+    }
+
+    return `<time datetime="${d.toISOString()}"${isRelative ? ` data-relative-date-opts="${encodeURIComponent(JSON.stringify(overrideOptions))}"` : ''}>${result}</time>`;
+
+  }; // end parseDate
+
+  const result = parseDate(date, options);
+
+  if (isRelative && !(/** @type {any} */ (window)).relativeDateUpd) {
+    /** @type {any} */ (window).relativeDateUpd = true;
+    setInterval(() => {
+      document.querySelectorAll('time[data-relative-date-opts]').forEach(item => {
+        const datetime = item.getAttribute('datetime');
+        const optsAttr = /** @type {HTMLElement} */ (item).dataset.relativeDateOpts;
+        if (datetime && optsAttr) {
+          item.outerHTML = parseDate(datetime, JSON.parse(decodeURIComponent(optsAttr)));
+        }
+      });
+    }, 60000);
+  }
+
+  return result;
+}

package/src/utilities/truncate-string.js

@@ -0,0 +1,22 @@
+
+// @ts-check
+
+/**
+ * Truncates a string to the desired length adding an option suffix
+ * from https://www.codegrepper.com/code-examples/javascript/javascript+truncate+string+full+word
+ *
+ * @param {string} str - string yo be truncated
+ * @param {number} maxLength - truncated string max length
+ * @param {string} suffix
+ * @returns {string|undefined} truncated string, or undefined if str is falsy
+ *
+ */
+
+export function truncateString(str, maxLength, suffix) {
+
+  suffix = suffix || '…';
+  if(str) {
+    return str.length < maxLength ? str :
+      `${str.substring(0, str.substring(0, maxLength - suffix.length).lastIndexOf(' '))}${suffix}`;
+  }
+}