@linear_non/stellar-libs 1.0.7 → 1.0.9

package/README.md

@@ -1,14 +1,15 @@
 # stellar-libs
 
-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.
+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.
 
-## ✨ Features
+## ✨ Available Libs
 
+- Designed for plug-and-play
 - **Sticky**: Basic sticky logic for DOM elements
-- **SplitOnScroll**: Text splitting + reveal synced to scroll
 - **Smooth**: Smooth scroll instance using Virtual Scroll
-- Designed for plug-and-play usage inside Stellar Template
-- Works with `kitStore`, `Resize`, `Scroll`, `Raf`, and GSAP if needed
+- **SplitOnScroll**: Text splitting + reveal synced to scroll
+- **Noise**: Configurable canvas noise
+- **SpritePlayer**: Canvas image sequence player
 
 ## 📦 Installation
 
@@ -16,7 +17,7 @@ A collection of lightweight, reusable frontend UI behavior modules — built to
 npm install @linear_non/stellar-libs
 ```
 
-> Note: Some libraries rely on `stellar-kit` for shared events, scroll, or utilities. Be sure to install both if needed:
+> Note: Most libraries rely on `stellar-kit` for shared events, scroll, or utilities. Be sure to install both:
 
 ```bash
 npm install @linear_non/stellar-kit
@@ -31,6 +32,8 @@ stellar-libs/
 │   ├── SplitOnScroll/      # Scroll-triggered text reveals
 │   ├── Smooth/             # Smooth scrolling system
 │   └── ScrollBar/          # Custom scrollbar component
+│   └── Noise/              # Canvas noise
+│   └── SpritePlayer/       # Image sprite player
 ├── dev/                    # Dev playgrounds for each lib
 ├── index.js                # Entry point for exports
 └── vite.config.js          # Vite config to run individual demos
@@ -48,12 +51,12 @@ npm run dev
 ## 🛠️ Usage Example
 
 ```js
-import { Sticky } from "@linear_non/stellar-libs";
+import { Sticky } from "@linear_non/stellar-libs"
 
 const sticky = new Sticky({
   el: qs(".sticky"),
   sticky: qs(".sticky-content"),
-});
+})
 ```
 
 > You can find usage examples in each library’s README file also an HTML markup example. You can see a live example inside the `dev/` folder.
@@ -62,10 +65,7 @@ const sticky = new Sticky({
 
 ### ✅ TODO
 
-- [ ] Implement `Marquee` module
-- [ ] Implement `Dropdown` module
-- [ ] Implement `Lenis` scroll
-- [ ] Update Readme files for each component
+This is a projects that will continue growing and we have plan to add as many things that we feel can be helpful for us in the future.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linear_non/stellar-libs",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Reusable JavaScript libraries for Non-Linear Studio projects.",
   "main": "src/index.js",
   "type": "module",
@@ -25,7 +25,7 @@
   "author": "Non-Linear Studio",
   "license": "MIT",
   "dependencies": {
-    "@linear_non/stellar-kit": "^1.1.0"
+    "@linear_non/stellar-kit": "^1.1.7"
   },
   "devDependencies": {
     "@linear_non/prettier-config": "^1.0.6",

package/src/SpritePlayer/index.js

@@ -0,0 +1,196 @@
+// SpritePlayer.js
+import { ImageLoader } from "@linear_non/stellar-kit/classes"
+import { emitter, EVENTS } from "@linear_non/stellar-kit/events"
+import { sniffer, bounds } from "@linear_non/stellar-kit/utils"
+import { gsap } from "@linear_non/stellar-kit/gsap"
+
+export default class SpritePlayer {
+  constructor({
+    canvas,
+    container,
+    mobile_path,
+    desktop_path,
+    fileName,
+    total = 0,
+    progress = 0,
+    fileExtension = "png",
+    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 = gsap.utils.clamp(0, 1, progress)
+    this.persistent = persistent
+    this.isAlpha = !!useAlpha
+
+    this.dom = { container, reference: container, images: [], alphaImages: [] }
+    this.canvas = {
+      el: canvas,
+      ctx: canvas.getContext("2d"),
+      width: rect.width,
+      height: rect.height,
+      rect,
+    }
+
+    this.settings = {
+      mobile_path,
+      desktop_path,
+      file_name: fileName,
+      total,
+      file_extension: fileExtension,
+      cache,
+      alpha_path,
+      fileAlpha,
+    }
+
+    this.state = { loaded: false }
+    this.isVisible = true
+    this.init()
+  }
+
+  async loadImages() {
+    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()
+
+    const onProgress = e => emitter.emit("sprite:progress", { instance: this, ...e })
+    emitter.on(ImageLoader.events.PROGRESS, onProgress)
+
+    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)
+  }
+
+  configureCanvas() {
+    const { container, reference } = this.dom
+    const rect = bounds(container)
+    const area = bounds(reference)
+    const offset = area.top - rect.top
+    const dpr = window.devicePixelRatio || 1
+
+    const { el, ctx } = this.canvas
+    el.style.width = `${rect.width}px`
+    el.style.height = `${rect.height}px`
+    el.width = Math.floor(rect.width * dpr)
+    el.height = Math.floor(rect.height * dpr)
+    ctx.setTransform(1, 0, 0, 1, 0, 0)
+    ctx.scale(dpr, dpr)
+
+    Object.assign(this.canvas, { width: rect.width, height: rect.height, rect, area, offset })
+  }
+
+  drawImageCover(ctx, img, area, offset) {
+    const iw = img.naturalWidth,
+      ih = img.naturalHeight
+    const cw = area.width,
+      ch = area.height
+    const ir = iw / ih,
+      cr = cw / ch
+    let sw, sh, sx, sy
+    if (ir > cr) {
+      sh = ih
+      sw = ih * cr
+      sx = (iw - sw) / 2
+      sy = 0
+    } else {
+      sw = iw
+      sh = iw / cr
+      sx = 0
+      sy = (ih - sh) / 2
+    }
+    ctx.drawImage(img, sx, sy, sw, sh, 0, offset, cw, ch)
+  }
+
+  tick = ({ current }) => {
+    if (!this.state.loaded || !this.isVisible) return
+    this.scroll = current
+
+    const { ctx, width, height, area, offset } = this.canvas
+    const { images, alphaImages } = this.dom
+    const total = this.frameCount || images.length || 1
+    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 (!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()
+
+  on() {
+    emitter.on(EVENTS.APP_TICK, this.tick)
+    emitter.on(EVENTS.APP_RESIZE, this.resize)
+  }
+  off() {
+    emitter.off(EVENTS.APP_TICK, this.tick)
+    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()
+    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() {
+    await this.loadImages()
+    this.configureCanvas()
+    this.on()
+  }
+}

package/src/Sticky/index.js

@@ -38,7 +38,7 @@ export default class Sticky {
       scrub: true,
       onEnter: () => this.toggleSticky(true),
       onEnterBack: () => this.toggleSticky(true),
-      onLeave: () => this.toggleSticky(false, true), // ✅ Ensure totalHeight is passed
+      onLeave: () => this.toggleSticky(false, true),
       onLeaveBack: () => this.toggleSticky(false),
       onUpdate: self => this.onUpdate(self),
     })

package/src/index.js

@@ -2,5 +2,6 @@ import Sticky from "./Sticky"
 import Smooth from "./Smooth"
 import SplitonScroll from "./SplitOnScroll"
 import Noise from "./Noise"
+import SpritePlayer from "./SpritePlayer"
 
-export { Sticky, Smooth, SplitonScroll, Noise }
+export { Sticky, Smooth, SplitonScroll, Noise, SpritePlayer }