feat(app): add native Needs-you bell and sheet over the attention model

This commit is contained in:
2026-10-22 00:07:53 +01:00
parent 261d3a19c5
commit ee93d4f55b
15 changed files with 1952 additions and 0 deletions
@@ -0,0 +1,225 @@
import 'dart:math' as math;
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../ui/adaptive/host.dart';
import '../domain/attention_models.dart';
import 'needs_you_keys.dart';
import 'needs_you_sheet.dart';
/// The reusable `Needs you` bell and its native sheet.
///
/// The widget is told what needs the operator and what each action means; it
/// never reads a socket, a store or the clock. The bell is plain when [entries]
/// is empty and carries the count badge from [attentionBadgeLabel] otherwise.
/// Opening it draws the caller's live list; row and Clear-all callbacks only ever
/// name identities from the list the operator saw.
///
/// [onOpen] is also the caller's invitation to navigate: a Failed row is
/// dismissed first, because opening it is the operator dealing with it. A
/// Decision row is not dismissed here — only answering the decision clears it.
///
/// Pass a new list when the rows change; the bell keeps the list it was given
/// and only redraws an open sheet when the new list draws different rows.
///
/// On Material the action reserves its own end room for the count badge, so it
/// can be placed directly in [AppBar.actions]. The badge paints outside the
/// icon and grows with the text scale; the inset keeps it inside the viewport
/// at narrow widths and doubled text instead of handing a clipping trap to the
/// caller.
class NeedsYouBell extends StatefulWidget {
const NeedsYouBell({
super.key,
required this.entries,
required this.onOpen,
required this.onDismiss,
required this.onClearAll,
this.cupertino,
});
final List<AttentionEntry> entries;
final ValueChanged<AttentionEntry> onOpen;
final ValueChanged<AttentionEntry> onDismiss;
final ValueChanged<List<AttentionEntry>> onClearAll;
/// Forces the native host in tests and fixtures; otherwise the ambient
/// [usesCupertinoHost] decides.
final bool? cupertino;
@override
State<NeedsYouBell> createState() => _NeedsYouBellState();
}
class _NeedsYouBellState extends State<NeedsYouBell> {
/// End room the Material action reserves for the count badge.
///
/// `Badge` places its label 12 logical px past the icon and makes the stadium
/// at least as wide as it is tall, so the label grows with the text scale: at
/// 1x it ends inside the 48 px action, at 2x it reaches 8 logical px beyond it.
/// A Material app bar puts its last action flush at the trailing edge, so a
/// flush bell would have the badge sheared by the viewport at enlarged text.
/// The action reserves the label's own scaled height minus its built-in
/// offset, leaving a 16 logical px margin at every scale and keeping the bell
/// safe to place directly in `AppBar.actions`.
static double _materialBadgeEndRoom(BuildContext context) {
final badgeLabel = MediaQuery.textScalerOf(context).scale(16);
return math.max(8, badgeLabel - 8);
}
/// The live rows the open sheet draws. It changes with the caller's state, so
/// a dismissal redraws the sheet instead of leaving a stale row behind.
late final ValueNotifier<List<AttentionEntry>> _live;
final FocusNode _focus = FocusNode(debugLabel: 'NeedsYouBell');
/// True when the sheet went away because a row was chosen, so focus belongs
/// to whatever the caller opened rather than back on the bell.
bool _openedRun = false;
static List<AttentionEntry> _frozen(List<AttentionEntry> entries) =>
List<AttentionEntry>.unmodifiable(entries);
/// True when two lists would draw the same rows: the same identities in the
/// same order with the same text. A title edit or a new diagnostic keeps the
/// identity but changes what the sheet shows, so it must count as a change.
static bool _sameRows(
List<AttentionEntry> before,
List<AttentionEntry> after,
) {
if (before.length != after.length) return false;
for (var i = 0; i < before.length; i++) {
final previous = before[i];
final next = after[i];
if (previous.key != next.key ||
previous.label != next.label ||
attentionRowDescription(previous) != attentionRowDescription(next)) {
return false;
}
}
return true;
}
@override
void initState() {
super.initState();
_live = ValueNotifier<List<AttentionEntry>>(_frozen(widget.entries));
}
@override
void didUpdateWidget(covariant NeedsYouBell oldWidget) {
super.didUpdateWidget(oldWidget);
if (_sameRows(oldWidget.entries, widget.entries)) return;
final next = _frozen(widget.entries);
// The open sheet is another overlay subtree, not a child of this build, so
// handing it the new rows mid-build would mark it dirty outside the current
// build target. The rows are handed over once the frame is painted.
WidgetsBinding.instance.addPostFrameCallback((_) {
if (mounted) _live.value = next;
});
}
@override
void dispose() {
_live.dispose();
_focus.dispose();
super.dispose();
}
Future<void> _open() async {
_openedRun = false;
await showNeedsYouSheet(
context: context,
entries: _live,
onOpen: _activate,
onDismiss: widget.onDismiss,
onClearAll: widget.onClearAll,
cupertino: widget.cupertino,
);
if (!mounted || _openedRun) return;
// The browser returns focus to the bell after the sheet closes; do the same
// so keyboard and switch users are not dropped at the top of the page.
_focus.requestFocus();
}
void _activate(AttentionEntry entry) {
_openedRun = true;
if (entry.kind == AttentionKind.failed) widget.onDismiss(entry);
widget.onOpen(entry);
}
@override
Widget build(BuildContext context) {
final native = widget.cupertino ?? usesCupertinoHost(context);
final label = attentionBadgeLabel(widget.entries.length);
final action = native ? _cupertino(context) : _material(context, label);
final semantics = Semantics(
label: label,
button: true,
onTap: _open,
excludeSemantics: true,
child: action,
);
if (native) return semantics;
// The reserved badge room is outside the semantics box, so the focus
// rectangle stays the size of the action rather than the empty end room.
return Padding(
padding: EdgeInsetsDirectional.only(end: _materialBadgeEndRoom(context)),
child: semantics,
);
}
Widget _material(BuildContext context, String label) {
return IconButton(
key: attentionBellKey,
focusNode: _focus,
tooltip: label,
onPressed: _open,
icon: _badged(
context,
hostCupertino: false,
icon: const Icon(Icons.notifications_outlined),
),
);
}
Widget _cupertino(BuildContext context) {
final theme = CupertinoTheme.of(context);
return CupertinoButton(
key: attentionBellKey,
focusNode: _focus,
onPressed: _open,
child: _badged(
context,
hostCupertino: true,
icon: const Icon(CupertinoIcons.bell),
textStyle: theme.textTheme.tabLabelTextStyle,
),
);
}
Widget _badged(
BuildContext context, {
required bool hostCupertino,
required Widget icon,
TextStyle? textStyle,
}) {
final count = widget.entries.length;
// No native Cupertino badge exists; the framework Badge is used with the
// host's semantic red and the host's smallest text role.
if (hostCupertino && count > 0) {
return Badge.count(
key: attentionBadgeKey,
count: count,
textStyle: textStyle,
backgroundColor: CupertinoColors.systemRed.resolveFrom(context),
textColor: CupertinoColors.white,
child: icon,
);
}
if (count > 0) {
return Badge.count(key: attentionBadgeKey, count: count, child: icon);
}
return icon;
}
}
@@ -0,0 +1,36 @@
import '../domain/attention_models.dart';
/// The sheet's title and actions, matching the browser's `Needs you` surface.
const attentionSheetTitle = 'Needs you';
const attentionEmptyCopy = 'Nothing needs you right now.';
const attentionClearAllCopy = 'Clear all';
const attentionCloseCopy = 'Close';
/// One row's dismissal name.
///
/// The browser names every destructive control by the row it removes
/// (`Dismiss {label}`), so a sheet with two rows never exposes two identical
/// `Dismiss` actions to VoiceOver, TalkBack or voice control. A repeated label
/// also carries the run id, because the label alone would still be ambiguous.
String attentionDismissLabel(AttentionEntry entry, {bool repeated = false}) {
final label = 'Dismiss ${entry.label}';
return repeated ? '$label (run ${entry.runId})' : label;
}
/// The dismissal names for the rows of one open sheet, keyed by entry identity.
///
/// Only repeated labels get the run id, so the common case stays short and
/// readable, exactly as the browser's `labelCounts` decides.
Map<String, String> attentionDismissLabels(Iterable<AttentionEntry> entries) {
final counts = <String, int>{};
for (final entry in entries) {
counts.update(entry.label, (count) => count + 1, ifAbsent: () => 1);
}
return {
for (final entry in entries)
entry.key: attentionDismissLabel(
entry,
repeated: (counts[entry.label] ?? 0) > 1,
),
};
}
@@ -0,0 +1,24 @@
import 'package:flutter/widgets.dart';
/// The bell action that opens the `Needs you` sheet.
const attentionBellKey = ValueKey<String>('attention-bell');
/// The visible count badge. Absent when nothing needs the operator.
const attentionBadgeKey = ValueKey<String>('attention-badge');
/// The open sheet itself, whichever native host draws it.
const attentionSheetKey = ValueKey<String>('attention-sheet');
/// The honest empty line shown when the open snapshot has no entries.
const attentionEmptyKey = ValueKey<String>('attention-empty');
/// The bulk dismissal action, present only while the snapshot has entries.
const attentionClearAllKey = ValueKey<String>('attention-clear-all');
/// One row, keyed by the run+kind identity it shows.
ValueKey<String> attentionRowKey(String entryKey) =>
ValueKey<String>('attention-row-$entryKey');
/// The per-row dismissal action for one identity.
ValueKey<String> attentionDismissKey(String entryKey) =>
ValueKey<String>('attention-dismiss-$entryKey');
@@ -0,0 +1,57 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import '../../../ui/adaptive/host.dart';
import '../domain/attention_models.dart';
import 'needs_you_sheet_cupertino.dart';
import 'needs_you_sheet_material.dart';
/// Opens the native `Needs you` sheet over the live [entries].
///
/// [entries] is the caller's current list: the sheet redraws when it changes, so
/// dismissing a row updates the open sheet in place, as the browser does. The
/// dismissal snapshot is captured here, when the route opens; Clear all acts
/// only on it, so an entry that arrives while the sheet is open is shown but is
/// never silently cleared.
///
/// The sheet stays open after Dismiss and Clear all, so several rows can be
/// dealt with in one visit. Choosing a row closes it; Escape, the barrier and
/// system back are native route behaviour. The caller supplies the native host
/// explicitly when it already knows it; otherwise the ambient app host decides.
Future<void> showNeedsYouSheet({
required BuildContext context,
required ValueListenable<List<AttentionEntry>> entries,
required ValueChanged<AttentionEntry> onOpen,
required ValueChanged<AttentionEntry> onDismiss,
required ValueChanged<List<AttentionEntry>> onClearAll,
bool? cupertino,
}) {
final snapshot = attentionDismissalSnapshot(entries.value);
final native = cupertino ?? usesCupertinoHost(context);
if (native) {
return showCupertinoModalPopup<void>(
context: context,
builder: (_) => CupertinoNeedsYouSheet(
entries: entries,
snapshot: snapshot,
onOpen: onOpen,
onDismiss: onDismiss,
onClearAll: onClearAll,
),
);
}
return showModalBottomSheet<void>(
context: context,
isScrollControlled: true,
useSafeArea: true,
showDragHandle: true,
builder: (_) => MaterialNeedsYouSheet(
entries: entries,
snapshot: snapshot,
onOpen: onOpen,
onDismiss: onDismiss,
onClearAll: onClearAll,
),
);
}
@@ -0,0 +1,205 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/foundation.dart';
import '../domain/attention_models.dart';
import 'needs_you_copy.dart';
import 'needs_you_keys.dart';
/// The Cupertino popup body of the `Needs you` surface.
///
/// It reads as a native action-sheet style grouped list: an inset-grouped iOS
/// list in a [CupertinoPopupSurface], with a Close action, one grouped row per
/// live entry and a separate Clear-all group. Dismissing and Clear all leave the
/// sheet open and redraw it, matching the browser; [snapshot] is the set Clear
/// all may remove, so a later arrival is shown but never cleared by this visit.
/// Rows use host text roles without a line cap so a long label and description
/// wrap at a narrow, scaled width.
class CupertinoNeedsYouSheet extends StatelessWidget {
const CupertinoNeedsYouSheet({
super.key,
required this.entries,
required this.snapshot,
required this.onOpen,
required this.onDismiss,
required this.onClearAll,
});
/// The caller's current rows; a dismissal removed there redraws the sheet.
final ValueListenable<List<AttentionEntry>> entries;
/// The identities captured when the sheet opened, all Clear all may remove.
final List<AttentionEntry> snapshot;
final ValueChanged<AttentionEntry> onOpen;
final ValueChanged<AttentionEntry> onDismiss;
final ValueChanged<List<AttentionEntry>> onClearAll;
void _close(BuildContext context) => Navigator.of(context).pop();
void _open(BuildContext context, AttentionEntry entry) {
_close(context);
onOpen(entry);
}
@override
Widget build(BuildContext context) {
return ValueListenableBuilder<List<AttentionEntry>>(
valueListenable: entries,
builder: (context, rows, _) => _sheet(context, rows),
);
}
Widget _sheet(BuildContext context, List<AttentionEntry> rows) {
final theme = CupertinoTheme.of(context);
final dismissLabels = attentionDismissLabels(rows);
return SafeArea(
key: attentionSheetKey,
top: false,
child: Padding(
padding: const EdgeInsets.all(8),
child: CupertinoPopupSurface(
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Padding(
padding: const EdgeInsetsDirectional.fromSTEB(20, 16, 8, 4),
child: Row(
children: [
Expanded(
child: Semantics(
header: true,
namesRoute: true,
child: Text(
attentionSheetTitle,
style: theme.textTheme.navTitleTextStyle,
),
),
),
CupertinoButton(
padding: EdgeInsets.zero,
onPressed: () => _close(context),
child: const Text(attentionCloseCopy),
),
],
),
),
if (rows.isEmpty)
Padding(
key: attentionEmptyKey,
padding: const EdgeInsetsDirectional.fromSTEB(20, 8, 20, 24),
child: Text(
attentionEmptyCopy,
style: theme.textTheme.textStyle.copyWith(
color: CupertinoColors.secondaryLabel.resolveFrom(
context,
),
),
),
)
else
Flexible(
child: SingleChildScrollView(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
CupertinoListSection.insetGrouped(
children: [
for (final entry in rows)
_AttentionRow(
key: attentionRowKey(entry.key),
entry: entry,
dismissLabel: dismissLabels[entry.key]!,
onOpen: () => _open(context, entry),
onDismiss: () => onDismiss(entry),
),
],
),
CupertinoListSection.insetGrouped(
children: [
CupertinoListTile(
key: attentionClearAllKey,
title: Center(child: Text(attentionClearAllCopy)),
onTap: () => onClearAll(snapshot),
),
],
),
],
),
),
),
],
),
),
),
);
}
}
/// One native grouped row: an open action over the host's text roles and a
/// separate Dismiss control named after the row it removes. It deliberately does
/// not use [CupertinoListTile], whose single-line title/subtitle would truncate a
/// long scaled label.
class _AttentionRow extends StatelessWidget {
const _AttentionRow({
super.key,
required this.entry,
required this.dismissLabel,
required this.onOpen,
required this.onDismiss,
});
final AttentionEntry entry;
final String dismissLabel;
final VoidCallback onOpen;
final VoidCallback onDismiss;
@override
Widget build(BuildContext context) {
final theme = CupertinoTheme.of(context);
final secondary = theme.textTheme.textStyle.copyWith(
color: CupertinoColors.secondaryLabel.resolveFrom(context),
);
return Padding(
padding: const EdgeInsetsDirectional.fromSTEB(16, 10, 8, 10),
child: Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Padding(
padding: const EdgeInsets.only(top: 4),
child: Icon(
entry.kind == AttentionKind.decision
? CupertinoIcons.time
: CupertinoIcons.exclamationmark_circle,
color: entry.kind == AttentionKind.decision
? CupertinoColors.systemOrange.resolveFrom(context)
: CupertinoColors.systemRed.resolveFrom(context),
),
),
const SizedBox(width: 12),
Expanded(
child: CupertinoButton(
padding: EdgeInsets.zero,
alignment: AlignmentDirectional.centerStart,
onPressed: onOpen,
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(entry.label, style: theme.textTheme.textStyle),
const SizedBox(height: 4),
Text(attentionRowDescription(entry), style: secondary),
],
),
),
),
CupertinoButton(
key: attentionDismissKey(entry.key),
padding: EdgeInsets.zero,
onPressed: onDismiss,
child: Icon(CupertinoIcons.xmark, semanticLabel: dismissLabel),
),
],
),
);
}
}
@@ -0,0 +1,129 @@
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import '../domain/attention_models.dart';
import 'needs_you_copy.dart';
import 'needs_you_keys.dart';
/// The Material bottom-sheet body of the `Needs you` surface.
///
/// It draws the live rows it is given: the pure model's order, one native
/// `ListTile` per entry, each row opening its run while its trailing control
/// dismisses only that identity. Dismissing and Clear all leave the sheet open
/// and redraw it, matching the browser; [snapshot] is the set Clear all may
/// remove, so a later arrival is shown but never cleared by this visit. The list
/// stays scrollable so a long label or a large text scale cannot push the
/// actions off the sheet.
class MaterialNeedsYouSheet extends StatelessWidget {
const MaterialNeedsYouSheet({
super.key,
required this.entries,
required this.snapshot,
required this.onOpen,
required this.onDismiss,
required this.onClearAll,
});
/// The caller's current rows; a dismissal removed there redraws the sheet.
final ValueListenable<List<AttentionEntry>> entries;
/// The identities captured when the sheet opened, all Clear all may remove.
final List<AttentionEntry> snapshot;
final ValueChanged<AttentionEntry> onOpen;
final ValueChanged<AttentionEntry> onDismiss;
final ValueChanged<List<AttentionEntry>> onClearAll;
void _open(BuildContext context, AttentionEntry entry) {
Navigator.of(context).pop();
onOpen(entry);
}
@override
Widget build(BuildContext context) {
return ValueListenableBuilder<List<AttentionEntry>>(
valueListenable: entries,
builder: (context, rows, _) => _sheet(context, rows),
);
}
Widget _sheet(BuildContext context, List<AttentionEntry> rows) {
final theme = Theme.of(context);
final dismissLabels = attentionDismissLabels(rows);
return SafeArea(
key: attentionSheetKey,
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Padding(
padding: const EdgeInsetsDirectional.fromSTEB(24, 0, 12, 4),
child: Row(
children: [
Expanded(
child: Semantics(
header: true,
namesRoute: true,
child: Text(
attentionSheetTitle,
style: theme.textTheme.titleLarge,
),
),
),
if (rows.isNotEmpty)
TextButton(
key: attentionClearAllKey,
onPressed: () => onClearAll(snapshot),
child: const Text(attentionClearAllCopy),
),
],
),
),
if (rows.isEmpty)
Padding(
key: attentionEmptyKey,
padding: const EdgeInsetsDirectional.fromSTEB(24, 8, 24, 24),
child: Text(
attentionEmptyCopy,
style: theme.textTheme.bodyMedium?.copyWith(
color: theme.colorScheme.onSurfaceVariant,
),
),
)
else
Flexible(
child: ListView.separated(
shrinkWrap: true,
padding: const EdgeInsets.only(bottom: 8),
itemCount: rows.length,
separatorBuilder: (_, _) => const Divider(height: 1),
itemBuilder: (context, index) {
final entry = rows[index];
return ListTile(
key: attentionRowKey(entry.key),
leading: Icon(
entry.kind == AttentionKind.decision
? Icons.hourglass_top
: Icons.error_outline,
color: entry.kind == AttentionKind.decision
? theme.colorScheme.primary
: theme.colorScheme.error,
),
title: Text(entry.label),
subtitle: Text(attentionRowDescription(entry)),
trailing: IconButton(
key: attentionDismissKey(entry.key),
tooltip: dismissLabels[entry.key],
onPressed: () => onDismiss(entry),
icon: const Icon(Icons.close),
),
onTap: () => _open(context, entry),
);
},
),
),
],
),
);
}
}
+113
View File
@@ -0,0 +1,113 @@
# Needs you surface (native bell + sheet)
The reusable native surface over the landed pure attention model is in
`lib/features/attention/ui/`:
- `needs_you_bell.dart` — `NeedsYouBell` receives `entries` and the
`onOpen`/`onDismiss`/`onClearAll` callbacks. It reads no socket, clock or
storage. The accessible name is `attentionBadgeLabel(entries.length)`
(`Notifications` when empty, `Notifications, N needing attention` otherwise)
and the visible count badge is absent when empty. It keeps the caller's list
live for the open sheet, dismisses a Failed row before handing it to `onOpen`
(opening it is dealing with it; a Decision row stays until answered), and
returns focus to the bell when the sheet is closed without choosing a run,
as the browser does.
- `needs_you_sheet.dart` — captures the dismissal snapshot with
`attentionDismissalSnapshot` as the route opens, then uses
`showModalBottomSheet` on Material and `showCupertinoModalPopup` on Cupertino.
Back, Escape and barrier dismissal are the native route behaviours.
- `needs_you_sheet_material.dart` — M3 bottom sheet with a native `ListTile` per
entry (leading kind icon, label, `{pipeline} · {detail}`), a per-row trailing
close `IconButton`, and a `Clear all` text action. It deliberately has no
extra `Close` button: the native drag handle, barrier, system back and Escape
close it, unlike the browser and the Cupertino popup, which carry an explicit
`Close`. That is a platform difference, not a missing action.
- `needs_you_sheet_cupertino.dart` — a `CupertinoPopupSurface` containing
inset-grouped Cupertino list sections, host text roles, an xmark dismissal
action per row, a Close action, and a separate Clear-all group. Rows do not
use `CupertinoListTile` because that control caps title/subtitle at one line
and would truncate a scaled label.
- `needs_you_copy.dart` — the browser's wording, including
`Dismiss {label}` and `Dismiss {label} (run {runId})` when labels repeat.
Each destructive control is named after its row, never bare `Dismiss`: the
Material tooltip and the Cupertino xmark semantic label are
`Dismiss {label}`, plus `(run {runId})` when two rows share a label, matching
`web/src/views/attention.js`. The Material drag handle keeps its native
`Dismiss` label (`modalBarrierDismissLabel`); that is the barrier action, not a
row action.
The Material action reserves its own trailing room for the count badge. A
native `Badge` paints its label 12 logical px past the icon and makes the
stadium at least as tall as it is wide, so the label grows with the text scale:
at 1x it ends inside the 48 px action, at 2x it reaches 8 logical px beyond it.
A Material app bar puts its last action flush at the trailing edge, which used
to shear the badge's right end at 2x text (320 and 390 logical px). The bell now
reserves the scaled label height minus that built-in offset, leaving a 16
logical px margin at every scale, so a caller can place it directly in
`AppBar.actions` without extra padding. `test/features/attention/ui/needs_you_badge_test.dart`
measures the stadium the badge actually paints in that placement at 320×640/2x
and 390×844/2x and requires a visible margin; it fails if the reserved room is
removed. The Cupertino action already sits inside the navigation bar's trailing
room and fits (32 logical px at 320/2x).
The bell keeps the list it was given: pass a new list when the rows change.
An open sheet redraws when the new list draws different rows, and the
`Dismiss {label}` names refresh with it. Callers must not mutate the list in
place, and should derive a row's current run data from its `runId` rather than
from `entry.run` if they replace a summary without changing the drawn text.
The sheet draws the caller's live list, so a dismissal redraws it in place, and
it stays open after `Dismiss` and `Clear all` so several rows can be dealt with
in one visit. The bell hands the sheet a new list whenever what it draws changes —
identities, order, label or the `{pipeline} · {detail}` line — so a title edit or
a new diagnostic on an existing run reaches both an open sheet and one reopened
later, and its `Dismiss {label}` name refreshes with it. `Clear all` still receives
only the snapshot captured when the sheet opened: a run that arrives later is
shown but never silently cleared. Both hosts show `Nothing needs you right now.`
and no Clear all when the live list is empty. The title is exposed as a
route-naming header for assistive technology.
Focused tests in `test/features/attention/ui/` (28 new widget tests, both hosts
where meaningful): empty/plain vs counted bell and semantics label, the honest
empty sheet, back/Escape/barrier dismissal, focus return to the bell, the named
header, per-row dismiss names including the run-id suffix for repeated labels,
row Dismiss naming exactly its identity while the sheet stays open and redraws,
row Open identity, a Failed row dismissed before opening while a Decision is
not, Clear all applied only to the open snapshot while a later entry stays, a
same-identity title/diagnostic change refreshing both the open and reopened
sheet and its dismiss name, the painted badge margin in `AppBar.actions` at
320×640/2x and 390×844/2x, and 320 logical px / 2x dark wrapping with an
unscaled width check.
`flutter test test/features/attention` passes all 72 tests.
Real-browser fixture: `tool/attention_probe.dart` + `tool/attention_probe.mjs`
(no socket, storage or notification permission; `CHROME_PATH` overrides the
Chrome binary). The drive passes and wrote twenty captures to the run artifact
folder under `attention-ui/`: bell, open sheet, the sheet redrawn after
dismissing `7:Decision`, the cleared sheet, the Decision and Failed row-open
states, and the empty sheet, for Material and Cupertino in dark at 320 logical
px / 2x; bell + sheet for both hosts in light at 390 logical px and the default
text scale; and the Material bell and after-dismiss state at 390 logical px / 2x
where the badge must keep its trailing margin. The drive asserts two distinct
`Dismiss ...` row names, the row disappearing from the still-open sheet, Escape
returning to the page with `Dismissed 7:Decision` and one needing attention,
Clear all leaving an empty sheet with no Clear all or row dismiss, a Decision
row opening without a dismissal while a Failed row drops the count, and the
empty state offering neither Clear all nor a row dismiss. Measured from the
fresh PNGs, the Material badge's right edge is 16 logical px inside the
viewport at 320/2x, 390/2x and 390/1x.
`flutter analyze` is clean; `flutter build web` (normal `lib/main.dart`) succeeds
and the full suite passes. The component is not registered in the shell,
runs-list heading or a route; frames wiring, persisted dismissals, notification
permission and routing remain for later slices. No run, chat, `run_detail_*`,
server, web or deployment files were changed. Mobile and real device behaviour
are unverified.
## Manager completion after the Review visit limit
The pipeline exhausted its Review visits after the Code fixes. The retained tree is
complete: 72 attention/UI tests pass. Manager merged it directly; no rerun was
started. This is the reusable bell + sheet surface — runs-list registration and
persistence wiring remain separate work.
@@ -0,0 +1,93 @@
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/attention/domain/attention_models.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_bell.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_keys.dart';
import 'needs_you_test_support.dart';
/// The count badge paints outside the icon it decorates, so a bell placed flush
/// at the end of an app bar can have the badge sheared off by the viewport. The
/// integration puts the bell in `AppBar.actions`, which is where these tests put
/// it too, and measures the stadium the badge actually paints rather than just
/// finding its text.
void main() {
for (final narrow in [true, false]) {
final size = narrow ? const Size(320, 640) : const Size(390, 844);
final where = '${size.width.toInt()}x${size.height.toInt()}';
final entry = attentionFixture(
id: 8,
name: 'nightly-audit',
title: 'Nightly audit',
);
testWidgets('Material badge fits the viewport at $where and 2x', (
tester,
) async {
tester.view.devicePixelRatio = 2;
tester.view.physicalSize = size * 2;
addTearDown(tester.view.resetPhysicalSize);
addTearDown(tester.view.resetDevicePixelRatio);
await tester.pumpWidget(
attentionApp(_BellInAppBar(entries: [entry]), dark: true, textScale: 2),
);
final badge = _paintedBadge(tester);
final icon = tester.getRect(find.byIcon(Icons.notifications_outlined));
expect(
badge.right,
greaterThan(icon.right),
reason:
'the measured box is the badge label, which paints past the icon',
);
expect(
badge.right,
lessThanOrEqualTo(size.width - 8),
reason:
'the count badge needs a visible margin at the trailing edge; '
'the action must reserve the badge overhang',
);
expect(badge.left, greaterThanOrEqualTo(0));
expect(tester.takeException(), isNull);
});
}
}
/// The global rectangle of the stadium [Badge] paints for its label.
///
/// `Badge` lays the label out outside its own box, so `getRect` on the badge
/// key would only return the icon-sized box. The decorated stadium is the
/// painted label itself, positioned by the badge's render object.
Rect _paintedBadge(WidgetTester tester) {
final stadium = find.descendant(
of: find.byKey(attentionBadgeKey),
matching: find.byType(DecoratedBox),
);
expect(stadium, findsOneWidget);
return tester.getRect(stadium);
}
class _BellInAppBar extends StatelessWidget {
const _BellInAppBar({required this.entries});
final List<AttentionEntry> entries;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Runs'),
actions: [
NeedsYouBell(
entries: entries,
onOpen: (_) {},
onDismiss: (_) {},
onClearAll: (_) {},
),
],
),
body: const SizedBox.shrink(),
);
}
}
@@ -0,0 +1,126 @@
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_keys.dart';
import 'needs_you_test_support.dart';
void main() {
for (final native in [false, true]) {
final host = native ? 'Cupertino' : 'Material';
testWidgets('$host bell is plain and announced when nothing needs you', (
tester,
) async {
final semantics = tester.ensureSemantics();
await tester.pumpWidget(
attentionApp(NeedsYouPage(entries: const [], cupertino: native)),
);
expect(find.bySemanticsLabel('Notifications'), findsOneWidget);
expect(find.byKey(attentionBadgeKey), findsNothing);
expect(find.text('0'), findsNothing);
semantics.dispose();
});
testWidgets('$host bell announces the count and shows one badge', (
tester,
) async {
final semantics = tester.ensureSemantics();
final entries = [
attentionFixture(id: 1),
attentionFixture(id: 2, status: 'waiting', title: 'Approve release'),
attentionFixture(id: 3, diagnostic: 'Stage 2 failed'),
];
await tester.pumpWidget(
attentionApp(
NeedsYouPage(entries: entries, cupertino: native),
cupertino: native,
),
);
expect(
find.bySemanticsLabel('Notifications, 3 needing attention'),
findsOneWidget,
);
expect(find.byKey(attentionBadgeKey), findsOneWidget);
expect(find.text('3'), findsOneWidget);
semantics.dispose();
});
testWidgets('$host bell opens the honest empty sheet and back closes it', (
tester,
) async {
await tester.pumpWidget(
attentionApp(NeedsYouPage(entries: const [], cupertino: native)),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsOneWidget);
expect(find.text('Needs you'), findsOneWidget);
expect(find.text('Nothing needs you right now.'), findsOneWidget);
expect(find.byKey(attentionEmptyKey), findsOneWidget);
expect(find.byKey(attentionClearAllKey), findsNothing);
expect(find.text('Dismiss'), findsNothing);
await tester.binding.handlePopRoute();
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsNothing);
});
testWidgets('$host sheet is a named heading and Escape closes it', (
tester,
) async {
final semantics = tester.ensureSemantics();
await tester.pumpWidget(
attentionApp(NeedsYouPage(entries: const [], cupertino: native)),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
final title = tester.getSemantics(find.text('Needs you'));
expect(
title.getSemanticsData().flagsCollection.isHeader,
isTrue,
reason: 'the sheet title must reach assistive tech as a heading',
);
await tester.sendKeyEvent(LogicalKeyboardKey.escape);
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsNothing);
semantics.dispose();
});
testWidgets('$host sheet closes on a barrier tap', (tester) async {
await tester.pumpWidget(
attentionApp(NeedsYouPage(entries: const [], cupertino: native)),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsOneWidget);
// Above the sheet body: only the native modal barrier is there.
await tester.tapAt(const Offset(20, 20));
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsNothing);
});
testWidgets('$host closing the sheet returns focus to the bell', (
tester,
) async {
await tester.pumpWidget(
attentionApp(NeedsYouPage(entries: const [], cupertino: native)),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
await tester.binding.handlePopRoute();
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsNothing);
expect(bellHasFocus(tester), isTrue);
});
}
}
@@ -0,0 +1,70 @@
import 'package:flutter/rendering.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_keys.dart';
import 'needs_you_test_support.dart';
/// Layout evidence for the hardest case: a narrow phone at a doubled text scale.
void main() {
for (final native in [false, true]) {
final host = native ? 'Cupertino' : 'Material';
testWidgets('$host sheet wraps at 320 logical px and 2x in dark', (
tester,
) async {
tester.view.devicePixelRatio = 2;
tester.view.physicalSize = const Size(640, 1280);
addTearDown(tester.view.resetPhysicalSize);
addTearDown(tester.view.resetDevicePixelRatio);
const longTitle =
'Implementer-with-an-unshortened-stage-label that the operator sees';
const longDetail =
'Stage 3 stopped at the export archive step because the credential '
'it needs is no longer configured on this server.';
final entry = attentionFixture(
id: 1,
name: 'Release',
title: longTitle,
diagnostic: longDetail,
);
await tester.pumpWidget(
attentionApp(
NeedsYouPage(entries: [entry], cupertino: native),
cupertino: native,
dark: true,
textScale: 2,
),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
final label = find.text(longTitle);
final description = find.text('Release · $longDetail');
expect(label, findsOneWidget);
expect(description, findsOneWidget);
await tester.ensureVisible(label);
final paragraph = tester.renderObject<RenderParagraph>(label);
expect(paragraph.didExceedMaxLines, isFalse);
final unscaled = TextPainter(
text: paragraph.text,
textDirection: paragraph.textDirection,
textScaler: TextScaler.noScaling,
)..layout();
expect(
unscaled.width,
greaterThan(paragraph.size.width),
reason: 'the long label wraps instead of shrinking to one line',
);
unscaled.dispose();
final sheet = tester.getRect(find.byKey(attentionSheetKey));
expect(sheet.left, greaterThanOrEqualTo(0));
expect(sheet.right, lessThanOrEqualTo(320));
expect(sheet.top, greaterThanOrEqualTo(0));
expect(sheet.bottom, lessThanOrEqualTo(640));
expect(tester.takeException(), isNull);
});
}
}
@@ -0,0 +1,117 @@
import 'package:flutter/foundation.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/attention/domain/attention_models.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_keys.dart';
import 'needs_you_test_support.dart';
/// The open sheet is a view of the caller's list, not a copy of it: rows that
/// arrive, disappear or change text must redraw, while Clear all stays limited
/// to the snapshot the route opened with.
void main() {
for (final native in [false, true]) {
final host = native ? 'Cupertino' : 'Material';
testWidgets(
'$host same-identity content change reaches the open and reopened sheet',
(tester) async {
final before = attentionFixture(id: 1, title: 'Old title');
final changed = attentionFixture(
id: 1,
title: 'New title',
diagnostic: 'Stage 3 failed',
);
final reopened = attentionFixture(id: 1, title: 'Newest title');
expect(changed.key, before.key);
final source = ValueNotifier<List<AttentionEntry>>([before]);
addTearDown(source.dispose);
await tester.pumpWidget(
attentionApp(
AttentionHarness(
source: source,
opened: <AttentionEntry>[],
dismissed: <AttentionEntry>[],
cleared: <List<AttentionEntry>>[],
cupertino: native,
),
cupertino: native,
),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
expect(find.text('Old title'), findsOneWidget);
// Same run and kind, new title and diagnostic: the open sheet must
// redraw from the caller's list, as the browser does.
source.value = [changed];
await tester.pumpAndSettle();
expect(find.text('New title'), findsOneWidget);
expect(find.text('Old title'), findsNothing);
expect(find.text('Release · Stage 3 failed'), findsOneWidget);
expect(
attentionDismissName(tester, changed),
'Dismiss New title',
reason: 'the row action is named from the row it now shows',
);
await tester.binding.handlePopRoute();
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsNothing);
// A closed sheet must not keep the list it was last opened with either.
source.value = [reopened];
await tester.pumpAndSettle();
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
expect(find.text('Newest title'), findsOneWidget);
expect(find.text('New title'), findsNothing);
expect(attentionDismissName(tester, reopened), 'Dismiss Newest title');
},
);
testWidgets(
'$host Clear all uses the open snapshot and leaves later arrivals',
(tester) async {
final a = attentionFixture(id: 1, title: 'Ship the release');
final b = attentionFixture(id: 2, title: 'Arrived while open');
final source = ValueNotifier<List<AttentionEntry>>([a]);
addTearDown(source.dispose);
final cleared = <List<AttentionEntry>>[];
await tester.pumpWidget(
attentionApp(
AttentionHarness(
source: source,
opened: <AttentionEntry>[],
dismissed: <AttentionEntry>[],
cleared: cleared,
cupertino: native,
),
cupertino: native,
),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
source.value = [a, b];
await tester.pumpAndSettle();
expect(
find.byKey(attentionRowKey(b.key)),
findsOneWidget,
reason: 'the open sheet shows the live list, as the browser does',
);
await tester.tap(find.byKey(attentionClearAllKey));
await tester.pumpAndSettle();
expect(cleared, hasLength(1));
expect(cleared.single.map((entry) => entry.key), [a.key]);
expect(source.value.map((entry) => entry.key), [b.key]);
// Clearing keeps the sheet open; only the snapshot it opened with is gone.
expect(find.byKey(attentionSheetKey), findsOneWidget);
expect(find.byKey(attentionRowKey(b.key)), findsOneWidget);
expect(find.byKey(attentionRowKey(a.key)), findsNothing);
},
);
}
}
@@ -0,0 +1,164 @@
import 'package:flutter/foundation.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/attention/domain/attention_models.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_keys.dart';
import 'needs_you_test_support.dart';
void main() {
for (final native in [false, true]) {
final host = native ? 'Cupertino' : 'Material';
testWidgets('$host sheet names every row and every dismiss action', (
tester,
) async {
final a = attentionFixture(id: 1, title: 'Ship the release');
final b = attentionFixture(
id: 2,
name: 'Nightly audit',
status: 'waiting',
);
await tester.pumpWidget(
attentionApp(
NeedsYouPage(entries: [a, b], cupertino: native),
cupertino: native,
),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
expect(find.byKey(attentionSheetKey), findsOneWidget);
expect(find.text('Needs you'), findsOneWidget);
expect(find.byKey(attentionRowKey(a.key)), findsOneWidget);
expect(find.byKey(attentionRowKey(b.key)), findsOneWidget);
expect(find.text('Ship the release'), findsOneWidget);
expect(find.text('Release · Run failed'), findsOneWidget);
expect(find.text('Nightly audit'), findsOneWidget);
expect(
find.text('Nightly audit · Waiting for your decision'),
findsOneWidget,
);
expect(find.byKey(attentionClearAllKey), findsOneWidget);
// The browser names each destructive control after the row it removes.
expect(attentionDismissName(tester, a), 'Dismiss Ship the release');
expect(attentionDismissName(tester, b), 'Dismiss Nightly audit');
expect(find.text('Dismiss'), findsNothing);
});
testWidgets('$host repeated labels add the run id to the dismiss name', (
tester,
) async {
final first = attentionFixture(id: 11, title: 'Nightly audit');
final second = attentionFixture(id: 12, title: 'Nightly audit');
await tester.pumpWidget(
attentionApp(
NeedsYouPage(entries: [first, second], cupertino: native),
cupertino: native,
),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
expect(
attentionDismissName(tester, first),
'Dismiss Nightly audit (run 11)',
);
expect(
attentionDismissName(tester, second),
'Dismiss Nightly audit (run 12)',
);
});
testWidgets('$host row Dismiss names its identity and stays open', (
tester,
) async {
final a = attentionFixture(id: 1, title: 'Ship the release');
final b = attentionFixture(id: 2, title: 'Fix the export');
final source = ValueNotifier<List<AttentionEntry>>([a, b]);
addTearDown(source.dispose);
final opened = <AttentionEntry>[];
final dismissed = <AttentionEntry>[];
await tester.pumpWidget(
attentionApp(
AttentionHarness(
source: source,
opened: opened,
dismissed: dismissed,
cleared: <List<AttentionEntry>>[],
cupertino: native,
),
cupertino: native,
),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
await tester.tap(find.byKey(attentionDismissKey(b.key)));
await tester.pumpAndSettle();
expect(dismissed.map((entry) => entry.key), [b.key]);
expect(opened, isEmpty);
// The browser keeps the sheet open and redraws it; the caller removed the
// dismissed identity, so the remaining row is still there for a second one.
expect(find.byKey(attentionSheetKey), findsOneWidget);
expect(find.byKey(attentionRowKey(b.key)), findsNothing);
expect(find.byKey(attentionRowKey(a.key)), findsOneWidget);
});
testWidgets('$host row opens its run and only a Failed row is dismissed', (
tester,
) async {
final failed = attentionFixture(id: 1, title: 'Ship the release');
final decision = attentionFixture(
id: 2,
title: 'Approve the release',
status: 'waiting',
);
final source = ValueNotifier<List<AttentionEntry>>([failed, decision]);
addTearDown(source.dispose);
final opened = <AttentionEntry>[];
final dismissed = <AttentionEntry>[];
await tester.pumpWidget(
attentionApp(
AttentionHarness(
source: source,
opened: opened,
dismissed: dismissed,
cleared: <List<AttentionEntry>>[],
cupertino: native,
),
cupertino: native,
),
);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
await tester.tap(find.byKey(attentionRowKey(failed.key)));
await tester.pumpAndSettle();
expect(opened.map((entry) => entry.key), [failed.key]);
expect(
dismissed.map((entry) => entry.key),
[failed.key],
reason: 'opening a failed run is the operator dealing with it',
);
expect(find.byKey(attentionSheetKey), findsNothing);
await tester.tap(find.byKey(attentionBellKey));
await tester.pumpAndSettle();
await tester.tap(find.byKey(attentionRowKey(decision.key)));
await tester.pumpAndSettle();
expect(opened.map((entry) => entry.key), [failed.key, decision.key]);
expect(
dismissed.map((entry) => entry.key),
[failed.key],
reason: 'a decision stays until the operator answers it',
);
expect(find.byKey(attentionSheetKey), findsNothing);
});
}
}
@@ -0,0 +1,166 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/attention/domain/attention_models.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_bell.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_keys.dart';
/// One qualifying run summary, built through the real pure model so the tests
/// exercise the same label/detail/identity wording the app renders.
AttentionEntry attentionFixture({
int id = 1,
String name = 'Release',
String? title,
String status = 'failed',
String diagnostic = '',
String createdAt = '2026-10-21T09:00:00Z',
String finishedAt = '2026-10-21T09:10:00Z',
}) {
return attentionEntryFor({
'id': id,
'name': name,
'title': title,
'status': status,
'diagnostic': diagnostic,
'created_at': createdAt,
'finished_at': finishedAt,
})!;
}
Widget attentionApp(
Widget home, {
bool cupertino = false,
bool dark = false,
double textScale = 1,
}) {
Widget scaled(BuildContext context, Widget? app) => MediaQuery(
data: MediaQuery.of(
context,
).copyWith(textScaler: TextScaler.linear(textScale)),
child: app!,
);
if (cupertino) {
return CupertinoApp(
theme: CupertinoThemeData(
brightness: dark ? Brightness.dark : Brightness.light,
),
builder: scaled,
home: home,
);
}
return MaterialApp(
theme: ThemeData(
platform: TargetPlatform.android,
brightness: dark ? Brightness.dark : Brightness.light,
),
builder: scaled,
home: home,
);
}
/// A normal page whose whole body is the reusable bell.
class NeedsYouPage extends StatelessWidget {
const NeedsYouPage({
super.key,
required this.entries,
this.cupertino = false,
this.onOpen,
this.onDismiss,
this.onClearAll,
});
final List<AttentionEntry> entries;
final bool cupertino;
final ValueChanged<AttentionEntry>? onOpen;
final ValueChanged<AttentionEntry>? onDismiss;
final ValueChanged<List<AttentionEntry>>? onClearAll;
@override
Widget build(BuildContext context) {
final bell = NeedsYouBell(
entries: entries,
cupertino: cupertino,
onOpen: onOpen ?? (_) {},
onDismiss: onDismiss ?? (_) {},
onClearAll: onClearAll ?? (_) {},
);
final body = Center(child: bell);
return cupertino
? CupertinoPageScaffold(child: SafeArea(child: body))
: Scaffold(body: SafeArea(child: body));
}
}
/// A page that behaves like the real integration: [source] is the live list,
/// dismissing removes that one identity at once, and Clear all removes exactly
/// the snapshot the sheet reports. Callbacks are recorded for the assertions.
class AttentionHarness extends StatelessWidget {
const AttentionHarness({
super.key,
required this.source,
required this.opened,
required this.dismissed,
required this.cleared,
this.cupertino = false,
});
final ValueNotifier<List<AttentionEntry>> source;
final List<AttentionEntry> opened;
final List<AttentionEntry> dismissed;
final List<List<AttentionEntry>> cleared;
final bool cupertino;
@override
Widget build(BuildContext context) {
return ValueListenableBuilder<List<AttentionEntry>>(
valueListenable: source,
builder: (context, entries, _) => NeedsYouPage(
entries: entries,
cupertino: cupertino,
onOpen: opened.add,
onDismiss: (entry) {
dismissed.add(entry);
source.value = [
for (final item in source.value)
if (item.key != entry.key) item,
];
},
onClearAll: (snapshot) {
cleared.add(snapshot);
final keys = snapshot.map((entry) => entry.key).toSet();
source.value = [
for (final item in source.value)
if (!keys.contains(item.key)) item,
];
},
),
);
}
}
/// True when the bell action currently holds keyboard focus.
bool bellHasFocus(WidgetTester tester) {
final widget = tester.widget(find.byKey(attentionBellKey));
final node = switch (widget) {
IconButton() => widget.focusNode,
CupertinoButton() => widget.focusNode,
_ => null,
};
return node?.hasPrimaryFocus ?? false;
}
/// The accessible name of one row's Dismiss action, whichever host drew it.
///
/// Material exposes it as the button tooltip, Cupertino as the xmark icon's
/// semantic label; both must name the row they remove.
String attentionDismissName(WidgetTester tester, AttentionEntry entry) {
final key = attentionDismissKey(entry.key);
final xmark = find.descendant(
of: find.byKey(key),
matching: find.byIcon(CupertinoIcons.xmark),
);
if (xmark.evaluate().isNotEmpty) {
return tester.widget<Icon>(xmark).semanticLabel ?? '';
}
return tester.widget<IconButton>(find.byKey(key)).tooltip ?? '';
}
+139
View File
@@ -0,0 +1,139 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:pipelines_app/features/attention/domain/attention_models.dart';
import 'package:pipelines_app/features/attention/ui/needs_you_bell.dart';
/// Browser capture entrypoint for the reusable `Needs you` bell and sheet.
///
/// The fixture owns the entries and records the callbacks in plain text, so a
/// browser drive can prove the bell label, both native sheets, the empty state
/// and that a dismissal/clear names a real identity. Nothing here opens a
/// socket, reads storage or asks for notification permission.
const _longDetail =
'Stage 3 stopped at the export archive step because the credential it '
'needs is no longer configured on this server.';
List<AttentionEntry> _entries() => [
attentionEntryFor({
'id': 7,
'name': 'release',
'title': 'Approve the release candidate',
'status': 'waiting',
'created_at': '2026-10-21T09:00:00Z',
'finished_at': '',
})!,
attentionEntryFor({
'id': 8,
'name': 'nightly-audit',
'title': 'Nightly audit with a label long enough to wrap at 320 logical px',
'status': 'failed',
'diagnostic': _longDetail,
'created_at': '2026-10-21T08:00:00Z',
'finished_at': '2026-10-21T08:30:00Z',
})!,
];
void main() {
final params = Uri.base.queryParameters;
final cupertino = params['host'] == 'cupertino';
final scale = double.tryParse(params['scale'] ?? '') ?? 1;
final empty = params['mode'] == 'empty';
final brightness = params['theme'] == 'light'
? Brightness.light
: Brightness.dark;
Widget scaled(BuildContext context, Widget? app) => MediaQuery(
data: MediaQuery.of(context).copyWith(textScaler: TextScaler.linear(scale)),
child: app!,
);
final home = _ProbeHome(
cupertino: cupertino,
entries: empty ? const [] : _entries(),
);
if (cupertino) {
runApp(
CupertinoApp(
theme: CupertinoThemeData(brightness: brightness),
builder: scaled,
home: home,
),
);
return;
}
runApp(
MaterialApp(
theme: ThemeData(
platform: TargetPlatform.android,
brightness: brightness,
),
builder: scaled,
home: home,
),
);
}
class _ProbeHome extends StatefulWidget {
const _ProbeHome({required this.cupertino, required this.entries});
final bool cupertino;
final List<AttentionEntry> entries;
@override
State<_ProbeHome> createState() => _ProbeHomeState();
}
class _ProbeHomeState extends State<_ProbeHome> {
late List<AttentionEntry> _entries = [...widget.entries];
String _event = 'Nothing raised yet';
void _open(AttentionEntry entry) {
setState(() => _event = 'Opened ${entry.key}');
}
void _dismiss(AttentionEntry entry) {
setState(() {
_entries = _entries.where((item) => item.key != entry.key).toList();
_event = 'Dismissed ${entry.key}';
});
}
void _clearAll(List<AttentionEntry> snapshot) {
final keys = snapshot.map((entry) => entry.key).toSet();
setState(() {
_entries = _entries.where((entry) => !keys.contains(entry.key)).toList();
_event = 'Cleared ${keys.length} of the open snapshot';
});
}
@override
Widget build(BuildContext context) {
final bell = NeedsYouBell(
entries: _entries,
cupertino: widget.cupertino,
onOpen: _open,
onDismiss: _dismiss,
onClearAll: _clearAll,
);
final body = ListView(
padding: const EdgeInsets.all(16),
children: [
Text(_event),
const SizedBox(height: 12),
Text('${_entries.length} needing attention now'),
],
);
if (widget.cupertino) {
return CupertinoPageScaffold(
navigationBar: CupertinoNavigationBar(
middle: const Text('Runs'),
trailing: bell,
),
child: SafeArea(child: body),
);
}
return Scaffold(
appBar: AppBar(title: const Text('Runs'), actions: [bell]),
body: SafeArea(child: body),
);
}
}
+288
View File
@@ -0,0 +1,288 @@
// Real-browser acceptance for the reusable Needs you bell and native sheets.
//
// flutter build web -t tool/attention_probe.dart -o build/attention_probe_web
// OPENCODE_ARTIFACT_DIR=<dir> node tool/attention_probe.mjs
//
// The fixture is in-process; it never opens a socket or asks for notification
// permission. The drive checks the accessible bell label, both native hosts at
// 320 logical px / 2x text in dark, the row wording and per-row dismiss names, a
// dismissal that redraws the open sheet, Clear all leaving an honest empty sheet,
// opening a Decision and a Failed row, Escape back to the page, the honest empty
// state, and light at the default text scale. The Material count badge is also
// captured at 390 logical px / 2x, where it must keep its trailing margin. One
// capture is written per state it inspects.
import { createServer } from 'node:http';
import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { existsSync } from 'node:fs';
import { setTimeout as delay } from 'node:timers/promises';
import { join, extname, resolve, sep } from 'node:path';
import { tmpdir } from 'node:os';
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
const root = resolve(process.env.PROBE_WEB_ROOT ?? 'build/attention_probe_web');
const artifactDir = process.env.OPENCODE_ARTIFACT_DIR;
if (!artifactDir) throw new Error('Set OPENCODE_ARTIFACT_DIR for the probe captures');
await mkdir(artifactDir, { recursive: true });
const defaultChrome = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
const chromePath = process.env.CHROME_PATH ?? defaultChrome;
if (!existsSync(chromePath)) throw new Error(`Chrome not found at ${chromePath}; set CHROME_PATH`);
const mime = { '.html': 'text/html', '.js': 'text/javascript', '.json': 'application/json', '.wasm': 'application/wasm', '.png': 'image/png', '.ico': 'image/x-icon' };
const server = createServer(async (req, res) => {
try {
const path = resolve(root, '.' + decodeURIComponent(new URL(req.url, 'http://localhost').pathname));
if (path !== root && !path.startsWith(root + sep)) return res.writeHead(403).end();
const filePath = path === root || path.endsWith('/') ? join(path, 'index.html') : path;
const file = await readFile(filePath);
res.writeHead(200, { 'content-type': mime[extname(filePath)] ?? 'application/octet-stream' }).end(file);
} catch { res.writeHead(404).end('not found'); }
});
server.listen(0, '127.0.0.1');
await once(server, 'listening');
const port = server.address().port;
const profile = await mkdtemp(join(tmpdir(), 'attention-chrome-'));
const chrome = spawn(chromePath, [
'--headless=new', '--no-first-run', '--no-default-browser-check', '--disable-gpu',
'--remote-debugging-port=0', `--user-data-dir=${profile}`, 'about:blank',
], { stdio: ['ignore', 'ignore', 'pipe'] });
let stderr = '';
chrome.stderr.on('data', (data) => { stderr += data; });
const waitFor = async (check) => {
for (let i = 0; i < 120; i++) { const value = await check(); if (value) return value; await delay(100); }
throw new Error(`Timed out waiting for Chrome DevTools\n${stderr.slice(-1200)}`);
};
let ws;
try {
const endpoint = await waitFor(() => stderr.match(/DevTools listening on (ws:\/\/[^\s]+)/)?.[1]);
ws = new WebSocket(endpoint);
await once(ws, 'open');
let id = 0;
const pending = new Map();
ws.addEventListener('message', (event) => {
const message = JSON.parse(event.data);
if (message.id && pending.has(message.id)) { pending.get(message.id)(message); pending.delete(message.id); }
});
const send = (method, params = {}, sessionId) => new Promise((resolveCall) => {
const callId = ++id; pending.set(callId, resolveCall);
ws.send(JSON.stringify({ id: callId, method, params, ...(sessionId ? { sessionId } : {}) }));
});
const target = (await send('Target.createTarget', { url: 'about:blank' })).result.targetId;
const session = (await send('Target.attachToTarget', { targetId: target, flatten: true })).result.sessionId;
await send('Page.enable', {}, session);
await send('Runtime.enable', {}, session);
const evaluate = async (expression) => {
const response = await send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, session);
if (response.error) throw new Error(`Runtime.evaluate failed: ${JSON.stringify(response)}`);
return response.result?.result?.value;
};
const semantics = () => evaluate("[...document.querySelectorAll('flt-semantics')].map(x=>{const r=x.getBoundingClientRect();return{label:(x.getAttribute('aria-label')||x.innerText||'').trim(), role:x.getAttribute('role'), x:r.x, y:r.y, w:r.width, h:r.height}})");
const labels = async () => (await semantics()).map((item) => item.label).filter(Boolean);
const requireLabels = (all, needles, state) => {
for (const needle of needles) {
if (!all.some((label) => label.includes(needle))) {
throw new Error(`Missing ${JSON.stringify(needle)} in ${state}: ${JSON.stringify(all)}`);
}
}
};
const clickLabel = async (needle, exact = false, minY = 0) => {
const point = await evaluate(`(() => { const all=[...document.querySelectorAll('flt-semantics')].filter(x => x.getBoundingClientRect().top >= ${minY}); const match=x => { const l=(x.getAttribute('aria-label')||x.innerText||'').trim(); return ${exact ? 'l === ' : 'l.includes('}${JSON.stringify(needle)}${exact ? '' : ')'}; }; const e=all.find(x => x.getAttribute('role') === 'button' && match(x)) || all.find(match); if (!e) return null; const r=e.getBoundingClientRect(); return {x:r.x+r.width/2,y:r.y+r.height/2,w:r.width,h:r.height}; })()`);
if (!point) return false;
await send('Input.dispatchMouseEvent', { type: 'mousePressed', x: point.x, y: point.y, button: 'left', clickCount: 1 }, session);
await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: point.x, y: point.y, button: 'left', clickCount: 1 }, session);
return true;
};
// Row-open and Clear-all controls can sit below the fold at 2x text. Find the
// node, wheel the sheet until its centre is on screen, then click it. Row
// labels are matched without their `Dismiss ...` sibling, whose label also
// contains the row text.
const clickScrolled = async (needle, { exact = false, minY = 0 } = {}) => {
for (let attempt = 0; attempt < 12; attempt++) {
const point = await evaluate(`(() => { const all=[...document.querySelectorAll('flt-semantics')].filter(x => x.getBoundingClientRect().top >= ${minY}); const match=x => { const l=(x.getAttribute('aria-label')||x.innerText||'').trim(); if (l.startsWith('Dismiss ')) return false; return ${exact ? 'l === ' : 'l.includes('}${JSON.stringify(needle)}${exact ? '' : ')'}; }; const e=all.find(x => x.getAttribute('role') === 'button' && match(x)) || all.find(match); if (!e) return null; const r=e.getBoundingClientRect(); return {x:r.x+r.width/2,y:r.y+r.height/2,w:r.width,h:r.height}; })()`);
if (point && point.y > 4 && point.y < viewport.height - 4) {
await send('Input.dispatchMouseEvent', { type: 'mousePressed', x: point.x, y: point.y, button: 'left', clickCount: 1 }, session);
await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: point.x, y: point.y, button: 'left', clickCount: 1 }, session);
return true;
}
const deltaY = point && point.y < 0 ? -240 : 240;
await send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: viewport.width / 2, y: viewport.height - 80, deltaX: 0, deltaY }, session);
await delay(500);
}
return false;
};
const pressEscape = async () => {
const key = { key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27, nativeVirtualKeyCode: 27 };
await send('Input.dispatchKeyEvent', { type: 'keyDown', ...key }, session);
await send('Input.dispatchKeyEvent', { type: 'keyUp', ...key }, session);
};
let viewport = { width: 320, height: 640 };
const navigate = async (host, { mode = '', theme = 'dark', scale = 2, width = 320, height = 640 } = {}) => {
viewport = { width, height };
await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: theme }] }, session);
const query = new URLSearchParams({ host, theme, scale: String(scale) });
if (mode) query.set('mode', mode);
await send('Page.navigate', { url: `http://127.0.0.1:${port}/?${query}` }, session);
await delay(3000);
await send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 2, mobile: true }, session);
await delay(1200);
await evaluate("document.querySelector('flt-semantics-placeholder')?.click()");
await delay(1200);
};
const capture = async (name) => {
const data = (await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false }, session)).result.data;
await writeFile(join(artifactDir, name), Buffer.from(data, 'base64'));
};
const captures = [];
const record = async (name) => {
await capture(name);
captures.push(name);
};
for (const host of ['material', 'cupertino']) {
// The hardest case: narrow, scaled text in dark.
await navigate(host);
requireLabels(await labels(), ['Notifications, 2 needing attention'], `${host} bell`);
await record(`attention-${host}-dark-320-2x-bell.png`);
if (!(await clickLabel('Notifications, 2 needing attention', true))) throw new Error(`${host}: bell not clickable`);
await delay(1000);
const sheet = await semantics();
requireLabels(sheet.map((item) => item.label), [
'Needs you', 'Clear all', 'Approve the release candidate',
'release · Waiting for your decision',
'Nightly audit with a label long enough to wrap at 320 logical px',
'nightly-audit · Stage 3 stopped',
], `${host} sheet`);
// Each row's destructive control is named after its row, never bare
// `Dismiss`. The Material drag handle legitimately carries the native
// `Dismiss` (modalBarrierDismissLabel), so only row buttons are collected.
const dismissLabels = sheet
.filter((item) => item.role === 'button' && item.label.startsWith('Dismiss '))
.map((item) => item.label);
requireLabels(dismissLabels, [
'Dismiss Approve the release candidate',
'Dismiss Nightly audit with a label long enough to wrap at 320 logical px',
], `${host} dismiss names`);
if (new Set(dismissLabels).size !== 2) {
throw new Error(`${host}: expected two distinct named row dismiss actions: ${JSON.stringify(dismissLabels)}`);
}
await record(`attention-${host}-dark-320-2x-sheet.png`);
// Dismissing redraws the open sheet: the row is gone, the sheet is still there.
if (!(await clickLabel('Dismiss Approve the release candidate', true, 100))) throw new Error(`${host}: dismiss not clickable`);
await delay(1000);
const afterDismiss = await labels();
if (afterDismiss.some((label) => label.includes('Approve the release candidate'))) {
throw new Error(`${host}: dismissed row is still shown in the open sheet`);
}
requireLabels(afterDismiss, [
'Needs you',
'Dismiss Nightly audit with a label long enough to wrap at 320 logical px',
], `${host} after dismiss`);
await record(`attention-${host}-dark-320-2x-after-dismiss.png`);
// Escape closes the sheet natively and the page reflects the one dismissal.
await pressEscape();
await delay(900);
requireLabels(await labels(), [
'Dismissed 7:Decision',
'1 needing attention now',
'Notifications, 1 needing attention',
], `${host} closed sheet`);
// Light and the default text scale on a normal phone width.
await navigate(host, { theme: 'light', scale: 1, width: 390, height: 844 });
requireLabels(await labels(), ['Notifications, 2 needing attention'], `${host} light bell`);
await record(`attention-${host}-light-390-1x-bell.png`);
if (!(await clickLabel('Notifications, 2 needing attention', true))) throw new Error(`${host}: light bell not clickable`);
await delay(900);
requireLabels(await labels(), [
'Needs you', 'Clear all', 'Dismiss Approve the release candidate',
'Dismiss Nightly audit with a label long enough to wrap at 320 logical px',
], `${host} light sheet`);
await record(`attention-${host}-light-390-1x-sheet.png`);
await navigate(host, { mode: 'empty' });
const emptyBell = await labels();
requireLabels(emptyBell, ['Notifications'], `${host} empty bell`);
if (emptyBell.some((label) => label.startsWith('Notifications,'))) throw new Error(`${host}: empty bell announced a count`);
if (!(await clickLabel('Notifications', true))) throw new Error(`${host}: empty bell not clickable`);
await delay(900);
const emptySheet = await semantics();
const emptyLabels = emptySheet.map((item) => item.label);
requireLabels(emptyLabels, ['Needs you', 'Nothing needs you right now.'], `${host} empty sheet`);
if (emptyLabels.some((label) => label.includes('Clear all'))) throw new Error(`${host}: empty sheet offered Clear all`);
if (emptySheet.some((item) => item.role === 'button' && item.label.startsWith('Dismiss '))) throw new Error(`${host}: empty sheet offered Dismiss`);
await record(`attention-${host}-dark-320-2x-empty.png`);
// Clear all leaves the sheet open and honest: the empty copy, no Clear all
// and no row dismiss. Closing then shows a plain bell and no remaining work.
await navigate(host);
if (!(await clickLabel('Notifications, 2 needing attention', true))) throw new Error(`${host}: bell not clickable for Clear all`);
await delay(1000);
if (!(await clickScrolled('Clear all', { exact: true }))) throw new Error(`${host}: Clear all not clickable`);
await delay(1000);
const clearedSheet = await semantics();
const clearedLabels = clearedSheet.map((item) => item.label);
requireLabels(clearedLabels, ['Needs you', 'Nothing needs you right now.'], `${host} cleared sheet`);
if (clearedLabels.some((label) => label.includes('Clear all'))) throw new Error(`${host}: cleared sheet still offered Clear all`);
if (clearedSheet.some((item) => item.role === 'button' && item.label.startsWith('Dismiss '))) throw new Error(`${host}: cleared sheet offered Dismiss`);
await record(`attention-${host}-dark-320-2x-cleared.png`);
await pressEscape();
await delay(900);
const clearedPage = await labels();
requireLabels(clearedPage, ['Cleared 2 of the open snapshot', '0 needing attention now', 'Notifications'], `${host} cleared page`);
if (clearedPage.some((label) => label.startsWith('Notifications,'))) throw new Error(`${host}: cleared page announced a count`);
// Opening a Decision row closes the sheet and leaves the identity in place:
// only answering the decision clears it.
await navigate(host);
if (!(await clickLabel('Notifications, 2 needing attention', true))) throw new Error(`${host}: bell not clickable for Decision row`);
await delay(1000);
if (!(await clickScrolled('Approve the release candidate'))) throw new Error(`${host}: Decision row not clickable`);
await delay(1000);
const decisionPage = await labels();
requireLabels(decisionPage, [
'Opened 7:Decision', '2 needing attention now',
'Notifications, 2 needing attention',
], `${host} Decision row open`);
if (decisionPage.some((label) => label.includes('Clear all'))) throw new Error(`${host}: Decision row left the sheet open`);
await record(`attention-${host}-dark-320-2x-row-open-decision.png`);
// Opening a Failed row dismisses its identity before opening it, so the
// bell no longer asks for a run the operator has already looked at.
await navigate(host);
if (!(await clickLabel('Notifications, 2 needing attention', true))) throw new Error(`${host}: bell not clickable for Failed row`);
await delay(1000);
if (!(await clickScrolled('Nightly audit with a label long enough'))) throw new Error(`${host}: Failed row not clickable`);
await delay(1000);
const failedPage = await labels();
requireLabels(failedPage, [
'Opened 8:Failed', '1 needing attention now',
'Notifications, 1 needing attention',
], `${host} Failed row open`);
await record(`attention-${host}-dark-320-2x-row-open-failed.png`);
}
// The Material count badge keeps its trailing margin at a normal phone width
// and doubled text, not only at the narrow 320 px fixture.
await navigate('material', { width: 390, height: 844 });
requireLabels(await labels(), ['Notifications, 2 needing attention'], 'material 390 bell');
await record('attention-material-dark-390-2x-bell.png');
if (!(await clickLabel('Notifications, 2 needing attention', true))) throw new Error('material 390: bell not clickable');
await delay(1000);
if (!(await clickLabel('Dismiss Approve the release candidate', true, 100))) throw new Error('material 390: dismiss not clickable');
await delay(1000);
requireLabels(await labels(), [
'Needs you',
'Dismiss Nightly audit with a label long enough to wrap at 320 logical px',
], 'material 390 after dismiss');
await record('attention-material-dark-390-2x-after-dismiss.png');
console.log(JSON.stringify({ captures }, null, 2));
} finally {
ws?.close();
chrome.kill('SIGTERM');
await Promise.race([once(chrome, 'exit'), delay(3000)]);
server.close();
await rm(profile, { recursive: true, force: true });
}