@linear_non/stellar-libs 1.3.1 → 1.4.2

package/README.md

@@ -1,72 +1,180 @@
 # 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. Also is a project that is constantly growing and we are adding new updates all the time.
+> `@linear_non/stellar-libs` — Reusable UI behavior modules for Non-Linear Studio projects.
 
-## ✨ Available Libs
+A collection of lightweight, self-contained frontend UI behavior modules built to work seamlessly with [`@linear_non/stellar-kit`](https://www.npmjs.com/package/@linear_non/stellar-kit). Each library provides specific functionality and can be dropped into modular websites with minimal configuration.
 
-- Designed for plug-and-play
-- **Sticky**: Basic sticky logic for DOM elements
-- **Smooth**: Smooth scroll instance using Virtual Scroll
-- **SplitOnScroll**: Text splitting + reveal synced to scroll
-- **Noise**: Configurable canvas noise
-- **SpritePlayer**: Canvas image sequence player
+## Available Libraries
 
-## 📦 Installation
+| Library | Description |
+|---|---|
+| **Sticky** | Sticky scroll behavior with GSAP ScrollTrigger |
+| **Smooth** | Smooth scroll system using VirtualScroll |
+| **SplitOnScroll** | Text splitting with scroll-triggered reveals |
+| **Noise** | Canvas-based animated noise effect |
+| **SpritePlayer** | Image sequence player on canvas |
+| **CursorTracker** | Custom cursor that follows mouse |
+| **Marquee** | Infinite horizontal marquee scroller |
+| **Slider** | Drag slider with optional infinite loop and progress |
+
+## Installation
 
 ```bash
 npm install @linear_non/stellar-libs
+npm install @linear_non/stellar-kit
 ```
 
-> Note: Most libraries rely on `stellar-kit` for shared events, scroll, or utilities. Be sure to install both:
+## Local Development
 
 ```bash
-npm install @linear_non/stellar-kit
+npm install
+npm run dev
+```
+
+Launches a Vite dev server with a demo index linking to individual playgrounds for each library.
+
+---
+
+## Usage
+
+### Sticky
+
+```js
+import { Sticky } from "@linear_non/stellar-libs"
+
+const sticky = new Sticky({
+  el: document.querySelector(".sticky-container"),
+  sticky: document.querySelector(".sticky-element"),
+  isSmooth: false,
+  onUpdateCallback: ({ progress }) => console.log(progress),
+})
 ```
 
-## 📁 Folder Structure
+### Smooth
 
+```js
+import { Smooth } from "@linear_non/stellar-libs"
+
+const smooth = new Smooth({ scroll: kitStore.scroll })
 ```
-stellar-libs/
-├── src/
-│   ├── Sticky/             # Sticky behavior module
-│   ├── 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
+
+```html
+<section data-smooth data-speed="0.8">Parallax content</section>
 ```
 
-## 🧪 Local Development
+### SplitOnScroll
 
-```bash
-npm install
-npm run dev
+```js
+import { SplitOnScroll } from "@linear_non/stellar-libs"
+
+const split = new SplitOnScroll({
+  el: document.querySelector(".trigger"),
+  splitText: document.querySelectorAll("h1"),
+  isReady: ({ splits, groups }) => {
+    gsap.from(splits[0].chars, { y: 40, opacity: 0, stagger: 0.03 })
+  },
+  once: true,
+})
 ```
 
-> This launches a Vite server and scans `dev/*/index.html` to preview each module. You can open individual demos for testing.
+> The constructor key is `splitText` (not `splitTargets`). The `isReady` callback receives `{ splits, groups }`.
 
-## 🛠️ Usage Example
+### Noise
 
 ```js
-import { Sticky } from "@linear_non/stellar-libs"
+import { Noise } from "@linear_non/stellar-libs"
+
+const noise = new Noise({
+  target: ".noise-canvas",
+  density: 0.75,
+  color: 0xf3f2feff,
+  opacity: 0.25,
+  fps: 24,
+})
+```
 
-const sticky = new Sticky({
-  el: qs(".sticky"),
-  sticky: qs(".sticky-content"),
+### SpritePlayer
+
+```js
+import { SpritePlayer } from "@linear_non/stellar-libs"
+
+const player = new SpritePlayer({
+  canvas: document.querySelector("canvas"),
+  container: document.querySelector(".player-container"),
+  desktop_path: "/sprites/desktop/",
+  mobile_path: "/sprites/mobile/",
+  fileName: "frame_{index}",
+  total: 60,
+})
+
+await player.init()
+player.setProgress(0.5)
+```
+
+### CursorTracker
+
+```js
+import { CursorTracker } from "@linear_non/stellar-libs"
+
+const tracker = new CursorTracker({
+  container: document.querySelector(".hover-area"),
+  el: document.querySelector(".cursor"),
+  ease: 0.12,
+  isCentered: true,
+})
+```
+
+> `CursorTracker` subscribes to `APP_TICK` internally — do not add an external tick subscription.
+
+### Marquee
+
+```js
+import { Marquee } from "@linear_non/stellar-libs"
+
+const marquee = new Marquee({
+  container: document.querySelector(".marquee"),
+  el: document.querySelector(".marquee__track"),
+  speed: 50,
+  gap: "1.6rem",
 })
 ```
 
-> 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.
+### Slider
+
+```js
+import { Slider } from "@linear_non/stellar-libs"
+
+const slider = new Slider({
+  container: document.querySelector(".slider"),
+  el: document.querySelector(".slider__track"),
+  speed: 0.1,
+  snap: true,
+  infinite: false,
+  prevEl: document.querySelector(".prev"),
+  nextEl: document.querySelector(".next"),
+  progressEl: document.querySelector(".progress-fill"),
+  onSlideChange: ({ index, total }) => console.log(index, total),
+})
+```
+
+```html
+<div class="slider">
+  <div class="slider__track">
+    <div class="slide">01</div>
+    <div class="slide">02</div>
+    <div class="slide">03</div>
+  </div>
+</div>
+```
 
 ---
 
-### ✅ TODO
+## Lifecycle
+
+All libraries follow a consistent class-based lifecycle: `init() → on() → tick() → resize() → off() → destroy()`
 
-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.
+Always call `destroy()` on page navigation to clean up event listeners, animations, and timers.
 
 ---
 
-Made with ❤️ by [Non-Linear Studio](https://non-linear.studio)
+Made with love by [Non-Linear Studio](https://non-linear.studio)

package/package.json

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

package/src/Slider/index.js

@@ -0,0 +1,375 @@
+import { lerp, bounds, sniffer } from "@linear_non/stellar-kit/utils"
+import { gsap } from "@linear_non/stellar-kit/gsap"
+import { emitter, EVENTS } from "@linear_non/stellar-kit/events"
+
+export default class Slider {
+  constructor({
+    container,
+    el,
+    speed = 0.1,
+    snap = true,
+    infinite = false,
+    mobileOnly = false,
+    prevEl = null,
+    nextEl = null,
+    progressEl = null,
+    onSlideChange = null,
+  }) {
+    this.container = container
+    this.el = el
+    this.speed = speed
+    this.snap = infinite ? true : snap // infinite always snaps
+    this.infinite = infinite
+    this.mobileOnly = mobileOnly
+    this.prevEl = prevEl
+    this.nextEl = nextEl
+    this.progressEl = progressEl
+    this.onSlideChange = typeof onSlideChange === "function" ? onSlideChange : null
+
+    this.isActive = false
+    this.isDown = false
+    this.isDragging = false
+
+    this.x = { start: 0, state: 0 }
+    this.current = 0
+    this.target = 0
+    this.index = 0 // 0-based real index (infinite: derived from position)
+    this.total = 0
+    this.slideWidth = 0
+    this.setW = 0 // total width of one full set of real slides (infinite mode)
+    this.limit = 0
+
+    this.dpr = Math.max(1, Math.round(window.devicePixelRatio || 1))
+    this._snap2px = v => Math.round(v * this.dpr) / this.dpr
+
+    this.init()
+  }
+
+  // ─── Setup ────────────────────────────────────────────────────────────────
+
+  _shouldActivate() {
+    return !this.mobileOnly || sniffer.isDevice
+  }
+
+  setup() {
+    this.isActive = this._shouldActivate()
+    if (!this.isActive) return
+
+    if (this.infinite) {
+      this._setupInfinite()
+    } else {
+      this._measure()
+      this.index = gsap.utils.clamp(0, this.total - 1, this.index)
+      this.target = this.index * this.slideWidth
+      this.current = this.target
+      this._draw(this.current)
+    }
+  }
+
+  _measure() {
+    // Only measure non-clone slides for width/total
+    const rawSlides = Array.from(this.el.children).filter(s => !s.dataset.clone)
+    this.total = rawSlides.length
+    if (!this.total) return
+
+    const gapPx = parseFloat(getComputedStyle(this.el).gap) || 0
+    this.slideWidth = rawSlides[0].getBoundingClientRect().width + gapPx
+    this.setW = this.slideWidth * this.total
+    const viewWidth = bounds(this.container).width
+    this.limit = Math.max(0, this.setW - viewWidth)
+  }
+
+  _setupInfinite() {
+    // Remove any stale clones from previous setup
+    Array.from(this.el.querySelectorAll("[data-clone]")).forEach(c => c.remove())
+
+    const rawSlides = Array.from(this.el.children)
+    if (rawSlides.length < 2) return
+
+    // Clone the ENTIRE set before and after (tripling) so the user can never
+    // reach a real edge regardless of drag speed or prev/next calls.
+    const cloneBefore = rawSlides.map(s => {
+      const c = s.cloneNode(true)
+      c.setAttribute("aria-hidden", "true")
+      c.dataset.clone = "before"
+      return c
+    })
+    const cloneAfter = rawSlides.map(s => {
+      const c = s.cloneNode(true)
+      c.setAttribute("aria-hidden", "true")
+      c.dataset.clone = "after"
+      return c
+    })
+
+    // Prepend "before" in correct visual order, append "after"
+    ;[...cloneBefore].reverse().forEach(c => this.el.prepend(c))
+    cloneAfter.forEach(c => this.el.appendChild(c))
+
+    this._measure()
+
+    // x convention: translateX(-x). Start at setW so real slide 0 is visible.
+    // Track layout: [before clones 0..setW) [real slides setW..2setW) [after clones 2setW..3setW)
+    this.index = 0
+    this.current = this.setW
+    this.target = this.setW
+    this._draw(this.current)
+  }
+
+  // ─── Infinite wrap (runs every tick) ──────────────────────────────────────
+  // Silently teleport when position drifts outside the real-set zone.
+  // Because we cloned full sets on both sides this jump is always invisible.
+
+  _wrapInfinite() {
+    if (!this.setW) return
+    let shift = 0
+    if (this.current < 0) {
+      shift = Math.ceil(-this.current / this.setW) * this.setW
+    } else if (this.current >= 2 * this.setW) {
+      shift = -Math.floor((this.current - this.setW) / this.setW) * this.setW
+    }
+    if (shift !== 0) {
+      this.current += shift
+      this.target += shift
+      // Keep the drag reference in sync so the next onPointerMove doesn't
+      // compute a target relative to the pre-wrap baseline, which would cause
+      // the slider to snap back to the wrong position.
+      if (this.isDown) this.x.state += shift
+    }
+  }
+
+  // ─── Render ───────────────────────────────────────────────────────────────
+
+  _draw(x) {
+    this.el.style.transform = `translate3d(${-this._snap2px(x)}px, 0, 0)`
+  }
+
+  _updateProgress() {
+    if (!this.progressEl || this.infinite) return
+    const progress = this.limit > 0 ? this.current / this.limit : 0
+    this.progressEl.style.transformOrigin = "left center"
+    this.progressEl.style.transform = `scaleX(${gsap.utils.clamp(0, 1, progress)})`
+  }
+
+  // ─── Tick ─────────────────────────────────────────────────────────────────
+
+  tick = () => {
+    if (!this.isActive) return
+
+    const prev = this.current
+    this.current = lerp(this.current, this.target, this.speed)
+
+    // Snap to exact value when close enough to avoid sub-pixel drift
+    if (Math.abs(this.current - this.target) < 0.01) {
+      this.current = this.target
+    }
+
+    // Infinite: wrap on every tick (not just when settled) so a fast drag
+    // that overshoots the clone zone is corrected immediately.
+    if (this.infinite) this._wrapInfinite()
+
+    if (this.current !== prev) {
+      this._draw(this.current)
+      this._updateProgress()
+    }
+  }
+
+  // ─── Snap ─────────────────────────────────────────────────────────────────
+
+  _snapToNearest() {
+    if (!this.slideWidth) return
+
+    if (this.infinite) {
+      // Round to nearest slide in ABSOLUTE (un-normalised) space.
+      // Do NOT clamp target back into [0, 2·setW) here — that would invert the
+      // lerp direction if the user released before current crossed the wrap
+      // boundary, causing a visible "all-slides-jump-backward" reset.
+      // Instead, keep target in whatever cycle it is; _wrapInfinite will shift
+      // both current and target together tick-by-tick as current naturally
+      // crosses each setW boundary — always seamless, always forward.
+      this.target = Math.round(this.target / this.slideWidth) * this.slideWidth
+      // Derive real 0-based index via modulo on normalised position
+      const normPos = ((this.target % this.setW) + this.setW) % this.setW
+      this.index = Math.round(normPos / this.slideWidth) % this.total
+    } else {
+      this.index = gsap.utils.clamp(0, this.total - 1, Math.round(this.target / this.slideWidth))
+      this.target = gsap.utils.clamp(0, this.limit, this.index * this.slideWidth)
+    }
+
+    this._fireChange()
+  }
+
+  _fireChange() {
+    if (!this.onSlideChange) return
+    this.onSlideChange({ index: this.index, total: this.total })
+  }
+
+  // ─── Public navigation ────────────────────────────────────────────────────
+
+  next = () => {
+    if (!this.isActive) return
+    if (this.infinite) {
+      this.target += this.slideWidth
+      this.index = (this.index + 1) % this.total
+    } else {
+      this.index = gsap.utils.clamp(0, this.total - 1, this.index + 1)
+      this.target = gsap.utils.clamp(0, this.limit, this.index * this.slideWidth)
+    }
+    this._fireChange()
+  }
+
+  prev = () => {
+    if (!this.isActive) return
+    if (this.infinite) {
+      this.target -= this.slideWidth
+      this.index = (this.index - 1 + this.total) % this.total
+    } else {
+      this.index = gsap.utils.clamp(0, this.total - 1, this.index - 1)
+      this.target = gsap.utils.clamp(0, this.limit, this.index * this.slideWidth)
+    }
+    this._fireChange()
+  }
+
+  goTo(i) {
+    if (!this.isActive) return
+    const idx = gsap.utils.clamp(0, this.total - 1, i)
+    if (this.infinite) {
+      // Find the shortest delta from current position to target idx
+      const currentIdx = this.index
+      let delta = idx - currentIdx
+      if (Math.abs(delta) > this.total / 2) {
+        delta = delta > 0 ? delta - this.total : delta + this.total
+      }
+      this.target += delta * this.slideWidth
+    } else {
+      this.target = gsap.utils.clamp(0, this.limit, idx * this.slideWidth)
+    }
+    this.index = idx
+    this._fireChange()
+  }
+
+  // ─── Pointer events ───────────────────────────────────────────────────────
+
+  onPointerDown = e => {
+    if (!this.isActive) return
+    const clientX = e.touches ? e.touches[0].clientX : e.clientX
+    this.isDown = true
+    this.x.start = clientX
+    this.x.state = this.target
+    this.container.classList.add("-dragging")
+  }
+
+  onPointerMove = e => {
+    if (!this.isActive || !this.isDown) return
+    this.isDragging = true
+    const clientX = e.touches ? e.touches[0].clientX : e.clientX
+    const delta = this.x.start - clientX
+    let newTarget = this.x.state + delta
+
+    if (!this.infinite) {
+      newTarget = gsap.utils.clamp(0, this.limit, newTarget)
+    }
+
+    this.target = newTarget
+  }
+
+  onPointerUp = () => {
+    if (!this.isActive) return
+    this.isDown = false
+    this.container.classList.remove("-dragging")
+
+    if (this.isDragging && this.snap) {
+      this._snapToNearest()
+    }
+
+    this.isDragging = false
+  }
+
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
+
+  on() {
+    if (!this.isActive) return
+
+    this.container.addEventListener("mousedown", this.onPointerDown)
+    this.container.addEventListener("touchstart", this.onPointerDown, { passive: true })
+    window.addEventListener("mousemove", this.onPointerMove)
+    window.addEventListener("touchmove", this.onPointerMove, { passive: true })
+    window.addEventListener("mouseup", this.onPointerUp)
+    window.addEventListener("touchend", this.onPointerUp)
+
+    if (this.prevEl) this.prevEl.addEventListener("click", this.prev)
+    if (this.nextEl) this.nextEl.addEventListener("click", this.next)
+
+    emitter.on(EVENTS.APP_TICK, this.tick)
+    emitter.on(EVENTS.APP_RESIZE, this.resize)
+  }
+
+  off() {
+    this.container?.removeEventListener("mousedown", this.onPointerDown)
+    this.container?.removeEventListener("touchstart", this.onPointerDown)
+    window.removeEventListener("mousemove", this.onPointerMove)
+    window.removeEventListener("touchmove", this.onPointerMove)
+    window.removeEventListener("mouseup", this.onPointerUp)
+    window.removeEventListener("touchend", this.onPointerUp)
+
+    if (this.prevEl) this.prevEl.removeEventListener("click", this.prev)
+    if (this.nextEl) this.nextEl.removeEventListener("click", this.next)
+
+    emitter.off(EVENTS.APP_TICK, this.tick)
+    emitter.off(EVENTS.APP_RESIZE, this.resize)
+  }
+
+  resize = () => {
+    const wasActive = this.isActive
+    this.isActive = this._shouldActivate()
+
+    // Was active, now inactive (e.g. mobileOnly + resized to desktop)
+    if (wasActive && !this.isActive) {
+      this._reset()
+      this.off()
+      return
+    }
+
+    // Was inactive, now active (e.g. mobileOnly + resized to mobile)
+    if (!wasActive && this.isActive) {
+      this.setup()
+      this.on()
+      return
+    }
+
+    if (!this.isActive) return
+
+    if (this.infinite) {
+      // Rebuild clones and remeasure, keeping current real index visible
+      const savedIndex = this.index
+      this._setupInfinite()
+      this.index = savedIndex
+      this.current = this.target = this.setW + savedIndex * this.slideWidth
+      this._draw(this.current)
+    } else {
+      this._measure()
+      this.target = gsap.utils.clamp(0, this.limit, this.index * this.slideWidth)
+      this.current = this.target
+      this._draw(this.current)
+      this._updateProgress()
+    }
+  }
+
+  _reset() {
+    Array.from(this.el.querySelectorAll("[data-clone]")).forEach(c => c.remove())
+    this.el.style.transform = ""
+    this.current = this.target = 0
+    this.index = 0
+  }
+
+  destroy() {
+    this.off()
+    this._reset()
+    this.container = null
+    this.el = null
+  }
+
+  init() {
+    this.setup()
+    this.on()
+  }
+}

package/src/Smooth/index.js

@@ -1,4 +1,5 @@
 import Scrollbar from "../ScrollBar"
+import { gsap } from "@linear_non/stellar-kit/gsap"
 import { kitStore } from "@linear_non/stellar-kit"
 import { emitter, EVENTS } from "@linear_non/stellar-kit/events"
 import { qs, qsa, bounds, Debug } from "@linear_non/stellar-kit/utils"
@@ -24,7 +25,7 @@ export default class Smooth {
     let cursor = 0
 
     this.elems.forEach(el => {
-      el.style.transform = "translate3d(0, 0, 0)"
+      gsap.set(el, { y: 0 })
       const raw = el.dataset.speed != null ? parseFloat(el.dataset.speed) : 1
       const speed = Number.isFinite(raw) ? raw : 1
       const { height, offset } = this.getVars(el, speed)
@@ -39,6 +40,7 @@ export default class Smooth {
 
       this.sections.push({
         el,
+        ySet: gsap.quickSetter(el, "y", "px"),
         parent,
         top,
         bottom,
@@ -66,9 +68,9 @@ export default class Smooth {
     this.sections.forEach(section => {
       const { isVisible, transform } = this.isVisible(section)
       if (isVisible || isResizing || !section.out) {
-        const { y, css } = this.getTransform(transform)
+        const y = this.getY(transform)
         if (y !== section._roundedY) {
-          section.el.style.transform = css
+          section.ySet(y)
           section._roundedY = y
         }
         section.out = !isVisible
@@ -90,10 +92,9 @@ export default class Smooth {
     return { isVisible, transform }
   }
 
-  getTransform(transform) {
-    let y = -transform
-    y = Math.round(y * this.dpr) / this.dpr
-    return { y, css: `translate3d(0, ${y}px, 0)` }
+  getY(transform) {
+    const y = -transform
+    return Math.round(y * this.dpr) / this.dpr
   }
 
   getVars(el, speed) {
@@ -137,7 +138,7 @@ export default class Smooth {
   }
 
   clean() {
-    if (this.sections) this.sections.forEach(s => (s.el.style.transform = ""))
+    if (this.sections) this.sections.forEach(s => gsap.set(s.el, { y: 0, clearProps: "transform" }))
     this.elems = this.sections = null
   }
 

package/src/SpritePlayer/index.js

@@ -124,7 +124,7 @@ export default class SpritePlayer {
     this.dom.alphaImages = alphaImages
 
     if (this.isAlpha && this.dom.alphaImages.length) {
-      this.dom.alphaImages = this.dom.alphaImages.map(img => this.toAlphaFromLuma(img))
+      this.dom.alphaImages = await Promise.all(this.dom.alphaImages.map(img => this.toAlphaFromLuma(img)))
     }
     if (this.isAlpha && this.dom.alphaImages.length !== this.dom.images.length) {
       this.isAlpha = false
@@ -154,8 +154,8 @@ export default class SpritePlayer {
     Object.assign(this.canvas, { width: rect.width, height: rect.height, rect, area, offset })
   }
 
-  // grayscale → alpha (returns a canvas)
-  toAlphaFromLuma(img) {
+  // grayscale → alpha (returns an ImageBitmap; temp canvas backing store freed immediately)
+  async toAlphaFromLuma(img) {
     const w = img.naturalWidth || img.width
     const h = img.naturalHeight || img.height
     const c = document.createElement("canvas")
@@ -173,7 +173,11 @@ export default class SpritePlayer {
       a[i + 3] = lum
     }
     x.putImageData(d, 0, 0)
-    return c
+    const bitmap = await createImageBitmap(c)
+    // Release backing store — bitmap is now the only reference needed
+    c.width = 0
+    c.height = 0
+    return bitmap
   }
 
   drawImageCover(ctx, img, area, offset) {
@@ -254,6 +258,7 @@ export default class SpritePlayer {
     if (!this.persistent) {
       this._loaders.forEach(l => l.destroy?.())
     }
+    this.dom.alphaImages.forEach(bmp => bmp?.close?.())
     this.dom.images = []
     this.dom.alphaImages = []
     this._loaders = []

package/src/index.js

@@ -5,5 +5,6 @@ import Noise from "./Noise"
 import SpritePlayer from "./SpritePlayer"
 import CursorTracker from "./CursorTracker"
 import Marquee from "./Marquee"
+import Slider from "./Slider"
 
-export { Sticky, Smooth, SplitOnScroll, Noise, SpritePlayer, CursorTracker, Marquee }
+export { Sticky, Smooth, SplitOnScroll, Noise, SpritePlayer, CursorTracker, Marquee, Slider }