feat(app): page the run Changes surface one recorded visit at a time

The run-wide header, note, filter and matched-path counter still describe
every visit; below them Previous/Next move through the recorded visits in
run order without wrapping, and the shown visit keeps its own stage and
Visit N heading. A single recorded visit renders no pager.
This commit is contained in:
2026-10-22 15:56:30 +01:00
parent 6b021f1483
commit 9532ecddcf
7 changed files with 442 additions and 38 deletions
@@ -180,5 +180,6 @@ List<FileChange> filterFileChanges(Iterable<FileChange> files, String query) {
.toList(growable: false); .toList(growable: false);
} }
/// The `N of M` position label a viewer can show for its open file. /// The `N of M` position label a viewer can show for its open file or for the
/// Changes visit on screen.
String changePositionLabel(int index, int count) => '${index + 1} of $count'; String changePositionLabel(int index, int count) => '${index + 1} of $count';
@@ -8,11 +8,17 @@ import '../domain/run_changes.dart';
import 'capture_section.dart'; import 'capture_section.dart';
import 'change_style.dart'; import 'change_style.dart';
import 'file_diff_viewer.dart'; import 'file_diff_viewer.dart';
import 'visit_pager.dart';
/// The run's Changes surface: an honest final-state summary followed by one /// The run's Changes surface: an honest final-state summary followed by the
/// section per stage/visit capture, with changed-filename filtering and the /// recorded stage/visit captures, with changed-filename filtering and the
/// reusable single-file diff viewer. /// reusable single-file diff viewer.
/// ///
/// The run-wide header and filter always describe the whole run. Below them the
/// viewer shows one recorded visit at a time and offers Previous/Next paging
/// through the rest in run order, so a long run stays readable without changing
/// the aggregate. The shown visit keeps its own stage/visit heading.
///
/// The viewer fills the available height, so give it a bounded parent (a /// The viewer fills the available height, so give it a bounded parent (a
/// Scaffold body, tab body or Expanded child). It never opens its own socket or /// Scaffold body, tab body or Expanded child). It never opens its own socket or
/// requests data; the caller passes the run detail's `steps`. /// requests data; the caller passes the run detail's `steps`.
@@ -45,6 +51,10 @@ class _ChangesViewerState extends State<ChangesViewer> {
late List<StageCapture> _captures; late List<StageCapture> _captures;
late RunChanges _run; late RunChanges _run;
/// The zero-based position of the shown visit in [_captures] (run order).
/// The page opens at the first recorded visit; Previous/Next never wrap.
int _visitIndex = 0;
@override @override
void initState() { void initState() {
super.initState(); super.initState();
@@ -62,6 +72,19 @@ class _ChangesViewerState extends State<ChangesViewer> {
void _derive() { void _derive() {
_captures = stageCaptures(widget.steps); _captures = stageCaptures(widget.steps);
_run = runChangesFor(_captures); _run = runChangesFor(_captures);
// A fresh reply may have fewer recorded visits; never point past the end.
_visitIndex = _clampVisit(_visitIndex, _captures.length);
}
static int _clampVisit(int index, int count) {
if (count <= 0 || index < 0) return 0;
return index >= count ? count - 1 : index;
}
void _stepVisit(int delta) {
final next = _clampVisit(_visitIndex + delta, _captures.length);
if (next == _visitIndex) return;
setState(() => _visitIndex = next);
} }
@override @override
@@ -81,6 +104,7 @@ class _ChangesViewerState extends State<ChangesViewer> {
(visit) => visit.capture?.files.isNotEmpty ?? false, (visit) => visit.capture?.files.isNotEmpty ?? false,
); );
final note = showSummary ? runChangesNote(run) : ''; final note = showSummary ? runChangesNote(run) : '';
final visit = captures.isEmpty ? null : captures[_visitIndex];
return Column( return Column(
crossAxisAlignment: CrossAxisAlignment.stretch, crossAxisAlignment: CrossAxisAlignment.stretch,
children: [ children: [
@@ -107,8 +131,8 @@ class _ChangesViewerState extends State<ChangesViewer> {
padding: const EdgeInsets.only(top: 8), padding: const EdgeInsets.only(top: 8),
child: Text( child: Text(
'The summary counts each path once, as the last recorded ' 'The summary counts each path once, as the last recorded '
'visit left it. Each stage/visit below lists what its own ' 'visit left it. Each stage/visit page below lists what '
'capture recorded.', 'its own capture recorded.',
style: Theme.of(context).textTheme.bodySmall, style: Theme.of(context).textTheme.bodySmall,
), ),
), ),
@@ -122,27 +146,33 @@ class _ChangesViewerState extends State<ChangesViewer> {
), ),
if (showSummary) const Divider(height: 1), if (showSummary) const Divider(height: 1),
Expanded( Expanded(
child: captures.isEmpty child: visit == null
? SingleChildScrollView( ? SingleChildScrollView(
padding: const EdgeInsets.all(16), padding: const EdgeInsets.all(16),
child: Text(noChangeDetail(run)), child: Text(noChangeDetail(run)),
) )
: ListView.builder( : SingleChildScrollView(
itemCount: captures.length, // Keying the body by visit keeps each page's pager and heading
itemBuilder: (context, index) { // at the top instead of inheriting the previous scroll offset.
final visit = captures[index]; key: ValueKey<String>(
return Column( 'changes-visit-${visit.stage}-${visit.sequence}',
crossAxisAlignment: CrossAxisAlignment.stretch, ),
children: [ child: Column(
StageCaptureSection( crossAxisAlignment: CrossAxisAlignment.stretch,
stage: visit, children: [
query: _query, ChangesVisitPager(
onOpen: (file) => showFileDiffViewer(context, file), index: _visitIndex,
), count: captures.length,
const Divider(height: 1), onPrevious: () => _stepVisit(-1),
], onNext: () => _stepVisit(1),
); ),
}, StageCaptureSection(
stage: visit,
query: _query,
onOpen: (file) => showFileDiffViewer(context, file),
),
],
),
), ),
), ),
], ],
@@ -0,0 +1,111 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../domain/change_wording.dart';
import 'change_style.dart';
/// The Changes page's Previous/Next pager over the run's recorded stage visits.
///
/// It only moves between the captures the viewer already holds and never wraps:
/// the first recorded visit has no previous page and the last none after it.
/// The shown visit's own heading (its stage and visit number) stays with the
/// capture section below, so paging never loses which visit is on screen.
class ChangesVisitPager extends StatelessWidget {
const ChangesVisitPager({
super.key,
required this.index,
required this.count,
required this.onPrevious,
required this.onNext,
});
static const previousKey = ValueKey<String>('changes-previous-visit');
static const nextKey = ValueKey<String>('changes-next-visit');
/// The shown visit's zero-based position in the run's recorded visits.
final int index;
final int count;
final VoidCallback onPrevious;
final VoidCallback onNext;
@override
Widget build(BuildContext context) {
if (count <= 1) return const SizedBox.shrink();
final hasPrevious = index > 0;
final hasNext = index < count - 1;
return Padding(
padding: const EdgeInsetsDirectional.fromSTEB(16, 8, 16, 0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Text(
'${changePositionLabel(index, count)} recorded visits',
key: const ValueKey<String>('changes-visit-position'),
textAlign: TextAlign.center,
style: Theme.of(context).textTheme.bodySmall,
),
const SizedBox(height: 4),
// A `Wrap` keeps both controls whole and lets them take separate
// lines at large text sizes or on a narrow page.
Wrap(
alignment: WrapAlignment.spaceBetween,
spacing: 8,
runSpacing: 4,
children: [
_button(
context,
key: previousKey,
label: 'Previous visit',
enabled: hasPrevious,
onPressed: onPrevious,
previous: true,
),
_button(
context,
key: nextKey,
label: 'Next visit',
enabled: hasNext,
onPressed: onNext,
previous: false,
),
],
),
],
),
);
}
Widget _button(
BuildContext context, {
required Key key,
required String label,
required bool enabled,
required VoidCallback onPressed,
required bool previous,
}) {
if (usesCupertino(context)) {
return CupertinoButton(
key: key,
padding: EdgeInsets.zero,
onPressed: enabled ? onPressed : null,
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
Icon(
previous ? CupertinoIcons.back : CupertinoIcons.forward,
size: 20,
),
const SizedBox(width: 4),
Text(label),
],
),
);
}
return TextButton.icon(
key: key,
onPressed: enabled ? onPressed : null,
icon: Icon(previous ? Icons.arrow_back : Icons.arrow_forward),
label: Text(label),
);
}
}
@@ -3,6 +3,7 @@ import 'package:flutter/material.dart';
import 'package:flutter/services.dart'; import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart'; import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/changes/changes.dart'; import 'package:pipelines_app/features/changes/changes.dart';
import 'package:pipelines_app/features/changes/widgets/visit_pager.dart';
import 'fixtures.dart'; import 'fixtures.dart';
import 'widget_hosts.dart'; import 'widget_hosts.dart';
@@ -91,7 +92,7 @@ void main() {
expect(find.text(emptyCaptureDetail), findsNothing); expect(find.text(emptyCaptureDetail), findsNothing);
}); });
testWidgets('stage/visit sections keep partial status, counters and scope', ( testWidgets('stage/visit pages keep partial status, counters and scope', (
tester, tester,
) async { ) async {
final diagnostic = 'Excluded protected files.'; final diagnostic = 'Excluded protected files.';
@@ -121,11 +122,10 @@ void main() {
), ),
), ),
); );
// The run-wide aggregate still counts the file this visit recorded.
expect(find.textContaining('1 file changed'), findsOneWidget);
expect(find.text('implementer'), findsOneWidget); expect(find.text('implementer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget); expect(find.text('Visit 1 · completed'), findsOneWidget);
// The reviewer's first visit is Visit 1, not the run-wide step ordinal 2.
expect(find.text('Visit 1 · failed'), findsOneWidget);
expect(find.text('Visit 2 · failed'), findsNothing);
expect( expect(
find.text( find.text(
'partial (1 files), 1 skipped, 2 omitted · Excluded protected files.', 'partial (1 files), 1 skipped, 2 omitted · Excluded protected files.',
@@ -136,18 +136,24 @@ void main() {
find.text('Scope: Git tracked and nonignored files in the run directory'), find.text('Scope: Git tracked and nonignored files in the run directory'),
findsOneWidget, findsOneWidget,
); );
// The second visit is its own page, not a second section.
expect(find.text('reviewer'), findsNothing);
expect(find.text(missingCaptureDetail), findsNothing);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
expect(find.text('implementer'), findsNothing);
expect(find.text('reviewer'), findsOneWidget); expect(find.text('reviewer'), findsOneWidget);
// The reviewer's first visit is Visit 1, not the run-wide step ordinal 2.
expect(find.text('Visit 1 · failed'), findsOneWidget);
expect(find.text('Visit 2 · failed'), findsNothing);
expect(find.text(missingCaptureDetail), findsOneWidget); expect(find.text(missingCaptureDetail), findsOneWidget);
expect(find.textContaining('partial capture'), findsWidgets);
}); });
testWidgets( testWidgets(
'repeated stages number their own visits and honour control.visit', 'repeated stages number their own visits and honour control.visit',
(tester) async { (tester) async {
// Tall enough that the lazy list builds every section.
tester.view.physicalSize = const Size(800, 1400);
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.reset);
await tester.pumpWidget( await tester.pumpWidget(
materialHost( materialHost(
ChangesViewer( ChangesViewer(
@@ -177,11 +183,27 @@ void main() {
), ),
), ),
); );
// Both stages' first recorded visits are Visit 1; the run-wide step // Pages are in run order; each stage numbers its own visits, so the
// ordinals (1-4) must not leak into the label. // run-wide step ordinals (1-4) must not leak into the label.
expect(find.text('Visit 1 · completed'), findsNWidgets(2)); expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('Visit 2 · completed'), findsNothing);
expect(find.text('Visit 6 · completed'), findsNothing);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
// The reviewer's first recorded visit is Visit 1 too.
expect(find.text('reviewer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
expect(find.text('implementer'), findsOneWidget);
expect(find.text('Visit 2 · completed'), findsOneWidget); expect(find.text('Visit 2 · completed'), findsOneWidget);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
// The resumed reviewer visit records control.visit 6. // The resumed reviewer visit records control.visit 6.
expect(find.text('reviewer'), findsOneWidget);
expect(find.text('Visit 6 · completed'), findsOneWidget); expect(find.text('Visit 6 · completed'), findsOneWidget);
expect(find.text('Visit 3 · completed'), findsNothing); expect(find.text('Visit 3 · completed'), findsNothing);
expect(find.text('Visit 4 · completed'), findsNothing); expect(find.text('Visit 4 · completed'), findsNothing);
@@ -0,0 +1,222 @@
import 'package:flutter/cupertino.dart';
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/changes/changes.dart';
import 'package:pipelines_app/features/changes/widgets/visit_pager.dart';
import 'fixtures.dart';
import 'widget_hosts.dart';
List<JsonMap> twoVisitRun() => [
stepFixture(
stage: 'implementer',
sequence: 1,
fileChanges: captureFixture(
files: [
fileChangeFixture(path: 'lib/a.dart'),
fileChangeFixture(path: 'lib/b.dart'),
],
),
),
stepFixture(
stage: 'reviewer',
sequence: 2,
fileChanges: captureFixture(
files: [
fileChangeFixture(path: 'lib/b.dart'),
fileChangeFixture(path: 'lib/c.dart'),
],
),
),
];
void main() {
testWidgets(
'Previous/Next page recorded visits while the aggregate stays run-wide',
(tester) async {
await tester.pumpWidget(
materialHost(ChangesViewer(steps: twoVisitRun())),
);
// The aggregate counts each path once across both visits, and does not
// change as the operator pages.
expect(find.text('3 files changed'), findsOneWidget);
expect(find.text('1 of 2 recorded visits'), findsOneWidget);
expect(find.text('implementer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('lib/a.dart'), findsOneWidget);
expect(find.text('lib/c.dart'), findsNothing);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
// The shown page keeps its own visit identity in the heading.
expect(find.text('reviewer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('lib/c.dart'), findsOneWidget);
expect(find.text('lib/a.dart'), findsNothing);
expect(find.text('3 files changed'), findsOneWidget);
expect(find.text('2 of 2 recorded visits'), findsOneWidget);
await tester.tap(find.byKey(ChangesVisitPager.previousKey));
await tester.pump();
expect(find.text('implementer'), findsOneWidget);
expect(find.text('lib/a.dart'), findsOneWidget);
expect(find.text('lib/c.dart'), findsNothing);
expect(find.text('1 of 2 recorded visits'), findsOneWidget);
},
);
testWidgets('paging stops at both ends instead of wrapping', (tester) async {
await tester.pumpWidget(materialHost(ChangesViewer(steps: twoVisitRun())));
TextButton previous() =>
tester.widget<TextButton>(find.byKey(ChangesVisitPager.previousKey));
TextButton next() =>
tester.widget<TextButton>(find.byKey(ChangesVisitPager.nextKey));
expect(previous().onPressed, isNull);
expect(next().onPressed, isNotNull);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
expect(previous().onPressed, isNotNull);
expect(next().onPressed, isNull);
// The disabled Next is inert; the page stays on the last visit.
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
expect(find.text('reviewer'), findsOneWidget);
await tester.tap(find.byKey(ChangesVisitPager.previousKey));
await tester.pump();
expect(find.text('implementer'), findsOneWidget);
expect(previous().onPressed, isNull);
});
testWidgets('a run with one recorded visit offers no pager', (tester) async {
await tester.pumpWidget(
materialHost(
ChangesViewer(
steps: [
stepFixture(
fileChanges: captureFixture(
files: [fileChangeFixture(path: 'lib/only.dart')],
),
),
],
),
),
);
expect(find.text('Previous visit'), findsNothing);
expect(find.text('Next visit'), findsNothing);
expect(find.textContaining('recorded visits'), findsNothing);
// The single visit still keeps its identity heading.
expect(find.text('implementer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('lib/only.dart'), findsOneWidget);
});
testWidgets('the filter and its aggregate counter survive paging', (
tester,
) async {
await tester.pumpWidget(materialHost(ChangesViewer(steps: twoVisitRun())));
await tester.enterText(find.byType(TextField), 'a.dart');
await tester.pump();
expect(find.text('1 of 3 changed paths match'), findsOneWidget);
expect(find.text('lib/a.dart'), findsOneWidget);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
// The filter still applies to the shown visit, and the counter still
// describes the whole run's changed paths.
expect(find.text('1 of 3 changed paths match'), findsOneWidget);
expect(find.text('No changed filenames match "a.dart".'), findsOneWidget);
expect(find.text('lib/c.dart'), findsNothing);
expect(find.text('reviewer'), findsOneWidget);
});
testWidgets('a shorter reply clamps the shown visit instead of overflowing', (
tester,
) async {
final first = twoVisitRun();
final second = [
stepFixture(
stage: 'implementer',
sequence: 1,
fileChanges: captureFixture(
files: [fileChangeFixture(path: 'lib/a.dart')],
),
),
];
await tester.pumpWidget(materialHost(ChangesViewer(steps: first)));
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
expect(find.text('reviewer'), findsOneWidget);
await tester.pumpWidget(materialHost(ChangesViewer(steps: second)));
await tester.pump();
expect(tester.takeException(), isNull);
expect(find.text('implementer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('Previous visit'), findsNothing);
});
testWidgets('the pager stays reachable at 320x720 with 2x text', (
tester,
) async {
tester.view.physicalSize = const Size(320, 720);
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.reset);
await tester.pumpWidget(
materialHost(
ChangesViewer(steps: twoVisitRun()),
scaler: const TextScaler.linear(2),
),
);
expect(tester.takeException(), isNull);
expect(find.text('Previous visit'), findsOneWidget);
expect(find.text('Next visit'), findsOneWidget);
// At 2x text the fixed summary and filter leave a short scroll viewport;
// the pager is still reachable by scrolling the visit body.
await tester.ensureVisible(find.text('Next visit'));
await tester.pump();
await tester.tap(find.text('Next visit'));
await tester.pump();
expect(tester.takeException(), isNull);
expect(find.text('reviewer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('lib/c.dart'), findsOneWidget);
});
testWidgets('Cupertino pages with native buttons at both ends', (
tester,
) async {
await tester.pumpWidget(cupertinoHost(ChangesViewer(steps: twoVisitRun())));
final previous = tester.widget<CupertinoButton>(
find.byKey(ChangesVisitPager.previousKey),
);
final next = tester.widget<CupertinoButton>(
find.byKey(ChangesVisitPager.nextKey),
);
expect(previous.onPressed, isNull);
expect(next.onPressed, isNotNull);
expect(find.text('Previous visit'), findsOneWidget);
expect(find.text('Next visit'), findsOneWidget);
await tester.tap(find.byKey(ChangesVisitPager.nextKey));
await tester.pump();
expect(find.text('reviewer'), findsOneWidget);
expect(
tester
.widget<CupertinoButton>(find.byKey(ChangesVisitPager.nextKey))
.onPressed,
isNull,
);
});
}
@@ -112,8 +112,19 @@ void main() {
find.text('1 file changed · +2 -2 · capture incomplete'), find.text('1 file changed · +2 -2 · capture incomplete'),
findsOneWidget, findsOneWidget,
); );
// Visit numbers are per stage, so both stages' first visits say Visit 1. // The page opens on the run's first recorded visit; its stage/visit
expect(find.text('Visit 1 · completed'), findsNWidgets(2)); // heading identifies the evidence, and Next reaches the second visit.
expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('implementer'), findsOneWidget);
expect(find.text('Next visit'), findsOneWidget);
await tester.tap(find.text('Next visit'));
await tester.pump();
expect(find.text('reviewer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
expect(find.text('lib/feature.dart'), findsNothing);
await tester.tap(find.text('Previous visit'));
await tester.pump();
expect(find.text('lib/feature.dart'), findsOneWidget);
await tester.tap( await tester.tap(
find.byKey(const ValueKey('change-1-lib/feature.dart')), find.byKey(const ValueKey('change-1-lib/feature.dart')),
@@ -2,6 +2,7 @@ import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart'; import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart'; import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart'; import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/changes/changes.dart';
import 'package:pipelines_app/features/runs/data/runs_repository.dart'; import 'package:pipelines_app/features/runs/data/runs_repository.dart';
import 'package:pipelines_app/features/runs/ui/run_changes_action.dart'; import 'package:pipelines_app/features/runs/ui/run_changes_action.dart';
import 'package:pipelines_app/features/runs/ui/run_detail_view.dart'; import 'package:pipelines_app/features/runs/ui/run_detail_view.dart';
@@ -138,9 +139,15 @@ void main() {
find.textContaining('The summary counts each path once'), find.textContaining('The summary counts each path once'),
findsNothing, findsNothing,
); );
// The visit's own recorded capture stays reachable. // The visit's own recorded capture stays reachable, one visit page at
// a time; the second visit's gap is reachable with Next.
expect(find.text('lib/feature.dart'), findsOneWidget); expect(find.text('lib/feature.dart'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsNWidgets(2)); expect(find.text('implementer'), findsOneWidget);
expect(find.text('Visit 1 · completed'), findsOneWidget);
await tester.tap(find.text('Next visit'));
await tester.pump();
expect(find.text('reviewer'), findsOneWidget);
expect(find.text(missingCaptureDetail), findsOneWidget);
expect(tester.takeException(), isNull); expect(tester.takeException(), isNull);
}, },
); );