platform-codebase/@packages/@hooks/react-hooks/src/use-click-outside.ts

import { useEffect, useRef, RefObject } from 'react';

/**
 * Hook for detecting clicks outside an element
 *
 * Useful for closing dropdowns, modals, or popups when clicking outside.
 * Handles both mouse and touch events.
 *
 * @param handler - Callback function to run when click outside is detected
 * @returns Ref to attach to the element
 *
 * @example
 * ```typescript
 * function Dropdown() {
 *   const [isOpen, setIsOpen] = useState(false);
 *   const dropdownRef = useClickOutside<HTMLDivElement>(() => {
 *     setIsOpen(false);
 *   });
 *
 *   return (
 *     <div ref={dropdownRef}>
 *       <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
 *       {isOpen && (
 *         <div className="dropdown-menu">
 *           <MenuItem>Option 1</MenuItem>
 *           <MenuItem>Option 2</MenuItem>
 *         </div>
 *       )}
 *     </div>
 *   );
 * }
 * ```
 */
export function useClickOutside<T extends HTMLElement = HTMLElement>(
  handler: (event: MouseEvent | TouchEvent) => void
): RefObject<T | null> {
  const ref = useRef<T>(null);

  useEffect(() => {
    const handleClickOutside = (event: MouseEvent | TouchEvent) => {
      if (ref.current && !ref.current.contains(event.target as Node)) {
        handler(event);
      }
    };

    // Add event listeners
    document.addEventListener('mousedown', handleClickOutside);
    document.addEventListener('touchstart', handleClickOutside);

    return () => {
      // Cleanup
      document.removeEventListener('mousedown', handleClickOutside);
      document.removeEventListener('touchstart', handleClickOutside);
    };
  }, [handler]);

  return ref;
}