Toggle the terminal with Alt/Ctrl/Cmd+T, animate it, focus it, and cycle its tabs with Ctrl+Tab

Alt+T, Ctrl+T and Cmd+T join Ctrl+` as early focus-manager key handlers, so
they toggle the panel, window or narrow page from anywhere without reaching
the shell or a text field. Opening with no terminal starts one. The shown
terminal takes the keyboard (also on reload and tab changes) and hiding gives
it back. The panel slides from the bottom edge as the app shrinks, the window
scales and fades, both on Motion.standard and off under reduced motion.
While shown, Ctrl+Tab/Ctrl+Shift+Tab move between terminal tabs instead of
chat panes. The tooltip and menu list the shortcuts the platform delivers.
This commit is contained in:
2026-11-09 23:43:56 +00:00
parent 371d29224c
commit 30934aa71c
22 changed files with 1139 additions and 158 deletions
@@ -0,0 +1,105 @@
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/shell/chat_shell_terminal_view.dart';
import 'package:pipelines_app/features/terminal/terminal_hub.dart';
import 'package:pipelines_app/features/terminal/terminal_layout.dart';
import 'package:pipelines_app/features/terminal/terminal_surface.dart';
import 'package:pipelines_app/features/terminal/terminal_toggle_button.dart';
const appField = Key('app-field');
/// An app with a text field under the terminal surface, [size] logical
/// pixels, optionally asking for reduced motion.
Future<void> pumpTerminalApp(
WidgetTester tester, {
required TerminalHub hub,
required TerminalLayout layout,
Size size = const Size(1200, 800),
bool reduceMotion = false,
}) async {
tester.view.physicalSize = size;
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.reset);
await tester.pumpWidget(
MaterialApp(
builder: (context, child) => MediaQuery(
data: MediaQuery.of(context).copyWith(disableAnimations: reduceMotion),
child: child!,
),
home: TerminalSurface(
hub: hub,
layout: layout,
cupertino: false,
child: Scaffold(
appBar: AppBar(
title: const Text('App'),
actions: [TerminalToggleButton(layout: layout, cupertino: false)],
),
body: const TextField(key: appField),
),
),
),
);
await tester.pump();
}
/// Presses [key] with [modifiers] held, then lets the motion finish unless
/// [settle] is false.
Future<void> chord(
WidgetTester tester,
LogicalKeyboardKey key,
List<LogicalKeyboardKey> modifiers, {
bool settle = true,
}) async {
for (final modifier in modifiers) {
await tester.sendKeyDownEvent(modifier);
}
await tester.sendKeyEvent(key);
for (final modifier in modifiers.reversed) {
await tester.sendKeyUpEvent(modifier);
}
if (settle) {
await tester.pumpAndSettle();
} else {
await tester.pump();
}
}
Future<void> altT(WidgetTester tester, {bool settle = true}) => chord(
tester,
LogicalKeyboardKey.keyT,
[LogicalKeyboardKey.altLeft],
settle: settle,
);
Future<void> ctrlTab(WidgetTester tester, {bool reverse = false}) => chord(
tester,
LogicalKeyboardKey.tab,
[LogicalKeyboardKey.controlLeft, if (reverse) LogicalKeyboardKey.shiftLeft],
);
/// The terminal whose emulator has the keyboard, or null.
ChatShellTerminalView? focusedTerminal() => FocusManager
.instance
.primaryFocus
?.context
?.findAncestorWidgetOfExactType<ChatShellTerminalView>();
/// Whether [tab]'s emulator has the keyboard.
bool terminalFocused(String key) =>
focusedTerminal()?.key == ValueKey('terminal-view-$key');
/// Whether the app's text field has the keyboard.
bool appFieldFocused(WidgetTester tester) => tester
.widget<EditableText>(
find.descendant(
of: find.byKey(appField),
matching: find.byType(EditableText),
),
)
.focusNode
.hasFocus;
final Finder panelFinder = find.byKey(const ValueKey('terminal-panel'));
final Finder floatFinder = find.byKey(const ValueKey('terminal-float'));
@@ -0,0 +1,117 @@
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/chat/screen.dart';
import 'package:pipelines_app/features/chat/ui/sessions/session_actions.dart';
import 'package:pipelines_app/features/chat/workspace/chat_workspace.dart';
import 'package:pipelines_app/features/terminal/terminal_hub.dart';
import 'package:pipelines_app/features/terminal/terminal_layout.dart';
import 'package:pipelines_app/features/terminal/terminal_surface.dart';
import 'package:pipelines_app/features/terminal/terminal_tab.dart';
import 'package:pipelines_app/shell/adaptive_shell.dart';
import 'package:pipelines_app/shell/destination.dart';
import '../chat/conversation/chat_thread_fixtures.dart';
import 'terminal_app.dart';
import 'terminal_fixtures.dart';
class _Chats extends FakeChatGateway {
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) {
if (type == 'chat_sessions') {
return Future.value({
'chat_sessions': [
for (final id in ['a', 'b']) {'id': id, 'title': 'Chat $id'},
],
});
}
if (type == 'chat_shells') return Future.value({'chat_shells': []});
return super.call(type, fields);
}
}
EditableText _composer(WidgetTester tester, String id) =>
tester.widget<EditableText>(
find.descendant(
of: find.byKey(ValueKey('chat-composer-$id')),
matching: find.byType(EditableText),
),
);
void main() {
testWidgets('Ctrl+Tab cycles chat panes while the terminal is hidden and '
'terminal tabs while it is shown; hiding returns to the composer', (
tester,
) async {
SharedPreferences.setMockInitialValues({});
tester.view.physicalSize = const Size(1800, 1000);
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.reset);
final chats = _Chats()..history = (_) async => chatPage([]);
addTearDown(chats.close);
final mac = TerminalGateway()
..add('term_a', cwd: '/Users/op/src')
..add('term_b', cwd: '/Users/op/docs');
addTearDown(mac.close);
final hub = TerminalHub(TestMachines([machine('mac', mac)]));
addTearDown(hub.dispose);
final layout = TerminalLayout(store: MemoryLayoutStore());
await tester.pumpWidget(
MaterialApp(
home: TerminalSurface(
hub: hub,
layout: layout,
cupertino: false,
child: AdaptiveShell(
destination: AppDestination.chat,
destinationBodies: {
AppDestination.chat: (_) => ChatScreen(gateway: chats),
},
),
),
),
);
await tester.pumpAndSettle();
await tester.tap(find.byKey(const Key('chat-row-a')));
await tester.pumpAndSettle();
await tester.tap(
find.byWidgetPredicate(
(widget) =>
widget is SessionActionsButton && widget.session['id'] == 'b',
),
);
await tester.pumpAndSettle();
await tester.tap(find.text('Open to the right'));
await tester.pumpAndSettle();
final workspace = tester
.widget<ChatWorkspace>(find.byType(ChatWorkspace))
.controller;
expect(workspace.activePane?.sessionId, 'b');
// Hidden: Ctrl+Tab is the chat's.
await ctrlTab(tester);
expect(workspace.activePane?.sessionId, 'a');
expect(_composer(tester, 'a').focusNode.hasPrimaryFocus, isTrue);
// Shown: it moves between terminal tabs instead.
await altT(tester);
expect(terminalFocused(terminalKey('mac', 'term_a')), isTrue);
await ctrlTab(tester);
expect(hub.selected!.info.id, 'term_b');
expect(terminalFocused(terminalKey('mac', 'term_b')), isTrue);
expect(workspace.activePane?.sessionId, 'a');
await ctrlTab(tester, reverse: true);
expect(hub.selected!.info.id, 'term_a');
expect(workspace.activePane?.sessionId, 'a');
// Hidden again: the composer that had the keyboard gets it back, and
// Ctrl+Tab is the chat's once more.
await altT(tester);
expect(_composer(tester, 'a').focusNode.hasPrimaryFocus, isTrue);
await ctrlTab(tester);
expect(workspace.activePane?.sessionId, 'b');
expect(hub.selected!.info.id, 'term_a');
await tester.pumpWidget(const SizedBox.shrink());
});
}
@@ -0,0 +1,122 @@
import 'package:flutter/material.dart';
import 'package:flutter/scheduler.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/terminal/terminal_hub.dart';
import 'package:pipelines_app/features/terminal/terminal_layout.dart';
import 'terminal_app.dart';
import 'terminal_fixtures.dart';
void main() {
late TerminalGateway mac;
late TerminalHub hub;
late TerminalLayout layout;
setUp(() {
mac = TerminalGateway()..add('term_a', cwd: '/Users/op/src');
hub = TerminalHub(TestMachines([machine('mac', mac, name: 'Mac')]));
layout = TerminalLayout(store: MemoryLayoutStore());
});
tearDown(() async {
hub.dispose();
await mac.close();
});
const shown = 800 - terminalPanelDefaultHeight;
double appBottom(WidgetTester tester) =>
tester.getRect(find.byType(Scaffold).first).bottom;
double panelOpacity(WidgetTester tester) => tester
.widget<FadeTransition>(
find
.ancestor(of: panelFinder, matching: find.byType(FadeTransition))
.first,
)
.opacity
.value;
ScaleTransition floatScale(WidgetTester tester) => tester.widget(
find.descendant(of: floatFinder, matching: find.byType(ScaleTransition)),
);
testWidgets('the panel slides up from the bottom edge as the app above '
'shrinks, and slides away still mounted', (tester) async {
await pumpTerminalApp(tester, hub: hub, layout: layout);
await tester.tap(find.byKey(appField));
await tester.pump();
await altT(tester, settle: false);
await tester.pump(const Duration(milliseconds: 100));
expect(panelFinder, findsOneWidget);
// Midway: the app has given up part of the panel's height, and the
// panel (at its full height) is partly below the window's edge.
expect(appBottom(tester), inExclusiveRange(shown, 800));
expect(tester.getRect(panelFinder).top, closeTo(appBottom(tester), 1));
expect(tester.getSize(panelFinder).height, terminalPanelDefaultHeight);
expect(panelOpacity(tester), inExclusiveRange(0.4, 1));
await tester.pumpAndSettle();
expect(appBottom(tester), shown);
expect(panelOpacity(tester), 1);
await altT(tester, settle: false);
// The keyboard is back in the field at once; the panel leaves after.
expect(appFieldFocused(tester), isTrue);
await tester.pump(const Duration(milliseconds: 100));
expect(panelFinder, findsOneWidget);
expect(appBottom(tester), inExclusiveRange(shown, 800));
await tester.pumpAndSettle();
expect(panelFinder, findsNothing);
expect(appBottom(tester), 800);
expect(appFieldFocused(tester), isTrue);
});
testWidgets('the floating window grows and fades in from its place, and '
'shrinks away', (tester) async {
layout.setMode(TerminalMode.float);
await pumpTerminalApp(tester, hub: hub, layout: layout);
await altT(tester, settle: false);
await tester.pump(const Duration(milliseconds: 100));
final scale = floatScale(tester).scale.value;
expect(scale, inExclusiveRange(0.92, 1));
expect(floatScale(tester).alignment, Alignment.center);
// The app underneath never moves for a window.
expect(appBottom(tester), 800);
await tester.pumpAndSettle();
expect(floatScale(tester).scale.value, 1);
await altT(tester, settle: false);
await tester.pump(const Duration(milliseconds: 100));
expect(floatFinder, findsOneWidget);
expect(floatScale(tester).scale.value, inExclusiveRange(0.92, 1));
await tester.pumpAndSettle();
expect(floatFinder, findsNothing);
});
testWidgets('the motion follows the animation speed setting', (tester) async {
// AnimationSpeedController plays animations at half speed this way.
timeDilation = 2;
await pumpTerminalApp(tester, hub: hub, layout: layout);
await altT(tester, settle: false);
await tester.pump(const Duration(milliseconds: 300));
expect(appBottom(tester), inExclusiveRange(shown, 800));
await tester.pumpAndSettle();
expect(appBottom(tester), shown);
timeDilation = 1;
});
testWidgets('with reduced motion the terminal shows and hides at once', (
tester,
) async {
await pumpTerminalApp(tester, hub: hub, layout: layout, reduceMotion: true);
await altT(tester, settle: false);
await tester.pump();
expect(appBottom(tester), shown);
expect(panelOpacity(tester), 1);
await altT(tester, settle: false);
await tester.pump();
expect(panelFinder, findsNothing);
expect(appBottom(tester), 800);
layout.setMode(TerminalMode.float);
await altT(tester, settle: false);
await tester.pump();
expect(floatScale(tester).scale.value, 1);
// The emulator's size reaches the server after its debounce.
await tester.pump(const Duration(milliseconds: 300));
});
}
@@ -0,0 +1,215 @@
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/terminal/terminal_hub.dart';
import 'package:pipelines_app/features/terminal/terminal_layout.dart';
import 'package:pipelines_app/features/terminal/terminal_shortcuts.dart';
import 'package:pipelines_app/features/terminal/terminal_tab.dart';
import 'package:xterm/xterm.dart';
import 'terminal_app.dart';
import 'terminal_fixtures.dart';
void main() {
late TerminalGateway mac;
late TerminalHub hub;
late TerminalLayout layout;
setUp(() {
mac = TerminalGateway()
..add('term_a', cwd: '/Users/op/src')
..add('term_b', cwd: '/Users/op/docs')
..add('term_c', cwd: '/Users/op/notes');
hub = TerminalHub(TestMachines([machine('mac', mac, name: 'Mac')]));
layout = TerminalLayout(store: MemoryLayoutStore());
});
tearDown(() async {
hub.dispose();
await mac.close();
});
String key(String id) => terminalKey('mac', id);
const toggles = {
'Alt+T': (LogicalKeyboardKey.keyT, LogicalKeyboardKey.altLeft),
'Ctrl+T': (LogicalKeyboardKey.keyT, LogicalKeyboardKey.controlLeft),
'Cmd+T': (LogicalKeyboardKey.keyT, LogicalKeyboardKey.metaLeft),
'Ctrl+`': (LogicalKeyboardKey.backquote, LogicalKeyboardKey.controlLeft),
};
for (final mode in TerminalMode.values) {
for (final MapEntry(key: name, value: (letter, modifier))
in toggles.entries) {
testWidgets('$name toggles the ${mode.label.toLowerCase()} from a text '
'field and from inside the terminal', (tester) async {
layout.setMode(mode);
final surface = mode == TerminalMode.panel ? panelFinder : floatFinder;
await pumpTerminalApp(tester, hub: hub, layout: layout);
await tester.tap(find.byKey(appField));
await tester.pump();
await chord(tester, letter, [modifier]);
expect(surface, findsOneWidget);
expect(layout.visible, isTrue);
// The shortcut never types into the field it was pressed in.
expect(find.text('t'), findsNothing);
expect(terminalFocused(key('term_a')), isTrue);
// Inside the terminal the same keys hide it instead of reaching the
// shell (Ctrl+T would be transpose-chars there).
final typed = mac.bodies('terminal_input').length;
await chord(tester, letter, [modifier]);
expect(surface, findsNothing);
expect(layout.visible, isFalse);
expect(mac.bodies('terminal_input'), hasLength(typed));
expect(hub.tabs, hasLength(3));
});
}
}
testWidgets('Shift or a second modifier leaves T alone', (tester) async {
await pumpTerminalApp(tester, hub: hub, layout: layout);
for (final modifiers in [
[LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.shiftLeft],
[LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.altLeft],
[LogicalKeyboardKey.metaLeft, LogicalKeyboardKey.shiftLeft],
]) {
await chord(tester, LogicalKeyboardKey.keyT, modifiers);
expect(layout.visible, isFalse, reason: '$modifiers');
}
});
testWidgets('showing focuses the terminal; hiding gives the keyboard back '
'to the field that had it', (tester) async {
await pumpTerminalApp(tester, hub: hub, layout: layout);
await tester.tap(find.byKey(appField));
await tester.pump();
expect(appFieldFocused(tester), isTrue);
await altT(tester);
expect(terminalFocused(key('term_a')), isTrue);
expect(appFieldFocused(tester), isFalse);
// Typing goes straight to the shell.
await tester.sendKeyEvent(LogicalKeyboardKey.keyX);
await tester.pump();
expect(mac.bodies('terminal_input').last['data'], 'x');
await altT(tester);
expect(appFieldFocused(tester), isTrue);
// The bar button focuses it as well.
await tester.tap(find.byIcon(Icons.terminal));
await tester.pumpAndSettle();
expect(terminalFocused(key('term_a')), isTrue);
});
testWidgets('a terminal left shown before a reload is focused once it '
'lists', (tester) async {
layout.show();
await pumpTerminalApp(tester, hub: hub, layout: layout);
await tester.pumpAndSettle();
expect(panelFinder, findsOneWidget);
expect(terminalFocused(key('term_a')), isTrue);
// The emulator's size reaches the server after its debounce.
await tester.pump(const Duration(milliseconds: 300));
});
testWidgets('Ctrl+Tab and Ctrl+Shift+Tab move between terminal tabs, '
'wrapping, and focus each; hidden, they do nothing here', (tester) async {
await pumpTerminalApp(tester, hub: hub, layout: layout);
await ctrlTab(tester);
expect(hub.active, isFalse);
await tester.tap(find.byKey(appField));
await altT(tester);
for (final id in ['term_b', 'term_c', 'term_a', 'term_b']) {
await ctrlTab(tester);
expect(hub.selected!.info.id, id);
expect(terminalFocused(key(id)), isTrue, reason: id);
}
for (final id in ['term_a', 'term_c']) {
await ctrlTab(tester, reverse: true);
expect(hub.selected!.info.id, id);
expect(terminalFocused(key(id)), isTrue, reason: id);
}
// From the field too: the terminal claims the keys while it is shown.
await tester.tap(find.byKey(appField));
await tester.pump();
await ctrlTab(tester);
expect(hub.selected!.info.id, 'term_a');
expect(terminalFocused(key('term_a')), isTrue);
await altT(tester);
await ctrlTab(tester);
expect(hub.selected!.info.id, 'term_a');
});
testWidgets('a tab picked by pointer takes the keyboard', (tester) async {
layout.show();
await pumpTerminalApp(tester, hub: hub, layout: layout);
await tester.pumpAndSettle();
await tester.tap(find.text('notes'));
await tester.pumpAndSettle();
expect(terminalFocused(key('term_c')), isTrue);
});
testWidgets('opening with no terminal starts one', (tester) async {
final empty = TerminalGateway();
final bare = TerminalHub(TestMachines([machine('mac', empty)]));
addTearDown(bare.dispose);
await pumpTerminalApp(tester, hub: bare, layout: layout);
await altT(tester);
expect(empty.bodies('terminal_open'), hasLength(1));
expect(bare.tabs, hasLength(1));
expect(terminalFocused(bare.tabs.single.key), isTrue);
await altT(tester);
await altT(tester);
expect(empty.bodies('terminal_open'), hasLength(1));
});
testWidgets('on a narrow window the keys open and close the full-screen '
'page, focused, and Ctrl+Tab moves between its tabs', (tester) async {
await pumpTerminalApp(
tester,
hub: hub,
layout: layout,
size: const Size(390, 800),
);
await tester.tap(find.byKey(appField));
await tester.pump();
await chord(tester, LogicalKeyboardKey.keyT, [
LogicalKeyboardKey.controlLeft,
]);
expect(find.widgetWithText(AppBar, 'Terminal'), findsOneWidget);
expect(terminalFocused(key('term_a')), isTrue);
await ctrlTab(tester, reverse: true);
expect(hub.selected!.info.id, 'term_c');
expect(terminalFocused(key('term_c')), isTrue);
await chord(tester, LogicalKeyboardKey.keyT, [
LogicalKeyboardKey.controlLeft,
]);
expect(find.widgetWithText(AppBar, 'Terminal'), findsNothing);
expect(find.byType(TerminalView), findsNothing);
expect(appFieldFocused(tester), isTrue);
});
test('the listed shortcuts are the ones the platform delivers', () {
const mac = TerminalShortcutLabels(
web: false,
platform: TargetPlatform.macOS,
);
expect(mac.toggle, ['Cmd+T', 'Ctrl+T', 'Option+T', 'Ctrl+`']);
expect(mac.tabs, ['Ctrl+Tab', 'Ctrl+Shift+Tab']);
const linux = TerminalShortcutLabels(
web: false,
platform: TargetPlatform.linux,
);
expect(linux.toggle, ['Ctrl+T', 'Alt+T', 'Ctrl+`']);
const macWeb = TerminalShortcutLabels(
web: true,
platform: TargetPlatform.macOS,
);
expect(macWeb.toggle, ['Ctrl+T', 'Option+T', 'Ctrl+`']);
expect(macWeb.tabs, isEmpty);
expect(macWeb.summary, isNot(contains('Tab')));
const windowsWeb = TerminalShortcutLabels(
web: true,
platform: TargetPlatform.windows,
);
expect(windowsWeb.toggle, ['Alt+T', 'Ctrl+`']);
expect(windowsWeb.button, 'Terminal (Alt+T)');
});
}