@frybynite/image-cloud 0.2.8 → 0.2.9

package/README.md

@@ -2,7 +2,7 @@
 
 # Image Cloud Library
 
-A TypeScript library for creating interactive image clouds with animated scattered layouts and zoom effects. Supports multiple image sources (Google Drive, static URLs) and layout algorithms.
+A TypeScript library for creating interactive image clouds with animated scattered layouts and zoom effects. Supports multiple image sources (static URLs, JSON endpoints, Google Drive) and layout algorithms.
 
 > [!WARNING]
 > ⚠️ All minor versions of this library before 1.0 (e.g., 0.1, 0.2, ...) will include breaking changes during development. Please re-test every time before upgrading until we have published v1.0.
@@ -15,7 +15,7 @@ A TypeScript library for creating interactive image clouds with animated scatter
 - 🔍 Zoom/focus interactions with keyboard navigation
 - 🎨 State-based image styling (borders, shadows, filters for default/hover/focused)
 - 📱 Responsive design with adaptive sizing
-- 🖼️ Multiple image sources (Google Drive, static URLs, composite loaders)
+- 🖼️ Multiple image sources (static URLs, JSON endpoints, Google Drive, composite loaders)
 - 🛠️ Interactive configurator for visual configuration
 - 📦 Zero runtime dependencies
 - 🔷 Full TypeScript support
@@ -121,7 +121,7 @@ await cloud.init();
 
 For detailed configuration, see the documentation in the `docs/` folder:
 
-1. **[Loaders](docs/LOADERS.md)** — Configure image sources (static URLs, local paths, Google Drive folders)
+1. **[Loaders](docs/LOADERS.md)** — Configure image sources (static URLs, JSON endpoints, local paths, Google Drive folders)
 2. **[Layout Generators](docs/GENERATORS.md)** — Choose and customize layout algorithms (radial, grid, spiral, cluster, random)
 3. **[Image Sizing](docs/IMAGE_SIZING.md)** — Control base sizes, variance, and responsive/adaptive behavior
 4. **[Full Parameter Reference](docs/PARAMETERS.md)** — Complete configuration options for animation, interaction, styling, and more
@@ -169,6 +169,8 @@ Check out the `examples/` directory for various usage patterns:
 - `cdn-umd-example.html` - Traditional script tag / CDN usage
 - `auto-init-example.html` - HTML data attribute initialization
 - `static-loader-example.html` - Static image URLs
+- `static-urls-shorthand-example.html` - Simplest static loader: direct URL array shorthand
+- `static-json-source-example.html` - Load images from a JSON endpoint
 - `google-drive-loader-example.html` - Google Drive folder source
 - `layout-algorithms.html` - Compare all layout algorithms
 - `entry-animations.html` - Entry animation styles

package/dist/image-cloud-auto-init.js

@@ -95,7 +95,9 @@ const kt = ".fbn-ic-gallery{--fbn-ic-bg-primary: #05060F;--fbn-ic-bg-secondary:
     }),
     static: Object.freeze({
       sources: [],
-      // Must be provided by user
+      // Must be provided by user (or use urls shorthand)
+      urls: void 0,
+      // Shorthand for sources: [{ type: 'urls', urls: [...] }]
       validateUrls: !0,
       validationTimeout: 5e3,
       validationMethod: "head",
@@ -299,7 +301,7 @@ function Bt(o) {
       }
     };
 }
-function Vt(o = {}) {
+function Jt(o = {}) {
   var s;
   const t = Xt(o), e = Bt(o);
   let i = o.image;
@@ -333,6 +335,7 @@ function Vt(o = {}) {
     ...y.loader.static,
     ...o.loader.static,
     sources: o.loader.static.sources || y.loader.static.sources,
+    urls: o.loader.static.urls || void 0,
     allowedExtensions: o.loader.static.allowedExtensions || y.loader.static.allowedExtensions
   })), o.layout && (n.layout = {
     ...y.layout,
@@ -396,7 +399,7 @@ function Vt(o = {}) {
     ...o.rendering.performance
   })), o.debug !== void 0 && (n.debug = o.debug), n;
 }
