msr-hooks 1.0.0

package/src/hooks/useHoverIntent/useHoverIntent.js

@@ -0,0 +1,81 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Detect deliberate hover with configurable delay and sensitivity.
+ * @param {React.RefObject<HTMLElement>} ref
+ * @param {{ delay?: number; leaveDelay?: number; sensitivity?: number }} options
+ * @returns {boolean}
+ */
+export function useHoverIntent(ref, options = {}) {
+    const { delay = 120, leaveDelay = 80, sensitivity = 8 } = options;
+    const [hovered, setHovered] = useState(false);
+    const startPos = useRef({ x: 0, y: 0 });
+    const lastPos = useRef({ x: 0, y: 0 });
+    const enterTimer = useRef();
+    const leaveTimer = useRef();
+
+    useEffect(() => {
+        const node = ref?.current;
+        if (!node) return undefined;
+
+        const clearEnter = () => {
+            if (enterTimer.current) {
+                clearTimeout(enterTimer.current);
+                enterTimer.current = undefined;
+            }
+        };
+
+        const clearLeave = () => {
+            if (leaveTimer.current) {
+                clearTimeout(leaveTimer.current);
+                leaveTimer.current = undefined;
+            }
+        };
+
+        const onMouseEnter = (event) => {
+            clearLeave();
+            startPos.current = { x: event.clientX, y: event.clientY };
+            lastPos.current = startPos.current;
+
+            const checkIntent = () => {
+                const dx = lastPos.current.x - startPos.current.x;
+                const dy = lastPos.current.y - startPos.current.y;
+                const distance = Math.sqrt(dx * dx + dy * dy);
+
+                if (distance <= sensitivity) {
+                    setHovered(true);
+                } else {
+                    startPos.current = { ...lastPos.current };
+                    enterTimer.current = setTimeout(checkIntent, delay);
+                }
+            };
+
+            clearEnter();
+            enterTimer.current = setTimeout(checkIntent, delay);
+        };
+
+        const onMouseMove = (event) => {
+            lastPos.current = { x: event.clientX, y: event.clientY };
+        };
+
+        const onMouseLeave = () => {
+            clearEnter();
+            clearLeave();
+            leaveTimer.current = setTimeout(() => setHovered(false), leaveDelay);
+        };
+
+        node.addEventListener('mouseenter', onMouseEnter);
+        node.addEventListener('mousemove', onMouseMove);
+        node.addEventListener('mouseleave', onMouseLeave);
+
+        return () => {
+            clearEnter();
+            clearLeave();
+            node.removeEventListener('mouseenter', onMouseEnter);
+            node.removeEventListener('mousemove', onMouseMove);
+            node.removeEventListener('mouseleave', onMouseLeave);
+        };
+    }, [ref, delay, leaveDelay, sensitivity]);
+
+    return hovered;
+}

package/src/hooks/useIntersectionObserver/index.js

@@ -0,0 +1 @@
+export { useIntersectionObserver } from './useIntersectionObserver';

package/src/hooks/useIntersectionObserver/useIntersectionObserver.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export function useIntersectionObserver(
+    options?: IntersectionObserverInit
+): [React.RefObject<HTMLElement>, boolean];

package/src/hooks/useIntersectionObserver/useIntersectionObserver.js

@@ -0,0 +1,25 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Detect when element enters/leaves viewport.
+ * @param {object} options - IntersectionObserver options
+ * @returns {[React.RefObject, boolean]} [ref to attach, isIntersecting state]
+ */
+export function useIntersectionObserver(options = {}) {
+    const [isIntersecting, setIsIntersecting] = useState(false);
+    const targetRef = useRef(null);
+
+    useEffect(() => {
+        const target = targetRef.current;
+        if (!target) return undefined;
+
+        const observer = new IntersectionObserver(([entry]) => {
+            setIsIntersecting(entry.isIntersecting);
+        }, options);
+
+        observer.observe(target);
+        return () => observer.disconnect();
+    }, [options]);
+
+    return [targetRef, isIntersecting];
+}

package/src/hooks/useInterval/index.js

@@ -0,0 +1 @@
+export { useInterval } from './useInterval';

package/src/hooks/useInterval/useInterval.d.ts

