npm package: @linear_non/stellar-libs
Description: Reusable JavaScript libraries for Non-Linear Studio projects.
Author: Non-Linear Studio
Latest version: 1.4.5

# stellar-libs

> `@linear_non/stellar-libs` — Reusable UI behavior modules for Non-Linear Studio projects.

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.

## Available Libraries

| 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
```

## Local Development

```bash
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),
})
```

### Smooth

```js
import { Smooth } from "@linear_non/stellar-libs"

const smooth = new Smooth({ scroll: kitStore.scroll })
```

```html
<section data-smooth data-speed="0.8">Parallax content</section>
```

### SplitOnScroll

```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,
})
```

> The constructor key is `splitText` (not `splitTargets`). The `isReady` callback receives `{ splits, groups }`.

### Noise

```js
import { Noise } from "@linear_non/stellar-libs"

const noise = new Noise({
  target: ".noise-canvas",
  density: 0.75,
  color: 0xf3f2feff,
  opacity: 0.25,
  fps: 24,
})
```

### 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",
})
```

### 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,
  activeBelow: 'mediumUp', // only active below the mediumUp breakpoint; mobileOnly:true is an alias
  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>
```

---

## Roadmap

- [ ] TypeScript definitions (`.d.ts` for all 8 libraries)
- [ ] Unit test suite (per-library Jest tests)
- [ ] Accessibility — ARIA attributes + keyboard support (Slider, Marquee, CursorTracker)
- [ ] Animation presets — exportable GSAP timeline builders per library
- [ ] Performance monitoring — FPS tracking integrated with stellar-kit `?debug`
- [ ] Storybook interactive docs
- [ ] Plugin system — `.use(plugin)` extension API

## Lifecycle

All libraries follow a consistent class-based lifecycle: `init() → on() → tick() → resize() → off() → destroy()`

Always call `destroy()` on page navigation to clean up event listeners, animations, and timers.

---

Made with ❤️ by [Non-Linear Studio](https://non-linear.studio)