scroll-snap-kit 1.0.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabian Faraz Farid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,10 @@
 
 Zero dependencies. Tree-shakeable. Works with or without React.
 
+[![npm version](https://img.shields.io/npm/v/scroll-snap-kit)](https://www.npmjs.com/package/scroll-snap-kit)
+[![license](https://img.shields.io/npm/l/scroll-snap-kit)](./LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/scroll-snap-kit)](https://bundlephobia.com/package/scroll-snap-kit)
+
 ---
 
 ## Install
@@ -14,27 +18,65 @@ npm install scroll-snap-kit
 
 ---
 
+## What's included
+
+| Utility | Description |
+|---------|-------------|
+| `scrollTo` | Smooth scroll to an element or pixel value |
+| `scrollToTop` / `scrollToBottom` | Page-level scroll helpers |
+| `getScrollPosition` | Current scroll x/y + percentages |
+| `onScroll` | Throttled scroll listener with cleanup |
+| `isInViewport` | Check if an element is visible |
+| `lockScroll` / `unlockScroll` | Freeze body scroll, restore position |
+| `scrollSpy` | Highlight nav links based on active section |
+| `onScrollEnd` | Fire a callback when scrolling stops |
+| `scrollIntoViewIfNeeded` | Only scroll if element is off-screen |
+| `easeScroll` + `Easings` | Custom easing curves for scroll animation |
+| `scrollSequence` | Chain multiple scroll animations in order |
+| `parallax` | Attach parallax speed multipliers to elements |
+| `scrollProgress` | Track how far through an element the user has scrolled |
+| `snapToSection` | Auto-snap to the nearest section after scrolling stops |
+
+| Hook | Description |
+|------|-------------|
+| `useScrollPosition` | Live scroll position + percentage |
+| `useInViewport` | Whether a ref'd element is visible |
+| `useScrollTo` | Scroll function scoped to a container ref |
+| `useScrolledPast` | Boolean — has user scrolled past a threshold |
+| `useScrollDirection` | `'up'` \| `'down'` \| `null` |
+
+---
+
 ## Vanilla JS Utilities
 
 ```js
-import { scrollTo, scrollToTop, scrollToBottom, getScrollPosition, onScroll, isInViewport, lockScroll, unlockScroll } from 'scroll-snap-kit/utils';
+import {
+  scrollTo, scrollToTop, scrollToBottom,
+  getScrollPosition, onScroll, isInViewport,
+  lockScroll, unlockScroll,
+  scrollSpy, onScrollEnd, scrollIntoViewIfNeeded,
+  easeScroll, Easings,
+  scrollSequence, parallax, scrollProgress, snapToSection
+} from 'scroll-snap-kit';
 ```
 
+---
+
 ### `scrollTo(target, options?)`
 
 Smoothly scroll to a DOM element or a Y pixel value.
 
 ```js
 scrollTo(document.querySelector('#section'));
-scrollTo(500);                                          // scroll to y=500px
-scrollTo(document.querySelector('#hero'), { offset: -80 }); // with offset (e.g. sticky header)
+scrollTo(500);                                               // scroll to y=500px
+scrollTo(document.querySelector('#hero'), { offset: -80 }); // offset for sticky headers
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `behavior` | `'smooth' \| 'instant'` | `'smooth'` | Scroll behavior |
 | `block` | `ScrollLogicalPosition` | `'start'` | Vertical alignment |
-| `offset` | `number` | `0` | Pixel offset adjustment |
+| `offset` | `number` | `0` | Pixel offset (e.g. `-80` for a sticky nav) |
 
 ---
 
@@ -49,9 +91,13 @@ scrollToBottom({ behavior: 'instant' });
 
 ### `getScrollPosition(container?)`
 
+Returns the current scroll position and scroll percentage for the page or any scrollable container.
+
 ```js
 const { x, y, percentX, percentY } = getScrollPosition();
-// percentY = how far down the page (0–100)
+// percentY → how far down the page (0–100)
+
+const pos = getScrollPosition(document.querySelector('.sidebar'));
 ```
 
 ---
@@ -61,14 +107,18 @@ const { x, y, percentX, percentY } = getScrollPosition();
 Throttled scroll listener. Returns a cleanup function.
 
 ```js
-const stop = onScroll(({ y, percentY }) => {
+const stop = onScroll(({ x, y, percentX, percentY }) => {
   console.log(`Scrolled ${percentY}% down`);
-}, { throttle: 150 });
+}, { throttle: 100 });
 
-// Later:
 stop(); // removes the listener
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `throttle` | `number` | `100` | Minimum ms between callbacks |
+| `container` | `Element` | `window` | Scrollable container to listen on |
+
 ---
 
 ### `isInViewport(element, options?)`
@@ -79,76 +129,259 @@ if (isInViewport(document.querySelector('.card'), { threshold: 0.5 })) {
 }
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `threshold` | `number` | `0` | 0–1 portion of element that must be visible |
+
 ---
 
 ### `lockScroll()` / `unlockScroll()`
 
-Lock page scroll (e.g. when a modal is open) and restore position on unlock.
+```js
+lockScroll();   // body stops scrolling, position saved
+unlockScroll(); // position restored precisely — no layout jump
+```
+
+---
+
+### `scrollSpy(sectionsSelector, linksSelector, options?)`
+
+Watches scroll position and automatically adds an active class to the nav link matching the current section.
+
+```js
+const stop = scrollSpy(
+  'section[id]',
+  'nav a',
+  { offset: 80, activeClass: 'scroll-spy-active' }
+);
+
+stop(); // remove listener
+```
+
+```css
+nav a.scroll-spy-active {
+  color: #00ffaa;
+  border-bottom: 1px solid currentColor;
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `offset` | `number` | `0` | px from top to trigger section change |
+| `activeClass` | `string` | `'scroll-spy-active'` | Class added to the active link |
+
+---
+
+### `onScrollEnd(callback, options?)`
+
+Fires once the user has stopped scrolling for a configurable delay.
+
+```js
+const stop = onScrollEnd(() => {
+  console.log('User stopped scrolling!');
+  saveScrollPosition();
+}, { delay: 200 });
+
+stop();
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `delay` | `number` | `150` | ms of idle scrolling before callback fires |
+| `container` | `Element` | `window` | Scrollable container to watch |
+
+---
+
+### `scrollIntoViewIfNeeded(element, options?)`
+
+Scrolls to an element only if it is outside the visible viewport. If it's already visible enough, nothing happens.
+
+```js
+scrollIntoViewIfNeeded(document.querySelector('.card'));
+scrollIntoViewIfNeeded(element, { threshold: 0.5, offset: -80 });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `threshold` | `number` | `1` | 0–1 visibility ratio required to skip scrolling |
+| `offset` | `number` | `0` | Pixel offset applied when scrolling |
+| `behavior` | `'smooth' \| 'instant'` | `'smooth'` | Scroll behavior |
+
+---
+
+### `easeScroll(target, options?)` + `Easings`
+
+Scroll to a position with a fully custom easing curve. Returns a `Promise` that resolves when animation completes.
+
+```js
+await easeScroll('#contact', { duration: 800, easing: Easings.easeOutElastic });
+
+// Chain animations
+await easeScroll('#hero',     { duration: 600, easing: Easings.easeInOutCubic });
+await easeScroll('#features', { duration: 400, easing: Easings.easeOutQuart });
+
+// BYO easing function — any (t: 0→1) => (0→1)
+easeScroll(element, { easing: t => t * t * t });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `duration` | `number` | `600` | Animation duration in ms |
+| `easing` | `(t: number) => number` | `Easings.easeInOutCubic` | Easing function |
+| `offset` | `number` | `0` | Pixel offset applied to target |
+
+**Built-in easings:** `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeOutElastic`, `easeOutBounce`
+
+---
+
+### `scrollSequence(steps)`
+
+Run multiple `easeScroll` animations one after another as a choreographed sequence. Supports pauses between steps. Returns `{ promise, cancel }`.
+
+```js
+const { promise, cancel } = scrollSequence([
+  { target: '#intro',    duration: 600 },
+  { target: '#features', duration: 800, pause: 400 },  // pause 400ms before next step
+  { target: '#pricing',  duration: 600, easing: Easings.easeOutElastic },
+]);
+
+await promise;       // resolves when all steps complete
+cancel();            // abort at any point mid-sequence
+```
+
+| Step option | Type | Default | Description |
+|-------------|------|---------|-------------|
+| `target` | `Element \| string \| number` | — | Scroll destination (required) |
+| `duration` | `number` | `600` | Duration of this step in ms |
+| `easing` | `Function` | `easeInOutCubic` | Easing for this step |
+| `offset` | `number` | `0` | Pixel offset |
+| `pause` | `number` | `0` | ms to wait after this step before the next |
+
+---
+
+### `parallax(targets, options?)`
+
+Attach a parallax scroll effect to one or more elements. Each element moves relative to its original position at the given `speed` multiplier.
+
+```js
+// speed < 1 = moves slower than scroll (background feel)
+// speed > 1 = moves faster than scroll (foreground feel)
+// speed < 0 = moves in the opposite direction to scroll
+
+const destroy = parallax('.hero-bg', { speed: 0.4 });
+const destroy = parallax('.clouds',  { speed: -0.2, axis: 'x' });
+const destroy = parallax([el1, el2], { speed: 0.6, axis: 'both' });
+
+destroy(); // removes the effect and resets all transforms
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `speed` | `number` | `0.5` | Movement multiplier |
+| `axis` | `'y' \| 'x' \| 'both'` | `'y'` | Axis to apply parallax on |
+| `container` | `Element` | `window` | Scrollable container |
+
+---
+
+### `scrollProgress(element, callback, options?)`
+
+Track how far the user has scrolled through a specific element, independent of overall page progress.
+
+- `0` = element top just entered the bottom of the viewport
+- `1` = element bottom just exited the top of the viewport
 
 ```js
-lockScroll();   // body stops scrolling
-unlockScroll(); // restored to previous position
+const stop = scrollProgress('#article', (progress) => {
+  progressBar.style.width = `${progress * 100}%`;
+  if (progress === 1) console.log('Article fully read!');
+});
+
+stop(); // cleanup
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `offset` | `number` | `0` | Pixel adjustment to progress calculation |
+
+---
+
+### `snapToSection(sections, options?)`
+
+After the user stops scrolling, automatically snap to the nearest section. Returns a destroy function.
+
+```js
+const destroy = snapToSection('section[id]', {
+  delay: 150,                        // ms to wait after scroll stops (default: 150)
+  offset: -70,                       // account for sticky nav (default: 0)
+  duration: 500,                     // snap animation duration (default: 500)
+  easing: Easings.easeInOutCubic     // snap animation easing
+});
+
+destroy(); // remove snap behaviour
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `delay` | `number` | `150` | ms after scrolling stops before snap fires |
+| `offset` | `number` | `0` | Pixel offset applied to snap target |
+| `duration` | `number` | `500` | Snap animation duration in ms |
+| `easing` | `Function` | `Easings.easeInOutCubic` | Snap animation easing |
+
+> Works on both window scroll and scrollable containers. Pass an array of elements instead of a selector for more control.
+
 ---
 
 ## React Hooks
 
 ```js
-import { useScrollPosition, useInViewport, useScrollTo, useScrolledPast, useScrollDirection } from 'scroll-snap-kit/hooks';
+import {
+  useScrollPosition, useInViewport, useScrollTo,
+  useScrolledPast, useScrollDirection
+} from 'scroll-snap-kit/hooks';
 ```
 
+> Requires React 16.8+. React is a peer dependency — install it separately.
+
+---
+
 ### `useScrollPosition(options?)`
 
 ```jsx
 function ProgressBar() {
   const { percentY } = useScrollPosition({ throttle: 50 });
-  return <div style={{ width: `${percentY}%` }} className="progress" />;
+  return <div style={{ width: `${percentY}%` }} className="progress-bar" />;
 }
 ```
 
----
-
 ### `useInViewport(options?)`
 
 ```jsx
-function FadeIn() {
+function FadeInCard() {
   const [ref, inView] = useInViewport({ threshold: 0.2, once: true });
   return (
     <div ref={ref} style={{ opacity: inView ? 1 : 0, transition: 'opacity 0.5s' }}>
-      I fade in when visible!
+      Fades in when visible!
     </div>
   );
 }
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `threshold` | `number` | `0` | 0–1 portion of element visible to trigger |
-| `once` | `boolean` | `false` | Only trigger the first time |
-
----
-
 ### `useScrollTo()`
 
 ```jsx
 function Page() {
   const [containerRef, scrollToTarget] = useScrollTo();
   const sectionRef = useRef(null);
-
   return (
     <div ref={containerRef} style={{ overflowY: 'scroll', height: '400px' }}>
-      <button onClick={() => scrollToTarget(sectionRef.current)}>Jump to section</button>
-      <div style={{ height: 300 }} />
-      <div ref={sectionRef}>Target section</div>
+      <button onClick={() => scrollToTarget(sectionRef.current)}>Jump</button>
+      <div ref={sectionRef}>Target</div>
     </div>
   );
 }
 ```
 
----
-
-### `useScrolledPast(threshold?, options?)`
+### `useScrolledPast(threshold?)`
 
 ```jsx
 function BackToTopButton() {
@@ -157,12 +390,10 @@ function BackToTopButton() {
 }
 ```
 
----
-
 ### `useScrollDirection()`
 
 ```jsx
-function Navbar() {
+function HideOnScrollNav() {
   const direction = useScrollDirection();
   return (
     <nav style={{ transform: direction === 'down' ? 'translateY(-100%)' : 'translateY(0)' }}>
@@ -172,10 +403,45 @@ function Navbar() {
 }
 ```
 
-Returns `'up'`, `'down'`, or `null` (on initial render).
+---
+
+## Tree-shaking
+
+All exports are named and side-effect free:
+
+```js
+import { scrollToTop } from 'scroll-snap-kit';             // ~400 bytes
+import { onScroll, scrollSpy } from 'scroll-snap-kit/utils';
+import { useScrollPosition } from 'scroll-snap-kit/hooks';
+```
+
+---
+
+## Browser support
+
+All modern browsers. `easeScroll` and `scrollSequence` use `requestAnimationFrame`. `useInViewport` / `isInViewport` use `IntersectionObserver` — polyfill if you need IE11.
+
+---
+
+## Changelog
+
+### v1.2.0
+- ✨ `scrollSequence()` — chain multiple scroll animations with pauses and cancel support
+- ✨ `parallax()` — multi-element parallax with configurable speed, axis, and cleanup
+- ✨ `scrollProgress()` — per-element scroll progress tracking (0→1)
+- ✨ `snapToSection()` — auto-snap to nearest section after scrolling stops
+
+### v1.1.0
+- ✨ `scrollSpy()` — highlight nav links by active section
+- ✨ `onScrollEnd()` — callback when scrolling stops
+- ✨ `scrollIntoViewIfNeeded()` — scroll only when off-screen
+- ✨ `easeScroll()` + `Easings` — custom easing engine with 11 built-in curves
+
+### v1.0.0
+- 🎉 Initial release — 8 core utilities and 5 React hooks
 
 ---
 
 ## License
 
-MIT
+MIT © Fabian Faraz Farid