fix(customize): debounce username preview requests (JhaSourav07#2452)

## Description

Fixes JhaSourav07#2451 

### Summary

This PR debounces username-based live preview requests in the customize
dashboard to reduce unnecessary API calls while typing.

### Changes Made

- Added a reusable `useDebounce` hook in `lib/hooks/useDebounce.ts`
- Debounced username updates by 400ms before triggering preview requests
- Generated a separate debounced preview query string for live preview
requests
- Kept export snippets and URL synchronization responsive and unchanged
- Reused the existing `AbortController` implementation to cancel stale
requests
- Added unit tests for `useDebounce` to verify delayed execution
behavior

### Result

**Before**
- A request was triggered on every username keystroke
- Multiple in-flight requests could occur while typing

**After**
- Preview requests are only sent after the user pauses typing for 400ms
- Stale requests are cancelled
- Reduced API usage and improved preview stability

## Pillar

- [ ] 🎨 Pillar 1 — New Theme Design
- [ ] 📐 Pillar 2 — Geometric SVG Improvement
- [ ] 🕐 Pillar 3 — Timezone Logic Optimization
- [x] 🛠️ Other (Bug fix, refactoring, docs)

## Visual Preview

N/A (behavioral improvement)

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
- [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
- [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
- [ ] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have starred the repo.
- [x] I have made sure that I have only one commit to merge in this PR.
- [x] The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animations, correct fonts).
- [x] (Recommended) I joined the CommitPulse Discord community for
contributor discussions, mentorship, and faster PR support.

Author: JhaSourav07

app/customize/page.tsx

@@ -20,6 +20,7 @@ import type {
   Language,
   Timezone,
 } from './types';
+import { useDebounce } from '@/hooks/useDebounce';
 import { getExportSnippet, buildQueryParams } from './utils';
 
 // ─── Main Page ────────────────────────────────────────────────────────────────
@@ -54,6 +55,7 @@ function CustomizePageInner(): ReactElement {
   const [svgState, setSvgState] = useState<'idle' | 'loading' | 'loaded' | 'error'>('idle');
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const trimmedUsername = username.trim();
+  const debouncedUsername = useDebounce(trimmedUsername, 400);
   const hasUsername = trimmedUsername.length > 0;
   const isRandomTheme = theme === 'random';
 
@@ -146,7 +148,32 @@ function CustomizePageInner(): ReactElement {
     language,
     timezone,
   });
-  const previewSrc = `/api/streak?${queryString}`;
+
+  const previewQueryString = buildQueryParams({
+    username: debouncedUsername,
+    theme,
+    bgHex,
+    accentHex,
+    textHex,
+    scale,
+    speed,
+    font,
+    year,
+    radius,
+    size,
+    hideTitle,
+    hideBackground,
+    hideStats,
+    viewMode,
+    deltaFormat,
+    badgeWidth,
+    badgeHeight,
+    grace,
+    language,
+    timezone,
+  });
+
+  const previewSrc = `/api/streak?${previewQueryString}`;
 
   // On change sync state to URL
   useEffect(() => {
@@ -169,6 +196,13 @@ function CustomizePageInner(): ReactElement {
       return;
     }
 
+    if (!validateGitHubUsername(debouncedUsername)) {
+      setSvgContent('');
+      setSvgState('error');
+      setErrorMessage("That doesn't look like a valid GitHub username");
+      return;
+    }
+
     setSvgState('loading');
     const controller = new AbortController();
 
@@ -235,7 +269,7 @@ function CustomizePageInner(): ReactElement {
       });
 
     return () => controller.abort();
-  }, [previewSrc, hasUsername, trimmedUsername]);
+  }, [previewSrc, hasUsername, debouncedUsername]);
 
   const exportSnippet = getExportSnippet(exportFormat, queryString);
 

lib/hooks/useDebounce.test.ts

@@ -0,0 +1,62 @@
+import { renderHook, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { useDebounce } from './useDebounce';
+
+describe('useDebounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('updates only after the delay', () => {
+    const { result, rerender } = renderHook(({ value }) => useDebounce(value, 400), {
+      initialProps: { value: 'a' },
+    });
+
+    expect(result.current).toBe('a');
+
+    rerender({ value: 'ab' });
+    rerender({ value: 'abc' });
+
+    act(() => {
+      vi.advanceTimersByTime(399);
+    });
+
+    expect(result.current).toBe('a');
+
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+
+    expect(result.current).toBe('abc');
+  });
+
+  it('resets the timer when value changes repeatedly', () => {
+    const { result, rerender } = renderHook(({ value }) => useDebounce(value, 400), {
+      initialProps: { value: 'a' },
+    });
+
+    rerender({ value: 'ab' });
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    rerender({ value: 'abc' });
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(result.current).toBe('a');
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(result.current).toBe('abc');
+  });
+});

lib/hooks/useDebounce.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState } from 'react';
+
+export function useDebounce<T>(value: T, delay: number) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}