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.
This commit is contained in:
2026-11-10 20:28:09 +00:00
parent e0e8ca68f3
commit 7ff012880b
13 changed files with 179 additions and 25 deletions
@@ -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<ChatComposerBar> {
/// 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
@@ -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,
),
),
);
},
);
@@ -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<ChatWorkspaceEntrance>
// 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(
+8 -3
View File
@@ -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<SettingsTopicTabs>
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
+2 -1
View File
@@ -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<DetailPaneNavigator> {
// 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: (_) {
+17 -12
View File
@@ -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<FadeThroughStack>
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(),
),
),
),
),
+42
View File
@@ -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;
}
+2 -1
View File
@@ -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<LiveElapsedBuilder> {
_unwatch();
_clock = clock;
}
_shown = TickerMode.valuesOf(context).enabled;
_shown = SurfaceVisibility.shownOf(context);
_sync();
}
+2 -1
View File
@@ -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<RelativeTimeLabel> {
@override
void didChangeDependencies() {
super.didChangeDependencies();
_shown = TickerMode.valuesOf(context).enabled;
_shown = SurfaceVisibility.shownOf(context);
if (_shown && _stale) _advance();
}
+10
View File
@@ -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.
@@ -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);
});
}
+4 -2
View File
@@ -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) =>
@@ -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++;