Fully autonomous AI Agents system capable of performing complex penetration testing tasks
Go ai-agentsai-security-toolanthropicautonomous-agentsgolanggptgraphqlmulti-agent-systemoffensive-securityopen-sourceopenaipenetration-testingpenetration-testing-toolsreactsecurity-automationsecurity-testingsecurity-toolsself-hosted
feat(frontend): in-sheet search + focus-steal fix in detail navigation
Sergey Kozyrenko5a26d800ee1e
diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsxindex 40bcfc70..d60451f4 100644--- a/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsx+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsx@@ -47,6 +47,7 @@ export function DetailNavigationButtons<T extends { id: string }>({disabled={!controller.prevId}onClick={controller.goToPrev}size="icon"+ type="button"variant="outline"><ChevronLeft />@@ -64,6 +65,7 @@ export function DetailNavigationButtons<T extends { id: string }>({)}disabled={!controller.hasEntries}onClick={controller.openSheet}+ type="button"variant="outline">{controller.positionLabel}@@ -79,6 +81,7 @@ export function DetailNavigationButtons<T extends { id: string }>({disabled={!controller.nextId}onClick={controller.goToNext}size="icon"+ type="button"variant="outline"><ChevronRight />diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.test.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.test.tsxindex 9965a92a..b0eddc50 100644--- a/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.test.tsx+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.test.tsx@@ -39,8 +39,11 @@ const LocationReadout = () => {interface HarnessProps {currentId?: null | string;+ defaultSearchQuery?: string;filter?: string;+ hasSearch?: boolean;items?: readonly Item[];+ searchPlaceholder?: string;}/**@@ -48,19 +51,31 @@ interface HarnessProps {* focus / a11y interactions can be exercised without round-tripping through* the toolbar's position button. Keeps each test focused on the leaf.*/-const SheetHarness = ({ currentId = 'c', items = ITEMS }: HarnessProps) => {+const SheetHarness = ({+ currentId = 'c',+ defaultSearchQuery,+ hasSearch,+ items = ITEMS,+ searchPlaceholder,+}: HarnessProps) => {const nav = useDetailNavigation<Item>({currentId,defaultOpen: true,+ defaultSearchQuery,getHref,getLabel,getSearchableText,items,+ // Skip the debounce so each test sees the post-typing subset on the+ // next paint instead of having to wait `>150ms` per keystroke.+ searchDebounceMs: 0,});return (<DetailNavigationSheet<Item>controller={nav}+ hasSearch={hasSearch}+ searchPlaceholder={searchPlaceholder}sheetTitle="Items"/>);@@ -239,3 +254,174 @@ describe('DetailNavigationSheet — selection', () => {});});});++describe('DetailNavigationSheet — search input', () => {+ it('renders the search input by default (hasSearch=true)', async () => {+ renderSheet({ currentId: 'c' });++ const input = await screen.findByRole('textbox');+ expect(input).toBeInTheDocument();+ expect(input).toHaveValue('');+ });++ it('hides the search input when hasSearch is false (opt-out)', async () => {+ renderSheet({ currentId: 'c', hasSearch: false });++ await screen.findByRole('listbox');+ expect(screen.queryByRole('textbox')).not.toBeInTheDocument();+ });++ it('uses the supplied placeholder', async () => {+ renderSheet({ currentId: 'c', searchPlaceholder: 'Find item' });++ const input = await screen.findByPlaceholderText('Find item');+ expect(input).toBeInTheDocument();+ });++ it('typing narrows the listbox immediately when searchDebounceMs=0', async () => {+ const user = userEvent.setup();+ renderSheet({ currentId: 'a' });++ const input = await screen.findByRole('textbox');+ await user.type(input, 'cha');++ const listbox = await screen.findByRole('listbox');++ await waitFor(() => {+ const labels = within(listbox)+ .getAllByRole('option')+ .map((option) => option.textContent ?? '');+ expect(labels).toEqual(['Charlie']);+ });+ });++ it('renders a clear button while the query is non-empty; clicking it resets', async () => {+ const user = userEvent.setup();+ renderSheet({ currentId: 'a', defaultSearchQuery: 'cha' });++ const clearButton = await screen.findByRole('button', { name: 'Clear search' });+ await user.click(clearButton);++ const input = await screen.findByRole('textbox');+ expect(input).toHaveValue('');++ const listbox = await screen.findByRole('listbox');++ await waitFor(() => {+ const labels = within(listbox)+ .getAllByRole('option')+ .map((option) => option.textContent ?? '');+ expect(labels).toEqual(['Alpha', 'Bravo', 'Charlie', 'Delta']);+ });+ });++ it('Escape clears a non-empty query without closing the sheet', async () => {+ const user = userEvent.setup();+ renderSheet({ currentId: 'a', defaultSearchQuery: 'cha' });++ const input = await screen.findByRole('textbox');+ input.focus();+ await user.keyboard('{Escape}');++ expect(input).toHaveValue('');+ // Sheet stayed mounted because the keydown was prevented + stopped.+ expect(screen.queryByRole('listbox', { name: 'Items' })).toBeInTheDocument();+ });++ it('shows a query-specific empty state when nothing matches', async () => {+ renderSheet({ currentId: 'a', defaultSearchQuery: 'zzzzz' });++ await waitFor(() => {+ expect(screen.getByText(/No items match "zzzzz"\./)).toBeInTheDocument();+ });+ expect(screen.queryByRole('listbox', { name: 'Items' })).not.toBeInTheDocument();+ });++ it('ANDs the in-sheet search with the URL ?q= filter', async () => {+ // URL filter narrows to Alpha + Bravo + Charlie (substring "a"); the+ // local "bra" then narrows further to just Bravo. Use a single+ // `fireEvent.change` instead of `user.type` so the assertion does+ // not race with React's per-keystroke re-renders.+ renderSheet({ currentId: 'b', filter: 'a' });++ const input = await screen.findByRole('textbox');+ fireEvent.change(input, { target: { value: 'bra' } });++ const listbox = await screen.findByRole('listbox', { name: 'Items' });++ await waitFor(() => {+ const labels = within(listbox)+ .getAllByRole('option')+ .map((option) => option.textContent ?? '');+ expect(labels).toEqual(['Bravo']);+ });+ });++ it('ArrowDown from the input moves roving focus into the listbox', async () => {+ // Start at currentId 'b' so the initial roving focus is 'b'; that way+ // we can prove ArrowDown from the *input* targeted the first item ('a')+ // rather than just no-op'ing on already-focused 'a'.+ renderSheet({ currentId: 'b' });++ const input = await screen.findByRole('textbox');+ fireEvent.keyDown(input, { key: 'ArrowDown' });++ const listbox = await screen.findByRole('listbox');++ await waitFor(() => {+ const focused = within(listbox)+ .getAllByRole('option')+ .find((option) => option.getAttribute('tabindex') === '0');+ expect(focused).toHaveAttribute('data-item-id', 'a');+ });+ // ArrowDown jumps DOM focus to the new option synchronously — the+ // auto-focus effect skips when focus is on the search input, so this+ // handler has to move focus itself. Without it, the user would have+ // to click the option to interact with it after typing.+ expect(document.activeElement).toHaveAttribute('data-item-id', 'a');+ });++ it('does not yank focus onto a listbox option when filteredItems shrinks (regression)', async () => {+ // Reproduces the bug from the original implementation: typing a+ // query that drops the current item from the subset triggered the+ // auto-focus effect to grab focus onto the new `focusedId` (the+ // first survivor) at the debounce boundary, interrupting typing.+ //+ // `currentId='d'` + query `'rav'` → Delta is gone, subset becomes+ // [Bravo], render-phase reconciliation sets `focusedId='b'`. With+ // the fix the effect observes the search input is focused and+ // refuses to steal focus onto the option.+ //+ // (The exact post-shrink `activeElement` is sensitive to Radix's+ // JSDOM-only focus-trap fallback behaviour — in a real browser+ // focus stays on the input, but JSDOM may bounce it onto the+ // dialog container if the previously-focused option unmounts. The+ // bug is specifically about the listbox option stealing focus, so+ // we assert against *that*, not against equality with the input.)+ renderSheet({ currentId: 'd' });++ const input = await screen.findByRole('textbox');++ // Radix Dialog runs its own open-time focus trap. Wait for it to+ // settle, then put focus on the input as the user would after+ // clicking it.+ await waitFor(() => {+ input.focus();+ expect(document.activeElement).toBe(input);+ });++ fireEvent.change(input, { target: { value: 'rav' } });++ await waitFor(() => {+ const labels = within(screen.getByRole('listbox'))+ .getAllByRole('option')+ .map((option) => option.textContent ?? '');+ expect(labels).toEqual(['Bravo']);+ });++ // The exact failure mode of the original bug: focus jumps onto a+ // `role="option"` button when the list shrinks. With the fix it+ // never lands there until the user explicitly arrows into the list.+ expect(document.activeElement?.getAttribute('role')).not.toBe('option');+ });+});diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsxindex fb6de70d..7e7c6236 100644--- a/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx@@ -1,6 +1,8 @@+import { Search, X } from 'lucide-react';import { type KeyboardEvent, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';import { Badge } from '@/components/ui/badge';+import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '@/components/ui/input-group';import { ScrollArea } from '@/components/ui/scroll-area';import { Sheet, SheetContent, SheetHeader, SheetTitle } from '@/components/ui/sheet';import { cn } from '@/lib/utils';@@ -9,7 +11,15 @@ import type { DetailNavigationController } from './use-detail-navigation';interface DetailNavigationSheetProps<T extends { id: string }> {controller: DetailNavigationController<T>;+ /**+ * Render a free-text search input in the sheet header that drives+ * `controller.setSearchQuery`. Defaults to `true` — pass `false` to opt+ * out for the rare consumer that wants the sheet to stay URL-filter-only.+ */+ hasSearch?: boolean;renderItem?: (item: T, isCurrent: boolean) => ReactNode;+ /** Placeholder for the in-sheet search input. Defaults to "Search…". */+ searchPlaceholder?: string;sheetIcon?: ReactNode;sheetTitle: string;}@@ -27,7 +37,9 @@ interface DetailNavigationSheetProps<T extends { id: string }> {*/export function DetailNavigationSheet<T extends { id: string }>({controller,+ hasSearch = true,renderItem,+ searchPlaceholder = 'Search…',sheetIcon,sheetTitle,}: DetailNavigationSheetProps<T>) {@@ -35,6 +47,7 @@ export function DetailNavigationSheet<T extends { id: string }>({// read individual fields rather than the controller object — keeps the// identity story the same as before the refactor.const {+ clearSearchQuery,currentId,currentIndex,filteredItems: items,@@ -42,15 +55,20 @@ export function DetailNavigationSheet<T extends { id: string }>({getLabel,handleItemSelect: onItemSelect,isSheetOpen: open,+ searchQuery,+ setSearchQuery,setSheetOpen: onOpenChange,total,} = controller;const listRef = useRef<HTMLUListElement>(null);+ const searchInputRef = useRef<HTMLInputElement>(null);const buttonRefs = useRef(new Map<string, HTMLButtonElement>());const [focusedId, setFocusedId] = useState<null | string>(null);const hasEntries = items.length > 0;+ const trimmedQuery = searchQuery.trim();+ const hasClearButton = hasSearch && trimmedQuery.length > 0;// Build an `id → index` map once per `items`/`getId` change so both the// per-render membership check below and the keyboard handler's lookup@@ -126,11 +144,35 @@ export function DetailNavigationSheet<T extends { id: string }>({// After roving focus moves, push the focus into the DOM. `rAF` defers past// Radix's own focus management so we don't fight its open-time focus trap.+ //+ // Gate: only auto-focus an option when the user's focus is already+ // somewhere that *expects* roving (a list option) or has not yet landed+ // (`document.activeElement === document.body` right after open, before+ // Radix moves focus into the dialog). Crucially, we must NOT steal focus+ // when the user is typing in the search input: every keystroke that+ // flushes the debounce can re-target `focusedId` (when `currentId` falls+ // out of the filtered subset, render-phase reconciliation snaps focus to+ // the first survivor). Without this gate, focus jumps out of the input+ // mid-type and the user can only enter a few characters before losing+ // their place — exact repro: type "aes" with current flow 837 visible,+ // focus moves to button 836 at the 150 ms debounce boundary.+ //+ // The fix is at the cause, not the symptom: a local input mirror (the+ // `InputSearch` / `DataTableFilter` pattern) would keep keystrokes from+ // being dropped during a state round-trip, but it would not stop this+ // effect from yanking focus away. The two patterns solve different bugs.useEffect(() => {if (!open || focusedId === null) {return;}+ const activeEl = document.activeElement;+ const focusIsOnSearchInput = activeEl !== null && activeEl === searchInputRef.current;++ if (focusIsOnSearchInput) {+ return;+ }+const id = requestAnimationFrame(() => {const node = buttonRefs.current.get(focusedId);@@ -206,6 +248,61 @@ export function DetailNavigationSheet<T extends { id: string }>({[onItemSelect],);+ // ArrowDown from the input jumps focus into the listbox so keyboard+ // users can flow `type → arrow down → enter` without hunting for the+ // list. We move focus *here* synchronously (not in the auto-focus+ // effect) because that effect now skips when focus is on the search+ // input — otherwise it would yank focus mid-type. Escape is *not*+ // handled here — Radix listens for it on a native document handler+ // that React-level `stopPropagation` cannot reach. See+ // `handleEscapeKeyDown` below, wired through `onEscapeKeyDown`.+ const handleSearchKeyDown = useCallback(+ (event: React.KeyboardEvent<HTMLInputElement>) => {+ if (event.key === 'ArrowDown' && hasEntries) {+ event.preventDefault();+ const first = items[0];++ if (!first) {+ return;+ }++ const firstId = String(getId(first));+ setFocusedId(firstId);+ // Button refs for the current items are already mounted —+ // this handler fires during a real user keystroke, so the+ // listbox commit that wired them up has already happened.+ buttonRefs.current.get(firstId)?.focus();+ }+ },+ [getId, hasEntries, items],+ );++ // Intercept Esc at the Radix-Content level so we can clear a non-empty+ // search before the dialog's built-in "close on Esc" fires. Once the+ // query is empty, we let Radix close as usual — matches the two-step+ // Esc affordance of `InputSearch` (clear, then dismiss).+ const handleEscapeKeyDown = useCallback(+ (event: KeyboardEvent) => {+ if (hasSearch && trimmedQuery.length > 0) {+ event.preventDefault();+ clearSearchQuery();+ }+ },+ [clearSearchQuery, hasSearch, trimmedQuery.length],+ );++ const handleSearchChange = useCallback(+ (event: React.ChangeEvent<HTMLInputElement>) => {+ setSearchQuery(event.target.value);+ },+ [setSearchQuery],+ );++ const handleSearchClear = useCallback(() => {+ clearSearchQuery();+ searchInputRef.current?.focus();+ }, [clearSearchQuery]);+// One stable callback ref reused for every button. The previous shape —// `setButtonRef(id) => (node) => …` — manufactured a new closure per id// on every render, which made React re-attach refs (a `delete` + `set`@@ -241,9 +338,10 @@ export function DetailNavigationSheet<T extends { id: string }>({// listbox of items, the `SheetTitle` already describes it.aria-describedby={undefined}className="flex w-full max-w-sm flex-col gap-0 p-0 sm:max-w-sm"+ onEscapeKeyDown={handleEscapeKeyDown}side="right">- <SheetHeader className="border-b p-4">+ <SheetHeader className="gap-3 border-b p-4"><SheetTitle className="flex items-center gap-2 pr-8 text-base">{sheetIcon}<span>{sheetTitle}</span>@@ -254,6 +352,39 @@ export function DetailNavigationSheet<T extends { id: string }>({{total}</Badge></SheetTitle>+ {hasSearch ? (+ <InputGroup className="h-9">+ <InputGroupAddon align="inline-start">+ <Search+ aria-hidden="true"+ className="text-muted-foreground"+ />+ </InputGroupAddon>+ <InputGroupInput+ aria-label={searchPlaceholder}+ className="h-9 py-0"+ onChange={handleSearchChange}+ onKeyDown={handleSearchKeyDown}+ placeholder={searchPlaceholder}+ ref={searchInputRef}+ type="text"+ value={searchQuery}+ />+ {hasClearButton ? (+ <InputGroupAddon align="inline-end">+ <InputGroupButton+ aria-label="Clear search"+ onClick={handleSearchClear}+ size="icon-sm"+ type="button"+ variant="ghost"+ >+ <X aria-hidden="true" />+ </InputGroupButton>+ </InputGroupAddon>+ ) : null}+ </InputGroup>+ ) : null}</SheetHeader>{hasEntries ? (<ScrollArea className="flex-1">@@ -301,7 +432,9 @@ export function DetailNavigationSheet<T extends { id: string }>({</ScrollArea>) : (<div className="text-muted-foreground flex flex-1 items-center justify-center px-4 text-center text-sm">- No items match the current filter.+ {trimmedQuery.length > 0+ ? `No items match "${trimmedQuery}".`+ : 'No items match the current filter.'}</div>)}</SheetContent>diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsxindex 8514e39d..1935bd4e 100644--- a/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx@@ -7,7 +7,14 @@ import { DetailNavigationSheet } from './detail-navigation-sheet';export interface DetailNavigationToolbarProps<T extends { id: string }> {controller: DetailNavigationController<T>;+ /**+ * Forwarded to `<DetailNavigationSheet>` — controls the in-sheet search+ * input. Defaults to `true`; pass `false` to opt out.+ */+ hasSearch?: boolean;renderItem?: (item: T, isCurrent: boolean) => ReactNode;+ /** Forwarded placeholder for the in-sheet search input. */+ searchPlaceholder?: string;sheetIcon?: ReactNode;sheetTitle: string;}@@ -24,7 +31,9 @@ export interface DetailNavigationToolbarProps<T extends { id: string }> {*/export function DetailNavigationToolbar<T extends { id: string }>({controller,+ hasSearch,renderItem,+ searchPlaceholder,sheetIcon,sheetTitle,}: DetailNavigationToolbarProps<T>) {@@ -40,7 +49,9 @@ export function DetailNavigationToolbar<T extends { id: string }>({/><DetailNavigationSheetcontroller={controller}+ hasSearch={hasSearch}renderItem={renderItem}+ searchPlaceholder={searchPlaceholder}sheetIcon={sheetIcon}sheetTitle={sheetTitle}/>diff --git a/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx b/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsxindex 81d0657c..a9797427 100644--- a/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx+++ b/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx@@ -443,6 +443,227 @@ describe('useDetailNavigation — current item bookkeeping', () => {});});+describe('useDetailNavigation — local search (uncontrolled)', () => {+ it('starts with an empty searchQuery and `isSearchActive=false` by default', () => {+ const { result } = renderHook(+ () =>+ useDetailNavigation<Item>({+ currentId: 'b',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ }),+ { wrapper: renderInRoute(['/items/b']) },+ );++ expect(result.current.searchQuery).toBe('');+ expect(result.current.debouncedSearchQuery).toBe('');+ expect(result.current.isSearchActive).toBe(false);+ // Without a query, the full subset is visible.+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['a', 'b', 'c']);+ });++ it('honours defaultSearchQuery on first render and surfaces it as active', async () => {+ const { result } = renderHook(+ () =>+ useDetailNavigation<Item>({+ currentId: 'b',+ defaultSearchQuery: 'bravo',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ searchDebounceMs: 0,+ }),+ { wrapper: renderInRoute(['/items/b']) },+ );++ expect(result.current.searchQuery).toBe('bravo');++ await waitFor(() => {+ expect(result.current.debouncedSearchQuery).toBe('bravo');+ });+ expect(result.current.isSearchActive).toBe(true);+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['b']);+ });++ it('setSearchQuery + debounce narrows filteredItems', async () => {+ const { result } = renderHook(+ () =>+ useDetailNavigation<Item>({+ currentId: 'a',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ searchDebounceMs: 0,+ }),+ { wrapper: renderInRoute(['/items/a']) },+ );++ act(() => {+ result.current.setSearchQuery('cha');+ });++ // searchQuery (raw) flips instantly for the input value.+ expect(result.current.searchQuery).toBe('cha');++ await waitFor(() => {+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['c']);+ });+ // Current id 'a' is no longer in the subset → -1 / null neighbours.+ expect(result.current.currentIndex).toBe(-1);+ expect(result.current.prevId).toBeNull();+ expect(result.current.nextId).toBeNull();+ });++ it('clearSearchQuery resets the value and restores the full subset', async () => {+ const { result } = renderHook(+ () =>+ useDetailNavigation<Item>({+ currentId: 'a',+ defaultSearchQuery: 'pha',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ searchDebounceMs: 0,+ }),+ { wrapper: renderInRoute(['/items/a']) },+ );++ await waitFor(() => {+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['a']);+ });++ act(() => {+ result.current.clearSearchQuery();+ });++ expect(result.current.searchQuery).toBe('');++ await waitFor(() => {+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['a', 'b', 'c']);+ });+ });++ it('combines URL filter and local search with AND semantics', async () => {+ // URL ?q=a narrows to Alpha + Bravo + Charlie. Local "bra" then keeps+ // only Bravo. Without AND we'd see Alpha (matches `a`) or Bravo+Charlie+ // (matches local in isolation).+ const { result } = renderHook(+ () =>+ useDetailNavigation<Item>({+ currentId: 'b',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ searchDebounceMs: 0,+ }),+ { wrapper: renderInRoute(['/items/b?q=a']) },+ );++ await waitFor(() => {+ expect(result.current.debouncedFilter).toBe('a');+ });++ act(() => {+ result.current.setSearchQuery('bra');+ });++ await waitFor(() => {+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['b']);+ });+ });+});++describe('useDetailNavigation — local search (controlled)', () => {+ it('respects the controlled searchQuery and fires onSearchQueryChange', () => {+ const onSearchQueryChange = vi.fn();++ const { rerender, result } = renderHook(+ ({ searchQuery }: { searchQuery: string }) =>+ useDetailNavigation<Item>({+ currentId: 'b',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ onSearchQueryChange,+ searchDebounceMs: 0,+ searchQuery,+ }),+ {+ initialProps: { searchQuery: 'bravo' },+ wrapper: renderInRoute(['/items/b']),+ },+ );++ expect(result.current.searchQuery).toBe('bravo');++ act(() => {+ result.current.setSearchQuery('charlie');+ });++ // Parent owns the value — controller does not flip without a prop change.+ expect(result.current.searchQuery).toBe('bravo');+ // But the consumer is told to update.+ expect(onSearchQueryChange).toHaveBeenLastCalledWith('charlie');++ rerender({ searchQuery: 'charlie' });+ expect(result.current.searchQuery).toBe('charlie');+ });++ it('fires onSearchQueryChange in uncontrolled mode too', () => {+ const onSearchQueryChange = vi.fn();++ const { result } = renderHook(+ () =>+ useDetailNavigation<Item>({+ currentId: 'b',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ onSearchQueryChange,+ }),+ { wrapper: renderInRoute(['/items/b']) },+ );++ act(() => {+ result.current.setSearchQuery('alpha');+ });++ expect(onSearchQueryChange).toHaveBeenLastCalledWith('alpha');+ expect(result.current.searchQuery).toBe('alpha');+ });+});++describe('useDetailNavigation — local search identity stability', () => {+ it('keeps setSearchQuery / clearSearchQuery identity-stable across re-renders', () => {+ const { rerender, result } = renderHook(+ () =>+ useDetailNavigation<Item>({+ currentId: 'b',+ getHref,+ getLabel,+ getSearchableText,+ items: ITEMS,+ }),+ { wrapper: renderInRoute(['/items/b']) },+ );++ const firstSet = result.current.setSearchQuery;+ const firstClear = result.current.clearSearchQuery;+ rerender();++ expect(result.current.setSearchQuery).toBe(firstSet);+ expect(result.current.clearSearchQuery).toBe(firstClear);+ });+});+describe('useDetailNavigation — navigation back to list does not leak the filter', () => {it('keeps the URL `?q=` intact after a navigate inside the same router', async () => {const Harness = () => {diff --git a/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts b/frontend/src/components/shared/detail-navigation/use-detail-navigation.tsindex c6536bde..64898e85 100644--- a/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts+++ b/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts@@ -1,20 +1,32 @@import { useCallback, useMemo, useState } from 'react';import { useNavigate, useSearchParams } from 'react-router-dom';+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';import { useNavigation } from './use-navigation';+/**+ * Default debounce for the in-sheet local search. Shorter than the URL filter's+ * 200 ms (`useTableQueryFilterReader`) — local search doesn't round-trip+ * through `history` / re-render the route subtree, so we can afford to react+ * faster while still coalescing burst typing.+ */+const DEFAULT_SEARCH_DEBOUNCE_MS = 150;+/*** Headless controller for a detail page that walks a filtered list.** Owns:- * - the filtered/sorted subset (pure `computeNavigation`),+ * - the filtered/sorted subset (pure `computeNavigation`), narrowed by+ * the URL filter AND an optional in-controller local search,* - the resolved Prev / Next sibling ids and the pre-formatted position* label (so leaf components don't recompute),* - the sheet open state (controllable via `open` / `onOpenChange`),+ * - the local search query state (controllable via `searchQuery` /+ * `onSearchQueryChange`), with its own debounce independent of the URL,* - navigation actions that thread the current `?<filter>=` into every* prev / next / item-select destination.*@@ -24,6 +36,8 @@ import { useNavigation } from './use-navigation';* controller can rely on referential equality for downstream memos.*/export interface DetailNavigationController<T extends { id: string }> {+ /** Reset the local search to an empty string. Convenience for "X" buttons. */+ clearSearchQuery: () => void;closeSheet: () => void;/** Active `currentId` coerced to a string, or `null` when absent. */currentId: null | string;@@ -33,6 +47,11 @@ export interface DetailNavigationController<T extends { id: string }> {currentItem: null | T;/** Debounced URL filter the controller is filtering against. */debouncedFilter: string;+ /**+ * Debounced version of {@link searchQuery} — this is what actually narrows+ * `filteredItems`. Combined with `debouncedFilter` via AND.+ */+ debouncedSearchQuery: string;/** Sorted+filtered subset that drives prev / next / sheet listing. */filteredItems: readonly T[];/** Stable id accessor (defaults to `item.id` when not supplied). */@@ -53,6 +72,8 @@ export interface DetailNavigationController<T extends { id: string }> {handleItemSelect: (item: T) => void;/** `true` iff `filteredItems.length > 0`. */hasEntries: boolean;+ /** `true` iff `debouncedSearchQuery` is non-empty (UI hints / clear button). */+ isSearchActive: boolean;isSheetOpen: boolean;/**@@ -69,6 +90,13 @@ export interface DetailNavigationController<T extends { id: string }> {positionLabel: string;/** ID of the previous filtered sibling, or `null` at the start / off-subset. */prevId: null | string;+ /**+ * Current local search value (raw, **not** debounced) — bind directly to+ * an `<input value={...}>` for instant caret feedback. The debounced+ * mirror is what filters the list, see {@link debouncedSearchQuery}.+ */+ searchQuery: string;+ setSearchQuery: (value: string) => void;setSheetOpen: (open: boolean) => void;/** Same as `filteredItems.length`, named explicitly for clarity. */@@ -79,6 +107,8 @@ interface UseDetailNavigationOptions<T extends { id: string }> {currentId: null | string | undefined;/** Initial value for the uncontrolled case. Defaults to `false`. */defaultOpen?: boolean;+ /** Initial local search value for the uncontrolled case. Defaults to `''`. */+ defaultSearchQuery?: string;getHref: (item: T) => string;getId?: (item: T) => string;getLabel: (item: T) => string;@@ -86,6 +116,13 @@ interface UseDetailNavigationOptions<T extends { id: string }> {items: readonly T[];onOpenChange?: (open: boolean) => void;+ /**+ * Fires on every `setSearchQuery` call — useful when the consumer wants+ * to mirror the value into URL params, localStorage, or analytics. Like+ * `onOpenChange`, it fires in both controlled and uncontrolled mode.+ */+ onSearchQueryChange?: (query: string) => void;+/*** Controlled-mode opt-in for the sheet. When `open` is `undefined` the* controller owns the state internally; when a value is provided the@@ -96,6 +133,22 @@ interface UseDetailNavigationOptions<T extends { id: string }> {* `@/components/ui/autocomplete.tsx`.*/open?: boolean;++ /**+ * Debounce (ms) applied between the raw `searchQuery` typed by the user+ * and the `debouncedSearchQuery` that actually filters `filteredItems`.+ * Defaults to {@link DEFAULT_SEARCH_DEBOUNCE_MS}. Pass `0` for instant+ * filtering on small lists.+ */+ searchDebounceMs?: number;++ /**+ * Controlled-mode opt-in for the local search query — same `undefined`+ * → uncontrolled / value → controlled convention as `open`. Use this+ * when the consumer wants to surface the search outside the sheet (e.g.+ * a page-level search box that also drives sibling navigation).+ */+ searchQuery?: string;sortFn?: (a: T, b: T) => number;}@@ -133,13 +186,17 @@ const defaultGetId = (item: { id: string }): string => item.id;export function useDetailNavigation<T extends { id: string }>({currentId,defaultOpen,+ defaultSearchQuery,getHref,getId,getLabel,getSearchableText,items,onOpenChange,+ onSearchQueryChange,open,+ searchDebounceMs,+ searchQuery,sortFn,}: UseDetailNavigationOptions<T>): DetailNavigationController<T> {const navigate = useNavigate();@@ -156,12 +213,43 @@ export function useDetailNavigation<T extends { id: string }>({[getSearchableText, getLabel],);+ // Controllable local search (same pattern as the sheet's `open` below).+ // Uncontrolled is the common case — most consumers want the controller to+ // own the value so the in-sheet input "just works". Controlled callers+ // (e.g. a page that mirrors the value to its own URL param) pass+ // `searchQuery` and observe via `onSearchQueryChange`.+ const onSearchQueryChangeRef = useLatestRef(onSearchQueryChange);+ const [internalSearchQuery, setInternalSearchQuery] = useState(defaultSearchQuery ?? '');+ const isSearchControlled = searchQuery !== undefined;+ const activeSearchQuery = isSearchControlled ? searchQuery : internalSearchQuery;+ const debouncedSearchQuery = useDebouncedValue(activeSearchQuery, searchDebounceMs ?? DEFAULT_SEARCH_DEBOUNCE_MS);++ const setSearchQuery = useCallback(+ (next: string) => {+ if (!isSearchControlled) {+ setInternalSearchQuery(next);+ }++ onSearchQueryChangeRef.current?.(next);+ },+ [isSearchControlled, onSearchQueryChangeRef],+ );+ const clearSearchQuery = useCallback(() => setSearchQuery(''), [setSearchQuery]);++ // Stabilise the query tuple so `useNavigation`'s `useMemo` only refires+ // when either source actually moved. Inline `[a, b]` per render would+ // defeat the memo even when both strings are unchanged.+ const queryTerms = useMemo(+ () => [debouncedFilter, debouncedSearchQuery] as const,+ [debouncedFilter, debouncedSearchQuery],+ );+const { currentIndex, currentItem, filteredItems, nextId, prevId, total } = useNavigation<T>({currentId,getId: resolvedGetId,getSearchableText: resolvedGetSearchableText,items,- query: debouncedFilter,+ query: queryTerms,sortFn,});@@ -243,14 +331,17 @@ export function useDetailNavigation<T extends { id: string }>({const normalizedCurrentId = currentId != null ? String(currentId) : null;const hasEntries = filteredItems.length > 0;const itemsEmpty = items.length === 0;+ const isSearchActive = debouncedSearchQuery.length > 0;return useMemo<DetailNavigationController<T>>(() => ({+ clearSearchQuery,closeSheet,currentId: normalizedCurrentId,currentIndex,currentItem,debouncedFilter,+ debouncedSearchQuery,filteredItems,getId: resolvedGetId,getLabel,@@ -259,21 +350,27 @@ export function useDetailNavigation<T extends { id: string }>({goToPrev,handleItemSelect,hasEntries,+ isSearchActive,isSheetOpen,itemsEmpty,nextId,openSheet,positionLabel,prevId,+ searchQuery: activeSearchQuery,+ setSearchQuery,setSheetOpen,total,}),[+ activeSearchQuery,+ clearSearchQuery,closeSheet,normalizedCurrentId,currentIndex,currentItem,debouncedFilter,+ debouncedSearchQuery,filteredItems,resolvedGetId,getLabel,@@ -282,12 +379,14 @@ export function useDetailNavigation<T extends { id: string }>({goToPrev,handleItemSelect,hasEntries,+ isSearchActive,isSheetOpen,itemsEmpty,nextId,openSheet,positionLabel,prevId,+ setSearchQuery,setSheetOpen,total,],diff --git a/frontend/src/components/shared/detail-navigation/use-navigation.test.ts b/frontend/src/components/shared/detail-navigation/use-navigation.test.tsindex f666cd41..df0e520b 100644--- a/frontend/src/components/shared/detail-navigation/use-navigation.test.ts+++ b/frontend/src/components/shared/detail-navigation/use-navigation.test.ts@@ -258,6 +258,63 @@ describe('computeNavigation', () => {expect(result.currentIndex).toBe(0);});+ it('treats an empty array query as "no filter"', () => {+ const result = computeNavigation({+ currentId: 'c',+ getId,+ getSearchableText: getTitle,+ items: ROWS,+ query: [],+ });++ expect(result.filteredItems.map(getId)).toEqual(['a', 'b', 'c', 'd']);+ expect(result.currentIndex).toBe(2);+ });++ it('ANDs every non-empty term when `query` is an array', () => {+ // Both terms must match the haystack — substring "a" matches Alpha,+ // Bravo, Charlie; substring "ph" then narrows to just Alpha.+ const result = computeNavigation({+ currentId: 'a',+ getId,+ getSearchableText: getTitle,+ items: ROWS,+ query: ['a', 'ph'],+ });++ expect(result.filteredItems.map(getId)).toEqual(['a']);+ expect(result.currentIndex).toBe(0);+ expect(result.prevId).toBeNull();+ expect(result.nextId).toBeNull();+ });++ it('drops empty strings from an array query without throwing', () => {+ // Callers can pass `[urlFilter, localSearch]` straight through; either+ // one being empty must not turn the whole filter off — the other term+ // is still expected to narrow.+ const result = computeNavigation({+ currentId: 'b',+ getId,+ getSearchableText: getTitle,+ items: ROWS,+ query: ['', 'bravo', ''],+ });++ expect(result.filteredItems.map(getId)).toEqual(['b']);+ });++ it('falls back to "no filter" when every array term is empty', () => {+ const result = computeNavigation({+ currentId: 'a',+ getId,+ getSearchableText: getTitle,+ items: ROWS,+ query: ['', '', ''],+ });++ expect(result.filteredItems.map(getId)).toEqual(['a', 'b', 'c', 'd']);+ });+it('matches numeric item ids with string currentId', () => {type NumRow = { id: number; title: string };const rows: readonly NumRow[] = [diff --git a/frontend/src/components/shared/detail-navigation/use-navigation.ts b/frontend/src/components/shared/detail-navigation/use-navigation.tsindex fe455012..67541ff3 100644--- a/frontend/src/components/shared/detail-navigation/use-navigation.ts+++ b/frontend/src/components/shared/detail-navigation/use-navigation.ts@@ -12,12 +12,17 @@ interface NavigationInput<T> {getSearchableText?: (item: T) => null | string | undefined;items: readonly T[];/**- * Free-text filter to narrow the navigable subset. Empty / `undefined` is- * treated as "no filter" and every item passes. Matching reuses- * `createTextMatcher`, so behaviour matches the list page's column- * filter (substring, case + diacritic insensitive).+ * Free-text filter(s) to narrow the navigable subset. Accepts:+ * - `undefined` / empty string / empty array → no filter, every item passes;+ * - a single string → substring match (case + diacritic insensitive);+ * - a `readonly string[]` → AND of every non-empty entry. Empty strings+ * inside the array are ignored, so callers can pass+ * `[urlFilter, localSearch]` without checking emptiness at the call site.+ *+ * Matching reuses `createTextMatcher`, so behaviour stays in lockstep with+ * the list page's column filter regardless of how many sources combine here.*/- query?: string;+ query?: readonly string[] | string;sortFn?: (a: T, b: T) => number;}@@ -48,10 +53,24 @@ export const computeNavigation = <T>({query,sortFn,}: NavigationInput<T>): NavigationResult<T> => {- const hasQuery = query !== undefined && query.length > 0;+ // Normalise `string | string[] | undefined` to a list of non-empty terms.+ // Empties are dropped here once so the hot `items.filter` below never+ // re-checks them — and callers can splice `[urlFilter, localSearch]`+ // straight through without short-circuiting at the call site.+ const queryTerms = query === undefined ? [] : Array.isArray(query) ? query : [query as string];+ const activeTerms = queryTerms.filter((term): term is string => term.length > 0);+ const hasQuery = activeTerms.length > 0;+ // Build each matcher once at the top of the filter pass — `createTextMatcher`+ // normalises the term, so doing it inside the per-item loop would burn+ // O(items × terms) on the same work.+ const matchers = hasQuery && getSearchableText ? activeTerms.map(createTextMatcher) : null;const filtered =- hasQuery && getSearchableText- ? items.filter((item) => createTextMatcher(query)(getSearchableText(item)))+ matchers && getSearchableText+ ? items.filter((item) => {+ const text = getSearchableText(item);++ return matchers.every((match) => match(text));+ }): items;const ordered = sortFn ? [...filtered].sort(sortFn) : filtered;@@ -98,8 +117,12 @@ interface UseNavigationOptions<T> {*/getSearchableText?: (item: T) => null | string | undefined;items: readonly T[];- /** Free-text filter. Empty / `undefined` → unfiltered. */- query?: string;+ /**+ * Free-text filter. Accepts a single string or an array (AND of every+ * non-empty entry). Empty / `undefined` / `[]` → unfiltered. See+ * {@link NavigationInput.query} for details.+ */+ query?: readonly string[] | string;/*** Optional comparator. When omitted, the input array order is preserved —* the navigation walks `items` exactly as the caller arranged them, which