Navigator Modernization — P2: TanStack Query for Search

Branch: feat/navigator-p2-query (forked from feat/navigator-modernization @ 1148c0a6) Date: 2026-05-27 Depends on: P1 (hook split) — merged or pending merge

1. Goal

Migrate Navigator's search request/response from event-driven imperative state to TanStack Query. The user gets:

• Instant tab switching when the same tab/filter was visited before in the session (cache hit, no round-trip)
• Stale-while-revalidate on revisit (shows cached results while refetching in background)
• Server-driven refresh via useNitroEventInvalidator on FlatCreatedEvent and RoomSettingsUpdatedEvent (and possibly FavouriteChangedEvent if the active tab is favorites_view)
• Single source of truth for isFetching — no separate isLoading flag to manage

2. Architecture changes

2.1 New file: src/hooks/navigator/useNavigatorSearch.ts

The query hook. Reads currentTabCode + currentFilter from navigatorUiStore, fires NavigatorSearchComposer, waits for NavigatorSearchEvent, returns the parsed NavigatorSearchResultSet.

import { NavigatorSearchComposer, NavigatorSearchEvent, NavigatorSearchResultSet } from '@nitrots/nitro-renderer';
import { useNitroEventInvalidator, useNitroQuery } from '../../api/nitro-query';
import { useNavigatorUiStore } from './navigatorUiStore';

export const useNavigatorSearch = () =>
{
    const tabCode = useNavigatorUiStore(s => s.currentTabCode);
    const filter = useNavigatorUiStore(s => s.currentFilter);

    const query = useNitroQuery<typeof NavigatorSearchEvent, NavigatorSearchResultSet>({
        key: [ 'navigator', 'search', tabCode, filter ],
        request: () => new NavigatorSearchComposer(tabCode, filter),
        parser: NavigatorSearchEvent,
        select: e => e.getParser()?.result ?? null,
        accept: e => {
            const result = e.getParser()?.result;
            // accept-filter: only this query's matching tab code
            return !!result && result.code === tabCode;
        },
        enabled: !!tabCode,
        staleTime: 30_000   // re-fetch after 30s of staleness on revisit
    });

    useNitroEventInvalidator(FlatCreatedEvent, [ 'navigator', 'search' ]);
    useNitroEventInvalidator(RoomSettingsUpdatedEvent, [ 'navigator', 'search' ]);

    return {
        searchResult: query.data,
        isFetching: query.isFetching,
        refetch: query.refetch
    };
};

2.2 navigatorUiStore.ts additions

Add 2 new state fields + 2 new actions:

type NavigatorUiState = {
    // ...existing 9 flags...
    currentTabCode: string;   // '' until NavigatorMetadataEvent arrives, then first top-level context code
    currentFilter: string;    // '' by default
};

type NavigatorUiActions = {
    // ...existing 15 actions...
    setTab(code: string): void;        // also clears currentFilter
    setFilter(value: string): void;
};

setTab(code) resets currentFilter to '' because switching tabs starts a fresh search. setFilter updates only the filter — the user is typing in the same tab.

2.3 useNavigatorStore.ts — remove search state ownership

Remove:

• useState<NavigatorSearchResultSet>(null) for searchResult
• useMessageEvent<NavigatorSearchEvent> listener
• sendSearch and reloadCurrentSearch actions
• The useNavigatorUiStore.getState().setLoading(...) calls (no longer needed)
• The topLevelContextRef and searchResultRef (only consumed inside reloadCurrentSearch)

Keep:

• topLevelContext + topLevelContexts (these still come from NavigatorMetadataEvent and drive the tab list)
• The NavigatorMetadataEvent listener — but it now ALSO calls useNavigatorUiStore.getState().setTab(parser.topLevelContexts[0]?.code ?? '') on first arrival, to seed the initial tab. The query then activates because currentTabCode becomes non-empty (enabled: !!tabCode).

2.4 useNavigatorData.ts — remove searchResult from return shape

useNavigatorData() no longer returns searchResult. Consumers that need it call useNavigatorSearch() instead.

2.5 useNavigatorActions.ts — empty or removed

Both sendSearch and reloadCurrentSearch are gone. Either:

• Remove the file + the export — consumers use useNavigatorUiStore.getState().setTab(...) / setFilter(...) directly
• Or keep the file as an empty re-export for forward compat. (Decision: REMOVE — minimize dead API).

