@arolariu/components 1.0.0 → 1.1.0

package/src/hooks/useDebounce.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Debounces a value, delaying updates until after the specified delay has elapsed.
+ *
+ * @remarks
+ * This hook returns a debounced version of the provided value that only updates
+ * after the value has stopped changing for the specified delay. Useful for optimizing
+ * performance in scenarios like search inputs, where you want to avoid triggering
+ * expensive operations on every keystroke.
+ *
+ * The debounce timer resets on every value change and cleans up automatically on unmount.
+ *
+ * @typeParam T - The type of the value being debounced.
+ * @param value - The value to debounce.
+ * @param delay - The delay in milliseconds before the debounced value updates.
+ * @returns The debounced value.
+ *
+ * @example
+ * ```tsx
+ * function SearchInput() {
+ *   const [searchTerm, setSearchTerm] = useState("");
+ *   const debouncedSearchTerm = useDebounce(searchTerm, 500);
+ *
+ *   useEffect(() => {
+ *     // Expensive search operation
+ *     performSearch(debouncedSearchTerm);
+ *   }, [debouncedSearchTerm]);
+ *
+ *   return <input value={searchTerm} onChange={(e) => setSearchTerm(e.target.value)} />;
+ * }
+ * ```
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = React.useState<T>(value);
+
+  React.useEffect(() => {
+    const timeoutId = globalThis.setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      globalThis.clearTimeout(timeoutId);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/hooks/useEventCallback.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Creates a stable callback reference that always calls the latest version of the provided function.
+ *
+ * @remarks
+ * Unlike `useCallback`, this hook returns a stable function reference that never changes,
+ * but always invokes the most recent version of the callback. This is useful when you need
+ * to pass callbacks to optimized child components or effects without triggering re-renders
+ * when dependencies change.
+ *
+ * The returned function is safe to use in dependency arrays because its identity never changes.
+ *
+ * @typeParam Args - The tuple type of the callback's arguments.
+ * @typeParam Return - The return type of the callback.
+ * @param callback - The function to wrap with a stable reference.
+ * @returns A stable function reference that invokes the latest callback.
+ *
+ * @example
+ * ```tsx
+ * function SearchInput({onSearch}) {
+ *   const [query, setQuery] = useState("");
+ *   // stableOnSearch never changes identity, but always calls the latest onSearch
+ *   const stableOnSearch = useEventCallback(onSearch);
+ *
+ *   useEffect(() => {
+ *     const timer = setTimeout(() => stableOnSearch(query), 500);
+ *     return () => clearTimeout(timer);
+ *   }, [query, stableOnSearch]); // Safe to include in deps
+ *
+ *   return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
+ * }
+ * ```
+ */
+export function useEventCallback<Args extends unknown[], Return>(callback: (...args: Args) => Return): (...args: Args) => Return {
+  const callbackRef = React.useRef(callback);
+
+  React.useLayoutEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  return React.useCallback((...args: Args) => {
+    return callbackRef.current(...args);
+  }, []);
+}

package/src/hooks/useId.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Generates a unique, stable identifier that is safe for server-side rendering.
+ *
+ * @remarks
+ * This hook wraps React's `useId` and optionally prepends a custom prefix.
+ * The generated ID remains stable across re-renders and matches between server
+ * and client, making it ideal for associating form labels with inputs or
+ * managing accessible ARIA relationships.
+ *
+ * @param prefix - Optional string to prepend to the generated ID.
+ * @returns A unique identifier string.
+ *
+ * @example
+ * ```tsx
+ * function FormField({label}) {
+ *   const id = useId("field");
+ *
+ *   return (
+ *     <div>
+ *       <label htmlFor={id}>{label}</label>
+ *       <input id={id} type="text" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://react.dev/reference/react/useId | React useId}
+ */
+export function useId(prefix?: string): string {
+  const reactId = React.useId();
+  return prefix ? `${prefix}-${reactId}` : reactId;
+}

package/src/hooks/useIntersectionObserver.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Observes element visibility using the Intersection Observer API.
+ *
+ * @remarks
+ * This hook creates an IntersectionObserver that watches the provided element
+ * reference and returns the latest `IntersectionObserverEntry`. It's useful
+ * for implementing lazy loading, infinite scroll, animations on scroll, and
+ * tracking element visibility.
+ *
+ * The observer automatically disconnects when the component unmounts or when
+ * the element reference changes. The hook is SSR-safe and returns `null` when
+ * running on the server or when the observer is not yet initialized.
+ *
+ * @param ref - A React ref object pointing to the element to observe.
+ * @param options - Optional IntersectionObserver configuration (threshold, root, rootMargin).
+ * @returns The latest IntersectionObserverEntry or null if not intersecting yet.
+ *
+ * @example
+ * ```tsx
+ * function LazyImage({src, alt}: {src: string; alt: string}) {
+ *   const imageRef = useRef<HTMLImageElement>(null);
+ *   const entry = useIntersectionObserver(imageRef, {threshold: 0.1});
+ *
+ *   return (
+ *     <img
+ *       ref={imageRef}
+ *       src={entry?.isIntersecting ? src : undefined}
+ *       alt={alt}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function AnimateOnScroll({children}: {children: React.ReactNode}) {
+ *   const ref = useRef<HTMLDivElement>(null);
+ *   const entry = useIntersectionObserver(ref, {threshold: 0.5});
+ *   const isVisible = entry?.isIntersecting ?? false;
+ *
+ *   return (
+ *     <div ref={ref} className={isVisible ? "fade-in" : "hidden"}>
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useIntersectionObserver(
+  ref: React.RefObject<Element | null>,
+  options?: IntersectionObserverInit,
+): IntersectionObserverEntry | null {
+  const [entry, setEntry] = React.useState<IntersectionObserverEntry | null>(null);
+
+  React.useEffect(() => {
+    const element = ref.current;
+
+    // SSR safety: IntersectionObserver is not available on server
+    if (typeof globalThis.IntersectionObserver === "undefined" || !element) {
+      return;
+    }
+
+    const observer = new globalThis.IntersectionObserver(([observerEntry]) => {
+      if (observerEntry) {
+        setEntry(observerEntry);
+      }
+    }, options);
+
+    observer.observe(element);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [ref, options?.threshold, options?.root, options?.rootMargin]);
+
+  return entry;
+}

package/src/hooks/useInterval.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Executes a callback function at specified intervals with automatic cleanup.
+ *
+ * @remarks
+ * This hook provides a declarative interface for `setInterval` that automatically
+ * handles cleanup on unmount and ensures the latest callback is always invoked
+ * (preventing stale closures). Setting the delay to `null` pauses the interval,
+ * which is useful for implementing play/pause functionality.
+ *
+ * Unlike raw `setInterval`, this hook guarantees that the interval is cleared
+ * when the component unmounts or when the delay changes, preventing memory leaks
+ * and unexpected behavior.
+ *
+ * @param callback - The function to execute at each interval.
+ * @param delay - The interval delay in milliseconds, or `null` to pause the interval.
+ *
+ * @example
+ * ```tsx
+ * function Timer() {
+ *   const [count, setCount] = useState(0);
+ *
+ *   useInterval(() => {
+ *     setCount((c) => c + 1);
+ *   }, 1000);
+ *
+ *   return <div>Count: {count}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function PausableTimer() {
+ *   const [count, setCount] = useState(0);
+ *   const [isRunning, setIsRunning] = useState(true);
+ *
+ *   useInterval(
+ *     () => {
+ *       setCount((c) => c + 1);
+ *     },
+ *     isRunning ? 1000 : null,
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       <div>Count: {count}</div>
+ *       <button onClick={() => setIsRunning(!isRunning)}>
+ *         {isRunning ? "Pause" : "Resume"}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useInterval(callback: () => void, delay: number | null): void {
+  const savedCallback = React.useRef(callback);
+
+  // Update ref to latest callback on every render to avoid stale closures
+  React.useEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+
+  React.useEffect(() => {
+    // Don't schedule if delay is null
+    if (delay === null) {
+      return;
+    }
+
+    const intervalId = globalThis.setInterval(() => {
+      savedCallback.current();
+    }, delay);
+
+    return () => {
+      globalThis.clearInterval(intervalId);
+    };
+  }, [delay]);
+}

package/src/hooks/useLocalStorage.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Persists state to localStorage with SSR safety and JSON serialization.
+ *
+ * @remarks
+ * This hook synchronizes state with localStorage, allowing data to persist
+ * across page refreshes and browser sessions. It is SSR-safe and returns the
+ * initial value on the server until hydration completes. The hook also syncs
+ * state across tabs/windows via the `storage` event and handles JSON parse
+ * errors gracefully by falling back to the initial value.
+ *
+ * @typeParam T - The type of the value being stored.
+ * @param key - The localStorage key to store the value under.
+ * @param initialValue - The default value to use if no value is found in localStorage.
+ * @returns A tuple containing the current value and a setter function.
+ *
+ * @example
+ * ```tsx
+ * function UserSettings() {
+ *   const [theme, setTheme] = useLocalStorage("theme", "light");
+ *
+ *   return (
+ *     <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
+ *       Toggle theme (current: {theme})
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ShoppingCart() {
+ *   const [cart, setCart] = useLocalStorage<Product[]>("cart", []);
+ *
+ *   return (
+ *     <button onClick={() => setCart((prev) => [...prev, newProduct])}>
+ *       Add to cart ({cart.length} items)
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void] {
+  const [storedValue, setStoredValue] = React.useState<T>(() => {
+    // SSR safety: return initial value on server
+    if (typeof globalThis.window === "undefined") {
+      return initialValue;
+    }
+
+    try {
+      const item = globalThis.window.localStorage.getItem(key);
+
+      return item !== null ? (JSON.parse(item) as T) : initialValue;
+    } catch (error) {
+      console.error(`Error reading localStorage key "${key}":`, error);
+
+      return initialValue;
+    }
+  });
+
+  const setValue = React.useCallback(
+    (value: T | ((prev: T) => T)) => {
+      try {
+        setStoredValue((currentValue) => {
+          const valueToStore = value instanceof Function ? value(currentValue) : value;
+
+          if (typeof globalThis.window !== "undefined") {
+            globalThis.window.localStorage.setItem(key, JSON.stringify(valueToStore));
+          }
+
+          return valueToStore;
+        });
+      } catch (error) {
+        console.error(`Error setting localStorage key "${key}":`, error);
+      }
+    },
+    [key],
+  );
+
+  React.useEffect(() => {
+    // SSR safety: window is not available on server
+    if (typeof globalThis.window === "undefined") {
+      return;
+    }
+
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key !== key || event.storageArea !== globalThis.window.localStorage) {
+        return;
+      }
+
+      try {
+        const newValue = event.newValue !== null ? (JSON.parse(event.newValue) as T) : initialValue;
+
+        setStoredValue(newValue);
+      } catch (error) {
+        console.error(`Error parsing storage event for key "${key}":`, error);
+      }
+    };
+
+    globalThis.window.addEventListener("storage", handleStorageChange);
+
+    return () => {
+      globalThis.window.removeEventListener("storage", handleStorageChange);
+    };
+  }, [key, initialValue]);
+
+  return [storedValue, setValue];
+}

package/src/hooks/useMergedRefs.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Merges multiple refs into a single callback ref.
+ *
+ * @remarks
+ * This hook is essential when you need to attach multiple refs to the same element,
+ * such as combining a forwarded ref with an internal ref for measurements or
+ * imperative operations. All provided refs will receive the same element instance.
+ *
+ * Supports all ref types: callback refs, mutable ref objects, and `null`/`undefined`.
+ *
+ * @typeParam T - The type of the element being referenced.
+ * @param refs - An array of refs to merge. Can include callback refs, ref objects, or undefined.
+ * @returns A callback ref that updates all provided refs.
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = React.forwardRef<HTMLDivElement, Props>((props, forwardedRef) => {
+ *   const internalRef = useRef<HTMLDivElement>(null);
+ *   const mergedRef = useMergedRefs(forwardedRef, internalRef);
+ *
+ *   return <div ref={mergedRef}>Content</div>;
+ * });
+ * ```
+ */
+export function useMergedRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T> {
+  return React.useCallback(
+    (element: T | null) => {
+      for (const ref of refs) {
+        if (!ref) {
+          continue;
+        }
+
+        if (typeof ref === "function") {
+          ref(element);
+        } else {
+          // Mutable ref object
+          (ref as React.MutableRefObject<T | null>).current = element;
+        }
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    refs,
+  );
+}

package/src/hooks/useOnClickOutside.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Detects clicks or touch events outside a referenced element.
+ *
+ * @remarks
+ * This hook is commonly used for implementing dropdown menus, modals, and popovers
+ * that should close when the user interacts outside their boundaries. It listens
+ * to both mouse and touch events to ensure broad device compatibility.
+ *
+ * The event listeners are automatically cleaned up when the component unmounts.
+ *
+ * @param ref - A ref object pointing to the element to monitor.
+ * @param handler - Callback invoked when a click or touch occurs outside the element.
+ *
+ * @example
+ * ```tsx
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const dropdownRef = useRef<HTMLDivElement>(null);
+ *
+ *   useOnClickOutside(dropdownRef, () => setIsOpen(false));
+ *
+ *   return (
+ *     <div ref={dropdownRef}>
+ *       {isOpen && <DropdownMenu />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useOnClickOutside(ref: React.RefObject<HTMLElement | null>, handler: (event: MouseEvent | TouchEvent) => void): void {
+  React.useEffect(() => {
+    const listener = (event: MouseEvent | TouchEvent) => {
+      const element = ref.current;
+
+      // Do nothing if clicking ref's element or descendent elements
+      if (!element || element.contains(event.target as Node)) {
+        return;
+      }
+
+      handler(event);
+    };
+
+    globalThis.document.addEventListener("mousedown", listener);
+    globalThis.document.addEventListener("touchstart", listener);
+
+    return () => {
+      globalThis.document.removeEventListener("mousedown", listener);
+      globalThis.document.removeEventListener("touchstart", listener);
+    };
+  }, [ref, handler]);
+}

package/src/hooks/usePrevious.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Tracks and returns the previous value of a state or prop.
+ *
+ * @remarks
+ * This hook stores the value from the previous render cycle, allowing you to compare
+ * current and previous values. On the initial render, it returns `undefined` since
+ * there is no previous value yet.
+ *
+ * Useful for detecting changes, implementing undo functionality, or creating
+ * animations based on value transitions.
+ *
+ * @typeParam T - The type of the value being tracked.
+ * @param value - The current value to track.
+ * @returns The value from the previous render, or `undefined` on the first render.
+ *
+ * @example
+ * ```tsx
+ * function Counter() {
+ *   const [count, setCount] = useState(0);
+ *   const previousCount = usePrevious(count);
+ *
+ *   return (
+ *     <div>
+ *       <p>Current: {count}</p>
+ *       <p>Previous: {previousCount ?? "N/A"}</p>
+ *       <button onClick={() => setCount(count + 1)}>Increment</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = React.useRef<T | undefined>(undefined);
+
+  React.useEffect(() => {
+    ref.current = value;
+  }, [value]);
+
+  return ref.current;
+}

package/src/hooks/useThrottle.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Throttles a callback function, limiting how often it can be invoked.
+ *
+ * @remarks
+ * This hook returns a throttled version of the provided callback that can only
+ * be executed once per specified interval. Subsequent calls within the interval
+ * are ignored. Useful for rate-limiting expensive operations triggered by high-frequency
+ * events like scrolling, resizing, or mouse movement.
+ *
+ * Unlike debouncing, throttling ensures the callback is invoked at regular intervals
+ * during continuous events, providing more predictable execution timing.
+ *
+ * @typeParam Args - The tuple type of the callback's arguments.
+ * @param callback - The function to throttle.
+ * @param delay - The minimum interval in milliseconds between invocations.
+ * @returns A throttled version of the callback.
+ *
+ * @example
+ * ```tsx
+ * function ScrollTracker() {
+ *   const [scrollPos, setScrollPos] = useState(0);
+ *
+ *   const handleScroll = useThrottle(() => {
+ *     setScrollPos(window.scrollY);
+ *   }, 200);
+ *
+ *   useEffect(() => {
+ *     window.addEventListener("scroll", handleScroll);
+ *     return () => window.removeEventListener("scroll", handleScroll);
+ *   }, [handleScroll]);
+ *
+ *   return <p>Scroll position: {scrollPos}</p>;
+ * }
+ * ```
+ */
+export function useThrottle<Args extends unknown[]>(callback: (...args: Args) => void, delay: number): (...args: Args) => void {
+  const lastRunRef = React.useRef(0);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const callbackRef = React.useRef(callback);
+
+  React.useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  React.useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        globalThis.clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return React.useCallback(
+    (...args: Args) => {
+      const now = Date.now();
+      const timeSinceLastRun = now - lastRunRef.current;
+
+      if (timeSinceLastRun >= delay) {
+        callbackRef.current(...args);
+        lastRunRef.current = now;
+      } else {
+        if (timeoutRef.current) {
+          globalThis.clearTimeout(timeoutRef.current);
+        }
+
+        timeoutRef.current = globalThis.setTimeout(() => {
+          callbackRef.current(...args);
+          lastRunRef.current = Date.now();
+        }, delay - timeSinceLastRun);
+      }
+    },
+    [delay],
+  );
+}

package/src/hooks/useTimeout.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Executes a callback after a specified delay with automatic cleanup.
+ *
+ * @remarks
+ * This hook wraps `setTimeout` and automatically clears the timeout when the component
+ * unmounts or when the delay changes. Setting `delay` to `null` disables the timeout.
+ *
+ * The timeout is reset whenever the `callback` or `delay` changes, ensuring the most
+ * recent callback is always executed.
+ *
+ * @param callback - The function to execute after the delay.
+ * @param delay - The delay in milliseconds, or `null` to disable the timeout.
+ *
+ * @example
+ * ```tsx
+ * function DelayedMessage() {
+ *   const [visible, setVisible] = useState(false);
+ *
+ *   useTimeout(() => {
+ *     setVisible(true);
+ *   }, 3000);
+ *
+ *   return visible ? <p>Message appeared!</p> : <p>Waiting...</p>;
+ * }
+ * ```
+ */
+export function useTimeout(callback: () => void, delay: number | null): void {
+  const savedCallback = React.useRef(callback);
+
+  React.useLayoutEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+
+  React.useEffect(() => {
+    if (delay === null) {
+      return;
+    }
+
+    const timeoutId = globalThis.setTimeout(() => {
+      savedCallback.current();
+    }, delay);
+
+    return () => {
+      globalThis.clearTimeout(timeoutId);
+    };
+  }, [delay]);
+}