react-essentials-functions 1.0.2 → 1.1.0

package/build/hooks/useDebounce.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDebounce = useDebounce;
+const react_1 = require("react");
+/**
+ * Hook that debounces a value by a given delay.
+ * The debounced value will only update after the specified delay has passed
+ * since the last change.
+ *
+ * @param value - The value to debounce
+ * @param delay - The debounce delay in milliseconds
+ * @returns The debounced value
+ *
+ * @example
+ * ```tsx
+ * const [searchTerm, setSearchTerm] = useState('');
+ * const debouncedSearch = useDebounce(searchTerm, 300);
+ *
+ * useEffect(() => {
+ *   // This will only fire 300ms after the user stops typing
+ *   fetchResults(debouncedSearch);
+ * }, [debouncedSearch]);
+ * ```
+ */
+function useDebounce(value, delay) {
+    const [debouncedValue, setDebouncedValue] = (0, react_1.useState)(value);
+    (0, react_1.useEffect)(() => {
+        const handler = setTimeout(() => {
+            setDebouncedValue(value);
+        }, delay);
+        return () => {
+            clearTimeout(handler);
+        };
+    }, [value, delay]);
+    return debouncedValue;
+}

package/build/hooks/useDimensions.d.ts

@@ -1,5 +1,25 @@
-import React from 'react';
-export declare function useDimensions(targetRef: React.RefObject<HTMLElement>): {
+import { RefObject } from 'react';
+export type Dimensions = {
     width: number;
     height: number;
 };
+/**
+ * Hook to get the dimensions of a DOM element.
+ * Uses ResizeObserver for optimal performance.
+ *
+ * @param targetRef - React ref to the element to measure
+ * @returns Object containing width and height of the element
+ *
+ * @example
+ * ```tsx
+ * const targetRef = useRef<HTMLDivElement>(null);
+ * const { width, height } = useDimensions(targetRef);
+ *
+ * return (
+ *   <div ref={targetRef}>
+ *     Size: {width} x {height}
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useDimensions(targetRef: RefObject<HTMLElement>): Dimensions;

package/build/hooks/useDimensions.js

@@ -1,35 +1,71 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useDimensions = void 0;
+exports.useDimensions = useDimensions;
 const react_1 = require("react");
+/**
+ * Hook to get the dimensions of a DOM element.
+ * Uses ResizeObserver for optimal performance.
+ *
+ * @param targetRef - React ref to the element to measure
+ * @returns Object containing width and height of the element
+ *
+ * @example
+ * ```tsx
+ * const targetRef = useRef<HTMLDivElement>(null);
+ * const { width, height } = useDimensions(targetRef);
+ *
+ * return (
+ *   <div ref={targetRef}>
+ *     Size: {width} x {height}
+ *   </div>
+ * );
+ * ```
+ */
 function useDimensions(targetRef) {
-    const getDimensions = () => {
+    const getDimensions = (0, react_1.useCallback)(() => {
         return {
             width: targetRef.current ? targetRef.current.offsetWidth : 0,
             height: targetRef.current ? targetRef.current.offsetHeight : 0,
         };
-    };
-    const [dimensions, setDimensions] = (0, react_1.useState)(getDimensions);
-    const handleResize = () => {
-        setDimensions(getDimensions());
-    };
+        // targetRef is a ref object - stable across renders, no need in deps
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const [dimensions, setDimensions] = (0, react_1.useState)({
+        width: 0,
+        height: 0,
+    });
+    (0, react_1.useLayoutEffect)(() => {
+        if (targetRef.current) {
+            setDimensions(getDimensions());
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
     (0, react_1.useEffect)(() => {
+        const element = targetRef.current;
+        if (!element) {
+            return;
+        }
+        // Use ResizeObserver for better performance than window resize events
+        if (typeof ResizeObserver !== 'undefined') {
+            const resizeObserver = new ResizeObserver(() => {
+                setDimensions(getDimensions());
+            });
+            resizeObserver.observe(element);
+            return () => {
+                resizeObserver.disconnect();
+            };
+        }
+        // Fallback for browsers that don't support ResizeObserver
+        const handleResize = () => {
+            setDimensions(getDimensions());
+        };
         window.addEventListener('resize', handleResize);
         window.addEventListener('scroll', handleResize);
-        window.addEventListener('load', handleResize);
         return () => {
             window.removeEventListener('resize', handleResize);
             window.removeEventListener('scroll', handleResize);
-            window.addEventListener('load', handleResize);
         };
-    }, []);
-    (0, react_1.useLayoutEffect)(() => {
-        handleResize();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     return dimensions;
 }
-exports.useDimensions = useDimensions;
-// const targetRef = useRef() // then set a ref to your component
-// const size = useDimensions(targetRef)
-// ....
-// return (div ref={targetRef}> .... <p>{size.width} - {size.height} </p> .... </div>);

package/build/hooks/useLocalStorage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hook that syncs state with localStorage.
+ * Handles serialization/deserialization automatically with JSON.
+ * Falls back gracefully when localStorage is unavailable.
+ *
+ * @param key - The localStorage key
+ * @param initialValue - The initial value if nothing is stored
+ * @returns A tuple of [storedValue, setValue, removeValue]
+ *
+ * @example
+ * ```tsx
+ * const [name, setName, removeName] = useLocalStorage('user-name', '');
+ *
+ * return (
+ *   <input
+ *     value={name}
+ *     onChange={(e) => setName(e.target.value)}
+ *   />
+ * );
+ * ```
+ */
+export declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void, () => void];

package/build/hooks/useLocalStorage.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLocalStorage = useLocalStorage;
+const react_1 = require("react");
+/**
+ * Hook that syncs state with localStorage.
+ * Handles serialization/deserialization automatically with JSON.
+ * Falls back gracefully when localStorage is unavailable.
+ *
+ * @param key - The localStorage key
+ * @param initialValue - The initial value if nothing is stored
+ * @returns A tuple of [storedValue, setValue, removeValue]
+ *
+ * @example
+ * ```tsx
+ * const [name, setName, removeName] = useLocalStorage('user-name', '');
+ *
+ * return (
+ *   <input
+ *     value={name}
+ *     onChange={(e) => setName(e.target.value)}
+ *   />
+ * );
+ * ```
+ */
+function useLocalStorage(key, initialValue) {
+    const [storedValue, setStoredValue] = (0, react_1.useState)(() => {
+        if (typeof window === 'undefined') {
+            return initialValue;
+        }
+        try {
+            const item = window.localStorage.getItem(key);
+            return item !== null ? JSON.parse(item) : initialValue;
+        }
+        catch {
+            return initialValue;
+        }
+    });
+    const setValue = (0, react_1.useCallback)((value) => {
+        setStoredValue((prev) => {
+            const valueToStore = value instanceof Function ? value(prev) : value;
+            try {
+                window.localStorage.setItem(key, JSON.stringify(valueToStore));
+            }
+            catch {
+                // localStorage may not be available
+            }
+            return valueToStore;
+        });
+    }, [key]);
+    const removeValue = (0, react_1.useCallback)(() => {
+        try {
+            window.localStorage.removeItem(key);
+        }
+        catch {
+            // localStorage may not be available
+        }
+        setStoredValue(initialValue);
+    }, [key, initialValue]);
+    return [storedValue, setValue, removeValue];
+}

package/build/hooks/useMediaQuery.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hook that tracks whether a CSS media query matches.
+ * Listens for changes and updates automatically.
+ *
+ * @param query - The CSS media query string (e.g. '(min-width: 768px)')
+ * @returns Whether the media query currently matches
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery('(max-width: 767px)');
+ * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
+ * const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+ *
+ * return isMobile ? <MobileLayout /> : <DesktopLayout />;
+ * ```
+ */
+export declare function useMediaQuery(query: string): boolean;

package/build/hooks/useMediaQuery.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMediaQuery = useMediaQuery;
+const react_1 = require("react");
+/**
+ * Hook that tracks whether a CSS media query matches.
+ * Listens for changes and updates automatically.
+ *
+ * @param query - The CSS media query string (e.g. '(min-width: 768px)')
+ * @returns Whether the media query currently matches
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery('(max-width: 767px)');
+ * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
+ * const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+ *
+ * return isMobile ? <MobileLayout /> : <DesktopLayout />;
+ * ```
+ */
+function useMediaQuery(query) {
+    const [matches, setMatches] = (0, react_1.useState)(() => {
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        return window.matchMedia(query).matches;
+    });
+    (0, react_1.useEffect)(() => {
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const mediaQuery = window.matchMedia(query);
+        setMatches(mediaQuery.matches);
+        const handleChange = (event) => {
+            setMatches(event.matches);
+        };
+        mediaQuery.addEventListener('change', handleChange);
+        return () => {
+            mediaQuery.removeEventListener('change', handleChange);
+        };
+    }, [query]);
+    return matches;
+}

package/build/hooks/usePrevious.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hook that returns the previous value of a variable.
+ * Useful for comparing current and previous props or state.
+ *
+ * @param value - The value to track
+ * @returns The value from the previous render, or undefined on first render
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useState(0);
+ * const previousCount = usePrevious(count);
+ *
+ * return (
+ *   <div>
+ *     Current: {count}, Previous: {previousCount ?? 'N/A'}
+ *   </div>
+ * );
+ * ```
+ */
+export declare function usePrevious<T>(value: T): T | undefined;

package/build/hooks/usePrevious.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePrevious = usePrevious;
+const react_1 = require("react");
+/**
+ * Hook that returns the previous value of a variable.
+ * Useful for comparing current and previous props or state.
+ *
+ * @param value - The value to track
+ * @returns The value from the previous render, or undefined on first render
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useState(0);
+ * const previousCount = usePrevious(count);
+ *
+ * return (
+ *   <div>
+ *     Current: {count}, Previous: {previousCount ?? 'N/A'}
+ *   </div>
+ * );
+ * ```
+ */
+function usePrevious(value) {
+    const ref = (0, react_1.useRef)(undefined);
+    (0, react_1.useEffect)(() => {
+        ref.current = value;
+    }, [value]);
+    return ref.current;
+}

package/build/hooks/useSafeFetch.d.ts

@@ -1 +1,26 @@
-export declare function useSafeFetch(): (url: string, options: Record<any, any>) => Promise<Response>;
+/**
+ * Hook that provides a fetch function which automatically aborts previous
+ * requests and cleans up on unmount using AbortController.
+ *
+ * @returns A fetch function with automatic abort handling
+ *
+ * @example
+ * ```tsx
+ * const safeFetch = useSafeFetch();
+ *
+ * useEffect(() => {
+ *   const fetchData = async () => {
+ *     try {
+ *       const response = await safeFetch('https://api.example.com/data');
+ *       const data = await response.json();
+ *     } catch (error) {
+ *       if (error.name !== 'AbortError') {
+ *         console.error('Fetch error:', error);
+ *       }
+ *     }
+ *   };
+ *   fetchData();
+ * }, [safeFetch]);
+ * ```
+ */
+export declare function useSafeFetch(): (url: string, options?: RequestInit) => Promise<Response>;

package/build/hooks/useSafeFetch.js

@@ -1,10 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useSafeFetch = void 0;
+exports.useSafeFetch = useSafeFetch;
 const react_1 = require("react");
+/**
+ * Hook that provides a fetch function which automatically aborts previous
+ * requests and cleans up on unmount using AbortController.
+ *
+ * @returns A fetch function with automatic abort handling
+ *
+ * @example
+ * ```tsx
+ * const safeFetch = useSafeFetch();
+ *
+ * useEffect(() => {
+ *   const fetchData = async () => {
+ *     try {
+ *       const response = await safeFetch('https://api.example.com/data');
+ *       const data = await response.json();
+ *     } catch (error) {
+ *       if (error.name !== 'AbortError') {
+ *         console.error('Fetch error:', error);
+ *       }
+ *     }
+ *   };
+ *   fetchData();
+ * }, [safeFetch]);
+ * ```
+ */
 function useSafeFetch() {
-    const abortController = (0, react_1.useRef)(new AbortController());
-    (0, react_1.useEffect)(() => () => abortController.current.abort(), []);
-    return (0, react_1.useCallback)((url, options) => fetch(url, { signal: abortController.current.signal, ...options }), []);
+    const abortControllerRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        return () => {
+            abortControllerRef.current?.abort();
+        };
+    }, []);
+    return (0, react_1.useCallback)((url, options = {}) => {
+        abortControllerRef.current?.abort();
+        const abortController = new AbortController();
+        abortControllerRef.current = abortController;
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { signal, ...restOptions } = options;
+        return fetch(url, {
+            ...restOptions,
+            signal: abortController.signal,
+        });
+    }, []);
 }
-exports.useSafeFetch = useSafeFetch;

package/build/hooks/useSafeState.d.ts

@@ -1 +1,3 @@
-export declare function useSafeState(initialValue?: null): (((value: any) => void) | null)[];
+type SetStateAction<T> = T | ((prevState: T) => T);
+export declare function useSafeState<T = unknown>(initialValue?: T | (() => T)): [T, (value: SetStateAction<T>) => void];
+export {};

package/build/hooks/useSafeState.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useSafeState = void 0;
+exports.useSafeState = useSafeState;
 const react_1 = require("react");
 function useSafeState(initialValue = null) {
     const isMounted = (0, react_1.useRef)(true);
@@ -17,4 +17,3 @@ function useSafeState(initialValue = null) {
     }, []);
     return [state, setStateSafe];
 }
-exports.useSafeState = useSafeState;

package/build/hooks/useScript.d.ts

@@ -1 +1,36 @@
-export declare const useScript: (url: string) => void;
+export type UseScriptStatus = 'idle' | 'loading' | 'ready' | 'error';
+export type UseScriptOptions = {
+    /**
+     * Callback called when script is loaded successfully
+     */
+    onLoad?: () => void;
+    /**
+     * Callback called when script fails to load
+     */
+    onError?: () => void;
+    /**
+     * Whether to remove the script tag when the component unmounts
+     * @default true
+     */
+    removeOnUnmount?: boolean;
+};
+/**
+ * Hook to dynamically load external scripts.
+ * Returns the loading status of the script.
+ *
+ * @param url - The URL of the script to load
+ * @param options - Optional callbacks and configuration
+ * @returns The current status of the script: 'idle' | 'loading' | 'ready' | 'error'
+ *
+ * @example
+ * ```tsx
+ * const status = useScript('https://example.com/script.js', {
+ *   onLoad: () => console.log('Script loaded'),
+ *   onError: () => console.error('Script failed to load'),
+ * });
+ *
+ * if (status === 'loading') return <div>Loading...</div>;
+ * if (status === 'error') return <div>Error loading script</div>;
+ * ```
+ */
+export declare const useScript: (url: string, options?: UseScriptOptions) => UseScriptStatus;

package/build/hooks/useScript.js

@@ -2,15 +2,67 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useScript = void 0;
 const react_1 = require("react");
-const useScript = (url) => {
+/**
+ * Hook to dynamically load external scripts.
+ * Returns the loading status of the script.
+ *
+ * @param url - The URL of the script to load
+ * @param options - Optional callbacks and configuration
+ * @returns The current status of the script: 'idle' | 'loading' | 'ready' | 'error'
+ *
+ * @example
+ * ```tsx
+ * const status = useScript('https://example.com/script.js', {
+ *   onLoad: () => console.log('Script loaded'),
+ *   onError: () => console.error('Script failed to load'),
+ * });
+ *
+ * if (status === 'loading') return <div>Loading...</div>;
+ * if (status === 'error') return <div>Error loading script</div>;
+ * ```
+ */
+const useScript = (url, options = {}) => {
+    const { onLoad, onError, removeOnUnmount = true } = options;
+    const [status, setStatus] = (0, react_1.useState)('idle');
+    const callbacksRef = (0, react_1.useRef)({ onLoad, onError });
+    // Keep callbacks ref updated
     (0, react_1.useEffect)(() => {
+        callbacksRef.current = { onLoad, onError };
+    }, [onLoad, onError]);
+    (0, react_1.useEffect)(() => {
+        // Find existing script safely (avoid CSS selector injection)
+        const existingScript = Array.from(document.querySelectorAll('script')).find((s) => s.src === url || s.getAttribute('src') === url);
+        if (existingScript) {
+            const isLoaded = existingScript.readyState ===
+                'complete' ||
+                existingScript.readyState ===
+                    'loaded';
+            setStatus(isLoaded ? 'ready' : 'loading');
+            return;
+        }
+        setStatus('loading');
         const script = document.createElement('script');
         script.src = url;
         script.async = true;
+        const handleLoad = () => {
+            setStatus('ready');
+            callbacksRef.current.onLoad?.();
+        };
+        const handleError = () => {
+            setStatus('error');
+            callbacksRef.current.onError?.();
+        };
+        script.addEventListener('load', handleLoad);
+        script.addEventListener('error', handleError);
         document.body.appendChild(script);
         return () => {
-            document.body.removeChild(script);
+            script.removeEventListener('load', handleLoad);
+            script.removeEventListener('error', handleError);
+            if (removeOnUnmount && script.parentNode) {
+                script.parentNode.removeChild(script);
+            }
         };
-    }, [url]);
+    }, [url, removeOnUnmount]);
+    return status;
 };
 exports.useScript = useScript;

package/build/hooks/useTheme.d.ts

@@ -1,2 +1,24 @@
-import { MouseEventHandler } from 'react';
-export declare const useTheme: () => [string, MouseEventHandler, boolean];
+export type ThemeMode = 'light' | 'dark';
+/**
+ * Hook to manage theme (light/dark) with localStorage persistence.
+ * Automatically detects system color scheme preference.
+ *
+ * @returns A tuple containing:
+ * - current theme mode ('light' | 'dark')
+ * - function to toggle between themes
+ * - boolean indicating if the component is mounted (useful for SSR)
+ *
+ * @example
+ * ```tsx
+ * const [theme, toggleTheme, mounted] = useTheme();
+ *
+ * if (!mounted) return null; // Avoid hydration mismatch
+ *
+ * return (
+ *   <button onClick={toggleTheme}>
+ *     Switch to {theme === 'light' ? 'dark' : 'light'} mode
+ *   </button>
+ * );
+ * ```
+ */
+export declare const useTheme: () => [ThemeMode, () => void, boolean];