scroll-snap-kit 1.0.0 → 1.1.0

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,60 @@ 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 |
+
+| 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
+} 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,45 +86,174 @@ 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)
+
+// Works on containers too
+const pos = getScrollPosition(document.querySelector('.sidebar'));
 ```
 
 ---
 
 ### `onScroll(callback, options?)`
 
-Throttled scroll listener. Returns a cleanup function.
+Throttled scroll listener. Returns a cleanup function to stop listening.
 
 ```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?)`
 
+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
 }
 ```
 
+| 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.
+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
+```
+
+---
+
+### `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.
+
+```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')
+  }
+);
+
+stop(); // remove the 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.
+
+---
+
+### `onScrollEnd(callback, options?)`
+
+Fires a callback once the user has stopped scrolling for a configurable delay. Great for lazy-loading, analytics, or autosave.
+
+```js
+const stop = onScrollEnd(() => {
+  console.log('User stopped scrolling!');
+  saveScrollPosition();
+}, { delay: 200 });
+
+stop(); // cleanup
+```
+
+| 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 partially or fully outside the visible viewport. If it's already visible enough, nothing happens — no unnecessary scroll.
+
+```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 });
+```
+
+| 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, bypassing the browser's native smooth scroll. Returns a `Promise` that resolves when the animation completes.
+
+```js
+// Use a built-in easing
+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 position |
+
+**Built-in easings:**
 
 ```js
-lockScroll();   // body stops scrolling
-unlockScroll(); // restored to previous position
+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
 ```
 
 ---
@@ -95,28 +261,55 @@ unlockScroll(); // restored to previous position
 ## 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?)`
 
