@frybynite/image-cloud 0.9.6 → 0.10.1

package/README.md

@@ -10,9 +10,9 @@ A TypeScript library for creating interactive image clouds with animated scatter
 ## Features
 
 - ✨ Animated image layouts with smooth transitions
-- 🎯 Multiple layout algorithms (radial, grid, spiral, cluster, wave, random)
+- 🎯 Multiple layout algorithms (radial, grid, spiral, cluster, wave, honeycomb, random)
 - 🎬 Rich entry animations (bounce, elastic, wave paths; spin, wobble rotations)
-- 🔍 Zoom/focus interactions with keyboard navigation
+- 🔍 Zoom/focus interactions with keyboard, swipe, and mouse wheel navigation
 - 🎨 State-based image styling (borders, shadows, filters for default/hover/focused)
 - 📱 Responsive design with adaptive sizing
 - 🖼️ Multiple image sources (static URLs, JSON endpoints, Google Drive, composite loaders)
@@ -53,30 +53,29 @@ Replace `@latest` with a specific version (e.g., `@0.5.1`) to pin to that releas
 ### TypeScript/JavaScript (Programmatic API)
 
 ```typescript
-import { ImageCloud } from '@frybynite/image-cloud';
+import { imageCloud } from '@frybynite/image-cloud';
 import '@frybynite/image-cloud/style.css';
 
-const cloud = new ImageCloud({
+// Single-expression initialization — imageCloud() constructs and calls init() for you
+const cloud = await imageCloud({
   container: 'myCloud',
-  loaders: [{
-    static: {
-      sources: [{
-        urls: [
-          'https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg?auto=compress&w=600',
-          'https://images.pexels.com/photos/3225517/pexels-photo-3225517.jpeg?auto=compress&w=600',
-          'https://images.pexels.com/photos/1402787/pexels-photo-1402787.jpeg?auto=compress&w=600'
-        ]
-      }]
-    }
-  }],
+  images: [
+    'https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg?auto=compress&w=600',
+    'https://images.pexels.com/photos/3225517/pexels-photo-3225517.jpeg?auto=compress&w=600',
+    'https://images.pexels.com/photos/1402787/pexels-photo-1402787.jpeg?auto=compress&w=600'
+  ],
   layout: {
     algorithm: 'radial'
   }
 });
-
-await cloud.init();
 ```
 
