spinit-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BillGR17
+
+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,69 @@
+# SpinIt.js
+
+A lightweight, high-performance JavaScript library for 360-degree image rotation. Perfect for product displays and interactive image viewers.
+
+## Features
+
+- **No Dependencies**: No external libraries required.
+- **Lightweight**: Minimal overhead and fast loading.
+- **Responsive**: Adapts to various screen sizes.
+- **Interactive**: Support for mouse and touch interactions.
+- **Configurable**: Easy to customize sensitivity, responsiveness, and more.
+- **Preload**: Number of initial images to load before making the viewer interactive. Other images fetch in the background.
+
+
+## Installation
+
+### Via npm
+
+```bash
+npm install spinit-js
+```
+
+
+## Quick Start
+
+1. **Prepare your container**:
+
+```html
+<div id="spinit-container" style="width: 100%; height: 500px;"></div>
+```
+
+2. **Initialize SpinIt**:
+
+```javascript
+import { SpinIT } from 'spinit-js';
+
+// container, [urlTemplate, startFrame, endFrame], options
+const spinit = new SpinIT("#spinit-container", ["img_##.jpg", 1, 90], {
+    loop: true,
+    inertia: true,
+    friction: 0.95,
+    sensitivity: 1.0,
+    velocityScale: 1.0,
+    responsive: true,
+    preload: "all",
+    autoplay: true,
+    autoplaySpeed: 24
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `loop` | `Boolean` | `true` | Whether the animation should loop when reaching the first or last frame. |
+| `inertia` | `Boolean` | `true` | Enables smooth deceleration after the user stops dragging. |
+| `friction` | `Number` | `0.95` | Controls how quickly the inertia slows down. (0 to 1) |
+| `sensitivity` | `Number` | `1.0` | Adjusts rotation speed. Lower values increase sensitivity (faster rotation). |
+| `velocityScale` | `Number` | `1.0` | Multiplier for the initial inertia velocity. |
+| `responsive` | `Boolean` | `true` | Automatically resizes the canvas to match its container. |
+| `preload` | `Number` \| `"all"` | `"all"` | Number of initial images to load before making the viewer interactive. Other images fetch in the background. |
+| `autoplay` | `Boolean` \| `Number` | `true` | If true, spins automatically until user interaction. If a number, auto-spins until that frame index. |
+| `autoplaySpeed` | `Number` | `24` | Autoplay speed in Frames Per Second (FPS). |
+| `debug` | `Boolean` | `false` | Enables debug mode. |
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "spinit-js",
+  "version": "1.0.0",
+  "description": "git init",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "node test/server.js"
+  },
+  "keywords": [
+    "spritespin",
+    "360",
+    "rotation",
+    "image",
+    "viewer"
+  ],
+  "author": "BillGR17",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BillGR17/SpinIt.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BillGR17/SpinIt/issues"
+  },
+  "homepage": "https://github.com/BillGR17/SpinIt#readme",
+  "files": [
+    "src"
+  ]
+}

package/src/EventManager.js

@@ -0,0 +1,40 @@
+/**
+ * EventManager module for SpinIT.
+ * Handles user interactions via pointer events.
+ */
+export class EventManager {
+  /**
+   * Sets up pointer events for an element.
+   * @param {HTMLElement} element - The target element.
+   * @param {Object} callbacks - Object containing callback functions.
+   * @param {Function} callbacks.onStart - Called on pointer down.
+   * @param {Function} callbacks.onMove - Called on pointer move.
+   * @param {Function} callbacks.onEnd - Called on pointer up/cancel.
+   */
+  static setupEvents(element, { onStart, onMove, onEnd }) {
+    element.style.touchAction = "none";
+
+    element.addEventListener("pointerdown", (e) => {
+      onStart(e);
+      element.setPointerCapture(e.pointerId);
+    });
+
+    element.addEventListener("pointermove", (e) => {
+      onMove(e);
+    });
+
+    const stopDrag = (e) => {
+      onEnd(e);
+      try {
+        if (element.hasPointerCapture(e.pointerId)) {
+          element.releasePointerCapture(e.pointerId);
+        }
+      } catch (error) {
+        // Suppress browser quirks where hasPointerCapture is true but pointer is already invalidated
+      }
+    };
+
+    element.addEventListener("pointerup", stopDrag);
+    element.addEventListener("pointercancel", stopDrag);
+  }
+}

package/src/Loader.js

@@ -0,0 +1,55 @@
+/**
+ * Loader module for SpinIT.
+ * Handles image URL generation and preloading images.
+ */
+export class Loader {
+  /**
+   * Generates an array of image URLs from a template.
+   * @param {string} template - The URL template (e.g., "img_##.jpg").
+   * @param {number} start - Start index.
+   * @param {number} end - End index.
+   * @param {boolean} [debug=false] - Whether to log warnings/errors.
+   * @returns {string[]}
+   */
+  static generateUrls(template, start, end, debug = false) {
+    const urls = [];
+    const match = template.match(/(#+)/);
+
+    if (!match) {
+      if (debug) console.error("SpinIT Loader Error: No '#' pattern found in the URL template.");
+      return urls;
+    }
+
+    const placeholder = match[0];
+    const paddingLength = placeholder.length;
+
+    for (let i = start; i <= end; i++) {
+      const numberStr = String(i).padStart(paddingLength, "0");
+      urls.push(template.replace(placeholder, numberStr));
+    }
+
+    return urls;
+  }
+
+  /**
+   * Preloads a list of images.
+   * @param {string[]} urls - The URLs to preload.
+   * @param {boolean} [debug=false] - Whether to log warnings/errors.
+   * @returns {Promise<HTMLImageElement[]>}
+   */
+  static preloadImages(urls, debug = false) {
+    const promises = urls.map(url => {
+      return new Promise(resolve => {
+        const img = new Image();
+        img.onload = () => resolve(img);
+        img.onerror = () => {
+          if (debug) console.warn(`SpinIT Loader Warning: Failed to load image at ${url}`);
+          resolve(null);
+        };
+        img.src = url;
+      });
+    });
+
+    return Promise.all(promises).then(images => images.filter(img => img !== null));
+  }
+}

package/src/Physics.js

@@ -0,0 +1,43 @@
+/**
+ * Physics module for SpinIT.
+ * Handles frame calculations, inertia, and friction.
+ */
+export class Physics {
+  /**
+   * Calculates the current frame based on movement.
+   * @param {number} virtualFrame - Current virtual frame.
+   * @param {number} movementX - Movement in pixels.
+   * @param {number} sensitivity - Pixels per frame.
+   * @param {number} totalFrames - Total number of frames.
+   * @param {boolean} loop - Whether to loop the animation.
+   * @returns {Object} - Updated virtualFrame and final currentFrame.
+   */
+  static calculateFrame(virtualFrame, movementX, sensitivity, totalFrames, loop) {
+    const frameChange = -(movementX / sensitivity);
+    let nextVirtualFrame = virtualFrame + frameChange;
+
+    if (loop) {
+      nextVirtualFrame = ((nextVirtualFrame % totalFrames) + totalFrames) % totalFrames;
+    } else {
+      nextVirtualFrame = Math.max(0, Math.min(totalFrames - 1, nextVirtualFrame));
+    }
+
+    return {
+      virtualFrame: nextVirtualFrame,
+      currentFrame: Math.floor(nextVirtualFrame)
+    };
+  }
+
+  /**
+   * Applies friction to velocity over time.
+   * @param {number} velocity - Current velocity pixels/ms.
+   * @param {number} friction - Friction coefficient.
+   * @param {number} dt - Time delta in ms.
+   * @returns {number} - New velocity.
+   */
+  static applyFriction(velocity, friction, dt) {
+    // Normalize friction to 16ms/frame
+    const effectiveFriction = Math.pow(friction, dt / 16);
+    return velocity * effectiveFriction;
+  }
+}

package/src/Renderer.js

@@ -0,0 +1,139 @@
+/**
+ * Renderer module for SpinIT.
+ * Handles canvas initialization and drawing.
+ */
+export class Renderer {
+  /**
+   * Initializes a canvas within a container.
+   * @param {HTMLElement} container - The container element.
+   * @param {number} width - Default width if not responsive.
+   * @param {number} height - Default height if not responsive.
+   * @param {boolean} [responsive=true] - Whether the canvas should be responsive.
+   * @returns {Object} - { canvas, ctx }
+   */
+  static initCanvas(container, width, height, responsive = true) {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+
+    if (responsive) {
+      canvas.width = container.clientWidth;
+      canvas.height = container.clientHeight;
+      canvas.style.width = "100%";
+      canvas.style.height = "100%";
+    } else {
+      canvas.width = width;
+      canvas.height = height;
+    }
+
+    canvas.className = "spinit-canvas";
+    container.style.position = "relative"; // Ensure loader stays within container
+    container.appendChild(canvas);
+    return { canvas, ctx };
+  }
+
+  /**
+   * Injects the required CSS for the loader and blur effect.
+   */
+  static injectStyles() {
+    const styleId = "spinit-styles";
+    if (document.getElementById(styleId)) return;
+
+    const style = document.createElement("style");
+    style.id = styleId;
+    style.textContent = `
+      .spinit-canvas.blurry {
+        filter: blur(15px);
+        transition: filter 0.6s ease;
+      }
+      .spinit-loader {
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        transform: translate(-50%, -50%);
+        width: 40px;
+        height: 40px;
+        border: 4px solid rgba(0, 0, 0, 0.1);
+        border-top: 4px solid #3498db;
+        border-radius: 50%;
+        animation: spinit-spin 1s linear infinite;
+        z-index: 10;
+        pointer-events: none;
+      }
+      @keyframes spinit-spin {
+        0% { transform: translate(-50%, -50%) rotate(0deg); }
+        100% { transform: translate(-50%, -50%) rotate(360deg); }
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  /**
+   * Toggles blur effect on the canvas.
+   * @param {HTMLCanvasElement} canvas 
+   * @param {boolean} isBlurry 
+   */
+  static applyBlur(canvas, isBlurry) {
+    if (!canvas) return;
+    if (isBlurry) {
+      canvas.classList.add("blurry");
+    } else {
+      canvas.classList.remove("blurry");
+    }
+  }
+
+  /**
+   * Shows a loading indicator in the container.
+   * @param {HTMLElement} container 
+   */
+  static showLoader(container) {
+    if (!container) return;
+    if (container.querySelector(".spinit-loader")) return;
+    const loader = document.createElement("div");
+    loader.className = "spinit-loader";
+    container.appendChild(loader);
+  }
+
+  /**
+   * Hides the loading indicator.
+   * @param {HTMLElement} container 
+   */
+  static hideLoader(container) {
+    if (!container) return;
+    const loader = container.querySelector(".spinit-loader");
+    if (loader) {
+      loader.remove();
+    }
+  }
+
+  /**
+   * Renders a specific frame to the canvas.
+   * @param {CanvasRenderingContext2D} ctx - The canvas context.
+   * @param {number} width - Canvas width.
+   * @param {number} height - Canvas height.
+   * @param {boolean} [debug=false] - Whether debug mode is enabled.
+   * @param {number} [frameIndex=0] - The current frame index.
+   */
+  static renderFrame(ctx, image, width, height, debug = false, frameIndex = 0) {
+    if (!ctx || !image) return;
+    ctx.clearRect(0, 0, width, height);
+    
+    // Calculate scale to fit image (equivalent to object-fit: contain)
+    const scale = Math.min(width / image.width, height / image.height);
+    const drawWidth = image.width * scale;
+    const drawHeight = image.height * scale;
+    
+    // Center the image
+    const x = (width - drawWidth) / 2;
+    const y = (height - drawHeight) / 2;
+    
+    ctx.drawImage(image, x, y, drawWidth, drawHeight);
+
+    if (debug) {
+      ctx.fillStyle = "rgba(0, 0, 0, 0.7)";
+      ctx.fillRect(10, 10, 140, 36);
+      ctx.fillStyle = "white";
+      ctx.font = "16px monospace";
+      ctx.fillText(`Frame: ${frameIndex}`, 20, 34);
+    }
+  }
+}

