chameleon-backgrounds 2.1.3 → 3.0.1

package/src/chameleon-backgrounds.js

@@ -14,7 +14,7 @@
  *                        |___/
  *
  *  @module ChameleonBackgrounds
- *  @version 2.1.3
+ *  @version 3.0.1
  *  @author Lennart van Ballegoij (https://weblenn.com/)
  *  @license MIT
  *  @see https://github.com/WebLenn/ChameleonBackgrounds
@@ -24,10 +24,15 @@
  */
 
 /**
+ * @typedef {Object} ChameleonImageConfig
+ * @property {string} url - The fallback URL.
+ * @property {string} [srcset] - Optional srcset.
+ * @property {string} [sizes] - Optional sizes.
+ *
  * @typedef {Object} ChameleonOptions
  * @property {string|HTMLElement}       element             - CSS selector or DOM element to attach to.
  * @property {'single'|'slider'}       type                - Background mode.
- * @property {string|string[]}         src                 - Image URL(s). String for 'single', array for 'slider'.
+ * @property {string|string[]|ChameleonImageConfig|ChameleonImageConfig[]} src - Image URL(s) or config object(s).
  * @property {string}                  overlayColor        - Overlay color (hex, rgb, rgba, hsl).
  * @property {string}                  [overlayImage]      - Optional overlay pattern image URL.
  * @property {number}                  [minOverlay=0]      - Minimum overlay opacity after fade (0–1).
@@ -35,6 +40,8 @@
  * @property {number}                  [sliderDuration=8000]     - Time each slide is shown in milliseconds.
  * @property {boolean}                 [sliderLoop=false]        - Whether the slider restarts after the last slide.
  * @property {'high'|'low'|'auto'}     [fetchPriority='auto']    - fetchPriority for the first loaded image (e.g., 'high' for LCP images).
+ * @property {boolean}                 [lazyLoad=true]           - Whether to wait until element is in viewport using IntersectionObserver.
+ * @property {'solid'|'crossfade'}     [transitionMode='solid']  - Transition mode: 'solid' (fade to color) or 'crossfade' (fade between images).
  */
 
 class ChameleonBackgrounds {
@@ -50,6 +57,9 @@ class ChameleonBackgrounds {
     sliderDuration: 8000,
     sliderLoop: false,
     fetchPriority: 'auto',
+    lazyLoad: true,
+    transitionMode: 'solid',
+    respectReducedMotion: false,
   });
 
   // Legacy snake_case → camelCase alias map
@@ -61,8 +71,14 @@ class ChameleonBackgrounds {
     overlay_color: 'overlayColor',
     overlay_image: 'overlayImage',
     fetch_priority: 'fetchPriority',
+    lazy_load: 'lazyLoad',
+    transition_mode: 'transitionMode',
+    respect_reduced_motion: 'respectReducedMotion',
   });
 
+  /** @type {boolean} */
+  static #globalStylesInjected = false;
+
   /** @type {ChameleonOptions} */
   #options;
 
