add comment for hooks

1 files changed, 30 insertions, 7 deletions

diff --git a/apps/web/src/hooks/use-timeline-zoom.ts b/apps/web/src/hooks/use-timeline-zoom.ts
index 16d20d7e..c8780f9a 100644
--- a/apps/web/src/hooks/use-timeline-zoom.ts
+++ b/apps/web/src/hooks/use-timeline-zoom.ts
@@ -15,15 +15,30 @@ interface UseTimelineZoomReturn {
   handleWheel: (e: React.WheelEvent) => void;

 }

 

+/**

+ * useTimelineZoom

+ *

+ * Custom hook to manage zoom logic for a timeline component.

+ * Handles zoom state, step calculation, level changes, and mouse wheel zooming (with ctrl/meta).

+ */

 export function useTimelineZoom(): UseTimelineZoomReturn {

+  // Current zoom level (1 = default)

   const [zoomLevel, setZoomLevel] = useState(1);

 

+  /**

+   * Calculate the current zoom step based on the zoom level and a base step constant.

+   * Ensures minimum step is 1 (prevents zero or negative step).

+   */

   const zoomStep = useMemo(

     () =>

       Math.max(1, Math.round(zoomLevel / TIMELINE_CONSTANTS.ZOOM_STEP_BASE)),

     [zoomLevel]

   );

 

+  /**

+   * Update the zoom level using a given step.

+   * The zoom level is clamped to a minimum value defined in constants.

+   */

   const handleChangeZoomStep = useCallback((newStep: number) => {

     setZoomLevel(

       Math.max(

@@ -33,6 +48,10 @@ export function useTimelineZoom(): UseTimelineZoomReturn {
     );

   }, []);

 

+  /**

+   * Update the zoom level directly.

+   * The new value is clamped between the defined minimum and maximum levels.

+   */

   const handleChangeZoomLevel = useCallback((newLevel: number) => {

     setZoomLevel(

       Math.max(

@@ -42,7 +61,10 @@ export function useTimelineZoom(): UseTimelineZoomReturn {
     );

   }, []);

 

-  // Mouse wheel zoom, ctrl/meta gesture

+  /**

+   * Handle zooming using mouse wheel + ctrl/meta key (like browser zoom).

+   * Prevents default browser behavior and updates zoom level accordingly.

+   */

   const handleWheel = useCallback((e: React.WheelEvent) => {

     if (e.ctrlKey || e.metaKey) {

       e.preventDefault?.();

@@ -59,12 +81,13 @@ export function useTimelineZoom(): UseTimelineZoomReturn {
     }

   }, []);

 

+  // Return all handlers and state values for use in timeline components

   return {

-    zoomLevel,

-    zoomStep,

-    setZoomLevel,

-    handleChangeZoomStep,

-    handleChangeZoomLevel,

-    handleWheel,

+    zoomLevel, // Current zoom level

+    zoomStep, // Current zoom step (calculated from zoomLevel)

+    setZoomLevel, // Directly set the zoom level (accepts value or updater function)

+    handleChangeZoomStep, // Change zoom by step value

+    handleChangeZoomLevel, // Change zoom by level value

+    handleWheel, // Handler for mouse wheel zooming

   };

 }