Keybindings and Mouse Support
Relevant source files
The following files were used as context for generating this wiki page:
The vscli tool features an interactive Terminal User Interface (TUI) primarily accessed via the recent command. This interface allows users to browse, search, and manage recently opened workspaces. To ensure an efficient developer experience, the TUI implements a robust set of keybindings and mouse interactions, enabling quick navigation, entry deletion, and project launching directly from the terminal.
The system is built using the ratatui library for rendering and crossterm for terminal event handling. It translates raw terminal inputs into high-level application actions, allowing users to interact with a list of historical entries stored in the history.json file.
Sources: README.md:144-149, src/ui.rs:219-232, src/main.rs:77-83
Input Architecture and Event Flow
The interaction system is centralized around the handle_input function, which processes crossterm::event::Event types. These events are mapped to an internal AppAction enum, which decouples the physical input (key press or mouse click) from the logic executed by the application.
The flow shows how raw terminal events are converted into actionable application commands.
Sources: src/ui.rs:22-34, src/ui.rs:310-349
AppAction Enum
The system uses the following variants to handle user intent:
Quit: Exits the TUI.SelectNext/SelectPrevious: Navigates the table.SelectFirst/SelectLast: Jumps to the start/end of the list.OpenSelected: Triggers the launch of the highlighted workspace.DeleteSelectedEntry: Removes the entry from history.SearchInput: Passes input to the fuzzy filtering engine.TableClick(u16): Handles mouse coordinate mapping.
Sources: src/ui.rs:24-34
Keyboard Shortcuts
Keyboard support includes standard navigation keys, Vim-style bindings (Ctrl+J/K), and shortcuts for project management. If an input does not match a defined shortcut, it is treated as a character for the fuzzy search input.
Navigation and Selection
| Action | Key Combination | Description |
|---|---|---|
| Select Next | Down or Ctrl+J | Moves the highlight to the next item. |
| Select Previous | Up or Ctrl+K | Moves the highlight to the previous item. |
| Select First | KeypadBegin or Ctrl+1 | Jumps to the top of the history list. |
| Select Last | End or Ctrl+0 | Jumps to the bottom of the history list. |
Sources: README.md:144-150, src/ui.rs:319-326
Execution and Management
| Action | Key Combination | Description |
|---|---|---|
| Open Selected | Enter or Ctrl+O | Launches the editor for the selected workspace. |
| Delete Entry | Delete, Ctrl+R, or Ctrl+X | Removes the selected item from the history.json. |
| Quit | Esc, Ctrl+Q, or Ctrl+C | Closes the UI without taking action. |
Sources: README.md:144-150, src/ui.rs:316-318, src/ui.rs:327-330
Mouse Support
The TUI enables mouse interactions by executing EnableMouseCapture upon startup. This allows users to navigate the list using the scroll wheel and select or open projects using clicks.
The sequence diagram illustrates the double-click-to-open logic implemented for mouse interactions.
Sources: src/ui.rs:223-228, src/ui.rs:289-307
Mouse Interaction Logic
- Scrolling:
MouseEventKind::ScrollDownmaps toAppAction::SelectNext, whileScrollUpmaps toAppAction::SelectPrevious. - Selection: A single left click on a row selects that entry.
- Launching: If a row is already selected and the user clicks it again (effectively a double-click or confirm click), the application triggers the
OpenSelectedaction. - Coordinate Mapping: The system calculates the clicked row relative to the terminal area, accounting for the header and borders (specifically checking if
row >= table_area.y + 2).
Sources: src/ui.rs:289-308, src/ui.rs:341-348
Search and Filtering
Keybindings are dynamically shared with the search component. The run_app loop treats non-shortcut keys as SearchInput.
// src/ui.rs:333-334
// For other key events (typing), pass to search input
return Some(AppAction::SearchInput((*key).into()));
When a user types, the apply_filter method is called. This uses the nucleo-matcher crate to perform fuzzy matching across the workspace name, dev container name, and file path. The UI then updates the table_state to ensure a valid selection remains visible after the list is filtered.
Sources: src/ui.rs:118-135, src/ui.rs:175-202, src/ui.rs:333-334
Visual Instructions
The interface provides a status bar at the bottom containing a summary of available keybindings. Users can suppress this information using the --hide-instructions flag in the CLI.
// src/ui.rs:502-511
if !hide_instructions {
let instruction = Span::styled(
"↑/↓ to navigate • Del/Ctrl+X to remove • Enter to open • Type to filter • Esc/Ctrl+C to quit",
Style::default().fg(Color::Gray),
);
// ... rendering logic
}
Sources: src/ui.rs:502-511, src/opts.rs:72-74
Summary
Keybindings and mouse support in vscli are designed for high-velocity navigation of project history. By leveraging crossterm for event capture and an internal action-based architecture, the tool provides a consistent experience across different terminals, supporting standard navigation, Vim-style shortcuts, and intuitive mouse interactions. All interactions are grounded in the history.json tracker, ensuring that actions like deletion or selection are persisted correctly.
Sources: src/ui.rs:235-245, src/history.rs:166-175