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.
This commit is contained in:
2026-11-12 14:41:20 +00:00
parent a3fb506a57
commit 3e0b1e55c7
9 changed files with 1002 additions and 50 deletions
@@ -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<void> showKeyboardShortcutsHelp(BuildContext context) =>
showAppDetails<void>(
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<KeyboardShortcutEntry> 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});
@@ -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<KeyboardShortcutEntry> inGroup(KeyboardShortcutGroup group) => [
for (final entry in entries)
if (entry.group == group) entry,
];
List<KeyboardShortcutEntry> get entries => [
..._navigation,
..._chat,
..._windows,
..._terminal,
..._lists,
];
String get _cheatsheetKeys => shellCheatsheetShortcutLabel(platform);
List<KeyboardShortcutEntry> 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<KeyboardShortcutEntry> 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<KeyboardShortcutEntry> 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<KeyboardShortcutEntry> 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<KeyboardShortcutEntry> 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',
),
];
}
+21
View File
@@ -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<AdaptiveShell> {
// page of its own for the system Back to close first.
final Map<AppDestination, bool> _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<AdaptiveShell> {
/// 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) &&
+35
View File
@@ -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();
}
}
@@ -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+?';
+57
View File
@@ -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.
@@ -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));
});
}
@@ -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+?');
});
}
+222
View File
@@ -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<JsonMap> get frames => const Stream.empty();
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) async => {
'search_results': {'results': [], 'truncated': false},
};
}
/// Presses [key] with [modifiers] held, as one chord.
Future<void> _chord(
WidgetTester tester,
List<LogicalKeyboardKey> 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<void> _cheatsheetChord(
WidgetTester tester,
LogicalKeyboardKey primary,
) => _chord(tester, [
primary,
LogicalKeyboardKey.shiftLeft,
], LogicalKeyboardKey.slash);
Future<void> _pumpShell(
WidgetTester tester, {
required Map<AppDestination, WidgetBuilder> 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<TextField>(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 = <LogicalKeyboardKey>[];
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);
});
}