2.6 useNavigatorUiState.ts — add the 2 new flags

Add currentTabCode and currentFilter to the per-key selector list and return shape.

2.7 useNavigatorSearch.test.tsx — new

Test cases:

• Initial mount with empty tabCode → query is disabled, no request fired
• After setTab('public') → query fires NavigatorSearchComposer('public', '')
• After setFilter('cocco') → query fires NavigatorSearchComposer('public', 'cocco')
• After setTab('events') → currentFilter resets to '', query fires NavigatorSearchComposer('events', '')
• FlatCreatedEvent invalidates the cache → refetch
• RoomSettingsUpdatedEvent invalidates the cache → refetch
• NavigatorSearchEvent with WRONG tabCode (e.g. server pushes an unsolicited result) is REJECTED by accept filter — does NOT update query data

2.8 NavigatorView.tsx — major rewrite

Replace:

• useNavigatorActions import → gone
• useNavigatorData no longer destructures searchResult — get it from useNavigatorSearch instead
• 4 useEffect blocks driving the imperative search flow (needsSearch, needsInit lifecycle, reloadCurrentSearch orchestration) → gone
• Tab onClick={ () => sendSearch('', context.code) } → onClick={ () => useNavigatorUiStore.getState().setTab(context.code) }
• isLoading from useNavigatorUiState() → isFetching from useNavigatorSearch() query
• NavigatorInitComposer initial dispatch on first isVisible — KEEP (still need it to get topLevelContexts populated)
• pendingSearch ref — gone (linkTracker case 'search' directly does setTab(code); setFilter(value))

Major simplification: the file shrinks ~30 lines.

2.9 NavigatorSearchView.tsx — drive setFilter

Read the file. The component currently exposes a search input that, on enter or button click, calls sendSearch(value, currentTabCode). After P2 it:

• Reads currentFilter from useNavigatorUiState
• onChange → useNavigatorUiStore.getState().setFilter(value) (debounced 300ms)
• No more sendSearch reference

Debounce: use a local useState for the input text + a useEffect that calls setFilter(text) 300ms after the last keystroke. Standard pattern.

3. Backward-compat considerations

• useNavigatorActions.sendSearch and useNavigatorActions.reloadCurrentSearch are REMOVED. No consumer outside Navigator depends on them — verified by grepping the previous P1 consumer migration.
• useNavigatorData.searchResult is REMOVED. Only NavigatorView reads it currently — easy to migrate.
• The useNavigatorActions filter itself becomes empty — consider whether to delete the file entirely. Decision: delete the file to minimize the API surface. Tasks 5-8 of P1 migrated NavigatorSearchView to use useNavigatorActions — that's the only consumer; it migrates to useNavigatorUiStore directly.

4. Out of scope (each gets its own future spec)

• Reactive favourite stars on cards (P3)
• Visual rework: empty states, virtualization, chip-based UI (P4)
• Form Action on search input (P6)

5. Acceptance criteria

P2 is complete when:

1. src/hooks/navigator/useNavigatorSearch.ts exists and exports useNavigatorSearch
2. useNavigatorStore.ts no longer owns searchResult, no longer subscribes to NavigatorSearchEvent, no longer exposes sendSearch or reloadCurrentSearch
3. navigatorUiStore.ts has currentTabCode + currentFilter state and setTab + setFilter actions
4. useNavigatorActions.ts is deleted; barrel no longer exports useNavigatorActions
5. useNavigatorData.ts no longer returns searchResult
6. useNavigatorUiState.ts returns currentTabCode + currentFilter
7. NavigatorView.tsx reads searchResult from useNavigatorSearch(), uses isFetching for the loading flag, calls setTab on tab clicks
8. NavigatorSearchView.tsx debounces setFilter calls
9. yarn typecheck clean (same pre-existing floorplan errors)
10. yarn test --run green; smoke test updated; new useNavigatorSearch.test.tsx with 7 cases
11. yarn lint:hooks clean
12. Manual smoke: switch tabs rapidly → results cached, no flicker. Type filter → debounced refetch. Create a room → list refreshes.

6. Risk register

7. Plan (executable)

Task 1: Add UI store state + actions (TDD)

Files: src/hooks/navigator/navigatorUiStore.ts, src/hooks/navigator/navigatorUiStore.test.ts

