Favorites System

Description

The Favorites System allows users to save quick-access shortcuts to frequently used screens, reports, and saved searches throughout the application. Users can favorite a screen by clicking the "Add to Favorites" star icon displayed on that screen, or mark saved searches as favorites when creating or managing them. All favorited items appear in a persistent favorites menu accessible from anywhere in the application.

Mockups

Navigation and Access

Figure 99.1.1: Favorites star icon persistently displayed in main navigation bar

Figure 99.1.2: Empty state when user has no favorites with instructional text

Figure 99.1.3: Dropdown menu showing favorite screens, reports, and saved searches with vertical scrolling

---

Adding Favorites

Figure 99.1.4: "Add to Favorites" button with outline star icon in top-right corner of screen

Figure 99.1.5: Success toast message "Added [Screen Name] to Favorites" after adding to favorites

---

Removing Favorites

Figure 99.1.6: Toast message "Removed [Screen Name] from Favorites" after successful removal from screen

Figure 99.1.7: Confirmation dialog when removing favorite from dropdown menu with Cancel and Confirm buttons

---

Managing Favorites

Figure 99.1.8: User reordering favorites via drag-and-drop within dropdown menu with visual feedback showing dragged item

---

Limits and Warnings

Figure 99.1.9: Warning message when user reaches 45 of 50 favorites with count indicator

Figure 99.1.10: Error message when attempting to add favorite at 50-item limit

---

Edge Cases and Error States

Figure 99.1.11: Favorite entries showing disabled states with strikethrough text and lock icons for screens that no longer exist or user has lost access to

---

View complete interactive Figma prototype →

Business Rules

Access and Navigation

Rule 1: The system must display the favorites icon persistently in the main navigation bar, accessible from all screens in the application. When the user clicks the favorites icon, the system must open a dropdown menu displaying all of the user's favorited items (page favorites and saved searches). The dropdown menu must support vertical scrolling when the number of items exceeds the visible area. Individual record detail pages must not display the "Add to Favorites" button and cannot be favorited. Saved searches are added to favorites through the saved search management interface (see Section Data Table Functionality - Rule #5).

Rationale: Record detail pages are excluded because they contain dynamic, record-specific data that varies by ID parameter. Favoriting these would create inconsistent user experiences when records are modified or deleted.

Adding Favorites

Rule 2: When a user clicks the "Add to Favorites" star icon located in the top-right corner of a screen's content area, the system must:

1. Add the screen to the user's favorites list.
2. Persist the favorite to the database.
3. Display a success toast notification reading "Added [Screen Name] to Favorites".
4. Update the button state to "Remove from Favorites" with a filled star icon.
5. Log the action with timestamp, user ID, and favorited item URL.
6. Default Sort Order: New favorites are added to the top of the user's favorites list (most recent first).

Toast Notifications: All toast messages must display for 3 seconds before automatically dismissing.

Precondition: User has fewer than 50 favorites.

Postcondition: The favorited item appears in the user's favorites dropdown menu immediately.

Page Favorites – URL Storage

Rule 3: When creating a page favorite, the system must store only the base URL path, stripping all query parameters, hash fragments, filters, and state information from the current URL.

Examples:

• Input: /reports/sales?filter=Q3&region=west#summary
• Stored: /reports/sales

When a user clicks a page favorite, the system must navigate to the stored base URL, loading the screen in its default/initial state with no pre-populated data, filters, or selections.

Rationale: This ensures consistent behavior and prevents favorites from becoming outdated when query parameter structures change.

Saved Search Favorites – Reference Storage

Rule 4: When a saved search is added to favorites, the system must store a reference object containing:

• Target page URL (base path only)
• Saved search criteria ID (integer reference to saved_searches table)
• Search name (text, max 100 characters)
• Search type identifier (e.g., "saved_search")

When a user clicks a saved search favorite, the system must:

1. Navigate to the target page URL.
2. Automatically load and execute the saved search criteria using the stored search criteria ID.
3. Display search results.
4. Display a loading indicator during search execution.

Display Format: Saved search favorites must display with a search icon and "Search:" text prefix (e.g., "🔍 Search: Q3 Sales Report") to visually differentiate them from page favorites in the dropdown menu.

Favorite Limits

Rule 5: The system must enforce a maximum limit of 50 favorited items per user. When a user reaches 45 favorites, the system must display a warning message: "You have 45 of 50 favorites. Consider removing unused items." When the user attempts to add a 51st favorite, the system must:

1. Prevent the favorite from being added.
2. Display an error message: "You've reached the maximum of 50 favorites. Remove existing favorites to add new ones."

