From 7ff012880bcadbec4c94fefd43a208f646f5d20e Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Tue, 10 Nov 2026 20:28:09 +0000 Subject: [PATCH] Add explicit surface visibility signal Provide composable shown/current visibility for retained surfaces and migrate visibility readers away from TickerMode. This keeps ticker muting separate from painted and current-surface state. --- .../chat/conversation/chat_composer_bar.dart | 3 +- .../chat/workspace/chat_float_host.dart | 10 ++- .../workspace/chat_workspace_entrance.dart | 10 ++- app/lib/features/settings/settings_tabs.dart | 11 ++- app/lib/shell/detail_pane_navigator.dart | 3 +- app/lib/ui/motion/fade_through_stack.dart | 29 ++++---- app/lib/ui/motion/surface_visibility.dart | 42 ++++++++++++ app/lib/ui/text/live_elapsed_builder.dart | 3 +- app/lib/ui/text/relative_time_label.dart | 3 +- app/notes/surface-visibility.md | 10 +++ .../ui/motion/surface_visibility_test.dart | 68 +++++++++++++++++++ app/test/ui/text/elapsed_clock_test.dart | 6 +- .../ui/text/relative_time_label_test.dart | 6 +- 13 files changed, 179 insertions(+), 25 deletions(-) create mode 100644 app/lib/ui/motion/surface_visibility.dart create mode 100644 app/notes/surface-visibility.md create mode 100644 app/test/ui/motion/surface_visibility_test.dart diff --git a/app/lib/features/chat/conversation/chat_composer_bar.dart b/app/lib/features/chat/conversation/chat_composer_bar.dart index bac3ef20..093d109d 100644 --- a/app/lib/features/chat/conversation/chat_composer_bar.dart +++ b/app/lib/features/chat/conversation/chat_composer_bar.dart @@ -6,6 +6,7 @@ import 'package:flutter/foundation.dart'; import 'package:flutter/material.dart'; import '../../../ui/scale/ui_scale.dart'; +import '../../../ui/motion/surface_visibility.dart'; import 'chat_stop_icon.dart'; import 'package:flutter/services.dart'; @@ -262,7 +263,7 @@ class _ChatComposerBarState extends State { /// and not covered by a dialog, sheet or another pushed route. bool _composerIsCurrent() => mounted && - TickerMode.valuesOf(context).enabled && + SurfaceVisibility.currentOf(context) && (ModalRoute.of(context)?.isCurrent ?? true); @override diff --git a/app/lib/features/chat/workspace/chat_float_host.dart b/app/lib/features/chat/workspace/chat_float_host.dart index 8d040bd5..61c9f17e 100644 --- a/app/lib/features/chat/workspace/chat_float_host.dart +++ b/app/lib/features/chat/workspace/chat_float_host.dart @@ -6,6 +6,7 @@ import 'package:flutter/services.dart'; import '../../../ui/floating/floating_layer.dart'; import '../../../ui/motion/motion.dart'; +import '../../../ui/motion/surface_visibility.dart'; import '../ui/sessions/chat_adaptive.dart'; import 'chat_float_binding.dart'; import 'chat_float_shortcut.dart'; @@ -322,7 +323,14 @@ class _ChatFloatSlotState extends State<_ChatFloatSlot> onDock: widget.onDock, onHide: widget.onHide, // A hidden window's chat pauses its tickers like a hidden tab. - child: TickerMode(enabled: !offstage, child: widget.child), + child: TickerMode( + enabled: !offstage, + child: SurfaceVisibility( + shown: !offstage, + current: !offstage, + child: widget.child, + ), + ), ); }, ); diff --git a/app/lib/features/chat/workspace/chat_workspace_entrance.dart b/app/lib/features/chat/workspace/chat_workspace_entrance.dart index a6ae83e0..16a49e8e 100644 --- a/app/lib/features/chat/workspace/chat_workspace_entrance.dart +++ b/app/lib/features/chat/workspace/chat_workspace_entrance.dart @@ -1,6 +1,7 @@ import 'package:flutter/cupertino.dart'; import '../../../ui/motion/motion.dart'; +import '../../../ui/motion/surface_visibility.dart'; /// Reopens a retained mobile workspace without moving it to another route. /// Its child keeps the same element, scroll positions, panes and drafts. @@ -68,7 +69,14 @@ class _ChatWorkspaceEntranceState extends State // Both surfaces share one route here; only the workspace entrance // animates, so no Hero inside the chat flies or duplicates a tag. enabled: false, - child: TickerMode(enabled: widget.visible, child: widget.child), + child: TickerMode( + enabled: widget.visible, + child: SurfaceVisibility( + shown: widget.visible, + current: widget.visible, + child: widget.child, + ), + ), ); final transition = widget.cupertino ? CupertinoPageTransition( diff --git a/app/lib/features/settings/settings_tabs.dart b/app/lib/features/settings/settings_tabs.dart index 5c5b148b..0a656e94 100644 --- a/app/lib/features/settings/settings_tabs.dart +++ b/app/lib/features/settings/settings_tabs.dart @@ -7,6 +7,7 @@ import 'settings_theme.dart'; import 'settings_page_body.dart'; import 'settings_topic_store.dart'; import '../../core/storage/ordered_local_storage.dart'; +import '../../ui/motion/surface_visibility.dart'; enum SettingsTopic { appearance('Appearance'), @@ -176,9 +177,13 @@ class _SettingsTopicTabsState extends State if (_visited.contains(topic)) TickerMode( enabled: topic == _selected, - child: KeyedSubtree( - key: ValueKey('settings-topic-${topic.name}'), - child: Builder(builder: widget.pages[topic]!), + child: SurfaceVisibility( + shown: true, + current: topic == _selected, + child: KeyedSubtree( + key: ValueKey('settings-topic-${topic.name}'), + child: Builder(builder: widget.pages[topic]!), + ), ), ) else diff --git a/app/lib/shell/detail_pane_navigator.dart b/app/lib/shell/detail_pane_navigator.dart index afcb9881..abeec02b 100644 --- a/app/lib/shell/detail_pane_navigator.dart +++ b/app/lib/shell/detail_pane_navigator.dart @@ -2,6 +2,7 @@ import 'package:flutter/cupertino.dart'; import 'package:flutter/material.dart'; import '../ui/adaptive/host.dart'; +import '../ui/motion/surface_visibility.dart'; /// The open item's own navigator beside a list on a wide window. /// @@ -48,7 +49,7 @@ class _DetailPaneNavigatorState extends State { // Only the shown tab's pane answers the system Back: a page left open in // another tab's pane stays there while Back acts on the current tab. The // route asks every handler on it, so a hidden pane also ignores the call. - final shown = TickerMode.valuesOf(context).enabled; + final shown = SurfaceVisibility.currentOf(context); return NavigatorPopHandler( enabled: shown, onPopWithResult: (_) { diff --git a/app/lib/ui/motion/fade_through_stack.dart b/app/lib/ui/motion/fade_through_stack.dart index 022ed906..8e2cdc94 100644 --- a/app/lib/ui/motion/fade_through_stack.dart +++ b/app/lib/ui/motion/fade_through_stack.dart @@ -2,6 +2,7 @@ import 'package:flutter/scheduler.dart'; import 'package:flutter/widgets.dart'; import 'motion.dart'; +import 'surface_visibility.dart'; /// Keeps every child mounted while fading between two indexed pages. /// @@ -155,19 +156,23 @@ class _FadeThroughStackState extends State offstage: !shown, child: TickerMode( enabled: active, - child: IgnorePointer( - ignoring: !active, - child: ExcludeFocus( - excluding: !active, - child: ExcludeSemantics( + child: SurfaceVisibility( + shown: shown, + current: active, + child: IgnorePointer( + ignoring: !active, + child: ExcludeFocus( excluding: !active, - child: Transform.scale( - scale: scale, - child: Opacity( - opacity: opacity, - child: !widget.lazy || _visited.contains(index) - ? widget.children[index] - : const SizedBox.shrink(), + child: ExcludeSemantics( + excluding: !active, + child: Transform.scale( + scale: scale, + child: Opacity( + opacity: opacity, + child: !widget.lazy || _visited.contains(index) + ? widget.children[index] + : const SizedBox.shrink(), + ), ), ), ), diff --git a/app/lib/ui/motion/surface_visibility.dart b/app/lib/ui/motion/surface_visibility.dart new file mode 100644 index 00000000..87dc03c5 --- /dev/null +++ b/app/lib/ui/motion/surface_visibility.dart @@ -0,0 +1,42 @@ +import 'package:flutter/widgets.dart'; + +/// Describes whether a surface is painted and whether it is the surface the +/// user is currently working on. +/// +/// Unlike [TickerMode], this signal describes visibility independently from +/// whether animations are allowed to run. Nested surfaces can only make their +/// descendants less visible. +class SurfaceVisibility extends InheritedWidget { + const SurfaceVisibility({ + super.key, + required this.shown, + required this.current, + required super.child, + }); + + final bool shown; + final bool current; + + static bool shownOf(BuildContext context) => _valuesOf(context).shown; + + static bool currentOf(BuildContext context) => _valuesOf(context).current; + + static ({bool shown, bool current}) _valuesOf(BuildContext context) { + var shown = true; + var current = true; + context.visitAncestorElements((element) { + final widget = element.widget; + if (element is InheritedElement && widget is SurfaceVisibility) { + context.dependOnInheritedElement(element); + shown = shown && widget.shown; + current = current && widget.current; + } + return true; + }); + return (shown: shown, current: current && shown); + } + + @override + bool updateShouldNotify(SurfaceVisibility oldWidget) => + shown != oldWidget.shown || current != oldWidget.current; +} diff --git a/app/lib/ui/text/live_elapsed_builder.dart b/app/lib/ui/text/live_elapsed_builder.dart index f7beaf04..bebaa69e 100644 --- a/app/lib/ui/text/live_elapsed_builder.dart +++ b/app/lib/ui/text/live_elapsed_builder.dart @@ -1,6 +1,7 @@ import 'package:flutter/widgets.dart'; import 'elapsed_clock.dart'; +import '../motion/surface_visibility.dart'; /// Builds a running item's elapsed-time text from the [ElapsedClock], and /// rebuilds only itself as that duration advances. @@ -39,7 +40,7 @@ class _LiveElapsedBuilderState extends State { _unwatch(); _clock = clock; } - _shown = TickerMode.valuesOf(context).enabled; + _shown = SurfaceVisibility.shownOf(context); _sync(); } diff --git a/app/lib/ui/text/relative_time_label.dart b/app/lib/ui/text/relative_time_label.dart index ade282ed..4d2b3b26 100644 --- a/app/lib/ui/text/relative_time_label.dart +++ b/app/lib/ui/text/relative_time_label.dart @@ -2,6 +2,7 @@ import 'package:flutter/widgets.dart'; import 'relative_time.dart'; import 'relative_time_clock.dart'; +import '../motion/surface_visibility.dart'; /// A relative-time label that rebuilds only itself, and only when its text /// changes. Every label follows one shared minute [RelativeTimeClock] rather @@ -53,7 +54,7 @@ class _RelativeTimeLabelState extends State { @override void didChangeDependencies() { super.didChangeDependencies(); - _shown = TickerMode.valuesOf(context).enabled; + _shown = SurfaceVisibility.shownOf(context); if (_shown && _stale) _advance(); } diff --git a/app/notes/surface-visibility.md b/app/notes/surface-visibility.md new file mode 100644 index 00000000..58ceb58e --- /dev/null +++ b/app/notes/surface-visibility.md @@ -0,0 +1,10 @@ +# Surface visibility signal + +- Added `SurfaceVisibility` and provided it for retained tab, workspace, float, + and fade-through surfaces without changing rendering. +- Migrated navigation Back, composer focus, elapsed time, and relative time + readers from `TickerMode` to the explicit signal. +- Added nesting, dependency, and `FadeThroughStack` regression coverage. +- Focused watchdog: `846 passed, 0 failed`. +- Analyzer: clean. +- UI review: skipped; this change has no intended rendered change. diff --git a/app/test/ui/motion/surface_visibility_test.dart b/app/test/ui/motion/surface_visibility_test.dart new file mode 100644 index 00000000..8d2abd6b --- /dev/null +++ b/app/test/ui/motion/surface_visibility_test.dart @@ -0,0 +1,68 @@ +import 'package:flutter/widgets.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/ui/motion/fade_through_stack.dart'; +import 'package:pipelines_app/ui/motion/surface_visibility.dart'; + +class _Values extends StatelessWidget { + const _Values({this.onBuild}); + + final VoidCallback? onBuild; + + @override + Widget build(BuildContext context) { + onBuild?.call(); + return Directionality( + textDirection: TextDirection.ltr, + child: Text( + '${SurfaceVisibility.shownOf(context)}:${SurfaceVisibility.currentOf(context)}', + ), + ); + } +} + +void main() { + testWidgets('defaults to shown and current', (tester) async { + await tester.pumpWidget(const _Values()); + expect(find.text('true:true'), findsOneWidget); + }); + + testWidgets('nested visibility combines', (tester) async { + await tester.pumpWidget( + const SurfaceVisibility( + shown: false, + current: true, + child: SurfaceVisibility(shown: true, current: true, child: _Values()), + ), + ); + expect(find.text('false:false'), findsOneWidget); + }); + + testWidgets('dependents rebuild when visibility changes', (tester) async { + var builds = 0; + Widget app(bool shown) => SurfaceVisibility( + shown: shown, + current: shown, + child: _Values(onBuild: () => builds++), + ); + + await tester.pumpWidget(app(true)); + expect(builds, 1); + await tester.pumpWidget(app(false)); + expect(builds, 2); + expect(find.text('false:false'), findsOneWidget); + }); + + testWidgets('FadeThroughStack marks only the active page current', ( + tester, + ) async { + await tester.pumpWidget( + const Directionality( + textDirection: TextDirection.ltr, + child: FadeThroughStack(index: 0, children: [_Values(), _Values()]), + ), + ); + + expect(find.text('true:true'), findsOneWidget); + expect(find.text('false:false', skipOffstage: false), findsOneWidget); + }); +} diff --git a/app/test/ui/text/elapsed_clock_test.dart b/app/test/ui/text/elapsed_clock_test.dart index 8b57cbb8..25c33e12 100644 --- a/app/test/ui/text/elapsed_clock_test.dart +++ b/app/test/ui/text/elapsed_clock_test.dart @@ -1,5 +1,6 @@ import 'package:flutter/widgets.dart'; import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/ui/motion/surface_visibility.dart'; import 'package:pipelines_app/ui/text/elapsed_clock.dart'; import 'package:pipelines_app/ui/text/live_elapsed_builder.dart'; @@ -87,8 +88,9 @@ void main() { textDirection: TextDirection.ltr, child: ElapsedClockScope( clock: clock, - child: TickerMode( - enabled: shown, + child: SurfaceVisibility( + shown: shown, + current: shown, child: LiveElapsedBuilder( since: start, builder: (context, now) => diff --git a/app/test/ui/text/relative_time_label_test.dart b/app/test/ui/text/relative_time_label_test.dart index 75b84afa..704e3c34 100644 --- a/app/test/ui/text/relative_time_label_test.dart +++ b/app/test/ui/text/relative_time_label_test.dart @@ -1,5 +1,6 @@ import 'package:flutter/material.dart'; import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/ui/motion/surface_visibility.dart'; import 'package:pipelines_app/ui/text/relative_time.dart'; import 'package:pipelines_app/ui/text/relative_time_clock.dart'; import 'package:pipelines_app/ui/text/relative_time_label.dart'; @@ -62,8 +63,9 @@ void main() { final instant = _minute().subtract(const Duration(minutes: 4)); var builds = 0; Widget app(bool enabled) => MaterialApp( - home: TickerMode( - enabled: enabled, + home: SurfaceVisibility( + shown: enabled, + current: enabled, child: Builder( builder: (_) { builds++;