diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index f3a52b45..dc114320 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -28,6 +28,8 @@ import '../features/runs/ui/run_search_selection.dart'; import '../features/search/domain/search_target.dart'; import '../features/settings/settings_screen.dart'; import '../features/settings/settings_store.dart'; +import '../features/walkthrough/walkthrough_gate.dart'; +import '../features/walkthrough/walkthrough_store.dart'; import '../features/updates/app_updates.dart'; import '../features/updates/launch_update.dart'; import '../features/updates/launch_update_dialog.dart'; @@ -579,6 +581,10 @@ class _PipelinesAppState extends State _attentionCount.value = count; } + /// The device's first-run walkthrough record (per device, not per server). + final WalkthroughStore _walkthroughStore = + const SharedPreferencesWalkthroughStore(); + @override Widget build(BuildContext context) => widget.servers == null ? MyApp.router(routerConfig: _config) @@ -801,7 +807,7 @@ class _PipelinesAppState extends State builder: (context, count, _) => _terminals.surround( _shellFor(route, count), onChat: route.kind == AppRouteKind.chat, - windows: WindowHost(manager: _windows), + windows: WindowHost(manager: _windows, reservesRail: true), ), ); @@ -837,32 +843,40 @@ class _PipelinesAppState extends State _bodyRoutes[AppDestination.pipelines] ?? AppRoute.pipelines, ), destinationBodies: { - AppDestination.pipelines: (_) => PipelinesDestination( - session: _session, - server: widget.server, - active: _destinationOf(route.kind) == AppDestination.pipelines, - legacyPendingEndpoints: widget.legacyPendingEndpoints, - refreshToken: _pipelinesRefresh, - onRunStarted: _runStarted, - onViewPipelineRuns: (id) => - _delegate.goTo(AppRoute.runsForPipeline(id)), - onOpenSchedules: _delegate.openSchedules, - onOpenSettings: () => _delegate.goTo(AppRoute.settings), - // The open pipeline is part of the route, so Back steps out of it. - onSelectionChanged: (id) { - final current = _delegate.route; - if (current.kind != AppRouteKind.pipelines) return; - if (id == null) { - if (current.pipelineId != null) { - _delegate.goTo(AppRoute.pipelines); + AppDestination.pipelines: (_) => FirstRunWalkthroughGate( + store: _walkthroughStore, + enabled: _destinationOf(route.kind) == AppDestination.pipelines, + serverScope: _navigationScope, + connection: _session, + connected: () => _session.connected, + gateway: _session.client, + child: PipelinesDestination( + session: _session, + server: widget.server, + active: _destinationOf(route.kind) == AppDestination.pipelines, + legacyPendingEndpoints: widget.legacyPendingEndpoints, + refreshToken: _pipelinesRefresh, + onRunStarted: _runStarted, + onViewPipelineRuns: (id) => + _delegate.goTo(AppRoute.runsForPipeline(id)), + onOpenSchedules: _delegate.openSchedules, + onOpenSettings: () => _delegate.goTo(AppRoute.settings), + // The open pipeline is part of the route, so Back steps out of it. + onSelectionChanged: (id) { + final current = _delegate.route; + if (current.kind != AppRouteKind.pipelines) return; + if (id == null) { + if (current.pipelineId != null) { + _delegate.goTo(AppRoute.pipelines); + } + } else if (current.pipelineId != id) { + _delegate.goTo(AppRoute.pipeline(id)); } - } else if (current.pipelineId != id) { - _delegate.goTo(AppRoute.pipeline(id)); - } - }, - initialPipelineId: pipelinesRoute.pipelineId, - initialVersion: pipelinesRoute.version, - initialStageKey: pipelinesRoute.stageKey, + }, + initialPipelineId: pipelinesRoute.pipelineId, + initialVersion: pipelinesRoute.version, + initialStageKey: pipelinesRoute.stageKey, + ), ), // The one place a field or artifact hit's selection can be resolved: the // run detail owns the recorded visit and Summary section. diff --git a/app/lib/features/pipelines/screen.dart b/app/lib/features/pipelines/screen.dart index f6a1a810..fb0ea904 100644 --- a/app/lib/features/pipelines/screen.dart +++ b/app/lib/features/pipelines/screen.dart @@ -2,6 +2,7 @@ import '../../ui/adaptive/segmented_bar.dart'; import '../../shell/destination.dart'; import '../../shell/detail_page.dart'; import '../../shell/list_detail.dart'; +import '../../shell/shell_rail_scope.dart'; import 'package:flutter/material.dart'; import '../../core/api_gateway.dart'; @@ -288,7 +289,10 @@ class _PipelinesScreenState extends State { if (listShown && widget.onOpenSchedules != null) _schedulesButton(context), _refreshButton(context), - if (listShown && widget.onOpenSettings != null) + // A wide window's rail offers Settings; the gear stays on a phone. + if (listShown && + !ShellRailScope.isShown(context) && + widget.onOpenSettings != null) _settingsButton(context), ], child: body, diff --git a/app/lib/features/runs/ui/run_detail_tab_bodies.dart b/app/lib/features/runs/ui/run_detail_tab_bodies.dart index 134ba8a1..a6377a0a 100644 --- a/app/lib/features/runs/ui/run_detail_tab_bodies.dart +++ b/app/lib/features/runs/ui/run_detail_tab_bodies.dart @@ -107,7 +107,12 @@ Widget runDetailSummaryTab({ title: 'Output', controller: outputController, copyText: runFieldCopyText(run['output']), - body: RunFieldBody(value: run['output'], empty: visitEmptyOutput), + // Output starts open, so it is a sliver: a long one builds only the + // fields on screen. + sliverBody: RunFieldSliver( + value: run['output'], + empty: visitEmptyOutput, + ), ), const SliverToBoxAdapter(child: SizedBox(height: 16)), const SliverFloatingBarClearance(), @@ -115,19 +120,25 @@ Widget runDetailSummaryTab({ ); } -/// A summary section that starts closed, follows its [controller] (so a -/// search hit can open it), and offers a copy of its recorded text. +/// A summary section that follows its [controller] (its open state starts from +/// the controller's; a search hit can open it), and offers a copy of its +/// recorded text. class _StickyField extends StatefulWidget { const _StickyField({ super.key, required this.title, - required this.body, + this.body, + this.sliverBody, this.controller, this.copyText, - }); + }) : assert((body == null) != (sliverBody == null)); final String title; - final Widget body; + + /// The content as a box, or as [sliverBody] for a long one (see + /// [StickySection.sliverBody]); exactly one is given. + final Widget? body; + final Widget? sliverBody; final ExpansibleController? controller; final String? copyText; @@ -158,25 +169,31 @@ class _StickyFieldState extends State<_StickyField> { final copyText = widget.copyText; return ListenableBuilder( listenable: _controller, - builder: (context, _) => StickySection( - title: widget.title, - open: _controller.isExpanded, - onToggle: () => _controller.isExpanded - ? _controller.collapse() - : _controller.expand(), - trailing: [ - if (copyText != null && copyText.isNotEmpty) - IconButton( - tooltip: 'Copy ${widget.title}', - onPressed: _copy, - icon: Icon(_copied ? Icons.check : Icons.copy), - ), - ], - body: Padding( - padding: const EdgeInsets.fromLTRB(16, 0, 16, 16), - child: widget.body, - ), - ), + builder: (context, _) { + // The body's own padding, the same for the box and the sliver form. + const padding = EdgeInsets.fromLTRB(16, 0, 16, 16); + final box = widget.body; + final sliver = widget.sliverBody; + return StickySection( + title: widget.title, + open: _controller.isExpanded, + onToggle: () => _controller.isExpanded + ? _controller.collapse() + : _controller.expand(), + trailing: [ + if (copyText != null && copyText.isNotEmpty) + IconButton( + tooltip: 'Copy ${widget.title}', + onPressed: _copy, + icon: Icon(_copied ? Icons.check : Icons.copy), + ), + ], + body: box == null ? null : Padding(padding: padding, child: box), + sliverBody: sliver == null + ? null + : SliverPadding(padding: padding, sliver: sliver), + ); + }, ); } } diff --git a/app/lib/features/runs/ui/run_detail_tabs.dart b/app/lib/features/runs/ui/run_detail_tabs.dart index d303ba93..940078a6 100644 --- a/app/lib/features/runs/ui/run_detail_tabs.dart +++ b/app/lib/features/runs/ui/run_detail_tabs.dart @@ -98,12 +98,13 @@ class _RunDetailTabsState extends State { Route? _visitRoute; late final ValueNotifier _liveRun = ValueNotifier(widget.run); - /// The Summary's collapsible Input and Output sections. A search text hit - /// expands the one its recorded field names, exactly as the browser opens the - /// matching Summary section. The detail owns them so the tab body stays a - /// presentation widget. + /// The Summary's collapsible Input and Output sections. Output starts open + /// and Input starts closed; the operator may close either for this view. A + /// search text hit expands the one its recorded field names, exactly as the + /// browser opens the matching Summary section. The detail owns them so the + /// tab body stays a presentation widget. final _inputSection = ExpansibleController(); - final _outputSection = ExpansibleController(); + final _outputSection = ExpansibleController()..expand(); /// The search request last applied by this detail, so a rebuild of the same /// request never reopens a pane the operator closed in the meantime. @@ -124,6 +125,12 @@ class _RunDetailTabsState extends State { _applySearchSelection(); } + /// The Summary's default sections: Input closed, Output open. + void _resetSummarySections() { + _inputSection.collapse(); + _outputSection.expand(); + } + @override void dispose() { _inputSection.dispose(); @@ -146,8 +153,7 @@ class _RunDetailTabsState extends State { _tab = RunDetailTab.summary; _selectedStage = null; _selectedVisit = null; - _inputSection.collapse(); - _outputSection.collapse(); + _resetSummarySections(); _applyInitialVisit(); } else if (!sameTarget) { // A route that names another stage or visit is applied to the same run. @@ -231,10 +237,10 @@ class _RunDetailTabsState extends State { case RunSummarySection.output: _outputSection.expand(); case null: - // A hit that names no section must not leave a previously expanded - // one open; the Summary panel starts collapsed. - _inputSection.collapse(); - _outputSection.collapse(); + // A hit that names no section must not leave a previously toggled + // one in a state the operator did not open; the Summary returns to + // its default sections. + _resetSummarySections(); } case RunVisitTarget(:final stageKey, :final timelineIndex): if (detailVisitStepAt(widget.run, timelineIndex) == null) return; diff --git a/app/lib/features/runs/ui/run_detail_visit_sections.dart b/app/lib/features/runs/ui/run_detail_visit_sections.dart index df811ae2..27b364fd 100644 --- a/app/lib/features/runs/ui/run_detail_visit_sections.dart +++ b/app/lib/features/runs/ui/run_detail_visit_sections.dart @@ -111,7 +111,8 @@ Widget runVisitSectionBody({ ); switch (section) { case RunVisitSection.summary: - // Input then Output, each a sticky collapsible with a copy button. + // Input then Output, each a sticky collapsible with a copy button; Output + // starts open. return _VisitSummary( key: ValueKey('run-visit-summary-$visitIndex'), input: step['input'], @@ -181,7 +182,9 @@ class _VisitSummary extends StatefulWidget { } class _VisitSummaryState extends State<_VisitSummary> { - final Set _closed = {'Input', 'Output'}; + /// The sections the operator has closed. Input starts closed; Output starts + /// open, and this set is per visit view. + final Set _closed = {'Input'}; String? _copied; Future _copy(String name, dynamic value) async { @@ -189,7 +192,14 @@ class _VisitSummaryState extends State<_VisitSummary> { if (mounted) setState(() => _copied = name); } - Widget _section(String name, dynamic value, String empty) { + /// [lazy] builds the field as a sliver, for a section open by default (the + /// Output): a long one then lays out only the fields on screen. + Widget _section( + String name, + dynamic value, + String empty, { + bool lazy = false, + }) { final copy = IconButton( key: ValueKey('run-visit-copy-$name'), tooltip: 'Copy $name', @@ -197,6 +207,7 @@ class _VisitSummaryState extends State<_VisitSummary> { icon: Icon(_copied == name ? Icons.check : Icons.copy), ); final open = !_closed.contains(name); + const padding = EdgeInsets.fromLTRB(16, 0, 16, 16); return StickySection( key: ValueKey('run-visit-section-$name'), title: name, @@ -205,10 +216,18 @@ class _VisitSummaryState extends State<_VisitSummary> { if (!_closed.remove(name)) _closed.add(name); }), trailing: [copy], - body: Padding( - padding: const EdgeInsets.fromLTRB(16, 0, 16, 16), - child: RunFieldBody(value: value, empty: empty), - ), + body: lazy + ? null + : Padding( + padding: padding, + child: RunFieldBody(value: value, empty: empty), + ), + sliverBody: lazy + ? SliverPadding( + padding: padding, + sliver: RunFieldSliver(value: value, empty: empty), + ) + : null, ); } @@ -221,7 +240,7 @@ class _VisitSummaryState extends State<_VisitSummary> { const SliverTopBarClearance(), if (widget.facts case final facts?) SliverToBoxAdapter(child: facts), _section('Input', widget.input, visitEmptyInput), - _section('Output', widget.output, visitEmptyOutput), + _section('Output', widget.output, visitEmptyOutput, lazy: true), const SliverFloatingBarClearance(), ], ); diff --git a/app/lib/features/runs/ui/run_field_body.dart b/app/lib/features/runs/ui/run_field_body.dart index d1ce93ad..355539b0 100644 --- a/app/lib/features/runs/ui/run_field_body.dart +++ b/app/lib/features/runs/ui/run_field_body.dart @@ -55,40 +55,99 @@ class RunFieldBody extends StatelessWidget { @override Widget build(BuildContext context) { - final map = value is Map ? Map.from(value as Map) : null; - if (map == null || map.isEmpty) return _plain(empty); - if (map.length == 1 && map.keys.single.toLowerCase() == 'markdown') { - return _value(runFieldText(map.values.single)); + final map = _runFieldMap(value); + if (map == null || map.isEmpty) { + return _runFieldPlain(empty, textBuilder); + } + if (_isMarkdownDocument(map)) { + return _runFieldValue(runFieldText(map.values.single), textBuilder); } - final caption = Theme.of(context).textTheme.labelMedium?.copyWith( - fontWeight: FontWeight.w600, - color: Theme.of(context).colorScheme.onSurfaceVariant, - ); return Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ for (final (index, entry) in map.entries.indexed) - Padding( - padding: EdgeInsets.only(top: index == 0 ? 0 : 12), - child: Column( - crossAxisAlignment: CrossAxisAlignment.start, - children: [ - Text( - entry.key.trim().isEmpty ? 'value' : entry.key, - style: caption, - ), - const SizedBox(height: 2), - _value(runFieldText(entry.value)), - ], - ), - ), + _runFieldRow(context, index, entry, textBuilder), ], ); } - - Widget _value(String text) => runFieldLooksLikeMarkdown(text) - ? ChatMarkdownView(text: text) - : _plain(text); - - Widget _plain(String text) => textBuilder?.call(text) ?? SelectableText(text); } + +/// [RunFieldBody] as a sliver, for a section of a [CustomScrollView] that is +/// open by default. A field map builds and lays out only the fields on screen, +/// however many there are, so a long Output does not cost a full layout when +/// its section opens. Its rows take the full width the sliver gives them; the +/// host pads it. +class RunFieldSliver extends StatelessWidget { + const RunFieldSliver({ + super.key, + required this.value, + required this.empty, + this.textBuilder, + }); + + final dynamic value; + final String empty; + + /// Draws a plain value; the host's selectable text by default. + final Widget Function(String text)? textBuilder; + + @override + Widget build(BuildContext context) { + final map = _runFieldMap(value); + if (map == null || map.isEmpty || _isMarkdownDocument(map)) { + return SliverToBoxAdapter( + child: RunFieldBody( + value: value, + empty: empty, + textBuilder: textBuilder, + ), + ); + } + final entries = map.entries.toList(growable: false); + return SliverList.builder( + itemCount: entries.length, + itemBuilder: (context, index) => + _runFieldRow(context, index, entries[index], textBuilder), + ); + } +} + +Map? _runFieldMap(dynamic value) => + value is Map ? Map.from(value) : null; + +/// A lone `markdown` field, shown as the document itself. +bool _isMarkdownDocument(Map map) => + map.length == 1 && map.keys.single.toLowerCase() == 'markdown'; + +/// One recorded field: its name, then its value. +Widget _runFieldRow( + BuildContext context, + int index, + MapEntry entry, + Widget Function(String text)? textBuilder, +) { + final theme = Theme.of(context); + final caption = theme.textTheme.labelMedium?.copyWith( + fontWeight: FontWeight.w600, + color: theme.colorScheme.onSurfaceVariant, + ); + return Padding( + padding: EdgeInsets.only(top: index == 0 ? 0 : 12), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text(entry.key.trim().isEmpty ? 'value' : entry.key, style: caption), + const SizedBox(height: 2), + _runFieldValue(runFieldText(entry.value), textBuilder), + ], + ), + ); +} + +Widget _runFieldValue(String text, Widget Function(String text)? textBuilder) => + runFieldLooksLikeMarkdown(text) + ? ChatMarkdownView(text: text) + : _runFieldPlain(text, textBuilder); + +Widget _runFieldPlain(String text, Widget Function(String text)? textBuilder) => + textBuilder?.call(text) ?? SelectableText(text); diff --git a/app/lib/features/settings/keyboard_shortcuts_registry.dart b/app/lib/features/settings/keyboard_shortcuts_registry.dart index 22f12a9d..85f3d2f0 100644 --- a/app/lib/features/settings/keyboard_shortcuts_registry.dart +++ b/app/lib/features/settings/keyboard_shortcuts_registry.dart @@ -5,6 +5,7 @@ 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_runs_pipelines_shortcut.dart'; import '../../shell/shell_search_shortcut_labels.dart'; /// A shortcut entry shown in the in-app help. Keeping these entries together @@ -61,6 +62,12 @@ class KeyboardShortcutRegistry { ? '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( + 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: diff --git a/app/lib/features/settings/settings_keys.dart b/app/lib/features/settings/settings_keys.dart index 337757ff..6c4e868b 100644 --- a/app/lib/features/settings/settings_keys.dart +++ b/app/lib/features/settings/settings_keys.dart @@ -13,4 +13,5 @@ abstract final class SettingsKeys { static const keyboardShortcuts = ValueKey( 'settings.keyboardShortcuts', ); + static const walkthrough = ValueKey('settings.walkthrough'); } diff --git a/app/lib/features/settings/settings_screen.dart b/app/lib/features/settings/settings_screen.dart index 1e63875d..ce8f097b 100644 --- a/app/lib/features/settings/settings_screen.dart +++ b/app/lib/features/settings/settings_screen.dart @@ -37,6 +37,7 @@ import 'server_connections.dart'; import 'saved_servers_section.dart'; import 'managed_connection_section.dart'; import 'settings_keyboard_shortcuts_section.dart'; +import 'settings_walkthrough_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 8d89bd49..7dee4895 100644 --- a/app/lib/features/settings/settings_topic_pages.dart +++ b/app/lib/features/settings/settings_topic_pages.dart @@ -85,7 +85,10 @@ extension _SettingsTopicPages on _SettingsScreenState { SettingsGroup( title: 'Help', leadingRows: true, - children: const [SettingsKeyboardShortcutsSection()], + children: const [ + SettingsKeyboardShortcutsSection(), + SettingsWalkthroughSection(), + ], ), if (widget.onOpenSchedules case final open?) SettingsGroup( diff --git a/app/lib/features/settings/settings_walkthrough_section.dart b/app/lib/features/settings/settings_walkthrough_section.dart new file mode 100644 index 00000000..5d31e398 --- /dev/null +++ b/app/lib/features/settings/settings_walkthrough_section.dart @@ -0,0 +1,23 @@ +import 'package:flutter/material.dart'; + +import '../walkthrough/first_run_walkthrough.dart'; +import 'settings_keys.dart'; +import 'settings_row.dart'; + +/// Reopens the first-run walkthrough. It only shows the walkthrough; it never +/// changes the device's seen record. +class SettingsWalkthroughSection extends StatelessWidget { + const SettingsWalkthroughSection({super.key}); + + @override + Widget build(BuildContext context) => SettingsRow( + key: SettingsKeys.walkthrough, + leading: const Icon(Icons.school_outlined), + title: const Text('Show the walkthrough'), + subtitle: const Text( + 'Four short steps: connect, set up an agent, run, chat.', + ), + chevron: true, + onTap: () => showFirstRunWalkthrough(context), + ); +} diff --git a/app/lib/features/walkthrough/first_run_walkthrough.dart b/app/lib/features/walkthrough/first_run_walkthrough.dart new file mode 100644 index 00000000..bedcbcac --- /dev/null +++ b/app/lib/features/walkthrough/first_run_walkthrough.dart @@ -0,0 +1,183 @@ +import 'package:flutter/material.dart'; + +import '../../ui/adaptive/app_popups.dart'; +import 'walkthrough_harness_command.dart'; +import 'walkthrough_steps.dart'; + +/// Opens the walkthrough as a Material details sheet on phones and a dialog on +/// wide windows. [onClosed] runs once however it closes (Skip, Done, the close +/// button or a tap outside), so the caller can record it as seen. +Future showFirstRunWalkthrough( + BuildContext context, { + Future Function()? onClosed, +}) async { + await showAppDetails( + context, + maxWidth: 560, + builder: (sheet) => + FirstRunWalkthrough(onClose: () => Navigator.of(sheet).pop()), + ); + await onClosed?.call(); +} + +/// The four-page stepper: Back and Next between pages, Skip on every page and +/// Done on the last. Every control is a standard Material button; the layout +/// wraps rather than clipping at large text scales. +class FirstRunWalkthrough extends StatefulWidget { + const FirstRunWalkthrough({ + super.key, + required this.onClose, + this.steps = walkthroughSteps, + }); + + /// Called by Skip, Done and the close button. + final VoidCallback onClose; + final List steps; + + @override + State createState() => _FirstRunWalkthroughState(); +} + +class _FirstRunWalkthroughState extends State { + int _index = 0; + + bool get _last => _index == widget.steps.length - 1; + + void _back() => setState(() => _index = _index > 0 ? _index - 1 : 0); + + void _next() => setState(() => _index = _last ? _index : _index + 1); + + @override + Widget build(BuildContext context) { + final step = widget.steps[_index]; + final theme = Theme.of(context); + final content = Semantics( + scopesRoute: true, + namesRoute: true, + explicitChildNodes: true, + label: 'Pipelines walkthrough', + child: Padding( + padding: const EdgeInsets.fromLTRB(24, 8, 24, 24), + child: Column( + mainAxisSize: MainAxisSize.min, + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Text( + 'Step ${_index + 1} of ${widget.steps.length}', + key: const ValueKey('walkthrough.progress'), + style: theme.textTheme.labelLarge, + ), + const SizedBox(height: 8), + LinearProgressIndicator(value: (_index + 1) / widget.steps.length), + const SizedBox(height: 20), + Row( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Icon(step.icon, color: theme.colorScheme.primary), + const SizedBox(width: 12), + Expanded( + child: Text( + step.title, + key: ValueKey('walkthrough.title.$_index'), + style: theme.textTheme.headlineSmall, + ), + ), + ], + ), + const SizedBox(height: 12), + Text(step.body, style: theme.textTheme.bodyLarge), + for (final point in step.points) ...[ + const SizedBox(height: 8), + _Point(text: point), + ], + if (step.showsHarnessCommand) ...[ + const SizedBox(height: 16), + const WalkthroughHarnessCommand(), + ], + const SizedBox(height: 24), + _Footer( + last: _last, + canGoBack: _index > 0, + onBack: _back, + onNext: _last ? widget.onClose : _next, + onSkip: widget.onClose, + ), + ], + ), + ), + ); + // A wide window wraps the sheet's content in its own scroll view; a phone + // sheet does not, so the page scrolls here at large text scales. + return usesDesktopPopups(context) + ? content + : SingleChildScrollView(child: content); + } +} + +class _Point extends StatelessWidget { + const _Point({required this.text}); + + final String text; + + @override + Widget build(BuildContext context) => Row( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + const Padding( + padding: EdgeInsets.only(top: 2), + child: Icon(Icons.circle, size: 6), + ), + const SizedBox(width: 12), + Expanded( + child: Text(text, style: Theme.of(context).textTheme.bodyMedium), + ), + ], + ); +} + +class _Footer extends StatelessWidget { + const _Footer({ + required this.last, + required this.canGoBack, + required this.onBack, + required this.onNext, + required this.onSkip, + }); + + final bool last; + final bool canGoBack; + final VoidCallback onBack; + final VoidCallback onNext; + final VoidCallback onSkip; + + @override + Widget build(BuildContext context) => Wrap( + alignment: WrapAlignment.spaceBetween, + crossAxisAlignment: WrapCrossAlignment.center, + spacing: 8, + runSpacing: 8, + children: [ + TextButton( + key: const ValueKey('walkthrough.skip'), + onPressed: onSkip, + child: const Text('Skip'), + ), + Wrap( + spacing: 8, + runSpacing: 8, + children: [ + TextButton( + key: const ValueKey('walkthrough.back'), + onPressed: canGoBack ? onBack : null, + child: const Text('Back'), + ), + FilledButton( + key: const ValueKey('walkthrough.next'), + onPressed: onNext, + child: Text(last ? 'Done' : 'Next'), + ), + ], + ), + ], + ); +} diff --git a/app/lib/features/walkthrough/walkthrough_gate.dart b/app/lib/features/walkthrough/walkthrough_gate.dart new file mode 100644 index 00000000..a560ece8 --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_gate.dart @@ -0,0 +1,200 @@ +import 'dart:async'; + +import 'package:flutter/widgets.dart'; + +import '../../core/api_gateway.dart'; +import 'first_run_walkthrough.dart'; +import 'walkthrough_store.dart'; + +/// Reports whether the server has no pipelines, runs or chats yet. Returns null +/// when any of the three lists cannot be read, so an unreadable server never +/// triggers the walkthrough. +Future serverHasNoWorkYet(ApiGateway? gateway) async { + if (gateway == null) return null; + try { + final replies = await Future.wait(>[ + gateway.call('list_pipelines', {'include_archived': true}), + gateway.call('list_runs'), + gateway.call('chat_sessions'), + ]); + final lists = [ + replies[0]['pipelines'], + replies[1]['runs'], + replies[2]['chat_sessions'], + ]; + if (lists.any((list) => list is! List)) return null; + return lists.every((list) => (list as List).isEmpty); + } catch (_) { + return null; + } +} + +/// Offers the walkthrough from the Pipelines page, which is the first screen a +/// new user sees. It is offered when: +/// +/// * the device has not finished or skipped it yet (first launch, once); or +/// * the device already has, and the connected server has no pipelines, runs +/// or chats, and that server has not been offered it before. +/// +/// The server check needs a connected session. While disconnected it waits, and +/// it runs again on each new connection until the server answers. A check that +/// cannot read the server leaves the gate open to retry; a decided check (the +/// walkthrough shown, or the server has work) ends it for this mount. +/// +/// Nothing is shown while the store cannot be read, because an unavailable +/// store reports "seen". The check runs only while [enabled] (the Pipelines tab +/// is the one showing). +class FirstRunWalkthroughGate extends StatefulWidget { + const FirstRunWalkthroughGate({ + super.key, + required this.child, + required this.store, + required this.enabled, + required this.serverScope, + required this.connection, + required this.connected, + this.gateway, + }); + + final Widget child; + final WalkthroughStore store; + + /// Whether the Pipelines page is the one showing. + final bool enabled; + + /// The connected server's scope, recorded when the walkthrough is offered. + final String serverScope; + + /// Notifies when the connection may have changed; the gate re-reads + /// [connected] on each notification. + final Listenable connection; + + /// Whether the server session is connected right now. + final bool Function() connected; + + /// The connected server's gateway, used for the empty-server check. + final ApiGateway? gateway; + + @override + State createState() => + _FirstRunWalkthroughGateState(); +} + +class _FirstRunWalkthroughGateState extends State { + /// The offer is decided for this mount: shown, or nothing left to offer. + bool _decided = false; + + /// An offer is in flight. + bool _running = false; + + /// A new connection arrived while an offer was in flight. + bool _connectedAgain = false; + late bool _wasConnected; + + @override + void initState() { + super.initState(); + _wasConnected = widget.connected(); + widget.connection.addListener(_onConnectionChanged); + _scheduleIfEnabled(); + } + + @override + void didUpdateWidget(FirstRunWalkthroughGate oldWidget) { + super.didUpdateWidget(oldWidget); + if (oldWidget.connection != widget.connection) { + oldWidget.connection.removeListener(_onConnectionChanged); + widget.connection.addListener(_onConnectionChanged); + } + _scheduleIfEnabled(); + } + + @override + void dispose() { + widget.connection.removeListener(_onConnectionChanged); + super.dispose(); + } + + /// Acts only on a disconnected-to-connected transition, so frequent session + /// notifications while connected never repeat the server check. + void _onConnectionChanged() { + final connected = widget.connected(); + final became = connected && !_wasConnected; + _wasConnected = connected; + if (!became || _decided) return; + if (_running) { + _connectedAgain = true; + return; + } + _scheduleIfEnabled(); + } + + void _scheduleIfEnabled() { + if (_decided || _running || !widget.enabled) return; + _running = true; + // A connection can arrive between frames; the post-frame callback needs a + // frame, so request one explicitly. + WidgetsBinding.instance.addPostFrameCallback((_) { + if (!_active) { + // Pipelines is hidden (or the gate is gone): release the flag so a + // later enable reschedules the offer through didUpdateWidget. + _running = false; + return; + } + unawaited(_runOffer()); + }); + WidgetsBinding.instance.ensureVisualUpdate(); + } + + /// The gate may offer only while mounted and while the Pipelines page is the + /// one showing. Checked after every await and before every show. + bool get _active => mounted && widget.enabled; + + Future _runOffer() async { + try { + await _offer(); + } finally { + _running = false; + final again = _connectedAgain; + _connectedAgain = false; + if (again && !_decided) _scheduleIfEnabled(); + } + } + + Future _offer() async { + final seen = await widget.store.isSeen(); + if (!_active) return; + if (!seen) { + _decided = true; + await _showIfActive(); + return; + } + if (await widget.store.wasOffered(widget.serverScope)) { + if (!_active) return; + _decided = true; + return; + } + // Wait for a connection; the connection listener runs the check again. + if (!widget.connected()) return; + final empty = await serverHasNoWorkYet(widget.gateway); + if (!_active) return; + // Unreadable: stay open so the next connection retries the check. + if (empty == null) return; + _decided = true; + if (!empty) return; + await widget.store.markOffered(widget.serverScope); + await _showIfActive(); + } + + Future _showIfActive() async { + if (!_active) return; + await _show(); + } + + Future _show() async { + await showFirstRunWalkthrough(context, onClosed: widget.store.markSeen); + } + + @override + Widget build(BuildContext context) => widget.child; +} diff --git a/app/lib/features/walkthrough/walkthrough_harness_command.dart b/app/lib/features/walkthrough/walkthrough_harness_command.dart new file mode 100644 index 00000000..7e560449 --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_harness_command.dart @@ -0,0 +1,86 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; + +import 'walkthrough_steps.dart'; + +/// The harness page's command: an agent picker and the one command it selects, +/// with a single copy button for that command. +class WalkthroughHarnessCommand extends StatefulWidget { + const WalkthroughHarnessCommand({super.key}); + + @override + State createState() => + _WalkthroughHarnessCommandState(); +} + +class _WalkthroughHarnessCommandState extends State { + String _agent = harnessAgents.first; + bool _copied = false; + + Future _copy(String command) async { + try { + await Clipboard.setData(ClipboardData(text: command)); + } catch (_) { + // The command stays selectable, so a failed copy never claims success. + return; + } + if (!mounted) return; + setState(() => _copied = true); + } + + @override + Widget build(BuildContext context) { + final scheme = Theme.of(context).colorScheme; + final command = harnessSetupCommand(_agent); + return Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Text('Agent', style: Theme.of(context).textTheme.labelLarge), + const SizedBox(height: 8), + Wrap( + spacing: 8, + runSpacing: 8, + children: [ + for (final agent in harnessAgents) + ChoiceChip( + key: ValueKey('walkthrough.agent.$agent'), + label: Text(agent), + selected: agent == _agent, + onSelected: (_) => setState(() { + _agent = agent; + _copied = false; + }), + ), + ], + ), + const SizedBox(height: 12), + DecoratedBox( + decoration: BoxDecoration( + color: scheme.surfaceContainerHighest, + borderRadius: BorderRadius.circular(12), + ), + child: Padding( + padding: const EdgeInsets.only(left: 12, right: 4), + child: Row( + children: [ + Expanded( + child: SelectableText( + command, + key: const ValueKey('walkthrough.command'), + style: Theme.of(context).textTheme.bodyLarge, + ), + ), + IconButton( + key: const ValueKey('walkthrough.copy'), + tooltip: _copied ? 'Command copied' : 'Copy command', + onPressed: () => _copy(command), + icon: Icon(_copied ? Icons.check : Icons.copy_outlined), + ), + ], + ), + ), + ), + ], + ); + } +} diff --git a/app/lib/features/walkthrough/walkthrough_steps.dart b/app/lib/features/walkthrough/walkthrough_steps.dart new file mode 100644 index 00000000..aa45ea1c --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_steps.dart @@ -0,0 +1,79 @@ +import 'package:flutter/material.dart'; + +/// One page of the first-run walkthrough. Pure content: no widgets, so the +/// copy can be checked without pumping a tree. +class WalkthroughStep { + const WalkthroughStep({ + required this.icon, + required this.title, + required this.body, + this.points = const [], + this.showsHarnessCommand = false, + }); + + final IconData icon; + final String title; + final String body; + + /// Short labelled facts shown under the body, one per line. + final List points; + + /// Whether this page shows the harness setup command picker. + final bool showsHarnessCommand; +} + +/// The agents `pipelines harness setup` accepts, in the order they are offered. +const harnessAgents = ['claude', 'codex', 'opencode', 'pi']; + +/// The command for [agent], exactly as a terminal should run it. +String harnessSetupCommand(String agent) => 'pipelines harness setup $agent'; + +/// The four walkthrough pages, in order. +const walkthroughSteps = [ + WalkthroughStep( + icon: Icons.hub_outlined, + title: 'Welcome to Pipelines', + body: + 'Pipelines runs reusable AI workflows and holds chats with coding ' + 'agents. Both live on your server, so start by connecting this app ' + 'to it.', + points: [ + 'Pipelines: workflows you define once and run again.', + 'Chats: conversations with coding agents on the server.', + 'Connect: open Settings, then Connection, enter the Server URL and ' + 'choose Connect.', + ], + ), + WalkthroughStep( + icon: Icons.build_circle_outlined, + title: 'Set up an agent harness', + body: + 'A harness lets Pipelines drive a coding agent. Choose the agent you ' + 'use, then run its setup command in a terminal.', + showsHarnessCommand: true, + ), + WalkthroughStep( + icon: Icons.play_circle_outline, + title: 'Start a run', + body: + 'Pipelines shows your workflows. Runs shows every run with its ' + 'progress and results.', + points: [ + 'Pipelines tab: open a workflow and fill in its inputs.', + 'Runs tab: follow a run as it works, then read what it produced.', + 'Choose Run on a workflow to start one.', + ], + ), + WalkthroughStep( + icon: Icons.forum_outlined, + title: 'Chat with an agent', + body: + 'The Chat tab lists your conversations. Open one to read the thread ' + 'and reply.', + points: [ + 'Float: pop a chat into its own window while you work elsewhere.', + 'Terminal: open a terminal beside the Chat tab for direct commands.', + 'New chat starts a conversation with an agent.', + ], + ), +]; diff --git a/app/lib/features/walkthrough/walkthrough_store.dart b/app/lib/features/walkthrough/walkthrough_store.dart new file mode 100644 index 00000000..01332fda --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_store.dart @@ -0,0 +1,118 @@ +import 'package:shared_preferences/shared_preferences.dart'; + +/// The device-level key for "the first-run walkthrough was finished or skipped". +/// It is per device, not per server, so a new server never repeats it. +const String walkthroughSeenKey = 'pipelines.next.firstRunWalkthrough.v1'; + +/// The key listing the server scopes that were already offered the walkthrough +/// because they had no pipelines, runs or chats yet. +const String walkthroughOfferedKey = 'pipelines.next.walkthroughOffered.v1'; + +/// The persistence seam for the walkthrough. A store that cannot be read or +/// written reports "seen" and "offered", so an unavailable store never nags. +abstract interface class WalkthroughStore { + Future isSeen(); + + Future markSeen(); + + Future wasOffered(String serverScope); + + Future markOffered(String serverScope); +} + +Future _openPreferences() async { + try { + return await SharedPreferences.getInstance(); + } catch (_) { + return null; + } +} + +/// `shared_preferences`-backed storage under the `pipelines.next` keys. +/// +/// [open] is the seam for an unavailable platform store (tests pass one that +/// yields null); production opens the real preferences. +class SharedPreferencesWalkthroughStore implements WalkthroughStore { + const SharedPreferencesWalkthroughStore({this.open = _openPreferences}); + + final Future Function() open; + + Future _preferences() => open(); + + @override + Future isSeen() async { + final preferences = await _preferences(); + if (preferences == null) return true; + try { + return preferences.getBool(walkthroughSeenKey) ?? false; + } catch (_) { + return true; + } + } + + @override + Future markSeen() async { + final preferences = await _preferences(); + if (preferences == null) return; + try { + await preferences.setBool(walkthroughSeenKey, true); + } catch (_) { + // Nothing to report: the walkthrough is still dismissed for this run. + } + } + + @override + Future wasOffered(String serverScope) async { + final preferences = await _preferences(); + if (preferences == null) return true; + try { + final offered = preferences.getStringList(walkthroughOfferedKey); + return offered?.contains(serverScope) ?? false; + } catch (_) { + return true; + } + } + + @override + Future markOffered(String serverScope) async { + final preferences = await _preferences(); + if (preferences == null) return; + try { + final offered = { + ...?preferences.getStringList(walkthroughOfferedKey), + serverScope, + }; + await preferences.setStringList(walkthroughOfferedKey, offered.toList()); + } catch (_) { + // A failed write only means the offer may show again later. + } + } +} + +/// An in-memory store for tests and previews. It never touches the platform +/// store, so a fixture cannot mark a real device as seen. +class MemoryWalkthroughStore implements WalkthroughStore { + MemoryWalkthroughStore({this.seen = false, Set? offered}) + : _offered = {...?offered}; + + /// Whether the walkthrough is marked seen. + bool seen; + final Set _offered; + + /// The server scopes already offered the walkthrough. + Set get offered => Set.unmodifiable(_offered); + + @override + Future isSeen() async => seen; + + @override + Future markSeen() async => seen = true; + + @override + Future wasOffered(String serverScope) async => + _offered.contains(serverScope); + + @override + Future markOffered(String serverScope) async => + _offered.add(serverScope); +} diff --git a/app/lib/shell/adaptive_shell.dart b/app/lib/shell/adaptive_shell.dart index 60a97fa4..e37da7b4 100644 --- a/app/lib/shell/adaptive_shell.dart +++ b/app/lib/shell/adaptive_shell.dart @@ -7,10 +7,13 @@ import '../ui/adaptive/floating_destination_bar.dart'; import 'attention_badge.dart'; import 'destination.dart'; import 'list_detail.dart'; +import 'navigation_rail.dart'; +import 'shell_rail_scope.dart'; import 'list_pane_widths.dart'; import 'shell_bar.dart'; import 'shell_chat_shortcut.dart'; import 'shell_list_shortcuts.dart'; +import 'shell_runs_pipelines_shortcut.dart'; import 'shell_search_shortcut_labels.dart'; import 'tab_history.dart'; import '../ui/input/keyboard_owner.dart'; @@ -223,7 +226,8 @@ class _AdaptiveShellState extends State { ); // The scaffolds below swap the system insets for their bars' // heights; panes beside a list read the real ones from here. - final system = MediaQuery.paddingOf(context); + final media = MediaQuery.of(context); + final system = media.padding; // A page (Settings) closes to Pipelines on the system Back too; at a // tab's root Back returns to the tab opened before it. Only with neither // does Back reach the platform, so Android's (predictive) Back closes the @@ -237,15 +241,60 @@ class _AdaptiveShellState extends State { }, child: child, ); + // On a wide window the destinations sit in a rail at the left edge, and + // the floating bar is not built; the scaffold gets the rest of the window. + // The tree has the same shape at every width (an empty rail slot on a + // phone), so resizing across the rail's threshold never remounts a + // destination. + final rail = showsNavigationRail(context); + final scaffold = Scaffold( + extendBodyBehindAppBar: true, + appBar: topBar, + body: _destinationStack(contents), + extendBody: true, + bottomNavigationBar: rail ? null : bar, + ); return backable( ShellSystemInsets( padding: system, - child: Scaffold( - extendBodyBehindAppBar: true, - appBar: topBar, - body: _destinationStack(contents), - extendBody: true, - bottomNavigationBar: bar, + child: Row( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + // Badges (running runs, unread chats) rebuild the rail alone. + ListenableBuilder( + listenable: _bar.badges, + builder: (context, _) => rail + ? ShellNavigationRail( + selected: _selected, + icon: (destination) => _icon( + destination, + destinationDetails(destination).icon, + ), + onSelected: _select, + padding: EdgeInsets.only( + top: system.top, + bottom: system.bottom, + ), + ) + : const SizedBox.shrink(), + ), + // Three children at every width, so the body keeps its slot. + rail + ? const VerticalDivider(width: 1, thickness: 1) + : const SizedBox.shrink(), + Expanded( + // Beside the rail the panes lay out in the width the rail leaves, + // which the window's width fixes here (not in a layout pass), so + // the panes and their pages rebuild with the window. + child: ShellRailScope( + shown: rail, + bodyWidth: rail + ? media.size.width - kNavigationRailSpace + : null, + child: scaffold, + ), + ), + ], ), ), ); @@ -274,8 +323,9 @@ class _AdaptiveShellState extends State { } /// App-wide search and conversation-list selection are handled before text - /// fields. Split-pane navigation belongs to the chat workspace; tab changes - /// have no global keyboard chord. + /// fields. Split-pane navigation belongs to the chat workspace. Ctrl+A + /// bounces between Runs and Pipelines, but leaves text fields and the + /// terminal their own Ctrl+A (select all, line start). bool _handleDestinationKeyEvent(KeyEvent event) { final keyboard = HardwareKeyboard.instance; // Ctrl+K is the terminal's kill-line while the terminal has the keyboard; @@ -285,6 +335,13 @@ class _AdaptiveShellState extends State { if (event is KeyDownEvent) _openChat(); return true; } + if (shellRunsPipelinesShortcut(event, keyboard)) { + if (primaryFocusTakesTyping()) return false; + if (event is KeyDownEvent) { + _select(shellRunsPipelinesTarget(_selected)); + } + return true; + } // A terminal keeps its keys (Escape, Ctrl+/, Ctrl+digits). if (primaryFocusIsTypingSurface()) return false; if (_selected == AppDestination.search && diff --git a/app/lib/shell/destination.dart b/app/lib/shell/destination.dart index a62eb13e..9fe91835 100644 --- a/app/lib/shell/destination.dart +++ b/app/lib/shell/destination.dart @@ -2,9 +2,10 @@ import 'package:flutter/material.dart'; enum AppDestination { pipelines, runs, chat, search, settings } -/// The destinations the shell's tab bar offers, in order. Settings is a -/// destination the shell can show (its route is `/settings`), but it opens -/// as a page from the Pipelines bar's gear instead of being a tab. +/// The destinations the shell's tab bar (or, on a wide window, its rail) offers, +/// in order. Settings is a destination the shell can show (its route is +/// `/settings`), but it opens as a page, from the rail's foot on a wide window +/// or the Pipelines bar's gear on a phone, instead of being a tab. const List shellTabDestinations = [ AppDestination.pipelines, AppDestination.runs, diff --git a/app/lib/shell/list_detail.dart b/app/lib/shell/list_detail.dart index 13a0a3cd..ce992640 100644 --- a/app/lib/shell/list_detail.dart +++ b/app/lib/shell/list_detail.dart @@ -7,6 +7,7 @@ import 'detail_pane_navigator.dart'; import 'list_detail_policy.dart'; import 'list_pane_divider.dart'; import 'list_pane_widths.dart'; +import 'shell_rail_scope.dart'; import 'shell_bar.dart'; export 'list_detail_policy.dart'; @@ -64,7 +65,7 @@ class ListPaneWidth extends StatelessWidget { builder: (context, constraints) { final width = split ? listDetailListWidth( - MediaQuery.sizeOf(context).width, + ShellRailScope.windowWidth(context), constraints.maxWidth, preferredWidth, ) @@ -143,7 +144,7 @@ class _ListDetailPanesState extends State { listenable: widths, builder: (context, _) => LayoutBuilder( builder: (context, constraints) { - final window = media.size.width; + final window = ShellRailScope.windowWidth(context); final available = constraints.maxWidth; final preferred = widths.widthFor(key); final resizable = diff --git a/app/lib/shell/list_detail_policy.dart b/app/lib/shell/list_detail_policy.dart index ffb1589f..fa760f25 100644 --- a/app/lib/shell/list_detail_policy.dart +++ b/app/lib/shell/list_detail_policy.dart @@ -2,6 +2,8 @@ import 'dart:math' as math; import 'package:flutter/widgets.dart'; +import 'shell_rail_scope.dart'; + /// At least this wide, a destination keeps its list beside the open item /// (with the destination rail) instead of pushing the item as its own page. const double kListDetailMinWidth = 600; @@ -15,7 +17,7 @@ const double kListPaneMaxWidth = 440; /// Whether the window at [context] shows list and detail side by side. bool showsListBesideDetail(BuildContext context) => - MediaQuery.sizeOf(context).width >= kListDetailMinWidth; + ShellRailScope.windowWidth(context) >= kListDetailMinWidth; /// The narrowest list pane a drag leaves. const double kListPaneMinWidth = 240; diff --git a/app/lib/shell/navigation_rail.dart b/app/lib/shell/navigation_rail.dart new file mode 100644 index 00000000..93f6deec --- /dev/null +++ b/app/lib/shell/navigation_rail.dart @@ -0,0 +1,145 @@ +import 'package:flutter/material.dart'; + +import 'destination.dart'; +import 'list_detail_policy.dart'; + +/// The width of the destination rail on a wide window. +const double kNavigationRailWidth = 96; + +/// The rail with its divider: what the rail takes from a wide window's width. +const double kNavigationRailSpace = kNavigationRailWidth + 1; + +/// The narrowest window that shows the destination rail: the list-detail +/// minimum for the body beside it, plus the rail and its divider (the space the +/// shell takes from the window). Narrower windows keep the floating destination +/// bar, unchanged. +const double kNavigationRailMinWindowWidth = + kListDetailMinWidth + kNavigationRailSpace; + +/// Whether the window at [context] shows the destination rail. Read from the +/// window's own [MediaQuery], so the shell and the floating windows layer +/// (which sits above the shell) agree. +bool showsNavigationRail(BuildContext context) => + MediaQuery.sizeOf(context).width >= kNavigationRailMinWindowWidth; + +/// The wide layout's left-edge navigation: a Material [NavigationRail] with +/// an icon and a label per tab, the selected tab marked by the rail's +/// indicator, and Settings pinned to its bottom. +/// +/// [icon] builds each tab's icon (its running or unread badge included), so +/// the rail shows the same counts the floating bar did. [selected] is the +/// shell's destination: Settings (a page, not a tab) selects no tab but its +/// own item. +class ShellNavigationRail extends StatelessWidget { + const ShellNavigationRail({ + super.key, + required this.selected, + required this.icon, + required this.onSelected, + this.padding = EdgeInsets.zero, + }); + + final AppDestination selected; + final Widget Function(AppDestination destination) icon; + final ValueChanged onSelected; + + /// The system insets the rail keeps clear of: the status bar above and the + /// navigation bar below. + final EdgeInsets padding; + + @override + Widget build(BuildContext context) { + final index = shellTabDestinations.indexOf(selected); + return Padding( + padding: padding, + child: SizedBox( + width: kNavigationRailWidth, + child: NavigationRail( + key: const ValueKey('shell.navigation-rail'), + minWidth: kNavigationRailWidth, + labelType: NavigationRailLabelType.all, + selectedIndex: index < 0 ? null : index, + onDestinationSelected: (value) => + onSelected(shellTabDestinations[value]), + destinations: [ + for (final destination in shellTabDestinations) + NavigationRailDestination( + icon: KeyedSubtree( + key: ValueKey('shell.destination.${destination.name}'), + // The bar it replaces named each tab in a tooltip too. + child: Tooltip( + message: destinationDetails(destination).label, + child: icon(destination), + ), + ), + label: Text(destinationDetails(destination).label), + ), + ], + trailingAtBottom: true, + trailing: _SettingsRailItem( + selected: selected == AppDestination.settings, + onTap: () => onSelected(AppDestination.settings), + ), + ), + ), + ); + } +} + +/// Settings at the rail's foot, drawn as a [NavigationRailDestination] is: an +/// icon on a stadium indicator with its label under it, and the same colours. +/// It is not a [NavigationRailDestination] itself because the rail's +/// destination list is the tabs, and `trailing` is what the rail pins. +class _SettingsRailItem extends StatelessWidget { + const _SettingsRailItem({required this.selected, required this.onTap}); + + final bool selected; + final VoidCallback onTap; + + @override + Widget build(BuildContext context) { + final scheme = Theme.of(context).colorScheme; + final item = destinationDetails(AppDestination.settings); + final foreground = selected + ? scheme.onSecondaryContainer + : scheme.onSurfaceVariant; + final textStyle = Theme.of(context).textTheme.labelMedium?.copyWith( + color: foreground, + fontWeight: selected ? FontWeight.w600 : FontWeight.w500, + ); + return Semantics( + button: true, + selected: selected, + label: item.label, + child: ExcludeSemantics( + child: InkWell( + key: const ValueKey('shell.destination.settings'), + onTap: onTap, + child: SizedBox( + width: kNavigationRailWidth, + child: Padding( + padding: const EdgeInsets.symmetric(vertical: 12), + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Container( + width: 56, + height: 32, + alignment: Alignment.center, + decoration: ShapeDecoration( + shape: const StadiumBorder(), + color: selected ? scheme.secondaryContainer : null, + ), + child: Icon(item.icon, color: foreground), + ), + const SizedBox(height: 4), + Text(item.label, style: textStyle), + ], + ), + ), + ), + ), + ), + ); + } +} diff --git a/app/lib/shell/shell_rail_scope.dart b/app/lib/shell/shell_rail_scope.dart new file mode 100644 index 00000000..024f0a28 --- /dev/null +++ b/app/lib/shell/shell_rail_scope.dart @@ -0,0 +1,35 @@ +import 'package:flutter/widgets.dart'; + +/// Marks the content beside the destination rail. A wide window's content +/// lays out in the width left beside the rail, so list and detail panes read +/// that width ([windowWidth]) instead of the window's. Outside the scope (a +/// phone, a route pushed over the shell) the window's own width applies. +class ShellRailScope extends InheritedWidget { + const ShellRailScope({ + super.key, + required this.shown, + required this.bodyWidth, + required super.child, + }); + + /// Whether the rail is shown beside this content. + final bool shown; + + /// The width beside the rail; null when no rail is shown. + final double? bodyWidth; + + /// Whether the rail is shown beside [context]'s content. + static bool isShown(BuildContext context) => + context.dependOnInheritedWidgetOfExactType()?.shown ?? + false; + + /// The width the panes of [context] lay out in: the body beside the rail, + /// or else the window. + static double windowWidth(BuildContext context) => + context.dependOnInheritedWidgetOfExactType()?.bodyWidth ?? + MediaQuery.sizeOf(context).width; + + @override + bool updateShouldNotify(ShellRailScope oldWidget) => + shown != oldWidget.shown || bodyWidth != oldWidget.bodyWidth; +} diff --git a/app/lib/shell/shell_runs_pipelines_shortcut.dart b/app/lib/shell/shell_runs_pipelines_shortcut.dart new file mode 100644 index 00000000..ad25a0eb --- /dev/null +++ b/app/lib/shell/shell_runs_pipelines_shortcut.dart @@ -0,0 +1,28 @@ +import 'package:flutter/services.dart'; + +import 'destination.dart'; + +/// The chord that bounces between Runs and Pipelines, as the help page reads +/// it. It is the same on every platform. +const shellRunsPipelinesShortcutLabel = 'Ctrl+A'; + +/// Whether [event] is Ctrl+A. Only Ctrl counts: Alt, Shift, Cmd and chords +/// with both Ctrl and Alt are not the shortcut. Repeats of a held chord match +/// as well, so the caller can swallow them; only its first press acts. +bool shellRunsPipelinesShortcut(KeyEvent event, HardwareKeyboard keyboard) { + if (event is KeyUpEvent || + keyboard.isAltPressed || + keyboard.isShiftPressed || + keyboard.isMetaPressed || + !keyboard.isControlPressed) { + return false; + } + return event.logicalKey == LogicalKeyboardKey.keyA; +} + +/// The destination Ctrl+A goes to from [current]: Pipelines from Runs, and +/// Runs from every other destination (Pipelines included). +AppDestination shellRunsPipelinesTarget(AppDestination current) => + current == AppDestination.runs + ? AppDestination.pipelines + : AppDestination.runs; diff --git a/app/lib/shell/windows/window_host.dart b/app/lib/shell/windows/window_host.dart index f4fc1f84..682d9b4b 100644 --- a/app/lib/shell/windows/window_host.dart +++ b/app/lib/shell/windows/window_host.dart @@ -1,6 +1,7 @@ import 'package:flutter/material.dart'; import 'package:flutter/services.dart'; +import '../navigation_rail.dart'; import 'window_focus.dart'; import 'window_layer.dart'; import 'window_manager.dart'; @@ -18,7 +19,16 @@ import 'window_shortcuts.dart'; /// /// The host fills its parent and takes no input between windows. class WindowHost extends StatefulWidget { - const WindowHost({super.key, required this.manager}); + const WindowHost({ + super.key, + required this.manager, + this.reservesRail = false, + }); + + /// Whether the shell beside this host shows the destination rail on the + /// window's left edge; the windows then keep to the right of it while the + /// window is wide enough for the rail (see [showsNavigationRail]). + final bool reservesRail; final WindowManager manager; @@ -119,24 +129,36 @@ class _WindowHostState extends State { ]), builder: (context, _) => LayoutBuilder( builder: (context, constraints) { - final bounds = constraints.biggest; - return Stack( - fit: StackFit.expand, - children: [ - for (final entry in windows) - if (manager.kinds[entry.kind] case final kind?) - WindowLayer( - key: ValueKey(entry.id), - manager: manager, - kind: kind, - entry: entry, - visible: - manager.isVisible(entry) && - bounds.width >= kind.minHostWidth, - bounds: bounds, - focus: _focus, - ), - ], + // Beside the destination rail the windows keep to the page's + // right, so they never sit under the rail. + // The shell takes the rail and its divider (kNavigationRailSpace). + final leading = widget.reservesRail && showsNavigationRail(context) + ? kNavigationRailSpace + : 0.0; + final bounds = Size( + constraints.maxWidth - leading, + constraints.maxHeight, + ); + return Padding( + padding: EdgeInsetsDirectional.only(start: leading), + child: Stack( + fit: StackFit.expand, + children: [ + for (final entry in windows) + if (manager.kinds[entry.kind] case final kind?) + WindowLayer( + key: ValueKey(entry.id), + manager: manager, + kind: kind, + entry: entry, + visible: + manager.isVisible(entry) && + bounds.width >= kind.minHostWidth, + bounds: bounds, + focus: _focus, + ), + ], + ), ); }, ), diff --git a/app/notes/ctrl-a-runs-pipelines.md b/app/notes/ctrl-a-runs-pipelines.md new file mode 100644 index 00000000..6a6ae0dd --- /dev/null +++ b/app/notes/ctrl-a-runs-pipelines.md @@ -0,0 +1,37 @@ +# Ctrl+A toggles Runs and Pipelines + +Stage 01-implement (artifact 401). Not committed. + +## Behaviour +- Ctrl+A (the same chord on every platform) moves the shell between destinations: + - from Runs, to Pipelines; + - from Pipelines, to Runs; + - from any other destination (Chat, Search, Settings), to Runs. +- It is matched like Ctrl+K in `shell/adaptive_shell.dart`: logical key A with Ctrl alone. Alt, Shift, Cmd, Ctrl+Alt, and key-up events do not match. Repeats of a held chord are swallowed; only the first key-down acts. +- It does not act while a text field (`primaryFocusTakesTyping`) or a `TypingSurface` such as the terminal has focus. The handler returns false, so the field or terminal keeps Ctrl+A (select all, line start). +- The switch goes through the shell's normal `_select`, so a controlled shell (`onDestinationSelected`) receives the destination. + +## Changed paths +- `app/lib/shell/shell_runs_pipelines_shortcut.dart` (new): `shellRunsPipelinesShortcut` (matcher), `shellRunsPipelinesTarget` (destination rule), `shellRunsPipelinesShortcutLabel` (`'Ctrl+A'`). +- `app/lib/shell/adaptive_shell.dart`: one branch in `_handleDestinationKeyEvent`, after the Ctrl+K branch and before the typing-surface check; updated doc comment. +- `app/lib/features/settings/keyboard_shortcuts_registry.dart`: "Switch between Runs and Pipelines" help entry, `Ctrl+A` on every platform, with a caveat about text fields and the terminal. +- `app/test/shell/runs_pipelines_shortcut_test.dart` (new): matcher, destination rule, Chat→Runs→Pipelines→Runs sequence, text-field exception, terminal exception. +- `app/test/features/settings/keyboard_shortcuts_help_test.dart`: help entry test over every `TargetPlatform` value. + +## Focused results +- `tool/memwatch/full.sh 'test/shell/runs_pipelines_shortcut_test.dart test/features/settings/keyboard_shortcuts_help_test.dart test/shell/shell_chat_shortcut_test.dart test/shell/destination_shortcuts_test.dart'`: PASS, 19 passed, 0 failed, peak 1151 MB, 13s, exit 0. +- Mutation check: with the `primaryFocusTakesTyping()` guard removed, `runs_pipelines_shortcut_test.dart` fails (2 failed, including the text-field case). The guard was restored; the file matches the pre-mutation backup. +- `tool/analyze.sh` on the changed files: clean, exit 0. Run after the focused tests, sequentially. +- No existing test sends Ctrl+A. The `keyA` uses in `chat_shell_terminal_test.dart` and `chat_transcript_selection_test.dart` are plain or Cmd+A, so they are unaffected. + +## Affected states +- Shell tabs: Pipelines, Runs, Chat, Search, and Settings (a page of Pipelines). +- Text field focused: Ctrl+A goes to the field. +- Terminal focused: Ctrl+A goes to the terminal. +- Help page: new "Switch between Runs and Pipelines" row. + +## Not covered +- No UI capture or device run (ui-review owns that). +- The text-field test pins the platform to Android so that Ctrl+A means select all. On Apple platforms Ctrl+A is line start in the field; the field still keeps it, but that case is not tested. +- The chat composer is not tested directly; it is a text field, so the same guard applies. +- On web, the browser may keep Ctrl+A; the registry caveat does not mention this. diff --git a/app/notes/first-run-walkthrough.md b/app/notes/first-run-walkthrough.md new file mode 100644 index 00000000..679ac1d4 --- /dev/null +++ b/app/notes/first-run-walkthrough.md @@ -0,0 +1,117 @@ +# First-run walkthrough + +A short, skippable four-page walkthrough for new users of the Flutter app. + +## What it does + +- Shows once per device on first launch, from the Pipelines page. +- Is also offered once per server when the device has already seen it and the + connected server has no pipelines, runs or chats yet (the server is checked + with `list_pipelines`, `list_runs` and `chat_sessions`; an unreadable server + never triggers it). +- Pages: 1) what Pipelines is and how to connect to the server; 2) set up an + agent harness, with an agent picker and one copy button for + `pipelines harness setup ` (`claude`, `codex`, `opencode`, `pi`); + 3) the Pipelines and Runs tabs and how to start a run; 4) the Chat tab, float + and terminal. +- Every page has Skip; Back and Next move between pages; Done ends on the last. +- Closing by any route (Skip, Done, the close gesture, a tap outside) records the + device as seen. +- Settings reopens it from Tools → Help → "Show the walkthrough". Reopening + does not change the seen record. + +## Where it lives + +- `lib/features/walkthrough/` + - `walkthrough_store.dart`: the seen/offered records (`pipelines.next.*` keys; + a store that cannot be read reports "seen", so it never nags). + - `walkthrough_steps.dart`: the page copy and agent list (pure data). + - `first_run_walkthrough.dart`: the stepper and `showFirstRunWalkthrough` + (a Material bottom sheet on phones, a dialog on wide windows, via + `showAppDetails`). + - `walkthrough_harness_command.dart`: agent chips, the command and copy. + - `walkthrough_gate.dart`: the first-launch and empty-server check. +- `lib/application/pipelines_app.dart`: wraps the Pipelines destination body in + the gate (the Pipelines tab is the first screen). +- `lib/features/settings/settings_walkthrough_section.dart`: one row in the + Tools → Help group, plus `SettingsKeys.walkthrough`. + +## Focused tests + +- `test/features/walkthrough/walkthrough_gate_test.dart`: first launch shows + once; Done and Skip persist; a seen device on an empty server is offered once; + a seen device that starts disconnected makes no server call and is offered + after it connects; an unreadable check is retried on the next connection (and + a repeated notification while connected does not re-query); a server with + work, an unreadable server, a hidden Pipelines page, and an unavailable store + all stay quiet; hiding the Pipelines page while the first-launch read is + still pending keeps the walkthrough closed, and showing it again offers it + once. +- `test/features/walkthrough/first_run_walkthrough_test.dart`: phone bottom + sheet and wide dialog; Back disabled on page 1; four pages with Done on the + last and Skip throughout; the harness picker and copy; large text (2x) and + dark mode without overflow. +- `test/features/settings/settings_walkthrough_test.dart`: the Settings row + reopens the walkthrough on page 1. + +## Results + +- Focused run: `tool/memwatch/full.sh 'test/features/walkthrough/first_run_walkthrough_test.dart test/features/walkthrough/walkthrough_gate_test.dart test/features/settings/settings_walkthrough_test.dart'` + → PASS, 20 passed, 0 failed, peak 1031 MB, 16 s. The verdict named only these + three paths. +- Visibility fix (review must-fix, visit 2): the gate offered without checking + `enabled`, so a walkthrough could open over another destination if Pipelines + was hidden before the post-frame callback or during a pending read. The gate + now checks `mounted && enabled` in the callback, after each await, and before + each show. A skipped callback clears the in-flight flag, so re-enabling + Pipelines reschedules the offer. Covered by the new gate test + "hiding Pipelines while an offer is pending keeps the walkthrough closed". + That test was not run against the pre-fix code, so the failing-before claim + is by reasoning only. +- Lifecycle fix (review must-fix): the empty-server check used to run once + right after the first frame, before the session connected. A seen device + then got a `NotConnectedError`, and the check was never retried. The gate now + takes the session as its connection source (`connection` + `connected`), waits + while disconnected, re-runs on each new connection until the server answers, + and stays quiet on a repeated notification while connected. A connection that + arrives between frames requests a visual update, so the post-frame callback + runs. The fix is covered by the two new gate tests above. +- Two earlier runs failed and were fixed in the test code, not by weakening + expectations: the large-text test tapped Next before scrolling it into view, + and the "unavailable store" test awaited the real preferences plugin inside + `testWidgets` and hung. The store now takes an injectable opener, so that case + is a plain test with a null opener. +- `tool/analyze.sh`: clean (0 errors, 0 warnings, 0 infos). +- Not run here: `pipelines_app_test`, the Settings screen suites and the other + Pipelines suites. They belong to the land gate. + +## Affected states (checked by focused tests only; nothing captured) + +- Phone (390×844): bottom sheet; page 1 with Back disabled; all four pages; + Skip mid-walkthrough. +- Wide (1280×900): dialog; Next reaches page 2. +- Harness page: four agent chips; the command follows the selected agent; copy + copies the selected command and the button shows a check. +- Large text (2×) on a 360×740 phone and dark mode: every page builds with no + exception. +- Gate: first launch once; Done and Skip persist; a seen device on an empty + server is offered once per server; a server with runs, an unreadable server, + a hidden Pipelines page and an unavailable store stay quiet. +- Settings: "Show the walkthrough" reopens page 1 and does not change the seen + record. + +Nothing was built, run on a device or captured. `ui-review` owns the rendered +review. + +## Limitations + +- The gate is tested in isolation with fake stores and gateways. The Pipelines + wiring in `pipelines_app.dart` is not covered by a focused test. +- Narrow window: the empty-server offer marks the server as offered before it + shows. If Pipelines is hidden during that one store write, the server is + consumed without the walkthrough appearing. Fixing it needs the store write + to move to the dialog's close, which changes when the offer is recorded. +- On phones the walkthrough is a Material bottom sheet, not a full page. +- The harness command is shown as a picker with one copy button for the + selected agent, not four separate copy buttons. +- The "Show the walkthrough" test covers the row, not the whole Settings tree. diff --git a/app/notes/navigation-rail.md b/app/notes/navigation-rail.md new file mode 100644 index 00000000..544302a5 --- /dev/null +++ b/app/notes/navigation-rail.md @@ -0,0 +1,124 @@ +# Wide destination rail with Settings + +On a wide window the shell's four destinations (Pipelines, Runs, Chat, Search) +move from the floating bottom-left pill to a Material `NavigationRail` at the +left edge, with Settings pinned to its foot. The rail keeps the running and +unread badges. The Pipelines toolbar's Settings gear is removed where the rail +shows. Phone and narrow layouts are unchanged. + +## Design + +- **Threshold.** The rail shows at window width >= 697 + (`kNavigationRailMinWindowWidth` = `kListDetailMinWidth` 600 + + `kNavigationRailSpace` 97, the rail plus its divider). The body beside the + rail therefore still meets the list/detail split threshold at 697 px. Between + 600 and 696 px the floating bar and split layout stay as before. +- **Layout.** `AdaptiveShell.build` returns the same tree at every width: + `Row[rail slot, divider slot, Expanded(ShellRailScope(Scaffold))]`. On a + phone the first two slots are empty. Resizing across the threshold does not + remount a destination, and pages pushed over a tab keep their state. +- **Body width.** `ShellRailScope.bodyWidth` is the window width less the rail + and its divider (`kNavigationRailSpace` = 97), computed in `build`. The + list/detail policy reads it through `ShellRailScope.windowWidth` + (`list_detail.dart`, `list_detail_policy.dart`), so `showsListBesideDetail` + and the pane widths follow the body. Outside the scope the window width still + applies. +- **Rail items** (`navigation_rail.dart`). Four `NavigationRailDestination`s + with `labelType: all`, `trailingAtBottom: true`. Each tab's icon keeps its + badge (`_icon`), a `Tooltip` with its label, and the `shell.destination.` + key the floating bar used. Settings is a custom `_SettingsRailItem` in + `trailing`, styled like a rail destination (stadium indicator, same colours). + A `NavigationRailDestination` cannot be pinned, so it is not one. +- **Window host.** Floating windows overlay the whole app, so `WindowHost` takes + `reservesRail` (set by `pipelines_app.dart`) and starts its bounds after the + rail and divider (`kNavigationRailSpace`, 97 px, the same inset the shell + uses) when the window is wide enough. Tests that mount the host without a + shell keep the full width. +- **Pipelines gear.** `ShellRailScope.isShown` hides `pipelines-open-settings` + in the shell's toolbar while the rail shows. On a phone it stays. + +## Changed paths + +- `app/lib/shell/navigation_rail.dart` (new): rail widget, Settings item, + threshold constants. +- `app/lib/shell/shell_rail_scope.dart` (new): body-width scope. +- `app/lib/shell/adaptive_shell.dart`: rail layout and constant tree shape. +- `app/lib/shell/list_detail.dart`, `app/lib/shell/list_detail_policy.dart`: + read the body width through the scope. +- `app/lib/shell/windows/window_host.dart`: `reservesRail` inset (97 px). +- `app/lib/shell/destination.dart`: comment only. +- `app/lib/features/pipelines/screen.dart`: gear hidden beside the rail. +- `app/lib/application/pipelines_app.dart`: `WindowHost(reservesRail: true)`. + +## Focused results + +Review fix (off-by-one at the threshold): the rail threshold and the +`WindowHost` inset both use `kNavigationRailSpace` (97). Re-run from `app/` +with `tool/memwatch/full.sh`: + +- Rail and window-host files (`navigation_rail_test`, `windows/window_host_test`, + `windows/window_layering_test`): `PASS: 21 passed` earlier, then covered by the + run below. +- All 18 changed test files plus the rail and window-host tests + (`application/`, `features/chat/`, `shell/`, `shell/windows/`): + `memwatch: PASS: 108 passed, 0 failed, 0 skipped; exit 0`. The verdict names + only the intended paths. +- `tool/analyze.sh` (whole app, run after the focused tests): `analyze: clean`. + +New tests (`test/shell/navigation_rail_test.dart`): + +- Wide: labelled rail, full height, left edge, Settings pinned below the tabs. +- Selection marks the tab and one tap selects another. +- Settings opens as a page from the rail foot; no tab is selected meanwhile; + Back returns to Pipelines. +- Running count on the Runs item of the rail. +- A list and its open item lay out to the right of the rail. +- The rail appears at 697 and not at 696; at 697 the list and detail sit side by + side (list starts at 97, detail ends at 697); phone and 640 keep the floating bar. +- Floating windows start after the rail (97) with `reservesRail`, and at 500 px + they use the full width. +- Crossing the threshold keeps a destination mounted with its state. + +Updated expectations (each one is a consequence of the rail, not a behaviour +change the task did not ask for): + +- Wide-window floating-bar tests moved to 640 px, where the bar still sits + beside the list (`floating_tab_bar_test`, `split_destination_bar_test`, + `split_detail_pages_test`, `split_status_bar_test`, `pane_bar_row_test`, + `chat_sidebar_clearance_test`). The width-driven policy numbers + (`list_pane_resize_test`) now use the body width. +- `settings_page_test`: the gear case runs on a phone; a wide case opens + Settings from the rail. `tab_location_navigation_test` uses the rail's + Settings item at 1100 px. +- `chat_registration_test`, `chat_list_detail_test`, `attention_badge_test`: + the rail replaces the bottom bar at wide widths. +- `list_pane_resize_test` (grip): one `pumpAndSettle` instead of one `pump`. + The focus emphasis reaches the grip one frame later beside the rail. The + expectation (emphasised on focus) is unchanged. +- `chat_sidebar_clearance_test`: the scroll offset is kept up to the new + maximum extent. At 640 px the list is narrower than beside the rail, so its + rows re-wrap and the content is shorter. +- `chat_split_integration_test`: the compact menu's "Runs" is picked by + element, not by text, because the rail also labels Runs. The rail's tooltips + keep `byTooltip('Chat')` working. +- Floating-window expectation (`navigation_rail_test`): the probe window starts at + `100 + kNavigationRailSpace` (97), not 96. + +## Affected states + +- Wide, rail shown (>= 697 px): rail with badges, Settings pinned, lists beside + the rail, floating windows beside it, no Pipelines gear, Settings page with + Back. +- 600-696 px: floating bar and split layout as before (no rail). +- Phone: unchanged, including the Pipelines gear. + +## Limitations + +- Not verified in a browser or on a device. `ui-review` owns captures. The + visual match of the rail and the Settings item is by reading the Material + sources, not by a capture. +- The terminal panel is laid over the app's bottom edge (`TerminalStage`), not + inside the shell. When it is open on a wide window it may cover the rail's + foot and Settings. This follows from the stack layout; it was not captured. +- The compact list's "Menu" sheet (`ShellDestinationMenu`) still offers the + destinations beside the rail. It is a duplicate, not a removed feature. diff --git a/app/notes/run-detail-output-expanded.md b/app/notes/run-detail-output-expanded.md new file mode 100644 index 00000000..aa1806ca --- /dev/null +++ b/app/notes/run-detail-output-expanded.md @@ -0,0 +1,39 @@ +# Run detail: Output section starts expanded + +## Change +- The run Summary's Output section (`run-detail-summary-output`) now starts open. + Input still starts closed. The Summary's default is restored on a different run + and when a search hit names no section (`RunDetailTabs._resetSummarySections`). +- A visit's Summary Output (`run-visit-section-Output`) starts open; Input starts + closed (`_VisitSummaryState._closed = {'Input'}`). +- Both stay collapsible by tapping the title. The open/closed state lives in the + controller or State for that view only; it is not persisted. +- Long outputs: Output is a sliver. `RunFieldSliver` (in `run_field_body.dart`) + builds one `SliverList` row per recorded + field, so a map with hundreds of fields lays out only the rows on screen. It + is used for the run Summary Output (`_StickyField.sliverBody`) and the visit + Summary Output (`_section(..., lazy: true)`), both through `StickySection`'s + sliver path. A closed `SliverReveal` builds nothing. +- Input stays on the box path (`RunFieldBody`); it starts closed, so its cost is + paid only when the operator opens it. The box and sliver forms share the row + builder, so they render the same fields. + +## Tests (run through `tool/memwatch/full.sh`, one quoted path list) +- Command: `tool/memwatch/full.sh 'test/features/runs/ui/run_detail_visit_sections_test.dart test/features/runs/ui/run_detail_summary_fields_test.dart test/features/runs/ui/run_detail_widget_test.dart test/features/runs/ui/run_search_selection_test.dart test/features/runs/ui/run_detail_tabs_test.dart test/features/runs/ui/run_detail_visit_test.dart'` +- Verdict (final code): `PASS: 49 passed, 0 failed, 0 skipped; peak 1884 MB; 32s; exit 0` +- New: visit Output starts expanded and collapses/reopens; run Output starts + expanded and collapses for the view; a 500-field visit Output opens with only + its first field built and the page scrolls to the last one (lazy regression). +- Updated (the old expectation was that Output started closed): visit tab/empty-state + tests, run Summary empty-wording and recorded-input tests, search-selection tests + for input, retired field and replacing a visit with the Summary. +- Not changed: Input's closed default and every Input expectation. + +## Analyze +- `tool/analyze.sh`: `analyze: clean; 10s; exit 0` +- `dart format --set-exit-if-changed` on the changed files: formatted one widget + test file (whitespace only). + +## Limitations +- No widget capture or browser/device check was run here; ui-review owns that. +- Very long Output is laid out when the section opens. Not measured for jank. diff --git a/app/test/application/chat_registration_test.dart b/app/test/application/chat_registration_test.dart index 07901af5..e29fe066 100644 --- a/app/test/application/chat_registration_test.dart +++ b/app/test/application/chat_registration_test.dart @@ -285,12 +285,12 @@ void main() { expect(find.byKey(const Key('chat-turn-activity')), findsOneWidget); expect(find.text('Kept behind a native disclosure.'), findsNothing); - // The shell bar stays over the list and tabs; the open chat draws its - // own floating bar in its pane, with no Back: the list beside it is the - // way out. + // The destination rail sits at the left edge; the shell bar stays over + // the list, and the open chat draws its own floating bar in its pane, + // with no Back: the list beside it is the way out. expect(find.byType(ChatSessionsScreen), findsOneWidget); - expect(find.byType(NavigationRail), findsNothing); - expect(find.byType(FloatingDestinationBar), findsOneWidget); + expect(find.byType(NavigationRail), findsOneWidget); + expect(find.byType(FloatingDestinationBar), findsNothing); // The shell's bar and the conversation's own header. expect(find.byType(SegmentedBar), findsNWidgets(2)); expect(find.byType(AppBar), findsNothing); diff --git a/app/test/application/settings_page_test.dart b/app/test/application/settings_page_test.dart index 73606176..e27df3ca 100644 --- a/app/test/application/settings_page_test.dart +++ b/app/test/application/settings_page_test.dart @@ -13,9 +13,9 @@ import '../features/pipelines/fixtures.dart'; import 'pipelines_app_test.dart' show webServer; import 'pipelines_replies.dart'; -/// Settings is not a tab: it opens as a page from the gear in the Pipelines -/// bar, keeps its `/settings` route (and deep link), and closes back to -/// Pipelines. The tab bar keeps Pipelines selected meanwhile. +/// Settings is not a tab: it opens as a page (from the gear in the Pipelines +/// bar on a phone, from the rail's foot on a wide window), keeps its +/// `/settings` route (and deep link), and closes back to Pipelines. The tab bar keeps Pipelines selected meanwhile. void main() { Future pumpApp( WidgetTester tester, { @@ -50,7 +50,9 @@ void main() { .widget(find.byType(FloatingDestinationBar)) .currentIndex; - for (final size in [const Size(390, 844), const Size(1200, 800)]) { + // A phone's Pipelines bar keeps the gear; a wide window's rail offers + // Settings instead (see the wide test below). + for (final size in [const Size(390, 844)]) { testWidgets('${size.width}: the Pipelines bar gear opens Settings ' 'as a page and Back returns', (tester) async { final provider = await pumpApp( @@ -101,6 +103,57 @@ void main() { }); } + testWidgets('1200: the rail offers Settings at its foot and no gear is ' + 'left in the Pipelines toolbar; Settings is a page and Back returns', ( + tester, + ) async { + final provider = await pumpApp( + tester, + location: '/pipelines', + size: const Size(1200, 800), + ); + expect(find.byType(NavigationRail), findsOneWidget); + expect(find.byKey(const Key('pipelines-open-settings')), findsNothing); + expect(find.byType(FloatingDestinationBar), findsNothing); + final rail = tester.widget(find.byType(NavigationRail)); + expect(rail.selectedIndex, 0); + for (final label in ['Pipelines', 'Runs', 'Chat', 'Search', 'Settings']) { + expect( + find.descendant( + of: find.byType(NavigationRail), + matching: find.text(label), + ), + findsOneWidget, + reason: label, + ); + } + + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); + await tester.pump(); + await tester.pump(); + expect(provider.value.uri.path, '/settings'); + expect(find.byType(SettingsScreen), findsOneWidget); + // Settings is a page of Pipelines: the rail marks Settings, not a tab. + expect( + tester.widget(find.byType(NavigationRail)).selectedIndex, + isNull, + ); + expect(find.byKey(const ValueKey('shell.back')), findsOneWidget); + expect(tester.takeException(), isNull); + + await tester.tap(find.byKey(const ValueKey('shell.back'))); + await tester.pump(); + await tester.pump(); + expect(provider.value.uri.path, '/pipelines'); + expect(find.byKey(const Key('pipelines-open-settings')), findsNothing); + expect( + tester.widget(find.byType(NavigationRail)).selectedIndex, + 0, + ); + await tester.pumpWidget(const SizedBox.shrink()); + await tester.pump(); + }); + testWidgets('the /settings deep link opens the Settings page and ' 'the system Back closes it to Pipelines', (tester) async { final provider = await pumpApp( diff --git a/app/test/application/tab_location_navigation_test.dart b/app/test/application/tab_location_navigation_test.dart index 1197cd27..55de9dbf 100644 --- a/app/test/application/tab_location_navigation_test.dart +++ b/app/test/application/tab_location_navigation_test.dart @@ -179,11 +179,9 @@ void main() { final before = tester.widget(find.byType(PipelinesScreen)); expect(before.initialPipelineId, 1); final pipelineState = tester.state(find.byType(PipelinesScreen)); - await tapBarAction( - tester, - find.byKey(const Key('pipelines-open-settings')), - 'Settings', - ); + // Wide: the rail offers Settings (the toolbar gear is gone). + expect(find.byKey(const Key('pipelines-open-settings')), findsNothing); + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); await tester.pumpAndSettle(); expect(app.provider.value.uri.path, '/settings'); final hidden = find.byType(PipelinesScreen, skipOffstage: false); diff --git a/app/test/features/chat/chat_list_detail_test.dart b/app/test/features/chat/chat_list_detail_test.dart index 9e3703b3..a96c93ee 100644 --- a/app/test/features/chat/chat_list_detail_test.dart +++ b/app/test/features/chat/chat_list_detail_test.dart @@ -50,7 +50,7 @@ Future _pumpShell(WidgetTester tester, Size size) async { void main() { for (final size in [const Size(1280, 800), const Size(800, 830)]) { - testWidgets('a wide window keeps the tab bar and list beside the open chat ' + testWidgets('a wide window keeps the rail and list beside the open chat ' 'at $size', (tester) async { await _pumpShell(tester, size); expect( @@ -68,8 +68,10 @@ void main() { find.byType(Navigator).first, ); expect(navigator.canPop(), isFalse, reason: 'No page covers the shell'); - expect(find.byType(NavigationRail), findsNothing); - expect(find.byType(FloatingDestinationBar), findsOneWidget); + // Both sizes are wide enough for the rail (the shell's own bar and list + // beside the open chat sit to its right). + expect(find.byType(NavigationRail), findsOneWidget); + expect(find.byType(FloatingDestinationBar), findsNothing); expect(find.byKey(const ValueKey('chat-thread-a')), findsOneWidget); expect(find.text('Second chat'), findsOneWidget); expect( diff --git a/app/test/features/chat/chat_sidebar_clearance_test.dart b/app/test/features/chat/chat_sidebar_clearance_test.dart index 2ed3b3be..c9f9c624 100644 --- a/app/test/features/chat/chat_sidebar_clearance_test.dart +++ b/app/test/features/chat/chat_sidebar_clearance_test.dart @@ -11,7 +11,7 @@ void main() { testWidgets('chat list stays above labeled navigation ($scale)', ( tester, ) async { - tester.view.physicalSize = const Size(1200, 900); + tester.view.physicalSize = const Size(640, 900); tester.view.devicePixelRatio = 1; tester.platformDispatcher.textScaleFactorTestValue = scale; addTearDown(tester.view.reset); @@ -87,7 +87,13 @@ void main() { ), same(scrollable), ); - expect(scrollable.position.pixels, closeTo(retainedOffset, .5)); + // The list is narrower at 640 (no rail) than beside the rail, so its + // rows re-wrap into a shorter scroll extent: the offset is kept up to + // that extent, and no further. + final kept = retainedOffset < scrollable.position.maxScrollExtent + ? retainedOffset + : scrollable.position.maxScrollExtent; + expect(scrollable.position.pixels, closeTo(kept, .5)); expect(tester.takeException(), isNull); }); } diff --git a/app/test/features/chat/chat_split_integration_test.dart b/app/test/features/chat/chat_split_integration_test.dart index 4d3eb558..c10ea315 100644 --- a/app/test/features/chat/chat_split_integration_test.dart +++ b/app/test/features/chat/chat_split_integration_test.dart @@ -106,7 +106,16 @@ void main() { expect(find.text('Menu'), findsOneWidget); await tester.tap(find.text('Menu')); await tester.pumpAndSettle(); - await tester.tap(find.text('Runs')); + // The menu's own row: the rail labels Runs too, so take the text that + // is not in the rail. + await tester.tap( + find.byElementPredicate( + (element) => + element.widget is Text && + (element.widget as Text).data == 'Runs' && + element.findAncestorWidgetOfExactType() == null, + ), + ); await tester.pumpAndSettle(); expect(find.text('Runs destination'), findsOneWidget); await tester.tap(find.byTooltip('Chat')); diff --git a/app/test/features/runs/ui/run_detail_summary_fields_test.dart b/app/test/features/runs/ui/run_detail_summary_fields_test.dart index 019607b6..b156bfc6 100644 --- a/app/test/features/runs/ui/run_detail_summary_fields_test.dart +++ b/app/test/features/runs/ui/run_detail_summary_fields_test.dart @@ -244,10 +244,9 @@ void main() { await tester.pumpAndSettle(); expect(find.text('No input recorded.'), findsOneWidget); + // Output starts open, so its empty sentence shows without a tap. await tester.ensureVisible(find.text('Output')); await tester.pumpAndSettle(); - await tester.tap(find.text('Output')); - await tester.pumpAndSettle(); expect(find.text('No output recorded.'), findsOneWidget); }); @@ -266,5 +265,35 @@ void main() { await tester.pumpAndSettle(); expect(find.text('ship it'), findsOneWidget); }); + + testWidgets('${platform.name} summary output starts expanded and ' + 'collapses for this view', (tester) async { + await pumpRunDetail( + tester, + platform, + run: recordedRunFixture(), + size: const Size(900, 1600), + ); + + final output = find.byKey(const ValueKey('run-detail-summary-output')); + final outputTitle = find.descendant( + of: output, + matching: find.text('Output'), + ); + final outputBody = find.descendant(of: output, matching: find.text('ok')); + // Output opens with its recorded value; Input stays closed. + expect(outputBody, findsOneWidget); + expect(find.text('ship it'), findsNothing); + + await tester.ensureVisible(outputTitle.first); + await tester.pumpAndSettle(); + await tester.tap(outputTitle.first); + await tester.pumpAndSettle(); + expect(outputBody, findsNothing); + + await tester.tap(outputTitle.first); + await tester.pumpAndSettle(); + expect(outputBody, findsOneWidget); + }); } } diff --git a/app/test/features/runs/ui/run_detail_visit_sections_test.dart b/app/test/features/runs/ui/run_detail_visit_sections_test.dart index 9baebc24..c7c13adb 100644 --- a/app/test/features/runs/ui/run_detail_visit_sections_test.dart +++ b/app/test/features/runs/ui/run_detail_visit_sections_test.dart @@ -49,21 +49,77 @@ void main() { } }); + testWidgets('${platform.name} visit Output starts expanded and collapses', ( + tester, + ) async { + await openVisit(tester, platform); + final output = find.byKey(const ValueKey('run-visit-section-Output')); + final outputTitle = find.descendant( + of: output, + matching: find.text('Output'), + ); + final outputBody = find.descendant(of: output, matching: find.text('ok')); + final input = find.byKey(const ValueKey('run-visit-section-Input')); + + // Output opens expanded; Input stays closed. + expect(find.text('result'), findsOneWidget); + expect(outputBody, findsOneWidget); + expect(find.text('Ship it.'), findsNothing); + + // The operator can collapse Output, and open it again. + await tester.ensureVisible(outputTitle.first); + await tester.tap(outputTitle.first); + await tester.pumpAndSettle(); + expect(outputBody, findsNothing); + expect(find.text('result'), findsNothing); + await tester.tap(outputTitle.first); + await tester.pumpAndSettle(); + expect(outputBody, findsOneWidget); + expect(input, findsOneWidget); + }); + + testWidgets('${platform.name} long visit Output opens lazily and still ' + 'scrolls to its last field', (tester) async { + final run = visitRunFixture(); + firstVisitStep(run)['output'] = { + for (var i = 0; i < 500; i++) 'field$i': 'value $i', + }; + await openVisit(tester, platform, run: run); + + // Open by default, yet only the fields on screen are built. + expect(find.text('value 0'), findsOneWidget); + expect(find.text('value 499'), findsNothing); + + // Scrolling the page reaches the rest of the Output. + await tester.scrollUntilVisible( + find.text('value 499'), + 500, + // The page's own scroll view is the outermost of its scrollables. + scrollable: find + .descendant( + of: find.byKey(const Key('run-visit-body-summary')), + matching: find.byType(Scrollable), + ) + .first, + ); + expect(find.text('value 499'), findsOneWidget); + }); + testWidgets('${platform.name} tabs show recorded values and exact empty ' 'wording', (tester) async { await openVisit(tester, platform); - // Each field by name with its value, never raw JSON. + // Each field by name with its value, never raw JSON. Output is open at + // once; Input's value shows only after its tap. expect(find.text('Ship it.'), findsNothing); - expect(find.text('ok'), findsNothing); + expect(find.text('ok'), findsOneWidget); await tester.tap(find.text('Input')); await tester.pumpAndSettle(); expect(find.text('prompt'), findsOneWidget); expect(find.text('Ship it.'), findsOneWidget); expect(find.textContaining('"prompt"'), findsNothing); + // Output is open as the visit opens; no tap is needed to read it. await openVisitTab(tester, RunVisitSection.output); - await tester.tap(find.text('Output')); - await tester.pumpAndSettle(); expect(find.text('result'), findsOneWidget); expect(find.text('ok'), findsOneWidget); @@ -127,13 +183,12 @@ void main() { await openVisit(tester, platform, run: run); expect(find.text(visitEmptyInput), findsNothing); - expect(find.text(visitEmptyOutput), findsNothing); + // Output is open, so its empty sentence is already there. + expect(find.text(visitEmptyOutput), findsOneWidget); await tester.tap(find.text('Input')); await tester.pumpAndSettle(); expect(find.text(visitEmptyInput), findsOneWidget); await openVisitTab(tester, RunVisitSection.output); - await tester.tap(find.text('Output')); - await tester.pumpAndSettle(); expect(find.text(visitEmptyOutput), findsOneWidget); await openVisitTab(tester, RunVisitSection.artifacts); expect( diff --git a/app/test/features/runs/ui/run_detail_widget_test.dart b/app/test/features/runs/ui/run_detail_widget_test.dart index 9767fb58..a8a81d03 100644 --- a/app/test/features/runs/ui/run_detail_widget_test.dart +++ b/app/test/features/runs/ui/run_detail_widget_test.dart @@ -172,7 +172,17 @@ void main() { expect(find.text('alpha=1, items=1, 2'), findsOneWidget); expect(find.textContaining('"alpha"'), findsNothing); - await openSummarySection('Output'); + // Output starts open: its value is there to scroll to, without a tap. + await tester.scrollUntilVisible( + find.text('ok=true'), + 200, + scrollable: find + .descendant( + of: find.byKey(const Key('run-detail-tab-body-summary')), + matching: find.byType(Scrollable), + ) + .first, + ); expect(find.text('ok=true'), findsOneWidget); await tapTab('Timeline'); diff --git a/app/test/features/runs/ui/run_search_selection_test.dart b/app/test/features/runs/ui/run_search_selection_test.dart index 88711f80..b2d21c4a 100644 --- a/app/test/features/runs/ui/run_search_selection_test.dart +++ b/app/test/features/runs/ui/run_search_selection_test.dart @@ -263,7 +263,7 @@ void main() { }); for (final platform in RunDetailTestPlatform.values) { - testWidgets('${platform.name} input field expands only the input section', ( + testWidgets('${platform.name} input field expands the input section', ( tester, ) async { await pumpSelection( @@ -277,7 +277,8 @@ void main() { findsOneWidget, ); expect(find.text('ship it'), findsOneWidget); - expect(find.text('ok'), findsNothing); + // Output keeps its default: open, as every Summary opens. + expect(find.text('ok'), findsOneWidget); }); testWidgets( @@ -310,8 +311,9 @@ void main() { find.byKey(const Key('run-detail-tab-body-summary')), findsOneWidget, ); + // The plain Summary shows its default sections: Output open, Input closed. expect(find.text('ship it'), findsNothing); - expect(find.text('ok'), findsNothing); + expect(find.text('ok'), findsOneWidget); }); for (final platform in RunDetailTestPlatform.values) { @@ -337,8 +339,9 @@ void main() { find.byKey(const Key('run-detail-tab-body-summary')), findsOneWidget, ); + // The Summary's default sections: Output open, Input closed. expect(find.text('ship it'), findsNothing); - expect(find.text('ok'), findsNothing); + expect(find.text('ok'), findsOneWidget); }, ); } diff --git a/app/test/features/settings/keyboard_shortcuts_help_test.dart b/app/test/features/settings/keyboard_shortcuts_help_test.dart index f070d2e7..1d6bd78a 100644 --- a/app/test/features/settings/keyboard_shortcuts_help_test.dart +++ b/app/test/features/settings/keyboard_shortcuts_help_test.dart @@ -40,6 +40,19 @@ void main() { }, ); + test('Runs and Pipelines switch is Ctrl+A on every platform', () { + for (final platform in TargetPlatform.values) { + final entry = KeyboardShortcutRegistry(platform: platform, web: false) + .entries + .firstWhere( + (entry) => entry.action == 'Switch between Runs and Pipelines', + ); + expect(entry.keys, 'Ctrl+A', reason: platform.name); + expect(entry.caveat, contains('Pipelines')); + expect(entry.caveat, contains('text field')); + } + }); + test('uses the shell primary modifier rule on iOS', () { final entries = const KeyboardShortcutRegistry( platform: TargetPlatform.iOS, diff --git a/app/test/features/settings/settings_walkthrough_test.dart b/app/test/features/settings/settings_walkthrough_test.dart new file mode 100644 index 00000000..a769479d --- /dev/null +++ b/app/test/features/settings/settings_walkthrough_test.dart @@ -0,0 +1,36 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/settings/settings_keys.dart'; +import 'package:pipelines_app/features/settings/settings_walkthrough_section.dart'; +import 'package:pipelines_app/ui/theme/app_theme.dart'; + +void main() { + testWidgets('Settings reopens the walkthrough on the first page', ( + tester, + ) async { + tester.view.devicePixelRatio = 1; + tester.view.physicalSize = const Size(390, 844); + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + + await tester.pumpWidget( + MaterialApp( + theme: appLightTheme(), + home: const Scaffold(body: SettingsWalkthroughSection()), + ), + ); + + expect(find.text('Show the walkthrough'), findsOneWidget); + expect(find.text('Welcome to Pipelines'), findsNothing); + + await tester.tap(find.byKey(SettingsKeys.walkthrough)); + await tester.pumpAndSettle(); + + expect(find.text('Welcome to Pipelines'), findsOneWidget); + expect(find.text('Step 1 of 4'), findsOneWidget); + + await tester.tap(find.byKey(const ValueKey('walkthrough.skip'))); + await tester.pumpAndSettle(); + expect(find.text('Welcome to Pipelines'), findsNothing); + }); +} diff --git a/app/test/features/walkthrough/first_run_walkthrough_test.dart b/app/test/features/walkthrough/first_run_walkthrough_test.dart new file mode 100644 index 00000000..ddeaec1a --- /dev/null +++ b/app/test/features/walkthrough/first_run_walkthrough_test.dart @@ -0,0 +1,202 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/walkthrough/first_run_walkthrough.dart'; +import 'package:pipelines_app/features/walkthrough/walkthrough_steps.dart'; +import 'package:pipelines_app/ui/theme/app_theme.dart'; + +const _nextKey = ValueKey('walkthrough.next'); +const _backKey = ValueKey('walkthrough.back'); +const _skipKey = ValueKey('walkthrough.skip'); +const _copyKey = ValueKey('walkthrough.copy'); +const _commandKey = ValueKey('walkthrough.command'); +const _launchKey = ValueKey('launch'); + +Widget _launcher({ThemeMode mode = ThemeMode.light, double textScale = 1}) => + MaterialApp( + theme: appLightTheme(), + darkTheme: appDarkTheme(), + themeMode: mode, + builder: (context, child) => MediaQuery( + data: MediaQuery.of( + context, + ).copyWith(textScaler: TextScaler.linear(textScale)), + child: child!, + ), + home: Scaffold( + body: Builder( + builder: (context) => Center( + child: FilledButton( + key: _launchKey, + onPressed: () => showFirstRunWalkthrough(context), + child: const Text('Open'), + ), + ), + ), + ), + ); + +Future _open(WidgetTester tester) async { + await tester.tap(find.byKey(_launchKey)); + await tester.pumpAndSettle(); +} + +void _useViewport(WidgetTester tester, Size size) { + tester.view.devicePixelRatio = 1; + tester.view.physicalSize = size; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); +} + +void main() { + group('phone layout', () { + testWidgets('opens as a bottom sheet with the first page', (tester) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + expect(find.byType(BottomSheet), findsOneWidget); + expect(find.byType(Dialog), findsNothing); + expect(find.text('Step 1 of 4'), findsOneWidget); + expect(find.text(walkthroughSteps.first.title), findsOneWidget); + }); + + testWidgets('Back is disabled on the first page; Next advances', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + expect(tester.widget(find.byKey(_backKey)).onPressed, isNull); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + expect(find.text('Step 2 of 4'), findsOneWidget); + expect( + tester.widget(find.byKey(_backKey)).onPressed, + isNotNull, + ); + + await tester.tap(find.byKey(_backKey)); + await tester.pumpAndSettle(); + expect(find.text('Step 1 of 4'), findsOneWidget); + }); + + testWidgets('walks four pages, Done on the last, Skip on every page', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + for (var page = 0; page < 3; page++) { + expect(find.byKey(_skipKey), findsOneWidget); + expect(find.text('Next'), findsOneWidget); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + } + expect(find.text('Step 4 of 4'), findsOneWidget); + expect(find.text('Done'), findsOneWidget); + expect(find.byKey(_skipKey), findsOneWidget); + expect(find.text(walkthroughSteps.last.title), findsOneWidget); + + await tester.tap(find.text('Done')); + await tester.pumpAndSettle(); + expect(find.text(walkthroughSteps.last.title), findsNothing); + }); + + testWidgets('Skip closes from the middle of the walkthrough', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + + await tester.tap(find.byKey(_skipKey)); + await tester.pumpAndSettle(); + expect(find.byType(BottomSheet), findsNothing); + }); + }); + + testWidgets('wide windows open the walkthrough as a dialog', (tester) async { + _useViewport(tester, const Size(1280, 900)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + expect(find.byType(Dialog), findsOneWidget); + expect(find.byType(BottomSheet), findsNothing); + expect(find.text('Step 1 of 4'), findsOneWidget); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + expect(find.text(walkthroughSteps[1].title), findsOneWidget); + }); + + testWidgets('the harness page offers each agent and copies its command', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + final copied = []; + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(SystemChannels.platform, (call) async { + if (call.method == 'Clipboard.setData') { + copied.add((call.arguments as Map)['text'] as String); + } + return null; + }); + addTearDown( + () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(SystemChannels.platform, null), + ); + + await tester.pumpWidget(_launcher()); + await _open(tester); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + + expect( + tester.widget(find.byKey(_commandKey)).data, + 'pipelines harness setup claude', + ); + await tester.tap( + find.byKey(const ValueKey('walkthrough.agent.pi')), + ); + await tester.pumpAndSettle(); + expect( + tester.widget(find.byKey(_commandKey)).data, + 'pipelines harness setup pi', + ); + + await tester.tap(find.byKey(_copyKey)); + await tester.pumpAndSettle(); + expect(copied, ['pipelines harness setup pi']); + expect( + find.descendant( + of: find.byKey(_copyKey), + matching: find.byIcon(Icons.check), + ), + findsOneWidget, + ); + }); + + testWidgets('large text and dark mode lay out without overflow', ( + tester, + ) async { + _useViewport(tester, const Size(360, 740)); + await tester.pumpWidget(_launcher(mode: ThemeMode.dark, textScale: 2)); + await _open(tester); + + for (var page = 0; page < walkthroughSteps.length; page++) { + expect(tester.takeException(), isNull, reason: 'page $page'); + expect(find.text(walkthroughSteps[page].title), findsOneWidget); + if (page < walkthroughSteps.length - 1) { + // At 2x text the phone sheet scrolls, so Next can start off screen. + await tester.ensureVisible(find.byKey(_nextKey)); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + } + } + expect(tester.takeException(), isNull); + }); +} diff --git a/app/test/features/walkthrough/walkthrough_gate_test.dart b/app/test/features/walkthrough/walkthrough_gate_test.dart new file mode 100644 index 00000000..72dc748b --- /dev/null +++ b/app/test/features/walkthrough/walkthrough_gate_test.dart @@ -0,0 +1,341 @@ +import 'dart:async'; + +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/walkthrough/walkthrough_gate.dart'; +import 'package:pipelines_app/features/walkthrough/walkthrough_store.dart'; +import 'package:pipelines_app/ui/theme/app_theme.dart'; +import 'package:shared_preferences/shared_preferences.dart'; + +const _welcome = 'Welcome to Pipelines'; + +Future _noPreferences() async => null; + +/// A gateway that answers the three empty-server list calls from fixed lists. +class _FakeGateway implements ApiGateway { + _FakeGateway({this.runs = const [], this.failing = false}); + + /// Runs the server reports; pipelines and chats are always empty here. + final List runs; + bool failing; + final calls = []; + + @override + Future call(String type, [JsonMap fields = const {}]) async { + calls.add(type); + if (failing) throw StateError('offline'); + return switch (type) { + 'list_pipelines' => {'pipelines': const []}, + 'list_runs' => {'runs': runs}, + 'chat_sessions' => {'chat_sessions': const []}, + _ => {'type': 'error'}, + }; + } + + @override + Stream get frames => const Stream.empty(); +} + +/// Delegates to [inner], but holds [isSeen] until [release] so a test can +/// change the page visibility while an offer is still in flight. +class _HeldStore implements WalkthroughStore { + _HeldStore(this.inner); + + final MemoryWalkthroughStore inner; + Completer? _gate; + + void hold() => _gate = Completer(); + + void release() { + _gate?.complete(); + _gate = null; + } + + @override + Future isSeen() async { + await _gate?.future; + return inner.isSeen(); + } + + @override + Future markSeen() => inner.markSeen(); + + @override + Future wasOffered(String serverScope) => + inner.wasOffered(serverScope); + + @override + Future markOffered(String serverScope) => + inner.markOffered(serverScope); +} + +/// [link] stands in for the session: its value is whether the server connected, +/// and notifying it is the connection transition. Defaults to connected. +Widget _host({ + required WalkthroughStore store, + ApiGateway? gateway, + bool enabled = true, + ValueNotifier? link, +}) { + final session = link ?? ValueNotifier(true); + return MaterialApp( + theme: appLightTheme(), + darkTheme: appDarkTheme(), + home: Scaffold( + body: FirstRunWalkthroughGate( + store: store, + enabled: enabled, + serverScope: 'server-a', + connection: session, + connected: () => session.value, + gateway: gateway, + child: const Text('Pipelines page'), + ), + ), + ); +} + +Future _finishWalkthrough(WidgetTester tester) async { + for (var page = 0; page < 3; page++) { + await tester.tap(find.byKey(const ValueKey('walkthrough.next'))); + await tester.pumpAndSettle(); + } + await tester.tap(find.text('Done')); + await tester.pumpAndSettle(); +} + +void main() { + testWidgets('first launch shows the walkthrough once per device', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + await tester.pumpWidget(_host(store: store)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + + await _finishWalkthrough(tester); + expect(find.text(_welcome), findsNothing); + expect(store.seen, isTrue); + + // A later launch on the same device does not show it again. + await tester.pumpWidget(const SizedBox()); + await tester.pumpWidget(_host(store: store)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsNothing); + expect(find.text('Pipelines page'), findsOneWidget); + }); + + testWidgets('Done persists the seen record and no server query runs', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + final gateway = _FakeGateway(); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + await _finishWalkthrough(tester); + + expect(store.seen, isTrue); + expect( + gateway.calls, + isEmpty, + reason: 'first launch needs no server check', + ); + }); + + testWidgets('Skip on the first page persists the seen record', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + await tester.pumpWidget(_host(store: store)); + await tester.pumpAndSettle(); + + await tester.tap(find.byKey(const ValueKey('walkthrough.skip'))); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.seen, isTrue); + }); + + testWidgets('a seen device on an empty server is offered it once', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway(); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + expect(store.offered, {'server-a'}); + expect( + gateway.calls, + containsAll(['list_pipelines', 'list_runs', 'chat_sessions']), + ); + + await tester.tap(find.byKey(const ValueKey('walkthrough.skip'))); + await tester.pumpAndSettle(); + + // The server was offered already, so a fresh mount stays quiet. + await tester.pumpWidget(const SizedBox()); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsNothing); + }); + + testWidgets( + 'a seen device that starts disconnected is offered once it connects', + (tester) async { + // Startup order in the app: the Pipelines page mounts before the session + // has connected. The server must not be asked yet, and the offer must + // still happen after the connection arrives. + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway(); + final link = ValueNotifier(false); + await tester.pumpWidget( + _host(store: store, gateway: gateway, link: link), + ); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect( + gateway.calls, + isEmpty, + reason: 'no server call while disconnected', + ); + expect(store.offered, isEmpty); + + link.value = true; + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + expect(store.offered, {'server-a'}); + expect( + gateway.calls, + containsAll(['list_pipelines', 'list_runs', 'chat_sessions']), + ); + }, + ); + + testWidgets('an unreadable check is retried on the next connection', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway(failing: true); + final link = ValueNotifier(true); + await tester.pumpWidget(_host(store: store, gateway: gateway, link: link)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.offered, isEmpty); + final callsAfterFailure = gateway.calls.length; + + // A repeated notification while still connected does not re-query. + link.notifyListeners(); + await tester.pumpAndSettle(); + expect(gateway.calls.length, callsAfterFailure); + + // The server recovers; a fresh connection runs the check and offers it. + gateway.failing = false; + link.value = false; + await tester.pumpAndSettle(); + link.value = true; + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + expect(store.offered, {'server-a'}); + }); + + testWidgets('a seen device on a server with work is not offered', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway( + runs: [ + {'id': 'run-1'}, + ], + ); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.offered, isEmpty); + }); + + testWidgets('an unreadable server never triggers the walkthrough', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + await tester.pumpWidget( + _host(store: store, gateway: _FakeGateway(failing: true)), + ); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.offered, isEmpty); + }); + + testWidgets('the Pipelines page being hidden defers the check', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + await tester.pumpWidget(_host(store: store, enabled: false)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsNothing); + expect(store.seen, isFalse); + + await tester.pumpWidget(_host(store: store, enabled: true)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsOneWidget); + }); + + testWidgets( + 'hiding Pipelines while an offer is pending keeps the walkthrough closed', + (tester) async { + final inner = MemoryWalkthroughStore(); + final store = _HeldStore(inner)..hold(); + await tester.pumpWidget(_host(store: store)); + await tester.pump(); + + // The Pipelines page is hidden while the offer is still reading the store. + await tester.pumpWidget(_host(store: store, enabled: false)); + store.release(); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(inner.seen, isFalse); + + // Showing Pipelines again offers it once, on the same mount. + await tester.pumpWidget(_host(store: store, enabled: true)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsOneWidget); + }, + ); + + test('an unavailable preference store reports seen and offered', () async { + // The opener yields no preferences, as when the platform store is absent: + // every read reports "seen" and every write is quietly dropped. + const store = SharedPreferencesWalkthroughStore(open: _noPreferences); + expect(await store.isSeen(), isTrue); + expect(await store.wasOffered('server-a'), isTrue); + await store.markSeen(); + await store.markOffered('server-a'); + expect(await store.isSeen(), isTrue); + }); + + test( + 'SharedPreferences store records seen and offered under the keys', + () async { + SharedPreferences.setMockInitialValues({}); + const store = SharedPreferencesWalkthroughStore(); + expect(await store.isSeen(), isFalse); + await store.markSeen(); + expect(await store.isSeen(), isTrue); + + expect(await store.wasOffered('server-a'), isFalse); + await store.markOffered('server-a'); + expect(await store.wasOffered('server-a'), isTrue); + expect(await store.wasOffered('server-b'), isFalse); + }, + ); +} diff --git a/app/test/shell/attention_badge_test.dart b/app/test/shell/attention_badge_test.dart index 66348283..fd70c6d0 100644 --- a/app/test/shell/attention_badge_test.dart +++ b/app/test/shell/attention_badge_test.dart @@ -22,13 +22,16 @@ void main() { } for (final width in [390.0, 1000.0]) { - final mount = width < 600 ? 'bottom bar' : 'wide bar'; + final mount = width < 600 ? 'bottom bar' : 'rail'; + // The rail (wide) or the floating bar (phone) carries the same counts. + final navigation = width < 600 + ? find.byType(FloatingDestinationBar) + : find.byType(NavigationRail); testWidgets('$mount shows the count on the Runs tab', (tester) async { final semantics = tester.ensureSemantics(); await pumpShell(tester, width: width, count: 3); - expect(find.byType(FloatingDestinationBar), findsOneWidget); - expect(find.byType(NavigationRail), findsNothing); + expect(navigation, findsOneWidget); final badge = find.byKey(const ValueKey('shell.badge.runs.running')); expect(badge, findsOneWidget); expect( diff --git a/app/test/shell/floating_tab_bar_test.dart b/app/test/shell/floating_tab_bar_test.dart index ff55d732..6a0a8dfc 100644 --- a/app/test/shell/floating_tab_bar_test.dart +++ b/app/test/shell/floating_tab_bar_test.dart @@ -110,22 +110,23 @@ void main() { testWidgets('wide leading bar under the list, content ' 'keeps the width and taps beside the bar reach it', (tester) async { taps = 0; - await setSize(tester, const Size(1200, 800)); + await setSize(tester, const Size(640, 800)); await tester.pumpWidget(shell()); final rect = tester.getRect(pill()); // With no item open the bar still sits under the list column, where it // sits beside an open item, so it never jumps sides. expect(rect.left, moreOrLessEquals(kFloatingBarMargin, epsilon: 0.5)); expect(rect.bottom, 800 - 16); - expect(rect.width, lessThan(1200 * 0.6)); + expect(rect.width, lessThan(640 * 0.6)); // Captions participate in the bar's content-driven width. await expectLabeledTargets(tester, rect); await expectNoSharedBackdrop(tester); expect( rect.width, - lessThanOrEqualTo(listDetailListWidth(1200, 1200, null) - 2 * 16), + lessThanOrEqualTo(listDetailListWidth(640, 640, null) - 2 * 16), ); - // No rail or sidebar: the content starts at the left edge. + // Below the rail's window width (see kNavigationRailMinWindowWidth) the + // floating bar still sits under the list: no rail, content at the left edge. expect(find.byType(NavigationRail), findsNothing); expect(tester.getRect(find.byKey(const Key('content'))).left, 0); // Beside the bar, at the bar's height, the content takes the tap. @@ -141,7 +142,7 @@ void main() { testWidgets('content learns the bar height as bottom padding', ( tester, ) async { - for (final size in const [Size(390, 844), Size(1200, 800)]) { + for (final size in const [Size(390, 844), Size(640, 800)]) { await setSize(tester, size); await tester.pumpWidget(shell()); await tester.pump(); @@ -166,13 +167,13 @@ void main() { expect(find.text('taps 1'), findsOneWidget); final state = tester.state(find.byType(StatefulBuilder)); - tester.view.physicalSize = const Size(1200, 800); + tester.view.physicalSize = const Size(640, 800); await tester.pump(); expect( tester.getRect(pill()).left, moreOrLessEquals(kFloatingBarMargin, epsilon: 0.5), ); - expect(tester.getRect(pill()).width, lessThan(1200 * 0.6)); + expect(tester.getRect(pill()).width, lessThan(640 * 0.6)); expect(tester.state(find.byType(StatefulBuilder)), same(state)); tester.view.physicalSize = const Size(390, 844); diff --git a/app/test/shell/list_pane_resize_test.dart b/app/test/shell/list_pane_resize_test.dart index 1e961bfb..a43c516b 100644 --- a/app/test/shell/list_pane_resize_test.dart +++ b/app/test/shell/list_pane_resize_test.dart @@ -8,6 +8,7 @@ import 'package:pipelines_app/shell/destination.dart'; import 'package:pipelines_app/shell/list_detail.dart'; import 'package:pipelines_app/shell/list_pane_divider.dart'; import 'package:pipelines_app/shell/list_pane_widths.dart'; +import 'package:pipelines_app/shell/navigation_rail.dart'; import 'package:pipelines_app/shell/shell_bar.dart'; import 'package:pipelines_app/ui/adaptive/resize_grip.dart'; @@ -66,6 +67,7 @@ void main() { testWidgets('dragging resizes the list live, the shell bar ' 'follows, and the width clamps', (tester) async { await setSize(tester, const Size(1200, 800)); + const body = 1200 - kNavigationRailSpace; final store = MemoryListPaneWidthStore(); await tester.pumpWidget(shell(store: store)); await settle(tester); @@ -79,7 +81,7 @@ void main() { // Live, before the drag ends; nothing saved yet. expect(listWidth(tester), closeTo(340, 0.5)); expect(shellBarWidth(tester), closeTo(340, 0.5)); - expect(bodyWidth(tester), closeTo(1200 - 1 - 340, 0.5)); + expect(bodyWidth(tester), closeTo(body - 1 - 340, 0.5)); expect(store.values, isEmpty); await gesture.up(); await tester.pump(); @@ -92,9 +94,10 @@ void main() { // ...nor wider than leaves the open item half the window. await tester.drag(divider, const Offset(900, 0)); await settle(tester); - expect(listWidth(tester), closeTo(1200 - 1 - 600, 0.5)); - expect(shellBarWidth(tester), closeTo(599, 0.5)); - expect(store.values['runs'], closeTo(599, 0.5)); + // Half of the body for the open item, the list the rest. + expect(listWidth(tester), closeTo(body - 1 - body * 0.5, 0.5)); + expect(shellBarWidth(tester), closeTo(body - 1 - body * 0.5, 0.5)); + expect(store.values['runs'], closeTo(body - 1 - body * 0.5, 0.5)); }); testWidgets('a double tap returns to the default policy', (tester) async { @@ -143,8 +146,11 @@ void main() { final store = MemoryListPaneWidthStore({'runs': 600}); await tester.pumpWidget(shell(store: store)); await settle(tester); - expect(listWidth(tester), closeTo(1000 - 1 - 500, 0.5)); - expect(shellBarWidth(tester), closeTo(499, 0.5)); + // Beside the destination rail the panes lay out in the window's width + // less the rail, so the clamp is the body's: half of it for the open item. + const body = 1000 - kNavigationRailSpace; + expect(listWidth(tester), closeTo(body - 1 - body * 0.5, 0.5)); + expect(shellBarWidth(tester), closeTo(body - 1 - body * 0.5, 0.5)); expect(store.values['runs'], 600); await setSize(tester, const Size(1600, 800)); @@ -212,7 +218,8 @@ void main() { expect(grip().emphasized, isFalse); Focus.of(tester.element(divider)).requestFocus(); - await tester.pump(); + // The focus change reaches the grip one frame later beside the rail. + await tester.pumpAndSettle(); expect(grip().emphasized, isTrue); }); diff --git a/app/test/shell/navigation_rail_test.dart b/app/test/shell/navigation_rail_test.dart new file mode 100644 index 00000000..3b6030f7 --- /dev/null +++ b/app/test/shell/navigation_rail_test.dart @@ -0,0 +1,283 @@ +import 'dart:ui' show Tristate; + +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/shell/adaptive_shell.dart'; +import 'package:pipelines_app/shell/destination.dart'; +import 'package:pipelines_app/shell/list_detail.dart'; +import 'package:pipelines_app/shell/navigation_rail.dart'; +import 'package:pipelines_app/shell/shell_bar.dart'; +import 'package:pipelines_app/shell/windows/window_host.dart'; +import 'package:pipelines_app/ui/adaptive/floating_destination_bar.dart'; + +import 'windows/window_test_harness.dart'; + +/// On a wide window the destinations sit in a Material navigation rail at the +/// left edge (Settings pinned to its foot); narrower windows keep the floating +/// bar. The rail keeps the badges and the keys of the bar it replaces. +void main() { + Future pumpShell( + WidgetTester tester, { + required double width, + double height = 800, + int runningRunCount = 0, + bool withPanes = false, + }) async { + tester.view.physicalSize = Size(width, height); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + final shell = AdaptiveShell( + destination: withPanes ? AppDestination.runs : AppDestination.pipelines, + runningRunCount: runningRunCount, + destinationBodies: { + AppDestination.pipelines: (_) => const Text('pipelines body'), + AppDestination.runs: (_) => withPanes + ? ListDetailPanes( + list: const ShellBar(child: Text('runs list')), + detail: const Center(child: Text('runs detail')), + ) + : const Text('runs body'), + AppDestination.chat: (_) => const Text('chat body'), + AppDestination.search: (_) => const Text('search body'), + AppDestination.settings: (_) => const Text('settings body'), + }, + ); + await tester.pumpWidget(MaterialApp(home: shell)); + await tester.pumpAndSettle(); + } + + Finder rail() => find.byType(NavigationRail); + + Finder inRail(Finder finder) => find.descendant(of: rail(), matching: finder); + + testWidgets('a wide window shows a labelled rail at the left edge, full ' + 'height, with Settings pinned to its foot', (tester) async { + await pumpShell(tester, width: 1000); + + expect(rail(), findsOneWidget); + expect(find.byType(FloatingDestinationBar), findsNothing); + for (final label in ['Pipelines', 'Runs', 'Chat', 'Search', 'Settings']) { + expect(inRail(find.text(label)), findsOneWidget, reason: label); + } + final railRect = tester.getRect(rail()); + expect(railRect.left, 0); + expect(railRect.top, 0); + expect(railRect.height, 800); + expect(railRect.width, kNavigationRailWidth); + + // Settings sits below every tab, at the bottom of the rail. + final settings = tester.getRect( + find.byKey(const ValueKey('shell.destination.settings')), + ); + final runs = tester.getRect( + find.byKey(const ValueKey('shell.destination.runs')), + ); + expect(settings.top, greaterThan(runs.bottom)); + expect(settings.bottom, closeTo(railRect.bottom, 1)); + }); + + testWidgets('the rail marks the selected tab and one tap selects another', ( + tester, + ) async { + await pumpShell(tester, width: 1000); + expect(tester.widget(rail()).selectedIndex, 0); + expect(find.text('pipelines body'), findsOneWidget); + + await tester.tap(find.byKey(const ValueKey('shell.destination.runs'))); + await tester.pumpAndSettle(); + expect(tester.widget(rail()).selectedIndex, 1); + expect(find.text('runs body'), findsOneWidget); + }); + + testWidgets('Settings opens from the rail foot as a page and no tab is ' + 'selected meanwhile', (tester) async { + final semantics = tester.ensureSemantics(); + await pumpShell(tester, width: 1000); + + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); + await tester.pumpAndSettle(); + expect(find.text('settings body'), findsOneWidget); + expect(tester.widget(rail()).selectedIndex, isNull); + expect( + tester + .getSemantics(inRail(find.bySemanticsLabel('Settings'))) + .flagsCollection + .isSelected, + Tristate.isTrue, + ); + // The page's own Back returns to Pipelines, the tab it belongs to. + await tester.tap(find.byKey(const ValueKey('shell.back'))); + await tester.pumpAndSettle(); + expect(tester.widget(rail()).selectedIndex, 0); + semantics.dispose(); + }); + + testWidgets('the running count stays on the Runs item of the rail', ( + tester, + ) async { + await pumpShell(tester, width: 1000, runningRunCount: 3); + final badge = find.byKey(const ValueKey('shell.badge.runs.running')); + expect( + find.descendant(of: badge, matching: find.text('3')), + findsOneWidget, + ); + expect( + find.descendant( + of: find.byKey(const ValueKey('shell.destination.runs')), + matching: badge, + ), + findsOneWidget, + ); + }); + + testWidgets('a list and its open item lay out to the right of the rail', ( + tester, + ) async { + await pumpShell(tester, width: 1000, withPanes: true); + final list = tester.getRect(find.byKey(const ValueKey('list-detail-list'))); + final body = tester.getRect(find.byKey(const ValueKey('list-detail-body'))); + expect(list.left, closeTo(kNavigationRailSpace, 0.5)); + expect(body.right, closeTo(1000, 0.5)); + expect(body.left, greaterThan(list.right)); + }); + + testWidgets('the rail appears from the threshold width, and below it the ' + 'floating bar stays', (tester) async { + expect( + kNavigationRailMinWindowWidth, + kListDetailMinWidth + kNavigationRailSpace, + ); + + await pumpShell(tester, width: kNavigationRailMinWindowWidth - 1); + expect(rail(), findsNothing); + expect(find.byType(FloatingDestinationBar), findsOneWidget); + + await pumpShell(tester, width: kNavigationRailMinWindowWidth); + expect(rail(), findsOneWidget); + expect(find.byType(FloatingDestinationBar), findsNothing); + }); + + testWidgets('at the threshold the body beside the rail meets the list-detail ' + 'minimum, so the list sits beside its detail', (tester) async { + await pumpShell( + tester, + width: kNavigationRailMinWindowWidth, + withPanes: true, + ); + final list = tester.getRect(find.byKey(const ValueKey('list-detail-list'))); + final body = tester.getRect(find.byKey(const ValueKey('list-detail-body'))); + // The list and detail fill the window beside the rail, at the split + // threshold: the list starts after the rail and the detail ends at the + // window's right edge, with the detail to the right of the list. + expect(list.left, closeTo(kNavigationRailSpace, 0.5)); + expect(body.right, closeTo(kNavigationRailMinWindowWidth, 0.5)); + expect(body.left, greaterThan(list.right)); + }); + + testWidgets('phone and narrow windows keep the floating bar and no rail', ( + tester, + ) async { + for (final width in [390.0, 640.0]) { + await pumpShell(tester, width: width); + expect(rail(), findsNothing, reason: '$width'); + expect( + find.byKey(const ValueKey('shell.destination.settings')), + findsNothing, + reason: '$width', + ); + expect( + find.byType(FloatingDestinationBar), + findsOneWidget, + reason: '$width', + ); + } + }); + + testWidgets('floating windows keep to the right of the rail on a wide ' + 'window, and use the whole window without one', (tester) async { + final manager = probeManager(); + manager.open('probe', 'a'); + Future pumpWindows(double width) async { + tester.view.physicalSize = Size(width, 800); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.reset); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: Stack( + fit: StackFit.expand, + children: [ + const SizedBox.expand(), + Positioned.fill( + child: WindowHost(manager: manager, reservesRail: true), + ), + ], + ), + ), + ), + ); + await tester.pumpAndSettle(); + } + + await pumpWindows(1280); + // The probe window opens at x=100; beside the rail it starts after it. + expect( + windowRect(tester, 'Probe a').left, + closeTo(100 + kNavigationRailSpace, 0.5), + ); + await pumpWindows(500); + expect(windowRect(tester, 'Probe a').left, closeTo(100, 0.5)); + }); + + testWidgets('crossing the rail threshold keeps the destination mounted and ' + 'its state', (tester) async { + tester.view.physicalSize = Size(kNavigationRailMinWindowWidth - 1, 800); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + await tester.pumpWidget( + MaterialApp( + home: AdaptiveShell( + destination: AppDestination.runs, + destinationBodies: {AppDestination.runs: (_) => const _Counter()}, + ), + ), + ); + await tester.pumpAndSettle(); + await tester.tap(find.byKey(const ValueKey('counter.increment'))); + await tester.pump(); + final state = tester.state(find.byType(_Counter)); + + for (final width in [kNavigationRailMinWindowWidth, 390.0]) { + tester.view.physicalSize = Size(width, 800); + await tester.pumpAndSettle(); + expect( + tester.state(find.byType(_Counter)), + same(state), + reason: '$width', + ); + expect(find.text('count 1'), findsOneWidget, reason: '$width'); + } + }); +} + +class _Counter extends StatefulWidget { + const _Counter(); + + @override + State<_Counter> createState() => _CounterState(); +} + +class _CounterState extends State<_Counter> { + int _count = 0; + + @override + Widget build(BuildContext context) => Center( + child: TextButton( + key: const ValueKey('counter.increment'), + onPressed: () => setState(() => _count += 1), + child: Text('count $_count'), + ), + ); +} diff --git a/app/test/shell/pane_bar_row_test.dart b/app/test/shell/pane_bar_row_test.dart index 35955a87..f1387469 100644 --- a/app/test/shell/pane_bar_row_test.dart +++ b/app/test/shell/pane_bar_row_test.dart @@ -140,9 +140,9 @@ void main() { expect(find.text('Its context'), findsOneWidget); }); - testWidgets('1200: the item\'s tabs float at the bottom of its ' + testWidgets('640: the item\'s tabs float at the bottom of its ' 'pane, the shell\'s tab bar under the list', (tester) async { - await setSize(tester, const Size(1200, 800)); + await setSize(tester, const Size(640, 800)); await tester.pumpWidget(shell()); await tester.pump(); await tester.pump(); @@ -168,7 +168,7 @@ void main() { expect(shellTabs.bottom, closeTo(800 - kFloatingBarMargin, 0.5)); expect(shellTabs.right, lessThanOrEqualTo(list.right)); expect(itemTabs.bottom, closeTo(800 - kFloatingBarMargin, 0.5)); - expect(itemTabs.right, closeTo(1200 - kFloatingBarMargin, 0.5)); + expect(itemTabs.right, closeTo(640 - kFloatingBarMargin, 0.5)); expect(itemTabs.left, greaterThanOrEqualTo(body.left)); expect(itemTabs.overlaps(shellTabs), isFalse); // The item's list starts below its bar and clears its tabs at rest. diff --git a/app/test/shell/runs_pipelines_shortcut_test.dart b/app/test/shell/runs_pipelines_shortcut_test.dart new file mode 100644 index 00000000..3bf2a038 --- /dev/null +++ b/app/test/shell/runs_pipelines_shortcut_test.dart @@ -0,0 +1,208 @@ +import 'package:flutter/foundation.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/shell/adaptive_shell.dart'; +import 'package:pipelines_app/shell/destination.dart'; +import 'package:pipelines_app/shell/shell_runs_pipelines_shortcut.dart'; +import 'package:pipelines_app/ui/input/keyboard_owner.dart'; + +const _a = KeyDownEvent( + physicalKey: PhysicalKeyboardKey.keyA, + logicalKey: LogicalKeyboardKey.keyA, + timeStamp: Duration.zero, +); + +void main() { + test('Ctrl+A matches only with Ctrl alone', () { + bool chord(Set held, [KeyEvent event = _a]) => + shellRunsPipelinesShortcut(event, _FakeKeyboard(held)); + expect(chord({}), isFalse); + expect(chord({LogicalKeyboardKey.controlLeft}), isTrue); + expect(chord({LogicalKeyboardKey.controlRight}), isTrue); + expect( + chord({LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.altLeft}), + isFalse, + ); + expect( + chord({LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.shiftLeft}), + isFalse, + ); + expect( + chord({LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.metaLeft}), + isFalse, + ); + expect(chord({LogicalKeyboardKey.altLeft}), isFalse); + expect(chord({LogicalKeyboardKey.metaLeft}), isFalse); + expect( + shellRunsPipelinesShortcut( + const KeyUpEvent( + physicalKey: PhysicalKeyboardKey.keyA, + logicalKey: LogicalKeyboardKey.keyA, + timeStamp: Duration.zero, + ), + _FakeKeyboard({LogicalKeyboardKey.controlLeft}), + ), + isFalse, + ); + }); + + test('Runs goes to Pipelines; every other destination goes to Runs', () { + expect( + shellRunsPipelinesTarget(AppDestination.runs), + AppDestination.pipelines, + ); + expect( + shellRunsPipelinesTarget(AppDestination.pipelines), + AppDestination.runs, + ); + expect(shellRunsPipelinesTarget(AppDestination.chat), AppDestination.runs); + expect( + shellRunsPipelinesTarget(AppDestination.search), + AppDestination.runs, + ); + expect( + shellRunsPipelinesTarget(AppDestination.settings), + AppDestination.runs, + ); + }); + + testWidgets('Ctrl+A bounces Chat, Runs, Pipelines, Runs', (tester) async { + await _onAndroid(() async { + await tester.pumpWidget( + MaterialApp( + home: AdaptiveShell( + destinationBodies: { + for (final destination in shellTabDestinations) + destination: (_) => Text('${destination.name} body'), + }, + ), + ), + ); + expect(find.text('pipelines body'), isOnstage); + + Future pressCtrl(LogicalKeyboardKey key) async { + await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft); + await tester.sendKeyEvent(key); + await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft); + await tester.pumpAndSettle(); + } + + // Reach Chat first with Ctrl+K, then start the Ctrl+A sequence. + await pressCtrl(LogicalKeyboardKey.keyK); + expect(find.text('chat body'), isOnstage); + expect(find.text('pipelines body'), findsNothing); + + await pressCtrl(LogicalKeyboardKey.keyA); + expect(find.text('runs body'), isOnstage); + expect(find.text('chat body'), findsNothing); + + await pressCtrl(LogicalKeyboardKey.keyA); + expect(find.text('pipelines body'), isOnstage); + expect(find.text('runs body'), findsNothing); + + await pressCtrl(LogicalKeyboardKey.keyA); + expect(find.text('runs body'), isOnstage); + expect(find.text('pipelines body'), findsNothing); + expect(tester.takeException(), isNull); + }); + }); + + testWidgets('Ctrl+A is left to a focused text field', (tester) async { + await _onAndroid(() async { + final field = TextEditingController(text: 'draft message'); + final focus = FocusNode(); + addTearDown(field.dispose); + addTearDown(focus.dispose); + await tester.pumpWidget( + MaterialApp( + home: AdaptiveShell( + destinationBodies: { + AppDestination.pipelines: (_) => + TextField(controller: field, focusNode: focus), + AppDestination.runs: (_) => const Text('runs body'), + }, + ), + ), + ); + focus.requestFocus(); + await tester.pump(); + expect(focus.hasPrimaryFocus, isTrue); + + await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft); + await tester.sendKeyEvent(LogicalKeyboardKey.keyA); + await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft); + await tester.pumpAndSettle(); + + // Destination unchanged; the field took the chord (select all on this + // platform), so the text is still there and fully selected. + expect(find.text('runs body'), findsNothing); + expect(field.text, 'draft message'); + expect(field.selection.baseOffset, 0); + expect(field.selection.extentOffset, field.text.length); + expect(tester.takeException(), isNull); + }); + }); + + testWidgets('Ctrl+A is left to the terminal while it has focus', ( + tester, + ) async { + await _onAndroid(() async { + final terminal = FocusNode(); + addTearDown(terminal.dispose); + final received = []; + await tester.pumpWidget( + MaterialApp( + home: AdaptiveShell( + destinationBodies: { + AppDestination.pipelines: (_) => TypingSurface( + child: Focus( + focusNode: terminal, + onKeyEvent: (node, event) { + if (event.logicalKey == LogicalKeyboardKey.keyA) { + received.add(event); + } + return KeyEventResult.ignored; + }, + child: const Text('terminal'), + ), + ), + AppDestination.runs: (_) => const Text('runs body'), + }, + ), + ), + ); + terminal.requestFocus(); + await tester.pump(); + + await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft); + await tester.sendKeyEvent(LogicalKeyboardKey.keyA); + await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft); + await tester.pumpAndSettle(); + + expect(find.text('runs body'), findsNothing); + expect(find.text('terminal'), isOnstage); + expect(received.whereType(), hasLength(1)); + expect(tester.takeException(), isNull); + }); + }); +} + +/// Runs [body] with the platform pinned to Android, so Ctrl+A in a text field +/// means select all everywhere. flutter_test requires the debug override to be +/// cleared before the test body returns, hence the `finally`. +Future _onAndroid(Future Function() body) async { + debugDefaultTargetPlatformOverride = TargetPlatform.android; + try { + await body(); + } finally { + debugDefaultTargetPlatformOverride = null; + } +} + +class _FakeKeyboard extends HardwareKeyboard { + _FakeKeyboard(this.pressed); + final Set pressed; + @override + bool isLogicalKeyPressed(LogicalKeyboardKey key) => pressed.contains(key); +} diff --git a/app/test/shell/split_destination_bar_test.dart b/app/test/shell/split_destination_bar_test.dart index 5da220a7..c0e7c2e9 100644 --- a/app/test/shell/split_destination_bar_test.dart +++ b/app/test/shell/split_destination_bar_test.dart @@ -106,7 +106,7 @@ void main() { .first, ); - for (final width in [1200.0, 1600.0]) { + for (final width in [600.0, 640.0]) { testWidgets('$width split: the destination bar sits under the ' 'list and the composer at the detail\'s bottom edge', (tester) async { await setSize(tester, Size(width, 800)); @@ -211,11 +211,12 @@ void main() { }); } - testWidgets('1200 split: the bar follows a dragged list width', ( + testWidgets('640 split: the bar follows a dragged list width', ( tester, ) async { - await setSize(tester, const Size(1200, 800)); - for (final width in [300.0, 520.0]) { + await setSize(tester, const Size(640, 800)); + // Within a 640 window's list bounds (at most 0.6 of it, less the body). + for (final width in [260.0, 300.0]) { final store = MemoryListPaneWidthStore({'chat': width}); await tester.pumpWidget( KeyedSubtree( @@ -235,26 +236,26 @@ void main() { } }); - testWidgets('1200 Settings: a page without a list keeps the bar ' + testWidgets('640 Settings: a page without a list keeps the bar ' 'at the right edge', (tester) async { - await setSize(tester, const Size(1200, 800)); + await setSize(tester, const Size(640, 800)); await tester.pumpWidget(shell(destination: AppDestination.settings)); await tester.pump(); final pill = destinationPill(tester); - expect(pill.right, closeTo(1200 - kFloatingBarMargin, 0.5)); + expect(pill.right, closeTo(640 - kFloatingBarMargin, 0.5)); }); - testWidgets('1200 unsplit: the bar stays under the list column', ( + testWidgets('640 unsplit: the bar stays under the list column', ( tester, ) async { - await setSize(tester, const Size(1200, 800)); + await setSize(tester, const Size(640, 800)); await tester.pumpWidget(shell(split: false)); await tester.pump(); final pill = destinationPill(tester); // Same place as beside an open item (Search has no split), so opening // or closing an item never moves the bar across the window. expect(pill.left, closeTo(kFloatingBarMargin, 0.5)); - expect(pill.width, lessThan(1200 * 0.6)); + expect(pill.width, lessThan(640 * 0.6)); }); testWidgets('390: the bar hugs its tabs at the phone\'s bottom ' @@ -277,7 +278,7 @@ void main() { expect(pill.right, closeTo(390 - kFloatingBarMargin, 0.5)); }); - for (final width in [600.0, 840.0]) { + for (final width in [600.0, 640.0]) { testWidgets('$width split at 2x: the bar fits the list pane and ' 'the item tabs the detail, without overflow', (tester) async { await setSize(tester, Size(width, 800)); diff --git a/app/test/shell/split_detail_pages_test.dart b/app/test/shell/split_detail_pages_test.dart index cef81444..5ed854c6 100644 --- a/app/test/shell/split_detail_pages_test.dart +++ b/app/test/shell/split_detail_pages_test.dart @@ -36,7 +36,7 @@ void main() { ); Future pumpSplitRun(WidgetTester tester) async { - tester.view.physicalSize = const Size(1200, 800); + tester.view.physicalSize = const Size(640, 800); tester.view.devicePixelRatio = 1; addTearDown(tester.view.reset); final gateway = RunDetailFakeGateway(visitRunFixture()); @@ -71,7 +71,7 @@ void main() { await tester.pumpAndSettle(); } - testWidgets('1200: run tabs float at the pane\'s bottom beside the ' + testWidgets('640: run tabs float at the pane\'s bottom beside the ' 'shell bar under the list, and the stage page opens in the pane', ( tester, ) async { @@ -84,7 +84,7 @@ void main() { final runTabs = pillOf(tester, find.byKey(const Key('run-detail-tabs'))); expect(runTabs.left, greaterThanOrEqualTo(body.left)); - expect(runTabs.right, closeTo(1200 - kFloatingBarMargin, 0.5)); + expect(runTabs.right, closeTo(640 - kFloatingBarMargin, 0.5)); expect(runTabs.overlaps(main), isFalse); expect(runTabs.bottom, closeTo(800 - kFloatingBarMargin, 0.5)); diff --git a/app/test/shell/split_status_bar_test.dart b/app/test/shell/split_status_bar_test.dart index 382b4fc5..40432fd3 100644 --- a/app/test/shell/split_status_bar_test.dart +++ b/app/test/shell/split_status_bar_test.dart @@ -158,7 +158,7 @@ void main() { testWidgets('split: the item tabs sit at the bottom right of the ' 'detail pane, the shell tab bar under the list', (tester) async { // A gesture-navigation inset as on the unfolded foldable. - await setUp(tester, const Size(1200, 800), bottom: 24); + await setUp(tester, const Size(640, 800), bottom: 24); await tester.pumpWidget(shell(tabbedItem())); await tester.pump(); await tester.pump(); @@ -188,7 +188,7 @@ void main() { expect(shellTabs.bottom, closeTo(800 - 24, 0.5)); expect(shellTabs.right, lessThanOrEqualTo(listPane.right)); expect(tabs.bottom, closeTo(800 - 24, 0.5)); - expect(tabs.right, closeTo(1200 - kFloatingBarMargin, 0.5)); + expect(tabs.right, closeTo(640 - kFloatingBarMargin, 0.5)); expect(shellTabs.overlaps(tabs), isFalse); // The item's list clears its tabs at rest. final list = tester.element(find.byKey(const Key('item-list')));