@@ -0,0 +1,4 @@
+export function useInterval(
+    callback: () => void,
+    delay: number | null
+): void;

package/src/hooks/useInterval/useInterval.js

@@ -0,0 +1,23 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Declarative setInterval with cleanup.
+ * @param {Function} callback - Function to call on interval
+ * @param {number|null} delay - Delay in ms, null to pause
+ * @returns {void}
+ */
+export function useInterval(callback, delay) {
+    const savedCallback = useRef();
+
+    useEffect(() => {
+        savedCallback.current = callback;
+    }, [callback]);
+
+    useEffect(() => {
+        if (delay === null) return undefined;
+
+        const tick = () => savedCallback.current();
+        const id = setInterval(tick, delay);
+        return () => clearInterval(id);
+    }, [delay]);
+}

package/src/hooks/useIsomorphicLayoutEffect/index.js

@@ -0,0 +1 @@
+export { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';

package/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+
+export const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;

package/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.js

@@ -0,0 +1,3 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+export const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;

package/src/hooks/useKeyPressSequence/index.js

@@ -0,0 +1 @@
+export { useKeyPressSequence } from './useKeyPressSequence';

package/src/hooks/useKeyPressSequence/useKeyPressSequence.d.ts

@@ -0,0 +1,5 @@
+export function useKeyPressSequence(
+    sequence: string | string[],
+    handler: (event: KeyboardEvent) => void,
+    options?: { timeout?: number }
+): void;

package/src/hooks/useKeyPressSequence/useKeyPressSequence.js

@@ -0,0 +1,52 @@
+import { useEffect } from 'react';
+
+/**
+ * Run a handler when a key sequence is pressed in order.
+ * @param {string | string[]} sequence
+ * @param {(event: KeyboardEvent) => void} handler
+ * @param {{ timeout?: number }} options
+ */
+export function useKeyPressSequence(sequence, handler, options = {}) {
+    const { timeout = 1000 } = options;
+
+    useEffect(() => {
+        if (!sequence || typeof window === 'undefined') return undefined;
+        const target = Array.isArray(sequence) ? sequence : String(sequence).split('');
+        let buffer = [];
+        let timerId;
+
+        const reset = () => {
+            buffer = [];
+            if (timerId) {
+                clearTimeout(timerId);
+                timerId = undefined;
+            }
+        };
+
+        const scheduleReset = () => {
+            if (!timeout) return;
+            if (timerId) clearTimeout(timerId);
+            timerId = setTimeout(reset, timeout);
+        };
+
+        const handleKeyDown = (event) => {
+            buffer.push(event.key);
+            if (buffer.length > target.length) {
+                buffer.shift();
+            }
+
+            scheduleReset();
+
+            if (buffer.length === target.length && target.every((key, idx) => buffer[idx] === key)) {
+                handler?.(event);
+                reset();
+            }
+        };
+
+        window.addEventListener('keydown', handleKeyDown);
+        return () => {
+            window.removeEventListener('keydown', handleKeyDown);
+            if (timerId) clearTimeout(timerId);
+        };
+    }, [sequence, handler, timeout]);
+}

package/src/hooks/useKeyboardNavigation/index.js

@@ -0,0 +1 @@
+export { useKeyboardNavigation } from './useKeyboardNavigation';

package/src/hooks/useKeyboardNavigation/useKeyboardNavigation.d.ts

@@ -0,0 +1,10 @@
+export interface UseKeyboardNavigationConfig {
+    selectedIndex: number | null;
+    handleSelect: (index: number | null) => void;
+    totalBytes: number;
+    bytesPerRow: number;
+}
+
+export function useKeyboardNavigation(
+    config: UseKeyboardNavigationConfig
+): void;

package/src/hooks/useKeyboardNavigation/useKeyboardNavigation.js

@@ -0,0 +1,50 @@
+import { useEffect } from 'react';
+
+/**
+ * Navigate through grid-like structures with arrow keys.
+ * @param {object} config - Configuration object
+ * @param {number} config.selectedIndex - Currently selected item index
+ * @param {Function} config.handleSelect - Callback to update selection
+ * @param {number} config.totalBytes - Total number of items
+ * @param {number} config.bytesPerRow - Items per row in grid
+ * @returns {void}
+ */
+export function useKeyboardNavigation({
+    selectedIndex,
+    handleSelect,
+    totalBytes,
+    bytesPerRow
+}) {
+    useEffect(() => {
+        const handleKeyDown = (event) => {
+            if (selectedIndex === null) return;
+
+            let newIndex = selectedIndex;
+
+            switch (event.key) {
+                case 'ArrowLeft':
+                    newIndex = Math.max(0, selectedIndex - 1);
+                    break;
+                case 'ArrowRight':
+                    newIndex = Math.min(totalBytes - 1, selectedIndex + 1);
+                    break;
+                case 'ArrowUp':
+                    newIndex = Math.max(0, selectedIndex - bytesPerRow);
+                    break;
+                case 'ArrowDown':
+                    newIndex = Math.min(totalBytes - 1, selectedIndex + bytesPerRow);
+                    break;
+                default:
+                    return;
+            }
+
+            if (newIndex !== selectedIndex) {
+                event.preventDefault();
+                handleSelect(newIndex);
+            }
+        };
+
+        window.addEventListener('keydown', handleKeyDown);
+        return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [selectedIndex, handleSelect, totalBytes, bytesPerRow]);
+}

package/src/hooks/useLocalStorage/index.js

@@ -0,0 +1 @@
+export { useLocalStorage } from './useLocalStorage';

package/src/hooks/useLocalStorage/useLocalStorage.d.ts

@@ -0,0 +1,4 @@
+export function useLocalStorage<T>(
+    key: string,
+    initialValue: T
+): [T, (value: T | ((val: T) => T)) => void];

package/src/hooks/useLocalStorage/useLocalStorage.js

@@ -0,0 +1,44 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * State synced to localStorage with JSON parsing and SSR guard.
+ * @param {string} key - Storage key
+ * @param {*} initialValue - Initial value if not in storage
+ * @returns {[*, Function]} [storedValue, setValue]
+ */
+export function useLocalStorage(key, initialValue) {
+    const isBrowser = typeof window !== 'undefined';
+
+    const readValue = useCallback(() => {
+        if (!isBrowser) return initialValue;
+        try {
+            const item = window.localStorage.getItem(key);
+            return item ? JSON.parse(item) : initialValue;
+        } catch (error) {
+            console.warn('useLocalStorage read error', error);
+            return initialValue;
+        }
+    }, [initialValue, isBrowser, key]);
+
+    const [storedValue, setStoredValue] = useState(readValue);
+
+    const setValue = useCallback(
+        (value) => {
+            if (!isBrowser) return;
+            try {
+                const valueToStore = value instanceof Function ? value(storedValue) : value;
+                setStoredValue(valueToStore);
+                window.localStorage.setItem(key, JSON.stringify(valueToStore));
+            } catch (error) {
+                console.warn('useLocalStorage write error', error);
+            }
+        },
+        [isBrowser, key, storedValue]
+    );
+
+    useEffect(() => {
+        setStoredValue(readValue());
+    }, [readValue]);
+
+    return [storedValue, setValue];
+}

package/src/hooks/useLockBodyScroll/index.js

@@ -0,0 +1 @@
+export { useLockBodyScroll } from './useLockBodyScroll';

package/src/hooks/useLockBodyScroll/useLockBodyScroll.d.ts

@@ -0,0 +1 @@
+export function useLockBodyScroll(enabled?: boolean): void;

package/src/hooks/useLockBodyScroll/useLockBodyScroll.js

@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+
+/**
+ * Lock document body scrolling while enabled.
+ * @param {boolean} enabled
+ */
+export function useLockBodyScroll(enabled = true) {
+    useEffect(() => {
+        if (!enabled || typeof document === 'undefined') return undefined;
+
+        const originalOverflow = document.body.style.overflow;
+        const originalPaddingRight = document.body.style.paddingRight;
+        const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+
+        document.body.style.overflow = 'hidden';
+        if (scrollbarWidth > 0) {
+            document.body.style.paddingRight = `${scrollbarWidth}px`;
+        }
+
+        return () => {
+            document.body.style.overflow = originalOverflow;
+            document.body.style.paddingRight = originalPaddingRight;
+        };
+    }, [enabled]);
+}

package/src/hooks/useMediaQuery/index.js

@@ -0,0 +1 @@
+export { useMediaQuery } from './useMediaQuery';

package/src/hooks/useMediaQuery/useMediaQuery.d.ts

@@ -0,0 +1 @@
+export function useMediaQuery(query: string): boolean;

package/src/hooks/useMediaQuery/useMediaQuery.js

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Detect if media query matches current viewport.
+ * @param {string} query - Media query string (e.g., '(min-width: 768px)')
+ * @returns {boolean} Whether the media query matches
+ */
+export function useMediaQuery(query) {
+    const [matches, setMatches] = useState(false);
+
+    useEffect(() => {
+        if (typeof window === 'undefined') return undefined;
+
+        const mediaQuery = window.matchMedia(query);
+        setMatches(mediaQuery.matches);
+
+        const handler = (event) => setMatches(event.matches);
+        
+        mediaQuery.addEventListener('change', handler);
+        return () => mediaQuery.removeEventListener('change', handler);
+    }, [query]);
+
+    return matches;
+}

package/src/hooks/useNetworkStatus/index.js

@@ -0,0 +1 @@
+export { useNetworkStatus } from './useNetworkStatus';

package/src/hooks/useNetworkStatus/useNetworkStatus.d.ts

@@ -0,0 +1,7 @@
+export interface NetworkStatusState {
+    online: boolean;
+    downlink: number | null;
+    rtt: number | null;
+}
+
+export function useNetworkStatus(): NetworkStatusState;

package/src/hooks/useNetworkStatus/useNetworkStatus.js

@@ -0,0 +1,47 @@
+import { useEffect, useState } from 'react';
+
+const getConnection = () => {
+    if (typeof navigator === 'undefined') return null;
+    return navigator.connection || navigator.mozConnection || navigator.webkitConnection || null;
+};
+
+const readStatus = () => {
+    const online = typeof navigator !== 'undefined' ? navigator.onLine : true;
+    const conn = getConnection();
+    return {
+        online,
+        downlink: conn?.downlink ?? null,
+        rtt: conn?.rtt ?? null,
+    };
+};
+
+/**
+ * Detect network status with basic debouncing and connection details.
+ * @returns {{online: boolean, downlink: number|null, rtt: number|null}}
+ */
+export function useNetworkStatus() {
+    const [state, setState] = useState(readStatus);
+
+    useEffect(() => {
+        let timer = null;
+        const scheduleUpdate = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => setState(readStatus()), 150);
+        };
+
+        window.addEventListener('online', scheduleUpdate);
+        window.addEventListener('offline', scheduleUpdate);
+
+        const conn = getConnection();
+        conn?.addEventListener?.('change', scheduleUpdate);
+
+        return () => {
+            clearTimeout(timer);
+            window.removeEventListener('online', scheduleUpdate);
+            window.removeEventListener('offline', scheduleUpdate);
+            conn?.removeEventListener?.('change', scheduleUpdate);
+        };
+    }, []);
+
+    return state;
+}

