Merge branch 'main' into pipelines/run-20261111-1951-material-cleanup-remaining-fixtures-and-92bd

This commit is contained in:
2026-11-11 20:48:46 +00:00
10 changed files with 366 additions and 1 deletions
@@ -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<void> showKeyboardShortcutsHelp(BuildContext context) =>
showAppDetails<void>(
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: [
Expanded(
child: Text(
keyboardShortcutsLabel,
style: Theme.of(context).textTheme.headlineSmall,
),
),
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),
],
],
),
);
}
@@ -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<KeyboardShortcutEntry> 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',
),
];
}
@@ -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),
);
}
@@ -11,4 +11,7 @@ abstract final class SettingsKeys {
static const saveWorkspace = ValueKey<String>('settings.saveWorkspace');
static const templates = ValueKey<String>('settings.templates');
static const schedules = ValueKey<String>('settings.schedules');
static const keyboardShortcuts = ValueKey<String>(
'settings.keyboardShortcuts',
);
}
@@ -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';
@@ -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',
+2 -1
View File
@@ -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';
@@ -382,7 +383,7 @@ class _AdaptiveShellState extends State<AdaptiveShell> {
IconButton(
key: const ValueKey('shell.search'),
onPressed: onSearch,
tooltip: 'Search',
tooltip: 'Search (${shellSearchShortcutLabels().join(', ')})',
icon: const Icon(Icons.search),
),
...widget.barActions,
@@ -0,0 +1,12 @@
import 'package:flutter/foundation.dart';
/// Search chords supported by the shell, independent of theme overrides.
List<String> 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+/',
];
}
+26
View File
@@ -0,0 +1,26 @@
# Keyboard shortcuts help
Added a Settings → Tools → 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+/. The separately reviewed Search handler change (run 367)
is integrated into this candidate before landing the help.
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.
Manager merged-tree verification after Search integration: 24 focused help,
Settings, Search-shortcut and chat-keyboard tests passed; analysis was clean.
@@ -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);
});
}