@linear_non/stellar-libs 1.0.8 → 1.0.10

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.10",
   "description": "Reusable JavaScript libraries for Non-Linear Studio projects.",
   "main": "src/index.js",
   "type": "module",

package/src/SpritePlayer/index.js

@@ -14,14 +14,18 @@ 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_path = null, // { mobile, desktop }
+    fileAlpha = null,
+    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 +41,8 @@ export default class SpritePlayer {
       total,
       file_extension: fileExtension,
       cache,
+      alpha_path,
+      fileAlpha,
     }
 
     this.state = { loaded: false }
@@ -45,27 +51,44 @@ 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 { mobile_path, desktop_path, alpha_path, file_name, fileAlpha, total, file_extension, cache } =
+      this.settings
+
+    const originBase = sniffer.isDesktop ? desktop_path : mobile_path || desktop_path
+    const originAlpha = alpha_path
+      ? sniffer.isDesktop
+        ? alpha_path.desktop || alpha_path.mobile
+        : alpha_path.mobile || alpha_path.desktop
+      : null
+
+    const make = (origin, name) =>
+      new ImageLoader({
+        origin,
+        fileName: name,
+        extension: file_extension,
+        total,
+        cache,
+        useWorker: true,
+      }).load()
 
-    const loader = new ImageLoader({
-      origin,
-      fileName: file_name,
-      extension: file_extension,
-      total,
-      cache, // pass cache Map if you have one
-      useWorker: true,
-    })
-
-    // (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
+
+    if (this.isAlpha && this.dom.alphaImages.length) {
+      this.dom.alphaImages = this.dom.alphaImages.map(img => this.toAlphaFromLuma(img))
+    }
+    if (this.isAlpha && !this.dom.alphaImages.length) this.isAlpha = false
+
     this.frameCount = images.length
     this.state.loaded = true
     emitter.emit("sprite:loaded", this)
@@ -89,9 +112,31 @@ export default class SpritePlayer {
     Object.assign(this.canvas, { width: rect.width, height: rect.height, rect, area, offset })
   }
 
+  // grayscale -> alpha (returns a canvas)
+  toAlphaFromLuma(img) {
+    const w = img.naturalWidth || img.width,
+      h = img.naturalHeight || img.height
+    const c = document.createElement("canvas")
+    c.width = w
+    c.height = h
+    const x = c.getContext("2d")
+    x.drawImage(img, 0, 0, w, h)
+    const d = x.getImageData(0, 0, w, h)
+    const a = d.data
+    for (let i = 0; i < a.length; i += 4) {
+      const lum = a[i] * 0.2126 + a[i + 1] * 0.7152 + a[i + 2] * 0.0722
+      a[i] = 0
+      a[i + 1] = 0
+      a[i + 2] = 0
+      a[i + 3] = lum
+    }
+    x.putImageData(d, 0, 0)
+    return c
+  }
+
   drawImageCover(ctx, img, area, offset) {
-    const iw = img.naturalWidth,
-      ih = img.naturalHeight
+    const iw = img.naturalWidth || img.width
+    const ih = img.naturalHeight || img.height
     const cw = area.width,
       ch = area.height
     const ir = iw / ih,
@@ -116,14 +161,24 @@ 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 hasMasks = this.isAlpha && alphaImages.length === images.length
+    const mask = hasMasks ? 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.save()
+      ctx.globalCompositeOperation = "destination-in"
+      this.drawImageCover(ctx, mask, area, offset)
+      ctx.restore()
+    }
   }
 
   resize = () => this.configureCanvas()
@@ -137,11 +192,30 @@ 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() {