Search Contacts and Peer Mentors by Name or Attribute
The contact search feature must provide a debounced search bar at the top of the contact list that queries both the online Supabase backend and a local offline cache. Search results must update as the user types, with a configurable debounce delay to avoid excessive API calls. The search must respect the same RLS policies as the main list, ensuring coordinators only find contacts within their chapter. Offline mode must degrade gracefully by searching the local cache.
User Story
Audience Summaries
Coordinators managing dozens to hundreds of contacts face a critical productivity bottleneck when urgent assignments arise — manual list scrolling is too slow when a peer mentor is needed immediately. This high-priority search feature eliminates that bottleneck by delivering real-time, debounced search that works both online and offline. The offline fallback is especially strategic: Norway's rural and remote counties, where many Blindeforbundet coordinators operate, may have unreliable connectivity, and productivity must not drop when network access is lost. Faster contact matching directly reduces the time-to-assignment metric, improving service responsiveness for visually impaired clients who depend on timely mentor support.
This capability also reduces coordinator frustration and cognitive load, supporting staff retention. As contact lists grow with organizational expansion, search becomes foundational infrastructure for the platform's long-term usability.
Rated high priority, this story has a single upstream dependency on story-contact-list-management-coordinator-001. Delivery scope includes: debounced search input with a configurable delay parameter (allows future tuning without code changes), dual-path query logic (Supabase online + local cache offline), offline indicator UI, and result-tap navigation to contact detail screens. The configurable debounce delay should be treated as a system-level setting to avoid future regression risk if API rate limits change. Testing must cover: debounce correctness (exactly one API call per interval), RLS enforcement (coordinator cannot surface contacts outside their chapter via search), offline behavior across both iOS and Android, and edge cases such as empty results, special characters, and rapid input clearing.
Coordination with the backend team is needed to confirm the Supabase query endpoint supports partial-name matching efficiently at scale. Rollout risk is low given the well-defined acceptance criteria, but performance testing at high contact volumes is recommended before release.
The search implementation requires a debounced TextInput component with a configurable delay (recommend exposing via app config or environment variable, not hardcoded). On debounce trigger, the query should fan out: if online, execute a Supabase `.ilike()` or full-text search query with RLS policies enforced server-side (coordinators must not receive contacts outside their chapter); if offline, query the local SQLite or AsyncStorage cache using a case-insensitive string match. The minimum 2-character threshold prevents expensive queries on single-character input. Search results must re-render within 400ms per the acceptance criteria — profile this on lower-end Android devices.
Clearing the input must restore the full contact list from the existing list state without re-fetching (debounce should not trigger on empty string). Navigation on result tap reuses the existing contact detail route. Edge cases: rapid typing followed by immediate clear, offline-to-online transition mid-search, and RLS-filtered empty results should each be handled with appropriate UI feedback.
Acceptance Criteria
- Given I am on the contact list screen, when I tap the search bar and type at least 2 characters, then the list filters to show matching contacts within 400ms
- Given I am searching for a contact, when the search debounce triggers, then only one API call is made per debounce interval rather than one call per keystroke
- Given I am offline, when I search for a contact, then the search queries the local offline cache and displays cached results with an offline indicator
- Given search results are displayed, when I tap a result, then I am navigated to the contact detail screen for that contact
- Given I clear the search bar, when the input is empty, then the full contact list is restored without requiring a manual reload
Business Value
Coordinators managing dozens to hundreds of contacts cannot rely on manual scrolling when time-sensitive situations arise, such as finding an available peer mentor for an urgent assignment. Real-time debounced search with offline fallback ensures productivity is maintained regardless of network conditions, directly reducing response time for contact matching and assignment.
Components
- Contact List Screen ui
- Contact Search Bar ui
- Contact Search Service service
- Contact Search Screen ui
- Accessible Search Input Field ui
- Search Results List ui
- Contact Search Service service
- Supabase Contact Search Repository data
- Offline Contact Search Repository data
- Contact Cache Sync Repository data
- Search Debounce Utility infrastructure