chameleon-backgrounds 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Lennart van Ballegoij (https://weblenn.com/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# ChameleonBackgrounds
+
+A **zero-dependency** JavaScript library to dynamically load background images with elegant fade-in transitions and slideshow support.
+
+> **v2.0** — Fully rewritten from scratch. No jQuery required.
+
+---
+
+## Why?
+
+Large background images slow down initial page loads. ChameleonBackgrounds **defers loading** these images and reveals them with a smooth CSS transition once they're fully downloaded — no layout shifts, no flicker.
+
+## Features
+
+- 🎯 **Zero dependencies** — no jQuery, no frameworks
+- 🖼️ **Single image** mode with preload + fade-in
+- 🎠 **Slider** mode with configurable duration and looping
+- 🎨 **Overlay** support with color, pattern images, and minimum opacity
+- 🧹 **`destroy()`** method for clean teardown
+- 📦 **ES Module** + **UMD** dual distribution
+- 🔄 **Backward compatible** with v1 snake_case option names
+
+---
+
+## Installation
+
+### npm
+
+```bash
+npm install chameleon-backgrounds
+```
+
+### CDN / Script Tag
+
+```html
+<script src="dist/chameleon-backgrounds.js"></script>
+```
+
+### ES Module
+
+```js
+import ChameleonBackgrounds from 'chameleon-backgrounds';
+```
+
+---
+
+## Quick Start
+
+### Single Background
+
+```html
+<script src="dist/chameleon-backgrounds.js"></script>
+<script>
+  const bg = new ChameleonBackgrounds({
+    element: 'body',
+    type: 'single',
+    src: './img/chameleon.jpg',
+    overlayColor: '#0f1e25',
+    overlayImage: './img/transparent-tile.png', // optional
+    minOverlay: 0.5,                            // optional, default: 0
+    transitionDuration: 2000
+  });
+</script>
+```
+
+### Slider / Slideshow
+
+```html
+<div id="hero"></div>
+
+<script src="dist/chameleon-backgrounds.js"></script>
+<script>
+  const bg = new ChameleonBackgrounds({
+    element: '#hero',
+    type: 'slider',
+    src: [
+      './img/image1.jpg',
+      './img/image2.jpg',
+      './img/image3.jpg'
+    ],
+    overlayColor: '#656946',
+    overlayImage: './img/transparent-tile.png', // optional
+    minOverlay: 0.6,                            // optional
+    transitionDuration: 3000,
+    sliderDuration: 4000,
+    sliderLoop: true
+  });
+</script>
+```
+
+### ES Module Usage
+
+```js
+import ChameleonBackgrounds from 'chameleon-backgrounds';
+
+const bg = new ChameleonBackgrounds({
+  element: '#hero',
+  type: 'single',
+  src: '/images/hero.jpg',
+  overlayColor: '#1a1a2e',
+  transitionDuration: 1500
+});
+
+// Clean up when done
+bg.destroy();
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `element` | `string \| HTMLElement` | `'body'` | yes | CSS selector or DOM element to attach to |
+| `type` | `'single' \| 'slider'` | `'single'` | yes | Background mode |
+| `src` | `string \| string[]` | `''` | yes | Image URL (single) or array of URLs (slider) |
+| `overlayColor` | `string` | `'#0f1e25'` | yes | Overlay color (hex, rgb, rgba, hsl) |
+| `overlayImage` | `string \| null` | `null` | no | Overlay pattern image URL |
+| `minOverlay` | `number` | `0` | no | Minimum overlay opacity after fade (0–1) |
+| `transitionDuration` | `number` | `2000` | yes | Fade duration in milliseconds |
+| `sliderDuration` | `number` | `8000` | slider only | Time each slide is shown (ms) |
+| `sliderLoop` | `boolean` | `false` | slider only | Restart slider after last slide |
+
+### Legacy Option Names
+
+For backward compatibility, v1 snake_case option names are still supported:
+
+| v1 (snake_case) | v2 (camelCase) |
+|---|---|
+| `transition_duration` | `transitionDuration` |
+| `slider_duration` | `sliderDuration` |
+| `slider_loop` | `sliderLoop` |
+| `min_overlay` | `minOverlay` |
+| `overlay_color` | `overlayColor` |
+| `overlay_image` | `overlayImage` |
+
+---
+
+## API
+
+### `new ChameleonBackgrounds(options)`
+
+Creates a new instance and immediately begins loading.
+
+### `.destroy()`
+
+Stops any running slider, removes all injected DOM and styles, and restores the target element to its original state.
+
+### `.getOptions()` / `.options` (ESM)
+
+Returns a read-only copy of the resolved options.
+
+---
+
+## Migration from v1
+
+1. **Remove jQuery** — ChameleonBackgrounds v2 uses native DOM APIs.
+2. **Rename options** (optional) — snake_case names still work, but camelCase is now preferred.
+3. **Use `new`** — `new ChameleonBackgrounds(options)` works identically to v1.
+4. **Clean up** — Call `.destroy()` when removing the background (new in v2).
+
+```diff
+- <script src="jquery.min.js"></script>
+- <script src="chameleonbackgrounds.js"></script>
++ <script src="dist/chameleon-backgrounds.js"></script>
+
+  <script>
+-   var options = {
++   const options = {
+      element: 'body',
+      type: 'single',
+      src: './img/chameleon.jpg',
+      overlayColor: '#0f1e25',
+-     transition_duration: 2000
++     transitionDuration: 2000
+    };
+
+-   background = new ChameleonBackgrounds(options);
++   const background = new ChameleonBackgrounds(options);
+  </script>
+```
+
+---
+
+## Tips
+
+- **Transparent patterns** work great as `overlayImage` — combine with `overlayColor` and `minOverlay` for cohesive designs across different background images.
+- Find awesome transparent patterns at [transparenttextures.com](https://www.transparenttextures.com/).
+
+---
+
+## License
+
+[MIT](./LICENSE) © [Lennart van Ballegoij](https://weblenn.com/)

package/dist/chameleon-backgrounds.js

@@ -0,0 +1,356 @@
+/**
+ *    _____ _                          _
+ *   / ____| |                        | |
+ *  | |    | |__   __ _ _ __ ___   ___| | ___  ___  _ __
+ *  | |    | '_ \ / _` | '_ ` _ \ / _ \ |/ _ \/ _ \| '_ \
+ *  | |____| | | | (_| | | | | | |  __/ |  __/ (_) | | | |
+ *   \_____|_| |_|\__,_|_| |_| |_|\___|_|\___|\___|_| |_|_
+ *  |  _ \           | |                                 | |
+ *  | |_) | __ _  ___| | ____ _ _ __ ___  _   _ _ __   __| |___
+ *  |  _ < / _` |/ __| |/ / _` | '__/ _ \| | | | '_ \ / _` / __|
+ *  | |_) | (_| | (__|   < (_| | | | (_) | |_| | | | | (_| \__ \
+ *  |____/ \__,_|\___|_|\_\__, |_|  \___/ \__,_|_| |_|\__,_|___/
+ *                         __/ |
+ *                        |___/
+ *
+ *  ChameleonBackgrounds v2.0.0 — UMD Bundle
+ *  A zero-dependency JavaScript library to dynamically load background
+ *  images with elegant fade-in transitions and slideshow support.
+ *
+ *  @author Lennart van Ballegoij (https://weblenn.com/)
+ *  @license MIT
+ *  @see https://github.com/WebLenn/ChameleonBackgrounds
+ */
+(function (root, factory) {
+  if (typeof define === 'function' && define.amd) {
+    // AMD
+    define([], factory);
+  } else if (typeof module === 'object' && module.exports) {
+    // CommonJS
+    module.exports = factory();
+  } else {
+    // Browser global
+    root.ChameleonBackgrounds = factory();
+  }
+}(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  /**
+   * @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}                  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).
+   * @property {number}                  [transitionDuration=2000] - Fade duration in milliseconds.
+   * @property {number}                  [sliderDuration=8000]     - Time each slide is shown in milliseconds.
+   * @property {boolean}                 [sliderLoop=false]        - Whether the slider restarts after the last slide.
+   */
+
+  const DEFAULTS = Object.freeze({
+    element: 'body',
+    type: 'single',
+    src: '',
+    overlayColor: '#0f1e25',
+    overlayImage: null,
+    minOverlay: 0,
+    transitionDuration: 2000,
+    sliderDuration: 8000,
+    sliderLoop: false,
+  });
+
+  const ALIASES = Object.freeze({
+    transition_duration: 'transitionDuration',
+    slider_duration: 'sliderDuration',
+    slider_loop: 'sliderLoop',
+    min_overlay: 'minOverlay',
+    overlay_color: 'overlayColor',
+    overlay_image: 'overlayImage',
+  });
+
+  /**
+   * Convert legacy snake_case option keys to camelCase.
+   */
+  function normalizeOptions(opts) {
+    const result = {};
+    for (const key of Object.keys(opts)) {
+      const alias = ALIASES[key];
+      result[alias !== undefined ? alias : key] = opts[key];
+    }
+    return result;
+  }
+
+  /**
+   * Resolve a CSS selector string or HTMLElement to an HTMLElement.
+   */
+  function resolveElement(el) {
+    if (el instanceof HTMLElement) return el;
+    if (typeof el === 'string') {
+      if (el === 'body') return document.body;
+      var found = document.querySelector(el);
+      if (!found) throw new Error('[ChameleonBackgrounds] Element not found: ' + el);
+      return found;
+    }
+    throw new TypeError('[ChameleonBackgrounds] Invalid element: ' + el);
+  }
+
+  /**
+   * Generate a short unique ID for scoping styles.
+   */
+  function generateUID() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+      return crypto.randomUUID().slice(0, 8);
+    }
+    return Array.from({ length: 8 }, function () {
+      return 'abcdefghijklmnopqrstuvwxyz0123456789'.charAt(Math.floor(Math.random() * 36));
+    }).join('');
+  }
+
+  // -------------------------------------------------------------------------
+  //  Constructor
+  // -------------------------------------------------------------------------
+
+  function ChameleonBackgrounds(options) {
+    if (!(this instanceof ChameleonBackgrounds)) {
+      return new ChameleonBackgrounds(options);
+    }
+
+    var normalized = normalizeOptions(options || {});
+    this._options = {};
+    for (var k in DEFAULTS) {
+      if (DEFAULTS.hasOwnProperty(k)) {
+        this._options[k] = normalized[k] !== undefined ? normalized[k] : DEFAULTS[k];
+      }
+    }
+
+    this._uid = generateUID();
+    this._element = resolveElement(this._options.element);
+    this._originalHTML = this._element.innerHTML;
+    this._styleElement = null;
+    this._sliderIntervalId = null;
+    this._destroyed = false;
+
+    this._init();
+  }
+
+  // -------------------------------------------------------------------------
+  //  Public API
+  // -------------------------------------------------------------------------
+
+  /**
+   * Clean up all injected DOM, styles, and intervals.
+   * Restores the target element to its original state.
+   */
+  ChameleonBackgrounds.prototype.destroy = function () {
+    if (this._destroyed) return;
+    this._destroyed = true;
+
+    if (this._sliderIntervalId !== null) {
+      clearInterval(this._sliderIntervalId);
+      this._sliderIntervalId = null;
+    }
+
+    if (this._styleElement && this._styleElement.parentNode) {
+      this._styleElement.parentNode.removeChild(this._styleElement);
+      this._styleElement = null;
+    }
+
+    this._element.innerHTML = this._originalHTML;
+    this._element.style.backgroundImage = '';
+  };
+
+  /**
+   * Readonly copy of the resolved options.
+   */
+  ChameleonBackgrounds.prototype.getOptions = function () {
+    var copy = {};
+    for (var k in this._options) {
+      if (this._options.hasOwnProperty(k)) {
+        copy[k] = this._options[k];
+      }
+    }
+    return copy;
+  };
+
+  // -------------------------------------------------------------------------
+  //  Initialization (private by convention)
+  // -------------------------------------------------------------------------
+
+  ChameleonBackgrounds.prototype._init = function () {
+    this._injectStyles();
+    this._buildDOM();
+
+    var self = this;
+
+    if (this._element === document.body || this._element.matches('body')) {
+      // Use a microtask so the DOM changes settle first
+      Promise.resolve().then(function () { self._retrieveBackground(); });
+    } else {
+      if (document.readyState === 'complete') {
+        this._retrieveBackground();
+      } else {
+        window.addEventListener('load', function onLoad() {
+          window.removeEventListener('load', onLoad);
+          self._retrieveBackground();
+        });
+      }
+    }
+  };
+
+  ChameleonBackgrounds.prototype._injectStyles = function () {
+    var uid = this._uid;
+    var selector = this._options.element === 'body' || this._element.matches('body')
+      ? 'body'
+      : this._options.element;
+    var duration = this._options.transitionDuration / 1000;
+    var position = this._element.matches('body') ? 'fixed' : 'absolute';
+    var overlayBg = this._options.overlayImage
+      ? 'url(' + this._options.overlayImage + ')'
+      : 'none';
+
+    var selectorStr = typeof selector === 'string' ? selector : '.cbg-host-' + uid;
+
+    var css =
+      selectorStr + ' { position: relative; } ' +
+      '#cbg-inner-' + uid + ' { z-index: 2; position: relative; } ' +
+      '.cbg-loader-' + uid + ' { ' +
+      'height: 100%; width: 100%; ' +
+      'position: ' + position + '; ' +
+      'background-image: ' + overlayBg + '; ' +
+      'background-color: ' + this._options.overlayColor + '; ' +
+      'opacity: 1; z-index: 1; ' +
+      'transition: opacity ' + duration + 's ease; ' +
+      'top: 0; left: 0; ' +
+      '}';
+
+    var style = document.createElement('style');
+    style.setAttribute('data-chameleon-uid', uid);
+    style.textContent = css;
+    document.head.appendChild(style);
+    this._styleElement = style;
+  };
+
+  ChameleonBackgrounds.prototype._buildDOM = function () {
+    var uid = this._uid;
+    var content = this._element.innerHTML;
+
+    var wrapper = document.createElement('div');
+    wrapper.id = 'cbg-inner-' + uid;
+    wrapper.innerHTML = content;
+
+    var loader = document.createElement('div');
+    loader.className = 'cbg-loader-' + uid;
+
+    this._element.innerHTML = '';
+    this._element.appendChild(wrapper);
+    this._element.appendChild(loader);
+  };
+
+  // -------------------------------------------------------------------------
+  //  Background Loading
+  // -------------------------------------------------------------------------
+
+  ChameleonBackgrounds.prototype._retrieveBackground = function () {
+    if (this._destroyed) return;
+
+    if (this._options.type === 'single') {
+      var src = typeof this._options.src === 'string'
+        ? this._options.src
+        : this._options.src[0];
+      this._loadBackground(src);
+    } else if (this._options.type === 'slider') {
+      this._startSlider();
+    }
+  };
+
+  ChameleonBackgrounds.prototype._loadBackground = function (src, callback) {
+    if (this._destroyed) { if (callback) callback(); return; }
+
+    var self = this;
+    var img = new Image();
+
+    img.onload = function () {
+      if (self._destroyed) { if (callback) callback(); return; }
+
+      self._element.style.backgroundImage = 'url(' + src + ')';
+      self._element.style.backgroundSize = 'cover';
+
+      var loader = self._element.querySelector('.cbg-loader-' + self._uid);
+      if (loader) {
+        loader.style.opacity = String(self._options.minOverlay);
+      }
+
+      if (callback) callback();
+    };
+
+    img.onerror = function () {
+      console.warn('[ChameleonBackgrounds] Failed to load image: ' + src);
+      if (callback) callback();
+    };
+
+    img.src = src;
+  };
+
+  ChameleonBackgrounds.prototype.reloadBackground = function (src, callback) {
+    if (this._destroyed) { if (callback) callback(); return; }
+
+    var loader = this._element.querySelector('.cbg-loader-' + this._uid);
+    if (loader) {
+      loader.style.opacity = '1';
+    }
+
+    var self = this;
+    setTimeout(function () {
+      if (self._destroyed) { if (callback) callback(); return; }
+      self._loadBackground(src, callback);
+    }, this._options.transitionDuration);
+  };
+
+  // -------------------------------------------------------------------------
+  //  Slider
+  // -------------------------------------------------------------------------
+
+  ChameleonBackgrounds.prototype._startSlider = function () {
+    if (this._destroyed) return;
+
+    var sources = this._options.src;
+    if (!Array.isArray(sources) || sources.length === 0) {
+      console.warn('[ChameleonBackgrounds] Slider mode requires an array of image URLs in `src`.');
+      return;
+    }
+
+    var self = this;
+    var index = 0;
+
+    this._loadBackground(sources[index], function () {
+      if (self._destroyed) return;
+
+      index = 1;
+      if (sources.length === 1) return;
+
+      var interval = self._options.sliderDuration + self._options.transitionDuration * 2;
+
+      self._sliderIntervalId = setInterval(function () {
+        if (self._destroyed) {
+          clearInterval(self._sliderIntervalId);
+          return;
+        }
+
+        self.reloadBackground(sources[index]);
+        index++;
+
+        if (index >= sources.length) {
+          if (self._options.sliderLoop) {
+            index = 0;
+          } else {
+            clearInterval(self._sliderIntervalId);
+            self._sliderIntervalId = null;
+          }
+        }
+      }, interval);
+    });
+  };
+
+  return ChameleonBackgrounds;
+}));

package/dist/chameleon-backgrounds.min.js

@@ -0,0 +1,2 @@
+/*! For license information please see chameleon-backgrounds.min.js.LICENSE.txt */
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports.ChameleonBackgrounds=t():e.ChameleonBackgrounds=t()}(this,()=>(()=>{"use strict";const e={d:(t,n)=>{if(Array.isArray(n))for(var o=0;o<n.length;){var r=n[o++],i=n[o++];e.o(t,r)?0===i&&o++:0===i?Object.defineProperty(t,r,{enumerable:!0,value:n[o++]}):Object.defineProperty(t,r,{enumerable:!0,get:i})}else for(var r in n)e.o(n,r)&&!e.o(t,r)&&Object.defineProperty(t,r,{enumerable:!0,get:n[r]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t)};let t={};class n{static#e=Object.freeze({element:"body",type:"single",src:"",overlayColor:"#0f1e25",overlayImage:null,minOverlay:0,transitionDuration:2e3,sliderDuration:8e3,sliderLoop:!1});static#t=Object.freeze({transition_duration:"transitionDuration",slider_duration:"sliderDuration",slider_loop:"sliderLoop",min_overlay:"minOverlay",overlay_color:"overlayColor",overlay_image:"overlayImage"});#n;#o;#r;#i;#s=null;#l=null;#a=!1;constructor(e={}){const t=n.#d(e);this.#n={...n.#e,...t},this.#r=n.#c(),this.#o=n.#h(this.#n.element),this.#i=this.#o.innerHTML,this.#u()}destroy(){this.#a||(this.#a=!0,null!==this.#l&&(clearInterval(this.#l),this.#l=null),this.#s?.parentNode&&(this.#s.parentNode.removeChild(this.#s),this.#s=null),this.#o.innerHTML=this.#i,this.#o.style.backgroundImage="")}get options(){return{...this.#n}}#u(){this.#m(),this.#y(),this.#o.matches("body")?queueMicrotask(()=>this.#p()):"complete"===document.readyState?this.#p():window.addEventListener("load",()=>this.#p(),{once:!0})}#m(){const e=this.#r,t="body"===this.#n.element||this.#o.matches("body")?"body":this.#n.element,n=this.#n.transitionDuration/1e3,o=`\n      ${"string"==typeof t?t:`.cbg-host-${e}`} {\n        position: relative;\n      }\n\n      #cbg-inner-${e} {\n        z-index: 2;\n        position: relative;\n      }\n\n      .cbg-loader-${e} {\n        height: 100%;\n        width: 100%;\n        position: ${this.#o.matches("body")?"fixed":"absolute"};\n        background-image: ${this.#n.overlayImage?`url(${this.#n.overlayImage})`:"none"};\n        background-color: ${this.#n.overlayColor};\n        opacity: 1;\n        z-index: 1;\n        transition: opacity ${n}s ease;\n        top: 0;\n        left: 0;\n      }\n    `,r=document.createElement("style");r.dataset.chameleonUid=e,r.textContent=o,document.head.appendChild(r),this.#s=r}#y(){const e=this.#r,t=this.#o.innerHTML,n=document.createElement("div");n.id=`cbg-inner-${e}`,n.innerHTML=t;const o=document.createElement("div");o.classList.add(`cbg-loader-${e}`),this.#o.innerHTML="",this.#o.appendChild(n),this.#o.appendChild(o)}#p(){this.#a||("single"===this.#n.type?this.#g("string"==typeof this.#n.src?this.#n.src:this.#n.src[0]):"slider"===this.#n.type&&this.#f())}#g(e,t=!0){return this.#a?Promise.resolve():new Promise(t=>{const n=new Image;n.onload=()=>{if(this.#a)return t();this.#o.style.backgroundImage=`url(${e})`,this.#o.style.backgroundSize="cover";const n=this.#o.querySelector(`.cbg-loader-${this.#r}`);n&&(n.style.opacity=String(this.#n.minOverlay)),t()},n.onerror=()=>{console.warn(`[ChameleonBackgrounds] Failed to load image: ${e}`),t()},n.src=e})}reloadBackground(e){if(this.#a)return Promise.resolve();const t=this.#o.querySelector(`.cbg-loader-${this.#r}`);return t&&(t.style.opacity="1"),new Promise(t=>{setTimeout(()=>{if(this.#a)return t();this.#g(e,!1).then(t)},this.#n.transitionDuration)})}#f(){if(this.#a)return;const e=this.#n.src;if(!Array.isArray(e)||0===e.length)return void console.warn("[ChameleonBackgrounds] Slider mode requires an array of image URLs in `src`.");let t=0;this.#g(e[t]).then(()=>{if(this.#a)return;if(t=1,1===e.length)return;const n=this.#n.sliderDuration+2*this.#n.transitionDuration;this.#l=setInterval(()=>{this.#a?clearInterval(this.#l):(this.reloadBackground(e[t]),t++,t>=e.length&&(this.#n.sliderLoop?t=0:(clearInterval(this.#l),this.#l=null)))},n)})}static#d(e){const t={};for(const[o,r]of Object.entries(e))t[n.#t[o]??o]=r;return t}static#h(e){if(e instanceof HTMLElement)return e;if("string"==typeof e){if("body"===e)return document.body;const t=document.querySelector(e);if(!t)throw new Error(`[ChameleonBackgrounds] Element not found: ${e}`);return t}throw new TypeError(`[ChameleonBackgrounds] Invalid element: ${e}`)}static#c(){return"undefined"!=typeof crypto&&"function"==typeof crypto.randomUUID?crypto.randomUUID().slice(0,8):Array.from({length:8},()=>"abcdefghijklmnopqrstuvwxyz0123456789".charAt(Math.floor(36*Math.random()))).join("")}}const o=n;return e.d(t,["default",0,o]),t=t.default,t})());

package/dist/chameleon-backgrounds.min.js.LICENSE.txt

@@ -0,0 +1,24 @@
+/**
+ *    _____ _                          _
+ *   / ____| |                        | |
+ *  | |    | |__   __ _ _ __ ___   ___| | ___  ___  _ __
+ *  | |    | '_ \ / _` | '_ ` _ \ / _ \ |/ _ \/ _ \| '_ \
+ *  | |____| | | | (_| | | | | | |  __/ |  __/ (_) | | | |
+ *   \_____|_| |_|\__,_|_| |_| |_|\___|_|\___|\___|_| |_|_
+ *  |  _ \           | |                                 | |
+ *  | |_) | __ _  ___| | ____ _ _ __ ___  _   _ _ __   __| |___
+ *  |  _ < / _` |/ __| |/ / _` | '__/ _ \| | | | '_ \ / _` / __|
+ *  | |_) | (_| | (__|   < (_| | | | (_) | |_| | | | | (_| \__ \
+ *  |____/ \__,_|\___|_|\_\__, |_|  \___/ \__,_|_| |_|\__,_|___/
+ *                         __/ |
+ *                        |___/
+ *
+ *  @module ChameleonBackgrounds
+ *  @version 2.0.0
+ *  @author Lennart van Ballegoij (https://weblenn.com/)
+ *  @license MIT
+ *  @see https://github.com/WebLenn/ChameleonBackgrounds
+ *
+ *  A zero-dependency JavaScript library to dynamically load background
+ *  images with elegant fade-in transitions and slideshow support.
+ */

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "chameleon-backgrounds",
+  "version": "2.0.0",
+  "description": "A zero-dependency JavaScript library to dynamically load background images with elegant fade-in transitions and slideshow support.",
+  "type": "module",
+  "main": "dist/chameleon-backgrounds.js",
+  "module": "src/chameleon-backgrounds.js",
+  "exports": {
+    ".": {
+      "import": "./src/chameleon-backgrounds.js",
+      "require": "./dist/chameleon-backgrounds.js",
+      "default": "./dist/chameleon-backgrounds.js"
+    }
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "webpack",
+    "test": "echo \"Open test/index.html in a browser to test.\""
+  },
+  "keywords": [
+    "background",
+    "image",
+    "loader",
+    "slider",
+    "slideshow",
+    "fade",
+    "transition",
+    "vanilla",
+    "javascript",
+    "no-jquery"
+  ],
+  "author": "Lennart van Ballegoij (https://weblenn.com/)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WebLenn/ChameleonBackgrounds.git"
+  },
+  "homepage": "https://github.com/WebLenn/ChameleonBackgrounds#readme",
+  "bugs": {
+    "url": "https://github.com/WebLenn/ChameleonBackgrounds/issues"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "devDependencies": {
+    "webpack": "^5.109.0",
+    "webpack-cli": "^7.2.1"
+  }
+}

package/src/chameleon-backgrounds.js

@@ -0,0 +1,398 @@
+/**
+ *    _____ _                          _
+ *   / ____| |                        | |
+ *  | |    | |__   __ _ _ __ ___   ___| | ___  ___  _ __
+ *  | |    | '_ \ / _` | '_ ` _ \ / _ \ |/ _ \/ _ \| '_ \
+ *  | |____| | | | (_| | | | | | |  __/ |  __/ (_) | | | |
+ *   \_____|_| |_|\__,_|_| |_| |_|\___|_|\___|\___|_| |_|_
+ *  |  _ \           | |                                 | |
+ *  | |_) | __ _  ___| | ____ _ _ __ ___  _   _ _ __   __| |___
+ *  |  _ < / _` |/ __| |/ / _` | '__/ _ \| | | | '_ \ / _` / __|
+ *  | |_) | (_| | (__|   < (_| | | | (_) | |_| | | | | (_| \__ \
+ *  |____/ \__,_|\___|_|\_\__, |_|  \___/ \__,_|_| |_|\__,_|___/
+ *                         __/ |
+ *                        |___/
+ *
+ *  @module ChameleonBackgrounds
+ *  @version 2.0.0
+ *  @author Lennart van Ballegoij (https://weblenn.com/)
+ *  @license MIT
+ *  @see https://github.com/WebLenn/ChameleonBackgrounds
+ *
+ *  A zero-dependency JavaScript library to dynamically load background
+ *  images with elegant fade-in transitions and slideshow support.
+ */
+
+/**
+ * @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}                  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).
+ * @property {number}                  [transitionDuration=2000] - Fade duration in milliseconds.
+ * @property {number}                  [sliderDuration=8000]     - Time each slide is shown in milliseconds.
+ * @property {boolean}                 [sliderLoop=false]        - Whether the slider restarts after the last slide.
+ */
+
+class ChameleonBackgrounds {
+  /** @type {ChameleonOptions} */
+  static #DEFAULTS = Object.freeze({
+    element: 'body',
+    type: 'single',
+    src: '',
+    overlayColor: '#0f1e25',
+    overlayImage: null,
+    minOverlay: 0,
+    transitionDuration: 2000,
+    sliderDuration: 8000,
+    sliderLoop: false,
+  });
+
+  // Legacy snake_case → camelCase alias map
+  static #ALIASES = Object.freeze({
+    transition_duration: 'transitionDuration',
+    slider_duration: 'sliderDuration',
+    slider_loop: 'sliderLoop',
+    min_overlay: 'minOverlay',
+    overlay_color: 'overlayColor',
+    overlay_image: 'overlayImage',
+  });
+
+  /** @type {ChameleonOptions} */
+  #options;
+
+  /** @type {HTMLElement} */
+  #element;
+
+  /** @type {string} */
+  #uid;
+
+  /** @type {string} */
+  #originalHTML;
+
+  /** @type {HTMLStyleElement|null} */
+  #styleElement = null;
+
+  /** @type {number|null} */
+  #sliderIntervalId = null;
+
+  /** @type {boolean} */
+  #destroyed = false;
+
+  /**
+   * Create a new ChameleonBackgrounds instance.
+   * @param {Partial<ChameleonOptions>} [options]
+   */
+  constructor(options = {}) {
+    const normalized = ChameleonBackgrounds.#normalizeOptions(options);
+    this.#options = { ...ChameleonBackgrounds.#DEFAULTS, ...normalized };
+    this.#uid = ChameleonBackgrounds.#generateUID();
+    this.#element = ChameleonBackgrounds.#resolveElement(this.#options.element);
+    this.#originalHTML = this.#element.innerHTML;
+
+    this.#init();
+  }
+
+  // ---------------------------------------------------------------------------
+  //  Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Clean up all injected DOM, styles, and intervals.
+   * Restores the target element to its original state.
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+
+    // Stop any running slider
+    if (this.#sliderIntervalId !== null) {
+      clearInterval(this.#sliderIntervalId);
+      this.#sliderIntervalId = null;
+    }
+
+    // Remove injected style element
+    if (this.#styleElement?.parentNode) {
+      this.#styleElement.parentNode.removeChild(this.#styleElement);
+      this.#styleElement = null;
+    }
+
+    // Restore original HTML and remove inline background-image
+    this.#element.innerHTML = this.#originalHTML;
+    this.#element.style.backgroundImage = '';
+  }
+
+  /**
+   * The resolved options (read-only copy).
+   * @returns {ChameleonOptions}
+   */
+  get options() {
+    return { ...this.#options };
+  }
+
+  // ---------------------------------------------------------------------------
+  //  Initialization
+  // ---------------------------------------------------------------------------
+
+  #init() {
+    this.#injectStyles();
+    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());
+    } else {
+      if (document.readyState === 'complete') {
+        this.#retrieveBackground();
+      } else {
+        window.addEventListener('load', () => this.#retrieveBackground(), { once: true });
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  //  DOM Construction
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Inject a scoped <style> element into the <head>.
+   */
+  #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';
+
+    const css = `
+      ${typeof selector === 'string' ? selector : `.cbg-host-${uid}`} {
+        position: relative;
+      }
+
+      #cbg-inner-${uid} {
+        z-index: 2;
+        position: relative;
+      }
+
+      .cbg-loader-${uid} {
+        height: 100%;
+        width: 100%;
+        position: ${position};
+        background-image: ${overlayBg};
+        background-color: ${this.#options.overlayColor};
+        opacity: 1;
+        z-index: 1;
+        transition: opacity ${duration}s ease;
+        top: 0;
+        left: 0;
+      }
+    `;
+
+    const style = document.createElement('style');
+    style.dataset.chameleonUid = uid;
+    style.textContent = css;
+    document.head.appendChild(style);
+    this.#styleElement = style;
+  }
+
+  /**
+   * Wrap existing content and insert the overlay loader.
+   */
+  #buildDOM() {
+    const uid = this.#uid;
+    const content = this.#element.innerHTML;
+
+    const wrapper = document.createElement('div');
+    wrapper.id = `cbg-inner-${uid}`;
+    wrapper.innerHTML = content;
+
+    const loader = document.createElement('div');
+    loader.classList.add(`cbg-loader-${uid}`);
+
+    // Replace element contents
+    this.#element.innerHTML = '';
+    this.#element.appendChild(wrapper);
+    this.#element.appendChild(loader);
+  }
+
+  // ---------------------------------------------------------------------------
+  //  Background Loading
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Route to the correct loader based on type.
+   */
+  #retrieveBackground() {
+    if (this.#destroyed) return;
+
+    if (this.#options.type === 'single') {
+      this.#loadBackground(typeof this.#options.src === 'string' ? this.#options.src : this.#options.src[0]);
+    } else if (this.#options.type === 'slider') {
+      this.#startSlider();
+    }
+  }
+
+  /**
+   * Preload an image and apply it as the element's background.
+   * @param {string}   src      - Image URL to load.
+   * @param {boolean}  [isFirst=true] - Whether this is the first image (skips overlay reset).
+   * @returns {Promise<void>}
+   */
+  #loadBackground(src, isFirst = true) {
+    if (this.#destroyed) return Promise.resolve();
+
+    return new Promise((resolve) => {
+      const img = new Image();
+
+      img.onload = () => {
+        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);
+        }
+
+        resolve();
+      };
+
+      img.onerror = () => {
+        console.warn(`[ChameleonBackgrounds] Failed to load image: ${src}`);
+        resolve();
+      };
+
+      img.src = src;
+    });
+  }
+
+  /**
+   * Reload background with a fade-out → swap → fade-in cycle.
+   * @param {string} src - New image URL.
+   * @returns {Promise<void>}
+   */
+  reloadBackground(src) {
+    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) => {
+      setTimeout(() => {
+        if (this.#destroyed) return resolve();
+        this.#loadBackground(src, false).then(resolve);
+      }, this.#options.transitionDuration);
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  //  Slider
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Start the background slideshow.
+   */
+  #startSlider() {
+    if (this.#destroyed) return;
+
+    const sources = this.#options.src;
+    if (!Array.isArray(sources) || sources.length === 0) {
+      console.warn('[ChameleonBackgrounds] Slider mode requires an array of image URLs in `src`.');
+      return;
+    }
+
+    // Load the first slide immediately
+    let index = 0;
+    this.#loadBackground(sources[index]).then(() => {
+      if (this.#destroyed) return;
+
+      index = 1;
+      if (sources.length === 1) return; // only one slide, nothing to rotate
+
+      const interval = this.#options.sliderDuration + this.#options.transitionDuration * 2;
+
+      this.#sliderIntervalId = setInterval(() => {
+        if (this.#destroyed) {
+          clearInterval(this.#sliderIntervalId);
+          return;
+        }
+
+        this.reloadBackground(sources[index]);
+        index++;
+
+        if (index >= sources.length) {
+          if (this.#options.sliderLoop) {
+            index = 0;
+          } else {
+            clearInterval(this.#sliderIntervalId);
+            this.#sliderIntervalId = null;
+          }
+        }
+      }, interval);
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  //  Static Helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Convert legacy snake_case option keys to camelCase.
+   * @param {Object} opts
+   * @returns {Object}
+   */
+  static #normalizeOptions(opts) {
+    const result = {};
+    for (const [key, value] of Object.entries(opts)) {
+      const alias = ChameleonBackgrounds.#ALIASES[key];
+      result[alias ?? key] = value;
+    }
+    return result;
+  }
+
+  /**
+   * Resolve a CSS selector string or HTMLElement to an HTMLElement.
+   * @param {string|HTMLElement} el
+   * @returns {HTMLElement}
+   */
+  static #resolveElement(el) {
+    if (el instanceof HTMLElement) return el;
+    if (typeof el === 'string') {
+      if (el === 'body') return document.body;
+      const found = document.querySelector(el);
+      if (!found) throw new Error(`[ChameleonBackgrounds] Element not found: ${el}`);
+      return /** @type {HTMLElement} */ (found);
+    }
+    throw new TypeError(`[ChameleonBackgrounds] Invalid element: ${el}`);
+  }
+
+  /**
+   * Generate a short unique ID for scoping styles.
+   * @returns {string}
+   */
+  static #generateUID() {
+    // Prefer crypto.randomUUID where available, otherwise fall back
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+      return crypto.randomUUID().slice(0, 8);
+    }
+    // Fallback: random alphanumeric string
+    return Array.from({ length: 8 }, () =>
+      'abcdefghijklmnopqrstuvwxyz0123456789'.charAt(Math.floor(Math.random() * 36))
+    ).join('');
+  }
+}
+
+export default ChameleonBackgrounds;
+export { ChameleonBackgrounds };