Centralized Keyboard Shortcuts

Overview#

The Centralized Keyboard Shortcuts module provides a unified system for registering, resolving, and managing keyboard shortcuts across all platform applications. A single provider manages shortcut registrations from the shell, application, and page levels, resolving conflicts through a four-tier priority system and supporting both combination shortcuts (such as Ctrl+K) and sequence shortcuts (such as pressing G then D). The system replaces per-application shortcut handling with a coordinated architecture that prevents double-handling, supports dynamic registration and cleanup, and provides a built-in help modal showing all available shortcuts.

Key Features#

• Priority-Based Resolution - Four priority tiers determine which shortcut handler wins when multiple registrations match the same key combination: shell (100), application (200), page (300), and override (400). Higher priority registrations take precedence, enabling page-specific shortcuts to override global navigation and modal-level shortcuts to override everything.

• Combination and Sequence Shortcuts - Support for standard key combinations (Ctrl+K, Ctrl+Shift+P, Shift+?) alongside key sequences where pressing one key followed by another triggers an action (G then D for go to dashboard, G then M for go to map). Sequence detection resets automatically after a configurable timeout.

• Scope System - Shortcuts are registered with one of three scopes: shell (platform-wide navigation and commands), app (application-level actions within a specific module), and page (context-specific actions on the current view). The scope determines where the shortcut appears in the help modal and how it interacts with other registrations.

• Editable Target Detection - The system automatically suppresses shortcut handling when the user is typing in form fields, text areas, content-editable elements, or other input contexts. This prevents shortcuts from firing during data entry without requiring per-registration configuration.

• Help Modal - A built-in keyboard shortcut reference modal (activated with Shift+?) displays all registered shortcuts grouped by category, with human-readable key labels and descriptions. The modal deduplicates entries by identifier and filters appropriately by scope.

• Command Palette Integration - The shortcut system integrates with the command palette, providing keyboard access to the palette via Ctrl+K and Ctrl+Shift+P at the shell level, and generating palette shortcut entries from registered shortcuts for searchable access.

• Dynamic Registration and Cleanup - Shortcuts are registered and unregistered as components mount and unmount, preventing stale handlers from persisting after navigation. Each registration returns a cleanup function that is called automatically on component teardown.

Use Cases#

• Platform Navigation - Navigate between major platform sections using key sequences (G+D for dashboard, G+M for map, G+I for investigations, G+A for admin, G+G for graph) without reaching for the mouse.
• Application-Specific Actions - Each application module registers its own shortcuts for common actions (creating entities, toggling panels, applying filters) at the appropriate priority level, ensuring they work within that module without conflicting with shell-level navigation.
• War Room and Collaboration - Override-priority shortcuts in the collaboration war room provide instant access to call controls (mute, camera, screen share, recording, hand raise, leave call) that take precedence over all other shortcut registrations.
• Surveillance Navigation - Sequence shortcuts in the surveillance module enable rapid camera switching, view toggling, and alert acknowledgment through keyboard-only workflows.
• Discoverability - New users press Shift+? to see all available shortcuts for their current context, reducing the learning curve and promoting keyboard-driven efficiency.

Integration#

The keyboard shortcuts system is provided by the application shell and is available to all platform modules. Individual applications register shortcuts through React hooks that manage lifecycle cleanup automatically. The system connects to the command palette for searchable shortcut access and to the global navigation for platform-wide key sequences.

Last Reviewed: 2026-04-02