@linear_non/stellar-kit 1.0.0

package/README.md

@@ -0,0 +1,69 @@
+# stellar-kit
+
+A modular frontend utility kit for custom websites. Built for performance, extensibility, and clean developer ergonomics — with support for smooth scrolling, events, tick updates, mouse tracking, and layout helpers.
+
+## ✨ Features
+
+- RAF-based update loop (`Raf`)
+- Virtual scroll support (`Scroll`)
+- Smooth scrolling with transformable sections (`Smooth`)
+- Viewport-based resize tracking (`Resize`)
+- Custom scrollbar component
+- Centralized event system (`Emitter`)
+- Mouse tracking (`Mouse`)
+- Utility helpers (DOM selection, bounds, clamping, etc.)
+- Designed for use with Astro, GSAP, Three.js, and modular frontend setups
+
+## 📦 Installation
+
+```bash
+npm install stellar-kit
+# Or from GitHub:
+npm install nonlinearstudio/stellar-kit
+```
+
+## 🧱 Folder Structure
+
+```
+stellar-kit/
+├── classes/      # Core logic: Scroll, Smooth, Mouse, Scrollbar, etc.
+├── events/       # Emitter system: Raf, Resize, Scroll, Mouse, etc.
+├── utils/        # Utilities: bounds, clamp, selectors, etc.
+├── kitStore.js   # Central store shared across all modules
+└── index.js      # Entry point for setupKit and kitStore access
+```
+
+## 🧪 Local Development
+
+```bash
+npm install
+npm run dev
+```
+
+> The `dev/` folder provides a Vite playground to test modules like Smooth, Scrollbar, and events. You can import any part of the kit and prototype in isolation.
+
+## 🛠️ Usage Example
+
+```js
+// main.js or index.js of your project
+import { kitStore, setupKit } from "stellar-kit"
+
+setupKit() // Initializes Resize, Raf, Scroll, Mouse, etc.
+
+// Access anywhere
+kitStore.scroll
+kitStore.raf
+kitStore.mouse
+```
+
+You can also import from specific paths:
+
+```js
+import { bounds, clamp, qs } from "stellar-kit/utils"
+import { Manager } from "stellar-kit/classes"
+import { Raf } from "stellar-kit/events"
+```
+
+---
+
+Made with ❤️ by [Non-Linear Studio](https://non-linear.studio)

package/classes/Component.js

@@ -0,0 +1,46 @@
+// Component.js
+import { qs, bounds } from "../utils"
+
+export default class Component {
+  constructor(obj) {
+    this.el = obj.el || null
+    this.renderer = obj.renderer || null
+    const id = obj.index || 0
+    const data = obj.data || null
+
+    this.hasTick = data?.hasTick || false
+    this.hasAnimateIn = data?.hasAnimateIn || false
+    this.hasAnimateOut = data?.hasAnimateOut || false
+    this.hasAnimateOnScroll = data?.hasAnimateOnScroll || false
+
+    if (this.el) this.rect = bounds(this.el)
+  }
+
+  setup() {
+    if (!this.name) return
+    this.el = qs(`[data-${this.name}]`)
+  }
+
+  animateIn() {}
+  animateOut() {}
+  animateOnScroll() {}
+
+  tick(obj) {}
+  resize() {}
+  smoothResize() {}
+
+  on() {}
+  off() {}
+
+  destroy() {
+    this.off()
+  }
+
+  setWebgl() {}
+
+  render() {
+    this.setup()
+    this.on()
+    if (this.hasAnimateOnScroll) this.animateOnScroll()
+  }
+}

package/classes/Manager.js

@@ -0,0 +1,73 @@
+// Manager.js
+import { qsa } from "../utils"
+
+export default class Manager {
+  constructor() {
+    this.components = []
+  }
+
+  addComponent(obj, renderer) {
+    const { name, instance } = obj
+    const els = qsa(`[data-${name}]`)
+    const data = {}
+    if (els.length === 0) return
+
+    data.hasTick = obj.hasTick || false
+    data.hasAnimateIn = obj.hasAnimateIn || false
+    data.hasAnimateOut = obj.hasAnimateOut || false
+    data.hasAnimateOnScroll = obj.hasAnimateOnScroll || false
+
+    els.forEach((el, index) => {
+      const component = new instance({ index, el, data, renderer })
+      this.components.push({ name, component })
+    })
+  }
+
+  initializeComponents() {
+    this.components.forEach(({ component }) => {
+      component?.render()
+    })
+  }
+
+  animateIn() {
+    this.components.forEach(({ component }) => {
+      component.hasAnimateIn && component.animateIn()
+    })
+  }
+
+  animateOut() {
+    this.components.forEach(({ component }) => {
+      component.hasAnimateOut && component.animateOut()
+    })
+  }
+
+  animateOnScroll() {
+    this.components.forEach(({ component }) => {
+      component.hasAnimateOnScroll && component.animateOnScroll()
+    })
+  }
+
+  update(obj) {
+    this.components.forEach(({ component }) => {
+      component.hasTick && component.tick(obj)
+    })
+  }
+
+  resize() {
+    this.components.forEach(({ component }) => {
+      component?.resize()
+    })
+  }
+
+  smoothResize() {
+    this.components.forEach(({ component }) => {
+      component?.smoothResize()
+    })
+  }
+
+  destroy() {
+    this.components.forEach(({ component }) => {
+      component?.destroy()
+    })
+  }
+}

package/classes/Scrollbar.js

@@ -0,0 +1,124 @@
+import kitStore from "../kitStore"
+import { emitter, EVENTS, Raf } from "../events"
+
+export default class Scrollbar {
+  constructor(obj) {
+    this.container = obj.container || document.body
+    this.el = null
+    this.handle = null
+    this.touching = false
+
+    this.state = {
+      clicked: false,
+      scale: 0,
+      current: 0,
+    }
+    this.height = 0
+    this.init()
+  }
+
+  init() {
+    this.create()
+    this.setBounds()
+    this.on()
+  }
+
+  on() {
+    emitter.on(EVENTS.APP_TICK, this.tick)
+    emitter.on(EVENTS.APP_RESIZE, this.resize)
+    this.handle.addEventListener("mousedown", this.mouseDown)
+    window.addEventListener("mouseup", this.mouseUp)
+    window.addEventListener("mousemove", this.mouseMove)
+  }
+
+  off() {
+    emitter.off(EVENTS.APP_TICK, this.tick)
+    emitter.off(EVENTS.APP_RESIZE, this.resize)
+    this.handle.removeEventListener("mousedown", this.mouseDown)
+    window.removeEventListener("mouseup", this.mouseUp)
+    window.removeEventListener("mousemove", this.mouseMove)
+  }
+
+  mouseDown = () => {
+    this.touching = true
+    document.body.style.userSelect = "none"
+    document.body.style.webkitUserSelect = "none"
+    document.body.style.pointerEvents = "none"
+  }
+
+  mouseUp = () => {
+    this.touching = false
+    document.body.style.userSelect = "inherit"
+    document.body.style.webkitUserSelect = "inherit"
+    document.body.style.pointerEvents = "inherit"
+  }
+
+  mouseMove = e => {
+    if (this.touching === true) {
+      const { isLocked } = kitStore.flags
+
+      if (isLocked) return
+
+      kitStore.raf.scroll.target = e.clientY * this.state.scale
+      kitStore.raf.clamp()
+    }
+  }
+
+  setBounds() {
+    const { vh, fh } = kitStore.sizes
+    const scrollLimit = fh
+    this.state.scale = (scrollLimit + vh) / vh
+    this.handle.style.height = `${vh / this.state.scale}px`
+  }
+
+  tick = ({ current }) => {
+    const scroll = current / this.state.scale
+    this.state.current = scroll
+    this.handle.style.transform = `translate3d(0, ${this.state.current}px, 0)`
+  }
+
+  resize = () => {
+    this.setBounds()
+  }
+
+  calcScroll(e) {
+    const delta = e.clientY * this.state.scale
+    Raf.target = delta
+    Raf.clampTarget()
+  }
+
+  create() {
+    this.el = document.createElement("div")
+    this.handle = document.createElement("div")
+    this.el.classList.add("scrollbar")
+    this.handle.classList.add("handle")
+
+    Object.assign(this.el.style, {
+      position: "fixed",
+      top: 0,
+      right: 0,
+      height: "100%",
+      pointerEvents: "all",
+    })
+
+    Object.assign(this.handle.style, {
+      position: "absolute",
+      top: 0,
+      left: 0,
+      width: "100%",
+      cursor: "pointer",
+      zIndex: 101,
+    })
+
+    this.container.appendChild(this.el)
+    this.el.appendChild(this.handle)
+  }
+
+  update() {
+    this.setBounds()
+  }
+
+  destroy() {
+    this.off()
+  }
+}

package/classes/Smooth.js

@@ -0,0 +1,146 @@
+// Smooth.js
+import kitStore from "../kitStore"
+import Scrollbar from "./Scrollbar"
+import { emitter, EVENTS } from "../events"
+import { qs, qsa, bounds } from "../utils"
+
+export default class Smooth {
+  constructor(obj) {
+    this.scroll = obj.scroll
+    this.el = qs("[data-view]")
+    this.elems = null
+    this.current = 0
+    this.threshold = 100
+    this.sections = null
+    this.scrollbar = null
+    this.init()
+  }
+
+  getSections() {
+    const { isSmooth } = kitStore.flags
+    if (!this.elems || !isSmooth) return
+
+    this.sections = []
+    this.elems.forEach(el => {
+      el.style.transform = "translate3d(0, 0, 0)"
+      const speed = el.dataset.speed || 1
+      const { top, bottom, offset } = this.getVars(el, speed)
+      let parent = el.parentNode.closest("[data-smooth]")
+
+      if (parent) {
+        this.sections.some(obj => {
+          if (obj.el === parent) parent = obj
+        })
+      }
+
+      this.sections.push({
+        el,
+        parent,
+        top,
+        bottom,
+        offset,
+        speed,
+        out: true,
+        transform: 0,
+      })
+    })
+  }
+
+  tick = ({ current }) => {
+    this.current = current
+    this.transformSections()
+  }
+
+  transformSections() {
+    const { isSmooth, isResizing } = kitStore.flags
+    if (!this.sections || !isSmooth) return
+
+    this.sections.forEach(section => {
+      const { isVisible, transform } = this.isVisible(section)
+
+      if (isVisible || isResizing || !section.out) {
+        section.out = !isVisible
+        section.transform = transform
+        section.el.style.transform = this.getTransform(transform)
+      }
+    })
+  }
+
+  isVisible(section) {
+    const { vh } = kitStore.sizes
+    const { top, bottom, offset, speed, parent } = section
+
+    const extra = (parent && parent.transform) || 0
+    const translate = this.current * speed
+    const transform = translate - offset - extra
+    const start = top - translate
+    const end = bottom - translate
+    const isVisible = start < this.threshold + vh && end > -this.threshold
+
+    return { isVisible, transform }
+  }
+
+  getTransform(transform) {
+    return `translate3d(0, ${-transform}px, 0)`
+  }
+
+  getVars(el, speed) {
+    const { vh } = kitStore.sizes
+    const rect = bounds(el)
+    const centering = vh / 2 - rect.height / 2
+    const offset = rect.top < vh ? 0 : (rect.top - centering) * speed - (rect.top - centering)
+
+    return {
+      top: rect.top + offset,
+      bottom: rect.bottom + offset,
+      offset,
+    }
+  }
+
+  resize = () => {
+    if (!this.sections) return
+
+    this.sections.forEach(section => {
+      section.el.style.transform = "translate3d(0, 0, 0)"
+      const { top, bottom, offset } = this.getVars(section.el, section.speed)
+      Object.assign(section, { top, bottom, offset })
+    })
+
+    emitter.emit(EVENTS.APP_SMOOTH_RESIZE)
+    this.transformSections()
+  }
+
+  update(elems) {
+    kitStore.flags.isResizing = true
+
+    this.scroll.setScrollBounds()
+    this.elems = elems || qsa("[data-smooth]")
+    this.scrollbar.update()
+    this.getSections()
+    this.transformSections()
+
+    kitStore.flags.isResizing = false
+  }
+
+  clean() {
+    this.elems = this.sections = null
+  }
+
+  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)
+  }
+
+  init(elems) {
+    this.elems = elems || qsa("[data-smooth]")
+    this.getSections()
+    this.scrollbar = new Scrollbar(this.current)
+    this.on()
+    this.update()
+  }
+}

