Command Palette
Relevant source files
The following files were used as context for generating this wiki page:
The Command Palette is a central navigation and action hub within the Hoop WebApp V2, providing users with a "Spotlight" style interface to search for resources, execute commands, and navigate the application. It serves as a unified search interface that indexes connections, runbooks, and various application routes, allowing for rapid interaction via keyboard shortcuts (specifically ⌘K or Ctrl+K).
The feature is part of the "React Shell" migration strategy, where global infrastructure components like the sidebar and palette are hosted in React while the application migrates away from its legacy ClojureScript implementation. It supports multi-page navigation within the palette itself, enabling deep-dive actions such as selecting specific resource roles or initiating terminal sessions directly from the search results.
Sources: webapp_v2/CONTEXT_MIGRATION.md:31-45, webapp_v2/src/layout/Sidebar/constants.js:46-54
Architecture and Components
The Command Palette is built using a multi-layered component structure based on the Mantine Spotlight library. It utilizes a centralized state store for page transitions and search result management.
Component Hierarchy
The UI is divided into several specialized views:
- CommandPaletteRoot: The base container handling search input, query changes, and global keyboard events.
- MainPage: The entry view showing initial search results, suggested resources, and application navigation links.
- ResourceRolesPage: A filtered view displaying specific connections/roles associated with a selected resource.
- ConnectionActionsPage: A context-specific menu for performing actions on a specific connection (e.g., opening a terminal or copying CLI commands).
Sources: webapp_v2/src/features/CommandPalette/index.jsx:21-25, webapp_v2/src/features/CommandPalette/index.jsx:106-135
Data Flow and Search Logic
The palette uses a debounced search mechanism to minimize API load. When a user types a query of at least two characters, the system triggers an asynchronous search request to the backend.
The search lifecycle is managed via the useCommandPaletteStore, which tracks searchStatus (idle, searching, ready, error) and the searchResults object containing connections and runbooks.
Sources: webapp_v2/src/features/CommandPalette/index.jsx:27-41, webapp_v2/COMPONENTS.md:522-527
State Management
The palette's state is persisted in useCommandPaletteStore, a Zustand store. This store is responsible for maintaining the navigation stack within the palette.
Navigation States
| Page | Purpose |
|---|---|
main | Default search view for connections, runbooks, and routes. |
resource-roles | Displays list of roles for a selected resource. |
connection-actions | Actions for a specific connection (Terminal, CLI, Native, etc). |
Sources: webapp_v2/src/features/CommandPalette/index.jsx:49-65, webapp_v2/src/features/CommandPalette/index.jsx:116-133
Integration with Legacy System
For actions involving native clients or legacy flows, the Command Palette uses a dispatch bridge. When a user selects "Native Client" from the actions page, the system calls clojureDispatch to trigger the native-client-access->start-flow event in the ClojureScript bundle.
Sources: webapp_v2/src/features/CommandPalette/index.jsx:17, webapp_v2/src/features/CommandPalette/index.jsx:82-84
Action Execution Flow
When a user selects a connection, they are presented with several action types. The handleConnectionAction function handles navigation or side-effects based on the chosen action.
Connection Action Types
| Action Type | Implementation | Target Route/Side Effect |
|---|---|---|
WEB_TERMINAL | React Router Navigation | /client?role={name} |
HOOP_CLI | Clipboard API | Copies hoop connect {name} to clipboard |
NATIVE_CLIENT | clojureDispatch | Triggers CLJS start-flow |
TEST | React Router Navigation | /connections/{name}/test |
CONFIGURE | React Router Navigation | /roles/{name}/configure |
Sources: webapp_v2/src/features/CommandPalette/index.jsx:71-98
The sequence above illustrates the transition from a search result to executing a specific connection action, resulting in the closing of the palette and navigation to the terminal.
Sources: webapp_v2/src/features/CommandPalette/index.jsx:71-76, webapp_v2/src/features/CommandPalette/spotlight.js
Styling and UX
The palette's visual appearance is defined by cmdk.css, which provides smooth transitions and accessibility indicators.
- Keyboard Interaction: Users can use
Backspaceto navigate back to the previous palette page if the search query is empty. - Selection Feedback: Items use
aria-selected="true"for highlighting, with background colors transitioning betweenvar(--gray-3)andvar(--gray-4). - Animations: Search results utilize a
fadeInanimation with a vertical translate effect to provide visual feedback when groups appear.
Sources: webapp/src/css/cmdk.css:1-49, webapp_v2/src/features/CommandPalette/index.jsx:43-48
Summary
The Command Palette is a high-performance React component integrated into the Hoop shell. It provides a centralized search interface for resources (Connections and Runbooks) and application-wide navigation. By utilizing debounced searching, a multi-page internal state, and a bridge to legacy ClojureScript actions, it ensures a fast, keyboard-driven user experience that maintains feature parity while the project undergoes its React migration.
Sources: webapp_v2/CONTEXT_MIGRATION.md:126-129, webapp_v2/src/features/CommandPalette/index.jsx:106-135