scroll-snap-kit 1.1.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

@@ -32,6 +32,10 @@ npm install scroll-snap-kit
 | `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 |
 |------|-------------|
@@ -51,7 +55,8 @@ import {
   getScrollPosition, onScroll, isInViewport,
   lockScroll, unlockScroll,
   scrollSpy, onScrollEnd, scrollIntoViewIfNeeded,
-  easeScroll, Easings
+  easeScroll, Easings,
+  scrollSequence, parallax, scrollProgress, snapToSection
 } from 'scroll-snap-kit';
 ```
 
@@ -92,7 +97,6 @@ Returns the current scroll position and scroll percentage for the page or any sc
 const { x, y, percentX, percentY } = getScrollPosition();
 // percentY → how far down the page (0–100)
 
-// Works on containers too
 const pos = getScrollPosition(document.querySelector('.sidebar'));
 ```
 
@@ -100,7 +104,7 @@ const pos = getScrollPosition(document.querySelector('.sidebar'));
 
 ### `onScroll(callback, options?)`
 
-Throttled scroll listener. Returns a cleanup function to stop listening.
+Throttled scroll listener. Returns a cleanup function.
 
 ```js
 const stop = onScroll(({ x, y, percentX, percentY }) => {
@@ -119,8 +123,6 @@ stop(); // removes the listener
 
 ### `isInViewport(element, options?)`
 
-Check whether an element is currently visible in the viewport.
-
 ```js
 if (isInViewport(document.querySelector('.card'), { threshold: 0.5 })) {
   // At least 50% of the card is visible
@@ -135,47 +137,44 @@ if (isInViewport(document.querySelector('.card'), { threshold: 0.5 })) {
 
 ### `lockScroll()` / `unlockScroll()`
 
-Lock page scroll (e.g. when a modal is open) and restore the exact position on unlock — no layout jump.
-
 ```js
 lockScroll();   // body stops scrolling, position saved
-unlockScroll(); // position restored precisely
+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. Returns a cleanup function.
+Watches scroll position and automatically adds an active class to the nav link matching the current section.
 
 ```js
 const stop = scrollSpy(
-  'section[id]',           // sections to spy on
-  'nav a',                 // nav links to highlight
-  {
-    offset: 80,                        // px from top to trigger (default: 0)
-    activeClass: 'scroll-spy-active'   // class to toggle (default: 'scroll-spy-active')
-  }
+  'section[id]',
+  'nav a',
+  { offset: 80, activeClass: 'scroll-spy-active' }
 );
 
-stop(); // remove the listener
+stop(); // remove listener
 ```
 
 ```css
-/* Style the active link however you like */
 nav a.scroll-spy-active {
   color: #00ffaa;
   border-bottom: 1px solid currentColor;
 }
 ```
 
-> Links are matched by comparing their `href` to `#sectionId`. Call `scrollSpy` multiple times to target different link groups simultaneously.
+| 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 a callback once the user has stopped scrolling for a configurable delay. Great for lazy-loading, analytics, or autosave.
+Fires once the user has stopped scrolling for a configurable delay.
 
 ```js
 const stop = onScrollEnd(() => {
@@ -183,7 +182,7 @@ const stop = onScrollEnd(() => {
   saveScrollPosition();
 }, { delay: 200 });
 
-stop(); // cleanup
+stop();
 ```
 
 | Option | Type | Default | Description |
@@ -195,13 +194,10 @@ stop(); // cleanup
 
 ### `scrollIntoViewIfNeeded(element, options?)`
 
-Scrolls to an element only if it is partially or fully outside the visible viewport. If it's already visible enough, nothing happens — no unnecessary scroll.
+Scrolls to an element only if it is outside the visible viewport. If it's already visible enough, nothing happens.
 
 ```js
-// Only scrolls if the element is off-screen
 scrollIntoViewIfNeeded(document.querySelector('.card'));
-
-// threshold: how much must be visible before we skip scrolling
 scrollIntoViewIfNeeded(element, { threshold: 0.5, offset: -80 });
 ```
 
@@ -215,14 +211,10 @@ scrollIntoViewIfNeeded(element, { threshold: 0.5, offset: -80 });
 
 ### `easeScroll(target, options?)` + `Easings`
 
-Scroll to a position with a fully custom easing curve, bypassing the browser's native smooth scroll. Returns a `Promise` that resolves when the animation completes.
+Scroll to a position with a fully custom easing curve. Returns a `Promise` that resolves when animation completes.
 
 ```js
-// Use a built-in easing
-await easeScroll('#contact', {
-  duration: 800,
-  easing: Easings.easeOutElastic
-});
+await easeScroll('#contact', { duration: 800, easing: Easings.easeOutElastic });
 
 // Chain animations
 await easeScroll('#hero',     { duration: 600, easing: Easings.easeInOutCubic });
@@ -236,37 +228,115 @@ easeScroll(element, { easing: t => t * t * t });
 |--------|------|---------|-------------|
 | `duration` | `number` | `600` | Animation duration in ms |
 | `easing` | `(t: number) => number` | `Easings.easeInOutCubic` | Easing function |
-| `offset` | `number` | `0` | Pixel offset applied to target position |
+| `offset` | `number` | `0` | Pixel offset applied to target |
+
+**Built-in easings:** `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeOutElastic`, `easeOutBounce`
+
+---
+
+### `scrollSequence(steps)`
 
-**Built-in easings:**
+Run multiple `easeScroll` animations one after another as a choreographed sequence. Supports pauses between steps. Returns `{ promise, cancel }`.
 
 ```js
-import { Easings } from 'scroll-snap-kit';
-
-Easings.linear
-Easings.easeInQuad
-Easings.easeOutQuad
-Easings.easeInOutQuad
-Easings.easeInCubic
-Easings.easeOutCubic
-Easings.easeInOutCubic   // ← default
-Easings.easeInQuart
-Easings.easeOutQuart
-Easings.easeOutElastic   // springy overshoot
-Easings.easeOutBounce    // bouncy landing
+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
+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
+  useScrollPosition, useInViewport, useScrollTo,
+  useScrolledPast, useScrollDirection
 } from 'scroll-snap-kit/hooks';
 ```
 
@@ -276,129 +346,71 @@ import {
 
 ### `useScrollPosition(options?)`
 
-Returns the current scroll position, updated live on scroll.
-
 ```jsx
 function ProgressBar() {
-  const { x, y, percentX, percentY } = useScrollPosition({ throttle: 50 });
+  const { percentY } = useScrollPosition({ throttle: 50 });
   return <div style={{ width: `${percentY}%` }} className="progress-bar" />;
 }
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `throttle` | `number` | `100` | ms between updates |
-| `container` | `Element` | `window` | Scrollable container |
-
----
-
 ### `useInViewport(options?)`
 
-Returns a `[ref, inView]` tuple. Attach `ref` to any element to track its viewport visibility using `IntersectionObserver`.
-
 ```jsx
 function FadeInCard() {
   const [ref, inView] = useInViewport({ threshold: 0.2, once: true });
-
   return (
-    <div
-      ref={ref}
-      style={{
-        opacity: inView ? 1 : 0,
-        transform: inView ? 'translateY(0)' : 'translateY(20px)',
-        transition: 'all 0.5s ease'
-      }}
-    >
-      I animate in when visible!
+    <div ref={ref} style={{ opacity: inView ? 1 : 0, transition: 'opacity 0.5s' }}>
+      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 on first entry, then stop observing |
-
----
-
 ### `useScrollTo()`
 
-Returns a `[containerRef, scrollToTarget]` tuple. Scope smooth scrolling to a specific scrollable container, or fall back to window scroll.
-
 ```jsx
-function Sidebar() {
+function Page() {
   const [containerRef, scrollToTarget] = useScrollTo();
   const sectionRef = useRef(null);
-
   return (
     <div ref={containerRef} style={{ overflowY: 'scroll', height: '400px' }}>
-      <button onClick={() => scrollToTarget(sectionRef.current, { offset: -16 })}>
-        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?)`
-
-Returns `true` once the user has scrolled past a given pixel value. Useful for showing back-to-top buttons, sticky CTAs, and similar patterns.
+### `useScrolledPast(threshold?)`
 
 ```jsx
 function BackToTopButton() {
   const scrolledPast = useScrolledPast(300);
-  return scrolledPast ? (
-    <button onClick={() => scrollToTop()}>↑ Back to top</button>
-  ) : null;
+  return scrolledPast ? <button onClick={scrollToTop}>↑ Top</button> : null;
 }
 ```
 
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `threshold` | `number` | `100` | Y pixel value to check against |
-| `options.container` | `Element` | `window` | Scrollable container |
-
----
-
 ### `useScrollDirection()`
 
-Returns the current scroll direction: `'up'`, `'down'`, or `null` on initial render.
-
 ```jsx
 function HideOnScrollNav() {
   const direction = useScrollDirection();
-
   return (
-    <nav style={{
-      transform: direction === 'down' ? 'translateY(-100%)' : 'translateY(0)',
-      transition: 'transform 0.3s ease'
-    }}>
+    <nav style={{ transform: direction === 'down' ? 'translateY(-100%)' : 'translateY(0)' }}>
       My Navbar
     </nav>
   );
 }
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `throttle` | `number` | `100` | ms between direction checks |
-
 ---
 
 ## Tree-shaking
 
-All exports are named and side-effect free — you only ship what you import:
+All exports are named and side-effect free:
 
 ```js
-// Only pulls in ~400 bytes
-import { scrollToTop } from 'scroll-snap-kit';
-
-// Import utils and hooks separately for maximum tree-shaking
+import { scrollToTop } from 'scroll-snap-kit';             // ~400 bytes
 import { onScroll, scrollSpy } from 'scroll-snap-kit/utils';
 import { useScrollPosition } from 'scroll-snap-kit/hooks';
 ```
@@ -407,12 +419,18 @@ import { useScrollPosition } from 'scroll-snap-kit/hooks';
 
 ## Browser support
 
-All modern browsers (Chrome, Firefox, Safari, Edge). `easeScroll` uses `requestAnimationFrame`. `useInViewport` and `isInViewport` use `IntersectionObserver` — supported everywhere modern; polyfill if you need IE11.
+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