@arolariu/components 0.5.0 → 1.1.0

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/useFocusManager.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import * as React from "react";
+
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not(:disabled)",
+  "input:not(:disabled)",
+  "select:not(:disabled)",
+  "textarea:not(:disabled)",
+  '[tabindex]:not([tabindex="-1"])',
+  "[contenteditable]",
+].join(", ");
+
+/**
+ * Represents the focus movement helpers returned by {@link useFocusManager}.
+ */
+interface FocusManager {
+  /**
+   * Focuses the first focusable element in the container.
+   */
+  focusFirst: () => void;
+  /**
+   * Focuses the last focusable element in the container.
+   */
+  focusLast: () => void;
+  /**
+   * Focuses the next focusable element after the currently focused one.
+   */
+  focusNext: () => void;
+  /**
+   * Focuses the previous focusable element before the currently focused one.
+   */
+  focusPrevious: () => void;
+}
+
+/**
+ * Provides programmatic focus movement helpers for a container element.
+ *
+ * @param containerRef - Ref pointing to the container whose focusable descendants should be managed.
+ * @returns Focus helpers for moving to the first, last, next, or previous focusable descendant.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = React.useRef<HTMLDivElement>(null);
+ * const {focusNext, focusPrevious} = useFocusManager(containerRef);
+ * ```
+ */
+export function useFocusManager(containerRef: React.RefObject<HTMLElement | null>): FocusManager {
+  const getFocusable = React.useCallback((): HTMLElement[] => {
+    if (!containerRef.current) {
+      return [];
+    }
+
+    return [...containerRef.current.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter(
+      (element) => !element.hasAttribute("disabled") && element.tabIndex >= 0,
+    );
+  }, [containerRef]);
+
+  const focusFirst = React.useCallback(() => {
+    getFocusable()[0]?.focus();
+  }, [getFocusable]);
+
+  const focusLast = React.useCallback(() => {
+    const items = getFocusable();
+
+    items.at(-1)?.focus();
+  }, [getFocusable]);
+
+  const focusNext = React.useCallback(() => {
+    const items = getFocusable();
+    const current = document.activeElement;
+    const index = items.indexOf(current as HTMLElement);
+    const next = items[index + 1] ?? items[0];
+
+    next?.focus();
+  }, [getFocusable]);
+
+  const focusPrevious = React.useCallback(() => {
+    const items = getFocusable();
+    const current = document.activeElement;
+    const index = items.indexOf(current as HTMLElement);
+    const previous = items[index - 1] ?? items.at(-1);
+
+    previous?.focus();
+  }, [getFocusable]);
+
+  return {focusFirst, focusLast, focusNext, focusPrevious};
+}

package/src/hooks/useFocusVisible.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Represents the focus handlers returned by {@link useFocusVisible}.
+ *
+ * @remarks
+ * Spread these handlers onto the interactive element that should respond to keyboard
+ * focus visibility. They coordinate transient focus styling without owning rendering.
+ */
+interface FocusVisibleProps {
+  /**
+   * Called when the target receives focus.
+   */
+  onFocus: (event: React.FocusEvent) => void;
+  /**
+   * Called when the target loses focus.
+   */
+  onBlur: () => void;
+}
+
+/**
+ * Detects whether the current focus originated from keyboard navigation.
+ *
+ * @remarks
+ * Tracks global keyboard and pointer input so consumers can render focus rings only when
+ * users are tabbing through the interface. This mirrors the intent of `:focus-visible`
+ * while remaining available to JavaScript-driven components and custom states.
+ *
+ * @returns An object containing the current focus-visible state and focus handlers to spread on the target element.
+ *
+ * @example
+ * ```tsx
+ * const {isFocusVisible, focusProps} = useFocusVisible();
+ *
+ * return (
+ *   <button
+ *     type="button"
+ *     {...focusProps}
+ *     className={isFocusVisible ? "ring" : undefined}>
+ *     Click
+ *   </button>
+ * );
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible | MDN :focus-visible}
+ */
+export function useFocusVisible(): {
+  isFocusVisible: boolean;
+  focusProps: FocusVisibleProps;
+} {
+  const [isFocusVisible, setIsFocusVisible] = React.useState(false);
+  const isKeyboardRef = React.useRef(false);
+
+  React.useEffect(() => {
+    const onKeyDown = () => {
+      isKeyboardRef.current = true;
+    };
+    const onPointerDown = () => {
+      isKeyboardRef.current = false;
+    };
+
+    globalThis.document.addEventListener("keydown", onKeyDown, true);
+    globalThis.document.addEventListener("pointerdown", onPointerDown, true);
+
+    return () => {
+      globalThis.document.removeEventListener("keydown", onKeyDown, true);
+      globalThis.document.removeEventListener("pointerdown", onPointerDown, true);
+    };
+  }, []);
+
+  const focusProps = React.useMemo<FocusVisibleProps>(
+    () => ({
+      onFocus: (_event: React.FocusEvent) => {
+        if (isKeyboardRef.current) {
+          setIsFocusVisible(true);
+        }
+      },
+      onBlur: () => {
+        setIsFocusVisible(false);
+      },
+    }),
+    [],
+  );
+
+  return {isFocusVisible, focusProps};
+}

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/useIsMobile.tsx

@@ -1,42 +1,21 @@
 "use client";
-import * as React from "react";
 
-const MOBILE_BREAKPOINT = 768;
+import {useMediaQuery} from "./useMediaQuery";
 
 /**
  * A custom React hook that detects whether the current device is a mobile device
- * based on the screen width.
- * This hook uses a media query to check if the viewport width is less than the defined
- * mobile breakpoint (768px). It updates the state when the window size changes.
- * @returns Returns true if the viewport width is less than the mobile breakpoint,
- * false otherwise.
+ * based on the screen width (viewport < 768px).
+ *
+ * @returns `true` if the viewport width is less than 768px, `false` otherwise.
+ *
  * @example
  * ```tsx
  * function MyComponent() {
  *   const isMobile = useIsMobile();
- *
- *   return (
- *     <div>
- *       {isMobile ? 'Mobile View' : 'Desktop View'}
- *     </div>
- *   );
+ *   return <div>{isMobile ? 'Mobile View' : 'Desktop View'}</div>;
  * }
  * ```
  */
 export function useIsMobile(): boolean {
-  const [isMobile, setIsMobile] = React.useState<boolean | null>(null);
-
-  React.useEffect(() => {
-    const mql = globalThis.window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
-    const onChange = () => {
-      // eslint-disable-next-line react-hooks-extra/no-direct-set-state-in-use-effect
-      setIsMobile(globalThis.window.innerWidth < MOBILE_BREAKPOINT);
-    };
-    mql.addEventListener("change", onChange);
-    // eslint-disable-next-line react-hooks-extra/no-direct-set-state-in-use-effect
-    setIsMobile(globalThis.window.innerWidth < MOBILE_BREAKPOINT);
-    return () => mql.removeEventListener("change", onChange);
-  }, []);
-
-  return Boolean(isMobile);
+  return useMediaQuery("(max-width: 767px)");
 }