From 6a910b211a7ab312043cce968e02bc04d8c3ec8d Mon Sep 17 00:00:00 2001
From: Damjan Savic <info@damjan-savic.com>
Date: Sun, 25 Jan 2026 12:03:24 +0100
Subject: [PATCH] auto-claude: subtask-4-5 - Add JSDoc to useScrollTracking.ts
 hook

---
 src/hooks/useScrollTracking.ts | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/src/hooks/useScrollTracking.ts b/src/hooks/useScrollTracking.ts
index 8eebbc7..d024bba 100644
--- a/src/hooks/useScrollTracking.ts
+++ b/src/hooks/useScrollTracking.ts
@@ -1,8 +1,37 @@
+/**
+ * Scroll Tracking Hook
+ * Tracks user scroll depth and sends events to Google Tag Manager
+ */
+
 import { useEffect, useRef } from 'react';
 import { trackScrollDepth } from '../services/gtm';
 
 /**
- * Hook to track scroll depth for GTM
+ * Custom hook to track scroll depth for GTM analytics
+ *
+ * Monitors user scroll behavior and triggers GTM events when the user reaches
+ * specific depth milestones (25%, 50%, 75%, 90%, 100%). Each milestone is
+ * tracked only once per page visit to avoid duplicate events.
+ *
+ * Features:
+ * - Debounced scroll event handling (100ms) for performance
+ * - Tracks depth milestones: 25%, 50%, 75%, 90%, 100%
+ * - Prevents duplicate tracking of the same milestone
+ * - Automatically resets tracking state on route changes
+ * - Checks initial scroll position on mount
+ *
+ * @example
+ * ```tsx
+ * function MyPage() {
+ *   useScrollTracking();
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @remarks
+ * This hook should be used at the page/route level component to ensure
+ * accurate tracking across navigation. The tracking state is automatically
+ * reset when the URL pathname changes.
  */
 export const useScrollTracking = () => {
   const trackedDepths = useRef(new Set<number>());