refactor: add JSDoc for custom hooks

src/hooks/use-close-listener.ts

@@ -2,6 +2,11 @@ import { useEffect } from 'react';
 
 import { onCloseModals } from '@/lib/modal';
 
+/**
+ * A custom React hook that registers a listener function to be called when modals are to be closed.
+ *
+ * @param {Function} listener - The function to be called when modals are to be closed.
+ */
 export function useCloseListener(listener: () => void) {
   useEffect(() => {
     const unsubscribe = onCloseModals(listener);

src/hooks/use-copy.ts

@@ -1,5 +1,13 @@
 import { useState, useCallback } from 'react';
 
+/**
+ * A custom React hook to copy text to the clipboard with a temporary state indication.
+ *
+ * @param {number} [timeout=1500] - The duration in milliseconds for which the `copying` state remains true. Defaults to 1500 milliseconds.
+ * @returns {{ copy: (content: string) => void, copying: boolean }} An object containing:
+ *   - copy: The function to copy content to the clipboard.
+ *   - copying: A boolean indicating if a copy operation is in progress.
+ */
 export function useCopy(timeout = 1500) {
   const [copying, setCopying] = useState(false);
 

src/hooks/use-keyboard-button.ts

@@ -1,6 +1,12 @@
 import { useCallback } from 'react';
 import type { KeyboardEvent } from 'react';
 
+/**
+ * A custom React hook that creates a keyboard event handler for 'Enter' and 'Space' keys.
+ *
+ * @param {Function} actionCallback - The function to be called when 'Enter' or 'Space' is pressed.
+ * @returns {Function} A keyboard event handler function that triggers the action callback.
+ */
 export const useKeyboardButton = (
   actionCallback: () => void,
 ): ((event: KeyboardEvent<HTMLElement>) => void) => {

src/hooks/use-local-storage.ts

@@ -2,6 +2,14 @@ import { type Dispatch, type SetStateAction, useEffect, useState } from 'react';
 
 type SetValue<T> = Dispatch<SetStateAction<T>>;
 
+/**
+ * A custom React hook to manage state with localStorage persistence.
+ *
+ * @template T
+ * @param {string} key - The key under which the value is stored in localStorage.
+ * @param {T} fallback - The fallback value to use if there is no value in localStorage.
+ * @returns {[T, SetValue<T>]} An array containing the stateful value and a function to update it.
+ */
 export function useLocalStorage<T>(key: string, fallback: T): [T, SetValue<T>] {
   const [value, setValue] = useState(fallback);
 

src/hooks/use-sound-effect.ts

@@ -3,6 +3,16 @@ import { Howl } from 'howler';
 
 import { useSSR } from './use-ssr';
 
+/**
+ * A custom React hook to manage sound effects using Howler.js.
+ *
+ * @param {string} src - The source URL of the sound file.
+ * @param {number} [volume=1] - The initial volume of the sound, ranging from 0.0 to 1.0.
+ * @returns {{ play: () => void, stop: () => void, pause: () => void }} An object containing control functions for the sound:
+ *   - play: Function to play the sound.
+ *   - stop: Function to stop the sound.
+ *   - pause: Function to pause the sound.
+ */
 export function useSoundEffect(src: string, volume: number = 1) {
   const { isBrowser } = useSSR();
 

src/hooks/use-sound.ts

@@ -6,6 +6,24 @@ import { subscribe } from '@/lib/event';
 import { useSSR } from './use-ssr';
 import { FADE_OUT } from '@/constants/events';
 
+/**
+ * A custom React hook to manage sound playback using Howler.js with additional features.
+ *
+ * This hook initializes a Howl instance for playing sound effects in the browser,
+ * and provides control functions to play, stop, pause, and fade out the sound.
+ * It also handles loading state management and supports event subscription for fade-out effects.
+ *
+ * @param {string} src - The source URL of the sound file.
+ * @param {Object} [options] - Options for sound playback.
+ * @param {boolean} [options.loop=false] - Whether the sound should loop.
+ * @param {number} [options.volume=0.5] - The initial volume of the sound, ranging from 0.0 to 1.0.
+ * @returns {{ play: () => void, stop: () => void, pause: () => void, fadeOut: (duration: number) => void, isLoading: boolean }} An object containing control functions for the sound:
+ *   - play: Function to play the sound.
+ *   - stop: Function to stop the sound.
+ *   - pause: Function to pause the sound.
+ *   - fadeOut: Function to fade out the sound over a given duration.
+ *   - isLoading: A boolean indicating if the sound is currently loading.
+ */
 export function useSound(
   src: string,
   options: { loop?: boolean; volume?: number } = {},

src/hooks/use-ssr.ts

@@ -1,3 +1,10 @@
+/**
+ * A custom React hook to determine if the code is running in a browser or server environment.
+ *
+ * @returns {{ isBrowser: boolean, isServer: boolean }} An object containing:
+ *   - isBrowser: A boolean indicating if the code is running in a browser environment.
+ *   - isServer: A boolean indicating if the code is running in a server environment.
+ */
 export function useSSR() {
   const isDOM =
     typeof window !== 'undefined' &&