@linear_non/stellar-libs 1.0.8 → 1.0.9

package/README.md

@@ -2,7 +2,7 @@
 
 A collection of lightweight, reusable frontend UI behavior modules — built to work seamlessly with [`stellar-kit`](https://www.npmjs.com/package/@linear_non/stellar-kit) and the [Stellar](https://github.com/nonlinearstudio/stellar) frontend system. Each library is self-contained, configurable, and designed to be dropped into modular websites. Also is a project that is constantly growing and we are adding new updates all the time.
 
-## ✨ Avalible Libs
+## ✨ Available Libs
 
 - Designed for plug-and-play
 - **Sticky**: Basic sticky logic for DOM elements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linear_non/stellar-libs",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Reusable JavaScript libraries for Non-Linear Studio projects.",
   "main": "src/index.js",
   "type": "module",

package/src/SpritePlayer/index.js

@@ -14,14 +14,20 @@ export default class SpritePlayer {
     total = 0,
     progress = 0,
     fileExtension = "png",
-    cache = null, // optional Map for global cache
-    persistent = false, // true if using shared cache (don’t revoke)
+    cache = null,
+    persistent = false,
+    // alpha options
+    alpha_path = null, // { mobile: "...", desktop: "..." }
+    fileAlpha = null, // e.g. "sprite_mask_"
+    useAlpha = false,
   }) {
     const rect = bounds(container)
-    this.progress = progress
+
+    this.progress = gsap.utils.clamp(0, 1, progress)
     this.persistent = persistent
+    this.isAlpha = !!useAlpha
 
-    this.dom = { container, reference: container, images: [] }
+    this.dom = { container, reference: container, images: [], alphaImages: [] }
     this.canvas = {
       el: canvas,
       ctx: canvas.getContext("2d"),
@@ -37,6 +43,8 @@ export default class SpritePlayer {
       total,
       file_extension: fileExtension,
       cache,
+      alpha_path,
+      fileAlpha,
     }
 
     this.state = { loaded: false }
@@ -45,27 +53,34 @@ export default class SpritePlayer {
   }
 
   async loadImages() {
-    const { mobile_path, desktop_path, total, file_name, file_extension, cache } = this.settings
-    const origin = sniffer.isDesktop ? desktop_path : mobile_path
-
-    const loader = new ImageLoader({
-      origin,
-      fileName: file_name,
-      extension: file_extension,
-      total,
-      cache, // pass cache Map if you have one
-      useWorker: true,
-    })
+    const { mobile_path, desktop_path, alpha_path, file_name, fileAlpha, total, file_extension, cache } =
+      this.settings
+
+    const originBase = sniffer.isDesktop ? desktop_path : mobile_path
+    const originAlpha = alpha_path ? (sniffer.isDesktop ? alpha_path.desktop : alpha_path.mobile) : null
+
+    const make = (origin, name) =>
+      new ImageLoader({
+        origin,
+        fileName: name,
+        extension: file_extension,
+        total,
+        cache,
+        useWorker: true,
+      }).load()
 
-    // (optional) forward progress
     const onProgress = e => emitter.emit("sprite:progress", { instance: this, ...e })
     emitter.on(ImageLoader.events.PROGRESS, onProgress)
 
-    const images = await loader.load() // ✅ get images from promise
+    const [images, alphaImages] = await Promise.all([
+      make(originBase, file_name),
+      originAlpha && fileAlpha ? make(originAlpha, fileAlpha) : Promise.resolve([]),
+    ])
 
     emitter.off?.(ImageLoader.events.PROGRESS, onProgress)
 
     this.dom.images = images
+    this.dom.alphaImages = alphaImages
     this.frameCount = images.length
     this.state.loaded = true
     emitter.emit("sprite:loaded", this)
@@ -116,14 +131,22 @@ export default class SpritePlayer {
     this.scroll = current
 
     const { ctx, width, height, area, offset } = this.canvas
-    const { images } = this.dom
+    const { images, alphaImages } = this.dom
     const total = this.frameCount || images.length || 1
-    const val = gsap.utils.clamp(0, total - 1, this.progress * total)
-    const index = Math.floor(val)
-    const img = images[index]
+    const index = Math.min(total - 1, Math.round(this.progress * (total - 1)))
+    const base = images[index]
+    const mask = this.isAlpha ? alphaImages[index] : null
 
     ctx.clearRect(0, 0, width, height)
-    if (img) this.drawImageCover(ctx, img, area, offset)
+    if (!base) return
+
+    this.drawImageCover(ctx, base, area, offset)
+
+    if (mask) {
+      ctx.globalCompositeOperation = "destination-in"
+      this.drawImageCover(ctx, mask, area, offset)
+      ctx.globalCompositeOperation = "source-over"
+    }
   }
 
   resize = () => this.configureCanvas()
@@ -137,11 +160,32 @@ export default class SpritePlayer {
     emitter.off(EVENTS.APP_RESIZE, this.resize)
   }
 
+  setProgress(p) {
+    this.progress = gsap.utils.clamp(0, 1, p)
+  }
+
+  show() {
+    this.isVisible = true
+  }
+  hide() {
+    this.isVisible = false
+    const { ctx, width, height } = this.canvas
+    ctx.clearRect(0, 0, width, height)
+  }
+
+  enableAlpha(v = true) {
+    this.isAlpha = !!v
+  }
+
   destroy() {
     this.off()
-    // Only revoke if not using shared cache
-    if (!this.persistent) this.dom.images.forEach(img => URL.revokeObjectURL(img?.src))
+    if (!this.persistent) {
+      const revoke = img => img?.src?.startsWith("blob:") && URL.revokeObjectURL(img.src)
+      this.dom.images.forEach(revoke)
+      this.dom.alphaImages.forEach(revoke)
+    }
     this.dom.images = []
+    this.dom.alphaImages = []
   }
 
   async init() {