package/src/hooks/usePageLeave/index.js

@@ -0,0 +1 @@
+export { usePageLeave } from './usePageLeave';

package/src/hooks/usePageLeave/usePageLeave.d.ts

@@ -0,0 +1 @@
+export function usePageLeave(handler: () => void): void;

package/src/hooks/usePageLeave/usePageLeave.js

@@ -0,0 +1,27 @@
+import { useEffect } from 'react';
+
+/**
+ * Trigger a callback when the user is about to leave the page/tab.
+ * @param {Function} handler - Callback to run before leave
+ */
+export function usePageLeave(handler) {
+    useEffect(() => {
+        const onBeforeUnload = (e) => {
+            handler?.();
+        };
+        const onVisibility = () => {
+            if (document.visibilityState === 'hidden') handler?.();
+        };
+        const onPageHide = () => handler?.();
+
+        window.addEventListener('beforeunload', onBeforeUnload);
+        document.addEventListener('visibilitychange', onVisibility);
+        window.addEventListener('pagehide', onPageHide);
+
+        return () => {
+            window.removeEventListener('beforeunload', onBeforeUnload);
+            document.removeEventListener('visibilitychange', onVisibility);
+            window.removeEventListener('pagehide', onPageHide);
+        };
+    }, [handler]);
+}