@@ -75,12 +91,24 @@ class ChameleonBackgrounds {
   /** @type {string} */
   #originalHTML;
 
-  /** @type {HTMLStyleElement|null} */
-  #styleElement = null;
-
   /** @type {number|null} */
   #sliderIntervalId = null;
 
+  /** @type {number} */
+  #currentSlideIndex = 0;
+
+  /** @type {boolean} */
+  #hasLoadedFirstBackground = false;
+
+  /** @type {number} */
+  #transitionId = 0;
+
+  /** @type {boolean} */
+  #isPaused = false;
+
+  /** @type {IntersectionObserver|null} */
+  #observer = null;
+
   /** @type {boolean} */
   #destroyed = false;
 
@@ -112,16 +140,18 @@ class ChameleonBackgrounds {
 
     // Stop any running slider
     if (this.#sliderIntervalId !== null) {
-      clearInterval(this.#sliderIntervalId);
+      clearTimeout(this.#sliderIntervalId);
       this.#sliderIntervalId = null;
     }
 
-    // Remove injected style element
-    if (this.#styleElement?.parentNode) {
-      this.#styleElement.parentNode.removeChild(this.#styleElement);
-      this.#styleElement = null;
+    if (this.#observer) {
+      this.#observer.disconnect();
+      this.#observer = null;
     }
 
+    // Clean up dynamic classes on host
+    this.#element.classList.remove(`cbg-host-${this.#uid}`, 'cbg-host');
+
     // Unwrap the original content instead of resetting innerHTML
     const wrapper = this.#element.querySelector(`#cbg-inner-${this.#uid}`);
     if (wrapper && wrapper.parentNode === this.#element) {
@@ -137,8 +167,16 @@ class ChameleonBackgrounds {
       loader.remove();
     }
 
-    // Remove inline background-image
+    // Remove temporary crossfade elements
+    const crossfadeElements = this.#element.querySelectorAll(`.cbg-crossfade-${this.#uid}`);
+    crossfadeElements.forEach(el => el.remove());
+
+    // Remove inline CSS Variables and background-image
     this.#element.style.backgroundImage = '';
+    this.#element.style.removeProperty('--cbg-duration');
+    this.#element.style.removeProperty('--cbg-overlay-color');
+    this.#element.style.removeProperty('--cbg-overlay-image');
+    this.#element.style.removeProperty('--cbg-min-overlay');
   }
 
   /**
@@ -154,71 +192,145 @@ class ChameleonBackgrounds {
   // ---------------------------------------------------------------------------
 
   #init() {
-    this.#injectStyles();
+    this.#injectGlobalStyles();
+    this.#updateCSSVariables();
     this.#buildDOM();
 
-    // If the element is NOT <body>, wait for window load to start loading images.
-    // For <body>, the loader is already visible, so we start immediately to avoid
-    // the re-execution issue the legacy lib had with body scripts.
-    if (this.#element.matches('body')) {
-      // Use a microtask so the DOM changes above settle first.
-      queueMicrotask(() => this.#retrieveBackground());
+    // Check for prefers-reduced-motion to auto-pause slider if enabled
+    if (this.#options.respectReducedMotion && window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+      this.#isPaused = true;
+    }
+
+    if (this.#options.lazyLoad && 'IntersectionObserver' in window) {
+      this.#observer = new IntersectionObserver((entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            this.#observer.disconnect();
+            this.#observer = null;
+            this.#retrieveBackground();
+          }
+        });
+      });
+      this.#observer.observe(this.#element);
     } else {
-      if (document.readyState === 'complete') {
-        this.#retrieveBackground();
+      if (this.#element.matches('body')) {
+        queueMicrotask(() => this.#retrieveBackground());
       } else {
-        window.addEventListener('load', () => this.#retrieveBackground(), { once: true });
+        if (document.readyState === 'complete') {
+          this.#retrieveBackground();
+        } else {
+          window.addEventListener('load', () => this.#retrieveBackground(), { once: true });
+        }
       }
     }
   }
 
+  // ---------------------------------------------------------------------------
+  //  Play / Pause API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Pause the slideshow.
+   */
+  pause() {
+    if (this.#destroyed || this.#options.type !== 'slider') return;
+    this.#isPaused = true;
+    if (this.#sliderIntervalId !== null) {
+      clearTimeout(this.#sliderIntervalId);
+      this.#sliderIntervalId = null;
+    }
+  }
+
+  /**
+   * Resume the slideshow.
+   */
+  play() {
+    if (this.#destroyed || this.#options.type !== 'slider') return;
+    this.#isPaused = false;
+    // Only restart if not currently running
+    if (this.#sliderIntervalId === null) {
+      this.#startSliderLoop();
+    }
+  }
+
   // ---------------------------------------------------------------------------
   //  DOM Construction
   // ---------------------------------------------------------------------------
 
   /**
-   * Inject a scoped <style> element into the <head>.
+   * Inject global styles once.
    */
-  #injectStyles() {
-    const uid = this.#uid;
-    const selector = this.#options.element === 'body' || this.#element.matches('body')
-      ? 'body'
-      : this.#options.element;
-    const duration = this.#options.transitionDuration / 1000; // ms → s
-    const position = this.#element.matches('body') ? 'fixed' : 'absolute';
-    const overlayBg = this.#options.overlayImage
-      ? `url(${this.#options.overlayImage})`
-      : 'none';
+  #injectGlobalStyles() {
+    if (ChameleonBackgrounds.#globalStylesInjected) return;
+    ChameleonBackgrounds.#globalStylesInjected = true;
 
     const css = `
-      ${typeof selector === 'string' ? selector : `.cbg-host-${uid}`} {
+      .cbg-host {
         position: relative;
       }
-
-      #cbg-inner-${uid} {
+      body.cbg-host {
+        /* body naturally acts as relative for background sizing if not explicitly positioned differently */
+      }
+      .cbg-inner {
         z-index: 2;
         position: relative;
       }
-
-      .cbg-loader-${uid} {
+      .cbg-loader {
         height: 100%;
         width: 100%;
-        position: ${position};
-        background-image: ${overlayBg};
-        background-color: ${this.#options.overlayColor};
+        position: absolute;
+        top: 0;
+        left: 0;
+        background-image: var(--cbg-overlay-image, none);
+        background-color: var(--cbg-overlay-color, transparent);
         opacity: 1;
         z-index: 1;
-        transition: opacity ${duration}s ease;
+        transition: opacity var(--cbg-duration, 2s) ease;
+        pointer-events: none;
+      }
+      body.cbg-host > .cbg-loader {
+        position: fixed;
+      }
+      .cbg-crossfade-el {
+        position: absolute;
         top: 0;
         left: 0;
+        height: 100%;
+        width: 100%;
+        background-size: cover;
+        background-position: center;
+        background-repeat: no-repeat;
+        z-index: 0;
+        opacity: 0;
+        transition: opacity var(--cbg-duration, 2s) ease;
+        pointer-events: none;
+      }
+      body.cbg-host > .cbg-crossfade-el {
+        position: fixed;
       }
     `;
 
     const style = document.createElement('style');
-    style.dataset.chameleonUid = uid;
+    style.id = 'chameleon-global-styles';
     style.textContent = css;
     document.head.appendChild(style);
-    this.#styleElement = style;
+  }
+
+  /**
+   * Apply CSS custom properties to the host element.
+   */
+  #updateCSSVariables() {
+    this.#element.classList.add(`cbg-host-${this.#uid}`, 'cbg-host');
+    this.#element.style.setProperty('--cbg-duration', `${this.#options.transitionDuration / 1000}s`);
+    this.#element.style.setProperty('--cbg-overlay-color', this.#options.overlayColor);
+
+    if (this.#options.overlayImage) {
+      this.#element.style.setProperty('--cbg-overlay-image', `url(${this.#options.overlayImage})`);
+    } else {
+      this.#element.style.setProperty('--cbg-overlay-image', 'none');
+    }
+
+    this.#element.style.setProperty('--cbg-min-overlay', String(this.#options.minOverlay));
   }
 
   /**
@@ -229,6 +341,7 @@ class ChameleonBackgrounds {
 
     const wrapper = document.createElement('div');
     wrapper.id = `cbg-inner-${uid}`;
+    wrapper.classList.add('cbg-inner');
 
     // Move all child nodes from the element into the wrapper
     while (this.#element.firstChild) {
@@ -236,7 +349,7 @@ class ChameleonBackgrounds {
     }
 
     const loader = document.createElement('div');
-    loader.classList.add(`cbg-loader-${uid}`);
+    loader.classList.add('cbg-loader', `cbg-loader-${uid}`);
 
     // Append wrapper and loader
     this.#element.appendChild(wrapper);
@@ -254,7 +367,8 @@ class ChameleonBackgrounds {
     if (this.#destroyed) return;
 
     if (this.#options.type === 'single') {
-      this.#loadBackground(typeof this.#options.src === 'string' ? this.#options.src : this.#options.src[0]);
+      const singleSrc = Array.isArray(this.#options.src) ? this.#options.src[0] : this.#options.src;
+      this.#loadBackground(singleSrc);
     } else if (this.#options.type === 'slider') {
       this.#startSlider();
     }
@@ -262,39 +376,90 @@ class ChameleonBackgrounds {
 
   /**
    * Preload an image and apply it as the element's background.
-   * @param {string}   src      - Image URL to load.
+   * Handles both string URLs and responsive image objects ({ url, srcset, sizes }).
+   * @param {string|ChameleonImageConfig} srcConfig - Image configuration or URL.
    * @param {boolean}  [isFirst=true] - Whether this is the first image (skips overlay reset).
+   * @param {boolean}  [isCrossfade=false] - If true, handles true crossfading without solid color drop.
    * @returns {Promise<void>}
    */
-  #loadBackground(src, isFirst = true) {
+  #loadBackground(srcConfig, isFirst = true, isCrossfade = false) {
     if (this.#destroyed) return Promise.resolve();
 
     return new Promise((resolve) => {
       const img = new Image();
+
+      let urlStr = srcConfig;
+      if (typeof srcConfig === 'object' && srcConfig.url) {
+        urlStr = srcConfig.url;
+        if (srcConfig.srcset) img.srcset = srcConfig.srcset;
+        if (srcConfig.sizes) img.sizes = srcConfig.sizes;
+      }
+
       if (isFirst && 'fetchPriority' in img && this.#options.fetchPriority !== 'auto') {
         img.fetchPriority = this.#options.fetchPriority;
       }
 
+      // Append to DOM to ensure viewport-based `sizes` calculate correctly in all browsers
+      img.style.position = 'absolute';
+      img.style.visibility = 'hidden';
+      img.style.width = '0';
+      img.style.height = '0';
+      this.#element.appendChild(img);
+
       img.onload = () => {
+        img.remove();
         if (this.#destroyed) return resolve();
 
-        this.#element.style.backgroundImage = `url(${src})`;
-        this.#element.style.backgroundSize = 'cover';
-
-        const loader = this.#element.querySelector(`.cbg-loader-${this.#uid}`);
-        if (loader) {
-          loader.style.opacity = String(this.#options.minOverlay);
+        // `img.currentSrc` retrieves the actual srcset chosen file, otherwise fallback to `urlStr`
+        const finalUrl = img.currentSrc || urlStr;
+
+        if (isCrossfade && !isFirst) {
+          // --- Crossfade Transition Mode ---
+          const crossfadeDiv = document.createElement('div');
+          crossfadeDiv.classList.add('cbg-crossfade-el', `cbg-crossfade-${this.#uid}`);
+          crossfadeDiv.style.backgroundImage = `url("${finalUrl}")`;
+
+          // Insert right behind the loader (or directly at start of host)
+          this.#element.insertBefore(crossfadeDiv, this.#element.firstChild);
+
+          // Trigger layout so the transition works
+          void crossfadeDiv.offsetWidth;
+
+          crossfadeDiv.style.opacity = '1';
+
+          setTimeout(() => {
+            if (this.#destroyed) return resolve();
+            this.#element.style.backgroundImage = `url("${finalUrl}")`;
+            this.#element.style.backgroundSize = 'cover';
+            this.#element.style.backgroundRepeat = 'no-repeat';
+            crossfadeDiv.remove();
+            resolve();
+          }, this.#options.transitionDuration);
+
+        } else {
+          // --- Solid Transition Mode or First Load ---
+          this.#element.style.backgroundImage = `url("${finalUrl}")`;
+          this.#element.style.backgroundSize = 'cover';
+          this.#element.style.backgroundRepeat = 'no-repeat';
+
+          const loader = this.#element.querySelector(`.cbg-loader-${this.#uid}`);
+          if (loader) {
+            loader.style.opacity = String(this.#options.minOverlay);
+          }
+          this.#hasLoadedFirstBackground = true;
+          setTimeout(() => {
+            resolve();
+          }, this.#options.transitionDuration);
         }
-
-        resolve();
       };
 
       img.onerror = () => {
-        console.warn(`[ChameleonBackgrounds] Failed to load image: ${src}`);
-        resolve();
+        img.remove();
+        console.warn(`[ChameleonBackgrounds] Failed to load image:`, srcConfig);
+        resolve(); // resolve anyway to keep logic flowing
       };
 
-      img.src = src;
+      img.src = urlStr;
     });
   }
 
@@ -307,9 +472,11 @@ class ChameleonBackgrounds {
   reloadBackground(src) {
     if (this.#destroyed) return Promise.resolve();
 
+    this.#transitionId++;
+
     if (src !== undefined) {
       if (this.#options.type === 'slider' && typeof src === 'string') {
-        // If the user passes a comma-separated string, split it. Otherwise wrap it.
+        // If the user passes a comma-separated string, split it.
         this.#options.src = src.includes(',') ? src.split(',').map(s => s.trim()) : [src];
       } else {
         this.#options.src = src;
@@ -318,28 +485,17 @@ class ChameleonBackgrounds {
 
     // Stop any running slider
     if (this.#sliderIntervalId !== null) {
-      clearInterval(this.#sliderIntervalId);
+      clearTimeout(this.#sliderIntervalId);
       this.#sliderIntervalId = null;
     }
 
-    const loader = this.#element.querySelector(`.cbg-loader-${this.#uid}`);
-    if (loader) {
-      loader.style.opacity = '1';
+    if (this.#options.type === 'single') {
+      const singleSrc = Array.isArray(this.#options.src) ? this.#options.src[0] : this.#options.src;
+      return this.#cycleSliderSlide(singleSrc, this.#transitionId);
+    } else if (this.#options.type === 'slider') {
+      this.#startSlider(this.#transitionId);
+      return Promise.resolve();
     }
-
-    return new Promise((resolve) => {
-      setTimeout(() => {
-        if (this.#destroyed) return resolve();
-
-        if (this.#options.type === 'single') {
-          const singleSrc = typeof this.#options.src === 'string' ? this.#options.src : this.#options.src[0];
-          this.#loadBackground(singleSrc, false).then(resolve);
-        } else if (this.#options.type === 'slider') {
-          this.#startSlider();
-          resolve();
-        }
-      }, this.#options.transitionDuration);
-    });
   }
 
   /**
@@ -352,14 +508,9 @@ class ChameleonBackgrounds {
     const normalized = ChameleonBackgrounds.#normalizeOptions(newOptions);
     this.#options = { ...this.#options, ...normalized };
 
-    // Remove old styles
-    if (this.#styleElement?.parentNode) {
-      this.#styleElement.parentNode.removeChild(this.#styleElement);
-      this.#styleElement = null;
-    }
-
-    // Inject updated styles
-    this.#injectStyles();
+    this.#updateCSSVariables();
+    // In v1/v2, reloadOptions did not restart the slider; the user called reloadBackground.
+    // We intentionally do not auto-restart here to prevent concurrent race conditions.
   }
 
   // ---------------------------------------------------------------------------
@@ -368,8 +519,9 @@ class ChameleonBackgrounds {
 
   /**
    * Start the background slideshow.
+   * @param {number} tid - The transition ID
    */
-  #startSlider() {
+  #startSlider(tid = this.#transitionId) {
     if (this.#destroyed) return;
 
     const sources = this.#options.src;
@@ -378,53 +530,86 @@ class ChameleonBackgrounds {
       return;
     }
 
-    // Load the first slide immediately
-    let index = 0;
-    this.#loadBackground(sources[index]).then(() => {
-      if (this.#destroyed) return;
+    this.#currentSlideIndex = 0;
+
+    if (this.#hasLoadedFirstBackground) {
+      // Instance already has a background, crossfade smoothly
+      this.#cycleSliderSlide(sources[this.#currentSlideIndex], tid).then(() => {
+        if (this.#destroyed || this.#transitionId !== tid) return;
+        this.#currentSlideIndex = 1;
+        if (sources.length > 1) this.#startSliderLoop();
+      });
+    } else {
+      // First load, load immediately without solid color flash
+      this.#loadBackground(sources[this.#currentSlideIndex], true, this.#options.transitionMode === 'crossfade').then(() => {
+        if (this.#destroyed || this.#transitionId !== tid) return;
+        this.#hasLoadedFirstBackground = true;
+        this.#currentSlideIndex = 1;
+        if (sources.length > 1) this.#startSliderLoop();
+      });
+    }
+  }
+
+  #startSliderLoop() {
+    if (this.#destroyed || this.#isPaused) return;
 
-      index = 1;
-      if (sources.length === 1) return; // only one slide, nothing to rotate
+    // Parse as integers to prevent string concatenation bugs if users passed strings
+    const sDuration = parseInt(this.#options.sliderDuration, 10) || 8000;
 
-      const interval = this.#options.sliderDuration + this.#options.transitionDuration * 2;
+    this.#sliderIntervalId = setTimeout(() => {
+      if (this.#destroyed || this.#isPaused) {
+        this.#sliderIntervalId = null;
+        return;
+      }
 
-      this.#sliderIntervalId = setInterval(() => {
-        if (this.#destroyed) {
-          clearInterval(this.#sliderIntervalId);
+      const tid = this.#transitionId;
+      this.#cycleSliderSlide(this.#options.src[this.#currentSlideIndex], tid).then(() => {
+        if (this.#destroyed || this.#isPaused || this.#transitionId !== tid) {
+          this.#sliderIntervalId = null;
           return;
         }
 
-        this.#cycleSliderSlide(sources[index]);
-        index++;
+        this.#currentSlideIndex++;
 
-        if (index >= sources.length) {
+        if (this.#currentSlideIndex >= this.#options.src.length) {
           if (this.#options.sliderLoop) {
-            index = 0;
+            this.#currentSlideIndex = 0;
           } else {
-            clearInterval(this.#sliderIntervalId);
             this.#sliderIntervalId = null;
+            return;
           }
         }
-      }, interval);
-    });
+
+        this.#startSliderLoop();
+      });
+    }, sDuration);
   }
 
   /**
    * Cycle to a specific slide without resetting the slider instance.
-   * @param {string} src - The image URL to load.
+   * @param {string|ChameleonImageConfig} src - The image URL/config to load.
+   * @param {number} tid - The transition ID
+   * @returns {Promise<void>}
    */
-  #cycleSliderSlide(src) {
-    if (this.#destroyed) return;
+  #cycleSliderSlide(src, tid = this.#transitionId) {
+    if (this.#destroyed) return Promise.resolve();
 
-    const loader = this.#element.querySelector(`.cbg-loader-${this.#uid}`);
-    if (loader) {
-      loader.style.opacity = '1';
-    }
+    return new Promise(resolve => {
+      if (this.#options.transitionMode === 'solid') {
+        const loader = this.#element.querySelector(`.cbg-loader-${this.#uid}`);
+        if (loader) {
+          loader.style.opacity = '1';
+        }
 
-    setTimeout(() => {
-      if (this.#destroyed) return;
-      this.#loadBackground(src, false);
-    }, this.#options.transitionDuration);
+        setTimeout(() => {
+          if (this.#destroyed || this.#transitionId !== tid) return resolve();
+          this.#loadBackground(src, false, false).then(resolve);
+        }, this.#options.transitionDuration);
+      } else {
+        // Crossfade mode triggers immediately
+        this.#loadBackground(src, false, true).then(resolve);
+      }
+    });
   }
 
   // ---------------------------------------------------------------------------