• Add currentTabCode: string (initial '') and currentFilter: string (initial '') to NavigatorUiState
• Add setTab(code: string): void and setFilter(value: string): void to NavigatorUiActions
• setTab(code) sets { currentTabCode: code, currentFilter: '' } (atomic reset on tab change)
• setFilter(value) sets { currentFilter: value } (no tab side-effect)
• Update test file: 3 new cases — setTab updates tab and resets filter; setFilter updates filter without touching tab; idempotent setTab on same code resets filter to '' regardless
• yarn test --run src/hooks/navigator/navigatorUiStore.test.ts → green
• Commit: feat(navigator): add currentTabCode + currentFilter to UI store (P2 prep)

Task 2: Create useNavigatorSearch query hook (TDD)

Files: src/hooks/navigator/useNavigatorSearch.ts, src/hooks/navigator/useNavigatorSearch.test.tsx

Implement per §2.1 + §2.7 above. 7 test cases.

The test will need: QueryClientProvider wrapper, mock for NavigatorSearchComposer (probably already in mock), NavigatorSearchEvent dispatch with parser.result.code matching/non-matching.

• Commit: feat(navigator): useNavigatorSearch query hook (P2 core)

Task 3: Strip search ownership from useNavigatorStore + useNavigatorData + remove useNavigatorActions

Files: useNavigatorStore.ts, useNavigatorData.ts, useNavigatorActions.ts (DELETE), useNavigatorUiState.ts, index.ts

• Remove searchResult state + setSearchResult from useNavigatorStore
• Remove NavigatorSearchEvent listener from useNavigatorStore
• Remove sendSearch and reloadCurrentSearch from useNavigatorStore return
• Remove setLoading calls inside useNavigatorStore
• Remove topLevelContextRef and searchResultRef (no longer used after sendSearch/reload removal)
• In NavigatorMetadataEvent handler, add useNavigatorUiStore.getState().setTab(parser.topLevelContexts[0]?.code ?? '') after setTopLevelContext(...) — seeds the query when contexts arrive
• Remove searchResult from useNavigatorData destructure + return
• DELETE src/hooks/navigator/useNavigatorActions.ts
• Update useNavigatorUiState.ts to expose currentTabCode + currentFilter per-key selectors
• Update src/hooks/navigator/index.ts to remove useNavigatorActions export, add useNavigatorSearch export
• Update useNavigatorStore.test.tsx smoke test: 2 cases that expected searchResult in data shape or sendSearch/reloadCurrentSearch in actions shape — update accordingly (or just remove the "useNavigatorActions returns ..." test entirely)
• Verify typecheck: ONLY consumer-side errors expected (NavigatorView still references the old API). Hook files clean.
• Commit: refactor(navigator): remove search ownership from useNavigatorStore

Task 4: Migrate NavigatorView.tsx + NavigatorSearchView.tsx

Files: src/components/navigator/NavigatorView.tsx, src/components/navigator/views/search/NavigatorSearchView.tsx

• In NavigatorView:
  • Import useNavigatorSearch
  • Replace useNavigatorData destructure of searchResult with useNavigatorSearch() call returning { searchResult, isFetching }
  • Drop useNavigatorActions import + destructure (it's gone)
  • Drop the 4 lifecycle useEffect blocks (needsSearch / needsInit-init / markReady / reloadCurrentSearch); the new flow:
    • Keep the NavigatorInitComposer on first isVisible — still needed for metadata
    • Tab clicks call useNavigatorUiStore.getState().setTab(context.code)
    • linkTracker case 'search': store.setTab(parts[2]); store.setFilter(parts[3] ?? ''); store.show(); (no more pendingSearch ref)
  • Replace <NitroCard.Content isLoading={ isLoading }> with isFetching from the query
  • Drop the pendingSearch ref
• In NavigatorSearchView:
  • Read currentFilter from useNavigatorUiState for the initial input value
  • Local useState for the text being typed (mirrors the store value)
  • Debounce: useEffect with 300ms timer calling useNavigatorUiStore.getState().setFilter(text)
  • Remove all useNavigatorActions references — the search submit happens via store, query refires automatically
• yarn typecheck clean
• yarn test --run green
• yarn lint:hooks clean
• Commit: feat(navigator): drive search via TanStack Query + setTab/setFilter UI store actions

Task 5: PR

• Push branch
• Open PR against duckietm:Dev: feat(navigator): TanStack Query for search (P2)