Mailbox Navigation & Message Lists
Relevant source files
The following files were used as context for generating this wiki page:
Mailbox Navigation and Message Lists provide the core interface for browsing email folders and viewing message headers. These components manage folder hierarchies, track message selection, and handle the asynchronous loading of message ranges from IMAP servers. The system ensures efficiency through virtual scrolling and localized caching of message metadata.
Mailbox Hierarchy and State
The application represents email folders as a tree of MailboxNode objects. Each node tracks its relationship to parents and children, its special-use role (e.g., Inbox, Trash), and unread message counts.
Mailbox Data Structures
| Field | Type | Description |
|---|---|---|
id | MailboxId | Unique identifier for the mailbox. |
name | String | Raw server name of the folder. |
role | MailboxRole | Functional role (Inbox, Sent, Drafts, Trash, etc.). |
unread_count | usize | Number of unread messages in the folder. |
selectable | bool | Whether the folder can be opened (false for \Noselect parents). |
Sources: crates/mailiner-app/src/mailbox.rs:32-42
Tree Generation Logic
The build_mailbox_tree function transforms a flat list of folders into a hierarchical structure. It sorts folders based on their role rank and alphabetical name, ensuring common folders like the Inbox appear first.
The diagram above shows the process of transforming flat IMAP folder data into the sorted tree used by the UI navigation.
Sources: crates/mailiner-app/src/mailbox.rs:61-118
Message List Management
The MessageList component displays message headers for the currently selected mailbox. It utilizes a VirtualScroll component to handle large folders by only rendering visible items and pre-fetching adjacent ranges.
Virtual Scrolling Mechanics
To maintain performance, the message list uses fixed-height rows and a buffer system. It triggers CoreEvent::FetchMessageRange when the user scrolls near the boundaries of the currently cached messages.
- Item Height: 52 pixels per message row.
- Buffer Size: 5 items.
- Max Cached: 500 messages.
Sources: crates/mailiner-app/src/components/emailnavigation/messagelist.rs:31-33, crates/mailiner-app/src/components/emailnavigation/messagelist.rs:44-48
Message Interaction Flow
The UI handles selection through mouse events, supporting standard modifiers for range and toggle selection.
This sequence diagram illustrates the flow from a user clicking a message to the asynchronous fetching of message data via the IMAP connector.
Sources: crates/mailiner-app/src/components/emailnavigation/messagelist.rs:59-74, crates/mailiner-imap-connector/src/lib.rs:555-565
Navigation Layout and Customization
The layout of the navigation and list panes is persistent and adjustable. Users can resize the folder pane and message list through split handles, with sizes saved to the browser's local storage.
Layout Constraints
| Property | Default | Min | Max |
|---|---|---|---|
| Folder Width | 240px | 160px | 480px |
| List Height | 40% | 18% | 70% |
Sources: crates/mailiner-app/src/layout.rs:6-14
The apply_saved_layout function reads these values and applies them as CSS variables (--folder-pane-width and --message-list-height) to the root #app element, which the stylesheet uses to calculate pane dimensions.
Sources: crates/mailiner-app/src/layout.rs:81-91, crates/mailiner-app/assets/main.css:910-925
Message Filtering and Search
The system provides localized filtering for mailboxes through the filter_mailbox_entries function. It performs a case-insensitive match against title, path, and ID.
- Exact Match: Ranks highest (Score 0).
- Prefix Match: Ranks second (Score 1).
- Content Match: Matches title/name (Score 2).
- Path/ID Match: Ranks lowest (Score 3).
Sources: crates/mailiner-app/src/mailbox.rs:248-270
Message Loading and Synchronization
The ImapConnector manages the actual retrieval of message metadata (envelopes). It uses the prepare_folder_list method to establish the initial state and sort order for a folder before fetching specific ranges.
The diagram outlines how the connector determines the sorting strategy before retrieving message envelopes for the UI.
Sources: crates/mailiner-imap-connector/src/lib.rs:518-535, crates/mailiner-imap-connector/src/lib.rs:728-750
Summary
The Mailbox Navigation and Message List systems combine hierarchical folder management with high-performance virtual scrolling. By utilizing a sorted tree structure for mailboxes and a buffered range-fetching strategy for messages, the application remains responsive even with large accounts. Persistent layout settings and robust IMAP synchronization ensure a consistent and efficient user experience.