Contact List & Search
Feature Detail
Description
This feature provides coordinators and peer mentors with a unified interface for browsing, searching, and filtering their contact lists and peer mentor rosters. The system supports role-specific views so coordinators see full contact management options while peer mentors see a simplified view relevant to their assignments. Filtering capabilities allow users to narrow results by status, area, or custom fields, reducing cognitive load when working with large contact lists. The list view is optimized for low-cognitive-load interaction with accessible list and card layout modes.
Analysis
A fast and reliable contact list is the daily operational backbone for coordinators managing hundreds of peer mentors and contacts. Without efficient search and filtering, coordinators waste significant time scrolling through long lists, increasing administrative burden and reducing time available for meaningful support work. For organisations with large volunteer networks like NHF (1,400 local branches) and Blindeforbundet, the ability to quickly locate the right peer mentor or contact is critical to operational efficiency. The feature directly reduces frustration and increases adoption by making the most-used screen feel fast and purposeful, which is especially important for users with cognitive or motor challenges.
Implemented in Flutter with a SearchDelegate or inline search bar triggering debounced Supabase queries filtered by organisation membership and role scope. The list uses SliverList for performance with large datasets, with a toggle between list and card views stored in local preferences. Role-based filtering is enforced both client-side (via BLoC state) and server-side (Supabase RLS policies). Contact data is cached locally using Riverpod with periodic refresh to support low-connectivity scenarios. Accessibility requirements mandate that all list items have semantic labels and sufficient touch target sizes (WCAG 2.2 AA), and the search bar must be reachable via screen reader without additional navigation steps.
Dependencies
Definition of Done
Components (8)
User Stories (14)
As a As a user
I want I want to switch between a Contacts view and a Peer Mentors view using a toggle widget
So that So that I can focus on the category of people most relevant to what I am currently doing without navigating away
- Given a user is on the Contacts screen, when they tap the view switcher toggle, then the list switches between Contacts and Peer Mentors views immediately
- Given a user switches to the Peer Mentors view and closes the app, when they reopen the app and navigate to Contacts, then the Peer Mentors view is still selected
- Given the Contacts view is active, when peer mentor-specific data fields are not applicable, then they are not displayed in the contact cards
- +2 more
As a As a Peer Mentor (Likeperson)
I want I want to see a simplified contact list showing only the individuals I am currently assigned to support
So that So that I can quickly locate the person I need without being distracted by contacts that are not relevant to my current assignments
- Given a peer mentor opens the Contacts screen, when the list loads, then only contacts linked to their active assignments are displayed
- Given a peer mentor's list is loaded, when they view a contact card, then coordinator-specific management actions (edit, assign, notes admin) are not shown
- Given a peer mentor has no active assignments, when the Contacts screen loads, then an appropriate empty state message is shown explaining that no contacts are currently assigned
- +2 more
As a As a user
I want I want to open a filter panel and narrow my contact list by status, area, or custom fields
So that So that I can quickly focus on a specific subset of contacts without manually scanning the entire list
- Given a user is on the Contacts screen, when they open the filter panel, then they see options to filter by status, area, and available custom fields
- Given a user applies a status filter, when the filter is active, then only contacts matching the selected status are shown in the list
- Given a user applies multiple filters simultaneously, when results are displayed, then only contacts matching all active filters are shown
- +3 more
As a As a user
I want I want to view my contact list even when my internet connection is poor or unavailable
So that So that I can still look up a contact or peer mentor when I am in the field without reliable network access
- Given a user has previously opened the Contacts screen with internet access, when they open the screen without internet connectivity, then the cached contact list is displayed
- Given the app is offline, when the contact list is showing cached data, then a visible indicator informs the user that data may be outdated
- Given the app regains internet connectivity, when the refresh triggers, then the contact list updates automatically in the background without requiring user action
- +2 more
As a As a user
I want I want to browse, search, and interact with the contact list using a screen reader such as VoiceOver or JAWS
So that So that visually impaired peer mentors and coordinators can use the contact list independently and efficiently
- Given a VoiceOver or JAWS user navigates to the Contacts screen, when they move through the list, then each contact card announces name, status, area, and available actions in a logical order
- Given a screen reader user reaches the Contact Search Bar, when navigating the screen, then the search bar is reachable without requiring additional navigation gestures beyond standard linear navigation
- Given a screen reader user activates a filter, when the filter is applied and results update, then the change in result count or state is announced via an accessibility live region
- +3 more
As a As a user
I want I want to switch between a Contacts view and a Peer Mentors view using a toggle widget
So that So that I can focus on the category of people most relevant to what I am currently doing without navigating away
- Given a user is on the Contacts screen, when they tap the view switcher toggle, then the list switches between Contacts and Peer Mentors views immediately
- Given a user switches to the Peer Mentors view and closes the app, when they reopen the app and navigate to Contacts, then the Peer Mentors view is still selected
- Given the Contacts view is active, when peer mentor-specific data fields are not applicable, then they are not displayed in the contact cards
- +2 more
As a As a Coordinator
I want I want to see and access full contact management action shortcuts directly from the contact list cards
So that So that I can initiate common management actions like editing, assigning, or viewing notes without having to navigate into the full contact detail screen first
- Given a coordinator views the contact list, when they see a contact card, then coordinator-specific action shortcuts are visible on or adjacent to the card
- Given a peer mentor views the same contact list, when they see a contact card, then coordinator-specific action shortcuts are not shown
- Given a coordinator taps a management shortcut on a contact card, when the action is invoked, then they are taken directly to the relevant screen or action dialog
- +2 more
As a As a user
I want I want to open a filter panel and narrow my contact list by status, area, or custom fields
So that So that I can quickly focus on a specific subset of contacts without manually scanning the entire list
- Given a user is on the Contacts screen, when they open the filter panel, then they see options to filter by status, area, and available custom fields
- Given a user applies a status filter, when the filter is active, then only contacts matching the selected status are shown in the list
- Given a user applies multiple filters simultaneously, when results are displayed, then only contacts matching all active filters are shown
- +3 more
As a As a user
I want I want to view my contact list even when my internet connection is poor or unavailable
So that So that I can still look up a contact or peer mentor when I am in the field without reliable network access
- Given a user has previously opened the Contacts screen with internet access, when they open the screen without internet connectivity, then the cached contact list is displayed
- Given the app is offline, when the contact list is showing cached data, then a visible indicator informs the user that data may be outdated
- Given the app regains internet connectivity, when the refresh triggers, then the contact list updates automatically in the background without requiring user action
- +2 more
As a As a user
I want I want to browse, search, and interact with the contact list using a screen reader such as VoiceOver or JAWS
So that So that visually impaired peer mentors and coordinators can use the contact list independently and efficiently
- Given a VoiceOver or JAWS user navigates to the Contacts screen, when they move through the list, then each contact card announces name, status, area, and available actions in a logical order
- Given a screen reader user reaches the Contact Search Bar, when navigating the screen, then the search bar is reachable without requiring additional navigation gestures beyond standard linear navigation
- Given a screen reader user activates a filter, when the filter is applied and results update, then the change in result count or state is announced via an accessibility live region
- +3 more
As a As a user
I want I want to type a name or keyword in the search bar and see matching contacts instantly
So that So that I can find a specific contact or peer mentor quickly without scrolling through a long list
- Given a user is on the Contacts screen, when they tap the search bar and begin typing, then results update automatically with a debounce delay of ~300ms
- Given a coordinator types a partial name, when results are returned, then only contacts within their organisational scope are shown
- Given a peer mentor types a partial name, when results are returned, then only contacts linked to their active assignments are shown
- +3 more
As a As a user
I want I want to open the Contacts screen and see a list of contacts and peer mentors relevant to my role
So that So that I can quickly identify the people I need to interact with without being overwhelmed by records outside my scope
- Given a coordinator is authenticated, when they open the Contacts screen, then they see all contacts and peer mentors within their organizational scope
- Given a peer mentor is authenticated, when they open the Contacts screen, then they see only contacts linked to their active assignments
- Given a large contact list (100+ entries), when the screen loads, then items render progressively without blocking the UI using SliverList
- +2 more
As a As a user
I want I want to type a name or keyword in the search bar and see matching contacts instantly
So that So that I can find a specific contact or peer mentor quickly without scrolling through a long list
- Given a user is on the Contacts screen, when they tap the search bar and begin typing, then results update automatically with a debounce delay of ~300ms
- Given a coordinator types a partial name, when results are returned, then only contacts within their organisational scope are shown
- Given a peer mentor types a partial name, when results are returned, then only contacts linked to their active assignments are shown
- +3 more
As a As a user
I want I want to open the Contacts screen and see a list of contacts and peer mentors relevant to my role
So that So that I can quickly identify the people I need to interact with without being overwhelmed by records outside my scope
- Given a coordinator is authenticated, when they open the Contacts screen, then they see all contacts and peer mentors within their organizational scope
- Given a peer mentor is authenticated, when they open the Contacts screen, then they see only contacts linked to their active assignments
- Given a large contact list (100+ entries), when the screen loads, then items render progressively without blocking the UI using SliverList
- +2 more