Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

refactor(frontend): migrate filter/search debounce to use-debounce npm

Sergey Kozyrenko17451e75dd41
diff --git a/frontend/package.json b/frontend/package.json
index 862af285..48d94e4d 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -90,6 +90,7 @@
"tailwind-merge": "^3.6.0",
"tiptap-markdown": "^0.9.0",
"tw-animate-css": "^1.4.0",
+ "use-debounce": "^10.1.1",
"vaul": "^1.1.2",
"zod": "^4.4.3"
},
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
index ca0c64af..237fe8ea 100644
--- a/frontend/pnpm-lock.yaml
+++ b/frontend/pnpm-lock.yaml
@@ -224,6 +224,9 @@ importers:
tw-animate-css:
specifier: ^1.4.0
version: 1.4.0
+ use-debounce:
+ specifier: ^10.1.1
+ version: 10.1.1([email protected])
vaul:
specifier: ^1.1.2
@@ -5708,6 +5711,12 @@ packages:
'@types/react':
optional: true
+ resolution: {integrity: sha512-kvds8BHR2k28cFsxW8k3nc/tRga2rs1RHYCqmmGqb90MEeE++oALwzh2COiuBLO1/QXiOuShXoSN2ZpWnMmvuQ==}
+ engines: {node: '>= 16.0.0'}
+ peerDependencies:
+ react: '*'
+
resolution: {integrity: sha512-tpZZ+EX0gaghDAiFR37hj5MgY6ZN55kLiPkJsKxBMZ6GZdOSPJXiOzPM984oPYZ5AnehYx5WQp1+ME8I/P/pRA==}
peerDependencies:
@@ -12025,6 +12034,10 @@ snapshots:
optionalDependencies:
'@types/react': 19.2.14
+ dependencies:
+ react: 19.2.6
+
dependencies:
react: 19.2.6
diff --git a/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts b/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
index 64898e85..dfeef411 100644
--- a/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
+++ b/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
@@ -1,7 +1,7 @@
import { useCallback, useMemo, useState } from 'react';
import { useNavigate, useSearchParams } from 'react-router-dom';
+import { useDebounce } from 'use-debounce';
-import { useDebouncedValue } from '@/hooks/use-debounced-value';
import { useLatestRef } from '@/hooks/use-latest-ref';
import { useTableQueryFilterReader } from '@/hooks/use-table-query-filter';
import { mergeHrefWithSearchParams } from '@/lib/url-params';
@@ -222,7 +222,7 @@ export function useDetailNavigation<T extends { id: string }>({
const [internalSearchQuery, setInternalSearchQuery] = useState(defaultSearchQuery ?? '');
const isSearchControlled = searchQuery !== undefined;
const activeSearchQuery = isSearchControlled ? searchQuery : internalSearchQuery;
- const debouncedSearchQuery = useDebouncedValue(activeSearchQuery, searchDebounceMs ?? DEFAULT_SEARCH_DEBOUNCE_MS);
+ const [debouncedSearchQuery] = useDebounce(activeSearchQuery, searchDebounceMs ?? DEFAULT_SEARCH_DEBOUNCE_MS);
const setSearchQuery = useCallback(
(next: string) => {
diff --git a/frontend/src/components/ui/data-table.test.tsx b/frontend/src/components/ui/data-table.test.tsx
index f1be2b37..8392e1c0 100644
--- a/frontend/src/components/ui/data-table.test.tsx
+++ b/frontend/src/components/ui/data-table.test.tsx
@@ -293,6 +293,194 @@ describe('DataTable — controlled filter projection', () => {
await waitFor(() => expect(emitted.at(-1)).toBe('seed'));
expect((input as HTMLInputElement).value).toBe('seed');
});
+
+ it('mounts with a deep-linked filterValue and shows the X clear button immediately', () => {
+ // Deep links land on the page with `?q=alpha` already in the URL —
+ // the parent passes that value down at first render, the input should
+ // be populated, and the trailing X should be available right away.
+ const emitted: string[] = [];
+
+ render(<FilterHost emitted={emitted} initialValue="alpha" />, { wrapper: Wrapper });
+
+ const input = screen.getByPlaceholderText('Filter...') as HTMLInputElement;
+ expect(input.value).toBe('alpha');
+ // No emission happened — we accepted the prop, we didn't echo it back.
+ expect(emitted).toEqual([]);
+
+ // X button is rendered because the input is non-empty.
+ const inputGroup = input.closest('[data-slot="input-group"]');
+ expect(within(inputGroup as HTMLElement).getByRole('button')).toBeInTheDocument();
+ });
+
+ it('coalesces burst typing into a single emit with the last-typed value', async () => {
+ // We type six characters back-to-back. The 150ms debounce should
+ // collapse the burst to a single outbound call — sequential prefix
+ // commits would defeat the debounce and hammer the URL writer.
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+
+ render(<FilterHost emitted={emitted} />, { wrapper: Wrapper });
+
+ const input = screen.getByPlaceholderText('Filter...');
+ await user.type(input, 'foobar');
+
+ await waitFor(() => expect(emitted.at(-1)).toBe('foobar'));
+
+ // No intermediate prefixes — only the final value lands.
+ expect(emitted).toEqual(['foobar']);
+ });
+
+ it('does not write to the upstream on unmount with a pending debounce', async () => {
+ // If the user types and immediately navigates away, the in-flight
+ // timer should be cancelled by `useDebouncedCallback` so the dead
+ // component can't push a stale value into the parent (which by then
+ // may belong to a different page).
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+
+ const { unmount } = render(<FilterHost emitted={emitted} />, { wrapper: Wrapper });
+
+ await user.type(screen.getByPlaceholderText('Filter...'), 'gone', { delay: 5 });
+
+ // Unmount before the debounce settles.
+ unmount();
+
+ // Give any leftover timer time to misfire.
+ await new Promise((resolve) => setTimeout(resolve, 400));
+
+ // Nothing made it upstream — the timer was cancelled by the hook's
+ // unmount cleanup.
+ expect(emitted).toEqual([]);
+ });
+
+ it('keeps two DataTables on one page independent (settings/prompts shape)', async () => {
+ // `/settings/prompts` mounts an Agent table and a Tool table on the
+ // same route. Typing in one input must not leak into the other —
+ // both DataTableFilter instances own private state, with separate
+ // `lastEmittedReference`s and timers.
+ const emittedAgent: string[] = [];
+ const emittedTool: string[] = [];
+ const user = userEvent.setup();
+
+ const TwoTablesHost = () => {
+ const [agent, setAgent] = useState('');
+ const [tool, setTool] = useState('');
+
+ return (
+ <>
+ <DataTable<Row>
+ columns={COLUMNS}
+ data={ROWS}
+ filterColumn="name"
+ filterPlaceholder="Agent filter..."
+ filterValue={agent}
+ onFilterChange={(next) => {
+ emittedAgent.push(next);
+ setAgent(next);
+ }}
+ />
+ <DataTable<Row>
+ columns={COLUMNS}
+ data={ROWS}
+ filterColumn="name"
+ filterPlaceholder="Tool filter..."
+ filterValue={tool}
+ onFilterChange={(next) => {
+ emittedTool.push(next);
+ setTool(next);
+ }}
+ />
+ </>
+ );
+ };
+
+ render(<TwoTablesHost />, { wrapper: Wrapper });
+
+ const agentInput = screen.getByPlaceholderText('Agent filter...');
+ const toolInput = screen.getByPlaceholderText('Tool filter...');
+
+ await user.type(agentInput, 'agX');
+ await waitFor(() => expect(emittedAgent.at(-1)).toBe('agX'));
+
+ // Tool table never saw anything.
+ expect(emittedTool).toEqual([]);
+ expect((toolInput as HTMLInputElement).value).toBe('');
+
+ // Now type in the tool input; agent must stay frozen.
+ await user.type(toolInput, 'toY');
+ await waitFor(() => expect(emittedTool.at(-1)).toBe('toY'));
+
+ expect((agentInput as HTMLInputElement).value).toBe('agX');
+ expect(emittedAgent).toEqual(['agX']);
+ });
+
+ it('accepts a back-button-style external clear without re-emitting the old value', async () => {
+ // History pop: user typed `'foo'`, then hit back. The router resets
+ // `filterValue` to `''`. The input should snap to `''` without
+ // re-emitting `'foo'` from a stale timer or sync effect.
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+ let setExternal: ((next: string) => void) | undefined;
+
+ render(
+ <FilterHost
+ emitted={emitted}
+ onSetValueRef={(setter) => {
+ setExternal = setter;
+ }}
+ />,
+ { wrapper: Wrapper },
+ );
+
+ const input = screen.getByPlaceholderText('Filter...');
+ await user.type(input, 'foo');
+ await waitFor(() => expect(emitted.at(-1)).toBe('foo'));
+
+ // Simulate the browser back button clearing `?q=`. The external
+ // setter bypasses `onFilterChange` (which is the realistic shape —
+ // a real router pop doesn't echo through our handler), so we measure
+ // the absence of further emits rather than a `''` arrival.
+ const indexOfFoo = emitted.lastIndexOf('foo');
+ expect(setExternal).toBeDefined();
+ act(() => setExternal!(''));
+
+ await new Promise((resolve) => setTimeout(resolve, 400));
+
+ // The input cleared; no leftover timer pushed `'foo'` back upstream.
+ expect((input as HTMLInputElement).value).toBe('');
+ expect(emitted.slice(indexOfFoo + 1)).not.toContain('foo');
+ });
+
+ it('survives rapid alternation between typing and X clicks', async () => {
+ // Stress: type, clear, type, clear — three rounds back to back.
+ // Each round must end with a clean `''` upstream and an empty input.
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+
+ render(<FilterHost emitted={emitted} />, { wrapper: Wrapper });
+
+ const input = screen.getByPlaceholderText('Filter...');
+
+ for (const round of ['one', 'two', 'three']) {
+ await user.type(input, round);
+ await waitFor(() => expect(emitted.at(-1)).toBe(round));
+
+ const inputGroup = input.closest('[data-slot="input-group"]');
+ const clearButton = within(inputGroup as HTMLElement).getByRole('button');
+ await user.click(clearButton);
+ await waitFor(() => expect((input as HTMLInputElement).value).toBe(''));
+ }
+
+ await new Promise((resolve) => setTimeout(resolve, 400));
+
+ // Final state: input empty, last emit is the clear from round three.
+ expect((input as HTMLInputElement).value).toBe('');
+ expect(emitted.at(-1)).toBe('');
+ // Every round's value made it through cleanly.
+ expect(emitted).toContain('one');
+ expect(emitted).toContain('two');
+ expect(emitted).toContain('three');
+ });
});
describe('DataTable — uncontrolled filter is still routed through the same input', () => {
diff --git a/frontend/src/components/ui/data-table.tsx b/frontend/src/components/ui/data-table.tsx
index a09170c4..e94a2964 100644
--- a/frontend/src/components/ui/data-table.tsx
+++ b/frontend/src/components/ui/data-table.tsx
@@ -41,6 +41,7 @@ import {
useState,
} from 'react';
import { useLocation } from 'react-router-dom';
+import { useDebouncedCallback } from 'use-debounce';
import { Button } from '@/components/ui/button';
import { ContextMenu, ContextMenuContent, ContextMenuTrigger } from '@/components/ui/context-menu';
@@ -54,7 +55,6 @@ import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '@/
import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '@/components/ui/input-group';
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';
-import { useDebouncedCallback } from '@/hooks/use-debounced-callback';
import { useEffectAfterMount } from '@/hooks/use-effect-after-mount';
import { useLatestRef } from '@/hooks/use-latest-ref';
import { usePageStorageKeys } from '@/hooks/use-page-storage-keys';
diff --git a/frontend/src/components/ui/input-search.test.tsx b/frontend/src/components/ui/input-search.test.tsx
new file mode 100644
index 00000000..5d4dc87e
--- /dev/null
+++ b/frontend/src/components/ui/input-search.test.tsx
@@ -0,0 +1,215 @@
+import type { ReactNode } from 'react';
+
+import { act, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useState } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { TooltipProvider } from '@/components/ui/tooltip';
+
+import { InputSearch } from './input-search';
+
+// Collapsed state shows a single `<button aria-label="Search docs">` (the
+// expand trigger). Expanded state replaces that button with a non-interactive
+// `<Search>` icon and exposes the controlled `<input>`. The presence of the
+// trigger button is therefore the canonical "is it collapsed" signal — the
+// input itself always lives in the DOM (just behind a `width: 0` motion box).
+const queryTrigger = () => screen.queryByRole('button', { name: 'Search docs' });
+const getInput = () => screen.getByPlaceholderText('Search…') as HTMLInputElement;
+
+// Real-time `sleep` — comfortably past the 150ms debounce.
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+const PAST_DEBOUNCE_MS = 250;
+
+const Wrapper = ({ children }: { children: ReactNode }) => <TooltipProvider>{children}</TooltipProvider>;
+
+beforeEach(() => {
+ if (!window.matchMedia) {
+ Object.defineProperty(window, 'matchMedia', {
+ configurable: true,
+ value: (query: string) => ({
+ addEventListener: vi.fn(),
+ addListener: vi.fn(),
+ dispatchEvent: vi.fn(),
+ matches: false,
+ media: query,
+ onchange: null,
+ removeEventListener: vi.fn(),
+ removeListener: vi.fn(),
+ }),
+ writable: true,
+ });
+ }
+});
+
+interface SearchHostProps {
+ emitted: string[];
+ initialQuery?: string;
+ onSetExternalRef?: (setter: (next: string) => void) => void;
+}
+
+// Mirrors /knowledges: a fresh inline `onSearchChange` per render plus an
+// imperative setter for tests that simulate an external source.
+const SearchHost = ({ emitted, initialQuery = '', onSetExternalRef }: SearchHostProps) => {
+ const [value, setValue] = useState(initialQuery);
+
+ if (onSetExternalRef) {
+ onSetExternalRef(setValue);
+ }
+
+ return (
+ <InputSearch
+ ariaLabel="Search docs"
+ onSearchChange={(next) => {
+ emitted.push(next);
+ setValue(next);
+ }}
+ placeholder="Search…"
+ searchQuery={value}
+ />
+ );
+};
+
+describe('InputSearch — collapsed/expanded presentation', () => {
+ it('mounts collapsed (trigger present) when initial query is empty', () => {
+ render(<SearchHost emitted={[]} />, { wrapper: Wrapper });
+ expect(queryTrigger()).toBeInTheDocument();
+ });
+
+ it('mounts expanded (trigger absent, input populated) when deep-linked', () => {
+ render(<SearchHost emitted={[]} initialQuery="jwt" />, { wrapper: Wrapper });
+ expect(queryTrigger()).not.toBeInTheDocument();
+ expect(getInput().value).toBe('jwt');
+ });
+
+ it('expands on trigger click and focuses the input on the next animation frame', async () => {
+ const user = userEvent.setup();
+ render(<SearchHost emitted={[]} />, { wrapper: Wrapper });
+
+ await user.click(queryTrigger()!);
+
+ await waitFor(() => expect(queryTrigger()).not.toBeInTheDocument());
+ await waitFor(() => expect(document.activeElement).toBe(getInput()));
+ });
+});
+
+describe('InputSearch — typing and outbound emit', () => {
+ it('coalesces a burst of keystrokes into a single emit with the latest value', async () => {
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+
+ render(<SearchHost emitted={emitted} initialQuery="x" />, { wrapper: Wrapper });
+
+ await user.clear(getInput());
+ await sleep(PAST_DEBOUNCE_MS);
+ emitted.length = 0;
+
+ await user.type(getInput(), 'abc');
+ await sleep(PAST_DEBOUNCE_MS);
+
+ expect(emitted).toEqual(['abc']);
+ });
+
+ it('drops a pending typed emit when Esc clears mid-debounce', async () => {
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+
+ render(<SearchHost emitted={emitted} />, { wrapper: Wrapper });
+ await user.click(queryTrigger()!);
+ await user.type(getInput(), 'ab');
+ await user.keyboard('{Escape}');
+ await sleep(PAST_DEBOUNCE_MS);
+
+ expect(emitted.some((value) => value.length > 0)).toBe(false);
+ expect(getInput().value).toBe('');
+ });
+});
+
+describe('InputSearch — Escape semantics', () => {
+ it('first Esc clears a non-empty query but keeps the input expanded', async () => {
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+
+ render(<SearchHost emitted={emitted} initialQuery="jwt" />, { wrapper: Wrapper });
+ const input = getInput();
+ input.focus();
+
+ await user.keyboard('{Escape}');
+ await sleep(50);
+
+ expect(input.value).toBe('');
+ expect(emitted.at(-1)).toBe('');
+ expect(document.activeElement).toBe(input);
+ expect(queryTrigger()).not.toBeInTheDocument();
+ });
+
+ it('second Esc on an already-empty query collapses the input', async () => {
+ const emitted: string[] = [];
+ const user = userEvent.setup();
+
+ render(<SearchHost emitted={emitted} initialQuery="jwt" />, { wrapper: Wrapper });
+ const input = getInput();
+ input.focus();
+
+ await user.keyboard('{Escape}');
+ await sleep(50);
+ await user.keyboard('{Escape}');
+ await sleep(50);
+
+ expect(queryTrigger()).toBeInTheDocument();
+ });
+});
+
+describe('InputSearch — external source-of-truth wins', () => {
+ it('snaps to an external value mid-debounce and drops the in-flight typed emit', async () => {
+ const emitted: string[] = [];
+ let setExternal: ((next: string) => void) | undefined;
+ const user = userEvent.setup();
+
+ render(
+ <SearchHost
+ emitted={emitted}
+ initialQuery=""
+ onSetExternalRef={(setter) => {
+ setExternal = setter;
+ }}
+ />,
+ { wrapper: Wrapper },
+ );
+
+ await user.click(queryTrigger()!);
+ await user.type(getInput(), 'ab');
+
+ // External source mutates the prop while the debounce is still pending.
+ expect(setExternal).toBeDefined();
+ act(() => setExternal!('external'));
+ await sleep(PAST_DEBOUNCE_MS);
+
+ expect(emitted).not.toContain('ab');
+ expect(getInput().value).toBe('external');
+ });
+});
+
+describe('InputSearch — global hotkey expansion', () => {
+ it('Ctrl+F expands the collapsed input', () => {
+ render(<SearchHost emitted={[]} />, { wrapper: Wrapper });
+
+ expect(queryTrigger()).toBeInTheDocument();
+
+ act(() => {
+ document.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, ctrlKey: true, key: 'f' }));
+ });
+
+ expect(queryTrigger()).not.toBeInTheDocument();
+ });
+
+ it('Cmd+F (metaKey) also expands', () => {
+ render(<SearchHost emitted={[]} />, { wrapper: Wrapper });
+
+ act(() => {
+ document.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'f', metaKey: true }));
+ });
+
+ expect(queryTrigger()).not.toBeInTheDocument();
+ });
+});
diff --git a/frontend/src/components/ui/input-search.tsx b/frontend/src/components/ui/input-search.tsx
index a1b2701d..dc64f8a7 100644
--- a/frontend/src/components/ui/input-search.tsx
+++ b/frontend/src/components/ui/input-search.tsx
@@ -1,11 +1,11 @@
import { Search } from 'lucide-react';
import { motion } from 'motion/react';
import { type ChangeEvent, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useDebouncedCallback } from 'use-debounce';
import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '@/components/ui/input-group';
import { Kbd, KbdGroup } from '@/components/ui/kbd';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
-import { useDebouncedCallback } from '@/hooks/use-debounced-callback';
import { cn } from '@/lib/utils';
import { isMac } from '@/lib/utils/platform';
diff --git a/frontend/src/features/flows/files/use-flow-files-search.ts b/frontend/src/features/flows/files/use-flow-files-search.ts
index b92520bf..cece25f0 100644
--- a/frontend/src/features/flows/files/use-flow-files-search.ts
+++ b/frontend/src/features/flows/files/use-flow-files-search.ts
@@ -1,10 +1,9 @@
import { zodResolver } from '@hookform/resolvers/zod';
import { useCallback } from 'react';
import { useForm, type UseFormReturn } from 'react-hook-form';
+import { useDebounce } from 'use-debounce';
import { z } from 'zod';
-import { useDebouncedValue } from '@/hooks/use-debounced-value';
-
import { SEARCH_DEBOUNCE_MS } from './flow-files-constants';
const flowFilesSearchFormSchema = z.object({
@@ -34,7 +33,7 @@ export function useFlowFilesSearch(): UseFlowFilesSearchResult {
});
const rawQuery = form.watch('search');
- const debouncedQuery = useDebouncedValue(rawQuery, SEARCH_DEBOUNCE_MS);
+ const [debouncedQuery] = useDebounce(rawQuery, SEARCH_DEBOUNCE_MS);
const resetSearch = useCallback(() => {
form.reset({ search: '' });
diff --git a/frontend/src/hooks/use-debounced-callback.test.tsx b/frontend/src/hooks/use-debounced-callback.test.tsx
deleted file mode 100644
index f3f1fe47..00000000
--- a/frontend/src/hooks/use-debounced-callback.test.tsx
+++ /dev/null
@@ -1,111 +0,0 @@
-import { act, renderHook } from '@testing-library/react';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { useDebouncedCallback } from './use-debounced-callback';
-
-describe('useDebouncedCallback', () => {
- beforeEach(() => {
- vi.useFakeTimers();
- });
-
- afterEach(() => {
- vi.useRealTimers();
- });
-
- it('defers invocation until delayMs of silence', () => {
- const fn = vi.fn();
- const { result } = renderHook(() => useDebouncedCallback(fn, 100));
-
- act(() => {
- result.current('a');
- result.current('b');
- result.current('c');
- });
-
- expect(fn).not.toHaveBeenCalled();
-
- act(() => {
- vi.advanceTimersByTime(100);
- });
-
- // Only the latest call lands; intermediate ones are dropped.
- expect(fn).toHaveBeenCalledExactlyOnceWith('c');
- });
-
- it('cancel() drops the pending dispatch', () => {
- const fn = vi.fn();
- const { result } = renderHook(() => useDebouncedCallback(fn, 100));
-
- act(() => {
- result.current('x');
- result.current.cancel();
- vi.advanceTimersByTime(500);
- });
-
- expect(fn).not.toHaveBeenCalled();
- });
-
- it('isPending() flips with the timer', () => {
- const fn = vi.fn();
- const { result } = renderHook(() => useDebouncedCallback(fn, 100));
-
- expect(result.current.isPending()).toBe(false);
-
- act(() => {
- result.current('a');
- });
-
- expect(result.current.isPending()).toBe(true);
-
- act(() => {
- vi.advanceTimersByTime(100);
- });
-
- expect(result.current.isPending()).toBe(false);
- });
-
- it('reads the latest `fn` closure at fire time, not at schedule time', () => {
- // Mirrors the production use case: a stale fn would close over an
- // old prop. The debounced callback identity stays stable across
- // renders, but the dispatched fn must be the freshest one.
- const calls: string[] = [];
- const { rerender, result } = renderHook(({ tag }: { tag: string }) => useDebouncedCallback(() => calls.push(tag), 100), {
- initialProps: { tag: 'old' },
- });
-
- const initialDebounced = result.current;
-
- act(() => {
- result.current();
- });
-
- rerender({ tag: 'new' });
-
- // Same callback identity across renders — caller can pass it to
- // memoised children or list it in effect deps without churn.
- expect(result.current).toBe(initialDebounced);
-
- act(() => {
- vi.advanceTimersByTime(100);
- });
-
- expect(calls).toEqual(['new']);
- });
-
- it('cancels pending dispatch on unmount so dead components never fire', () => {
- const fn = vi.fn();
- const { result, unmount } = renderHook(() => useDebouncedCallback(fn, 100));
-
- act(() => {
- result.current('a');
- });
-
- unmount();
-
- act(() => {
- vi.advanceTimersByTime(500);
- });
-
- expect(fn).not.toHaveBeenCalled();
- });
-});
diff --git a/frontend/src/hooks/use-debounced-callback.ts b/frontend/src/hooks/use-debounced-callback.ts
deleted file mode 100644
index dc66cea4..00000000
--- a/frontend/src/hooks/use-debounced-callback.ts
+++ /dev/null
@@ -1,95 +0,0 @@
-import { useEffect, useState } from 'react';
-
-import { useLatestRef } from './use-latest-ref';
-
-/**
- * A function that defers invoking `fn` until `delayMs` have elapsed since the
- * last call. The returned function is stable across renders and exposes
- * imperative escape hatches for callers that need to override the schedule.
- */
-export interface DebouncedCallback<Args extends unknown[]> {
- (...args: Args): void;
- /**
- * Drop any pending call. After this, the next invocation starts a fresh
- * timer. Idempotent — safe to call from `handleClear`, route transitions,
- * external-sync effects, or anywhere else that needs to override the
- * schedule.
- */
- cancel: () => void;
- /**
- * Whether a call is currently scheduled but not yet dispatched. Useful
- * for tests; rarely needed in product code.
- */
- isPending: () => boolean;
-}
-
-/**
- * Same idea as `lodash.debounce` / `use-debounce`, but small and
- * dependency-free: returns a stable callback that defers invoking `fn` until
- * `delayMs` have elapsed since the most recent call. New calls reset the
- * timer; the most recent arguments are the ones eventually dispatched.
- *
- * Why a hook (instead of inlining `setTimeout`):
- * - `cancel()` is a single, synchronous call site — usable from `handleClear`,
- * external-sync effects, or anywhere else that needs to override the
- * pending dispatch. There is no opportunity for a stale timer to fire
- * after the cancel, which was the entire class of races in our previous
- * filter implementation.
- * - The returned function identity is stable across renders, so it can be
- * passed to memoised children and listed in effect deps without churn.
- * - `fn` is captured in a latest-ref, so the dispatched call always sees the
- * most recent closure (props/state at fire time, not at schedule time).
- * This is the standard React idiom for stashing an event-like handler.
- * - Unmount cleanup is automatic — `useEffect` cancels any pending timer
- * so dispatched functions can't land in a torn-down tree.
- *
- * Tradeoff vs `useDeferredValue`: `useDeferredValue` is React's preferred
- * tool for deferring *rendering* work (a memoised list re-renders later
- * while the input stays snappy). It does not defer side-effects. Reach for
- * `useDebouncedCallback` whenever you need to throttle imperative work that
- * leaves React's render tree — URL writes, network requests, persistence —
- * and `useDeferredValue` for the render pipeline itself.
- *
- * Implementation note: the entire API object is built once inside a
- * `useState` lazy initialiser, with the timer handle living in a *closure
- * variable* (`timerId`) rather than a React `useRef`. This keeps the
- * returned `debounced` reference stable forever and side-steps the React
- * Compiler rule that flags reading refs during render — there are no refs
- * to read, only a private variable closed over by the three methods.
- */
-export function useDebouncedCallback<Args extends unknown[]>(
- fn: (...args: Args) => void,
- delayMs: number,
-): DebouncedCallback<Args> {
- const fnReference = useLatestRef(fn);
- const delayReference = useLatestRef(delayMs);
-
- const [debounced] = useState<DebouncedCallback<Args>>(() => {
- let timerId: null | number = null;
-
- const cancel = () => {
- if (timerId !== null) {
- window.clearTimeout(timerId);
- timerId = null;
- }
- };
-
- const isPending = () => timerId !== null;
-
- const invoker = (...args: Args) => {
- cancel();
- timerId = window.setTimeout(() => {
- timerId = null;
- fnReference.current(...args);
- }, delayReference.current);
- };
-
- return Object.assign(invoker, { cancel, isPending });
- });
-
- // Cancel any pending dispatch when the host component unmounts so it
- // can't fire into a torn-down tree.
- useEffect(() => debounced.cancel, [debounced]);
-
- return debounced;
-}
diff --git a/frontend/src/hooks/use-debounced-value.ts b/frontend/src/hooks/use-debounced-value.ts
deleted file mode 100644
index dcd3a924..00000000
--- a/frontend/src/hooks/use-debounced-value.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import { useEffect, useState } from 'react';
-
-/**
- * Returns a debounced version of `value` that updates only after `delayMs` of inactivity.
- *
- * The hook owns its timer entirely: every change to `value` schedules a new update and
- * cancels the previous one. When the component unmounts, the pending timer is cleared,
- * so callers do not need to manage cancellation themselves.
- */
-export function useDebouncedValue<Value>(value: Value, delayMs: number): Value {
- const [debouncedValue, setDebouncedValue] = useState<Value>(value);
-
- useEffect(() => {
- const timeoutId = window.setTimeout(() => {
- setDebouncedValue(value);
- }, delayMs);
-
- return () => {
- window.clearTimeout(timeoutId);
- };
- }, [value, delayMs]);
-
- return debouncedValue;
-}
diff --git a/frontend/src/hooks/use-table-query-filter.ts b/frontend/src/hooks/use-table-query-filter.ts
index 0614365a..ec049ccb 100644
--- a/frontend/src/hooks/use-table-query-filter.ts
+++ b/frontend/src/hooks/use-table-query-filter.ts
@@ -1,7 +1,7 @@
import { useMemo } from 'react';
import { useSearchParams } from 'react-router-dom';
+import { useDebounce } from 'use-debounce';
-import { useDebouncedValue } from '@/hooks/use-debounced-value';
import { URL_PARAMS } from '@/lib/url-params';
interface UseTableQueryFilterReaderOptions {
@@ -34,7 +34,7 @@ export function useTableQueryFilterReader({
}: UseTableQueryFilterReaderOptions = {}): UseTableQueryFilterReaderResult {
const [searchParams] = useSearchParams();
const filter = searchParams.get(paramName) ?? '';
- const debouncedFilter = useDebouncedValue(filter, debounceMs);
+ const [debouncedFilter] = useDebounce(filter, debounceMs);
return useMemo(() => ({ debouncedFilter, filter }), [debouncedFilter, filter]);
}
diff --git a/frontend/src/hooks/use-table-state.ts b/frontend/src/hooks/use-table-state.ts
index bd21afcc..2cfca377 100644
--- a/frontend/src/hooks/use-table-state.ts
+++ b/frontend/src/hooks/use-table-state.ts
@@ -1,7 +1,7 @@
import { useCallback, useEffect, useMemo, useRef } from 'react';
import { useSearchParams } from 'react-router-dom';
+import { useDebounce } from 'use-debounce';
-import { useDebouncedValue } from '@/hooks/use-debounced-value';
import { URL_PARAMS } from '@/lib/url-params';
interface SetPageOptions {
@@ -95,7 +95,7 @@ export function useTableState(options: UseTableStateOptions = {}): UseTableState
const [searchParams, setSearchParams] = useSearchParams();
const filter = searchParams.get(filterParamName) ?? '';
- const debouncedFilter = useDebouncedValue(filter, debounceMs);
+ const [debouncedFilter] = useDebounce(filter, debounceMs);
const pageIndex = useMemo(() => {
const raw = searchParams.get(pageParamName);
diff --git a/frontend/src/providers/knowledges-provider.tsx b/frontend/src/providers/knowledges-provider.tsx
index da50184c..6068e936 100644
--- a/frontend/src/providers/knowledges-provider.tsx
+++ b/frontend/src/providers/knowledges-provider.tsx
@@ -1,6 +1,7 @@
import { createContext, type ReactNode, useCallback, useContext, useMemo } from 'react';
import { useSearchParams } from 'react-router-dom';
import { toast } from 'sonner';
+import { useDebounce } from 'use-debounce';
import type {
CreateKnowledgeDocumentInput,
@@ -18,7 +19,6 @@ import {
useSearchKnowledgeQuery,
useUpdateKnowledgeDocumentMutation,
} from '@/graphql/types';
-import { useDebouncedValue } from '@/hooks/use-debounced-value';
import { useLatestRef } from '@/hooks/use-latest-ref';
import { Log } from '@/lib/log';
import { URL_PARAMS } from '@/lib/url-params';
@@ -71,7 +71,8 @@ export function KnowledgesProvider({ children }: KnowledgesProviderProps) {
// provider sees one canonical "is the user actively searching" flag.
const [searchParams] = useSearchParams();
const rawSemanticQuery = searchParams.get(URL_PARAMS.SEARCH) ?? '';
- const debouncedSemanticQuery = useDebouncedValue(rawSemanticQuery, SEARCH_DEBOUNCE_MS).trim();
+ const [debouncedSemanticQueryRaw] = useDebounce(rawSemanticQuery, SEARCH_DEBOUNCE_MS);
+ const debouncedSemanticQuery = debouncedSemanticQueryRaw.trim();
const inSearchMode = debouncedSemanticQuery.length > 0;
// Override the client's default `nextFetchPolicy: 'cache-first'`: since
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 1b40833c..3571d369 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -117,6 +117,14 @@ export default defineConfig(({ mode }) => {
alias: {
'@': path.resolve(__dirname, './src'),
},
+ // pnpm hoists each package into its own `.pnpm/<name>@<version>/`
+ // folder, which means transitive deps that import `react` resolve
+ // it through their own private path. Without dedupe, two physical
+ // copies of React end up in the bundle and any hook called from
+ // inside the second copy throws "Cannot read properties of null
+ // (reading 'useRef')" — that's what bit us when `use-debounce`
+ // was added.
+ dedupe: ['react', 'react-dom'],
},
server: serverConfig,
};