SEP-1779: Lift the duplicated search debounce into @sep/framework

The Snippet Manager list and the ATW Collect pane's snippet picker each
carried the same debounce: a `useEffect` opening a `setTimeout`, clearing
it on cleanup, against its own locally-declared 300ms constant. Two
copies means a change to the window has to be found and applied twice,
and the second copy is the one that gets missed.

`useDebouncedValue(value, delayMs)` and the shared `SEARCH_DEBOUNCE_MS`
now live in `@sep/framework`, and both consumers call it. The primitive
seeds its state from the incoming value rather than from a blank, so a
list mounted with a term already in state queries for that term instead
of fetching the unfiltered page first; both consumers mount with an empty
box today, so nothing user-visible moves. Callers trim at the call site,
which is where the old effects trimmed too, only inside the timer.

Behaviour is otherwise unchanged: same window, same one-publish-per-pause
coalescing, same clear on unmount.

`SnippetsListPage.test.tsx` moves from a full `vi.mock('@sep/framework')`
to an `importOriginal` partial mock so the page exercises the real
primitive; only the download hook stays stubbed. The ATW suite needed no
change.

Scope note: the ticket also asked for a shared snippets-search query
hook. SEP-1821 (#1349) has since moved ATW's search onto ATW's own
router, dropping the `approval` param and the row projection, and
`useSnippets` has gained a `sort` param, so the two hooks no longer share
an endpoint, a param surface, or a mapper. The only remaining overlap is
`apiClient.get` -> `normalizeAppListResponse` -> `keepPreviousData`,
which `useTasksList` shares equally: a generic app-list wrapper, not a
snippets-search one. Left for a follow-up rather than built here.

Author: nachodd

frontend/packages/apps/atw/src/CollectPane.tsx

@@ -17,7 +17,11 @@
 
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { Alert, Autocomplete, Box, CircularProgress, TextField, Typography } from '@mui/material';
-import { SchemaFormRenderer, SNIPPET_FORM_RESERVED_FIELD_NAMES } from '@sep/framework';
+import {
+  SchemaFormRenderer,
+  SNIPPET_FORM_RESERVED_FIELD_NAMES,
+  useDebouncedValue,
+} from '@sep/framework';
 import type { FormSection, SectionField } from '@sep/api';
 import { CategoryBrowser } from './CategoryBrowser';
 import { useAtwBatchExecute, useAtwMergedSchema, useAtwSnippetSearch } from './hooks';
@@ -28,9 +32,6 @@ export interface CollectPaneProps {
   isClosed?: boolean;
 }
 
-/** Pause after the last keystroke before the snippet search fires (ms). */
-const SNIPPET_SEARCH_DEBOUNCE_MS = 300;
-
 /** Stable empty list so an idle search does not churn the options memo. */
 const NO_SNIPPETS: AtwSnippetSummary[] = [];
 
@@ -194,21 +195,13 @@ export function CollectPane({ incidentId, isClosed = false }: CollectPaneProps)
   const [selected, setSelected] = useState<AtwSnippetSummary[]>([]);
   const [itemErrors, setItemErrors] = useState<string[]>([]);
   const [searchInput, setSearchInput] = useState('');
-  const [debouncedSearch, setDebouncedSearch] = useState('');
+  // Shares the Snippet Manager list's search-debounce window.
+  const debouncedSearch = useDebouncedValue(searchInput.trim());
 
   const handleSnippetsChange = useCallback((snippets: AtwSnippetSummary[]) => {
     setAvailable(snippets);
   }, []);
 
-  // Matches the Snippet Manager list's 300ms window.
-  useEffect(() => {
-    const handle = setTimeout(
-      () => setDebouncedSearch(searchInput.trim()),
-      SNIPPET_SEARCH_DEBOUNCE_MS,
-    );
-    return () => clearTimeout(handle);
-  }, [searchInput]);
-
   useEffect(() => {
     if (!isClosed) {
       return;

frontend/packages/apps/snippets/src/SnippetsListPage.test.tsx

@@ -36,7 +36,11 @@ vi.mock('react-router', () => ({
 // The download button owns a mutation now (the SPA fetches the file through the
 // Bearer-authenticated JSON endpoint), so the download-before-approve guard
 // flips on the mutation's success callback rather than on a plain anchor click.
-vi.mock('@sep/framework', () => ({
+// Partial mock: only the download hook is stubbed. `useDebouncedValue` is a
+// pure timer primitive with no transport of its own, so the page exercises the
+// real one — the same 300ms window it debounced inline before.
+vi.mock('@sep/framework', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@sep/framework')>()),
   useSnippetDownload: vi.fn(() => ({
     mutate: (_params: unknown, callbacks?: { onSuccess?: () => void }) => callbacks?.onSuccess?.(),
     isPending: false,

frontend/packages/apps/snippets/src/SnippetsListPage.tsx

@@ -49,7 +49,7 @@ import DownloadIcon from '@mui/icons-material/Download';
 import RemoveCircleOutlineIcon from '@mui/icons-material/RemoveCircleOutline';
 import SearchIcon from '@mui/icons-material/Search';
 import { ApiError, DEFAULT_APP_LIST_LIMIT, DEFAULT_APP_LIST_OFFSET } from '@sep/api';
-import { useSnippetDownload } from '@sep/framework';
+import { useDebouncedValue, useSnippetDownload } from '@sep/framework';
 import {
   useSnippets,
   useApproveSnippet,
@@ -99,9 +99,6 @@ function decodeServiceType(value: string): string {
   return value.slice(SERVICE_TYPE_PREFIX.length);
 }
 
-/** Debounce window (ms) before a search keystroke drives a server refetch. */
-const SEARCH_DEBOUNCE_MS = 300;
-
 /** Label shown for snippets that declare no `service_type`. */
 const UNCATEGORIZED_LABEL = 'Uncategorized';
 
@@ -241,11 +238,7 @@ export function SnippetsListPage({ isAdmin = false }: SnippetsListPageProps) {
   const [serviceTypeFilter, setServiceTypeFilter] = useState<string>(ALL_SERVICES);
 
   // Debounce the search box so typing drives one refetch per pause, not per key.
-  const [debouncedSearch, setDebouncedSearch] = useState('');
-  useEffect(() => {
-    const handle = setTimeout(() => setDebouncedSearch(search.trim()), SEARCH_DEBOUNCE_MS);
-    return () => clearTimeout(handle);
-  }, [search]);
+  const debouncedSearch = useDebouncedValue(search.trim());
 
   // Map the service-type UI selection onto the server equality param: no filter,
   // "uncategorized" (carried by a separate flag below), or the decoded free-form

frontend/packages/framework/src/hooks/index.ts

@@ -86,4 +86,6 @@ export type { UseSnippetAppExecutionOptions } from './useSnippetAppExecution';
 export { useTaskStats } from './useTaskStats';
 export type { TaskStatsView } from './useTaskStats';
 
+export { useDebouncedValue, SEARCH_DEBOUNCE_MS } from './useDebouncedValue';
+
 export { sepRetry } from './sepRetry';

frontend/packages/framework/src/hooks/useDebouncedValue.test.tsx

@@ -0,0 +1,121 @@
+/**
+ * Copyright (C) 2026 Percona LLC
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { SEARCH_DEBOUNCE_MS, useDebouncedValue } from './useDebouncedValue';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/** Advance timers inside `act` so the resulting state update is flushed. */
+function advance(ms: number) {
+  act(() => {
+    vi.advanceTimersByTime(ms);
+  });
+}
+
+describe('useDebouncedValue', () => {
+  it('publishes the initial value immediately', () => {
+    const { result } = renderHook(() => useDebouncedValue('seed'));
+
+    expect(result.current).toBe('seed');
+  });
+
+  it('withholds a new value until the delay elapses', () => {
+    const { result, rerender } = renderHook(({ value }) => useDebouncedValue(value), {
+      initialProps: { value: '' },
+    });
+
+    rerender({ value: 'pg' });
+    expect(result.current).toBe('');
+
+    advance(SEARCH_DEBOUNCE_MS - 1);
+    expect(result.current).toBe('');
+
+    advance(1);
+    expect(result.current).toBe('pg');
+  });
+
+  it('publishes once per pause, not once per change', () => {
+    const { result, rerender } = renderHook(({ value }) => useDebouncedValue(value), {
+      initialProps: { value: '' },
+    });
+
+    for (const value of ['p', 'pg', 'pgs', 'pgst']) {
+      rerender({ value });
+      advance(SEARCH_DEBOUNCE_MS - 50);
+    }
+    // Every keystroke landed inside the window, so nothing has been published.
+    expect(result.current).toBe('');
+
+    advance(50);
+    expect(result.current).toBe('pgst');
+  });
+
+  it('honours a caller-supplied delay', () => {
+    const { result, rerender } = renderHook(({ value }) => useDebouncedValue(value, 1000), {
+      initialProps: { value: '' },
+    });
+
+    rerender({ value: 'slow' });
+    advance(SEARCH_DEBOUNCE_MS);
+    expect(result.current).toBe('');
+
+    advance(1000 - SEARCH_DEBOUNCE_MS);
+    expect(result.current).toBe('slow');
+  });
+
+  it('restarts the window when the delay itself changes', () => {
+    const { result, rerender } = renderHook(({ value, delay }) => useDebouncedValue(value, delay), {
+      initialProps: { value: 'a', delay: SEARCH_DEBOUNCE_MS },
+    });
+
+    rerender({ value: 'b', delay: SEARCH_DEBOUNCE_MS });
+    advance(SEARCH_DEBOUNCE_MS - 100);
+
+    rerender({ value: 'b', delay: 1000 });
+    advance(100);
+    expect(result.current).toBe('a');
+
+    advance(900);
+    expect(result.current).toBe('b');
+  });
+
+  it('clears the pending timer on unmount', () => {
+    const clearTimeoutSpy = vi.spyOn(globalThis, 'clearTimeout');
+    const { rerender, unmount } = renderHook(({ value }) => useDebouncedValue(value), {
+      initialProps: { value: '' },
+    });
+
+    rerender({ value: 'gone' });
+    clearTimeoutSpy.mockClear();
+    unmount();
+
+    expect(clearTimeoutSpy).toHaveBeenCalledTimes(1);
+
+    // The timer never fires, so no state update is attempted after unmount.
+    expect(() => advance(SEARCH_DEBOUNCE_MS)).not.toThrow();
+    clearTimeoutSpy.mockRestore();
+  });
+});

frontend/packages/framework/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (C) 2026 Percona LLC
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { useEffect, useState } from 'react';
+
+/**
+ * Default settle window for a typed input before it drives work downstream (ms).
+ *
+ * Named for its origin — the search boxes across the apps, where the work is a
+ * server refetch — and shared so they all settle on one window rather than each
+ * redeclaring it. It is the hook's default rather than its only value: a
+ * consumer wanting a different pause states that delay at the call site.
+ */
+export const SEARCH_DEBOUNCE_MS = 300;
+
+/**
+ * Track `value`, but only publish it once it has held still for `delayMs`.
+ *
+ * The debounced value starts at the initial `value` rather than at a blank —
+ * a list mounted with a search term already in its state queries for that term
+ * immediately instead of fetching the unfiltered page first.
+ *
+ * The pending timer is cleared on every change and on unmount, so a fast typist
+ * causes one publish per pause, and an unmounted component never publishes.
+ */
+export function useDebouncedValue<T>(value: T, delayMs: number = SEARCH_DEBOUNCE_MS): T {
+  const [debounced, setDebounced] = useState<T>(value);
+
+  useEffect(() => {
+    const handle = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(handle);
+  }, [value, delayMs]);
+
+  return debounced;
+}

frontend/packages/framework/src/index.ts

@@ -152,6 +152,8 @@ export {
   useTaskHistoryFiles,
   useTaskFileDownload,
   useSnippetDownload,
+  useDebouncedValue,
+  SEARCH_DEBOUNCE_MS,
 } from './hooks';
 export type {
   TaskLogsState,