Data Persistence

Rule 6: The system must store all favorites data at the user account level in the database. Favorites must persist across all user sessions and remain available when the user logs in from any device.

Error Handling: If database operations fail due to network or server errors, the system must display a user-friendly error message and allow the user to retry the action.

Multi-Tab Behavior: If favorites are modified in one browser tab or window, other open tabs will reflect the changes when the favorites dropdown is reopened.

Button State Management

Rule 7: The system must dynamically update the favorites button on each screen based on the current favorite status:

When the screen is NOT favorited:

• Display: Outline star icon
• Label: "Add to Favorites"
• Action: Adds the page to favorites (see Rule 2)

When the screen IS favorited:

• Display: Filled/solid star icon
• Label: "Remove from Favorites"
• Action: Removes the page from favorites (see Rule 8)

The button state must:

• Update immediately when favorites are added or removed.
• Persist across user sessions.
• Reflect the current state on page load.
• Prevent duplicate favorite entries through client-side and server-side validation.

Accessibility: Button must have appropriate ARIA labels (aria-label="Add [Screen Name] to Favorites" or "Remove [Screen Name] from Favorites") and support keyboard navigation (Enter/Space to activate).

Quick Removal from Screen

Rule 8: When a user clicks "Remove from Favorites" on a screen's favorites button, the system must:

1. Remove the favorite immediately without confirmation.
2. Update the button state to "Add to Favorites" with outline star icon.
3. Display a toast notification: "Removed [Screen Name] from Favorites".
4. Persist the removal to the database.
5. Update the favorites dropdown menu on all open sessions.

Toast Notifications: All toast messages must display for 3 seconds before automatically dismissing.

Note: This quick removal applies only to the favorites button displayed on screens. Removal from the favorites dropdown menu requires confirmation (see Rule 10).

Rationale: On-screen removal provides a fast undo action for accidental favorites, while dropdown removal prevents accidental deletion of intentionally saved favorites.

Reordering Favorites

Rule 9: The system must allow users to reorder favorites via drag-and-drop within the favorites dropdown menu:

• Dragging must provide visual feedback (semi-transparent drag handle, highlighted drop zone)
• The system must persist the custom sort order to the database immediately upon drop
• Custom sort order must be maintained across all user sessions
• If persistence fails, the system must revert to the previous order and display an error: "Unable to save new order. Please try again."

Accessibility: Users must be able to reorder favorites using keyboard controls (Tab to focus, Space to grab, Arrow keys to move, Space to drop).

Removal from Dropdown Menu

Rule 10: When a user clicks the "X" (remove) icon next to a favorited item in the favorites dropdown menu, the system must:

1. Display a confirmation dialog with the message: "Remove [Screen/Report Name] from favorites?"
2. Provide two buttons: "Cancel" (secondary style) and "Confirm" (primary style, red/destructive color)
3. If the user clicks "Cancel", close the dialog with no changes
4. If the user clicks "Confirm":
   • Remove the favorite immediately from the dropdown
   • Persist the removal to the database
   • Update all open sessions
   • Display a toast notification: "Removed [Screen/Report Name] from Favorites"
   • Update the on-screen button state if the user is currently on that screen

Keyboard Support: Dialog must support Escape key to cancel and Enter key to confirm.

Disabled/Inaccessible Favorites

Rule 11: When a favorited screen or report is removed from the application or the user loses access permissions, the system must:

1. Retain the favorite entry in the user's favorites list
2. Display the entry in a disabled state with:
   • Strikethrough text styling
   • Lock icon (if permission-related) or broken link icon (if screen no longer exists)
   • Tooltip displaying the reason for disabled state
3. Prevent navigation when the disabled favorite is clicked
4. Display an informational message when clicked:
   • "This screen is no longer available" (for deleted screens)
   • "You no longer have access to this screen" (for permission issues)
5. Allow users to remove disabled favorites using the standard removal flow (Rule 10)

System Behavior: The system must check favorite validity when the favorites dropdown is opened and flag inaccessible items at that time.

Data Model

Favorites Table

The system must store the following data for each favorite:

• id - Unique identifier for the favorite (primary key)
• user_id - Reference to the user who owns this favorite (foreign key)
• item_type - Type of favorite: 'page' or 'saved_search'
• item_url - The base URL path for the favorited item
• saved_search_id - Reference to saved search criteria (nullable, only populated for saved_search types)
• display_name - The name shown to the user in the dropdown
• sort_order - Integer value determining display order (lower numbers appear first)
• created_at - Timestamp when the favorite was created