package/src/hooks/useParentWidth/index.js

@@ -0,0 +1 @@
+export { useParentWidth } from './useParentWidth';

package/src/hooks/useParentWidth/useParentWidth.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+
+export interface UseParentWidthReturn {
+    parentWidth: number | null;
+    childRef: React.RefObject<HTMLDivElement>;
+}
+
+export function useParentWidth(): UseParentWidthReturn;

package/src/hooks/useParentWidth/useParentWidth.js

@@ -0,0 +1,30 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Get the parent element's width and a ref for the child element.
+ * @returns {{parentWidth: number|null, childRef: React.RefObject}} Parent width and child ref
+ */
+export function useParentWidth() {
+    const [parentWidth, setParentWidth] = useState(null);
+    const childRef = useRef(null);
+
+    useEffect(() => {
+        if (!childRef.current || !childRef.current.parentElement) return;
+
+        const parentElement = childRef.current.parentElement;
+
+        const resizeObserver = new ResizeObserver((entries) => {
+            entries.forEach((entry) => {
+                if (entry.target === parentElement) {
+                    setParentWidth(entry.contentRect.width);
+                }
+            });
+        });
+
+        resizeObserver.observe(parentElement);
+
+        return () => resizeObserver.disconnect();
+    }, []);
+
+    return { parentWidth, childRef };
+}