+> For advanced lifecycle control (e.g. deferred init, re-use), the `ImageCloud` class is also exported and still works as before:
+> ```typescript
+> const cloud = new ImageCloud({ container: 'myCloud', images: [...] });
+> await cloud.init();
+> ```
+
 ### HTML (Auto-initialization)
 
 ```html
@@ -107,13 +106,13 @@ await cloud.init();
 
 ## Getting Started
 
-For detailed configuration, see the documentation in the `docs/` folder:
+Full documentation is available at **[frybynite.github.io/image-cloud](https://frybynite.github.io/image-cloud/)**
 
-1. **[Loaders](docs/LOADERS.md)** — Configure image sources (static URLs, JSON endpoints, local paths, Google Drive folders)
-2. **[Layouts](docs/LAYOUTS.md)** — Choose and customize layout algorithms (radial, grid, spiral, cluster, random, wave)
-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
-5. **[API Reference](docs/api/README.md)** — TypeScript API documentation for the ImageCloud class, types, loaders, and layouts
+- **[Loaders](https://frybynite.github.io/image-cloud/loaders/)** — Configure image sources (static URLs, JSON endpoints, Google Drive)
+- **[Layouts](https://frybynite.github.io/image-cloud/layouts/)** — Layout algorithms (radial, grid, spiral, cluster, wave, honeycomb, random)
+- **[Image Sizing](https://frybynite.github.io/image-cloud/image_sizing/)** — Base sizes, variance, and responsive/adaptive behavior
+- **[Parameters](https://frybynite.github.io/image-cloud/parameters/)** — Complete configuration reference
+- **[API Reference](https://frybynite.github.io/image-cloud/api/)** — TypeScript API documentation
 
 ### Using the Configurator
 
@@ -139,6 +138,10 @@ The Configurator lets you visually adjust all settings and exports a ready-to-us
 - **Enter / Space**: Focus hovered image
 - **Escape**: Unfocus current image
 
+### Touch
+
+- **Swipe left / right**: Navigate between focused images
+
 ### Window
 
 - **Resize**: Responsive layout adjustment (debounced)
@@ -152,29 +155,31 @@ The Configurator lets you visually adjust all settings and exports a ready-to-us
 
 ## Examples
 
-Check out the `examples/` directory for various usage patterns:
-- `esm-example.html` - Modern ES module usage
-- `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
-- `image-style-demo.html` - Borders, shadows, and filters
-- `typescript-example.ts` - TypeScript with React and Vue
-- See `examples/README.md` for detailed instructions
+Live examples are published at [frybynite.github.io/image-cloud/examples/](https://frybynite.github.io/image-cloud/examples/):
+
+- [Static URLs Shorthand](https://frybynite.github.io/image-cloud/examples/static-urls-shorthand-example.html) - Simplest setup: direct URL array
+- [Static Loader](https://frybynite.github.io/image-cloud/examples/static-loader-example.html) - Static image URLs
+- [Static JSON Source](https://frybynite.github.io/image-cloud/examples/static-json-source-example.html) - Load images from a JSON endpoint
+- [Google Drive](https://frybynite.github.io/image-cloud/examples/google-drive-loader-example.html) - Google Drive folder source
+- [Auto-Init](https://frybynite.github.io/image-cloud/examples/auto-init-example.html) - Zero-JS setup using data attributes
+- [ESM Module](https://frybynite.github.io/image-cloud/examples/esm-example.html) - ES module usage
+- [CDN/UMD](https://frybynite.github.io/image-cloud/examples/cdn-umd-example.html) - CDN script tag usage
+- [Iframe Embed](https://frybynite.github.io/image-cloud/examples/iframe-example.html) - Embedded in an iframe
+- [Layout Algorithms](https://frybynite.github.io/image-cloud/examples/layout-algorithms.html) - Compare all layout algorithms
+- [Entry Animations](https://frybynite.github.io/image-cloud/examples/entry-animations.html) - Entry animation styles
+- [Keyboard Navigation](https://frybynite.github.io/image-cloud/examples/keyboard-navigation-demo.html) - Per-container keyboard navigation
+- [Image Style Demo](https://frybynite.github.io/image-cloud/examples/image-style-demo.html) - Borders, shadows, and filters
+- [Detailed Styling](https://frybynite.github.io/image-cloud/examples/styling/index.html) - In-depth styling examples
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for a full list of changes across all versions.
+See [Changelog](https://frybynite.github.io/image-cloud/changelog/) for a full list of changes across all versions.
 
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-See [docs/DEVELOPER.md](docs/DEVELOPER.md) for build scripts, testing, and project structure.
+See the [Developer Guide](https://frybynite.github.io/image-cloud/developer/) for build scripts, testing, and project structure.
 
 ## License
 

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

@@ -24,7 +24,7 @@ const Ut = ".fbn-ic-gallery{--fbn-ic-bg-primary: #05060F;--fbn-ic-bg-secondary:
   mode: "none"
 }), xt = Object.freeze({
   mode: "none"
-}), Ft = Object.freeze({
+}), Mt = Object.freeze({
   default: Object.freeze({
     border: Object.freeze({
       width: 0,
@@ -82,7 +82,7 @@ const Ut = ".fbn-ic-gallery{--fbn-ic-bg-primary: #05060F;--fbn-ic-bg-secondary:
     min: -15,
     max: 15
   })
-}), Mt = Object.freeze({
+}), Ft = Object.freeze({
   sizing: jt,
   rotation: Wt
 }), zt = Object.freeze({
@@ -103,7 +103,7 @@ const Ut = ".fbn-ic-gallery{--fbn-ic-bg-primary: #05060F;--fbn-ic-bg-secondary:
     debug: Ot
   }),
   // Image sizing and rotation configuration
-  image: Mt,
+  image: Ft,
   // Pattern-based layout configuration
   layout: Object.freeze({
     algorithm: "radial",
@@ -186,7 +186,7 @@ const Ut = ".fbn-ic-gallery{--fbn-ic-bg-primary: #05060F;--fbn-ic-bg-secondary:
     showFocusOutline: !1
   }),
   // Image styling
-  styling: Ft
+  styling: Mt
 });
 function Z(o, t) {
   if (!o) return t || {};
@@ -274,12 +274,12 @@ function Qt(o = {}) {
   }, s = {
     loaders: n,
     config: r,
-    image: Vt(Mt, e),
+    image: Vt(Ft, e),
     layout: { ...C.layout },
     animation: { ...C.animation },
     interaction: { ...C.interaction },
     ui: { ...C.ui },
-    styling: Jt(Ft, o.styling)
+    styling: Jt(Mt, o.styling)
   };
   o.layout && (s.layout = {
     ...C.layout,
@@ -653,10 +653,10 @@ function de(o) {
         };
     }
     const W = D.x - e.x, U = D.y - e.y;
-    let F;
-    m ? F = le(A, c, y) : f ? F = V(d, c, A) : F = c;
+    let M;
+    m ? M = le(A, c, y) : f ? M = V(d, c, A) : M = c;
     let R;
-    S ? R = he(A, l, w) : v ? R = V(b, l, A) : R = l, t.style.transform = `translate(${L}px, ${_}px) translate(${W}px, ${U}px) rotate(${F}deg) scale(${R})`, A < 1 ? requestAnimationFrame(O) : (t.style.transform = `translate(${L}px, ${_}px) rotate(${c}deg) scale(${l})`, u && u());
+    S ? R = he(A, l, w) : v ? R = V(b, l, A) : R = l, t.style.transform = `translate(${L}px, ${_}px) translate(${W}px, ${U}px) rotate(${M}deg) scale(${R})`, A < 1 ? requestAnimationFrame(O) : (t.style.transform = `translate(${L}px, ${_}px) rotate(${c}deg) scale(${l})`, u && u());
   }
   requestAnimationFrame(O);
 }
@@ -1279,16 +1279,16 @@ class be {
         continue;
       }
       const W = 2 * Math.PI / D, U = I * (20 * Math.PI / 180);
-      for (let F = 0; F < D && w < t; F++) {
-        const R = F * W + U, k = g ? this.random(h, d) : 1, q = L * k, T = f * q;
-        let $ = m + Math.cos(R) * H, M = y + Math.sin(R) * O;
+      for (let M = 0; M < D && w < t; M++) {
+        const R = M * W + U, k = g ? this.random(h, d) : 1, q = L * k, T = f * q;
+        let $ = m + Math.cos(R) * H, F = y + Math.sin(R) * O;
         const P = T * 1.5 / 2, B = T / 2;
-        $ - P < v ? $ = v + P : $ + P > a - v && ($ = a - v - P), M - B < v ? M = v + B : M + B > r - v && (M = r - v - B);
+        $ - P < v ? $ = v + P : $ + P > a - v && ($ = a - v - P), F - B < v ? F = v + B : F + B > r - v && (F = r - v - B);
         const Y = c === "random" ? this.random(l, u) : 0;
         n.push({
           id: w,
           x: $,
-          y: M,
+          y: F,
           rotation: Y,
           scale: q,
           baseSize: T,
@@ -1365,27 +1365,27 @@ class ve {
       p,
       l,
       s
-    ), y = s.stagger === "row", x = s.stagger === "column", v = y ? f + 0.5 : f, S = x ? m + 0.5 : m, w = (b - s.gap * (f - 1)) / v, I = (p - s.gap * (m - 1)) / S, z = y ? w / 2 : 0, L = x ? I / 2 : 0, _ = 1 + s.overlap, O = Math.min(w, I) * _, H = e.fixedHeight ? Math.min(e.fixedHeight, O) : O, N = f * w + (f - 1) * s.gap + z, A = m * I + (m - 1) * s.gap + L, D = c + (b - N) / 2, W = c + (p - A) / 2, U = f * m, F = s.columns !== "auto" && s.rows !== "auto", R = F && t > U;
+    ), y = s.stagger === "row", x = s.stagger === "column", v = y ? f + 0.5 : f, S = x ? m + 0.5 : m, w = (b - s.gap * (f - 1)) / v, I = (p - s.gap * (m - 1)) / S, z = y ? w / 2 : 0, L = x ? I / 2 : 0, _ = 1 + s.overlap, O = Math.min(w, I) * _, H = e.fixedHeight ? Math.min(e.fixedHeight, O) : O, N = f * w + (f - 1) * s.gap + z, A = m * I + (m - 1) * s.gap + L, D = c + (b - N) / 2, W = c + (p - A) / 2, U = f * m, M = s.columns !== "auto" && s.rows !== "auto", R = M && t > U;
     typeof window < "u" && (window.__gridOverflowDebug = {
       gridConfigColumns: s.columns,
       gridConfigRows: s.rows,
       columns: f,
       rows: m,
       cellCount: U,
-      hasFixedGrid: F,
+      hasFixedGrid: M,
       imageCount: t,
       isOverflowMode: R
     });
     const k = R ? new Array(U).fill(0) : [], q = Math.min(w, I) * s.overflowOffset;
     for (let T = 0; T < t; T++) {
-      let $, M, X = 0;
+      let $, F, X = 0;
       if (R && T >= U) {
         const G = T - U, j = G % U;
-        X = Math.floor(G / U) + 1, k[j]++, s.fillDirection === "row" ? ($ = j % f, M = Math.floor(j / f)) : (M = j % m, $ = Math.floor(j / m));
+        X = Math.floor(G / U) + 1, k[j]++, s.fillDirection === "row" ? ($ = j % f, F = Math.floor(j / f)) : (F = j % m, $ = Math.floor(j / m));
       } else
-        s.fillDirection === "row" ? ($ = T % f, M = Math.floor(T / f)) : (M = T % m, $ = Math.floor(T / m));
-      let P = D + $ * (w + s.gap) + w / 2, B = W + M * (I + s.gap) + I / 2;
-      if (s.stagger === "row" && M % 2 === 1 ? P += w / 2 : s.stagger === "column" && $ % 2 === 1 && (B += I / 2), X > 0) {
+        s.fillDirection === "row" ? ($ = T % f, F = Math.floor(T / f)) : (F = T % m, $ = Math.floor(T / m));
+      let P = D + $ * (w + s.gap) + w / 2, B = W + F * (I + s.gap) + I / 2;
+      if (s.stagger === "row" && F % 2 === 1 ? P += w / 2 : s.stagger === "column" && $ % 2 === 1 && (B += I / 2), X > 0) {
         const G = (X - 1) % Rt.length, j = Rt[G];
         P += j.x * q, B += j.y * q;
       }
@@ -1396,7 +1396,7 @@ class ve {
       let Y = P, J = B;
       if (!R && s.fillDirection === "row") {
         const G = t % f || f;
-        if (M === Math.floor((t - 1) / f) && G < f) {
+        if (F === Math.floor((t - 1) / f) && G < f) {
           const St = G * w + (G - 1) * s.gap;
           let gt = 0;
           s.alignment === "center" ? gt = (N - St) / 2 : s.alignment === "end" && (gt = N - St), Y += gt;
@@ -1481,18 +1481,18 @@ class Ee {
         const P = S * 0.3 * s.tightness;
         w = P * v + s.startAngle, I = this.calculateLogarithmicRadius(P, t, x, s.tightness);
       }
-      const z = m + Math.cos(w) * I, L = y + Math.sin(w) * I, _ = I / x, O = f > 0 ? 1 - _ * f * 0.5 : 1, H = p ? this.random(g, b) : 1, N = O * H, A = l * N, W = A * 1.5 / 2, U = A / 2, F = c + W, R = a - c - W, k = c + U, q = r - c - U, T = Math.max(F, Math.min(z, R)), $ = Math.max(k, Math.min(L, q));
-      let M = 0;
+      const z = m + Math.cos(w) * I, L = y + Math.sin(w) * I, _ = I / x, O = f > 0 ? 1 - _ * f * 0.5 : 1, H = p ? this.random(g, b) : 1, N = O * H, A = l * N, W = A * 1.5 / 2, U = A / 2, M = c + W, R = a - c - W, k = c + U, q = r - c - U, T = Math.max(M, Math.min(z, R)), $ = Math.max(k, Math.min(L, q));
+      let F = 0;
       if (u === "random") {
         const P = w * 180 / Math.PI % 360, B = this.random(h, d);
-        M = s.spiralType === "golden" ? B : P * 0.1 + B * 0.9;
-      } else u === "tangent" && (M = this.calculateSpiralTangent(w, I, s));
+        F = s.spiralType === "golden" ? B : P * 0.1 + B * 0.9;
+      } else u === "tangent" && (F = this.calculateSpiralTangent(w, I, s));
       const X = t - S;
       n.push({
         id: S,
         x: T,
         y: $,
-        rotation: M,
+        rotation: F,
         scale: N,
         baseSize: A,
         zIndex: X
@@ -1591,15 +1591,15 @@ class Ie {
         if (s.distribution === "gaussian")
           z = this.gaussianRandom() * S.spread, L = this.gaussianRandom() * S.spread;
         else {
-          const M = this.random(0, Math.PI * 2), X = this.random(0, S.spread);
-          z = Math.cos(M) * X, L = Math.sin(M) * X;
+          const F = this.random(0, Math.PI * 2), X = this.random(0, S.spread);
+          z = Math.cos(F) * X, L = Math.sin(F) * X;
         }
         const _ = 1 + s.overlap * 0.5, O = 1 + s.overlap * 0.3;
         z /= _, L /= _;
         const H = p ? this.random(g, b) : 1, N = O * H, A = l * N;
         let D = S.x + z, W = S.y + L;
-        const F = A * 1.5 / 2, R = A / 2;
-        D = Math.max(c + F, Math.min(D, a - c - F)), W = Math.max(c + R, Math.min(W, r - c - R));
+        const M = A * 1.5 / 2, R = A / 2;
+        D = Math.max(c + M, Math.min(D, a - c - M)), W = Math.max(c + R, Math.min(W, r - c - R));
         const k = u === "random" ? this.random(h, d) : 0, T = Math.sqrt(z * z + L * L) / S.spread, $ = Math.round((1 - T) * 50) + 1;
         n.push({
           id: x,
@@ -1690,25 +1690,25 @@ class Ce {
       ...Nt,
       ...this.config.wave
     }, { rows: m, amplitude: y, frequency: x, phaseShift: v, synchronization: S } = f, w = Math.ceil(t / m), L = p * 1.5 / 2, _ = c + L, O = a - c - L, H = O - _, N = w > 1 ? H / (w - 1) : 0, A = c + y + p / 2, D = r - c - y - p / 2, W = D - A, U = m > 1 ? W / (m - 1) : 0;
-    let F = 0;
-    for (let R = 0; R < m && F < t; R++) {
+    let M = 0;
+    for (let R = 0; R < m && M < t; R++) {
       const k = m === 1 ? (A + D) / 2 : A + R * U;
       let q = 0;
       S === "offset" ? q = R * v : S === "alternating" && (q = R * Math.PI);
-      for (let T = 0; T < w && F < t; T++) {
-        const $ = w === 1 ? (_ + O) / 2 : _ + T * N, M = this.calculateWaveY($, a, y, x, q), X = $, P = k + M, B = b ? this.random(d, g) : 1, Y = p * B;
+      for (let T = 0; T < w && M < t; T++) {
+        const $ = w === 1 ? (_ + O) / 2 : _ + T * N, F = this.calculateWaveY($, a, y, x, q), X = $, P = k + F, B = b ? this.random(d, g) : 1, Y = p * B;
         let J = 0;
         l === "tangent" ? J = this.calculateRotation($, a, y, x, q) : l === "random" && (J = this.random(u, h));
         const K = Y * 1.5 / 2, lt = Y / 2, nt = c + K, ot = a - c - K, ht = c + lt, dt = r - c - lt;
         n.push({
-          id: F,
+          id: M,
           x: Math.max(nt, Math.min(X, ot)),
           y: Math.max(ht, Math.min(P, dt)),
           rotation: J,
           scale: B,
           baseSize: Y,
-          zIndex: F + 1
-        }), F++;
+          zIndex: M + 1
+        }), M++;
       }
     }
     return n;
@@ -1778,7 +1778,7 @@ function Le(o, t, i, e, n, a) {
     py: n + a * (t + o / 2)
   };
 }
-const Fe = [
+const Me = [
   [1, 0, -1],
   [0, 1, -1],
   [-1, 1, 0],
@@ -1786,11 +1786,11 @@ const Fe = [
   [0, -1, 1],
   [1, -1, 0]
 ];
-function Me(o) {
+function Fe(o) {
   if (o === 0) return [[0, 0, 0]];
   const t = [];
   let [i, e, n] = [0, -o, o];
-  for (const [a, r, s] of Fe)
+  for (const [a, r, s] of Me)
     for (let c = 0; c < o; c++)
       t.push([i, e, n]), i += a, e += r, n += s;
   return t;
@@ -1808,7 +1808,7 @@ class ze {
     }.spacing ?? 0, d = l + h;
     let g = 0, b = 0;
     for (; g < t; ) {
-      const p = Me(b);
+      const p = Fe(b);
       for (const [f, m, y] of p) {
         if (g >= t) break;
         const { px: x, py: v } = Le(f, m, y, s, c, d);
@@ -3292,7 +3292,7 @@ class ti {
   createLoader() {
     const t = this.fullConfig.loaders, i = this.fullConfig.config.loaders ?? {};
     if (!t || t.length === 0)
-      throw new Error("No loaders configured. Provide `images`, `loaders`, or both.");
+      throw new Error("No loaders configured. Provide `images`, `loaders`, or both.\n  Example: imageCloud({ container: 'id', images: ['https://...'] })");
     const e = t.map((n) => this.createLoaderFromEntry(n, i));
     return e.length === 1 ? e[0] : new Ve({
       loaders: e,
@@ -3331,7 +3331,7 @@ class ti {
       if (Qe(), this.containerRef)
         this.containerEl = this.containerRef;
       else if (this.containerEl = document.getElementById(this.containerId), !this.containerEl)
-        throw new Error(`Container #${this.containerId} not found`);
+        throw new Error(`Container "#${this.containerId}" not found. Ensure an element with id="${this.containerId}" exists in the DOM before calling imageCloud().`);
       this.containerEl.classList.add("fbn-ic-gallery"), this.containerEl.setAttribute("tabindex", "0"), this.fullConfig.interaction.navigation?.swipe !== !1 && (this.swipeEngine = new bt(this.containerEl, {
         onNext: () => this.navigateToNextImage(),
         onPrev: () => this.navigateToPreviousImage(),
@@ -3341,7 +3341,7 @@ class ti {
         }
       })), this.setupUI(), this.setupEventListeners(), this.logDebug("ImageCloud initialized"), await this.loadImages();
     } catch (t) {
-      console.error("Gallery initialization failed:", t), this.errorEl && t instanceof Error && this.showError("Gallery failed to initialize: " + t.message);
+      console.error(`ImageCloud initialization failed (container: "${this.containerId ?? "element"}"):`, t), this.errorEl && t instanceof Error && this.showError("Gallery failed to initialize: " + t.message);
     }
   }
   setupUI() {
@@ -3695,7 +3695,8 @@ function ii() {
           return;
         }
       else {
-        console.error(`ImageCloud: Missing configuration for #${e.id}. Add data-config='{...}' attribute.`);
+        console.error(`ImageCloud: Missing configuration for #${e.id}. Add data-config='{...}' attribute.
+  Example: data-config='{"images":["https://..."]}'`);
         return;
       }
       new ti(a).init().catch((s) => {