package/classes/index.js

@@ -0,0 +1,6 @@
+import Component from "./Component"
+import Manager from "./Manager"
+import Smooth from "./Smooth"
+import Scrollbar from "./Scrollbar"
+
+export { Component, Manager, Smooth, Scrollbar }

package/events/Emitter.js

@@ -0,0 +1,67 @@
+// Emitter.js
+class Emitter {
+  constructor() {
+    this.events = {}
+  }
+
+  emit(event, ...args) {
+    const callbacks = this.events[event] || []
+    for (let i = 0, { length } = callbacks; i < length; i++) {
+      callbacks[i].cb(...args)
+    }
+  }
+
+  on(event, cb, priority = 0) {
+    const data = { cb, priority }
+    this.events[event]?.push(data) || (this.events[event] = [data])
+    this.events[event].sort((a, b) => a.priority - b.priority)
+    return () => {
+      this.events[event] = this.events[event]?.filter(v => cb !== v.cb)
+    }
+  }
+
+  off(event, callback) {
+    this.events[event] = this.events[event]?.filter(({ cb }) => callback !== cb)
+  }
+
+  once(event, cb, priority = 0) {
+    const onceCallback = (...args) => {
+      cb(...args)
+      this.off(event, onceCallback)
+    }
+
+    this.on(event, onceCallback, priority)
+
+    return () => {
+      this.off(event, cb)
+    }
+  }
+
+  destroy() {
+    this.events = {}
+  }
+}
+
+const emitter = new Emitter()
+
+const EVENTS = {
+  APP_TICK: "tick",
+  APP_RESIZE: "resize",
+  APP_SMOOTH_RESIZE: "smooth:resize",
+  APP_SCROLL: "scroll",
+  APP_MOUSEMOVE: "mousemove",
+  APP_MOUSEDOWN: "mousedown",
+  APP_MOUSEUP: "mouseup",
+  APP_SPLITTEXT_READY: "splittext:ready",
+}
+
+const PRIORITY = {
+  first: -10,
+  instant: 0,
+  high: 10,
+  mid: 20,
+  low: 30,
+}
+
+export { EVENTS, PRIORITY }
+export default emitter

