From 4f789038c4b7ae40744ea92a9b1fece0df0aaeec Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 23 Oct 2026 19:29:20 +0100 Subject: [PATCH] feat(app): gallery switches between grid and thumbnail list, and each artifact or document group is collapsible with a pinned title --- .../ui/artifact_document_section.dart | 10 + .../artifacts/ui/artifact_record_row.dart | 6 + .../features/artifacts/ui/artifact_tile.dart | 112 +++--- .../artifacts/ui/artifact_visit_list.dart | 327 ++++++++++++++---- .../ui/artifact_gallery_documents_test.dart | 2 +- .../ui/artifact_gallery_page_test.dart | 4 +- .../artifact_visit_list_semantics_test.dart | 9 +- .../ui/artifact_visit_list_test.dart | 37 +- 8 files changed, 389 insertions(+), 118 deletions(-) diff --git a/app/lib/features/artifacts/ui/artifact_document_section.dart b/app/lib/features/artifacts/ui/artifact_document_section.dart index 003af5e9..71161175 100644 --- a/app/lib/features/artifacts/ui/artifact_document_section.dart +++ b/app/lib/features/artifacts/ui/artifact_document_section.dart @@ -19,8 +19,12 @@ class ArtifactDocumentSection extends StatelessWidget { required this.group, this.selectedIdentity, this.onSelected, + this.showHeader = true, }); + /// False when a collapsible title above already names the section. + final bool showHeader; + final ArtifactGroup group; final String? selectedIdentity; final ArtifactSelected? onSelected; @@ -30,6 +34,12 @@ class ArtifactDocumentSection extends StatelessWidget { final rows = [ for (final document in group.documents) _row(document), ]; + if (!showHeader) { + return Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: rows, + ); + } if (usesCupertinoHost(context)) { return CupertinoListSection.insetGrouped( header: Semantics( diff --git a/app/lib/features/artifacts/ui/artifact_record_row.dart b/app/lib/features/artifacts/ui/artifact_record_row.dart index 2abd427c..a3181228 100644 --- a/app/lib/features/artifacts/ui/artifact_record_row.dart +++ b/app/lib/features/artifacts/ui/artifact_record_row.dart @@ -18,8 +18,12 @@ class ArtifactRecordRow extends StatelessWidget { required this.artifact, required this.selected, required this.onSelected, + this.leading, }); + /// A small picture before the name (the list view's thumbnail). + final Widget? leading; + final ArtifactGroup group; final ArtifactRecord artifact; final bool selected; @@ -30,6 +34,7 @@ class ArtifactRecordRow extends StatelessWidget { if (!usesCupertinoHost(context)) { return ListTile( selected: selected, + leading: leading, title: Text(artifactDisplayName(artifact)), subtitle: Text(artifactFactsLabel(artifact)), trailing: selected ? const Icon(Icons.check) : null, @@ -44,6 +49,7 @@ class ArtifactRecordRow extends StatelessWidget { style: textTheme.textStyle, child: Row( children: [ + if (leading != null) ...[leading!, const SizedBox(width: 12)], Expanded( child: Column( crossAxisAlignment: CrossAxisAlignment.start, diff --git a/app/lib/features/artifacts/ui/artifact_tile.dart b/app/lib/features/artifacts/ui/artifact_tile.dart index a86814e8..f051d048 100644 --- a/app/lib/features/artifacts/ui/artifact_tile.dart +++ b/app/lib/features/artifacts/ui/artifact_tile.dart @@ -34,24 +34,6 @@ class ArtifactTile extends StatefulWidget { } class _ArtifactTileState extends State { - Future? _thumbnail; - - @override - void initState() { - super.initState(); - final artifact = widget.artifact; - final format = artifactPreviewFormat(artifact.contentType, artifact.name); - final resolved = artifact.hasUrl - ? resolveArtifactUrl(widget.configuredEndpoint, artifact.url) - : null; - // Only same-origin images load a thumbnail, through the app's own fetch. - if (format == ArtifactPreviewFormat.image && - resolved != null && - !resolved.external) { - _thumbnail = widget.fetch(resolved.uri); - } - } - @override Widget build(BuildContext context) { final cupertino = usesCupertinoHost(context); @@ -69,28 +51,12 @@ class _ArtifactTileState extends State { : (cupertino ? CupertinoColors.separator.resolveFrom(context) : Theme.of(context).colorScheme.outlineVariant); - final icon = Icon( - artifactKindIcon(artifact, cupertino: cupertino), - size: 40, - color: secondary, + final preview = ArtifactThumbnail( + artifact: artifact, + configuredEndpoint: widget.configuredEndpoint, + fetch: widget.fetch, + iconSize: 40, ); - final preview = _thumbnail == null - ? Center(child: icon) - : FutureBuilder( - future: _thumbnail, - builder: (context, snapshot) { - final result = snapshot.data; - if (result == null || !result.ok || result.bytes.isEmpty) { - return Center(child: icon); - } - return Image.memory( - result.bytes, - fit: BoxFit.cover, - gaplessPlayback: true, - errorBuilder: (_, _, _) => Center(child: icon), - ); - }, - ); final name = artifactDisplayName(artifact); final facts = artifactFactsLabel(artifact); final body = Column( @@ -153,6 +119,74 @@ class _ArtifactTileState extends State { } } +/// An artifact's picture: the image itself, loaded once through the app's own +/// fetch, or an icon for its kind of file. +class ArtifactThumbnail extends StatefulWidget { + const ArtifactThumbnail({ + super.key, + required this.artifact, + required this.configuredEndpoint, + required this.fetch, + this.iconSize = 24, + }); + + final ArtifactRecord artifact; + final String configuredEndpoint; + final ArtifactFetch fetch; + final double iconSize; + + @override + State createState() => _ArtifactThumbnailState(); +} + +class _ArtifactThumbnailState extends State { + Future? _image; + + @override + void initState() { + super.initState(); + final artifact = widget.artifact; + final format = artifactPreviewFormat(artifact.contentType, artifact.name); + final resolved = artifact.hasUrl + ? resolveArtifactUrl(widget.configuredEndpoint, artifact.url) + : null; + // Only same-origin images load a thumbnail, through the app's own fetch. + if (format == ArtifactPreviewFormat.image && + resolved != null && + !resolved.external) { + _image = widget.fetch(resolved.uri); + } + } + + @override + Widget build(BuildContext context) { + final cupertino = usesCupertinoHost(context); + final icon = Icon( + artifactKindIcon(widget.artifact, cupertino: cupertino), + size: widget.iconSize, + color: cupertino + ? CupertinoColors.secondaryLabel.resolveFrom(context) + : Theme.of(context).colorScheme.onSurfaceVariant, + ); + if (_image == null) return Center(child: icon); + return FutureBuilder( + future: _image, + builder: (context, snapshot) { + final result = snapshot.data; + if (result == null || !result.ok || result.bytes.isEmpty) { + return Center(child: icon); + } + return Image.memory( + result.bytes, + fit: BoxFit.cover, + gaplessPlayback: true, + errorBuilder: (_, _, _) => Center(child: icon), + ); + }, + ); + } +} + /// The icon for an artifact's kind of file, when it has no thumbnail. IconData artifactKindIcon(ArtifactRecord artifact, {required bool cupertino}) { final name = artifact.name.toLowerCase(); diff --git a/app/lib/features/artifacts/ui/artifact_visit_list.dart b/app/lib/features/artifacts/ui/artifact_visit_list.dart index 62e2fb97..f45db772 100644 --- a/app/lib/features/artifacts/ui/artifact_visit_list.dart +++ b/app/lib/features/artifacts/ui/artifact_visit_list.dart @@ -1,9 +1,12 @@ +import 'dart:math' as math; + import 'package:flutter/cupertino.dart'; import 'package:flutter/material.dart'; import '../../../ui/adaptive/host.dart'; import '../domain/artifact_groups.dart'; import 'artifact_document_section.dart'; +import 'artifact_record_row.dart'; import 'artifact_tile.dart'; import 'artifact_viewer_fetch.dart'; import 'artifact_row_labels.dart'; @@ -26,7 +29,10 @@ export 'artifact_row_labels.dart' /// list sections under [CupertinoApp]. An optional [header] leads the same /// scroll view. It never resolves a url, opens a preview, downloads, shares or /// filters. -class ArtifactVisitList extends StatelessWidget { +/// How the gallery lays out each visit's artifacts. +enum ArtifactGalleryMode { grid, list } + +class ArtifactVisitList extends StatefulWidget { const ArtifactVisitList({ super.key, required this.groups, @@ -37,90 +43,190 @@ class ArtifactVisitList extends StatelessWidget { this.fetch = fetchArtifact, }); - /// Resolves an image's url for its thumbnail; [fetch] loads it. - final String configuredEndpoint; - final ArtifactFetch fetch; - - /// An optional page header rendered above the first section, inside the same - /// scroll view. - /// - /// A header sized by recorded facts (a summary and one line per capture note) - /// must not take height from the list: it scrolls away with the rows instead - /// of shrinking the viewport, which keeps every artifact reachable at a small - /// surface or a large text scale. final Widget? header; final List groups; - /// [artifactVisitIdentity] of the selected artifact, or null for none. final String? selectedIdentity; final ArtifactSelected? onSelected; + /// Resolves an image's url for its thumbnail; [fetch] loads it. + final String configuredEndpoint; + final ArtifactFetch fetch; + + /// The layout last chosen, kept for the app's lifetime. + static ArtifactGalleryMode lastMode = ArtifactGalleryMode.grid; + + @override + State createState() => _ArtifactVisitListState(); +} + +class _ArtifactVisitListState extends State { + ArtifactGalleryMode _mode = ArtifactVisitList.lastMode; + + /// Sections the operator closed, by their key. + final Set _closed = {}; + + void _toggle(String key) => setState(() { + if (!_closed.remove(key)) _closed.add(key); + }); + + void _setMode(ArtifactGalleryMode mode) => setState(() { + _mode = mode; + ArtifactVisitList.lastMode = mode; + }); + @override Widget build(BuildContext context) { - final header = this.header; - if (groups.isEmpty) { - return _NoArtifacts(header: header); - } - if (usesCupertinoHost(context)) { - return ListView( - children: [ - ?header, - for (final group in groups) ...[ - Padding( - padding: const EdgeInsetsDirectional.fromSTEB(16, 16, 16, 4), - // `container` keeps the heading a separate semantics node. - child: Semantics( - container: true, - header: true, - child: Text( - artifactGroupLabel(group), - style: TextStyle( - color: CupertinoColors.secondaryLabel.resolveFrom(context), - ), - ), - ), - ), - _grid(group), - if (group.documents.isNotEmpty) - ArtifactDocumentSection( - group: group, - selectedIdentity: selectedIdentity, - onSelected: onSelected, - ), - ], - ], - ); - } - final theme = Theme.of(context); - final headingStyle = theme.textTheme.titleSmall?.copyWith( - color: theme.colorScheme.onSurfaceVariant, - ); - return ListView( - children: [ - ?header, - for (final group in groups) ...[ - Padding( - padding: const EdgeInsetsDirectional.fromSTEB(16, 16, 16, 4), - child: Semantics( - container: true, - header: true, - child: Text(artifactGroupLabel(group), style: headingStyle), + final header = widget.header; + if (widget.groups.isEmpty) return _NoArtifacts(header: header); + final slivers = [ + if (header != null) SliverToBoxAdapter(child: header), + SliverToBoxAdapter(child: _modeSwitch(context)), + ]; + for (final group in widget.groups) { + final identity = '${group.stageKey}\u0000${group.visit}'; + if (group.artifacts.isNotEmpty) { + final key = '$identity\u0000artifacts'; + slivers.add( + _section( + context, + key: key, + title: artifactGroupLabel(group), + count: group.artifacts.length, + body: _mode == ArtifactGalleryMode.grid + ? _grid(group) + : _list(group), + ), + ); + } + if (group.documents.isNotEmpty) { + final key = '$identity\u0000documents'; + slivers.add( + _section( + context, + key: key, + title: '${artifactGroupLabel(group)} · Turn documents', + count: group.documents.length, + body: ArtifactDocumentSection( + group: group, + selectedIdentity: widget.selectedIdentity, + onSelected: widget.onSelected, + showHeader: false, ), ), - _grid(group), - if (group.documents.isNotEmpty) - ArtifactDocumentSection( - group: group, - selectedIdentity: selectedIdentity, - onSelected: onSelected, + ); + } + } + return CustomScrollView(slivers: slivers); + } + + /// One collapsible section: its title stays pinned at the top while its + /// content scrolls under it, and tapping the title opens or closes it. + Widget _section( + BuildContext context, { + required String key, + required String title, + required int count, + required Widget body, + }) { + final open = !_closed.contains(key); + final scale = MediaQuery.textScalerOf(context).scale(16); + return SliverMainAxisGroup( + key: ValueKey('artifact-section:$key'), + slivers: [ + PinnedHeaderSliver( + child: SizedBox( + height: math.max(44, scale + 28), + child: _SectionTitle( + title: title, + count: count, + open: open, + onTap: () => _toggle(key), ), - ], + ), + ), + if (open) SliverToBoxAdapter(child: body), ], ); } + Widget _modeSwitch(BuildContext context) { + final cupertino = usesCupertinoHost(context); + final control = cupertino + ? CupertinoSlidingSegmentedControl( + key: const Key('artifact-gallery-mode'), + groupValue: _mode, + onValueChanged: (mode) { + if (mode != null) _setMode(mode); + }, + children: const { + ArtifactGalleryMode.grid: Icon( + CupertinoIcons.square_grid_2x2, + semanticLabel: 'Grid', + ), + ArtifactGalleryMode.list: Icon( + CupertinoIcons.list_bullet, + semanticLabel: 'List', + ), + }, + ) + : SegmentedButton( + key: const Key('artifact-gallery-mode'), + showSelectedIcon: false, + segments: const [ + ButtonSegment( + value: ArtifactGalleryMode.grid, + icon: Icon(Icons.grid_view), + tooltip: 'Grid', + ), + ButtonSegment( + value: ArtifactGalleryMode.list, + icon: Icon(Icons.view_list), + tooltip: 'List', + ), + ], + selected: {_mode}, + onSelectionChanged: (mode) => _setMode(mode.single), + ); + return Padding( + padding: const EdgeInsetsDirectional.fromSTEB(16, 4, 16, 4), + child: Align(alignment: AlignmentDirectional.centerEnd, child: control), + ); + } + + /// The list view: one row per artifact with a small thumbnail beside it. + Widget _list(ArtifactGroup group) => Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + for (var index = 0; index < group.artifacts.length; index += 1) + ArtifactRecordRow( + key: ValueKey( + '${artifactVisitIdentity(group, group.artifacts[index])}' + '\u0000$index', + ), + group: group, + artifact: group.artifacts[index], + selected: + widget.selectedIdentity == + artifactVisitIdentity(group, group.artifacts[index]), + onSelected: widget.onSelected, + leading: ClipRRect( + borderRadius: BorderRadius.circular(6), + child: SizedBox.square( + dimension: 44, + child: ArtifactThumbnail( + artifact: group.artifacts[index], + configuredEndpoint: widget.configuredEndpoint, + fetch: widget.fetch, + ), + ), + ), + ), + ], + ); + /// A group's artifacts as a grid: two tiles across on a phone, more as the /// pane widens. Widget _grid(ArtifactGroup group) => LayoutBuilder( @@ -146,11 +252,11 @@ class ArtifactVisitList extends StatelessWidget { group: group, artifact: group.artifacts[index], selected: - selectedIdentity == + widget.selectedIdentity == artifactVisitIdentity(group, group.artifacts[index]), - configuredEndpoint: configuredEndpoint, - fetch: fetch, - onSelected: onSelected, + configuredEndpoint: widget.configuredEndpoint, + fetch: widget.fetch, + onSelected: widget.onSelected, ), ), ], @@ -160,6 +266,83 @@ class ArtifactVisitList extends StatelessWidget { ); } +/// A section's pinned title bar: its name, how many items, and the chevron. +class _SectionTitle extends StatelessWidget { + const _SectionTitle({ + required this.title, + required this.count, + required this.open, + required this.onTap, + }); + + final String title; + final int count; + final bool open; + final VoidCallback onTap; + + @override + Widget build(BuildContext context) { + final cupertino = usesCupertinoHost(context); + final background = cupertino + ? CupertinoColors.systemGroupedBackground.resolveFrom(context) + : Theme.of(context).colorScheme.surface; + final muted = cupertino + ? CupertinoColors.secondaryLabel.resolveFrom(context) + : Theme.of(context).colorScheme.onSurfaceVariant; + final style = TextStyle( + fontWeight: FontWeight.w600, + color: cupertino + ? CupertinoColors.label.resolveFrom(context) + : Theme.of(context).colorScheme.onSurface, + ); + // `container` keeps the heading a separate semantics node. + return Semantics( + container: true, + header: true, + button: true, + expanded: open, + label: title, + value: '$count', + excludeSemantics: true, + onTap: onTap, + child: GestureDetector( + behavior: HitTestBehavior.opaque, + onTap: onTap, + child: ColoredBox( + color: background, + child: Padding( + padding: const EdgeInsets.symmetric(horizontal: 16), + child: Row( + children: [ + Expanded( + child: Text( + title, + style: style, + maxLines: 1, + overflow: TextOverflow.ellipsis, + ), + ), + Text('$count', style: TextStyle(color: muted)), + const SizedBox(width: 6), + Icon( + open + ? (cupertino + ? CupertinoIcons.chevron_up + : Icons.expand_less) + : (cupertino + ? CupertinoIcons.chevron_down + : Icons.expand_more), + color: muted, + ), + ], + ), + ), + ), + ), + ); + } +} + class _NoArtifacts extends StatelessWidget { const _NoArtifacts({this.header}); diff --git a/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart index f8335281..0dadca69 100644 --- a/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart +++ b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart @@ -91,7 +91,7 @@ void main() { tester, ) async { await _pump(tester, platform); - expect(find.text('Turn documents'), findsNWidgets(2)); + expect(find.textContaining('Turn documents'), findsNWidgets(2)); expect(find.text('input.md'), findsNWidgets(2)); expect(find.text('output.md'), findsNWidgets(2)); expect(find.text('session.html'), findsNWidgets(2)); diff --git a/app/test/features/artifacts/ui/artifact_gallery_page_test.dart b/app/test/features/artifacts/ui/artifact_gallery_page_test.dart index d2466aa1..88778988 100644 --- a/app/test/features/artifacts/ui/artifact_gallery_page_test.dart +++ b/app/test/features/artifacts/ui/artifact_gallery_page_test.dart @@ -427,7 +427,7 @@ void main() { ], surface: const Size(360, 640)); expect(tester.takeException(), isNull); - final list = find.byType(ListView); + final list = find.byType(CustomScrollView); expect(tester.getSize(list).height, greaterThan(0)); // The header belongs to that scroll view, so it scrolls away instead of // shrinking the list. @@ -466,7 +466,7 @@ void main() { ); expect(tester.takeException(), isNull); - expect(tester.getSize(find.byType(ListView)).height, greaterThan(0)); + expect(tester.getSize(find.byType(CustomScrollView)).height, greaterThan(0)); expect( find.text('12 files excluded from artifact capture.'), findsOneWidget, diff --git a/app/test/features/artifacts/ui/artifact_visit_list_semantics_test.dart b/app/test/features/artifacts/ui/artifact_visit_list_semantics_test.dart index 411ebf0e..8d580d37 100644 --- a/app/test/features/artifacts/ui/artifact_visit_list_semantics_test.dart +++ b/app/test/features/artifacts/ui/artifact_visit_list_semantics_test.dart @@ -1,3 +1,5 @@ +import 'dart:ui' show Tristate; + import 'package:flutter/semantics.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:pipelines_app/features/artifacts/ui/artifact_tile.dart'; @@ -77,10 +79,11 @@ void main() { final heading = tester.getSemantics(find.text('review · visit 2')); expect(heading, isSemantics(label: 'review · visit 2', isHeader: true)); + // The heading's own action opens or closes its section; it is a separate + // node, so activating it never opens the artifact below. expect( - heading.getSemanticsData().hasAction(SemanticsAction.tap), - isFalse, - reason: 'a heading must never activate the artifact below it', + heading.getSemanticsData().flagsCollection.isExpanded, + Tristate.isTrue, ); final button = tester.getSemantics(find.byType(ArtifactTile)); diff --git a/app/test/features/artifacts/ui/artifact_visit_list_test.dart b/app/test/features/artifacts/ui/artifact_visit_list_test.dart index e2a270ee..02c8cda8 100644 --- a/app/test/features/artifacts/ui/artifact_visit_list_test.dart +++ b/app/test/features/artifacts/ui/artifact_visit_list_test.dart @@ -253,7 +253,7 @@ void main() { ), ); - final list = find.byType(ListView); + final list = find.byType(CustomScrollView); expect(list, findsOneWidget); expect( find.descendant(of: list, matching: find.text('Artifacts · 1 recorded')), @@ -277,4 +277,39 @@ void main() { expect(find.text('Artifacts · 0 recorded'), findsOneWidget); expect(find.text('No stage artifacts recorded.'), findsOneWidget); }); + + testWidgets('the gallery switches to a list with thumbnails and sections ' + 'collapse', (tester) async { + ArtifactVisitList.lastMode = ArtifactGalleryMode.grid; + addTearDown(() => ArtifactVisitList.lastMode = ArtifactGalleryMode.grid); + final group = visitGroup( + visit: 1, + artifacts: [ + recordedArtifact('a.csv', url: '/artifacts/7/1/a.csv'), + recordedArtifact('b.png', url: '/artifacts/7/1/b.png'), + ], + ); + await tester.pumpWidget( + artifactListHost( + cupertino: false, + groups: [group], + onSelected: (_, _) {}, + ), + ); + expect(find.byType(ArtifactTile), findsNWidgets(2)); + + await tester.tap(find.byTooltip('List')); + await tester.pumpAndSettle(); + expect(find.byType(ArtifactTile), findsNothing); + expect(find.byType(ArtifactThumbnail), findsNWidgets(2)); + expect(find.text('a.csv'), findsOneWidget); + + // The section title closes and reopens its section. + await tester.tap(find.text('review · visit 1')); + await tester.pumpAndSettle(); + expect(find.text('a.csv'), findsNothing); + await tester.tap(find.text('review · visit 1')); + await tester.pumpAndSettle(); + expect(find.text('a.csv'), findsOneWidget); + }); }