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

import { useState, useCallback } from 'react';

/**
 * Return type for useToggle hook
 */
export interface UseToggleReturn {
  /**
   * Current boolean value
   */
  value: boolean;

  /**
   * Toggle the value
   */
  toggle: () => void;

  /**
   * Set value to true
   */
  setTrue: () => void;

  /**
   * Set value to false
   */
  setFalse: () => void;

  /**
   * Set value directly
   */
  setValue: (value: boolean) => void;
}

/**
 * Hook for managing boolean state with helpful utilities
 *
 * Provides toggle, setTrue, and setFalse helpers in addition
 * to the raw setValue function.
 *
 * @param initialValue - Initial boolean value
 * @returns Object with value and control functions
 *
 * @example
 * ```typescript
 * function Modal() {
 *   const modal = useToggle(false);
 *
 *   return (
 *     <div>
 *       <button onClick={modal.setTrue}>Open Modal</button>
 *       {modal.value && (
 *         <div className="modal">
 *           <p>Modal Content</p>
 *           <button onClick={modal.setFalse}>Close</button>
 *         </div>
 *       )}
 *     </div>
 *   );
 * }
 * ```
 */
export function useToggle(initialValue: boolean = false): UseToggleReturn {
  const [value, setValue] = useState<boolean>(initialValue);

  const toggle = useCallback(() => {
    setValue((prev) => !prev);
  }, []);

  const setTrue = useCallback(() => {
    setValue(true);
  }, []);

  const setFalse = useCallback(() => {
    setValue(false);
  }, []);

  return {
    value,
    toggle,
    setTrue,
    setFalse,
    setValue,
  };
}