package/events/Mouse.js

@@ -0,0 +1,60 @@
+// Mouse.js
+import emitter, { EVENTS } from "./Emitter"
+import { sniffer } from "../utils"
+
+export default class Mouse {
+  constructor() {
+    this.state = {
+      on: 0,
+      off: 0,
+      coords: { x: 0, y: 0 },
+    }
+
+    this.events = {
+      move: sniffer.isDevice ? "touchmove" : "mousemove",
+      down: sniffer.isDevice ? "touchstart" : "mousedown",
+      up: sniffer.isDevice ? "touchend" : "mouseup",
+    }
+
+    this.on()
+  }
+
+  on() {
+    const { move, down, up } = this.events
+    window.addEventListener(move, this.onMove)
+    window.addEventListener(down, this.onDown)
+    window.addEventListener(up, this.onUp)
+  }
+
+  off() {
+    const { move, down, up } = this.events
+    window.removeEventListener(move, this.onMove)
+    window.removeEventListener(down, this.onDown)
+    window.removeEventListener(up, this.onUp)
+  }
+
+  getPos(e) {
+    const x = e.changedTouches ? e.changedTouches[0].clientX : e.clientX
+    const y = e.changedTouches ? e.changedTouches[0].clientY : e.clientY
+    const target = e.target
+    return { x, y, target }
+  }
+
+  onMove = e => {
+    const { x, y, target } = this.getPos(e)
+    emitter.emit(EVENTS.APP_MOUSEMOVE, { x, y, target, e })
+  }
+
+  onDown = e => {
+    const { x, y, target } = this.getPos(e)
+    this.state.on = x
+    emitter.emit(EVENTS.APP_MOUSEDOWN, { x, y, target })
+  }
+
+  onUp = e => {
+    const { x, target } = this.getPos(e)
+    this.state.off = x
+    const isClick = Math.abs(this.state.on - this.state.off) > 10
+    emitter.emit(EVENTS.APP_MOUSEUP, { x, target, isClick })
+  }
+}

