@massimo-cassandro/minimo 1.14.4 → 1.14.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.14.4",
+  "version": "1.14.6",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",

package/src/utilities/build-picture-tag.js

@@ -5,10 +5,13 @@ import { classnames } from './classnames.js';
 /**
  * @typedef {Object} PictureSizeEntry
  * @property {number} [from] - Breakpoint (px) the size applies from (`width >=` media condition); omitted in the (single) mobile-first default entry.
- * @property {number | [number, number]} size - Rendered width (px, height computed with `ratio`) or explicit `[width, height]` pair (px).
+ * @property {number | [number, number]} size - Rendered width (px, height computed with `ratio`, if set) or explicit `[width, height]` pair (px).
  */
 
 // TODO aggiungere compatibilità con immagini Unsplash basate su imgix
+// TODO parametri viewer: le convenzioni attuali (`bb=WxH`, `bb=Wx` per il resize width-only,
+// `q`, `fd`, `f`) sono legate al viewer interno; prevedere un meccanismo di astrazione
+// per altri servizi con parametri diversi (es. imgix/Unsplash)
 
 /**
  * Creates a `picture` domBuilder item for an image rendered through the viewer.
@@ -20,7 +23,9 @@ import { classnames } from './classnames.js';
  * `(width >= …)` media condition (range syntax).
  *
  * @example
- * // fixed-width thumb (250px, 16:9 ratio, 1x and 2x candidates)
+ * // fixed-width thumb (250px, 1x and 2x candidates); with no `ratio` nor explicit
+ * // heights, the viewer gets a width-only resize (bb=250x) and the `img` has no
+ * // `height` attribute
  * buildPictureTag({ baseSrc: 'https://img-viewer.example.com/abc123', alt: '…' });
  * // sizes="250px", srcset="… 250w, … 500w"
  *
@@ -55,15 +60,25 @@ import { classnames } from './classnames.js';
  * // dev environment (no avif) and above-the-fold img (no loading="lazy")
  * buildPictureTag({ baseSrc, devMode: true, lazy: false });
  *
+ * @example
+ * // onLoad callback: reveal the image once it has finished loading
+ * buildPictureTag({
+ *   baseSrc,
+ *   imgExtraClass: 'img-loading',
+ *   onLoad: img => img.classList.remove('img-loading'),
+ * });
+ *
  * @param {Object} args
  * @param {string} args.baseSrc - Image base URL (viewer endpoint); its query params are preserved.
  * @param {(number | [number, number] | PictureSizeEntry)[]} [args.sizes=[250]] - Rendered image sizes, in any order. Each entry is a `{from, size}` object (see {@link PictureSizeEntry}); a bare number or `[width, height]` pair is a shorthand for the mobile-first default entry (the one without `from`), expected exactly once.
- * @param {number} [args.ratio=16/9] - Default aspect ratio (width / height, as in the CSS `aspect-ratio` property) used to compute the height of numeric sizes.
+ * @param {number|null} [args.ratio=null] - Default aspect ratio (width / height, as in the CSS `aspect-ratio` property) used to compute the height of numeric sizes. When null, no height is computed: the height-related output (`height` attribute, height in the `bb` param) is omitted and the viewer preserves the image's own ratio.
  * @param {number} [args.dpr=2] - Maximum pixel density (integer): `srcset` candidates are generated for every density from 1 to `dpr`.
- * @param {[string, string|number][]} [args.img_params=[['q','60'],['fd',1]]] - Query params (`[name, value]` pairs) added to every generated URL.
+ * @param {[string, string|number][]} [args.img_params=[['q','60']]] - Query params (`[name, value]` pairs) added to every generated URL.
  * @param {string[]} [args.formats=['avif','webp','pjpg']] - Image formats: the last one is used for the `img` fallback element, the others for the `source` elements.
  * @param {boolean} [args.devMode=false] - When true, `avif` is excluded from `formats` (not supported by the local dev environment).
  * @param {boolean} [args.lazy=true] - When true, the `img` element gets `loading="lazy"`.
+ * @param {'high'|'low'|null} [args.fetchpriority=null] - `fetchpriority` attribute for the `img` element: use `high` for the LCP/above-the-fold image (typically with `lazy: false`). When null the attribute is omitted (browser default `auto`).
+ * @param {((img: HTMLImageElement) => void) | null} [args.onLoad=null] - Called once the image has finished loading, receiving the `img` element (called immediately if the image is already complete).
  * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
  * @param {boolean} [args.legacyMediaSyntax=false] - When true, the `sizes` media conditions use `(min-width: …)` instead of the range syntax `(width >= …)`, for older browsers (pre Chrome/Edge 104, Firefox 102, Safari 16.4).
  * @param {string|null} [args.pictureExtraClass=null] - Extra class(es) for the `picture` element.
@@ -76,12 +91,14 @@ import { classnames } from './classnames.js';
 export function buildPictureTag({
   baseSrc,
   sizes = [250],
-  ratio = 16/9,
+  ratio = null,
   dpr = 2,
   img_params = [ ['q', '60'] ],
   formats = ['avif', 'webp', 'pjpg'],
   devMode = false,
   lazy = true,
+  fetchpriority = null,
+  onLoad = null,
   condition = true,
   legacyMediaSyntax = false,
   pictureExtraClass = null,
@@ -107,14 +124,14 @@ export function buildPictureTag({
   const dprList = Array.from({length: dpr}, (_, i) => i + 1);
 
   // entry di `sizes` normalizzate in oggetti {from, width, height}
-  // (per le size numeriche l'altezza è calcolata con `ratio`),
+  // (per le size numeriche l'altezza è calcolata con `ratio`, se presente, altrimenti è null),
   // ordinate per breakpoint, con il default (from = null) per primo
   const sizeEntries = sizes.map(entry => {
     if(typeof entry === 'object' && !Array.isArray(entry)) {
-      const [width, height] = Array.isArray(entry.size)? entry.size : [entry.size, Math.floor(entry.size / ratio)];
+      const [width, height] = Array.isArray(entry.size)? entry.size : [entry.size, ratio == null? null : Math.floor(entry.size / ratio)];
       return { from: entry.from ?? null, width, height };
     }
-    const [width, height] = Array.isArray(entry)? entry : [entry, Math.floor(entry / ratio)];
+    const [width, height] = Array.isArray(entry)? entry : [entry, ratio == null? null : Math.floor(entry / ratio)];
     return { from: null, width, height };
   }).sort((a, b) => (a.from ?? 0) - (b.from ?? 0));
 
@@ -133,7 +150,7 @@ export function buildPictureTag({
     // dimensioni dei candidati srcset (una per ogni densità da 1 a `dpr`),
     // senza duplicati (per larghezza), in ordine crescente
     ,srcsetSizes = sizeEntries
-      .flatMap(({width, height}) => dprList.map(d => /** @type {[number, number]} */ ([width * d, height * d])))
+      .flatMap(({width, height}) => dprList.map(d => /** @type {[number, number|null]} */ ([width * d, height == null? null : height * d])))
       .filter((pair, idx, arr) => arr.findIndex(p => p[0] === pair[0]) === idx)
       .sort((a, b) => a[0] - b[0])
 
@@ -184,7 +201,8 @@ export function buildPictureTag({
       searchParams.set('f', fmt);
 
       srcsetSizes.forEach(([w, h]) => {
-        searchParams.set('bb', `${w}x${h}`);
+        // TODO senza altezza `bb=<w>x` vale per questo viewer: prevedere altre convenzioni (es. imgix)
+        searchParams.set('bb', `${w}x${h ?? ''}`);
         base_url.search = searchParams.toString();
         srcsetArray.push(`${base_url.toString()} ${w}w`);
       });
@@ -202,8 +220,18 @@ export function buildPictureTag({
             width: imgWidth,
             height: imgHeight,
             loading: lazy? 'lazy' : null,
+            decoding: 'async',
+            fetchpriority: fetchpriority,
             ...imgExtraAttrs
           },
+          callback: onLoad == null? undefined : el => {
+            const img = /** @type {HTMLImageElement} */ (el);
+            if(img.complete) {
+              onLoad(img);
+            } else {
+              img.addEventListener('load', () => onLoad(img), {once: true});
+            }
+          },
           // TODO classe popover, se attivato
           // callback: options.addPopover
           //   ? el => el.addEventListener('click', () => zoomPopoverEl.togglePopover())