msr-hooks 1.0.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "msr-hooks",
+  "version": "1.0.0",
+  "description": "A comprehensive collection of production-ready React hooks for JavaScript and TypeScript projects",
+  "private": false,
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "keywords": [
+    "react",
+    "hooks",
+    "react-hooks",
+    "custom-hooks",
+    "typescript",
+    "javascript",
+    "utilities",
+    "ui-hooks"
+  ],
+  "author": "MSR",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Minka1902/msr-hooks"
+  },
+  "bugs": {
+    "url": "https://github.com/Minka1902/msr-hooks/issues"
+  },
+  "homepage": "https://github.com/Minka1902/msr-hooks#readme",
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "@eslint/js": "^9.39.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^16.5.0"
+  }
+}

package/src/hooks/index.js

@@ -0,0 +1,53 @@
+// Core hooks
+export { useEffectAfterMount } from './useEffectAfterMount';
+export { useWindowSize } from './useWindowSize';
+export { useDebounce } from './useDebounce';
+export { usePrevious } from './usePrevious';
+export { useToggle } from './useToggle';
+export { useLocalStorage } from './useLocalStorage';
+
+// UI & Interaction hooks
+export { usePreventZoom } from './usePreventZoom';
+export { useChangeIconColor } from './useChangeIconColor';
+export { useClickOutsideObject } from './useClickOutsideObject';
+export { useKeyboardNavigation } from './useKeyboardNavigation';
+export { useEscapeKey } from './useEscapeKey';
+export { useParentWidth } from './useParentWidth';
+export { useResize } from './useResize';
+
+// New utility hooks
+export { useMediaQuery } from './useMediaQuery';
+export { useClipboard } from './useClipboard';
+export { useInterval } from './useInterval';
+export { useTimeout } from './useTimeout';
+export { useThrottle } from './useThrottle';
+export { useIntersectionObserver } from './useIntersectionObserver';
+export { useFetch } from './useFetch';
+
+// State management & History
+export { useUndoRedo } from './useUndoRedo';
+export { useStateHistory } from './useStateHistory';
+
+// Scroll & Animation
+export { useElementScrollProgress } from './useElementScrollProgress';
+export { useSpringValue } from './useSpringValue';
+
+// Network & Browser
+export { useNetworkStatus } from './useNetworkStatus';
+export { useDocumentVisibility } from './useDocumentVisibility';
+export { usePageLeave } from './usePageLeave';
+export { usePrefersReducedMotion } from './usePrefersReducedMotion';
+
+// DOM & Layout
+export { useLockBodyScroll } from './useLockBodyScroll';
+export { usePortal } from './usePortal';
+
+// Events & Interaction
+export { useKeyPressSequence } from './useKeyPressSequence';
+export { useHoverIntent } from './useHoverIntent';
+export { useEventListener } from './useEventListener';
+
+// Advanced Effects
+export { useAsyncEffect } from './useAsyncEffect';
+export { useDeepCompareEffect } from './useDeepCompareEffect';
+export { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';

package/src/hooks/useAsyncEffect/index.js

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

package/src/hooks/useAsyncEffect/useAsyncEffect.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+
+export function useAsyncEffect(
+    effect: (signal: AbortSignal) => void | (() => void) | Promise<void | (() => void)>,
+    deps?: React.DependencyList
+): void;

package/src/hooks/useAsyncEffect/useAsyncEffect.js

@@ -0,0 +1,31 @@
+import { useEffect } from 'react';
+
+/**
+ * An async-friendly effect with AbortSignal support.
+ * @param {(signal: AbortSignal) => void | (() => void) | Promise<void | (() => void)>} effect
+ * @param {React.DependencyList} deps
+ */
+export function useAsyncEffect(effect, deps = []) {
+    useEffect(() => {
+        const controller = new AbortController();
+        let cleanup;
+
+        const run = async () => {
+            const result = await effect(controller.signal);
+            if (typeof result === 'function') {
+                cleanup = result;
+            }
+        };
+
+        run().catch(() => {
+            // Avoid unhandled rejections; surface errors in the caller if needed.
+        });
+
+        return () => {
+            controller.abort();
+            if (typeof cleanup === 'function') {
+                cleanup();
+            }
+        };
+    }, deps);
+}

package/src/hooks/useChangeIconColor/index.js

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

package/src/hooks/useChangeIconColor/useChangeIconColor.d.ts

@@ -0,0 +1 @@
+export function useChangeIconColor(color?: string): void;

package/src/hooks/useChangeIconColor/useChangeIconColor.js

@@ -0,0 +1,39 @@
+import { useEffect } from 'react';
+
+/**
+ * Change the favicon color dynamically.
+ * @param {string} color - Hex color code for favicon, defaults to #000000
+ * @returns {void}
+ */
+export function useChangeIconColor(color = '#000000') {
+    useEffect(() => {
+        const favicon = document.getElementById('favicon');
+        if (!favicon) return;
+
+        const svgContent = `
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="${color}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-server-cog ">
+          <circle cx="12" cy="12" r="3"></circle>
+          <path d="M4.5 10H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v4a2 2 0 0 1-2 2h-.5"></path>
+          <path d="M4.5 14H4a2 2 0 0 0-2 2v4a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-4a2 2 0 0 0-2-2h-.5"></path>
+          <path d="M6 6h.01"></path>
+          <path d="M6 18h.01"></path>
+          <path d="m15.7 13.4-.9-.3"></path>
+          <path d="m9.2 10.9-.9-.3"></path>
+          <path d="m10.6 15.7.3-.9"></path>
+          <path d="m13.6 15.7-.4-1"></path>
+          <path d="m10.8 9.3-.4-1"></path>
+          <path d="m8.3 13.6 1-.4"></path>
+          <path d="m14.7 10.8 1-.4"></path>
+          <path d="m13.4 8.3-.3.9"></path>
+          </svg>
+        `;
+
+        try {
+            const blob = new Blob([svgContent], { type: 'image/svg+xml' });
+            const url = URL.createObjectURL(blob);
+            favicon.href = url;
+        } catch (error) {
+            console.warn('useChangeIconColor: Failed to update favicon', error);
+        }
+    }, [color]);
+}

package/src/hooks/useClickOutsideObject/index.js

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

package/src/hooks/useClickOutsideObject/useClickOutsideObject.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+
+export function useClickOutsideObject(
+    ref: React.RefObject<HTMLElement>,
+    handler: () => void,
+    dontReactTo?: string,
+    excludeRef?: React.RefObject<HTMLElement>
+): void;

package/src/hooks/useClickOutsideObject/useClickOutsideObject.js

@@ -0,0 +1,28 @@
+import { useEffect } from 'react';
+
+/**
+ * Detect clicks outside an element and trigger a handler.
+ * @param {object} ref - React ref to the target element
+ * @param {Function} handler - Callback when click occurs outside
+ * @param {string} dontReactTo - Element ID to ignore
+ * @param {object} excludeRef - Additional ref to exclude from trigger
+ * @returns {void}
+ */
+export function useClickOutsideObject(ref, handler, dontReactTo, excludeRef) {
+    useEffect(() => {
+        const listener = (event) => {
+            const target = event.target;
+            if (!ref.current || ref.current.contains(target)) return;
+            if (excludeRef?.current && excludeRef.current.contains(target)) return;
+            if (event?.target?.id !== dontReactTo) handler();
+        };
+
+        document.addEventListener('mousedown', listener);
+        document.addEventListener('touchstart', listener);
+
+        return () => {
+            document.removeEventListener('mousedown', listener);
+            document.removeEventListener('touchstart', listener);
+        };
+    }, [ref, handler, excludeRef, dontReactTo]);
+}

package/src/hooks/useClipboard/index.js

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

package/src/hooks/useClipboard/useClipboard.d.ts

@@ -0,0 +1,4 @@
+export function useClipboard(): [
+    (text: string) => Promise<void>,
+    boolean
+];

package/src/hooks/useClipboard/useClipboard.js

@@ -0,0 +1,27 @@
+import { useCallback, useState } from 'react';
+
+/**
+ * Copy text to clipboard.
+ * @returns {[() => Promise<void>, boolean]} [copy function, isCopied state]
+ */
+export function useClipboard() {
+    const [isCopied, setIsCopied] = useState(false);
+
+    const copy = useCallback(async (text) => {
+        if (!navigator?.clipboard) {
+            console.warn('Clipboard API not available');
+            return;
+        }
+
+        try {
+            await navigator.clipboard.writeText(text);
+            setIsCopied(true);
+            setTimeout(() => setIsCopied(false), 2000);
+        } catch (error) {
+            console.warn('Failed to copy text', error);
+            setIsCopied(false);
+        }
+    }, []);
+
+    return [copy, isCopied];
+}

package/src/hooks/useDebounce/index.js

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

package/src/hooks/useDebounce/useDebounce.d.ts

@@ -0,0 +1 @@
+export function useDebounce<T>(value: T, delay?: number): T;

package/src/hooks/useDebounce/useDebounce.js

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Debounce a changing value.
+ * @param {*} value - Value to debounce
+ * @param {number} delay - Debounce delay in ms, defaults to 300
+ * @returns {*} Debounced value
+ */
+export function useDebounce(value, delay = 300) {
+    const [debounced, setDebounced] = useState(value);
+
+    useEffect(() => {
+        const timer = setTimeout(() => setDebounced(value), delay);
+        return () => clearTimeout(timer);
+    }, [value, delay]);
+
+    return debounced;
+}

package/src/hooks/useDeepCompareEffect/index.js

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

package/src/hooks/useDeepCompareEffect/useDeepCompareEffect.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+
+export function useDeepCompareEffect(effect: React.EffectCallback, deps: React.DependencyList): void;

package/src/hooks/useDeepCompareEffect/useDeepCompareEffect.js

@@ -0,0 +1,40 @@
+import { useEffect, useRef } from 'react';
+
+function isObject(value) {
+    return value !== null && typeof value === 'object';
+}
+
+function deepEqual(a, b) {
+    if (Object.is(a, b)) return true;
+    if (!isObject(a) || !isObject(b)) return false;
+    if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+
+    for (const key of aKeys) {
+        if (!bKeys.includes(key)) return false;
+        if (!deepEqual(a[key], b[key])) return false;
+    }
+
+    return true;
+}
+
+/**
+ * useEffect with deep comparison on dependencies.
+ * @param {React.EffectCallback} effect
+ * @param {React.DependencyList} deps
+ */
+export function useDeepCompareEffect(effect, deps) {
+    const previousDepsRef = useRef();
+    const signalRef = useRef(0);
+    const dependencyList = deps || [];
+
+    if (!previousDepsRef.current || !deepEqual(previousDepsRef.current, dependencyList)) {
+        previousDepsRef.current = dependencyList;
+        signalRef.current += 1;
+    }
+
+    useEffect(effect, [signalRef.current]);
+}

package/src/hooks/useDocumentVisibility/index.js

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

package/src/hooks/useDocumentVisibility/useDocumentVisibility.d.ts

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

package/src/hooks/useDocumentVisibility/useDocumentVisibility.js

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Track document visibility (tab focus/blur).
+ * @returns {boolean} true when document is visible
+ */
+export function useDocumentVisibility() {
+    const isBrowser = typeof document !== 'undefined';
+    const [isVisible, setIsVisible] = useState(() => (isBrowser ? !document.hidden : true));
+
+    useEffect(() => {
+        if (!isBrowser) return undefined;
+        const handler = () => setIsVisible(!document.hidden);
+        document.addEventListener('visibilitychange', handler);
+        return () => document.removeEventListener('visibilitychange', handler);
+    }, [isBrowser]);
+
+    return isVisible;
+}

package/src/hooks/useEffectAfterMount/index.js

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

package/src/hooks/useEffectAfterMount/useEffectAfterMount.d.ts

@@ -0,0 +1,4 @@
+export function useEffectAfterMount(
+    effect: () => void | (() => void),
+    deps?: React.DependencyList
+): void;

package/src/hooks/useEffectAfterMount/useEffectAfterMount.js

@@ -0,0 +1,20 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Run an effect only after the first render (skips mount).
+ * @param {Function} effect - Effect callback to run after mount
+ * @param {Array} deps - Dependency array, defaults to []
+ * @returns {void}
+ */
+export function useEffectAfterMount(effect, deps = []) {
+    const isMounted = useRef(false);
+
+    useEffect(() => {
+        if (!isMounted.current) {
+            isMounted.current = true;
+            return undefined;
+        }
+        return effect();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+}

package/src/hooks/useElementScrollProgress/index.js

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

package/src/hooks/useElementScrollProgress/useElementScrollProgress.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export function useElementScrollProgress(
+    ref: React.RefObject<HTMLElement>
+): number;

package/src/hooks/useElementScrollProgress/useElementScrollProgress.js

@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Track scroll progress of a specific element (0-1).
+ * @param {React.RefObject<HTMLElement>} ref - Element ref to observe
+ * @returns {number} progress ratio between 0 and 1
+ */
+export function useElementScrollProgress(ref) {
+    const [progress, setProgress] = useState(0);
+
+    useEffect(() => {
+        const el = ref?.current;
+        if (!el) return;
+
+        const handleScroll = () => {
+            const max = el.scrollHeight - el.clientHeight;
+            if (max <= 0) {
+                setProgress(1);
+                return;
+            }
+            const next = Math.min(1, Math.max(0, el.scrollTop / max));
+            setProgress(next);
+        };
+
+        handleScroll();
+        el.addEventListener('scroll', handleScroll, { passive: true });
+        const resizeObserver = new ResizeObserver(handleScroll);
+        resizeObserver.observe(el);
+
+        return () => {
+            el.removeEventListener('scroll', handleScroll);
+            resizeObserver.disconnect();
+        };
+    }, [ref]);
+
+    return progress;
+}

package/src/hooks/useEscapeKey/index.js

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

package/src/hooks/useEscapeKey/useEscapeKey.d.ts

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

package/src/hooks/useEscapeKey/useEscapeKey.js

@@ -0,0 +1,22 @@
+import { useEffect } from 'react';
+
+/**
+ * Trigger a handler when Escape key is pressed.
+ * @param {Function} handler - Callback to execute on Escape
+ * @returns {void}
+ */
+export function useEscapeKey(handler) {
+    useEffect(() => {
+        const listener = (event) => {
+            if (event.key === 'Escape') {
+                handler();
+            }
+        };
+
+        document.addEventListener('keydown', listener);
+
+        return () => {
+            document.removeEventListener('keydown', listener);
+        };
+    }, [handler]);
+}

package/src/hooks/useEventListener/index.js

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

package/src/hooks/useEventListener/useEventListener.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+
+export function useEventListener(
+    target: EventTarget | null | undefined | React.RefObject<EventTarget>,
+    type: string,
+    listener: (event: Event) => void,
+    options?: boolean | AddEventListenerOptions
+): void;

package/src/hooks/useEventListener/useEventListener.js

@@ -0,0 +1,25 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Add an event listener with automatic cleanup.
+ * @param {EventTarget | React.RefObject<EventTarget>} target
+ * @param {string} type
+ * @param {(event: Event) => void} listener
+ * @param {boolean | AddEventListenerOptions} [options]
+ */
+export function useEventListener(target, type, listener, options) {
+    const handlerRef = useRef(listener);
+
+    useEffect(() => {
+        handlerRef.current = listener;
+    }, [listener]);
+
+    useEffect(() => {
+        const element = target && 'current' in target ? target.current : target || (typeof window !== 'undefined' ? window : undefined);
+        if (!element || !element.addEventListener) return undefined;
+
+        const eventHandler = (event) => handlerRef.current?.(event);
+        element.addEventListener(type, eventHandler, options);
+        return () => element.removeEventListener(type, eventHandler, options);
+    }, [target, type, options]);
+}

package/src/hooks/useFetch/index.js

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

package/src/hooks/useFetch/useFetch.d.ts

@@ -0,0 +1,11 @@
+export interface UseFetchReturn<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+
+export function useFetch<T = any>(
+    url: string,
+    options?: RequestInit
+): UseFetchReturn<T>;

package/src/hooks/useFetch/useFetch.js

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * Fetch data with loading and error states.
+ * @param {string} url - URL to fetch
+ * @param {object} options - Fetch options
+ * @returns {{data: *, loading: boolean, error: Error|null, refetch: Function}}
+ */
+export function useFetch(url, options = {}) {
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+
+    const fetchData = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+
+        try {
+            const response = await fetch(url, options);
+            if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
+            const result = await response.json();
+            setData(result);
+        } catch (err) {
+            setError(err);
+        } finally {
+            setLoading(false);
+        }
+    }, [url, options]);
+
+    useEffect(() => {
+        fetchData();
+    }, [fetchData]);
+
+    return { data, loading, error, refetch: fetchData };
+}

package/src/hooks/useHoverIntent/index.js

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

package/src/hooks/useHoverIntent/useHoverIntent.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+
+export function useHoverIntent(
+    ref: React.RefObject<HTMLElement>,
+    options?: { delay?: number; leaveDelay?: number; sensitivity?: number }
+): boolean;