⌨️ Epic: Keyboard Navigation & Shortcuts

Goal

Implement comprehensive keyboard shortcuts and navigation for power users, enabling fast, mouse-free interaction with the Admin UI. Include a discoverable help system and customizable bindings.

Why Now?

1. Power User Productivity: Keyboard shortcuts significantly speed up repetitive tasks
2. Accessibility Requirement: Keyboard navigation is essential for users who cannot use a mouse
3. Developer Expectation: Developers expect keyboard shortcuts in admin tools (like IDE patterns)
4. Competitive Feature: Modern admin UIs (Vercel, Linear, GitHub) all have keyboard shortcuts

📖 User Stories

📋 Implementation Tasks

Phase 1: Infrastructure

• Add keyboard shortcut library (hotkeys-js or tinykeys, both MIT)
• Create shortcut registry with categories
• Implement context-aware shortcuts (disable in inputs)
• Add shortcut help modal component

Phase 2: Global Navigation

• Implement g + key navigation shortcuts
• Add tab switching shortcuts
• Implement command palette trigger (Ctrl+K)
• Add help panel trigger (?)

Phase 3: Table Navigation

• Add row selection state management
• Implement j/k or arrow navigation
• Add Enter to open, e to edit, d to delete
• Implement multi-select with Space and Ctrl+A
• Visual indicator for selected row

Phase 4: Modal & Form Shortcuts

• Implement Escape to close modals
• Add Ctrl+Enter to submit forms
• Ensure focus trapping in modals
• Return focus on modal close

Phase 5: Documentation & Polish

• Create keyboard shortcuts help content
• Add tooltips showing shortcuts on buttons
• Document shortcuts in user guide
• Add visual hints (e.g., "Press ? for shortcuts")

⚙️ Configuration

// Shortcut registry structure
const shortcuts = {
  global: {
    '?': { action: 'showHelp', description: 'Show keyboard shortcuts' },
    'ctrl+k': { action: 'openCommandPalette', description: 'Open search' },
    'escape': { action: 'closeModal', description: 'Close modal/clear' },
  },
  navigation: {
    'g s': { action: 'goToServers', description: 'Go to Servers' },
    'g t': { action: 'goToTools', description: 'Go to Tools' },
    // ...
  },
  table: {
    'j': { action: 'nextRow', description: 'Next row' },
    'k': { action: 'prevRow', description: 'Previous row' },
    'enter': { action: 'openItem', description: 'Open selected' },
    // ...
  }
};

✅ Success Criteria

• All primary navigation achievable via keyboard
• Table navigation works with j/k or arrows
• Help panel shows all available shortcuts
• Shortcuts don't interfere with form input
• Shortcuts documented in user guide

📚 References

• hotkeys-js (MIT)
• tinykeys (MIT)
• GitHub Keyboard Shortcuts
• Linear Keyboard Shortcuts