From 52f003f25ab8d3124ddf4880c44f874206d7f988 Mon Sep 17 00:00:00 2001
From: gantiro <gantiro396@gmail.com>
Date: Tue, 15 Jul 2025 22:56:56 +0700
Subject: add comment for hooks

---
 apps/web/src/hooks/use-timeline-zoom.ts | 37 ++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

(limited to 'apps/web/src/hooks/use-timeline-zoom.ts')

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
   };
 }
-- 
cgit v1.3.1