Migrate manual data fetching to React Query hooks

[JohnRDOrazio]

Context

The codebase already uses React Query (@tanstack/react-query v5) in 5 hooks (analytics, search, cross-references, etc.), but 13 hooks and most page components still use manual useState/useEffect fetch patterns. This causes duplicate network requests and inconsistent caching.

The most impactful example: projectApi.get() is called independently from 9 different page components — navigating between project pages triggers redundant fetches that React Query's shared cache would eliminate.

Phase 1: useProject hook (completed in PR #86)

• Create useProject(projectId) hook wrapping projectApi.get() in useQuery
• Create derivePermissions() helper to centralize permission logic
• Migrate viewer page, dashboard, pull-requests, suggestions, suggestion review, and useProjectViewer (6 of 9 call sites)
• Migrate settings page (3 remaining calls — complex due to post-mutation state updates)
• Add invalidateQueries calls after project mutations in settings page

Phase 2: Secondary Data Queries (future)

• Migrate useRemoteSync.ts to useQuery + refetchInterval for polling
• Extract PR count, lint summary, and normalization status fetches from useProjectViewer into standalone useQuery hooks
• Create factory hooks for projectOntologyApi searches

Phase 3: Complex Queries (optional, higher risk)

• Evaluate refactoring useOntologyTree.ts to use React Query with per-node queries
• Evaluate refactoring useGraphData.ts to coordinate multiple queries
• Implement proper invalidateQueries strategy for entity create/update/delete mutations

Not suitable for migration

• useSuggestionSession.ts — state machine with strict lifecycle ordering
• useAutoSave.ts / useEntityAutoSave.ts — local-first draft management
• useTreeDragDrop.ts — optimistic UI with manual rollback
• useKeyboardShortcuts.ts, useFilteredTree.ts — UI state, not data fetching

Benefits

• Deduplication — redundant projectApi.get() calls share a single cache entry
• Stale-while-revalidate — instant page transitions with background refresh
• DevTools — React Query DevTools for debugging query state and cache
• Automatic refetch — on window focus/reconnect
• Simplified error handling — centralized via query error state

Related

• PR fix: viewer source tab empty in developer mode #86 — Phase 1 implementation

[JohnRDOrazio]

Phase 1 implemented in PR #86

PR #86 includes the initial React Query migration alongside the viewer source fix:

• Created lib/hooks/useProject.ts with useProject(projectId, accessToken) hook wrapping projectApi.get() in useQuery, plus a derivePermissions() helper for centralized permission logic
• Migrated 6 of 9 projectApi.get() call sites to the shared hook:
  • app/projects/[id]/page.tsx (viewer)
  • app/projects/[id]/dashboard/page.tsx
  • app/projects/[id]/pull-requests/page.tsx
  • app/projects/[id]/suggestions/page.tsx
  • app/projects/[id]/suggestions/review/page.tsx
  • lib/hooks/useProjectViewer.ts (editor hook)
• Net change: -286 lines, +153 lines

The settings page (3 remaining calls) was deferred — its projectApi.get() calls are tightly coupled with post-mutation setProject() state updates that need queryClient.invalidateQueries to replace properly.

Remaining work tracked in the checkboxes above (Phase 1 settings migration, Phase 2, Phase 3).

[JohnRDOrazio]

Note: There is a pre-existing react-hooks/set-state-in-effect lint warning in lib/hooks/useGraphData.ts — the early return when focusIri becomes null calls setGraphData(null) and setIsLoading(false) synchronously inside a useEffect, which the React compiler flags as potentially causing cascading renders.

This warning will be naturally resolved by the React Query migration tracked here, since useQuery handles loading/data/error state internally — eliminating the manual useState + useEffect pattern entirely.

[JohnRDOrazio]

Cross-linking #200 — that issue tracks eliminating the 16 react-hooks/set-state-in-effect warnings across the codebase so the rule can graduate from "warn" to "error".

Of those 16 sites, only 3 (Category C in #200) are actually data-fetching mirrors that this issue's React Query migration would naturally clean up:

• lib/context/BranchContext.tsx:116 and :149 — currentBranch mirrored from a query response
• app/projects/[id]/suggestions/page.tsx:83 — manual setIsLoadingSessions/setSessions/setSessionsError from a suggestionsApi.listSessions fetch (a clean Phase-2 candidate here)

The other 13 sites are reset-on-prop-change patterns (key-prop fix), browser-API subscriptions (useSyncExternalStore), or one-shot init (lazy useState initializer). Those are out of scope here and tracked in #200 — the two efforts share at most ~20% overlap.