@arolariu/components 1.0.0 → 2.0.0

package/src/hooks/useClipboard.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Options for the `useClipboard` hook.
+ */
+export interface UseClipboardOptions {
+  /**
+   * The duration in milliseconds after which the `copied` state resets to `false`.
+   *
+   * @defaultValue 2000
+   */
+  timeout?: number;
+}
+
+/**
+ * Return type for the `useClipboard` hook.
+ */
+export interface UseClipboardReturn {
+  /**
+   * Whether the text was successfully copied to the clipboard.
+   */
+  copied: boolean;
+
+  /**
+   * Copies the provided text to the clipboard.
+   *
+   * @param text - The text to copy.
+   * @returns A promise that resolves when the copy operation completes.
+   */
+  copy: (text: string) => Promise<void>;
+
+  /**
+   * The error that occurred during the copy operation, or `null` if no error occurred.
+   */
+  error: Error | null;
+}
+
+/**
+ * Copies text to the clipboard with success/error state management.
+ *
+ * @remarks
+ * This hook provides a simple interface for copying text to the clipboard using
+ * the Clipboard API. It manages the `copied` state that automatically resets
+ * after a configurable timeout, and handles errors gracefully when the Clipboard
+ * API is unavailable or the operation fails.
+ *
+ * The hook is SSR-safe and will handle the case where `navigator.clipboard` is
+ * not available (e.g., in non-secure contexts or older browsers).
+ *
+ * @param options - Configuration options for the hook.
+ * @returns An object containing the copied state, copy function, and any error.
+ *
+ * @example
+ * ```tsx
+ * function CopyButton({textToCopy}: {textToCopy: string}) {
+ *   const {copied, copy, error} = useClipboard({timeout: 3000});
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => copy(textToCopy)}>
+ *         {copied ? "Copied!" : "Copy to clipboard"}
+ *       </button>
+ *       {error && <span>Failed to copy: {error.message}</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ShareLink({url}: {url: string}) {
+ *   const {copied, copy} = useClipboard();
+ *
+ *   return (
+ *     <button onClick={() => copy(url)} disabled={copied}>
+ *       {copied ? "✓ Copied" : "Share link"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useClipboard(options: UseClipboardOptions = {}): UseClipboardReturn {
+  const {timeout = 2000} = options;
+
+  const [copied, setCopied] = React.useState(false);
+  const [error, setError] = React.useState<Error | null>(null);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const copy = React.useCallback(
+    async (text: string): Promise<void> => {
+      // Clear any existing timeout
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+
+      // Reset error state
+      setError(null);
+
+      try {
+        // Check if Clipboard API is available
+        if (typeof globalThis.navigator === "undefined" || !globalThis.navigator.clipboard) {
+          throw new Error("Clipboard API is not available");
+        }
+
+        await globalThis.navigator.clipboard.writeText(text);
+        setCopied(true);
+
+        // Reset copied state after timeout
+        timeoutRef.current = setTimeout(() => {
+          setCopied(false);
+          timeoutRef.current = null;
+        }, timeout);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err : new Error("Failed to copy to clipboard");
+
+        setError(errorMessage);
+        setCopied(false);
+        console.error("Copy to clipboard failed:", errorMessage);
+      }
+    },
+    [timeout],
+  );
+
+  // Cleanup timeout on unmount
+  React.useEffect(() => {
+    return () => {
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return {copied, copy, error};
+}

package/src/hooks/useControllableState.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Options for configuring controllable state behavior.
+ *
+ * @typeParam T - The type of the state value.
+ */
+export interface UseControllableStateOptions<T> {
+  /**
+   * The controlled value from props. When provided, the component operates in controlled mode.
+   */
+  controlled?: T;
+  /**
+   * The default value used when the component is uncontrolled.
+   */
+  defaultValue: T;
+  /**
+   * Callback fired when the internal state changes in controlled mode.
+   *
+   * @param value - The new state value.
+   */
+  onChange?: (value: T) => void;
+}
+
+/**
+ * Manages state that can be either controlled or uncontrolled.
+ *
+ * @remarks
+ * This hook enables components to support both controlled and uncontrolled patterns
+ * seamlessly. When a `controlled` value is provided, it takes precedence; otherwise,
+ * the hook manages internal state initialized with `defaultValue`.
+ *
+ * @typeParam T - The type of the state value.
+ * @param options - Configuration object for controllable state.
+ * @returns A tuple containing the current state value and a setter function.
+ *
+ * @example
+ * ```tsx
+ * function CustomInput({value, defaultValue = "", onChange}) {
+ *   const [internalValue, setValue] = useControllableState({
+ *     controlled: value,
+ *     defaultValue,
+ *     onChange,
+ *   });
+ *
+ *   return (
+ *     <input
+ *       type="text"
+ *       value={internalValue}
+ *       onChange={(e) => setValue(e.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useControllableState<T>(options: UseControllableStateOptions<T>): [T, (value: T | ((prev: T) => T)) => void] {
+  const {controlled, defaultValue, onChange} = options;
+  const [uncontrolledState, setUncontrolledState] = React.useState<T>(defaultValue);
+  const isControlled = controlled !== undefined;
+  const value = isControlled ? controlled : uncontrolledState;
+
+  const setValue = React.useCallback(
+    (nextValue: T | ((prev: T) => T)) => {
+      if (!isControlled) {
+        setUncontrolledState((currentValue) => {
+          const resolvedValue = typeof nextValue === "function" ? (nextValue as (prev: T) => T)(currentValue) : nextValue;
+          onChange?.(resolvedValue);
+          return resolvedValue;
+        });
+      } else {
+        const resolvedValue = typeof nextValue === "function" ? (nextValue as (prev: T) => T)(controlled as T) : nextValue;
+        onChange?.(resolvedValue);
+      }
+    },
+    [isControlled, onChange, controlled],
+  );
+
+  return [value, setValue];
+}

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,
+  );
+}