package/events/Raf.js

@@ -0,0 +1,122 @@
+// Raf.js
+import kitStore from "../kitStore"
+import emitter, { EVENTS } from "./Emitter"
+import { sniffer, lerp } from "../utils"
+import { gsap, ScrollTrigger } from "../libraries/gsap"
+
+export default class Raf {
+  constructor() {
+    this.scroll = {
+      target: 0,
+      current: 0,
+      rounded: 0,
+      ease: 0.115,
+    }
+
+    this.mouse = {
+      x: 0,
+      y: 0,
+      target: null,
+    }
+
+    this.setScrollTrigger()
+    this.on()
+  }
+
+  tick = () => {
+    const { target, current, ease } = this.scroll
+
+    this.scroll.current = lerp(current, target, ease)
+    this.scroll.rounded = Math.round(this.scroll.current * 100) / 100
+    this.diff = (target - this.scroll.current) * 0.005
+
+    emitter.emit(EVENTS.APP_TICK, {
+      target,
+      current: this.getScroll(),
+      mouse: this.mouse,
+      diff: this.diff,
+    })
+
+    ScrollTrigger.update()
+  }
+
+  getScroll() {
+    const { pageContent } = kitStore
+    return sniffer.isDevice ? pageContent.parentNode.scrollTop : this.scroll.rounded
+  }
+
+  clamp() {
+    const { fh } = kitStore.sizes
+    this.scroll.target = Math.min(Math.max(this.scroll.target, 0), fh)
+  }
+
+  onScroll = ({ y }) => {
+    if (kitStore.flags.isLocked) return
+    this.scroll.target += y
+    this.clamp()
+  }
+
+  onMouseMove = ({ x, y, target }) => {
+    this.mouse.x = x
+    this.mouse.y = y
+    this.mouse.target = target
+  }
+
+  scrollTo(offset) {
+    if (kitStore.flags.isSmooth) {
+      gsap.to(this.scroll, {
+        target: offset,
+        duration: 1,
+        ease: "expo.inOut",
+      })
+    } else {
+      window.scrollTo({ top: offset, left: 0, behavior: "smooth" })
+    }
+  }
+
+  setScroll(offset) {
+    if (kitStore.flags.isSmooth) {
+      gsap.set(this.scroll, {
+        target: offset,
+        current: offset,
+        rounded: offset,
+      })
+    } else {
+      window.scrollTo({ top: offset, left: 0 })
+    }
+  }
+
+  setScrollTrigger() {
+    const { pageContent } = kitStore
+
+    ScrollTrigger.defaults({
+      scroller: pageContent,
+    })
+
+    ScrollTrigger.scrollerProxy(pageContent, {
+      scrollTop: () => {
+        return this.smooth()
+      },
+      getBoundingClientRect() {
+        // Important that width and height are dynamic
+        return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight }
+      },
+    })
+  }
+
+  on() {
+    gsap.ticker.add(this.tick)
+    emitter.on(EVENTS.APP_SCROLL, this.onScroll)
+    emitter.on(EVENTS.APP_MOUSEMOVE, this.onMouseMove)
+  }
+
+  off() {
+    gsap.ticker.remove(this.tick)
+    emitter.off(EVENTS.APP_SCROLL, this.onScroll)
+    emitter.off(EVENTS.APP_MOUSEMOVE, this.onMouseMove)
+  }
+
+  destroy() {
+    this.off()
+  }
+}