package/src/hooks/usePortal/index.js

@@ -0,0 +1 @@
+export { usePortal } from './usePortal';

package/src/hooks/usePortal/usePortal.d.ts

@@ -0,0 +1 @@
+export function usePortal(id?: string): HTMLElement | null;

package/src/hooks/usePortal/usePortal.js

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Ensure a DOM node exists for portals and return it.
+ * @param {string} id
+ * @returns {HTMLElement | null}
+ */
+export function usePortal(id) {
+    const [el] = useState(() => {
+        if (typeof document === 'undefined') return null;
+        const existing = id ? document.getElementById(id) : null;
+        if (existing) return existing;
+        const created = document.createElement('div');
+        if (id) created.id = id;
+        return created;
+    });
+
+    useEffect(() => {
+        if (!el || typeof document === 'undefined') return undefined;
+        const alreadyInDom = document.body.contains(el);
+        if (!alreadyInDom) {
+            document.body.appendChild(el);
+        }
+
+        return () => {
+            if (!alreadyInDom && el.parentNode) {
+                el.parentNode.removeChild(el);
+            }
+        };
+    }, [el]);
+
+    return el;
+}

package/src/hooks/usePrefersReducedMotion/index.js

@@ -0,0 +1 @@
+export { usePrefersReducedMotion } from './usePrefersReducedMotion';

package/src/hooks/usePrefersReducedMotion/usePrefersReducedMotion.d.ts

@@ -0,0 +1 @@
+export function usePrefersReducedMotion(): boolean;

package/src/hooks/usePrefersReducedMotion/usePrefersReducedMotion.js

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Detect OS reduced motion preference.
+ * @returns {boolean} true if user prefers reduced motion
+ */
+export function usePrefersReducedMotion() {
+    const isBrowser = typeof window !== 'undefined';
+    const query = '(prefers-reduced-motion: reduce)';
+    const [prefers, setPrefers] = useState(() => {
+        if (!isBrowser || !window.matchMedia) return false;
+        return window.matchMedia(query).matches;
+    });
+
+    useEffect(() => {
+        if (!isBrowser || !window.matchMedia) return undefined;
+        const mql = window.matchMedia(query);
+        const handler = (event) => setPrefers(event.matches);
+        mql.addEventListener('change', handler);
+        return () => mql.removeEventListener('change', handler);
+    }, [isBrowser]);
+
+    return prefers;
+}

package/src/hooks/usePreventZoom/index.js

@@ -0,0 +1 @@
+export { usePreventZoom } from './usePreventZoom';

package/src/hooks/usePreventZoom/usePreventZoom.d.ts

@@ -0,0 +1,4 @@
+export function usePreventZoom(
+    scrollCheck?: boolean,
+    keyboardCheck?: boolean
+): void;