-function Jt(o, t) {
+function Vt(o, t) {
   return { ...o ? zt[o] : zt.playful, ...t };
 }
 function Kt(o, t) {
@@ -675,7 +678,7 @@ function re(o) {
     let A;
     switch (p) {
       case "bounce": {
-        const _ = Jt(
+        const _ = Vt(
           n.bouncePreset,
           n.bounce
         );
@@ -1244,24 +1247,24 @@ class fe {
     for (let F = 0; F < t; F++) {
       let $, N, G = 0;
       if (M && F >= z) {
-        const J = F - z, V = J % z;
-        G = Math.floor(J / z) + 1, _[V]++, a.fillDirection === "row" ? ($ = V % g, N = Math.floor(V / g)) : (N = V % f, $ = Math.floor(V / f));
+        const V = F - z, J = V % z;
+        G = Math.floor(V / z) + 1, _[J]++, a.fillDirection === "row" ? ($ = J % g, N = Math.floor(J / g)) : (N = J % f, $ = Math.floor(J / f));
       } else
         a.fillDirection === "row" ? ($ = F % g, N = Math.floor(F / g)) : (N = F % f, $ = Math.floor(F / f));
       let H = A + $ * (x + a.gap) + x / 2, it = O + N * (L + a.gap) + L / 2;
       if (a.stagger === "row" && N % 2 === 1 ? H += x / 2 : a.stagger === "column" && $ % 2 === 1 && (it += L / 2), G > 0) {
-        const J = (G - 1) % Lt.length, V = Lt[J];
-        H += V.x * K, it += V.y * K;
+        const V = (G - 1) % Lt.length, J = Lt[V];
+        H += J.x * K, it += J.y * K;
       }
       if (a.jitter > 0) {
-        const J = x / 2 * a.jitter, V = L / 2 * a.jitter;
-        H += this.random(-J, J), it += this.random(-V, V);
+        const V = x / 2 * a.jitter, J = L / 2 * a.jitter;
+        H += this.random(-V, V), it += this.random(-J, J);
       }
       let nt = H, ot = it;
       if (!M && a.fillDirection === "row") {
-        const J = t % g || g;
-        if (N === Math.floor((t - 1) / g) && J < g) {
-          const Mt = J * x + (J - 1) * a.gap;
+        const V = t % g || g;
+        if (N === Math.floor((t - 1) / g) && V < g) {
+          const Mt = V * x + (V - 1) * a.gap;
           let St = 0;
           a.alignment === "center" ? St = (C - Mt) / 2 : a.alignment === "end" && (St = C - Mt), nt += St;
         }
@@ -1270,8 +1273,8 @@ class fe {
       nt = Math.max(yt, Math.min(nt, vt)), ot = Math.max(Ht, Math.min(ot, _t));
       let wt = 0;
       if (u === "random") {
-        const J = ((q = (tt = this.imageConfig.rotation) == null ? void 0 : tt.range) == null ? void 0 : q.min) ?? -15, V = ((Y = (et = this.imageConfig.rotation) == null ? void 0 : et.range) == null ? void 0 : Y.max) ?? 15;
-        a.jitter > 0 ? wt = this.random(J * a.jitter, V * a.jitter) : wt = this.random(J, V);
+        const V = ((q = (tt = this.imageConfig.rotation) == null ? void 0 : tt.range) == null ? void 0 : q.min) ?? -15, J = ((Y = (et = this.imageConfig.rotation) == null ? void 0 : et.range) == null ? void 0 : Y.max) ?? 15;
+        a.jitter > 0 ? wt = this.random(V * a.jitter, J * a.jitter) : wt = this.random(V, J);
       }
       let xt;
       M && G > 0 ? xt = 50 - G : xt = M ? 100 + F : F + 1, n.push({
@@ -2575,8 +2578,8 @@ class Le {
 }
 class Oe {
   constructor(t = {}) {
-    if (this._prepared = !1, this._discoveredUrls = [], this.validateUrls = t.validateUrls !== !1, this.validationTimeout = t.validationTimeout ?? 5e3, this.validationMethod = t.validationMethod ?? "head", this.sources = t.sources ?? [], this.debugLogging = t.debugLogging ?? !1, !this.sources || this.sources.length === 0)
-      throw new Error("StaticImageLoader requires at least one source to be configured");
+    if (this._prepared = !1, this._discoveredUrls = [], this.validateUrls = t.validateUrls !== !1, this.validationTimeout = t.validationTimeout ?? 5e3, this.validationMethod = t.validationMethod ?? "head", this.debugLogging = t.debugLogging ?? !1, t.urls && Array.isArray(t.urls) && t.urls.length > 0 ? this.sources = [{ type: "urls", urls: t.urls }, ...t.sources ?? []] : this.sources = t.sources ?? [], !this.sources || this.sources.length === 0)
+      throw new Error("StaticImageLoader requires at least one source (or urls shorthand) to be configured");
     this.log("StaticImageLoader initialized with config:", t);
   }
   /**
@@ -2625,7 +2628,7 @@ class Oe {
    * @returns Promise resolving to array of valid URLs from this source
    */
   async processSource(t, e) {
-    return !t || !t.type ? (console.warn("Invalid source object (missing type):", t), []) : t.type === "urls" ? await this.processUrls(t.urls || [], e) : t.type === "path" ? await this.processPath(t.basePath, t.files || [], e) : (console.warn(`Unknown source type: ${t.type}`), []);
+    return !t || !t.type ? (console.warn("Invalid source object (missing type):", t), []) : t.type === "urls" ? await this.processUrls(t.urls || [], e) : t.type === "path" ? await this.processPath(t.basePath, t.files || [], e) : t.type === "json" ? await this.processJson(t.url, e) : (console.warn(`Unknown source type: ${t.type}`), []);
   }
   /**
    * Process a list of direct URLs
@@ -2670,6 +2673,30 @@ class Oe {
     }
     return n;
   }
+  /**
+   * Process a JSON endpoint source
+   * Fetches a JSON endpoint that returns { images: string[] }
+   * @param url - JSON endpoint URL
+   * @param filter - Filter to apply to discovered images
+   * @returns Promise resolving to array of validated URLs
+   */
+  async processJson(t, e) {
+    if (!t)
+      return console.warn("url is required for json-type sources"), [];
+    this.log(`Fetching JSON endpoint: ${t}`);
+    const i = new AbortController(), n = setTimeout(() => i.abort(), 1e4);
+    try {
+      const s = await fetch(t, { signal: i.signal });
+      if (clearTimeout(n), !s.ok)
+        throw new Error(`HTTP ${s.status} fetching ${t}`);
+      const r = await s.json();
+      if (!r || !Array.isArray(r.images))
+        throw new Error('JSON source must return JSON with shape { "images": ["url1", "url2", ...] }');
+      return this.log(`JSON endpoint returned ${r.images.length} image(s)`), await this.processUrls(r.images, e);
+    } catch (s) {
+      throw clearTimeout(n), s instanceof Error && s.name === "AbortError" ? new Error(`Timeout fetching JSON endpoint: ${t}`) : s;
+    }
+  }
   /**
    * Validate a single URL using HEAD request
    * @param url - URL to validate
@@ -2879,7 +2906,7 @@ function Ue() {
 class He {
   constructor(t = {}) {
     var i, n, s, r, a, h;
-    this.fullConfig = Vt(t), t.container instanceof HTMLElement ? (this.containerRef = t.container, this.containerId = null) : (this.containerRef = null, this.containerId = t.container || "imageCloud"), this.imagesLoaded = !1, this.imageElements = [], this.imageLayouts = [], this.currentImageHeight = 225, this.currentFocusIndex = null, this.hoveredImage = null, this.resizeTimeout = null, this.displayQueue = [], this.queueInterval = null, this.loadGeneration = 0, this.animationEngine = new Qt(this.fullConfig.animation), this.layoutEngine = new xe({
+    this.fullConfig = Jt(t), t.container instanceof HTMLElement ? (this.containerRef = t.container, this.containerId = null) : (this.containerRef = null, this.containerId = t.container || "imageCloud"), this.imagesLoaded = !1, this.imageElements = [], this.imageLayouts = [], this.currentImageHeight = 225, this.currentFocusIndex = null, this.hoveredImage = null, this.resizeTimeout = null, this.displayQueue = [], this.queueInterval = null, this.loadGeneration = 0, this.animationEngine = new Qt(this.fullConfig.animation), this.layoutEngine = new xe({
       layout: this.fullConfig.layout,
       image: this.fullConfig.image
     }), this.zoomEngine = new Te(this.fullConfig.interaction.focus, this.animationEngine, this.fullConfig.styling), this.defaultStyles = ft((i = this.fullConfig.styling) == null ? void 0 : i.default), this.hoverStyles = ft((n = this.fullConfig.styling) == null ? void 0 : n.hover), this.defaultClassName = (r = (s = this.fullConfig.styling) == null ? void 0 : s.default) == null ? void 0 : r.className, this.hoverClassName = (h = (a = this.fullConfig.styling) == null ? void 0 : a.hover) == null ? void 0 : h.className;