diff --git a/lib/screens/album_screen.dart b/lib/screens/album_screen.dart index f2022e65c..ee7dc7604 100644 --- a/lib/screens/album_screen.dart +++ b/lib/screens/album_screen.dart @@ -28,6 +28,7 @@ import 'package:mornye/utils/adaptive_layout.dart'; import 'package:mornye/utils/provider_resource_ids.dart'; import 'package:mornye/utils/ttl_cache.dart'; import 'package:mornye/widgets/animation_utils.dart'; +import 'package:mornye/widgets/loaded_sliver_fade_in.dart'; import 'package:mornye/widgets/playlist_picker_sheet.dart'; import 'package:mornye/widgets/cross_extension_share_sheet.dart'; import 'package:mornye/widgets/link/link_actions.dart'; @@ -484,10 +485,24 @@ class _AlbumScreenState extends ConsumerState description: _description!, ), ), - if (_isLoading) - // The skeleton rows carry the list's own inset. - const SliverToBoxAdapter( - child: AlbumTrackListSkeleton(itemCount: 10), + if (_isLoading || (_error == null && tracks.isNotEmpty)) + // The desktop table fades in once over its skeleton's place; + // phone rows stagger in on their own. + LoadedSliverFadeIn( + key: const ValueKey('album-tracks'), + loading: _isLoading, + enabled: isDesktopPlatform, + sliver: _isLoading + // The skeleton rows carry the list's own inset. + ? const SliverToBoxAdapter( + child: AlbumTrackListSkeleton(itemCount: 10), + ) + : _buildTrackList( + context, + colorScheme, + tracks, + commonQualityTrack, + ), ), if (_error != null) SliverToBoxAdapter( @@ -501,7 +516,6 @@ class _AlbumScreenState extends ConsumerState ), ), if (!_isLoading && _error == null && tracks.isNotEmpty) ...[ - _buildTrackList(context, colorScheme, tracks, commonQualityTrack), _buildAlbumFooter(context, colorScheme, tracks), if (!isSelectionMode) CollectionSuggestionsSliver( diff --git a/lib/screens/home_tab.dart b/lib/screens/home_tab.dart index bc6da1a88..afbb89939 100644 --- a/lib/screens/home_tab.dart +++ b/lib/screens/home_tab.dart @@ -91,6 +91,7 @@ import 'package:mornye/widgets/download_service_picker.dart'; import 'package:mornye/widgets/track_collection_quick_actions.dart'; import 'package:mornye/widgets/desktop/context_menu.dart'; import 'package:mornye/widgets/animation_utils.dart'; +import 'package:mornye/widgets/loaded_sliver_fade_in.dart'; import 'package:mornye/widgets/audio_quality_badges.dart'; import 'package:mornye/widgets/cached_cover_image.dart'; import 'package:mornye/widgets/extension_icon_image.dart'; diff --git a/lib/screens/home_tab_search_wide.dart b/lib/screens/home_tab_search_wide.dart index 5214e07ee..fb4f80f1d 100644 --- a/lib/screens/home_tab_search_wide.dart +++ b/lib/screens/home_tab_search_wide.dart @@ -43,20 +43,31 @@ extension _HomeTabSearchWideUI on _HomeTabState { ?.id; final hasActualData = tracks.isNotEmpty; + // The results fade in once over the skeleton's place; a new search + // shows the skeleton again, while results that refine keep the stage. + Widget reveal({required bool loading, required Widget sliver}) => + LoadedSliverFadeIn( + key: const ValueKey('wide-search-results'), + loading: loading, + sliver: sliver, + ); if (!hasActualData && isLoading) { return [ - SliverToBoxAdapter( - child: HomeSearchSkeleton( - layout: switch (overview - ? 'all' - : canonicalExtensionSearchFilterId(displayFilter)) { - 'all' => HomeSearchSkeletonLayout.overview, - 'artist' => HomeSearchSkeletonLayout.artistGrid, - 'track' || - 'album' || - 'playlist' => HomeSearchSkeletonLayout.coverGrid, - _ => HomeSearchSkeletonLayout.rows, - }, + reveal( + loading: true, + sliver: SliverToBoxAdapter( + child: HomeSearchSkeleton( + layout: switch (overview + ? 'all' + : canonicalExtensionSearchFilterId(displayFilter)) { + 'all' => HomeSearchSkeletonLayout.overview, + 'artist' => HomeSearchSkeletonLayout.artistGrid, + 'track' || + 'album' || + 'playlist' => HomeSearchSkeletonLayout.coverGrid, + _ => HomeSearchSkeletonLayout.rows, + }, + ), ), ), ]; @@ -233,7 +244,9 @@ extension _HomeTabSearchWideUI on _HomeTabState { if (!songsAdded && songs.isNotEmpty) addSongs(); slivers.add(const SliverToBoxAdapter(child: SizedBox(height: 16))); - return slivers; + return [ + reveal(loading: false, sliver: SliverMainAxisGroup(slivers: slivers)), + ]; } /// Which results fill the preview cards: a song first, then the first diff --git a/lib/screens/local_album_screen.dart b/lib/screens/local_album_screen.dart index a34941076..df5b5b24d 100644 --- a/lib/screens/local_album_screen.dart +++ b/lib/screens/local_album_screen.dart @@ -46,6 +46,7 @@ import 'package:mornye/widgets/desktop/track_table.dart'; import 'package:mornye/widgets/expressive_button.dart'; import 'package:mornye/widgets/album_track_tile.dart'; import 'package:mornye/widgets/animation_utils.dart'; +import 'package:mornye/widgets/loaded_sliver_fade_in.dart'; import 'package:mornye/widgets/app_snack_bar.dart'; import 'package:mornye/widgets/library_track_selection_bar.dart'; import 'package:mornye/widgets/link/link_actions.dart'; @@ -314,15 +315,26 @@ class _LocalAlbumScreenState extends ConsumerState ), ), ) - else if (_loadingTracks) - const SliverToBoxAdapter( - child: RepaintBoundary( - child: AlbumTrackListSkeleton(itemCount: 8, showQuality: true), - ), - ) else ...[ - _buildTrackList(context, colorScheme, tracks), - if (!showsSelectionBar) + // Loaded songs fade in once over the skeleton's place where their + // rows do not stagger in: the desktop table, and phone rows that + // load after the page opens. + LoadedSliverFadeIn( + key: const ValueKey('local-album-tracks'), + loading: _loadingTracks, + enabled: isDesktopPlatform || widget.loadTracks != null, + sliver: _loadingTracks + ? const SliverToBoxAdapter( + child: RepaintBoundary( + child: AlbumTrackListSkeleton( + itemCount: 8, + showQuality: true, + ), + ), + ) + : _buildTrackList(context, colorScheme, tracks), + ), + if (!_loadingTracks && !showsSelectionBar) CollectionSuggestionsSliver( collectionKey: 'local-album:${widget.artistName}:${widget.albumName}', diff --git a/lib/screens/playlist_screen.dart b/lib/screens/playlist_screen.dart index 6a068aa1b..167f9b3fa 100644 --- a/lib/screens/playlist_screen.dart +++ b/lib/screens/playlist_screen.dart @@ -17,6 +17,7 @@ import 'package:mornye/utils/adaptive_layout.dart'; import 'package:mornye/utils/provider_resource_ids.dart'; import 'package:mornye/widgets/playlist_picker_sheet.dart'; import 'package:mornye/widgets/animation_utils.dart'; +import 'package:mornye/widgets/loaded_sliver_fade_in.dart'; import 'package:mornye/widgets/cached_cover_image.dart'; import 'package:mornye/widgets/link/link_actions.dart'; import 'package:mornye/widgets/motion_header_banner.dart'; @@ -286,7 +287,13 @@ class _PlaylistScreenState extends ConsumerState ), appBar: _buildAppBar(context, colorScheme), slivers: [ - _buildTrackList(context, colorScheme), + // The desktop table fades in once over its skeleton's place; + // phone rows stagger in on their own. + LoadedSliverFadeIn( + loading: _isLoading, + enabled: isDesktopPlatform, + sliver: _buildTrackList(context, colorScheme), + ), _buildPlaylistFooter(context, colorScheme), if (!_isLoading && _tracks.isNotEmpty && !isSelectionMode) CollectionSuggestionsSliver( diff --git a/lib/widgets/animation_utils.dart b/lib/widgets/animation_utils.dart index 632a2bc62..8f28b1ffc 100644 --- a/lib/widgets/animation_utils.dart +++ b/lib/widgets/animation_utils.dart @@ -1,3 +1,5 @@ +import 'dart:math' as math; + import 'package:flutter/material.dart'; import 'package:mornye/theme/app_motion.dart'; import 'package:mornye/theme/app_tokens.dart'; @@ -5,7 +7,9 @@ import 'package:mornye/theme/material_expressive.dart'; import 'package:mornye/theme/mornye_theme.dart'; import 'package:mornye/utils/adaptive_layout.dart'; import 'package:mornye/utils/desktop_platform.dart'; +import 'package:mornye/widgets/decorative_phase.dart'; import 'package:mornye/widgets/desktop/track_table.dart'; +import 'package:mornye/widgets/loaded_sliver_fade_in.dart'; /// Wraps a child in a staggered fade-in + slide-up animation. /// @@ -32,13 +36,20 @@ class StaggeredListItem extends StatelessWidget { this.animate = true, }); - @override - Widget build(BuildContext context) { - final position = Scrollable.maybeOf(context)?.position; - final scrolled = - position != null && + static bool _hasScrolled(ScrollableState? scrollable) { + final position = scrollable?.position; + return position != null && position.hasContentDimensions && position.pixels > position.minScrollExtent; + } + + @override + Widget build(BuildContext context) { + // A shelf scrolls sideways inside a page that builds its shelves lazily + // while it scrolls down, so a moved page skips the reveal as well. + final scrolled = + _hasScrolled(Scrollable.maybeOf(context)) || + _hasScrolled(Scrollable.maybeOf(context, axis: Axis.vertical)); if (!animate || scrolled || index >= _maxAnimatedItems || @@ -47,58 +58,40 @@ class StaggeredListItem extends StatelessWidget { } final cappedIndex = index.clamp(0, _maxAnimatedItems - 1); final delay = staggerDelay * cappedIndex; - if (materialExpressiveEnabled(context)) { - // Expressive: each item springs up after its own delay and may - // overshoot slightly; opacity stays within range. - final motion = AppMotion.spatial( - context, - AppMotionSpec(duration, Curves.easeOutCubic), - ); - final total = motion.duration + delay; - final delayFraction = total.inMicroseconds > 0 - ? delay.inMicroseconds / total.inMicroseconds - : 0.0; - return TweenAnimationBuilder( - key: ValueKey('stagger_$index'), - tween: Tween(begin: 0.0, end: 1.0), - duration: total, - builder: (context, value, child) { - final elapsed = value <= delayFraction - ? 0.0 - : ((value - delayFraction) / (1.0 - delayFraction)).clamp( - 0.0, - 1.0, - ); - final progress = motion.curve.transform(elapsed); - return Opacity( - opacity: progress.clamp(0.0, 1.0), - child: Transform.translate( - offset: Offset(0, 16 * (1 - progress)), - child: child, - ), - ); - }, - child: child, - ); - } - final totalDuration = duration + delay; + // Expressive: each item springs up after its own delay and may + // overshoot slightly, while its opacity follows the effects spring. + final rise = AppMotion.spatial( + context, + AppMotionSpec(duration, Curves.easeOutCubic), + ); + final fade = AppMotion.effectsFast( + context, + AppMotionSpec(duration, Curves.easeOutCubic), + ); + final distance = materialExpressiveEnabled(context) ? 16.0 : 12.0; + final span = rise.duration > fade.duration ? rise.duration : fade.duration; + final total = (span + delay).inMicroseconds.toDouble(); + // The skeleton leaves in the frame these rows arrive, so the reveal + // starts one frame in and the first row already shows. + final start = math.min( + loadedFadeFirstFrame.inMicroseconds.toDouble(), + total, + ); + double progress(double elapsed, Duration length) => + (elapsed / length.inMicroseconds).clamp(0.0, 1.0); return TweenAnimationBuilder( key: ValueKey('stagger_$index'), - tween: Tween(begin: 0.0, end: 1.0), - duration: totalDuration, - curve: Curves.easeOutCubic, - builder: (context, value, child) { - final delayFraction = totalDuration.inMilliseconds > 0 - ? delay.inMilliseconds / totalDuration.inMilliseconds - : 0.0; - final progress = value <= delayFraction - ? 0.0 - : ((value - delayFraction) / (1.0 - delayFraction)).clamp(0.0, 1.0); + tween: Tween(begin: start, end: total), + duration: Duration(microseconds: (total - start).round()), + builder: (context, time, child) { + final elapsed = time - delay.inMicroseconds; + final moved = rise.curve.transform(progress(elapsed, rise.duration)); + final opacity = fade.curve.transform(progress(elapsed, fade.duration)); return Opacity( - opacity: progress, + opacity: opacity.clamp(0.0, 1.0), child: Transform.translate( - offset: Offset(0, 12 * (1 - progress)), + offset: Offset(0, distance * (1 - moved)), child: child, ), ); @@ -117,7 +110,9 @@ Route slidePageRoute({required Widget page}) { return MaterialPageRoute(builder: (context) => page); } -/// A shimmer effect widget that can wrap skeleton placeholders. +/// A shimmer effect widget that can wrap skeleton placeholders. Its sweep +/// advances on a [DecorativePhase], at most 30 times a second, like the +/// other continuous decorations. class ShimmerLoading extends StatefulWidget { final Widget child; @@ -131,33 +126,23 @@ class ShimmerLoading extends StatefulWidget { State createState() => _ShimmerLoadingState(); } -class _ShimmerLoadingState extends State - with SingleTickerProviderStateMixin { - late AnimationController _controller; - - @override - void initState() { - super.initState(); - _controller = AnimationController( - vsync: this, - duration: const Duration(milliseconds: 1200), - ); - } +class _ShimmerLoadingState extends State { + final _phase = DecorativePhase(const Duration(milliseconds: 1200)); @override void didChangeDependencies() { super.didChangeDependencies(); if (MediaQuery.disableAnimationsOf(context) || !TickerMode.valuesOf(context).enabled) { - _controller.stop(); - } else if (!_controller.isAnimating) { - _controller.repeat(); + _phase.stop(); + } else { + _phase.start(); } } @override void dispose() { - _controller.dispose(); + _phase.dispose(); super.dispose(); } @@ -178,8 +163,9 @@ class _ShimmerLoadingState extends State : Color.alphaBlend(Colors.black.withValues(alpha: 0.01), surface); return AnimatedBuilder( - animation: _controller, + animation: _phase, builder: (context, child) { + final phase = _phase.value; return ShaderMask( shaderCallback: (bounds) { return LinearGradient( @@ -187,9 +173,9 @@ class _ShimmerLoadingState extends State end: Alignment.centerRight, colors: [baseColor, highlightColor, baseColor], stops: [ - (_controller.value - 0.3).clamp(0.0, 1.0), - _controller.value, - (_controller.value + 0.3).clamp(0.0, 1.0), + (phase - 0.3).clamp(0.0, 1.0), + phase, + (phase + 0.3).clamp(0.0, 1.0), ], tileMode: TileMode.clamp, ).createShader(bounds); diff --git a/lib/widgets/loaded_sliver_fade_in.dart b/lib/widgets/loaded_sliver_fade_in.dart new file mode 100644 index 000000000..651189304 --- /dev/null +++ b/lib/widgets/loaded_sliver_fade_in.dart @@ -0,0 +1,73 @@ +import 'package:flutter/widgets.dart'; +import 'package:mornye/theme/app_motion.dart'; + +/// How far into its fade loaded content starts, so the frame that drops the +/// skeleton already shows the content: one frame at 60 Hz. +const loadedFadeFirstFrame = Duration(milliseconds: 16); + +/// Fades loaded content in once, when it replaces its skeleton. +/// +/// Keep one instance, under a stable key, where the skeleton and the loaded +/// sliver take turns: while [loading] it shows [sliver] (the skeleton) as it +/// is, and the build that turns [loading] off fades the loaded [sliver] in, +/// on the effects spring on Material and over 150 ms ease-out on Mornye. +/// Content already there on the first build, later rebuilds and scrolling +/// never fade, and nothing staggers. Reduced motion and a false [enabled] +/// cut. Hit testing does not wait for the fade. +class LoadedSliverFadeIn extends StatefulWidget { + const LoadedSliverFadeIn({ + super.key, + required this.loading, + required this.sliver, + this.enabled = true, + }); + + final bool loading; + final Widget sliver; + final bool enabled; + + static const _fallback = AppMotionSpec( + Duration(milliseconds: 150), + Curves.easeOut, + ); + + @override + State createState() => _LoadedSliverFadeInState(); +} + +class _LoadedSliverFadeInState extends State + with SingleTickerProviderStateMixin { + late final _controller = AnimationController(vsync: this, value: 1); + late Animation _opacity = _controller; + + @override + void didUpdateWidget(LoadedSliverFadeIn oldWidget) { + super.didUpdateWidget(oldWidget); + if (oldWidget.loading == widget.loading) return; + if (widget.loading || + !widget.enabled || + MediaQuery.disableAnimationsOf(context)) { + _controller.value = 1; + return; + } + final motion = AppMotion.effects(context, LoadedSliverFadeIn._fallback); + _controller.duration = motion.duration; + _opacity = _controller.drive(CurveTween(curve: motion.curve)); + // The skeleton is already gone in this frame, so start one frame into + // the fade instead of drawing an empty frame at opacity 0. + _controller.forward( + from: + loadedFadeFirstFrame.inMicroseconds / motion.duration.inMicroseconds, + ); + } + + @override + void dispose() { + _controller.dispose(); + super.dispose(); + } + + @override + Widget build(BuildContext context) => + SliverFadeTransition(opacity: _opacity, sliver: widget.sliver); +} diff --git a/test/loading_motion_test.dart b/test/loading_motion_test.dart new file mode 100644 index 000000000..eb3503e97 --- /dev/null +++ b/test/loading_motion_test.dart @@ -0,0 +1,197 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:mornye/theme/app_theme.dart'; +import 'package:mornye/widgets/animation_utils.dart'; +import 'package:mornye/widgets/decorative_phase.dart'; +import 'package:mornye/widgets/loaded_sliver_fade_in.dart'; + +Widget _app(Widget child, {bool reduced = false}) => MaterialApp( + theme: AppTheme.light(), + home: Builder( + builder: (context) => MediaQuery( + data: MediaQuery.of(context).copyWith(disableAnimations: reduced), + child: Scaffold(body: child), + ), + ), +); + +Widget _page({ + required bool loading, + bool enabled = true, + bool reduced = false, + int build = 0, +}) => _app( + CustomScrollView( + slivers: [ + LoadedSliverFadeIn( + key: const ValueKey('tracks'), + loading: loading, + enabled: enabled, + sliver: SliverToBoxAdapter( + child: SizedBox( + height: 100, + child: Text(loading ? 'skeleton' : 'loaded $build'), + ), + ), + ), + ], + ), + reduced: reduced, +); + +double _sliverOpacity(WidgetTester tester) => tester + .widget(find.byType(SliverFadeTransition)) + .opacity + .value; + +void main() { + tearDown(DecorativePhase.debugResetClock); + + group('LoadedSliverFadeIn', () { + testWidgets('fades loaded content in once over the skeleton', ( + tester, + ) async { + await tester.pumpWidget(_page(loading: true)); + expect(_sliverOpacity(tester), 1); + + await tester.pumpWidget(_page(loading: false)); + // The first frame without the skeleton already shows the content. + final first = _sliverOpacity(tester); + expect(first, greaterThan(0)); + expect(first, lessThan(1)); + + await tester.pump(const Duration(milliseconds: 50)); + final mid = _sliverOpacity(tester); + expect(mid, greaterThan(first)); + expect(mid, lessThan(1)); + + await tester.pump(const Duration(milliseconds: 500)); + expect(_sliverOpacity(tester), 1); + + // A rebuild with new data never replays it. + await tester.pumpWidget(_page(loading: false, build: 1)); + expect(_sliverOpacity(tester), 1); + expect(find.text('loaded 1'), findsOneWidget); + }); + + testWidgets('content there on the first build does not fade', ( + tester, + ) async { + await tester.pumpWidget(_page(loading: false)); + expect(_sliverOpacity(tester), 1); + }); + + testWidgets('reduced motion and a disabled fade cut', (tester) async { + await tester.pumpWidget(_page(loading: true, reduced: true)); + await tester.pumpWidget(_page(loading: false, reduced: true)); + expect(_sliverOpacity(tester), 1); + + await tester.pumpWidget(_page(loading: true, enabled: false)); + await tester.pumpWidget(_page(loading: false, enabled: false)); + expect(_sliverOpacity(tester), 1); + }); + }); + + group('StaggeredListItem', () { + Iterable itemOpacities(WidgetTester tester) => tester + .widgetList( + find.descendant( + of: find.byType(StaggeredListItem), + matching: find.byType(Opacity), + ), + ) + .map((opacity) => opacity.opacity); + + testWidgets('the first row shows on the first frame', (tester) async { + await tester.pumpWidget( + _app( + ListView( + children: [ + for (var i = 0; i < 3; i++) + StaggeredListItem( + index: i, + child: SizedBox(height: 40, child: Text('row $i')), + ), + ], + ), + ), + ); + final opacities = itemOpacities(tester).toList(); + expect(opacities.first, greaterThan(0)); + await tester.pump(const Duration(seconds: 1)); + expect(itemOpacities(tester), everyElement(1)); + }); + + testWidgets('shelves built while the page scrolls do not replay it', ( + tester, + ) async { + final controller = ScrollController(); + addTearDown(controller.dispose); + await tester.pumpWidget( + _app( + ListView.builder( + controller: controller, + itemExtent: 200, + itemCount: 30, + itemBuilder: (context, shelf) => ListView.builder( + scrollDirection: Axis.horizontal, + itemCount: 6, + itemBuilder: (context, index) => StaggeredListItem( + index: index, + child: SizedBox(width: 120, child: Text('$shelf-$index')), + ), + ), + ), + ), + ); + expect(itemOpacities(tester), isNotEmpty); + await tester.pump(const Duration(seconds: 1)); + + controller.jumpTo(1200); + await tester.pump(); + expect(find.text('7-0'), findsOneWidget); + expect(itemOpacities(tester), everyElement(1)); + }); + + testWidgets('reduced motion shows rows at once', (tester) async { + await tester.pumpWidget( + _app( + const StaggeredListItem(index: 0, child: Text('row')), + reduced: true, + ), + ); + expect(itemOpacities(tester), isEmpty); + }); + }); + + group('ShimmerLoading', () { + const box = SizedBox( + width: 200, + height: 20, + child: ColoredBox(color: Colors.grey), + ); + + testWidgets('sweeps at most 30 times a second', (tester) async { + await tester.pumpWidget(_app(const ShimmerLoading(child: box))); + final masks = {}; + for (var frame = 0; frame < 120; frame++) { + await tester.pump(const Duration(microseconds: 8333)); + masks.add(tester.widget(find.byType(ShaderMask))); + } + // 120 frames at 120 Hz span one second. + expect(masks.length, inInclusiveRange(20, 31)); + expect(DecorativePhase.debugClockRunning, isTrue); + + await tester.pumpWidget(_app(const SizedBox())); + expect(DecorativePhase.debugClockRunning, isFalse); + }); + + testWidgets('reduced motion keeps the placeholders still', (tester) async { + await tester.pumpWidget( + _app(const ShimmerLoading(child: box), reduced: true), + ); + expect(find.byType(ShaderMask), findsNothing); + expect(DecorativePhase.debugClockRunning, isFalse); + }); + }); +}