Files
pipelines/app/lib/shell/shell_bar.dart
T
alan 3b996bdbc7 Share one minute clock across time labels and narrow shell and runs rebuilds
Relative-time labels follow one wall-minute RelativeTimeClock instead of a
timer per row, skip ticks while their tab is offstage and rebuild only when
their text changes. The shell rebuilds its top bar only for the focused
destination's published bar and its tab bar only for badge changes. Run
events that repeat a row's state no longer notify, and the runs list filters
and sorts once per build. Adds a rebuild/timer benchmark.
2026-11-01 23:29:39 +00:00

397 lines
11 KiB
Dart

import 'package:flutter/widgets.dart';
import 'destination.dart';
/// What the open screen of a tab puts in the app bar: its title, a Back
/// control and its actions. Absent, the bar shows the tab's own name.
class ShellBarSpec {
const ShellBarSpec({
this.title,
this.subtitle,
this.subtitleIcon,
this.onTitlePressed,
this.expandableTitle = false,
this.titleAction,
this.titleSemanticLabel,
this.titleKey,
this.onBack,
this.actions = const [],
this.barless = false,
this.titleWidget,
this.titleWidgetMaxWidth = double.infinity,
this.backgroundColor,
});
final String? title;
/// The bar's main pill in place of the title (a search field); see
/// `SegmentedBar.titleWidget`.
final Widget? titleWidget;
final double titleWidgetMaxWidth;
/// The page's own background behind the bar (a grouped list's), so the
/// bar's scrim matches what scrolls under it; null keeps the shell's.
final Color? backgroundColor;
/// A one-line subtitle in the title pill (the item's context: its
/// pipeline and version), so the body need not repeat it.
final String? subtitle;
final IconData? subtitleIcon;
/// Makes the title pill a button; see `SegmentedBar.onTitlePressed`.
final VoidCallback? onTitlePressed;
final bool expandableTitle;
final Widget? titleAction;
final String? titleSemanticLabel;
final Key? titleKey;
final VoidCallback? onBack;
final List<Widget> actions;
/// The content draws its own floating bar: a detail page shows no bar of
/// its own and lets the content reach the top edge.
final bool barless;
}
/// The bar contents each tab's open screen has published.
///
/// It notifies its own listeners of every visible change. A host that shows
/// one destination's bar at a time sets [focus] and may listen to [bar] and
/// [badges] separately: a hidden tab republishing its bar (a list rebuilding
/// on a run event) then rebuilds nothing, and a badge change rebuilds only
/// the tab bar.
class ShellBarRegistry extends ChangeNotifier {
final Map<AppDestination, (Object, ShellBarSpec)> _specs = {};
final Map<(AppDestination, ShellBadgeKind), int> _badges = {};
final _Notifier _bar = _Notifier();
final _Notifier _badgeNotifier = _Notifier();
/// The destination whose bar is on screen; null treats every destination
/// as shown. Bar changes of other destinations are kept without notifying:
/// the host rebuilds when it changes the focus.
AppDestination? focus;
/// Notifies when the focused destination's bar spec or split changes.
Listenable get bar => _bar;
/// Notifies when any tab badge count changes.
Listenable get badges => _badgeNotifier;
bool _shown(AppDestination destination) =>
focus == null || focus == destination;
void _barChanged(AppDestination destination) {
if (!_shown(destination)) return;
_bar.notify();
notifyListeners();
}
final Map<AppDestination, int> _splits = {};
/// Whether a tab's screen shows a list beside an open item right now
/// ([ShellPaneSplit]): the shell's bar then covers the list pane only, so
/// the item's own bar shares its top row.
bool split(AppDestination destination) => (_splits[destination] ?? 0) > 0;
void _setSplit(AppDestination destination, bool value) {
if (_disposed) return;
final before = split(destination);
_splits[destination] = (_splits[destination] ?? 0) + (value ? 1 : -1);
if (split(destination) != before) _barChanged(destination);
}
/// The count a tab's screen published for [kind], 0 when none.
int badge(AppDestination destination, ShellBadgeKind kind) =>
_badges[(destination, kind)] ?? 0;
void _setBadge(AppDestination destination, ShellBadgeKind kind, int count) {
if (_disposed || badge(destination, kind) == count) return;
_badges[(destination, kind)] = count;
_badgeNotifier.notify();
notifyListeners();
}
bool _disposed = false;
@override
void dispose() {
_disposed = true;
_bar.dispose();
_badgeNotifier.dispose();
super.dispose();
}
ShellBarSpec? specFor(AppDestination destination) => _specs[destination]?.$2;
/// The screen that published [destination]'s bar; it changes when another
/// screen takes the bar over.
Object? ownerFor(AppDestination destination) => _specs[destination]?.$1;
void _set(AppDestination destination, Object owner, ShellBarSpec spec) {
// A screen's update can land after the shell itself has gone.
if (_disposed) return;
_specs[destination] = (owner, spec);
_barChanged(destination);
}
void _clear(AppDestination destination, Object owner) {
if (_disposed) return;
if (_specs[destination]?.$1 != owner) return;
_specs.remove(destination);
_barChanged(destination);
}
}
class _Notifier extends ChangeNotifier {
void notify() => notifyListeners();
}
/// Places one tab's content under the shell's bar registry.
class ShellBarScope extends InheritedWidget {
const ShellBarScope({
super.key,
required this.registry,
required this.destination,
required super.child,
});
final ShellBarRegistry registry;
final AppDestination destination;
static ShellBarScope? maybeOf(BuildContext context) =>
context.dependOnInheritedWidgetOfExactType<ShellBarScope>();
@override
bool updateShouldNotify(ShellBarScope oldWidget) =>
registry != oldWidget.registry || destination != oldWidget.destination;
}
/// Puts [title], [onBack] and [actions] in the app bar while [child] is shown.
/// Outside a shell (a screen mounted on its own) it does nothing, so the
/// screen keeps its own controls.
class ShellBar extends StatefulWidget {
const ShellBar({
super.key,
this.title,
this.subtitle,
this.subtitleIcon,
this.onTitlePressed,
this.expandableTitle = false,
this.titleAction,
this.titleSemanticLabel,
this.titleKey,
this.onBack,
this.actions = const [],
this.active = true,
this.barless = false,
this.titleWidget,
this.titleWidgetMaxWidth = double.infinity,
this.backgroundColor,
required this.child,
});
/// See [ShellBarSpec.titleWidget].
final Widget? titleWidget;
final double titleWidgetMaxWidth;
/// See [ShellBarSpec.backgroundColor].
final Color? backgroundColor;
/// See [ShellBarSpec.barless].
final bool barless;
/// False while the screen is kept mounted but hidden (a list under an open
/// detail): it then gives the bar up.
final bool active;
final String? title;
/// See [ShellBarSpec.subtitle].
final String? subtitle;
final IconData? subtitleIcon;
final VoidCallback? onTitlePressed;
final bool expandableTitle;
final Widget? titleAction;
final String? titleSemanticLabel;
final Key? titleKey;
final VoidCallback? onBack;
final List<Widget> actions;
final Widget child;
/// Whether a shell bar will show these controls for the subtree at
/// [context].
static bool available(BuildContext context) =>
ShellBarScope.maybeOf(context) != null;
@override
State<ShellBar> createState() => _ShellBarState();
}
class _ShellBarState extends State<ShellBar> {
final Object _owner = Object();
ShellBarScope? _scope;
@override
void didChangeDependencies() {
super.didChangeDependencies();
_scope = ShellBarScope.maybeOf(context);
}
void _publish() {
final scope = _scope;
if (scope == null) return;
if (!widget.active) {
WidgetsBinding.instance.addPostFrameCallback((_) {
if (mounted) scope.registry._clear(scope.destination, _owner);
});
return;
}
final spec = ShellBarSpec(
title: widget.title,
subtitle: widget.subtitle,
subtitleIcon: widget.subtitleIcon,
onTitlePressed: widget.onTitlePressed,
expandableTitle: widget.expandableTitle,
titleAction: widget.titleAction,
titleSemanticLabel: widget.titleSemanticLabel,
titleKey: widget.titleKey,
onBack: widget.onBack,
actions: widget.actions,
barless: widget.barless,
titleWidget: widget.titleWidget,
titleWidgetMaxWidth: widget.titleWidgetMaxWidth,
backgroundColor: widget.backgroundColor,
);
// The bar is above this screen; update it after this frame's build.
WidgetsBinding.instance.addPostFrameCallback((_) {
if (mounted) scope.registry._set(scope.destination, _owner, spec);
});
}
@override
void dispose() {
final scope = _scope;
if (scope != null) {
WidgetsBinding.instance.addPostFrameCallback(
(_) => scope.registry._clear(scope.destination, _owner),
);
}
super.dispose();
}
@override
Widget build(BuildContext context) {
_publish();
return widget.child;
}
}
/// Tells the shell, while mounted, that its tab shows a list beside an open
/// item (`ListDetailPanes`). The shell then narrows its own bar to the list
/// pane, so each pane owns its bar on one shared top row. Outside a shell it
/// does nothing.
class ShellPaneSplit extends StatefulWidget {
const ShellPaneSplit({super.key, required this.child});
final Widget child;
@override
State<ShellPaneSplit> createState() => _ShellPaneSplitState();
}
class _ShellPaneSplitState extends State<ShellPaneSplit> {
ShellBarScope? _scope;
@override
void didChangeDependencies() {
super.didChangeDependencies();
final scope = ShellBarScope.maybeOf(context);
if (scope == _scope) return;
_release();
_scope = scope;
if (scope != null) {
// The bar is above this screen; update it after this frame's build.
WidgetsBinding.instance.addPostFrameCallback(
(_) => scope.registry._setSplit(scope.destination, true),
);
}
}
void _release() {
final scope = _scope;
if (scope == null) return;
WidgetsBinding.instance.addPostFrameCallback(
(_) => scope.registry._setSplit(scope.destination, false),
);
}
@override
void dispose() {
_release();
super.dispose();
}
@override
Widget build(BuildContext context) => widget.child;
}
/// What a tab badge counts.
enum ShellBadgeKind {
/// Runs still executing.
running,
/// Chats with messages not yet seen.
unread,
}
/// Publishes a count for this tab's badge while [child] is mounted.
class ShellBadge extends StatefulWidget {
const ShellBadge({
super.key,
required this.kind,
required this.count,
required this.child,
});
final ShellBadgeKind kind;
final int count;
final Widget child;
@override
State<ShellBadge> createState() => _ShellBadgeState();
}
class _ShellBadgeState extends State<ShellBadge> {
ShellBarScope? _scope;
@override
void didChangeDependencies() {
super.didChangeDependencies();
_scope = ShellBarScope.maybeOf(context);
}
@override
void dispose() {
final scope = _scope;
final kind = widget.kind;
if (scope != null) {
WidgetsBinding.instance.addPostFrameCallback(
(_) => scope.registry._setBadge(scope.destination, kind, 0),
);
}
super.dispose();
}
@override
Widget build(BuildContext context) {
final scope = _scope;
if (scope != null) {
final count = widget.count;
final kind = widget.kind;
WidgetsBinding.instance.addPostFrameCallback((_) {
if (mounted) scope.registry._setBadge(scope.destination, kind, count);
});
}
return widget.child;
}
}