Keyboard Navigation and Shortcuts

[olucasandrade]

Task: Keyboard Navigation and Shortcuts

Description

Implement comprehensive keyboard navigation using react-hotkeys-hook. Every UI action should be accessible via keyboard with visible focus indicators. Include a shortcut cheat sheet (Cmd/Ctrl + ?) for discoverability.

Acceptance Criteria

• react-hotkeys-hook library installed
• Global keyboard shortcut provider created
• All UI actions accessible via keyboard shortcuts
• Visible focus indicators on all interactive elements
• Tab order follows logical flow
• Escape key closes modals/dialogs
• Keyboard shortcut cheat sheet modal (Cmd/Ctrl + ?)
• Focus trap implemented for modals
• Custom shortcuts configurable (store in localStorage)
• i18n support for shortcut labels (en/pt)

Technical Details

Implementation Approach

1. Install react-hotkeys-hook package
2. Create src/contexts/KeyboardShortcutContext.tsx:
   • Define default shortcuts
   • Provide hook to register/use shortcuts
   • Handle shortcut conflicts
3. Create src/components/KeyboardShortcutModal.tsx:
   • Display all available shortcuts
   • Categorized by feature area
   • Search/filter functionality
4. Define keyboard shortcuts:
   • Cmd/Ctrl + K: Focus request URL
   • Cmd/Ctrl + Enter: Send request
   • Cmd/Ctrl + H: Toggle history panel
   • Cmd/Ctrl + S: Save request
   • Cmd/Ctrl + T: Toggle terminal mode
   • Cmd/Ctrl + ,: Open settings
   • Cmd/Ctrl + ?: Show shortcuts cheat sheet
   • Escape: Close modals
5. Implement focus management utilities
6. Add visible focus styles to globals.css

Key Considerations

• Audit existing shortcuts to avoid conflicts
• Use modifier keys (Cmd/Ctrl) to avoid typing interference
• Test on both Mac (Cmd) and Windows/Linux (Ctrl)
• Focus indicators should be theme-aware
• Prevent shortcuts when typing in inputs
• Screen reader announcements for shortcut actions

Files Affected

• package.json (add react-hotkeys-hook)
• src/contexts/KeyboardShortcutContext.tsx (new)
• src/components/KeyboardShortcutModal.tsx (new)
• src/app/globals.css (add focus styles)
• src/app/components/RequestPanel.tsx (add shortcuts)
• src/app/components/ResponsePanel.tsx (add shortcuts)
• src/app/[locale]/layout.tsx (wrap with KeyboardShortcutProvider)
• messages/en.json (add shortcut labels)
• messages/pt.json (add shortcut labels)

Dependencies

• Task 001 (Theme System) - focus indicators need theme colors
• react-hotkeys-hook package installation
• Shortcut documentation content (en/pt)

Effort Estimate

• Size: M (Medium)
• Hours: 10-14 hours
• Parallel: true (can run parallel with Task 002)

Definition of Done

• Code implemented with all shortcuts working
• Shortcut cheat sheet modal functional
• All components keyboard accessible
• Focus indicators visible and theme-aware
• Tests written for keyboard interactions
• Accessibility audit passed (keyboard-only navigation)
• Documentation updated with keyboard shortcuts
• Code reviewed
• Merged to main branch