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 utility interface that allows users to perform site-wide actions through a keyboard-driven dialog. It provides quick access to page navigation, theme customization, sound settings, and a "Secrets" view for tracking discovered easter eggs.
Sources: src/components/CommandPalette/command-palette.ts:40-62, src/components/CommandPalette/utils.ts:32-72
Architecture and Components
The system utilizes a vanilla TypeScript implementation wrapped around a native HTML <dialog> element. It manages state for the active view (Main or Secrets), item filtering, and keyboard navigation.
Core Structure
The Palette is defined by a Palette type which tracks DOM elements and internal state:
| Component | Description |
|---|---|
dialog | The native HTMLDialogElement container. |
input | The search field providing the combobox interface. |
navItems | An array of navigation targets parsed from the DOM. |
state | Internal object tracking activeIndex, page context, and arrowOverride. |
trigger | The button element that opens the palette. |
Sources: src/components/CommandPalette/command-palette.ts:40-62, e2e/components/command-palette.ts:11-25
Interaction Flow
The following diagram illustrates the lifecycle of the palette from initialization to command execution.
Command Processing Logic
The palette processes text input to match different categories of actions. It prioritizes navigation items before checking for system settings.
Command Categories
Commands are identified via the getHighlightedCommand function using the following priority:
- Navigation: Matches names of site pages (e.g., "Resume").
- Theme Color: Matches defined theme labels (e.g., "Blue").
- Theme Mode: Matches appearance modes (e.g., "Dark").
- Sound: Matches sound preference keywords (e.g., "Sound").
Sources: src/components/CommandPalette/utils.ts:42-72, src/components/CommandPalette/utils.test.ts:70-108
Execution Logic
Once a command is highlighted, the applyHighlightedCommand function executes specific actions:
export function applyHighlightedCommand(
actions: ApplyHighlightedCommandActions,
command: HighlightedCommand | undefined,
): void {
if (!command) return;
if (command.type === 'nav') {
actions.close();
actions.navigate(command.href);
return;
}
// ... handles color, mode, and sound
}
Sources: src/components/CommandPalette/utils.ts:74-102
Secrets and Easter Eggs
The palette includes a specialized "Secrets" view accessed via a specific keyboard shortcut (⌘. or Ctrl+.). This view displays a list of found easter eggs and tracks progress.
Secrets State Management
- Progress Tracking: Uses
getFoundEasterEggIdsto filter visible eggs. - Labels: Generates dynamic labels like "Secrets 1/3" or "All secrets found".
- Navigation: The "Back" action returns the user to the main palette view.
Sources: src/components/CommandPalette/command-palette.ts:88-125, src/components/CommandPalette/utils.ts:118-144
Sequence: Opening Secrets
Accessibility and Navigation
The palette implements ARIA patterns for a combobox with aria-activedescendant to support screen readers.
Keyboard Controls
| Key | Action |
|---|---|
ArrowDown / ArrowUp | Moves highlight and updates aria-activedescendant. |
Enter | Selects the active item or applies the highlighted command. |
Escape | Closes the dialog or returns from the Secrets view. |
Backspace (empty) | Returns to the main view if currently in Secrets. |
Sources: src/components/CommandPalette/command-palette.ts:413-460, src/components/CommandPalette/utils.ts:146-148, e2e/specs/command-palette.spec.ts:37-52
Technical Implementation
The system utilizes ResizeObserver to measure the listSizer element, ensuring the container height matches the dynamic content exactly by setting the --palette-list-height CSS variable.
Sources: src/components/CommandPalette/command-palette.ts:241-247, src/components/CommandPalette/command-palette.ts:518-528
Summary
The Command Palette serves as a high-efficiency interface for both navigation and site configuration. By combining a native <dialog> with complex filtering logic and ARIA support, it provides a performant and accessible tool for power users while managing secondary features like the easter egg collection system.