Keyboard Shortcuts
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Keyboard-based interactions for accelerated access to operations Domain: KEYBOARD
Statement
The system shall provide keyboard shortcuts that allow users to trigger common operations without mouse interaction.
Shortcuts are categorized as global (available throughout the application) or context-specific (available only where the corresponding action exists). The system prevents shortcuts from interfering with normal text input and ensures only one modal or widget is active at a time.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Global Shortcut | A keyboard shortcut available throughout the application regardless of current screen |
| Context-Specific Shortcut | A keyboard shortcut available only on screens where the corresponding action exists |
| Modal | A UI element that captures focus and requires dismissal before other interactions |
| Widget | An interactive panel or overlay that provides additional functionality |
Functional Requirements
Shortcut Execution (REQ-KEYBOARD-001)
FR-KEYBOARD-001 Execute Actions via Keyboard Shortcuts
The system shall allow users to trigger common operations using designated keyboard keys as an alternative to mouse-based interactions.
Acceptance Criteria:
Shortcut Availability:
- The system shall accept keyboard input to trigger bound actions
- Global shortcuts shall function on all screens
- Context-specific shortcuts shall function only where the corresponding action is available
- The system shall indicate available shortcuts for discoverable actions
Shortcut Categories:
- The system shall provide global shortcuts for dismiss modal, export/download, and print operations
- The system shall provide context-specific shortcuts for edit, manage results, reanalyze, and run information operations
Input Conflict Prevention:
- Shortcuts shall not trigger when text input has focus
- If text editing conflict cannot be resolved through focus detection, the system shall require a modifier key (e.g., Ctrl+key) to trigger the shortcut
Execution Constraints:
- Only one modal or widget shall be active at a time
- Each shortcut shall activate exactly once per discrete key press
Error Handling:
- Shortcut pressed but action unavailable: The system shall ignore the key press with no error
- Shortcut pressed during text editing: The system shall pass the key to the text input without triggering the shortcut
- Shortcut pressed while modal is open: The system shall not open additional modals (except Esc to close)
Trace: Source: 3.0.0-Keyboard shortcuts (Rows 1-11) | Jira: BT-2259 | Epic: BT-2387 | Tests: BT-2482, BT-2490, BT-2491
Modal Dismissal (REQ-KEYBOARD-002)
FR-KEYBOARD-002 Dismiss Active Modal or Widget
The system shall close the active modal or widget when the user presses the designated dismiss key.
Acceptance Criteria:
Dismiss Behavior:
- The dismiss shortcut shall close any modal that has a close control
- The dismiss shortcut shall function regardless of modal content
- The dismiss shortcut shall apply to modals and widgets that have a close control (X button)
Focus Management:
- The system shall return focus to the underlying screen after dismissal
Trace: Source: 3.0.0-Keyboard shortcuts (Row 3) | Jira: BT-2259 | Tests: [Pending]
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
shortcut_dismiss | Esc | Key binding for dismissing modals/widgets | REQ-KEYBOARD-002 |
shortcut_export | x | Key binding for export/download action | REQ-KEYBOARD-001 |
shortcut_print | p | Key binding for print action | REQ-KEYBOARD-001 |
shortcut_edit | e | Key binding for edit action | REQ-KEYBOARD-001 |
shortcut_manage_results | m | Key binding for manage results action | REQ-KEYBOARD-001 |
shortcut_reanalyze | r | Key binding for reanalyze action | REQ-KEYBOARD-001 |
shortcut_run_info | i | Key binding for run information action | REQ-KEYBOARD-001 |
Assumptions
- Users have a keyboard capable of sending standard key events
- The application has focus when shortcuts are invoked
- Toolbar actions bound to shortcuts exist on at least one screen
UI Notes (Illustrative)
FR-KEYBOARD-001 UI Specifications
Shortcut Key Mappings:
| Key | Action | Context |
|---|---|---|
| Esc | Close windows | Global - closes modals/widgets with close control |
| x | Export/Download | Anywhere export is available |
| p | Anywhere print is available | |
| e | Edit | Screens with Edit functionality |
| m | Manage Results | Screens with Manage Results functionality |
| r | ReAnalyse | Screens with ReAnalyse functionality |
| i | Run Information | Run Report screen only |
Discoverability:
- Icons with available shortcuts display a tooltip showing the shortcut key on hover
- Icon background changes to grey on hover to indicate shortcut availability
- Shortcuts are bound to toolbar buttons (enables inheritance when buttons are reused across screens)
Visual Reference:
- Tooltip with shortcut key example:
media/image183.png
FR-KEYBOARD-002 UI Specifications
- Esc key used industry-wide for modal dismissal
- No visual indicator needed (user expectation)
Implementation (Illustrative)
This domain is implemented entirely in the Vue.js frontend. The backend provides the SPA entry point only.
| Component | Type | Path | Requirements |
|---|---|---|---|
| SpaController | Controller | code/app/Http/Controllers/SpaController.php | REQ-KEYBOARD-001, REQ-KEYBOARD-002 |
Architecture Notes:
- Keyboard shortcuts are implemented entirely in Vue.js frontend components
- Key event handling is bound to toolbar buttons for reusability across screens
- Text input focus detection prevents shortcuts from interfering with user input
- Modal/widget management enforces single-active constraint in frontend state
- No backend API endpoints required for keyboard shortcut functionality
- The
SpaControllerserves the frontend application containing all shortcut logic
Frontend Components:
| Component Type | Location |
|---|---|
| Views | views/RunView.vue, views/LjReport.vue, views/TrendsReport.vue, views/KitConfigurations.vue (v-hotkey usage) |
| Components | Cross-cutting v-hotkey directive usage |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-KEYBOARD-001 | Execute Actions via Keyboard Shortcuts | Test | SpaController (frontend JS) | BT-2482, BT-2490, BT-2491 | Draft |
| REQ-KEYBOARD-002 | Dismiss Active Modal or Widget | Test | SpaController (frontend JS) | [Pending] | Draft |
Notes
- Export shortcut applies to both "Export" and "Download Data" labeled actions
- Shortcuts follow single-letter convention without modifier keys for efficiency
- Modifier key (Ctrl) may be needed as fallback if text editing conflict cannot be resolved through focus detection
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| - | No open questions | - | - | - |
Acceptance Tests
Test: REQ-KEYBOARD-001
Test: Verify export shortcut
Given: User is on a screen with Export or Download Data available
When: User presses the export shortcut key
Then: The export operation is triggered
Test: Verify print shortcut
Given: User is on a screen with Print available
When: User presses the print shortcut key
Then: The print operation is triggered
Test: Verify edit shortcut
Given: User is on a screen with Edit functionality
When: User presses the edit shortcut key
Then: The edit function is triggered
Test: Verify manage results shortcut
Given: User is on a screen with Manage Results functionality
When: User presses the manage results shortcut key
Then: The Manage Results function is triggered
Test: Verify reanalyse shortcut
Given: User is on a screen with ReAnalyse functionality
When: User presses the reanalyse shortcut key
Then: The ReAnalyse function is triggered
Test: Verify run information shortcut
Given: User is on the Run Report screen
When: User presses the run information shortcut key
Then: The Run Information panel opens
Test: Verify shortcut discoverability (BT-2482)
Given: User is on a screen with icons that have keyboard shortcuts
When: User indicates focus on an icon with a shortcut
Then: The system shall display the available shortcut key
Test: Verify shortcuts disabled during text editing
Given: User is in a text input field
When: User presses a shortcut key
Then: The character is entered in the text field
And: The shortcut action is NOT triggered
Test: Verify single widget limit (BT-2491)
Given: User has a widget or modal open
When: User presses a shortcut key that would open another widget
Then: No new widget opens
And: The existing widget remains open
Test: Verify single action per key press (BT-2490)
Given: User is on a screen with shortcut functionality
When: User presses and holds a shortcut key
Then: The action is performed exactly once
And: The action does NOT repeat while the key is held
Test: REQ-KEYBOARD-002
Test: Verify dismiss key closes modals
Given: User has a modal or widget open with a close control
When: User presses the dismiss shortcut key
Then: The modal or widget closes
And: Focus returns to the underlying screen
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Architecture | SPA Entry Point, Frontend Architecture |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
Requirement Split: REQ-KEYBOARD-001 and REQ-KEYBOARD-002
The source document contained a single requirement (REQ-KEYBOARD-001) that described both shortcut execution and modal dismissal. These were separated into two requirements:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-KEYBOARD-001 (all shortcuts) | 3.0.0-Keyboard shortcuts Rows 1-11 | Split into REQ-KEYBOARD-001 and REQ-KEYBOARD-002 |
| Esc key behavior | 3.0.0-Keyboard shortcuts Row 3 | Promoted to REQ-KEYBOARD-002 |
Rationale: Modal dismissal is a distinct capability from action shortcuts. Separating them improves testability and allows independent evolution (e.g., dismiss shortcut could change without affecting action shortcuts).
Reversibility: To restore original structure, reference:
- Source:
output/pilot/restructured/keyboard.md - Confluence: 3.0.0-Keyboard shortcuts (Rows 1-11)
AC Transformations
The following UI-centric acceptance criteria were transformed to behavior-centric:
| Original (UI-Centric) | Transformed (Behavior-Centric) |
|---|---|
| "Pressing the x key triggers the Export operation" | "The system shall accept keyboard input to trigger bound actions" |
| "Icons display a tooltip showing the shortcut key when user hovers" | "The system shall indicate available shortcuts for discoverable actions" |
| "Only one widget or modal can be open at a time" | "Only one modal or widget shall be active at a time" |
Configuration Extraction
Shortcut key bindings were extracted to Configuration Options. The specific key assignments (Esc, x, p, e, m, r, i) are deployment-configurable parameters, not normative requirements.
Refinements Folded into Acceptance Criteria
The following refinements were folded into acceptance criteria:
| Original Refinement | Folded Into |
|---|---|
| RF-01 (REQ-KEYBOARD-001): Global shortcuts: dismiss modal, export/download, print | AC under Shortcut Categories |
| RF-02 (REQ-KEYBOARD-001): Context-specific shortcuts: edit, manage results, reanalyze, run information | AC under Shortcut Categories |
| RF-03 (REQ-KEYBOARD-001): Text editing detection | AC under Input Conflict Prevention |
| RF-04 (REQ-KEYBOARD-001): Modifier key fallback | AC under Input Conflict Prevention |
| RF-05 (REQ-KEYBOARD-001): Key press detection | AC under Execution Constraints |
| RF-01 (REQ-KEYBOARD-002): Dismiss applies to modals/widgets with close control | AC under Dismiss Behavior |