+Returns the current scroll position, updated live on scroll.
+
 ```jsx
 function ProgressBar() {
-  const { percentY } = useScrollPosition({ throttle: 50 });
-  return <div style={{ width: `${percentY}%` }} className="progress" />;
+  const { x, y, percentX, 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 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!
+    <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>
   );
 }
@@ -125,20 +318,24 @@ function FadeIn() {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `threshold` | `number` | `0` | 0–1 portion of element visible to trigger |
-| `once` | `boolean` | `false` | Only trigger the first time |
+| `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 Page() {
+function Sidebar() {
   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>
+      <button onClick={() => scrollToTarget(sectionRef.current, { offset: -16 })}>
+        Jump to section
+      </button>
       <div style={{ height: 300 }} />
       <div ref={sectionRef}>Target section</div>
     </div>
@@ -150,32 +347,83 @@ function Page() {
 
 ### `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.
+
 ```jsx
 function BackToTopButton() {
   const scrolledPast = useScrolledPast(300);
-  return scrolledPast ? <button onClick={scrollToTop}>↑ Top</button> : null;
+  return scrolledPast ? (
+    <button onClick={() => scrollToTop()}>↑ Back to 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 Navbar() {
+function HideOnScrollNav() {
   const direction = useScrollDirection();
+
   return (
-    <nav style={{ transform: direction === 'down' ? 'translateY(-100%)' : 'translateY(0)' }}>
+    <nav style={{
+      transform: direction === 'down' ? 'translateY(-100%)' : 'translateY(0)',
+      transition: 'transform 0.3s ease'
+    }}>
       My Navbar
     </nav>
   );
 }
 ```
 
-Returns `'up'`, `'down'`, or `null` (on initial render).
+| 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:
+
+```js
+// Only pulls in ~400 bytes
+import { scrollToTop } from 'scroll-snap-kit';
+
+// Import utils and hooks separately for maximum tree-shaking
+import { onScroll, scrollSpy } from 'scroll-snap-kit/utils';
+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.
+
+---
+
+## Changelog
+
+### 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "scroll-snap-kit",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Smooth scroll utilities and React hooks for modern web apps",
     "type": "module",
     "main": "./src/index.js",
@@ -44,6 +44,10 @@
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/farazfarid/scroll-snap-kit"
-    }
-}
+        "url": "git+https://github.com/farazfarid/scroll-snap-kit.git"
+    },
+    "bugs": {
+        "url": "https://github.com/farazfarid/scroll-snap-kit/issues"
+    },
+    "homepage": "https://farazfarid.github.io/scroll-snap-kit/"
+}

package/src/index.js

@@ -11,6 +11,12 @@ export {
     isInViewport,
     lockScroll,
     unlockScroll,
+    // New in v1.1
+    scrollSpy,
+    onScrollEnd,
+    scrollIntoViewIfNeeded,
+    easeScroll,
+    Easings,
 } from './utils.js';
 
 export {

package/src/utils.js

@@ -151,4 +151,187 @@ export function unlockScroll() {
     document.body.style.top = '';
     document.body.style.width = '';
     window.scrollTo(0, parseInt(scrollY || '0') * -1);
+}
+
+// ─────────────────────────────────────────────
+// NEW FEATURES
+// ─────────────────────────────────────────────
+
+/**
+ * scrollSpy — watches scroll position and highlights nav links
+ * matching the currently active section.
+ *
+ * @param {string} sectionsSelector   CSS selector for the sections to spy on
+ * @param {string} linksSelector      CSS selector for the nav links
+ * @param {{ offset?: number, activeClass?: string }} options
+ * @returns {() => void}  cleanup / stop function
+ *
+ * @example
+ * const stop = scrollSpy('section[id]', 'nav a', { offset: 80, activeClass: 'active' })
+ */
+export function scrollSpy(sectionsSelector, linksSelector, options = {}) {
+    const { offset = 0, activeClass = 'scroll-spy-active' } = options;
+
+    const sections = Array.from(document.querySelectorAll(sectionsSelector));
+    const links = Array.from(document.querySelectorAll(linksSelector));
+
+    if (!sections.length || !links.length) {
+        console.warn('[scroll-snap-kit] scrollSpy: no sections or links found');
+        return () => { };
+    }
+
+    function update() {
+        const scrollY = window.scrollY + offset;
+        let current = sections[0];
+
+        for (const section of sections) {
+            if (section.offsetTop <= scrollY) current = section;
+        }
+
+        links.forEach(link => {
+            link.classList.remove(activeClass);
+            const href = link.getAttribute('href');
+            if (href && current && href === `#${current.id}`) {
+                link.classList.add(activeClass);
+            }
+        });
+    }
+
+    update();
+    window.addEventListener('scroll', update, { passive: true });
+    return () => window.removeEventListener('scroll', update);
+}
+
+/**
+ * onScrollEnd — fires a callback once the user stops scrolling.
+ *
+ * @param {() => void} callback
+ * @param {{ delay?: number, container?: Element }} options
+ * @returns {() => void}  cleanup function
+ *
+ * @example
+ * const stop = onScrollEnd(() => console.log('Scrolling stopped!'), { delay: 150 })
+ */
+export function onScrollEnd(callback, options = {}) {
+    const { delay = 150, container } = options;
+    const target = container || window;
+    let timer = null;
+
+    const handler = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            callback(getScrollPosition(container));
+        }, delay);
+    };
+
+    target.addEventListener('scroll', handler, { passive: true });
+    return () => {
+        clearTimeout(timer);
+        target.removeEventListener('scroll', handler);
+    };
+}
+
+/**
+ * scrollIntoViewIfNeeded — scrolls to an element only if it is
+ * partially or fully outside the visible viewport.
+ *
+ * @param {Element} element
+ * @param {{ behavior?: ScrollBehavior, offset?: number, threshold?: number }} options
+ *   threshold: 0–1, how much of the element must be visible before we skip scrolling (default 1 = fully visible)
+ *
+ * @example
+ * scrollIntoViewIfNeeded(document.querySelector('.card'))
+ */
+export function scrollIntoViewIfNeeded(element, options = {}) {
+    if (!(element instanceof Element)) {
+        console.warn('[scroll-snap-kit] scrollIntoViewIfNeeded: argument must be an Element');
+        return;
+    }
+
+    const { behavior = 'smooth', offset = 0, threshold = 1 } = options;
+    const rect = element.getBoundingClientRect();
+    const wh = window.innerHeight || document.documentElement.clientHeight;
+    const ww = window.innerWidth || document.documentElement.clientWidth;
+
+    const visibleH = Math.min(rect.bottom, wh) - Math.max(rect.top, 0);
+    const visibleW = Math.min(rect.right, ww) - Math.max(rect.left, 0);
+    const visibleRatio =
+        (Math.max(0, visibleH) * Math.max(0, visibleW)) / (rect.height * rect.width);
+
+    if (visibleRatio >= threshold) return; // already sufficiently visible — skip
+
+    const y = rect.top + window.scrollY - offset;
+    window.scrollTo({ top: y, behavior });
+}
+
+/**
+ * Built-in easing functions for use with easeScroll().
+ */
+export const Easings = {
+    linear: (t) => t,
+    easeInQuad: (t) => t * t,
+    easeOutQuad: (t) => t * (2 - t),
+    easeInOutQuad: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t,
+    easeInCubic: (t) => t * t * t,
+    easeOutCubic: (t) => (--t) * t * t + 1,
+    easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,
+    easeInQuart: (t) => t * t * t * t,
+    easeOutQuart: (t) => 1 - (--t) * t * t * t,
+    easeOutElastic: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0 ? 0 : t === 1 ? 1
+            : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+    },
+    easeOutBounce: (t) => {
+        const n1 = 7.5625, d1 = 2.75;
+        if (t < 1 / d1) return n1 * t * t;
+        if (t < 2 / d1) return n1 * (t -= 1.5 / d1) * t + 0.75;
+        if (t < 2.5 / d1) return n1 * (t -= 2.25 / d1) * t + 0.9375;
+        return n1 * (t -= 2.625 / d1) * t + 0.984375;
+    },
+};
+
+/**
+ * easeScroll — scroll to a position with a custom easing curve,
+ * bypassing the browser's native smooth scroll.
+ *
+ * @param {Element|number} target   DOM element or pixel Y value
+ * @param {{ duration?: number, easing?: (t: number) => number, offset?: number }} options
+ * @returns {Promise<void>}  resolves when animation completes
+ *
+ * @example
+ * await easeScroll('#contact', { duration: 800, easing: Easings.easeOutElastic })
+ */
+export function easeScroll(target, options = {}) {
+    const { duration = 600, easing = Easings.easeInOutCubic, offset = 0 } = options;
+
+    let targetY;
+    if (typeof target === 'number') {
+        targetY = target + offset;
+    } else {
+        const el = typeof target === 'string' ? document.querySelector(target) : target;
+        if (!el) { console.warn('[scroll-snap-kit] easeScroll: target not found'); return Promise.resolve(); }
+        targetY = el.getBoundingClientRect().top + window.scrollY + offset;
+    }
+
+    const startY = window.scrollY;
+    const distance = targetY - startY;
+    const startTime = performance.now();
+
+    return new Promise((resolve) => {
+        function step(now) {
+            const elapsed = now - startTime;
+            const progress = Math.min(elapsed / duration, 1);
+            const easedProgress = easing(progress);
+
+            window.scrollTo(0, startY + distance * easedProgress);
+
+            if (progress < 1) {
+                requestAnimationFrame(step);
+            } else {
+                resolve();
+            }
+        }
+        requestAnimationFrame(step);
+    });
 }