From 3e0b1e55c7cca0419cbcc39e4811b743981031bb Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 12 Nov 2026 14:41:20 +0000 Subject: [PATCH] Add global keyboard shortcuts cheatsheet Expose the existing shortcut help as a global Ctrl+?/Cmd+? cheatsheet while preserving Ctrl+/ search behavior. Register the current shortcuts and cover composer, terminal, layout, and close interactions with focused tests. --- .../settings/keyboard_shortcuts_help.dart | 102 +++++++- .../settings/keyboard_shortcuts_registry.dart | 240 +++++++++++++++--- app/lib/shell/adaptive_shell.dart | 21 ++ app/lib/shell/shell_cheatsheet.dart | 35 +++ app/lib/shell/shell_cheatsheet_shortcut.dart | 31 +++ app/notes/ctrl-question-cheatsheet.md | 57 +++++ .../keyboard_shortcuts_cheatsheet_test.dart | 176 +++++++++++++ .../shell/shell_cheatsheet_shortcut_test.dart | 168 ++++++++++++ app/test/shell/shell_cheatsheet_test.dart | 222 ++++++++++++++++ 9 files changed, 1002 insertions(+), 50 deletions(-) create mode 100644 app/lib/shell/shell_cheatsheet.dart create mode 100644 app/lib/shell/shell_cheatsheet_shortcut.dart create mode 100644 app/notes/ctrl-question-cheatsheet.md create mode 100644 app/test/features/settings/keyboard_shortcuts_cheatsheet_test.dart create mode 100644 app/test/shell/shell_cheatsheet_shortcut_test.dart create mode 100644 app/test/shell/shell_cheatsheet_test.dart diff --git a/app/lib/features/settings/keyboard_shortcuts_help.dart b/app/lib/features/settings/keyboard_shortcuts_help.dart index 11732b1e..d2b82138 100644 --- a/app/lib/features/settings/keyboard_shortcuts_help.dart +++ b/app/lib/features/settings/keyboard_shortcuts_help.dart @@ -5,6 +5,10 @@ import 'keyboard_shortcuts_registry.dart'; const keyboardShortcutsLabel = 'Keyboard shortcuts'; +/// The narrowest content width (after the page padding) that shows the groups +/// in two columns. Narrower content, such as a phone sheet, stacks them. +const _twoColumnMinWidth = 520.0; + Future showKeyboardShortcutsHelp(BuildContext context) => showAppDetails( context, @@ -19,7 +23,12 @@ class KeyboardShortcutsHelp extends StatelessWidget { @override Widget build(BuildContext context) { - final entries = (registry ?? KeyboardShortcutRegistry.current()).entries; + final source = registry ?? KeyboardShortcutRegistry.current(); + final groups = [ + for (final group in KeyboardShortcutGroup.values) + if (source.inGroup(group) case final entries when entries.isNotEmpty) + (group: group, entries: entries), + ]; final content = Semantics( scopesRoute: true, namesRoute: true, @@ -52,13 +61,7 @@ class KeyboardShortcutsHelp extends StatelessWidget { style: Theme.of(context).textTheme.bodyMedium, ), const SizedBox(height: 16), - for (final (index, entry) in entries.indexed) ...[ - if (index > 0) const Divider(height: 1), - Padding( - padding: const EdgeInsets.symmetric(vertical: 12), - child: _ShortcutRow(entry: entry), - ), - ], + _ShortcutGroups(groups: groups), const SizedBox(height: 4), Text( 'On macOS, Option is shown for Alt. Browsers can reserve system or tab shortcuts.', @@ -77,6 +80,89 @@ class KeyboardShortcutsHelp extends StatelessWidget { } } +typedef _Group = ({ + KeyboardShortcutGroup group, + List entries, +}); + +/// The groups in display order: one column when narrow, otherwise two. Each +/// group goes to the shorter column so the two stay about the same height. +class _ShortcutGroups extends StatelessWidget { + const _ShortcutGroups({required this.groups}); + + final List<_Group> groups; + + @override + Widget build(BuildContext context) => LayoutBuilder( + builder: (context, constraints) { + if (constraints.maxWidth < _twoColumnMinWidth) { + return Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [for (final group in groups) _GroupBlock(group: group)], + ); + } + final left = <_Group>[]; + final right = <_Group>[]; + var leftRows = 0; + var rightRows = 0; + for (final group in groups) { + if (leftRows <= rightRows) { + left.add(group); + leftRows += group.entries.length + 1; + } else { + right.add(group); + rightRows += group.entries.length + 1; + } + } + return Row( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Expanded(child: _GroupColumn(groups: left)), + const SizedBox(width: 24), + Expanded(child: _GroupColumn(groups: right)), + ], + ); + }, + ); +} + +class _GroupColumn extends StatelessWidget { + const _GroupColumn({required this.groups}); + + final List<_Group> groups; + + @override + Widget build(BuildContext context) => Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [for (final group in groups) _GroupBlock(group: group)], + ); +} + +class _GroupBlock extends StatelessWidget { + const _GroupBlock({required this.group}); + + final _Group group; + + @override + Widget build(BuildContext context) => Padding( + padding: const EdgeInsets.only(bottom: 12), + child: Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Text(group.group.title, style: Theme.of(context).textTheme.titleSmall), + const SizedBox(height: 4), + for (final (index, entry) in group.entries.indexed) ...[ + if (index > 0) const Divider(height: 1), + Padding( + padding: const EdgeInsets.symmetric(vertical: 10), + child: _ShortcutRow(entry: entry), + ), + ], + ], + ), + ); +} + class _ShortcutRow extends StatelessWidget { const _ShortcutRow({required this.entry}); diff --git a/app/lib/features/settings/keyboard_shortcuts_registry.dart b/app/lib/features/settings/keyboard_shortcuts_registry.dart index 85f3d2f0..ccb52f9e 100644 --- a/app/lib/features/settings/keyboard_shortcuts_registry.dart +++ b/app/lib/features/settings/keyboard_shortcuts_registry.dart @@ -5,18 +5,34 @@ import '../chat/workspace/chat_float_shortcut.dart'; import '../terminal/terminal_shortcuts.dart'; import '../../shell/windows/window_shortcuts.dart'; import '../../shell/shell_chat_shortcut.dart'; +import '../../shell/shell_cheatsheet_shortcut.dart'; import '../../shell/shell_runs_pipelines_shortcut.dart'; import '../../shell/shell_search_shortcut_labels.dart'; +/// The headings the help page groups its shortcuts under, in display order. +enum KeyboardShortcutGroup { + navigation('Navigation'), + chat('Chat'), + windows('Windows'), + terminal('Terminal'), + lists('Lists'); + + const KeyboardShortcutGroup(this.title); + + final String title; +} + /// A shortcut entry shown in the in-app help. Keeping these entries together /// prevents the help page from inventing chords that the handlers do not use. class KeyboardShortcutEntry { const KeyboardShortcutEntry({ + required this.group, required this.action, required this.keys, this.caveat, }); + final KeyboardShortcutGroup group; final String action; final String keys; final String? caveat; @@ -36,8 +52,150 @@ class KeyboardShortcutRegistry { bool get _macOS => platform == TargetPlatform.macOS; + /// The entries of one [group], in the order they are listed. + List inGroup(KeyboardShortcutGroup group) => [ + for (final entry in entries) + if (entry.group == group) entry, + ]; + List get entries => [ + ..._navigation, + ..._chat, + ..._windows, + ..._terminal, + ..._lists, + ]; + + String get _cheatsheetKeys => shellCheatsheetShortcutLabel(platform); + + List get _navigation => [ KeyboardShortcutEntry( + group: KeyboardShortcutGroup.navigation, + action: 'Show keyboard shortcuts', + keys: _cheatsheetKeys, + caveat: + 'Press again or Esc to close. Ctrl+/ still opens Search. In the terminal the key goes to the terminal.', + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.navigation, + action: 'Open Search', + keys: shellSearchShortcutLabels(platform).join(', '), + caveat: web ? 'The browser may reserve some keyboard shortcuts.' : null, + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.navigation, + action: 'Leave Search', + keys: 'Esc', + caveat: + 'Focuses the search field first, then goes back to the previous page.', + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.navigation, + action: 'Open Chat', + keys: shellChatShortcutLabels(platform).join(', '), + caveat: web + ? 'Shows the open chat and focuses its message input. The browser may reserve Ctrl+K.' + : 'Shows the open chat and focuses its message input. In the terminal Ctrl+K stays kill-line; Alt+K still opens Chat.', + ), + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.navigation, + action: 'Switch between Runs and Pipelines', + keys: shellRunsPipelinesShortcutLabel, + caveat: + 'Goes to Runs from other destinations and to Pipelines from Runs. In a text field or the terminal Ctrl+A keeps its own meaning.', + ), + ]; + + List get _chat => [ + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Focus the active chat composer', + keys: '/', + caveat: 'Only outside text fields and other popup surfaces.', + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Send a chat message', + keys: _apple ? 'Cmd+Enter' : 'Ctrl+Enter', + ), + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Choose a slash command', + keys: 'Up, Down, Enter', + caveat: + 'While the slash command list is open above the composer. Esc dismisses it.', + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Toggle Center Stage', + keys: + '${chatCenterStageShortcutLabel(platform)}${_apple ? ', Cmd+E' : ', Ctrl+E'}', + ), + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Stop a running chat', + keys: 'Esc, Esc', + caveat: + 'Press Esc twice within one second while a turn runs; the first press shows a hint.', + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Focus the neighbouring chat pane', + keys: _apple ? 'Cmd+Shift+Arrows' : 'Ctrl+Shift+Arrows', + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Move the active chat pane', + keys: _apple ? 'Cmd+Option+Shift+Arrows' : 'Ctrl+Alt+Shift+Arrows', + ), + if (!web) + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Cycle chat panes and floating chats', + keys: 'Ctrl+Tab, Ctrl+Shift+Tab', + caveat: + 'While the terminal is shown, Ctrl+Tab moves between its tabs instead.', + ), + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Resize panes with a focused divider', + keys: 'Arrow keys', + caveat: 'While the divider between panes has keyboard focus.', + ), + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.chat, + action: 'Scroll a wide transcript block', + keys: 'Left, Right', + caveat: 'While the block has keyboard focus.', + ), + ]; + + List get _windows => [ + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.windows, + action: 'Show or hide floating chats', + keys: _apple + ? '${chatFloatShortcutLabel(platform)}, Ctrl+Y, Cmd+Y' + : '${chatFloatShortcutLabel(platform)}, Ctrl+Y', + caveat: + 'Brings a chat forward from Terminal and focuses its message input.', + ), + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.windows, + action: 'Cycle floating windows', + keys: _cycleKeys, + ), + ]; + + /// Alt+` (Option+` on macOS) and the same chord with Shift, backwards. + String get _cycleKeys { + final forward = windowCycleShortcutLabel(platform); + return '$forward, ${forward.replaceFirst('+', '+Shift+')}'; + } + + List get _terminal => [ + KeyboardShortcutEntry( + group: KeyboardShortcutGroup.terminal, action: 'Show or hide terminal', keys: TerminalShortcutLabels( web: web, @@ -47,61 +205,59 @@ class KeyboardShortcutRegistry { ? 'Browser tab shortcuts such as Cmd+T are not available to the app.' : null, ), + if (!web) + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.terminal, + action: 'Move between terminal tabs', + keys: 'Ctrl+Tab, Ctrl+Shift+Tab', + ), KeyboardShortcutEntry( - action: 'Show or hide floating chats', - keys: _apple - ? '${chatFloatShortcutLabel(platform)}, Ctrl+Y, Cmd+Y' - : '${chatFloatShortcutLabel(platform)}, Ctrl+Y', - caveat: - 'Brings a chat forward from Terminal and focuses its message input.', + group: KeyboardShortcutGroup.terminal, + action: 'Copy selected terminal text', + keys: TerminalShortcutLabels(web: web, platform: platform).copy, + caveat: _apple + ? null + : 'Ctrl+C copies only while text is selected; otherwise it reaches the process.', ), KeyboardShortcutEntry( - action: 'Open Chat', - keys: shellChatShortcutLabels(platform).join(', '), - caveat: web - ? 'Shows the open chat and focuses its message input. The browser may reserve Ctrl+K.' - : 'Shows the open chat and focuses its message input. In the terminal Ctrl+K stays kill-line; Alt+K still opens Chat.', + group: KeyboardShortcutGroup.terminal, + action: 'Paste into the terminal', + keys: _apple ? 'Cmd+V' : 'Ctrl+V, Ctrl+Shift+V', ), + if (_apple) + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.terminal, + action: 'Select all terminal text', + keys: 'Cmd+A', + ), const KeyboardShortcutEntry( - action: 'Switch between Runs and Pipelines', - keys: shellRunsPipelinesShortcutLabel, - caveat: - 'Goes to Runs from other destinations and to Pipelines from Runs. In a text field or the terminal Ctrl+A keeps its own meaning.', - ), - KeyboardShortcutEntry( - action: 'Toggle Center Stage', - keys: - '${chatCenterStageShortcutLabel(platform)}${_apple ? ', Cmd+E' : ', Ctrl+E'}', - ), - KeyboardShortcutEntry( - action: 'Open Search', - keys: shellSearchShortcutLabels(platform).join(', '), - caveat: web ? 'The browser may reserve some keyboard shortcuts.' : null, - ), - KeyboardShortcutEntry( - action: 'Cycle floating windows', - keys: - '${windowCycleShortcutLabel(platform)}, ${windowCycleShortcutLabel(platform)} with Shift', + group: KeyboardShortcutGroup.terminal, + action: 'Resize the terminal panel', + keys: 'Up, Down', + caveat: 'While the panel has keyboard focus.', ), + ]; + + List get _lists => [ KeyboardShortcutEntry( + group: KeyboardShortcutGroup.lists, action: 'Open a chat list item', keys: _macOS ? 'Cmd+1…9' : 'Ctrl+1…9', caveat: 'Available when the Chat list is mounted; numbers select its visible item.', ), - KeyboardShortcutEntry( - action: 'Focus the active chat composer', - keys: '/', - caveat: 'Only outside text fields and other popup surfaces.', + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.lists, + action: 'Resize a list pane', + keys: 'Left, Right', + caveat: 'While the divider beside a list has keyboard focus.', ), - KeyboardShortcutEntry( - action: 'Send a chat message', - keys: _apple ? 'Cmd+Enter' : 'Ctrl+Enter', + const KeyboardShortcutEntry( + group: KeyboardShortcutGroup.lists, + action: 'Previous or next artifact or changed file', + keys: 'Left, Right', + caveat: + 'In an artifact or file-diff viewer. Esc closes an artifact viewer.', ), - if (!web) - const KeyboardShortcutEntry( - action: 'Move between terminal tabs', - keys: 'Ctrl+Tab, Ctrl+Shift+Tab', - ), ]; } diff --git a/app/lib/shell/adaptive_shell.dart b/app/lib/shell/adaptive_shell.dart index 99b618f0..addbce22 100644 --- a/app/lib/shell/adaptive_shell.dart +++ b/app/lib/shell/adaptive_shell.dart @@ -13,6 +13,8 @@ import 'shell_rail_scope.dart'; import 'list_pane_widths.dart'; import 'shell_bar.dart'; import 'shell_chat_shortcut.dart'; +import 'shell_cheatsheet.dart'; +import 'shell_cheatsheet_shortcut.dart'; import 'shell_list_shortcuts.dart'; import 'shell_runs_pipelines_shortcut.dart'; import 'shell_search_shortcut_labels.dart'; @@ -92,6 +94,7 @@ class _AdaptiveShellState extends State { // page of its own for the system Back to close first. final Map _nestedCanPop = {}; final ShellBarRegistry _bar = ShellBarRegistry(); + final ShellCheatsheet _cheatsheet = ShellCheatsheet(); late final ListPaneWidths _paneWidths = ListPaneWidths( store: widget.listPaneWidthStore, ); @@ -390,6 +393,24 @@ class _AdaptiveShellState extends State { /// terminal their own Ctrl+A (select all, line start). bool _handleDestinationKeyEvent(KeyEvent event) { final keyboard = HardwareKeyboard.instance; + // Ctrl+? opens the shortcuts cheatsheet from anywhere, including a focused + // composer and floating windows; the terminal keeps the chord while it has + // the keyboard. Escape closes the cheatsheet while it is open. + if (shellCheatsheetShortcut(event, keyboard) && + !primaryFocusIsTypingSurface()) { + if (event is KeyDownEvent) _cheatsheet.toggle(context); + return true; + } + if (_cheatsheet.isOpen && + event is KeyDownEvent && + event.logicalKey == LogicalKeyboardKey.escape && + !keyboard.isControlPressed && + !keyboard.isMetaPressed && + !keyboard.isShiftPressed && + !keyboard.isAltPressed) { + _cheatsheet.close(context); + return true; + } // Ctrl+K is the terminal's kill-line while the terminal has the keyboard; // Alt+K still opens Chat there. if (shellChatShortcut(event, keyboard) && diff --git a/app/lib/shell/shell_cheatsheet.dart b/app/lib/shell/shell_cheatsheet.dart new file mode 100644 index 00000000..d9169ed3 --- /dev/null +++ b/app/lib/shell/shell_cheatsheet.dart @@ -0,0 +1,35 @@ +import 'package:flutter/widgets.dart'; + +import '../features/settings/keyboard_shortcuts_help.dart'; + +/// Opens and closes the keyboard shortcuts cheatsheet from the shell's global +/// key handler. Ctrl+? (or Escape) closes it, and it is only ever popped once: +/// closing clears the token first, and a dismissal by the barrier or close +/// button clears it when the route completes. +class ShellCheatsheet { + Object? _token; + + bool get isOpen => _token != null; + + void toggle(BuildContext context) { + if (isOpen) { + close(context); + } else { + open(context); + } + } + + void open(BuildContext context) { + if (isOpen) return; + final token = _token = Object(); + showKeyboardShortcutsHelp(context).whenComplete(() { + if (identical(_token, token)) _token = null; + }); + } + + void close(BuildContext context) { + if (!isOpen) return; + _token = null; + Navigator.of(context, rootNavigator: true).maybePop(); + } +} diff --git a/app/lib/shell/shell_cheatsheet_shortcut.dart b/app/lib/shell/shell_cheatsheet_shortcut.dart new file mode 100644 index 00000000..7d99bda1 --- /dev/null +++ b/app/lib/shell/shell_cheatsheet_shortcut.dart @@ -0,0 +1,31 @@ +import 'package:flutter/foundation.dart'; +import 'package:flutter/services.dart'; + +import 'shell_list_shortcuts.dart'; + +/// Whether [event] opens or closes the keyboard shortcuts cheatsheet: Ctrl+? +/// (Cmd+? on macOS). The chord is the one that types '?', so it is matched +/// by the logical '?' key or character, or by the slash key held with Shift on +/// US layouts. Ctrl+/ without Shift is Search and never matches here, and +/// Alt is never part of this chord. Only the first press of a held chord acts. +bool shellCheatsheetShortcut( + KeyEvent event, + HardwareKeyboard keyboard, { + TargetPlatform? platform, +}) { + if (event is! KeyDownEvent || + keyboard.isAltPressed || + !shellPrimaryModifier(keyboard, platform: platform)) { + return false; + } + return event.logicalKey == LogicalKeyboardKey.question || + event.character == '?' || + (event.logicalKey == LogicalKeyboardKey.slash && keyboard.isShiftPressed); +} + +/// The chord as it reads on this platform, for the help page. macOS accepts +/// Cmd or Ctrl (as Search does), so both are shown there. +String shellCheatsheetShortcutLabel([TargetPlatform? platform]) => + (platform ?? defaultTargetPlatform) == TargetPlatform.macOS + ? 'Cmd+?, Ctrl+?' + : 'Ctrl+?'; diff --git a/app/notes/ctrl-question-cheatsheet.md b/app/notes/ctrl-question-cheatsheet.md new file mode 100644 index 00000000..e9fbc84c --- /dev/null +++ b/app/notes/ctrl-question-cheatsheet.md @@ -0,0 +1,57 @@ +# Ctrl+? keyboard shortcuts cheatsheet + +Ctrl+? (Cmd+? on macOS) opens the keyboard shortcuts help as a cheatsheet from +any destination, from a focused chat composer and from floating windows. Ctrl+? +or Escape closes it. Ctrl+/ still opens Search. + +## Chord rules +- `shell/shell_cheatsheet_shortcut.dart`: primary modifier (Ctrl, or Cmd on + macOS, as Search uses), no Alt, KeyDown only. Matches the logical `?` key or + `?` character, or the slash key with Shift (US layout). +- Ctrl+/ without Shift is unchanged: Search. Search's matcher already rejects + Shift, so Ctrl+Shift+/ never opens Search. +- The terminal keeps the chord while it has the keyboard + (`primaryFocusIsTypingSurface()`, the chat shell terminal's `TypingSurface`). +- Labels: `Cmd+?, Ctrl+?` on macOS (the matcher accepts both, as Search's labels + do), `Ctrl+?` elsewhere. + +## Shell wiring +- `shell/shell_cheatsheet.dart` owns open/close. A token guards against a + second pop; dismissal by barrier or close button clears it. +- `shell/adaptive_shell.dart` checks the chord and Escape before the chat, Search + and list handlers. The rest of the handler is unchanged. + +## Help page +- Entries carry a group: Navigation, Chat, Windows, Terminal, Lists. +- Wide dialogs (content at least 520 px) split the groups into two balanced + columns; phone sheets stack them. +- Registry audit, added since the last help version: Ctrl+?, Esc to leave + Search, Esc Esc to stop a chat, pane focus and move chords, the Ctrl+Tab + pane cycle (not on web), divider and transcript arrows, slash-command arrows, + terminal copy/paste/select-all, terminal panel arrows, list pane arrows and + viewer Left/Right. The window-cycle entry now reads `Alt+\``, `Alt+Shift+\`` + (it was `Alt+\`` with Shift). + +## Focused tests (memwatch, 4 files, 27 passed, 0 failed) +- `test/shell/shell_cheatsheet_shortcut_test.dart`: matcher cases (US and other + layouts, Ctrl+/ vs Ctrl+?, Ctrl+Shift+/ not Search, Alt and key-up rejected, + macOS Cmd/Ctrl). +- `test/shell/shell_cheatsheet_test.dart`: opens from another destination and + from a focused composer on macOS and Windows; Ctrl+/ still opens Search; + Ctrl+Shift+/ opens the cheatsheet and not Search; ignored while a terminal + (TypingSurface) has focus, with the key reaching it; Escape and a second + Ctrl+? close it. +- `test/features/settings/keyboard_shortcuts_cheatsheet_test.dart`: every + implemented action appears once per platform, group coverage, Ctrl+? label, + pane/terminal chord labels, web tab-entry exclusion, two columns wide, one + column narrow. +- `test/features/settings/keyboard_shortcuts_help_test.dart` (existing, expectations + unchanged): passes. + +`tool/analyze.sh`: clean. + +## Not verified here +- No UI capture or device run (ui-review owns it). Widget tests use synthetic + key events; real Mac, Windows and non-US keyboard delivery is unverified. +- Phone bottom sheet and two-column wide layout are only checked by widget + layout tests, not by captures. diff --git a/app/test/features/settings/keyboard_shortcuts_cheatsheet_test.dart b/app/test/features/settings/keyboard_shortcuts_cheatsheet_test.dart new file mode 100644 index 00000000..a2d24090 --- /dev/null +++ b/app/test/features/settings/keyboard_shortcuts_cheatsheet_test.dart @@ -0,0 +1,176 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/settings/keyboard_shortcuts_help.dart'; +import 'package:pipelines_app/features/settings/keyboard_shortcuts_registry.dart'; + +const _implemented = [ + 'Show keyboard shortcuts', + 'Open Search', + 'Leave Search', + 'Open Chat', + 'Switch between Runs and Pipelines', + 'Focus the active chat composer', + 'Send a chat message', + 'Choose a slash command', + 'Toggle Center Stage', + 'Stop a running chat', + 'Focus the neighbouring chat pane', + 'Move the active chat pane', + 'Cycle chat panes and floating chats', + 'Resize panes with a focused divider', + 'Scroll a wide transcript block', + 'Show or hide floating chats', + 'Cycle floating windows', + 'Show or hide terminal', + 'Move between terminal tabs', + 'Copy selected terminal text', + 'Paste into the terminal', + 'Resize the terminal panel', + 'Open a chat list item', + 'Resize a list pane', + 'Previous or next artifact or changed file', +]; + +KeyboardShortcutEntry _entry( + KeyboardShortcutRegistry registry, + String action, +) => registry.entries.firstWhere((entry) => entry.action == action); + +void main() { + test('registry lists every implemented shortcut once, in its group', () { + for (final platform in [ + TargetPlatform.macOS, + TargetPlatform.windows, + TargetPlatform.iOS, + ]) { + final registry = KeyboardShortcutRegistry(platform: platform, web: false); + final actions = registry.entries.map((entry) => entry.action).toList(); + for (final action in _implemented) { + expect( + actions.where((listed) => listed == action), + hasLength(1), + reason: '$action on ${platform.name}', + ); + } + expect(actions.toSet(), hasLength(actions.length), reason: platform.name); + for (final group in KeyboardShortcutGroup.values) { + expect(registry.inGroup(group), isNotEmpty, reason: group.title); + } + } + }); + + test('Ctrl+? is labelled per platform and is in Navigation', () { + final mac = KeyboardShortcutRegistry( + platform: TargetPlatform.macOS, + web: false, + ); + final windows = KeyboardShortcutRegistry( + platform: TargetPlatform.windows, + web: false, + ); + final entry = _entry(mac, 'Show keyboard shortcuts'); + expect(entry.group, KeyboardShortcutGroup.navigation); + expect(entry.keys, 'Cmd+?, Ctrl+?'); + expect(entry.caveat, contains('Esc')); + expect(_entry(windows, 'Show keyboard shortcuts').keys, 'Ctrl+?'); + }); + + test('pane and terminal chords read as their handlers accept them', () { + KeyboardShortcutEntry at(TargetPlatform platform, String action) => _entry( + KeyboardShortcutRegistry(platform: platform, web: false), + action, + ); + + expect( + at(TargetPlatform.macOS, 'Focus the neighbouring chat pane').keys, + 'Cmd+Shift+Arrows', + ); + expect( + at(TargetPlatform.linux, 'Move the active chat pane').keys, + 'Ctrl+Alt+Shift+Arrows', + ); + expect(at(TargetPlatform.macOS, 'Stop a running chat').keys, 'Esc, Esc'); + expect( + at(TargetPlatform.macOS, 'Copy selected terminal text').keys, + 'Cmd+C', + ); + expect( + at(TargetPlatform.windows, 'Copy selected terminal text').keys, + 'Ctrl+C, Ctrl+Shift+C', + ); + expect( + at(TargetPlatform.windows, 'Cycle floating windows').keys, + 'Alt+`, Alt+Shift+`', + ); + expect( + at(TargetPlatform.macOS, 'Cycle floating windows').keys, + 'Option+`, Option+Shift+`', + ); + }); + + test('browsers keep Ctrl+Tab, so the tab entries are left out', () { + final web = KeyboardShortcutRegistry( + platform: TargetPlatform.linux, + web: true, + ); + final actions = web.entries.map((entry) => entry.action); + expect(actions, isNot(contains('Cycle chat panes and floating chats'))); + expect(actions, isNot(contains('Move between terminal tabs'))); + }); + + testWidgets('wide help splits groups into two columns', (tester) async { + const registry = KeyboardShortcutRegistry( + platform: TargetPlatform.windows, + web: false, + ); + tester.view.physicalSize = const Size(900, 1400); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + await tester.pumpWidget( + const MaterialApp( + home: Scaffold( + // The desktop dialog scrolls its content; mirror that here. + body: SingleChildScrollView( + child: Center( + child: SizedBox( + width: 640, + child: KeyboardShortcutsHelp(registry: registry), + ), + ), + ), + ), + ), + ); + + final navigation = tester.getTopLeft(find.text('Navigation')); + final chat = tester.getTopLeft(find.text('Chat')); + final windows = tester.getTopLeft(find.text('Windows')); + final lists = tester.getTopLeft(find.text('Lists')); + expect(chat.dx, greaterThan(navigation.dx)); + expect(lists.dx, greaterThan(navigation.dx)); + expect(windows.dx, navigation.dx); + expect(windows.dy, greaterThan(navigation.dy)); + }); + + testWidgets('narrow help stacks groups in one column', (tester) async { + const registry = KeyboardShortcutRegistry( + platform: TargetPlatform.iOS, + web: false, + ); + tester.view.physicalSize = const Size(360, 720); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + await tester.pumpWidget( + const MaterialApp( + home: Scaffold(body: KeyboardShortcutsHelp(registry: registry)), + ), + ); + + final navigation = tester.getTopLeft(find.text('Navigation')); + final chat = tester.getTopLeft(find.text('Chat')); + expect(chat.dx, navigation.dx); + expect(chat.dy, greaterThan(navigation.dy)); + }); +} diff --git a/app/test/shell/shell_cheatsheet_shortcut_test.dart b/app/test/shell/shell_cheatsheet_shortcut_test.dart new file mode 100644 index 00000000..1195984d --- /dev/null +++ b/app/test/shell/shell_cheatsheet_shortcut_test.dart @@ -0,0 +1,168 @@ +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/shell/shell_cheatsheet_shortcut.dart'; +import 'package:pipelines_app/shell/shell_list_shortcuts.dart'; + +class _Held extends HardwareKeyboard { + _Held({ + this.control = false, + this.meta = false, + this.shift = false, + this.alt = false, + }); + + final bool control; + final bool meta; + final bool shift; + final bool alt; + + @override + bool get isControlPressed => control; + @override + bool get isMetaPressed => meta; + @override + bool get isShiftPressed => shift; + @override + bool get isAltPressed => alt; +} + +KeyDownEvent _down(LogicalKeyboardKey key, {String? character}) => KeyDownEvent( + physicalKey: PhysicalKeyboardKey.slash, + logicalKey: key, + character: character, + timeStamp: Duration.zero, +); + +void main() { + test('Ctrl+? matches the typed question mark on US and other layouts', () { + const linux = TargetPlatform.linux; + // US layout: Shift+/ arrives as the slash key with Shift held. + expect( + shellCheatsheetShortcut( + _down(LogicalKeyboardKey.slash, character: '?'), + _Held(control: true, shift: true), + platform: linux, + ), + isTrue, + ); + // A layout whose '?' is its own logical key, with or without Shift. + expect( + shellCheatsheetShortcut( + _down(LogicalKeyboardKey.question, character: '?'), + _Held(control: true), + platform: linux, + ), + isTrue, + ); + expect( + shellCheatsheetShortcut( + _down(LogicalKeyboardKey.question), + _Held(control: true, shift: true), + platform: linux, + ), + isTrue, + ); + }); + + test('Ctrl+/ without Shift is Search and never the cheatsheet', () { + final slash = _down(LogicalKeyboardKey.slash, character: '/'); + expect( + shellCheatsheetShortcut( + slash, + _Held(control: true), + platform: TargetPlatform.linux, + ), + isFalse, + ); + expect( + shellSearchShortcut( + slash, + _Held(control: true), + platform: TargetPlatform.linux, + ), + isTrue, + ); + }); + + test('Ctrl+Shift+/ does not open Search', () { + final shiftedSlash = _down(LogicalKeyboardKey.slash, character: '?'); + expect( + shellSearchShortcut( + shiftedSlash, + _Held(control: true, shift: true), + platform: TargetPlatform.linux, + ), + isFalse, + ); + expect( + shellSearchShortcut( + shiftedSlash, + _Held(control: true, shift: true), + platform: TargetPlatform.macOS, + ), + isFalse, + ); + }); + + test('Alt, Cmd off macOS, and key releases do not match', () { + final question = _down(LogicalKeyboardKey.question, character: '?'); + expect( + shellCheatsheetShortcut( + question, + _Held(control: true, alt: true), + platform: TargetPlatform.linux, + ), + isFalse, + ); + expect( + shellCheatsheetShortcut( + question, + _Held(meta: true), + platform: TargetPlatform.linux, + ), + isFalse, + ); + expect( + shellCheatsheetShortcut( + const KeyUpEvent( + physicalKey: PhysicalKeyboardKey.slash, + logicalKey: LogicalKeyboardKey.question, + timeStamp: Duration.zero, + ), + _Held(control: true), + platform: TargetPlatform.linux, + ), + isFalse, + ); + expect( + shellCheatsheetShortcut( + _down(LogicalKeyboardKey.keyA), + _Held(control: true), + platform: TargetPlatform.linux, + ), + isFalse, + ); + }); + + test('macOS accepts Cmd or Ctrl, as Search does', () { + final question = _down(LogicalKeyboardKey.question, character: '?'); + expect( + shellCheatsheetShortcut( + question, + _Held(meta: true), + platform: TargetPlatform.macOS, + ), + isTrue, + ); + expect( + shellCheatsheetShortcut( + question, + _Held(control: true), + platform: TargetPlatform.macOS, + ), + isTrue, + ); + expect(shellCheatsheetShortcutLabel(TargetPlatform.macOS), 'Cmd+?, Ctrl+?'); + expect(shellCheatsheetShortcutLabel(TargetPlatform.windows), 'Ctrl+?'); + }); +} diff --git a/app/test/shell/shell_cheatsheet_test.dart b/app/test/shell/shell_cheatsheet_test.dart new file mode 100644 index 00000000..cade5b6b --- /dev/null +++ b/app/test/shell/shell_cheatsheet_test.dart @@ -0,0 +1,222 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/search/search_screen.dart'; +import 'package:pipelines_app/features/search/ui/search_bar_controls.dart'; +import 'package:pipelines_app/features/settings/keyboard_shortcuts_help.dart'; +import 'package:pipelines_app/shell/adaptive_shell.dart'; +import 'package:pipelines_app/shell/destination.dart'; +import 'package:pipelines_app/ui/input/keyboard_owner.dart'; + +class _Gateway implements ApiGateway { + @override + Stream get frames => const Stream.empty(); + @override + Future call(String type, [JsonMap fields = const {}]) async => { + 'search_results': {'results': [], 'truncated': false}, + }; +} + +/// Presses [key] with [modifiers] held, as one chord. +Future _chord( + WidgetTester tester, + List modifiers, + LogicalKeyboardKey key, +) async { + for (final modifier in modifiers) { + await tester.sendKeyDownEvent(modifier); + } + await tester.sendKeyEvent(key); + for (final modifier in modifiers.reversed) { + await tester.sendKeyUpEvent(modifier); + } + await tester.pumpAndSettle(); +} + +/// Ctrl+? as a US keyboard types it: Shift with the slash key. +Future _cheatsheetChord( + WidgetTester tester, + LogicalKeyboardKey primary, +) => _chord(tester, [ + primary, + LogicalKeyboardKey.shiftLeft, +], LogicalKeyboardKey.slash); + +Future _pumpShell( + WidgetTester tester, { + required Map bodies, + AppDestination destination = AppDestination.pipelines, + TargetPlatform? platform, +}) async { + await tester.pumpWidget( + MaterialApp( + theme: platform == null ? null : ThemeData(platform: platform), + home: AdaptiveShell(destination: destination, destinationBodies: bodies), + ), + ); + await tester.pumpAndSettle(); +} + +void main() { + for (final platform in [TargetPlatform.macOS, TargetPlatform.windows]) { + final primary = platform == TargetPlatform.macOS + ? LogicalKeyboardKey.metaLeft + : LogicalKeyboardKey.controlLeft; + + testWidgets( + 'Ctrl+? opens the cheatsheet from another destination on $platform', + (tester) async { + await _pumpShell( + tester, + destination: AppDestination.runs, + bodies: { + AppDestination.runs: (_) => const Text('runs body'), + AppDestination.pipelines: (_) => const Text('pipelines body'), + }, + ); + expect(find.byType(KeyboardShortcutsHelp), findsNothing); + + await _cheatsheetChord(tester, primary); + + expect(find.byType(KeyboardShortcutsHelp), findsOneWidget); + expect(find.text('Keyboard shortcuts'), findsOneWidget); + }, + variant: TargetPlatformVariant.only(platform), + ); + + testWidgets( + 'Ctrl+? opens the cheatsheet from a focused composer on $platform', + (tester) async { + final composer = TextEditingController(text: 'draft'); + final focus = FocusNode(); + addTearDown(composer.dispose); + addTearDown(focus.dispose); + await _pumpShell( + tester, + destination: AppDestination.chat, + platform: platform, + bodies: { + AppDestination.chat: (_) => + TextField(controller: composer, focusNode: focus), + }, + ); + focus.requestFocus(); + await tester.pump(); + + await _cheatsheetChord(tester, primary); + + expect(find.byType(KeyboardShortcutsHelp), findsOneWidget); + expect(composer.text, 'draft'); + }, + variant: TargetPlatformVariant.only(platform), + ); + + testWidgets( + 'Ctrl+/ still opens Search, not the cheatsheet, on $platform', + (tester) async { + final composer = TextEditingController(); + final focus = FocusNode(); + addTearDown(composer.dispose); + addTearDown(focus.dispose); + await _pumpShell( + tester, + destination: AppDestination.chat, + platform: platform, + bodies: { + AppDestination.chat: (_) => + TextField(controller: composer, focusNode: focus), + AppDestination.search: (_) => SearchScreen( + gateway: _Gateway(), + onOpen: (_) {}, + embedded: true, + ), + }, + ); + + await _chord(tester, [primary], LogicalKeyboardKey.slash); + + expect(find.byType(KeyboardShortcutsHelp), findsNothing); + final search = tester.widget(find.byKey(searchFieldKey)); + expect(search.focusNode!.hasFocus, isTrue); + }, + variant: TargetPlatformVariant.only(platform), + ); + + testWidgets( + 'Ctrl+Shift+/ opens the cheatsheet and not Search on $platform', + (tester) async { + await _pumpShell( + tester, + destination: AppDestination.chat, + platform: platform, + bodies: { + AppDestination.chat: (_) => const Text('chat body'), + AppDestination.search: (_) => SearchScreen( + gateway: _Gateway(), + onOpen: (_) {}, + embedded: true, + ), + }, + ); + + await _cheatsheetChord(tester, primary); + + expect(find.byType(KeyboardShortcutsHelp), findsOneWidget); + expect(find.byKey(searchFieldKey), findsNothing); + }, + variant: TargetPlatformVariant.only(platform), + ); + } + + testWidgets('Ctrl+? is ignored while a terminal has the keyboard', ( + tester, + ) async { + final seen = []; + final terminal = FocusNode(); + addTearDown(terminal.dispose); + await _pumpShell( + tester, + destination: AppDestination.chat, + bodies: { + AppDestination.chat: (_) => TypingSurface( + child: Focus( + focusNode: terminal, + autofocus: true, + onKeyEvent: (node, event) { + if (event is KeyDownEvent) seen.add(event.logicalKey); + return KeyEventResult.ignored; + }, + child: const SizedBox.expand(), + ), + ), + }, + ); + + await _cheatsheetChord(tester, LogicalKeyboardKey.controlLeft); + + expect(find.byType(KeyboardShortcutsHelp), findsNothing); + expect(seen, contains(LogicalKeyboardKey.slash)); + }); + + testWidgets('Escape and a second Ctrl+? close the cheatsheet', ( + tester, + ) async { + await _pumpShell( + tester, + destination: AppDestination.chat, + bodies: {AppDestination.chat: (_) => const Text('chat body')}, + ); + + await _cheatsheetChord(tester, LogicalKeyboardKey.controlLeft); + expect(find.byType(KeyboardShortcutsHelp), findsOneWidget); + await tester.sendKeyEvent(LogicalKeyboardKey.escape); + await tester.pumpAndSettle(); + expect(find.byType(KeyboardShortcutsHelp), findsNothing); + + await _cheatsheetChord(tester, LogicalKeyboardKey.controlLeft); + expect(find.byType(KeyboardShortcutsHelp), findsOneWidget); + await _cheatsheetChord(tester, LogicalKeyboardKey.controlLeft); + expect(find.byType(KeyboardShortcutsHelp), findsNothing); + }); +}