refactor: write JSDoc for libs

src/lib/event.ts

@@ -1,9 +1,24 @@
+/**
+ * Dispatches a custom event with an optional detail payload.
+ *
+ * @template T
+ * @param {string} eventName - The name of the event to be dispatched.
+ * @param {T} [detail] - Optional data to be passed with the event.
+ */
 export function dispatch<T>(eventName: string, detail?: T) {
   const event = new CustomEvent(eventName, { detail });
 
   document.dispatchEvent(event);
 }
 
+/**
+ * Subscribes a listener function to a custom event.
+ *
+ * @template T
+ * @param {string} eventName - The name of the event to listen for.
+ * @param {(e: T) => void} listener - The function to be called when the event is dispatched.
+ * @returns {Function} A function to unsubscribe the listener from the event.
+ */
 export function subscribe<T>(eventName: string, listener: (e: T) => void) {
   const handler = (event: Event) => {
     if ('detail' in event) {
@@ -18,6 +33,12 @@ export function subscribe<T>(eventName: string, listener: (e: T) => void) {
   return () => unsubscribe(eventName, handler);
 }
 
+/**
+ * Unsubscribes a listener function from a custom event.
+ *
+ * @param {string} eventName - The name of the event to unsubscribe from.
+ * @param {(e: Event) => void} listener - The function to be removed from the event listeners.
+ */
 export function unsubscribe(eventName: string, listener: (e: Event) => void) {
   document.removeEventListener(eventName, listener);
 }

src/lib/modal.ts

@@ -1,10 +1,19 @@
 import { dispatch, subscribe } from './event';
 import { CLOSE_MODALS } from '@/constants/events';
 
+/**
+ * Dispatches the CLOSE_MODALS event to signal that modals should be closed.
+ */
 export function closeModals() {
   dispatch(CLOSE_MODALS);
 }
 
+/**
+ * Subscribes a listener function to the CLOSE_MODALS event.
+ *
+ * @param {() => void} listener - The function to be called when the CLOSE_MODALS event is dispatched.
+ * @returns {Function} A function to unsubscribe the listener from the CLOSE_MODALS event.
+ */
 export function onCloseModals(listener: () => void) {
   const unsubscribe = subscribe(CLOSE_MODALS, listener);
 

src/lib/motion.ts

@@ -7,6 +7,11 @@ type Motion = {
   };
 };
 
+/**
+ * Creates a fade motion object with opacity transition.
+ *
+ * @returns {Motion} An object containing the hidden and show states for a fade transition.
+ */
 export function fade(): Motion {
   return {
     hidden: { opacity: 0 },
@@ -14,6 +19,13 @@ export function fade(): Motion {
   };
 }
 
+/**
+ * Creates a scale motion object with scaling transition.
+ *
+ * @param {number} [from=0.85] - The initial scale value for the hidden state.
+ * @param {number} [to=1] - The final scale value for the show state.
+ * @returns {Motion} An object containing the hidden and show states for a scale transition.
+ */
 export function scale(from = 0.85, to = 1): Motion {
   return {
     hidden: { scale: from },
@@ -21,6 +33,13 @@ export function scale(from = 0.85, to = 1): Motion {
   };
 }
 
+/**
+ * Creates a slide motion object with horizontal sliding transition.
+ *
+ * @param {number} [from=-10] - The initial x position for the hidden state.
+ * @param {number} [to=0] - The final x position for the show state.
+ * @returns {Motion} An object containing the hidden and show states for a horizontal slide transition.
+ */
 export function slideX(from = -10, to = 0): Motion {
   return {
     hidden: { x: from },
@@ -28,6 +47,13 @@ export function slideX(from = -10, to = 0): Motion {
   };
 }
 
+/**
+ * Creates a slide motion object with vertical sliding transition.
+ *
+ * @param {number} [from=-10] - The initial y position for the hidden state.
+ * @param {number} [to=0] - The final y position for the show state.
+ * @returns {Motion} An object containing the hidden and show states for a vertical slide transition.
+ */
 export function slideY(from = -10, to = 0): Motion {
   return {
     hidden: { y: from },
@@ -35,6 +61,15 @@ export function slideY(from = -10, to = 0): Motion {
   };
 }
 
+/**
+ * Combines multiple motion objects into a single motion object.
+ *
+ * This function merges the hidden and show states of the provided motion objects
+ * into a single motion object.
+ *
+ * @param {...Motion} motions - The motion objects to be combined.
+ * @returns {Motion} An object containing the combined hidden and show states.
+ */
 export function mix(...motions: Array<Motion>): Motion {
   let hidden = {};
   let show = {};

src/lib/sounds.ts

@@ -1,5 +1,11 @@
 import { sounds } from '@/data/sounds';
 
+/**
+ * Counts the total number of sounds across all categories.
+ *
+ * @param {boolean} [round=false] - Whether to round the count down to the nearest multiple of 5.
+ * @returns {number} The total count of sounds, optionally rounded down.
+ */
 export function count(round: boolean = false) {
   let count = 0;