scroll-snap-kit 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# scroll-snap-kit 🎯
+
+> Smooth scroll utilities + React hooks for modern web apps.
+
+Zero dependencies. Tree-shakeable. Works with or without React.
+
+---
+
+## Install
+
+```bash
+npm install scroll-snap-kit
+```
+
+---
+
+## Vanilla JS Utilities
+
+```js
+import { scrollTo, scrollToTop, scrollToBottom, getScrollPosition, onScroll, isInViewport, lockScroll, unlockScroll } from 'scroll-snap-kit/utils';
+```
+
+### `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)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `behavior` | `'smooth' \| 'instant'` | `'smooth'` | Scroll behavior |
+| `block` | `ScrollLogicalPosition` | `'start'` | Vertical alignment |
+| `offset` | `number` | `0` | Pixel offset adjustment |
+
+---
+
+### `scrollToTop(options?)` / `scrollToBottom(options?)`
+
+```js
+scrollToTop();
+scrollToBottom({ behavior: 'instant' });
+```
+
+---
+
+### `getScrollPosition(container?)`
+
+```js
+const { x, y, percentX, percentY } = getScrollPosition();
+// percentY = how far down the page (0–100)
+```
+
+---
+
+### `onScroll(callback, options?)`
+
+Throttled scroll listener. Returns a cleanup function.
+
+```js
+const stop = onScroll(({ y, percentY }) => {
+  console.log(`Scrolled ${percentY}% down`);
+}, { throttle: 150 });
+
+// Later:
+stop(); // removes the listener
+```
+
+---
+
+### `isInViewport(element, options?)`
+
+```js
+if (isInViewport(document.querySelector('.card'), { threshold: 0.5 })) {
+  // At least 50% of the card is visible
+}
+```
+
+---
+
+### `lockScroll()` / `unlockScroll()`
+
+Lock page scroll (e.g. when a modal is open) and restore position on unlock.
+
+```js
+lockScroll();   // body stops scrolling
+unlockScroll(); // restored to previous position
+```
+
+---
+
+## React Hooks
+
+```js
+import { useScrollPosition, useInViewport, useScrollTo, useScrolledPast, useScrollDirection } from 'scroll-snap-kit/hooks';
+```
+
+### `useScrollPosition(options?)`
+
+```jsx
+function ProgressBar() {
+  const { percentY } = useScrollPosition({ throttle: 50 });
+  return <div style={{ width: `${percentY}%` }} className="progress" />;
+}
+```
+
+---
+
+### `useInViewport(options?)`
+
+```jsx
+function FadeIn() {
+  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>
+  );
+}
+```
+
+| 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>
+    </div>
+  );
+}
+```
+
+---
+
+### `useScrolledPast(threshold?, options?)`
+
+```jsx
+function BackToTopButton() {
+  const scrolledPast = useScrolledPast(300);
+  return scrolledPast ? <button onClick={scrollToTop}>↑ Top</button> : null;
+}
+```
+
+---
+
+### `useScrollDirection()`
+
+```jsx
+function Navbar() {
+  const direction = useScrollDirection();
+  return (
+    <nav style={{ transform: direction === 'down' ? 'translateY(-100%)' : 'translateY(0)' }}>
+      My Navbar
+    </nav>
+  );
+}
+```
+
+Returns `'up'`, `'down'`, or `null` (on initial render).
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "scroll-snap-kit",
+    "version": "1.0.0",
+    "description": "Smooth scroll utilities and React hooks for modern web apps",
+    "type": "module",
+    "main": "./src/index.js",
+    "module": "./src/index.js",
+    "exports": {
+        ".": {
+            "import": "./src/index.js"
+        },
+        "./utils": {
+            "import": "./src/utils.js"
+        },
+        "./hooks": {
+            "import": "./src/hooks.js"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "scripts": {
+        "test": "echo \"No tests yet\""
+    },
+    "keywords": [
+        "scroll",
+        "smooth-scroll",
+        "scroll-hooks",
+        "react-hooks",
+        "viewport",
+        "scroll-position",
+        "frontend",
+        "ui"
+    ],
+    "author": "Fabian Faraz Farid",
+    "license": "MIT",
+    "peerDependencies": {
+        "react": ">=16.8.0"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        }
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/farazfarid/scroll-snap-kit"
+    }
+}

package/src/hooks.js

@@ -0,0 +1,136 @@
+/**
+ * scroll-snap-kit — React Hooks
+ * Requires React 16.8+
+ */
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { getScrollPosition, onScroll, isInViewport } from './utils.js';
+
+/**
+ * Returns the current scroll position, updated on scroll.
+ * @param {{ throttle?: number, container?: Element }} options
+ * @returns {{ x: number, y: number, percentX: number, percentY: number }}
+ */
+export function useScrollPosition(options = {}) {
+    const { throttle = 100, container } = options;
+    const [position, setPosition] = useState(() =>
+        typeof window !== 'undefined' ? getScrollPosition(container) : { x: 0, y: 0, percentX: 0, percentY: 0 }
+    );
+
+    useEffect(() => {
+        const cleanup = onScroll((pos) => setPosition(pos), { throttle, container });
+        return cleanup;
+    }, [throttle, container]);
+
+    return position;
+}
+
+/**
+ * Returns whether a referenced element is currently in the viewport.
+ * @param {{ threshold?: number, once?: boolean }} options
+ * @returns {[React.RefObject, boolean]}
+ */
+export function useInViewport(options = {}) {
+    const { threshold = 0, once = false } = options;
+    const ref = useRef(null);
+    const [inView, setInView] = useState(false);
+    const hasTriggered = useRef(false);
+
+    useEffect(() => {
+        if (!ref.current) return;
+
+        const observer = new IntersectionObserver(
+            ([entry]) => {
+                const visible = entry.isIntersecting;
+                if (once) {
+                    if (visible && !hasTriggered.current) {
+                        hasTriggered.current = true;
+                        setInView(true);
+                        observer.disconnect();
+                    }
+                } else {
+                    setInView(visible);
+                }
+            },
+            { threshold }
+        );
+
+        observer.observe(ref.current);
+        return () => observer.disconnect();
+    }, [threshold, once]);
+
+    return [ref, inView];
+}
+
+/**
+ * Returns a scrollTo function scoped to an element ref or the window.
+ * @returns {[React.RefObject, (target: Element|number, options?: object) => void]}
+ */
+export function useScrollTo() {
+    const containerRef = useRef(null);
+
+    const scrollToTarget = useCallback((target, options = {}) => {
+        const { behavior = 'smooth', offset = 0 } = options;
+        const container = containerRef.current;
+
+        if (!container) {
+            // fallback to window scroll
+            if (typeof target === 'number') {
+                window.scrollTo({ top: target + offset, behavior });
+            } else if (target instanceof Element) {
+                target.scrollIntoView({ behavior });
+            }
+            return;
+        }
+
+        if (typeof target === 'number') {
+            container.scrollTo({ top: target + offset, behavior });
+        } else if (target instanceof Element) {
+            const containerTop = container.getBoundingClientRect().top;
+            const targetTop = target.getBoundingClientRect().top;
+            container.scrollBy({ top: targetTop - containerTop + offset, behavior });
+        }
+    }, []);
+
+    return [containerRef, scrollToTarget];
+}
+
+/**
+ * Tracks whether the user has scrolled past a given pixel threshold.
+ * @param {number} threshold - Y pixel value to check against (default: 100)
+ * @param {{ container?: Element }} options
+ * @returns {boolean}
+ */
+export function useScrolledPast(threshold = 100, options = {}) {
+    const { container } = options;
+    const [scrolledPast, setScrolledPast] = useState(false);
+
+    useEffect(() => {
+        const cleanup = onScroll(({ y }) => {
+            setScrolledPast(y > threshold);
+        }, { container });
+        return cleanup;
+    }, [threshold, container]);
+
+    return scrolledPast;
+}
+
+/**
+ * Returns scroll direction: 'up' | 'down' | null
+ * @param {{ throttle?: number }} options
+ * @returns {'up'|'down'|null}
+ */
+export function useScrollDirection(options = {}) {
+    const { throttle = 100 } = options;
+    const [direction, setDirection] = useState(null);
+    const lastY = useRef(typeof window !== 'undefined' ? window.scrollY : 0);
+
+    useEffect(() => {
+        const cleanup = onScroll(({ y }) => {
+            setDirection(y > lastY.current ? 'down' : 'up');
+            lastY.current = y;
+        }, { throttle });
+        return cleanup;
+    }, [throttle]);
+
+    return direction;
+}

package/src/index.js

@@ -0,0 +1,22 @@
+// scroll-snap-kit
+// Smooth scroll utilities + React hooks
+// https://github.com/farazfarid/scroll-snap-kit
+
+export {
+    scrollTo,
+    scrollToTop,
+    scrollToBottom,
+    getScrollPosition,
+    onScroll,
+    isInViewport,
+    lockScroll,
+    unlockScroll,
+} from './utils.js';
+
+export {
+    useScrollPosition,
+    useInViewport,
+    useScrollTo,
+    useScrolledPast,
+    useScrollDirection,
+} from './hooks.js';

package/src/utils.js

@@ -0,0 +1,154 @@
+/**
+ * scroll-snap-kit — Core Utilities
+ */
+
+/**
+ * Smoothly scrolls to a target element or position.
+ * @param {Element|number} target - A DOM element or Y pixel value
+ * @param {{ behavior?: ScrollBehavior, block?: ScrollLogicalPosition, offset?: number }} options
+ */
+export function scrollTo(target, options = {}) {
+    const { behavior = 'smooth', block = 'start', offset = 0 } = options;
+
+    if (typeof target === 'number') {
+        window.scrollTo({ top: target + offset, behavior });
+        return;
+    }
+
+    if (!(target instanceof Element)) {
+        console.warn('[scroll-snap-kit] scrollTo: target must be an Element or a number');
+        return;
+    }
+
+    if (offset !== 0) {
+        const y = target.getBoundingClientRect().top + window.scrollY + offset;
+        window.scrollTo({ top: y, behavior });
+    } else {
+        target.scrollIntoView({ behavior, block });
+    }
+}
+
+/**
+ * Smoothly scrolls to the top of the page.
+ * @param {{ behavior?: ScrollBehavior }} options
+ */
+export function scrollToTop(options = {}) {
+    const { behavior = 'smooth' } = options;
+    window.scrollTo({ top: 0, behavior });
+}
+
+/**
+ * Smoothly scrolls to the bottom of the page.
+ * @param {{ behavior?: ScrollBehavior }} options
+ */
+export function scrollToBottom(options = {}) {
+    const { behavior = 'smooth' } = options;
+    window.scrollTo({ top: document.body.scrollHeight, behavior });
+}
+
+/**
+ * Returns the current scroll position and scroll percentage.
+ * @param {Element} [container=window] - Optional scrollable container
+ * @returns {{ x: number, y: number, percentX: number, percentY: number }}
+ */
+export function getScrollPosition(container) {
+    if (container && container instanceof Element) {
+        const { scrollLeft, scrollTop, scrollWidth, scrollHeight, clientWidth, clientHeight } = container;
+        return {
+            x: scrollLeft,
+            y: scrollTop,
+            percentX: scrollWidth > clientWidth ? Math.round((scrollLeft / (scrollWidth - clientWidth)) * 100) : 0,
+            percentY: scrollHeight > clientHeight ? Math.round((scrollTop / (scrollHeight - clientHeight)) * 100) : 0,
+        };
+    }
+
+    const x = window.scrollX;
+    const y = window.scrollY;
+    const maxX = document.body.scrollWidth - window.innerWidth;
+    const maxY = document.body.scrollHeight - window.innerHeight;
+
+    return {
+        x,
+        y,
+        percentX: maxX > 0 ? Math.round((x / maxX) * 100) : 0,
+        percentY: maxY > 0 ? Math.round((y / maxY) * 100) : 0,
+    };
+}
+
+/**
+ * Attaches a throttled scroll event listener.
+ * @param {(position: ReturnType<typeof getScrollPosition>) => void} callback
+ * @param {{ throttle?: number, container?: Element }} options
+ * @returns {() => void} Cleanup function to remove the listener
+ */
+export function onScroll(callback, options = {}) {
+    const { throttle: throttleMs = 100, container } = options;
+    const target = container || window;
+
+    let ticking = false;
+    let lastTime = 0;
+
+    const handler = () => {
+        const now = Date.now();
+        if (now - lastTime < throttleMs) {
+            if (!ticking) {
+                ticking = true;
+                requestAnimationFrame(() => {
+                    callback(getScrollPosition(container));
+                    ticking = false;
+                    lastTime = Date.now();
+                });
+            }
+            return;
+        }
+        lastTime = now;
+        callback(getScrollPosition(container));
+    };
+
+    target.addEventListener('scroll', handler, { passive: true });
+    return () => target.removeEventListener('scroll', handler);
+}
+
+/**
+ * Checks whether an element is currently visible in the viewport.
+ * @param {Element} element
+ * @param {{ threshold?: number }} options - threshold: 0–1, portion of element that must be visible
+ * @returns {boolean}
+ */
+export function isInViewport(element, options = {}) {
+    if (!(element instanceof Element)) {
+        console.warn('[scroll-snap-kit] isInViewport: argument must be an Element');
+        return false;
+    }
+
+    const { threshold = 0 } = options;
+    const rect = element.getBoundingClientRect();
+    const windowHeight = window.innerHeight || document.documentElement.clientHeight;
+    const windowWidth = window.innerWidth || document.documentElement.clientWidth;
+
+    const verticalVisible = rect.top + rect.height * threshold < windowHeight && rect.bottom - rect.height * threshold > 0;
+    const horizontalVisible = rect.left + rect.width * threshold < windowWidth && rect.right - rect.width * threshold > 0;
+
+    return verticalVisible && horizontalVisible;
+}
+
+/**
+ * Locks the page scroll (e.g. when a modal is open).
+ */
+export function lockScroll() {
+    const scrollY = window.scrollY;
+    document.body.style.position = 'fixed';
+    document.body.style.top = `-${scrollY}px`;
+    document.body.style.width = '100%';
+}
+
+/**
+ * Unlocks the page scroll and restores position.
+ */
+export function unlockScroll() {
+    const scrollY = document.body.style.top;
+    document.body.style.position = '';
+    document.body.style.top = '';
+    document.body.style.width = '';
+    window.scrollTo(0, parseInt(scrollY || '0') * -1);
+}