From 5a2022c2bb575bd598c8a47b3e6cd6953274b5c1 Mon Sep 17 00:00:00 2001
From: Chidimj <165854539+Chidimj@users.noreply.github.com>
Date: Sat, 27 Jun 2026 15:56:56 +0100
Subject: [PATCH] feat: add useDebounce hook, integration tests, and state
 management docs

---
 docs/state-management.md                      |  69 +++++++++
 src/components/common/TransactionHistory.tsx  |  23 ++-
 .../__tests__/TransactionHistory.test.tsx     |  54 +++++++
 src/hooks/__tests__/useDebounce.test.tsx      |  77 ++++++++++
 src/hooks/useDebounce.ts                      |  12 ++
 src/pages/LandingPage.tsx                     |   9 +-
 ...gPage.debouncedSearch.integration.test.tsx | 141 ++++++++++++++++++
 7 files changed, 375 insertions(+), 10 deletions(-)
 create mode 100644 docs/state-management.md
 create mode 100644 src/components/common/__tests__/TransactionHistory.test.tsx
 create mode 100644 src/hooks/__tests__/useDebounce.test.tsx
 create mode 100644 src/hooks/useDebounce.ts
 create mode 100644 src/pages/__tests__/LandingPage.debouncedSearch.integration.test.tsx

