Files
pipelines/app/lib/features/changes/widgets/changes_viewer.dart
T
alan 9532ecddcf 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.
2026-10-22 15:56:30 +01:00

231 lines
8.1 KiB
Dart

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../core/api_gateway.dart';
import '../domain/change_capture.dart';
import '../domain/change_wording.dart';
import '../domain/run_changes.dart';
import 'capture_section.dart';
import 'change_style.dart';
import 'file_diff_viewer.dart';
import 'visit_pager.dart';
/// The run's Changes surface: an honest final-state summary followed by the
/// recorded stage/visit captures, with changed-filename filtering and the
/// 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
/// Scaffold body, tab body or Expanded child). It never opens its own socket or
/// requests data; the caller passes the run detail's `steps`.
class ChangesViewer extends StatefulWidget {
const ChangesViewer({
super.key,
required this.steps,
this.showSummary = true,
});
/// The run detail's steps exactly as the server returned them. Each step's
/// `file_changes` may be null (no capture), a complete/partial/unavailable
/// capture, or a capture with zero files (a recorded no-change).
///
/// Pass a stable list: the same instance until the server reply changes. The
/// captures and the summary are derived from it rather than on every rebuild.
final List<JsonMap> steps;
/// Whether the run-wide final-state header and filter are shown. The web
/// client gates its aggregate on [showRunChangesSummary]; the per-stage
/// sections stay the evidence for a run without a settled final state.
final bool showSummary;
@override
State<ChangesViewer> createState() => _ChangesViewerState();
}
class _ChangesViewerState extends State<ChangesViewer> {
final _filter = TextEditingController();
late List<StageCapture> _captures;
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
void initState() {
super.initState();
_derive();
}
@override
void didUpdateWidget(ChangesViewer oldWidget) {
super.didUpdateWidget(oldWidget);
// Filter keystrokes rebuild this widget with the same steps list; only a
// new server reply re-derives the captures and the aggregate.
if (!identical(oldWidget.steps, widget.steps)) _derive();
}
void _derive() {
_captures = stageCaptures(widget.steps);
_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
void dispose() {
_filter.dispose();
super.dispose();
}
String get _query => _filter.text;
@override
Widget build(BuildContext context) {
final run = _run;
final captures = _captures;
final showSummary = widget.showSummary;
final hasFiles = captures.any(
(visit) => visit.capture?.files.isNotEmpty ?? false,
);
final note = showSummary ? runChangesNote(run) : '';
final visit = captures.isEmpty ? null : captures[_visitIndex];
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
if (showSummary)
Padding(
padding: const EdgeInsets.fromLTRB(16, 16, 16, 8),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
runChangesHeader(run),
style: Theme.of(context).textTheme.titleMedium,
),
if (note.isNotEmpty)
Padding(
padding: const EdgeInsets.only(top: 4),
child: Text(
note,
style: Theme.of(context).textTheme.bodySmall,
),
),
if (hasFiles)
Padding(
padding: const EdgeInsets.only(top: 8),
child: Text(
'The summary counts each path once, as the last recorded '
'visit left it. Each stage/visit page below lists what '
'its own capture recorded.',
style: Theme.of(context).textTheme.bodySmall,
),
),
],
),
),
if (showSummary && hasFiles)
Padding(
padding: const EdgeInsets.fromLTRB(16, 0, 16, 8),
child: _filterField(context, run),
),
if (showSummary) const Divider(height: 1),
Expanded(
child: visit == null
? SingleChildScrollView(
padding: const EdgeInsets.all(16),
child: Text(noChangeDetail(run)),
)
: SingleChildScrollView(
// Keying the body by visit keeps each page's pager and heading
// at the top instead of inheriting the previous scroll offset.
key: ValueKey<String>(
'changes-visit-${visit.stage}-${visit.sequence}',
),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
ChangesVisitPager(
index: _visitIndex,
count: captures.length,
onPrevious: () => _stepVisit(-1),
onNext: () => _stepVisit(1),
),
StageCaptureSection(
stage: visit,
query: _query,
onOpen: (file) => showFileDiffViewer(context, file),
),
],
),
),
),
],
);
}
Widget _filterField(BuildContext context, RunChanges run) {
final query = _query;
final matched = query.trim().isEmpty
? run.files.length
: filterFileChanges(run.files, query).length;
// The summary counts paths while the sections below list one row per stage
// visit, so the counter names what it actually counts.
final counter = query.trim().isEmpty
? ''
: '$matched of ${run.files.length} changed '
'${run.files.length == 1 ? 'path' : 'paths'} match';
final field = usesCupertino(context)
? CupertinoSearchTextField(
controller: _filter,
placeholder: 'Filter changed files',
onChanged: (_) => setState(() {}),
)
: TextField(
controller: _filter,
decoration: InputDecoration(
labelText: 'Filter changed files',
hintText: 'Filename contains…',
prefixIcon: const Icon(Icons.search),
suffixIcon: query.isEmpty
? null
: IconButton(
tooltip: 'Clear filter',
onPressed: () {
_filter.clear();
setState(() {});
},
icon: const Icon(Icons.clear),
),
),
onChanged: (_) => setState(() {}),
);
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
field,
if (counter.isNotEmpty)
Padding(
padding: const EdgeInsets.only(top: 4),
child: Text(counter, style: Theme.of(context).textTheme.bodySmall),
),
],
);
}
}