Command Palette

Phase: MVP (Phase 1) Depends On: Page System

---

Overview

The Command Palette is a keyboard-driven interface for search, navigation, and actions. It serves as the primary discovery mechanism and entry point for AI assistance.

Overview Diagram

Key Design Decisions

1. Global Shortcut

• macOS: Cmd+K
• Windows/Linux: Ctrl+K

This follows conventions from VS Code, Linear, Notion, and other modern apps.

2. Unified Search

Single input searches across:

• Page titles (fuzzy match)
• Quick actions (create, settings, etc.)
• Recent items

3. Keyboard-First

Full keyboard navigation:

• ↑/↓ or Tab/Shift+Tab: Navigate results
• Enter: Select item
• Escape: Close palette
• Type to filter

4. Categorized Results

Results grouped by type:

┌─────────────────────────────────────┐
│ 🔍 Search...                        │
├─────────────────────────────────────┤
│ Recent                              │
│   📄 Character: Elena               │
│   📄 World Overview                 │
├─────────────────────────────────────┤
│ Pages                               │
│   📄 Characters                     │
│   📄 Locations                      │
├─────────────────────────────────────┤
│ Actions                             │
│   ➕ Create new page                │
│   ⚙️ Open settings                  │
│   🤖 Ask AI...                      │
└─────────────────────────────────────┘

UX Design

Visual Design

• Modal overlay with backdrop blur
• Centered, ~500px wide
• Appears with subtle animation
• Auto-focuses search input

Search Behavior

• Fuzzy matching (typo-tolerant)
• Results update as user types (debounced)
• Empty state shows recent + suggestions
• No results state with helpful message

Performance

• Opens in under 100ms
• Search results in under 50ms
• Index pages in memory for speed

Use Cases

Use Case	Description
SearchPagesUseCase	Fuzzy search page titles
GetRecentPagesUseCase	Get recently opened pages
ExecuteActionUseCase	Run quick action

API Surface

Tauri Commands

// Search pages by query
search_pages(query: string): Promise<SearchResult[]>

// Get recent pages
get_recent_pages(limit?: number): Promise<Page[]>

TypeScript Types

interface SearchResult {
  type: 'page' | 'action';
  id: string;
  title: string;
  subtitle?: string;
  icon?: string;
  score: number; // Relevance score for sorting
}

interface QuickAction {
  id: string;
  title: string;
  shortcut?: string;
  icon: string;
  handler: () => void;
}

Quick Actions (MVP)

Action	Shortcut	Description
Create page	Cmd+N	Open create page dialog
Open settings	Cmd+,	Open settings panel
Toggle sidebar	Cmd+B	Show/hide sidebar

Component Structure

CommandPalette/
├── CommandPalette.tsx      # Main component
├── CommandInput.tsx        # Search input with keyboard handling
├── ResultsList.tsx         # Virtualized results list
├── ResultItem.tsx          # Individual result row
├── useCommandPalette.ts    # State and search logic
└── actions.ts              # Quick action definitions

Keyboard Handling

// Global listener
useEffect(() => {
  const handler = (e: KeyboardEvent) => {
    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
      e.preventDefault();
      togglePalette();
    }
  };
  window.addEventListener('keydown', handler);
  return () => window.removeEventListener('keydown', handler);
}, []);

Testing Strategy

• Unit: Search algorithm, result ranking
• Component: Keyboard navigation, result display
• E2E: Open palette → search → navigate → select

---

Depends on Page System. Required by First Launch Experience.