diff --git a/docs/state-management.md b/docs/state-management.md
new file mode 100644
index 0000000..24fa7c6
--- /dev/null
+++ b/docs/state-management.md
@@ -0,0 +1,69 @@
+# Client State Management
+
+## The Rule
+
+| Data type                                                               | Where it lives                           |
+| ----------------------------------------------------------------------- | ---------------------------------------- |
+| Server data (creators, holdings, activity feed)                         | React Query (`useQuery` / `useMutation`) |
+| Ephemeral UI state (modals, input values, selected tabs, loading flags) | Local `useState`                         |
+
+If the value came from an API response and needs to survive a component unmount or be shared across routes, put it in React Query. If it only controls what the user sees right now and can be re-derived on re-mount, use `useState`.
+
+## Query Invalidation vs Manual Refetch
+
+**Invalidate** after a mutation that changes server data:
+
+```ts
+const queryClient = useQueryClient();
+queryClient.invalidateQueries({ queryKey: queryKeys.creators.list() });
+```
+
+This marks cached data stale and lets React Query refetch in the background the next time the query is observed. Use this after a buy, sell, or profile update so all subscribers see fresh data automatically.
+
+**Refetch manually** only when you need to force an immediate reload independent of staleness — for example, a user-triggered "Refresh" button:
+
+```ts
+const { refetch } = useQuery({ queryKey: queryKeys.wallet.holdings(address), ... });
+<button onClick={() => refetch()}>Refresh</button>
+```
+
+Avoid calling `refetch()` inside effects or after mutations — that bypasses cache coordination and can race with invalidation.
+
+## Do Not Copy Server State into Local State
+
+Storing a React Query result in `useState` breaks cache coherence and causes stale UI after mutations.
+
+### Wrong
+
+```tsx
+function CreatorProfile({ id }: { id: string }) {
+	const { data } = useCreatorDetail(id);
+
+	// Never do this — local state diverges from the cache after mutations.
+	const [creator, setCreator] = useState(data);
+
+	return <div>{creator?.title}</div>;
+}
+```
+
+### Right
+
+```tsx
+function CreatorProfile({ id }: { id: string }) {
+	const { data: creator } = useCreatorDetail(id);
+
+	// Read directly from the query result — always in sync with the cache.
+	return <div>{creator?.title}</div>;
+}
+```
+
+## Ephemeral UI State Examples
+
+These belong in `useState`, not React Query:
+
+- Modal open/closed: `const [open, setOpen] = useState(false)`
+- Controlled input value: `const [query, setQuery] = useState('')`
+- Active tab: `const [activeTab, setActiveTab] = useState('overview')`
+- Optimistic loading flag: `const [submitting, setSubmitting] = useState(false)`
+
+None of these values need to survive a page navigation or be shared with another component tree, so there is no reason to put them in the server-state layer.
diff --git a/src/components/common/TransactionHistory.tsx b/src/components/common/TransactionHistory.tsx
index d55e537..d8d835c 100644
--- a/src/components/common/TransactionHistory.tsx
+++ b/src/components/common/TransactionHistory.tsx
@@ -159,6 +159,7 @@ const TransactionHistory: React.FC = () => {
 					return (
 						<div
 							key={tx.id}
+							data-testid={`activity-item-${tx.type}`}
 							className={cn(
 								'group rounded-xl border border-white/10 bg-white/[0.02] transition-all duration-200 hover:border-white/20 hover:bg-white/[0.04]',
 								isCompact && !isExpanded && 'py-2',
@@ -183,7 +184,7 @@ const TransactionHistory: React.FC = () => {
 											<div className="mt-1 flex items-center gap-3 text-xs text-white/50">
 												<span>{tx.amount} keys</span>
 												<span className="text-white/30">•</span>
-												<span>{tx.price} ETH</span>
+												<span>{tx.price} XLM</span>
 												<span className="text-white/30">•</span>
 												<span>{formatTimestamp(tx.timestamp)}</span>
 											</div>
@@ -193,9 +194,12 @@ const TransactionHistory: React.FC = () => {
 									{(!isCompact || isExpanded) && (
 										<div className="hidden shrink-0 items-center gap-4 text-right sm:flex">
 											<div className="text-sm">
-												<div className="font-semibold text-white">
-													{tx.type === 'buy' ? '+' : '-'}
-													{(tx.amount * tx.price).toFixed(4)} ETH
+												<div
+													className="font-semibold text-white"
+													data-testid={`tx-amount-${tx.id}`}
+												>
+													{tx.type === 'buy' ? '-' : '+'}
+													{(tx.amount * tx.price).toFixed(4)} XLM
 												</div>
 												<div className="text-xs text-white/50">
 													{tx.txHash}
@@ -213,9 +217,12 @@ const TransactionHistory: React.FC = () => {
 									{isCompact && !isExpanded && (
 										<div className="flex shrink-0 items-center gap-3">
 											<div className="text-right">
-												<div className="text-sm font-semibold text-white">
-													{tx.type === 'buy' ? '+' : '-'}
-													{(tx.amount * tx.price).toFixed(4)} ETH
+												<div
+													className="text-sm font-semibold text-white"
+													data-testid={`tx-amount-${tx.id}`}
+												>
+													{tx.type === 'buy' ? '-' : '+'}
+													{(tx.amount * tx.price).toFixed(4)} XLM
 												</div>
 											</div>
 											<Button
@@ -247,7 +254,7 @@ const TransactionHistory: React.FC = () => {
 									<div className="flex items-center gap-3 text-white/50">
 										<span>{tx.amount} keys</span>
 										<span className="text-white/30">•</span>
-										<span>{tx.price} ETH</span>
+										<span>{tx.price} XLM</span>
 										<span className="text-white/30">•</span>
 										<span>{formatTimestamp(tx.timestamp)}</span>
 										<span className="text-white/30">•</span>
diff --git a/src/components/common/__tests__/TransactionHistory.test.tsx b/src/components/common/__tests__/TransactionHistory.test.tsx
new file mode 100644
index 0000000..cc2ceec
--- /dev/null
+++ b/src/components/common/__tests__/TransactionHistory.test.tsx
@@ -0,0 +1,54 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import TransactionHistory from '@/components/common/TransactionHistory';
+
+// TransactionHistory reads localStorage during initialisation.
+beforeEach(() => {
+	vi.stubEnv('NODE_ENV', 'test');
+	localStorage.clear();
+});
+
+describe('TransactionHistory – activity feed sign prefix (integration)', () => {
+	it('buy event amount is prefixed with a minus sign', () => {
+		render(<TransactionHistory />);
+
+		// There is at least one buy activity item in the sample data.
+		const buyItems = screen.getAllByTestId('activity-item-buy');
+		expect(buyItems.length).toBeGreaterThan(0);
+
+		// For each buy row the visible amount must start with "-".
+		buyItems.forEach(item => {
+			const amountEl = item.querySelector('[data-testid^="tx-amount-"]');
+			expect(amountEl).not.toBeNull();
+			expect(amountEl!.textContent).toMatch(/^-/);
+		});
+	});
+
+	it('sell event amount is prefixed with a plus sign', () => {
+		render(<TransactionHistory />);
+
+		const sellItems = screen.getAllByTestId('activity-item-sell');
+		expect(sellItems.length).toBeGreaterThan(0);
+
+		sellItems.forEach(item => {
+			const amountEl = item.querySelector('[data-testid^="tx-amount-"]');
+			expect(amountEl).not.toBeNull();
+			expect(amountEl!.textContent).toMatch(/^\+/);
+		});
+	});
+
+	it('XLM suffix is present on both buy and sell amounts', () => {
+		render(<TransactionHistory />);
+
+		const allItems = [
+			...screen.getAllByTestId('activity-item-buy'),
+			...screen.getAllByTestId('activity-item-sell'),
+		];
+
+		allItems.forEach(item => {
+			const amountEl = item.querySelector('[data-testid^="tx-amount-"]');
+			expect(amountEl).not.toBeNull();
+			expect(amountEl!.textContent).toMatch(/XLM$/);
+		});
+	});
+});
diff --git a/src/hooks/__tests__/useDebounce.test.tsx b/src/hooks/__tests__/useDebounce.test.tsx
new file mode 100644
index 0000000..ad86907
--- /dev/null
+++ b/src/hooks/__tests__/useDebounce.test.tsx
@@ -0,0 +1,77 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useState } from 'react';
+import { useDebounce } from '@/hooks/useDebounce';
+
+describe('useDebounce – integration (fake timers)', () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it('does not update the debounced value before the delay elapses', () => {
+		const { result } = renderHook(() => {
+			const [value, setValue] = useState('initial');
+			const debounced = useDebounce(value, 300);
+			return { value, setValue, debounced };
+		});
+
+		act(() => {
+			result.current.setValue('updated');
+		});
+
+		// Immediately after the change the debounced value must still be the old one.
+		expect(result.current.debounced).toBe('initial');
+	});
+
+	it('updates the debounced value after the delay elapses', () => {
+		const { result } = renderHook(() => {
+			const [value, setValue] = useState('initial');
+			const debounced = useDebounce(value, 300);
+			return { value, setValue, debounced };
+		});
+
+		act(() => {
+			result.current.setValue('updated');
+		});
+
+		act(() => {
+			vi.advanceTimersByTime(300);
+		});
+
+		expect(result.current.debounced).toBe('updated');
+	});
+
+	it('resets the timer on each new value during the debounce window', () => {
+		const { result } = renderHook(() => {
+			const [value, setValue] = useState('a');
+			const debounced = useDebounce(value, 300);
+			return { value, setValue, debounced };
+		});
+
+		act(() => {
+			result.current.setValue('b');
+		});
+		act(() => {
+			vi.advanceTimersByTime(150);
+		});
+		// Still within the window — another update resets the timer.
+		act(() => {
+			result.current.setValue('c');
+		});
+		act(() => {
+			vi.advanceTimersByTime(150);
+		});
+		// Only 150 ms have passed since the last update, not yet 300 ms.
+		expect(result.current.debounced).toBe('a');
+
+		act(() => {
+			vi.advanceTimersByTime(150);
+		});
+		// Now the full 300 ms have elapsed since the last value change.
+		expect(result.current.debounced).toBe('c');
+	});
+});
diff --git a/src/hooks/useDebounce.ts b/src/hooks/useDebounce.ts
new file mode 100644
index 0000000..b01db7c
--- /dev/null
+++ b/src/hooks/useDebounce.ts
@@ -0,0 +1,12 @@
+import { useEffect, useState } from 'react';
+
+export function useDebounce<T>(value: T, delayMs: number): T {
+	const [debounced, setDebounced] = useState<T>(value);
+
+	useEffect(() => {
+		const timer = setTimeout(() => setDebounced(value), delayMs);
+		return () => clearTimeout(timer);
+	}, [value, delayMs]);
+
+	return debounced;
+}
diff --git a/src/pages/LandingPage.tsx b/src/pages/LandingPage.tsx
index b61b52c..b78916f 100644
--- a/src/pages/LandingPage.tsx
+++ b/src/pages/LandingPage.tsx
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useDebounce } from '@/hooks/useDebounce';
 import { LayoutGroup, motion } from 'framer-motion';
 import { useSearchParams } from 'react-router';
 import { courseService, type Course } from '@/services/course.service';
@@ -283,6 +284,7 @@ function LandingPage() {
 	const [isFilterLoading, setIsFilterLoading] = useState(false);
 	const [searchParams, setSearchParams] = useSearchParams();
 	const [searchQuery, setSearchQuery] = useState('');
+	const debouncedSearchQuery = useDebounce(searchQuery, 300);
 	const searchQueryRef = useRef<string>('');
 	const sortOptionRef = useRef<SortOption>('featured');
 	const PROFILE_TABS = ['overview', 'creations', 'collectors', 'activity'];
@@ -447,7 +449,10 @@ function LandingPage() {
 			setShowRetryBanner(false);
 			setFinalFetchError('');
 			try {
-				const data = await courseService.getCourses();
+				const params = debouncedSearchQuery.trim()
+					? { search: debouncedSearchQuery.trim() }
+					: undefined;
+				const data = await courseService.getCourses(params);
 				if (data && data.length > 0) {
 					setCreators(data);
 				} else {
@@ -482,7 +487,7 @@ function LandingPage() {
 		};
 
 		fetchCreators();
-	}, [fetchRetryAttempt, fetchRequestId]);
+	}, [fetchRetryAttempt, fetchRequestId, debouncedSearchQuery]);
 
 	const searchSuggestions = useMemo(() => {
 		const fromCategories = creators
diff --git a/src/pages/__tests__/LandingPage.debouncedSearch.integration.test.tsx b/src/pages/__tests__/LandingPage.debouncedSearch.integration.test.tsx
new file mode 100644
index 0000000..d4beb98
--- /dev/null
+++ b/src/pages/__tests__/LandingPage.debouncedSearch.integration.test.tsx
@@ -0,0 +1,141 @@
+/**
+ * Integration test for the debounced creator search (#489).
+ *
+ * Strategy: render a minimal wrapper that uses useDebounce with the real hook
+ * (fake timers) and calls courseService.getCourses in a useEffect, identical
+ * to what LandingPage does. This avoids the URL-sync / price-refresh side
+ * effects that make call-count assertions brittle when testing the full page.
+ */
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useEffect, useState } from 'react';
+import { useDebounce } from '@/hooks/useDebounce';
+import { courseService, type Course } from '@/services/course.service';
+
+vi.mock('@/services/course.service', () => ({
+	courseService: { getCourses: vi.fn() },
+}));
+
+const mockGetCourses = vi.mocked(courseService.getCourses);
+
+const creator: Course = {
+	id: '1',
+	title: 'Creator Alpha',
+	description: 'Digital artist',
+	price: 0.05,
+	priceStroops: 500_000,
+	creatorShareSupply: 100,
+	instructorId: 'creator-a',
+	category: 'Art',
+	level: 'BEGINNER',
+	isVerified: true,
+};
+
+// Minimal harness — mirrors the search → debounce → API pattern from LandingPage.
+function DebouncedSearchHarness({ delay = 300 }: { delay?: number }) {
+	const [query, setQuery] = useState('');
+	const debouncedQuery = useDebounce(query, delay);
+
+	useEffect(() => {
+		const params = debouncedQuery.trim()
+			? { search: debouncedQuery.trim() }
+			: undefined;
+		courseService.getCourses(params);
+	}, [debouncedQuery]);
+
+	return (
+		<input
+			data-testid="search"
+			placeholder="Search creators by name or handle..."
+			value={query}
+			onChange={e => setQuery(e.target.value)}
+		/>
+	);
+}
+
+describe('Debounced search – integration (#489)', () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+		mockGetCourses.mockReset();
+		mockGetCourses.mockResolvedValue([creator]);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it('fires no API calls during the typing burst (before the delay elapses)', () => {
+		render(<DebouncedSearchHarness delay={300} />);
+
+		// The initial render triggers one call (debouncedQuery = '').
+		act(() => { vi.advanceTimersByTime(300); });
+		expect(mockGetCourses).toHaveBeenCalledTimes(1);
+		mockGetCourses.mockClear();
+
+		const input = screen.getByTestId('search');
+
+		// Type five characters, each 50 ms apart — all within the 300 ms window.
+		for (const value of ['a', 'ab', 'abc', 'abcd', 'abcde']) {
+			act(() => {
+				fireEvent.change(input, { target: { value } });
+				vi.advanceTimersByTime(50);
+			});
+		}
+
+		// Debounce has NOT expired yet → no additional API calls.
+		expect(mockGetCourses).not.toHaveBeenCalled();
+	});
+
+	it('fires exactly one API call after the debounce delay with the final value', () => {
+		render(<DebouncedSearchHarness delay={300} />);
+
+		// Flush the initial render call.
+		act(() => { vi.advanceTimersByTime(300); });
+		mockGetCourses.mockClear();
+
+		const input = screen.getByTestId('search');
+
+		// Rapid-fire five keystrokes within the 300 ms window.
+		for (const value of ['a', 'ab', 'abc', 'abcd', 'abcde']) {
+			act(() => {
+				fireEvent.change(input, { target: { value } });
+				vi.advanceTimersByTime(50);
+			});
+		}
+
+		// Advance past the full debounce window for the last keystroke.
+		act(() => { vi.advanceTimersByTime(300); });
+
+		// Exactly one call, using the final typed value.
+		expect(mockGetCourses).toHaveBeenCalledTimes(1);
+		expect(mockGetCourses).toHaveBeenCalledWith({ search: 'abcde' });
+	});
+
+	it('omits the search param when the input is cleared', () => {
+		render(<DebouncedSearchHarness delay={300} />);
+
+		act(() => { vi.advanceTimersByTime(300); });
+		mockGetCourses.mockClear();
+
+		const input = screen.getByTestId('search');
+
+		// Type a value, let it settle.
+		act(() => {
+			fireEvent.change(input, { target: { value: 'hello' } });
+		});
+		act(() => { vi.advanceTimersByTime(300); });
+		expect(mockGetCourses).toHaveBeenLastCalledWith({ search: 'hello' });
+
+		mockGetCourses.mockClear();
+
+		// Clear the input.
+		act(() => {
+			fireEvent.change(input, { target: { value: '' } });
+		});
+		act(() => { vi.advanceTimersByTime(300); });
+
+		// Empty query → no search param (component passes undefined).
+		expect(mockGetCourses).toHaveBeenCalledTimes(1);
+		expect(mockGetCourses).toHaveBeenCalledWith(undefined);
+	});
+});