From 21115f8e8f790209c5c7a8326d283a1022d5003d Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 11 Nov 2026 20:05:56 +0000 Subject: [PATCH] Add unified keyboard shortcut help Expose platform-aware shortcut help from Settings, keep narrow layouts scrollable, share Search tooltip labels, and document Terminal-to-chat composer focus. Integrate together with the separately reviewed Alt-slash handler. --- .../settings/keyboard_shortcuts_help.dart | 114 ++++++++++++++++++ .../settings/keyboard_shortcuts_registry.dart | 92 ++++++++++++++ .../settings_keyboard_shortcuts_section.dart | 19 +++ app/lib/features/settings/settings_keys.dart | 3 + .../features/settings/settings_screen.dart | 1 + .../settings/settings_topic_pages.dart | 5 + app/lib/shell/adaptive_shell.dart | 3 +- .../shell/shell_search_shortcut_labels.dart | 12 ++ app/notes/keyboard-shortcuts-help.md | 23 ++++ .../keyboard_shortcuts_help_test.dart | 92 ++++++++++++++ 10 files changed, 363 insertions(+), 1 deletion(-) create mode 100644 app/lib/features/settings/keyboard_shortcuts_help.dart create mode 100644 app/lib/features/settings/keyboard_shortcuts_registry.dart create mode 100644 app/lib/features/settings/settings_keyboard_shortcuts_section.dart create mode 100644 app/lib/shell/shell_search_shortcut_labels.dart create mode 100644 app/notes/keyboard-shortcuts-help.md create mode 100644 app/test/features/settings/keyboard_shortcuts_help_test.dart diff --git a/app/lib/features/settings/keyboard_shortcuts_help.dart b/app/lib/features/settings/keyboard_shortcuts_help.dart new file mode 100644 index 00000000..a0b99414 --- /dev/null +++ b/app/lib/features/settings/keyboard_shortcuts_help.dart @@ -0,0 +1,114 @@ +import 'package:flutter/material.dart'; + +import '../../ui/adaptive/app_popups.dart'; +import 'keyboard_shortcuts_registry.dart'; + +const keyboardShortcutsLabel = 'Keyboard shortcuts'; + +Future showKeyboardShortcutsHelp(BuildContext context) => + showAppDetails( + context, + maxWidth: 640, + builder: (_) => const KeyboardShortcutsHelp(), + ); + +class KeyboardShortcutsHelp extends StatelessWidget { + const KeyboardShortcutsHelp({super.key, this.registry}); + + final KeyboardShortcutRegistry? registry; + + @override + Widget build(BuildContext context) { + final entries = (registry ?? KeyboardShortcutRegistry.current()).entries; + final content = Semantics( + scopesRoute: true, + namesRoute: true, + explicitChildNodes: true, + label: 'Keyboard shortcuts help', + child: Padding( + padding: const EdgeInsets.fromLTRB(24, 8, 24, 24), + child: Column( + mainAxisSize: MainAxisSize.min, + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Row( + children: [ + const Expanded( + child: Text( + keyboardShortcutsLabel, + style: TextStyle(fontSize: 22, fontWeight: FontWeight.w600), + ), + ), + IconButton( + tooltip: 'Close keyboard shortcuts', + onPressed: () => Navigator.of(context).pop(), + icon: const Icon(Icons.close), + ), + ], + ), + const SizedBox(height: 8), + Text( + 'Shortcuts available in the current app and browser environment.', + 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), + ), + ], + const SizedBox(height: 4), + Text( + 'On macOS, Option is shown for Alt. Browsers can reserve system or tab shortcuts.', + style: Theme.of(context).textTheme.bodySmall, + ), + ], + ), + ), + ); + // The desktop details dialog supplies its own bounded scroll view. The + // narrow details sheet does not, so keep the help readable at large text + // scales and on short phone screens there as well. + return usesDesktopPopups(context) + ? content + : SingleChildScrollView(child: content); + } +} + +class _ShortcutRow extends StatelessWidget { + const _ShortcutRow({required this.entry}); + + final KeyboardShortcutEntry entry; + + @override + Widget build(BuildContext context) => Semantics( + container: true, + label: + '${entry.action}: ${entry.keys}${entry.caveat == null ? '' : '. ${entry.caveat}'}', + child: Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Row( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Expanded(child: Text(entry.action)), + const SizedBox(width: 16), + Flexible( + child: Text( + entry.keys, + textAlign: TextAlign.end, + style: const TextStyle(fontWeight: FontWeight.w600), + ), + ), + ], + ), + if (entry.caveat case final caveat?) ...[ + const SizedBox(height: 4), + Text(caveat, style: Theme.of(context).textTheme.bodySmall), + ], + ], + ), + ); +} diff --git a/app/lib/features/settings/keyboard_shortcuts_registry.dart b/app/lib/features/settings/keyboard_shortcuts_registry.dart new file mode 100644 index 00000000..a4ce79f4 --- /dev/null +++ b/app/lib/features/settings/keyboard_shortcuts_registry.dart @@ -0,0 +1,92 @@ +import 'package:flutter/foundation.dart'; + +import '../chat/workspace/chat_center_stage_controller.dart'; +import '../chat/workspace/chat_float_shortcut.dart'; +import '../terminal/terminal_shortcuts.dart'; +import '../../shell/windows/window_shortcuts.dart'; +import '../../shell/shell_search_shortcut_labels.dart'; + +/// 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.action, + required this.keys, + this.caveat, + }); + + final String action; + final String keys; + final String? caveat; +} + +class KeyboardShortcutRegistry { + const KeyboardShortcutRegistry({required this.platform, required this.web}); + + factory KeyboardShortcutRegistry.current() => + KeyboardShortcutRegistry(platform: defaultTargetPlatform, web: kIsWeb); + + final TargetPlatform platform; + final bool web; + + bool get _apple => + platform == TargetPlatform.macOS || platform == TargetPlatform.iOS; + + bool get _macOS => platform == TargetPlatform.macOS; + + List get entries => [ + KeyboardShortcutEntry( + action: 'Show or hide terminal', + keys: TerminalShortcutLabels( + web: web, + platform: platform, + ).toggle.join(', '), + caveat: web + ? 'Browser tab shortcuts such as Cmd+T are not available to the app.' + : null, + ), + 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.', + ), + 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', + ), + KeyboardShortcutEntry( + 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.', + ), + KeyboardShortcutEntry( + action: 'Send a chat message', + keys: _apple ? 'Cmd+Enter' : 'Ctrl+Enter', + ), + if (!web) + const KeyboardShortcutEntry( + action: 'Move between terminal tabs', + keys: 'Ctrl+Tab, Ctrl+Shift+Tab', + ), + ]; +} diff --git a/app/lib/features/settings/settings_keyboard_shortcuts_section.dart b/app/lib/features/settings/settings_keyboard_shortcuts_section.dart new file mode 100644 index 00000000..4a6466b6 --- /dev/null +++ b/app/lib/features/settings/settings_keyboard_shortcuts_section.dart @@ -0,0 +1,19 @@ +import 'package:flutter/material.dart'; + +import 'keyboard_shortcuts_help.dart'; +import 'settings_keys.dart'; +import 'settings_row.dart'; + +class SettingsKeyboardShortcutsSection extends StatelessWidget { + const SettingsKeyboardShortcutsSection({super.key}); + + @override + Widget build(BuildContext context) => SettingsRow( + key: SettingsKeys.keyboardShortcuts, + leading: const Icon(Icons.keyboard_outlined), + title: const Text(keyboardShortcutsLabel), + subtitle: const Text('See the shortcuts available on this platform.'), + chevron: true, + onTap: () => showKeyboardShortcutsHelp(context), + ); +} diff --git a/app/lib/features/settings/settings_keys.dart b/app/lib/features/settings/settings_keys.dart index 48bee87a..cd9a56b6 100644 --- a/app/lib/features/settings/settings_keys.dart +++ b/app/lib/features/settings/settings_keys.dart @@ -11,4 +11,7 @@ abstract final class SettingsKeys { static const saveWorkspace = ValueKey('settings.saveWorkspace'); static const templates = ValueKey('settings.templates'); static const schedules = ValueKey('settings.schedules'); + static const keyboardShortcuts = ValueKey( + 'settings.keyboardShortcuts', + ); } diff --git a/app/lib/features/settings/settings_screen.dart b/app/lib/features/settings/settings_screen.dart index bd646fd9..463a8c4b 100644 --- a/app/lib/features/settings/settings_screen.dart +++ b/app/lib/features/settings/settings_screen.dart @@ -37,6 +37,7 @@ import 'settings_templates_section.dart'; import 'server_connections.dart'; import 'saved_servers_section.dart'; import 'managed_connection_section.dart'; +import 'settings_keyboard_shortcuts_section.dart'; part 'settings_topic_pages.dart'; diff --git a/app/lib/features/settings/settings_topic_pages.dart b/app/lib/features/settings/settings_topic_pages.dart index 7defeaaf..2be494de 100644 --- a/app/lib/features/settings/settings_topic_pages.dart +++ b/app/lib/features/settings/settings_topic_pages.dart @@ -82,6 +82,11 @@ extension _SettingsTopicPages on _SettingsScreenState { SettingsStorageSection(gateway: widget.client), ), _single('Server', SettingsHealthSection(gateway: widget.client)), + SettingsGroup( + title: 'Help', + leadingRows: true, + children: const [SettingsKeyboardShortcutsSection()], + ), if (widget.onOpenSchedules != null || widget.onOpenTemplates != null) SettingsGroup( title: 'Library', diff --git a/app/lib/shell/adaptive_shell.dart b/app/lib/shell/adaptive_shell.dart index 9427c9da..1a1dec1b 100644 --- a/app/lib/shell/adaptive_shell.dart +++ b/app/lib/shell/adaptive_shell.dart @@ -10,6 +10,7 @@ import 'list_detail.dart'; import 'list_pane_widths.dart'; import 'shell_bar.dart'; import 'shell_list_shortcuts.dart'; +import 'shell_search_shortcut_labels.dart'; import 'tab_history.dart'; import '../ui/input/keyboard_owner.dart'; @@ -383,7 +384,7 @@ class _AdaptiveShellState extends State { IconButton( key: const ValueKey('shell.search'), onPressed: onSearch, - tooltip: 'Search', + tooltip: 'Search (${shellSearchShortcutLabels().join(', ')})', icon: const Icon(Icons.search), ), ...widget.barActions, diff --git a/app/lib/shell/shell_search_shortcut_labels.dart b/app/lib/shell/shell_search_shortcut_labels.dart new file mode 100644 index 00000000..b4046a5c --- /dev/null +++ b/app/lib/shell/shell_search_shortcut_labels.dart @@ -0,0 +1,12 @@ +import 'package:flutter/foundation.dart'; + +/// Search chords supported by the shell, independent of theme overrides. +List shellSearchShortcutLabels([TargetPlatform? platform]) { + final target = platform ?? defaultTargetPlatform; + final apple = target == TargetPlatform.macOS || target == TargetPlatform.iOS; + return [ + apple ? 'Option+/' : 'Alt+/', + if (target == TargetPlatform.macOS) 'Cmd+/', + 'Ctrl+/', + ]; +} diff --git a/app/notes/keyboard-shortcuts-help.md b/app/notes/keyboard-shortcuts-help.md new file mode 100644 index 00000000..97eb28d9 --- /dev/null +++ b/app/notes/keyboard-shortcuts-help.md @@ -0,0 +1,23 @@ +# Keyboard shortcuts help + +Added a Settings → Help entry that opens a root-layered, bounded Material help +surface on desktop and the existing adaptive sheet on narrow layouts. The +registry reuses the terminal, floating-chat, Center Stage and window-cycle +label helpers, and records browser caveats for shortcuts that may be reserved. +Search and its tooltip share platform-aware labels for Option/Alt+/, macOS +Cmd+/, and Ctrl+/. Integration depends on the separately reviewed Search +handler change (run 367); do not land the help without that handler. +Floating-chat help describes the new Terminal-to-composer focus handoff +instead of the obsolete macOS shell-yank exception. +Chat list numbering likewise uses Command only on macOS, matching the shell +rule on iOS and other platforms. + +Focused verification: + +- `tool/memwatch/full.sh 'test/features/settings/keyboard_shortcuts_help_test.dart test/features/settings/settings_screen_test.dart'` + — 15 passed, 0 failed. +- `tool/analyze.sh` — clean. + +Browser/full-app capture was not run in this implementation stage; ui-review +should verify desktop light/dark, scaled text, keyboard traversal, and phone +constraints with the full-app fixture. diff --git a/app/test/features/settings/keyboard_shortcuts_help_test.dart b/app/test/features/settings/keyboard_shortcuts_help_test.dart new file mode 100644 index 00000000..80fa97e1 --- /dev/null +++ b/app/test/features/settings/keyboard_shortcuts_help_test.dart @@ -0,0 +1,92 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.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'; + +void main() { + const registry = KeyboardShortcutRegistry( + platform: TargetPlatform.macOS, + web: true, + ); + + test('registry uses platform labels and browser caveats', () { + final entries = registry.entries; + final terminal = entries.firstWhere( + (entry) => entry.action == 'Show or hide terminal', + ); + final search = entries.firstWhere((entry) => entry.action == 'Open Search'); + + expect(terminal.keys, contains('Option+T')); + expect(terminal.keys, isNot(contains('Cmd+T'))); + expect(search.keys, 'Option+/, Cmd+/, Ctrl+/'); + expect(search.caveat, contains('browser')); + }); + + test('uses the shell primary modifier rule on iOS', () { + final entries = const KeyboardShortcutRegistry( + platform: TargetPlatform.iOS, + web: false, + ).entries; + expect( + entries + .firstWhere((entry) => entry.action == 'Open a chat list item') + .keys, + 'Ctrl+1…9', + ); + expect( + entries.firstWhere((entry) => entry.action == 'Open Search').keys, + 'Option+/, Ctrl+/', + ); + expect( + entries + .firstWhere((entry) => entry.action == 'Show or hide floating chats') + .caveat, + contains('focuses its message input'), + ); + }); + + testWidgets('help is readable and keyboard traversable', (tester) async { + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: SingleChildScrollView( + child: KeyboardShortcutsHelp(registry: registry), + ), + ), + ), + ); + + expect(find.text('Keyboard shortcuts'), findsOneWidget); + expect(find.text('Show or hide floating chats'), findsOneWidget); + expect(find.text('Option+Y, Ctrl+Y, Cmd+Y'), findsOneWidget); + expect( + tester.getSemantics(find.bySemanticsLabel('Keyboard shortcuts help')), + matchesSemantics( + scopesRoute: true, + namesRoute: true, + label: 'Keyboard shortcuts help', + ), + ); + + await tester.sendKeyEvent(LogicalKeyboardKey.tab); + expect(find.byTooltip('Close keyboard shortcuts'), findsOneWidget); + }); + + testWidgets('narrow help content scrolls', (tester) async { + await tester.pumpWidget( + MediaQuery( + data: const MediaQueryData( + size: Size(400, 640), + textScaler: TextScaler.linear(2), + ), + child: MaterialApp( + home: Scaffold(body: KeyboardShortcutsHelp(registry: registry)), + ), + ), + ); + + expect(find.byType(SingleChildScrollView), findsOneWidget); + expect(find.text('Keyboard shortcuts'), findsOneWidget); + }); +}