Search Contacts by Name or Identifier
Coordinators manage large rosters of contacts and peer mentors across one or more chapters. Finding a specific person in a long list is time-consuming and error-prone. This story provides a dedicated search screen with a real-time, debounced search input that queries both online (Supabase) and offline (local cache) data sources, returning ranked results that match the query against name, phone, and other identifiable fields. Results are displayed in a consistent list with contact cards, allowing the coordinator to tap through to the full contact detail screen.
User Story
Audience Summaries
Coordinators across NHF, HLF, and Blindeforbundet manage large and growing rosters of contacts and peer mentors distributed across multiple chapters. Without fast, reliable search, locating the right person in a long list requires manual scrolling and introduces delays that compound across dozens of daily coordination tasks. This critical-priority story delivers a real-time search experience that cuts lookup time from minutes to seconds, enabling coordinators to assign peer mentors faster, follow up on open tasks more responsively, and provide higher-quality service to the members they serve. The direct beneficiary is the end member receiving peer mentoring — faster coordinator response translates to more timely support.
For the platform, this is a foundational capability: nearly every downstream workflow (task assignment, case follow-up, note review) begins with finding a person. Investing in search quality at this stage prevents friction from compounding as rosters grow, protecting long-term platform scalability and coordinator satisfaction.
As a critical-priority story with no upstream dependencies, this is a strong candidate for early-sprint delivery to unblock downstream workflows. The scope is well-defined: a dedicated search screen with debounced input, dual-source querying (Supabase online + local cache offline), ranked result display, and tap-through navigation to the contact detail screen. Effort should include UI implementation, debounce logic (300ms threshold per acceptance criteria), result ranking algorithm, and the offline fallback path — which introduces coordination dependency with the offline cache story (ID 333) if both are in flight simultaneously. Acceptance criteria are testable and specific, making UAT straightforward.
Testing should cover: minimum character threshold (2 chars), debounce timing, result card content (name, role badge, chapter), empty state display, offline banner behavior, and navigation correctness. No data migration is required. Rollout risk is low if the offline cache is available; without it, the offline acceptance criterion cannot pass, so sprint sequencing must account for this dependency even though it is not declared in the story metadata.
The search screen requires a unified repository interface that dispatches to either the Supabase remote query or the local offline cache based on current connectivity state — this abstraction should be shared with story 333 to avoid duplication. Debounce must be implemented at the input layer (300ms, cancelable on each keystroke) before triggering the repository query, preventing excessive API calls. The query should match against name, phone, and other identifiable fields using a case-insensitive, prefix-friendly search — on Supabase this maps to `ilike` or full-text search depending on index availability; on the local cache, use SQLite `LIKE` with indexed columns. Result ranking should prioritize exact name matches over partial matches.
Each result card renders name, role badge, and chapter affiliation — ensure these fields are always present in the result model to avoid null rendering bugs. Navigation to contact detail must pass the contact ID, not the full object, to avoid serialization issues across route boundaries. Edge cases: empty query (show no results, not an error), query with only whitespace (treat as empty), offline with empty cache (show sync-required empty state). Write widget tests for debounce behavior and unit tests for the repository dispatch logic.
Acceptance Criteria
- Given the coordinator is on any tab, when they navigate to the search screen, then a search input field is focused and ready for input
- Given the coordinator types at least 2 characters, when 300ms have elapsed without further input (debounce), then results matching the query appear in the results list
- Given search results are returned, when displayed, then each result shows the contact's name, role badge, and chapter affiliation
- Given no results are found, when the results list is rendered, then an empty-state message is shown explaining no matches were found
- Given the device is offline, when the coordinator performs a search, then results are served from the local offline cache and a banner indicates offline mode
- Given a result is tapped, when navigating, then the full contact detail screen opens for that contact
Business Value
Coordinators across NHF, HLF, and Blindeforbundet manage large contact rosters. Fast, accurate search directly reduces friction in daily coordination work, enabling faster assignment of peer mentors, quicker follow-up on open tasks, and more responsive care — all of which directly improve the quality of the peer mentoring service delivered to end users.
Components
- 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
- Contact Card Widget ui
- Peer Mentor Card Widget ui