package/src/SpinIT.js

@@ -0,0 +1,318 @@
+import { Loader } from './Loader.js';
+import { Physics } from './Physics.js';
+import { Renderer } from './Renderer.js';
+import { EventManager } from './EventManager.js';
+
+/**
+ * SpinIT - A modular, professional JavaScript 360-degree image spinner.
+ */
+export class SpinIT {
+  /**
+   * Initializes the SpinIT instance.
+   * @param {string|HTMLElement} container - The container element or CSS selector.
+   * @param {Array} source - Array containing [urlTemplate, startNumber, endNumber].
+   * @param {Object} [options] - Configuration options.
+   */
+  constructor(container, source, options = {}) {
+    this.container = typeof container === 'string' ? document.querySelector(container) : container;
+
+    if (!this.container) {
+      throw new Error("SpinIT Error: Container element not found.");
+    }
+
+    this.options = {
+      loop: options.loop ?? true,
+      inertia: options.inertia ?? true,
+      friction: options.friction ?? 0.95,
+      sensitivity: options.sensitivity ?? 1.0,
+      velocityScale: options.velocityScale ?? 1.0,
+      responsive: options.responsive ?? true,
+      preload: options.preload ?? "all",
+      autoplay: options.autoplay ?? true,
+      autoplaySpeed: options.autoplaySpeed ?? 24,
+      debug: options.debug ?? false
+    };
+
+    /** @type {HTMLImageElement[]} */
+    this.images = [];
+    this.currentFrame = 0;
+    this.virtualFrame = 0;
+
+    this.isDragging = false;
+    this.lastX = 0;
+    this.lastTime = 0;
+    this.velocity = 0; // Pixels per ms
+
+    this.animationId = null;
+    this.lastInertiaTime = 0;
+
+    this.canvas = null;
+    this.ctx = null;
+
+    this.#init(source);
+  }
+
+  #log(...args) {
+    if (this.options.debug) console.log(...args);
+  }
+
+  #error(...args) {
+    if (this.options.debug) console.error(...args);
+  }
+
+  async #init(source) {
+    this.#log("SpinIT: Initializing with source:", source);
+    
+    // 1. Inject styles and show loader
+    Renderer.injectStyles();
+    Renderer.showLoader(this.container);
+
+    const urls = Loader.generateUrls(source[0], source[1], source[2], this.options.debug);
+    const isPreloadingAll = (this.options.preload === "all" || this.options.preload >= urls.length);
+    const preloadCount = isPreloadingAll ? 1 : Math.max(1, this.options.preload);
+
+    const preloadUrls = urls.slice(0, preloadCount);
+    
+    // 2. Preload the specified number of images to show something immediately
+    const preloadedImages = await Loader.preloadImages(preloadUrls, this.options.debug);
+    
+    if (preloadedImages.length === 0) {
+      this.#error("SpinIT Error: Could not load the initial images.");
+      Renderer.hideLoader(this.container);
+      return;
+    }
+
+    // Initialize this.images array with the correct length to allow correct math in physics
+    this.images = new Array(urls.length);
+    for (let i = 0; i < preloadedImages.length; i++) {
+        this.images[i] = preloadedImages[i];
+    }
+    const { width, height } = preloadedImages[0];
+    
+    // 3. Initialize canvas
+    const { canvas, ctx } = Renderer.initCanvas(this.container, width, height, this.options.responsive);
+    this.canvas = canvas;
+    this.ctx = ctx;
+
+    if (this.options.responsive) {
+      this.resizeObserver = new ResizeObserver(() => this.handleResize());
+      this.resizeObserver.observe(this.container);
+    }
+
+    // 4. Render the first frame
+    this.render();
+
+    // If preloading all, keep old behavior: blur, wait for all, unblur.
+    // Otherwise, unblur immediately and load the rest in background.
+    if (isPreloadingAll) {
+      Renderer.applyBlur(this.canvas, true);
+      this.#log("SpinIT: First frame rendered with blur. Loading remaining images...");
+
+      Loader.preloadImages(urls, this.options.debug).then(allImages => {
+        this.#log(`SpinIT: Preloaded ${allImages.length} images. Clearing loading state...`);
+        this.images = allImages;
+        Renderer.applyBlur(this.canvas, false);
+        Renderer.hideLoader(this.container);
+        this.#setupEvents();
+        this.render(); // Final crisp render
+        this.#startAutoPlay();
+        this.#log("SpinIT: Initialization complete. Canvas size:", width, "x", height);
+      });
+    } else {
+      Renderer.applyBlur(this.canvas, false);
+      Renderer.hideLoader(this.container);
+      this.#setupEvents();
+      this.#startAutoPlay();
+      this.#log(`SpinIT: Preloaded ${preloadCount} images. Enabling interaction and loading remaining in background...`);
+
+      const remainingUrls = urls.slice(preloadCount);
+      const remainingPromises = remainingUrls.map((url, i) => {
+        return Loader.preloadImages([url], this.options.debug).then(([img]) => {
+          const index = preloadCount + i;
+          this.images[index] = img;
+          if (this.currentFrame === index) {
+              this.render();
+          }
+        });
+      });
+
+      Promise.all(remainingPromises).then(() => {
+        this.#log("SpinIT: All background images loaded.");
+      });
+    }
+  }
+
+  #setupEvents() {
+    EventManager.setupEvents(this.canvas, {
+      onStart: (e) => {
+        this.#log("SpinIT: Drag started at", e.clientX);
+        this.isDragging = true;
+        this.#stopAutoPlay();
+        this.lastX = e.clientX;
+        this.lastTime = performance.now();
+        this.velocity = 0;
+
+        if (this.animationId) {
+          cancelAnimationFrame(this.animationId);
+        }
+      },
+      onMove: (e) => {
+        if (!this.isDragging) return;
+
+        const now = performance.now();
+        const dt = now - this.lastTime;
+        const dx = e.clientX - this.lastX;
+
+        if (dt > 0) {
+          const currentVelocity = dx / dt;
+          this.velocity = (this.velocity * 0.5) + (currentVelocity * 0.5);
+        }
+
+        this.updateFrame(dx);
+
+        this.lastX = e.clientX;
+        this.lastTime = now;
+      },
+      onEnd: () => {
+        this.#log("SpinIT: Drag ended. Velocity:", this.velocity);
+        this.isDragging = false;
+
+        if (performance.now() - this.lastTime > 50) {
+          this.velocity = 0;
+        }
+
+        if (this.options.inertia && Math.abs(this.velocity) > 0.1) {
+          this.velocity *= this.options.velocityScale;
+          this.lastInertiaTime = performance.now();
+          this.#applyInertia();
+        }
+      }
+    });
+  }
+
+  /**
+   * Updates the current frame based on movement.
+   * @param {number} dx - Movement in pixels.
+   */
+  updateFrame(dx) {
+    const { virtualFrame, currentFrame } = Physics.calculateFrame(
+      this.virtualFrame,
+      dx,
+      this.options.sensitivity,
+      this.images.length,
+      this.options.loop
+    );
+
+    this.virtualFrame = virtualFrame;
+
+    if (this.currentFrame !== currentFrame) {
+      this.#log(`SpinIT: Switching to frame ${currentFrame} (virtual: ${virtualFrame.toFixed(2)})`);
+      this.currentFrame = currentFrame;
+      this.render();
+    }
+
+    // Hard stop for non-looping spin
+    if (!this.options.loop && (this.virtualFrame === 0 || this.virtualFrame === this.images.length - 1)) {
+      this.velocity = 0;
+    }
+  }
+
+  #applyInertia() {
+    const now = performance.now();
+    const dt = now - this.lastInertiaTime;
+    this.lastInertiaTime = now;
+
+    if (dt <= 0) {
+      this.animationId = requestAnimationFrame(() => this.#applyInertia());
+      return;
+    }
+
+    this.velocity = Physics.applyFriction(this.velocity, this.options.friction, dt);
+    const frameMovement = this.velocity * dt;
+
+    if (Math.abs(frameMovement) < 0.1) {
+      this.velocity = 0;
+      this.lastInertiaTime = 0;
+      return;
+    }
+
+    this.updateFrame(frameMovement);
+    this.animationId = requestAnimationFrame(() => this.#applyInertia());
+  }
+
+  /**
+   * Handles container resize.
+   */
+  handleResize() {
+    if (!this.canvas || !this.container) return;
+    this.canvas.width = this.container.clientWidth;
+    this.canvas.height = this.container.clientHeight;
+    this.render();
+  }
+
+  /**
+   * Renders the current frame.
+   */
+  render() {
+    Renderer.renderFrame(
+      this.ctx, 
+      this.images[this.currentFrame], 
+      this.canvas.width, 
+      this.canvas.height, 
+      this.options.debug, 
+      this.currentFrame
+    );
+  }
+
+  /**
+   * Destroys the SpinIT instance and cleans up.
+   */
+  destroy() {
+    this.#stopAutoPlay();
+    if (this.resizeObserver) {
+      this.resizeObserver.disconnect();
+    }
+    if (this.animationId) {
+      cancelAnimationFrame(this.animationId);
+    }
+    // Remove canvas if needed, or other cleanup...
+    if (this.canvas && this.canvas.parentNode) {
+      this.canvas.parentNode.removeChild(this.canvas);
+    }
+  }
+
+  #startAutoPlay() {
+    if (this.options.autoplay === false) return;
+    
+    this.isAutoPlaying = true;
+    
+    let targetFrame = null;
+    if (typeof this.options.autoplay === 'number') {
+      targetFrame = this.options.autoplay;
+      if (this.currentFrame === targetFrame) return;
+    }
+
+    this.autoPlayInterval = setInterval(() => {
+      if (!this.isAutoPlaying) {
+        this.#stopAutoPlay();
+        return;
+      }
+
+      this.updateFrame(-Math.max(1, this.options.sensitivity));
+      
+      if (targetFrame !== null && this.currentFrame === targetFrame) {
+        this.#stopAutoPlay();
+      } else if (!this.options.loop && this.currentFrame === this.images.length - 1) {
+        this.#stopAutoPlay();
+      }
+    }, 1000 / this.options.autoplaySpeed);
+  }
+
+  #stopAutoPlay() {
+    this.isAutoPlaying = false;
+    if (this.autoPlayInterval) {
+      clearInterval(this.autoPlayInterval);
+      this.autoPlayInterval = null;
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+import { SpinIT } from './SpinIT.js';
+
+export { SpinIT };
+export default SpinIT;