Keyboard Shortcuts

Relevant source files

The following files were used as context for generating this wiki page:

• crates/mailiner-app/src/shortcuts.rs
• crates/mailiner-app/src/components/shortcuts.rs
• crates/mailiner-app/src/components/virtual_scroll.rs
• crates/mailiner-app/src/layout.rs
• crates/mailiner-app/src/components/messageview.rs (Referenced via imports)

Keyboard shortcuts enable efficient navigation and message management within Mailiner. The system provides global key bindings for mailbox navigation, message selection, scrolling, and administrative actions like deletion.

Architecture and Dispatch

The shortcut system consists of a central catalog, a global event listener, and a help overlay. Shortcuts are defined in a static registry and dispatched through a central handler that interacts with the application context and core event loop.

Core Data Structures

• ShortcutId: An enum representing unique stable identifiers for supported actions, such as JumpToFolder or MoveToTrash.
• Shortcut: A struct containing the metadata for a binding, including the associated ShortcutId, keys, Shift requirement, labels, and group classification.
• ShortcutGroup: Categorizes shortcuts into logical sets (Mail, Reading, Help) for display in the help dialog.

Sources: crates/mailiner-app/src/shortcuts.rs:6-60

Event Handling Logic

The ShortcutsHost component registers a global keydown event listener on the browser window. The handler filters events based on the following conditions:

1. Ignores events if Ctrl, Meta, or Alt keys are pressed.
2. Ignores events if the focus is on an editable element (Input, Textarea, Select, or contenteditable).
3. Ignores events if a compose draft is currently active.
4. Processes the Escape key or the help shortcut (?) specifically when the help dialog is already open.

Sources: crates/mailiner-app/src/components/shortcuts.rs:133-167

Shortcut Dispatch Flow

The following diagram illustrates how a keyboard event is transformed into an application action.

Shortcut Catalog

Mailiner defines a set of global shortcuts categorized by their functional area.

Mail Management

These shortcuts manage folder navigation and message state.

Shortcut	Key(s)	Action
Jump to Folder	J	Opens the folder picker in jump mode.
Move to Folder	M	Opens the folder picker for moving selected messages.
Next Message	↓	Selects the next adjacent message.
Previous Message	↑	Selects the previous adjacent message.
Extend Next	Shift+↓	Extends current selection to the next message.
Extend Previous	Shift+↑	Extends current selection to the previous message.
Move to Trash	Delete	Moves selected messages to the trash mailbox.
Delete Permanently	Shift+Delete	Deletes selected messages without using trash.

Sources: crates/mailiner-app/src/shortcuts.rs:72-126

Reading and Navigation

These shortcuts control the viewing experience of specific message content.

Shortcut	Key(s)	Action
Scroll Down	→	Scrolls the message view down by one line.
Scroll Up	←	Scrolls the message view up by one line.
Page Down	PageDown	Scrolls the message view down by one page.
Page Up	PageUp	Scrolls the message view up by one page.

Sources: crates/mailiner-app/src/shortcuts.rs:134-162

Component Interaction

Shortcuts trigger state changes or events in various specialized components.

Virtual Scroll and Selection

Shortcuts like NextMessage and PrevMessage calculate the adjacent_index based on the current selection and total item count. When a selection move occurs, the VirtualScroll component uses the reveal_index property to ensure the new selection is scrolled into the viewport.

Layout Reset

While not bound to primary alphanumeric keys, the layout system provides programmatic resets for UI panels (folder width and list height) which can be tied to the application context used by the shortcut runner.

Sources: crates/mailiner-app/src/layout.rs:35-44

Help System

The ShortcutHelp component renders a modal overlay displaying all registered shortcuts. It iterates through the ShortcutGroup::ALL slice and uses shortcuts_in_group to populate rows.

• Activation: Triggered by the ? key.
• Dismissal: Closed via the Escape key, clicking the backdrop, or the close icon button.
• Structure: Uses a picker-backdrop with a shortcut-dialog containing a list of kbd elements for keys and span elements for descriptions.

Sources: crates/mailiner-app/src/components/shortcuts.rs:183-228

Summary

The keyboard shortcut system provides a robust mechanism for power-user navigation in the Mailiner web interface. By utilizing a global window listener and a centralized catalog, it ensures consistent behavior across the application while protecting user input in forms and editor components.