@xoong/controls 0.0.35 → 0.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xoong/controls",
-  "version": "0.0.35",
+  "version": "0.0.39",
   "description": "xoong form and page controls: tabs, popover, tooltip, menu, combobox, chips, tag input, carousel. Light DOM, accessible, zero dependencies besides @xoong/core.",
   "type": "module",
   "main": "src/index.js",
@@ -12,6 +12,7 @@
     "./combobox": "./src/combobox.js",
     "./copy": "./src/copy.js",
     "./date": "./src/date.js",
+    "./image": "./src/image.js",
     "./password": "./src/password.js",
     "./slider": "./src/slider.js",
     "./stepper": "./src/stepper.js",
@@ -47,7 +48,7 @@
   },
   "homepage": "https://github.com/fpt-duongtx/xoong#readme",
   "dependencies": {
-    "@xoong/core": "0.0.35"
+    "@xoong/core": "0.0.39"
   },
   "publishConfig": {
     "access": "public"

package/src/controls.css

@@ -8,6 +8,18 @@
   xo-tabs > [role="tabpanel"] { padding-top: var(--xo-space-3, .75rem); }
 }
 
+@layer xoong-controls {
+  xo-image { display: block; position: relative; overflow: hidden; max-width: 100%; }
+  xo-image > img { display: block; width: 100%; height: 100%; object-fit: var(--xo-image-fit, cover); object-position: var(--xo-image-position, center); }
+  xo-image[data-state="loading"] { background: var(--xo-color-subtle, #eef0f3); }
+  xo-image[data-state="loading"] > img { opacity: 0; }
+  xo-image > img { transition: opacity .2s; }
+  @media (prefers-reduced-motion: reduce) { xo-image > img { transition: none; } }
+  xo-image[data-state="empty"] > img, xo-image[data-state="error"] > img { display: none; }
+  xo-image[data-state="empty"], xo-image[data-state="error"] { background: var(--xo-color-subtle, #eef0f3); min-height: 3rem; }
+  xo-image .xo-image-note { position: absolute; inset: 0; display: grid; place-items: center; padding: .5rem; text-align: center; font-size: .85rem; color: var(--xo-color-muted, #5b6470); }
+}
+
 @layer xoong-controls {
   xo-menu { display: inline-block; }
   xo-menu [role="menu"] { min-width: 10rem; padding: var(--xo-space-1, .25rem); background: var(--xo-color-surface, #fff); color: inherit; border: 1px solid var(--xo-color-border, #d8dee4); border-radius: var(--xo-radius, 6px); box-shadow: 0 6px 18px rgb(0 0 0 / .15); }

package/src/image.js

@@ -0,0 +1,84 @@
+// @ts-check
+/**
+ * <xo-image> is an image that behaves well on a page: it loads lazily, keeps its space (no layout jump), shows a placeholder while it
+ * loads and something useful when it fails.
+ *
+ *   <xo-image src="/img/cover.jpg" alt="The harbour at dusk" width="1200" height="800"></xo-image>
+ *   <xo-image src="{cover.url}" alt="{cover.alt}" ratio="16/9" fit="cover" srcset="/s.jpg 480w, /l.jpg 1200w" sizes="(min-width: 60rem) 50vw, 100vw"></xo-image>
+ *   <xo-image src="/hero.jpg" alt="" priority></xo-image>
+ *
+ * - `alt` is required: text for the image, or `alt=""` for a decorative one. `xoong check` warns when it is missing.
+ * - Lazy by default (`loading="lazy"`, `decoding="async"`). `priority` is for the one image above the fold: eager, high fetch priority.
+ * - The space is reserved from `width` and `height`, or from `ratio` (`16/9`, `1.5`). `fit` (cover by default, or contain) and `position` set how
+ *   the picture fills it (the custom properties --xo-image-fit and --xo-image-position, set through the CSS object model: no style attribute).
+ * - `srcset` and `sizes` go to the <img> as they are. A `src` that changes (in an <xo-view>, with `src="{path}"`) loads again.
+ * - `data-state` on the element: `empty` (no src), `loading` (skeleton), `loaded`, `error`. On an error the `fallback` src is tried once;
+ *   without one the alt text is shown in the box. `load` and `error` events are re-fired on the element (they do not bubble).
+ */
+import { XoElement, define } from '@xoong/core';
+
+class XoImage extends XoElement {
+  static props = { src: String, srcset: String, sizes: String, alt: String, width: Number, height: Number, ratio: String, fit: String, position: String, priority: Boolean, loading: String, fallback: String };
+
+  /** @type {HTMLImageElement | null} */ #img = null;
+  /** @type {HTMLElement | null} */ #note = null;
+  #fellBack = false;
+  #warned = false;
+
+  connected() {
+    const img = document.createElement('img');
+    img.decoding = 'async';
+    img.addEventListener('load', () => { this.#state('loaded'); this.dispatchEvent(new Event('load')); });
+    img.addEventListener('error', () => this.#failed());
+    this.#img = img;
+    this.replaceChildren(img);
+    this.#paint();
+  }
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (attr === 'src' || attr === 'srcset') this.#fellBack = false;
+    this.#paint();
+  }
+
+  #state(/** @type {string} */ s) {
+    this.dataset.state = s;
+    if (s !== 'error') { this.#note?.remove(); this.#note = null; }
+  }
+
+  #paint() {
+    const img = this.#img;
+    if (!img) return;
+    if (!this.hasAttribute('alt') && !this.#warned) { this.#warned = true; console.warn('xoong: <xo-image> needs an alt attribute (alt="" for a decorative image)', this.getAttribute('src')); }
+    img.alt = this.alt ?? '';
+    img.loading = this.priority ? 'eager' : this.loading === 'eager' ? 'eager' : 'lazy';
+    img.fetchPriority = this.priority ? 'high' : 'auto';
+    for (const k of /** @type {const} */ (['width', 'height'])) { if (this[k]) img.setAttribute(k, String(this[k])); else img.removeAttribute(k); }
+    if (this.sizes) img.sizes = this.sizes; else img.removeAttribute('sizes');
+    const ratio = this.ratio ? this.ratio.replace(/\s/g, '') : this.width && this.height ? `${this.width}/${this.height}` : '';
+    const set = (/** @type {string} */ k, /** @type {string | null | undefined} */ v) => (v ? this.style.setProperty(k, v) : this.style.removeProperty(k));
+    set('aspect-ratio', ratio);
+    set('--xo-image-fit', this.fit);
+    set('--xo-image-position', this.position);
+    const src = this.#fellBack ? this.fallback : this.src;
+    const srcset = this.#fellBack ? '' : this.srcset;
+    if (!src && !srcset) { img.removeAttribute('src'); img.removeAttribute('srcset'); this.#state('empty'); return; }
+    if (srcset) img.srcset = srcset; else img.removeAttribute('srcset');
+    if (src && img.getAttribute('src') !== src) { this.#state('loading'); img.src = src; }
+    else if (!src) this.#state('loading');
+    if (img.complete && img.naturalWidth > 0) this.#state('loaded'); // from the cache: there may be no load event
+    else if (!this.dataset.state || this.dataset.state === 'empty') this.#state('loading');
+  }
+
+  #failed() {
+    if (this.fallback && !this.#fellBack) { this.#fellBack = true; this.#paint(); return; }
+    this.#state('error');
+    if (!this.#note) {
+      this.#note = document.createElement('span');
+      this.#note.className = 'xo-image-note';
+      this.append(this.#note);
+    }
+    this.#note.textContent = this.alt ?? '';
+    this.dispatchEvent(new Event('error'));
+  }
+}
+define('xo-image', XoImage);

package/src/index.js

@@ -11,3 +11,4 @@ import './slider.js';
 import './stepper.js';
 import './password.js';
 import './copy.js';
+import './image.js';